owenloop 0.5.0 → 0.5.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 (229) hide show
  1. package/CHANGELOG.md +67 -0
  2. package/README.md +144 -35
  3. package/bin/owenloop.mjs +49 -1
  4. package/dist/packages/work/src/agent/brief.d.ts +29 -4
  5. package/dist/packages/work/src/agent/brief.js +49 -4
  6. package/dist/packages/work/src/agent/capability-model.d.ts +123 -0
  7. package/dist/packages/work/src/agent/capability-model.js +148 -0
  8. package/dist/packages/work/src/agent/loop.d.ts +56 -7
  9. package/dist/packages/work/src/agent/loop.js +166 -9
  10. package/dist/packages/work/src/bundle/cache.d.ts +7 -5
  11. package/dist/packages/work/src/bundle/cache.js +20 -6
  12. package/dist/packages/work/src/bundle/fetch.d.ts +7 -5
  13. package/dist/packages/work/src/bundle/fetch.js +27 -7
  14. package/dist/packages/work/src/bundle/types.d.ts +8 -4
  15. package/dist/packages/work/src/consumed-verifier.d.ts +45 -0
  16. package/dist/packages/work/src/consumed-verifier.js +205 -0
  17. package/dist/packages/work/src/exec/instructions.d.ts +99 -0
  18. package/dist/packages/work/src/exec/instructions.js +323 -0
  19. package/dist/packages/work/src/exec/loop.d.ts +29 -1
  20. package/dist/packages/work/src/exec/loop.js +313 -35
  21. package/dist/packages/work/src/exec/payload.d.ts +29 -0
  22. package/dist/packages/work/src/exec/payload.js +54 -0
  23. package/dist/packages/work/src/exec/receipt.d.ts +9 -6
  24. package/dist/packages/work/src/exec/receipt.js +12 -1
  25. package/dist/packages/work/src/exec/runner.d.ts +7 -1
  26. package/dist/packages/work/src/exec/runner.js +84 -3
  27. package/dist/packages/work/src/harness/child-env.js +7 -0
  28. package/dist/packages/work/src/harness/claude.d.ts +20 -8
  29. package/dist/packages/work/src/harness/claude.js +260 -58
  30. package/dist/packages/work/src/harness/codex.d.ts +5 -4
  31. package/dist/packages/work/src/harness/codex.js +169 -41
  32. package/dist/packages/work/src/harness/contract.d.ts +36 -11
  33. package/dist/packages/work/src/harness/fake.js +1 -0
  34. package/dist/packages/work/src/harness/jsonrpc-stdio.js +7 -0
  35. package/dist/packages/work/src/harness/permissions.d.ts +16 -3
  36. package/dist/packages/work/src/harness/permissions.js +102 -13
  37. package/dist/packages/work/src/harness/session-store.d.ts +30 -10
  38. package/dist/packages/work/src/harness/session-store.js +317 -89
  39. package/dist/packages/work/src/hold/mcp.d.ts +25 -5
  40. package/dist/packages/work/src/hold/mcp.js +134 -12
  41. package/dist/packages/work/src/hub/client.d.ts +8 -1
  42. package/dist/packages/work/src/hub/client.js +15 -1
  43. package/dist/packages/work/src/hub/types.d.ts +137 -33
  44. package/dist/packages/work/src/hub/types.js +8 -10
  45. package/dist/packages/work/src/mcp/server.js +1 -1
  46. package/dist/packages/work/src/owenloop-bin.d.ts +1 -0
  47. package/dist/packages/work/src/owenloop-bin.js +18 -0
  48. package/dist/packages/work/src/roles/agent-run.d.ts +12 -6
  49. package/dist/packages/work/src/roles/agent-run.js +115 -34
  50. package/dist/packages/work/src/roles/exec.d.ts +8 -0
  51. package/dist/packages/work/src/roles/exec.js +27 -2
  52. package/dist/packages/work/src/roles/hold.d.ts +6 -0
  53. package/dist/packages/work/src/roles/hold.js +83 -13
  54. package/dist/packages/work/src/roles/lint.d.ts +3 -4
  55. package/dist/packages/work/src/roles/lint.js +41 -7
  56. package/dist/packages/work/src/roles/settings.js +19 -2
  57. package/dist/packages/work/src/roles/shift.d.ts +1 -0
  58. package/dist/packages/work/src/roles/shift.js +36 -2
  59. package/dist/packages/work/src/settings/settings.d.ts +70 -1
  60. package/dist/packages/work/src/settings/settings.js +90 -4
  61. package/dist/packages/work/src/shift/logretention.d.ts +253 -0
  62. package/dist/packages/work/src/shift/logretention.js +407 -0
  63. package/dist/packages/work/src/shift/logsink.d.ts +14 -0
  64. package/dist/packages/work/src/shift/logsink.js +98 -0
  65. package/dist/packages/work/src/shift/loop.d.ts +32 -4
  66. package/dist/packages/work/src/shift/loop.js +687 -166
  67. package/dist/packages/work/src/shift/protocol.d.ts +128 -1
  68. package/dist/packages/work/src/shift/protocol.js +14 -0
  69. package/dist/packages/work/src/shift/runtime.d.ts +16 -0
  70. package/dist/packages/work/src/shift/runtime.js +291 -5
  71. package/dist/packages/work/src/shift/server.d.ts +13 -0
  72. package/dist/packages/work/src/shift/server.js +61 -36
  73. package/dist/packages/work/src/shift/spawn.d.ts +115 -19
  74. package/dist/packages/work/src/shift/spawn.js +234 -30
  75. package/dist/packages/work/src/shift/state.d.ts +76 -49
  76. package/dist/packages/work/src/shift/state.js +350 -103
  77. package/dist/packages/work/src/shift/truncate.d.ts +35 -0
  78. package/dist/packages/work/src/shift/truncate.js +73 -0
  79. package/dist/packages/work/src/submit-proof.d.ts +61 -0
  80. package/dist/packages/work/src/submit-proof.js +119 -0
  81. package/dist/packages/work/src/submit-value.d.ts +48 -0
  82. package/dist/packages/work/src/submit-value.js +118 -0
  83. package/dist/packages/work/src/usage.d.ts +1 -1
  84. package/dist/packages/work/src/usage.js +11 -0
  85. package/dist/src/add.d.ts +64 -259
  86. package/dist/src/add.js +81 -615
  87. package/dist/src/archive.d.ts +97 -0
  88. package/dist/src/archive.js +591 -0
  89. package/dist/src/bundle/index.d.ts +64 -0
  90. package/dist/src/bundle/index.js +508 -0
  91. package/dist/src/bundle/manifest.d.ts +50 -0
  92. package/dist/src/bundle/manifest.js +435 -0
  93. package/dist/src/bundle/runtime.d.ts +26 -0
  94. package/dist/src/bundle/runtime.js +64 -0
  95. package/dist/src/bundle/tar.d.ts +62 -0
  96. package/dist/src/bundle/tar.js +238 -0
  97. package/dist/src/bundle/types.d.ts +105 -0
  98. package/dist/src/bundle/types.js +21 -0
  99. package/dist/src/capabilities.d.ts +93 -0
  100. package/dist/src/capabilities.js +101 -0
  101. package/dist/src/cli.d.ts +90 -20
  102. package/dist/src/cli.js +2421 -374
  103. package/dist/src/credentials.d.ts +4 -3
  104. package/dist/src/credentials.js +21 -19
  105. package/dist/src/crypto/allowed-signers.d.ts +68 -0
  106. package/dist/src/crypto/allowed-signers.js +307 -0
  107. package/dist/src/crypto/canonical.d.ts +8 -0
  108. package/dist/src/crypto/canonical.js +92 -0
  109. package/dist/src/crypto/chain.d.ts +65 -0
  110. package/dist/src/crypto/chain.js +377 -0
  111. package/dist/src/crypto/dsse.d.ts +209 -0
  112. package/dist/src/crypto/dsse.js +282 -0
  113. package/dist/src/crypto/enrollment.d.ts +78 -0
  114. package/dist/src/crypto/enrollment.js +186 -0
  115. package/dist/src/crypto/index.d.ts +48 -0
  116. package/dist/src/crypto/index.js +44 -0
  117. package/dist/src/crypto/keys.d.ts +258 -0
  118. package/dist/src/crypto/keys.js +908 -0
  119. package/dist/src/crypto/org-root.d.ts +33 -0
  120. package/dist/src/crypto/org-root.js +78 -0
  121. package/dist/src/crypto/origin-rules.d.ts +56 -0
  122. package/dist/src/crypto/origin-rules.js +143 -0
  123. package/dist/src/crypto/policy-floor.d.ts +98 -0
  124. package/dist/src/crypto/policy-floor.js +353 -0
  125. package/dist/src/crypto/records.d.ts +319 -0
  126. package/dist/src/crypto/records.js +168 -0
  127. package/dist/src/crypto/scope.d.ts +49 -0
  128. package/dist/src/crypto/scope.js +83 -0
  129. package/dist/src/crypto/ssh.d.ts +171 -0
  130. package/dist/src/crypto/ssh.js +396 -0
  131. package/dist/src/crypto/submission.d.ts +33 -0
  132. package/dist/src/crypto/submission.js +47 -0
  133. package/dist/src/crypto/trust-roots.d.ts +29 -0
  134. package/dist/src/crypto/trust-roots.js +39 -0
  135. package/dist/src/crypto/verify-consumed.d.ts +67 -0
  136. package/dist/src/crypto/verify-consumed.js +259 -0
  137. package/dist/src/crypto/verify-origin.d.ts +50 -0
  138. package/dist/src/crypto/verify-origin.js +151 -0
  139. package/dist/src/crypto/verify-publication.d.ts +60 -0
  140. package/dist/src/crypto/verify-publication.js +150 -0
  141. package/dist/src/defs.d.ts +24 -1
  142. package/dist/src/defs.js +335 -27
  143. package/dist/src/engine.d.ts +211 -6
  144. package/dist/src/engine.js +459 -59
  145. package/dist/src/factory.d.ts +16 -0
  146. package/dist/src/factory.js +16 -4
  147. package/dist/src/global-config.d.ts +59 -0
  148. package/dist/src/global-config.js +84 -0
  149. package/dist/src/hub.d.ts +102 -32
  150. package/dist/src/hub.js +147 -58
  151. package/dist/src/index.d.ts +19 -2
  152. package/dist/src/index.js +23 -2
  153. package/dist/src/install.d.ts +538 -0
  154. package/dist/src/install.js +1981 -0
  155. package/dist/src/lock.d.ts +15 -57
  156. package/dist/src/lock.js +251 -143
  157. package/dist/src/mcp/serve.d.ts +46 -22
  158. package/dist/src/mcp/serve.js +174 -44
  159. package/dist/src/mcp/server.js +12 -1
  160. package/dist/src/model.d.ts +51 -0
  161. package/dist/src/model.js +157 -1
  162. package/dist/src/order-resolver.d.ts +184 -0
  163. package/dist/src/order-resolver.js +252 -0
  164. package/dist/src/package-version.d.ts +10 -0
  165. package/dist/src/package-version.js +42 -0
  166. package/dist/src/paths.d.ts +14 -1
  167. package/dist/src/paths.js +18 -0
  168. package/dist/src/schemas/enrollment-grant.v1.schema.json +90 -0
  169. package/dist/src/schemas/index.d.ts +1433 -0
  170. package/dist/src/schemas/index.js +31 -0
  171. package/dist/src/schemas/order.v1.schema.json +120 -0
  172. package/dist/src/schemas/origin.v1.schema.json +68 -0
  173. package/dist/src/schemas/policy-floor.v1.schema.json +29 -0
  174. package/dist/src/schemas/publication.v1.schema.json +31 -0
  175. package/dist/src/schemas/revocation.v1.schema.json +39 -0
  176. package/dist/src/schemas/submission.v1.schema.json +61 -0
  177. package/dist/src/store/def-source.d.ts +52 -0
  178. package/dist/src/store/def-source.js +335 -0
  179. package/dist/src/store/index-file.d.ts +69 -0
  180. package/dist/src/store/index-file.js +151 -0
  181. package/dist/src/store/index.d.ts +27 -0
  182. package/dist/src/store/index.js +22 -0
  183. package/dist/src/store/ingestor.d.ts +43 -0
  184. package/dist/src/store/ingestor.js +211 -0
  185. package/dist/src/store/install.d.ts +228 -0
  186. package/dist/src/store/install.js +555 -0
  187. package/dist/src/store/instruction-source.d.ts +49 -0
  188. package/dist/src/store/instruction-source.js +298 -0
  189. package/dist/src/store/origin-evidence.d.ts +21 -0
  190. package/dist/src/store/origin-evidence.js +66 -0
  191. package/dist/src/store/pre-commit-verifier.d.ts +68 -0
  192. package/dist/src/store/pre-commit-verifier.js +418 -0
  193. package/dist/src/store/resolve.d.ts +138 -0
  194. package/dist/src/store/resolve.js +363 -0
  195. package/dist/src/store/types.d.ts +288 -0
  196. package/dist/src/store/types.js +356 -0
  197. package/dist/src/store.d.ts +33 -1
  198. package/dist/src/store.js +57 -4
  199. package/dist/src/types.d.ts +146 -12
  200. package/dist/src/untar.d.ts +8 -23
  201. package/dist/src/untar.js +10 -136
  202. package/docs/agent-runner.md +86 -0
  203. package/docs/authoring.md +64 -6
  204. package/docs/bundles.md +350 -0
  205. package/docs/cli.md +1298 -106
  206. package/docs/crypto.md +832 -0
  207. package/docs/design.md +342 -20
  208. package/docs/embedding.md +132 -25
  209. package/docs/shift-logs.md +642 -0
  210. package/docs/wire-contracts.md +395 -0
  211. package/package.json +6 -1
  212. package/plugins/claude-code/.claude-plugin/marketplace.json +14 -0
  213. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +8 -0
  214. package/plugins/claude-code/plugin/.mcp.json +14 -0
  215. package/plugins/claude-code/plugin/hooks/hooks.json +26 -0
  216. package/plugins/claude-code/plugin/hooks/session-end.sh +40 -0
  217. package/plugins/claude-code/plugin/hooks/session-start.sh +52 -0
  218. package/plugins/claude-code/plugin/skills/author/SKILL.md +181 -0
  219. package/plugins/claude-code/plugin/skills/conduct/SKILL.md +106 -0
  220. package/plugins/claude-code/plugin/skills/shift/SKILL.md +105 -0
  221. package/plugins/codex/.agents/plugins/marketplace.json +21 -0
  222. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +7 -0
  223. package/plugins/codex/plugins/owenloop/.mcp.json +20 -0
  224. package/plugins/codex/plugins/owenloop/hooks/hooks.json +26 -0
  225. package/plugins/codex/plugins/owenloop/hooks/session-end.sh +40 -0
  226. package/plugins/codex/plugins/owenloop/hooks/session-start.sh +52 -0
  227. package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +181 -0
  228. package/plugins/codex/plugins/owenloop/skills/conduct/SKILL.md +106 -0
  229. package/plugins/codex/plugins/owenloop/skills/shift/SKILL.md +105 -0
@@ -1,113 +1,341 @@
1
1
  /**
2
- * In-flight tracking for detached exec children (plan decision 7).
2
+ * Durable Shift dispatch state.
3
3
  *
4
- * The shift spawns `owenloop work exec <run>` DETACHED — the child survives a shift
5
- * restart (kernel reparenting, SP5-verified). So the shift cannot trust its own
6
- * memory to know what is in flight across a restart; it reconstructs that from
7
- * durable local records instead. A state dir holds one JSON record per spawned
8
- * child — `{ workflow, run, pid, spawnedAt, def?, hash?, step? }` — and on every
9
- * sweep (and startup) we scan the records, probe each pid with `kill(pid, 0)`,
10
- * count the live ones as in-flight, and reap the dead ones.
11
- *
12
- * The design docs disdain PID files for broker/discovery plumbing of
13
- * harness-managed processes; these are shift-spawned children, so local
14
- * bookkeeping is the legitimate mechanism, not that anti-pattern. Metering off
15
- * this count is an EFFICIENCY mechanism only — engine race-safety plus the
16
- * pickup/lease TTLs are the correctness backstop — so a rare pid-reuse miscount
17
- * is acceptable and never a bug to chase.
18
- *
19
- * Every fs op is FAIL-OPEN: a broken state dir degrades metering (the shift may
20
- * over- or under-count in flight), it never kills the loop.
4
+ * Every dispatch is reserved before spawn. A reservation counts against capacity
5
+ * and same-run deduplication, and carries a start-gate token. The child waits on
6
+ * that gate before entering the CLI. The Shift replaces the reservation with a
7
+ * PID-bearing child record, then opens the gate. A crash before PID persistence
8
+ * leaves a gated child that exits when the abandoned reservation is reaped; a
9
+ * crash after PID persistence leaves enough state for restart reconciliation to
10
+ * open the gate safely.
21
11
  */
22
- import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
23
- import { join } from 'node:path';
12
+ import { closeSync, existsSync, fsyncSync, ftruncateSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync, } from 'node:fs';
13
+ import { randomBytes } from 'node:crypto';
14
+ import { basename, join, resolve } from 'node:path';
15
+ export const DEFAULT_RESERVATION_MAX_AGE_MS = 2 * 60_000;
24
16
  /**
25
- * Resolve the state dir: `override` → `$XDG_STATE_HOME/owenloop/exec` →
26
- * `$HOME/.local/state/owenloop/exec`. Throws when none is available (same
27
- * stance as the cache/settings resolvers — never guess a home dir). Tests pass
28
- * an explicit `override` pointing at a temp dir.
17
+ * Where this shift's `<run>.json` in-flight records live.
18
+ *
19
+ * ALWAYS ABSOLUTE. `--state-dir ./state` is a legal thing for an operator to
20
+ * type, and while only this process joined paths onto it the relative spelling
21
+ * was harmless. It stopped being harmless when the log-owner registry
22
+ * (`logretention.ts`) began WRITING this string into a file that a DIFFERENT
23
+ * shift process, with a DIFFERENT working directory, reads back and probes for
24
+ * `<run>.json`: `./state` resolved against the wrong cwd finds no record, the
25
+ * in-flight gate concludes the run finished, and a live worker's log is
26
+ * unlinked out from under it. `resolve()` here is what makes the writer, the
27
+ * reader and the probe agree on ONE spelling, and it is also what keeps
28
+ * `ownerClaimName`'s hash stable so one shift writes one claim file rather than
29
+ * one per cwd it was ever started from.
29
30
  */
30
31
  export function resolveStateDir(env, override) {
31
32
  if (override !== undefined && override.trim() !== '')
32
- return override;
33
+ return resolve(override);
33
34
  const xdg = env['XDG_STATE_HOME'];
34
35
  if (xdg !== undefined && xdg.trim() !== '')
35
- return join(xdg, 'owenloop', 'exec');
36
+ return resolve(xdg, 'owenloop', 'exec');
36
37
  const home = env['HOME'];
37
38
  if (home !== undefined && home.trim() !== '')
38
- return join(home, '.local', 'state', 'owenloop', 'exec');
39
+ return resolve(home, '.local', 'state', 'owenloop', 'exec');
39
40
  throw new Error('cannot locate a state directory: set OWENLOOP_STATE_DIR, XDG_STATE_HOME, or HOME');
40
41
  }
41
- /** Map a run id onto a safe record filename (hub run ids are already safe; this
42
- * is defense in depth against a `/`, `\`, or `..` sneaking in). */
42
+ /**
43
+ * The run id as it appears in a filename, with every character a path could
44
+ * misread replaced.
45
+ *
46
+ * EXPORTED because the worker log `<run>.log` correlates to the in-flight
47
+ * record `<run>.json` BY BASENAME. Two sanitizers would be two basenames, and
48
+ * the correlation an operator and a future uploader both rely on would silently
49
+ * stop holding for any run id containing an unusual character.
50
+ */
51
+ export function safeRun(run) {
52
+ return run.replace(/[^A-Za-z0-9_.-]/g, '_');
53
+ }
43
54
  function recordFile(stateDir, run) {
44
- const safe = run.replace(/[^A-Za-z0-9_.-]/g, '_');
45
- return join(stateDir, `${safe}.json`);
55
+ return join(stateDir, `${safeRun(run)}.json`);
56
+ }
57
+ function gateFile(stateDir, token) {
58
+ if (!/^[a-f0-9]{32}$/u.test(token))
59
+ throw new Error('invalid child start-gate token');
60
+ return join(stateDir, `.${token}.gate`);
46
61
  }
47
- /** Persist a child record (atomic temp+rename). Fail-open. */
48
- export function writeChildRecord(stateDir, rec) {
62
+ function syncDirectory(dir) {
63
+ if (process.platform === 'win32')
64
+ return;
65
+ const fd = openSync(dir, 'r');
49
66
  try {
50
- mkdirSync(stateDir, { recursive: true });
51
- const file = recordFile(stateDir, rec.run);
52
- const tmp = join(stateDir, `.${Math.random().toString(36).slice(2)}-${process.pid}-${Date.now()}.tmp`);
53
- writeFileSync(tmp, JSON.stringify(rec));
67
+ fsyncSync(fd);
68
+ }
69
+ finally {
70
+ closeSync(fd);
71
+ }
72
+ }
73
+ function durableExclusiveWrite(path, value) {
74
+ const fd = openSync(path, 'wx');
75
+ let failure;
76
+ try {
77
+ writeFileSync(fd, value);
78
+ fsyncSync(fd);
79
+ }
80
+ catch (error) {
81
+ failure = error;
82
+ }
83
+ try {
84
+ closeSync(fd);
85
+ }
86
+ catch (error) {
87
+ if (failure === undefined)
88
+ failure = error;
89
+ }
90
+ if (failure !== undefined) {
54
91
  try {
55
- renameSync(tmp, file);
92
+ rmSync(path, { force: true });
56
93
  }
57
- catch (err) {
58
- try {
59
- unlinkSync(tmp);
60
- }
61
- catch {
62
- // best-effort cleanup
63
- }
64
- throw err;
94
+ catch {
95
+ // Preserve the original write or close failure.
65
96
  }
97
+ throw failure;
66
98
  }
67
- catch {
68
- // fail-open: a lost record degrades metering, never kills the loop.
69
- }
99
+ syncDirectory(join(path, '..'));
70
100
  }
71
- /** Read every child record in the state dir. Corrupt files are skipped, a
72
- * missing dir reads as empty. Fail-open. */
73
- export function readChildRecords(stateDir) {
74
- let names;
101
+ function durableRemove(path) {
102
+ rmSync(path, { force: true });
103
+ syncDirectory(join(path, '..'));
104
+ }
105
+ function atomicWrite(path, value) {
106
+ const dir = join(path, '..');
107
+ mkdirSync(dir, { recursive: true });
108
+ const tmp = join(dir, `.${randomBytes(8).toString('hex')}-${process.pid}-${Date.now()}.tmp`);
109
+ durableExclusiveWrite(tmp, value);
75
110
  try {
76
- names = readdirSync(stateDir).filter((f) => f.endsWith('.json'));
111
+ renameSync(tmp, path);
112
+ syncDirectory(dir);
77
113
  }
78
- catch {
79
- return [];
114
+ catch (error) {
115
+ try {
116
+ unlinkSync(tmp);
117
+ }
118
+ catch {
119
+ // Preserve the original write failure.
120
+ }
121
+ throw error;
122
+ }
123
+ }
124
+ function writeStateRecord(stateDir, record) {
125
+ atomicWrite(recordFile(stateDir, record.run), JSON.stringify(record));
126
+ }
127
+ /** Persist a child record atomically. State persistence is correctness-sensitive and throws on failure. */
128
+ export function writeChildRecord(stateDir, record) {
129
+ writeStateRecord(stateDir, record);
130
+ }
131
+ /** Create the durable capacity reservation and closed start gate before spawn. */
132
+ export function reserveChild(stateDir, request) {
133
+ ensureStateDir(stateDir);
134
+ const token = randomBytes(16).toString('hex');
135
+ const gatePath = gateFile(stateDir, token);
136
+ const reservation = {
137
+ recordType: 'reservation',
138
+ workflow: request.workflow,
139
+ run: request.run,
140
+ reservedAt: request.reservedAt,
141
+ token,
142
+ childKind: request.childKind,
143
+ ...(request.step !== undefined ? { step: request.step } : {}),
144
+ };
145
+ durableExclusiveWrite(gatePath, 'wait\n');
146
+ try {
147
+ // Exclusive create is the same-run reservation point. A stale, live, or even
148
+ // corrupt existing record blocks dispatch rather than being overwritten.
149
+ durableExclusiveWrite(recordFile(stateDir, reservation.run), JSON.stringify(reservation));
80
150
  }
81
- const records = [];
82
- for (const name of names) {
151
+ catch (error) {
83
152
  try {
84
- const rec = JSON.parse(readFileSync(join(stateDir, name), 'utf8'));
85
- if (rec && typeof rec.run === 'string' && typeof rec.pid === 'number' && typeof rec.workflow === 'string') {
86
- records.push(rec);
87
- }
153
+ durableRemove(gatePath);
88
154
  }
89
155
  catch {
90
- // skip corrupt record
156
+ // Preserve the reservation write failure.
91
157
  }
158
+ throw error;
92
159
  }
93
- return records;
160
+ return { reservation, gatePath };
94
161
  }
95
- /** Delete a child record by run id. Fail-open. */
96
- export function removeChildRecord(stateDir, run) {
162
+ function isReservation(record) {
163
+ return record.recordType === 'reservation';
164
+ }
165
+ export class ShiftStateRecordError extends Error {
166
+ path;
167
+ constructor(path, detail) {
168
+ super(`cannot reconcile Shift state record '${path}': ${detail}; ` +
169
+ 'dispatch is disabled until the record is repaired or removed after verifying that no child still owns the slot');
170
+ this.name = 'ShiftStateRecordError';
171
+ this.path = path;
172
+ }
173
+ }
174
+ function readOneStateRecord(path) {
175
+ let raw;
97
176
  try {
98
- rmSync(recordFile(stateDir, run), { force: true });
177
+ raw = readFileSync(path, 'utf8');
178
+ }
179
+ catch (error) {
180
+ if (error.code === 'ENOENT')
181
+ return undefined;
182
+ const code = error.code;
183
+ throw new ShiftStateRecordError(path, `the canonical record is unreadable${code === undefined ? '' : ` (${code})`}`);
184
+ }
185
+ let parsed;
186
+ try {
187
+ parsed = JSON.parse(raw);
99
188
  }
100
189
  catch {
101
- // best-effort
190
+ throw new ShiftStateRecordError(path, 'the canonical record is truncated or is not valid JSON');
191
+ }
192
+ if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
193
+ throw new ShiftStateRecordError(path, 'the canonical record is not a JSON object');
194
+ }
195
+ if (typeof parsed['workflow'] !== 'string' || parsed['workflow'] === '' ||
196
+ typeof parsed['run'] !== 'string' || parsed['run'] === '') {
197
+ throw new ShiftStateRecordError(path, 'the canonical record is missing workflow or run identity');
198
+ }
199
+ if (basename(path) !== `${safeRun(parsed['run'])}.json`) {
200
+ throw new ShiftStateRecordError(path, 'the canonical record pathname does not match its run identity');
201
+ }
202
+ if (parsed['recordType'] === 'reservation') {
203
+ if (typeof parsed['reservedAt'] !== 'number' ||
204
+ !Number.isInteger(parsed['reservedAt']) ||
205
+ parsed['reservedAt'] < 0 ||
206
+ typeof parsed['token'] !== 'string' ||
207
+ !/^[a-f0-9]{32}$/u.test(parsed['token']) ||
208
+ (parsed['childKind'] !== 'exec' && parsed['childKind'] !== 'agent-run') ||
209
+ (parsed['step'] !== undefined && typeof parsed['step'] !== 'string')) {
210
+ throw new ShiftStateRecordError(path, 'the canonical reservation fields are malformed');
211
+ }
212
+ return parsed;
213
+ }
214
+ if (parsed['recordType'] !== undefined ||
215
+ typeof parsed['pid'] !== 'number' ||
216
+ !Number.isInteger(parsed['pid']) ||
217
+ parsed['pid'] <= 0 ||
218
+ typeof parsed['spawnedAt'] !== 'number' ||
219
+ !Number.isInteger(parsed['spawnedAt']) ||
220
+ parsed['spawnedAt'] < 0 ||
221
+ (parsed['kind'] !== undefined && parsed['kind'] !== 'exec' && parsed['kind'] !== 'agent-run') ||
222
+ (parsed['def'] !== undefined && typeof parsed['def'] !== 'string') ||
223
+ (parsed['hash'] !== undefined && typeof parsed['hash'] !== 'string') ||
224
+ (parsed['step'] !== undefined && typeof parsed['step'] !== 'string') ||
225
+ (parsed['gateToken'] !== undefined && (typeof parsed['gateToken'] !== 'string' ||
226
+ !/^[a-f0-9]{32}$/u.test(parsed['gateToken'])))) {
227
+ throw new ShiftStateRecordError(path, 'the canonical child fields are malformed');
228
+ }
229
+ return parsed;
230
+ }
231
+ function readStateRecords(stateDir) {
232
+ let names;
233
+ try {
234
+ names = readdirSync(stateDir)
235
+ .filter((name) => name.endsWith('.json') && name !== '.dispatch.lock.owner.json')
236
+ .sort();
237
+ }
238
+ catch (error) {
239
+ if (error.code === 'ENOENT')
240
+ return [];
241
+ throw error;
242
+ }
243
+ return names
244
+ .map((name) => readOneStateRecord(join(stateDir, name)))
245
+ .filter((record) => record !== undefined);
246
+ }
247
+ /** Read only PID-bearing records for status and compatibility callers. */
248
+ export function readChildRecords(stateDir) {
249
+ return readStateRecords(stateDir).filter((record) => !(isReservation(record)));
250
+ }
251
+ export function readChildReservations(stateDir) {
252
+ return readStateRecords(stateDir).filter((record) => isReservation(record));
253
+ }
254
+ /** Replace the matching reservation with a PID-bearing record before work starts. */
255
+ export function finalizeChildReservation(stateDir, reservation, child) {
256
+ const current = readOneStateRecord(recordFile(stateDir, reservation.run));
257
+ if (current === undefined ||
258
+ !isReservation(current) ||
259
+ current.token !== reservation.token) {
260
+ throw new Error(`child reservation for ${reservation.workflow}/${reservation.run} is missing or was replaced`);
261
+ }
262
+ const record = {
263
+ workflow: reservation.workflow,
264
+ run: reservation.run,
265
+ ...child,
266
+ gateToken: reservation.token,
267
+ };
268
+ writeStateRecord(stateDir, record);
269
+ return record;
270
+ }
271
+ function signalGate(path, signal, allowMissing) {
272
+ let fd;
273
+ try {
274
+ fd = openSync(path, 'r+');
275
+ }
276
+ catch (error) {
277
+ if (allowMissing && error.code === 'ENOENT')
278
+ return false;
279
+ throw error;
280
+ }
281
+ try {
282
+ ftruncateSync(fd, 0);
283
+ writeFileSync(fd, `${signal}\n`);
284
+ fsyncSync(fd);
285
+ }
286
+ finally {
287
+ closeSync(fd);
288
+ }
289
+ return true;
290
+ }
291
+ /** Open a child's gate only after the PID-bearing record is durable. */
292
+ export function startReservedChild(stateDir, record) {
293
+ if (record.gateToken === undefined)
294
+ return;
295
+ signalGate(gateFile(stateDir, record.gateToken), 'start', false);
296
+ }
297
+ /** Cancel a gated child and remove the matching reservation/record. */
298
+ export function cancelReservedChild(stateDir, reservation) {
299
+ const path = gateFile(stateDir, reservation.token);
300
+ try {
301
+ signalGate(path, 'cancel', true);
302
+ }
303
+ finally {
304
+ durableRemove(path);
305
+ const current = readOneStateRecord(recordFile(stateDir, reservation.run));
306
+ const matchesReservation = current !== undefined &&
307
+ isReservation(current) &&
308
+ current.token === reservation.token;
309
+ const matchesFinalized = current !== undefined &&
310
+ !isReservation(current) &&
311
+ current.gateToken === reservation.token;
312
+ if (matchesReservation || matchesFinalized)
313
+ durableRemove(recordFile(stateDir, reservation.run));
102
314
  }
103
315
  }
104
316
  /**
105
- * Default liveness probe: `process.kill(pid, 0)` sends no signal, only checks
106
- * existence/permissions. `ESRCH` ⇒ the process is gone (dead). `EPERM` ⇒ it
107
- * exists but is owned by another user (count as alive — pid reuse aside, a live
108
- * foreign process at that pid is not ours to reap). Any other error ⇒ alive
109
- * (conservative: don't reap on an ambiguous signal).
317
+ * Delete one run's in-flight state. A still-gated reservation or finalized child
318
+ * is cancelled first so an external run-ended signal cannot leave a worker gate
319
+ * behind that later opens without a capacity record.
110
320
  */
321
+ export function removeChildRecord(stateDir, run) {
322
+ const path = recordFile(stateDir, run);
323
+ const current = readOneStateRecord(path);
324
+ if (current !== undefined && isReservation(current)) {
325
+ cancelReservedChild(stateDir, current);
326
+ return;
327
+ }
328
+ if (current?.gateToken !== undefined) {
329
+ const gatePath = gateFile(stateDir, current.gateToken);
330
+ try {
331
+ signalGate(gatePath, 'cancel', true);
332
+ }
333
+ finally {
334
+ durableRemove(gatePath);
335
+ }
336
+ }
337
+ durableRemove(path);
338
+ }
111
339
  export const defaultIsAlive = (pid) => {
112
340
  if (!Number.isInteger(pid) || pid <= 0)
113
341
  return false;
@@ -115,48 +343,67 @@ export const defaultIsAlive = (pid) => {
115
343
  process.kill(pid, 0);
116
344
  return true;
117
345
  }
118
- catch (err) {
119
- return err.code !== 'ESRCH';
346
+ catch (error) {
347
+ return error.code !== 'ESRCH';
120
348
  }
121
349
  };
122
350
  /**
123
- * Scan the state dir, decide each record's liveness, delete the dead ones, and
124
- * return the live/reaped split. Deduped by run id (last record for a run wins)
125
- * so a stray double-write can never double-count capacity.
126
- *
127
- * Liveness is UNIFORM: every record names a real local child, so every record
128
- * is live exactly while `kill(pid, 0)` says its pid is.
129
- *
130
- * Back-compat: the second positional arg still accepts a bare `Liveness`
131
- * (pre-split callers passed `reconcileInFlight(dir, isAlive)`).
351
+ * Reconcile live children and durable reservations. Fresh reservations count as
352
+ * occupied capacity. An expired reservation is cancelled before its record is
353
+ * removed, so a child that was spawned but never finalized cannot begin work.
132
354
  */
133
355
  export function reconcileInFlight(stateDir, arg) {
134
- const opts = typeof arg === 'function' ? { isAlive: arg } : (arg ?? {});
135
- const isAlive = opts.isAlive ?? defaultIsAlive;
356
+ const options = typeof arg === 'function' ? { isAlive: arg } : (arg ?? {});
357
+ const isAlive = options.isAlive ?? defaultIsAlive;
358
+ const now = options.now ?? Date.now();
359
+ const maxAge = options.reservationMaxAgeMs ?? DEFAULT_RESERVATION_MAX_AGE_MS;
136
360
  const byRun = new Map();
137
- for (const rec of readChildRecords(stateDir))
138
- byRun.set(rec.run, rec);
361
+ for (const record of readStateRecords(stateDir))
362
+ byRun.set(record.run, record);
139
363
  const live = [];
364
+ const reserved = [];
140
365
  const reaped = [];
141
- for (const rec of byRun.values()) {
142
- const alive = isAlive(rec.pid);
143
- if (alive) {
144
- live.push(rec);
366
+ const abandoned = [];
367
+ for (const record of byRun.values()) {
368
+ if (isReservation(record)) {
369
+ // The worker removes its gate when its monotonic wait expires. A missing
370
+ // gate therefore proves that this reservation cannot start work, even if
371
+ // wall-clock rollback makes its persisted age look fresh.
372
+ const gateExists = existsSync(gateFile(stateDir, record.token));
373
+ // A persisted wall-clock timestamp from the future cannot be aged safely
374
+ // after a clock rollback. Cancel the reservation instead of letting a
375
+ // negative elapsed interval occupy capacity indefinitely.
376
+ if (gateExists && record.reservedAt <= now && now - record.reservedAt < maxAge) {
377
+ reserved.push(record);
378
+ continue;
379
+ }
380
+ cancelReservedChild(stateDir, record);
381
+ abandoned.push(record);
382
+ continue;
383
+ }
384
+ if (!isAlive(record.pid)) {
385
+ removeChildRecord(stateDir, record.run);
386
+ reaped.push(record);
387
+ continue;
388
+ }
389
+ if (record.gateToken !== undefined) {
390
+ // A restart after PID persistence but before the parent opened the gate can
391
+ // safely finish the handoff: the durable PID record is the prerequisite.
392
+ signalGate(gateFile(stateDir, record.gateToken), 'start', true);
393
+ const settled = { ...record };
394
+ delete settled.gateToken;
395
+ writeStateRecord(stateDir, settled);
396
+ live.push(settled);
145
397
  }
146
398
  else {
147
- removeChildRecord(stateDir, rec.run);
148
- reaped.push(rec);
399
+ live.push(record);
149
400
  }
150
401
  }
151
- return { live, reaped };
402
+ return { live, reserved, reaped, abandoned };
152
403
  }
153
- /** Ensure the state dir exists so the first read doesn't churn. Fail-open. */
404
+ /** Ensure the state directory exists and is readable. Failure is fatal to dispatch safety. */
154
405
  export function ensureStateDir(stateDir) {
155
- try {
156
- if (!existsSync(stateDir))
157
- mkdirSync(stateDir, { recursive: true });
158
- }
159
- catch {
160
- // fail-open
161
- }
406
+ if (!existsSync(stateDir))
407
+ mkdirSync(stateDir, { recursive: true });
408
+ readdirSync(stateDir);
162
409
  }
@@ -0,0 +1,35 @@
1
+ /**
2
+ * Byte-bounding one `ShiftEvent`, shared by the two consumers that must bound it.
3
+ *
4
+ * There is exactly ONE line-size rule, and both consumers apply it:
5
+ * - the socket daemon (`server.ts`) measures a whole response envelope, and
6
+ * - the on-disk JSON Lines sink (`logsink.ts`) measures one serialized line,
7
+ *
8
+ * so the ceiling in the file matches the ceiling on the wire and a future
9
+ * uploader tailing the file never faces a line the socket would have refused.
10
+ * The two differ only in HOW bytes are counted, which is why `measure` is a
11
+ * parameter rather than a second copy of the algorithm.
12
+ *
13
+ * THE ENVELOPE IS NEVER TRUNCATED AWAY. `type`, `ts`, and `shiftId` are exempt:
14
+ * they are the fields that make a record self-describing, they are bounded by
15
+ * construction (a literal, an ISO-8601 timestamp, `shf_<uuid>`), and blanking
16
+ * them would leave a reader with a marked husk it cannot place in time or
17
+ * attribute to a process. `shift` — the operator-chosen name — is NOT exempt;
18
+ * it is unbounded input and is shortened like any other string field, and only
19
+ * when it is the largest one left.
20
+ */
21
+ import { type ShiftEvent } from './protocol.ts';
22
+ /** Shorten `value` to at most `maxBytes` UTF-8 bytes, marker included. */
23
+ export declare function truncateUtf8(value: string, maxBytes: number): string;
24
+ /**
25
+ * Render one event within `maxBytes`, as `measure` counts them.
26
+ *
27
+ * A single event can be larger than the ceiling. It is delivered once with its
28
+ * string fields progressively halved — largest first — and an explicit
29
+ * `RESPONSE_TRUNCATION_MARKER`, rather than blocking every later event forever.
30
+ *
31
+ * `measure` receives the CANDIDATE event and returns the byte length the caller
32
+ * cares about: the socket adds its response envelope, the file sink adds the
33
+ * trailing newline.
34
+ */
35
+ export declare function truncateEventToBytes(event: ShiftEvent, maxBytes: number, measure: (candidate: ShiftEvent) => number): ShiftEvent;
@@ -0,0 +1,73 @@
1
+ /**
2
+ * Byte-bounding one `ShiftEvent`, shared by the two consumers that must bound it.
3
+ *
4
+ * There is exactly ONE line-size rule, and both consumers apply it:
5
+ * - the socket daemon (`server.ts`) measures a whole response envelope, and
6
+ * - the on-disk JSON Lines sink (`logsink.ts`) measures one serialized line,
7
+ *
8
+ * so the ceiling in the file matches the ceiling on the wire and a future
9
+ * uploader tailing the file never faces a line the socket would have refused.
10
+ * The two differ only in HOW bytes are counted, which is why `measure` is a
11
+ * parameter rather than a second copy of the algorithm.
12
+ *
13
+ * THE ENVELOPE IS NEVER TRUNCATED AWAY. `type`, `ts`, and `shiftId` are exempt:
14
+ * they are the fields that make a record self-describing, they are bounded by
15
+ * construction (a literal, an ISO-8601 timestamp, `shf_<uuid>`), and blanking
16
+ * them would leave a reader with a marked husk it cannot place in time or
17
+ * attribute to a process. `shift` — the operator-chosen name — is NOT exempt;
18
+ * it is unbounded input and is shortened like any other string field, and only
19
+ * when it is the largest one left.
20
+ */
21
+ import { RESPONSE_TRUNCATION_MARKER } from "./protocol.js";
22
+ /** Fields whose value must survive truncation intact. See the module comment. */
23
+ const PROTECTED_KEYS = new Set(['type', 'ts', 'shiftId']);
24
+ /** Shorten `value` to at most `maxBytes` UTF-8 bytes, marker included. */
25
+ export function truncateUtf8(value, maxBytes) {
26
+ if (Buffer.byteLength(value, 'utf8') <= maxBytes)
27
+ return value;
28
+ const markerBytes = Buffer.byteLength(RESPONSE_TRUNCATION_MARKER, 'utf8');
29
+ if (maxBytes <= markerBytes)
30
+ return RESPONSE_TRUNCATION_MARKER;
31
+ let prefix = Buffer.from(value, 'utf8').subarray(0, maxBytes - markerBytes).toString('utf8');
32
+ while (Buffer.byteLength(prefix, 'utf8') > maxBytes - markerBytes)
33
+ prefix = prefix.slice(0, -1);
34
+ return `${prefix}${RESPONSE_TRUNCATION_MARKER}`;
35
+ }
36
+ /**
37
+ * Render one event within `maxBytes`, as `measure` counts them.
38
+ *
39
+ * A single event can be larger than the ceiling. It is delivered once with its
40
+ * string fields progressively halved — largest first — and an explicit
41
+ * `RESPONSE_TRUNCATION_MARKER`, rather than blocking every later event forever.
42
+ *
43
+ * `measure` receives the CANDIDATE event and returns the byte length the caller
44
+ * cares about: the socket adds its response envelope, the file sink adds the
45
+ * trailing newline.
46
+ */
47
+ export function truncateEventToBytes(event, maxBytes, measure) {
48
+ const candidate = { ...event };
49
+ const stringKeys = Object.keys(candidate).filter((key) => typeof candidate[key] === 'string' && !PROTECTED_KEYS.has(key));
50
+ const markerBytes = Buffer.byteLength(RESPONSE_TRUNCATION_MARKER, 'utf8');
51
+ while (measure(candidate) > maxBytes) {
52
+ const key = stringKeys
53
+ .filter((name) => candidate[name] !== RESPONSE_TRUNCATION_MARKER)
54
+ .sort((left, right) => Buffer.byteLength(String(candidate[right]), 'utf8') -
55
+ Buffer.byteLength(String(candidate[left]), 'utf8'))[0];
56
+ if (key === undefined)
57
+ break;
58
+ const value = String(candidate[key]);
59
+ const currentBytes = Buffer.byteLength(value, 'utf8');
60
+ const targetBytes = Math.max(markerBytes, Math.floor(currentBytes / 2));
61
+ const shortened = truncateUtf8(value, targetBytes);
62
+ candidate[key] = shortened === value ? RESPONSE_TRUNCATION_MARKER : shortened;
63
+ }
64
+ // Final backstop if a future event shape needs more reduction than the
65
+ // progressive shortening above provided. Non-string fields (and the protected
66
+ // envelope) are left alone, so a pathological case can still exceed the
67
+ // ceiling rather than lose the identity that makes the record readable.
68
+ if (measure(candidate) > maxBytes) {
69
+ for (const key of stringKeys)
70
+ candidate[key] = RESPONSE_TRUNCATION_MARKER;
71
+ }
72
+ return candidate;
73
+ }