nawabari 0.4.1 → 0.6.0

package/README.md

@@ -94,6 +94,7 @@ The supported standalone sequence is:
 ```text
 session create -> session claim(s) -> authorize/checkpoint
 -> commit/push -> doctor (reconciliation) -> session close/gc
+-> explicit session discard only when the selected work is intentionally disposable
 ```
 
 The JSON envelope is one document on stdout. Success has `ok: true`, a
@@ -106,16 +107,17 @@ failure. Consumers must use these fields and codes, never human presentation.
 
 The result schemas expose the following identities:
 
-| Surface                | Versioned identities                                                             |
-| ---------------------- | -------------------------------------------------------------------------------- |
-| session lifecycle      | `session_id`, `repository`, `worktree`, `branch`, `state`                        |
-| claims                 | `claim_id`, `session_id`, `resource`, `mode`                                     |
-| authorization          | `operation`, `allowed`, `code`, `claim_ids`                                      |
-| checkpoint evidence    | `head`, `changed`, `staged`, `unstaged`, `untracked`, `in_claim`, `out_of_claim` |
-| repository evidence    | `session_id`, `base_revision`, `head`, `clean`, `paths.stats`, `evidence_hash`   |
-| bounded diff           | `from_revision`, `to_revision`, `paths`, `stats`, `patch`, `evidence_hash`       |
-| commit/push            | `commit_sha`, `remote`, `branch`, `target`, `relation`                           |
-| reconciliation/cleanup | `clean`, `issues`, `candidates`, `cleaned`, `blocked`, `recovery_hints`          |
+| Surface                | Versioned identities                                                                                                                |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| session lifecycle      | `session_id`, `repository`, `worktree`, `branch`, `state`                                                                           |
+| explicit discard       | `previous_head`, `worktree_removed`, `branch_removed`, `released_claims`, `final_state`, final `session.state`/`terminal_operation` |
+| claims                 | `claim_id`, `session_id`, `resource`, `mode`                                                                                        |
+| authorization          | `operation`, `allowed`, `code`, `claim_ids`                                                                                         |
+| checkpoint evidence    | `head`, `changed`, `staged`, `unstaged`, `untracked`, `in_claim`, `out_of_claim`                                                    |
+| repository evidence    | `session_id`, `base_revision`, `head`, `clean`, `paths.stats`, `evidence_hash`                                                      |
+| bounded diff           | `from_revision`, `to_revision`, `paths`, `stats`, `patch`, `evidence_hash`                                                          |
+| commit/push            | `commit_sha`, `remote`, `branch`, `target`, `relation`                                                                              |
+| reconciliation/cleanup | `clean`, `issues`, `candidates`, `cleaned`, `blocked`, `recovery_hints`                                                             |
 
 Git subprocesses are bounded at 10 seconds and 64 KiB of output; checkpoint
 evidence is bounded to 4,096 paths. `GIT_SPAWN_FAILED`, `GIT_TIMEOUT`,
@@ -162,24 +164,39 @@ machine identities; labels and branch names are separate display metadata.
 git nawabari session create --branch feature/example --worktree ../example-worktree --json
 git nawabari session id --json
 git nawabari session show --json
+git nawabari session show <session-id> --json
 git nawabari session list --json
 git nawabari status --json
 git nawabari guard --json
 git nawabari session close --json
+git nawabari session discard --session <session-id> --json
 git nawabari gc --dry-run --json
 git nawabari doctor --json
 ```
 
 `status --json` reports the resolved `managed_worktree_root` used when
-`session create` omits `--worktree`. `session create --help --json` describes
-all four create options as optional and reports defaults for branch, worktree,
-base (`HEAD`), and label.
+`session create` omits `--worktree` and `--worktree-root`. `session create
+--help --json` describes all create options as optional and reports defaults
+for branch, worktree, worktree root, base (`HEAD`), and label.
+
+`--worktree-root` selects only the parent directory for a new session
+worktree; Nawabari still derives the final worktree basename from its own
+session-naming contract. It is mutually exclusive with `--worktree`, the
+exact-path override. Every session record's `worktree_root` field reports
+the resolved parent of that session's worktree.
 
 `session create` provisions a dedicated worktree and mutable branch atomically
 under the repository-scoped mutation lock. The default/integration worktree
 and its protected branch cannot be session resources. `session id` and the
 other current-session commands resolve ownership from the current worktree;
-callers do not need to repeat the session ID.
+callers do not need to repeat the session ID for current-owner operations.
+
+Session-scoped commands use one target grammar: the canonical `--session <id>`
+option is accepted everywhere, and `show`, `inspect`, `claim`, `claims`,
+`release`, `update`, `close`, and `discard` also accept one positional
+`<session-id>` immediately after the subcommand. Supplying both forms is
+rejected as ambiguous. `session discard` always requires one explicit target
+and never infers the current worktree owner.
 
 Close is conservative. Dirty worktrees, ambiguous ownership, mismatched Git
 state, and commits not proven reachable from the integration branch block
@@ -192,6 +209,17 @@ every candidate that is not safe. Cleanup revalidates the physical worktree,
 branch, and `HEAD` observations immediately before each destructive Git
 operation.
 
+`session discard` is the sole explicit destructive abandonment path. It
+revalidates repository identity, the selected session, exact worktree/branch
+ownership, and session/worktree `HEAD` immediately before each Git mutation.
+It may destroy the selected session's unintegrated commits and uncommitted
+worktree contents, removes only that session's worktree/branch, releases only
+its claims, and records `terminal_operation: "discard"` plus the pre-discard
+`HEAD`. It never acts as an implicit fallback for `close`, `gc`, `doctor`, or
+reconciliation; sibling sessions remain untouched. A partial failure leaves a
+retryable closing record and a repeated discard converges or returns an
+explicit terminal idempotent result.
+
 Routine `session list` and `status` output excludes `closed` history and is
 limited to 64 records. Use `--all` (or `--history`) for an explicit complete
 history view; closed records remain persisted and are never silently deleted
@@ -321,6 +349,54 @@ Detached, corrupt, missing, or conflicting state fails closed. The guard does
 not install hooks and does not prevent direct filesystem writes outside
 Nawabari.
 
+## Actionable lifecycle rejections
+
+Stable codes are necessary but not sufficient for a caller to pick a safe
+next step without a second, separate inspection. For the codes below,
+Nawabari's `details` carry bounded, deterministic evidence and a
+`safeActions`/`safe_actions` list of stable, kebab-case next-action
+identifiers, in addition to the human-readable `message`. JSON and human
+output always render the identical underlying result; only the formatting
+differs.
+
+- **`RESOURCE_CLAIM_CONFLICT`** (`session claim`/`session update`,
+  `authorize`, `guard --operation`) reports the blocking claim
+  (`ownerClaimId`, `ownerResource`, `ownerMode`) and the blocking session's
+  canonical identity (`ownerSessionId`, `ownerWorktree`, `ownerBranch`, and
+  `ownerLabel` when the session has one) in the same result, so a caller
+  never needs a second `session list` scan to find the owner.
+- **`PROTECTED_WORKTREE`**/**`PROTECTED_BRANCH`** raised by a live command
+  (not by cleanup) add `phase: "execution"` and distinguish the current
+  (protected) execution context from the referenced `--session` target:
+  `requestedSessionId`, `targetWorktree`, `targetBranch`, and `targetState`
+  when that session exists. `safeActions` names the deterministic fix
+  (`run-from-managed-session-worktree`, `select-target-session-explicitly`)
+  instead of the unrelated cleanup-time hint.
+- **`INVALID_SESSION_ID`** stays machine-ID based: an invalid `--session`
+  value is never silently reinterpreted as a label. When it exactly and
+  unambiguously matches one active session's label, the result adds
+  `session_id_hint` (the canonical session ID) and
+  `session_label_match: "unique"` as a non-authoritative hint. An ambiguous
+  or absent label match never guesses: `session_label_match` reports
+  `"ambiguous"` (with `session_label_match_count`) or `"none"` instead.
+- **`RECOVERABLE_COMMITS`** raised by `session close` carries the same
+  `close_readiness`/`result_state` classification `session inspect` reports
+  for the identical state — `external_evidence_required` when ancestry alone
+  could not prove the branch safe and a `--integrated-revision` proof might
+  resolve it (e.g. after a squash/rebase merge), versus `blocked` when
+  supplied evidence failed to prove equivalence, versus `ambiguous` when Git
+  observation itself was inconclusive. For supplied evidence, bounded
+  `proofFailure` details distinguish an unauthoritative revision from a
+  tree-equivalence failure. The bounded evidence also includes
+  `currentSessionHead`, `suppliedIntegratedRevision`, `resolvedIntegrationSha`,
+  `lineageProof`/`authorityProof`, and `contentProof`. `safe_actions` includes
+  `discard-session` only as an explicit user choice; it does not authorize an
+  implicit cleanup fallback. Both surfaces reuse one authority, so a raw close
+  rejection and `session inspect` never drift apart.
+
+None of the above weakens fail-closed behavior, changes an error code's
+meaning, or performs any mutation while producing the rejection.
+
 ## Orchestrator integration
 
 An external orchestrator can create a session, capture the returned

package/dist/cli.js

@@ -26,14 +26,18 @@ const HELP_COMMANDS = [
                 value: "<name>",
                 default: "nawabari/session/<session_id>",
             }),
-            option("--worktree", "Managed worktree path; omitted uses the resolved repository-local root", {
+            option("--worktree", "Exact managed worktree path override; mutually exclusive with --worktree-root", {
                 value: "<path>",
                 default: "<managed_worktree_root>/<repository>-<session_id>",
             }),
+            option("--worktree-root", "Managed root to place the worktree under; Nawabari derives the final path. Mutually exclusive with --worktree", { value: "<path>", default: "resolved repository-local root" }),
             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."],
+        notes: [
+            "All create options are optional. Use status --json to discover managed_worktree_root.",
+            "--worktree and --worktree-root cannot be combined.",
+        ],
     },
     {
         name: "session id",
@@ -44,8 +48,26 @@ const HELP_COMMANDS = [
     {
         name: "session show",
         summary: "Show the current or selected session",
-        usage: `${CLI_NAME} session show [--session <id>]`,
+        usage: `${CLI_NAME} session show [<session-id>|--session <id>]`,
         options: [option("--session", "Select a session instead of the current worktree owner", { value: "<id>" })],
+        notes: [
+            "Target grammar is consistent: an optional first positional <session-id> is an alias for --session <id>; do not supply both.",
+        ],
+    },
+    {
+        name: "session inspect",
+        summary: "Report side-effect-free close/cleanup readiness for a session",
+        usage: `${CLI_NAME} session inspect [<session-id>|--session <id>] [--integrated-revision <rev>]`,
+        options: [
+            option("--session", "Select a session instead of the current worktree owner", { value: "<id>" }),
+            option("--integrated-revision", "Externally evidenced revision to test for non-ancestry (squash/rebase) integration; independently re-verified via exact Git tree-object equivalence, never trusted blindly", { value: "<rev>" }),
+        ],
+        notes: [
+            "Read-only: never mutates session, claim, Git, worktree, branch, or registry state. Repeated calls are idempotent.",
+            "Derived from the same authoritative close/cleanup Git evidence as session close; does not duplicate or diverge from that logic.",
+            "Nawabari never queries GitHub or any remote provider; --integrated-revision only names a local revision for Nawabari to independently verify.",
+            "Target grammar: optional first positional <session-id> is an alias for --session <id>; do not supply both.",
+        ],
     },
     {
         name: "session run",
@@ -70,18 +92,21 @@ const HELP_COMMANDS = [
     {
         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>]`,
+        usage: `${CLI_NAME} session claim [<session-id>] --resource <path-or-glob> --mode <read|write|exclusive-write>`,
         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>" }),
         ],
+        notes: [
+            "Target grammar: optional first positional <session-id> is an alias for --session <id>; do not supply both.",
+        ],
     },
     {
         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>]`,
+        usage: `${CLI_NAME} session update [<session-id>] --resource <path-or-glob> --mode <read|write|exclusive-write> [--resource <path-or-glob> --mode <read|write|exclusive-write> ...]`,
         options: [
             option("--resource", "Repository-relative resource; repeatable, each paired with the --mode immediately after it", {
                 value: "<path-or-glob>",
@@ -98,33 +123,43 @@ const HELP_COMMANDS = [
             "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.",
+            "Target grammar: optional first positional <session-id> is an alias for --session <id>; do not supply both.",
         ],
     },
     {
         name: "session claims",
         summary: "List canonical resource claims",
-        usage: `${CLI_NAME} session claims [--session <id>]`,
+        usage: `${CLI_NAME} session claims [<session-id>|--session <id>]`,
         options: [option("--session", "Select a session; omitted lists all claims", { value: "<id>" })],
+        notes: [
+            "Target grammar: optional first positional <session-id> is an alias for --session <id>; do not supply both.",
+        ],
     },
     {
         name: "session release",
         summary: "Release resource claims",
-        usage: `${CLI_NAME} session release [--session <id>] [--claim-id <id>]`,
+        usage: `${CLI_NAME} session release [<session-id>|--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>" }),
         ],
+        notes: [
+            "Target grammar: optional first positional <session-id> is an alias for --session <id>; do not supply both.",
+        ],
     },
     {
         name: "resource claim",
         summary: "Add a canonical resource claim (alias)",
-        usage: `${CLI_NAME} resource claim --resource <path-or-glob> --mode <read|write|exclusive-write>`,
+        usage: `${CLI_NAME} resource claim [<session-id>|--session <id>] --resource <path-or-glob> --mode <read|write|exclusive-write>`,
         options: [],
+        notes: [
+            "Target grammar matches session claim: optional first positional <session-id> is an alias for --session <id>; do not supply both.",
+        ],
     },
     {
         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>]`,
+        usage: `${CLI_NAME} resource update [<session-id>|--session <id>] --resource <path-or-glob> --mode <read|write|exclusive-write> [--resource <path-or-glob> --mode <read|write|exclusive-write> ...]`,
         options: [
             option("--resource", "Repository-relative resource; repeatable, each paired with the --mode immediately after it", {
                 value: "<path-or-glob>",
@@ -141,28 +176,60 @@ const HELP_COMMANDS = [
             "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.",
+            "Target grammar matches session update: optional first positional <session-id> is an alias for --session <id>; do not supply both.",
         ],
     },
     {
         name: "resource list",
         summary: "List canonical resource claims (alias)",
-        usage: `${CLI_NAME} resource list [--session <id>]`,
+        usage: `${CLI_NAME} resource list [<session-id>|--session <id>]`,
         options: [option("--session", "Select a session; omitted lists all claims", { value: "<id>" })],
+        notes: [
+            "Target grammar: optional first positional <session-id> is an alias for --session <id>; do not supply both.",
+        ],
     },
     {
         name: "resource release",
         summary: "Release resource claims (alias)",
-        usage: `${CLI_NAME} resource release [--session <id>] [--claim-id <id>]`,
+        usage: `${CLI_NAME} resource release [<session-id>|--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>" }),
         ],
+        notes: [
+            "Target grammar: optional first positional <session-id> is an alias for --session <id>; do not supply both.",
+        ],
     },
     {
         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>" })],
+        usage: `${CLI_NAME} session close [<session-id>|--session <id>] [--integrated-revision <rev>]`,
+        options: [
+            option("--session", "Select a session instead of the current worktree owner", { value: "<id>" }),
+            option("--integrated-revision", "Externally evidenced revision proving non-ancestry (squash/rebase) integration; independently re-verified via exact Git tree-object equivalence, never trusted blindly", { value: "<rev>" }),
+        ],
+        notes: [
+            "Ordinary ancestry-based close remains the cheap/default path and requires no flags.",
+            "Nawabari never queries GitHub or any remote provider; --integrated-revision only names a local revision for Nawabari to independently verify.",
+            "Target grammar: optional first positional <session-id> is an alias for --session <id>; do not supply both.",
+        ],
+    },
+    {
+        name: "session discard",
+        summary: "Explicitly discard one selected session and its owned resources",
+        usage: `${CLI_NAME} session discard <session-id>|--session <id>`,
+        options: [
+            option("--session", "Required explicit target; the current session is never inferred", {
+                value: "<id>",
+                required: true,
+            }),
+        ],
+        notes: [
+            "Destructive and explicit: unintegrated commits and uncommitted work in the selected owned worktree may be destroyed.",
+            "Discard never changes close, gc, doctor, reconciliation, or integration-lineage proof behavior.",
+            "Use exactly one target form: positional <session-id> or --session <id>; do not supply both.",
+            "Machine JSON mode is non-interactive and deterministic.",
+        ],
     },
     {
         name: "authorize",
@@ -322,6 +389,13 @@ function helpPayload(spec) {
             commit_options: optionsFor("commit"),
             push_options: optionsFor("push"),
             gc_options: optionsFor("gc"),
+            session_targeting: {
+                canonical: "--session <id>",
+                positional_alias: "<session-id> as the first argument after a session-scoped subcommand",
+                commands: ["show", "inspect", "claim", "claims", "release", "update", "close", "discard"],
+                ambiguity: "supplying both positional and --session is rejected",
+                discard_requires_explicit_target: true,
+            },
         };
     }
     const options = spec.options.map((candidate) => ({
@@ -431,6 +505,7 @@ function parseOptions(arguments_, allowed) {
         session_id: null,
         branch: null,
         worktree: null,
+        worktree_root: null,
         base: null,
         label: null,
         resource: null,
@@ -456,6 +531,7 @@ function parseOptions(arguments_, allowed) {
         patch: false,
         max_bytes: null,
         max_hunks: null,
+        integrated_revision: null,
     };
     let dryRun = false;
     for (let index = 0; index < arguments_.length; index += 1) {
@@ -501,6 +577,8 @@ function parseOptions(arguments_, allowed) {
             options.branch = value;
         else if (name === "--worktree")
             options.worktree = value;
+        else if (name === "--worktree-root")
+            options.worktree_root = value;
         else if (name === "--base")
             options.base = value;
         else if (name === "--label")
@@ -539,6 +617,8 @@ function parseOptions(arguments_, allowed) {
             options.max_bytes = value;
         else if (name === "--max-hunks")
             options.max_hunks = value;
+        else if (name === "--integrated-revision")
+            options.integrated_revision = value;
     }
     if (options.apply && dryRun) {
         return failure(usageError("INVALID_ARGUMENT", "--apply and --dry-run cannot be used together."));
@@ -548,6 +628,34 @@ function parseOptions(arguments_, allowed) {
 function noOptions(arguments_) {
     return parseOptions(arguments_, new Set());
 }
+/** One unambiguous positional alias shared by every session-targeted command. */
+function splitPositionalSessionTarget(arguments_) {
+    const first = arguments_[0];
+    if (first === undefined || first.startsWith("-")) {
+        return { ok: true, value: { sessionId: null, arguments: arguments_ } };
+    }
+    return { ok: true, value: { sessionId: first, arguments: arguments_.slice(1) } };
+}
+function parseTargetedOptions(arguments_, allowed, required = false) {
+    const positional = splitPositionalSessionTarget(arguments_);
+    if (!positional.ok)
+        return positional;
+    const parsed = parseOptions(positional.value.arguments, allowed);
+    if (!parsed.ok)
+        return parsed;
+    if (positional.value.sessionId !== null && parsed.value.session_id !== null) {
+        return failure(usageError("INVALID_ARGUMENT", "Specify a session target either positionally or with --session, not both.", {
+            option: "--session",
+        }));
+    }
+    parsed.value.session_id = positional.value.sessionId ?? parsed.value.session_id;
+    if (required && parsed.value.session_id === null) {
+        return failure(usageError("MISSING_ARGUMENT", "An explicit session target is required; use <session-id> or --session <id>.", {
+            option: "--session",
+        }));
+    }
+    return parsed;
+}
 /**
  * `update` accepts a complete desired claim set as repeated
  * `--resource <path> --mode <mode>` pairs. Pairing is by strict local
@@ -557,26 +665,35 @@ function noOptions(arguments_) {
  * with the wrong mode.
  */
 function parseClaimReplacementPairs(arguments_) {
+    const positional = splitPositionalSessionTarget(arguments_);
+    if (!positional.ok)
+        return positional;
     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]);
+    sessionId = positional.value.sessionId;
+    const targetArguments = positional.value.arguments;
+    for (let index = 0; index < targetArguments.length; index += 1) {
+        const { name, inlineValue } = optionParts(targetArguments[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];
+        const value = inlineValue ?? targetArguments[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")
+        if (name === "--session") {
+            if (sessionId !== null) {
+                return failure(usageError("INVALID_ARGUMENT", "Specify a session target either positionally or with --session, not both."));
+            }
             sessionId = value;
+        }
         else if (name === "--repository")
             repository = value;
         else if (name === "--resource")
@@ -714,7 +831,7 @@ async function executeCommand(commandArguments, dependencies) {
             return result.ok ? { ok: true, value: result.value } : result;
         }
         if (subcommand === "claims") {
-            const parsed = parseOptions(rest, new Set(["--session"]));
+            const parsed = parseTargetedOptions(rest, new Set(["--session"]));
             if (!parsed.ok)
                 return parsed;
             if (dependencies.backend.listClaims === undefined)
@@ -723,7 +840,7 @@ async function executeCommand(commandArguments, dependencies) {
             return result.ok ? { ok: true, value: result.value } : result;
         }
         if (subcommand === "release") {
-            const parsed = parseOptions(rest, new Set(["--session", "--claim-id"]));
+            const parsed = parseTargetedOptions(rest, new Set(["--session", "--claim-id"]));
             if (!parsed.ok)
                 return parsed;
             if (dependencies.backend.releaseClaims === undefined)
@@ -735,12 +852,16 @@ async function executeCommand(commandArguments, dependencies) {
             return result.ok ? { ok: true, value: result.value } : result;
         }
         if (subcommand === "create") {
-            const parsed = parseOptions(rest, new Set(["--branch", "--worktree", "--base", "--label"]));
+            const parsed = parseOptions(rest, new Set(["--branch", "--worktree", "--worktree-root", "--base", "--label"]));
             if (!parsed.ok)
                 return parsed;
+            if (parsed.value.worktree !== null && parsed.value.worktree_root !== null) {
+                return failure(usageError("INVALID_ARGUMENT", "--worktree and --worktree-root cannot be used together."));
+            }
             const options = {
                 branch: parsed.value.branch,
                 worktree: parsed.value.worktree,
+                worktree_root: parsed.value.worktree_root,
                 base: parsed.value.base,
                 label: parsed.value.label,
             };
@@ -769,6 +890,28 @@ async function executeCommand(commandArguments, dependencies) {
             });
             return result.ok ? { ok: true, value: result.value } : result;
         }
+        if (subcommand === "inspect") {
+            const parsed = parseTargetedOptions(rest, new Set(["--session", "--integrated-revision"]));
+            if (!parsed.ok)
+                return parsed;
+            if (dependencies.backend.sessionDiagnostic === undefined)
+                return sessionDiagnosticCapabilityUnavailable();
+            const options = {
+                session_id: parsed.value.session_id,
+                integrated_revision: parsed.value.integrated_revision,
+            };
+            const result = await dependencies.backend.sessionDiagnostic(context, options);
+            return result.ok ? { ok: true, value: result.value } : result;
+        }
+        if (subcommand === "discard") {
+            const parsed = parseTargetedOptions(rest, new Set(["--session"]), true);
+            if (!parsed.ok)
+                return parsed;
+            if (dependencies.backend.discardSession === undefined)
+                return sessionDiscardCapabilityUnavailable();
+            const result = await dependencies.backend.discardSession(context, parsed.value.session_id);
+            return result.ok ? { ok: true, value: result.value } : result;
+        }
         if (subcommand === "id" || subcommand === "show" || subcommand === "close") {
             if (subcommand === "id") {
                 const parsed = noOptions(rest);
@@ -779,11 +922,14 @@ async function executeCommand(commandArguments, dependencies) {
                     return selected;
                 return { ok: true, value: { session_id: selected.value.session_id } };
             }
-            const parsed = parseOptions(rest, new Set(["--session"]));
+            const parsed = parseTargetedOptions(rest, new Set(subcommand === "close" ? ["--session", "--integrated-revision"] : ["--session"]));
             if (!parsed.ok)
                 return parsed;
             if (subcommand === "close") {
-                const closeOptions = { session_id: parsed.value.session_id };
+                const closeOptions = {
+                    session_id: parsed.value.session_id,
+                    integrated_revision: parsed.value.integrated_revision,
+                };
                 const selected = await dependencies.backend.closeSession(context, closeOptions);
                 return selected.ok ? { ok: true, value: selected.value } : selected;
             }
@@ -834,7 +980,7 @@ async function executeCommand(commandArguments, dependencies) {
             return result.ok ? { ok: true, value: result.value } : result;
         }
         if (resourceSubcommand === "list" || resourceSubcommand === "claims") {
-            const parsed = parseOptions(rest, new Set(["--session"]));
+            const parsed = parseTargetedOptions(rest, new Set(["--session"]));
             if (!parsed.ok)
                 return parsed;
             if (dependencies.backend.listClaims === undefined)
@@ -843,7 +989,7 @@ async function executeCommand(commandArguments, dependencies) {
             return result.ok ? { ok: true, value: result.value } : result;
         }
         if (resourceSubcommand === "release") {
-            const parsed = parseOptions(rest, new Set(["--session", "--claim-id"]));
+            const parsed = parseTargetedOptions(rest, new Set(["--session", "--claim-id"]));
             if (!parsed.ok)
                 return parsed;
             if (dependencies.backend.releaseClaims === undefined)
@@ -1095,6 +1241,16 @@ function checkpointCapabilityUnavailable() {
         operation: "checkpoint",
     }));
 }
+function sessionDiagnosticCapabilityUnavailable() {
+    return failure(new DomainError("BACKEND_UNAVAILABLE", "Session diagnostic capability is not available.", {
+        operation: "session.inspect",
+    }));
+}
+function sessionDiscardCapabilityUnavailable() {
+    return failure(new DomainError("BACKEND_UNAVAILABLE", "Session discard capability is not available.", {
+        operation: "session.discard",
+    }));
+}
 function repositoryEvidenceCapabilityUnavailable(operation) {
     return failure(new DomainError("BACKEND_UNAVAILABLE", "Repository evidence capability is not available.", { operation }));
 }
@@ -1130,6 +1286,57 @@ function emitFailure(mode, command, error, io) {
     io[mode === "json" ? "stdout" : "stderr"](renderFailure(mode, command, error));
     return error.exitCode;
 }
+/** Extract the raw `--session` value a rejected INVALID_SESSION_ID carried, regardless of which command path threw it. */
+function invalidSessionIdQuery(error) {
+    const details = error.details;
+    if (details === null)
+        return null;
+    if (typeof details.sessionId === "string")
+        return details.sessionId;
+    const nested = details.details;
+    if (nested === null || typeof nested !== "object" || Array.isArray(nested))
+        return null;
+    const nestedSessionId = nested.sessionId;
+    return typeof nestedSessionId === "string" ? nestedSessionId : null;
+}
+/**
+ * `--session` stays machine-ID based: an invalid value is never silently
+ * reinterpreted as a label. But when it exactly and unambiguously matches
+ * one active session's label, expose that session's canonical ID as a
+ * bounded, non-authoritative hint instead of forcing a separate `session
+ * list` round trip. Ambiguous or absent matches never guess.
+ */
+async function enrichInvalidSessionIdError(error, backend, context) {
+    if (error.code !== "INVALID_SESSION_ID")
+        return error;
+    const query = invalidSessionIdQuery(error);
+    if (query === null || query.length === 0)
+        return error;
+    const listing = await backend.listSessions(context, { include_closed: false, limit: MAX_SESSION_LIST_LIMIT });
+    if (!listing.ok)
+        return error;
+    const matches = listing.value.sessions.filter((session) => session.state === "active" && session.label === query);
+    const hint = matches.length === 1
+        ? {
+            session_label_query: query,
+            session_label_match: "unique",
+            session_id_hint: matches[0].session_id,
+            safe_actions: ["retry-with-session-id-hint"],
+        }
+        : matches.length > 1
+            ? {
+                session_label_query: query,
+                session_label_match: "ambiguous",
+                session_label_match_count: matches.length,
+                safe_actions: ["disambiguate-session-label", "list-sessions"],
+            }
+            : {
+                session_label_query: query,
+                session_label_match: "none",
+                safe_actions: ["list-sessions"],
+            };
+    return new DomainError(error.code, error.message, { ...error.details, ...hint }, error.exitCode);
+}
 export async function runCli(argv, dependencies = {}) {
     const io = dependencies.io ?? defaultCliIO();
     const delimiter = argv.indexOf("--");
@@ -1182,8 +1389,10 @@ export async function runCli(argv, dependencies = {}) {
             sandboxProbe: dependencies.sandboxProbe,
             sandboxRuntimeLayout: dependencies.sandboxRuntimeLayout,
         });
-        if (!result.ok)
-            return emitFailure(mode, command, result.error, io);
+        if (!result.ok) {
+            const enriched = await enrichInvalidSessionIdError(result.error, backend, sessionContext(cwd));
+            return emitFailure(mode, command, enriched, io);
+        }
         io.stdout(renderSuccess(mode, command, result.value));
         if ((command === "session run" || command === "session exec") &&
             typeof result.value.exit_code === "number" &&