@entelligentsia/forgecli 1.0.10 → 1.0.20

package/dist/extensions/forgecli/run-task.js

@@ -19,16 +19,20 @@ import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { assertAudience, CallerContextStore } from "./audience-gate.js";
 import { loadLayeredConfig } from "./config-layer.js";
+import { buildGovernorFactory } from "./context-governor.js";
+import { buildForgeCompactionFactory } from "./context-governor-compaction.js";
 import { loadForgePersona, runForgeSubagent } from "./forge-subagent.js";
 import { getSubagentTools } from "./forge-tools.js";
 import { readPersonaDir, readPipelineNames } from "./lib/catalog-helpers.js";
 import { discoverForgeConfigCached } from "./lib/forge-config.js";
+import { resolveAdvisorModel, runHaltAdvisor } from "./lib/halt-advisor.js";
 import { checkMaterialization } from "./lib/manifest-checker.js";
 import { runOrchestratorPreflight } from "./lib/orchestrator-preflight.js";
 import { isStateStale as isJsonStateStale, readJsonState, taskStateFilePath, writeJsonState, } from "./lib/state-helpers.js";
 import { resolveModelForPhase } from "./model-resolver.js";
 import { loadWorkflow } from "./parsers/workflow-loader.js";
 import { getSessionRegistry } from "./session-registry.js";
+import { getOrchestratorTree } from "./orchestrator-tree.js";
 import { OrchestratorTranscriptWriter } from "./subagent/orchestrator-transcript.js";
 import { resolveToCanonicalId, resolveToolDir } from "./store-resolver.js";
 import { attachViewportObserver } from "./viewport-events.js";
@@ -224,6 +228,49 @@ export function emitEvent(storeCli, cwd, sprintId, event) {
     });
     return { ok: result.status === 0, stderr: typeof result.stderr === "string" ? result.stderr : "" };
 }
+/**
+ * Emit a phase event for an INCOMPLETE attempt (cancelled / failed) so its
+ * provider-billed tokens reach the store. Bug B: the cancel and halt-on-failure
+ * branches used to return without emitting, so collate's COST_REPORT
+ * under-counted real spend by exactly the aborted passes (CART-S02-T03
+ * baseline: 259,950 tokens across two aborted plan attempts, invisible).
+ *
+ * The event is the canonical phase event (schema-unchanged) with
+ * `verdict: "aborted" | "failed"` marking the outcome.
+ *
+ * Zero-token attempts are skipped — there is no spend to account, and a
+ * token-less event would be flagged as a husk by collate's ingestion-quality
+ * pass. Never throws: emission must not perturb the cancel/halt return paths.
+ *
+ * @param opts.decorate  Optional event mutation hook applied before emit
+ *                       (fix-bug uses it for the BUG_TYPE_TOKENS `type` field).
+ * @returns true when the event was emitted and store-cli accepted it.
+ */
+export function emitIncompletePhaseEvent(opts) {
+    try {
+        const { emitCtx, outcome } = opts;
+        const u = emitCtx.usage;
+        if (u.input + u.output + u.cacheRead + u.cacheWrite <= 0) {
+            opts.onDebug?.({ kind: "incomplete_emit_skipped", reason: "no-tokens", outcome });
+            return false;
+        }
+        const judgement = { verdict: outcome };
+        if (opts.notes)
+            judgement.notes = opts.notes;
+        const event = buildPhaseEvent({ ...emitCtx, judgement });
+        opts.decorate?.(event);
+        const res = emitEvent(emitCtx.storeCli, emitCtx.cwd, emitCtx.sprintId, event);
+        opts.onDebug?.(res.ok
+            ? { kind: "incomplete_emit_ok", eventId: event.eventId, outcome }
+            : { kind: "incomplete_emit_failed", stderr: res.stderr, outcome });
+        return res.ok;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        opts.onDebug?.({ kind: "incomplete_emit_failed", stderr: msg, outcome: opts.outcome });
+        return false;
+    }
+}
 export function judgementFromSummary(record, phaseRole, summaryKeyByRole) {
     if (!record || !record.summaries)
         return undefined;
@@ -348,13 +395,71 @@ export function composeTaskBody(subWorkflowMd, taskId, summariesBlock) {
     return parts.join("\n");
 }
 export function runPreflightGate(preflightGate, role, taskId, cwd, entityType) {
+    const outcome = runPreflightGateWithData(preflightGate, role, taskId, cwd, entityType);
+    return outcome.result;
+}
+/**
+ * Run postflight-gate.cjs after a phase subagent returns, before FSM advance.
+ * Mirrors runPreflightGateWithData — same argv-array discipline, same structured-JSON
+ * parsing from stdout on exit 1.
+ *
+ * Returns:
+ *   "ok"          — gate passed (or no outputs block for this phase); advance may proceed.
+ *   "unsatisfied" — gate failed; do NOT advance FSM; halt and call runHaltAdvisor.
+ *   "error"       — gate binary missing or parse error; treat as pass-through (additive).
+ */
+export function runPostflightGate(postflightGate, role, taskId, cwd) {
+    if (!fs.existsSync(postflightGate)) {
+        // postflight-gate.cjs not present in this forgeRoot — pass through (additive).
+        return { result: "ok", gateFailure: null };
+    }
+    const spawnResult = spawnSync("node", [postflightGate, "--phase", role, "--task", taskId], { cwd, encoding: "utf8" });
+    if (spawnResult.status === 0)
+        return { result: "ok", gateFailure: null };
+    if (spawnResult.status === 2)
+        return { result: "error", gateFailure: null };
+    // Exit 1: parse structured JSON from stdout
+    let gateFailure = null;
+    try {
+        const stdout = typeof spawnResult.stdout === "string" ? spawnResult.stdout.trim() : "";
+        if (stdout) {
+            const parsed = JSON.parse(stdout);
+            if (parsed && typeof parsed.reasonCode === "string") {
+                gateFailure = parsed;
+            }
+        }
+    }
+    catch {
+        // stdout not valid JSON — gate failure but no structured data
+    }
+    return { result: "unsatisfied", gateFailure };
+}
+/**
+ * Upgraded variant that returns structured failure data alongside the status enum.
+ * Callers that need the advisory data should use this function directly.
+ */
+export function runPreflightGateWithData(preflightGate, role, taskId, cwd, entityType) {
     const entityFlag = entityType === "bug" ? "--bug" : "--task";
-    const result = spawnSync("node", [preflightGate, "--phase", role, entityFlag, taskId], { cwd });
-    if (result.status === 0)
-        return "proceed";
-    if (result.status === 2)
-        return "escalate";
-    return "halt";
+    const spawnResult = spawnSync("node", [preflightGate, "--phase", role, entityFlag, taskId], { cwd, encoding: "utf8" });
+    if (spawnResult.status === 0)
+        return { result: "proceed", gateFailure: null };
+    if (spawnResult.status === 2)
+        return { result: "escalate", gateFailure: null };
+    // Exit 1: parse structured JSON from stdout
+    let gateFailure = null;
+    try {
+        const stdout = typeof spawnResult.stdout === "string" ? spawnResult.stdout.trim() : "";
+        if (stdout) {
+            const parsed = JSON.parse(stdout);
+            if (parsed && typeof parsed.reasonCode === "string") {
+                gateFailure = parsed;
+            }
+        }
+    }
+    catch {
+        // stdout not valid JSON — gate failure but no structured data
+    }
+    return { result: "halt", gateFailure };
 }
 // ── Per-task orchestrator pipeline (FORGE-S21-T03 extracted) ──────────────
 // The entire phase loop was inline in registerRunTask. It is now a standalone
@@ -369,6 +474,8 @@ export { extractTurnPreview } from "./viewport-renderer.js";
 // ── runTaskPipeline ──────────────────────────────────────────────────────
 export async function runTaskPipeline(opts) {
     const { taskId, cwd, ctx, forgeRoot, storeCli, preflightGate, registry, resumeFromState, onPhaseEvent } = opts;
+    // Bridge: OrchestratorTree for the dashboard overlay.
+    const tree = getOrchestratorTree();
     // Load per-phase model routing config once at task entry (Plan 16 Slice 2).
     // Empty / absent config produces inherit for every phase — no behaviour change.
     // N-B-E: surface schema errors to caller (Decision 9 — orchestrators fail-fast).
@@ -513,9 +620,16 @@ export async function runTaskPipeline(opts) {
             }
             // ── 6a. Preflight gate ────────────────────────────────────────
             if (fs.existsSync(preflightGate)) {
-                const preflightResult = runPreflightGate(preflightGate, phase.role, taskId, cwd);
-                if (preflightResult === "halt") {
-                    ctx.ui.notify(`× forge:run-task — preflight gate failed for phase ${phase.role} (exit 1); halting.`, "error");
+                const preflightOutcome = runPreflightGateWithData(preflightGate, phase.role, taskId, cwd);
+                if (preflightOutcome.result === "halt") {
+                    // Render structured failure reason if available.
+                    if (preflightOutcome.gateFailure) {
+                        ctx.ui.notify(`× forge:run-task — preflight gate failed for phase ${phase.role} ` +
+                            `[${preflightOutcome.gateFailure.reasonCode}]: ${preflightOutcome.gateFailure.detail}`, "error");
+                    }
+                    else {
+                        ctx.ui.notify(`× forge:run-task — preflight gate failed for phase ${phase.role} (exit 1); halting.`, "error");
+                    }
                     writeState(cwd, {
                         taskId,
                         phaseIndex: currentPhaseIndex,
@@ -524,6 +638,18 @@ export async function runTaskPipeline(opts) {
                         lastError: `preflight gate exit 1 for ${phase.role}`,
                         savedAt: new Date().toISOString(),
                     });
+                    // Spawn halt-recovery advisor (Tier 1, best-effort — non-fatal).
+                    if (preflightOutcome.gateFailure) {
+                        const advisorModel = resolveAdvisorModel(modelRoutingConfig, ctx.model);
+                        void runHaltAdvisor({
+                            gateFailure: preflightOutcome.gateFailure,
+                            advisorModel,
+                            taskId,
+                            cwd,
+                            ctx: { ui: ctx.ui },
+                            forgeRoot,
+                        });
+                    }
                     return {
                         status: "halted",
                         lastPhaseIndex: currentPhaseIndex,
@@ -531,7 +657,7 @@ export async function runTaskPipeline(opts) {
                         lastError: `preflight gate exit 1 for ${phase.role}`,
                     };
                 }
-                if (preflightResult === "escalate") {
+                if (preflightOutcome.result === "escalate") {
                     ctx.ui.notify(`× forge:run-task — preflight gate escalated for phase ${phase.role} (exit 2); manual intervention required.`, "error");
                     writeState(cwd, {
                         taskId,
@@ -646,6 +772,15 @@ export async function runTaskPipeline(opts) {
                 persona: phase.personaNoun,
             });
             registry.startPhase(taskId, phase.role, currentPhaseIndex);
+            // Bridge: register phase in OrchestratorTree.
+            const iteration = (opts.resumeFromState?.iterationCounts?.[phase.role] ?? 0) + 1;
+            const phaseNodeId = `${taskId}:${phase.role}:${iteration}`;
+            tree.startNode(phaseNodeId, {
+                parentId: taskId,
+                label: `${phase.role}:${iteration}`,
+                kind: "leaf",
+                promptPreview: taskBody.slice(0, 200),
+            });
             // Capture the first stream-observed model on turn_end (IL10 visibility).
             // If pi auto-substitutes or setModel silently no-ops, this line will diverge
             // from requested_model — exactly the diagnostic signal we want.
@@ -680,6 +815,29 @@ export async function runTaskPipeline(opts) {
                 verboseKeys: { messageKey: MESSAGE_KEY },
                 afterEach: refreshStatus,
             });
+            // ── Context governor injection (completes FORGE-S30-T07) ──────
+            // Per-phase factories built HERE because only the pipeline knows the
+            // `${personaNoun}/${role}` phase key — pi never sets persona/phase on
+            // ExtensionContext, and the parent session's registerHookDispatcher
+            // governor never sees subagent tool traffic (dormant-governor defect,
+            // CART-S02-T03 benchmark). Flag-gated: FORGE_CTX_GOVERNOR=1.
+            //   buildGovernorFactory        — Mechanisms A/B/C/D in the subagent
+            //   buildForgeCompactionFactory — Mechanism E with warm-tier path opts
+            //     (previously injected from index.ts with NO opts → warm-tier dead)
+            const phaseKey = `${phase.personaNoun}/${phase.role}`;
+            const sprintIdForSummaries = /^(.*)-T\d+$/.exec(taskId)?.[1];
+            const governorFactories = process.env.FORGE_CTX_GOVERNOR === "1"
+                ? [
+                    buildGovernorFactory({ phaseKey, cwd }),
+                    buildForgeCompactionFactory({
+                        cwd,
+                        phaseKey,
+                        entityId: taskId,
+                        sprintId: sprintIdForSummaries,
+                    }),
+                ]
+                : [];
+            const phaseExtensionFactories = [...(opts.extensionFactories ?? []), ...governorFactories];
             let result;
             try {
                 // FORGE-BUG-040: wrap the runForgeSubagent dispatch in the phase
@@ -698,6 +856,7 @@ export async function runTaskPipeline(opts) {
                     modelRegistry: ctx.modelRegistry,
                     signal: opts.signal,
                     customTools: opts.forgeToolDefs ? getSubagentTools(opts.forgeToolDefs, persona.name) : undefined,
+                    extensionFactories: phaseExtensionFactories.length > 0 ? phaseExtensionFactories : undefined,
                 }));
             }
             catch (err) {
@@ -728,7 +887,42 @@ export async function runTaskPipeline(opts) {
             if (result.stopReason === "aborted" || opts.signal?.aborted) {
                 ctx.ui.notify(`⊘ forge:run-task — ${taskId} phase ${phase.role} cancelled.`, "info");
                 registry.completePhase(taskId, phase.role, "cancelled");
+                tree.completeNode(phaseNodeId, "cancelled");
                 registry.confirmCancelled(taskId);
+                // Bug B: account the billed tokens of this aborted attempt before returning.
+                {
+                    const abortSprintId = readTaskRecord(taskId, storeCli, cwd)?.sprintId;
+                    if (abortSprintId) {
+                        emitIncompletePhaseEvent({
+                            emitCtx: {
+                                entityType: "task",
+                                taskId,
+                                sprintId: abortSprintId,
+                                phase,
+                                iteration: (iterationCounts[phase.role] ?? 0) + 1,
+                                startMs: phaseStart,
+                                endMs: Date.now(),
+                                model: result.model ?? "unknown",
+                                provider: result.provider ?? "unknown",
+                                usage: {
+                                    input: result.usage.input,
+                                    output: result.usage.output,
+                                    cacheRead: result.usage.cacheRead,
+                                    cacheWrite: result.usage.cacheWrite,
+                                },
+                                judgement: undefined,
+                                storeCli,
+                                cwd,
+                            },
+                            outcome: "aborted",
+                            notes: result.errorMessage ?? result.stopReason ?? undefined,
+                            onDebug: writeDebug,
+                        });
+                    }
+                    else {
+                        writeDebug({ kind: "incomplete_emit_skipped", reason: "no-sprintId", outcome: "aborted" });
+                    }
+                }
                 // ADR-S21-01: preserve state file so cancelled runs are resumable
                 writeState(cwd, {
                     taskId,
@@ -746,6 +940,40 @@ export async function runTaskPipeline(opts) {
                 ctx.ui.notify(`× forge:run-task — phase ${phase.role} failed (exit ${result.exitCode})` +
                     (result.errorMessage ? `: ${result.errorMessage}` : "") +
                     (result.stopReason ? ` [${result.stopReason}]` : ""), "error");
+                // Bug B: account the billed tokens of this failed attempt before returning.
+                {
+                    const failSprintId = readTaskRecord(taskId, storeCli, cwd)?.sprintId;
+                    if (failSprintId) {
+                        emitIncompletePhaseEvent({
+                            emitCtx: {
+                                entityType: "task",
+                                taskId,
+                                sprintId: failSprintId,
+                                phase,
+                                iteration: (iterationCounts[phase.role] ?? 0) + 1,
+                                startMs: phaseStart,
+                                endMs: Date.now(),
+                                model: result.model ?? "unknown",
+                                provider: result.provider ?? "unknown",
+                                usage: {
+                                    input: result.usage.input,
+                                    output: result.usage.output,
+                                    cacheRead: result.usage.cacheRead,
+                                    cacheWrite: result.usage.cacheWrite,
+                                },
+                                judgement: undefined,
+                                storeCli,
+                                cwd,
+                            },
+                            outcome: "failed",
+                            notes: result.errorMessage ?? result.stopReason ?? undefined,
+                            onDebug: writeDebug,
+                        });
+                    }
+                    else {
+                        writeDebug({ kind: "incomplete_emit_skipped", reason: "no-sprintId", outcome: "failed" });
+                    }
+                }
                 writeState(cwd, {
                     taskId,
                     phaseIndex: currentPhaseIndex,
@@ -854,7 +1082,7 @@ export async function runTaskPipeline(opts) {
                 const verdict = readVerdict(taskId, phase.role, storeCli, cwd);
                 if (verdict === "missing") {
                     ctx.ui.notify(`× forge:run-task — verdict missing for phase ${phase.role} after subagent completed. ` +
-                        "Subagent may have crashed or failed to write summaries. Escalating.", "error");
+                        "Subagent may have crashed or failed to write summaries. Halting for advisory.", "error");
                     writeState(cwd, {
                         taskId,
                         phaseIndex: currentPhaseIndex,
@@ -863,8 +1091,35 @@ export async function runTaskPipeline(opts) {
                         lastError: `verdict missing for ${phase.role}`,
                         savedAt: new Date().toISOString(),
                     });
+                    // A missing verdict IS a postflight-outputs failure: the canonical
+                    // phase summary the subagent must write (e.g. summaries.code_review)
+                    // was never recorded, so there is no verdict to route on. review-phase
+                    // workflows declare no `outputs` block, so runPostflightGate is a
+                    // pass-through here — this readVerdict check is the effective gate.
+                    // Route it through the halt-recovery advisor (FORGE-S26-T18), the same
+                    // hand-off the postflight-gate-unsatisfied branch uses, instead of a
+                    // bare escalation — so the strongest configured model can diagnose the
+                    // missing-summary cause. Best-effort, non-fatal (FORGE-S26-T19 parity).
+                    const gateFailure = {
+                        phase: phase.role,
+                        reasonCode: "verdict-missing",
+                        detail: `Phase '${phase.role}' completed but no verdict was found in the store. ` +
+                            "The canonical phase summary was not written, so the orchestrator has no verdict to route on.",
+                        remediation: "Re-run the phase and ensure the subagent's forge_store set-summary call " +
+                            'uses args:["<recordId>", "<phaseKey>"] with the literal phase key as args[1] ' +
+                            "(e.g. code_review), and that the call exits zero before the subagent returns.",
+                    };
+                    const advisorModel = resolveAdvisorModel(modelRoutingConfig, ctx.model);
+                    void runHaltAdvisor({
+                        gateFailure,
+                        advisorModel,
+                        taskId,
+                        cwd,
+                        ctx: { ui: ctx.ui },
+                        forgeRoot,
+                    });
                     return {
-                        status: "failed",
+                        status: "halted",
                         lastPhaseIndex: currentPhaseIndex,
                         iterationCounts,
                         lastError: `verdict missing for ${phase.role}`,
@@ -917,8 +1172,57 @@ export async function runTaskPipeline(opts) {
                 }
                 // verdict === "approved": fall through to advance
             }
+            // Postflight gate: evaluate `outputs` block after subagent returns,
+            // before FSM status advance (FORGE-S26-T19). Hard enforcement in forge-cli;
+            // plugin LLM route treats postflight as advisory. On UNSATISFIED: do not
+            // advance currentPhaseIndex, halt, hand off to existing runHaltAdvisor.
+            {
+                const postflightGatePath = preflightGate.replace("preflight-gate.cjs", "postflight-gate.cjs");
+                const postflightOutcome = runPostflightGate(postflightGatePath, phase.role, taskId, cwd);
+                if (postflightOutcome.result === "unsatisfied") {
+                    if (postflightOutcome.gateFailure) {
+                        ctx.ui.notify(`× forge:run-task — postflight gate failed for phase ${phase.role} ` +
+                            `[${postflightOutcome.gateFailure.reasonCode}]: ${postflightOutcome.gateFailure.detail}`, "error");
+                    }
+                    else {
+                        ctx.ui.notify(`× forge:run-task — postflight gate failed for phase ${phase.role}; halting.`, "error");
+                    }
+                    // Do NOT advance FSM — write state at current phaseIndex (halted)
+                    writeState(cwd, {
+                        taskId,
+                        phaseIndex: currentPhaseIndex,
+                        iterationCounts,
+                        halted: true,
+                        lastError: `postflight gate exit 1 for ${phase.role}`,
+                        savedAt: new Date().toISOString(),
+                    });
+                    // Spawn halt-recovery advisor (Tier 1, best-effort — non-fatal).
+                    if (postflightOutcome.gateFailure) {
+                        const advisorModel = resolveAdvisorModel(modelRoutingConfig, ctx.model);
+                        void runHaltAdvisor({
+                            gateFailure: postflightOutcome.gateFailure,
+                            advisorModel,
+                            taskId,
+                            cwd,
+                            ctx: { ui: ctx.ui },
+                            forgeRoot,
+                        });
+                    }
+                    return {
+                        status: "halted",
+                        lastPhaseIndex: currentPhaseIndex,
+                        iterationCounts,
+                        lastError: `postflight gate exit 1 for ${phase.role}`,
+                    };
+                }
+                // "ok" or "error" — proceed to advance
+            }
             // ── Advance to next phase ─────────────────────────────────────
             registry.completePhase(taskId, phase.role, "completed");
+            tree.completeNode(phaseNodeId, "completed");
+            tree.setNodeUsage(phaseNodeId, { input: result.usage.input, output: result.usage.output, cacheRead: result.usage.cacheRead });
+            if (result.model)
+                tree.setNodeModel(phaseNodeId, result.model, result.provider ?? "");
             writeState(cwd, {
                 taskId,
                 phaseIndex: currentPhaseIndex,
@@ -1058,6 +1362,9 @@ export function registerRunTask(pi, options = {}) {
             // steal arrow keys from ctx.ui.select / ctx.ui.confirm dialogs.
             const registry = getSessionRegistry();
             registry.startSession(taskId);
+            // Bridge: also register in OrchestratorTree for the dashboard overlay.
+            const tree = getOrchestratorTree();
+            tree.startNode(taskId, { label: taskId, kind: "orchestrator" });
             const signal = registry.getAbortSignal(taskId);
             const pipelineResult = await runTaskPipeline({
                 taskId,
@@ -1070,19 +1377,23 @@ export function registerRunTask(pi, options = {}) {
                 resumeFromState,
                 signal,
                 forgeToolDefs: options.forgeToolDefs,
+                extensionFactories: options.extensionFactories,
             });
             // ── Handle result ────────────────────────────────────────────────
             if (pipelineResult.status === "completed") {
                 registry.completeSession(taskId, "completed");
+                tree.completeNode(taskId, "completed");
                 ctx.ui.notify(`〇 forge:run-task — ${taskId} pipeline complete (${PHASES.length} phases).`, "info");
             }
             else if (pipelineResult.status === "cancelled") {
                 // confirmCancelled was already called by the pipeline, but
                 // completeSession("cancelled") ensures the session ends cleanly.
                 registry.completeSession(taskId, "cancelled");
+                tree.completeNode(taskId, "cancelled");
             }
             else {
                 registry.completeSession(taskId, "failed");
+                tree.completeNode(taskId, "failed");
             }
             ctx.ui.setStatus?.(STATUS_KEY, undefined);
             ctx.ui.setStatus?.(MESSAGE_KEY, undefined);