@cabane/companion 0.6.156 → 0.6.157

package/dist/runtime.js

@@ -616,6 +616,15 @@ var companionConfigSchema = z2.object({
   // absent `claudeCode` block means "never offered"; without it, the block's
   // absence marks a config from before connectors were chosen.
   harnessesChosen: z2.boolean().optional(),
+  // Whether this companion keeps itself current: installs the version Cabane names, between
+  // turns, and rolls back one that doesn't come up (`updater.ts`). Absent means never asked,
+  // which `start` offers; off either way until someone says yes.
+  update: z2.object({
+    auto: z2.boolean()
+  }).strict().optional(),
+  // The answer to `start`'s "start at boot?" when it was no, so it isn't asked again.
+  // `cabane service install` still installs it.
+  serviceDeclined: z2.boolean().optional(),
   // OpenCode's decline. Its block is an address, so a decline can't live there
   // the way `claudeCode`/`codex` `enabled: false` does; without it a declined
   // serve would be offered again on every `start`.
@@ -792,7 +801,7 @@ import { serve } from "@hono/node-server";
 import { Hono } from "hono";
 
 // src/dashboard/routes.ts
-import { openSync, readSync, closeSync, fstatSync, existsSync as existsSync3 } from "fs";
+import { openSync as openSync2, readSync, closeSync, fstatSync, existsSync as existsSync3 } from "fs";
 import { readFile } from "fs/promises";
 import { extname, join as join6, normalize } from "path";
 import { streamSSE } from "hono/streaming";
@@ -1264,7 +1273,13 @@ function connectLines(outcome, opts = {}) {
 }
 
 // src/logger.ts
-import { createWriteStream, mkdirSync as mkdirSync2 } from "fs";
+import {
+  createWriteStream,
+  mkdirSync as mkdirSync2,
+  openSync,
+  renameSync as renameSync2,
+  statSync as statSync2
+} from "fs";
 import { dirname as dirname3, join as join5 } from "path";
 import { stripVTControlCharacters } from "util";
 import pino from "pino";
@@ -1319,6 +1334,53 @@ function formatHumanLine(record) {
   }
   return line + "\n";
 }
+var LOG_ROTATE_BYTES = 50 * 1024 * 1024;
+var LOG_ROTATIONS_KEPT = 3;
+var RotatingLog = class {
+  constructor(path, maxBytes = LOG_ROTATE_BYTES, keep = LOG_ROTATIONS_KEPT) {
+    this.path = path;
+    this.maxBytes = maxBytes;
+    this.keep = keep;
+    this.size = sizeOf(path);
+    this.stream = openAppend(path);
+  }
+  path;
+  maxBytes;
+  keep;
+  stream;
+  size;
+  write(chunk) {
+    const ok = this.stream.write(chunk);
+    this.size += Buffer.byteLength(chunk);
+    if (this.size >= this.maxBytes) this.rotate();
+    return ok;
+  }
+  rotate() {
+    this.stream.end();
+    try {
+      for (let i = this.keep - 1; i >= 1; i--) {
+        try {
+          renameSync2(`${this.path}.${i}`, `${this.path}.${i + 1}`);
+        } catch {
+        }
+      }
+      renameSync2(this.path, `${this.path}.1`);
+    } catch {
+    }
+    this.stream = openAppend(this.path);
+    this.size = sizeOf(this.path);
+  }
+};
+function openAppend(path) {
+  return createWriteStream("", { fd: openSync(path, "a") });
+}
+function sizeOf(path) {
+  try {
+    return statSync2(path).size;
+  } catch {
+    return 0;
+  }
+}
 var cached = null;
 var consoleLogging = true;
 var overrides = {};
@@ -1331,7 +1393,7 @@ function configureLogger(log, config) {
 function createLogger(destinations = {}, options = {}) {
   const path = companionLogPath();
   if (!destinations.file) mkdirSync2(dirname3(path), { recursive: true });
-  const file = destinations.file ?? createWriteStream(path, { flags: "a" });
+  const file = destinations.file ?? new RotatingLog(path);
   const state = { format: options.logFormat ?? "human" };
   const streams = [];
   const human = (chunk) => {
@@ -1755,7 +1817,7 @@ function tailFile(path, lines2) {
   const MAX_BYTES = 256 * 1024;
   let fd;
   try {
-    fd = openSync(path, "r");
+    fd = openSync2(path, "r");
     const size = fstatSync(fd).size;
     const start = Math.max(0, size - MAX_BYTES);
     const len = size - start;
@@ -1931,6 +1993,10 @@ async function serveConnection(socket, handlers) {
       reply(socket, result);
       return;
     }
+    if (req.cmd === "update") {
+      reply(socket, await handlers.update(req.auto));
+      return;
+    }
     if (req.cmd === "stop") {
       reply(socket, { ok: true });
       setTimeout(() => handlers.stop(), 50).unref?.();
@@ -2053,7 +2119,7 @@ import {
   rmSync as rmSync3,
   writeFileSync as writeFileSync2,
   mkdirSync as mkdirSync4,
-  openSync as openSync2,
+  openSync as openSync3,
   closeSync as closeSync2
 } from "fs";
 import { join as join9 } from "path";
@@ -2075,7 +2141,7 @@ function acquireRuntimeState(state) {
   mkdirSync4(cabaneDir(), { recursive: true });
   let fd;
   try {
-    fd = openSync2(runtimePath(), "wx");
+    fd = openSync3(runtimePath(), "wx");
   } catch {
     return { acquired: false, existing: readLiveRuntimeState() };
   }
@@ -2961,7 +3027,7 @@ import {
   existsSync as existsSync6,
   mkdirSync as mkdirSync5,
   readFileSync as readFileSync3,
-  renameSync as renameSync2,
+  renameSync as renameSync3,
   rmSync as rmSync4,
   writeFileSync as writeFileSync3
 } from "fs";
@@ -3002,7 +3068,7 @@ function save(map) {
       chmodSync3(tmp, 384);
     } catch {
     }
-    renameSync2(tmp, path);
+    renameSync3(tmp, path);
   } catch (err) {
     try {
       rmSync4(tmp, { force: true });
@@ -3035,7 +3101,7 @@ function pruneCredentials(keepAgentIds) {
 }
 
 // src/dispatch-dedupe.ts
-import { mkdirSync as mkdirSync6, readFileSync as readFileSync4, writeFileSync as writeFileSync4, renameSync as renameSync3, existsSync as existsSync7 } from "fs";
+import { mkdirSync as mkdirSync6, readFileSync as readFileSync4, writeFileSync as writeFileSync4, renameSync as renameSync4, existsSync as existsSync7 } from "fs";
 import { join as join11 } from "path";
 var MAX_IDS = 256;
 function dir(log) {
@@ -3153,7 +3219,7 @@ function writeTurnIds(workspaceId, turns) {
   const path = turnPathFor(workspaceId);
   const tmp = `${path}.${process.pid}.tmp`;
   writeFileSync4(tmp, entries.map(([id, t]) => `${id}	${t}`).join("\n") + "\n", "utf8");
-  renameSync3(tmp, path);
+  renameSync4(tmp, path);
   return entries.length;
 }
 function rememberTurnId(workspaceId, eventId, turnId) {
@@ -8078,7 +8144,7 @@ var ConnectorHealthStore = class {
 
 // src/dispatcher.ts
 import { randomUUID as randomUUID4 } from "crypto";
-import { existsSync as existsSync11, readdirSync as readdirSync2, statSync as statSync2 } from "fs";
+import { existsSync as existsSync11, readdirSync as readdirSync2, statSync as statSync3 } from "fs";
 import { join as join17 } from "path";
 
 // src/runner/launch.ts
@@ -11199,7 +11265,7 @@ function checkoutState(cwd) {
   if (!existsSync11(gitPath)) return { ok: true, reason: "usable" };
   let stat;
   try {
-    stat = statSync2(gitPath);
+    stat = statSync3(gitPath);
   } catch (error) {
     return { ok: false, reason: `${gitPath} is unreadable (${error.message})` };
   }
@@ -11416,9 +11482,9 @@ import {
   mkdirSync as mkdirSync10,
   readdirSync as readdirSync4,
   readFileSync as readFileSync9,
-  renameSync as renameSync5,
+  renameSync as renameSync6,
   rmSync as rmSync9,
-  statSync as statSync3,
+  statSync as statSync4,
   writeFileSync as writeFileSync6
 } from "fs";
 import { join as join20 } from "path";
@@ -11612,7 +11678,7 @@ import {
   mkdirSync as mkdirSync9,
   readdirSync as readdirSync3,
   readFileSync as readFileSync8,
-  renameSync as renameSync4,
+  renameSync as renameSync5,
   rmSync as rmSync8
 } from "fs";
 import { join as join18 } from "path";
@@ -11648,11 +11714,11 @@ function admitCollectedEntry(raw, turn) {
 }
 var atomicMove = (from, to) => {
   try {
-    renameSync4(from, to);
+    renameSync5(from, to);
   } catch {
     const partial = `${to}.partial`;
     copyFileSync2(from, partial);
-    renameSync4(partial, to);
+    renameSync5(partial, to);
     rmSync8(from, { force: true });
   }
 };
@@ -11896,6 +11962,25 @@ function pruneOtherAttempts(deviceDir, pair, keep) {
     }
   }
 }
+var IDLE_SESSION_ARCHIVE_MS = 30 * 24 * 60 * 6e4;
+function pruneIdleSessionArchives(deviceDir, now = Date.now(), maxAgeMs = IDLE_SESSION_ARCHIVE_MS) {
+  const root = join20(deviceDir, "attempts");
+  if (!existsSync14(root)) return [];
+  const removed = [];
+  for (const id of readdirSync4(root)) {
+    if (!UUID_RE.test(id)) continue;
+    let kept;
+    try {
+      kept = statSync4(join20(root, id)).mtimeMs;
+    } catch {
+      continue;
+    }
+    if (now - kept < maxAgeMs) continue;
+    rmSync9(join20(root, id), { recursive: true, force: true });
+    removed.push(id);
+  }
+  return removed;
+}
 var CappedFile = class extends Writable {
   constructor(path, cap) {
     super();
@@ -12273,7 +12358,7 @@ function createDockerProvider(opts) {
       (resolve2) => file.writableFinished ? resolve2() : file.once("finish", resolve2)
     );
     if (r.code === 0 && !file.over) {
-      renameSync5(partial, archive);
+      renameSync6(partial, archive);
       writeFileSync6(join20(archive, "..", "pair"), `${attempt.conversationId}/${attempt.agentId}`);
       pruneOtherAttempts(opts.deviceDir, attempt, attemptId);
       await writeMarker(name, attemptId);
@@ -12410,7 +12495,7 @@ function createDockerProvider(opts) {
             );
           } else {
             log.info(
-              { container: name, attemptId, bytes: statSync3(archive).size },
+              { container: name, attemptId, bytes: statSync4(archive).size },
               "runners: session files restored"
             );
           }
@@ -12983,7 +13068,7 @@ import {
   mkdirSync as mkdirSync12,
   readdirSync as readdirSync5,
   readFileSync as readFileSync11,
-  renameSync as renameSync6,
+  renameSync as renameSync7,
   rmSync as rmSync11,
   writeFileSync as writeFileSync8
 } from "fs";
@@ -13015,7 +13100,7 @@ var Outbox = class {
     const tmp = `${target}.${process.pid}.tmp`;
     try {
       writeFileSync8(tmp, JSON.stringify(entry) + "\n", "utf8");
-      renameSync6(tmp, target);
+      renameSync7(tmp, target);
     } catch (err) {
       try {
         rmSync11(tmp, { force: true });
@@ -13170,6 +13255,12 @@ var SseSubscriber = class {
     this.aborted = true;
     this.controller?.abort();
   }
+  // Connect again after a `stop()`, once its loop has exited.
+  async resume() {
+    await this.finished;
+    this.aborted = false;
+    this.start();
+  }
   setCursor(eventId) {
     this.lastEventId = eventId;
   }
@@ -13256,6 +13347,550 @@ function sleep3(ms) {
   return new Promise((resolve2) => setTimeout(resolve2, ms));
 }
 
+// src/updater.ts
+import { spawn as spawn8 } from "child_process";
+import { copyFileSync as copyFileSync3, existsSync as existsSync17, mkdirSync as mkdirSync16, renameSync as renameSync11, rmSync as rmSync14 } from "fs";
+import { dirname as dirname12, join as join26 } from "path";
+
+// src/boot-rule.ts
+import {
+  mkdirSync as mkdirSync13,
+  readFileSync as readFileSync12,
+  realpathSync as realpathSync5,
+  renameSync as renameSync8,
+  rmSync as rmSync12,
+  symlinkSync,
+  writeFileSync as writeFileSync9
+} from "fs";
+import { dirname as dirname9, join as join23 } from "path";
+var UNCONFIRMED_WINDOW_MS = 10 * 6e4;
+var MAX_STAGE_ATTEMPTS = 3;
+function superseded(pending, ...running) {
+  return !!pending && !running.includes(pending.to);
+}
+function rolledBackState(state, pending, reason, now) {
+  const { pending: _done, ...rest } = state;
+  return {
+    ...rest,
+    lastResult: {
+      kind: "rolled_back",
+      from: pending.from,
+      to: pending.to,
+      at: now.toISOString(),
+      reason: reason.replace(/\s+/g, " ").trim().slice(0, 400)
+    },
+    failed: { version: pending.to, attempts: MAX_STAGE_ATTEMPTS, at: now.toISOString() }
+  };
+}
+
+// src/install-layout.ts
+import {
+  existsSync as existsSync16,
+  lstatSync,
+  mkdirSync as mkdirSync14,
+  readFileSync as readFileSync13,
+  readdirSync as readdirSync6,
+  realpathSync as realpathSync6,
+  renameSync as renameSync9,
+  rmSync as rmSync13,
+  symlinkSync as symlinkSync2
+} from "fs";
+import { dirname as dirname10, join as join24 } from "path";
+import { fileURLToPath as fileURLToPath6 } from "url";
+function versionsDir() {
+  return join24(cabaneDir(), "versions");
+}
+function currentLink() {
+  return join24(cabaneDir(), "current");
+}
+function bootGuardPath() {
+  return join24(cabaneDir(), "boot-guard.mjs");
+}
+function versionPackageRoot(version) {
+  return join24(versionsDir(), version, "node_modules", "@cabane", "companion");
+}
+function ownPackageRoot(moduleUrl = import.meta.url) {
+  return dirname10(dirname10(fileURLToPath6(moduleUrl)));
+}
+function packageVersion(root) {
+  try {
+    const pkg2 = JSON.parse(readFileSync13(join24(root, "package.json"), "utf8"));
+    return typeof pkg2.version === "string" ? pkg2.version : null;
+  } catch {
+    return null;
+  }
+}
+function currentRoot() {
+  try {
+    const root = realpathSync6(currentLink());
+    return existsSync16(join24(root, "dist", "cli.js")) ? root : null;
+  } catch {
+    return null;
+  }
+}
+function pointCurrentAt(root) {
+  const link = currentLink();
+  mkdirSync14(dirname10(link), { recursive: true });
+  const fresh = `${link}.${process.pid}.${Date.now()}`;
+  symlinkSync2(root, fresh);
+  try {
+    renameSync9(fresh, link);
+  } catch (err) {
+    rmSync13(fresh, { force: true });
+    throw err;
+  }
+}
+function pruneVersions(keep) {
+  const dir2 = versionsDir();
+  if (!existsSync16(dir2)) return [];
+  const removed = [];
+  for (const name of readdirSync6(dir2)) {
+    if (keep.includes(name)) continue;
+    rmSync13(join24(dir2, name), { recursive: true, force: true });
+    removed.push(name);
+  }
+  return removed;
+}
+function compareVersions(a, b) {
+  const parts = (v) => /^\d+(\.\d+)*$/.test(v) ? v.split(".").map(Number) : null;
+  const pa = parts(a);
+  const pb = parts(b);
+  if (!pa || !pb) return pa ? 1 : pb ? -1 : 0;
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (d !== 0) return d;
+  }
+  return 0;
+}
+
+// src/update-state.ts
+import { mkdirSync as mkdirSync15, readFileSync as readFileSync14, renameSync as renameSync10, writeFileSync as writeFileSync10 } from "fs";
+import { dirname as dirname11, join as join25 } from "path";
+import { z as z18 } from "zod";
+var resultSchema = z18.object({
+  kind: z18.enum(["updated", "rolled_back", "failed"]),
+  from: z18.string(),
+  to: z18.string(),
+  at: z18.string(),
+  reason: z18.string().optional()
+});
+var pendingSchema = z18.object({
+  from: z18.string(),
+  // The package root `current` pointed at before the swap, so a rollback can point it back.
+  fromRoot: z18.string(),
+  to: z18.string(),
+  at: z18.string(),
+  boots: z18.number().int().nonnegative()
+});
+var stateSchema = z18.object({
+  server: z18.object({ latest: z18.string(), minimum: z18.string(), at: z18.string() }).optional(),
+  pending: pendingSchema.optional(),
+  lastResult: resultSchema.optional(),
+  failed: z18.object({ version: z18.string(), attempts: z18.number().int(), at: z18.string() }).optional()
+});
+function updateStatePath(dir2 = cabaneDir()) {
+  return join25(dir2, "update.json");
+}
+function readUpdateState(path = updateStatePath()) {
+  try {
+    const parsed = stateSchema.safeParse(JSON.parse(readFileSync14(path, "utf8")));
+    return parsed.success ? parsed.data : {};
+  } catch {
+    return {};
+  }
+}
+function writeUpdateState(state, path = updateStatePath()) {
+  mkdirSync15(dirname11(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync10(tmp, `${JSON.stringify(state, null, 2)}
+`, { mode: 384 });
+  renameSync10(tmp, path);
+}
+function updateUpdateState(change, path = updateStatePath()) {
+  const next = change(readUpdateState(path));
+  writeUpdateState(next, path);
+  return next;
+}
+
+// src/updater.ts
+function updateMode(env = process.env) {
+  return env.CABANE_COMPANION_SUPERVISED === "1" ? "supervised" : "attached";
+}
+var STAGE_RETRY_MS = 60 * 6e4;
+var SWAP_DRAIN_MS = 1e4;
+var SOURCE_BUILD_VERSION = "0.0.0";
+function versionToStage(input) {
+  const { own, state, now, force } = input;
+  if (!input.auto && !force) return null;
+  if (own === SOURCE_BUILD_VERSION) return null;
+  const latest = state.server?.latest;
+  if (!latest || compareVersions(latest, own) <= 0) return null;
+  if (state.pending) return null;
+  const failed = state.failed;
+  if (!force && failed?.version === latest) {
+    if (failed.attempts >= MAX_STAGE_ATTEMPTS) return null;
+    if (now - Date.parse(failed.at) < STAGE_RETRY_MS) return null;
+  }
+  return latest;
+}
+function rollBack(pending, reason, now = /* @__PURE__ */ new Date()) {
+  if (existsSync17(pending.fromRoot)) pointCurrentAt(pending.fromRoot);
+  return updateUpdateState((state) => rolledBackState(state, pending, reason, now));
+}
+function writeBootGuard(root = ownPackageRoot()) {
+  const built = join26(root, "dist", "boot-guard.js");
+  if (!existsSync17(built)) return false;
+  const target = bootGuardPath();
+  mkdirSync16(dirname12(target), { recursive: true });
+  const tmp = `${target}.${process.pid}.tmp`;
+  copyFileSync3(built, tmp);
+  renameSync11(tmp, target);
+  return true;
+}
+function oneLine(text) {
+  return text.replace(/\s+/g, " ").trim().slice(0, 400);
+}
+var runProcess = (command, args, opts = {}) => new Promise((resolve2) => {
+  let stdout = "";
+  let stderr = "";
+  let child;
+  try {
+    child = spawn8(command, [...args], {
+      stdio: ["ignore", "pipe", "pipe"],
+      env: opts.env ?? process.env
+    });
+  } catch (err) {
+    resolve2({ code: null, stdout, stderr: err instanceof Error ? err.message : String(err) });
+    return;
+  }
+  const timer = opts.timeoutMs ? setTimeout(() => child.kill("SIGKILL"), opts.timeoutMs) : null;
+  child.stdout.on("data", (d) => stdout += d.toString());
+  child.stderr.on("data", (d) => stderr += d.toString());
+  child.on("error", (err) => {
+    if (timer) clearTimeout(timer);
+    resolve2({ code: null, stdout, stderr: stderr || err.message });
+  });
+  child.on("close", (code) => {
+    if (timer) clearTimeout(timer);
+    resolve2({ code, stdout, stderr });
+  });
+});
+async function stageVersion(version, harnesses, deps = {}) {
+  const run = deps.run ?? runProcess;
+  const node = deps.execPath ?? process.execPath;
+  const target = join26(versionsDir(), version);
+  const placed = versionPackageRoot(version);
+  if (existsSync17(placed)) {
+    if (!await verifyInstall(placed, version, harnesses, { run, execPath: node }))
+      return { ok: true, root: placed };
+  }
+  const npm = join26(dirname12(node), "npm");
+  if (!existsSync17(npm))
+    return { ok: false, reason: `there is no npm beside Node at ${dirname12(node)}` };
+  mkdirSync16(versionsDir(), { recursive: true });
+  const staging = join26(versionsDir(), `.${version}.staging-${process.pid}`);
+  rmSync14(staging, { recursive: true, force: true });
+  const installed = await run(
+    npm,
+    [
+      "install",
+      "--prefix",
+      staging,
+      "--include=optional",
+      "--no-audit",
+      "--no-fund",
+      "--no-save",
+      "--loglevel=error",
+      `@cabane/companion@${version}`
+    ],
+    {
+      // npm's install scripts run on this Node, not whichever `node` is first on PATH.
+      env: { ...process.env, PATH: `${dirname12(node)}:${process.env.PATH ?? ""}` },
+      timeoutMs: 15 * 6e4
+    }
+  );
+  if (installed.code !== 0) {
+    rmSync14(staging, { recursive: true, force: true });
+    if (/\bE404\b|\bETARGET\b|No matching version found|is not in this registry/i.test(
+      installed.stderr
+    ))
+      return { ok: false, reason: `version ${version} isn't published yet`, unpublished: true };
+    return { ok: false, reason: `npm couldn't install it: ${lastLine(installed.stderr)}` };
+  }
+  const root = join26(staging, "node_modules", "@cabane", "companion");
+  const verdict = await verifyInstall(root, version, harnesses, { run, execPath: node });
+  if (verdict) {
+    rmSync14(staging, { recursive: true, force: true });
+    return { ok: false, reason: verdict };
+  }
+  rmSync14(target, { recursive: true, force: true });
+  renameSync11(staging, target);
+  return { ok: true, root: versionPackageRoot(version) };
+}
+async function verifyInstall(root, version, harnesses, deps) {
+  if (packageVersion(root) !== version) return `the installed package isn't version ${version}`;
+  const answered = await deps.run(deps.execPath, [join26(root, "dist", "bin.js"), "--version"], {
+    timeoutMs: 6e4,
+    env: { ...process.env, CABANE_LAUNCH_SELF: "1" }
+  });
+  if (answered.code !== 0 || answered.stdout.trim() !== version) {
+    return `it doesn't start: ${lastLine(answered.stderr) || "no version printed"}`;
+  }
+  if (harnesses.length === 0) return null;
+  const probed = await deps.run(deps.execPath, [join26(root, "dist", "postinstall.js"), "--json"], {
+    timeoutMs: 6e4
+  });
+  let resolutions = {};
+  try {
+    resolutions = JSON.parse(probed.stdout);
+  } catch {
+    return "it couldn't say which bundled agents it has";
+  }
+  const missing = harnesses.filter((h) => resolutions[h]?.status !== "present");
+  if (missing.length > 0) {
+    return `its bundled ${missing.map(harnessName).join(" and ")} ${missing.length > 1 ? "are" : "is"} missing`;
+  }
+  return null;
+}
+function harnessName(h) {
+  return h === "claude-code" ? "Claude Code" : "Codex";
+}
+function lastLine(text) {
+  const lines2 = text.split("\n").map((l) => l.trim()).filter(Boolean);
+  return lines2.at(-1)?.slice(0, 300) ?? "";
+}
+var CompanionUpdater = class {
+  constructor(deps) {
+    this.deps = deps;
+    this.now = deps.now ?? Date.now;
+  }
+  deps;
+  staging = null;
+  ready = null;
+  swapping = false;
+  watchdog = null;
+  now;
+  // At start: a recorded swap to a version that will never start again (someone installed or
+  // chose another since) is dropped, or nothing would ever confirm it and no later update would
+  // be installed.
+  start() {
+    const pending = readUpdateState().pending;
+    const current = currentRoot();
+    const currentVersion = current ? packageVersion(current) : null;
+    if (superseded(pending, this.deps.own, ...currentVersion ? [currentVersion] : [])) {
+      updateUpdateState(({ pending: _gone, ...rest }) => rest);
+      this.deps.log.info(
+        { to: pending.to, own: this.deps.own },
+        `Dropped the update to ${pending.to}: Cabane ${this.deps.own} was installed since`
+      );
+    }
+  }
+  // The deadline for an update this process is the result of: ten minutes from the first time
+  // Cabane answers it without its stream connecting. Until Cabane answers, there's no verdict on
+  // time: a server or network that is down says nothing about the version.
+  armDeadline() {
+    if (this.watchdog) return;
+    this.watchdog = setTimeout(() => void this.giveUp(), UNCONFIRMED_WINDOW_MS);
+    this.watchdog.unref?.();
+  }
+  stop() {
+    if (this.watchdog) clearTimeout(this.watchdog);
+    this.watchdog = null;
+  }
+  async giveUp() {
+    const pending = readUpdateState().pending;
+    if (!pending || pending.to !== this.deps.own) return;
+    this.deps.log.warn(
+      { from: pending.from, to: pending.to },
+      `Cabane ${pending.to} didn't connect within ${UNCONFIRMED_WINDOW_MS / 6e4} minutes of Cabane answering; going back to ${pending.from}`
+    );
+    rollBack(
+      pending,
+      `it didn't connect to Cabane within ${UNCONFIRMED_WINDOW_MS / 6e4} minutes`
+    );
+    await this.deps.restart();
+  }
+  // Auto-update is on and something will restart this companion into the new version.
+  updatesItself() {
+    return this.deps.mode === "supervised" && this.deps.autoUpdate();
+  }
+  // What the heartbeat reports.
+  report() {
+    const last = readUpdateState().lastResult;
+    return { auto: this.updatesItself(), ...last ? { lastResult: last } : {} };
+  }
+  // A heartbeat landed. Record what the server named; confirm an update this process is the
+  // result of; then, when there is something newer, install it and swap when idle.
+  async onHeartbeat(server, streamConnected) {
+    const state = updateUpdateState((s) => ({
+      ...s,
+      ...server ? { server: { ...server, at: new Date(this.now()).toISOString() } } : {}
+    }));
+    if (state.pending?.to === this.deps.own) {
+      if (streamConnected) this.confirm(state.pending);
+      else this.armDeadline();
+    }
+    if (this.ready) {
+      await this.trySwap();
+      return;
+    }
+    this.maybeStage(false);
+  }
+  confirm(pending) {
+    this.stop();
+    updateUpdateState((s) => {
+      const { pending: _done, failed: _failed, ...rest } = s;
+      return {
+        ...rest,
+        lastResult: {
+          kind: "updated",
+          from: pending.from,
+          to: pending.to,
+          at: new Date(this.now()).toISOString()
+        }
+      };
+    });
+    const removed = pruneVersions([pending.to, pending.from]);
+    this.deps.log.info(
+      { from: pending.from, to: pending.to, removed },
+      `Updated Cabane from ${pending.from} to ${pending.to}`
+    );
+  }
+  // `cabane update`, from the person: install the latest now, whatever the setting.
+  async updateNow() {
+    const state = readUpdateState();
+    const latest = state.server?.latest;
+    if (!latest) return { ok: false, message: "Cabane hasn't said which version is latest yet." };
+    if (compareVersions(latest, this.deps.own) <= 0)
+      return { ok: true, message: `Cabane ${this.deps.own} is up to date.` };
+    if (state.pending?.to === latest) return { ok: true, message: this.waitingMessage(latest) };
+    if (this.ready === latest) {
+      void this.trySwap();
+      return { ok: true, message: this.waitingMessage(latest) };
+    }
+    this.maybeStage(true);
+    if (this.staging) await this.staging;
+    if (this.ready !== latest) {
+      const after = readUpdateState();
+      if (after.pending?.to === latest) return { ok: true, message: this.waitingMessage(latest) };
+      if (after.failed?.version === latest && after.failed.attempts === 0)
+        return { ok: false, message: `Cabane ${latest} isn't published yet. Try again later.` };
+      const failed = after.lastResult;
+      return {
+        ok: false,
+        message: failed?.kind === "failed" && failed.to === latest ? `Couldn't update to ${latest}: ${failed.reason ?? "see cabane logs"}.` : `Couldn't update to ${latest}. cabane logs says why.`
+      };
+    }
+    void this.trySwap();
+    return { ok: true, message: this.waitingMessage(latest) };
+  }
+  waitingMessage(version) {
+    if (this.deps.mode === "attached")
+      return `Cabane ${version} is installed. It runs from the next  cabane start.`;
+    return this.deps.isIdle() ? `Updating to ${version} now.` : `Updating to ${version} once the turns running now finish.`;
+  }
+  maybeStage(force) {
+    if (this.staging) return;
+    const version = versionToStage({
+      auto: this.updatesItself(),
+      own: this.deps.own,
+      state: readUpdateState(),
+      now: this.now(),
+      force
+    });
+    if (!version) return;
+    const stage = this.deps.stage ?? stageVersion;
+    this.staging = (async () => {
+      this.deps.log.info({ version }, `Installing Cabane ${version} beside this one`);
+      const outcome = await stage(version, this.deps.harnesses());
+      if (outcome.ok) {
+        this.ready = version;
+        updateUpdateState((s) => {
+          const { failed: _failed, ...rest } = s;
+          return rest;
+        });
+        return;
+      }
+      if (outcome.unpublished) {
+        this.deps.log.info({ version }, `Cabane ${version} isn't published yet; trying later`);
+        updateUpdateState((s) => ({
+          ...s,
+          failed: { version, attempts: 0, at: new Date(this.now()).toISOString() }
+        }));
+        return;
+      }
+      this.deps.log.warn({ version, reason: outcome.reason }, `Couldn't install Cabane ${version}`);
+      updateUpdateState((s) => {
+        const attempts = s.failed?.version === version ? s.failed.attempts + 1 : 1;
+        const at = new Date(this.now()).toISOString();
+        return {
+          ...s,
+          failed: { version, attempts, at },
+          // Reported once it has failed for good, so a registry blip isn't an email.
+          ...attempts >= MAX_STAGE_ATTEMPTS || force ? {
+            lastResult: {
+              kind: "failed",
+              from: this.deps.own,
+              to: version,
+              at,
+              reason: oneLine(outcome.reason)
+            }
+          } : {}
+        };
+      });
+    })().finally(() => {
+      this.staging = null;
+    });
+    void this.staging.then(() => this.trySwap());
+  }
+  // Swap into the ready version once nothing is running. Called on each heartbeat until it can.
+  async trySwap() {
+    const to = this.ready;
+    if (!to || this.swapping) return;
+    if (readUpdateState().pending) return;
+    if (this.deps.mode === "attached") {
+      this.select(to);
+      this.deps.log.info({ version: to }, `Cabane ${to} is installed; it runs from the next start`);
+      return;
+    }
+    if (!this.deps.isIdle()) return;
+    this.swapping = true;
+    try {
+      await this.deps.pauseStream();
+      const sleep4 = this.deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+      const deadline = this.now() + SWAP_DRAIN_MS;
+      await sleep4(250);
+      while (!this.deps.isIdle() && this.now() < deadline) await sleep4(250);
+      if (!this.deps.isIdle()) {
+        this.deps.resumeStream();
+        return;
+      }
+      this.select(to);
+      this.deps.log.info({ from: this.deps.own, to }, `Restarting into Cabane ${to}`);
+      await this.deps.restart();
+    } finally {
+      this.swapping = false;
+    }
+  }
+  // Record the swap and point `current` at `to`, leaving the guard that counts its starts.
+  select(to) {
+    const fromRoot = currentRoot() ?? ownPackageRoot();
+    writeBootGuard();
+    updateUpdateState((s) => ({
+      ...s,
+      pending: {
+        from: this.deps.own,
+        fromRoot,
+        to,
+        at: new Date(this.now()).toISOString(),
+        boots: 0
+      }
+    }));
+    pointCurrentAt(versionPackageRoot(to));
+    this.ready = null;
+  }
+};
+
 // src/version.ts
 import { createRequire as createRequire3 } from "module";
 var pkg = createRequire3(import.meta.url)("../package.json");
@@ -13263,6 +13898,7 @@ var COMPANION_VERSION = pkg.version;
 
 // src/supervisor.ts
 var HEARTBEAT_INTERVAL_MS = 3e4;
+var ARCHIVE_PRUNE_MS = 24 * 60 * 6e4;
 var SHUTDOWN_HEARTBEAT_WAIT_MS = 1e3;
 function positiveIntEnv(name) {
   const raw = process.env[name];
@@ -13344,6 +13980,10 @@ var CompanionSupervisor = class {
   // Which dispatches this process is running, so a redelivered frame doesn't
   // run the turn a second time.
   claims = new DispatchClaims();
+  archivePruneTimer = null;
+  // Keeps this companion current when its person said so; null until paired.
+  updater = null;
+  restartForUpdate;
   constructor(opts) {
     this.config = opts.config;
     this.log = opts.log;
@@ -13353,6 +13993,10 @@ var CompanionSupervisor = class {
     this.harnessVersions = opts.harnessVersions ?? emptyHarnessVersions();
     this.exitFn = opts.exit ?? ((code) => process.exit(code));
     this.reexecFn = opts.reexec ?? defaultReexec;
+    this.restartForUpdate = opts.restartForUpdate ?? (async () => {
+      await this.shutdown();
+      this.exitFn(0);
+    });
     this.dispatcherFactory = opts.dispatcherFactory;
     if (opts.runnerCommand) this.runnerCommand = opts.runnerCommand;
     if (opts.runnerProvider) this.providerForRunners = opts.runnerProvider;
@@ -13403,6 +14047,9 @@ var CompanionSupervisor = class {
         if (!this.runnerImage) await invalidateCompanionVolume(docker, image, source);
       }
       this.latchBootBundledState();
+      this.pruneSessionArchives();
+      this.archivePruneTimer = setInterval(() => this.pruneSessionArchives(), ARCHIVE_PRUNE_MS);
+      this.archivePruneTimer.unref?.();
     }
     const sandboxRows = agentSandboxRows(this.config);
     if (sandboxRows.length > 0 && this.dockerRunners()) {
@@ -13466,6 +14113,23 @@ var CompanionSupervisor = class {
         );
       }
     });
+    this.updater = new CompanionUpdater({
+      own: COMPANION_VERSION,
+      mode: updateMode(),
+      autoUpdate: () => this.config.update?.auto === true,
+      harnesses: () => this.connectedBundledHarnesses(),
+      isIdle: () => this.idle(),
+      pauseStream: async () => {
+        const sub = this.deviceSub;
+        if (!sub) return;
+        sub.stop();
+        await sub.finished;
+      },
+      resumeStream: () => void this.deviceSub?.resume(),
+      restart: () => this.restartForUpdate(),
+      log: this.log
+    });
+    this.updater.start();
     await this.refreshAssignments();
     this.deviceSub.start();
     const firstHeartbeat = startupHarnessRefresh.then(async () => {
@@ -13526,13 +14190,20 @@ var CompanionSupervisor = class {
         // Omitted until the first observed failure or heal, so the server's
         // status-less manifest synthesis still runs for a fresh companion.
         ...connectorReports.length > 0 ? { connectors: connectorReports } : {},
-        ...opencodeModels !== null ? { models: opencodeModels } : {}
+        ...opencodeModels !== null ? { models: opencodeModels } : {},
+        ...this.updater ? { update: this.updater.report() } : {}
       });
       this.hub.setDevice({ deviceId: res.deviceId });
       this.deviceId = res.deviceId;
       this.checkVersionSkew(res.serverVersion);
       this.heartbeated = true;
       void this.recoverRuns();
+      void this.updater?.onHeartbeat(res.companion, this.deviceConnected).catch(
+        (err) => this.log.warn(
+          { err: err instanceof Error ? err.message : String(err) },
+          "Couldn't check for a Cabane update; trying again on the next check-in."
+        )
+      );
     } catch (err) {
       this.log.warn(
         { ...apiErrorLogFields(err) },
@@ -14563,9 +15234,54 @@ var CompanionSupervisor = class {
       }
     }
   }
+  // A long-lived device keeps a session archive per conversation and agent it ever ran; those
+  // nobody has used in a month go.
+  pruneSessionArchives() {
+    try {
+      const removed = pruneIdleSessionArchives(cabaneDir());
+      if (removed.length > 0)
+        this.log.info({ removed: removed.length }, "runners: removed idle session archives");
+    } catch (err) {
+      this.log.warn(
+        { err: err instanceof Error ? err.message : String(err) },
+        "runners: couldn't remove idle session archives"
+      );
+    }
+  }
+  // Nothing running and nothing about to: no dispatch claimed, no turn chained, no recovery
+  // in progress. What a self-update swap waits for.
+  idle() {
+    if (this.claims.size > 0 || this.recovering) return false;
+    for (const wr of this.workspaces.values()) if (wr.chains.size > 0) return false;
+    return true;
+  }
+  // The bundled harnesses this device has connected, which a new version must still carry.
+  connectedBundledHarnesses() {
+    return [
+      ...isClaudeCodeConnected(this.config) ? ["claude-code"] : [],
+      ...isCodexEnabled(this.config) ? ["codex"] : []
+    ];
+  }
+  // `cabane update`, over the control socket: set whether this companion keeps itself current
+  // (`auto`), or install the latest now.
+  async update(auto) {
+    if (auto !== void 0) {
+      this.config = { ...this.config, update: { auto } };
+      saveConfig(this.config);
+      if (auto) this.kickHeartbeat();
+      return {
+        ok: true,
+        message: auto ? "Cabane will keep itself up to date. Updates install between turns and roll back if they fail." : "Cabane won't update itself. Run  cabane update  to update."
+      };
+    }
+    if (!this.updater) return { ok: false, message: "This computer isn't paired yet." };
+    return this.updater.updateNow();
+  }
   // ---- control actions ----
   async shutdown() {
     this.stopped = true;
+    this.updater?.stop();
+    if (this.archivePruneTimer) clearInterval(this.archivePruneTimer);
     if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
     if (this.pollTimer) clearInterval(this.pollTimer);
     const heartbeat = this.inFlightHeartbeat;
@@ -14600,9 +15316,9 @@ async function waitForBoundedHeartbeat(heartbeat) {
 }
 function defaultReexec() {
   clearRuntimeState();
-  void import("child_process").then(({ spawn: spawn8 }) => {
+  void import("child_process").then(({ spawn: spawn9 }) => {
     try {
-      const child = spawn8(process.execPath, process.argv.slice(1), {
+      const child = spawn9(process.execPath, process.argv.slice(1), {
         stdio: "inherit",
         detached: false
       });
@@ -14672,22 +15388,22 @@ function handleUncaught(log, err, origin) {
 }
 
 // src/crash-marker.ts
-import { existsSync as existsSync16, mkdirSync as mkdirSync13, readFileSync as readFileSync12, rmSync as rmSync12, writeFileSync as writeFileSync9 } from "fs";
-import { join as join23 } from "path";
+import { existsSync as existsSync18, mkdirSync as mkdirSync17, readFileSync as readFileSync15, rmSync as rmSync15, writeFileSync as writeFileSync11 } from "fs";
+import { join as join27 } from "path";
 function crashMarkerPath() {
-  return join23(cabaneDir(), "last-error.json");
+  return join27(cabaneDir(), "last-error.json");
 }
 function recordCrash(rec) {
   try {
-    mkdirSync13(cabaneDir(), { recursive: true });
-    writeFileSync9(crashMarkerPath(), JSON.stringify(rec, null, 2) + "\n");
+    mkdirSync17(cabaneDir(), { recursive: true });
+    writeFileSync11(crashMarkerPath(), JSON.stringify(rec, null, 2) + "\n");
   } catch {
   }
 }
 function clearCrash() {
   try {
     const path = crashMarkerPath();
-    if (existsSync16(path)) rmSync12(path, { force: true });
+    if (existsSync18(path)) rmSync15(path, { force: true });
   } catch {
   }
 }
@@ -14742,11 +15458,14 @@ async function createCompanionRuntime(opts = {}) {
     // process behind the marker pid is this companion (not a recycled pid).
     instanceId
   });
+  let restartForUpdate = async () => {
+  };
   const supervisor = new CompanionSupervisor({
     config: cfg,
     log,
     hub,
-    ...opts.checkHarness ? { checkHarness: opts.checkHarness } : {}
+    ...opts.checkHarness ? { checkHarness: opts.checkHarness } : {},
+    restartForUpdate: () => restartForUpdate()
   });
   await supervisor.start();
   const connectHarness = async (runtime, serverUrl) => {
@@ -14771,6 +15490,7 @@ async function createCompanionRuntime(opts = {}) {
     control = await startControlServer({
       status: () => hub.statusJson(),
       connect: (runtime, serverUrl) => connectHarness(runtime, serverUrl),
+      update: (auto) => supervisor.update(auto),
       stop: () => void supervisor.requestStop()
     });
     if (opts.dashboard) {
@@ -14823,6 +15543,10 @@ async function createCompanionRuntime(opts = {}) {
     } catch {
     }
   };
+  restartForUpdate = async () => {
+    await stop();
+    process.exit(0);
+  };
   return {
     ok: true,
     runtime: {