@sema-agent/core 7.62.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 (193) hide show
  1. package/CHANGELOG.md +528 -0
  2. package/dist/agents/subagent-transcript-placement.d.ts +23 -0
  3. package/dist/agents/subagent-transcript-placement.js +14 -0
  4. package/dist/agents/subagent.js +82 -51
  5. package/dist/brain/route-adjudicator.js +9 -4
  6. package/dist/core/approval-object.js +1 -1
  7. package/dist/core/arg-summary.js +1 -1
  8. package/dist/core/ask-question.d.ts +2 -2
  9. package/dist/core/canonical-json.d.ts +23 -13
  10. package/dist/core/canonical-json.js +4 -4
  11. package/dist/core/checkpoint-queries.d.ts +47 -4
  12. package/dist/core/checkpoint-queries.js +36 -16
  13. package/dist/core/checkpoint-requirements.d.ts +3 -3
  14. package/dist/core/checkpoint-requirements.js +2 -1
  15. package/dist/core/checkpoint-row-verdict.d.ts +15 -4
  16. package/dist/core/checkpoint-row-verdict.js +22 -2
  17. package/dist/core/checkpoint-store.d.ts +23 -10
  18. package/dist/core/checkpoint-store.js +45 -4
  19. package/dist/core/compliance.d.ts +6 -2
  20. package/dist/core/compliance.js +3 -3
  21. package/dist/core/engine-attestation.d.ts +1 -1
  22. package/dist/core/engine-notice.d.ts +19 -4
  23. package/dist/core/git-worktree-env.d.ts +62 -3
  24. package/dist/core/git-worktree-env.js +91 -30
  25. package/dist/core/governance-codes.d.ts +7 -3
  26. package/dist/core/governance-codes.js +13 -3
  27. package/dist/core/memory-engine/consolidation-driver.d.ts +32 -17
  28. package/dist/core/memory-engine/consolidation-driver.js +99 -98
  29. package/dist/core/memory-engine/consolidation.d.ts +73 -10
  30. package/dist/core/memory-engine/consolidation.js +167 -11
  31. package/dist/core/memory-engine/data-plane.d.ts +8 -4
  32. package/dist/core/memory-engine/data-plane.js +11 -6
  33. package/dist/core/memory-engine/delegation-settlement.d.ts +37 -35
  34. package/dist/core/memory-engine/delegation-settlement.js +53 -59
  35. package/dist/core/memory-engine/dual-root.d.ts +12 -6
  36. package/dist/core/memory-engine/dual-root.js +9 -5
  37. package/dist/core/memory-engine/engine.d.ts +98 -35
  38. package/dist/core/memory-engine/engine.js +477 -380
  39. package/dist/core/memory-engine/entry-scan.d.ts +8 -0
  40. package/dist/core/memory-engine/entry-scan.js +3 -0
  41. package/dist/core/memory-engine/file-backend.d.ts +29 -3
  42. package/dist/core/memory-engine/file-backend.js +66 -35
  43. package/dist/core/memory-engine/index.d.ts +7 -7
  44. package/dist/core/memory-engine/index.js +6 -6
  45. package/dist/core/memory-engine/landing-admission.d.ts +5 -3
  46. package/dist/core/memory-engine/landing-admission.js +3 -3
  47. package/dist/core/memory-engine/layout.d.ts +121 -45
  48. package/dist/core/memory-engine/layout.js +252 -102
  49. package/dist/core/memory-engine/memory-backend-contract.d.ts +19 -1
  50. package/dist/core/memory-engine/memory-backend-contract.js +320 -0
  51. package/dist/core/memory-engine/memory-deployment.d.ts +31 -8
  52. package/dist/core/memory-engine/memory-deployment.js +26 -12
  53. package/dist/core/memory-engine/scope-contract.d.ts +52 -11
  54. package/dist/core/memory-engine/scope-contract.js +68 -19
  55. package/dist/core/memory-engine/session-write-home.d.ts +3 -1
  56. package/dist/core/memory-engine/session-write-home.js +1 -1
  57. package/dist/core/memory-engine/sync-client.d.ts +3 -1
  58. package/dist/core/memory-engine/sync-client.js +7 -0
  59. package/dist/core/memory-engine/sync-report.d.ts +3 -2
  60. package/dist/core/memory-engine/sync-report.js +6 -2
  61. package/dist/core/memory-engine/tools.d.ts +2 -2
  62. package/dist/core/memory-engine/tools.js +10 -10
  63. package/dist/core/memory-engine/types.d.ts +118 -19
  64. package/dist/core/memory-engine/types.js +1 -0
  65. package/dist/core/memory.js +15 -6
  66. package/dist/core/mods/stations.d.ts +20 -1
  67. package/dist/core/mods/stations.js +21 -2
  68. package/dist/core/park-selfcheck.js +2 -2
  69. package/dist/core/pause-registry.d.ts +2 -0
  70. package/dist/core/pause-registry.js +3 -0
  71. package/dist/core/permission-rule-consent.d.ts +10 -3
  72. package/dist/core/permission-rule-consent.js +37 -24
  73. package/dist/core/permission-rule-store.d.ts +35 -1
  74. package/dist/core/permission-rule-store.js +27 -8
  75. package/dist/core/read-only-shell.js +3 -2
  76. package/dist/core/redaction-marks.d.ts +8 -0
  77. package/dist/core/redaction-marks.js +6 -0
  78. package/dist/core/remote-env.d.ts +12 -1
  79. package/dist/core/remote-env.js +3 -0
  80. package/dist/core/runner/child-tree.d.ts +29 -3
  81. package/dist/core/runner/child-tree.js +39 -16
  82. package/dist/core/runner/contracts.d.ts +18 -9
  83. package/dist/core/runner/gate-exit.js +2 -2
  84. package/dist/core/runner/inherited-ask-grants.js +1 -1
  85. package/dist/core/runner/memory-consolidation-driver.d.ts +6 -3
  86. package/dist/core/runner/memory-consolidation-driver.js +4 -4
  87. package/dist/core/runner/memory-consolidation-write-judge.d.ts +2 -1
  88. package/dist/core/runner/memory-consolidation-write-judge.js +3 -2
  89. package/dist/core/runner/person-path-rows.d.ts +8 -3
  90. package/dist/core/runner/person-path-rows.js +5 -1
  91. package/dist/core/runner/placement-fence.d.ts +12 -0
  92. package/dist/core/runner/placement-fence.js +20 -6
  93. package/dist/core/runner/prepare-ask-lane.js +2 -2
  94. package/dist/core/runner/prepare-caps-and-workflow.d.ts +4 -1
  95. package/dist/core/runner/prepare-caps-and-workflow.js +5 -2
  96. package/dist/core/runner/prepare-execution-env.js +17 -6
  97. package/dist/core/runner/prepare-hands-readface.d.ts +2 -1
  98. package/dist/core/runner/prepare-hands-readface.js +4 -3
  99. package/dist/core/runner/prepare-inherited-gate.d.ts +10 -8
  100. package/dist/core/runner/prepare-inherited-gate.js +8 -4
  101. package/dist/core/runner/prepare-memory-engine-session.d.ts +2 -4
  102. package/dist/core/runner/prepare-memory-engine-session.js +4 -4
  103. package/dist/core/runner/prepare-memory.d.ts +3 -2
  104. package/dist/core/runner/prepare-memory.js +28 -20
  105. package/dist/core/runner/prepare-park-ask.js +4 -3
  106. package/dist/core/runner/prepare-task.js +15 -12
  107. package/dist/core/runner/prepare-workspace-restore.js +3 -6
  108. package/dist/core/runner/run-leg.js +1 -1
  109. package/dist/core/runner/run-settle-and-teardown.js +3 -2
  110. package/dist/core/runner/terminal-account.js +1 -1
  111. package/dist/core/runner-deps.d.ts +6 -2
  112. package/dist/core/secret-env.d.ts +1 -1
  113. package/dist/core/secret-env.js +4 -4
  114. package/dist/core/session-checkout.d.ts +108 -0
  115. package/dist/core/session-checkout.js +485 -0
  116. package/dist/core/session-store.d.ts +12 -4
  117. package/dist/core/session-store.js +23 -3
  118. package/dist/core/session.d.ts +16 -2
  119. package/dist/core/session.js +3 -0
  120. package/dist/core/store-contracts/checkpoint-store-contract.d.ts +0 -12
  121. package/dist/core/store-contracts/checkpoint-store-contract.js +6 -7
  122. package/dist/core/store-contracts/session-store-contract.js +39 -0
  123. package/dist/core/task-event.d.ts +21 -0
  124. package/dist/core/task-notification.d.ts +9 -1
  125. package/dist/core/task-notification.js +6 -0
  126. package/dist/core/task-registry-agent.d.ts +14 -2
  127. package/dist/core/task-registry-agent.js +45 -19
  128. package/dist/core/task-registry-shared.d.ts +26 -11
  129. package/dist/core/task-registry.d.ts +15 -9
  130. package/dist/core/task-registry.js +9 -10
  131. package/dist/core/task-spec-members.js +1 -1
  132. package/dist/core/task-spec.d.ts +20 -0
  133. package/dist/core/tool-policy.d.ts +14 -12
  134. package/dist/core/tool-policy.js +11 -10
  135. package/dist/core/tool-spec.d.ts +38 -19
  136. package/dist/core/types.d.ts +1 -1
  137. package/dist/core/untrusted-egress.d.ts +15 -4
  138. package/dist/core/untrusted-egress.js +23 -22
  139. package/dist/core/workspace-snapshot.d.ts +3 -1
  140. package/dist/core/workspace-snapshot.js +1 -0
  141. package/dist/engine/harness/types.d.ts +66 -1
  142. package/dist/engine/harness/types.js +108 -0
  143. package/dist/engine/session/import-validate.js +6 -1
  144. package/dist/engine/session/session.d.ts +24 -1
  145. package/dist/engine/session/session.js +45 -1
  146. package/dist/index.d.ts +7 -4
  147. package/dist/index.js +7 -4
  148. package/dist/internal/harness-types.d.ts +1 -1
  149. package/dist/orchestration/run-workflow-tool.d.ts +4 -1
  150. package/dist/orchestration/run-workflow-tool.js +1 -0
  151. package/dist/orchestration/workflow.d.ts +3 -0
  152. package/dist/orchestration/workflow.js +3 -1
  153. package/dist/stores/file/session-store.js +2 -1
  154. package/dist/tools/fs/bash-program-position.js +3 -3
  155. package/dist/tools/fs/program-read-model.d.ts +34 -10
  156. package/dist/tools/fs/program-read-model.js +37 -7
  157. package/dist/tools/fs/program-read-model.rows.js +13 -2
  158. package/dist/tools/fs/read-deny.d.ts +13 -1
  159. package/dist/tools/fs/read-deny.js +10 -2
  160. package/dist/tools/fs/removal-targets.js +3 -3
  161. package/dist/tools/fs/safety.d.ts +2 -0
  162. package/dist/tools/fs/safety.js +1 -1
  163. package/dist/tools/fs/shell-read-argv.d.ts +8 -1
  164. package/dist/tools/fs/shell-read-argv.js +34 -29
  165. package/dist/tools/fs/shell-read-bindings.d.ts +2 -0
  166. package/dist/tools/fs/shell-read-bindings.js +5 -1
  167. package/dist/tools/fs/shell-read-brace.d.ts +18 -0
  168. package/dist/tools/fs/shell-read-brace.js +79 -0
  169. package/dist/tools/fs/shell-read-check.js +10 -8
  170. package/dist/tools/fs/shell-read-establish.js +23 -16
  171. package/dist/tools/fs/shell-read-judge.d.ts +11 -0
  172. package/dist/tools/fs/shell-read-judge.js +3 -3
  173. package/dist/tools/fs/shell-read-plan.d.ts +10 -0
  174. package/dist/tools/fs/shell-read-plan.js +189 -93
  175. package/dist/tools/fs/shell-read-start.d.ts +19 -9
  176. package/dist/tools/fs/shell-read-start.js +20 -12
  177. package/dist/tools/fs/shell-read-word.d.ts +10 -0
  178. package/dist/tools/fs/shell-read-word.js +9 -5
  179. package/dist/tools/fs/shell-read-workdir.d.ts +26 -7
  180. package/dist/tools/fs/shell-read-workdir.js +73 -12
  181. package/dist/tools/fs/shell-read-write-targets.js +13 -8
  182. package/dist/tools/worktree.d.ts +3 -2
  183. package/dist/tools/worktree.js +7 -35
  184. package/package.json +3 -2
  185. package/test/export-surface.snapshot.json +73 -11
  186. package/wire-changes/core-stores-sql@7.63.0.json +30 -0
  187. package/wire-changes/core@7.63.0.json +3523 -0
  188. package/wire-changes/mods-kernel@7.63.0.json +30 -0
  189. package/wire-changes/primitives@7.63.0.json +445 -0
  190. package/dist/core/credential-vocabulary.d.ts +0 -176
  191. package/dist/core/credential-vocabulary.js +0 -190
  192. package/dist/core/redaction-passes.d.ts +0 -82
  193. package/dist/core/redaction-passes.js +0 -377
@@ -1,7 +1,8 @@
1
1
  import { asAgentMessage, createCompactionSummaryMessage, createCustomMessage, } from "../harness/messages.js";
2
- import { SessionError, isSyntheticApiErrorMessage, isValidModelChange, normalizeAnnouncedListing, normalizeCompactionStateCarrier, normalizeGitAnnouncement, normalizeReminderMark, normalizeWorkspaceState } from "../harness/types.js";
2
+ import { SessionError, isSyntheticApiErrorMessage, isValidModelChange, normalizeAnnouncedListing, normalizeCompactionStateCarrier, normalizeGitAnnouncement, normalizeReminderMark, normalizeSessionCheckout, normalizeWorkspaceState } from "../harness/types.js";
3
3
  import { readStoredPromptEpoch } from "../../prompt-assembly/epoch.js";
4
4
  import { budgetInvokedSkillsRetention, readElidedMessages, readRetainedInvokedSkills, readUnsummarizedMessages, renderInvokedSkillsRetention, } from "../compaction/utils.js";
5
+ import { thrownText } from "../../core/thrown-value.js";
5
6
  const RETENTION_CLAMP_DEFAULT_CHARS_PER_TOKEN = 3;
6
7
  const RETENTION_CLAMP_WINDOW_FRACTION = 0.5;
7
8
  export function buildSessionContext(pathEntries, opts) {
@@ -395,3 +396,46 @@ export function gitFrameContextVisible(branch, entryId) {
395
396
  const keptIdx = branch.findIndex((e) => e.id === firstKeptId);
396
397
  return keptIdx !== -1 && frameIdx >= keptIdx;
397
398
  }
399
+ export async function readSessionCheckout(session, sessionId) {
400
+ let entries;
401
+ try {
402
+ entries = await session.getStorage().findEntries("session_checkout");
403
+ }
404
+ catch (err) {
405
+ return { kind: "unreadable", detail: `the session log could not be read (${thrownText(err)})` };
406
+ }
407
+ let allocation;
408
+ const releases = [];
409
+ for (const entry of entries) {
410
+ const shaped = normalizeSessionCheckout(entry);
411
+ if (shaped === undefined) {
412
+ const owner = entry.sessionId;
413
+ if (typeof owner === "string" && owner !== sessionId)
414
+ continue;
415
+ return { kind: "unreadable", detail: `session_checkout entry "${entry.id}" is not a valid checkout record` };
416
+ }
417
+ if (shaped.sessionId !== sessionId)
418
+ continue;
419
+ if (shaped.released === true)
420
+ releases.push(shaped);
421
+ else if (allocation !== undefined)
422
+ return { kind: "unreadable", detail: `the session holds two checkout allocations (${allocation.allocationId}, ${shaped.allocationId})` };
423
+ else
424
+ allocation = shaped;
425
+ }
426
+ if (allocation === undefined)
427
+ return releases.length === 0 ? { kind: "none" } : { kind: "unreadable", detail: "the session holds a checkout release with no allocation" };
428
+ if (releases.some((r) => r.allocationId !== allocation.allocationId))
429
+ return { kind: "unreadable", detail: "a checkout release names another allocation" };
430
+ return { kind: "record", record: releases.length > 0 ? { ...allocation, released: true } : allocation };
431
+ }
432
+ export async function appendSessionCheckout(session, record, observedLeafId) {
433
+ const shaped = normalizeSessionCheckout(record);
434
+ if (shaped === undefined)
435
+ throw new SessionError("invalid_entry", "appendSessionCheckout: the record is not a structurally valid session checkout");
436
+ const storage = session.getStorage();
437
+ const parentId = observedLeafId !== undefined ? observedLeafId : await storage.getLeafId();
438
+ const entry = { type: "session_checkout", id: await storage.createEntryId(), parentId, timestamp: new Date().toISOString(), ...shaped };
439
+ await storage.appendEntry(entry, { expectedLeafId: entry.parentId });
440
+ return entry.id;
441
+ }
package/dist/index.d.ts CHANGED
@@ -121,6 +121,7 @@ export { withRetry } from "./core/with-retry.js";
121
121
  export type { RetryPolicy, RetryResult } from "./core/with-retry.js";
122
122
  export type { RemoteExecutionEnv, WorkspaceHandle, SnapshotId, SessionToken, SandboxTier, OutputChunk, ExecStreamOptions, RemoteConnectConfig, VmLifecycleOptions, SecretRef, RemoteExecutionErrorCode, ExecutionEnvFactory, ExecutionEnvFactoryContext, PlacementTarget, } from "./core/remote-env.js";
123
123
  export { addWorktree, pruneWorktrees, WORKTREE_PARENT, type AddWorktreeOptions } from "./core/git-worktree-env.js";
124
+ export { probeWorktreeCapability, releaseSessionCheckout, WORKTREE_INCAPABLE_REASONS, type ReleasedTree, type WorkspaceDeclaration, type WorkspaceSourceDeclaration, type WorktreeCapability, type WorktreeIncapableReason, } from "./core/session-checkout.js";
124
125
  export { runExecGate } from "./core/exec-gate.js";
125
126
  export type { ExecStep, ExecStepResult, ExecGateResult, ExecGateOptions } from "./core/exec-gate.js";
126
127
  export { sanitizeUntrustedText, delimitUntrusted, inlineUntrusted, isMintableProbeReason } from "./core/untrusted-text.js";
@@ -297,20 +298,22 @@ export type { ClassicEventMap, ClassicEventName, ObservedAnswer, EngineModRegist
297
298
  export { KERNEL_CONTRACT_VERSION, MOD_TIERS, MOD_SEATS, MOD_EVENT_SIDES, MOD_EVENT_TABLE, MODS_INVALID_CODE, MODS_REGISTRATION_REFUSED_CODE, type ModTier, type ModRegistrationTier, type ModSeat, type ModEventSide, type ModEventName, type ModEventRow, type ModStation, type ModRegistration, type ModUses, type On, type ModHandler, type ModHandlerOptions, type ModNext, type ModOrigin, type ModTraceEntry, type ModCaughtError, type ModDollarBase, type ModEventPayload, type ModMatcher, type ModAdmissionRecord, } from "./core/mods/kernel/index.js";
298
299
  export type { AgentSpawnAnswer, EngineDollar, ModelCompleteBlock, SessionAppendAnswer, SessionCompactAnswer, SessionSendAnswer, SessionUsage, SessionVersion, ToolCallAnswer } from "./core/mods/dollar.js";
299
300
  export type { ContextOccupancy } from "./core/mods/lifecycle-stations.js";
300
- export { admitModChain } from "./core/mods/stations.js";
301
+ export { admitModChain, promptScreenDeclaredBy } from "./core/mods/stations.js";
301
302
  export { SESSION_APPEND_DOORS, SESSION_APPEND_ORIGIN_KINDS, type SessionAppendDoor, type SessionAppendOrigin } from "./core/mods/session-append.js";
302
303
  export { SESSION_RECEIVE_ORIGIN_KINDS, type SessionReceiveOrigin } from "./core/mods/session-receive.js";
303
304
  export { SESSION_SEND_ORIGIN_KINDS, type SessionSendOrigin } from "./core/mods/session-send.js";
304
305
  export { loadModPackage, type ModPackageHost, type ModPackageRegistration } from "./core/mods/package.js";
305
306
  export { CREDENTIAL_REF_KINDS, CREDENTIAL_REF_TRUST, CREDENTIAL_REF_TEXT_MAX, CREDENTIAL_REF_MAP_MAX, CREDENTIAL_REF_PROBLEM_REASONS, readCredentialRef, type CredentialRef, type CredentialRefKind, type CredentialRefRequestAdmission, type CredentialRefProblem, type CredentialRefProblemReason, type CredentialRefReading, } from "@sema-agent/primitives";
306
307
  export { InMemoryMemoryStore, composeMemoryBlock, composeLayeredMemoryBlock, normalizeMemorySpec, type NormalizedMemorySpec, type MemorySpecInput, supportsConsolidation, supportsPeriodicConsolidation, firstSentence, expandLexicalTerms, lexicalSearchMatch, type Embedder, classifyPromotable, enforcePromotableWriteGate, guardedMemoryStore, MemoryGateError, MemoryProjectionError, detectSecret, enforceSecretWriteGate, enforceStructuredNoteSecretGate, type UtilityGate, type MemoryVectorMode, type ScoredMemory, type MemoryNoteHeader, type MemoryNoteRecord, type MemoryNoteType, type StructuredNoteInput, MEMORY_PROJECT_KEY_ABSENT_REASONS, type MemoryProjectKeyAbsentReason, type MemoryProjectKey, } from "./core/memory.js";
307
- export { MemoryEngine, FileMemoryEngineBackend, memoryBackendContract, assertMemoryBackendSearchEquivalence, type MemoryBackendContractHooks, buildMemoryInstruction, writableRootOf, truncateIndex, scanEntryFiles, deriveRepoKey, deriveRepoMemoryDir, deriveControlPlaneDir, deriveRepoControlPlaneDir, resolveMemoryEngineRoot, scopeDirName, ControlPlaneCorruptError, parseEntryFile, serializeEntryFile, computeEntryRev, entryFromFile, MEMORY_ORIGIN_CAUSES, committedOriginOf, originEquals, consolidationExposedFrontmatter, ambiguousOriginRepresentation, type OriginClearanceRow, type OriginClearanceEvent, type OriginClearanceShadow, committedDistilledOf, distilledEquals, type MemoryEntryDistilled, type MemoryEntryDistilledInput, CONSOLIDATION_DEFAULTS, ConsolidationRefusedError, MEMORY_SEARCH_SUPERSEDED_TAG, consolidationTypeEligible, deriveSupersededSet, memorySupersededNote, readIntentCredentials, supersessionFuseCeiling, deriveShadowedSet, memoryConsolidationRecommendedNotice, memoryConsolidationCommittedNotice, memoryConsolidationConflictNotice, memoryConsolidationIncompleteNotice, memoryConsolidationRefusedNotice, memoryConsolidationWithheldNotice, type ConsolidationGateRead, type ConsolidationGateRow, type ConsolidationIntent, type ConsolidationIntentCredentialRow, type ConsolidationLeaseSeat, type ConsolidationProductProposal, type ConsolidationProposal, type ConsolidationWriteGate, type MemoryConsolidationOptions, type ConsolidationCommitReceipt, type ConsolidationReconcileReport, type ConsolidationResolveReceipt, type ConsolidationPlanSummary, type ConsolidationPlanFoldEvidence, type SessionMemoryStatus, DISTILLER_DEFAULT_MAX_INPUTS_PER_PRODUCT, LLM_DISTILLER_CONTRACT, LLM_DISTILLER_CONTRACT_DL2, LLM_DISTILLER_CONTRACT_DL3, LLM_DISTILLER_CONTRACTS, MEMORY_DISTILLER_CONTRACT_V1, contractGroupingDiff, driveConsolidationToFixpoint, isAliasModelId, llmPlanDistiller, mintExposurePartitionedPlan, mintLlmConsolidationPlan, MEMORY_DISTILLER_PURITY_CONTRACT_V1, detectCleanArmVerbatimLeak, type CleanArmLeakFinding, type CleanArmLeakVerdict, type MemoryDistillerPurityContract, openAiCompatChatSeat, parseJsonAnswer, planParseRepairs, sanitizeLlmGroups, scheduleUnderFuse, type ConsolidationDistillFn, type ConsolidationDriveCycleRow, type ConsolidationDriveEngine, type ConsolidationDriveResult, type ConsolidationFoldState, type DistillerCandidate, type DistillerChatAnswer, type DistillerChatFn, type DistillerChatRequest, type FuseSchedule, type LlmConsolidationPlan, type LlmConsolidationPlanArm, type LlmConsolidationPlanProduct, type LlmDistillerContract, type MintLlmConsolidationPlanResult, type PlanParseRepairs, type SanitizedLlmGroups, CONSOLIDATION_DRIVER_PLANS_DIR, CONSOLIDATION_DRIVER_RUNS_FILE, CONSOLIDATION_RUN_STOP_REASONS, CONSOLIDATION_WRITE_REFUSED_CODE, archiveDistillerPlan, readConsolidationDriverRun, runMemoryConsolidationDriver, type ConsolidationDriverEngine, type ConsolidationDriverRunRow, type ConsolidationRunReceipt, type ConsolidationRunStopReason, type ConsolidationWriteJudge, type ConsolidationWriteTarget, type RunMemoryConsolidationOptions, isInstructionEntry, type MemoryEntryOrigin, type MemoryOriginCause, MEMORY_INSTRUCTION_TEMPLATE, MEMORY_RECALL_DISCIPLINE, MEMORY_PREFERENCE_DISCIPLINE, MEMORY_READONLY_NOTICE, MEMORY_CAPTURE_OPTOUT_NOTICE, memoryCaptureOptedOutNotice, memoryCaptureOptOutUnpersistedNotice, SESSION_CAPTURE_OPTOUT_DIR, markSessionCaptureOptOut, readSessionCaptureOptOut, listSessionCaptureOptOut, fileSessionCaptureRecordStore, type SessionCaptureOptOutRecord, type SessionCaptureOptOutMarkOutcome, type SessionCaptureRecordStore, readV2HeaderHints, type V2HeaderHints, LINEAGE_FILE, CHALLENGES_FILE, CHALLENGED_HISTORY_FILE, CHALLENGE_LEDGER_MAX_EVENTS, rebuildStrictControlPlaneLedger, type ControlPlaneRebuildReceipt, type StrictControlPlaneLedger, type ChallengeAssignment, type ChallengeEvent, type ChallengedHistoryRow, type LineagePendingTxn, type LineagePromotion, MEMORY_INDEX_FILENAME, MEMORY_INDEX_MAX_LINES, MEMORY_INDEX_MAX_BYTES, MEMORY_SEARCH_TOOL_NAME, MEMORY_GET_TOOL_NAME, MEMORY_INDEX_TOOL_NAME, MEMORY_ENGINE_TOOL_NAMES, type MemorySearchDetails, type MemorySearchHit, type CleanMemorySearchHit, type ExposedMemorySearchHit, MEMORY_EXPOSURE_BANNER, MEMORY_EXPOSURE_HANDLE_TAG, memoryExposureIndexRow, type MemoryGetDetails, type MemoryIndexDetails, type MemoryIndexRow, type CleanMemoryIndexRow, type ExposedMemoryIndexRow, STUB_ARCHIVED_LINE, DEFAULT_MAX_MEMORY_FILES, DEFAULT_MAX_ENTRY_DEPTH, DEFAULT_HARVEST_DEADLINE_MS, DEFAULT_HARVEST_FILE_BUDGET, MASS_DELETION_FUSE_RATIO, scanMemoryWrite, scanMemoryFileName, scanRemediation, MEMORY_FILENAME_SEGMENT_RE, renderAnnouncements, enqueueMemoryAnnouncement, drainMemoryAnnouncements, peekMemoryAnnouncements, bumpScanFuse, scanFuseCount, clearScanFuse, ANNOUNCEMENTS_FILE, MEMORY_ANNOUNCEMENTS_MAX, SCAN_FUSE_FILE, SCAN_FUSE_THRESHOLD, type MemoryAnnouncement, type ScanFinding, type MemoryEngineOptions, type MemoryInjection, type EntryProvenanceAccount, type TransferEvidence, type CommittedBinding, type CommittedEntrySnapshot, type CommittedScopeSnapshots, type EntryCustodyReport, erasureSelectHash, type EraseMemoryEntriesInput, type ErasureCarrierAnswer, type ErasureCarrierClass, type ErasureCountAnswer, type ErasureSelect, type ErasedBinding, type MemoryErasureAttestation, computeMemoryBundleHash, type MemoryExportBundle, type MemoryImportReport, type MemoryExportSnapshot, type MemoryBundleImportPlan, type BundleChallengeRow, type BundleLineageRow, type BundlePollutedSession, type MemoryBackend, type MemoryEntry, type MemoryEntryFrontmatter, type MemoryEntryHeader, type MemoryScopeEnumeration, type ScoredMemoryEntry, type NotePatch, type PatchReport, type MaterializedFile, type MemorySessionHandle, type HarvestReport, type HarvestRejection, type HarvestRejectionCode, type ParsedEntryFile, type ScannedEntryFile, SCOPE_SEGMENT_MAX_ENCODED, PROJECT_MARKER_PATH, encodeScopeSegment, decodeScopeSegment, parseScopeKey, formatUserScope, formatOrgScope, formatProjScope, formatUserProjScope, isPersonalScope, isOrgScopeKey, assertScopeContractPlacement, formatProjectMarker, parseProjectMarker, resolveProjectId, PROJECT_ID_REGEX, type ParsedScopeKey, migrateScope, type MigrateScopeReport, materializeEntriesToFiles, harvestFilesToPatches, projectionsToWriteBack, screenInboundEntries, REMOTE_HARVEST_PER_FILE_BYTES, REMOTE_MASS_DELETION_FUSE_RATIO, type RemoteMemoryFile, type RemoteMemoryBaseline, type RemoteMaterialization, type RemoteHarvestResult, type InboundEntryFinding, deriveProjectMemoryDir, deriveProjectControlDir, recordProjectIdHint, lookupProjectIdHint, PROJECT_ID_HINTS_FILE, reconcileMemoryEntries, nextSyncBaseline, mergeRecallHits, type MemorySyncCursor, type MemorySyncConflict, type MemorySyncPlan, type RecallSource, syncMemoryScope, memorySyncStoreOf, carriesCredential, type MemorySyncTransport, type MemorySyncRequestBody, type MemorySyncResponseBody, type MemorySyncClientConflict, type SyncMemoryScopeOptions, type MemorySyncClientResult, memorySyncReportOf, memoryTravelGapOf, type MemorySyncLayerReport, type MemorySyncRoundReport, } from "./core/memory-engine/index.js";
308
+ export { MemoryEngine, FileMemoryEngineBackend, readMemoryLedgerForm, memoryBackendContract, assertMemoryBackendSearchEquivalence, type MemoryBackendContractHooks, memoryGovernanceStoreContract, type MemoryGovernanceStoreContractHooks, buildMemoryInstruction, writableRootOf, truncateIndex, scanEntryFiles, deriveRepoKey, deriveRepoMemoryDir, deriveControlPlaneDir, deriveRepoControlPlaneDir, resolveMemoryEngineRoot, scopeDirName, ControlPlaneCorruptError, parseEntryFile, serializeEntryFile, computeEntryRev, entryFromFile, MEMORY_ORIGIN_CAUSES, committedOriginOf, originEquals, consolidationExposedFrontmatter, ambiguousOriginRepresentation, type OriginClearanceRow, type OriginClearanceEvent, type OriginClearanceShadow, committedDistilledOf, distilledEquals, type MemoryEntryDistilled, type MemoryEntryDistilledInput, CONSOLIDATION_DEFAULTS, ConsolidationRefusedError, MEMORY_SEARCH_SUPERSEDED_TAG, consolidationTypeEligible, deriveSupersededSet, memorySupersededNote, supersessionFuseCeiling, DELETION_FUSE_FLOOR, fileGovernanceStore, memoryGovernanceDurability, type MemoryGovernanceDurability, deriveShadowedSet, memoryConsolidationRecommendedNotice, memoryConsolidationCommittedNotice, memoryConsolidationConflictNotice, memoryConsolidationIncompleteNotice, memoryConsolidationRefusedNotice, memoryConsolidationWithheldNotice, type ConsolidationGateRead, type ConsolidationGateRow, type ConsolidationIntent, type ConsolidationIntentCredentialRow, type ConsolidationLeaseSeat, type ConsolidationProductProposal, type ConsolidationProposal, type ConsolidationWriteGate, type MemoryConsolidationOptions, type ConsolidationCommitReceipt, type ConsolidationReconcileReport, type ConsolidationResolveReceipt, type ConsolidationPlanSummary, type ConsolidationPlanFoldEvidence, type SessionMemoryStatus, DISTILLER_DEFAULT_MAX_INPUTS_PER_PRODUCT, LLM_DISTILLER_CONTRACT, LLM_DISTILLER_CONTRACT_DL2, LLM_DISTILLER_CONTRACT_DL3, LLM_DISTILLER_CONTRACTS, MEMORY_DISTILLER_CONTRACT_V1, contractGroupingDiff, driveConsolidationToFixpoint, isAliasModelId, llmPlanDistiller, mintExposurePartitionedPlan, mintLlmConsolidationPlan, MEMORY_DISTILLER_PURITY_CONTRACT_V1, detectCleanArmVerbatimLeak, type CleanArmLeakFinding, type CleanArmLeakVerdict, type MemoryDistillerPurityContract, openAiCompatChatSeat, parseJsonAnswer, planParseRepairs, sanitizeLlmGroups, scheduleUnderFuse, type ConsolidationDistillFn, type ConsolidationDriveCycleRow, type ConsolidationDriveEngine, type ConsolidationDriveResult, type ConsolidationFoldState, type DistillerCandidate, type DistillerChatAnswer, type DistillerChatFn, type DistillerChatRequest, type FuseSchedule, type LlmConsolidationPlan, type LlmConsolidationPlanArm, type LlmConsolidationPlanProduct, type LlmDistillerContract, type MintLlmConsolidationPlanResult, type PlanParseRepairs, type SanitizedLlmGroups, CONSOLIDATION_RUN_STOP_REASONS, CONSOLIDATION_WRITE_REFUSED_CODE, runMemoryConsolidationDriver, type ConsolidationDriverEngine, type ConsolidationDriverRunRow, type ConsolidationRunReceipt, type ConsolidationRunStopReason, type ConsolidationWriteJudge, type ConsolidationWriteTarget, type RunMemoryConsolidationOptions, isInstructionEntry, type MemoryEntryOrigin, type MemoryOriginCause, MEMORY_INSTRUCTION_TEMPLATE, MEMORY_RECALL_DISCIPLINE, MEMORY_PREFERENCE_DISCIPLINE, MEMORY_READONLY_NOTICE, MEMORY_CAPTURE_OPTOUT_NOTICE, memoryCaptureOptedOutNotice, memoryCaptureOptOutUnpersistedNotice, SESSION_CAPTURE_OPTOUT_DIR, markSessionCaptureOptOut, readSessionCaptureOptOut, listSessionCaptureOptOut, fileSessionCaptureRecordStore, type SessionCaptureOptOutRecord, type SessionCaptureOptOutMarkOutcome, type SessionCaptureRecordStore, readV2HeaderHints, type V2HeaderHints, LINEAGE_FILE, CHALLENGES_FILE, CHALLENGED_HISTORY_FILE, CHALLENGE_LEDGER_MAX_EVENTS, rebuildStrictControlPlaneLedger, type ControlPlaneRebuildReceipt, type StrictControlPlaneLedger, type ChallengeAssignment, type ChallengeEvent, type ChallengedHistoryRow, type LineagePendingTxn, type LineagePromotion, MEMORY_INDEX_FILENAME, MEMORY_INDEX_MAX_LINES, MEMORY_INDEX_MAX_BYTES, MEMORY_SEARCH_TOOL_NAME, MEMORY_GET_TOOL_NAME, MEMORY_INDEX_TOOL_NAME, MEMORY_ENGINE_TOOL_NAMES, type MemorySearchDetails, type MemorySearchHit, type CleanMemorySearchHit, type ExposedMemorySearchHit, MEMORY_EXPOSURE_BANNER, MEMORY_EXPOSURE_HANDLE_TAG, memoryExposureIndexRow, type MemoryGetDetails, type MemoryIndexDetails, type MemoryIndexRow, type CleanMemoryIndexRow, type ExposedMemoryIndexRow, STUB_ARCHIVED_LINE, DEFAULT_MAX_MEMORY_FILES, DEFAULT_MAX_ENTRY_DEPTH, DEFAULT_HARVEST_DEADLINE_MS, DEFAULT_HARVEST_FILE_BUDGET, MASS_DELETION_FUSE_RATIO, scanMemoryWrite, scanMemoryFileName, scanRemediation, MEMORY_FILENAME_SEGMENT_RE, renderAnnouncements, enqueueMemoryAnnouncement, drainMemoryAnnouncements, peekMemoryAnnouncements, bumpScanFuse, scanFuseCount, clearScanFuse, ANNOUNCEMENTS_FILE, MEMORY_ANNOUNCEMENTS_MAX, SCAN_FUSE_FILE, SCAN_FUSE_THRESHOLD, type MemoryAnnouncement, type ScanFinding, type MemoryEngineOptions, type MemoryInjection, type EntryProvenanceAccount, type TransferEvidence, type CommittedBinding, type CommittedEntrySnapshot, type CommittedScopeSnapshots, type EntryCustodyReport, erasureSelectHash, type EraseMemoryEntriesInput, type ErasureCarrierAnswer, type ErasureCarrierClass, type ErasureCountAnswer, type ErasureSelect, type ErasedBinding, type MemoryErasureAttestation, computeMemoryBundleHash, type MemoryExportBundle, type MemoryImportReport, type MemoryExportSnapshot, type MemoryBundleImportPlan, type BundleChallengeRow, type BundleLineageRow, type BundlePollutedSession, type MemoryBackend, type MemoryGovernanceStore, MEMORY_GOVERNANCE_DOC_NAMES, type MemoryGovernanceDocName, type MemoryGovernanceDocs, type ConsolidationTx, type MemoryEntry, type MemoryEntryFrontmatter, type MemoryEntryHeader, type MemoryScopeEnumeration, type ScoredMemoryEntry, type NotePatch, type PatchReport, type MaterializedFile, type MemorySessionHandle, type HarvestReport, type HarvestRejection, type HarvestRejectionCode, type ParsedEntryFile, type ScannedEntryFile, SCOPE_SEGMENT_MAX_ENCODED, PROJECT_MARKER_PATH, encodeScopeSegment, decodeScopeSegment, parseScopeKey, formatUserScope, formatUserLocalScope, formatOrgScope, formatProjScope, formatUserProjScope, isPersonalScope, isReplicableScope, isOrgScopeKey, assertScopeContractPlacement, formatProjectMarker, parseProjectMarker, resolveProjectId, PROJECT_ID_REGEX, type ParsedScopeKey, migrateScope, type MigrateScopeReport, materializeEntriesToFiles, harvestFilesToPatches, projectionsToWriteBack, screenInboundEntries, REMOTE_HARVEST_PER_FILE_BYTES, REMOTE_MASS_DELETION_FUSE_RATIO, type RemoteMemoryFile, type RemoteMemoryBaseline, type RemoteMaterialization, type RemoteHarvestResult, type InboundEntryFinding, deriveProjectMemoryDir, deriveProjectControlDir, recordProjectIdHint, lookupProjectIdHint, PROJECT_ID_HINTS_FILE, reconcileMemoryEntries, nextSyncBaseline, mergeRecallHits, type MemorySyncCursor, type MemorySyncConflict, type MemorySyncPlan, type RecallSource, syncMemoryScope, memorySyncStoreOf, carriesCredential, type MemorySyncTransport, type MemorySyncRequestBody, type MemorySyncResponseBody, type MemorySyncClientConflict, type SyncMemoryScopeOptions, type MemorySyncClientResult, memorySyncReportOf, memoryTravelGapOf, type MemorySyncLayerReport, type MemorySyncRoundReport, } from "./core/memory-engine/index.js";
308
309
  export { createConsolidationWriteJudge, deliverWriteRefusal, type ConsolidationWriteJudgeInput } from "./core/runner/memory-consolidation-write-judge.js";
309
310
  export { STORE_FORM_REFUSAL_CODES, TARGET_OUTSIDE_STORE, SCOPE_HOME_NOT_DIRECTORY, SCOPE_HOME_FORMS, type StoreFormRefusalCode, type StoreFormRefusalDetail, type StoreFormRefusal, type ScopeHomeForm } from "./core/memory-engine/layout.js";
310
311
  export { resolveMemoryScopeStore, type MemoryScopeStore, type MemoryScopeStoreInput } from "./core/memory-engine/dual-root.js";
311
- export { classifyScopePlanes, scopePlanesOf, type ScopePlanes } from "./core/memory-engine/dual-root.js";
312
+ export { classifyScopePlanes, memoryScopePlaneOf, scopePlanesOf, type ScopePlanes } from "./core/memory-engine/dual-root.js";
312
313
  export { createMemoryDeployment, type MemoryDeployment, type MemoryDeploymentInput, type MemoryDeploymentStore, type DeploymentSessionMemoryStatus, } from "./core/memory-engine/memory-deployment.js";
313
314
  export { reanchorMemoryStoreRoot, type StoreRootReanchor } from "./core/memory-engine/layout.js";
315
+ export { admittingLandings, cutPerLanding, LandingsNeedAdmission, MAX_LANDING_ADMISSION_ROUNDS, requireLandingsAdmitted, type AdmitLandings, type LandingCut, type PatchLanding, type PatchShare, } from "./core/memory-engine/landing-admission.js";
316
+ export { NON_GOVERNANCE_MEMORY_CODES } from "./core/governance-codes.js";
314
317
  export { SHARED_MEMORY_READ_CAP_BYTES, SHARED_MEMORY_LIST_PAGE_SIZE, SharedMemoryStoreError, type SharedMemoryStoreProvider, type SharedMemoryStoreReader, type SharedMemoryPagedList, type SharedMemoryStoreInfo, type SharedMemoryDocumentEntry, type SharedMemorySnapshot, type SharedMemoryRequestContext, type MemoryListDetails, type MemoryReadDetails, } from "./core/shared-memory/types.js";
315
318
  export { isSharedMemoryDocumentPath, isSharedMemoryStoreId } from "./core/shared-memory/normalize.js";
316
319
  export { sharedMemoryStoreContract, type SharedMemoryFixture, type SharedMemoryStoreContractHooks, } from "./core/shared-memory/contract.js";
@@ -383,7 +386,7 @@ export { readAgentState, agentStateSourceOfRecord, agentStateSummary, type Agent
383
386
  export type { TranscriptStep } from "./agents/subagent-steps.js";
384
387
  export type { UnifiedTaskResult } from "./core/task-registry-shared.js";
385
388
  export { TASK_OUTPUT_REPLAY_KINDS, type TaskOutputReplay } from "./core/task-registry-shared.js";
386
- export { REMOVAL_LIVENESS_WORDS, type RemovalLiveness, RULE_WRITE_COMMITTED_WORDS, type RuleWriteCommitted } from "./core/permission-rule-store.js";
389
+ export { REMOVAL_LIVENESS_WORDS, type RemovalLiveness, RULE_REFUSAL_CODES, type RuleRefusalCode, RULE_WRITE_COMMITTED_WORDS, type RuleWriteCommitted } from "./core/permission-rule-store.js";
387
390
  export { normalizeReadRootCandidate, READ_ROOT_CANDIDATE_DIR_MAX } from "./core/read-root-candidate.js";
388
391
  export { FileBackgroundAgentStore, type FileBackgroundAgentStoreOptions } from "./stores/file/background-agent-store.js";
389
392
  export { A2A_TASK_STATES, type A2ATaskState, type A2ATaskStateReversal, type A2ATaskStateReversalFaithful, type A2ATaskStateReversalLossy, toA2ATaskState, fromA2ATaskState, } from "./core/a2a-task-state.js";
package/dist/index.js CHANGED
@@ -98,6 +98,7 @@ export { confineShellStart } from "./core/shell-confinement.js";
98
98
  export { RemoteExecutionError, hasDestroy, isRemoteExecutionEnv, isSuspendable, isIsolated, canonicalPathIsAuthoritative, pathsAreHostLocal, keepsReadFloor, missingRestoreSurface, isRetryableRemoteErrorCode, RETRYABLE_REMOTE_ERROR_CODES, } from "./core/remote-env.js";
99
99
  export { withRetry } from "./core/with-retry.js";
100
100
  export { addWorktree, pruneWorktrees, WORKTREE_PARENT } from "./core/git-worktree-env.js";
101
+ export { probeWorktreeCapability, releaseSessionCheckout, WORKTREE_INCAPABLE_REASONS, } from "./core/session-checkout.js";
101
102
  export { runExecGate } from "./core/exec-gate.js";
102
103
  export { sanitizeUntrustedText, delimitUntrusted, inlineUntrusted, isMintableProbeReason } from "./core/untrusted-text.js";
103
104
  export { mintReminderMark, isValidReminderMark, openSystemReminder, mintSystemReminder, reminderMarkDeclaration } from "./core/reminder-mint.js";
@@ -225,20 +226,22 @@ export { AdoptionError, assertAdoptionBootGate, readRootAdoptionFile, writeRootA
225
226
  export { adoptLocalDataRoot, ackAdoptionConfig, witnessAdoptionConfig, listAdoptionQuarantine, readAdoptionStatus, } from "./stores/file/adoption/adopt.js";
226
227
  export { formatHookFeedback, runToolGate, createHookEnvCapabilities, normalizePersistedRuleHit, } from "./core/hooks.js";
227
228
  export { KERNEL_CONTRACT_VERSION, MOD_TIERS, MOD_SEATS, MOD_EVENT_SIDES, MOD_EVENT_TABLE, MODS_INVALID_CODE, MODS_REGISTRATION_REFUSED_CODE, } from "./core/mods/kernel/index.js";
228
- export { admitModChain } from "./core/mods/stations.js";
229
+ export { admitModChain, promptScreenDeclaredBy } from "./core/mods/stations.js";
229
230
  export { SESSION_APPEND_DOORS, SESSION_APPEND_ORIGIN_KINDS } from "./core/mods/session-append.js";
230
231
  export { SESSION_RECEIVE_ORIGIN_KINDS } from "./core/mods/session-receive.js";
231
232
  export { SESSION_SEND_ORIGIN_KINDS } from "./core/mods/session-send.js";
232
233
  export { loadModPackage } from "./core/mods/package.js";
233
234
  export { CREDENTIAL_REF_KINDS, CREDENTIAL_REF_TRUST, CREDENTIAL_REF_TEXT_MAX, CREDENTIAL_REF_MAP_MAX, CREDENTIAL_REF_PROBLEM_REASONS, readCredentialRef, } from "@sema-agent/primitives";
234
235
  export { InMemoryMemoryStore, composeMemoryBlock, composeLayeredMemoryBlock, normalizeMemorySpec, supportsConsolidation, supportsPeriodicConsolidation, firstSentence, expandLexicalTerms, lexicalSearchMatch, classifyPromotable, enforcePromotableWriteGate, guardedMemoryStore, MemoryGateError, MemoryProjectionError, detectSecret, enforceSecretWriteGate, enforceStructuredNoteSecretGate, MEMORY_PROJECT_KEY_ABSENT_REASONS, } from "./core/memory.js";
235
- export { MemoryEngine, FileMemoryEngineBackend, memoryBackendContract, assertMemoryBackendSearchEquivalence, buildMemoryInstruction, writableRootOf, truncateIndex, scanEntryFiles, deriveRepoKey, deriveRepoMemoryDir, deriveControlPlaneDir, deriveRepoControlPlaneDir, resolveMemoryEngineRoot, scopeDirName, ControlPlaneCorruptError, parseEntryFile, serializeEntryFile, computeEntryRev, entryFromFile, MEMORY_ORIGIN_CAUSES, committedOriginOf, originEquals, consolidationExposedFrontmatter, ambiguousOriginRepresentation, committedDistilledOf, distilledEquals, CONSOLIDATION_DEFAULTS, ConsolidationRefusedError, MEMORY_SEARCH_SUPERSEDED_TAG, consolidationTypeEligible, deriveSupersededSet, memorySupersededNote, readIntentCredentials, supersessionFuseCeiling, deriveShadowedSet, memoryConsolidationRecommendedNotice, memoryConsolidationCommittedNotice, memoryConsolidationConflictNotice, memoryConsolidationIncompleteNotice, memoryConsolidationRefusedNotice, memoryConsolidationWithheldNotice, DISTILLER_DEFAULT_MAX_INPUTS_PER_PRODUCT, LLM_DISTILLER_CONTRACT, LLM_DISTILLER_CONTRACT_DL2, LLM_DISTILLER_CONTRACT_DL3, LLM_DISTILLER_CONTRACTS, MEMORY_DISTILLER_CONTRACT_V1, contractGroupingDiff, driveConsolidationToFixpoint, isAliasModelId, llmPlanDistiller, mintExposurePartitionedPlan, mintLlmConsolidationPlan, MEMORY_DISTILLER_PURITY_CONTRACT_V1, detectCleanArmVerbatimLeak, openAiCompatChatSeat, parseJsonAnswer, planParseRepairs, sanitizeLlmGroups, scheduleUnderFuse, CONSOLIDATION_DRIVER_PLANS_DIR, CONSOLIDATION_DRIVER_RUNS_FILE, CONSOLIDATION_RUN_STOP_REASONS, CONSOLIDATION_WRITE_REFUSED_CODE, archiveDistillerPlan, readConsolidationDriverRun, runMemoryConsolidationDriver, isInstructionEntry, MEMORY_INSTRUCTION_TEMPLATE, MEMORY_RECALL_DISCIPLINE, MEMORY_PREFERENCE_DISCIPLINE, MEMORY_READONLY_NOTICE, MEMORY_CAPTURE_OPTOUT_NOTICE, memoryCaptureOptedOutNotice, memoryCaptureOptOutUnpersistedNotice, SESSION_CAPTURE_OPTOUT_DIR, markSessionCaptureOptOut, readSessionCaptureOptOut, listSessionCaptureOptOut, fileSessionCaptureRecordStore, readV2HeaderHints, LINEAGE_FILE, CHALLENGES_FILE, CHALLENGED_HISTORY_FILE, CHALLENGE_LEDGER_MAX_EVENTS, rebuildStrictControlPlaneLedger, MEMORY_INDEX_FILENAME, MEMORY_INDEX_MAX_LINES, MEMORY_INDEX_MAX_BYTES, MEMORY_SEARCH_TOOL_NAME, MEMORY_GET_TOOL_NAME, MEMORY_INDEX_TOOL_NAME, MEMORY_ENGINE_TOOL_NAMES, MEMORY_EXPOSURE_BANNER, MEMORY_EXPOSURE_HANDLE_TAG, memoryExposureIndexRow, STUB_ARCHIVED_LINE, DEFAULT_MAX_MEMORY_FILES, DEFAULT_MAX_ENTRY_DEPTH, DEFAULT_HARVEST_DEADLINE_MS, DEFAULT_HARVEST_FILE_BUDGET, MASS_DELETION_FUSE_RATIO, scanMemoryWrite, scanMemoryFileName, scanRemediation, MEMORY_FILENAME_SEGMENT_RE, renderAnnouncements, enqueueMemoryAnnouncement, drainMemoryAnnouncements, peekMemoryAnnouncements, bumpScanFuse, scanFuseCount, clearScanFuse, ANNOUNCEMENTS_FILE, MEMORY_ANNOUNCEMENTS_MAX, SCAN_FUSE_FILE, SCAN_FUSE_THRESHOLD, erasureSelectHash, computeMemoryBundleHash, SCOPE_SEGMENT_MAX_ENCODED, PROJECT_MARKER_PATH, encodeScopeSegment, decodeScopeSegment, parseScopeKey, formatUserScope, formatOrgScope, formatProjScope, formatUserProjScope, isPersonalScope, isOrgScopeKey, assertScopeContractPlacement, formatProjectMarker, parseProjectMarker, resolveProjectId, PROJECT_ID_REGEX, migrateScope, materializeEntriesToFiles, harvestFilesToPatches, projectionsToWriteBack, screenInboundEntries, REMOTE_HARVEST_PER_FILE_BYTES, REMOTE_MASS_DELETION_FUSE_RATIO, deriveProjectMemoryDir, deriveProjectControlDir, recordProjectIdHint, lookupProjectIdHint, PROJECT_ID_HINTS_FILE, reconcileMemoryEntries, nextSyncBaseline, mergeRecallHits, syncMemoryScope, memorySyncStoreOf, carriesCredential, memorySyncReportOf, memoryTravelGapOf, } from "./core/memory-engine/index.js";
236
+ export { MemoryEngine, FileMemoryEngineBackend, readMemoryLedgerForm, memoryBackendContract, assertMemoryBackendSearchEquivalence, memoryGovernanceStoreContract, buildMemoryInstruction, writableRootOf, truncateIndex, scanEntryFiles, deriveRepoKey, deriveRepoMemoryDir, deriveControlPlaneDir, deriveRepoControlPlaneDir, resolveMemoryEngineRoot, scopeDirName, ControlPlaneCorruptError, parseEntryFile, serializeEntryFile, computeEntryRev, entryFromFile, MEMORY_ORIGIN_CAUSES, committedOriginOf, originEquals, consolidationExposedFrontmatter, ambiguousOriginRepresentation, committedDistilledOf, distilledEquals, CONSOLIDATION_DEFAULTS, ConsolidationRefusedError, MEMORY_SEARCH_SUPERSEDED_TAG, consolidationTypeEligible, deriveSupersededSet, memorySupersededNote, supersessionFuseCeiling, DELETION_FUSE_FLOOR, fileGovernanceStore, memoryGovernanceDurability, deriveShadowedSet, memoryConsolidationRecommendedNotice, memoryConsolidationCommittedNotice, memoryConsolidationConflictNotice, memoryConsolidationIncompleteNotice, memoryConsolidationRefusedNotice, memoryConsolidationWithheldNotice, DISTILLER_DEFAULT_MAX_INPUTS_PER_PRODUCT, LLM_DISTILLER_CONTRACT, LLM_DISTILLER_CONTRACT_DL2, LLM_DISTILLER_CONTRACT_DL3, LLM_DISTILLER_CONTRACTS, MEMORY_DISTILLER_CONTRACT_V1, contractGroupingDiff, driveConsolidationToFixpoint, isAliasModelId, llmPlanDistiller, mintExposurePartitionedPlan, mintLlmConsolidationPlan, MEMORY_DISTILLER_PURITY_CONTRACT_V1, detectCleanArmVerbatimLeak, openAiCompatChatSeat, parseJsonAnswer, planParseRepairs, sanitizeLlmGroups, scheduleUnderFuse, CONSOLIDATION_RUN_STOP_REASONS, CONSOLIDATION_WRITE_REFUSED_CODE, runMemoryConsolidationDriver, isInstructionEntry, MEMORY_INSTRUCTION_TEMPLATE, MEMORY_RECALL_DISCIPLINE, MEMORY_PREFERENCE_DISCIPLINE, MEMORY_READONLY_NOTICE, MEMORY_CAPTURE_OPTOUT_NOTICE, memoryCaptureOptedOutNotice, memoryCaptureOptOutUnpersistedNotice, SESSION_CAPTURE_OPTOUT_DIR, markSessionCaptureOptOut, readSessionCaptureOptOut, listSessionCaptureOptOut, fileSessionCaptureRecordStore, readV2HeaderHints, LINEAGE_FILE, CHALLENGES_FILE, CHALLENGED_HISTORY_FILE, CHALLENGE_LEDGER_MAX_EVENTS, rebuildStrictControlPlaneLedger, MEMORY_INDEX_FILENAME, MEMORY_INDEX_MAX_LINES, MEMORY_INDEX_MAX_BYTES, MEMORY_SEARCH_TOOL_NAME, MEMORY_GET_TOOL_NAME, MEMORY_INDEX_TOOL_NAME, MEMORY_ENGINE_TOOL_NAMES, MEMORY_EXPOSURE_BANNER, MEMORY_EXPOSURE_HANDLE_TAG, memoryExposureIndexRow, STUB_ARCHIVED_LINE, DEFAULT_MAX_MEMORY_FILES, DEFAULT_MAX_ENTRY_DEPTH, DEFAULT_HARVEST_DEADLINE_MS, DEFAULT_HARVEST_FILE_BUDGET, MASS_DELETION_FUSE_RATIO, scanMemoryWrite, scanMemoryFileName, scanRemediation, MEMORY_FILENAME_SEGMENT_RE, renderAnnouncements, enqueueMemoryAnnouncement, drainMemoryAnnouncements, peekMemoryAnnouncements, bumpScanFuse, scanFuseCount, clearScanFuse, ANNOUNCEMENTS_FILE, MEMORY_ANNOUNCEMENTS_MAX, SCAN_FUSE_FILE, SCAN_FUSE_THRESHOLD, erasureSelectHash, computeMemoryBundleHash, MEMORY_GOVERNANCE_DOC_NAMES, SCOPE_SEGMENT_MAX_ENCODED, PROJECT_MARKER_PATH, encodeScopeSegment, decodeScopeSegment, parseScopeKey, formatUserScope, formatUserLocalScope, formatOrgScope, formatProjScope, formatUserProjScope, isPersonalScope, isReplicableScope, isOrgScopeKey, assertScopeContractPlacement, formatProjectMarker, parseProjectMarker, resolveProjectId, PROJECT_ID_REGEX, migrateScope, materializeEntriesToFiles, harvestFilesToPatches, projectionsToWriteBack, screenInboundEntries, REMOTE_HARVEST_PER_FILE_BYTES, REMOTE_MASS_DELETION_FUSE_RATIO, deriveProjectMemoryDir, deriveProjectControlDir, recordProjectIdHint, lookupProjectIdHint, PROJECT_ID_HINTS_FILE, reconcileMemoryEntries, nextSyncBaseline, mergeRecallHits, syncMemoryScope, memorySyncStoreOf, carriesCredential, memorySyncReportOf, memoryTravelGapOf, } from "./core/memory-engine/index.js";
236
237
  export { createConsolidationWriteJudge, deliverWriteRefusal } from "./core/runner/memory-consolidation-write-judge.js";
237
238
  export { STORE_FORM_REFUSAL_CODES, TARGET_OUTSIDE_STORE, SCOPE_HOME_NOT_DIRECTORY, SCOPE_HOME_FORMS } from "./core/memory-engine/layout.js";
238
239
  export { resolveMemoryScopeStore } from "./core/memory-engine/dual-root.js";
239
- export { classifyScopePlanes, scopePlanesOf } from "./core/memory-engine/dual-root.js";
240
+ export { classifyScopePlanes, memoryScopePlaneOf, scopePlanesOf } from "./core/memory-engine/dual-root.js";
240
241
  export { createMemoryDeployment, } from "./core/memory-engine/memory-deployment.js";
241
242
  export { reanchorMemoryStoreRoot } from "./core/memory-engine/layout.js";
243
+ export { admittingLandings, cutPerLanding, LandingsNeedAdmission, MAX_LANDING_ADMISSION_ROUNDS, requireLandingsAdmitted, } from "./core/memory-engine/landing-admission.js";
244
+ export { NON_GOVERNANCE_MEMORY_CODES } from "./core/governance-codes.js";
242
245
  export { SHARED_MEMORY_READ_CAP_BYTES, SHARED_MEMORY_LIST_PAGE_SIZE, SharedMemoryStoreError, } from "./core/shared-memory/types.js";
243
246
  export { isSharedMemoryDocumentPath, isSharedMemoryStoreId } from "./core/shared-memory/normalize.js";
244
247
  export { sharedMemoryStoreContract, } from "./core/shared-memory/contract.js";
@@ -306,7 +309,7 @@ export { canAccessAgentRecord, STALE_RUNNING_REAP_ATTRIBUTION, BackgroundAgentSt
306
309
  export { serveDurableAgentRowLane, buildAgentPollDetails, } from "./core/task-registry-agent.js";
307
310
  export { readAgentState, agentStateSourceOfRecord, agentStateSummary, } from "./core/agent-state.js";
308
311
  export { TASK_OUTPUT_REPLAY_KINDS } from "./core/task-registry-shared.js";
309
- export { REMOVAL_LIVENESS_WORDS, RULE_WRITE_COMMITTED_WORDS } from "./core/permission-rule-store.js";
312
+ export { REMOVAL_LIVENESS_WORDS, RULE_REFUSAL_CODES, RULE_WRITE_COMMITTED_WORDS } from "./core/permission-rule-store.js";
310
313
  export { normalizeReadRootCandidate, READ_ROOT_CANDIDATE_DIR_MAX } from "./core/read-root-candidate.js";
311
314
  export { FileBackgroundAgentStore } from "./stores/file/background-agent-store.js";
312
315
  export { A2A_TASK_STATES, toA2ATaskState, fromA2ATaskState, } from "./core/a2a-task-state.js";
@@ -9,7 +9,7 @@ export type { InvokedSkillRetention } from "../engine/compaction/utils.js";
9
9
  export type { AgentCoreRuntimeDeps } from "../engine/loop/runtime-deps.js";
10
10
  export type { LoopTerminalReason } from "../engine/loop/agent-loop.js";
11
11
  export type { AgentMessage, AgentTool, AgentToolResult, AgentToolUpdateCallback, ThinkingLevel, ToolExecutionMode, ToolInputValidationContext, ToolInputVerdict, } from "../engine/loop/types.js";
12
- export type { AgentHarnessEvent, CompactionSettings, ExecutionEnv, ExecutionErrorCode, FileError, FileKind, FileErrorCode, FileInfo, Result, WriteExpectation, WriteReceipt, SymlinkChain, BoundFileObject, Session, SessionMetadata, SessionRepo, SessionStorage, SessionTreeEntry, Skill, } from "../engine/harness/types.js";
12
+ export type { AgentHarnessEvent, CompactionSettings, ExecutionEnv, ExecutionErrorCode, FileError, FileKind, FileErrorCode, FileInfo, Result, WriteExpectation, WriteReceipt, SymlinkChain, BoundFileObject, Session, SessionCheckoutCell, SessionCheckoutDeclared, SessionCheckoutRecord, SessionCheckoutSource, SessionMetadata, SessionRepo, SessionStorage, SessionTreeEntry, Skill, } from "../engine/harness/types.js";
13
13
  export type { ExecutionEnvExecOptions, ExecResult, ReadFloor, ExecutionEnvCapabilities } from "../engine/harness/types.js";
14
14
  export type { SessionWriteOptions, CompactionEntry } from "../engine/harness/types.js";
15
15
  export type { RowAdmission, RowRaising } from "../engine/harness/types.js";
@@ -258,9 +258,12 @@ export interface RunWorkflowToolDeps {
258
258
  /** TRUSTED nesting depth from the run's internals (NOT a tool param) — passed to `startWorkflow` so a
259
259
  * cross-process child workflow is rejected by the one-level guard. */
260
260
  workflowDepth?: number;
261
- /** The HOST task's effective working root — threaded into every spawned agent's trusted internals so a
261
+ /** Where the HOST task writes (read at the spawn) — threaded into every spawned agent's trusted internals so a
262
262
  * TOC env factory can root the child at the parent's cwd (CC parity, 2026-07-03). */
263
263
  parentCwd?: string;
264
+ /** The HOST task's own task root — threaded beside {@link parentCwd} as `RunInternals.callerRoot`, the checkout a child's
265
+ * placement is judged against (whichever tree the host has switched to inside it). */
266
+ callerRoot?: string;
264
267
  /** The HOST task's own placement target (what its env reported as its workspace settled) — the fence every agent the
265
268
  * workflow spawns is minted under (`RunInternals.placementTarget`). Rides deps for the auto-mounted form (whose
266
269
  * execute ctx carries none); a rich ctx's own `placementTarget` wins. */
@@ -531,6 +531,7 @@ async function mountRunWorkflowTool(d) {
531
531
  maxResultChars: lim.maxResultChars ?? DEFAULTS.maxResultChars,
532
532
  maxLogChars: lim.maxLogChars ?? DEFAULTS.maxLogChars,
533
533
  ...(d.parentCwd !== undefined ? { parentCwd: d.parentCwd } : {}),
534
+ ...(d.callerRoot !== undefined ? { callerRoot: d.callerRoot } : {}),
534
535
  parentToolCallId: ctx.toolCallId,
535
536
  ...(sourceTaskId !== undefined ? { parentTaskId: sourceTaskId } : {}),
536
537
  ...((ctx.interactionPosture ?? d.parentInteractionPosture) !== undefined ? { interactionPosture: (ctx.interactionPosture ?? d.parentInteractionPosture) } : {}),
@@ -438,6 +438,9 @@ export interface RunWorkflowOptions {
438
438
  * (`RunInternals.parentCwd`) so a TOC env factory roots children at the parent's cwd (CC parity;
439
439
  * `isolation: "worktree"` on an individual agent wins over it). */
440
440
  parentCwd?: string;
441
+ /** The HOST task's own task root — `RunInternals.callerRoot` on both spawn legs, the checkout a child's placement is judged
442
+ * against (the host's {@link parentCwd} can sit in a tree inside it). Absent: the host's root is where it works ({@link parentCwd}). */
443
+ callerRoot?: string;
441
444
  /**
442
445
  * The SPAWNING tool call's id (`run_workflow`'s own `ToolExecuteContext.toolCallId`) — threaded into every
443
446
  * spawned agent's trusted internals (`RunInternals.parentToolCallId`) so each child's frames carry this id
@@ -26,6 +26,7 @@ import { namesEveryTool } from "../agents/tool-filter.js";
26
26
  import { definitionAllowTools, withDefinitionServers } from "../agents/inherited-tool-pool.js";
27
27
  import { snapshotAndValidateMcpEntries } from "../core/locked-config.js";
28
28
  import { compileOutputSchema } from "../core/runner/strict-output-schema.js";
29
+ import { callerPlacementSeats } from "../core/runner/child-tree.js";
29
30
  import { WorkflowBudgetExceededError, WorkflowNestingError, WorkflowAgentBlockedError, WorkflowAgentParkedError, WorkflowAgentSchemaError, WorkflowAgentStalledError, WorkflowMaxAgentsError, WORKFLOW_SPAWN_BLOCKED_ERROR_CODE } from "./workflow-types.js";
30
31
  import { WorkflowScriptError } from "./workflow-meta.js";
31
32
  import { firstByteLaneKnobMs, STALL_FIRST_BYTE_MS, STALL_FIRST_TOKEN_MS } from "../brain/timeout.js";
@@ -1893,7 +1894,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
1893
1894
  opts.onForwardEvent(e.type === "task_progress" || e.type === "task_started" ? { ...e, workflowRunId: runId, workflowAgentLabel: label } : e);
1894
1895
  }
1895
1896
  : undefined;
1896
- const baseInternals = { ...(agentOpts.isolation ? { isolation: agentOpts.isolation } : {}), ...(opts.parentCwd !== undefined ? { parentCwd: opts.parentCwd, callerRoot: opts.parentCwd } : {}), ...spawnAttribution, ...(await captureFloorSeatsNow()), ...(enrichedForward !== undefined ? { onForwardEvent: enrichedForward } : {}), delegationTaskType: "workflow", agentName: label, onWorkspaceResolved: createWorkspaceObserver(rec) };
1897
+ const baseInternals = { ...(agentOpts.isolation ? { isolation: agentOpts.isolation } : {}), ...(opts.parentCwd !== undefined ? { parentCwd: opts.parentCwd } : {}), ...callerPlacementSeats(opts.parentCwd, opts.callerRoot), ...spawnAttribution, ...(await captureFloorSeatsNow()), ...(enrichedForward !== undefined ? { onForwardEvent: enrichedForward } : {}), delegationTaskType: "workflow", agentName: label, onWorkspaceResolved: createWorkspaceObserver(rec) };
1897
1898
  let attempts = 0;
1898
1899
  let throttleRetried = false;
1899
1900
  let lastAttemptReason;
@@ -2285,6 +2286,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
2285
2286
  ...(inheritedModelRef !== undefined ? { inheritedModelRef } : {}),
2286
2287
  ...(agentOpts.isolation ? { isolation: agentOpts.isolation } : {}),
2287
2288
  ...(opts.parentCwd !== undefined ? { parentCwd: opts.parentCwd } : {}),
2289
+ ...callerPlacementSeats(opts.parentCwd, opts.callerRoot),
2288
2290
  ...spawnAttribution,
2289
2291
  ...(await captureFloorSeatsNow()),
2290
2292
  ...(enrichedForwardS !== undefined ? { onForwardEvent: enrichedForwardS } : {}),
@@ -343,7 +343,8 @@ export class FileSessionRepo {
343
343
  const id = options.id ?? uuidv7();
344
344
  const createdAt = new Date().toISOString();
345
345
  const path = this.pathFor(id);
346
- const meta = { id, createdAt, ...forkRowCells(await source.getMetadata(), options.owner) };
346
+ const placement = placementCellToWrite(options.placement, id, Date.now());
347
+ const meta = { id, createdAt, ...(placement !== undefined ? { placement } : {}), ...forkRowCells(await source.getMetadata(), options.owner) };
347
348
  const lines = [JSON.stringify({ kind: "meta", ...meta })];
348
349
  for (const entry of forked) {
349
350
  lines.push(JSON.stringify({ kind: "entry", entry }));
@@ -1,6 +1,6 @@
1
1
  import { SHELL_CONTROL_PREFIXES, argvOf, lexShellText } from "../../shell/lex.js";
2
2
  import { shellWordsOf } from "../../shell/shell-words.js";
3
- import { BLOCK_WORD_NAMES, LAUNCHER_NAMES, feedsArgvFromStdin, launcherOptionMovesBase, launcherOptionQueries, launcherOptionStep, launcherRunsShell, programRow, selectedOptions, streamDefaultProgram } from "./program-read-model.js";
3
+ import { BLOCK_WORD_NAMES, feedsArgvFromStdin, launcherOptionMovesBase, launcherOptionQueries, launcherOptionStep, launcherRunsShell, programRow, selectedOptions, streamDefaultProgram } from "./program-read-model.js";
4
4
  export const NOT_AUTO_ALLOWED = "— not auto-allowed";
5
5
  export function programBasename(word) {
6
6
  return word.includes("/") ? (word.split("/").pop() ?? word) : word;
@@ -106,7 +106,7 @@ export function readProgramPosition(words) {
106
106
  const owner = controlWords.length > 0 ? folded[controlWords[controlWords.length - 1]] : head;
107
107
  return none(written, assignments, optionShaped(owner, head));
108
108
  }
109
- if (!LAUNCHER_NAMES.has(basename)) {
109
+ if (launcherRowOf(basename) === undefined) {
110
110
  const glob = globProgramRefusal(i);
111
111
  if (glob !== undefined)
112
112
  return none(written, assignments, glob);
@@ -155,7 +155,7 @@ export function readProgramPosition(words) {
155
155
  ended.by = undefined;
156
156
  continue;
157
157
  }
158
- if (LAUNCHER_NAMES.has(wordBasename)) {
158
+ if (launcherRowOf(wordBasename) !== undefined) {
159
159
  launchers.push({ index: j, name: wordBasename });
160
160
  lastRow = launcherRowOf(wordBasename)?.launcher;
161
161
  if (launcherRunsShell(launcherRowOf(wordBasename), folded.slice(j + 1)))
@@ -2,7 +2,8 @@
2
2
  * The PROGRAM READ MODEL — one table that answers "what does this program do with its k-th word", and the readers
3
3
  * every shell face reads it through.
4
4
  *
5
- * A row is one program (the basename bash runs; a versioned spelling of an interpreter is its row), carrying every
5
+ * A row is one program (the basename bash runs; a spelling of its name the row declares — an interpreter's version, a GNU
6
+ * build's `g` — is its row), carrying every
6
7
  * argument fact the shell faces need: its option grammar (one per implementation where implementations disagree),
7
8
  * the ROLE each option value and each operand plays, whether a form walks a tree, how an interpreter receives the
8
9
  * program it runs, what a launcher steps over before the program it runs, which words a builtin keeps as shell text
@@ -305,6 +306,13 @@ export interface OperandSpec {
305
306
  readonly assignmentArguments?: "not-paths";
306
307
  /** The role of the LAST operand, unless an option delivered it ({@link OptionSpec.fillsLast}): a copy's destination. */
307
308
  readonly last?: ArgRole;
309
+ /** A LONE operand (no option delivering the last) is no destination: the program puts its copy / link in the working
310
+ * directory, under the operand's last segment (`ln -s dir/f` makes `./f`). Absent: a lone operand is the last. */
311
+ readonly loneOperand?: "into-working-directory";
312
+ /** Operands spelled `KEY=VALUE` (`dd if=… of=…`): the role of the VALUE of each key this table names — the operand is read
313
+ * in that role and its value is the path it names ({@link ArgEvent} `value`). An operand of a key the table does not name,
314
+ * or of no key, is an ordinary operand. */
315
+ readonly keyed?: Readonly<Record<string, ArgRole>>;
308
316
  /** What an ordinary operand becomes when an option selects editing in place ({@link OptionSpec.selects}). */
309
317
  readonly editedInPlace?: ArgRole;
310
318
  /** With fewer operands than this (the first-operand slot counted), the program reads its standard input; `always`:
@@ -400,10 +408,14 @@ export interface Subcommand {
400
408
  readonly operands?: OperandSpec;
401
409
  readonly traversal?: TraversalSpec;
402
410
  }
411
+ /** A spelling of a program's name, other than its row's key, that runs the row ({@link programRow}): `versioned` — the key with a
412
+ * trailing version (`python3`, `python3.11`); `gnu-prefixed` — the key behind a `g`, the name a GNU build is installed under
413
+ * beside the system's own implementation (`gln`, `gtimeout`), which runs the row's GNU grammar. */
414
+ export type ProgramSpelling = "versioned" | "gnu-prefixed";
403
415
  export interface ProgramRow {
404
416
  readonly key: string;
405
- /** A versioned spelling (`python3`, `python3.11`) is this row. */
406
- readonly versioned?: true;
417
+ /** The other spellings of the name that run this row ({@link ProgramSpelling}). */
418
+ readonly spellings?: readonly ProgramSpelling[];
407
419
  readonly grammars: readonly Grammar[];
408
420
  readonly operands?: OperandSpec;
409
421
  readonly traversal?: TraversalSpec;
@@ -437,12 +449,16 @@ export interface ProgramRow {
437
449
  readonly optionsComplete?: true;
438
450
  readonly witness: Witness;
439
451
  }
440
- /** The row bash runs for this basename: the exact key, or — for a row that declares versioned spellings — the name
441
- * with its trailing version dropped (`python3.11` is `python`). */
452
+ /** The row bash runs for this basename: the exact key, or a spelling of it the row declares ({@link ProgramRow.spellings}) —
453
+ * `python3.11` is `python`, `gln` is `ln` read by its GNU grammar. */
442
454
  export declare function programRow(name: string): ProgramRow | undefined;
455
+ /** The key of the row bash runs for this basename ({@link programRow}): what a table of programs is keyed by, so a spelling of
456
+ * a name (`gcp`) is the program it spells; the name itself where no row reads it. */
457
+ export declare function programKeyOf(name: string): string;
443
458
  /** Every row, in table order. */
444
459
  export declare function programRows(): readonly ProgramRow[];
445
- /** The launcher names — derived from the rows. */
460
+ /** The launcher rows' keys — derived from the rows (a name is read as a launcher by its row, {@link programRow}, spellings
461
+ * included). */
446
462
  export declare const LAUNCHER_NAMES: ReadonlySet<string>;
447
463
  /** The block words — derived from the rows. */
448
464
  export declare const BLOCK_WORD_NAMES: ReadonlySet<string>;
@@ -610,7 +626,8 @@ type Event<R> =
610
626
  readonly unsettled?: true;
611
627
  }
612
628
  /** An operand, the `ordinal`-th. `slot` = the first-operand slot's role when the slot applies; `role` = the role the
613
- * row declares for an operand at this position past the slot (a URL, a name it only examines); `dash` = the word is
629
+ * row declares for an operand at this position past the slot (a URL, a name it only examines), or for a `KEY=VALUE`
630
+ * operand by its key — whose `value` is then the text after the `=` ({@link OperandSpec.keyed}); `dash` = the word is
614
631
  * a lone `-`, read as standard input (`stdin`) or as a file name. */
615
632
  | {
616
633
  readonly kind: "operand";
@@ -618,6 +635,7 @@ type Event<R> =
618
635
  readonly ordinal: number;
619
636
  readonly slot?: ArgRole;
620
637
  readonly role?: ArgRole;
638
+ readonly value?: string;
621
639
  readonly dash?: "stdin" | "file";
622
640
  };
623
641
  export type ArgEvent = Event<ArgRole>;
@@ -757,8 +775,13 @@ export type WritingRole = Extract<ArgRole, {
757
775
  }>;
758
776
  /** Does this role write its path ({@link WRITING_EFFECTS})? */
759
777
  export declare function writesPath(role: ArgRole | undefined): role is WritingRole;
778
+ /** The programs whose OPERANDS the table says they write — a row whose ordinary or last operands take a writing role, a
779
+ * `KEY=VALUE` operand of a writing key (named by its key: `dd's of=`), an operand an in-place edit rewrites (`an in-place
780
+ * sed`) — in table order, as a sentence names them. The write face's refusal note reads it: the sentence names what the
781
+ * station judges by, never a list of its own. */
782
+ export declare function operandWriterNames(): readonly string[];
760
783
  /** One word an implementation's reading writes: its argv index, the value inside it when an option carries it
761
- * attached, and the role it is written by. */
784
+ * attached (or a `KEY=VALUE` operand after its key), and the role it is written by. */
762
785
  export interface WrittenWord {
763
786
  readonly at: number;
764
787
  readonly value?: string;
@@ -776,9 +799,10 @@ export interface WriteReading {
776
799
  readonly unexplained: boolean;
777
800
  /** The backup suffixes an option selecting edit-in-place was given (empty values dropped: no backup). */
778
801
  readonly suffixes: readonly string[];
779
- /** A copy's destination (argv index, and its value when an option carries it attached) and its sources. */
802
+ /** A copy's destination (argv index, and its value when an option carries it attached) and its sources; no destination:
803
+ * the working directory ({@link OperandSpec.loneOperand}). */
780
804
  readonly copy?: {
781
- readonly destination: {
805
+ readonly destination?: {
782
806
  readonly at: number;
783
807
  readonly value?: string;
784
808
  };
@@ -7,13 +7,24 @@ export const ARG_ROLE_KINDS = Object.freeze(["path", "mount-source", "object-pat
7
7
  export const PATH_EFFECTS = Object.freeze(["read", "names", "write", "create", "edit-in-place"]);
8
8
  export const WRITING_EFFECTS = new Set(["write", "create", "edit-in-place"]);
9
9
  const ROWS_BY_KEY = new Map(PROGRAM_ROWS.map((r) => [r.key, r]));
10
+ const SPELLING_FORMS = [
11
+ { form: "versioned", keyOf: (name) => name.replace(/\d+(?:\.\d+)*$/, ""), runs: (row) => row },
12
+ { form: "gnu-prefixed", keyOf: (name) => name.replace(/^g/, ""), runs: (row) => implementationsOf(row).find((view) => view.grammars[0]?.dialect === "gnu") ?? row },
13
+ ];
10
14
  export function programRow(name) {
11
15
  const exact = ROWS_BY_KEY.get(name);
12
16
  if (exact !== undefined)
13
17
  return exact;
14
- const stripped = name.replace(/\d+(?:\.\d+)*$/, "");
15
- const row = stripped === name ? undefined : ROWS_BY_KEY.get(stripped);
16
- return row?.versioned === true ? row : undefined;
18
+ for (const { form, keyOf, runs } of SPELLING_FORMS) {
19
+ const key = keyOf(name);
20
+ const row = key === name ? undefined : ROWS_BY_KEY.get(key);
21
+ if (row?.spellings?.includes(form) === true)
22
+ return runs(row);
23
+ }
24
+ return undefined;
25
+ }
26
+ export function programKeyOf(name) {
27
+ return programRow(name)?.key ?? name;
17
28
  }
18
29
  export function programRows() {
19
30
  return PROGRAM_ROWS;
@@ -510,12 +521,20 @@ function walkArgs(row, words, readOption, slot, readsRole, ownedValue) {
510
521
  }
511
522
  const inSlot = slot !== undefined && !slotSupplied && !sawOperand;
512
523
  sawOperand = true;
513
- const declared = inSlot ? undefined : slot !== undefined ? row?.operands?.positional?.[slotSupplied ? ordinal + 1 : ordinal] ?? row?.operands?.rest : row?.operands?.rest;
524
+ const keyed = inSlot ? undefined : keyedOperandOf(row, t);
525
+ const declared = keyed !== undefined ? keyed.role : inSlot ? undefined : slot !== undefined ? row?.operands?.positional?.[slotSupplied ? ordinal + 1 : ordinal] ?? row?.operands?.rest : row?.operands?.rest;
514
526
  const role = declared !== undefined && readsRole(declared) ? declared : undefined;
515
- out.push({ kind: "operand", at: k, ordinal: ordinal++, ...(inSlot ? { slot: slot.role } : {}), ...(role !== undefined ? { role } : {}), ...(t === "-" ? { dash: dashRead } : {}) });
527
+ out.push({ kind: "operand", at: k, ordinal: ordinal++, ...(inSlot ? { slot: slot.role } : {}), ...(role !== undefined ? { role, ...(keyed !== undefined ? { value: keyed.value } : {}) } : {}), ...(t === "-" ? { dash: dashRead } : {}) });
516
528
  }
517
529
  return out;
518
530
  }
531
+ function keyedOperandOf(row, word) {
532
+ const table = row?.operands?.keyed;
533
+ const eq = word.indexOf("=");
534
+ if (table === undefined || eq <= 0 || !Object.hasOwn(table, word.slice(0, eq)))
535
+ return undefined;
536
+ return { role: table[word.slice(0, eq)], value: word.slice(eq + 1) };
537
+ }
519
538
  export function readArgs(row, words, opts) {
520
539
  const slot = opts.firstOperandSlot === false ? undefined : firstOperandSlot(row);
521
540
  const owned = opts.ownedValues === true && row?.traversal?.discloses === "contents"
@@ -879,6 +898,15 @@ export function rowRefusesArgv(row, args) {
879
898
  export function writesPath(role) {
880
899
  return role?.kind === "path" && WRITING_EFFECTS.has(role.effect);
881
900
  }
901
+ export function operandWriterNames() {
902
+ const writes = (r) => writesPath(r.operands?.rest) || writesPath(r.operands?.last);
903
+ const keys = (r) => Object.entries(r.operands?.keyed ?? {}).flatMap(([k, role]) => (writesPath(role) ? [`${k}=`] : []));
904
+ return [
905
+ ...PROGRAM_ROWS.filter(writes).map((r) => r.key),
906
+ ...PROGRAM_ROWS.flatMap((r) => (keys(r).length > 0 ? [`${r.key}'s ${keys(r).join(" ")}`] : [])),
907
+ ...PROGRAM_ROWS.filter((r) => writesPath(r.operands?.editedInPlace)).map((r) => `an in-place ${r.key}`),
908
+ ];
909
+ }
882
910
  export function writeReadings(row, args) {
883
911
  return implementationsOf(row).map((view) => {
884
912
  const ops = view.operands;
@@ -906,7 +934,7 @@ export function writeReadings(row, args) {
906
934
  continue;
907
935
  const role = e.role ?? ordinary;
908
936
  if (writesPath(role))
909
- written.push({ at: e.at, role });
937
+ written.push({ at: e.at, ...(e.value !== undefined ? { value: e.value } : {}), role });
910
938
  }
911
939
  else if (e.kind === "dash-word-operand") {
912
940
  if (writesPath(ordinary))
@@ -918,7 +946,9 @@ export function writeReadings(row, args) {
918
946
  if (writesPath(last)) {
919
947
  const filled = scan.values.filter((v) => v.spec.fillsLast === true).at(-1);
920
948
  const destination = filled !== undefined ? { at: filled.at, ...(filled.value !== undefined ? { value: filled.value } : {}) } : scan.operands.length > 0 ? { at: scan.operands.at(-1) } : undefined;
921
- if (destination !== undefined) {
949
+ if (filled === undefined && scan.operands.length === 1 && ops?.loneOperand === "into-working-directory")
950
+ copy = { sources: scan.operands };
951
+ else if (destination !== undefined) {
922
952
  copy = { destination, sources: scan.operands.filter((at) => at !== destination.at) };
923
953
  for (let i = written.length - 1; i >= 0; i--)
924
954
  if (written[i].at === destination.at && written[i].value === destination.value)
@@ -35,6 +35,8 @@ const file = (language) => ({ kind: "program-file", language });
35
35
  const WALKS = { walks: true };
36
36
  const REBASES = { rebases: true };
37
37
  const SWITCH = { arity: 0 };
38
+ const SWITCH_NONE = { arity: 0, effect: "none" };
39
+ const SWITCH_WRITES = { arity: 0, effect: "writes" };
38
40
  const QUERY = { arity: 0, mode: "queries" };
39
41
  const val = (value, extra = {}) => ({ arity: 1, ...(value !== undefined ? { value } : {}), ...extra });
40
42
  const optional = (value) => ({ arity: "attached", ...(value !== undefined ? { value } : {}) });
@@ -312,7 +314,7 @@ function interpreterGrammar(language, g) {
312
314
  }
313
315
  const interpreter = (key, language, g, program, stdinWhenUnnamed, extra = {}, departures) => ({
314
316
  key,
315
- versioned: true,
317
+ spellings: ["versioned"],
316
318
  grammars: departures === undefined ? [interpreterGrammar(language, g)] : implementations(interpreterGrammar(language, g), departures.gnu, departures.bsd),
317
319
  ...(program === "none" ? {} : { operands: { positional: program === "file" ? [file(language)] : program === "text" ? [text(language)] : [undefined, text(language)] } }),
318
320
  delivery: { stdinWhenUnnamed },
@@ -656,6 +658,10 @@ const writerRows = [
656
658
  { key: "tee", grammars: [], operands: { rest: WRITE_THROUGH, dash: "file" }, witness: BINARY },
657
659
  { key: "cp", grammars: copyGrammars(true, COPY_DESTINATION), operands: { rest: COPY_SOURCE, last: COPY_DESTINATION, dash: "file" }, witness: BINARY },
658
660
  { key: "mv", grammars: copyGrammars(false, MOVE_DESTINATION), operands: { rest: MOVE_SOURCE, last: MOVE_DESTINATION, dash: "file" }, witness: BINARY },
661
+ { key: "truncate", grammars: implementations(grammar({ c: SWITCH_NONE, o: SWITCH_NONE, r: val(READ, { effect: "none" }), s: val(LABEL, { effect: "none" }) }, { "no-create": SWITCH_NONE, "io-blocks": SWITCH_NONE, reference: val(READ, { effect: "none" }), size: val(LABEL, { effect: "none" }), ...BANNERS }), { afterFirstOperand: "options" }, { lacks: ["-o", "--no-create", "--io-blocks", "--reference", "--size", "--help", "--version"], afterFirstOperand: "operands" }), operands: { rest: WRITE, dash: "file" }, witness: BINARY },
662
+ { key: "dd", grammars: implementations(grammar({}, { ...BANNERS }), {}, { lacks: ["--help", "--version"] }), operands: { keyed: { if: READ, of: WRITE_THROUGH } }, witness: BINARY },
663
+ { key: "install", grammars: implementations(grammar({ b: SWITCH_WRITES, c: SWITCH_NONE, C: SWITCH_NONE, d: SWITCH_WRITES, D: SWITCH_NONE, g: val(LABEL, { effect: "none" }), m: val(LABEL, { effect: "none" }), o: val(LABEL, { effect: "none" }), p: SWITCH_NONE, s: SWITCH, v: SWITCH_NONE, t: val(MOVE_DESTINATION, { fillsLast: true }), S: val(LABEL, { effect: "writes" }), T: SWITCH_NONE }, { backup: { arity: "attached", value: LABEL, effect: "writes" }, compare: SWITCH_NONE, directory: SWITCH_WRITES, group: val(LABEL, { effect: "none" }), mode: val(LABEL, { effect: "none" }), owner: val(LABEL, { effect: "none" }), "preserve-timestamps": SWITCH_NONE, strip: SWITCH, suffix: val(LABEL, { effect: "writes" }), "target-directory": val(MOVE_DESTINATION, { fillsLast: true }), "no-target-directory": SWITCH_NONE, verbose: SWITCH_NONE, ...BANNERS }), { afterFirstOperand: "options" }, { lacks: ["-t", "--backup", "--compare", "--directory", "--group", "--mode", "--owner", "--preserve-timestamps", "--strip", "--suffix", "--target-directory", "--no-target-directory", "--verbose", "--help", "--version"], reads: { "-S": SWITCH_NONE, "-T": val(LABEL, { effect: "none" }), "-D": val(LABEL, { effect: "none" }) }, afterFirstOperand: "operands" }), operands: { rest: READ, last: MOVE_DESTINATION, dash: "file" }, witness: BINARY },
664
+ { key: "ln", grammars: implementations(grammar({ b: SWITCH_WRITES, d: SWITCH_NONE, F: SWITCH, f: SWITCH_NONE, i: SWITCH_NONE, L: SWITCH_NONE, n: SWITCH_NONE, P: SWITCH_NONE, r: SWITCH_NONE, s: SWITCH_NONE, v: SWITCH_NONE, h: SWITCH_NONE, w: SWITCH_NONE, t: val(MOVE_DESTINATION, { fillsLast: true }), S: val(LABEL, { effect: "writes" }), T: SWITCH_NONE }, { backup: { arity: "attached", value: LABEL, effect: "writes" }, directory: SWITCH_NONE, force: SWITCH_NONE, interactive: SWITCH_NONE, logical: SWITCH_NONE, "no-dereference": SWITCH_NONE, physical: SWITCH_NONE, relative: SWITCH_NONE, symbolic: SWITCH_NONE, suffix: val(LABEL, { effect: "writes" }), "target-directory": val(MOVE_DESTINATION, { fillsLast: true }), "no-target-directory": SWITCH_NONE, verbose: SWITCH_NONE, ...BANNERS }), { lacks: ["-h", "-w"], afterFirstOperand: "options" }, { lacks: ["-b", "-d", "-r", "-t", "-S", "-T", "--backup", "--directory", "--force", "--interactive", "--logical", "--no-dereference", "--physical", "--relative", "--symbolic", "--suffix", "--target-directory", "--no-target-directory", "--verbose", "--help", "--version"], afterFirstOperand: "operands" }), operands: { rest: NAMES, last: MOVE_DESTINATION, loneOperand: "into-working-directory", dash: "file" }, witness: BINARY },
659
665
  ];
660
666
  const stdinReaders = [
661
667
  { key: "cat", grammars: [], operands: { stdinBelow: 1 }, witness: BINARY },
@@ -665,6 +671,11 @@ const stdinReaders = [
665
671
  const SYNTAX = { declared: "shell syntax, not a program: read by the lexer" };
666
672
  const block = (key, g = []) => ({ key, grammars: g, syntax: "block", witness: SYNTAX });
667
673
  const BLOCK_GRAMMARS = { "[[": [grammar({ v: val(BINDS_NAME) })] };
674
+ const GNU_COREUTILS = new Set([
675
+ "[", "basename", "cat", "chroot", "comm", "cp", "cut", "date", "dd", "dirname", "du", "echo", "env", "expr", "false", "groups", "head", "id", "install", "ln", "ls", "mkdir", "mv",
676
+ "nice", "nohup", "nproc", "printf", "pwd", "rm", "rmdir", "seq", "sleep", "stdbuf", "tail", "tee", "test", "timeout", "touch", "tr", "true", "truncate", "uname", "wc", "whoami",
677
+ ]);
678
+ const spelledByGnuBuilds = (row) => (GNU_COREUTILS.has(row.key) ? { ...row, spellings: [...(row.spellings ?? []), "gnu-prefixed"] } : row);
668
679
  export const PROGRAM_ROWS = [
669
680
  head, tail, cut, grepRow("grep"), grepRow("egrep"), grepRow("fgrep"), diff, cmp, sed, date, tar, find, curl,
670
681
  ls, namesWalker("du"), rg, namesWalker("tree"), ag, ack,
@@ -710,4 +721,4 @@ export const PROGRAM_ROWS = [
710
721
  shellRow("fc", "history", BUILTIN_ONLY, [grammar({ ...switches("nr"), s: { arity: 0, effect: "executes" }, ...switches("l", { mode: "banner" }), e: val(COMMAND, { executesWhenValue: "-" }) }, {}, { afterFirstOperand: "operands" })]),
711
722
  ...codeBodyRows,
712
723
  ...[...shellWordsOf("block")].map((k) => block(k, BLOCK_GRAMMARS[k])),
713
- ];
724
+ ].map(spelledByGnuBuilds);
@@ -167,6 +167,10 @@ export interface WriteDenyMatcher {
167
167
  }): ReadDenyHit | null;
168
168
  /** The table ONE call judges with ({@link ReadDenyMatcher.forCall}). */
169
169
  forCall?(toolCallId: string | undefined): WriteDenyMatcher;
170
+ /** Is the row a hit named (its rule text) a row that guards the READ face too — a `Read(…)` rule on the write face, whose
171
+ * paths are not written because their reads are denied — rather than a row of the write face alone? The refusal's sentence
172
+ * says which of the two refused ({@link readDenySentence}'s `readRow`). Absent ⇒ no row of this table guards reads. */
173
+ guardsReads?(pattern: string): boolean;
170
174
  }
171
175
  /** Compile the write face over the rule rows (the rows not on it are dropped here, once). */
172
176
  export declare function compileWriteDeny(rules?: readonly PathRuleDenyRow[]): WriteDenyMatcher;
@@ -288,6 +292,8 @@ export declare function sensitivePathDenyList(pattern: string | readonly string[
288
292
  export declare const SENSITIVE_PATH_DENY_SCOPE = "This list guards credential-class paths and applies regardless of the containment roots.";
289
293
  /** The write face's reach, in the same place of the sentence: a write deny row holds under every root and every mode. */
290
294
  export declare const WRITE_DENY_SCOPE = "A write deny row holds regardless of the containment roots and of the permission mode.";
295
+ /** The same place, for a write refused by a row of the READ face (a `Read(…)` rule): it holds on writes as it holds on reads. */
296
+ export declare const READ_ROW_WRITE_SCOPE = "A read deny row holds on writes too, regardless of the containment roots and of the permission mode.";
291
297
  /**
292
298
  * THE deny refusal sentence — five segments, one mint, every read face: the ACTION, the ABSOLUTE target as the
293
299
  * caller spelled it (with its canonical target in parentheses when the two differ), the DISPOSITION (a deny row is
@@ -296,7 +302,9 @@ export declare const WRITE_DENY_SCOPE = "A write deny row holds regardless of th
296
302
  * when that is the requested SPELLING rather than the target — under a symlink or case alias the two strings
297
303
  * differ, only one matches, and naming the other sends the reader chasing a path the pattern does not match.
298
304
  * A face prefixes its own `Error (<tool>): ` and may append its own closing clause; the finding itself is
299
- * never re-spelled.
305
+ * never re-spelled. One variant, by the row's family and not by the face alone: a write refused by a `Read(…)` row
306
+ * ({@link WriteDenyMatcher.guardsReads}) says the path's reads are denied, where a row of the write face alone says the
307
+ * write list.
300
308
  */
301
309
  export declare function readDenySentence(finding: {
302
310
  readonly action?: string;
@@ -306,6 +314,10 @@ export declare function readDenySentence(finding: {
306
314
  readonly matchedView?: string;
307
315
  /** The table face that refused (default `read`): a write-face hit names the write list and its reach, and writes. */
308
316
  readonly face?: DenyFace;
317
+ /** On the write face: the row that refused is a row of the READ face too ({@link WriteDenyMatcher.guardsReads}) — a
318
+ * `Read(…)` rule, not a rule about writing. The sentence then says the path's reads are denied, which is why it is not
319
+ * written, instead of calling a read row a write deny row. */
320
+ readonly readRow?: true;
309
321
  }): string;
310
322
  /** The per-part budget of the deny sentence — the gate's own card-account cap, not a second number. */
311
323
  export declare const READ_DENY_SENTENCE_PART_MAX = 200;