@join-pantheon/cli 0.38.2 → 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
@@ -10,34 +10,49 @@
10
10
  * runtime, runtime/upgrade-probation.json, naming the version it put in place
11
11
  * and the one it kept in runtime/cli.prev. Until that version has been seen to
12
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:
13
+ * or two hours have passed, this file watches it. Only evidence about the
14
+ * release counts (0.38.3, issue #132):
14
15
  *
15
- * - a worker run that ends with a code no stop gives (0, 129, 130, 143), or
16
- * that vanished without ending (killed hard, crashed in native code), counts;
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);
17
22
  * - so does any command whose code cannot even be loaded, or that dies of an
18
23
  * exception nobody caught (a Kiro prompt hook, say);
19
- * - so does a worker that the relay answers but that never came online
20
- * (src/upgrade-probation.ts writes `never_online`).
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.
21
27
  *
22
28
  * FAILS_TO_ROLL_BACK of those, and the next `pantheon` to start puts the kept
23
29
  * version back — two renames, as the upgrade made them — writes
24
30
  * runtime/upgrade-held.json so that release is not taken again on this machine
25
- * (a newer one is), and carries on as the version put back. Nothing here needs
26
- * the relay, the network or any of the release's own compiled code: it runs in
27
- * bin/pantheon.js, before dist/cli.js is loaded, from the stable entry the
28
- * launcher, launchd, systemd and the Windows host all start.
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.
29
38
  *
30
39
  * Anything that goes wrong in here is swallowed: the guard must never be the
31
- * reason pantheon does not start.
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.
32
47
  *
33
48
  * Plain JavaScript, no dependencies, only node: built-ins, sync file calls.
34
- * The file names and fields are shared with src/upgrade-probation.ts (a test
35
- * holds the two together).
49
+ * The file names, fields, limits and the lock are shared with
50
+ * src/upgrade-probation.ts (a test holds the two together).
36
51
  */
37
52
  import { spawnSync } from "node:child_process";
38
- import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
53
+ import { closeSync, constants, existsSync, fstatSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
39
54
  import { homedir } from "node:os";
40
- import { basename, dirname, join } from "node:path";
55
+ import { dirname, join, posix, win32 } from "node:path";
41
56
 
42
57
  export const PROBATION_FILE = "upgrade-probation.json";
43
58
  export const HELD_FILE = "upgrade-held.json";
@@ -45,16 +60,51 @@ export const PROBATION_MS = 2 * 3600_000;
45
60
  export const FAILS_TO_ROLL_BACK = 3;
46
61
  /** exit codes a run ends with when it was told to stop (crash-loop.ts EXPECTED_EXIT_CODES) */
47
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;
48
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;
49
74
 
50
75
  const pidAlive = (pid) => {
51
76
  if (!(pid > 0)) return false;
52
77
  try { process.kill(pid, 0); return true; } catch (e) { return e && e.code === "EPERM"; }
53
78
  };
54
79
  const pause = (ms) => { try { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); } catch { /* */ } };
55
- const readJson = (f) => { try { const v = JSON.parse(readFileSync(f, "utf8")); return v && typeof v === "object" ? v : null; } catch { return null; } };
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 */ } };
56
106
  const writeJson = (f, v) => {
57
- const tmp = `${f}.${process.pid}.${Math.random().toString(16).slice(2, 10)}.tmp`;
107
+ const tmp = `${f}.${process.pid}.${rand()}.tmp`;
58
108
  writeFileSync(tmp, JSON.stringify(v, null, 2) + "\n", { mode: 0o600 });
59
109
  try { renameSync(tmp, f); } catch (e) { try { rmSync(tmp, { force: true }); } catch { /* */ } throw e; }
60
110
  };
@@ -63,19 +113,93 @@ const versionOf = (dir) => { const p = readJson(join(dir, "package.json")); retu
63
113
  const whole = (dir) => ["package.json", join("bin", "pantheon.js"), join("dist", "cli.js")].every((f) => existsSync(join(dir, f)));
64
114
  const isTime = (v) => typeof v === "number" && Number.isFinite(v) && v > 0;
65
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
+
66
138
  /**
67
139
  * The runtime folder a managed install's CLI sits in, from the CLI's own folder,
68
140
  * or null when this is any other install (npm's global, a checkout):
69
141
  * <runtime>/node/lib/node_modules/@join-pantheon/cli macOS, Linux
70
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.
71
167
  */
72
- export function runtimeOf(pkgDir) {
73
- const scope = dirname(pkgDir), nm = dirname(scope);
74
- if (basename(pkgDir) !== "cli" || basename(scope) !== "@join-pantheon" || basename(nm) !== "node_modules") return null;
75
- const up = dirname(nm);
76
- const node = basename(up) === "lib" ? dirname(up) : up;
77
- const runtime = dirname(node);
78
- return basename(node) === "node" && basename(runtime) === "runtime" ? runtime : null;
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 { /* */ }
79
203
  }
80
204
 
81
205
  /** The probation file, every field checked (anything odd: no probation). */
@@ -85,32 +209,102 @@ export function readProbation(runtime) {
85
209
  return {
86
210
  v: 1, to: p.to, at: p.at,
87
211
  ...(typeof p.from === "string" ? { from: p.from } : {}),
88
- runs: Array.isArray(p.runs) ? p.runs.filter((r) => r && Number.isInteger(r.pid) && isTime(r.at)).slice(-KEEP_RUNS) : [],
89
- fails: Array.isArray(p.fails) ? p.fails.filter(isTime).slice(-KEEP_RUNS) : [],
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 } : {}),
90
216
  ...(isTime(p.never_online) ? { never_online: p.never_online } : {}),
91
217
  ...(isTime(p.stop_expected_at) ? { stop_expected_at: p.stop_expected_at } : {}),
92
- ...(isTime(p.stuck) ? { stuck: p.stuck, ...(typeof p.stuck_why === "string" ? { stuck_why: p.stuck_why } : {}) } : {}),
218
+ ...(isTime(p.stuck) ? { stuck: p.stuck, ...(typeof p.stuck_why === "string" ? { stuck_why: p.stuck_why.slice(0, 300) } : {}) } : {}),
93
219
  };
94
220
  }
95
221
 
96
- /** Read, changed, written back; null when there is no probation (or it could not be written). */
97
- function change(runtime, fn) {
98
- const p = readProbation(runtime);
99
- if (!p) return null;
100
- fn(p);
101
- try { writeJson(join(runtime, PROBATION_FILE), p); } catch { return null; }
102
- return p;
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
+ });
103
248
  }
104
249
 
105
250
  /**
106
- * Worker runs that vanished without saying how they ended — their process gone,
107
- * started before no expected stop — become failures.
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.
108
266
  */
109
- function foldLost(p, self, alive) {
267
+ function foldLost(p, alive, mine) {
268
+ let changed = false;
110
269
  for (const r of p.runs) {
111
- if (r.end !== undefined || r.pid === self || alive(r.pid)) continue;
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;
112
273
  r.end = "lost";
113
- if (!(isTime(p.stop_expected_at) && p.stop_expected_at >= r.at)) p.fails.push(r.at);
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 */ }
114
308
  }
115
309
  }
116
310
 
@@ -121,7 +315,7 @@ function takeLock(dir, alive) {
121
315
  catch (e) {
122
316
  if (!e || e.code !== "EEXIST") return false;
123
317
  let pid = 0, age = 0;
124
- try { pid = Number(readFileSync(join(dir, "pid"), "utf8").trim()); } catch { /* */ }
318
+ try { pid = Number((readSmall(join(dir, "pid")) || "").trim()); } catch { /* */ }
125
319
  try { age = Date.now() - statSync(dir).mtimeMs; } catch { continue; }
126
320
  if (alive(pid) ? age < 20 * 60_000 : !pid && age < 10_000) return false;
127
321
  const gone = `${dir}.stale-${process.pid}`;
@@ -131,7 +325,7 @@ function takeLock(dir, alive) {
131
325
  return false;
132
326
  }
133
327
  function dropLock(dir) {
134
- try { if (Number(readFileSync(join(dir, "pid"), "utf8").trim()) === process.pid) rmSync(dir, { recursive: true, force: true }); } catch { /* */ }
328
+ try { if (Number((readSmall(join(dir, "pid")) || "").trim()) === process.pid) rmSync(dir, { recursive: true, force: true }); } catch { /* */ }
135
329
  }
136
330
 
137
331
  /** A rename retried for a few seconds: Windows refuses one while a scanner holds a file. */
@@ -151,6 +345,32 @@ function clearWorkerStarts(home) {
151
345
  } catch { /* counted once more, at worst */ }
152
346
  }
153
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
+
154
374
  /**
155
375
  * Put the kept version back. Returns the path of its dist/cli.js when it is in
156
376
  * place, else null (and the version on probation keeps running; the next start
@@ -163,19 +383,33 @@ export function rollBack(pkgDir, runtime, p, o = {}) {
163
383
  const log = o.log || ((line) => { try { process.stderr.write(`${line}\n`); } catch { /* */ } });
164
384
  const prev = join(runtime, "cli.prev"), failed = join(runtime, "cli.failed"), lock = join(runtime, ".upgrade.lock");
165
385
  const held = join(runtime, HELD_FILE);
166
- if (!takeLock(lock, alive)) return null;
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
+ }
167
395
  try {
168
- const back = whole(prev) ? versionOf(prev) : null;
169
- if (!back || back === p.to) {
170
- // Nothing to go back to: said once (here and in the file doctor reads), and not tried again.
171
- const why = !back ? "no previous version is kept beside it" : "the version kept beside it is the same release";
172
- change(runtime, (q) => { q.stuck = now; q.stuck_why = why; });
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; });
173
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`);
174
404
  return null;
175
405
  }
406
+ const back = versionOf(prev);
176
407
  // Written first: cut off between the renames below, the launcher (or the
177
408
  // Windows host) moves cli.prev into place by itself, and this says why.
178
- try { writeJson(held, { v: 1, version: p.to, back_to: back, at: now, why: p.never_online ? "never_online" : "failed_starts" }); } catch { /* the swap still helps */ }
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 */ }
179
413
  if (existsSync(failed)) { try { rmSync(failed, { recursive: true, force: true }); } catch { /* */ } }
180
414
  if (existsSync(failed) || !renameRetry(pkgDir, failed, io)) {
181
415
  try { rmSync(held, { force: true }); } catch { /* */ }
@@ -187,7 +421,7 @@ export function rollBack(pkgDir, runtime, p, o = {}) {
187
421
  if (renameRetry(failed, pkgDir, io)) { try { rmSync(held, { force: true }); } catch { /* */ } }
188
422
  return null;
189
423
  }
190
- try { rmSync(join(runtime, PROBATION_FILE), { force: true }); } catch { /* */ }
424
+ endProbation(runtime, p.to);
191
425
  try { rmSync(failed, { recursive: true, force: true }); } catch { /* the next upgrade removes it */ }
192
426
  clearWorkerStarts(o.home || process.env.PANTHEON_HOME || join(homedir(), ".pantheon"));
193
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`);
@@ -213,26 +447,49 @@ export function guard(pkgDir, argv = process.argv.slice(2), o = {}) {
213
447
  const version = versionOf(pkgDir);
214
448
  if (!p0 || !version || p0.to !== version) return none; // not the release on probation (the one put back, or a later one)
215
449
  if (p0.stuck) return none;
216
- if (now() - p0.at > PROBATION_MS) { try { rmSync(join(runtime, PROBATION_FILE), { force: true }); } catch { /* */ } return none; }
450
+ if (expired(p0, now())) { endProbation(runtime, version, p0.at); return none; }
217
451
  const due = (p) => !!p.never_online || p.fails.length >= FAILS_TO_ROLL_BACK;
218
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;
219
456
 
220
- const p = change(runtime, (q) => foldLost(q, process.pid, alive)) || p0;
221
- if (due(p)) { const e = back(p); if (e) return { entry: e, importFailed: () => false }; }
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
+ }
222
465
 
223
466
  const worker = argv[0] === "worker" && argv[1] !== "token";
467
+ const proc = o.proc || process;
224
468
  let counted = false;
225
- const fail = () => { if (counted) return; counted = true; change(runtime, (q) => { q.fails.push(now()); }); };
226
- if (worker) change(runtime, (q) => { q.runs.push({ pid: process.pid, at: now() }); q.runs = q.runs.slice(-KEEP_RUNS); });
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); });
227
473
  if (!o.passive) {
228
474
  let crashed = false;
229
- try { process.on("uncaughtExceptionMonitor", () => { crashed = true; }); } catch { /* */ }
230
- process.on("exit", (code) => {
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) => {
231
488
  try {
232
489
  const expected = EXPECTED_EXIT_CODES.includes(code) || globalThis.__pantheonExpectedExit === true;
233
490
  if (worker) {
234
- change(runtime, (q) => {
235
- const r = q.runs.find((x) => x.pid === process.pid && x.end === undefined);
491
+ change(runtime, version, (q) => {
492
+ const r = ownRun(q);
236
493
  if (r) r.end = code;
237
494
  if (!counted && (crashed || !expected)) { counted = true; q.fails.push(now()); }
238
495
  });
@@ -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",