@sema-agent/core 7.5.0 → 7.5.2

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;