@cohortapp/agent-sdk 2.18.14 → 2.18.15

package/lib/telemetry/alerts.mjs

@@ -19,6 +19,10 @@
  *   - subAgentsRunning over the cap      → INFO (more children than expected).
  *   - machine.sessionNote present        → WARNING/CRITICAL (frontdoor) — the
  *                                          seat's front door is not answering.
+ *   - machine.upgrade.failStreak >= N    → WARNING/CRITICAL (rollout) — N
+ *                                          consecutive attempts to reach
+ *                                          @latest have failed; the seat is
+ *                                          stranded on old code.
  *
  * Output: a deterministic array `[{ id, severity, kind, detail }, ...]` (the
  * snapshot's alert shape) sorted critical→warning→info then by id, so identical
@@ -90,6 +94,30 @@ export const DEFAULT_THRESHOLDS = Object.freeze({
     warnMs: 15 * 60 * 1000,
     critMs: 2 * 60 * 60 * 1000,
   }),
+  /**
+   * How many CONSECUTIVE failed attempts to reach @latest make a seat STUCK.
+   *
+   * `warnStreak` 3, not 1: one failure is a bad release or a slow mirror and
+   * the hourly job is entitled to try again; the failed-target hold already
+   * spaces those out. Three separate, completed attempts have failed, which
+   * means every fix the seat can apply to itself has been applied three times
+   * and the seat is still where it was.
+   *
+   * `critStreak` 6: past this the seat has been refusing @latest for the best
+   * part of a week under the default 24 h hold — which is exactly how long
+   * three seats sat on 2.17.0 while every hourly log line was individually
+   * correct. A release that cannot reach a colleague is not a machine problem
+   * that resolves itself; it waits for a person, like a scope fault.
+   */
+  upgradeStuck: Object.freeze({
+    // THE ONE DEFINITION of the stuck threshold. scripts/fleet/rollout.mjs
+    // imports `warnStreak` as its STUCK_STREAK rather than restating it, and
+    // the shell copy (autoupdate.sh) is pinned against this value by a
+    // source-reading test — because three literals agreeing by comment is the
+    // prose-promise-instead-of-a-check pattern this repo bans.
+    warnStreak: 3,
+    critStreak: 6,
+  }),
   replyDebt: Object.freeze({
     // ONE withheld reply is already worth saying. This is not a resource gauge
     // where a low reading is normal noise — it counts people who asked this
@@ -175,6 +203,7 @@ export function deriveAlerts(status, thresholds, now = Date.now()) {
     push(alerts, frontDoorRule(machine, t.frontDoor, now));
     push(alerts, scopeFaultRule(machine));
     push(alerts, repliesWithheldRule(machine, t.replyDebt));
+    push(alerts, upgradeStuckRule(machine, t.upgradeStuck, now));
 
     alerts.sort((a, b) => {
       const r = (SEVERITY_RANK[a.severity] ?? 9) - (SEVERITY_RANK[b.severity] ?? 9);
@@ -282,6 +311,71 @@ function repliesWithheldRule(machine, cfg = {}) {
   };
 }
 
+/**
+ * THIS SEAT CANNOT GET TO @latest, AND HAS PROVED IT N TIMES.
+ *
+ * Every other rule in this file reads a gauge. This one reads a COUNT of
+ * completed failures, because the failure it names has no gauge: on 2026-09-25
+ * three seats were found sitting on 2.17.0 while the fleet ran 2.18.13, and
+ * nothing anywhere was in an error state. The launchd job fired hourly, npm
+ * answered, the install ran, the health gate did its job, the rollback worked,
+ * `last.json` recorded the outcome honestly and the beat carried it. Each hour
+ * was a correct, self-contained failure — and the org has no way to see the
+ * difference between the first one and the fortieth, which is the only thing
+ * that distinguishes "a release is settling" from "a colleague is stranded on
+ * code from three weeks ago and will never leave it unaided".
+ *
+ * WHY THIS RIDES THE EXISTING BEAT AND NOTHING ELSE. The seats this rule is
+ * about are, by construction, running the OLDEST code in the fleet — so any
+ * new channel it might use is the one channel they do not have. `machine.upgrade`
+ * is a field their beat already carries; the count is added to it, and this
+ * rule turns it into an alert on the seats new enough to run this file.
+ *
+ * FOR THE ONES THAT ARE NOT, THIS RULE IS STRUCTURALLY BLIND AND SAYING SO IS
+ * PART OF THE DESIGN. A seat too stale to install the SDK runs a collector that
+ * never writes `failStreak` and an alerts file that has never heard of this
+ * rule — so the alert cannot reach exactly the seats it was written for. The
+ * fleet-side derivation covers them from outside: `seatStuck()` in
+ * scripts/fleet/rollout.mjs reads the same fact out of a 2.17-era beat, and
+ * `propagationOutcome()` there returns reason `"stuck"` so that stage 3 of
+ * every publish exits non-zero and names the machine. That path is automatic
+ * because publishing is; nobody has to decide to go looking.
+ *
+ * Both answer (d) the same way: a streak counts ATTEMPTS, and a seat that has
+ * not been asked has made none.
+ *
+ * DISTINCT FROM DRIFT. A `stranded` seat (framework paths pinned in
+ * `.maestroignore`, `machine.stranded`) cannot RECEIVE parts of a release it
+ * did install; a STUCK seat never installs the release at all. Different
+ * cause, different fix, different alert id — they can be true at once.
+ */
+function upgradeStuckRule(machine, cfg = {}, now = Date.now()) {
+  const u = machine && machine.upgrade;
+  if (!u || typeof u !== "object") return null;
+  // Strict: the producer (autoupdate.sh via collect.upgradeSummary) writes an
+  // integer, and both validate it. A string here means something else wrote
+  // this record, and a rule that coerces would be reporting on a shape it does
+  // not understand.
+  const n = Number.isInteger(u.failStreak) ? u.failStreak : 0;
+  if (!(n > 0)) return null;
+  const sev = severityFor(n, num(cfg.warnStreak, Infinity), num(cfg.critStreak, Infinity));
+  if (!sev) return null;
+  const target = typeof u.streakTarget === "string" && u.streakTarget ? u.streakTarget : (typeof u.to === "string" ? u.to : "@latest");
+  // A DURATION, not only a tally: four attempts since Monday and four attempts
+  // in the last hour are different seats with different urgency, and the count
+  // alone cannot tell them apart.
+  const sinceMs = typeof u.stuckSince === "string" ? Date.parse(u.stuckSince) : NaN;
+  const days = Number.isFinite(sinceMs) ? Math.floor((now - sinceMs) / 86400000) : null;
+  const forHow = days === null ? "" : days >= 1 ? ` over ${days} ${days === 1 ? "day" : "days"}` : " today";
+  const why = typeof u.reason === "string" && u.reason ? ` Last failure: ${u.reason.split(":")[0]}.` : "";
+  return {
+    id: "upgrade_stuck",
+    severity: sev,
+    kind: "rollout",
+    detail: `${n} consecutive upgrade attempts to ${target} have failed${forHow} — this seat is running ${typeof u.from === "string" && u.from ? u.from : "older code"} and will not arrive on its own.${why} It needs a person at the machine.`,
+  };
+}
+
 function subAgentsRule(status, cfg = {}) {
   const v = num(status.subAgentsRunning);
   const cap = num(cfg.infoCap, Infinity);

package/lib/telemetry/collect.mjs

@@ -84,8 +84,14 @@
  *       // Also on `machine` (open record), so hq's fleet view can show it next
  *       // to sdkVersion without a schema change. `ok` is the attempt's verdict:
  *       // true = healthy on `to`; false = install failed or rolled back to `from`.
+ *       // `failStreak` is the one field here that describes a PATTERN: N
+ *       // consecutive failed attempts to reach @latest, since `stuckSince`,
+ *       // against `streakTarget`. Absent below 1. A seat that has simply not
+ *       // been asked (nothing newer published, or held after its last failure)
+ *       // never accrues one — see autoupdate.sh's write_last.
  *       upgrade?: { at: ISO8601, from: string, to: string, ok: boolean,
- *                   reason?: string, healthy?: boolean },  // reason: WHY a failure failed
+ *                   reason?: string, healthy?: boolean,     // reason: WHY a failure failed
+ *                   failStreak?: number, stuckSince?: ISO8601, streakTarget?: string },
  *       // THE BEATING DAEMON — which process is emitting this beat, what code
  *       // it is actually running, and the last health-gate verdict on it.
  *       // Also on `machine` (open record). `sdkVersion` ABOVE is what is
@@ -1395,7 +1401,9 @@ export function sessionNote(a = {}) {
  * fields the fleet view reads; anything malformed → null, and the field drops
  * out rather than lying.
  * @param {object|null} last
- * @returns {{at:string, from:string, to:string, ok:boolean}|null}
+ * @returns {{at:string, from:string, to:string, ok:boolean, reason?:string,
+ *            healthy?:boolean, failStreak?:number, stuckSince?:string,
+ *            streakTarget?:string}|null}
  */
 export function upgradeSummary(last) {
   if (!last || typeof last !== "object") return null;
@@ -1413,6 +1421,19 @@ export function upgradeSummary(last) {
   // Bounded on the way out: a reason is a short token plus at most a trimmed
   // error line, and the beat is not a log shipper.
   const reason = typeof last.reason === "string" ? last.reason.trim().slice(0, 300) : "";
+  // `failStreak` — how many CONSECUTIVE upgrade attempts have failed, with the
+  // instant the run of failures began and the version it is failing against.
+  // Written by autoupdate.sh's write_last; see the long block above it for what
+  // does and does not count as an attempt. This is the ONLY field here that is
+  // about a pattern rather than an event, and it is the reason three seats sat
+  // on 2.17.0 for days without anything saying so: every individual record was
+  // a truthful `ok:false` that told a reader nothing about the fortieth one.
+  //
+  // Absent when zero, so a healthy seat's beat carries nothing extra and a
+  // reader can treat presence as the finding.
+  const failStreak = Number.isInteger(last.failStreak) && last.failStreak > 0 ? last.failStreak : 0;
+  const stuckSince = typeof last.stuckSince === "string" && !Number.isNaN(Date.parse(last.stuckSince)) ? last.stuckSince : "";
+  const streakTarget = typeof last.streakTarget === "string" ? last.streakTarget.trim().slice(0, 40) : "";
   return {
     at,
     from: typeof last.from === "string" ? last.from : "",
@@ -1420,6 +1441,9 @@ export function upgradeSummary(last) {
     ok: last.ok === true,
     ...(reason ? { reason } : {}),
     ...(typeof last.healthy === "boolean" ? { healthy: last.healthy } : {}),
+    ...(failStreak ? { failStreak } : {}),
+    ...(failStreak && stuckSince ? { stuckSince } : {}),
+    ...(failStreak && streakTarget ? { streakTarget } : {}),
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cohortapp/agent-sdk",
-  "version": "2.18.14",
+  "version": "2.18.15",
   "description": "Cohort Agent SDK — autonomous AI colleague runtime. Deploy senior AI colleagues on dedicated Mac minis, wired to the Cohort operating surface.",
   "type": "module",
   "bin": {

package/scripts/daemon/agent-daemon.mjs

@@ -67,6 +67,7 @@ import { classifyItem, isDirectedAtAgent } from "./classifier.mjs";
 // gets a deterministic classification (no LLM triage), no holding ack, and a
 // per-seat jitter so thirteen answers do not land in the same second.
 import { isRollCallItem, rollCallJitterMs } from "../../lib/org/inbound/broadcast.mjs";
+import { stampFirstReplyPlan } from "../../lib/assurance/first-reply.mjs";
 import { isRoomSurface } from "../../lib/org/inbound/surfaces.mjs";
 import { isMembershipReason } from "../../lib/org/inbound/directedness.mjs";
 import { cohortSurfaceOf, cohortSurfaceLabel, cohortSurfaceIsDeclared } from "./deliver.mjs";
@@ -96,7 +97,7 @@ import {
   isPidAlive,
 } from "./assurance.mjs";
 import { recordPoll, recordClassification, recordSession, writeHealthDashboard } from "./health.mjs";
-import { acquireLock, releaseLock, updateLock, scanStaleLocks, acquireThreadLock, claimRequest, hasActiveClaim, sweepStaleItemClaims, sanitiseItemId } from "./session-lock.mjs";
+import { acquireLock, releaseLock, updateLock, scanStaleLocks, acquireThreadLock, threadLockKey, claimRequest, hasActiveClaim, sweepStaleItemClaims, sanitiseItemId } from "./session-lock.mjs";
 import { markDeferred } from "./inbox-deferral.mjs";
 import { parseQueueItems, rankBacklog, resolveBacklogWeights } from "../../lib/backlog.mjs";
 import { readLatestGaps } from "../../lib/goals/gaps.mjs";
@@ -322,10 +323,23 @@ async function reviveFrontDoorIfShut(state, deps = {}) {
   return verdict;
 }
 
-async function pollService(svc) {
+/**
+ * Drain one service's inbox: poll, dedup, stamp the flurry plan, process.
+ *
+ * @param {{name:string, fn:Function}} svc
+ * @param {object} [deps] TEST-ONLY seams; PRODUCTION PASSES NOTHING, so the
+ *   defaults are the real collaborators and behaviour is byte-identical. The
+ *   same idiom as `processItem`/`sweepBacklog` above. Exported (and seamed) so
+ *   the ONE-FIRST-REPLY-PER-FLURRY stamping has a test that fails when the call
+ *   is removed — see `notice-emission.test.mjs`.
+ *   @param {object} [deps.frontDoorGate] override the front-door gate
+ *   @param {Function} [deps.processItem] override processItem
+ */
+export async function pollService(svc, deps = {}) {
+  const processItemImpl = deps.processItem || processItem;
   try {
     // Front door: a live main session owns this service's inbox — leave it.
-    const fd = _frontDoorGate.check(svc.name);
+    const fd = (deps.frontDoorGate || _frontDoorGate).check(svc.name);
     if (fd.changed) console.log(`[daemon] front door for ${svc.name}: ${fd.dispatch ? "daemon dispatches" : "main session owns intake"} (${fd.reason})`);
     if (!fd.dispatch) return 0;
     const result = await svc.fn();
@@ -358,8 +372,33 @@ async function pollService(svc) {
       return lock.acquired;
     });
 
+    // ── ONE FIRST REPLY PER FLURRY ───────────────────────────────────────
+    // "If there's a flurry of 4 messages in one go by others, instead of having
+    // a generic reply per message, it would be responding to the batch of
+    // messages." (owner, 2026-09-25.) The batch is computed HERE, over the whole
+    // poll, because this is the only place that sees more than one item at a
+    // time — `processItem` is called per item and structurally cannot know it is
+    // the third of four. Every non-leader carries `covered_by_batch`, which
+    // `assurance.shouldAcknowledge` turns into `ack:false` and the daemon makes
+    // durable as `interimForbidden`, so no later sweep in any process speaks for
+    // it either. The leader is told how many it stands for, so the one line it
+    // writes can answer all of them.
+    //
+    // WORK IS UNAFFECTED. Every item still gets its own `processItem`, its own
+    // obligation and its own answer; what is batched is only the FIRST thing
+    // said. Silence about timing is not silence about outcome.
+    //
+    // The stamping itself is `assurance/first-reply.stampFirstReplyPlan`, not
+    // four lines here, because four lines here had NO TEST THAT COULD SEE THEM:
+    // the only call site was inside this module-internal function, so deleting
+    // them left the whole suite green — including a test named "wired, not just
+    // available". `first-reply.test.mjs` now exercises the stamp and
+    // `notice-emission.test.mjs` drives THIS function through `pollService`'s
+    // injected seams, so removing the call is red in both.
+    stampFirstReplyPlan(newItems);
+
     for (const item of newItems) {
-      await processItem(item, svc.name);
+      await processItemImpl(item, svc.name);
     }
 
     if (result.errors.length > 0) {
@@ -1107,7 +1146,38 @@ export async function answerItem(item, service, itemId, trace_id, deps = {}, rou
     // This check runs BEFORE quick reply to prevent ALL duplicate responses.
     {
       const channel = item.channel_id || (item.raw_ref ? item.raw_ref.match(/slack:([^:]+):/)?.[1] : null) || item.channel;
-      const threadTs = item.thread_id || (isDm ? `dm-channel` : null);
+      // THE UNTREADED CHANNEL POST USED TO TAKE NO LOCK AT ALL.
+      //
+      // `item.thread_id || (isDm ? "dm-channel" : null)` is null for exactly
+      // one shape: a message posted to the main surface of a channel or group,
+      // not in a thread, not a DM. That is the shape the owner screenshotted —
+      // a flurry of messages into a room — and it was the one shape with no
+      // dedup: each message cleared this block, spawned its own session, and
+      // opened its own obligation, so the room got N sessions and N chances at
+      // a holding line for one conversation.
+      //
+      // `channel-main` is the DM lock's counterpart for that surface: one
+      // session at a time on a room's main feed, the rest deferred and
+      // promoted at session close exactly like a DM burst.
+      //
+      // THIS IS ONLY SAFE BECAUSE OF THE BUNDLING FIX BESIDE IT. Deferral ends
+      // in `promoteDeferred`, which collapses a group to its latest member and
+      // marks the rest `.processed-bundled`. On a shared channel the deferred
+      // set is several PEOPLE, not one person's flurry, so an unconditional
+      // collapse here would silently bin a colleague's question — which is why
+      // inbox-deferral.mjs now splits a group by sender unless the winner
+      // actually carries the room's history. Widening this lock without that
+      // change would trade a message storm for lost messages.
+      //
+      // The off-switch is real and deliberate: MAESTRO_CHANNEL_MAIN_LOCK=0
+      // restores the previous behaviour on a seat without a code change, in
+      // the same style as every other threshold in the assurance stack.
+      const threadTs = threadLockKey({
+        channel,
+        threadId: item.thread_id,
+        isDm,
+        channelMainLock: String(process.env.MAESTRO_CHANNEL_MAIN_LOCK ?? "1") !== "0",
+      });
       if (threadTs && channel) {
         const threadCheck = acquireThreadLock(channel, threadTs);
         if (!threadCheck.allowed) {