nawabari 0.5.0 → 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,10 +164,12 @@ 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
 ```
@@ -185,7 +189,14 @@ the resolved parent of that session's worktree.
 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
@@ -198,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
@@ -363,8 +385,14 @@ differs.
   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. Both surfaces reuse one authority, so
-  a raw close rejection and `session inspect` never drift apart.
+  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.

package/dist/cli.js

@@ -48,13 +48,16 @@ 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>] [--integrated-revision <rev>]`,
+        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>" }),
@@ -63,6 +66,7 @@ const HELP_COMMANDS = [
             "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.",
         ],
     },
     {
@@ -88,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>",
@@ -116,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>",
@@ -159,27 +176,34 @@ 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>] [--integrated-revision <rev>]`,
+        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>" }),
@@ -187,6 +211,24 @@ const HELP_COMMANDS = [
         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.",
         ],
     },
     {
@@ -347,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) => ({
@@ -579,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
@@ -588,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")
@@ -745,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)
@@ -754,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)
@@ -805,7 +891,7 @@ async function executeCommand(commandArguments, dependencies) {
             return result.ok ? { ok: true, value: result.value } : result;
         }
         if (subcommand === "inspect") {
-            const parsed = parseOptions(rest, new Set(["--session", "--integrated-revision"]));
+            const parsed = parseTargetedOptions(rest, new Set(["--session", "--integrated-revision"]));
             if (!parsed.ok)
                 return parsed;
             if (dependencies.backend.sessionDiagnostic === undefined)
@@ -817,6 +903,15 @@ async function executeCommand(commandArguments, dependencies) {
             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);
@@ -827,7 +922,7 @@ async function executeCommand(commandArguments, dependencies) {
                     return selected;
                 return { ok: true, value: { session_id: selected.value.session_id } };
             }
-            const parsed = parseOptions(rest, new Set(subcommand === "close" ? ["--session", "--integrated-revision"] : ["--session"]));
+            const parsed = parseTargetedOptions(rest, new Set(subcommand === "close" ? ["--session", "--integrated-revision"] : ["--session"]));
             if (!parsed.ok)
                 return parsed;
             if (subcommand === "close") {
@@ -885,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)
@@ -894,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)
@@ -1151,6 +1246,11 @@ function sessionDiagnosticCapabilityUnavailable() {
         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 }));
 }