Dispatch a task or code review contract to another local AI agent host via the shared SQLite WAL mesh.

Purpose

Registers a new contract in SUBMITTED status with full-file SHA-256 fingerprint snapshots of all target files, establishing an immutable baseline for cross-host verification.

Usage Guidelines

• When to use: Use when requesting code reviews, architecture audits, implementation, or test generation from a target agent (e.g., target_agent="workbuddy" or "antigravity").

• When NOT to use:

  • Do NOT use to claim or execute tasks (use poll_next_task).

  • Do NOT use to check task status or inspect outputs (use inspect_mesh_state).

  • Do NOT use if the target host does not share the same local filesystem access to workspace_root.

• Prerequisites: workspace_root must be a valid directory accessible by both hosts. Pointer files must exist on disk and be saved. Sensitive files (.env, keys, credentials, .git/config) and path escapes are strictly blocked.

Behavior & Side Effects

• Mutates database: Synchronously inserts a single row into contracts with status='SUBMITTED' in SQLite WAL (~/.ferrycat/mesh.db).

• SHA-256 Snapshot: Computes 64-char hex SHA-256, byte size, and first/last lines for each pointer. Emits a warning if any file was modified within the last 3 seconds (indicating unsaved IDE buffers).

• Lifecycle & Expiry: Starts the queue_ttl_sec countdown (default: 1800s / 30m). If the target agent never claims it before queue_ttl_sec elapses, the contract lazily transitions to TIMED_OUT.

• Once claimed, execution is governed by exec_ttl_sec (tiered default: 1800s for review/audit, 300s for implementation/test).

Return Value

Returns { contract_id: string, status: 'SUBMITTED', created_at: number, files: Array<{ path, size, mtime_ms, sha256, first_line, last_line, line_range? }>, warning?: string }. Note: requester_agent / target_agent / task_type / title / TTLs are NOT echoed back — read them via inspect_mesh_state if needed.

Atomically claim the oldest pending SUBMITTED contract assigned to this agent and verify local file fingerprints.

Purpose

Retrieves and claims next available contract work for the current agent, transitioning it from SUBMITTED to CLAIMED.

Usage Guidelines

• When to use: Call periodically or when notified to discover and atomically take ownership of pending tasks assigned to your agent_id.

• When NOT to use:

  • Do NOT use to non-destructively inspect queue depth or monitor status without claiming (use inspect_mesh_state).

  • Do NOT use to create contracts (use dispatch_contract).

• IMPORTANT (ADR-0004): Pointers are an immutable baseline snapshot ("what I read"). Never edit pointer files directly on disk while holding a review contract; deliver any proposed code fixes via structured_output.fixes in fulfill_contract.

Behavior & Side Effects

• Mutates database: Atomically claims the oldest SUBMITTED contract for agent_id using optimistic concurrency (UPDATE ... WHERE status='SUBMITTED', checked by changes===1). Starts the exec_ttl_sec window.

• Lazy TTL sweep: Automatically sweeps and marks expired contracts as TIMED_OUT using lock-free read-before-write probing.

• Fingerprint verification: Verifies Existence -> Byte Size -> SHA-256 for all pointers. If on-disk files were altered or missing, marks the contract POINTER_STALE and transparently advances to claim the next valid candidate in the queue.

Return Value

• When work is claimed: { ok: true, has_task: true, status: 'CLAIMED', contract: { contract_id, requester_agent, target_agent, task_type, title, context_summary, workspace_root, pointers, contract_schema, claimed_at, exec_ttl_sec } }.

• When queue is empty: { ok: true, has_task: false, message: 'No pending contracts for agent "<agent_id>"' }.

Submit execution or review deliverables for a CLAIMED contract, with TOCTOU soft-failure buffering and Ajv JSON Schema validation.

Purpose

Delivers the final output of a task, verifies that the code baseline was not mutated during execution, validates structured payloads, and transitions the contract to terminal COMPLETED.

Usage Guidelines

• When to use: Use after completing task work to deliver result_summary, optional structured_output, and optional artifacts_pointers.

• When NOT to use:

  • Do NOT use if you cannot complete the task (use release_contract to re-queue, or fail_contract to record failure).

  • Do NOT use if you modified pointer files directly on disk. If modified accidentally, run "git stash" or restore the files, run verify_contract, and pass proposed fixes inside structured_output.fixes.

Behavior & Side Effects

• Authorization: Caller agent_id must match target_agent of the claimed contract.

• TOCTOU Guard & Soft-Failure Buffer (ADR-0004) — exactly ONE recoverable rejection:

  • 1st blocked fulfill: returns status='RETRY_NEEDED', keeps the contract CLAIMED, renews the execution window (claimed_at=now), and lists dirty_files with restore instructions.

  • 2nd blocked fulfill: transitions to terminal status='POINTER_STALE', preserving your summary and payload in salvaged_result_json so the work is not lost.

  • Only ONE rejection is recoverable: restore/stash the files BEFORE retrying, and call verify_contract first so a stray second attempt cannot burn the buffer.

• Schema Validation: If contract_schema was defined, validates structured_output via cached Ajv validator. Failures 1 & 2 return RETRY_NEEDED with flattened error paths and renew the execution window; 3rd failure transitions to terminal VALIDATION_FAILED.

• On Success: Transitions to terminal status='COMPLETED', recording result_summary, structured_output, artifacts_pointers, and verified SHA-256 snapshot.

Return Value

Returns { ok: boolean, contract_id: string, status: 'COMPLETED' | 'RETRY_NEEDED' | 'POINTER_STALE' | 'VALIDATION_FAILED', retry_count: number, max_retries: number, toctou_strike?: number, max_toctou_strikes?: number, dirty_files?: Array<{ path, reason, detail }>, validation_errors?: string[], message: string }.

Strictly read-only query of contracts, execution progress, outputs, diagnostic counters, and failure causes.

Purpose

Provides comprehensive observability into the multi-agent mesh state without acquiring database locks or mutating rows.

Usage Guidelines

• When to use:

  • Check whether a contract you dispatched has been claimed or completed.

  • Inspect result summaries, structured outputs, or salvaged results of completed/stale contracts.

  • Monitor queue depth or pending contracts for a specific agent via target_agent filter.

• When NOT to use:

  • Do NOT use to claim tasks (use poll_next_task).

  • Do NOT use to dispatch tasks (use dispatch_contract).

  • Do NOT use to verify on-disk file pointer hygiene (use verify_contract).

Behavior & Side Effects

• Zero side effects: Pure read-only SELECT query against SQLite WAL. Never alters rows or triggers sweeps.

• Dynamically calculates is_logically_expired: true when a contract has exceeded its queue or execution TTL based on the current timestamp, even before the next lazy sweep runs.

Return Value

Returns { total_returned: number, contracts: Array<{ contract_id, requester_agent, target_agent, task_type, title, status, is_logically_expired, created_at, claimed_at, completed_at, retry_count, extend_count, release_count, toctou_strike, result_summary, structured_output, artifacts_pointers, error_reason, salvaged_result, verified_sha256 }> }.

Hand a CLAIMED contract back to the queue tail as SUBMITTED with a fresh queue window.

Purpose

Allows an agent holding a claimed task to safely release ownership back to the queue without failing or aborting the task.

Usage Guidelines

• When to use: Use when your agent claimed a task by mistake, encounters missing local dependencies/tools, or needs to switch git branches before processing.

• When NOT to use:

  • Do NOT use if the task permanently failed or cannot ever be completed (use fail_contract).

  • Do NOT use if you simply need more time to finish active execution (use extend_ttl).

• Prerequisites: Caller must be the current holder (agent_id matches target_agent) and contract status must be CLAIMED.

Behavior & Side Effects

• Mutates database: Resets claimed_at=NULL, updates queued_at=nowMs, resets extend_count=0 (renewal quota is per holder), and increments release_count.

• Preserves retry_count: The schema validation circuit-breaker quota is contract-level; releasing a contract cannot launder previously consumed retry attempts.

• Audit history: Appends reason to error_reason history ("RELEASED_BY_HOLDER: | prev: ...").

• Limits: Maximum 3 releases per contract. Refused once the contract reaches its absolute lifetime ceiling (nowMs >= created_at + 4 * queue_ttl_sec).

Return Value

Returns { ok: boolean, contract_id: string, status: 'SUBMITTED' | 'CLAIMED' | 'TIMED_OUT', release_count: number, max_releases: number, message: string }.

Heartbeat renewal for long-running execution: restarts the active execution window of a CLAIMED contract.

Purpose

Prevents execution timeout during deep reasoning, extensive test execution, or complex multi-step refactoring by resetting the execution clock.

Usage Guidelines

• When to use: Call periodically during long-running tasks before the active exec_ttl_sec countdown expires.

• When NOT to use:

  • Do NOT use after the window has already expired (expired contracts transition to TIMED_OUT).

  • Do NOT use to deliver task completion (use fulfill_contract).

  • Do NOT use if abandoning the task (use release_contract or fail_contract).

• Prerequisites: Caller must be the current holder and contract must be currently CLAIMED.

Behavior & Side Effects

• Mutates database: Resets claimed_at=nowMs (restarting the full exec_ttl_sec window from the current moment) and increments extend_count.

• Quotas & Boundaries: Maximum 5 renewals per holder. Bounded by the contract's absolute lifetime ceiling (created_at + 4 * queue_ttl_sec); rejected if proposedExpiresAt > lifetimeDeadline.

Return Value

Returns { ok: boolean, contract_id: string, status: 'CLAIMED' | 'TIMED_OUT', claimed_at?: number, expires_at?: number, extend_count: number, max_extends: number, message: string }.

Explicitly mark a CLAIMED contract as terminal FAILED with a mandatory failure reason.

Purpose

Immediately terminates a claimed task that cannot be completed, recording actionable diagnostic reasons and freeing the requester from waiting for the execution TTL to expire.

Usage Guidelines

• When to use: Use when a task encounters an unrecoverable failure (e.g. fatal syntax error, broken test suite, missing required environment).

• When NOT to use:

  • Do NOT use if the task succeeded (use fulfill_contract).

  • Do NOT use if the task is recoverable by another agent or retryable (use release_contract).

• Prerequisites: Caller must be the current holder and reason must be non-empty.

Behavior & Side Effects

• Mutates database: Sets status='FAILED', error_reason='WORKER_FAILED: ', and completed_at=nowMs.

• Late report handling: If the execution window already expired before fail_contract was called, the status becomes TIMED_OUT while faithfully preserving the worker's reason for the requester.

Return Value

Returns { ok: boolean, contract_id: string, status: 'FAILED' | 'TIMED_OUT', message: string }.

Read-only pre-flight consistency check (ADR-0004): audits on-disk pointer files against the baseline SHA-256 snapshot.

Purpose

Enables agents or automated scripts to verify that on-disk files match the contract's dispatched baseline before calling fulfill_contract, preventing accidental TOCTOU strikes.

Usage Guidelines

• When to use: Call before fulfill_contract while holding a CLAIMED contract to confirm file cleanliness, or when investigating why a fulfill call was blocked.

• When NOT to use:

  • Do NOT use to deliver results (use fulfill_contract).

  • Do NOT use to renew time (use extend_ttl).

• ADR-0004 Rule: Pointers are an immutable review baseline. If verify_contract reports dirty files, restore or stash them (e.g., git stash or git checkout -- ) and deliver proposed changes inside structured_output.fixes.

Behavior & Side Effects

• Zero side effects: Pure read-only operation. Never updates the database, never alters contract status, and never consumes a TOCTOU strike.

• Complete pointer check: Verifies all pointer files on disk and returns every drifted file (reason: SIZE_MISMATCH, CONTENT_CHANGED, or FILE_MISSING).

Return Value

Returns { ok: true, valid: boolean, fulfillable: boolean, contract_id: string, status: ContractStatus, target_agent: string, toctou_strike: number, max_toctou_strikes: number, dirty_files: Array<{ path, reason, detail }>, message: string }. NOTE: valid only means every pointer still matches its dispatched baseline. fulfillable additionally requires the contract to be CLAIMED. A contract that already went terminal (FAILED / POINTER_STALE / COMPLETED) can report valid=true while fulfillable=false, so branch on fulfillable rather than valid before calling fulfill_contract.