@clagentic/console 1.9.0-beta.2 → 1.9.0-beta.3

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.
@@ -1,25 +1,116 @@
1
1
  #!/usr/bin/env node
2
2
  'use strict';
3
3
 
4
- // verify-installed-build.js — post-merge install assertion (lr-0d45).
4
+ // verify-installed-build.js — post-merge install assertion (lr-0d45),
5
+ // extended by lr-dc9a3b to also check the RUNNING PROCESS.
5
6
  //
6
- // Confirms the globally-installed @clagentic/console build (installed by the
7
- // preceding `npm run install:local-test` post_merge_steps entry) actually
8
- // reflects the merged HEAD commit, rather than trusting a zero exit code from
9
- // `npm install -g` alone. Compares the SHA embedded by scripts/write-build-sha.js
10
- // (baked into the tarball at `prepack` time, so it travels with the package
11
- // that `npm install -g` unpacked) against this working tree's own HEAD SHA at
12
- // the moment loadout-merge runs post_merge_steps (i.e. the merged commit).
7
+ // PART 1 (lr-0d45, unchanged): confirms the globally-installed
8
+ // @clagentic/console build (installed by the preceding
9
+ // `npm run install:local-test` post_merge_steps entry) actually reflects the
10
+ // merged HEAD commit, rather than trusting a zero exit code from
11
+ // `npm install -g` alone. Compares the SHA embedded by
12
+ // scripts/write-build-sha.js (baked into the tarball at `prepack` time, so
13
+ // it travels with the package that `npm install -g` unpacked) against this
14
+ // working tree's own HEAD SHA at the moment loadout-merge runs
15
+ // post_merge_steps (i.e. the merged commit). This is a check of the
16
+ // ARTIFACT ON DISK only.
17
+ //
18
+ // PART 2 (lr-dc9a3b, new): the artifact check above says nothing about
19
+ // which build the RUNNING daemon process actually loaded — Node reads JS at
20
+ // require-time, so a process started before an install cannot be executing
21
+ // code that install just wrote, no matter what build-sha.json now says. On
22
+ // 2026-08-25, PART 1 passed twice while the running daemon served 3-day-old
23
+ // code and logged its own '[daemon] WARNING: this process is serving STALE
24
+ // code' 403 times — nothing consumed that warning. This queries the live
25
+ // daemon over its IPC socket (`clagentic-console --process-build-status`,
26
+ // lib/daemon.js's "get_build_status" case) for the SHA it loaded at its own
27
+ // startup and for the existing stale-inode detector's live result, and
28
+ // fails loudly on either signal of drift. No daemon running is reported as
29
+ // its own distinct, non-failing state (ARTIFACT_ONLY) — there is nothing to
30
+ // compare against yet (e.g. a fresh box that has never started the
31
+ // service), which is different from a daemon that IS running but did not
32
+ // pick up the new build.
33
+ //
34
+ // STALE_PROCESS (lr-71f0c3, new): a FOURTH outcome, distinct from all of the
35
+ // above. A daemon that predates the get_build_status IPC case entirely (i.e.
36
+ // predates lr-dc9a3b itself) cannot answer this query at all — it replies
37
+ // {ok:false, error:"unknown command: get_build_status"} over the socket,
38
+ // which the CLI surfaces as `Failed: unknown command: get_build_status` on
39
+ // stderr with a non-zero exit. That raw transport string reads as a
40
+ // MISSING-CODE defect (the subcommand "isn't wired up") when it is nothing
41
+ // of the kind — the handler IS present (lib/daemon.js:~1640, see
42
+ // test/verify-installed-build-lr-dc9a3b.test.js's tests 7-9), the process
43
+ // just started before the handler existed. This condition recurred three
44
+ // times (PR #411, #412, #414 — see lr-71f0c3): twice it misled a crew agent
45
+ // into treating it as missing code; the third time it aborted a P1 merge's
46
+ // post_merge_steps chain outright, since the raw error was indistinguishable
47
+ // from a genuine tooling failure and the step was on_failure: fail.
48
+ //
49
+ // This is structurally unavoidable, not an edge case: a daemon predating the
50
+ // handler cannot manifest as a SHA mismatch (PROCESS_MISMATCH above) since it
51
+ // cannot answer the SHA question at all. "unknown command" is the ONLY shape
52
+ // this specific staleness can take, and it recurs on every merge until an
53
+ // operator restarts the daemon onto a build that has the handler. Detected
54
+ // here by matching the "unknown command: get_build_status" error text the
55
+ // daemon's default IPC case emits (see lib/daemon.js's default branch) —
56
+ // distinguished from a generic/unexpected failure the same way "no running
57
+ // daemon" already is, one level up in resolveProcessBuildStatus().
58
+ //
59
+ // Treated as NON-FATAL (exit 0), same posture as ARTIFACT_VERIFIED_NO_PROCESS
60
+ // — the primary assertion (artifact matches merged HEAD) already passed by
61
+ // the time this leg runs, and this condition self-resolves the moment the
62
+ // daemon restarts (no operator action this script could gate on would change
63
+ // the outcome faster than a restart already would). Aborting on_failure:fail
64
+ // on it, as happened on PR #414, halts an otherwise-sound merge's post-merge
65
+ // chain on a known, self-resolving, non-code condition. It is NOT read as
66
+ // "verified" — the message says plainly the process build status is UNKNOWN
67
+ // pending a restart, mirroring ARTIFACT_VERIFIED_NO_PROCESS's own "not a
68
+ // failure, but do not read this as verified" framing exactly.
69
+ //
70
+ // Every reported outcome names EXACTLY ONE of "artifact" or "process" (or
71
+ // both) so "verified" is never ambiguous about which one it means — that
72
+ // ambiguity is what let the artifact-only PART 1 result get relayed
73
+ // upstream (NAOMI's post-merge report, HOLDEN's operator relay) as if it
74
+ // meant the running service was fixed.
13
75
  //
14
76
  // Exit codes:
15
- // 0 — installed build-sha.json matches this tree's HEAD.
16
- // 1 — mismatch, or build-sha.json missing/unreadable, or HEAD unresolvable.
17
- // Reported on stderr with both SHAs so the exact drift is visible in
18
- // loadout-merge's captured step output.
77
+ // 0 — ARTIFACT_AND_PROCESS_VERIFIED: installed build-sha.json matches
78
+ // merged HEAD AND the running daemon (if any) loaded that same SHA
79
+ // with no detected stale inodes.
80
+ // — ARTIFACT_VERIFIED_NO_PROCESS: installed build-sha.json matches
81
+ // merged HEAD and no daemon is currently running, so the PROCESS
82
+ // CHECK DID NOT RUN. The service's build status is UNKNOWN, not
83
+ // verified — nothing to compare against yet (e.g. a fresh box that
84
+ // has never started the service). This is not a failure, but it must
85
+ // never be read as "the service is fine".
86
+ // 1 — ARTIFACT_MISMATCH: installed build-sha.json does not match merged
87
+ // HEAD (PART 1's original failure mode, unchanged).
88
+ // — PROCESS_MISMATCH: the artifact matches, but the running daemon's
89
+ // loaded SHA differs from merged HEAD, or the daemon itself reports
90
+ // stale inodes (on-disk JS was replaced out from under it). THIS is
91
+ // the failure mode that would have caught 2026-08-25 at 01:48 — see
92
+ // test/verify-installed-build-lr-dc9a3b.test.js for the
93
+ // demonstrated-failure-before-fix simulation.
94
+ // — STALE_PROCESS (lr-71f0c3): the artifact matches, but the running
95
+ // daemon predates the get_build_status handler itself and cannot
96
+ // answer the query at all. NOT a failure (exit 0, see PART 2's
97
+ // header comment above for the fatal/non-fatal reasoning) — reported
98
+ // plainly with the remedy (restart the daemon), never as the raw
99
+ // 'unknown command' transport string.
100
+ // All failures are reported on stderr with the exact SHAs/flags involved
101
+ // so the drift is visible in loadout-merge's captured step output.
19
102
  //
20
103
  // Run as a SEPARATE post_merge_steps entry (on_failure: fail) after
21
104
  // `npm run install:local-test` — never combined into one shell string, per
22
105
  // loadout-merge's shell-operator-token rejection (merge/post_merge.py).
106
+ //
107
+ // NON-GOAL (lr-dc9a3b task brief): does NOT auto-restart the daemon on a
108
+ // PROCESS_MISMATCH. A restart mid-merge is not obviously correct — on
109
+ // 2026-08-25 a restart at merge time would have killed five in-flight
110
+ // sessions, including the one dispatching the merge. This exits non-zero
111
+ // with a loud, structured, unmissable stderr report instead; an operator or
112
+ // a separate, explicitly-decided automation restarts the daemon. See the
113
+ // PR body for the full trade-off.
23
114
 
24
115
  const fs = require('fs');
25
116
  const path = require('path');
@@ -48,6 +139,80 @@ function resolveInstalledSha() {
48
139
  return { sha: parsed.sha, path: installedPath };
49
140
  }
50
141
 
142
+ // lr-dc9a3b: queries the RUNNING daemon (if any) for the build SHA it
143
+ // actually loaded at startup, via the CLI's --process-build-status
144
+ // subcommand (lib/cli/ipc-subcommands.js's handleProcessBuildStatus,
145
+ // lib/daemon.js's "get_build_status" IPC case). Exposed as its own function
146
+ // (rather than inlined into main()) so a test can call it against a fake
147
+ // `clagentic-console` on PATH instead of a real daemon socket.
148
+ //
149
+ // Returns:
150
+ // { running: false } — no daemon
151
+ // { running: true, stale: true } — daemon
152
+ // running but predates the get_build_status handler (lr-71f0c3) — see
153
+ // this function's STALE_PROCESS handling below
154
+ // { running: true, loadedBuildSha, staleInodes, pid } — daemon
155
+ // answered normally
156
+ //
157
+ // Throws only on a genuinely unexpected failure (the binary isn't on PATH,
158
+ // or it returned output this parser can't make sense of at all) — a daemon
159
+ // that is simply not running, or one that is running but predates this
160
+ // check, is NOT a throw, since both are expected, non-failing states.
161
+ function resolveProcessBuildStatus(cliBin) {
162
+ const bin = cliBin || 'clagentic-console';
163
+ let raw;
164
+ try {
165
+ raw = execFileSync(bin, ['--process-build-status'], {
166
+ stdio: ['ignore', 'pipe', 'pipe'],
167
+ }).toString();
168
+ } catch (err) {
169
+ // handleProcessBuildStatus() exits 1 with {"ok":false,"error":"no
170
+ // running daemon"} on stdout when nothing is listening on the socket —
171
+ // execFileSync throws on that non-zero exit, but the JSON is still on
172
+ // err.stdout. Distinguish "no daemon" from a genuine failure by parsing
173
+ // it rather than treating every non-zero exit as fatal.
174
+ const stdout = err.stdout ? err.stdout.toString() : '';
175
+ try {
176
+ const parsed = JSON.parse(stdout);
177
+ if (parsed && parsed.ok === false && parsed.error === 'no running daemon') {
178
+ return { running: false };
179
+ }
180
+ } catch (_parseErr) {
181
+ // fall through below
182
+ }
183
+
184
+ // lr-71f0c3: a daemon that predates the get_build_status IPC case
185
+ // (i.e. predates lr-dc9a3b's own introduction) does not hit the
186
+ // {ok:false, error:"no running daemon"} shape above at all — it IS
187
+ // running, it just has no case for this command, so lib/daemon.js's
188
+ // default IPC branch replies {ok:false, error:"unknown command:
189
+ // get_build_status"}, and handleProcessBuildStatus (lib/cli/
190
+ // ipc-subcommands.js) surfaces that on stderr as
191
+ // "Failed: unknown command: get_build_status" with exit 1.
192
+ // execFileSync's err.message embeds that stderr text, so match on it
193
+ // directly here (stdout carries no JSON in this path, unlike the "no
194
+ // running daemon" shape above -- the failure is on stderr, from a
195
+ // console.error, not a stdout console.log).
196
+ const stderrText = err.stderr ? err.stderr.toString() : '';
197
+ if (/unknown command:\s*get_build_status/.test(stderrText) ||
198
+ /unknown command:\s*get_build_status/.test(err.message || '')) {
199
+ return { running: true, stale: true };
200
+ }
201
+
202
+ throw new Error(`--process-build-status failed: ${err.message}`);
203
+ }
204
+ const parsed = JSON.parse(raw);
205
+ if (!parsed || typeof parsed.loadedBuildSha === 'undefined') {
206
+ throw new Error(`--process-build-status returned unexpected output: ${raw}`);
207
+ }
208
+ return {
209
+ running: true,
210
+ loadedBuildSha: parsed.loadedBuildSha,
211
+ staleInodes: !!parsed.staleInodes,
212
+ pid: parsed.pid,
213
+ };
214
+ }
215
+
51
216
  function main() {
52
217
  let headSha;
53
218
  try {
@@ -67,14 +232,76 @@ function main() {
67
232
 
68
233
  if (installed.sha !== headSha) {
69
234
  console.error(
70
- `[verify-installed-build] MISMATCH: installed build (${installed.path}) is at ` +
235
+ `[verify-installed-build] ARTIFACT_MISMATCH: installed build (${installed.path}) is at ` +
71
236
  `${installed.sha}, but merged HEAD is ${headSha}. The post-merge install did ` +
72
237
  `not land the merged commit — investigate before trusting the running build.`
73
238
  );
74
239
  process.exit(1);
75
240
  }
76
241
 
77
- console.log(`[verify-installed-build] ok: installed build matches merged HEAD (${headSha})`);
242
+ console.log(`[verify-installed-build] artifact verified: installed build-sha.json matches merged HEAD (${headSha})`);
243
+
244
+ // PART 2 (lr-dc9a3b): the artifact is right; now check whether the
245
+ // RUNNING process actually loaded it. This is the check that would have
246
+ // failed at 2026-08-25 01:48 — see test/verify-installed-build-lr-dc9a3b.test.js.
247
+ let processStatus;
248
+ try {
249
+ processStatus = resolveProcessBuildStatus();
250
+ } catch (err) {
251
+ console.error(`[verify-installed-build] ERROR: could not query the running process's build status: ${err.message}`);
252
+ process.exit(1);
253
+ }
254
+
255
+ if (!processStatus.running) {
256
+ console.log(
257
+ '[verify-installed-build] ARTIFACT_VERIFIED_NO_PROCESS: artifact matches merged HEAD ' +
258
+ `(${headSha}); no daemon is running, so the PROCESS CHECK DID NOT RUN and the process ` +
259
+ 'build status is UNKNOWN -- do not read this as the process/service being verified. ' +
260
+ 'Not a failure: there is no running process to compare against yet.'
261
+ );
262
+ return;
263
+ }
264
+
265
+ if (processStatus.stale) {
266
+ // lr-71f0c3: the running daemon predates the get_build_status handler
267
+ // itself, so it cannot answer this query at all -- structurally
268
+ // unavoidable until it restarts (see this script's header comment for
269
+ // why this is non-fatal, not a code defect, and not surfaced as the raw
270
+ // transport error). This is NOT read as "verified": the build status of
271
+ // the running process is explicitly UNKNOWN pending a restart.
272
+ console.log(
273
+ '[verify-installed-build] STALE_PROCESS: artifact matches merged HEAD ' +
274
+ `(${headSha}); the running daemon does not recognize the get_build_status query, ` +
275
+ 'meaning it predates that handler and has not picked up any build since. The PROCESS build ' +
276
+ 'status is UNKNOWN, NOT VERIFIED (PROCESS check inconclusive) -- restart the daemon to ' +
277
+ 'clear this: systemctl restart clagentic-console (NOT done automatically by this check). ' +
278
+ 'Not a failure: this is expected on first contact with a build that adds a new ' +
279
+ 'PROCESS-status query and self-resolves on restart.'
280
+ );
281
+ return;
282
+ }
283
+
284
+ const processMismatch = processStatus.loadedBuildSha !== headSha;
285
+ if (processMismatch || processStatus.staleInodes) {
286
+ console.error(
287
+ `[verify-installed-build] PROCESS_MISMATCH: the on-disk artifact matches merged HEAD ` +
288
+ `(${headSha}), but the RUNNING daemon (PID ${processStatus.pid}) has NOT loaded it. ` +
289
+ `loadedBuildSha=${processStatus.loadedBuildSha || '(none)'} staleInodes=${processStatus.staleInodes}. ` +
290
+ `The artifact on disk is correct; the SERVICE is still serving the old build. ` +
291
+ `Restart the daemon to load the new build: systemctl restart clagentic-console ` +
292
+ `(NOT done automatically by this check -- see this script's header comment for why).`
293
+ );
294
+ process.exit(1);
295
+ }
296
+
297
+ console.log(
298
+ `[verify-installed-build] ARTIFACT_AND_PROCESS_VERIFIED: installed build-sha.json AND the ` +
299
+ `running daemon (PID ${processStatus.pid}) both match merged HEAD (${headSha}), no stale inodes detected.`
300
+ );
78
301
  }
79
302
 
80
- main();
303
+ module.exports = { resolveHeadSha, resolveInstalledSha, resolveProcessBuildStatus };
304
+
305
+ if (require.main === module) {
306
+ main();
307
+ }