@commonlyai/cli 0.1.10 → 0.1.13

package/package.json

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

package/src/commands/agent.js

@@ -41,6 +41,8 @@ import {
 } from '../lib/spawn-retry.js';
 import {
   ADDRESSED_EVENT_TYPES,
+  CASCADE_DEFAULTS,
+  CASCADE_ENV_VARS,
   CLAIMABLE_EVENT_TYPES,
   classifyTrigger,
   createCascadeGovernor,
@@ -48,6 +50,7 @@ import {
   createClaimKeeper,
   deliverChatReply,
   peerHoldsFrame,
+  resolveCascadeSettings,
 } from '../lib/enforcement.js';
 
 // ── Token file I/O — ~/.commonly/tokens/<name>.json (ADR-005) ───────────────
@@ -709,9 +712,12 @@ export const performRun = ({
   clearIntervalImpl = clearInterval,
   retryJitterRatio,
   claimLeaseSeconds = 90,
-  cascadeCap = 3,
-  cascadeAddressedGrace = 2,
-  cascadeResetMs = 10 * 60 * 1000,
+  // Undefined means "not overridden" — resolveCascadeSettings falls back to
+  // the env var, then to the shipped default. Passing a value here still
+  // wins, which is how the tests pin a cap of 1.
+  cascadeCap,
+  cascadeAddressedGrace,
+  cascadeResetMs,
   chatCharLimit = 400,
   maxChatChunks = 3,
   claimYieldDelayMs = 3000,
@@ -730,11 +736,27 @@ 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,
-    addressedGrace: cascadeAddressedGrace,
-    resetMs: cascadeResetMs,
+  const cascadeSettings = resolveCascadeSettings({
+    overrides: {
+      cap: cascadeCap,
+      addressedGrace: cascadeAddressedGrace,
+      resetMs: cascadeResetMs,
+    },
+    warn: (message) => log(`cascade config: ${message}`),
   });
+  const cascadeGovernor = createCascadeGovernor(cascadeSettings);
+  // Unconditional, because the only other cascade line on this path is the
+  // warn callback above — which fires only when a value is BAD. Without this,
+  // a seat running COMMONLY_CASCADE_CAP=8 logs exactly what a seat on the
+  // shipped default logs, and an env var (unlike the source edit it replaces)
+  // leaves no git evidence of which seat diverged. The `(defaults)` marker
+  // makes "show me every retuned seat" a grep for its absence.
+  const cascadeIsDefault = Object.keys(CASCADE_DEFAULTS)
+    .every((key) => cascadeSettings[key] === CASCADE_DEFAULTS[key]);
+  log(
+    `cascade: cap=${cascadeSettings.cap} grace=${cascadeSettings.addressedGrace} `
+    + `reset=${cascadeSettings.resetMs}ms${cascadeIsDefault ? ' (defaults)' : ''}`,
+  );
   // Fairness: recent broadcast-race winners start the next race from the back.
   const claimHandicap = createClaimHandicap({ delayMs: claimYieldDelayMs });
 
@@ -803,15 +825,91 @@ 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);
+    // 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) {
+      // 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,
+      // an operator reading the log cannot tell which mentions were dropped, and
+      // the suppressed seat cannot say what it ignored — it never saw the id. Two
+      // real mentions were lost this way on 2026-08-19 and the seat they were
+      // addressed to could not enumerate them afterwards.
       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',
+        + (event?.payload?.messageId ? ` (dropped message ${event.payload.messageId})` : '')
+        + (admission.graceApplied ? ' (addressed grace also spent)' : '')
+        // NOT "until the pod goes quiet": other seats' traffic never touches
+        // this seat's clock, and a refusal returns here without reaching
+        // `record()` below — so the window is measured from this seat's last
+        // ADMITTED turn in this pod and runs regardless of how loud the room
+        // is. Saying "the pod goes quiet" told an operator to wait for a lull
+        // that is neither necessary nor sufficient (#989).
+        + ` — standing down until a human speaks or ${cascadeSettings.resetMs}ms `
+        + 'passes with no admitted turn from this seat in this pod',
       );
-      return { outcome: 'no_action', reason: 'cascade-cap' };
+      // `details` rides through to the AgentEvent row untouched:
+      // normalizeDeliveryMeta whitelists outcome/reason/messageId and passes
+      // `details` straight into `delivery.details`, typed Schema.Types.Mixed.
+      // So the settings that produced this refusal become queryable with NO
+      // backend change and no deploy.
+      //
+      // This is the half the boot log cannot cover. The log says what a seat
+      // resolved; it does not survive a restart, and nothing joins it to the
+      // refusals it caused. Once cap is per-seat and arbitrary, a refusal
+      // whose cap is unknown cannot be compared against one from another seat.
+      // `reason` deliberately stays the fixed literal 'cascade-cap' — :1111
+      // matches it with === and the run-loop tests assert it — so the value
+      // goes in a sibling field instead of being spelled into the reason.
+      return {
+        outcome: 'no_action',
+        reason: 'cascade-cap',
+        details: {
+          // The id of what was dropped. `reason` and `streak` say a refusal
+          // happened; only this says WHICH message never got answered, which is
+          // what anyone auditing a missed mention actually needs to join on.
+          messageId: event?.payload?.messageId || null,
+          streak: admission.streak,
+          cap: cascadeSettings.cap,
+          addressedGrace: cascadeSettings.addressedGrace,
+          resetMs: cascadeSettings.resetMs,
+          addressed: admission.addressed,
+          graceApplied: admission.graceApplied,
+        },
+      };
     }
 
     // ── ADR-018 enforcement: claim-before-act ───────────────────────────────
@@ -987,7 +1085,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
@@ -1343,6 +1468,23 @@ export const performDetach = async ({
  */
 const stamp = () => new Date().toISOString();
 
+/**
+ * Map `agent run`'s cascade flags onto resolveCascadeSettings' override keys.
+ *
+ * Exported because the mapping is where the flag path can go wrong invisibly:
+ * an earlier version coerced with Number() here, so `--cascade-cap abc`
+ * reached the resolver as NaN and the warning read `--cascade-cap='NaN'` —
+ * naming a value the user never typed, on the one line whose whole job is to
+ * tell them which input was bad. The values pass through RAW; the resolver is
+ * the only thing that parses, for the same reason it is the only thing that
+ * validates.
+ */
+export const cascadeOverridesFromOpts = (opts = {}) => ({
+  cascadeCap: opts.cascadeCap,
+  cascadeAddressedGrace: opts.cascadeGrace,
+  cascadeResetMs: opts.cascadeReset,
+});
+
 export const registerAgent = (program) => {
   const agent = program.command('agent').description('Manage agents');
 
@@ -1683,6 +1825,9 @@ Docs:
     .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')
+    .option('--cascade-cap <n>', `Consecutive agent-triggered turns allowed per pod (env ${CASCADE_ENV_VARS.cap}, default ${CASCADE_DEFAULTS.cap})`)
+    .option('--cascade-grace <n>', `Extra turns allowed when this seat was directly addressed; 0 disables the grace (env ${CASCADE_ENV_VARS.addressedGrace}, default ${CASCADE_DEFAULTS.addressedGrace})`)
+    .option('--cascade-reset <ms>', `Silence window that clears the streak (env ${CASCADE_ENV_VARS.resetMs}, default ${CASCADE_DEFAULTS.resetMs})`)
     .action(async (name, opts) => {
       let record = loadAgentToken(name);
       if (!record) {
@@ -1736,6 +1881,7 @@ Docs:
         environment: record.environment || null,
         workspacePath: record.workspacePath || null,
         intervalMs: parseInt(opts.interval, 10),
+        ...cascadeOverridesFromOpts(opts),
         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.

package/src/lib/enforcement.js

@@ -64,6 +64,99 @@ export const ADDRESSED_EVENT_TYPES = new Set(['chat.mention', 'thread.mention',
 
 // ── cascade governor ────────────────────────────────────────────────────────
 
+export const CASCADE_DEFAULTS = Object.freeze({
+  cap: 3,
+  addressedGrace: 2,
+  resetMs: 10 * 60 * 1000,
+});
+
+// Env names, exported so the CLI help text and the tests quote the same
+// strings rather than two copies that can drift apart.
+export const CASCADE_ENV_VARS = Object.freeze({
+  cap: 'COMMONLY_CASCADE_CAP',
+  addressedGrace: 'COMMONLY_CASCADE_ADDRESSED_GRACE',
+  resetMs: 'COMMONLY_CASCADE_RESET_MS',
+});
+
+// Flag spelling per key, for warning messages. A derived string
+// (key.replace(...)) would silently produce a flag that does not exist the
+// first time a key is renamed; this fails at the same moment the flag does.
+const CASCADE_FLAGS = {
+  cap: '--cascade-cap',
+  addressedGrace: '--cascade-grace',
+  resetMs: '--cascade-reset',
+};
+
+const CASCADE_BOUNDS = {
+  // 0 is meaningful, not a mistake: it refuses every agent-triggered turn in
+  // the pod, which is the "this room is on fire, mute the cascades" setting.
+  cap: { min: 0, max: 1000, integer: true },
+  // 0 restores the pre-#973 behaviour exactly. That is the point of the knob —
+  // the grace can be taken back on one seat, in one restart, without a revert
+  // and without a source edit.
+  addressedGrace: { min: 0, max: 1000, integer: true },
+  resetMs: { min: 1000, max: 24 * 60 * 60 * 1000, integer: true },
+};
+
+/**
+ * Resolve the three governor constants from (in precedence order) an explicit
+ * override, an environment variable, then the shipped default.
+ *
+ * These were literals in `run()`'s signature, reachable only by editing source
+ * — on a fleet whose CLI is a symlink into a live worktree, so "retune the
+ * cap" meant an edit plus a restart of every seat, with nothing recording
+ * which value ran. The sibling dampener one service over
+ * (AGENT_ASK_RATE_LIMIT_PER_HOUR) has always been env-tunable; this is
+ * copying that, not inventing it.
+ *
+ * An unparseable or out-of-range value warns and falls back rather than
+ * throwing. A seat that crash-loops on a typo'd env var is a worse outcome
+ * than one running the default — but a silent fallback would hide the typo,
+ * so it is loud.
+ *
+ * Overrides are validated on the SAME path as env values, deliberately. An
+ * earlier draft trusted them and passed them straight through, which made
+ * `--cascade-cap abc` resolve to NaN — and `streak < NaN` is false for every
+ * streak, so a typo at the command line would have silently refused every
+ * agent-triggered turn the seat ever saw. The louder source is not the safer
+ * one; there is one validator because there is one way to be wrong.
+ */
+export const resolveCascadeSettings = ({
+  env = process.env,
+  overrides = {},
+  warn = (msg) => console.warn(msg),
+} = {}) => {
+  const resolved = {};
+  for (const key of Object.keys(CASCADE_DEFAULTS)) {
+    const bounds = CASCADE_BOUNDS[key];
+    const fallback = CASCADE_DEFAULTS[key];
+    const override = overrides[key];
+    const hasOverride = override !== undefined && override !== null;
+    const raw = hasOverride ? override : env?.[CASCADE_ENV_VARS[key]];
+    // Names the source in the warning, so "which one did I get wrong" is
+    // answered by the message rather than by bisecting the launch command.
+    const label = hasOverride ? CASCADE_FLAGS[key] : CASCADE_ENV_VARS[key];
+
+    if (raw === undefined || raw === null || String(raw).trim() === '') {
+      resolved[key] = fallback;
+      continue;
+    }
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || (bounds.integer && !Number.isInteger(parsed))) {
+      warn(`${label}='${raw}' is not an integer — using ${fallback}`);
+      resolved[key] = fallback;
+      continue;
+    }
+    if (parsed < bounds.min || parsed > bounds.max) {
+      warn(`${label}=${parsed} is outside [${bounds.min}, ${bounds.max}] — using ${fallback}`);
+      resolved[key] = fallback;
+      continue;
+    }
+    resolved[key] = parsed;
+  }
+  return resolved;
+};
+
 /**
  * Per-pod damping of agent→agent retrigger chains.
  *
@@ -71,24 +164,42 @@ export const ADDRESSED_EVENT_TYPES = new Set(['chat.mention', 'thread.mention',
  * 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).
+ * the streak, or `resetMs` passes with no ADMITTED agent-triggered turn from
+ * this seat in this pod (so a damped seat 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, but the silence is far narrower
+ * than "the pod is quiet", and it is measured on two axes people get wrong in
+ * opposite directions:
+ *
+ *   WHOSE turns  — `pods` is a Map in this closure, inside ONE wrapper
+ *                  process. It never observes another seat's turns at all.
+ *                  Three chatty peers cannot keep this streak alive.
+ *   WHICH turns  — only turns that reached `record()`. A refusal returns from
+ *                  agent.js before it (`:859` vs `:1087`), so a capped seat
+ *                  stops updating `lastAgentTurnAt` entirely and its clock
+ *                  runs free from the last turn it was ALLOWED.
+ *
+ * Net shape is a token bucket, not a static ceiling: a burst of `cap`, then
+ * `cap` admits per `resetMs`, per pod. Sustained agent traffic with zero human
+ * turns yields 6/9/12/15/18/18/18/18 admits per hour as arrivals go from one
+ * per 600s to one per second — inert when quiet, pinned at cap-per-window
+ * however hard the burst gets. Per POD: a seat in N pods holds N buckets, so
+ * its seat-level ceiling is N times that.
  *
- * 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.
+ * An earlier version of this note said the window requires zero agent turns
+ * "in the pod", and concluded that in a busy room the only live release is a
+ * human turn. Both halves are wrong, and wrongly reassuring: a capped seat
+ * self-releases every window no matter how loud the room is.
  *
  * 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,
+  cap = CASCADE_DEFAULTS.cap,
+  addressedGrace = CASCADE_DEFAULTS.addressedGrace,
+  resetMs = CASCADE_DEFAULTS.resetMs,
   now = Date.now,
 } = {}) => {
   const pods = new Map(); // podId -> { streak, lastAgentTurnAt }
@@ -118,7 +229,18 @@ export const createCascadeGovernor = ({
       // 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 };
+      // `addressed` describes the EVENT; `graceApplied` describes what this
+      // governor actually did with it. They diverge whenever addressedGrace is
+      // 0 — the pre-#973 setting, and the first thing an operator dials back —
+      // where an addressed event is refused at the plain cap having been given
+      // nothing extra. Reporting only `addressed` made the refusal log claim a
+      // grace was "also spent" on a seat whose own boot line says grace=0.
+      return {
+        allowed: s.streak < limit,
+        streak: s.streak,
+        addressed,
+        graceApplied: addressed && addressedGrace > 0,
+      };
     },
     record(podId, trigger) {
       if (trigger === 'human') {