nawabari 0.7.1 → 0.8.0

package/README.md

@@ -17,9 +17,11 @@ authority (`src/domain/sandbox.ts`, contract
 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
+primitives (bubblewrap, user/mount/PID/IPC/UTS namespaces, the versioned
+seccomp baseline, and capability reduction) from optional defense-in-depth
+primitives (cgroups v2 and Landlock). The sandbox report exposes Landlock's
+observed ABI, support, and effective state (`available`, `enforced`,
+`reduced-defense`, `incompatible`, or `error`). 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
@@ -44,15 +46,43 @@ 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.
 
+When the host exposes a compatible Landlock ABI, the protected launcher applies
+a rule set derived from this same topology inside bubblewrap. An unavailable
+or incompatible optional ABI leaves bubblewrap active and reports
+`reduced-defense`; an adapter setup failure fails closed, and a profile that
+explicitly requires Landlock also fails closed when its adapter cannot be
+established. Setup diagnostics are bounded and no ambient/unsandboxed retry is
+attempted.
+
 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.
+when present; broad FHS views (`/usr`, `/bin`, `/lib*`) are not selected when
+the NixOS closure roots are present. Missing required paths or namespace
+support produces a stable capability/topology error. The protected child uses
+`nawabari.seccomp.v1`, a compatibility-first deny-list whose policy denials
+return `EPERM` rather than hanging or terminating ordinary development
+subprocess trees. Ambient capabilities are empty (`--cap-drop ALL`). Network
+remains inherited by design.
+
+The canonical Mottainai NixOS Runtime fixture can run the opt-in compatibility
+conformance matrix as its unprivileged repository principal:
+
+```bash
+NAWABARI_NIXOS_RUNTIME_CONFORMANCE=1 \
+  node --test --import tsx src/domain/nixos-runtime-compat.test.ts
+```
+
+This invokes the normal `session run` CLI route and production launcher. It
+checks explicit NixOS closure paths, private versus repository-shared HOME
+state, Git/checkpoint authority, representative toolchain subprocesses, and
+sequential/concurrent session isolation. It does not create a test-only
+sandbox or treat Mottainai state as Nawabari authority.
 
 ## Install
 
+Nawabari requires Node.js >=24.
+
 ```bash
 npm install -g nawabari
 ```
@@ -82,6 +112,17 @@ 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 `protected-execution` capability separately advertises the versioned
+`nawabari.sandbox-execution.v1` contract, its required and optional host
+capabilities, the canonical `session run` entry point and `session exec` alias,
+`network_mode: "inherited"`, and fail-closed behavior. Use
+`nawabari doctor --json` to inspect the current host without creating or
+selecting a session. Its `sandbox` report is produced by the same
+`sandboxDoctorReport` authority used when resolving protected execution and
+contains `platform_supported`, per-capability status, `ready`, and
+`missing_required`. An unavailable required capability never implies an
+ambient protected fallback.
+
 The `resource-claims` capability additionally exposes a machine-readable
 `claim_set_replacement` object (`commands`, `atomic: true`,
 `pairing: "adjacent-resource-mode"`, `idempotent_retry: true`,
@@ -126,8 +167,8 @@ The result schemas expose the following identities:
 | claims                 | `claim_id`, `session_id`, `resource`, `mode`, `claim_set_generation`, `previous_claim_set_generation`                               |
 | 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`                                                          |
+| repository evidence    | `session_id`, `session_updated_at`, `base_revision`, `head`, `clean`, `paths.stats`, `evidence_hash`                                |
+| bounded diff           | `from_revision`, `to_revision`, `paths`, `stats`, `diagnostics`, `patch`, `evidence_hash`                                           |
 | commit/push            | `commit_sha`, `remote`, `branch`, `target`, `relation`                                                                              |
 | reconciliation/cleanup | `clean`, `issues`, `candidates`, `cleaned`, `blocked`, `recovery_hints`                                                             |
 
@@ -159,13 +200,24 @@ 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.
 
+`session_updated_at` is the UTC timestamp of the last authoritative
+session-state mutation, not a general Git filesystem mtime. A successful
+Nawabari-managed `commit` is such a mutation, so the registry timestamp is
+persisted before the command returns and a subsequent snapshot reports it with
+the resulting `head`. Git changes made outside Nawabari do not advance this
+field; consumers must use the Git-observed fields for those changes.
+
 `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.
+`complete: false`, so no path silently disappears. Such paths include a
+bounded `diagnostics` entry; a target directly observed as untracked reports
+`reason: UNTRACKED_TARGET`, while other unavailable-stat causes remain
+`STAT_UNAVAILABLE`. These diagnostics are read-only and do not stage or add
+files.
 
 ## Session lifecycle
 
@@ -216,8 +268,9 @@ destructive cleanup. A clean close releases only the owned worktree and
 branch, and repeating close is idempotent. `gc` detects stale or interrupted
 sessions; `--apply` uses the same close safety checks and reports blocked
 sessions instead of guessing. `gc --dry-run` performs the same non-mutating
-cleanup preflight and includes stable blocker codes and `recovery_hints` for
-every candidate that is not safe. Cleanup revalidates the physical worktree,
+cleanup preflight, reports age/physical/lifecycle suspicion separately from
+destructive eligibility, and includes stable blocker codes and
+`recovery_hints` for every eligible candidate that is not safe. Cleanup revalidates the physical worktree,
 branch, and `HEAD` observations immediately before each destructive Git
 operation.
 
@@ -238,12 +291,15 @@ 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.
+threshold is 24 hours (`86,400,000` ms), measured from persisted `updated_at`.
+Elapsed age is diagnostic suspicion only: it never authorizes destructive
+cleanup for a physically healthy active session. Records already in `stale` or
+`closing` state are eligible, as is an otherwise live record when Git reports
+its registered worktree as safely prunable and missing. Ambiguous physical
+state remains ineligible and fail-closed. `gc --dry-run` exposes suspicion and
+destructive eligibility/reason separately for each candidate; `gc --apply`
+uses only eligible candidates. Closed records are never stale cleanup
+candidates.
 
 `doctor` includes a non-destructive `reconciliation` check. It reports
 registry/Git ownership drift, including missing or prunable worktrees and
@@ -258,8 +314,18 @@ code. Claim JSON exposes `schema_version`, `claim_id`, `session_id`, the
 repository/worktree identities, canonical `resource`, `mode`, and timestamps.
 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.
+not interpreted implicitly. If an upgraded repository reports
+`UNSUPPORTED_CLAIM_SCHEMA_VERSION`, run the public migration command:
+
+```bash
+git nawabari migrate --json
+```
+
+Migration validates the complete legacy registry under the registry lock and
+rewrites it with an atomic replace. It is idempotent and retry-safe; ambiguous
+or corrupt state is rejected with bounded diagnostics. Do not hand-edit or
+delete the registry. Embedding callers may use the same authority through
+`SessionRegistry.migrate()`.
 
 ```bash
 git nawabari session claim --session "$NAWABARI_SESSION_ID" \
@@ -337,6 +403,14 @@ 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.
 
+For an existing path, canonicalization follows the physical directory entry,
+so a case-insensitive filesystem cannot give `README.md` and `readme.md`
+independent claim identities. This is determined from the filesystem entry
+itself; paths that do not exist yet, and wildcard portions of a claim, retain
+their exact lexical case because their future physical identity is unknown.
+On a case-sensitive filesystem an alternate-case spelling is therefore a
+distinct (possibly future) path, and no global lowercasing is applied.
+
 An ordinary source change uses `write` and can proceed while another session
 holds a `read` declaration:
 
@@ -389,6 +463,16 @@ identifiers, in addition to the human-readable `message`. JSON and human
 output always render the identical underlying result; only the formatting
 differs.
 
+Lifecycle diagnostics additionally expose `next_action` (and the bounded
+`next_actions` list) as typed, non-mutating caller actions. The action schema
+is versioned independently and currently includes `retain-session`,
+`supply-exact-integrated-revision`,
+`retry-close-with-bounded-integration-fetch`, `discard-session`, and
+`reconcile-physical-state`. A discard action always carries explicit intent;
+ambiguous or terminal states never advertise destructive actions. These
+fields are additive to `session-diagnostic.v1`, so existing consumers may
+continue using `safe_actions`.
+
 - **`RESOURCE_CLAIM_CONFLICT`** (`session claim`/`session update`,
   `authorize`, `guard --operation`) reports the blocking claim
   (`ownerClaimId`, `ownerResource`, `ownerMode`) and the blocking session's
@@ -521,6 +605,16 @@ 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.
 
+If Git reports a bounded transport failure (timeout, output limit, or spawn
+failure) after the commit invocation, Nawabari re-reads the local `HEAD` and
+that commit's bounded changed-path set before classifying the outcome. A
+failure whose `HEAD` is unchanged is reported with `outcome: "proven-absent"`
+and `retrySafe: true`; a matching new commit is returned as a successful
+result with `reconciliation.outcome: "proven-committed"` and its resulting
+SHA; if either observation is unavailable or does not match the authorized
+paths, the failure carries `outcome: "unresolved"` and `retrySafe: false`.
+Unresolved outcomes never authorize a blind retry.
+
 ```bash
 git nawabari commit --session "$NAWABARI_SESSION_ID" \
   --message 'record the local change' --resource src/example.ts --json
@@ -546,12 +640,19 @@ 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`. 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.
+exact `--force-with-lease` bound to the observed remote branch SHA. Ordinary
+pushes use the same exact-generation lease, while force authorization remains
+separate. A new remote branch uses an empty lease, requiring the target ref to
+remain absent. 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.
+observed `observed_remote_sha`, and relation. If a bounded transport failure
+may have happened after the remote mutation, Nawabari re-observes only that
+exact remote ref. It reports `reconciliation.outcome` as `proven-pushed`,
+`proven-absent`, or `unresolved`, with the exact precondition and post-failure
+generation evidence. Only a proven-absent outcome is retry-safe; unresolved
+outcomes never authorize a blind retry.
 
 ```bash
 git nawabari push --session "$NAWABARI_SESSION_ID" \
@@ -610,11 +711,18 @@ ID, canonical worktree and branch identities, lifecycle state, and timestamps.
 
 Ownership-changing writes use an exclusive repository-local lock and a synced
 temporary file followed by atomic replacement. Concurrent creation cannot
-silently duplicate an active worktree or branch. Lock recovery is conservative:
-the lock records a random token, PID, host, and process-start identity; an
-owner is reclaimed only when the same host proves that exact process identity
-is dead. Invalid, remote, or otherwise unverifiable lock metadata is never
-stolen and fails closed so an operator can inspect or remove it deliberately.
+silently duplicate an active worktree or branch. Lock recovery is conservative
+and platform-qualified: stale-lock reclamation is supported only on Linux,
+where the lock records a random token, PID, host, and the exact process-start
+token from `/proc/<pid>/stat`. An owner is reclaimed only when the same host
+proves that exact process identity is dead; elapsed age and PID liveness alone
+are never reclaim authority. On non-Linux platforms, Node can run ordinary
+Nawabari operations but does not provide a safe process-generation identity,
+so stale local locks remain `LOCK_STALE` and require deliberate operator
+remediation. Invalid, remote, or otherwise unverifiable lock metadata is never
+stolen and fails closed. The same limitation is machine-readable under
+`capabilities --json` at the `session-lifecycle.registry_lock_recovery`
+contract.
 
 ### Conformance and extraction boundary
 
@@ -639,6 +747,98 @@ The relevant Mottainai #28 execution cases are mapped as follows:
 Run `pnpm run test:package` to validate the exact packed tarball and its
 installed CLI, or `pnpm run verify` for the complete local conformance gate.
 
+## Exact packed standalone protected-execution evidence
+
+`pnpm run test:package:protected` is the package/evidence gate for the
+standalone protected product. It creates one exact `pnpm pack` archive, records its
+package/version, filename, byte size, SHA-256, source revision, and host
+identity in `test-artifacts/packed-standalone-protected-execution.json`,
+validates the archive contents, and installs that archive into a fresh
+temporary consumer with `npm install --offline`. The default evidence report
+is ignored by Git; pass `--evidence-output <path>` to retain it elsewhere and
+`--keep-tarball` to retain the exact archive for inspection.
+
+The smoke test invokes only the installed `nawabari` bin. Its package allowlist
+contains `dist` runtime artifacts, `README.md`, `LICENSE`, and `package.json`;
+source, test, and script modules are rejected, and the installed manifest must
+not declare runtime dependencies. The lifecycle proof goes through the
+installed public CLI for `capabilities --json`, `doctor --json`, session
+creation/resolution, `session run`, resource claims, checkpoint, commit,
+local-bare-remote push, and close. The gate requires the protected doctor
+report to be ready; unavailable protected execution is a failure, not a skip
+or an ambient fallback. The fixture uses only a temporary local repository and
+local bare remote and has no Mottainai, GitHub, `gh`, LLM, or network
+dependency.
+
+The ordinary `pnpm run test:package` command runs the package/install smoke
+without requiring a real protected host, so it retains the existing
+compatibility CI job; it still verifies fail-closed rejection when protection
+is unavailable. The `pnpm run test:package:protected` command is the #149
+evidence command and must be run on a supported Linux host. It requires a
+ready protected profile and fails when that prerequisite is unavailable.
+
+The evidence supports these boundaries only:
+
+- Process: on Linux with the required capabilities, the canonical launcher
+  establishes bubblewrap user, mount, PID, IPC, and UTS namespaces, applies
+  the versioned seccomp profile, and drops ambient capabilities. This is not a
+  VM or a claim about every host process.
+- Filesystem: the protected child receives the authoritative session worktree
+  read-write, private session HOME/cache/`/tmp`/`/proc`, repository-owned
+  shared HOME state, and the fixed read-only runtime/tool inputs selected by
+  the profile. Sibling worktrees and unselected host HOME paths are not part
+  of the selected topology.
+- HOME/cache: the child sees `/home/nawabari`; private state is per session,
+  while only the repository's selected shared-home subtree is shared. Selected
+  host tool directories are read-only inputs, not the host HOME.
+- Network: `network_mode` is `inherited`; this evidence does not prove egress
+  isolation.
+- Linux prerequisites: use `nawabari doctor --json` on a supported Linux host.
+  The package's supported Node.js engine, Git, and required bubblewrap,
+  namespace, seccomp, and capability support must be available and ready;
+  cgroups v2 and Landlock remain profile-reported optional defenses.
+- Failure behavior: protected resolution uses `enforce: true`; missing
+  required capability, unsupported topology, or launch failure returns a
+  bounded failure and never retries through ambient execution.
+
+## Packed Mottainai preselected-UID handoff evidence
+
+`pnpm run test:package:mottainai` is the required-CI external-handoff gate for
+Issue #150. `scripts/run-mottainai-uid-handoff-gate.mjs` runs the #149
+protected package gate exactly once, retains that exact tarball and its
+`nawabari.packed-standalone-protected-execution.v1` evidence, and passes only
+those exact paths into `scripts/run-mottainai-uid-handoff.mjs`, which installs
+that same tarball into a disposable consumer. `run-mottainai-uid-handoff.mjs`
+itself has no self-pack path: it always requires an already-produced
+`--tarball`/`--artifact-evidence` pair, so #150 can never hide a stale or
+mismatched artifact behind a second pack. The fixture invokes the installed
+`session run` contract under two distinct preselected unprivileged UIDs
+(23001 and 23002 by default) and records bounded
+artifact/fixture/UID/session/worktree/resource/Git evidence in
+`test-artifacts/mottainai-packed-uid-handoff.json`. This gate runs in required
+CI on a Linux host with bubblewrap (`mottainai-uid-handoff` job).
+
+The checked-in `scripts/test-fixtures/mottainai-preselected-uid-runner.sh` is a
+UID-only execution adapter. A real Mottainai Runtime may supply another
+executable with the same `--uid`, `--root`, `--cwd`, `--` argv contract:
+
+```bash
+node scripts/run-mottainai-uid-handoff.mjs \
+  --tarball nawabari-0.7.1.tgz \
+  --artifact-evidence test-artifacts/packed-standalone-protected-execution.json \
+  --fixture-runner /path/to/mottainai-uid-runner \
+  --uids 23001,23002 \
+  --output test-artifacts/mottainai-packed-uid-handoff.json
+```
+
+The runner supplies only the caller's OS UID/GID view. Nawabari remains the
+sole authority for session, worktree, resource claims, protected execution,
+checkpoint, commit, push, local Git, and close; the fixture creates no
+repository-principal registry and passes no Mottainai task, policy, or
+credential semantics. Identical display names, branch names, and resource
+paths are used under different canonical repository paths, and the protected
+child's session/cwd marker is checked to prevent principal confusion.
+
 ## Development
 
 ```bash

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

@@ -0,0 +1,44 @@
+export type CliHelpOptionSpec = {
+    readonly name: string;
+    readonly aliases?: readonly string[];
+    readonly alias_of?: string;
+    readonly value?: string;
+    readonly required?: boolean;
+    readonly default?: string;
+    readonly minimum?: number;
+    readonly maximum?: number;
+    readonly repeatable?: boolean;
+    readonly description: string;
+};
+export type CliCommandDefinition = {
+    readonly name: string;
+    readonly aliases?: readonly string[];
+    readonly summary: string;
+    readonly usage: string;
+    readonly options: readonly CliHelpOptionSpec[];
+    readonly notes?: readonly string[];
+};
+export declare const GLOBAL_HELP_OPTIONS: readonly CliHelpOptionSpec[];
+/**
+ * Canonical public command/discovery registry.
+ *
+ * Dispatcher implementation deliberately remains below in this module.  This
+ * registry only describes the public discovery surface; aliases point at the
+ * canonical command so option metadata cannot drift between projections.
+ */
+export declare const CLI_COMMAND_REGISTRY: readonly CliCommandDefinition[];
+export declare const ROOT_HELP_SPEC: CliCommandDefinition;
+/** Resolve a public name through the one canonical registry. */
+export declare function canonicalCommandForName(name: string): CliCommandDefinition | undefined;
+/**
+ * Materialize public names for projections without copying option metadata.
+ * Alias entries are generated from their canonical definition, including the
+ * usage, options, and parser notes.
+ */
+export declare function publicCliCommandDefinitions(): readonly CliCommandDefinition[];
+/** Stable alias for consumers such as the future dispatcher parity layer. */
+export declare const COMMAND_REGISTRY: readonly CliCommandDefinition[];
+/** Resolve either a canonical command or one of its public aliases. */
+export declare function resolveCliCommandDefinition(name: string): CliCommandDefinition | undefined;
+/** Return the complete public discovery name list in registry order. */
+export declare function publicCliCommandNames(): readonly string[];