@cohortapp/agent-sdk 2.18.36 → 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.
Files changed (39) hide show
  1. package/bin/maestro.mjs +3 -0
  2. package/docs/guides/billing-console-keys.md +16 -3
  3. package/docs/runbooks/cadence-requeue-storm-recovery.md +186 -0
  4. package/lib/assurance/first-reply.mjs +47 -2
  5. package/lib/assurance/notice-plane.mjs +218 -0
  6. package/lib/assurance/notice-voice.mjs +35 -2
  7. package/lib/assurance/operator-plane-store.mjs +164 -0
  8. package/lib/assurance/operator-plane.mjs +689 -0
  9. package/lib/budget-escalate.mjs +42 -4
  10. package/lib/budget-guard.mjs +24 -1
  11. package/lib/cadence-bus.mjs +359 -46
  12. package/lib/cli/attention.mjs +300 -0
  13. package/lib/cli/seat-auth.mjs +86 -6
  14. package/lib/comms/machine-status.mjs +377 -0
  15. package/lib/comms/send-gate.mjs +309 -2
  16. package/lib/org/awareness.mjs +15 -2
  17. package/lib/org/clause-match.mjs +470 -0
  18. package/lib/org/client.mjs +27 -1
  19. package/lib/org/escalation-chain.mjs +134 -0
  20. package/lib/org/first-run.mjs +263 -0
  21. package/lib/org/genesis-contract.mjs +271 -0
  22. package/lib/org/governance-runtime.mjs +409 -0
  23. package/lib/org/governance-store.mjs +238 -0
  24. package/lib/org/governance.mjs +326 -0
  25. package/lib/org/mesh.mjs +135 -0
  26. package/lib/org/protocol.checksum +1 -1
  27. package/lib/org/protocol.mjs +6 -0
  28. package/lib/org/tool-surface.mjs +28 -0
  29. package/lib/setup/enroll-from-cohort.mjs +11 -0
  30. package/lib/telemetry/alerts.mjs +12 -0
  31. package/lib/telemetry/collect.mjs +237 -1
  32. package/package.json +1 -1
  33. package/scripts/ci/check-durable-write-seam.mjs +3 -3
  34. package/scripts/daemon/agent-daemon.mjs +41 -2
  35. package/scripts/daemon/assurance.mjs +852 -49
  36. package/scripts/daemon/cadence-consumer.mjs +182 -9
  37. package/scripts/daemon/context-compiler.mjs +25 -0
  38. package/scripts/daemon/deliver.mjs +172 -2
  39. package/scripts/fleet/closing-sweep.mjs +266 -0
@@ -0,0 +1,300 @@
1
+ /**
2
+ * lib/cli/attention.mjs — `maestro attention list|clusters|show <key>`.
3
+ *
4
+ * THE SINK HAD TWO WRITERS AND NO READER.
5
+ *
6
+ * `lib/assurance/notice-plane.mjs` moved every machine-status notice off the
7
+ * human path and into the operator plane, and gave reason #4 for why that was
8
+ * safe: the `needs-attention` row "already works and was always written in
9
+ * parallel… What was missing was never information; it was a person looking at
10
+ * the sink."
11
+ *
12
+ * Nobody was looking. Measured on this seat the next day: 78 rows,
13
+ * 26 Aug → 1 Oct, five weeks unswept, two writers (`assurance.escalate` and
14
+ * `agent-daemon.mjs`) and **zero readers** — no CLI command, no MCP tool, no
15
+ * doctor check, no cadence. The one thing that lifted anything off the box,
16
+ * `lib/daemon/reply-debt.mjs`, reads three reply-path counters, and the dominant
17
+ * population here (94% `no_outcome`) is not among them.
18
+ *
19
+ * So the plane's own argument was load-bearing on a reader that did not exist.
20
+ * This is it.
21
+ *
22
+ * ── PUSH AND POLL, NOT ONE OR THE OTHER ─────────────────────────────────────
23
+ *
24
+ * A command is the WRONG answer on its own, and `lib/cli/skills.mjs` says so in
25
+ * its own header: the skill-approval gate was defined, exported and tested with
26
+ * no caller, and 767 skills were authored and 0 promoted. "Someone will run it"
27
+ * is the same premise as "someone will look at the sink". So the poll surface
28
+ * here is deliberately only half the change — the other half is the summary this
29
+ * plane now puts on the presence beat (`lib/telemetry/collect.mjs` →
30
+ * `machine.operatorPlane`), which already runs every 30 s on every seat and
31
+ * already carries `machine.replyDebt` for the identical "the seat withheld
32
+ * something and nobody downstream knows" problem.
33
+ *
34
+ * And it is NOT routed into the morning brief, the midday sweep or the evening
35
+ * wrap: all three end in a Slack DM to the principal — the person the routing
36
+ * change exists to stop messaging — and `lib/diagnostics/cadence-output-freshness.mjs`
37
+ * records the evening wrap running 4 of 9 days. Re-sending machine status to the
38
+ * owner one day later and in bulk is the same defect from the other side.
39
+ *
40
+ * ── IT GROUPS, BECAUSE A LIST OF 78 TIMEOUTS SAYS NOTHING ───────────────────
41
+ *
42
+ * Two shapes are actionable and neither is a row: "this one ask has failed N
43
+ * times in M hours" (`list`, per obligation, across its whole notice sequence)
44
+ * and "14 asks in one channel all died the same way" (`clusters`, per
45
+ * channel+cause). `lib/cli/skills.mjs` had to make the same correction — it
46
+ * counted per id and missed 117 duplicate files because the real unit was the
47
+ * family.
48
+ *
49
+ * ── AND IT SAYS WHEN IT CANNOT HELP ─────────────────────────────────────────
50
+ *
51
+ * 72 of the 78 rows (92%) have no obligation record left, because rows are never
52
+ * pruned and records are pruned at three days. Those are rendered as
53
+ * UNRESOLVABLE, in their own section, with the reason — not as open incidents.
54
+ * A screen of 72 fixable-looking items that cannot be fixed is how this reader
55
+ * would earn the same neglect as the sink.
56
+ *
57
+ * @module lib/cli/attention
58
+ */
59
+
60
+ import { readOperatorPlane, planeRoot } from "../assurance/operator-plane-store.mjs";
61
+ import { planeAlert, planeKeyMatches } from "../assurance/operator-plane.mjs";
62
+
63
+ export const USAGE = `Usage:
64
+ maestro attention list [--all] [--json] Dead asks, grouped by obligation — worst first
65
+ maestro attention clusters [--json] Grouped by conversation + cause — the room, not the ask
66
+ maestro attention show <key> [--json] One obligation: every notice, in order, with the join
67
+
68
+ --all also show ANSWERED rows (owed, open and unrecoverable always show)
69
+ `;
70
+
71
+ const HOUR = 3_600_000;
72
+
73
+ /** "6h", "4d", "just now" — a duration an operator reads, not a number of ms. */
74
+ function dur(ms) {
75
+ const n = Number(ms);
76
+ if (!Number.isFinite(n) || n < 60_000) return "under a minute";
77
+ if (n < HOUR) return `${Math.round(n / 60_000)}m`;
78
+ if (n < 48 * HOUR) return `${Math.round(n / HOUR)}h`;
79
+ return `${Math.round(n / (24 * HOUR))}d`;
80
+ }
81
+
82
+ function ago(at, now) {
83
+ const t = Number(at);
84
+ if (!Number.isFinite(t)) return "unknown";
85
+ return `${dur(now - t)} ago`;
86
+ }
87
+
88
+ function short(v, n = 60) {
89
+ const s = v == null ? "" : String(v).replace(/\s+/g, " ").trim();
90
+ if (!s) return "";
91
+ return s.length > n ? `${s.slice(0, n - 1)}…` : s;
92
+ }
93
+
94
+ /**
95
+ * The one line that says what this incident IS.
96
+ *
97
+ * The repeat count and the span are first, deliberately: they are the only part
98
+ * a reader can triage on, and the plane's whole purpose was defeated for five
99
+ * weeks by a surface that would have shown the cause label instead — which is
100
+ * `no_outcome` on 94% of the population and therefore carries no information at
101
+ * all.
102
+ */
103
+ function headline(inc, now) {
104
+ const bits = [];
105
+ if (inc.noticeCount > 1) bits.push(`failed ${inc.noticeCount}x over ${dur(inc.spanMs)}`);
106
+ else if (inc.noticeCount === 1) bits.push("failed once");
107
+ if (Number(inc.attempts) > 1) bits.push(`${inc.attempts} attempts`);
108
+ bits.push(inc.cause || "cause not recorded");
109
+ if (Number.isFinite(inc.exitCode)) bits.push(`exit ${inc.exitCode}`);
110
+ bits.push(ago(inc.lastAt, now));
111
+ return bits.join(" · ");
112
+ }
113
+
114
+ function renderIncident(inc, now, write, indent = " ") {
115
+ write(`${indent}${inc.key}\n`);
116
+ write(`${indent} ${headline(inc, now)}\n`);
117
+ const where = [inc.service, inc.channel].filter(Boolean).join(" / ");
118
+ if (where) write(`${indent} in ${short(where, 80)}${inc.sender ? ` · from ${short(inc.sender, 40)}` : ""}\n`);
119
+ const ask = inc.summary || inc.itemPreview;
120
+ if (ask) write(`${indent} asked: ${short(ask, 100)}\n`);
121
+ if (inc.configFault) write(`${indent} config fault: ${inc.configFault} — nothing on this machine can grant it\n`);
122
+ }
123
+
124
+ /**
125
+ * Run `maestro attention …`. Prints a human report or JSON; returns the exit code.
126
+ *
127
+ * Exit codes are a contract, not decoration: `list` returns 0 even when the plane
128
+ * is full, because a reader that fails when it has something to say cannot be put
129
+ * in a pipeline. `show` returns 1 for a key the plane does not know, which is the
130
+ * one case a script needs to branch on.
131
+ *
132
+ * @param {string[]} argv
133
+ * @param {{agentRoot?:string, now?:number, stdout?:Function, readImpl?:Function}} [deps]
134
+ * @returns {Promise<number>}
135
+ */
136
+ export async function attentionCmd(argv = [], deps = {}) {
137
+ const write = deps.stdout || ((s) => process.stdout.write(s));
138
+ const agentRoot = planeRoot(deps);
139
+ const now = Number.isFinite(deps.now) ? Number(deps.now) : Date.now();
140
+ const [sub, ...rest] = argv;
141
+ const json = argv.includes("--json");
142
+ const all = argv.includes("--all");
143
+
144
+ if (!sub || sub === "--help" || sub === "-h") { write(USAGE); return 0; }
145
+
146
+ const read = deps.readImpl || readOperatorPlane;
147
+ const plane = read({ agentRoot, now });
148
+ const incidents = Array.isArray(plane.incidents) ? plane.incidents : [];
149
+ // OWED FIRST, and it is its own bucket rather than a slice of `resolved`.
150
+ // Before this split every `failed`/`undeliverable` ask sat in `resolved`,
151
+ // which `list` hides by default — so the surface read "0 open" to an operator
152
+ // while 78 people were still owed an answer. A bucket that exists but is
153
+ // rendered in no section is the same defect by another route, which is why the
154
+ // headline, the sections and the JSON all name this one.
155
+ const owed = incidents.filter((i) => i.state === "owed");
156
+ const open = incidents.filter((i) => i.state === "open");
157
+ const unresolvable = incidents.filter((i) => i.state === "unresolvable");
158
+ const resolved = incidents.filter((i) => i.state === "resolved");
159
+
160
+ if (sub === "list") {
161
+ if (json) {
162
+ write(`${JSON.stringify({
163
+ ok: true, now, windowMs: plane.windowMs, counts: plane.counts,
164
+ summary: plane.summary, alert: planeAlert(plane.summary),
165
+ incidents: all ? incidents : incidents.filter((i) => i.state !== "resolved"),
166
+ }, null, 2)}\n`);
167
+ return 0;
168
+ }
169
+ if (!incidents.length) {
170
+ write(`Nothing in the operator plane. No dead asks on this seat.\n`);
171
+ return 0;
172
+ }
173
+ // THE HEADLINE IS THE COUNT OF PEOPLE WHO GOT NOTHING, not the count of files.
174
+ write(`${owed.length} owed, ${open.length} open, ${unresolvable.length} unrecoverable, ${resolved.length} answered — ${incidents.length} obligations in the operator plane.\n`);
175
+ const a = planeAlert(plane.summary);
176
+ if (a) write(`${a.severity === "critical" ? "CRITICAL" : "WARNING"}: ${a.detail}\n`);
177
+ if (!plane.journalPresent) {
178
+ // Without the journal there is no sequence, so every "failed Nx" below
179
+ // reads 1 and the reader must not let that pass for a quiet seat.
180
+ write(`\nThere is no notice journal on this seat yet, so no repeat counts are available — only the last state of each row.\n`);
181
+ }
182
+ if (owed.length) {
183
+ // The worst state, so it is first and it is never hidden. "The machine
184
+ // stopped working on it" is not "the person got an answer".
185
+ write(`\nOWED — the work is finished and the person was never answered. These are the ones somebody has to pick up:\n`);
186
+ for (const inc of owed.slice(0, 25)) renderIncident(inc, now, write);
187
+ if (owed.length > 25) write(` … and ${owed.length - 25} more (--json for all)\n`);
188
+ }
189
+ if (open.length) {
190
+ write(`\nOPEN — someone asked, got nothing, and the plane still has the record:\n`);
191
+ for (const inc of open.slice(0, 25)) renderIncident(inc, now, write);
192
+ if (open.length > 25) write(` … and ${open.length - 25} more (--json for all)\n`);
193
+ }
194
+ if (unresolvable.length) {
195
+ // SAY WHY, in the section header rather than per row: the cause is one
196
+ // structural fact about retention, not 72 separate problems.
197
+ write(`\nUNRECOVERABLE — ${unresolvable.length} ${unresolvable.length === 1 ? "row" : "rows"} whose obligation record was pruned at ${dur(plane.windowMs)} while the row was kept forever. What was asked, whether it was retried and how it ended are all gone; these cannot be worked, only acknowledged:\n`);
198
+ for (const inc of unresolvable.slice(0, 10)) {
199
+ write(` ${inc.key} ${inc.cause || "cause not recorded"} · ${ago(inc.lastAt, now)}\n`);
200
+ }
201
+ if (unresolvable.length > 10) write(` … and ${unresolvable.length - 10} more (--json for all)\n`);
202
+ }
203
+ if (all && resolved.length) {
204
+ // Only `answered` reaches this section now. The previous version put
205
+ // `failed` here under a "CLOSED" heading — the author saw that "resolved"
206
+ // was the wrong word and renamed the heading instead of re-classifying the
207
+ // row, so the ask stayed hidden by default. Renaming a label is not
208
+ // re-deciding a destination; that is the same mistake the notice-wording
209
+ // fixes made three times.
210
+ write(`\nANSWERED — the asker got a reply:\n`);
211
+ for (const inc of resolved.slice(0, 25)) {
212
+ write(` ${inc.key} ${inc.outcome || "closed"}${inc.closeNote ? ` (${short(inc.closeNote, 50)})` : ""} · ${ago(inc.closedAt || inc.lastAt, now)}\n`);
213
+ }
214
+ }
215
+ const clusters = (plane.clusters || []).filter((c) => c.keys > 1);
216
+ if (clusters.length) {
217
+ write(`\n${clusters.length} ${clusters.length === 1 ? "conversation has" : "conversations have"} more than one dead ask — \`maestro attention clusters\` for the full grouping:\n`);
218
+ for (const c of clusters.slice(0, 5)) {
219
+ write(` ${String(c.keys).padStart(3)} asks ${short(c.channel, 50)} ${c.cause}\n`);
220
+ }
221
+ }
222
+ write(`\n\`maestro attention show <key>\` for one obligation's whole sequence.\n`);
223
+ return 0;
224
+ }
225
+
226
+ if (sub === "clusters") {
227
+ const clusters = plane.clusters || [];
228
+ if (json) { write(`${JSON.stringify({ ok: true, now, clusters }, null, 2)}\n`); return 0; }
229
+ if (!clusters.length) { write(`Nothing in the operator plane.\n`); return 0; }
230
+ write(`${clusters.length} ${clusters.length === 1 ? "group" : "groups"} across ${incidents.length} obligations, by conversation and cause.\n`);
231
+ write(`A group with many asks and one cause is a fact about the CONVERSATION, not about the asks.\n\n`);
232
+ for (const c of clusters.slice(0, 30)) {
233
+ write(` ${String(c.keys).padStart(3)} asks ${c.cause.padEnd(18)} ${short(c.channel, 46)}\n`);
234
+ const bits = [];
235
+ if (c.open) bits.push(`${c.open} open`);
236
+ if (c.unresolvable) bits.push(`${c.unresolvable} unrecoverable`);
237
+ if (c.owed) bits.push(`${c.owed} owed`);
238
+ if (c.resolved) bits.push(`${c.resolved} answered`);
239
+ if (c.notices > c.keys) bits.push(`${c.notices} notices`);
240
+ if (c.spanMs) bits.push(`over ${dur(c.spanMs)}`);
241
+ write(` ${bits.join(" · ")}\n`);
242
+ }
243
+ if (clusters.length > 30) write(` … and ${clusters.length - 30} more (--json for all)\n`);
244
+ return 0;
245
+ }
246
+
247
+ if (sub === "show") {
248
+ const needle = rest.find((x) => !x.startsWith("--"));
249
+ if (!needle) { write(USAGE); return 2; }
250
+ const hits = incidents.filter((i) => planeKeyMatches(needle, i.key));
251
+ if (!hits.length) { write(`not in the operator plane: ${needle}\n`); return 1; }
252
+ if (hits.length > 1 && !json) {
253
+ write(`${hits.length} obligations match "${needle}":\n`);
254
+ for (const h of hits) write(` ${h.key}\n`);
255
+ return 2;
256
+ }
257
+ const inc = hits[0];
258
+ if (json) { write(`${JSON.stringify({ ok: true, now, incident: inc }, null, 2)}\n`); return 0; }
259
+ write(`${inc.key}\n`);
260
+ write(` state ${inc.state}${inc.outcome ? ` (${inc.outcome})` : ""}\n`);
261
+ write(` ${headline(inc, now)}\n`);
262
+ if (inc.service || inc.channel) write(` where ${[inc.service, inc.channel].filter(Boolean).join(" / ")}\n`);
263
+ if (inc.sender) write(` from ${inc.sender}\n`);
264
+ if (inc.summary) write(` asked ${short(inc.summary, 200)}\n`);
265
+ else if (inc.itemPreview) write(` asked ${short(inc.itemPreview, 200)}\n`);
266
+ if (inc.causes.length > 1) write(` causes ${inc.causes.map((c) => `${c.label} x${c.count}`).join(", ")}\n`);
267
+ // The late-reply fallback's held result: the session's end-of-turn text,
268
+ // which is NOT posted anywhere. This is the owner's copy to decide on.
269
+ if (inc.heldResultPreview) {
270
+ write(` held result ${Number.isFinite(inc.heldResultChars) ? `${inc.heldResultChars} chars, not posted` : "not posted"} — full text in the session log\n`);
271
+ write(` ${short(inc.heldResultPreview, 300)}\n`);
272
+ }
273
+ if (inc.sessionId) write(` session ${inc.sessionId}\n`);
274
+ // The only pointer in the whole plane at something that can distinguish a
275
+ // timeout from a crash from a clean exit that never spoke.
276
+ if (inc.sessionLog) write(` session log ${inc.sessionLog}\n`);
277
+ if (inc.traceId) write(` trace ${inc.traceId}\n`);
278
+ if (inc.configFault) write(` config fault ${inc.configFault} — nothing on this machine can grant it\n`);
279
+ write(` joined row:${inc.hasRow ? "yes" : "no"} journal:${inc.journalLines} record:${inc.hasRecord ? "yes" : "no"}\n`);
280
+ if (inc.state === "unresolvable") {
281
+ write(`\nUNRECOVERABLE: the obligation record was pruned at ${dur(plane.windowMs)} while this row was kept.\nWhat was asked, whether it was retried and how it ended are all gone. There is nothing to work here.\n`);
282
+ }
283
+ if (inc.notices.length) {
284
+ write(`\n notices, in order:\n`);
285
+ for (const n of inc.notices) {
286
+ const when = Number.isFinite(n.at) ? new Date(n.at).toISOString() : "unknown time";
287
+ write(` ${when} ${n.notice}${n.attempt ? ` (attempt ${n.attempt})` : ""}${n.repeat ? " [repeat]" : ""}\n`);
288
+ if (n.statusLine) write(` ${short(n.statusLine, 120)}\n`);
289
+ }
290
+ } else {
291
+ write(`\n No journal lines — nothing recorded the sequence, only the last state.\n`);
292
+ }
293
+ return 0;
294
+ }
295
+
296
+ write(USAGE);
297
+ return 2;
298
+ }
299
+
300
+ export default { attentionCmd, USAGE };
@@ -36,9 +36,18 @@
36
36
  * `.env`, the hostname, the clock, the org directory) is injectable.
37
37
  *
38
38
  * What this module deliberately does NOT do: reach another machine. A seat's
39
- * environment lives on the seat's own box; there is no remote inventory
40
- * mechanism to invent. The fleet report is a TEMPLATE plus paste-able rows,
41
- * which is the honest shape of the job.
39
+ * environment lives on the seat's own box, and nothing here goes and fetches
40
+ * one. ~~"There is no remote inventory mechanism to invent."~~ — amended
41
+ * 2026-10-02: there is one, in the other direction. Seats already beat a status
42
+ * snapshot to the org, so {@link seatAuthBeat} reduces a verdict to the two
43
+ * facts that are safe to transmit (a four-value rail category and a boolean)
44
+ * and `lib/telemetry/collect.mjs` puts them on `machine.seatAuth`. That makes
45
+ * the "which seats are still on subscription OAuth" half of the inventory a
46
+ * QUERY. The Console-side half — which account, which workspace, which cap,
47
+ * which key — is still a human with Console access filling in a template, and
48
+ * no beat will ever carry it: see `seatAuthBeat` for the exhaustive list of
49
+ * what is deliberately not sent, and why a leaked key shape would be far worse
50
+ * than a manual inventory.
42
51
  *
43
52
  * @module lib/cli/seat-auth
44
53
  */
@@ -47,6 +56,9 @@
47
56
 
48
57
  import { hostname as osHostname } from "node:os";
49
58
 
59
+ /** The four rails a seat can be on. The value of `verdict`, and of the beat's `rail`. */
60
+ export const SEAT_AUTH_RAILS = Object.freeze(["api-key", "subscription", "both", "neither"]);
61
+
50
62
  /** The three variables that decide the rail. Order is the report order. */
51
63
  export const SEAT_AUTH_VARS = Object.freeze([
52
64
  "ANTHROPIC_API_KEY",
@@ -179,6 +191,67 @@ export function seatAuthVerdict(env = {}, opts = {}) {
179
191
  };
180
192
  }
181
193
 
194
+ // ---------------------------------------------------------------------------
195
+ // The BEAT shape — the only part of a verdict that may cross the wire
196
+ // ---------------------------------------------------------------------------
197
+
198
+ /**
199
+ * Reduce a verdict to the two facts that are safe to transmit on the presence
200
+ * beat, so the G4 inventory stops being a machine-by-machine tour.
201
+ *
202
+ * WHAT IS SENT, and why only this:
203
+ * `rail` one of {@link SEAT_AUTH_RAILS} — a CATEGORY, four possible
204
+ * values for the whole fleet. It is the answer to "which billing
205
+ * rail", which is the question G4 asks. It is derived from
206
+ * whether three variable names are non-empty; it cannot be
207
+ * inverted into a value, a length, a prefix or a key id, because
208
+ * four enum members cannot encode a credential.
209
+ * `compliant` the boolean health: is this rail the fleet posture for this
210
+ * seat's engine. `api-key` on a claude seat and `neither` on a
211
+ * cohort seat are both true; everything else is false.
212
+ *
213
+ * WHAT IS DELIBERATELY **NOT** SENT, and must not be added later:
214
+ * - **No credential, in any form.** Not the value, not a mask, not a prefix,
215
+ * not a suffix, not a length, not a hash. `mask()` exists in
216
+ * `doctor-checks.mjs` for a LOCAL terminal; nothing masked goes on a wire.
217
+ * - **No key id, and no last-four.** Those identify a key in the Console.
218
+ * They belong in the inventory a human fills in with Console access, which
219
+ * is why `INVENTORY_COLUMNS` has a column for them and this does not.
220
+ * - **No `present`/`absent` variable NAMES.** Harmless one at a time, but a
221
+ * list of a seat's environment variable names is an environment dump by
222
+ * instalments, and `rail` already carries everything the names decide. The
223
+ * names stay on the seat, in `maestro seat-auth`'s local output.
224
+ * - **No account, workspace, organisation or email.** The beat cannot know
225
+ * them (they are Console-side) and must not start guessing them.
226
+ * - **No `level`/`enforced`/`msg`/`remedy`.** `level` and `enforced` are a
227
+ * restatement of `MAESTRO_REQUIRE_CONSOLE_KEY` on that box — a local
228
+ * policy switch, not a property of the seat's auth — and `msg`/`remedy`
229
+ * are free text assembled from variable names, i.e. the one shape in this
230
+ * module that could grow a leak by accident. A reader that wants the
231
+ * prose runs `maestro seat-auth` on the seat.
232
+ *
233
+ * So the beat says "seat 7 is on subscription OAuth and that is not the
234
+ * posture" and nothing else. An operator still needs the Console to find out
235
+ * WHICH account — but they no longer need sixteen SSH sessions to find out
236
+ * which seats to look up.
237
+ *
238
+ * Returns `null` for anything that is not a recognised verdict, so a caller's
239
+ * `if (b) machine.seatAuth = b` drops the field rather than emitting a shape
240
+ * nobody can read.
241
+ *
242
+ * @param {{verdict?:string, compliant?:boolean}} [verdict] from {@link seatAuthVerdict}
243
+ * @returns {{rail:string, compliant:boolean}|null}
244
+ */
245
+ export function seatAuthBeat(verdict) {
246
+ if (!verdict || typeof verdict !== "object") return null;
247
+ const rail = String(verdict.verdict || "");
248
+ if (!SEAT_AUTH_RAILS.includes(rail)) return null;
249
+ // Built field-by-field on purpose. A spread of the verdict would put every
250
+ // future field of `seatAuthVerdict` on the wire the day it is added, which is
251
+ // exactly how a credential-adjacent field reaches the fleet by accident.
252
+ return { rail, compliant: verdict.compliant === true };
253
+ }
254
+
182
255
  // ---------------------------------------------------------------------------
183
256
  // The fleet inventory: a template, and rows that paste into it
184
257
  // ---------------------------------------------------------------------------
@@ -279,9 +352,14 @@ export function fleetInventoryTemplate(o = {}) {
279
352
  lines.push("");
280
353
  lines.push(`Generated by \`maestro seat-auth --fleet\`${generatedAt ? ` at ${generatedAt}` : ""} from ${source}.`);
281
354
  lines.push("");
282
- lines.push("**How to fill this in.** A seat's environment lives on the seat's own machine — there is no");
283
- lines.push("remote inventory and this tool does not pretend otherwise. On EACH machine, in the agent's");
284
- lines.push("directory, run:");
355
+ lines.push("**Start from the fleet view, not from a tour.** Every seat's presence beat carries its verdict");
356
+ lines.push("as `machine.seatAuth = {rail, compliant}` alongside `machine.engine`, so which seats are still");
357
+ lines.push("on subscription OAuth is a query. A seat on an SDK too old to send the field reads as UNKNOWN,");
358
+ lines.push("not clean. The beat carries no credential in any form — not a value, a mask, a key id or even");
359
+ lines.push("the variable names — so the columns below are still filled in by a person.");
360
+ lines.push("");
361
+ lines.push("**How to fill this in.** The rest of a seat's environment lives on the seat's own machine, and");
362
+ lines.push("the Console-side facts live in the Console. On EACH machine, in the agent's directory, run:");
285
363
  lines.push("");
286
364
  lines.push("```sh");
287
365
  lines.push("maestro seat-auth --row");
@@ -450,12 +528,14 @@ export async function runSeatAuth(argv = [], deps = {}) {
450
528
 
451
529
  export default {
452
530
  SEAT_AUTH_VARS,
531
+ SEAT_AUTH_RAILS,
453
532
  REQUIRE_CONSOLE_KEY_VAR,
454
533
  CONSOLE_KEY_REMEDY,
455
534
  RUNBOOK,
456
535
  INVENTORY_COLUMNS,
457
536
  enforcementEnabled,
458
537
  seatAuthVerdict,
538
+ seatAuthBeat,
459
539
  inventoryRow,
460
540
  seatsFromDirectory,
461
541
  fleetInventoryTemplate,