@cohortapp/agent-sdk 2.18.37 → 2.19.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. package/bin/maestro.mjs +10 -1
  2. package/docs/guides/billing-console-keys.md +16 -3
  3. package/lib/assurance/first-reply.mjs +31 -2
  4. package/lib/assurance/operator-plane-store.mjs +164 -0
  5. package/lib/assurance/operator-plane.mjs +689 -0
  6. package/lib/budget-guard.mjs +93 -3
  7. package/lib/cli/attention.mjs +300 -0
  8. package/lib/cli/seat-auth.mjs +86 -6
  9. package/lib/comms/receipts.mjs +15 -3
  10. package/lib/comms/send-gate.mjs +329 -2
  11. package/lib/org/awareness.mjs +15 -2
  12. package/lib/org/clause-match.mjs +470 -0
  13. package/lib/org/client.mjs +27 -1
  14. package/lib/org/escalation-chain.mjs +134 -0
  15. package/lib/org/first-run.mjs +263 -0
  16. package/lib/org/genesis-contract.mjs +271 -0
  17. package/lib/org/governance-runtime.mjs +409 -0
  18. package/lib/org/governance-store.mjs +238 -0
  19. package/lib/org/governance.mjs +326 -0
  20. package/lib/org/mesh.mjs +135 -0
  21. package/lib/org/protocol.checksum +1 -1
  22. package/lib/org/protocol.mjs +6 -0
  23. package/lib/org/registry.mjs +7 -1
  24. package/lib/org/tool-surface.mjs +28 -0
  25. package/lib/setup/enroll-from-cohort.mjs +11 -0
  26. package/lib/telemetry/alerts.mjs +86 -1
  27. package/lib/telemetry/collect.mjs +237 -1
  28. package/package.json +1 -1
  29. package/scripts/daemon/agent-daemon.mjs +41 -2
  30. package/scripts/daemon/assurance.mjs +482 -55
  31. package/scripts/daemon/cadence-consumer.mjs +17 -0
  32. package/scripts/daemon/context-compiler.mjs +25 -0
  33. package/scripts/daemon/deliver.mjs +71 -5
  34. package/scripts/fleet/closing-sweep.mjs +266 -0
  35. package/scripts/healthcheck.sh +35 -0
  36. package/scripts/local-triggers/autoupdate.sh +61 -5
  37. package/scripts/maintenance/check-stamp-freshness.mjs +314 -0
  38. package/scripts/org/send-orgmail.mjs +112 -25
  39. package/scripts/session/supervisor.mjs +14 -0
@@ -19,6 +19,10 @@
19
19
  * - subAgentsRunning over the cap → INFO (more children than expected).
20
20
  * - machine.sessionNote present → WARNING/CRITICAL (frontdoor) — the
21
21
  * seat's front door is not answering.
22
+ * - machine.wedge present → WARNING/CRITICAL (wedge) — the
23
+ * seat's front door is BEATING but not
24
+ * READING (risk-2026-09-25-03):
25
+ * presence alone reads idle/healthy.
22
26
  * - machine.upgrade.failStreak >= N → WARNING/CRITICAL (rollout) — N
23
27
  * consecutive attempts to reach
24
28
  * @latest have failed; the seat is
@@ -40,6 +44,11 @@
40
44
 
41
45
  "use strict";
42
46
 
47
+ // The operator plane's verdict is computed by the pure reader, beside the join it
48
+ // reasons over — so the rule table here does not acquire a second opinion about
49
+ // what an unrecoverable dead ask is.
50
+ import { planeAlert } from "../assurance/operator-plane.mjs";
51
+
43
52
  /**
44
53
  * Built-in thresholds for the status-snapshot health rules. Mirrors the
45
54
  * lib/diagnostics/alerts.mjs DEFAULT_THRESHOLDS style; an operator override merges
@@ -94,6 +103,34 @@ export const DEFAULT_THRESHOLDS = Object.freeze({
94
103
  warnMs: 15 * 60 * 1000,
95
104
  critMs: 2 * 60 * 60 * 1000,
96
105
  }),
106
+ /**
107
+ * How long the seat's front door may be WEDGED — beating, but not reading
108
+ * its inbound (`machine.wedge`, `lib/telemetry/collect.sessionWedge`) —
109
+ * before the fleet is told. `frontDoor` above catches a door that stopped
110
+ * beating; this catches the inverse the same episode exposed
111
+ * (risk-2026-09-25-03, A029 2026-09-25): claudeAuth ok, state=idle,
112
+ * lastSeenMs fresh, and the seat could not read a message sent 23 minutes
113
+ * earlier. Presence alone cannot tell the two apart — this rule is the
114
+ * difference.
115
+ *
116
+ * `warnMs` 0: unlike `frontDoor`, `sessionWedge` does not fire on a single
117
+ * bad read — it already requires a handoff to be overdue past its OWN
118
+ * deadline (`DEFAULT_HANDOFF_DEADLINE_MS`, 30 min) before returning
119
+ * `wedged:true`. The grace this rule's `frontDoor` sibling gives a resume
120
+ * gap is already spent by the time `machine.wedge` appears, so nothing here
121
+ * should re-spend it — the first beat that carries the field is worth
122
+ * surfacing.
123
+ *
124
+ * `critMs` 30 min: a wedge that outlives another half hour past first
125
+ * detection is not resolving on its own — the same order of magnitude as
126
+ * the handoff deadline that opened it, not the frontDoor rule's 2h (that
127
+ * window exists to tolerate a LEGITIMATE long silence; a wedge is never
128
+ * legitimate once the deadline it is keyed to has already passed).
129
+ */
130
+ wedge: Object.freeze({
131
+ warnMs: 0,
132
+ critMs: 30 * 60 * 1000,
133
+ }),
97
134
  /**
98
135
  * How many CONSECUTIVE failed attempts to reach @latest make a seat STUCK.
99
136
  *
@@ -201,8 +238,16 @@ export function deriveAlerts(status, thresholds, now = Date.now()) {
201
238
  push(alerts, diskRule(machine, t.disk));
202
239
  push(alerts, subAgentsRule(s, t.subAgents));
203
240
  push(alerts, frontDoorRule(machine, t.frontDoor, now));
241
+ push(alerts, wedgeRule(machine, t.wedge, now));
204
242
  push(alerts, scopeFaultRule(machine));
205
243
  push(alerts, repliesWithheldRule(machine, t.replyDebt));
244
+ // NO THRESHOLD ARGUMENT, DELIBERATELY. `planeAlert` derives its severity from
245
+ // a STRUCTURAL property (is the obligation record still there?) rather than
246
+ // from a count, because no count could be defended on observed data — the
247
+ // reasoning is in `lib/assurance/operator-plane.mjs`'s own docblock, beside
248
+ // the predicate it governs. The window this is measured over is already
249
+ // operator-tunable through `ASSURANCE_RETENTION_MS`.
250
+ push(alerts, planeAlert(machine.operatorPlane));
206
251
  push(alerts, upgradeStuckRule(machine, t.upgradeStuck, now));
207
252
 
208
253
  alerts.sort((a, b) => {
@@ -450,6 +495,46 @@ function frontDoorRule(machine, cfg = {}, now = Date.now()) {
450
495
  };
451
496
  }
452
497
 
498
+ /**
499
+ * The front door is BEATING but not READING — `machine.wedge`
500
+ * (`collect.sessionWedge`), present only while a handoff sits unclaimed past
501
+ * its own deadline with a fresh heartbeat underneath it. This is the inverse
502
+ * of `frontDoorRule` above: that rule fires when the beat itself goes stale;
503
+ * this one fires when the beat stays fresh and everything else is still
504
+ * wrong. Neither rule can see the other's case — `sessionLiveness` reports
505
+ * exactly one `sessionLive` value, so a snapshot is in at most one of the two
506
+ * states, never both.
507
+ *
508
+ * Anchored on `wedge.since`, same as `frontDoorRule` and for the same reason:
509
+ * a detail carrying a ticking duration opens a new hq alert row every beat
510
+ * (`alertClientKey` keys on severity\0kind\0detail). At most two rows per
511
+ * episode this way — the warn one, then the critical one — not one per beat.
512
+ *
513
+ * A `since` that fails to parse raises nothing, same as `frontDoorRule`: an
514
+ * alert is a claim about duration, and an undatable wedge cannot support one.
515
+ */
516
+ function wedgeRule(machine, cfg = {}, now = Date.now()) {
517
+ const wedge = machine && typeof machine.wedge === "object" && machine.wedge !== null && !Array.isArray(machine.wedge)
518
+ ? machine.wedge
519
+ : null;
520
+ if (!wedge) return null;
521
+ const reason = typeof wedge.reason === "string" ? wedge.reason.trim() : "";
522
+ if (!reason) return null;
523
+ const since = Date.parse(typeof wedge.since === "string" ? wedge.since : "");
524
+ if (!Number.isFinite(since)) return null;
525
+ const ageMs = num(now) - since;
526
+ if (!(ageMs >= 0)) return null; // a future stamp is skew, not a duration
527
+ const sev = severityFor(ageMs, num(cfg.warnMs, Infinity), num(cfg.critMs, Infinity));
528
+ if (!sev) return null;
529
+ return {
530
+ id: "front_door_wedged",
531
+ severity: sev,
532
+ kind: "wedge",
533
+ // An INSTANT, never a duration — see `alertClientKey` above.
534
+ detail: `the seat's front door is beating but not reading since ${new Date(since).toISOString()} (${reason}) — presence alone reads this seat as idle and healthy.`,
535
+ };
536
+ }
537
+
453
538
  /**
454
539
  * Does this alert list contain a critical alert? Convenience for the mesh's
455
540
  * local-escalation decision. Never throws.
@@ -462,6 +547,6 @@ export function hasCritical(alerts) {
462
547
  }
463
548
  }
464
549
 
465
- export const _internals = { severityFor, reloginRule, tempRule, memRule, diskRule, subAgentsRule, frontDoorRule };
550
+ export const _internals = { severityFor, reloginRule, tempRule, memRule, diskRule, subAgentsRule, frontDoorRule, wedgeRule };
466
551
 
467
552
  export default { deriveAlerts, hasCritical, mergeThresholds, DEFAULT_THRESHOLDS };
@@ -40,6 +40,26 @@
40
40
  * hostname?: string, // os.hostname()
41
41
  * tailnetIp?: string, // `tailscale ip -4`, fail-open
42
42
  * sdkVersion?: string, // installed @cohortapp/agent-sdk version — how a fleet upgrade is verified
43
+ * // THE ENGINE ACTUALLY IN FORCE — `claude` or `cohort`, resolved the way
44
+ * // a spawn resolves it (`resolveEngine`), NOT the raw `runtime.engine`
45
+ * // string. An operator's question is "what is this seat running", and a
46
+ * // seat with no `runtime` key in config/agent.json still runs something
47
+ * // definite: DEFAULT_ENGINE. So this is ALWAYS PRESENT and never null —
48
+ * // which is the only way a seat that says "claude" can be told apart
49
+ * // from a seat on an SDK too old to say anything, and telling those two
50
+ * // apart is the whole reason the field exists. Engine adoption is then a
51
+ * // COUNT over the fleet rather than a tour of sixteen machines.
52
+ * engine: "claude"|"cohort",
53
+ * // WHICH CLAUDE BILLING RAIL THIS SEAT IS ON (G4) — four enum values and
54
+ * // a boolean, and NOTHING ELSE EVER. See `seatAuthBeat` in
55
+ * // lib/cli/seat-auth.mjs for the full list of what is deliberately not
56
+ * // transmitted: no credential in any form, no mask, no length, no key
57
+ * // id or last-four, no account/workspace, and not even the variable
58
+ * // NAMES that decided the rail. `rail` is a category (api-key /
59
+ * // subscription / both / neither) and `compliant` is whether that is
60
+ * // the posture for this seat's engine. Absent when the collector could
61
+ * // not read the seat's env at all.
62
+ * seatAuth?: { rail: "api-key"|"subscription"|"both"|"neither", compliant: boolean },
43
63
  * // FRONT DOOR — who receives inbound on this seat and whether it is alive.
44
64
  * // Lives on `machine` (hq stores it as an OPEN record, so a new key lands
45
65
  * // the moment the daemon emits it) and NOT on `session`, whose hq schema
@@ -162,7 +182,12 @@ import { fileURLToPath } from "node:url";
162
182
  import { createRequire } from "node:module";
163
183
  import { writeJsonAtomic } from "../fs-atomic.mjs";
164
184
  import { probeClaude as defaultProbeClaude } from "../setup/claude-probe.mjs";
165
- import { readSeatEngine } from "../runtime/adapter.mjs";
185
+ import { readSeatEngine, DEFAULT_ENGINE } from "../runtime/adapter.mjs";
186
+ // seat-auth.mjs statically imports node:os and nothing else, so this is not a
187
+ // cycle. `lib/cli/doctor-checks.mjs` WOULD be one — it imports `sessionLiveness`
188
+ // from this module — which is why `parseDotEnv` is not reused here and the
189
+ // presence-only scan below exists instead.
190
+ import { seatAuthVerdict, seatAuthBeat, SEAT_AUTH_VARS } from "../cli/seat-auth.mjs";
166
191
 
167
192
  import { list as listPresence } from "../collective/presence.mjs";
168
193
  import { billableUsd } from "../cost/ledger-row.mjs";
@@ -170,6 +195,7 @@ import { liveClaudeStats } from "../resource-governor.mjs";
170
195
  import { agentFirstName } from "../session/identity.mjs";
171
196
  import { snapshot as countersSnapshot } from "../diagnostics/counters.mjs";
172
197
  import { replyDebtFromCounters } from "../daemon/reply-debt.mjs";
198
+ import { readOperatorPlane } from "../assurance/operator-plane-store.mjs";
173
199
  import { summarisePinnedDrift, countPins } from "../upgrade/pinned-drift.mjs";
174
200
  import { IGNORED_DRIFT_REL } from "../upgrade/ignored-drift.mjs";
175
201
  import { listHandoffs, DEFAULT_HANDOFF_DEADLINE_MS } from "../session/handoffs.mjs";
@@ -2128,6 +2154,154 @@ function tailFile(path, bytes) {
2128
2154
  } catch { return ""; }
2129
2155
  }
2130
2156
 
2157
+ // ---------------------------------------------------------------------------
2158
+ // engine + seat auth — what this seat RUNS, and which Claude rail pays for it
2159
+ // ---------------------------------------------------------------------------
2160
+
2161
+ /**
2162
+ * The engine actually in force on this seat: `claude` or `cohort`, resolved the
2163
+ * way a spawn resolves it.
2164
+ *
2165
+ * TOTAL BY CONSTRUCTION — it answers DEFAULT_ENGINE for an absent `runtime`
2166
+ * key, an absent config, an unparseable config, an absent agentRoot and a
2167
+ * throwing reader, and it never answers null or undefined. That is the point of
2168
+ * the field: a beat carrying `engine: null` would be indistinguishable from a
2169
+ * beat from a seat on an SDK that predates the field, and the whole reason to
2170
+ * add it is to tell those two apart. `readSeatEngine` already makes the first
2171
+ * four of those answer the default; the try here closes the fifth.
2172
+ *
2173
+ * Seams: `o.engine` (a string) short-circuits the read; `o.seatEngine` (a
2174
+ * function) replaces the reader, which is the same seam `probeAuthForBeat`
2175
+ * already uses, so a test configures one thing for both.
2176
+ *
2177
+ * @param {{agentRoot?:string, engine?:string, seatEngine?:Function}} [o]
2178
+ * @returns {"claude"|"cohort"|string}
2179
+ */
2180
+ function collectEngine(o = {}) {
2181
+ try {
2182
+ if (typeof o.engine === "string" && o.engine.trim()) return o.engine.trim();
2183
+ const read = typeof o.seatEngine === "function" ? o.seatEngine : readSeatEngine;
2184
+ return read(o.agentRoot || "") || DEFAULT_ENGINE;
2185
+ } catch {
2186
+ return DEFAULT_ENGINE;
2187
+ }
2188
+ }
2189
+
2190
+ /** The same truthiness test `seatAuthVerdict` and the runtime adapter apply. */
2191
+ const SEAT_AUTH_TRUTHY = /^(1|true|yes)$/i;
2192
+
2193
+ /**
2194
+ * Scan a `.env` body for the seat-auth variables and report, for each one,
2195
+ * ONLY whether it is assigned something and whether that something is truthy.
2196
+ *
2197
+ * NO VALUE IS RETURNED. The two sentinels are `"set"` and `"truthy"`, and the
2198
+ * matched value goes out of scope on the next loop iteration — so no credential
2199
+ * is ever held in a variable this module's caller can reach, let alone put on a
2200
+ * beat. `seatAuthVerdict` needs exactly these two bits (non-emptiness for the
2201
+ * two credentials, truthiness for the preference flag) and nothing more.
2202
+ *
2203
+ * The line grammar deliberately mirrors `parseDotEnv` in
2204
+ * `lib/cli/doctor-checks.mjs` — `export` prefix, `#` comments, one layer of
2205
+ * matching quotes — because the two must agree about what "set" means. It is
2206
+ * copied rather than imported because that module imports `sessionLiveness`
2207
+ * from this one and the import would be a cycle.
2208
+ *
2209
+ * @param {string} body
2210
+ * @param {readonly string[]} names
2211
+ * @returns {Record<string,"set"|"truthy">}
2212
+ */
2213
+ function dotEnvPresence(body, names) {
2214
+ const out = {};
2215
+ for (const raw of String(body || "").split("\n")) {
2216
+ const line = raw.trim();
2217
+ if (!line || line.startsWith("#")) continue;
2218
+ const m = line.match(/^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/);
2219
+ if (!m || !names.includes(m[1])) continue;
2220
+ const v = m[2].trim().replace(/^(["'])(.*)\1$/, "$2");
2221
+ if (v) out[m[1]] = SEAT_AUTH_TRUTHY.test(v) ? "truthy" : "set";
2222
+ }
2223
+ return out;
2224
+ }
2225
+
2226
+ /** The same reduction for an ambient env bag: presence and truthiness, never the value. */
2227
+ function envPresence(env, names) {
2228
+ const out = {};
2229
+ const e = env && typeof env === "object" ? env : {};
2230
+ for (const n of names) {
2231
+ const v = e[n] === undefined || e[n] === null ? "" : String(e[n]).trim();
2232
+ if (v) out[n] = SEAT_AUTH_TRUTHY.test(v) ? "truthy" : "set";
2233
+ }
2234
+ return out;
2235
+ }
2236
+
2237
+ /**
2238
+ * The G4 seat-auth verdict, reduced to the two facts that may ride a beat.
2239
+ *
2240
+ * WHY THIS IS ON THE BEAT AT ALL. The verdict existed only as a local CLI
2241
+ * (`maestro seat-auth --row|--fleet`), so the inventory G4 needs — which
2242
+ * Anthropic account backs each seat, subscription or Console key — had to be
2243
+ * collected machine by machine by a person, and `claudeAuth` was `ok` on all
2244
+ * sixteen seats, one value with no discrimination in it. A seat can sit on
2245
+ * subscription OAuth for months precisely because it WORKS.
2246
+ *
2247
+ * WHAT CROSSES THE WIRE, and what deliberately does not, is decided by
2248
+ * `seatAuthBeat` (lib/cli/seat-auth.mjs) and documented exhaustively there: a
2249
+ * four-value rail category and a boolean, no credential in any form, no mask,
2250
+ * no length, no key id or last-four, no account or workspace, and not even the
2251
+ * variable NAMES that decided the rail. This function's own contribution to
2252
+ * that guarantee is that it never holds a value either — the env is reduced to
2253
+ * `"set"`/`"truthy"` sentinels by `dotEnvPresence`/`envPresence` before
2254
+ * `seatAuthVerdict` ever sees it, so the verdict it judges is built from
2255
+ * sentinels and cannot encode anything else.
2256
+ *
2257
+ * The merge order is the one `runSeatAuth` uses: `.env` wins over the ambient
2258
+ * environment, because the FILE is the seat's declared intent and that is what
2259
+ * an audit is about.
2260
+ *
2261
+ * Seams: `o.seatAuth === false` skips it; `o.seatAuthEnv` replaces the `.env`
2262
+ * read (an object of values, reduced to sentinels like any other); `o.env`
2263
+ * replaces the ambient env. Returns `null` when there is nothing to judge.
2264
+ *
2265
+ * @param {object} [o]
2266
+ * @param {string} [engine] the resolved engine — a cohort seat holding no
2267
+ * Anthropic credential is COMPLIANT, and the verdict needs to know that.
2268
+ * @returns {{rail:string, compliant:boolean}|null}
2269
+ */
2270
+ function collectSeatAuth(o = {}, engine = DEFAULT_ENGINE) {
2271
+ if (o.seatAuth === false) return null;
2272
+ // No agentRoot and no injected env: there is no seat to judge. The ambient
2273
+ // environment on its own would be a verdict about the COLLECTOR's process,
2274
+ // not about the seat, and a wrong `neither` is a failing verdict — so this
2275
+ // reports nothing rather than something it cannot stand behind.
2276
+ if (!o.agentRoot && o.seatAuthEnv === undefined) return null;
2277
+ const names = SEAT_AUTH_VARS;
2278
+
2279
+ let dot = {};
2280
+ if (o.seatAuthEnv !== undefined) {
2281
+ dot = envPresence(o.seatAuthEnv, names);
2282
+ } else {
2283
+ // A MISSING `.env` is not a failure to read — it is a seat that declared
2284
+ // nothing, and the ambient env then decides, exactly as `runSeatAuth` and
2285
+ // `subscriptionModeFromEnv` already treat it (launchd hands a headless seat
2286
+ // its credential that way, with no `.env` involved).
2287
+ let body = "";
2288
+ try { body = readFileSync(join(resolve(o.agentRoot), ".env"), "utf8"); } catch { body = ""; }
2289
+ dot = dotEnvPresence(body, names);
2290
+ }
2291
+ const ambient = envPresence(o.env || process.env, names);
2292
+
2293
+ // The bag handed to `seatAuthVerdict` holds sentinels, not credentials. "set"
2294
+ // is non-empty but not truthy; "1" is both. That is exactly the distinction
2295
+ // the verdict draws, and it is the only information that survives this step.
2296
+ const bag = {};
2297
+ for (const n of names) {
2298
+ const p = dot[n] || ambient[n] || "";
2299
+ if (p) bag[n] = p === "truthy" ? "1" : "set";
2300
+ }
2301
+
2302
+ return seatAuthBeat(seatAuthVerdict(bag, { seatEngine: engine }));
2303
+ }
2304
+
2131
2305
  // ---------------------------------------------------------------------------
2132
2306
  // subAgentsRunning
2133
2307
  // ---------------------------------------------------------------------------
@@ -2317,6 +2491,35 @@ export async function collectStatus(o = {}) {
2317
2491
  if (debt) machine.replyDebt = debt;
2318
2492
  } catch { /* no replyDebt field */ }
2319
2493
 
2494
+ // 4c-iii. DEAD ASKS IN THE OPERATOR PLANE — `machine.operatorPlane`, absent on
2495
+ // a seat with nothing in the plane.
2496
+ //
2497
+ // THIS IS THE PUSH HALF, AND IT IS THE HALF THAT MATTERS. The routing change
2498
+ // moved every machine-status notice off the human path and into
2499
+ // `state/obligations/needs-attention/` + the notice journal, arguing that the
2500
+ // sink "already works" and that "what was missing was never information; it was
2501
+ // a person looking at the sink". Nobody was: 78 rows accumulated on this seat
2502
+ // over five weeks with two writers and zero readers. `maestro attention` is the
2503
+ // drill-down, but a command that has to be REMEMBERED is the same premise that
2504
+ // failed, which is why this field exists — it rides the 30 s presence beat that
2505
+ // every seat already runs, exactly as `machine.replyDebt` above does for the
2506
+ // identical "the seat withheld something and nobody downstream knows" problem.
2507
+ //
2508
+ // NOT routed into the morning brief / midday sweep / evening wrap: all three end
2509
+ // in a Slack DM to the principal, who is the person the routing change exists to
2510
+ // stop messaging, and `lib/diagnostics/cadence-output-freshness.mjs` records the
2511
+ // wrap running 4 of 9 days.
2512
+ //
2513
+ // Reads disk, so it is the one probe here that could be slow on a seat with a
2514
+ // large plane; bounded by the same retention the daemon prunes to. Fail-open like
2515
+ // every other probe — a throw drops the field, never the beat.
2516
+ try {
2517
+ const plane = opt.operatorPlane !== undefined
2518
+ ? opt.operatorPlane
2519
+ : readOperatorPlane({ agentRoot: opt.agentRoot, now: nowMs });
2520
+ if (plane && plane.summary) machine.operatorPlane = plane.summary;
2521
+ } catch { /* no operatorPlane field */ }
2522
+
2320
2523
  // 4d. WHO is beating — `machine.daemon` {pid, bootAt, uptimeS, sdkVersion,
2321
2524
  // dashboardAt, healthy?, healthReason?}. This is what makes fleet version
2322
2525
  // drift a QUERY instead of an ssh tour: `machine.sdkVersion` is what is
@@ -2347,6 +2550,36 @@ export async function collectStatus(o = {}) {
2347
2550
  if (pd) machine.pinnedDrift = pd;
2348
2551
  } catch { /* no pinnedDrift field */ }
2349
2552
 
2553
+ // 4f. WHAT THIS SEAT RUNS, AND WHO PAYS FOR IT — `machine.engine` (always)
2554
+ // and `machine.seatAuth` (when the env could be read at all).
2555
+ //
2556
+ // WHY HERE AND NOT IN `collectMachine`. Both are config reads, not hardware
2557
+ // probes, and the lesson written up around the identity block in
2558
+ // `collectMachine` is that a `system_profiler` fork that throws takes the
2559
+ // whole of `collectMachine` down — `collectStatus` then substitutes its bare
2560
+ // `{loadavg, memUsedPct}` floor and the beat goes out carrying none of the
2561
+ // seat-level facts. Identity was hoisted within `collectMachine` to survive
2562
+ // the inventory probe; these two are assembled OUT HERE, past the floor, so
2563
+ // no probe failure anywhere can take them. `machine` is an OPEN record in
2564
+ // hq's presence.beat validator (unlike `session`, which is strict), so both
2565
+ // land without a lock-step hq deploy.
2566
+ //
2567
+ // `engine` is UNCONDITIONAL and is not gated on `o.identity`: a missing
2568
+ // engine must mean "SDK too old to report one", never "this caller switched
2569
+ // a probe off". `collectEngine` is total and cannot throw; the try is the
2570
+ // belt to that brace, and its catch still lands the default rather than
2571
+ // dropping the field.
2572
+ try { machine.engine = collectEngine(opt) || DEFAULT_ENGINE; }
2573
+ catch { machine.engine = DEFAULT_ENGINE; }
2574
+
2575
+ // `seatAuth` is absent rather than guessed when the env could not be read —
2576
+ // "I could not tell" must not render as "neither", which is a FAILING verdict
2577
+ // on a claude seat and would page someone about a healthy machine.
2578
+ try {
2579
+ const sa = collectSeatAuth(opt, machine.engine);
2580
+ if (sa) machine.seatAuth = sa;
2581
+ } catch { /* no seatAuth field — the beat still carries engine */ }
2582
+
2350
2583
  const status = {
2351
2584
  state,
2352
2585
  activity: act.activity || "idle",
@@ -2404,6 +2637,9 @@ export const _internals = {
2404
2637
  readIgnoredDriftReport,
2405
2638
  readPinCount,
2406
2639
  detectClaudeAuth,
2640
+ collectEngine,
2641
+ collectSeatAuth,
2642
+ dotEnvPresence,
2407
2643
  resetAuthProbeCache,
2408
2644
  scanForRelogin,
2409
2645
  countSubAgents,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cohortapp/agent-sdk",
3
- "version": "2.18.37",
3
+ "version": "2.19.1",
4
4
  "description": "Cohort Agent SDK — autonomous AI colleague runtime. Deploy senior AI colleagues on dedicated Mac minis, wired to the Cohort operating surface.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -169,6 +169,9 @@ import { sweepSessionInboxForDaemon, itemHandledByDoor } from "../../lib/session
169
169
  import { defaultEffects, scheduleToQueue } from "../../lib/execution/effects.mjs";
170
170
  import { loadReactObligations } from "../../lib/execution/match.mjs";
171
171
  import { policyFor } from "../../lib/execution/surface-policy.mjs";
172
+ import { loadGovernance, readPause as readGovernancePause } from "../../lib/org/governance-store.mjs";
173
+ import { ladderInputs, ladderNeedsHumanApproval } from "../../lib/org/governance.mjs";
174
+ import { escalateTo as awarenessEscalateTo } from "../../lib/org/awareness.mjs";
172
175
 
173
176
  // ---------------------------------------------------------------------------
174
177
  // Configuration
@@ -2175,6 +2178,30 @@ const UNINTERPRETABLE_IGNORE_REASONS = new Set([
2175
2178
  "not_an_object",
2176
2179
  ]);
2177
2180
 
2181
+ /**
2182
+ * The Genesis governance inputs for the ladder (WS6): a pause or a team-off
2183
+ * seat reads as `pause_schedules`, a monthly-cap pause as an exhausted daily
2184
+ * cap, and the first human up the reports-to chain as `facts.escalateTo`.
2185
+ * Empty for an old server — the ladder then sees exactly what it saw before.
2186
+ */
2187
+ export function ladderGovernance(agentRoot = AGENT_REPO_DIR) {
2188
+ try {
2189
+ const g = loadGovernance(agentRoot);
2190
+ // awareness.escalateTo is the one "who do I escalate to" answer; with an
2191
+ // agent manager it carries the first human up the chain (M3).
2192
+ const esc = awarenessEscalateTo(agentRoot);
2193
+ return ladderInputs({
2194
+ present: g.present,
2195
+ governance: g.governance,
2196
+ pause: readGovernancePause(agentRoot),
2197
+ firstHuman: esc && esc.firstHuman ? esc.firstHuman.memberId : null,
2198
+ });
2199
+ } catch (err) {
2200
+ console.warn(`[execution] could not read governance (${err.message}) — the ladder runs without it`);
2201
+ return { runtime: {}, facts: {} };
2202
+ }
2203
+ }
2204
+
2178
2205
  /** Cooperative kill switches the disposition layer reads. */
2179
2206
  function ladderRuntime() {
2180
2207
  const runtime = {};
@@ -2185,7 +2212,7 @@ function ladderRuntime() {
2185
2212
  } catch (err) {
2186
2213
  console.warn(`[execution] could not read the emergency-stop marker (${err.message}) — assuming not stopped`);
2187
2214
  }
2188
- return runtime;
2215
+ return { ...ladderGovernance().runtime, ...runtime };
2189
2216
  }
2190
2217
 
2191
2218
  /**
@@ -2243,7 +2270,15 @@ async function ladderArbitrate({ decision, candidate, resource }) {
2243
2270
  async function ladderRequestApproval(args) {
2244
2271
  const { decision, classes } = args;
2245
2272
  const policy = policyFor(decision && decision.surface);
2246
- const human = process.env.DAEMON_LADDER_APPROVALS === "1";
2273
+ // The workspace's approval mode (Genesis WS6) overrides surface self-approval:
2274
+ // `all_first_week` sends every gated class to a human, `external_only` the
2275
+ // external and financial ones. No mode (an old server) → today's rule.
2276
+ let modeWantsHuman = false;
2277
+ try {
2278
+ const g = loadGovernance(AGENT_REPO_DIR);
2279
+ modeWantsHuman = !!(g.present && g.governance && ladderNeedsHumanApproval(g.governance.approvalMode, classes));
2280
+ } catch { /* unreadable governance is the old-server reading: today's rule applies */ }
2281
+ const human = process.env.DAEMON_LADDER_APPROVALS === "1" || modeWantsHuman;
2247
2282
  if (!human && policy.selfApprove === true) {
2248
2283
  console.warn(
2249
2284
  `[execution] ${decision.surface} action is classed ${(classes || []).join("+")} (approval-gated by §8), but the ` +
@@ -2363,11 +2398,15 @@ export async function runExecutionLadder(item, service, itemId, trace_id, deps =
2363
2398
  requestApproval: ladderRequestApproval,
2364
2399
  };
2365
2400
 
2401
+ const govFacts = ladderGovernance().facts;
2366
2402
  const res = await _processOne({
2367
2403
  item,
2368
2404
  me,
2369
2405
  agentRoot: AGENT_REPO_DIR,
2370
2406
  runtime: ladderRuntime(),
2407
+ // facts are passed only when governance has one, so an old server's
2408
+ // decision is byte-identical to before.
2409
+ ...(Object.keys(govFacts).length ? { facts: govFacts } : {}),
2371
2410
  need: ladderNeed(item),
2372
2411
  obligations,
2373
2412
  effects,