@sema-agent/core 7.63.0 → 7.64.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 (204) hide show
  1. package/CHANGELOG.md +408 -0
  2. package/dist/agents/cc-peer-directory.js +1 -0
  3. package/dist/agents/cc-peer-wire.d.ts +4 -0
  4. package/dist/agents/cc-peer-wire.js +1 -0
  5. package/dist/agents/cc-uds-peer-channel.js +5 -0
  6. package/dist/agents/cross-session-judge.d.ts +3 -1
  7. package/dist/agents/cross-session-judge.js +4 -1
  8. package/dist/agents/peer-directory.d.ts +8 -0
  9. package/dist/agents/peer-directory.js +4 -0
  10. package/dist/agents/peer-held-queue.d.ts +9 -3
  11. package/dist/agents/peer-held-queue.js +12 -9
  12. package/dist/agents/peer-idle.d.ts +20 -1
  13. package/dist/agents/peer-idle.js +23 -12
  14. package/dist/agents/peer-notice-route.d.ts +16 -5
  15. package/dist/agents/peer-notice-route.js +11 -9
  16. package/dist/agents/peer-notices.d.ts +25 -8
  17. package/dist/agents/peer-notices.js +6 -1
  18. package/dist/agents/peer-session-drain.d.ts +32 -6
  19. package/dist/agents/peer-session-drain.js +100 -26
  20. package/dist/agents/send-message-tool.d.ts +7 -0
  21. package/dist/agents/send-message-tool.js +18 -6
  22. package/dist/agents/subagent.js +20 -3
  23. package/dist/core/allow-entry.d.ts +4 -0
  24. package/dist/core/ask-origin.d.ts +1 -1
  25. package/dist/core/ask-origin.js +2 -2
  26. package/dist/core/ask-unresolvable-notice.d.ts +13 -4
  27. package/dist/core/ask-unresolvable-notice.js +10 -3
  28. package/dist/core/auto-compaction.d.ts +7 -5
  29. package/dist/core/background-agent-store.d.ts +7 -0
  30. package/dist/core/background-agent-store.js +3 -0
  31. package/dist/core/checkpoint-queries.d.ts +9 -6
  32. package/dist/core/checkpoint-queries.js +8 -3
  33. package/dist/core/checkpoint-store.d.ts +5 -1
  34. package/dist/core/context-settings.d.ts +40 -9
  35. package/dist/core/context-settings.js +32 -10
  36. package/dist/core/engine-attestation.d.ts +26 -6
  37. package/dist/core/engine-attestation.js +5 -1
  38. package/dist/core/engine-notice.d.ts +24 -1
  39. package/dist/core/extension-requester.d.ts +9 -0
  40. package/dist/core/extension-requester.js +7 -0
  41. package/dist/core/file-history-store.d.ts +28 -0
  42. package/dist/core/file-history-store.js +48 -5
  43. package/dist/core/fs-write-gate-policy.js +1 -1
  44. package/dist/core/gate-fold.js +2 -0
  45. package/dist/core/gate-lanes.js +2 -0
  46. package/dist/core/gate-outcome.d.ts +39 -2
  47. package/dist/core/gate-outcome.js +20 -1
  48. package/dist/core/governance-codes.d.ts +3 -1
  49. package/dist/core/governance-codes.js +4 -0
  50. package/dist/core/leg-identity.d.ts +19 -1
  51. package/dist/core/leg-identity.js +12 -0
  52. package/dist/core/mailbox-store.d.ts +39 -4
  53. package/dist/core/mailbox-store.js +14 -2
  54. package/dist/core/memory-engine/consolidation.d.ts +3 -2
  55. package/dist/core/memory-engine/consolidation.js +16 -0
  56. package/dist/core/memory-engine/control-objects.d.ts +25 -0
  57. package/dist/core/memory-engine/control-objects.js +151 -0
  58. package/dist/core/memory-engine/control-plane-adoption.d.ts +48 -0
  59. package/dist/core/memory-engine/control-plane-adoption.js +159 -0
  60. package/dist/core/memory-engine/delegation-settlement.d.ts +21 -5
  61. package/dist/core/memory-engine/delegation-settlement.js +217 -26
  62. package/dist/core/memory-engine/dual-root.js +2 -2
  63. package/dist/core/memory-engine/engine.d.ts +38 -23
  64. package/dist/core/memory-engine/engine.js +14 -14
  65. package/dist/core/memory-engine/file-backend.d.ts +41 -65
  66. package/dist/core/memory-engine/file-backend.js +59 -166
  67. package/dist/core/memory-engine/index.d.ts +3 -2
  68. package/dist/core/memory-engine/index.js +2 -1
  69. package/dist/core/memory-engine/layout.d.ts +6 -1
  70. package/dist/core/memory-engine/layout.js +12 -7
  71. package/dist/core/memory-engine/memory-backend-contract.d.ts +10 -3
  72. package/dist/core/memory-engine/memory-backend-contract.js +158 -2
  73. package/dist/core/memory-engine/memory-deployment.d.ts +11 -3
  74. package/dist/core/memory-engine/memory-deployment.js +31 -6
  75. package/dist/core/memory-engine/origin-clearance.d.ts +12 -3
  76. package/dist/core/memory-engine/origin-clearance.js +68 -9
  77. package/dist/core/memory-engine/session-write-home.d.ts +34 -1
  78. package/dist/core/memory-engine/session-write-home.js +37 -10
  79. package/dist/core/memory-engine/types.d.ts +44 -7
  80. package/dist/core/memory-engine/types.js +2 -1
  81. package/dist/core/mode-policy.js +3 -3
  82. package/dist/core/mods/agent-stations.d.ts +18 -0
  83. package/dist/core/mods/agent-stations.js +8 -6
  84. package/dist/core/mods/extension-call.d.ts +4 -0
  85. package/dist/core/mods/extension-call.js +8 -0
  86. package/dist/core/mods/tool-call.js +3 -4
  87. package/dist/core/parent-spec-seat.d.ts +2 -2
  88. package/dist/core/peer-channel.d.ts +5 -0
  89. package/dist/core/permission-rule-consent.d.ts +21 -10
  90. package/dist/core/permission-rule-consent.js +50 -23
  91. package/dist/core/permission-rule-store.d.ts +41 -16
  92. package/dist/core/permission-rule-store.js +2 -0
  93. package/dist/core/refusal-echo.d.ts +20 -0
  94. package/dist/core/refusal-echo.js +33 -0
  95. package/dist/core/retention.d.ts +180 -10
  96. package/dist/core/retention.js +45 -0
  97. package/dist/core/retired-keys.d.ts +5 -0
  98. package/dist/core/retired-keys.js +3 -0
  99. package/dist/core/rule-offer-read.d.ts +0 -4
  100. package/dist/core/rule-offer-read.js +2 -18
  101. package/dist/core/runner/classifier-ladder.d.ts +7 -1
  102. package/dist/core/runner/classifier-ladder.js +4 -2
  103. package/dist/core/runner/compact-session.js +10 -7
  104. package/dist/core/runner/compaction-call-options.d.ts +7 -7
  105. package/dist/core/runner/compaction-call-options.js +3 -2
  106. package/dist/core/runner/contracts.d.ts +21 -2
  107. package/dist/core/runner/delegation-owner.d.ts +10 -3
  108. package/dist/core/runner/delegation-owner.js +4 -1
  109. package/dist/core/runner/gate-exit.d.ts +6 -0
  110. package/dist/core/runner/gate-exit.js +11 -2
  111. package/dist/core/runner/memory-consolidation-driver.d.ts +4 -2
  112. package/dist/core/runner/memory-consolidation-driver.js +8 -5
  113. package/dist/core/runner/prepare-ask-lane.js +3 -3
  114. package/dist/core/runner/prepare-caps-and-workflow.d.ts +3 -1
  115. package/dist/core/runner/prepare-caps-and-workflow.js +2 -2
  116. package/dist/core/runner/prepare-config-doors.js +4 -0
  117. package/dist/core/runner/prepare-delegation-surface.d.ts +3 -0
  118. package/dist/core/runner/prepare-delegation-surface.js +2 -2
  119. package/dist/core/runner/prepare-gate-stations.d.ts +5 -0
  120. package/dist/core/runner/prepare-gate-stations.js +5 -5
  121. package/dist/core/runner/prepare-hands-readface.js +1 -1
  122. package/dist/core/runner/prepare-inherited-gate.d.ts +3 -1
  123. package/dist/core/runner/prepare-inherited-gate.js +4 -2
  124. package/dist/core/runner/prepare-memory.d.ts +4 -0
  125. package/dist/core/runner/prepare-memory.js +14 -20
  126. package/dist/core/runner/prepare-policy-chain.js +7 -7
  127. package/dist/core/runner/prepare-prompt-inputs.js +1 -1
  128. package/dist/core/runner/prepare-task.js +15 -10
  129. package/dist/core/runner/prepare-wiring-manifest.d.ts +3 -1
  130. package/dist/core/runner/prepare-wiring-manifest.js +3 -2
  131. package/dist/core/runner/resume-admission.d.ts +2 -2
  132. package/dist/core/runner/resume-admission.js +2 -23
  133. package/dist/core/runner/role-resolution-table.d.ts +98 -0
  134. package/dist/core/runner/role-resolution-table.js +62 -0
  135. package/dist/core/runner/run-compaction-machinery.js +2 -2
  136. package/dist/core/runner/run-identity-wiring.js +12 -9
  137. package/dist/core/runner/run-leg.js +8 -4
  138. package/dist/core/runner/run-notification-lane.js +22 -22
  139. package/dist/core/runner/run-recovery-lanes.js +3 -3
  140. package/dist/core/runner/run-terminal-adoption.js +1 -1
  141. package/dist/core/runner/run-turn-boundary.js +14 -15
  142. package/dist/core/runner/runtask.js +1 -1
  143. package/dist/core/runner/tool-occurrence.d.ts +4 -2
  144. package/dist/core/runner/tool-occurrence.js +2 -2
  145. package/dist/core/runner-deps.d.ts +1 -1
  146. package/dist/core/session-checkout.d.ts +63 -3
  147. package/dist/core/session-checkout.js +152 -58
  148. package/dist/core/shell-read-silence.js +8 -0
  149. package/dist/core/store-contracts/peer-directory-contract.js +8 -1
  150. package/dist/core/task-event.d.ts +9 -5
  151. package/dist/core/task-notification.d.ts +110 -31
  152. package/dist/core/task-notification.js +180 -100
  153. package/dist/core/task-registry-agent.d.ts +11 -0
  154. package/dist/core/task-registry-agent.js +11 -3
  155. package/dist/core/task-registry-shared.d.ts +7 -0
  156. package/dist/core/task-registry.d.ts +18 -0
  157. package/dist/core/task-registry.js +27 -8
  158. package/dist/core/task-spec.d.ts +7 -2
  159. package/dist/core/tool-errors.d.ts +14 -6
  160. package/dist/core/tool-errors.js +1 -1
  161. package/dist/core/tool-policy.d.ts +18 -1
  162. package/dist/core/tool-policy.js +16 -7
  163. package/dist/core/tool-result-store.d.ts +20 -0
  164. package/dist/core/tool-spec.d.ts +4 -0
  165. package/dist/core/trace.d.ts +3 -2
  166. package/dist/core/workflow-journal-store.d.ts +11 -0
  167. package/dist/core/workflow-journal-store.js +7 -0
  168. package/dist/core/workflow-run-store.d.ts +9 -0
  169. package/dist/core/workflow-run-store.js +6 -0
  170. package/dist/engine/compaction/compaction.d.ts +2 -1
  171. package/dist/engine/harness/types.d.ts +1 -0
  172. package/dist/engine/session/session.d.ts +7 -1
  173. package/dist/engine/session/session.js +5 -2
  174. package/dist/index.d.ts +7 -5
  175. package/dist/index.js +7 -5
  176. package/dist/orchestration/run-workflow-tool.d.ts +4 -0
  177. package/dist/orchestration/run-workflow-tool.js +7 -0
  178. package/dist/orchestration/workflow-types.d.ts +2 -1
  179. package/dist/orchestration/workflow.d.ts +3 -0
  180. package/dist/orchestration/workflow.js +2 -1
  181. package/dist/stores/file/checkpoint-store.d.ts +6 -0
  182. package/dist/stores/file/checkpoint-store.js +4 -1
  183. package/dist/stores/file/file-history-store.d.ts +13 -0
  184. package/dist/stores/file/file-history-store.js +75 -13
  185. package/dist/stores/file/index.d.ts +11 -1
  186. package/dist/stores/file/index.js +7 -11
  187. package/dist/stores/file/permission-rule-store.d.ts +23 -0
  188. package/dist/stores/file/permission-rule-store.js +75 -7
  189. package/dist/stores/file/tool-result-store.d.ts +14 -0
  190. package/dist/stores/file/tool-result-store.js +39 -2
  191. package/dist/stores/file/workflow-journal-store.d.ts +4 -0
  192. package/dist/stores/file/workflow-journal-store.js +17 -0
  193. package/dist/stores/file/workflow-run-store.d.ts +3 -0
  194. package/dist/stores/file/workflow-run-store.js +15 -0
  195. package/dist/tools/fs/read-deny.d.ts +15 -2
  196. package/dist/tools/fs/read-deny.js +10 -2
  197. package/dist/tools/fs/shell-read-check.d.ts +8 -2
  198. package/dist/tools/fs/shell-read-check.js +7 -7
  199. package/package.json +2 -2
  200. package/test/export-surface.snapshot.json +63 -1
  201. package/wire-changes/core-stores-sql@7.64.0.json +30 -0
  202. package/wire-changes/core@7.64.0.json +2653 -0
  203. package/wire-changes/mods-kernel@7.64.0.json +30 -0
  204. package/wire-changes/primitives@7.64.0.json +30 -0
@@ -1,7 +1,7 @@
1
1
  import { randomUUID } from "node:crypto";
2
2
  import { appendSessionCheckout, readSessionCheckout } from "../engine/session/session.js";
3
3
  import { isSensitiveRecordKey } from "@sema-agent/primitives";
4
- import { managedAnchorOf, managedWorktreeBranchOf, managedWorktreeDir, mintManagedWorktree, removeManagedWorktree, repositoryRootOf, resolveBaseCommit, shq, symlinkedLevel, WORKTREE_PARENT, worktreeNameProblem, } from "./git-worktree-env.js";
4
+ import { managedAnchorOf, managedWorktreeBaseOf, managedWorktreeBranchOf, managedWorktreeDir, mintManagedWorktree, removeManagedWorktree, repositoryRootOf, resolveBaseCommit, shq, symlinkedLevel, WORKTREE_PARENT, worktreeNameProblem, } from "./git-worktree-env.js";
5
5
  import { strayMembersOf } from "./own-property-receipt.js";
6
6
  import { thrownText } from "./thrown-value.js";
7
7
  export const WORKTREE_INCAPABLE_REASONS = Object.freeze([
@@ -178,23 +178,31 @@ async function birthRecordPath(env, dir) {
178
178
  const gitDir = await run(env, "git rev-parse --absolute-git-dir", dir);
179
179
  return gitDir !== undefined && gitDir.exitCode === 0 && gitDir.stdout.trim().startsWith("/") ? `${gitDir.stdout.trim()}/sema-allocation` : undefined;
180
180
  }
181
- async function readBirthRecord(env, dir) {
181
+ async function readBirthMark(env, dir) {
182
+ const unreadable = (detail) => ({ kind: "unreadable", detail });
183
+ const own = await env.canonicalPath(dir);
184
+ const top = await checkoutTopOf(env, dir);
185
+ if (!own.ok || top === undefined)
186
+ return unreadable(`git cannot say which checkout ${dir} is`);
187
+ if (top !== own.value)
188
+ return { kind: "absent" };
182
189
  const at = await birthRecordPath(env, dir);
183
190
  if (at === undefined)
184
- return undefined;
191
+ return unreadable(`git does not name the private directory of ${dir}`);
185
192
  const text = await env.readTextFile(at);
186
193
  if (!text.ok)
187
- return undefined;
194
+ return text.error.code === "not_found" ? { kind: "absent" } : unreadable(`its allocation mark cannot be read (${thrownText(text.error).slice(0, 200)})`);
188
195
  try {
189
196
  const v = JSON.parse(text.value);
190
- return typeof v.allocationId === "string" && typeof v.sessionId === "string" && typeof v.baseSha === "string" && FULL_SHA.test(v.baseSha) && typeof v.declared === "string"
191
- ? { allocationId: v.allocationId, sessionId: v.sessionId, baseSha: v.baseSha, declared: v.declared }
192
- : undefined;
197
+ if (typeof v.allocationId === "string" && typeof v.sessionId === "string" && typeof v.baseSha === "string" && FULL_SHA.test(v.baseSha) && typeof v.declared === "string") {
198
+ return { kind: "marked", mark: { allocationId: v.allocationId, sessionId: v.sessionId, baseSha: v.baseSha, declared: v.declared } };
199
+ }
193
200
  }
194
201
  catch {
195
- return undefined;
196
202
  }
203
+ return unreadable("its allocation mark is not a valid record");
197
204
  }
205
+ const recordHoldsMark = (holder, mark) => holder.allocationId === mark.allocationId;
198
206
  const overlaps = (path, top) => path === top || path.startsWith(`${top}/`) || top.startsWith(`${path === "/" ? "" : path}/`);
199
207
  async function refuseOverlap(env, base, additional) {
200
208
  const top = await canonicalOf(env, base);
@@ -261,8 +269,8 @@ async function reopen(input, declared, record) {
261
269
  }
262
270
  if (info.value.kind !== "directory")
263
271
  throw refusal("workspace.checkout_missing", `This session's tree ${cell.dir} is no longer a directory; the leg was not started.`);
264
- const birth = await readBirthRecord(env, cell.dir);
265
- if (birth === undefined || birth.allocationId !== record.allocationId) {
272
+ const birth = await readBirthMark(env, cell.dir);
273
+ if (birth.kind !== "marked" || !recordHoldsMark(record, birth.mark)) {
266
274
  throw refusal("workspace.checkout_missing", `This session's tree ${cell.dir} is no longer the tree this session minted (its allocation mark is missing or names another allocation); the leg was not started. Release the session's checkout and start a new session.`);
267
275
  }
268
276
  if (cell.root === "taskRoot") {
@@ -320,12 +328,16 @@ async function allocate(input, declared, observedLeaf) {
320
328
  }
321
329
  isolatedRepository = probe.gitRoot;
322
330
  const dir = managedWorktreeDir(isolatedRepository, name);
331
+ const placed = await placeInTree(env, baseRoot, dir);
332
+ if (placed === undefined)
333
+ throw refusal("workspace.isolation_unavailable", `The task root ${baseRoot} has no place in the session's tree ${dir}.`);
323
334
  let tree;
324
335
  const existing = await env.fileInfo(dir);
325
336
  if (existing.ok || existing.error.code !== "not_found") {
326
- const birth = await readBirthRecord(env, dir);
337
+ const read = await readBirthMark(env, dir);
338
+ const birth = read.kind === "marked" ? read.mark : undefined;
327
339
  if (birth === undefined || birth.sessionId !== sessionId) {
328
- throw refusal("workspace.isolation_unavailable", `The session's tree cannot be made: a tree named "${name}" already exists at ${dir} and was not minted by this session (name_in_use). Declare another name.`);
340
+ throw refusal("workspace.isolation_unavailable", `The session's tree cannot be made: a tree named "${name}" already exists at ${dir} and was not minted by this session (name_in_use). Declare another name — or, when no session's record holds that tree, release it with releaseOrphanSessionTree (listOrphanSessionTrees lists such trees).`);
329
341
  }
330
342
  if (birth.declared !== declaredDigest(declared)) {
331
343
  const atOtherCommit = taskRootSource !== undefined && birth.baseSha !== taskRootSource.sha;
@@ -356,6 +368,9 @@ async function allocate(input, declared, observedLeaf) {
356
368
  throw refusal(taskRootSource !== undefined ? "workspace.source_mismatch" : "workspace.isolation_unavailable", `The session's tree cannot be made${taskRootSource !== undefined ? ` at the declared commit ${taskRootSource.sha}` : ""}: ${why.slice(0, 600)}`);
357
369
  }
358
370
  const undo = async (why, code) => {
371
+ const mark = await readBirthMark(env, minted.worktreeDir);
372
+ if (mark.kind !== "absent")
373
+ throw refusal(code, `${why} The tree is kept at ${minted.worktreeDir} (its allocation mark ${mark.kind === "marked" ? "was written" : "cannot be read"}); a tree no record holds is listed by listOrphanSessionTrees.`);
359
374
  const removed = await removeManagedWorktree(env, minted.anchor, minted.worktreeDir, minted.baseSha !== undefined ? { name: minted.branch, baseSha: minted.baseSha } : undefined, undefined, "clean");
360
375
  throw refusal(code, `${why}${removed.ok ? "" : ` The tree minted for it was left at ${minted.worktreeDir} (${removed.detail.trim().slice(0, 200)}).`}`);
361
376
  };
@@ -366,7 +381,7 @@ async function allocate(input, declared, observedLeaf) {
366
381
  const wrote = birthAt === undefined ? undefined : await env.writeFile(birthAt, JSON.stringify({ allocationId, sessionId, baseSha: minted.baseSha, declared: declaredDigest(declared) }));
367
382
  if (wrote === undefined || !wrote.ok)
368
383
  return undo("The session's tree could not be marked as this session's; the leg was not started.", "workspace.isolation_unavailable");
369
- tree = { dir: minted.worktreeDir, branch: minted.branch, baseSha: minted.baseSha, baseRef: taskRootSource !== undefined ? "source" : declared.baseRef ?? "fresh", allocationId, undo };
384
+ tree = { dir: minted.worktreeDir, branch: minted.branch, baseSha: minted.baseSha, baseRef: taskRootSource !== undefined ? "source" : declared.baseRef ?? "fresh", allocationId };
370
385
  }
371
386
  checkouts.push({
372
387
  repository: isolatedRepository,
@@ -378,38 +393,23 @@ async function allocate(input, declared, observedLeaf) {
378
393
  baseRef: tree.baseRef,
379
394
  ...(taskRootSource !== undefined ? { source: { remote: taskRootSource.remote, sha: taskRootSource.sha, ...(taskRootSource.ref !== undefined ? { ref: taskRootSource.ref } : {}) } } : {}),
380
395
  });
381
- const placed = await placeInTree(env, baseRoot, tree.dir);
382
- if (placed === undefined) {
383
- const why = `The task root ${baseRoot} has no place in the session's tree ${tree.dir}.`;
384
- if (tree.undo !== undefined)
385
- return tree.undo(why, "workspace.isolation_unavailable");
386
- throw refusal("workspace.isolation_unavailable", why);
387
- }
388
- taskRoot = placed;
396
+ taskRoot = `${tree.dir}${placed.slice(dir.length)}`;
389
397
  const record = { allocationId: tree.allocationId, sessionId, declared, checkouts: [...checkouts, ...sourceCells] };
390
- return { taskRoot, record: await recordNow(input.session, record, observedLeaf, tree.undo) };
398
+ return { taskRoot, record: await recordNow(input.session, record, observedLeaf) };
391
399
  }
392
400
  const record = { allocationId, sessionId, declared, checkouts: sourceCells };
393
401
  return { taskRoot, record: await recordNow(input.session, record, observedLeaf) };
394
402
  }
395
- async function recordNow(session, record, observedLeaf, undo) {
403
+ async function recordNow(session, record, observedLeaf) {
396
404
  try {
397
405
  await appendSessionCheckout(session, record, observedLeaf);
398
406
  }
399
407
  catch (err) {
400
- const why = `This session's checkout could not be recorded (${thrownText(err).slice(0, 300)}); the leg was not started.`;
401
- const back = await readSessionCheckout(session, record.sessionId).catch((e) => ({ kind: "unreadable", detail: thrownText(e) }));
402
408
  const dirs = record.checkouts.flatMap((cell) => (cell.dir === undefined ? [] : [cell.dir]));
403
- const named = back.kind === "record" ? back.record : undefined;
404
- const holds = named !== undefined && (named.allocationId === record.allocationId || named.checkouts.some((cell) => cell.dir !== undefined && dirs.includes(cell.dir)));
405
- if (undo !== undefined && back.kind !== "unreadable" && !holds)
406
- return undo(why, "workspace.checkout_unavailable");
407
- const note = back.kind === "unreadable"
408
- ? ` The allocation record could not be read back${dirs.length > 0 ? `; the tree is kept at ${dirs.join(", ")}` : ""} (${back.detail.slice(0, 200)}).`
409
- : named !== undefined && holds && named.allocationId !== record.allocationId
410
- ? ` Another record names this tree; the tree is kept at ${dirs.join(", ")}.`
411
- : "";
412
- throw refusal("workspace.checkout_unavailable", `${why}${note}`);
409
+ const kept = dirs.length === 0
410
+ ? ""
411
+ : ` The tree is kept at ${dirs.join(", ")}. If the record was written, the next leg reopens it and releaseSessionCheckout releases it; if not, the next leg of this session with the same declaration takes it back; a tree no record holds is listed by listOrphanSessionTrees.`;
412
+ throw refusal("workspace.checkout_unavailable", `This session's checkout could not be recorded (${thrownText(err).slice(0, 300)}); the leg was not started.${kept}`);
413
413
  }
414
414
  return record;
415
415
  }
@@ -429,7 +429,7 @@ export async function releaseSessionCheckout(env, session, opts) {
429
429
  for (const cell of record.checkouts) {
430
430
  if (cell.dir === undefined || cell.branch === undefined)
431
431
  continue;
432
- trees.push(await releaseTree(env, record, cell, onExit));
432
+ trees.push(await releaseTree(env, { path: cell.dir, repository: cell.repository, branch: cell.branch, baseSha: cell.baseSha }, record, onExit));
433
433
  }
434
434
  if (record.released !== true)
435
435
  await appendSessionCheckout(session, { ...record, released: true });
@@ -441,42 +441,136 @@ function ignoredDetail(paths) {
441
441
  const more = paths.length > IGNORED_NAMED ? ` and ${paths.length - IGNORED_NAMED} more` : "";
442
442
  return `the tree holds files git ignores (${named}${more}), which removing it would delete — delete or move them, then release again`;
443
443
  }
444
- async function releaseTree(env, record, cell, onExit) {
445
- const path = cell.dir;
446
- const branchLeft = async () => {
447
- const ref = await run(env, `git rev-parse --verify --quiet ${shq(`refs/heads/${cell.branch}`)}`, cell.repository);
448
- return ref !== undefined && ref.exitCode === 0 ? { branch: cell.branch } : {};
449
- };
444
+ async function branchLeftOf(env, tree) {
445
+ const ref = await run(env, `git rev-parse --verify --quiet ${shq(`refs/heads/${tree.branch}`)}`, tree.repository);
446
+ return ref !== undefined && ref.exitCode === 0 ? { branch: tree.branch } : {};
447
+ }
448
+ async function goneTree(env, tree) {
449
+ await run(env, "git worktree prune", tree.repository);
450
+ return { path: tree.path, removed: true, ...(await branchLeftOf(env, tree)) };
451
+ }
452
+ async function releaseTree(env, tree, holder, onExit) {
453
+ const { path, repository, branch, baseSha } = tree;
450
454
  const at = await env.fileInfo(path);
451
455
  if (!at.ok) {
452
456
  if (at.error.code !== "not_found")
453
- return { path, removed: false, kept: "unverifiable", branch: cell.branch, detail: thrownText(at.error).slice(0, 300) };
454
- await run(env, "git worktree prune", cell.repository);
455
- return { path, removed: true, ...(await branchLeft()) };
457
+ return { path, removed: false, kept: "unverifiable", branch, detail: thrownText(at.error).slice(0, 300) };
458
+ return goneTree(env, tree);
456
459
  }
457
- const birth = await readBirthRecord(env, path);
458
- if (birth === undefined || birth.allocationId !== record.allocationId)
459
- return { path, removed: false, kept: "not_owned", ...(await branchLeft()) };
460
+ const held = async () => {
461
+ const mark = await readBirthMark(env, path);
462
+ return mark.kind === "marked" && recordHoldsMark(holder, mark.mark);
463
+ };
464
+ if (!(await held()))
465
+ return { path, removed: false, kept: "not_owned", ...(await branchLeftOf(env, tree)) };
460
466
  if (onExit === "keep")
461
- return { path, removed: false, kept: "requested", branch: cell.branch };
467
+ return { path, removed: false, kept: "requested", branch };
462
468
  const status = await run(env, "git status --porcelain --ignored --untracked-files=normal", path);
463
469
  if (status === undefined || status.exitCode !== 0)
464
- return { path, removed: false, kept: "unverifiable", branch: cell.branch };
470
+ return { path, removed: false, kept: "unverifiable", branch };
465
471
  const entries = status.stdout.split("\n").filter((line) => line !== "");
466
472
  if (entries.some((line) => !line.startsWith("!! ")))
467
- return { path, removed: false, kept: "dirty", branch: cell.branch };
473
+ return { path, removed: false, kept: "dirty", branch };
468
474
  if (entries.length > 0)
469
- return { path, removed: false, kept: "ignored", branch: cell.branch, detail: ignoredDetail(entries.map((line) => line.slice(3))) };
470
- const ahead = await run(env, `git rev-list --count ${shq(`${cell.baseSha}..HEAD`)}`, path);
475
+ return { path, removed: false, kept: "ignored", branch, detail: ignoredDetail(entries.map((line) => line.slice(3))) };
476
+ const ahead = await run(env, `git rev-list --count ${shq(`${baseSha}..HEAD`)}`, path);
471
477
  const commits = ahead !== undefined && ahead.exitCode === 0 ? Number.parseInt(ahead.stdout.trim(), 10) : Number.NaN;
472
478
  if (!Number.isFinite(commits))
473
- return { path, removed: false, kept: "unverifiable", branch: cell.branch };
479
+ return { path, removed: false, kept: "unverifiable", branch };
474
480
  if (commits > 0)
475
- return { path, removed: false, kept: "commits", branch: cell.branch };
476
- const removed = await removeManagedWorktree(env, cell.repository, path, { name: cell.branch, baseSha: cell.baseSha }, undefined, "clean");
481
+ return { path, removed: false, kept: "commits", branch };
482
+ if (!(await held()))
483
+ return { path, removed: false, kept: "not_owned", ...(await branchLeftOf(env, tree)) };
484
+ const removed = await removeManagedWorktree(env, repository, path, { name: branch, baseSha }, undefined, "clean");
477
485
  if (!removed.ok)
478
- return { path, removed: false, kept: "unverifiable", branch: cell.branch, detail: removed.detail.trim().slice(0, 300) };
479
- return { path, removed: true, ...(await branchLeft()) };
486
+ return { path, removed: false, kept: "unverifiable", branch, detail: removed.detail.trim().slice(0, 300) };
487
+ return { path, removed: true, ...(await branchLeftOf(env, tree)) };
488
+ }
489
+ async function standingOf(env, dir, sessionOf) {
490
+ const read = await readBirthMark(env, dir);
491
+ if (read.kind !== "marked")
492
+ return { kind: "unmarked", read };
493
+ const mark = read.mark;
494
+ const orphan = (why, detail) => ({ kind: "orphan", mark, why, ...(detail !== undefined ? { detail: detail.slice(0, 300) } : {}) });
495
+ let checkout;
496
+ try {
497
+ const session = await sessionOf(mark.sessionId);
498
+ if (session === undefined)
499
+ return orphan("unrecorded");
500
+ checkout = await readSessionCheckout(session, mark.sessionId);
501
+ }
502
+ catch (err) {
503
+ return orphan("record_unreadable", `the session ${mark.sessionId} could not be read (${thrownText(err)})`);
504
+ }
505
+ if (checkout.kind === "unreadable")
506
+ return orphan("record_unreadable", checkout.detail);
507
+ if (checkout.kind === "none") {
508
+ return checkout.window === undefined ? orphan("unrecorded") : orphan("record_unreadable", `the session's log is loaded from a bounded window (floor ${checkout.window.floor}); a checkout record below the floor cannot be ruled out`);
509
+ }
510
+ return recordHoldsMark(checkout.record, mark) ? { kind: "held", mark } : orphan("record_elsewhere", `the session's record holds allocation ${checkout.record.allocationId}`);
511
+ }
512
+ function lookupOf(door, opts) {
513
+ const sessionOf = opts !== null && typeof opts === "object" ? opts.sessionOf : undefined;
514
+ if (typeof sessionOf !== "function")
515
+ throw refusal("config.invalid_argument", `${door}: opts.sessionOf must be a function (the host's lookup of a session by id in its durable store)`);
516
+ return sessionOf;
517
+ }
518
+ export async function listOrphanSessionTrees(env, root, opts) {
519
+ const sessionOf = lookupOf("listOrphanSessionTrees", opts);
520
+ if (typeof root !== "string" || !root.startsWith("/"))
521
+ throw refusal("config.invalid_argument", "listOrphanSessionTrees: root must be an absolute path");
522
+ const repository = await managedAnchorOf(env, root);
523
+ const parent = `${repository}/${WORKTREE_PARENT}`;
524
+ const listed = await env.listDir(parent);
525
+ if (!listed.ok) {
526
+ if (listed.error.code === "not_found")
527
+ return { repository, trees: [] };
528
+ throw refusal("workspace.checkout_unavailable", `listOrphanSessionTrees: the managed parent ${parent} cannot be listed (${thrownText(listed.error).slice(0, 200)}); nothing was judged.`);
529
+ }
530
+ const trees = [];
531
+ for (const child of [...listed.value].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))) {
532
+ if (child.kind !== "directory")
533
+ continue;
534
+ const path = managedWorktreeDir(repository, child.name);
535
+ const standing = await standingOf(env, path, sessionOf);
536
+ if (standing.kind !== "orphan")
537
+ continue;
538
+ const { mark, why, detail } = standing;
539
+ const branch = managedWorktreeBranchOf(path);
540
+ trees.push({
541
+ path,
542
+ ...(branch !== undefined ? await branchLeftOf(env, { repository, branch }) : {}),
543
+ sessionId: mark.sessionId,
544
+ allocationId: mark.allocationId,
545
+ baseSha: mark.baseSha,
546
+ why,
547
+ ...(detail !== undefined ? { detail } : {}),
548
+ modifiedAt: child.mtimeMs,
549
+ });
550
+ }
551
+ return { repository, trees };
552
+ }
553
+ export async function releaseOrphanSessionTree(env, path, opts) {
554
+ const sessionOf = lookupOf("releaseOrphanSessionTree", opts);
555
+ const repository = typeof path === "string" ? managedWorktreeBaseOf(path) : undefined;
556
+ const branch = repository !== undefined ? managedWorktreeBranchOf(path) : undefined;
557
+ if (repository === undefined || branch === undefined) {
558
+ throw refusal("config.invalid_argument", `releaseOrphanSessionTree: ${String(path).slice(0, 200)} is not a managed tree path (<repository root>/${WORKTREE_PARENT}/<name>)`);
559
+ }
560
+ const at = await env.fileInfo(path);
561
+ if (!at.ok)
562
+ return at.error.code === "not_found" ? goneTree(env, { path, repository, branch }) : { path, removed: false, kept: "unverifiable", branch, detail: thrownText(at.error).slice(0, 300) };
563
+ const standing = await standingOf(env, path, sessionOf);
564
+ if (standing.kind === "unmarked") {
565
+ return standing.read.kind === "absent"
566
+ ? { path, removed: false, kept: "not_owned", ...(await branchLeftOf(env, { repository, branch })), detail: "it carries no allocation mark: it is no session tree" }
567
+ : { path, removed: false, kept: "unverifiable", branch, detail: standing.read.detail };
568
+ }
569
+ if (standing.kind === "held")
570
+ return { path, removed: false, kept: "not_owned", branch, detail: "a session's record holds this tree; releaseSessionCheckout releases it" };
571
+ if (standing.why === "record_unreadable")
572
+ return { path, removed: false, kept: "unverifiable", branch, ...(standing.detail !== undefined ? { detail: standing.detail } : {}) };
573
+ return releaseTree(env, { path, repository, branch, baseSha: standing.mark.baseSha }, standing.mark, "keep-if-dirty");
480
574
  }
481
575
  export function sessionFrameOf(record) {
482
576
  if (record === undefined || record.checkouts.length === 0)
@@ -1,6 +1,7 @@
1
1
  import { types } from "node:util";
2
2
  import { dispositionsOfRow, SHELL_READ_FINDINGS } from "../tools/fs/shell-read-judge.js";
3
3
  import { receiveContract } from "./decision-receipt.js";
4
+ import { refusalEchoDefects } from "./refusal-echo.js";
4
5
  import { egressThrownText } from "./untrusted-egress.js";
5
6
  import { receive } from "./mods/kernel/receive.js";
6
7
  import { attest, attestationOf } from "./engine-attestation.js";
@@ -13,6 +14,7 @@ const MEMBER_KINDS = {
13
14
  face: "face",
14
15
  sentence: "word",
15
16
  details: "record",
17
+ echoed: "list",
16
18
  readRootCandidate: "record",
17
19
  unestablished: "mark",
18
20
  writesPlaced: "mark",
@@ -43,6 +45,12 @@ function receivedAnswer(answer, call) {
43
45
  return undefined;
44
46
  v = data.value;
45
47
  }
48
+ if (kind === "list") {
49
+ const data = receive(v, OWNED_DATA_MODE);
50
+ if (!data.ok || !Array.isArray(data.value) || refusalEchoDefects(data.value).length > 0)
51
+ return undefined;
52
+ v = Object.freeze(data.value);
53
+ }
46
54
  if (kind === "admission") {
47
55
  const admission = v;
48
56
  v = () => {
@@ -3,7 +3,7 @@ import { readPeerSessionRecord, resolvePeerSessions } from "../../agents/peer-di
3
3
  import { beginContract } from "./contract-harness.js";
4
4
  export const PEER_DIRECTORY_CONTRACT_SCOPE = "peer-kit-A";
5
5
  function row(name, sessionId, over = {}) {
6
- return { schemaVersion: 1, sessionId, scope: PEER_DIRECTORY_CONTRACT_SCOPE, name, startedAt: 1_000, updatedAt: 2_000, liveness: "live", where: "hosted", ...over };
6
+ return { schemaVersion: 1, sessionId, occupant: `occ-${sessionId}`, scope: PEER_DIRECTORY_CONTRACT_SCOPE, name, startedAt: 1_000, updatedAt: 2_000, liveness: "live", where: "hosted", ...over };
7
7
  }
8
8
  async function withDirs(mk, fn) {
9
9
  const live = [];
@@ -90,5 +90,12 @@ export async function peerDirectoryContract(mk, hooks) {
90
90
  assert.ok(read.ok, `listed row ${r.sessionId} is refused by the engine's reader (${read.ok ? "" : `${read.reason}${read.field !== undefined ? `: ${read.field}` : ""}`})`);
91
91
  }
92
92
  });
93
+ run("a row's occupant is listed as written — a token and null (a row with no token) alike", async (make) => {
94
+ const d = make();
95
+ await hooks.write(d, row("alpha", "sess-a"));
96
+ await hooks.write(d, row("beta", "sess-b", { occupant: null }));
97
+ const listed = await d.listPeerSessions({ scope: S });
98
+ assert.deepEqual(Object.fromEntries(listed.map((r) => [r.sessionId, r.occupant])), { "sess-a": "occ-sess-a", "sess-b": null }, "the occupant is what a sender stamps on what it parks in that session's box; a directory that loses or rewrites it misaddresses every message");
99
+ });
93
100
  await settle();
94
101
  }
@@ -871,10 +871,12 @@ export type TaskEvent = ({
871
871
  * - `"blocked"` — a `preCompact` hook deliberately blocked the pass.
872
872
  * - `"suppressed"` — wanted to fire, held under the §25.2 anti-thrash floor.
873
873
  * - `"noop"` — the pass ran but found nothing to compact (no valid cut point/empty history).
874
- * - `"disabled"` — an explicit (manual/forced) request was refused because compaction is off,
875
- * or the rapid-refill breaker disabled compaction mid-task (`reason` says which). A spec
876
- * that statically disables compaction does NOT produce one of these per boundary (that
877
- * would be per-boundary noise about a static configuration, not a state change).
874
+ * - `"disabled"` — a requested pass (`trigger:"manual"`) was refused because the `manualCompact`
875
+ * seat is off, or the rapid-refill breaker disabled compaction mid-task (`reason` says so; the
876
+ * trigger is the landing pass's). The `trigger` names the seat: a `"manual"` frame is the
877
+ * `manualCompact` seat's, never the `autoCompact` seat's. A seat that is statically off does NOT
878
+ * produce one of these per boundary for the passes the engine would start (that would be
879
+ * per-boundary noise about a static configuration, not a state change).
878
880
  * - `"mooted"` — the pass did not run to its end: a manual request no boundary could serve
879
881
  * (`trigger:"manual"`, `reason:"task_ending"`), or a request withdrawn / a pass cut in flight by its
880
882
  * caller — a `compact({ signal })` withdrawal, `halt()`, `interrupt()`, `destroy()` or the task's own
@@ -1392,6 +1394,8 @@ export interface HumanInputAttachment {
1392
1394
  * durable suspend / plan review in flight), or the task settled before any boundary arrived.
1393
1395
  * - `"noop"` — the attempt ran but there was nothing to compact (no valid cut point / empty history).
1394
1396
  * - `"blocked"` — a `preCompact` hook deliberately blocked this compaction (not a failure).
1395
- * - `"disabled"` — compaction is disabled by the task spec (`compaction.enabled: false`).
1397
+ * - `"disabled"` — requested compaction is switched off: the `manualCompact` seat is `false` (the task's
1398
+ * `compaction.manualCompact`, else the deployment's `contextSettings[word].manualCompact`). No pass ran. The
1399
+ * `autoCompact` seat never answers a request: with it off a requested pass still runs.
1396
1400
  */
1397
1401
  export type CompactOutcome = "compacted" | "failed" | "mooted" | "noop" | "blocked" | "disabled";