owenloop 0.5.0 → 0.5.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (229) hide show
  1. package/CHANGELOG.md +67 -0
  2. package/README.md +144 -35
  3. package/bin/owenloop.mjs +49 -1
  4. package/dist/packages/work/src/agent/brief.d.ts +29 -4
  5. package/dist/packages/work/src/agent/brief.js +49 -4
  6. package/dist/packages/work/src/agent/capability-model.d.ts +123 -0
  7. package/dist/packages/work/src/agent/capability-model.js +148 -0
  8. package/dist/packages/work/src/agent/loop.d.ts +56 -7
  9. package/dist/packages/work/src/agent/loop.js +166 -9
  10. package/dist/packages/work/src/bundle/cache.d.ts +7 -5
  11. package/dist/packages/work/src/bundle/cache.js +20 -6
  12. package/dist/packages/work/src/bundle/fetch.d.ts +7 -5
  13. package/dist/packages/work/src/bundle/fetch.js +27 -7
  14. package/dist/packages/work/src/bundle/types.d.ts +8 -4
  15. package/dist/packages/work/src/consumed-verifier.d.ts +45 -0
  16. package/dist/packages/work/src/consumed-verifier.js +205 -0
  17. package/dist/packages/work/src/exec/instructions.d.ts +99 -0
  18. package/dist/packages/work/src/exec/instructions.js +323 -0
  19. package/dist/packages/work/src/exec/loop.d.ts +29 -1
  20. package/dist/packages/work/src/exec/loop.js +313 -35
  21. package/dist/packages/work/src/exec/payload.d.ts +29 -0
  22. package/dist/packages/work/src/exec/payload.js +54 -0
  23. package/dist/packages/work/src/exec/receipt.d.ts +9 -6
  24. package/dist/packages/work/src/exec/receipt.js +12 -1
  25. package/dist/packages/work/src/exec/runner.d.ts +7 -1
  26. package/dist/packages/work/src/exec/runner.js +84 -3
  27. package/dist/packages/work/src/harness/child-env.js +7 -0
  28. package/dist/packages/work/src/harness/claude.d.ts +20 -8
  29. package/dist/packages/work/src/harness/claude.js +260 -58
  30. package/dist/packages/work/src/harness/codex.d.ts +5 -4
  31. package/dist/packages/work/src/harness/codex.js +169 -41
  32. package/dist/packages/work/src/harness/contract.d.ts +36 -11
  33. package/dist/packages/work/src/harness/fake.js +1 -0
  34. package/dist/packages/work/src/harness/jsonrpc-stdio.js +7 -0
  35. package/dist/packages/work/src/harness/permissions.d.ts +16 -3
  36. package/dist/packages/work/src/harness/permissions.js +102 -13
  37. package/dist/packages/work/src/harness/session-store.d.ts +30 -10
  38. package/dist/packages/work/src/harness/session-store.js +317 -89
  39. package/dist/packages/work/src/hold/mcp.d.ts +25 -5
  40. package/dist/packages/work/src/hold/mcp.js +134 -12
  41. package/dist/packages/work/src/hub/client.d.ts +8 -1
  42. package/dist/packages/work/src/hub/client.js +15 -1
  43. package/dist/packages/work/src/hub/types.d.ts +137 -33
  44. package/dist/packages/work/src/hub/types.js +8 -10
  45. package/dist/packages/work/src/mcp/server.js +1 -1
  46. package/dist/packages/work/src/owenloop-bin.d.ts +1 -0
  47. package/dist/packages/work/src/owenloop-bin.js +18 -0
  48. package/dist/packages/work/src/roles/agent-run.d.ts +12 -6
  49. package/dist/packages/work/src/roles/agent-run.js +115 -34
  50. package/dist/packages/work/src/roles/exec.d.ts +8 -0
  51. package/dist/packages/work/src/roles/exec.js +27 -2
  52. package/dist/packages/work/src/roles/hold.d.ts +6 -0
  53. package/dist/packages/work/src/roles/hold.js +83 -13
  54. package/dist/packages/work/src/roles/lint.d.ts +3 -4
  55. package/dist/packages/work/src/roles/lint.js +41 -7
  56. package/dist/packages/work/src/roles/settings.js +19 -2
  57. package/dist/packages/work/src/roles/shift.d.ts +1 -0
  58. package/dist/packages/work/src/roles/shift.js +36 -2
  59. package/dist/packages/work/src/settings/settings.d.ts +70 -1
  60. package/dist/packages/work/src/settings/settings.js +90 -4
  61. package/dist/packages/work/src/shift/logretention.d.ts +253 -0
  62. package/dist/packages/work/src/shift/logretention.js +407 -0
  63. package/dist/packages/work/src/shift/logsink.d.ts +14 -0
  64. package/dist/packages/work/src/shift/logsink.js +98 -0
  65. package/dist/packages/work/src/shift/loop.d.ts +32 -4
  66. package/dist/packages/work/src/shift/loop.js +687 -166
  67. package/dist/packages/work/src/shift/protocol.d.ts +128 -1
  68. package/dist/packages/work/src/shift/protocol.js +14 -0
  69. package/dist/packages/work/src/shift/runtime.d.ts +16 -0
  70. package/dist/packages/work/src/shift/runtime.js +291 -5
  71. package/dist/packages/work/src/shift/server.d.ts +13 -0
  72. package/dist/packages/work/src/shift/server.js +61 -36
  73. package/dist/packages/work/src/shift/spawn.d.ts +115 -19
  74. package/dist/packages/work/src/shift/spawn.js +234 -30
  75. package/dist/packages/work/src/shift/state.d.ts +76 -49
  76. package/dist/packages/work/src/shift/state.js +350 -103
  77. package/dist/packages/work/src/shift/truncate.d.ts +35 -0
  78. package/dist/packages/work/src/shift/truncate.js +73 -0
  79. package/dist/packages/work/src/submit-proof.d.ts +61 -0
  80. package/dist/packages/work/src/submit-proof.js +119 -0
  81. package/dist/packages/work/src/submit-value.d.ts +48 -0
  82. package/dist/packages/work/src/submit-value.js +118 -0
  83. package/dist/packages/work/src/usage.d.ts +1 -1
  84. package/dist/packages/work/src/usage.js +11 -0
  85. package/dist/src/add.d.ts +64 -259
  86. package/dist/src/add.js +81 -615
  87. package/dist/src/archive.d.ts +97 -0
  88. package/dist/src/archive.js +591 -0
  89. package/dist/src/bundle/index.d.ts +64 -0
  90. package/dist/src/bundle/index.js +508 -0
  91. package/dist/src/bundle/manifest.d.ts +50 -0
  92. package/dist/src/bundle/manifest.js +435 -0
  93. package/dist/src/bundle/runtime.d.ts +26 -0
  94. package/dist/src/bundle/runtime.js +64 -0
  95. package/dist/src/bundle/tar.d.ts +62 -0
  96. package/dist/src/bundle/tar.js +238 -0
  97. package/dist/src/bundle/types.d.ts +105 -0
  98. package/dist/src/bundle/types.js +21 -0
  99. package/dist/src/capabilities.d.ts +93 -0
  100. package/dist/src/capabilities.js +101 -0
  101. package/dist/src/cli.d.ts +90 -20
  102. package/dist/src/cli.js +2421 -374
  103. package/dist/src/credentials.d.ts +4 -3
  104. package/dist/src/credentials.js +21 -19
  105. package/dist/src/crypto/allowed-signers.d.ts +68 -0
  106. package/dist/src/crypto/allowed-signers.js +307 -0
  107. package/dist/src/crypto/canonical.d.ts +8 -0
  108. package/dist/src/crypto/canonical.js +92 -0
  109. package/dist/src/crypto/chain.d.ts +65 -0
  110. package/dist/src/crypto/chain.js +377 -0
  111. package/dist/src/crypto/dsse.d.ts +209 -0
  112. package/dist/src/crypto/dsse.js +282 -0
  113. package/dist/src/crypto/enrollment.d.ts +78 -0
  114. package/dist/src/crypto/enrollment.js +186 -0
  115. package/dist/src/crypto/index.d.ts +48 -0
  116. package/dist/src/crypto/index.js +44 -0
  117. package/dist/src/crypto/keys.d.ts +258 -0
  118. package/dist/src/crypto/keys.js +908 -0
  119. package/dist/src/crypto/org-root.d.ts +33 -0
  120. package/dist/src/crypto/org-root.js +78 -0
  121. package/dist/src/crypto/origin-rules.d.ts +56 -0
  122. package/dist/src/crypto/origin-rules.js +143 -0
  123. package/dist/src/crypto/policy-floor.d.ts +98 -0
  124. package/dist/src/crypto/policy-floor.js +353 -0
  125. package/dist/src/crypto/records.d.ts +319 -0
  126. package/dist/src/crypto/records.js +168 -0
  127. package/dist/src/crypto/scope.d.ts +49 -0
  128. package/dist/src/crypto/scope.js +83 -0
  129. package/dist/src/crypto/ssh.d.ts +171 -0
  130. package/dist/src/crypto/ssh.js +396 -0
  131. package/dist/src/crypto/submission.d.ts +33 -0
  132. package/dist/src/crypto/submission.js +47 -0
  133. package/dist/src/crypto/trust-roots.d.ts +29 -0
  134. package/dist/src/crypto/trust-roots.js +39 -0
  135. package/dist/src/crypto/verify-consumed.d.ts +67 -0
  136. package/dist/src/crypto/verify-consumed.js +259 -0
  137. package/dist/src/crypto/verify-origin.d.ts +50 -0
  138. package/dist/src/crypto/verify-origin.js +151 -0
  139. package/dist/src/crypto/verify-publication.d.ts +60 -0
  140. package/dist/src/crypto/verify-publication.js +150 -0
  141. package/dist/src/defs.d.ts +24 -1
  142. package/dist/src/defs.js +335 -27
  143. package/dist/src/engine.d.ts +211 -6
  144. package/dist/src/engine.js +459 -59
  145. package/dist/src/factory.d.ts +16 -0
  146. package/dist/src/factory.js +16 -4
  147. package/dist/src/global-config.d.ts +59 -0
  148. package/dist/src/global-config.js +84 -0
  149. package/dist/src/hub.d.ts +102 -32
  150. package/dist/src/hub.js +147 -58
  151. package/dist/src/index.d.ts +19 -2
  152. package/dist/src/index.js +23 -2
  153. package/dist/src/install.d.ts +538 -0
  154. package/dist/src/install.js +1981 -0
  155. package/dist/src/lock.d.ts +15 -57
  156. package/dist/src/lock.js +251 -143
  157. package/dist/src/mcp/serve.d.ts +46 -22
  158. package/dist/src/mcp/serve.js +174 -44
  159. package/dist/src/mcp/server.js +12 -1
  160. package/dist/src/model.d.ts +51 -0
  161. package/dist/src/model.js +157 -1
  162. package/dist/src/order-resolver.d.ts +184 -0
  163. package/dist/src/order-resolver.js +252 -0
  164. package/dist/src/package-version.d.ts +10 -0
  165. package/dist/src/package-version.js +42 -0
  166. package/dist/src/paths.d.ts +14 -1
  167. package/dist/src/paths.js +18 -0
  168. package/dist/src/schemas/enrollment-grant.v1.schema.json +90 -0
  169. package/dist/src/schemas/index.d.ts +1433 -0
  170. package/dist/src/schemas/index.js +31 -0
  171. package/dist/src/schemas/order.v1.schema.json +120 -0
  172. package/dist/src/schemas/origin.v1.schema.json +68 -0
  173. package/dist/src/schemas/policy-floor.v1.schema.json +29 -0
  174. package/dist/src/schemas/publication.v1.schema.json +31 -0
  175. package/dist/src/schemas/revocation.v1.schema.json +39 -0
  176. package/dist/src/schemas/submission.v1.schema.json +61 -0
  177. package/dist/src/store/def-source.d.ts +52 -0
  178. package/dist/src/store/def-source.js +335 -0
  179. package/dist/src/store/index-file.d.ts +69 -0
  180. package/dist/src/store/index-file.js +151 -0
  181. package/dist/src/store/index.d.ts +27 -0
  182. package/dist/src/store/index.js +22 -0
  183. package/dist/src/store/ingestor.d.ts +43 -0
  184. package/dist/src/store/ingestor.js +211 -0
  185. package/dist/src/store/install.d.ts +228 -0
  186. package/dist/src/store/install.js +555 -0
  187. package/dist/src/store/instruction-source.d.ts +49 -0
  188. package/dist/src/store/instruction-source.js +298 -0
  189. package/dist/src/store/origin-evidence.d.ts +21 -0
  190. package/dist/src/store/origin-evidence.js +66 -0
  191. package/dist/src/store/pre-commit-verifier.d.ts +68 -0
  192. package/dist/src/store/pre-commit-verifier.js +418 -0
  193. package/dist/src/store/resolve.d.ts +138 -0
  194. package/dist/src/store/resolve.js +363 -0
  195. package/dist/src/store/types.d.ts +288 -0
  196. package/dist/src/store/types.js +356 -0
  197. package/dist/src/store.d.ts +33 -1
  198. package/dist/src/store.js +57 -4
  199. package/dist/src/types.d.ts +146 -12
  200. package/dist/src/untar.d.ts +8 -23
  201. package/dist/src/untar.js +10 -136
  202. package/docs/agent-runner.md +86 -0
  203. package/docs/authoring.md +64 -6
  204. package/docs/bundles.md +350 -0
  205. package/docs/cli.md +1298 -106
  206. package/docs/crypto.md +832 -0
  207. package/docs/design.md +342 -20
  208. package/docs/embedding.md +132 -25
  209. package/docs/shift-logs.md +642 -0
  210. package/docs/wire-contracts.md +395 -0
  211. package/package.json +6 -1
  212. package/plugins/claude-code/.claude-plugin/marketplace.json +14 -0
  213. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +8 -0
  214. package/plugins/claude-code/plugin/.mcp.json +14 -0
  215. package/plugins/claude-code/plugin/hooks/hooks.json +26 -0
  216. package/plugins/claude-code/plugin/hooks/session-end.sh +40 -0
  217. package/plugins/claude-code/plugin/hooks/session-start.sh +52 -0
  218. package/plugins/claude-code/plugin/skills/author/SKILL.md +181 -0
  219. package/plugins/claude-code/plugin/skills/conduct/SKILL.md +106 -0
  220. package/plugins/claude-code/plugin/skills/shift/SKILL.md +105 -0
  221. package/plugins/codex/.agents/plugins/marketplace.json +21 -0
  222. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +7 -0
  223. package/plugins/codex/plugins/owenloop/.mcp.json +20 -0
  224. package/plugins/codex/plugins/owenloop/hooks/hooks.json +26 -0
  225. package/plugins/codex/plugins/owenloop/hooks/session-end.sh +40 -0
  226. package/plugins/codex/plugins/owenloop/hooks/session-start.sh +52 -0
  227. package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +181 -0
  228. package/plugins/codex/plugins/owenloop/skills/conduct/SKILL.md +106 -0
  229. package/plugins/codex/plugins/owenloop/skills/shift/SKILL.md +105 -0
@@ -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. */
@@ -65,7 +69,130 @@ export interface GateEvent {
65
69
  export interface EndedEvent {
66
70
  type: 'ended';
67
71
  }
68
- export type ShiftEvent = DispatchedEvent | ReapedEvent | FailedEvent | GateEvent | EndedEvent;
72
+ /**
73
+ * The shift announced its identity and started serving. The FIRST record a
74
+ * shift writes, so a reader can place every later record on the same machine
75
+ * without external context. `shift` and `shiftId` are not repeated here: they
76
+ * are on the envelope of this and every other record.
77
+ *
78
+ * FILE-ONLY. Written to `shift.log` and never delivered over the socket. An
79
+ * idle `owenloop shift next` must BLOCK until there is work to report, and a
80
+ * startup record sitting in the FIFO would satisfy the first `next` after every
81
+ * start. A socket client needs none of this — it knows which shift it reached
82
+ * because it connected to that shift's socket, and `op: 'status'` answers name,
83
+ * crews, and cap on demand.
84
+ */
85
+ export interface ParkedEvent {
86
+ type: 'parked';
87
+ origin: string;
88
+ cap: number;
89
+ serveCrews: string[];
90
+ hostname: string;
91
+ cwd: string;
92
+ }
93
+ /**
94
+ * No local capacity, so the `whats_next` SWEEP was deferred. Explains a shift
95
+ * that is running nothing new while work remains outstanding.
96
+ *
97
+ * NOT "the hub was not polled" — `opts.hub.wake(cursor)` runs every tick
98
+ * regardless of local capacity. Only the follow-up sweep is skipped, so this
99
+ * record means "there was news and I had nowhere to put it".
100
+ *
101
+ * EDGE-TRIGGERED: AT MOST one record per unbroken stretch at capacity, emitted
102
+ * when the shift ENTERS that state, not once per tick while it stays there. How
103
+ * long the stretch lasted is recoverable from the next record's `ts`.
104
+ *
105
+ * At most, not exactly: the emit sits inside `loop.ts`'s `changed && k <= 0`
106
+ * branch, so it needs a wake that reports a CHANGED cursor. A shift that fills
107
+ * up and stays full while the hub reports nothing new produces no record at all,
108
+ * and the absence of one is not evidence the shift had free slots.
109
+ *
110
+ * FILE-ONLY, for the same reason as `ParkedEvent`. On the socket it is both
111
+ * redundant and harmful: every `ShiftCapacity` response already carries live
112
+ * `cap`, `free`, and `running`, so this record restates on the wire what the
113
+ * response states anyway — and queueing it satisfies a parked `next` with news
114
+ * that nothing happened. In the file, which has no response envelope, it is the
115
+ * only thing distinguishing a saturated shift from an idle one.
116
+ */
117
+ export interface CapacityEvent {
118
+ type: 'capacity';
119
+ inFlight: number;
120
+ cap: number;
121
+ }
122
+ /** A hub call failed. `workflow` is present only for per-workflow calls. */
123
+ export interface HubErrorEvent {
124
+ type: 'hub-error';
125
+ op: 'wake' | 'whats_next';
126
+ workflow?: string;
127
+ message: string;
128
+ }
129
+ /** A legacy order named a def with no cached bundle, so it was left for pickup. */
130
+ export interface BundleMissEvent {
131
+ type: 'bundle-miss';
132
+ workflow: string;
133
+ def: string;
134
+ }
135
+ /**
136
+ * The shift refused one order and left it for the hub pickup window. A dropped
137
+ * unit of work, which is why it is a record and not a debug aside. `reason` is
138
+ * the stable machine discriminator; `message` is the human text.
139
+ */
140
+ export interface OrderDroppedEvent {
141
+ type: 'order-dropped';
142
+ workflow: string;
143
+ run: string;
144
+ step: string;
145
+ reason: 'malformed-digest' | 'malformed-worker' | 'unsupported-worker' | 'verification-failed' | 'metadata-unavailable';
146
+ message: string;
147
+ }
148
+ /**
149
+ * The socket event FIFO overflowed and discarded its oldest event. Written
150
+ * STRAIGHT to the file sink, never through the loop's `emit()` — `emit()` feeds
151
+ * the very queue that overflowed, so routing this through it would recurse
152
+ * under exactly the load that produced it. `dropped` is cumulative for the
153
+ * shift process, so each record states the running total lost so far.
154
+ */
155
+ export interface EventQueueOverflowEvent {
156
+ type: 'event-queue-overflow';
157
+ dropped: number;
158
+ }
159
+ /**
160
+ * What a construction site builds: the event's own payload, with no identity
161
+ * and no timestamp. Every consumer receives the stamped `ShiftEvent` instead.
162
+ */
163
+ export type ShiftEventBody = DispatchedEvent | ReapedEvent | FailedEvent | GateEvent | EndedEvent | ParkedEvent | CapacityEvent | HubErrorEvent | BundleMissEvent | OrderDroppedEvent | EventQueueOverflowEvent;
164
+ /**
165
+ * The identity every event carries, added once on a shared envelope rather than
166
+ * per variant.
167
+ *
168
+ * This is what makes one record SELF-DESCRIBING: a consumer holding a single
169
+ * line from an unknown machine can place it in time (`ts`) and attribute it to
170
+ * one shift process (`shiftId`) with no external context. That property is what
171
+ * lets the on-disk log, the socket, and a future uploader be three consumers of
172
+ * ONE contract instead of three shapes.
173
+ */
174
+ export interface ShiftEventEnvelope {
175
+ /** ISO-8601 UTC with milliseconds, e.g. `2026-08-13T18:04:11.412Z`. */
176
+ ts: string;
177
+ /** The shift's human name — live-mutable via `clock_in`, so it can change between records. */
178
+ shift: string;
179
+ /** The shift process incarnation's id (`shf_<uuid>`); `''` when undeclared. Stable for the process. */
180
+ shiftId: string;
181
+ }
182
+ /** A body plus its envelope: what every consumer actually receives. */
183
+ export type ShiftEvent = ShiftEventBody & ShiftEventEnvelope;
184
+ /** Who emitted an event. `id` is `''` when the emitter declared no shift id. */
185
+ export interface ShiftIdentity {
186
+ name: string;
187
+ id: string;
188
+ }
189
+ /**
190
+ * Stamp a body with its envelope. The ONE place the envelope is constructed —
191
+ * every emitter (the loop's `emit()`, the daemon's `ended`, the runtime's worker
192
+ * failures and startup record) routes through here so no consumer can receive a
193
+ * half-stamped record.
194
+ */
195
+ export declare function stampShiftEvent(body: ShiftEventBody, identity: ShiftIdentity, now: number): ShiftEvent;
69
196
  export interface ShiftCapacity {
70
197
  cap: number;
71
198
  free: number;
@@ -19,6 +19,20 @@ export const RESPONSE_TRUNCATION_MARKER = '[truncated]';
19
19
  export const MAX_EVENT_QUEUE = 1_000;
20
20
  export const OVERLAP_ERROR = 'whats_next is already parked — one park at a time (cancel it or wait for it to return)';
21
21
  export const NO_DAEMON_SUFFIX = ' — start one with: owenloop shift start <crew…>';
22
+ /**
23
+ * Stamp a body with its envelope. The ONE place the envelope is constructed —
24
+ * every emitter (the loop's `emit()`, the daemon's `ended`, the runtime's worker
25
+ * failures and startup record) routes through here so no consumer can receive a
26
+ * half-stamped record.
27
+ */
28
+ export function stampShiftEvent(body, identity, now) {
29
+ return {
30
+ ...body,
31
+ ts: new Date(now).toISOString(),
32
+ shift: identity.name,
33
+ shiftId: identity.id,
34
+ };
35
+ }
22
36
  export function isShiftError(value) {
23
37
  return typeof value === 'object' && value !== null && typeof value.error === 'string';
24
38
  }
@@ -1,5 +1,15 @@
1
+ import { type ShiftEventBody } from './protocol.ts';
1
2
  import { installSignalHandlers, type SignalHost } from '../roles/signals.ts';
2
3
  export { installSignalHandlers, type SignalHost };
4
+ /**
5
+ * Does this event type reach the SOCKET consumer (a parked `owenloop shift
6
+ * next`), or only `shift.log`?
7
+ *
8
+ * The routing rule as a pure predicate so it can be asserted directly rather
9
+ * than only through a daemon's timing. `consumeEvent` is its one production
10
+ * caller; a `false` here means the record still reaches the file.
11
+ */
12
+ export declare function reachesSocketConsumer(type: ShiftEventBody['type']): boolean;
3
13
  export declare function resolveCap(flagCap: number | undefined, settingsCap: number | undefined): number;
4
14
  export declare function resolveStateDirOverride(flag: string | undefined, env: Record<string, string | undefined>, settingsStateDir: string | undefined): string | undefined;
5
15
  export declare function resolveMaxConcurrentAgents(flagMax: number | undefined, settingsMax: number | undefined): number;
@@ -21,6 +31,10 @@ export interface ParsedArgs {
21
31
  maxAgents?: number;
22
32
  cacheDir?: string;
23
33
  stateDir?: string;
34
+ /** `--log-dir` — where `shift.log` and `<run>.log` are written. */
35
+ logDir?: string;
36
+ /** `--log-max-age` — worker-log retention in milliseconds. `0` reaps eagerly. */
37
+ logMaxAgeMs?: number;
24
38
  error?: string;
25
39
  }
26
40
  /** Parse shift's internal `--flag value` and `--flag=value` forms. */
@@ -33,6 +47,8 @@ export interface ShiftRuntimeOptions {
33
47
  /** Socket path selected by the shift command. */
34
48
  socketPath?: string;
35
49
  }
50
+ /** Public Shift daemon transport is a Unix-domain socket on macOS and Linux. */
51
+ export declare function assertShiftDaemonPlatform(platform?: NodeJS.Platform): void;
36
52
  /**
37
53
  * Shared runtime setup for the internal shift and public shift daemon.
38
54
  * `parsed` is already grammar-validated by the caller; this function owns all
@@ -9,17 +9,22 @@
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";
15
16
  import { resolveCacheDir } from "../bundle/cache.js";
16
17
  import { createShiftLoop } from "./loop.js";
18
+ import { createShiftLogSink } from "./logsink.js";
19
+ import { prepareShiftLogDir, shiftLogFile } from "./logretention.js";
20
+ import { stampShiftEvent } from "./protocol.js";
17
21
  import { createDefaultSpawner } from "./spawn.js";
18
22
  import { resolveStateDir, ensureStateDir, reconcileInFlight } from "./state.js";
19
23
  import { reconcileActiveSessions, sessionsPath } from "../harness/session-store.js";
20
24
  import { resolveWorkRepo, resolveWorkRoot } from "../agent/workdir.js";
21
25
  import { installSignalHandlers } from "../roles/signals.js";
22
26
  import { createShiftDaemon } from "./server.js";
27
+ import { createBundleIngestor, createStoreInstructionSource, globalStoreRoot, } from "../../../../src/store/index.js";
23
28
  // Re-exported so existing importers keep their import site while the
24
29
  // implementation lives in the shared signals seam.
25
30
  export { installSignalHandlers };
@@ -27,6 +32,73 @@ const DEFAULT_CAP = 3;
27
32
  const DEFAULT_POLL_MS = 5_000;
28
33
  const DEFAULT_MAX_AGENTS = 4;
29
34
  const DEFAULT_PRESENCE_MS = 60_000;
35
+ /**
36
+ * Record types written to the LOG FILE but never delivered over the socket.
37
+ *
38
+ * The split is not "important vs unimportant" — it is what each consumer is.
39
+ * A record about a UNIT OF WORK THAT MOVED (`dispatched`, `reaped`, `failed`,
40
+ * `order-dropped`, `bundle-miss`, `ended`, `gate`) tells a socket client
41
+ * something it cannot otherwise learn, so it goes to both sinks. Everything
42
+ * else is about the SHIFT'S OWN CONDITION, and that is different on each side:
43
+ *
44
+ * - On the SOCKET it is redundant or harmful. Every `ShiftCapacity` response
45
+ * already carries live `cap`, `free`, and `running`, so `capacity` and
46
+ * `parked` restate on the wire what the response states anyway — while
47
+ * queueing ANY record instantly satisfies a parked `owenloop shift next`,
48
+ * which must BLOCK until there is work to report. That is the bug this set
49
+ * exists to prevent: a shift that is merely full, merely idle, or merely
50
+ * unable to reach the hub would wake every attending terminal with news of
51
+ * nothing having happened.
52
+ * - In the FILE it is the only record of that condition. The file has no
53
+ * response envelope, so without these records a reader cannot tell an idle
54
+ * shift (no orders offered) from a saturated one (orders offered, no slots)
55
+ * from a stranded one (hub unreachable, so nothing was ever offered).
56
+ *
57
+ * `hub-error` IS IN THIS SET, AND THE REASON IS BOTH HALVES ABOVE.
58
+ *
59
+ * A FAILED HUB CALL IS NOT A UNIT OF WORK MOVING. Nothing was dispatched,
60
+ * reaped, or dropped — the shift failed to ask. So the "a socket client cannot
61
+ * learn it otherwise" justification for both-sinks does not apply, and the
62
+ * blocking contract of `shift next` does.
63
+ *
64
+ * The volume makes it a correctness problem rather than a style one, because
65
+ * `hub-error` is LEVEL-TRIGGERED and cannot self-limit. `noteServerBackoff`
66
+ * (`loop.ts`) sets a backoff only for a `HubError` with `status === 429`; an
67
+ * unreachable hub (ECONNREFUSED, DNS failure, timeout, HTTP 500) sets none, so
68
+ * the loop emits one `hub-error` per poll tick for as long as the outage lasts
69
+ * — about 720/hour per workflow at the 5s default. The socket queue holds
70
+ * `MAX_EVENT_QUEUE` (1000) records and evicts the OLDEST, so roughly 83 minutes
71
+ * of outage would evict every `dispatched`, `failed`, and `reaped` record a
72
+ * parked client actually needs, and every `owenloop shift next` during the
73
+ * outage would return instantly with a record that is not work.
74
+ *
75
+ * `shift.log` is append-only and unbounded, so it still keeps every attempt for
76
+ * an operator to count and time. Whether the FILE should ALSO collapse a long
77
+ * outage into fewer records is a separate, open question (idea
78
+ * W99TXHD9jqwpymifl-5-C) — frequency and routing are independent concerns, and
79
+ * this set is the one that decides routing.
80
+ *
81
+ * `event-queue-overflow` never reaches `consumeEvent` at all — `server.ts`
82
+ * hands it straight to the log sink through `onSynthesized`, because the queue
83
+ * is what overflowed. It is listed here so the category is stated in one place.
84
+ */
85
+ const FILE_ONLY_EVENTS = new Set([
86
+ 'parked',
87
+ 'capacity',
88
+ 'hub-error',
89
+ 'event-queue-overflow',
90
+ ]);
91
+ /**
92
+ * Does this event type reach the SOCKET consumer (a parked `owenloop shift
93
+ * next`), or only `shift.log`?
94
+ *
95
+ * The routing rule as a pure predicate so it can be asserted directly rather
96
+ * than only through a daemon's timing. `consumeEvent` is its one production
97
+ * caller; a `false` here means the record still reaches the file.
98
+ */
99
+ export function reachesSocketConsumer(type) {
100
+ return !FILE_ONLY_EVENTS.has(type);
101
+ }
30
102
  export function resolveCap(flagCap, settingsCap) {
31
103
  return flagCap ?? settingsCap ?? DEFAULT_CAP;
32
104
  }
@@ -79,6 +151,8 @@ export function parseArgs(args) {
79
151
  case '--workflow':
80
152
  case '--poll-interval':
81
153
  case '--cache-dir':
154
+ case '--log-dir':
155
+ case '--log-max-age':
82
156
  case '--state-dir': {
83
157
  const r = takeValue(a, i);
84
158
  if ('error' in r)
@@ -102,6 +176,14 @@ export function parseArgs(args) {
102
176
  parsed.cacheDir = r.value;
103
177
  else if (name === '--state-dir')
104
178
  parsed.stateDir = r.value;
179
+ else if (name === '--log-dir')
180
+ parsed.logDir = r.value;
181
+ else if (name === '--log-max-age') {
182
+ const n = intFlag(r.value, '--log-max-age');
183
+ if (typeof n !== 'number')
184
+ return { error: n.error };
185
+ parsed.logMaxAgeMs = n;
186
+ }
105
187
  else if (name === '--cap') {
106
188
  const n = intFlag(r.value, '--cap');
107
189
  if (typeof n !== 'number')
@@ -131,11 +213,19 @@ export function parseArgs(args) {
131
213
  function usage() {
132
214
  process.stderr.write('usage: owenloop work shift [--origin <url>] [--as <account>] [--name <n>] [--serve-crews a,b] [--cap <n>]\n' +
133
215
  ' [--workflow <id>] [--poll-interval <ms>] [--once]\n' +
134
- ' [--max-agents <n>] [--cache-dir <p>] [--state-dir <p>]\n');
216
+ ' [--max-agents <n>] [--cache-dir <p>] [--state-dir <p>]\n' +
217
+ ' [--log-dir <p>] [--log-max-age <ms>]\n');
135
218
  }
136
219
  function errMsg(err) {
137
220
  return err instanceof Error ? err.message : String(err);
138
221
  }
222
+ /** Public Shift daemon transport is a Unix-domain socket on macOS and Linux. */
223
+ export function assertShiftDaemonPlatform(platform = process.platform) {
224
+ if (platform === 'win32') {
225
+ throw new Error('the public Shift daemon is not supported on Windows: Windows named-pipe transport is not implemented; ' +
226
+ 'use `owenloop work shift` directly');
227
+ }
228
+ }
139
229
  /**
140
230
  * Shared runtime setup for the internal shift and public shift daemon.
141
231
  * `parsed` is already grammar-validated by the caller; this function owns all
@@ -145,6 +235,15 @@ function errMsg(err) {
145
235
  export async function runShiftRuntime(parsed, options = {}) {
146
236
  const daemonMode = options.daemon === true;
147
237
  const roleLabel = options.role === 'shift' ? 'owenloop shift' : 'owenloop work shift';
238
+ if (daemonMode) {
239
+ try {
240
+ assertShiftDaemonPlatform();
241
+ }
242
+ catch (error) {
243
+ process.stderr.write(`${roleLabel}: ${errMsg(error)}\n`);
244
+ return 1;
245
+ }
246
+ }
148
247
  const env = process.env;
149
248
  let settings;
150
249
  try {
@@ -180,7 +279,13 @@ export async function runShiftRuntime(parsed, options = {}) {
180
279
  process.stderr.write(`${roleLabel}: ${errMsg(err)}\n`);
181
280
  return 1;
182
281
  }
183
- ensureStateDir(stateDir);
282
+ try {
283
+ ensureStateDir(stateDir);
284
+ }
285
+ catch (err) {
286
+ process.stderr.write(`${roleLabel}: cannot initialize dispatch state at ${stateDir}: ${errMsg(err)}\n`);
287
+ return 1;
288
+ }
184
289
  {
185
290
  const liveRunIds = new Set(reconcileInFlight(stateDir).live.filter((r) => r.kind === 'agent-run').map((r) => r.run));
186
291
  try {
@@ -195,32 +300,172 @@ export async function runShiftRuntime(parsed, options = {}) {
195
300
  process.stderr.write(`${roleLabel}: session reconcile failed (continuing): ${errMsg(err)}\n`);
196
301
  }
197
302
  }
303
+ // ── ON-DISK LOGGING ──
304
+ //
305
+ // Prepared AFTER `ensureStateDir` because the log directory DEFAULTS to the
306
+ // state directory, and BEFORE the spawner because every dispatch needs the
307
+ // destination.
308
+ //
309
+ // `prepareShiftLogDir` resolves the directory, creates it, claims it for this
310
+ // shift's state directory, and sweeps aged-out worker logs — and degrades to
311
+ // "less logging" rather than failing the shift at every one of those steps.
312
+ // Its branches are unit-tested directly; what THIS site owns is the wiring:
313
+ // which flags, settings and environment reach it, and that a `ready: false`
314
+ // result withholds both the sink and the spawner's log directory.
315
+ const prepared = prepareShiftLogDir({
316
+ flagDir: parsed.logDir,
317
+ flagMaxAgeMs: parsed.logMaxAgeMs,
318
+ env,
319
+ settingsLogDir: settings.shiftLogDir,
320
+ settingsMaxAgeMs: settings.shiftLogMaxAgeMs,
321
+ stateDir,
322
+ now: Date.now(),
323
+ err: (line) => process.stderr.write(`${line}\n`),
324
+ label: roleLabel,
325
+ });
326
+ const logDir = prepared.dir;
327
+ const logDirReady = prepared.ready;
328
+ const logSink = logDirReady
329
+ ? createShiftLogSink({
330
+ path: shiftLogFile(logDir),
331
+ err: (line) => process.stderr.write(`${line}\n`),
332
+ })
333
+ : undefined;
198
334
  const cap = resolveCap(parsed.cap, settings.dispatchCap);
199
335
  const maxConcurrentAgents = resolveMaxConcurrentAgents(parsed.maxAgents, settings.maxConcurrentAgents);
200
336
  const workRoot = resolveWorkRoot(env, settings.workRoot, cacheDir);
201
337
  const workRepo = resolveWorkRepo(env, settings.workRepo);
202
338
  const hub = createHubClient({ origin, getToken: async () => token });
203
339
  const now = () => Date.now();
340
+ const monotonicNow = () => performance.now();
341
+ const home = [env.HOME, env.USERPROFILE].find((value) => value !== undefined && value.trim() !== '');
342
+ // Legacy orders and modern agent orders do not need Shift-side instruction
343
+ // lookup. Keep serving those lanes without a home directory; a modern command
344
+ // order still fails closed because its exact digest cannot be resolved.
345
+ const instructionSource = home === undefined
346
+ ? undefined
347
+ : createStoreInstructionSource({
348
+ projectRoot: join(process.cwd(), 'workflows'),
349
+ globalRoot: globalStoreRoot(home),
350
+ verifier: createBundleIngestor(),
351
+ });
352
+ const resolveOrderStep = async (order) => {
353
+ if (instructionSource === undefined ||
354
+ order.defDigest === undefined ||
355
+ order.defDigest.trim() === '')
356
+ return undefined;
357
+ if (await instructionSource.prime(order.defDigest) !== 'resolved')
358
+ return undefined;
359
+ return instructionSource.getVerifiedStep(order.defDigest, order.step);
360
+ };
204
361
  const shiftId = `shf_${randomUUID()}`;
205
362
  const startedAt = now();
206
363
  const name = resolveShiftName(parsed.name, { shiftId });
207
- const spawner = createDefaultSpawner(origin, account, undefined, shiftId);
208
- const pollIntervalMs = parsed.pollIntervalMs ?? DEFAULT_POLL_MS;
209
364
  let daemon;
365
+ /**
366
+ * `loop` is constructed BELOW this function, so it is captured by reference
367
+ * rather than value — exactly as `daemon` is, and for the same reason. Both
368
+ * are safe because nothing calls `reportWorkerFailure` until a spawned child
369
+ * exits, which cannot happen before construction finishes.
370
+ *
371
+ * A one-field holder rather than a bare `let`: `let loopRef; loopRef = loop;`
372
+ * is a single write in the same scope as the declaration, which is exactly
373
+ * the shape `prefer-const` rejects. The field write is not a rebinding, so
374
+ * the holder can be `const`.
375
+ */
376
+ const loopRef = { current: undefined };
377
+ /**
378
+ * Attach the `{ts, shift, shiftId}` envelope. Reads the shift's name LIVE from
379
+ * the loop rather than closing over the startup `name`, because `clock_in` can
380
+ * rename a shift mid-run and a record must carry the name in force when it was
381
+ * produced. Before the loop exists there is nothing to dispatch and therefore
382
+ * nothing to stamp, so the fallback to `name` is unreachable in practice and
383
+ * still correct if it is ever reached.
384
+ */
385
+ const stamp = (body) => stampShiftEvent(body, { name: loopRef.current?.getShift().name ?? name, id: shiftId }, now());
386
+ /**
387
+ * THE ONE PLACE a shift event fans out to its consumers: the socket daemon
388
+ * (live, ephemeral, only in daemon mode) and the on-disk log (durable, always
389
+ * when a log directory resolved).
390
+ *
391
+ * Each consumer is wrapped SEPARATELY. A daemon whose FIFO throws must not
392
+ * cost the file its record, and a full disk must not cost a parked client its
393
+ * event. Neither failure may reach the loop, which is why nothing rethrows.
394
+ *
395
+ * The two consumers do NOT receive the same set: `FILE_ONLY_EVENTS` reaches
396
+ * the file only. Routing is decided HERE rather than at each emit site so an
397
+ * emitter never has to know how many sinks exist.
398
+ */
399
+ const consumeEvent = (event) => {
400
+ if (daemonMode && reachesSocketConsumer(event.type)) {
401
+ try {
402
+ daemon?.onEvent(event);
403
+ }
404
+ catch (err) {
405
+ process.stderr.write(`${roleLabel}: shift event queue failed: ${errMsg(err)} (continuing)\n`);
406
+ }
407
+ }
408
+ // `createShiftLogSink.write` already swallows and reports its own failures;
409
+ // this guard covers a throw from anywhere else in the call.
410
+ try {
411
+ logSink?.write(event);
412
+ }
413
+ catch (err) {
414
+ process.stderr.write(`${roleLabel}: shift event sink failed: ${errMsg(err)} (continuing)\n`);
415
+ }
416
+ };
417
+ const reportWorkerFailure = (failure) => {
418
+ // A worker failure is detected by the SPAWNER's `exit`/`error` listener, not
419
+ // inside the loop's sweep, so it never passes through the loop's `emit()`.
420
+ // It is stamped here for the same reason `ended` is stamped in `server.ts`:
421
+ // every record on the wire and in the file carries the same envelope, with
422
+ // no exceptions a consumer would have to special-case.
423
+ const event = stamp({
424
+ type: 'failed',
425
+ workflow: failure.workflow,
426
+ run: failure.run,
427
+ step: failure.step ?? '(unknown)',
428
+ kind: failure.kind,
429
+ ...(failure.harness !== undefined ? { harness: failure.harness } : {}),
430
+ executable: failure.executable,
431
+ exitStatus: failure.exitStatus,
432
+ signal: failure.signal,
433
+ message: failure.message,
434
+ });
435
+ consumeEvent(event);
436
+ process.stderr.write(`${roleLabel}: worker failure ${JSON.stringify(event)}\n`);
437
+ // The third consumer, and the one that changes behaviour: charge the
438
+ // failure against the step's dispatch brake so a step that fails the same
439
+ // way forever is re-dispatched on a backoff instead of once per poll.
440
+ loopRef.current?.noteWorkerFailure(failure);
441
+ };
442
+ const spawner = createDefaultSpawner(origin, account, undefined, shiftId, reportWorkerFailure,
443
+ // `undefined` when the log directory could not be created, which is what
444
+ // makes `buildSpawnPlan` emit no `logFile` and the worker launch with its
445
+ // output discarded exactly as it did before this change.
446
+ logDirReady
447
+ ? { dir: logDir, err: (line) => process.stderr.write(`${line}\n`) }
448
+ : undefined);
449
+ const pollIntervalMs = parsed.pollIntervalMs ?? DEFAULT_POLL_MS;
210
450
  const loop = createShiftLoop({
211
451
  hub,
212
452
  spawner,
213
453
  sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
214
454
  now,
455
+ monotonicNow,
215
456
  out: (line) => process.stdout.write(`${line}\n`),
216
457
  err: (line) => process.stderr.write(`${line}\n`),
217
- ...(daemonMode ? { onEvent: (event) => daemon?.onEvent(event) } : {}),
458
+ // Previously daemon-mode only, because the socket daemon was the only
459
+ // consumer. The file sink is a second consumer that exists in BOTH modes, so
460
+ // the loop now emits whenever either consumer is present.
461
+ ...(daemonMode || logSink !== undefined ? { onEvent: consumeEvent } : {}),
218
462
  cacheDir,
219
463
  stateDir,
220
464
  cap,
221
465
  serveCrews: parsed.serveCrews ?? [],
222
466
  name,
223
467
  commandRouting: settings.commandRouting,
468
+ resolveOrderStep,
224
469
  pollIntervalMs,
225
470
  presenceIntervalMs: DEFAULT_PRESENCE_MS,
226
471
  maxConcurrentAgents,
@@ -231,6 +476,39 @@ export async function runShiftRuntime(parsed, options = {}) {
231
476
  ...(parsed.workflow !== undefined ? { workflow: parsed.workflow } : {}),
232
477
  ...(parsed.once === true ? { once: true } : {}),
233
478
  });
479
+ // Close the loop on `reportWorkerFailure`'s forward reference. Assigned
480
+ // immediately after construction, long before any child can exit.
481
+ loopRef.current = loop;
482
+ /**
483
+ * The first record in a shift's log: what this process is, where it is, and
484
+ * what it will serve. `shift.log` is read on a machine, days later, by someone
485
+ * who has only the file — so the file must be SELF-DESCRIBING. Every later
486
+ * record identifies the shift by name and id alone; this one is what those
487
+ * names resolve to.
488
+ *
489
+ * Written by `runtime.ts` rather than the loop because the loop knows its cap
490
+ * and crews but not the origin it was pointed at, the host, or the launch
491
+ * directory. Suppressed under `--once`, matching the console `parked as …`
492
+ * line — a one-shot drain is not a parked shift.
493
+ *
494
+ * FILE-ONLY, via `FILE_ONLY_EVENTS` — this goes through `consumeEvent` like
495
+ * every other record, and `consumeEvent` withholds it from the socket. A
496
+ * startup record sitting in the daemon's FIFO would make the first `next`
497
+ * after every start return instantly with a record about the shift itself,
498
+ * breaking the contract that an idle `next` BLOCKS until there is work to
499
+ * report; `packages/work/test/shift-blocking-acceptance.test.ts` asserts that
500
+ * blocking behaviour directly.
501
+ */
502
+ const emitParked = () => {
503
+ consumeEvent(stamp({
504
+ type: 'parked',
505
+ origin,
506
+ cap,
507
+ serveCrews: parsed.serveCrews ?? [],
508
+ hostname: hostname(),
509
+ cwd: process.cwd(),
510
+ }));
511
+ };
234
512
  if (daemonMode) {
235
513
  daemon = createShiftDaemon({
236
514
  socketPath: options.socketPath ?? join(stateDir, 'shift.sock'),
@@ -241,6 +519,12 @@ export async function runShiftRuntime(parsed, options = {}) {
241
519
  startedAt,
242
520
  shiftId,
243
521
  err: (line) => process.stderr.write(`${line}\n`),
522
+ // The daemon's self-made records (`event-queue-overflow`, `ended`) go
523
+ // STRAIGHT to the file, never back through `consumeEvent` — `consumeEvent`
524
+ // feeds `daemon.onEvent`, and the daemon has already put each of these in
525
+ // its own queue. For `event-queue-overflow` that routing is load-bearing
526
+ // rather than merely tidy: its queue is the thing that just overflowed.
527
+ ...(logSink !== undefined ? { onSynthesized: (event) => logSink.write(event) } : {}),
244
528
  });
245
529
  installSignalHandlers(daemon, process, (line) => process.stderr.write(`${line}\n`), {
246
530
  role: 'shift',
@@ -249,12 +533,14 @@ export async function runShiftRuntime(parsed, options = {}) {
249
533
  });
250
534
  if (parsed.once !== true) {
251
535
  process.stdout.write(`owenloop shift: parked as '${name}' @ ${origin} (cap ${cap})\n`);
536
+ emitParked();
252
537
  }
253
538
  return daemon.run();
254
539
  }
255
540
  installSignalHandlers(loop, process, (line) => process.stderr.write(`${line}\n`));
256
541
  if (parsed.once !== true) {
257
542
  process.stdout.write(`owenloop work shift: parked as '${name}' @ ${origin} (cap ${cap})\n`);
543
+ emitParked();
258
544
  }
259
545
  return loop.run();
260
546
  }
@@ -10,6 +10,19 @@ export interface ShiftDaemonOptions {
10
10
  startedAt: number;
11
11
  shiftId?: string;
12
12
  err: (line: string) => void;
13
+ /**
14
+ * Called with each already-stamped event this daemon SYNTHESIZES rather than
15
+ * receives through `onEvent` — today `event-queue-overflow` and `ended`.
16
+ *
17
+ * These two are the only shift events that never pass through `emit()` in
18
+ * `loop.ts`, so they are the only ones a second consumer would otherwise never
19
+ * see. In `runtime.ts` this callback is the on-disk log sink, which is what
20
+ * makes the file and the socket carry the same record set.
21
+ *
22
+ * The callback must write somewhere that is NOT this daemon's queue. For
23
+ * `event-queue-overflow` that is load-bearing: the queue is what overflowed.
24
+ */
25
+ onSynthesized?: (event: ShiftEvent) => void;
13
26
  }
14
27
  export interface ShiftDaemon {
15
28
  run(): Promise<number>;