@cabane/companion 0.6.144 → 0.6.146

package/dist/pairing-config.js

@@ -64,18 +64,15 @@ var prepareHookSchema = z.object({
   // default is generous; a hook that hangs past this is killed and the turn
   // fails with a clear timeout message rather than pinning the companion.
   timeoutMs: z.number().int().positive().optional(),
-  // CT943: re-invoke the hook on turns where a prepared result already exists,
-  // in VALIDATE mode — the cached result is handed back as `prepared` and the
-  // hook's stdout is ignored, so the cwd provably cannot move. Its only power
-  // is to exit non-zero and fail the turn.
+  // Re-invoke the hook when a prepared result already exists, in VALIDATE
+  // mode: the cached result is handed back as `prepared` and stdout is
+  // ignored, so the cwd cannot move. Its only power is to exit non-zero and
+  // fail the turn. The hook resolves once per (conversation, agent), so a
+  // later message asking for a different environment is otherwise silently
+  // ignored; this lets a hook refuse it out loud.
   //
-  // Why it exists: the hook runs exactly once per (conversation, agent), so a
-  // later message asking for a different environment can't be honoured. Without
-  // this, it is silently ignored — the host knows and says nothing, which is
-  // the worst available outcome. An opt-in hook can now refuse it out loud.
-  //
-  // Default OFF, and deliberately: an operator hook that provisions
-  // unconditionally must not start running on every turn because it upgraded.
+  // Default OFF: a hook that provisions unconditionally must not start
+  // running on every turn because the companion upgraded.
   validateCached: z.boolean().optional(),
   // Independent operator-owned reporter. Receives sanitized failure metadata
   // on stdin; never re-enters this hook and cannot change the turn outcome.
@@ -122,18 +119,17 @@ function configPath() {
 var localAgentConfigSchema = z2.object({
   cwd: z2.string().optional(),
   prepareHook: prepareHookSchema.optional(),
-  // CT289: the Claude Code auto-memory escape hatch. Auto-memory is forced OFF
-  // by default on every companion (memory belongs in the Cabane workspace, and a
-  // shared companion would otherwise pool one cwd-keyed memory dir across users).
-  // On a companion you run yourself, set `claudeCode: { autoMemory: true }` to hand
-  // auto-memory back to your own `~/.claude/settings.json` — Cabane then stops
+  // The Claude Code auto-memory escape hatch. Auto-memory is forced OFF by
+  // default (memory belongs in the Cabane workspace, and a shared companion
+  // would pool one cwd-keyed memory dir across users). On a companion you run
+  // yourself, `claudeCode: { autoMemory: true }` hands auto-memory back to your
+  // own `~/.claude/settings.json` — Cabane then stops
   // injecting the off switch and your normal Claude Code memory workflow applies
   // (in coding mode, where the checkout's project settings are read).
   claudeCode: z2.object({ autoMemory: z2.boolean().optional() }).strict().optional(),
-  // CT1693: this agent's exception to `runners.sandbox` — an ops agent that
-  // runs with the machine on a sandboxed device, or one sandboxed agent on a
-  // device that isn't. Absent is "inherit"; see `runnerSandboxFor`. Only on a
-  // row keyed by the agent's id (`agentsConfigSchema`).
+  // This agent's exception to `runners.sandbox`: an ops agent that runs with
+  // the machine on a sandboxed device, or one sandboxed agent on a device that
+  // isn't. Absent is "inherit". Only on a row keyed by the agent's id.
   sandbox: z2.enum(["os", "none"]).optional()
 }).strict();
 var AGENT_ID_KEY = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
@@ -149,9 +145,8 @@ var agentsConfigSchema = z2.record(z2.string(), localAgentConfigSchema).superRef
   }
 });
 var companionConfigSchema = z2.object({
-  // The cabane instance this device is paired with. SJ515: https-enforced
-  // (loopback exempt) so a hand-edited config can't smuggle a plaintext-http
-  // base URL onto the MITM-able channel the device token + prompt ride.
+  // https-enforced (loopback exempt), so a hand-edited config can't put the
+  // device token and prompt on a plaintext channel.
   baseUrl: z2.string().url().refine(isAllowedBaseUrl, {
     message: "baseUrl must be https (loopback http is allowed for local dev only)"
   }),
@@ -169,91 +164,59 @@ var companionConfigSchema = z2.object({
   // agentId / username / `slug/username`. Hand-added by the operator; the companion
   // never writes this (it only persists credentials + the device, elsewhere).
   agents: agentsConfigSchema.optional(),
-  // CT1095: the DEVICE-LEVEL prepare hook — one entry that applies to every agent
-  // assigned to this device, unless that agent's own `agents` row names a hook of
-  // its own.
-  //
-  // Until now `prepareHook` existed only under `agents[<id>]`, which made the
-  // config a second silent roster: a device whose provisioning is genuinely
-  // per-device (ours resolves a directory from the conversation and agent ids the
-  // companion already hands the hook) still had to list every agent by id, and an
-  // agent nobody remembered to add got no hook at all — no error, no log, just a
-  // turn that started in the operator's `$HOME`. That is how @dale woke in
-  // `/home/joshed` on 2026-08-17 with a perfectly correct dispatch.
-  //
-  // Absent → nothing changes for anyone, which is why this can land inert: a
-  // device with no device-level entry behaves exactly as it did before. A hook
-  // that fails still fails the dispatch loudly, as now.
+  // The DEVICE-LEVEL prepare hook, for every agent assigned here unless its own
+  // `agents` row names one. Per-agent hooks alone make the config a second
+  // silent roster: an agent nobody listed gets no hook and no error, and starts
+  // in the operator's `$HOME` (an agent woke in `/home/joshed` this way on
+  // 2026-08-17).
   prepareHook: prepareHookSchema.optional(),
-  // CT1085 §9: `dashboardPort` and `autoOpen` are READ AND IGNORED by the CLI —
-  // it binds no port and opens no browser. They stay in the schema (rather than
-  // becoming a strict-mode parse error on an existing config file) and still mean
-  // what they say to the Electron shell, the one front-end that renders a
-  // dashboard. `logLevel` is unaffected: pino level, live-editable.
+  // `dashboardPort` and `autoOpen` are IGNORED by the CLI (no port, no browser)
+  // but stay in the schema so an existing file still parses; the Electron shell
+  // reads them. `logLevel` is pino's level, live-editable.
   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
-  // here. Setting this makes the device advertise the `opencode` runtime on its
-  // heartbeat manifest (so the server offers DeepSeek/opencode models here and
-  // routes those turns to this device) AND registers the opencode adapter in the
-  // dispatcher. Absent → the device is claude-code-only, exactly as before.
+  // An `opencode serve` the operator runs here (auth via opencode's own
+  // `/connect`; Cabane never sees provider keys). Set, the device advertises the
+  // `opencode` runtime and registers its adapter.
   opencode: z2.object({
     serverUrl: z2.string().url()
   }).strict().optional(),
-  // CT1082: the Claude Code runtime, when the user connected it on this machine.
-  // The change this task exists for: Claude Code used to be the one harness a
-  // device exposed with no configuration — a `claude --version` exit-0 was taken as
-  // consent — and it is now the third config-driven harness, opted into exactly
-  // like codex. CT1379: the binary that must be there is the Agent SDK's own
-  // bundled executable — the file a turn actually launches — not the user's
-  // `claude` on PATH, which the SDK never runs. The manifest advertises
-  // claude-code only when this block says so AND that binary resolves.
+  // Whether the user connected Claude Code on this machine: consent, opted into
+  // like codex. The manifest advertises claude-code only when this says so AND
+  // the Agent SDK's bundled executable resolves (not `claude` on PATH, which the
+  // SDK never runs).
   //
-  // The block's PRESENCE is also the migration marker (see `migrateConnectedHarnesses`).
-  // Absent means the config predates this task — a device whose user was never
-  // asked — and the migration grandfathers it on first start. So every config
-  // written from here on carries the block explicitly, including a freshly-paired
-  // one, which starts at `enabled: false`: a new device is connected to nothing
-  // until its user says otherwise.
+  // The block's PRESENCE is also the migration marker
+  // (`migrateConnectedHarnesses`): absent means a config whose user was never
+  // asked. So every config written carries it, a fresh pair at `enabled: false`.
   //
-  // Not to be confused with the per-agent `agents.<key>.claudeCode.autoMemory`
-  // above — that's one agent's memory switch, this is the device's connected set.
+  // Not the per-agent `agents.<key>.claudeCode.autoMemory`, one agent's memory
+  // switch.
   claudeCode: z2.object({
     enabled: z2.boolean().optional()
   }).strict().optional(),
-  // CT481: the codex runtime, when the operator runs Codex on this machine. Unlike
-  // opencode (a long-lived `opencode serve` addressed by URL), Codex is a local CLI
-  // the `@openai/codex-sdk` spawns per turn — so the config is just an opt-in flag,
-  // not a server address. The operator installs Codex + logs in (`codex login`, or
-  // `CODEX_API_KEY` — Cabane never sees the key) and sets `{ "codex": { "enabled":
-  // true } }`. Presence of the block enables it (an explicit `enabled: false`
-  // keeps the block but turns it off). Absent → the device doesn't offer codex.
-  // CT1379: enabling is now half the answer, not all of it — the manifest and the
-  // adapter registry additionally require the SDK's vendored `codex` binary to
-  // resolve, because the enable flag alone advertised a runtime a device with a
-  // half-installed platform package could not start.
+  // Codex is a local CLI the SDK spawns per turn, so this is an opt-in flag, not
+  // an address. The operator logs in (`codex login` or `CODEX_API_KEY`; Cabane
+  // never sees the key). The block's presence enables it; `enabled: false` turns
+  // it off. Half the answer: advertising also requires the SDK's vendored
+  // `codex` binary to resolve.
   codex: z2.object({
     enabled: z2.boolean().optional()
   }).strict().optional(),
-  // CT1679: run each turn in a child runner process instead of in this one.
-  // Absent, or `enabled: false`, is the in-process path, untouched. `sandbox`
-  // wraps the runner in an OS sandbox where the host supports one; `'none'`
-  // (the default) runs it as a plain child beside this process, a supported
-  // configuration in its own right rather than a degraded one.
-  // CT1684: `policy` is what the OS sandbox lets a turn reach, read and hold
-  // (`runner/sandbox-policy.ts`). It is validated there rather than here, so a
-  // bad policy refuses the turns it governs, with the field named, instead of
-  // keeping the companion from starting at all.
+  // Run each turn in a child runner process. Absent or `enabled: false` is the
+  // in-process path. `sandbox: 'os'` wraps the runner in an OS sandbox where the
+  // host supports one; `'none'` (the default) is a plain child, supported in its
+  // own right. `policy` is what the sandbox lets a turn reach, read and hold,
+  // validated in `runner/sandbox-policy.ts` so a bad policy refuses the turns it
+  // governs, field named, instead of stopping the companion starting.
   runners: z2.object({
     enabled: z2.boolean().optional(),
     provider: z2.enum(["local-process", "docker"]).optional(),
     sandbox: z2.enum(["os", "none"]).optional(),
-    // CT1681: the `docker` provider — a container per conversation and agent,
-    // from one image, on a network whose only way out is an allow-listed proxy.
+    // A container per conversation and agent, from one image, on a network
+    // whose only way out is an allow-listed proxy.
     docker: z2.object({
       // The base image a container runs. Default: the one this companion
       // builds from its own Dockerfile on first use. One named here must
@@ -526,13 +489,11 @@ function resolvePairBaseUrl(server) {
 function writePairedConfig(paired) {
   const { local, note, hadPriorConfig } = loadConfigTolerant();
   const config = {
-    // CT1082: a device pairs connected to NOTHING — `claudeCode: { enabled: false }`
-    // written explicitly, not left absent, because absence is exactly what marks a
-    // pre-CT1082 config for the grandfathering migration. Omit it and a brand-new
-    // device gets auto-connected on its first start by the behaviour this task
-    // removes; stamp it on a RE-pair and an upgrading user's working device gets
-    // disconnected instead. So it's written only when there was no config here
-    // before. `local` spreads after, so a re-pair keeps the answer already given.
+    // A device pairs connected to NOTHING: `claudeCode: { enabled: false }`
+    // written explicitly, since absence is what the harness migration reads.
+    // Omitted, a new device is auto-connected on first start; stamped on a
+    // RE-pair, an upgrading user's working device is disconnected. So only when
+    // there was no config before; `local` spreads after, keeping a prior answer.
     ...hadPriorConfig ? {} : { claudeCode: { enabled: false } },
     ...local,
     baseUrl: paired.baseUrl,