@commonlyai/cli 0.1.8 → 0.1.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commonlyai/cli",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "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

@@ -39,6 +39,16 @@ import {
   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) ───────────────
 
@@ -47,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 },
   );
 };
 
@@ -69,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
@@ -188,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) ────────────────────
 
 /**
@@ -293,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
@@ -438,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 || [
@@ -493,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,
@@ -507,7 +705,17 @@ export const performRun = ({
   log = () => {},
   onError,
   setTimeoutImpl = setTimeout,
+  setIntervalImpl = setInterval,
+  clearIntervalImpl = clearInterval,
   retryJitterRatio,
+  claimLeaseSeconds = 90,
+  cascadeCap = 3,
+  cascadeAddressedGrace = 2,
+  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;
@@ -520,6 +728,15 @@ export const performRun = ({
   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,
+    addressedGrace: cascadeAddressedGrace,
+    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
@@ -535,15 +752,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
@@ -566,12 +790,108 @@ 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, event.type);
+    if (!admission.allowed) {
+      log(
+        `[${event.type}] cascade cap: ${admission.streak} consecutive agent-triggered `
+        + `turns in pod ${eventPodId}`
+        + (admission.addressed ? ' (addressed grace also spent)' : '')
+        + ' — standing down until a human speaks or the pod goes quiet for the reset window',
+      );
+      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,
@@ -677,12 +997,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 {
@@ -696,6 +1035,10 @@ 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' };
   };
 
@@ -746,14 +1089,35 @@ export const performRun = ({
               circuitOpen: retry.circuitOpen,
               eventId: event._id,
             });
-            log(`[${event.type}] ${wrapped.message}`);
-            onError?.(wrapped);
+            // ONE emission, not two. `wrapped.message` already opens with the
+            // event type, so the log copy added a second prefix and a second
+            // line of identical text into the same merged stream — enough that
+            // `grep -c 'session limit'` returned 8 for 4 failures, and a reader
+            // counting hits per event id saw 2 and inferred two deliveries.
+            // On 2026-08-18 that count pointed at the wrong cause for #993:
+            // two deliveries per event puts `attempts` at 2 and the requeue cap
+            // one step away. It did not decide anything — the cap was ruled out
+            // from the DB, where a capped event would have left a `failed` row
+            // and none existed — but it corroborated the wrong theory, and the
+            // doubling had to be spotted by hand before the count could be
+            // discounted. A log that inflates is worse than one that is silent,
+            // because it argues.
+            //
+            // Routed to the error channel when a caller provides one, and to
+            // the log when it doesn't, so neither contract loses the failure:
+            // an embedder that passes no `onError` still sees it, and `agent
+            // run` — which always passes one — stops printing it twice.
+            if (onError) onError(wrapped);
+            else log(`[${event.type}] ${wrapped.message}`);
             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.
-          if (eventWillSpawn) consecutiveSpawnFailures = 0;
+          // 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.
@@ -961,6 +1325,24 @@ export const performDetach = async ({
   return { backend: backendResult, localCleaned: true };
 };
 
+/**
+ * Every line a seat emits lands in one file, because the fleet is launched as
+ * `nohup commonly agent run <name> > <log> 2>&1`. Until now none of those lines
+ * carried a time.
+ *
+ * That is not a cosmetic gap. On 2026-08-18 a fleet-wide quota stall destroyed
+ * 38 queued events (#993), and the seat log was the ONLY surviving trace —
+ * the kernel rows were deleted, so nothing else recorded that those turns had
+ * been attempted. The log records `(4 consecutive)` and `next probe in 2.0m`
+ * and gives no way to place either on a clock: the investigation had to date
+ * events by decoding ObjectId prefixes instead, because the file that named
+ * them could not say when.
+ *
+ * ISO-8601 so stamps sort lexically, diff cleanly, and line up with the
+ * kernel's own timestamps without conversion.
+ */
+const stamp = () => new Date().toISOString();
+
 export const registerAgent = (program) => {
   const agent = program.command('agent').description('Manage agents');
 
@@ -1300,11 +1682,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(`${stamp()} [${name}] ${line}`),
+          });
+        } catch (err) {
+          console.error(`${stamp()} [${name}] ${err.message}`);
+          process.exit(1);
+        }
+        if (record) {
+          saveAgentToken(record.agentName, record);
+          console.log(`${stamp()} [${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);
@@ -1313,7 +1717,14 @@ Docs:
         process.exit(1);
       }
 
-      console.log(`[${name}] polling ${record.instanceUrl} for events (ctrl+c to stop)`);
+      // THE line to stamp, not just one of them. It is the first line of every
+      // seat log and the truncation boundary — the fleet is launched as
+      // `nohup … > log 2>&1`, so this banner is written at boot and everything
+      // before it is gone. Stamped, it dates the restart from the log itself.
+      // Unstamped, it took `ps -o lstart` to establish when nine seats came
+      // back on 2026-08-18, and that only worked because the processes were
+      // still alive — after the next restart that route is gone too.
+      console.log(`${stamp()} [${name}] polling ${record.instanceUrl} for events (ctrl+c to stop)`);
 
       const { stop } = performRun({
         instanceUrl: record.instanceUrl,
@@ -1325,12 +1736,32 @@ Docs:
         environment: record.environment || null,
         workspacePath: record.workspacePath || null,
         intervalMs: parseInt(opts.interval, 10),
-        log: (line) => console.log(`[${name}] ${line}`),
-        onError: (err) => console.error(`[${name}] ${err.message}`),
+        log: (line) => console.log(`${stamp()} [${name}] ${line}`),
+        // Both sinks are stamped, and both must be — but not for the reason
+        // this comment gave until now, which its own PR falsified.
+        //
+        // A spawn failure is routed to `onError` when a caller provides one and
+        // to `log` only as the fallback, so in `agent run` — which always passes
+        // one — EVERY failure line comes out of the error channel and none out
+        // of the log. Stamping only `log:` would leave the entire failure class
+        // undated, which is the class these stamps exist for.
+        //
+        // The two sinks also carry genuinely different text elsewhere: the
+        // no-prompt skip logs a terse line and sends a detailed diagnostic, so
+        // one stamped and one bare would date half of that pair.
+        //
+        // (History, because the reasoning moved twice. This originally argued
+        // from a DOUBLE emission — the retry path called both sinks with
+        // identical text, so `grep -c 'session limit'` returned 8 for 4 failures
+        // and a per-event count read as two deliveries. That was true when the
+        // stamps landed and false eleven minutes later, when the same PR
+        // collapsed the duplication. The conclusion survived the premise; the
+        // sentence did not, and nothing in the diff pointed at it.)
+        onError: (err) => console.error(`${stamp()} [${name}] ${err.message}`),
       });
 
       process.on('SIGINT', () => {
-        console.log(`\n[${name}] stopping...`);
+        console.log(`\n${stamp()} [${name}] stopping...`);
         stop();
         process.exit(0);
       });

package/src/lib/adapters/claude.js

@@ -474,7 +474,18 @@ export default {
     const sessionId = ctx.sessionId || randomUUID();
     const fullPrompt = buildPrompt(prompt, ctx.memoryLongTerm || '');
     const sessionFlag = isResume ? '--resume' : '--session-id';
-    const baseArgs = ['-p', fullPrompt, '--output-format', 'text', sessionFlag, sessionId];
+    // Model pin from the ADR-008 environment spec. Absent it, claude picks its
+    // own default — which is how a fleet of ten agents ended up running three
+    // different Opus versions that nobody chose and nothing recorded, with one
+    // seat named after a model it does not run.
+    //
+    // Computed ONCE and spread into BOTH arg builders. The session-recovery
+    // path at the bottom of this function constructs its own array, and a model
+    // present in one but not the other means a retry silently runs a different
+    // model than the turn it is replacing — the same drifting-copy shape that
+    // has bitten this codebase repeatedly.
+    const modelArgs = ctx.environment?.model ? ['--model', String(ctx.environment.model)] : [];
+    const baseArgs = ['-p', fullPrompt, '--output-format', 'text', sessionFlag, sessionId, ...modelArgs];
 
     if (ctx.environment && ctx.cwd) {
       const skills = await mountSkills(ctx.environment, ctx.cwd);
@@ -529,7 +540,7 @@ export default {
       // session id poisons every subsequent event re-delivery.
       if (isResume && /already in use|no conversation|no session/i.test(String(err.message))) {
         const freshId = randomUUID();
-        const retryBase = ['-p', fullPrompt, '--output-format', 'text', '--session-id', freshId];
+        const retryBase = ['-p', fullPrompt, '--output-format', 'text', '--session-id', freshId, ...modelArgs];
         const retry = await prepareArgv(retryBase, {
           ...ctx,
           mcpConfigPath: mcpConfig?.file || null,

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,452 @@
+/**
+ * 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';
+};
+
+// 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']);
+
+// ── 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).
+ *
+ * NOTE on `resetMs`: it is a SILENCE window, not a decay. It requires
+ * `resetMs` with ZERO agent-triggered turns in the pod. Three chatty seats
+ * never leave a ten-minute hole, so in a busy room the only live release is a
+ * human turn. Say so plainly rather than letting "or the streak decays" imply
+ * a timer that will save you.
+ *
+ * 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,
+  addressedGrace = 2,
+  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, eventType) {
+      if (trigger !== 'agent') return { allowed: true, streak: 0, addressed: false };
+      const s = stateFor(podId);
+      // Being NAMED outranks a mechanical brake — the same judgement the claim
+      // path already makes forty lines down in agent.js. Without this, a peer
+      // can @mention a capped seat and get silence, with no signal to either
+      // side that anything was suppressed. Observed 2026-08-18: one seat took
+      // 51 wakes and 28 consecutive cap refusals, five of them chat.mention,
+      // and answered none of them.
+      //
+      // A GRACE, not an exemption: an unbounded pass would restore the exact
+      // A-mentions-B-mentions-A echo this governor exists to kill. Addressed
+      // turns still count toward the streak, so a mention loop terminates at
+      // cap + addressedGrace instead of never.
+      const addressed = ADDRESSED_EVENT_TYPES.has(eventType);
+      const limit = addressed ? cap + addressedGrace : cap;
+      return { allowed: s.streak < limit, streak: s.streak, addressed };
+    },
+    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 ──────────────────────────────────────────────────────────
+
+
+// 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/environment.js

@@ -29,8 +29,19 @@ import { homedir } from 'os';
 // exposes `$HOME` layout for zero server-side benefit. Callers pass
 // `envFileDir` as a separate argument to resolveWorkspace / mountSkills.
 
+// `model` closes issue #774. Before it, the only way to pin a wrapper's model
+// was `ANTHROPIC_MODEL` exported at `commonly agent run` time — per-process,
+// never persisted, and silently dropped by any restart. Measured consequence on
+// 2026-08-16: six of nine live seats had lost their assigned model, including
+// ux-lead, which was supposed to be on Fable and had been running the CLI
+// default for days with nothing recording the drift.
+//
+// Putting it in the env spec makes the model a persisted, server-side fact that
+// survives restarts and is readable by the platform — which is what ADR-022's
+// "persona and runtime are chosen separately" requires to mean anything for a
+// BYO seat, and what lets an identity card answer "what is this running".
 const ALLOWED_TOP_KEYS = new Set([
-  'version', 'workspace', 'sandbox', 'skills', 'mcp',
+  'version', 'workspace', 'sandbox', 'skills', 'mcp', 'model',
 ]);
 const ALLOWED_SANDBOX_MODES = new Set([
   'none', 'workspace', 'read-only', 'bwrap', 'firejail', 'container', 'managed',
@@ -112,6 +123,18 @@ export const validateEnvironmentSpec = (spec) => {
     errors.push(`version must be 1, got ${JSON.stringify(spec.version)}`);
   }
 
+  // Validated as an opaque non-empty string, deliberately not against a list of
+  // known model ids. A whitelist here would need editing every time a provider
+  // ships a model, and would reject a valid id the local CLI understands and
+  // this file does not — failing the user's attach for a fact it is not the
+  // authority on. The adapter passes it through to `--model`; the CLI is the
+  // thing that knows what is valid, and its error is the honest one.
+  if (spec.model !== undefined) {
+    if (typeof spec.model !== 'string' || spec.model.trim() === '') {
+      errors.push('model must be a non-empty string');
+    }
+  }
+
   if (spec.workspace !== undefined) {
     if (typeof spec.workspace !== 'object' || spec.workspace === null) {
       errors.push('workspace must be an object');

package/src/lib/spawn-retry.js

@@ -19,11 +19,37 @@ export const SPAWN_CIRCUIT_THRESHOLD = 3;
 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;
+// This list is a per-provider allowlist, and it only ever grows after an
+// outage has already been misclassified. Twice now:
+//   2026-08-03  codex  "Your workspace is out of credits."   → `out of credits`
+//   2026-08-18  claude "You've hit your session limit"       → `session limit`
+// The second one is the instructive failure: `usage limit` was already here —
+// it is Claude's OTHER exhaustion wording — so the fleet stalled for an hour on
+// a string one word away from a pattern we had. Both times the miss meant
+// RUNTIME, the weakest class with the shortest backoff, against a provider that
+// was not going to answer for hours.
+//
+// What a miss costs, measured against these constants (intervalMs 5000,
+// jitter 0; `*` = circuit open):
+//
+//   quota          n=1,2,3 ->  900s*  900s*  900s*
+//   configuration  n=1,2,3 ->  900s*  900s*  900s*
+//   rate_limit     n=1,2,3 ->   60s*  120s*  240s*
+//   runtime        n=1,2,3 ->    5s     10s    60s*
+//
+// So an unmatched wording is not one class off — it is 180x faster on the
+// first retry than the class it belonged in, and the only class that does not
+// open the circuit at n=1. That is the price of a missing string, and it is
+// why the entry below is a list of exact wordings rather than a loose pattern.
+//
+// Note RUNTIME is also `classifySpawnFailure`'s fallthrough, so "unrecognised"
+// and "transient local fault" resolve to the same, most aggressive schedule.
+// That is a structural issue rather than a vocabulary one — see #996.
+//
+// Deliberately NOT loosened to a bare `limit`: QUOTA is tested before
+// RATE_LIMIT, so that would swallow every "rate limit" error into the 15-minute
+// cooldown. Add exact wordings, not looser ones.
+const QUOTA_RE = /(?:quota|usage limit|session 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;