owenloop 0.5.9 → 0.5.10

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 (83) hide show
  1. package/CHANGELOG.md +44 -0
  2. package/README.md +77 -37
  3. package/bin/owenloop.mjs +16 -1
  4. package/dist/packages/work/src/agent/loop.js +7 -0
  5. package/dist/packages/work/src/bundle/pull.d.ts +21 -0
  6. package/dist/packages/work/src/bundle/pull.js +118 -0
  7. package/dist/packages/work/src/exec/instructions.d.ts +4 -1
  8. package/dist/packages/work/src/exec/instructions.js +3 -0
  9. package/dist/packages/work/src/exec/loop.d.ts +1 -1
  10. package/dist/packages/work/src/exec/loop.js +92 -14
  11. package/dist/packages/work/src/harness/claude.js +16 -0
  12. package/dist/packages/work/src/harness/codex.d.ts +8 -0
  13. package/dist/packages/work/src/harness/codex.js +27 -1
  14. package/dist/packages/work/src/harness/contract.d.ts +9 -0
  15. package/dist/packages/work/src/roles/agent-run.js +38 -10
  16. package/dist/packages/work/src/roles/exec.js +25 -8
  17. package/dist/packages/work/src/shift/loop.js +118 -4
  18. package/dist/packages/work/src/shift/runtime.d.ts +3 -0
  19. package/dist/packages/work/src/shift/runtime.js +10 -1
  20. package/dist/packages/work/src/submit-proof.d.ts +11 -8
  21. package/dist/packages/work/src/submit-proof.js +11 -8
  22. package/dist/src/capabilities.d.ts +70 -6
  23. package/dist/src/capabilities.js +49 -6
  24. package/dist/src/capability-mapping-client.d.ts +29 -0
  25. package/dist/src/capability-mapping-client.js +160 -0
  26. package/dist/src/cli.d.ts +2 -2
  27. package/dist/src/cli.js +1196 -164
  28. package/dist/src/defs.d.ts +32 -1
  29. package/dist/src/defs.js +391 -79
  30. package/dist/src/engine.d.ts +62 -19
  31. package/dist/src/engine.js +180 -70
  32. package/dist/src/hub.d.ts +77 -0
  33. package/dist/src/hub.js +162 -0
  34. package/dist/src/implements.d.ts +56 -0
  35. package/dist/src/implements.js +790 -0
  36. package/dist/src/index.d.ts +8 -6
  37. package/dist/src/index.js +4 -3
  38. package/dist/src/mcp/serve.js +254 -45
  39. package/dist/src/mcp/server.d.ts +10 -7
  40. package/dist/src/mcp/server.js +53 -8
  41. package/dist/src/model.d.ts +46 -10
  42. package/dist/src/model.js +220 -74
  43. package/dist/src/store/def-source.d.ts +19 -0
  44. package/dist/src/store/def-source.js +87 -17
  45. package/dist/src/store/gc-recovery.d.ts +46 -0
  46. package/dist/src/store/gc-recovery.js +258 -0
  47. package/dist/src/store/gc.d.ts +94 -0
  48. package/dist/src/store/gc.js +562 -0
  49. package/dist/src/store/index.d.ts +3 -1
  50. package/dist/src/store/index.js +2 -0
  51. package/dist/src/store/install.d.ts +34 -5
  52. package/dist/src/store/install.js +73 -11
  53. package/dist/src/store/pre-commit-verifier.js +42 -2
  54. package/dist/src/store/snapshot-guard.d.ts +18 -0
  55. package/dist/src/store/snapshot-guard.js +94 -0
  56. package/dist/src/store.d.ts +64 -4
  57. package/dist/src/store.js +211 -8
  58. package/dist/src/types.d.ts +61 -17
  59. package/dist/src/util.js +4 -1
  60. package/docs/authoring.md +145 -8
  61. package/docs/bundles.md +19 -0
  62. package/docs/cli.md +270 -30
  63. package/docs/crypto.md +13 -7
  64. package/docs/design.md +107 -46
  65. package/docs/evals/mcp-charter-baseline.json +428 -0
  66. package/docs/mcp-charter-eval.md +124 -0
  67. package/docs/shift-logs.md +18 -0
  68. package/docs/wire-contracts.md +28 -7
  69. package/examples/workflows/compile-dev-playbook.yaml +1 -1
  70. package/examples/workflows/ship.yaml +28 -2
  71. package/package.json +2 -1
  72. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
  73. package/plugins/claude-code/plugin/.mcp.json +1 -1
  74. package/plugins/claude-code/plugin/skills/author/SKILL.md +22 -0
  75. package/plugins/claude-code/plugin/skills/ephemeral/SKILL.md +95 -0
  76. package/plugins/claude-code/plugin/skills/graduate/SKILL.md +156 -0
  77. package/plugins/claude-code/plugin/skills/plan/SKILL.md +236 -0
  78. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
  79. package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
  80. package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +22 -0
  81. package/plugins/codex/plugins/owenloop/skills/ephemeral/SKILL.md +95 -0
  82. package/plugins/codex/plugins/owenloop/skills/graduate/SKILL.md +156 -0
  83. package/plugins/codex/plugins/owenloop/skills/plan/SKILL.md +236 -0
@@ -768,6 +768,18 @@ function emitAssistant(message, onEvent) {
768
768
  }
769
769
  }
770
770
  }
771
+ /** The reply a user would see from one top-level assistant message. This is
772
+ * deliberately separate from `emitAssistant`: that function is operational
773
+ * telemetry, while this value is emitted once at turn end as response evidence. */
774
+ function assistantResponse(message) {
775
+ if (message.parent_tool_use_id !== null)
776
+ return undefined;
777
+ const text = message.message.content
778
+ .filter((block) => block.type === 'text')
779
+ .map((block) => block.text)
780
+ .join('\n');
781
+ return text === '' ? undefined : text;
782
+ }
771
783
  /** One progress line per content block of a user message — which on this path
772
784
  * means tool results coming back, plus any synthetic user text.
773
785
  *
@@ -821,6 +833,7 @@ function emitUser(message, onEvent) {
821
833
  */
822
834
  export async function consumeTurn(q, onEvent, onInit, expectedSessionId) {
823
835
  let sessionId;
836
+ let finalResponse;
824
837
  for await (const message of q) {
825
838
  if (message.type === 'system' && message.subtype === 'init') {
826
839
  if (expectedSessionId !== undefined && message.session_id !== expectedSessionId) {
@@ -840,6 +853,8 @@ export async function consumeTurn(q, onEvent, onInit, expectedSessionId) {
840
853
  onInit?.(sessionId);
841
854
  }
842
855
  else if (message.type === 'result') {
856
+ if (finalResponse !== undefined)
857
+ onEvent({ kind: 'assistant_response', text: finalResponse });
843
858
  if (message.subtype !== 'success') {
844
859
  // The contract's channel for "something went wrong that is not a resume
845
860
  // failure". Emitted BEFORE turn_ended so a caller reading events in
@@ -855,6 +870,7 @@ export async function consumeTurn(q, onEvent, onInit, expectedSessionId) {
855
870
  }
856
871
  else if (message.type === 'assistant') {
857
872
  emitAssistant(message, onEvent);
873
+ finalResponse = assistantResponse(message) ?? finalResponse;
858
874
  }
859
875
  else if (message.type === 'user') {
860
876
  emitUser(message, onEvent);
@@ -87,6 +87,14 @@ export interface TurnOutcome {
87
87
  * Returns `undefined` for anything that is not a `turn/completed`.
88
88
  */
89
89
  export declare function readTurnCompleted(method: string, params: unknown): TurnOutcome | undefined;
90
+ /**
91
+ * Read the final user-visible assistant reply from an app-server notification.
92
+ *
93
+ * Deltas are deliberately not used: they are incomplete transport fragments and
94
+ * can coexist with reasoning, tool output, and other intermediate telemetry.
95
+ * The completed `agentMessage` is the app-server's assembled final answer.
96
+ */
97
+ export declare function readFinalAssistantResponse(method: string, params: unknown): string | undefined;
90
98
  /**
91
99
  * Map one server→client notification to an `AgentEvent`.
92
100
  *
@@ -496,6 +496,24 @@ export function readTurnCompleted(method, params) {
496
496
  : `${message} (${details})`,
497
497
  };
498
498
  }
499
+ /**
500
+ * Read the final user-visible assistant reply from an app-server notification.
501
+ *
502
+ * Deltas are deliberately not used: they are incomplete transport fragments and
503
+ * can coexist with reasoning, tool output, and other intermediate telemetry.
504
+ * The completed `agentMessage` is the app-server's assembled final answer.
505
+ */
506
+ export function readFinalAssistantResponse(method, params) {
507
+ if (method !== 'item/completed')
508
+ return undefined;
509
+ const item = asMap(asMap(params)['item']);
510
+ if ((str(item['type']) ?? str(item['itemType'])) !== 'agentMessage')
511
+ return undefined;
512
+ if (str(item['phase']) !== 'final_answer')
513
+ return undefined;
514
+ const text = str(item['text']);
515
+ return text === undefined || text === '' ? undefined : text;
516
+ }
499
517
  /**
500
518
  * Map one server→client notification to an `AgentEvent`.
501
519
  *
@@ -649,6 +667,9 @@ function createTurnGate(onEvent) {
649
667
  const event = mapNotification(method, params);
650
668
  if (event !== undefined)
651
669
  onEvent(event);
670
+ const finalResponse = readFinalAssistantResponse(method, params);
671
+ if (finalResponse !== undefined)
672
+ onEvent({ kind: 'assistant_response', text: finalResponse });
652
673
  if (mounted !== undefined) {
653
674
  // A silent dead order otherwise: with no `submit` tool the agent can
654
675
  // never complete the order, so burning the turn's tokens is pointless.
@@ -1078,12 +1099,17 @@ export const codexAdapter = {
1078
1099
  // there. Nothing is spawned and unowned by the time this rejects.
1079
1100
  const { client, reportExit } = await openClient(args.cwd, onEvent, gate, args.approvals);
1080
1101
  let threadId;
1102
+ let reportedModel;
1081
1103
  try {
1082
1104
  const res = await client.request('thread/start', startParams, SETUP_TIMEOUT_MS);
1083
1105
  const id = str(asMap(res['thread'])['id']);
1084
1106
  if (id === undefined)
1085
1107
  throw new Error('thread/start returned no thread id');
1086
1108
  threadId = id;
1109
+ // The app-server resolves an omitted model to the actual session model in
1110
+ // this response. Surface it with the durable session reference so callers
1111
+ // can attribute measurements without scraping persisted Codex state.
1112
+ reportedModel = str(res['model']);
1087
1113
  }
1088
1114
  catch (err) {
1089
1115
  // No token exists yet, so there is nothing to hand back and nothing to
@@ -1099,7 +1125,7 @@ export const codexAdapter = {
1099
1125
  SESSIONS.set(threadId, session);
1100
1126
  // BEFORE the turn runs and before resolving: the caller persists the token
1101
1127
  // on this event, so a mid-turn crash still leaves a resumable record.
1102
- onEvent({ kind: 'started', ref });
1128
+ onEvent({ kind: 'started', ref, ...(reportedModel === undefined ? {} : { model: reportedModel }) });
1103
1129
  try {
1104
1130
  await runTurn(client, gate, buildTurnStartParams(threadId, args.brief, args.effort ?? args.permissions.effort));
1105
1131
  }
@@ -56,12 +56,21 @@ export interface HarnessSessionRef {
56
56
  export type AgentEvent = {
57
57
  kind: 'started';
58
58
  ref: HarnessSessionRef;
59
+ /** Provider-selected model when the session-start response exposes it. */
60
+ model?: string;
59
61
  }
60
62
  /** Optional log line. Adapters may emit none; nothing may depend on it. */
61
63
  | {
62
64
  kind: 'progress';
63
65
  text: string;
64
66
  }
67
+ /** The completed top-level assistant reply, assembled by the owning adapter.
68
+ * Unlike `progress`, this is suitable for a caller that explicitly needs the
69
+ * final response rather than transport, tool, reasoning, or stderr telemetry. */
70
+ | {
71
+ kind: 'assistant_response';
72
+ text: string;
73
+ }
65
74
  /** The harness surfaced a blocking question. Phase 1 defines the EVENT only —
66
75
  * this contract has no reply channel, and adding one is Phase 3/4's call. */
67
76
  | {
@@ -85,9 +85,11 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
85
85
  import "../harnesses.js";
86
86
  // ─────────────────────────────────────────────────────────────────────────────
87
87
  import { hostname } from 'node:os';
88
+ import { join } from 'node:path';
88
89
  import { resolveCacheDir } from "../bundle/cache.js";
89
90
  import { createAgentRunLoop, } from "../agent/loop.js";
90
91
  import { createDefaultStoreInstructionResolver } from "../exec/instructions.js";
92
+ import { createHubBundleRecoveryHandler } from "../bundle/pull.js";
91
93
  import { createConsumedVerifier } from "../consumed-verifier.js";
92
94
  import { createHubClient } from "../hub/client.js";
93
95
  import { resolveBearer } from "../credentials/resolve.js";
@@ -277,15 +279,6 @@ export async function run(args, deps = {}) {
277
279
  });
278
280
  const instructionCwd = deps.cwd ?? process.cwd();
279
281
  let instructions = deps.instructions;
280
- if (instructions === undefined) {
281
- try {
282
- instructions = createDefaultStoreInstructionResolver({ cwd: instructionCwd, env, consumedVerifier });
283
- }
284
- catch (e) {
285
- err(`owenloop work agent-run: instruction store unavailable: ${errMsg(e)}`);
286
- return 1;
287
- }
288
- }
289
282
  let cacheDir;
290
283
  try {
291
284
  cacheDir = resolveCacheDir(env, settings.cacheDir);
@@ -335,13 +328,48 @@ export async function run(args, deps = {}) {
335
328
  return { ok: true, rosters };
336
329
  };
337
330
  let hub = deps.hub;
331
+ let token;
332
+ // An injected HubClient is already the embedding boundary's authenticated
333
+ // transport. Keep that seam credential-free even when it asks us to build
334
+ // the ordinary local resolver; authenticated recovery is attached only when
335
+ // this role owns the production hub client and its scoped bearer.
338
336
  if (hub === undefined) {
339
337
  const bearer = await resolveBearer({ origin, account, env: workerEnv });
340
338
  if (!bearer.ok) {
341
339
  err(`owenloop work agent-run: ${bearer.message}`);
342
340
  return bearer.code;
343
341
  }
344
- const token = bearer.token;
342
+ token = bearer.token;
343
+ }
344
+ if (instructions === undefined) {
345
+ try {
346
+ const home = [workerEnv.HOME, workerEnv.USERPROFILE].find((value) => value !== undefined && value.trim() !== '');
347
+ if (home === undefined)
348
+ throw new Error('cannot locate the global workflow store: set HOME or USERPROFILE');
349
+ instructions = createDefaultStoreInstructionResolver({
350
+ cwd: instructionCwd,
351
+ env: workerEnv,
352
+ consumedVerifier,
353
+ ...(token === undefined
354
+ ? {}
355
+ : {
356
+ onMissing: createHubBundleRecoveryHandler({
357
+ origin,
358
+ token,
359
+ home,
360
+ projectRoot: join(instructionCwd, 'workflows'),
361
+ env: workerEnv,
362
+ warn: (line) => err(`owenloop work agent-run: ${line}`),
363
+ }),
364
+ }),
365
+ });
366
+ }
367
+ catch (e) {
368
+ err(`owenloop work agent-run: instruction store unavailable: ${errMsg(e)}`);
369
+ return 1;
370
+ }
371
+ }
372
+ if (hub === undefined) {
345
373
  hub = createHubClient({ origin, getToken: async () => token });
346
374
  }
347
375
  const client = hub;
@@ -32,12 +32,14 @@
32
32
  * is the contract. Exit codes are documented in `src/usage.ts`.
33
33
  */
34
34
  import { hostname } from 'node:os';
35
+ import { join } from 'node:path';
35
36
  import { createHubClient } from "../hub/client.js";
36
37
  import { resolveBearer } from "../credentials/resolve.js";
37
38
  import { resolveAllowedWorkdirRoots } from "../agent/workdir.js";
38
39
  import { loadSettings } from "../settings/settings.js";
39
40
  import { createExecLoop } from "../exec/loop.js";
40
41
  import { createDefaultStoreInstructionResolver } from "../exec/instructions.js";
42
+ import { createHubBundleRecoveryHandler } from "../bundle/pull.js";
41
43
  import { createDefaultRunner } from "../exec/runner.js";
42
44
  import { createConsumedVerifier } from "../consumed-verifier.js";
43
45
  import { resolveShiftId, resolveTarget } from "./hold.js";
@@ -183,23 +185,38 @@ export async function run(args, deps = {}) {
183
185
  // independently launched `owenloop work exec` therefore honours the settings
184
186
  // file on its own, with no shift involved.
185
187
  const allowedWorkdirRoots = resolveAllowedWorkdirRoots(env, settings.allowedWorkdirRoots, cwd);
188
+ const account = env['OWENLOOP_ACCOUNT'] ?? 'default';
189
+ const bearer = await resolveBearer({ origin, account, env });
190
+ if (!bearer.ok) {
191
+ err(`owenloop work exec: ${bearer.message}`);
192
+ return bearer.code;
193
+ }
194
+ const token = bearer.token;
186
195
  let instructions = deps.instructions;
187
196
  if (instructions === undefined) {
188
197
  try {
189
- instructions = createDefaultStoreInstructionResolver({ cwd, env, consumedVerifier });
198
+ const home = [env.HOME, env.USERPROFILE].find((value) => value !== undefined && value.trim() !== '');
199
+ if (home === undefined)
200
+ throw new Error('cannot locate the global workflow store: set HOME or USERPROFILE');
201
+ instructions = createDefaultStoreInstructionResolver({
202
+ cwd,
203
+ env,
204
+ consumedVerifier,
205
+ onMissing: createHubBundleRecoveryHandler({
206
+ origin,
207
+ token,
208
+ home,
209
+ projectRoot: join(cwd, 'workflows'),
210
+ env,
211
+ warn: (line) => err(`owenloop work exec: ${line}`),
212
+ }),
213
+ });
190
214
  }
191
215
  catch (e) {
192
216
  err(`owenloop work exec: instruction store unavailable: ${errMsg(e)}`);
193
217
  return 1;
194
218
  }
195
219
  }
196
- const account = env['OWENLOOP_ACCOUNT'] ?? 'default';
197
- const bearer = await resolveBearer({ origin, account, env });
198
- if (!bearer.ok) {
199
- err(`owenloop work exec: ${bearer.message}`);
200
- return bearer.code;
201
- }
202
- const token = bearer.token;
203
220
  const shiftId = resolveShiftId(parsed.shift, env);
204
221
  const holder = {
205
222
  kind: 'exec',
@@ -115,6 +115,13 @@ const CHILD_FIRST_CONTACT_MARGIN_MS = 30_000;
115
115
  * after 90 seconds so a detached child retains 30 seconds to make first contact.
116
116
  */
117
117
  export const MAX_PENDING_CANDIDATE_AGE_MS = HUB_PICKUP_WINDOW_MS - CHILD_FIRST_CONTACT_MARGIN_MS;
118
+ /**
119
+ * A capacity-refused claim is returned to the hub immediately, so sibling
120
+ * shifts can take it. This short, fixed monotonic window stops this shift from
121
+ * claiming that same stable step again on every busy wake while its relevant
122
+ * capacity is still unavailable.
123
+ */
124
+ const CAPACITY_RELEASE_COOLDOWN_MS = 30_000;
118
125
  /**
119
126
  * THE PER-STEP FAILURE BRAKE.
120
127
  *
@@ -258,6 +265,15 @@ export function createShiftLoop(opts) {
258
265
  /** Earliest monotonic time at which a braked step becomes dispatchable again.
259
266
  * Drives a sweep without a hub cursor move, so a brake never waits forever. */
260
267
  let brakeSweepDueAt;
268
+ /**
269
+ * Recently capacity-released stable orders. This is deliberately separate
270
+ * from `stepBrake`: a worker failure leaves its claim to lapse, while a
271
+ * capacity refusal hands the claim back to the hub and needs a reason-aware
272
+ * targeted-poll damper.
273
+ */
274
+ const capacityCooldown = new Map();
275
+ /** Earliest fixed cooldown deadline, used to re-admit an unchanged wake. */
276
+ let capacityCooldownDueAt;
261
277
  /**
262
278
  * Has the current at-capacity EPISODE already produced a `capacity` event?
263
279
  *
@@ -272,6 +288,73 @@ export function createShiftLoop(opts) {
272
288
  /** Bumped whenever a ping starts or is forced due, so a ping that completes
273
289
  * after a force does not stamp the cadence over that force. */
274
290
  let presenceGeneration = 0;
291
+ function refreshCapacityCooldownDueAt() {
292
+ let earliest;
293
+ for (const entry of capacityCooldown.values()) {
294
+ earliest = earliest === undefined ? entry.retryAt : Math.min(earliest, entry.retryAt);
295
+ }
296
+ capacityCooldownDueAt = earliest;
297
+ }
298
+ /** Remove all expired entries; a real post-expiry retry can arm a new window. */
299
+ function pruneExpiredCapacityCooldown(now = monotonicNow()) {
300
+ let changed = false;
301
+ for (const [key, entry] of capacityCooldown) {
302
+ if (entry.retryAt <= now) {
303
+ capacityCooldown.delete(key);
304
+ changed = true;
305
+ }
306
+ }
307
+ if (changed)
308
+ refreshCapacityCooldownDueAt();
309
+ }
310
+ function armCapacityCooldown(workflow, order, reason) {
311
+ const now = monotonicNow();
312
+ pruneExpiredCapacityCooldown(now);
313
+ const key = stepBrakeKey(workflow, order.step, order.key);
314
+ // Do not let cursor activity or duplicate observations slide an active
315
+ // deadline. Only a genuine retry after expiry creates a fresh window.
316
+ if (capacityCooldown.has(key))
317
+ return;
318
+ capacityCooldown.set(key, { workflow, reason, retryAt: now + CAPACITY_RELEASE_COOLDOWN_MS });
319
+ refreshCapacityCooldownDueAt();
320
+ }
321
+ /** Read-only admission signal from the freshly reconciled capacity snapshot. */
322
+ function capacityCooldownReady(remaining, agentRoom, now = monotonicNow()) {
323
+ for (const entry of capacityCooldown.values()) {
324
+ if (entry.retryAt <= now)
325
+ continue;
326
+ if (entry.reason === 'dispatch-cap-full' ? remaining > 0 : agentRoom > 0)
327
+ return true;
328
+ }
329
+ return false;
330
+ }
331
+ /**
332
+ * Remove entries for `workflow` whose own capacity class is now eligible and
333
+ * report whether any active entry still suppresses its targeted request.
334
+ * Expiry is global housekeeping so workflows which disappear from the inbox
335
+ * cannot pin this private map forever.
336
+ */
337
+ function workflowCapacityCooldownActive(workflow, remaining, agentRoom) {
338
+ const now = monotonicNow();
339
+ pruneExpiredCapacityCooldown(now);
340
+ let changed = false;
341
+ let active = false;
342
+ for (const [key, entry] of capacityCooldown) {
343
+ if (entry.workflow !== workflow)
344
+ continue;
345
+ const ready = entry.reason === 'dispatch-cap-full' ? remaining > 0 : agentRoom > 0;
346
+ if (ready) {
347
+ capacityCooldown.delete(key);
348
+ changed = true;
349
+ }
350
+ else {
351
+ active = true;
352
+ }
353
+ }
354
+ if (changed)
355
+ refreshCapacityCooldownDueAt();
356
+ return active;
357
+ }
275
358
  function noteServerBackoff(error) {
276
359
  if (!(error instanceof HubError) || error.status !== 429)
277
360
  return false;
@@ -615,6 +698,7 @@ export function createShiftLoop(opts) {
615
698
  if (!liveOrReserved.has(run))
616
699
  runBrakeKey.delete(run);
617
700
  }
701
+ pruneExpiredCapacityCooldown();
618
702
  /**
619
703
  * PHASE 4, for the work-dir reaper only. `polled` is the set of workflows
620
704
  * whose `whats_next` SUCCEEDED this sweep — a workflow whose call threw is
@@ -628,6 +712,7 @@ export function createShiftLoop(opts) {
628
712
  const polled = new Set();
629
713
  const openRuns = new Set();
630
714
  let complete = true;
715
+ let releasedForCapacity = false;
631
716
  let remaining = budget;
632
717
  const liveRuns = new Set([...live.map((r) => r.run), ...reserved.map((r) => r.run)]);
633
718
  // The agent lane's SECOND budget (D7). Counted from live records and durable
@@ -672,7 +757,7 @@ export function createShiftLoop(opts) {
672
757
  // that omission is what distinguishes the untargeted inbox call from a
673
758
  // per-workflow one, since `HubErrorEvent.workflow` is optional.
674
759
  emit({ type: 'hub-error', op: 'whats_next', message: errMsg(e) });
675
- return { dispatched, polled, openRuns, complete: false };
760
+ return { dispatched, polled, openRuns, complete: false, releasedForCapacity };
676
761
  }
677
762
  }
678
763
  // Collect candidates, metering NEW dispatches and deduping in-flight.
@@ -701,8 +786,24 @@ export function createShiftLoop(opts) {
701
786
  const releaseOrder = (workflow, order, reason, message) => {
702
787
  dropOrder(workflow, order, reason, message);
703
788
  releaseClaim(workflow, order.run);
789
+ // Re-arm the next sweep, but only for the two TRANSIENT reasons — see
790
+ // `SweepResult.releasedForCapacity` for why `agent-lane-closed` is not
791
+ // one of them. The independent cooldown prevents a busy cursor from
792
+ // immediately re-claiming this stable step while the same capacity class
793
+ // remains unavailable; it neither replaces server Retry-After backoff
794
+ // nor the worker-failure brake.
795
+ if (reason === 'dispatch-cap-full' || reason === 'agent-cap-full') {
796
+ armCapacityCooldown(workflow, order, reason);
797
+ releasedForCapacity = true;
798
+ }
704
799
  };
705
800
  for (const wf of instances) {
801
+ // Skipping means no targeted hub observation happened: leave this
802
+ // workflow out of `polled`/`openRuns` so the work-directory reaper never
803
+ // mistakes damping for an empty response. The inbox call and other
804
+ // workflows remain eligible.
805
+ if (workflowCapacityCooldownActive(wf, remaining, agentRoom))
806
+ continue;
706
807
  let res;
707
808
  const requestStartedAt = monotonicNow();
708
809
  try {
@@ -924,7 +1025,7 @@ export function createShiftLoop(opts) {
924
1025
  }
925
1026
  }
926
1027
  }
927
- return { dispatched, polled, openRuns, complete };
1028
+ return { dispatched, polled, openRuns, complete, releasedForCapacity };
928
1029
  }
929
1030
  /**
930
1031
  * PHASE 4 — remove the per-run work directories of runs that are over.
@@ -1043,6 +1144,9 @@ export function createShiftLoop(opts) {
1043
1144
  const reserved = inFlight.reserved;
1044
1145
  const occupied = live.length + reserved.length;
1045
1146
  const k = cap - occupied;
1147
+ const agentRoom = agentLane().ceiling -
1148
+ live.filter((record) => record.kind === 'agent-run').length -
1149
+ reserved.filter((record) => record.childKind === 'agent-run').length;
1046
1150
  // Re-arm the at-capacity report the instant a slot frees, independently of
1047
1151
  // whether this tick goes on to wake or sweep. The next stretch at capacity
1048
1152
  // is a NEW episode and gets its own record.
@@ -1076,12 +1180,22 @@ export function createShiftLoop(opts) {
1076
1180
  // unchanged next time. `sweepOwed` preserves that unconsumed work signal.
1077
1181
  let swept;
1078
1182
  const brakeDue = brakeSweepDueAt !== undefined && monotonicNow() >= brakeSweepDueAt;
1079
- if (wakeSucceeded && (changed || sweepOwed || brakeDue) && k > 0) {
1183
+ // Keep a due cooldown armed while total capacity is zero: the outer gate
1184
+ // must still defer hub work, but an unchanged wake needs to retry as soon
1185
+ // as a total slot exists. `sweep()` removes expired entries only when it
1186
+ // can actually make the targeted decision.
1187
+ const capacityCooldownDue = capacityCooldownDueAt !== undefined && monotonicNow() >= capacityCooldownDueAt;
1188
+ const capacityBecameReady = capacityCooldownReady(k, agentRoom);
1189
+ if (wakeSucceeded && (changed || sweepOwed || brakeDue || capacityCooldownDue || capacityBecameReady) && k > 0) {
1080
1190
  // Clear before awaiting: a new brake armed during sweep must survive.
1081
1191
  if (brakeDue)
1082
1192
  brakeSweepDueAt = undefined;
1083
1193
  swept = await sweep(k, live, reserved);
1084
- sweepOwed = !swept.complete;
1194
+ // A COMPLETE sweep that handed work back for capacity is still unfinished
1195
+ // business. Without this the assignment below would clear the very signal
1196
+ // the release just raised, and the released order would wait for a cursor
1197
+ // change that a single-capability topology never produces.
1198
+ sweepOwed = !swept.complete || swept.releasedForCapacity;
1085
1199
  }
1086
1200
  else if (changed && k <= 0) {
1087
1201
  sweepOwed = true;
@@ -1,4 +1,5 @@
1
1
  import { type ShiftEventBody } from './protocol.ts';
2
+ import { type Spawner } from './spawn.ts';
2
3
  import { type Liveness, type Reconciliation } from './state.ts';
3
4
  import { type AcquireFileLockOpts } from '../../../../src/lock.ts';
4
5
  import { installSignalHandlers, type SignalHost } from '../roles/signals.ts';
@@ -68,6 +69,8 @@ export interface ShiftRuntimeOptions {
68
69
  role?: 'shift';
69
70
  /** Socket path selected by the shift command. */
70
71
  socketPath?: string;
72
+ /** Test/embedder spawner; production uses the detached worker spawner. */
73
+ spawner?: Spawner;
71
74
  }
72
75
  /** Public Shift daemon transport is a Unix-domain socket on macOS and Linux. */
73
76
  export declare function assertShiftDaemonPlatform(platform?: NodeJS.Platform): void;
@@ -17,6 +17,7 @@ import { DEFAULT_HUB_ROSTER_SYNC_TIMEOUT_MS, syncHubRosterCache, withHubRosterSy
17
17
  import { computeServeCapabilities } from "../settings/serving.js";
18
18
  import { resolveCacheDir } from "../bundle/cache.js";
19
19
  import { createLockedRemovalCallbacks, createShiftLoop } from "./loop.js";
20
+ import { createHubBundleRecoveryHandler } from "../bundle/pull.js";
20
21
  import { createShiftLogSink } from "./logsink.js";
21
22
  import { prepareShiftLogDir, shiftLogFile } from "./logretention.js";
22
23
  import { stampShiftEvent } from "./protocol.js";
@@ -434,6 +435,14 @@ export async function runShiftRuntime(parsed, options = {}) {
434
435
  projectRoot: join(process.cwd(), 'workflows'),
435
436
  globalRoot: globalStoreRoot(home),
436
437
  verifier: createBundleIngestor(),
438
+ onMissing: createHubBundleRecoveryHandler({
439
+ origin,
440
+ token,
441
+ home,
442
+ projectRoot: join(process.cwd(), 'workflows'),
443
+ env,
444
+ warn: (line) => process.stderr.write(`${roleLabel}: ${line}\n`),
445
+ }),
437
446
  });
438
447
  const resolveOrderStep = async (order) => {
439
448
  if (instructionSource === undefined ||
@@ -536,7 +545,7 @@ export async function runShiftRuntime(parsed, options = {}) {
536
545
  const reportWorkerExit = (exit) => {
537
546
  loopRef.current?.noteChildExited(exit);
538
547
  };
539
- const spawner = createDefaultSpawner(origin, account, undefined, shiftId, reportWorkerFailure,
548
+ const spawner = options.spawner ?? createDefaultSpawner(origin, account, undefined, shiftId, reportWorkerFailure,
540
549
  // `undefined` when the log directory could not be created, which is what
541
550
  // makes `buildSpawnPlan` emit no `logFile` and the worker launch with its
542
551
  // output discarded exactly as it did before this change.
@@ -38,14 +38,17 @@ export declare function buildSubmitProof(opts: SubmitProofOptions): Promise<stri
38
38
  * the proof against.
39
39
  *
40
40
  * Retry-safety comes from the hub, not from this function. The target is
41
- * computed once inside the claim transaction and persisted with the immutable
42
- * order, so every retry of the same claim — a reconnect, a lost response, a
43
- * restarted holder — reads the same number. The engine's refusal paths that
44
- * leave the run open (schema-reject) do not bump the artifact, so the target
45
- * survives in-claim retries; a refinement is a NEW claim and therefore a newly
46
- * issued target. If a target ever did go stale, the consumer's version check
47
- * refuses the artifact. The failure mode is a refusal, never an admitted
48
- * unverified value.
41
+ * issued inside the claim transaction and persisted with the order, so a
42
+ * reconnect, a lost response, or a restarted holder re-reads the same number
43
+ * rather than guessing one; a refinement is a NEW claim and therefore a newly
44
+ * issued target. It is not, however, frozen for the life of the claim. A
45
+ * refusal that leaves the run open without bumping the artifact (a schema
46
+ * reject) leaves the target correct, but a judgment/human reject FOLLOWS a
47
+ * commit that already bumped it, so the engine re-stamps the target on the
48
+ * still-open claim at the reject site — this function simply re-reads whatever
49
+ * the current order says, which is why it must never cache one. If a target
50
+ * does go stale anyway, the consumer's version check refuses the artifact. The
51
+ * failure mode is a refusal, never an admitted unverified value.
49
52
  *
50
53
  * A hub that projects no `owes[].version` (pre-version-aware) yields
51
54
  * `undefined`, and the caller submits unsigned rather than signing a guess.
@@ -78,14 +78,17 @@ function submissionFingerprint(order, warn) {
78
78
  * the proof against.
79
79
  *
80
80
  * Retry-safety comes from the hub, not from this function. The target is
81
- * computed once inside the claim transaction and persisted with the immutable
82
- * order, so every retry of the same claim — a reconnect, a lost response, a
83
- * restarted holder — reads the same number. The engine's refusal paths that
84
- * leave the run open (schema-reject) do not bump the artifact, so the target
85
- * survives in-claim retries; a refinement is a NEW claim and therefore a newly
86
- * issued target. If a target ever did go stale, the consumer's version check
87
- * refuses the artifact. The failure mode is a refusal, never an admitted
88
- * unverified value.
81
+ * issued inside the claim transaction and persisted with the order, so a
82
+ * reconnect, a lost response, or a restarted holder re-reads the same number
83
+ * rather than guessing one; a refinement is a NEW claim and therefore a newly
84
+ * issued target. It is not, however, frozen for the life of the claim. A
85
+ * refusal that leaves the run open without bumping the artifact (a schema
86
+ * reject) leaves the target correct, but a judgment/human reject FOLLOWS a
87
+ * commit that already bumped it, so the engine re-stamps the target on the
88
+ * still-open claim at the reject site — this function simply re-reads whatever
89
+ * the current order says, which is why it must never cache one. If a target
90
+ * does go stale anyway, the consumer's version check refuses the artifact. The
91
+ * failure mode is a refusal, never an admitted unverified value.
89
92
  *
90
93
  * A hub that projects no `owes[].version` (pre-version-aware) yields
91
94
  * `undefined`, and the caller submits unsigned rather than signing a guess.