[WIP] Heartbeat checkpoint - 2026-02-01 02:00:32 UTCmakima/task-task-5f420783-5f420783

2 files changed, 138 insertions, 0 deletions

diff --git a/makima/src/daemon/cli/contract.rs b/makima/src/daemon/cli/contract.rs
index a443b85..b5bd7cc 100644
--- a/makima/src/daemon/cli/contract.rs
+++ b/makima/src/daemon/cli/contract.rs
@@ -1,4 +1,8 @@
 //! Contract subcommand - task-contract interaction commands.
+//!
+//! This module contains two types of commands:
+//! 1. Task-contract interaction commands (used by agents via `makima contract`)
+//! 2. Contract management helper commands (used by users via `makima contracts`)
 
 use clap::Args;
 use uuid::Uuid;
@@ -85,3 +89,95 @@ pub struct CreateFileArgs {
     /// Name of the new file
     pub name: String,
 }
+
+// =============================================================================
+// Contract Management Helper Commands (makima contracts)
+// =============================================================================
+
+/// Common arguments for contracts management commands.
+#[derive(Args, Debug, Clone)]
+pub struct ContractsCommonArgs {
+    /// API URL
+    #[arg(long, env = "MAKIMA_API_URL", default_value = "https://api.makima.jp")]
+    pub api_url: String,
+
+    /// API key for authentication
+    #[arg(long, env = "MAKIMA_API_KEY")]
+    pub api_key: String,
+}
+
+/// Arguments for pause command.
+#[derive(Args, Debug)]
+pub struct PauseArgs {
+    #[command(flatten)]
+    pub common: ContractsCommonArgs,
+
+    /// Contract ID to pause
+    pub contract_id: Uuid,
+
+    /// Reason for pausing the contract
+    #[arg(long)]
+    pub reason: Option<String>,
+}
+
+/// Arguments for resume command.
+#[derive(Args, Debug)]
+pub struct ResumeArgs {
+    #[command(flatten)]
+    pub common: ContractsCommonArgs,
+
+    /// Contract ID to resume
+    pub contract_id: Uuid,
+}
+
+/// Arguments for advance command.
+#[derive(Args, Debug)]
+pub struct AdvanceArgs {
+    #[command(flatten)]
+    pub common: ContractsCommonArgs,
+
+    /// Contract ID to advance
+    pub contract_id: Uuid,
+
+    /// Target phase to advance to
+    #[arg(long)]
+    pub phase: String,
+
+    /// Force the phase transition even if deliverables are incomplete
+    #[arg(long)]
+    pub force: bool,
+}
+
+/// Arguments for restart-supervisor command.
+#[derive(Args, Debug)]
+pub struct RestartSupervisorArgs {
+    #[command(flatten)]
+    pub common: ContractsCommonArgs,
+
+    /// Contract ID to restart supervisor for
+    pub contract_id: Uuid,
+}
+
+/// Arguments for show command.
+#[derive(Args, Debug)]
+pub struct ShowArgs {
+    #[command(flatten)]
+    pub common: ContractsCommonArgs,
+
+    /// Contract ID to show
+    pub contract_id: Uuid,
+
+    /// Show verbose output with all details
+    #[arg(long, short = 'v')]
+    pub verbose: bool,
+}
+
+/// Arguments for health command.
+#[derive(Args, Debug)]
+pub struct HealthArgs {
+    #[command(flatten)]
+    pub common: ContractsCommonArgs,
+
+    /// Contract ID to check health for
+    pub contract_id: Uuid,
+}
diff --git a/makima/src/daemon/cli/mod.rs b/makima/src/daemon/cli/mod.rs
index c848e8e..07f0b7c 100644
--- a/makima/src/daemon/cli/mod.rs
+++ b/makima/src/daemon/cli/mod.rs
@@ -13,6 +13,7 @@ use uuid::Uuid;
 
 pub use config::CliConfig;
 pub use contract::ContractArgs;
+pub use contract::{PauseArgs, ResumeArgs, AdvanceArgs, RestartSupervisorArgs, ShowArgs, HealthArgs};
 pub use daemon::DaemonArgs;
 pub use red_team::handle_notify;
 pub use server::ServerArgs;
@@ -65,6 +66,12 @@ pub enum Commands {
     /// Red team commands for adversarial monitoring
     #[command(name = "red-team", subcommand)]
     RedTeam(RedTeamCommand),
+
+    /// Contract management helper commands
+    ///
+    /// User-facing commands for managing contracts (pause, resume, show, etc.)
+    #[command(subcommand)]
+    Contracts(ContractsCommand),
 }
 
 /// Config subcommands for CLI configuration.
@@ -211,6 +218,41 @@ pub enum RedTeamCommand {
     Notify(RedTeamNotifyArgs),
 }
 
+/// Contract management helper subcommands.
+#[derive(Subcommand, Debug)]
+pub enum ContractsCommand {
+    /// Pause a contract
+    ///
+    /// Sets the contract status to paused, optionally with a reason.
+    /// The supervisor will be stopped and tasks will not be picked up.
+    Pause(contract::PauseArgs),
+
+    /// Resume a paused contract
+    ///
+    /// Sets the contract status back to active and restarts the supervisor.
+    Resume(contract::ResumeArgs),
+
+    /// Manually advance a contract to a specific phase
+    ///
+    /// Use --force to skip deliverable validation.
+    Advance(contract::AdvanceArgs),
+
+    /// Restart the supervisor for a contract
+    ///
+    /// Useful when the supervisor is stuck or needs to be refreshed.
+    RestartSupervisor(contract::RestartSupervisorArgs),
+
+    /// Show detailed contract information
+    ///
+    /// Use --verbose for all details including tasks and files.
+    Show(contract::ShowArgs),
+
+    /// Check contract and supervisor health
+    ///
+    /// Returns health status including supervisor state, task counts, and staleness.
+    Health(contract::HealthArgs),
+}
+
 /// Arguments for red-team notify command.
 #[derive(Args, Debug)]
 pub struct RedTeamNotifyArgs {