@join-pantheon/cli 0.38.1 → 0.38.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.
package/README.md CHANGED
@@ -397,7 +397,8 @@ peer's machine was answered in **31 seconds with no human involved**, and:
397
397
  no restart; `--idle` sets it for one worker). The teammate who asked is told when to expect it:
398
398
  the `pantheon_send` result for an ASK, `pantheon status` and the board say "Rohit's agent will
399
399
  pick this up in about 2 minutes", "Rohit is at his keyboard…", that his worker is offline, or
400
- that his machine can't take requests yet (no agent CLI installed or signed in)
400
+ that his machine can't take requests yet (no agent CLI installed or signed in, or one that
401
+ cannot start)
401
402
  4. nothing has ever reported and no hook is installed here → any open window wins (the
402
403
  conservative fallback); with the hook installed, silence reads as idle
403
404
  5. otherwise the worker claims the work — after a 20-second grace while a window is open,
@@ -467,6 +468,14 @@ run never fails on an expired session when another agent could have answered. If
467
468
  signed in, the first on PATH runs and the alert says exactly that, with the sign-in command.
468
469
  `pantheon doctor` shows the same choice (`worker agent`).
469
470
 
471
+ A name on PATH is not a program that starts. Before an agent is chosen it is asked its `--version`
472
+ — no model, a few seconds at most, remembered for hours and asked again when its file changes. One
473
+ that cannot start here (VS Code's stand-in for the Copilot CLI, an npm launcher whose Node is gone,
474
+ a file that is not runnable) is skipped and named like one that is not signed in. If it is the only
475
+ agent, or the one you pinned, no run is started: you are told once (`pantheon status` and
476
+ `pantheon doctor` say why and the fix), each teammate who asks is told their request waits, and the
477
+ requests run by themselves once it starts. A `--version` that is slow or odd excludes nothing.
478
+
470
479
  **Whichever agent you use answers your teammates while you are away** — Claude Code, Codex, Cursor
471
480
  or Copilot. Claude Code runs inside its own OS sandbox (macOS and Linux, 2.1.83+), so `auto`
472
481
  prefers it when it is installed; Codex, Cursor and Copilot answer too, so a team on any of them is
package/bin/pantheon.js CHANGED
@@ -37,9 +37,24 @@ if (!existsSync(entry)) {
37
37
  process.exit(1);
38
38
  }
39
39
 
40
+ // After an upgrade, a release on probation is watched from here, before any of
41
+ // its own code loads, and the kept version is put back when it keeps failing
42
+ // (upgrade-guard.js, #124). The guard never stops pantheon starting.
43
+ let guarded = { entry, importFailed: () => null };
44
+ try { guarded = (await import("./upgrade-guard.js")).guard(root); } catch { /* no guard: start as before */ }
45
+
40
46
  // A path is not a URL, and on Windows that is fatal rather than pedantic: an
41
47
  // absolute POSIX path happens to work as an import specifier, while `D:\...`
42
48
  // is read as the scheme "d:" and Node refuses it — so `pantheon --version`,
43
49
  // the first command anyone runs, died with ERR_UNSUPPORTED_ESM_URL_SCHEME on
44
50
  // every Windows machine. A real Windows runner is what said so.
45
- await import(pathToFileURL(entry).href);
51
+ try {
52
+ await import(pathToFileURL(guarded.entry).href);
53
+ } catch (e) {
54
+ // A release whose code will not even load: counted, and when that was the
55
+ // last failure allowed, the version put back runs this command instead — in
56
+ // a process of its own, since this one has the failed release's modules
57
+ // loaded under the same paths (upgrade-guard.js rerun).
58
+ if (!guarded.importFailed()) throw e;
59
+ process.exitCode = (await import("./upgrade-guard.js")).rerun(process.argv.slice(1));
60
+ }
@@ -0,0 +1,530 @@
1
+ /**
2
+ * The probation after an upgrade, and the way back (issue #124).
3
+ *
4
+ * A release that answers `--version` but whose worker throws at start, or can
5
+ * never finish the handshake, used to crash-loop on every machine that took it:
6
+ * launchd's KeepAlive, systemd's Restart=always and the Windows host restarted it
7
+ * for ever, and a broken worker can never fetch the release that fixes it.
8
+ *
9
+ * So the upgrade (src/upgrade.ts stagedManagedUpgrade) leaves a mark beside the
10
+ * runtime, runtime/upgrade-probation.json, naming the version it put in place
11
+ * and the one it kept in runtime/cli.prev. Until that version has been seen to
12
+ * work (a worker that reached the relay and stayed a minute: src/crash-loop.ts),
13
+ * or two hours have passed, this file watches it. Only evidence about the
14
+ * release counts (0.38.3, issue #132):
15
+ *
16
+ * - a worker run that ends with a code no stop gives (0, 129, 130, 143) counts.
17
+ * A stop never does, at any moment: the stop signals are answered from here
18
+ * until the release's own code answers them (coverStops);
19
+ * - a worker run that vanished without ending itself (killed hard, crashed in
20
+ * native code, the computer shut down under it) counts only while no worker
21
+ * run of this release has yet stayed up a minute here (foldLost says why);
22
+ * - so does any command whose code cannot even be loaded, or that dies of an
23
+ * exception nobody caught (a Kiro prompt hook, say);
24
+ * - so does a worker that the relay answers but whose hellos never got any
25
+ * reply from it (src/upgrade-probation.ts writes `never_online`). A worker
26
+ * the relay turns away has reached it, and is never marked.
27
+ *
28
+ * FAILS_TO_ROLL_BACK of those, and the next `pantheon` to start puts the kept
29
+ * version back — two renames, as the upgrade made them — writes
30
+ * runtime/upgrade-held.json so that release is not taken again on this machine
31
+ * (a newer one is), and carries on as the version put back. It goes back only to
32
+ * a kept version that is whole, has what it needs to run, and is the one the
33
+ * mark says the upgrade came from: otherwise the release stays, and the mark
34
+ * says `stuck` with the reason, which `pantheon doctor` shows. Nothing here
35
+ * needs the relay, the network or any of the release's own compiled code: it
36
+ * runs in bin/pantheon.js, before dist/cli.js is loaded, from the stable entry
37
+ * the launcher, launchd, systemd and the Windows host all start.
38
+ *
39
+ * Anything that goes wrong in here is swallowed: the guard must never be the
40
+ * reason pantheon does not start, nor make a start wait. A mark or a hold that
41
+ * is not a plain file (a folder, a FIFO, a socket) is read as no file, without
42
+ * ever being opened in a way that can block.
43
+ *
44
+ * Several processes rewrite the mark (every start, every worker's end, the
45
+ * compiled side): each read-change-write is made under a short lock
46
+ * (withMarkLock), so none loses another's.
47
+ *
48
+ * Plain JavaScript, no dependencies, only node: built-ins, sync file calls.
49
+ * The file names, fields, limits and the lock are shared with
50
+ * src/upgrade-probation.ts (a test holds the two together).
51
+ */
52
+ import { spawnSync } from "node:child_process";
53
+ import { closeSync, constants, existsSync, fstatSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
54
+ import { homedir } from "node:os";
55
+ import { dirname, join, posix, win32 } from "node:path";
56
+
57
+ export const PROBATION_FILE = "upgrade-probation.json";
58
+ export const HELD_FILE = "upgrade-held.json";
59
+ export const PROBATION_MS = 2 * 3600_000;
60
+ export const FAILS_TO_ROLL_BACK = 3;
61
+ /** exit codes a run ends with when it was told to stop (crash-loop.ts EXPECTED_EXIT_CODES) */
62
+ export const EXPECTED_EXIT_CODES = [0, 129, 130, 143];
63
+ /** a worker run still up this long after it started shows the release starts here (foldLost) */
64
+ export const STEADY_RUN_MS = 60_000;
65
+ /** a mark dated further ahead than this is not a probation: its two hours could never be told to be over */
66
+ export const CLOCK_SLACK_MS = 60_000;
67
+ /** the lock every rewrite of the mark is made under, how old a lock nobody lets go of is, and how long a start waits for one */
68
+ export const MARK_LOCK = `${PROBATION_FILE}.lock`;
69
+ export const LOCK_STALE_MS = 10_000;
70
+ export const LOCK_WAIT_MS = 400;
71
+ const KEEP_RUNS = 20;
72
+ /** no mark or hold is anywhere near this size: a larger file there is not one */
73
+ const MAX_STATE_BYTES = 1_000_000;
74
+
75
+ const pidAlive = (pid) => {
76
+ if (!(pid > 0)) return false;
77
+ try { process.kill(pid, 0); return true; } catch (e) { return e && e.code === "EPERM"; }
78
+ };
79
+ const pause = (ms) => { try { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); } catch { /* */ } };
80
+ const rand = () => Math.random().toString(16).slice(2, 10);
81
+
82
+ /**
83
+ * A small state file's text, or null — only ever from a plain file. A folder, a
84
+ * FIFO, a socket or a device where the file should be is no file: a FIFO opened
85
+ * for reading waits for a writer for ever, and with it every `pantheon` on the
86
+ * machine (seen in review: one named upgrade-probation.json hung every start).
87
+ * stat does not open it; the open after it cannot wait either (O_NONBLOCK), in
88
+ * case the file was swapped in between, and what was opened is looked at again.
89
+ */
90
+ export function readSmall(f) {
91
+ let fd;
92
+ try {
93
+ if (!statSync(f).isFile()) return null;
94
+ fd = openSync(f, constants.O_RDONLY | (constants.O_NONBLOCK || 0));
95
+ const st = fstatSync(fd);
96
+ if (!st.isFile() || st.size > MAX_STATE_BYTES) return null;
97
+ return readFileSync(fd, "utf8").replace(/^/, "");
98
+ } catch { return null; }
99
+ finally { if (fd !== undefined) { try { closeSync(fd); } catch { /* */ } } }
100
+ }
101
+ const readJson = (f) => {
102
+ try { const t = readSmall(f); const v = t === null ? null : JSON.parse(t); return v && typeof v === "object" && !Array.isArray(v) ? v : null; } catch { return null; }
103
+ };
104
+ /** Whatever sits where a file is about to be written and is not a file (a folder, a FIFO) goes: it was never Pantheon's. */
105
+ const clearNotFile = (f) => { try { const st = lstatSync(f); if (!st.isFile() && !st.isSymbolicLink()) rmSync(f, { recursive: true, force: true }); } catch { /* nothing there */ } };
106
+ const writeJson = (f, v) => {
107
+ const tmp = `${f}.${process.pid}.${rand()}.tmp`;
108
+ writeFileSync(tmp, JSON.stringify(v, null, 2) + "\n", { mode: 0o600 });
109
+ try { renameSync(tmp, f); } catch (e) { try { rmSync(tmp, { force: true }); } catch { /* */ } throw e; }
110
+ };
111
+ const versionOf = (dir) => { const p = readJson(join(dir, "package.json")); return p && typeof p.version === "string" ? p.version : null; };
112
+ /** a whole CLI folder: its manifest, its entry and its build (upgrade.ts `whole`) */
113
+ const whole = (dir) => ["package.json", join("bin", "pantheon.js"), join("dist", "cli.js")].every((f) => existsSync(join(dir, f)));
114
+ const isTime = (v) => typeof v === "number" && Number.isFinite(v) && v > 0;
115
+
116
+ /**
117
+ * Semver order: -1, 0 or 1, a release after its own candidates (0.38.3 after
118
+ * 0.38.3-rc.1); null when either is not a version.
119
+ */
120
+ export function compareVersions(a, b) {
121
+ const re = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
122
+ const x = re.exec(String(a)), y = re.exec(String(b));
123
+ if (!x || !y) return null;
124
+ for (let i = 1; i <= 3; i++) { const d = Number(x[i]) - Number(y[i]); if (d) return d < 0 ? -1 : 1; }
125
+ if (!x[4] || !y[4]) return x[4] ? -1 : y[4] ? 1 : 0;
126
+ const p = x[4].split("."), q = y[4].split(".");
127
+ for (let i = 0; i < Math.max(p.length, q.length); i++) {
128
+ if (p[i] === undefined) return -1;
129
+ if (q[i] === undefined) return 1;
130
+ const pn = /^\d+$/.test(p[i]), qn = /^\d+$/.test(q[i]);
131
+ if (pn && qn) { const d = Number(p[i]) - Number(q[i]); if (d) return d < 0 ? -1 : 1; }
132
+ else if (pn !== qn) return pn ? -1 : 1;
133
+ else if (p[i] !== q[i]) return p[i] < q[i] ? -1 : 1;
134
+ }
135
+ return 0;
136
+ }
137
+
138
+ /**
139
+ * The runtime folder a managed install's CLI sits in, from the CLI's own folder,
140
+ * or null when this is any other install (npm's global, a checkout):
141
+ * <runtime>/node/lib/node_modules/@join-pantheon/cli macOS, Linux
142
+ * <runtime>\node\node_modules\@join-pantheon\cli Windows
143
+ * Windows names are compared the way Windows compares them, whatever their
144
+ * letter case (managed.ts managedLayout lowercases too): a path that came back
145
+ * as ...\Runtime\Node\... is the same install, and was not watched at all.
146
+ */
147
+ export function runtimeOf(pkgDir, os = process.platform) {
148
+ const P = os === "win32" ? win32 : posix;
149
+ const name = (p) => (os === "win32" ? P.basename(p).toLowerCase() : P.basename(p));
150
+ const scope = P.dirname(pkgDir), nm = P.dirname(scope);
151
+ if (name(pkgDir) !== "cli" || name(scope) !== "@join-pantheon" || name(nm) !== "node_modules") return null;
152
+ const up = P.dirname(nm);
153
+ const node = name(up) === "lib" ? P.dirname(up) : up;
154
+ const runtime = P.dirname(node);
155
+ return name(node) === "node" && name(runtime) === "runtime" ? runtime : null;
156
+ }
157
+
158
+ /**
159
+ * Run `fn` holding the mark's lock. The lock is a file beside the mark, made
160
+ * only if absent, holding its maker's pid; it is let go by its maker alone. One
161
+ * whose maker is gone, or that nobody let go of for LOCK_STALE_MS (a critical
162
+ * section here is a read and a write), is renamed aside — which only one of
163
+ * several contenders can do — and taken. A start never waits for it longer than
164
+ * LOCK_WAIT_MS: past that `fn` runs without the lock, as every write did before
165
+ * 0.38.3, because a start that hangs is worse than a count that is off by one.
166
+ * The same lock, to the letter, is src/upgrade-probation.ts withMarkLock.
167
+ */
168
+ export function withMarkLock(runtime, fn) {
169
+ const lock = join(runtime, MARK_LOCK);
170
+ const token = `${process.pid} ${rand()}${rand()}`;
171
+ const deadline = Date.now() + LOCK_WAIT_MS;
172
+ let mine = false;
173
+ for (;;) {
174
+ try { writeFileSync(lock, token, { flag: "wx", mode: 0o600 }); mine = true; break; }
175
+ catch (e) {
176
+ const code = e && e.code;
177
+ // Held (or, on Windows, being deleted this instant): wait. Anything else — a folder that takes no file — is no lock to wait for.
178
+ if (code !== "EEXIST" && !(process.platform === "win32" && (code === "EPERM" || code === "EACCES" || code === "EBUSY"))) break;
179
+ }
180
+ breakStaleLock(lock);
181
+ if (Date.now() >= deadline) break;
182
+ pause(2 + Math.floor(Math.random() * 8));
183
+ }
184
+ try { return fn(); }
185
+ finally { if (mine) { try { if (readSmall(lock) === token) rmSync(lock, { force: true }); } catch { /* the next taker finds it stale */ } } }
186
+ }
187
+
188
+ function breakStaleLock(lock) {
189
+ let st;
190
+ try { st = lstatSync(lock); } catch { return; } // let go already: the next try takes it
191
+ // An age either way: a lock dated in the future is not held for ever by its date.
192
+ const age = Math.abs(Date.now() - st.mtimeMs);
193
+ const seen = st.isFile() ? readSmall(lock) : null; // (a folder or a FIFO there is never opened)
194
+ const holder = /^(\d+) /.exec(seen || "");
195
+ // Its maker is gone; or it is not a lock this code wrote (empty for the instant it is being written); or nobody let go of it.
196
+ const stale = age > LOCK_STALE_MS || (holder ? !pidAlive(Number(holder[1])) && age > 50 : age > 1_000);
197
+ if (!stale) return;
198
+ const aside = `${lock}.stale-${process.pid}-${rand()}`;
199
+ try { renameSync(lock, aside); } catch { return; } // another contender took it away first
200
+ // What came away is a newer lock than the one judged (let go and taken again in between): its holder keeps it.
201
+ if (st.isFile() && readSmall(aside) !== seen) { try { linkSync(aside, lock); } catch { /* a newer lock stands */ } }
202
+ try { rmSync(aside, { recursive: true, force: true }); } catch { /* */ }
203
+ }
204
+
205
+ /** The probation file, every field checked (anything odd: no probation). */
206
+ export function readProbation(runtime) {
207
+ const p = readJson(join(runtime, PROBATION_FILE));
208
+ if (!p || typeof p.to !== "string" || !isTime(p.at)) return null;
209
+ return {
210
+ v: 1, to: p.to, at: p.at,
211
+ ...(typeof p.from === "string" ? { from: p.from } : {}),
212
+ runs: Array.isArray(p.runs) ? p.runs.filter((r) => r && typeof r === "object" && Number.isInteger(r.pid) && isTime(r.at)).slice(-KEEP_RUNS) : [],
213
+ // Only failures of this probation: one dated before the upgrade is not this release's.
214
+ fails: Array.isArray(p.fails) ? p.fails.filter((t) => isTime(t) && t >= p.at - CLOCK_SLACK_MS).slice(-KEEP_RUNS) : [],
215
+ ...(isTime(p.steady_at) ? { steady_at: p.steady_at } : {}),
216
+ ...(isTime(p.never_online) ? { never_online: p.never_online } : {}),
217
+ ...(isTime(p.stop_expected_at) ? { stop_expected_at: p.stop_expected_at } : {}),
218
+ ...(isTime(p.stuck) ? { stuck: p.stuck, ...(typeof p.stuck_why === "string" ? { stuck_why: p.stuck_why.slice(0, 300) } : {}) } : {}),
219
+ };
220
+ }
221
+
222
+ /** Over: two hours on — or dated ahead of this computer's clock, where "two hours on" would never come. */
223
+ const expired = (p, now) => now - p.at > PROBATION_MS || p.at - now > CLOCK_SLACK_MS;
224
+
225
+ /**
226
+ * Read, changed, written back, all under the lock — and only the probation of
227
+ * `version` (a newer upgrade's mark, written meanwhile, is never rewritten by an
228
+ * older release's process). `fn` returning false means nothing changed: nothing
229
+ * is written. null when there is no such probation (or it could not be written).
230
+ */
231
+ function change(runtime, version, fn) {
232
+ return withMarkLock(runtime, () => {
233
+ const p = readProbation(runtime);
234
+ if (!p || (version && p.to !== version)) return null;
235
+ if (fn(p) === false) return p;
236
+ try { writeJson(join(runtime, PROBATION_FILE), p); } catch { return null; }
237
+ return p;
238
+ });
239
+ }
240
+
241
+ /** The probation of `version`, started at `at`, is over: its mark goes (never a later upgrade's). */
242
+ function endProbation(runtime, version, at) {
243
+ withMarkLock(runtime, () => {
244
+ const p = readProbation(runtime);
245
+ if (!p || p.to !== version || (at !== undefined && p.at !== at)) return;
246
+ try { rmSync(join(runtime, PROBATION_FILE), { force: true }); } catch { /* */ }
247
+ });
248
+ }
249
+
250
+ /**
251
+ * Worker runs whose process is gone without having said how it ended. The rule,
252
+ * in one sentence: a run that vanished counts against the release only while no
253
+ * worker run of this release has yet stayed up STEADY_RUN_MS on this computer —
254
+ * once one has, the release is known to start here, so a process that
255
+ * disappears was ended from outside and is never counted.
256
+ *
257
+ * Why: a process ended from outside (a force-quit, kill -9, a shutdown, a
258
+ * Windows logoff, a few restarts) looks exactly like one that died in native
259
+ * code, and the first is everyday life while the second is rare. Counting each
260
+ * as one of three failures (0.38.2) let ordinary life undo a healthy release.
261
+ * What still tells them apart is whether the release has ever run: a release
262
+ * whose worker dies at start every time never has a run that lasts a minute,
263
+ * so its vanished runs all count and it goes back; a release that has run for
264
+ * a minute once has shown it starts, and what ends it later is not its code.
265
+ * A run Pantheon itself stopped (stop_expected_at) is never counted either way.
266
+ */
267
+ function foldLost(p, alive, mine) {
268
+ let changed = false;
269
+ for (const r of p.runs) {
270
+ if (r.end !== undefined || mine(r)) continue;
271
+ // Still running. (This process's own pid on a run that is not its own is an earlier process's: pids are used again.)
272
+ if (r.pid !== process.pid && alive(r.pid)) continue;
273
+ r.end = "lost";
274
+ changed = true;
275
+ const stopped = isTime(p.stop_expected_at) && p.stop_expected_at >= r.at;
276
+ if (!stopped && !isTime(p.steady_at)) p.fails.push(r.at);
277
+ }
278
+ return changed;
279
+ }
280
+
281
+ /**
282
+ * A stop is never a failure, at any moment of the process's life. The release's
283
+ * own code answers SIGTERM and SIGHUP (crash-loop.ts exitOnStopSignals) and the
284
+ * worker command SIGINT — but only once it has loaded, a few hundred
285
+ * milliseconds in. A stop before that killed the process with no exit code, and
286
+ * the run, already written down, was read as one that vanished (reproduced in
287
+ * review: SIGTERM at 150 ms counted). So the guard answers them from before the
288
+ * run is written down, ending with the same 128+n. Each handler steps aside the
289
+ * moment anything else listens for its signal — after that listener is in
290
+ * place, never before — so the code that loads later decides exactly as it did
291
+ * (it counts listeners: crash-loop.ts, agents.ts), and there is no instant with
292
+ * nobody listening.
293
+ */
294
+ export function coverStops(proc = process) {
295
+ const stops = [["SIGTERM", 143], ["SIGHUP", 129], ["SIGINT", 130]];
296
+ if (proc.platform === "win32") stops.push(["SIGBREAK", 130]);
297
+ for (const [sig, code] of stops) {
298
+ try {
299
+ const stop = () => { proc.exit(code); };
300
+ const aside = (ev, fn) => {
301
+ if (ev !== sig || fn === stop) return;
302
+ proc.removeListener("newListener", aside);
303
+ queueMicrotask(() => { try { proc.removeListener(sig, stop); } catch { /* */ } });
304
+ };
305
+ proc.on(sig, stop);
306
+ proc.on("newListener", aside);
307
+ } catch { /* a platform without this signal */ }
308
+ }
309
+ }
310
+
311
+ /** Take the upgrade's own lock folder (upgrade.ts realSwapIo.lock): an upgrade under way is never raced. */
312
+ function takeLock(dir, alive) {
313
+ for (let i = 0; i < 2; i++) {
314
+ try { mkdirSync(dir); writeFileSync(join(dir, "pid"), String(process.pid)); return true; }
315
+ catch (e) {
316
+ if (!e || e.code !== "EEXIST") return false;
317
+ let pid = 0, age = 0;
318
+ try { pid = Number((readSmall(join(dir, "pid")) || "").trim()); } catch { /* */ }
319
+ try { age = Date.now() - statSync(dir).mtimeMs; } catch { continue; }
320
+ if (alive(pid) ? age < 20 * 60_000 : !pid && age < 10_000) return false;
321
+ const gone = `${dir}.stale-${process.pid}`;
322
+ try { renameSync(dir, gone); rmSync(gone, { recursive: true, force: true }); } catch { /* the next try says */ }
323
+ }
324
+ }
325
+ return false;
326
+ }
327
+ function dropLock(dir) {
328
+ try { if (Number((readSmall(join(dir, "pid")) || "").trim()) === process.pid) rmSync(dir, { recursive: true, force: true }); } catch { /* */ }
329
+ }
330
+
331
+ /** A rename retried for a few seconds: Windows refuses one while a scanner holds a file. */
332
+ function renameRetry(a, b, io) {
333
+ for (let i = 0; i < 6; i++) {
334
+ try { io.rename(a, b); return true; } catch { if (i < 5) io.sleep(300); }
335
+ }
336
+ return false;
337
+ }
338
+
339
+ /** The crash-loop record (crash-loop.ts) told the worker's next start is not a failure: the start after a way back is a fresh one. */
340
+ function clearWorkerStarts(home) {
341
+ try {
342
+ const f = join(home, "service-starts.json");
343
+ const s = readJson(f);
344
+ if (s && s.worker && Array.isArray(s.worker.starts) && s.worker.starts.length) { s.worker.starts = []; writeJson(f, s); }
345
+ } catch { /* counted once more, at worst */ }
346
+ }
347
+
348
+ /**
349
+ * Why the kept version cannot be gone back to, or null when it can. It is gone
350
+ * back to only when it would run and is the version this upgrade replaced:
351
+ * - whole (manifest, entry, build), and every package its manifest depends on
352
+ * is where Node will look once it is back in place — one kept without its
353
+ * node_modules was put back in review, and then nothing could start at all;
354
+ * - the version the mark says the upgrade came from, when the mark names one;
355
+ * - never the release on probation itself, and never a newer one: a newer
356
+ * version in cli.prev is not what was running before.
357
+ */
358
+ export function prevUnsound(prev, pkgDir, p) {
359
+ const back = whole(prev) ? versionOf(prev) : null;
360
+ if (!back) return "no previous version is kept beside it";
361
+ if (back === p.to) return "the version kept beside it is the same release";
362
+ const man = readJson(join(prev, "package.json"));
363
+ const deps = man && man.dependencies && typeof man.dependencies === "object" ? Object.keys(man.dependencies) : [];
364
+ // Where Node looks from the place it goes back to: its own node_modules, then the one that holds @join-pantheon.
365
+ const roots = [join(prev, "node_modules"), dirname(dirname(pkgDir))];
366
+ const missing = deps.find((d) => !roots.some((r) => existsSync(join(r, d, "package.json"))));
367
+ if (missing) return `the previous version kept beside it is incomplete (${missing} is missing from it)`;
368
+ if (p.from && back !== p.from) return `the version kept beside it is ${back}, not the ${p.from} this computer upgraded from`;
369
+ const order = compareVersions(back, p.to);
370
+ if (order === 1 || (!p.from && order !== -1)) return `the version kept beside it (${back}) is not an older one`;
371
+ return null;
372
+ }
373
+
374
+ /**
375
+ * Put the kept version back. Returns the path of its dist/cli.js when it is in
376
+ * place, else null (and the version on probation keeps running; the next start
377
+ * tries again, or says why it cannot).
378
+ */
379
+ export function rollBack(pkgDir, runtime, p, o = {}) {
380
+ const io = { rename: renameSync, sleep: pause, ...(o.io || {}) };
381
+ const alive = o.alive || pidAlive;
382
+ const now = (o.now || Date.now)();
383
+ const log = o.log || ((line) => { try { process.stderr.write(`${line}\n`); } catch { /* */ } });
384
+ const prev = join(runtime, "cli.prev"), failed = join(runtime, "cli.failed"), lock = join(runtime, ".upgrade.lock");
385
+ const held = join(runtime, HELD_FILE);
386
+ if (!takeLock(lock, alive)) {
387
+ // Another start is going back this instant: given a moment, so this start
388
+ // loads a version that is in place whole, not one being moved. Only for a
389
+ // lock just taken — a going back is over in milliseconds; an upgrade holds
390
+ // the lock for minutes, and no start waits for that.
391
+ const young = () => { try { return Date.now() - statSync(lock).mtimeMs < 5_000; } catch { return false; } };
392
+ for (let i = 0; i < 30 && young(); i++) io.sleep(50);
393
+ return null;
394
+ }
395
+ try {
396
+ // Looked at again, holding the lock: another start may have gone back already.
397
+ const cur = readProbation(runtime);
398
+ if (!cur || cur.to !== p.to || cur.at !== p.at || versionOf(pkgDir) !== p.to) return null;
399
+ const why = prevUnsound(prev, pkgDir, cur);
400
+ if (why) {
401
+ // Nothing sound to go back to: said once (here and in the mark, which doctor reads), and not tried again.
402
+ change(runtime, p.to, (q) => { q.stuck = now; q.stuck_why = why; });
403
+ log(`! pantheon ${p.to} is not working on this computer and cannot go back by itself (${why}). Run the installer again to repair it`);
404
+ return null;
405
+ }
406
+ const back = versionOf(prev);
407
+ // Written first: cut off between the renames below, the launcher (or the
408
+ // Windows host) moves cli.prev into place by itself, and this says why.
409
+ // A folder or a FIFO in its place goes first: with no hold written, the
410
+ // worker took the same release again within the hour (review).
411
+ clearNotFile(held);
412
+ try { writeJson(held, { v: 1, version: p.to, back_to: back, at: now, why: cur.never_online ? "never_online" : "failed_starts" }); } catch { /* the swap still helps */ }
413
+ if (existsSync(failed)) { try { rmSync(failed, { recursive: true, force: true }); } catch { /* */ } }
414
+ if (existsSync(failed) || !renameRetry(pkgDir, failed, io)) {
415
+ try { rmSync(held, { force: true }); } catch { /* */ }
416
+ return null;
417
+ }
418
+ if (!renameRetry(prev, pkgDir, io)) {
419
+ // The release on probation goes back where it was; if even that is refused,
420
+ // the folder is missing and the launcher puts cli.prev in on the next start.
421
+ if (renameRetry(failed, pkgDir, io)) { try { rmSync(held, { force: true }); } catch { /* */ } }
422
+ return null;
423
+ }
424
+ endProbation(runtime, p.to);
425
+ try { rmSync(failed, { recursive: true, force: true }); } catch { /* the next upgrade removes it */ }
426
+ clearWorkerStarts(o.home || process.env.PANTHEON_HOME || join(homedir(), ".pantheon"));
427
+ log(`! pantheon ${p.to} did not work on this computer, so it went back to ${back} by itself. It updates again when a newer release is out`);
428
+ return join(pkgDir, "dist", "cli.js");
429
+ } finally { dropLock(lock); }
430
+ }
431
+
432
+ /**
433
+ * Called by bin/pantheon.js before the CLI is loaded. Returns:
434
+ * entry the dist/cli.js to load (the version put back, after a way back)
435
+ * importFailed() the CLI would not load: counted; true when that was the last
436
+ * failure allowed and the version put back is in place (run it
437
+ * with rerun(): never in this process)
438
+ */
439
+ export function guard(pkgDir, argv = process.argv.slice(2), o = {}) {
440
+ const own = join(pkgDir, "dist", "cli.js");
441
+ const none = { entry: own, importFailed: () => false };
442
+ const runtime = o.runtime === undefined ? runtimeOf(pkgDir) : o.runtime;
443
+ if (!runtime || !existsSync(join(runtime, PROBATION_FILE))) return none;
444
+ const alive = o.alive || pidAlive;
445
+ const now = o.now || Date.now;
446
+ const p0 = readProbation(runtime);
447
+ const version = versionOf(pkgDir);
448
+ if (!p0 || !version || p0.to !== version) return none; // not the release on probation (the one put back, or a later one)
449
+ if (p0.stuck) return none;
450
+ if (expired(p0, now())) { endProbation(runtime, version, p0.at); return none; }
451
+ const due = (p) => !!p.never_online || p.fails.length >= FAILS_TO_ROLL_BACK;
452
+ const back = (p) => rollBack(pkgDir, runtime, p, o);
453
+ // A run written down under this pid before this process began is an earlier process's (pids are used again after a restart).
454
+ const began = Date.now() - Math.round(process.uptime() * 1000) - 2_000;
455
+ const mine = (r) => r.pid === process.pid && r.at >= began;
456
+
457
+ // (Nothing left open to fold: the mark is not touched, and no lock taken — most starts are a hook's or a status line's.)
458
+ const p = (p0.runs.some((r) => r.end === undefined) ? change(runtime, version, (q) => foldLost(q, alive, mine)) : null) || p0;
459
+ if (due(p)) {
460
+ const e = back(p);
461
+ if (e) return { entry: e, importFailed: () => false };
462
+ // Another start went back meanwhile: what is in place now is not the release on probation.
463
+ if (versionOf(pkgDir) !== version) return none;
464
+ }
465
+
466
+ const worker = argv[0] === "worker" && argv[1] !== "token";
467
+ const proc = o.proc || process;
468
+ let counted = false;
469
+ const fail = () => { if (counted) return; counted = true; change(runtime, version, (q) => { q.fails.push(now()); }); };
470
+ // Before the run is written down: from the moment it can be counted, a stop ends it with a code.
471
+ if (worker && !o.passive) coverStops(proc);
472
+ if (worker) change(runtime, version, (q) => { q.runs.push({ pid: process.pid, at: now() }); q.runs = q.runs.slice(-KEEP_RUNS); });
473
+ if (!o.passive) {
474
+ let crashed = false;
475
+ // A reader that went away first (`pantheon ps | true`, a closed terminal) ends a command with EPIPE:
476
+ // that says nothing about the release, and three of them undid a healthy one (0.38.3 review).
477
+ const readerGone = (e) => !!e && typeof e === "object" && (e.code === "EPIPE" || (e.code === "EIO" && e.syscall === "write"));
478
+ try { proc.on("uncaughtExceptionMonitor", (e) => { if (!readerGone(e)) crashed = true; }); } catch { /* */ }
479
+ const ownRun = (q) => { for (let i = q.runs.length - 1; i >= 0; i--) { if (q.runs[i].pid === process.pid && q.runs[i].end === undefined) return q.runs[i]; } return null; };
480
+ if (worker) {
481
+ // Still up a minute on: this release starts here (foldLost). Never keeps the process alive by itself.
482
+ const t = setTimeout(() => {
483
+ try { change(runtime, version, (q) => { const at = now(); if (!isTime(q.steady_at)) q.steady_at = at; const r = ownRun(q); if (r) r.up = at; }); } catch { /* */ }
484
+ }, o.steadyMs === undefined ? STEADY_RUN_MS : o.steadyMs);
485
+ if (t.unref) t.unref();
486
+ }
487
+ proc.on("exit", (code) => {
488
+ try {
489
+ const expected = EXPECTED_EXIT_CODES.includes(code) || globalThis.__pantheonExpectedExit === true;
490
+ if (worker) {
491
+ change(runtime, version, (q) => {
492
+ const r = ownRun(q);
493
+ if (r) r.end = code;
494
+ if (!counted && (crashed || !expected)) { counted = true; q.fails.push(now()); }
495
+ });
496
+ } else if (crashed && !counted) fail();
497
+ } catch { /* never in the way of an exit */ }
498
+ });
499
+ }
500
+ return {
501
+ entry: own,
502
+ importFailed: () => {
503
+ try {
504
+ fail();
505
+ const q = readProbation(runtime);
506
+ if (q && q.to === version && due(q)) return !!back(q);
507
+ } catch { /* */ }
508
+ return false;
509
+ },
510
+ };
511
+ }
512
+
513
+ /** Services the service manager starts again by itself: ended, so it starts the version put back. */
514
+ const SERVICES = ["worker", "notifier", "host", "menubar", "relay"];
515
+
516
+ /**
517
+ * The command again, on the version put back, after the release failed to load
518
+ * in this process. Node keeps a module that failed — and every module of that
519
+ * release that did load — under its path, which is now the version put back's:
520
+ * loading it here would mix the two. A service ends instead (its manager starts
521
+ * it again, on the version put back); any other command — an agent's hook that
522
+ * would otherwise block every prompt — runs once more as a child, its input and
523
+ * output its own. Returns the exit code.
524
+ */
525
+ export function rerun(argv, o = {}) {
526
+ const cmd = argv[1];
527
+ if (SERVICES.includes(cmd)) return 1;
528
+ const r = (o.spawn || spawnSync)(process.execPath, [...process.execArgv, ...argv], { stdio: "inherit", windowsHide: true });
529
+ return typeof r.status === "number" ? r.status : 1;
530
+ }
@@ -46,6 +46,7 @@ const WORKER_WORDS = {
46
46
  kiro_only: "only Kiro is installed, which it cannot run unattended",
47
47
  unsandboxed_off: "it would need to run unsandboxed, which is off",
48
48
  sandbox_unavailable: "the sandbox it needs is not available",
49
+ cannot_start: "its agent's program cannot start there",
49
50
  busy_turn: "its person's own session is mid-turn",
50
51
  recently_active: "its person was active a moment ago",
51
52
  no_signal: "it cannot tell whether its person is at the keyboard",