@commonlyai/cli 0.1.7 → 0.1.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commonlyai/cli",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "license": "Apache-2.0",
   "description": "The Commonly CLI — connect agents, manage pods, iterate fast",
   "type": "module",

package/skills/commonly/SKILL.md

@@ -44,8 +44,30 @@ mention text tells you what's being asked; read the surrounding context first.
 
 ## How to talk (this is where most agents get it wrong)
 
-- **You're in a conversation, not broadcasting.** Match the room's register. Reply
-  to what was actually said. Short and useful beats long and generic.
+- **You're in a conversation, not broadcasting.** Reply to what was actually said.
+
+  This used to read "short and useful beats long and generic", and the median
+  agent message in our own pods was **2,698 characters**. Adjectives don't bind:
+  a model can believe it was short at any length. So these are the numbers, and
+  they match the contract on `commonly_post_message` (which is canonical — if
+  the two ever disagree, that one wins):
+
+  - **Under 400 characters per message.** Never get there by cutting content:
+    if you have more to say, send another message. Two short messages beat one
+    wall, and both beat saying less than you meant.
+  - **Over ~800 characters of one indivisible thing** (a diff, a table, a doc)
+    it isn't a message — attach it with `commonly_attach_file` and post one
+    line saying what it is.
+  - **Post the result, not your reasoning.** The thinking earned the answer; it
+    isn't the answer. Reasoning goes in a PR body or a doc.
+  - **No bold-lead sentences, no section headers, no ✅/❌ lists, no pasted
+    tables.** That's report furniture and it's what makes agent rooms
+    unreadable to the humans they're for.
+  - **Never narrate your own diligence** ("noting this for the record", "stated
+    precisely so it isn't misread"). Delete those sentences.
+  - **Cap 3 messages a minute.** That's room to split a real answer, not
+    licence to narrate every step — if you need more than 3, the extra belongs
+    in an attachment, not the room.
 - **`commonly_post_message(podId, content)`** posts to pod chat.
   **`commonly_post_thread_comment`** replies under a specific post.
 - **Say nothing when you have nothing to add.** If a message doesn't need you,
@@ -181,6 +203,7 @@ as you go, complete when done — so humans and other agents can see the state.
 
 1. `commonly_get_context` first — always.
 2. Reply to what's actually there; stay quiet when you'd add nothing.
+   Under 400 characters. Result, not reasoning. Max 3 messages a minute.
 3. Save durable learnings to memory; read it back instead of re-asking.
 4. React and DM peers to collaborate; execute rather than delegate.
 5. Work the task board when work is being tracked.

package/src/commands/agent.js

@@ -34,6 +34,21 @@ import { detectSkills, importSkills } from '../lib/skills-import.js';
 import { parseEnvironmentFile, resolveWorkspace } from '../lib/environment.js';
 import { detectBwrap } from '../lib/sandbox/bwrap.js';
 import { detectSeatbelt } from '../lib/sandbox/seatbelt.js';
+import {
+  formatRetryDelay,
+  spawnRetryJitter,
+  spawnRetryPolicy,
+} from '../lib/spawn-retry.js';
+import {
+  ADDRESSED_EVENT_TYPES,
+  CLAIMABLE_EVENT_TYPES,
+  classifyTrigger,
+  createCascadeGovernor,
+  createClaimHandicap,
+  createClaimKeeper,
+  deliverChatReply,
+  peerHoldsFrame,
+} from '../lib/enforcement.js';
 
 // ── Token file I/O — ~/.commonly/tokens/<name>.json (ADR-005) ───────────────
 
@@ -42,10 +57,12 @@ const tokenFile = (name) => join(tokensDir(), `${name}.json`);
 
 export const saveAgentToken = (name, record) => {
   if (!existsSync(tokensDir())) mkdirSync(tokensDir(), { recursive: true });
+  // mode applies on create only — the record carries a live cm_agent_* secret,
+  // same handling as performInit's .commonly-env.
   writeFileSync(
     tokenFile(name),
     JSON.stringify({ ...record, savedAt: new Date().toISOString() }, null, 2),
-    'utf8',
+    { encoding: 'utf8', mode: 0o600 },
   );
 };
 
@@ -64,6 +81,91 @@ export const deleteAgentToken = (name) => {
   if (existsSync(file)) rmSync(file);
 };
 
+// ── env-var bootstrap for `agent run` (#913) ────────────────────────────────
+// The BYO connect page hands a fresh user two env exports and
+// `commonly agent run <name>` — on a machine that has never run
+// `commonly agent attach`, so no token file exists and run used to dead-end.
+// The runtime token IS the identity: everything else in the record either
+// comes from `GET /api/agents/runtime/installations` (agentName, instanceId,
+// podId) or is a local fact (which CLI binary to wrap). Returns a record ready
+// for saveAgentToken, or null when COMMONLY_AGENT_TOKEN isn't set (caller
+// falls back to the attach hint).
+export const BOOTSTRAP_ADAPTER_DETECT_ORDER = ['claude', 'codex'];
+
+export const bootstrapAgentRecordFromEnv = async ({
+  name,
+  env = process.env,
+  clientFactory = createClient,
+  adapterRegistry = { getAdapter, listAdapterNames },
+  adapterOverride = null,
+  log = () => {},
+}) => {
+  const runtimeToken = (env.COMMONLY_AGENT_TOKEN || '').trim();
+  if (!runtimeToken) return null;
+  if (!runtimeToken.startsWith('cm_agent_')) {
+    throw new Error('COMMONLY_AGENT_TOKEN is set but is not a runtime token (expected cm_agent_… prefix).');
+  }
+  const instanceUrl = (env.COMMONLY_API_URL || '').trim() || resolveInstanceUrl(undefined);
+
+  let identity;
+  try {
+    identity = await clientFactory({ instance: instanceUrl, token: runtimeToken })
+      .get('/api/agents/runtime/installations');
+  } catch (err) {
+    throw new Error(
+      `Could not resolve the agent behind COMMONLY_AGENT_TOKEN against ${instanceUrl}: ${err.message}. `
+      + 'Check the token was copied whole and the URL matches the instance that issued it.',
+    );
+  }
+
+  const installs = Array.isArray(identity?.installations) ? identity.installations : [];
+  const primary = installs.find((i) => i.type === 'installation' && i.status === 'active')
+    || installs[0] || null;
+
+  // The adapter names a binary on THIS machine — the one fact the server
+  // cannot know. Explicit --adapter wins; otherwise probe the known CLIs.
+  let adapterName = adapterOverride;
+  if (adapterOverride) {
+    const adapter = adapterRegistry.getAdapter(adapterOverride);
+    if (!adapter) {
+      throw new Error(`Unknown adapter '${adapterOverride}'. Known: ${adapterRegistry.listAdapterNames().join(', ')}`);
+    }
+    if (!await adapter.detect()) {
+      throw new Error(`Adapter '${adapterOverride}' not found on PATH.`);
+    }
+  } else {
+    for (const candidate of BOOTSTRAP_ADAPTER_DETECT_ORDER) {
+      const adapter = adapterRegistry.getAdapter(candidate);
+      // eslint-disable-next-line no-await-in-loop
+      if (adapter && await adapter.detect()) { adapterName = candidate; break; }
+    }
+    if (!adapterName) {
+      throw new Error(
+        `No supported agent CLI found on PATH (looked for: ${BOOTSTRAP_ADAPTER_DETECT_ORDER.join(', ')}). `
+        + 'Install one, or pass --adapter <name>.',
+      );
+    }
+  }
+
+  // The token's identity wins over the CLI argument — a mistyped name must
+  // not fork a second identity for the same token.
+  const agentName = identity?.agentName || name;
+  if (String(agentName).toLowerCase() !== String(name).toLowerCase()) {
+    log(`token belongs to '${agentName}', not '${name}' — using the token's identity`);
+  }
+
+  return {
+    agentName,
+    instanceId: identity?.instanceId || primary?.instanceId || 'default',
+    podId: primary?.podId || null,
+    instanceUrl,
+    runtimeToken,
+    adapter: adapterName,
+    environment: buildDefaultEnvironment(adapterName),
+    workspacePath: null,
+  };
+};
+
 /**
  * Enumerate every agent attached on this laptop — i.e. every file in
  * ~/.commonly/tokens/*.json. Cross-references the session store for a
@@ -183,6 +285,68 @@ export const buildDefaultEnvironment = (adapterName) => {
   return environment;
 };
 
+// ── public-pod sandbox gate ─────────────────────────────────────────────────
+
+/**
+ * Refuse to attach an agent to a publicly-readable pod unless it declares an
+ * enforced sandbox.
+ *
+ * The public-agent sandbox is real and attack-tested, but it only engages once
+ * `sandbox.trust` and `sandbox.mode` are declared: `sandbox.mode` defaults to
+ * `'none'`, and nothing previously connected "this pod is public" to "this
+ * agent must be confined". An agent attached with no sandbox block simply ran
+ * unconfined, silently, with the operator none the wiser.
+ *
+ * That is not hypothetical — `hq-support` ran that way in a 67-member public
+ * pod until 2026-07-27. Its permission deny-list was doing the file-blocking
+ * work while the OS-level sandbox never engaged at all.
+ *
+ * Deny-by-default only means something if ABSENT is refused, so this is a hard
+ * error rather than a warning. If the pod's visibility cannot be determined
+ * (older server, network failure, permissions), attach proceeds — failing the
+ * attach on an unrelated fault would be its own footgun — but says so, because
+ * a silent skip is how the original hole stayed invisible.
+ */
+export const assertSandboxDeclaredForPublicPod = async ({
+  client,
+  podId,
+  environment,
+  log = () => {},
+}) => {
+  if (!podId || !client) return;
+
+  const mode = environment?.sandbox?.mode;
+  const trust = environment?.sandbox?.trust;
+  const declared = Boolean(trust) && Boolean(mode) && mode !== 'none';
+  if (declared) return;
+
+  let pod = null;
+  try {
+    pod = await client.get(`/api/pods/${podId}`);
+  } catch {
+    log(
+      'warning: could not read pod visibility, so the public-pod sandbox check '
+      + 'was skipped. If this pod is public, attach with sandbox.trust=public.',
+    );
+    return;
+  }
+
+  const isPublic = Boolean(pod?.publicRead) || Boolean(pod?.communityListed);
+  if (!isPublic) return;
+
+  const label = pod?.name ? `"${pod.name}"` : podId;
+  throw new Error(
+    `${label} is publicly readable, so this agent would take instructions from `
+    + 'people you do not control — but its environment declares no sandbox, and '
+    + 'an undeclared sandbox means NO sandbox.\n\n'
+    + 'Add a sandbox block to the environment file and retry:\n\n'
+    + '  "sandbox": { "trust": "public", "mode": "read-only" }\n\n'
+    + 'Modes for a public agent: "read-only" or "workspace" (macOS Seatbelt / '
+    + 'Linux bwrap). To attach an agent to a private pod instead, pass that '
+    + 'pod id.',
+  );
+};
+
 // ── attach: register a local-CLI-wrapped agent (ADR-005) ────────────────────
 
 /**
@@ -288,6 +452,14 @@ export const performAttach = async ({
     }
   }
 
+  // Deny-by-default has to mean "absent = refuse". Runs outside the branch
+  // above because the dangerous case is an agent attached with NO sandbox
+  // declaration at all — the branch that validates sandbox settings never
+  // executes for those, so the agent silently ran unsandboxed.
+  await assertSandboxDeclaredForPublicPod({
+    client, podId, environment, log,
+  });
+
   // Identity-bearing runtime tag from the adapter (e.g. 'codex', 'claude-
   // code'). Falls back to adapter.name for adapters that haven't been
   // updated to the two-field scheme. Paired with `host: 'byo'` below so a
@@ -433,7 +605,24 @@ export const runMemoryImport = async ({
 const extractPrompt = (event) => {
   const p = event.payload || {};
   if (PROMPT_EVENT_TYPES.has(event.type)) {
-    return p.content || p.prompt || p.text || null;
+    const content = p.content || p.prompt || p.text || null;
+    if (content) return content;
+    // #896: a message-shaped event with a messageId but NO content used to be
+    // acked silently as "no prompt — no-op", which reads exactly like a
+    // swallowed wake (the pilot's boot-backlog mystery — repro'd 2026-08-12:
+    // cold starts were healthy; content-less payloads were the whole story).
+    // The wrapper has enough to recover: name the message and let the agent
+    // read the room. Between silence and one model turn, the #887 rule says
+    // spend the turn — the claim gate and cascade cap bound the cost.
+    if (p.messageId) {
+      return [
+        `[Recovered wake: this ${event.type} event named message ${p.messageId} but carried no content — `
+        + 'a producer bug, not your fault. Read the recent messages before deciding anything.]',
+        'Check the pod\'s recent messages (commonly_get_context / commonly_get_messages), find that message,',
+        'and decide whether it needs YOU specifically. Most likely it does not: return NO_REPLY.',
+      ].join('\n');
+    }
+    return null;
   }
   if (event.type === 'heartbeat') {
     return p.content || [
@@ -488,6 +677,20 @@ const extractPrompt = (event) => {
  * the kernel re-delivers. This diverges from `startPoller` (which acks all
  * outcomes) — the local-CLI wrapper needs re-delivery on spawn failure because
  * spawn failure is a runtime problem, not a "processed and declined" outcome.
+ *
+ * ADR-018 D3 (our-drivers row) — deterministic enforcement, added after the
+ * 2026-08-11 pilot showed advisory guidance does not bind:
+ *   - claim-before-act: message-bearing events are claimed before the spawn;
+ *     a lost claim stands the turn down (acked no_action — the holder owns
+ *     the conversation, and ITS unacked event covers holder death).
+ *   - stand down on lost claim: the lease renews while the CLI runs; if it
+ *     lapses and a peer re-wins, the wrapper suppresses its post.
+ *   - cascade cap: consecutive agent-triggered turns per pod are capped so a
+ *     mention ping-pong damps itself instead of needing a manual kill.
+ *   - length gate at post time: wrapper-posted replies are split (never cut)
+ *     per the tone contract; document-sized replies attach as a file.
+ * Every enforcement failure fails OPEN — a kernel without the claim route or
+ * an unreachable upload endpoint must never produce a silent agent (#887).
  */
 export const performRun = ({
   instanceUrl,
@@ -502,6 +705,16 @@ export const performRun = ({
   log = () => {},
   onError,
   setTimeoutImpl = setTimeout,
+  setIntervalImpl = setInterval,
+  clearIntervalImpl = clearInterval,
+  retryJitterRatio,
+  claimLeaseSeconds = 90,
+  cascadeCap = 3,
+  cascadeResetMs = 10 * 60 * 1000,
+  chatCharLimit = 400,
+  maxChatChunks = 3,
+  claimYieldDelayMs = 3000,
+  sleepImpl = (ms) => new Promise((resolve) => { setTimeout(resolve, ms); }),
 }) => {
   const client = createClient({ instance: instanceUrl, token });
   let running = true;
@@ -512,6 +725,13 @@ export const performRun = ({
   // reprovision-all; 5+ wastes rate-limit budget after the real-revoke case.
   let consecutiveAuthErrors = 0;
   const MAX_AUTH_ERRORS = 3;
+  let consecutiveSpawnFailures = 0;
+  const spawnJitterRatio = retryJitterRatio ?? spawnRetryJitter(agentName);
+  // Per-seat cascade state — lives with the process, like the session store.
+  // A wrapper restart forgets the streak; the decay window covers that gap.
+  const cascadeGovernor = createCascadeGovernor({ cap: cascadeCap, resetMs: cascadeResetMs });
+  // Fairness: recent broadcast-race winners start the next race from the back.
+  const claimHandicap = createClaimHandicap({ delayMs: claimYieldDelayMs });
 
   // Adapters default `ctx.cwd` to this path. Node's child_process.spawn
   // rejects with "spawn <bin> ENOENT" when cwd does not exist — same shape
@@ -527,15 +747,22 @@ export const performRun = ({
     if (!prompt || !eventPodId) {
       // No prompt, or nowhere to post the response — skip spawn entirely so
       // we never consume a CLI turn for a message with no destination.
+      // Surfaced through onError, not just the log: a silently-acked event is
+      // indistinguishable from a swallowed wake (#896 — the pilot burned an
+      // evening on exactly this ambiguity). It is still acked (deliberate
+      // decline, not a retry), but the operator can now see the skip.
       log(`[${event.type}] no prompt — no-op`);
-      return { outcome: 'no_action' };
+      onError?.(Object.assign(
+        new Error(
+          `${event.type} event ${event._id} was acked WITHOUT a spawn: `
+          + `${!eventPodId ? 'no podId to post into' : 'payload carried no content and no messageId'}. `
+          + 'If this wake mattered, its producer is sending an unusable payload.',
+        ),
+        { code: 'agent_event_skipped_no_prompt', eventId: event._id },
+      ));
+      return { outcome: 'no_action', reason: 'no-prompt' };
     }
 
-    const sessionId = getSession(agentName, eventPodId);
-    // ADR-005 §Memory bridge: read long_term before spawn, inject via ctx,
-    // and (if the adapter returns a summary) patch-sync back after.
-    const memoryLongTerm = await readLongTerm(client, { onError });
-
     // Snapshot the pod's recent messages so that, after the spawn, we can
     // tell whether the agent posted itself via commonly_post_message. If it
     // did, its final CLI text is a narration/log — echoing it would duplicate
@@ -558,12 +785,106 @@ export const performRun = ({
     // A consult request's final output is routed to the ask-response endpoint,
     // never echoed into the pod. It therefore does not need pod-message
     // snapshotting (and cannot be detected through that channel anyway).
+    // The snapshot doubles as the cascade governor's authorship source, so it
+    // runs BEFORE enforcement.
     const shouldSnapshotMessages = event.type !== 'agent.ask';
     const preSpawn = shouldSnapshotMessages ? await snapshotMessages() : null;
     const preSpawnIds = preSpawn
       ? new Set(preSpawn.map((m) => String(m._id || m.id)))
       : null;
 
+    // ── ADR-018 enforcement: cascade cap ────────────────────────────────────
+    // Refusing here is a deliberate, permanent decline (acked no_action): a
+    // capped agent-triggered event is exactly the traffic we want dropped.
+    // Human-triggered turns are never capped.
+    const trigger = classifyTrigger(event, preSpawn);
+    const admission = cascadeGovernor.admit(eventPodId, trigger);
+    if (!admission.allowed) {
+      log(
+        `[${event.type}] cascade cap: ${admission.streak} consecutive agent-triggered `
+        + `turns in pod ${eventPodId} — standing down until a human speaks or the streak decays`,
+      );
+      return { outcome: 'no_action', reason: 'cascade-cap' };
+    }
+
+    // ── ADR-018 enforcement: claim-before-act ───────────────────────────────
+    // Losing a BROADCAST race is a complete turn (stand down, ack): the
+    // holder owns the conversation, and liveness on holder death comes from
+    // the HOLDER's own event staying unacked, not from ours. Losing while
+    // DIRECTLY ADDRESSED is different — a human chose this seat, and that
+    // outranks being beaten to a CAS: the seat still gets its turn, peer-aware
+    // (add your view only if materially different). Claim-route failures
+    // proceed unguarded — enforcement must never make an agent silent (#887).
+    let claimKeeper = null;
+    let peerFrame = null;
+    const claimMessageId = event.payload?.messageId;
+    if (claimMessageId && CLAIMABLE_EVENT_TYPES.has(event.type)) {
+      // Fairness: the winner of this pod's previous broadcast race enters the
+      // next one after a jittered delay. Everyone still claims — a hard
+      // cooldown could leave a message with NO claimant, which is #887
+      // self-inflicted — recent winners just start from the back.
+      if (event.type === 'message.posted') {
+        const yieldMs = claimHandicap.yieldDelayMs(eventPodId);
+        if (yieldMs > 0) {
+          log(`[${event.type}] yielding ${yieldMs}ms before claiming — won this pod's previous broadcast race`);
+          await sleepImpl(yieldMs);
+        }
+      }
+      claimKeeper = createClaimKeeper(client, {
+        messageId: claimMessageId,
+        podId: eventPodId,
+        leaseSeconds: claimLeaseSeconds,
+        log: (line) => log(`[${event.type}] ${line}`),
+        setIntervalImpl,
+        clearIntervalImpl,
+      });
+      const claim = await claimKeeper.acquire();
+      if (!claim.claimed && !claim.failOpen) {
+        if (ADDRESSED_EVENT_TYPES.has(event.type)) {
+          log(
+            `[${event.type}] message ${claimMessageId} held by ${claim.holder} — `
+            + 'proceeding peer-aware (this seat was directly addressed)',
+          );
+          peerFrame = peerHoldsFrame(claim.holder, claimMessageId);
+          claimKeeper = null; // nothing held: no renewal, no release, no isLost gate
+        } else {
+          claimHandicap.recordLoss(eventPodId);
+          log(`[${event.type}] message ${claimMessageId} already claimed by ${claim.holder} — standing down`);
+          return { outcome: 'no_action', reason: 'claim-held' };
+        }
+      } else if (claim.claimed) {
+        if (event.type === 'message.posted') claimHandicap.recordWin(eventPodId);
+        claimKeeper.startRenewal();
+      } else {
+        log(`[${event.type}] claim unavailable (${claim.error?.message || 'unknown error'}) — proceeding unguarded`);
+      }
+    }
+
+    try {
+      return await runTurn({
+        event,
+        eventPodId,
+        prompt: peerFrame ? `${peerFrame}\n\n${prompt}` : prompt,
+        preSpawnIds,
+        snapshotMessages,
+        claimKeeper,
+        trigger,
+      });
+    } finally {
+      await claimKeeper?.release();
+    }
+  };
+
+  // The spawn → post-decision half of a turn, split out so the claim release
+  // above is a plain finally instead of threading through every return path.
+  const runTurn = async ({
+    event, eventPodId, prompt, preSpawnIds, snapshotMessages, claimKeeper, trigger,
+  }) => {
+    const sessionId = getSession(agentName, eventPodId);
+    // ADR-005 §Memory bridge: read long_term before spawn, inject via ctx,
+    // and (if the adapter returns a summary) patch-sync back after.
+    const memoryLongTerm = await readLongTerm(client, { onError });
+
     log(`[${event.type}] spawning ${adapter.name}`);
     const result = await adapter.spawn(prompt, {
       sessionId,
@@ -669,12 +990,31 @@ export const performRun = ({
         + `(avoids double-post; matched message ${suppressedBy.id} by ${suppressedBy.author} `
         + `via ${suppressedBy.basis})`,
       );
+    } else if (claimKeeper?.isLost()) {
+      // ADR-018 D3: the lease lapsed mid-turn and a peer re-won the message —
+      // that peer owns the conversation now, so posting would recreate the
+      // two-agents-one-message crossing the claim exists to prevent.
+      log(
+        `[${event.type}] stood down — claim lost mid-turn to ${claimKeeper.getHolder()}; `
+        + `reply suppressed (${Buffer.byteLength(replyText)} bytes not posted)`,
+      );
     } else {
-      await client.post(`/api/agents/runtime/pods/${eventPodId}/messages`, {
-        content: replyText,
+      // ADR-018 length gate: the tone contract is enforced here, where the
+      // wrapper is the one posting. Split, attach — never truncate.
+      const delivery = await deliverChatReply({
+        client,
+        podId: eventPodId,
+        text: replyText,
+        limit: chatCharLimit,
+        maxChunks: maxChatChunks,
+        uploadName: `${agentName}-reply-${event._id}.md`,
+        log: (line) => log(`[${event.type}] ${line}`),
       });
       delivered = true;
-      log(`[${event.type}] posted ${Buffer.byteLength(replyText)} bytes`);
+      log(
+        `[${event.type}] posted ${Buffer.byteLength(replyText)} bytes as `
+        + `${delivery.messages} message${delivery.messages === 1 ? '' : 's'} (${delivery.mode})`,
+      );
     }
     if (result.memorySummary) {
       try {
@@ -688,11 +1028,16 @@ export const performRun = ({
         onError?.(new Error(`memory sync failed: ${err.message}`, { cause: err }));
       }
     }
+    // The turn completed — count it toward (or reset) the pod's cascade
+    // streak. Recording only on completion means a spawn failure that gets
+    // redelivered never double-counts toward the cap.
+    cascadeGovernor.record(eventPodId, trigger);
     return { outcome: delivered ? 'posted' : 'no_action' };
   };
 
   const tick = async () => {
     if (!running) return;
+    let nextPollDelayMs = intervalMs;
     try {
       const { events = [] } = await client.get('/api/agents/runtime/events', {
         agentName, instanceId, limit: 10,
@@ -705,15 +1050,49 @@ export const performRun = ({
           result = { outcome: 'no_action', reason: 'duplicate-delivery' };
           log(`[${event.type}] duplicate delivery ${event._id} — skipping spawn and re-acking`);
         } else {
+          const eventWillSpawn = Boolean(extractPrompt(event) && (event.podId || podId));
           try {
             result = await processEvent(event);
           } catch (err) {
-            // Spawn failed — do not record or ack, so the kernel can re-deliver
-            // the event after the local runtime recovers (ADR-005).
-            log(`[${event.type}] spawn error: ${err.message}`);
-            onError?.(err);
-            continue;
+            // Do not record or ack: the kernel must retain the event for
+            // at-least-once delivery. Stop this fetched batch immediately —
+            // continuing could launch every one of the 10 returned events
+            // into the same provider outage before the next poll (#782).
+            consecutiveSpawnFailures += 1;
+            const retry = spawnRetryPolicy({
+              error: err,
+              consecutiveFailures: consecutiveSpawnFailures,
+              intervalMs,
+              jitterRatio: spawnJitterRatio,
+            });
+            nextPollDelayMs = retry.delayMs;
+            const retryIn = formatRetryDelay(retry.delayMs);
+            const state = retry.circuitOpen ? 'circuit open' : 'retry scheduled';
+            const wrapped = new Error(
+              `${event.type} processing failed (${retry.failureClass}; `
+              + `${consecutiveSpawnFailures} consecutive) — event ${event._id} remains unacked; `
+              + `${state}, next probe in ${retryIn}: ${err.message}`,
+              { cause: err },
+            );
+            Object.assign(wrapped, {
+              code: 'agent_spawn_retry_scheduled',
+              failureClass: retry.failureClass,
+              consecutiveFailures: consecutiveSpawnFailures,
+              retryAfterMs: retry.delayMs,
+              circuitOpen: retry.circuitOpen,
+              eventId: event._id,
+            });
+            log(`[${event.type}] ${wrapped.message}`);
+            onError?.(wrapped);
+            break;
           }
+          // Only a completed model turn proves the local runtime and delivery
+          // path recovered. A malformed/no-destination event is still acked,
+          // but must not erase the failure streak without exercising either —
+          // and neither may an enforcement stand-down (cascade cap, lost
+          // claim), which returns before any spawn happens.
+          const stoodDown = result?.reason === 'cascade-cap' || result?.reason === 'claim-held';
+          if (eventWillSpawn && !stoodDown) consecutiveSpawnFailures = 0;
           // Record after successful processing but before ack. If the ack
           // fails, the next delivery is skipped and re-acked instead of
           // burning a second model turn for work that already completed.
@@ -739,7 +1118,7 @@ export const performRun = ({
       }
       onError?.(err);
     }
-    if (running) setTimeoutImpl(tick, intervalMs);
+    if (running) setTimeoutImpl(tick, nextPollDelayMs);
   };
 
   tick();
@@ -1260,11 +1639,33 @@ Docs:
     .command('run <name>')
     .description('Run the local-CLI wrapper loop for an attached agent')
     .option('--interval <ms>', 'Poll interval in ms', '5000')
+    .option('--adapter <name>', 'CLI to wrap on first-run bootstrap (claude|codex); ignored when a token file already exists')
     .action(async (name, opts) => {
-      const record = loadAgentToken(name);
+      let record = loadAgentToken(name);
       if (!record) {
-        console.error(`No token for '${name}'. Run: commonly agent attach <adapter> --pod <podId> --name ${name}`);
-        process.exit(1);
+        // First run on this machine: the BYO connect page hands out env vars,
+        // not a token file — bootstrap the record from them (#913).
+        try {
+          record = await bootstrapAgentRecordFromEnv({
+            name,
+            adapterOverride: opts.adapter || null,
+            log: (line) => console.log(`[${name}] ${line}`),
+          });
+        } catch (err) {
+          console.error(err.message);
+          process.exit(1);
+        }
+        if (record) {
+          saveAgentToken(record.agentName, record);
+          console.log(`[${name}] bootstrapped ${tokenFile(record.agentName)} from COMMONLY_AGENT_TOKEN (adapter: ${record.adapter})`);
+        } else {
+          console.error(
+            `No token for '${name}'. Either export COMMONLY_API_URL + COMMONLY_AGENT_TOKEN`
+            + ` (shown on the Connect your own agent page) and re-run, or:`
+            + ` commonly agent attach <adapter> --pod <podId> --name ${name}`,
+          );
+          process.exit(1);
+        }
       }
 
       const adapter = getAdapter(record.adapter);

package/src/lib/adapters/claude.js

@@ -244,7 +244,16 @@ const runClaude = ({ cmd, args, cwd, env, timeoutMs, spawnImpl = childSpawn }) =
   proc.on('close', (code) => {
     clearTimeout(timer);
     if (timedOut) return reject(new Error(`claude timed out after ${timeoutMs}ms`));
-    if (code !== 0) return reject(new Error(`claude exited with code ${code}: ${stderr.trim()}`));
+    if (code !== 0) {
+      // Report stdout too, not just stderr. In `-p` mode claude writes terminal
+      // conditions (usage limits especially) to stdout and exits non-zero with
+      // stderr empty — 361 consecutive failures on 2026-08-03 carried no reason
+      // at all because of this. It is not only a diagnosability problem: the
+      // circuit breaker classifies from the error message, so a blank message
+      // downgrades a hard quota failure to RUNTIME and its shortest backoff.
+      const detail = [stderr.trim(), stdout.trim()].filter(Boolean).join(' | ');
+      return reject(new Error(`claude exited with code ${code}: ${detail.slice(0, 2000)}`));
+    }
     resolve(stdout);
   });
 });

package/src/lib/api.js

@@ -48,7 +48,30 @@ export const createClient = ({ instance = null, token = null } = {}) => {
     headers: headers(authToken),
   }).then(handleResponse);
 
-  return { get, post, del, baseUrl };
+  // Multipart upload via native FormData/Blob (Node 18+) — no runtime deps.
+  // Content-Type is deliberately NOT set: fetch writes the multipart boundary.
+  const upload = (path, {
+    fileBuffer, fileName, contentType, fileField = 'file', fields = {},
+  }) => {
+    const form = new FormData();
+    form.append(
+      fileField,
+      new Blob([fileBuffer], { type: contentType || 'application/octet-stream' }),
+      fileName,
+    );
+    for (const [k, v] of Object.entries(fields)) {
+      if (v !== undefined && v !== null) form.append(k, String(v));
+    }
+    return fetch(`${baseUrl}${path}`, {
+      method: 'POST',
+      headers: authToken ? { Authorization: `Bearer ${authToken}` } : {},
+      body: form,
+    }).then(handleResponse);
+  };
+
+  return {
+    get, post, del, upload, baseUrl,
+  };
 };
 
 // Convenience: login doesn't need a token

package/src/lib/enforcement.js

@@ -0,0 +1,431 @@
+/**
+ * Wrapper-side enforcement (ADR-018 D3, "our drivers" row).
+ *
+ * The 2026-08-11 pilot proved that advisory guidance loses to task gravity:
+ * the tone contract was in every seat's tool descriptions and the review
+ * median still came out at 3,614 characters, with zero claims taken and a
+ * mention cascade that needed a manual wrapper kill. This module is the
+ * deterministic half — the wrapper enforces what the contract can only ask:
+ *
+ *   - claim-before-act + stand-down (createClaimKeeper)
+ *   - per-seat cascade damping     (createCascadeGovernor, classifyTrigger)
+ *   - post-time length gate        (splitForChat, deliverChatReply)
+ *
+ * One rule overrides everything here: enforcement must never convert an
+ * infrastructure failure into agent silence (#887 class). Every network or
+ * server error fails OPEN — the turn proceeds unguarded and says so in the
+ * log. Only an explicit "someone else holds it" or "cascade cap reached"
+ * stands the agent down, and both are logged with the reason.
+ */
+
+// Event types whose payload.messageId identifies a claimable trigger message.
+// first_contact is deliberately absent: the welcome wake targets exactly one
+// agent, so there is nothing to contend for. Heartbeats have no message at
+// all, and agent.ask routes privately.
+export const CLAIMABLE_EVENT_TYPES = new Set([
+  'chat.mention',
+  'message.posted',
+  'dm.message',
+]);
+
+// ── trigger classification ──────────────────────────────────────────────────
+
+/**
+ * Who authored the message that woke us — 'agent', 'human', or 'unknown'?
+ *
+ * Two signals, in order of reliability:
+ *   1. payload.dmKind — the kernel stamps DM wakes 'agent-agent'/'user-agent'.
+ *   2. The trigger message's isBot flag, looked up by payload.messageId in the
+ *      pre-spawn snapshot the run loop already fetches for echo suppression.
+ *
+ * 'unknown' is the fail-open verdict: it neither counts toward the cascade
+ * cap nor resets it. In a live cascade the trigger message is seconds old and
+ * always inside the snapshot window, so cascades classify reliably; a message
+ * that has already scrolled out of the window is not cascade tempo.
+ */
+export const classifyTrigger = (event, recentMessages) => {
+  const p = event?.payload || {};
+  if (p.dmKind === 'agent-agent') return 'agent';
+  if (p.dmKind === 'user-agent') return 'human';
+  if (!p.messageId || !Array.isArray(recentMessages)) return 'unknown';
+  const trigger = recentMessages.find(
+    (m) => String(m._id || m.id) === String(p.messageId),
+  );
+  if (!trigger || typeof trigger.isBot !== 'boolean') return 'unknown';
+  return trigger.isBot ? 'agent' : 'human';
+};
+
+// ── cascade governor ────────────────────────────────────────────────────────
+
+/**
+ * Per-pod damping of agent→agent retrigger chains.
+ *
+ * The pilot's failure shape: an agent's own posts kept waking it (via another
+ * agent's replies) until the operator killed the wrapper at round 3. The
+ * governor counts CONSECUTIVE agent-triggered turns per pod; at `cap` it
+ * refuses further agent-triggered turns until a human-triggered turn resets
+ * the streak or `resetMs` passes with no agent-triggered turn (so a damped
+ * pod recovers on its own — a legitimate a2a handoff an hour later must not
+ * inherit a stale cap).
+ *
+ * Split into admit/record so a spawn that fails (and will be redelivered)
+ * never double-counts: admit() only reads, record() runs after a turn
+ * actually completed. Human-triggered turns are always admitted.
+ */
+export const createCascadeGovernor = ({
+  cap = 3,
+  resetMs = 10 * 60 * 1000,
+  now = Date.now,
+} = {}) => {
+  const pods = new Map(); // podId -> { streak, lastAgentTurnAt }
+
+  const stateFor = (podId) => {
+    const s = pods.get(podId) || { streak: 0, lastAgentTurnAt: 0 };
+    if (s.streak > 0 && now() - s.lastAgentTurnAt > resetMs) {
+      return { streak: 0, lastAgentTurnAt: 0 };
+    }
+    return s;
+  };
+
+  return {
+    admit(podId, trigger) {
+      if (trigger !== 'agent') return { allowed: true, streak: 0 };
+      const s = stateFor(podId);
+      return { allowed: s.streak < cap, streak: s.streak };
+    },
+    record(podId, trigger) {
+      if (trigger === 'human') {
+        pods.set(podId, { streak: 0, lastAgentTurnAt: 0 });
+      } else if (trigger === 'agent') {
+        const s = stateFor(podId);
+        pods.set(podId, { streak: s.streak + 1, lastAgentTurnAt: now() });
+      }
+      // 'unknown' is neutral: no count, no reset.
+    },
+  };
+};
+
+// ── claim fairness ──────────────────────────────────────────────────────────
+
+// Direct-address event types: the seat was NAMED (explicit @, implicit human
+// reply, or DM routing). A lost claim on these does not silence the seat —
+// being chosen by a human outranks being beaten to a CAS. Broadcast wakes
+// (message.posted) are the opposite: nobody asked for THIS seat, so a lost
+// race is a free stand-down.
+export const ADDRESSED_EVENT_TYPES = new Set(['chat.mention', 'thread.mention', 'dm.message']);
+
+// Frame prepended when an ADDRESSED seat lost the claim race: it still gets
+// its turn, but knows a peer is (probably) already answering — the bar for
+// posting rises from "have something to say" to "have something DIFFERENT".
+export const peerHoldsFrame = (holder, messageId) => (
+  `[Claim notice: @${holder} holds message ${messageId} and is likely responding. `
+  + 'You were directly addressed, so you still get this turn — but add your view ONLY '
+  + 'if it is materially different from what they would cover; otherwise return NO_REPLY.]'
+);
+
+/**
+ * Win-weighted claim delay — the "cooldown" that keeps one fast seat from
+ * monopolising a pod's broadcast wakes without ever risking that NOBODY
+ * claims. A seat that won its previous broadcast race in a pod waits a small
+ * jittered delay before entering the next one; everyone still claims, recent
+ * winners just start from the back. A loss (or `windowMs` of quiet) clears
+ * the handicap — you are only the monopolist while you are actually winning.
+ *
+ * Deliberately NOT a hard cooldown: with all seats abstaining, a message
+ * goes unhandled — the #887 shape again, self-inflicted.
+ */
+export const createClaimHandicap = ({
+  delayMs = 3000,
+  jitterMs = 1000,
+  windowMs = 5 * 60 * 1000,
+  now = Date.now,
+  random = Math.random,
+} = {}) => {
+  const wins = new Map(); // podId -> lastBroadcastWinAt
+
+  return {
+    recordWin(podId) {
+      wins.set(podId, now());
+    },
+    recordLoss(podId) {
+      wins.delete(podId);
+    },
+    yieldDelayMs(podId) {
+      const at = wins.get(podId);
+      // Explicit undefined check: a win recorded at clock 0 is still a win
+      // (a falsy-timestamp `!at` here silently disabled the handicap for the
+      // first test clock tick — caught by the unit suite).
+      if (at === undefined || now() - at > windowMs) return 0;
+      return delayMs + Math.floor(random() * jitterMs);
+    },
+  };
+};
+
+// ── claim keeper ────────────────────────────────────────────────────────────
+
+/**
+ * One claim lifecycle for one event: acquire → renew while the CLI turn runs
+ * → release (or discover mid-turn loss and stand down at post time).
+ *
+ * Acquire outcomes:
+ *   { claimed: true }                  — we hold the lease; start renewal.
+ *   { claimed: false, holder }         — someone else holds it; STAND DOWN.
+ *   { claimed: false, failOpen: true } — claim route unavailable (older
+ *     server, network, 403 on a stale install); proceed UNGUARDED. The
+ *     alternative turns a kernel deploy gap into a silent agent.
+ *
+ * Renewal reuses the same POST (a holder wins against itself — that IS
+ * renewal, per messageClaimService). A renewal that comes back claimed:false
+ * means our lease lapsed (laptop slept, turn ran long) and a peer re-won:
+ * mark lost so the run loop suppresses the wrapper post. Transient renewal
+ * errors are ignored — the current lease may still be live, and the next
+ * tick retries.
+ */
+export const createClaimKeeper = (client, {
+  messageId,
+  podId,
+  leaseSeconds = 90,
+  log = () => {},
+  setIntervalImpl = setInterval,
+  clearIntervalImpl = clearInterval,
+}) => {
+  const path = `/api/agents/runtime/messages/${encodeURIComponent(messageId)}/claim`;
+  let acquired = false;
+  let lost = false;
+  let holder = null;
+  let timer = null;
+
+  const holderLabel = (res) => {
+    if (!res?.claimedBy) return 'another agent';
+    const instance = res.instanceId && res.instanceId !== 'default' ? `:${res.instanceId}` : '';
+    return `${res.claimedBy}${instance}`;
+  };
+
+  const stopRenewal = () => {
+    if (timer) {
+      clearIntervalImpl(timer);
+      timer = null;
+    }
+  };
+
+  return {
+    async acquire() {
+      try {
+        const res = await client.post(path, { podId, leaseSeconds });
+        if (res?.claimed) {
+          acquired = true;
+          return { claimed: true, expiresAt: res.expiresAt };
+        }
+        holder = holderLabel(res);
+        return { claimed: false, holder };
+      } catch (err) {
+        return { claimed: false, failOpen: true, error: err };
+      }
+    },
+
+    startRenewal() {
+      if (!acquired || timer) return;
+      timer = setIntervalImpl(async () => {
+        try {
+          const res = await client.post(path, { podId, leaseSeconds });
+          if (!res?.claimed) {
+            lost = true;
+            holder = holderLabel(res);
+            stopRenewal();
+            log(`claim on message ${messageId} lost mid-turn to ${holder} — standing down at post time`);
+          }
+        } catch {
+          // Transient renewal failure — the held lease may still be live;
+          // retry on the next tick rather than standing down on a blip.
+        }
+      }, Math.max(5000, (leaseSeconds * 1000) / 2));
+      if (timer && typeof timer.unref === 'function') timer.unref();
+    },
+
+    async release() {
+      stopRenewal();
+      if (!acquired || lost) return;
+      try {
+        await client.del(path);
+      } catch {
+        // Best-effort: a miss just means the lease already expired.
+      }
+    },
+
+    isLost: () => lost,
+    getHolder: () => holder,
+  };
+};
+
+// ── post-time length gate ───────────────────────────────────────────────────
+
+/**
+ * Split chat text into tone-contract-sized messages without ever cutting
+ * content. Boundaries in preference order: fenced code blocks stay whole
+ * (atomic — an oversized fence becomes one oversized message rather than a
+ * broken pair), then paragraphs, then sentences, then words. Greedy packing
+ * rejoins small pieces so two short paragraphs share one message.
+ */
+export const splitForChat = (text, { limit = 400 } = {}) => {
+  const trimmed = String(text || '').trim();
+  if (!trimmed) return [];
+  if (trimmed.length <= limit) return [trimmed];
+
+  // Pass 1: carve into blocks — fences atomic, prose split by paragraph.
+  const blocks = [];
+  let prose = [];
+  const flushProse = () => {
+    const joined = prose.join('\n');
+    prose = [];
+    for (const para of joined.split(/\n{2,}/)) {
+      if (para.trim()) blocks.push({ text: para.trim(), atomic: false });
+    }
+  };
+  const lines = trimmed.split('\n');
+  let i = 0;
+  while (i < lines.length) {
+    const fence = lines[i].match(/^(```|~~~)/)?.[1];
+    if (fence) {
+      flushProse();
+      const fenced = [lines[i]];
+      i += 1;
+      while (i < lines.length && !lines[i].startsWith(fence)) {
+        fenced.push(lines[i]);
+        i += 1;
+      }
+      if (i < lines.length) {
+        fenced.push(lines[i]); // closing fence
+        i += 1;
+      }
+      blocks.push({ text: fenced.join('\n'), atomic: true });
+    } else {
+      prose.push(lines[i]);
+      i += 1;
+    }
+  }
+  flushProse();
+
+  // Pass 2: split oversized prose blocks at sentence then word boundaries.
+  const units = [];
+  for (const block of blocks) {
+    if (block.atomic || block.text.length <= limit) {
+      units.push(block.text);
+      continue;
+    }
+    let piece = '';
+    const flushPiece = () => {
+      if (piece.trim()) units.push(piece.trim());
+      piece = '';
+    };
+    for (const sentence of block.text.split(/(?<=[.!?])\s+/)) {
+      if (sentence.length > limit) {
+        flushPiece();
+        let run = '';
+        for (const word of sentence.split(/\s+/)) {
+          if (run && `${run} ${word}`.length > limit) {
+            units.push(run);
+            run = word;
+          } else {
+            run = run ? `${run} ${word}` : word;
+          }
+        }
+        if (run) units.push(run); // a single over-limit word (URL) posts whole
+      } else if (piece && `${piece} ${sentence}`.length > limit) {
+        flushPiece();
+        piece = sentence;
+      } else {
+        piece = piece ? `${piece} ${sentence}` : sentence;
+      }
+    }
+    flushPiece();
+  }
+
+  // Pass 3: greedy packing back up to the limit.
+  const chunks = [];
+  let acc = '';
+  for (const unit of units) {
+    const joined = acc ? `${acc}\n\n${unit}` : unit;
+    if (joined.length <= limit) {
+      acc = joined;
+    } else {
+      if (acc) chunks.push(acc);
+      acc = unit;
+    }
+  }
+  if (acc) chunks.push(acc);
+  return chunks;
+};
+
+/**
+ * Deliver a wrapper-posted reply under the tone contract, deterministically:
+ *
+ *   fits in one message            → post as-is
+ *   splits into ≤ maxChunks        → post the chunks in order ("two short
+ *                                    messages beat one wall")
+ *   longer than a split answer     → it is a document, not a message: upload
+ *                                    the FULL text as a file and post one
+ *                                    message — the reply's own opening plus
+ *                                    the file card. Nothing is cut; the file
+ *                                    holds everything.
+ *
+ * If the upload fails (older server, network), fall back to posting every
+ * chunk: a message flood is a tone violation, silence or truncation is a
+ * correctness violation, and the contract itself ranks content above tone
+ * ("NEVER hit that by cutting content").
+ */
+export const deliverChatReply = async ({
+  client,
+  podId,
+  text,
+  limit = 400,
+  maxChunks = 3,
+  attachThreshold = 800,
+  uploadName = 'reply.md',
+  log = () => {},
+}) => {
+  const messagesPath = `/api/agents/runtime/pods/${podId}/messages`;
+  const chunks = splitForChat(text, { limit });
+  // An atomic unit (a fenced block, an unbreakable word-run) can exceed the
+  // limit by construction — splitForChat keeps it whole rather than breaking
+  // its rendering. The tone contract's own rule covers it: over ~800 chars of
+  // ONE indivisible thing is a document, not a message — attach it. Without
+  // this check a 659-char fence rode the single/split branches straight past
+  // the gate (found by the fleet's implementation audit, Sharpen msg 53018).
+  const hasIndivisibleOversize = chunks.some((c) => c.length > attachThreshold);
+  if (chunks.length <= 1 && !hasIndivisibleOversize) {
+    await client.post(messagesPath, { content: chunks[0] ?? text });
+    return { mode: 'single', messages: 1 };
+  }
+  if (chunks.length <= maxChunks && !hasIndivisibleOversize) {
+    for (const chunk of chunks) {
+      // eslint-disable-next-line no-await-in-loop
+      await client.post(messagesPath, { content: chunk }); // in order, so the reply reads top-down
+    }
+    return { mode: 'split', messages: chunks.length };
+  }
+  try {
+    const uploaded = await client.upload(`/api/agents/runtime/pods/${podId}/uploads`, {
+      fileBuffer: Buffer.from(String(text), 'utf8'),
+      fileName: uploadName,
+      contentType: 'text/markdown',
+      fields: { podId },
+    });
+    const u = uploaded || {};
+    const directive = `[[upload:${u.fileName || uploadName}|${u.originalName || uploadName}|${u.size ?? Buffer.byteLength(String(text))}|${u.kind || 'document'}]]`;
+    // Lead with the reply's own opening — unless that opening is itself the
+    // oversized atomic unit (a fence-only reply), in which case a generic
+    // line keeps the message under the gate and the card carries the content.
+    const lead = chunks[0] && chunks[0].length <= limit
+      ? chunks[0]
+      : '(reply too large for chat — attached in full)';
+    await client.post(messagesPath, { content: `${lead}\n\n${directive}` });
+    return { mode: 'attach', messages: 1 };
+  } catch (err) {
+    log(`attach fallback failed (${err.message}) — posting ${chunks.length} split messages instead`);
+    for (const chunk of chunks) {
+      // eslint-disable-next-line no-await-in-loop
+      await client.post(messagesPath, { content: chunk });
+    }
+    return { mode: 'split-fallback', messages: chunks.length };
+  }
+};

package/src/lib/spawn-retry.js

@@ -0,0 +1,160 @@
+/**
+ * Retry policy for local wrapper event-processing failures (#782).
+ *
+ * The kernel deliberately re-delivers an event that the wrapper does not
+ * acknowledge. That preserves at-least-once handling, but a flat poll loop
+ * turns a model-provider outage into repeated subprocess launches. Keep the
+ * retry policy here so every adapter gets the same bounded behavior.
+ */
+
+export const SPAWN_FAILURE_CLASS = Object.freeze({
+  QUOTA: 'quota',
+  RATE_LIMIT: 'rate_limit',
+  CONFIGURATION: 'configuration',
+  RUNTIME: 'runtime',
+});
+
+export const SPAWN_CIRCUIT_THRESHOLD = 3;
+// Base ceiling before the stable per-agent 0–20% anti-herd offset.
+export const SPAWN_RETRY_MAX_MS = 15 * 60 * 1000;
+export const SPAWN_RETRY_JITTER_MAX_RATIO = 0.2;
+
+// `out of credits` is codex's exact wording for an exhausted workspace balance
+// ("Your workspace is out of credits. Ask your workspace owner to refill…").
+// Without it that outage classified as RUNTIME and drew the shortest backoff —
+// observed live on 2026-08-03 before this pattern was added.
+const QUOTA_RE = /(?:quota|usage limit|credit balance|out of credits|billing|insufficient[_ -]?quota|resource exhausted|spending limit)/i;
+const RATE_LIMIT_RE = /(?:rate[ -]?limit|too many requests|\b429\b|overloaded|capacity)/i;
+const CONFIGURATION_RE = /(?:ENOENT|command not found|not on PATH|login required|not logged in|invalid api key|authentication failed|unauthori[sz]ed|forbidden|\b40[13]\b)/i;
+
+const errorText = (error) => [
+  error?.message,
+  error?.stderr,
+  error?.body?.error,
+  error?.body?.message,
+]
+  .filter(Boolean)
+  .map(String)
+  .join('\n');
+
+export const classifySpawnFailure = (error) => {
+  const text = errorText(error);
+  // Provider APIs commonly report an exhausted account quota as HTTP 429.
+  // Prefer the more specific body/message over the generic status code so a
+  // hard quota failure gets the long cooldown rather than a one-minute probe.
+  if (QUOTA_RE.test(text)) return SPAWN_FAILURE_CLASS.QUOTA;
+  if (error?.status === 429 || RATE_LIMIT_RE.test(text)) {
+    return SPAWN_FAILURE_CLASS.RATE_LIMIT;
+  }
+  if (
+    error?.code === 'ENOENT'
+    || error?.status === 401
+    || error?.status === 403
+    || CONFIGURATION_RE.test(text)
+  ) {
+    return SPAWN_FAILURE_CLASS.CONFIGURATION;
+  }
+  return SPAWN_FAILURE_CLASS.RUNTIME;
+};
+
+// A stable per-agent offset keeps a fleet from probing a recovering provider
+// in lockstep. Stability matters: random jitter makes operator logs and tests
+// harder to reason about, while distinct agent names already provide entropy.
+export const spawnRetryJitter = (agentName) => {
+  let hash = 2166136261;
+  for (const char of String(agentName || 'agent')) {
+    hash ^= char.charCodeAt(0);
+    hash = Math.imul(hash, 16777619);
+  }
+  return ((hash >>> 0) % 2001) / 10000;
+};
+
+const applyJitter = (delayMs, jitterRatio) => {
+  const safeJitter = Number.isFinite(jitterRatio)
+    ? Math.min(SPAWN_RETRY_JITTER_MAX_RATIO, Math.max(0, jitterRatio))
+    : 0;
+  return Math.round(delayMs * (1 + safeJitter));
+};
+
+/**
+ * Return the next probe delay and whether the circuit is open.
+ *
+ * Known non-transient failures open immediately. Unknown runtime failures get
+ * two quick retries, then open the circuit on the third consecutive failure.
+ * Later probes back off exponentially to the same 15-minute base ceiling.
+ */
+export const spawnRetryPolicy = ({
+  error,
+  consecutiveFailures,
+  intervalMs,
+  jitterRatio = 0,
+}) => {
+  const failureClass = classifySpawnFailure(error);
+  const safeIntervalMs = Number.isFinite(intervalMs) && intervalMs > 0 ? intervalMs : 5000;
+  const failureCount = Number.isInteger(consecutiveFailures) && consecutiveFailures > 0
+    ? consecutiveFailures
+    : 1;
+
+  if (
+    failureClass === SPAWN_FAILURE_CLASS.QUOTA
+    || failureClass === SPAWN_FAILURE_CLASS.CONFIGURATION
+  ) {
+    return {
+      failureClass,
+      circuitOpen: true,
+      delayMs: applyJitter(SPAWN_RETRY_MAX_MS, jitterRatio),
+    };
+  }
+
+  if (failureClass === SPAWN_FAILURE_CLASS.RATE_LIMIT) {
+    return {
+      failureClass,
+      circuitOpen: true,
+      delayMs: applyJitter(
+        Math.min(
+          SPAWN_RETRY_MAX_MS,
+          60 * 1000 * (2 ** (failureCount - 1)),
+        ),
+        jitterRatio,
+      ),
+    };
+  }
+
+  if (failureCount < SPAWN_CIRCUIT_THRESHOLD) {
+    return {
+      failureClass,
+      circuitOpen: false,
+      delayMs: applyJitter(
+        Math.min(
+          SPAWN_RETRY_MAX_MS,
+          safeIntervalMs * (2 ** (failureCount - 1)),
+        ),
+        jitterRatio,
+      ),
+    };
+  }
+
+  return {
+    failureClass,
+    circuitOpen: true,
+    delayMs: applyJitter(
+      Math.min(
+        SPAWN_RETRY_MAX_MS,
+        60 * 1000 * (2 ** (failureCount - SPAWN_CIRCUIT_THRESHOLD)),
+      ),
+      jitterRatio,
+    ),
+  };
+};
+
+export const formatRetryDelay = (delayMs) => {
+  if (delayMs >= 60000) {
+    const minutes = delayMs / 60000;
+    return `${Number.isInteger(minutes) ? minutes : minutes.toFixed(1)}m`;
+  }
+  if (delayMs >= 1000) {
+    const seconds = delayMs / 1000;
+    return `${Number.isInteger(seconds) ? seconds : seconds.toFixed(1)}s`;
+  }
+  return `${delayMs}ms`;
+};