@awebai/oats 0.50.0 → 0.52.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 (132) hide show
  1. package/README.md +1 -0
  2. package/bin/oats.mjs +153 -51
  3. package/docs/capabilities.md +11 -3
  4. package/docs/configuration.md +134 -88
  5. package/docs/desktop-cli-api.md +994 -71
  6. package/docs/desktop-instance-start.md +56 -0
  7. package/docs/desktop.md +10 -7
  8. package/docs/execution-targets.md +230 -59
  9. package/docs/first-team.md +3 -1
  10. package/docs/harness-trust.md +50 -2
  11. package/docs/implementation.md +73 -8
  12. package/docs/integrations.md +9 -8
  13. package/docs/knowledge-reference/acceptance.md +1 -0
  14. package/docs/knowledge-reference/harvester.md +5 -3
  15. package/docs/knowledge-reference/model.md +5 -3
  16. package/docs/knowledge-theory.md +1 -1
  17. package/docs/knowledge.md +43 -7
  18. package/docs/launch-prompt-completion.md +50 -48
  19. package/docs/oats-local.schema.json +4 -3
  20. package/docs/official-catalog.md +4 -4
  21. package/docs/packages.md +14 -14
  22. package/docs/release-lane.md +15 -5
  23. package/docs/release-notes/v0.44.0.md +1 -1
  24. package/docs/release-notes/v0.51.0.md +156 -0
  25. package/docs/release-notes/v0.52.0.md +933 -0
  26. package/docs/schedules.md +91 -4
  27. package/docs/servers.md +21 -2
  28. package/docs/souls-and-instances.md +113 -21
  29. package/docs/tui.md +152 -0
  30. package/docs/workspaces.md +2 -2
  31. package/lib/claim.mjs +266 -0
  32. package/lib/core.mjs +845 -166
  33. package/lib/errors.mjs +170 -0
  34. package/lib/harness-trust-write.mjs +68 -27
  35. package/lib/harness-trust.mjs +34 -16
  36. package/lib/instance-inspect.mjs +40 -11
  37. package/lib/instance-lifecycle.mjs +169 -47
  38. package/lib/launch-preference.mjs +16 -0
  39. package/lib/launch-prompt-completion.mjs +7 -43
  40. package/lib/launch-prompt-evidence.mjs +14 -7
  41. package/lib/launch-prompt-fixtures/README.md +86 -152
  42. package/lib/launch-prompt-fixtures/dev-channel-confirmation.json +50 -0
  43. package/lib/launch-prompt-fixtures.mjs +122 -109
  44. package/lib/launch-prompt-transport.mjs +2 -56
  45. package/lib/launch-prompts.mjs +102 -100
  46. package/lib/schedule-host.mjs +154 -22
  47. package/lib/schedule.mjs +73 -24
  48. package/lib/servers.mjs +20 -4
  49. package/lib/session-viewer.mjs +87 -10
  50. package/lib/system-tools.mjs +39 -0
  51. package/lib/tmux-server-scope.mjs +62 -0
  52. package/lib/triggers.mjs +4 -4
  53. package/lib/workspace.mjs +5 -11
  54. package/lib/worktree-hooks.mjs +116 -23
  55. package/lib/worktree.mjs +89 -102
  56. package/package-catalog.json +3 -3
  57. package/package.json +7 -2
  58. package/packages/client/capability-show-contract.mjs +230 -0
  59. package/packages/client/capability-warnings-contract.mjs +57 -0
  60. package/packages/client/cli-adapter.mjs +548 -0
  61. package/packages/client/cli-environment.mjs +53 -0
  62. package/packages/client/cli-locator.mjs +253 -0
  63. package/packages/client/cli-probe-contract.mjs +47 -0
  64. package/packages/client/client-terms.mjs +60 -0
  65. package/packages/client/deployment-contract.mjs +68 -0
  66. package/packages/client/deployment-data.mjs +483 -0
  67. package/packages/client/deployment-facts.mjs +34 -0
  68. package/packages/client/deployment-label.mjs +76 -0
  69. package/packages/client/deployment-observer.mjs +89 -0
  70. package/packages/client/deployment-panel.mjs +142 -0
  71. package/packages/client/deployment-read-cli.mjs +53 -0
  72. package/packages/client/display-text.mjs +44 -0
  73. package/packages/client/harness-names.mjs +30 -0
  74. package/packages/client/inspect-contract.mjs +62 -0
  75. package/packages/client/instance-acts.mjs +54 -0
  76. package/packages/client/instance-admission.mjs +45 -0
  77. package/packages/client/instance-events-contract.mjs +74 -0
  78. package/packages/client/instance-git-contract.mjs +80 -0
  79. package/packages/client/instance-presentation.mjs +22 -0
  80. package/packages/client/instance-tree.mjs +453 -0
  81. package/packages/client/kernel-environment.mjs +11 -0
  82. package/packages/client/launch-contract.mjs +51 -0
  83. package/packages/client/launch-prompt-outcome.mjs +165 -0
  84. package/packages/client/lifecycle-cli.mjs +61 -0
  85. package/packages/client/lifecycle-contract.mjs +372 -0
  86. package/packages/client/liveness-main.mjs +10 -0
  87. package/packages/client/liveness.mjs +35 -0
  88. package/packages/client/machine-contract.mjs +123 -0
  89. package/packages/client/own-environment.mjs +22 -0
  90. package/packages/client/panel-views.mjs +286 -0
  91. package/packages/client/readiness-contract.mjs +172 -0
  92. package/packages/client/refresh-loop.mjs +52 -0
  93. package/packages/client/remote-address.mjs +126 -0
  94. package/packages/client/remote-roster.mjs +67 -0
  95. package/packages/client/roster-sections.mjs +80 -0
  96. package/packages/client/spawn-apply-cli.mjs +104 -0
  97. package/packages/client/spawn-apply-contract.mjs +183 -0
  98. package/packages/client/spawn-decision.mjs +46 -0
  99. package/packages/client/spawn-messages.mjs +119 -0
  100. package/packages/client/spawn-preview-cli.mjs +32 -0
  101. package/packages/client/spawn-preview-contract.mjs +314 -0
  102. package/packages/client/team-members.mjs +41 -0
  103. package/packages/client/team-rows.mjs +45 -0
  104. package/packages/client/terminal-contract.mjs +57 -0
  105. package/packages/client/tmux-status.mjs +66 -0
  106. package/packages/client/waiting-on-you.mjs +88 -0
  107. package/packages/client/workspace-admission.mjs +45 -0
  108. package/packages/client/workspace-cli.mjs +142 -0
  109. package/packages/client/workspace-views.mjs +147 -0
  110. package/packages/tui/README.md +46 -0
  111. package/packages/tui/bin/tui.mjs +7 -0
  112. package/packages/tui/lib/actions.mjs +29 -0
  113. package/packages/tui/lib/client.mjs +4 -0
  114. package/packages/tui/lib/main.mjs +105 -0
  115. package/packages/tui/lib/term/keys.mjs +323 -0
  116. package/packages/tui/lib/term/screen.mjs +122 -0
  117. package/packages/tui/lib/term/style.mjs +43 -0
  118. package/packages/tui/lib/term/text.mjs +49 -0
  119. package/packages/tui/lib/term/tty.mjs +168 -0
  120. package/packages/tui/lib/term/width.mjs +124 -0
  121. package/packages/tui/lib/views/frame.mjs +62 -0
  122. package/packages/tui/lib/views/help.mjs +28 -0
  123. package/packages/tui/package.json +8 -0
  124. package/skills/oats-getting-started/SKILL.md +29 -22
  125. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-05-channel-seeded.txt +0 -35
  126. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-06-first-after-channel.txt +0 -35
  127. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-07-after-channel-200ms.txt +0 -35
  128. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-08-installed-after-channel-200ms.txt +0 -35
  129. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/manifest.json +0 -77
  130. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/max-bypass-source.json +0 -88
  131. package/lib/launch-prompt-fixtures/structural-completion.json +0 -205
  132. package/lib/launch-prompt-policy.mjs +0 -87
@@ -3,7 +3,41 @@ import { execFileSync, spawn } from "node:child_process";
3
3
  import { randomUUID } from "node:crypto";
4
4
  import { inspectSessionTarget } from "./session-input.mjs";
5
5
 
6
- export function prepareSessionViewer(target, { exec = execFileSync } = {}) {
6
+ /** The kernel feature of `session attach --detach-key` (docs/execution-targets.md, "Inspect,
7
+ * input and attach"): a routed attach sends the flag only to a host that advertises it. */
8
+ export const DETACH_KEY_FEATURE = "session-attach-detach-key";
9
+ /** The status of an attach its detach key ended. Answered only when the key's own binding ran. */
10
+ export const SESSION_DETACHED_EXIT = 20;
11
+ /** The closed grammar of a detach key: Control with a letter other than h, i and m, or one of
12
+ * \ ] ^ _, Meta with a lowercase letter or a digit, or F1 to F12 with at most one modifier.
13
+ * Outside it: C-i and C-m (Tab and Enter), C-h (the byte many terminals send for
14
+ * Ctrl+Backspace, and some for Backspace: not one key everywhere), Escape (C-[), the ESC + C1
15
+ * introducers (M-[, M-], M-\, M-O: a terminal's reply can arrive as one), `Any` and the mouse
16
+ * key names. A closed grammar can be widened later and never narrowed. */
17
+ const DETACH_KEY = /^(?:C-[a-gj-ln-z\\\]^_]|M-[a-z0-9]|(?:[CMS]-)?F(?:[1-9]|1[0-2]))$/;
18
+ /** Whether a value is one detach key: the local and the routed attach both ask here. */
19
+ export function isDetachKey(value) { return typeof value === "string" && DETACH_KEY.test(value); }
20
+ /** The key, or E_BAD_ARGS: called before any tmux or ssh call. */
21
+ export function requireDetachKey(value) {
22
+ if (isDetachKey(value)) return value;
23
+ throw Object.assign(new Error(`--detach-key must be one key: C-<a letter except h, i and m, or one of \\ ] ^ _>, M-<a lowercase letter or digit>, or F1 to F12 with at most one of C-, M-, S- (got ${JSON.stringify(value)})`), { code: "E_BAD_ARGS" });
24
+ }
25
+
26
+ /** The table of a viewer without a detach key: one for the whole tmux server, emptied and bound
27
+ * again by each such viewer. */
28
+ const LOCKED_TABLE = "oatsview-locked";
29
+ /** The mouse bindings of a viewer's key table, the locked one or a keyed viewer's own. */
30
+ const MOUSE_BINDINGS = [
31
+ ["WheelUpPane", "if-shell", "-F", "#{||:#{pane_in_mode},#{mouse_any_flag}}", "send-keys -M", "copy-mode -e; send-keys -M"],
32
+ ["MouseDrag1Pane", "if-shell", "-F", "#{||:#{pane_in_mode},#{mouse_any_flag}}", "send-keys -M", "copy-mode -M"],
33
+ ];
34
+ /** What a detach key runs, as ONE bind-key argument (a bare `;` argument would end bind-key and
35
+ * run the rest at once): mark the viewer session, then detach the client that pressed the key.
36
+ * A constant: no caller text is ever part of a tmux command string. */
37
+ const DETACH_BINDING = "set-option @oats-detached 1 ; detach-client";
38
+
39
+ export function prepareSessionViewer(target, { exec = execFileSync, detachKey } = {}) {
40
+ if (detachKey !== undefined) requireDetachKey(detachKey);
7
41
  if (!inspectSessionTarget(target, { exec }).present) throw new Error("session no longer exists");
8
42
  // UTF-8 mode (-u) like the shared session helper: a service without a
9
43
  // UTF-8 locale (launchd) otherwise mangles tmux output.
@@ -11,7 +45,15 @@ export function prepareSessionViewer(target, { exec = execFileSync } = {}) {
11
45
  encoding: "utf8", timeout: 10000, stdio: ["ignore", "pipe", "pipe"],
12
46
  }).trim();
13
47
  const viewer = `oatsview-${process.pid}-${randomUUID().slice(0, 8)}`;
14
- const cleanup = () => { try { run(["kill-session", "-t", `=${viewer}`]); } catch { /* already detached/ended */ } };
48
+ // A keyed viewer reads a table of its own, named as its session: a binding in the locked table
49
+ // would be every viewer's, and the next viewer's unbind would remove it.
50
+ const table = detachKey === undefined ? LOCKED_TABLE : viewer;
51
+ const cleanup = () => {
52
+ try { run(["kill-session", "-t", `=${viewer}`]); } catch { /* already detached/ended */ }
53
+ // A key table belongs to the tmux server and outlives the session; tmux drops it with its
54
+ // last binding.
55
+ if (table !== LOCKED_TABLE) { try { run(["unbind-key", "-a", "-q", "-T", table]); } catch { /* the server is gone */ } }
56
+ };
15
57
  try {
16
58
  const placeholder = run(["new-session", "-d", "-s", viewer, "-P", "-F", "#{window_id}"]);
17
59
  if (!/^@\d+$/.test(placeholder)) throw new Error("tmux returned no viewer window id");
@@ -20,33 +62,68 @@ export function prepareSessionViewer(target, { exec = execFileSync } = {}) {
20
62
  // One linked window prevents a stale viewer from selecting a sibling agent
21
63
  // when this agent retires. Disable window navigation in the viewer only.
22
64
  for (const name of ["prefix", "prefix2"]) run(["set-option", "-t", viewer, name, "None"]);
23
- run(["set-option", "-t", viewer, "key-table", "oatsview-locked"]);
65
+ run(["set-option", "-t", viewer, "key-table", table]);
24
66
  // The viewer shows one agent; its status line only repeats that name.
25
67
  // Session-scoped on the temporary viewer: the agents' own session and
26
68
  // the operator's tmux settings are untouched.
27
69
  run(["set-option", "-t", viewer, "status", "off"]);
28
- run(["unbind-key", "-a", "-q", "-T", "oatsview-locked"]);
29
- run(["bind-key", "-T", "oatsview-locked", "WheelUpPane", "if-shell", "-F", "#{||:#{pane_in_mode},#{mouse_any_flag}}", "send-keys -M", "copy-mode -e; send-keys -M"]);
30
- run(["bind-key", "-T", "oatsview-locked", "MouseDrag1Pane", "if-shell", "-F", "#{||:#{pane_in_mode},#{mouse_any_flag}}", "send-keys -M", "copy-mode -M"]);
70
+ run(["unbind-key", "-a", "-q", "-T", table]);
71
+ for (const binding of MOUSE_BINDINGS) run(["bind-key", "-T", table, ...binding]);
72
+ // The key is its own argv element, after the grammar admitted it.
73
+ if (detachKey !== undefined) run(["bind-key", "-T", table, detachKey, DETACH_BINDING]);
31
74
  run(["set-option", "-t", viewer, "mouse", "on"]);
32
75
  const env = { ...process.env }; delete env.TMUX;
33
- return { binary: "tmux", args: ["-u", "-S", target.socket, "attach-session", "-t", `=${viewer}`], env, cleanup };
76
+ /** Whether the detach key's binding ran: it marks the viewer session before it detaches. A
77
+ * client that left any other way (its window ended, another client detached it) left no
78
+ * mark, and a session that is gone answers nothing. The target is `=<session>:`:
79
+ * show-options reads -t as a pane, and under -q answers nothing at all for `=<session>`. */
80
+ const detached = () => {
81
+ if (detachKey === undefined) return false;
82
+ try { return run(["show-options", "-t", `=${viewer}:`, "-qv", "@oats-detached"]) === "1"; } catch { return false; }
83
+ };
84
+ return { binary: "tmux", args: ["-u", "-S", target.socket, "attach-session", "-t", `=${viewer}`], env, cleanup, detached };
34
85
  } catch (e) { cleanup(); throw e; }
35
86
  }
36
87
 
37
- export async function attachSessionTarget(target) {
38
- const viewer = prepareSessionViewer(target);
88
+ // SIGQUIT under a keyed attach. The key may be C-\, the tty's QUIT character: pressed before the
89
+ // tmux client has taken the tty, or again once the client has given it back, it reaches this
90
+ // process as SIGQUIT, whose default action ends Node before any `finally` (status 131, the viewer
91
+ // session and its table left on the server). One listener, added by the first keyed attach and
92
+ // never removed, calls whatever the attach in progress set.
93
+ let onQuit = null;
94
+ let quitHeld = false;
95
+ function holdQuit() {
96
+ if (quitHeld) return;
97
+ quitHeld = true;
98
+ process.on("SIGQUIT", () => onQuit?.());
99
+ }
100
+
101
+ /** Attach this terminal to a viewer of the target and answer the client's status, or
102
+ * SESSION_DETACHED_EXIT when `detachKey` was given and ended the attach. */
103
+ export async function attachSessionTarget(target, { detachKey } = {}) {
104
+ if (detachKey !== undefined) { requireDetachKey(detachKey); holdQuit(); }
105
+ const viewer = prepareSessionViewer(target, { detachKey });
39
106
  let child;
107
+ let quit = false;
40
108
  const stop = () => { viewer.cleanup(); child?.kill(); };
41
109
  const signals = ["SIGHUP", "SIGTERM", "SIGINT"];
42
110
  for (const sig of signals) process.on(sig, stop);
111
+ // Until the client has exited, a QUIT stops the attach as the other signals do, with status 1.
112
+ // Unless the key's binding has already run: then the client is on its way out, the QUIT is the
113
+ // key pressed again, and the attach ends as a detach.
114
+ if (detachKey !== undefined) onQuit = () => { if (viewer.detached()) return; quit = true; stop(); };
43
115
  try {
44
- return await new Promise((resolve, reject) => {
116
+ const code = await new Promise((resolve, reject) => {
45
117
  child = spawn(viewer.binary, viewer.args, { env: viewer.env, stdio: "inherit" });
46
118
  child.once("error", reject);
47
119
  child.once("exit", (code) => resolve(code ?? 1));
48
120
  });
121
+ if (quit) return 1;
122
+ return viewer.detached() ? SESSION_DETACHED_EXIT : code;
49
123
  } finally {
124
+ // The client has exited (or never started): a QUIT from here on changes nothing. One that
125
+ // arrives during the calls below waits for them, so cleanup completes and the status stands.
126
+ onQuit = null;
50
127
  for (const sig of signals) process.removeListener(sig, stop);
51
128
  viewer.cleanup();
52
129
  }
@@ -0,0 +1,39 @@
1
+ /** System tools: programs the kernel runs from the system's own directories, never from the
2
+ * caller's PATH. A job, a shell or an instance may have changed PATH; what a system tool does
3
+ * (read a process's start, start the OATS tmux server in its own scope) must not depend on it. */
4
+ import { accessSync, constants, statSync } from "node:fs";
5
+ import { isAbsolute, join } from "node:path";
6
+
7
+ /** Where a system tool is looked for, in order. */
8
+ export const SYSTEM_TOOL_DIRS = Object.freeze(["/usr/bin", "/bin"]);
9
+
10
+ /** The directories a system tool is looked for in → { dirs } | { reason }. SYSTEM_TOOL_DIRS, or for a
11
+ * test only, OATS_TEST_SYSTEM_TOOL_DIRS: absolute directories separated by `:`. A seam with any other
12
+ * value names no tool at all, never a PATH-like lookup. */
13
+ export function systemToolDirs() {
14
+ const seam = process.env.OATS_TEST_SYSTEM_TOOL_DIRS;
15
+ if (seam === undefined) return { dirs: SYSTEM_TOOL_DIRS };
16
+ const dirs = seam.split(":");
17
+ if (dirs.some((dir) => !isAbsolute(dir))) return { reason: `OATS_TEST_SYSTEM_TOOL_DIRS is ${JSON.stringify(seam)}, not absolute directories` };
18
+ return { dirs };
19
+ }
20
+
21
+ /** `name` in the system directories (`dirs`, else systemToolDirs) → { file } (the first regular
22
+ * executable file, an absolute path) or { reason } (none, and where it looked). Nothing is run. */
23
+ export function systemTool(name, { dirs } = {}) {
24
+ if (typeof name !== "string" || !/^[A-Za-z0-9._+-]+$/.test(name) || name === "." || name === "..") return { reason: `${JSON.stringify(name)} is not a tool name` };
25
+ if (dirs === undefined) {
26
+ const where = systemToolDirs();
27
+ if (where.reason) return { reason: where.reason };
28
+ dirs = where.dirs;
29
+ }
30
+ for (const dir of dirs) {
31
+ const file = join(dir, name);
32
+ try {
33
+ if (!statSync(file).isFile()) continue;
34
+ accessSync(file, constants.X_OK);
35
+ return { file };
36
+ } catch { /* not here */ }
37
+ }
38
+ return { reason: `no executable ${name} in ${dirs.join(", ")}` };
39
+ }
@@ -0,0 +1,62 @@
1
+ /** Whether the OATS tmux server starts in a systemd scope of its own (awebai/oats#915).
2
+ * A server started by a process inside a systemd service lives in that service's cgroup and dies
3
+ * when the unit stops: the schedule tick's oneshot, or a Desktop run as a user service. On Linux,
4
+ * from inside a service, on the unified cgroup hierarchy, the server's start runs under
5
+ * `systemd-run --user --scope`: the server is then a sibling of the service, not part of it.
6
+ * Everything else starts the server as before. */
7
+ import { createHash, randomBytes } from "node:crypto";
8
+ import { readFileSync } from "node:fs";
9
+
10
+ const HIERARCHY = "the cgroup hierarchy is not the unified one, so there is no unified cgroup path to judge";
11
+ /** The last component of an absolute cgroup path, when it names a systemd service. */
12
+ function serviceOf(path) {
13
+ if (typeof path !== "string" || !path.startsWith("/")) return null;
14
+ const last = path.split("/").pop();
15
+ return last.endsWith(".service") ? last : null;
16
+ }
17
+
18
+ /** → { wrap: true, unit } (inside `unit`, start the server in its own scope), { wrap: false }, or
19
+ * { wrap: false, warn: { unit, reason } } (inside a service, known only from INVOCATION_ID, on a
20
+ * hierarchy this cannot judge). `cgroup` is the text of /proc/self/cgroup, null when unreadable. */
21
+ export function serverScopePlan({ platform, cgroup, invocationId }) {
22
+ if (platform !== "linux" || typeof cgroup !== "string") return { wrap: false };
23
+ const lines = cgroup.split("\n").filter(Boolean);
24
+ if (lines.length === 1 && lines[0].startsWith("0::") && lines[0].slice(3).startsWith("/")) {
25
+ const unit = serviceOf(lines[0].slice(3));
26
+ return unit ? { wrap: true, unit } : { wrap: false };
27
+ }
28
+ if (!invocationId) return { wrap: false };
29
+ // The service the systemd hierarchy names, when one does: a hybrid host's 0:: line, or v1's name=systemd.
30
+ const named = lines.map((line) => /^(?:0::|\d+:name=systemd:)(\/.*)$/.exec(line)?.[1]).map(serviceOf).find(Boolean);
31
+ return { wrap: false, warn: { unit: named || "a systemd service", reason: HIERARCHY } };
32
+ }
33
+
34
+ /** Where the creator runs → { platform, cgroup, invocationId }: `io`'s when it says, else for a test only
35
+ * OATS_TEST_CGROUP (the text of a /proc/self/cgroup, judged as Linux), else this process's own (null
36
+ * cgroup when it cannot be read, or off Linux). */
37
+ export function creatorPlacement(io) {
38
+ const seam = process.env.OATS_TEST_CGROUP;
39
+ const platform = io?.platform ?? (seam !== undefined ? "linux" : process.platform);
40
+ let cgroup = io?.cgroup;
41
+ if (cgroup === undefined) {
42
+ if (seam !== undefined) cgroup = seam;
43
+ else if (platform === "linux") { try { cgroup = readFileSync("/proc/self/cgroup", "utf8"); } catch { cgroup = null; } }
44
+ else cgroup = null;
45
+ }
46
+ const invocationId = io && "invocationId" in io ? io.invocationId : process.env.INVOCATION_ID;
47
+ return { platform, cgroup, invocationId };
48
+ }
49
+
50
+ /** The scope's name, one per start that starts the server: a prefix per server address (the socket
51
+ * when it is known, else `-L oats` under the TMUX_TMPDIR the tmux client resolves it in, tmux's
52
+ * default /tmp when unset) and a random part. A scope ends with its last process, which is not
53
+ * always the server (a pane's process can outlive it), so a later start never reuses its name. */
54
+ export function serverScopeUnit({ socket, env }) {
55
+ const address = socket ? socket : `-L oats\0${env?.TMUX_TMPDIR || "/tmp"}`;
56
+ return `oats-tmux-${createHash("sha256").update(address).digest("hex").slice(0, 12)}-${randomBytes(4).toString("hex")}`;
57
+ }
58
+
59
+ /** The answer's warning when the server was started inside a service after all. */
60
+ export function serverScopeWarning({ unit, reason }) {
61
+ return `the OATS tmux server was started inside ${unit}: it ends when that unit stops; start the OATS tmux server from your own shell, or enable the user systemd bus (${reason})`;
62
+ }
package/lib/triggers.mjs CHANGED
@@ -39,7 +39,7 @@ import { createHash } from "node:crypto";
39
39
  import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
40
40
  import { dirname, join } from "node:path";
41
41
  import { fileURLToPath } from "node:url";
42
- import { readDefinitions, writeDefinitions, stateDir, withScopeLock, childEnv, parseEnvelopeText, schedulerStatus, readRegistry, definitionsPath } from "./schedule.mjs";
42
+ import { readDefinitions, writeDefinitions, stateDir, withScopeLock, childEnv, parseEnvelopeText, schedulerStatus, readRegistry, definitionsPath, runWarnings } from "./schedule.mjs";
43
43
  import { herdrSettingRemoved } from "./errors.mjs";
44
44
  import { MODEL_RE, SNAPSHOT_MAX_AGE_MS, automationError, baseRow, localEntry, localId, parseOwner, qualifiedId, soulOriginOf, validateDescription } from "./automations.mjs";
45
45
  import { judgeAnswer, pollFailure, triggerSourcesOf } from "./trigger-sources.mjs";
@@ -774,7 +774,7 @@ const isNewEvent = (ts, key) => !ts.fired[key] && !ts.pending[key];
774
774
  const pendingQueue = (ts) => Object.values(ts.pending).map(withSubject).sort((a, b) => a.observedAt.localeCompare(b.observedAt) || a.key.localeCompare(b.key));
775
775
  /** Record a spawned event as fired (only after its spawn succeeded: at least once). */
776
776
  function recordFired(ts, ev, run, now) {
777
- ts.fired[ev.key] = { at: now.toISOString(), instance: run.instance ?? null, home: run.home ?? null, event: ev.event, number: ev.number ?? null, subject: ev.subject };
777
+ ts.fired[ev.key] = { at: now.toISOString(), instance: run.instance ?? null, home: run.home ?? null, event: ev.event, number: ev.number ?? null, subject: ev.subject, ...runWarnings(run) };
778
778
  delete ts.pending[ev.key];
779
779
  ts.lastFiredAt = now.toISOString();
780
780
  }
@@ -882,7 +882,7 @@ export function spawnForEvent(ws, def, ev, io, pv = previewSoul(ws, def, io)) {
882
882
  if (r.timedOut) throw triggerError("E_SPAWN_UNCONFIRMED", "the trigger's spawn timed out; a home may exist (it counts toward concurrency) — the event is retried on the next poll");
883
883
  if (!r.envelope || typeof r.envelope.ok !== "boolean") throw triggerError("E_SPAWN_UNCONFIRMED", `the trigger's spawn answered no envelope (exit ${r.status})${r.stderr ? `: ${r.stderr.trim().split("\n").pop()}` : ""}`);
884
884
  if (!r.envelope.ok) throw triggerError(r.envelope.error?.code || "E_SPAWN_FAILED", String(r.envelope.error?.message || "spawn failed"), { details: r.envelope.error?.details });
885
- return { instance: r.envelope.result?.instance, home: r.envelope.result?.home };
885
+ return { instance: r.envelope.result?.instance, home: r.envelope.result?.home, ...runWarnings(r.envelope.result) };
886
886
  }
887
887
 
888
888
  /** Admission of one pending event against the trigger's concurrency. → null | reason */
@@ -1053,7 +1053,7 @@ function triggerRow(ws, e, st, ctx) {
1053
1053
  const ts = stateFor(st.triggers[e.id], e.definition?.on?.source);
1054
1054
  const fired = Object.entries(ts?.fired || {}).map(([key, f]) => ({ key, ...f })).sort((a, b) => b.at.localeCompare(a.at));
1055
1055
  const pollMs = parsePoll(e.definition?.on?.poll ?? DEFAULT_POLL);
1056
- const lastRun = fired[0] ? { at: fired[0].at, instance: fired[0].instance ?? null, home: fired[0].home ?? null, event: fired[0].event, number: fired[0].number, subject: subjectOf(fired[0]), key: fired[0].key } : null;
1056
+ const lastRun = fired[0] ? { at: fired[0].at, instance: fired[0].instance ?? null, home: fired[0].home ?? null, event: fired[0].event, number: fired[0].number, subject: subjectOf(fired[0]), key: fired[0].key, ...runWarnings(fired[0]) } : null;
1057
1057
  const nextDue = e.placement.runsHere && ts?.lastPollAt && pollMs ? new Date(Date.parse(ts.lastPollAt) + pollMs).toISOString() : null;
1058
1058
  const local = e.member === "local";
1059
1059
  const def = e.definition || {};
package/lib/workspace.mjs CHANGED
@@ -12,7 +12,6 @@
12
12
  */
13
13
  import { readFileSync, existsSync } from "node:fs";
14
14
  import { dirname, join, resolve } from "node:path";
15
- import { launchPromptPolicyProblems } from "./launch-prompt-policy.mjs";
16
15
  import { recordLocalInput } from "./local-inputs.mjs";
17
16
  import { parseConfigData } from "./config-data.mjs";
18
17
  import { oatsError } from "./errors.mjs";
@@ -282,6 +281,11 @@ const REMOVED_KEYS = {
282
281
  local: [
283
282
  { at: (v) => (isObject(v?.souls) && Object.hasOwn(v.souls, "teams") ? ["/souls/teams"] : []), message: "souls.teams was removed in 0.38.0 (team model 3): which teams a soul may join is souls: in oats-workspace.yaml" },
284
283
  { at: (v) => (isObject(v?.souls) && Object.hasOwn(v.souls, "default") ? ["/souls/default"] : []), message: "souls.default was removed in 0.38.0 (team model 3): a soul's default team is souls: in oats-workspace.yaml (default:)" },
284
+ // 0.52.0: launchPromptAnswers is ignored (core.mjs launchPromptAnswersNotice), except an
285
+ // operator's explicit refusal, which this kernel cannot honour and so must not drop silently.
286
+ { at: (v) => (isObject(v?.launchPromptAnswers?.homes) ? Object.entries(v.launchPromptAnswers.homes)
287
+ .filter(([, e]) => isObject(e) && e.awebDevelopmentChannel === false).map(([home]) => `/launchPromptAnswers/homes/${pointerKey(home)}`) : []),
288
+ message: "launchPromptAnswers awebDevelopmentChannel: false cannot be honoured: OATS confirms Claude's development-channel prompt whenever it launches Claude with --dangerously-load-development-channels plugin:aweb-channel@awebai-marketplace. To keep the prompt unanswered, set settings.oats.aweb.delivery: session or settings.oats.aweb.claudeChannelMode: approved in oats-local.yaml, then remove launchPromptAnswers" },
285
289
  ],
286
290
  };
287
291
  function withRemovedKeys(problems, value, removed) {
@@ -339,16 +343,6 @@ export function validateLocal(value) {
339
343
  problems.push({ path: `/launch-configs/${pointerKey(name)}/runtime`, reason: "harness-conflict", message: `harness ${show(entry.harness)} and runtime ${show(entry.runtime)} disagree: \`runtime\` is the pre-0.27 name of \`harness\` — keep one` });
340
344
  }
341
345
  }
342
- if (isObject(value) && Object.hasOwn(value, "launchPromptAnswers")) {
343
- // Shape is checked by the schema; add filesystem-dependent canonical-home checks.
344
- for (const problem of launchPromptPolicyProblems(value.launchPromptAnswers)) {
345
- if (problem.reason === "unsupported-launch-prompt") {
346
- const index = problems.findIndex((p) => p.path === problem.path);
347
- if (index !== -1) problems.splice(index, 1);
348
- problems.push(problem);
349
- } else if (problem.reason === "noncanonical-home") problems.push(problem);
350
- }
351
- }
352
346
  return problems;
353
347
  }
354
348
 
@@ -17,8 +17,9 @@
17
17
  * is a test seam, not a setting. */
18
18
  import { spawn as spawnProcess, execFileSync, spawnSync } from "node:child_process";
19
19
  import { closeSync, existsSync, fchmodSync, mkdirSync, openSync, readFileSync, realpathSync, writeSync } from "node:fs";
20
- import { dirname, join } from "node:path";
20
+ import { dirname, isAbsolute, join } from "node:path";
21
21
  import { terminateGroup, watchGroup, TERM_GRACE_MS } from "./process-group.mjs";
22
+ import { SYSTEM_TOOL_DIRS } from "./system-tools.mjs";
22
23
 
23
24
  export const WORKTREE_HOOK_TIMEOUT_MS = 30 * 60 * 1000;
24
25
  /** The fixed timeout, or the test seam's value (a positive integer of milliseconds). */
@@ -36,12 +37,25 @@ export const interruptExitStatus = (signal) => 128 + (SIGNAL_NUMBERS[signal] ??
36
37
  // ---------- process identity: a pid is verified by its start time ----------
37
38
 
38
39
  /** Where a start time is read: /proc when this host has procfs, else `ps`. The test seam
39
- * OATS_TEST_PROCESS_START_PS=1 (not a setting) takes the `ps` path on a host with procfs. */
40
- const readsProc = () => process.env.OATS_TEST_PROCESS_START_PS !== "1" && existsSync("/proc/self/stat");
41
- /** `ps` runs with a fixed environment, nothing inherited: `lstart` is local time in the locale's
42
- * format, and two readers with another TZ or LANG would otherwise read one live process's start
43
- * differently, and take it for another. */
44
- const psEnv = () => ({ PATH: process.env.PATH ?? "/usr/bin:/bin", LC_ALL: "C", TZ: "UTC" });
40
+ * OATS_TEST_PROCESS_START_PS (not a setting; a launch configuration cannot set it) takes the `ps`
41
+ * path on any host: `1` runs the system `ps`, an absolute path runs that file as `ps`, and any
42
+ * other value reads no start at all (psProgram). */
43
+ const readsProc = () => process.env.OATS_TEST_PROCESS_START_PS === undefined && existsSync("/proc/self/stat");
44
+ /** `ps` runs with a fixed environment, nothing inherited (runPs). Its PATH is the system directories only (SYSTEM_TOOL_DIRS),
45
+ * never the caller's: what `ps` reports is the identity a claim is held or taken over on, so the
46
+ * caller's PATH must not choose the program, and a caller whose PATH holds no `ps` reads the same
47
+ * start as any other. `lstart` is local time in the locale's format, and two readers with another
48
+ * TZ or LANG would otherwise read one live process's start differently, and take it for another. */
49
+ export const PS_ENV = Object.freeze({ PATH: SYSTEM_TOOL_DIRS.join(":"), LC_ALL: "C", TZ: "UTC" });
50
+ /** The `ps` a start is read with → { file, name } | { reason }: the system one, or the file the
51
+ * test seam names by absolute path, run directly (no shell). A seam that names neither is never a
52
+ * fallback to /proc or to a `ps` found on PATH; nor is a named file that cannot be run (readStart). */
53
+ function psProgram() {
54
+ const seam = process.env.OATS_TEST_PROCESS_START_PS;
55
+ if (seam === undefined || seam === "1") return { file: "ps", name: "ps" };
56
+ if (isAbsolute(seam)) return { file: seam, name: `the ps OATS_TEST_PROCESS_START_PS names (${seam})` };
57
+ return { reason: `OATS_TEST_PROCESS_START_PS is ${JSON.stringify(seam)}, neither 1 nor an absolute path` };
58
+ }
45
59
 
46
60
  /** Whether `pid` exists, from the kernel itself: kill(pid, 0). ESRCH is gone; EPERM (another user's
47
61
  * process) and success are "exists"; anything else is unknown. Never from how procfs or `ps`
@@ -56,8 +70,39 @@ function existence(pid) {
56
70
  }
57
71
  }
58
72
 
59
- /** The start of a pid that exists: /proc/<pid>/stat field 22 (clock ticks since boot) on Linux,
60
- * elsewhere `ps -o lstart=` in a fixed environment. → { state: "alive", token } | { state: "unknown", reason }. */
73
+ /** Run the system `ps` once: `ps -o <column>= … <selection>`, each column without its header.
74
+ * → { out } — its stdout as it was written, when it exited 0 and answered something;
75
+ * → { reason } — it could not be run, was ended, failed or answered nothing: one line saying which.
76
+ * The one way the kernel calls `ps` (awebai/oats#870, #882): the program (psProgram), the fixed
77
+ * environment (PS_ENV), the time it is given and how its answer is classified are decided here.
78
+ * `selection` is the rest of its arguments (`["-p", "<pid>"]`, `["-ax"]`). The environment is
79
+ * PS_ENV whoever calls: what `ps` answers under it is the same for every reader. `path`, when
80
+ * given, is the PATH the program is found on, in place of PS_ENV's and of nothing else in it: an
81
+ * explicit argument, never read from the caller's environment here. The start reader passes
82
+ * none, so the caller's PATH never chooses the program an identity is read with (#878). */
83
+ export function runPs(columns, selection, { path } = {}) {
84
+ const ps = psProgram();
85
+ if (ps.reason) return { reason: ps.reason };
86
+ const argv = [...columns.flatMap((column) => ["-o", `${column}=`]), ...selection];
87
+ const r = spawnSync(ps.file, argv, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], env: path === undefined ? PS_ENV : { ...PS_ENV, PATH: path }, timeout: 10_000, maxBuffer: 4 * 1024 * 1024 });
88
+ if (r.error) return { reason: `${ps.name} could not be run (${r.error.code || r.error.message})` };
89
+ const out = String(r.stdout ?? ""), err = String(r.stderr ?? "").trim();
90
+ if (r.status === 0 && out.trim()) return { out };
91
+ return { reason: `ps ${argv.join(" ")} answered ${r.status === null ? `signal ${r.signal}` : `exit ${r.status}`}${err ? `: ${err.split("\n")[0]}` : out.trim() ? " with output" : " with no output"}` };
92
+ }
93
+
94
+ /** The start of a pid that exists, and whether it is a zombie (it exited, or was killed, and its
95
+ * parent has not reaped it): one read gives both.
96
+ * Linux: /proc/<pid>/stat, field 22 (clock ticks since boot) and field 3 (its state: `Z`, or `X`,
97
+ * a process being removed). Elsewhere `ps -o lstart= -o stat=` (runPs): the start, then a state
98
+ * that begins with `Z` (procps `Z`, macOS `Z` and `Z+`).
99
+ * → { state: "alive", token, zombie? } | { state: "unknown", reason }. `zombie` is set only when
100
+ * it is true. A state that cannot be read makes no zombie, and the start is what it was before
101
+ * there was a second column: whatever `ps` prints as a state (`?` included) is only ever cut off
102
+ * the start, and a `ps` that answers the start alone gives the start.
103
+ * The token is what released kernels recorded, byte for byte (`proc:<ticks>`, `ps:<lstart>`): a
104
+ * claim, a tree record or a marker written by an older kernel names its live holder by it, and a
105
+ * reader that gave that holder another token would take it for a reused pid, which is gone. */
61
106
  function readStart(pid) {
62
107
  if (readsProc()) {
63
108
  let stat;
@@ -66,24 +111,47 @@ function readStart(pid) {
66
111
  // comm (field 2) is in parentheses and may hold spaces or parentheses itself.
67
112
  const fields = stat.slice(stat.lastIndexOf(")") + 2).split(" ");
68
113
  const start = fields[19]; // field 22 overall: after pid, comm and the 19 before it
69
- return /^[0-9]+$/.test(start ?? "") ? { state: "alive", token: `proc:${start}` } : { state: "unknown", reason: `/proc/${pid}/stat has no start time` };
114
+ if (!/^[0-9]+$/.test(start ?? "")) return { state: "unknown", reason: `/proc/${pid}/stat has no start time` };
115
+ return { state: "alive", token: `proc:${start}`, ...(fields[0] === "Z" || fields[0] === "X" ? { zombie: true } : {}) };
70
116
  }
71
- const r = spawnSync("ps", ["-o", "lstart=", "-p", String(pid)], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], env: psEnv(), timeout: 10_000 });
72
- const out = String(r.stdout ?? "").trim(), err = String(r.stderr ?? "").trim();
73
- if (r.error) return { state: "unknown", reason: `ps could not be run (${r.error.code || r.error.message})` };
74
- if (r.status === 0 && out) return { state: "alive", token: `ps:${out}` };
75
- return { state: "unknown", reason: `ps -o lstart= -p ${pid} answered ${r.status === null ? `signal ${r.signal}` : `exit ${r.status}`}${err ? `: ${err.split("\n")[0]}` : out ? " with output" : " with no output"}` };
117
+ const r = runPs(["lstart", "stat"], ["-p", String(pid)]);
118
+ if (r.reason) return { state: "unknown", reason: r.reason };
119
+ // `Thu Jan 1 00:00:00 2026 Ss`: the state is the last field, one word whatever it says, and the
120
+ // start before it is taken whole, as `ps -o lstart=` alone prints it. A start ends with its year,
121
+ // so a last field of digits only is the start's own: that `ps` answered no state.
122
+ const out = r.out.trim();
123
+ const column = /^(.*\S)\s+(\S+)$/s.exec(out);
124
+ if (!column || /^[0-9]+$/.test(column[2])) return { state: "alive", token: `ps:${out}` };
125
+ return { state: "alive", token: `ps:${column[1]}`, ...(column[2].startsWith("Z") ? { zombie: true } : {}) };
76
126
  }
77
127
 
128
+ /** Whether `token` has a shape readStart writes: `proc:` and a count of clock ticks (64 bits: at
129
+ * most 20 digits), or `ps:` and a start as `ps -o lstart=` prints it under PS_ENV
130
+ * (`Thu Jan 1 00:00:00 2026`). The shape is said here, beside its writer, and nowhere else.
131
+ * It decides only what of a record may be SHOWN: a record is a file that others than its writer
132
+ * can write, and text that is not the kernel's enters an answer only as an id or a code. It is
133
+ * never a liveness decision: processLiveness compares the recorded string as it is, and a real
134
+ * token this does not know (a `ps` that prints a start otherwise) is shown as none, never read
135
+ * as gone. */
136
+ const START_TOKEN = /^(?:proc:[0-9]{1,20}|ps:[A-Z][a-z]{2} [A-Z][a-z]{2} [ 0-9][0-9] [0-9]{2}:[0-9]{2}:[0-9]{2} [0-9]{4})$/;
137
+ export const isStartToken = (token) => typeof token === "string" && START_TOKEN.test(token);
138
+
78
139
  /** When `pid` started, read three ways apart (lessons/observation-must-not-harm-the-observer.md:
79
140
  * "absent" never collapses with "unreadable"). One rule on every host: whether the pid exists is
80
141
  * the kernel's answer (existence), and only a pid that exists has its start read.
81
- * → { state: "alive", token } — an opaque token for its start; two processes that held one pid at
82
- * different times never share it, so a pid is only ever compared WITH its token;
142
+ * → { state: "alive", token, zombie? } — an opaque token for its start; two processes that held
143
+ * one pid at different times never share it, so a pid is only ever compared WITH its token;
83
144
  * → { state: "gone" } — kill(pid, 0) answers ESRCH, before the read or (it exited in between)
84
145
  * after a read that failed;
85
146
  * → { state: "unknown", reason } — anything else: the pid exists and its start could not be read,
86
- * or kill(pid, 0) failed otherwise. Every caller fails safe on it. */
147
+ * or kill(pid, 0) failed otherwise. Every caller fails safe on it.
148
+ *
149
+ * This answers WHOSE the pid is, and a zombie still holds its pid and its start: it is "alive"
150
+ * here, with `zombie: true` as a fact beside it. That is what a recorded process group needs
151
+ * (terminateRecordedGroup): while its leader is a zombie the group's id cannot be reused, so a
152
+ * zombie leader with the recorded start is the best proof there is that the group is still that
153
+ * run's, and its members are ended. Whether a process can still ACT is another question, and
154
+ * processLiveness answers it (awebai/oats#870). */
87
155
  export function processStart(pid) {
88
156
  if (!Number.isSafeInteger(pid) || pid <= 0) return { state: "gone" };
89
157
  const before = existence(pid);
@@ -106,17 +174,39 @@ export function selfIdentity() {
106
174
  return { pid: process.pid, processStart: processStartToken(process.pid) };
107
175
  }
108
176
 
109
- /** Whether the process a record names (`{ pid, processStart }`) still runs:
177
+ /** Whether the COMMAND a record names (`{ pid, processStart }`) can still act:
110
178
  * → { state: "alive" } — its pid runs with the recorded start;
111
- * → { state: "gone" } — its pid does not run, or runs with another start (a reused pid);
179
+ * → { state: "gone", zombie? } — its pid does not run, or runs with another start (a reused pid),
180
+ * or is a zombie (`zombie: true`): it exited or was killed and its parent has not reaped it;
112
181
  * → { state: "unknown", reason } — the start could not be read, or the record has none to
113
182
  * compare while its pid runs. Every caller fails safe on it: nothing is taken over, rolled back,
114
- * retired or signalled, and the refusal names the way out. */
183
+ * retired or signalled, and the refusal names the way out.
184
+ *
185
+ * A zombie is gone here (awebai/oats#870), though processStart still reads its pid and start. It
186
+ * will never run again, and a parent that never waits for it would otherwise keep its claim or
187
+ * marker refused for ever, with the advice to wait for it. Taking over from it is as safe as from
188
+ * a holder that was killed and reaped: a process's children are re-parented when it exits, not
189
+ * when it is reaped, so what a zombie leaves behind is exactly what that holder leaves: the steps
190
+ * it recorded, which each takeover ends (lib/claim.mjs `endHolderStep`; the hook group of a tree
191
+ * record or a spawn's marker), and for a retire its hook children (awebai/oats#865). The zombie
192
+ * adds nothing to that; it only delays the takeover until a reap that may never come.
193
+ * It is decided before the start is compared: a pid that is a zombie now is not a running
194
+ * holder whichever start the record names (it is that holder, or the pid was reused), and so
195
+ * neither when the record names none.
196
+ *
197
+ * WHOM THIS MAY BE ASKED ABOUT: the process of an `oats` command itself, which is what every
198
+ * record read with it names (a claim's holder, the adder of a tree record, a spawn's `inProgress`,
199
+ * a self-retire's completion). That is what makes "a zombie cannot act" true. On Linux a process
200
+ * whose main thread has exited while other threads run also reads `Z` in /proc/<pid>/stat, and
201
+ * it still acts; Node exits as a whole, so it does not arise for those records. Never ask this
202
+ * about a hook's or a harness's pid: for a process that is not the kernel's own, a `Z` does not
203
+ * say it is finished. (A recorded group's leader is asked through processStart, not through this.) */
115
204
  export function processLiveness(record) {
116
205
  const pid = record?.pid;
117
206
  if (!Number.isSafeInteger(pid) || pid <= 0) return { state: "gone" };
118
207
  const s = processStart(pid);
119
208
  if (s.state !== "alive") return s;
209
+ if (s.zombie) return { state: "gone", zombie: true };
120
210
  if (typeof record.processStart !== "string" || !record.processStart) return { state: "unknown", reason: `pid ${pid} runs, and the record names no start time to compare it with` };
121
211
  return s.token === record.processStart ? { state: "alive" } : { state: "gone" };
122
212
  }
@@ -156,11 +246,14 @@ export const unverifiedGroupWarning = (pgid, what = "hook") =>
156
246
  `${what} process group ${pgid} was not signalled: its leader exited, so the group cannot be proven to be this run's; end any leftover processes yourself`;
157
247
 
158
248
  /** What a refusal says of an "unknown" group (terminateRecordedGroup): its id, the recorded start
159
- * of its leader and why that start cannot be read now. The caller adds what it kept and the way out. */
249
+ * of its leader and why that start cannot be read now. The caller adds what it kept and the way out.
250
+ * The recorded start is printed only when it is a token of the kernel's (isStartToken), else as
251
+ * `none`: `rec` is read from a file (a claim, a tree record, a spawn's marker). The id is an
252
+ * integer whenever a group is "unknown". */
160
253
  export function unknownGroupNote(rec, what = "hook") {
161
254
  const s = processStart(rec.hookPgid);
162
255
  const reason = s.state === "unknown" ? s.reason : "its leader's start time could not be read";
163
- return `${what} process group ${rec.hookPgid} (leader pid ${rec.hookPgid}, recorded start ${rec.hookStart ?? "none"}) still has members, and its leader's start cannot be read (${reason}), so whether it is still that ${what} cannot be told and it was not signalled`;
256
+ return `${what} process group ${rec.hookPgid} (leader pid ${rec.hookPgid}, recorded start ${isStartToken(rec.hookStart) ? rec.hookStart : "none"}) still has members, and its leader's start cannot be read (${reason}), so whether it is still that ${what} cannot be told and it was not signalled`;
164
257
  }
165
258
 
166
259
  /** End the group of a hook this process is running, synchronously, once its leader has