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
@@ -52,6 +52,10 @@ export interface FailedEvent {
52
52
  run: string;
53
53
  step: string;
54
54
  kind: 'exec' | 'agent-run';
55
+ harness?: string;
56
+ executable?: string;
57
+ exitStatus?: number | null;
58
+ signal?: NodeJS.Signals | null;
55
59
  message: string;
56
60
  }
57
61
  /** Reserved for a future local representation of a pending hub gate. */
@@ -33,6 +33,8 @@ export interface ShiftRuntimeOptions {
33
33
  /** Socket path selected by the shift command. */
34
34
  socketPath?: string;
35
35
  }
36
+ /** Public Shift daemon transport is a Unix-domain socket on macOS and Linux. */
37
+ export declare function assertShiftDaemonPlatform(platform?: NodeJS.Platform): void;
36
38
  /**
37
39
  * Shared runtime setup for the internal shift and public shift daemon.
38
40
  * `parsed` is already grammar-validated by the caller; this function owns all
@@ -9,6 +9,7 @@
9
9
  import { randomUUID } from 'node:crypto';
10
10
  import { hostname } from 'node:os';
11
11
  import { basename, join } from 'node:path';
12
+ import { performance } from 'node:perf_hooks';
12
13
  import { createHubClient } from "../hub/client.js";
13
14
  import { resolveBearer } from "../credentials/resolve.js";
14
15
  import { loadSettings } from "../settings/settings.js";
@@ -20,6 +21,7 @@ import { reconcileActiveSessions, sessionsPath } from "../harness/session-store.
20
21
  import { resolveWorkRepo, resolveWorkRoot } from "../agent/workdir.js";
21
22
  import { installSignalHandlers } from "../roles/signals.js";
22
23
  import { createShiftDaemon } from "./server.js";
24
+ import { createBundleIngestor, createStoreInstructionSource, globalStoreRoot, } from "../../../../src/store/index.js";
23
25
  // Re-exported so existing importers keep their import site while the
24
26
  // implementation lives in the shared signals seam.
25
27
  export { installSignalHandlers };
@@ -136,6 +138,13 @@ function usage() {
136
138
  function errMsg(err) {
137
139
  return err instanceof Error ? err.message : String(err);
138
140
  }
141
+ /** Public Shift daemon transport is a Unix-domain socket on macOS and Linux. */
142
+ export function assertShiftDaemonPlatform(platform = process.platform) {
143
+ if (platform === 'win32') {
144
+ throw new Error('the public Shift daemon is not supported on Windows: Windows named-pipe transport is not implemented; ' +
145
+ 'use `owenloop work shift` directly');
146
+ }
147
+ }
139
148
  /**
140
149
  * Shared runtime setup for the internal shift and public shift daemon.
141
150
  * `parsed` is already grammar-validated by the caller; this function owns all
@@ -145,6 +154,15 @@ function errMsg(err) {
145
154
  export async function runShiftRuntime(parsed, options = {}) {
146
155
  const daemonMode = options.daemon === true;
147
156
  const roleLabel = options.role === 'shift' ? 'owenloop shift' : 'owenloop work shift';
157
+ if (daemonMode) {
158
+ try {
159
+ assertShiftDaemonPlatform();
160
+ }
161
+ catch (error) {
162
+ process.stderr.write(`${roleLabel}: ${errMsg(error)}\n`);
163
+ return 1;
164
+ }
165
+ }
148
166
  const env = process.env;
149
167
  let settings;
150
168
  try {
@@ -180,7 +198,13 @@ export async function runShiftRuntime(parsed, options = {}) {
180
198
  process.stderr.write(`${roleLabel}: ${errMsg(err)}\n`);
181
199
  return 1;
182
200
  }
183
- ensureStateDir(stateDir);
201
+ try {
202
+ ensureStateDir(stateDir);
203
+ }
204
+ catch (err) {
205
+ process.stderr.write(`${roleLabel}: cannot initialize dispatch state at ${stateDir}: ${errMsg(err)}\n`);
206
+ return 1;
207
+ }
184
208
  {
185
209
  const liveRunIds = new Set(reconcileInFlight(stateDir).live.filter((r) => r.kind === 'agent-run').map((r) => r.run));
186
210
  try {
@@ -201,17 +225,55 @@ export async function runShiftRuntime(parsed, options = {}) {
201
225
  const workRepo = resolveWorkRepo(env, settings.workRepo);
202
226
  const hub = createHubClient({ origin, getToken: async () => token });
203
227
  const now = () => Date.now();
228
+ const monotonicNow = () => performance.now();
229
+ const home = [env.HOME, env.USERPROFILE].find((value) => value !== undefined && value.trim() !== '');
230
+ // Legacy orders and modern agent orders do not need Shift-side instruction
231
+ // lookup. Keep serving those lanes without a home directory; a modern command
232
+ // order still fails closed because its exact digest cannot be resolved.
233
+ const instructionSource = home === undefined
234
+ ? undefined
235
+ : createStoreInstructionSource({
236
+ projectRoot: join(process.cwd(), 'workflows'),
237
+ globalRoot: globalStoreRoot(home),
238
+ verifier: createBundleIngestor(),
239
+ });
240
+ const resolveOrderStep = async (order) => {
241
+ if (instructionSource === undefined ||
242
+ order.defDigest === undefined ||
243
+ order.defDigest.trim() === '')
244
+ return undefined;
245
+ if (await instructionSource.prime(order.defDigest) !== 'resolved')
246
+ return undefined;
247
+ return instructionSource.getVerifiedStep(order.defDigest, order.step);
248
+ };
204
249
  const shiftId = `shf_${randomUUID()}`;
205
250
  const startedAt = now();
206
251
  const name = resolveShiftName(parsed.name, { shiftId });
207
- const spawner = createDefaultSpawner(origin, account, undefined, shiftId);
208
- const pollIntervalMs = parsed.pollIntervalMs ?? DEFAULT_POLL_MS;
209
252
  let daemon;
253
+ const reportWorkerFailure = (failure) => {
254
+ const event = {
255
+ type: 'failed',
256
+ workflow: failure.workflow,
257
+ run: failure.run,
258
+ step: failure.step ?? '(unknown)',
259
+ kind: failure.kind,
260
+ ...(failure.harness !== undefined ? { harness: failure.harness } : {}),
261
+ executable: failure.executable,
262
+ exitStatus: failure.exitStatus,
263
+ signal: failure.signal,
264
+ message: failure.message,
265
+ };
266
+ daemon?.onEvent(event);
267
+ process.stderr.write(`${roleLabel}: worker failure ${JSON.stringify(event)}\n`);
268
+ };
269
+ const spawner = createDefaultSpawner(origin, account, undefined, shiftId, reportWorkerFailure);
270
+ const pollIntervalMs = parsed.pollIntervalMs ?? DEFAULT_POLL_MS;
210
271
  const loop = createShiftLoop({
211
272
  hub,
212
273
  spawner,
213
274
  sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
214
275
  now,
276
+ monotonicNow,
215
277
  out: (line) => process.stdout.write(`${line}\n`),
216
278
  err: (line) => process.stderr.write(`${line}\n`),
217
279
  ...(daemonMode ? { onEvent: (event) => daemon?.onEvent(event) } : {}),
@@ -221,6 +283,7 @@ export async function runShiftRuntime(parsed, options = {}) {
221
283
  serveCrews: parsed.serveCrews ?? [],
222
284
  name,
223
285
  commandRouting: settings.commandRouting,
286
+ resolveOrderStep,
224
287
  pollIntervalMs,
225
288
  presenceIntervalMs: DEFAULT_PRESENCE_MS,
226
289
  maxConcurrentAgents,
@@ -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,53 @@ 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.
25
27
  */
26
28
  harness?: string;
29
+ /** Closed start gate created by the durable Shift reservation. */
30
+ startGate?: string;
27
31
  }
28
- /** The result the loop records: the child's pid. */
32
+ /** The result the loop records plus best-effort pre-start cancellation handles. */
29
33
  export interface SpawnResult {
30
34
  pid: number;
35
+ /**
36
+ * Dispatcher-owned cancellation. The default spawner disarms spontaneous
37
+ * lifecycle reporting before sending SIGTERM, so one failed dispatch emits
38
+ * one Shift failure event.
39
+ */
40
+ cancel?: () => void;
41
+ /** Legacy injected-spawner compatibility. New dispatcher code prefers cancel. */
42
+ terminate?: () => void;
31
43
  }
32
44
  /** The spawn seam. Injected; faked in tests. */
33
45
  export type Spawner = (spec: SpawnSpec) => SpawnResult;
46
+ /** Safe, bounded metadata emitted when a detached worker fails. Detached
47
+ * worker stderr is not attached to Shift: agent-run output is untrusted, and a
48
+ * parent-owned pipe can kill either worker with EPIPE after Shift exits. */
49
+ export interface WorkerFailure {
50
+ workflow: string;
51
+ run: string;
52
+ step?: string;
53
+ kind: 'exec' | 'agent-run';
54
+ harness?: string;
55
+ executable: string;
56
+ exitStatus: number | null;
57
+ signal: NodeJS.Signals | null;
58
+ message: string;
59
+ }
60
+ export type WorkerFailureReporter = (failure: WorkerFailure) => void;
34
61
  /** The fully-resolved spawn arguments — pure data, asserted directly in tests. */
35
62
  export interface SpawnPlan {
36
63
  command: string;
37
64
  args: string[];
38
65
  options: {
39
66
  detached: true;
40
- stdio: 'ignore';
67
+ stdio: ['ignore', 'ignore', 'ignore'];
41
68
  env: NodeJS.ProcessEnv;
42
69
  };
43
70
  }
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
71
  /**
54
72
  * Build the argv + options for a detached
55
73
  * `owenloop work exec <workflow>/<run> --origin <url>`. Pure — no spawn, no I/O — so
@@ -68,11 +86,16 @@ export declare function resolveOwenloopBin(): string;
68
86
  * (advisory only, D8/INV-82). Omitted/empty carries no flag at all.
69
87
  *
70
88
  * 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
89
+ * selects the role positional (`exec` vs `agent-run`). Everything else — the
73
90
  * composite order positional, `--origin`, `--shift`, and every spawn option
74
91
  * — is identical for both kinds, so an agent-run child is detached,
75
92
  * stdio-ignored, and account-scoped exactly like an exec child.
93
+ *
94
+ * The Shift never emits `--harness`. A prepared-cache step is dispatch metadata,
95
+ * not an operator override; the `agent-run` child resolves its authoritative
96
+ * inputs in precedence order (`--harness`, `OWENLOOP_HARNESS`, verified runtime
97
+ * step, registered default). The Shift command has no operator-facing harness
98
+ * flag, so there is no legitimate CLI override for this seam to carry.
76
99
  */
77
100
  export declare function buildSpawnPlan(spec: SpawnSpec, origin: string, account: string, binPath: string, execPath?: string, shiftId?: string): SpawnPlan;
78
101
  /**
@@ -83,4 +106,4 @@ export declare function buildSpawnPlan(spec: SpawnSpec, origin: string, account:
83
106
  * relying on `buildSpawnPlan`'s default) so `shiftId` — trailing after it
84
107
  * — can be supplied positionally.
85
108
  */
86
- export declare function createDefaultSpawner(origin: string, account: string, binPath?: string, shiftId?: string): Spawner;
109
+ export declare function createDefaultSpawner(origin: string, account: string, binPath?: string, shiftId?: string, onFailure?: WorkerFailureReporter): Spawner;
@@ -3,7 +3,7 @@
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
+ * all stdio ignored, `unref()` — so the child is its own process-group leader and
7
7
  * survives the parent's death (SP5-verified kernel reparenting). The shift meters
8
8
  * and hands off; the child self-leases (C5). Both ids ride the argv as the
9
9
  * composite `<workflow>/<run>` order-id `owenloop work exec` parses, and `--origin`
@@ -13,28 +13,13 @@
13
13
  * env is the contract), selecting which Scoped Identity credential slot
14
14
  * (agent:<account>) exec reads.
15
15
  *
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.
16
+ * `Spawner` is an injected seam; most loop tests fake it. The default impl's
17
+ * argv/option construction is factored into the pure `buildSpawnPlan`, while a
18
+ * focused lifecycle regression uses harmless local children.
19
19
  */
20
- import { existsSync } from 'node:fs';
21
20
  import { spawn } from 'node:child_process';
22
- import { fileURLToPath } from 'node:url';
23
- /**
24
- * Resolve the single packaged `bin/owenloop.mjs` from this module's URL.
25
- *
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
- */
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];
37
- }
21
+ import { resolveOwenloopBin } from "../owenloop-bin.js";
22
+ export { resolveOwenloopBin } from "../owenloop-bin.js";
38
23
  /**
39
24
  * Build the argv + options for a detached
40
25
  * `owenloop work exec <workflow>/<run> --origin <url>`. Pure — no spawn, no I/O — so
@@ -53,11 +38,16 @@ export function resolveOwenloopBin() {
53
38
  * (advisory only, D8/INV-82). Omitted/empty carries no flag at all.
54
39
  *
55
40
  * 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
41
+ * selects the role positional (`exec` vs `agent-run`). Everything else — the
58
42
  * composite order positional, `--origin`, `--shift`, and every spawn option
59
43
  * — is identical for both kinds, so an agent-run child is detached,
60
44
  * stdio-ignored, and account-scoped exactly like an exec child.
45
+ *
46
+ * The Shift never emits `--harness`. A prepared-cache step is dispatch metadata,
47
+ * not an operator override; the `agent-run` child resolves its authoritative
48
+ * inputs in precedence order (`--harness`, `OWENLOOP_HARNESS`, verified runtime
49
+ * step, registered default). The Shift command has no operator-facing harness
50
+ * flag, so there is no legitimate CLI override for this seam to carry.
61
51
  */
62
52
  export function buildSpawnPlan(spec, origin, account, binPath, execPath = process.execPath, shiftId) {
63
53
  const role = spec.kind === 'agent-run' ? 'agent-run' : 'exec';
@@ -71,11 +61,16 @@ export function buildSpawnPlan(spec, origin, account, binPath, execPath = proces
71
61
  '--origin',
72
62
  origin,
73
63
  ...(shiftId !== undefined && shiftId !== '' ? ['--shift', shiftId] : []),
74
- ...(role === 'agent-run' && spec.harness !== undefined && spec.harness !== ''
75
- ? ['--harness', spec.harness]
76
- : []),
77
64
  ],
78
- options: { detached: true, stdio: 'ignore', env: { ...process.env, OWENLOOP_ACCOUNT: account } },
65
+ options: {
66
+ detached: true,
67
+ stdio: ['ignore', 'ignore', 'ignore'],
68
+ env: {
69
+ ...process.env,
70
+ OWENLOOP_ACCOUNT: account,
71
+ ...(spec.startGate !== undefined ? { OWENLOOP_START_GATE: spec.startGate } : {}),
72
+ },
73
+ },
79
74
  };
80
75
  }
81
76
  /**
@@ -86,15 +81,78 @@ export function buildSpawnPlan(spec, origin, account, binPath, execPath = proces
86
81
  * relying on `buildSpawnPlan`'s default) so `shiftId` — trailing after it
87
82
  * — can be supplied positionally.
88
83
  */
89
- export function createDefaultSpawner(origin, account, binPath = resolveOwenloopBin(), shiftId) {
84
+ export function createDefaultSpawner(origin, account, binPath = resolveOwenloopBin(), shiftId, onFailure) {
90
85
  return (spec) => {
91
86
  const plan = buildSpawnPlan(spec, origin, account, binPath, process.execPath, shiftId);
92
87
  const child = spawn(plan.command, plan.args, plan.options);
88
+ const kind = spec.kind === 'agent-run' ? 'agent-run' : 'exec';
89
+ const harness = kind === 'agent-run'
90
+ ? (spec.harness ?? process.env['OWENLOOP_HARNESS'] ?? 'auto')
91
+ : undefined;
92
+ // This process is the executable Shift actually launched. The harness may
93
+ // start its own vendor process later, but reporting or guessing that
94
+ // executable here would couple the neutral dispatcher to one adapter.
95
+ const executable = `${process.execPath} ${binPath}`;
96
+ // No worker stdio slot is a parent-owned pipe. Once Shift exits, a detached
97
+ // worker may keep writing diagnostics without receiving EPIPE from a vanished
98
+ // reader. Agent-run stderr is untrusted; exec failures therefore use the same
99
+ // bounded generic lifecycle message rather than capturing worker output.
100
+ let failureReported = false;
101
+ const report = (exitStatus, signal, message) => {
102
+ if (failureReported || onFailure === undefined)
103
+ return;
104
+ failureReported = true;
105
+ onFailure({
106
+ workflow: spec.workflow,
107
+ run: spec.run,
108
+ ...(spec.step !== undefined ? { step: spec.step } : {}),
109
+ kind,
110
+ ...(harness !== undefined ? { harness } : {}),
111
+ executable,
112
+ exitStatus,
113
+ signal,
114
+ message,
115
+ });
116
+ };
117
+ child.once('error', () => report(null, null, 'worker process failed to start'));
118
+ child.once('exit', (code, signal) => {
119
+ if (code === 0)
120
+ return;
121
+ report(code, signal, 'worker exited without completing successfully');
122
+ });
93
123
  child.unref();
94
124
  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`);
125
+ // A synchronous spawn failure leaves no pid AND makes Node emit `error` on
126
+ // a later tick (verified on node v22: `pid` undefined, events `error` then
127
+ // `close`, no `exit`). The spawned COMMAND here is always
128
+ // `process.execPath`, never `binPath`, so the trigger is not a missing bin
129
+ // — it is resource exhaustion in the Shift itself (EMFILE from too many
130
+ // concurrent children, ENOMEM), which is exactly the condition a busy
131
+ // dispatcher hits. Throwing is what the caller sees, and
132
+ // `createShiftLoop.dispatchCandidate` already turns that throw into one
133
+ // `failed` event. Latch the reporter closed first, or the `error` handler
134
+ // registered above fires afterwards and emits a SECOND `failed` event —
135
+ // two daemon events for one dispatch attempt.
136
+ failureReported = true;
137
+ throw new Error(`spawn of 'owenloop work ${kind} ${spec.workflow}/${spec.run}' returned no pid`);
97
138
  }
98
- return { pid: child.pid };
139
+ const kill = () => {
140
+ try {
141
+ child.kill('SIGTERM');
142
+ }
143
+ catch {
144
+ // The child may already have exited after a cancelled or missing gate.
145
+ }
146
+ };
147
+ return {
148
+ pid: child.pid,
149
+ cancel: () => {
150
+ // Dispatcher-owned termination has its own authoritative failure event.
151
+ // Latch first so the resulting signal exit cannot report a second event.
152
+ failureReported = true;
153
+ kill();
154
+ },
155
+ terminate: kill,
156
+ };
99
157
  };
100
158
  }
@@ -1,77 +1,79 @@
1
- /** One dispatched order the shift meters against capacity.
2
- *
3
- * Two kinds, and BOTH are real local processes tracked by a live pid:
4
- * - `exec` (default; absent `kind` for legacy records) — a detached
5
- * `owenloop work exec` command child, tracked by `kill(pid, 0)`.
6
- * - `agent-run` — a detached `owenloop work agent-run` child hosting the step
7
- * agent itself, tracked exactly the same way.
8
- *
9
- * There is no pid-less kind any more. The removed `'agent'` kind recorded a
10
- * stamped Step Agent file handed to an out-of-process Shift: no local
11
- * child, a `0` sentinel pid, and a coarse TTL standing in for liveness. With
12
- * the stamp path gone nothing produces such a record, so a leftover one on disk
13
- * fails the pid probe and is reaped on the next reconcile — which is correct.
14
- *
15
- * `def/hash/step` are dispatch provenance (which cached def revision and step
16
- * this child was dispatched for); they are absent for command orders. */
1
+ export declare const DEFAULT_RESERVATION_MAX_AGE_MS: number;
17
2
  export interface ChildRecord {
18
3
  workflow: string;
19
4
  run: string;
20
- /** The child's live pid. */
21
5
  pid: number;
22
6
  spawnedAt: number;
23
- /** Dispatch kind; absent = `'exec'` (back-compat with pre-split records). */
7
+ /** Dispatch kind; absent = `'exec'` for backward compatibility. */
24
8
  kind?: 'exec' | 'agent-run';
25
9
  def?: string;
26
10
  hash?: string;
27
11
  step?: string;
12
+ /** Present only between PID persistence and opening the child's start gate. */
13
+ gateToken?: string;
14
+ }
15
+ export interface ChildReservation {
16
+ recordType: 'reservation';
17
+ workflow: string;
18
+ run: string;
19
+ reservedAt: number;
20
+ token: string;
21
+ childKind: 'exec' | 'agent-run';
22
+ step?: string;
23
+ }
24
+ export interface ReservationRequest {
25
+ workflow: string;
26
+ run: string;
27
+ reservedAt: number;
28
+ childKind: 'exec' | 'agent-run';
29
+ step?: string;
30
+ }
31
+ export interface ReservedChild {
32
+ reservation: ChildReservation;
33
+ gatePath: string;
28
34
  }
29
- /**
30
- * Resolve the state dir: `override` → `$XDG_STATE_HOME/owenloop/exec` →
31
- * `$HOME/.local/state/owenloop/exec`. Throws when none is available (same
32
- * stance as the cache/settings resolvers — never guess a home dir). Tests pass
33
- * an explicit `override` pointing at a temp dir.
34
- */
35
35
  export declare function resolveStateDir(env: Record<string, string | undefined>, override?: string): string;
36
- /** Persist a child record (atomic temp+rename). Fail-open. */
37
- export declare function writeChildRecord(stateDir: string, rec: ChildRecord): void;
38
- /** Read every child record in the state dir. Corrupt files are skipped, a
39
- * missing dir reads as empty. Fail-open. */
36
+ /** Persist a child record atomically. State persistence is correctness-sensitive and throws on failure. */
37
+ export declare function writeChildRecord(stateDir: string, record: ChildRecord): void;
38
+ /** Create the durable capacity reservation and closed start gate before spawn. */
39
+ export declare function reserveChild(stateDir: string, request: ReservationRequest): ReservedChild;
40
+ export declare class ShiftStateRecordError extends Error {
41
+ readonly path: string;
42
+ constructor(path: string, detail: string);
43
+ }
44
+ /** Read only PID-bearing records for status and compatibility callers. */
40
45
  export declare function readChildRecords(stateDir: string): ChildRecord[];
41
- /** Delete a child record by run id. Fail-open. */
42
- export declare function removeChildRecord(stateDir: string, run: string): void;
43
- /** A liveness probe over a pid. Injectable so tests never touch real pids. */
44
- export type Liveness = (pid: number) => boolean;
46
+ export declare function readChildReservations(stateDir: string): ChildReservation[];
47
+ /** Replace the matching reservation with a PID-bearing record before work starts. */
48
+ export declare function finalizeChildReservation(stateDir: string, reservation: ChildReservation, child: Omit<ChildRecord, 'workflow' | 'run' | 'gateToken'>): ChildRecord;
49
+ /** Open a child's gate only after the PID-bearing record is durable. */
50
+ export declare function startReservedChild(stateDir: string, record: ChildRecord): void;
51
+ /** Cancel a gated child and remove the matching reservation/record. */
52
+ export declare function cancelReservedChild(stateDir: string, reservation: ChildReservation): void;
45
53
  /**
46
- * Default liveness probe: `process.kill(pid, 0)` sends no signal, only checks
47
- * existence/permissions. `ESRCH` ⇒ the process is gone (dead). `EPERM` ⇒ it
48
- * exists but is owned by another user (count as alive — pid reuse aside, a live
49
- * foreign process at that pid is not ours to reap). Any other error ⇒ alive
50
- * (conservative: don't reap on an ambiguous signal).
54
+ * Delete one run's in-flight state. A still-gated reservation or finalized child
55
+ * is cancelled first so an external run-ended signal cannot leave a worker gate
56
+ * behind that later opens without a capacity record.
51
57
  */
58
+ export declare function removeChildRecord(stateDir: string, run: string): void;
59
+ export type Liveness = (pid: number) => boolean;
52
60
  export declare const defaultIsAlive: Liveness;
53
61
  export interface Reconciliation {
54
- /** Records whose child is still alive — these count as in-flight. */
55
62
  live: ChildRecord[];
56
- /** Records whose child is gone — reaped (record deleted) this pass. */
63
+ reserved: ChildReservation[];
57
64
  reaped: ChildRecord[];
65
+ abandoned: ChildReservation[];
58
66
  }
59
- /** Injectable knobs for `reconcileInFlight` (all optional; real defaults). */
60
67
  export interface ReconcileOptions {
61
- /** pid liveness probe (default `defaultIsAlive`). */
62
68
  isAlive?: Liveness;
69
+ now?: number;
70
+ reservationMaxAgeMs?: number;
63
71
  }
64
72
  /**
65
- * Scan the state dir, decide each record's liveness, delete the dead ones, and
66
- * return the live/reaped split. Deduped by run id (last record for a run wins)
67
- * so a stray double-write can never double-count capacity.
68
- *
69
- * Liveness is UNIFORM: every record names a real local child, so every record
70
- * is live exactly while `kill(pid, 0)` says its pid is.
71
- *
72
- * Back-compat: the second positional arg still accepts a bare `Liveness`
73
- * (pre-split callers passed `reconcileInFlight(dir, isAlive)`).
73
+ * Reconcile live children and durable reservations. Fresh reservations count as
74
+ * occupied capacity. An expired reservation is cancelled before its record is
75
+ * removed, so a child that was spawned but never finalized cannot begin work.
74
76
  */
75
77
  export declare function reconcileInFlight(stateDir: string, arg?: Liveness | ReconcileOptions): Reconciliation;
76
- /** Ensure the state dir exists so the first read doesn't churn. Fail-open. */
78
+ /** Ensure the state directory exists and is readable. Failure is fatal to dispatch safety. */
77
79
  export declare function ensureStateDir(stateDir: string): void;