@sema-agent/core 5.45.0 → 5.47.0

package/dist/core/runner/prepare-hands-readface.d.ts

@@ -98,6 +98,11 @@ export interface PrepareHandsReadFaceInput {
     /** borrowed-mutable — the classify doctrine's probe installs (`.set`, only where the doctrine
      *  owns the seat). Same-object contract as above. */
     reversibilityProbes: PrepareSafetyScanResult["reversibilityProbes"];
+    /** borrowed-readonly — design/319 (A ticket): the run's reminder provenance mark (minted/adopted
+     *  by the driver's adoption ladder); threaded into the hands band so the fs-side engine mints
+     *  (the Read cyber/dedup/offset/empty reminders, the gh rate-limit hint) stamp the same mark the
+     *  system-prompt declaration names. */
+    reminderMark: string;
 }
 /** The phase's outputs (相 API 规则件 four-class form) — ALL settled before the return; the driver
  *  binds them as fresh consts (R-5) except the inverted-closure trio and the two shellGated bits,
@@ -173,17 +178,6 @@ export interface PrepareHandsReadFaceResult {
     /** write-back — the Monitor twin of the bit above. */
     shellGatedMonitor: boolean;
 }
-/** The hands-LESS resolver arm (#242) — SYNCHRONOUS by contract. The original P10 else-arm ran
- *  with ZERO awaits, so on a hands-less leg the stretch from the driver's A2A warning callback
- *  (deployment `onError`, which can queue a microtask) through the P11 SendMessage/delegation
- *  mounts was uninterruptible. An `async` phase call would open exactly that microtask window (the
- *  T1 hazard, here on the hands-less leg — a queued `spec.tools` mutation could suppress the
- *  SendMessage mount or plant a trusted-revive delegation entry). So this leg is its OWN plain sync
- *  seam the driver calls WITHOUT `await` (dispatching on the `handsEnabled` boolean it already
- *  owns — NOT on a `Promise` identity check, which a host that replaces `globalThis.Promise` could
- *  defeat; r3): the leg is byte-for-byte as synchronous as before the extraction.
- *  (Adversarial review 2026-08-18, verified against the a945be28 baseline: awaits 3981–4243 are all
- *  inside the hands branch; the else arm reached 4440/4463 with none.) */
 export declare function resolveHandsLessReadFace(input: PrepareHandsReadFaceInput): PrepareHandsReadFaceResult;
 /** The hands-MOUNT branch — the async half of the phase (see the module header for the contract).
  *  The driver awaits this ONLY on the hands leg (`handsEnabled === true`); the hands-less leg goes

package/dist/core/runner/prepare-hands-readface.js

@@ -12,8 +12,29 @@ let readFaceClampConsoleAnnounced = false;
 export function __resetReadFaceClampAnnouncement() {
     readFaceClampConsoleAnnounced = false;
 }
+function assertStringArraySeat(value, seat, entryLaw) {
+    if (value === undefined)
+        return;
+    if (!Array.isArray(value)) {
+        const e = new Error(`${seat} must be an array or absent (got ${value === null ? "null" : typeof value}) — a non-array here would be iterated character by character, so it refuses loudly instead.`);
+        e.code = "config.read_face_seat";
+        throw e;
+    }
+    if (entryLaw !== "strings")
+        return;
+    const entries = value;
+    for (const entry of entries) {
+        if (typeof entry !== "string") {
+            const e = new Error(`${seat} entries must be strings (got ${entry === null ? "null" : typeof entry}).`);
+            e.code = "config.read_face_seat";
+            throw e;
+        }
+    }
+}
 export function resolveHandsLessReadFace(input) {
     const { resume, fullShellReachable, spec, deps } = input;
+    assertStringArraySeat(deps.readDenyPatterns, "RunnerDeps.readDenyPatterns", "compiler-owned");
+    assertStringArraySeat(spec.readDenyPatterns, "TaskSpec.readDenyPatterns", "compiler-owned");
     let handsLessResolvedFace;
     let readDenyAdditionsNormalized = [];
     {
@@ -56,6 +77,10 @@ export function resolveHandsLessReadFace(input) {
 }
 export async function prepareHandsMount(input) {
     const { handsEnabled, executionEnv, taskRootFinal, rebaseRestoredPath, resume, session, sessionId, hostTaskId, taskScope, fullShellReachable, effectiveShellGate, toolFaceSnapshot, model, spec, deps, internals, memoryWriteGateRef, firstPartyOffload, tools, egressTools, irreversibilityTier, irreversibleTools, reversibilityProbes } = input;
+    assertStringArraySeat(spec.additionalDirectories, "TaskSpec.additionalDirectories", "strings");
+    assertStringArraySeat(spec.additionalReadDirectories, "TaskSpec.additionalReadDirectories", "strings");
+    assertStringArraySeat(deps.readDenyPatterns, "RunnerDeps.readDenyPatterns", "compiler-owned");
+    assertStringArraySeat(spec.readDenyPatterns, "TaskSpec.readDenyPatterns", "compiler-owned");
     let readFileStateForCheckpoint;
     let seedContextFiles;
     let handsCwdRef;
@@ -193,6 +218,7 @@ export async function prepareHandsMount(input) {
             ...(readDenyBuiltinCfg.tiers !== undefined ? { readDenyBuiltinTiers: readDenyBuiltinCfg.tiers } : {}),
             ...(readDenyBuiltinCfg.exclude !== undefined ? { readDenyBuiltinExclude: readDenyBuiltinCfg.exclude } : {}),
             readFace: liveReadFace,
+            reminderMark: input.reminderMark,
             includeShell: handsIncludeShell,
             readOnly: handsReadOnly,
             ...(handsCwdRef ? { cwdRef: handsCwdRef } : {}),

package/dist/core/runner/prepare-memory.d.ts

@@ -21,6 +21,10 @@ export interface PrepareMemoryInput {
      * its roster (or cannot reach the store); the RB-276 index seed follows the same gate.
      */
     writeToolsMounted: boolean;
+    /** design/319 (A ticket) — the run's reminder provenance mark: the memory engine's announcement
+     *  block is an engine-authored `<system-reminder>`, so its open tag must carry the same mark the
+     *  system-prompt declaration names. Threaded into every `engine.inject` call this phase builds. */
+    reminderMark: string;
     /**
      * The session-wide persistence verdict: `TaskSpec.memoryPersistenceCapable` (the deployment's own
      * statement — the only honest channel for a custom memory writer persisting through its closure,
@@ -46,6 +50,13 @@ export interface PrepareMemoryInput {
      *   the memory store" stays a true statement instead of a disclosure the store then contradicts.
      */
     memoryPersistenceDeclared?: boolean;
+    /**
+     * design/336 §13-3 — the memory-provenance master switch, screened at the config doors
+     * (`config.memory_provenance`, exact spellings, absent folded to `"carry"`). Every engine this
+     * phase constructs runs under it, and the pollution notices/tool wording state the mode-true
+     * behavior off it. See {@link RunnerDeps.memoryProvenance}.
+     */
+    memoryProvenance: "off" | "carry";
     /**
      * design/178 ②-1 — whether the `memory_search`/`memory_get` pair PASSED its early mount conjuncts
      * (exclusion + name occupancy, decided in prepare-task BEFORE this phase). True ⇒ this phase builds

package/dist/core/runner/prepare-memory.js

@@ -1,10 +1,10 @@
-import { sep } from "node:path";
+import { isAbsolute, sep } from "node:path";
 import { deliverEngineNotice } from "../types.js";
 import { admitMemoryScopes } from "../memory-admission.js";
 import { adoptLegacyRepoDirs, canonicalize, deriveRepoControlPlaneDir, deriveProjectControlDir, deriveProjectMemoryDir, deriveRepoMemoryDir, drainMemoryAnnouncements, enqueueMemoryAnnouncement, isContainedIn, lookupProjectIdHint, recordProjectIdHint, resolveMemoryEngineRoot } from "../memory-engine/layout.js";
 import { classifyScopePlanes, derivePersonalControlDir, derivePersonalMemoryDir, mergeHarvestReports, mergeInjections, needsDualRoots, parsedProjectPlane } from "../memory-engine/dual-root.js";
 import { normalizeMemorySpec } from "../memory.js";
-import { MEMORY_ANNOUNCEMENT_READONLY_CODA, MEMORY_PREFERENCE_DISCIPLINE, MEMORY_READONLY_NOTICE, MEMORY_RECALL_DISCIPLINE, MemoryEngine, memoryHarvestQuarantinedNotice, memorySessionPollutedNotice, pollutionContainmentCounts, } from "../memory-engine/engine.js";
+import { MEMORY_ANNOUNCEMENT_READONLY_CODA, MEMORY_PREFERENCE_DISCIPLINE, MEMORY_READONLY_NOTICE, MemoryEngine, entryFileHeadCarriesOrigin, memoryHarvestQuarantinedNotice, memoryHoldNotices, memoryRecallDisciplineSegment, memorySessionPollutedNotice, pollutionContainmentCounts, } from "../memory-engine/engine.js";
 import { createMemoryEngineTools } from "../memory-engine/tools.js";
 import { assertScopeContractPlacement, parseScopeKey, resolveProjectId } from "../memory-engine/scope-contract.js";
 import { FileMemoryEngineBackend } from "../memory-engine/file-backend.js";
@@ -135,7 +135,7 @@ export async function prepareMemory(input) {
             const choosePersonalBackend = () => typeof pinned === "string" && pinned ? new FileMemoryEngineBackend(personalMemoryDir, { controlDir: personalControlDir }) : backend;
             const createPersonalEngine = (personalBackend) => {
                 return {
-                    engine: new MemoryEngine({ backend: personalBackend, memoryDir: personalMemoryDir, controlDir: personalControlDir, onIncident: onEngineIncident }),
+                    engine: new MemoryEngine({ backend: personalBackend, memoryDir: personalMemoryDir, controlDir: personalControlDir, onIncident: onEngineIncident, provenance: input.memoryProvenance }),
                     backend: personalBackend,
                 };
             };
@@ -155,7 +155,7 @@ export async function prepareMemory(input) {
                 : planeScopes(memorySpec.scopes, memorySpec.writeScope)).map((scope) => ({ scope, origin: originOf(scope) }));
             const pollutedOpts = (engine) => {
                 const rec = engine.sessionPollution(sessionId);
-                return rec !== undefined ? { polluted: { reason: rec.reason } } : {};
+                return rec !== undefined ? { polluted: { reason: rec.reason, ...(rec.cause !== undefined ? { cause: rec.cause } : {}) } } : {};
             };
             let writeEngine;
             let writeHandle;
@@ -194,20 +194,21 @@ export async function prepareMemory(input) {
                     memoryDir,
                     controlDir: identityKey !== undefined ? deriveProjectControlDir(engineRoot, identityKey) : deriveRepoControlPlaneDir(engineRoot, repoRoot),
                     onIncident: onEngineIncident,
+                    provenance: input.memoryProvenance,
                 });
                 const personal = createPersonalEngine(personalBackendChosen);
                 const personalEngine = personal.engine;
                 const p = planes;
-                const projectHandle = await projectEngine.materialize(p.project, p.writePlane === "project" ? memorySpec.writeScope : null, { adoptionRestricted });
+                const projectHandle = await projectEngine.materialize(p.project, p.writePlane === "project" ? memorySpec.writeScope : null, { adoptionRestricted, sessionId });
                 materializedResidue.push(...planeScopes(p.project, p.writePlane === "project" ? memorySpec.writeScope : null));
-                const personalHandle = await personalEngine.materialize(p.personal, p.writePlane === "personal" ? memorySpec.writeScope : null, { adoptionRestricted });
+                const personalHandle = await personalEngine.materialize(p.personal, p.writePlane === "personal" ? memorySpec.writeScope : null, { adoptionRestricted, sessionId });
                 materializedResidue.push(...planeScopes(p.personal, p.writePlane === "personal" ? memorySpec.writeScope : null));
                 const writeIsPersonal = p.writePlane === "personal";
                 writeEngine = writeIsPersonal ? personalEngine : projectEngine;
                 writeHandle = writeIsPersonal ? personalHandle : projectHandle;
                 readOnlyEngine = writeIsPersonal ? projectEngine : personalEngine;
                 readOnlyHandle = writeIsPersonal ? projectHandle : personalHandle;
-                injectFn = () => mergeInjections(projectEngine.inject(projectHandle, { writeToolMounted: input.writeToolsMounted }), personalEngine.inject(personalHandle, { writeToolMounted: input.writeToolsMounted }));
+                injectFn = () => mergeInjections(projectEngine.inject(projectHandle, { writeToolMounted: input.writeToolsMounted, reminderMark: input.reminderMark }), personalEngine.inject(personalHandle, { writeToolMounted: input.writeToolsMounted, reminderMark: input.reminderMark }));
                 toolPlanes = [
                     {
                         backend: retrievalBackend(backend, adoptionRestricted || p.writePlane !== "project"),
@@ -243,11 +244,11 @@ export async function prepareMemory(input) {
             else if (personalOnly) {
                 const personal = createPersonalEngine(choosePersonalBackend());
                 const personalEngine = personal.engine;
-                const handle = await personalEngine.materialize(memorySpec.scopes, memorySpec.writeScope, { adoptionRestricted });
+                const handle = await personalEngine.materialize(memorySpec.scopes, memorySpec.writeScope, { adoptionRestricted, sessionId });
                 materializedResidue.push(...planeScopes(memorySpec.scopes, memorySpec.writeScope));
                 writeEngine = personalEngine;
                 writeHandle = handle;
-                injectFn = () => personalEngine.inject(handle, { writeToolMounted: input.writeToolsMounted });
+                injectFn = () => personalEngine.inject(handle, { writeToolMounted: input.writeToolsMounted, reminderMark: input.reminderMark });
                 harvestBoth = () => personalEngine.harvest(handle, { ...pollutedOpts(personalEngine), sessionId, ...admitNothingOpts });
                 toolPlanes = [
                     {
@@ -264,12 +265,13 @@ export async function prepareMemory(input) {
                     memoryDir,
                     controlDir: identityKey !== undefined ? deriveProjectControlDir(engineRoot, identityKey) : deriveRepoControlPlaneDir(engineRoot, repoRoot),
                     onIncident: onEngineIncident,
+                    provenance: input.memoryProvenance,
                 });
-                const handle = await engine.materialize(memorySpec.scopes, memorySpec.writeScope, { adoptionRestricted });
+                const handle = await engine.materialize(memorySpec.scopes, memorySpec.writeScope, { adoptionRestricted, sessionId });
                 materializedResidue.push(...planeScopes(memorySpec.scopes, memorySpec.writeScope));
                 writeEngine = engine;
                 writeHandle = handle;
-                injectFn = () => engine.inject(handle, { writeToolMounted: input.writeToolsMounted });
+                injectFn = () => engine.inject(handle, { writeToolMounted: input.writeToolsMounted, reminderMark: input.reminderMark });
                 harvestBoth = () => engine.harvest(handle, { ...pollutedOpts(engine), sessionId, ...admitNothingOpts });
                 toolPlanes = [
                     {
@@ -302,15 +304,18 @@ export async function prepareMemory(input) {
             let pollutionAnnounced = false;
             const announceHarvestContainment = (report) => {
                 const { count, moved, escalated } = pollutionContainmentCounts(report);
-                if (count === 0)
-                    return;
-                let reason;
-                try {
-                    reason = writeEngine.sessionPollution(sessionId)?.reason;
-                }
-                catch {
+                const indexOnly = input.memoryProvenance !== "off" && count === 0 && report.containment?.indexRolledBack === true;
+                if (count > 0 || indexOnly) {
+                    let reason;
+                    try {
+                        reason = writeEngine.sessionPollution(sessionId)?.reason;
+                    }
+                    catch {
+                    }
+                    deliverEngineNotice(deps.onNotice, memoryHarvestQuarantinedNotice({ count, moved, escalated, ...(reason !== undefined ? { reason } : {}), sessionId, provenance: input.memoryProvenance, ...(indexOnly ? { indexRolledBack: true } : {}) }));
                 }
-                deliverEngineNotice(deps.onNotice, memoryHarvestQuarantinedNotice({ count, moved, escalated, ...(reason !== undefined ? { reason } : {}), sessionId }));
+                for (const notice of memoryHoldNotices(report, sessionId))
+                    deliverEngineNotice(deps.onNotice, notice);
             };
             const harvestSafe = async (phase = "terminal") => {
                 try {
@@ -342,18 +347,40 @@ export async function prepareMemory(input) {
                 harvest: harvestSafe,
                 pollution: {
                     polluted: () => writeEngine.sessionPollution(sessionId),
-                    markPolluted: (reason) => {
-                        const outcome = writeEngine.markSessionPolluted(sessionId, reason);
+                    markPolluted: (reason, cause) => {
+                        const outcome = writeEngine.markSessionPolluted(sessionId, reason, cause);
                         if (outcome === "existed" || (outcome === "unpersisted" && pollutionAnnounced))
                             return;
                         pollutionAnnounced = true;
-                        deliverEngineNotice(deps.onNotice, memorySessionPollutedNotice({ reason, sessionId }));
+                        deliverEngineNotice(deps.onNotice, memorySessionPollutedNotice({ reason, sessionId, provenance: input.memoryProvenance }));
                     },
                 },
                 contentSafety: {
                     trustedTools: new Set(memorySpec.trustedTools ?? []),
                     execIsExternalContent: memorySpec.execIsExternalContent === true,
                 },
+                ...(input.memoryProvenance !== "off"
+                    ? { settlement: { controlDir: writeEngine.controlPlaneDir, sessionId, provenance: "carry" } }
+                    : {}),
+                ...(input.memoryProvenance !== "off"
+                    ? {
+                        recallTaint: {
+                            judgeDeliveredPath: (absPath) => {
+                                try {
+                                    if (!isAbsolute(absPath))
+                                        return false;
+                                    const roots = [writeHandle.memoryDir, ...(readOnlyHandle !== undefined ? [readOnlyHandle.memoryDir] : [])];
+                                    if (!roots.some((r) => isContainedIn(r, absPath)))
+                                        return false;
+                                    return entryFileHeadCarriesOrigin(absPath);
+                                }
+                                catch {
+                                    return false;
+                                }
+                            },
+                        },
+                    }
+                    : {}),
             };
             effectiveMemoryScopes = {
                 state: "mounted",
@@ -361,8 +388,17 @@ export async function prepareMemory(input) {
                 scopes: mountedScopeRows,
                 writeScope: memorySpec.writeScope,
             };
+            if (input.memoryProvenance !== "off") {
+                const session = memoryEngineSession;
+                const markDerived = (ids) => {
+                    const shown = ids.slice(0, 3).join(", ") + (ids.length > 3 ? ", …" : "");
+                    session.pollution.markPolluted(`this session read the content of external-origin memory entr${ids.length === 1 ? "y" : "ies"} ${shown}`, "derived");
+                };
+                for (const plane of toolPlanes)
+                    plane.onTaintedDelivery = markDerived;
+            }
             if (input.memorySearchToolsPlanned)
-                memoryTools = createMemoryEngineTools({ planes: toolPlanes, sessionPollution: () => writeEngine.sessionPollution(sessionId) });
+                memoryTools = createMemoryEngineTools({ planes: toolPlanes, sessionPollution: () => writeEngine.sessionPollution(sessionId), provenance: input.memoryProvenance });
         }
         catch (err) {
             if (typeof err.code === "string" &&
@@ -411,7 +447,8 @@ export async function prepareMemory(input) {
         if (blockBody.trim())
             memoryBlock = blockBody;
         if (memoryTools !== undefined) {
-            memoryBlock = memoryBlock !== undefined ? `${memoryBlock}\n\n${MEMORY_RECALL_DISCIPLINE}` : MEMORY_RECALL_DISCIPLINE;
+            const segment = memoryRecallDisciplineSegment(input.memoryProvenance);
+            memoryBlock = memoryBlock !== undefined ? `${memoryBlock}\n\n${segment}` : segment;
         }
         if (memoryEngineSession.handle.writeScope !== null && input.writeToolsMounted && input.rosterCanPersist) {
             memoryBlock = memoryBlock !== undefined ? `${memoryBlock}\n\n${MEMORY_PREFERENCE_DISCIPLINE}` : MEMORY_PREFERENCE_DISCIPLINE;

package/dist/core/runner/prepare-task.d.ts

@@ -142,6 +142,11 @@ export interface Prepared {
      *  the `Session` contract instead. */
     session: StoredSession;
     sessionId: string;
+    /** design/319 (A ticket) — the session's reminder provenance mark this run mints under (adopted
+     *  through the prepare adoption ladder: checkpoint seed → trusted fork channel → session entry →
+     *  fresh mint). Every engine-authored `<system-reminder>` open tag in the run carries it, and the
+     *  system prompt's Harness declaration names it. Always present on a completed prepare. */
+    reminderMark: string;
     /** The ISOLATION-AWARE working-tree root for this task (a worktree's cwd when `isolation: "worktree"`, else
      *  `deps.rootPath ?? executionEnv.cwd`) — the same value the hands/LSP/policy/restore use. The Runner's
      *  rewind/snapshot path MUST key off THIS, not `deps.rootPath`, or a worktree-isolated turn snapshots the base
@@ -414,8 +419,13 @@ export interface Prepared {
             polluted: () => {
                 at: number;
                 reason: string;
+                cause?: import("../memory-engine/types.js").MemoryOriginCause;
             } | undefined;
-            markPolluted: (reason: string) => void;
+            /** design/336 §2.2 — `cause` is the structured mechanical fact the mark records (and the
+             *  origin marker minted off it carries): `"observed"` for a witnessed external event,
+             *  `"static"` for the capability over-approximation, `"derived"` for recall-taint. Absent
+             *  folds to `"observed"` at mint time (the honest floor). */
+            markPolluted: (reason: string, cause?: import("../memory-engine/types.js").MemoryOriginCause) => void;
         };
         /** design/178 §3 — the task's content-safety config (normalized memory spec): the allowlist for
          *  UNDECLARED tools and the strict execution-class upgrade. Consumed by the tool wrap only. */
@@ -423,6 +433,30 @@ export interface Prepared {
             trustedTools: ReadonlySet<string>;
             execIsExternalContent: boolean;
         };
+        /**
+         * design/336 §3.3 — the delegation-settlement handle: the control-plane coordinates a
+         * settlement writer needs, as PURE DATA. Consumers (the subagent background leg's write-ahead
+         * + terminal observation, the tool wrap's sync unattestable row) can outlive this prepared
+         * leg, so they rebuild their write handle from these fields alone — never from the live
+         * engine/session objects above. Present only under `memoryProvenance: "carry"` (the default):
+         * an `"off"` deployment keeps the pre-336 accepted-cost posture byte-level.
+         */
+        settlement?: {
+            /** The WRITE plane's control-plane dir (the pollution-marker/lineage sidecar home). */
+            controlDir: string;
+            sessionId: string;
+            provenance: "carry";
+        };
+        /**
+         * design/336 §5.5 (file-face half) — the Read-tool recall-taint judgment, present only under
+         * `memoryProvenance: "carry"`. True ⇔ the delivered ABSOLUTE path sits inside a mounted memory
+         * plane and its head bytes carry a committed external-origin marker; the tool wrap then marks
+         * the session derived (same seat and cause as the memory_get propagation). Never throws;
+         * relative paths and unreadable files answer false (named residuals beside the Bash channel).
+         */
+        recallTaint?: {
+            judgeDeliveredPath: (absPath: string) => boolean;
+        };
     };
     /** A per-task env minted by `RunnerDeps.executionEnvFactory` (design/48 remote seam) that THIS task owns
      *  and the Runner must tear down on task end. Undefined when the env came from a (caller-owned) static
@@ -1167,6 +1201,17 @@ export interface RunInternals {
      * `TaskSpec` field — the untrusted-caller surface), mirrors `inheritedManifestScope`.
      */
     insideFork?: boolean;
+    /**
+     * design/319 (A ticket) — the PARENT's reminder provenance mark, set ONLY by the Agent tool's
+     * fork route on the child it spawns ("one declaration, one mark": a fork runs under the parent's
+     * byte-identical system-prompt declaration, so its own engine mints must carry the PARENT's mark;
+     * a spawn/clone context mints its own). Verified through the mint home's verify port at adoption
+     * (`isValidReminderMark` — an unrecognized value re-mints, fail-safe); the forked SESSION's own
+     * `reminder_mark` entry is the primary carrier (a store fork copies committed history), this
+     * channel is the in-process belt over it. TRUSTED run-scoped channel (NOT a {@link TaskSpec}
+     * field), mirroring `insideFork`.
+     */
+    reminderMark?: string;
     /**
      * RB-204 P1 (codex review) — set UNCONDITIONALLY by every core spawn path (`createSubagentTool`'s
      * `childInternals` — shared by all four spawn legs sync/steer/background/fork, its persisted