@sema-agent/core 7.5.0 → 7.5.2

package/dist/core/runner/prepare-caps-and-workflow.d.ts

@@ -0,0 +1,170 @@
+/**
+ * design/390 §1.2 M4 — prepareTask's CAPS-AND-WORKFLOW phase, verbatim from the driver: the caller-tool roster
+ * map (the defineTool-product branch and the rich-ctx wrap through the large-result wrapper), the ReportBlocked /
+ * ReportFindings / plan-pair mounts, the per-principal runtime caps resolve with its fail-closed degrade and value
+ * screen, the compliance posture veto with its two refusal codes, the fork verdict and the observers grant, the
+ * auto-mode arming (classifier model, lane rule, decider + denial tracker + persisted recipe) with its manifest
+ * reason, the self-orchestration gate with its governance note, and the Workflow mount with its size-guideline
+ * seat. The three arming helpers and the parent-capture-state join moved with the segment (only this phase calls
+ * them). The interface is the dependency list the segment had implicitly (design/238 R-1).
+ *
+ * ASYNC PHASE: the segment awaits the two resolvers, the classifier route pre-flight and the Workflow factory,
+ * exactly where the driver awaited them; the roster map and the synthetic mounts before the first of those awaits
+ * run synchronously as they did. Read-stability of the host handles for the call: {@link RunInternals}
+ * (`@contract prepare.deps-read-stable`).
+ *
+ * THE ROSTER IS MINTED HERE (`tools`): every later phase that mounts pushes into this same array — the writer table
+ * lives on {@link Prepared.tools} (design/238 R-3). LATE-BOUND SEATS: the Workflow mount's call-time getters read
+ * three facts later stations resolve (the memory session, the center adoption, the hands mount's deny additions);
+ * each enters as a getter on the Input and is read exactly where the driver's getter read the variable.
+ */
+import type { AgentHarness, AgentTool, ThinkingLevel } from "../../internal/harness.js";
+import type { Model } from "../../internal/llm.js";
+import { forkGovernanceDenial } from "../../agents/subagent.js";
+import type { PromptEpochArtifact } from "../../prompt-assembly/artifact.js";
+import { createRunWorkflowTool } from "../../orchestration/run-workflow-tool.js";
+import { type WorkflowSizeGuideline } from "../../orchestration/workflow-size-guideline.js";
+import { type AutoModeArmingRecipe } from "../auto-mode-arming.js";
+import { type AutoModeDecider, type AutoModeDenialTracker } from "../auto-mode.js";
+import { type ComplianceCapability } from "../compliance.js";
+import type { LockedPreflight } from "../locked-config.js";
+import type { StoredSession } from "../session.js";
+import type { OnAsk } from "../tool-policy.js";
+import type { RunnerDeps, RuntimeCaps, TaskEvent, TaskSpec, ToolExecuteContext } from "../types.js";
+import type { AutoModeArmReason } from "../wiring-manifest.js";
+import type { ReadFace } from "../../tools/fs/index.js";
+import type { InheritedGate, Prepared, RunInternals, ToolFaceSnapshot } from "./contracts.js";
+import { type BlockedRef } from "./synthetic-tools.js";
+/** The runner the Workflow mount accepts — 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; see the layering registry). */
+type WorkflowMountRunner = Parameters<typeof createRunWorkflowTool>[0]["runner"];
+export interface PrepareCapsAndWorkflowInput {
+    /** borrowed-readonly — the REBOUND spec, whole: the roster map reads `tools`; the mounts read `enableBlockedReport`,
+     *  `enablePlanMode`, `interactiveTools`, `checkpointStore`; the caps/compliance stations read `principal`, `selfOrchestration`,
+     *  `enableFork`, `getApiKeyAndHeaders`; the Workflow mount forwards `oneShot`, `handsReadOnly`, `interactiveTools`. The
+     *  self-orchestration predicate takes the whole spec. Never mutated. */
+    spec: TaskSpec;
+    /** borrowed-readonly — the deployment seats, whole: `runtimeCapsResolver`, `compliancePostureResolver`, `onError`, `onNotice`,
+     *  `autoMode`, `brain`, `models`, `checkpointStore` (the plan-pair face), and the Workflow mount's dozen deps (`workflowScriptRunner`,
+     *  `workflowGovernanceBaseline`, `workflowRunStore`, `workflowJournalStore`, `workflowScriptStore`, `builtinWorkflows`,
+     *  `onWorkflowAgentSpawn`, `workflowCompletionNotifier`, `workflowLimits`, `agents`, `builtinAgents`, `onBackgroundChildEvent`).
+     *  The self-orchestration predicate takes the whole record. */
+    deps: RunnerDeps;
+    /** borrowed-readonly — the trusted spawn-side channel; the Workflow mount forwards `rootSessionId`, `placementRoot`,
+     *  `onTaskNotification`, `workflowDepth`, and the capture-floor getter reads `memoryCaptureAncestors`. */
+    internals: Pick<RunInternals, "rootSessionId" | "placementRoot" | "onTaskNotification" | "workflowDepth" | "memoryCaptureAncestors"> | undefined;
+    /** borrowed-readonly — the acquired session; the classifier leg rebuilds its transcript window from `buildContext`. */
+    session: Pick<StoredSession, "buildContext">;
+    /** borrowed-readonly — the acquired session id (operator-line context, the refusal codes' phase record). */
+    sessionId: string;
+    /** borrowed-readonly — the run's invocation id (the classifier route pre-flight's notice names it). */
+    runId: string;
+    /** borrowed-readonly — the per-task identity the Workflow mount registers its children under. */
+    hostTaskId: string;
+    /** borrowed-readonly — the registry scope the Workflow mount registers in. */
+    taskScope: string;
+    /** borrowed-readonly — the SETTLED task root the Workflow mount hands its children as `parentCwd`. */
+    taskRootFinal: string;
+    /** borrowed-readonly — the run's resolved model: the classifier leg's fallback and the route pre-flight's primary. */
+    model: Model;
+    /** borrowed-readonly — the run's resolved thinking level, when one is (the Workflow mount's parentThinking fallback). */
+    thinking: ThinkingLevel | undefined;
+    /** borrowed-readonly — the frozen preflight; only `mcp` (the compliance veto's mcp_servers conflict check). */
+    lockedPreflight: Pick<LockedPreflight, "mcp">;
+    /** borrowed-mutable — the effect collection (`Prepared.toolEffects`). Writer here: ONE set, `Workflow → write`, at its mount.
+     *  Every other writer is the safety scan (the seed) and the later mounts (see the roster table on `Prepared.tools`). */
+    toolEffects: Prepared["toolEffects"];
+    /** borrowed-readonly — the frozen tool-face snapshot the Workflow mount forwards (exclude / defer / alwaysLoad / restoreGated). */
+    toolFaceSnapshot: ToolFaceSnapshot;
+    /** borrowed-readonly — the resolved prompt profile (the Workflow mount's parentPromptProfile). */
+    promptProfile: ToolExecuteContext["promptProfile"];
+    /** borrowed-readonly — the resolved interaction posture (the Workflow mount's parentInteractionPosture; absent ⇒ no key). */
+    resolvedInteractionPosture: ToolExecuteContext["interactionPosture"];
+    /** borrowed-readonly — the harness seat; the Workflow mount's parentModel / parentThinking getters read it call-time. */
+    harnessRef: {
+        current?: AgentHarness;
+    };
+    /** borrowed-readonly — the FROZEN approver seat (the Workflow mount's parentOnAsk). */
+    frozenOnAsk: OnAsk | undefined;
+    /** borrowed-readonly — the ONE read-face carrier expression (the Workflow mount's parentReadFace getter calls it). */
+    carrierReadFace: () => ReadFace | undefined;
+    /** borrowed-readonly — the filtered display-forwarding wrapper (the Workflow mount's forwardEvent; absent ⇒ no key). */
+    forwardEvent: ((e: TaskEvent) => void) | undefined;
+    /** borrowed-readonly — the child-chain assembly (the Workflow mount's inheritedGateForChildren). */
+    inheritedGateForChildren: () => InheritedGate;
+    /** borrowed-readonly — the caller-tool ctx enrichment the roster map wraps every raw ToolSpec with. */
+    enrichSpecToolCtx: (ctx: ToolExecuteContext) => ToolExecuteContext;
+    /** borrowed-readonly — the large-result wrapper every roster entry passes through (per-tool policy honored inside). */
+    maybeOffload: (tool: AgentTool, perTool?: {
+        offload?: boolean;
+        offloadThresholdChars?: number;
+    }) => AgentTool;
+    /** borrowed-readonly — the plan-review primitive the ExitPlanMode tool calls. */
+    requestReview: (opts?: {
+        reason?: string;
+    }) => void;
+    /** borrowed-readonly — the plan-mode primitive the EnterPlanMode tool calls. */
+    enterPlanMode: () => void;
+    /** borrowed-readonly — the auto-mode INTENT (own seat ∨ chain ∨ checkpoint), the arming's first arm. */
+    autoModeIntent: boolean;
+    /** borrowed-readonly — the peer lane's mount verdict (the classifier's cross-session rule fills only while mounted). */
+    peerLaneActive: boolean;
+    /** borrowed-readonly — whether the BUILT-IN SendMessage is on this face (the lane rule's second term). */
+    peerSendMessageBuiltIn: boolean;
+    /** borrowed-readonly — the trusted Runner self-reference the Workflow mount executes children through; undefined when
+     *  prepareTask runs standalone (then Workflow is simply not mounted). */
+    runnerSelf: WorkflowMountRunner | undefined;
+    /** borrowed-readonly — LATE-BOUND: the memory-engine session; the Workflow mount's capture-floor getter reads it at ITS call time. */
+    memoryEngineSession: () => Prepared["memoryEngineSession"];
+    /** borrowed-readonly — LATE-BOUND: the adopted center artifact; the Workflow mount's two center getters read it at THEIR call time. */
+    centerAdoption: () => {
+        artifact: PromptEpochArtifact;
+        sourceRevision?: string;
+    } | undefined;
+    /** borrowed-readonly — LATE-BOUND: the normalized deny additions; the Workflow mount's parentReadDenyPatterns getter reads it at call time. */
+    readDenyAdditionsNormalized: () => ReadonlyArray<{
+        pattern: string;
+        caseSensitive: boolean;
+    }>;
+}
+export interface PrepareCapsAndWorkflowResult {
+    /** owned — THE run's roster, minted here from the caller's tools; every later mount pushes into this same array
+     *  (`Prepared.tools`, whose JSDoc carries the writer table). Writers here: the map that mints it, then the ReportBlocked,
+     *  ReportFindings, ExitPlanMode, EnterPlanMode and Workflow pushes. */
+    tools: AgentTool[];
+    /** borrowed-mutable — the ReportBlocked tool's write seat (`Prepared.blockedRef`). Writer: the tool at run time; read at
+     *  result assembly. */
+    blockedRef: BlockedRef;
+    /** owned — the per-principal entitlements as resolved (or the fail-closed degrade), undefined = no restriction. */
+    runtimeCaps: RuntimeCaps | undefined;
+    /** owned — whether the caps resolve FAULTED (throw or value screen) — never read off a coined explicit value. */
+    runtimeCapsFaulted: boolean;
+    /** owned — the compliance deny set (every capability under a resolver fault). */
+    complianceDenies: ReadonlySet<ComplianceCapability>;
+    /** owned — whether the compliance resolve faulted (the refusal code distinguishes it). */
+    complianceDegraded: boolean;
+    /** owned — the fork-governance verdict (present only when denied; the ctx reads it call-time). */
+    agentForkDenial: ReturnType<typeof forkGovernanceDenial>;
+    /** owned — the observers grant (`allowObservers === true`, explicit opt-in). */
+    observersActive: boolean;
+    /** owned — the arming outcome as a closed reason (the manifest's auto-mode face). */
+    autoModeArmReason: AutoModeArmReason;
+    /** owned — the armed classifier, or undefined when any arming arm failed. */
+    autoModeDecider: AutoModeDecider | undefined;
+    /** owned — the denial tracker built beside the decider (same face, same arming). */
+    autoModeDenialTracking: AutoModeDenialTracker | undefined;
+    /** owned — the serializable arming recipe (persistArming opt-in only). */
+    autoModeArming: AutoModeArmingRecipe | undefined;
+    /** owned — self-orchestration is ACTIVE for this leg (deployment ready ∧ not entitlement-denied); drives the prompt injection. */
+    selfOrchestrationActive: boolean;
+    /** owned — the Workflow tool is on the roster (the delegation surface's second door). */
+    workflowToolsActive: boolean;
+    /** owned — the mid-session size-guideline seat, armed with the Workflow mount (`Prepared.workflowSizeGuideline`). */
+    workflowSizeGuideline: {
+        legGuideline: WorkflowSizeGuideline;
+        current: () => WorkflowSizeGuideline;
+    } | undefined;
+}
+/** The M4 phase body — prepareTask's caps-and-workflow stretch, verbatim (see the module header). */
+export declare function prepareCapsAndWorkflow(input: PrepareCapsAndWorkflowInput): Promise<PrepareCapsAndWorkflowResult>;
+export {};

package/dist/core/runner/prepare-caps-and-workflow.js

@@ -0,0 +1,255 @@
+import { isSyntheticApiErrorMessage } from "../../internal/harness.js";
+import { createHash } from "node:crypto";
+import { forkGovernanceDenial } from "../../agents/subagent.js";
+import { CROSS_SESSION_CLASSIFIER_RULE } from "../../agents/cross-session-envelope.js";
+import { createRunWorkflowTool, RUN_WORKFLOW_TOOL_NAME } from "../../orchestration/run-workflow-tool.js";
+import { isSelfOrchestrationActive } from "../../orchestration/workflow-script-runner.js";
+import { resolveWorkflowSizeGuideline } from "../../orchestration/workflow-size-guideline.js";
+import { autoModeArmingRecipeOf } from "../auto-mode-arming.js";
+import { buildAutoModePrompt, renderAutoModeAction, renderAutoModeWindow } from "../auto-mode-prompt.js";
+import { createAutoModeDecider, createAutoModeDenialTracker } from "../auto-mode.js";
+import { resolveCheckpointStore } from "../checkpoint-store.js";
+import { COMPLIANCE_CAPABILITIES, WEB_FETCH_TOOL_NAME, resolveComplianceDenies } from "../compliance.js";
+import { createPresentPlanTool, createEnterPlanModeTool } from "../present-plan-tool.js";
+import { resolveTaskModel } from "../roles.js";
+import { brainToRuntime } from "../runtime.js";
+import { defaultTaskRegistry } from "../task-registry.js";
+import { defineTool, isDefineToolProduct } from "../tools.js";
+import { derivedRouteFallsBack } from "./derived-route-fallback.js";
+import { REPORT_FINDINGS_TOOL_NAME, createReportBlockedTool, createReportFindingsTool } from "./synthetic-tools.js";
+function assembleParentCaptureState(o, i, ctl, ancestors) {
+    const build = (optedOut, indeterminate) => ({
+        optedOut: optedOut === true,
+        indeterminate: indeterminate === true,
+        ...(ctl !== undefined ? { controlDir: ctl } : {}),
+        ancestors,
+    });
+    return o instanceof Promise || i instanceof Promise ? Promise.all([o, i]).then(([ov, iv]) => build(ov, iv)) : build(o, i);
+}
+function screenAutoModeCap(caps, onError, sessionId) {
+    if (caps === undefined)
+        return { caps, faulted: false };
+    if (typeof caps !== "object" || caps === null || Array.isArray(caps)) {
+        onError?.(new Error(`runtimeCapsResolver returned a non-record value (${JSON.stringify(caps)}) — read as a resolver fault: every per-principal capability is DENIED for this run (auto mode is not armed; asks flow the original chain). Return a RuntimeCaps object or undefined.`), { phase: "config", sessionId });
+        return { caps: { allowWorkflows: false, allowFork: false, autoMode: false }, faulted: true };
+    }
+    const record = caps;
+    if (record.autoMode === undefined || typeof record.autoMode === "boolean")
+        return { caps: record, faulted: false };
+    onError?.(new Error(`runtimeCapsResolver returned a non-boolean autoMode (${JSON.stringify(record.autoMode)}) — read as a resolver fault: auto mode is DENIED for this run (the classifier is not armed; asks flow the original chain). Return true, false, or omit the key.`), { phase: "config", sessionId });
+    return { caps: { ...record, autoMode: false }, faulted: true };
+}
+function mintPersistedArming(am, laneRule, classifierSystemPrompt, onError, sessionId) {
+    const arming = autoModeArmingRecipeOf(laneRule ? { ...am, crossSessionMessagesRule: true } : am, {
+        promptDigest: `apv1:${createHash("sha256").update(classifierSystemPrompt).digest("hex")}`,
+    });
+    if (arming === undefined) {
+        onError?.(new Error("RunnerDeps.autoMode.persistArming is set but the auto-mode face did not canonicalize into an arming recipe " +
+            "(a rule list carrying a non-string, or a non-finite/out-of-range timeoutMs / failureThreshold / window bound) — " +
+            "NO arming recipe is recorded on this run's parked constraint chain, and a cross-process redemption keeps the " +
+            "conservative behavior (the ancestor classifier answers unavailable and the inherited ask flows to a human)"), { phase: "config", sessionId });
+    }
+    return arming;
+}
+function autoModeArmReasonOf(intent, facePresent, capsAutoMode, capsFaulted) {
+    if (!intent)
+        return "no_intent";
+    if (!facePresent)
+        return "no_face";
+    if (capsAutoMode === false)
+        return capsFaulted ? "resolver_fault" : "denied";
+    return "armed";
+}
+export async function prepareCapsAndWorkflow(input) {
+    const { spec, deps, internals, session, sessionId, runId, hostTaskId, taskScope, taskRootFinal, model, thinking, lockedPreflight, toolEffects, toolFaceSnapshot, promptProfile, resolvedInteractionPosture, harnessRef, frozenOnAsk, carrierReadFace, forwardEvent, inheritedGateForChildren, enrichSpecToolCtx, maybeOffload, requestReview, enterPlanMode, autoModeIntent, peerLaneActive, peerSendMessageBuiltIn, runnerSelf } = input;
+    const tools = (spec.tools ?? []).map((t) => {
+        if (isDefineToolProduct(t)) {
+            return maybeOffload(t, t);
+        }
+        return maybeOffload(defineTool({
+            ...t,
+            execute: (args, ctx) => t.execute(args, enrichSpecToolCtx(ctx)),
+        }), t);
+    });
+    const blockedRef = {};
+    if (spec.enableBlockedReport !== false) {
+        tools.push(createReportBlockedTool(blockedRef));
+    }
+    if (!(spec.tools ?? []).some((t) => t.name === REPORT_FINDINGS_TOOL_NAME || t.aliases?.includes(REPORT_FINDINGS_TOOL_NAME))) {
+        tools.push(createReportFindingsTool());
+    }
+    if (spec.enablePlanMode === true && spec.interactiveTools !== false) {
+        const planReviewFace = resolveCheckpointStore(spec, deps) !== undefined;
+        if (spec.interactiveTools === true || planReviewFace) {
+            tools.push(defineTool(createPresentPlanTool(requestReview)));
+            if (planReviewFace) {
+                tools.push(defineTool(createEnterPlanModeTool(enterPlanMode)));
+            }
+        }
+    }
+    let runtimeCaps;
+    let runtimeCapsFaulted = false;
+    if (deps.runtimeCapsResolver) {
+        try {
+            runtimeCaps = (await deps.runtimeCapsResolver(spec.principal)) ?? undefined;
+        }
+        catch (err) {
+            deps.onError?.(err instanceof Error ? err : new Error(String(err)), { phase: "config", sessionId });
+            runtimeCaps = { allowWorkflows: false, allowFork: false, autoMode: false };
+            runtimeCapsFaulted = true;
+        }
+        const screened = screenAutoModeCap(runtimeCaps, deps.onError, sessionId);
+        runtimeCaps = screened.caps;
+        runtimeCapsFaulted ||= screened.faulted;
+    }
+    let complianceDenies = new Set();
+    let complianceDegraded = false;
+    if (deps.compliancePostureResolver) {
+        try {
+            const posture = (await deps.compliancePostureResolver(spec.principal)) ?? undefined;
+            if (posture !== undefined)
+                complianceDenies = resolveComplianceDenies(posture);
+        }
+        catch (err) {
+            deps.onError?.(err instanceof Error ? err : new Error(String(err)), { phase: "config", sessionId });
+            complianceDenies = new Set(COMPLIANCE_CAPABILITIES);
+            complianceDegraded = true;
+        }
+        const complianceRefuse = (capability, requested) => {
+            const e = new Error(`${requested} is denied for this principal by the compliance posture (capability "${capability}"` +
+                `${complianceDegraded ? "; the posture resolver is currently failing, so every managed capability is denied fail-closed" : ""}) — ` +
+                `the task is refused rather than silently narrowed.`);
+            e.code = complianceDegraded ? "config.compliance_required" : "config.compliance_denied";
+            throw e;
+        };
+        if (complianceDenies.has("mcp_servers") && lockedPreflight.mcp?.length) {
+            complianceRefuse("mcp_servers", "TaskSpec.mcp (MCP server materialization)");
+        }
+        if (complianceDenies.has("workflows") && spec.selfOrchestration === true) {
+            complianceRefuse("workflows", "TaskSpec.selfOrchestration (workflow self-orchestration)");
+        }
+        if (complianceDenies.has("web_fetch")) {
+            const webTool = (spec.tools ?? []).find((t) => t.name === WEB_FETCH_TOOL_NAME || (t.aliases ?? []).includes(WEB_FETCH_TOOL_NAME));
+            if (webTool !== undefined) {
+                complianceRefuse("web_fetch", `TaskSpec.tools["${webTool.name}"] (the WebFetch tool face)`);
+            }
+        }
+    }
+    const agentForkDenial = forkGovernanceDenial(spec.enableFork, runtimeCaps?.allowFork);
+    const observersActive = runtimeCaps?.allowObservers === true;
+    let autoModeDecider;
+    let autoModeDenialTracking;
+    let autoModeArming;
+    const autoModeArmReason = autoModeArmReasonOf(autoModeIntent, deps.autoMode !== undefined, runtimeCaps?.autoMode, runtimeCapsFaulted);
+    if (autoModeIntent && deps.autoMode !== undefined && runtimeCaps?.autoMode !== false) {
+        const am = deps.autoMode;
+        let classifierModel;
+        try {
+            classifierModel = resolveTaskModel({ modelRole: "classifier" }, deps).model;
+        }
+        catch {
+            classifierModel = model;
+        }
+        if (await derivedRouteFallsBack({ seat: "auto-mode-classifier", derived: classifierModel, primary: model, brain: deps.brain, getApiKeyAndHeaders: spec.getApiKeyAndHeaders, onNotice: deps.onNotice, sessionId, runId })) {
+            classifierModel = model;
+        }
+        const classifierLaneRule = peerLaneActive && peerSendMessageBuiltIn;
+        const classifierSystemPrompt = buildAutoModePrompt(classifierLaneRule ? { ...am, crossSessionMessagesRule: CROSS_SESSION_CLASSIFIER_RULE } : am);
+        const classifierRuntime = brainToRuntime(deps.brain);
+        autoModeDenialTracking = createAutoModeDenialTracker(am.denialLimit);
+        autoModeDecider = createAutoModeDecider({
+            ...(am.timeoutMs !== undefined ? { timeoutMs: am.timeoutMs } : {}),
+            ...(am.failureThreshold !== undefined ? { failureThreshold: am.failureThreshold } : {}),
+            ...(am.onBreakerOpen !== undefined ? { onBreakerOpen: am.onBreakerOpen } : {}),
+            classify: async (input, signal) => {
+                const ctx = await session.buildContext();
+                const known = ctx.messages.filter((m) => !isSyntheticApiErrorMessage(m) &&
+                    (m.role === "user" || m.role === "assistant" || m.role === "toolResult"));
+                const userPrompt = renderAutoModeWindow(known, am.window) + renderAutoModeAction(input);
+                const classifierAuth = await spec.getApiKeyAndHeaders?.(classifierModel);
+                const response = await classifierRuntime.completeSimple(classifierModel, { systemPrompt: classifierSystemPrompt, messages: [{ role: "user", content: userPrompt, timestamp: Date.now() }] }, {
+                    signal,
+                    ...(classifierAuth?.apiKey !== undefined ? { apiKey: classifierAuth.apiKey } : {}),
+                    ...(classifierAuth?.headers !== undefined ? { headers: classifierAuth.headers } : {}),
+                });
+                return response.content
+                    .filter((c) => c.type === "text")
+                    .map((c) => c.text)
+                    .join("");
+            },
+        });
+        if (am.persistArming === true)
+            autoModeArming = mintPersistedArming(am, classifierLaneRule, classifierSystemPrompt, deps.onError, sessionId);
+    }
+    const deploymentWorkflowReady = runnerSelf !== undefined && isSelfOrchestrationActive(spec, deps);
+    const selfOrchestrationActive = deploymentWorkflowReady && runtimeCaps?.allowWorkflows !== false;
+    if (deploymentWorkflowReady && runtimeCaps?.allowWorkflows === false) {
+        deps.onError?.(new Error(`self-orchestration DENIED for principal "${spec.principal ?? ""}" by runtimeCaps.allowWorkflows=false ` +
+            `(per-principal entitlement governance, not a misconfiguration — the run_workflow tool is not mounted)`), { phase: "config", sessionId });
+    }
+    let workflowToolsActive = false;
+    let workflowSizeGuideline;
+    if (selfOrchestrationActive && runnerSelf && deps.workflowScriptRunner && deps.workflowGovernanceBaseline) {
+        workflowToolsActive = true;
+        const currentSizeGuideline = () => resolveWorkflowSizeGuideline(deps.workflowLimits?.sizeGuideline).size;
+        workflowSizeGuideline = { legGuideline: currentSizeGuideline(), current: currentSizeGuideline };
+        toolEffects.set(RUN_WORKFLOW_TOOL_NAME, "write");
+        tools.push(await createRunWorkflowTool({
+            runner: runnerSelf,
+            scriptRunner: deps.workflowScriptRunner,
+            governanceBaseline: deps.workflowGovernanceBaseline,
+            parentExcludeTools: toolFaceSnapshot.exclude,
+            parentDeferTools: toolFaceSnapshot.defer,
+            parentAlwaysLoadTools: toolFaceSnapshot.alwaysLoad,
+            ...(toolFaceSnapshot.restoreGated !== undefined ? { parentRestoreGatedTools: toolFaceSnapshot.restoreGated } : {}),
+            parentPromptProfile: promptProfile,
+            models: deps.models,
+            agents: deps.agents,
+            builtinAgents: deps.builtinAgents,
+            store: deps.workflowRunStore,
+            journalStore: deps.workflowJournalStore,
+            ...(deps.onBackgroundChildEvent ? { onBackgroundChildEvent: deps.onBackgroundChildEvent } : {}),
+            scriptStore: deps.workflowScriptStore,
+            builtinWorkflows: deps.builtinWorkflows,
+            onAgentSpawn: deps.onWorkflowAgentSpawn,
+            scope: taskScope,
+            notifier: deps.workflowCompletionNotifier,
+            originatingSessionId: sessionId,
+            rootSessionId: internals?.rootSessionId ?? sessionId, ...(internals?.placementRoot !== undefined ? { placementRoot: internals.placementRoot } : {}),
+            taskRegistry: defaultTaskRegistry,
+            taskNotification: internals?.onTaskNotification,
+            taskOwner: hostTaskId,
+            limits: deps.workflowLimits,
+            sourceTaskId: hostTaskId,
+            parentModel: () => harnessRef.current?.getModel(),
+            ...(spec.getApiKeyAndHeaders !== undefined ? { parentGetApiKeyAndHeaders: spec.getApiKeyAndHeaders } : {}),
+            ...(frozenOnAsk !== undefined ? { parentOnAsk: frozenOnAsk } : {}),
+            principal: spec.principal,
+            oneShot: spec.oneShot,
+            ...(resolvedInteractionPosture !== undefined ? { parentInteractionPosture: resolvedInteractionPosture } : {}),
+            parentMemoryCaptureState: () => {
+                const memoryEngineSession = input.memoryEngineSession();
+                const ctl = memoryEngineSession?.engine.controlPlaneDir;
+                const co = memoryEngineSession?.captureOptOut;
+                return assembleParentCaptureState(co?.optedOut() ?? false, co?.indeterminate() ?? false, ctl, [...(internals?.memoryCaptureAncestors ?? []), { sessionId, ...(ctl !== undefined ? { controlDir: ctl } : {}) }]);
+            },
+            autoModeReview: () => (autoModeDecider !== undefined ? { decider: autoModeDecider } : undefined),
+            workflowDepth: internals?.workflowDepth,
+            parentCwd: taskRootFinal,
+            parentThinking: () => harnessRef.current?.getThinkingLevel() ?? thinking,
+            parentReadFace: () => carrierReadFace(),
+            parentReadDenyPatterns: () => {
+                const readDenyAdditionsNormalized = input.readDenyAdditionsNormalized();
+                return readDenyAdditionsNormalized.length > 0 ? readDenyAdditionsNormalized : undefined;
+            },
+            ...(spec.handsReadOnly === true ? { parentHandsReadOnly: true } : {}), ...(spec.interactiveTools === false ? { parentInteractiveTools: false } : {}),
+            onNotice: deps.onNotice,
+            parentCheckpointStoreDisabled: spec.checkpointStore === null,
+            parentCenterArtifactDigest: () => input.centerAdoption()?.artifact.artifactDigest,
+            parentCenterSourceRevision: () => input.centerAdoption()?.sourceRevision,
+            ...(forwardEvent ? { forwardEvent } : {}),
+            inheritedGateForChildren,
+        }));
+    }
+    return { tools, blockedRef, runtimeCaps, runtimeCapsFaulted, complianceDenies, complianceDegraded, agentForkDenial, observersActive, autoModeArmReason, autoModeDecider, autoModeDenialTracking, autoModeArming, selfOrchestrationActive, workflowToolsActive, workflowSizeGuideline };
+}

package/dist/core/runner/prepare-config-doors.d.ts

@@ -28,7 +28,7 @@ import { type ResolvedRole } from "../roles.js";
 import type { SessionStore } from "../session.js";
 import type { RunnerDeps, TaskLimits, TaskSpec } from "../types.js";
 import { type UsageWindow } from "../usage-window-store.js";
-import type { PrepareResume, RunInternals } from "./prepare-task.js";
+import type { PrepareResume, RunInternals, ToolFaceSnapshot } from "./contracts.js";
 export declare function limitConfigError(code: string, message: string): Error & {
     code?: string;
 };
@@ -138,15 +138,7 @@ export interface PrepareConfigDoorsResult {
     /** owned — the frozen task-start snapshot of the caller's tool-face control arrays; the ONLY thing
      *  later face reads consult (own-task filter, defer classify, delegation ctx). Frozen-immutable ⇒
      *  shared by reference into tool execution ctxs. */
-    toolFaceSnapshot: {
-        exclude: readonly string[] | undefined;
-        defer: readonly string[] | undefined;
-        alwaysLoad: readonly string[] | undefined;
-        /** design/277 — the model-gate restore selector ({@link TaskSpec.restoreGatedTools}), fourth
-         *  seat of the same frozen task-start snapshot: the gate decision and the delegation carrier
-         *  read THIS, never the live spec. */
-        restoreGated: readonly string[] | true | undefined;
-    };
+    toolFaceSnapshot: ToolFaceSnapshot;
     /** owned — the profile half of the RB-50 single decision point (model-independent by contract). */
     promptProfile: "simple" | "classic";
     /** owned — the administrator lock snapshot; the rest of prepare reads guarded slots through it. */

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

@@ -0,0 +1,119 @@
+/**
+ * design/390 §1.2 M21 — prepareTask's CONTEXT-LANE phase, verbatim from the driver: the edit/guard budgets, the
+ * microCompact machine state with the trigger-window clamp's one loud outlet, the model's chars-per-token coordinate,
+ * and the `context` handler registered on the harness — heal → ledger replay → aggregate tool-result and media caps →
+ * frontier clear → the guard chain (arms A/B/C) → the git-frame guard → the orphan belt → the lossy-projection flag →
+ * the projection seat. The four module-level helpers only this lane called moved with it (the machine-state builder,
+ * the frontier-clear recorder, the observation-buffer flush, the guard chain with its two types). The interface is the
+ * dependency list the segment had implicitly (design/238 R-1).
+ *
+ * SYNCHRONOUS FUNCTION, SYNCHRONOUS CALL: the stretch has no await of its own (the handler it registers is async and
+ * runs per provider request), so the phase adds no yield between the gate stations before it and the turn wiring after
+ * it (design/390 §1.5). Read-stability of the host handles: {@link RunInternals} (`@contract prepare.deps-read-stable`).
+ *
+ * REGISTRATION SIDE EFFECT, OWNED: this phase registers the ONE `context` handler on the harness; the harness owns the
+ * listener for the run's life (it is never unregistered — the harness is per prepare). No other station registers on
+ * that hook.
+ */
+import { type AgentHarness, type AgentMessage } from "../../internal/harness.js";
+import type { Model } from "../../internal/llm.js";
+import { type ContextEditMachine, type OccurrenceIndex } from "../context-edit.js";
+import { type ToolResultStore } from "../tool-result-store.js";
+import { type RunnerDeps } from "../types.js";
+import type { Prepared, PreparedMicroCompact } from "./contracts.js";
+import { type GitStatusLaneRef } from "./git-status-frame.js";
+export interface PrepareContextLaneInput {
+    /** borrowed-readonly — the task model: the budgets, the trigger-window geometry and `charsPerToken` are read off it. */
+    model: Model;
+    /** borrowed-readonly — the deployment seats, whole: `onNotice` (the clamp outlet, the offload-loss announcement), `tracer`
+     *  (the cap / clear / trim frames), `mediaByteCapBytes` and `onMediaStripped` (the media cap), `onError` (the belt line, the
+     *  git-frame degrade) — the guard chain and the machine-state builder read through the whole record. */
+    deps: RunnerDeps;
+    /** borrowed-readonly — the acquired session id (the offload persist key; every disclosure's attribution). */
+    sessionId: string;
+    /** borrowed-readonly — the run's invocation id (the clamp notice's per-run claim). */
+    runId: string;
+    /** borrowed-readonly — the per-task identity (the trace frames' taskId). */
+    hostTaskId: string;
+    /** borrowed-readonly — the run's offload store, or undefined (the caps' and the machine's persist seat). */
+    offloadStore: ToolResultStore | undefined;
+    /** borrowed-readonly — the doors' RESOLVED microCompact knob (immutable values, never the deps bag). */
+    microCompactKnob: {
+        machine: "off" | ContextEditMachine;
+        clearOnRejection: boolean;
+    };
+    /** borrowed-mutable — the built harness. Writer here: `on("context", …)` — the ONE registration of the request-build
+     *  handler (the harness owns the listener; nothing unregisters it). */
+    harness: AgentHarness;
+    /** borrowed-mutable — the turn's halt fact (`Prepared.batchHaltRef`). Writer here: the handler CLEARS it at every new
+     *  provider request (a new request means the halted boundary was legitimately passed). The judgment site sets it. */
+    batchHaltRef: Prepared["batchHaltRef"];
+    /** borrowed-mutable — the git-status lane ref. Writers here: the git-frame guard's degrade latch (`overBudgetShrunk`) inside
+     *  the handler; the prompt-inputs phase seeds it. */
+    gitStatusRef: GitStatusLaneRef;
+    /** borrowed-mutable — the per-request lossy-projection flag. Writer here: the handler re-derives it at every request
+     *  build; the provider-seam recording shim reads it immediately after. */
+    requestLossyRef: {
+        current: boolean;
+    };
+    /** borrowed-mutable — the trim-pressure flag (`Prepared.trimPressureRef`). Writer here: the guard chain's trim arm sets
+     *  `droppedMessages`; the run loop's boundary reads and clears it. */
+    trimPressureRef: {
+        droppedMessages: boolean;
+    };
+}
+export interface PrepareContextLaneResult {
+    /** owned — the per-run microCompact machine state (`Prepared.microCompact`): machine, MC-R flag, ledger, the projection
+     *  and in-turn-compaction seats the handler and the runtask arms fill. */
+    microCompact: PreparedMicroCompact;
+    /** owned — the model's structural coefficient (`charsPerToken ?? DEFAULT`), the ONE coordinate the request-layer
+     *  defenses here and the prompt-overhead term downstream share with the compaction trigger estimate. */
+    charsPerToken: number;
+}
+/** The M21 phase body — prepareTask's context-lane stretch, verbatim (see the module header). */
+export declare function prepareContextLane(input: PrepareContextLaneInput): PrepareContextLaneResult;
+/** See {@link runGuardChain}. */
+export interface GuardChainArgs {
+    /** The post-frontier view the chain starts from. */
+    edited: AgentMessage[];
+    /** The pre-cap counterpart view (arm A's clearSource — RB-212 durable composition seat). */
+    replayed: AgentMessage[];
+    index: OccurrenceIndex;
+    microCompact: PreparedMicroCompact;
+    guardAt: number;
+    charsPerToken: number;
+    offloadStore: import("../tool-result-store.js").ToolResultStore | undefined;
+    sessionId: string;
+    taskId: string;
+    deps: RunnerDeps;
+    trimPressureRef: {
+        droppedMessages: boolean;
+    };
+    recheck: boolean | undefined;
+    signal: AbortSignal | undefined;
+    /** The r7 per-request observation buffer — the chain DROPS it on its early returns (a discarded
+     *  provisional projection must not narrate itself). */
+    pendingProjectionObservations: Array<() => void>;
+}
+export type GuardChainOutcome = {
+    earlyReturn: {
+        messages: AgentMessage[];
+        adoptSessionRebuild?: boolean;
+    };
+} | {
+    working: AgentMessage[];
+    trimmed: AgentMessage[];
+    trimDroppedMessages: boolean;
+};
+/**
+ * design/374 slice 3 — the GUARD CHAIN over one request build (D-7 case-ii transfer table),
+ * module-level per the design/238 body-span bank. design/123 D3: the chain reads the anchored
+ * coordinate re-estimated on the EDITED array (pre-anchor clears don't lower it — deliberately;
+ * trimToBudget doc). The opt-out machine = the pre-374 backstop order byte-identical
+ * (trim as the ordinary second line); otherwise arm A (blocking machine run, only when the
+ * frontier pass is off) → arm B (in-turn forced compaction behind the adopt seam) → arm C (trim,
+ * the disaster-only last resort and this chain's sole `context.trim` emitter). Returns either the
+ * post-chain view for the pipeline tail, or an EARLY hook result the context handler must return
+ * verbatim (arm-B adoption / the r8 dead-turn stand-down).
+ */
+export declare function runGuardChain(args: GuardChainArgs): Promise<GuardChainOutcome>;