@indigoai-us/hq-cli 5.345.56 → 5.345.58

package/dist/lib/lanes/loop.js

@@ -0,0 +1,743 @@
+/** Durable envelope queue and runtime primitives for conduct worker lanes. */
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { providerSupportsSessionResume } from "./delivery.js";
+export const LOOP_SCHEMA = "hq-lane-loop.v1";
+export const PHASE_ENVELOPE_SCHEMA = "hq-phase-envelope/v1";
+export const PHASE_HANDOFF_SCHEMA = "hq-phase-handoff/v1";
+export const LOOP_ENVELOPE_LIMIT = 1024 * 1024;
+export function loopAdmissionPath(state, hasPendingResume, initialAdmission) {
+    if (initialAdmission)
+        return "initial";
+    if (state === "queued" && hasPendingResume)
+        return "deferred";
+    return "resume";
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function nonEmpty(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function validateDeadline(envelope) {
+    if (envelope.deadline_seconds !== undefined &&
+        (typeof envelope.deadline_seconds !== "number" || !Number.isFinite(envelope.deadline_seconds) || envelope.deadline_seconds <= 0)) {
+        throw new Error("deadline_seconds must be a positive finite number");
+    }
+    if (envelope.deadline !== undefined &&
+        (typeof envelope.deadline !== "string" || !Number.isFinite(Date.parse(envelope.deadline)))) {
+        throw new Error("deadline must be an ISO date-time");
+    }
+}
+/** Validate both hq-cli phase envelopes and the conduct protocol §8 shape. */
+export function validateLoopEnvelope(value) {
+    if (!isRecord(value))
+        throw new Error("envelope must be a JSON object");
+    if (value.kind === "stop")
+        return value;
+    if (value.schema === PHASE_ENVELOPE_SCHEMA) {
+        if (!nonEmpty(value.story_id) || !nonEmpty(value.phase) || !nonEmpty(value.worker_id) || !nonEmpty(value.worktree)) {
+            throw new Error("hq-phase-envelope/v1 requires story_id, phase, worker_id, and worktree");
+        }
+        if (!path.isAbsolute(value.worktree))
+            throw new Error("worktree must be an absolute path");
+        if (!(value.incoming_handoff === null || nonEmpty(value.incoming_handoff)))
+            throw new Error("incoming_handoff must be a path or null");
+        if (!Array.isArray(value.acceptance_criteria) || !value.acceptance_criteria.every((item) => typeof item === "string"))
+            throw new Error("acceptance_criteria must be an array of strings");
+        if (typeof value.fresh_call !== "boolean")
+            throw new Error("fresh_call must be a boolean");
+        if (value.engine !== undefined && !["claude", "codex", "grok"].includes(String(value.engine))) {
+            throw new Error("engine must be claude, codex, or grok");
+        }
+        if (value.result_path !== undefined && !nonEmpty(value.result_path))
+            throw new Error("result_path must be a non-empty path");
+        validateDeadline(value);
+        return value;
+    }
+    if (value.kind !== "phase")
+        throw new Error('envelope kind must be "phase" or "stop"');
+    if (!nonEmpty(value.prompt))
+        throw new Error("phase envelope requires a non-empty prompt");
+    if (value.engine !== undefined && !["claude", "codex", "grok"].includes(String(value.engine))) {
+        throw new Error("engine must be claude, codex, or grok");
+    }
+    if (value.result_path !== undefined && !nonEmpty(value.result_path))
+        throw new Error("result_path must be a non-empty path");
+    validateDeadline(value);
+    return value;
+}
+export function validateSection8Handoff(value, envelope) {
+    if (!isRecord(value) || value.schema !== PHASE_HANDOFF_SCHEMA)
+        throw new Error("result must use schema hq-phase-handoff/v1");
+    for (const field of ["story_id", "phase", "worker_id"]) {
+        if (!nonEmpty(value[field]))
+            throw new Error(`handoff requires non-empty ${field}`);
+    }
+    for (const field of ["summary", "context_for_next"]) {
+        if (typeof value[field] !== "string")
+            throw new Error(`handoff requires string ${field}`);
+    }
+    if (value.story_id !== envelope.story_id || value.phase !== envelope.phase) {
+        throw new Error("handoff story_id and phase must match the queued phase envelope");
+    }
+    if (!(value.status === "passed" || value.status === "failed" || value.status === "blocked")) {
+        throw new Error("handoff status must be passed, failed, or blocked");
+    }
+    if (!Array.isArray(value.files_changed) || !value.files_changed.every((item) => typeof item === "string"))
+        throw new Error("handoff files_changed must be an array of strings");
+    if (!Array.isArray(value.commits) || !value.commits.every((item) => typeof item === "string"))
+        throw new Error("handoff commits must be an array of strings");
+    if (!isRecord(value.back_pressure))
+        throw new Error("handoff back_pressure must be an object");
+    for (const gate of ["tests", "lint", "typecheck", "build"]) {
+        if (!(value.back_pressure[gate] === "pass" || value.back_pressure[gate] === "fail" || value.back_pressure[gate] === "skip")) {
+            throw new Error(`handoff back_pressure.${gate} must be pass, fail, or skip`);
+        }
+    }
+    return value;
+}
+function atomicJson(file, value) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        fs.writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { flag: "wx", mode: 0o600 });
+        fs.renameSync(temporary, file);
+    }
+    catch (error) {
+        try {
+            fs.unlinkSync(temporary);
+        }
+        catch (cleanupError) {
+            if (cleanupError.code !== "ENOENT") {
+                throw new AggregateError([error, cleanupError], "Could not clean up an atomic JSON write");
+            }
+        }
+        throw error;
+    }
+}
+function readJson(file) {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+function pendingDir(runDir) { return path.join(runDir, "loop", "pending"); }
+function activeDir(runDir) { return path.join(runDir, "loop", "active"); }
+function claimedDir(runDir) { return path.join(runDir, "loop", "claimed"); }
+function resultsDir(runDir) { return path.join(runDir, "loop", "results"); }
+function loopPath(runDir) { return path.join(runDir, "loop", "loop.json"); }
+function sessionsPath(runDir) { return path.join(runDir, "loop", "sessions.json"); }
+function acquireEnqueueLock(runDir) {
+    const root = path.join(runDir, "loop");
+    fs.mkdirSync(root, { recursive: true });
+    const lock = path.join(root, "enqueue.lock");
+    const sequenceFile = path.join(root, "enqueue-sequence.json");
+    const deadline = Date.now() + 5_000;
+    for (;;) {
+        try {
+            fs.mkdirSync(lock);
+            break;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            try {
+                if (Date.now() - fs.statSync(lock).mtimeMs > 30_000) {
+                    // Rename is the ownership claim: only one stale-lock contender can
+                    // move this directory. A plain rm followed by mkdir lets two
+                    // contenders both believe they reclaimed it.
+                    const stale = `${lock}.stale-${process.pid}-${randomUUID()}`;
+                    try {
+                        fs.renameSync(lock, stale);
+                        fs.rmSync(stale, { recursive: true, force: true });
+                    }
+                    catch (renameError) {
+                        if (renameError.code !== "ENOENT")
+                            throw renameError;
+                    }
+                }
+            }
+            catch (statError) {
+                if (statError.code !== "ENOENT")
+                    throw statError;
+            }
+            if (Date.now() >= deadline)
+                throw new Error("Timed out acquiring the loop enqueue lock");
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
+        }
+    }
+    return () => fs.rmSync(lock, { recursive: true, force: true });
+}
+function nextQueueSequence(runDir) {
+    const root = path.join(runDir, "loop");
+    const sequenceFile = path.join(root, "enqueue-sequence.json");
+    let sequence = 0;
+    try {
+        const prior = readJson(sequenceFile);
+        if (isRecord(prior) && Number.isSafeInteger(prior.sequence) && Number(prior.sequence) >= 0)
+            sequence = Number(prior.sequence);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT" && !(error instanceof SyntaxError))
+            throw error;
+    }
+    sequence += 1;
+    atomicJson(sequenceFile, { sequence });
+    return sequence;
+}
+function acquireRunnerLease(runDir) {
+    const lock = path.join(runDir, "loop", "runner.lock");
+    fs.mkdirSync(path.dirname(lock), { recursive: true });
+    try {
+        fs.mkdirSync(lock);
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+        let pid;
+        try {
+            const owner = readJson(path.join(lock, "owner.json"));
+            if (isRecord(owner) && typeof owner.pid === "number")
+                pid = owner.pid;
+        }
+        catch (readError) {
+            if (readError.code !== "ENOENT" && !(readError instanceof SyntaxError))
+                throw readError;
+        }
+        let alive = false;
+        if (pid !== undefined && Number.isSafeInteger(pid) && pid > 0) {
+            try {
+                process.kill(pid, 0);
+                alive = true;
+            }
+            catch (probeError) {
+                alive = probeError.code === "EPERM";
+                if (!alive && probeError.code !== "ESRCH")
+                    throw probeError;
+            }
+        }
+        const age = Date.now() - fs.statSync(lock).mtimeMs;
+        if (alive || age <= 60_000)
+            throw new Error(`Loop runner is already active${pid ? ` (pid ${pid})` : ""}`);
+        const stale = `${lock}.stale-${process.pid}-${randomUUID()}`;
+        try {
+            fs.renameSync(lock, stale);
+        }
+        catch (renameError) {
+            if (renameError.code === "ENOENT") {
+                throw new Error("Loop runner lease changed while reclaiming it");
+            }
+            throw renameError;
+        }
+        fs.rmSync(stale, { recursive: true, force: true });
+        try {
+            fs.mkdirSync(lock);
+        }
+        catch (mkdirError) {
+            if (mkdirError.code === "EEXIST") {
+                throw new Error("Loop runner lease was claimed by another controller");
+            }
+            throw mkdirError;
+        }
+    }
+    const ownerFile = path.join(lock, "owner.json");
+    let released = false;
+    const release = () => {
+        if (released)
+            return;
+        released = true;
+        clearInterval(heartbeat);
+        try {
+            fs.rmSync(lock, { recursive: true, force: true });
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    };
+    const heartbeat = setInterval(() => {
+        try {
+            atomicJson(ownerFile, { pid: process.pid, heartbeat_at: new Date().toISOString() });
+        }
+        catch (error) {
+            process.stderr.write(`hq lanes: loop lease heartbeat failed: ${error instanceof Error ? error.message : String(error)}\n`);
+        }
+    }, 15_000);
+    atomicJson(ownerFile, { pid: process.pid, heartbeat_at: new Date().toISOString() });
+    process.once("exit", release);
+    fs.mkdirSync(pendingDir(runDir), { recursive: true });
+    for (const active of envelopeFiles(activeDir(runDir))) {
+        const recovered = path.join(pendingDir(runDir), `0000000000000-recovered-${path.basename(active)}`);
+        try {
+            fs.renameSync(active, recovered);
+        }
+        catch (recoveryError) {
+            if (recoveryError.code !== "ENOENT") {
+                release();
+                throw recoveryError;
+            }
+        }
+    }
+    return release;
+}
+function envelopeFiles(dir) {
+    try {
+        return fs.readdirSync(dir).filter((name) => !name.startsWith(".")).sort()
+            .map((name) => path.join(dir, name));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+}
+function fileEnvelope(file) {
+    const value = readJson(file);
+    if (!isRecord(value) || value.schema_version !== LOOP_SCHEMA || !nonEmpty(value.envelope_id) || !nonEmpty(value.queued_at)) {
+        throw new Error(`Invalid queued loop envelope record: ${file}`);
+    }
+    return { ...value, envelope: validateLoopEnvelope(value.envelope) };
+}
+/** Queue depth and FIFO ordering are based on the timestamp-prefixed filename. */
+export function listLoopQueue(runDir) {
+    return envelopeFiles(pendingDir(runDir)).map(fileEnvelope);
+}
+/**
+ * Copy and enqueue atomically. Unique timestamp/ULID-like names establish FIFO;
+ * temporary files are ignored by claimers until rename completes.
+ */
+export function enqueueLoopEnvelope(input) {
+    const envelope = validateLoopEnvelope(input.envelope);
+    const serialized = JSON.stringify(envelope);
+    if (Buffer.byteLength(serialized, "utf8") > LOOP_ENVELOPE_LIMIT)
+        throw new Error("envelope exceeds the 1 MiB limit");
+    const now = (input.now ?? (() => new Date()))();
+    const queuedAt = now.toISOString();
+    const envelopeId = nonEmpty(envelope.id)
+        ? String(envelope.id)
+        : randomUUID();
+    const dir = pendingDir(input.runDir);
+    fs.mkdirSync(dir, { recursive: true });
+    const release = acquireEnqueueLock(input.runDir);
+    try {
+        const records = [pendingDir(input.runDir), activeDir(input.runDir), claimedDir(input.runDir), path.join(input.runDir, "loop", "stalled"), path.join(input.runDir, "loop", "withdrawn")]
+            .flatMap(envelopeFiles)
+            .map((file) => {
+            try {
+                return fileEnvelope(file);
+            }
+            catch (error) {
+                process.stderr.write(`hq lanes: ignored unreadable loop record ${file}: ${error instanceof Error ? error.message : String(error)}\n`);
+                return undefined;
+            }
+        })
+            .filter((record) => record !== undefined);
+        if (records.some((record) => record.envelope_id === envelopeId) || fs.existsSync(path.join(resultsDir(input.runDir), resultName(envelopeId)))) {
+            throw new Error(`envelope id ${envelopeId} was already used in this loop lane`);
+        }
+        const incomingStop = envelope.kind === "stop";
+        if (records.some((record) => record.envelope.kind === "stop")) {
+            throw new Error(incomingStop ? "a stop envelope is already queued or active" : "cannot enqueue a phase after a stop envelope");
+        }
+        const sequence = nextQueueSequence(input.runDir);
+        const prefix = `${String(sequence).padStart(16, "0")}-${String(now.getTime()).padStart(13, "0")}-${randomUUID()}`;
+        const destination = path.join(dir, `${prefix}-${envelopeId.replace(/[^A-Za-z0-9._-]/g, "_")}.json`);
+        const temporary = `${destination}.${process.pid}.tmp`;
+        const record = { schema_version: LOOP_SCHEMA, envelope_id: envelopeId, queued_at: queuedAt, envelope };
+        try {
+            fs.writeFileSync(temporary, `${JSON.stringify(record)}\n`, { flag: "wx", mode: 0o600 });
+            fs.renameSync(temporary, destination);
+        }
+        catch (error) {
+            try {
+                fs.unlinkSync(temporary);
+            }
+            catch (cleanupError) {
+                if (cleanupError.code !== "ENOENT") {
+                    throw new AggregateError([error, cleanupError], "Could not clean up an enqueued envelope");
+                }
+            }
+            throw error;
+        }
+        const position = envelopeFiles(dir).indexOf(destination) + 1;
+        return { lane_id: input.laneId, envelope_id: envelopeId, position, queue_depth: envelopeFiles(dir).length, queued_at: queuedAt };
+    }
+    finally {
+        release();
+    }
+}
+/** Atomically claims exactly the FIFO head. The active rename is the claim. */
+export function claimNextLoopEnvelope(runDir) {
+    fs.mkdirSync(activeDir(runDir), { recursive: true });
+    fs.mkdirSync(claimedDir(runDir), { recursive: true });
+    for (const pending of envelopeFiles(pendingDir(runDir))) {
+        const active = path.join(activeDir(runDir), path.basename(pending));
+        try {
+            fs.renameSync(pending, active);
+            return { file: active, record: fileEnvelope(active) };
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === "ENOENT" || code === "EEXIST")
+                continue;
+            throw error;
+        }
+    }
+    return null;
+}
+function resultName(id) { return `${id.replace(/[^A-Za-z0-9._-]/g, "_")}.json`; }
+/** Withdraw all unclaimed envelopes; active work remains claimed by the worker. */
+export function interruptLoopQueue(runDir) {
+    const withdrawn = [];
+    const alreadyPickedUp = envelopeFiles(activeDir(runDir)).map((file) => fileEnvelope(file).envelope_id);
+    const withdrawnDir = path.join(runDir, "loop", "withdrawn");
+    fs.mkdirSync(withdrawnDir, { recursive: true });
+    for (const file of envelopeFiles(pendingDir(runDir))) {
+        const record = fileEnvelope(file);
+        try {
+            fs.renameSync(file, path.join(withdrawnDir, path.basename(file)));
+            withdrawn.push(record.envelope_id);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            alreadyPickedUp.push(record.envelope_id);
+        }
+    }
+    return { withdrawn, already_picked_up: alreadyPickedUp };
+}
+export function loopStatus(runDir, laneId) {
+    const loop = fs.existsSync(loopPath(runDir)) && isRecord(readJson(loopPath(runDir))) ? readJson(loopPath(runDir)) : {};
+    const active = envelopeFiles(activeDir(runDir)).map(fileEnvelope)[0];
+    const queueDepth = envelopeFiles(pendingDir(runDir)).length;
+    const stallCounts = isRecord(loop.stall_counts)
+        ? Object.fromEntries(Object.entries(loop.stall_counts).filter((entry) => typeof entry[1] === "number"))
+        : {};
+    const processState = loop.state === "running" || loop.state === "parked" || loop.state === "stopped" || loop.state === "failed" ? loop.state : "waiting";
+    return {
+        mode: "loop", lane_id: laneId, state: processState, queue_depth: queueDepth,
+        active_envelope_id: active?.envelope_id ?? null,
+        active_phase: active ? phaseName(active.envelope, active.envelope_id) : null,
+        stall_counts: stallCounts,
+        ...(typeof loop.pid === "number" ? { pid: loop.pid } : {}),
+        updated_at: typeof loop.updated_at === "string" ? loop.updated_at : new Date(0).toISOString(),
+    };
+}
+export function setLoopControllerPid(runDir, laneId, pid) {
+    persistStatus(runDir, laneId, { pid });
+}
+export function clearLoopControllerPid(runDir, laneId, pid) {
+    let currentPid;
+    try {
+        const status = readJson(loopPath(runDir));
+        if (isRecord(status))
+            currentPid = status.pid;
+    }
+    catch (error) {
+        if (error.code !== "ENOENT" && !(error instanceof SyntaxError))
+            throw error;
+    }
+    if (currentPid === pid)
+        persistStatus(runDir, laneId, { pid: undefined });
+}
+export function loopControllerIsAlive(runDir) {
+    let pid;
+    try {
+        const status = readJson(loopPath(runDir));
+        if (isRecord(status))
+            pid = status.pid;
+    }
+    catch (error) {
+        if (error.code !== "ENOENT" && !(error instanceof SyntaxError))
+            throw error;
+    }
+    if (typeof pid !== "number") {
+        try {
+            const owner = readJson(path.join(runDir, "loop", "runner.lock", "owner.json"));
+            if (isRecord(owner))
+                pid = owner.pid;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT" && !(error instanceof SyntaxError))
+                throw error;
+        }
+    }
+    if (typeof pid !== "number" || !Number.isSafeInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "EPERM")
+            return true;
+        if (error.code === "ESRCH")
+            return false;
+        throw error;
+    }
+}
+function phaseName(envelope, fallback) {
+    const value = envelope;
+    return String(value.phase ?? value.label ?? value.id ?? fallback);
+}
+function envelopeStory(envelope) {
+    const value = envelope;
+    return String(value.story_id ?? "");
+}
+function envelopeProvider(envelope, fallback) {
+    const provider = envelope.engine;
+    return provider === "claude" || provider === "codex" || provider === "grok" ? provider : fallback;
+}
+function phaseDeadlineBudget(envelope, defaultSeconds) {
+    const value = envelope;
+    if (typeof value.deadline_seconds === "number")
+        return value.deadline_seconds;
+    const configured = Number(process.env.HQ_LANE_LOOP_PHASE_DEADLINE_SECS);
+    return Number.isFinite(configured) && configured > 0 ? configured : defaultSeconds;
+}
+function persistStatus(runDir, laneId, patch) {
+    let current = {};
+    try {
+        const value = readJson(loopPath(runDir));
+        if (isRecord(value))
+            current = value;
+    }
+    catch (error) {
+        if (error.code !== "ENOENT" && !(error instanceof SyntaxError))
+            throw error;
+    }
+    atomicJson(loopPath(runDir), {
+        ...current, ...patch, schema_version: LOOP_SCHEMA, mode: "loop", lane_id: laneId,
+        updated_at: new Date().toISOString(),
+    });
+}
+function abortAfter(ms, parent) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new Error("phase deadline exceeded")), Math.min(Math.max(ms, 1), 2_147_483_647));
+    const onAbort = () => controller.abort(parent?.reason);
+    parent?.addEventListener("abort", onAbort, { once: true });
+    return { signal: controller.signal, clear: () => { clearTimeout(timer); parent?.removeEventListener("abort", onAbort); } };
+}
+/** Run queued phases serially. Sessions are isolated by story and provider. */
+export async function runLoopLane(options) {
+    const now = options.now ?? (() => new Date());
+    const defaultDeadlineSeconds = options.defaultDeadlineSeconds ?? 3600;
+    const sessions = new Map();
+    try {
+        const storedSessions = readJson(sessionsPath(options.runDir));
+        if (isRecord(storedSessions)) {
+            for (const [key, sessionId] of Object.entries(storedSessions)) {
+                if (typeof sessionId === "string" && sessionId.trim())
+                    sessions.set(key, sessionId);
+            }
+        }
+    }
+    catch (error) {
+        if (error.code !== "ENOENT" && !(error instanceof SyntaxError))
+            throw error;
+    }
+    const firstDeadline = new Map();
+    const stalls = new Map();
+    let completed = 0;
+    fs.mkdirSync(options.runDir, { recursive: true });
+    const releaseRunner = acquireRunnerLease(options.runDir);
+    persistStatus(options.runDir, options.lane.lane_id, { pid: process.pid });
+    try {
+        const previous = readJson(loopPath(options.runDir));
+        if (isRecord(previous) && isRecord(previous.stall_counts)) {
+            for (const [id, count] of Object.entries(previous.stall_counts)) {
+                if (typeof count === "number" && Number.isSafeInteger(count) && count > 0)
+                    stalls.set(id, count);
+            }
+        }
+    }
+    catch (error) {
+        if (error.code !== "ENOENT" && !(error instanceof SyntaxError))
+            throw error;
+    }
+    persistStatus(options.runDir, options.lane.lane_id, { state: "waiting", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: null, active_phase: null, stall_counts: {} });
+    while (!options.signal?.aborted) {
+        const claimed = claimNextLoopEnvelope(options.runDir);
+        if (!claimed) {
+            await new Promise((resolve) => setTimeout(resolve, options.idlePollMs ?? 200));
+            continue;
+        }
+        const { file, record } = claimed;
+        Object.assign(record, { __active_dir: activeDir(options.runDir) });
+        const envelope = record.envelope;
+        if (envelope.kind === "stop") {
+            const stopped = { schema_version: LOOP_SCHEMA, envelope_id: record.envelope_id, status: "stopped", started_at: record.queued_at, finished_at: now().toISOString() };
+            writeResultAt(options.runDir, file, record, stopped);
+            persistStatus(options.runDir, options.lane.lane_id, { state: "stopped", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: null, active_phase: null, stall_counts: Object.fromEntries(stalls) });
+            releaseRunner();
+            return { state: "stopped", completed };
+        }
+        const provider = envelopeProvider(envelope, options.lane.provider);
+        const story = envelopeStory(envelope);
+        const sessionKey = `${story}\0${provider}`;
+        const fresh = envelope.fresh === true || envelope.fresh_call === true;
+        const previousSession = sessions.get(sessionKey);
+        const startedAt = now().toISOString();
+        const startedAtMs = Date.parse(startedAt);
+        let deadlineAtMs = record.deadline_at_ms;
+        if (deadlineAtMs === undefined) {
+            const absoluteDeadline = envelope.deadline;
+            if (typeof absoluteDeadline === "string")
+                deadlineAtMs = Date.parse(absoluteDeadline);
+            else {
+                const budget = record.deadline_budget_seconds ?? firstDeadline.get(record.envelope_id) ?? phaseDeadlineBudget(envelope, defaultDeadlineSeconds);
+                firstDeadline.set(record.envelope_id, budget);
+                record.deadline_budget_seconds = budget;
+                deadlineAtMs = startedAtMs + budget * 1000;
+            }
+            record.deadline_at_ms = deadlineAtMs;
+        }
+        atomicJson(file, record);
+        persistStatus(options.runDir, options.lane.lane_id, { state: "running", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: record.envelope_id, active_phase: phaseName(envelope, record.envelope_id), stall_counts: Object.fromEntries(stalls) });
+        const timer = abortAfter(deadlineAtMs - startedAtMs, options.signal);
+        try {
+            let result;
+            let fallback = false;
+            try {
+                const resumable = options.canResume?.(provider) ?? providerSupportsSessionResume(provider);
+                result = await options.execute({ lane: options.lane, envelope, envelopeId: record.envelope_id, signal: timer.signal, fresh: fresh || previousSession === undefined || !resumable, ...(fresh || previousSession === undefined || !resumable ? {} : { sessionId: previousSession }) });
+            }
+            catch (error) {
+                const resumable = options.canResume?.(provider) ?? providerSupportsSessionResume(provider);
+                if (!fresh && previousSession && resumable && !timer.signal.aborted) {
+                    fallback = true;
+                    result = await options.execute({ lane: options.lane, envelope, envelopeId: record.envelope_id, signal: timer.signal, fresh: true });
+                }
+                else
+                    throw error;
+            }
+            if (timer.signal.aborted)
+                throw timer.signal.reason;
+            const finishedAt = now().toISOString();
+            const success = {
+                schema_version: LOOP_SCHEMA, envelope_id: record.envelope_id, status: "done", started_at: startedAt, finished_at: finishedAt,
+                output: result.output, ...(result.sessionId ? { session_id: result.sessionId } : {}),
+                ...(previousSession && !fresh && !fallback ? { resumed: true } : { resumed: false }),
+                ...(fallback ? { fresh_fallback: true } : {}),
+            };
+            if (envelope.schema === PHASE_ENVELOPE_SCHEMA) {
+                let handoff;
+                try {
+                    handoff = JSON.parse(result.output);
+                }
+                catch {
+                    throw new Error("section 8 phase result is not valid JSON");
+                }
+                const validated = validateSection8Handoff(handoff, envelope);
+                if (validated.worker_id !== envelope.worker_id) {
+                    throw new Error("handoff worker_id must match the queued phase envelope");
+                }
+            }
+            writeResultAt(options.runDir, file, record, success);
+            if (result.sessionId) {
+                sessions.set(sessionKey, result.sessionId);
+                atomicJson(sessionsPath(options.runDir), Object.fromEntries(sessions));
+            }
+            stalls.delete(record.envelope_id);
+            completed += 1;
+        }
+        catch (error) {
+            if (options.signal?.aborted) {
+                timer.clear();
+                const pending = path.join(pendingDir(options.runDir), path.basename(file));
+                fs.mkdirSync(pendingDir(options.runDir), { recursive: true });
+                fs.renameSync(file, pending);
+                persistStatus(options.runDir, options.lane.lane_id, { state: "waiting", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: null, active_phase: null, stall_counts: Object.fromEntries(stalls) });
+                releaseRunner();
+                return { state: "aborted", completed };
+            }
+            if (!timer.signal.aborted) {
+                const failure = error instanceof Error ? error.message : String(error);
+                writeResultAt(options.runDir, file, record, { schema_version: LOOP_SCHEMA, envelope_id: record.envelope_id, status: "failed", started_at: startedAt, finished_at: now().toISOString(), error: failure });
+                completed += 1;
+                persistStatus(options.runDir, options.lane.lane_id, { state: "waiting", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: null, active_phase: null, stall_counts: Object.fromEntries(stalls) });
+                continue;
+            }
+            const attempt = (stalls.get(record.envelope_id) ?? 0) + 1;
+            stalls.set(record.envelope_id, attempt);
+            persistStatus(options.runDir, options.lane.lane_id, { state: "running", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: record.envelope_id, active_phase: phaseName(envelope, record.envelope_id), stall_counts: Object.fromEntries(stalls) });
+            appendJournal(options.runDir, { event: "phase_stalled", envelope_id: record.envelope_id, phase: phaseName(envelope, record.envelope_id), attempt, at: now().toISOString() });
+            if (attempt === 1) {
+                timer.clear();
+                sessions.delete(sessionKey);
+                atomicJson(sessionsPath(options.runDir), Object.fromEntries(sessions));
+                // Restore the same envelope at the FIFO head. Rename preserves a single claim.
+                const head = path.join(pendingDir(options.runDir), `0000000000000-retry-${path.basename(file)}`);
+                fs.mkdirSync(pendingDir(options.runDir), { recursive: true });
+                fs.renameSync(file, head);
+                persistStatus(options.runDir, options.lane.lane_id, { state: "waiting", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: null, active_phase: null, stall_counts: Object.fromEntries(stalls) });
+                continue;
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            const result = { schema_version: LOOP_SCHEMA, envelope_id: record.envelope_id, status: "stalled", started_at: startedAt, finished_at: now().toISOString(), error: message };
+            writeResultAt(options.runDir, file, record, result);
+            await options.raiseQuestion?.({ envelope, envelopeId: record.envelope_id, attempt, error: message });
+            completed += 1;
+            persistStatus(options.runDir, options.lane.lane_id, { state: "parked", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: null, active_phase: null, stall_counts: Object.fromEntries(stalls) });
+            releaseRunner();
+            return { state: "parked", completed };
+        }
+        finally {
+            timer.clear();
+        }
+        persistStatus(options.runDir, options.lane.lane_id, { state: "waiting", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: null, active_phase: null, stall_counts: Object.fromEntries(stalls) });
+    }
+    releaseRunner();
+    return { state: "aborted", completed };
+}
+function appendJournal(runDir, value) {
+    const file = path.join(runDir, "loop", "stalls.jsonl");
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.appendFileSync(file, `${JSON.stringify(value)}\n`, { mode: 0o600 });
+}
+function writeResultAt(runDir, activeFile, record, result) {
+    const localPath = path.join(resultsDir(runDir), resultName(record.envelope_id));
+    atomicJson(localPath, result);
+    const envelope = record.envelope;
+    const externalPath = envelope.result_path;
+    if (typeof externalPath === "string" && externalPath.trim()) {
+        try {
+            if (envelope.schema === PHASE_ENVELOPE_SCHEMA) {
+                if (result.status === "done") {
+                    const parsed = JSON.parse(result.output ?? "null");
+                    atomicJson(path.resolve(externalPath), validateSection8Handoff(parsed, envelope));
+                }
+                else {
+                    const stalled = result.status === "stalled";
+                    const failure = {
+                        schema: PHASE_HANDOFF_SCHEMA,
+                        story_id: String(envelope.story_id), phase: String(envelope.phase),
+                        worker_id: String(envelope.worker_id), status: stalled ? "blocked" : "failed",
+                        summary: stalled ? "Phase stalled twice and needs operator direction." : "Phase execution failed.",
+                        files_changed: [], commits: [],
+                        back_pressure: { tests: "skip", lint: "skip", typecheck: "skip", build: "skip" },
+                        context_for_next: result.error ?? result.status,
+                    };
+                    atomicJson(path.resolve(externalPath), failure);
+                }
+            }
+            else
+                atomicJson(path.resolve(externalPath), result);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const recorded = {
+                ...result,
+                ...(result.status === "done" ? { status: "failed" } : {}),
+                error: [result.error, `result_path_error: ${message}`].filter(Boolean).join("; "),
+            };
+            atomicJson(localPath, recorded);
+        }
+    }
+    const claim = path.join(claimedDir(runDir), path.basename(activeFile));
+    const destination = result.status === "stalled"
+        ? path.join(runDir, "loop", "stalled", path.basename(activeFile))
+        : claim;
+    fs.mkdirSync(path.dirname(destination), { recursive: true });
+    fs.renameSync(activeFile, destination);
+}
+//# sourceMappingURL=loop.js.map