stageflow 0.1.0

package/dist/runstore/stageSnapshot.js

@@ -0,0 +1,46 @@
+import { derivePendingPrompt } from "../hitl/qaTrail.js";
+import { stageStatusFromEvents } from "./port.js";
+import { listArtifactNames } from "./workspaceLayout.js";
+async function tryReadEnvelope(store, runId, stageId, latest) {
+    if (latest?.envelope != null) {
+        return latest.envelope;
+    }
+    try {
+        return await store.readEnvelope(runId, stageId);
+    }
+    catch {
+        return null;
+    }
+}
+export async function buildStageSnapshotFromStore(store, runId, stageId, workspaceDir) {
+    const latest = await store.getLatestStageExecution(runId, stageId);
+    let events;
+    let status;
+    let envelope;
+    let attempt_count;
+    if (latest !== null) {
+        events = await store.listStageEvents(runId, stageId, latest.attempt);
+        status = stageStatusFromEvents(events);
+        envelope = await tryReadEnvelope(store, runId, stageId, latest);
+        attempt_count = await store.countStageAttempts(runId, stageId);
+    }
+    else {
+        events = await store.listStageEvents(runId, stageId);
+        status = stageStatusFromEvents(events);
+        envelope = await tryReadEnvelope(store, runId, stageId, null);
+        attempt_count = 1;
+    }
+    const artifacts = await listArtifactNames(workspaceDir, stageId, latest?.attempt ?? 1);
+    const last_at = events.length > 0 ? events[events.length - 1]?.at : undefined;
+    const pending = derivePendingPrompt(events);
+    return {
+        stage_id: stageId,
+        status,
+        events,
+        envelope,
+        artifacts,
+        last_at,
+        attempt_count,
+        ...(pending ? { pending_prompt: pending } : {}),
+    };
+}

package/dist/runstore/syntheticStageSnapshot.d.ts

@@ -0,0 +1,2 @@
+import type { StageSnapshot } from "./port.js";
+export declare function syntheticPendingSnapshot(stageId: string): StageSnapshot;

package/dist/runstore/syntheticStageSnapshot.js

@@ -0,0 +1,10 @@
+export function syntheticPendingSnapshot(stageId) {
+    return {
+        stage_id: stageId,
+        status: "pending",
+        events: [],
+        envelope: null,
+        artifacts: [],
+        attempt_count: 1,
+    };
+}

package/dist/runstore/trackProjection.d.ts

@@ -0,0 +1,7 @@
+import type { PipelineTrackProjection, RunPipelineDagSnapshot, RunStatus, StageSnapshot } from "./port.js";
+export type BuildPipelineTrackInput = {
+    dagSnapshot: RunPipelineDagSnapshot | null | undefined;
+    stages: StageSnapshot[];
+    runStatus: RunStatus;
+};
+export declare function buildPipelineTrack(input: BuildPipelineTrackInput): PipelineTrackProjection;

package/dist/runstore/trackProjection.js

@@ -0,0 +1,94 @@
+import { linearCompatDagSnapshot } from "./pipelineDagSnapshot.js";
+function stageStarted(stage) {
+    return stage.events.some((e) => e.event === "started" || e.event === "resumed");
+}
+function runHalted(stages) {
+    return stages.some((s) => s.status === "failed");
+}
+function computeLayers(dag) {
+    const layers = new Map();
+    const nodeById = new Map(dag.nodes.map((n) => [n.id, n]));
+    function layerFor(id) {
+        const cached = layers.get(id);
+        if (cached !== undefined)
+            return cached;
+        const node = nodeById.get(id);
+        if (!node?.needs) {
+            layers.set(id, 0);
+            return 0;
+        }
+        const l = layerFor(node.needs) + 1;
+        layers.set(id, l);
+        return l;
+    }
+    for (const id of dag.stage_ids) {
+        layerFor(id);
+    }
+    return layers;
+}
+function deriveReadiness(stage, dag, snapshotsById, halted) {
+    const { status } = stage;
+    if (status === "succeeded")
+        return { readiness: "succeeded" };
+    if (status === "failed")
+        return { readiness: "failed" };
+    if (status === "running")
+        return { readiness: "running" };
+    if (status === "waiting_for_input")
+        return { readiness: "waiting" };
+    if (halted && !stageStarted(stage)) {
+        return { readiness: "skipped" };
+    }
+    const node = dag.nodes.find((n) => n.id === stage.stage_id);
+    const need = node?.needs;
+    if (need) {
+        const predecessor = snapshotsById.get(need);
+        if (!predecessor || predecessor.status !== "succeeded") {
+            return { readiness: "blocked", blocked_by: [need] };
+        }
+    }
+    return { readiness: "ready" };
+}
+export function buildPipelineTrack(input) {
+    const snapshotsById = new Map(input.stages.map((s) => [s.stage_id, s]));
+    const stageIds = input.dagSnapshot?.stage_ids ??
+        input.stages.map((s) => s.stage_id);
+    const dag = input.dagSnapshot ?? linearCompatDagSnapshot(stageIds);
+    const layers = computeLayers(dag);
+    const halted = runHalted(input.stages);
+    const nodes = dag.stage_ids.map((stageId) => {
+        const stage = snapshotsById.get(stageId);
+        if (!stage) {
+            throw new Error(`buildPipelineTrack: missing overlay snapshot for "${stageId}" — call overlayPlannedStages first`);
+        }
+        const node = dag.nodes.find((n) => n.id === stageId);
+        const { readiness, blocked_by } = deriveReadiness(stage, dag, snapshotsById, halted);
+        const trackNode = {
+            stage_id: stageId,
+            status: stage.status,
+            readiness,
+            layer: layers.get(stageId) ?? 0,
+            layer_order: node?.stageIndex ?? dag.stage_ids.indexOf(stageId),
+            attempt_count: stage.attempt_count,
+        };
+        if (blocked_by?.length)
+            trackNode.blocked_by = blocked_by;
+        const gateKinds = dag.gate_kinds?.[stageId];
+        if (gateKinds?.length)
+            trackNode.gate_kinds = gateKinds;
+        return trackNode;
+    });
+    const edges = [];
+    for (const node of dag.nodes) {
+        if (!node.needs)
+            continue;
+        const fromStage = snapshotsById.get(node.needs);
+        const edge = { from: node.needs, to: node.id };
+        if (fromStage?.status === "succeeded" &&
+            fromStage.envelope?.summary) {
+            edge.envelope_summary = fromStage.envelope.summary;
+        }
+        edges.push(edge);
+    }
+    return { nodes, edges };
+}

package/dist/runstore/workspaceLayout.d.ts

@@ -0,0 +1,31 @@
+export { stageDir } from "./paths.js";
+export declare function attemptWorkspaceDir(workspaceDir: string, stageId: string, attempt: number): string;
+export declare function attemptLogPath(workspaceDir: string, stageId: string, attempt: number): string;
+export declare function attemptEnvelopePath(workspaceDir: string, stageId: string, attempt: number): string;
+export declare function attemptArtifactsDir(workspaceDir: string, stageId: string, attempt: number): string;
+export declare function attemptAgentDir(workspaceDir: string, stageId: string, attempt: number): string;
+export declare function attemptSessionPath(workspaceDir: string, stageId: string, attempt: number): string;
+/** @deprecated Use attemptArtifactsDir with an explicit attempt number. */
+export declare function artifactsDir(workspaceDir: string, stageId: string): string;
+/** @deprecated Use attemptAgentDir with an explicit attempt number. */
+export declare function agentDir(workspaceDir: string, stageId: string): string;
+/** @deprecated Use attemptEnvelopePath with an explicit attempt number. */
+export declare function envelopePath(workspaceDir: string, stageId: string): string;
+/** @deprecated Use attemptLogPath with an explicit attempt number. */
+export declare function stageLogPath(workspaceDir: string, stageId: string): string;
+/** @deprecated Use attemptSessionPath with an explicit attempt number. */
+export declare function stageSessionPath(workspaceDir: string, stageId: string): string;
+export declare function isInsideDir(child: string, parent: string): boolean;
+export declare function resolveArtifactTarget(runWorkspaceDir: string, stageId: string, attempt: number, relativePath: string): {
+    absolutePath: string;
+    runRelativePath: string;
+    artifactsDir: string;
+};
+export declare function ensureRealArtifactsDir(runWorkspaceDir: string, artifactsDirectory: string): Promise<{
+    realRun: string;
+    realArtifacts: string;
+}>;
+export declare function resolveContainedParent(realArtifacts: string, relativeToArtifacts: string): Promise<string>;
+/** Legacy stage-root artifacts dir (pre-uniform unbound writes); kept for reads. */
+export declare function stageArtifactsDir(workspaceDir: string, stageId: string): string;
+export declare function listArtifactNames(workspaceDir: string, stageId: string, attempt: number): Promise<string[]>;

package/dist/runstore/workspaceLayout.js

@@ -0,0 +1,172 @@
+import { access, lstat, mkdir, readdir, realpath } from "node:fs/promises";
+import path from "node:path";
+export { stageDir } from "./paths.js";
+function guardStageId(stageId) {
+    if (stageId.includes("..") ||
+        stageId.includes("/") ||
+        stageId.includes("\\")) {
+        throw new Error("stageId must not contain path separators or ..");
+    }
+}
+function guardAttempt(attempt) {
+    if (!Number.isInteger(attempt) || attempt < 1) {
+        throw new Error("attempt must be a positive integer");
+    }
+}
+export function attemptWorkspaceDir(workspaceDir, stageId, attempt) {
+    guardStageId(stageId);
+    guardAttempt(attempt);
+    return path.join(workspaceDir, "stages", stageId, "attempts", String(attempt));
+}
+export function attemptLogPath(workspaceDir, stageId, attempt) {
+    return path.join(attemptWorkspaceDir(workspaceDir, stageId, attempt), "log.jsonl");
+}
+export function attemptEnvelopePath(workspaceDir, stageId, attempt) {
+    return path.join(attemptWorkspaceDir(workspaceDir, stageId, attempt), "envelope.json");
+}
+export function attemptArtifactsDir(workspaceDir, stageId, attempt) {
+    return path.join(attemptWorkspaceDir(workspaceDir, stageId, attempt), "artifacts");
+}
+export function attemptAgentDir(workspaceDir, stageId, attempt) {
+    return path.join(attemptWorkspaceDir(workspaceDir, stageId, attempt), ".pi-agent");
+}
+export function attemptSessionPath(workspaceDir, stageId, attempt) {
+    return path.join(attemptWorkspaceDir(workspaceDir, stageId, attempt), "pi-session.jsonl");
+}
+/** @deprecated Use attemptArtifactsDir with an explicit attempt number. */
+export function artifactsDir(workspaceDir, stageId) {
+    return attemptArtifactsDir(workspaceDir, stageId, 1);
+}
+/** @deprecated Use attemptAgentDir with an explicit attempt number. */
+export function agentDir(workspaceDir, stageId) {
+    return attemptAgentDir(workspaceDir, stageId, 1);
+}
+/** @deprecated Use attemptEnvelopePath with an explicit attempt number. */
+export function envelopePath(workspaceDir, stageId) {
+    return attemptEnvelopePath(workspaceDir, stageId, 1);
+}
+/** @deprecated Use attemptLogPath with an explicit attempt number. */
+export function stageLogPath(workspaceDir, stageId) {
+    return attemptLogPath(workspaceDir, stageId, 1);
+}
+/** @deprecated Use attemptSessionPath with an explicit attempt number. */
+export function stageSessionPath(workspaceDir, stageId) {
+    return attemptSessionPath(workspaceDir, stageId, 1);
+}
+export function isInsideDir(child, parent) {
+    const relative = path.relative(parent, child);
+    return (relative === "" ||
+        (!relative.startsWith(`..${path.sep}`) &&
+            relative !== ".." &&
+            !path.isAbsolute(relative)));
+}
+export function resolveArtifactTarget(runWorkspaceDir, stageId, attempt, relativePath) {
+    guardStageId(stageId);
+    guardAttempt(attempt);
+    if (typeof relativePath !== "string" || relativePath.length === 0) {
+        throw new Error("path must be a non-empty string");
+    }
+    if (path.isAbsolute(relativePath)) {
+        throw new Error("path must be relative to the stage artifacts directory");
+    }
+    const artifacts = path.resolve(attemptArtifactsDir(runWorkspaceDir, stageId, attempt));
+    const resolved = path.resolve(artifacts, relativePath);
+    const relativeToArtifacts = path.relative(artifacts, resolved);
+    if (relativeToArtifacts === "") {
+        throw new Error("path must name a file under the stage artifacts directory");
+    }
+    if (relativeToArtifacts === ".." ||
+        relativeToArtifacts.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(relativeToArtifacts)) {
+        throw new Error("path escapes the stage artifacts directory");
+    }
+    const runRelativePath = path.posix.join("stages", stageId, "attempts", String(attempt), "artifacts", ...relativeToArtifacts.split(path.sep));
+    return {
+        absolutePath: resolved,
+        runRelativePath,
+        artifactsDir: artifacts,
+    };
+}
+export async function ensureRealArtifactsDir(runWorkspaceDir, artifactsDirectory) {
+    await mkdir(artifactsDirectory, { recursive: true });
+    const realRun = await realpath(runWorkspaceDir);
+    const realArtifacts = await realpath(artifactsDirectory);
+    if (!isInsideDir(realArtifacts, realRun)) {
+        throw new Error("path escapes the stage artifacts directory");
+    }
+    return { realRun, realArtifacts };
+}
+export async function resolveContainedParent(realArtifacts, relativeToArtifacts) {
+    const segments = relativeToArtifacts.split(path.sep).filter((s) => s.length > 0);
+    if (segments.length === 0) {
+        throw new Error("path must name a file under the stage artifacts directory");
+    }
+    const dirSegments = segments.slice(0, -1);
+    let current = realArtifacts;
+    for (const segment of dirSegments) {
+        const next = path.join(current, segment);
+        try {
+            const st = await lstat(next);
+            if (st.isSymbolicLink()) {
+                throw new Error("path escapes the stage artifacts directory");
+            }
+            if (!st.isDirectory()) {
+                throw new Error("path escapes the stage artifacts directory");
+            }
+            current = await realpath(next);
+        }
+        catch (err) {
+            if (err.code !== "ENOENT") {
+                throw err;
+            }
+            await mkdir(next);
+            current = next;
+        }
+        if (!isInsideDir(current, realArtifacts)) {
+            throw new Error("path escapes the stage artifacts directory");
+        }
+    }
+    return current;
+}
+async function fileExists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function walkArtifactFiles(dir, runRelativePrefix, relativeParts, out) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const nextParts = [...relativeParts, entry.name];
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            await walkArtifactFiles(full, runRelativePrefix, nextParts, out);
+        }
+        else if (entry.isFile()) {
+            out.push(path.posix.join(...runRelativePrefix, ...nextParts));
+        }
+    }
+}
+/** Legacy stage-root artifacts dir (pre-uniform unbound writes); kept for reads. */
+export function stageArtifactsDir(workspaceDir, stageId) {
+    guardStageId(stageId);
+    return path.join(workspaceDir, "stages", stageId, "artifacts");
+}
+export async function listArtifactNames(workspaceDir, stageId, attempt) {
+    guardStageId(stageId);
+    guardAttempt(attempt);
+    const out = [];
+    const attemptDir = attemptArtifactsDir(workspaceDir, stageId, attempt);
+    if (await fileExists(attemptDir)) {
+        await walkArtifactFiles(attemptDir, ["stages", stageId, "attempts", String(attempt), "artifacts"], [], out);
+    }
+    const stageDirPath = stageArtifactsDir(workspaceDir, stageId);
+    if (await fileExists(stageDirPath)) {
+        await walkArtifactFiles(stageDirPath, ["stages", stageId, "artifacts"], [], out);
+    }
+    out.sort();
+    return out;
+}

package/dist/runtime/answerResume.d.ts

@@ -0,0 +1,16 @@
+import type { StageExecutionMode } from "./stageConcurrency.js";
+import type { DeliverAnswerResult } from "./stageHitl.js";
+export declare const WAIT_WITHOUT_WORKER_DISPATCH = "stage entered wait without worker dispatch";
+export type AnswerResumeAdapterResult = {
+    ok: boolean;
+    reason?: string;
+};
+export declare function orchestrateAnswerResume(options: {
+    prefixMode: "live" | "restart";
+    executionMode: StageExecutionMode;
+    insertedForResume: boolean;
+    removeInsertedResume: () => void;
+    registerResumeUntrack: (done: Promise<AnswerResumeAdapterResult>) => void;
+    resumeViaSubprocess: () => Promise<AnswerResumeAdapterResult>;
+    reconstructAndContinue: () => Promise<AnswerResumeAdapterResult>;
+}): Promise<DeliverAnswerResult>;

package/dist/runtime/answerResume.js

@@ -0,0 +1,22 @@
+export const WAIT_WITHOUT_WORKER_DISPATCH = "stage entered wait without worker dispatch";
+export async function orchestrateAnswerResume(options) {
+    if (options.prefixMode === "live" && options.executionMode !== "process") {
+        if (options.insertedForResume) {
+            options.removeInsertedResume();
+        }
+        return { ok: true };
+    }
+    const done = options.executionMode === "process"
+        ? options.resumeViaSubprocess()
+        : options.reconstructAndContinue();
+    options.registerResumeUntrack(done);
+    const outcome = await done;
+    if (!outcome.ok) {
+        return {
+            ok: false,
+            reason: outcome.reason ?? "resume failed",
+            status: 500,
+        };
+    }
+    return { ok: true };
+}

package/dist/runtime/credentialBinding.d.ts

@@ -0,0 +1,16 @@
+import { parseCredentialSource, readCredentialSourceFromFile, writeCredentialSourceToFile, type CredentialSource } from "./settingsFile.js";
+export { parseCredentialSource, readCredentialSourceFromFile, writeCredentialSourceToFile, };
+export type CredentialBinding = {
+    source: CredentialSource;
+    authPath: string;
+    provisional: boolean;
+};
+export type ResolveCredentialBindingOptions = {
+    piHomeAuthPath?: string;
+};
+export declare function sfOwnedAgentDir(cwd: string): string;
+export declare function sfOwnedAuthPath(cwd: string): string;
+export declare function piHomeAuthPath(override?: string): string;
+export declare function isUsableAuthFile(authPath: string): boolean;
+export declare function ensureSfOwnedAuthStore(cwd: string): string;
+export declare function resolveCredentialBinding(cwd: string, options?: ResolveCredentialBindingOptions): CredentialBinding;

package/dist/runtime/credentialBinding.js

@@ -0,0 +1,80 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { storeRootFor } from "../runstore/paths.js";
+import { parseCredentialSource, readCredentialSourceFromFile, writeCredentialSourceToFile, } from "./settingsFile.js";
+export { parseCredentialSource, readCredentialSourceFromFile, writeCredentialSourceToFile, };
+export function sfOwnedAgentDir(cwd) {
+    return path.join(storeRootFor(cwd), "agent");
+}
+export function sfOwnedAuthPath(cwd) {
+    return path.join(sfOwnedAgentDir(cwd), "auth.json");
+}
+export function piHomeAuthPath(override) {
+    return (override ??
+        path.join(os.homedir(), ".pi", "agent", "auth.json"));
+}
+export function isUsableAuthFile(authPath) {
+    if (!existsSync(authPath))
+        return false;
+    try {
+        const content = readFileSync(authPath, "utf8").trim();
+        return content !== "" && content !== "{}";
+    }
+    catch {
+        return false;
+    }
+}
+export function ensureSfOwnedAuthStore(cwd) {
+    const storeRoot = storeRootFor(cwd);
+    mkdirSync(storeRoot, { recursive: true });
+    const agentDir = sfOwnedAgentDir(cwd);
+    mkdirSync(agentDir, { recursive: true });
+    try {
+        chmodSync(agentDir, 0o700);
+    }
+    catch {
+        // best-effort on non-POSIX
+    }
+    const authPath = sfOwnedAuthPath(cwd);
+    if (!existsSync(authPath)) {
+        writeFileSync(authPath, "{}\n", { encoding: "utf8", mode: 0o600 });
+    }
+    try {
+        chmodSync(authPath, 0o600);
+    }
+    catch {
+        // best-effort on non-POSIX
+    }
+    return authPath;
+}
+export function resolveCredentialBinding(cwd, options = {}) {
+    const piHome = piHomeAuthPath(options.piHomeAuthPath);
+    const persisted = readCredentialSourceFromFile(cwd);
+    if (persisted !== undefined) {
+        if (persisted === "sf_owned") {
+            return {
+                source: "sf_owned",
+                authPath: ensureSfOwnedAuthStore(cwd),
+                provisional: false,
+            };
+        }
+        return {
+            source: "pi_home",
+            authPath: piHome,
+            provisional: false,
+        };
+    }
+    if (isUsableAuthFile(piHome)) {
+        return {
+            source: "pi_home",
+            authPath: piHome,
+            provisional: true,
+        };
+    }
+    return {
+        source: "sf_owned",
+        authPath: ensureSfOwnedAuthStore(cwd),
+        provisional: true,
+    };
+}

package/dist/runtime/dagTraversal.d.ts

@@ -0,0 +1,3 @@
+import type { ResolvedPipelineDag } from "../types/pipeline.js";
+export declare function collectDownstreamStageIds(dag: ResolvedPipelineDag, rootId: string): Set<string>;
+export declare function collectDownstreamClosure(dag: ResolvedPipelineDag, rootIds: string[]): Set<string>;

package/dist/runtime/dagTraversal.js

@@ -0,0 +1,26 @@
+export function collectDownstreamStageIds(dag, rootId) {
+    const downstream = new Set();
+    const queue = [...(dag.childrenOf[rootId] ?? [])];
+    while (queue.length > 0) {
+        const id = queue.shift();
+        if (downstream.has(id))
+            continue;
+        downstream.add(id);
+        const children = dag.childrenOf[id];
+        if (children) {
+            for (const child of children) {
+                queue.push(child);
+            }
+        }
+    }
+    return downstream;
+}
+export function collectDownstreamClosure(dag, rootIds) {
+    const downstream = new Set();
+    for (const rootId of rootIds) {
+        for (const id of collectDownstreamStageIds(dag, rootId)) {
+            downstream.add(id);
+        }
+    }
+    return downstream;
+}

package/dist/runtime/envelopeRouting.d.ts

@@ -0,0 +1,20 @@
+import type { RunStore, StageSnapshot } from "../runstore/port.js";
+import type { StageEnvelope } from "../types/envelope.js";
+import type { LoadedPipeline, ResolvedPipelineDag } from "../types/pipeline.js";
+import type { StageConfig } from "../types/stage.js";
+export declare function buildCompletedEnvelopesFromRun(store: RunStore, runId: string, stages?: StageSnapshot[]): Promise<Map<string, StageEnvelope>>;
+export declare function buildStageConfigById(loaded: LoadedPipeline): Map<string, StageConfig>;
+export type ResolvePriorEnvelopeResult = {
+    ok: true;
+    prior: StageEnvelope | null;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function resolvePriorEnvelope(options: {
+    dag: ResolvedPipelineDag;
+    stageId: string;
+    completedEnvelopes: Map<string, StageEnvelope>;
+    store?: RunStore;
+    runId?: string;
+}): Promise<ResolvePriorEnvelopeResult>;

package/dist/runtime/envelopeRouting.js

@@ -0,0 +1,59 @@
+export async function buildCompletedEnvelopesFromRun(store, runId, stages) {
+    const completedEnvelopes = new Map();
+    const snapshotStages = stages ?? (await store.readRun(runId)).stages;
+    for (const snap of snapshotStages) {
+        if (snap.status !== "succeeded")
+            continue;
+        try {
+            const envelope = snap.envelope ?? (await store.readEnvelope(runId, snap.stage_id));
+            completedEnvelopes.set(snap.stage_id, envelope);
+        }
+        catch {
+            // envelope may be missing for corrupt runs; leave map empty
+        }
+    }
+    return completedEnvelopes;
+}
+export function buildStageConfigById(loaded) {
+    const map = new Map();
+    for (const stage of loaded.stages) {
+        map.set(stage.id, stage);
+    }
+    return map;
+}
+function dagNode(dag, stageId) {
+    return dag.nodes.find((node) => node.id === stageId);
+}
+export async function resolvePriorEnvelope(options) {
+    const node = dagNode(options.dag, options.stageId);
+    if (!node) {
+        return {
+            ok: false,
+            reason: `stage "${options.stageId}" not in pipeline DAG`,
+        };
+    }
+    if (node.needs === null) {
+        return { ok: true, prior: null };
+    }
+    const parentId = node.needs;
+    const fromMap = options.completedEnvelopes.get(parentId);
+    if (fromMap !== undefined) {
+        return { ok: true, prior: structuredClone(fromMap) };
+    }
+    if (options.store !== undefined && options.runId !== undefined) {
+        try {
+            const envelope = await options.store.readEnvelope(options.runId, parentId);
+            return { ok: true, prior: structuredClone(envelope) };
+        }
+        catch {
+            return {
+                ok: false,
+                reason: `missing envelope for upstream stage "${parentId}"`,
+            };
+        }
+    }
+    return {
+        ok: false,
+        reason: `missing envelope for upstream stage "${parentId}"`,
+    };
+}

package/dist/runtime/hitlSeams.d.ts

@@ -0,0 +1,38 @@
+import type { OpaqueAnswer, OpaqueWaitRequest } from "../agent/port.js";
+/** Context for T2 answer/prompt matching (T2 owns kind schema later). */
+export type AnswerPromptAssertContext = {
+    runId: string;
+    stageId: string;
+    answer: OpaqueAnswer;
+    pendingRequest?: OpaqueWaitRequest;
+};
+/**
+ * T2 pre-append gate. Stub accepts any opaque until ask-operator lands.
+ * Call at deliverAnswer entry before any append or inject (KTD6 / KTD9).
+ */
+export type AssertAnswerMatchesPrompt = (ctx: AnswerPromptAssertContext) => void | Promise<void>;
+export type HitlWaitEnterContext = {
+    runId: string;
+    stageId: string;
+    request: OpaqueWaitRequest;
+};
+export type HitlAnswerDeliverContext = {
+    runId: string;
+    stageId: string;
+    answer: OpaqueAnswer;
+    pendingRequest?: OpaqueWaitRequest;
+};
+/**
+ * T3 ordered hooks. No-op until durable Q&A owns operator_prompt / operator_answer.
+ * T1 must not define event bodies here (KTD9).
+ */
+export type HitlQaHooks = {
+    onWaitEnter?: (ctx: HitlWaitEnterContext) => void | Promise<void>;
+    onAnswerDeliver?: (ctx: HitlAnswerDeliverContext) => void | Promise<void>;
+};
+export declare const noopAssertAnswerMatchesPrompt: AssertAnswerMatchesPrompt;
+export declare const noopHitlQaHooks: HitlQaHooks;
+export type HitlSeams = {
+    assertAnswerMatchesPrompt?: AssertAnswerMatchesPrompt;
+    qaHooks?: HitlQaHooks;
+};

package/dist/runtime/hitlSeams.js

@@ -0,0 +1,2 @@
+export const noopAssertAnswerMatchesPrompt = () => { };
+export const noopHitlQaHooks = {};