@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
@@ -110,6 +110,8 @@ import { classifyCadenceFailure, isPermanent, PERMANENT_MAX_ATTEMPTS } from "../
110
110
  import { bump as bumpCounter } from "../../lib/diagnostics/counters.mjs";
111
111
  import { obligationAllowedUnderPosture } from "../../lib/plan/compile.mjs";
112
112
  import { isHumanLaneCadence } from "../../lib/cadences.mjs";
113
+ import { readPause as readGovernancePause, loadGovernance } from "../../lib/org/governance-store.mjs";
114
+ import { teamModePosture } from "../../lib/org/governance.mjs";
113
115
  import { sessionPermissionArgs } from "../../lib/session-permissions.mjs";
114
116
  import { renderTemplate, buildContext } from "../../lib/render.mjs";
115
117
  import { withParallelism } from "../../lib/prompts/parallelism.mjs";
@@ -868,6 +870,21 @@ export function startConsumer(opts = {}) {
868
870
  * Returns { admit:boolean, reason }.
869
871
  */
870
872
  function governanceGate(cadence) {
873
+ // Genesis governance (WS6): a spend-cap / directive pause, or a team that
874
+ // has the seat switched OFF, stops PROACTIVE cadences. The human lane
875
+ // (inbox-processor, messaging-inbound) is never held — a paused seat still
876
+ // answers when addressed. A seat whose server sends no governance fields
877
+ // has no pause file and a null teamMode, so nothing here changes for it.
878
+ if (!(cadence && isHumanLaneCadence(cadence))) {
879
+ try {
880
+ const pause = readGovernancePause(agentRoot);
881
+ if (pause) return { admit: false, reason: `governance-paused:${pause.source}` };
882
+ const g = loadGovernance(agentRoot);
883
+ if (g.present && g.governance && !teamModePosture(g.governance.teamMode).proactive) {
884
+ return { admit: false, reason: "team-mode-off" };
885
+ }
886
+ } catch { /* a governance read fault admits: a governance bug must not wedge cadences (same invariant as below) */ }
887
+ }
871
888
  try {
872
889
  const rb = rateGuard.checkRateLimit(RATE_PROVIDER, { agentRoot });
873
890
  if (!rb.allowed) return { admit: false, reason: "rate-limited" };
@@ -20,6 +20,8 @@ import { isPrivateConversation, historyDirNames } from "../../lib/context/histor
20
20
  import { stripDisclosureInstructionsAndWarn } from "../../lib/identity/disclosure-instructions.mjs";
21
21
  import { fitSections } from "../../lib/context/budget.mjs";
22
22
  import { currentWorkBlock, audienceForItem } from "../../lib/session/current-work.mjs";
23
+ import { loadGovernance, readPause as readGovernancePause } from "../../lib/org/governance-store.mjs";
24
+ import { governancePromptBlock } from "../../lib/org/governance.mjs";
23
25
 
24
26
  const AGENT_REPO_DIR = process.env.__TEST_AGENT_DIR || process.env.AGENT_DIR || join(new URL(".", import.meta.url).pathname, "../..");
25
27
  const SESSION_DIR = process.env.__TEST_SESSION_DIR || join(AGENT_REPO_DIR, "state", "sessions");
@@ -462,6 +464,19 @@ function loadCachedOrgCfg() {
462
464
  }
463
465
 
464
466
  /** For tests: reset the cached org config so a fresh config/org.yaml is re-read. */
467
+ /** The decision-rights block for this seat, or "" (old server / unreadable). */
468
+ function loadDecisionRights() {
469
+ try {
470
+ const g = loadGovernance(AGENT_REPO_DIR);
471
+ if (!g.present) return "";
472
+ return governancePromptBlock(g.governance, { pause: readGovernancePause(AGENT_REPO_DIR) });
473
+ } catch {
474
+ // The block is advisory; the tool gate is what enforces. Omitting it on a
475
+ // read fault leaves the context exactly as it was before WS6.
476
+ return "";
477
+ }
478
+ }
479
+
465
480
  export function _resetOrgCfgCache() {
466
481
  cachedOrgCfg = undefined;
467
482
  }
@@ -610,6 +625,16 @@ export async function compileContext(item, classResult, options = {}) {
610
625
  sections.push("");
611
626
  }
612
627
 
628
+ // Genesis decision rights (WS6). The tool gate enforces only the clauses it
629
+ // can match clearly; every clause still reaches the model here. Absent for
630
+ // a seat whose server sends no governance fields — the block is omitted.
631
+ const rightsText = loadDecisionRights();
632
+ if (rightsText) {
633
+ sections.push("## Decision Rights");
634
+ sections.push(rightsText);
635
+ sections.push("");
636
+ }
637
+
613
638
  if (orgMemoryText) {
614
639
  sections.push("## Org Shared Memory");
615
640
  sections.push(orgMemoryText);
@@ -28,14 +28,14 @@
28
28
  import { execFileSync } from "child_process";
29
29
  import { mkdirSync, writeFileSync } from "fs";
30
30
  import { join } from "path";
31
- import { screenOutbound } from "../../lib/comms/send-gate.mjs";
31
+ import { screenOutbound, machineLeakVerdict } from "../../lib/comms/send-gate.mjs";
32
32
  import { getHookBus } from "../../lib/hooks/bus.mjs";
33
33
  import { recordNoSend, recordOutbound } from "../../lib/comms/receipts.mjs";
34
34
  // Pure data (a frozen table, no imports of its own) — the surface vocabulary the
35
35
  // inbound projection stamps into `raw_ref`. Imported rather than re-listed so a
36
36
  // new surface cannot be added upstream without this file's switch noticing.
37
37
  import { ROOM_SURFACES, SURFACE_NAMES } from "../../lib/org/inbound/surfaces.mjs";
38
- import { isAgentStatusNotice, isRetiredFirstReply } from "../../lib/assurance/first-reply.mjs";
38
+ import { isAgentStatusNotice, isRetiredFirstReply, opensAsRescueNotice } from "../../lib/assurance/first-reply.mjs";
39
39
  // THE TWO HALVES OF THE MACHINE-STATUS REFUSAL. `isMachineStatusDeliveryKind`
40
40
  // is the ORIGIN test (what composed this) and `machineStatusNarration` is the
41
41
  // SHAPE test (what it reads like). Both are pure data + pure predicates, imported
@@ -149,6 +149,43 @@ const CHANNEL_SURFACES = ROOM_SURFACES;
149
149
  * otherwise healthy deployment, which is a strictly worse failure than one
150
150
  * extra attempt.
151
151
  */
152
+ /**
153
+ * The code the FOUR MACHINE-STATUS refusals below carry — and why it is not
154
+ * `FORBIDDEN_SCOPE` any more.
155
+ *
156
+ * All three used to be coded `FORBIDDEN_SCOPE`, which is hq's code for a 403.
157
+ * `isScopeFault()` in `lib/daemon/reply-debt.mjs` returns true for exactly that
158
+ * string, and that predicate drives both `configFault:"missing-scope"` on a
159
+ * needs-attention row (`agent-daemon.mjs`) and the `reply.scope_refused` counter
160
+ * behind the `seat_missing_scope` CRITICAL alert, whose own detail text reads
161
+ * "Grant the scope; the seat cannot."
162
+ *
163
+ * So "I correctly refused to post my own status line" was about to become
164
+ * indistinguishable from "this seat is missing a scope and a human must grant
165
+ * one" — a critical alert, on a working seat, with an instruction nobody can
166
+ * carry out. Latent only because no seat had shipped the routing change yet; it
167
+ * lands the first time one does.
168
+ *
169
+ * Deliberately NOT added to PERMANENT_RPC_CODES below: that list is about error
170
+ * frames hq returns, and these refusals are this daemon's own and already carry
171
+ * `permanent:true` explicitly.
172
+ *
173
+ * `lib/assurance/operator-plane.test.mjs` pins that `isScopeFault` is false for
174
+ * this code, because the whole value of the distinction is that one predicate
175
+ * stops seeing the other thing.
176
+ */
177
+ export const OPERATOR_PLANE_REFUSAL = "OPERATOR_PLANE";
178
+
179
+ /**
180
+ * The code a CONTENT refusal carries: a body this daemon will not send because
181
+ * of what it says (send-gate's MACHINE_LEAK_RULES), not because of who it may
182
+ * talk to. Distinct from `FORBIDDEN_SCOPE` for the reason given above for
183
+ * OPERATOR_PLANE_REFUSAL: `isScopeFault` reads that string as "a human must
184
+ * grant this seat a scope" and raises the `seat_missing_scope` CRITICAL alert,
185
+ * and the remedy for a leak is a rewrite, not a grant.
186
+ */
187
+ export const CONTENT_POLICY_REFUSAL = "CONTENT_POLICY";
188
+
152
189
  const PERMANENT_RPC_CODES = Object.freeze([
153
190
  "NOT_FOUND",
154
191
  "BAD_REQUEST",
@@ -1083,12 +1120,12 @@ export async function deliver(item, text, o = {}) {
1083
1120
  // already written the `needs-attention` row an operator sweeps.
1084
1121
  if (isMachineStatusDeliveryKind(kind)) {
1085
1122
  try { console.error(`[deliver] refused: machine-status delivery kind ${JSON.stringify(kind)} — status about this machine's own work goes to the operator plane (needs-attention, counters, logs), never to a conversation (permanent, not retrying)`); } catch { /* */ }
1086
- return noteNoSend(item, o, { sent: false, via: null, permanent: true, channel: item && item.channel_id, code: "FORBIDDEN_SCOPE", error: `FORBIDDEN_SCOPE: machine-status kind "${kind}" may not be delivered to a conversation — route it to the operator plane` });
1123
+ return noteNoSend(item, o, { sent: false, via: null, permanent: true, channel: item && item.channel_id, code: OPERATOR_PLANE_REFUSAL, error: `${OPERATOR_PLANE_REFUSAL}: machine-status kind "${kind}" may not be delivered to a conversation — route it to the operator plane` });
1087
1124
  }
1088
1125
  const narration = machineStatusNarration(text);
1089
1126
  if (narration) {
1090
1127
  try { console.error(`[deliver] refused: outbound body narrates this machine's own apparatus (${JSON.stringify(narration)}) — a person is owed the answer or nothing, not a status line (permanent, not retrying)`); } catch { /* */ }
1091
- return noteNoSend(item, o, { sent: false, via: null, permanent: true, channel: item && item.channel_id, code: "FORBIDDEN_SCOPE", error: `FORBIDDEN_SCOPE: machine-status narration in outbound body (${narration}) — this belongs in the operator plane, not in a conversation` });
1128
+ return noteNoSend(item, o, { sent: false, via: null, permanent: true, channel: item && item.channel_id, code: OPERATOR_PLANE_REFUSAL, error: `${OPERATOR_PLANE_REFUSAL}: machine-status narration in outbound body (${narration}) — this belongs in the operator plane, not in a conversation` });
1092
1129
  }
1093
1130
  // ── THE THIRD SHAPE: ONE OF THIS DAEMON'S OWN TEMPLATES, WITH NO ANSWER ───
1094
1131
  //
@@ -1119,7 +1156,21 @@ export async function deliver(item, text, o = {}) {
1119
1156
  const answerless = await answerlessOwnTemplate(text);
1120
1157
  if (answerless) {
1121
1158
  try { console.error(`[deliver] refused: outbound body is this daemon's own status template with no answer in it — ${JSON.stringify(answerless)} (permanent, not retrying)`); } catch { /* */ }
1122
- return noteNoSend(item, o, { sent: false, via: null, permanent: true, channel: item && item.channel_id, code: "FORBIDDEN_SCOPE", error: `FORBIDDEN_SCOPE: machine-status template with no work product in it — route it to the operator plane, not to a conversation` });
1159
+ return noteNoSend(item, o, { sent: false, via: null, permanent: true, channel: item && item.channel_id, code: OPERATOR_PLANE_REFUSAL, error: `${OPERATOR_PLANE_REFUSAL}: machine-status template with no work product in it — route it to the operator plane, not to a conversation` });
1160
+ }
1161
+ // ── THE FOURTH SHAPE: A RESCUE WRAPPER, WITH A SESSION'S NOTES INSIDE IT ──
1162
+ //
1163
+ // The gate above stops the two rescue composers when they carry NOTHING. With
1164
+ // a second paragraph they used to be treated as replies, and the second
1165
+ // paragraph is the session's end-of-turn text — its report to the process that
1166
+ // spawned it, with this machine's file paths, queue ids and session talk in it.
1167
+ // That body went to team channels under the seat's name from five seats.
1168
+ // `settleSession` now holds that text in the operator plane and sends neither
1169
+ // wrapper to anyone; this refuses the wrapper here too, whatever follows the
1170
+ // head, so the emitter decision is not the only thing standing.
1171
+ if (opensAsRescueNotice(text)) {
1172
+ try { console.error(`[deliver] refused: outbound body opens as the assurance rescue wrapper — a session's end-of-turn text is held for the owner in the operator plane, never posted (permanent, not retrying)`); } catch { /* */ }
1173
+ return noteNoSend(item, o, { sent: false, via: null, permanent: true, channel: item && item.channel_id, code: OPERATOR_PLANE_REFUSAL, error: `${OPERATOR_PLANE_REFUSAL}: the assurance rescue wrapper may not reach a conversation — the session's text is held for the owner (maestro attention)` });
1123
1174
  }
1124
1175
  const leak = scaffoldMarkerLeak(text);
1125
1176
  if (leak) {
@@ -1137,6 +1188,21 @@ export async function deliver(item, text, o = {}) {
1137
1188
  try { console.error(`[deliver] refused: machine-local path ${JSON.stringify(pathLeak)} in outbound body (permanent, not retrying)`); } catch { /* */ }
1138
1189
  return noteNoSend(item, o, { sent: false, via: null, permanent: true, channel: item && item.channel_id, surface, code: "FORBIDDEN_SCOPE", error: `FORBIDDEN_SCOPE: machine-local path ${pathLeak} in outbound body — no one off this machine can open it; a reply must not carry a local path` });
1139
1190
  }
1191
+ // ── MACHINE INTERNALS, ON EVERY LANE ────────────────────────────────────────
1192
+ //
1193
+ // send-gate's MACHINE_LEAK_RULES (agent-state paths, queue and inbox ids, the
1194
+ // agent's own sessions) run inside `screenOutbound`, which the cohort and
1195
+ // slack lanes call — but the gmail lane below shells out to a script that runs
1196
+ // only the Layer-0 validator, so a rule that lives only in the lanes is a rule
1197
+ // one lane routes around. Applied here, once, before any lane. Pure, so it
1198
+ // cannot fail open; the refusal names the rule and the span, and nothing is
1199
+ // rewritten — the caller escalates, the sender restates.
1200
+ const machineLeak = machineLeakVerdict(text, { agentRoot: AGENT_REPO_DIR });
1201
+ if (machineLeak) {
1202
+ const surface = (item && item.channel_id) ? "room" : "unknown";
1203
+ try { console.error(`[deliver] refused: ${machineLeak.reason} (permanent, not retrying)`); } catch { /* */ }
1204
+ return noteNoSend(item, o, { sent: false, via: null, permanent: true, channel: item && item.channel_id, surface, code: CONTENT_POLICY_REFUSAL, error: `${CONTENT_POLICY_REFUSAL}: ${machineLeak.reason}` });
1205
+ }
1140
1206
  // `permanent` says retrying changes nothing. A caller that cannot tell the
1141
1207
  // difference between "hq blipped" and "there is no transport for telegram"
1142
1208
  // retries both at the same cadence, which is how an impossible send becomes an
@@ -0,0 +1,266 @@
1
+ #!/usr/bin/env node
2
+ // scripts/fleet/closing-sweep.mjs
3
+ //
4
+ // Per-seat closing-condition sweep for the #90 assurance-leak rollout.
5
+ //
6
+ // Encodes the settled closing condition (Isla + Jacob + Hannah, 2026-10-13):
7
+ // a seat is CLOSED for #90 only when, after it takes the fix and its daemon
8
+ // restarts onto the new module:
9
+ // (1) every guard #90 touches is green;
10
+ // (2) no guard is NEWLY broken — we compare the broken-guard SET (not a
11
+ // count) at a pinned pre-upgrade instant vs a pinned post-restart
12
+ // instant. A set regression fails the seat regardless of count, which
13
+ // is what a count can't see (fixed-two-broke-two reads as unchanged);
14
+ // (3) every guard still broken after the upgrade has a named owner + date;
15
+ // (4) install-on-absent-checker: a seat with no invariant checker wired is
16
+ // a FINDING, not a pass — nothing ran, so "clean" means unmeasured.
17
+ //
18
+ // This script IS the portable checker clause (4) calls for. It reads
19
+ // config/local-invariants.yaml and runs each invariant's own `verify`, so a
20
+ // seat whose only record is a passive checklist still gets measured. It does
21
+ // NOT modify seat state — it verifies.
22
+ //
23
+ // Usage:
24
+ // node scripts/fleet/closing-sweep.mjs capture [--out <file.json>]
25
+ // node scripts/fleet/closing-sweep.mjs diff <before.json> <after.json> [--touches id1,id2]
26
+ //
27
+ // `--touches` names the invariant ids #90's fix is accountable for (clause 1
28
+ // target = zero broken among these). Everything else broken rides clause 3
29
+ // (named owner + date), never a count.
30
+
31
+ import { execSync } from 'node:child_process';
32
+ import { readFileSync, writeFileSync, existsSync, readdirSync } from 'node:fs';
33
+ import { resolve, basename } from 'node:path';
34
+ import { homedir } from 'node:os';
35
+ import yaml from 'js-yaml';
36
+
37
+ const AGENT_ROOT = resolve(process.cwd());
38
+ const INVARIANTS_FILE = resolve(AGENT_ROOT, 'config/local-invariants.yaml');
39
+ const HEALTHCHECK_FILE = resolve(AGENT_ROOT, 'scripts/healthcheck.sh');
40
+ // The checker is seat-owned and may live under scripts/local/ or scripts/ci/
41
+ // (both outside the SDK overwrite path). Detect any present candidate rather
42
+ // than hardcoding one path — a seat whose checker sits elsewhere must not read
43
+ // as absent (Hannah, 2026-10-13).
44
+ const CHECKER_CANDIDATES = [
45
+ 'scripts/local/check-local-invariants.mjs',
46
+ 'scripts/ci/check-local-invariants.mjs',
47
+ 'scripts/local/invariant-watch.sh',
48
+ ].map((p) => resolve(AGENT_ROOT, p));
49
+ // The checker writes this stamp (ISO timestamp) each time it actually runs.
50
+ // "ran" is evidenced here, not by a loaded plist — a scheduled job can fail
51
+ // before it reaches the checker.
52
+ const STAMP_FILE = resolve(AGENT_ROOT, 'state/local/invariant-check.stamp');
53
+ // Freshness window for the stamp; default 25h (a daily checker + slack).
54
+ // Override with --window-hours on capture.
55
+ const DEFAULT_WINDOW_HOURS = 25;
56
+
57
+ function seatName() {
58
+ try {
59
+ const cfg = JSON.parse(readFileSync(resolve(AGENT_ROOT, 'config/agent.json'), 'utf8'));
60
+ return cfg?.agent?.seat || cfg?.seat || cfg?.agent?.repoSlug || basename(AGENT_ROOT);
61
+ } catch {
62
+ return basename(AGENT_ROOT);
63
+ }
64
+ }
65
+
66
+ // "Wired" is FOUR states, not a boolean (Isla/Jacob/Candace/Hannah 2026-10-13).
67
+ // The property we close on is that the checker EXECUTED recently — not that a
68
+ // call-site string exists (Jacob's seat) and not that a plist is loaded
69
+ // (Hannah's point: a loaded job can fail before reaching the checker). Both are
70
+ // presence checks on an adjacent property.
71
+ // absent — no checker and no call site
72
+ // present-unscheduled — checker/call-site exist, nothing runs them
73
+ // scheduled-not-run-in-window — a scheduler is configured, but no fresh run stamp
74
+ // ran — checker wrote a stamp dated inside its window
75
+ // Only 'ran' closes a seat.
76
+ function detectCheckerState(windowHours) {
77
+ const hasChecker = CHECKER_CANDIDATES.some((p) => existsSync(p));
78
+ let hasCallSite = false;
79
+ try {
80
+ hasCallSite = /invariant|local-invariants|check-local-invariants/i.test(readFileSync(HEALTHCHECK_FILE, 'utf8'));
81
+ } catch {}
82
+ if (!hasChecker && !hasCallSite) return { state: 'absent', runners: [], stamp: null };
83
+
84
+ // Does anything actually schedule it? launchd agents on this host, crontab,
85
+ // or a cadence obligation that invokes healthcheck.sh / the checker.
86
+ const runners = [];
87
+ try {
88
+ const laDir = resolve(homedir(), 'Library/LaunchAgents');
89
+ for (const f of readdirSync(laDir)) {
90
+ if (!f.endsWith('.plist')) continue;
91
+ if (/healthcheck\.sh|check-local-invariants/.test(readFileSync(resolve(laDir, f), 'utf8'))) runners.push(`launchd:${f}`);
92
+ }
93
+ } catch {}
94
+ try {
95
+ if (/healthcheck\.sh|check-local-invariants/.test(execSync('crontab -l', { stdio: 'pipe' }).toString())) runners.push('crontab');
96
+ } catch {}
97
+ try {
98
+ if (/healthcheck|check-local-invariants/.test(readFileSync(resolve(AGENT_ROOT, '.cadence-registry.json'), 'utf8'))) runners.push('cadence');
99
+ } catch {}
100
+
101
+ if (!runners.length) return { state: 'present-unscheduled', runners: [], stamp: null };
102
+
103
+ // Scheduled — but did it actually run inside its window? Evidence is the stamp.
104
+ let stamp = null;
105
+ try {
106
+ stamp = readFileSync(STAMP_FILE, 'utf8').trim();
107
+ } catch {}
108
+ const fresh = stamp && (Date.now() - Date.parse(stamp)) <= windowHours * 3600 * 1000;
109
+ return { state: fresh ? 'ran' : 'scheduled-not-run-in-window', runners, stamp };
110
+ }
111
+
112
+ // A verify that only greps for a string measures the property ADJACENT to the
113
+ // one we care about ("string present"), not behaviour — it can stay green over
114
+ // a dead path (Candace). Flag those structural rather than accepting the green.
115
+ function classifyMeasure(verify) {
116
+ if (!verify) return 'none';
117
+ const v = verify.trim();
118
+ if (/\bnode\b|\bnpm\b|--test\b/.test(v)) return 'behavioural';
119
+ if (/\bgrep\b/.test(v)) return 'presence-only';
120
+ return 'unknown';
121
+ }
122
+
123
+ function loadInvariants() {
124
+ const doc = yaml.load(readFileSync(INVARIANTS_FILE, 'utf8'));
125
+ return Array.isArray(doc?.invariants) ? doc.invariants : [];
126
+ }
127
+
128
+ // Run an invariant's own `verify`. Exit 0 => OK, anything else => BROKEN.
129
+ // grep verifies exit 1 on no-match; node --test verifies exit non-zero on
130
+ // a reverted export/import or a failed assertion. Both map cleanly.
131
+ function runVerify(inv) {
132
+ if (!inv.verify) return { status: 'UNVERIFIABLE', detail: 'no verify command declared' };
133
+ try {
134
+ execSync(inv.verify, { cwd: AGENT_ROOT, stdio: 'pipe', timeout: 120000 });
135
+ return { status: 'OK' };
136
+ } catch (err) {
137
+ const out = `${err.stdout || ''}${err.stderr || ''}`.trim();
138
+ const firstLine = out.split('\n').find((l) => /error|not provide an export|No such|not a function|undefined/i.test(l));
139
+ return { status: 'BROKEN', detail: firstLine || `verify exited ${err.status ?? 'non-zero'}` };
140
+ }
141
+ }
142
+
143
+ function capture(windowHours) {
144
+ const instant = new Date().toISOString();
145
+ const invariants = loadInvariants().map((inv) => {
146
+ const r = runVerify(inv);
147
+ return {
148
+ id: inv.id,
149
+ file: inv.file,
150
+ anchor: inv.anchor,
151
+ fixed: inv.fixed,
152
+ status: r.status,
153
+ detail: r.detail,
154
+ measures: classifyMeasure(inv.verify),
155
+ owner: inv.owner,
156
+ date: inv.date,
157
+ };
158
+ });
159
+ const brokenSet = invariants.filter((i) => i.status === 'BROKEN').map((i) => i.id);
160
+ const unverifiable = invariants.filter((i) => i.status === 'UNVERIFIABLE').map((i) => i.id);
161
+ // Structural: green is on an adjacent property, not behaviour — don't bank it.
162
+ const structural = invariants.filter((i) => i.measures === 'presence-only').map((i) => i.id);
163
+ return {
164
+ seat: seatName(),
165
+ instant,
166
+ windowHours,
167
+ checker: detectCheckerState(windowHours),
168
+ invariants,
169
+ brokenSet,
170
+ unverifiable,
171
+ structural,
172
+ };
173
+ }
174
+
175
+ // Apply the four-clause verdict to a before/after pair.
176
+ function diff(before, after, touches) {
177
+ const beforeBroken = new Set(before.brokenSet);
178
+ const afterBroken = new Set(after.brokenSet);
179
+ const newlyBroken = [...afterBroken].filter((id) => !beforeBroken.has(id)); // clause 2
180
+ const touchedBroken = touches.filter((id) => afterBroken.has(id)); // clause 1
181
+ const stillBroken = [...afterBroken]; // clause 3 — each needs owner + date
182
+
183
+ const checkerState = after.checker?.state;
184
+ // Clause 3: a still-broken guard is accountable only if the record carries a
185
+ // named owner AND a date for it (Hannah/Jacob 2026-10-13). Accountable breaks
186
+ // do NOT block closure; unaccounted ones do. A NEW break (clause 2) blocks
187
+ // regardless of owner — a regression is a regression.
188
+ const od = Object.fromEntries((after.invariants || []).map((i) => [i.id, i]));
189
+ const accountable = (id) => Boolean(od[id] && od[id].owner && od[id].date);
190
+ const unaccounted = stillBroken.filter((id) => !accountable(id));
191
+ const accounted = stillBroken.filter(accountable);
192
+ // Clause 4-adjacent: an invariant with no runnable verify measured NOTHING.
193
+ // That is a finding, not a pass — the same "zero means unmeasured" failure one
194
+ // level down (Hannah). It must block closure, never be silently dropped.
195
+ const unverifiable = after.unverifiable || [];
196
+
197
+ const findings = [];
198
+ if (checkerState !== 'ran') {
199
+ const why = {
200
+ absent: 'no checker and no call site — seat produces no signal when guards break',
201
+ 'present-unscheduled': 'checker/call-site exist but nothing runs them — never fires on its own',
202
+ 'scheduled-not-run-in-window': 'a scheduler is configured but no fresh run stamp — a loaded job can fail before reaching the checker',
203
+ }[checkerState] || 'checker never ran';
204
+ findings.push(`CLAUSE 4: checker state is "${checkerState}" (${why}). Only "ran" closes. Rollout must install the checker + a call site OUTSIDE the overwrite path AND prove it executed (a dated run stamp), not merely that a plist is loaded.`);
205
+ }
206
+ if (touchedBroken.length) {
207
+ findings.push(`CLAUSE 1: guard(s) #90 is accountable for still broken: ${touchedBroken.join(', ')}`);
208
+ }
209
+ if (newlyBroken.length) {
210
+ findings.push(`CLAUSE 2: set regression — guard(s) newly broken by taking the fix: ${newlyBroken.join(', ')}`);
211
+ }
212
+ if (unaccounted.length) {
213
+ findings.push(`CLAUSE 3: still broken WITHOUT a named owner + date in the record (blocks closure): ${unaccounted.join(', ')}`);
214
+ }
215
+ if (unverifiable.length) {
216
+ findings.push(`UNVERIFIABLE: measured nothing (no runnable verify) — a finding, not a pass: ${unverifiable.join(', ')}`);
217
+ }
218
+ // Structural: greens that measure an adjacent property, not behaviour.
219
+ if (after.structural?.length) {
220
+ findings.push(`STRUCTURAL: these invariants measure an adjacent property (string presence), not behaviour, so their green doesn't prove the guard: ${after.structural.join(', ')}`);
221
+ }
222
+
223
+ const closed =
224
+ checkerState === 'ran' &&
225
+ !touchedBroken.length &&
226
+ !newlyBroken.length &&
227
+ !unaccounted.length &&
228
+ !unverifiable.length;
229
+ return {
230
+ seat: after.seat,
231
+ beforeInstant: before.instant,
232
+ afterInstant: after.instant,
233
+ checkerState,
234
+ newlyBroken,
235
+ touchedBroken,
236
+ stillBroken,
237
+ accounted, // still broken but owned + dated — non-blocking under clause 3
238
+ unaccounted,
239
+ unverifiable,
240
+ structural: after.structural || [],
241
+ verdict: closed ? 'CLOSED' : 'NOT-CLOSED',
242
+ findings,
243
+ };
244
+ }
245
+
246
+ const [, , mode, ...rest] = process.argv;
247
+
248
+ if (mode === 'capture') {
249
+ const outIdx = rest.indexOf('--out');
250
+ const whIdx = rest.indexOf('--window-hours');
251
+ const windowHours = whIdx !== -1 && rest[whIdx + 1] ? Number(rest[whIdx + 1]) : DEFAULT_WINDOW_HOURS;
252
+ const snap = capture(windowHours);
253
+ const json = JSON.stringify(snap, null, 2);
254
+ if (outIdx !== -1 && rest[outIdx + 1]) writeFileSync(rest[outIdx + 1], json);
255
+ console.log(json);
256
+ } else if (mode === 'diff') {
257
+ const [beforeFile, afterFile] = rest.filter((a) => !a.startsWith('--'));
258
+ const tIdx = rest.indexOf('--touches');
259
+ const touches = tIdx !== -1 && rest[tIdx + 1] ? rest[tIdx + 1].split(',') : [];
260
+ const before = JSON.parse(readFileSync(beforeFile, 'utf8'));
261
+ const after = JSON.parse(readFileSync(afterFile, 'utf8'));
262
+ console.log(JSON.stringify(diff(before, after, touches), null, 2));
263
+ } else {
264
+ console.error('usage: closing-sweep.mjs capture [--out f] | diff <before> <after> [--touches ids]');
265
+ process.exit(2);
266
+ }
@@ -187,6 +187,41 @@ for config in priorities.yaml environment.yaml contacts.yaml; do
187
187
  fi
188
188
  done
189
189
 
190
+ # Check 9: Artefact stamp freshness — a typed `generated:` must never lead the
191
+ # file's own mtime, and under --strict a stamp that cannot witness same-day
192
+ # freshness (date-only, null, unparseable) must not pass silently either.
193
+ # Typed-shape queue-row stamps are reported by the checker and never gated.
194
+ # `|| STAMP_RC=$?` is load-bearing: `set -e` is on, so an unguarded `$(...)`
195
+ # would abort the whole healthcheck the moment the checker exits non-zero —
196
+ # before this [FAIL] branch and before the summary, so the run would read as
197
+ # DEGRADED with the error count and the CRITICAL verdict never computed.
198
+ if [ -f "$AGENT_DIR/scripts/maintenance/check-stamp-freshness.mjs" ]; then
199
+ STAMP_RC=0
200
+ STAMP_OUT=$(cd "$AGENT_DIR" && node scripts/maintenance/check-stamp-freshness.mjs --strict 2>&1) || STAMP_RC=$?
201
+ if [ "$STAMP_RC" -eq 0 ]; then
202
+ # Summary is the last line on stdout; WEAK/INFO detail precedes it on stderr.
203
+ echo "[OK] Artefact stamps: $(printf '%s' "$STAMP_OUT" | tail -1)"
204
+ elif [ "$STAMP_RC" -eq 2 ] || ! printf '%s\n' "$STAMP_OUT" | grep -Eq '^(OK|OK-WEAK|FAIL): '; then
205
+ # The checker could not run (rc 2), or it died before printing its verdict
206
+ # line (a crash exits 1 like a finding does). Never read "did not measure"
207
+ # as "measured green", and never read a crash as a stamp finding either.
208
+ echo "[FAIL] Artefact stamps NOT CHECKED — checker could not run:"
209
+ printf '%s\n' "$STAMP_OUT" | sed 's/^/ /'
210
+ ERRORS=$((ERRORS + 1))
211
+ elif printf '%s\n' "$STAMP_OUT" | grep -Eq '^(FAIL|LEAD) '; then
212
+ echo "[FAIL] Artefact stamp(s) dated ahead of their own write:"
213
+ printf '%s\n' "$STAMP_OUT" | sed 's/^/ /'
214
+ ERRORS=$((ERRORS + 1))
215
+ else
216
+ echo "[FAIL] Artefact stamp(s) cannot witness same-day freshness (date-only, null or unparseable under --strict):"
217
+ printf '%s\n' "$STAMP_OUT" | sed 's/^/ /'
218
+ ERRORS=$((ERRORS + 1))
219
+ fi
220
+ else
221
+ echo "[WARN] scripts/maintenance/check-stamp-freshness.mjs absent — stamp freshness unchecked"
222
+ WARNINGS=$((WARNINGS + 1))
223
+ fi
224
+
190
225
  # Summary. `Blocking:` / `Warnings:` are the machine-readable contract:
191
226
  # resume-operations.sh parses `Blocking:` to name the condition it refused on.
192
227
  echo ""
@@ -612,6 +612,37 @@ session_beating(){ # is the front door actually ANSWERING, not merely loaded?
612
612
  [ "$age" -le "$SESSION_STALE_S" ]
613
613
  }
614
614
 
615
+ front_door_wedged(){ # is a FRESH critical wedge alert on record — beating, but not reading (risk-2026-09-25-03)?
616
+ # `session_beating` proves the heartbeat is fresh; it proves nothing about
617
+ # inbox consumption. state/org/alert-critical.json is written by the SAME
618
+ # process's own beat loop (lib/org/mesh.mjs#escalateCriticalAlerts) every
619
+ # ~30s while a critical alert is open, INCLUDING a "wedge" kind
620
+ # (lib/telemetry/alerts.mjs#wedgeRule) — the local, path-independent read of
621
+ # exactly the signal that made A029's seat look healthy from presence alone.
622
+ # The file is never deleted, only re-written on the next critical beat, so a
623
+ # RESOLVED wedge would read as still-live forever without the freshness
624
+ # check below.
625
+ local f="$AGENT_DIR/state/org/alert-critical.json"
626
+ [ -f "$f" ] || return 1
627
+ node -e '
628
+ try {
629
+ const j = JSON.parse(require("fs").readFileSync(process.argv[1], "utf8"));
630
+ const at = Date.parse(j && j.at);
631
+ const freshMs = Number(process.argv[2]) * 1000;
632
+ if (!Number.isFinite(at) || (Date.now() - at) > freshMs) process.exit(1);
633
+ const hit = Array.isArray(j.alerts) && j.alerts.some((a) => a && a.kind === "wedge");
634
+ process.exit(hit ? 0 : 1);
635
+ } catch { process.exit(1); }
636
+ ' "$f" "$WEDGE_ALERT_FRESH_S"
637
+ }
638
+
639
+ kickstart_session(){ # the shared "actually restart it" tail for both revive_session branches below
640
+ launchctl kickstart -k "gui/$(id -u)/$SESSION_LABEL" >> "$LOG" 2>&1 \
641
+ && { log "front door $SESSION_LABEL restarted"; return 0; }
642
+ log "WARN: could not kickstart $SESSION_LABEL (maestro session restart --force)"
643
+ return 1
644
+ }
645
+
615
646
  revive_session(){ # a wedged front door cannot restart itself; restart it FOR it
616
647
  # The upgrade notice asks the session to restart "at an idle moment". A
617
648
  # session sitting on a modal never reaches an idle moment, so the polite ask
@@ -624,7 +655,23 @@ revive_session(){ # a wedged front door cannot restart itself; restart it FOR it
624
655
  # session start`), and kickstarting a label launchd does not know just fails.
625
656
  # Leave that one to session_reconciled, which already names it.
626
657
  label_loaded "$SESSION_LABEL" || return 0
627
- session_beating && return 0
658
+ if session_beating; then
659
+ # risk-2026-09-25-03: a fresh beat is not proof of health — it proves the
660
+ # heartbeat process is alive, and nothing about whether it is reading its
661
+ # inbox. Only kickstart on TOP of a fresh beat when a fresh critical wedge
662
+ # alert is on record; otherwise this is the ordinary healthy case.
663
+ front_door_wedged || return 0
664
+ log "front door $SESSION_LABEL is beating but a fresh critical wedge alert is on record (beating but not reading) — confirming over a second read ${SESSION_REVIVE_RECHECK_S}s apart before kickstarting"
665
+ sleep "$SESSION_REVIVE_RECHECK_S"
666
+ # Re-check the WEDGE, not the beat: the beat was never the thing in
667
+ # question here, and re-reading it would tell us nothing new. If the
668
+ # handoff got claimed during the sleep the alert stops being fresh (the
669
+ # daemon's beat loop stops re-writing it) and this reads as cleared.
670
+ front_door_wedged || { log "front door $SESSION_LABEL wedge alert cleared on the second read — leaving it"; return 0; }
671
+ log "front door $SESSION_LABEL still shows a fresh critical wedge alert on the second read — kickstarting it; a beating front door proves nothing about inbox consumption"
672
+ kickstart_session
673
+ return $?
674
+ fi
628
675
  # Two-read hysteresis (see SESSION_REVIVE_RECHECK_S): the first stale read is
629
676
  # not enough to drop a session, because a supervisor resume gaps the beat for
630
677
  # a moment. Confirm the door is STILL silent on a second read 60s later
@@ -647,10 +694,8 @@ revive_session(){ # a wedged front door cannot restart itself; restart it FOR it
647
694
  log "front door $SESSION_LABEL dark past grace while a supervisor (pid $spid) still holds the session lock — parked in its launch probe; hard-kickstarting over it"
648
695
  fi
649
696
  log "front door $SESSION_LABEL not beating on two reads ${SESSION_REVIVE_RECHECK_S}s apart — kickstarting it rather than waiting for a session that cannot answer"
650
- launchctl kickstart -k "gui/$(id -u)/$SESSION_LABEL" >> "$LOG" 2>&1 \
651
- && { log "front door $SESSION_LABEL restarted"; return 0; }
652
- log "WARN: could not kickstart $SESSION_LABEL (maestro session restart --force)"
653
- return 1
697
+ kickstart_session
698
+ return $?
654
699
  }
655
700
 
656
701
  daemon_launchctl_state(){ # "pid" | "dash" | "absent" for DAEMON_LABEL, read from column 1 (PID) of `launchctl list` — a number is a live pid, "-" is loaded-with-no-pid, missing is absent
@@ -1088,6 +1133,17 @@ SESSION_STALE_S="${MAESTRO_SESSION_STALE_S:-90}"
1088
1133
  # gap must not kickstart a session that is mid-resume. The two reads are 60s
1089
1134
  # apart; the hourly backstop can afford the one wait.
1090
1135
  SESSION_REVIVE_RECHECK_S="${MAESTRO_SESSION_REVIVE_RECHECK_S:-60}"
1136
+ # How fresh a critical "wedge" alert (state/org/alert-critical.json, kind
1137
+ # "wedge" — lib/org/mesh.mjs#escalateCriticalAlerts, fed by
1138
+ # lib/telemetry/alerts.mjs#wedgeRule reading machine.wedge from
1139
+ # lib/telemetry/collect.sessionWedge) must be for `front_door_wedged` to trust
1140
+ # it. risk-2026-09-25-03: a front door can be BEATING (session_beating true)
1141
+ # while unable to read its inbox — claudeAuth ok, state=idle, indistinguishable
1142
+ # from a seat between tasks — so a fresh beat alone is not proof of health.
1143
+ # 90s — the same 3x-the-30s-beat-cadence margin as SESSION_STALE_S above, so a
1144
+ # wedge that cleared is not read as still-live off a stale flag file (the file
1145
+ # is never deleted, only re-written on the next critical beat).
1146
+ WEDGE_ALERT_FRESH_S="${MAESTRO_WEDGE_ALERT_FRESH_S:-90}"
1091
1147
  failed_hold_reason(){ # prints "<reason> at <at>" when LATEST failed health within FAILED_HOLD_S
1092
1148
  node -e '
1093
1149
  const [file, latest, holdS] = process.argv.slice(1);