@jbkjr/relay 0.0.0-stage → 1.2.2

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 (296) hide show
  1. package/LICENSE +21 -0
  2. package/LICENSES/Apache-2.0.txt +201 -0
  3. package/LICENSES/README.md +19 -0
  4. package/LICENSES/codex-NOTICE.txt +6 -0
  5. package/README.md +393 -2
  6. package/SECURITY.md +145 -0
  7. package/adapters/briefs/claude.md +43 -0
  8. package/adapters/briefs/codex.md +56 -0
  9. package/adapters/briefs/models.json +33 -0
  10. package/adapters/build.mjs +8 -0
  11. package/adapters/claude/.claude-plugin/marketplace.json +13 -0
  12. package/adapters/claude/relay/.claude-plugin/plugin.json +5 -0
  13. package/adapters/claude/relay/agents/codex.md +21 -0
  14. package/adapters/claude/relay/agents/operator.md +21 -0
  15. package/adapters/claude/relay/skills/ask/SKILL.md +20 -0
  16. package/adapters/claude/relay/skills/chat/SKILL.md +13 -0
  17. package/adapters/claude/relay/skills/delegate/SKILL.md +21 -0
  18. package/adapters/claude/relay/skills/discuss/SKILL.md +19 -0
  19. package/adapters/claude/relay/skills/review/SKILL.md +21 -0
  20. package/adapters/claude/relay/skills/tree/SKILL.md +10 -0
  21. package/adapters/claude/relay/skills/write-for-codex/SKILL.md +78 -0
  22. package/adapters/codex/.agents/plugins/marketplace.json +20 -0
  23. package/adapters/codex/AGENTS.snippet.md +5 -0
  24. package/adapters/codex/relay/.codex-plugin/plugin.json +6 -0
  25. package/adapters/codex/relay/skills/relay-ask/SKILL.md +20 -0
  26. package/adapters/codex/relay/skills/relay-chat/SKILL.md +13 -0
  27. package/adapters/codex/relay/skills/relay-delegate/SKILL.md +21 -0
  28. package/adapters/codex/relay/skills/relay-discuss/SKILL.md +19 -0
  29. package/adapters/codex/relay/skills/relay-review/SKILL.md +21 -0
  30. package/adapters/codex/relay/skills/relay-tree/SKILL.md +10 -0
  31. package/adapters/codex/relay/skills/relay-write-for-claude/SKILL.md +66 -0
  32. package/adapters/generate.mjs +124 -0
  33. package/bin/relay +59 -0
  34. package/codex-pin.json +12 -0
  35. package/dist/backends/acp.js +1424 -0
  36. package/dist/backends/claude.js +890 -0
  37. package/dist/backends/cli-version.js +112 -0
  38. package/dist/backends/codex-app.js +1539 -0
  39. package/dist/backends/codex-daybreak.js +75 -0
  40. package/dist/backends/codex-env.js +656 -0
  41. package/dist/backends/codex-network.js +304 -0
  42. package/dist/backends/codex-pin.js +345 -0
  43. package/dist/backends/codex-shell-policy.js +182 -0
  44. package/dist/backends/codex-stage2.js +998 -0
  45. package/dist/backends/codex-subagents.js +47 -0
  46. package/dist/backends/codex.js +641 -0
  47. package/dist/backends/copilot.js +246 -0
  48. package/dist/backends/env.js +147 -0
  49. package/dist/backends/gemini.js +607 -0
  50. package/dist/backends/grok.js +337 -0
  51. package/dist/backends/index.js +8 -0
  52. package/dist/backends/native-temp.js +187 -0
  53. package/dist/backends/never-admission.js +90 -0
  54. package/dist/backends/run.js +67 -0
  55. package/dist/backends/stream.js +230 -0
  56. package/dist/backends/tool-discovery.js +15 -0
  57. package/dist/backends/types.js +264 -0
  58. package/dist/build-info.json +5 -0
  59. package/dist/cli.js +344 -0
  60. package/dist/confine/bridge.js +113 -0
  61. package/dist/confine/broker-core.js +76 -0
  62. package/dist/confine/broker-http.js +650 -0
  63. package/dist/confine/broker-names.js +9 -0
  64. package/dist/confine/broker.js +258 -0
  65. package/dist/confine/canary.js +380 -0
  66. package/dist/confine/diagnostics.js +122 -0
  67. package/dist/confine/gemini-tools-main.js +8 -0
  68. package/dist/confine/gemini-tools.js +181 -0
  69. package/dist/confine/hardlinks.js +58 -0
  70. package/dist/confine/harness-config.js +16 -0
  71. package/dist/confine/index.js +117 -0
  72. package/dist/confine/leases.js +217 -0
  73. package/dist/confine/paths.js +6 -0
  74. package/dist/confine/peer.js +115 -0
  75. package/dist/confine/port-policy.js +8 -0
  76. package/dist/confine/ports.js +365 -0
  77. package/dist/confine/private-root.js +208 -0
  78. package/dist/confine/probe-stage2.js +501 -0
  79. package/dist/confine/probe.js +1109 -0
  80. package/dist/confine/proxy.js +783 -0
  81. package/dist/confine/sbcheck.js +208 -0
  82. package/dist/confine/seatbelt-never.js +41 -0
  83. package/dist/confine/seatbelt-stage2.js +139 -0
  84. package/dist/confine/seatbelt.js +1129 -0
  85. package/dist/confine/sockets.js +36 -0
  86. package/dist/confine/turn-probe.js +19 -0
  87. package/dist/confine/turn.js +86 -0
  88. package/dist/core/adoption.js +124 -0
  89. package/dist/core/api-keys.js +423 -0
  90. package/dist/core/approvals.js +740 -0
  91. package/dist/core/build-identity.js +248 -0
  92. package/dist/core/caller.js +749 -0
  93. package/dist/core/calls.js +102 -0
  94. package/dist/core/claude-settings.js +1045 -0
  95. package/dist/core/config.js +453 -0
  96. package/dist/core/context.js +186 -0
  97. package/dist/core/db.js +753 -0
  98. package/dist/core/dispatch.js +110 -0
  99. package/dist/core/env-broker.js +505 -0
  100. package/dist/core/env-policy.js +182 -0
  101. package/dist/core/escalation-authority.js +76 -0
  102. package/dist/core/escalation-contract.js +13 -0
  103. package/dist/core/escalation-person-path.js +131 -0
  104. package/dist/core/escalation-policy.js +79 -0
  105. package/dist/core/escalation-runtime.js +135 -0
  106. package/dist/core/escalation-state.js +42 -0
  107. package/dist/core/escalations.js +191 -0
  108. package/dist/core/events.js +235 -0
  109. package/dist/core/executables.js +147 -0
  110. package/dist/core/extensions.js +645 -0
  111. package/dist/core/families.js +204 -0
  112. package/dist/core/git.js +657 -0
  113. package/dist/core/identity.js +113 -0
  114. package/dist/core/liveness.js +68 -0
  115. package/dist/core/mediated-network-provider.js +81 -0
  116. package/dist/core/never-checkpoint.js +76 -0
  117. package/dist/core/never-coverage.js +97 -0
  118. package/dist/core/never-network.js +49 -0
  119. package/dist/core/never-policy.js +302 -0
  120. package/dist/core/never-proxy-policy.js +109 -0
  121. package/dist/core/never-schema.js +61 -0
  122. package/dist/core/never-tools.js +56 -0
  123. package/dist/core/notices.js +48 -0
  124. package/dist/core/ops.js +959 -0
  125. package/dist/core/outcome.js +224 -0
  126. package/dist/core/params.js +32 -0
  127. package/dist/core/presence.js +174 -0
  128. package/dist/core/procs.js +546 -0
  129. package/dist/core/prompts.js +363 -0
  130. package/dist/core/protected-config.js +238 -0
  131. package/dist/core/raw-network.js +192 -0
  132. package/dist/core/redact.js +152 -0
  133. package/dist/core/refusal.js +33 -0
  134. package/dist/core/relay-command.js +310 -0
  135. package/dist/core/reported.js +3 -0
  136. package/dist/core/restart-overlay.js +651 -0
  137. package/dist/core/retention.js +1135 -0
  138. package/dist/core/secrets.js +329 -0
  139. package/dist/core/session-token.js +175 -0
  140. package/dist/core/session.js +744 -0
  141. package/dist/core/shell.js +2 -0
  142. package/dist/core/shipped-pin.js +47 -0
  143. package/dist/core/shown.js +42 -0
  144. package/dist/core/slots.js +67 -0
  145. package/dist/core/stage2-executors.js +453 -0
  146. package/dist/core/stage2-switch.js +5 -0
  147. package/dist/core/steering.js +149 -0
  148. package/dist/core/storage.js +358 -0
  149. package/dist/core/toml.js +175 -0
  150. package/dist/core/views.js +324 -0
  151. package/dist/core/wait.js +114 -0
  152. package/dist/core/wake.js +207 -0
  153. package/dist/core/watch.js +247 -0
  154. package/dist/core/worktree.js +213 -0
  155. package/dist/hosts/claude-desktop.js +274 -0
  156. package/dist/hosts/claude.js +249 -0
  157. package/dist/hosts/codex.js +345 -0
  158. package/dist/hosts/desktop-shared.js +20 -0
  159. package/dist/hosts/index.js +11 -0
  160. package/dist/hosts/types.js +4 -0
  161. package/dist/install/basics.js +18 -0
  162. package/dist/install/claude-init.js +133 -0
  163. package/dist/install/common.js +655 -0
  164. package/dist/install/doctor.js +635 -0
  165. package/dist/install/qualify-codex.js +205 -0
  166. package/dist/install.js +524 -0
  167. package/dist/mcp/elicit.js +209 -0
  168. package/dist/mcp/gateway.js +218 -0
  169. package/dist/mcp/host.js +253 -0
  170. package/dist/mcp/server.js +1124 -0
  171. package/dist/mcp/stdio.js +37 -0
  172. package/dist/modes/discussion.js +393 -0
  173. package/dist/modes/review.js +722 -0
  174. package/dist/native/relay-sbcheck +0 -0
  175. package/dist/targets/briefs.js +86 -0
  176. package/dist/targets/claude.js +94 -0
  177. package/dist/targets/codex.js +66 -0
  178. package/dist/targets/copilot.js +93 -0
  179. package/dist/targets/gemini.js +119 -0
  180. package/dist/targets/grok.js +126 -0
  181. package/dist/targets/index.js +192 -0
  182. package/dist/targets/types.js +18 -0
  183. package/dist/targets/verified.js +35 -0
  184. package/dist/worker.js +113 -0
  185. package/docs/UPGRADING.md +1518 -0
  186. package/docs/pinned-codex.md +333 -0
  187. package/experiments/stage2-redteam/lib/oracles.mjs +214 -0
  188. package/experiments/stage2-redteam/lib/report.mjs +35 -0
  189. package/npm-shrinkwrap.json +1632 -0
  190. package/package.json +82 -4
  191. package/scripts/codex-qualify/codex-pin-store.mjs +353 -0
  192. package/scripts/codex-qualify/codex-qualifier-process.mjs +265 -0
  193. package/scripts/codex-qualify/codex-qualifier.example.json +5 -0
  194. package/scripts/codex-qualify/codex-qualifier.mjs +281 -0
  195. package/scripts/codex-qualify/codex-shipped-pin.mjs +158 -0
  196. package/scripts/codex-qualify/codex-stage2-pin.mjs +48 -0
  197. package/scripts/codex-qualify/codex-stage2.mjs +2381 -0
  198. package/scripts/codex-qualify/install-codex-qualifier.mjs +98 -0
  199. package/scripts/codex-qualify/main-module.mjs +14 -0
  200. package/scripts/codex-qualify/relay-codex-qualifier.plist +37 -0
  201. package/scripts/codex-qualify/scratch-env.mjs +31 -0
  202. package/scripts/codex-qualify/session.mjs +96 -0
  203. package/scripts/codex-qualify/stage2-escalation-cases.mjs +125 -0
  204. package/test/codex-permissions.test.ts +875 -0
  205. package/test/fixtures/boundary-probes.mjs +17 -0
  206. package/test/fixtures/denial-stream-host.mjs +7 -0
  207. package/test/fixtures/families.json +246 -0
  208. package/test/fixtures/install-snapshots/claude-desktop-foreign.txt +158 -0
  209. package/test/fixtures/install-snapshots/claude-desktop-fresh.txt +101 -0
  210. package/test/fixtures/install-snapshots/claude-desktop-installed.txt +161 -0
  211. package/test/fixtures/install-snapshots/claude-foreign.txt +133 -0
  212. package/test/fixtures/install-snapshots/claude-fresh.txt +77 -0
  213. package/test/fixtures/install-snapshots/claude-installed.txt +133 -0
  214. package/test/fixtures/install-snapshots/codex-foreign.txt +159 -0
  215. package/test/fixtures/install-snapshots/codex-fresh.txt +107 -0
  216. package/test/fixtures/install-snapshots/codex-installed.txt +161 -0
  217. package/test/fixtures/link-parent.mjs +6 -0
  218. package/test/fixtures/mediated-command.cjs +72 -0
  219. package/test/fixtures/native-skill-isolation.json +280 -0
  220. package/test/fixtures/pinned-codex-app-server.mjs +25 -0
  221. package/test/fixtures/qualified-ext-adapters.mjs +36 -0
  222. package/test/fixtures/refusals/README.md +52 -0
  223. package/test/fixtures/refusals/claude-source-result.json +7 -0
  224. package/test/fixtures/refusals/openai-app-capacity.json +24 -0
  225. package/test/fixtures/refusals/openai-app-cyberPolicy.json +24 -0
  226. package/test/fixtures/refusals/openai-gpt-6-astra-max.json +12 -0
  227. package/test/fixtures/refusals/openai-gpt-6.1-sol-xhigh.json +12 -0
  228. package/test/fixtures/refusals/openai-review-capacity.json +24 -0
  229. package/test/fixtures/relay-0.2.0.sql +57 -0
  230. package/test/fixtures/relay-0.9.1.gen.mjs +212 -0
  231. package/test/fixtures/relay-0.9.1.sql +340 -0
  232. package/test/fixtures/slow-boundary-probes.mjs +37 -0
  233. package/test/fixtures/stable-surfaces/config.json +1122 -0
  234. package/test/fixtures/stable-surfaces/escalation.json +128 -0
  235. package/test/fixtures/stable-surfaces/events.json +37 -0
  236. package/test/fixtures/stable-surfaces/gemini-native-resume.json +4 -0
  237. package/test/fixtures/stable-surfaces/inbox.jsonl +2 -0
  238. package/test/fixtures/stable-surfaces/notice.txt +1 -0
  239. package/test/fixtures/stable-surfaces/refusal-item.json +28 -0
  240. package/test/fixtures/stable-surfaces/refusal-review.json +23 -0
  241. package/test/fixtures/stable-surfaces/registry.json +49 -0
  242. package/test/fixtures/stable-surfaces/tools-desktop.json +575 -0
  243. package/test/fixtures/stable-surfaces/tools.json +716 -0
  244. package/test/fixtures/stable-surfaces/usage.txt +46 -0
  245. package/test/fixtures/stage2-acp-native.mjs +138 -0
  246. package/test/fixtures/stage2-app-server.mjs +23 -0
  247. package/test/fixtures/stage2-catalog.json +91 -0
  248. package/test/fixtures/stage2-hostile-web.mjs +35 -0
  249. package/test/fixtures/stage2-native-network.mjs +62 -0
  250. package/test/fixtures/stage2-worker.ts +87 -0
  251. package/test/fixtures/status-views/expected.json +7825 -0
  252. package/test/fixtures/status-views/registries.json +1 -0
  253. package/test/fixtures/steering.json +209 -0
  254. package/test/helpers.ts +740 -0
  255. package/test/host-env.ts +7 -0
  256. package/test/keychain-decoy.ts +197 -0
  257. package/test/live-scope.ts +44 -0
  258. package/test/mediated-network.test.ts +192 -0
  259. package/test/mediated-proxy.test.ts +264 -0
  260. package/test/native-temp-alias.ts +10 -0
  261. package/test/never-policy.test.ts +629 -0
  262. package/test/never-tools.test.ts +136 -0
  263. package/test/process-home.ts +18 -0
  264. package/test/proxy.test.ts +531 -0
  265. package/test/restart-overlay-live.test.ts +85 -0
  266. package/test/restart-overlay-profile.test.ts +66 -0
  267. package/test/restart-overlay.test.ts +416 -0
  268. package/test/stable-surfaces.test.ts +249 -0
  269. package/test/stage2-escalation-live.test.ts +544 -0
  270. package/test/stage2-escalation-qualification.test.ts +170 -0
  271. package/test/stage2-escalation.test.ts +747 -0
  272. package/test/stage2-executor.test.ts +849 -0
  273. package/test/stage2-grant.test.ts +603 -0
  274. package/test/stage2-native-live.test.ts +647 -0
  275. package/test/stage2-network-decisions.test.ts +70 -0
  276. package/test/stage2-probe.test.ts +845 -0
  277. package/test/stage2-standing-live.test.ts +203 -0
  278. package/test/stubs/broker-host.mjs +59 -0
  279. package/test/stubs/broker-peer.mjs +20 -0
  280. package/test/stubs/confined-harness.mjs +91 -0
  281. package/test/stubs/ext-broken-server.mjs +2 -0
  282. package/test/stubs/ext-odd-server.mjs +21 -0
  283. package/test/stubs/ext-server.mjs +31 -0
  284. package/test/stubs/fake-host-cli.mjs +218 -0
  285. package/test/stubs/procargs.mjs +30 -0
  286. package/test/stubs/stub-acp +4 -0
  287. package/test/stubs/stub-agent.mjs +322 -0
  288. package/test/stubs/stub-claude +4 -0
  289. package/test/stubs/stub-codex +4 -0
  290. package/test/stubs/targets/acp.mjs +307 -0
  291. package/test/stubs/targets/claude.mjs +149 -0
  292. package/test/stubs/targets/codex.mjs +479 -0
  293. package/test/stubs/targets/gemini.mjs +604 -0
  294. package/test/temp-root.ts +11 -0
  295. package/test/wp4-adapters.test.ts +353 -0
  296. package/test/wp4-interlock.test.ts +136 -0
@@ -0,0 +1,753 @@
1
+ import fs from "node:fs";
2
+ import path from "node:path";
3
+ import crypto from "node:crypto";
4
+ import { DatabaseSync } from "node:sqlite";
5
+ import { canonical, configPath, inside, relayHome, withDefaults, worktreesHome } from "./config.js";
6
+ import { resolveNeverPolicy } from "./never-policy.js";
7
+ import { groupAlive, isGroupSignalRefusal, killGroupNow, pidAlive, processGone, procStart, sameProcess } from "./procs.js";
8
+ import { queuedSpeeds, speedOf } from "./params.js";
9
+ import { executorRecords, nodeHasLiveExecutor, quarantineRecordedExecutor, stoppedNote, stopRecordedExecutorNow, stopNodeExecutorsNow } from "./stage2-executors.js";
10
+ import { overlayOwnerAlive, overlayTurnProblem, reapOverlays, reapLaunchReservations, stopNodeLaunchReservations } from "./restart-overlay.js";
11
+ export const ACTIVE = ["queued", "running"];
12
+ /** The launch_leaders table, under a name (a rebuild of a pre-release copy uses a scratch name). */
13
+ const LAUNCH_LEADERS_DDL = (name) => `CREATE TABLE IF NOT EXISTS ${name} (
14
+ run_id TEXT NOT NULL, leader_pid INTEGER NOT NULL, kind TEXT NOT NULL, node_id TEXT,
15
+ start TEXT NOT NULL DEFAULT '', created_at INTEGER NOT NULL, PRIMARY KEY (run_id, leader_pid, start)
16
+ );`;
17
+ const SCHEMA = `
18
+ CREATE TABLE IF NOT EXISTS runs (
19
+ id TEXT PRIMARY KEY, created_at INTEGER NOT NULL, root_cwd TEXT NOT NULL,
20
+ config_json TEXT NOT NULL, status TEXT NOT NULL DEFAULT 'active'
21
+ );
22
+ CREATE TABLE IF NOT EXISTS nodes (
23
+ id TEXT PRIMARY KEY, run_id TEXT NOT NULL, parent_id TEXT, kind TEXT NOT NULL,
24
+ target TEXT, mode TEXT NOT NULL, depth INTEGER NOT NULL, allow_delegation INTEGER NOT NULL,
25
+ status TEXT NOT NULL, task TEXT NOT NULL, params_json TEXT, session_id TEXT,
26
+ cwd TEXT NOT NULL, repo TEXT, worktree TEXT, branch TEXT, base_sha TEXT, model TEXT, effort TEXT,
27
+ worker_pid INTEGER, worker_claimed_at INTEGER, agent_pid INTEGER, agent_pgid INTEGER,
28
+ log_path TEXT, transcript_path TEXT, result_json TEXT, error TEXT,
29
+ created_at INTEGER NOT NULL, started_at INTEGER, ended_at INTEGER
30
+ );
31
+ CREATE INDEX IF NOT EXISTS nodes_run ON nodes(run_id);
32
+ CREATE INDEX IF NOT EXISTS nodes_parent ON nodes(parent_id);
33
+ -- One row per turn sent to a session. Queued rows are the session's inbox.
34
+ CREATE TABLE IF NOT EXISTS turns (
35
+ id INTEGER PRIMARY KEY AUTOINCREMENT, node_id TEXT NOT NULL, source TEXT NOT NULL,
36
+ body TEXT NOT NULL, access TEXT NOT NULL, status TEXT NOT NULL, reply TEXT, error TEXT,
37
+ prompt_path TEXT, created_at INTEGER NOT NULL, started_at INTEGER, ended_at INTEGER
38
+ );
39
+ CREATE INDEX IF NOT EXISTS turns_node ON turns(node_id);
40
+ -- Human messages injected into a live discussion.
41
+ CREATE TABLE IF NOT EXISTS injections (
42
+ id INTEGER PRIMARY KEY AUTOINCREMENT, discussion_id TEXT NOT NULL, body TEXT NOT NULL,
43
+ created_at INTEGER NOT NULL
44
+ );
45
+ -- Approval requests from launched agents. status: pending | allowed | denied | expired.
46
+ CREATE TABLE IF NOT EXISTS requests (
47
+ id TEXT PRIMARY KEY, run_id TEXT NOT NULL, node_id TEXT NOT NULL, kind TEXT NOT NULL,
48
+ summary TEXT NOT NULL, reason TEXT, detail_json TEXT, status TEXT NOT NULL,
49
+ decided_by TEXT, note TEXT, created_at INTEGER NOT NULL, decided_at INTEGER
50
+ );
51
+ CREATE INDEX IF NOT EXISTS requests_run ON requests(run_id, status);
52
+ -- Approval requests put to the user through a root session's host (MCP elicitation), one row per
53
+ -- request: which relay server asked, and how it ended. outcome is null while the question is open;
54
+ -- reading is how relay took the answer: decided, dismissed (undecided), error or withdrawn.
55
+ CREATE TABLE IF NOT EXISTS elicitations (
56
+ request_id TEXT PRIMARY KEY, token TEXT NOT NULL, pid INTEGER NOT NULL, pid_start TEXT,
57
+ asked_at INTEGER NOT NULL, outcome TEXT, reading TEXT, ended_at INTEGER
58
+ );
59
+ -- What root sessions should hear about in their runs, each recorded once (key). noticed_at: a
60
+ -- notice was posted to the session's inbox; seen_at: it was returned in a tool result.
61
+ CREATE TABLE IF NOT EXISTS events (
62
+ id INTEGER PRIMARY KEY AUTOINCREMENT, run_id TEXT NOT NULL, key TEXT NOT NULL UNIQUE, kind TEXT NOT NULL,
63
+ item_id TEXT NOT NULL, subject TEXT NOT NULL, text TEXT NOT NULL, created_at INTEGER NOT NULL,
64
+ noticed_at INTEGER, seen_at INTEGER
65
+ );
66
+ CREATE INDEX IF NOT EXISTS events_run ON events(run_id, seen_at);
67
+ -- Relay's own server and worker processes, so that cleanup of an agent's processes can tell them apart.
68
+ CREATE TABLE IF NOT EXISTS relay_procs (
69
+ pid INTEGER NOT NULL, start TEXT NOT NULL, kind TEXT NOT NULL, node_id TEXT, created_at INTEGER NOT NULL
70
+ );
71
+ -- Process-group / session leaders relay has launched (workers and agents, each started detached, so
72
+ -- leader pid == pgid == sid). Kept for the run's lifetime, never cleared when the leader dies: an
73
+ -- orphan left in a dead leader's group or session is still placed inside the launched tree
74
+ -- (src/core/presence.ts). The start column is the leader's start time as ps prints it (empty when
75
+ -- relay could not read it), part of the key so a pid reused within a run keeps every leader it led;
76
+ -- a live process at that pid whose start matches none of them means its old group/session is gone.
77
+ ${LAUNCH_LEADERS_DDL("launch_leaders")}
78
+ -- Calls that named a request_id, and what each started (src/core/calls.ts). scope: the caller.
79
+ -- claim, owner_pid, owner_start: the call holding it while it starts (node_id '').
80
+ CREATE TABLE IF NOT EXISTS calls (
81
+ scope TEXT NOT NULL, request_id TEXT NOT NULL, tool TEXT NOT NULL, args_hash TEXT NOT NULL,
82
+ node_id TEXT NOT NULL, turn_id INTEGER, claim TEXT NOT NULL, owner_pid INTEGER NOT NULL, owner_start TEXT,
83
+ created_at INTEGER NOT NULL, PRIMARY KEY (scope, request_id)
84
+ );
85
+ -- Concurrency slots. state: waiting | held | lent.
86
+ CREATE TABLE IF NOT EXISTS slots (
87
+ id INTEGER PRIMARY KEY AUTOINCREMENT, run_id TEXT NOT NULL, holder TEXT NOT NULL,
88
+ pid INTEGER NOT NULL, state TEXT NOT NULL, created_at INTEGER NOT NULL
89
+ );
90
+ `;
91
+ /**
92
+ * The registry's schema version, kept in the file's PRAGMA user_version (0.2.0 never set it, so
93
+ * its files read 0). Bump it with every change to SCHEMA or to migrate() below: the first open by
94
+ * a relay with a higher version backs the file up before changing it (see docs/UPGRADING.md), and
95
+ * a relay with a lower version refuses the file rather than work on a schema it does not know.
96
+ */
97
+ export const SCHEMA_VERSION = 4;
98
+ let handle = null;
99
+ let backupMade = null;
100
+ /** Where this process backed up the registry before migrating it, or null if it did not need to. */
101
+ export const registryBackup = () => backupMade;
102
+ /** The registry file and its schema version, read without changing anything; null when there is none yet. */
103
+ export function registryVersion() {
104
+ const file = path.join(relayHome(), "relay.db");
105
+ if (!fs.existsSync(file))
106
+ return null;
107
+ const d = new DatabaseSync(file, { readOnly: true });
108
+ try {
109
+ d.exec("PRAGMA busy_timeout = 10000;");
110
+ return { file, version: d.prepare("PRAGMA user_version").get().user_version };
111
+ }
112
+ finally {
113
+ d.close();
114
+ }
115
+ }
116
+ /**
117
+ * Refuses a registry from a newer relay. Before a registry from an earlier relay is migrated, a
118
+ * consistent copy of it is written next to it (relay.db.backup-v<its version>-<time>-<pid>); if
119
+ * that copy cannot be made, the file is left as it is and relay stops, since going back to the
120
+ * earlier relay depends on it. Returns the version the file had.
121
+ */
122
+ function guardVersion(d, file, home) {
123
+ const found = d.prepare("PRAGMA user_version").get().user_version;
124
+ if (found > SCHEMA_VERSION) {
125
+ throw new Error(`relay's registry ${file} was written by a newer relay (schema version ${found}; this relay knows up to ${SCHEMA_VERSION}), so this relay will not use it. Run the newer relay, or restore the backup that relay made when it upgraded the file (relay.db.backup-v${SCHEMA_VERSION}-… in ${home}); see docs/UPGRADING.md.`);
126
+ }
127
+ const existing = d.prepare("SELECT count(*) AS n FROM sqlite_master WHERE type = 'table' AND name = 'runs'").get().n > 0;
128
+ if (existing && found < SCHEMA_VERSION && !backupMade) {
129
+ const backup = path.join(home, `relay.db.backup-v${found}-${new Date().toISOString().replace(/[:.]/g, "-")}-${process.pid}`);
130
+ try {
131
+ d.prepare("VACUUM INTO ?").run(backup);
132
+ }
133
+ catch (err) {
134
+ if (/locked|busy/i.test(err.message))
135
+ throw err;
136
+ throw new Error(`relay's registry ${file} is from an earlier relay (schema version ${found}) and needs migrating, but relay could not back it up first to ${backup} (${err.message}), so it has left the file as it is.`);
137
+ }
138
+ backupMade = backup;
139
+ }
140
+ return found;
141
+ }
142
+ /** Tests that use several scratch registries in one process must release the cached connection. */
143
+ export function closeDbForTests() {
144
+ handle?.close();
145
+ handle = null;
146
+ backupMade = null;
147
+ }
148
+ export function db() {
149
+ if (handle)
150
+ return handle;
151
+ const home = relayHome();
152
+ // Prompts, logs and transcripts live here and can hold anything an agent read. Private to the
153
+ // user, including a directory made before relay set this.
154
+ fs.mkdirSync(home, { recursive: true, mode: 0o700 });
155
+ if ((fs.statSync(home).mode & 0o077) !== 0) {
156
+ try {
157
+ fs.chmodSync(home, 0o700);
158
+ }
159
+ catch {
160
+ // Reported below.
161
+ }
162
+ if ((fs.statSync(home).mode & 0o077) !== 0)
163
+ throw new Error(`relay's control directory ${home} is open to other users and relay could not make it private (mode 700). Fix its owner or mode, or set RELAY_HOME elsewhere.`);
164
+ }
165
+ const file = path.join(home, "relay.db");
166
+ const d = new DatabaseSync(file);
167
+ // The busy timeout comes first: switching to WAL and creating the schema take a write lock, and
168
+ // several relay processes can open a fresh database at the same moment.
169
+ d.exec("PRAGMA busy_timeout = 10000;");
170
+ const migrate = () => {
171
+ // Columns added after a table first shipped.
172
+ const add = (table, column, type) => {
173
+ const cols = d.prepare(`PRAGMA table_info(${table})`).all().map((c) => c.name);
174
+ if (cols.includes(column))
175
+ return;
176
+ try {
177
+ d.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${type}`);
178
+ }
179
+ catch (err) {
180
+ // Another process starting at the same moment added it first.
181
+ if (!/duplicate column/i.test(err.message))
182
+ throw err;
183
+ }
184
+ };
185
+ add("requests", "scope", "TEXT");
186
+ add("requests", "turn_id", "INTEGER");
187
+ add("runs", "root_pid", "INTEGER");
188
+ add("runs", "root_start", "TEXT");
189
+ add("runs", "root_token", "TEXT");
190
+ add("nodes", "worker_start", "TEXT");
191
+ add("nodes", "agent_start", "TEXT");
192
+ add("nodes", "owner_id", "TEXT");
193
+ add("nodes", "head_sha", "TEXT");
194
+ add("turns", "denials", "TEXT");
195
+ add("turns", "activity", "TEXT");
196
+ add("turns", "activity_at", "INTEGER");
197
+ add("turns", "usage_json", "TEXT");
198
+ add("turns", "tmp_dir", "TEXT");
199
+ add("turns", "tmp_dev", "INTEGER");
200
+ add("turns", "tmp_ino", "INTEGER");
201
+ add("turns", "grant_json", "TEXT");
202
+ add("turns", "refusal_json", "TEXT");
203
+ add("launch_leaders", "start", "TEXT");
204
+ rekeyLaunchLeaders();
205
+ };
206
+ // A schema-4 file written by an unreleased build of this branch keyed launch_leaders on
207
+ // (run_id, leader_pid) alone, keeping only the first start time a reused pid had. Rebuild it under
208
+ // the current key, carrying every row over (an unknown start becomes ''). Version stays 4.
209
+ const rekeyLaunchLeaders = () => {
210
+ const keyed = () => d.prepare("PRAGMA table_info(launch_leaders)").all().some((c) => c.name === "start" && c.pk > 0);
211
+ if (keyed())
212
+ return;
213
+ d.exec("BEGIN IMMEDIATE");
214
+ try {
215
+ if (!keyed()) {
216
+ d.exec("DROP TABLE IF EXISTS launch_leaders_rekey");
217
+ d.exec(LAUNCH_LEADERS_DDL("launch_leaders_rekey"));
218
+ d.exec("INSERT OR IGNORE INTO launch_leaders_rekey (run_id, leader_pid, kind, node_id, start, created_at) SELECT run_id, leader_pid, kind, node_id, COALESCE(start, ''), created_at FROM launch_leaders");
219
+ d.exec("DROP TABLE launch_leaders");
220
+ d.exec("ALTER TABLE launch_leaders_rekey RENAME TO launch_leaders");
221
+ }
222
+ d.exec("COMMIT");
223
+ }
224
+ catch (err) {
225
+ try {
226
+ d.exec("ROLLBACK");
227
+ }
228
+ catch { /* nothing open */ }
229
+ throw err;
230
+ }
231
+ };
232
+ for (let attempt = 0;; attempt++) {
233
+ try {
234
+ const found = guardVersion(d, file, home);
235
+ d.exec("PRAGMA journal_mode = WAL; PRAGMA synchronous = NORMAL;");
236
+ d.exec(SCHEMA);
237
+ migrate();
238
+ if (found < SCHEMA_VERSION)
239
+ d.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`);
240
+ break;
241
+ }
242
+ catch (err) {
243
+ if (attempt >= 20 || !/locked|busy/i.test(err.message)) {
244
+ d.close();
245
+ throw err;
246
+ }
247
+ Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 100);
248
+ }
249
+ }
250
+ handle = d;
251
+ return d;
252
+ }
253
+ /**
254
+ * Statements prepared on this process's connection, by their SQL text, for the reads relay makes
255
+ * over and over (status reads every item of a run several ways). node:sqlite resets a statement
256
+ * after each get, all and run, so a kept statement holds no snapshot or lock between uses and every
257
+ * use sees what has been committed since; SQLite prepares it again by itself after a schema change.
258
+ * Kept with the connection they were prepared on, which finalizes them when it closes.
259
+ */
260
+ const prepared = new WeakMap();
261
+ function stmt(sql) {
262
+ const d = db();
263
+ let mine = prepared.get(d);
264
+ if (!mine)
265
+ prepared.set(d, (mine = new Map()));
266
+ let s = mine.get(sql);
267
+ if (!s)
268
+ mine.set(sql, (s = d.prepare(sql)));
269
+ return s;
270
+ }
271
+ export function registryMark() {
272
+ const r = stmt("SELECT data_version AS others, total_changes() AS own FROM pragma_data_version()").get();
273
+ return { conn: db(), others: r.others, own: r.own };
274
+ }
275
+ export const sameMark = (a, b) => a.conn === b.conn && a.others === b.others && a.own === b.own;
276
+ export const now = () => Date.now();
277
+ export const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
278
+ const PREFIX = {
279
+ run: "run", job: "j", thread: "t", participant: "p", discussion: "d", review: "r", request: "q",
280
+ };
281
+ export function newId(kind) {
282
+ return `${PREFIX[kind]}_${crypto.randomBytes(4).toString("hex")}`;
283
+ }
284
+ /** Runs fn inside BEGIN IMMEDIATE so read-then-write sequences are atomic across processes. */
285
+ export function tx(fn) {
286
+ const d = db();
287
+ d.exec("BEGIN IMMEDIATE");
288
+ try {
289
+ const out = fn();
290
+ d.exec("COMMIT");
291
+ return out;
292
+ }
293
+ catch (err) {
294
+ d.exec("ROLLBACK");
295
+ throw err;
296
+ }
297
+ }
298
+ export function getRun(id) {
299
+ return stmt("SELECT * FROM runs WHERE id = ?").get(id);
300
+ }
301
+ const parsedRuns = new Map();
302
+ /** Runs kept parsed at most; a process looks at one or a few runs at a time. */
303
+ const PARSED_RUNS_MAX = 32;
304
+ function deepFreeze(v) {
305
+ if (v && typeof v === "object" && !Object.isFrozen(v)) {
306
+ Object.freeze(v);
307
+ for (const x of Object.values(v))
308
+ deepFreeze(x);
309
+ }
310
+ return v;
311
+ }
312
+ /** The run's config_json, parsed (see ParsedRun); undefined for a run not in the registry. Throws where the text is not JSON. */
313
+ function parsedRun(runId) {
314
+ const mark = registryMark();
315
+ const hit = parsedRuns.get(runId);
316
+ // Nothing in the registry has changed since the text was read, so it is still the run's.
317
+ if (hit && sameMark(hit.mark, mark))
318
+ return hit;
319
+ const row = stmt("SELECT config_json FROM runs WHERE id = ?").get(runId);
320
+ if (!row)
321
+ return undefined;
322
+ if (hit && hit.text === row.config_json) {
323
+ hit.mark = mark;
324
+ return hit;
325
+ }
326
+ // runs has no params column in schema 4. Private run params share its existing JSON envelope,
327
+ // and must never leak into the effective configuration or its authorization fingerprints.
328
+ const { params_json: params, ...config } = JSON.parse(row.config_json);
329
+ let parsed = null;
330
+ try {
331
+ // A copy, so that freezing it cannot freeze anything withDefaults shares with its defaults.
332
+ parsed = deepFreeze(structuredClone(withDefaults(config)));
333
+ }
334
+ catch {
335
+ // Not valid: runConfig refuses it afresh every time it is asked.
336
+ }
337
+ const entry = { text: row.config_json, mark, config: parsed, overlays: params?.overlays !== undefined, reservations: params?.launch_reservations !== undefined };
338
+ if (!hit && parsedRuns.size >= PARSED_RUNS_MAX)
339
+ parsedRuns.delete(parsedRuns.keys().next().value);
340
+ parsedRuns.set(runId, entry);
341
+ return entry;
342
+ }
343
+ /** The run's configuration, a copy of its own for each caller: some change what they are given (env-broker.ts). */
344
+ export function runConfig(runId) {
345
+ const run = parsedRun(runId);
346
+ if (!run)
347
+ throw new Error(`unknown run ${runId}`);
348
+ if (run.config)
349
+ return structuredClone(run.config);
350
+ const { params_json: _params, ...config } = JSON.parse(run.text);
351
+ return withDefaults(config);
352
+ }
353
+ export function createRun(rootCwd, config, token) {
354
+ const id = newId("run");
355
+ const d = db();
356
+ // Capture trusted expansions before any child can start. Checkpoints keep these identities
357
+ // even if paths disappear or the person's next config selects another destination.
358
+ const policy = resolveNeverPolicy({ never: config.never, codexHome: config.targets.codex.home });
359
+ const snapshot = { ...config, params_json: { never_floor: { policy, configRequired: fs.existsSync(configPath()) } } };
360
+ d.prepare("INSERT INTO runs (id, created_at, root_cwd, config_json, root_pid, root_start, root_token) VALUES (?, ?, ?, ?, ?, ?, ?)")
361
+ .run(id, now(), rootCwd, JSON.stringify(snapshot), process.pid, procStart(process.pid), token);
362
+ return id;
363
+ }
364
+ export function latestRun() {
365
+ // Prefer the latest run that actually started something.
366
+ return (db().prepare("SELECT * FROM runs WHERE id IN (SELECT run_id FROM nodes) ORDER BY created_at DESC LIMIT 1").get()
367
+ ?? db().prepare("SELECT * FROM runs ORDER BY created_at DESC LIMIT 1").get());
368
+ }
369
+ export function getNode(id) {
370
+ return stmt("SELECT * FROM nodes WHERE id = ?").get(id);
371
+ }
372
+ export function runNodes(runId) {
373
+ return stmt("SELECT * FROM nodes WHERE run_id = ? ORDER BY created_at, id").all(runId);
374
+ }
375
+ /**
376
+ * The job whose worktree holds `dir`: relay runs git for such a directory with the git directory the
377
+ * repository records for that worktree (git.ts jobTree), never through the worktree's `.git` file,
378
+ * which the job's agent can rewrite. "unknown" for a directory inside relay's worktree directory
379
+ * that no job's worktree holds; null for any other directory.
380
+ */
381
+ export function worktreeHolder(dir) {
382
+ // By relay's own records first, without going through the filesystem: a path recorded inside a
383
+ // job's worktree belongs to that job even if a component of it is now a link to somewhere else.
384
+ const lexical = lexicalHolder(dir);
385
+ if (lexical)
386
+ return lexical;
387
+ const real = canonical(dir);
388
+ const holder = worktreeRows().find((n) => inside(real, n.worktree));
389
+ if (holder)
390
+ return holder;
391
+ return inside(real, worktreesHome()) ? "unknown" : null;
392
+ }
393
+ const worktreeRows = () => db().prepare("SELECT * FROM nodes WHERE worktree IS NOT NULL ORDER BY created_at DESC").all();
394
+ /** The job whose recorded worktree holds `dir` as a path, compared as strings, never resolved. */
395
+ function lexicalHolder(dir) {
396
+ const p = path.resolve(dir);
397
+ // Only rows whose worktree begins `dir` can hold it, which SQLite finds without handing every
398
+ // worktree in the registry's history to JavaScript; the comparison that decides is the same.
399
+ const rows = stmt("SELECT * FROM nodes WHERE worktree IS NOT NULL AND instr(?, worktree) = 1 ORDER BY created_at DESC").all(p);
400
+ return rows.find((n) => p === n.worktree || p.startsWith(n.worktree.endsWith(path.sep) ? n.worktree : n.worktree + path.sep));
401
+ }
402
+ /**
403
+ * The directory relay works in for a node, wherever it reads one (a launch, a resumed child, a nested
404
+ * delegate, native resume, approval details). A write job's own is its worktree root, whatever an
405
+ * earlier relay recorded: before the root launch it recorded the caller's subdirectory, which a
406
+ * process the agent left running can swap for a link. A node recorded inside a job's worktree (an
407
+ * in-place child) gets that worktree's root the same way. Matched against relay's own records,
408
+ * never through the filesystem. Any other node's directory is its own.
409
+ */
410
+ export function workCwd(n) {
411
+ if (n.worktree)
412
+ return n.worktree;
413
+ return lexicalHolder(n.cwd)?.worktree ?? n.cwd;
414
+ }
415
+ /**
416
+ * Rewrites a write job recorded with a subdirectory cwd (by a relay before the root launch) to its
417
+ * worktree root, keeping where the caller was, as the path recorded (never resolved), in params_json
418
+ * subdir. Returns the row as it is now.
419
+ */
420
+ export function normaliseWorkCwd(n) {
421
+ if (!n.worktree || n.cwd === n.worktree)
422
+ return n;
423
+ const rel = path.relative(n.worktree, n.cwd);
424
+ const within = rel !== "" && rel !== ".." && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel);
425
+ // One statement, setting subdir only where none is recorded: nothing else in params_json is
426
+ // written back from the row read earlier (review C11).
427
+ db().prepare("UPDATE nodes SET cwd = ?, params_json = CASE WHEN ? IS NULL OR json_type(COALESCE(params_json, '{}'), '$.subdir') = 'text' THEN params_json ELSE json_set(COALESCE(params_json, '{}'), '$.subdir', ?) END WHERE id = ?").run(n.worktree, within ? 1 : null, rel.split(path.sep).join("/"), n.id);
428
+ return getNode(n.id);
429
+ }
430
+ /**
431
+ * Sets one key of a node's params_json, in one statement, leaving every other key as it is in the
432
+ * row now (review C11). params_json is written by several processes (the worker re-pinning a
433
+ * restored worktree, a root session granting more): a whole object written back from a copy read
434
+ * earlier would undo whatever another wrote in between.
435
+ */
436
+ export function setParam(nodeId, key, value) {
437
+ if (!/^[a-z_]+$/.test(key))
438
+ throw new Error(`not a params_json key: ${key}`);
439
+ db().prepare("UPDATE nodes SET params_json = json_set(COALESCE(params_json, '{}'), ?, json(?)) WHERE id = ?").run(`$.${key}`, JSON.stringify(value ?? null), nodeId);
440
+ }
441
+ function childrenOf(id) {
442
+ return stmt("SELECT * FROM nodes WHERE parent_id = ? ORDER BY created_at, id").all(id);
443
+ }
444
+ export function descendants(id) {
445
+ const out = [];
446
+ const stack = [id];
447
+ while (stack.length) {
448
+ for (const child of childrenOf(stack.pop())) {
449
+ out.push(child);
450
+ stack.push(child.id);
451
+ }
452
+ }
453
+ return out;
454
+ }
455
+ /**
456
+ * The node's ancestors, its parent first, as far up as the registry has them (a parent that is
457
+ * not there ends the walk); with `self`, the node itself comes first.
458
+ */
459
+ export function ancestors(n, o = {}) {
460
+ const out = o.self ? [n] : [];
461
+ for (let cur = n.parent_id ? getNode(n.parent_id) : undefined; cur; cur = cur.parent_id ? getNode(cur.parent_id) : undefined)
462
+ out.push(cur);
463
+ return out;
464
+ }
465
+ /**
466
+ * True when the node's run, or one of its ancestors, has been cancelled; with `self`, the node
467
+ * itself counts too. A caller that has no node in hand decides for itself what a missing one means.
468
+ */
469
+ export function cancelledAbove(n, o = {}) {
470
+ if (getRun(n.run_id)?.status === "cancelled")
471
+ return true;
472
+ return ancestors(n, o).some((a) => a.status === "cancelled");
473
+ }
474
+ /**
475
+ * Why a turn is no longer one a launched agent's relay connection can act for, or null: it must be
476
+ * in the registry as the node's, running, and so must the node's session.
477
+ */
478
+ export function turnEnded(nodeId, turnId) {
479
+ const t = getTurn(turnId);
480
+ if (!t || t.node_id !== nodeId)
481
+ return `turn ${turnId} of ${nodeId} is not in the registry`;
482
+ if (t.status !== "running")
483
+ return `turn ${turnId} of ${nodeId} has ended (${t.status})`;
484
+ const n = getNode(nodeId);
485
+ // The turn's own record is not enough: the session must still be running.
486
+ if (!n || n.status !== "running")
487
+ return `turn ${turnId} of ${nodeId} has ended (its session is ${n?.status ?? "gone"})`;
488
+ return overlayTurnProblem(nodeId, turnId);
489
+ }
490
+ export function insertNode(n) {
491
+ const row = {
492
+ parent_id: null, target: null, allow_delegation: 0, status: "queued", params_json: null,
493
+ repo: null, worktree: null, branch: null, base_sha: null, model: null, effort: null,
494
+ created_at: now(), ...n,
495
+ };
496
+ db().prepare(`INSERT INTO nodes (id, run_id, parent_id, kind, target, mode, depth, allow_delegation, status, task,
497
+ params_json, cwd, repo, worktree, branch, base_sha, model, effort, created_at)
498
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(row.id, row.run_id, row.parent_id, row.kind, row.target, row.mode, row.depth, row.allow_delegation, row.status, row.task, row.params_json, row.cwd, row.repo, row.worktree, row.branch, row.base_sha, row.model, row.effort, row.created_at);
499
+ return getNode(row.id);
500
+ }
501
+ export function updateNode(id, fields) {
502
+ const keys = Object.keys(fields);
503
+ if (!keys.length)
504
+ return;
505
+ const sql = `UPDATE nodes SET ${keys.map((k) => `${k} = ?`).join(", ")} WHERE id = ?`;
506
+ db().prepare(sql).run(...keys.map((k) => fields[k]), id);
507
+ }
508
+ export function insertTurn(nodeId, source, body, access, status = "queued") {
509
+ const r = db().prepare("INSERT INTO turns (node_id, source, body, access, status, created_at) VALUES (?, ?, ?, ?, ?, ?)")
510
+ .run(nodeId, source, body, access, status, now());
511
+ return Number(r.lastInsertRowid);
512
+ }
513
+ export function getTurn(id) {
514
+ return stmt("SELECT * FROM turns WHERE id = ?").get(id);
515
+ }
516
+ export function updateTurn(id, fields) {
517
+ const keys = Object.keys(fields);
518
+ const sql = `UPDATE turns SET ${keys.map((k) => `${k} = ?`).join(", ")} WHERE id = ?`;
519
+ db().prepare(sql).run(...keys.map((k) => fields[k]), id);
520
+ }
521
+ export function nextQueuedTurn(nodeId) {
522
+ return stmt("SELECT * FROM turns WHERE node_id = ? AND status = 'queued' ORDER BY id LIMIT 1").get(nodeId);
523
+ }
524
+ /**
525
+ * The speed a session goes on at: that of the last of its queued turns a call was admitted at
526
+ * (params.ts queuedSpeeds; caller.ts changeSpeed), else that of its turn now running or last
527
+ * started. What a call that continues the session and names no speed runs at, and what admits it.
528
+ * A speed kept for a turn that ended without starting (cancelled while queued) counts for nothing.
529
+ */
530
+ export function speedAfter(n) {
531
+ const queued = queuedSpeeds(n);
532
+ if (!queued.length)
533
+ return speedOf(n);
534
+ const live = queuedTurnIds(n.id);
535
+ return queued.filter(([t]) => live.has(t)).at(-1)?.[1] ?? speedOf(n);
536
+ }
537
+ /** The ids of a node's turns still queued. */
538
+ export const queuedTurnIds = (nodeId) => new Set(stmt("SELECT id FROM turns WHERE node_id = ? AND status = 'queued'").all(nodeId).map((r) => r.id));
539
+ export function nodeTurns(nodeId) {
540
+ return stmt("SELECT * FROM turns WHERE node_id = ? ORDER BY id").all(nodeId);
541
+ }
542
+ /** A node's turns, in order, with only what an item's view reports of them (views.ts): not the prompts and replies. */
543
+ export function turnReports(nodeId) {
544
+ return stmt("SELECT status, usage_json FROM turns WHERE node_id = ? ORDER BY id").all(nodeId);
545
+ }
546
+ /**
547
+ * Relay's own servers and workers announce themselves here. Cleanup of what an agent started must
548
+ * leave them alone: a launched agent's relay server starts workers for jobs that are meant to
549
+ * outlive the agent's turn.
550
+ */
551
+ export function registerSelf(kind, nodeId) {
552
+ const start = procStart(process.pid);
553
+ if (!start)
554
+ return;
555
+ db().prepare("INSERT INTO relay_procs (pid, start, kind, node_id, created_at) VALUES (?, ?, ?, ?, ?)").run(process.pid, start, kind, nodeId, now());
556
+ }
557
+ /**
558
+ * Relay's own registered processes (relay_procs), by pid, each with its start time as ps prints it:
559
+ * what the process helpers in procs.ts spare, read afresh at each look.
560
+ */
561
+ export const relayProcs = () => new Map(stmt("SELECT pid, start FROM relay_procs").all().map((p) => [p.pid, p.start.replace(/\s+/g, " ")]));
562
+ /**
563
+ * Records a process-group / session leader relay launched (a worker or an agent, started detached,
564
+ * so its pid is its pgid and sid). Kept for the run's lifetime; the presence check matches a
565
+ * current process's group or session against these numeric ids even after the leader has died
566
+ * (src/core/presence.ts). Idempotent per (run, pid).
567
+ */
568
+ export function recordLaunchLeader(runId, leaderPid, kind, nodeId) {
569
+ if (!leaderPid || leaderPid <= 1)
570
+ return;
571
+ // The leader is alive at this point, so its start time is readable; it pins the pid against reuse.
572
+ const start = procStart(leaderPid);
573
+ // Keyed on the start too, so a pid that leads again later in the run adds a row rather than being ignored.
574
+ db().prepare("INSERT OR IGNORE INTO launch_leaders (run_id, leader_pid, kind, node_id, start, created_at) VALUES (?, ?, ?, ?, ?, ?)").run(runId, leaderPid, kind, nodeId, start ?? "", now());
575
+ }
576
+ /** Every launched leader id relay has recorded, across runs, each with what it is and its start time, for the presence check. */
577
+ export const launchLeaders = () => db().prepare("SELECT leader_pid, kind, node_id, start FROM launch_leaders ORDER BY created_at, rowid").all()
578
+ .map((l) => ({ ...l, start: l.start ? l.start : null })); // '' (unknown) reads as null
579
+ const CLAIM_GRACE_MS = 15000;
580
+ /** True while some worker process owns the node (or was claimed moments ago and is still starting). */
581
+ export function workerLive(n) {
582
+ if (n.worker_pid === null)
583
+ return false;
584
+ if (n.worker_pid === -1)
585
+ return now() - (n.worker_claimed_at ?? 0) < CLAIM_GRACE_MS;
586
+ return sameProcess(n.worker_pid, n.worker_start);
587
+ }
588
+ /** The one answer to "is this item in use right now": it is queued or running. Waits, views, merge, cleanup and cancel all go by this. */
589
+ export function busy(n) {
590
+ return ACTIVE.includes(n.status);
591
+ }
592
+ /**
593
+ * Whether a session is done with one of its turns, which is what a call waiting on the turn (ask,
594
+ * a discussion's reply) waits for: the turn is over, and its session has recorded that with its
595
+ * own end, or has no worker left that could. A turn that started is recorded as over as soon as
596
+ * its agent has ended, since the turn's authority ends with it; the session records the turn's end
597
+ * after relay's work on it (a job's commit), settling, or showing as queued for its next turn, in
598
+ * one transaction (outcome.ts finishTurn); until then the session shows as running with no turn
599
+ * running. Once recorded, it stays so for every later state of the session: a later turn that has
600
+ * started (running, or over since, its own end perhaps not yet recorded) means the worker had
601
+ * recorded this one, since it records each turn's end before it starts another. Later is by id
602
+ * and by start time both: a turn that jumped ahead of this one (an overlay's restart) started
603
+ * before it. A turn that never started is recorded as over in that transaction, or by a cancel or
604
+ * reap that ends its session first. A worker is taken for gone only once it is known to be
605
+ * (processGone): one whose start time ps cannot read at the moment may still be recording the
606
+ * turn's end. The wait stays bounded by the call's own limit, and by reap.
607
+ */
608
+ export function turnSettled(t) {
609
+ if (!t)
610
+ return true;
611
+ if (t.status === "queued" || t.status === "running")
612
+ return false;
613
+ if (t.started_at === null)
614
+ return true;
615
+ const n = getNode(t.node_id);
616
+ if (!n || n.status !== "running")
617
+ return true;
618
+ if (stmt("SELECT 1 FROM turns WHERE node_id = ? AND id > ? AND started_at >= ? LIMIT 1").get(n.id, t.id, t.started_at))
619
+ return true;
620
+ // No worker recorded, or a claim of one that never started (workerLive), is none.
621
+ if (n.worker_pid === null || n.worker_pid === -1)
622
+ return !workerLive(n);
623
+ return processGone(n.worker_pid, n.worker_start);
624
+ }
625
+ /** Ends every turn of a node that is still marked running or queued. */
626
+ export function closeTurns(nodeId, status, error) {
627
+ stopNodeLaunchReservations(nodeId);
628
+ db().prepare("UPDATE turns SET status = ?, error = COALESCE(error, ?), ended_at = ? WHERE node_id = ? AND status IN ('running', 'queued')").run(status, error, now(), nodeId);
629
+ }
630
+ /**
631
+ * Deals with an agent whose supervising process has gone. If the recorded group is still the one
632
+ * relay started, it is killed. Keeps the agent identity when cleanup is unconfirmed or refused;
633
+ * refusal also carries a persistent executor quarantine, since its sandbox cannot prove the
634
+ * absence of a live app server that could reconnect to a reused executor port.
635
+ */
636
+ function stopOrphan(n) {
637
+ const clear = () => updateNode(n.id, { agent_pid: null, agent_pgid: null, agent_start: null });
638
+ if (!n.agent_pgid)
639
+ return { outcome: "none", note: "" };
640
+ if (!groupAlive(n.agent_pgid)) {
641
+ clear();
642
+ return { outcome: "none", note: "" };
643
+ }
644
+ // A live leader with a different start time means the number now belongs to something else.
645
+ if (pidAlive(n.agent_pid) && n.agent_start && !sameProcess(n.agent_pid, n.agent_start, { fresh: true })) {
646
+ clear();
647
+ return { outcome: "none", note: "" };
648
+ }
649
+ // There is no supervisor left to ask the agent to stop cleanly, so everything it started goes with it.
650
+ try {
651
+ // Only the recorded group leader can authorize reaping an ancestor (an agent may have
652
+ // started the MCP server doing this reap). killGroupNow checks this identity fresh again.
653
+ const leader = n.agent_pid === n.agent_pgid && n.agent_start ? { pid: n.agent_pid, start: n.agent_start } : undefined;
654
+ if (!killGroupNow(n.agent_pgid, relayProcs, leader))
655
+ return { outcome: "unconfirmed", note: ` An agent process (group ${n.agent_pgid}) may still be running.` };
656
+ }
657
+ catch (err) {
658
+ if (!isGroupSignalRefusal(err))
659
+ throw err;
660
+ const note = ` Agent cleanup refused for group ${n.agent_pgid}: ${err.message}.`;
661
+ return { outcome: "refused", note, quarantine: `untraceable app-server cleanup:${note}` };
662
+ }
663
+ clear();
664
+ return { outcome: "stopped", note: "" };
665
+ }
666
+ /**
667
+ * Marks active nodes whose worker has died as lost, stops agents left without a supervisor,
668
+ * releases sessions whose moderator has died, and drops slots held by dead processes. Called from
669
+ * status and from slot acquisition so stale state never blocks a run.
670
+ */
671
+ export function reap(runId) {
672
+ // Overlays and launch reservations are kept in the run's params; a run that holds none (most)
673
+ // has nothing for either to reap, and they are not parsed. Looked at again after the first,
674
+ // which rewrites those params. Where the run cannot be read, each is left to say why.
675
+ const holds = (which) => {
676
+ try {
677
+ return parsedRun(runId)?.[which] ?? true;
678
+ }
679
+ catch {
680
+ return true;
681
+ }
682
+ };
683
+ if (holds("reservations"))
684
+ reapLaunchReservations(runId, (r) => {
685
+ const n = getNode(r.nodeId);
686
+ const app = n ? stopOrphan(n) : undefined;
687
+ const appProblem = app?.note ?? "node unavailable";
688
+ const current = executorRecords();
689
+ const owned = current.records.filter(x => x.record.nodeId === r.nodeId && x.record.turnId === r.turnId);
690
+ const stopped = owned.map(rec => app?.outcome === "refused" ? quarantineRecordedExecutor(rec, app.quarantine) : stopRecordedExecutorNow(rec, appProblem || undefined));
691
+ // An absent native leader cannot prove detached cleanup. An executor sweep proves only its
692
+ // own sandbox; retain any uncertainty the worker recorded about the unconfined app server.
693
+ const clean = r.launchClass === "stage2" && owned.length > 0 && !appProblem && !current.problems.length && r.cleanup?.appClean === true && stopped.every(x => !x.tainted);
694
+ return { clean, ...(!clean ? { problem: appProblem || "detached/native cleanup is unproven; quarantine retained" } : {}) };
695
+ });
696
+ if (holds("overlays"))
697
+ reapOverlays(runId, { ownerAlive: overlayOwnerAlive, stop: (r) => {
698
+ const n = getNode(r.nodeId);
699
+ const app = n ? stopOrphan(n) : undefined;
700
+ const appProblem = app?.note ?? "";
701
+ const current = executorRecords();
702
+ // Deadline enforcement cannot defer to a still-live but stalled worker. Only this overlay's
703
+ // recorded turn is stopped; no later turn can start before this record is released.
704
+ const owned = current.records.filter(x => x.record.nodeId === r.nodeId && x.record.turnId === (r.destinationTurn ?? r.originTurn));
705
+ const executorProblem = stoppedNote(owned.map(rec => app?.outcome === "refused" ? quarantineRecordedExecutor(rec, app.quarantine) : stopRecordedExecutorNow(rec, appProblem || undefined)));
706
+ const nativeUncertain = r.state === "tainted" && r.consumedAt === undefined && r.request.originConfinement === "native" && !owned.length && r.cleanup?.clean === false;
707
+ const clean = !appProblem && !current.problems.length && !nativeUncertain && !nodeHasLiveExecutor(r.nodeId);
708
+ return { clean, ...(!clean ? { problem: appProblem + executorProblem || "executor cleanup could not be confirmed" } : {}) };
709
+ } });
710
+ // Only items that are queued or running and have (or had) a worker can have lost it.
711
+ const active = stmt("SELECT * FROM nodes WHERE run_id = ? AND status IN ('queued', 'running') AND worker_pid IS NOT NULL ORDER BY created_at, id").all(runId);
712
+ for (const n of active) {
713
+ if (!workerLive(n)) {
714
+ // The app server first, so that it cannot reconnect to whatever later holds its executor's port; then the executor (stage 2).
715
+ // An app server that may still run (unconfirmed) keeps the executor's lease quarantined, as
716
+ // on the reservation and overlay paths, though the executor itself is still stopped.
717
+ const app = stopOrphan(n);
718
+ const note = app.note + stopNodeExecutorsNow(n.id, app.quarantine, app.outcome === "unconfirmed" ? `untraceable app-server cleanup:${app.note}` : undefined);
719
+ // The node lost and its turns over in one transaction (the processes stopped above, outside
720
+ // it), so that no reader, another server recording events say, finds the one without the
721
+ // other, as a turn's end is recorded with its session's (outcome.ts finishTurn).
722
+ tx(() => {
723
+ // Conditional on the worker it was judged by, so a worker claimed in the meantime is not
724
+ // written off, and a reap by another process that came first leaves this one nothing to write.
725
+ const lost = db().prepare("UPDATE nodes SET status = 'lost', ended_at = ?, worker_pid = NULL, worker_start = NULL, error = ? WHERE id = ? AND worker_pid IS ? AND status IN ('queued', 'running')")
726
+ .run(now(), `worker process died.${note}`, n.id, n.worker_pid);
727
+ // Its turn is over too. A relay server left behind by that turn must find it so, or it would keep the turn's authority.
728
+ if (Number(lost.changes) === 1)
729
+ closeTurns(n.id, "failed", "worker process died");
730
+ });
731
+ }
732
+ }
733
+ // The write lock is taken only when there is something to write. What is found here is looked at
734
+ // again inside the transaction, which alone decides: a reap by another process in between finds
735
+ // the same, and whichever comes second writes nothing.
736
+ const expirable = stmt("SELECT 1 FROM requests WHERE run_id = ? AND status = 'pending' AND node_id IN (SELECT id FROM nodes WHERE run_id = ? AND status NOT IN ('queued', 'running')) LIMIT 1").get(runId, runId);
737
+ const deadSlot = () => stmt("SELECT pid FROM slots WHERE run_id = ?").all(runId).some((s) => !pidAlive(s.pid));
738
+ const deadProc = () => stmt("SELECT pid, start FROM relay_procs").all().some((p) => !sameProcess(p.pid, p.start));
739
+ if (!expirable && !deadSlot() && !deadProc())
740
+ return;
741
+ tx(() => {
742
+ // A request whose job is no longer running can never be answered usefully.
743
+ db().prepare("UPDATE requests SET status = 'expired', decided_at = ? WHERE run_id = ? AND status = 'pending' AND node_id IN (SELECT id FROM nodes WHERE run_id = ? AND status NOT IN ('queued', 'running'))").run(now(), runId, runId);
744
+ const slots = db().prepare("SELECT id, pid FROM slots WHERE run_id = ?").all(runId);
745
+ for (const s of slots)
746
+ if (!pidAlive(s.pid))
747
+ db().prepare("DELETE FROM slots WHERE id = ?").run(s.id);
748
+ for (const p of stmt("SELECT pid, start FROM relay_procs").all()) {
749
+ if (!sameProcess(p.pid, p.start))
750
+ db().prepare("DELETE FROM relay_procs WHERE pid = ? AND start = ?").run(p.pid, p.start);
751
+ }
752
+ });
753
+ }