@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
@@ -657,51 +657,58 @@ async function confirmEditedCandidate(rec, edit, deps) {
657
657
  }
658
658
  return { ok: true, mintedCandidate: { index, rule: checked.canonicalRule, ticket: mintRuleTicket(rec.id, index) } };
659
659
  }
660
+ function refusal(code, reason, committed = "no") {
661
+ return { status: "refused", code, committed, reason };
662
+ }
660
663
  export async function redeemRuleTicket(opts) {
664
+ const res = await redeemTicketLeg(opts);
665
+ return res.status === "refused" ? { status: "refused", reason: res.reason } : res;
666
+ }
667
+ async function redeemTicketLeg(opts) {
661
668
  const caller = resolveCallerOwner(opts.principal, opts.owner, "redeemRuleTicket");
662
669
  const parsed = parseRuleTicket(opts.ticket);
663
670
  if (parsed === undefined)
664
- return { status: "refused", reason: "malformed ticket" };
671
+ return refusal("ticket_invalid", "malformed ticket");
665
672
  const rec = await opts.deps.approvals.get(parsed.recordId);
666
673
  if (rec === undefined)
667
- return { status: "refused", reason: "no such approval record" };
674
+ return refusal("record_missing", "no such approval record");
668
675
  const recOwner = ownerOfRecord(rec);
669
676
  if (recOwner === undefined || !sameRuleOwner(recOwner, caller))
670
- return { status: "refused", reason: "the ticket belongs to a different principal" };
677
+ return refusal("wrong_principal", "the ticket belongs to a different principal");
671
678
  if (isStale(rec))
672
- return { status: "refused", reason: `record_schema_stale: ${STALE_RECORD_MESSAGE}` };
679
+ return refusal("record_schema_stale", `record_schema_stale: ${STALE_RECORD_MESSAGE}`);
673
680
  if (rec.state === "pending")
674
- return { status: "refused", reason: "the approval record has not been confirmed" };
681
+ return refusal("not_confirmed", "the approval record has not been confirmed");
675
682
  const damage = approvalRecordDamageOf(rec);
676
683
  if (damage !== undefined)
677
- return { status: "refused", reason: `the approval record is malformed: ${damage}` };
684
+ return refusal("record_malformed", `the approval record is malformed: ${damage}`);
678
685
  const candidate = rec.candidates[parsed.index];
679
686
  if (candidate === undefined)
680
- return { status: "refused", reason: "the ticket names no candidate on this record" };
687
+ return refusal("ticket_invalid", "the ticket names no candidate on this record");
681
688
  const chosen = rec.selectedOffer;
682
689
  const chosenOffer = chosen !== undefined && Number.isInteger(chosen) ? rec.offers[chosen] : undefined;
683
690
  if (chosenOffer === undefined) {
684
- return { status: "refused", reason: "the approval record is malformed: it is settled but names no valid chosen offer" };
691
+ return refusal("record_malformed", "the approval record is malformed: it is settled but names no valid chosen offer");
685
692
  }
686
693
  if (!offerMembersOf(chosenOffer).includes(parsed.index)) {
687
- return { status: "refused", reason: "the ticket names an option the person did not choose" };
694
+ return refusal("not_chosen", "the ticket names an option the person did not choose");
688
695
  }
689
696
  const siblingsOf = candidate.behavior === "allow" ? { rec, offer: chosenOffer, index: parsed.index } : undefined;
690
697
  const parsedRule = parseRuleText(candidate.rule, candidate.behavior);
691
698
  if ("reject" in parsedRule)
692
- return { status: "refused", reason: `${parsedRule.reject.code}: ${parsedRule.reject.message}` };
699
+ return refusal("parse_rejected", `${parsedRule.reject.code}: ${parsedRule.reject.message}`);
693
700
  if (rec.kind === "import" && !importCarries(candidate.scope, parsedRule.rule))
694
- return { status: "refused", reason: LAYER_ROOT_RECORD_REASON };
701
+ return refusal("unsupported.layer_root", LAYER_ROOT_RECORD_REASON);
695
702
  let store;
696
703
  try {
697
704
  store = storeForOwner(opts.deps.provider, caller);
698
705
  }
699
706
  catch (err) {
700
- return { status: "refused", reason: errText(err) };
707
+ return refusal("store_unavailable", errText(err));
701
708
  }
702
709
  const writer = writerOf(store);
703
710
  if (writer === undefined)
704
- return { status: "refused", reason: "the resolved permission-rule store has no write face" };
711
+ return refusal("store_unavailable", "the resolved permission-rule store has no write face");
705
712
  const known = rec.redeemedDots?.[parsed.index];
706
713
  const dot = known ?? (await writer.nextDot());
707
714
  if (known === undefined) {
@@ -716,7 +723,7 @@ export async function redeemRuleTicket(opts) {
716
723
  const again = await opts.deps.approvals.get(rec.id);
717
724
  const theirs = again === undefined || isStale(again) ? undefined : again.redeemedDots?.[parsed.index];
718
725
  if (theirs === undefined)
719
- return { status: "refused", reason: "the approval record changed state concurrently" };
726
+ return refusal("record_changed", "the approval record changed state concurrently");
720
727
  return await applyRedemption({ deps: opts.deps, owner: caller, candidate, parsedRule: parsedRule.rule, dot: theirs, recordId: rec.id, kind: rec.kind, replay: true, ...(siblingsOf !== undefined ? { siblingsOf } : {}) });
721
728
  }
722
729
  }
@@ -745,11 +752,11 @@ async function applyRedemption(args) {
745
752
  store = storeForOwner(args.deps.provider, args.owner);
746
753
  }
747
754
  catch (err) {
748
- return { status: "refused", reason: errText(err) };
755
+ return refusal("store_unavailable", errText(err));
749
756
  }
750
757
  const writer = writerOf(store);
751
758
  if (writer === undefined)
752
- return { status: "refused", reason: "the resolved permission-rule store has no write face" };
759
+ return refusal("store_unavailable", "the resolved permission-rule store has no write face");
753
760
  const origin = originOfRecordKind(args.kind);
754
761
  const siblings = args.siblingsOf;
755
762
  const landing = await landRuleAdd({
@@ -778,7 +785,7 @@ async function applyRedemption(args) {
778
785
  : {}),
779
786
  });
780
787
  if (!landing.landed)
781
- return { status: "refused", reason: landing.reason };
788
+ return refusal(landing.code, landing.reason, landing.committed);
782
789
  return { status: "redeemed", behavior: args.parsedRule.behavior, rule: args.parsedRule.rule, scope: args.candidate.scope, dot: args.dot, rev: landing.rev, alreadyRedeemed: args.replay };
783
790
  }
784
791
  function originOfRecordKind(kind) {
@@ -976,7 +983,7 @@ export async function redeemRuleBatch(opts) {
976
983
  const candidate = rec.candidates[candidateIndex];
977
984
  const row = { candidateIndex, behavior: candidate.behavior, rule: candidate.rule, scope: candidate.scope };
978
985
  if (candidate.behavior === "allow" && tighteningFailed !== undefined) {
979
- members.push({ ...row, status: "refused", reason: `withheld: candidate ${tighteningFailed} (a deny/ask member of this batch) did not land, and an allow must not stand wider than the list that was confirmed — redeem the batch again once the store accepts the tightening member` });
986
+ members.push({ ...row, status: "refused", code: "withheld", committed: "no", reason: `withheld: candidate ${tighteningFailed} (a deny/ask member of this batch) did not land, and an allow must not stand wider than the list that was confirmed — redeem the batch again once the store accepts the tightening member` });
980
987
  continue;
981
988
  }
982
989
  let alreadyThere = false;
@@ -987,34 +994,40 @@ export async function redeemRuleBatch(opts) {
987
994
  alreadyThere = snap.rules.some((r) => r.behavior === candidate.behavior && r.rule === candidate.rule && sameScope(r.scope, candidate.scope));
988
995
  }
989
996
  catch (err) {
990
- members.push({ ...row, status: "refused", reason: `could not read the permission-rule store: ${errText(err)}` });
997
+ members.push({ ...row, status: "refused", code: "store_read", committed: "no", reason: `could not read the permission-rule store: ${errText(err)}` });
991
998
  if (candidate.behavior !== "allow")
992
999
  tighteningFailed ??= candidateIndex;
993
1000
  continue;
994
1001
  }
995
1002
  }
996
- const res = await redeemRuleTicket({
1003
+ const res = await redeemTicketLeg({
997
1004
  ticket: mintRuleTicket(rec.id, candidateIndex),
998
1005
  ...(caller.kind === "principal" ? { principal: caller.principal } : { owner: caller }),
999
1006
  deps: opts.deps,
1000
1007
  });
1001
1008
  if (res.status === "refused") {
1002
- members.push({ ...row, status: "refused", reason: res.reason });
1009
+ members.push({ ...row, status: "refused", code: res.code, committed: res.committed, reason: res.reason });
1003
1010
  if (candidate.behavior !== "allow")
1004
1011
  tighteningFailed ??= candidateIndex;
1005
1012
  continue;
1006
1013
  }
1007
1014
  if (candidate.behavior !== "allow") {
1008
1015
  let live = false;
1016
+ let unreadable;
1009
1017
  try {
1010
1018
  const snap = await effectiveOrThrow(store, candidate.scope.kind === "session" ? { sessionId: candidate.scope.sessionId } : undefined);
1011
1019
  live = snap.rules.some((r) => r.behavior === candidate.behavior && r.rule === candidate.rule && sameScope(r.scope, candidate.scope) && r.adds.some((a) => a.dot.actor === res.dot.actor && a.dot.counter === res.dot.counter));
1012
1020
  }
1013
- catch {
1014
- live = false;
1021
+ catch (err) {
1022
+ unreadable = errText(err);
1023
+ }
1024
+ if (unreadable !== undefined) {
1025
+ members.push({ ...row, status: "refused", code: "store_read", committed: "unknown", reason: `could not read the permission-rule store to confirm this ${candidate.behavior} member stands after its redemption: ${unreadable}` });
1026
+ tighteningFailed ??= candidateIndex;
1027
+ continue;
1015
1028
  }
1016
1029
  if (!live) {
1017
- members.push({ ...row, status: "refused", reason: `this ${candidate.behavior} member's redeemed dot ${res.dot.actor}#${res.dot.counter} is not live in the store (removed since it was redeemed) — a removed rule is not re-landed by replaying its record; a new consent is required` });
1030
+ members.push({ ...row, status: "refused", code: "dot_removed", committed: "no", reason: `this ${candidate.behavior} member's redeemed dot ${res.dot.actor}#${res.dot.counter} is not live in the store (removed since it was redeemed) — a removed rule is not re-landed by replaying its record; a new consent is required` });
1018
1031
  tighteningFailed ??= candidateIndex;
1019
1032
  continue;
1020
1033
  }
@@ -608,6 +608,37 @@ export type RemovalLiveness = (typeof REMOVAL_LIVENESS_WORDS)[number];
608
608
  */
609
609
  export declare const RULE_WRITE_COMMITTED_WORDS: readonly ["no", "unknown"];
610
610
  export type RuleWriteCommitted = (typeof RULE_WRITE_COMMITTED_WORDS)[number];
611
+ /**
612
+ * WHY a redemption was refused — the cause, spelled once and read by every refused row: the single-ticket leg, the
613
+ * member table of a batch walk, and the landing under both. A refusal carries a `reason` for a person AND one of these
614
+ * words, so a consumer that has to branch on the cause reads a word and never the start of a sentence. One word per
615
+ * CAUSE, every place that refuses names one, and there is deliberately no catch-all: a refusal nobody classified is a
616
+ * compile error at the place that mints it, never an `other`.
617
+ *
618
+ * It rides beside {@link RuleWriteCommitted}, and the two answer different questions. The code says what stopped the
619
+ * redemption; `committed` says what may be claimed about the bytes. The same code can carry both words (`store_read`:
620
+ * a read before any write says `no`, a read-back after one that could not be taken says `unknown`).
621
+ *
622
+ * - `unsupported.layer_root` — an import record's global rule written from `/`, which no stored row can hold
623
+ * - `ticket_invalid` — the ticket does not name a candidate (unparseable, or an index the record has none at)
624
+ * - `record_missing` — no approval record is stored under the ticket's id
625
+ * - `wrong_principal` — the record belongs to another owner than the caller
626
+ * - `record_schema_stale` — the record predates the current form, so the decision it carried is not read
627
+ * - `not_confirmed` — the record is still pending; nobody has said yes
628
+ * - `record_malformed` — the record fails the structural precondition, or is settled but names no chosen offer
629
+ * - `not_chosen` — the candidate is outside the offer the person chose
630
+ * - `parse_rejected` — the candidate's rule text no longer passes the one validator
631
+ * - `store_unavailable` — the owner's store cannot be resolved, or has no write face
632
+ * - `record_changed` — the record moved under this redemption and the dot it needed is not there
633
+ * - `withheld` — held back because the batch's deny/ask members do not all stand, and an allow may not stand wider
634
+ * - `store_read` — a permission-rule store read failed (before the write: `no`; the read-back after it: `unknown`)
635
+ * - `store_write` — the write threw, answered unreadably, or was reported landed with no trace of its dot (`unknown`)
636
+ * - `session_ended` — a session-scope rule whose session has ended; a late redemption cannot revive it
637
+ * - `occ` — every optimistic-concurrency attempt lost its compare-and-set
638
+ * - `dot_removed` — the member's redeemed dot is no longer live in the store (the rule was removed since)
639
+ */
640
+ export declare const RULE_REFUSAL_CODES: readonly ["unsupported.layer_root", "ticket_invalid", "record_missing", "wrong_principal", "record_schema_stale", "not_confirmed", "record_malformed", "not_chosen", "parse_rejected", "store_unavailable", "record_changed", "withheld", "store_read", "store_write", "session_ended", "occ", "dot_removed"];
641
+ export type RuleRefusalCode = (typeof RULE_REFUSAL_CODES)[number];
611
642
  /**
612
643
  * The result of a removal.
613
644
  *
@@ -686,11 +717,14 @@ export type RuleAddLanding = {
686
717
  /** `committed` is what the caller may CLAIM afterwards. `"no"` means the store itself answered — a
687
718
  * read that failed before any write, a refused preflight, an epoch seal, or a compare-and-set that
688
719
  * lost every attempt: each of those is the store saying nothing landed. `"unknown"` means the apply
689
- * THREW, which proves nothing either way: a backend can commit and then lose its acknowledgement. */
720
+ * THREW, which proves nothing either way: a backend can commit and then lose its acknowledgement.
721
+ * `code` is the cause ({@link RuleRefusalCode}); this path mints five of them (`withheld`, `store_read`,
722
+ * `store_write`, `session_ended`, `occ`), so a door never reads the cause out of `reason`. */
690
723
  | {
691
724
  landed: false;
692
725
  reason: string;
693
726
  committed: RuleWriteCommitted;
727
+ code: RuleRefusalCode;
694
728
  };
695
729
  /**
696
730
  * Land ONE add — the terminal write both doors take (the consent protocol's redemption and the
@@ -467,6 +467,25 @@ export async function ruleStoreChecksum(payload) {
467
467
  }
468
468
  export const REMOVAL_LIVENESS_WORDS = Object.freeze(["yes", "no", "unknown"]);
469
469
  export const RULE_WRITE_COMMITTED_WORDS = Object.freeze(["no", "unknown"]);
470
+ export const RULE_REFUSAL_CODES = Object.freeze([
471
+ "unsupported.layer_root",
472
+ "ticket_invalid",
473
+ "record_missing",
474
+ "wrong_principal",
475
+ "record_schema_stale",
476
+ "not_confirmed",
477
+ "record_malformed",
478
+ "not_chosen",
479
+ "parse_rejected",
480
+ "store_unavailable",
481
+ "record_changed",
482
+ "withheld",
483
+ "store_read",
484
+ "store_write",
485
+ "session_ended",
486
+ "occ",
487
+ "dot_removed",
488
+ ]);
470
489
  function resolveRuleWriter(store) {
471
490
  let w;
472
491
  try {
@@ -641,35 +660,35 @@ export async function landRuleAdd(args) {
641
660
  rev = snapshot.rev;
642
661
  const refusal = await args.preflight?.(snapshot);
643
662
  if (refusal !== undefined)
644
- return { landed: false, reason: refusal, committed: "no" };
663
+ return { landed: false, reason: refusal, committed: "no", code: "withheld" };
645
664
  }
646
665
  catch (err) {
647
- return { landed: false, reason: `could not read the permission-rule store: ${errText(err)}`, committed: "no" };
666
+ return { landed: false, reason: `could not read the permission-rule store: ${errText(err)}`, committed: "no", code: "store_read" };
648
667
  }
649
668
  let res;
650
669
  try {
651
670
  res = await args.writer.apply(args.delta, { expectedRev: rev });
652
671
  }
653
672
  catch (err) {
654
- return { landed: false, reason: `the permission-rule store refused the write: ${errText(err)}`, committed: "unknown" };
673
+ return { landed: false, reason: `the permission-rule store refused the write: ${errText(err)}`, committed: "unknown", code: "store_write" };
655
674
  }
656
675
  const reading = readRuleWriteOutcome(res);
657
676
  if (reading.kind === "refused")
658
- return { landed: false, reason: SESSION_ENDED_REFUSAL, committed: "no" };
677
+ return { landed: false, reason: SESSION_ENDED_REFUSAL, committed: "no", code: "session_ended" };
659
678
  if (reading.kind === "unreadable")
660
- return { landed: false, reason: `the permission-rule store answered the write unreadably: ${reading.why}`, committed: "unknown" };
679
+ return { landed: false, reason: `the permission-rule store answered the write unreadably: ${reading.why}`, committed: "unknown", code: "store_write" };
661
680
  if (reading.kind === "landed") {
662
681
  const witness = await witnessRuleAdd(args.store, args.writer, args.delta);
663
682
  if ("unreadable" in witness) {
664
- return { landed: false, reason: `the permission-rule store reported a landing at revision ${String(reading.rev)}, and the read-back that would have witnessed it could not be taken (${witness.unreadable})`, committed: "unknown" };
683
+ return { landed: false, reason: `the permission-rule store reported a landing at revision ${String(reading.rev)}, and the read-back that would have witnessed it could not be taken (${witness.unreadable})`, committed: "unknown", code: "store_read" };
665
684
  }
666
685
  if (!witness.seen) {
667
- return { landed: false, reason: `the permission-rule store reported a landing at revision ${String(reading.rev)}, and a read-back of this add's own dot finds no trace of it — a revision says the ANSWER was well formed, not that a row exists, so nothing here can say the write landed`, committed: "unknown" };
686
+ return { landed: false, reason: `the permission-rule store reported a landing at revision ${String(reading.rev)}, and a read-back of this add's own dot finds no trace of it — a revision says the ANSWER was well formed, not that a row exists, so nothing here can say the write landed`, committed: "unknown", code: "store_write" };
668
687
  }
669
688
  return { landed: true, rev: reading.rev };
670
689
  }
671
690
  }
672
- return { landed: false, reason: `optimistic-concurrency retries exhausted after ${RULE_ADD_MAX_ATTEMPTS} attempts`, committed: "no" };
691
+ return { landed: false, reason: `optimistic-concurrency retries exhausted after ${RULE_ADD_MAX_ATTEMPTS} attempts`, committed: "no", code: "occ" };
673
692
  }
674
693
  export async function addPersistedRule(opts) {
675
694
  const behavior = opts.behavior;
@@ -3,6 +3,7 @@ import { lexedWordOf, readShellCommand } from "./shell-run-candidates.js";
3
3
  import { unlistedReaderSentence } from "../tools/fs/bash-readonly-classifier.js";
4
4
  import { descriptorsOfPlan, newLineDescriptors, standardDeviceUnrebound } from "../tools/fs/shell-read-device.js";
5
5
  import { planShellReads } from "../tools/fs/shell-read-plan.js";
6
+ import { programKeyOf } from "../tools/fs/program-read-model.js";
6
7
  import { writesOnlyStandardDevices } from "../tools/fs/shell-read-write-targets.js";
7
8
  import { FIND_ACTION_PRIMARIES, FIND_NEWER_PRIMARY, FIND_VALUE_PRIMARIES, FLAG_VALUE_ACCEPTS, READ_ONLY_BARE_ONLY, READ_ONLY_BARE_PROGRAMS, READ_ONLY_COMMAND_TABLE, READ_ONLY_ENV_NAMES, READ_ONLY_EXACT_FORMS, READ_ONLY_GLOB_PROGRAMS, XARGS_READ_ONLY_TARGETS, dockerRetargetDanger, } from "./read-only-shell-table.js";
8
9
  const NOT = (reason) => ({ readOnly: false, reason });
@@ -182,7 +183,7 @@ function segmentVerdict(seg, line, bindings, readers) {
182
183
  return unlisted;
183
184
  if (run.some((w) => expansionKind(w) === "glob"))
184
185
  return GLOB_PROGRAMS.has(program) ? READ_ONLY : NOT(`\`${program}\` with a glob argument — the glob may name anything`);
185
- if (DEVICE_WRITERS.has(program) && writesOnlyStandardDevices(program, words.slice(1), bindings()))
186
+ if (DEVICE_WRITERS.has(programKeyOf(program)) && writesOnlyStandardDevices(program, words.slice(1), bindings()))
186
187
  return READ_ONLY;
187
188
  const structural = structuralReading(words);
188
189
  if (structural !== null)
@@ -192,7 +193,7 @@ function segmentVerdict(seg, line, bindings, readers) {
192
193
  export function lineDescriptorsOfText(command) {
193
194
  return descriptorsOfPlan(planShellReads(command, { readers: new Set(), cwd: "/", roots: [] }));
194
195
  }
195
- const DEVICE_WRITERS = new Set(["tee", "cp"]);
196
+ const DEVICE_WRITERS = new Set(["tee", "cp", "dd"]);
196
197
  function structuralReading(words) {
197
198
  const program = words[0];
198
199
  if (BARE_ONLY.has(program))
@@ -1,4 +1,4 @@
1
- import { isPlainRecord, safeDataValue } from "./checkpoint-store.js";
1
+ import { isPlainRecord, safeDataValue } from "./checkpoint-features.js";
2
2
  import { validatePath } from "./effective-path-target.js";
3
3
  export { READ_ROOT_CANDIDATE_DIR_MAX } from "./effective-path-target.js";
4
4
  export function normalizeReadRootCandidate(value) {
@@ -1,3 +1,4 @@
1
+ import type { SecretNotation } from "@sema-agent/primitives";
1
2
  /** The marks, by what they stand for. `whole` is the bare mark (a span removed whole — a credential value, a floor, a
2
3
  * depth cut); the others name the shape that was withheld: `credentials` a URL's userinfo, `url` a whole URL, `path` an
3
4
  * absolute filesystem path. A mark the engine writes is exactly one of these four. Frozen: the table is exported to hosts, and every
@@ -10,6 +11,13 @@ export declare const REDACTION_MARKS: Readonly<{
10
11
  }>;
11
12
  /** The bare mark — what a host compares against to tell that the engine withheld a value. */
12
13
  export declare const REDACTION_MARK: "[redacted]";
14
+ /** The engine's notation for the credential renderer (`renderSecrets`): a credential value is the bare mark, a URL userinfo
15
+ * the credentials mark, and a text no reading can afford is the bare mark whole. Built from the table, so it follows it. */
16
+ export declare const REDACTION_NOTATION: SecretNotation;
17
+ /** The spelling a request-route rendering writes for a withheld query value or URL user (`«redacted»`) — shown to a person
18
+ * in a refusal or a route display, never written by a redaction pass. It is not a member of {@link REDACTION_MARKS}: the
19
+ * marks the readers below recognize are that table's four, and this spelling is not one of them. */
20
+ export declare const WITHHELD_VALUE_MARK = "\u00ABredacted\u00BB";
13
21
  /** Where the marks sit in `s`, one [start, end) span at a time, leftmost first. Lazy: a reader that stops early (a display cut stops
14
22
  * at its bound) pays for the marks it looked at, not for every mark an input of a million of them holds. */
15
23
  export declare function eachRedactionMarkerSpan(s: string): Generator<[number, number], void, undefined>;
@@ -5,6 +5,12 @@ export const REDACTION_MARKS = Object.freeze({
5
5
  path: "[redacted-path]",
6
6
  });
7
7
  export const REDACTION_MARK = REDACTION_MARKS.whole;
8
+ export const REDACTION_NOTATION = Object.freeze({
9
+ value: REDACTION_MARKS.whole,
10
+ byKind: Object.freeze({ "url-credentials": REDACTION_MARKS.credentials }),
11
+ overStrip: REDACTION_MARKS.whole,
12
+ });
13
+ export const WITHHELD_VALUE_MARK = "«redacted»";
8
14
  const escapeLiteral = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
9
15
  const REDACTION_MARKER_RE = new RegExp(Object.values(REDACTION_MARKS).map(escapeLiteral).join("|"), "g");
10
16
  export function* eachRedactionMarkerSpan(s) {
@@ -512,7 +512,11 @@ export interface ExecutionEnvFactoryContext {
512
512
  * main session's cwd. A single-user/TOC factory SHOULD root the child env here (unless `isolation`
513
513
  * requests a worktree — that wins); a multi-tenant/TOB factory minting isolated containers may ignore
514
514
  * it. Absent on top-level tasks. Static shared-`executionEnv` deployments need nothing — the child
515
- * already shares the parent env (and its cwd).
515
+ * already shares the parent env (and its cwd). When the parent works in a managed tree (a session's own
516
+ * tree), the child MUST be rooted at this hint or inside that tree: an env the factory roots elsewhere on
517
+ * the host — the base checkout the tree isolates, another tree — is refused before the child's first turn
518
+ * (`workspace.isolation_unavailable`, `factory_ignored_hint`); a declared sandbox off the host's disk
519
+ * (`hostLocalPaths: false` with `isolation: true`) is another namespace and is not judged.
516
520
  */
517
521
  parentCwd?: string;
518
522
  /**
@@ -746,6 +750,13 @@ export declare function declaredHostLocalPaths(env: Pick<ExecutionEnv, "capabili
746
750
  * engine never presents a path it cannot vouch for as a host path. Total: it never throws.
747
751
  */
748
752
  export declare function pathsAreHostLocal(env: Pick<ExecutionEnv, "capabilities">): boolean;
753
+ /**
754
+ * Is this environment a DECLARED sandbox off the host's disk — its paths another namespace's (`hostLocalPaths: false`) and its
755
+ * containment its own job (`isolation: true`)? The one reading that exempts an environment from comparing its paths with the
756
+ * caller's: the worktree request's guard and a delegated child's caller-tree floor both take it. Only the two declarations
757
+ * together earn it; an undeclared or non-isolated environment off the host's disk (an SSH host, a device) does not. Total.
758
+ */
759
+ export declare function isDeclaredSandboxOffHost(env: Pick<ExecutionEnv, "capabilities">): boolean;
749
760
  /**
750
761
  * Does content this environment produces come from outside the deployment's trust boundary
751
762
  * ({@link ExecutionEnvCapabilities.externalContentTarget})? Three states: `true`, `false`, or `"undeclared"` (absent, not a
@@ -188,6 +188,9 @@ export function declaredHostLocalPaths(env) {
188
188
  export function pathsAreHostLocal(env) {
189
189
  return declaredHostLocalPaths(env) === true;
190
190
  }
191
+ export function isDeclaredSandboxOffHost(env) {
192
+ return declaredHostLocalPaths(env) === false && isIsolated(env);
193
+ }
191
194
  export function targetIsExternal(env) {
192
195
  return declaredCapability(env, "externalContentTarget") ?? UNDECLARED_CAPABILITY_READING.externalContentTarget.reads;
193
196
  }
@@ -9,10 +9,11 @@
9
9
  * · `environment` — the leg's infrastructure failed (the workspace restore, an abort): the decision is
10
10
  * untouched, and a retry replays it;
11
11
  * · `session_gone` — the resumed agent's transcript session is missing;
12
- * · `transcript_corrupt` — the resumed agent's transcript session is THERE but cannot be read as a session: its log
13
- * has no header its store wrote (`corrupt_session`), or its entry tree is structurally unusable — a leaf or parent
14
- * entry that is not in the log (`invalid_session`). Distinct from `session_gone`: the bytes exist, so deleting or
15
- * restoring the transcript is the remedy, not re-creating a session;
12
+ * · `transcript_corrupt` — the resumed agent's transcript session is THERE but cannot be read as a session
13
+ * (`corrupt_session`): its log has no header its store wrote, or its entry tree does not hold together — a leaf,
14
+ * a parent or the entry its checkpoint was cut at that is not in the log, a parent chain that loops. A store outside
15
+ * this package that answers the same fact `invalid_session` reads the same way. Distinct from `session_gone`: the
16
+ * bytes exist, so deleting or restoring the transcript is the remedy, not re-creating a session;
16
17
  * · `tool_unavailable` — the approved tool is not available to the resumed leg (gone, replaced by a
17
18
  * different contract, or an inherited tool the drive cannot hand over): this approval cannot run, and a
18
19
  * fresh decision resolves it;
@@ -21,19 +21,45 @@ export declare function deploymentCanRerootChild(deps: Pick<RunnerDeps, "executi
21
21
  * ONE judgment every reader of that fact takes
22
22
  * (the delegation tool's worktree request, and the anchors of the rules the child inherits):
23
23
  * · `honored` — the environment's root is where the child was asked to be (canonical on both sides);
24
- * · `caller_tree` — it is not, and it lies inside the caller's own tree (`callerRoot`): the same filesystem, the wrong
24
+ * · `caller_tree` — it is not, and it lies inside the caller's own tree (`callerRoot`, or the checkout the caller has switched
25
+ * to — `callerCheckout`, which can lie outside the root): the same filesystem, the wrong
25
26
  * directory — a worktree request then fails (the child would write the caller's checkout);
26
27
  * · `elsewhere` — neither: another filesystem namespace (a sandbox the factory minted). The child runs there, it is not
27
28
  * in the worktree it was offered, and it takes the caller's path rules again at its own anchors.
28
29
  * A path the environment cannot canonicalize is compared as spelled. Residual: two namespaces that hold the same path
29
30
  * string, with a factory claiming to honor it, read `honored`.
30
31
  */
31
- export declare function childPlacementOf(env: Pick<ExecutionEnv, "canonicalPath">, childRoot: string, asked: string | undefined, callerRoot: string): Promise<ChildPlacement>;
32
+ export declare function childPlacementOf(env: Pick<ExecutionEnv, "canonicalPath">, childRoot: string, asked: string | undefined, callerRoot: string, callerCheckout?: string): Promise<ChildPlacement>;
33
+ /** `p` as the environment resolves it, or as spelled when it cannot (the placement judgments' one spelling reading). */
34
+ export declare function canonicalOrSelf(env: Pick<ExecutionEnv, "canonicalPath">, p: string): Promise<string>;
35
+ /**
36
+ * The managed tree a delegated child was placed outside of — `undefined` when nothing binds it there. A caller whose root lies
37
+ * in a managed tree (a session's own tree, or a worktree the caller itself was started in) works in that tree; a child its
38
+ * environment did not place where it was asked (`placement` other than `honored`) must still start inside it (at or below the
39
+ * tree's root, canonical), or it would read and write the checkout the tree isolates. The caller's tree is read on the canonical
40
+ * spelling of its root (a symlink alias or a `.` segment names the same tree). Asked only on a placed leg (one a delegation
41
+ * caller placed; any other has no placement). Not bound: a child placed where asked, a caller outside every managed tree, and an
42
+ * environment that is a declared sandbox off the host's disk ({@link isDeclaredSandboxOffHost} — another namespace, the same
43
+ * reading the worktree request's guard exempts by).
44
+ */
45
+ export declare function callerTreeMissed(env: ExecutionEnv, placement: ChildPlacement, callerRoot: string, childRoot: string): Promise<string | undefined>;
46
+ /** The refusal of a child placed outside the managed tree its caller works in ({@link callerTreeMissed}); `envCwd` is named too
47
+ * when the child's root is not its environment's own directory. */
48
+ export declare function factoryIgnoredHint(childRoot: string, envCwd: string, tree: string): Error & {
49
+ code: "workspace.isolation_unavailable";
50
+ };
51
+ /**
52
+ * The placement seats a delegation caller hands its child (`RunInternals.callerRoot` / `callerCheckout`), read from where the
53
+ * caller works (`parentCwd`) and its task root (`callerRoot`) — the ONE reading every spawn lane takes (the delegation tool and
54
+ * both workflow lanes). A caller that names only where it works is its own root; the checkout seat is filled only when the caller
55
+ * has switched to a tree other than its root (it can lie outside that root). Neither named ⇒ no seats: no placement is judged.
56
+ */
57
+ export declare function callerPlacementSeats(parentCwd: string | undefined, callerRoot: string | undefined): Pick<RunInternals, "callerRoot" | "callerCheckout">;
32
58
  /** A delegated leg's placement: the place asked for is the hint (a minted worktree, an explicit cwd, the caller's own cwd)
33
59
  * — or, for a worktree the factory mints itself (`isolation`), that worktree on the caller's host when the environment's
34
60
  * paths are the host's (`pathsAreHostLocal`; any other environment's is another namespace). A leg no delegation caller
35
61
  * placed (no `callerRoot`) has no placement and reads nothing. */
36
- export declare function childPlacementOnLeg(env: ExecutionEnv, internals: Pick<RunInternals, "isolation" | "parentCwd"> & {
62
+ export declare function childPlacementOnLeg(env: ExecutionEnv, internals: Pick<RunInternals, "isolation" | "parentCwd" | "callerCheckout"> & {
37
63
  readonly callerRoot: string;
38
64
  }, root: string): Promise<ChildPlacement>;
39
65
  /** The refusal of a worktree the caller minted for a child its environment placed in the caller's own tree. */
@@ -1,30 +1,53 @@
1
- import { pathsAreHostLocal } from "../remote-env.js";
1
+ import { isDeclaredSandboxOffHost, pathsAreHostLocal } from "../remote-env.js";
2
+ import { managedTreeAt } from "../git-worktree-env.js";
2
3
  import { validatePath } from "../effective-path-target.js";
3
4
  import { installPolicyAnchors, installationAnchorsOf, installedFrom } from "../path-rule-binding.js";
4
5
  import { CheckpointError } from "../checkpoint-store.js";
5
6
  export function deploymentCanRerootChild(deps) {
6
7
  return deps.executionEnvFactory !== undefined;
7
8
  }
8
- export async function childPlacementOf(env, childRoot, asked, callerRoot) {
9
- const canon = async (p) => {
10
- try {
11
- const r = await env.canonicalPath(p);
12
- return r.ok ? r.value : p;
13
- }
14
- catch {
15
- return p;
16
- }
17
- };
18
- const root = await canon(childRoot);
19
- if (asked !== undefined && (await canon(asked)) === root)
9
+ export async function childPlacementOf(env, childRoot, asked, callerRoot, callerCheckout) {
10
+ const root = await canonicalOrSelf(env, childRoot);
11
+ if (asked !== undefined && (await canonicalOrSelf(env, asked)) === root)
20
12
  return "honored";
21
- const tree = await canon(callerRoot);
13
+ return (await atOrBelow(env, root, callerRoot)) || (callerCheckout !== undefined && (await atOrBelow(env, root, callerCheckout))) ? "caller_tree" : "elsewhere";
14
+ }
15
+ export async function canonicalOrSelf(env, p) {
16
+ try {
17
+ const r = await env.canonicalPath(p);
18
+ return r.ok ? r.value : p;
19
+ }
20
+ catch {
21
+ return p;
22
+ }
23
+ }
24
+ async function atOrBelow(env, root, dir) {
25
+ const tree = await canonicalOrSelf(env, dir);
22
26
  const sep = tree.includes("\\") && !tree.includes("/") ? "\\" : "/";
23
- return root === tree || root.startsWith(tree.endsWith(sep) ? tree : tree + sep) ? "caller_tree" : "elsewhere";
27
+ return root === tree || root.startsWith(tree.endsWith(sep) ? tree : tree + sep);
28
+ }
29
+ export async function callerTreeMissed(env, placement, callerRoot, childRoot) {
30
+ if (placement === "honored")
31
+ return undefined;
32
+ const tree = managedTreeAt(await canonicalOrSelf(env, callerRoot))?.root;
33
+ if (tree === undefined || isDeclaredSandboxOffHost(env))
34
+ return undefined;
35
+ return (await atOrBelow(env, await canonicalOrSelf(env, childRoot), tree)) ? undefined : tree;
36
+ }
37
+ export function factoryIgnoredHint(childRoot, envCwd, tree) {
38
+ const where = envCwd === childRoot ? childRoot : `${childRoot} (its environment stands at ${envCwd})`;
39
+ return Object.assign(new Error(`The sub-agent was not started (factory_ignored_hint): the execution environment factory placed the child at ${where} while the session's tree is ${tree}, where its caller works — a child outside that tree would read and write the checkout it isolates. The factory must root the child at the parentCwd it is handed; the child is never started outside the tree instead.`), { code: "workspace.isolation_unavailable" });
40
+ }
41
+ export function callerPlacementSeats(parentCwd, callerRoot) {
42
+ const root = callerRoot ?? parentCwd;
43
+ return {
44
+ ...(root !== undefined ? { callerRoot: root } : {}),
45
+ ...(parentCwd !== undefined && callerRoot !== undefined && parentCwd !== callerRoot ? { callerCheckout: parentCwd } : {}),
46
+ };
24
47
  }
25
48
  export function childPlacementOnLeg(env, internals, root) {
26
49
  const asked = internals.isolation === "worktree" ? (pathsAreHostLocal(env) ? root : undefined) : internals.parentCwd;
27
- return childPlacementOf(env, root, asked, internals.callerRoot);
50
+ return childPlacementOf(env, root, asked, internals.callerRoot, internals.callerCheckout);
28
51
  }
29
52
  export function worktreeNotHonored(cwd) {
30
53
  return Object.assign(new Error(`isolation "worktree" was requested but cannot be honored: the execution environment factory placed the sub-agent at "${cwd}", inside the caller's own tree, instead of the worktree it was offered. The sub-agent was not started (fail-closed — no silent fallback to the shared working tree).`), { code: "isolation.unavailable" });
@@ -1,7 +1,7 @@
1
1
  import { convertToLlm, uuidv7 } from "../../internal/harness.js";
2
2
  import { compactionFailureReason, compactionPassReport, DEFAULT_COMPACTION_INSTRUCTIONS, isCompactionManualCancel, manualCompactOutcomeOf, maybeCompact, mintCompactedEvent } from "../auto-compaction.js";
3
3
  import { contextOverlayFor } from "../context-settings.js";
4
- import { createRowSeat } from "../mods/session-append.js";
4
+ import { createRowSeat, promptCountOf } from "../mods/session-append.js";
5
5
  import { createCompactStation } from "../mods/session-compact.js";
6
6
  import { admitLegMods, legFacadeSeats } from "../mods/stations.js";
7
7
  import { malformedPricingField } from "../pricing.js";
@@ -73,7 +73,7 @@ async function compactOnSession(req, deps, session, resolved, named, legMods) {
73
73
  const compactionModel = compactionSummaryIsDerived(req.compactionModel !== undefined, named) ? await compactionSummaryFallback({ derived: named, primary: resolved.model, brain: deps.brain, getApiKeyAndHeaders: req.getApiKeyAndHeaders, onNotice: deps.onNotice, sessionId }) : named;
74
74
  const branch = await session.getBranch();
75
75
  const contextMessages = convertToLlm((await session.buildContext()).messages);
76
- bindSessionFacade(legMods, { deps, req, model: resolved.model, messages: contextMessages, book });
76
+ bindSessionFacade(legMods, { deps, req, model: resolved.model, messages: contextMessages, book, turns: async () => promptCountOf(await session.getBranch()) });
77
77
  const rowSeat = createRowSeat();
78
78
  rowSeat.bind({ bus: legMods.bus, identity: undefined, report: legMods.report });
79
79
  const compactStation = createCompactStation();
@@ -142,6 +142,9 @@ function bindSessionFacade(legMods, input) {
142
142
  taskRoot: "",
143
143
  cwdRef: undefined,
144
144
  lastBrainContext: () => ({ messages: input.messages }),
145
+ agentSessions: undefined,
146
+ turns: input.turns,
147
+ measure: {},
145
148
  activeTools: new Set(),
146
149
  agentListing: undefined,
147
150
  book: (answeredBy, reply) => input.book("mod", answeredBy, reply),