@cabane/companion 0.6.103 → 0.6.104

package/dist/cli.js

@@ -1896,7 +1896,7 @@ async function pair(opts = {}) {
 }
 
 // src/cli.ts
-import { readFileSync as readFileSync11 } from "fs";
+import { readFileSync as readFileSync12 } from "fs";
 
 // src/commands/logs.ts
 import { once } from "events";
@@ -4641,7 +4641,39 @@ function buildClaudeCodeOptions(req, augment) {
     ...cwd ? { cwd } : {},
     // Extra env (a companion prepare hook's tokens/ports; the in-app's debug flags)
     // merged OVER the inherited environment.
-    ...req.local.env ? { env: { ...process.env, ...req.local.env } } : {},
+    //
+    // CT1503: and the background-tasks kill switch LAST, so nothing in
+    // `process.env` or `req.local.env` can turn it back on. Claude Code converts
+    // a foreground command that hits its Bash ceiling (600 000 ms) into a
+    // background task instead of erroring; the agent then reads a phantom task
+    // id inside a live turn. A later turn that resumed such a session was then
+    // seen getting every tool call aborted with kind `background` — which the CLI
+    // renders as "The user doesn't want to take this action right now", a
+    // cancellation wearing a refusal's words. The automatic conversion is
+    // REPRODUCED and is what this flag fixes; that the stopped task is what
+    // poisoned the resumed session is an INFERENCE from one incident, consistent
+    // with the transcript but never reproduced, and this change does not rest on
+    // it. `Dl()` reads this variable on the Bash tool's own call
+    // path and sets `canAutoBackground: false` and `turnAbortBackgrounds: false`
+    // together, so a timed-out command comes back as a readable error instead.
+    //
+    // The cost is acknowledged and deliberate: it ALSO removes deliberate
+    // `run_in_background` (the parameter leaves the tool schema). That is the
+    // only switch this harness offers, and there is no operator opt-out here on
+    // purpose — an escape hatch would contradict the guarantee. It is a targeted
+    // mitigation for the automatic conversion, NOT a cleanup mechanism: step 0
+    // measured that this flag changes no process-survival outcome on any turn-end
+    // path. Cleanup is its own change.
+    //
+    // Note `env` REPLACES the subprocess environment rather than merging (the
+    // SDK's own doc on `Options.env`), which is why `process.env` is spread here
+    // and why this key is now always present — previously it appeared only when
+    // `req.local.env` was set, and an absent `env` inherits `process.env`.
+    env: {
+      ...process.env,
+      ...req.local.env,
+      CLAUDE_CODE_DISABLE_BACKGROUND_TASKS: "1"
+    },
     ...resume ? { resume } : {}
   };
   let options;
@@ -8730,6 +8762,261 @@ function pruneOld(dir2, retain) {
   }
 }
 
+// src/turn-containment.ts
+import { execFile, execFileSync, spawn as spawn4 } from "child_process";
+import { readFileSync as readFileSync8 } from "fs";
+import { promisify } from "util";
+var execFileAsync = promisify(execFile);
+var asContained = (child) => child;
+var CONTAINMENT_STOP_GRACE_SEC = 5;
+var FALLBACK_GRACE_MS = CONTAINMENT_STOP_GRACE_SEC * 1e3;
+var CAPABILITY_PROBE_TIMEOUT_MS = 4e3;
+function turnScopeUnit(turnId, attempt) {
+  const safe3 = turnId.replace(/[^A-Za-z0-9_.-]/g, "-");
+  return `cabane-turn-${safe3}-${attempt}`;
+}
+function scopeCapabilityUsable(env, timeoutMs = CAPABILITY_PROBE_TIMEOUT_MS) {
+  if (process.platform !== "linux") return false;
+  try {
+    execFileSync("systemd-run", ["--user", "--scope", "--quiet", "--collect", "--", "/bin/true"], {
+      env,
+      timeout: timeoutMs,
+      stdio: "ignore"
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function classifyStopError(message) {
+  if (/failed to connect to bus|failed to get d-?bus connection|connection refused|refusing to operate|spawn systemctl|systemctl.*ENOENT|ENOENT.*systemctl/i.test(
+    message
+  )) {
+    return "failure";
+  }
+  if (/not loaded|could not be found|no such unit|unit .* not found/i.test(message))
+    return "absent";
+  return "failure";
+}
+function currentSystemdUnit(cgroupText) {
+  for (const line of cgroupText.split("\n")) {
+    const path = line.trim().split(":").pop();
+    if (!path?.startsWith("/")) continue;
+    const leaf = path.split("/").filter(Boolean).pop();
+    if (leaf && (leaf.endsWith(".service") || leaf.endsWith(".scope"))) return leaf;
+  }
+  return null;
+}
+function readCurrentSystemdUnit() {
+  try {
+    return currentSystemdUnit(readFileSync8("/proc/self/cgroup", "utf8"));
+  } catch {
+    return null;
+  }
+}
+function processGroupMembers(pgid) {
+  try {
+    const out = execFileSync("ps", ["-eo", "pid=,pgid="], { timeout: 5e3 }).toString();
+    return {
+      ok: true,
+      members: out.split("\n").map((line) => /^\s*(\d+)\s+(\d+)\s*$/.exec(line)).filter((m) => m !== null).filter((m) => Number(m[2]) === pgid && Number(m[1]) !== process.pid).map((m) => Number(m[1]))
+    };
+  } catch (err) {
+    return { ok: false, error: (err instanceof Error ? err.message : String(err)).slice(0, 150) };
+  }
+}
+var sleep3 = (ms) => new Promise((resolve2) => setTimeout(resolve2, ms));
+var MANAGER_ENV_KEYS = ["DBUS_SESSION_BUS_ADDRESS", "XDG_RUNTIME_DIR", "PATH"];
+var managerEnvKey = (env) => MANAGER_ENV_KEYS.map((k) => `${k}=${env[k] ?? ""}`).join("\0");
+function createTurnContainment(turnId, deps = {}) {
+  const probe = deps.capabilityProbe ?? scopeCapabilityUsable;
+  const ownUnit = (deps.ownSystemdUnit ?? readCurrentSystemdUnit)();
+  const scopeUnits = [];
+  const groups = [];
+  let kind = null;
+  let probedEnvKey = null;
+  let attempt = 0;
+  function spawnInScope(options) {
+    const unit = turnScopeUnit(turnId, attempt++);
+    scopeUnits.push({ unit, env: options.env });
+    deps.log?.("containment: spawning the turn CLI into a systemd scope", {
+      unit,
+      partOf: ownUnit,
+      command: options.command
+    });
+    return asContained(
+      spawn4(
+        "systemd-run",
+        [
+          "--user",
+          "--scope",
+          "--quiet",
+          "--collect",
+          `--unit=${unit}`,
+          `--property=TimeoutStopSec=${CONTAINMENT_STOP_GRACE_SEC}s`,
+          // Bind the scope's life to the companion's own unit, so stopping or
+          // restarting the companion still takes its in-flight turns with it —
+          // which is what happens today, and what the scope would otherwise undo.
+          // Omitted outside a unit, where there is nothing to bind to.
+          ...ownUnit ? [`--property=PartOf=${ownUnit}`] : [],
+          "--",
+          options.command,
+          ...options.args
+        ],
+        {
+          ...options.cwd ? { cwd: options.cwd } : {},
+          env: options.env,
+          stdio: ["pipe", "pipe", "pipe"]
+        }
+      )
+    );
+  }
+  function spawnInGroup(options) {
+    const child = spawn4(options.command, options.args, {
+      ...options.cwd ? { cwd: options.cwd } : {},
+      env: options.env,
+      stdio: ["pipe", "pipe", "pipe"],
+      detached: process.platform !== "win32"
+    });
+    if (child.pid !== void 0) groups.push({ pgid: child.pid, child });
+    deps.log?.("containment: no host-owned containment here \u2014 best effort only", {
+      platform: process.platform,
+      pid: child.pid
+    });
+    return asContained(child);
+  }
+  async function reapScopes(result) {
+    for (const { unit, env } of scopeUnits) {
+      try {
+        await execFileAsync("systemctl", ["--user", "stop", `${unit}.scope`], {
+          env,
+          timeout: (CONTAINMENT_STOP_GRACE_SEC + 10) * 1e3
+        });
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (classifyStopError(message) === "failure") {
+          result.failures.push({ target: unit, error: message.slice(0, 200) });
+          continue;
+        }
+        result.reaped.push(unit);
+        continue;
+      }
+      try {
+        const { stdout } = await execFileAsync(
+          "systemctl",
+          ["--user", "show", `${unit}.scope`, "--property=ActiveState", "--value"],
+          { env, timeout: 1e4 }
+        );
+        const state = stdout.trim();
+        if (state === "" || state === "inactive" || state === "failed") result.reaped.push(unit);
+        else result.failures.push({ target: unit, error: `scope still ${state} after stop` });
+      } catch (err) {
+        result.failures.push({
+          target: unit,
+          error: `could not confirm the scope stopped: ${(err instanceof Error ? err.message : String(err)).slice(0, 150)}`
+        });
+      }
+    }
+  }
+  async function reapGroups(result) {
+    for (const { pgid, child } of groups) {
+      const target = String(pgid);
+      if (process.platform === "win32") {
+        try {
+          if (child.exitCode === null) child.kill();
+          result.unverified.push(target);
+        } catch (err) {
+          result.failures.push({
+            target,
+            error: (err instanceof Error ? err.message : String(err)).slice(0, 200)
+          });
+        }
+        continue;
+      }
+      const first = processGroupMembers(pgid);
+      if (!first.ok) {
+        result.failures.push({
+          target,
+          error: `could not enumerate the process group: ${first.error}`
+        });
+        continue;
+      }
+      if (first.members.length === 0) {
+        result.reaped.push(target);
+        continue;
+      }
+      for (const pid of first.members) {
+        try {
+          process.kill(pid, "SIGTERM");
+        } catch {
+        }
+      }
+      await sleep3(FALLBACK_GRACE_MS);
+      const afterTerm = processGroupMembers(pgid);
+      if (!afterTerm.ok) {
+        result.failures.push({
+          target,
+          error: `could not re-enumerate the process group after SIGTERM: ${afterTerm.error}`
+        });
+        continue;
+      }
+      for (const pid of afterTerm.members) {
+        try {
+          process.kill(pid, "SIGKILL");
+        } catch {
+        }
+      }
+      const afterKill = processGroupMembers(pgid);
+      if (!afterKill.ok) {
+        result.failures.push({
+          target,
+          error: `could not confirm the process group is empty after SIGKILL: ${afterKill.error}`
+        });
+        continue;
+      }
+      if (afterKill.members.length)
+        result.failures.push({
+          target,
+          error: `${afterKill.members.length} process(es) still in the group after SIGKILL`
+        });
+      else result.reaped.push(target);
+    }
+  }
+  return {
+    get kind() {
+      return kind;
+    },
+    spawn(options) {
+      const envKey = managerEnvKey(options.env);
+      if (kind === null || envKey !== probedEnvKey) {
+        kind = probe(options.env) ? "systemd-scope" : "process-group";
+        probedEnvKey = envKey;
+        deps.log?.("containment: resolved strategy for this turn", {
+          kind,
+          platform: process.platform
+        });
+      }
+      return kind === "systemd-scope" ? spawnInScope(options) : spawnInGroup(options);
+    },
+    async reap() {
+      const result = {
+        kind: kind ?? "unused",
+        reaped: [],
+        failures: [],
+        unverified: []
+      };
+      await reapScopes(result);
+      await reapGroups(result);
+      deps.log?.("containment: reap complete", {
+        kind: result.kind,
+        reaped: result.reaped,
+        failures: result.failures
+      });
+      return result;
+    }
+  };
+}
+
 // src/turn-committer.ts
 var TurnCommitter = class {
   constructor(deps) {
@@ -8949,7 +9236,10 @@ function missingSecretReason(missing) {
 var RUNTIME_UNAVAILABLE_PREFIX = "**This agent's runtime isn't available on this companion.** The model this agent uses needs a runtime this device isn't running, so I can't run this turn here. Details:";
 var UNEXPECTED_ROLE_REASON = `refused the wake trigger (role "system" isn't dispatchable on this companion) \u2014 the companion is likely running outdated code; refresh it, then re-address the agent`;
 var DEFAULT_PREPARING_ROW_DELAY_MS = 1500;
-var DEFAULT_AGENT_IDLE_TIMEOUT_MS = 10 * 6e4;
+var DEFAULT_AGENT_IDLE_TIMEOUT_MS = 15 * 6e4;
+function resolveIdleTimeoutMs(override) {
+  return override ?? DEFAULT_AGENT_IDLE_TIMEOUT_MS;
+}
 var DEFAULT_AGENT_TOTAL_TIMEOUT_MS = 6 * 60 * 6e4;
 var DEFAULT_LEASE_RENEWAL_MS = 3e4;
 function initialOutcome() {
@@ -9007,6 +9297,11 @@ var TurnExecution = class {
   turnLog;
   abortController = new AbortController();
   outcome = initialOutcome();
+  // CT1503: this turn's shell containment, once the claude-code adapter is built.
+  // Null before that and on a turn that never reached adapter construction — a
+  // startup failure has nothing to reap, and reaping is a no-op rather than a
+  // special case.
+  containment = null;
   seqCounter = 0;
   // CT11: per-turn monotonic counter mirroring the in-process dispatcher's.
   //
@@ -9041,6 +9336,36 @@ var TurnExecution = class {
   };
   disarmWatchdogs = () => {
   };
+  // CT1503: reap this turn's shell containment. Idempotent (the containment drops
+  // what it has already stopped) and total — a reap that fails is reported and
+  // swallowed, because a turn that produced a good answer must not be recorded as
+  // failed on account of a leftover process, and the failure is visible in the log
+  // either way.
+  async reapContainment() {
+    const containment = this.containment;
+    if (!containment) return;
+    this.containment = null;
+    try {
+      const result = await containment.reap();
+      if (result.failures.length) {
+        this.turnLog.warn(
+          { kind: result.kind, failures: result.failures },
+          "turn containment: some of this turn\u2019s shell work could not be reaped"
+        );
+      }
+      if (result.unverified.length) {
+        this.turnLog.debug(
+          { kind: result.kind, unverified: result.unverified },
+          "turn containment: cleanup requested but not confirmable on this platform"
+        );
+      }
+    } catch (err) {
+      this.turnLog.warn(
+        { err: err instanceof Error ? err.message : String(err) },
+        "turn containment: reap threw"
+      );
+    }
+  }
   // Codo's stack review, blocking finding #2: set the moment `acquireLease`'s
   // PATCH returns — the lease is granted and this is the pair's running span,
   // so every exit after this point must settle THE SPAN, not just clear the
@@ -9431,7 +9756,20 @@ var TurnExecution = class {
     const onWarn = (msg, meta) => turnLog.debug(meta ?? {}, msg);
     const adapters = [];
     if (this.opts.claudeCodeAvailable?.() ?? true) {
-      adapters.push(createClaudeCodeAdapter({ queryFn: this.opts.queryFn, onWarn }));
+      this.containment = createTurnContainment(this.turnId, {
+        log: (msg, meta) => turnLog.debug(meta ?? {}, msg)
+      });
+      const containment = this.containment;
+      adapters.push(
+        createClaudeCodeAdapter({
+          queryFn: this.opts.queryFn,
+          onWarn,
+          augmentOptions: (options) => ({
+            ...options,
+            spawnClaudeCodeProcess: (spawnOptions) => containment.spawn(spawnOptions)
+          })
+        })
+      );
     }
     if (this.opts.opencodeServerUrl) {
       adapters.push(createOpencodeAdapter({ serverUrl: this.opts.opencodeServerUrl, onWarn }));
@@ -9573,7 +9911,7 @@ var TurnExecution = class {
         );
       }
     };
-    const idleTimeoutMs = this.opts.idleTimeoutMs ?? DEFAULT_AGENT_IDLE_TIMEOUT_MS;
+    const idleTimeoutMs = resolveIdleTimeoutMs(this.opts.idleTimeoutMs);
     const fireTimeout = (reason) => {
       if (abortController.signal.aborted) return;
       o.timeoutReason = reason;
@@ -9726,6 +10064,7 @@ var TurnExecution = class {
       );
     } finally {
       this.disarmWatchdogs();
+      await this.reapContainment();
       if (o.leaseLost) {
         o.resultReason = "lease_lost";
         o.okResult = false;
@@ -10031,7 +10370,7 @@ import {
   existsSync as existsSync12,
   mkdirSync as mkdirSync10,
   readdirSync as readdirSync3,
-  readFileSync as readFileSync8,
+  readFileSync as readFileSync9,
   renameSync as renameSync4,
   rmSync as rmSync7,
   writeFileSync as writeFileSync7
@@ -10096,7 +10435,7 @@ var Outbox = class {
       if (!name.endsWith(".json")) continue;
       const full = join16(dir2, name);
       try {
-        const parsed = JSON.parse(readFileSync8(full, "utf8"));
+        const parsed = JSON.parse(readFileSync9(full, "utf8"));
         if (parsed && typeof parsed.turnId === "string" && typeof parsed.seq === "number" && typeof parsed.path === "string") {
           entries.push(parsed);
         } else {
@@ -10277,7 +10616,7 @@ var SseSubscriber = class {
         backoff = 500;
         if (!this.aborted) {
           this.opts.log.warn("Lost the connection to Cabane; reconnecting");
-          await sleep3(backoff);
+          await sleep4(backoff);
         }
       } catch (err) {
         if (this.aborted) return;
@@ -10297,7 +10636,7 @@ var SseSubscriber = class {
           },
           "Lost the connection to Cabane; reconnecting"
         );
-        await sleep3(backoff);
+        await sleep4(backoff);
         backoff = Math.min(backoff * 2, MAX_BACKOFF_MS);
       }
     }
@@ -10349,7 +10688,7 @@ var SseSubscriber = class {
     }
   }
 };
-function sleep3(ms) {
+function sleep4(ms) {
   return new Promise((resolve2) => setTimeout(resolve2, ms));
 }
 
@@ -10917,7 +11256,9 @@ var CompanionSupervisor = class {
       codexAvailable: () => this.codexOffered(),
       // CT556: per-turn timeout watchdog windows, from the companion's own env
       // (`AGENT_IDLE_TIMEOUT_MS` / `AGENT_TOTAL_TIMEOUT_MS`). Unset → the
-      // dispatcher's baked-in defaults (10 min idle / 6h total).
+      // dispatcher's baked-in defaults (CT1503: 15 min idle / 6h total). An
+      // override set here still wins, and is deliberately not validated against
+      // the tool ceilings it may reorder — see DEFAULT_AGENT_IDLE_TIMEOUT_MS.
       ...positiveIntEnv("AGENT_IDLE_TIMEOUT_MS") !== void 0 ? { idleTimeoutMs: positiveIntEnv("AGENT_IDLE_TIMEOUT_MS") } : {},
       ...positiveIntEnv("AGENT_TOTAL_TIMEOUT_MS") !== void 0 ? { totalTimeoutMs: positiveIntEnv("AGENT_TOTAL_TIMEOUT_MS") } : {},
       observer: this.hub.observerFor(ctx.workspaceId, ctx.agentId, ctx.workspaceSlug),
@@ -11529,9 +11870,9 @@ async function waitForBoundedHeartbeat(heartbeat) {
 }
 function defaultReexec() {
   clearRuntimeState();
-  void import("child_process").then(({ spawn: spawn5 }) => {
+  void import("child_process").then(({ spawn: spawn6 }) => {
     try {
-      const child = spawn5(process.execPath, process.argv.slice(1), {
+      const child = spawn6(process.execPath, process.argv.slice(1), {
         stdio: "inherit",
         detached: false
       });
@@ -11601,7 +11942,7 @@ function handleUncaught(log, err, origin) {
 }
 
 // src/crash-marker.ts
-import { existsSync as existsSync13, mkdirSync as mkdirSync11, readFileSync as readFileSync9, rmSync as rmSync8, writeFileSync as writeFileSync8 } from "fs";
+import { existsSync as existsSync13, mkdirSync as mkdirSync11, readFileSync as readFileSync10, rmSync as rmSync8, writeFileSync as writeFileSync8 } from "fs";
 import { join as join17 } from "path";
 function crashMarkerPath() {
   return join17(cabaneDir(), "last-error.json");
@@ -11786,7 +12127,7 @@ async function closeSurfaces(control, dashboard) {
 }
 
 // src/commands/daemon.ts
-import { spawn as spawn4 } from "child_process";
+import { spawn as spawn5 } from "child_process";
 import { closeSync as closeSync3, mkdirSync as mkdirSync12, openSync as openSync3 } from "fs";
 
 // src/cli-entry.ts
@@ -11812,7 +12153,7 @@ async function startDaemon(opts = {}, deps = {}) {
   const readState = deps.readState ?? readLiveRuntimeState;
   const verify = deps.verify ?? ((s) => verifyRuntime(s));
   const spawnDetached = deps.spawnDetached ?? defaultSpawnDetached;
-  const sleep4 = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const sleep5 = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
   const now = deps.now ?? (() => Date.now());
   const quiet = opts.report === "failures";
   const { cfg, claudeOnPath: claudeOnPath2 } = await requireStartConfig({
@@ -11867,7 +12208,7 @@ Connect a harness to the running companion: cabane-companion connect claude-code
     const deadline = now() + STARTUP_TIMEOUT_MS;
     let seen = readState();
     while (!ready(seen) && now() < deadline) {
-      await sleep4(POLL_INTERVAL_MS);
+      await sleep5(POLL_INTERVAL_MS);
       seen = readState();
     }
     return ready(seen) ? seen : null;
@@ -11898,7 +12239,7 @@ function defaultSpawnDetached(args) {
   mkdirSync12(cabaneDir(), { recursive: true });
   const logFd = openSync3(companionLogPath(), "a");
   try {
-    return spawn4(process.execPath, [cliPath, ...args], {
+    return spawn5(process.execPath, [cliPath, ...args], {
       detached: true,
       stdio: ["ignore", logFd, logFd],
       env: { ...process.env, CABANE_COMPANION_DAEMON: "1" }
@@ -12273,7 +12614,7 @@ async function stop(deps = {}) {
   const readState = deps.readState ?? readLiveRuntimeState;
   const verify = deps.verify ?? ((s) => verifyRuntime(s));
   const kill = deps.kill ?? ((pid2, signal) => process.kill(pid2, signal));
-  const sleep4 = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const sleep5 = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
   const now = deps.now ?? (() => Date.now());
   const state = readState();
   if (!state) {
@@ -12301,7 +12642,7 @@ async function stop(deps = {}) {
       process.stdout.write("companion: stopped.\n");
       return;
     }
-    await sleep4(POLL_INTERVAL_MS2);
+    await sleep5(POLL_INTERVAL_MS2);
   }
   process.stdout.write(
     `companion: didn't exit within ${TERM_GRACE_MS / 1e3}s, sending SIGKILL.
@@ -12324,7 +12665,7 @@ function isAlive(kill, pid) {
 }
 
 // src/commands/transcript.ts
-import { existsSync as existsSync15, readFileSync as readFileSync10, readdirSync as readdirSync5 } from "fs";
+import { existsSync as existsSync15, readFileSync as readFileSync11, readdirSync as readdirSync5 } from "fs";
 import { isAbsolute, join as join18 } from "path";
 async function transcript(opts = {}) {
   const dir2 = transcriptsDir();
@@ -12425,7 +12766,7 @@ function isComplete(content) {
 async function followTranscripts(dir2) {
   const follower = new TranscriptFollower({
     listFiles: () => listFiles(dir2),
-    read: (f) => readFileSync10(join18(dir2, f), "utf8"),
+    read: (f) => readFileSync11(join18(dir2, f), "utf8"),
     write: (s) => process.stdout.write(s),
     // CSI: cursor up `n` lines, then erase from cursor to end of screen.
     clearLines: (n) => process.stdout.write(`\x1B[${n}A\x1B[0J`),
@@ -12486,7 +12827,7 @@ function peek(path) {
   let meta;
   let outcome;
   try {
-    for (const line of readFileSync10(path, "utf8").split("\n")) {
+    for (const line of readFileSync11(path, "utf8").split("\n")) {
       if (!line.trim()) continue;
       const o = safeParse(line);
       const t = str2(rec(o)?.type);
@@ -12519,7 +12860,7 @@ function resolveTarget(dir2, target) {
 function renderFile(path) {
   let content;
   try {
-    content = readFileSync10(path, "utf8");
+    content = readFileSync11(path, "utf8");
   } catch (err) {
     throw new CompanionError(
       `couldn't read ${path}: ${err instanceof Error ? err.message : String(err)}`
@@ -12679,7 +13020,7 @@ program.command("pair").description(
   });
 });
 program.command("write-paired-config", { hidden: true }).description("persist an already-completed device enrollment payload from stdin.").action(() => {
-  writeCompletedPairing(readFileSync11(0, "utf8"));
+  writeCompletedPairing(readFileSync12(0, "utf8"));
 });
 program.command("start").description(
   "pair this device if needed, connect a coding agent on it, and run in the background."

package/dist/runtime.js

@@ -4054,7 +4054,39 @@ function buildClaudeCodeOptions(req, augment) {
     ...cwd ? { cwd } : {},
     // Extra env (a companion prepare hook's tokens/ports; the in-app's debug flags)
     // merged OVER the inherited environment.
-    ...req.local.env ? { env: { ...process.env, ...req.local.env } } : {},
+    //
+    // CT1503: and the background-tasks kill switch LAST, so nothing in
+    // `process.env` or `req.local.env` can turn it back on. Claude Code converts
+    // a foreground command that hits its Bash ceiling (600 000 ms) into a
+    // background task instead of erroring; the agent then reads a phantom task
+    // id inside a live turn. A later turn that resumed such a session was then
+    // seen getting every tool call aborted with kind `background` — which the CLI
+    // renders as "The user doesn't want to take this action right now", a
+    // cancellation wearing a refusal's words. The automatic conversion is
+    // REPRODUCED and is what this flag fixes; that the stopped task is what
+    // poisoned the resumed session is an INFERENCE from one incident, consistent
+    // with the transcript but never reproduced, and this change does not rest on
+    // it. `Dl()` reads this variable on the Bash tool's own call
+    // path and sets `canAutoBackground: false` and `turnAbortBackgrounds: false`
+    // together, so a timed-out command comes back as a readable error instead.
+    //
+    // The cost is acknowledged and deliberate: it ALSO removes deliberate
+    // `run_in_background` (the parameter leaves the tool schema). That is the
+    // only switch this harness offers, and there is no operator opt-out here on
+    // purpose — an escape hatch would contradict the guarantee. It is a targeted
+    // mitigation for the automatic conversion, NOT a cleanup mechanism: step 0
+    // measured that this flag changes no process-survival outcome on any turn-end
+    // path. Cleanup is its own change.
+    //
+    // Note `env` REPLACES the subprocess environment rather than merging (the
+    // SDK's own doc on `Options.env`), which is why `process.env` is spread here
+    // and why this key is now always present — previously it appeared only when
+    // `req.local.env` was set, and an absent `env` inherits `process.env`.
+    env: {
+      ...process.env,
+      ...req.local.env,
+      CLAUDE_CODE_DISABLE_BACKGROUND_TASKS: "1"
+    },
     ...resume ? { resume } : {}
   };
   let options;
@@ -8153,6 +8185,261 @@ function pruneOld(dir2, retain) {
   }
 }
 
+// src/turn-containment.ts
+import { execFile, execFileSync, spawn as spawn4 } from "child_process";
+import { readFileSync as readFileSync8 } from "fs";
+import { promisify } from "util";
+var execFileAsync = promisify(execFile);
+var asContained = (child) => child;
+var CONTAINMENT_STOP_GRACE_SEC = 5;
+var FALLBACK_GRACE_MS = CONTAINMENT_STOP_GRACE_SEC * 1e3;
+var CAPABILITY_PROBE_TIMEOUT_MS = 4e3;
+function turnScopeUnit(turnId, attempt) {
+  const safe3 = turnId.replace(/[^A-Za-z0-9_.-]/g, "-");
+  return `cabane-turn-${safe3}-${attempt}`;
+}
+function scopeCapabilityUsable(env, timeoutMs = CAPABILITY_PROBE_TIMEOUT_MS) {
+  if (process.platform !== "linux") return false;
+  try {
+    execFileSync("systemd-run", ["--user", "--scope", "--quiet", "--collect", "--", "/bin/true"], {
+      env,
+      timeout: timeoutMs,
+      stdio: "ignore"
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function classifyStopError(message) {
+  if (/failed to connect to bus|failed to get d-?bus connection|connection refused|refusing to operate|spawn systemctl|systemctl.*ENOENT|ENOENT.*systemctl/i.test(
+    message
+  )) {
+    return "failure";
+  }
+  if (/not loaded|could not be found|no such unit|unit .* not found/i.test(message))
+    return "absent";
+  return "failure";
+}
+function currentSystemdUnit(cgroupText) {
+  for (const line of cgroupText.split("\n")) {
+    const path = line.trim().split(":").pop();
+    if (!path?.startsWith("/")) continue;
+    const leaf = path.split("/").filter(Boolean).pop();
+    if (leaf && (leaf.endsWith(".service") || leaf.endsWith(".scope"))) return leaf;
+  }
+  return null;
+}
+function readCurrentSystemdUnit() {
+  try {
+    return currentSystemdUnit(readFileSync8("/proc/self/cgroup", "utf8"));
+  } catch {
+    return null;
+  }
+}
+function processGroupMembers(pgid) {
+  try {
+    const out = execFileSync("ps", ["-eo", "pid=,pgid="], { timeout: 5e3 }).toString();
+    return {
+      ok: true,
+      members: out.split("\n").map((line) => /^\s*(\d+)\s+(\d+)\s*$/.exec(line)).filter((m) => m !== null).filter((m) => Number(m[2]) === pgid && Number(m[1]) !== process.pid).map((m) => Number(m[1]))
+    };
+  } catch (err) {
+    return { ok: false, error: (err instanceof Error ? err.message : String(err)).slice(0, 150) };
+  }
+}
+var sleep2 = (ms) => new Promise((resolve2) => setTimeout(resolve2, ms));
+var MANAGER_ENV_KEYS = ["DBUS_SESSION_BUS_ADDRESS", "XDG_RUNTIME_DIR", "PATH"];
+var managerEnvKey = (env) => MANAGER_ENV_KEYS.map((k) => `${k}=${env[k] ?? ""}`).join("\0");
+function createTurnContainment(turnId, deps = {}) {
+  const probe = deps.capabilityProbe ?? scopeCapabilityUsable;
+  const ownUnit = (deps.ownSystemdUnit ?? readCurrentSystemdUnit)();
+  const scopeUnits = [];
+  const groups = [];
+  let kind = null;
+  let probedEnvKey = null;
+  let attempt = 0;
+  function spawnInScope(options) {
+    const unit = turnScopeUnit(turnId, attempt++);
+    scopeUnits.push({ unit, env: options.env });
+    deps.log?.("containment: spawning the turn CLI into a systemd scope", {
+      unit,
+      partOf: ownUnit,
+      command: options.command
+    });
+    return asContained(
+      spawn4(
+        "systemd-run",
+        [
+          "--user",
+          "--scope",
+          "--quiet",
+          "--collect",
+          `--unit=${unit}`,
+          `--property=TimeoutStopSec=${CONTAINMENT_STOP_GRACE_SEC}s`,
+          // Bind the scope's life to the companion's own unit, so stopping or
+          // restarting the companion still takes its in-flight turns with it —
+          // which is what happens today, and what the scope would otherwise undo.
+          // Omitted outside a unit, where there is nothing to bind to.
+          ...ownUnit ? [`--property=PartOf=${ownUnit}`] : [],
+          "--",
+          options.command,
+          ...options.args
+        ],
+        {
+          ...options.cwd ? { cwd: options.cwd } : {},
+          env: options.env,
+          stdio: ["pipe", "pipe", "pipe"]
+        }
+      )
+    );
+  }
+  function spawnInGroup(options) {
+    const child = spawn4(options.command, options.args, {
+      ...options.cwd ? { cwd: options.cwd } : {},
+      env: options.env,
+      stdio: ["pipe", "pipe", "pipe"],
+      detached: process.platform !== "win32"
+    });
+    if (child.pid !== void 0) groups.push({ pgid: child.pid, child });
+    deps.log?.("containment: no host-owned containment here \u2014 best effort only", {
+      platform: process.platform,
+      pid: child.pid
+    });
+    return asContained(child);
+  }
+  async function reapScopes(result) {
+    for (const { unit, env } of scopeUnits) {
+      try {
+        await execFileAsync("systemctl", ["--user", "stop", `${unit}.scope`], {
+          env,
+          timeout: (CONTAINMENT_STOP_GRACE_SEC + 10) * 1e3
+        });
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (classifyStopError(message) === "failure") {
+          result.failures.push({ target: unit, error: message.slice(0, 200) });
+          continue;
+        }
+        result.reaped.push(unit);
+        continue;
+      }
+      try {
+        const { stdout } = await execFileAsync(
+          "systemctl",
+          ["--user", "show", `${unit}.scope`, "--property=ActiveState", "--value"],
+          { env, timeout: 1e4 }
+        );
+        const state = stdout.trim();
+        if (state === "" || state === "inactive" || state === "failed") result.reaped.push(unit);
+        else result.failures.push({ target: unit, error: `scope still ${state} after stop` });
+      } catch (err) {
+        result.failures.push({
+          target: unit,
+          error: `could not confirm the scope stopped: ${(err instanceof Error ? err.message : String(err)).slice(0, 150)}`
+        });
+      }
+    }
+  }
+  async function reapGroups(result) {
+    for (const { pgid, child } of groups) {
+      const target = String(pgid);
+      if (process.platform === "win32") {
+        try {
+          if (child.exitCode === null) child.kill();
+          result.unverified.push(target);
+        } catch (err) {
+          result.failures.push({
+            target,
+            error: (err instanceof Error ? err.message : String(err)).slice(0, 200)
+          });
+        }
+        continue;
+      }
+      const first = processGroupMembers(pgid);
+      if (!first.ok) {
+        result.failures.push({
+          target,
+          error: `could not enumerate the process group: ${first.error}`
+        });
+        continue;
+      }
+      if (first.members.length === 0) {
+        result.reaped.push(target);
+        continue;
+      }
+      for (const pid of first.members) {
+        try {
+          process.kill(pid, "SIGTERM");
+        } catch {
+        }
+      }
+      await sleep2(FALLBACK_GRACE_MS);
+      const afterTerm = processGroupMembers(pgid);
+      if (!afterTerm.ok) {
+        result.failures.push({
+          target,
+          error: `could not re-enumerate the process group after SIGTERM: ${afterTerm.error}`
+        });
+        continue;
+      }
+      for (const pid of afterTerm.members) {
+        try {
+          process.kill(pid, "SIGKILL");
+        } catch {
+        }
+      }
+      const afterKill = processGroupMembers(pgid);
+      if (!afterKill.ok) {
+        result.failures.push({
+          target,
+          error: `could not confirm the process group is empty after SIGKILL: ${afterKill.error}`
+        });
+        continue;
+      }
+      if (afterKill.members.length)
+        result.failures.push({
+          target,
+          error: `${afterKill.members.length} process(es) still in the group after SIGKILL`
+        });
+      else result.reaped.push(target);
+    }
+  }
+  return {
+    get kind() {
+      return kind;
+    },
+    spawn(options) {
+      const envKey = managerEnvKey(options.env);
+      if (kind === null || envKey !== probedEnvKey) {
+        kind = probe(options.env) ? "systemd-scope" : "process-group";
+        probedEnvKey = envKey;
+        deps.log?.("containment: resolved strategy for this turn", {
+          kind,
+          platform: process.platform
+        });
+      }
+      return kind === "systemd-scope" ? spawnInScope(options) : spawnInGroup(options);
+    },
+    async reap() {
+      const result = {
+        kind: kind ?? "unused",
+        reaped: [],
+        failures: [],
+        unverified: []
+      };
+      await reapScopes(result);
+      await reapGroups(result);
+      deps.log?.("containment: reap complete", {
+        kind: result.kind,
+        reaped: result.reaped,
+        failures: result.failures
+      });
+      return result;
+    }
+  };
+}
+
 // src/turn-committer.ts
 var TurnCommitter = class {
   constructor(deps) {
@@ -8372,7 +8659,10 @@ function missingSecretReason(missing) {
 var RUNTIME_UNAVAILABLE_PREFIX = "**This agent's runtime isn't available on this companion.** The model this agent uses needs a runtime this device isn't running, so I can't run this turn here. Details:";
 var UNEXPECTED_ROLE_REASON = `refused the wake trigger (role "system" isn't dispatchable on this companion) \u2014 the companion is likely running outdated code; refresh it, then re-address the agent`;
 var DEFAULT_PREPARING_ROW_DELAY_MS = 1500;
-var DEFAULT_AGENT_IDLE_TIMEOUT_MS = 10 * 6e4;
+var DEFAULT_AGENT_IDLE_TIMEOUT_MS = 15 * 6e4;
+function resolveIdleTimeoutMs(override) {
+  return override ?? DEFAULT_AGENT_IDLE_TIMEOUT_MS;
+}
 var DEFAULT_AGENT_TOTAL_TIMEOUT_MS = 6 * 60 * 6e4;
 var DEFAULT_LEASE_RENEWAL_MS = 3e4;
 function initialOutcome() {
@@ -8430,6 +8720,11 @@ var TurnExecution = class {
   turnLog;
   abortController = new AbortController();
   outcome = initialOutcome();
+  // CT1503: this turn's shell containment, once the claude-code adapter is built.
+  // Null before that and on a turn that never reached adapter construction — a
+  // startup failure has nothing to reap, and reaping is a no-op rather than a
+  // special case.
+  containment = null;
   seqCounter = 0;
   // CT11: per-turn monotonic counter mirroring the in-process dispatcher's.
   //
@@ -8464,6 +8759,36 @@ var TurnExecution = class {
   };
   disarmWatchdogs = () => {
   };
+  // CT1503: reap this turn's shell containment. Idempotent (the containment drops
+  // what it has already stopped) and total — a reap that fails is reported and
+  // swallowed, because a turn that produced a good answer must not be recorded as
+  // failed on account of a leftover process, and the failure is visible in the log
+  // either way.
+  async reapContainment() {
+    const containment = this.containment;
+    if (!containment) return;
+    this.containment = null;
+    try {
+      const result = await containment.reap();
+      if (result.failures.length) {
+        this.turnLog.warn(
+          { kind: result.kind, failures: result.failures },
+          "turn containment: some of this turn\u2019s shell work could not be reaped"
+        );
+      }
+      if (result.unverified.length) {
+        this.turnLog.debug(
+          { kind: result.kind, unverified: result.unverified },
+          "turn containment: cleanup requested but not confirmable on this platform"
+        );
+      }
+    } catch (err) {
+      this.turnLog.warn(
+        { err: err instanceof Error ? err.message : String(err) },
+        "turn containment: reap threw"
+      );
+    }
+  }
   // Codo's stack review, blocking finding #2: set the moment `acquireLease`'s
   // PATCH returns — the lease is granted and this is the pair's running span,
   // so every exit after this point must settle THE SPAN, not just clear the
@@ -8854,7 +9179,20 @@ var TurnExecution = class {
     const onWarn = (msg, meta) => turnLog.debug(meta ?? {}, msg);
     const adapters = [];
     if (this.opts.claudeCodeAvailable?.() ?? true) {
-      adapters.push(createClaudeCodeAdapter({ queryFn: this.opts.queryFn, onWarn }));
+      this.containment = createTurnContainment(this.turnId, {
+        log: (msg, meta) => turnLog.debug(meta ?? {}, msg)
+      });
+      const containment = this.containment;
+      adapters.push(
+        createClaudeCodeAdapter({
+          queryFn: this.opts.queryFn,
+          onWarn,
+          augmentOptions: (options) => ({
+            ...options,
+            spawnClaudeCodeProcess: (spawnOptions) => containment.spawn(spawnOptions)
+          })
+        })
+      );
     }
     if (this.opts.opencodeServerUrl) {
       adapters.push(createOpencodeAdapter({ serverUrl: this.opts.opencodeServerUrl, onWarn }));
@@ -8996,7 +9334,7 @@ var TurnExecution = class {
         );
       }
     };
-    const idleTimeoutMs = this.opts.idleTimeoutMs ?? DEFAULT_AGENT_IDLE_TIMEOUT_MS;
+    const idleTimeoutMs = resolveIdleTimeoutMs(this.opts.idleTimeoutMs);
     const fireTimeout = (reason) => {
       if (abortController.signal.aborted) return;
       o.timeoutReason = reason;
@@ -9149,6 +9487,7 @@ var TurnExecution = class {
       );
     } finally {
       this.disarmWatchdogs();
+      await this.reapContainment();
       if (o.leaseLost) {
         o.resultReason = "lease_lost";
         o.okResult = false;
@@ -9454,7 +9793,7 @@ import {
   existsSync as existsSync12,
   mkdirSync as mkdirSync10,
   readdirSync as readdirSync3,
-  readFileSync as readFileSync8,
+  readFileSync as readFileSync9,
   renameSync as renameSync4,
   rmSync as rmSync7,
   writeFileSync as writeFileSync7
@@ -9519,7 +9858,7 @@ var Outbox = class {
       if (!name.endsWith(".json")) continue;
       const full = join16(dir2, name);
       try {
-        const parsed = JSON.parse(readFileSync8(full, "utf8"));
+        const parsed = JSON.parse(readFileSync9(full, "utf8"));
         if (parsed && typeof parsed.turnId === "string" && typeof parsed.seq === "number" && typeof parsed.path === "string") {
           entries.push(parsed);
         } else {
@@ -9700,7 +10039,7 @@ var SseSubscriber = class {
         backoff = 500;
         if (!this.aborted) {
           this.opts.log.warn("Lost the connection to Cabane; reconnecting");
-          await sleep2(backoff);
+          await sleep3(backoff);
         }
       } catch (err) {
         if (this.aborted) return;
@@ -9720,7 +10059,7 @@ var SseSubscriber = class {
           },
           "Lost the connection to Cabane; reconnecting"
         );
-        await sleep2(backoff);
+        await sleep3(backoff);
         backoff = Math.min(backoff * 2, MAX_BACKOFF_MS);
       }
     }
@@ -9772,7 +10111,7 @@ var SseSubscriber = class {
     }
   }
 };
-function sleep2(ms) {
+function sleep3(ms) {
   return new Promise((resolve2) => setTimeout(resolve2, ms));
 }
 
@@ -10340,7 +10679,9 @@ var CompanionSupervisor = class {
       codexAvailable: () => this.codexOffered(),
       // CT556: per-turn timeout watchdog windows, from the companion's own env
       // (`AGENT_IDLE_TIMEOUT_MS` / `AGENT_TOTAL_TIMEOUT_MS`). Unset → the
-      // dispatcher's baked-in defaults (10 min idle / 6h total).
+      // dispatcher's baked-in defaults (CT1503: 15 min idle / 6h total). An
+      // override set here still wins, and is deliberately not validated against
+      // the tool ceilings it may reorder — see DEFAULT_AGENT_IDLE_TIMEOUT_MS.
       ...positiveIntEnv("AGENT_IDLE_TIMEOUT_MS") !== void 0 ? { idleTimeoutMs: positiveIntEnv("AGENT_IDLE_TIMEOUT_MS") } : {},
       ...positiveIntEnv("AGENT_TOTAL_TIMEOUT_MS") !== void 0 ? { totalTimeoutMs: positiveIntEnv("AGENT_TOTAL_TIMEOUT_MS") } : {},
       observer: this.hub.observerFor(ctx.workspaceId, ctx.agentId, ctx.workspaceSlug),
@@ -10952,9 +11293,9 @@ async function waitForBoundedHeartbeat(heartbeat) {
 }
 function defaultReexec() {
   clearRuntimeState();
-  void import("child_process").then(({ spawn: spawn4 }) => {
+  void import("child_process").then(({ spawn: spawn5 }) => {
     try {
-      const child = spawn4(process.execPath, process.argv.slice(1), {
+      const child = spawn5(process.execPath, process.argv.slice(1), {
         stdio: "inherit",
         detached: false
       });
@@ -11024,7 +11365,7 @@ function handleUncaught(log, err, origin) {
 }
 
 // src/crash-marker.ts
-import { existsSync as existsSync13, mkdirSync as mkdirSync11, readFileSync as readFileSync9, rmSync as rmSync8, writeFileSync as writeFileSync8 } from "fs";
+import { existsSync as existsSync13, mkdirSync as mkdirSync11, readFileSync as readFileSync10, rmSync as rmSync8, writeFileSync as writeFileSync8 } from "fs";
 import { join as join17 } from "path";
 function crashMarkerPath() {
   return join17(cabaneDir(), "last-error.json");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cabane/companion",
-  "version": "0.6.103",
+  "version": "0.6.104",
   "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",