@sema-agent/core 7.4.0 → 7.5.1

package/dist/core/runner/prepare-defer-classify.js

@@ -0,0 +1,107 @@
+import { getToolContract } from "../../prompt-assembly/tool-catalog.js";
+import { FULL_SHELL_CONTRACT_ID } from "../../tools/fs/index.js";
+import { ASK_USER_QUESTION_TOOL_NAME } from "../ask-question.js";
+import { MEMORY_ENGINE_TOOL_NAMES } from "../memory-engine/tools.js";
+import { SHARED_MEMORY_TOOL_NAMES } from "../shared-memory/types.js";
+import { TOOL_SEARCH_NAME, classifyDeferred } from "./tool-disclosure.js";
+function explicitlyDeferredMemoryTrio(mounted, roster, deferNames) {
+    return mounted ? MEMORY_ENGINE_TOOL_NAMES.filter((n) => roster.some((t) => t.name === n) && (deferNames ?? []).includes(n)) : [];
+}
+function memoryGroupRetractionSet(builtinDeferPairNames, engineTrioInPlay) {
+    return new Set([...builtinDeferPairNames, ...(engineTrioInPlay ? MEMORY_ENGINE_TOOL_NAMES : [])]);
+}
+export function prepareDeferClassify(input) {
+    const { spec, deps, tools, toolFaceSnapshot, handsEnabled, fullShellReachable, promptProfile, model, mcp, a2a, sharedMemoryPairMounted, memoryEnginePairMounted, memoryRecallSegment, onceLedger, sessionId } = input;
+    let memoryBlock = input.memoryBlock;
+    if (toolFaceSnapshot.exclude !== undefined && toolFaceSnapshot.exclude.length > 0) {
+        const excluded = new Set(toolFaceSnapshot.exclude);
+        for (let i = tools.length - 1; i >= 0; i--)
+            if (excluded.has(tools[i].name))
+                tools.splice(i, 1);
+    }
+    if (handsEnabled) {
+        const fullShellOnRoster = tools.some((t) => t.name === "Bash" && getToolContract(t, "core").contractId === FULL_SHELL_CONTRACT_ID);
+        if (fullShellOnRoster !== fullShellReachable) {
+            const e = new Error(`internal invariant: fullShellReachable=${String(fullShellReachable)} but the post-exclusion roster ` +
+                `${fullShellOnRoster ? "carries" : "does not carry"} the full shell (${FULL_SHELL_CONTRACT_ID}). ` +
+                `A new roster-affecting mechanism was added without updating the predicate.`);
+            e.code = "internal.full_shell_reachable_mismatch";
+            throw e;
+        }
+    }
+    if (promptProfile === "classic") {
+        for (let i = 0; i < tools.length; i++) {
+            const t = tools[i];
+            if (t.descriptionClassic !== undefined)
+                tools[i] = { ...t, description: t.descriptionClassic };
+        }
+    }
+    const userToolNames = (spec.tools ?? []).map((t) => t.name);
+    const protocolToolNames = [...mcp.tools.map((t) => t.name), ...a2a.tools.map((t) => t.name)];
+    const mcpAlwaysLoadNames = mcp.tools
+        .filter((t) => t.mcpAlwaysLoad === true && !(toolFaceSnapshot.defer ?? []).includes(t.name))
+        .map((t) => t.name);
+    const classifyDeferredOverFace = (face, builtinDeferNames) => {
+        const deferredSet = classifyDeferred({
+            specs: spec.tools ?? [],
+            protocolToolNames,
+            fullTools: face.filter((t) => userToolNames.includes(t.name) || protocolToolNames.includes(t.name)),
+            deferMode: deps.deferMode,
+            model,
+            deferNames: [...(toolFaceSnapshot.defer ?? []), ...builtinDeferNames].filter((n) => face.some((t) => t.name === n)),
+            alwaysLoadNames: [
+                ASK_USER_QUESTION_TOOL_NAME,
+                ...(toolFaceSnapshot.alwaysLoad ?? []),
+                ...mcpAlwaysLoadNames,
+            ],
+        });
+        for (const n of [...deferredSet]) {
+            if (!face.some((t) => t.name === n))
+                deferredSet.delete(n);
+        }
+        return deferredSet;
+    };
+    const sharedMemoryPair = sharedMemoryPairMounted ? SHARED_MEMORY_TOOL_NAMES.filter((n) => tools.some((t) => t.name === n)) : [];
+    const memoryEnginePair = explicitlyDeferredMemoryTrio(memoryEnginePairMounted, tools, toolFaceSnapshot.defer);
+    const builtinDeferPairNames = [...sharedMemoryPair, ...memoryEnginePair];
+    let deferred;
+    if (builtinDeferPairNames.length > 0) {
+        const withoutPairs = tools.filter((t) => !builtinDeferPairNames.some((n) => n === t.name));
+        const d1 = classifyDeferredOverFace(tools, builtinDeferPairNames);
+        const d0 = classifyDeferredOverFace(withoutPairs, []);
+        const soleCause = d0.size === 0 && d1.size > 0;
+        const supportNameTaken = tools.some((t) => t.name === TOOL_SEARCH_NAME || (t.aliases ?? []).includes(TOOL_SEARCH_NAME));
+        if (soleCause && supportNameTaken) {
+            const retractNames = memoryGroupRetractionSet(builtinDeferPairNames, memoryEnginePair.length > 0);
+            for (let i = tools.length - 1; i >= 0; i--) {
+                if (retractNames.has(tools[i].name))
+                    tools.splice(i, 1);
+            }
+            if (sharedMemoryPair.length > 0) {
+                onceLedger.onError(new Error(`Shared memory tools ${SHARED_MEMORY_TOOL_NAMES.join("/")} were NOT mounted: mounting them would inject ` +
+                    `the "${TOOL_SEARCH_NAME}" tool, whose name this task already declares — the pair mounts together or not at all.`), { phase: "config", sessionId, classification: "shared-memory-not-mounted" });
+            }
+            if (memoryEnginePair.length > 0) {
+                if (memoryBlock !== undefined && memoryRecallSegment !== undefined) {
+                    const segment = memoryRecallSegment;
+                    if (memoryBlock === segment)
+                        memoryBlock = undefined;
+                    else if (memoryBlock.includes(`\n\n${segment}`))
+                        memoryBlock = memoryBlock.replace(`\n\n${segment}`, "");
+                    else if (memoryBlock.startsWith(`${segment}\n\n`))
+                        memoryBlock = memoryBlock.slice(segment.length + 2);
+                }
+                onceLedger.onError(new Error(`Memory tools ${MEMORY_ENGINE_TOOL_NAMES.join("/")} were NOT mounted: mounting them would inject ` +
+                    `the "${TOOL_SEARCH_NAME}" tool, whose name this task already declares — these tools mount together or not at all.`), { phase: "config", sessionId, classification: "memory-tools-not-mounted" });
+            }
+            deferred = d0;
+        }
+        else {
+            deferred = d1;
+        }
+    }
+    else {
+        deferred = classifyDeferredOverFace(tools, []);
+    }
+    return { deferred, memoryBlock };
+}

package/dist/core/runner/prepare-delegation-surface.d.ts

@@ -0,0 +1,104 @@
+import type { AgentTool, ExecutionEnv, WorkspaceState } from "../../internal/harness.js";
+import { createSendMessageTool } from "../../agents/send-message-tool.js";
+import { type PeerLaneRefs } from "../../agents/peer-session-drain.js";
+import type { SubagentRetainLedger } from "../../agents/retain-ledger.js";
+import { type WorktreeSessionRef } from "../../tools/worktree.js";
+import type { CwdRef } from "../../tools/fs/index.js";
+import { type ToolResultStore } from "../tool-result-store.js";
+import type { RunnerDeps, TaskSpec, ToolEffect, ToolExecuteContext } from "../types.js";
+import type { PrepareResume, RunInternals, ToolFaceSnapshot } from "./contracts.js";
+/** The runner the SendMessage / AgentTranscript mounts accept — spelled as the factory's own option type so this phase
+ *  names no runner module of its own (the narrow `RunnerSelfSeat` contract is a design decision still open). */
+type DelegationMountRunner = Parameters<typeof createSendMessageTool>[0]["runner"];
+export interface PrepareDelegationSurfaceInput {
+    /** borrowed-readonly — the REBOUND spec. Read: `tools` (the shadow checks and the revival spawner's delegation-tool
+     *  lookup), `oneShot` (the read/kill faces' completion promises), `retainBackgroundProcesses` (the Monitor receipt),
+     *  `handsReadOnly` is NOT read here (the hands mount decided the surface). Never mutated. */
+    spec: Pick<TaskSpec, "tools" | "oneShot" | "retainBackgroundProcesses">;
+    /** borrowed-readonly — the deployment seats the mounts read: `workflowRunStore` / `backgroundAgentStore` / `mailboxStore` (the
+     *  read/kill faces and the tier-3 revival seams), `rosterStore`, `peerAdmission`, `peerDirectory`, `onNotice`,
+     *  `onBackgroundChildEvent`, `tracer`. */
+    deps: Pick<RunnerDeps, "workflowRunStore" | "backgroundAgentStore" | "mailboxStore" | "rosterStore" | "peerAdmission" | "peerDirectory" | "onNotice" | "onBackgroundChildEvent" | "tracer">;
+    /** borrowed-readonly — the trusted spawn-side channel: `parentNotify` (the delegated-child door), the uplink / sibling /
+     *  identity seats the SendMessage mount forwards, `onTaskNotification`, `onSubagentSpawn`. Never mutated. */
+    internals: Pick<RunInternals, "parentNotify" | "parentPeerRef" | "parentRetainLedger" | "explicitAgentName" | "parentTaskId" | "parentSessionId" | "peerSelfRef" | "peerInboundChainRef" | "onTaskNotification" | "onSubagentSpawn"> | undefined;
+    /** borrowed-readonly — the resume leg, or undefined: `seed.activeWorktree` seeds the worktree session (checkpoint first). */
+    resume: Pick<PrepareResume, "seed"> | undefined;
+    /** borrowed-readonly — the acquired session id (the mounts' session axis). */
+    sessionId: string;
+    /** borrowed-readonly — the per-task identity (the mounts' owner axis). */
+    hostTaskId: string;
+    /** borrowed-readonly — the registry scope the mounts register in. */
+    taskScope: string;
+    /** borrowed-readonly — the SETTLED task root (the worktree tools' repoRoot). */
+    taskRootFinal: string;
+    /** borrowed-readonly — the run's resolved env the Monitor and worktree tools operate. */
+    executionEnv: ExecutionEnv;
+    /** borrowed-readonly — the trusted Runner self-reference the SendMessage / AgentTranscript mounts execute through; undefined
+     *  when prepareTask runs standalone (then neither mounts). */
+    runnerSelf: DelegationMountRunner | undefined;
+    /** borrowed-readonly — the background/workflow door's first half: the hands mount decided a real shell with write hands. */
+    backgroundTaskToolsActive: boolean;
+    /** borrowed-readonly — the door's second half: the Workflow tool is on the roster. */
+    workflowToolsActive: boolean;
+    /** borrowed-readonly — the peer lane's mount verdict for this leg. */
+    peerLaneActive: boolean;
+    /** borrowed-readonly — whether the BUILT-IN SendMessage is on this face (the ListAgents mount's second term). */
+    peerSendMessageBuiltIn: boolean;
+    /** borrowed-mutable — the lane's late-bound facts; the SendMessage mount hands the SAME object to its peer seats (identity is
+     *  the contract: the wiring station fills `askEffective` later). Not written here. */
+    peerLaneRefs: PeerLaneRefs;
+    /** borrowed-mutable — the run's shared roster (`Prepared.tools`, whose JSDoc carries the writer table). Writers here: the
+     *  eight mounts (TaskOutput, TaskStop, SendMessage, AgentTranscript, ListAgents, Monitor, the worktree pair, the offload
+     *  reader), every one a push. */
+    tools: AgentTool[];
+    /** borrowed-mutable — the effect collection (`Prepared.toolEffects`). Writers here: TaskOutput → read, TaskStop / SendMessage
+     *  (built-in mount only) / Monitor / EnterWorktree / ExitWorktree → write. */
+    toolEffects: Map<string, ToolEffect>;
+    /** borrowed-mutable — the explicit-negative axis declarations. Writer here: the built-in SendMessage mount's `egress: false`
+     *  (report-face only). */
+    axisExplicitNegatives: Map<string, {
+        irreversible?: false;
+        egress?: false;
+    }>;
+    /** borrowed-mutable — the env-hand tool-name set the read posture reads. Writers here: Monitor and the two worktree tools
+     *  (membership minted at the mount). */
+    envHandToolNames: Set<string>;
+    /** borrowed-readonly — the frozen tool-face snapshot (`exclude` feeds the ListAgents mount predicate). */
+    toolFaceSnapshot: Pick<ToolFaceSnapshot, "exclude">;
+    /** borrowed-readonly — the large-result wrapper for first-party mounts. */
+    firstPartyOffload: (tool: AgentTool) => AgentTool;
+    /** borrowed-readonly — the run's offload store, or undefined when offload is disabled (then no reader mounts and the
+     *  read/kill faces spill nowhere). */
+    offloadStore: ToolResultStore | undefined;
+    /** borrowed-readonly — the retain ledger the SendMessage mount continues children through (absent ⇒ honest not-retained). */
+    subagentRetain: SubagentRetainLedger | undefined;
+    /** borrowed-readonly — the caller-tool ctx enrichment: the revival spawner re-enters the delegation tool through it, and
+     *  the SendMessage / AgentTranscript mounts activate their ctx-first arms with it. */
+    enrichSpecToolCtx: (ctx: ToolExecuteContext) => ToolExecuteContext;
+    /** borrowed-mutable — the hands mount's tracked-cwd seat: present ⇔ real shell + write hands; the worktree pair's mount
+     *  predicate. Not written by this phase, but the tools it mounts over it ARE its writers (design/238 R-3): EnterWorktree and
+     *  ExitWorktree assign `current` at run time (the hands band's shared cwd then points at the worktree, and back); the
+     *  Monitor only reads it. The cell must stay the hands mount's own object — a copy would strand those writes. */
+    handsCwdRef: CwdRef | undefined;
+    /** borrowed-readonly — the workspace-state snapshot (the worktree seed's continuation rung), or undefined. */
+    wsSnapshot: Pick<WorkspaceState, "activeWorktree"> | undefined;
+    /** borrowed-readonly — the rebase of a snapshot path onto this leg's root. */
+    rebaseWsPath: (p: string) => string;
+    /** borrowed-readonly — the rebase of a checkpoint path onto this leg's root. */
+    rebaseRestoredPath: (p: string) => string;
+    /** borrowed-mutable — the workspace-state settle seat; the worktree mount stamps `restoredWorktreeDir` on it once. */
+    workspaceStateSettle: {
+        restoredWorktreeDir?: string;
+    } | undefined;
+}
+export interface PrepareDelegationSurfaceResult {
+    /** owned — whether the background/workflow door is open (TaskOutput / TaskStop / AgentTranscript ride it). */
+    delegationSurfaceActive: boolean;
+    /** borrowed-mutable — the EnterWorktree session's shared serializable state (`Prepared.worktreeSessionRef`), minted iff the
+     *  worktree pair mounted. Writers: the worktree tools at run time (Enter/Exit); the suspend serializer reads it. */
+    worktreeSessionRef: WorktreeSessionRef | undefined;
+}
+/** The M6 phase body — prepareTask's delegation-surface stretch, verbatim (see the module header). */
+export declare function prepareDelegationSurface(input: PrepareDelegationSurfaceInput): PrepareDelegationSurfaceResult;
+export {};

package/dist/core/runner/prepare-delegation-surface.js

@@ -0,0 +1,144 @@
+import { randomBytes } from "node:crypto";
+import { createAgentTranscriptTool, AGENT_TRANSCRIPT_TOOL_NAME } from "../../agents/agent-transcript-tool.js";
+import { createSendMessageTool, SEND_MESSAGE_TOOL_NAME } from "../../agents/send-message-tool.js";
+import { listAgentsMountable, mountListAgents, peerLaneSendMessageSeats } from "../../agents/peer-session-drain.js";
+import { createMonitorTool } from "../../tools/monitor.js";
+import { createWorktreeTools } from "../../tools/worktree.js";
+import { createTaskOutputTool, createTaskStopTool, defaultTaskRegistry } from "../task-registry.js";
+import { createReadToolResultTool } from "../tool-result-store.js";
+import { emitTrace } from "../trace.js";
+import { deliverEngineNotice } from "../types.js";
+function buildTier3ReviveSpawn(delegationForRevive, enrichSpecToolCtx) {
+    if (delegationForRevive === undefined)
+        return undefined;
+    return async (req) => {
+        const out = await delegationForRevive.execute({
+            description: req.row.description ?? "revived teammate",
+            prompt: req.prompt,
+            run_in_background: true,
+            ...(req.row.agentType !== undefined ? { subagent_type: req.row.agentType } : {}),
+            ...(req.row.name !== undefined ? { name: req.row.name } : {}),
+            ...(req.row.model !== undefined ? { model: req.row.model } : {}),
+        }, enrichSpecToolCtx({ toolCallId: `rv-${randomBytes(8).toString("hex")}`, reviveClaim: { row: req.row, rev: req.rev, ...(req.peerSeed !== undefined ? { peerSeed: req.peerSeed } : {}) } }));
+        const o = (typeof out === "string" ? { content: out } : out);
+        return {
+            content: typeof o.content === "string" ? o.content : JSON.stringify(o.content),
+            ...(o.isError === true ? { isError: true } : {}),
+            ...(o.details !== undefined ? { details: o.details } : {}),
+        };
+    };
+}
+export function prepareDelegationSurface(input) {
+    const { spec, deps, internals, resume, sessionId, hostTaskId, taskScope, taskRootFinal, executionEnv, runnerSelf, backgroundTaskToolsActive, workflowToolsActive, peerLaneActive, peerSendMessageBuiltIn, peerLaneRefs, tools, toolEffects, axisExplicitNegatives, envHandToolNames, toolFaceSnapshot, firstPartyOffload, offloadStore, subagentRetain, enrichSpecToolCtx, handsCwdRef, wsSnapshot, rebaseWsPath, rebaseRestoredPath, workspaceStateSettle } = input;
+    let worktreeSessionRef;
+    const delegationSurfaceActive = backgroundTaskToolsActive || workflowToolsActive;
+    if (delegationSurfaceActive || internals?.parentNotify !== undefined || peerLaneActive) {
+        if (delegationSurfaceActive) {
+            toolEffects.set("TaskOutput", "read");
+            toolEffects.set("TaskStop", "write");
+            tools.push(firstPartyOffload(createTaskOutputTool({ registry: defaultTaskRegistry, owner: hostTaskId, scope: taskScope, sessionId, workflowStore: deps.workflowRunStore, agentStore: deps.backgroundAgentStore, notificationWired: internals?.onTaskNotification !== undefined, oneShot: spec.oneShot, toolResultStore: offloadStore })), firstPartyOffload(createTaskStopTool({ registry: defaultTaskRegistry, owner: hostTaskId, scope: taskScope, sessionId, workflowStore: deps.workflowRunStore, agentStore: deps.backgroundAgentStore })));
+        }
+        if (runnerSelf && !(spec.tools ?? []).some((t) => t.name === SEND_MESSAGE_TOOL_NAME)) {
+            toolEffects.set(SEND_MESSAGE_TOOL_NAME, "write");
+            axisExplicitNegatives.set(SEND_MESSAGE_TOOL_NAME, { ...axisExplicitNegatives.get(SEND_MESSAGE_TOOL_NAME), egress: false });
+            const delegationForRevive = (spec.tools ?? []).find((t) => t.agentListing !== undefined);
+            const reviveSpawn = deps.backgroundAgentStore !== undefined && deps.mailboxStore !== undefined ? buildTier3ReviveSpawn(delegationForRevive, enrichSpecToolCtx) : undefined;
+            tools.push(firstPartyOffload(createSendMessageTool({
+                runner: runnerSelf,
+                registry: defaultTaskRegistry,
+                ...(subagentRetain ? { retain: subagentRetain } : {}),
+                owner: hostTaskId,
+                scope: taskScope,
+                ...(sessionId !== undefined ? { sessionId } : {}),
+                ...(internals?.onTaskNotification !== undefined ? { notify: internals.onTaskNotification } : {}), ...(spec.oneShot !== undefined ? { oneShot: spec.oneShot } : {}), retrievalToolMounted: delegationSurfaceActive,
+                ...(internals?.onSubagentSpawn !== undefined ? { sink: internals.onSubagentSpawn } : {}),
+                ...(internals?.parentNotify !== undefined
+                    ? { uplink: internals.parentNotify, ...(internals.parentPeerRef !== undefined ? { uplinkRecipient: internals.parentPeerRef } : {}) }
+                    : {}),
+                ...(internals?.explicitAgentName !== undefined ? { senderName: internals.explicitAgentName } : {}),
+                ...(internals?.parentRetainLedger !== undefined ? { siblingRetain: internals.parentRetainLedger } : {}),
+                ...(internals?.parentTaskId !== undefined ? { parentTaskId: internals.parentTaskId } : {}),
+                ...(internals?.parentSessionId !== undefined ? { parentSessionId: internals.parentSessionId } : {}),
+                enrichCtx: enrichSpecToolCtx,
+                ...(deps.rosterStore !== undefined ? { roster: deps.rosterStore } : {}),
+                ...(deps.peerAdmission !== undefined ? { admission: deps.peerAdmission } : {}),
+                ...(deps.onNotice !== undefined ? { onNotice: deps.onNotice } : {}),
+                ...(internals?.peerSelfRef !== undefined ? { peerSelf: internals.peerSelfRef } : {}),
+                ...(internals?.peerInboundChainRef !== undefined ? { peerInbound: internals.peerInboundChainRef } : {}),
+                ...(deps.onBackgroundChildEvent ? { onBackgroundChildEvent: deps.onBackgroundChildEvent } : {}),
+                ...(deps.backgroundAgentStore !== undefined ? { agentStore: deps.backgroundAgentStore } : {}),
+                ...(deps.mailboxStore !== undefined ? { mailbox: deps.mailboxStore } : {}),
+                ...(reviveSpawn !== undefined ? { reviveSpawn } : {}),
+                ...(peerLaneActive ? peerLaneSendMessageSeats({ peerDirectory: deps.peerDirectory, sessionId, scope: taskScope, ...(internals?.explicitAgentName !== undefined ? { name: internals.explicitAgentName } : {}), refs: peerLaneRefs, listingMounted: listAgentsMountable({ exclude: toolFaceSnapshot.exclude, specTools: spec.tools ?? [] }) }) : {}),
+                onNotifyError: (f) => emitTrace(deps.tracer, () => ({ kind: "observer.notify_failed", version: 1, taskId: hostTaskId, site: f.site, message: f.error.message, ts: Date.now() })),
+                onTranscriptIntegrityGap: (handle, scope) => deliverEngineNotice(deps.onNotice, {
+                    code: "delegation.transcript_integrity",
+                    message: `delegation transcript integrity: agent ${handle}'s durable row binds a transcript session the session store attests is gone — the declared transcript durability is being contradicted (check the session store wiring/retention)`,
+                    detail: { handle, ...(scope !== undefined ? { scope } : {}) },
+                }),
+            })));
+            if (delegationSurfaceActive && !(spec.tools ?? []).some((t) => t.name === AGENT_TRANSCRIPT_TOOL_NAME)) {
+                tools.push(firstPartyOffload(createAgentTranscriptTool({
+                    runner: runnerSelf,
+                    registry: defaultTaskRegistry,
+                    agentStore: deps.backgroundAgentStore,
+                    owner: hostTaskId,
+                    scope: taskScope,
+                    ...(sessionId !== undefined ? { sessionId } : {}),
+                    enrichCtx: enrichSpecToolCtx,
+                    onTranscriptIntegrityGap: (handle, scope) => deliverEngineNotice(deps.onNotice, {
+                        code: "delegation.transcript_integrity",
+                        message: `delegation transcript integrity: agent ${handle}'s durable row binds a transcript session the session store attests is gone — the declared transcript durability is being contradicted (check the session store wiring/retention)`,
+                        detail: { handle, ...(scope !== undefined ? { scope } : {}) },
+                    }),
+                })));
+            }
+        }
+    }
+    const listAgents = peerLaneActive && peerSendMessageBuiltIn && listAgentsMountable({ exclude: toolFaceSnapshot.exclude, specTools: spec.tools ?? [] }) ? mountListAgents({ peerDirectory: deps.peerDirectory, sessionId, scope: taskScope, hostTaskId, ...(internals?.parentTaskId !== undefined ? { parentTaskId: internals.parentTaskId } : {}), ...(internals?.parentSessionId !== undefined ? { parentSessionId: internals.parentSessionId } : {}), registry: defaultTaskRegistry, ...(deps.rosterStore !== undefined ? { roster: deps.rosterStore } : {}), specTools: spec.tools ?? [], toolEffects }) : undefined;
+    if (listAgents !== undefined)
+        tools.push(firstPartyOffload(listAgents));
+    if (backgroundTaskToolsActive) {
+        toolEffects.set("Monitor", "write");
+        envHandToolNames.add("Monitor");
+        tools.push(firstPartyOffload(createMonitorTool(executionEnv, {
+            registry: defaultTaskRegistry,
+            owner: hostTaskId,
+            scope: taskScope,
+            ...(sessionId !== undefined ? { sessionId } : {}),
+            ...(internals?.onTaskNotification !== undefined ? { onTaskNotification: internals.onTaskNotification } : {}),
+            ...(handsCwdRef !== undefined ? { cwdRef: handsCwdRef } : {}),
+            ...(offloadStore !== undefined ? { toolResultStore: offloadStore } : {}),
+            ...(spec.retainBackgroundProcesses === true ? { retainBackgroundProcesses: true } : {}),
+        })));
+    }
+    if (handsCwdRef !== undefined) {
+        toolEffects.set("EnterWorktree", "write");
+        toolEffects.set("ExitWorktree", "write");
+        worktreeSessionRef = {
+            ...(resume?.seed.activeWorktree
+                ? {
+                    current: {
+                        ...resume.seed.activeWorktree,
+                        worktreeDir: rebaseRestoredPath(resume.seed.activeWorktree.worktreeDir),
+                        originalCwd: rebaseRestoredPath(resume.seed.activeWorktree.originalCwd),
+                    },
+                }
+                : wsSnapshot?.activeWorktree !== undefined
+                    ? {
+                        current: {
+                            ...wsSnapshot.activeWorktree,
+                            worktreeDir: rebaseWsPath(wsSnapshot.activeWorktree.worktreeDir),
+                            originalCwd: rebaseWsPath(wsSnapshot.activeWorktree.originalCwd),
+                        },
+                    }
+                    : {}),
+        };
+        if (workspaceStateSettle !== undefined)
+            workspaceStateSettle.restoredWorktreeDir = worktreeSessionRef.current?.worktreeDir;
+        tools.push(...createWorktreeTools(executionEnv, { repoRoot: taskRootFinal, cwdRef: handsCwdRef, session: worktreeSessionRef }).map((t) => (envHandToolNames.add(t.name), firstPartyOffload(t))));
+    }
+    if (offloadStore)
+        tools.push(createReadToolResultTool(offloadStore));
+    return { delegationSurfaceActive, worktreeSessionRef };
+}

package/dist/core/runner/prepare-execution-env.d.ts

@@ -0,0 +1,54 @@
+import type { ExecutionEnv } from "../../internal/harness.js";
+import type { RunnerDeps, TaskSpec } from "../types.js";
+import type { PrepareResume, RollbackStack, RunInternals } from "./contracts.js";
+/**
+ * The ONE reference to a factory-minted env, shared by the driver's detach guard and the rollback entry
+ * this phase registers. `current` is the minted env, or `undefined` when the run has none / after the
+ * driver detached an aliasing one. Written by: this phase (once, at the mint) and the driver's worktree
+ * guard (the detach). Read by: the rollback entry (at unwind), and the driver, which settles it into a
+ * plain `ownedEnv` binding once the guard has passed.
+ */
+export interface OwnedEnvSeat {
+    current: ExecutionEnv | undefined;
+}
+export interface PrepareExecutionEnvInput {
+    /** borrowed-readonly — the deployment's env seats: the per-task factory (wins), the static env, the
+     *  declared root fence, and the incident sink for the bounded teardown legs. */
+    deps: Pick<RunnerDeps, "executionEnvFactory" | "executionEnv" | "rootPath" | "onError">;
+    /** borrowed-readonly — the REBOUND spec; only the caller's task id rides into the factory ctx. */
+    spec: Pick<TaskSpec, "taskId">;
+    /** borrowed-readonly — the trusted spawn-side requests: the explicit cwd (a contract), the isolation
+     *  request and the parent's cwd (both threaded to the factory ctx). */
+    internals: Pick<RunInternals, "requestedCwd" | "isolation" | "parentCwd"> | undefined;
+    /** borrowed-readonly — the resume leg, read only to refuse an explicit cwd that a checkpoint workspace
+     *  restore would overrule. */
+    resume: Pick<PrepareResume, "workspaceHandle"> | undefined;
+    /** borrowed-readonly — the run tree's placement fixed point, resolved ONCE by the driver; the factory
+     *  door refuses an empty value loudly before the factory is asked. */
+    placementRootResolved: string;
+    /** borrowed-readonly — the acquired session id (the factory ctx's identity, and the incident phase tag). */
+    sessionId: string;
+    /** borrowed-readonly — the driver's session-view forget leg; every refusal here runs it, bounded, before
+     *  throwing (the acquired view must not outlive a prepare the caller never gets a handle to). */
+    forgetOnThrow: () => Promise<void>;
+    /** borrowed-mutable — the driver-owned prepare-failure stack; this phase pushes ONE entry (the minted
+     *  env's destroy, read through the seat) and nothing else touches it here. */
+    rollback: RollbackStack;
+}
+export interface PrepareExecutionEnvResult {
+    /** borrowed-readonly — the run's resolved env: the minted one, else the static one, else the no-I/O stub. */
+    executionEnv: ExecutionEnv;
+    /** ownership-ref — the seat holding the factory-minted env (`current` undefined when none was minted).
+     *  The exception-path protocol stays with the driver (D-8 案①): its worktree guard may detach through
+     *  this seat before throwing; the rollback entry registered here reads it at unwind. */
+    ownedEnvSeat: OwnedEnvSeat;
+    /** borrowed-readonly — epoch ms at which the factory-minted env was obtained (the lifetime anchor of
+     *  last resort); `undefined` for a static env or no env. */
+    ownedEnvObservedAt: number | undefined;
+    /** borrowed-readonly — whether a real fs env is present (a minted env, or a static one). */
+    handsEnabled: boolean;
+    /** borrowed-readonly — the INITIAL task root (the workspace-restore phase may re-root it and returns the
+     *  settled root under the NEW name `taskRootFinal`). */
+    taskRootInitial: string;
+}
+export declare function prepareExecutionEnv(input: PrepareExecutionEnvInput): Promise<PrepareExecutionEnvResult>;

package/dist/core/runner/prepare-execution-env.js

@@ -0,0 +1,86 @@
+import { StubExecutionEnv } from "../stub-env.js";
+import { hasDestroy } from "../remote-env.js";
+import { settleTeardownLeg } from "./teardown-bounded.js";
+export async function prepareExecutionEnv(input) {
+    const { deps, spec, internals, resume, placementRootResolved, sessionId, forgetOnThrow, rollback } = input;
+    let ownedEnv;
+    let ownedEnvObservedAt;
+    if (internals?.requestedCwd !== undefined && deps.executionEnvFactory === undefined) {
+        await settleTeardownLeg(() => forgetOnThrow(), "forgetOnThrow (cwd-unsupported leg)", (err) => deps.onError?.(err, { phase: "config", sessionId }));
+        const e = new Error(`Agent cwd "${internals.requestedCwd}" cannot take effect: this deployment has no executionEnvFactory (a static execution environment cannot be re-rooted per agent). Drop the cwd parameter or deploy a factory.`);
+        e.code = "config.cwd_unsupported";
+        throw e;
+    }
+    if (internals?.requestedCwd !== undefined && resume?.workspaceHandle !== undefined) {
+        await settleTeardownLeg(() => forgetOnThrow(), "forgetOnThrow (cwd-conflicts-restore leg)", (err) => deps.onError?.(err, { phase: "config", sessionId }));
+        throw cwdConflictsRestoreError(internals.requestedCwd);
+    }
+    try {
+        ownedEnv = deps.executionEnvFactory
+            ? await deps.executionEnvFactory({
+                sessionId, placementRootSessionId: mintPlacementRootSessionId(placementRootResolved),
+                taskId: spec.taskId,
+                ...(internals?.isolation ? { isolation: internals.isolation } : {}),
+                ...(internals?.parentCwd ? { parentCwd: internals.parentCwd } : {}),
+            })
+            : undefined;
+        if (ownedEnv !== undefined)
+            ownedEnvObservedAt = Date.now();
+    }
+    catch (factoryErr) {
+        await settleTeardownLeg(() => forgetOnThrow(), "forgetOnThrow (env-factory-throw leg)", (err) => deps.onError?.(err, { phase: "config", sessionId }));
+        throw factoryErr;
+    }
+    const ownedEnvSeat = { current: ownedEnv };
+    if (ownedEnv !== undefined) {
+        rollback.push(function ownedEnvDestroy() {
+            const env = ownedEnvSeat.current;
+            return env !== undefined && hasDestroy(env) ? env.destroy() : undefined;
+        });
+    }
+    const executionEnv = ownedEnv ?? deps.executionEnv ?? new StubExecutionEnv();
+    if (internals?.requestedCwd !== undefined) {
+        const canon = async (p) => {
+            const r = await executionEnv.canonicalPath(p);
+            return r.ok ? r.value : p;
+        };
+        const want = await canon(internals.requestedCwd);
+        const rejectCwd = async (message, code) => {
+            await settleTeardownLeg(() => forgetOnThrow(), "forgetOnThrow (cwd-reject leg)", (err) => deps.onError?.(err, { phase: "config", sessionId }));
+            await settleTeardownLeg(() => (ownedEnv && hasDestroy(ownedEnv) ? ownedEnv.destroy() : undefined), "ownedEnv.destroy (cwd-reject leg)", (err) => deps.onError?.(err, { phase: "config", sessionId }));
+            const e = new Error(message);
+            e.code = code;
+            throw e;
+        };
+        if (deps.rootPath !== undefined) {
+            const root = await canon(deps.rootPath);
+            const sep = root.includes("\\") && !root.includes("/") ? "\\" : "/";
+            const rootPrefix = root.endsWith(sep) ? root : root + sep;
+            if (want !== root && !want.startsWith(rootPrefix)) {
+                await rejectCwd(`Agent cwd "${internals.requestedCwd}" is outside this deployment's declared root "${deps.rootPath}" — the cwd must be located within the deployment root.`, "config.cwd_outside_root");
+            }
+        }
+        const got = await canon(executionEnv.cwd);
+        if (want !== got) {
+            await rejectCwd(`Agent cwd "${internals.requestedCwd}" was not honored by the execution environment (it rooted at "${executionEnv.cwd}") — failing loud instead of running the agent in the wrong tree.`, "config.cwd_not_honored");
+        }
+    }
+    const handsEnabled = ownedEnv !== undefined || deps.executionEnv !== undefined;
+    const taskRootInitial = internals?.isolation === "worktree" || internals?.requestedCwd !== undefined || !deps.rootPath ? executionEnv.cwd : deps.rootPath;
+    return { executionEnv, ownedEnvSeat, ownedEnvObservedAt, handsEnabled, taskRootInitial };
+}
+function cwdConflictsRestoreError(requestedCwd) {
+    const e = new Error(`RunInternals.requestedCwd ("${requestedCwd}") cannot be combined with a checkpoint workspace restore — ` +
+        `the restored workspace's own mount path is authoritative for the task root, so a requested cwd on this leg ` +
+        `would be ignored (or worse, probed against an unrestored environment). Drop requestedCwd on resume legs.`);
+    e.code = "config.cwd_conflicts_restore";
+    return e;
+}
+function mintPlacementRootSessionId(placementRootResolved) {
+    if (placementRootResolved === "") {
+        const e = new Error("placement root resolved EMPTY (internals.placementRoot / internals.rootSessionId carries an empty string) — an empty fixed point cannot key a placement lookup; fix the spawning lane instead of defaulting around it.");
+        e.code = "config.placement_root_invalid";
+        throw e;
+    }
+    return placementRootResolved;
+}

package/dist/core/runner/prepare-file-history.d.ts

@@ -0,0 +1,95 @@
+/**
+ * design/390 §1.2 M2 — prepareTask's file-history phase, verbatim from the driver: the DV-14 first-touch
+ * policy door, the `RunnerDeps.fileHistoryStore` bad-value door, the retired `rewindFiles` two-sense
+ * split, the restoreFiles / resumeAt / rewindFilesTo combination gates, the run's history coordinates
+ * (canonical root, recording scope, filesystem identity), the fork carry, the child-scope refusal, the
+ * rewind RESTORE itself (anchor translation in "before" mode, the per-file ledger, partial-restore
+ * policy), the `trackFileEdit` hook the hands band calls before every mutation lane, and the turn-start
+ * boundary seat runtask drives.
+ *
+ * Runs INSIDE the driver's prepare try-block, after the workspace root is FINAL (`taskRootFinal`) and the
+ * env is resolved: every refusal here throws through to the driver's prepare-throw catch exactly as
+ * before the move (a minted ownedEnv is destroyed there, the session view forgotten). The phase acquires
+ * no resource of its own — the two seats it returns are closures over the store the deployment owns.
+ *
+ * The module-level helpers below the phase (`restoredAbsPathsOf`, `resolveWiredFileHistoryStore`,
+ * the refusal's epoch-tail wording helper, `adoptForkedFileHistory` with its per-store carry memo,
+ * `createFileHistoryBoundarySeat`, `resolveFileHistoryCoordinates` / `resolveFileHistoryScope` /
+ * `fileHistoryFilesystemIdentity`, `childScopeRewindRefusal`) moved with it unchanged; the two the test
+ * suite reaches through the driver are re-exported from there.
+ */
+import type { ExecutionEnv } from "../../internal/harness.js";
+import type { StoredSession } from "../../engine/session/session.js";
+import type { RunnerDeps, TaskResult, TaskSpec, TrackFileEditHook } from "../types.js";
+import type { FileHistoryBoundarySeat, RunInternals } from "./contracts.js";
+export interface PrepareFileHistoryInput {
+    /** borrowed-readonly — the deployment seats this phase reads: the first-touch failure policy and the
+     *  history store (both validated HERE, once), the incident sink, and the retired-epoch diagnostic probe. */
+    deps: Pick<RunnerDeps, "onTrackFailure" | "fileHistoryStore" | "onError" | "legacyRewindBoundaryProbe">;
+    /** borrowed-readonly — the REBOUND spec's rewind request fields (the retired `rewindFiles` spelling is
+     *  read off the same object as an unknown key) and the caller's cancel signal for the restore. */
+    spec: Pick<TaskSpec, "resumeAt" | "resumeAtMode" | "restoreFiles" | "rewindFilesTo" | "acceptPartialRestore" | "signal">;
+    /** borrowed-readonly — the trusted lineage a delegating parent handed this run (absent for a root run
+     *  and for a host's own fork), read for the recording-scope decision only. */
+    internals: Pick<RunInternals, "fileHistoryLineage"> | undefined;
+    /** borrowed-readonly — the run's resolved env (owned or static or the stub); every history verb runs
+     *  against ITS filesystem ops. Never rebound or destroyed here. */
+    executionEnv: ExecutionEnv;
+    /** borrowed-readonly — the FINAL task root (the workspace-restore phase's output binding). */
+    taskRootFinal: string;
+    /** borrowed-readonly — the "real fs env" fact (`ownedEnv !== undefined || deps.executionEnv !== undefined`). */
+    handsEnabled: boolean;
+    /** borrowed-readonly — the acquired session id: the run's OWN history scope and the restore's session key. */
+    sessionId: string;
+    /** borrowed-readonly — the acquired session, read for the fork lineage (`getMetadata`) and the "before"
+     *  anchor walk (`getEntry`); never written here. */
+    session: Pick<StoredSession, "getEntry" | "getMetadata">;
+    /** borrowed-readonly — §E18 "before" mode: the validated target's parentId (the acquire phase's output);
+     *  `null` outside "before" mode. */
+    resumeAtBeforeParentId: string | null;
+    /** borrowed-readonly — the run's abort controller (driver-minted); only its `signal` is read, composed
+     *  with `spec.signal` for the restore. */
+    abortController: AbortController;
+}
+export interface PrepareFileHistoryResult {
+    /** borrowed-readonly — the hook the hands band calls before every mutation lane; `undefined` when the
+     *  machinery is not live (no store, or no real fs env). */
+    trackFileEdit: TrackFileEditHook | undefined;
+    /** borrowed-readonly — the turn-start boundary seat runtask drives; `undefined` when not live or when
+     *  this run records into its ROOT session's scope (a child mints no boundaries). */
+    fileHistoryBoundary: FileHistoryBoundarySeat | undefined;
+    /** borrowed-readonly — the absolute paths the restore MUTATED (empty when no restore ran), for the
+     *  read-face phase's read-state invalidation. */
+    restoredFilePaths: string[];
+    /** borrowed-mutable — the non-fatal rewind disclosures (`TaskResult.rewindNotes`). Mutation owners after
+     *  this call: none — every push happens inside this phase; the driver only reads it into `Prepared`. */
+    rewindNotes: NonNullable<TaskResult["rewindNotes"]>;
+    /** borrowed-readonly — whether the file-history machinery is LIVE for this run (store wired AND hands). */
+    fileHistoryEnabled: boolean;
+    /** borrowed-readonly — the scope this run's first-touch records land in (own session, or the root
+     *  session's for a same-tree delegated child). */
+    historyScope: string;
+    /** borrowed-readonly — the canonical history root every history verb keys against. */
+    historyRoot: string;
+    /** borrowed-readonly — the filesystem identity of the env (the lineage's second tree coordinate). */
+    historyFs: string;
+}
+export declare function prepareFileHistory(input: PrepareFileHistoryInput): Promise<PrepareFileHistoryResult>;
+/** The ONE reading of {@link RunInternals.fileHistoryLineage} (see {@link resolveFileHistoryCoordinates}):
+ *  the lineage's scope iff BOTH tree coordinates match; otherwise the run's own session. */
+export declare function resolveFileHistoryScope(lineage: RunInternals["fileHistoryLineage"], historyRoot: string, historyFs: string, sessionId: string): string;
+/**
+ * WHICH filesystem an env is a view of — the second coordinate of tree identity for the file-history
+ * lineage, read from what the env's MINTER states rather than inferred from a path:
+ *  · a remote workspace names itself through its {@link WorkspaceHandle} (provider + sandbox, and the
+ *    device lane's id when stamped) — two runs on one sandbox share a tree, two sandboxes never do;
+ *  · an env that DECLARES its paths host-local (`hostLocalPaths: true`), or is the host adapter itself
+ *    (a {@link NodeExecutionEnv}, which the #211 seam names as the host-local default), is the
+ *    control-plane host's filesystem — every such env is one tree;
+ *  · anything else — an env declaring `hostLocalPaths: false`, or an undeclared custom adapter — is
+ *    attested to nothing, so it is its OWN tree: a per-instance token, which still matches when the
+ *    child literally holds the parent's env object and never matches a fresh per-task mint.
+ * A remote handle that cannot be read (an env not yet connected) falls to the per-instance arm for
+ * the same reason: unattested is not shared.
+ */
+export declare function fileHistoryFilesystemIdentity(env: ExecutionEnv): string;