@commonlyai/cli 0.1.13 → 0.1.18

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@commonlyai/cli",
-  "version": "0.1.13",
+  "version": "0.1.18",
   "license": "Apache-2.0",
-  "description": "The Commonly CLI — connect agents, manage pods, iterate fast",
+  "description": "The Commonly CLI \u2014 connect agents, manage pods, iterate fast",
   "type": "module",
   "main": "./src/index.js",
   "bin": {

package/src/commands/agent.js

@@ -29,6 +29,7 @@ import {
   recordHandledEvent,
 } from '../lib/session-store.js';
 import { readLongTerm, syncBack } from '../lib/memory-bridge.js';
+import { pollRetryPolicy } from '../lib/poll-retry.js';
 import { detectMemorySources, composeImport, importMemory } from '../lib/memory-import.js';
 import { detectSkills, importSkills } from '../lib/skills-import.js';
 import { parseEnvironmentFile, resolveWorkspace } from '../lib/environment.js';
@@ -732,6 +733,7 @@ export const performRun = ({
   // reprovision-all; 5+ wastes rate-limit budget after the real-revoke case.
   let consecutiveAuthErrors = 0;
   const MAX_AUTH_ERRORS = 3;
+  let consecutivePollFailures = 0;
   let consecutiveSpawnFailures = 0;
   const spawnJitterRatio = retryJitterRatio ?? spawnRetryJitter(agentName);
   // Per-seat cascade state — lives with the process, like the session store.
@@ -859,7 +861,7 @@ export const performRun = ({
     // 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);
+    const admission = cascadeGovernor.admit(eventPodId, trigger, event.type, event.payload);
     if (!admission.allowed) {
       // Name the MESSAGE, not just the pod. Without this the refusal is silent at
       // three ends, not two: the mentioning agent gets no signal its mention died,
@@ -945,10 +947,20 @@ export const performRun = ({
       });
       const claim = await claimKeeper.acquire();
       if (!claim.claimed && !claim.failOpen) {
-        if (ADDRESSED_EVENT_TYPES.has(event.type)) {
+        // Per-event EVIDENCE, deliberately not a widening of
+        // ADDRESSED_EVENT_TYPES (that set is a pricing table): the backend
+        // stamps repliesToYourMessage when the woken message replies to or
+        // threads on a message THIS seat authored. Without it, a peer's
+        // claim on its own reply ordered the replied-to author out of its
+        // own conversation (Sage stood down twice on Anvil's thread
+        // replies, 2026-08-24). Interim for TASK-058.
+        const repliesToThisSeat = event.payload?.repliesToYourMessage === true;
+        if (ADDRESSED_EVENT_TYPES.has(event.type) || repliesToThisSeat) {
           log(
             `[${event.type}] message ${claimMessageId} held by ${claim.holder} — `
-            + 'proceeding peer-aware (this seat was directly addressed)',
+            + (repliesToThisSeat
+              ? 'proceeding peer-aware (the message replies to this seat\'s own message)'
+              : 'proceeding peer-aware (this seat was directly addressed)'),
           );
           peerFrame = peerHoldsFrame(claim.holder, claimMessageId);
           claimKeeper = null; // nothing held: no renewal, no release, no isLost gate
@@ -1171,10 +1183,32 @@ export const performRun = ({
     if (!running) return;
     let nextPollDelayMs = intervalMs;
     try {
+      // ONE event per fetch, because the fetch IS the claim.
+      //
+      // `AgentEventService.list()` does not hand back a preview — it marks
+      // every candidate `delivered` with `$inc: { attempts: 1 }` before
+      // returning. This loop then processes them SERIALLY, one full model
+      // turn each. So asking for 10 claims 10 and starts 1.
+      //
+      // The nine it cannot start are then reclaimed out from under it: the
+      // backend requeues `delivered` rows older than
+      // `requeueDeliveredMinutes` (default 10, swept on `*/10`), and turns
+      // routinely outlast that — measured on the pod-architect seat over
+      // 11.5h: median 128s, p90 669s, 13 turns over 600s, max 1153s. Each
+      // sweep returns the untouched siblings to `pending` at `attempts + 1`,
+      // and `attempts >= 3` retires an event to `failed`, which is terminal
+      // and invisible to `list()`. That cap exists to bound POISON events;
+      // over-claiming feeds it work no model ever saw, so a mention can be
+      // dropped without once being read.
+      //
+      // `limit: 1` costs nothing: capacity here is one turn at a time
+      // regardless, and the poll interval is 5s. It only stops the loop
+      // claiming work it has no way to begin.
       const { events = [] } = await client.get('/api/agents/runtime/events', {
-        agentName, instanceId, limit: 10,
+        agentName, instanceId, limit: 1,
       });
       consecutiveAuthErrors = 0;
+      consecutivePollFailures = 0;
       for (const event of events) {
         if (!running) break;
         let result;
@@ -1265,6 +1299,33 @@ export const performRun = ({
           running = false;
           return;
         }
+      } else {
+        // TASK-025: everything that is not an auth rejection used to fall
+        // through to `onError` with `nextPollDelayMs` still at `intervalMs`,
+        // because that variable is only reassigned in the spawn-retry branch
+        // above and a failed fetch never reaches it. So a network outage
+        // retried flat at the poll interval, forever, with one indistinct
+        // line per attempt — 797 consecutive `fetch failed` across three
+        // seats, ~66 minutes, and nothing that read as an outage.
+        //
+        // Deliberately NOT a stop. `MAX_AUTH_ERRORS` halts because a rejected
+        // token cannot heal itself; a network failure usually can, and a seat
+        // that stops on one is dead until a human notices.
+        consecutivePollFailures += 1;
+        const retry = pollRetryPolicy({
+          consecutiveFailures: consecutivePollFailures,
+          intervalMs,
+          jitterRatio: spawnJitterRatio,
+        });
+        nextPollDelayMs = retry.delayMs;
+        if (retry.escalate) {
+          log(
+            `poll failed ${consecutivePollFailures}x in a row `
+            + `(${err?.message || 'unknown error'}) — backing off to `
+            + `${formatRetryDelay(retry.delayMs)}`
+            + `${retry.atCeiling ? ', at the ceiling' : ''}`,
+          );
+        }
       }
       onError?.(err);
     }

package/src/lib/enforcement.js

@@ -45,6 +45,14 @@ export const CLAIMABLE_EVENT_TYPES = new Set([
  */
 export const classifyTrigger = (event, recentMessages) => {
   const p = event?.payload || {};
+  // The third pricing branch (#1044, fable 55845). Kernel-found work is not
+  // agent churn and must not price as it: counted as 'agent' it eats cascade
+  // budget exactly when the board is busiest; counted as 'human' it CLEARS the
+  // brake on unrelated cascades. 'kernel' is neutral like 'unknown' — no
+  // count, no reset — but chosen on purpose rather than fallen into, and the
+  // refusal/boot logs can say so. Checked before dmKind: triggerAuthor is the
+  // honest field (#1018) and wins where both appear.
+  if (p.triggerAuthor === 'kernel') return 'kernel';
   if (p.dmKind === 'agent-agent') return 'agent';
   if (p.dmKind === 'user-agent') return 'human';
   if (!p.messageId || !Array.isArray(recentMessages)) return 'unknown';
@@ -62,6 +70,19 @@ export const classifyTrigger = (event, recentMessages) => {
 // race is a free stand-down.
 export const ADDRESSED_EVENT_TYPES = new Set(['chat.mention', 'thread.mention', 'dm.message']);
 
+// These are the two event types the kernel's bot-to-bot mention dampener
+// bounds as one shared budget. Keep the wrapper out of that same loop's
+// admission path: named seats need to respond even when broadcasts have
+// exhausted their cascade budget. The backend cannot be a runtime import of
+// the published CLI, so cli/__tests__/mention-event-types.contract.test.mjs
+// imports both modules and pins the two lists together.
+//
+// Agent-DM wakes also arrive as chat.mention, but carry payload.dmKind. They
+// stay on this governor's bounded path: event type alone does not identify the
+// producer that owns the kernel mention budget. dm.message is legacy consumer
+// vocabulary and remains on that same ordinary addressed-grace path.
+export const MENTION_EVENT_TYPES = new Set(['chat.mention', 'thread.mention']);
+
 // ── cascade governor ────────────────────────────────────────────────────────
 
 export const CASCADE_DEFAULTS = Object.freeze({
@@ -213,9 +234,24 @@ export const createCascadeGovernor = ({
   };
 
   return {
-    admit(podId, trigger, eventType) {
+    admit(podId, trigger, eventType, payload = {}) {
       if (trigger !== 'agent') return { allowed: true, streak: 0, addressed: false };
       const s = stateFor(podId);
+      const addressed = ADDRESSED_EVENT_TYPES.has(eventType);
+      if (MENTION_EVENT_TYPES.has(eventType) && !payload?.dmKind) {
+        // Named mentions are bounded upstream by the kernel's shared
+        // bot-to-bot mention dampener. A DM emits chat.mention too, but its
+        // dmKind identifies a different producer, so it remains locally
+        // bounded. Every admitted turn still reaches record() after it
+        // completes, consuming broadcast liveness rather than creating an
+        // unmetered second loop.
+        return {
+          allowed: true,
+          streak: s.streak,
+          addressed,
+          graceApplied: false,
+        };
+      }
       // 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
@@ -223,11 +259,9 @@ export const createCascadeGovernor = ({
       // 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);
+      // Legacy direct-address events retain a GRACE, not an exemption. They
+      // still count toward the streak, so they terminate at cap +
+      // addressedGrace instead of never.
       const limit = addressed ? cap + addressedGrace : cap;
       // `addressed` describes the EVENT; `graceApplied` describes what this
       // governor actually did with it. They diverge whenever addressedGrace is
@@ -249,7 +283,8 @@ export const createCascadeGovernor = ({
         const s = stateFor(podId);
         pods.set(podId, { streak: s.streak + 1, lastAgentTurnAt: now() });
       }
-      // 'unknown' is neutral: no count, no reset.
+      // 'unknown' is neutral by FALLBACK; 'kernel' is neutral by DESIGN —
+      // both take this path, but only one of them is an accident.
     },
   };
 };

package/src/lib/poll-retry.js

@@ -0,0 +1,81 @@
+/**
+ * Retry policy for the run loop's own FETCH failures (TASK-025).
+ *
+ * `spawn-retry.js` bounds failures of the subprocess a poll produces. This
+ * bounds failures of the poll itself — the request to
+ * `/api/agents/runtime/events` that has to succeed before there is anything to
+ * spawn. They are different failures with different remedies and, until now,
+ * only one of them had a policy.
+ *
+ * The gap, measured: `agent run`'s tick set `nextPollDelayMs = intervalMs` and
+ * only ever reassigned it inside the spawn-retry branch. A fetch that threw
+ * never reached that branch, so a network failure retried at a flat 5s
+ * forever — no backoff, no ceiling, and no escalation. 797 consecutive
+ * `fetch failed` ran across three seats that way: ~66 minutes at 5s, and the
+ * only trace was one `onError` line per attempt in a log nobody was tailing.
+ *
+ * Two deliberate differences from the auth path directly above it:
+ *
+ * 1. NO STOP. `MAX_AUTH_ERRORS` halts the loop because a rejected token does
+ *    not heal on its own — retrying is pure cost and the operator must act.
+ *    A network failure is usually transient, and a seat that stops on one is
+ *    dead until someone notices. So this backs off and stays alive.
+ *
+ * 2. ESCALATION IS THE POINT. The harm in the measured outage was not the
+ *    retry rate, it was that 797 failures produced no signal distinguishable
+ *    from one failure. `escalate` fires on a small set of thresholds so a
+ *    sustained outage announces itself at widening intervals instead of
+ *    disappearing into per-attempt noise.
+ */
+
+// Same ceiling as the spawn path: past this, more waiting buys nothing and a
+// human is the only thing that resolves it.
+export const POLL_RETRY_MAX_MS = 15 * 60 * 1000;
+
+// Backoff starts only after the first failure has been retried once at the
+// normal interval, so a single blip costs nothing.
+export const POLL_BACKOFF_AFTER = 1;
+
+// Failure counts that emit a loud line. Chosen against the measured outage:
+// at intervalMs=5000 these land at roughly 15s, 1min, 5min, 20min and 1h of
+// sustained failure, so an operator reading the log sees the shape of the
+// outage rather than 797 identical lines.
+export const POLL_ESCALATE_AT = Object.freeze([3, 10, 30, 60, 120]);
+
+/**
+ * Next poll delay after a failed fetch, and whether this attempt should be
+ * announced loudly.
+ *
+ * Exponential from `intervalMs`, bounded by POLL_RETRY_MAX_MS. Jitter is the
+ * same anti-herd offset the spawn path uses — without it, every seat that lost
+ * the same upstream retries in lockstep and re-creates the thundering herd on
+ * recovery.
+ */
+export const pollRetryPolicy = ({
+  consecutiveFailures,
+  intervalMs,
+  jitterRatio = 0,
+}) => {
+  const safeIntervalMs = Number.isFinite(intervalMs) && intervalMs > 0 ? intervalMs : 5000;
+  const failureCount = Number.isInteger(consecutiveFailures) && consecutiveFailures > 0
+    ? consecutiveFailures
+    : 1;
+
+  const steps = Math.max(0, failureCount - POLL_BACKOFF_AFTER);
+  const raw = safeIntervalMs * (2 ** steps);
+  const bounded = Math.min(POLL_RETRY_MAX_MS, raw);
+
+  // Clamp rather than trust the caller: a jitterRatio above the cap would
+  // widen the herd window instead of narrowing it.
+  const safeJitter = Number.isFinite(jitterRatio)
+    ? Math.min(0.2, Math.max(0, jitterRatio))
+    : 0;
+
+  return {
+    delayMs: Math.round(bounded * (1 + safeJitter)),
+    escalate: POLL_ESCALATE_AT.includes(failureCount),
+    atCeiling: bounded >= POLL_RETRY_MAX_MS,
+  };
+};
+
+export default pollRetryPolicy;