@sema-agent/core 7.61.0 → 7.63.0

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 (298) hide show
  1. package/CHANGELOG.md +840 -0
  2. package/dist/agents/cascade.d.ts +11 -3
  3. package/dist/agents/cascade.js +1 -1
  4. package/dist/agents/peer-held-queue.d.ts +27 -4
  5. package/dist/agents/peer-held-queue.js +81 -36
  6. package/dist/agents/peer-session-drain.js +13 -3
  7. package/dist/agents/subagent-transcript-placement.d.ts +23 -0
  8. package/dist/agents/subagent-transcript-placement.js +14 -0
  9. package/dist/agents/subagent.d.ts +6 -1
  10. package/dist/agents/subagent.js +143 -58
  11. package/dist/agents/suspend-guard.d.ts +38 -16
  12. package/dist/agents/suspend-guard.js +9 -4
  13. package/dist/agents/verify.js +4 -3
  14. package/dist/brain/route-adjudicator.js +9 -4
  15. package/dist/core/approval-object.js +1 -1
  16. package/dist/core/arg-summary.js +1 -1
  17. package/dist/core/ask-question.d.ts +2 -2
  18. package/dist/core/canonical-json.d.ts +23 -13
  19. package/dist/core/canonical-json.js +4 -4
  20. package/dist/core/checkpoint-features.d.ts +722 -0
  21. package/dist/core/checkpoint-features.js +98 -0
  22. package/dist/core/checkpoint-queries.d.ts +47 -4
  23. package/dist/core/checkpoint-queries.js +36 -16
  24. package/dist/core/checkpoint-requirements.d.ts +12 -5
  25. package/dist/core/checkpoint-requirements.js +11 -5
  26. package/dist/core/checkpoint-row-verdict.d.ts +110 -0
  27. package/dist/core/checkpoint-row-verdict.js +245 -0
  28. package/dist/core/checkpoint-store.d.ts +76 -753
  29. package/dist/core/checkpoint-store.js +83 -144
  30. package/dist/core/compliance.d.ts +6 -2
  31. package/dist/core/compliance.js +3 -3
  32. package/dist/core/engine-attestation.d.ts +1 -1
  33. package/dist/core/engine-notice.d.ts +38 -7
  34. package/dist/core/engine-notice.js +9 -2
  35. package/dist/core/gate-fold.js +2 -2
  36. package/dist/core/git-worktree-env.d.ts +62 -3
  37. package/dist/core/git-worktree-env.js +91 -30
  38. package/dist/core/governance-codes.d.ts +9 -3
  39. package/dist/core/governance-codes.js +16 -3
  40. package/dist/core/hooks.d.ts +13 -0
  41. package/dist/core/human-input-projection.d.ts +1 -0
  42. package/dist/core/human-input-projection.js +3 -0
  43. package/dist/core/image-admission.d.ts +1 -1
  44. package/dist/core/locked-config.d.ts +2 -2
  45. package/dist/core/mcp-host-seat.js +6 -1
  46. package/dist/core/memory-engine/consolidation-driver.d.ts +33 -18
  47. package/dist/core/memory-engine/consolidation-driver.js +99 -98
  48. package/dist/core/memory-engine/consolidation.d.ts +73 -10
  49. package/dist/core/memory-engine/consolidation.js +167 -11
  50. package/dist/core/memory-engine/data-plane.d.ts +8 -4
  51. package/dist/core/memory-engine/data-plane.js +11 -6
  52. package/dist/core/memory-engine/delegation-settlement.d.ts +37 -35
  53. package/dist/core/memory-engine/delegation-settlement.js +53 -59
  54. package/dist/core/memory-engine/dual-root.d.ts +12 -6
  55. package/dist/core/memory-engine/dual-root.js +9 -5
  56. package/dist/core/memory-engine/engine.d.ts +98 -35
  57. package/dist/core/memory-engine/engine.js +477 -380
  58. package/dist/core/memory-engine/entry-scan.d.ts +8 -0
  59. package/dist/core/memory-engine/entry-scan.js +3 -0
  60. package/dist/core/memory-engine/file-backend.d.ts +29 -3
  61. package/dist/core/memory-engine/file-backend.js +66 -35
  62. package/dist/core/memory-engine/index.d.ts +7 -7
  63. package/dist/core/memory-engine/index.js +6 -6
  64. package/dist/core/memory-engine/landing-admission.d.ts +5 -3
  65. package/dist/core/memory-engine/landing-admission.js +3 -3
  66. package/dist/core/memory-engine/layout.d.ts +121 -45
  67. package/dist/core/memory-engine/layout.js +252 -102
  68. package/dist/core/memory-engine/memory-backend-contract.d.ts +19 -1
  69. package/dist/core/memory-engine/memory-backend-contract.js +320 -0
  70. package/dist/core/memory-engine/memory-deployment.d.ts +31 -8
  71. package/dist/core/memory-engine/memory-deployment.js +26 -12
  72. package/dist/core/memory-engine/scope-contract.d.ts +52 -11
  73. package/dist/core/memory-engine/scope-contract.js +68 -19
  74. package/dist/core/memory-engine/session-write-home.d.ts +3 -1
  75. package/dist/core/memory-engine/session-write-home.js +1 -1
  76. package/dist/core/memory-engine/sync-client.d.ts +3 -1
  77. package/dist/core/memory-engine/sync-client.js +7 -0
  78. package/dist/core/memory-engine/sync-report.d.ts +3 -2
  79. package/dist/core/memory-engine/sync-report.js +6 -2
  80. package/dist/core/memory-engine/tools.d.ts +2 -2
  81. package/dist/core/memory-engine/tools.js +10 -10
  82. package/dist/core/memory-engine/types.d.ts +118 -19
  83. package/dist/core/memory-engine/types.js +1 -0
  84. package/dist/core/memory-vector.d.ts +1 -1
  85. package/dist/core/memory.d.ts +10 -10
  86. package/dist/core/memory.js +15 -6
  87. package/dist/core/mode-policy.js +1 -1
  88. package/dist/core/mods/classic-events.d.ts +9 -1
  89. package/dist/core/mods/dollar.d.ts +32 -1
  90. package/dist/core/mods/dollar.js +13 -1
  91. package/dist/core/mods/kernel/events.d.ts +11 -3
  92. package/dist/core/mods/kernel/events.js +13 -10
  93. package/dist/core/mods/lifecycle-stations.d.ts +36 -4
  94. package/dist/core/mods/lifecycle-stations.js +44 -9
  95. package/dist/core/mods/session-append.d.ts +4 -1
  96. package/dist/core/mods/session-append.js +7 -0
  97. package/dist/core/mods/session-receive.js +12 -15
  98. package/dist/core/mods/stations.d.ts +70 -6
  99. package/dist/core/mods/stations.js +144 -1
  100. package/dist/core/own-property-receipt.d.ts +7 -0
  101. package/dist/core/own-property-receipt.js +3 -0
  102. package/dist/core/park-selfcheck.js +2 -2
  103. package/dist/core/pause-registry.d.ts +2 -0
  104. package/dist/core/pause-registry.js +3 -0
  105. package/dist/core/permission-rule-consent.d.ts +10 -3
  106. package/dist/core/permission-rule-consent.js +37 -24
  107. package/dist/core/permission-rule-store.d.ts +35 -1
  108. package/dist/core/permission-rule-store.js +27 -8
  109. package/dist/core/read-only-shell.js +3 -2
  110. package/dist/core/read-root-candidate.js +1 -1
  111. package/dist/core/redaction-marks.d.ts +8 -0
  112. package/dist/core/redaction-marks.js +6 -0
  113. package/dist/core/remote-env.d.ts +12 -1
  114. package/dist/core/remote-env.js +3 -0
  115. package/dist/core/resume-startup-cause.d.ts +5 -4
  116. package/dist/core/runner/child-tree.d.ts +29 -3
  117. package/dist/core/runner/child-tree.js +39 -16
  118. package/dist/core/runner/compact-session.js +5 -2
  119. package/dist/core/runner/contracts.d.ts +36 -17
  120. package/dist/core/runner/delegation-owner.d.ts +43 -0
  121. package/dist/core/runner/delegation-owner.js +59 -0
  122. package/dist/core/runner/gate-exit.js +2 -2
  123. package/dist/core/runner/inherited-ask-grants.js +1 -1
  124. package/dist/core/runner/lineage-reroot-view.d.ts +56 -0
  125. package/dist/core/runner/lineage-reroot-view.js +108 -0
  126. package/dist/core/runner/memory-consolidation-driver.d.ts +6 -3
  127. package/dist/core/runner/memory-consolidation-driver.js +4 -4
  128. package/dist/core/runner/memory-consolidation-write-judge.d.ts +2 -1
  129. package/dist/core/runner/memory-consolidation-write-judge.js +3 -2
  130. package/dist/core/runner/permission-rule-lanes.d.ts +2 -1
  131. package/dist/core/runner/permission-rule-lanes.js +2 -2
  132. package/dist/core/runner/person-path-rows.d.ts +23 -3
  133. package/dist/core/runner/person-path-rows.js +31 -4
  134. package/dist/core/runner/placement-fence.d.ts +12 -0
  135. package/dist/core/runner/placement-fence.js +20 -6
  136. package/dist/core/runner/prepare-acquire-reconcile.d.ts +4 -1
  137. package/dist/core/runner/prepare-acquire-reconcile.js +7 -2
  138. package/dist/core/runner/prepare-ask-lane.js +2 -2
  139. package/dist/core/runner/prepare-caps-and-workflow.d.ts +5 -1
  140. package/dist/core/runner/prepare-caps-and-workflow.js +6 -3
  141. package/dist/core/runner/prepare-config-doors.d.ts +6 -6
  142. package/dist/core/runner/prepare-config-doors.js +3 -4
  143. package/dist/core/runner/prepare-execution-env.js +17 -6
  144. package/dist/core/runner/prepare-hands-readface.d.ts +3 -2
  145. package/dist/core/runner/prepare-hands-readface.js +32 -10
  146. package/dist/core/runner/prepare-inherited-gate.d.ts +12 -8
  147. package/dist/core/runner/prepare-inherited-gate.js +14 -6
  148. package/dist/core/runner/prepare-memory-engine-session.d.ts +2 -4
  149. package/dist/core/runner/prepare-memory-engine-session.js +4 -4
  150. package/dist/core/runner/prepare-memory.d.ts +3 -2
  151. package/dist/core/runner/prepare-memory.js +28 -20
  152. package/dist/core/runner/prepare-park-ask.js +4 -3
  153. package/dist/core/runner/prepare-task.js +22 -16
  154. package/dist/core/runner/prepare-workspace-restore.js +3 -6
  155. package/dist/core/runner/resume-admission.d.ts +3 -3
  156. package/dist/core/runner/resume-admission.js +6 -3
  157. package/dist/core/runner/resume-apply.d.ts +4 -0
  158. package/dist/core/runner/resume-apply.js +11 -4
  159. package/dist/core/runner/resume-checkpoint-screen.d.ts +9 -0
  160. package/dist/core/runner/resume-checkpoint-screen.js +4 -84
  161. package/dist/core/runner/run-git-lane.d.ts +2 -0
  162. package/dist/core/runner/run-git-lane.js +4 -1
  163. package/dist/core/runner/run-harness-handlers.d.ts +2 -0
  164. package/dist/core/runner/run-harness-handlers.js +3 -2
  165. package/dist/core/runner/run-leg.js +25 -8
  166. package/dist/core/runner/run-settle-and-teardown.js +6 -4
  167. package/dist/core/runner/run-stop-and-final-verify.js +2 -1
  168. package/dist/core/runner/run-turn-boundary.js +7 -4
  169. package/dist/core/runner/runtask.js +6 -6
  170. package/dist/core/runner/steering-preview.d.ts +9 -0
  171. package/dist/core/runner/steering-preview.js +5 -0
  172. package/dist/core/runner/stream-steer-verb.js +8 -0
  173. package/dist/core/runner/terminal-account.js +1 -1
  174. package/dist/core/runner/tool-face-overlay.js +2 -0
  175. package/dist/core/runner/turn-attachments.d.ts +5 -0
  176. package/dist/core/runner/turn-attachments.js +1 -1
  177. package/dist/core/runner-deps.d.ts +8 -4
  178. package/dist/core/secret-env.d.ts +9 -6
  179. package/dist/core/secret-env.js +41 -22
  180. package/dist/core/session-checkout.d.ts +108 -0
  181. package/dist/core/session-checkout.js +485 -0
  182. package/dist/core/session-store.d.ts +13 -5
  183. package/dist/core/session-store.js +28 -4
  184. package/dist/core/session.d.ts +29 -5
  185. package/dist/core/session.js +3 -0
  186. package/dist/core/store-contracts/checkpoint-store-contract.d.ts +6 -12
  187. package/dist/core/store-contracts/checkpoint-store-contract.js +73 -6
  188. package/dist/core/store-contracts/session-store-contract.js +61 -8
  189. package/dist/core/task-event.d.ts +28 -1
  190. package/dist/core/task-notification.d.ts +9 -1
  191. package/dist/core/task-notification.js +8 -1
  192. package/dist/core/task-registry-agent.d.ts +40 -8
  193. package/dist/core/task-registry-agent.js +57 -24
  194. package/dist/core/task-registry-shared.d.ts +33 -11
  195. package/dist/core/task-registry-workflow.js +4 -3
  196. package/dist/core/task-registry.d.ts +27 -10
  197. package/dist/core/task-registry.js +19 -13
  198. package/dist/core/task-result.d.ts +5 -5
  199. package/dist/core/task-spec-members.js +1 -1
  200. package/dist/core/task-spec.d.ts +21 -1
  201. package/dist/core/terminal-cause.d.ts +6 -6
  202. package/dist/core/tool-face.d.ts +6 -2
  203. package/dist/core/tool-face.js +1 -1
  204. package/dist/core/tool-policy.d.ts +16 -13
  205. package/dist/core/tool-policy.js +11 -10
  206. package/dist/core/tool-roster.d.ts +4 -4
  207. package/dist/core/tool-spec.d.ts +42 -19
  208. package/dist/core/types.d.ts +2 -2
  209. package/dist/core/types.js +1 -1
  210. package/dist/core/untrusted-egress.d.ts +15 -4
  211. package/dist/core/untrusted-egress.js +23 -22
  212. package/dist/core/workspace-snapshot.d.ts +3 -1
  213. package/dist/core/workspace-snapshot.js +1 -0
  214. package/dist/engine/execution-env/node-execution-env.d.ts +3 -0
  215. package/dist/engine/execution-env/node-execution-env.js +12 -5
  216. package/dist/engine/harness/types.d.ts +77 -1
  217. package/dist/engine/harness/types.js +108 -0
  218. package/dist/engine/session/import-validate.js +6 -1
  219. package/dist/engine/session/parent-chain-guard.d.ts +3 -3
  220. package/dist/engine/session/parent-chain-guard.js +1 -1
  221. package/dist/engine/session/path-to-root.d.ts +18 -3
  222. package/dist/engine/session/path-to-root.js +15 -1
  223. package/dist/engine/session/repo-utils.d.ts +12 -1
  224. package/dist/engine/session/repo-utils.js +41 -0
  225. package/dist/engine/session/session.d.ts +24 -1
  226. package/dist/engine/session/session.js +46 -2
  227. package/dist/engine/session/storage-base.d.ts +20 -0
  228. package/dist/engine/session/storage-base.js +28 -9
  229. package/dist/index.d.ts +16 -12
  230. package/dist/index.js +11 -8
  231. package/dist/internal/harness-types.d.ts +1 -1
  232. package/dist/internal/harness.d.ts +4 -3
  233. package/dist/internal/harness.js +3 -2
  234. package/dist/orchestration/run-workflow-tool.d.ts +7 -1
  235. package/dist/orchestration/run-workflow-tool.js +28 -11
  236. package/dist/orchestration/workflow-governance.d.ts +1 -1
  237. package/dist/orchestration/workflow.d.ts +6 -0
  238. package/dist/orchestration/workflow.js +5 -8
  239. package/dist/stores/file/checkpoint-store.d.ts +2 -0
  240. package/dist/stores/file/checkpoint-store.js +7 -6
  241. package/dist/stores/file/fs-atomic.d.ts +0 -22
  242. package/dist/stores/file/fs-atomic.js +0 -17
  243. package/dist/stores/file/index.d.ts +2 -9
  244. package/dist/stores/file/index.js +2 -4
  245. package/dist/stores/file/session-store.d.ts +13 -7
  246. package/dist/stores/file/session-store.js +42 -18
  247. package/dist/tools/fs/bash-program-position.d.ts +3 -2
  248. package/dist/tools/fs/bash-program-position.js +10 -10
  249. package/dist/tools/fs/program-read-model.d.ts +34 -10
  250. package/dist/tools/fs/program-read-model.js +37 -7
  251. package/dist/tools/fs/program-read-model.rows.js +13 -2
  252. package/dist/tools/fs/read-deny.d.ts +13 -1
  253. package/dist/tools/fs/read-deny.js +10 -2
  254. package/dist/tools/fs/removal-targets.js +5 -5
  255. package/dist/tools/fs/safety.d.ts +2 -0
  256. package/dist/tools/fs/safety.js +1 -1
  257. package/dist/tools/fs/shell-read-argv.d.ts +11 -2
  258. package/dist/tools/fs/shell-read-argv.js +45 -29
  259. package/dist/tools/fs/shell-read-bindings.d.ts +20 -2
  260. package/dist/tools/fs/shell-read-bindings.js +153 -69
  261. package/dist/tools/fs/shell-read-brace.d.ts +18 -0
  262. package/dist/tools/fs/shell-read-brace.js +79 -0
  263. package/dist/tools/fs/shell-read-check.js +29 -11
  264. package/dist/tools/fs/shell-read-establish.js +43 -22
  265. package/dist/tools/fs/shell-read-functions.js +2 -2
  266. package/dist/tools/fs/shell-read-judge.d.ts +11 -0
  267. package/dist/tools/fs/shell-read-judge.js +3 -3
  268. package/dist/tools/fs/shell-read-object-path.d.ts +59 -0
  269. package/dist/tools/fs/shell-read-object-path.js +119 -0
  270. package/dist/tools/fs/shell-read-plan.d.ts +18 -0
  271. package/dist/tools/fs/shell-read-plan.js +217 -104
  272. package/dist/tools/fs/shell-read-start.d.ts +76 -13
  273. package/dist/tools/fs/shell-read-start.js +97 -17
  274. package/dist/tools/fs/shell-read-word.d.ts +10 -0
  275. package/dist/tools/fs/shell-read-word.js +9 -5
  276. package/dist/tools/fs/shell-read-workdir.d.ts +54 -14
  277. package/dist/tools/fs/shell-read-workdir.js +103 -19
  278. package/dist/tools/fs/shell-read-write-targets.js +13 -8
  279. package/dist/tools/worktree.d.ts +3 -2
  280. package/dist/tools/worktree.js +7 -35
  281. package/package.json +3 -2
  282. package/test/export-surface.snapshot.json +93 -43
  283. package/wire-changes/core-stores-sql@7.62.0.json +30 -0
  284. package/wire-changes/core-stores-sql@7.63.0.json +30 -0
  285. package/wire-changes/core@7.62.0.json +2181 -0
  286. package/wire-changes/core@7.63.0.json +3523 -0
  287. package/wire-changes/mods-kernel@7.62.0.json +42 -0
  288. package/wire-changes/mods-kernel@7.63.0.json +30 -0
  289. package/wire-changes/primitives@7.62.0.json +30 -0
  290. package/wire-changes/primitives@7.63.0.json +445 -0
  291. package/dist/core/consolidate-scope.d.ts +0 -93
  292. package/dist/core/consolidate-scope.js +0 -98
  293. package/dist/core/credential-vocabulary.d.ts +0 -176
  294. package/dist/core/credential-vocabulary.js +0 -190
  295. package/dist/core/redaction-passes.d.ts +0 -82
  296. package/dist/core/redaction-passes.js +0 -377
  297. package/dist/core/runner/memory-consolidation.d.ts +0 -109
  298. package/dist/core/runner/memory-consolidation.js +0 -251
@@ -374,28 +374,6 @@ export declare function acquireStoreDirLock(dir: string, opts: {
374
374
  label: string;
375
375
  fileName?: string;
376
376
  }): StoreDirLockLease;
377
- /**
378
- * design/84 Seam B (TOC profile) — a per-scope CONSOLIDATION lock factory for the file backend's
379
- * {@link import("../../core/consolidate-scope.js").ConsolidateScopeDeps.acquire} injection point. A single
380
- * machine may run a periodic-consolidation timer AND a task-end inline pass concurrently; this advisory lock
381
- * stops two processes consolidating the SAME scope at once (the in-process model the file backend assumes —
382
- * see {@link BootLock} — does not cover a second OS process with its own timer).
383
- *
384
- * `acquire(scope)` takes a {@link BootLock} over `lockDir/<sanitizedScope>.consolidate.lock`. It returns a
385
- * `release` callback on success, or `undefined` for EVERY refusal that lock knows how to make — a live
386
- * owner (including this process: a second pass here is still a conflict), a takeover in flight, an
387
- * unreadable file — because the caller's whole vocabulary is "busy → skip this pass", a no-op that costs
388
- * one deferred consolidation. A stale lock is reclaimed by the same protocol as any other, which is the
389
- * point of not hand-rolling one: this factory used to prune with a bare `unlink` and re-publish, and two
390
- * passes that had both read the same dead owner would then both prune and both publish — one deleting the
391
- * other's fresh lock, leaving two processes consolidating the SAME scope, which is exactly what the lock
392
- * exists to prevent. The reclaim gate serialises that, the depth cap bounds it, and the identity re-read
393
- * makes sure a reclaim prunes the owner it came for. One lock MECHANISM in this family, not two.
394
- *
395
- * The implementation lives HERE (the deployment shell's persist/exec axis), NOT core — core only DEFINES
396
- * the injection point (the constitutional split: gate-presence in core, mechanism in the profile).
397
- */
398
- export declare function createFileConsolidationLock(lockDir: string): (scope: string) => (() => void) | undefined;
399
377
  /**
400
378
  * A process identity that survives PID REUSE: a pid, WHEN that pid's process started, and the host the
401
379
  * observation was made on.
@@ -717,23 +717,6 @@ export function acquireStoreDirLock(dir, opts) {
717
717
  heldStoreDirLocks.set(key, entry);
718
718
  return lease(entry);
719
719
  }
720
- export function createFileConsolidationLock(lockDir) {
721
- return (scope) => {
722
- ensureDir(lockDir);
723
- const lock = new BootLock(join(lockDir, `${sanitizeScope(scope)}.consolidate.lock`));
724
- try {
725
- lock.acquire();
726
- }
727
- catch (err) {
728
- if (err instanceof FileStoreLockError)
729
- return undefined;
730
- throw err;
731
- }
732
- return () => {
733
- lock.release();
734
- };
735
- };
736
- }
737
720
  function isProcessRunning(pid) {
738
721
  try {
739
722
  process.kill(pid, 0);
@@ -24,7 +24,7 @@ export { FileFileHistoryStore, type FileFileHistoryStoreOptions } from "./file-h
24
24
  export { FileWorkflowJournalStore } from "./workflow-journal-store.js";
25
25
  export { MAX_JOURNAL_RESULT_BYTES, oversizeJournalResult } from "../../core/workflow-journal-store.js";
26
26
  export { FileUsageWindowStore, type FileUsageWindowStoreOptions } from "./usage-window-store.js";
27
- export { resolveDataRoot, sanitizeScope, sanitizePathComponent, createFileConsolidationLock } from "./fs-atomic.js";
27
+ export { resolveDataRoot, sanitizeScope, sanitizePathComponent } from "./fs-atomic.js";
28
28
  export { FileStoreLockError, type FileStoreLockErrorCode } from "./fs-atomic.js";
29
29
  export { atomicWriteFile, writeThenLink, ensureDir, readJsonlRecords, AppendLog } from "./fs-atomic.js";
30
30
  export { processFingerprint, isProcessLive, type ProcessFingerprint } from "./fs-atomic.js";
@@ -34,7 +34,7 @@ export { adoptLocalDataRoot, ackAdoptionConfig, witnessAdoptionConfig, listAdopt
34
34
  * design/80 — the file-backed {@link EngineStorageBackend} for the local (TOC) single-user binary, selected
35
35
  * purely by what the embedder injects into `RunnerDeps` (no engine change). Construct one over a single data
36
36
  * root and pass its members into the `RunnerDeps` seats of the same names (every member of the contract is
37
- * one; the class's extra members — `root`, `memoryStore`, `consolidationLock` — are not seats):
37
+ * one; the class's extra members — `root`, `memoryStore` — are not seats):
38
38
  *
39
39
  * ```ts
40
40
  * const backend = new FileStorageBackend(); // ~/.ai-agent (or $AGENT_DATA_DIR)
@@ -170,13 +170,6 @@ export declare class FileStorageBackend implements EngineStorageBackend {
170
170
  * never edited are structurally out of reach of a restore.
171
171
  */
172
172
  readonly fileHistoryStore: FileHistoryStore;
173
- /**
174
- * design/84 Seam B (TOC) — the per-scope consolidation lock for `consolidateScope`'s `acquire` injection
175
- * point: `consolidateScope(scope, { store: backend.memoryStore, llm, acquire: backend.consolidationLock })`.
176
- * Stops two OS processes sharing this data dir from consolidating the SAME scope at once (a busy scope ⇒
177
- * `undefined` ⇒ the pass is a no-op). The locks live under `root/consolidation-locks/`.
178
- */
179
- readonly consolidationLock: (scope: string) => (() => void) | undefined;
180
173
  private readonly lock;
181
174
  private readonly fileAgentRows;
182
175
  private readonly fileMailbox;
@@ -1,7 +1,7 @@
1
1
  import { join } from "node:path";
2
2
  import { guardedMemoryStore } from "../../core/memory.js";
3
3
  import { STORE_HOOK_KEYS, TtlSessionStore } from "../../core/session-store.js";
4
- import { BootLock, createFileConsolidationLock, resolveDataRoot } from "./fs-atomic.js";
4
+ import { BootLock, resolveDataRoot } from "./fs-atomic.js";
5
5
  import { assertAdoptionBootGate } from "./adoption/marker.js";
6
6
  import { FileCheckpointStore } from "./checkpoint-store.js";
7
7
  import { readLedgerTuning } from "./ledger-tuning.js";
@@ -30,7 +30,7 @@ export { FileFileHistoryStore } from "./file-history-store.js";
30
30
  export { FileWorkflowJournalStore } from "./workflow-journal-store.js";
31
31
  export { MAX_JOURNAL_RESULT_BYTES, oversizeJournalResult } from "../../core/workflow-journal-store.js";
32
32
  export { FileUsageWindowStore } from "./usage-window-store.js";
33
- export { resolveDataRoot, sanitizeScope, sanitizePathComponent, createFileConsolidationLock } from "./fs-atomic.js";
33
+ export { resolveDataRoot, sanitizeScope, sanitizePathComponent } from "./fs-atomic.js";
34
34
  export { FileStoreLockError } from "./fs-atomic.js";
35
35
  export { atomicWriteFile, writeThenLink, ensureDir, readJsonlRecords, AppendLog } from "./fs-atomic.js";
36
36
  export { processFingerprint, isProcessLive } from "./fs-atomic.js";
@@ -53,7 +53,6 @@ export class FileStorageBackend {
53
53
  mailboxStore;
54
54
  rosterStore;
55
55
  fileHistoryStore;
56
- consolidationLock;
57
56
  lock;
58
57
  fileAgentRows;
59
58
  fileMailbox;
@@ -110,7 +109,6 @@ export class FileStorageBackend {
110
109
  this.mailboxStore = this.fileMailbox;
111
110
  this.rosterStore = new FileRosterStore(join(this.root, "roster.json"), corruptRead ?? {});
112
111
  this.fileHistoryStore = new FileFileHistoryStore(this.root, { ...fileHistoryOptions, ...(corruptRead ?? {}) });
113
- this.consolidationLock = createFileConsolidationLock(join(this.root, "consolidation-locks"));
114
112
  }
115
113
  catch (err) {
116
114
  for (const undo of built.reverse()) {
@@ -9,7 +9,8 @@ export interface FileSessionRepoOptions {
9
9
  *
10
10
  * Fires for: an unreadable sessions DIRECTORY (the listing degrades to "no sessions"), a session log
11
11
  * whose header could not be read during a listing (skipped from the result — a listing reads headers,
12
- * it never replays a log), and each corrupt interior JSONL record dropped on replay plus that replay's
12
+ * it never replays a log; a PLACED row whose owner cell alone is unreadable is not skipped — the placed listing lists it — and is
13
+ * disclosed as that), and each corrupt interior JSONL record dropped on replay plus that replay's
13
14
  * tally (turns missing from an otherwise healthy session).
14
15
  *
15
16
  * Never fires on plain ENOENT / `not_found` — that is honest absence, and the torn TAIL stays silent
@@ -41,7 +42,7 @@ export declare class FileSessionRepo implements SessionRepo {
41
42
  * file whose first record is not a meta header → `corrupt_session`, even when every other record is intact
42
43
  * (every write path here lays the header down first and the header alone carries `createdAt` / fork /
43
44
  * placement / owner, so the file is not a session this store wrote, or its header line is damaged);
44
- * otherwise the session, each skipped record disclosed.
45
+ * otherwise the session, each skipped record disclosed, and `loss` = what the replay dropped (absent = nothing).
45
46
  */
46
47
  private read;
47
48
  /**
@@ -51,11 +52,14 @@ export declare class FileSessionRepo implements SessionRepo {
51
52
  * the row). `skipped` words the corrupt-header refusal's reading of the records around it, where the caller has one.
52
53
  */
53
54
  private headerOf;
55
+ /** The header's cells but its owner — what a reader of the row's lane, lineage and occupant needs, each cell through its decoder. */
56
+ private cellsOf;
54
57
  /**
55
58
  * The row's header record, where the log has one: its FIRST record, which must be the meta header every write path lays down. A log whose
56
- * first record is anything else is no row this store wrote — `corrupt_session`, said once here for every reader of the row. The cells
57
- * inside it are each read by their own reader ({@link headerOf} for the whole header, `placementOf` for the placement tuple alone):
58
- * a reader of one cell does not answer for the others.
59
+ * first record is anything else is no row this store wrote — `corrupt_session`, said once here for every reader of the row — and so is one
60
+ * whose placement cell is no placement tuple ({@link readPlacementCell}): the placement is the cell that says which lane the row lives
61
+ * in, so every reader of the row, of any other cell, goes through its judge. The other cells are each read by their own reader
62
+ * ({@link headerOf} for the whole header, `placementOf` for the placement tuple alone): a reader of one cell does not answer for the others.
59
63
  */
60
64
  private metaLineOf;
61
65
  /**
@@ -77,7 +81,8 @@ export declare class FileSessionRepo implements SessionRepo {
77
81
  /**
78
82
  * The row's {@link SessionRow} — its header cells and the newest write it holds, the log's modification time (every write to a row
79
83
  * is an append to its log; the placed listing's age reads the same time) — in one read of the header, never a replay of the log.
80
- * `undefined` = no row; a row whose header cannot be read rejects (`corrupt_session`).
84
+ * `undefined` = no row; a row whose header cannot be read rejects (`corrupt_session`) — except a PLACED row whose only unreadable cell
85
+ * is the owner's, which is {@link OwnerlessPlacedRow}: a listing asks where a row lives and how old it is, not who owns it.
81
86
  */
82
87
  private rowOf;
83
88
  /** The one descriptor a by-id read of the row takes: its size and modification time and its header decoded whole, from one inode (a
@@ -114,7 +119,8 @@ export declare class FileSessionRepo implements SessionRepo {
114
119
  * browse face never throws — but "I could not read the directory" and "there are none" are different facts, and only the sink can
115
120
  * tell them apart (ENOENT is honest absence: the constructor creates the directory, so it was removed underneath us). A session
116
121
  * whose header cannot be read is skipped and disclosed — it exists and is missing from the listing — while a file that vanished
117
- * between the directory read and its own is honest absence.
122
+ * between the directory read and its own is honest absence. A placed row whose owner alone is unreadable is neither skipped nor
123
+ * silent: it is kept (the placed listing lists it) and disclosed, once per listing, in the same sentence whichever listing reads it.
118
124
  */
119
125
  private rows;
120
126
  /**
@@ -1,6 +1,6 @@
1
1
  import { closeSync, existsSync, fstatSync, openSync, readdirSync, rmSync, utimesSync } from "node:fs";
2
2
  import { join } from "node:path";
3
- import { BaseSessionStorage, StoredSession, SessionError, assertForkTarget, compareOccupants, forkRowCells, frozenRow, getEntriesToFork, importRowCells, incarnationCell, leafIdAfterEntry, ownerCell, readIncarnationCell, readOwnerCell, resolveLeafId, rowExpectationMissed, sessionLogMarkOf, sessionRowMatches, uuidv7, validateEntriesForImport, } from "../../internal/harness.js";
3
+ import { BaseSessionStorage, StoredSession, SessionError, assertForkTarget, compareOccupants, forkRowCells, frozenRow, getEntriesToFork, importRowCells, incarnationCell, leafIdAfterEntry, ownerCell, placementCellToWrite, readIncarnationCell, readOwnerCell, readPlacementCell, replayLossText, resolveLeafId, rowExpectationMissed, sessionLogMarkOf, sessionRowMatches, uuidv7, validateEntriesForImport, } from "../../internal/harness.js";
4
4
  import { canonicalStoreKey, AppendLog, atomicWriteFile, ensureDir, firstJsonlRecord, lastJsonlRecord, readJsonlRecords, sanitizePathComponent, writeThenLink } from "./fs-atomic.js";
5
5
  import { guardCorruptSink } from "./corrupt-read-sink.js";
6
6
  import { assertAdoptionBootGate } from "./adoption/marker.js";
@@ -38,8 +38,8 @@ class FileSessionStorage extends BaseSessionStorage {
38
38
  canonicalPath;
39
39
  holders = new Set();
40
40
  occupant;
41
- constructor(log, meta, entries, canonicalPath) {
42
- super(meta, entries);
41
+ constructor(log, meta, entries, canonicalPath, replayLoss) {
42
+ super(meta, entries, undefined, replayLoss !== undefined ? { replayLoss } : undefined);
43
43
  this.log = log;
44
44
  this.canonicalPath = canonicalPath;
45
45
  this.occupant = { incarnation: meta.incarnation };
@@ -104,15 +104,19 @@ export class FileSessionRepo {
104
104
  tally = info;
105
105
  this.onCorruptRead?.({ ...info, sessionId: id });
106
106
  }, SESSION_LINE_JUDGE);
107
- const meta = this.headerOf(id, path, lines[0], () => ` (${tally?.dropped ?? 0} of ${tally?.total ?? lines.length} records skipped as corrupt)`);
107
+ const loss = tally !== undefined ? { dropped: tally.dropped, total: tally.total } : undefined;
108
+ const meta = this.headerOf(id, path, lines[0], () => ` (${replayLossText(loss ?? { dropped: 0, total: lines.length })})`);
108
109
  const entries = [];
109
110
  for (const line of lines)
110
111
  if (line.kind === "entry")
111
112
  entries.push(line.entry);
112
- return { meta, entries };
113
+ return { meta, entries, ...(loss !== undefined ? { loss } : {}) };
113
114
  }
114
115
  headerOf(id, path, first, skipped = () => "") {
115
116
  const head = this.metaLineOf(id, first, skipped);
117
+ return { ...this.cellsOf(id, path, head), owner: readOwnerCell(head.owner, id) };
118
+ }
119
+ cellsOf(id, path, head) {
116
120
  const said = (key) => (detail) => this.disclose(path, `session header ${key}: ${detail}`, id);
117
121
  const incarnation = readIncarnationCell(head.incarnation, said("incarnation"));
118
122
  const forkedFromIncarnation = readIncarnationCell(head.forkedFromIncarnation, said("forkedFromIncarnation"));
@@ -123,13 +127,14 @@ export class FileSessionRepo {
123
127
  ...(head.placement !== undefined ? { placement: head.placement } : {}),
124
128
  ...(incarnation !== undefined ? { incarnation } : {}),
125
129
  ...(forkedFromIncarnation !== undefined ? { forkedFromIncarnation } : {}),
126
- owner: readOwnerCell(head.owner, id),
127
130
  };
128
131
  }
129
132
  metaLineOf(id, first, skipped = () => "") {
130
133
  if (first === undefined || first.kind !== "meta")
131
134
  throw new SessionError("corrupt_session", `Session ${id} is unreadable: its log has no meta header${skipped()}`);
132
- return first;
135
+ const { placement: raw, ...cells } = first;
136
+ const placement = readPlacementCell(raw, id);
137
+ return { ...cells, ...(placement !== undefined ? { placement } : {}) };
133
138
  }
134
139
  async headOf(sessionId) {
135
140
  return this.headNow(sessionId);
@@ -157,7 +162,22 @@ export class FileSessionRepo {
157
162
  return { metadata: meta, head: { owner: meta.owner ?? null, incarnation: meta.incarnation, leafId: resolveLeafId(entries) }, entries };
158
163
  }
159
164
  rowOf(sessionId) {
160
- return this.atRow(sessionId, (_fd, _size, meta, mtimeMs) => ({ ...meta, lastActiveAt: Math.trunc(mtimeMs) }));
165
+ const path = this.pathFor(sessionId);
166
+ return this.atFirstRecord(sessionId, (_fd, _size, first, mtimeMs) => {
167
+ const head = this.metaLineOf(sessionId, first);
168
+ const cells = this.cellsOf(sessionId, path, head);
169
+ const lastActiveAt = Math.trunc(mtimeMs);
170
+ let owner;
171
+ try {
172
+ owner = readOwnerCell(head.owner, sessionId);
173
+ }
174
+ catch (err) {
175
+ if (head.placement === undefined || !(err instanceof SessionError))
176
+ throw err;
177
+ return { id: sessionId, placement: head.placement, lastActiveAt, ownerFault: thrownText(err) };
178
+ }
179
+ return { ...cells, owner, lastActiveAt };
180
+ });
161
181
  }
162
182
  atRow(sessionId, read) {
163
183
  const path = this.pathFor(sessionId);
@@ -181,7 +201,7 @@ export class FileSessionRepo {
181
201
  closeSync(fd);
182
202
  }
183
203
  }
184
- storage(meta, entries) {
204
+ storage(meta, entries, loss) {
185
205
  const { id } = meta;
186
206
  const canonical = canonicalStoreKey(this.pathFor(id));
187
207
  const live = sharedSessionStorages.get(canonical)?.deref();
@@ -193,7 +213,7 @@ export class FileSessionRepo {
193
213
  if (live !== undefined)
194
214
  evictSharedSessionStorage(canonical);
195
215
  const log = new AppendLog(this.pathFor(id));
196
- const created = new FileSessionStorage(log, frozenRow({ ...meta, ...(meta.placement !== undefined ? { placement: { ...meta.placement } } : {}) }), entries, canonical);
216
+ const created = new FileSessionStorage(log, frozenRow({ ...meta, ...(meta.placement !== undefined ? { placement: { ...meta.placement } } : {}) }), entries, canonical, loss);
197
217
  sharedSessionStorages.set(canonical, new WeakRef(created));
198
218
  created.addHolder(this);
199
219
  this.joined.set(canonical, new WeakRef(created));
@@ -218,7 +238,7 @@ export class FileSessionRepo {
218
238
  const path = this.pathFor(id);
219
239
  if (!existsSync(path)) {
220
240
  const owner = ownerCell(options.owner);
221
- const placement = options.placement !== undefined ? { ...options.placement, placedAt: options.placement.placedAt ?? Date.now() } : undefined;
241
+ const placement = placementCellToWrite(options.placement, id, Date.now());
222
242
  const meta = { id, createdAt, ...(placement !== undefined ? { placement } : {}), ...incarnationCell(undefined), ...owner };
223
243
  try {
224
244
  writeThenLink(path, `${JSON.stringify({ kind: "meta", ...meta })}\n`);
@@ -230,12 +250,12 @@ export class FileSessionRepo {
230
250
  }
231
251
  return new StoredSession(this.storage(meta, []));
232
252
  }
233
- const { meta, entries } = this.read(id);
234
- return new StoredSession(this.storage({ ...meta, createdAt: meta.createdAt || createdAt }, entries));
253
+ const { meta, entries, loss } = this.read(id);
254
+ return new StoredSession(this.storage({ ...meta, createdAt: meta.createdAt || createdAt }, entries, loss));
235
255
  }
236
256
  async open(metadata) {
237
- const { meta, entries } = this.read(metadata.id);
238
- return new StoredSession(this.storage(meta, entries));
257
+ const { meta, entries, loss } = this.read(metadata.id);
258
+ return new StoredSession(this.storage(meta, entries, loss));
239
259
  }
240
260
  async touch(sessionId) {
241
261
  const now = new Date();
@@ -277,8 +297,11 @@ export class FileSessionRepo {
277
297
  this.disclose(this.pathFor(id), `session log unreadable (${thrownText(err)}) — skipped from ${listing}`, id);
278
298
  continue;
279
299
  }
280
- if (row !== undefined)
281
- out.push(row);
300
+ if (row === undefined)
301
+ continue;
302
+ if ("ownerFault" in row)
303
+ this.disclose(this.pathFor(id), `session log is a placed row whose owner cell is unreadable (${row.ownerFault}) — the placed listing lists it, the host listing never does`, id);
304
+ out.push(row);
282
305
  }
283
306
  return out;
284
307
  }
@@ -320,7 +343,8 @@ export class FileSessionRepo {
320
343
  const id = options.id ?? uuidv7();
321
344
  const createdAt = new Date().toISOString();
322
345
  const path = this.pathFor(id);
323
- const meta = { id, createdAt, ...forkRowCells(await source.getMetadata(), options.owner) };
346
+ const placement = placementCellToWrite(options.placement, id, Date.now());
347
+ const meta = { id, createdAt, ...(placement !== undefined ? { placement } : {}), ...forkRowCells(await source.getMetadata(), options.owner) };
324
348
  const lines = [JSON.stringify({ kind: "meta", ...meta })];
325
349
  for (const entry of forked) {
326
350
  lines.push(JSON.stringify({ kind: "entry", entry }));
@@ -106,8 +106,9 @@ export interface ProgramPosition {
106
106
  readonly refusal: ProgramPositionRefusal | undefined;
107
107
  /** A launcher of the chain moves the directory or the root the program runs in, or where its word is looked up
108
108
  * (`env -C <dir>`, `sudo -R <dir>`, `env -P <dirs>`): the program is still the word it names, but where its path
109
- * operands resolve is not the command line's working directory — each consumer reads that as it must. */
110
- readonly launcherMovesBase: boolean;
109
+ * operands resolve is not the command line's working directory — each consumer reads that as it must. The argv index of
110
+ * each such option word the walk stepped, in order (its value is that word's rest or the next word); empty: none moves. */
111
+ readonly baseMovedAt: readonly number[];
111
112
  }
112
113
  /**
113
114
  * Read the program position of one segment's argv words.
@@ -1,6 +1,6 @@
1
1
  import { SHELL_CONTROL_PREFIXES, argvOf, lexShellText } from "../../shell/lex.js";
2
2
  import { shellWordsOf } from "../../shell/shell-words.js";
3
- import { BLOCK_WORD_NAMES, LAUNCHER_NAMES, feedsArgvFromStdin, launcherOptionMovesBase, launcherOptionQueries, launcherOptionStep, launcherRunsShell, programRow, selectedOptions, streamDefaultProgram } from "./program-read-model.js";
3
+ import { BLOCK_WORD_NAMES, feedsArgvFromStdin, launcherOptionMovesBase, launcherOptionQueries, launcherOptionStep, launcherRunsShell, programRow, selectedOptions, streamDefaultProgram } from "./program-read-model.js";
4
4
  export const NOT_AUTO_ALLOWED = "— not auto-allowed";
5
5
  export function programBasename(word) {
6
6
  return word.includes("/") ? (word.split("/").pop() ?? word) : word;
@@ -49,7 +49,7 @@ function pastLauncherOptions(launcher, folded, i, moved, queried, ended) {
49
49
  if (step === 2 && folded[i + 1] === undefined)
50
50
  return i;
51
51
  if (launcherOptionMovesBase(row, tok))
52
- moved?.();
52
+ moved?.(i);
53
53
  if (launcherOptionQueries(row, tok))
54
54
  queried?.();
55
55
  i += step;
@@ -72,7 +72,7 @@ export function readProgramPosition(words) {
72
72
  controlWords.push(i);
73
73
  i = pastLauncherOptions(controlWord, folded, i + 1);
74
74
  }
75
- const none = (written, assignments, refusal) => ({ controlWords, written, assignments, launchers: [], argvFromStdin: false, runsDefaultProgram: false, program: undefined, refusal, launcherMovesBase: false });
75
+ const none = (written, assignments, refusal) => ({ controlWords, written, assignments, launchers: [], argvFromStdin: false, runsDefaultProgram: false, program: undefined, refusal, baseMovedAt: [] });
76
76
  const globProgramRefusal = (idx) => {
77
77
  let glob = false;
78
78
  for (const p of words[idx].pieces) {
@@ -106,30 +106,30 @@ export function readProgramPosition(words) {
106
106
  const owner = controlWords.length > 0 ? folded[controlWords[controlWords.length - 1]] : head;
107
107
  return none(written, assignments, optionShaped(owner, head));
108
108
  }
109
- if (!LAUNCHER_NAMES.has(basename)) {
109
+ if (launcherRowOf(basename) === undefined) {
110
110
  const glob = globProgramRefusal(i);
111
111
  if (glob !== undefined)
112
112
  return none(written, assignments, glob);
113
- return { controlWords, written, assignments, launchers: [], argvFromStdin: false, runsDefaultProgram: false, program: { index: i, name: head, basename }, refusal: undefined, launcherMovesBase: false };
113
+ return { controlWords, written, assignments, launchers: [], argvFromStdin: false, runsDefaultProgram: false, program: { index: i, name: head, basename }, refusal: undefined, baseMovedAt: [] };
114
114
  }
115
115
  const launchers = [{ index: i, name: basename }];
116
116
  const owner = head;
117
117
  const shellRefusal = (launcher, from) => ({ kind: "control_syntax_at_program_position", owner, word: "sh", runsShell: { launcher, from } });
118
118
  let lastRow = launcherRowOf(basename)?.launcher;
119
119
  let owedOperands = lastRow?.requiredOperands ?? 0;
120
- const chain0 = (program, refusal) => ({ controlWords, written, assignments, launchers, argvFromStdin: false, runsDefaultProgram: false, program, refusal, launcherMovesBase: false });
120
+ const chain0 = (program, refusal) => ({ controlWords, written, assignments, launchers, argvFromStdin: false, runsDefaultProgram: false, program, refusal, baseMovedAt: [] });
121
121
  if (launcherRunsShell(launcherRowOf(basename), folded.slice(i + 1)))
122
122
  return chain0(undefined, shellRefusal(i, i + 1));
123
123
  let argvFromStdin = feedsArgvFromStdin(basename);
124
124
  let lastReentry = argvFromStdin ? i : -1;
125
125
  let reentryDefault = argvFromStdin ? streamDefaultProgram(basename) : undefined;
126
- let launcherMovesBase = false;
127
- const moved = () => { launcherMovesBase = true; };
126
+ const baseMovedAt = [];
127
+ const moved = (at) => { baseMovedAt.push(at); };
128
128
  let looksUp = false;
129
129
  const queried = () => { looksUp = true; };
130
130
  const chain = (program, refusal) => {
131
131
  const runsDefaultProgram = lastReentry === folded.length - 1;
132
- return { controlWords, written, assignments, launchers, argvFromStdin, runsDefaultProgram, ...(runsDefaultProgram && reentryDefault !== undefined ? { defaultProgram: reentryDefault } : {}), program, refusal, launcherMovesBase };
132
+ return { controlWords, written, assignments, launchers, argvFromStdin, runsDefaultProgram, ...(runsDefaultProgram && reentryDefault !== undefined ? { defaultProgram: reentryDefault } : {}), program, refusal, baseMovedAt };
133
133
  };
134
134
  const selectsShell = (l, end) => selectedOptions(launcherRowOf(l.name), folded.slice(l.index + 1, end)).some((o) => o.mode === "interactive");
135
135
  const first = pastLauncherOptions(basename, folded, i + 1, moved, queried, endsOptions(basename));
@@ -155,7 +155,7 @@ export function readProgramPosition(words) {
155
155
  ended.by = undefined;
156
156
  continue;
157
157
  }
158
- if (LAUNCHER_NAMES.has(wordBasename)) {
158
+ if (launcherRowOf(wordBasename) !== undefined) {
159
159
  launchers.push({ index: j, name: wordBasename });
160
160
  lastRow = launcherRowOf(wordBasename)?.launcher;
161
161
  if (launcherRunsShell(launcherRowOf(wordBasename), folded.slice(j + 1)))
@@ -2,7 +2,8 @@
2
2
  * The PROGRAM READ MODEL — one table that answers "what does this program do with its k-th word", and the readers
3
3
  * every shell face reads it through.
4
4
  *
5
- * A row is one program (the basename bash runs; a versioned spelling of an interpreter is its row), carrying every
5
+ * A row is one program (the basename bash runs; a spelling of its name the row declares — an interpreter's version, a GNU
6
+ * build's `g` — is its row), carrying every
6
7
  * argument fact the shell faces need: its option grammar (one per implementation where implementations disagree),
7
8
  * the ROLE each option value and each operand plays, whether a form walks a tree, how an interpreter receives the
8
9
  * program it runs, what a launcher steps over before the program it runs, which words a builtin keeps as shell text
@@ -305,6 +306,13 @@ export interface OperandSpec {
305
306
  readonly assignmentArguments?: "not-paths";
306
307
  /** The role of the LAST operand, unless an option delivered it ({@link OptionSpec.fillsLast}): a copy's destination. */
307
308
  readonly last?: ArgRole;
309
+ /** A LONE operand (no option delivering the last) is no destination: the program puts its copy / link in the working
310
+ * directory, under the operand's last segment (`ln -s dir/f` makes `./f`). Absent: a lone operand is the last. */
311
+ readonly loneOperand?: "into-working-directory";
312
+ /** Operands spelled `KEY=VALUE` (`dd if=… of=…`): the role of the VALUE of each key this table names — the operand is read
313
+ * in that role and its value is the path it names ({@link ArgEvent} `value`). An operand of a key the table does not name,
314
+ * or of no key, is an ordinary operand. */
315
+ readonly keyed?: Readonly<Record<string, ArgRole>>;
308
316
  /** What an ordinary operand becomes when an option selects editing in place ({@link OptionSpec.selects}). */
309
317
  readonly editedInPlace?: ArgRole;
310
318
  /** With fewer operands than this (the first-operand slot counted), the program reads its standard input; `always`:
@@ -400,10 +408,14 @@ export interface Subcommand {
400
408
  readonly operands?: OperandSpec;
401
409
  readonly traversal?: TraversalSpec;
402
410
  }
411
+ /** A spelling of a program's name, other than its row's key, that runs the row ({@link programRow}): `versioned` — the key with a
412
+ * trailing version (`python3`, `python3.11`); `gnu-prefixed` — the key behind a `g`, the name a GNU build is installed under
413
+ * beside the system's own implementation (`gln`, `gtimeout`), which runs the row's GNU grammar. */
414
+ export type ProgramSpelling = "versioned" | "gnu-prefixed";
403
415
  export interface ProgramRow {
404
416
  readonly key: string;
405
- /** A versioned spelling (`python3`, `python3.11`) is this row. */
406
- readonly versioned?: true;
417
+ /** The other spellings of the name that run this row ({@link ProgramSpelling}). */
418
+ readonly spellings?: readonly ProgramSpelling[];
407
419
  readonly grammars: readonly Grammar[];
408
420
  readonly operands?: OperandSpec;
409
421
  readonly traversal?: TraversalSpec;
@@ -437,12 +449,16 @@ export interface ProgramRow {
437
449
  readonly optionsComplete?: true;
438
450
  readonly witness: Witness;
439
451
  }
440
- /** The row bash runs for this basename: the exact key, or — for a row that declares versioned spellings — the name
441
- * with its trailing version dropped (`python3.11` is `python`). */
452
+ /** The row bash runs for this basename: the exact key, or a spelling of it the row declares ({@link ProgramRow.spellings}) —
453
+ * `python3.11` is `python`, `gln` is `ln` read by its GNU grammar. */
442
454
  export declare function programRow(name: string): ProgramRow | undefined;
455
+ /** The key of the row bash runs for this basename ({@link programRow}): what a table of programs is keyed by, so a spelling of
456
+ * a name (`gcp`) is the program it spells; the name itself where no row reads it. */
457
+ export declare function programKeyOf(name: string): string;
443
458
  /** Every row, in table order. */
444
459
  export declare function programRows(): readonly ProgramRow[];
445
- /** The launcher names — derived from the rows. */
460
+ /** The launcher rows' keys — derived from the rows (a name is read as a launcher by its row, {@link programRow}, spellings
461
+ * included). */
446
462
  export declare const LAUNCHER_NAMES: ReadonlySet<string>;
447
463
  /** The block words — derived from the rows. */
448
464
  export declare const BLOCK_WORD_NAMES: ReadonlySet<string>;
@@ -610,7 +626,8 @@ type Event<R> =
610
626
  readonly unsettled?: true;
611
627
  }
612
628
  /** An operand, the `ordinal`-th. `slot` = the first-operand slot's role when the slot applies; `role` = the role the
613
- * row declares for an operand at this position past the slot (a URL, a name it only examines); `dash` = the word is
629
+ * row declares for an operand at this position past the slot (a URL, a name it only examines), or for a `KEY=VALUE`
630
+ * operand by its key — whose `value` is then the text after the `=` ({@link OperandSpec.keyed}); `dash` = the word is
614
631
  * a lone `-`, read as standard input (`stdin`) or as a file name. */
615
632
  | {
616
633
  readonly kind: "operand";
@@ -618,6 +635,7 @@ type Event<R> =
618
635
  readonly ordinal: number;
619
636
  readonly slot?: ArgRole;
620
637
  readonly role?: ArgRole;
638
+ readonly value?: string;
621
639
  readonly dash?: "stdin" | "file";
622
640
  };
623
641
  export type ArgEvent = Event<ArgRole>;
@@ -757,8 +775,13 @@ export type WritingRole = Extract<ArgRole, {
757
775
  }>;
758
776
  /** Does this role write its path ({@link WRITING_EFFECTS})? */
759
777
  export declare function writesPath(role: ArgRole | undefined): role is WritingRole;
778
+ /** The programs whose OPERANDS the table says they write — a row whose ordinary or last operands take a writing role, a
779
+ * `KEY=VALUE` operand of a writing key (named by its key: `dd's of=`), an operand an in-place edit rewrites (`an in-place
780
+ * sed`) — in table order, as a sentence names them. The write face's refusal note reads it: the sentence names what the
781
+ * station judges by, never a list of its own. */
782
+ export declare function operandWriterNames(): readonly string[];
760
783
  /** One word an implementation's reading writes: its argv index, the value inside it when an option carries it
761
- * attached, and the role it is written by. */
784
+ * attached (or a `KEY=VALUE` operand after its key), and the role it is written by. */
762
785
  export interface WrittenWord {
763
786
  readonly at: number;
764
787
  readonly value?: string;
@@ -776,9 +799,10 @@ export interface WriteReading {
776
799
  readonly unexplained: boolean;
777
800
  /** The backup suffixes an option selecting edit-in-place was given (empty values dropped: no backup). */
778
801
  readonly suffixes: readonly string[];
779
- /** A copy's destination (argv index, and its value when an option carries it attached) and its sources. */
802
+ /** A copy's destination (argv index, and its value when an option carries it attached) and its sources; no destination:
803
+ * the working directory ({@link OperandSpec.loneOperand}). */
780
804
  readonly copy?: {
781
- readonly destination: {
805
+ readonly destination?: {
782
806
  readonly at: number;
783
807
  readonly value?: string;
784
808
  };
@@ -7,13 +7,24 @@ export const ARG_ROLE_KINDS = Object.freeze(["path", "mount-source", "object-pat
7
7
  export const PATH_EFFECTS = Object.freeze(["read", "names", "write", "create", "edit-in-place"]);
8
8
  export const WRITING_EFFECTS = new Set(["write", "create", "edit-in-place"]);
9
9
  const ROWS_BY_KEY = new Map(PROGRAM_ROWS.map((r) => [r.key, r]));
10
+ const SPELLING_FORMS = [
11
+ { form: "versioned", keyOf: (name) => name.replace(/\d+(?:\.\d+)*$/, ""), runs: (row) => row },
12
+ { form: "gnu-prefixed", keyOf: (name) => name.replace(/^g/, ""), runs: (row) => implementationsOf(row).find((view) => view.grammars[0]?.dialect === "gnu") ?? row },
13
+ ];
10
14
  export function programRow(name) {
11
15
  const exact = ROWS_BY_KEY.get(name);
12
16
  if (exact !== undefined)
13
17
  return exact;
14
- const stripped = name.replace(/\d+(?:\.\d+)*$/, "");
15
- const row = stripped === name ? undefined : ROWS_BY_KEY.get(stripped);
16
- return row?.versioned === true ? row : undefined;
18
+ for (const { form, keyOf, runs } of SPELLING_FORMS) {
19
+ const key = keyOf(name);
20
+ const row = key === name ? undefined : ROWS_BY_KEY.get(key);
21
+ if (row?.spellings?.includes(form) === true)
22
+ return runs(row);
23
+ }
24
+ return undefined;
25
+ }
26
+ export function programKeyOf(name) {
27
+ return programRow(name)?.key ?? name;
17
28
  }
18
29
  export function programRows() {
19
30
  return PROGRAM_ROWS;
@@ -510,12 +521,20 @@ function walkArgs(row, words, readOption, slot, readsRole, ownedValue) {
510
521
  }
511
522
  const inSlot = slot !== undefined && !slotSupplied && !sawOperand;
512
523
  sawOperand = true;
513
- const declared = inSlot ? undefined : slot !== undefined ? row?.operands?.positional?.[slotSupplied ? ordinal + 1 : ordinal] ?? row?.operands?.rest : row?.operands?.rest;
524
+ const keyed = inSlot ? undefined : keyedOperandOf(row, t);
525
+ const declared = keyed !== undefined ? keyed.role : inSlot ? undefined : slot !== undefined ? row?.operands?.positional?.[slotSupplied ? ordinal + 1 : ordinal] ?? row?.operands?.rest : row?.operands?.rest;
514
526
  const role = declared !== undefined && readsRole(declared) ? declared : undefined;
515
- out.push({ kind: "operand", at: k, ordinal: ordinal++, ...(inSlot ? { slot: slot.role } : {}), ...(role !== undefined ? { role } : {}), ...(t === "-" ? { dash: dashRead } : {}) });
527
+ out.push({ kind: "operand", at: k, ordinal: ordinal++, ...(inSlot ? { slot: slot.role } : {}), ...(role !== undefined ? { role, ...(keyed !== undefined ? { value: keyed.value } : {}) } : {}), ...(t === "-" ? { dash: dashRead } : {}) });
516
528
  }
517
529
  return out;
518
530
  }
531
+ function keyedOperandOf(row, word) {
532
+ const table = row?.operands?.keyed;
533
+ const eq = word.indexOf("=");
534
+ if (table === undefined || eq <= 0 || !Object.hasOwn(table, word.slice(0, eq)))
535
+ return undefined;
536
+ return { role: table[word.slice(0, eq)], value: word.slice(eq + 1) };
537
+ }
519
538
  export function readArgs(row, words, opts) {
520
539
  const slot = opts.firstOperandSlot === false ? undefined : firstOperandSlot(row);
521
540
  const owned = opts.ownedValues === true && row?.traversal?.discloses === "contents"
@@ -879,6 +898,15 @@ export function rowRefusesArgv(row, args) {
879
898
  export function writesPath(role) {
880
899
  return role?.kind === "path" && WRITING_EFFECTS.has(role.effect);
881
900
  }
901
+ export function operandWriterNames() {
902
+ const writes = (r) => writesPath(r.operands?.rest) || writesPath(r.operands?.last);
903
+ const keys = (r) => Object.entries(r.operands?.keyed ?? {}).flatMap(([k, role]) => (writesPath(role) ? [`${k}=`] : []));
904
+ return [
905
+ ...PROGRAM_ROWS.filter(writes).map((r) => r.key),
906
+ ...PROGRAM_ROWS.flatMap((r) => (keys(r).length > 0 ? [`${r.key}'s ${keys(r).join(" ")}`] : [])),
907
+ ...PROGRAM_ROWS.filter((r) => writesPath(r.operands?.editedInPlace)).map((r) => `an in-place ${r.key}`),
908
+ ];
909
+ }
882
910
  export function writeReadings(row, args) {
883
911
  return implementationsOf(row).map((view) => {
884
912
  const ops = view.operands;
@@ -906,7 +934,7 @@ export function writeReadings(row, args) {
906
934
  continue;
907
935
  const role = e.role ?? ordinary;
908
936
  if (writesPath(role))
909
- written.push({ at: e.at, role });
937
+ written.push({ at: e.at, ...(e.value !== undefined ? { value: e.value } : {}), role });
910
938
  }
911
939
  else if (e.kind === "dash-word-operand") {
912
940
  if (writesPath(ordinary))
@@ -918,7 +946,9 @@ export function writeReadings(row, args) {
918
946
  if (writesPath(last)) {
919
947
  const filled = scan.values.filter((v) => v.spec.fillsLast === true).at(-1);
920
948
  const destination = filled !== undefined ? { at: filled.at, ...(filled.value !== undefined ? { value: filled.value } : {}) } : scan.operands.length > 0 ? { at: scan.operands.at(-1) } : undefined;
921
- if (destination !== undefined) {
949
+ if (filled === undefined && scan.operands.length === 1 && ops?.loneOperand === "into-working-directory")
950
+ copy = { sources: scan.operands };
951
+ else if (destination !== undefined) {
922
952
  copy = { destination, sources: scan.operands.filter((at) => at !== destination.at) };
923
953
  for (let i = written.length - 1; i >= 0; i--)
924
954
  if (written[i].at === destination.at && written[i].value === destination.value)