@cabane/companion 0.6.101 → 0.6.102

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { Command, Option } from "commander";
+import { Command, Option, InvalidArgumentError } from "commander";
 
 // src/control-socket.ts
 import { createHash } from "crypto";
@@ -307,6 +307,7 @@ var companionConfigSchema = z2.object({
   dashboardPort: z2.number().int().min(1).max(65535).optional(),
   autoOpen: z2.boolean().optional(),
   logLevel: z2.enum(["warn", "info", "debug"]).optional(),
+  logFormat: z2.enum(["human", "json"]).optional(),
   // CT270: the opencode runtime, when the operator runs one on this machine. The
   // operator installs opencode, starts `opencode serve` (auth via opencode's own
   // `/connect` — Cabane never sees provider keys), and points the companion at it
@@ -427,7 +428,7 @@ function loadConfigTolerant() {
   }
   const strict = companionConfigSchema.safeParse(parsed);
   if (strict.success) {
-    const { agents: agents2, prepareHook: prepareHook2, dashboardPort, autoOpen, logLevel, claudeCode: claudeCode2 } = strict.data;
+    const { agents: agents2, prepareHook: prepareHook2, dashboardPort, autoOpen, logLevel, logFormat, claudeCode: claudeCode2 } = strict.data;
     return {
       local: {
         ...agents2 !== void 0 ? { agents: agents2 } : {},
@@ -435,6 +436,7 @@ function loadConfigTolerant() {
         ...dashboardPort !== void 0 ? { dashboardPort } : {},
         ...autoOpen !== void 0 ? { autoOpen } : {},
         ...logLevel !== void 0 ? { logLevel } : {},
+        ...logFormat !== void 0 ? { logFormat } : {},
         ...claudeCode2 !== void 0 ? { claudeCode: claudeCode2 } : {}
       },
       note: null,
@@ -449,6 +451,7 @@ function loadConfigTolerant() {
   if (prepareHook.success) local.prepareHook = prepareHook.data;
   if (typeof obj.dashboardPort === "number") local.dashboardPort = obj.dashboardPort;
   if (typeof obj.autoOpen === "boolean") local.autoOpen = obj.autoOpen;
+  if (obj.logFormat === "human" || obj.logFormat === "json") local.logFormat = obj.logFormat;
   if (obj.logLevel === "warn" || obj.logLevel === "info" || obj.logLevel === "debug") {
     local.logLevel = obj.logLevel;
   }
@@ -954,7 +957,7 @@ function repairAction() {
 }
 function startupWarning(r) {
   const label = HARNESS_LABEL[r.runtime];
-  return `warning: ${label} is ${HARNESS_INTENT_WORD[r.runtime]}, but @cabane/companion's bundled ${label} ${missingNoun(r.status)} is missing. It will not be offered to Cabane. ${repairAction()} Then restart the companion.`;
+  return `${label} is ${HARNESS_INTENT_WORD[r.runtime]}, but its installation is incomplete (${missingNoun(r.status)} is missing). It cannot run turns until repaired. ${repairAction()} Then restart the companion.`;
 }
 function harnessIssueNote(runtime, status2) {
   const intent = HARNESS_INTENT_WORD[runtime];
@@ -1766,8 +1769,8 @@ function requestEnrollmentCode(baseUrl, opts = {}) {
     ...opts.label ? { label: opts.label } : {}
   });
 }
-function deviceLabelFromHostname(hostname3) {
-  const trimmed = hostname3.trim().replace(/\.local$/i, "");
+function deviceLabelFromHostname(hostname4) {
+  const trimmed = hostname4.trim().replace(/\.local$/i, "");
   if (trimmed.length === 0) return void 0;
   return trimmed.slice(0, 120);
 }
@@ -1895,73 +1898,207 @@ async function pair(opts = {}) {
 // src/cli.ts
 import { readFileSync as readFileSync11 } from "fs";
 
-// src/commands/start.ts
-import { hostname as hostname2 } from "os";
+// src/commands/logs.ts
+import { once } from "events";
+import { open } from "fs/promises";
+import { setTimeout as delay } from "timers/promises";
 
 // src/logger.ts
 import { createWriteStream, mkdirSync as mkdirSync5 } from "fs";
 import { dirname as dirname4, join as join6 } from "path";
+import { stripVTControlCharacters } from "util";
 import pino from "pino";
-import pretty from "pino-pretty";
 function companionLogPath() {
   return join6(cabaneDir(), "companion.log");
 }
-var CONSOLE_IGNORE = [
-  "pid",
-  "hostname",
-  "workspaceId",
-  "conversationId",
-  "agentId",
-  "messageId",
-  "sessionId",
-  "companionId"
-].join(",");
-function consoleShortId(log) {
-  const id = log.conversationId ?? log.workspaceId;
-  return typeof id === "string" && id.length > 0 ? id.slice(0, 8) : null;
-}
-function consoleMessageFormat(log, messageKey) {
-  const short = consoleShortId(log);
-  const msg = String(log[messageKey] ?? "");
-  return short ? `${short} ${msg}` : msg;
+function humanText(value) {
+  return stripVTControlCharacters(String(value ?? "")).replace(
+    /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/gi,
+    (id) => id.slice(0, 8)
+  ).replace(/\s+/g, " ").trim();
+}
+function formatHumanLine(record) {
+  const date = new Date(
+    typeof record.time === "number" || typeof record.time === "string" ? record.time : 0
+  );
+  const time = [date.getHours(), date.getMinutes(), date.getSeconds()].map((n) => String(n).padStart(2, "0")).join(":");
+  const level = typeof record.level === "number" ? record.level : 30;
+  const word = level >= 50 ? "error" : level >= 40 ? "warn" : level < 30 ? "debug" : "";
+  const conversation = typeof record.conversationId === "string" ? record.conversationId.slice(0, 8) : "";
+  const agent = humanText(record.agentName);
+  const context = [agent, conversation].filter(Boolean).join(" \xB7 ");
+  let line = `${time}  ${word ? `${word}  ` : ""}${context ? `${context}  ` : ""}${humanText(record.msg)}`;
+  const err = record.err;
+  const errorRecord = err !== null && typeof err === "object" ? err : null;
+  const message = humanText(errorRecord && "message" in errorRecord ? errorRecord.message : err);
+  const detail = typeof record.status === "number" ? `HTTP ${record.status}: ${humanText(record.responseBody) || message}` : message;
+  if (detail && !line.includes(detail)) line += ` (${detail})`;
+  if (level < 30) {
+    const hidden = /* @__PURE__ */ new Set([
+      "time",
+      "level",
+      "pid",
+      "hostname",
+      "msg",
+      "err",
+      "stack",
+      "agentName",
+      "conversationId",
+      "transcriptPath"
+    ]);
+    const details = Object.fromEntries(Object.entries(record).filter(([key]) => !hidden.has(key)));
+    if (Object.keys(details).length)
+      line += ` ${humanText(JSON.stringify(details)).slice(0, 2e3)}`;
+  }
+  if (record.transcriptPath)
+    line += `
+                            Transcript: ${humanText(record.transcriptPath)}`;
+  const stack = errorRecord && "stack" in errorRecord ? errorRecord.stack : record.stack;
+  if ((level >= 50 || level < 30) && typeof stack === "string") {
+    line += "\n" + stack.split("\n").map((part) => `    ${humanText(part)}`).join("\n");
+  }
+  return line + "\n";
 }
 var cached = null;
 var consoleLogging = true;
+var overrides = {};
+var formats = /* @__PURE__ */ new WeakMap();
 function setConsoleLogging(enabled) {
   consoleLogging = enabled;
 }
-function createLogger(destinations = {}) {
+function setLogOverrides(options) {
+  overrides = options;
+}
+function configureLogger(log, config) {
+  log.level = overrides.logLevel ?? config.logLevel ?? "info";
+  const state = formats.get(log);
+  if (state) state.format = overrides.logFormat ?? config.logFormat ?? "human";
+}
+function createLogger(destinations = {}, options = {}) {
   const path = companionLogPath();
   if (!destinations.file) mkdirSync5(dirname4(path), { recursive: true });
+  const file = destinations.file ?? createWriteStream(path, { flags: "a" });
+  const state = { format: options.logFormat ?? "human" };
   const streams = [];
+  const human = (chunk) => {
+    const record = JSON.parse(chunk);
+    let text = formatHumanLine(record);
+    const err = record.err;
+    if (log.isLevelEnabled("debug") && record.level !== 20 && typeof record.level === "number" && record.level < 50 && err && typeof err === "object" && "stack" in err) {
+      text += formatHumanLine({ ...record, level: 20, msg: "Error details" });
+    }
+    return text;
+  };
   if (process.env.CABANE_COMPANION_DAEMON !== "1") {
-    const consoleStream = pretty({
-      colorize: true,
-      ignore: CONSOLE_IGNORE,
-      messageFormat: (log, messageKey) => consoleMessageFormat(log, messageKey),
-      ...destinations.console ? { destination: destinations.console } : {}
-    });
     streams.push({
-      level: "info",
+      level: "debug",
       stream: {
         write(chunk) {
-          if (consoleLogging) consoleStream.write(chunk);
+          if (consoleLogging) (destinations.console ?? process.stdout).write(human(chunk));
         }
       }
     });
   }
   streams.push({
     level: "debug",
-    stream: destinations.file ?? createWriteStream(path, { flags: "a" })
+    stream: {
+      write(chunk) {
+        file.write(state.format === "json" ? chunk : human(chunk));
+      }
+    }
   });
-  return pino({ level: "debug" }, pino.multistream(streams));
+  const log = pino({ level: options.logLevel ?? "info" }, pino.multistream(streams));
+  formats.set(log, state);
+  return log;
 }
 function getLogger() {
   if (cached) return cached;
-  cached = createLogger();
+  let config = {};
+  try {
+    config = loadConfig() ?? {};
+  } catch {
+  }
+  cached = createLogger({}, { ...config, ...overrides });
   return cached;
 }
 
+// src/commands/logs.ts
+var BLOCK_BYTES = 64 * 1024;
+var TAIL_BYTES = 1024 * 1024;
+async function readLogTail(file, lines) {
+  const { size } = await file.stat();
+  let offset = size;
+  let bytes = 0;
+  let newlines = 0;
+  const chunks = [];
+  while (offset > 0 && newlines <= lines && bytes < TAIL_BYTES) {
+    const length = Math.min(BLOCK_BYTES, offset, TAIL_BYTES - bytes);
+    offset -= length;
+    const buffer = Buffer.alloc(length);
+    const { bytesRead } = await file.read(buffer, 0, length, offset);
+    const chunk = buffer.subarray(0, bytesRead);
+    chunks.unshift(chunk);
+    bytes += bytesRead;
+    for (const byte of chunk) if (byte === 10) newlines++;
+  }
+  let text = Buffer.concat(chunks).toString("utf8");
+  if (offset > 0) text = text.slice(text.indexOf("\n") + 1);
+  const trailing = text.endsWith("\n");
+  const rows = (trailing ? text.slice(0, -1) : text).split("\n");
+  text = lines === 0 ? "" : rows.slice(-lines).join("\n") + (trailing ? "\n" : "");
+  return { text, position: size };
+}
+async function logs(opts = {}) {
+  let file;
+  try {
+    file = await open(companionLogPath(), "r");
+  } catch (err) {
+    if (err && typeof err === "object" && "code" in err && err.code === "ENOENT") {
+      process.stdout.write("No log yet. Start the companion with cabane-companion start.\n");
+      return;
+    }
+    throw err;
+  }
+  const aborter = new AbortController();
+  const stop2 = () => aborter.abort();
+  if (opts.follow) {
+    process.on("SIGINT", stop2);
+    process.on("SIGTERM", stop2);
+  }
+  try {
+    const tail = await readLogTail(file, opts.lines ?? 50);
+    const write2 = async (chunk) => {
+      if (!process.stdout.write(chunk)) {
+        await once(process.stdout, "drain", { signal: aborter.signal }).catch((err) => {
+          if (!aborter.signal.aborted) throw err;
+        });
+      }
+    };
+    await write2(tail.text);
+    let position = tail.position;
+    const buffer = Buffer.alloc(BLOCK_BYTES);
+    while (opts.follow && !aborter.signal.aborted) {
+      if ((await file.stat()).size < position) position = 0;
+      const { bytesRead } = await file.read(buffer, 0, buffer.length, position);
+      if (bytesRead) {
+        position += bytesRead;
+        await write2(Buffer.from(buffer.subarray(0, bytesRead)));
+      } else {
+        await delay(200, void 0, { signal: aborter.signal }).catch((err) => {
+          if (!aborter.signal.aborted) throw err;
+        });
+      }
+    }
+  } finally {
+    process.removeListener("SIGINT", stop2);
+    process.removeListener("SIGTERM", stop2);
+    await file.close();
+  }
+}
+
+// src/commands/start.ts
+import { hostname as hostname3 } from "os";
+
 // src/runtime.ts
 import { randomUUID as randomUUID5 } from "crypto";
 
@@ -2524,6 +2661,246 @@ async function warnAboutHarnessReadiness(cfg, deps = {}) {
   warn(`No harness is connected on this device yet, so no agent turn can run here. ${guidance}`);
 }
 
+// src/supervisor.ts
+import { hostname as hostname2 } from "os";
+
+// packages/agent-runtime/src/failure.ts
+import { z as z4 } from "zod";
+var turnFailureSchema = z4.discriminatedUnion("kind", [
+  z4.object({ kind: z4.literal("usage_capped"), resetsAt: z4.string().optional() }),
+  z4.object({ kind: z4.literal("rate_limited") }),
+  z4.object({ kind: z4.literal("server_error") }),
+  z4.object({ kind: z4.literal("auth_expired") })
+]);
+var USAGE_CAPPED = "usage_capped";
+var RATE_LIMITED = "rate_limited";
+var SERVER_ERROR = "server_error";
+var AUTH_EXPIRED = "auth_expired";
+function encodeFailureReason(failure) {
+  switch (failure.kind) {
+    case "auth_expired":
+      return AUTH_EXPIRED;
+    case "server_error":
+      return SERVER_ERROR;
+    case "rate_limited":
+      return RATE_LIMITED;
+    case "usage_capped":
+      return failure.resetsAt ? `${USAGE_CAPPED}:${failure.resetsAt}` : USAGE_CAPPED;
+  }
+}
+function decodeFailureReason(reason) {
+  if (!reason) return null;
+  if (reason === AUTH_EXPIRED) return { kind: "auth_expired" };
+  if (reason === SERVER_ERROR) return { kind: "server_error" };
+  if (reason === RATE_LIMITED) return { kind: "rate_limited" };
+  if (reason === USAGE_CAPPED) return { kind: "usage_capped" };
+  if (reason.startsWith(`${USAGE_CAPPED}:`)) {
+    const iso = reason.slice(USAGE_CAPPED.length + 1);
+    return isValidIso(iso) ? { kind: "usage_capped", resetsAt: iso } : { kind: "usage_capped" };
+  }
+  return null;
+}
+function isValidIso(value) {
+  if (!value) return false;
+  const ms = Date.parse(value);
+  return Number.isFinite(ms);
+}
+function quotaForFailure(failure) {
+  if (failure.kind === "auth_expired") return { quotaState: "auth_expired", limitedUntil: null };
+  if (failure.kind === "usage_capped")
+    return { quotaState: "limited", limitedUntil: failure.resetsAt ?? null };
+  return null;
+}
+function resetsAtToIso(resetsAt) {
+  if (typeof resetsAt !== "number" || !Number.isFinite(resetsAt) || resetsAt <= 0) return void 0;
+  const ms = resetsAt < 1e12 ? resetsAt * 1e3 : resetsAt;
+  const date = new Date(ms);
+  const time = date.getTime();
+  if (Number.isNaN(time)) return void 0;
+  const YEAR_2000 = 9466848e5;
+  const now = Date.now();
+  if (time < YEAR_2000 || time > now + 366 * 24 * 60 * 60 * 1e3) return void 0;
+  return date.toISOString();
+}
+function classifyAssistantError(error) {
+  switch (error) {
+    case "rate_limit":
+      return { kind: "rate_limited" };
+    case "overloaded":
+    case "server_error":
+      return { kind: "server_error" };
+    case "authentication_failed":
+    case "oauth_org_not_allowed":
+      return { kind: "auth_expired" };
+    default:
+      return null;
+  }
+}
+function classifyErrorText(text) {
+  if (!text) return null;
+  const t = text.toLowerCase();
+  if (AUTH_PATTERNS.some((re) => re.test(t))) return { kind: "auth_expired" };
+  if (SERVER_PATTERNS.some((re) => re.test(t))) return { kind: "server_error" };
+  const withoutNegatedCap = t.replace(NEGATED_CAP, "");
+  const capNoun = CAP_PATTERNS.some((re) => re.test(withoutNegatedCap));
+  const rateToken = RATE_PATTERNS.some((re) => re.test(t));
+  if (capNoun) return { kind: "usage_capped" };
+  if (rateToken) return { kind: "rate_limited" };
+  if (BARE_LIMIT.test(t)) return { kind: "usage_capped" };
+  return null;
+}
+function classifyRuntimeNoticeText(text) {
+  if (!text) return null;
+  const normalized = text.trim().replace(/\s+/g, " ");
+  if (!normalized) return null;
+  if (/^you(?:'|’)ve hit your (?:session|weekly|usage) limit(?:\s*[·—-]\s*resets?\s+.+)?$/i.test(
+    normalized
+  )) {
+    return { kind: "usage_capped" };
+  }
+  return null;
+}
+var AUTH_PATTERNS = [
+  /authentication[_ ]error/,
+  /invalid[_ ]?(x-)?api[_ ]?key/,
+  /invalid bearer token/,
+  /\bunauthorized\b/,
+  /\b401\b/,
+  /oauth token.{0,20}expired/,
+  /(login|token|credential|session).{0,20}(has )?expired/,
+  /please run\s+\/login/,
+  /run `?\/login`?/,
+  /not authenticated/
+];
+var SERVER_PATTERNS = [
+  /\b5\d\d\b/,
+  // any 5xx status token (500 / 502 / 503 / 529 …)
+  /overloaded(_error)?/,
+  /\beconnreset\b/,
+  /\betimedout\b/,
+  /socket hang up/,
+  /fetch failed/
+];
+var CAP_PATTERNS = [/usage limit/, /weekly limit/, /session limit/, /\bquota\b/];
+var NEGATED_CAP = /not (your|a) usage limit/g;
+var RATE_PATTERNS = [/rate[_ ]?limit/, /\b429\b/, /too many requests/];
+var BARE_LIMIT = /\blimit (reached|exceeded)\b/;
+
+// src/log-copy.ts
+function turnFailureCopy(reason, runtime) {
+  const failure = decodeFailureReason(reason);
+  if (failure?.kind === "auth_expired") {
+    if (runtime === "claude-code")
+      return "Claude Code sign-in has expired on this machine. Open Claude Code, run /login, then reply in Cabane to try again.";
+    if (runtime === "codex")
+      return "Codex sign-in has expired on this machine. Run codex login, then reply in Cabane to try again.";
+    return "Sign-in has expired on this machine. Sign in to the coding agent, then reply in Cabane to try again.";
+  }
+  if (failure?.kind === "usage_capped")
+    return failure.resetsAt ? `The usage limit is reached; it resets around ${new Date(failure.resetsAt).toLocaleTimeString()}. Reply in Cabane after it resets.` : "The usage limit is reached. Try again later in Cabane.";
+  if (failure?.kind === "rate_limited")
+    return "The provider is limiting requests. Reply in Cabane to try again.";
+  if (failure?.kind === "server_error")
+    return "The provider had a temporary error. Reply in Cabane to try again.";
+  if (reason?.startsWith("missing_secret:"))
+    return `A required secret is missing: ${humanText(reason.slice(15))}. Add it to ~/.cabane/secrets.json, then reply in Cabane to try again.`;
+  if (reason?.startsWith("runtime_incomplete:"))
+    return "The coding agent installation is incomplete. Reinstall with npm i -g @cabane/companion@latest, then restart the companion.";
+  if (/^(runtime|codex|opencode)_unavailable:/.test(reason ?? ""))
+    return "The coding agent is unavailable on this machine. Enable it here or choose another connector in Cabane.";
+  if (reason?.startsWith("model_unavailable:"))
+    return "The selected model is unavailable. Choose a different model in the agent settings in Cabane.";
+  if (reason?.startsWith("prepare_failed:"))
+    return `Could not prepare the working environment (${humanText(reason.slice(15))}). Check the prepare command in ~/.cabane/config.json.`;
+  if (reason?.startsWith("fetch_failed:"))
+    return `Could not load the conversation (${humanText(reason.slice(13))}). Reply in Cabane to try again.`;
+  if (reason === "timeout_idle")
+    return "The coding agent stopped responding. Reply in Cabane to try again.";
+  if (reason === "timeout_total")
+    return "The turn ran longer than expected and was stopped. Reply in Cabane to continue.";
+  if (reason === "result_error:error_max_turns")
+    return "The coding agent reached its step limit. Reply in Cabane to continue.";
+  if (reason === "no_result" || reason === "empty_result" || reason === "empty_result_unverified")
+    return "The coding agent finished without a response. Reply in Cabane to try again.";
+  if (reason === "session_start_failed")
+    return "The coding agent could not start a session. Restart the companion, then reply in Cabane to try again.";
+  if (reason === "no_terminal")
+    return "The coding agent stopped before confirming the turn was complete. Reply in Cabane to continue.";
+  if (reason === "lease_unconfirmed")
+    return "Could not confirm with Cabane that the turn could start. Check this machine\u2019s connection, then reply in Cabane to try again.";
+  if (reason === "workspace_tools_missing")
+    return "The Cabane workspace tools did not load. Reply in Cabane to try again.";
+  if (reason?.startsWith("seq_floor_unavailable:"))
+    return "The interrupted turn could not safely continue. Reply in Cabane to continue.";
+  if (reason === "result_error:error_max_budget_usd")
+    return "The coding agent reached its spending limit. Check its budget settings before trying again in Cabane.";
+  if (reason === "result_error:error_max_structured_output_retries")
+    return "The coding agent could not produce the requested response format. Check the requested format, then reply in Cabane to try again.";
+  if (reason?.startsWith("result_error:"))
+    return "The coding agent stopped with an error while running. Check its transcript, then reply in Cabane to try again.";
+  if (reason === "setup_failed")
+    return "The turn could not be set up. Check the coding agent setup on this machine, then reply in Cabane to try again.";
+  if (reason === "unexpected_role")
+    return "The message could not start an agent response. Send a new message in Cabane to try again.";
+  if (reason === "lease_lost" || reason?.startsWith("lease_refused:"))
+    return "The turn could not keep its connection to Cabane. Reply in Cabane to try again.";
+  const detail = humanText(reason?.replace(/^error:/, "") ?? "").slice(0, 400);
+  if (/\b(EACCES|EPERM)\b|permission denied/i.test(detail)) {
+    const readable = detail.replace(/\b(EACCES|EPERM)\b/g, "permission denied");
+    return `The coding agent was denied access: ${readable}. Check access permissions for the reported file or command, then reply in Cabane to try again.`;
+  }
+  if (detail)
+    return `The coding agent reported: ${detail}. Check the coding agent setup on this machine, then reply in Cabane to try again.`;
+  return "The coding agent could not finish this turn. Reply in Cabane to try again.";
+}
+
+// src/api-error-shape.ts
+var LEASE_REFUSALS = /* @__PURE__ */ new Set([
+  "dispatch_not_admitted",
+  "turn_already_ended",
+  "turn_belongs_elsewhere"
+]);
+function apiErrorCode(err) {
+  if (!(err instanceof ApiError)) return null;
+  const body = err.body;
+  return typeof body === "object" && body !== null && typeof body.error === "string" ? body.error : null;
+}
+function leaseRefusal(err) {
+  const code = apiErrorCode(err);
+  if (code && LEASE_REFUSALS.has(code)) return code;
+  return null;
+}
+function isWriteFenceRefusal(err) {
+  return err instanceof ApiError && err.status === 409 && apiErrorCode(err) === "not_running";
+}
+var ERROR_BODY_LOG_CAP = 2e3;
+function describeErrorBody(body) {
+  if (body === void 0 || body === null) return void 0;
+  let text;
+  if (typeof body === "string") {
+    text = body;
+  } else {
+    try {
+      text = JSON.stringify(body);
+    } catch {
+      text = String(body);
+    }
+  }
+  if (text.length === 0) return void 0;
+  return text.length > ERROR_BODY_LOG_CAP ? `${text.slice(0, ERROR_BODY_LOG_CAP)}\u2026` : text;
+}
+function apiErrorLogFields(err) {
+  const fields = {
+    err: err instanceof Error ? err.message : String(err)
+  };
+  if (err instanceof ApiError) {
+    fields.status = err.status;
+    const body = describeErrorBody(err.body);
+    if (body !== void 0) fields.responseBody = body;
+  }
+  return fields;
+}
+
 // src/boot-id.ts
 import { randomUUID } from "crypto";
 var bootId = randomUUID();
@@ -2548,6 +2925,7 @@ var CabaneApi = class {
   // this guard two overlapping drains could each pick up the same queued entry
   // and double-send it (the server dedupes, but the wasted POSTs aren't free).
   draining = false;
+  lastDeliveryWarning = 0;
   get base() {
     return this.opts.baseUrl.endsWith("/") ? this.opts.baseUrl.slice(0, -1) : this.opts.baseUrl;
   }
@@ -2625,7 +3003,7 @@ var CabaneApi = class {
       if (signal?.aborted || isAbortError(err)) throw err;
       if (!isRetryable(err)) throw err;
       outbox.persist({ enqueuedAt: Date.now(), turnId, seq, method: "POST", path, body, kind });
-      this.opts.log?.warn(
+      this.opts.log?.debug(
         { kind, turnId, seq, err: err instanceof Error ? err.message : String(err) },
         "companion: commit queued to outbox after transient failure (will drain when the API returns)"
       );
@@ -2653,13 +3031,21 @@ var CabaneApi = class {
         } catch (err) {
           if (err instanceof ApiError && err.status >= 400 && err.status < 500) {
             this.opts.log?.warn(
-              { kind: entry.kind, turnId: entry.turnId, seq: entry.seq, status: err.status },
-              "companion outbox: discarding entry on terminal 4xx (will never land)"
+              { kind: entry.kind, turnId: entry.turnId, seq: entry.seq, ...apiErrorLogFields(err) },
+              "Cabane rejected a saved update; it could not be delivered. This companion may need an update: npm i -g @cabane/companion@latest"
             );
             outbox.remove(entry.turnId, entry.seq);
             progressed = true;
             continue;
           }
+          const now = Date.now();
+          if (now - entry.enqueuedAt >= 12e4 && now - this.lastDeliveryWarning >= 12e4) {
+            this.lastDeliveryWarning = now;
+            this.opts.log?.warn(
+              { ...apiErrorLogFields(err) },
+              "Updates have been waiting to reach Cabane for at least two minutes; still trying. Check the connection to Cabane."
+            );
+          }
           break;
         }
       }
@@ -2861,7 +3247,7 @@ var CabaneApi = class {
         body,
         kind: "active-run"
       });
-      this.opts.log?.warn(
+      this.opts.log?.debug(
         { conversationId, agentId, turnId },
         "companion: settle queued behind this turn's undelivered commits (drains in order)"
       );
@@ -2885,7 +3271,7 @@ var CabaneApi = class {
         body,
         kind: "active-run"
       });
-      this.opts.log?.warn(
+      this.opts.log?.debug(
         { conversationId, agentId, err: err instanceof Error ? err.message : String(err) },
         "companion: active-run write queued to outbox after transient failure (will drain when the API returns)"
       );
@@ -3293,44 +3679,44 @@ function noResume() {
 var TURN_PROTOCOL_VERSION = 1;
 
 // packages/agent-runtime/src/host-policy.ts
-import { z as z4 } from "zod";
-var hostPolicySchema = z4.object({
+import { z as z5 } from "zod";
+var hostPolicySchema = z5.object({
   // Host filesystem + shell: `Bash`/`Read`/`Write`/`Edit`/`Glob`/`Grep`, the
   // notebook read/write pair, git-worktree tools, and the `REPL` host code-exec
   // tool. Off under the locked assistant surface (today's `DISALLOWED_TOOLS`);
   // on under `coding` mode.
-  hostFs: z4.boolean(),
+  hostFs: z5.boolean(),
   // Public web (today's `WebSearch` / `WebFetch`, the `DEFAULT_WEB_TOOLS`). Public
   // web, not host reach — granted by default today, but expressible as a grant.
-  web: z4.boolean(),
+  web: z5.boolean(),
   // Browser automation (the Playwright MCP surface). Varies by host: a companion has
   // it, the house executor does not (CT230).
-  browser: z4.boolean(),
+  browser: z5.boolean(),
   // User-configured MCP servers permitted. False for the house executor
   // (CT227: Cabane agents run no user MCP servers), true for a personal companion.
-  userMcp: z4.boolean(),
+  userMcp: z5.boolean(),
   // Subagent / sub-dispatch (`Task` / `Agent`). A per-host GRANT (see the CT261
   // amendment above): `false` on the locked assistant/house surface (banned via
   // `DISALLOWED_TOOLS`), `true` under coding / custom where the fan-out is left to
   // the coding allow-hook (which reaches sub-agent tool calls, CT680) or the user
   // allowlist. The subagent completes within the turn, so
   // it's not the turn-model invariant `scheduling` is.
-  subagents: z4.boolean(),
+  subagents: z5.boolean(),
   // ── Hard platform invariants — always denied, never granted ────────────────
   // Deferred re-invocation / scheduling (`ScheduleWakeup`, the `Cron*` / `Task*`
   // families, `Monitor`, `Workflow`, …). A turn is one query that resolves when
   // `result` fires; a scheduled callback fires after the reply window has closed
   // and strands the agent (the CT155/CT156 rule).
-  scheduling: z4.literal("never"),
+  scheduling: z5.literal("never"),
   // Human-facing UI prompts (`AskUserQuestion`). A Cabane conversation has no
   // handler to answer a structured prompt, so the call hangs the turn
   // (`UNSUPPORTED_TOOLS`). The agent asks in its reply instead.
-  uiPrompts: z4.literal("never")
+  uiPrompts: z5.literal("never")
 });
 
 // packages/agent-runtime/src/turn-event.ts
-import { z as z5 } from "zod";
-var turnEventSchema = z5.discriminatedUnion("type", [
+import { z as z6 } from "zod";
+var turnEventSchema = z6.discriminatedUnion("type", [
   // The runtime's opaque session state, emitted when the adapter learns it (e.g.
   // the SDK `system/init` frame). The platform stores `state` verbatim per
   // (conversation, agent) and hands it back on the next turn; only the adapter
@@ -3350,25 +3736,25 @@ var turnEventSchema = z5.discriminatedUnion("type", [
   // on the companion, after the server committed the manifest). Runtime-neutral: a
   // plain boolean, not a runtime-specific reason string (that stays in the
   // adapter's `onWarn` log). Additive + optional — an old receiver ignores it.
-  z5.object({
-    type: z5.literal("session"),
-    state: z5.string(),
-    degraded: z5.boolean().optional()
+  z6.object({
+    type: z6.literal("session"),
+    state: z6.string(),
+    degraded: z6.boolean().optional()
   }),
   // One readable thinking summary. Maps `onThinking({ text })`. Transient —
   // surfaced live, never persisted as durable content.
-  z5.object({ type: z5.literal("thinking"), text: z5.string() }),
+  z6.object({ type: z6.literal("thinking"), text: z6.string() }),
   // Assistant text. Maps `onAssistantText({ text, final })` — `text`→`body`,
   // `final`→`terminal`. `terminal: false` is interim narration (commits as a
   // `progress` row); `terminal: true` is the turn's closing reply (commits as
   // the `final` row).
-  z5.object({ type: z5.literal("text"), body: z5.string(), terminal: z5.boolean() }),
+  z6.object({ type: z6.literal("text"), body: z6.string(), terminal: z6.boolean() }),
   // Runtime/provider-authored prose surfaced alongside a failed turn. Unlike
   // `text`, this is not the agent's narration or reply: the pump persists it as
   // `runtime_notice`, and the transcript renders it in the shared SystemNote
   // voice. Adapters emit it only from positive runtime evidence; the web never
   // classifies English strings.
-  z5.object({ type: z5.literal("runtime_notice"), body: z5.string() }),
+  z6.object({ type: z6.literal("runtime_notice"), body: z6.string() }),
   // A tool-activity transition. Maps `onToolActivity` — `toolUseId`→`id`,
   // `toolName`→`name` (already prefix-stripped: `cabane_read`, not
   // `mcp__cabane__cabane_read`), `summary` is the short card label. `phase`
@@ -3383,15 +3769,15 @@ var turnEventSchema = z5.discriminatedUnion("type", [
   // dropped the prefix; null for a host / built-in tool. The client tags Cabane
   // MCP calls (`=== 'cabane'`) with a subtle glyph. Nullable + optional so a
   // pre-CT496 producer that never sets it is unaffected (treated as null).
-  z5.object({
-    type: z5.literal("tool"),
-    id: z5.string(),
-    name: z5.string(),
-    phase: z5.enum(["start", "done", "error"]),
-    summary: z5.string(),
-    input: z5.unknown().optional(),
-    result: z5.unknown().optional(),
-    mcpServer: z5.string().nullable().optional()
+  z6.object({
+    type: z6.literal("tool"),
+    id: z6.string(),
+    name: z6.string(),
+    phase: z6.enum(["start", "done", "error"]),
+    summary: z6.string(),
+    input: z6.unknown().optional(),
+    result: z6.unknown().optional(),
+    mcpServer: z6.string().nullable().optional()
   }),
   // The turn's terminal outcome. Maps the `{ ok, reason }` both loops return
   // inline. `ok:false` carries a machine reason (`no_session`, an error code);
@@ -3435,54 +3821,54 @@ var turnEventSchema = z5.discriminatedUnion("type", [
   // `message_turn_metadata.resolved_model` / `resolved_config`. Optional ⇒
   // backward-compatible: an old adapter/companion omits them, a cancel has no result
   // event at all, and the columns stay null → the UI shows `—`.
-  z5.object({
-    type: z5.literal("result"),
-    ok: z5.boolean(),
-    reason: z5.string().optional(),
-    usage: z5.object({
-      inputTokens: z5.number(),
-      outputTokens: z5.number(),
-      cacheReadTokens: z5.number().optional(),
-      cacheCreationTokens: z5.number().optional(),
-      contextTokens: z5.number().optional(),
-      contextWindow: z5.number().optional()
+  z6.object({
+    type: z6.literal("result"),
+    ok: z6.boolean(),
+    reason: z6.string().optional(),
+    usage: z6.object({
+      inputTokens: z6.number(),
+      outputTokens: z6.number(),
+      cacheReadTokens: z6.number().optional(),
+      cacheCreationTokens: z6.number().optional(),
+      contextTokens: z6.number().optional(),
+      contextWindow: z6.number().optional()
     }).optional(),
-    resolvedModel: z5.string().optional(),
-    resolvedConfig: z5.object({
-      effort: z5.string().optional(),
-      thinking: z5.string().optional(),
-      reasoningEffort: z5.string().optional()
+    resolvedModel: z6.string().optional(),
+    resolvedConfig: z6.object({
+      effort: z6.string().optional(),
+      thinking: z6.string().optional(),
+      reasoningEffort: z6.string().optional()
     }).optional(),
     // CT1275: the harness-reported MCP inventory from this turn's init frame.
     // This is deliberately diagnostic-only: names, statuses and a count, never
     // server definitions, credentials or session ids. `initReceived:false`
     // distinguishes a missing init frame from a real empty inventory.
-    mcpInventory: z5.object({
-      initReceived: z5.boolean(),
-      servers: z5.array(z5.object({ name: z5.string(), status: z5.string() })),
-      toolCount: z5.number().int().nonnegative()
+    mcpInventory: z6.object({
+      initReceived: z6.boolean(),
+      servers: z6.array(z6.object({ name: z6.string(), status: z6.string() })),
+      toolCount: z6.number().int().nonnegative()
     }).optional()
   })
 ]);
 
 // packages/agent-runtime/src/turn-diagnostics.ts
-import { z as z6 } from "zod";
-var turnResultReasonSchema = z6.discriminatedUnion("kind", [
-  z6.object({ kind: z6.literal("usage_capped"), resetsAt: z6.string().optional() }),
-  z6.object({ kind: z6.literal("rate_limited") }),
-  z6.object({ kind: z6.literal("server_error") }),
-  z6.object({ kind: z6.literal("auth_expired") }),
-  z6.object({ kind: z6.literal("no_result") }),
-  z6.object({ kind: z6.literal("empty_result") }),
-  z6.object({ kind: z6.literal("empty_result_unverified") }),
-  z6.object({ kind: z6.literal("timeout_idle") }),
-  z6.object({ kind: z6.literal("timeout_total") }),
-  z6.object({ kind: z6.literal("cancelled") }),
-  z6.object({ kind: z6.literal("lease_lost") }),
-  z6.object({ kind: z6.literal("skipped") }),
-  z6.object({ kind: z6.literal("session_start_failed") }),
-  z6.object({ kind: z6.literal("workspace_tools_missing") }),
-  z6.object({ kind: z6.literal("runtime_error") })
+import { z as z7 } from "zod";
+var turnResultReasonSchema = z7.discriminatedUnion("kind", [
+  z7.object({ kind: z7.literal("usage_capped"), resetsAt: z7.string().optional() }),
+  z7.object({ kind: z7.literal("rate_limited") }),
+  z7.object({ kind: z7.literal("server_error") }),
+  z7.object({ kind: z7.literal("auth_expired") }),
+  z7.object({ kind: z7.literal("no_result") }),
+  z7.object({ kind: z7.literal("empty_result") }),
+  z7.object({ kind: z7.literal("empty_result_unverified") }),
+  z7.object({ kind: z7.literal("timeout_idle") }),
+  z7.object({ kind: z7.literal("timeout_total") }),
+  z7.object({ kind: z7.literal("cancelled") }),
+  z7.object({ kind: z7.literal("lease_lost") }),
+  z7.object({ kind: z7.literal("skipped") }),
+  z7.object({ kind: z7.literal("session_start_failed") }),
+  z7.object({ kind: z7.literal("workspace_tools_missing") }),
+  z7.object({ kind: z7.literal("runtime_error") })
 ]);
 var turnOutcomes = ["success", "failure", "cancelled", "skipped"];
 var turnSessionModes = ["fresh", "resumed", "degraded"];
@@ -3494,150 +3880,28 @@ var turnFinalSources = [
   "marker",
   "none"
 ];
-var turnDiagnosticsSchema = z6.object({
-  outcome: z6.enum(turnOutcomes),
+var turnDiagnosticsSchema = z7.object({
+  outcome: z7.enum(turnOutcomes),
   resultReason: turnResultReasonSchema.nullable(),
-  sessionMode: z6.enum(turnSessionModes),
-  sessionFingerprint: z6.string().regex(/^[a-f0-9]{16}$/).nullable(),
-  eventCounts: z6.object({
-    session: z6.number().int().nonnegative(),
-    text: z6.number().int().nonnegative(),
-    runtime_notice: z6.number().int().nonnegative(),
-    thinking: z6.number().int().nonnegative(),
-    tool: z6.number().int().nonnegative(),
-    result: z6.number().int().nonnegative()
+  sessionMode: z7.enum(turnSessionModes),
+  sessionFingerprint: z7.string().regex(/^[a-f0-9]{16}$/).nullable(),
+  eventCounts: z7.object({
+    session: z7.number().int().nonnegative(),
+    text: z7.number().int().nonnegative(),
+    runtime_notice: z7.number().int().nonnegative(),
+    thinking: z7.number().int().nonnegative(),
+    tool: z7.number().int().nonnegative(),
+    result: z7.number().int().nonnegative()
   }),
-  runtimeResultKind: z6.enum(turnRuntimeResultKinds).nullable(),
-  finalSource: z6.enum(turnFinalSources),
-  mcpInventory: z6.object({
-    initReceived: z6.boolean(),
-    servers: z6.array(z6.object({ name: z6.string(), status: z6.string() })),
-    toolCount: z6.number().int().nonnegative()
+  runtimeResultKind: z7.enum(turnRuntimeResultKinds).nullable(),
+  finalSource: z7.enum(turnFinalSources),
+  mcpInventory: z7.object({
+    initReceived: z7.boolean(),
+    servers: z7.array(z7.object({ name: z7.string(), status: z7.string() })),
+    toolCount: z7.number().int().nonnegative()
   }).optional()
 });
 
-// packages/agent-runtime/src/failure.ts
-import { z as z7 } from "zod";
-var turnFailureSchema = z7.discriminatedUnion("kind", [
-  z7.object({ kind: z7.literal("usage_capped"), resetsAt: z7.string().optional() }),
-  z7.object({ kind: z7.literal("rate_limited") }),
-  z7.object({ kind: z7.literal("server_error") }),
-  z7.object({ kind: z7.literal("auth_expired") })
-]);
-var USAGE_CAPPED = "usage_capped";
-var RATE_LIMITED = "rate_limited";
-var SERVER_ERROR = "server_error";
-var AUTH_EXPIRED = "auth_expired";
-function encodeFailureReason(failure) {
-  switch (failure.kind) {
-    case "auth_expired":
-      return AUTH_EXPIRED;
-    case "server_error":
-      return SERVER_ERROR;
-    case "rate_limited":
-      return RATE_LIMITED;
-    case "usage_capped":
-      return failure.resetsAt ? `${USAGE_CAPPED}:${failure.resetsAt}` : USAGE_CAPPED;
-  }
-}
-function decodeFailureReason(reason) {
-  if (!reason) return null;
-  if (reason === AUTH_EXPIRED) return { kind: "auth_expired" };
-  if (reason === SERVER_ERROR) return { kind: "server_error" };
-  if (reason === RATE_LIMITED) return { kind: "rate_limited" };
-  if (reason === USAGE_CAPPED) return { kind: "usage_capped" };
-  if (reason.startsWith(`${USAGE_CAPPED}:`)) {
-    const iso = reason.slice(USAGE_CAPPED.length + 1);
-    return isValidIso(iso) ? { kind: "usage_capped", resetsAt: iso } : { kind: "usage_capped" };
-  }
-  return null;
-}
-function isValidIso(value) {
-  if (!value) return false;
-  const ms = Date.parse(value);
-  return Number.isFinite(ms);
-}
-function quotaForFailure(failure) {
-  if (failure.kind === "auth_expired") return { quotaState: "auth_expired", limitedUntil: null };
-  if (failure.kind === "usage_capped")
-    return { quotaState: "limited", limitedUntil: failure.resetsAt ?? null };
-  return null;
-}
-function resetsAtToIso(resetsAt) {
-  if (typeof resetsAt !== "number" || !Number.isFinite(resetsAt) || resetsAt <= 0) return void 0;
-  const ms = resetsAt < 1e12 ? resetsAt * 1e3 : resetsAt;
-  const date = new Date(ms);
-  const time = date.getTime();
-  if (Number.isNaN(time)) return void 0;
-  const YEAR_2000 = 9466848e5;
-  const now = Date.now();
-  if (time < YEAR_2000 || time > now + 366 * 24 * 60 * 60 * 1e3) return void 0;
-  return date.toISOString();
-}
-function classifyAssistantError(error) {
-  switch (error) {
-    case "rate_limit":
-      return { kind: "rate_limited" };
-    case "overloaded":
-    case "server_error":
-      return { kind: "server_error" };
-    case "authentication_failed":
-    case "oauth_org_not_allowed":
-      return { kind: "auth_expired" };
-    default:
-      return null;
-  }
-}
-function classifyErrorText(text) {
-  if (!text) return null;
-  const t = text.toLowerCase();
-  if (AUTH_PATTERNS.some((re) => re.test(t))) return { kind: "auth_expired" };
-  if (SERVER_PATTERNS.some((re) => re.test(t))) return { kind: "server_error" };
-  const withoutNegatedCap = t.replace(NEGATED_CAP, "");
-  const capNoun = CAP_PATTERNS.some((re) => re.test(withoutNegatedCap));
-  const rateToken = RATE_PATTERNS.some((re) => re.test(t));
-  if (capNoun) return { kind: "usage_capped" };
-  if (rateToken) return { kind: "rate_limited" };
-  if (BARE_LIMIT.test(t)) return { kind: "usage_capped" };
-  return null;
-}
-function classifyRuntimeNoticeText(text) {
-  if (!text) return null;
-  const normalized = text.trim().replace(/\s+/g, " ");
-  if (!normalized) return null;
-  if (/^you(?:'|’)ve hit your (?:session|weekly|usage) limit(?:\s*[·—-]\s*resets?\s+.+)?$/i.test(
-    normalized
-  )) {
-    return { kind: "usage_capped" };
-  }
-  return null;
-}
-var AUTH_PATTERNS = [
-  /authentication[_ ]error/,
-  /invalid[_ ]?(x-)?api[_ ]?key/,
-  /invalid bearer token/,
-  /\bunauthorized\b/,
-  /\b401\b/,
-  /oauth token.{0,20}expired/,
-  /(login|token|credential|session).{0,20}(has )?expired/,
-  /please run\s+\/login/,
-  /run `?\/login`?/,
-  /not authenticated/
-];
-var SERVER_PATTERNS = [
-  /\b5\d\d\b/,
-  // any 5xx status token (500 / 502 / 503 / 529 …)
-  /overloaded(_error)?/,
-  /\beconnreset\b/,
-  /\betimedout\b/,
-  /socket hang up/,
-  /fetch failed/
-];
-var CAP_PATTERNS = [/usage limit/, /weekly limit/, /session limit/, /\bquota\b/];
-var NEGATED_CAP = /not (your|a) usage limit/g;
-var RATE_PATTERNS = [/rate[_ ]?limit/, /\b429\b/, /too many requests/];
-var BARE_LIMIT = /\blimit (reached|exceeded)\b/;
-
 // packages/agent-runtime/src/turn-diagnostics-normalize.ts
 function normalizeTurnResultReason(reason) {
   const classified = decodeFailureReason(reason);
@@ -4355,11 +4619,6 @@ function buildClaudeCodeOptions(req, augment) {
   const freshReason = "fresh" in resumeDecision ? resumeDecision.reason : void 0;
   const devControlsAutoMemory = req.local.claudeCode?.autoMemory === true;
   const model = parseClaudeCodeModel(config.model);
-  if (model === null) {
-    console.warn(
-      `[agent-runtime/claude-code] CT823: dispatching a subscription turn with NO concrete model (config.model=${JSON.stringify(config.model)}) \u2014 the SDK will fall back to its bundled default. This should be unreachable post-CT823; the model resolver should have supplied a concrete house default.`
-    );
-  }
   const base = {
     // model / effort: `model` is pinned only when the config names a real one —
     // omitted for "let it choose" (see `parseClaudeCodeModel`), so the SDK picks
@@ -4678,6 +4937,11 @@ function createClaudeCodeAdapter(deps = {}) {
         degraded = fresh.degraded;
         built = buildClaudeCodeOptions(req, deps.augmentOptions);
       }
+      if (built.options.model === void 0) {
+        deps.onWarn?.("Claude Code is using its default model because no model was resolved", {
+          model: req.config.model
+        });
+      }
       yield* runWithResumeRecovery(
         queryFn,
         req,
@@ -4710,7 +4974,7 @@ var HEALTHY_MCP_INVENTORY = {
   servers: [{ name: "cabane", status: "connected" }],
   toolCount: 1
 };
-function makeRequest(overrides = {}) {
+function makeRequest(overrides2 = {}) {
   return {
     systemPrompt: "system",
     prompt: "hi there",
@@ -4723,7 +4987,7 @@ function makeRequest(overrides = {}) {
     cabane: { mcpUrl: "https://cabane.test/api/mcp", bearer: "tok", activeConversationId: "conv" },
     local: { cwd: CWD },
     extra: { mcpServers: {} },
-    ...overrides
+    ...overrides2
   };
 }
 var init = (sessionId, model) => ({
@@ -5911,7 +6175,7 @@ var COMPANION_POLICY = {
   uiPrompts: "never"
 };
 var DIR = "/env/here";
-function makeRequest2(overrides = {}) {
+function makeRequest2(overrides2 = {}) {
   return {
     systemPrompt: "system",
     prompt: "hi there",
@@ -5922,7 +6186,7 @@ function makeRequest2(overrides = {}) {
     cabane: { mcpUrl: "https://cabane.test/api/mcp", bearer: "tok", activeConversationId: "conv" },
     local: { cwd: DIR },
     extra: { mcpServers: {} },
-    ...overrides
+    ...overrides2
   };
 }
 var textPart = (id, text) => ({
@@ -6736,11 +7000,6 @@ function buildRunSpec2(req, resumeThreadId, instructionsFile = null, threadPromp
   const dialect = readCodexDialect(config.runtimeOptions);
   const baseInstructionsFile = !policy.hostFs && instructionsFile ? instructionsFile : null;
   const model = config.model ? parseCodexModel(config.model) : null;
-  if (model === null) {
-    console.warn(
-      `[agent-runtime/codex] CT823: dispatching a subscription turn with NO concrete model (config.model=${JSON.stringify(config.model)}) \u2014 Codex will fall back to its own default. This should be unreachable post-CT823; the model resolver should have supplied a concrete house default.`
-    );
-  }
   const promptFingerprint = fingerprintPrompt(req.systemPrompt);
   const threadHasThisPrompt = resumeThreadId !== null && threadPromptFingerprint !== null && threadPromptFingerprint === promptFingerprint;
   const promptRidesInput = baseInstructionsFile === null && !threadHasThisPrompt;
@@ -6937,6 +7196,11 @@ function createCodexAdapter(deps = {}) {
           instructions?.path ?? null,
           threadPromptFingerprint
         );
+        if (spec.model === null) {
+          deps.onWarn?.("Codex is using its default model because no model was resolved", {
+            model: req.config.model
+          });
+        }
         const result = await transport.run(spec, signal);
         if (signal.aborted) return;
         yield* decodeCodexStream(result.events, {
@@ -6988,7 +7252,7 @@ var COMPANION_POLICY2 = {
 };
 var DIR2 = "/env/here";
 var PROMPT = "system";
-function makeRequest3(overrides = {}) {
+function makeRequest3(overrides2 = {}) {
   return {
     systemPrompt: PROMPT,
     prompt: "hi there",
@@ -7004,7 +7268,7 @@ function makeRequest3(overrides = {}) {
     cabane: { mcpUrl: "https://cabane.test/api/mcp", bearer: "tok", activeConversationId: "conv" },
     local: { cwd: DIR2 },
     extra: { mcpServers: {} },
-    ...overrides
+    ...overrides2
   };
 }
 var threadStarted = (threadId) => ({
@@ -8204,53 +8468,6 @@ async function writeCodexInstructionsFile(contents) {
   };
 }
 
-// src/api-error-shape.ts
-var LEASE_REFUSALS = /* @__PURE__ */ new Set([
-  "dispatch_not_admitted",
-  "turn_already_ended",
-  "turn_belongs_elsewhere"
-]);
-function apiErrorCode(err) {
-  if (!(err instanceof ApiError)) return null;
-  const body = err.body;
-  return typeof body === "object" && body !== null && typeof body.error === "string" ? body.error : null;
-}
-function leaseRefusal(err) {
-  const code = apiErrorCode(err);
-  if (code && LEASE_REFUSALS.has(code)) return code;
-  return null;
-}
-function isWriteFenceRefusal(err) {
-  return err instanceof ApiError && err.status === 409 && apiErrorCode(err) === "not_running";
-}
-var ERROR_BODY_LOG_CAP = 2e3;
-function describeErrorBody(body) {
-  if (body === void 0 || body === null) return void 0;
-  let text;
-  if (typeof body === "string") {
-    text = body;
-  } else {
-    try {
-      text = JSON.stringify(body);
-    } catch {
-      text = String(body);
-    }
-  }
-  if (text.length === 0) return void 0;
-  return text.length > ERROR_BODY_LOG_CAP ? `${text.slice(0, ERROR_BODY_LOG_CAP)}\u2026` : text;
-}
-function apiErrorLogFields(err) {
-  const fields = {
-    err: err instanceof Error ? err.message : String(err)
-  };
-  if (err instanceof ApiError) {
-    fields.status = err.status;
-    const body = describeErrorBody(err.body);
-    if (body !== void 0) fields.responseBody = body;
-  }
-  return fields;
-}
-
 // src/turn-seq-floor.ts
 var SeqFloorUnavailable = class extends Error {
   constructor(detail) {
@@ -8266,7 +8483,7 @@ function resolveSeqFloor(sources, ctx) {
     throw new SeqFloorUnavailable("server sent no committed floor for a resumed turn");
   }
   const floor = Math.max(serverFloor, outboxFloor);
-  ctx.log.info(
+  ctx.log.debug(
     { turnId: ctx.turnId, floor, outboxFloor, serverFloor },
     "companion: resumed turn \u2014 seq counter seeded above its committed high-water mark"
   );
@@ -8276,7 +8493,7 @@ function readOutboxFloor(read, turnId, log) {
   try {
     return read(turnId);
   } catch (err) {
-    log.error(
+    log.debug(
       { turnId, err: err instanceof Error ? err.message : String(err) },
       "companion: the on-disk outbox floor is unreadable; refusing to resume"
     );
@@ -8518,7 +8735,10 @@ var TurnCommitter = class {
   constructor(deps) {
     this.deps = deps;
     this.onError = (err, hook) => {
-      deps.log.warn({ ...apiErrorLogFields(err), hook }, "dispatcher: transcript callback failed");
+      deps.log.warn(
+        { ...apiErrorLogFields(err), hook },
+        `Couldn't save ${String(deps.log.bindings().agentName ?? "the agent")}'s ${hook === "text" ? "reply" : "reply or activity"} to Cabane. This companion may need an update: npm i -g @cabane/companion@latest`
+      );
       deps.onCommitFailed?.(err);
     };
     const commit = {
@@ -8653,8 +8873,8 @@ async function postIncompleteNotice(ctx, harness, resolution) {
     return true;
   } catch (err) {
     ctx.log.warn(
-      { err: err instanceof Error ? err.message : String(err) },
-      "dispatcher: runtime-incomplete notice post failed"
+      { ...apiErrorLogFields(err) },
+      "Couldn't save the explanation to Cabane. This companion may need an update: npm i -g @cabane/companion@latest"
     );
     return false;
   }
@@ -8664,7 +8884,7 @@ async function checkBundledBinary(ctx) {
   if (!harness) return null;
   const resolution = resolve(ctx, harness);
   if (resolution.status === "present") return null;
-  ctx.log.error(
+  ctx.log.debug(
     {
       runtime: harness,
       status: resolution.status,
@@ -8684,7 +8904,7 @@ async function reclassifyThrow(ctx, opts) {
   if (!harness || opts.aborted) return null;
   const resolution = resolve(ctx, harness);
   if (resolution.status === "present") return null;
-  ctx.log.error(
+  ctx.log.debug(
     {
       runtime: harness,
       status: resolution.status,
@@ -8881,13 +9101,13 @@ var TurnExecution = class {
       );
     } catch (err) {
       turnLog.warn(
-        { err: err instanceof Error ? err.message : String(err) },
-        "dispatcher: pre-run active-run clear failed terminally; server age-sweep is the backstop"
+        { ...apiErrorLogFields(err) },
+        "Couldn't update the turn's status in Cabane. Check the conversation before trying again."
       );
     }
     const durationMs = Date.now() - startedAt;
     this.supervisor.notifyEnd({ id: payload.messageId, ok: false, durationMs, reason });
-    return { ok: false, durationMs, reason };
+    return { ok: false, durationMs, reason, runtime: this.turnContext?.runtime };
   }
   // The post-admission analogue of `concludeBeforeRun` (Codo's stack review,
   // blocking finding #2): this turn WAS admitted — it holds the conversation's
@@ -8917,12 +9137,12 @@ var TurnExecution = class {
     } catch (err) {
       turnLog.warn(
         { ...apiErrorLogFields(err), turnId },
-        "dispatcher: admitted-run settle failed terminally; server age-sweep is the backstop"
+        "Couldn't save the turn's result to Cabane. This companion may need an update: npm i -g @cabane/companion@latest"
       );
     }
     const durationMs = Date.now() - startedAt;
     this.supervisor.notifyEnd({ id: payload.messageId, ok: false, durationMs, reason });
-    return { ok: false, durationMs, reason };
+    return { ok: false, durationMs, reason, runtime: this.turnContext?.runtime };
   }
   async fetchContext() {
     const { payload, turnId, turnLog } = this;
@@ -8939,20 +9159,20 @@ var TurnExecution = class {
     } catch (err) {
       const status2 = err instanceof ApiError ? err.status : 0;
       if (status2 === 404) {
-        turnLog.warn(
+        turnLog.debug(
           { err: err instanceof Error ? err.message : String(err) },
           "dispatcher: turn-context 404 (stale event \u2014 conversation/message/participant gone); skipping"
         );
         throw this.concluded("turn_context_not_found");
       }
       if (status2 === 409 && apiErrorCode(err) === "dispatch_not_admitted") {
-        turnLog.warn(
+        turnLog.debug(
           "dispatcher: turn-context 409 dispatch_not_admitted (wake already resolved); skipping"
         );
         throw this.concluded("turn_context_not_admitted");
       }
       const reason = err instanceof Error ? err.message : String(err);
-      turnLog.error({ err: reason }, "dispatcher: failed to fetch turn context");
+      turnLog.debug({ err: reason }, "dispatcher: failed to fetch turn context");
       const fetchReason = `fetch_failed: ${reason}`;
       throw this.concluded(fetchReason, fetchReason);
     }
@@ -8962,7 +9182,7 @@ var TurnExecution = class {
       this.resumedFromSeq = resolveSeqFloor(sources, { turnId, log: turnLog });
       this.seqCounter = Math.max(this.seqCounter, this.resumedFromSeq);
       this.resumedSpoke = turnContext.turnSpoke === true || outboxSpoke;
-      if (this.resumedSpoke) turnLog.info({ turnId }, "dispatcher: resumed span already spoke");
+      if (this.resumedSpoke) turnLog.debug({ turnId }, "dispatcher: resumed span already spoke");
     }
   }
   gateTrigger() {
@@ -8970,7 +9190,7 @@ var TurnExecution = class {
     const message = this.turnContext.message;
     const isDispatchableTrigger = message.role === "user" || message.role === "agent" || message.role === "system";
     if (!isDispatchableTrigger) {
-      turnLog.warn({ role: message.role }, "dispatcher: trigger role not dispatchable \u2014 skipping");
+      turnLog.debug({ role: message.role }, "dispatcher: trigger role not dispatchable \u2014 skipping");
       throw this.concluded("unexpected_role", UNEXPECTED_ROLE_REASON);
     }
     this.supervisor.notifyStart({
@@ -8981,7 +9201,9 @@ var TurnExecution = class {
   }
   async resolveSecrets() {
     const { payload, workspaceId, turnLog } = this;
-    const secretStore = this.opts.secretStore ?? loadSecretStoreTolerant((m) => turnLog.warn(m));
+    const secretStore = this.opts.secretStore ?? loadSecretStoreTolerant(
+      (m) => turnLog.warn({ err: m }, "Could not read the secrets file. Check ~/.cabane/secrets.json.")
+    );
     const { servers: resolvedMcpServers, missing } = resolveMcpSecrets(
       // CT262: the user MCP DEFINITIONS (placeholder form) come from the turn
       // context now, not a separate `getAgentSelf` run-config fetch.
@@ -8989,7 +9211,7 @@ var TurnExecution = class {
       secretStore
     );
     if (missing.length > 0) {
-      turnLog.error({ missing }, "dispatcher: turn needs secrets not declared on this companion");
+      turnLog.debug({ missing }, "dispatcher: turn needs secrets not declared on this companion");
       const reason = missingSecretReason(missing);
       throw this.concluded(reason, reason);
     }
@@ -9004,7 +9226,7 @@ var TurnExecution = class {
     if (effectiveCwd && !existsSync10(effectiveCwd)) {
       turnLog.warn(
         { cwd: effectiveCwd },
-        "dispatcher: configured working directory does not exist on this device \u2014 falling back to the process cwd"
+        "The working directory is missing; using the companion's directory instead. Check this agent's working directory setting."
       );
       effectiveCwd = void 0;
     }
@@ -9012,7 +9234,7 @@ var TurnExecution = class {
     if (prepareHook) {
       let cached2 = readPrepared(workspaceId, payload.conversationId, payload.agentId);
       if (cached2 && !checkoutState(cached2.cwd).ok) {
-        turnLog.warn(
+        turnLog.debug(
           { cwd: cached2.cwd, reason: checkoutState(cached2.cwd).reason },
           "dispatcher: the prepared checkout is no longer usable \u2014 re-running the prepare hook to restore it"
         );
@@ -9039,7 +9261,7 @@ var TurnExecution = class {
             });
           } catch (err) {
             const reason = err instanceof Error ? err.message : String(err);
-            turnLog.error({ err: reason }, "dispatcher: prepare hook rejected a prepared turn");
+            turnLog.debug({ err: reason }, "dispatcher: prepare hook rejected a prepared turn");
             const failReason = `prepare_failed: ${reason}`;
             throw this.concluded(failReason, failReason);
           }
@@ -9059,7 +9281,7 @@ var TurnExecution = class {
             phase,
             seq
           }).catch((err) => {
-            turnLog.warn(
+            turnLog.debug(
               { err: err instanceof Error ? err.message : String(err), phase },
               "dispatcher: preparing-activity report failed (continuing with the hook)"
             );
@@ -9099,7 +9321,7 @@ var TurnExecution = class {
           clearTimeout(preparingTimer);
           if (preparingStarted) reportPreparing("error");
           const reason = err instanceof Error ? err.message : String(err);
-          turnLog.error({ err: reason }, "dispatcher: prepare hook failed");
+          turnLog.debug({ err: reason }, "dispatcher: prepare hook failed");
           const failReason = `prepare_failed: ${reason}`;
           throw this.concluded(failReason, failReason);
         }
@@ -9147,14 +9369,14 @@ var TurnExecution = class {
     } catch (err) {
       const refusal = leaseRefusal(err);
       if (refusal === "dispatch_not_admitted" || refusal === "turn_already_ended") {
-        turnLog.error(
+        turnLog.debug(
           { refusal, turnId },
           "dispatcher: refused a turn lease; not running the model"
         );
         throw this.concluded(`lease_refused: ${refusal}`);
       }
       const reason = refusal ? `lease_refused: ${refusal}` : "lease_unconfirmed";
-      turnLog.error(
+      turnLog.debug(
         { refusal, turnId, err: err instanceof Error ? err.message : String(err) },
         "dispatcher: turn lease not confirmed; not running the model"
       );
@@ -9206,7 +9428,7 @@ var TurnExecution = class {
   async selectAdapter() {
     const { payload, workspaceId, turnId, turnLog } = this;
     await guardBundledBinary(this.integrityContext(), (r, e) => this.concluded(r, e), this.outcome);
-    const onWarn = (msg, meta) => turnLog.warn(meta ?? {}, msg);
+    const onWarn = (msg, meta) => turnLog.debug(meta ?? {}, msg);
     const adapters = [];
     if (this.opts.claudeCodeAvailable?.() ?? true) {
       adapters.push(createClaudeCodeAdapter({ queryFn: this.opts.queryFn, onWarn }));
@@ -9228,7 +9450,7 @@ var TurnExecution = class {
       this.adapter = selectAdapter(registry, this.turnContext.runtime);
     } catch (err) {
       if (!(err instanceof RuntimeUnavailableError)) throw err;
-      turnLog.error(
+      turnLog.debug(
         { runtime: err.runtime, available: err.available },
         "dispatcher: turn runtime not available on this device"
       );
@@ -9241,8 +9463,8 @@ var TurnExecution = class {
         });
       } catch (postErr) {
         turnLog.warn(
-          { err: postErr instanceof Error ? postErr.message : String(postErr) },
-          "dispatcher: runtime-unavailable notice post failed"
+          { ...apiErrorLogFields(postErr) },
+          "Couldn't save the explanation to Cabane. This companion may need an update: npm i -g @cabane/companion@latest"
         );
         const reason = `runtime_unavailable:${err.runtime}`;
         throw this.concluded(reason, reason);
@@ -9270,7 +9492,7 @@ var TurnExecution = class {
         false,
         true
       );
-      turnLog.warn(
+      turnLog.debug(
         { reason },
         "dispatcher: stored session not resumed \u2014 the turn context was recomposed for a fresh session"
       );
@@ -9281,8 +9503,8 @@ var TurnExecution = class {
       };
     } catch (err) {
       turnLog.error(
-        { reason, err: err instanceof Error ? err.message : String(err) },
-        "dispatcher: could not recompose the turn context for a fresh session \u2014 running on the incremental one, degraded"
+        { reason, ...apiErrorLogFields(err) },
+        "Couldn't load the full conversation; continuing with the recent messages."
       );
       return null;
     }
@@ -9303,7 +9525,10 @@ var TurnExecution = class {
         dispatchId: this.dispatchId,
         message: this.turnContext.message.body
       },
-      (m) => turnLog.warn(m)
+      (m) => turnLog.warn(
+        { err: m },
+        "Could not save the transcript. Check free disk space and access to ~/.cabane."
+      )
     ) : null;
     const turnRuntime = this.turnContext.runtime;
     const committer = this.committer = new TurnCommitter({
@@ -9343,8 +9568,8 @@ var TurnExecution = class {
         }
       } catch (err) {
         turnLog.warn(
-          { err: err instanceof Error ? err.message : String(err) },
-          "dispatcher: turn-control intent fetch failed; the skip for this turn is dropped"
+          { ...apiErrorLogFields(err) },
+          "Couldn't check whether the agent chose to pass; the turn may appear to have failed."
         );
       }
     };
@@ -9352,7 +9577,7 @@ var TurnExecution = class {
     const fireTimeout = (reason) => {
       if (abortController.signal.aborted) return;
       o.timeoutReason = reason;
-      turnLog.warn(
+      turnLog.debug(
         { reason, idleTimeoutMs, totalTimeoutMs },
         "dispatcher: turn timeout \u2014 aborting"
       );
@@ -9382,7 +9607,7 @@ var TurnExecution = class {
         if (state !== "ended") return;
         if (abortController.signal.aborted) return;
         o.leaseLost = true;
-        turnLog.warn(
+        turnLog.debug(
           { turnId, trigger },
           "dispatcher: this turn is no longer running server-side \u2014 aborting the loop"
         );
@@ -9410,7 +9635,7 @@ var TurnExecution = class {
         if (isContentBearingEvent(event)) o.contentBearingEvents += 1;
         armIdle();
         if (abortController.signal.aborted) {
-          turnLog.info("dispatcher: aborted mid-turn");
+          turnLog.debug("dispatcher: aborted mid-turn");
           o.okResult = false;
           o.resultReason = o.timeoutReason ?? "cancelled";
           break;
@@ -9433,18 +9658,18 @@ var TurnExecution = class {
                 o.sessionWriteRejected = true;
                 turnLog.error(
                   {
-                    err: err instanceof Error ? err.message : String(err),
+                    ...apiErrorLogFields(err),
                     status: status2,
                     responseBody: describeErrorBody(err instanceof ApiError ? err.body : void 0),
                     stateLength: event.state.length,
                     runtime: turnRuntime
                   },
-                  "dispatcher: session-state write REJECTED (4xx) \u2014 this turn is not resumable and the next turn starts with no memory of it"
+                  "Couldn't save the agent's memory in Cabane. The next turn will start a new session. This companion may need an update: npm i -g @cabane/companion@latest"
                 );
               } else {
                 turnLog.warn(
-                  { err: err instanceof Error ? err.message : String(err) },
-                  "dispatcher: session-id write failed (will retry next turn)"
+                  { ...apiErrorLogFields(err) },
+                  "Couldn't save the agent's memory; trying again next turn."
                 );
               }
             }
@@ -9485,7 +9710,7 @@ var TurnExecution = class {
         await this.applyRecordedTurnControlIntent();
       }
       if (!abortController.signal.aborted && this.skipState.skipped) {
-        turnLog.info(
+        turnLog.debug(
           { reason: this.skipState.reason, turnId, ok: o.okResult },
           "agent skipped turn (skip_turn)"
         );
@@ -9493,7 +9718,7 @@ var TurnExecution = class {
     } catch (err) {
       o.okResult = false;
       o.resultReason = err instanceof Error ? err.message : String(err);
-      turnLog.error({ err: o.resultReason }, "dispatcher: SDK query threw");
+      turnLog.debug({ err: o.resultReason }, "dispatcher: SDK query threw");
       o.runtimeIncomplete = await absorbBundledLoss(
         this.integrityContext(),
         abortController.signal.aborted,
@@ -9518,7 +9743,7 @@ var TurnExecution = class {
                 kind: "usage_capped",
                 resetsAt: health.limitedUntil
               });
-              turnLog.info(
+              turnLog.debug(
                 { runtime: turnRuntime, limitedUntil: health.limitedUntil },
                 "dispatcher: idle-timeout on a capped runtime \u2014 reclassified as usage_capped (CT639)"
               );
@@ -9569,7 +9794,7 @@ var TurnExecution = class {
       if (diagnosticReason && !["usage_capped", "rate_limited", "auth_expired", "cancelled", "skipped"].includes(
         diagnosticReason.kind
       )) {
-        turnLog.warn(
+        turnLog.debug(
           {
             workspaceId,
             turnId,
@@ -9597,8 +9822,8 @@ var TurnExecution = class {
         );
       } catch (err) {
         turnLog.warn(
-          { err: err instanceof Error ? err.message : String(err) },
-          "dispatcher: active-run clear failed terminally; server age-sweep is the backstop"
+          { ...apiErrorLogFields(err) },
+          "Couldn't save the turn's result to Cabane. This companion may need an update: npm i -g @cabane/companion@latest"
         );
       }
       this.supervisor.releaseAbort(turnId, abortController);
@@ -9615,9 +9840,6 @@ var TurnExecution = class {
         ...o.resultReason ? { reason: o.resultReason } : {},
         durationMs
       });
-      if (!o.okResult && o.resultReason !== "cancelled") {
-        turnLog.info(`turn failed \u2014 full this.transcript: ${this.transcript.path}`);
-      }
       if (o.settledDiagnostics?.resultReason?.kind === "empty_result" || o.settledDiagnostics?.resultReason?.kind === "empty_result_unverified") {
         this.transcript.preserveAnomaly();
       }
@@ -9642,7 +9864,9 @@ var TurnExecution = class {
     return {
       ok: false,
       durationMs,
-      ...o.resultReason ? { reason: o.resultReason } : {}
+      ...o.resultReason ? { reason: o.resultReason } : {},
+      runtime: this.turnContext.runtime,
+      ...this.transcript ? { transcriptPath: tildePath(this.transcript.path) } : {}
     };
   }
 };
@@ -9848,7 +10072,7 @@ var Outbox = class {
       }
       this.log?.warn(
         { workspaceId: this.workspaceId, err: err instanceof Error ? err.message : String(err) },
-        "companion outbox: failed to persist entry"
+        "Couldn't save an update on this machine. Check free disk space and access to ~/.cabane."
       );
       return;
     }
@@ -9936,7 +10160,7 @@ var Outbox = class {
   dropCorrupt(full) {
     this.log?.warn(
       { workspaceId: this.workspaceId, file: full },
-      "companion outbox: dropping unreadable entry"
+      "A saved update is unreadable and couldn't be delivered. Check the conversation for missing replies."
     );
     try {
       rmSync7(full, { force: true });
@@ -9953,7 +10177,7 @@ var Outbox = class {
       if (now - e.enqueuedAt > MAX_AGE_MS) {
         this.log?.warn(
           { workspaceId: this.workspaceId, turnId: e.turnId, seq: e.seq, kind: e.kind },
-          "companion outbox: evicting entry past max age (undeliverable)"
+          "A saved update waited too long and couldn't be delivered. Check the conversation for missing replies."
         );
         this.remove(e.turnId, e.seq);
       } else {
@@ -9965,7 +10189,7 @@ var Outbox = class {
       for (const e of survivors.slice(0, overflow)) {
         this.log?.warn(
           { workspaceId: this.workspaceId, turnId: e.turnId, seq: e.seq, kind: e.kind },
-          "companion outbox: evicting oldest entry past max size"
+          "Too many updates are waiting; the oldest couldn't be kept. Check the connection to Cabane."
         );
         this.remove(e.turnId, e.seq);
       }
@@ -10051,11 +10275,14 @@ var SseSubscriber = class {
       try {
         await this.connect();
         backoff = 500;
-        if (!this.aborted) await sleep3(backoff);
+        if (!this.aborted) {
+          this.opts.log.warn("Lost the connection to Cabane; reconnecting");
+          await sleep3(backoff);
+        }
       } catch (err) {
         if (this.aborted) return;
         if (err instanceof ApiError && (err.status === 401 || err.status === 403)) {
-          this.opts.log.error(
+          this.opts.log.debug(
             { workspaceId: this.opts.workspaceId, status: err.status },
             "SSE auth failed \u2014 tearing down this workspace subscriber"
           );
@@ -10068,7 +10295,7 @@ var SseSubscriber = class {
             err: err instanceof Error ? err.message : String(err),
             backoff
           },
-          "SSE disconnected; reconnecting"
+          "Lost the connection to Cabane; reconnecting"
         );
         await sleep3(backoff);
         backoff = Math.min(backoff * 2, MAX_BACKOFF_MS);
@@ -10092,7 +10319,7 @@ var SseSubscriber = class {
     if (!res.body) {
       throw new Error("SSE response has no body");
     }
-    this.opts.log.info({ workspaceId: this.opts.workspaceId }, "SSE connected");
+    this.opts.log.debug({ workspaceId: this.opts.workspaceId }, "SSE connected");
     let opened = true;
     this.opts.onOpen?.();
     const parser = createParser({
@@ -10222,15 +10449,12 @@ var CompanionSupervisor = class {
   async start() {
     this.log.info(
       { protocolVersion: TURN_PROTOCOL_VERSION, version: COMPANION_VERSION },
-      "companion: starting"
+      `Companion ${COMPANION_VERSION} starting on ${this.config.deviceLabel ?? hostname2()}`
     );
     const startupHarnessRefresh = this.refreshHarnessStatuses();
     this.trackHeartbeat(startupHarnessRefresh);
     if (!this.config.deviceToken) {
-      this.log.warn("companion: not paired (no device token) \u2014 run `cabane-companion pair`");
-      process.stdout.write(
-        "companion: this device is not paired \u2014 run `cabane-companion pair`, then confirm the short code in Settings \u2192 Connectors.\n"
-      );
+      this.log.warn("This device isn't paired. Run cabane-companion start to pair it.");
       return;
     }
     this.deviceApi = new DeviceApi({
@@ -10244,6 +10468,7 @@ var CompanionSupervisor = class {
       token: this.config.deviceToken,
       log: this.log,
       lastEventId: null,
+      onOpen: () => this.log.info(`Connected to Cabane as ${this.hub.statusJson().device_label ?? hostname2()}`),
       onMessage: async (ev) => {
         if (ev.event === "assignments_changed") {
           if (this.refreshing && this.inFlightRefresh) await this.inFlightRefresh;
@@ -10251,11 +10476,13 @@ var CompanionSupervisor = class {
         }
       },
       onAuthFailure: () => {
-        this.log.error("companion: device control stream authentication failed");
+        this.log.error(
+          "Cabane no longer accepts this device. Run cabane-companion logout, then cabane-companion start to pair again."
+        );
       }
     });
-    this.deviceSub.start();
     await this.refreshAssignments();
+    this.deviceSub.start();
     const firstHeartbeat = startupHarnessRefresh.then(async () => {
       if (this.stopped) return;
       await this.sendHeartbeat();
@@ -10291,7 +10518,9 @@ var CompanionSupervisor = class {
     if (!this.deviceApi) return;
     await this.refreshHarnessStatuses();
     try {
-      const store = loadSecretStoreTolerant((m) => this.log.warn({ msg: m }, "companion: secrets"));
+      const store = loadSecretStoreTolerant(
+        (m) => this.log.warn({ err: m }, "Could not read the secrets file. Check ~/.cabane/secrets.json.")
+      );
       const connectorReports = this.connectorHealth.reports();
       const opencodeModels = this.config.opencode?.serverUrl ? await enumerateOpencodeModels(this.config.opencode.serverUrl) : null;
       const res = await this.deviceApi.heartbeat({
@@ -10338,8 +10567,8 @@ var CompanionSupervisor = class {
       void this.recoverRuns();
     } catch (err) {
       this.log.warn(
-        { err: err instanceof Error ? err.message : String(err) },
-        "companion: device heartbeat failed (will retry on next tick)"
+        { ...apiErrorLogFields(err) },
+        "Couldn't check in with Cabane; trying again shortly."
       );
     }
   }
@@ -10354,7 +10583,7 @@ var CompanionSupervisor = class {
     this.versionSkewWarned = true;
     this.log.warn(
       { companionVersion: COMPANION_VERSION, serverVersion },
-      "companion: VERSION SKEW \u2014 this companion and its server were built from different versions. Turns may misbehave. The self-host artifact ships a matching companion; run `cabane update` so the companion matches its server."
+      "This companion and Cabane are on different versions. If turns fail, update with npm i -g @cabane/companion@latest"
     );
   }
   // Pull assignments and reconcile the live runner set against them. Re-entrancy
@@ -10376,8 +10605,8 @@ var CompanionSupervisor = class {
           device = resp.device;
         } catch (err) {
           this.log.error(
-            { err: err instanceof Error ? err.message : String(err) },
-            "companion: assignments pull failed \u2014 check the device is still active in the cabane app"
+            { ...apiErrorLogFields(err) },
+            "Couldn't load the assigned agents. Check that this device is active in Cabane; trying again shortly."
           );
           this.hub.setDeviceError(err instanceof Error ? err.message : String(err));
           return;
@@ -10443,14 +10672,17 @@ var CompanionSupervisor = class {
       const credential = it.credential ?? getCredential(it.agentId);
       const runConfig = parseRunConfig(
         it.runConfig,
-        (m) => this.log.warn({ agentId: it.agentId, msg: m }, "companion: run-config")
+        (m) => this.log.warn(
+          { agentId: it.agentId, agentName: it.agentDisplayName, err: m },
+          "Some agent settings could not be read; using defaults. Check the agent settings in Cabane."
+        )
       );
       const required = requiredSecretNames(runConfig.mcpServers);
       const missing = required.filter((n) => !exposed.has(n));
       if (!credential) {
         this.log.error(
           { workspaceId, agentId: it.agentId, username: it.agentUsername },
-          "companion: agent assigned but no credential on this device \u2014 re-assign it in the cabane app"
+          `Cannot run ${it.agentDisplayName}: its sign-in to Cabane is missing. Reassign it to this device in Cabane.`
         );
         this.removeAgent(wr, it.agentId);
         this.hub.setAgent(workspaceId, {
@@ -10484,19 +10716,20 @@ var CompanionSupervisor = class {
       if (missing.length > 0) {
         this.log.warn(
           { workspaceId, agentId: it.agentId, missing },
-          "companion: agent needs secrets this device does not expose (turns using them will fail)"
+          `${it.agentDisplayName} needs secrets this machine does not have: ${missing.join(", ")}. Add them to ~/.cabane/secrets.json.`
         );
       }
     }
     this.ensureWorkspaceSse(wr);
   }
   addAgent(wr, it, credential, runConfig) {
-    const outbox = new Outbox(it.agentId, this.log);
+    const agentLog = this.log.child({ agentName: it.agentDisplayName });
+    const outbox = new Outbox(it.agentId, agentLog);
     const api = new CabaneApi({
       baseUrl: this.config.baseUrl,
       token: credential,
       outbox,
-      log: this.log
+      log: agentLog
     });
     const aborts = /* @__PURE__ */ new Map();
     const dispatcher = this.buildDispatcher({
@@ -10506,6 +10739,7 @@ var CompanionSupervisor = class {
       workspaceSlug: it.workspaceSlug,
       agentId: it.agentId,
       agentUsername: it.agentUsername,
+      agentDisplayName: it.agentDisplayName,
       credential,
       runConfig,
       aborts
@@ -10526,7 +10760,7 @@ var CompanionSupervisor = class {
     drain2.kick();
     this.log.info(
       { workspaceId: it.workspaceId, agentId: it.agentId, username: it.agentUsername },
-      "companion: running agent"
+      `Running ${it.agentDisplayName}`
     );
   }
   removeAgent(wr, agentId) {
@@ -10537,7 +10771,7 @@ var CompanionSupervisor = class {
     this.hub.removeAgent(wr.workspaceId, agentId);
     this.log.info(
       { workspaceId: wr.workspaceId, agentId },
-      "companion: stopped agent (unassigned)"
+      `Stopped running ${runner.displayName} (unassigned)`
     );
   }
   // CT1379: can this machine LAUNCH the harness — is the SDK's own bundled
@@ -10610,7 +10844,11 @@ var CompanionSupervisor = class {
       const meta = { runtime, platform: resolution.platform, arch: resolution.arch, status: status2 };
       if (status2 === "present") {
         const say = intended ? this.log.info : this.log.debug;
-        say.call(this.log, meta, "companion: bundled harness binary is present again");
+        say.call(
+          this.log,
+          meta,
+          `${runtime === "codex" ? "Codex" : "Claude Code"} is available again`
+        );
         continue;
       }
       if (intended) this.log.warn(meta, startupWarning(resolution));
@@ -10656,7 +10894,7 @@ var CompanionSupervisor = class {
       local,
       aborts: ctx.aborts,
       runConfig: ctx.runConfig,
-      log: this.log,
+      log: this.log.child({ agentName: ctx.agentDisplayName ?? ctx.agentUsername }),
       // CT833: register the claude-code adapter only when this device actually
       // offers claude-code — read per turn (not captured here), so a harness
       // installed or connected after boot works on the next turn exactly as it
@@ -10714,7 +10952,7 @@ var CompanionSupervisor = class {
       onMessage: (ev) => this.handleWorkspaceMessage(wr, ev),
       onAuthFailure: (status2) => {
         this.hub.setAuthFailed(wr.workspaceId);
-        this.log.error(
+        this.log.debug(
           { workspaceId: wr.workspaceId, status: status2, sseAgentId: wr.sseAgentId },
           "companion: workspace stream auth failed \u2014 re-pulling assignments"
         );
@@ -10723,7 +10961,7 @@ var CompanionSupervisor = class {
       }
     });
     wr.sub.start();
-    this.log.info({ workspaceId: wr.workspaceId }, "companion: subscribed");
+    this.log.debug({ workspaceId: wr.workspaceId }, "companion: subscribed");
   }
   async removeWorkspace(workspaceId) {
     const wr = this.workspaces.get(workspaceId);
@@ -10747,7 +10985,7 @@ var CompanionSupervisor = class {
     try {
       wire = JSON.parse(ev.data);
     } catch (err) {
-      this.log.warn(
+      this.log.debug(
         { err: err instanceof Error ? err.message : String(err) },
         "malformed SSE payload"
       );
@@ -10763,7 +11001,7 @@ var CompanionSupervisor = class {
       if (agent2) {
         const aborted = agent2.dispatcher.cancel(payload2.conversationId, payload2.agentId);
         if (aborted) {
-          this.log.info(
+          this.log.debug(
             {
               workspaceId: wr.workspaceId,
               conversationId: payload2.conversationId,
@@ -10817,9 +11055,9 @@ var CompanionSupervisor = class {
           workspaceId: wr.workspaceId,
           conversationId: payload.conversationId,
           agentId: payload.agentId,
-          err: err instanceof Error ? err.message : String(err)
+          ...apiErrorLogFields(err)
         },
-        "companion: conversation turn handler threw"
+        "The turn stopped unexpectedly. Reply in Cabane to try again."
       );
     });
     wr.chains.set(chainKey, tail);
@@ -10852,7 +11090,7 @@ var CompanionSupervisor = class {
           messageId: payload.messageId,
           reason: "agent_not_on_device"
         });
-        this.log.warn(
+        this.log.debug(
           {
             workspaceId: wr.workspaceId,
             conversationId: payload.conversationId,
@@ -10873,7 +11111,7 @@ var CompanionSupervisor = class {
         agentId: payload.agentId,
         err: lastErr instanceof Error ? lastErr.message : String(lastErr)
       },
-      "companion: could not report an unrunnable dispatch \u2014 leaving it unsettled so a reconnect replays it"
+      "Couldn't tell Cabane that this agent no longer runs here; trying again when the connection returns."
     );
     return false;
   }
@@ -10928,7 +11166,7 @@ var CompanionSupervisor = class {
           agent,
           run.turnId
         ).catch(
-          (err) => this.log.warn({ err, turnId: run.turnId }, "companion: restart recovery failed")
+          (err) => this.log.debug({ err, turnId: run.turnId }, "companion: restart recovery failed")
         ).finally(() => {
           if (wr.chains.get(key) === tail) wr.chains.delete(key);
         });
@@ -10939,7 +11177,7 @@ var CompanionSupervisor = class {
         this.recoveryChecked = page.nextCursor === null;
       }
     } catch (err) {
-      this.log.warn({ err }, "companion: run recovery read failed (will retry)");
+      this.log.debug({ err }, "companion: run recovery read failed (will retry)");
     } finally {
       this.recovering = false;
     }
@@ -10951,7 +11189,7 @@ var CompanionSupervisor = class {
     const workspaceId = wr.workspaceId;
     if (ev.id && hasDispatched(workspaceId, ev.id)) {
       if (hasCompleted(workspaceId, ev.id)) {
-        this.log.info(
+        this.log.debug(
           { workspaceId, eventId: ev.id },
           "companion: skipping already-completed event (resume after restart)"
         );
@@ -10959,7 +11197,7 @@ var CompanionSupervisor = class {
         return;
       }
       if (noResume()) {
-        this.log.warn(
+        this.log.debug(
           { workspaceId, eventId: ev.id },
           "companion: skipping interrupted turn (CABANE_COMPANION_NO_RESUME=1) \u2014 resume disabled for this boot"
         );
@@ -10971,13 +11209,13 @@ var CompanionSupervisor = class {
       if (attempt > MAX_RESUME_ATTEMPTS) {
         this.log.error(
           { workspaceId, eventId: ev.id, attempt, cap: MAX_RESUME_ATTEMPTS },
-          "companion: giving up on an interrupted turn after too many resume attempts \u2014 retiring it so boot is never wedged (run `cabane companion reset` to clear resume state)"
+          "An interrupted turn couldn't finish after several attempts. Reply in Cabane to try again."
         );
         markCompleted(workspaceId, ev.id);
         wr.cursor.settle(ev.id);
         return;
       }
-      this.log.info(
+      this.log.debug(
         { workspaceId, eventId: ev.id, attempt, cap: MAX_RESUME_ATTEMPTS },
         "companion: re-dispatching interrupted turn (resume after restart)"
       );
@@ -10987,7 +11225,7 @@ var CompanionSupervisor = class {
     if (ev.id) {
       const liveTurnIds = rememberTurnId(workspaceId, ev.id, turnId);
       if (liveTurnIds > TURN_ID_OVERFLOW_WARN) {
-        this.log.error(
+        this.log.debug(
           { workspaceId, liveTurnIds, threshold: TURN_ID_OVERFLOW_WARN },
           "companion: in-flight turn-id map is implausibly large \u2014 completion pruning is likely broken. Keeping every mapping; dropping one would silently lose a resumable turn."
         );
@@ -10995,11 +11233,18 @@ var CompanionSupervisor = class {
       markDispatched(workspaceId, ev.id);
     }
     if (resumedTurnId) {
-      this.log.info(
+      this.log.debug(
         { workspaceId, eventId: ev.id, turnId },
         "companion: resuming an interrupted turn under its original id"
       );
     }
+    const turnBindings = {
+      agentName: agent.displayName,
+      conversationId: payload.conversationId,
+      agentId: agent.agentId,
+      workspaceId
+    };
+    this.log.info(turnBindings, "Turn started");
     const result = await agent.dispatcher.handle(payload, {
       turnId,
       resumed: resumedTurnId !== null
@@ -11008,16 +11253,23 @@ var CompanionSupervisor = class {
     if (ev.id) wr.cursor.settle(ev.id);
     const durationS = (result.durationMs / 1e3).toFixed(1);
     const bindings = {
-      workspaceId,
-      conversationId: payload.conversationId,
-      agentId: agent.agentId
+      ...turnBindings,
+      ...result.transcriptPath ? { transcriptPath: result.transcriptPath } : {}
     };
     if (result.ok) {
-      this.log.info(bindings, `${wr.slug}/${agent.username} \u2014 replied (${durationS}s)`);
+      this.log.info(bindings, `Replied (${durationS}s)`);
+    } else if (result.reason === "cancelled") {
+      this.log.info(turnBindings, `Turn stopped (${durationS}s)`);
+    } else if ([
+      "turn_context_not_found",
+      "turn_context_not_admitted",
+      "trigger_role_not_dispatchable"
+    ].includes(result.reason ?? "") || result.reason === "lease_refused: dispatch_not_admitted" || result.reason === "lease_refused: turn_already_ended") {
+      this.log.debug({ ...turnBindings, reason: result.reason }, "Dispatch no longer needed");
     } else {
-      this.log.warn(
+      this.log.info(
         bindings,
-        `${wr.slug}/${agent.username} \u2014 dispatch failed: ${result.reason ?? "unknown"} (${durationS}s)`
+        `Turn failed after ${durationS}s: ${turnFailureCopy(result.reason, result.runtime)}`
       );
     }
   }
@@ -11037,7 +11289,7 @@ var CompanionSupervisor = class {
         }
       } catch (err) {
         drainDelay = Math.min(drainDelay * 2, DRAIN_MAX_MS);
-        this.log.warn(
+        this.log.debug(
           { agentId, err: err instanceof Error ? err.message : String(err) },
           "companion: outbox drain pass threw (will retry with backoff)"
         );
@@ -11072,7 +11324,7 @@ var CompanionSupervisor = class {
     const next = loadConfig();
     if (!next) return;
     this.config = next;
-    this.log.level = next.logLevel ?? "debug";
+    configureLogger(this.log, next);
     this.rebuildDispatchers();
     void this.refreshAssignments();
   }
@@ -11088,7 +11340,7 @@ var CompanionSupervisor = class {
     };
     this.config = next;
     saveConfig(next);
-    this.log.level = next.logLevel ?? "debug";
+    configureLogger(this.log, next);
   }
   // ---- harnesses (CT586) ----
   // Probe all three harnesses, cache the signals + versions, and push the derived
@@ -11114,7 +11366,7 @@ var CompanionSupervisor = class {
       };
       this.hub.setHarnesses(deriveHarnessSnapshot(signals).harnesses);
     } catch (err) {
-      this.log.warn(
+      this.log.debug(
         { err: err instanceof Error ? err.message : String(err) },
         "companion: harness probe failed (will retry on next beat)"
       );
@@ -11230,6 +11482,7 @@ var CompanionSupervisor = class {
           workspaceSlug: wr.slug,
           agentId: runner.agentId,
           agentUsername: runner.username,
+          agentDisplayName: runner.displayName,
           credential: runner.credential,
           runConfig: runner.runConfig,
           aborts: runner.aborts
@@ -11335,7 +11588,7 @@ function handleUncaught(log, err, origin) {
   const message = err instanceof Error ? err.message : String(err);
   const code = errorCode(err);
   if (isRecoverableSocketError(err)) {
-    log.warn(
+    log.debug(
       { origin, code, err: message },
       "companion: recovered from a socket error (kept running \u2014 a broken pipe never kills the companion)"
     );
@@ -11343,7 +11596,7 @@ function handleUncaught(log, err, origin) {
   }
   log.error(
     { origin, code, err: message, stack: err instanceof Error ? err.stack : void 0 },
-    "companion: uncaught error (kept running \u2014 see the stack above)"
+    "An unexpected error occurred; the companion is still running."
   );
 }
 
@@ -11377,7 +11630,7 @@ async function createCompanionRuntime(opts = {}) {
   try {
     ({ cfg, claudeOnPath: claudeCode } = await requireStartConfig({
       ...opts.probeClaude ? { probeClaude: opts.probeClaude } : {},
-      onMigrated: (migrated, onPath) => log.info(
+      onMigrated: (migrated, onPath) => log.debug(
         { claudeCode: isClaudeCodeConnected(migrated) },
         onPath ? "companion: carried Claude Code over as a connected harness on this device (connectors are now chosen, not detected)" : "companion: no Claude Code on PATH, so this device starts with it disconnected (connectors are now chosen, not detected)"
       )
@@ -11398,7 +11651,7 @@ async function createCompanionRuntime(opts = {}) {
     });
     throw err;
   }
-  if (cfg.logLevel) log.level = cfg.logLevel;
+  configureLogger(log, cfg);
   const harnessVersions = await probeHarnessVersions({
     // Connected AND its CLI answered — the two things that make a
     // `claude --version` probe worth spawning. Not the offer predicate.
@@ -11598,7 +11851,12 @@ Connect a harness to the running companion: cabane-companion connect claude-code
     }
     clearRuntimeState();
   }
-  const args = ["start", "--foreground"];
+  const args = [
+    "start",
+    "--foreground",
+    ...opts.logLevel ? ["--log-level", opts.logLevel] : [],
+    ...opts.logFormat ? ["--log-format", opts.logFormat] : []
+  ];
   const launchDetached = () => {
     const spawned = spawnDetached(args);
     spawned.unref();
@@ -11628,7 +11886,7 @@ Check ${companionLogPath()} for errors, or run \`cabane-companion status\`.
   if (quiet) return { started: true, state };
   process.stdout.write(
     `Cabane Companion started in the background (pid ${state.pid}).
-Logs:    ${companionLogPath()}
+Logs:    cabane-companion logs   (${companionLogPath()})
 Status:  cabane-companion status
 Stop:    cabane-companion stop
 `
@@ -11654,11 +11912,11 @@ function defaultSpawnDetached(args) {
 var FORCE_EXIT_MS = 4e3;
 var MAX_CODES = 3;
 async function start(opts = {}) {
+  setLogOverrides(opts);
   const interactive = isInteractive();
-  if (!interactive) return startScript(opts, false);
   setConsoleLogging(false);
   try {
-    await startScript(opts, true);
+    await startScript(opts, interactive);
   } finally {
     setConsoleLogging(true);
   }
@@ -11669,7 +11927,10 @@ async function startScript(opts, interactive) {
     reportAlreadyRunning(running.pid);
     return;
   }
-  blank();
+  const daemon = process.env.CABANE_COMPANION_DAEMON === "1";
+  if (daemon)
+    write(`Running in the background (pid ${process.pid}). Stop with cabane-companion stop.`);
+  else blank();
   const held = !isDevicePaired() ? await collectHarnessChoices(interactive) : [];
   let paired = null;
   if (!isDevicePaired()) {
@@ -11678,14 +11939,19 @@ async function startScript(opts, interactive) {
       return;
     }
     const { note } = writePairedConfig(paired);
-    if (note) getLogger().warn({ note }, "companion: salvaged an older config on pairing");
+    getLogger().info(`Paired with Cabane as ${paired.deviceLabel}`);
+    if (note)
+      getLogger().warn(
+        { note },
+        "An older configuration was repaired during pairing. Check ~/.cabane/config.json."
+      );
   }
   const justPaired = paired !== null;
   const log = getLogger();
   const result = await createCompanionRuntime({
     // The script says what's connectable in its own words below; a stderr warning
     // in the middle of it would be the same news, worse.
-    onReadinessWarning: (message) => log.info({ msg: message }, "companion: harness readiness")
+    onReadinessWarning: (message) => log.warn(message)
   });
   if (!result.ok) {
     reportAlreadyRunning(result.existing?.pid);
@@ -11703,24 +11969,28 @@ async function startScript(opts, interactive) {
   if (interactive && !opts.foreground) {
     await handOffToBackground(runtime, {
       justPaired,
-      connected
+      connected,
+      ...opts
     });
     return;
   }
   if (interactive) {
     blank();
     write(INDENT + tick("Cabane companion is running in this terminal."));
-    write(`    Stop:  Ctrl-C                       Logs:  ${tildePath(companionLogPath())}`);
+    write(
+      `    Stop:  Ctrl-C                       Logs:  cabane-companion logs   (${tildePath(companionLogPath())})`
+    );
     blank();
     write(`${INDENT}Listening for messages\u2026`);
     setConsoleLogging(true);
-  } else {
+  } else if (!daemon) {
     blank();
     write(
       `${INDENT}Cabane companion is running. No terminal attached, so it stays in the foreground.`
     );
     write(`${INDENT}Listening for messages\u2026`);
   }
+  setConsoleLogging(true);
   await runAttached(runtime);
 }
 async function liveCompanion() {
@@ -11796,7 +12066,7 @@ function prePairFoundPhrase(harness) {
 }
 async function pairHere(opts, interactive) {
   const baseUrl = resolvePairBaseUrl(opts.server);
-  const label = deviceLabelFromHostname(hostname2());
+  const label = deviceLabelFromHostname(hostname3());
   const aborter = new AbortController();
   const onSigint = () => aborter.abort();
   process.on("SIGINT", onSigint);
@@ -11866,7 +12136,7 @@ function connectCommand(runtime) {
 }
 async function handOffToBackground(runtime, ctx) {
   await runtime.stop();
-  const outcome = await startDaemon({ report: "failures" });
+  const outcome = await startDaemon({ report: "failures", ...ctx });
   if (!outcome.started) {
     return;
   }
@@ -11879,7 +12149,9 @@ async function handOffToBackground(runtime, ctx) {
     }
   }
   write(INDENT + tick("Cabane companion is running in the background."));
-  write(`    Stop:  cabane-companion stop        Logs:  ${tildePath(companionLogPath())}`);
+  write(
+    `    Stop:  cabane-companion stop        Logs:  cabane-companion logs   (${tildePath(companionLogPath())})`
+  );
   if (ctx.justPaired) {
     blank();
     write(`${INDENT}! It won't restart on its own \u2014 after a reboot, or if it ever stops,`);
@@ -11891,20 +12163,15 @@ async function handOffToBackground(runtime, ctx) {
 async function runAttached(runtime) {
   await new Promise((resolve2) => {
     let shuttingDown = false;
-    const shutdown = async (signal) => {
+    const shutdown = async () => {
       if (shuttingDown) {
-        process.stdout.write(`
-companion: second ${signal}, force-quitting.
-`);
+        getLogger().error("Stopped: forced to quit after a second stop request.");
         process.exit(1);
       }
       shuttingDown = true;
-      process.stdout.write(`
-companion: received ${signal}, shutting down\u2026
-`);
+      getLogger().info("Stopping the companion");
       const forceExit = setTimeout(() => {
-        process.stdout.write(`companion: shutdown timed out, force-quitting.
-`);
+        getLogger().error("Stopped: shutdown took too long.");
         process.exit(1);
       }, FORCE_EXIT_MS);
       forceExit.unref?.();
@@ -11913,8 +12180,8 @@ companion: received ${signal}, shutting down\u2026
       resolve2();
       process.exit(0);
     };
-    process.on("SIGINT", () => void shutdown("SIGINT"));
-    process.on("SIGTERM", () => void shutdown("SIGTERM"));
+    process.on("SIGINT", () => void shutdown());
+    process.on("SIGTERM", () => void shutdown());
   });
 }
 
@@ -11933,7 +12200,7 @@ async function status() {
 `);
   if (cfg.deviceLabel) process.stdout.write(`device:       ${cfg.deviceLabel}
 `);
-  process.stdout.write(`log file:     ${companionLogPath()}
+  process.stdout.write(`log file:     cabane-companion logs   (${companionLogPath()})
 `);
   process.stdout.write(`transcripts:  ${transcriptsLine()}
 `);
@@ -11968,9 +12235,9 @@ async function status() {
     process.stdout.write(`prepare hook: ${cfg.prepareHook.command} (device-level, all agents)
 `);
   }
-  const overrides = Object.keys(cfg.agents ?? {});
-  if (overrides.length > 0) {
-    process.stdout.write(`local overrides for: ${overrides.join(", ")}
+  const overrides2 = Object.keys(cfg.agents ?? {});
+  if (overrides2.length > 0) {
+    process.stdout.write(`local overrides for: ${overrides2.join(", ")}
 `);
   }
 }
@@ -12416,8 +12683,21 @@ program.command("write-paired-config", { hidden: true }).description("persist an
 });
 program.command("start").description(
   "pair this device if needed, connect a coding agent on it, and run in the background."
-).option("--foreground", "run attached in this terminal (for terminals and supervisors)").option("--daemon", "run in the background (the default; kept for compatibility)").option("--server <url>", "the cabane instance to pair with, if this device isn\u2019t paired yet").addOption(new Option("--open").hideHelp()).addOption(new Option("--no-open").hideHelp()).addOption(new Option("--port <port>").hideHelp()).action(async (opts) => {
+).option("--foreground", "run attached in this terminal (for terminals and supervisors)").option("--daemon", "run in the background (the default; kept for compatibility)").option("--server <url>", "the cabane instance to pair with, if this device isn\u2019t paired yet").addOption(
+  new Option("--log-level <level>", "info (default), warn, or debug").choices([
+    "info",
+    "warn",
+    "debug"
+  ])
+).addOption(
+  new Option("--log-format <format>", "human (default) or json, for the log file").choices([
+    "human",
+    "json"
+  ])
+).addOption(new Option("--open").hideHelp()).addOption(new Option("--no-open").hideHelp()).addOption(new Option("--port <port>").hideHelp()).action(async (opts) => {
   await start({
+    ...opts.logLevel ? { logLevel: opts.logLevel } : {},
+    ...opts.logFormat ? { logFormat: opts.logFormat } : {},
     ...opts.foreground ? { foreground: true } : {},
     ...opts.server !== void 0 ? { server: opts.server } : {}
   });
@@ -12431,6 +12711,13 @@ program.command("stop").description("stop a running companion (SIGTERM, then for
 program.command("status").description("print the companion's local state (pairing, secrets, log path).").action(async () => {
   await status();
 });
+program.command("logs").description("show the companion log (last 50 lines; up to 1 MiB)").option("-n, --lines <N>", "number of recent lines", (value) => {
+  if (!/^\d+$/.test(value) || !Number.isSafeInteger(Number(value)))
+    throw new InvalidArgumentError("N must be a non-negative integer.");
+  return Number(value);
+}).option("-f, --follow", "follow new log lines (Ctrl-C to stop)").action(async (opts) => {
+  await logs(opts);
+});
 program.command("transcript").description("show the full agent transcript for a recent dispatch (the agent's whole turn).").argument("[file]", "a transcript filename or substring; omit to list recent transcripts").option("--last", "render the most recent transcript").option("-f, --follow", "watch for new turns and live-render them as they land (Ctrl-C to stop)").action(async (file, opts) => {
   await transcript({
     ...file !== void 0 ? { target: file } : {},
@@ -12463,7 +12750,7 @@ program.parseAsync(process.argv).catch((err) => {
   }
   setConsoleLogging(false);
   try {
-    getLogger().error({ err }, "companion: command failed");
+    getLogger().error({ err }, `Stopped: ${err instanceof Error ? err.message : String(err)}`);
   } catch {
   }
   process.stderr.write(`${err instanceof Error ? err.message : String(err)}