owenloop 0.5.0 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (211) hide show
  1. package/CHANGELOG.md +45 -0
  2. package/README.md +137 -35
  3. package/bin/owenloop.mjs +49 -1
  4. package/dist/packages/work/src/agent/brief.d.ts +8 -4
  5. package/dist/packages/work/src/agent/brief.js +7 -3
  6. package/dist/packages/work/src/agent/loop.d.ts +13 -7
  7. package/dist/packages/work/src/agent/loop.js +136 -9
  8. package/dist/packages/work/src/agent/model-policy.d.ts +49 -0
  9. package/dist/packages/work/src/agent/model-policy.js +138 -0
  10. package/dist/packages/work/src/bundle/cache.d.ts +7 -5
  11. package/dist/packages/work/src/bundle/cache.js +20 -6
  12. package/dist/packages/work/src/bundle/fetch.d.ts +7 -5
  13. package/dist/packages/work/src/bundle/fetch.js +27 -7
  14. package/dist/packages/work/src/bundle/types.d.ts +8 -4
  15. package/dist/packages/work/src/consumed-verifier.d.ts +45 -0
  16. package/dist/packages/work/src/consumed-verifier.js +205 -0
  17. package/dist/packages/work/src/exec/instructions.d.ts +99 -0
  18. package/dist/packages/work/src/exec/instructions.js +323 -0
  19. package/dist/packages/work/src/exec/loop.d.ts +12 -1
  20. package/dist/packages/work/src/exec/loop.js +137 -20
  21. package/dist/packages/work/src/exec/payload.d.ts +29 -0
  22. package/dist/packages/work/src/exec/payload.js +54 -0
  23. package/dist/packages/work/src/exec/receipt.d.ts +9 -6
  24. package/dist/packages/work/src/exec/receipt.js +12 -1
  25. package/dist/packages/work/src/exec/runner.d.ts +7 -1
  26. package/dist/packages/work/src/exec/runner.js +74 -3
  27. package/dist/packages/work/src/harness/child-env.js +7 -0
  28. package/dist/packages/work/src/harness/claude.d.ts +20 -8
  29. package/dist/packages/work/src/harness/claude.js +260 -58
  30. package/dist/packages/work/src/harness/codex.d.ts +5 -4
  31. package/dist/packages/work/src/harness/codex.js +169 -41
  32. package/dist/packages/work/src/harness/contract.d.ts +36 -11
  33. package/dist/packages/work/src/harness/fake.js +1 -0
  34. package/dist/packages/work/src/harness/jsonrpc-stdio.js +7 -0
  35. package/dist/packages/work/src/harness/permissions.d.ts +16 -3
  36. package/dist/packages/work/src/harness/permissions.js +102 -13
  37. package/dist/packages/work/src/harness/session-store.d.ts +27 -9
  38. package/dist/packages/work/src/harness/session-store.js +271 -67
  39. package/dist/packages/work/src/hold/mcp.d.ts +25 -5
  40. package/dist/packages/work/src/hold/mcp.js +126 -11
  41. package/dist/packages/work/src/hub/client.d.ts +2 -1
  42. package/dist/packages/work/src/hub/client.js +14 -1
  43. package/dist/packages/work/src/hub/types.d.ts +69 -33
  44. package/dist/packages/work/src/hub/types.js +8 -10
  45. package/dist/packages/work/src/mcp/server.js +1 -1
  46. package/dist/packages/work/src/owenloop-bin.d.ts +1 -0
  47. package/dist/packages/work/src/owenloop-bin.js +18 -0
  48. package/dist/packages/work/src/roles/agent-run.d.ts +12 -6
  49. package/dist/packages/work/src/roles/agent-run.js +116 -34
  50. package/dist/packages/work/src/roles/exec.d.ts +8 -0
  51. package/dist/packages/work/src/roles/exec.js +27 -2
  52. package/dist/packages/work/src/roles/hold.d.ts +4 -0
  53. package/dist/packages/work/src/roles/hold.js +44 -5
  54. package/dist/packages/work/src/roles/lint.d.ts +3 -4
  55. package/dist/packages/work/src/roles/lint.js +41 -7
  56. package/dist/packages/work/src/roles/settings.js +5 -0
  57. package/dist/packages/work/src/roles/shift.d.ts +1 -0
  58. package/dist/packages/work/src/roles/shift.js +23 -1
  59. package/dist/packages/work/src/settings/settings.d.ts +17 -1
  60. package/dist/packages/work/src/settings/settings.js +39 -0
  61. package/dist/packages/work/src/shift/loop.d.ts +14 -3
  62. package/dist/packages/work/src/shift/loop.js +447 -164
  63. package/dist/packages/work/src/shift/protocol.d.ts +4 -0
  64. package/dist/packages/work/src/shift/runtime.d.ts +2 -0
  65. package/dist/packages/work/src/shift/runtime.js +66 -3
  66. package/dist/packages/work/src/shift/spawn.d.ts +41 -18
  67. package/dist/packages/work/src/shift/spawn.js +89 -31
  68. package/dist/packages/work/src/shift/state.d.ts +53 -51
  69. package/dist/packages/work/src/shift/state.js +325 -102
  70. package/dist/packages/work/src/submit-proof.d.ts +36 -0
  71. package/dist/packages/work/src/submit-proof.js +93 -0
  72. package/dist/src/add.d.ts +64 -259
  73. package/dist/src/add.js +81 -615
  74. package/dist/src/archive.d.ts +97 -0
  75. package/dist/src/archive.js +591 -0
  76. package/dist/src/bundle/index.d.ts +64 -0
  77. package/dist/src/bundle/index.js +508 -0
  78. package/dist/src/bundle/manifest.d.ts +50 -0
  79. package/dist/src/bundle/manifest.js +435 -0
  80. package/dist/src/bundle/runtime.d.ts +26 -0
  81. package/dist/src/bundle/runtime.js +64 -0
  82. package/dist/src/bundle/tar.d.ts +62 -0
  83. package/dist/src/bundle/tar.js +238 -0
  84. package/dist/src/bundle/types.d.ts +105 -0
  85. package/dist/src/bundle/types.js +21 -0
  86. package/dist/src/cli.d.ts +90 -20
  87. package/dist/src/cli.js +2407 -365
  88. package/dist/src/credentials.d.ts +4 -3
  89. package/dist/src/credentials.js +21 -19
  90. package/dist/src/crypto/allowed-signers.d.ts +68 -0
  91. package/dist/src/crypto/allowed-signers.js +307 -0
  92. package/dist/src/crypto/canonical.d.ts +8 -0
  93. package/dist/src/crypto/canonical.js +92 -0
  94. package/dist/src/crypto/chain.d.ts +65 -0
  95. package/dist/src/crypto/chain.js +377 -0
  96. package/dist/src/crypto/dsse.d.ts +209 -0
  97. package/dist/src/crypto/dsse.js +282 -0
  98. package/dist/src/crypto/enrollment.d.ts +78 -0
  99. package/dist/src/crypto/enrollment.js +186 -0
  100. package/dist/src/crypto/index.d.ts +48 -0
  101. package/dist/src/crypto/index.js +44 -0
  102. package/dist/src/crypto/keys.d.ts +258 -0
  103. package/dist/src/crypto/keys.js +908 -0
  104. package/dist/src/crypto/org-root.d.ts +33 -0
  105. package/dist/src/crypto/org-root.js +78 -0
  106. package/dist/src/crypto/origin-rules.d.ts +56 -0
  107. package/dist/src/crypto/origin-rules.js +143 -0
  108. package/dist/src/crypto/policy-floor.d.ts +98 -0
  109. package/dist/src/crypto/policy-floor.js +353 -0
  110. package/dist/src/crypto/records.d.ts +316 -0
  111. package/dist/src/crypto/records.js +157 -0
  112. package/dist/src/crypto/scope.d.ts +49 -0
  113. package/dist/src/crypto/scope.js +83 -0
  114. package/dist/src/crypto/ssh.d.ts +171 -0
  115. package/dist/src/crypto/ssh.js +396 -0
  116. package/dist/src/crypto/submission.d.ts +33 -0
  117. package/dist/src/crypto/submission.js +47 -0
  118. package/dist/src/crypto/trust-roots.d.ts +29 -0
  119. package/dist/src/crypto/trust-roots.js +39 -0
  120. package/dist/src/crypto/verify-consumed.d.ts +67 -0
  121. package/dist/src/crypto/verify-consumed.js +259 -0
  122. package/dist/src/crypto/verify-origin.d.ts +50 -0
  123. package/dist/src/crypto/verify-origin.js +151 -0
  124. package/dist/src/crypto/verify-publication.d.ts +60 -0
  125. package/dist/src/crypto/verify-publication.js +150 -0
  126. package/dist/src/defs.d.ts +24 -1
  127. package/dist/src/defs.js +145 -25
  128. package/dist/src/engine.d.ts +99 -3
  129. package/dist/src/engine.js +238 -34
  130. package/dist/src/factory.d.ts +16 -0
  131. package/dist/src/factory.js +16 -4
  132. package/dist/src/global-config.d.ts +59 -0
  133. package/dist/src/global-config.js +84 -0
  134. package/dist/src/hub.d.ts +75 -21
  135. package/dist/src/hub.js +123 -40
  136. package/dist/src/index.d.ts +17 -2
  137. package/dist/src/index.js +20 -2
  138. package/dist/src/install.d.ts +538 -0
  139. package/dist/src/install.js +1981 -0
  140. package/dist/src/lock.d.ts +15 -57
  141. package/dist/src/lock.js +251 -143
  142. package/dist/src/mcp/serve.d.ts +46 -22
  143. package/dist/src/mcp/serve.js +167 -44
  144. package/dist/src/mcp/server.js +12 -1
  145. package/dist/src/model.d.ts +15 -0
  146. package/dist/src/model.js +111 -1
  147. package/dist/src/order-resolver.d.ts +184 -0
  148. package/dist/src/order-resolver.js +252 -0
  149. package/dist/src/package-version.d.ts +10 -0
  150. package/dist/src/package-version.js +42 -0
  151. package/dist/src/paths.d.ts +14 -1
  152. package/dist/src/paths.js +18 -0
  153. package/dist/src/schemas/enrollment-grant.v1.schema.json +90 -0
  154. package/dist/src/schemas/index.d.ts +1416 -0
  155. package/dist/src/schemas/index.js +31 -0
  156. package/dist/src/schemas/order.v1.schema.json +106 -0
  157. package/dist/src/schemas/origin.v1.schema.json +68 -0
  158. package/dist/src/schemas/policy-floor.v1.schema.json +29 -0
  159. package/dist/src/schemas/publication.v1.schema.json +31 -0
  160. package/dist/src/schemas/revocation.v1.schema.json +39 -0
  161. package/dist/src/schemas/submission.v1.schema.json +61 -0
  162. package/dist/src/store/def-source.d.ts +52 -0
  163. package/dist/src/store/def-source.js +335 -0
  164. package/dist/src/store/index-file.d.ts +69 -0
  165. package/dist/src/store/index-file.js +151 -0
  166. package/dist/src/store/index.d.ts +27 -0
  167. package/dist/src/store/index.js +22 -0
  168. package/dist/src/store/ingestor.d.ts +43 -0
  169. package/dist/src/store/ingestor.js +211 -0
  170. package/dist/src/store/install.d.ts +228 -0
  171. package/dist/src/store/install.js +555 -0
  172. package/dist/src/store/instruction-source.d.ts +49 -0
  173. package/dist/src/store/instruction-source.js +298 -0
  174. package/dist/src/store/origin-evidence.d.ts +21 -0
  175. package/dist/src/store/origin-evidence.js +66 -0
  176. package/dist/src/store/pre-commit-verifier.d.ts +68 -0
  177. package/dist/src/store/pre-commit-verifier.js +418 -0
  178. package/dist/src/store/resolve.d.ts +138 -0
  179. package/dist/src/store/resolve.js +363 -0
  180. package/dist/src/store/types.d.ts +288 -0
  181. package/dist/src/store/types.js +356 -0
  182. package/dist/src/types.d.ts +45 -11
  183. package/dist/src/untar.d.ts +8 -23
  184. package/dist/src/untar.js +10 -136
  185. package/docs/agent-runner.md +86 -0
  186. package/docs/authoring.md +57 -6
  187. package/docs/bundles.md +250 -0
  188. package/docs/cli.md +1171 -97
  189. package/docs/crypto.md +816 -0
  190. package/docs/design.md +342 -20
  191. package/docs/embedding.md +132 -25
  192. package/docs/wire-contracts.md +380 -0
  193. package/package.json +6 -1
  194. package/plugins/claude-code/.claude-plugin/marketplace.json +14 -0
  195. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +8 -0
  196. package/plugins/claude-code/plugin/.mcp.json +14 -0
  197. package/plugins/claude-code/plugin/hooks/hooks.json +26 -0
  198. package/plugins/claude-code/plugin/hooks/session-end.sh +40 -0
  199. package/plugins/claude-code/plugin/hooks/session-start.sh +52 -0
  200. package/plugins/claude-code/plugin/skills/author/SKILL.md +181 -0
  201. package/plugins/claude-code/plugin/skills/conduct/SKILL.md +106 -0
  202. package/plugins/claude-code/plugin/skills/shift/SKILL.md +105 -0
  203. package/plugins/codex/.agents/plugins/marketplace.json +21 -0
  204. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +7 -0
  205. package/plugins/codex/plugins/owenloop/.mcp.json +20 -0
  206. package/plugins/codex/plugins/owenloop/hooks/hooks.json +26 -0
  207. package/plugins/codex/plugins/owenloop/hooks/session-end.sh +40 -0
  208. package/plugins/codex/plugins/owenloop/hooks/session-start.sh +52 -0
  209. package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +181 -0
  210. package/plugins/codex/plugins/owenloop/skills/conduct/SKILL.md +106 -0
  211. package/plugins/codex/plugins/owenloop/skills/shift/SKILL.md +105 -0
@@ -42,19 +42,34 @@ export interface SessionRecord {
42
42
  export interface SessionStoreOptions {
43
43
  /** Called once per skipped corrupt line. Default writes to stderr. */
44
44
  warn?: (line: string) => void;
45
+ /** Test barrier invoked under the writer lock after a retirement snapshot. */
46
+ afterWriterSnapshot?: () => void;
45
47
  /** Compaction threshold in bytes, checked after each append. Default 2 MB. */
46
48
  maxBytes?: number;
49
+ /** Clock used to detect an abandoned unterminated tail. Default `Date.now`. */
50
+ now?: () => number;
51
+ /** Unchanged-tail grace before one warning is emitted. Default 5 seconds. */
52
+ unterminatedTailGraceMs?: number;
53
+ /** Injectable durability primitive for focused tests. Default `fsyncSync`. */
54
+ sync?: (fd: number) => void;
47
55
  }
48
56
  /** Default compaction threshold — plan §3's 2 MB. */
49
57
  export declare const DEFAULT_MAX_BYTES = 2000000;
58
+ /** Grace for a concurrent writer to finish an unterminated JSONL append. */
59
+ export declare const DEFAULT_UNTERMINATED_TAIL_GRACE_MS = 5000;
50
60
  /** `<cacheDir>/sessions.jsonl`. */
51
61
  export declare function sessionsPath(cacheDir: string): string;
52
62
  /** The composite order id `<workflow>/<run>` — the one place it is built. */
53
63
  export declare function orderId(workflow: string, run: string): string;
54
64
  /**
55
65
  * Every valid record in `file`, oldest first. A missing/unreadable file reads as
56
- * `[]`. Blank lines are skipped silently; every other unusable line is skipped
57
- * and reported through `warn` with its 1-indexed line number. Never throws.
66
+ * `[]`. A trailing newline is the record-commit marker: an unterminated final
67
+ * tail may be a concurrent writer still appending. File modification time starts
68
+ * the grace, so a recently modified tail is ignored silently while an already-old
69
+ * tail warns on the first read even in a fresh process. File identity, size, tail,
70
+ * or modification changes restart the observation; a newline clears it. Blank lines are
71
+ * skipped silently; every other unusable COMPLETE line is skipped and reported
72
+ * through `warn` with its 1-indexed line number. Never throws.
58
73
  */
59
74
  export declare function readSessions(file: string, opts?: SessionStoreOptions): SessionRecord[];
60
75
  /**
@@ -67,7 +82,8 @@ export declare function latestFor(file: string, workflow: string, run: string, s
67
82
  * Rewrite `file` with only the last record per `(workflow, run, step)`,
68
83
  * preserving FIRST-SEEN key order, via temp file + rename. Corrupt lines are
69
84
  * dropped in the process (they were already unreadable). A missing file is a
70
- * no-op. Fs failures propagate here; `appendSession` is what swallows them.
85
+ * no-op. The complete read/rewrite/rename transaction shares the same lock as
86
+ * append, so a successful append cannot be replaced by this snapshot.
71
87
  */
72
88
  export declare function compact(file: string, opts?: SessionStoreOptions): void;
73
89
  /**
@@ -82,8 +98,8 @@ export declare function compact(file: string, opts?: SessionStoreOptions): void;
82
98
  *
83
99
  * WHY A NEW ROW RATHER THAN A REWRITE: the store is append-only and last-wins per
84
100
  * `(workflow, run, step)`, so appending a copy with `status: 'dead'` shadows the
85
- * live row without rewriting history — and it keeps the ACCEPTED RACE in this
86
- * module's header (compaction losing concurrent appends) as the only writer race.
101
+ * live row without rewriting history. The shared writer lock serializes each
102
+ * appended retirement with append/compaction transactions from other processes.
87
103
  *
88
104
  * IDEMPOTENT: a key whose newest row is already `dead` is skipped, so a sweep
89
105
  * that reaps the same run twice appends nothing the second time.
@@ -155,9 +171,11 @@ export declare function reconcileActiveSessions(file: string, liveRunIds: Readon
155
171
  /**
156
172
  * Append one record, then compact when the file has grown past `maxBytes`.
157
173
  *
158
- * The whole line is written in ONE `appendFileSync` call (with its trailing
159
- * newline) so concurrent workers' O_APPEND writes interleave line-atomically on
160
- * local filesystems. Append failures PROPAGATE — see this module's failure
161
- * stance. The post-append compaction is best-effort and swallowed.
174
+ * The cross-process writer lock covers the WHOLE transaction: abandoned-tail
175
+ * quarantine, append, size check, and optional compaction rename. If a crashed
176
+ * writer left bytes without the JSONL commit newline, a leading newline commits
177
+ * only that fragment as corrupt before the new complete record. Append and lock
178
+ * failures PROPAGATE; post-append compaction remains best-effort because the
179
+ * appended line is already committed by its trailing JSONL newline in the original log.
162
180
  */
163
181
  export declare function appendSession(file: string, rec: SessionRecord, opts?: SessionStoreOptions): void;
@@ -24,8 +24,12 @@
24
24
  * - APPEND PROPAGATES. Unlike the shift's advisory metering records, a lost
25
25
  * session token silently degrades a Phase 4 resume into a cold replay — real
26
26
  * work thrown away — so the caller must see the failure.
27
- * - COMPACTION is best-effort (swallowed): the un-compacted file is still
28
- * correct, just larger.
27
+ * - `active` is the safety-critical boundary. Its complete JSONL row is fsynced
28
+ * before provider work may proceed. Other lifecycle rows retain ordinary
29
+ * append durability; losing one degrades to conservative retirement/replay.
30
+ * - COMPACTION is best-effort after a committed append, but a successful
31
+ * compaction fsyncs its replacement before rename so it cannot erase a
32
+ * previously durable `active` row across a host crash.
29
33
  *
30
34
  * DEVIATION FROM PLAN §3, stated deliberately: plan §3 says "compact on load if
31
35
  * > 2 MB". This module compacts on the WRITE path instead — `appendSession`
@@ -34,20 +38,26 @@
34
38
  * read-only filesystem), and a small `maxBytes` lets tests exercise compaction
35
39
  * without writing 2 MB. The 2 MB default is unchanged.
36
40
  *
37
- * ACCEPTED RACE: `compact` reads, rewrites, and renames, so lines appended by
38
- * another process in that window are lost. No locking is built. Session records
39
- * are advisory — a lost token degrades that one step to the designed replay
40
- * fallback — and compaction only runs past `maxBytes`.
41
+ * WRITER SERIALIZATION: every append, retirement, and compaction takes one
42
+ * cross-process writer lock for its complete read/append/size-check/rename
43
+ * transaction. A completed append can therefore never be replaced or shadowed
44
+ * by another process's stale snapshot. The shared SQLite lock database persists;
45
+ * process exit or crash releases its kernel lock without pathname deletion.
41
46
  *
42
47
  * Logging follows the house rule (there are zero `console.*` calls anywhere in
43
48
  * `src/`): the library takes an injectable callback and the default writes to
44
49
  * stderr, so tests stay silent and assertable.
45
50
  */
46
- import { appendFileSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
51
+ import { closeSync, fstatSync, fsyncSync, mkdirSync, openSync, readFileSync, readSync, renameSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
47
52
  import { join } from 'node:path';
53
+ import { acquireFileLockSync, releaseFileLock } from "../../../../src/lock.js";
48
54
  const STATUSES = new Set(['active', 'turn-ended', 'submitted', 'dead']);
49
55
  /** Default compaction threshold — plan §3's 2 MB. */
50
56
  export const DEFAULT_MAX_BYTES = 2_000_000;
57
+ /** Grace for a concurrent writer to finish an unterminated JSONL append. */
58
+ export const DEFAULT_UNTERMINATED_TAIL_GRACE_MS = 5_000;
59
+ /** Process-local observations; session files remain the only persisted state. */
60
+ const tailObservations = new Map();
51
61
  /** `<cacheDir>/sessions.jsonl`. */
52
62
  export function sessionsPath(cacheDir) {
53
63
  return join(cacheDir, 'sessions.jsonl');
@@ -92,17 +102,55 @@ function isSessionRecord(v) {
92
102
  return false;
93
103
  return true;
94
104
  }
95
- /** Atomic write: temp file + rename into place. Fs errors propagate to the
96
- * caller (the one caller, `compact`, is the one that swallows them). Mirrors
97
- * the private helper in `src/bundle/cache.ts` — copied on purpose rather than
98
- * exported from there, so the cache module's surface stays about bundles. */
99
- function atomicWrite(filePath, content) {
105
+ /** Flush a directory entry update where the platform exposes directory fsync. */
106
+ function syncDirectory(dir, sync = fsyncSync) {
107
+ if (process.platform === 'win32')
108
+ return;
109
+ const fd = openSync(dir, 'r');
110
+ try {
111
+ sync(fd);
112
+ }
113
+ finally {
114
+ closeSync(fd);
115
+ }
116
+ }
117
+ /** Atomic durable write used by compaction. The replacement bytes are fsynced
118
+ * before rename, then the directory entry is fsynced. Fs errors propagate to
119
+ * the caller; `compactIfNeededUnlocked` decides whether best-effort compaction
120
+ * may swallow them. */
121
+ function atomicWrite(filePath, content, opts) {
100
122
  const dir = join(filePath, '..');
123
+ const sync = opts.sync ?? fsyncSync;
101
124
  mkdirSync(dir, { recursive: true });
102
125
  const tmp = join(dir, `.${Math.random().toString(36).slice(2)}-${process.pid}-${Date.now()}.tmp`);
103
- writeFileSync(tmp, content);
126
+ const fd = openSync(tmp, 'wx');
127
+ let failure;
128
+ try {
129
+ writeFileSync(fd, content);
130
+ sync(fd);
131
+ }
132
+ catch (error) {
133
+ failure = error;
134
+ }
135
+ try {
136
+ closeSync(fd);
137
+ }
138
+ catch (error) {
139
+ if (failure === undefined)
140
+ failure = error;
141
+ }
142
+ if (failure !== undefined) {
143
+ try {
144
+ unlinkSync(tmp);
145
+ }
146
+ catch {
147
+ // Preserve the original write or close failure.
148
+ }
149
+ throw failure;
150
+ }
104
151
  try {
105
152
  renameSync(tmp, filePath);
153
+ syncDirectory(dir, sync);
106
154
  }
107
155
  catch (err) {
108
156
  try {
@@ -116,24 +164,93 @@ function atomicWrite(filePath, content) {
116
164
  }
117
165
  /**
118
166
  * Every valid record in `file`, oldest first. A missing/unreadable file reads as
119
- * `[]`. Blank lines are skipped silently; every other unusable line is skipped
120
- * and reported through `warn` with its 1-indexed line number. Never throws.
167
+ * `[]`. A trailing newline is the record-commit marker: an unterminated final
168
+ * tail may be a concurrent writer still appending. File modification time starts
169
+ * the grace, so a recently modified tail is ignored silently while an already-old
170
+ * tail warns on the first read even in a fresh process. File identity, size, tail,
171
+ * or modification changes restart the observation; a newline clears it. Blank lines are
172
+ * skipped silently; every other unusable COMPLETE line is skipped and reported
173
+ * through `warn` with its 1-indexed line number. Never throws.
121
174
  */
122
175
  export function readSessions(file, opts = {}) {
123
176
  const warn = opts.warn ?? defaultWarn;
124
177
  let raw;
178
+ let metadata;
179
+ let fd;
125
180
  try {
126
- raw = readFileSync(file, 'utf8');
181
+ fd = openSync(file, 'r');
182
+ raw = readFileSync(fd, 'utf8');
183
+ const stat = fstatSync(fd);
184
+ metadata = {
185
+ identity: `${stat.dev}:${stat.ino}`,
186
+ size: stat.size,
187
+ mtimeMs: stat.mtimeMs,
188
+ };
127
189
  }
128
190
  catch {
191
+ tailObservations.delete(file);
129
192
  return []; // fail-open: no store yet is the normal first-run case
130
193
  }
194
+ finally {
195
+ if (fd !== undefined) {
196
+ try {
197
+ closeSync(fd);
198
+ }
199
+ catch {
200
+ // The bytes and metadata were already captured; a close failure cannot
201
+ // make a resumable record safer, so preserve the read path's fail-open stance.
202
+ }
203
+ }
204
+ }
131
205
  const out = [];
132
206
  const lines = raw.split('\n');
207
+ const hasUncommittedTail = raw !== '' && !raw.endsWith('\n');
208
+ if (!hasUncommittedTail) {
209
+ tailObservations.delete(file);
210
+ }
211
+ else {
212
+ const tail = lines.at(-1) ?? '';
213
+ if (tail.trim() === '') {
214
+ tailObservations.delete(file);
215
+ }
216
+ else {
217
+ const now = (opts.now ?? Date.now)();
218
+ const graceMs = opts.unterminatedTailGraceMs ?? DEFAULT_UNTERMINATED_TAIL_GRACE_MS;
219
+ const observed = tailObservations.get(file);
220
+ const sameObservation = observed !== undefined
221
+ && observed.identity === metadata.identity
222
+ && observed.size === metadata.size
223
+ && observed.mtimeMs === metadata.mtimeMs
224
+ && observed.tail === tail;
225
+ if (!sameObservation) {
226
+ // mtime is persisted by the filesystem, so an abandoned tail can be
227
+ // recognized on the first read of a fresh one-shot process. Clamp a
228
+ // future timestamp to `now` for clock skew and injected test clocks.
229
+ const firstSeenAt = Math.min(now, metadata.mtimeMs);
230
+ const next = {
231
+ ...metadata,
232
+ tail,
233
+ firstSeenAt,
234
+ warned: false,
235
+ };
236
+ tailObservations.set(file, next);
237
+ if (now - firstSeenAt >= graceMs) {
238
+ warn(`owenloop work sessions: persistent unterminated record at ${file}:${lines.length}`);
239
+ next.warned = true;
240
+ }
241
+ }
242
+ else if (observed !== undefined && !observed.warned && now - observed.firstSeenAt >= graceMs) {
243
+ warn(`owenloop work sessions: persistent unterminated record at ${file}:${lines.length}`);
244
+ observed.warned = true;
245
+ }
246
+ }
247
+ }
133
248
  for (let i = 0; i < lines.length; i++) {
134
249
  const line = lines[i];
135
250
  if (line === undefined)
136
251
  continue; // noUncheckedIndexedAccess
252
+ if (hasUncommittedTail && i === lines.length - 1)
253
+ continue;
137
254
  if (line.trim() === '')
138
255
  continue; // blank lines are not corruption
139
256
  let parsed;
@@ -166,13 +283,40 @@ export function latestFor(file, workflow, run, step) {
166
283
  }
167
284
  return best;
168
285
  }
169
- /**
170
- * Rewrite `file` with only the last record per `(workflow, run, step)`,
171
- * preserving FIRST-SEEN key order, via temp file + rename. Corrupt lines are
172
- * dropped in the process (they were already unreadable). A missing file is a
173
- * no-op. Fs failures propagate here; `appendSession` is what swallows them.
174
- */
175
- export function compact(file, opts = {}) {
286
+ /** The lock shared by append and compaction for one session log. */
287
+ function writerLockPath(file) {
288
+ return `${file}.lock`;
289
+ }
290
+ /** Run one complete writer transaction under the cross-process session lock. */
291
+ function withWriterLock(file, operation) {
292
+ const lock = acquireFileLockSync(writerLockPath(file), {
293
+ waitMs: 30_000,
294
+ label: 'owenloop session-store write',
295
+ });
296
+ try {
297
+ return operation();
298
+ }
299
+ finally {
300
+ releaseFileLock(lock);
301
+ }
302
+ }
303
+ /** True when an existing nonempty log does not end at a JSONL commit marker. */
304
+ function needsRecordSeparator(file) {
305
+ const stat = statSync(file, { throwIfNoEntry: false });
306
+ if (stat === undefined || stat.size === 0)
307
+ return false;
308
+ const fd = openSync(file, 'r');
309
+ try {
310
+ const last = Buffer.allocUnsafe(1);
311
+ const read = readSync(fd, last, 0, 1, stat.size - 1);
312
+ return read !== 1 || last[0] !== 0x0a;
313
+ }
314
+ finally {
315
+ closeSync(fd);
316
+ }
317
+ }
318
+ /** Lock must already be held by the caller. */
319
+ function compactUnlocked(file, opts) {
176
320
  const records = readSessions(file, opts);
177
321
  if (records.length === 0)
178
322
  return;
@@ -183,7 +327,58 @@ export function compact(file, opts = {}) {
183
327
  byKey.set(keyOf(rec.workflow, rec.run, rec.step), rec);
184
328
  }
185
329
  const body = [...byKey.values()].map((r) => JSON.stringify(r)).join('\n');
186
- atomicWrite(file, `${body}\n`);
330
+ atomicWrite(file, `${body}\n`, opts);
331
+ }
332
+ /** Lock must already be held. Append exactly one committed JSONL row.
333
+ * `active` is fsynced before returning because provider work is gated on this
334
+ * call. Later statuses use ordinary close-to-flush durability. */
335
+ function appendSessionUnlocked(file, rec, opts) {
336
+ const separator = needsRecordSeparator(file) ? '\n' : '';
337
+ const existed = statSync(file, { throwIfNoEntry: false }) !== undefined;
338
+ const fd = openSync(file, 'a');
339
+ let failure;
340
+ try {
341
+ writeFileSync(fd, `${separator}${JSON.stringify(rec)}\n`);
342
+ if (rec.status === 'active') {
343
+ const sync = opts.sync ?? fsyncSync;
344
+ sync(fd);
345
+ if (!existed)
346
+ syncDirectory(join(file, '..'), sync);
347
+ }
348
+ }
349
+ catch (error) {
350
+ failure = error;
351
+ }
352
+ try {
353
+ closeSync(fd);
354
+ }
355
+ catch (error) {
356
+ if (failure === undefined)
357
+ failure = error;
358
+ }
359
+ if (failure !== undefined)
360
+ throw failure;
361
+ }
362
+ /** Lock must already be held. Compaction remains best-effort after committed JSONL appends. */
363
+ function compactIfNeededUnlocked(file, opts) {
364
+ const maxBytes = opts.maxBytes ?? DEFAULT_MAX_BYTES;
365
+ try {
366
+ if (statSync(file).size > maxBytes)
367
+ compactUnlocked(file, opts);
368
+ }
369
+ catch {
370
+ // An un-compacted (or unstatable) file still contains the committed rows.
371
+ }
372
+ }
373
+ /**
374
+ * Rewrite `file` with only the last record per `(workflow, run, step)`,
375
+ * preserving FIRST-SEEN key order, via temp file + rename. Corrupt lines are
376
+ * dropped in the process (they were already unreadable). A missing file is a
377
+ * no-op. The complete read/rewrite/rename transaction shares the same lock as
378
+ * append, so a successful append cannot be replaced by this snapshot.
379
+ */
380
+ export function compact(file, opts = {}) {
381
+ withWriterLock(file, () => compactUnlocked(file, opts));
187
382
  }
188
383
  /**
189
384
  * PHASE 4 — retire every session of one RUN by appending a `dead` row per step.
@@ -197,8 +392,8 @@ export function compact(file, opts = {}) {
197
392
  *
198
393
  * WHY A NEW ROW RATHER THAN A REWRITE: the store is append-only and last-wins per
199
394
  * `(workflow, run, step)`, so appending a copy with `status: 'dead'` shadows the
200
- * live row without rewriting history — and it keeps the ACCEPTED RACE in this
201
- * module's header (compaction losing concurrent appends) as the only writer race.
395
+ * live row without rewriting history. The shared writer lock serializes each
396
+ * appended retirement with append/compaction transactions from other processes.
202
397
  *
203
398
  * IDEMPOTENT: a key whose newest row is already `dead` is skipped, so a sweep
204
399
  * that reaps the same run twice appends nothing the second time.
@@ -215,20 +410,26 @@ export function compact(file, opts = {}) {
215
410
  * Returns the step names actually marked, so a sweep can log a count.
216
411
  */
217
412
  export function markRunSessionsDead(file, workflow, run, now, opts = {}) {
218
- const newest = new Map();
219
- for (const rec of readSessions(file, opts)) {
220
- if (rec.workflow !== workflow || rec.run !== run)
221
- continue;
222
- newest.set(keyOf(rec.workflow, rec.run, rec.step), rec);
223
- }
224
- const marked = [];
225
- for (const rec of newest.values()) {
226
- if (rec.status === 'dead')
227
- continue; // already retired — nothing to append
228
- appendSession(file, { ...rec, status: 'dead', updatedAt: now }, opts);
229
- marked.push(rec.step);
230
- }
231
- return marked;
413
+ mkdirSync(join(file, '..'), { recursive: true });
414
+ return withWriterLock(file, () => {
415
+ const newest = new Map();
416
+ for (const rec of readSessions(file, opts)) {
417
+ if (rec.workflow !== workflow || rec.run !== run)
418
+ continue;
419
+ newest.set(keyOf(rec.workflow, rec.run, rec.step), rec);
420
+ }
421
+ opts.afterWriterSnapshot?.();
422
+ const marked = [];
423
+ for (const rec of newest.values()) {
424
+ if (rec.status === 'dead')
425
+ continue; // already retired — nothing to append
426
+ appendSessionUnlocked(file, { ...rec, status: 'dead', updatedAt: now }, opts);
427
+ marked.push(rec.step);
428
+ }
429
+ if (marked.length > 0)
430
+ compactIfNeededUnlocked(file, opts);
431
+ return marked;
432
+ });
232
433
  }
233
434
  /**
234
435
  * PHASE 6, ITEM 4 — retire the `active` sessions of runs that are no longer
@@ -282,38 +483,41 @@ export function markRunSessionsDead(file, workflow, run, now, opts = {}) {
282
483
  * caller can log what it took away.
283
484
  */
284
485
  export function reconcileActiveSessions(file, liveRunIds, now, opts = {}) {
285
- const newest = new Map();
286
- for (const rec of readSessions(file, opts)) {
287
- newest.set(keyOf(rec.workflow, rec.run, rec.step), rec);
288
- }
289
- const retired = [];
290
- for (const rec of newest.values()) {
291
- if (rec.status !== 'active')
292
- continue; // a completed turn is still resumable
293
- if (liveRunIds.has(rec.run))
294
- continue; // its worker is alive; the row is true
295
- appendSession(file, { ...rec, status: 'dead', updatedAt: now }, opts);
296
- retired.push(rec);
297
- }
298
- return retired;
486
+ mkdirSync(join(file, '..'), { recursive: true });
487
+ return withWriterLock(file, () => {
488
+ const newest = new Map();
489
+ for (const rec of readSessions(file, opts)) {
490
+ newest.set(keyOf(rec.workflow, rec.run, rec.step), rec);
491
+ }
492
+ opts.afterWriterSnapshot?.();
493
+ const retired = [];
494
+ for (const rec of newest.values()) {
495
+ if (rec.status !== 'active')
496
+ continue; // a completed turn is still resumable
497
+ if (liveRunIds.has(rec.run))
498
+ continue; // its worker is alive; the row is true
499
+ appendSessionUnlocked(file, { ...rec, status: 'dead', updatedAt: now }, opts);
500
+ retired.push(rec);
501
+ }
502
+ if (retired.length > 0)
503
+ compactIfNeededUnlocked(file, opts);
504
+ return retired;
505
+ });
299
506
  }
300
507
  /**
301
508
  * Append one record, then compact when the file has grown past `maxBytes`.
302
509
  *
303
- * The whole line is written in ONE `appendFileSync` call (with its trailing
304
- * newline) so concurrent workers' O_APPEND writes interleave line-atomically on
305
- * local filesystems. Append failures PROPAGATE — see this module's failure
306
- * stance. The post-append compaction is best-effort and swallowed.
510
+ * The cross-process writer lock covers the WHOLE transaction: abandoned-tail
511
+ * quarantine, append, size check, and optional compaction rename. If a crashed
512
+ * writer left bytes without the JSONL commit newline, a leading newline commits
513
+ * only that fragment as corrupt before the new complete record. Append and lock
514
+ * failures PROPAGATE; post-append compaction remains best-effort because the
515
+ * appended line is already committed by its trailing JSONL newline in the original log.
307
516
  */
308
517
  export function appendSession(file, rec, opts = {}) {
309
518
  mkdirSync(join(file, '..'), { recursive: true });
310
- appendFileSync(file, `${JSON.stringify(rec)}\n`);
311
- const maxBytes = opts.maxBytes ?? DEFAULT_MAX_BYTES;
312
- try {
313
- if (statSync(file).size > maxBytes)
314
- compact(file, opts);
315
- }
316
- catch {
317
- // best-effort: an un-compacted (or unstatable) file is still correct.
318
- }
519
+ withWriterLock(file, () => {
520
+ appendSessionUnlocked(file, rec, opts);
521
+ compactIfNeededUnlocked(file, opts);
522
+ });
319
523
  }
@@ -4,13 +4,16 @@
4
4
  * A born-bound work-holder: the D2 stamped Step Agent's frontmatter declares
5
5
  * `mcpServers.owenloop = owenloop work hold --order <wf>/<run> --origin <url> --mcp`,
6
6
  * so when the Step Agent session boots it launches THIS as a stdio MCP server. The
7
- * server exposes two bare tools the model uses to do its order:
7
+ * server exposes three bare tools the model uses to do its order:
8
8
  * - `get_order` → the order packet (prompt, inputs, owed outputs) for the run
9
9
  * this holder is bound to. No ids are arguments — they came in on argv, never
10
10
  * through the model.
11
11
  * - `submit` → post a receipt for an owed output path; when the hub reports
12
12
  * the submit CLOSED the run, the lease loop is stopped with `release:false`
13
13
  * (the claim is already gone).
14
+ * - `reject` → invalidate a consumed artifact through the claiming step's
15
+ * server-derived authority; the client never supplies `by`. A CLOSED reject
16
+ * also stops the lease loop without releasing the already-closed claim.
14
17
  *
15
18
  * Underneath the tools, the SAME lease loop the CLI `hold` runs keeps the order's
16
19
  * lease warm: `createHoldMcp` builds the loop with `onOrder` wired to capture the
@@ -26,11 +29,26 @@
26
29
  import { type ToolRegistration } from '../mcp/server.ts';
27
30
  import type { HubClient } from '../hub/client.ts';
28
31
  import type { ContactHolder } from '../hub/types.ts';
32
+ import { type SubmissionKeyManager } from '../submit-proof.ts';
33
+ import type { SshProcessAdapter } from '../../../../src/crypto/ssh.ts';
34
+ import type { ConsumedVerifier } from '../consumed-verifier.ts';
29
35
  import { type HoldLoop } from './loop.ts';
36
+ export declare const HOLD_MCP_TOOL_NAMES: readonly ["get_order", "submit", "reject"];
37
+ export type HoldMcpToolName = (typeof HOLD_MCP_TOOL_NAMES)[number];
30
38
  export interface HoldMcpDeps {
31
39
  hub: HubClient;
32
40
  workflow: string;
33
41
  run: string;
42
+ /** Positive registration list. Absent exposes the full three-tool server. */
43
+ tools?: readonly HoldMcpToolName[];
44
+ /** Hub origin used to resolve the local machine signing key. */
45
+ origin?: string;
46
+ principalKeys?: SubmissionKeyManager;
47
+ env?: Record<string, string | undefined>;
48
+ /** Injectable ssh-keygen seam for hermetic submit-proof tests. */
49
+ sshProcess?: SshProcessAdapter;
50
+ /** Gate dynamic consumed values before the packet reaches the model. */
51
+ consumedVerifier?: ConsumedVerifier;
34
52
  /** B3 holder tag; rides get_order/heartbeat when known. */
35
53
  holder?: ContactHolder;
36
54
  sleep: (ms: number) => Promise<void>;
@@ -42,14 +60,16 @@ export interface HoldMcpDeps {
42
60
  jumpToleranceMs?: number;
43
61
  }
44
62
  export interface HoldMcpMount {
45
- /** The two tools (`get_order`, `submit`) for the MCP server. */
63
+ /** Exactly the selected registrations; full mode has all three tools. */
46
64
  tools: ToolRegistration[];
47
65
  /** The lease loop kept warm underneath — the role runs and stops it. */
48
66
  loop: HoldLoop;
49
67
  }
50
68
  /**
51
- * Build the hold MCP mount: the lease loop plus its two tools. The caller (the
52
- * role) creates the MCP server around `tools`, starts `loop.run()`, and pumps
53
- * stdin — stopping the loop on stdin EOF.
69
+ * Build the hold MCP mount: the lease loop plus a positive tool selection. The
70
+ * default selection is the full `get_order`/`submit`/`reject` surface. A caller
71
+ * can request an exact subset; future registrations do not enter that subset
72
+ * unless the caller names them. The role creates the MCP server around `tools`,
73
+ * starts `loop.run()`, and pumps stdin — stopping the loop on stdin EOF.
54
74
  */
55
75
  export declare function createHoldMcp(deps: HoldMcpDeps): HoldMcpMount;