@entelligentsia/forgecli 1.0.21 → 1.0.36

package/dist/extensions/forgecli/orchestrators/common/orchestrator-entry.js

@@ -0,0 +1,85 @@
+// orchestrator-entry.ts — shared "common concerns" for orchestrator entry.
+//
+// Three helpers used by all three orchestrator handlers:
+//   - gatherModelValidationInputs: the byte-identical persona/pipeline/model
+//     catalogue snippet (run-task, fix-bug, run-sprint).
+//   - resolveOrchestratorEntry: discover the Forge config, fail-and-clear-status
+//     when absent, sweep orphaned transcripts, return resolved tool paths.
+//   - runPipelinePreflight: layered-config schema check + full model-config
+//     validation (used by run-task and fix-bug; run-sprint keeps its own inline
+//     sprint-entry validation per the N-H-D boundary).
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadLayeredConfig } from "../../config/config-layer.js";
+import { readPersonaDir, readPipelineNames } from "../../lib/catalog-helpers.js";
+import { discoverForgeConfigCached } from "../../lib/forge-config.js";
+import { sweepProjectTranscripts } from "../../transcript-archive.js";
+import { runOrchestratorPreflight } from "../orchestrator-preflight.js";
+/** Gather the model-validation inputs shared by every orchestrator entry: the
+ *  bundled persona catalogue, the project pipeline names, and the session model
+ *  registry. The persona dir is resolved relative to this module's dist
+ *  location (orchestrators/common → four levels up to dist/forge-payload). */
+export function gatherModelValidationInputs(cwd, ctx) {
+    const personasDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "..", "forge-payload", ".base-pack", "personas");
+    const personaCatalogue = readPersonaDir(personasDir);
+    const forgeCfgPath = path.join(cwd, ".forge", "config.json");
+    const pipelineCatalogue = readPipelineNames(forgeCfgPath);
+    const availableModels = (ctx.modelRegistry?.getAvailable?.() ?? []).map((m) => ({ provider: m.provider, id: m.id }));
+    return { personaCatalogue, pipelineCatalogue, availableModels };
+}
+/** Discover the Forge config at cwd. On success, sweep orphaned project
+ *  transcripts and return the resolved tool paths. On failure, notify and clear
+ *  the status line, then return null (caller returns immediately). */
+export function resolveOrchestratorEntry(opts) {
+    const { cwd, notify } = opts;
+    const forgeConfig = discoverForgeConfigCached(cwd);
+    if (!forgeConfig) {
+        notify.error("no Forge project found at cwd. Run /forge:init first.");
+        notify.clearStatus();
+        return null;
+    }
+    const forgeRoot = forgeConfig.forgeRoot;
+    // Best-effort transcript-archive sweep: adopt any project-local runs not yet
+    // in the central index (crash recovery + pre-existing history). Runs BEFORE
+    // any pipeline creates its own transcript writer, so in-flight runs are
+    // never swept half-written.
+    sweepProjectTranscripts(cwd);
+    return {
+        forgeRoot,
+        storeCli: path.join(forgeRoot, "tools", "store-cli.cjs"),
+        preflightGate: path.join(forgeRoot, "tools", "preflight-gate.cjs"),
+    };
+}
+/** Layered-config schema check followed by full model-config validation.
+ *  Surfaces schema/validation errors via the notifier (matching the legacy
+ *  inline strings) and returns the merged routing config on success. */
+export function runPipelinePreflight(opts) {
+    const { cwd, ctx, notify } = opts;
+    // N-B-E: surface schema errors to caller (Decision 9 — orchestrators
+    // fail-fast). See doc/decisions/layered-config-error-policy.md.
+    const { merged: modelRoutingConfig, errors: layeredConfigErrors } = loadLayeredConfig(cwd);
+    if (layeredConfigErrors.length > 0) {
+        for (const e of layeredConfigErrors) {
+            notify.error(`forge-cli config schema error: ${e}`);
+        }
+        return { proceed: false, lastError: `forge-cli config schema errors: ${layeredConfigErrors.join("; ")}` };
+    }
+    const inputs = gatherModelValidationInputs(cwd, ctx);
+    const preflightResult = runOrchestratorPreflight({
+        mode: "task",
+        ctx,
+        notifyPrefix: notify.label,
+        personaCatalogue: inputs.personaCatalogue,
+        pipelineCatalogue: inputs.pipelineCatalogue,
+        modelRoutingConfig,
+        availableModels: inputs.availableModels,
+    });
+    if (!preflightResult.proceed) {
+        return {
+            proceed: false,
+            lastError: preflightResult.result.lastError ?? "model config validation failed",
+        };
+    }
+    return { proceed: true, modelRoutingConfig };
+}
+//# sourceMappingURL=orchestrator-entry.js.map

package/dist/extensions/forgecli/orchestrators/common/orchestrator-entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator-entry.js","sourceRoot":"","sources":["../../../../../src/extensions/forgecli/orchestrators/common/orchestrator-entry.ts"],"names":[],"mappings":"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"}

package/dist/extensions/forgecli/orchestrators/common/orchestrator-misc.d.ts

@@ -0,0 +1,8 @@
+export declare function isNonInteractive(): boolean;
+/** Validate that an ID contains no path-traversal characters. */
+export declare function validateId(id: string): boolean;
+/**
+ * Format an ISO timestamp for human display in the user's local timezone.
+ * Falls back to the raw ISO string if parsing fails.
+ */
+export declare function formatLocalTime(iso: string): string;

package/dist/extensions/forgecli/orchestrators/common/orchestrator-misc.js

@@ -0,0 +1,37 @@
+// orchestrator-misc.ts — generic orchestrator helpers shared across the
+// task / sprint / bug pipelines. Extracted from run-task.ts (no logic changes)
+// so the per-file architectural line cap is satisfied; run-task.ts re-exports
+// these for backwards compatibility (fix-bug.ts and run-sprint.ts import them
+// from run-task today).
+// ── Non-interactive helpers ───────────────────────────────────────────────
+export function isNonInteractive() {
+    return process.env.FORGE_YES === "1" || process.env.FORGE_NON_INTERACTIVE === "1";
+}
+/** Validate that an ID contains no path-traversal characters. */
+export function validateId(id) {
+    return /^[A-Za-z0-9_-]+$/.test(id) && !id.includes("..");
+}
+/**
+ * Format an ISO timestamp for human display in the user's local timezone.
+ * Falls back to the raw ISO string if parsing fails.
+ */
+export function formatLocalTime(iso) {
+    const d = new Date(iso);
+    if (Number.isNaN(d.getTime()))
+        return iso;
+    const date = d.toLocaleString(undefined, {
+        year: "numeric",
+        month: "short",
+        day: "2-digit",
+        hour: "2-digit",
+        minute: "2-digit",
+        second: "2-digit",
+        hour12: false,
+    });
+    // Append short timezone abbreviation for unambiguous reading.
+    const tz = new Intl.DateTimeFormat(undefined, { timeZoneName: "short" })
+        .formatToParts(d)
+        .find((p) => p.type === "timeZoneName")?.value ?? "";
+    return tz ? `${date} ${tz}` : date;
+}
+//# sourceMappingURL=orchestrator-misc.js.map

package/dist/extensions/forgecli/orchestrators/common/orchestrator-misc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator-misc.js","sourceRoot":"","sources":["../../../../../src/extensions/forgecli/orchestrators/common/orchestrator-misc.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,+EAA+E;AAC/E,8EAA8E;AAC9E,8EAA8E;AAC9E,wBAAwB;AAExB,6EAA6E;AAE7E,MAAM,UAAU,gBAAgB;IAC/B,OAAO,OAAO,CAAC,GAAG,CAAC,SAAS,KAAK,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC,qBAAqB,KAAK,GAAG,CAAC;AACnF,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,UAAU,CAAC,EAAU;IACpC,OAAO,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AAC1D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,GAAW;IAC1C,MAAM,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC;IACxB,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;QAAE,OAAO,GAAG,CAAC;IAC1C,MAAM,IAAI,GAAG,CAAC,CAAC,cAAc,CAAC,SAAS,EAAE;QACxC,IAAI,EAAE,SAAS;QACf,KAAK,EAAE,OAAO;QACd,GAAG,EAAE,SAAS;QACd,IAAI,EAAE,SAAS;QACf,MAAM,EAAE,SAAS;QACjB,MAAM,EAAE,SAAS;QACjB,MAAM,EAAE,KAAK;KACb,CAAC,CAAC;IACH,8DAA8D;IAC9D,MAAM,EAAE,GACP,IAAI,IAAI,CAAC,cAAc,CAAC,SAAS,EAAE,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC;SAC3D,aAAa,CAAC,CAAC,CAAC;SAChB,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,cAAc,CAAC,EAAE,KAAK,IAAI,EAAE,CAAC;IACvD,OAAO,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AACpC,CAAC"}

package/dist/extensions/forgecli/orchestrators/common/orchestrator-notify.d.ts

@@ -0,0 +1,28 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+type NotifyLevel = Parameters<ExtensionCommandContext["ui"]["notify"]>[1];
+export interface OrchestratorNotifierOptions {
+    /** Command label, e.g. "forge:run-task" / "forge:fix-bug" / "forge:run-sprint". */
+    label: string;
+    /** ctx.ui status key for this command. */
+    statusKey: string;
+    /** Optional detail-message status key (absent for run-sprint). */
+    messageKey?: string;
+}
+export interface OrchestratorNotifier {
+    readonly label: string;
+    readonly statusKey: string;
+    /** Raw passthrough to the live ctx.ui.notify. */
+    notify(message: string, level?: NotifyLevel): void;
+    /** `× <label> — <msg>` at error level. */
+    error(msg: string): void;
+    /** `⚠ <label> — <msg>` at warning level. */
+    warn(msg: string): void;
+    /** `<label> — <msg>` at info level. */
+    info(msg: string): void;
+    /** Set the command status line. */
+    setStatus(text: string): void;
+    /** Clear the status key (and message key, if configured). */
+    clearStatus(): void;
+}
+export declare function createOrchestratorNotifier(ctx: ExtensionCommandContext, opts: OrchestratorNotifierOptions): OrchestratorNotifier;
+export {};

package/dist/extensions/forgecli/orchestrators/common/orchestrator-notify.js

@@ -0,0 +1,45 @@
+// orchestrator-notify.ts — shared UI-notification facade for the orchestrator
+// pipelines (run-task, fix-bug, run-sprint).
+//
+// Owns the per-command label, the status/message keys, and the two highest-
+// frequency mechanical notification shapes:
+//
+//   error(msg)  → `× <label> — <msg>`   (level "error")
+//   warn(msg)   → `⚠ <label> — <msg>`   (level "warning")
+//   info(msg)   → `<label> — <msg>`     (level "info")
+//
+// The semantic-symbol lines (⊘ cancel, ⟳ loopback, 〇 complete, ✓ phase-done,
+// → phase-start, ▶ dispatch) stay inline at their call sites but are emitted
+// through `notify(...)` so they still hit the transcript recorder.
+//
+// IMPORTANT: every method reads `ctx.ui.notify` LIVE on each call (never a
+// captured/bound reference) so the transcript-recorder swap installed by
+// withOrchestratorTranscript is honored.
+export function createOrchestratorNotifier(ctx, opts) {
+    const { label, statusKey, messageKey } = opts;
+    return {
+        label,
+        statusKey,
+        notify(message, level) {
+            ctx.ui.notify(message, level);
+        },
+        error(msg) {
+            ctx.ui.notify(`× ${label} — ${msg}`, "error");
+        },
+        warn(msg) {
+            ctx.ui.notify(`⚠ ${label} — ${msg}`, "warning");
+        },
+        info(msg) {
+            ctx.ui.notify(`${label} — ${msg}`, "info");
+        },
+        setStatus(text) {
+            ctx.ui.setStatus?.(statusKey, text);
+        },
+        clearStatus() {
+            ctx.ui.setStatus?.(statusKey, undefined);
+            if (messageKey)
+                ctx.ui.setStatus?.(messageKey, undefined);
+        },
+    };
+}
+//# sourceMappingURL=orchestrator-notify.js.map

package/dist/extensions/forgecli/orchestrators/common/orchestrator-notify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator-notify.js","sourceRoot":"","sources":["../../../../../src/extensions/forgecli/orchestrators/common/orchestrator-notify.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,6CAA6C;AAC7C,EAAE;AACF,4EAA4E;AAC5E,4CAA4C;AAC5C,EAAE;AACF,wDAAwD;AACxD,0DAA0D;AAC1D,uDAAuD;AACvD,EAAE;AACF,6EAA6E;AAC7E,6EAA6E;AAC7E,mEAAmE;AACnE,EAAE;AACF,2EAA2E;AAC3E,yEAAyE;AACzE,yCAAyC;AAgCzC,MAAM,UAAU,0BAA0B,CACzC,GAA4B,EAC5B,IAAiC;IAEjC,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,GAAG,IAAI,CAAC;IAC9C,OAAO;QACN,KAAK;QACL,SAAS;QACT,MAAM,CAAC,OAAe,EAAE,KAAmB;YAC1C,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAC/B,CAAC;QACD,KAAK,CAAC,GAAW;YAChB,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,KAAK,KAAK,MAAM,GAAG,EAAE,EAAE,OAAO,CAAC,CAAC;QAC/C,CAAC;QACD,IAAI,CAAC,GAAW;YACf,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,KAAK,KAAK,MAAM,GAAG,EAAE,EAAE,SAAS,CAAC,CAAC;QACjD,CAAC;QACD,IAAI,CAAC,GAAW;YACf,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,GAAG,KAAK,MAAM,GAAG,EAAE,EAAE,MAAM,CAAC,CAAC;QAC5C,CAAC;QACD,SAAS,CAAC,IAAY;YACrB,GAAG,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;QACrC,CAAC;QACD,WAAW;YACV,GAAG,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;YACzC,IAAI,UAAU;gBAAE,GAAG,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;QAC3D,CAAC;KACD,CAAC;AACH,CAAC"}

package/dist/extensions/forgecli/orchestrators/common/orchestrator-transcript-session.d.ts

@@ -0,0 +1,26 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { OrchestratorResult, OrchestratorStatus } from "../../lib/orchestrator-types.js";
+import { OrchestratorTranscriptWriter } from "../../subagent/orchestrator-transcript.js";
+/** Map a pipeline status to the orchestrator-transcript outcome vocabulary.
+ *  Shared by run-task and fix-bug (same status union). */
+export declare function transcriptOutcomeFor(status: OrchestratorStatus): "complete" | "halted" | "cancelled" | "error";
+/** Handle passed to the inner pipeline loop — exposes the live transcript
+ *  writer for structured phase-boundary records. */
+export interface OrchestratorTranscriptSession {
+    readonly writer: OrchestratorTranscriptWriter;
+}
+export interface WithOrchestratorTranscriptOpts {
+    cwd: string;
+    entityKind: "bug" | "task" | "sprint";
+    entityId: string;
+    ctx: ExtensionCommandContext;
+}
+/**
+ * Create the orchestrator transcript writer, intercept ctx.ui.notify so every
+ * notification is recorded, run `inner(session)`, then close the writer with
+ * the result's mapped outcome and surface its path on the result. Restores the
+ * original ctx.ui.notify in a finally.
+ */
+export declare function withOrchestratorTranscript<T extends OrchestratorResult & {
+    orchestratorTranscriptPath?: string;
+}>(opts: WithOrchestratorTranscriptOpts, inner: (session: OrchestratorTranscriptSession) => Promise<T>): Promise<T>;

package/dist/extensions/forgecli/orchestrators/common/orchestrator-transcript-session.js

@@ -0,0 +1,75 @@
+// orchestrator-transcript-session.ts — shared transcript-writing concern for
+// the orchestrator pipelines (run-task, fix-bug).
+//
+// Collapses three byte-identical duplications that previously lived in both
+// run-task.ts and fix-bug.ts:
+//   1. the ctx.ui.notify interception that records every notify line into the
+//      orchestrator transcript,
+//   2. the pipeline-wrapper dance (create writer → run inner → close with the
+//      mapped outcome → surface the file path), and
+//   3. the status→outcome mapping (transcriptOutcomeFor).
+//
+// Behavior contract preserved exactly:
+//   - The writer is created INSIDE this helper, so callers must run their
+//     config/preflight early-returns BEFORE calling withOrchestratorTranscript
+//     (a failed preflight must not create a transcript file).
+//   - On a clean run the inner loop records its own "complete" pipeline-end;
+//     OrchestratorTranscriptWriter.record() marks the log closed, so the
+//     trailing close() here is an idempotent no-op. On cancel/halt/fail the
+//     inner returns without a pipeline-end and this close() is the guarantee
+//     that the run is archived with its true outcome.
+//   - ctx.ui.notify is restored in a finally, even if inner throws.
+import { getOrchestratorTree } from "../../orchestrator-tree.js";
+import { OrchestratorTranscriptWriter } from "../../subagent/orchestrator-transcript.js";
+/** Map a pipeline status to the orchestrator-transcript outcome vocabulary.
+ *  Shared by run-task and fix-bug (same status union). */
+export function transcriptOutcomeFor(status) {
+    switch (status) {
+        case "completed":
+            return "complete";
+        case "cancelled":
+            return "cancelled";
+        case "halted":
+        case "escalated":
+            return "halted";
+        case "failed":
+            return "error";
+    }
+}
+/**
+ * Create the orchestrator transcript writer, intercept ctx.ui.notify so every
+ * notification is recorded, run `inner(session)`, then close the writer with
+ * the result's mapped outcome and surface its path on the result. Restores the
+ * original ctx.ui.notify in a finally.
+ */
+export async function withOrchestratorTranscript(opts, inner) {
+    const { cwd, entityKind, entityId, ctx } = opts;
+    const writer = new OrchestratorTranscriptWriter({ cwd, entityKind, entityId });
+    const tree = getOrchestratorTree();
+    const origNotify = ctx.ui.notify.bind(ctx.ui);
+    ctx.ui.notify = ((msg, level) => {
+        origNotify(msg, level);
+        const text = typeof msg === "string" ? msg : String(msg);
+        writer.record({
+            kind: "notify",
+            ts: new Date().toISOString(),
+            level: (level ?? "info"),
+            message: text,
+        });
+        // Mirror the orchestrator's decision log onto its root node so the
+        // dashboard surfaces it. Leaf phase nodes carry subagent tool-call
+        // activity (via the viewport observer); this root node (entityId) carries
+        // the orchestrator's own narrative — gates, verdicts, escalations, halts.
+        tree.appendTail(entityId, text, level === "error" || level === "warning" ? { warning: true } : undefined);
+    });
+    try {
+        const result = await inner({ writer });
+        writer.close(transcriptOutcomeFor(result.status), result.lastError);
+        result.orchestratorTranscriptPath = writer.filePath;
+        return result;
+    }
+    finally {
+        ctx.ui.notify = origNotify;
+    }
+}
+//# sourceMappingURL=orchestrator-transcript-session.js.map

package/dist/extensions/forgecli/orchestrators/common/orchestrator-transcript-session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator-transcript-session.js","sourceRoot":"","sources":["../../../../../src/extensions/forgecli/orchestrators/common/orchestrator-transcript-session.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,kDAAkD;AAClD,EAAE;AACF,4EAA4E;AAC5E,8BAA8B;AAC9B,8EAA8E;AAC9E,gCAAgC;AAChC,8EAA8E;AAC9E,oDAAoD;AACpD,0DAA0D;AAC1D,EAAE;AACF,uCAAuC;AACvC,0EAA0E;AAC1E,+EAA+E;AAC/E,8DAA8D;AAC9D,6EAA6E;AAC7E,yEAAyE;AACzE,4EAA4E;AAC5E,6EAA6E;AAC7E,sDAAsD;AACtD,oEAAoE;AAKpE,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,4BAA4B,EAAE,MAAM,2CAA2C,CAAC;AAEzF;0DAC0D;AAC1D,MAAM,UAAU,oBAAoB,CAAC,MAA0B;IAC9D,QAAQ,MAAM,EAAE,CAAC;QAChB,KAAK,WAAW;YACf,OAAO,UAAU,CAAC;QACnB,KAAK,WAAW;YACf,OAAO,WAAW,CAAC;QACpB,KAAK,QAAQ,CAAC;QACd,KAAK,WAAW;YACf,OAAO,QAAQ,CAAC;QACjB,KAAK,QAAQ;YACZ,OAAO,OAAO,CAAC;IACjB,CAAC;AACF,CAAC;AAeD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAE9C,IAAoC,EAAE,KAA6D;IACpG,MAAM,EAAE,GAAG,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IAChD,MAAM,MAAM,GAAG,IAAI,4BAA4B,CAAC,EAAE,GAAG,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAC,CAAC;IAC/E,MAAM,IAAI,GAAG,mBAAmB,EAAE,CAAC;IACnC,MAAM,UAAU,GAAyB,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACpE,GAAG,CAAC,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,GAAW,EAAE,KAAwC,EAAE,EAAE;QAC1E,UAAU,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACvB,MAAM,IAAI,GAAG,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACzD,MAAM,CAAC,MAAM,CAAC;YACb,IAAI,EAAE,QAAQ;YACd,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YAC5B,KAAK,EAAE,CAAC,KAAK,IAAI,MAAM,CAA0C;YACjE,OAAO,EAAE,IAAI;SACb,CAAC,CAAC;QACH,mEAAmE;QACnE,mEAAmE;QACnE,0EAA0E;QAC1E,0EAA0E;QAC1E,IAAI,CAAC,UAAU,CAAC,QAAQ,EAAE,IAAI,EAAE,KAAK,KAAK,OAAO,IAAI,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAC3G,CAAC,CAAyB,CAAC;IAE3B,IAAI,CAAC;QACJ,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;QACvC,MAAM,CAAC,KAAK,CAAC,oBAAoB,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC;QACpE,MAAM,CAAC,0BAA0B,GAAG,MAAM,CAAC,QAAQ,CAAC;QACpD,OAAO,MAAM,CAAC;IACf,CAAC;YAAS,CAAC;QACV,GAAG,CAAC,EAAE,CAAC,MAAM,GAAG,UAAU,CAAC;IAC5B,CAAC;AACF,CAAC"}

package/dist/extensions/forgecli/orchestrators/common/summary-recovery.d.ts

@@ -0,0 +1,24 @@
+export interface SummaryRecoveryResult {
+    /** Always true — the recovery was attempted (caller decides when to call). */
+    attempted: boolean;
+    /** True only when set-summary exited 0 (sidecar present + schema-valid). */
+    ok: boolean;
+    /** Captured stderr for debug logging. */
+    stderr: string;
+}
+export interface RecoverPhaseSummaryParams {
+    /** Absolute path to the project's store-cli.cjs. */
+    storeCli: string;
+    /** Task or bug record id whose summary is being registered. */
+    entityId: string;
+    /** Canonical `summaries.*` store key (e.g. "plan", "code_review"). */
+    summaryKey: string;
+    cwd: string;
+    /** "set-summary" (task, default) or "set-bug-summary" (bug). */
+    summaryVerb?: "set-summary" | "set-bug-summary";
+}
+/**
+ * Attempt to register a phase's already-written {PHASE}-SUMMARY.json sidecar
+ * into the store via store-cli. Returns ok=true only when the verb exits 0.
+ */
+export declare function recoverPhaseSummary(p: RecoverPhaseSummaryParams): SummaryRecoveryResult;

package/dist/extensions/forgecli/orchestrators/common/summary-recovery.js

@@ -0,0 +1,37 @@
+// summary-recovery.ts — deterministic phase-completion recovery for the
+// orchestrator pipelines (forge-engineering#41).
+//
+// Failure mode: a phase's subagent finalizes in two steps —
+//   1. `forge_artifact write <phase>-summary` → writes the {PHASE}-SUMMARY.json
+//      sidecar to the record's path on disk, and
+//   2. `forge_store set-summary <id> <phaseKey>` → ingests that sidecar into
+//      `record.summaries.<phaseKey>`.
+// Under turn-budget pressure (or with a weaker model) the subagent stops after
+// step 1 with stopReason=stop, silently eliding step 2. The orchestrator then
+// reads the store, finds no verdict, and hard-fails the phase — forcing the
+// operator to rerun the whole task even though the work artifact is on disk.
+//
+// Recovery: the orchestrator registers the subagent's already-authored sidecar
+// itself by running step 2 (store-cli set-summary / set-bug-summary — the
+// sidecar is auto-resolved from record.path when the file arg is omitted), then
+// re-checks its gate. This does NOT fabricate a verdict (IL10): the verdict
+// content is the subagent's own sidecar; the orchestrator only registers it,
+// exactly as it already emits phase events on the subagent's behalf. When the
+// sidecar is genuinely absent, set-summary exits non-zero and the caller falls
+// through to the existing hard-fail + halt advisor.
+//
+// IL6 — external invocation via spawnSync argv array, no shell interpolation.
+import { spawnSync } from "node:child_process";
+/**
+ * Attempt to register a phase's already-written {PHASE}-SUMMARY.json sidecar
+ * into the store via store-cli. Returns ok=true only when the verb exits 0.
+ */
+export function recoverPhaseSummary(p) {
+    const verb = p.summaryVerb ?? "set-summary";
+    const r = spawnSync("node", [p.storeCli, verb, p.entityId, p.summaryKey], {
+        cwd: p.cwd,
+        encoding: "utf8",
+    });
+    return { attempted: true, ok: r.status === 0, stderr: (r.stderr ?? "").toString() };
+}
+//# sourceMappingURL=summary-recovery.js.map

package/dist/extensions/forgecli/orchestrators/common/summary-recovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"summary-recovery.js","sourceRoot":"","sources":["../../../../../src/extensions/forgecli/orchestrators/common/summary-recovery.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,iDAAiD;AACjD,EAAE;AACF,4DAA4D;AAC5D,gFAAgF;AAChF,iDAAiD;AACjD,6EAA6E;AAC7E,sCAAsC;AACtC,+EAA+E;AAC/E,8EAA8E;AAC9E,4EAA4E;AAC5E,6EAA6E;AAC7E,EAAE;AACF,+EAA+E;AAC/E,0EAA0E;AAC1E,gFAAgF;AAChF,4EAA4E;AAC5E,6EAA6E;AAC7E,8EAA8E;AAC9E,+EAA+E;AAC/E,oDAAoD;AACpD,EAAE;AACF,8EAA8E;AAE9E,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAuB/C;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,CAA4B;IAC/D,MAAM,IAAI,GAAG,CAAC,CAAC,WAAW,IAAI,aAAa,CAAC;IAC5C,MAAM,CAAC,GAAG,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,UAAU,CAAC,EAAE;QACzE,GAAG,EAAE,CAAC,CAAC,GAAG;QACV,QAAQ,EAAE,MAAM;KAChB,CAAC,CAAC;IACH,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC;AACrF,CAAC"}

package/dist/extensions/forgecli/orchestrators/fix-bug.d.ts

@@ -1,93 +1,10 @@
-import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-import { type ForgeToolDefs } from "../forge-tools.js";
-import { getSessionRegistry } from "../session-registry.js";
-import { type PhaseDescriptor } from "./run-task.js";
-export declare const BUG_PHASES: PhaseDescriptor[];
+export { BUG_PHASES, BUG_TYPE_TOKENS, postTriageTransitions } from "./bug/bug-phases.js";
+export { type RouteAfterTriageOutcome, type RouteAfterTriageParams, routeAfterTriage, } from "./bug/bug-triage-routing.js";
 export { BUG_SUMMARY_KEY_BY_ROLE } from "../subagent/phase-summary-map.js";
-export declare const BUG_TYPE_TOKENS: Record<string, {
-    pass: string;
-    fail: string;
-}>;
-export interface RunBugState {
-    bugId: string;
-    phaseIndex: number;
-    iterationCounts: Record<string, number>;
-    halted: boolean;
-    /** Set on cancellation so the resume prompt says "cancelled" vs "halted". */
-    status?: "cancelled" | "halted" | "running";
-    lastError?: string;
-    savedAt: string;
-}
-export declare function readBugState(cwd: string, bugId: string, sessionId?: string): RunBugState | null;
-export declare function writeBugState(cwd: string, state: RunBugState): void;
-export declare function deleteBugState(cwd: string, bugId: string): void;
-export declare function isBugStateStale(state: RunBugState): boolean;
-export interface BugRecord {
-    bugId?: string;
-    status?: string;
-    summaries?: Record<string, unknown>;
-    [key: string]: unknown;
-}
-export declare function readBugRecord(bugId: string, storeCli: string, cwd: string): BugRecord | null;
-export declare function computeNextBugId(bugIds: string[], prefix: string): string;
-export declare function assignNextBugId(storeCli: string, cwd: string, prefix?: string): string;
-export declare function extractBugIdFromReportText(text: string, prefix: string): string | null;
-export declare function preCreateBug(bugId: string, title: string, storeCli: string, cwd: string): boolean;
-type BugVerdict = "approved" | "revision" | "n/a" | "missing";
-export declare function readBugVerdict(bugRecord: BugRecord | null, phaseRole: string, summaryKeyByRole: Record<string, string | null>): BugVerdict;
-export declare function composeBugBody(subWorkflowMd: string, bugId: string, phaseRole: string, bugStatusBeforePhase?: string, summariesBlock?: string): string;
-/**
- * Scan tool_execution_end events to extract the bugId written by a triage
- * subagent. Returns the LAST matching tool call's bugId, or null if none found.
- *
- * In pi runtime, the forge_store tool is registered as "forge_store" (not
- * "store-cli"). In Claude Code runtime, subagents may shell out via Bash.
- * This function covers all three paths.
- */
-export declare function extractBugIdFromEvents(events: Array<{
-    toolName?: string;
-    result?: unknown;
-}>, prefix?: string): string | null;
-export type RunBugPipelineStatus = "completed" | "halted" | "escalated" | "failed" | "cancelled";
-export interface RunBugPipelineResult {
-    status: RunBugPipelineStatus;
-    lastPhaseIndex: number;
-    iterationCounts: Record<string, number>;
-    lastError?: string;
-    model?: string;
-    provider?: string;
-    /**
-     * Project-local orchestrator JSONL path for this run. Callers hand it to
-     * archiveRun() to mirror the run into the central transcript archive.
-     * Unset only when the pipeline returned before the writer was created.
-     */
-    orchestratorTranscriptPath?: string;
-}
-export interface RunBugPipelineOptions {
-    bugId: string;
-    /** Original free-form text argument when creating a new bug (not a FORGE-BUG-NNN ID).
-     *  Passed to triage-phase subagent so it can create the bug with a meaningful description. */
-    originalArg?: string;
-    /** Whether this is a new bug (free-form text) vs. an existing FORGE-BUG-NNN ID. */
-    isNewBug?: boolean;
-    cwd: string;
-    ctx: ExtensionCommandContext;
-    forgeRoot: string;
-    storeCli: string;
-    preflightGate: string;
-    registry: ReturnType<typeof getSessionRegistry>;
-    resumeFromState?: RunBugState;
-    /**
-     * Optional AbortSignal from SessionRegistry. When provided, the pipeline
-     * checks signal.aborted between phases and passes the signal to
-     * runForgeSubagent so in-flight subagents can be aborted.
-     */
-    signal?: AbortSignal;
-    forgeToolDefs?: ForgeToolDefs;
-}
-export declare function runBugPipeline(opts: RunBugPipelineOptions): Promise<RunBugPipelineResult>;
-export interface RegisterFixBugOptions {
-    cwd?: string;
-    forgeToolDefs?: ForgeToolDefs;
-}
-export declare function registerFixBug(pi: ExtensionAPI, options?: RegisterFixBugOptions): void;
+export { deleteBugState, isBugStateStale, readBugState, type RunBugState, writeBugState, } from "./bug/bug-state.js";
+export { assignNextBugId, type BugRecord, computeNextBugId, extractBugIdFromEvents, extractBugIdFromReportText, preCreateBug, readBugRecord, } from "./bug/bug-id.js";
+export { readBugVerdict } from "./bug/bug-verdict.js";
+export { composeBugBody } from "./bug/bug-body.js";
+export { type RunBugPipelineOptions, type RunBugPipelineResult, type RunBugPipelineStatus, } from "./bug/run-bug-types.js";
+export { runBugPipeline } from "./bug/run-bug-pipeline.js";
+export { type RegisterFixBugOptions, registerFixBug } from "./bug/run-bug-command.js";