@sema-agent/core 7.5.0 → 7.5.2

package/dist/core/runner/prepare-inherited-gate.js

@@ -0,0 +1,266 @@
+import { forkGovernanceDenial, resolveDelegationEntryCaps } from "../../agents/subagent.js";
+import { isLiveQuestionFace } from "../ask-question.js";
+import { createPreToolUseConstraintPolicy } from "../hooks.js";
+import { StubExecutionEnv } from "../stub-env.js";
+import { askApproverIdentity, isLiveApproverSeat } from "../tool-policy.js";
+import { attachRebuiltDenialTrackers, createDenialLimitStop } from "./denial-limit-arms.js";
+export function prepareInheritedGate(input) {
+    const { spec, deps, internals, resume, sessions, sessionId, runId, hostTaskId, taskRootFinal, executionEnv, ownedEnv, lockedPreflight, toolFaceSnapshot, promptProfile, resolvedInteractionPosture, autoModeSeat, handsEnabled, reportUsage, harnessRef, skillScope, forwardEvent, subagentRetain, worktreeIsolation, requestReview, requestStopAfterTurn, enterPlanMode, reminderMark, reminderDisclosureCounts, fileHistoryEnabled, historyScope, historyRoot, historyFs, abortRun } = input;
+    const liveInheritedGate = internals?.inheritedGate;
+    const seedInheritedGate = resume?.seed.inheritedGate;
+    const inheritedAncestorRules = (() => {
+        const seedRules = seedInheritedGate?.ancestorRules;
+        const liveRules = liveInheritedGate?.ancestorRules;
+        if (seedRules === undefined || seedRules.length === 0)
+            return liveRules ?? seedRules;
+        if (liveRules === undefined || liveRules.length === 0)
+            return seedRules;
+        const merged = seedRules.map((s) => {
+            const live = liveRules.find((l) => l.sessionId === s.sessionId && l.principal === s.principal);
+            return live !== undefined && live.rev >= s.rev ? live : s;
+        });
+        const extras = liveRules.filter((l) => !seedRules.some((s) => s.sessionId === l.sessionId && s.principal === l.principal));
+        return [...merged, ...extras];
+    })();
+    const shellGateRank = { off: 0, classify: 1, always: 2 };
+    const liveShellGate = liveInheritedGate?.shellGate;
+    const seedShellGate = seedInheritedGate?.shellGate;
+    const inheritedShellGate = liveShellGate === undefined
+        ? seedShellGate
+        : seedShellGate === undefined
+            ? liveShellGate
+            : shellGateRank[liveShellGate] >= shellGateRank[seedShellGate]
+                ? liveShellGate
+                : seedShellGate;
+    const inheritedParentConstraints = attachRebuiltDenialTrackers(liveInheritedGate?.parentConstraints, deps.autoMode?.denialLimit);
+    const autoModeIntent = autoModeSeat || liveInheritedGate?.autoModeRequested === true || seedInheritedGate?.autoModeRequested === true;
+    const liveAdmittedOrg = liveInheritedGate?.admittedOrgScopes;
+    const seedAdmittedOrg = seedInheritedGate?.admittedOrgScopes;
+    const inheritedAdmittedOrgScopes = liveAdmittedOrg === undefined ? seedAdmittedOrg : seedAdmittedOrg === undefined ? liveAdmittedOrg : liveAdmittedOrg.filter((s) => seedAdmittedOrg.includes(s));
+    const inheritedOrgGoverned = liveInheritedGate?.orgAdmissionGoverned === true || seedInheritedGate?.orgAdmissionGoverned === true;
+    const checkpointOwnOrgVerdict = resume?.seed.inheritedGate?.ownAdmittedOrgScopes !== undefined
+        ? { scopes: resume.seed.inheritedGate.ownAdmittedOrgScopes, writeScope: resume.seed.inheritedGate.ownAdmittedOrgWriteScope ?? null }
+        : undefined;
+    const refOwnOrgVerdict = internals?.ownOrgAdmissionRef?.current;
+    const priorOwnOrgVerdict = checkpointOwnOrgVerdict === undefined
+        ? refOwnOrgVerdict
+        : refOwnOrgVerdict === undefined
+            ? checkpointOwnOrgVerdict
+            : {
+                scopes: checkpointOwnOrgVerdict.scopes.filter((sc) => refOwnOrgVerdict.scopes.includes(sc)),
+                writeScope: checkpointOwnOrgVerdict.writeScope !== null && checkpointOwnOrgVerdict.writeScope === refOwnOrgVerdict.writeScope
+                    ? checkpointOwnOrgVerdict.writeScope
+                    : null,
+            };
+    const orgGovernedProvenance = deps.memoryScopeAdmission !== undefined ||
+        (deps.deploymentMemoryScopes !== undefined && deps.deploymentMemoryScopes.length > 0) ||
+        deps.compliancePostureResolver !== undefined ||
+        inheritedOrgGoverned ||
+        priorOwnOrgVerdict !== undefined;
+    const specShellGate = spec.shellGate ?? "off";
+    const effectiveShellGate = inheritedShellGate !== undefined && shellGateRank[inheritedShellGate] > shellGateRank[specShellGate] ? inheritedShellGate : specShellGate;
+    const ownSessionRulesRef = {};
+    const memoryAdmittedOrgScopesRef = { current: [] };
+    const ownOrgVerdictRef = { current: undefined };
+    const orgAdmissionCheckpointState = () => inheritedAdmittedOrgScopes !== undefined || ownOrgVerdictRef.current !== undefined || orgGovernedProvenance;
+    const faceCheckpointSection = () => {
+        const resolvedReadFace = input.resolvedReadFace();
+        const handsLessResolvedFace = input.handsLessResolvedFace();
+        const readDenyAdditionsNormalized = input.readDenyAdditionsNormalized();
+        if (resolvedReadFace === undefined && resume !== undefined) {
+            const seed = resume.seed.readFace;
+            return seed !== undefined ? { face: seed.face, ...(seed.denyEntries !== undefined ? { denyEntries: seed.denyEntries.map((e) => ({ ...e })) } : {}) } : undefined;
+        }
+        const face = resolvedReadFace ?? handsLessResolvedFace;
+        if (face === undefined)
+            return undefined;
+        if (face === "open" || readDenyAdditionsNormalized.length > 0) {
+            return { face, ...(readDenyAdditionsNormalized.length > 0 ? { denyEntries: readDenyAdditionsNormalized.map((e) => ({ ...e })) } : {}) };
+        }
+        return undefined;
+    };
+    const faceCheckpointState = () => faceCheckpointSection() !== undefined;
+    const f012CheckpointState = () => (inheritedParentConstraints?.length ?? 0) > 0 ||
+        seedInheritedGate?.constraintChain !== undefined ||
+        internals?.delegationProvenance !== undefined;
+    const frozenOnAsk = spec.onAsk ?? deps.onAsk;
+    const hookEnvSource = (ownedEnv ?? deps.executionEnv) != null ? executionEnv : undefined;
+    const notifyOwnHookCrash = (err) => {
+        try {
+            deps.onError?.(err instanceof Error ? err : new Error(String(err)), { phase: "hook", sessionId });
+        }
+        catch {
+        }
+    };
+    const frozenOnQuestion = spec.onQuestion ?? deps.onQuestion;
+    const provenanceForChildrenRef = {};
+    const delegationProvenanceForChildren = () => provenanceForChildrenRef.current;
+    const delegationSettlementRef = {};
+    const delegationSettlementForChildren = () => delegationSettlementRef.current;
+    const inheritedGateForChildren = () => {
+        const autoModeDecider = input.autoModeDecider();
+        const autoModeDenialTracking = input.autoModeDenialTracking();
+        const autoModeArming = input.autoModeArming();
+        const ancestorRules = [
+            ...(inheritedAncestorRules ?? []),
+            ...(ownSessionRulesRef.current !== undefined ? [ownSessionRulesRef.current] : []),
+        ];
+        const ownCallerPolicy = lockedPreflight.toolPolicy;
+        const durableMandate = input.runtimeCaps()?.forceDurableGate === true ||
+            (spec.durableApproval !== undefined && !isLiveApproverSeat(frozenOnAsk));
+        const contentMandate = input.runtimeCaps()?.forceDurableGate === true ||
+            (spec.durableApproval !== undefined && !isLiveQuestionFace(frozenOnQuestion));
+        const ownPreToolUse = input.preToolUseObservational() ? undefined : input.hooks()?.preToolUse;
+        const hookConstraint = ownPreToolUse !== undefined &&
+            !(inheritedParentConstraints ?? []).some((pc) => pc.preToolUse === ownPreToolUse &&
+                askApproverIdentity(pc.onAsk) === askApproverIdentity(frozenOnAsk) &&
+                (pc.durableMandate === true) === durableMandate &&
+                (pc.contentMandate === true) === contentMandate &&
+                pc.hookEnv === hookEnvSource &&
+                pc.autoMode?.decider === autoModeDecider)
+            ? [
+                {
+                    policy: createPreToolUseConstraintPolicy(ownPreToolUse, input.hookEnvFace(), notifyOwnHookCrash, input.hookTimeoutMs()),
+                    preToolUse: ownPreToolUse,
+                    ...(hookEnvSource !== undefined ? { hookEnv: hookEnvSource } : {}),
+                    ...(frozenOnAsk !== undefined ? { onAsk: frozenOnAsk } : {}),
+                    ...(durableMandate ? { durableMandate: true } : {}),
+                    ...(contentMandate ? { contentMandate: true } : {}),
+                    ...(autoModeDecider !== undefined
+                        ? { autoMode: { decider: autoModeDecider, ...(autoModeDenialTracking !== undefined ? { denialTracking: autoModeDenialTracking } : {}), ...(autoModeArming !== undefined ? { arming: autoModeArming } : {}) } }
+                        : {}),
+                },
+            ]
+            : [];
+        const parentConstraints = [
+            ...(inheritedParentConstraints ?? []),
+            ...hookConstraint,
+            ...(ownCallerPolicy !== undefined
+                ? [
+                    {
+                        policy: ownCallerPolicy,
+                        ...(frozenOnAsk !== undefined ? { onAsk: frozenOnAsk } : {}),
+                        ...(durableMandate ? { durableMandate: true } : {}),
+                        ...(contentMandate ? { contentMandate: true } : {}),
+                        ...(autoModeDecider !== undefined
+                            ? { autoMode: { decider: autoModeDecider, ...(autoModeDenialTracking !== undefined ? { denialTracking: autoModeDenialTracking } : {}), ...(autoModeArming !== undefined ? { arming: autoModeArming } : {}) } }
+                            : {}),
+                    },
+                ]
+                : []),
+        ];
+        return {
+            ...(ancestorRules.length > 0 ? { ancestorRules } : {}),
+            ...(effectiveShellGate !== "off" ? { shellGate: effectiveShellGate } : {}),
+            ...(autoModeIntent ? { autoModeRequested: true } : {}),
+            ...(parentConstraints.length > 0 ? { parentConstraints } : {}),
+            admittedOrgScopes: memoryAdmittedOrgScopesRef.current,
+            ...(orgGovernedProvenance ? { orgAdmissionGoverned: true } : {}),
+        };
+    };
+    const carrierReadFace = () => input.resolvedReadFace() ?? input.handsLessResolvedFace();
+    const fullShellReachable = handsEnabled &&
+        !(executionEnv instanceof StubExecutionEnv) &&
+        spec.handsReadOnly !== true &&
+        !(toolFaceSnapshot.exclude?.includes("Bash") ?? false);
+    const { gateStopRef, stopForDenialLimit } = createDenialLimitStop({ sessionId, runId, onNotice: deps.onNotice, abort: abortRun });
+    const delegationEntryCapsResolved = resolveDelegationEntryCaps(deps.delegationEntryCaps);
+    const enrichSpecToolCtx = (ctx) => {
+        const agentForkDenial = input.agentForkDenial();
+        const observersActive = input.observersActive();
+        const readDenyAdditionsNormalized = input.readDenyAdditionsNormalized();
+        const autoModeDecider = input.autoModeDecider();
+        const centerAdoption = input.centerAdoption();
+        return {
+            ...ctx,
+            delegationEntryCaps: delegationEntryCapsResolved,
+            reportUsage,
+            model: harnessRef.current?.getModel(),
+            thinkingLevel: harnessRef.current?.getThinkingLevel(),
+            principal: spec.principal,
+            ...(frozenOnAsk !== undefined ? { onAsk: frozenOnAsk } : {}),
+            ...(frozenOnQuestion !== undefined ? { onQuestion: frozenOnQuestion } : {}),
+            ...(spec.handsReadOnly === true ? { handsReadOnly: true } : {}),
+            ...(carrierReadFace() === "roots" ? { readFace: "roots" } : {}),
+            ...(readDenyAdditionsNormalized.length > 0 ? { readDenyPatterns: Object.freeze(readDenyAdditionsNormalized.map((e) => ({ ...e }))) } : {}),
+            ...(spec.interactiveTools === false ? { interactiveTools: false } : {}),
+            oneShot: spec.oneShot,
+            clientContext: spec.clientContext,
+            excludeTools: toolFaceSnapshot.exclude,
+            deferTools: toolFaceSnapshot.defer,
+            alwaysLoadTools: toolFaceSnapshot.alwaysLoad,
+            ...(toolFaceSnapshot.restoreGated !== undefined ? { restoreGatedTools: toolFaceSnapshot.restoreGated } : {}),
+            promptProfile,
+            ...(spec.additionalDirectories !== undefined ? { additionalDirectories: Object.freeze([...spec.additionalDirectories]) } : {}),
+            ...(spec.additionalReadDirectories !== undefined ? { additionalReadDirectories: Object.freeze([...spec.additionalReadDirectories]) } : {}),
+            ...(spec.envFacts !== undefined ? { envFacts: { ...spec.envFacts } } : {}),
+            ...(spec.memoryPersistenceCapable !== undefined ? { memoryPersistenceCapable: spec.memoryPersistenceCapable } : {}),
+            get memoryCaptureOptedOut() {
+                return input.memoryEngineSession()?.captureOptOut?.optedOut() ?? false;
+            },
+            get memoryCaptureIndeterminate() {
+                return input.memoryEngineSession()?.captureOptOut?.indeterminate() ?? false;
+            },
+            get memoryCaptureControlDir() {
+                return input.memoryEngineSession()?.engine.controlPlaneDir;
+            },
+            get memoryCaptureAncestors() {
+                const ctl = input.memoryEngineSession()?.engine.controlPlaneDir;
+                return [...(internals?.memoryCaptureAncestors ?? []), { sessionId, ...(ctl !== undefined ? { controlDir: ctl } : {}) }];
+            },
+            getApiKeyAndHeaders: spec.getApiKeyAndHeaders,
+            parentCwd: taskRootFinal,
+            ...(fileHistoryEnabled ? { fileHistoryLineage: { scope: historyScope, root: historyRoot, fs: historyFs } } : {}),
+            reminderMark,
+            reminderDisclosureCounts,
+            ...(centerAdoption !== undefined ? { centerArtifactDigest: centerAdoption.artifact.artifactDigest } : {}),
+            ...(centerAdoption?.sourceRevision !== undefined ? { centerSourceRevision: centerAdoption.sourceRevision } : {}),
+            activeSkillScope: () => skillScope.active(),
+            inheritedGateForChildren,
+            delegationProvenanceForChildren,
+            delegationSettlement: delegationSettlementForChildren,
+            ...(autoModeDecider ? { autoModeReview: { decider: autoModeDecider } } : {}),
+            ...(spec.durableApproval !== undefined ? { durableApprovalForChildren: { ...spec.durableApproval } } : {}),
+            ...(spec.checkpointStore === null ? { checkpointStoreDisabledForChildren: true } : {}),
+            taskId: hostTaskId,
+            ...(internals?.parentTaskId !== undefined ? { parentTaskId: internals.parentTaskId } : {}),
+            ...(internals?.parentSessionId !== undefined ? { parentSessionId: internals.parentSessionId } : {}),
+            ...(internals?.rootSessionId !== undefined ? { rootSessionId: internals.rootSessionId } : {}), ...(internals?.placementRoot !== undefined ? { placementRoot: internals.placementRoot } : {}),
+            ...(internals?.explicitAgentName !== undefined ? { spawnedAgentName: internals.explicitAgentName } : {}),
+            ...(internals?.peerSelfRef !== undefined ? { peerSelfRef: internals.peerSelfRef } : {}),
+            ...(internals?.peerInboundChainRef !== undefined ? { peerInboundChainRef: internals.peerInboundChainRef } : {}),
+            ...(deps.rosterStore !== undefined ? { roster: deps.rosterStore } : {}),
+            ...(sessions.fork !== undefined
+                ? {
+                    hostSessionFork: async () => {
+                        const forked = (await sessions.fork(sessionId, spec.principal ?? null)) ?? null;
+                        if (forked === null)
+                            return null;
+                        return {
+                            sessionId: forked,
+                            release: async () => {
+                                await sessions.release?.(forked);
+                            },
+                        };
+                    },
+                }
+                : {}),
+            sessionId,
+            ...(spec.backgroundScope !== undefined ? { backgroundScope: spec.backgroundScope } : {}),
+            ...(resolvedInteractionPosture !== undefined ? { interactionPosture: resolvedInteractionPosture } : {}),
+            ...(deps.onBackgroundChildEvent ? { onBackgroundChildEvent: deps.onBackgroundChildEvent } : {}),
+            ...(internals?.onTaskNotification ? { onTaskNotification: internals.onTaskNotification } : {}),
+            ...(forwardEvent ? { forwardEvent } : {}),
+            ...(internals?.onSubagentSpawn ? { onSubagentSpawn: internals.onSubagentSpawn } : {}),
+            ...(subagentRetain ? { subagentRetain } : {}),
+            ...(worktreeIsolation ? { worktreeIsolation } : {}),
+            ...(internals?.insideFork === true ? { insideFork: true } : {}),
+            ...(agentForkDenial !== undefined ? { forkAccess: { denied: agentForkDenial } } : {}),
+            ...(observersActive ? { observersAllowed: true } : {}),
+            requestReview,
+            requestStopAfterTurn,
+            ...(spec.enablePlanMode === true ? { enterPlanMode } : {}),
+        };
+    };
+    return { liveInheritedGate, seedInheritedGate, inheritedAncestorRules, inheritedShellGate, inheritedParentConstraints, autoModeIntent, inheritedAdmittedOrgScopes, priorOwnOrgVerdict, orgGovernedProvenance, effectiveShellGate, ownSessionRulesRef, memoryAdmittedOrgScopesRef, ownOrgVerdictRef, orgAdmissionCheckpointState, faceCheckpointSection, faceCheckpointState, f012CheckpointState, frozenOnAsk, hookEnvSource, notifyOwnHookCrash, frozenOnQuestion, provenanceForChildrenRef, delegationSettlementRef, inheritedGateForChildren, carrierReadFace, fullShellReachable, gateStopRef, stopForDenialLimit, enrichSpecToolCtx };
+}

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

@@ -0,0 +1,77 @@
+/**
+ * design/390 M15 — prepareTask's LISTINGS phase: the per-task agent definitions' tool-name audit
+ * (deny entries fail loud, allow entries advise), the agent-listing announce face read off the
+ * delegation tool's roster (with its deferred / excluded / removal-to-zero arms), the two listing
+ * opt-out advisories, the announced-listings mirror seeded from the once-per-session ledger, the
+ * deferred roster's ToolSearch ride, and the date_change seam. The body is the driver's stretch moved
+ * verbatim; the interface is the dependency list it had implicitly (design/238 R-1).
+ *
+ * SYNCHRONOUS FUNCTION, SYNCHRONOUS CALL: the stretch has no await, so the phase adds no yield between
+ * the disclosure mount before it and the context-lane seats after it (design/390 §1.5 S1: a stretch
+ * with no await is extracted as a sync function — an `async` wrapper would open a microtask window).
+ *
+ * Throws pass through unchanged: `config.agent.unknown_tool` (a deny entry naming a tool this
+ * deployment does not mount — a typo there would silently guard nothing).
+ */
+import type { AgentTool } from "../../internal/harness.js";
+import type { TaskSpec } from "../types.js";
+import type { AnnounceOnceSink, Prepared, PrepareResume, ToolFaceSnapshot } from "./contracts.js";
+import type { AnnouncedListingSnapshot } from "../../internal/harness.js";
+export interface PrepareListingsInput {
+    /** borrowed-readonly — the REBOUND spec (`spec′`). Read: `agents` (the audit's subject), `tools`
+     *  (the roster-bearing delegation tool, by its `agentListing` marker), `sessionId` (continuation
+     *  ⇒ seeded/removal projections), `attachments` (the two opt-outs). Never mutated. */
+    spec: Pick<TaskSpec, "agents" | "tools" | "sessionId" | "attachments">;
+    /** borrowed-readonly — the FULLY ASSEMBLED mount array (names + aliases = the audit's universe).
+     *  Read only; this phase never mutates the roster. */
+    tools: ReadonlyArray<AgentTool>;
+    /** borrowed-readonly — the once-per-session ledger: its deduplicated operator sink (`onError`) and
+     *  the whole announced snapshot (`arms()`) the mirror is seeded from. */
+    onceLedger: AnnounceOnceSink & {
+        arms(): AnnouncedListingSnapshot;
+    };
+    /** borrowed-readonly — the acquired session's id (operator-line context). */
+    sessionId: string;
+    /** borrowed-readonly — the frozen tool face: `exclude` / `defer` decide the roster face's arm. */
+    toolFaceSnapshot: Pick<ToolFaceSnapshot, "exclude" | "defer">;
+    /** borrowed-readonly — the activated deferred names as of prepare (transcript replay / checkpoint
+     *  seed); only `has()` is read: an already-ACTIVE roster tool un-defers its listing face. The set
+     *  keeps mutating mid-run (ToolSearch activations) — this phase reads it once, here. */
+    activeTools: ReadonlySet<string>;
+    /** borrowed-readonly — the durable-resume carrier: presence (seedAnnounced) and
+     *  `seed.announcedListings.agents` (the removal-to-zero projection's gate). */
+    resume: Pick<PrepareResume, "seed"> | undefined;
+    /** borrowed-readonly — the project-context phase's skills-listing projection; read only for the
+     *  skills opt-out advisory (entries.length). */
+    skillsListing: Prepared["skillsListing"];
+    /** borrowed-mutable — the deferred roster's ToolSearch RIDE seat (declared by the disclosure
+     *  mount, read at activation time through `listingRideRef.current?.(newly)`). Written here, once,
+     *  on a deferred roster face; no later writer. Identity is the contract (the mount's closures read
+     *  this exact cell). */
+    listingRideRef: {
+        current?: (newly: readonly string[]) => string | undefined;
+    };
+    /** borrowed-readonly — the prompt assembly's date re-renderer; presence alone decides whether the
+     *  date_change seam exists (a provider that owns the whole prompt has none). */
+    renderWithDate: ((date: string) => string) | undefined;
+    /** borrowed-readonly — the environment facts; only `date` is read (the leg's frozen date). */
+    envFacts: {
+        readonly date?: string;
+    };
+    /** borrowed-readonly — whether the client zone validated (the seam re-judges "today" in it). */
+    tzValid: boolean;
+    /** borrowed-readonly — the client's declared zone (used only when `tzValid`). */
+    userTz: string | undefined;
+}
+export interface PrepareListingsResult {
+    /** owned — the agent-listing announce projection (`Prepared.agentListing`): the roster off the
+     *  delegation tool's effective face, the removal-to-zero projection, or undefined (silent). */
+    agentListing: Prepared["agentListing"];
+    /** owned — the announced-listings mirror seeded from the ledger's whole snapshot
+     *  (`Prepared.announcedListingsRef`); the run loop and the checkpoint serializer write it from here on. */
+    announcedListingsRef: Prepared["announcedListingsRef"];
+    /** owned — the date_change seam (`Prepared.dateChange`), or undefined when the prompt has no date re-renderer. */
+    dateChange: Prepared["dateChange"];
+}
+/** The M15 phase body — prepareTask's listings stretch, verbatim (see the module header). */
+export declare function prepareListings(input: PrepareListingsInput): PrepareListingsResult;

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

@@ -0,0 +1,76 @@
+import { formatLocalDate } from "../../prompts/default.js";
+import { SKILL_TOOL_NAME } from "./synthetic-tools.js";
+import { renderAgentListingDelta } from "./turn-attachments.js";
+export function prepareListings(input) {
+    const { spec, tools, onceLedger, sessionId, toolFaceSnapshot, activeTools, resume, skillsListing, listingRideRef, renderWithDate, envFacts, tzValid, userTz } = input;
+    if (spec.agents !== undefined && spec.agents.length > 0) {
+        const known = new Set(tools.flatMap((t) => [t.name, ...(t.aliases ?? [])]));
+        for (const def of spec.agents) {
+            const unknownAllow = (def.allowTools ?? []).filter((n) => n !== "*" && !known.has(n));
+            if (unknownAllow.length > 0) {
+                try {
+                    onceLedger.onError(new Error(`TaskSpec.agents: agent "${def.name}" allows tool(s) ${unknownAllow.join(", ")} not present in this task's assembled roster — likely a typo (the entry would be item-filtered at spawn; the agent stays usable). Advisory only: the delegation pool can differ from this roster, so a tool mounted only on the delegation tool or produced by per-spawn extraTools makes this spurious.`), { phase: "config", sessionId });
+                }
+                catch {
+                }
+            }
+            for (const n of def.denyTools ?? []) {
+                if (n === "*")
+                    continue;
+                if (!known.has(n)) {
+                    const e = new Error(`TaskSpec.agents: agent "${def.name}" declares tool "${n}" in its denied tools, but no such tool exists in this deployment — fix the agent's tools list or mount the tool.`);
+                    e.code = "config.agent.unknown_tool";
+                    throw e;
+                }
+            }
+        }
+    }
+    const rosterBearingSpec = (spec.tools ?? []).find((t) => t.agentListing !== undefined && t.agentListing.length > 0);
+    const rosterFaceDeferred = rosterBearingSpec !== undefined &&
+        !(toolFaceSnapshot.exclude?.includes(rosterBearingSpec.name) ?? false) &&
+        (toolFaceSnapshot.defer?.includes(rosterBearingSpec.name) ?? false) &&
+        !activeTools.has(rosterBearingSpec.name);
+    const agentListingSpec = rosterBearingSpec !== undefined &&
+        !rosterFaceDeferred &&
+        !(toolFaceSnapshot.exclude?.includes(rosterBearingSpec.name) ?? false)
+        ? rosterBearingSpec
+        : undefined;
+    const agentListing = agentListingSpec
+        ? {
+            entries: agentListingSpec.agentListing,
+            toolName: agentListingSpec.name,
+            seedAnnounced: resume !== undefined || spec.sessionId !== undefined,
+            ...(agentListingSpec.agentModels !== undefined ? { models: agentListingSpec.agentModels } : {}),
+        }
+        :
+            !rosterFaceDeferred && ((resume?.seed.announcedListings?.agents?.length ?? 0) > 0 || spec.sessionId !== undefined)
+                ?
+                    {
+                        entries: [],
+                        toolName: (spec.tools ?? []).find((t) => t.agentListing !== undefined)?.name ?? "Agent",
+                        seedAnnounced: true,
+                    }
+                : undefined;
+    if (spec.attachments?.agentListing === false && agentListing !== undefined && agentListing.entries.length > 0) {
+        onceLedger.onError(new Error(`attachments.agentListing is explicitly false but the "${agentListing.toolName}" delegation tool mounts a ${agentListing.entries.length}-type roster — the model will never see the agent-type listing its tool description points to.`), { phase: "config", sessionId });
+    }
+    if (spec.attachments?.skillsListing === false && skillsListing !== undefined && skillsListing.entries.length > 0) {
+        onceLedger.onError(new Error(`attachments.skillsListing is explicitly false but ${skillsListing.entries.length} skill(s) are mounted — the model will never see the skills listing the ${SKILL_TOOL_NAME} tool description points to.`), { phase: "config", sessionId });
+    }
+    const announcedListingsRef = onceLedger.arms();
+    if (rosterFaceDeferred && rosterBearingSpec !== undefined) {
+        const rideEntries = rosterBearingSpec.agentListing;
+        const rideModels = rosterBearingSpec.agentModels;
+        listingRideRef.current = (newly) => {
+            if (!newly.includes(rosterBearingSpec.name))
+                return undefined;
+            if ((announcedListingsRef.agents?.length ?? 0) > 0)
+                return undefined;
+            return renderAgentListingDelta({ announcedAgentTypes: undefined }, rideEntries, rosterBearingSpec.name, rideModels);
+        };
+    }
+    const dateChange = renderWithDate
+        ? { legDate: envFacts.date, today: () => formatLocalDate(new Date(), tzValid ? userTz : undefined) }
+        : undefined;
+    return { agentListing, announcedListingsRef, dateChange };
+}

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

@@ -0,0 +1,55 @@
+/**
+ * design/390 §1.2 M8 — prepareTask's LSP phase, verbatim from the driver: the manager fold (spec > deps), the
+ * LSP tool mount over the per-task env with its git-ignore filter, the diagnostics lane behind its four
+ * preconditions (a manager whose sessions feed a registry, write-capable hands, not opted out), the run-scoped
+ * registry key, and the edit nudge (raw path → the SAME resolution the tool leg uses → registry reset +
+ * session didChange). No manager ⇒ nothing mounts and both lane seats are undefined. The interface is the
+ * dependency list the segment had implicitly (design/238 R-1).
+ *
+ * SYNCHRONOUS FUNCTION, SYNCHRONOUS CALL: the stretch has no await, so the phase adds no yield between the
+ * fork-governance note before it and the memory trio's occupancy read after it (design/390 §1.5 S1: a stretch
+ * with no await is extracted as a sync function — an `async` wrapper would open a microtask window).
+ * Read-stability of the host handles for the call: {@link RunInternals} (`@contract prepare.deps-read-stable`).
+ */
+import type { AgentTool, ExecutionEnv } from "../../internal/harness.js";
+import type { LspDiagnosticsRegistry } from "../lsp-diagnostics.js";
+import type { RunnerDeps, TaskSpec } from "../types.js";
+import type { Prepared } from "./contracts.js";
+export interface PrepareLspInput {
+    /** borrowed-readonly — the REBOUND spec. Read: `lspManager` (the per-task manager, outranks the deployment's),
+     *  `lspDiagnostics` (the lane's opt-out), `handsReadOnly` (a read-only run has no lane). Never mutated. */
+    spec: Pick<TaskSpec, "lspManager" | "lspDiagnostics" | "handsReadOnly">;
+    /** borrowed-readonly — the deployment's manager seat (read only when the spec carries none). */
+    deps: Pick<RunnerDeps, "lspManager">;
+    /** borrowed-readonly — the run's resolved env: the tool's in-env server and git-ignore filter, and the
+     *  session lookup the nudge performs. */
+    executionEnv: ExecutionEnv;
+    /** borrowed-readonly — the SETTLED task root: the tool's git-ignore root, and the nudge's resolution base when
+     *  no cwd is tracked. */
+    taskRootFinal: string;
+    /** borrowed-readonly — whether a real fs env is present (the lane's hands precondition). */
+    handsEnabled: boolean;
+    /** borrowed-readonly — the acquired session id: the run's key into the deployment-shared registry. */
+    sessionId: string;
+    /** borrowed-readonly — the tracked-cwd cell the hands band writes; the nudge READS `current` per call as its
+     *  resolution base (identity is the contract — the band's `cd` handling writes this exact cell). */
+    handsCwdRef: Prepared["cwdRef"];
+    /** borrowed-mutable — the run's shared roster (identity is the contract). Writer here: ONE push (the LSP tool)
+     *  when a manager exists. */
+    tools: AgentTool[];
+    /** borrowed-mutable — the env-hand membership set the read-posture observer projects; writer here: `add("LSP")`
+     *  on the mount. */
+    envHandToolNames: Set<string>;
+}
+export interface PrepareLspResult {
+    /** borrowed-readonly — the manager's diagnostics registry when the lane is live, else undefined (the
+     *  registry is a DEPLOYMENT object shared by every task; this run reads and resets it under its own key). */
+    lspDiagnostics: LspDiagnosticsRegistry | undefined;
+    /** owned — the edit nudge (raw path in), or undefined when the lane is not live. */
+    nudgeLspOnEdit: ((rawPath: string) => void) | undefined;
+    /** borrowed-readonly — the run's registry key (= the session id): a session hosts one run at a time and the
+     *  run loop releases the key at the terminal. */
+    lspRunIdent: string;
+}
+/** The M8 phase body — prepareTask's LSP stretch, verbatim (see the module header). */
+export declare function prepareLsp(input: PrepareLspInput): PrepareLspResult;

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

@@ -0,0 +1,27 @@
+import { createLspTool, gitCheckIgnoreFilter, resolveLspPath } from "../lsp.js";
+import { pathToUri } from "../lsp-protocol.js";
+export function prepareLsp(input) {
+    const { spec, deps, executionEnv, taskRootFinal, handsEnabled, sessionId, handsCwdRef, tools, envHandToolNames } = input;
+    const lspManager = spec.lspManager ?? deps.lspManager;
+    if (lspManager) {
+        const lspRoot = taskRootFinal;
+        tools.push(createLspTool(lspManager, { isPathIgnored: gitCheckIgnoreFilter(executionEnv, lspRoot), env: executionEnv }));
+        envHandToolNames.add("LSP");
+    }
+    const lspDiagnostics = spec.lspDiagnostics !== false && lspManager?.diagnostics !== undefined && handsEnabled && spec.handsReadOnly !== true
+        ? lspManager.diagnostics
+        : undefined;
+    const lspRunIdent = sessionId;
+    const nudgeLspOnEdit = lspDiagnostics
+        ? (rawPath) => {
+            const baseDir = handsCwdRef?.current ?? taskRootFinal;
+            const filePath = resolveLspPath(rawPath, baseDir);
+            lspDiagnostics.fileEdited(lspRunIdent, pathToUri(filePath));
+            void lspManager
+                .sessionFor(filePath, undefined, executionEnv)
+                .then((session) => session?.notifyFileChanged?.(filePath))
+                .catch(() => undefined);
+        }
+        : undefined;
+    return { lspDiagnostics, nudgeLspOnEdit, lspRunIdent };
+}

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

@@ -0,0 +1,84 @@
+/**
+ * design/390 §1.2 M12 — prepareTask's MEMORY-ENGINE-SESSION phase, verbatim from the driver: the content-origin
+ * classification + one-way session pollution wrap section (design/178 §3 / design/180 half A / design/324 /
+ * design/336 §3.3 + §5.5 / design/378 D-4 / design/380 O9a). Its arming predicate (a mounted memory session OR an
+ * upstream recorder channel), the chain-narrowed classification config, the children's provenance seat, the
+ * declared-MCP-class announcement, the settlement seat, the per-tool wrap with its three record verbs (mark /
+ * recordExternal / recordIncomplete), the Read tool's recall-taint arm and the delegation arm's three-valued
+ * attestation judgment all live here; the announcement helper only this section called moved with it. The
+ * interface is the dependency list the segment had implicitly (design/238 R-1).
+ *
+ * SYNCHRONOUS FUNCTION, SYNCHRONOUS CALL: the stretch has no await of its own (the awaits sit inside the wrappers it
+ * installs, which run at tool-call time), so the phase adds no yield between the deferred classification before it
+ * and the prompt assembly after it (design/390 §1.5: a stretch with no await is extracted as a sync function).
+ * Read-stability of the host handles for the call: {@link RunInternals} (`@contract prepare.deps-read-stable`).
+ *
+ * One read changed spelling and nothing else: the declared-class announcement read `mcp?.statuses` while `mcp` had
+ * long been the protocol-tools phase's non-null handle; the optional chain was dead and is now the plain member read.
+ */
+import type { AgentTool } from "../../internal/harness.js";
+import type { LockedPreflight } from "../locked-config.js";
+import type { MaterializedMcp } from "../mcp.js";
+import { type DelegationContentSafety } from "../memory-engine/delegation-provenance.js";
+import type { RunnerDeps, TaskSpec } from "../types.js";
+import type { Prepared, RunInternals } from "./contracts.js";
+export interface PrepareMemoryEngineSessionInput {
+    /** borrowed-readonly — the mounted engine session, or undefined (the ARMING fact's first half). Read: `pollution`
+     *  (the mark face), `contentSafety` (the own half of the narrowing), `settlement` (the seat + the receipt ledger),
+     *  `recallTaint` (the Read arm's judge). Never mutated; the wrappers call `pollution.markPolluted` at tool-call time. */
+    memoryEngineSession: Prepared["memoryEngineSession"];
+    /** borrowed-mutable — the trusted spawn-side channel; only `delegationProvenance` (the ARMING fact's second half: the
+     *  recorder channel with the chain's frozen `contentSafety`). Writers: the wrappers this phase installs set
+     *  `delegationProvenance.ref.current.sawExternal` / `.incomplete` at tool-call time (monotonic, never cleared). */
+    internals: Pick<RunInternals, "delegationProvenance"> | undefined;
+    /** borrowed-readonly — the doors' per-leg SNAPSHOT of `RunnerDeps.memoryDelegationEvidence` (screened in the
+     *  synchronous pre-await stretch; never a live deps re-read here). */
+    memoryDelegationEvidence: "static-face" | "attested-only";
+    /** borrowed-readonly — the run's external-content-target fold (live adapter declaration OR the persisted bit). */
+    externalContentTargetActive: boolean;
+    /** borrowed-readonly — the frozen preflight; only `mcp` (the declared entries the announcement walks). */
+    lockedPreflight: Pick<LockedPreflight, "mcp">;
+    /** borrowed-readonly — the materialized MCP handle; only `statuses` (the announcement's mounted-tool count). */
+    mcp: Pick<MaterializedMcp, "statuses">;
+    /** borrowed-readonly — the acquired session id (notice detail). */
+    sessionId: string;
+    /** borrowed-readonly — the run's invocation id (notice detail; the once-per-leg claims are per-RUN claims). */
+    runId: string;
+    /** borrowed-readonly — the deployment seats; only `onNotice` (the declared-class line and the waiver notice). */
+    deps: Pick<RunnerDeps, "onNotice">;
+    /** borrowed-mutable — the children's provenance seat (the inherited-gate phase mints it; `inheritedGateForChildren`
+     *  reads it late). Writer: THIS phase, once at arming, to the effective (chain-narrowed) config. */
+    provenanceForChildrenRef: {
+        current?: DelegationContentSafety;
+    };
+    /** borrowed-mutable — the children's settlement seat (the inherited-gate phase mints it). Writer: THIS phase, once at
+     *  arming, when the memory session mounted a settlement (memoryProvenance "carry"). */
+    delegationSettlementRef: {
+        current?: {
+            controlDir: string;
+            sessionId: string;
+        };
+    };
+    /** borrowed-readonly — the REBOUND spec; only `tools` (the RAW caller specs: caller-tool names and the marker-bearing
+     *  delegation entries — the assembled roster objects carry neither marker). Never mutated. */
+    spec: Pick<TaskSpec, "tools">;
+    /** borrowed-readonly — the env-hand roster (membership minted at the mount sites); read by the classification. */
+    envHandToolNames: ReadonlySet<string>;
+    /** borrowed-mutable — the run's ONE tool roster. Writer here: the wrap pass REPLACES entries in place
+     *  (`tools[i] = wrapped`, identity-tracked so a re-run never stacks wrappers); see the roster's writer table on
+     *  {@link Prepared.tools}. */
+    tools: AgentTool[];
+    /** borrowed-mutable — the re-runnable wrap pass's seat (the protocol-tools phase mints it; the rebuild seam re-runs it
+     *  after a refresh re-splice). Writer: THIS phase installs the pass and runs it once. */
+    contentOriginWrapRef: {
+        current?: () => void;
+    };
+}
+export interface PrepareMemoryEngineSessionResult {
+    /** owned — whether the section ARMED on this leg (a memory session or a recorder channel existed): armed ⇒ every
+     *  roster tool was classified and the polluting/delegation/Read-plane ones wrapped; not armed ⇒ zero wraps, zero
+     *  announcements, both children's seats untouched. */
+    armed: boolean;
+}
+/** The M12 phase body — prepareTask's content-origin wrap stretch, verbatim (see the module header). */
+export declare function prepareMemoryEngineSession(input: PrepareMemoryEngineSessionInput): PrepareMemoryEngineSessionResult;