owenloop 0.5.0 → 0.5.1

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 (211) hide show
  1. package/CHANGELOG.md +45 -0
  2. package/README.md +137 -35
  3. package/bin/owenloop.mjs +49 -1
  4. package/dist/packages/work/src/agent/brief.d.ts +8 -4
  5. package/dist/packages/work/src/agent/brief.js +7 -3
  6. package/dist/packages/work/src/agent/loop.d.ts +13 -7
  7. package/dist/packages/work/src/agent/loop.js +136 -9
  8. package/dist/packages/work/src/agent/model-policy.d.ts +49 -0
  9. package/dist/packages/work/src/agent/model-policy.js +138 -0
  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 +12 -1
  20. package/dist/packages/work/src/exec/loop.js +137 -20
  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 +74 -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 +27 -9
  38. package/dist/packages/work/src/harness/session-store.js +271 -67
  39. package/dist/packages/work/src/hold/mcp.d.ts +25 -5
  40. package/dist/packages/work/src/hold/mcp.js +126 -11
  41. package/dist/packages/work/src/hub/client.d.ts +2 -1
  42. package/dist/packages/work/src/hub/client.js +14 -1
  43. package/dist/packages/work/src/hub/types.d.ts +69 -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 +116 -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 +4 -0
  53. package/dist/packages/work/src/roles/hold.js +44 -5
  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 +5 -0
  57. package/dist/packages/work/src/roles/shift.d.ts +1 -0
  58. package/dist/packages/work/src/roles/shift.js +23 -1
  59. package/dist/packages/work/src/settings/settings.d.ts +17 -1
  60. package/dist/packages/work/src/settings/settings.js +39 -0
  61. package/dist/packages/work/src/shift/loop.d.ts +14 -3
  62. package/dist/packages/work/src/shift/loop.js +447 -164
  63. package/dist/packages/work/src/shift/protocol.d.ts +4 -0
  64. package/dist/packages/work/src/shift/runtime.d.ts +2 -0
  65. package/dist/packages/work/src/shift/runtime.js +66 -3
  66. package/dist/packages/work/src/shift/spawn.d.ts +41 -18
  67. package/dist/packages/work/src/shift/spawn.js +89 -31
  68. package/dist/packages/work/src/shift/state.d.ts +53 -51
  69. package/dist/packages/work/src/shift/state.js +325 -102
  70. package/dist/packages/work/src/submit-proof.d.ts +36 -0
  71. package/dist/packages/work/src/submit-proof.js +93 -0
  72. package/dist/src/add.d.ts +64 -259
  73. package/dist/src/add.js +81 -615
  74. package/dist/src/archive.d.ts +97 -0
  75. package/dist/src/archive.js +591 -0
  76. package/dist/src/bundle/index.d.ts +64 -0
  77. package/dist/src/bundle/index.js +508 -0
  78. package/dist/src/bundle/manifest.d.ts +50 -0
  79. package/dist/src/bundle/manifest.js +435 -0
  80. package/dist/src/bundle/runtime.d.ts +26 -0
  81. package/dist/src/bundle/runtime.js +64 -0
  82. package/dist/src/bundle/tar.d.ts +62 -0
  83. package/dist/src/bundle/tar.js +238 -0
  84. package/dist/src/bundle/types.d.ts +105 -0
  85. package/dist/src/bundle/types.js +21 -0
  86. package/dist/src/cli.d.ts +90 -20
  87. package/dist/src/cli.js +2407 -365
  88. package/dist/src/credentials.d.ts +4 -3
  89. package/dist/src/credentials.js +21 -19
  90. package/dist/src/crypto/allowed-signers.d.ts +68 -0
  91. package/dist/src/crypto/allowed-signers.js +307 -0
  92. package/dist/src/crypto/canonical.d.ts +8 -0
  93. package/dist/src/crypto/canonical.js +92 -0
  94. package/dist/src/crypto/chain.d.ts +65 -0
  95. package/dist/src/crypto/chain.js +377 -0
  96. package/dist/src/crypto/dsse.d.ts +209 -0
  97. package/dist/src/crypto/dsse.js +282 -0
  98. package/dist/src/crypto/enrollment.d.ts +78 -0
  99. package/dist/src/crypto/enrollment.js +186 -0
  100. package/dist/src/crypto/index.d.ts +48 -0
  101. package/dist/src/crypto/index.js +44 -0
  102. package/dist/src/crypto/keys.d.ts +258 -0
  103. package/dist/src/crypto/keys.js +908 -0
  104. package/dist/src/crypto/org-root.d.ts +33 -0
  105. package/dist/src/crypto/org-root.js +78 -0
  106. package/dist/src/crypto/origin-rules.d.ts +56 -0
  107. package/dist/src/crypto/origin-rules.js +143 -0
  108. package/dist/src/crypto/policy-floor.d.ts +98 -0
  109. package/dist/src/crypto/policy-floor.js +353 -0
  110. package/dist/src/crypto/records.d.ts +316 -0
  111. package/dist/src/crypto/records.js +157 -0
  112. package/dist/src/crypto/scope.d.ts +49 -0
  113. package/dist/src/crypto/scope.js +83 -0
  114. package/dist/src/crypto/ssh.d.ts +171 -0
  115. package/dist/src/crypto/ssh.js +396 -0
  116. package/dist/src/crypto/submission.d.ts +33 -0
  117. package/dist/src/crypto/submission.js +47 -0
  118. package/dist/src/crypto/trust-roots.d.ts +29 -0
  119. package/dist/src/crypto/trust-roots.js +39 -0
  120. package/dist/src/crypto/verify-consumed.d.ts +67 -0
  121. package/dist/src/crypto/verify-consumed.js +259 -0
  122. package/dist/src/crypto/verify-origin.d.ts +50 -0
  123. package/dist/src/crypto/verify-origin.js +151 -0
  124. package/dist/src/crypto/verify-publication.d.ts +60 -0
  125. package/dist/src/crypto/verify-publication.js +150 -0
  126. package/dist/src/defs.d.ts +24 -1
  127. package/dist/src/defs.js +145 -25
  128. package/dist/src/engine.d.ts +99 -3
  129. package/dist/src/engine.js +238 -34
  130. package/dist/src/factory.d.ts +16 -0
  131. package/dist/src/factory.js +16 -4
  132. package/dist/src/global-config.d.ts +59 -0
  133. package/dist/src/global-config.js +84 -0
  134. package/dist/src/hub.d.ts +75 -21
  135. package/dist/src/hub.js +123 -40
  136. package/dist/src/index.d.ts +17 -2
  137. package/dist/src/index.js +20 -2
  138. package/dist/src/install.d.ts +538 -0
  139. package/dist/src/install.js +1981 -0
  140. package/dist/src/lock.d.ts +15 -57
  141. package/dist/src/lock.js +251 -143
  142. package/dist/src/mcp/serve.d.ts +46 -22
  143. package/dist/src/mcp/serve.js +167 -44
  144. package/dist/src/mcp/server.js +12 -1
  145. package/dist/src/model.d.ts +15 -0
  146. package/dist/src/model.js +111 -1
  147. package/dist/src/order-resolver.d.ts +184 -0
  148. package/dist/src/order-resolver.js +252 -0
  149. package/dist/src/package-version.d.ts +10 -0
  150. package/dist/src/package-version.js +42 -0
  151. package/dist/src/paths.d.ts +14 -1
  152. package/dist/src/paths.js +18 -0
  153. package/dist/src/schemas/enrollment-grant.v1.schema.json +90 -0
  154. package/dist/src/schemas/index.d.ts +1416 -0
  155. package/dist/src/schemas/index.js +31 -0
  156. package/dist/src/schemas/order.v1.schema.json +106 -0
  157. package/dist/src/schemas/origin.v1.schema.json +68 -0
  158. package/dist/src/schemas/policy-floor.v1.schema.json +29 -0
  159. package/dist/src/schemas/publication.v1.schema.json +31 -0
  160. package/dist/src/schemas/revocation.v1.schema.json +39 -0
  161. package/dist/src/schemas/submission.v1.schema.json +61 -0
  162. package/dist/src/store/def-source.d.ts +52 -0
  163. package/dist/src/store/def-source.js +335 -0
  164. package/dist/src/store/index-file.d.ts +69 -0
  165. package/dist/src/store/index-file.js +151 -0
  166. package/dist/src/store/index.d.ts +27 -0
  167. package/dist/src/store/index.js +22 -0
  168. package/dist/src/store/ingestor.d.ts +43 -0
  169. package/dist/src/store/ingestor.js +211 -0
  170. package/dist/src/store/install.d.ts +228 -0
  171. package/dist/src/store/install.js +555 -0
  172. package/dist/src/store/instruction-source.d.ts +49 -0
  173. package/dist/src/store/instruction-source.js +298 -0
  174. package/dist/src/store/origin-evidence.d.ts +21 -0
  175. package/dist/src/store/origin-evidence.js +66 -0
  176. package/dist/src/store/pre-commit-verifier.d.ts +68 -0
  177. package/dist/src/store/pre-commit-verifier.js +418 -0
  178. package/dist/src/store/resolve.d.ts +138 -0
  179. package/dist/src/store/resolve.js +363 -0
  180. package/dist/src/store/types.d.ts +288 -0
  181. package/dist/src/store/types.js +356 -0
  182. package/dist/src/types.d.ts +45 -11
  183. package/dist/src/untar.d.ts +8 -23
  184. package/dist/src/untar.js +10 -136
  185. package/docs/agent-runner.md +86 -0
  186. package/docs/authoring.md +57 -6
  187. package/docs/bundles.md +250 -0
  188. package/docs/cli.md +1171 -97
  189. package/docs/crypto.md +816 -0
  190. package/docs/design.md +342 -20
  191. package/docs/embedding.md +132 -25
  192. package/docs/wire-contracts.md +380 -0
  193. package/package.json +6 -1
  194. package/plugins/claude-code/.claude-plugin/marketplace.json +14 -0
  195. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +8 -0
  196. package/plugins/claude-code/plugin/.mcp.json +14 -0
  197. package/plugins/claude-code/plugin/hooks/hooks.json +26 -0
  198. package/plugins/claude-code/plugin/hooks/session-end.sh +40 -0
  199. package/plugins/claude-code/plugin/hooks/session-start.sh +52 -0
  200. package/plugins/claude-code/plugin/skills/author/SKILL.md +181 -0
  201. package/plugins/claude-code/plugin/skills/conduct/SKILL.md +106 -0
  202. package/plugins/claude-code/plugin/skills/shift/SKILL.md +105 -0
  203. package/plugins/codex/.agents/plugins/marketplace.json +21 -0
  204. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +7 -0
  205. package/plugins/codex/plugins/owenloop/.mcp.json +20 -0
  206. package/plugins/codex/plugins/owenloop/hooks/hooks.json +26 -0
  207. package/plugins/codex/plugins/owenloop/hooks/session-end.sh +40 -0
  208. package/plugins/codex/plugins/owenloop/hooks/session-start.sh +52 -0
  209. package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +181 -0
  210. package/plugins/codex/plugins/owenloop/skills/conduct/SKILL.md +106 -0
  211. package/plugins/codex/plugins/owenloop/skills/shift/SKILL.md +105 -0
@@ -1,32 +1,18 @@
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.
21
- */
22
- import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
23
- import { join } from 'node:path';
24
- /**
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.
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.
29
11
  */
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 } from 'node:path';
15
+ export const DEFAULT_RESERVATION_MAX_AGE_MS = 2 * 60_000;
30
16
  export function resolveStateDir(env, override) {
31
17
  if (override !== undefined && override.trim() !== '')
32
18
  return override;
@@ -38,76 +24,294 @@ export function resolveStateDir(env, override) {
38
24
  return join(home, '.local', 'state', 'owenloop', 'exec');
39
25
  throw new Error('cannot locate a state directory: set OWENLOOP_STATE_DIR, XDG_STATE_HOME, or HOME');
40
26
  }
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). */
27
+ function safeRun(run) {
28
+ return run.replace(/[^A-Za-z0-9_.-]/g, '_');
29
+ }
43
30
  function recordFile(stateDir, run) {
44
- const safe = run.replace(/[^A-Za-z0-9_.-]/g, '_');
45
- return join(stateDir, `${safe}.json`);
31
+ return join(stateDir, `${safeRun(run)}.json`);
32
+ }
33
+ function gateFile(stateDir, token) {
34
+ if (!/^[a-f0-9]{32}$/u.test(token))
35
+ throw new Error('invalid child start-gate token');
36
+ return join(stateDir, `.${token}.gate`);
46
37
  }
47
- /** Persist a child record (atomic temp+rename). Fail-open. */
48
- export function writeChildRecord(stateDir, rec) {
38
+ function syncDirectory(dir) {
39
+ if (process.platform === 'win32')
40
+ return;
41
+ const fd = openSync(dir, 'r');
49
42
  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));
43
+ fsyncSync(fd);
44
+ }
45
+ finally {
46
+ closeSync(fd);
47
+ }
48
+ }
49
+ function durableExclusiveWrite(path, value) {
50
+ const fd = openSync(path, 'wx');
51
+ let failure;
52
+ try {
53
+ writeFileSync(fd, value);
54
+ fsyncSync(fd);
55
+ }
56
+ catch (error) {
57
+ failure = error;
58
+ }
59
+ try {
60
+ closeSync(fd);
61
+ }
62
+ catch (error) {
63
+ if (failure === undefined)
64
+ failure = error;
65
+ }
66
+ if (failure !== undefined) {
54
67
  try {
55
- renameSync(tmp, file);
68
+ rmSync(path, { force: true });
56
69
  }
57
- catch (err) {
58
- try {
59
- unlinkSync(tmp);
60
- }
61
- catch {
62
- // best-effort cleanup
63
- }
64
- throw err;
70
+ catch {
71
+ // Preserve the original write or close failure.
65
72
  }
73
+ throw failure;
66
74
  }
67
- catch {
68
- // fail-open: a lost record degrades metering, never kills the loop.
69
- }
75
+ syncDirectory(join(path, '..'));
70
76
  }
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;
77
+ function durableRemove(path) {
78
+ rmSync(path, { force: true });
79
+ syncDirectory(join(path, '..'));
80
+ }
81
+ function atomicWrite(path, value) {
82
+ const dir = join(path, '..');
83
+ mkdirSync(dir, { recursive: true });
84
+ const tmp = join(dir, `.${randomBytes(8).toString('hex')}-${process.pid}-${Date.now()}.tmp`);
85
+ durableExclusiveWrite(tmp, value);
75
86
  try {
76
- names = readdirSync(stateDir).filter((f) => f.endsWith('.json'));
87
+ renameSync(tmp, path);
88
+ syncDirectory(dir);
77
89
  }
78
- catch {
79
- return [];
90
+ catch (error) {
91
+ try {
92
+ unlinkSync(tmp);
93
+ }
94
+ catch {
95
+ // Preserve the original write failure.
96
+ }
97
+ throw error;
98
+ }
99
+ }
100
+ function writeStateRecord(stateDir, record) {
101
+ atomicWrite(recordFile(stateDir, record.run), JSON.stringify(record));
102
+ }
103
+ /** Persist a child record atomically. State persistence is correctness-sensitive and throws on failure. */
104
+ export function writeChildRecord(stateDir, record) {
105
+ writeStateRecord(stateDir, record);
106
+ }
107
+ /** Create the durable capacity reservation and closed start gate before spawn. */
108
+ export function reserveChild(stateDir, request) {
109
+ ensureStateDir(stateDir);
110
+ const token = randomBytes(16).toString('hex');
111
+ const gatePath = gateFile(stateDir, token);
112
+ const reservation = {
113
+ recordType: 'reservation',
114
+ workflow: request.workflow,
115
+ run: request.run,
116
+ reservedAt: request.reservedAt,
117
+ token,
118
+ childKind: request.childKind,
119
+ ...(request.step !== undefined ? { step: request.step } : {}),
120
+ };
121
+ durableExclusiveWrite(gatePath, 'wait\n');
122
+ try {
123
+ // Exclusive create is the same-run reservation point. A stale, live, or even
124
+ // corrupt existing record blocks dispatch rather than being overwritten.
125
+ durableExclusiveWrite(recordFile(stateDir, reservation.run), JSON.stringify(reservation));
80
126
  }
81
- const records = [];
82
- for (const name of names) {
127
+ catch (error) {
83
128
  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
- }
129
+ durableRemove(gatePath);
88
130
  }
89
131
  catch {
90
- // skip corrupt record
132
+ // Preserve the reservation write failure.
91
133
  }
134
+ throw error;
92
135
  }
93
- return records;
136
+ return { reservation, gatePath };
94
137
  }
95
- /** Delete a child record by run id. Fail-open. */
96
- export function removeChildRecord(stateDir, run) {
138
+ function isReservation(record) {
139
+ return record.recordType === 'reservation';
140
+ }
141
+ export class ShiftStateRecordError extends Error {
142
+ path;
143
+ constructor(path, detail) {
144
+ super(`cannot reconcile Shift state record '${path}': ${detail}; ` +
145
+ 'dispatch is disabled until the record is repaired or removed after verifying that no child still owns the slot');
146
+ this.name = 'ShiftStateRecordError';
147
+ this.path = path;
148
+ }
149
+ }
150
+ function readOneStateRecord(path) {
151
+ let raw;
97
152
  try {
98
- rmSync(recordFile(stateDir, run), { force: true });
153
+ raw = readFileSync(path, 'utf8');
154
+ }
155
+ catch (error) {
156
+ if (error.code === 'ENOENT')
157
+ return undefined;
158
+ const code = error.code;
159
+ throw new ShiftStateRecordError(path, `the canonical record is unreadable${code === undefined ? '' : ` (${code})`}`);
160
+ }
161
+ let parsed;
162
+ try {
163
+ parsed = JSON.parse(raw);
99
164
  }
100
165
  catch {
101
- // best-effort
166
+ throw new ShiftStateRecordError(path, 'the canonical record is truncated or is not valid JSON');
167
+ }
168
+ if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
169
+ throw new ShiftStateRecordError(path, 'the canonical record is not a JSON object');
170
+ }
171
+ if (typeof parsed['workflow'] !== 'string' || parsed['workflow'] === '' ||
172
+ typeof parsed['run'] !== 'string' || parsed['run'] === '') {
173
+ throw new ShiftStateRecordError(path, 'the canonical record is missing workflow or run identity');
174
+ }
175
+ if (basename(path) !== `${safeRun(parsed['run'])}.json`) {
176
+ throw new ShiftStateRecordError(path, 'the canonical record pathname does not match its run identity');
177
+ }
178
+ if (parsed['recordType'] === 'reservation') {
179
+ if (typeof parsed['reservedAt'] !== 'number' ||
180
+ !Number.isInteger(parsed['reservedAt']) ||
181
+ parsed['reservedAt'] < 0 ||
182
+ typeof parsed['token'] !== 'string' ||
183
+ !/^[a-f0-9]{32}$/u.test(parsed['token']) ||
184
+ (parsed['childKind'] !== 'exec' && parsed['childKind'] !== 'agent-run') ||
185
+ (parsed['step'] !== undefined && typeof parsed['step'] !== 'string')) {
186
+ throw new ShiftStateRecordError(path, 'the canonical reservation fields are malformed');
187
+ }
188
+ return parsed;
189
+ }
190
+ if (parsed['recordType'] !== undefined ||
191
+ typeof parsed['pid'] !== 'number' ||
192
+ !Number.isInteger(parsed['pid']) ||
193
+ parsed['pid'] <= 0 ||
194
+ typeof parsed['spawnedAt'] !== 'number' ||
195
+ !Number.isInteger(parsed['spawnedAt']) ||
196
+ parsed['spawnedAt'] < 0 ||
197
+ (parsed['kind'] !== undefined && parsed['kind'] !== 'exec' && parsed['kind'] !== 'agent-run') ||
198
+ (parsed['def'] !== undefined && typeof parsed['def'] !== 'string') ||
199
+ (parsed['hash'] !== undefined && typeof parsed['hash'] !== 'string') ||
200
+ (parsed['step'] !== undefined && typeof parsed['step'] !== 'string') ||
201
+ (parsed['gateToken'] !== undefined && (typeof parsed['gateToken'] !== 'string' ||
202
+ !/^[a-f0-9]{32}$/u.test(parsed['gateToken'])))) {
203
+ throw new ShiftStateRecordError(path, 'the canonical child fields are malformed');
204
+ }
205
+ return parsed;
206
+ }
207
+ function readStateRecords(stateDir) {
208
+ let names;
209
+ try {
210
+ names = readdirSync(stateDir)
211
+ .filter((name) => name.endsWith('.json') && name !== '.dispatch.lock.owner.json')
212
+ .sort();
213
+ }
214
+ catch (error) {
215
+ if (error.code === 'ENOENT')
216
+ return [];
217
+ throw error;
218
+ }
219
+ return names
220
+ .map((name) => readOneStateRecord(join(stateDir, name)))
221
+ .filter((record) => record !== undefined);
222
+ }
223
+ /** Read only PID-bearing records for status and compatibility callers. */
224
+ export function readChildRecords(stateDir) {
225
+ return readStateRecords(stateDir).filter((record) => !(isReservation(record)));
226
+ }
227
+ export function readChildReservations(stateDir) {
228
+ return readStateRecords(stateDir).filter((record) => isReservation(record));
229
+ }
230
+ /** Replace the matching reservation with a PID-bearing record before work starts. */
231
+ export function finalizeChildReservation(stateDir, reservation, child) {
232
+ const current = readOneStateRecord(recordFile(stateDir, reservation.run));
233
+ if (current === undefined ||
234
+ !isReservation(current) ||
235
+ current.token !== reservation.token) {
236
+ throw new Error(`child reservation for ${reservation.workflow}/${reservation.run} is missing or was replaced`);
237
+ }
238
+ const record = {
239
+ workflow: reservation.workflow,
240
+ run: reservation.run,
241
+ ...child,
242
+ gateToken: reservation.token,
243
+ };
244
+ writeStateRecord(stateDir, record);
245
+ return record;
246
+ }
247
+ function signalGate(path, signal, allowMissing) {
248
+ let fd;
249
+ try {
250
+ fd = openSync(path, 'r+');
251
+ }
252
+ catch (error) {
253
+ if (allowMissing && error.code === 'ENOENT')
254
+ return false;
255
+ throw error;
256
+ }
257
+ try {
258
+ ftruncateSync(fd, 0);
259
+ writeFileSync(fd, `${signal}\n`);
260
+ fsyncSync(fd);
261
+ }
262
+ finally {
263
+ closeSync(fd);
264
+ }
265
+ return true;
266
+ }
267
+ /** Open a child's gate only after the PID-bearing record is durable. */
268
+ export function startReservedChild(stateDir, record) {
269
+ if (record.gateToken === undefined)
270
+ return;
271
+ signalGate(gateFile(stateDir, record.gateToken), 'start', false);
272
+ }
273
+ /** Cancel a gated child and remove the matching reservation/record. */
274
+ export function cancelReservedChild(stateDir, reservation) {
275
+ const path = gateFile(stateDir, reservation.token);
276
+ try {
277
+ signalGate(path, 'cancel', true);
278
+ }
279
+ finally {
280
+ durableRemove(path);
281
+ const current = readOneStateRecord(recordFile(stateDir, reservation.run));
282
+ const matchesReservation = current !== undefined &&
283
+ isReservation(current) &&
284
+ current.token === reservation.token;
285
+ const matchesFinalized = current !== undefined &&
286
+ !isReservation(current) &&
287
+ current.gateToken === reservation.token;
288
+ if (matchesReservation || matchesFinalized)
289
+ durableRemove(recordFile(stateDir, reservation.run));
102
290
  }
103
291
  }
104
292
  /**
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).
293
+ * Delete one run's in-flight state. A still-gated reservation or finalized child
294
+ * is cancelled first so an external run-ended signal cannot leave a worker gate
295
+ * behind that later opens without a capacity record.
110
296
  */
297
+ export function removeChildRecord(stateDir, run) {
298
+ const path = recordFile(stateDir, run);
299
+ const current = readOneStateRecord(path);
300
+ if (current !== undefined && isReservation(current)) {
301
+ cancelReservedChild(stateDir, current);
302
+ return;
303
+ }
304
+ if (current?.gateToken !== undefined) {
305
+ const gatePath = gateFile(stateDir, current.gateToken);
306
+ try {
307
+ signalGate(gatePath, 'cancel', true);
308
+ }
309
+ finally {
310
+ durableRemove(gatePath);
311
+ }
312
+ }
313
+ durableRemove(path);
314
+ }
111
315
  export const defaultIsAlive = (pid) => {
112
316
  if (!Number.isInteger(pid) || pid <= 0)
113
317
  return false;
@@ -115,48 +319,67 @@ export const defaultIsAlive = (pid) => {
115
319
  process.kill(pid, 0);
116
320
  return true;
117
321
  }
118
- catch (err) {
119
- return err.code !== 'ESRCH';
322
+ catch (error) {
323
+ return error.code !== 'ESRCH';
120
324
  }
121
325
  };
122
326
  /**
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)`).
327
+ * Reconcile live children and durable reservations. Fresh reservations count as
328
+ * occupied capacity. An expired reservation is cancelled before its record is
329
+ * removed, so a child that was spawned but never finalized cannot begin work.
132
330
  */
133
331
  export function reconcileInFlight(stateDir, arg) {
134
- const opts = typeof arg === 'function' ? { isAlive: arg } : (arg ?? {});
135
- const isAlive = opts.isAlive ?? defaultIsAlive;
332
+ const options = typeof arg === 'function' ? { isAlive: arg } : (arg ?? {});
333
+ const isAlive = options.isAlive ?? defaultIsAlive;
334
+ const now = options.now ?? Date.now();
335
+ const maxAge = options.reservationMaxAgeMs ?? DEFAULT_RESERVATION_MAX_AGE_MS;
136
336
  const byRun = new Map();
137
- for (const rec of readChildRecords(stateDir))
138
- byRun.set(rec.run, rec);
337
+ for (const record of readStateRecords(stateDir))
338
+ byRun.set(record.run, record);
139
339
  const live = [];
340
+ const reserved = [];
140
341
  const reaped = [];
141
- for (const rec of byRun.values()) {
142
- const alive = isAlive(rec.pid);
143
- if (alive) {
144
- live.push(rec);
342
+ const abandoned = [];
343
+ for (const record of byRun.values()) {
344
+ if (isReservation(record)) {
345
+ // The worker removes its gate when its monotonic wait expires. A missing
346
+ // gate therefore proves that this reservation cannot start work, even if
347
+ // wall-clock rollback makes its persisted age look fresh.
348
+ const gateExists = existsSync(gateFile(stateDir, record.token));
349
+ // A persisted wall-clock timestamp from the future cannot be aged safely
350
+ // after a clock rollback. Cancel the reservation instead of letting a
351
+ // negative elapsed interval occupy capacity indefinitely.
352
+ if (gateExists && record.reservedAt <= now && now - record.reservedAt < maxAge) {
353
+ reserved.push(record);
354
+ continue;
355
+ }
356
+ cancelReservedChild(stateDir, record);
357
+ abandoned.push(record);
358
+ continue;
359
+ }
360
+ if (!isAlive(record.pid)) {
361
+ removeChildRecord(stateDir, record.run);
362
+ reaped.push(record);
363
+ continue;
364
+ }
365
+ if (record.gateToken !== undefined) {
366
+ // A restart after PID persistence but before the parent opened the gate can
367
+ // safely finish the handoff: the durable PID record is the prerequisite.
368
+ signalGate(gateFile(stateDir, record.gateToken), 'start', true);
369
+ const settled = { ...record };
370
+ delete settled.gateToken;
371
+ writeStateRecord(stateDir, settled);
372
+ live.push(settled);
145
373
  }
146
374
  else {
147
- removeChildRecord(stateDir, rec.run);
148
- reaped.push(rec);
375
+ live.push(record);
149
376
  }
150
377
  }
151
- return { live, reaped };
378
+ return { live, reserved, reaped, abandoned };
152
379
  }
153
- /** Ensure the state dir exists so the first read doesn't churn. Fail-open. */
380
+ /** Ensure the state directory exists and is readable. Failure is fatal to dispatch safety. */
154
381
  export function ensureStateDir(stateDir) {
155
- try {
156
- if (!existsSync(stateDir))
157
- mkdirSync(stateDir, { recursive: true });
158
- }
159
- catch {
160
- // fail-open
161
- }
382
+ if (!existsSync(stateDir))
383
+ mkdirSync(stateDir, { recursive: true });
384
+ readdirSync(stateDir);
162
385
  }
@@ -0,0 +1,36 @@
1
+ import { PrincipalKeyManager } from '../../../src/crypto/index.ts';
2
+ import type { SshProcessAdapter } from '../../../src/crypto/ssh.ts';
3
+ import type { OrderPacket } from './hub/types.ts';
4
+ export type SubmissionKeyManager = Pick<PrincipalKeyManager, 'inspect' | 'resolveRef' | 'withSigningKey'>;
5
+ export interface SubmitProofOptions {
6
+ origin: string;
7
+ order: OrderPacket;
8
+ path: string;
9
+ value: unknown;
10
+ /** Exact target version issued by a version-aware, retry-safe hub protocol. */
11
+ version?: number;
12
+ now: () => number;
13
+ warn: (line: string) => void;
14
+ principalKeys?: SubmissionKeyManager;
15
+ env?: Record<string, string | undefined>;
16
+ /** Injectable ssh-keygen seam for hermetic callers and tests. */
17
+ sshProcess?: SshProcessAdapter;
18
+ }
19
+ /**
20
+ * Sign one driver submit at the transport boundary. A missing machine key is
21
+ * deliberately an unsigned fallback for WP-D2; signer/tool failures still
22
+ * propagate because silently dropping a configured key would hide corruption.
23
+ */
24
+ export declare function buildSubmitProof(opts: SubmitProofOptions): Promise<string | undefined>;
25
+ /**
26
+ * Resolve the version named by the next submission from authoritative lifecycle
27
+ * metadata only. A judge approval attests the already-submitted version captured
28
+ * in the claim fingerprint and does not increment it. A producer submit requires
29
+ * an explicit target version issued by a retry-safe hub protocol: `owes[].version`
30
+ * is immutable claim-time state and becomes stale after a refinement, lost
31
+ * response, unsigned commit, or holder restart. Without an explicit target,
32
+ * callers must submit without a proof rather than sign a process-local guess.
33
+ */
34
+ export declare function outputVersionForSubmission(order: OrderPacket, path: string, explicit?: number): number | undefined;
35
+ /** Reset the process-local warning latch for hermetic tests. */
36
+ export declare function resetSubmitProofWarningForTests(): void;
@@ -0,0 +1,93 @@
1
+ import { DSSE_SSH_NAMESPACE, PrincipalKeyManager, buildSubmissionRecord, createSshSigner, signSubmission, } from "../../../src/crypto/index.js";
2
+ let warnedUnsigned = false;
3
+ /**
4
+ * Sign one driver submit at the transport boundary. A missing machine key is
5
+ * deliberately an unsigned fallback for WP-D2; signer/tool failures still
6
+ * propagate because silently dropping a configured key would hide corruption.
7
+ */
8
+ export async function buildSubmitProof(opts) {
9
+ const version = outputVersionForSubmission(opts.order, opts.path, opts.version);
10
+ if (version === undefined) {
11
+ warnUnsigned(opts.warn, `order ${opts.order.workflow}/${opts.order.run} omitted authoritative version metadata for output '${opts.path}'; submitting without a proof`);
12
+ return undefined;
13
+ }
14
+ const consumedFingerprint = submissionFingerprint(opts.order, opts.warn);
15
+ if (consumedFingerprint === undefined)
16
+ return undefined;
17
+ let keys;
18
+ try {
19
+ keys = opts.principalKeys ?? new PrincipalKeyManager({ env: opts.env ?? process.env });
20
+ }
21
+ catch (error) {
22
+ warnUnsigned(opts.warn, `machine signing is unavailable (${errorMessage(error)}); submitting without a proof`);
23
+ return undefined;
24
+ }
25
+ const ref = keys.resolveRef(opts.origin, 'machine');
26
+ if (ref === null) {
27
+ warnUnsigned(opts.warn, `no machine signing key for ${opts.origin}; submitting without a proof`);
28
+ return undefined;
29
+ }
30
+ const inspected = await keys.inspect(ref);
31
+ if (!inspected.exists || inspected.publicKey === undefined) {
32
+ warnUnsigned(opts.warn, `machine signing key for ${opts.origin} is unavailable; submitting without a proof`);
33
+ return undefined;
34
+ }
35
+ const record = buildSubmissionRecord({
36
+ run: opts.order.run,
37
+ workflow: opts.order.workflow,
38
+ defDigest: opts.order.defDigest,
39
+ step: opts.order.step,
40
+ key: opts.order.key,
41
+ ...(opts.order.index !== undefined ? { index: opts.order.index } : {}),
42
+ produced: [{ artifact: opts.path, version, value: opts.value }],
43
+ consumedFingerprint,
44
+ producerKeyId: inspected.publicKey.keyid,
45
+ timestamp: opts.now(),
46
+ });
47
+ return keys.withSigningKey(ref, async (keyPath) => {
48
+ const signer = createSshSigner({
49
+ namespace: DSSE_SSH_NAMESPACE,
50
+ signKeyPath: keyPath,
51
+ ...(opts.sshProcess !== undefined ? { process: opts.sshProcess } : {}),
52
+ });
53
+ return signSubmission(record, signer);
54
+ });
55
+ }
56
+ function submissionFingerprint(order, warn) {
57
+ if (order.consumedFingerprint !== undefined)
58
+ return order.consumedFingerprint;
59
+ if (order.inputs.length > 0 || Object.keys(order.consumes).length > 0) {
60
+ warnUnsigned(warn, `order ${order.workflow}/${order.run} omitted its consumed fingerprint; submitting without a proof`);
61
+ return undefined;
62
+ }
63
+ return {};
64
+ }
65
+ /**
66
+ * Resolve the version named by the next submission from authoritative lifecycle
67
+ * metadata only. A judge approval attests the already-submitted version captured
68
+ * in the claim fingerprint and does not increment it. A producer submit requires
69
+ * an explicit target version issued by a retry-safe hub protocol: `owes[].version`
70
+ * is immutable claim-time state and becomes stale after a refinement, lost
71
+ * response, unsigned commit, or holder restart. Without an explicit target,
72
+ * callers must submit without a proof rather than sign a process-local guess.
73
+ */
74
+ export function outputVersionForSubmission(order, path, explicit) {
75
+ if (explicit !== undefined)
76
+ return explicit;
77
+ if (order.judge === path)
78
+ return order.consumedFingerprint?.[path];
79
+ return undefined;
80
+ }
81
+ function errorMessage(error) {
82
+ return error instanceof Error ? error.message : String(error);
83
+ }
84
+ function warnUnsigned(warn, reason) {
85
+ if (warnedUnsigned)
86
+ return;
87
+ warnedUnsigned = true;
88
+ warn(`owenloop: ${reason}`);
89
+ }
90
+ /** Reset the process-local warning latch for hermetic tests. */
91
+ export function resetSubmitProofWarningForTests() {
92
+ warnedUnsigned = false;
93
+ }