owenloop 0.5.1 → 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 (81) hide show
  1. package/CHANGELOG.md +22 -0
  2. package/README.md +9 -2
  3. package/dist/packages/work/src/agent/brief.d.ts +21 -0
  4. package/dist/packages/work/src/agent/brief.js +42 -1
  5. package/dist/packages/work/src/agent/capability-model.d.ts +123 -0
  6. package/dist/packages/work/src/agent/capability-model.js +148 -0
  7. package/dist/packages/work/src/agent/loop.d.ts +47 -4
  8. package/dist/packages/work/src/agent/loop.js +83 -53
  9. package/dist/packages/work/src/exec/loop.d.ts +17 -0
  10. package/dist/packages/work/src/exec/loop.js +195 -34
  11. package/dist/packages/work/src/exec/runner.js +15 -5
  12. package/dist/packages/work/src/harness/session-store.d.ts +3 -1
  13. package/dist/packages/work/src/harness/session-store.js +46 -22
  14. package/dist/packages/work/src/hold/mcp.js +9 -2
  15. package/dist/packages/work/src/hub/client.d.ts +7 -1
  16. package/dist/packages/work/src/hub/client.js +1 -0
  17. package/dist/packages/work/src/hub/types.d.ts +71 -3
  18. package/dist/packages/work/src/roles/agent-run.js +8 -9
  19. package/dist/packages/work/src/roles/hold.d.ts +2 -0
  20. package/dist/packages/work/src/roles/hold.js +39 -8
  21. package/dist/packages/work/src/roles/settings.js +18 -6
  22. package/dist/packages/work/src/roles/shift.js +13 -1
  23. package/dist/packages/work/src/settings/settings.d.ts +60 -7
  24. package/dist/packages/work/src/settings/settings.js +69 -22
  25. package/dist/packages/work/src/shift/logretention.d.ts +253 -0
  26. package/dist/packages/work/src/shift/logretention.js +407 -0
  27. package/dist/packages/work/src/shift/logsink.d.ts +14 -0
  28. package/dist/packages/work/src/shift/logsink.js +98 -0
  29. package/dist/packages/work/src/shift/loop.d.ts +18 -1
  30. package/dist/packages/work/src/shift/loop.js +250 -12
  31. package/dist/packages/work/src/shift/protocol.d.ts +124 -1
  32. package/dist/packages/work/src/shift/protocol.js +14 -0
  33. package/dist/packages/work/src/shift/runtime.d.ts +14 -0
  34. package/dist/packages/work/src/shift/runtime.js +229 -6
  35. package/dist/packages/work/src/shift/server.d.ts +13 -0
  36. package/dist/packages/work/src/shift/server.js +61 -36
  37. package/dist/packages/work/src/shift/spawn.d.ts +78 -5
  38. package/dist/packages/work/src/shift/spawn.js +158 -12
  39. package/dist/packages/work/src/shift/state.d.ts +25 -0
  40. package/dist/packages/work/src/shift/state.js +29 -5
  41. package/dist/packages/work/src/shift/truncate.d.ts +35 -0
  42. package/dist/packages/work/src/shift/truncate.js +73 -0
  43. package/dist/packages/work/src/submit-proof.d.ts +31 -6
  44. package/dist/packages/work/src/submit-proof.js +33 -7
  45. package/dist/packages/work/src/submit-value.d.ts +48 -0
  46. package/dist/packages/work/src/submit-value.js +118 -0
  47. package/dist/packages/work/src/usage.d.ts +1 -1
  48. package/dist/packages/work/src/usage.js +11 -0
  49. package/dist/src/capabilities.d.ts +93 -0
  50. package/dist/src/capabilities.js +101 -0
  51. package/dist/src/cli.js +14 -9
  52. package/dist/src/crypto/records.d.ts +3 -0
  53. package/dist/src/crypto/records.js +11 -0
  54. package/dist/src/defs.js +192 -4
  55. package/dist/src/engine.d.ts +112 -3
  56. package/dist/src/engine.js +224 -28
  57. package/dist/src/hub.d.ts +27 -11
  58. package/dist/src/hub.js +24 -18
  59. package/dist/src/index.d.ts +3 -1
  60. package/dist/src/index.js +4 -1
  61. package/dist/src/mcp/serve.js +11 -4
  62. package/dist/src/model.d.ts +36 -0
  63. package/dist/src/model.js +46 -0
  64. package/dist/src/schemas/index.d.ts +17 -0
  65. package/dist/src/schemas/order.v1.schema.json +17 -3
  66. package/dist/src/store.d.ts +33 -1
  67. package/dist/src/store.js +57 -4
  68. package/dist/src/types.d.ts +102 -2
  69. package/docs/authoring.md +7 -0
  70. package/docs/bundles.md +103 -3
  71. package/docs/cli.md +127 -9
  72. package/docs/crypto.md +23 -7
  73. package/docs/shift-logs.md +642 -0
  74. package/docs/wire-contracts.md +34 -19
  75. package/package.json +1 -1
  76. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
  77. package/plugins/claude-code/plugin/.mcp.json +1 -1
  78. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
  79. package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
  80. package/dist/packages/work/src/agent/model-policy.d.ts +0 -49
  81. package/dist/packages/work/src/agent/model-policy.js +0 -138
@@ -0,0 +1,253 @@
1
+ /** The shift's own structured JSON Lines log, inside the log directory. */
2
+ export declare const SHIFT_LOG_NAME = "shift.log";
3
+ /**
4
+ * `<log-dir>/shift.log` — the shift process's own structured log. Pure path
5
+ * math; creates nothing.
6
+ */
7
+ export declare function shiftLogFile(logDir: string): string;
8
+ /**
9
+ * `<log-dir>/<run>.log` — one worker's raw output. Pure path math; creates
10
+ * nothing. Uses the SAME `safeRun` sanitizer `state.ts` uses for `<run>.json`,
11
+ * which is what makes basename correlation hold.
12
+ */
13
+ export declare function runLogFile(logDir: string, run: string): string;
14
+ /**
15
+ * Default retention for worker logs: 14 days.
16
+ *
17
+ * Long enough to read a postmortem the week after something went wrong, short
18
+ * enough to bound disk on a machine that runs shifts continuously. Worker logs
19
+ * are unbounded in SIZE by design — the tail you would have capped away is
20
+ * exactly the pathological run you needed to read — so volume is bounded here,
21
+ * by age, instead.
22
+ */
23
+ export declare const DEFAULT_SHIFT_LOG_MAX_AGE_MS: number;
24
+ /**
25
+ * Resolve the log directory: `--log-dir` > `OWENLOOP_SHIFT_LOG_DIR` >
26
+ * `settings.shiftLogDir` > the already-resolved state dir. Same precedence shape
27
+ * as `resolveWorkRoot` and `resolveStateDirOverride`, so there is one rule to
28
+ * remember.
29
+ *
30
+ * DEFAULTING TO THE STATE DIR is what makes correlation free: `<run>.log` lands
31
+ * beside the existing `<run>.json`, same basename. The correlation key is the
32
+ * BASENAME, not the adjacency — an operator who points `--log-dir` elsewhere
33
+ * moves the logs away from the records and basename correlation still holds.
34
+ *
35
+ * ALWAYS ABSOLUTE, for the same reason `resolveStateDir` is: this directory is
36
+ * the RENDEZVOUS between shift processes that may have been started from
37
+ * different working directories, and `.owners` inside it is read by whichever
38
+ * of them sweeps. Two spellings of one directory would be two rendezvous
39
+ * points, and a sweeping shift would not see the claims written under the
40
+ * other spelling.
41
+ */
42
+ export declare function resolveShiftLogDir(flag: string | undefined, env: Record<string, string | undefined>, settingsLogDir: string | undefined, stateDir: string): string;
43
+ /**
44
+ * Resolve worker-log retention in milliseconds: `--log-max-age` >
45
+ * `OWENLOOP_SHIFT_LOG_MAX_AGE_MS` > `settings.shiftLogMaxAgeMs` >
46
+ * `DEFAULT_SHIFT_LOG_MAX_AGE_MS`. The env value is accepted only as a
47
+ * NON-NEGATIVE INTEGER: unparseable, negative, and non-integer values
48
+ * (`86400000.5`) are all ignored rather than fatal, and resolution falls through
49
+ * to the next source — a typo in an environment variable must not stop a shift
50
+ * from serving.
51
+ */
52
+ export declare function resolveShiftLogMaxAgeMs(flag: number | undefined, env: Record<string, string | undefined>, settingsMaxAgeMs: number | undefined): number;
53
+ export interface ShiftLogReapGateInput {
54
+ /** The log file's basename, e.g. `run_7b29d1845b2926eba5dbc574.log`. */
55
+ name: string;
56
+ /** The log file's own last-modification time, in ms. */
57
+ mtimeMs: number;
58
+ /**
59
+ * Does the matching `<run>.json` in-flight record still exist in ANY state
60
+ * directory that logs into this directory? See `LOG_OWNERS_DIR_NAME`.
61
+ */
62
+ hasRunRecord: boolean;
63
+ now: number;
64
+ maxAgeMs: number;
65
+ }
66
+ /**
67
+ * May this log file be removed?
68
+ *
69
+ * PURE — no filesystem, no clock. That is what lets the truth table below be a
70
+ * unit test instead of an integration test.
71
+ *
72
+ * | `<run>.json` exists | older than maxAge | reap? |
73
+ * |---|---|---|
74
+ * | yes | any | NO — the run is still in flight (see the orphaned-inode note above) |
75
+ * | no | no | NO — recent, still the postmortem you would want |
76
+ * | no | yes | YES |
77
+ *
78
+ * NEVER reapable regardless of age: `shift.log` (the shift's own structured log,
79
+ * which this change does not rotate), anything not ending `.log`, and anything
80
+ * whose basename is not a `run_…` id. The log directory defaults to the state
81
+ * directory, which also holds `shift.sock`, `.dispatch.lock`, gate files and
82
+ * atomic-write temporaries — a sweep that removed by age alone would eat them.
83
+ *
84
+ * Unlike `isWorkDirReapable`, whose `lastSeenAt` is a DIRECTORY mtime and
85
+ * therefore a weak signal (a write deep inside a subtree does not update it),
86
+ * this gate reads the log file's OWN mtime, which the worker's every write
87
+ * updates. The signal is strong here, so the gate needs no grace window beyond
88
+ * the retention age.
89
+ */
90
+ export declare function isShiftLogReapable(g: ShiftLogReapGateInput): boolean;
91
+ /**
92
+ * Is this basename a worker log this sweep owns?
93
+ *
94
+ * `<run>.log` where `<run>` is a run id as `state.ts` writes it — the same
95
+ * `run_…` shape, sanitized the same way. Exported so the sweep and the gate
96
+ * cannot disagree about what they own.
97
+ */
98
+ export declare function isWorkerLogName(name: string): boolean;
99
+ /**
100
+ * Sub-directory of the log directory in which each shift declares WHICH state
101
+ * directory holds its in-flight `<run>.json` records.
102
+ *
103
+ * ── WHY A REGISTRY EXISTS AT ALL ──
104
+ *
105
+ * The in-flight gate asks "does `<run>.json` still exist?", and a shift can only
106
+ * answer that for the state directory it owns. `--log-dir` /
107
+ * `OWENLOOP_SHIFT_LOG_DIR` is a single global setting, so centralizing several
108
+ * crews' logs into ONE directory while each crew keeps its own per-crew state
109
+ * directory is the obvious way to use it. In that layout a sweeping shift sees
110
+ * another shift's `<run>.log` with no `<run>.json` anywhere IT can see, decides
111
+ * the run is finished, and unlinks a log a LIVE worker still holds a descriptor
112
+ * on — the exact orphaned-inode data loss the gate exists to prevent. At the
113
+ * 14-day default that needs a worker quiet for 14 days; at a reduced
114
+ * `--log-max-age` it fires against every live worker of every other shift.
115
+ *
116
+ * So each shift writes one claim naming its state directory, and the sweep
117
+ * treats a run as in flight if ANY claimed state directory still holds its
118
+ * record. One file per shift, named by a hash of the state directory it names,
119
+ * so two shifts starting at once each write their OWN file and no
120
+ * read-modify-write can lose a claim.
121
+ *
122
+ * A stale claim (a retired crew) is harmless: its state directory either no
123
+ * longer exists or holds no records, so it contributes no `true` and merely
124
+ * costs one `stat`. Erring toward keeping a log costs disk; erring the other way
125
+ * costs an operator the evidence they went looking for.
126
+ */
127
+ export declare const LOG_OWNERS_DIR_NAME = ".owners";
128
+ /** `<log-dir>/.owners` — pure path math; creates nothing. */
129
+ export declare function logOwnersDir(logDir: string): string;
130
+ /**
131
+ * Declare that `stateDir` holds the in-flight records for the workers logging
132
+ * into `logDir`. Idempotent — re-run at every shift startup, rewriting the same
133
+ * path with the same bytes.
134
+ *
135
+ * WRITES THE ABSOLUTE PATH, and does not trust its caller to have resolved one.
136
+ * The reader of this file is a DIFFERENT process with a DIFFERENT working
137
+ * directory, and it joins `<run>.json` onto whatever string it finds here. A
138
+ * relative claim resolved against the reader's cwd probes a directory that does
139
+ * not exist, every probe answers "no record", and the sweep unlinks live
140
+ * workers' logs — which is precisely the failure this registry exists to
141
+ * prevent. Absoluteness is therefore an invariant OF THE REGISTRY, enforced at
142
+ * both ends, not an assumption about who calls it.
143
+ *
144
+ * THROWS on failure, deliberately: the caller decides what a shift that cannot
145
+ * claim its logs should do (see `runtime.ts`, which reports once and keeps
146
+ * dispatching, because an observability defect must not become an outage).
147
+ */
148
+ export declare function registerShiftLogOwner(logDir: string, stateDir: string): string;
149
+ /**
150
+ * Every state directory that has claimed `logDir`, plus `ownStateDir` — which is
151
+ * included unconditionally so a sweep is never LESS informed than it was before
152
+ * the registry existed, even if the claim write failed or the directory is
153
+ * unreadable. Every returned path is absolute (see `registerShiftLogOwner`), so
154
+ * a caller joining `<run>.json` onto one of them probes the directory the
155
+ * claimant meant regardless of either process's working directory.
156
+ *
157
+ * Never throws. An absent registry (the default single-shift layout, where no
158
+ * claim has been written yet) and one unparseable claim both degrade to "that
159
+ * claim tells me nothing", not to a failed sweep. The try/catch is deliberately
160
+ * INSIDE the loop: one shift that crashed mid-write must cost its own logs
161
+ * only, never the other claimants' — an outer guard would blind the sweep to
162
+ * every claim after the corrupt one.
163
+ */
164
+ export declare function readShiftLogOwners(logDir: string, ownStateDir: string): string[];
165
+ export interface SweepShiftLogsOptions {
166
+ /** The resolved log directory. */
167
+ dir: string;
168
+ /** Where THIS shift's `<run>.json` in-flight records live. */
169
+ stateDir: string;
170
+ /**
171
+ * Every state directory whose records gate this sweep. Defaults to
172
+ * `readShiftLogOwners(dir, stateDir)` — this shift's own, plus every other
173
+ * shift that has claimed the log directory. Injected for tests.
174
+ */
175
+ stateDirs?: string[];
176
+ now: number;
177
+ maxAgeMs: number;
178
+ /** Progress/warning sink. */
179
+ err?: (line: string) => void;
180
+ /** Injected for tests; defaults to `node:fs` `readdirSync`. */
181
+ list?: (dir: string) => string[];
182
+ /** Injected for tests; defaults to `node:fs` `statSync().mtimeMs`. */
183
+ mtime?: (path: string) => number;
184
+ /** Injected for tests; defaults to `node:fs` `existsSync`-style probe. */
185
+ hasRecord?: (stateDir: string, name: string) => boolean;
186
+ /** Injected for tests; defaults to `node:fs` `rmSync`. */
187
+ remove?: (path: string) => void;
188
+ }
189
+ /**
190
+ * Apply `isShiftLogReapable` to every file in the log directory and remove the
191
+ * ones that pass. Returns the paths actually removed, so a caller can log a
192
+ * count.
193
+ *
194
+ * BEST EFFORT, NEVER THROWS. It runs at shift startup, before any work is
195
+ * dispatched, and a shift that cannot tidy its logs must still serve. Every
196
+ * per-file step is individually guarded: a locked, unreadable, or
197
+ * concurrently-removed file costs that one entry, not the sweep.
198
+ */
199
+ export declare function sweepShiftLogs(o: SweepShiftLogsOptions): string[];
200
+ export interface PrepareShiftLogDirOptions {
201
+ /** `--log-dir`, if the operator passed one. */
202
+ flagDir?: string | undefined;
203
+ /** `--log-max-age`, if the operator passed one. */
204
+ flagMaxAgeMs?: number | undefined;
205
+ env: Record<string, string | undefined>;
206
+ settingsLogDir?: string | undefined;
207
+ settingsMaxAgeMs?: number | undefined;
208
+ /** This shift's ALREADY-RESOLVED state directory (absolute — see `resolveStateDir`). */
209
+ stateDir: string;
210
+ now: number;
211
+ /** Operator-facing report sink. Every line is prefixed with `label`. */
212
+ err: (line: string) => void;
213
+ /** The command's own name for its messages, e.g. `owenloop shift`. */
214
+ label: string;
215
+ }
216
+ export interface PreparedShiftLogDir {
217
+ /** The resolved, absolute log directory — valid whether or not it exists. */
218
+ dir: string;
219
+ maxAgeMs: number;
220
+ /**
221
+ * Did the directory come up? `false` means the caller must build NO log sink
222
+ * and pass NO log directory to the spawner, so workers keep the pre-logging
223
+ * `stdio: ['ignore','ignore','ignore']` topology.
224
+ */
225
+ ready: boolean;
226
+ /** Paths the startup sweep removed. Empty when `ready` is `false`. */
227
+ reaped: string[];
228
+ }
229
+ /**
230
+ * Everything that must happen to a log directory BEFORE the first dispatch:
231
+ * resolve it, create it, claim it for this shift's state directory, and sweep
232
+ * the worker logs that aged out.
233
+ *
234
+ * ── WHY THIS IS A FUNCTION AND NOT A BLOCK INSIDE `runtime.ts` ──
235
+ *
236
+ * It has five distinct failure branches (uncreatable directory, unclaimable
237
+ * registry, unscannable directory, unremovable file, a sweep that throws
238
+ * despite its never-throws contract) and every one of them must degrade to
239
+ * "less logging", never to "no shift". Driving those from a real
240
+ * `owenloop shift start` would mean five daemon processes; as a function it is
241
+ * five cheap calls against a temp directory, and `runtime.ts` keeps one call
242
+ * site whose wiring an acceptance test then proves once.
243
+ *
244
+ * NEVER THROWS. A shift whose only defect is that it cannot write a log must
245
+ * still dispatch work: refusing to start would turn an observability feature
246
+ * into an outage.
247
+ *
248
+ * ORDER MATTERS. The claim is written BEFORE the sweep so that this shift's own
249
+ * records gate its own sweep even on its very first startup, and so that a
250
+ * concurrently-starting sibling can see this shift's state directory rather
251
+ * than reaping its live workers' logs.
252
+ */
253
+ export declare function prepareShiftLogDir(o: PrepareShiftLogDirOptions): PreparedShiftLogDir;
@@ -0,0 +1,407 @@
1
+ /**
2
+ * Where shift logs live, and the gate that removes worker logs.
3
+ *
4
+ * ── WHY THE LOG LIFETIME IS NOT THE RUN RECORD'S LIFETIME ──
5
+ *
6
+ * `state.ts` removes a run's `<run>.json` the moment its child completes. A log
7
+ * that inherited that lifecycle would be readable only while the run is still in
8
+ * flight — useless for the postmortem it exists for. So worker logs are swept by
9
+ * AGE, independently, and the run record's disappearance is what makes a log
10
+ * eligible rather than what deletes it.
11
+ *
12
+ * ── THE IN-FLIGHT GATE IS NOT TIDINESS ──
13
+ *
14
+ * A live worker holds an open descriptor on its log. On POSIX, unlinking that
15
+ * file makes it invisible while the child keeps writing to the now-orphaned
16
+ * inode: the bytes are produced, accounted against the filesystem, and lost.
17
+ * Refusing to reap any log whose `<run>.json` still exists is what prevents
18
+ * that.
19
+ *
20
+ * "Still exists" means in ANY state directory that writes logs here, not just
21
+ * the sweeping shift's own — several shifts may share one log directory while
22
+ * keeping separate per-crew state directories. `LOG_OWNERS_DIR_NAME` below is
23
+ * how a sweeping shift learns where the other shifts' records live.
24
+ *
25
+ * Shape mirrors `agent/workdir.ts`: a PURE truth-table gate (`isShiftLogReapable`)
26
+ * a unit test can drive with no filesystem, plus a best-effort sweep
27
+ * (`sweepShiftLogs`) that never throws, because a sweep must not die over one
28
+ * file.
29
+ */
30
+ import { createHash } from 'node:crypto';
31
+ import { mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
32
+ import { join, resolve } from 'node:path';
33
+ import { safeRun } from "./state.js";
34
+ /** The shift's own structured JSON Lines log, inside the log directory. */
35
+ export const SHIFT_LOG_NAME = 'shift.log';
36
+ /**
37
+ * `<log-dir>/shift.log` — the shift process's own structured log. Pure path
38
+ * math; creates nothing.
39
+ */
40
+ export function shiftLogFile(logDir) {
41
+ return join(logDir, SHIFT_LOG_NAME);
42
+ }
43
+ /**
44
+ * `<log-dir>/<run>.log` — one worker's raw output. Pure path math; creates
45
+ * nothing. Uses the SAME `safeRun` sanitizer `state.ts` uses for `<run>.json`,
46
+ * which is what makes basename correlation hold.
47
+ */
48
+ export function runLogFile(logDir, run) {
49
+ return join(logDir, `${safeRun(run)}.log`);
50
+ }
51
+ /**
52
+ * Default retention for worker logs: 14 days.
53
+ *
54
+ * Long enough to read a postmortem the week after something went wrong, short
55
+ * enough to bound disk on a machine that runs shifts continuously. Worker logs
56
+ * are unbounded in SIZE by design — the tail you would have capped away is
57
+ * exactly the pathological run you needed to read — so volume is bounded here,
58
+ * by age, instead.
59
+ */
60
+ export const DEFAULT_SHIFT_LOG_MAX_AGE_MS = 14 * 24 * 60 * 60 * 1000;
61
+ /**
62
+ * Resolve the log directory: `--log-dir` > `OWENLOOP_SHIFT_LOG_DIR` >
63
+ * `settings.shiftLogDir` > the already-resolved state dir. Same precedence shape
64
+ * as `resolveWorkRoot` and `resolveStateDirOverride`, so there is one rule to
65
+ * remember.
66
+ *
67
+ * DEFAULTING TO THE STATE DIR is what makes correlation free: `<run>.log` lands
68
+ * beside the existing `<run>.json`, same basename. The correlation key is the
69
+ * BASENAME, not the adjacency — an operator who points `--log-dir` elsewhere
70
+ * moves the logs away from the records and basename correlation still holds.
71
+ *
72
+ * ALWAYS ABSOLUTE, for the same reason `resolveStateDir` is: this directory is
73
+ * the RENDEZVOUS between shift processes that may have been started from
74
+ * different working directories, and `.owners` inside it is read by whichever
75
+ * of them sweeps. Two spellings of one directory would be two rendezvous
76
+ * points, and a sweeping shift would not see the claims written under the
77
+ * other spelling.
78
+ */
79
+ export function resolveShiftLogDir(flag, env, settingsLogDir, stateDir) {
80
+ if (flag !== undefined && flag.trim() !== '')
81
+ return resolve(flag);
82
+ const override = env['OWENLOOP_SHIFT_LOG_DIR'];
83
+ if (override !== undefined && override.trim() !== '')
84
+ return resolve(override);
85
+ if (settingsLogDir !== undefined && settingsLogDir.trim() !== '')
86
+ return resolve(settingsLogDir);
87
+ return resolve(stateDir);
88
+ }
89
+ /**
90
+ * Resolve worker-log retention in milliseconds: `--log-max-age` >
91
+ * `OWENLOOP_SHIFT_LOG_MAX_AGE_MS` > `settings.shiftLogMaxAgeMs` >
92
+ * `DEFAULT_SHIFT_LOG_MAX_AGE_MS`. The env value is accepted only as a
93
+ * NON-NEGATIVE INTEGER: unparseable, negative, and non-integer values
94
+ * (`86400000.5`) are all ignored rather than fatal, and resolution falls through
95
+ * to the next source — a typo in an environment variable must not stop a shift
96
+ * from serving.
97
+ */
98
+ export function resolveShiftLogMaxAgeMs(flag, env, settingsMaxAgeMs) {
99
+ if (flag !== undefined)
100
+ return flag;
101
+ const raw = env['OWENLOOP_SHIFT_LOG_MAX_AGE_MS'];
102
+ if (raw !== undefined && raw.trim() !== '') {
103
+ const parsed = Number(raw);
104
+ if (Number.isFinite(parsed) && Number.isInteger(parsed) && parsed >= 0)
105
+ return parsed;
106
+ }
107
+ if (settingsMaxAgeMs !== undefined)
108
+ return settingsMaxAgeMs;
109
+ return DEFAULT_SHIFT_LOG_MAX_AGE_MS;
110
+ }
111
+ /**
112
+ * May this log file be removed?
113
+ *
114
+ * PURE — no filesystem, no clock. That is what lets the truth table below be a
115
+ * unit test instead of an integration test.
116
+ *
117
+ * | `<run>.json` exists | older than maxAge | reap? |
118
+ * |---|---|---|
119
+ * | yes | any | NO — the run is still in flight (see the orphaned-inode note above) |
120
+ * | no | no | NO — recent, still the postmortem you would want |
121
+ * | no | yes | YES |
122
+ *
123
+ * NEVER reapable regardless of age: `shift.log` (the shift's own structured log,
124
+ * which this change does not rotate), anything not ending `.log`, and anything
125
+ * whose basename is not a `run_…` id. The log directory defaults to the state
126
+ * directory, which also holds `shift.sock`, `.dispatch.lock`, gate files and
127
+ * atomic-write temporaries — a sweep that removed by age alone would eat them.
128
+ *
129
+ * Unlike `isWorkDirReapable`, whose `lastSeenAt` is a DIRECTORY mtime and
130
+ * therefore a weak signal (a write deep inside a subtree does not update it),
131
+ * this gate reads the log file's OWN mtime, which the worker's every write
132
+ * updates. The signal is strong here, so the gate needs no grace window beyond
133
+ * the retention age.
134
+ */
135
+ export function isShiftLogReapable(g) {
136
+ if (!isWorkerLogName(g.name))
137
+ return false;
138
+ if (g.hasRunRecord)
139
+ return false;
140
+ return g.now - g.mtimeMs >= g.maxAgeMs;
141
+ }
142
+ /**
143
+ * Is this basename a worker log this sweep owns?
144
+ *
145
+ * `<run>.log` where `<run>` is a run id as `state.ts` writes it — the same
146
+ * `run_…` shape, sanitized the same way. Exported so the sweep and the gate
147
+ * cannot disagree about what they own.
148
+ */
149
+ export function isWorkerLogName(name) {
150
+ if (name === SHIFT_LOG_NAME)
151
+ return false;
152
+ if (!name.endsWith('.log'))
153
+ return false;
154
+ return /^run_[A-Za-z0-9_.-]+$/u.test(name.slice(0, -'.log'.length));
155
+ }
156
+ /**
157
+ * Sub-directory of the log directory in which each shift declares WHICH state
158
+ * directory holds its in-flight `<run>.json` records.
159
+ *
160
+ * ── WHY A REGISTRY EXISTS AT ALL ──
161
+ *
162
+ * The in-flight gate asks "does `<run>.json` still exist?", and a shift can only
163
+ * answer that for the state directory it owns. `--log-dir` /
164
+ * `OWENLOOP_SHIFT_LOG_DIR` is a single global setting, so centralizing several
165
+ * crews' logs into ONE directory while each crew keeps its own per-crew state
166
+ * directory is the obvious way to use it. In that layout a sweeping shift sees
167
+ * another shift's `<run>.log` with no `<run>.json` anywhere IT can see, decides
168
+ * the run is finished, and unlinks a log a LIVE worker still holds a descriptor
169
+ * on — the exact orphaned-inode data loss the gate exists to prevent. At the
170
+ * 14-day default that needs a worker quiet for 14 days; at a reduced
171
+ * `--log-max-age` it fires against every live worker of every other shift.
172
+ *
173
+ * So each shift writes one claim naming its state directory, and the sweep
174
+ * treats a run as in flight if ANY claimed state directory still holds its
175
+ * record. One file per shift, named by a hash of the state directory it names,
176
+ * so two shifts starting at once each write their OWN file and no
177
+ * read-modify-write can lose a claim.
178
+ *
179
+ * A stale claim (a retired crew) is harmless: its state directory either no
180
+ * longer exists or holds no records, so it contributes no `true` and merely
181
+ * costs one `stat`. Erring toward keeping a log costs disk; erring the other way
182
+ * costs an operator the evidence they went looking for.
183
+ */
184
+ export const LOG_OWNERS_DIR_NAME = '.owners';
185
+ /** `<log-dir>/.owners` — pure path math; creates nothing. */
186
+ export function logOwnersDir(logDir) {
187
+ return join(logDir, LOG_OWNERS_DIR_NAME);
188
+ }
189
+ /**
190
+ * The claim filename for one state directory. A hash, not the path itself:
191
+ * a state directory path is not a safe filename, and the hash makes each shift's
192
+ * write land on its own name so concurrent claims cannot clobber each other.
193
+ *
194
+ * Hashes the ABSOLUTE path. Hashing whatever spelling the caller happened to
195
+ * hold would give `./state` and `/a/state` two different names for one
196
+ * directory, so one shift restarted from a different working directory would
197
+ * accumulate a second claim file and contradict "one file per shift".
198
+ */
199
+ function ownerClaimName(stateDir) {
200
+ return `${createHash('sha256').update(resolve(stateDir)).digest('hex').slice(0, 16)}.json`;
201
+ }
202
+ /**
203
+ * Declare that `stateDir` holds the in-flight records for the workers logging
204
+ * into `logDir`. Idempotent — re-run at every shift startup, rewriting the same
205
+ * path with the same bytes.
206
+ *
207
+ * WRITES THE ABSOLUTE PATH, and does not trust its caller to have resolved one.
208
+ * The reader of this file is a DIFFERENT process with a DIFFERENT working
209
+ * directory, and it joins `<run>.json` onto whatever string it finds here. A
210
+ * relative claim resolved against the reader's cwd probes a directory that does
211
+ * not exist, every probe answers "no record", and the sweep unlinks live
212
+ * workers' logs — which is precisely the failure this registry exists to
213
+ * prevent. Absoluteness is therefore an invariant OF THE REGISTRY, enforced at
214
+ * both ends, not an assumption about who calls it.
215
+ *
216
+ * THROWS on failure, deliberately: the caller decides what a shift that cannot
217
+ * claim its logs should do (see `runtime.ts`, which reports once and keeps
218
+ * dispatching, because an observability defect must not become an outage).
219
+ */
220
+ export function registerShiftLogOwner(logDir, stateDir) {
221
+ const dir = logOwnersDir(resolve(logDir));
222
+ // 0700 on the registry directory and 0600 on the claim. A claim names an
223
+ // absolute filesystem path on this host, which is a layout disclosure and not
224
+ // something every local account needs. Both modes apply at CREATION only, so
225
+ // an existing `.owners/` from an earlier build keeps its mode — `mkdirSync`
226
+ // never chmods a directory that is already there.
227
+ mkdirSync(dir, { recursive: true, mode: 0o700 });
228
+ const path = join(dir, ownerClaimName(stateDir));
229
+ writeFileSync(path, `${JSON.stringify({ stateDir: resolve(stateDir) })}\n`, { mode: 0o600 });
230
+ return path;
231
+ }
232
+ /**
233
+ * Every state directory that has claimed `logDir`, plus `ownStateDir` — which is
234
+ * included unconditionally so a sweep is never LESS informed than it was before
235
+ * the registry existed, even if the claim write failed or the directory is
236
+ * unreadable. Every returned path is absolute (see `registerShiftLogOwner`), so
237
+ * a caller joining `<run>.json` onto one of them probes the directory the
238
+ * claimant meant regardless of either process's working directory.
239
+ *
240
+ * Never throws. An absent registry (the default single-shift layout, where no
241
+ * claim has been written yet) and one unparseable claim both degrade to "that
242
+ * claim tells me nothing", not to a failed sweep. The try/catch is deliberately
243
+ * INSIDE the loop: one shift that crashed mid-write must cost its own logs
244
+ * only, never the other claimants' — an outer guard would blind the sweep to
245
+ * every claim after the corrupt one.
246
+ */
247
+ export function readShiftLogOwners(logDir, ownStateDir) {
248
+ const owners = new Set([resolve(ownStateDir)]);
249
+ const dir = logOwnersDir(resolve(logDir));
250
+ let names;
251
+ try {
252
+ names = readdirSync(dir);
253
+ }
254
+ catch {
255
+ return [...owners];
256
+ }
257
+ for (const name of names) {
258
+ if (!name.endsWith('.json'))
259
+ continue;
260
+ try {
261
+ const parsed = JSON.parse(readFileSync(join(dir, name), 'utf8'));
262
+ const claimed = parsed.stateDir;
263
+ if (typeof claimed === 'string' && claimed.trim() !== '')
264
+ owners.add(resolve(claimed));
265
+ }
266
+ catch {
267
+ // One corrupt claim must not blind the sweep to the others. It can only
268
+ // cost the claimant's own logs, and only if that shift never rewrites it.
269
+ }
270
+ }
271
+ return [...owners];
272
+ }
273
+ function defaultHasRecord(stateDir, logName) {
274
+ const record = join(stateDir, `${logName.slice(0, -'.log'.length)}.json`);
275
+ try {
276
+ statSync(record);
277
+ return true;
278
+ }
279
+ catch {
280
+ return false;
281
+ }
282
+ }
283
+ /**
284
+ * Apply `isShiftLogReapable` to every file in the log directory and remove the
285
+ * ones that pass. Returns the paths actually removed, so a caller can log a
286
+ * count.
287
+ *
288
+ * BEST EFFORT, NEVER THROWS. It runs at shift startup, before any work is
289
+ * dispatched, and a shift that cannot tidy its logs must still serve. Every
290
+ * per-file step is individually guarded: a locked, unreadable, or
291
+ * concurrently-removed file costs that one entry, not the sweep.
292
+ */
293
+ export function sweepShiftLogs(o) {
294
+ const list = o.list ?? ((dir) => readdirSync(dir));
295
+ const mtime = o.mtime ?? ((path) => statSync(path).mtimeMs);
296
+ const hasRecord = o.hasRecord ?? defaultHasRecord;
297
+ // A run is in flight if ANY shift that logs here still holds its record — not
298
+ // just this one. See `LOG_OWNERS_DIR_NAME` for why a single-state-dir probe
299
+ // silently reaps other shifts' live logs.
300
+ const stateDirs = o.stateDirs ?? readShiftLogOwners(o.dir, o.stateDir);
301
+ const remove = o.remove ?? ((path) => {
302
+ rmSync(path, { force: true });
303
+ });
304
+ const removed = [];
305
+ let names;
306
+ try {
307
+ names = list(o.dir);
308
+ }
309
+ catch (e) {
310
+ o.err?.(`owenloop shift: could not scan shift logs in ${o.dir}: ${errMsg(e)} (ignored)`);
311
+ return removed;
312
+ }
313
+ for (const name of names) {
314
+ const path = join(o.dir, name);
315
+ try {
316
+ if (!isWorkerLogName(name))
317
+ continue;
318
+ if (!isShiftLogReapable({
319
+ name,
320
+ mtimeMs: mtime(path),
321
+ hasRunRecord: stateDirs.some((stateDir) => hasRecord(stateDir, name)),
322
+ now: o.now,
323
+ maxAgeMs: o.maxAgeMs,
324
+ }))
325
+ continue;
326
+ remove(path);
327
+ removed.push(path);
328
+ }
329
+ catch (e) {
330
+ o.err?.(`owenloop shift: could not reap shift log ${path}: ${errMsg(e)} (ignored)`);
331
+ }
332
+ }
333
+ return removed;
334
+ }
335
+ function errMsg(err) {
336
+ return err instanceof Error ? err.message : String(err);
337
+ }
338
+ /**
339
+ * Everything that must happen to a log directory BEFORE the first dispatch:
340
+ * resolve it, create it, claim it for this shift's state directory, and sweep
341
+ * the worker logs that aged out.
342
+ *
343
+ * ── WHY THIS IS A FUNCTION AND NOT A BLOCK INSIDE `runtime.ts` ──
344
+ *
345
+ * It has five distinct failure branches (uncreatable directory, unclaimable
346
+ * registry, unscannable directory, unremovable file, a sweep that throws
347
+ * despite its never-throws contract) and every one of them must degrade to
348
+ * "less logging", never to "no shift". Driving those from a real
349
+ * `owenloop shift start` would mean five daemon processes; as a function it is
350
+ * five cheap calls against a temp directory, and `runtime.ts` keeps one call
351
+ * site whose wiring an acceptance test then proves once.
352
+ *
353
+ * NEVER THROWS. A shift whose only defect is that it cannot write a log must
354
+ * still dispatch work: refusing to start would turn an observability feature
355
+ * into an outage.
356
+ *
357
+ * ORDER MATTERS. The claim is written BEFORE the sweep so that this shift's own
358
+ * records gate its own sweep even on its very first startup, and so that a
359
+ * concurrently-starting sibling can see this shift's state directory rather
360
+ * than reaping its live workers' logs.
361
+ */
362
+ export function prepareShiftLogDir(o) {
363
+ const dir = resolveShiftLogDir(o.flagDir, o.env, o.settingsLogDir, o.stateDir);
364
+ const maxAgeMs = resolveShiftLogMaxAgeMs(o.flagMaxAgeMs, o.env, o.settingsMaxAgeMs);
365
+ try {
366
+ // 0700 WHEN THIS CALL CREATES THE DIRECTORY. The directory holds worker
367
+ // logs of authored workflow content, and the files inside are 0600, so a
368
+ // world-traversable parent would only advertise their names. `mkdirSync`
369
+ // does NOT chmod a directory that already exists, and that is the escape
370
+ // hatch for a site that wants a shared drop directory a separate uploader
371
+ // account can read: pre-create `--log-dir` with the group and mode that
372
+ // account needs, and this call leaves it exactly as found. The two log
373
+ // FILES stay 0600 either way — a shared directory is an operator's choice
374
+ // to make, and it does not make the bytes inside less sensitive.
375
+ mkdirSync(dir, { recursive: true, mode: 0o700 });
376
+ }
377
+ catch (err) {
378
+ o.err(`${o.label}: cannot create shift log directory ${dir}: ${errMsg(err)} — ` +
379
+ 'continuing with logging disabled');
380
+ return { dir, maxAgeMs, ready: false, reaped: [] };
381
+ }
382
+ // A failed claim costs retention SAFETY, not dispatch: another shift sharing
383
+ // this directory can no longer see our in-flight records and may reap our
384
+ // live workers' logs. Report it and keep going — that is a degraded log, and
385
+ // an outage is worse.
386
+ try {
387
+ registerShiftLogOwner(dir, o.stateDir);
388
+ }
389
+ catch (err) {
390
+ o.err(`${o.label}: cannot record this shift's claim on ${dir}: ${errMsg(err)} — ` +
391
+ "another shift sharing this log directory may reap this one's worker logs");
392
+ }
393
+ // `sweepShiftLogs` never throws by contract; this guard is belt-and-braces so
394
+ // a future change to it can never become a startup failure.
395
+ let reaped = [];
396
+ try {
397
+ reaped = sweepShiftLogs({ dir, stateDir: o.stateDir, now: o.now, maxAgeMs, err: o.err });
398
+ if (reaped.length > 0) {
399
+ o.err(`${o.label}: reaped ${String(reaped.length)} worker log(s) older than ` +
400
+ `${String(maxAgeMs)}ms from ${dir}`);
401
+ }
402
+ }
403
+ catch (err) {
404
+ o.err(`${o.label}: shift log sweep failed (continuing): ${errMsg(err)}`);
405
+ }
406
+ return { dir, maxAgeMs, ready: true, reaped };
407
+ }
@@ -0,0 +1,14 @@
1
+ import { type ShiftEvent } from './protocol.ts';
2
+ export interface ShiftLogSinkOptions {
3
+ /** Absolute path of the JSON Lines file to append to. */
4
+ path: string;
5
+ /** Where the one-time failure report goes. Never the sink itself. */
6
+ err: (line: string) => void;
7
+ /** Injected for tests; defaults to `node:fs` `appendFileSync`. */
8
+ append?: (path: string, line: string) => void;
9
+ }
10
+ export interface ShiftLogSink {
11
+ /** Append one event as a single JSON Lines record. Never throws. */
12
+ write(event: ShiftEvent): void;
13
+ }
14
+ export declare function createShiftLogSink(opts: ShiftLogSinkOptions): ShiftLogSink;