nawabari 0.2.0 → 0.4.1

package/README.md

@@ -5,10 +5,51 @@ agents. It gives each active session one exclusively owned worktree and one
 mutable branch. It works without GitHub, `gh`, a network connection, Mottainai,
 or a particular agent runtime.
 
-Nawabari governs operations routed through Nawabari. It is an authorization and
-ownership boundary, not an operating-system or filesystem sandbox: a process
-that already has filesystem permissions can still edit another worktree
-directly.
+Nawabari governs operations routed through Nawabari. By default it is an
+authorization and ownership boundary, not an operating-system or filesystem
+sandbox: a process that already has filesystem permissions can still edit
+another worktree directly. This default (legacy) mode is unchanged.
+
+The opt-in protected session mode defines a Linux-only OS/filesystem/process
+enforcement boundary underneath the existing session/worktree/resource
+authority (`src/domain/sandbox.ts`, contract
+`nawabari.sandbox-execution.v1`). It binds one existing Nawabari session
+resolved through the authoritative registry/guard path to a typed sandbox
+execution request; it does not create a second session identity. A
+machine-readable capability/doctor report distinguishes required Linux
+primitives (bubblewrap, user/mount/PID/IPC/UTS namespaces) from optional
+defense-in-depth primitives (cgroups v2, Landlock, seccomp, capability
+inspection). When protected execution is requested and a required capability
+is unavailable or the platform is unsupported, resolution fails closed and
+never returns a request that claims the legacy unsandboxed path is
+protected. The lower-level contract remains responsible only for capability
+detection and the typed request/result shape; `resolveSandboxExecutionRequest()`
+returns a request without invoking bubblewrap. The managed `session run`
+launcher consumes that request and establishes the protected boundary. Network
+mode is honestly reported as `inherited` (shared with the host), not isolated.
+
+`git nawabari session run --session <id> -- <command> [args...]` is the
+managed protected execution entry point. It resolves the existing session
+through the normal guard authority and compiles a fixed bubblewrap argv; the
+command is passed after an argv terminator and is never interpreted by a
+shell. Resolution or launch failure never falls back to the legacy ambient
+filesystem view.
+
+The canonical profile starts from a private root, mounts only the owned
+worktree read-write, gives each session private `/tmp`, `/proc`, HOME and
+cache state, and exposes no sibling worktree or control-plane path. A small
+repository-owned `nawabari/sandbox/shared-home` subtree is the only HOME state
+shared between sessions. Selected host user-tool directories (`~/.local/bin`
+and pnpm's user bin when present) are read-only; credentials and the rest of
+the host HOME are not mounted. `/dev`, system certificates/configuration, and
+the detected runtime are explicit read-only/runtime inputs.
+
+On standalone Linux the profile uses existing `/usr`, `/bin`, `/lib*` and
+selected `/etc` paths only when present. On NixOS it additionally selects
+`/nix/store`, `/run/current-system`, `/run/wrappers`, and the per-user profile
+when present; no `/usr` layout is assumed. Missing required paths or namespace
+support produces a stable capability/topology error. Network remains
+inherited by design.
 
 ## Install
 
@@ -41,6 +82,13 @@ result-schema versions, identity fields, and stable `failure_codes`. The
 package version is release metadata; it is not a substitute for the
 machine-contract identifier.
 
+The `resource-claims` capability additionally exposes a machine-readable
+`claim_set_replacement` object (`commands`, `atomic: true`,
+`pairing: "adjacent-resource-mode"`, `idempotent_retry: true`,
+`unchanged_on_rejection: true`) describing the atomic multi-claim replacement
+surface documented above, so a caller can discover this contract instead of
+assuming it from the CLI help text.
+
 The supported standalone sequence is:
 
 ```text
@@ -64,6 +112,8 @@ The result schemas expose the following identities:
 | 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`          |
 
@@ -74,6 +124,35 @@ The local lifecycle requires Git and the repository-local registry/lock only;
 it does not require Mottainai, GitHub, `gh`, network access, an LLM, or a
 coding-agent runtime.
 
+## Read-only repository evidence
+
+The evidence family is session-addressed and has no task, Issue, semantic, or
+GitHub interpretation. It is the physical repository authority for one owned
+session:
+
+```bash
+git nawabari evidence snapshot --session "$NAWABARI_SESSION_ID" --json
+git nawabari diff --session "$NAWABARI_SESSION_ID" --path src/example.ts --json
+git nawabari diff --session "$NAWABARI_SESSION_ID" --path src/example.ts \
+  --patch --max-bytes 32768 --max-hunks 32 --json
+```
+
+`evidence snapshot` verifies the registry's repository/worktree/branch owner,
+then reuses checkpoint's exact NUL-safe Git observation for `changed`,
+`staged`, `unstaged`, and `untracked` paths. It also reports canonical per-path
+stats, `clean`, the current `head`, session state, and an `evidence_hash`.
+New sessions persist the exact creation/base revision as `base_revision`;
+legacy records that lack this field report `base_revision: null` and
+`base_revision_proven: false` rather than inferring it from a mutable ref.
+
+`diff` requires at least one explicit concrete path and never accepts a glob or
+an empty repository-wide selection. Stats are returned by default. Patch text
+requires `--patch` and is bounded to at most 64 paths, 64 KiB, and 128 hunks;
+the caller may request smaller limits. Unrepresentable Git observations fail
+with `GIT_STATE_AMBIGUOUS`; a requested path whose stat is not exposed by Git
+remains in the result with `available: false` and makes snapshot evidence
+`complete: false`, so no path silently disappears.
+
 ## Session lifecycle
 
 Session IDs are generated automatically as UUIDv7 values. They are immutable
@@ -91,6 +170,11 @@ 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` 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
@@ -108,6 +192,19 @@ every candidate that is not safe. Cleanup revalidates the physical worktree,
 branch, and `HEAD` observations immediately before each destructive Git
 operation.
 
+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
+by listing or cleanup.
+
+`gc` stale eligibility is separate from closed-history retention. Its default
+threshold is 24 hours (`86,400,000` ms), measured from persisted `updated_at`;
+records already in `stale` or `closing` state are eligible, and an otherwise
+live record is also eligible when Git reports its registered worktree as
+missing or prunable. Physical Git/worktree state is authoritative for that
+check. `gc --dry-run` and `gc --apply` do not treat a closed record as a stale
+cleanup candidate.
+
 `doctor` includes a non-destructive `reconciliation` check. It reports
 registry/Git ownership drift, including missing or prunable worktrees and
 unregistered physical worktrees, without repairing or deleting anything.
@@ -119,8 +216,10 @@ same repository registry and protected by the same mutation lock. They are
 caller declarations; Nawabari does not infer them from task text or source
 code. Claim JSON exposes `schema_version`, `claim_id`, `session_id`, the
 repository/worktree identities, canonical `resource`, `mode`, and timestamps.
-The initial claim schema version is `1` and supports `read`, `write`, and
-`exclusive-write`.
+The claim schema version is `2` and supports `read`, `write`, and
+`exclusive-write`. Schema v1 records use different overlap semantics and are
+not interpreted implicitly: an embedding caller must explicitly run
+`SessionRegistry.migrate()` before using them.
 
 ```bash
 git nawabari session claim --session "$NAWABARI_SESSION_ID" \
@@ -131,14 +230,45 @@ git nawabari session update --session "$NAWABARI_SESSION_ID" \
 git nawabari session release --session "$NAWABARI_SESSION_ID" --json
 ```
 
+`session update` (and its `resource update` alias) atomically replaces a
+session's _complete_ claim set in one `updateClaims()` transaction, backed by
+the same repository lock as every other mutation. `--resource`/`--mode` are
+repeatable to submit a multi-resource desired set in a single call; each
+`--resource` must be immediately followed by its own `--mode`, so pairing is
+positional adjacency rather than flag order and repeated resources can never
+be associated with the wrong mode:
+
+```bash
+git nawabari session update --session "$NAWABARI_SESSION_ID" \
+  --resource src/a.ts --mode exclusive-write \
+  --resource src/b.ts --mode exclusive-write \
+  --json
+```
+
+If any requested claim in the set is invalid or conflicts, the whole update
+is rejected and the session's prior claim set is left unchanged; no partial
+or empty intermediate claim state is ever observable. Submitting the same
+complete desired set again is idempotent. A successful replacement's JSON
+exposes the resulting `claims` together with machine-readable `added` and
+`released` claims.
+
+The modes have these normative meanings:
+
+- `read`: a non-mutating access declaration. It is not a consistency lease,
+  so it may overlap an ordinary `write` claim.
+- `write`: ordinary source-modification authority. It may overlap `read`, but
+  not another writer or any `exclusive-write` claim.
+- `exclusive-write`: stronger ownership-sensitive mutation authority. It
+  excludes every overlapping claim, including `read`.
+
 Overlapping claims use this complete compatibility matrix; non-overlapping
 claims are compatible for every mode:
 
-| existing \/ requested | read       | write    | exclusive-write |
-| --------------------- | ---------- | -------- | --------------- |
-| read                  | compatible | conflict | conflict        |
-| write                 | conflict   | conflict | conflict        |
-| exclusive-write       | conflict   | conflict | conflict        |
+| existing \/ requested | read       | write      | exclusive-write |
+| --------------------- | ---------- | ---------- | --------------- |
+| read                  | compatible | compatible | conflict        |
+| write                 | compatible | conflict   | conflict        |
+| exclusive-write       | conflict   | conflict   | conflict        |
 
 Claims use canonical repository-relative POSIX paths. Literal path segments,
 `*`/`?` segment wildcards, and a complete `**` segment are supported. Empty,
@@ -149,6 +279,26 @@ garbage-collecting a session releases its claims; no separate claim registry
 or claim lock exists. Claims describe ownership state only and do not provide
 OS-level filesystem observation or a filesystem sandbox.
 
+An ordinary source change uses `write` and can proceed while another session
+holds a `read` declaration:
+
+```bash
+git nawabari session claim --session "$NAWABARI_SESSION_ID" \
+  --resource src/example.ts --mode write --json
+git nawabari authorize --session "$NAWABARI_SESSION_ID" \
+  --operation source-write --resource src/example.ts --json
+```
+
+A stronger ownership-sensitive operation uses `exclusive-write` and therefore
+requires no overlapping claim:
+
+```bash
+git nawabari session claim --session "$NAWABARI_SESSION_ID" \
+  --resource src/example.ts --mode exclusive-write --json
+git nawabari authorize --session "$NAWABARI_SESSION_ID" \
+  --operation commit --resource src/example.ts --json
+```
+
 ## Ownership guard
 
 `git nawabari guard` is a cheap, side-effect-free authorization decision for a
@@ -187,6 +337,17 @@ worktree=$(printf '%s' "$created" | jq -r .worktree)
 git nawabari session close --session "$session_id" --json
 ```
 
+For a worker that must receive the protected filesystem/process boundary, use
+the managed launcher instead of starting the worker directly:
+
+```bash
+git nawabari session run --session "$session_id" -- node worker.js
+```
+
+The launcher owns only the child sandbox topology and process attachment. The
+session registry, worktree/branch ownership, resource claims and lifecycle
+remain the authoritative Nawabari domain state.
+
 The orchestrator owns scheduling, prompts, and worker lifetime; Nawabari owns
 only local session identity, worktree/branch ownership, and safe cleanup. No
 Mottainai, GitHub, `gh`, network, or agent-runtime dependency is required.
@@ -217,9 +378,15 @@ repository-relative resources. Nawabari independently verifies the current
 repository, owned worktree, branch, active session, and persisted claims;
 caller-supplied labels do not weaken that decision. The JSON result is the
 automation contract and reports stable allow/deny codes such as
-`MISSING_RESOURCE_CLAIM`, `RESOURCE_CLAIM_CONFLICT`, `INVALID_RESOURCE`, and
+`MISSING_RESOURCE_CLAIM`, `INSUFFICIENT_CLAIM_MODE`, `RESOURCE_CLAIM_CONFLICT`,
+`INVALID_RESOURCE`, and
 the existing ownership/physical-observation codes.
 
+`INSUFFICIENT_CLAIM_MODE` means a matching claim exists but its granted mode
+is weaker than the operation requires. Its bounded details identify the
+resource, required access, and matching granted mode names;
+`MISSING_RESOURCE_CLAIM` remains reserved for an absent matching claim.
+
 **`authorize` returns an authorization decision only; it does NOT execute the
 operation itself.** Governed commit and push execution use this same decision
 path before invoking bounded Git subprocesses.
@@ -234,17 +401,51 @@ repository-relative resources. Every resource must be covered by an active
 `exclusive-write` claim; all Git-visible changed/staged paths must be in the
 explicit list. JSON includes the resulting `commit_sha`.
 
+Commit evidence distinguishes three sets: the caller's **declared/authorized**
+resources (the explicit, claim-covered list a caller passed in), the
+**staged** set Git reports as staged immediately before the commit runs, and
+the **actual committed** set — read back from the resulting commit itself via
+a bounded, NUL-safe `git diff-tree` observation, not inferred from staging
+intent. The `resources` field in a successful `commit --json` result is
+always the actual committed set, proven equal to or a subset of the
+authorized resources; if Git staging/index drift between staging and the
+commit (a hook, a concurrent process) causes the actual commit to contain a
+path outside the authorized set, the result is not reported as an ordinary
+successful commit — it fails with `COMMIT_RESULT_DIVERGED`, which retains the
+resulting `commitSha` (the Git commit already happened) alongside the
+authorized, actual, and divergent path sets for recovery/reconciliation.
+
 ```bash
 git nawabari commit --session "$NAWABARI_SESSION_ID" \
   --message 'record the local change' --resource src/example.ts --json
 ```
 
+An optional `--message-pattern <regex>` validates the final message against a
+caller-declared rule before Git is invoked; Nawabari does not own or infer
+commit-message conventions (such as Conventional Commits) itself, so this
+check runs only when a caller explicitly supplies a pattern, and a mismatch
+fails with `INVALID_COMMIT_MESSAGE` before anything is staged. The pattern is
+bounded to 512 characters and is evaluated before the repository lock is
+acquired, so a pathological caller-supplied pattern cannot stall other
+sessions' governed operations. A repository's own `commit-msg` Git hook (if
+any) still runs normally, since governed commit invokes real `git commit`.
+
+```bash
+git nawabari commit --session "$NAWABARI_SESSION_ID" \
+  --message 'feat: record the local change' --resource src/example.ts \
+  --message-pattern '^(feat|fix|docs|refactor|test|chore): .+$' --json
+```
+
 Governed push requires explicit claim-covered resources and an explicit
 `--remote`/`--branch` target. Existing upstream and local/remote relation are
 inspected before mutation. A missing upstream requires `--create-upstream`;
-behind or diverged history requires explicit `--force`, which uses
-`--force-with-lease`. The JSON result identifies the pushed `target` and
-reports its relation.
+behind or diverged history requires explicit `--force`. Force pushes use an
+exact `--force-with-lease` bound to the observed remote branch SHA; non-force
+pushes rely on `--no-force` without any lease option. Nawabari fetches only
+the explicit remote branch into a disposable ref when local ancestry is
+missing; it does not update tracking refs or fetch unrelated branches/tags.
+The JSON result includes the immutable `source_sha`, explicit `target_ref`,
+observed `observed_remote_sha`, and relation.
 
 ```bash
 git nawabari push --session "$NAWABARI_SESSION_ID" \
@@ -259,6 +460,15 @@ filesystem activity that is reverted, ignored, or otherwise not observable in
 the Git checkpoint is outside Nawabari's guarantee; this feature is not an
 OS-level filesystem monitor.
 
+Checkpoint canonicalization fails closed: a Git-reported path that cannot be
+represented as a canonical repository resource (traversal, symlink escape, or
+syntax reserved for the claim/glob model) never disappears from evidence.
+Checkpoint fails the whole observation with `GIT_STATE_AMBIGUOUS` instead of
+silently omitting the path, so a caller can never mistake an unrepresentable
+observation for a clean one. This mirrors the strictness governed mutation
+already applies to the same Git-observed paths, so checkpoint evidence is
+never weaker than mutation authorization.
+
 ## Physical execution context
 
 Nawabari treats Git and the canonical filesystem as the authority for every
@@ -280,6 +490,11 @@ worktree paths, and existing local branches are rejected deterministically;
 the repository lock serializes Nawabari provisioning and Git's own ref checks
 remain the final collision authority.
 
+An explicit `--base` ref that is empty, malformed, or does not resolve to a
+commit fails with `INVALID_BASE_REF`. The bounded JSON details retain the
+rejected ref, identify `HEAD` as the default recovery base, and include the
+retry hint to omit `--base`; Nawabari does not enumerate or fuzzy-search refs.
+
 ## Repository state and concurrency
 
 The authoritative registry is stored in the repository-common Git directory at

package/dist/cli.d.ts

@@ -1,9 +1,14 @@
+import { type DomainResult } from "./domain/errors.js";
 import { type SessionBackend } from "./domain/session.js";
 import { type CliIO } from "./presentation.js";
+import { type SandboxCommand, type SandboxExecutionResult, type SandboxProbe, type SandboxRuntimeLayout } from "./domain/sandbox.js";
 export type CliDependencies = {
     backend?: SessionBackend;
     cwd?: string;
     io?: CliIO;
     version?: string;
+    sandboxRunner?: (request: import("./domain/sandbox.js").SandboxExecutionRequest, command: SandboxCommand) => Promise<DomainResult<SandboxExecutionResult>>;
+    sandboxProbe?: SandboxProbe;
+    sandboxRuntimeLayout?: SandboxRuntimeLayout;
 };
 export declare function runCli(argv: string[], dependencies?: CliDependencies): Promise<number>;