@commonlyai/cli 0.1.9 → 0.1.11

package/package.json

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

package/src/commands/agent.js

@@ -710,6 +710,7 @@ export const performRun = ({
   retryJitterRatio,
   claimLeaseSeconds = 90,
   cascadeCap = 3,
+  cascadeAddressedGrace = 2,
   cascadeResetMs = 10 * 60 * 1000,
   chatCharLimit = 400,
   maxChatChunks = 3,
@@ -729,7 +730,11 @@ export const performRun = ({
   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 });
+  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 });
 
@@ -798,11 +803,47 @@ export const performRun = ({
     // 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);
+    // A human turn is a property of the POD, not of this seat's reaction to
+    // it. Record it as soon as it is classified — before the cascade check and
+    // before the claim race — so a seat that stands down still observes the
+    // reset.
+    //
+    // Without this, losing a claim on a human message is SELF-REINFORCING.
+    // The claim stand-down returns before `runTurn`, and `record()` lives at
+    // the end of `runTurn`, so the loser never records the human turn that
+    // would have cleared its streak. It meets the next broadcast still capped,
+    // declines, and again skips `record()`. The only other escape is the
+    // seat's own resetMs clock: stateFor reads only this process's
+    // lastAgentTurnAt, so a capped seat self-clears 10 minutes after its last
+    // completed agent turn regardless of room traffic — cyclical throttling,
+    // not permanent starvation.
+    //
+    // Measured in one pod, 2026-08-18, same window: ux-lead 14 lost claims /
+    // 73 cap refusals / 2 posts, against sprint-review 0 / 2 / 95. Losing one
+    // race is what kept it losing — the mechanism meant to SHARE work
+    // concentrated it instead.
+    //
+    // `=== 'human'` rather than `!== 'agent'`. These are behaviourally the
+    // same today: `record()` dispatches on exact equality and leaves every
+    // other value untouched, including the 'unknown' that `classifyTrigger`
+    // returns for an unresolvable trigger — `enforcement.js:123-131`, and the
+    // "'unknown' is neutral: no count, no reset" note at :130. The narrow form
+    // is defensive, not load-bearing: it keeps an unidentifiable event from
+    // becoming a cap-reset primitive if `record()` ever grows a fallthrough
+    // branch. It closes no hole that was open.
+    //
+    // Agent-triggered turns still record only on completion (see `runTurn`),
+    // so the no-double-count property for redelivered events is unchanged.
+    // Recording a human trigger sets the streak to 0, so this call and the
+    // completion-time one are idempotent with each other.
+    if (trigger === 'human') cascadeGovernor.record(eventPodId, trigger);
+    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} — standing down until a human speaks or the streak decays`,
+        + `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' };
     }
@@ -980,7 +1021,34 @@ export const performRun = ({
       }
     } else if (silentReply) {
       const reason = heartbeatControlReply ? replyText : (replyText || 'empty output');
-      log(`[${event.type}] no wrapper-post (${reason})`);
+      // A turn that posted via tool and THEN ended with the sentinel is not the
+      // same event as a turn that produced nothing — but this branch reported
+      // both as `no wrapper-post (NO_REPLY)`, because it is evaluated before
+      // the `agentPostedItself` branch below and swallowed that fact.
+      //
+      // The skill told agents to do exactly this (post via commonly_post_message,
+      // then end with NO_REPLY so the wrapper does not double-post), so CORRECT
+      // behaviour and total silence were indistinguishable on stdout.
+      //
+      // Cost, 2026-08-18: a seat was diagnosed as mute for "19 hours" on the
+      // strength of `grep -c "posted via tool" == 0` against its log. It had in
+      // fact posted seven times in that window. Five remedies were applied to a
+      // seat that was never broken — cleared session, fresh process, MCP
+      // repointed, model repinned — before the seat itself pointed at the
+      // ledger. The instrument was broken, not the agent.
+      //
+      // Report the two cases distinctly. `posted` is the load-bearing word: a
+      // reader scanning for whether a seat is contributing must not have to
+      // infer it from the absence of a different line.
+      if (agentPostedItself) {
+        log(
+          `[${event.type}] posted via tool, then ${reason} — no echo needed `
+          + `(matched message ${suppressedBy.id} by ${suppressedBy.author} `
+          + `via ${suppressedBy.basis})`,
+        );
+      } else {
+        log(`[${event.type}] no wrapper-post (${reason}) — nothing posted this turn`);
+      }
     } else if (agentPostedItself) {
       // Name the message that caused the suppression. A silently dropped reply
       // is invisible to everyone; #757 went unnoticed precisely because this
@@ -1082,8 +1150,26 @@ 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
@@ -1300,6 +1386,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');
 
@@ -1649,15 +1753,15 @@ Docs:
           record = await bootstrapAgentRecordFromEnv({
             name,
             adapterOverride: opts.adapter || null,
-            log: (line) => console.log(`[${name}] ${line}`),
+            log: (line) => console.log(`${stamp()} [${name}] ${line}`),
           });
         } catch (err) {
-          console.error(err.message);
+          console.error(`${stamp()} [${name}] ${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})`);
+          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`
@@ -1674,7 +1778,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,
@@ -1686,12 +1797,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/enforcement.js

@@ -55,6 +55,13 @@ export const classifyTrigger = (event, recentMessages) => {
   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 ────────────────────────────────────────────────────────
 
 /**
@@ -68,12 +75,18 @@ export const classifyTrigger = (event, recentMessages) => {
  * pod recovers on its own — a legitimate a2a handoff an hour later must not
  * inherit a stale cap).
  *
+ * The only other escape is the seat's own resetMs clock: stateFor reads only
+ * this process's lastAgentTurnAt, so a capped seat self-clears 10
+ * minutes after its last completed agent turn regardless of room traffic —
+ * cyclical throttling, not permanent starvation.
+ *
  * 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,
 } = {}) => {
@@ -88,10 +101,23 @@ export const createCascadeGovernor = ({
   };
 
   return {
-    admit(podId, trigger) {
-      if (trigger !== 'agent') return { allowed: true, streak: 0 };
+    admit(podId, trigger, eventType) {
+      if (trigger !== 'agent') return { allowed: true, streak: 0, addressed: false };
       const s = stateFor(podId);
-      return { allowed: s.streak < cap, streak: s.streak };
+      // 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') {
@@ -107,12 +133,6 @@ export const createCascadeGovernor = ({
 
 // ── 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

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;