substrate-ai 0.20.64 → 0.20.65

package/dist/modules/interactive-prompt/index.d.ts

@@ -0,0 +1,86 @@
+//#region src/modules/interactive-prompt/index.d.ts
+/**
+ * Interactive Prompt — Phase D Story 54-3 (2026-04-05): original spec.
+ * Epic 72: Decision Router that triggers prompts (Story 72-1 / 72-2).
+ * Story 73-1: Recovery Engine that the prompt collects responses for.
+ *
+ * Presents an interactive numbered-choice prompt when the Decision Router halts
+ * execution, and writes a filesystem notification file before prompting so
+ * external monitors can detect the halt immediately.
+ *
+ * Non-interactive mode (SUBSTRATE_NON_INTERACTIVE=true or
+ * decisionContext.nonInteractive=true) bypasses stdin, applies the default
+ * action, and emits a decision:halt-skipped-non-interactive event for audit.
+ */
+/**
+ * Context provided to the interactive prompt when a halt is triggered.
+ * Consumed by the Recovery Engine (Story 73-1) to route the operator's choice.
+ */
+interface DecisionContext {
+  /** Pipeline run ID — resolved from manifest-read if not provided. */
+  runId?: string;
+  /** Decision type that triggered the halt (e.g., 'cost-ceiling-exhausted'). */
+  decisionType: string;
+  /** Severity of the halt (e.g., 'critical', 'fatal'). */
+  severity: string;
+  /** Human-readable summary of the halt condition to display to the operator. */
+  summary: string;
+  /** Default action to apply if operator presses Enter or is in non-interactive mode. */
+  defaultAction: string;
+  /** List of choice labels (e.g., ['retry', 'abort']). Used in the notification file. */
+  choices: string[];
+  /** When true, bypass stdin and return defaultAction immediately (AC4). */
+  nonInteractive?: boolean;
+  /** Optional event emitter callback for decision:halt-skipped-non-interactive. */
+  onHaltSkipped?: (payload: HaltSkippedPayload) => void;
+}
+/**
+ * Payload emitted when a halt is skipped under non-interactive mode (AC4).
+ * Matches OrchestratorEvents['decision:halt-skipped-non-interactive'].
+ */
+interface HaltSkippedPayload {
+  runId: string;
+  decisionType: string;
+  severity: string;
+  defaultAction: string;
+  reason: string;
+}
+/**
+ * The operator's chosen action, returned by runInteractivePrompt.
+ * Maps choice 1–4 to the corresponding action string.
+ */
+type OperatorAction = string | 'retry-with-custom-context' | 'propose-re-scope' | 'abort-run';
+/**
+ * Shape written to .substrate/notifications/<runId>-<timestamp>.json.
+ * Exported so callers (e.g., report.ts) can parse typed notifications.
+ */
+interface HaltNotification {
+  runId: string;
+  timestamp: string;
+  decisionType: string;
+  severity: string;
+  context: Record<string, unknown>;
+  choices: string[];
+  operatorChoice: string | null;
+}
+/**
+ * Run the interactive prompt for a Decision Router halt.
+ *
+ * Workflow:
+ * 1. Resolve run ID (from context or manifest-read.ts).
+ * 2. Write notification file BEFORE prompting (AC5).
+ * 3. If non-interactive mode, emit halt-skipped event and return default (AC4).
+ * 4. If stdin is not a TTY, log warning and treat as non-interactive (defensive).
+ * 5. Render the numbered-choice prompt (AC2).
+ * 6. Read one line from stdin via readline.createInterface (AC3).
+ * 7. Parse and return the chosen action.
+ * 8. Update notification file with the operator's choice (AC5).
+ *
+ * @param decisionContext - Decision context from the Decision Router halt.
+ * @returns The operator's chosen action string.
+ */
+declare function runInteractivePrompt(decisionContext: DecisionContext): Promise<string>; //#endregion
+
+//# sourceMappingURL=index.d.ts.map
+export { DecisionContext, HaltNotification, HaltSkippedPayload, OperatorAction, runInteractivePrompt };
+//# sourceMappingURL=index.d.ts.map

package/dist/modules/interactive-prompt/index.js

@@ -0,0 +1,6 @@
+import "../../logger-KeHncl-f.js";
+import "../../dist-K_RRWnBX.js";
+import "../../manifest-read-DDkXC3L_.js";
+import { runInteractivePrompt } from "../../interactive-prompt-C7wpE4z4.js";
+
+export { runInteractivePrompt };

package/dist/recovery-engine-BKGBeBnW.js

@@ -0,0 +1,281 @@
+import { createLogger } from "./logger-KeHncl-f.js";
+import { WorkGraphRepository } from "./work-graph-repository-DZyJv5pV.js";
+import { randomUUID } from "node:crypto";
+
+//#region src/modules/recovery-engine/index.ts
+const logger = createLogger("recovery-engine");
+/**
+* Root causes that map to Tier A (auto-retry) when retry budget is available.
+* Transient failures that can be resolved by re-dispatching with additional context.
+*/
+const RETRY_ROOT_CAUSES = new Set([
+	"build-failure",
+	"test-coverage-gap",
+	"ac-missing-evidence",
+	"missing-import"
+]);
+/**
+* Root causes that always map to Tier B (re-scope proposal) regardless of budget.
+* Structural failures that cannot be resolved by retrying the same approach.
+*/
+const PROPOSE_ROOT_CAUSES = new Set([
+	"scope-violation",
+	"fundamental-design-error",
+	"cross-story-contract-mismatch"
+]);
+/**
+* Root causes that map to Tier C (halt) — requires operator intervention.
+*/
+const HALT_ROOT_CAUSES = new Set([
+	"halt-policy",
+	"irreversible",
+	"security-violation",
+	"data-loss-risk"
+]);
+/**
+* Classify a failure into a recovery action tier.
+*
+* Pure function — no imports from I/O modules, no side effects.
+* The action handler (`runRecoveryEngine`) owns all I/O.
+*
+* Classification rules:
+*   1. HALT root causes → 'halt' always
+*   2. PROPOSE root causes → 'propose' always (structural, not retry-able)
+*   3. RETRY root causes:
+*      - budget.remaining > 0 → 'retry'
+*      - budget.remaining <= 0 → 'propose' (exhausted, escalate)
+*   4. Unknown root cause → 'propose' (safe default)
+*
+* @param failure - Failure with rootCause field
+* @param budget  - Retry budget with remaining count
+* @returns 'retry' | 'propose' | 'halt'
+*/
+function classifyRecoveryAction(failure, budget) {
+	const { rootCause } = failure;
+	if (HALT_ROOT_CAUSES.has(rootCause) || rootCause.startsWith("halt-")) return "halt";
+	if (PROPOSE_ROOT_CAUSES.has(rootCause)) return "propose";
+	if (RETRY_ROOT_CAUSES.has(rootCause)) {
+		if (budget.remaining > 0) return "retry";
+		return "propose";
+	}
+	return "propose";
+}
+/**
+* Query work-graph dependency edges to find stories that depend on any
+* proposed story. Used for Tier B back-pressure when NOT in linear mode.
+*
+* @param proposedStoryKeys - Story keys currently in pending_proposals
+* @param pendingStoryKeys  - Story keys still pending / dispatching
+* @param adapter           - DatabaseAdapter for wg_stories / story_dependencies
+* @returns { pause: string[], continue: string[] }
+*/
+async function computeDependencyAwarePause(proposedStoryKeys, pendingStoryKeys, adapter) {
+	if (pendingStoryKeys.length === 0) return {
+		pause: [],
+		continue: []
+	};
+	try {
+		const wgRepo = new WorkGraphRepository(adapter);
+		const deps = await wgRepo.getDependencyEdges();
+		const proposedSet = new Set(proposedStoryKeys);
+		const pause = [];
+		const continueKeys = [];
+		for (const pendingKey of pendingStoryKeys) {
+			const blockers = deps.filter((d) => d.story_key === pendingKey).map((d) => d.depends_on);
+			const isBlocked = blockers.some((b) => proposedSet.has(b));
+			if (isBlocked) pause.push(pendingKey);
+			else continueKeys.push(pendingKey);
+		}
+		return {
+			pause,
+			continue: continueKeys
+		};
+	} catch (err) {
+		logger.warn({ err: err instanceof Error ? err.message : String(err) }, "Work-graph dependency query failed — falling back to pause-all for back-pressure");
+		return {
+			pause: pendingStoryKeys,
+			continue: []
+		};
+	}
+}
+/**
+* Recovery Engine action handler.
+*
+* Consumes a halt decision (failure + budget) and applies tiered recovery:
+*
+*   Tier A (retry): emits recovery:tier-a-retry, returns enriched prompt for re-dispatch.
+*   Tier B (propose): appends Proposal to RunManifest.pending_proposals, applies back-pressure.
+*   Tier C (halt): emits recovery:tier-c-halt, returns halt action for Decision Router.
+*
+* Safety valve: if pending_proposals.length >= 5 after any Tier B append,
+* emits pipeline:halted-pending-proposals and returns halt-entire-run.
+*
+* Back-pressure:
+*   >= 2 proposals + work graph: pauses dependent stories, continues independent ones.
+*   >= 2 proposals + linear mode: pauses ALL remaining dispatches.
+*
+* Idempotency: re-invoking on a story already in pending_proposals is a no-op
+* (handled inside RunManifest.appendProposal via storyKey deduplication).
+*
+* Canonical helper discipline: all manifest reads/writes via RunManifest class.
+* No direct JSON file access. No new aggregate manifest formats.
+*
+* @param input - Recovery engine input (see RecoveryEngineInput)
+* @returns Recovery action result for the orchestrator to act on
+*/
+async function runRecoveryEngine(input) {
+	const { runId, storyKey, failure, budget, bus, manifest, adapter, engine, pendingStoryKeys = [] } = input;
+	const action = classifyRecoveryAction(failure, budget);
+	if (action === "retry") {
+		const attempt = budget.max - budget.remaining + 1;
+		const retryBudgetRemaining = budget.remaining - 1;
+		const diagnosisParts = [];
+		if (failure.diagnosis) diagnosisParts.push(`## Recovery Diagnosis\n\n${failure.diagnosis}`);
+		if (failure.findings && failure.findings.length > 0) diagnosisParts.push(`## Prior Attempt Findings\n\n${failure.findings.map((f, i) => `${i + 1}. ${typeof f === "string" ? f : JSON.stringify(f)}`).join("\n")}`);
+		const enrichedPrompt = diagnosisParts.length > 0 ? diagnosisParts.join("\n\n") + "\n\n---\n\n" : void 0;
+		bus.emit("recovery:tier-a-retry", {
+			runId,
+			storyKey,
+			rootCause: failure.rootCause,
+			attempt,
+			retryBudgetRemaining
+		});
+		logger.info({
+			runId,
+			storyKey,
+			rootCause: failure.rootCause,
+			attempt,
+			retryBudgetRemaining
+		}, "Recovery Engine: Tier A retry dispatched");
+		return {
+			action: "retry",
+			attempt,
+			retryBudgetRemaining,
+			...enrichedPrompt !== void 0 ? { enrichedPrompt } : {}
+		};
+	}
+	if (action === "halt") {
+		bus.emit("recovery:tier-c-halt", {
+			runId,
+			storyKey,
+			rootCause: failure.rootCause
+		});
+		logger.warn({
+			runId,
+			storyKey,
+			rootCause: failure.rootCause
+		}, "Recovery Engine: Tier C halt — operator intervention required");
+		return { action: "halt" };
+	}
+	const attempts = budget.max - budget.remaining;
+	const suggestedAction = buildSuggestedAction(failure.rootCause, storyKey);
+	const blastRadius = [];
+	const proposal = {
+		id: randomUUID(),
+		created_at: new Date().toISOString(),
+		description: `Recovery Engine: ${failure.rootCause} on story ${storyKey} after ${attempts} attempt(s)`,
+		type: "escalate",
+		story_key: storyKey,
+		storyKey,
+		rootCause: failure.rootCause,
+		attempts,
+		suggestedAction,
+		blastRadius
+	};
+	await manifest.appendProposal(proposal).catch((err) => {
+		logger.warn({
+			err: err instanceof Error ? err.message : String(err),
+			storyKey
+		}, "Recovery Engine: appendProposal failed — pipeline continues");
+	});
+	let pendingProposals = [];
+	try {
+		const manifestData = await manifest.read();
+		pendingProposals = manifestData.pending_proposals;
+	} catch (err) {
+		logger.warn({ err: err instanceof Error ? err.message : String(err) }, "Recovery Engine: manifest read failed after appendProposal");
+	}
+	const pendingProposalsCount = pendingProposals.length;
+	if (pendingProposalsCount >= 5) {
+		bus.emit("pipeline:halted-pending-proposals", {
+			runId,
+			pendingProposalsCount
+		});
+		logger.error({
+			runId,
+			pendingProposalsCount
+		}, "Recovery Engine: safety valve triggered — >= 5 pending proposals, halting run");
+		return {
+			action: "halt-entire-run",
+			pendingProposalsCount
+		};
+	}
+	bus.emit("recovery:tier-b-proposal", {
+		runId,
+		storyKey,
+		rootCause: failure.rootCause,
+		attempts,
+		suggestedAction,
+		blastRadius
+	});
+	logger.info({
+		runId,
+		storyKey,
+		rootCause: failure.rootCause,
+		pendingProposalsCount
+	}, "Recovery Engine: Tier B proposal appended");
+	if (pendingProposalsCount >= 2) {
+		const isLinearMode = engine === "linear";
+		if (isLinearMode) {
+			logger.info({
+				runId,
+				pendingProposalsCount
+			}, "Recovery Engine: linear mode back-pressure — pausing all pending dispatches");
+			return {
+				action: "propose",
+				storyKey,
+				pendingProposalsCount,
+				pauseAll: true
+			};
+		}
+		const proposedStoryKeys = pendingProposals.map((p) => p.storyKey ?? p.story_key).filter((k) => k !== void 0);
+		const { pause, continue: continueKeys } = await computeDependencyAwarePause(proposedStoryKeys, pendingStoryKeys, adapter);
+		logger.info({
+			runId,
+			pendingProposalsCount,
+			pause,
+			continue: continueKeys
+		}, "Recovery Engine: work-graph back-pressure computed");
+		return {
+			action: "propose",
+			storyKey,
+			pendingProposalsCount,
+			pause,
+			continue: continueKeys
+		};
+	}
+	return {
+		action: "propose",
+		storyKey,
+		pendingProposalsCount
+	};
+}
+/**
+* Build a human-readable suggested action for the operator based on root cause.
+*/
+function buildSuggestedAction(rootCause, storyKey) {
+	switch (rootCause) {
+		case "scope-violation": return `Split story ${storyKey} into smaller stories with narrower scope`;
+		case "fundamental-design-error": return `Revisit the architecture for story ${storyKey} — design approach is not viable`;
+		case "cross-story-contract-mismatch": return `Reconcile interface contracts for story ${storyKey} with dependent stories`;
+		case "build-failure": return `Fix build errors for story ${storyKey} — retry budget exhausted`;
+		case "test-coverage-gap": return `Add missing test coverage for story ${storyKey}`;
+		case "ac-missing-evidence": return `Story ${storyKey} lacks acceptance criteria evidence — revisit scope or provide evidence`;
+		case "missing-import": return `Fix missing import dependencies for story ${storyKey}`;
+		default: return `Manual review required for story ${storyKey}: ${rootCause}`;
+	}
+}
+
+//#endregion
+export { classifyRecoveryAction, runRecoveryEngine };
+//# sourceMappingURL=recovery-engine-BKGBeBnW.js.map

package/dist/{routing-0ykvBl_4.js → routing-CzF0p6lI.js}

@@ -1,4 +1,4 @@
-import { ModelRoutingConfigSchema, ProviderPolicySchema, RoutingConfigError, RoutingRecommender, RoutingResolver, RoutingTelemetry, RoutingTokenAccumulator, RoutingTuner, TASK_TYPE_PHASE_MAP, getModelTier, loadModelRoutingConfig } from "./dist-W2emvN3F.js";
-import "./routing-CcBOCuC9.js";
+import { ModelRoutingConfigSchema, ProviderPolicySchema, RoutingConfigError, RoutingRecommender, RoutingResolver, RoutingTelemetry, RoutingTokenAccumulator, RoutingTuner, TASK_TYPE_PHASE_MAP, getModelTier, loadModelRoutingConfig } from "./dist-K_RRWnBX.js";
+import "./routing-DFxoKHDt.js";
 
 export { loadModelRoutingConfig };

package/dist/run-DX95j4_D.js

@@ -0,0 +1,14 @@
+import "./health-DC3y-sR6.js";
+import "./logger-KeHncl-f.js";
+import "./helpers-CElYrONe.js";
+import "./dist-K_RRWnBX.js";
+import "./manifest-read-DDkXC3L_.js";
+import { normalizeGraphSummaryToStatus, registerRunCommand, resolveMaxReviewCycles, resolveProbeAuthorStateIntegrating, runRunAction, wireNdjsonEmitter } from "./run-DzB4rgkj.js";
+import "./routing-DFxoKHDt.js";
+import "./work-graph-repository-DZyJv5pV.js";
+import "./decisions-CzSIEeGP.js";
+import "./decision-router-DblHY8se.js";
+import "./interactive-prompt-C7wpE4z4.js";
+import "./recovery-engine-BKGBeBnW.js";
+
+export { runRunAction };