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
@@ -8,52 +8,25 @@
8
8
  */
9
9
  import { chmodSync, lstatSync, mkdirSync, renameSync, unlinkSync, } from 'node:fs';
10
10
  import { createServer, createConnection } from 'node:net';
11
- import { MAX_EVENT_QUEUE, MAX_REQUEST_LINE_BYTES, MAX_RESPONSE_LINE_BYTES, OVERLAP_ERROR, RESPONSE_TRUNCATION_MARKER, } from "./protocol.js";
11
+ import { MAX_EVENT_QUEUE, MAX_REQUEST_LINE_BYTES, MAX_RESPONSE_LINE_BYTES, OVERLAP_ERROR, stampShiftEvent, } from "./protocol.js";
12
+ import { truncateEventToBytes } from "./truncate.js";
12
13
  const REQUEST_IDLE_TIMEOUT_MS = 5_000;
13
14
  const SHUTDOWN_GRACE_MS = 500;
14
15
  function serializedResponseBytes(response) {
15
16
  return Buffer.byteLength(`${JSON.stringify(response)}\n`, 'utf8');
16
17
  }
17
- function truncateUtf8(value, maxBytes) {
18
- if (Buffer.byteLength(value, 'utf8') <= maxBytes)
19
- return value;
20
- const markerBytes = Buffer.byteLength(RESPONSE_TRUNCATION_MARKER, 'utf8');
21
- if (maxBytes <= markerBytes)
22
- return RESPONSE_TRUNCATION_MARKER;
23
- let prefix = Buffer.from(value, 'utf8').subarray(0, maxBytes - markerBytes).toString('utf8');
24
- while (Buffer.byteLength(prefix, 'utf8') > maxBytes - markerBytes)
25
- prefix = prefix.slice(0, -1);
26
- return `${prefix}${RESPONSE_TRUNCATION_MARKER}`;
27
- }
28
18
  /**
29
19
  * A single event can be larger than the response ceiling. It is delivered once
30
20
  * with its string fields shortened and an explicit marker instead of blocking
31
21
  * every later event in the FIFO forever.
22
+ *
23
+ * The algorithm lives in `truncate.ts` and is SHARED with the on-disk log sink,
24
+ * so the file's line ceiling and the wire's are one rule with one
25
+ * implementation. Only the byte accounting differs, and that is what the
26
+ * callback supplies: here, a whole response envelope carrying this one event.
32
27
  */
33
28
  function truncateEventForResponse(event, envelope) {
34
- const candidate = { ...event };
35
- const stringKeys = Object.keys(candidate).filter((key) => typeof candidate[key] === 'string' && key !== 'type');
36
- const markerBytes = Buffer.byteLength(RESPONSE_TRUNCATION_MARKER, 'utf8');
37
- while (serializedResponseBytes({ ...envelope, events: [candidate] }) > MAX_RESPONSE_LINE_BYTES) {
38
- const key = stringKeys
39
- .filter((name) => candidate[name] !== RESPONSE_TRUNCATION_MARKER)
40
- .sort((left, right) => Buffer.byteLength(String(candidate[right]), 'utf8') - Buffer.byteLength(String(candidate[left]), 'utf8'))[0];
41
- if (key === undefined)
42
- break;
43
- const value = String(candidate[key]);
44
- const currentBytes = Buffer.byteLength(value, 'utf8');
45
- const targetBytes = Math.max(markerBytes, Math.floor(currentBytes / 2));
46
- const shortened = truncateUtf8(value, targetBytes);
47
- candidate[key] = shortened === value ? RESPONSE_TRUNCATION_MARKER : shortened;
48
- }
49
- // The current event union has a fixed envelope plus only string fields. The
50
- // marker-only form is a final backstop if a future event shape needs more
51
- // reduction than the progressive shortening above provided.
52
- if (serializedResponseBytes({ ...envelope, events: [candidate] }) > MAX_RESPONSE_LINE_BYTES) {
53
- for (const key of stringKeys)
54
- candidate[key] = RESPONSE_TRUNCATION_MARKER;
55
- }
56
- return candidate;
29
+ return truncateEventToBytes(event, MAX_RESPONSE_LINE_BYTES, (candidate) => serializedResponseBytes({ ...envelope, events: [candidate] }));
57
30
  }
58
31
  function fileIdentity(stat) {
59
32
  return { dev: stat.dev, ino: stat.ino, ctimeMs: stat.ctimeMs };
@@ -282,6 +255,27 @@ export function createShiftDaemon(opts) {
282
255
  const connections = new Set();
283
256
  const shutdownSockets = new Set();
284
257
  const events = [];
258
+ /**
259
+ * How many events the FIFO has evicted since this daemon started, and the
260
+ * cumulative count at which the NEXT overflow record is written.
261
+ *
262
+ * Reporting every eviction is not an option: an unattended shift — no client
263
+ * ever calls `next`, so nothing ever drains the queue — evicts one event per
264
+ * event forever, and a per-eviction record would roughly double the volume of
265
+ * a file this change does not rotate.
266
+ *
267
+ * Reporting only the first eviction is not an option either: that record says
268
+ * `dropped: 1` and is never corrected, so the operator reading the file learns
269
+ * that loss STARTED and never learns its size.
270
+ *
271
+ * So: report at each power of ten (1, 10, 100, 1000, …). At most ~7 records
272
+ * for any run a real machine can produce, the first arrives immediately, and
273
+ * every record carries a current cumulative total.
274
+ */
275
+ let dropped = 0;
276
+ let nextOverflowReport = 1;
277
+ /** Attach the `{ts, shift, shiftId}` envelope this daemon is responsible for. */
278
+ const stamp = (body) => stampShiftEvent(body, { name: opts.loop.getShift().name, id: opts.shiftId ?? '' }, opts.now());
285
279
  const capacity = () => {
286
280
  const cap = opts.loop.getCap();
287
281
  const free = opts.loop.freeCapacity();
@@ -333,6 +327,20 @@ export function createShiftDaemon(opts) {
333
327
  if (events.length >= MAX_EVENT_QUEUE) {
334
328
  events.shift();
335
329
  opts.err(`shift event queue overflow — dropping oldest event`);
330
+ dropped += 1;
331
+ if (dropped === nextOverflowReport) {
332
+ nextOverflowReport *= 10;
333
+ // DIRECT to the caller's sink — never enqueue(). enqueue() feeds the
334
+ // very queue that just overflowed, so an overflow event routed through
335
+ // it would evict another event, overflow again, and recurse under
336
+ // exactly the load that produced the overflow.
337
+ try {
338
+ opts.onSynthesized?.(stamp({ type: 'event-queue-overflow', dropped }));
339
+ }
340
+ catch (e) {
341
+ opts.err(`shift event sink failed: ${e instanceof Error ? e.message : String(e)} (continuing)`);
342
+ }
343
+ }
336
344
  }
337
345
  events.push(event);
338
346
  if (parked !== undefined)
@@ -462,7 +470,24 @@ export function createShiftDaemon(opts) {
462
470
  if (reason === 'end') {
463
471
  if (parked !== undefined)
464
472
  shutdownSockets.add(parked.socket);
465
- enqueue({ type: 'ended' });
473
+ // `ended` is synthesized here rather than received from the loop, so it is
474
+ // one of the two events `emit()` in loop.ts never stamps. Stamp it once
475
+ // and hand the SAME record to both consumers, so the socket and the file
476
+ // agree on its `ts` down to the millisecond.
477
+ //
478
+ // Note the narrow meaning, which `docs/shift-logs.md` states for readers
479
+ // of the file: `ended` is written only for `reason === 'end'` — an
480
+ // operator ran `owenloop shift end`. A signal or a loop failure ends the
481
+ // process without one, so a `shift.log` with no trailing `ended` record
482
+ // describes a shift that stopped some other way, or is still running.
483
+ const ended = stamp({ type: 'ended' });
484
+ enqueue(ended);
485
+ try {
486
+ opts.onSynthesized?.(ended);
487
+ }
488
+ catch (e) {
489
+ opts.err(`shift event sink failed: ${e instanceof Error ? e.message : String(e)} (continuing)`);
490
+ }
466
491
  }
467
492
  else if (parked !== undefined) {
468
493
  // A signal or unexpected loop exit does not synthesize an `ended` event,
@@ -1,3 +1,4 @@
1
+ export { resolveOwenloopBin } from '../owenloop-bin.ts';
1
2
  /**
2
3
  * What to spawn: the order to run. `run` IS the order id (hub verb contract);
3
4
  * `workflow` pairs with it (every hub verb needs both). The hub `origin` is NOT
@@ -7,6 +8,8 @@
7
8
  export interface SpawnSpec {
8
9
  workflow: string;
9
10
  run: string;
11
+ /** Step name, carried only for safe local lifecycle reporting. */
12
+ step?: string;
10
13
  /**
11
14
  * Which role the detached child runs (Phase 3). Absent ⇒ `'exec'`, so every
12
15
  * pre-Phase-3 caller and every faked spawner in the existing tests keeps its
@@ -18,38 +21,120 @@ export interface SpawnSpec {
18
21
  */
19
22
  kind?: 'exec' | 'agent-run';
20
23
  /**
21
- * The harness id to host the step agent in, for `kind: 'agent-run'` only.
22
- * Absent carries no `--harness` flag, leaving the child to resolve the id
23
- * from `OWENLOOP_HARNESS`, the step def, or its built-in default. Ignored for
24
- * `'exec'` (a command order has no step agent).
24
+ * Optional safe lifecycle-reporting label for an `agent-run` child. This field
25
+ * never becomes `--harness`; the child resolves the authoritative harness from
26
+ * CLI/environment/verified runtime definition precedence.
27
+ *
28
+ * It is ONE INPUT to the reported label, not the label itself, and it is the
29
+ * LOWER-ranked one: `reportedHarnessId` puts the child's `OWENLOOP_HARNESS`
30
+ * above it, because the child does.
25
31
  */
26
32
  harness?: string;
33
+ /** Closed start gate created by the durable Shift reservation. */
34
+ startGate?: string;
27
35
  }
28
- /** The result the loop records: the child's pid. */
36
+ /** The result the loop records plus best-effort pre-start cancellation handles. */
29
37
  export interface SpawnResult {
30
38
  pid: number;
39
+ /**
40
+ * Dispatcher-owned cancellation. The default spawner disarms spontaneous
41
+ * lifecycle reporting before sending SIGTERM, so one failed dispatch emits
42
+ * one Shift failure event.
43
+ */
44
+ cancel?: () => void;
45
+ /** Legacy injected-spawner compatibility. New dispatcher code prefers cancel. */
46
+ terminate?: () => void;
31
47
  }
32
48
  /** The spawn seam. Injected; faked in tests. */
33
49
  export type Spawner = (spec: SpawnSpec) => SpawnResult;
50
+ /**
51
+ * Where a detached worker's own stdout and stderr are appended, when the shift
52
+ * has a log directory. `dir` absent ⇒ workers stay `stdio: ['ignore','ignore',
53
+ * 'ignore']`, exactly as before this option existed.
54
+ */
55
+ export interface WorkerLogOptions {
56
+ /** The resolved log directory. `<dir>/<run>.log` is the destination. */
57
+ dir: string;
58
+ /** One-time failure report sink for a log that could not be opened. */
59
+ err?: (line: string) => void;
60
+ }
61
+ /** Safe, bounded metadata emitted when a detached worker fails. Detached
62
+ * worker stderr is not attached to Shift as a PIPE: agent-run output is
63
+ * untrusted, and a parent-owned pipe can kill either worker with EPIPE after
64
+ * Shift exits. It is appended to a per-run FILE instead — see
65
+ * `createDefaultSpawner`. */
66
+ export interface WorkerFailure {
67
+ workflow: string;
68
+ run: string;
69
+ step?: string;
70
+ kind: 'exec' | 'agent-run';
71
+ harness?: string;
72
+ executable: string;
73
+ exitStatus: number | null;
74
+ signal: NodeJS.Signals | null;
75
+ message: string;
76
+ }
77
+ export type WorkerFailureReporter = (failure: WorkerFailure) => void;
78
+ /**
79
+ * The harness id to REPORT on an agent-run worker failure — a best-effort
80
+ * mirror of the id the CHILD resolved, never an independent decision.
81
+ *
82
+ * It mirrors `resolveAdapter` in `roles/agent-run.ts`, minus the `--harness`
83
+ * rank the Shift never emits:
84
+ *
85
+ * 1. `OWENLOOP_HARNESS` when the variable is SET. Set-but-blank is not a
86
+ * fall-through: the child refuses that config outright and names it
87
+ * `<empty OWENLOOP_HARNESS>`, so the failure event says the same thing.
88
+ * 2. `spec.harness` — the prepared-cache step's `harness` field — when it is
89
+ * a non-empty string. An empty string counts as absent, matching the
90
+ * child.
91
+ * 3. Otherwise the child took the first REGISTERED adapter. This process
92
+ * cannot name it: the Shift is a neutral dispatcher and never imports the
93
+ * adapter composition root, so its own registry is empty and asking it
94
+ * would answer `undefined`. Report the placeholder instead.
95
+ *
96
+ * WHY THE ORDER MATTERS. It used to read `spec.harness ?? OWENLOOP_HARNESS`,
97
+ * which is the child's precedence INVERTED. An operator who pinned
98
+ * `OWENLOOP_HARNESS` on a shift whose cached step also named a harness got a
99
+ * failure event naming the harness that did NOT run — the single most
100
+ * misleading field in the record, since the harness is the first thing an
101
+ * operator reaches for when a worker dies.
102
+ *
103
+ * BEST-EFFORT IS DELIBERATE at rank 2. A modern agent order carries no
104
+ * `spec.harness` at all (the child reads the verified, order-pinned step), so
105
+ * rank 2 only ever fires on the legacy cache path. The alternative — the Shift
106
+ * verifying the order digest itself purely to label a failure — would duplicate
107
+ * the child's whole resolution for a diagnostic string.
108
+ *
109
+ * `env` is the environment the CHILD is spawned with (`plan.options.env`), not
110
+ * this process's — they differ, and the child's is the one that decided.
111
+ */
112
+ export declare function reportedHarnessId(spec: Pick<SpawnSpec, 'harness'>, env: NodeJS.ProcessEnv): string;
113
+ /**
114
+ * The stdio topology of a detached worker.
115
+ *
116
+ * Slot 0 is always `'ignore'`: a worker reads nothing. Slots 1 and 2 are either
117
+ * both `'ignore'` (no log destination resolved, or opening it failed) or both
118
+ * the SAME descriptor number — one file opened once and handed to stdout and
119
+ * stderr together, which is exactly shell `2>&1`.
120
+ */
121
+ export type WorkerStdio = ['ignore', 'ignore', 'ignore'] | ['ignore', number, number];
34
122
  /** The fully-resolved spawn arguments — pure data, asserted directly in tests. */
35
123
  export interface SpawnPlan {
36
124
  command: string;
37
125
  args: string[];
38
126
  options: {
39
127
  detached: true;
40
- stdio: 'ignore';
128
+ stdio: WorkerStdio;
41
129
  env: NodeJS.ProcessEnv;
42
130
  };
131
+ /**
132
+ * Absolute path this worker's stdout and stderr should be appended to, when a
133
+ * log directory is configured. A PATH, never a descriptor: `buildSpawnPlan`
134
+ * stays pure, and `createDefaultSpawner` does the opening.
135
+ */
136
+ logFile?: string;
43
137
  }
44
- /**
45
- * Resolve the single packaged `bin/owenloop.mjs` from this module's URL.
46
- *
47
- * Source-driven tests import `packages/work/src/**`, while installed/runtime
48
- * execution imports `dist/packages/work/src/**`; those layouts are one parent
49
- * level apart. Choose the existing candidate so detached children use the root
50
- * binary in both layouts.
51
- */
52
- export declare function resolveOwenloopBin(): string;
53
138
  /**
54
139
  * Build the argv + options for a detached
55
140
  * `owenloop work exec <workflow>/<run> --origin <url>`. Pure — no spawn, no I/O — so
@@ -68,13 +153,24 @@ export declare function resolveOwenloopBin(): string;
68
153
  * (advisory only, D8/INV-82). Omitted/empty carries no flag at all.
69
154
  *
70
155
  * Phase 3 (D6) widens this ONE seam rather than adding a second: `spec.kind`
71
- * selects the role positional (`exec` vs `agent-run`) and `spec.harness`
72
- * appends `--harness <id>` on the `agent-run` branch. Everything else — the
156
+ * selects the role positional (`exec` vs `agent-run`). Everything else — the
73
157
  * composite order positional, `--origin`, `--shift`, and every spawn option
74
158
  * — is identical for both kinds, so an agent-run child is detached,
75
159
  * stdio-ignored, and account-scoped exactly like an exec child.
160
+ *
161
+ * The Shift never emits `--harness`. A prepared-cache step is dispatch metadata,
162
+ * not an operator override; the `agent-run` child resolves its authoritative
163
+ * inputs in precedence order (`--harness`, `OWENLOOP_HARNESS`, verified runtime
164
+ * step, registered default). The Shift command has no operator-facing harness
165
+ * flag, so there is no legitimate CLI override for this seam to carry.
166
+ *
167
+ * `logDir` (trailing, after `shiftId`, for the same reason) adds the worker's
168
+ * log DESTINATION to the plan as `<logDir>/<run>.log`. The plan still carries
169
+ * `stdio: ['ignore','ignore','ignore']`: opening the file is I/O, this function
170
+ * is pure, and `createDefaultSpawner` substitutes the descriptors. Omitted ⇒ no
171
+ * `logFile` key at all, and the plan is byte-identical to the pre-logging shape.
76
172
  */
77
- export declare function buildSpawnPlan(spec: SpawnSpec, origin: string, account: string, binPath: string, execPath?: string, shiftId?: string): SpawnPlan;
173
+ export declare function buildSpawnPlan(spec: SpawnSpec, origin: string, account: string, binPath: string, execPath?: string, shiftId?: string, logDir?: string): SpawnPlan;
78
174
  /**
79
175
  * The default detached spawner. Captures the resolved hub `origin`, the
80
176
  * resolved `account`, the packaged bin path, and the dispatching Shift's
@@ -83,4 +179,4 @@ export declare function buildSpawnPlan(spec: SpawnSpec, origin: string, account:
83
179
  * relying on `buildSpawnPlan`'s default) so `shiftId` — trailing after it
84
180
  * — can be supplied positionally.
85
181
  */
86
- export declare function createDefaultSpawner(origin: string, account: string, binPath?: string, shiftId?: string): Spawner;
182
+ export declare function createDefaultSpawner(origin: string, account: string, binPath?: string, shiftId?: string, onFailure?: WorkerFailureReporter, logging?: WorkerLogOptions): Spawner;
@@ -3,7 +3,9 @@
3
3
  *
4
4
  * Every order the shift dispatches becomes a DETACHED
5
5
  * `owenloop work exec <workflow>/<run> --origin <url>` child: `detached: true`,
6
- * `stdio: 'ignore'`, `unref()` — so the child is its own process-group leader and
6
+ * stdin ignored, stdout and stderr appended to `<log-dir>/<run>.log` when the
7
+ * shift resolved a log directory (and ignored when it did not), `unref()` — so
8
+ * the child is its own process-group leader and
7
9
  * survives the parent's death (SP5-verified kernel reparenting). The shift meters
8
10
  * and hands off; the child self-leases (C5). Both ids ride the argv as the
9
11
  * composite `<workflow>/<run>` order-id `owenloop work exec` parses, and `--origin`
@@ -13,27 +15,95 @@
13
15
  * env is the contract), selecting which Scoped Identity credential slot
14
16
  * (agent:<account>) exec reads.
15
17
  *
16
- * `Spawner` is an injected seam; unit tests always fake it and NEVER spawn a
17
- * real child. The default impl's argv/option construction is factored into the
18
- * pure `buildSpawnPlan` so a test can assert the exact shape as data.
18
+ * `Spawner` is an injected seam; most loop tests fake it. The default impl's
19
+ * argv/option construction is factored into the pure `buildSpawnPlan`, while a
20
+ * focused lifecycle regression uses harmless local children.
19
21
  */
20
- import { existsSync } from 'node:fs';
21
22
  import { spawn } from 'node:child_process';
22
- import { fileURLToPath } from 'node:url';
23
+ import { closeSync, openSync } from 'node:fs';
24
+ import { resolveOwenloopBin } from "../owenloop-bin.js";
25
+ import { runLogFile } from "./logretention.js";
26
+ export { resolveOwenloopBin } from "../owenloop-bin.js";
23
27
  /**
24
- * Resolve the single packaged `bin/owenloop.mjs` from this module's URL.
28
+ * Open one worker's log for appending, or give up and return `undefined`.
25
29
  *
26
- * Source-driven tests import `packages/work/src/**`, while installed/runtime
27
- * execution imports `dist/packages/work/src/**`; those layouts are one parent
28
- * level apart. Choose the existing candidate so detached children use the root
29
- * binary in both layouts.
30
+ * A LOG THAT WILL NOT OPEN MUST NEVER FAIL AN ORDER. A full disk, a read-only
31
+ * directory, or a path an operator deleted underneath the shift costs
32
+ * observability for that worker and nothing else: the caller falls back to
33
+ * `'ignore'` on slots 1 and 2 and dispatches anyway.
34
+ *
35
+ * `report` is the caller's LATCHED sink — see `createDefaultSpawner`. This
36
+ * function reports on every failure it sees; the latch that turns that into one
37
+ * line per shift lives with the spawner, which is the thing whose lifetime the
38
+ * latch is scoped to.
39
+ *
40
+ * MODE 0600, OWNER ONLY. A worker runs authored workflow content, so its
41
+ * stdout and stderr are attacker-influenceable data and may contain whatever a
42
+ * step printed — including a token a step echoed. `exec/loop.ts` already writes
43
+ * its agent-produced artifact JSON with `mode: 0o600` for exactly this reason;
44
+ * a raw worker log is the same data class and strictly less filtered. Without
45
+ * an explicit mode `openSync` creates 0666 & ~umask, which is 0644 under the
46
+ * usual 022 — readable by every local account.
47
+ *
48
+ * THE MODE APPLIES ONLY WHEN THE FILE IS CREATED. Append mode never re-chmods,
49
+ * so a `<run>.log` left behind by a build from before this became explicit
50
+ * keeps its old permissions. That is deliberate: silently tightening a file an
51
+ * operator may have already handed to an uploader account is a worse surprise
52
+ * than a stale-permission file the operator can fix with one `chmod`.
30
53
  */
31
- export function resolveOwenloopBin() {
32
- const candidates = [
33
- new URL('../../../../bin/owenloop.mjs', import.meta.url),
34
- new URL('../../../../../bin/owenloop.mjs', import.meta.url),
35
- ].map((url) => fileURLToPath(url));
36
- return candidates.find((candidate) => existsSync(candidate)) ?? candidates[0];
54
+ function openWorkerLog(path, report) {
55
+ try {
56
+ return openSync(path, 'a', 0o600);
57
+ }
58
+ catch (e) {
59
+ report(`owenloop shift: could not open worker log ${path}: ${err(e)} — dispatching with its output discarded`);
60
+ return undefined;
61
+ }
62
+ }
63
+ function err(e) {
64
+ return e instanceof Error ? e.message : String(e);
65
+ }
66
+ /**
67
+ * The harness id to REPORT on an agent-run worker failure — a best-effort
68
+ * mirror of the id the CHILD resolved, never an independent decision.
69
+ *
70
+ * It mirrors `resolveAdapter` in `roles/agent-run.ts`, minus the `--harness`
71
+ * rank the Shift never emits:
72
+ *
73
+ * 1. `OWENLOOP_HARNESS` when the variable is SET. Set-but-blank is not a
74
+ * fall-through: the child refuses that config outright and names it
75
+ * `<empty OWENLOOP_HARNESS>`, so the failure event says the same thing.
76
+ * 2. `spec.harness` — the prepared-cache step's `harness` field — when it is
77
+ * a non-empty string. An empty string counts as absent, matching the
78
+ * child.
79
+ * 3. Otherwise the child took the first REGISTERED adapter. This process
80
+ * cannot name it: the Shift is a neutral dispatcher and never imports the
81
+ * adapter composition root, so its own registry is empty and asking it
82
+ * would answer `undefined`. Report the placeholder instead.
83
+ *
84
+ * WHY THE ORDER MATTERS. It used to read `spec.harness ?? OWENLOOP_HARNESS`,
85
+ * which is the child's precedence INVERTED. An operator who pinned
86
+ * `OWENLOOP_HARNESS` on a shift whose cached step also named a harness got a
87
+ * failure event naming the harness that did NOT run — the single most
88
+ * misleading field in the record, since the harness is the first thing an
89
+ * operator reaches for when a worker dies.
90
+ *
91
+ * BEST-EFFORT IS DELIBERATE at rank 2. A modern agent order carries no
92
+ * `spec.harness` at all (the child reads the verified, order-pinned step), so
93
+ * rank 2 only ever fires on the legacy cache path. The alternative — the Shift
94
+ * verifying the order digest itself purely to label a failure — would duplicate
95
+ * the child's whole resolution for a diagnostic string.
96
+ *
97
+ * `env` is the environment the CHILD is spawned with (`plan.options.env`), not
98
+ * this process's — they differ, and the child's is the one that decided.
99
+ */
100
+ export function reportedHarnessId(spec, env) {
101
+ const fromEnv = env['OWENLOOP_HARNESS'];
102
+ if (fromEnv !== undefined)
103
+ return fromEnv.trim() === '' ? '<empty OWENLOOP_HARNESS>' : fromEnv;
104
+ if (spec.harness !== undefined && spec.harness !== '')
105
+ return spec.harness;
106
+ return '<registered default>';
37
107
  }
38
108
  /**
39
109
  * Build the argv + options for a detached
@@ -53,13 +123,24 @@ export function resolveOwenloopBin() {
53
123
  * (advisory only, D8/INV-82). Omitted/empty carries no flag at all.
54
124
  *
55
125
  * Phase 3 (D6) widens this ONE seam rather than adding a second: `spec.kind`
56
- * selects the role positional (`exec` vs `agent-run`) and `spec.harness`
57
- * appends `--harness <id>` on the `agent-run` branch. Everything else — the
126
+ * selects the role positional (`exec` vs `agent-run`). Everything else — the
58
127
  * composite order positional, `--origin`, `--shift`, and every spawn option
59
128
  * — is identical for both kinds, so an agent-run child is detached,
60
129
  * stdio-ignored, and account-scoped exactly like an exec child.
130
+ *
131
+ * The Shift never emits `--harness`. A prepared-cache step is dispatch metadata,
132
+ * not an operator override; the `agent-run` child resolves its authoritative
133
+ * inputs in precedence order (`--harness`, `OWENLOOP_HARNESS`, verified runtime
134
+ * step, registered default). The Shift command has no operator-facing harness
135
+ * flag, so there is no legitimate CLI override for this seam to carry.
136
+ *
137
+ * `logDir` (trailing, after `shiftId`, for the same reason) adds the worker's
138
+ * log DESTINATION to the plan as `<logDir>/<run>.log`. The plan still carries
139
+ * `stdio: ['ignore','ignore','ignore']`: opening the file is I/O, this function
140
+ * is pure, and `createDefaultSpawner` substitutes the descriptors. Omitted ⇒ no
141
+ * `logFile` key at all, and the plan is byte-identical to the pre-logging shape.
61
142
  */
62
- export function buildSpawnPlan(spec, origin, account, binPath, execPath = process.execPath, shiftId) {
143
+ export function buildSpawnPlan(spec, origin, account, binPath, execPath = process.execPath, shiftId, logDir) {
63
144
  const role = spec.kind === 'agent-run' ? 'agent-run' : 'exec';
64
145
  return {
65
146
  command: execPath,
@@ -71,11 +152,17 @@ export function buildSpawnPlan(spec, origin, account, binPath, execPath = proces
71
152
  '--origin',
72
153
  origin,
73
154
  ...(shiftId !== undefined && shiftId !== '' ? ['--shift', shiftId] : []),
74
- ...(role === 'agent-run' && spec.harness !== undefined && spec.harness !== ''
75
- ? ['--harness', spec.harness]
76
- : []),
77
155
  ],
78
- options: { detached: true, stdio: 'ignore', env: { ...process.env, OWENLOOP_ACCOUNT: account } },
156
+ options: {
157
+ detached: true,
158
+ stdio: ['ignore', 'ignore', 'ignore'],
159
+ env: {
160
+ ...process.env,
161
+ OWENLOOP_ACCOUNT: account,
162
+ ...(spec.startGate !== undefined ? { OWENLOOP_START_GATE: spec.startGate } : {}),
163
+ },
164
+ },
165
+ ...(logDir !== undefined && logDir !== '' ? { logFile: runLogFile(logDir, spec.run) } : {}),
79
166
  };
80
167
  }
81
168
  /**
@@ -86,15 +173,132 @@ export function buildSpawnPlan(spec, origin, account, binPath, execPath = proces
86
173
  * relying on `buildSpawnPlan`'s default) so `shiftId` — trailing after it
87
174
  * — can be supplied positionally.
88
175
  */
89
- export function createDefaultSpawner(origin, account, binPath = resolveOwenloopBin(), shiftId) {
176
+ export function createDefaultSpawner(origin, account, binPath = resolveOwenloopBin(), shiftId, onFailure, logging) {
177
+ // ONE report per shift, not one per dispatch. Every condition that stops a
178
+ // worker log from opening — a full disk, a read-only log directory, an
179
+ // operator deleting it underneath a running shift — PERSISTS across the
180
+ // dispatches that follow, so an unlatched report writes one stderr line per
181
+ // dispatch for as long as the shift runs. The event sink latches its own
182
+ // failure report the same way (`logsink.ts`); these are the two failure paths
183
+ // of the same feature and they make the operator the same promise.
184
+ let reportedOpenFailure = false;
185
+ const reportOpenFailure = (line) => {
186
+ if (reportedOpenFailure)
187
+ return;
188
+ reportedOpenFailure = true;
189
+ logging?.err?.(line);
190
+ };
90
191
  return (spec) => {
91
- const plan = buildSpawnPlan(spec, origin, account, binPath, process.execPath, shiftId);
92
- const child = spawn(plan.command, plan.args, plan.options);
192
+ const plan = buildSpawnPlan(spec, origin, account, binPath, process.execPath, shiftId, logging?.dir);
193
+ // Open the log ONCE and hand the SAME descriptor to slots 1 and 2. Opening
194
+ // it twice would create two independent file offsets, and the two streams
195
+ // would overwrite each other's bytes — silent corruption no unit test on the
196
+ // plan can catch. One descriptor used twice is exactly shell `2>&1`.
197
+ //
198
+ // ALWAYS APPEND, never truncate. A retried or re-armed run reuses its run
199
+ // id, and the prior attempt's output is precisely the evidence this feature
200
+ // exists to keep.
201
+ const logFd = plan.logFile === undefined
202
+ ? undefined
203
+ : openWorkerLog(plan.logFile, reportOpenFailure);
204
+ const options = logFd === undefined
205
+ ? plan.options
206
+ : { ...plan.options, stdio: ['ignore', logFd, logFd] };
207
+ let child;
208
+ try {
209
+ child = spawn(plan.command, plan.args, options);
210
+ }
211
+ finally {
212
+ // The parent's copy must go once the child has inherited its own dup, and
213
+ // it must go even when `spawn` throws. A long-lived shift that leaked one
214
+ // descriptor per dispatch would eventually hit EMFILE and stop
215
+ // dispatching entirely.
216
+ if (logFd !== undefined) {
217
+ try {
218
+ closeSync(logFd);
219
+ }
220
+ catch {
221
+ // Nothing useful remains to do with a descriptor that will not close.
222
+ }
223
+ }
224
+ }
225
+ const kind = spec.kind === 'agent-run' ? 'agent-run' : 'exec';
226
+ const harness = kind === 'agent-run' ? reportedHarnessId(spec, plan.options.env) : undefined;
227
+ // This process is the executable Shift actually launched. The harness may
228
+ // start its own vendor process later, but reporting or guessing that
229
+ // executable here would couple the neutral dispatcher to one adapter.
230
+ const executable = `${process.execPath} ${binPath}`;
231
+ // THE INVARIANT: no worker stdio slot is ever a PARENT-OWNED PIPE. Once
232
+ // Shift exits, a detached worker may keep writing diagnostics, and a pipe
233
+ // whose reader has vanished kills the writer with EPIPE — losing the worker,
234
+ // not just its output.
235
+ //
236
+ // A FILE DESCRIPTOR IS NOT A PIPE, and slots 1 and 2 are now an appended
237
+ // file: it outlives the parent, needs no live reader, and cannot raise
238
+ // EPIPE. So the invariant holds unchanged while the bytes are kept.
239
+ //
240
+ // "Agent-run stderr is untrusted" also still holds, and still means what it
241
+ // always meant: worker output is never quoted back as a failure message.
242
+ // The bounded generic lifecycle message below is what a failure reports.
243
+ // Untrusted is a reason not to REPEAT those bytes, never a reason to
244
+ // discard them before an operator can read them — reading them is the whole
245
+ // point of `<run>.log`.
246
+ let failureReported = false;
247
+ const report = (exitStatus, signal, message) => {
248
+ if (failureReported || onFailure === undefined)
249
+ return;
250
+ failureReported = true;
251
+ onFailure({
252
+ workflow: spec.workflow,
253
+ run: spec.run,
254
+ ...(spec.step !== undefined ? { step: spec.step } : {}),
255
+ kind,
256
+ ...(harness !== undefined ? { harness } : {}),
257
+ executable,
258
+ exitStatus,
259
+ signal,
260
+ message,
261
+ });
262
+ };
263
+ child.once('error', () => report(null, null, 'worker process failed to start'));
264
+ child.once('exit', (code, signal) => {
265
+ if (code === 0)
266
+ return;
267
+ report(code, signal, 'worker exited without completing successfully');
268
+ });
93
269
  child.unref();
94
270
  if (child.pid === undefined) {
95
- const role = spec.kind === 'agent-run' ? 'agent-run' : 'exec';
96
- throw new Error(`spawn of 'owenloop work ${role} ${spec.workflow}/${spec.run}' returned no pid`);
271
+ // A synchronous spawn failure leaves no pid AND makes Node emit `error` on
272
+ // a later tick (verified on node v22: `pid` undefined, events `error` then
273
+ // `close`, no `exit`). The spawned COMMAND here is always
274
+ // `process.execPath`, never `binPath`, so the trigger is not a missing bin
275
+ // — it is resource exhaustion in the Shift itself (EMFILE from too many
276
+ // concurrent children, ENOMEM), which is exactly the condition a busy
277
+ // dispatcher hits. Throwing is what the caller sees, and
278
+ // `createShiftLoop.dispatchCandidate` already turns that throw into one
279
+ // `failed` event. Latch the reporter closed first, or the `error` handler
280
+ // registered above fires afterwards and emits a SECOND `failed` event —
281
+ // two daemon events for one dispatch attempt.
282
+ failureReported = true;
283
+ throw new Error(`spawn of 'owenloop work ${kind} ${spec.workflow}/${spec.run}' returned no pid`);
97
284
  }
98
- return { pid: child.pid };
285
+ const kill = () => {
286
+ try {
287
+ child.kill('SIGTERM');
288
+ }
289
+ catch {
290
+ // The child may already have exited after a cancelled or missing gate.
291
+ }
292
+ };
293
+ return {
294
+ pid: child.pid,
295
+ cancel: () => {
296
+ // Dispatcher-owned termination has its own authoritative failure event.
297
+ // Latch first so the resulting signal exit cannot report a second event.
298
+ failureReported = true;
299
+ kill();
300
+ },
301
+ terminate: kill,
302
+ };
99
303
  };
100
304
  }