nawabari 0.3.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
@@ -182,6 +230,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,
@@ -267,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.

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

package/dist/cli.js

@@ -6,6 +6,7 @@ import { EVIDENCE_MAX_DIFF_BYTES, EVIDENCE_MAX_DIFF_HUNKS, EVIDENCE_MAX_DIFF_PAT
 import { createLocalSessionBackend } from "./domain/session-backend.js";
 import { defaultCliIO, renderFailure, renderSuccess } from "./presentation.js";
 import { MACHINE_CONTRACT_ID, MACHINE_CONTRACT_SCHEMA_VERSION, machineContract } from "./contract.js";
+import { resolveSandboxExecutionRequest, runSandboxedCommand, } from "./domain/sandbox.js";
 const CLI_NAME = "nawabari";
 const packageMetadata = createRequire(import.meta.url)("../package.json");
 const VERSION = packageMetadata.version;
@@ -46,6 +47,16 @@ const HELP_COMMANDS = [
         usage: `${CLI_NAME} session show [--session <id>]`,
         options: [option("--session", "Select a session instead of the current worktree owner", { value: "<id>" })],
     },
+    {
+        name: "session run",
+        summary: "Run one command inside the protected session sandbox",
+        usage: `${CLI_NAME} session run [--session <id>] -- <command> [args...]`,
+        options: [option("--session", "Select the active owned session", { value: "<id>" })],
+        notes: [
+            "The -- terminator is mandatory. The command is passed as argv without a shell, and protected execution is fail-closed.",
+            "session exec is an alias.",
+        ],
+    },
     {
         name: "session list",
         summary: "List bounded repository session records",
@@ -69,14 +80,25 @@ const HELP_COMMANDS = [
     },
     {
         name: "session update",
-        summary: "Replace a session's resource claims",
-        usage: `${CLI_NAME} session update --resource <path-or-glob> --mode <read|write|exclusive-write> [--session <id>]`,
+        summary: "Atomically replace a session's complete resource claim set",
+        usage: `${CLI_NAME} session update --resource <path-or-glob> --mode <read|write|exclusive-write> [--resource <path-or-glob> --mode <read|write|exclusive-write> ...] [--session <id>]`,
         options: [
-            option("--resource", "Repository-relative resource", { value: "<path-or-glob>", required: true }),
-            option("--mode", "Granted claim mode", { value: "<read|write|exclusive-write>", required: true }),
+            option("--resource", "Repository-relative resource; repeatable, each paired with the --mode immediately after it", {
+                value: "<path-or-glob>",
+                required: true,
+            }),
+            option("--mode", "Mode for the --resource immediately before it; repeatable", {
+                value: "<read|write|exclusive-write>",
+                required: true,
+            }),
             option("--session", "Target active session; omitted resolves the current owner", { value: "<id>" }),
             option("--repository", "Expected repository identity", { value: "<id>" }),
         ],
+        notes: [
+            "The desired claim set fully replaces the session's current claims in one updateClaims() transaction; " +
+                "on any invalid or conflicting claim the prior set is left unchanged.",
+            "Each --resource must be immediately followed by its own --mode; pairing is positional adjacency, not flag order.",
+        ],
     },
     {
         name: "session claims",
@@ -101,9 +123,25 @@ const HELP_COMMANDS = [
     },
     {
         name: "resource update",
-        summary: "Replace a session's resource claims (alias)",
-        usage: `${CLI_NAME} resource update --resource <path-or-glob> --mode <read|write|exclusive-write>`,
-        options: [],
+        summary: "Atomically replace a session's complete resource claim set (alias)",
+        usage: `${CLI_NAME} resource update --resource <path-or-glob> --mode <read|write|exclusive-write> [--resource <path-or-glob> --mode <read|write|exclusive-write> ...] [--session <id>]`,
+        options: [
+            option("--resource", "Repository-relative resource; repeatable, each paired with the --mode immediately after it", {
+                value: "<path-or-glob>",
+                required: true,
+            }),
+            option("--mode", "Mode for the --resource immediately before it; repeatable", {
+                value: "<read|write|exclusive-write>",
+                required: true,
+            }),
+            option("--session", "Target active session; omitted resolves the current owner", { value: "<id>" }),
+            option("--repository", "Expected repository identity", { value: "<id>" }),
+        ],
+        notes: [
+            "The desired claim set fully replaces the session's current claims in one updateClaims() transaction; " +
+                "on any invalid or conflicting claim the prior set is left unchanged.",
+            "Each --resource must be immediately followed by its own --mode; pairing is positional adjacency, not flag order.",
+        ],
     },
     {
         name: "resource list",
@@ -246,7 +284,9 @@ function helpSpecFor(commandArguments) {
         return ROOT_HELP_SPEC;
     let key = commandArguments[0] === "resource"
         ? `resource ${commandArguments[1] ?? "list"}`
-        : commandArguments.slice(0, 2).join(" ");
+        : commandArguments[0] === "session" && commandArguments[1] === "exec"
+            ? "session run"
+            : commandArguments.slice(0, 2).join(" ");
     if (key === "resource claims")
         key = "resource list";
     const direct = HELP_COMMANDS.find((spec) => spec.name === key);
@@ -348,7 +388,17 @@ function parseGlobalArguments(argv) {
     let help = false;
     let version = false;
     const commandArguments = [];
+    let passthrough = false;
     for (const argument of argv) {
+        if (passthrough) {
+            commandArguments.push(argument);
+            continue;
+        }
+        if (argument === "--") {
+            passthrough = true;
+            commandArguments.push(argument);
+            continue;
+        }
         if (argument === "--json") {
             json = true;
         }
@@ -498,6 +548,83 @@ function parseOptions(arguments_, allowed) {
 function noOptions(arguments_) {
     return parseOptions(arguments_, new Set());
 }
+/**
+ * `update` accepts a complete desired claim set as repeated
+ * `--resource <path> --mode <mode>` pairs. Pairing is by strict local
+ * adjacency (each `--resource` must be immediately followed by its own
+ * `--mode`, with no other option able to intervene) rather than by
+ * parallel-array position, so argv order can never associate a resource
+ * with the wrong mode.
+ */
+function parseClaimReplacementPairs(arguments_) {
+    let sessionId = null;
+    let repository = null;
+    const pairs = [];
+    let pendingResource = null;
+    for (let index = 0; index < arguments_.length; index += 1) {
+        const { name, inlineValue } = optionParts(arguments_[index]);
+        if (name !== "--session" && name !== "--repository" && name !== "--resource" && name !== "--mode") {
+            return failure(usageError("INVALID_ARGUMENT", `Unknown option: ${name}.`, { option: name }));
+        }
+        if (pendingResource !== null && name !== "--mode") {
+            return failure(usageError("INVALID_ARGUMENT", `${name} cannot appear between --resource and its --mode; only --mode is permitted immediately after --resource.`, { option: name }));
+        }
+        const value = inlineValue ?? arguments_[index + 1];
+        if (value === undefined || value === "" || (inlineValue === null && value.startsWith("-"))) {
+            return failure(usageError("MISSING_ARGUMENT", `${name} requires a value.`, { option: name }));
+        }
+        if (inlineValue === null)
+            index += 1;
+        if (name === "--session")
+            sessionId = value;
+        else if (name === "--repository")
+            repository = value;
+        else if (name === "--resource")
+            pendingResource = value;
+        else {
+            if (pendingResource === null) {
+                return failure(usageError("INVALID_ARGUMENT", "--mode must be immediately preceded by its own --resource.", {
+                    option: "--mode",
+                }));
+            }
+            pairs.push({ resource: pendingResource, mode: value });
+            pendingResource = null;
+        }
+    }
+    if (pendingResource !== null) {
+        return failure(usageError("MISSING_ARGUMENT", "--resource must be immediately followed by --mode.", { option: "--mode" }));
+    }
+    if (pairs.length === 0) {
+        return failure(usageError("MISSING_ARGUMENT", "--resource requires a value.", { option: "--resource" }));
+    }
+    return { ok: true, value: { session_id: sessionId, repository, pairs } };
+}
+/**
+ * `claim` accepts exactly one `--resource`/`--mode` pair. Reuses the same
+ * strict-adjacency scan as `update` so a second `--resource`/`--mode` (in
+ * any order) is rejected outright instead of silently overwriting the
+ * first pair (last-wins).
+ */
+function parseSingleClaimPair(arguments_) {
+    const parsed = parseClaimReplacementPairs(arguments_);
+    if (!parsed.ok)
+        return parsed;
+    if (parsed.value.pairs.length > 1) {
+        return failure(usageError("INVALID_ARGUMENT", "claim accepts exactly one --resource/--mode pair.", {
+            pair_count: parsed.value.pairs.length,
+        }));
+    }
+    const [pair] = parsed.value.pairs;
+    return {
+        ok: true,
+        value: {
+            session_id: parsed.value.session_id,
+            repository: parsed.value.repository,
+            resource: pair.resource,
+            mode: pair.mode,
+        },
+    };
+}
 function sessionListingOptions(parsed) {
     const parseInteger = (option, value) => {
         if (value === null)
@@ -557,25 +684,33 @@ async function executeCommand(commandArguments, dependencies) {
         if (subcommand === undefined) {
             return failure(usageError("MISSING_ARGUMENT", "session requires a subcommand."));
         }
-        if (subcommand === "claim" || subcommand === "update") {
-            const parsed = parseOptions(rest, new Set(["--session", "--resource", "--mode", "--repository"]));
+        if (subcommand === "claim") {
+            const parsed = parseSingleClaimPair(rest);
             if (!parsed.ok)
                 return parsed;
-            if (parsed.value.resource === null) {
-                return failure(usageError("MISSING_ARGUMENT", "--resource requires a value.", { option: "--resource" }));
-            }
-            if (parsed.value.mode === null) {
-                return failure(usageError("MISSING_ARGUMENT", "--mode requires a value.", { option: "--mode" }));
-            }
-            const options = {
+            if (dependencies.backend.claimResources === undefined)
+                return claimCapabilityUnavailable(subcommand);
+            const result = await dependencies.backend.claimResources(context, {
                 session_id: parsed.value.session_id,
                 repository: parsed.value.repository,
                 claims: [{ resource: parsed.value.resource, mode: parsed.value.mode }],
-            };
-            const operation = subcommand === "claim" ? dependencies.backend.claimResources : dependencies.backend.updateClaims;
-            if (operation === undefined)
+            });
+            return result.ok ? { ok: true, value: result.value } : result;
+        }
+        if (subcommand === "update") {
+            const parsed = parseClaimReplacementPairs(rest);
+            if (!parsed.ok)
+                return parsed;
+            if (dependencies.backend.updateClaims === undefined)
                 return claimCapabilityUnavailable(subcommand);
-            const result = await operation.call(dependencies.backend, context, options);
+            const result = await dependencies.backend.updateClaims(context, {
+                session_id: parsed.value.session_id,
+                repository: parsed.value.repository,
+                claims: parsed.value.pairs.map((pair) => ({
+                    resource: pair.resource,
+                    mode: pair.mode,
+                })),
+            });
             return result.ok ? { ok: true, value: result.value } : result;
         }
         if (subcommand === "claims") {
@@ -612,6 +747,28 @@ async function executeCommand(commandArguments, dependencies) {
             const result = await dependencies.backend.createSession(context, options);
             return result.ok ? { ok: true, value: result.value } : result;
         }
+        if (subcommand === "run" || subcommand === "exec") {
+            const delimiter = rest.indexOf("--");
+            if (delimiter === -1) {
+                return failure(usageError("MISSING_ARGUMENT", "session run requires a -- terminator before the command."));
+            }
+            const parsed = parseOptions(rest.slice(0, delimiter), new Set(["--session"]));
+            if (!parsed.ok)
+                return parsed;
+            const command = rest[delimiter + 1];
+            if (command === undefined || command.length === 0) {
+                return failure(usageError("MISSING_ARGUMENT", "session run requires a command after --."));
+            }
+            const request = await resolveSandboxExecutionRequest(dependencies.backend, context, { session_id: parsed.value.session_id, enforce: true }, dependencies.sandboxProbe, dependencies.sandboxRuntimeLayout);
+            if (!request.ok)
+                return request;
+            const runner = dependencies.sandboxRunner ?? runSandboxedCommand;
+            const result = await runner(request.value, {
+                command,
+                args: rest.slice(delimiter + 2),
+            });
+            return result.ok ? { ok: true, value: result.value } : result;
+        }
         if (subcommand === "id" || subcommand === "show" || subcommand === "close") {
             if (subcommand === "id") {
                 const parsed = noOptions(rest);
@@ -647,23 +804,35 @@ async function executeCommand(commandArguments, dependencies) {
     }
     if (command === "resource") {
         const resourceSubcommand = subcommand ?? "list";
-        if (resourceSubcommand === "claim" || resourceSubcommand === "update") {
-            const parsed = parseOptions(rest, new Set(["--session", "--resource", "--mode", "--repository"]));
+        if (resourceSubcommand === "claim") {
+            const parsed = parseSingleClaimPair(rest);
             if (!parsed.ok)
                 return parsed;
-            if (parsed.value.resource === null || parsed.value.mode === null) {
-                return failure(usageError("MISSING_ARGUMENT", "resource claim requires --resource and --mode."));
-            }
-            const operation = resourceSubcommand === "claim" ? dependencies.backend.claimResources : dependencies.backend.updateClaims;
-            if (operation === undefined)
+            if (dependencies.backend.claimResources === undefined)
                 return claimCapabilityUnavailable(resourceSubcommand);
-            const result = await operation.call(dependencies.backend, context, {
+            const result = await dependencies.backend.claimResources(context, {
                 session_id: parsed.value.session_id,
                 repository: parsed.value.repository,
                 claims: [{ resource: parsed.value.resource, mode: parsed.value.mode }],
             });
             return result.ok ? { ok: true, value: result.value } : result;
         }
+        if (resourceSubcommand === "update") {
+            const parsed = parseClaimReplacementPairs(rest);
+            if (!parsed.ok)
+                return parsed;
+            if (dependencies.backend.updateClaims === undefined)
+                return claimCapabilityUnavailable(resourceSubcommand);
+            const result = await dependencies.backend.updateClaims(context, {
+                session_id: parsed.value.session_id,
+                repository: parsed.value.repository,
+                claims: parsed.value.pairs.map((pair) => ({
+                    resource: pair.resource,
+                    mode: pair.mode,
+                })),
+            });
+            return result.ok ? { ok: true, value: result.value } : result;
+        }
         if (resourceSubcommand === "list" || resourceSubcommand === "claims") {
             const parsed = parseOptions(rest, new Set(["--session"]));
             if (!parsed.ok)
@@ -963,7 +1132,9 @@ function emitFailure(mode, command, error, io) {
 }
 export async function runCli(argv, dependencies = {}) {
     const io = dependencies.io ?? defaultCliIO();
-    const mode = argv.includes("--json") ? "json" : "human";
+    const delimiter = argv.indexOf("--");
+    const globalArguments = delimiter === -1 ? argv : argv.slice(0, delimiter);
+    const mode = globalArguments.includes("--json") ? "json" : "human";
     const parsed = parseGlobalArguments(argv);
     if (!parsed.ok)
         return emitFailure(mode, "cli", parsed.error, io);
@@ -1004,10 +1175,23 @@ export async function runCli(argv, dependencies = {}) {
     const cwd = dependencies.cwd ?? process.cwd();
     try {
         const backend = dependencies.backend ?? createLocalSessionBackend();
-        const result = await executeCommand(parsed.value.commandArguments, { backend, cwd });
+        const result = await executeCommand(parsed.value.commandArguments, {
+            backend,
+            cwd,
+            sandboxRunner: dependencies.sandboxRunner,
+            sandboxProbe: dependencies.sandboxProbe,
+            sandboxRuntimeLayout: dependencies.sandboxRuntimeLayout,
+        });
         if (!result.ok)
             return emitFailure(mode, command, result.error, io);
         io.stdout(renderSuccess(mode, command, result.value));
+        if ((command === "session run" || command === "session exec") &&
+            typeof result.value.exit_code === "number" &&
+            result.value.exit_code !== 0) {
+            return result.value.exit_code >= 1 && result.value.exit_code <= 255
+                ? result.value.exit_code
+                : EXIT_CODES.rejected;
+        }
         return EXIT_CODES.success;
     }
     catch {