owenloop 0.5.30 → 0.5.31

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 (51) hide show
  1. package/CHANGELOG.md +14 -0
  2. package/dist/packages/work/src/agent/loop.d.ts +5 -3
  3. package/dist/packages/work/src/agent/loop.js +24 -3
  4. package/dist/packages/work/src/agent/workdir.d.ts +17 -0
  5. package/dist/packages/work/src/agent/workdir.js +24 -0
  6. package/dist/packages/work/src/exec/loop.d.ts +8 -1
  7. package/dist/packages/work/src/exec/loop.js +24 -1
  8. package/dist/packages/work/src/hub/client.d.ts +10 -3
  9. package/dist/packages/work/src/hub/client.js +5 -4
  10. package/dist/packages/work/src/hub/deadline.d.ts +20 -0
  11. package/dist/packages/work/src/hub/deadline.js +49 -0
  12. package/dist/packages/work/src/roles/agent-run.js +1 -0
  13. package/dist/packages/work/src/roles/exec.js +1 -0
  14. package/dist/packages/work/src/settings/hub-roster-cache.js +5 -23
  15. package/dist/packages/work/src/shift/loop.d.ts +59 -0
  16. package/dist/packages/work/src/shift/loop.js +177 -19
  17. package/dist/packages/work/src/shift/protocol.d.ts +53 -1
  18. package/dist/packages/work/src/shift/runtime.js +10 -1
  19. package/dist/packages/work/src/shift/server.js +2 -0
  20. package/dist/src/bundle/manifest.d.ts +6 -1
  21. package/dist/src/bundle/manifest.js +38 -8
  22. package/dist/src/bundle/runtime.d.ts +1 -1
  23. package/dist/src/bundle/runtime.js +1 -0
  24. package/dist/src/bundle/types.d.ts +3 -2
  25. package/dist/src/cli.js +17 -3
  26. package/dist/src/defs.js +17 -4
  27. package/dist/src/engine.d.ts +3 -0
  28. package/dist/src/engine.js +42 -9
  29. package/dist/src/factory.d.ts +2 -0
  30. package/dist/src/factory.js +2 -0
  31. package/dist/src/index.d.ts +1 -1
  32. package/dist/src/index.js +1 -1
  33. package/dist/src/store/def-source.d.ts +1 -1
  34. package/dist/src/store/def-source.js +25 -0
  35. package/dist/src/store/gc.js +9 -7
  36. package/dist/src/store/index.d.ts +1 -0
  37. package/dist/src/store/index.js +1 -0
  38. package/dist/src/store/install.js +9 -3
  39. package/dist/src/store/instruction-source.js +9 -5
  40. package/dist/src/store/verified-lock.d.ts +4 -0
  41. package/dist/src/store/verified-lock.js +38 -0
  42. package/dist/src/store.js +4 -2
  43. package/docs/authoring.md +12 -0
  44. package/docs/bundles.md +3 -2
  45. package/docs/cli.md +39 -11
  46. package/docs/shift-logs.md +53 -4
  47. package/package.json +1 -1
  48. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
  49. package/plugins/claude-code/plugin/.mcp.json +1 -1
  50. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
  51. package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
@@ -15,6 +15,7 @@ import { summarizeIssues, validateValue } from "./schema.js";
15
15
  import { hashDef } from "./defs.js";
16
16
  import { checkInterfaceCompatibility } from "./implements.js";
17
17
  import { isDefDigest, parseWorkflowCoordinate } from "./store/types.js";
18
+ import { parseVersionedCallTarget } from "./bundle/manifest.js";
18
19
  import { applyCapabilityMappings, applyCapabilityRewrites, claimMatches, composeCapabilities } from "./capabilities.js";
19
20
  import { localMidnightMs, nowMs, randId } from "./util.js";
20
21
  import { isCallStep } from "./types.js";
@@ -165,8 +166,9 @@ function hasExactImplementationClaim(def, expected) {
165
166
  * containing bundle's own digest. `childDef.bundleDigest` must equal
166
167
  * `parentDef.bundleDigest`.
167
168
  *
168
- * 2. `target` is an explicit `namespace/name@version` reference AND the parent
169
- * bundle's manifest `lock` names it. The lock value is a canonical BUNDLE
169
+ * 2. `target` is an explicit `namespace/name@version` reference, optionally
170
+ * followed by `#workflow`, AND the parent bundle's manifest `lock` names
171
+ * its base coordinate. The lock value is a canonical BUNDLE
170
172
  * digest (`bundle.yaml.lock` validates lowercase 64-hex; `assertLockCoverage`
171
173
  * requires an entry for every versioned target), so it is compared against
172
174
  * `childDef.bundleDigest` — NOT against `defInstructionDigest`, which
@@ -179,9 +181,13 @@ function hasExactImplementationClaim(def, expected) {
179
181
  */
180
182
  function callsPinViolation(parentDef, childDef, target) {
181
183
  if (target.includes('/')) {
182
- const pinned = parentDef.bundleLock?.[target];
183
- if (pinned === undefined)
184
- return undefined; // no lock entry reachable — unpinned
184
+ const lockKey = target.includes('#') ? parseVersionedCallTarget(target).coordinate : target;
185
+ const pinned = parentDef.bundleLock?.[lockKey];
186
+ if (pinned === undefined) {
187
+ return parentDef.bundleDigest !== undefined && target.includes('#')
188
+ ? `parent bundle has no lock for exact target ${lockKey}`
189
+ : undefined;
190
+ }
185
191
  if (childDef.bundleDigest === undefined) {
186
192
  return `parent bundle pins it to ${pinned} but the resolved definition carries no bundle provenance`;
187
193
  }
@@ -230,6 +236,7 @@ export class Engine {
230
236
  * compatibility mode). Public read-only facade: {@link Engine.resolver}.
231
237
  */
232
238
  instructionSource;
239
+ readVerifiedBundleLock;
233
240
  resolver;
234
241
  reapTtlMs;
235
242
  maxLeaseMs;
@@ -242,6 +249,7 @@ export class Engine {
242
249
  this.store = store;
243
250
  this.resolveDef = resolveDef;
244
251
  this.instructionSource = opts.instructionSource ?? createDefInstructionSource();
252
+ this.readVerifiedBundleLock = opts.readVerifiedBundleLock;
245
253
  this.resolver = new OrderResolver(this.instructionSource);
246
254
  this.reapTtlMs = opts.reapTtlMs ?? DEFAULT_REAP_TTL_MS;
247
255
  this.maxLeaseMs = opts.maxLeaseMs;
@@ -566,6 +574,10 @@ export class Engine {
566
574
  const needsSnapshot = Symbol('needs-workflow-snapshot');
567
575
  let snapshotDef;
568
576
  let optimisticInterfaceBinding;
577
+ const namedExactLockKey = step.calls !== undefined && step.calls.includes('#') && parentDef.bundleDigest !== undefined
578
+ ? parseVersionedCallTarget(step.calls).coordinate
579
+ : undefined;
580
+ let verifiedParentPin;
569
581
  // Interface targets are selected once, stored on the parent, and resolved by
570
582
  // exact digest BEFORE either the workflow-store guard or SQLite write lock.
571
583
  // The transaction below re-reads and compares the persisted selection.
@@ -641,12 +653,19 @@ export class Engine {
641
653
  let created = false;
642
654
  let childDef;
643
655
  if (!child) {
644
- // Resolving a new child's CAS def must happen before its coordinated
645
- // transaction acquires SQLite. Return a read-only sentinel on the
646
- // first pass; `run` resolves, locks/revalidates the bundle store, and
647
- // then repeats every gate/child read under the guarded write tx.
656
+ // Resolve outside SQLite before any parent-pin comparison or child write.
648
657
  if (snapshotDef === undefined)
649
658
  return needsSnapshot;
659
+ if (namedExactLockKey !== undefined) {
660
+ const fresh = parentRow.defSnapshot;
661
+ if (verifiedParentPin === undefined
662
+ || fresh === undefined
663
+ || fresh.bundleDigest !== parentDef.bundleDigest
664
+ || fresh.bundleLock?.[namedExactLockKey] !== verifiedParentPin
665
+ || fresh.steps.find((candidate) => candidate.name === step.name)?.calls !== step.calls) {
666
+ throw new CallsPinError(step.calls, 'the persisted parent or its base-coordinate lock changed before child creation');
667
+ }
668
+ }
650
669
  const childId = randId('wf');
651
670
  // WS-6: resolve IN THE PARENT'S SCOPE. `parentDef` is the parent's own
652
671
  // §28 pin (defFor prefers `defSnapshot` over the live resolver), so a
@@ -748,6 +767,20 @@ export class Engine {
748
767
  return result;
749
768
  // Resolve optimistically outside both locks. The snapshot guard then
750
769
  // revalidates this CAS provenance under add.lock before SQLite begins.
770
+ if (namedExactLockKey !== undefined) {
771
+ if (this.readVerifiedBundleLock === undefined) {
772
+ throw new CallsPinError(step.calls, 'no verified parent bundle lock reader is configured');
773
+ }
774
+ try {
775
+ verifiedParentPin = this.readVerifiedBundleLock(parentDef.bundleDigest)[namedExactLockKey];
776
+ }
777
+ catch (error) {
778
+ throw new CallsPinError(step.calls, `the parent bundle could not be verified: ${error.message}`);
779
+ }
780
+ if (verifiedParentPin === undefined || parentDef.bundleLock?.[namedExactLockKey] !== verifiedParentPin) {
781
+ throw new CallsPinError(step.calls, `the persisted base-coordinate lock differs from the verified parent bundle for ${namedExactLockKey}`);
782
+ }
783
+ }
751
784
  snapshotDef = this.resolveDef(step.calls, parentDef);
752
785
  result = transact();
753
786
  if (result === needsSnapshot)
@@ -73,6 +73,8 @@ export interface CreateEngineOpts {
73
73
  * same reference-mode behavior, no legacy branch.
74
74
  */
75
75
  instructionSource?: OrderInstructionSource;
76
+ /** Verified, index-independent CAS lock reader for replaying named exact calls. */
77
+ readVerifiedBundleLock?: (digest: string) => Readonly<Record<string, string>>;
76
78
  }
77
79
  export interface CreatedEngine {
78
80
  engine: Engine;
@@ -105,6 +105,8 @@ export function createEngine(opts = {}) {
105
105
  if (opts.onListenerError !== undefined)
106
106
  engineOpts.onListenerError = opts.onListenerError;
107
107
  engineOpts.instructionSource = instructionSource;
108
+ if (opts.readVerifiedBundleLock !== undefined)
109
+ engineOpts.readVerifiedBundleLock = opts.readVerifiedBundleLock;
108
110
  const engine = new Engine(store, resolveDef, engineOpts);
109
111
  return { engine, store, defs, resolver: engine.resolver };
110
112
  }
@@ -21,7 +21,7 @@ export { createDefInstructionSource, defInstructionDigest, OrderResolver, substi
21
21
  export type { OrderInstructionLookup, OrderInstructionRef, OrderInstructionSource, OrderRuntimeVars, ResolvedInstructionRecord, ResolvedInstructions, } from './order-resolver.ts';
22
22
  export { Store, openStore, readRuntimeSnapshotBundlePins, StoreVersionError } from './store.ts';
23
23
  export type { ArtifactRow, RunRow, RuntimeSnapshotBundlePins, TaskRow, WorkflowRow } from './store.ts';
24
- export { defDigest, collectWorkflowStoreGarbage, emptyWorkflowStoreIndex, globalStoreRoot, hardenObjectModes, installWorkflowBundle, inspectCasDefs, isDefDigest, loadCasDefs, planWorkflowStoreGc, objectDestRelPath, objectDirForDigest, parseWorkflowCoordinate, parseWorkflowStoreIndex, projectStoreRoot, probeObjectDir, probeStoreRoot, readWorkflowStoreIndex, recoverWorkflowStore, resolveWorkflowCoordinate, resolveWorkflowDigest, serializeWorkflowStoreIndex, storeIndexPath, workflowCoordinate, workflowStoreStatePaths, WORKFLOW_STORE_INDEX_VERSION, WorkflowStoreError, StoreIndexError, StoreDigestError, StoreCoordinateError, StoreAmbiguityError, StoreNotFoundError, StoreIntegrityError, StoreConflictError, StoreDefinitionVerificationError, StoreOriginPolicyError, StorePathError, BundleIngestorUnavailableError, PreCommitVerifierUnavailableError, createExecutionOriginVerifier, originEvidencePath, persistOriginEvidence, readOriginEvidence, } from './store/index.ts';
24
+ export { defDigest, collectWorkflowStoreGarbage, emptyWorkflowStoreIndex, globalStoreRoot, hardenObjectModes, installWorkflowBundle, inspectCasDefs, isDefDigest, loadCasDefs, planWorkflowStoreGc, objectDestRelPath, objectDirForDigest, parseWorkflowCoordinate, parseWorkflowStoreIndex, projectStoreRoot, probeObjectDir, probeStoreRoot, readWorkflowStoreIndex, recoverWorkflowStore, resolveWorkflowCoordinate, resolveWorkflowDigest, serializeWorkflowStoreIndex, storeIndexPath, workflowCoordinate, workflowStoreStatePaths, WORKFLOW_STORE_INDEX_VERSION, WorkflowStoreError, StoreIndexError, StoreDigestError, StoreCoordinateError, StoreAmbiguityError, StoreNotFoundError, StoreIntegrityError, StoreConflictError, StoreDefinitionVerificationError, StoreOriginPolicyError, StorePathError, BundleIngestorUnavailableError, PreCommitVerifierUnavailableError, createExecutionOriginVerifier, createVerifiedBundleLockReader, originEvidencePath, persistOriginEvidence, readOriginEvidence, } from './store/index.ts';
25
25
  export type { BundleInstallResult, BundleIngestor, BundleSource, BundleVerificationEvidence, CasDefInspectionResult, CasDefRegistration, DefDigest, LoadCasDefsArgs, CollectWorkflowStoreGcArgs, InstallWorkflowBundleArgs, PreCommitVerifier, PlanWorkflowStoreGcArgs, ExecutionOriginVerifierInput, RecoverWorkflowStoreArgs, ResolvedWorkflowObject, ResolveWorkflowCoordinateArgs, ResolveWorkflowDigestArgs, ResolutionLevel, StoreLevel, WorkflowCoordinate, WorkflowStoreIndex, WorkflowStoreIndexEntry, WorkflowStoreGcObject, WorkflowStoreGcPlan, WorkflowStoreGcReport, WorkflowStoreStatePaths, } from './store/index.ts';
26
26
  export { buildDef, cancelCleanupSteps, DefError, expandIncludes, finalizeDefs, hashDef, InterfaceCallDefinitionError, lintDef, loadDefFile, loadDefs, loadDefsRaw, parseDef, resolveCallsTarget, SUPPORTED_ENGINE_VERSION, validateDef } from './defs.ts';
27
27
  export { checkInterfaceCompatibility, implementsIssues } from './implements.ts';
package/dist/src/index.js CHANGED
@@ -21,7 +21,7 @@ export { Store, openStore, readRuntimeSnapshotBundlePins, StoreVersionError } fr
21
21
  // The content-addressed WORKFLOW store (distinct from the SQLite runtime
22
22
  // store above): two-level digest-addressed workflow objects + coordinate
23
23
  // index, `.wnlp` bundle installation, and fail-closed resolution.
24
- export { defDigest, collectWorkflowStoreGarbage, emptyWorkflowStoreIndex, globalStoreRoot, hardenObjectModes, installWorkflowBundle, inspectCasDefs, isDefDigest, loadCasDefs, planWorkflowStoreGc, objectDestRelPath, objectDirForDigest, parseWorkflowCoordinate, parseWorkflowStoreIndex, projectStoreRoot, probeObjectDir, probeStoreRoot, readWorkflowStoreIndex, recoverWorkflowStore, resolveWorkflowCoordinate, resolveWorkflowDigest, serializeWorkflowStoreIndex, storeIndexPath, workflowCoordinate, workflowStoreStatePaths, WORKFLOW_STORE_INDEX_VERSION, WorkflowStoreError, StoreIndexError, StoreDigestError, StoreCoordinateError, StoreAmbiguityError, StoreNotFoundError, StoreIntegrityError, StoreConflictError, StoreDefinitionVerificationError, StoreOriginPolicyError, StorePathError, BundleIngestorUnavailableError, PreCommitVerifierUnavailableError, createExecutionOriginVerifier, originEvidencePath, persistOriginEvidence, readOriginEvidence, } from "./store/index.js";
24
+ export { defDigest, collectWorkflowStoreGarbage, emptyWorkflowStoreIndex, globalStoreRoot, hardenObjectModes, installWorkflowBundle, inspectCasDefs, isDefDigest, loadCasDefs, planWorkflowStoreGc, objectDestRelPath, objectDirForDigest, parseWorkflowCoordinate, parseWorkflowStoreIndex, projectStoreRoot, probeObjectDir, probeStoreRoot, readWorkflowStoreIndex, recoverWorkflowStore, resolveWorkflowCoordinate, resolveWorkflowDigest, serializeWorkflowStoreIndex, storeIndexPath, workflowCoordinate, workflowStoreStatePaths, WORKFLOW_STORE_INDEX_VERSION, WorkflowStoreError, StoreIndexError, StoreDigestError, StoreCoordinateError, StoreAmbiguityError, StoreNotFoundError, StoreIntegrityError, StoreConflictError, StoreDefinitionVerificationError, StoreOriginPolicyError, StorePathError, BundleIngestorUnavailableError, PreCommitVerifierUnavailableError, createExecutionOriginVerifier, createVerifiedBundleLockReader, originEvidencePath, persistOriginEvidence, readOriginEvidence, } from "./store/index.js";
25
25
  export { buildDef, cancelCleanupSteps, DefError, expandIncludes, finalizeDefs, hashDef, InterfaceCallDefinitionError, lintDef, loadDefFile, loadDefs, loadDefsRaw, parseDef, resolveCallsTarget, SUPPORTED_ENGINE_VERSION, validateDef } from "./defs.js";
26
26
  export { checkInterfaceCompatibility, implementsIssues } from "./implements.js";
27
27
  export { credentialSlot, hashDefForHub, keychainServiceFor, normalizeOrigin, readStoredCredential } from "./hub.js";
@@ -29,7 +29,7 @@ export interface CasDefRegistration {
29
29
  level: ResolutionLevel;
30
30
  /** Registration purpose. Coordinate aliases are exact versioned call targets. */
31
31
  kind: 'workflow' | 'coordinate';
32
- /** Present only for a full versioned coordinate alias. */
32
+ /** Base package coordinate for an exact alias, including named workflow selectors. */
33
33
  coordinate?: WorkflowCoordinate;
34
34
  }
35
35
  export interface LoadCasDefsArgs {
@@ -325,6 +325,31 @@ function discoverCasDefs(args, tolerant, repairReplacement) {
325
325
  loaded.objectRoot,
326
326
  ])].sort(compareStoreText));
327
327
  }
328
+ // A selector is derived only from this verified coordinate/object pair.
329
+ // Register the digest-scoped alias even for a shadowed global row;
330
+ // the direct alias still obeys project precedence.
331
+ for (const [workflowName, def] of loaded.defs) {
332
+ const selector = `${indexed.coordinate}#${workflowName}`;
333
+ for (const key of [
334
+ digestScopedCallsTargetKey(digest, selector),
335
+ ...(indexed.registerAlias ? [selector] : []),
336
+ ]) {
337
+ if (registeredCoordinateKeys.has(key))
338
+ continue;
339
+ registeredCoordinateKeys.add(key);
340
+ registrations.push({
341
+ key,
342
+ qualified: `${loaded.manifest.package.name}/${workflowName}`,
343
+ bare: workflowName,
344
+ def,
345
+ bundleDigest: digest,
346
+ bundlePackage: loaded.manifest.package.name,
347
+ level: loaded.level,
348
+ kind: 'coordinate',
349
+ coordinate: indexed.coordinate,
350
+ });
351
+ }
352
+ }
328
353
  if (target === undefined) {
329
354
  if (indexed.registerAlias) {
330
355
  args.warn(`warning: coordinate '${indexed.coordinate}' is not callable because the bundle exports ` +
@@ -7,6 +7,7 @@
7
7
  import { lstatSync, readFileSync, readdirSync, } from 'node:fs';
8
8
  import { dirname, join } from 'node:path';
9
9
  import { parseManifestBytes } from "../bundle/manifest.js";
10
+ import { parseVersionedCallTarget } from "../bundle/manifest.js";
10
11
  import { loadDefFile } from "../defs.js";
11
12
  import { acquireInstallLock, ensureDirectoryPathNoSymlink, guardStateFile, probeDirectoryPath, recoverInterruptedInstall, releaseInstallLock, rmRecursiveForce, STAGING_DIRNAME, } from "../install.js";
12
13
  import { randId } from "../util.js";
@@ -158,8 +159,8 @@ export function planWorkflowStoreGc(args) {
158
159
  for (const registration of registrations) {
159
160
  if (registration.kind === 'coordinate'
160
161
  && registration.coordinate !== undefined
161
- && registration.key === registration.coordinate) {
162
- directCoordinateDigests.set(registration.coordinate, registration.bundleDigest);
162
+ && (registration.key === registration.coordinate || registration.key.startsWith(`${registration.coordinate}#`))) {
163
+ directCoordinateDigests.set(registration.key, registration.bundleDigest);
163
164
  }
164
165
  }
165
166
  const projectObjects = scanObjects(projectRoot);
@@ -332,13 +333,14 @@ export function planWorkflowStoreGc(args) {
332
333
  'but no exact callable coordinate with verified bytes is installed');
333
334
  };
334
335
  // A retained filesystem/add/legacy parent carries no bundle digest or lock,
335
- // but its explicit namespace/name@version call still resolves through the
336
- // direct CAS coordinate alias. Root that exact coordinate and the digest it
336
+ // but its exact package or named-workflow call still resolves through the
337
+ // direct CAS alias. Root its base coordinate and the digest it
337
338
  // selects before walking the selected object's own manifest locks.
338
- for (const coordinate of [...retainedExactCalls].sort(compareStoreText)) {
339
- const digest = directCoordinateDigests.get(coordinate);
339
+ for (const target of [...retainedExactCalls].sort(compareStoreText)) {
340
+ const coordinate = parseVersionedCallTarget(target).coordinate;
341
+ const digest = directCoordinateDigests.get(target);
340
342
  if (digest === undefined) {
341
- throw new Error(`workflow-store GC cannot preserve retained exact calls target '${coordinate}': ` +
343
+ throw new Error(`workflow-store GC cannot preserve retained exact calls target '${target}': ` +
342
344
  'no callable exact coordinate is installed');
343
345
  }
344
346
  preserveCoordinate(coordinate, digest, `retained exact calls target '${coordinate}'`, `workflow-store GC cannot preserve retained exact calls target '${coordinate}' at ${digest}: ` +
@@ -18,6 +18,7 @@ export { hardenObjectModes, installWorkflowBundle, objectDestRelPath, recoverWor
18
18
  export { createBundleIngestor, verifyHardenedWorkflowObjectModesSync, verifyWorkflowObjectSync, } from './ingestor.ts';
19
19
  export type { BundleIngestorOptions } from './ingestor.ts';
20
20
  export { inspectCasDefs, loadCasDefs } from './def-source.ts';
21
+ export { createVerifiedBundleLockReader } from './verified-lock.ts';
21
22
  export type { CasDefInspectionResult, CasDefRegistration, LoadCasDefsArgs, } from './def-source.ts';
22
23
  export { collectWorkflowStoreGarbage, planWorkflowStoreGc } from './gc.ts';
23
24
  export type { CollectWorkflowStoreGcArgs, PlanWorkflowStoreGcArgs, WorkflowStoreGcObject, WorkflowStoreGcPlan, WorkflowStoreGcReport, } from './gc.ts';
@@ -16,6 +16,7 @@ export { hardenObjectModes, installWorkflowBundle, objectDestRelPath, recoverWor
16
16
  export { createBundleIngestor, verifyHardenedWorkflowObjectModesSync, verifyWorkflowObjectSync, } from "./ingestor.js";
17
17
  // ---- WS-6 CAS -> calls: def bridge ----
18
18
  export { inspectCasDefs, loadCasDefs } from "./def-source.js";
19
+ export { createVerifiedBundleLockReader } from "./verified-lock.js";
19
20
  // ---- workflow-store reachability GC ----
20
21
  export { collectWorkflowStoreGarbage, planWorkflowStoreGc } from "./gc.js";
21
22
  // ---- WP-E2a origin execution policy ----
@@ -25,7 +25,7 @@ import { chmodSync, existsSync, lstatSync, readFileSync, readdirSync } from 'nod
25
25
  import { dirname, join } from 'node:path';
26
26
  import { randId } from "../util.js";
27
27
  import { DefError, digestScopedCallsTargetKey, finalizeDefs, lintDef, loadDefFile, loadDefsRaw, validateDef, } from "../defs.js";
28
- import { parseManifestBytes } from "../bundle/manifest.js";
28
+ import { isVersionedReference, parseManifestBytes, parseVersionedCallTarget } from "../bundle/manifest.js";
29
29
  import { hasDefiniteCheckDefect, modelCheck } from "../model.js";
30
30
  import { acquireInstallLock, canonicalJsonBytes, commitInstall, createRecoveryMarker, ensureDirectoryPathNoSymlink, finalizeInstallCommit, guardStateFile, multiSegmentPathViolation, probeDirectoryPath, recoverInterruptedInstall, recordRecoveryMarkerPriorIdentity, releaseInstallLock, removeAddJournal, removeRecoveryMarker, rmRecursiveForce, RollbackFailedError, rollbackInstallCommit, sha256Hex, writeAddJournal, } from "../install.js";
31
31
  import { BundleIngestorUnavailableError, PreCommitVerifierUnavailableError, StoreConflictError, StoreIntegrityError, StorePathError, } from "./types.js";
@@ -62,7 +62,9 @@ function assertManifestLocksResolvable(args) {
62
62
  .map((registration) => registration.key));
63
63
  for (const [coordinate, rawDigest] of entries.sort(([a], [b]) => compareStoreText(a, b))) {
64
64
  const digest = defDigest(rawDigest);
65
- if (!callableKeys.has(digestScopedCallsTargetKey(digest, coordinate))) {
65
+ const usedTargets = args.callsTargets.filter((target) => target.includes('@') && parseVersionedCallTarget(target).coordinate === coordinate);
66
+ const targets = usedTargets.length > 0 ? usedTargets : [coordinate];
67
+ if (targets.some((target) => !callableKeys.has(digestScopedCallsTargetKey(digest, target)))) {
66
68
  throw new Error(`refusing bundle install: lock target '${coordinate}' pinned to ${digest} ` +
67
69
  'is no longer exactly callable from the combined workflow store');
68
70
  }
@@ -265,7 +267,6 @@ export async function installWorkflowBundle(args) {
265
267
  staged = new Map();
266
268
  try {
267
269
  const manifest = parseManifestBytes(readFileSync(manifestPath));
268
- externalVersionedCalls = new Set(Object.keys(manifest.lock));
269
270
  stagedBundleLock = manifest.lock;
270
271
  for (const [workflowName, workflowPath] of Object.entries(manifest.workflows)) {
271
272
  const workflowFile = join(stagingDir, workflowPath);
@@ -302,6 +303,10 @@ export async function installWorkflowBundle(args) {
302
303
  staged = loadDefsRaw(stagingDir, failures);
303
304
  reasons.push(...failures.map((failure) => `${failure.file}: ${failure.error}`));
304
305
  }
306
+ if (existsSync(manifestPath)) {
307
+ externalVersionedCalls = new Set([...staged.values()].flatMap((def) => def.steps.map((step) => step.calls)
308
+ .filter((target) => target !== undefined && isVersionedReference(target))));
309
+ }
305
310
  for (const stagedDef of staged.values()) {
306
311
  const lintResult = lintDef(stagedDef);
307
312
  reasons.push(...lintResult.errors.map((err) => `${stagedDef.name}: ${err}`));
@@ -374,6 +379,7 @@ export async function installWorkflowBundle(args) {
374
379
  projectRoot: args.projectRoot,
375
380
  globalRoot: args.globalRoot,
376
381
  lock: stagedBundleLock,
382
+ callsTargets: [...staged.values()].flatMap((def) => def.steps.map((step) => step.calls).filter((target) => target !== undefined)),
377
383
  ...(repairRequired ? { repairReplacement: { root, digest, objectDir: stagingDir } } : {}),
378
384
  });
379
385
  // The post-install index, computed BEFORE the commit point so its exact
@@ -9,7 +9,7 @@
9
9
  */
10
10
  import { join } from 'node:path';
11
11
  import { readFileSync } from 'node:fs';
12
- import { isVersionedReference, parseManifestBytes } from "../bundle/manifest.js";
12
+ import { isVersionedReference, parseManifestBytes, parseVersionedCallTarget } from "../bundle/manifest.js";
13
13
  import { defInstructionDigest } from "../order-resolver.js";
14
14
  import { digestScopedCallsTargetKey, finalizeDefs, loadDefFile, resolveCallsTarget } from "../defs.js";
15
15
  import { readWorkflowStoreIndex } from "./index-file.js";
@@ -150,8 +150,11 @@ export function createStoreInstructionSource(args) {
150
150
  };
151
151
  const selectLockedTarget = (target, childDigest, child) => {
152
152
  let coordinate;
153
+ let namedWorkflow;
153
154
  try {
154
- coordinate = parseWorkflowCoordinate(target);
155
+ const parsed = parseVersionedCallTarget(target);
156
+ coordinate = parseWorkflowCoordinate(parsed.coordinate);
157
+ namedWorkflow = parsed.workflow;
155
158
  }
156
159
  catch (error) {
157
160
  throw new StoreIntegrityError('object-corrupt', childDigest, `locked calls target '${target}' has an invalid coordinate: ${errorText(error)}`);
@@ -160,7 +163,7 @@ export function createStoreInstructionSource(args) {
160
163
  || coordinate.version !== child.manifest.package.version) {
161
164
  throw new StoreIntegrityError('object-corrupt', childDigest, `locked calls target '${target}' does not match child manifest package '${child.manifest.package.name}@${child.manifest.package.version}'`);
162
165
  }
163
- const workflowName = child.manifest.default
166
+ const workflowName = namedWorkflow ?? child.manifest.default
164
167
  ?? (child.defs.size === 1 ? child.defs.keys().next().value : undefined);
165
168
  if (workflowName === undefined) {
166
169
  throw new StoreIntegrityError('object-corrupt', childDigest, `locked calls target '${target}' digest ${childDigest} exports multiple workflows and has no default`);
@@ -181,10 +184,11 @@ export function createStoreInstructionSource(args) {
181
184
  if (step.calls === undefined || !isVersionedReference(step.calls))
182
185
  continue;
183
186
  const target = step.calls;
184
- if (!Object.prototype.hasOwnProperty.call(object.manifest.lock, target)) {
187
+ const lockKey = parseVersionedCallTarget(target).coordinate;
188
+ if (!Object.prototype.hasOwnProperty.call(object.manifest.lock, lockKey)) {
185
189
  throw new StoreIntegrityError('object-corrupt', object.bundleDigest, `locked calls target '${target}' has no entry in parent bundle ${object.bundleDigest} manifest lock`);
186
190
  }
187
- const childDigest = defDigest(object.manifest.lock[target]);
191
+ const childDigest = defDigest(object.manifest.lock[lockKey]);
188
192
  let child;
189
193
  for (const candidate of dependencyRoots(object)) {
190
194
  try {
@@ -0,0 +1,4 @@
1
+ export declare function createVerifiedBundleLockReader(args: {
2
+ projectRoot?: string;
3
+ globalRoot: string;
4
+ }): (digest: string) => Readonly<Record<string, string>>;
@@ -0,0 +1,38 @@
1
+ /** Read a bundle lock from verified CAS bytes without requiring an index row. */
2
+ import { readFileSync } from 'node:fs';
3
+ import { join } from 'node:path';
4
+ import { parseManifestBytes } from "../bundle/manifest.js";
5
+ import { verifyWorkflowObjectSync } from "./ingestor.js";
6
+ import { coordinateDigestReadSync, probeObjectDir, probeStoreRoot, projectStoreRoot } from "./resolve.js";
7
+ import { defDigest, objectDirForDigest, StoreIntegrityError } from "./types.js";
8
+ export function createVerifiedBundleLockReader(args) {
9
+ const roots = [args.projectRoot, args.globalRoot]
10
+ .filter((root) => root !== undefined)
11
+ .map(projectStoreRoot)
12
+ .filter((root, index, all) => all.indexOf(root) === index);
13
+ return (rawDigest) => {
14
+ const digest = defDigest(rawDigest);
15
+ for (const [index, root] of roots.entries()) {
16
+ const level = index === 0 && args.projectRoot !== undefined ? 'project' : 'global';
17
+ if (probeStoreRoot(root) === 'absent')
18
+ continue;
19
+ const objectDir = objectDirForDigest(root, digest);
20
+ try {
21
+ const lock = coordinateDigestReadSync(root, digest, () => {
22
+ if (probeObjectDir(objectDir, digest, level) === 'absent')
23
+ return undefined;
24
+ verifyWorkflowObjectSync(objectDir, digest, { coordinateRepair: false });
25
+ return parseManifestBytes(readFileSync(join(objectDir, 'bundle.yaml'))).lock;
26
+ });
27
+ if (lock !== undefined)
28
+ return lock;
29
+ }
30
+ catch (error) {
31
+ if (error instanceof StoreIntegrityError)
32
+ throw error;
33
+ throw new StoreIntegrityError('object-corrupt', digest, `${level}-level object could not be verified: ${error.message}`);
34
+ }
35
+ }
36
+ throw new StoreIntegrityError('object-missing', digest, 'parent bundle is absent from the project and global workflow stores');
37
+ };
38
+ }
package/dist/src/store.js CHANGED
@@ -16,6 +16,7 @@ import { DatabaseSync } from 'node:sqlite';
16
16
  import { lstatSync } from 'node:fs';
17
17
  import { detId, nowMs } from "./util.js";
18
18
  import { compareStoreText, defDigest, isDefDigest, parseWorkflowCoordinate } from "./store/types.js";
19
+ import { parseVersionedCallTarget } from "./bundle/manifest.js";
19
20
  import { withWorkflowSnapshotStoreGuard } from "./store/snapshot-guard.js";
20
21
  function exactCallsFromSnapshot(record, workflow) {
21
22
  const rawSteps = record.steps;
@@ -37,8 +38,9 @@ function exactCallsFromSnapshot(record, workflow) {
37
38
  }
38
39
  if (!calls.includes('@'))
39
40
  continue;
41
+ let lockKey;
40
42
  try {
41
- parseWorkflowCoordinate(calls);
43
+ lockKey = parseVersionedCallTarget(calls).coordinate;
42
44
  }
43
45
  catch (error) {
44
46
  throw new Error(`workflow '${workflow}' has malformed exact def_snapshot calls target ${JSON.stringify(calls)}: ` +
@@ -48,7 +50,7 @@ function exactCallsFromSnapshot(record, workflow) {
48
50
  if (typeof rawLock === 'object'
49
51
  && rawLock !== null
50
52
  && !Array.isArray(rawLock)
51
- && Object.prototype.hasOwnProperty.call(rawLock, calls))
53
+ && Object.prototype.hasOwnProperty.call(rawLock, lockKey))
52
54
  continue;
53
55
  exactCalls.add(calls);
54
56
  }
package/docs/authoring.md CHANGED
@@ -258,6 +258,18 @@ unresolvable path remains deferred until a valid value arrives.
258
258
  produced it. What bounds where a worker may actually run is machine-side and
259
259
  belongs to the operator running the shift, not to the definition.
260
260
 
261
+ The resolved value can also outlive the directory it names: a cleanup step
262
+ reclaims a worktree, then a rejection re-arms an earlier step whose workdir was
263
+ that worktree. A worker that is handed such an order does not spawn or open a
264
+ session there. It releases the order with the reason
265
+ `step workdir no longer exists: <absolute path>`, which the hub records as a
266
+ routing alert (`owenloop routing alerts --workflow <wf>`). The hub keeps only
267
+ the first such observation per workflow and step, so a worker that is offered
268
+ the same order again and releases it again adds no further rows. The release
269
+ is not a failure: the step stays eligible, and the fix is to supply a workdir
270
+ that exists (re-run the provisioning step, or provide a fresh path) rather
271
+ than to retry the order as-is.
272
+
261
273
  ## `executor:` — declaring the executor
262
274
 
263
275
  Every step in every def written before this feature dispatches to an LLM
package/docs/bundles.md CHANGED
@@ -75,13 +75,13 @@ The following rules apply:
75
75
  - `runtime` is optional. When present, `runtime` is a closed mapping that contains `minVersion`, `features`, or both; `runtime: {}` is invalid. Runtime requirements are described in [Runtime compatibility](#runtime-compatibility).
76
76
  - `workflows` is a non-empty map from workflow names to archive-relative YAML paths. Each workflow name matches `/^[a-z][a-z0-9-]*$/`. Each path must pass the canonical bundle path safety policy, and two workflow names may not point to the same path.
77
77
  - A workflow file's `name:` must equal the workflow map key. For example, `workflows.delivery` must point to a file containing `name: delivery`.
78
- - An installed workflow is addressable from `calls:` by the qualified name `<package>/<workflow>`. A bare `calls: <workflow>` inside a CAS-installed bundle is resolved to a sibling from that same bundle; it does not search unrelated bundles for a same-named workflow. For local-engine coordinate discovery, an exact versioned `calls: namespace/name@version` resolves through the verified store-index coordinate to the bundle's selected default workflow, then the engine checks the matching `lock` digest before creating the child. A worker validates the same edge differently: it follows only the verified parent manifest's pinned lock digest to a locally verified CAS object and never uses coordinator-supplied child definition bytes.
78
+ - An installed workflow is addressable from `calls:` by the qualified name `<package>/<workflow>`. A bare `calls: <workflow>` inside a CAS-installed bundle is resolved to a sibling from that same bundle; it does not search unrelated bundles for a same-named workflow. An exact `calls: namespace/package@version` selects the verified bundle's default (or sole) workflow. An exact `calls: namespace/package@version#workflow` selects that named workflow from the same verified bundle, whether or not it is the default. The `#workflow` suffix must match a registered `workflows` key; `#` is forbidden in store coordinates and the selector cannot be empty. Both forms use the base `namespace/package@version` as their `lock` key. The coordinator resolves through the verified store index and compares the selected child's bundle digest to that lock. A worker follows the verified parent's lock digest to a locally verified CAS object and selects the same workflow; it never uses coordinator-supplied child definition bytes.
79
79
  - `default` is optional. When present, `default` must be one of the workflow map keys. When absent, a single-workflow package has that one workflow as its implicit default. A package with two or more workflows has no implicit default: the versioned coordinate is not registered as a callable target, while explicit `<package>/<workflow>` targets remain available.
80
80
  - `platforms` is a duplicate-free list of portable selector strings. The list is advisory; platform policy is outside the package parser.
81
81
  - `integrity.algorithm` is exactly `sha256`.
82
82
  - `integrity.files` contains one lowercase 64-hex SHA-256 digest for every regular archive file except `bundle.yaml`. The packer regenerates this map from the source bytes and does not edit the source manifest. Excluding `bundle.yaml` avoids a recursive self-hash; the def digest still covers the complete canonical tar, including `bundle.yaml`.
83
83
  - `capabilities` contains requested capability classes and values. The manifest does not grant capabilities.
84
- - `lock` maps exact versioned `namespace/name@version` call references to lowercase 64-hex **bundle digests**. Every explicit versioned `calls:` target in every workflow must have a matching lock key. A bare same-bundle call has no lock entry: its pin is the containing bundle's own digest. The runtime compares bundle digests at child spawn; it does not compare this lock value with a per-workflow instruction digest.
84
+ - `lock` maps base exact coordinates `namespace/package@version` to lowercase 64-hex **bundle digests**. A named exact call `namespace/package@version#workflow` requires a lock at `namespace/package@version`; a selector is never a lock key. Every exact `calls:` target in every workflow must have a matching base-coordinate lock. A bare same-bundle call has no lock entry: its pin is the containing bundle's own digest. The runtime compares bundle digests at child spawn; it does not compare this lock value with a per-workflow instruction digest. Authors using named exact calls should declare `runtime.features: [exact-workflow-selector.v1]` so older engines refuse the bundle before executing it. Published Owenloop 0.5.30 and 0.5.25 do not support this feature. Use the first published release containing it as `runtime.minVersion` once released.
85
85
 
86
86
  Canonical manifest serialization uses the fixed top-level order `formatVersion`, `package`, optional `runtime`, `workflows`, optional `default`, `platforms`, `integrity`, `capabilities`, `lock`. Runtime fields use the order `minVersion`, then `features`; feature identifiers are sorted by ascending UTF-8 bytes. Other mapping keys and list values use their defined canonical order. Strings use JSON-style double quotes, indentation is two spaces, and the document has exactly one final newline. Inspection rejects a manifest that parses correctly but is not in that canonical byte form.
87
87
 
@@ -105,6 +105,7 @@ The mapping is strict and closed. Unknown keys are rejected. At least one of `mi
105
105
 
106
106
  This Owenloop release advertises exactly these feature identifiers:
107
107
 
108
+ - `exact-workflow-selector.v1`
108
109
  - `harness-policy-enforcement.v1`
109
110
  - `native-judge-policy-inheritance.v1`
110
111
  - `neutral-approval-modes.v1`
package/docs/cli.md CHANGED
@@ -290,7 +290,8 @@ that field a **crew**: `serve_crews` contains the selected crew names. Passing
290
290
  the Scoped Identity. Do not treat `attended_at` as a liveness signal: every
291
291
  accepted `shift next` records attendance and makes the next presence ping due,
292
292
  but attendance is advisory and observability-only. Attendance never changes
293
- routing, dispatch, or lease behavior.
293
+ routing, dispatch, or lease behavior. The liveness signal is `last_poll_at` on
294
+ `shift status` — see [`shift status`](#shift-status---state-dir-path).
294
295
 
295
296
  <a id="config-dir"></a>
296
297
  By default, the execution settings file is `$HOME/.owenloop/settings.json`.
@@ -384,13 +385,31 @@ Only a workdir the ORDER names is checked. A step that declares neither
384
385
  controls — the shift's own launch directory for a command step, or
385
386
  `<workRoot>/<workflow>/<run>/` for an agent step — and is never denied.
386
387
 
388
+ The same two workers make one more check on an order-named workdir, right after
389
+ the roots check: the directory must still **exist** on this machine and be a
390
+ directory. A `workdirFrom:` value can outlive what it names — a cleanup step
391
+ reclaims a worktree, then a rejection re-arms an earlier step whose workdir was
392
+ that worktree — and spawning there used to fail inside the command or the
393
+ harness with a message that never mentioned the cwd. Now `owenloop work exec`
394
+ and `owenloop work agent-run` refuse before anything is spawned or any session
395
+ opens. The shape is the same as the roots refusal: a **release**, not a
396
+ failure. The worker releases its claim with the reason
397
+ `step workdir no longer exists: <absolute path>`, exits non-zero (outcome
398
+ `workdir-missing`, exit 1), and writes one line to `<log-dir>/<run>.log` naming
399
+ the path. The step stays eligible and the order returns to the pickup window;
400
+ the hub records the reason as a routing alert (`owenloop routing alerts
401
+ --workflow <wf>`), keeping only the first observation per workflow and step. The
402
+ roots check runs first, so a workdir that is both outside the roots and missing
403
+ is reported as denied, not missing. A step that names no workdir is never
404
+ existence-checked — its fallback directory is one owenloop itself controls.
405
+
387
406
  `--work-root` is not `--work-root`'s neighbour `workRoot`. `workRoot` (settings,
388
407
  `OWENLOOP_WORK_ROOT`) is the ONE directory owenloop **creates** per-run
389
408
  directories under. `--work-root` / `allowedWorkdirRoots` is the SET of
390
409
  directories an order is **allowed to name**. Neither derives from the other.
391
410
 
392
411
  ```bash
393
- owenloop shift start build --work-root ~/code --work-root /srv/work
412
+ owenloop shift start openai --work-root ~/code --work-root /srv/work
394
413
  ```
395
414
 
396
415
  **Crew roster selection.** A selected roster candidate decides
@@ -590,24 +609,28 @@ either `exec` or `agent-run`:
590
609
  - `order-dropped`: `{ "type": "order-dropped", "workflow": "...", "run": "...", "step": "...", "reason": "unsupported-worker", "message": "..." }` — the shift refused one order. Match on `reason` (`malformed-digest`, `malformed-worker`, `unsupported-worker`, `verification-failed`, `metadata-unavailable`, `agent-lane-closed`, `dispatch-cap-full`, `agent-cap-full`, `claim-expired`); display `message`. The capacity, expiry, and `agent-lane-closed` reasons return the claim to the hub; malformed and unsupported reasons leave it for the pickup window.
591
610
  - `ended`: `{ "type": "ended" }`, delivered to a parked `next` when `shift end` explicitly shuts down the daemon
592
611
  - `wedged`: `{ "type": "wedged", "faults": [{ "kind": "missing", "role": "temp-dir", "path": "...", "message": "..." }], "streak": 3 }` — the shift stopped because the MACHINE it runs on is broken, and the process exits non-zero straight after. `faults` is never empty; display each `message`, which names the path and the operator fix. `streak` is how many consecutive hub calls failed before the check ran, and is `0` for the check a shift makes at start. A shift that cannot reach the hub does NOT produce this — a hub outage or a rate-limit ban recovers on its own, and the shift keeps polling through it. This record means a human must change something on the host.
612
+ - `stalled`: `{ "type": "stalled", "lastPollAt": 1738000000000, "sinceMs": 45000 }` — the poll loop has made no progress (no hub call settled, no cycle completed) for longer than the stall threshold (three poll intervals plus the per-call hub deadline, 45 s at the defaults). It is written by a watchdog timer that does not depend on the loop, so it is the one record a hung loop cannot suppress. `lastPollAt` is the last completed cycle (epoch ms, `null` if none completed since start) and `sinceMs` is how long the loop has made no progress. A hub that stops answering does not produce this: every poll-loop hub call settles within its deadline and is reported as `hub-error` records and the `wedged` streak; `stalled` is the backstop for a hang that is not under a deadline (local dispatch, the filesystem, a spawn, or any other non-hub await inside the iteration). **Edge-triggered**: one record per stall episode, re-armed when a cycle completes. A hub-instructed `Retry-After` pause is not a stall and produces none. Compare `last_poll_at` on `shift status` to confirm.
593
613
 
594
614
  Every event above is also appended to `<log-dir>/shift.log` as JSON Lines, which
595
- is how they survive the daemon. **Five further record types exist in
615
+ is how they survive the daemon. **Six further record types exist in
596
616
  `shift.log` and are never delivered over the socket** — `parked`, `capacity`,
597
- `hub-error`, `event-queue-overflow`, and `low-disk`.
617
+ `hub-error`, `event-queue-overflow`, `low-disk`, and `heartbeat`.
598
618
 
599
619
  An idle `shift next` must block until there is work to report, and each of those
600
- five would satisfy it with news that no work moved: a startup record, a report
620
+ six would satisfy it with news that no work moved: a startup record, a report
601
621
  that the shift is full, a failed call to the hub, a record about the socket
602
- queue itself, or a report that the disk is too full to start anything. `parked` and `capacity` are also redundant on the wire — the
622
+ queue itself, a report that the disk is too full to start anything, or the
623
+ periodic heartbeat (every five minutes) that says only that the daemon is still
624
+ alive and how many poll cycles it has completed. `parked` and `capacity` are also redundant on the wire — the
603
625
  response above already carries live `cap`, `free`, and `running`, which is
604
626
  exactly what a `capacity` record restates. `hub-error` is level-triggered at the
605
627
  poll interval, so an unreachable hub would otherwise fill the 1000-slot socket
606
628
  FIFO and evict the `dispatched`, `failed` and `reaped` records a parked client
607
629
  is actually waiting for. In `shift.log`, which is append-only and unbounded, all
608
- four are load-bearing: they are the only way to tell an idle shift from a
609
- saturated one, and the only record of every failed hub call. See
610
- [`docs/shift-logs.md`](shift-logs.md).
630
+ of them are load-bearing: they are the only way to tell an idle shift from a
631
+ saturated one, the only record of every failed hub call, and — through
632
+ `heartbeat` — the only way to tell a daemon that is alive but no longer polling
633
+ from one that is merely quiet. See [`docs/shift-logs.md`](shift-logs.md).
611
634
 
612
635
  `gate` is a reserved protocol shape for a future local representation of a
613
636
  pending hub gate. Production code does not construct live hub gate events yet;
@@ -633,13 +656,18 @@ owenloop shift status [--state-dir <p>]
633
656
  With a daemon, status exits `0` and prints:
634
657
 
635
658
  ```json
636
- { "name": "host/project#abc123", "serve_crews": ["alpha"], "cap": 3, "free": 3, "running": 0, "agent_ceiling": 2, "attended_at": null, "started_at": 1738000000000 }
659
+ { "name": "host/project#abc123", "serve_crews": ["alpha"], "cap": 3, "free": 3, "running": 0, "agent_ceiling": 2, "attended_at": null, "started_at": 1738000000000, "last_poll_at": 1738000005000, "cycles_completed": 1 }
637
660
  ```
638
661
 
639
662
  `agent_ceiling` is the effective maximum number of `agent-run` children after
640
663
  applying `--max-agents`, `--cap`, and `--exec-reserve`; command and exec work
641
664
  may still use any free slot inside `cap`. `attended_at` remains `null` until the
642
- first accepted `next` request. Without a daemon, status is still a successful question: it exits `0` and prints
665
+ first accepted `next` request. `last_poll_at` (epoch ms) and `cycles_completed`
666
+ are the liveness facts: they move only when the poll loop completes a full
667
+ cycle, so a daemon that still answers `status` but whose `last_poll_at` is
668
+ minutes old and whose `cycles_completed` no longer climbs has a loop that is
669
+ hung or wedged, not merely idle. `last_poll_at` is `null` until the first cycle
670
+ completes. Without a daemon, status is still a successful question: it exits `0` and prints
643
671
  `{ "status": "no daemon", "socket": "<path>" }`. Invalid arguments exit `2`;
644
672
  other client/runtime errors exit `1`.
645
673