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

3 files changed, 227 insertions, 0 deletions

diff --git a/makima/src/daemon/api/contract.rs b/makima/src/daemon/api/contract.rs
index 7c76b40..b6da837 100644
--- a/makima/src/daemon/api/contract.rs
+++ b/makima/src/daemon/api/contract.rs
@@ -274,6 +274,7 @@ impl ApiClient {
     }
 }
 
+/// Request to add a remote repository.
 #[derive(Serialize)]
 #[serde(rename_all = "camelCase")]
 struct AddRemoteRepositoryRequest {
@@ -281,3 +282,91 @@ struct AddRemoteRepositoryRequest {
     repository_url: String,
     is_primary: bool,
 }
+
+// =============================================================================
+// Contract Management Helper API Methods
+// =============================================================================
+
+/// Request to pause a contract.
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PauseContractRequest {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub reason: Option<String>,
+}
+
+/// Request to change contract phase.
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ChangePhaseRequest {
+    pub phase: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub confirmed: Option<bool>,
+}
+
+/// Request to update contract status.
+#[derive(Serialize, Default)]
+#[serde(rename_all = "camelCase")]
+pub struct UpdateContractStatusRequest {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub status: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub pause_reason: Option<String>,
+}
+
+impl ApiClient {
+    /// Pause a contract by setting its status to paused.
+    pub async fn pause_contract(
+        &self,
+        contract_id: Uuid,
+        reason: Option<String>,
+    ) -> Result<JsonValue, ApiError> {
+        let req = UpdateContractStatusRequest {
+            status: Some("paused".to_string()),
+            pause_reason: reason,
+        };
+        self.put(&format!("/api/v1/contracts/{}", contract_id), &req)
+            .await
+    }
+
+    /// Resume a paused contract by setting its status back to active.
+    pub async fn resume_contract(&self, contract_id: Uuid) -> Result<JsonValue, ApiError> {
+        let req = UpdateContractStatusRequest {
+            status: Some("active".to_string()),
+            pause_reason: None,
+        };
+        self.put(&format!("/api/v1/contracts/{}", contract_id), &req)
+            .await
+    }
+
+    /// Advance a contract to a specific phase.
+    pub async fn advance_contract_phase(
+        &self,
+        contract_id: Uuid,
+        phase: &str,
+        force: bool,
+    ) -> Result<JsonValue, ApiError> {
+        let req = ChangePhaseRequest {
+            phase: phase.to_string(),
+            confirmed: Some(force),
+        };
+        self.post(&format!("/api/v1/contracts/{}/phase", contract_id), &req)
+            .await
+    }
+
+    /// Request a supervisor restart for a contract.
+    /// This will stop the current supervisor (if running) and queue a new one.
+    pub async fn restart_supervisor(&self, contract_id: Uuid) -> Result<JsonValue, ApiError> {
+        self.post_empty(&format!(
+            "/api/v1/contracts/{}/supervisor/restart",
+            contract_id
+        ))
+        .await
+    }
+
+    /// Get detailed contract information including health status.
+    pub async fn get_contract_health(&self, contract_id: Uuid) -> Result<JsonValue, ApiError> {
+        self.get(&format!("/api/v1/contracts/{}/health", contract_id))
+            .await
+    }
+}
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 {