nawabari 0.2.0 → 0.3.0

package/dist/cli.js

@@ -1,96 +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 claim        Add a canonical resource claim",
-    "  session update       Replace a session's resource claims",
-    "  session claims       List canonical resource claims",
-    "  session release      Release resource claims",
-    "  session close        Close the current or selected session",
-    "  authorize            Authorize an operation against concrete claims",
-    "  checkpoint           Capture bounded Git execution evidence",
-    "  commit               Commit explicit claim-authorized resources",
-    "  push                 Push the owned branch to an explicit target",
-    "  status               Show Nawabari session status",
-    "  guard [--session id] Authorize the current worktree or operation",
-    "  gc                   Detect or clean eligible stale sessions",
-    "  doctor               Check local Nawabari prerequisites",
-    "  capabilities         Describe the standalone CLI/JSON contract",
-    "  --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>",
-    "  session claim|update --session <id> --resource <path-or-glob> --mode <read|write|exclusive-write>",
-    "  session claims|release --session <id> [--claim-id <id>]",
-    "  authorize --session <id> --operation <name> --resource <path> [--resource <path>]",
-    "  checkpoint [--session <id>]",
-    "  commit --message <final-message> --resource <path> [--resource <path>] [--session <id>]",
-    "  push --remote <name> --branch <name> --resource <path> [--create-upstream] [--force] [--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 claim",
-        "session update",
-        "session claims",
-        "session release",
-        "resource claim",
-        "resource update",
-        "resource list",
-        "resource release",
-        "session close",
-        "authorize",
-        "checkpoint",
-        "commit",
-        "push",
-        "status",
-        "guard",
-        "gc",
-        "doctor",
-        "capabilities",
-    ],
-    options: ["--json", "--help", "--version"],
-    session_options: [
-        "--branch",
-        "--worktree",
-        "--base",
-        "--label",
-        "--session",
-        "--resource",
-        "--mode",
-        "--claim-id",
-        "--repository",
-    ],
-    authorization_options: ["--session", "--operation", "--resource"],
-    checkpoint_options: ["--session"],
-    commit_options: ["--session", "--message", "--resource"],
-    push_options: ["--session", "--resource", "--remote", "--branch", "--remote-branch", "--force", "--create-upstream"],
-    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);
 }
@@ -138,6 +387,7 @@ function parseOptions(arguments_, allowed) {
         resources: [],
         operation: null,
         message: null,
+        message_pattern: null,
         remote: null,
         remote_branch: null,
         mode: null,
@@ -146,6 +396,16 @@ function parseOptions(arguments_, allowed) {
         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) {
@@ -153,7 +413,13 @@ function parseOptions(arguments_, allowed) {
         if (!allowed.has(name)) {
             return failure(usageError("INVALID_ARGUMENT", `Unknown option: ${name}.`, { option: name }));
         }
-        if (name === "--apply" || name === "--dry-run" || name === "--force" || name === "--create-upstream") {
+        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 }));
             }
@@ -163,8 +429,14 @@ function parseOptions(arguments_, allowed) {
                 dryRun = true;
             else if (name === "--force")
                 options.force = true;
-            else
+            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];
@@ -191,6 +463,8 @@ function parseOptions(arguments_, allowed) {
             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")
@@ -201,6 +475,20 @@ function parseOptions(arguments_, allowed) {
             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."));
@@ -210,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 };
 }
@@ -300,10 +634,13 @@ 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 }));
@@ -386,8 +723,59 @@ async function executeCommand(commandArguments, dependencies) {
         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"]));
+        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) {
@@ -402,6 +790,7 @@ async function executeCommand(commandArguments, dependencies) {
             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;
     }
@@ -436,10 +825,13 @@ async function executeCommand(commandArguments, dependencies) {
         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") {
@@ -517,6 +909,8 @@ function commandName(commandArguments) {
         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) {
@@ -532,11 +926,20 @@ function checkpointCapabilityUnavailable() {
         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,
@@ -550,6 +953,7 @@ function deniedAuthorization(decision) {
         requested_session_id: decision.requested_session_id,
         state: decision.state,
         resources: decision.resources,
+        ...diagnosticDetails,
         details: decision.details,
     }));
 }
@@ -564,10 +968,11 @@ 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) {