nawabari 0.2.0 → 0.4.1

package/dist/cli.js

@@ -1,96 +1,385 @@
 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";
+import { resolveSandboxExecutionRequest, runSandboxedCommand, } from "./domain/sandbox.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 run",
+        summary: "Run one command inside the protected session sandbox",
+        usage: `${CLI_NAME} session run [--session <id>] -- <command> [args...]`,
+        options: [option("--session", "Select the active owned session", { value: "<id>" })],
+        notes: [
+            "The -- terminator is mandatory. The command is passed as argv without a shell, and protected execution is fail-closed.",
+            "session exec is an alias.",
+        ],
+    },
+    {
+        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: "Atomically replace a session's complete resource claim set",
+        usage: `${CLI_NAME} session update --resource <path-or-glob> --mode <read|write|exclusive-write> [--resource <path-or-glob> --mode <read|write|exclusive-write> ...] [--session <id>]`,
+        options: [
+            option("--resource", "Repository-relative resource; repeatable, each paired with the --mode immediately after it", {
+                value: "<path-or-glob>",
+                required: true,
+            }),
+            option("--mode", "Mode for the --resource immediately before it; repeatable", {
+                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>" }),
+        ],
+        notes: [
+            "The desired claim set fully replaces the session's current claims in one updateClaims() transaction; " +
+                "on any invalid or conflicting claim the prior set is left unchanged.",
+            "Each --resource must be immediately followed by its own --mode; pairing is positional adjacency, not flag order.",
+        ],
+    },
+    {
+        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: "Atomically replace a session's complete resource claim set (alias)",
+        usage: `${CLI_NAME} resource update --resource <path-or-glob> --mode <read|write|exclusive-write> [--resource <path-or-glob> --mode <read|write|exclusive-write> ...] [--session <id>]`,
+        options: [
+            option("--resource", "Repository-relative resource; repeatable, each paired with the --mode immediately after it", {
+                value: "<path-or-glob>",
+                required: true,
+            }),
+            option("--mode", "Mode for the --resource immediately before it; repeatable", {
+                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>" }),
+        ],
+        notes: [
+            "The desired claim set fully replaces the session's current claims in one updateClaims() transaction; " +
+                "on any invalid or conflicting claim the prior set is left unchanged.",
+            "Each --resource must be immediately followed by its own --mode; pairing is positional adjacency, not flag order.",
+        ],
+    },
+    {
+        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[0] === "session" && commandArguments[1] === "exec"
+            ? "session run"
+            : 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);
 }
@@ -99,7 +388,17 @@ function parseGlobalArguments(argv) {
     let help = false;
     let version = false;
     const commandArguments = [];
+    let passthrough = false;
     for (const argument of argv) {
+        if (passthrough) {
+            commandArguments.push(argument);
+            continue;
+        }
+        if (argument === "--") {
+            passthrough = true;
+            commandArguments.push(argument);
+            continue;
+        }
         if (argument === "--json") {
             json = true;
         }
@@ -138,6 +437,7 @@ function parseOptions(arguments_, allowed) {
         resources: [],
         operation: null,
         message: null,
+        message_pattern: null,
         remote: null,
         remote_branch: null,
         mode: null,
@@ -146,6 +446,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 +463,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 +479,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 +513,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 +525,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 +548,129 @@ function parseOptions(arguments_, allowed) {
 function noOptions(arguments_) {
     return parseOptions(arguments_, new Set());
 }
+/**
+ * `update` accepts a complete desired claim set as repeated
+ * `--resource <path> --mode <mode>` pairs. Pairing is by strict local
+ * adjacency (each `--resource` must be immediately followed by its own
+ * `--mode`, with no other option able to intervene) rather than by
+ * parallel-array position, so argv order can never associate a resource
+ * with the wrong mode.
+ */
+function parseClaimReplacementPairs(arguments_) {
+    let sessionId = null;
+    let repository = null;
+    const pairs = [];
+    let pendingResource = null;
+    for (let index = 0; index < arguments_.length; index += 1) {
+        const { name, inlineValue } = optionParts(arguments_[index]);
+        if (name !== "--session" && name !== "--repository" && name !== "--resource" && name !== "--mode") {
+            return failure(usageError("INVALID_ARGUMENT", `Unknown option: ${name}.`, { option: name }));
+        }
+        if (pendingResource !== null && name !== "--mode") {
+            return failure(usageError("INVALID_ARGUMENT", `${name} cannot appear between --resource and its --mode; only --mode is permitted immediately after --resource.`, { option: name }));
+        }
+        const value = inlineValue ?? arguments_[index + 1];
+        if (value === undefined || value === "" || (inlineValue === null && value.startsWith("-"))) {
+            return failure(usageError("MISSING_ARGUMENT", `${name} requires a value.`, { option: name }));
+        }
+        if (inlineValue === null)
+            index += 1;
+        if (name === "--session")
+            sessionId = value;
+        else if (name === "--repository")
+            repository = value;
+        else if (name === "--resource")
+            pendingResource = value;
+        else {
+            if (pendingResource === null) {
+                return failure(usageError("INVALID_ARGUMENT", "--mode must be immediately preceded by its own --resource.", {
+                    option: "--mode",
+                }));
+            }
+            pairs.push({ resource: pendingResource, mode: value });
+            pendingResource = null;
+        }
+    }
+    if (pendingResource !== null) {
+        return failure(usageError("MISSING_ARGUMENT", "--resource must be immediately followed by --mode.", { option: "--mode" }));
+    }
+    if (pairs.length === 0) {
+        return failure(usageError("MISSING_ARGUMENT", "--resource requires a value.", { option: "--resource" }));
+    }
+    return { ok: true, value: { session_id: sessionId, repository, pairs } };
+}
+/**
+ * `claim` accepts exactly one `--resource`/`--mode` pair. Reuses the same
+ * strict-adjacency scan as `update` so a second `--resource`/`--mode` (in
+ * any order) is rejected outright instead of silently overwriting the
+ * first pair (last-wins).
+ */
+function parseSingleClaimPair(arguments_) {
+    const parsed = parseClaimReplacementPairs(arguments_);
+    if (!parsed.ok)
+        return parsed;
+    if (parsed.value.pairs.length > 1) {
+        return failure(usageError("INVALID_ARGUMENT", "claim accepts exactly one --resource/--mode pair.", {
+            pair_count: parsed.value.pairs.length,
+        }));
+    }
+    const [pair] = parsed.value.pairs;
+    return {
+        ok: true,
+        value: {
+            session_id: parsed.value.session_id,
+            repository: parsed.value.repository,
+            resource: pair.resource,
+            mode: pair.mode,
+        },
+    };
+}
+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 };
 }
@@ -223,25 +684,33 @@ 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 (subcommand === "claim") {
+            const parsed = parseSingleClaimPair(rest);
             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 = {
+            if (dependencies.backend.claimResources === undefined)
+                return claimCapabilityUnavailable(subcommand);
+            const result = await dependencies.backend.claimResources(context, {
                 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 result.ok ? { ok: true, value: result.value } : result;
+        }
+        if (subcommand === "update") {
+            const parsed = parseClaimReplacementPairs(rest);
+            if (!parsed.ok)
+                return parsed;
+            if (dependencies.backend.updateClaims === undefined)
                 return claimCapabilityUnavailable(subcommand);
-            const result = await operation.call(dependencies.backend, context, options);
+            const result = await dependencies.backend.updateClaims(context, {
+                session_id: parsed.value.session_id,
+                repository: parsed.value.repository,
+                claims: parsed.value.pairs.map((pair) => ({
+                    resource: pair.resource,
+                    mode: pair.mode,
+                })),
+            });
             return result.ok ? { ok: true, value: result.value } : result;
         }
         if (subcommand === "claims") {
@@ -278,6 +747,28 @@ async function executeCommand(commandArguments, dependencies) {
             const result = await dependencies.backend.createSession(context, options);
             return result.ok ? { ok: true, value: result.value } : result;
         }
+        if (subcommand === "run" || subcommand === "exec") {
+            const delimiter = rest.indexOf("--");
+            if (delimiter === -1) {
+                return failure(usageError("MISSING_ARGUMENT", "session run requires a -- terminator before the command."));
+            }
+            const parsed = parseOptions(rest.slice(0, delimiter), new Set(["--session"]));
+            if (!parsed.ok)
+                return parsed;
+            const command = rest[delimiter + 1];
+            if (command === undefined || command.length === 0) {
+                return failure(usageError("MISSING_ARGUMENT", "session run requires a command after --."));
+            }
+            const request = await resolveSandboxExecutionRequest(dependencies.backend, context, { session_id: parsed.value.session_id, enforce: true }, dependencies.sandboxProbe, dependencies.sandboxRuntimeLayout);
+            if (!request.ok)
+                return request;
+            const runner = dependencies.sandboxRunner ?? runSandboxedCommand;
+            const result = await runner(request.value, {
+                command,
+                args: rest.slice(delimiter + 2),
+            });
+            return result.ok ? { ok: true, value: result.value } : result;
+        }
         if (subcommand === "id" || subcommand === "show" || subcommand === "close") {
             if (subcommand === "id") {
                 const parsed = noOptions(rest);
@@ -300,33 +791,48 @@ 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 (resourceSubcommand === "claim") {
+            const parsed = parseSingleClaimPair(rest);
             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)
+            if (dependencies.backend.claimResources === undefined)
                 return claimCapabilityUnavailable(resourceSubcommand);
-            const result = await operation.call(dependencies.backend, context, {
+            const result = await dependencies.backend.claimResources(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 === "update") {
+            const parsed = parseClaimReplacementPairs(rest);
+            if (!parsed.ok)
+                return parsed;
+            if (dependencies.backend.updateClaims === undefined)
+                return claimCapabilityUnavailable(resourceSubcommand);
+            const result = await dependencies.backend.updateClaims(context, {
+                session_id: parsed.value.session_id,
+                repository: parsed.value.repository,
+                claims: parsed.value.pairs.map((pair) => ({
+                    resource: pair.resource,
+                    mode: pair.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)
@@ -386,8 +892,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 +959,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 +994,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 +1078,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 +1095,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 +1122,7 @@ function deniedAuthorization(decision) {
         requested_session_id: decision.requested_session_id,
         state: decision.state,
         resources: decision.resources,
+        ...diagnosticDetails,
         details: decision.details,
     }));
 }
@@ -559,15 +1132,18 @@ function emitFailure(mode, command, error, io) {
 }
 export async function runCli(argv, dependencies = {}) {
     const io = dependencies.io ?? defaultCliIO();
-    const mode = argv.includes("--json") ? "json" : "human";
+    const delimiter = argv.indexOf("--");
+    const globalArguments = delimiter === -1 ? argv : argv.slice(0, delimiter);
+    const mode = globalArguments.includes("--json") ? "json" : "human";
     const parsed = parseGlobalArguments(argv);
     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) {
@@ -599,10 +1175,23 @@ export async function runCli(argv, dependencies = {}) {
     const cwd = dependencies.cwd ?? process.cwd();
     try {
         const backend = dependencies.backend ?? createLocalSessionBackend();
-        const result = await executeCommand(parsed.value.commandArguments, { backend, cwd });
+        const result = await executeCommand(parsed.value.commandArguments, {
+            backend,
+            cwd,
+            sandboxRunner: dependencies.sandboxRunner,
+            sandboxProbe: dependencies.sandboxProbe,
+            sandboxRuntimeLayout: dependencies.sandboxRuntimeLayout,
+        });
         if (!result.ok)
             return emitFailure(mode, command, result.error, io);
         io.stdout(renderSuccess(mode, command, result.value));
+        if ((command === "session run" || command === "session exec") &&
+            typeof result.value.exit_code === "number" &&
+            result.value.exit_code !== 0) {
+            return result.value.exit_code >= 1 && result.value.exit_code <= 255
+                ? result.value.exit_code
+                : EXIT_CODES.rejected;
+        }
         return EXIT_CODES.success;
     }
     catch {