@sema-agent/core 7.4.0 → 7.5.1

package/dist/core/runner/prepare-project-context.d.ts

@@ -0,0 +1,131 @@
+/**
+ * design/390 M9 — prepareTask's PROJECT-CONTEXT phase: the deployment's project memory snapshot (the
+ * `loadProjectMemory` seam: phase derivation, instruction sources, the framed + fenced project layer
+ * appended to the memory block), the skills roster (declaration rank, normalization, the 1MB load gate,
+ * the manifest-scope door, the `skill` tool mount), the two built-in memory pairs' mount-or-yield
+ * (shared-memory pair, engine-memory pair), and the skills-listing projection the run loop announces.
+ * The body is the driver's stretch moved verbatim; the interface below is the dependency list it had
+ * implicitly (design/238 R-1: a new read is an Input field, i.e. a review event).
+ *
+ * ASYNC BY CONTENT: the stretch awaits the session branch read, the seam itself and the read-state
+ * seeding (all inside the `loadProjectMemory` arm). It already sits past prepareTask's first await, so
+ * the one extra microtask the driver's `await` adds on the seam-less path opens no window any caller
+ * could reach (design/390 §1.5 S1 synchronicity rule: only pre-first-await stretches must stay sync).
+ *
+ * Throws pass through unchanged: `config.reserved_tool_name` (a caller tool named like the skill tool
+ * while skills are present) is the only refusal here; the seam's own throw and the seeding's are
+ * caught and forwarded to `deps.onError` (best-effort, never block the task).
+ */
+import type { AgentTool } from "../../internal/harness.js";
+import type { StoredSession } from "../session.js";
+import type { RunnerDeps, TaskSpec, ToolSpec } from "../types.js";
+import type { ActiveSkillScope } from "./active-skill-scope.js";
+import type { AnnounceOnceSink, Prepared, PrepareResume, RunInternals, ToolFaceSnapshot } from "./contracts.js";
+import { normalizeSkills } from "./synthetic-tools.js";
+/**
+ * The ONE "has this session seen conversation?" predicate — the freshness question is asked three
+ * times in one prepare (project-memory phase, design/148 center adoption, the epoch-pin
+ * discriminator), and an entry-COUNT proxy at ANY of them re-creates the same lie: a host may write
+ * session_info / model_change / … rows before the first turn (naming a new chat, recording a model
+ * pick), and none of that is evidence of a prior session (5.29 merge-rescan: the count proxy
+ * survived at the adoption arm after the pin arm was fixed, silently costing a pre-named session
+ * its published center prompt for life). Conversation content — and only that — is the evidence.
+ */
+export declare function hasConversationContent(branch: ReadonlyArray<{
+    type: string;
+}>): boolean;
+export interface PrepareProjectContextInput {
+    /** borrowed-readonly — the deployment seams this phase reads: `loadProjectMemory` (the snapshot),
+     *  `onError` (the operator lane for a throwing seam / seeding / oversize skill), `sharedMemoryStores`
+     *  (the shared-memory pair's switch: wired ⇒ mount). Receiver preserved (`deps.onError?.(…)`). */
+    deps: Pick<RunnerDeps, "loadProjectMemory" | "onError" | "sharedMemoryStores">;
+    /** borrowed-readonly — the REBOUND spec (`spec′`). Read: `sessionId` (phase derivation + the
+     *  continuation projections), `skills` (the roster), `principal` (the shared-memory tools' trusted
+     *  identity). Never mutated. */
+    spec: Pick<TaskSpec, "sessionId" | "skills" | "principal">;
+    /** borrowed-readonly — trusted internals: `agentName` (seam ctx), `inheritedManifestScope` (the
+     *  parent's active skill frames, seeded as the base of the LIFO). `undefined` on a standalone prepare. */
+    internals: Pick<RunInternals, "agentName" | "inheritedManifestScope"> | undefined;
+    /** borrowed-readonly — the acquired session; only `getBranch()` is read (phase derivation walk).
+     *  The read is best-effort: a throw keeps the provisional phase. */
+    session: Pick<StoredSession, "getBranch">;
+    /** borrowed-readonly — the acquired session's id (seam ctx cache key; operator-line context). */
+    sessionId: string;
+    /** borrowed-readonly — `spec.taskId ?? sessionId`: the shared-memory tools' trusted task identity. */
+    hostTaskId: string;
+    /** borrowed-readonly — the FINAL task root (post-restore): the seam's `cwd`. */
+    taskRootFinal: string;
+    /** borrowed-readonly — whether a real execution env is mounted (seam ctx flag). */
+    handsEnabled: boolean;
+    /** borrowed-readonly — the leg's effective-delegation facts; only `isNonForkChild` is read (the
+     *  seam's `isSubagent` — one derivation shared with the prompt fact, never re-derived here). */
+    delegation: {
+        readonly isNonForkChild: boolean;
+    };
+    /** borrowed-readonly — the hands phase's read-state seeding closure (CREATED there, CALLED here for
+     *  the snapshot's declared `seededFiles`); `undefined` on a hands-less task = nothing to seed. */
+    seedContextFiles: ((files: ReadonlyArray<{
+        path: string;
+        content: string;
+    }>) => Promise<void>) | undefined;
+    /** borrowed-readonly — the memory phase's composed block, as returned (recall discipline + engine
+     *  files). This phase APPENDS the project layer and hands the result back as
+     *  {@link PrepareProjectContextResult.memoryBlock}; the input value itself is never mutated. */
+    memoryBlockFromEngine: string | undefined;
+    /** borrowed-mutable — the run's LIFO skill-scope stack (identity is the contract: the scope policy
+     *  and the `skill` tool alias this exact object). Mutated here: `push` of every inherited parent
+     *  frame; after this phase only the `skill` tool's execute pushes/pops. */
+    skillScope: ActiveSkillScope;
+    /** borrowed-mutable — the shared mount array (later refs alias it; in-place contract). Mutated
+     *  here: `push` of the `skill` tool, the shared-memory pair and the engine-memory pair. Occupancy
+     *  is judged on this ALREADY-MOUNTED roster (names + aliases). */
+    tools: AgentTool[];
+    /** borrowed-readonly — the frozen task-start tool face; only `exclude` is read (pair yield ①). */
+    toolFaceSnapshot: Pick<ToolFaceSnapshot, "exclude">;
+    /** borrowed-readonly — the once-per-session announcement ledger; only its deduplicated `onError`
+     *  sink is invoked (a pair's mount shape is a session-level fact, announced once). */
+    onceLedger: AnnounceOnceSink;
+    /** borrowed-readonly — the memory phase's engine-pair ToolSpecs (present iff the pair may mount). */
+    memoryTools: ToolSpec[] | undefined;
+    /** borrowed-readonly — the memory phase's session seat; only `!== undefined` is read (the
+     *  blocked-mount disclosure fires only when a session mounted). */
+    memoryEngineSession: Prepared["memoryEngineSession"];
+    /** borrowed-readonly — the engine pair's early conjuncts (computed before the memory phase). */
+    memorySearchToolsPlanned: boolean;
+    /** borrowed-readonly — the engine-pair name the exclusion valve removed, if any (disclosure text). */
+    memoryPairExcludedName: string | undefined;
+    /** borrowed-readonly — the engine-pair name a declared tool already occupies, if any (disclosure text). */
+    memoryPairOccupiedName: string | undefined;
+    /** borrowed-readonly — the durable-resume carrier; read for `!== undefined` (seedAnnounced) and
+     *  `seed.announcedListings.skills` (the removal-to-zero projection's gate). */
+    resume: Pick<PrepareResume, "seed"> | undefined;
+}
+export interface PrepareProjectContextResult {
+    /** owned — the memory block with the project layer appended at the tail (unchanged when the seam is
+     *  unwired or returns null/blank). The driver binds it under a NEW name; the defer-classification
+     *  stretch may still strip the recall-discipline segment from it. */
+    memoryBlock: string | undefined;
+    /** owned — the snapshot's declared instruction sources (non-empty only), for the run loop's
+     *  instructions_change lane (`Prepared.instructionSources`). */
+    instructionSources: ReadonlyArray<{
+        path: string;
+        contentHash: string | null;
+    }> | undefined;
+    /** owned — the RAW snapshot text (pre-compose) for the compaction lanes' instruction-file seat
+     *  (`Prepared.projectInstructionContent`). */
+    projectInstructionContent: string | undefined;
+    /** owned — the normalized, load-gated skills (first-wins dedupe, name-sorted). Consumed inside this
+     *  phase (tool + listing); exposed as the phase's own product. */
+    skillSpecs: ReturnType<typeof normalizeSkills>;
+    /** owned — whether THIS task carries a manifested skill or inherits a parent frame (the skill-scope
+     *  policy's activation predicate). */
+    hasSkillManifest: boolean;
+    /** owned — the skills-listing projection the run loop's announce lane consumes (`Prepared.skillsListing`). */
+    skillsListing: Prepared["skillsListing"];
+    /** owned — whether the shared-memory pair mounted here (the support-name pre-check reads it). */
+    sharedMemoryPairMounted: boolean;
+    /** owned — whether the engine-memory pair mounted here (the support-name pre-check reads it). */
+    memoryEnginePairMounted: boolean;
+}
+/** The M9 phase body — prepareTask's project-context stretch, verbatim (see the module header). */
+export declare function prepareProjectContext(input: PrepareProjectContextInput): Promise<PrepareProjectContextResult>;

package/dist/core/runner/prepare-project-context.js

@@ -0,0 +1,150 @@
+import { PROJECT_CONTEXT_FRAMING } from "../../prompts/default.js";
+import { MEMORY_ENGINE_TOOL_NAMES } from "../memory-engine/tools.js";
+import { composeMemoryBlock } from "../memory.js";
+import { createSharedMemoryTools } from "../shared-memory/tools.js";
+import { SHARED_MEMORY_TOOL_NAMES } from "../shared-memory/types.js";
+import { defineTool } from "../tools.js";
+import { SKILL_CONTENT_MAX_CHARS, SKILL_TOOL_NAME, createSkillTool, normalizeSkills } from "./synthetic-tools.js";
+export function hasConversationContent(branch) {
+    return branch.some((e) => e.type === "message" || e.type === "custom_message" || e.type === "compaction");
+}
+export async function prepareProjectContext(input) {
+    const { deps, spec, internals, session, sessionId, hostTaskId, taskRootFinal, handsEnabled, delegation, seedContextFiles, memoryBlockFromEngine, skillScope, tools, toolFaceSnapshot, onceLedger, memoryTools, memoryEngineSession, memorySearchToolsPlanned, memoryPairExcludedName, memoryPairOccupiedName, resume } = input;
+    let memoryBlock = memoryBlockFromEngine;
+    let instructionSources;
+    let projectInstructionContent;
+    if (deps.loadProjectMemory) {
+        let projectMemoryPhase = spec.sessionId ? "resume" : "fresh";
+        if (spec.sessionId) {
+            try {
+                const branch = await session.getBranch();
+                const hasConversation = hasConversationContent(branch);
+                if (!hasConversation)
+                    projectMemoryPhase = "fresh";
+                else {
+                    for (let i = branch.length - 1; i >= 0; i--) {
+                        const e = branch[i];
+                        if (e.type === "compaction") {
+                            projectMemoryPhase = "post-compact";
+                            break;
+                        }
+                        if (e.type === "message" && e.message.role === "user")
+                            break;
+                    }
+                }
+            }
+            catch {
+            }
+        }
+        let loaded = null;
+        try {
+            loaded = await Promise.resolve(deps.loadProjectMemory({
+                cwd: taskRootFinal,
+                handsEnabled,
+                isSubagent: delegation.isNonForkChild,
+                ...(internals?.agentName ? { agentName: internals.agentName } : {}),
+                sessionId,
+                phase: projectMemoryPhase,
+            }));
+        }
+        catch (err) {
+            deps.onError?.(err instanceof Error ? err : new Error(String(err)), { phase: "config", sessionId });
+        }
+        const projectMem = loaded !== null && typeof loaded === "object" ? loaded.content : loaded;
+        const seededFiles = loaded !== null && typeof loaded === "object" ? loaded.seededFiles : undefined;
+        const declaredSources = loaded !== null && typeof loaded === "object" ? loaded.instructionSources : undefined;
+        if (declaredSources !== undefined && declaredSources.length > 0)
+            instructionSources = declaredSources;
+        if (seededFiles?.length && seedContextFiles) {
+            try {
+                await seedContextFiles(seededFiles);
+            }
+            catch (err) {
+                deps.onError?.(err instanceof Error ? err : new Error(String(err)), { phase: "config", sessionId });
+            }
+        }
+        if (projectMem != null && projectMem.trim()) {
+            projectInstructionContent = projectMem;
+            const projectBlock = `${PROJECT_CONTEXT_FRAMING}\n\n${composeMemoryBlock(projectMem, "project")}`;
+            memoryBlock = memoryBlock ? `${memoryBlock}\n\n${projectBlock}` : projectBlock;
+        }
+    }
+    const declaredSkillRank = new Map();
+    for (const s of spec.skills ?? [])
+        if (!declaredSkillRank.has(s.name))
+            declaredSkillRank.set(s.name, declaredSkillRank.size);
+    const skillSpecs = normalizeSkills(spec.skills ?? []).filter((s) => {
+        if (s.content.length <= SKILL_CONTENT_MAX_CHARS)
+            return true;
+        deps.onError?.(new Error(`Skill "${s.name}" content is ${s.content.length} chars, over the ${SKILL_CONTENT_MAX_CHARS}-char load limit — skill not loaded (skills are never truncated; shrink the body or move material to attachments/files).`), { phase: "config", sessionId });
+        return false;
+    });
+    const inheritedFrames = internals?.inheritedManifestScope ?? [];
+    for (const frame of inheritedFrames) {
+        skillScope.push(frame);
+    }
+    const hasSkillManifest = skillSpecs.some((s) => s.manifest !== undefined) || inheritedFrames.length > 0;
+    if (skillSpecs.length > 0) {
+        if (tools.some((t) => t.name === SKILL_TOOL_NAME)) {
+            const e = new Error(`Tool name "${SKILL_TOOL_NAME}" is reserved when spec.skills is present.`);
+            e.code = "config.reserved_tool_name";
+            throw e;
+        }
+        tools.push(createSkillTool(skillSpecs, skillScope));
+    }
+    const sharedMemoryProvider = deps.sharedMemoryStores;
+    let sharedMemoryPairMounted = false;
+    if (sharedMemoryProvider !== undefined) {
+        const excluded = new Set(toolFaceSnapshot.exclude ?? []);
+        const mountedNameDomain = new Set();
+        for (const t of tools) {
+            mountedNameDomain.add(t.name);
+            for (const alias of t.aliases ?? [])
+                mountedNameDomain.add(alias);
+        }
+        const excludedName = SHARED_MEMORY_TOOL_NAMES.find((n) => excluded.has(n));
+        const occupiedName = SHARED_MEMORY_TOOL_NAMES.find((n) => mountedNameDomain.has(n));
+        if (excludedName !== undefined || occupiedName !== undefined) {
+            onceLedger.onError(new Error(`Shared memory tools ${SHARED_MEMORY_TOOL_NAMES.join("/")} were NOT mounted: ` +
+                (excludedName !== undefined
+                    ? `excludeTools removes "${excludedName}"`
+                    : `this task already declares a tool named "${occupiedName}" (the built-in yields to it)`) +
+                " — the pair mounts together or not at all."), { phase: "config", sessionId, classification: "shared-memory-not-mounted" });
+        }
+        else {
+            tools.push(...createSharedMemoryTools({
+                provider: sharedMemoryProvider,
+                context: { sessionId, taskId: hostTaskId, ...(spec.principal !== undefined ? { principal: spec.principal } : {}) },
+            }).map((s) => defineTool(s)));
+            sharedMemoryPairMounted = true;
+        }
+    }
+    let memoryEnginePairMounted = false;
+    if (memoryTools !== undefined && memoryTools.length > 0) {
+        tools.push(...memoryTools.map((s) => defineTool(s)));
+        memoryEnginePairMounted = true;
+    }
+    else if (memoryEngineSession !== undefined && !memorySearchToolsPlanned) {
+        onceLedger.onError(new Error(`Memory tools ${MEMORY_ENGINE_TOOL_NAMES.join("/")} were NOT mounted: ` +
+            (memoryPairExcludedName !== undefined
+                ? `excludeTools removes "${memoryPairExcludedName}"`
+                : `this task already declares a tool named "${memoryPairOccupiedName}" (the built-in yields to it)`) +
+            " — these tools mount together or not at all."), { phase: "config", sessionId, classification: "memory-tools-not-mounted" });
+    }
+    const skillsListing = skillSpecs.length > 0
+        ? {
+            entries: skillSpecs.map((s) => ({
+                name: s.name,
+                description: s.description,
+                ...(s.files !== undefined ? { files: s.files.map((f) => ({ path: f.path })) } : {}),
+                ...(declaredSkillRank.get(s.name) !== undefined ? { declaredRank: declaredSkillRank.get(s.name) } : {}),
+            })),
+            seedAnnounced: resume !== undefined || spec.sessionId !== undefined,
+        }
+        :
+            (resume?.seed.announcedListings?.skills?.length ?? 0) > 0 || spec.sessionId !== undefined
+                ?
+                    { entries: [], seedAnnounced: true }
+                : undefined;
+    return { memoryBlock, instructionSources, projectInstructionContent, skillSpecs, hasSkillManifest, skillsListing, sharedMemoryPairMounted, memoryEnginePairMounted };
+}

package/dist/core/runner/prepare-prompt-inputs.d.ts

@@ -0,0 +1,138 @@
+/**
+ * design/390 M10 — prepareTask's PROMPT-INPUTS phase: the prompt provider selection, the runtime
+ * feature flags the harness-context block gates on (so it never claims a mechanism the task lacks),
+ * the three-source user system prompt + the caller's append block, the fenced MCP server-instructions
+ * block, the environment facts (client zone + date basis, knowledge cutoff, the deployment's sandbox
+ * axes, resume-continuity facts on a durable-resume leg only, the hands facts + the one batched env
+ * probe with its cwd/pwd alignment guard) and the git-status lane probe. The body is the driver's
+ * stretch moved verbatim; the interface is the dependency list it had implicitly (design/238 R-1).
+ *
+ * ASYNC BY CONTENT: the stretch awaits the env probe (hands) and the git-status lane probe (always).
+ * It sits past prepareTask's first await, so the driver's `await` adds no window a caller could reach.
+ *
+ * The one input computed by the DRIVER rather than read here: `failClosedReason` — the
+ * self-orchestration fail-closed advisory's text. Its helper takes the whole `TaskSpec`/`RunnerDeps`
+ * (it audits several deployment seats), which this phase's narrow `spec`/`deps` seats cannot satisfy
+ * (design/238 R-4); the driver evaluates the helper in the Input literal and this phase only announces
+ * the result on the operator lane, exactly where the stretch always did.
+ *
+ * Nothing here throws on its own: the env probe and the alignment guard are best-effort (a stub/odd env
+ * just omits the shell-derived facts), and the git lane degrades through `onDegrade` → `deps.onError`.
+ */
+import type { ExecutionEnv, ThinkingLevel } from "../../internal/harness.js";
+import type { Model } from "../../internal/llm.js";
+import { type EnvironmentFacts, type PromptProvider } from "../../prompts/default.js";
+import type { ReadFace } from "../../tools/fs/index.js";
+import type { LockedPreflight } from "../locked-config.js";
+import type { MaterializedMcp } from "../mcp.js";
+import type { ResolvedRole } from "../roles.js";
+import type { RunnerDeps, TaskSpec } from "../types.js";
+import type { PrepareResume, RunInternals, ToolFaceSnapshot } from "./contracts.js";
+import { type GitStatusLaneRef } from "./git-status-frame.js";
+/** The runtime feature flags the stable prompt's harness-context block gates its sections on
+ *  (design/64 §6.3: claim only what the task has). Spread into the assembly's StablePromptContext
+ *  by the driver, which re-derives the two orchestration flags against the post-exclusion roster. */
+export interface PromptFeatureFlags {
+    policyEnabled: boolean;
+    hooksEnabled: boolean;
+    isolationEnabled: boolean;
+    reminderMark: string;
+    readFaceOpen: boolean;
+    orchestrationEnabled: boolean;
+    orchestrationDeferred: boolean;
+    promptProfile: "simple" | "classic";
+    fableMitigations: boolean;
+    goalEnabled: boolean;
+    awarenessEnabled: boolean;
+    worktreeIsolated: boolean;
+    withinTaskCompactionEnabled: boolean;
+    isSubagent: boolean;
+}
+export interface PreparePromptInputsInput {
+    /** borrowed-readonly — the REBOUND spec (`spec′`). Read: `promptProvider`, `hooks` (flag), `systemPrompt`
+     *  / `appendSystemPrompt` (the user prompt sources), `clientContext` (zone, email), `envFacts` (the
+     *  deployment's sandbox + resume facts), `compaction` (the within-task flag). Never mutated. */
+    spec: Pick<TaskSpec, "promptProvider" | "hooks" | "systemPrompt" | "appendSystemPrompt" | "clientContext" | "envFacts" | "compaction">;
+    /** borrowed-readonly — deployment deps: `promptProvider` (fallback), `hooks` (flag), `onError` (the
+     *  operator lane: fail-closed advisory, cwd misalignment, git-lane degrade), `modelKnowledgeCutoffs`.
+     *  Receiver preserved (`deps.onError?.(…)`). */
+    deps: Pick<RunnerDeps, "promptProvider" | "hooks" | "onError" | "modelKnowledgeCutoffs">;
+    /** borrowed-readonly — the self-orchestration fail-closed advisory (null = nothing to announce),
+     *  evaluated by the DRIVER against the whole spec/deps (see the module header). */
+    failClosedReason: string | null;
+    /** borrowed-readonly — the locked preflight; only `toolPolicy` presence is read (the policy flag). */
+    lockedPreflight: Pick<LockedPreflight, "toolPolicy">;
+    /** borrowed-readonly — whether self-orchestration is ACTIVE (the same gate that mounted the
+     *  workflow tool): drives the orchestration prompt flags. */
+    selfOrchestrationActive: boolean;
+    /** borrowed-readonly — the task's execution env: `isIsolated` for the isolation flag, `exec` for the
+     *  one batched probe, `canonicalPath` for the alignment guard. Never re-bound, never destroyed here. */
+    executionEnv: ExecutionEnv;
+    /** borrowed-readonly — the session's reminder mark (rides the prompt facts for the declaration). */
+    reminderMark: string;
+    /** borrowed-readonly — the resolved read face (the open-reads flag + the structured env fact). */
+    resolvedReadFace: ReadFace | undefined;
+    /** borrowed-readonly — the frozen tool face; only `defer` is read (the Workflow short-pointer flag). */
+    toolFaceSnapshot: Pick<ToolFaceSnapshot, "defer">;
+    /** borrowed-readonly — the resolved prompt profile (rides the flags to the legacy ctx). */
+    promptProfile: "simple" | "classic";
+    /** borrowed-readonly — the fable-mitigations profile axis (rides the flags with the profile). */
+    fableMitigations: boolean;
+    /** borrowed-readonly — trusted internals: `goalMode` (goal flag), `isolation` (worktree flag),
+     *  `defaultSystemPrompt` (the third prompt source). `undefined` on a standalone prepare. */
+    internals: Pick<RunInternals, "goalMode" | "isolation" | "defaultSystemPrompt"> | undefined;
+    /** borrowed-readonly — the resolved, role-folded reasoning tier (the awareness flag's input). */
+    thinking: ThinkingLevel | undefined;
+    /** borrowed-readonly — the factory-minted isolated env, read for PRESENCE only (the worktree flag's
+     *  belt over the fail-closed isolation guard). */
+    ownedEnv: ExecutionEnv | undefined;
+    /** borrowed-readonly — the leg's effective-delegation facts; only `isNonForkChild` is read. */
+    delegation: {
+        readonly isNonForkChild: boolean;
+    };
+    /** borrowed-readonly — the resolved role; only its `systemPrompt` preset is read (second source). */
+    resolvedRole: Pick<ResolvedRole, "systemPrompt">;
+    /** borrowed-readonly — the materialized MCP roster; only `serverInstructions` is read (fenced). */
+    mcp: Pick<MaterializedMcp, "serverInstructions">;
+    /** borrowed-readonly — the resolved model (id for the env line + the cutoff lookup). */
+    model: Model;
+    /** borrowed-readonly — the run's external-content-target fold (the single-source disclosure fact). */
+    externalContentTargetActive: boolean;
+    /** borrowed-readonly — the durable-resume carrier, read for PRESENCE only (resume facts copy on a
+     *  resume leg and never on a fresh one). */
+    resume: PrepareResume | undefined;
+    /** borrowed-readonly — whether a real execution env is mounted (the hands facts + both probes). */
+    handsEnabled: boolean;
+    /** borrowed-readonly — the FINAL task root: the env `cwd` fact and the git lane's root. */
+    taskRootFinal: string;
+    /** borrowed-readonly — the canonical extra working roots (copied into the env facts). */
+    additionalRootsCanonical: readonly string[];
+    /** borrowed-readonly — the canonical extra read-only roots (copied into the env facts). */
+    additionalReadRootsCanonical: readonly string[];
+    /** borrowed-readonly — the acquired session's id (operator-line context). */
+    sessionId: string;
+}
+export interface PreparePromptInputsResult {
+    /** owned — the prompt provider in force (`spec` ?? `deps` ?? the default). */
+    provider: PromptProvider;
+    /** owned — the runtime feature flags (see {@link PromptFeatureFlags}). */
+    featureFlags: PromptFeatureFlags;
+    /** owned — the user system prompt: `spec.systemPrompt ?? resolvedRole.systemPrompt ?? internals.defaultSystemPrompt`. */
+    userSystemPrompt: string | undefined;
+    /** owned — the caller's append block (`spec.appendSystemPrompt`). */
+    userAppendSystemPrompt: string | undefined;
+    /** owned — the fenced MCP server-instructions block, or undefined when no server declared any. */
+    mcpInstructionsBlock: string | undefined;
+    /** owned — the environment facts the env tail renders from. Filled here; no later phase writes it
+     *  (the run loop re-renders only the date through `renderWithDate`). */
+    envFacts: EnvironmentFacts;
+    /** owned — whether the client zone validated (the date-change seam re-renders in the same zone). */
+    tzValid: boolean;
+    /** owned — the client's declared zone as given (paired with `tzValid`; unvalidated on its own). */
+    userTz: string | undefined;
+    /** owned — the git-status lane's run-local state (empty on a hands-less leg); the run loop and the
+     *  checkpoint serializer mutate its fields from here on (`announced`, `pendingReceipt`, …). */
+    gitStatusRef: GitStatusLaneRef;
+}
+/** The M10 phase body — prepareTask's prompt-inputs stretch, verbatim (see the module header). */
+export declare function preparePromptInputs(input: PreparePromptInputsInput): Promise<PreparePromptInputsResult>;

package/dist/core/runner/prepare-prompt-inputs.js

@@ -0,0 +1,141 @@
+import { defaultPromptProvider, formatLocalDate, isValidTimeZone } from "../../prompts/default.js";
+import { isIsolated } from "../remote-env.js";
+import { probeGitStatusLane } from "./git-status-frame.js";
+import { fenceMcpServerInstructions } from "./turn-attachments.js";
+const ULTRA_REASONING_TIERS = new Set(["xhigh", "max"]);
+export async function preparePromptInputs(input) {
+    const { spec, deps, failClosedReason, lockedPreflight, selfOrchestrationActive, executionEnv, reminderMark, resolvedReadFace, toolFaceSnapshot, promptProfile, fableMitigations, internals, thinking, ownedEnv, delegation, resolvedRole, mcp, model, externalContentTargetActive, resume, handsEnabled, taskRootFinal, additionalRootsCanonical, additionalReadRootsCanonical, sessionId } = input;
+    const provider = spec.promptProvider ?? deps.promptProvider ?? defaultPromptProvider;
+    const promptPolicyEnabled = Boolean(lockedPreflight.toolPolicy);
+    const promptHooks = spec.hooks ?? deps.hooks;
+    const promptHooksEnabled = Boolean(promptHooks?.preToolUse || promptHooks?.postToolUse);
+    if (failClosedReason) {
+        deps.onError?.(new Error(failClosedReason), { phase: "config", sessionId });
+    }
+    const featureFlags = {
+        policyEnabled: promptPolicyEnabled,
+        hooksEnabled: promptHooksEnabled,
+        isolationEnabled: isIsolated(executionEnv),
+        reminderMark,
+        readFaceOpen: resolvedReadFace === "open",
+        orchestrationEnabled: selfOrchestrationActive,
+        orchestrationDeferred: selfOrchestrationActive && (toolFaceSnapshot.defer?.includes("Workflow") ?? false),
+        promptProfile,
+        fableMitigations,
+        goalEnabled: internals?.goalMode === true,
+        awarenessEnabled: thinking !== undefined && ULTRA_REASONING_TIERS.has(thinking),
+        worktreeIsolated: internals?.isolation === "worktree" && ownedEnv !== undefined,
+        withinTaskCompactionEnabled: (spec.compaction?.enabled ?? true) && (spec.compaction?.withinTask ?? true),
+        isSubagent: delegation.isNonForkChild,
+    };
+    const userSystemPrompt = spec.systemPrompt ?? resolvedRole.systemPrompt ?? internals?.defaultSystemPrompt;
+    const userAppendSystemPrompt = spec.appendSystemPrompt;
+    const mcpInstructionsBlock = mcp.serverInstructions.length
+        ? `# MCP Server Instructions\n${mcp.serverInstructions.map((s) => fenceMcpServerInstructions(s.server, s.text)).join("\n\n")}`
+        : undefined;
+    const userTz = spec.clientContext?.timeZone;
+    const tzValid = userTz !== undefined && isValidTimeZone(userTz);
+    const envFacts = { date: formatLocalDate(new Date(), tzValid ? userTz : undefined), modelId: model.id };
+    if (tzValid)
+        envFacts.timeZone = userTz;
+    if (spec.clientContext?.userEmail)
+        envFacts.userEmail = spec.clientContext.userEmail;
+    const declaredCutoff = deps.modelKnowledgeCutoffs?.[model.id];
+    if (declaredCutoff)
+        envFacts.knowledgeCutoff = declaredCutoff;
+    if (spec.envFacts?.profile)
+        envFacts.sandboxProfile = spec.envFacts.profile;
+    if (spec.envFacts?.capabilities && spec.envFacts.capabilities.length > 0)
+        envFacts.sandboxCapabilities = [...spec.envFacts.capabilities];
+    if (spec.envFacts?.pkgSource)
+        envFacts.sandboxPkgSource = spec.envFacts.pkgSource;
+    if (spec.envFacts?.egress === "none" || spec.envFacts?.egress === "allowlist" || spec.envFacts?.egress === "full")
+        envFacts.sandboxEgress = spec.envFacts.egress;
+    if (spec.envFacts?.scratchpadDir)
+        envFacts.scratchpadDir = spec.envFacts.scratchpadDir;
+    if (externalContentTargetActive)
+        envFacts.externalContentTarget = true;
+    if (resume !== undefined && spec.envFacts?.resumeFacts) {
+        const rf = spec.envFacts.resumeFacts;
+        const copy = {};
+        if (rf.processes === "preserved" || rf.processes === "lost")
+            copy.processes = rf.processes;
+        if (rf.scratch === "preserved" || rf.scratch === "lost")
+            copy.scratch = rf.scratch;
+        if (typeof rf.note === "string" && rf.note.length > 0)
+            copy.note = rf.note;
+        if (Object.keys(copy).length > 0)
+            envFacts.resumeFacts = copy;
+    }
+    if (handsEnabled) {
+        envFacts.cwd = taskRootFinal;
+        if (additionalRootsCanonical.length > 0) {
+            envFacts.additionalDirectories = [...additionalRootsCanonical];
+        }
+        if (resolvedReadFace !== undefined)
+            envFacts.readFace = resolvedReadFace;
+        if (additionalReadRootsCanonical.length > 0) {
+            envFacts.additionalReadDirectories = [...additionalReadRootsCanonical];
+        }
+        try {
+            const probe = await executionEnv.exec('uname -s; uname -r; (git rev-parse --is-inside-work-tree 2>/dev/null || echo false); (git symbolic-ref --short -q HEAD 2>/dev/null || echo "HEAD (detached)"); (git rev-parse --show-toplevel 2>/dev/null || echo); (test -n "$(git status --porcelain 2>/dev/null | head -1)" && echo dirty || echo clean); (s=$(ps -p $$ -o comm= 2>/dev/null); s=${s##*/}; echo "${s#-}"); (test "$(git rev-parse --git-dir 2>/dev/null)" != "$(git rev-parse --git-common-dir 2>/dev/null)" && echo linked || echo main); (pwd -P 2>/dev/null || pwd)', { cwd: envFacts.cwd, timeout: 10 });
+            if (probe.ok && probe.value.exitCode === 0) {
+                const lines = probe.value.stdout.split("\n");
+                if (lines.length >= 6) {
+                    const [osName, osVer, git, branch, worktreeRoot, dirty] = lines;
+                    if (osName?.trim())
+                        envFacts.platform = osName.trim();
+                    if (osVer?.trim())
+                        envFacts.osVersion = osVer.trim();
+                    envFacts.isGitRepo = (git ?? "").trim() === "true";
+                    if (envFacts.isGitRepo) {
+                        const b = (branch ?? "").trim();
+                        if (b)
+                            envFacts.gitBranch = b;
+                        const root = (worktreeRoot ?? "").trim();
+                        if (root)
+                            envFacts.gitWorktreeRoot = root;
+                        const d = (dirty ?? "").trim();
+                        if (d === "dirty" || d === "clean")
+                            envFacts.gitDirty = d === "dirty";
+                    }
+                    const sh = (lines[6] ?? "").trim();
+                    if (sh)
+                        envFacts.shell = sh;
+                    if (envFacts.isGitRepo && (lines[7] ?? "").trim() === "linked")
+                        envFacts.isLinkedWorktree = true;
+                    const probedPwd = (lines[8] ?? "").trim();
+                    if (probedPwd && envFacts.cwd && probedPwd !== envFacts.cwd) {
+                        const canonOf = async (p) => {
+                            try {
+                                const c = await executionEnv.canonicalPath(p);
+                                return c.ok ? c.value : p;
+                            }
+                            catch {
+                                return p;
+                            }
+                        };
+                        const canonicalProbed = await canonOf(probedPwd);
+                        if (canonicalProbed !== (await canonOf(envFacts.cwd))) {
+                            try {
+                                deps.onError?.(new Error(`execution-env cwd misalignment: task root is "${envFacts.cwd}" but the env's shell reports pwd "${canonicalProbed}" — per-exec cwd injection may be ignored on this lane (execs/artifacts can land outside the workspace root)`), { phase: "config", sessionId });
+                            }
+                            catch {
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        catch {
+        }
+    }
+    const gitStatusRef = await probeGitStatusLane({
+        executionEnv,
+        envFacts,
+        handsEnabled,
+        taskRoot: taskRootFinal,
+        onDegrade: (reason) => deps.onError?.(new Error(`env git snapshot degraded — ${reason}`), { phase: "degraded", sessionId, classification: "env-git-snapshot" }),
+    });
+    return { provider, featureFlags, userSystemPrompt, userAppendSystemPrompt, mcpInstructionsBlock, envFacts, tzValid, userTz, gitStatusRef };
+}