ralph-flow-pi 0.1.0

package/dist/engine/runner.js

@@ -0,0 +1,510 @@
+/**
+ * The instance runner — one loop per active workflow instance.
+ *
+ * This file replaces driver.ts, and it is the place where ralph-flow-pi stops
+ * being a port and becomes a different thing. The opencode plugin could not own
+ * the DO session: it lived in the user's chat, so the plugin waited for a
+ * `session.idle` event, scraped the last assistant message, regex'd it for
+ * `<promise>done</promise>`, and poked the session with `promptAsync`. Every one
+ * of those steps was a guess about someone else's session.
+ *
+ * Here the engine creates the session, so the loop just awaits it:
+ *
+ *     while (instance is live and unpaused):
+ *        DO      → fresh session per step, keep-alive until report_done
+ *        gate    → stop and let the user review (manual steps only)
+ *        CHECK   → fresh read-only session, verdict tool
+ *        route   → handleCheckPassed/Failed (verbatim engine logic)
+ *
+ * What the DO session gets is the point of the whole project: a brand-new
+ * context per step. Steps hand off through artifacts + the input/output fields,
+ * never through accumulated chat history — so step 7 cannot be poisoned by the
+ * debris of steps 1-6. The one exception is a check-failed retry of the SAME
+ * step, which resumes the same session because "here's what you just tried and
+ * why it failed" is exactly the context a fix needs, and max_fail_count bounds
+ * how far it can grow.
+ *
+ * Behaviors carried over verbatim from driver.ts (each was load-bearing):
+ *  - keep-alive budget MAX_DO_REINJECT=5, keyed per step:phase, NOT burned while
+ *    the model is making tool calls (it's working, not stuck); on exhaustion the
+ *    loop stops driving and hands control to the user WITHOUT pausing the state.
+ *  - the manual review gate sits BEFORE the check, not after.
+ *  - a check verdict is DISCARDED if the state moved while the check ran.
+ *  - infra failures pause with check_error and never burn a fail count.
+ */
+import fs from "fs";
+import path from "path";
+import { MANUAL_GATE_MARKER, MANUAL_STEP_MARKER } from "./core.js";
+import { adversarialCheck } from "./check.js";
+import { isSubWorkflowStep } from "./types.js";
+import { createStepSession } from "../pi/adapter.js";
+import { makeReportDoneTool } from "./step-tools.js";
+/** Keep-alive nudges before the loop gives up and hands control to the user. */
+export const MAX_DO_REINJECT = 5;
+export function createRunner(engine, initialEvents = {}, deps = {}) {
+    const createSession = deps.createSession ?? createStepSession;
+    /**
+     * The runner has exactly one caller of these callbacks internally (`events.
+     * onXxx?.(...)`, unchanged below), but now potentially several consumers:
+     * the chat session's "post into the transcript" listener lives for the
+     * whole process, and a run-view's listener is added only while a human is
+     * actively attached (see attachRunView in tui/embed.ts) and removed on
+     * detach. `events` stays a single object with the same shape so every
+     * existing call site below is untouched — it just fans out to whichever
+     * listeners are currently registered instead of being one fixed sink.
+     */
+    const listeners = new Set([initialEvents]);
+    const events = {
+        onStepStart: (instId, stepId, phase, attempt) => { for (const l of listeners)
+            l.onStepStart?.(instId, stepId, phase, attempt); },
+        onStepEvent: (instId, stepId, phase, event) => { for (const l of listeners)
+            l.onStepEvent?.(instId, stepId, phase, event); },
+        onVerdict: (instId, stepId, result) => { for (const l of listeners)
+            l.onVerdict?.(instId, stepId, result); },
+        onMessage: (instId, text) => { for (const l of listeners)
+            l.onMessage?.(instId, text); },
+        onGate: (instId, stepId) => { for (const l of listeners)
+            l.onGate?.(instId, stepId); },
+        onPaused: (instId, state) => { for (const l of listeners)
+            l.onPaused?.(instId, state); },
+        onStalled: (instId, stepId, attempts) => { for (const l of listeners)
+            l.onStalled?.(instId, stepId, attempts); },
+        onCompleted: (instId, reportPath) => { for (const l of listeners)
+            l.onCompleted?.(instId, reportPath); },
+    };
+    /** Attach an additional listener; call the returned function to detach it. */
+    function addEventListener(l) {
+        listeners.add(l);
+        return () => { listeners.delete(l); };
+    }
+    /** In-process guard: one loop per instance. Also the abort registry. */
+    const loops = new Map();
+    const activeStepSessions = new Map();
+    /** Pending "revise this gated step" instructions, consumed by the next DO turn. */
+    const pendingRevisions = new Map();
+    /**
+     * instIds that got a live human message since the loop last checked. A human
+     * talking to the session is not the model going silent, so that cycle must not
+     * burn the keep-alive budget — see sendUserMessage and its use in runDoPhase.
+     */
+    const humanSteered = new Set();
+    /** Platform seam: destroyInstance aborts a DO session running in this process. */
+    function abortActiveStep(instId) {
+        const session = activeStepSessions.get(instId);
+        if (!session)
+            return;
+        activeStepSessions.delete(instId);
+        Promise.resolve().then(() => session.abort()).catch(() => { }).then(() => session.dispose()).catch(() => { });
+    }
+    function isRunning(instId) {
+        return loops.has(instId);
+    }
+    /** Start the loop for an instance unless one is already running for it. */
+    function ensureRunning(instId) {
+        if (loops.has(instId))
+            return;
+        const loop = runLoop(instId)
+            .catch((e) => {
+            engine.diag(`[runner] loop crashed for ${instId}:`, e?.stack || e?.message || String(e));
+            engine.logEvent(instId, "error", "runner_loop_crashed", { error: e?.message });
+        })
+            .finally(() => {
+            loops.delete(instId);
+            engine.clearRunnerPid(instId);
+        });
+        loops.set(instId, loop);
+    }
+    /**
+     * The user reviewed a manual step and wants changes before verification.
+     * Re-open that step's DO session with their instruction and re-arm the gate —
+     * the opposite of approving it. The instruction is consumed by the next DO turn.
+     */
+    function reviseGate(instId, instruction) {
+        if (!engine.instanceExists(instId))
+            return;
+        const text = String(instruction || "").trim();
+        if (!text)
+            return;
+        pendingRevisions.set(instId, text);
+        engine.clearManualGate(instId);
+        engine.clearDoneReported(instId); // must re-run DO, not go to CHECK
+        engine.logEvent(instId, "info", "manual_gate_revise", { instruction: text.slice(0, 200) });
+        ensureRunning(instId);
+    }
+    /**
+     * Steer the live DO session with a human-typed message. Only meaningful while
+     * a DO turn is actually running — CHECK is independent and read-only by
+     * design, and there's nothing to steer once the step has moved on. Returns
+     * whether the message actually had somewhere to go.
+     */
+    function sendUserMessage(instId, text) {
+        const value = String(text || "").trim();
+        if (!value)
+            return false;
+        const session = activeStepSessions.get(instId);
+        if (!session)
+            return false;
+        const state = engine.readState(instId);
+        if (!state || !state.active || state.paused || state.current_phase !== "do")
+            return false;
+        humanSteered.add(instId);
+        void session.steer(value).catch((e) => engine.logEvent(instId, "warn", "steer_failed", { error: e?.message }));
+        return true;
+    }
+    /** Await every in-flight loop (tests; shutdown). */
+    async function idle() {
+        while (loops.size > 0)
+            await Promise.all([...loops.values()]);
+    }
+    /**
+     * Pause every instance this process is driving. Called on SIGINT/exit: the
+     * step transcripts are already on disk, so `ralphflow_continue` resumes the
+     * very session that was interrupted rather than restarting the step.
+     */
+    function pauseAllForShutdown() {
+        for (const instId of loops.keys()) {
+            const state = engine.readState(instId);
+            if (state && state.active && !state.paused) {
+                engine.writeState({ ...state, paused: true, pause_reason: "session_aborted" }, instId);
+                engine.logEvent(instId, "warn", "session_aborted", { instance: instId, step: state.current_step, phase: state.current_phase });
+            }
+            abortActiveStep(instId);
+            engine.clearRunnerPid(instId);
+        }
+    }
+    // ─── The loop ───────────────────────────────────────────────────────────────
+    async function runLoop(instId) {
+        engine.writeRunnerPid(instId);
+        for (;;) {
+            const state = engine.readState(instId);
+            // Gone: completed (destroyInstance) or cancelled by anyone.
+            if (!state || !state.active)
+                return;
+            if (state.paused) {
+                events.onPaused?.(instId, state);
+                return;
+            }
+            const workflow = engine.loadWorkflow(state.workflow_name);
+            if (!workflow) {
+                // Workflow YAML deleted after the instance was created — pause instead
+                // of stalling silently (driver.ts did the same).
+                pause(instId, state, "config_error", `工作流 "${state.workflow_name}" 未找到。`);
+                continue;
+            }
+            const step = engine.getStep(workflow, state.current_step);
+            if (!step) {
+                pause(instId, state, "config_error", `步骤 "${state.current_step}" 在工作流 "${state.workflow_name}" 中未找到。`);
+                continue;
+            }
+            if (isSubWorkflowStep(step)) {
+                // Normal flow enters sub-workflows inline through the transition logic;
+                // landing here means a resume found the state parked on one. Resolve it.
+                const entry = engine.resolveSubWorkflowEntry(instId, step.workflow, state.user_task, step);
+                if (entry.error) {
+                    pause(instId, state, "config_error", entry.text);
+                }
+                else {
+                    events.onMessage?.(instId, entry.text);
+                }
+                continue;
+            }
+            // ── CHECK re-entry ──
+            // A state already in "check" means either a continue cleared a check_error
+            // pause, or a crash landed here. Either way: verify, don't re-run DO.
+            if (state.current_phase === "check") {
+                const finished = await runCheckAndAdvance(instId, workflow, step, state);
+                if (finished)
+                    return;
+                continue;
+            }
+            // ── DO ──
+            const outcome = await runDoPhase(instId, workflow, step, state);
+            if (outcome === "gone")
+                return;
+            if (outcome === "stalled")
+                return; // user's turn; state deliberately NOT paused
+            // ── Manual review gate: BEFORE the check, never after ──
+            // The user's ralphflow_continue is the approval that starts verification.
+            if (engine.markerExists(MANUAL_STEP_MARKER, instId)) {
+                if (outcome === "done") {
+                    // Just finished a manual step → stop for review.
+                    engine.writeManualGate(instId);
+                    engine.logEvent(instId, "info", "manual_gate_armed", { step: step.id });
+                    events.onGate?.(instId, step.id);
+                    events.onMessage?.(instId, `📋 手动步骤 \`${step.id}\` 已完成，等待你的审查。\n\n- 满意后运行 /ralphflow-continue 进入独立验证\n- 需要修改直接在对话里说明，修改完成后会再次提示审查\n- 放弃可运行 /ralphflow-cancel`);
+                    return; // ralphflow_continue re-enters the loop
+                }
+                // Re-entered on a step that had already reported done. If the gate is
+                // still armed the user hasn't approved yet — stay out of their way.
+                // If it's gone, ralphflow_continue cleared it: that IS the approval.
+                if (engine.markerExists(MANUAL_GATE_MARKER, instId))
+                    return;
+            }
+            const fresh = engine.readState(instId);
+            if (!fresh || !fresh.active)
+                return;
+            const finished = await runCheckAndAdvance(instId, workflow, step, fresh);
+            if (finished)
+                return;
+        }
+    }
+    function pause(instId, state, reason, failure) {
+        engine.writeState({ ...state, paused: true, pause_reason: reason, last_failure_reason: failure }, instId);
+        engine.logEvent(instId, "warn", "workflow_paused", { workflow: state.workflow_name, step: state.current_step, reason });
+    }
+    // ─── DO phase ───────────────────────────────────────────────────────────────
+    /**
+     * Drive one step's DO phase to `report_done`.
+     *
+     * Session identity is the interesting part. `resumeSession` is true only when
+     * this step is being retried after its own check failed (state carries a
+     * last_failure_reason and the attempt dir already exists) — then the model
+     * keeps the context of what it just tried. Any other entry (a new step, a
+     * route from elsewhere) opens a fresh attempt dir, and therefore a fresh
+     * context window.
+     */
+    async function runDoPhase(instId, workflow, step, state) {
+        // A DO that already reported done (a gate the user just approved, or a crash
+        // between report_done and the check) must not be re-run — the work exists.
+        if (engine.doneReported(instId))
+            return "already-done";
+        // A gate revision resumes the SAME session (so the model keeps what it built)
+        // and leads with the user's requested change.
+        const revision = pendingRevisions.get(instId);
+        const attemptDir = revision !== undefined
+            ? (engine.listStepSessionDirs(instId, step.id, "do").slice(-1)[0] ?? pickAttemptDir(instId, step.id, state))
+            : pickAttemptDir(instId, step.id, state);
+        const model = deps.currentModel?.() ?? {};
+        let session;
+        try {
+            session = await createSession({
+                cwd: engine.projectDir,
+                model: model.model,
+                thinkingLevel: model.thinkingLevel,
+                sessionDir: attemptDir,
+                customTools: [makeReportDoneTool(engine, instId), ...(deps.stepTools?.(instId) ?? [])],
+                appendSystemPrompt: deps.stepSystemPromptSuffix?.(),
+                skillPaths: deps.skillPaths?.(),
+            });
+        }
+        catch (e) {
+            pause(instId, state, "config_error", `无法创建步骤会话：${e.message}`);
+            events.onMessage?.(instId, `## ⚠️ 无法创建步骤会话\n\n${e.message}\n\n工作流已暂停。解决后运行 \`/ralphflow-continue\` 恢复。`);
+            return "gone";
+        }
+        activeStepSessions.set(instId, session);
+        const attempt = (state.fail_count || 0) + 1;
+        events.onStepStart?.(instId, step.id, "do", attempt);
+        // Track tool activity per turn: a model that is calling tools is working,
+        // not stuck, so its keep-alive budget must not be burned.
+        let turnHadToolCalls = false;
+        let compacted = false;
+        const unsubscribe = session.subscribe((event) => {
+            if (event.type === "tool_start")
+                turnHadToolCalls = true;
+            if (event.type === "compaction_end")
+                compacted = true;
+            events.onStepEvent?.(instId, step.id, "do", event);
+        });
+        try {
+            const reinjectKey = `${step.id}:do`;
+            // First turn: a gate revision leads with the user's change (resuming the
+            // same session); otherwise the DO prompt itself (already cached).
+            let message;
+            if (revision !== undefined) {
+                pendingRevisions.delete(instId);
+                message = `用户审查了这一步的成果，要求如下修改：\n\n${revision}\n\n请据此调整，完成后再次调用 report_done 工具。`;
+            }
+            else {
+                message = engine.readDoPromptCache(instId)
+                    ?? engine.buildDoPrompt(instId, step, state.user_task, state.last_failure_reason, state.fail_count || undefined);
+            }
+            await session.prompt(message);
+            for (;;) {
+                if (engine.doneReported(instId)) {
+                    engine.clearReinjectCounter(instId);
+                    return "done";
+                }
+                const cur = engine.readState(instId);
+                if (!cur || !cur.active || cur.paused)
+                    return "gone"; // cancelled / paused underneath us
+                // A human just steered this session — that is engagement, not the model
+                // going silent, so this cycle must not burn the keep-alive budget.
+                const steered = humanSteered.delete(instId);
+                const attempts = turnHadToolCalls || steered
+                    ? engine.readReinjectCount(instId, reinjectKey)
+                    : engine.incrementReinjectCount(instId, reinjectKey);
+                if (attempts > MAX_DO_REINJECT && !turnHadToolCalls && !steered) {
+                    // Stop driving, but do NOT pause: the workflow is fine, the model is
+                    // just stuck. Driving resumes the moment the user says something.
+                    engine.logEvent(instId, "warn", "do_reinject_exhausted", { step: step.id, attempts });
+                    events.onStalled?.(instId, step.id, attempts);
+                    events.onMessage?.(instId, `## ⚠️ Ralph Flow 已停止自动驱动\n\n步骤 \`${step.id}\` 的 DO 阶段已连续 ${attempts} 次收到继续提示但未调用 report_done，请人工介入：\n1. 查看任务卡在哪里，补充信息后让模型继续\n2. 若任务实际已完成，运行 /ralphflow-continue 进入验证\n3. 运行 /ralphflow-cancel 取消工作流`);
+                    return "stalled";
+                }
+                // A compaction just dropped the task out of context — re-inject the full
+                // DO prompt rather than a bare "continue" (driver.ts did this on the
+                // session.compacted event). A human message was already steered into the
+                // turn directly, so the generic nudge would just be noise stacked right
+                // after real feedback — use a short acknowledgement instead.
+                const nudge = steered
+                    ? "（已收到你的补充说明，请据此继续；完成后调用 report_done 工具。）"
+                    : compacted
+                        ? `继续执行步骤 \`${step.id}\` 的任务。\n\n${engine.readDoPromptCache(instId) ?? ""}\n\n所有要求满足后调用 \`report_done\` 工具。`
+                        : `继续执行步骤 \`${step.id}\` 的任务。当所有要求满足后，调用 \`report_done\` 工具。`;
+                compacted = false;
+                turnHadToolCalls = false;
+                await session.followUp(nudge);
+            }
+        }
+        catch (e) {
+            if (!engine.instanceExists(instId))
+                return "gone"; // cancelled mid-turn
+            engine.logEvent(instId, "error", "do_session_error", { step: step.id, error: e.message });
+            const cur = engine.readState(instId);
+            if (cur && cur.active && !cur.paused) {
+                pause(instId, cur, "check_error", `步骤会话执行失败：${e.message}`);
+                events.onMessage?.(instId, `## ⚠️ 步骤会话执行失败\n\n${e.message}\n\n工作流已暂停（不计入失败次数）。解决后运行 \`/ralphflow-continue\` 恢复。`);
+            }
+            return "gone";
+        }
+        finally {
+            unsubscribe();
+            if (activeStepSessions.get(instId) === session)
+                activeStepSessions.delete(instId);
+            session.dispose();
+        }
+    }
+    /**
+     * Where this step attempt's transcript lives.
+     *
+     * Retrying the same step after ITS check failed resumes the newest attempt dir
+     * (fail_count > 0 and a dir exists). Everything else gets a new one — which is
+     * what makes "fresh context per step" true rather than aspirational.
+     */
+    /**
+     * Where this step attempt's transcript lives.
+     *
+     * Two conditions must BOTH hold to resume an existing session:
+     *  1. The state carries failure context (a check just rejected something, and
+     *     we are here to fix it — fail_count > 0, last_failure_reason present).
+     *  2. THIS specific step has been attempted before (its session dir exists).
+     *
+     * Together they mean "we came back to a step that already ran, with a reason
+     * to fix it." The second condition is the important guard: if on_fail routes
+     * to a DIFFERENT step that has never been tried, existing is empty → a new
+     * session is created (fresh context per step, even during failure routing).
+     *
+     * The common cases:
+     *  - Self-retry (on_fail == this step): resumes, model sees what it just tried.
+     *  - Loop-back (test fails → on_fail: implement): resumes implement's own
+     *    session so the model has its prior implementation context + the failure.
+     *  - Route to a recovery step never run before: fresh session.
+     */
+    function pickAttemptDir(instId, stepId, state) {
+        const hasFailureContext = (state.fail_count || 0) > 0 && !!state.last_failure_reason;
+        const existing = engine.listStepSessionDirs(instId, stepId, "do");
+        if (hasFailureContext && existing.length > 0)
+            return existing[existing.length - 1];
+        return engine.getStepSessionDir(instId, stepId, "do", existing.length + 1);
+    }
+    // ─── CHECK phase ────────────────────────────────────────────────────────────
+    /** @returns true when the loop should stop (completed, paused, or gone). */
+    async function runCheckAndAdvance(instId, workflow, step, state) {
+        // The DO-completion record belongs to the real do→check edge only. This
+        // function is re-entered with the state already in "check" (an infra retry
+        // after continue, or the crashed-check path), where re-recording would
+        // double the report rows.
+        if (state.current_phase === "do") {
+            engine.logEvent(instId, "info", "done_detected", { step: state.current_step });
+            engine.addStepRecord(instId, state.current_step, "do", "passed", state.fail_count || 0);
+        }
+        engine.clearManualStepMarker(instId);
+        engine.clearManualGate(instId);
+        engine.clearReinjectCounter(instId);
+        engine.clearDoPromptCache(instId);
+        engine.clearDoneReported(instId);
+        engine.writeState({ ...state, current_phase: "check" }, instId);
+        engine.recordStepStart(instId, state.current_step, "check");
+        engine.logEvent(instId, "info", "step_start", { step: state.current_step, phase: "check" });
+        events.onStepStart?.(instId, step.id, "check", (state.fail_count || 0) + 1);
+        const checkPrompt = engine.buildCheckPrompt(instId, step, state.user_task);
+        let checkResult;
+        try {
+            checkResult = await adversarialCheck(engine, instId, step, checkPrompt, state.user_task, workflow.adversarial_check, undefined, // onBashEvent: superseded by the live event stream below
+            deps.checkDeps, (event) => events.onStepEvent?.(instId, step.id, "check", event));
+        }
+        catch (err) {
+            engine.logEvent(instId, "error", "adversarial_check_uncaught", { stepId: step.id, error: err.message });
+            const st = engine.readState(instId);
+            if (st && st.active && st.current_phase === "check" && st.current_step === state.current_step && st.workflow_name === state.workflow_name) {
+                engine.writeState({ ...st, paused: true, pause_reason: "check_error", last_failure_reason: `对抗性检查崩溃：${err.message}` }, instId);
+            }
+            events.onMessage?.(instId, `## ⚠️ 验证未能运行\n\n对抗性检查崩溃：${err.message}\n\n工作流已暂停（不计入失败次数，已完成的工作保持原样）。问题解决后运行 \`/ralphflow-continue\` 重新验证。`);
+            return true;
+        }
+        // The state may have moved while the check ran (a cancel, a continue from
+        // another process, a shutdown pause). Applying a stale verdict would clear
+        // someone else's pause and drive a workflow that has moved on — discard it.
+        const cur = engine.readState(instId);
+        if (!cur || !cur.active || cur.paused || cur.current_phase !== "check"
+            || cur.workflow_name !== state.workflow_name || cur.current_step !== state.current_step) {
+            engine.logEvent(instId, "warn", "check_result_discarded", { reason: cur?.paused ? "instance paused during check" : "state changed during check" });
+            return true;
+        }
+        events.onVerdict?.(instId, step.id, { passed: checkResult.passed, infra: checkResult.infra, reason: checkResult.reason });
+        // Infra failure: no verdict was produced. Pause in check WITHOUT burning a
+        // fail count — the work is fine, the verifier isn't.
+        if (checkResult.infra) {
+            engine.writeState({ ...cur, paused: true, pause_reason: "check_error", last_failure_reason: checkResult.reason }, instId);
+            engine.logEvent(instId, "warn", "workflow_paused", { workflow: cur.workflow_name, step: cur.current_step, reason: "check_infra_error" });
+            events.onMessage?.(instId, `## ⚠️ 验证未能运行\n\n${checkResult.reason}\n\n这是验证进程自身的问题（额度/API/超时），**不是**工作成果的问题：本次不计入失败次数，已完成的工作无需重做。问题解决后运行 \`/ralphflow-continue\` 直接重新验证。`);
+            const p = engine.readState(instId);
+            if (p)
+                events.onPaused?.(instId, p);
+            return true;
+        }
+        engine.addStepRecord(instId, cur.current_step, "check", checkResult.passed ? "passed" : "failed", cur.fail_count || 0, checkResult.reason);
+        const result = checkResult.passed
+            ? engine.handleCheckPassed(instId, cur, workflow, step, checkResult)
+            : engine.handleCheckFailed(instId, cur, workflow, step, checkResult);
+        // Arm the next DO phase's markers before emitting the transition text
+        // (handleCheckPassed/Failed already wrote the state and cached the prompt).
+        if (!result.completed && !result.paused) {
+            const next = engine.readState(instId);
+            if (next && next.active && next.current_phase === "do") {
+                engine.clearDoneReported(instId);
+                engine.clearManualGate(instId);
+                const nextWf = next.workflow_name === workflow.name ? workflow : engine.loadWorkflow(next.workflow_name);
+                if (nextWf?.manual_step?.includes(next.current_step))
+                    engine.writeManualStepMarker(instId);
+                else
+                    engine.clearManualStepMarker(instId);
+            }
+        }
+        // Only a transition that needs the user (paused/completed) reaches the
+        // permanent chat listener — an ordinary silent pass-and-advance or
+        // fail-and-retry is exactly what "runs in the background, tells you when
+        // it needs you" promises NOT to surface unprompted. The run view (if
+        // attached) already shows every attempt live via onStepStart/onStepEvent/
+        // onVerdict, independent of onMessage, so nothing here is lost by staying
+        // quiet — only who gets told, and when.
+        if (result.completed || result.paused)
+            events.onMessage?.(instId, result.text);
+        if (result.completed) {
+            // The instance dir is gone now, but the archived report survives here.
+            const reportPath = path.join(engine.getReportsDir(), `${instId}-final-report.md`);
+            events.onCompleted?.(instId, fs.existsSync(reportPath) ? reportPath : undefined);
+            return true;
+        }
+        if (result.paused) {
+            const paused = engine.readState(instId);
+            if (paused)
+                events.onPaused?.(instId, paused);
+            return true;
+        }
+        return false; // keep looping into the next step's DO
+    }
+    return { ensureRunning, reviseGate, sendUserMessage, addEventListener, abortActiveStep, isRunning, idle, pauseAllForShutdown };
+}
+//# sourceMappingURL=runner.js.map

package/dist/engine/runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.js","sourceRoot":"","sources":["../../src/engine/runner.ts"],"names":[],"mappings":"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"}

package/dist/engine/skills.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Skill discovery, in the same three tiers as workflows: project → global → built-in.
+ *
+ * The engine deliberately knows almost nothing about skills. A workflow step's
+ * `do:` text just says "use the c-to-rust-plan skill"; the model reads that,
+ * finds the skill in its system prompt catalog, and loads it. That decoupling is
+ * inherited from both plugin versions and is why the 12 domain skills could move
+ * here as plain text.
+ *
+ * What changed from the plan: pi already ships this. `loadSkillsFromDir` parses
+ * SKILL.md frontmatter, and the default system prompt appends a catalog (name,
+ * description, ABSOLUTE location) plus the instruction to resolve a skill's
+ * relative references against its own directory — as long as the session has the
+ * `read` tool. So there is no `use_skill` tool here: writing one would have
+ * duplicated pi's mechanism and fought its prompt.
+ *
+ * All this file adds is the tier resolution pi doesn't do: same-named skills
+ * shadow, nearest tier wins, and only the winners are handed to the session.
+ */
+export type SkillSource = "project" | "global" | "builtin";
+export interface ResolvedSkill {
+    name: string;
+    description: string;
+    /** Absolute path to SKILL.md — what goes in the model's catalog. */
+    filePath: string;
+    source: SkillSource;
+    /** Same-named skills this one shadows, nearest-tier-first. */
+    shadowed: Array<{
+        source: SkillSource;
+        filePath: string;
+    }>;
+}
+export interface SkillIndex {
+    skills: ResolvedSkill[];
+    /** Absolute SKILL.md paths for the winners — pass to a session's skillPaths. */
+    paths: string[];
+    /** Human-readable problems (unparseable SKILL.md, etc). */
+    diagnostics: string[];
+}
+/** Skills shipped inside the package. */
+export declare function getBuiltinSkillsDir(): string;
+export declare function getProjectSkillsDir(ralphFlowDir: string): string;
+export declare function getGlobalSkillsDir(globalConfigHome: string | null): string | null;
+/**
+ * Resolve the skills available to a DO session.
+ *
+ * @param ralphFlowDir     the project's .ralph-flow dir
+ * @param globalConfigHome ~/.config/ralph-flow-pi, or null when there's no home
+ */
+export declare function loadSkillIndex(ralphFlowDir: string, globalConfigHome: string | null): SkillIndex;
+/** Doctor section: which skills are available, and what shadows what. */
+export declare function formatSkillReport(index: SkillIndex): string;
+//# sourceMappingURL=skills.d.ts.map

package/dist/engine/skills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../src/engine/skills.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAOH,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE3D,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,WAAW,CAAC;IACpB,8DAA8D;IAC9D,QAAQ,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,WAAW,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC5D;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,gFAAgF;IAChF,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,2DAA2D;IAC3D,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,yCAAyC;AACzC,wBAAgB,mBAAmB,IAAI,MAAM,CAI5C;AAED,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED,wBAAgB,kBAAkB,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAEjF;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,YAAY,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,IAAI,GAAG,UAAU,CA2ChG;AAED,yEAAyE;AACzE,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAoB3D"}