@cabane/companion 0.6.132 → 0.6.134

package/README.md

@@ -232,8 +232,9 @@ A `coding` agent needs a directory to run in — a path that only exists on your
 {
   // …device identity, managed by `pair`; don't hand-edit those fields…
 
-  // Per-agent machine-local overrides. Only `cwd` and `prepareHook` live here —
-  // everything else about the agent (mode, MCP servers, model) is set in Cabane.
+  // Per-agent machine-local overrides. Only `cwd`, `prepareHook`, `claudeCode` and
+  // `sandbox` live here — everything else about the agent (mode, MCP servers,
+  // model) is set in Cabane.
   "agents": {
     "my-coding-agent": {
       "cwd": "/Users/you/code/project", // working directory the agent runs in
@@ -310,18 +311,37 @@ What the sandbox allows is `runners.policy` in `~/.cabane/config.json`. Every ke
 }
 ```
 
-| Setting                                   | Default                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Hosts**, always reachable               | Cabane, and the model provider of the turn's harness (Anthropic for Claude Code, OpenAI for Codex). `allow` and `defaults` never remove these; a `deny` entry naming one does, and blocks the turn from reaching it.                                                                                                                                                                                                                                                                                                                                                            |
-| **Hosts**, `defaults`                     | `github.com`, `*.github.com`, `*.githubusercontent.com`, `registry.npmjs.org`, `pypi.org`, `files.pythonhosted.org`, `crates.io`, `static.crates.io`, `index.crates.io`. `allow` adds to them, `deny` removes a host (and wins), `defaults: false` drops the list.                                                                                                                                                                                                                                                                                                              |
-| **Reads**, `blocklist` mode (the default) | Everything is readable except every companion's store (`~/.cabane`, and any `.cabane` under your home or beside this companion's home; see below), the `.claude` and `.codex` of the other companion homes those stores sit in, `~/.ssh`, `~/.aws`, `~/.gnupg`, `~/.config/gh`, `~/.git-credentials`, `~/.netrc`, `~/.npmrc`, `~/.pypirc`, `~/.docker/config.json`, `~/.kube`, `~/.config/gcloud`, `~/.azure`, `~/.config/op`, `~/.password-store`, any `.env` or `.env.*` in the working directory, and your `denyRead` paths. `allowRead` reopens a path inside a denied one. |
-| **Writes**                                | The working directory, the temp dir, `~/.claude`, `~/.claude.json`, `~/.codex`, plus `allowWrite`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| Setting                                   | Default                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Hosts**, always reachable               | Cabane, and the model provider of the turn's harness (Anthropic for Claude Code, OpenAI for Codex). `allow` and `defaults` never remove these; a `deny` entry naming one does, and blocks the turn from reaching it.                                                                                                                                                                                                                                                                                                           |
+| **Hosts**, `defaults`                     | `github.com`, `*.github.com`, `*.githubusercontent.com`, `registry.npmjs.org`, `pypi.org`, `files.pythonhosted.org`, `crates.io`, `static.crates.io`, `index.crates.io`. `allow` adds to them, `deny` removes a host (and wins), `defaults: false` drops the list.                                                                                                                                                                                                                                                             |
+| **Reads**, `blocklist` mode (the default) | Everything is readable except every companion's store (`~/.cabane`, and any `.cabane` under your home or beside this companion's home; see below), the `.claude` and `.codex` of the other companion homes those stores sit in, `~/.ssh`, `~/.aws`, `~/.gnupg`, `~/.config/gh`, `~/.git-credentials`, `~/.netrc`, `~/.npmrc`, `~/.pypirc`, `~/.docker/config.json`, `~/.kube`, `~/.config/gcloud`, `~/.azure`, `~/.config/op`, `~/.password-store`, and your `denyRead` paths. `allowRead` reopens a path inside a denied one. |
+| **Writes**                                | The working directory, the temp dir, `~/.claude`, `~/.claude.json`, `~/.codex`, plus `allowWrite`.                                                                                                                                                                                                                                                                                                                                                                                                                             |
+
+**One agent can be excepted.** The sandbox is set per device, and one agent's row in `agents` can say otherwise — for example an ops agent whose job is the machine itself, on a device whose other agents stay sandboxed:
+
+```jsonc
+{
+  "runners": {
+    "enabled": true,
+    "sandbox": "os",
+    "policy": {
+      /* unchanged */
+    },
+  },
+  "agents": {
+    "014d18a7-6395-48e3-a2f2-313d5baa2a5e": { "sandbox": "none" }, // the ops agent, by its id: it runs with the machine; everyone else stays sandboxed
+  },
+}
+```
+
+It works the other way too: `"agents": { "<agent id>": { "sandbox": "os" } }` sandboxes one agent on a device that otherwise isn't. **A sandbox row is keyed by the agent's id**, the last part of the agent's settings page URL in Cabane (`/<workspace>/settings/agents/<agent id>`). A username, or `workspace-slug/username`, can match more than one agent: slugs are unique only per workspace owner, so two workspaces this device serves can share one. A `sandbox` row keyed any other way is refused at start, with the field named. `cwd` and `prepareHook` rows still take all three keys. The agent's row wins, then `runners.sandbox`, then no sandbox. The policy stays the device's. Under the `docker` provider the container is the sandbox, so a row's `sandbox` is ignored, and the log says so at start. The exception is set only here: Cabane shows it on the device page and can't change it.
 
 Paths may start with `~/` and may be globs. An invalid `policy` doesn't stop the Companion from starting. Instead, every sandboxed turn is refused and the conversation names the field that's wrong, for example `runners.policy.filesystem.mode`.
 
 **Other companions on the same machine.** A second companion (another account, a test device) keeps its own secrets in its own `.cabane`, so a turn can't read any companion's store, not only this device's. Every turn denies this companion's store and `~/.cabane` (both, when the Companion runs from a home set with `CABANE_COMPANION_HOME`), plus any `.cabane` up to two levels under your home or beside this companion's home, where companion homes conventionally sit. Stores anywhere deeper are found by a search of your home with `find`, along with the `.claude` and `.codex` beside each one, which hold that companion's harness logins. That search takes seconds over a large home, so the Companion runs it in the background: when it starts, and again whenever a turn starts more than 5 minutes after the last search finished. Only the first turn after a start waits for it. **A store created deeper than two levels is denied within about 5 minutes plus one search, not instantly.** If a search can't finish (`find` is missing, runs past 60 seconds, or hits a directory it can't list), the stores it did find are still denied, and the log says so. The search runs in strict mode too, because strict mode reopens the working directory, and a store inside it must stay hidden.
 
-**`.env` files in other projects.** Only the working directory's `.env` files are denied by default. Another project's `.env` stays readable by its absolute path. If your other projects hold secrets, list their roots, for example `"denyRead": ["~/work/**/.env", "~/work/**/.env.*"]`. Each glob is expanded when the turn starts, which costs a walk of that tree on every turn and misses files created during the turn. When other projects' secrets really matter, strict mode is the better answer, because it hides them all without a walk.
+**`.env` files are readable.** Beyond the credential locations above, nothing guesses which of your files hold secrets, so `.env` files, in the working directory or any other project, are readable unless you deny them. To hide them, list the roots that hold them, for example `"denyRead": ["~/work/**/.env", "~/work/**/.env.*"]`. Each glob is expanded when the turn starts, which costs a walk of that tree on every turn and misses files created during the turn, so keep the roots narrow. When other projects' secrets really matter, strict mode is the better answer, because it hides them all without a walk.
 
 **Strict mode.** `"filesystem": { "mode": "strict" }` hides your whole home directory except the working directory, the harness state (`~/.claude`, `~/.codex`), what the Companion and its harnesses run from, and the paths you list in `allowRead`. Toolchains live all over a home directory (`~/.nvm`, `~/.local/share/pnpm`, `~/.cargo`, `~/.pyenv`, mise or asdf shims), so list yours, or builds will fail with "No such file or directory" on a path you didn't expect. On Linux a hidden path looks missing rather than denied, so the Companion log prints the readable list at the start of each strict turn. Compare it against the path the build couldn't find.
 
@@ -336,7 +356,7 @@ Paths may start with `~/` and may be globs. An invalid `policy` doesn't stop the
 
 A `gh auth login` session on the machine isn't used: `~/.config/gh` is unreadable in the sandbox. Only the token in `secrets.json` is.
 
-`cabane-companion status` prints the effective posture: the filesystem mode, extra hosts, denied hosts and reads, and the **names** of masked credentials, never their values. The Companion also logs it once at start.
+`cabane-companion status` prints the effective posture: the filesystem mode, extra hosts, denied hosts and reads, the **names** of masked credentials, never their values, and each agent excepted on its row. The Companion also logs it once at start.
 
 ## Harnesses
 

package/dist/cli.js

@@ -295,6 +295,28 @@ function localAgentConfig(cfg, agent) {
   if (!cfg.prepareHook || row.prepareHook) return row;
   return { ...row, prepareHook: cfg.prepareHook };
 }
+function agentSandbox(cfg, agent) {
+  const sandbox = cfg.agents?.[agent.agentId]?.sandbox;
+  return sandbox ? { sandbox } : {};
+}
+function runnerSandboxFor(cfg, row, host) {
+  const asked = row.sandbox ?? cfg.runners?.sandbox ?? "none";
+  if (asked !== "os" || cfg.runners?.provider === "docker") return "none";
+  return host.osSandboxUsable() ? "os" : "none";
+}
+function runnerSandboxReport(cfg, agents, host) {
+  const device = runnerSandboxFor(cfg, {}, host);
+  const sandboxOverrides = agents.flatMap((agent) => {
+    const sandbox = runnerSandboxFor(cfg, agentSandbox(cfg, agent), host);
+    return sandbox === device ? [] : [{ agentId: agent.agentId, sandbox }];
+  });
+  return { sandbox: device, sandboxOverrides };
+}
+function agentSandboxRows(cfg) {
+  return Object.entries(cfg.agents ?? {}).flatMap(
+    ([key, row]) => row.sandbox ? [[key, row.sandbox]] : []
+  );
+}
 function loadConfig() {
   const path = configPath();
   if (!existsSync(path)) return null;
@@ -370,7 +392,7 @@ function loadConfigTolerant() {
   }
   const obj = parsed && typeof parsed === "object" ? parsed : {};
   const local = {};
-  const agents = z2.record(z2.string(), localAgentConfigSchema).safeParse(obj.agents);
+  const agents = agentsConfigSchema.safeParse(obj.agents);
   if (agents.success) local.agents = agents.data;
   const prepareHook = prepareHookSchema.safeParse(obj.prepareHook);
   if (prepareHook.success) local.prepareHook = prepareHook.data;
@@ -426,7 +448,7 @@ function deleteConfig() {
     writeFileSync(path, "", { mode: 384 });
   }
 }
-var realHomeCache, localAgentConfigSchema, companionConfigSchema;
+var realHomeCache, localAgentConfigSchema, AGENT_ID_KEY, agentsConfigSchema, companionConfigSchema;
 var init_config = __esm({
   "src/config.ts"() {
     "use strict";
@@ -443,8 +465,25 @@ var init_config = __esm({
       // auto-memory back to your own `~/.claude/settings.json` — Cabane then stops
       // injecting the off switch and your normal Claude Code memory workflow applies
       // (in coding mode, where the checkout's project settings are read).
-      claudeCode: z2.object({ autoMemory: z2.boolean().optional() }).strict().optional()
+      claudeCode: z2.object({ autoMemory: z2.boolean().optional() }).strict().optional(),
+      // CT1693: this agent's exception to `runners.sandbox` — an ops agent that
+      // runs with the machine on a sandboxed device, or one sandboxed agent on a
+      // device that isn't. Absent is "inherit"; see `runnerSandboxFor`. Only on a
+      // row keyed by the agent's id (`agentsConfigSchema`).
+      sandbox: z2.enum(["os", "none"]).optional()
     }).strict();
+    AGENT_ID_KEY = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+    agentsConfigSchema = z2.record(z2.string(), localAgentConfigSchema).superRefine((agents, ctx) => {
+      for (const [key, row] of Object.entries(agents)) {
+        if (row.sandbox === void 0) continue;
+        if (AGENT_ID_KEY.test(key)) continue;
+        ctx.addIssue({
+          code: z2.ZodIssueCode.custom,
+          path: [key, "sandbox"],
+          message: "a sandbox exception must name one agent \u2014 key the row by the agent's id (shown in Cabane), not a username or workspace-slug/username"
+        });
+      }
+    });
     companionConfigSchema = z2.object({
       // The cabane instance this device is paired with. SJ515: https-enforced
       // (loopback exempt) so a hand-edited config can't smuggle a plaintext-http
@@ -465,7 +504,7 @@ var init_config = __esm({
       // Optional per-agent machine-local overrides (cwd / prepareHook), keyed by
       // agentId / username / `slug/username`. Hand-added by the operator; the companion
       // never writes this (it only persists credentials + the device, elsewhere).
-      agents: z2.record(z2.string(), localAgentConfigSchema).optional(),
+      agents: agentsConfigSchema.optional(),
       // CT1095: the DEVICE-LEVEL prepare hook — one entry that applies to every agent
       // assigned to this device, unless that agent's own `agents` row names a hook of
       // its own.
@@ -10520,7 +10559,6 @@ function harnessSandboxConfig(input) {
     ...policy.hosts?.allow ?? []
   ];
   const allowedDomains = [.../* @__PURE__ */ new Set([...cabane, ...models, ...reachable])];
-  const envGlobs = input.cwd ? [join18(input.cwd, "**/.env"), join18(input.cwd, "**/.env.*")] : [];
   const secrets = [
     ...companionStoreDenies({
       homes,
@@ -10529,7 +10567,6 @@ function harnessSandboxConfig(input) {
       ownState: [claudeDir, codexDir]
     }),
     ...homes.flatMap((home) => SECRET_PATHS_UNDER_HOME.map((p) => join18(home, p))),
-    ...envGlobs,
     ...expand(policy.filesystem?.denyRead)
   ];
   const strict = policy.filesystem?.mode === "strict";
@@ -11652,7 +11689,7 @@ function buildCompanionManifest(opts) {
     runtimes,
     capabilities: { ...DEVICE_MANIFEST.capabilities },
     runtimeIssues: opts.runtimeIssues ?? [],
-    ...opts.runnerProvider ? { runner: { provider: opts.runnerProvider } } : {}
+    ...opts.runner ? { runner: opts.runner } : {}
   };
 }
 function runtimeIssuesFor(gates) {
@@ -15279,10 +15316,21 @@ var CompanionSupervisor = class {
       }
       this.latchBootBundledState();
     }
-    if (this.runnerSandbox() === "os") {
+    const sandboxRows = agentSandboxRows(this.config);
+    if (sandboxRows.length > 0 && this.dockerRunners()) {
+      this.log.warn(
+        { agents: sandboxRows.map(([key]) => key) },
+        `runners: ${sandboxRows.map(([key]) => `agents.${key}.sandbox`).join(", ")} ignored \u2014 under Docker the container is the sandbox`
+      );
+    }
+    const anySandboxed = [{}, ...sandboxRows.map(([, sandbox]) => ({ sandbox }))].some(
+      (row) => this.runnerSandboxFor(row) === "os"
+    );
+    if (anySandboxed) {
       const policy = this.sandboxPolicy();
       const posture = postureLines(policy);
-      const summary = posture.join("; ");
+      const perAgent = sandboxRows.map(([key, sandbox]) => `${key} \u2192 ${sandbox}`).join(", ");
+      const summary = posture.join("; ") + (perAgent ? `; per-agent: ${perAgent}` : "");
       if (policy.ok) this.log.info({ posture }, `runners: OS sandbox policy \u2014 ${summary}`);
       else this.log.error({ posture }, `runners: ${summary}`);
       void this.companionStores().refresh();
@@ -15396,7 +15444,7 @@ var CompanionSupervisor = class {
           // (fail-soft to null). Informational only — the server matches on name.
           versions: this.harnessVersions,
           // CT1681: shown on the device page.
-          ...runnersEnabled(this.config) ? { runnerProvider: this.config.runners?.provider ?? "local-process" } : {}
+          ...runnersEnabled(this.config) ? { runner: this.runnerManifest() } : {}
         }),
         // CT566: echo the last classified credential state per runtime, when the
         // companion has seen any. Omitted (undefined) until the first observed
@@ -15728,6 +15776,9 @@ var CompanionSupervisor = class {
   // CT1679: `runners.sandbox`, checked against this host once. A host that
   // can't make the sandbox says so once and runs its turns unwrapped.
   sandboxUsable;
+  sandboxHost = {
+    osSandboxUsable: () => this.sandboxUsable ??= osSandboxUsable(this.log)
+  };
   // CT1684: `runners.policy`, parsed once. An invalid one is kept as the
   // error, which every sandboxed turn is refused with.
   parsedSandboxPolicy;
@@ -15741,10 +15792,26 @@ var CompanionSupervisor = class {
     this.storeWatch ??= companionStoreWatch(this.log);
     return this.storeWatch;
   }
-  runnerSandbox() {
-    if (this.config.runners?.sandbox !== "os" || this.dockerRunners()) return "none";
-    this.sandboxUsable ??= osSandboxUsable(this.log);
-    return this.sandboxUsable ? "os" : "none";
+  // CT1693: the sandbox one agent's turns run under — its `agents` row, then
+  // the device's. Resolved from the current config every time it's asked, so
+  // a reload changes it; only the host probe is kept.
+  runnerSandboxFor(row) {
+    return runnerSandboxFor(this.config, row, this.sandboxHost);
+  }
+  // CT1693: what the heartbeat says about this device's runners, resolved
+  // against the agents it runs right now.
+  runnerManifest() {
+    const agents = [...this.workspaces.values()].flatMap(
+      (wr) => [...wr.agents.values()].map((agent) => ({
+        agentId: agent.agentId,
+        agentUsername: agent.username,
+        workspaceSlug: wr.slug
+      }))
+    );
+    return {
+      provider: this.config.runners?.provider ?? "local-process",
+      ...runnerSandboxReport(this.config, agents, this.sandboxHost)
+    };
   }
   // CT1679: one provider for the device, built on first use.
   runnerProvider() {
@@ -15860,7 +15927,7 @@ var CompanionSupervisor = class {
           reportRunnerGone: (report) => this.reportRunnerGone(report),
           connectorHealth: this.connectorHealth,
           locks: this.runnerLocks,
-          sandbox: this.runnerSandbox(),
+          sandbox: this.runnerSandboxFor(agentSandbox(this.config, ctx)),
           policy: this.sandboxPolicy(),
           companionStores: () => this.companionStores().stores()
         }
@@ -17205,19 +17272,36 @@ async function status() {
     process.stdout.write(`prepare hook: ${cfg.prepareHook.command} (device-level, all agents)
 `);
   }
-  if (runnersEnabled(cfg) && cfg.runners?.sandbox === "os") {
-    process.stdout.write("sandbox:      os\n");
-    for (const line of postureLines(parseSandboxPolicy(cfg.runners.policy))) {
-      process.stdout.write(`  ${line}
+  for (const line of sandboxStatusLines(cfg)) process.stdout.write(`${line}
 `);
-    }
-  }
   const overrides2 = Object.keys(cfg.agents ?? {});
   if (overrides2.length > 0) {
     process.stdout.write(`local overrides for: ${overrides2.join(", ")}
 `);
   }
 }
+function sandboxStatusLines(cfg) {
+  const rows = agentSandboxRows(cfg);
+  const device = cfg.runners?.sandbox ?? "none";
+  if (!runnersEnabled(cfg)) {
+    if (rows.length === 0) return [];
+    const fields = rows.map(([key]) => `agents.${key}.sandbox`).join(", ");
+    return [`sandbox:      off (runners.enabled is false; ${fields} has no effect)`];
+  }
+  if (cfg.runners?.provider === "docker") {
+    if (rows.length === 0) return [];
+    const fields = rows.map(([key]) => `agents.${key}.sandbox`).join(", ");
+    return [`sandbox:      docker (the container is the sandbox; ${fields} is ignored)`];
+  }
+  if (device !== "os" && !rows.some(([, sandbox]) => sandbox === "os")) return [];
+  return [
+    `sandbox:      ${device}`,
+    ...postureLines(parseSandboxPolicy(cfg.runners?.policy)).map((line) => `  ${line}`),
+    ...rows.map(
+      ([key, sandbox]) => `  ${key}: ${sandbox} (this agent runs ${sandbox === "os" ? "sandboxed" : "unsandboxed"})`
+    )
+  ];
+}
 function transcriptsLine() {
   const dir2 = transcriptsDir();
   let count = 0;

package/dist/pairing-config.js

@@ -129,8 +129,25 @@ var localAgentConfigSchema = z2.object({
   // auto-memory back to your own `~/.claude/settings.json` — Cabane then stops
   // injecting the off switch and your normal Claude Code memory workflow applies
   // (in coding mode, where the checkout's project settings are read).
-  claudeCode: z2.object({ autoMemory: z2.boolean().optional() }).strict().optional()
+  claudeCode: z2.object({ autoMemory: z2.boolean().optional() }).strict().optional(),
+  // CT1693: this agent's exception to `runners.sandbox` — an ops agent that
+  // runs with the machine on a sandboxed device, or one sandboxed agent on a
+  // device that isn't. Absent is "inherit"; see `runnerSandboxFor`. Only on a
+  // row keyed by the agent's id (`agentsConfigSchema`).
+  sandbox: z2.enum(["os", "none"]).optional()
 }).strict();
+var AGENT_ID_KEY = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+var agentsConfigSchema = z2.record(z2.string(), localAgentConfigSchema).superRefine((agents, ctx) => {
+  for (const [key, row] of Object.entries(agents)) {
+    if (row.sandbox === void 0) continue;
+    if (AGENT_ID_KEY.test(key)) continue;
+    ctx.addIssue({
+      code: z2.ZodIssueCode.custom,
+      path: [key, "sandbox"],
+      message: "a sandbox exception must name one agent \u2014 key the row by the agent's id (shown in Cabane), not a username or workspace-slug/username"
+    });
+  }
+});
 var companionConfigSchema = z2.object({
   // The cabane instance this device is paired with. SJ515: https-enforced
   // (loopback exempt) so a hand-edited config can't smuggle a plaintext-http
@@ -151,7 +168,7 @@ var companionConfigSchema = z2.object({
   // Optional per-agent machine-local overrides (cwd / prepareHook), keyed by
   // agentId / username / `slug/username`. Hand-added by the operator; the companion
   // never writes this (it only persists credentials + the device, elsewhere).
-  agents: z2.record(z2.string(), localAgentConfigSchema).optional(),
+  agents: agentsConfigSchema.optional(),
   // CT1095: the DEVICE-LEVEL prepare hook — one entry that applies to every agent
   // assigned to this device, unless that agent's own `agents` row names a hook of
   // its own.
@@ -343,7 +360,7 @@ function loadConfigTolerant() {
   }
   const obj = parsed && typeof parsed === "object" ? parsed : {};
   const local = {};
-  const agents = z2.record(z2.string(), localAgentConfigSchema).safeParse(obj.agents);
+  const agents = agentsConfigSchema.safeParse(obj.agents);
   if (agents.success) local.agents = agents.data;
   const prepareHook = prepareHookSchema.safeParse(obj.prepareHook);
   if (prepareHook.success) local.prepareHook = prepareHook.data;

package/dist/runtime.js

@@ -260,8 +260,25 @@ var localAgentConfigSchema = z2.object({
   // auto-memory back to your own `~/.claude/settings.json` — Cabane then stops
   // injecting the off switch and your normal Claude Code memory workflow applies
   // (in coding mode, where the checkout's project settings are read).
-  claudeCode: z2.object({ autoMemory: z2.boolean().optional() }).strict().optional()
+  claudeCode: z2.object({ autoMemory: z2.boolean().optional() }).strict().optional(),
+  // CT1693: this agent's exception to `runners.sandbox` — an ops agent that
+  // runs with the machine on a sandboxed device, or one sandboxed agent on a
+  // device that isn't. Absent is "inherit"; see `runnerSandboxFor`. Only on a
+  // row keyed by the agent's id (`agentsConfigSchema`).
+  sandbox: z2.enum(["os", "none"]).optional()
 }).strict();
+var AGENT_ID_KEY = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+var agentsConfigSchema = z2.record(z2.string(), localAgentConfigSchema).superRefine((agents, ctx) => {
+  for (const [key, row] of Object.entries(agents)) {
+    if (row.sandbox === void 0) continue;
+    if (AGENT_ID_KEY.test(key)) continue;
+    ctx.addIssue({
+      code: z2.ZodIssueCode.custom,
+      path: [key, "sandbox"],
+      message: "a sandbox exception must name one agent \u2014 key the row by the agent's id (shown in Cabane), not a username or workspace-slug/username"
+    });
+  }
+});
 var companionConfigSchema = z2.object({
   // The cabane instance this device is paired with. SJ515: https-enforced
   // (loopback exempt) so a hand-edited config can't smuggle a plaintext-http
@@ -282,7 +299,7 @@ var companionConfigSchema = z2.object({
   // Optional per-agent machine-local overrides (cwd / prepareHook), keyed by
   // agentId / username / `slug/username`. Hand-added by the operator; the companion
   // never writes this (it only persists credentials + the device, elsewhere).
-  agents: z2.record(z2.string(), localAgentConfigSchema).optional(),
+  agents: agentsConfigSchema.optional(),
   // CT1095: the DEVICE-LEVEL prepare hook — one entry that applies to every agent
   // assigned to this device, unless that agent's own `agents` row names a hook of
   // its own.
@@ -421,6 +438,28 @@ function localAgentConfig(cfg, agent) {
   if (!cfg.prepareHook || row.prepareHook) return row;
   return { ...row, prepareHook: cfg.prepareHook };
 }
+function agentSandbox(cfg, agent) {
+  const sandbox = cfg.agents?.[agent.agentId]?.sandbox;
+  return sandbox ? { sandbox } : {};
+}
+function runnerSandboxFor(cfg, row, host) {
+  const asked = row.sandbox ?? cfg.runners?.sandbox ?? "none";
+  if (asked !== "os" || cfg.runners?.provider === "docker") return "none";
+  return host.osSandboxUsable() ? "os" : "none";
+}
+function runnerSandboxReport(cfg, agents, host) {
+  const device = runnerSandboxFor(cfg, {}, host);
+  const sandboxOverrides = agents.flatMap((agent) => {
+    const sandbox = runnerSandboxFor(cfg, agentSandbox(cfg, agent), host);
+    return sandbox === device ? [] : [{ agentId: agent.agentId, sandbox }];
+  });
+  return { sandbox: device, sandboxOverrides };
+}
+function agentSandboxRows(cfg) {
+  return Object.entries(cfg.agents ?? {}).flatMap(
+    ([key, row]) => row.sandbox ? [[key, row.sandbox]] : []
+  );
+}
 function loadConfig() {
   const path = configPath();
   if (!existsSync(path)) return null;
@@ -814,7 +853,7 @@ function buildCompanionManifest(opts) {
     runtimes,
     capabilities: { ...DEVICE_MANIFEST.capabilities },
     runtimeIssues: opts.runtimeIssues ?? [],
-    ...opts.runnerProvider ? { runner: { provider: opts.runnerProvider } } : {}
+    ...opts.runner ? { runner: opts.runner } : {}
   };
 }
 function runtimeIssuesFor(gates) {
@@ -13173,10 +13212,21 @@ var CompanionSupervisor = class {
       }
       this.latchBootBundledState();
     }
-    if (this.runnerSandbox() === "os") {
+    const sandboxRows = agentSandboxRows(this.config);
+    if (sandboxRows.length > 0 && this.dockerRunners()) {
+      this.log.warn(
+        { agents: sandboxRows.map(([key]) => key) },
+        `runners: ${sandboxRows.map(([key]) => `agents.${key}.sandbox`).join(", ")} ignored \u2014 under Docker the container is the sandbox`
+      );
+    }
+    const anySandboxed = [{}, ...sandboxRows.map(([, sandbox]) => ({ sandbox }))].some(
+      (row) => this.runnerSandboxFor(row) === "os"
+    );
+    if (anySandboxed) {
       const policy = this.sandboxPolicy();
       const posture = postureLines(policy);
-      const summary = posture.join("; ");
+      const perAgent = sandboxRows.map(([key, sandbox]) => `${key} \u2192 ${sandbox}`).join(", ");
+      const summary = posture.join("; ") + (perAgent ? `; per-agent: ${perAgent}` : "");
       if (policy.ok) this.log.info({ posture }, `runners: OS sandbox policy \u2014 ${summary}`);
       else this.log.error({ posture }, `runners: ${summary}`);
       void this.companionStores().refresh();
@@ -13290,7 +13340,7 @@ var CompanionSupervisor = class {
           // (fail-soft to null). Informational only — the server matches on name.
           versions: this.harnessVersions,
           // CT1681: shown on the device page.
-          ...runnersEnabled(this.config) ? { runnerProvider: this.config.runners?.provider ?? "local-process" } : {}
+          ...runnersEnabled(this.config) ? { runner: this.runnerManifest() } : {}
         }),
         // CT566: echo the last classified credential state per runtime, when the
         // companion has seen any. Omitted (undefined) until the first observed
@@ -13622,6 +13672,9 @@ var CompanionSupervisor = class {
   // CT1679: `runners.sandbox`, checked against this host once. A host that
   // can't make the sandbox says so once and runs its turns unwrapped.
   sandboxUsable;
+  sandboxHost = {
+    osSandboxUsable: () => this.sandboxUsable ??= osSandboxUsable(this.log)
+  };
   // CT1684: `runners.policy`, parsed once. An invalid one is kept as the
   // error, which every sandboxed turn is refused with.
   parsedSandboxPolicy;
@@ -13635,10 +13688,26 @@ var CompanionSupervisor = class {
     this.storeWatch ??= companionStoreWatch(this.log);
     return this.storeWatch;
   }
-  runnerSandbox() {
-    if (this.config.runners?.sandbox !== "os" || this.dockerRunners()) return "none";
-    this.sandboxUsable ??= osSandboxUsable(this.log);
-    return this.sandboxUsable ? "os" : "none";
+  // CT1693: the sandbox one agent's turns run under — its `agents` row, then
+  // the device's. Resolved from the current config every time it's asked, so
+  // a reload changes it; only the host probe is kept.
+  runnerSandboxFor(row) {
+    return runnerSandboxFor(this.config, row, this.sandboxHost);
+  }
+  // CT1693: what the heartbeat says about this device's runners, resolved
+  // against the agents it runs right now.
+  runnerManifest() {
+    const agents = [...this.workspaces.values()].flatMap(
+      (wr) => [...wr.agents.values()].map((agent) => ({
+        agentId: agent.agentId,
+        agentUsername: agent.username,
+        workspaceSlug: wr.slug
+      }))
+    );
+    return {
+      provider: this.config.runners?.provider ?? "local-process",
+      ...runnerSandboxReport(this.config, agents, this.sandboxHost)
+    };
   }
   // CT1679: one provider for the device, built on first use.
   runnerProvider() {
@@ -13754,7 +13823,7 @@ var CompanionSupervisor = class {
           reportRunnerGone: (report) => this.reportRunnerGone(report),
           connectorHealth: this.connectorHealth,
           locks: this.runnerLocks,
-          sandbox: this.runnerSandbox(),
+          sandbox: this.runnerSandboxFor(agentSandbox(this.config, ctx)),
           policy: this.sandboxPolicy(),
           companionStores: () => this.companionStores().stores()
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cabane/companion",
-  "version": "0.6.132",
+  "version": "0.6.134",
   "type": "module",
   "description": "The Cabane Companion (headless): connect a coding agent on your machine to your Cabane workspace as a responder — drive work against your own codebase, files, and MCP servers without putting any of it in Cabane.",
   "license": "UNLICENSED",