nawabari 0.3.0 → 0.5.0

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
@@ -123,9 +171,15 @@ 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
@@ -182,6 +236,28 @@ 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,
@@ -251,6 +327,48 @@ 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. 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
@@ -267,6 +385,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.

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>;