@sema-agent/core 7.67.3 → 7.68.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 (496) hide show
  1. package/CHANGELOG.md +1516 -0
  2. package/README.md +18 -9
  3. package/README.zh-CN.md +16 -8
  4. package/dist/agents/agent-definition.d.ts +1 -1
  5. package/dist/agents/agent-definition.js +4 -1
  6. package/dist/agents/cascade.d.ts +2 -2
  7. package/dist/agents/cascade.js +3 -1
  8. package/dist/agents/cumulative-stats.d.ts +2 -1
  9. package/dist/agents/cumulative-stats.js +4 -1
  10. package/dist/agents/list-agents-tool.d.ts +30 -0
  11. package/dist/agents/list-agents-tool.js +45 -3
  12. package/dist/agents/peer-admission.d.ts +2 -2
  13. package/dist/agents/peer-session-drain.d.ts +2 -0
  14. package/dist/agents/peer-session-drain.js +1 -0
  15. package/dist/agents/repair-loop.js +3 -1
  16. package/dist/agents/retain-ledger.d.ts +61 -8
  17. package/dist/agents/retain-ledger.js +25 -3
  18. package/dist/agents/roster-store.d.ts +4 -2
  19. package/dist/agents/send-message-tool.d.ts +1 -1
  20. package/dist/agents/send-message-tool.js +20 -15
  21. package/dist/agents/subagent-steps.js +2 -10
  22. package/dist/agents/subagent.d.ts +3 -0
  23. package/dist/agents/subagent.js +106 -76
  24. package/dist/agents/tool-filter.d.ts +20 -11
  25. package/dist/agents/tool-filter.js +8 -4
  26. package/dist/agents/verify.d.ts +3 -1
  27. package/dist/agents/verify.js +2 -0
  28. package/dist/brain/anthropic.js +4 -4
  29. package/dist/brain/open-responses.js +3 -1
  30. package/dist/brain/openai.js +3 -1
  31. package/dist/brain/reasoning-request.d.ts +73 -19
  32. package/dist/brain/reasoning-request.js +164 -72
  33. package/dist/brain/reasoning-stamp.d.ts +26 -0
  34. package/dist/brain/reasoning-stamp.js +10 -0
  35. package/dist/brain/reasoning.d.ts +95 -162
  36. package/dist/brain/reasoning.js +31 -86
  37. package/dist/brain/route-adjudicator.d.ts +9 -7
  38. package/dist/brain/route-adjudicator.js +12 -10
  39. package/dist/brain/status-sink.d.ts +19 -64
  40. package/dist/brain/status-sink.js +5 -21
  41. package/dist/brain/stream-engine.d.ts +11 -2
  42. package/dist/brain/stream-engine.js +10 -0
  43. package/dist/core/a2a.d.ts +17 -5
  44. package/dist/core/a2a.js +11 -3
  45. package/dist/core/allow-entry.d.ts +35 -15
  46. package/dist/core/allow-entry.js +47 -60
  47. package/dist/core/ask-headline.d.ts +68 -0
  48. package/dist/core/ask-headline.js +23 -0
  49. package/dist/core/ask-origin.d.ts +36 -8
  50. package/dist/core/ask-origin.js +17 -10
  51. package/dist/core/ask-question.d.ts +34 -7
  52. package/dist/core/ask-question.js +10 -1
  53. package/dist/core/ask-unresolvable-notice.d.ts +7 -0
  54. package/dist/core/ask-unresolvable-notice.js +9 -3
  55. package/dist/core/auto-strip.d.ts +53 -0
  56. package/dist/core/auto-strip.js +76 -0
  57. package/dist/core/background-agent-store.d.ts +45 -5
  58. package/dist/core/background-agent-store.js +69 -15
  59. package/dist/core/background-shell.d.ts +2 -2
  60. package/dist/core/caller-text.js +2 -2
  61. package/dist/core/canonical-json.d.ts +13 -0
  62. package/dist/core/canonical-json.js +7 -0
  63. package/dist/core/checkpoint-features.d.ts +66 -20
  64. package/dist/core/checkpoint-features.js +12 -1
  65. package/dist/core/checkpoint-generation.d.ts +1 -1
  66. package/dist/core/checkpoint-queries.d.ts +1 -1
  67. package/dist/core/checkpoint-queries.js +4 -1
  68. package/dist/core/checkpoint-requirements.d.ts +25 -1
  69. package/dist/core/checkpoint-requirements.js +5 -1
  70. package/dist/core/checkpoint-row-verdict.d.ts +1 -0
  71. package/dist/core/checkpoint-row-verdict.js +4 -0
  72. package/dist/core/checkpoint-store.d.ts +66 -38
  73. package/dist/core/checkpoint-store.js +15 -6
  74. package/dist/core/child-clamp-seats.d.ts +6 -0
  75. package/dist/core/child-clamp-seats.js +1 -0
  76. package/dist/core/config-refusal-codes.d.ts +1 -1
  77. package/dist/core/config-refusal-codes.js +1 -0
  78. package/dist/core/delegation-frames.d.ts +9 -12
  79. package/dist/core/delegation-frames.js +9 -8
  80. package/dist/core/engine-capabilities.d.ts +21 -8
  81. package/dist/core/engine-capabilities.js +1 -1
  82. package/dist/core/engine-notice.d.ts +147 -34
  83. package/dist/core/engine-notice.js +27 -16
  84. package/dist/core/engine-storage-backend.d.ts +2 -1
  85. package/dist/core/env-budget.js +3 -3
  86. package/dist/core/env-knob-announce.d.ts +10 -10
  87. package/dist/core/env-knob-announce.js +3 -6
  88. package/dist/core/file-history-store.d.ts +29 -4
  89. package/dist/core/file-history-store.js +13 -0
  90. package/dist/core/frame-settlement.d.ts +2 -1
  91. package/dist/core/gate-fold.js +1 -1
  92. package/dist/core/gate-lanes.js +56 -49
  93. package/dist/core/governance-codes.d.ts +39 -3
  94. package/dist/core/governance-codes.js +61 -3
  95. package/dist/core/hooks.d.ts +29 -11
  96. package/dist/core/hooks.js +5 -2
  97. package/dist/core/human-input-projection.js +3 -3
  98. package/dist/core/input-author.d.ts +17 -3
  99. package/dist/core/input-author.js +15 -3
  100. package/dist/core/leg-identity.d.ts +10 -28
  101. package/dist/core/leg-identity.js +1 -21
  102. package/dist/core/lsp.d.ts +18 -13
  103. package/dist/core/lsp.js +30 -22
  104. package/dist/core/mailbox-store.d.ts +1 -1
  105. package/dist/core/mailbox-store.js +4 -4
  106. package/dist/core/mcp-connection-pool.d.ts +93 -4
  107. package/dist/core/mcp-connection-pool.js +104 -1
  108. package/dist/core/mcp-failure.d.ts +38 -12
  109. package/dist/core/mcp-failure.js +9 -13
  110. package/dist/core/mcp-probe.d.ts +4 -3
  111. package/dist/core/mcp-server-link.d.ts +4 -2
  112. package/dist/core/mcp-server-link.js +4 -5
  113. package/dist/core/mcp-server-spec.d.ts +3 -3
  114. package/dist/core/mcp-server-unavailable-notice.d.ts +22 -8
  115. package/dist/core/mcp-server-unavailable-notice.js +18 -4
  116. package/dist/core/mcp.d.ts +40 -6
  117. package/dist/core/mcp.js +39 -13
  118. package/dist/core/memory-engine/content-origin.js +2 -2
  119. package/dist/core/memory-engine/control-objects.d.ts +2 -4
  120. package/dist/core/memory-engine/control-objects.js +2 -10
  121. package/dist/core/memory-engine/delegation-settlement.js +6 -1
  122. package/dist/core/memory-engine/dual-root.js +3 -0
  123. package/dist/core/memory-engine/engine.d.ts +6 -4
  124. package/dist/core/memory-engine/engine.js +32 -29
  125. package/dist/core/memory-engine/file-backend.d.ts +20 -5
  126. package/dist/core/memory-engine/file-backend.js +21 -31
  127. package/dist/core/memory-engine/frontmatter.d.ts +2 -0
  128. package/dist/core/memory-engine/frontmatter.js +4 -0
  129. package/dist/core/memory-engine/layout.d.ts +114 -20
  130. package/dist/core/memory-engine/layout.js +340 -22
  131. package/dist/core/memory-engine/memory-deployment.d.ts +7 -5
  132. package/dist/core/memory-engine/mount-failed-notice.d.ts +19 -7
  133. package/dist/core/memory-engine/mount-failed-notice.js +43 -10
  134. package/dist/core/memory-engine/sync-client.js +4 -5
  135. package/dist/core/model-fallbacks.d.ts +5 -1
  136. package/dist/core/model-fallbacks.js +3 -3
  137. package/dist/core/model-receipt.d.ts +2 -1
  138. package/dist/core/model-receipt.js +12 -1
  139. package/dist/core/mods/kernel/dispatch.d.ts +2 -2
  140. package/dist/core/mods/kernel/dispatch.js +14 -6
  141. package/dist/core/mods/kernel/events.d.ts +8 -5
  142. package/dist/core/mods/kernel/events.js +2 -2
  143. package/dist/core/mods/kernel/index.d.ts +1 -1
  144. package/dist/core/mods/kernel/registration.d.ts +9 -0
  145. package/dist/core/mods/package.js +1 -1
  146. package/dist/core/mods/session-append.d.ts +4 -2
  147. package/dist/core/mods/session-append.js +3 -0
  148. package/dist/core/mods/stations.d.ts +7 -11
  149. package/dist/core/mods/stations.js +4 -7
  150. package/dist/core/mods/tool-call.d.ts +10 -8
  151. package/dist/core/mods/tool-call.js +15 -18
  152. package/dist/core/mounted-mcp.d.ts +0 -4
  153. package/dist/core/mounted-mcp.js +1 -1
  154. package/dist/core/park-noun.d.ts +24 -0
  155. package/dist/core/park-noun.js +21 -0
  156. package/dist/core/park-resumability.d.ts +60 -0
  157. package/dist/core/park-resumability.js +30 -0
  158. package/dist/core/permission-rule-provider.d.ts +24 -2
  159. package/dist/core/permission-rule-provider.js +11 -8
  160. package/dist/core/permission-rule-store.d.ts +8 -1
  161. package/dist/core/permission-rule-store.js +2 -3
  162. package/dist/core/permission-rules.d.ts +2 -1
  163. package/dist/core/permission-rules.js +8 -4
  164. package/dist/core/persisted-rule-arms.d.ts +3 -0
  165. package/dist/core/persisted-rule-arms.js +2 -1
  166. package/dist/core/present-plan-tool.d.ts +47 -3
  167. package/dist/core/present-plan-tool.js +62 -4
  168. package/dist/core/principal-name.d.ts +1 -1
  169. package/dist/core/principal-name.js +5 -5
  170. package/dist/core/process-identity.js +10 -5
  171. package/dist/core/protocol-http-auth.d.ts +20 -14
  172. package/dist/core/protocol-http-auth.js +70 -50
  173. package/dist/core/read-only-shell.js +9 -5
  174. package/dist/core/redaction-marks.d.ts +4 -26
  175. package/dist/core/redaction-marks.js +9 -21
  176. package/dist/core/remote-env.d.ts +43 -16
  177. package/dist/core/remote-env.js +1 -1
  178. package/dist/core/request-copy-projection.d.ts +1 -1
  179. package/dist/core/request-copy-projection.js +40 -50
  180. package/dist/core/resume-config-judge.js +1 -1
  181. package/dist/core/resume-startup-cause.d.ts +35 -18
  182. package/dist/core/resume-startup-cause.js +13 -10
  183. package/dist/core/retention.d.ts +167 -25
  184. package/dist/core/retention.js +100 -20
  185. package/dist/core/roles.d.ts +6 -0
  186. package/dist/core/roles.js +11 -5
  187. package/dist/core/rule-lane-reads.d.ts +3 -0
  188. package/dist/core/rule-lane-reads.js +5 -1
  189. package/dist/core/rule-store-fault.d.ts +70 -0
  190. package/dist/core/rule-store-fault.js +102 -0
  191. package/dist/core/runner/advertised-writable-dirs.js +16 -31
  192. package/dist/core/runner/announce-once-ledger.d.ts +19 -2
  193. package/dist/core/runner/announce-once-ledger.js +24 -2
  194. package/dist/core/runner/assemble-result.d.ts +6 -0
  195. package/dist/core/runner/assemble-result.js +1 -1
  196. package/dist/core/runner/auto-strip-notice.d.ts +36 -0
  197. package/dist/core/runner/auto-strip-notice.js +59 -0
  198. package/dist/core/runner/branch-window.d.ts +3 -0
  199. package/dist/core/runner/branch-window.js +37 -0
  200. package/dist/core/runner/caller-roster.d.ts +8 -3
  201. package/dist/core/runner/capability-withheld-seat.js +3 -9
  202. package/dist/core/runner/clock-and-limits.d.ts +22 -1
  203. package/dist/core/runner/clock-and-limits.js +30 -0
  204. package/dist/core/runner/contracts.d.ts +58 -35
  205. package/dist/core/runner/credential-refusal-seat.d.ts +2 -0
  206. package/dist/core/runner/credential-refusal-seat.js +47 -0
  207. package/dist/core/runner/cross-boundary-lane.js +6 -4
  208. package/dist/core/runner/decide-continuation.js +1 -1
  209. package/dist/core/runner/file-history-restore.d.ts +53 -2
  210. package/dist/core/runner/file-history-restore.js +29 -10
  211. package/dist/core/runner/forward-sink.d.ts +14 -1
  212. package/dist/core/runner/forward-sink.js +14 -12
  213. package/dist/core/runner/gate-exit.d.ts +8 -7
  214. package/dist/core/runner/gate-exit.js +13 -13
  215. package/dist/core/runner/git-status-frame.js +2 -4
  216. package/dist/core/runner/initial-run-state.js +1 -1
  217. package/dist/core/runner/main-call-account.d.ts +3 -1
  218. package/dist/core/runner/main-call-account.js +5 -3
  219. package/dist/core/runner/mcp-redial.d.ts +2 -5
  220. package/dist/core/runner/mcp-redial.js +2 -2
  221. package/dist/core/runner/nested-memory-content.d.ts +7 -1
  222. package/dist/core/runner/nested-memory-content.js +73 -13
  223. package/dist/core/runner/nested-memory-lane.d.ts +44 -19
  224. package/dist/core/runner/nested-memory-lane.js +152 -76
  225. package/dist/core/runner/park-commit.js +3 -1
  226. package/dist/core/runner/permission-rule-lanes.d.ts +8 -2
  227. package/dist/core/runner/permission-rule-lanes.js +29 -3
  228. package/dist/core/runner/person-path-rows.d.ts +3 -11
  229. package/dist/core/runner/person-path-rows.js +21 -24
  230. package/dist/core/runner/prepare-acquire-reconcile.js +3 -1
  231. package/dist/core/runner/prepare-artifact.d.ts +1 -1
  232. package/dist/core/runner/prepare-artifact.js +20 -14
  233. package/dist/core/runner/prepare-ask-lane.d.ts +9 -6
  234. package/dist/core/runner/prepare-ask-lane.js +6 -5
  235. package/dist/core/runner/prepare-boundary-parks.d.ts +7 -1
  236. package/dist/core/runner/prepare-boundary-parks.js +27 -24
  237. package/dist/core/runner/prepare-caps-and-workflow.d.ts +5 -2
  238. package/dist/core/runner/prepare-caps-and-workflow.js +4 -3
  239. package/dist/core/runner/prepare-config-doors.d.ts +9 -24
  240. package/dist/core/runner/prepare-config-doors.js +58 -41
  241. package/dist/core/runner/prepare-context-lane.d.ts +2 -2
  242. package/dist/core/runner/prepare-context-lane.js +3 -5
  243. package/dist/core/runner/prepare-defer-classify.d.ts +1 -1
  244. package/dist/core/runner/prepare-defer-classify.js +1 -1
  245. package/dist/core/runner/prepare-delegation-surface.d.ts +2 -2
  246. package/dist/core/runner/prepare-delegation-surface.js +3 -2
  247. package/dist/core/runner/prepare-file-history.d.ts +62 -26
  248. package/dist/core/runner/prepare-file-history.js +117 -46
  249. package/dist/core/runner/prepare-gate-stations.d.ts +4 -0
  250. package/dist/core/runner/prepare-gate-stations.js +6 -5
  251. package/dist/core/runner/prepare-hands-readface.d.ts +9 -4
  252. package/dist/core/runner/prepare-hands-readface.js +8 -4
  253. package/dist/core/runner/prepare-inherited-gate.d.ts +11 -4
  254. package/dist/core/runner/prepare-inherited-gate.js +6 -6
  255. package/dist/core/runner/prepare-listings.d.ts +1 -1
  256. package/dist/core/runner/prepare-listings.js +1 -1
  257. package/dist/core/runner/prepare-memory.js +2 -2
  258. package/dist/core/runner/prepare-offload-wrappers.d.ts +1 -1
  259. package/dist/core/runner/prepare-offload-wrappers.js +1 -1
  260. package/dist/core/runner/prepare-park-ask.d.ts +10 -3
  261. package/dist/core/runner/prepare-park-ask.js +7 -9
  262. package/dist/core/runner/prepare-policy-chain.d.ts +18 -9
  263. package/dist/core/runner/prepare-policy-chain.js +18 -13
  264. package/dist/core/runner/prepare-project-context.d.ts +1 -1
  265. package/dist/core/runner/prepare-project-context.js +5 -3
  266. package/dist/core/runner/prepare-prompt-assembly.js +2 -1
  267. package/dist/core/runner/prepare-prompt-inputs.d.ts +2 -2
  268. package/dist/core/runner/prepare-prompt-inputs.js +1 -1
  269. package/dist/core/runner/prepare-protocol-tools.d.ts +4 -5
  270. package/dist/core/runner/prepare-protocol-tools.js +7 -7
  271. package/dist/core/runner/prepare-question-face.d.ts +4 -2
  272. package/dist/core/runner/prepare-run-refs.d.ts +7 -2
  273. package/dist/core/runner/prepare-run-refs.js +8 -7
  274. package/dist/core/runner/prepare-safety-scan.d.ts +4 -3
  275. package/dist/core/runner/prepare-suspend-saga.d.ts +3 -7
  276. package/dist/core/runner/prepare-suspend-saga.js +4 -3
  277. package/dist/core/runner/prepare-task.js +66 -53
  278. package/dist/core/runner/prepare-tool-disclosure-mount.d.ts +3 -2
  279. package/dist/core/runner/prepare-tool-disclosure-mount.js +2 -1
  280. package/dist/core/runner/prepare-turn-wiring.d.ts +3 -1
  281. package/dist/core/runner/prepare-turn-wiring.js +1 -1
  282. package/dist/core/runner/prepare-wiring-manifest.d.ts +9 -4
  283. package/dist/core/runner/prepare-wiring-manifest.js +14 -6
  284. package/dist/core/runner/prepare-workspace-restore.d.ts +4 -4
  285. package/dist/core/runner/prepare-workspace-restore.js +15 -6
  286. package/dist/core/runner/remote-env-retry.d.ts +3 -3
  287. package/dist/core/runner/restore-seat.d.ts +41 -0
  288. package/dist/core/runner/restore-seat.js +38 -0
  289. package/dist/core/runner/resume-admission.js +1 -1
  290. package/dist/core/runner/resume-apply.js +4 -3
  291. package/dist/core/runner/resume-checkpoint-screen.js +2 -1
  292. package/dist/core/runner/resume-internals-and-config.js +2 -1
  293. package/dist/core/runner/resume-preflight.js +2 -1
  294. package/dist/core/runner/rewind-files.js +22 -6
  295. package/dist/core/runner/rule-store-unreadable-notice.d.ts +8 -0
  296. package/dist/core/runner/rule-store-unreadable-notice.js +11 -0
  297. package/dist/core/runner/run-brain-sinks.d.ts +3 -6
  298. package/dist/core/runner/run-brain-sinks.js +6 -6
  299. package/dist/core/runner/run-compaction-machinery.d.ts +2 -2
  300. package/dist/core/runner/run-git-lane.d.ts +2 -0
  301. package/dist/core/runner/run-git-lane.js +2 -1
  302. package/dist/core/runner/run-harness-handlers.js +5 -4
  303. package/dist/core/runner/run-identity-wiring.js +20 -12
  304. package/dist/core/runner/run-leg.js +31 -72
  305. package/dist/core/runner/run-notification-lane.d.ts +3 -0
  306. package/dist/core/runner/run-notification-lane.js +2 -4
  307. package/dist/core/runner/run-reasoning-seat.d.ts +5 -6
  308. package/dist/core/runner/run-reasoning-seat.js +13 -18
  309. package/dist/core/runner/run-settle-and-teardown.js +13 -9
  310. package/dist/core/runner/run-terminal-adoption.js +4 -8
  311. package/dist/core/runner/run-turn-boundary.js +6 -3
  312. package/dist/core/runner/runtask.d.ts +9 -4
  313. package/dist/core/runner/runtask.js +29 -22
  314. package/dist/core/runner/session-rule-policy.d.ts +11 -1
  315. package/dist/core/runner/shell-env-withheld.js +2 -7
  316. package/dist/core/runner/side-call-account.d.ts +5 -6
  317. package/dist/core/runner/side-call-account.js +2 -2
  318. package/dist/core/runner/stream-lifecycle-verbs.d.ts +3 -0
  319. package/dist/core/runner/stream-lifecycle-verbs.js +5 -3
  320. package/dist/core/runner/stream-settle-backstop.js +4 -6
  321. package/dist/core/runner/stream-steer-verb.d.ts +1 -1
  322. package/dist/core/runner/stream-steer-verb.js +4 -4
  323. package/dist/core/runner/sub-agent-deny-lists.d.ts +8 -3
  324. package/dist/core/runner/sub-agent-deny-lists.js +7 -4
  325. package/dist/core/runner/teardown-bounded.d.ts +7 -0
  326. package/dist/core/runner/teardown-bounded.js +7 -0
  327. package/dist/core/runner/terminal-account.js +41 -13
  328. package/dist/core/runner/terminal-projection.d.ts +1 -5
  329. package/dist/core/runner/tool-end-body.d.ts +9 -3
  330. package/dist/core/runner/tool-end-body.js +6 -3
  331. package/dist/core/runner/tool-output-projection.d.ts +13 -4
  332. package/dist/core/runner/tool-output-projection.js +10 -14
  333. package/dist/core/runner/turn-attachments.d.ts +3 -2
  334. package/dist/core/runner/turn-attachments.js +12 -5
  335. package/dist/core/runner-deps.d.ts +6 -6
  336. package/dist/core/runtime-caps.d.ts +2 -1
  337. package/dist/core/secret-env.d.ts +20 -3
  338. package/dist/core/secret-env.js +13 -15
  339. package/dist/core/session-checkout.d.ts +115 -15
  340. package/dist/core/session-checkout.js +435 -136
  341. package/dist/core/session-policy-store.js +21 -3
  342. package/dist/core/session-reconcile.js +1 -0
  343. package/dist/core/session-store.js +2 -0
  344. package/dist/core/session.d.ts +11 -1
  345. package/dist/core/shell-run-candidates.d.ts +1 -0
  346. package/dist/core/shell-run-candidates.js +1 -1
  347. package/dist/core/shutdown-debug.d.ts +6 -5
  348. package/dist/core/shutdown-debug.js +5 -1
  349. package/dist/core/skill-grant.js +4 -1
  350. package/dist/core/skills-directory.js +5 -3
  351. package/dist/core/spec-contract.d.ts +1 -1
  352. package/dist/core/store-contracts/checkpoint-store-contract.js +2 -7
  353. package/dist/core/store-contracts/file-history-store-contract.js +26 -2
  354. package/dist/core/store-contracts/session-deletion-cascade-contract.js +130 -14
  355. package/dist/core/store-contracts/task-list-store-contract.d.ts +2 -1
  356. package/dist/core/store-contracts/task-list-store-contract.js +28 -1
  357. package/dist/core/task-event.d.ts +48 -27
  358. package/dist/core/task-notification.d.ts +15 -9
  359. package/dist/core/task-notification.js +12 -0
  360. package/dist/core/task-registry-agent.d.ts +24 -22
  361. package/dist/core/task-registry-agent.js +65 -46
  362. package/dist/core/task-registry-shared.d.ts +17 -5
  363. package/dist/core/task-registry.d.ts +17 -6
  364. package/dist/core/task-registry.js +6 -1
  365. package/dist/core/task-result.d.ts +71 -25
  366. package/dist/core/task-spec-members.d.ts +0 -1
  367. package/dist/core/task-spec-members.js +1 -1
  368. package/dist/core/task-spec.d.ts +60 -52
  369. package/dist/core/task-stream.d.ts +45 -12
  370. package/dist/core/terminal-cause.d.ts +45 -8
  371. package/dist/core/terminal-cause.js +5 -0
  372. package/dist/core/tool-card-bound.d.ts +32 -0
  373. package/dist/core/tool-card-bound.js +33 -0
  374. package/dist/core/tool-catalog-entries.d.ts +9 -0
  375. package/dist/core/tool-catalog-entries.js +48 -0
  376. package/dist/core/tool-errors.d.ts +4 -3
  377. package/dist/core/tool-face.d.ts +3 -3
  378. package/dist/core/tool-mount-facts.d.ts +3 -2
  379. package/dist/core/tool-mount-facts.js +1 -1
  380. package/dist/core/tool-mount-static.js +7 -5
  381. package/dist/core/tool-policy.d.ts +21 -19
  382. package/dist/core/tool-policy.js +5 -6
  383. package/dist/core/tool-registry.d.ts +3 -1
  384. package/dist/core/tool-registry.js +15 -1
  385. package/dist/core/tool-result-store.d.ts +9 -3
  386. package/dist/core/tool-result-store.js +14 -1
  387. package/dist/core/tool-roster.d.ts +6 -0
  388. package/dist/core/tool-roster.js +18 -0
  389. package/dist/core/tool-spec.d.ts +17 -8
  390. package/dist/core/trace.d.ts +35 -31
  391. package/dist/core/types.d.ts +2 -2
  392. package/dist/core/untrusted-egress.d.ts +10 -9
  393. package/dist/core/untrusted-egress.js +9 -9
  394. package/dist/core/untrusted-text.d.ts +0 -18
  395. package/dist/core/untrusted-text.js +7 -3
  396. package/dist/core/user-attachment.d.ts +9 -6
  397. package/dist/core/user-attachment.js +12 -10
  398. package/dist/core/user-row-origin.d.ts +44 -25
  399. package/dist/core/user-row-origin.js +30 -20
  400. package/dist/core/wiring-manifest.d.ts +26 -7
  401. package/dist/core/wiring-manifest.js +14 -11
  402. package/dist/core/workspace-snapshot.d.ts +3 -1
  403. package/dist/core/workspace-snapshot.js +1 -0
  404. package/dist/engine/execution-env/node-execution-env.d.ts +23 -16
  405. package/dist/engine/execution-env/node-execution-env.js +127 -67
  406. package/dist/engine/harness/agent-harness.d.ts +4 -5
  407. package/dist/engine/harness/agent-harness.js +2 -7
  408. package/dist/engine/harness/types.d.ts +51 -19
  409. package/dist/engine/harness/types.js +28 -1
  410. package/dist/engine/llm/types.d.ts +26 -14
  411. package/dist/engine/llm/types.js +2 -2
  412. package/dist/engine/loop/agent-loop.d.ts +2 -2
  413. package/dist/engine/loop/agent-loop.js +51 -275
  414. package/dist/engine/loop/types.d.ts +0 -18
  415. package/dist/engine/session/import-validate.d.ts +3 -0
  416. package/dist/engine/session/import-validate.js +34 -2
  417. package/dist/engine/session/repo-utils.d.ts +42 -4
  418. package/dist/engine/session/repo-utils.js +33 -5
  419. package/dist/engine/session/session.d.ts +41 -14
  420. package/dist/engine/session/session.js +96 -25
  421. package/dist/index.d.ts +21 -16
  422. package/dist/index.js +16 -10
  423. package/dist/orchestration/run-spec.d.ts +1 -1
  424. package/dist/orchestration/run-workflow-tool.d.ts +12 -9
  425. package/dist/orchestration/run-workflow-tool.js +15 -19
  426. package/dist/orchestration/workflow-governance.js +13 -21
  427. package/dist/orchestration/workflow-observe.d.ts +4 -3
  428. package/dist/orchestration/workflow-primitives.d.ts +1 -1
  429. package/dist/orchestration/workflow-record-artifact.d.ts +14 -0
  430. package/dist/orchestration/workflow-record-artifact.js +32 -0
  431. package/dist/orchestration/workflow-script-store.d.ts +9 -0
  432. package/dist/orchestration/workflow-script-store.js +20 -1
  433. package/dist/orchestration/workflow-types.d.ts +33 -3
  434. package/dist/orchestration/workflow.d.ts +24 -14
  435. package/dist/orchestration/workflow.js +52 -23
  436. package/dist/prompt-assembly/artifact.js +4 -8
  437. package/dist/prompt-assembly/catalog/engine.d.ts +263 -0
  438. package/dist/prompt-assembly/catalog/engine.js +30 -0
  439. package/dist/prompt-assembly/catalog/index.d.ts +1 -1
  440. package/dist/prompt-assembly/catalog/index.js +2 -2
  441. package/dist/prompt-assembly/catalog/locales/zh-Hans/engine.d.ts +1 -1
  442. package/dist/prompt-assembly/catalog/locales/zh-Hans/engine.js +29 -0
  443. package/dist/prompt-assembly/epoch.js +6 -8
  444. package/dist/prompt-assembly/turn-snapshot.js +8 -9
  445. package/dist/stores/file/background-agent-store.js +5 -6
  446. package/dist/stores/file/checkpoint-store.d.ts +0 -4
  447. package/dist/stores/file/checkpoint-store.js +7 -3
  448. package/dist/stores/file/file-history-store.d.ts +8 -0
  449. package/dist/stores/file/file-history-store.js +72 -0
  450. package/dist/stores/file/fs-atomic.js +17 -12
  451. package/dist/stores/file/index.js +11 -5
  452. package/dist/stores/file/mailbox-store.js +13 -4
  453. package/dist/stores/file/permission-rule-store.js +14 -13
  454. package/dist/stores/file/shared-ledger.d.ts +4 -0
  455. package/dist/stores/file/shared-ledger.js +4 -0
  456. package/dist/stores/file/task-list-store.js +12 -3
  457. package/dist/stores/file/workflow-run-store.js +1 -0
  458. package/dist/tools/fs/bash-program-position.d.ts +4 -2
  459. package/dist/tools/fs/bash-program-position.js +1 -1
  460. package/dist/tools/fs/bash-readonly-classifier.js +1 -1
  461. package/dist/tools/fs/bound-open.d.ts +97 -0
  462. package/dist/tools/fs/bound-open.js +103 -0
  463. package/dist/tools/fs/containment-face.d.ts +2 -2
  464. package/dist/tools/fs/fs-pdf.d.ts +7 -1
  465. package/dist/tools/fs/fs-pdf.js +31 -23
  466. package/dist/tools/fs/fs-read.d.ts +24 -17
  467. package/dist/tools/fs/fs-read.js +84 -53
  468. package/dist/tools/fs/fs-shared.d.ts +14 -12
  469. package/dist/tools/fs/fs-shared.js +5 -4
  470. package/dist/tools/fs/fs-write.d.ts +2 -2
  471. package/dist/tools/fs/fs-write.js +20 -12
  472. package/dist/tools/fs/index.d.ts +4 -4
  473. package/dist/tools/fs/index.js +2 -2
  474. package/dist/tools/fs/notebook.d.ts +1 -1
  475. package/dist/tools/fs/pdf.d.ts +12 -3
  476. package/dist/tools/fs/pdf.js +22 -9
  477. package/dist/tools/fs/read-deny-home.d.ts +3 -2
  478. package/dist/tools/fs/read-deny-home.js +8 -11
  479. package/dist/tools/fs/safety.d.ts +3 -2
  480. package/dist/tools/fs/shell-read-check.js +10 -9
  481. package/dist/tools/monitor.d.ts +6 -5
  482. package/dist/tools/task-list.d.ts +16 -6
  483. package/dist/tools/task-list.js +4 -0
  484. package/dist/tools/web.d.ts +9 -1
  485. package/dist/tools/web.js +8 -3
  486. package/dist/tools/worktree.d.ts +7 -5
  487. package/dist/tools/worktree.js +4 -3
  488. package/package.json +4 -3
  489. package/test/export-surface.snapshot.json +93 -7
  490. package/wire-changes/core-stores-sql@7.68.0.json +39 -0
  491. package/wire-changes/core@7.68.0.json +4257 -0
  492. package/wire-changes/mods-kernel@7.68.0.json +129 -0
  493. package/wire-changes/primitives@7.68.0.json +253 -0
  494. package/wire-changes/wiki-gate@7.68.0.json +39 -0
  495. package/dist/core/runner/credential-origin-seat.d.ts +0 -2
  496. package/dist/core/runner/credential-origin-seat.js +0 -20
@@ -460,16 +460,50 @@ export declare const MCP_IDLE_TIMEOUT_HTTP_DEFAULT_MS: number;
460
460
  /** Resolve the idle-watchdog bound in ms for a transport kind (env `MCP_IDLE_TIMEOUT_STDIO` /
461
461
  * `MCP_IDLE_TIMEOUT_HTTP`, else the CC-matched default). Exported for tests. */
462
462
  export declare function mcpIdleTimeoutMs(kind: "stdio" | "http"): number;
463
+ /** The startup bound in force when neither the declaration nor env `MCP_TIMEOUT` names one: the reference's dial bound (30 s). */
464
+ export declare const MCP_STARTUP_TIMEOUT_DEFAULT_MS = 30000;
463
465
  /**
464
- * Startup-phase (connect + initial listTools) timeout override in ms; undefined keeps the SDK default. Startup
465
- * deliberately stays bounded: a hung server at materialize time should fail open into a skipped-server warning
466
- * quickly, not stall task preparation indefinitely. THE one reader of the knob: with a `server`, that
466
+ * Startup-phase (connect + initial listTools) bound in ms. Startup deliberately stays bounded: a hung server at
467
+ * materialize time should fail open into a skipped-server warning quickly, not stall task preparation
468
+ * indefinitely. THE one reader of the knob, and it answers the bound in force: with a `server`, that
467
469
  * declaration's own `startupTimeoutMs` wins over env `MCP_TIMEOUT` (typed data held to the env knob's range
468
470
  * [{@link MCP_ENV_MS_MIN}, {@link MCP_ENV_MS_MAX}], but REFUSED outside it — `config.mcp_startup_timeout_invalid`
469
- * — where a process string is clamped and announced); without one, the process-level bound alone. The env value
470
- * is resolved either way, so a bad one is announced even when a declaration shadows it.
471
+ * — where a process string is clamped and announced); without one, the process-level bound; with neither,
472
+ * {@link MCP_STARTUP_TIMEOUT_DEFAULT_MS}. The env value is resolved either way, so a bad one is announced even
473
+ * when a declaration shadows it.
471
474
  */
472
- export declare function mcpStartupTimeoutMs(server?: Pick<McpServerSpec, "name" | "startupTimeoutMs">): number | undefined;
475
+ export declare function mcpStartupTimeoutMs(server?: Pick<McpServerSpec, "name" | "startupTimeoutMs">): number;
476
+ /**
477
+ * The machine-readable `details` every MCP request failure thrown to the run loop carries. The loop
478
+ * renders `.message`; the loop's error fold copies `details` onto the tool result, and the `tool_end`
479
+ * frame lifts `code` as `errorCode` and `delivered` as `delivered` — so the words a consumer keys on
480
+ * here are the SAME words the per-server status and the wiring manifest carry ({@link McpFailure}).
481
+ */
482
+ export interface McpFailureDetails {
483
+ /** {@link McpFailure.kind} under the frame's lift key. */
484
+ code: McpFailureKind;
485
+ /** {@link McpFailure.delivered}. */
486
+ delivered: McpDelivered;
487
+ /** The raw caller-config server name (machine-readable side channel, not prompt text). */
488
+ server: string;
489
+ /** For `code === "timeout"`: the bound that elapsed, and WHICH bound — `totalTimeout` = the total
490
+ * wall-clock ceiling (`MCP_TOOL_TIMEOUT_TOTAL`), `idleTimeout` = the idle watchdog (`mcpIdleTimeoutMs`),
491
+ * neither = the SDK's per-call timer. Three knobs, one code; a consumer tuning one reads these bits
492
+ * rather than the message. */
493
+ timeoutMs?: number;
494
+ totalTimeout?: true;
495
+ idleTimeout?: true;
496
+ /** For `code === "protocol"`: the JSON-RPC code when it falls in the protocol-owned range (see
497
+ * {@link describeMcpSpecErrorCode}) — a consumer keying retry/auth policy off the CONDITION reads
498
+ * this instead of matching on the message text. */
499
+ specErrorCode?: number;
500
+ /** {@link McpFailure.httpStatus}: present iff `code === "http_status"`. */
501
+ httpStatus?: number;
502
+ /** Why the principal must authorize ({@link McpFailure.authorization}'s `reason`): present iff `code === "unauthorized"`. The card is copied into the
503
+ * session archive as it stands and no deployment disposition edits an archived byte, so it keeps the reason alone — the seat's address and the
504
+ * endpoint's metadata url are the status record's and the notice's (`McpAuthorization`), where a host reads them live. */
505
+ authorization?: Pick<McpAuthorization, "reason">;
506
+ }
473
507
  /** The protocol-range condition name for a JSON-RPC error code, or `undefined` for every other code
474
508
  * (see {@link MCP_SPEC_ERROR_CODE_NAMES}). */
475
509
  export declare function describeMcpSpecErrorCode(code: unknown): string | undefined;
package/dist/core/mcp.js CHANGED
@@ -18,7 +18,7 @@ import { underStartupBound } from "./mcp-startup-request.js";
18
18
  import { LIST_MCP_RESOURCES, MCP_FACE_WORD_DROP_REASON, MCP_RESOURCE_LIST_ALLOW, MCP_RESOURCE_READ_ALLOW, READ_MCP_RESOURCE, READ_MCP_RESOURCE_DIR, faceAllowed, isMcpFaceWord, retractInstructions, tellInstructions, toldOnDial, unretractInstructions, withdrawInstructionAdds } from "./mounted-mcp.js";
19
19
  import { MCP_CHARS_PER_TOKEN, fetchMcpAnswer, mcpHostReadPorts, mcpMaxOutputTokens, notServed, readMcpListing } from "./mcp-host-read.js";
20
20
  import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
21
- import { describeHttpTransportFailure, failureFields, livenessOf, namingLostSession, readMcpFailure, sessionGone, unauthorizedLine } from "./mcp-failure.js";
21
+ import { authorizationOwed, describeHttpTransportFailure, failureFields, livenessOf, namingLostSession, readMcpFailure, sessionGone, unauthorizedLine, userMustAuthorize } from "./mcp-failure.js";
22
22
  import { DEFAULT_REQUEST_TIMEOUT_MSEC } from "@modelcontextprotocol/client";
23
23
  import { mediaBlockTypeOf } from "./image-admission.js";
24
24
  import { keepBytesWith, mediaTypePhrase } from "./tool-result-bytes.js";
@@ -136,8 +136,9 @@ export function mcpIdleTimeoutMs(kind) {
136
136
  function idleKindOf(kind) {
137
137
  return kind === "stdio" ? "stdio" : "http";
138
138
  }
139
+ export const MCP_STARTUP_TIMEOUT_DEFAULT_MS = 30_000;
139
140
  export function mcpStartupTimeoutMs(server) {
140
- const fromEnv = parseEnvMs("MCP_TIMEOUT");
141
+ const fromEnv = parseEnvMs("MCP_TIMEOUT") ?? MCP_STARTUP_TIMEOUT_DEFAULT_MS;
141
142
  const own = server?.startupTimeoutMs;
142
143
  if (server === undefined || own === undefined)
143
144
  return fromEnv;
@@ -160,7 +161,7 @@ export function describeMcpSpecErrorCode(code) {
160
161
  function sanitizeMcpErrorTextInPlace(err, declared) {
161
162
  if (!(err instanceof Error))
162
163
  return;
163
- const sanitized = remoteWords(err.message, declared);
164
+ const sanitized = remoteFailureText(err, err.message, declared);
164
165
  if (sanitized !== err.message)
165
166
  err.message = sanitized;
166
167
  }
@@ -174,7 +175,11 @@ function namedMcpFailureText(err, declared) {
174
175
  return condition !== undefined ? `${condition} (MCP protocol error ${String(code)}): ${detail}` : detail;
175
176
  }
176
177
  function remoteErrorText(err, declared) {
177
- return remoteWords(thrownText(err), declared);
178
+ return remoteFailureText(err, thrownText(err), declared);
179
+ }
180
+ function remoteFailureText(err, text, declared) {
181
+ const owed = authorizationOwed(err);
182
+ return owed !== undefined ? userMustAuthorize(owed.reason) : remoteWords(text, declared);
178
183
  }
179
184
  function writeEffectWarning(writeEffect) {
180
185
  return writeEffect
@@ -209,7 +214,7 @@ function rethrowHonestMcpError(err, ctx) {
209
214
  const serverLabel = inlineUntrusted(ctx.server);
210
215
  const fenceServerText = (label, raw) => delimitUntrusted(label, truncateMcpErrorText(raw));
211
216
  const failure = observedFailure(err, ctx.site, ctx.liveness, ctx.attempt === undefined);
212
- const details = (extra) => ({ code: failure.kind, delivered: failure.delivered, server: ctx.server, ...(failure.authorization !== undefined ? { authorization: { ...failure.authorization } } : {}), ...extra });
217
+ const details = (extra) => ({ code: failure.kind, delivered: failure.delivered, server: ctx.server, ...(failure.authorization !== undefined ? { authorization: { reason: failure.authorization.reason } } : {}), ...extra });
213
218
  switch (failure.kind) {
214
219
  case "timeout": {
215
220
  const data = readMember(err, "data");
@@ -744,20 +749,41 @@ export async function materializeLegMcpTools(seat, onSubtreeActivity, ...[specs,
744
749
  throw refusal;
745
750
  const carrier = new PeerCarrier(peerSeat, mcpPeerTarget(spec, dialKind), principal, dialKind === "stdio" ? "stdio" : "http", dialKind !== "stdio" && "principalHeader" in spec.transport && spec.transport.principalHeader !== undefined);
746
751
  dialedBy.set(spec.name, carrier);
752
+ const startupMs = mcpStartupTimeoutMs(spec);
753
+ const pool = poolOpts?.pool;
754
+ const key = pool !== undefined ? McpConnectionPool.keyOf(spec, principal, dialKind, startupMs, poolOpts?.isolationScope) : undefined;
755
+ const attempt = pool !== undefined && key !== undefined ? pool.attempt(key, spec.name, { fresh: dialOpts.fresh === true }) : undefined;
756
+ if (attempt?.recalled !== undefined) {
757
+ const { reason } = attempt.recalled;
758
+ if (typeof reason === "object" && reason !== null)
759
+ dialedBy.set(spec.name, carrierOf(reason) ?? carrier);
760
+ recalledOf.add(spec.name);
761
+ throw reason;
762
+ }
747
763
  const through = doorOf(spec, dialKind);
748
764
  const gate = dialGateOf(spec);
749
- const dial = () => gate(() => connectServer(spec, principal, onElicit, binarySeat, mcpDisclosure, through, dialKind, poolOpts?.pool, { ...dialOpts, ...(poolOpts?.isolationScope !== undefined ? { isolationScope: poolOpts.isolationScope } : {}), link: linkOf(spec.name), carrier, announceEcho: (where) => announceEcho(spec.name, where), ...(signal !== undefined ? { signal } : {}), ...(hostSeat !== undefined ? { hostSeat } : {}) }, seat, onSubtreeActivity));
750
- const connected = await dial().catch(async (err) => {
765
+ const dial = () => gate(() => connectServer(spec, principal, onElicit, binarySeat, mcpDisclosure, through, dialKind, poolOpts?.pool, { ...dialOpts, startupMs, ...(key !== undefined ? { key } : {}), link: linkOf(spec.name), carrier, announceEcho: (where) => announceEcho(spec.name, where), ...(signal !== undefined ? { signal } : {}), ...(hostSeat !== undefined ? { hostSeat } : {}) }, seat, onSubtreeActivity));
766
+ const connected = await dial()
767
+ .catch(async (err) => {
751
768
  if (typeof err === "object" && err !== null)
752
769
  dialedBy.set(spec.name, carrierOf(err) ?? carrier);
753
770
  const dialing = (typeof err === "object" && err !== null ? carrierOf(err) : undefined) ?? carrier;
754
771
  if (!(dialing.renewed && answeredUnauthorized(err)) || signal?.aborted === true)
755
772
  throw err;
756
773
  return dial();
774
+ })
775
+ .catch((err) => {
776
+ if (attempt?.settle(attemptKeeps(err, dialKind) ? { failed: err } : "unkept") === true)
777
+ keptOf.add(spec.name);
778
+ throw err;
757
779
  });
780
+ attempt?.settle("connected");
758
781
  dialedBy.set(spec.name, carrierOf(connected.client) ?? carrier);
759
782
  return connected;
760
783
  };
784
+ const attemptKeeps = (err, dialKind) => !disposing && signal?.aborted !== true && readMcpFailure(err, { phase: "connect", transport: dialKind }).failure.kind === "timeout";
785
+ const recalledOf = new Set();
786
+ const keptOf = new Set();
761
787
  const prefixOf = (name) => mintNamespacePrefix(MCP_NAMESPACE, name);
762
788
  const dialedBy = new Map();
763
789
  const echoOf = (spec) => dialedBy.get(spec.name)?.sent ?? [];
@@ -792,7 +818,7 @@ export async function materializeLegMcpTools(seat, onSubtreeActivity, ...[specs,
792
818
  }
793
819
  else {
794
820
  const declared = echoOf(spec);
795
- warnings.push(asServerWarning(spec, r.reason, declared));
821
+ warnings.push(asServerWarning(spec, r.reason, declared, recalledOf.has(spec.name) ? "recalled" : keptOf.has(spec.name) ? "kept" : undefined));
796
822
  statuses.push(failedStatus(spec, r.reason, dialKinds[i], declared));
797
823
  }
798
824
  }
@@ -1515,10 +1541,10 @@ async function connectServer(spec, principal, onElicit, binarySeat, reminderDisc
1515
1541
  const elicitOn = spec.elicitation === true && onElicit !== undefined;
1516
1542
  const health = { dead: false, pendingElicitations: 0, lastElicitationClosedAt: 0 };
1517
1543
  const announce = {};
1518
- const startupMs = mcpStartupTimeoutMs(spec);
1519
- const startupOpts = startupMs !== undefined ? { timeout: startupMs } : undefined;
1544
+ const startupMs = dialOpts.startupMs;
1545
+ const startupOpts = { timeout: startupMs };
1520
1546
  const answersOneLeg = elicitOn || transportKind === "host";
1521
- const poolKey = pool !== undefined && !answersOneLeg ? McpConnectionPool.keyOf(spec, principal, transportKind, startupMs, dialOpts.isolationScope) : undefined;
1547
+ const poolKey = pool !== undefined && !answersOneLeg ? dialOpts.key : undefined;
1522
1548
  const dialClient = async (stop = dialOpts?.signal) => {
1523
1549
  stop?.throwIfAborted();
1524
1550
  const outputSchemaValidator = new AjvJsonSchemaValidator();
@@ -1873,11 +1899,11 @@ function intakeListedTools(listed, spec, link, declared, validator, binarySeat,
1873
1899
  }
1874
1900
  return { serverTools, serverAxes, gates, definitions, dropped, advisories };
1875
1901
  }
1876
- function asServerWarning(spec, err, declared) {
1902
+ function asServerWarning(spec, err, declared, memory) {
1877
1903
  const warning = new Error(`mcp: server "${spec.name}" failed to connect — skipped (${namedMcpFailureText(err, declared)})`, { cause: sanitizedCause(err, declared) });
1878
1904
  warning.code = MCP_SERVER_UNAVAILABLE;
1879
1905
  warning.server = spec.name;
1880
- return warning;
1906
+ return (memory !== undefined ? Object.assign(warning, { memory }) : warning);
1881
1907
  }
1882
1908
  function dialDecision(dialable, spec) {
1883
1909
  if (dialable === undefined)
@@ -33,13 +33,13 @@ export function delegationCallIsExternal(input) {
33
33
  return [];
34
34
  const own = f.servers;
35
35
  const lists = compileToolSelector([{ ...(f.allowTools !== undefined ? { allow: f.allowTools } : {}), deny: f.denyTools ?? [] }]);
36
- const peerLeft = valveLeavesPeer({}, lists);
36
+ const peerLeft = valveLeavesPeer(lists);
37
37
  const sameNamespace = (input.inheritedServers ?? []).filter((p) => own.some((s) => mintNamespacePrefix(MCP_NAMESPACE, s.name) === mintNamespacePrefix(MCP_NAMESPACE, p.name)));
38
38
  const namespaces = [...own, ...sameNamespace].flatMap((s) => {
39
39
  const prefix = mintNamespacePrefix(MCP_NAMESPACE, s.name);
40
40
  return peerLeft(prefix) ? [{ name: prefix, ...(s.contentOrigin !== undefined ? { contentOrigin: s.contentOrigin } : {}) }] : [];
41
41
  });
42
- const readers = MCP_RESOURCE_FACES.filter((name) => valveLeaves({}, lists)({ name })).map((name) => ({ name, contentOrigin: "external" }));
42
+ const readers = MCP_RESOURCE_FACES.filter((name) => valveLeaves(lists)({ name })).map((name) => ({ name, contentOrigin: "external" }));
43
43
  return [...namespaces, ...readers];
44
44
  };
45
45
  const reachesPolluting = (f) => [...selectedFor(f), ...broughtBy(f)].some((t) => input.isPolluting(t));
@@ -1,8 +1,6 @@
1
1
  import { type MemoryControlObjectKind } from "./types.js";
2
- import { type QuarantineCapture } from "./layout.js";
3
- /** Where a File store stages an object's bytes before publishing them under the object's name. Never a kind's
4
- * directory: a listing of a kind answers published names only. */
5
- export declare const CONTROL_OBJECT_STAGE_DIR = ".control-object-stage";
2
+ import { CONTROL_OBJECT_STAGE_DIR, type QuarantineCapture } from "./layout.js";
3
+ export { CONTROL_OBJECT_STAGE_DIR };
6
4
  /** A control-object kind's directory under a File store's control plane. A kind outside
7
5
  * {@link MEMORY_CONTROL_OBJECT_KINDS} is refused (`memory.control_object_unknown`) — never given a directory of its own. */
8
6
  export declare function fileControlObjectDirOf(kind: MemoryControlObjectKind): string;
@@ -2,17 +2,9 @@ import { closeSync, fsyncSync, linkSync, lstatSync, openSync, readFileSync, read
2
2
  import { randomUUID } from "node:crypto";
3
3
  import { join } from "node:path";
4
4
  import { MEMORY_CONTROL_OBJECT_KINDS } from "./types.js";
5
- import { CONTROL_OBJECT_NAME_MAX_BYTES, ControlPlaneCorruptError, IMPORT_RECEIPTS_DIR, LINK_PROBE_PREFIX, QUARANTINE_DIR, SESSION_CAPTURE_OPTOUT_DIR, SESSION_POLLUTION_DIR, controlPlaneLinksRefusal, ensureDirExists, quarantineCaptureName, quarantineObjectNameOf } from "./layout.js";
5
+ import { CONTROL_OBJECT_NAME_MAX_BYTES, CONTROL_OBJECT_STAGE_DIR, ControlPlaneCorruptError, FILE_CONTROL_OBJECT_DIRS, LINK_PROBE_PREFIX, controlPlaneLinksRefusal, ensureDirExists, quarantineCaptureName, quarantineObjectNameOf } from "./layout.js";
6
6
  import { thrownText } from "../thrown-value.js";
7
- const FILE_CONTROL_OBJECT_DIRS = Object.freeze({
8
- pollution: SESSION_POLLUTION_DIR,
9
- "import-receipt": IMPORT_RECEIPTS_DIR,
10
- quarantine: QUARANTINE_DIR,
11
- hold: "hold",
12
- "clearance-custody": "origin-clearance-custody",
13
- capture: SESSION_CAPTURE_OPTOUT_DIR,
14
- });
15
- export const CONTROL_OBJECT_STAGE_DIR = ".control-object-stage";
7
+ export { CONTROL_OBJECT_STAGE_DIR };
16
8
  function unknownObject(what) {
17
9
  const e = new Error(`memory governance store: ${what} (a control object is one of ${MEMORY_CONTROL_OBJECT_KINDS.join(", ")}, named by one opaque segment)`);
18
10
  e.code = "memory.control_object_unknown";
@@ -4,6 +4,7 @@ import { existsSync, linkSync, lstatSync, readFileSync, readdirSync, renameSync,
4
4
  import { dirname, join } from "node:path";
5
5
  import { appendChallengeEvents, claimStaging, fileGovernanceDocOf, isSameFile, lockedStrictUpdate, mintStagingName, readStrictSidecar, stagingNamePattern, v1MemoryPathKeyResolver, lineageContributionsOfSession, markSessionPolluted, readProjectionDebts, readSessionPollution, putControlObjectOnce, quarantineObjectNameOf, ControlPlaneCorruptError } from "./layout.js";
6
6
  import { thrownText } from "../thrown-value.js";
7
+ import { deliverEngineNotice } from "../engine-notice.js";
7
8
  import { processCensus, processFingerprint, uncheckableProcessText } from "../process-identity.js";
8
9
  import { fileControlObjectDirOf, fileControlObjectFaultCode } from "./control-objects.js";
9
10
  function reqStr(v) {
@@ -218,7 +219,11 @@ export async function replayExternalSettlementEffects(docs, input) {
218
219
  catch {
219
220
  continue;
220
221
  }
221
- console.warn(`[sema] delegation settlement: a background delegation of session ${JSON.stringify(sessionId)} settled EXTERNAL after launch — the session is marked and its unmarked committed contributions are challenged`);
222
+ deliverEngineNotice(undefined, {
223
+ code: "delegation.settlement_external",
224
+ message: `[sema] delegation settlement: a background delegation of session ${JSON.stringify(sessionId)} settled EXTERNAL after launch — the session is marked and its unmarked committed contributions are challenged`,
225
+ detail: { sessionId },
226
+ });
222
227
  await docs.updateDoc("settlements", coerceSettlement, (r) => {
223
228
  r.effects[s.row.settleId] = s.terminalEventId;
224
229
  return { next: r, result: undefined };
@@ -135,6 +135,9 @@ export function mergeHarvestReports(a, b) {
135
135
  const qf = [...(a.quarantineFailures ?? []), ...(b.quarantineFailures ?? [])];
136
136
  if (qf.length > 0)
137
137
  merged.quarantineFailures = qf;
138
+ const withheld = [...(a.restoreWithheld ?? []), ...(b.restoreWithheld ?? [])];
139
+ if (withheld.length > 0)
140
+ merged.restoreWithheld = withheld;
138
141
  const rec = a.consolidationRecommended ?? b.consolidationRecommended;
139
142
  if (rec !== undefined)
140
143
  merged.consolidationRecommended = rec;
@@ -1,4 +1,4 @@
1
- import type { EngineNotice } from "../types.js";
1
+ import { type EngineNotice } from "../engine-notice.js";
2
2
  import { type ConsolidationGateRead, type ConsolidationGateRow, type ConsolidationPlanFile, type ConsolidationProposal, type ConsolidationRunStopReason, type ConsolidationWriteGate, type MemoryConsolidationOptions } from "./consolidation.js";
3
3
  import { type SessionAccountRow, type SessionAccountWrite, type EffectiveSettlement, type HoldRow } from "./delegation-settlement.js";
4
4
  import { type SessionWriteHomeReading } from "./session-write-home.js";
@@ -1037,6 +1037,8 @@ export declare class MemoryEngine {
1037
1037
  * file system refused it on permissions ({@link withPermissionRemedy} — the one spelling every
1038
1038
  * write seat surfaces, so no seat renders a permission refusal as a bare errno). */
1039
1039
  private writeFailureText;
1040
+ /** B2 — the backend's read-side containment record into the report: its findings, and the put-backs it withheld beside the engine arms' own. */
1041
+ private drainBackendInbound;
1040
1042
  /**
1041
1043
  * The ONE delivery point for a failed announcement-queue operation (`memory.announce_failed`, ruled
1042
1044
  * 2026-08-03). Every enqueue/drain call site stays fail-OPEN — a broken queue must never fail a
@@ -1082,9 +1084,9 @@ export declare class MemoryEngine {
1082
1084
  * work only: every other notice is awaited by the flow that raised it ({@link announce}), and the
1083
1085
  * queue's own read-modify-write is serialized by the store (`updateDoc`). */
1084
1086
  private announcementWork;
1085
- /** The warnings of a report that are NOT about the write home, each with the scope it is about
1086
- * (`undefined` for a sentence about several scopes or the whole store — the host's). Every other
1087
- * warning of a report is the write scope's. Read once, by the harvest tail's notice filing. */
1087
+ /** The warnings of a report that are NOT about the write home, each with the scope it is about (`undefined` for a sentence about several scopes or the
1088
+ * whole store — the host's; `false` for the harvest's own account of why it admitted nothing — a fact of the session, which its report carries and no
1089
+ * scope's notice queue does: a session that kept nothing leaves nothing in the store). Every other warning is the write scope's. Read once, by the tail. */
1088
1090
  private readonly layerWarningScopes;
1089
1091
  /** The writer legs a mount's read of the writers proved over, per handle, until that session's harvest says them. */
1090
1092
  private readonly mountEndedLegs;
@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
2
2
  import { accessSync, closeSync, constants as fsConstants, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, rmSync, unlinkSync } from "node:fs";
3
3
  import { basename, dirname, join, relative, sep } from "node:path";
4
4
  import { uuidv7 } from "../../internal/harness.js";
5
+ import { deliverEngineNotice } from "../engine-notice.js";
5
6
  import { MAX_MEMORY_BYTES, composeMemoryBlock, firstSentence } from "../memory.js";
6
7
  import { inlineUntrusted } from "../untrusted-text.js";
7
8
  import { describeRejectedValue } from "../tool-search-setting.js";
@@ -9,7 +10,7 @@ import { canonicalJsonStringify } from "../canonical-json.js";
9
10
  import { mintSystemReminder } from "../reminder-mint.js";
10
11
  import { formatMemoryAge } from "./memory-age.js";
11
12
  import { committedShadowFrontmatter, committedShadowOrFault, committedShadowTextOrAbsent } from "./committed-shadow-read.js";
12
- import { committedDistilledOf, committedOriginOf, computeEntryRev, consolidationExposedFrontmatter, distilledEquals, hasDistilledFormExtra, hasOriginFormExtra, isValidEntryId, originEquals, parseEntryFile, serializeEntryFile, stripModelWrittenDistilled, stripModelWrittenOrigin, UNCLOSED_MEMORY_FILE_REASON } from "./frontmatter.js";
13
+ import { committedDistilledOf, committedOriginOf, computeEntryRev, consolidationExposedFrontmatter, distilledEquals, hasDistilledFormExtra, hasOriginFormExtra, isValidEntryId, originEquals, parseEntryFile, revOfText, serializeEntryFile, stripModelWrittenDistilled, stripModelWrittenOrigin, UNCLOSED_MEMORY_FILE_REASON } from "./frontmatter.js";
13
14
  import { MEMORY_PROVENANCE_RECALL_SENTENCE, memoryExposureIndexRow, parseMemoryExposureIndexRow } from "./provenance-wording.js";
14
15
  import { isInstructionEntry } from "./header-hints.js";
15
16
  import { ConsolidationRefusedError, CONSOLIDATION_WRITE_REFUSED_CODE, CONSOLIDATION_FORCE_THROTTLE_FLOOR_MS, CONSOLIDATION_SEAT_FREEZE_GRACE_MS, consolidationTypeEligible, deriveProductSlug, deriveSupersededSet, fileGovernanceStore, governanceCaptureRecordStore, fileGovernanceStoreDir, governanceStoreIsFileOver, standingControlObjectsOf, isValidConsolidationPlanId, productAddPatch, recordActiveSetBaseline, recordConsolidationSession, sessionsSinceExcludingCurrent, scanRefusalCeiling, screenConsolidationOptions, memoryGovernanceDurability, supersessionFuseCeiling, deletionFuseCeiling, MEMORY_CHALLENGED_ENTRY_GUIDANCE, } from "./consolidation.js";
@@ -24,7 +25,7 @@ import { clearanceCustodyErased, eraseOriginClearanceCustody, markOriginClearanc
24
25
  import { carriesEntry, standsAsLink } from "./entry-scan.js";
25
26
  import { DEFAULT_MAX_ENTRY_DEPTH, MEMORY_INDEX_FILENAME, captureErasureInput, erasureRequestInvalid, erasureScopeRefusal, erasureSelectHash, erasureStatusOf, sweepUnderErasureRecord, scanEntryFiles, } from "./file-backend.js";
26
27
  import { assembleMemoryExportBundle, canonicalExpectedScopes, computeMemoryBundleHash, expectedScopesInvalid, firstOutsideExpectedScopes, memoryBundleInvalid, } from "./export-bundle.js";
27
- import { SCAN_FUSE_THRESHOLD, captureIntoQuarantine, clearContainedPath, eraseQuarantineCopies, keepCopiesBeforeOverwrite, quarantineObjectNameOf, restoreContainedBaseline, mintStagingName, indexLineIsStale, readIndexRevs, writeIndexRevs, bumpScanFuse, scanFuseKey, canonicalize, anchorStoreRoot, landingPathOf, landsOutsideStore, storeActRefusal, storeRootMovedRefusal, adoptRootScopeLayout, clearScanFuse, effectiveControlRootOf, sayAnnounceFailure, drainMemoryAnnouncements, enqueueMemoryAnnouncement, ensureDirExists, markSessionPolluted, readSessionPollution, recordRetrievedAccount, writeFileNoFollow, writeFileNoReplace, withPermissionRemedy, permissionRemedyOf, readRetrievedAccount, registerScope, registeredScopes, scopeDirFor, appendChallengeEvents, appendLineageAudit, rebuildStrictControlPlaneLedger, isStrictControlPlaneLedgerCorrupt, ControlPlaneCorruptError, CHALLENGE_LEDGER_MAX_EVENTS, adjudicateLineagePending, challengedEntryIds, clearLineageForEntries, discardLineagePending, lineageAccountOfEntry, lineageContributionsOfSession, lineageLatchedIds, promoteLineagePending, readChallengeEvents, readChallengedHistory, readLineageRecord, recordChallengedHistory, recordLineageCredential, reconcileLineage, readProjectionDebts, resolveChallengeEvent, settleProjectionDebts, stageLineagePending, stageProjectionDebts, controlPlaneStraysRefusal, } from "./layout.js";
28
+ import { SCAN_FUSE_THRESHOLD, captureIntoQuarantine, clearContainedPath, eraseQuarantineCopies, keepCopiesBeforeOverwrite, quarantineObjectNameOf, restoreContainedBaseline, mintStagingName, indexLineIsStale, readIndexRevs, writeIndexRevs, bumpScanFuse, scanFuseKey, canonicalize, anchorStoreRoot, landingPathOf, landsOutsideStore, storeActRefusal, storeRootReanchoredRefusal, adoptRootScopeLayout, clearScanFuse, effectiveControlRootOf, sayAnnounceFailure, drainMemoryAnnouncements, enqueueMemoryAnnouncement, ensureDirExists, markSessionPolluted, readSessionPollution, recordRetrievedAccount, writeFileNoFollow, writeFileNoReplace, withPermissionRemedy, permissionRemedyOf, readRetrievedAccount, registerScope, registeredScopes, scopeDirFor, appendChallengeEvents, appendLineageAudit, rebuildStrictControlPlaneLedger, isStrictControlPlaneLedgerCorrupt, ControlPlaneCorruptError, CHALLENGE_LEDGER_MAX_EVENTS, adjudicateLineagePending, challengedEntryIds, clearLineageForEntries, discardLineagePending, lineageAccountOfEntry, lineageContributionsOfSession, lineageLatchedIds, promoteLineagePending, readChallengeEvents, readChallengedHistory, readLineageRecord, recordChallengedHistory, recordLineageCredential, reconcileLineage, readProjectionDebts, resolveChallengeEvent, settleProjectionDebts, stageLineagePending, stageProjectionDebts, controlPlaneStraysRefusal, } from "./layout.js";
28
29
  import { createSessionIncarnationSeat, recalledForAnyIdentity, recalledForIdentity, rememberForIdentity } from "./session-incarnation.js";
29
30
  import { scanMemoryFileName, scanMemoryWrite, scanRemediation } from "./scan.js";
30
31
  import { writableRootOf } from "./types.js";
@@ -111,12 +112,12 @@ const MEMORY_ENGINE_OPTION_KEYS = optionKeys()({ backend: 0, memoryDir: 0, contr
111
112
  export function memorySessionPollutedNotice(input) {
112
113
  const reason = inlineUntrusted(input.reason, 200);
113
114
  const message = input.provenance === "carry"
114
- ? `Memory for this session is marked externally exposed: ${reason}. Ordinary memory entries it writes are ` +
115
- `still committed to the long-term library, each carrying an engine-minted external-origin marker (the ` +
116
- `content scan gates run unchanged); instruction-form files (type: feedback, or pinned/triggers/applies-when ` +
117
- `header lines) are withheld and quarantined for host review, and this session's index prose additions are ` +
118
- `not retained. Contributions this session already committed are challenged (a sweep that cannot run ` +
119
- `announces memory.challenge_sweep_failed). What a given harvest actually withheld is announced as ` +
115
+ ? `Memory for this session now counts as exposed to outside content (${reason}). Nothing is needed from you. ` +
116
+ `Ordinary memories this session saves are still kept, each with an engine-written external-origin marker (the ` +
117
+ `content checks run as before); memories that would act as standing instructions (type: feedback, or pinned, ` +
118
+ `triggers or applies-when header lines) are held for the host to review instead of being saved, and this session's ` +
119
+ `additions to the memory index are not kept. What this session saved before now is checked again (if that check ` +
120
+ `cannot run, memory.challenge_sweep_failed says so). Each harvest that holds something back says so as ` +
120
121
  `memory.harvest_quarantined.`
121
122
  : `Memory for this session is marked polluted: ${reason}. Its memory writes are no longer eligible for the ` +
122
123
  `long-term library — a harvest withholds what it collects (quarantined for host review, judged against the ` +
@@ -857,6 +858,15 @@ export class MemoryEngine {
857
858
  writeFailureText(err) {
858
859
  return thrownText(withPermissionRemedy(err, this.memoryDir));
859
860
  }
861
+ drainBackendInbound(report) {
862
+ const backend = this.backend;
863
+ const findings = backend.drainInboundFindings?.();
864
+ if (findings !== undefined && findings.length > 0)
865
+ report.inboundFindings = findings;
866
+ const withheld = backend.drainInboundRestoreWithheld?.();
867
+ if (withheld !== undefined && withheld.length > 0)
868
+ (report.restoreWithheld ??= []).push(...withheld);
869
+ }
860
870
  discloseAnnounceFailure(stage, cause) {
861
871
  sayAnnounceFailure(this.onIncident, stage, cause);
862
872
  }
@@ -878,7 +888,7 @@ export class MemoryEngine {
878
888
  const text = `memory notice (${stage}) names no single scope, so it was kept off every session's memory notices: ${items.join(" | ")}`;
879
889
  const sink = this.onIncident;
880
890
  if (sink === undefined) {
881
- console.warn(`[sema] ${text}`);
891
+ deliverEngineNotice(undefined, { code: "memory.notice_unscoped", message: `[sema] ${text}`, detail: { stage } });
882
892
  return;
883
893
  }
884
894
  try {
@@ -2408,9 +2418,7 @@ export class MemoryEngine {
2408
2418
  catch (err) {
2409
2419
  report.warnings.push(`restricted-session divergence audit failed: ${thrownText(err)}`);
2410
2420
  }
2411
- const roFindings = this.backend.drainInboundFindings?.();
2412
- if (roFindings !== undefined && roFindings.length > 0)
2413
- report.inboundFindings = roFindings;
2421
+ this.drainBackendInbound(report);
2414
2422
  if ((captureOptOut !== undefined || opts?.admitNothing?.cause === "capture_optout_inherited") && writeScope !== null) {
2415
2423
  try {
2416
2424
  const sweep = await this.sweepSessionCaptureResidue(handle);
@@ -2427,12 +2435,12 @@ export class MemoryEngine {
2427
2435
  }
2428
2436
  this.concludeObservations(observed, report);
2429
2437
  if (opts?.admitNothing !== undefined)
2430
- report.warnings.push(opts.admitNothing.reason);
2438
+ this.warnScoped(report, false, opts.admitNothing.reason);
2431
2439
  else if (captureOptOut !== undefined) {
2432
- report.warnings.push(`harvest admitted nothing: this session declared memory capture opt-out (memory.capture: "off") — nothing it produced enters the long-term library`);
2440
+ this.warnScoped(report, false, `harvest admitted nothing: this session declared memory capture opt-out (memory.capture: "off") — nothing it produced enters the long-term library`);
2433
2441
  }
2434
2442
  else if (captureRead.fault) {
2435
- report.warnings.push(`harvest admitted nothing: the capture opt-out record store is unreadable (outage), so this session's opt-out state is INDETERMINATE — commits are suppressed fail-closed until the store answers (a recorded session must not run captured because its record could not be read)`);
2443
+ this.warnScoped(report, false, `harvest admitted nothing: the capture opt-out record store is unreadable (outage), so this session's opt-out state is INDETERMINATE — commits are suppressed fail-closed until the store answers (a recorded session must not run captured because its record could not be read)`);
2436
2444
  }
2437
2445
  return report;
2438
2446
  }
@@ -3235,12 +3243,10 @@ export class MemoryEngine {
3235
3243
  try {
3236
3244
  const preCommitRead = lineageSessionId !== undefined ? await this.sessionCaptureOptOutOrFault(lineageSessionId) : { fault: false, record: undefined };
3237
3245
  if (preCommitRead.record !== undefined || preCommitRead.fault) {
3238
- report.warnings.push(preCommitRead.record !== undefined
3246
+ this.warnScoped(report, false, preCommitRead.record !== undefined
3239
3247
  ? `harvest admitted nothing: a memory capture opt-out record landed for this session while the harvest was collecting — the assembled batch was discarded before commit`
3240
3248
  : `harvest admitted nothing: the capture opt-out record store became unreadable while the harvest was collecting — the assembled batch was discarded fail-closed (an indeterminate opt-out state must not commit)`);
3241
- const preFindings = this.backend.drainInboundFindings?.();
3242
- if (preFindings !== undefined && preFindings.length > 0)
3243
- report.inboundFindings = preFindings;
3249
+ this.drainBackendInbound(report);
3244
3250
  return report;
3245
3251
  }
3246
3252
  let preCommit = lineageSessionId !== undefined ? await this.sessionPollution(lineageSessionId) : undefined;
@@ -3651,9 +3657,7 @@ export class MemoryEngine {
3651
3657
  for (const a of patchReport.applied)
3652
3658
  report.patches[a.op]++;
3653
3659
  report.conflicts = patchReport.conflicts;
3654
- const drained = this.backend.drainInboundFindings?.();
3655
- if (drained !== undefined && drained.length > 0)
3656
- report.inboundFindings = drained;
3660
+ this.drainBackendInbound(report);
3657
3661
  if (pollutedReason !== undefined) {
3658
3662
  if (await restorePollutedIndex())
3659
3663
  signalContainment((c) => (c.indexRolledBack = true));
@@ -5842,7 +5846,7 @@ export class MemoryEngine {
5842
5846
  assertRootAnchored(handle) {
5843
5847
  const root = anchorStoreRoot(this.memoryDir, this.controlDir, { onIncident: this.onIncident, now: this.now });
5844
5848
  if (handle !== undefined && handle.memoryDir !== root)
5845
- throw storeRootMovedRefusal(this.memoryDir, { controlDir: this.controlDir, recorded: root, now: handle.memoryDir });
5849
+ throw storeRootReanchoredRefusal(this.memoryDir, { controlDir: this.controlDir, recorded: root, now: handle.memoryDir });
5846
5850
  return root;
5847
5851
  }
5848
5852
  writeIfChanged(target, text, handle) {
@@ -5981,8 +5985,11 @@ function gateAnnouncementItems(report, owner) {
5981
5985
  for (const x of report.quarantineFailures ?? []) {
5982
5986
  put(owner.ofRel(x.path), `quarantine escalation ${quoteId(x.path)} (${x.contained ? "contained" : "NOT contained"}): ${inlineUntrusted(x.detail, 200)}`);
5983
5987
  }
5984
- for (const w of report.warnings)
5985
- put(owner.ofWarning(w), `index note: ${inlineUntrusted(w, 200)}`);
5988
+ for (const w of report.warnings) {
5989
+ const scope = owner.ofWarning(w);
5990
+ if (scope !== false)
5991
+ put(scope, `index note: ${inlineUntrusted(w, 200)}`);
5992
+ }
5986
5993
  for (const [scope, items] of out)
5987
5994
  out.set(scope, capItems(items));
5988
5995
  return out;
@@ -6021,10 +6028,6 @@ function indexLineTarget(line) {
6021
6028
  function countIndexLines(text) {
6022
6029
  return text.split("\n").filter((l) => indexLineTarget(l) !== undefined || parseMemoryExposureIndexRow(l) !== undefined).length;
6023
6030
  }
6024
- function revOfText(text, id) {
6025
- const parsed = parseEntryFile(text);
6026
- return computeEntryRev({ id, frontmatter: parsed.frontmatter, body: parsed.body });
6027
- }
6028
6031
  function planeDigest(text) {
6029
6032
  return createHash("sha256").update(text, "utf8").digest("hex");
6030
6033
  }
@@ -113,7 +113,12 @@ export interface MemoryErasureAttestation {
113
113
  * selected ids: another entry that restates an erased one is counted on `residuals.derivedEntries`
114
114
  * and does not decide it. Everything else is `"partial"`; a replay converges the classes the lane
115
115
  * can clear, and says when it cannot (`unverified`, or `evidenceBinding.remaining` — rows the
116
- * append-only chain keeps). */
116
+ * append-only chain keeps).
117
+ * What `"complete"` covers, said plainly: the selected entries are gone from this store and every copy the carrier table
118
+ * counts is cleared with them — the clearance log's held text of an erased entry included (`clearanceCustody`: the log's
119
+ * rows stay for audit with their text erased; read back, such a row says `custodyErased: true`, and an empty `entryText`
120
+ * there is the erasure, not an entry that never had text). The attestation is a structured record by contract and carries
121
+ * no sentence; a surface that tells a person "erased" reads this member and the carrier table. */
117
122
  status: "complete" | "partial";
118
123
  /** `"journal"` = the backend holds an append-only evidence chain, whatever its medium; `"none"` = the
119
124
  * explicit `allowUnevidenced` degradation lane (always present — a silent downgrade is the forbidden shape). */
@@ -506,6 +511,9 @@ export declare class FileMemoryEngineBackend implements MemoryBackend {
506
511
  /** B2 — inbound-gate findings accumulated by read-side syncs; the engine drains them into
507
512
  * `HarvestReport.inboundFindings` at harvest. */
508
513
  private inboundFindings;
514
+ /** The committed copies an inbound containment did NOT put back (another writer held the path); the engine
515
+ * drains them into `HarvestReport.restoreWithheld` beside the findings. */
516
+ private inboundRestoreWithheld;
509
517
  /** Batch-planning scan memo (applyPatchesLocked only): planning reads pre-batch disk exclusively,
510
518
  * so one `readScope(scope, false)` per scope serves every patch of the batch. Set for the planning
511
519
  * loop, cleared before EXECUTE mutates the disk. Never caches `sync:true` reads. */
@@ -529,6 +537,12 @@ export declare class FileMemoryEngineBackend implements MemoryBackend {
529
537
  checkControlPlane(): void;
530
538
  /** B2 — drain the accumulated inbound-gate findings (engine harvest reporting). */
531
539
  drainInboundFindings(): HarvestRejection[];
540
+ /** Drain the inbound containments' withheld put-backs (engine harvest reporting, beside the findings). */
541
+ drainInboundRestoreWithheld(): Array<{
542
+ path: string;
543
+ entryId: string;
544
+ rev: string;
545
+ }>;
532
546
  /** B1 — read an entry's COMMITTED content copy from the control-plane shadow (undefined = none).
533
547
  * The engine's missing-file recovery reads this (zero-copy: a deleted file is gone from the
534
548
  * directory scan, so the shadow is the only committed copy left). It answers only for an id the
@@ -787,11 +801,12 @@ export declare class FileMemoryEngineBackend implements MemoryBackend {
787
801
  private sweepStagedFiles;
788
802
  private scopeDir;
789
803
  /** B2/C-F9 — contain one inbound-gate REJECT, shared by the adopting read (`readScope` sync) and
790
- * the adoption-restricted committed view (`readScopeCommitted`) so the two doors can never drift:
804
+ * the boundary committed views (`readScopeCommitted`) so the doors can never drift:
791
805
  * report the finding, capture the SCANNED bytes into control-plane quarantine (never a path
792
- * re-read — TOCTOU), restore the committed shadow over the suspect where one exists (the write
793
- * lands by `rename`, which REPLACES a link at the final component instead of traversing it —
794
- * pinned by test), and escalate any deviation as a report-visible `quarantine_failed`. Returns
806
+ * re-read — TOCTOU), take them off the plane, put the committed shadow back where one exists
807
+ * ({@link restoreContainedBaseline}, the restore every containment arm shares: bytes another
808
+ * writer landed after the read stay, and are judged on their own next read), and escalate any
809
+ * deviation as a report-visible `quarantine_failed`. Returns
795
810
  * the shadow text that now backs the entry (undefined ⇔ never committed / shadow-less legacy —
796
811
  * each caller decides what leaving the set means on its channel). */
797
812
  private containInboundReject;