@sema-agent/core 7.30.1 → 7.31.1

package/dist/core/task-spec.d.ts

@@ -213,12 +213,12 @@ export interface TaskSpec {
      *   that could support this without a second root is a recorded design candidate, not built.)
      *
      * File-history interaction (design/381): with {@link restoreFiles}, the `"before"` file anchor is the
-     * target's OWN entry id first — history boundaries are keyed by a turn's initial entry and mean "file
-     * state when that turn began", so B(target) IS the before-state. When the target carries no boundary
-     * (a mixed-epoch session, or a non-turn-initial target), the anchor falls back to the nearest
-     * boundary-carrying ANCESTOR, so files and context land on the same side of the cut. If no such
-     * boundary exists, prepare fails loud (`rewind_snapshot.unresolvable`) instead of silently leaving
-     * the files at their pre-rewind state while the conversation moved back.
+     * target's OWN entry id — history boundaries are keyed by a turn's initial entry and mean "file state
+     * when that turn began", so B(target) IS the before-state. A target with no boundary of its own (a
+     * steer / follow-up entry, a turn that recorded no history, a mixed-epoch session) refuses at prepare
+     * (`rewind_snapshot.unresolvable`) with the files untouched: an earlier boundary would also revert edits
+     * the conversation keeps, so the anchor never falls back to an ancestor and never crosses into an
+     * earlier turn.
      * Fail-loud: setting this without {@link resumeAt}, or an unknown mode value, rejects at prepare.
      */
     resumeAtMode?: "at" | "before";
@@ -311,6 +311,15 @@ export interface TaskSpec {
         count?: number;
         role?: ModelRole;
     };
+    /**
+     * The per-run OFF SWITCH for file history (`"disabled"`, the only word; `checkpointStore`'s spelling). Omitted ⇒
+     * the deployment (`RunnerDeps.fileHistoryStore` / `fileHistoryCapture`) decides. `"disabled"` ⇒ this run makes no history-store call: no first-touch record
+     * (the edit proceeds), no turn boundary, no fork carry, no liveness advisory; a restore request ({@link restoreFiles}
+     * / {@link rewindFilesTo}) refuses `rewind.capture_disabled` (the store may be wired; the request turned it off).
+     * The manifest reports `fileHistory: "disabled"`. Children inherit it (parent spec seat; a retained child woken by
+     * such a run, for that cycle); no word turns it back on below. Any other value refuses (`rewind.invalid_spec`).
+     */
+    fileHistory?: "disabled";
     /**
      * design/381 (DV-9) — the RESTORE half of file rewind: when this task uses {@link resumeAt} to branch at
      * a prior entry, ALSO converge the working tree's **agent-edited files** (the tracked set — files this
@@ -323,8 +332,8 @@ export interface TaskSpec {
      * Fail-loud: setting this without {@link resumeAt} rejects at prepare (`rewind.invalid_spec`) — a
      * restore with no anchor is a contradiction, not a default.
      *
-     * There is NO capture flag anymore: first-touch tracking is ALWAYS ON whenever a
-     * `RunnerDeps.fileHistoryStore` is wired (per-edited-file backups are near-zero cost — no tree walk,
+     * There is NO capture request anymore: first-touch tracking is ON whenever a `RunnerDeps.fileHistoryStore`
+     * is wired, `RunnerDeps.fileHistoryCapture` is not `"off"`, and no {@link fileHistory} off switch is set (per-edited-file backups are near-zero cost — no tree walk,
      * no size gate), which is what retired the old `rewindFiles` capture request. The retired
      * `rewindFiles` spelling is handled at prepare: its capture sense (true, no `resumeAt`) is a
      * tolerated no-op with a deprecation disclosure (the intent is structurally satisfied); its restore

package/dist/core/tool-spec.d.ts

@@ -752,7 +752,7 @@ export interface ToolExecuteContext {
     parentCwd?: string;
     /**
      * The RUNNING task's file-history LINEAGE (Runner-filled, read-only, never a model/tool argument;
-     * present iff a `RunnerDeps.fileHistoryStore` is live for the run): the history scope this run
+     * present iff the run records file history — a `RunnerDeps.fileHistoryStore` wired, capture not `"off"`, not `"disabled"`): the history scope this run
      * records its first-touch edits into and the TREE those records' keys are minted against — the
      * canonical root spelling plus the env's filesystem identity (`fs`: a remote workspace's handle,
      * `"host"` for the control-plane host's filesystem, else a per-env-instance token).

package/dist/core/wiring-manifest.d.ts

@@ -407,6 +407,14 @@ export interface WiringManifest {
     autoConsolidation?: {
         onRecommendation: true;
     };
+    /**
+     * EFFECTIVE half only, ALWAYS present on an engine-minted effective manifest: does this leg capture file history.
+     * `"on"` — it records (store wired, neither layer declared it off, a filesystem env mounted). `"disabled"` — it does
+     * not, whichever layer or missing half made it so (`TaskSpec.fileHistory`, `RunnerDeps.fileHistoryStore: "disabled"`, `RunnerDeps.fileHistoryCapture: "off"`,
+     * no store, no filesystem env); the host knows its own deployment seat. ABSENT = an older mint or an external
+     * derivation, never a state. Out of {@link configFingerprint}: the request word is a per-task seat (`hooks` reasoning).
+     */
+    fileHistory?: "on" | "disabled";
     /** EFFECTIVE half only — a short, non-sensitive fingerprint (sha256 prefix over the canonical
      *  JSON of this manifest's own resolved facts; every field here is an enum/boolean/count, no
      *  secrets) so an operator can correlate legs that ran under the same resolved assembly. */
@@ -498,6 +506,8 @@ export interface WiringFacts {
     /** Effective half only — `RunnerDeps.autoRunOnRecommendation === true`
      *  ({@link WiringManifest.autoConsolidation}); false ⇒ no section (byte-identical manifest). */
     autoConsolidationOnRecommendation?: boolean;
+    /** Effective half only — the file-history phase's word ({@link WiringManifest.fileHistory}); the engine always passes it. */
+    fileHistory?: "on" | "disabled";
 }
 /** Named view of the deps seats the static half reads (a `Pick` of the real {@link RunnerDeps} —
  *  single-source shapes, no parallel hand-copied interface). */

package/dist/core/wiring-manifest.js

@@ -84,6 +84,11 @@ function readAutoModeFact(fact) {
     }
     return { armed, reason, ...(deniedSource !== undefined ? { deniedSource } : {}) };
 }
+function readFileHistoryFact(word) {
+    if (word !== "on" && word !== "disabled")
+        throw new Error(`the file-history wiring fact ${JSON.stringify(word)} is not one of on|disabled`);
+    return word;
+}
 export function deriveWiringManifest(facts) {
     if (facts.half === "static" && facts.leg !== undefined) {
         throw new Error("a static wiring manifest has no leg — leg identity is an effective-half fact");
@@ -146,13 +151,14 @@ export function deriveWiringManifest(facts) {
             ? { readDeny: { builtinTiers: [...facts.readDenyBuiltinTiersActive] } }
             : {}),
         ...(facts.half === "effective" && facts.autoConsolidationOnRecommendation === true ? { autoConsolidation: { onRecommendation: true } } : {}),
+        ...(facts.half === "effective" && facts.fileHistory !== undefined ? { fileHistory: readFileHistoryFact(facts.fileHistory) } : {}),
         ...(facts.half === "effective" && facts.teamRole !== undefined ? { teamRole: facts.teamRole } : {}),
         ...(facts.half === "effective" && facts.peerPresence !== undefined && (facts.peerPresence.agent !== undefined || facts.peerPresence.intent !== undefined)
             ? { peerPresence: { ...(facts.peerPresence.agent !== undefined ? { agent: facts.peerPresence.agent } : {}), ...(facts.peerPresence.intent !== undefined ? { intent: facts.peerPresence.intent } : {}) } }
             : {}),
     };
     if (facts.half === "effective") {
-        const { leg: _leg, mcp: _mcp, tools: _tools, lsp: _lsp, hooks: _hooks, teamRole: _teamRole, peerPresence: _peerPresence, ...assembly } = manifest;
+        const { leg: _leg, mcp: _mcp, tools: _tools, lsp: _lsp, hooks: _hooks, teamRole: _teamRole, peerPresence: _peerPresence, fileHistory: _fileHistory, ...assembly } = manifest;
         const { provenance: _askSeat, ...askForHash } = assembly.ask;
         const { provenance: _questionSeat, ...questionForHash } = assembly.question;
         manifest.configFingerprint = createHash("sha256")

package/dist/engine/execution-env/node-execution-env.d.ts

@@ -1,5 +1,6 @@
 import { type ExecResult, type ExecutionEnv, ExecutionError, type ExecutionEnvExecOptions, FileError, type FileInfo, type Result } from "../harness/types.js";
 import { type SecretEnvFinding } from "../../core/secret-env.js";
+import type { EngineNotice } from "../../core/engine-notice.js";
 import type { SymlinkChain } from "../harness/types.js";
 import type { BackgroundShellCapability, BackgroundShellId, BackgroundPoll, BackgroundSpawnOptions } from "../../core/background-shell.js";
 import { BackgroundShellError } from "../../core/background-shell.js";
@@ -106,6 +107,7 @@ export declare class NodeExecutionEnv implements ExecutionEnv, BackgroundShellCa
     private bgCounter;
     private readonly retainBackgroundProcesses;
     private readonly onSecretEnvScrub?;
+    private readonly onNotice?;
     /** design/128 T1-1: lazily-created env-owned spool dir (mkdtemp under os tmp — unpredictable, never the cwd). */
     private bgSpoolDir?;
     readonly backgroundCapabilities: BackgroundShellCapability["backgroundCapabilities"];
@@ -135,6 +137,10 @@ export declare class NodeExecutionEnv implements ExecutionEnv, BackgroundShellCa
          *  "scrub" leg withholds from a shell child. Absent ⇒ a once-per-process console summary (loud
          *  enough to notice, quiet enough not to spam). Never called on the "all"/allowlist legs. */
         onSecretEnvScrub?: (findings: readonly SecretEnvFinding[]) => void;
+        /** #1081 — the structured-notice seat for the SAME withheld-keys disclosure (`EngineNotice`,
+         *  `code: "config.secret_env_scrubbed"`, `detail.names`); independent of `onSecretEnvScrub` (a raw
+         *  findings collector) except: that seat wired alone stays console-silent, as before this existed. */
+        onNotice?: (notice: EngineNotice) => void;
     });
     get schedulerCapabilities(): SchedulerCapability["schedulerCapabilities"];
     schedule(intent: ScheduledIntent, ctx: SchedulerContext): Promise<Result<{

package/dist/engine/execution-env/node-execution-env.js

@@ -7,7 +7,7 @@ import { dirname, isAbsolute, join, resolve, sep } from "node:path";
 import { createInterface } from "node:readline";
 import { ExecutionError, err, FileError, ok, toError, } from "../harness/types.js";
 import { killProcessTree, shutdownDebug } from "./kill-tree.js";
-import { scrubSecretEnv } from "../../core/secret-env.js";
+import { __resetSecretEnvScrubNoticeAnnouncement, announceSecretEnvScrub, scrubSecretEnv } from "../../core/secret-env.js";
 import { physicalPathOfAsync } from "../../core/physical-path.js";
 import { isUncSpelling } from "../../tools/fs/safety.js";
 import { RollingTailBuffer, markTruncated, newStreamCursorState, sliceStreamIncrement, } from "../../core/exec-output-tail.js";
@@ -197,13 +197,12 @@ export async function getShellConfig(customShellPath) {
     return ok({ shell: "sh", args: ["-c"] });
 }
 const EXEC_FORCE_SETTLE_GRACE_MS = 3000;
-let secretScrubConsoleAnnounced = false;
 let secretScrubSeatDefectAnnounced = false;
 export function __resetSecretScrubAnnouncement() {
-    secretScrubConsoleAnnounced = false;
     secretScrubSeatDefectAnnounced = false;
+    __resetSecretEnvScrubNoticeAnnouncement();
 }
-function getShellEnv(inheritEnv, baseEnv, extraEnv, onScrub) {
+function getShellEnv(inheritEnv, baseEnv, extraEnv, onScrub, onNotice) {
     let inherited;
     if (inheritEnv === "all") {
         inherited = process.env;
@@ -230,20 +229,17 @@ function getShellEnv(inheritEnv, baseEnv, extraEnv, onScrub) {
                 catch {
                 }
             }
-            else {
-                if (onScrub !== undefined && !secretScrubSeatDefectAnnounced) {
-                    secretScrubSeatDefectAnnounced = true;
-                    try {
-                        console.warn(`onSecretEnvScrub seat holds ${onScrub === null ? "null" : typeof onScrub} — not a function; scrub findings fall back to the console summary (once per process)`);
-                    }
-                    catch {
-                    }
+            else if (onScrub !== undefined && !secretScrubSeatDefectAnnounced) {
+                secretScrubSeatDefectAnnounced = true;
+                try {
+                    console.warn(`onSecretEnvScrub seat holds ${onScrub === null ? "null" : typeof onScrub} — not a function; scrub findings fall back to the console summary (once per process)`);
                 }
-                if (!secretScrubConsoleAnnounced) {
-                    secretScrubConsoleAnnounced = true;
-                    console.warn(`secret_env_scrubbed: ${findings.length} env key(s) withheld from the shell child (${findings.map((f) => f.key).join(", ")}) — once per process; wire onSecretEnvScrub for per-exec telemetry`);
+                catch {
                 }
             }
+            if (!(typeof onScrub === "function" && onNotice === undefined)) {
+                announceSecretEnvScrub(onNotice, findings);
+            }
         }
     }
     return {
@@ -302,6 +298,7 @@ export class NodeExecutionEnv {
     bgCounter = 0;
     retainBackgroundProcesses;
     onSecretEnvScrub;
+    onNotice;
     bgSpoolDir;
     backgroundCapabilities;
     constructor(options) {
@@ -312,6 +309,7 @@ export class NodeExecutionEnv {
         this.scheduler = options.scheduler;
         this.retainBackgroundProcesses = options.retainBackgroundProcesses ?? false;
         this.onSecretEnvScrub = options.onSecretEnvScrub;
+        this.onNotice = options.onNotice;
         this.backgroundCapabilities = {
             supported: true,
             maxConcurrent: 8,
@@ -469,7 +467,7 @@ export class NodeExecutionEnv {
                 child = spawn(shellConfig.value.shell, [...shellConfig.value.args, command], {
                     cwd,
                     detached: process.platform !== "win32",
-                    env: getShellEnv(this.inheritEnv, this.shellEnv, options?.env, this.onSecretEnvScrub),
+                    env: getShellEnv(this.inheritEnv, this.shellEnv, options?.env, this.onSecretEnvScrub, this.onNotice),
                     stdio: execSpoolFds ? ["ignore", execSpoolFds[0], execSpoolFds[1]] : ["ignore", "pipe", "pipe"],
                     windowsHide: true,
                 });
@@ -1221,7 +1219,7 @@ export class NodeExecutionEnv {
             child = spawn(shellConfig.value.shell, [...shellConfig.value.args, command], {
                 cwd: options?.cwd ? resolvePath(this.cwd, options.cwd) : this.cwd,
                 detached: process.platform !== "win32",
-                env: getShellEnv(this.inheritEnv, this.shellEnv, options?.env, this.onSecretEnvScrub),
+                env: getShellEnv(this.inheritEnv, this.shellEnv, options?.env, this.onSecretEnvScrub, this.onNotice),
                 stdio: spoolFds ? ["ignore", spoolFds[0], spoolFds[1]] : ["ignore", "pipe", "pipe"],
                 windowsHide: true,
             });

package/dist/engine/harness/agent-harness.js

@@ -858,7 +858,7 @@ export class AgentHarness {
         await this.handleAgentEvent({ type: "agent_end", messages: [failureMessage] }, signal);
         return [failureMessage];
     }
-    async executeTurn(turnState, text, options) {
+    async executeTurn(turnState, text, options, abortController) {
         let activeTurnState = turnState;
         const userMessage = createUserMessage(text, options?.images, options);
         const beforeResult = await this.emitHook({
@@ -897,12 +897,10 @@ export class AgentHarness {
             }
             return messages;
         };
-        const abortController = new AbortController();
         const getTurnState = () => activeTurnState;
         const setTurnState = (nextTurnState) => {
             activeTurnState = nextTurnState;
         };
-        this.runAbortController = abortController;
         const runResultPromise = (async () => {
             try {
                 return await runAgentLoop(takePrompts, this.createContext(turnState, beforeResult?.systemPrompt), this.createLoopConfig(getTurnState, setTurnState, beforeResult?.systemPrompt), (event) => this.handleAgentEvent(event, abortController.signal), abortController.signal, this.createStreamFn(getTurnState), undefined, this.loopTrace, {
@@ -938,7 +936,7 @@ export class AgentHarness {
                     return mergeTruncatedOutputChain(newMessages, i);
                 }
             }
-            if (this.stopRequested)
+            if (this.stopRequested || abortController.signal.aborted)
                 return undefined;
             if (this.trailingBatchEndedOn !== undefined)
                 return this.trailingBatchEndedOn;
@@ -976,17 +974,21 @@ export class AgentHarness {
             }
         }
         this.phase = "turn";
+        const abortController = new AbortController();
+        this.runAbortController = abortController;
         const finishRunPromise = this.startRunPromise();
         try {
             await this.flushPendingSessionWrites();
             const turnState = await this.createTurnState();
-            return await this.executeTurn(turnState, text, options);
+            return await this.executeTurn(turnState, text, options, abortController);
         }
         catch (error) {
             this.phase = "idle";
             throw normalizeHarnessError(error, "unknown");
         }
         finally {
+            if (this.runAbortController === abortController)
+                this.runAbortController = undefined;
             finishRunPromise();
         }
     }

package/dist/engine/lsp/node-lsp-manager.d.ts

@@ -2,6 +2,7 @@ import { type SessionWarmup } from "../../core/lsp-session.js";
 import { type LspChildProcess } from "./stdio-lsp-transport.js";
 import { type LspServerManager, type LspSession, type LspReadText } from "../../core/lsp.js";
 import type { ExecutionEnv } from "../../internal/harness-types.js";
+import type { EngineNotice } from "../../core/engine-notice.js";
 /**
  * Default language → server command table (the DETERMINED supported set). Each value is a `command [args…]`
  * whose binary must be on the host `PATH`; absent ⇒ that language degrades. Mirrors the servers service bakes
@@ -22,6 +23,9 @@ export interface NodeLspManagerOptions {
     /** The language server's environment for the default spawn, verbatim. Omitted ⇒ the host environment scrubbed of
      *  credential-shaped names (`scrubSecretEnv`, a tool child's scrub). Unread when {@link spawn} is supplied. */
     env?: Record<string, string>;
+    /** #1081 — the withheld-keys notice sink, SAME shared once-per-process latch/code as the shell-exec
+     *  site's `NodeExecutionEnv.onNotice`. Absent ⇒ console only. Unread when {@link spawn} is supplied. */
+    onNotice?: (notice: EngineNotice) => void;
     /** Read a file's CURRENT text for the session's didOpen/didChange re-sync (default = local `fs.readFile` utf8). */
     readText?: LspReadText;
     /** Resolve the server `cwd`/`rootUri` for a file (default = env.cwd ?? nearest project marker ?? file dir). */

package/dist/engine/lsp/node-lsp-manager.js

@@ -9,7 +9,7 @@ import { TransportLspSession } from "../../core/lsp-session.js";
 import { StdioLspTransport } from "./stdio-lsp-transport.js";
 import { MAX_LSP_FILE_BYTES, SharedAbortScope, settleOnAbort } from "../../core/lsp.js";
 import { asThrownError, thrownText } from "../../core/thrown-value.js";
-import { scrubSecretEnv } from "../../core/secret-env.js";
+import { announceSecretEnvScrub, scrubSecretEnv } from "../../core/secret-env.js";
 export const DEFAULT_LSP_SERVERS = {
     typescript: "typescript-language-server --stdio",
     javascript: "typescript-language-server --stdio",
@@ -67,7 +67,7 @@ export class NodeLspManager {
     disposed = false;
     constructor(opts = {}) {
         this.servers = { ...DEFAULT_LSP_SERVERS, ...opts.servers };
-        this.spawnFn = opts.spawn ?? (opts.env !== undefined ? lspSpawnWithEnv(opts.env) : defaultLspSpawn);
+        this.spawnFn = opts.spawn ?? lspSpawnWithEnv(opts.env, opts.onNotice);
         this.readTextFn = opts.readText ?? defaultLspReadText;
         this.resolveRootFn = opts.resolveRoot ?? defaultResolveRoot;
         this.log = opts.log ?? (() => { });
@@ -330,10 +330,16 @@ export function lspSpawnOptions(cwd) {
         : { cwd, stdio: ["pipe", "pipe", "ignore"] };
 }
 export const defaultLspSpawn = (command, args, cwd, signal) => lspSpawnWithEnv(undefined)(command, args, cwd, signal);
-const lspSpawnWithEnv = (env) => (command, args, cwd, signal) => new Promise((resolve, reject) => {
+const lspSpawnWithEnv = (env, onNotice) => (command, args, cwd, signal) => new Promise((resolve, reject) => {
     let child;
     try {
-        child = spawn(command, args, { ...lspSpawnOptions(cwd), env: env ?? scrubSecretEnv(process.env) });
+        let scrubbedEnv = env;
+        if (scrubbedEnv == null) {
+            const findings = [];
+            scrubbedEnv = scrubSecretEnv(process.env, findings);
+            announceSecretEnvScrub(onNotice, findings);
+        }
+        child = spawn(command, args, { ...lspSpawnOptions(cwd), env: scrubbedEnv });
     }
     catch (e) {
         return reject(asThrownError(e));

package/dist/index.d.ts

@@ -229,7 +229,7 @@ export { AdoptionError, assertAdoptionBootGate, readRootAdoptionFile, writeRootA
 export { adoptLocalDataRoot, ackAdoptionConfig, witnessAdoptionConfig, listAdoptionQuarantine, readAdoptionStatus, type AdoptionStatus, type AdoptLocalDataRootOptions, type AdoptLocalDataRootResult, type AdoptionCarriageLeg, type AdoptionCarriageLegContext, type AdoptionConfigWitnessReceipt, } from "./stores/file/adoption/adopt.js";
 export { formatHookFeedback, runToolGate, createHookEnvCapabilities, createPreToolUseConstraintPolicy, type PersistedRuleHit, type PersistedRuleHitRule, type PersistedRuleUnreadable, type PersistedRuleCoverage, type PersistedRuleAnswer, normalizePersistedRuleHit, type Hooks, type HookToolContext, type HookInvocationIdentity, type UserPromptSubmitContext, type PostToolBatchContext, type HookEnvCapabilities, type HookToolOutput, type PreToolUseResult, type PostToolUseResult, type UserPromptSubmitResult, type HookToolFailure, type PostToolUseFailureResult, type PostToolBatchCall, type PostToolBatchResult, type PreCompactContext, type PreCompactResult, type PostCompactContext, type StopFailureContext, type PermissionDeniedPayload, } from "./core/hooks.js";
 export { HOOK_FAMILIES, HOOKS_INVALID_CODE, type HookFamily, type WiringManifestHookEntry } from "./core/hook-seats.js";
-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 MemoryStore, type MemoryVectorMode, type ScoredMemory, type MemoryNoteHeader, type MemoryNoteRecord, type MemoryNoteType, type StructuredNoteInput, } from "./core/memory.js";
+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 MemoryStore, 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";
 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 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, archiveDistillerPlan, readConsolidationDriverRun, runMemoryConsolidationDriver, type ConsolidationDriverEngine, type ConsolidationDriverRunRow, type ConsolidationRunReceipt, type ConsolidationRunStopReason, 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 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, 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, type MemorySyncTransport, type MemorySyncRequestBody, type MemorySyncResponseBody, type MemorySyncClientConflict, type SyncMemoryScopeOptions, type MemorySyncClientResult, } from "./core/memory-engine/index.js";
 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";
 export { sharedMemoryStoreContract, type SharedMemoryFixture, type SharedMemoryStoreContractHooks, } from "./core/shared-memory/contract.js";

package/dist/index.js

@@ -179,7 +179,7 @@ export { AdoptionError, assertAdoptionBootGate, readRootAdoptionFile, writeRootA
 export { adoptLocalDataRoot, ackAdoptionConfig, witnessAdoptionConfig, listAdoptionQuarantine, readAdoptionStatus, } from "./stores/file/adoption/adopt.js";
 export { formatHookFeedback, runToolGate, createHookEnvCapabilities, createPreToolUseConstraintPolicy, normalizePersistedRuleHit, } from "./core/hooks.js";
 export { HOOK_FAMILIES, HOOKS_INVALID_CODE } from "./core/hook-seats.js";
-export { InMemoryMemoryStore, composeMemoryBlock, composeLayeredMemoryBlock, normalizeMemorySpec, supportsConsolidation, supportsPeriodicConsolidation, firstSentence, expandLexicalTerms, lexicalSearchMatch, classifyPromotable, enforcePromotableWriteGate, guardedMemoryStore, MemoryGateError, MemoryProjectionError, detectSecret, enforceSecretWriteGate, enforceStructuredNoteSecretGate, } from "./core/memory.js";
+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";
 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, 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, 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, } from "./core/memory-engine/index.js";
 export { SHARED_MEMORY_READ_CAP_BYTES, SHARED_MEMORY_LIST_PAGE_SIZE, SharedMemoryStoreError, } from "./core/shared-memory/types.js";
 export { sharedMemoryStoreContract, } from "./core/shared-memory/contract.js";

package/dist/tools/fs/shell-read-plan.d.ts

@@ -62,8 +62,8 @@ export interface ReadCandidate {
      *  A deny row is a floor, so the judge resolves the spelling against these for deny rows ONLY — never to
      *  establish a read. `cd sub && cd $'\x2e' && cat <deny row under sub>` (bash: `cd .`) is refused through it. */
     readonly floorBases?: readonly string[];
-    /** A home word the plan does not place (the text may rebind `HOME`, or it sits in a value): spelled with the DECLARED
-     *  home. A deny row is a floor: the judge reads it for deny rows ONLY, never to establish a read. */
+    /** A home word the plan does not place (the text may rebind `HOME`, it sits in a value, or it is a literal tilde the
+     *  program may expand itself): spelled with the DECLARED home. The judge reads it for deny rows ONLY. */
     readonly floorSpelled?: string;
     /** A deny-floor shadow of a `floorSpelled` spelling, established as a read and judged for deny rows only. */
     readonly denyOnly?: true;

package/dist/tools/fs/shell-read-plan.js

@@ -193,7 +193,7 @@ function segmentFacts(segment, p, decl, home, nestedPlan) {
             unresolvedRaw.add(w.raw);
     }
     const homeWithheld = home === undefined && decl.homeDir !== undefined;
-    const floor = (c) => { const f = c.expands === "unresolvable" && decl.homeDir !== undefined ? spelledWithHome(c.spelled, c.raw, decl.homeDir) : undefined; return f === undefined ? c : { ...c, floorSpelled: f }; };
+    const floor = (c) => { const f = (c.expands === "unresolvable" || c.spelled.startsWith("./~")) && decl.homeDir !== undefined ? spelledWithHome(c.spelled, c.raw, decl.homeDir) : undefined; return f === undefined ? c : { ...c, floorSpelled: f }; };
     const unsettle = (c) => floor((unresolvedRaw.has(c.raw) || (homeWithheld && c.spelled.startsWith("~"))) && c.expands !== "unresolvable" ? { ...c, expands: "unresolvable" } : c);
     const move = facts.baseMove;
     return {
@@ -268,9 +268,8 @@ function segmentFactsRead(segment, p, decl, home, nestedPlan) {
     const basename = program?.basename;
     const listed = basename !== undefined && (decl.readers.has(basename) || basename === "cd");
     const verb = program === undefined ? undefined : { name: program.name, basename: program.basename, listed };
-    const envOpens = basename !== undefined && !NO_PATH_OPERAND_COMMANDS.has(basename);
     for (const k of pos.assignments)
-        pushAssignment(reads, toks[k].word, "env_assignment", envOpens);
+        pushAssignment(reads, toks[k].word, "env_assignment");
     for (const l of pos.launchers) {
         const r = toks[l.index];
         if (isPathShapedToken(r.folded))
@@ -313,7 +312,7 @@ function segmentFactsRead(segment, p, decl, home, nestedPlan) {
                 continue;
             }
             if (r.word.assignment !== undefined) {
-                pushAssignment(reads, r.word, "env_assignment", envOpens);
+                pushAssignment(reads, r.word, "env_assignment");
                 continue;
             }
             reads.push(bare(r, "unlisted_word"));
@@ -462,7 +461,7 @@ function dedupe(reads) {
     const seen = new Set();
     const out = [];
     for (const c of reads) {
-        const key = `${c.provenance}\u0000${c.spelled}\u0000${c.expands}\u0000${c.denyOnly === true}`;
+        const key = `${c.provenance}\u0000${c.spelled}\u0000${c.expands}\u0000${c.raw}\u0000${c.denyOnly === true}`;
         if (seen.has(key))
             continue;
         seen.add(key);
@@ -488,7 +487,7 @@ function redirectFact(r, home) {
         return { op: r.op, direction: "in" };
     return { op: r.op, direction: "out", target: bare(readsOf([r.target], home)[0], "write_redirect_target") };
 }
-function pushAssignment(reads, w, provenance, opensValue = true) {
+function pushAssignment(reads, w, provenance) {
     const a = w.assignment;
     if (a === undefined)
         return;
@@ -498,13 +497,19 @@ function pushAssignment(reads, w, provenance, opensValue = true) {
     const named = a.value.folded === "" || (a.op === "+=" ? expandsTilde : !settled) ? undefined : value;
     if (a.value.folded === "" && settled)
         return;
-    const v = { spelled: a.value.folded, raw: a.bare ? a.value.raw : w.raw, provenance };
+    const v = { spelled: value, raw: a.bare ? a.value.raw : w.raw, provenance };
     const unsettled = provenance !== "env_assignment" ? { ...v, expands: "unresolvable" } : v.spelled.startsWith("~") && !v.spelled.includes(":") ? { ...v, expands: expandsOf(a.value) } : undefined;
-    if (!settled && opensValue && unsettled !== undefined)
+    if (!settled && unsettled !== undefined)
         reads.push(unsettled);
     const substitutes = a.value.expansions.some((p) => p.expansion?.kind === "command" || p.expansion?.kind === "process" || p.expansion?.kind === "arithmetic");
     if (named !== undefined && !substitutes)
         reads.push({ spelled: named, raw: w.raw, provenance, expands: expandsOf(w) });
+    if (a.value.folded.includes(":"))
+        for (const m of a.value.folded.split(":"))
+            if (m !== "") {
+                const r = readOfText(m);
+                reads.push({ spelled: r.folded, raw: r.raw, provenance, expands: r.expands, denyOnly: true });
+            }
     if (a.form === "compound")
         for (const e of compoundArrayElements(a.value))
             reads.push({ spelled: e.folded, raw: e.raw, provenance, expands: e.expands, ...(e.denyOnly === true ? { denyOnly: true } : {}) });
@@ -527,7 +532,7 @@ function unlistedWords(reads, toks, from, launcherIndices, provenance, program)
         expanding.add(j);
         reads.push(bare(toks[j], j === argvStart ? "program_path" : provenance));
         if (j < argvStart)
-            pushAssignment(reads, toks[j].word, "env_assignment", slotVerb !== undefined && !noPathOperands);
+            pushAssignment(reads, toks[j].word, "env_assignment");
         else if (j > argvStart && !declaredNotPaths)
             pushAssignment(reads, toks[j].word, provenance);
     }
@@ -605,7 +610,7 @@ function unlistedWords(reads, toks, from, launcherIndices, provenance, program)
         }
         reads.push(bare(r, j === argvStart ? "program_path" : provenance));
         if (j < argvStart)
-            pushAssignment(reads, r.word, "env_assignment", slotVerb !== undefined && !noPathOperands);
+            pushAssignment(reads, r.word, "env_assignment");
         else if (!declaredNotPaths)
             pushAssignment(reads, r.word, provenance);
     }

package/dist/tools/fs/shell-read-word.d.ts

@@ -25,10 +25,11 @@ export declare function readsOf(words: readonly LexedWord[], home: string | unde
 export declare const rewritten: (r: Read) => boolean;
 /** The reading of a text that came out of a word (a sed script's file operand): one shell word, or unresolvable. */
 export declare function readOfText(text: string): Read;
-/** A home-rooted candidate spelled with `home`: a leading `~` / `~/` (a literal tilde is spelled `./~` before this
- *  point, so a leading `~` IS the expansion), or a `$HOME` / `${HOME}` word as {@link homeExpansionOf} reads it —
- *  read off the VALUE's pieces when the word is assignment-shaped (`A="$HOME/x"`, `dd if="$HOME/x"`: the candidate is
- *  the value, quotes kept); `undefined` for any other (`~user`, a payload, a word that is no home word). */
+/** A home-rooted candidate spelled with `home`: a leading `~` / `~/` — the shell's expansion, or the literal-tilde
+ *  spelling `./~` of one it leaves alone (quoted, escaped, after an option's `=`), which the program it reaches may
+ *  expand itself — or a `$HOME` / `${HOME}` word as {@link homeExpansionOf} reads it, read off the VALUE's pieces when
+ *  the word is assignment-shaped (`A="$HOME/x"`, `dd if="$HOME/x"`: the candidate is the value, quotes kept);
+ *  `undefined` for any other (`~user`, a word that is no home word). */
 export declare function spelledWithHome(spelled: string, raw: string, home: string): string | undefined;
 /** A function definition's head names nothing that runs here and is dropped from a segment's tokens, in place:
  *  `NAME ( )` (an identifier), and `function NAME [( )]` — a bare `function` at command position, a name of any

package/dist/tools/fs/shell-read-word.js

@@ -20,8 +20,9 @@ export function readOfText(text) {
     return { word, raw: text, folded: text, expands: expandsOf(word) };
 }
 export function spelledWithHome(spelled, raw, home) {
-    if (spelled.startsWith("~"))
-        return /^~(?:\/|$)/.test(spelled) ? `${home}${spelled.slice(1)}` : undefined;
+    const tilde = spelled.startsWith("./~") ? spelled.slice(2) : spelled;
+    if (tilde.startsWith("~"))
+        return /^~(?:\/|$)/.test(tilde) ? `${home}${tilde.slice(1)}` : undefined;
     if (!raw.includes("HOME"))
         return undefined;
     const w = readOfText(raw).word;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "7.30.1",
+  "version": "7.31.1",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",

package/test/export-surface.snapshot.json

@@ -1,7 +1,7 @@
 {
   "_comment": "design/87 L3 — frozen public export surface of src/index.ts (name -> kind). DO NOT edit by hand to silence a red test. A removed/changed entry = a SemVer-BREAKING change; bump MAJOR and update this fixture in the SAME commit (design/87 §4.2 / §5.2). Regenerate via REGEN in test/export-surface.test.ts.",
   "_tierComment": "#435 v1 — machine-readable layering of the public surface: stable = demonstrated by README.md / src/examples; internal = an `Internal`-marked name or a runner/engine deep-subtree declaration (the model seam src/engine/llm is excluded — it is the BYOM contract, not an engine internal); advanced = a supported export the front door does not walk you through. THIS IS AN INITIAL HEURISTIC, derived mechanically and expected to be refined ticket by ticket: no human reviewed these 1700+ entries one by one, and nothing here claims otherwise. Known bias: a short or English-word export name (ok, err, Result, Usage) can match ordinary prose in README.md and land `stable` on a coincidence. Every export MUST carry a tier — a new export with no row fails the gate in export-surface.test.ts.",
-  "count": 2475,
+  "count": 2478,
   "exports": {
     "A2ATaskState": "type",
     "A2ATaskStateReversal": "type",
@@ -688,6 +688,7 @@
     "MEMORY_INSTRUCTION_TEMPLATE": "variable",
     "MEMORY_ORIGIN_CAUSES": "variable",
     "MEMORY_PREFERENCE_DISCIPLINE": "variable",
+    "MEMORY_PROJECT_KEY_ABSENT_REASONS": "variable",
     "MEMORY_READONLY_NOTICE": "variable",
     "MEMORY_RECALL_DISCIPLINE": "variable",
     "MEMORY_SAFETY": "variable",
@@ -769,6 +770,8 @@
     "MemoryNoteRecord": "interface",
     "MemoryNoteType": "type",
     "MemoryOriginCause": "type",
+    "MemoryProjectKey": "type",
+    "MemoryProjectKeyAbsentReason": "type",
     "MemoryProjectionError": "class",
     "MemoryPromptArtifactStore": "class",
     "MemoryPromptSourceStateStore": "class",
@@ -3165,6 +3168,7 @@
     "MEMORY_INSTRUCTION_TEMPLATE": "advanced",
     "MEMORY_ORIGIN_CAUSES": "advanced",
     "MEMORY_PREFERENCE_DISCIPLINE": "advanced",
+    "MEMORY_PROJECT_KEY_ABSENT_REASONS": "advanced",
     "MEMORY_READONLY_NOTICE": "advanced",
     "MEMORY_RECALL_DISCIPLINE": "advanced",
     "MEMORY_SAFETY": "advanced",
@@ -3246,6 +3250,8 @@
     "MemoryNoteRecord": "stable",
     "MemoryNoteType": "advanced",
     "MemoryOriginCause": "advanced",
+    "MemoryProjectKey": "advanced",
+    "MemoryProjectKeyAbsentReason": "advanced",
     "MemoryProjectionError": "advanced",
     "MemoryPromptArtifactStore": "advanced",
     "MemoryPromptSourceStateStore": "advanced",