nawabari 0.13.0 → 0.15.0

package/README.md

@@ -2,386 +2,126 @@
   <img src="./docs/assets/readme/nawabari-hero.webp" alt="Nawabari — Git Worktree Isolation." width="100%">
 </p>
 
-<p align="center">
-  <a href="https://github.com/yohn-jp/nawabari/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/yohn-jp/nawabari/actions/workflows/ci.yml/badge.svg"></a>
-  <a href="https://www.npmjs.com/package/nawabari"><img alt="npm" src="https://img.shields.io/npm/v/nawabari"></a>
-  <a href="https://www.npmjs.com/package/nawabari"><img alt="Node" src="https://img.shields.io/node/v/nawabari"></a>
-  <a href="./LICENSE"><img alt="License" src="https://img.shields.io/npm/l/nawabari"></a>
-</p>
-
 # Nawabari
 
-Nawabari is a local governance layer for parallel coding agents. It gives each agent session an owned Git worktree and branch, records which repository resources that session may use, and checks those boundaries before governed mutations.
-
-It is for teams and tools that need several agents to work in one repository without silently sharing a worktree, overwriting one another's files, or guessing whether a session is safe to close. Nawabari is local-first: the session registry, Git observations, and authorization decisions do not require GitHub, `gh`, a network connection, or a particular agent runtime.
-
-This README describes the current 0.10.x product model. It is an overview and navigation surface, not a copy of generated contracts or implementation history.
-
-The canonical routine-use workflow is one machine-authority path for both people
-and agents:
+Nawabari is a machine-local runtime for coding-agent sessions. It binds each session to an owned Git worktree and
+mutable branch, checks declared access and coordination boundaries, and supports protected execution on Linux.
+Repository ownership remains independent for each local Git repository; a shared remote does not merge local authority.
 
-1. Create a managed session with explicit initial claims.
-2. Declare any required auxiliary repository-local state explicitly.
-3. Inspect the session and its claims.
-4. Run governed work and mutations through the claim and evidence surfaces.
-5. Handle claim conflicts from machine-readable evidence and typed lifecycle actions.
-6. Reconcile stale or inconsistent physical state through the canonical operation.
-7. Close or discard according to the lifecycle authority.
-8. Confirm convergence with `doctor` and garbage-collection observation.
+Nawabari owns local execution and recovery, not task selection, semantic orchestration, or GitHub Issue/PR governance.
+Local ownership operations do not require GitHub, `gh`, or a particular agent runtime. Explicit Git push/fetch operations
+and caller programs may use the network.
 
-Nawabari governs operations routed through Nawabari. A normal governed session is an ownership and authorization boundary, not an operating-system or filesystem sandbox. A process with ambient filesystem permissions can still edit another worktree directly.
+The [accepted Target Architecture](docs/architecture/index.md) defines the design to which the product must converge.
+The [implementation status](docs/architecture/implementation-status.md) distinguishes that target from the current code.
+This documentation adoption does not implement parking, change claim enforcement, repair Control Server authentication,
+add a singleton lease, or strengthen filesystem durability by itself.
 
-## Install
+## Install and discover
 
-Node.js 24 or newer is required.
+Use Node.js 24 or newer.
 
 ```bash
 npm install -g nawabari
 nawabari --version
-git nawabari --help
-```
-
-The package installs both `nawabari` and `git-nawabari`; `git nawabari ...` works as Git's external subcommand.
-
-## Canonical routine-use workflow
-
-Run from the repository's integration worktree. The following bootstrap uses the
-same public option shape as the packed routine-use certification. Omit the
-auxiliary declaration when the session needs no declared repository-local state;
-do not replace it with an arbitrary host path.
-
-```bash
 nawabari capabilities --json
-nawabari doctor --json
-
-auxiliary_state='{"source":{"kind":"repository-local","path":".codegraph/ignored"},"target":{"kind":"managed-worktree","path":".codegraph/ignored"},"mode":"copy","durability":"durable"}'
-created=$(git nawabari session create \
-  --branch feature/example \
-  --resource README.md --mode write \
-  --auxiliary-state "$auxiliary_state" \
-  --json)
-session_id=$(printf '%s' "$created" | jq -r .session_id)
-worktree=$(printf '%s' "$created" | jq -r .worktree)
-
-(cd "$worktree" && git nawabari session show --session "$session_id" --json)
-(cd "$worktree" && git nawabari session claims --session "$session_id" --json)
-(cd "$worktree" && git nawabari session inspect --session "$session_id" --schema-version 2 --json)
-
-(cd "$worktree" && git nawabari session claim --session "$session_id" --resource contract-lifecycle.txt --mode exclusive-write --json)
-(cd "$worktree" && git nawabari authorize --session "$session_id" --operation source-write --resource contract-lifecycle.txt --json)
-(cd "$worktree" && "$EDITOR" contract-lifecycle.txt)
-(cd "$worktree" && git nawabari evidence snapshot --session "$session_id" --json)
-(cd "$worktree" && git nawabari checkpoint --session "$session_id" --json)
-(cd "$worktree" && git nawabari commit --session "$session_id" --message "Exercise governed lifecycle" --resource contract-lifecycle.txt --json)
-(cd "$worktree" && git nawabari push --session "$session_id" --remote origin --branch feature/example --resource contract-lifecycle.txt --create-upstream --json)
+git nawabari session create --help --json
 ```
 
-`session create` provisions the new worktree under `<repository-parent>/.nawabari/worktrees` by default (discoverable via `status --json` as `managed_worktree_root`). Nawabari creates that managed subdirectory on first default placement. New exact `--worktree` paths must be under the reported root; an absolute path directly under the repository parent remains accepted for compatibility with older callers and persisted sessions.
-
-The initial-claim grammar is `--resource <path-or-glob> --mode <read|write|exclusive-write>` and the pair may be repeated. Each resource is paired with its own mode. The parser also permits zero pairs for backward compatibility, but the canonical routine path declares at least one initial claim. Initial claims are committed atomically with the new session, worktree, and branch. A conflict returns a machine-readable failure such as `RESOURCE_CLAIM_CONFLICT` and does not leave a partially established session or claim set.
-
-Resource-claim enforcement is disabled by default for a new session: `commit`/`push` authorization does not require the session to hold a resource claim for its own session-owned operations. Pass `--enforce-claims` to `session create` to opt that session into the previous claim-authorization behavior, including `MISSING_RESOURCE_CLAIM`/`INSUFFICIENT_CLAIM_MODE` denials and existing claim-mode compatibility rules. Worktree ownership, branch ownership, and `RESOURCE_CLAIM_CONFLICT` protection against another session's active claim remain enforced either way.
-
-### Working-set artifacts
-
-For a bounded session, supply **both** `--execution-scope-file` and `--candidate-working-set-file` to `session create`. The JSON below illustrates the versioned fields accepted by the [canonical parsers](./src/working-set.ts). Replace the identity, revision, digest, and paths with values from the implementation authorization and the repository being bootstrapped. `repositoryHost` and `repositoryId` must agree between the two artifacts and the authorization; `repository` is optional in the execution scope and required in the candidate. The candidate `revision` and execution-scope `base.revision` must equal the session's resolved Git base revision (40 or 64 hexadecimal characters). `base.branch` names that base; `base.freshness` and the top-level execution-scope `branch` are optional bounded strings.
-
-`execution-scope.json`:
-
-```json
-{
-  "version": 1,
-  "kind": "implementation-execution-scope",
-  "authorization": {
-    "version": 1,
-    "kind": "implementation-authorization",
-    "contractVersion": 1,
-    "implementation": {
-      "repositoryHost": "github.com",
-      "repositoryId": "1329799765",
-      "repository": "yohn-jp/nawabari",
-      "number": 659
-    },
-    "governedBodyDigest": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
-  },
-  "repository": { "repositoryHost": "github.com", "repositoryId": "1329799765", "repository": "yohn-jp/nawabari" },
-  "base": { "branch": "main", "revision": "e0e3c4376c9d70c87f24c7211b5ded1f3d58a983" },
-  "scope": {
-    "readOnly": ["README.md", "src/**"],
-    "write": [],
-    "create": [],
-    "delete": [],
-    "deny": []
-  }
-}
-```
+The package installs `nawabari` and `git-nawabari`; Git discovers the latter as `git nawabari`.
+Use installed help and capabilities for exact supported commands, schemas, options, and failure codes.
+Package version, persisted schema version, claim schema version, and public contract identity are distinct.
 
-`candidate-working-set.json`:
-
-```json
-{
-  "kind": "candidate-working-set",
-  "schemaVersion": 1,
-  "workingSetId": "implementation-659-candidate-v1",
-  "repository": { "repositoryHost": "github.com", "repositoryId": "1329799765", "repository": "yohn-jp/nawabari" },
-  "revision": "e0e3c4376c9d70c87f24c7211b5ded1f3d58a983",
-  "entries": [
-    {
-      "state": "required",
-      "target": { "kind": "file", "locator": "README.md" },
-      "reason": { "id": "implementation-659", "summary": "Read the public contract" },
-      "evidence": [{ "artifact": "implementation-659", "reference": "working-set-bootstrap" }]
-    }
-  ]
-}
-```
+## Local session workflow
 
-The execution scope is the maximum authority: all five arrays (`readOnly`, `write`, `create`, `delete`, `deny`) are required, contain canonical repository-relative path selectors, and may be empty. The authorization's `implementation.number` is a positive integer and `governedBodyDigest` is a 64-character lowercase hexadecimal digest from the governing authorization. `implementation.repository` is optional. Candidate `entries` may be empty; each entry requires `state` (`required`, `supporting`, `verification`, or `unresolved`), `target` (`kind`: `file`, `symbol`, `test`, or `unresolved`; plus a nonempty `locator`), `reason` (`id` and `summary`), and an `evidence` array of `{ "artifact", "reference" }` objects. An `unresolved` state requires an `unresolved` target kind; concrete states require a concrete target kind. Candidate entries describe need, not permission. Unknown fields are rejected; the parser in `src/working-set.ts` is the contract authority.
+From the repository's integration worktree, create a session and retain the returned identity and worktree path.
+The default session does not require resource claims for otherwise-valid session-owned operations.
+Worktree/branch ownership, applicable scope restrictions, and conflicts with another session's claims remain enforced.
 
 ```bash
-nawabari session create --base main --execution-scope-file execution-scope.json \
-  --candidate-working-set-file candidate-working-set.json --json
+nawabari session create --branch feature/example --json
 nawabari session show --session "$session_id" --json
-nawabari session scope expand --help --json
-nawabari session scope expand --session "$session_id" --repository 1329799765 \
-  --repository-host github.com --revision "$revision" \
-  --execution-scope-file execution-scope.json --path src/new-context.ts \
-  --operation READONLY --reason 'Needed for current task' --json
-```
-
-Read `working_set.revision` from `session show --json` before expansion. A granted expansion advances that revision and appends `working_set.history`; a stale revision or different execution-scope provenance is rejected without changing the working set. The requested path must be within the original execution-scope maximum and outside its `deny` selectors. READONLY expansion grants no WRITE, CREATE, or DELETE authority. Mutation still follows the existing claim and scope checks. If a resource handoff reports `Destination maximum scope is unavailable`, inspect the destination and explicitly expand its scope first; retry `session handoff` with fresh claim-set generation through the normal handoff command. Handoff never expands destination scope itself.
-
-The packed auxiliary-state declaration above is the bounded `copy` form: a `repository-local` source is copied to a `managed-worktree` target with `durability: durable`. It is an explicit, repeatable, allowlisted capability. It does not discover ignored state, project process-local sockets/PID files/logs, shadow Git-tracked paths, or expose arbitrary host filesystem paths. Auxiliary-state projection is separate from `SessionRuntimeProjection`: the former copies declared repository-local durable state for a managed worktree; the latter describes explicit runtime material and filesystem visibility for protected execution. Auxiliary state does not change the runtime projection.
-
-The create operation is atomic, but a caller must treat an uncertain result carefully. If JSON reports `REGISTRY_DURABILITY_UNCERTAIN`, re-read the reported session and claims before retrying. If the exact original declaration is already present, follow `bootstrap_retry.next_action: inspect-established-session` and inspect that `session_id`; if another declaration owns the worktree or branch, follow `bootstrap_retry.next_action: inspect-blocking-session`. Nawabari never silently adopts an existing owner. A retry is appropriate only after the authoritative state proves that the requested bootstrap was not established.
-
-`--all-claimed` is an explicit resource selector. It resolves safely observed Git-changed paths covered by qualifying claims; it does not bypass claim authorization. Use repeated `--resource <path>` when an explicit path list is preferable.
-
-After reviewing and integrating the session branch through the caller's normal local Git/provider process:
-
-```bash
-git nawabari session inspect --session "$session_id" --json
-git nawabari session close --session "$session_id" --json
+nawabari session inspect --session "$session_id" --schema-version 2 --json
 ```
 
-Close is conservative. Unintegrated commits, dirty worktrees, ambiguous Git state, and ownership mismatches remain blocked. For a squash or rebase merge, pass an exact local `--integrated-revision <rev>` so Nawabari can independently re-verify the content.
-
-If the lifecycle result exposes a recoverable blocker, follow its typed `next_action`/`next_actions` entry. `reconcile-physical-state` is the non-mutating observation action (its command is `doctor`). Its explicit apply action is `reconcile-physical-state-apply`, and its exact command is:
+Set `session_id` and the working directory from the create result; do not use another session's worktree.
+For explicit claim enforcement, declare it at creation:
 
 ```bash
-git nawabari session reconcile --session "$owner_session_id" --apply --json
+nawabari session create --branch feature/claimed --enforce-claims \
+  --resource README.md --mode write --json
 ```
 
-The session ID must be the blocking owner reported by the machine result. A successful apply returns `operation: "reconcile-apply"`, `action.action_id: "reconcile-physical-state-apply"`, and a completed outcome; the owner is terminalized and its claims are released only when the existing lifecycle and physical-state evidence authorizes that transition. Retry the blocked claim only after this result succeeds.
-
-After every session reaches its terminal lifecycle result, confirm convergence from
-the repository integration worktree:
+Commit and push are explicit governed operations with concrete resources. On claim-enforced sessions, their required
+claim strength is discovered from the operation contract. Integration/review decisions remain caller-owned.
+After integration, inspect and close. A blocked close does not authorize discard.
 
 ```bash
-git nawabari gc --dry-run --json
-git nawabari doctor --json
-```
-
-## Authority model
-
-Each boundary has one job and one local authority. README summarizes the product contract; executable code and machine-readable projections remain authoritative for exact schemas, transitions, and failure vocabularies.
-
-| Boundary               | What it answers                                                                                    | Typical commands                                                       |
-| ---------------------- | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
-| Session lifecycle      | Which session owns a worktree/branch and whether it can safely progress or terminate               | `session create`, `session inspect`, `session close`                   |
-| Resource Claims        | Which session may access a canonical repository resource and at what mode                          | `session claim`, `session claims`, `session update`, `session release` |
-| Mutation authorization | Whether a concrete operation has sufficient claims and no conflicting owner                        | `guard`, `authorize`, `commit`, `push`                                 |
-| Repository evidence    | What Git can observe about revisions, paths, changes, ancestry, and bounded diffs                  | `checkpoint`, `evidence snapshot`, `diff`                              |
-| Auxiliary state        | Whether explicitly declared durable repository-local state may be copied into the managed worktree | `session create --auxiliary-state`, `capabilities`                     |
-| Reconciliation/cleanup | Whether observed physical state permits a lifecycle recovery or cleanup action                     | `session inspect`, `session reconcile`, `doctor`, `gc`                 |
-| Protected execution    | Whether a command runs inside the opt-in Linux process/filesystem boundary                         | `session run`, `session exec`, `session shell`, `doctor`               |
-
-Claims are not task labels and do not encode GitHub or agent semantics. `write` permits ordinary path changes; `exclusive-write` is required for finalizing operations such as commit and push. Conflicting or ambiguous claims fail closed.
-
-The default governance path does not install hooks and does not prevent direct filesystem writes outside Nawabari. Its guarantee is that Nawabari-routed operations consult authoritative session, Git, and claim state before mutation.
-
-Nawabari's authority ends at local session ownership, claims, Git evidence, and the lifecycle of the managed worktree and branch. Task meaning, Issue/PR state, review decisions, and provider/GitHub state remain outside that authority.
-
-### Claim conflict and physical recovery
-
-`RESOURCE_CLAIM_CONFLICT` does not always mean stale state. A healthy owner is reported with `ownerState: "active"`; the certified contention path exposes `inspect-blocking-session` and `wait-for-conflicting-claim-release` safe actions without a reconciliation `nextAction`. Inspect the owner and wait for the legitimate claim release; do not remove another session's claim.
-
-For a stale or inconsistent owner, the machine result instead carries physical and lifecycle evidence such as `ownerPhysicalState: "prunable-missing"`, `ownerLifecycleState: "stale-inconsistent"`, and the typed `nextAction.actionId: "reconcile-physical-state"`. Inspect it first:
-
-```bash
-git nawabari session inspect --session "$owner_session_id" --schema-version 2 --json
-```
-
-Then use the explicit apply operation shown above and retry the original claim after it completes. Age or a missing path alone is not destructive authority. The packed test removes a worktree only as external fault injection; supported recovery does not involve editing the session registry manually or deleting a raw Git worktree.
-
-## Session and resource lifecycle
-
-The normal path is:
-
-```text
-session create (explicit initial claims)
-      ↓
-inspect session/claims → claim/authorize → checkpoint → commit or push
-      ↓                                              ↓
-  inspect readiness                         integrate the branch
-      ↓                                              ↓
-session close or discard  ←─────────────────────────┘
-       ↓
-doctor + gc --dry-run convergence check
-```
-
-If work is not integrated, `session inspect` reports bounded blockers and safe next actions. Discard is never an implicit fallback for close or garbage collection.
-
-The Session lifecycle is backed by the executable XState authority in 0.10.x and exposed through public state, contract, and manifest projections. Consumers use those projections rather than internal machine nodes or actor objects.
-
-### Claims
-
-Claims are canonical repository-relative resource records attached to a session. Supported modes are `read`, `write`, and `exclusive-write`. The canonical routine path establishes its first claim during `session create`; later additions, transitions, and releases use the existing claim surfaces.
-
-```bash
-git nawabari session claim --session "$session_id" --resource src/example.ts --mode exclusive-write --json
-git nawabari session claims --session "$session_id" --json
-git nawabari session update --session "$session_id" --resource src/example.ts --mode exclusive-write --resource test/example.test.ts --mode write --if-generation 1 --json
-git nawabari session release --session "$session_id" --all --force --json
-```
-
-Resource aliases are discoverable through help. Use `--help --json` rather than copying option metadata into an integration.
-
-Claim modes are cumulative. The canonical operation requirements are derived from the operation authorization policy and are shown by `session claim --help`:
-
-- `read`: no governed operation
-- `write`: `source-write`, `stage`
-- `exclusive-write`: `source-write`, `stage`, `commit`, `branch-mutation`, `push`, `cleanup`
-
-The policy requires `exclusive-write` for operations that finalize or remove shared state. This mapping is documentation of the executable authority, not a second claim policy; integrations should discover the current values from help or the machine contract.
-
-### Inspect, close, discard, and garbage collection
-
-`session inspect` is read-only and uses the same close/cleanup evidence as `session close`. Use `--schema-version 2` when consuming the single-authority lifecycle and action projection.
-
-```bash
-git nawabari session inspect --session "$session_id" --json
-git nawabari session discard --session "$session_id" --preview --json
-```
-
-`session discard` requires an explicit session ID and may destroy unintegrated commits and uncommitted work in that session's worktree. Preview reports bounded destructive scope without mutation. Actual discard revalidates repository, worktree, branch, `HEAD`, and registry ownership before destructive steps.
-
-When the caller intentionally abandons the session, apply that explicit
-decision with `git nawabari session discard --session "$session_id" --json`.
-Discard is not an automatic fallback for a blocked close.
-
-`gc --dry-run` reports stale candidates and blockers. `gc --apply` only cleans candidates passing the same safety checks; elapsed age alone is diagnostic suspicion, not destructive authority. `doctor` reports prerequisite and reconciliation state without silently repairing ownership. Use the typed lifecycle action and explicit `session reconcile` operation for supported stale/inconsistent-owner recovery; `doctor` does not silently repair it.
-
-## Governed Git work
-
-`guard` and `authorize` are separate read-only boundaries:
-
-- `guard` without an operation verifies the current physical worktree, branch, and session ownership/context. It does not evaluate resource claims.
-- `authorize` evaluates a named operation against concrete resources, using the canonical operation policy and active claims. It does not grant or persist claims.
-- `guard --operation <name> --resource <path>` remains a compatibility convenience for the combined claim-aware check. Use `authorize` when the operation decision itself is the intended boundary.
-
-The operation vocabulary is discoverable from the CLI and includes `source-write`, `stage`, `commit`, `branch-mutation`, `push`, and `cleanup`.
-
-`checkpoint` and `evidence snapshot` describe Git-observable facts only. They do not infer task meaning, Issue ownership, or review status. `diff` requires explicit concrete paths and bounds optional patch output.
-
-```bash
-git nawabari commit --session "$session_id" --message "Update example" --resource src/example.ts --json
-git nawabari commit --session "$session_id" --message "Update example" --all-claimed --json
-git nawabari push --session "$session_id" --remote origin --branch feature/example --all-claimed --json
-```
-
-## Optional protected execution
-
-Protected execution is an opt-in Linux-only mode beneath the existing Nawabari session and claim authority. It does not create a second session identity and does not turn ordinary `session create` work into a sandbox.
-
-```bash
-git nawabari session run --session "$session_id" --runtime-policy strict -- node worker.js
-git nawabari session exec --session "$session_id" -- npm test
-git nawabari session shell --session "$session_id" --runtime-policy compatibility
-```
-
-The `--` terminator is mandatory. The command is passed as argv and is not interpreted by a shell. The canonical profile gives the child a private root, `/tmp`, `/proc`, HOME, and cache state, mounts only the owned worktree read-write, and does not expose sibling worktrees or Nawabari control paths. Network mode is explicitly `inherited`, not isolated. Required Linux capabilities fail closed when unavailable; optional Landlock and cgroups v2 provide defense in depth when available.
-
-Protected execution defaults to the strict `development` runtime profile. Only declared Node, Git, and the deterministic `ls` baseline utility are projected through `/nawabari/bin`; `/usr`, `/bin`, `/nix/store`, the host home, and local user-tool directories are not implicitly visible. pnpm is an explicit opt-in development requirement. Compatibility is available only through the explicit `--runtime-policy compatibility` option.
-
-```bash
-git nawabari doctor --json
+nawabari session close --session "$session_id" --json
+nawabari gc --dry-run --json
+nawabari doctor --json
 ```
 
-See [Standalone Linux compatibility](docs/standalone-linux-compatibility.md) for platform-specific details.
+See [current CLI workflows](docs/reference/cli-workflows.md) for bounded working sets, auxiliary state, claims,
+Git mutation, explicit discard, reconciliation, and bootstrap retry. Target park/resume semantics are documented in
+[session lifecycle](docs/architecture/session-lifecycle.md), not advertised here as implemented commands.
 
-## CLI and machine-readable discovery
+## Execution guarantees
 
-The installed CLI is the primary integration surface. Discover its contract rather than hard-coding presentation output:
+An ordinary session is an ownership boundary, not automatic OS isolation. Direct edits by a host process with ambient
+permissions remain outside the mediated-operation guarantee.
+Protected execution requires the selected Linux sandbox and explicit runtime material. Managed execution additionally
+uses durable execution ownership, launch admission, and owned process/cgroup evidence. These are separate capabilities;
+a generic sandbox-ready result does not prove managed-runtime readiness.
 
 ```bash
-nawabari capabilities --json
-nawabari --version --json
-nawabari session create --help --json
-nawabari session inspect --help --json
-nawabari session reconcile --help --json
-nawabari commit --help --json
+nawabari session run --session "$session_id" --runtime-policy strict -- node worker.js
 ```
 
-`capabilities --json` works without a Git repository. The top-level contract is `nawabari.standalone-execution.v1`, schema version `1`; Resource Claim meaning is separately versioned as `nawabari.resource-claims.v2`. Package version alone is not a compatibility decision. The capability projection publishes the initial-claim grammar and retry vocabulary, auxiliary-state contract, lifecycle action IDs, and the `session reconcile --session <id> --apply` apply arguments used above.
-
-JSON mode emits one bounded document on stdout. Consumers should use machine-readable fields and stable codes rather than parse human-oriented text.
+Strict execution does not silently fall back to host PATH, HOME, broad mounts, or compatibility mode.
+Network mode remains `inherited`; filesystem isolation does not imply isolation from host loopback services.
+See [runtime/process](docs/architecture/runtime-process.md), [runtime reference](docs/reference/runtime-projection.md),
+and [security policy](SECURITY.md) before interpreting a capability or isolation claim.
 
-The command surface includes Session lifecycle, Resource Claims, authorization/evidence, governed Git commit/push, reconciliation/discovery, and protected execution. Use `--help --json` and `capabilities --json` for the authoritative inventory. Human-readable guidance and agent integrations use these same command and action identifiers; there is no separate human or agent workflow.
-
-`src/cli-command-registry.ts` is the single canonical authority for that surface: every command/option name is a `CommandId`/`OptionId` literal type derived directly from the registry data (not hand-typed), and `--help`, `capabilities`, and the executable dispatcher's own accepted-flag parsing all read that same data. There is no second command or option table to keep in sync.
-
-### Optional machine-local Control Server
+## Optional local Control Server
 
 ```bash
-nawabari server [--port <port>]
+nawabari server
+nawabari server --port 47472
 ```
 
-`nawabari server` runs one foreground Control Server and built-in Web UI at `http://127.0.0.1:47471/` (default port `47471`; `--port` selects another; an occupied port fails instead of choosing another endpoint). The listener binds IPv4 loopback `127.0.0.1` only and the bind address is not configurable. Stop it with Ctrl-C or `SIGTERM`.
-
-One listener serves every locally known Nawabari repository. Repository discovery uses a machine-local locator catalog (`$XDG_STATE_HOME/nawabari/control-repositories.json`, default `~/.local/state/nawabari/`) that holds only repository identity (common Git directory) and worktree path; `session create` and `server` record the current repository when it already has a Nawabari registry. The catalog is discovery metadata, not authority: each request reopens that repository's own backend, and each repository's registry, lifecycle, claims, runtime and filesystem authority stay independent.
+The current foreground server binds only `127.0.0.1`, defaults to port `47471`, and serves known repositories through one
+browser endpoint. CLI and TUI work without it. Stop it with Ctrl-C or SIGTERM.
 
-The HTTP v1 API is `GET /api/v1/health`, `GET /api/v1/repositories`, `GET /api/v1/repositories/:repositoryKey/snapshot`, `GET /api/v1/repositories/:repositoryKey/sessions/:sessionId`, and `POST /api/v1/repositories/:repositoryKey/sessions/:sessionId/actions`. Reads re-project the canonical `RepositoryRuntimeSnapshot`; actions accept only the typed `session action` contract (`action_id`, `token`, `confirmation`) and delegate to the repository's `SessionActionDispatcher`, so stale evidence fails closed (HTTP 409) and `discard-session` still needs the authoritative preview plus explicit confirmation. No route executes command text.
+**Current limitation:** the implementation audited for this adoption bootstraps its control token into the unauthenticated
+root document. With inherited host networking, this is not an isolation boundary against untrusted local/protected
+processes. Do not treat concurrent untrusted workloads and this server as a securely separated operator interface.
+The accepted target requires trusted-host-only credential delivery; that repair remains implementation work.
+Different ports also do not currently enforce the accepted machine/user singleton requirement.
 
-Every API request needs the `x-nawabari-control-token` header. The token is random per start, bootstrapped only into the same-origin root document, and never printed, logged, persisted, or put in URLs. Requests with an unexpected `Host` or a foreign `Origin` are rejected, no CORS headers are sent, and actions accept bounded `application/json` bodies only. The Web UI polls every 3 seconds and has a manual refresh; it offers only the actions listed by the current canonical diagnostic. The server is optional: every other command, including `nawabari ui`, keeps calling the backend directly.
+The [control-surfaces contract](docs/architecture/control-surfaces.md) defines authentication, lifecycle, discovery,
+concurrency, and projection boundaries without turning this optional server into a remote control plane.
 
-## Stable package exports
-
-Node consumers can use public projections without spawning the CLI:
+## Public Node projections
 
 ```js
-import {
-  availableNawabariCommands,
-  classifyNawabariState,
-  getNawabariSessionStateSnapshot,
-  nawabariTransitionDecision,
-} from "nawabari/state";
-
+import { getNawabariSessionStateSnapshot } from "nawabari/state";
 import { nawabariMachineContract } from "nawabari/contract";
-
-import { generateNawabariProductStateManifest, serializeNawabariProductStateManifest } from "nawabari/manifest";
+import { generateNawabariProductStateManifest } from "nawabari/manifest";
 ```
 
-`nawabari/state` provides transport-neutral lifecycle projection and read-only observation of an existing session. `nawabari/contract` provides the installed machine-contract projection. `nawabari/manifest` provides the deterministic Product State Manifest projection.
-
-These exports do not grant mutation authority and do not expose raw XState machines, actor references, internal state-node IDs, private context, or `dist/` deep imports. Mutations still go through authoritative runtime paths. See [XState state architecture](docs/architecture/xstate-state-architecture.md).
-
-## Further reading
+These exports expose read/classification/contract projections, not mutation permission or raw XState actors.
+Do not deep-import private `dist` modules as a supported API.
 
-- [XState state architecture](docs/architecture/xstate-state-architecture.md): lifecycle authority, public projections, and integration boundaries.
-- [Standalone Linux compatibility](docs/standalone-linux-compatibility.md): protected-execution compatibility and conformance details.
-- [Release notes](docs/releases/): version-specific changes and migration context.
-- [Contributing](CONTRIBUTING.md): development workflow and repository conventions.
-- [Security policy](SECURITY.md): vulnerability reporting.
+## Documentation and development
 
-## Development
+Start with the [documentation map](docs/index.md), [contribution workflow](CONTRIBUTING.md), and
+[release history](docs/releases/). Development uses the exact `packageManager` declaration in `package.json`.
 
 ```bash
 pnpm install --frozen-lockfile
-pnpm run format:check
-pnpm run lint
-pnpm run typecheck
-pnpm test
+pnpm run verify
 ```
 
-`pnpm run verify` runs the complete repository validation, including package and workflow checks.
+Verification includes package and environment-dependent proofs. A missing sandbox, runtime material, or delegated cgroup
+is not a successful security test. See the [proof matrix](docs/architecture/verification-provenance.md).

package/dist/cli-command-registry.d.ts

@@ -51,6 +51,66 @@ export declare const GLOBAL_HELP_OPTIONS: readonly [{
  * second copy.
  */
 declare const REGISTRY_DATA: readonly [{
+    readonly name: "verification snapshot";
+    readonly summary: "Read the current owned session verification policy fence";
+    readonly usage: "nawabari verification snapshot --session <id>";
+    readonly options: readonly [{
+        name: "--session";
+        description: string;
+    } & {
+        readonly value: "<id>";
+        readonly required: true;
+    }];
+    readonly notes: readonly ["Read-only; the returned snapshot grants no execution authority and is revalidated by the execution owner."];
+}, {
+    readonly name: "verification execute";
+    readonly summary: "Execute a source-bound verifier through the owned protected session";
+    readonly usage: "nawabari verification execute --request-file <path>";
+    readonly options: readonly [{
+        name: "--request-file";
+        description: string;
+    } & {
+        readonly value: "<path>";
+        readonly required: true;
+    }];
+    readonly notes: readonly ["Uses strict managed admission and a read-only invocation-local profile. Unknown currentness or cleanup cannot pass; there is no unmanaged fallback."];
+}, {
+    readonly name: "verification candidate-paths";
+    readonly summary: "Resolve deterministic owner-bound candidate bundle transfer paths";
+    readonly usage: "nawabari verification candidate-paths --request-file <path>";
+    readonly options: readonly [{
+        name: "--request-file";
+        description: string;
+    } & {
+        readonly value: "<path>";
+        readonly required: true;
+    }];
+    readonly notes: readonly ["Read-only; requires the exact current session snapshot and returns only paths derived from the owned worktree and candidate identities."];
+}, {
+    readonly name: "verification stage-candidate";
+    readonly summary: "Stage an exact Git candidate into the owned session verifier working set";
+    readonly usage: "nawabari verification stage-candidate --request-file <path>";
+    readonly options: readonly [{
+        name: "--request-file";
+        description: string;
+    } & {
+        readonly value: "<path>";
+        readonly required: true;
+    }];
+    readonly notes: readonly ["Imports only the declared current bundle through strict managed execution after an exact session snapshot CAS.", "The request contains no filesystem path; the bundle location is derived from the owned session worktree and SHA-256 identity."];
+}, {
+    readonly name: "verification release-candidate";
+    readonly summary: "Drain the owned session and release one verified candidate scratch tree";
+    readonly usage: "nawabari verification release-candidate --request-file <path>";
+    readonly options: readonly [{
+        name: "--request-file";
+        description: string;
+    } & {
+        readonly value: "<path>";
+        readonly required: true;
+    }];
+    readonly notes: readonly ["Requires the exact current owner snapshot, waits for closed-admission owned-scope emptiness, and removes only the clean deterministic candidate source subtree.", "Dirty, nested, symlinked, wrong-owner, or unexpected recoverable candidate data blocks release and remains available for recovery."];
+}, {
     readonly name: "session create";
     readonly summary: "Request a new Nawabari session";
     readonly usage: string;
@@ -317,7 +377,7 @@ declare const REGISTRY_DATA: readonly [{
     } & {
         readonly value: "<action-id>";
         readonly required: true;
-        readonly values: readonly ["retain-session", "supply-exact-integrated-revision", "retry-close-with-bounded-integration-fetch", "discard-session", "reconcile-physical-state"];
+        readonly values: readonly import("./domain/session-actions.js").SessionActionId[];
     }, {
         name: "--token";
         description: string;
@@ -708,7 +768,7 @@ declare const REGISTRY_DATA: readonly [{
 }, {
     readonly name: "session close";
     readonly summary: "Close the current or selected session";
-    readonly usage: "nawabari session close [<session-id>|--session <id>] [--integrated-revision <rev>] [--fetch-remote <name> --fetch-branch <branch>]";
+    readonly usage: "nawabari session close [<session-id>|--session <id>] [--drain-policy <wait|terminate>] [--integrated-revision <rev>] [--fetch-remote <name> --fetch-branch <branch>]";
     readonly options: readonly [{
         name: "--session";
         description: string;
@@ -729,8 +789,15 @@ declare const REGISTRY_DATA: readonly [{
         description: string;
     } & {
         readonly value: "<branch>";
+    }, {
+        name: "--drain-policy";
+        description: string;
+    } & {
+        readonly value: "<wait|terminate>";
+        readonly default: "wait";
+        readonly values: readonly ["wait", "terminate"];
     }];
-    readonly notes: readonly ["Ordinary ancestry-based close remains the cheap/default path and requires no flags.", "Network access is never implicit; --fetch-remote and --fetch-branch are accepted only with a full lowercase --integrated-revision SHA.", "Fetch updates only a disposable internal proof ref with no tags, FETCH_HEAD, tracking-ref, or local integration-branch changes; remote tip races fail closed.", "Nawabari never calls provider APIs such as GitHub; only explicit --fetch-remote/--fetch-branch options connect to the configured Git remote.", "Target grammar: optional first positional <session-id> is an alias for --session <id>; do not supply both."];
+    readonly notes: readonly ["Ordinary ancestry-based close remains the cheap/default path and requires no flags.", "The default drain policy waits; terminate is explicit and targets only exact owned execution scopes after session admission is closed and ownership is revalidated.", "Network access is never implicit; --fetch-remote and --fetch-branch are accepted only with a full lowercase --integrated-revision SHA.", "Fetch updates only a disposable internal proof ref with no tags, FETCH_HEAD, tracking-ref, or local integration-branch changes; remote tip races fail closed.", "Nawabari never calls provider APIs such as GitHub; only explicit --fetch-remote/--fetch-branch options connect to the configured Git remote.", "Target grammar: optional first positional <session-id> is an alias for --session <id>; do not supply both."];
 }, {
     readonly name: "session discard";
     readonly summary: "Explicitly discard one selected session and its owned resources";