@cohortapp/agent-sdk 2.18.37 → 2.19.0
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.
- package/bin/maestro.mjs +3 -0
- package/docs/guides/billing-console-keys.md +16 -3
- package/lib/assurance/first-reply.mjs +31 -2
- package/lib/assurance/operator-plane-store.mjs +164 -0
- package/lib/assurance/operator-plane.mjs +689 -0
- package/lib/budget-guard.mjs +24 -1
- package/lib/cli/attention.mjs +300 -0
- package/lib/cli/seat-auth.mjs +86 -6
- package/lib/comms/send-gate.mjs +309 -2
- package/lib/org/awareness.mjs +15 -2
- package/lib/org/clause-match.mjs +470 -0
- package/lib/org/client.mjs +27 -1
- package/lib/org/escalation-chain.mjs +134 -0
- package/lib/org/first-run.mjs +263 -0
- package/lib/org/genesis-contract.mjs +271 -0
- package/lib/org/governance-runtime.mjs +409 -0
- package/lib/org/governance-store.mjs +238 -0
- package/lib/org/governance.mjs +326 -0
- package/lib/org/mesh.mjs +135 -0
- package/lib/org/protocol.checksum +1 -1
- package/lib/org/protocol.mjs +6 -0
- package/lib/org/tool-surface.mjs +28 -0
- package/lib/setup/enroll-from-cohort.mjs +11 -0
- package/lib/telemetry/alerts.mjs +12 -0
- package/lib/telemetry/collect.mjs +237 -1
- package/package.json +1 -1
- package/scripts/daemon/agent-daemon.mjs +41 -2
- package/scripts/daemon/assurance.mjs +482 -55
- package/scripts/daemon/cadence-consumer.mjs +17 -0
- package/scripts/daemon/context-compiler.mjs +25 -0
- package/scripts/daemon/deliver.mjs +71 -5
- package/scripts/fleet/closing-sweep.mjs +266 -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:
|
|
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:
|
|
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:
|
|
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
|
+
}
|