nawabari 0.1.0 → 0.3.0

package/dist/cli.js

@@ -1,53 +1,345 @@
 import { createRequire } from "node:module";
 import { runDoctor } from "./domain/doctor.js";
 import { DomainError, EXIT_CODES, failure } from "./domain/errors.js";
+import { MAX_SESSION_LIST_LIMIT, } from "./domain/session.js";
+import { EVIDENCE_MAX_DIFF_BYTES, EVIDENCE_MAX_DIFF_HUNKS, EVIDENCE_MAX_DIFF_PATHS } from "./repository-evidence.js";
 import { createLocalSessionBackend } from "./domain/session-backend.js";
 import { defaultCliIO, renderFailure, renderSuccess } from "./presentation.js";
+import { MACHINE_CONTRACT_ID, MACHINE_CONTRACT_SCHEMA_VERSION, machineContract } from "./contract.js";
 const CLI_NAME = "nawabari";
 const packageMetadata = createRequire(import.meta.url)("../package.json");
 const VERSION = packageMetadata.version;
-const HELP_TEXT = [
-    `Usage: ${CLI_NAME} <command> [options]`,
-    "",
-    "Commands:",
-    "  session create       Request a new Nawabari session",
-    "  session id           Resolve the current session identity",
-    "  session show         Show the current or selected session",
-    "  session list         List repository sessions",
-    "  session close        Close the current or selected session",
-    "  status               Show Nawabari session status",
-    "  guard [--session id] Authorize the current worktree for mutation",
-    "  gc                   Detect or clean eligible stale sessions",
-    "  doctor               Check local Nawabari prerequisites",
-    "  --help               Show this help",
-    "  --version            Print the installed version",
-    "",
-    "Global options:",
-    "  --json               Emit one stable JSON document on stdout",
-    "  -h, --help           Show this help",
-    "",
-    "Session options:",
-    "  session create --branch <name> --worktree <path> --base <ref> --label <text>",
-    "  session show|close --session <id>",
-    "  gc [--dry-run|--apply]",
-].join("\n");
-const HELP_DATA = {
-    usage: `Usage: ${CLI_NAME} <command> [options]`,
-    commands: [
-        "session create",
-        "session id",
-        "session show",
-        "session list",
-        "session close",
-        "status",
-        "guard",
-        "gc",
-        "doctor",
-    ],
-    options: ["--json", "--help", "--version"],
-    session_options: ["--branch", "--worktree", "--base", "--label", "--session"],
-    gc_options: ["--apply", "--dry-run"],
+const GLOBAL_HELP_OPTIONS = [
+    { name: "--json", description: "Emit one stable JSON document on stdout" },
+    { name: "--help", description: "Show command-specific help" },
+    { name: "--version", description: "Print the installed version" },
+];
+const option = (name, description, options = {}) => ({ name, description, ...options });
+const HELP_COMMANDS = [
+    {
+        name: "session create",
+        summary: "Request a new Nawabari session",
+        usage: `${CLI_NAME} session create [options]`,
+        options: [
+            option("--branch", "Branch to create; omitted uses the generated session branch", {
+                value: "<name>",
+                default: "nawabari/session/<session_id>",
+            }),
+            option("--worktree", "Managed worktree path; omitted uses the resolved repository-local root", {
+                value: "<path>",
+                default: "<managed_worktree_root>/<repository>-<session_id>",
+            }),
+            option("--base", "Commit-resolving base ref for the new worktree", { value: "<ref>", default: "HEAD" }),
+            option("--label", "Optional display label; never used as an identity", { value: "<text>", default: "omitted" }),
+        ],
+        notes: ["All create options are optional. Use status --json to discover managed_worktree_root."],
+    },
+    {
+        name: "session id",
+        summary: "Resolve the current session identity",
+        usage: `${CLI_NAME} session id`,
+        options: [],
+    },
+    {
+        name: "session show",
+        summary: "Show the current or selected session",
+        usage: `${CLI_NAME} session show [--session <id>]`,
+        options: [option("--session", "Select a session instead of the current worktree owner", { value: "<id>" })],
+    },
+    {
+        name: "session list",
+        summary: "List bounded repository session records",
+        usage: `${CLI_NAME} session list [--all|--history]`,
+        options: [
+            option("--all", "Include closed history; explicit unbounded history view"),
+            option("--history", "Alias for --all"),
+        ],
+        notes: ["Default output excludes closed records and is limited to 64 records."],
+    },
+    {
+        name: "session claim",
+        summary: "Add a canonical resource claim",
+        usage: `${CLI_NAME} session claim --resource <path-or-glob> --mode <read|write|exclusive-write> [--session <id>]`,
+        options: [
+            option("--resource", "Repository-relative resource", { value: "<path-or-glob>", required: true }),
+            option("--mode", "Granted claim mode", { value: "<read|write|exclusive-write>", required: true }),
+            option("--session", "Target active session; omitted resolves the current owner", { value: "<id>" }),
+            option("--repository", "Expected repository identity", { value: "<id>" }),
+        ],
+    },
+    {
+        name: "session update",
+        summary: "Replace a session's resource claims",
+        usage: `${CLI_NAME} session update --resource <path-or-glob> --mode <read|write|exclusive-write> [--session <id>]`,
+        options: [
+            option("--resource", "Repository-relative resource", { value: "<path-or-glob>", required: true }),
+            option("--mode", "Granted claim mode", { value: "<read|write|exclusive-write>", required: true }),
+            option("--session", "Target active session; omitted resolves the current owner", { value: "<id>" }),
+            option("--repository", "Expected repository identity", { value: "<id>" }),
+        ],
+    },
+    {
+        name: "session claims",
+        summary: "List canonical resource claims",
+        usage: `${CLI_NAME} session claims [--session <id>]`,
+        options: [option("--session", "Select a session; omitted lists all claims", { value: "<id>" })],
+    },
+    {
+        name: "session release",
+        summary: "Release resource claims",
+        usage: `${CLI_NAME} session release [--session <id>] [--claim-id <id>]`,
+        options: [
+            option("--session", "Target session; omitted resolves the current owner", { value: "<id>" }),
+            option("--claim-id", "Release only one claim; omitted releases all owned claims", { value: "<id>" }),
+        ],
+    },
+    {
+        name: "resource claim",
+        summary: "Add a canonical resource claim (alias)",
+        usage: `${CLI_NAME} resource claim --resource <path-or-glob> --mode <read|write|exclusive-write>`,
+        options: [],
+    },
+    {
+        name: "resource update",
+        summary: "Replace a session's resource claims (alias)",
+        usage: `${CLI_NAME} resource update --resource <path-or-glob> --mode <read|write|exclusive-write>`,
+        options: [],
+    },
+    {
+        name: "resource list",
+        summary: "List canonical resource claims (alias)",
+        usage: `${CLI_NAME} resource list [--session <id>]`,
+        options: [option("--session", "Select a session; omitted lists all claims", { value: "<id>" })],
+    },
+    {
+        name: "resource release",
+        summary: "Release resource claims (alias)",
+        usage: `${CLI_NAME} resource release [--session <id>] [--claim-id <id>]`,
+        options: [
+            option("--session", "Target session; omitted resolves the current owner", { value: "<id>" }),
+            option("--claim-id", "Release only one claim; omitted releases all owned claims", { value: "<id>" }),
+        ],
+    },
+    {
+        name: "session close",
+        summary: "Close the current or selected session",
+        usage: `${CLI_NAME} session close [--session <id>]`,
+        options: [option("--session", "Select a session instead of the current worktree owner", { value: "<id>" })],
+    },
+    {
+        name: "authorize",
+        summary: "Authorize an operation against concrete claims",
+        usage: `${CLI_NAME} authorize --operation <name> --resource <path> [--resource <path>] [--session <id>]`,
+        options: [
+            option("--session", "Assert the current session identity", { value: "<id>" }),
+            option("--operation", "Operation vocabulary entry", { value: "<name>", required: true }),
+            option("--resource", "Concrete repository-relative path; repeatable", { value: "<path>", required: true }),
+        ],
+    },
+    {
+        name: "checkpoint",
+        summary: "Capture bounded Git execution evidence",
+        usage: `${CLI_NAME} checkpoint [--session <id>]`,
+        options: [option("--session", "Assert the current session identity", { value: "<id>" })],
+    },
+    {
+        name: "evidence snapshot",
+        summary: "Capture bounded read-only evidence for one owned session",
+        usage: `${CLI_NAME} evidence snapshot --session <id>`,
+        options: [option("--session", "Explicit owned session to observe", { value: "<id>", required: true })],
+        notes: ["The result is Git-observable physical evidence only; it contains no task or semantic interpretation."],
+    },
+    {
+        name: "diff",
+        summary: "Inspect bounded Git evidence for explicit paths",
+        usage: `${CLI_NAME} diff --session <id> --path <path> [options]`,
+        options: [
+            option("--session", "Explicit owned session to observe", { value: "<id>", required: true }),
+            option("--path", "Concrete repository-relative path; repeatable", { value: "<path>", required: true }),
+            option("--from", "Commit/ref at the start of the range", { value: "<ref>", default: "HEAD" }),
+            option("--to", "Commit/ref at the end of the range; omitted means worktree", { value: "<ref>" }),
+            option("--patch", "Include patch text; requires the bounded byte/hunk limits"),
+            option("--max-bytes", "Maximum UTF-8 patch bytes", { value: "<n>", default: String(EVIDENCE_MAX_DIFF_BYTES) }),
+            option("--max-hunks", "Maximum patch hunks", { value: "<n>", default: String(EVIDENCE_MAX_DIFF_HUNKS) }),
+        ],
+    },
+    {
+        name: "commit",
+        summary: "Commit explicit claim-authorized resources",
+        usage: `${CLI_NAME} commit --message <final-message> --resource <path> [--resource <path>] [--session <id>] [--message-pattern <regex>]`,
+        options: [
+            option("--session", "Assert the current session identity", { value: "<id>" }),
+            option("--message", "Caller-decided final commit message", { value: "<final-message>", required: true }),
+            option("--resource", "Claim-covered concrete path; repeatable", { value: "<path>", required: true }),
+            option("--message-pattern", "Caller-declared commit-message rule; validated only when supplied", {
+                value: "<regex>",
+            }),
+        ],
+    },
+    {
+        name: "push",
+        summary: "Push the owned branch to an explicit target",
+        usage: `${CLI_NAME} push --remote <name> --branch <name> --resource <path> [options]`,
+        options: [
+            option("--session", "Assert the current session identity", { value: "<id>" }),
+            option("--resource", "Claim-covered concrete path; repeatable", { value: "<path>", required: true }),
+            option("--remote", "Explicit Git remote", { value: "<name>", required: true }),
+            option("--branch", "Explicit target branch", { value: "<name>", required: true }),
+            option("--remote-branch", "Explicit remote branch alias for --branch", { value: "<name>" }),
+            option("--force", "Allow force-with-lease when relation requires it"),
+            option("--create-upstream", "Allow creation of a missing upstream"),
+        ],
+    },
+    {
+        name: "status",
+        summary: "Show repository context and bounded session status",
+        usage: `${CLI_NAME} status [--all|--history]`,
+        options: [
+            option("--all", "Include closed history; explicit unbounded history view"),
+            option("--history", "Alias for --all"),
+        ],
+        notes: ["The default machine result exposes managed_worktree_root for session-create path discovery."],
+    },
+    {
+        name: "guard",
+        summary: "Authorize the current worktree or operation",
+        usage: `${CLI_NAME} guard [--session <id>] [--operation <name> --resource <path>]`,
+        options: [
+            option("--session", "Assert the current session identity", { value: "<id>" }),
+            option("--operation", "Authorize an operation when resources are supplied", { value: "<name>" }),
+            option("--resource", "Concrete resource; repeatable with --operation", { value: "<path>" }),
+        ],
+    },
+    {
+        name: "gc",
+        summary: "Detect or clean eligible stale sessions",
+        usage: `${CLI_NAME} gc [--dry-run|--apply]`,
+        options: [
+            option("--apply", "Apply only cleanup that passes safety checks"),
+            option("--dry-run", "Preflight eligible stale cleanup without mutation"),
+        ],
+        notes: [
+            "Default stale threshold is 24 hours (86,400,000 ms). Eligibility uses persisted state age or missing/prunable Git worktree physical state; closed history is not a stale candidate.",
+        ],
+    },
+    {
+        name: "doctor",
+        summary: "Check local Nawabari prerequisites and reconciliation",
+        usage: `${CLI_NAME} doctor`,
+        options: [],
+    },
+    {
+        name: "capabilities",
+        summary: "Describe the standalone CLI/JSON contract",
+        usage: `${CLI_NAME} capabilities`,
+        options: [],
+    },
+];
+const ROOT_HELP_SPEC = {
+    name: "root",
+    summary: "Standalone local Git/session ownership CLI",
+    usage: `${CLI_NAME} <command> [options]`,
+    options: GLOBAL_HELP_OPTIONS,
 };
+function helpSpecFor(commandArguments) {
+    if (commandArguments.length === 0)
+        return ROOT_HELP_SPEC;
+    let key = commandArguments[0] === "resource"
+        ? `resource ${commandArguments[1] ?? "list"}`
+        : commandArguments.slice(0, 2).join(" ");
+    if (key === "resource claims")
+        key = "resource list";
+    const direct = HELP_COMMANDS.find((spec) => spec.name === key);
+    if (direct !== undefined && !direct.name.startsWith("resource "))
+        return direct;
+    const aliasTarget = direct?.name.replace(/^resource /u, "session ");
+    const target = aliasTarget === undefined ? undefined : HELP_COMMANDS.find((spec) => spec.name === aliasTarget);
+    if (direct !== undefined && target !== undefined) {
+        return {
+            name: direct.name,
+            summary: direct.summary,
+            usage: direct.usage,
+            options: direct.options,
+            notes: direct.notes,
+        };
+    }
+    return HELP_COMMANDS.find((spec) => spec.name === commandArguments[0]) ?? ROOT_HELP_SPEC;
+}
+function helpPayload(spec) {
+    if (spec.name === "root") {
+        const optionNames = (options) => options.map((candidate) => candidate.name);
+        const sessionOptions = HELP_COMMANDS.filter((command) => command.name.startsWith("session ")).flatMap((command) => command.options);
+        const unique = (values) => values.filter((value, index) => values.indexOf(value) === index);
+        const sessionListOnlyOptions = new Set(["--all", "--history"]);
+        const optionsFor = (name) => optionNames(HELP_COMMANDS.find((command) => command.name === name)?.options ?? []);
+        return {
+            usage: `Usage: ${spec.usage}`,
+            commands: HELP_COMMANDS.map((command) => command.name),
+            options: ["--json", "--help", "--version"],
+            session_options: unique(sessionOptions.map((option) => option.name).filter((name) => !sessionListOnlyOptions.has(name))),
+            authorization_options: optionsFor("authorize"),
+            checkpoint_options: optionsFor("checkpoint"),
+            commit_options: optionsFor("commit"),
+            push_options: optionsFor("push"),
+            gc_options: optionsFor("gc"),
+        };
+    }
+    const options = spec.options.map((candidate) => ({
+        name: candidate.name,
+        ...(candidate.value === undefined ? {} : { value: candidate.value }),
+        required: candidate.required === true,
+        ...(candidate.default === undefined ? {} : { default: candidate.default }),
+        description: candidate.description,
+    }));
+    return {
+        help_for: spec.name,
+        usage: spec.usage,
+        summary: spec.summary,
+        required_options: spec.options
+            .filter((candidate) => candidate.required === true)
+            .map((candidate) => candidate.name),
+        optional_options: spec.options
+            .filter((candidate) => candidate.required !== true)
+            .map((candidate) => candidate.name),
+        defaults: Object.fromEntries(spec.options
+            .filter((candidate) => candidate.default !== undefined)
+            .map((candidate) => [candidate.name, candidate.default])),
+        options,
+        ...(spec.notes === undefined ? {} : { notes: [...spec.notes] }),
+    };
+}
+function helpText(spec) {
+    const lines = [`Usage: ${spec.usage}`, "", spec.summary];
+    if (spec.name === "root") {
+        lines.push("", "Commands:");
+        for (const command of HELP_COMMANDS)
+            lines.push(`  ${command.name.padEnd(20)} ${command.summary}`);
+        lines.push("", "Global options:");
+        for (const candidate of GLOBAL_HELP_OPTIONS) {
+            const label = candidate.name === "--help" ? "-h, --help" : candidate.name;
+            lines.push(`  ${label.padEnd(20)} ${candidate.description}`);
+        }
+    }
+    else {
+        lines.push("", "Options:");
+        if (spec.options.length === 0)
+            lines.push("  (none)");
+        for (const candidate of spec.options) {
+            const label = candidate.value === undefined ? candidate.name : `${candidate.name} ${candidate.value}`;
+            const qualifier = candidate.required === true
+                ? "required"
+                : `optional${candidate.default === undefined ? "" : `; default: ${candidate.default}`}`;
+            lines.push(`  ${label.padEnd(38)} ${qualifier}; ${candidate.description}`);
+        }
+        if (spec.notes !== undefined) {
+            lines.push("", "Notes:");
+            for (const note of spec.notes)
+                lines.push(`  ${note}`);
+        }
+    }
+    return lines.join("\n");
+}
+const HELP_TEXT = helpText(ROOT_HELP_SPEC);
 function usageError(code, message, details = null) {
     return new DomainError(code, message, details);
 }
@@ -91,7 +383,29 @@ function parseOptions(arguments_, allowed) {
         worktree: null,
         base: null,
         label: null,
+        resource: null,
+        resources: [],
+        operation: null,
+        message: null,
+        message_pattern: null,
+        remote: null,
+        remote_branch: null,
+        mode: null,
+        claim_id: null,
+        repository: null,
         apply: false,
+        force: false,
+        create_upstream: false,
+        all: false,
+        history: false,
+        limit: null,
+        offset: null,
+        paths: [],
+        from_revision: null,
+        to_revision: null,
+        patch: false,
+        max_bytes: null,
+        max_hunks: null,
     };
     let dryRun = false;
     for (let index = 0; index < arguments_.length; index += 1) {
@@ -99,14 +413,30 @@ function parseOptions(arguments_, allowed) {
         if (!allowed.has(name)) {
             return failure(usageError("INVALID_ARGUMENT", `Unknown option: ${name}.`, { option: name }));
         }
-        if (name === "--apply" || name === "--dry-run") {
+        if (name === "--apply" ||
+            name === "--dry-run" ||
+            name === "--force" ||
+            name === "--create-upstream" ||
+            name === "--all" ||
+            name === "--history" ||
+            name === "--patch") {
             if (inlineValue !== null) {
                 return failure(usageError("INVALID_ARGUMENT", `${name} does not accept a value.`, { option: name }));
             }
             if (name === "--apply")
                 options.apply = true;
-            else
+            else if (name === "--dry-run")
                 dryRun = true;
+            else if (name === "--force")
+                options.force = true;
+            else if (name === "--create-upstream")
+                options.create_upstream = true;
+            else if (name === "--all")
+                options.all = true;
+            else if (name === "--history")
+                options.history = true;
+            else
+                options.patch = true;
             continue;
         }
         const value = inlineValue ?? arguments_[index + 1];
@@ -125,6 +455,40 @@ function parseOptions(arguments_, allowed) {
             options.base = value;
         else if (name === "--label")
             options.label = value;
+        else if (name === "--resource") {
+            options.resource = value;
+            options.resources.push(value);
+        }
+        else if (name === "--operation")
+            options.operation = value;
+        else if (name === "--message")
+            options.message = value;
+        else if (name === "--message-pattern")
+            options.message_pattern = value;
+        else if (name === "--remote")
+            options.remote = value;
+        else if (name === "--remote-branch")
+            options.remote_branch = value;
+        else if (name === "--mode")
+            options.mode = value;
+        else if (name === "--claim-id")
+            options.claim_id = value;
+        else if (name === "--repository")
+            options.repository = value;
+        else if (name === "--limit")
+            options.limit = value;
+        else if (name === "--offset")
+            options.offset = value;
+        else if (name === "--path")
+            options.paths.push(value);
+        else if (name === "--from")
+            options.from_revision = value;
+        else if (name === "--to")
+            options.to_revision = value;
+        else if (name === "--max-bytes")
+            options.max_bytes = value;
+        else if (name === "--max-hunks")
+            options.max_hunks = value;
     }
     if (options.apply && dryRun) {
         return failure(usageError("INVALID_ARGUMENT", "--apply and --dry-run cannot be used together."));
@@ -134,6 +498,52 @@ function parseOptions(arguments_, allowed) {
 function noOptions(arguments_) {
     return parseOptions(arguments_, new Set());
 }
+function sessionListingOptions(parsed) {
+    const parseInteger = (option, value) => {
+        if (value === null)
+            return { ok: true, value: undefined };
+        if (!/^\d+$/u.test(value)) {
+            return failure(usageError("INVALID_ARGUMENT", `${option} requires a non-negative integer.`, { option, value }));
+        }
+        const parsedValue = Number(value);
+        if (!Number.isSafeInteger(parsedValue)) {
+            return failure(usageError("INVALID_ARGUMENT", `${option} is outside the safe integer range.`, { option }));
+        }
+        return { ok: true, value: parsedValue };
+    };
+    const limit = parseInteger("--limit", parsed.limit);
+    if (!limit.ok)
+        return limit;
+    if (limit.value !== undefined && (limit.value < 1 || limit.value > MAX_SESSION_LIST_LIMIT)) {
+        return failure(usageError("INVALID_ARGUMENT", `--limit must be between 1 and ${MAX_SESSION_LIST_LIMIT}.`, {
+            option: "--limit",
+            max: MAX_SESSION_LIST_LIMIT,
+        }));
+    }
+    const offset = parseInteger("--offset", parsed.offset);
+    if (!offset.ok)
+        return offset;
+    return {
+        ok: true,
+        value: {
+            include_closed: parsed.all || parsed.history,
+            ...(limit.value === undefined ? {} : { limit: limit.value }),
+            ...(offset.value === undefined ? {} : { offset: offset.value }),
+        },
+    };
+}
+function boundedEvidenceInteger(option, value, max) {
+    if (value === null)
+        return { ok: true, value: undefined };
+    if (!/^\d+$/u.test(value)) {
+        return failure(usageError("INVALID_ARGUMENT", `${option} requires a positive integer.`, { option, value }));
+    }
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed < 1 || parsed > max) {
+        return failure(usageError("INVALID_ARGUMENT", `${option} must be between 1 and ${max}.`, { option, max, value }));
+    }
+    return { ok: true, value: parsed };
+}
 function sessionContext(cwd) {
     return { cwd };
 }
@@ -147,6 +557,48 @@ async function executeCommand(commandArguments, dependencies) {
         if (subcommand === undefined) {
             return failure(usageError("MISSING_ARGUMENT", "session requires a subcommand."));
         }
+        if (subcommand === "claim" || subcommand === "update") {
+            const parsed = parseOptions(rest, new Set(["--session", "--resource", "--mode", "--repository"]));
+            if (!parsed.ok)
+                return parsed;
+            if (parsed.value.resource === null) {
+                return failure(usageError("MISSING_ARGUMENT", "--resource requires a value.", { option: "--resource" }));
+            }
+            if (parsed.value.mode === null) {
+                return failure(usageError("MISSING_ARGUMENT", "--mode requires a value.", { option: "--mode" }));
+            }
+            const options = {
+                session_id: parsed.value.session_id,
+                repository: parsed.value.repository,
+                claims: [{ resource: parsed.value.resource, mode: parsed.value.mode }],
+            };
+            const operation = subcommand === "claim" ? dependencies.backend.claimResources : dependencies.backend.updateClaims;
+            if (operation === undefined)
+                return claimCapabilityUnavailable(subcommand);
+            const result = await operation.call(dependencies.backend, context, options);
+            return result.ok ? { ok: true, value: result.value } : result;
+        }
+        if (subcommand === "claims") {
+            const parsed = parseOptions(rest, new Set(["--session"]));
+            if (!parsed.ok)
+                return parsed;
+            if (dependencies.backend.listClaims === undefined)
+                return claimCapabilityUnavailable("claims");
+            const result = await dependencies.backend.listClaims(context, parsed.value.session_id);
+            return result.ok ? { ok: true, value: result.value } : result;
+        }
+        if (subcommand === "release") {
+            const parsed = parseOptions(rest, new Set(["--session", "--claim-id"]));
+            if (!parsed.ok)
+                return parsed;
+            if (dependencies.backend.releaseClaims === undefined)
+                return claimCapabilityUnavailable("release");
+            const result = await dependencies.backend.releaseClaims(context, {
+                session_id: parsed.value.session_id,
+                claim_ids: parsed.value.claim_id === null ? null : [parsed.value.claim_id],
+            });
+            return result.ok ? { ok: true, value: result.value } : result;
+        }
         if (subcommand === "create") {
             const parsed = parseOptions(rest, new Set(["--branch", "--worktree", "--base", "--label"]));
             if (!parsed.ok)
@@ -182,25 +634,232 @@ async function executeCommand(commandArguments, dependencies) {
             return selected.ok ? { ok: true, value: selected.value } : selected;
         }
         if (subcommand === "list") {
-            const parsed = noOptions(rest);
+            const parsed = parseOptions(rest, new Set(["--all", "--history", "--limit", "--offset"]));
             if (!parsed.ok)
                 return parsed;
-            const result = await dependencies.backend.listSessions(context);
+            const options = sessionListingOptions(parsed.value);
+            if (!options.ok)
+                return options;
+            const result = await dependencies.backend.listSessions(context, options.value);
             return result.ok ? { ok: true, value: result.value } : result;
         }
         return failure(new DomainError("UNKNOWN_COMMAND", `Unknown session subcommand: ${subcommand}.`, { subcommand }));
     }
+    if (command === "resource") {
+        const resourceSubcommand = subcommand ?? "list";
+        if (resourceSubcommand === "claim" || resourceSubcommand === "update") {
+            const parsed = parseOptions(rest, new Set(["--session", "--resource", "--mode", "--repository"]));
+            if (!parsed.ok)
+                return parsed;
+            if (parsed.value.resource === null || parsed.value.mode === null) {
+                return failure(usageError("MISSING_ARGUMENT", "resource claim requires --resource and --mode."));
+            }
+            const operation = resourceSubcommand === "claim" ? dependencies.backend.claimResources : dependencies.backend.updateClaims;
+            if (operation === undefined)
+                return claimCapabilityUnavailable(resourceSubcommand);
+            const result = await operation.call(dependencies.backend, context, {
+                session_id: parsed.value.session_id,
+                repository: parsed.value.repository,
+                claims: [{ resource: parsed.value.resource, mode: parsed.value.mode }],
+            });
+            return result.ok ? { ok: true, value: result.value } : result;
+        }
+        if (resourceSubcommand === "list" || resourceSubcommand === "claims") {
+            const parsed = parseOptions(rest, new Set(["--session"]));
+            if (!parsed.ok)
+                return parsed;
+            if (dependencies.backend.listClaims === undefined)
+                return claimCapabilityUnavailable("list");
+            const result = await dependencies.backend.listClaims(context, parsed.value.session_id);
+            return result.ok ? { ok: true, value: result.value } : result;
+        }
+        if (resourceSubcommand === "release") {
+            const parsed = parseOptions(rest, new Set(["--session", "--claim-id"]));
+            if (!parsed.ok)
+                return parsed;
+            if (dependencies.backend.releaseClaims === undefined)
+                return claimCapabilityUnavailable("release");
+            const result = await dependencies.backend.releaseClaims(context, {
+                session_id: parsed.value.session_id,
+                claim_ids: parsed.value.claim_id === null ? null : [parsed.value.claim_id],
+            });
+            return result.ok ? { ok: true, value: result.value } : result;
+        }
+        return failure(new DomainError("UNKNOWN_COMMAND", `Unknown resource subcommand: ${resourceSubcommand}.`, {
+            subcommand: resourceSubcommand,
+        }));
+    }
+    if (command === "authorize") {
+        const parsed = parseOptions([subcommand, ...rest].filter((argument) => argument !== undefined), new Set(["--session", "--operation", "--resource"]));
+        if (!parsed.ok)
+            return parsed;
+        if (parsed.value.operation === null) {
+            return failure(usageError("MISSING_ARGUMENT", "--operation requires a value.", { option: "--operation" }));
+        }
+        if (parsed.value.resources.length === 0) {
+            return failure(usageError("MISSING_ARGUMENT", "--resource requires a value.", { option: "--resource" }));
+        }
+        if (dependencies.backend.authorizeOperation === undefined)
+            return authorizationCapabilityUnavailable();
+        const options = {
+            session_id: parsed.value.session_id,
+            operation: parsed.value.operation,
+            resources: parsed.value.resources,
+        };
+        const result = await dependencies.backend.authorizeOperation(context, options);
+        if (!result.ok)
+            return result;
+        return result.value.allowed
+            ? { ok: true, value: result.value }
+            : deniedAuthorization(result.value);
+    }
+    if (command === "checkpoint") {
+        const parsed = parseOptions([subcommand, ...rest].filter((argument) => argument !== undefined), new Set(["--session"]));
+        if (!parsed.ok)
+            return parsed;
+        if (dependencies.backend.checkpoint === undefined)
+            return checkpointCapabilityUnavailable();
+        const options = { session_id: parsed.value.session_id };
+        const result = await dependencies.backend.checkpoint(context, options);
+        return result.ok ? { ok: true, value: result.value } : result;
+    }
+    if (command === "evidence" && subcommand === "snapshot") {
+        const parsed = parseOptions(rest, new Set(["--session"]));
+        if (!parsed.ok)
+            return parsed;
+        if (parsed.value.session_id === null) {
+            return failure(usageError("MISSING_ARGUMENT", "evidence snapshot requires --session.", { option: "--session" }));
+        }
+        if (dependencies.backend.repositoryEvidence === undefined) {
+            return repositoryEvidenceCapabilityUnavailable("evidence snapshot");
+        }
+        const options = { session_id: parsed.value.session_id };
+        const result = await dependencies.backend.repositoryEvidence(context, options);
+        return result.ok ? { ok: true, value: result.value } : result;
+    }
+    if (command === "diff") {
+        const parsed = parseOptions([subcommand, ...rest].filter((argument) => argument !== undefined), new Set(["--session", "--path", "--from", "--to", "--patch", "--max-bytes", "--max-hunks"]));
+        if (!parsed.ok)
+            return parsed;
+        if (parsed.value.session_id === null) {
+            return failure(usageError("MISSING_ARGUMENT", "diff requires --session.", { option: "--session" }));
+        }
+        if (parsed.value.paths.length === 0) {
+            return failure(usageError("MISSING_ARGUMENT", "diff requires at least one --path.", { option: "--path" }));
+        }
+        if (parsed.value.paths.length > EVIDENCE_MAX_DIFF_PATHS) {
+            return failure(usageError("INVALID_ARGUMENT", `diff accepts at most ${EVIDENCE_MAX_DIFF_PATHS} paths.`, {
+                option: "--path",
+                max: EVIDENCE_MAX_DIFF_PATHS,
+            }));
+        }
+        const maxBytes = boundedEvidenceInteger("--max-bytes", parsed.value.max_bytes, EVIDENCE_MAX_DIFF_BYTES);
+        if (!maxBytes.ok)
+            return maxBytes;
+        const maxHunks = boundedEvidenceInteger("--max-hunks", parsed.value.max_hunks, EVIDENCE_MAX_DIFF_HUNKS);
+        if (!maxHunks.ok)
+            return maxHunks;
+        if (dependencies.backend.repositoryDiff === undefined) {
+            return repositoryEvidenceCapabilityUnavailable("diff");
+        }
+        const options = {
+            session_id: parsed.value.session_id,
+            paths: parsed.value.paths,
+            from: parsed.value.from_revision,
+            to: parsed.value.to_revision,
+            include_patch: parsed.value.patch,
+            max_bytes: maxBytes.value,
+            max_hunks: maxHunks.value,
+        };
+        const result = await dependencies.backend.repositoryDiff(context, options);
+        return result.ok ? { ok: true, value: result.value } : result;
+    }
+    if (command === "commit") {
+        const parsed = parseOptions([subcommand, ...rest].filter((argument) => argument !== undefined), new Set(["--session", "--message", "--resource", "--message-pattern"]));
+        if (!parsed.ok)
+            return parsed;
+        if (parsed.value.message === null) {
+            return failure(usageError("MISSING_ARGUMENT", "--message requires a value.", { option: "--message" }));
+        }
+        if (parsed.value.resources.length === 0) {
+            return failure(usageError("MISSING_ARGUMENT", "--resource requires a value.", { option: "--resource" }));
+        }
+        if (dependencies.backend.commit === undefined)
+            return mutationCapabilityUnavailable("commit");
+        const result = await dependencies.backend.commit(context, {
+            session_id: parsed.value.session_id,
+            message: parsed.value.message,
+            resources: parsed.value.resources,
+            message_pattern: parsed.value.message_pattern,
+        });
+        return result.ok ? { ok: true, value: result.value } : result;
+    }
+    if (command === "push") {
+        const parsed = parseOptions([subcommand, ...rest].filter((argument) => argument !== undefined), new Set(["--session", "--resource", "--remote", "--branch", "--remote-branch", "--force", "--create-upstream"]));
+        if (!parsed.ok)
+            return parsed;
+        if (parsed.value.remote === null) {
+            return failure(usageError("MISSING_ARGUMENT", "--remote requires a value.", { option: "--remote" }));
+        }
+        if (parsed.value.branch === null && parsed.value.remote_branch === null) {
+            return failure(usageError("MISSING_ARGUMENT", "--branch requires a value.", { option: "--branch" }));
+        }
+        if (parsed.value.branch !== null &&
+            parsed.value.remote_branch !== null &&
+            parsed.value.branch !== parsed.value.remote_branch) {
+            return failure(usageError("INVALID_ARGUMENT", "--branch and --remote-branch must identify the same target."));
+        }
+        if (parsed.value.resources.length === 0) {
+            return failure(usageError("MISSING_ARGUMENT", "--resource requires a value.", { option: "--resource" }));
+        }
+        if (dependencies.backend.push === undefined)
+            return mutationCapabilityUnavailable("push");
+        const result = await dependencies.backend.push(context, {
+            session_id: parsed.value.session_id,
+            resources: parsed.value.resources,
+            remote: parsed.value.remote,
+            branch: parsed.value.branch ?? parsed.value.remote_branch,
+            force: parsed.value.force,
+            create_upstream: parsed.value.create_upstream,
+        });
+        return result.ok ? { ok: true, value: result.value } : result;
+    }
     if (command === "status") {
-        const parsed = noOptions([subcommand, ...rest].filter((argument) => argument !== undefined));
+        const parsed = parseOptions([subcommand, ...rest].filter((argument) => argument !== undefined), new Set(["--all", "--history", "--limit", "--offset"]));
         if (!parsed.ok)
             return parsed;
-        const result = await dependencies.backend.status(context);
+        const options = sessionListingOptions(parsed.value);
+        if (!options.ok)
+            return options;
+        const result = await dependencies.backend.status(context, options.value);
         return result.ok ? { ok: true, value: result.value } : result;
     }
     if (command === "guard") {
-        const parsed = parseOptions([subcommand, ...rest].filter((argument) => argument !== undefined), new Set(["--session"]));
+        const parsed = parseOptions([subcommand, ...rest].filter((argument) => argument !== undefined), new Set(["--session", "--operation", "--resource"]));
         if (!parsed.ok)
             return parsed;
+        if (parsed.value.resources.length > 0 && parsed.value.operation === null) {
+            return failure(usageError("MISSING_ARGUMENT", "--operation is required when --resource is provided.", {
+                option: "--operation",
+            }));
+        }
+        if (parsed.value.operation !== null) {
+            if (parsed.value.resources.length === 0) {
+                return failure(usageError("MISSING_ARGUMENT", "--resource requires a value.", { option: "--resource" }));
+            }
+            if (dependencies.backend.authorizeOperation === undefined)
+                return authorizationCapabilityUnavailable();
+            const result = await dependencies.backend.authorizeOperation(context, {
+                session_id: parsed.value.session_id,
+                operation: parsed.value.operation,
+                resources: parsed.value.resources,
+            });
+            if (!result.ok)
+                return result;
+            return result.value.allowed
+                ? { ok: true, value: result.value }
+                : deniedAuthorization(result.value);
+        }
         const result = await dependencies.backend.guard(context, { session_id: parsed.value.session_id });
         if (!result.ok)
             return result;
@@ -248,8 +907,56 @@ async function executeCommand(commandArguments, dependencies) {
 function commandName(commandArguments) {
     if (commandArguments[0] === "session")
         return commandArguments.slice(0, 2).join(" ");
+    if (commandArguments[0] === "resource")
+        return commandArguments.slice(0, 2).join(" ");
+    if (commandArguments[0] === "evidence")
+        return commandArguments.slice(0, 2).join(" ");
     return commandArguments[0] ?? "cli";
 }
+function claimCapabilityUnavailable(operation) {
+    return failure(new DomainError("BACKEND_UNAVAILABLE", "Resource claim capability is not available.", { operation }));
+}
+function authorizationCapabilityUnavailable() {
+    return failure(new DomainError("BACKEND_UNAVAILABLE", "Operation authorization capability is not available.", {
+        operation: "authorize",
+    }));
+}
+function checkpointCapabilityUnavailable() {
+    return failure(new DomainError("BACKEND_UNAVAILABLE", "Checkpoint evidence capability is not available.", {
+        operation: "checkpoint",
+    }));
+}
+function repositoryEvidenceCapabilityUnavailable(operation) {
+    return failure(new DomainError("BACKEND_UNAVAILABLE", "Repository evidence capability is not available.", { operation }));
+}
+function mutationCapabilityUnavailable(operation) {
+    return failure(new DomainError("BACKEND_UNAVAILABLE", "Governed Git mutation capability is not available.", { operation }));
+}
+function deniedAuthorization(decision) {
+    const code = decision.code === "ALLOWED" ? "OPERATION_REJECTED" : decision.code;
+    const diagnosticDetails = code === "INSUFFICIENT_CLAIM_MODE"
+        ? {
+            resource: decision.details.resource,
+            granted_modes: decision.details.grantedModes,
+        }
+        : {};
+    return failure(new DomainError(code, `Operation denied: ${code}.`, {
+        allowed: false,
+        schema_version: decision.schema_version,
+        operation: decision.operation,
+        required_access: decision.required_access,
+        repository: decision.repository,
+        worktree: decision.worktree,
+        branch: decision.branch,
+        session_id: decision.session_id,
+        owner_session_id: decision.owner_session_id,
+        requested_session_id: decision.requested_session_id,
+        state: decision.state,
+        resources: decision.resources,
+        ...diagnosticDetails,
+        details: decision.details,
+    }));
+}
 function emitFailure(mode, command, error, io) {
     io[mode === "json" ? "stdout" : "stderr"](renderFailure(mode, command, error));
     return error.exitCode;
@@ -261,14 +968,19 @@ export async function runCli(argv, dependencies = {}) {
     if (!parsed.ok)
         return emitFailure(mode, "cli", parsed.error, io);
     if (parsed.value.help) {
+        const spec = helpSpecFor(parsed.value.commandArguments);
         if (mode === "json")
-            io.stdout(renderSuccess(mode, "help", HELP_DATA));
+            io.stdout(renderSuccess(mode, "help", helpPayload(spec)));
         else
-            io.stdout(HELP_TEXT);
+            io.stdout(helpText(spec));
         return EXIT_CODES.success;
     }
     if (parsed.value.version) {
-        const payload = { version: dependencies.version ?? VERSION };
+        const payload = {
+            version: dependencies.version ?? VERSION,
+            contract_id: MACHINE_CONTRACT_ID,
+            contract_schema_version: MACHINE_CONTRACT_SCHEMA_VERSION,
+        };
         if (mode === "json")
             io.stdout(renderSuccess(mode, "version", payload));
         else
@@ -281,6 +993,13 @@ export async function runCli(argv, dependencies = {}) {
         io.stdout(HELP_TEXT);
         return EXIT_CODES.usage;
     }
+    if (parsed.value.commandArguments[0] === "capabilities") {
+        const capabilityOptions = noOptions(parsed.value.commandArguments.slice(1));
+        if (!capabilityOptions.ok)
+            return emitFailure(mode, "capabilities", capabilityOptions.error, io);
+        io.stdout(renderSuccess(mode, "capabilities", machineContract(dependencies.version ?? VERSION)));
+        return EXIT_CODES.success;
+    }
     const command = commandName(parsed.value.commandArguments);
     const cwd = dependencies.cwd ?? process.cwd();
     try {