@quantmind-br/pi-goal-x 0.0.0-stage → 0.35.1

package/extensions/goal-live-retention.ts

@@ -0,0 +1,239 @@
+import { createHash } from "node:crypto";
+import { asRecord } from "./goal-record.ts";
+
+/**
+ * Prefix-stable retention for request-only goal-state tails.
+ *
+ * The context hook appends live goal state to every provider request without
+ * persisting it. When the next request arrives, the completed assistant turn
+ * occupies the position where the previous tail sat, so request N is no
+ * longer a prefix of request N+1 and implicit prompt caches (OpenAI Responses
+ * / Chat Completions, which carry no explicit marker) freeze at the first
+ * injection point.
+ *
+ * This module makes each request a true prefix of the next: previously sent
+ * tails are re-inserted verbatim at their recorded anchor (the session length
+ * when they were emitted), the whole preceding history is verified unchanged
+ * by digest, and only genuinely new tail content is appended. Identical
+ * content across repeated requests appends nothing, so tool loops and idle
+ * re-requests cost zero growth. A stable-state change, any history rewrite
+ * (compaction, resume, session-tree moves, filter changes, middle-message
+ * edits), an unsafe insertion point, or overflow all perform one documented
+ * full reset instead of silently shifting the prefix or corrupting message
+ * structure.
+ *
+ * Task snapshots and usage counters are separate tail kinds. Each is appended
+ * only when it differs from its previous emission, so task progress extends
+ * the prefix instead of resetting it; only the policy block forces a reset.
+ */
+
+export const LIVE_CONTEXT_TYPE = "pi-goal-live-context";
+
+export type LiveTailKind = "goal-state" | "goal-tasks" | "goal-counters";
+
+/** A request-only tail message. Never persisted; the hook replays it per request. */
+export interface LiveMessage {
+	role: "custom";
+	customType: typeof LIVE_CONTEXT_TYPE;
+	content: string;
+	display: false;
+	timestamp: 0;
+}
+
+/**
+ * Upper bound on retained tails per session. Retained tails are small (the
+ * per-turn volatile counters), so the steady-state wire overhead stays near
+ * a few kilobytes; exceeding the bound performs a single full reset, i.e. at
+ * most one prefix break per MAX_RETAINED_LIVE_TAILS state changes.
+ */
+export const MAX_RETAINED_LIVE_TAILS = 32;
+
+/** Upper bound on concurrently tracked sessions (parent plus isolated runs). */
+export const MAX_TRACKED_SESSIONS = 16;
+/** Extra historical observations, excluding the single current policy block. */
+export const MAX_RETAINED_COUNTER_BYTES = 4096;
+/**
+ * Retained task snapshots. Each task transition appends one snapshot, so a
+ * long task run stays prefix-stable until this bound forces a single reset.
+ */
+export const MAX_RETAINED_TASK_BYTES = 16_384;
+
+export interface FreshLiveTails {
+	state: string;
+	tasks?: string | undefined;
+	counters?: string | undefined;
+}
+
+interface LiveBlock {
+	content: string;
+	kind: LiveTailKind;
+}
+
+interface RetainedTail extends LiveBlock {
+	anchorIndex: number;
+	anchorFingerprint: string | null;
+}
+
+interface SessionRetention {
+	tails: RetainedTail[];
+	lastFresh: FreshLiveTails | undefined;
+	/** Digest of every base message at the last apply; any earlier rewrite resets. */
+	baseFingerprints: Array<string | null>;
+}
+
+function freshBlocks(fresh: FreshLiveTails): LiveBlock[] {
+	const blocks: LiveBlock[] = [{ content: fresh.state, kind: "goal-state" }];
+	if (fresh.tasks) blocks.push({ content: fresh.tasks, kind: "goal-tasks" });
+	if (fresh.counters !== undefined) blocks.push({ content: fresh.counters, kind: "goal-counters" });
+	return blocks;
+}
+
+function kindBytes(blocks: readonly LiveBlock[], kind: LiveTailKind): number {
+	return blocks.reduce((n, block) => block.kind === kind ? n + Buffer.byteLength(block.content) : n, 0);
+}
+
+/** Full-message digest, or null (never a match) when serialization fails. */
+function fingerprintMessage(message: unknown): string | null {
+	try {
+		const serialized = JSON.stringify(message) ?? "undefined";
+		return createHash("sha256").update(serialized).digest("base64");
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Tool results must stay adjacent to the call they answer, so a retained tail
+ * may never be inserted directly before one. Covers the Pi session role
+ * (`toolResult`), the provider wire role (`tool`, as seen by marker
+ * relocation), and result-bearing content blocks in either vocabulary — the
+ * call side needs no guard since inserting before a call keeps the pair
+ * adjacent.
+ */
+function splitsToolBatch(next: unknown): boolean {
+	const record = asRecord(next);
+	const role = record?.role;
+	if (role === "toolResult" || role === "tool") return true;
+	const content = record?.content;
+	if (Array.isArray(content)) {
+		for (const block of content) {
+			const entry = asRecord(block);
+			if (!entry) continue;
+			const type = typeof entry.type === "string" ? entry.type : "";
+			if (type === "tool_result" || type === "toolResult") return true;
+			if ("toolCallId" in entry || "toolUseId" in entry) return true;
+		}
+	}
+	return false;
+}
+
+function makeLiveMessage(content: string): LiveMessage {
+	return {
+		role: "custom",
+		customType: LIVE_CONTEXT_TYPE,
+		content,
+		display: false,
+		timestamp: 0,
+	};
+}
+
+export class LiveTailRetention {
+	private readonly sessions = new Map<string, SessionRetention>();
+
+	apply<T>(sessionKey: string, base: readonly T[], fresh: FreshLiveTails | null): { messages: Array<T | LiveMessage>; transientContents: string[] } {
+		if (fresh === null) {
+			this.sessions.delete(sessionKey);
+			return { messages: [...base], transientContents: [] };
+		}
+		// Hash each message once per request. Extensions may reuse and mutate
+		// message objects, so object identity cannot cache a digest across requests.
+		const fingerprints = base.map(fingerprintMessage);
+		let session = this.sessions.get(sessionKey);
+		if (!session) {
+			session = { tails: [], lastFresh: undefined, baseFingerprints: [] };
+			if (this.sessions.size >= MAX_TRACKED_SESSIONS) {
+				const oldest = this.sessions.keys().next();
+				if (!oldest.done) this.sessions.delete(oldest.value);
+			}
+			this.sessions.set(sessionKey, session);
+		}
+		const reset = () => {
+			session!.tails = [];
+			session!.lastFresh = undefined;
+			session!.baseFingerprints = [];
+		};
+		// A changed state block supersedes every previously sent tail: start
+		// fresh rather than leave a stale objective or a cancelled scheduling
+		// instruction lingering mid-history. A dropped task snapshot or counter
+		// block resets too, so its last copy never reads as the current one.
+		if (session.lastFresh !== undefined && (session.lastFresh.state !== fresh.state
+			|| (session.lastFresh.tasks !== undefined && !fresh.tasks)
+			|| (session.lastFresh.counters !== undefined && fresh.counters === undefined))) reset();
+		// Tails anchored while history was empty would linger at the head once
+		// real history arrives. Reset once so fresh tails anchor at the tail.
+		if (session.tails.length > 0 && session.baseFingerprints.length === 0 && base.length > 0) reset();
+		// Any rewrite earlier than the anchors — middle-message edits, filter
+		// changes, checkpoint normalization — breaks the prefix even when the
+		// trailing message is identical, so verify the whole preceding history.
+		if (session.baseFingerprints.length > base.length) reset();
+		else {
+			for (let i = 0; i < session.baseFingerprints.length; i++) {
+				const current = fingerprints[i];
+				if (current === null || current !== session.baseFingerprints[i]) {
+					reset();
+					break;
+				}
+			}
+		}
+		// An unsafe anchor invalidates the whole replay. Keeping an earlier
+		// policy while re-appending fresh blocks would duplicate that policy.
+		let valid = 0;
+		while (valid < session.tails.length) {
+			const tail = session.tails[valid]!;
+			if (tail.anchorIndex > base.length) break;
+			if (tail.anchorIndex > 0) {
+				const current = fingerprints[tail.anchorIndex - 1];
+				if (current === null || current !== tail.anchorFingerprint) break;
+			}
+			if (splitsToolBatch(base[tail.anchorIndex])) break;
+			valid++;
+		}
+		if (valid < session.tails.length) reset();
+		const blocks = freshBlocks(fresh);
+		// Append only blocks that differ from the last emitted block of the same
+		// kind, so unchanged content across repeats, tool loops, and history
+		// advances adds zero blocks while keeping the prefix literal. The state
+		// block never differs here: a changed state already reset above.
+		const previous = session.lastFresh === undefined ? [] : freshBlocks(session.lastFresh);
+		let appended = blocks.filter(block => !previous.some(prior => prior.kind === block.kind && prior.content === block.content));
+		// Overflow is measured against what this request actually appends: an
+		// unchanged request adds nothing and must never trigger a reset.
+		if (session.tails.length + appended.length > MAX_RETAINED_LIVE_TAILS
+			|| kindBytes(session.tails, "goal-counters") + kindBytes(appended, "goal-counters") > MAX_RETAINED_COUNTER_BYTES
+			|| kindBytes(session.tails, "goal-tasks") + kindBytes(appended, "goal-tasks") > MAX_RETAINED_TASK_BYTES) {
+			reset();
+			appended = blocks;
+		}
+		const messages: Array<T | LiveMessage> = [...base];
+		for (let i = session.tails.length - 1; i >= 0; i--) {
+			const tail = session.tails[i]!;
+			messages.splice(tail.anchorIndex, 0, makeLiveMessage(tail.content));
+		}
+		for (const block of appended) {
+			messages.push(makeLiveMessage(block.content));
+			session.tails.push({ anchorIndex: base.length, anchorFingerprint: fingerprints.at(-1) ?? null, content: block.content, kind: block.kind });
+		}
+		session.baseFingerprints = fingerprints;
+		session.lastFresh = { state: fresh.state, tasks: fresh.tasks || undefined, counters: fresh.counters };
+		return { messages, transientContents: [...new Set([...session.tails.map(tail => tail.content), ...blocks.map(block => block.content)])] };
+	}
+
+	contents(sessionKey: string): string[] | undefined {
+		return this.sessions.get(sessionKey)?.tails.map(tail => tail.content);
+	}
+
+	clear(sessionKey?: string): void {
+		if (sessionKey === undefined) this.sessions.clear();
+		else this.sessions.delete(sessionKey);
+	}
+}

package/extensions/goal-oracle.ts

@@ -0,0 +1,346 @@
+/**
+ * Issue #26 — opt-in read-only Blocker Oracle.
+ *
+ * A cheap executor can benefit from ONE stronger, read-only consultation
+ * before giving up and asking the user. Hard safety properties (plan §64):
+ *
+ *   - disabled by default; requires an explicit resolvable provider/model;
+ *   - invoked only through a valid update_goal({status:"blocked"}) request;
+ *   - the nested session gets ONLY read/grep/find/ls + a structured submit
+ *     tool — no write/edit/bash, ever;
+ *   - one successful consultation per blocker fingerprint (usage, timestamps,
+ *     and revision never change the fingerprint);
+ *   - actionable advice keeps the goal ACTIVE and arms a follow-up marker;
+ *     blocking is only permitted after a meaningful work attempt or when the
+ *     Oracle concludes needs_human/insufficient_context;
+ *   - every phase is durably recorded in the ledger with bounded payloads.
+ */
+
+import { Type } from "@earendil-works/pi-ai";
+import { createHash } from "node:crypto";
+
+import { defineTool, SessionManager, SettingsManager, type AgentToolResult, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { makeAuditorResourceLoader, resolveAuditorSessionModelOptions } from "./goal-auditor.ts";
+import type { GoalLedgerEvent } from "./goal-ledger.ts";
+import type { ResolvedGoalOracleSettings } from "./goal-settings.ts";
+import { safeIdPart, type GoalRecord } from "./goal-record.ts";
+
+function escapePromptPayload(value: string): string {
+	return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+
+// ── blocker fingerprint ─────────────────────────────────────────────────────
+
+function normalizeBlockerReason(reason: string): string {
+	return reason.normalize("NFKC").toLowerCase().replace(/\s+/g, " ").trim();
+}
+
+/** Stable short hash over task-tree shape + contracts (not usage/timestamps). */
+function taskStateFingerprint(goal: GoalRecord): string {
+	const lines: string[] = [];
+	const walk = (tasks: NonNullable<GoalRecord["taskList"]>["tasks"], depth: number): void => {
+		for (const t of tasks) {
+			lines.push(`${depth}:${t.id}:${t.status}:${t.verificationContract ?? ""}`);
+			if (t.subtasks) walk(t.subtasks, depth + 1);
+		}
+	};
+	if (goal.taskList) walk(goal.taskList.tasks, 0);
+	return createHash("sha256").update(lines.join("|")).digest("hex").slice(0, 16);
+}
+
+export interface BlockerFingerprintInput {
+	goalId: string;
+	objectiveHash: string;
+	verificationContractHash: string;
+	taskStateHash: string;
+	currentTaskId?: string;
+	normalizedReason: string;
+}
+
+/**
+ * Distinguishes materially different blockers without changing when usage,
+ * elapsed time, or revision counters change.
+ */
+export function buildBlockerFingerprint(goal: GoalRecord, reason: string): string {
+	const input: BlockerFingerprintInput = {
+		goalId: goal.id,
+		objectiveHash: createHash("sha256").update(goal.objective).digest("hex").slice(0, 16),
+		verificationContractHash: createHash("sha256").update(goal.verificationContract ?? "").digest("hex").slice(0, 16),
+		taskStateHash: taskStateFingerprint(goal),
+		currentTaskId: goal.currentTaskId,
+		normalizedReason: normalizeBlockerReason(reason),
+	};
+	return createHash("sha256").update(JSON.stringify(input)).digest("hex").slice(0, 24);
+}
+
+// ── ledger reconstruction ───────────────────────────────────────────────────
+
+export interface OracleConsultState {
+	result?: { adviceId: string; disposition: "actionable" | "needs_human" | "insufficient_context"; summary: string };
+	failedAttempts: number;
+	lastFailure?: { errorCode: "config" | "provider" | "aborted" | "invalid_output"; message: string };
+	followupAttempted: boolean;
+}
+
+/** Reconstruct per-fingerprint consult state from raw ledger events. */
+export function oracleStateForFingerprint(events: readonly GoalLedgerEvent[], goalId: string, fingerprint: string): OracleConsultState {
+	const state: OracleConsultState = { failedAttempts: 0, followupAttempted: false };
+	for (const event of events) {
+		if (event.type !== "oracle_started" && event.type !== "oracle_result" && event.type !== "oracle_failed" && event.type !== "oracle_followup_attempted") continue;
+		if (event.goalId !== goalId || event.fingerprint !== fingerprint) continue;
+		switch (event.type) {
+			case "oracle_result":
+				state.result = { adviceId: event.adviceId, disposition: event.disposition, summary: event.summary };
+				break;
+			case "oracle_failed":
+				state.failedAttempts += 1;
+				state.lastFailure = { errorCode: event.errorCode, message: event.message };
+				break;
+			case "oracle_followup_attempted":
+				state.followupAttempted = true;
+				break;
+			default:
+				break;
+		}
+	}
+	return state;
+}
+
+// ── structured advice + isolated session ────────────────────────────────────
+
+const OracleAdviceSchema = Type.Object({
+	diagnosis: Type.String({ maxLength: 2000 }),
+	alternatives: Type.Array(
+		Type.Object({
+			title: Type.String({ maxLength: 200 }),
+			rationale: Type.String({ maxLength: 1000 }),
+			steps: Type.Array(Type.String({ maxLength: 400 }), { minItems: 1, maxItems: 8 }),
+			expectedEvidence: Type.Array(Type.String({ maxLength: 400 }), { maxItems: 8 }),
+		}),
+		{ minItems: 1, maxItems: 4 },
+	),
+	recommendedIndex: Type.Integer({ minimum: 0, maximum: 3 }),
+	unresolvedQuestions: Type.Array(Type.String({ maxLength: 400 }), { maxItems: 6 }),
+	disposition: Type.Union([
+		Type.Literal("actionable"),
+		Type.Literal("needs_human"),
+		Type.Literal("insufficient_context"),
+	]),
+});
+
+export type OracleAdvice = {
+	diagnosis: string;
+	alternatives: Array<{ title: string; rationale: string; steps: string[]; expectedEvidence: string[] }>;
+	recommendedIndex: number;
+	unresolvedQuestions: string[];
+	disposition: "actionable" | "needs_human" | "insufficient_context";
+};
+
+export type OracleRunResult =
+	| { ok: true; advice: OracleAdvice }
+	| { ok: false; errorCode: "config" | "provider" | "aborted" | "invalid_output"; message: string };
+
+export function buildBlockerOraclePrompt(args: {
+	goal: GoalRecord;
+	reason: string;
+	attemptedActions: string[];
+	recentEvidence: string;
+}): string {
+	const g = args.goal;
+	return [
+		"You are a read-only blocker adviser.",
+		"Find concrete alternative paths. Do not mutate files.",
+		"Do not mark the goal complete or blocked.",
+		"Return advice only through submit_goal_oracle_advice.",
+		"",
+		"<objective>",
+		escapePromptPayload(g.objective),
+		"</objective>",
+		g.verificationContract?.trim() ? `<verification_contract>\n${escapePromptPayload(g.verificationContract.trim())}\n</verification_contract>` : "",
+		`<blocker_reason>\n${escapePromptPayload(args.reason)}\n</blocker_reason>`,
+		args.attemptedActions.length > 0 ? `<attempted_actions>\n${args.attemptedActions.map((a) => `- ${a}`).join("\n")}\n</attempted_actions>` : "",
+		args.recentEvidence.trim() ? `<recent_evidence>\n${escapePromptPayload(args.recentEvidence.slice(0, 2000))}\n</recent_evidence>` : "",
+		"",
+		"Inspect relevant files with read-only tools before advising when needed.",
+	].filter(Boolean).join("\n\n");
+}
+
+/** Validate untrusted submitted advice against the bounded schema semantics. */
+function validateAdvice(value: unknown): OracleAdvice | { error: string } {
+	const raw = value as Record<string, unknown> | null;
+	if (!raw || typeof raw !== "object") return { error: "advice must be an object" };
+	if (typeof raw.diagnosis !== "string" || !raw.diagnosis.trim()) return { error: "diagnosis required" };
+	if (!Array.isArray(raw.alternatives) || raw.alternatives.length < 1 || raw.alternatives.length > 4) {
+		return { error: "1-4 alternatives required" };
+	}
+	for (const alt of raw.alternatives as Array<Record<string, unknown>>) {
+		if (typeof alt.title !== "string" || typeof alt.rationale !== "string") return { error: "alternative title/rationale required" };
+		if (!Array.isArray(alt.steps) || alt.steps.length < 1 || alt.steps.some((s) => typeof s !== "string")) return { error: "steps must be non-empty strings" };
+	}
+	if (typeof raw.recommendedIndex !== "number" || raw.recommendedIndex < 0 || raw.recommendedIndex >= (raw.alternatives as unknown[]).length) {
+		return { error: "recommendedIndex out of range" };
+	}
+	if (raw.disposition !== "actionable" && raw.disposition !== "needs_human" && raw.disposition !== "insufficient_context") {
+		return { error: "disposition must be actionable|needs_human|insufficient_context" };
+	}
+	return value as OracleAdvice;
+}
+
+/** Resolve the EXPLICIT Oracle model; provider-only or missing config is refused. */
+export function resolveOracleModel(
+	ctx: ExtensionContext,
+	settings: ResolvedGoalOracleSettings,
+): { ok: true; model: unknown } | { ok: false; message: string } {
+	if (!settings.provider || !settings.model) {
+		return {
+			ok: false,
+			message: "The blocker Oracle is enabled but not fully configured: set both oracle.provider and oracle.model in settings. The executor model is NOT used silently.",
+		};
+	}
+	const found = (ctx.modelRegistry as unknown as { find?: (provider: string, id: string) => unknown })?.find?.(settings.provider, settings.model);
+	if (!found) {
+		return { ok: false, message: `Configured Oracle model not found: ${settings.provider}/${settings.model}.` };
+	}
+	return { ok: true, model: found };
+}
+
+/**
+ * Run ONE isolated read-only Oracle consultation. `createSession` is
+ * injectable for tests (same seam as the completion auditor).
+ */
+export async function runBlockerOracle(args: {
+	ctx: ExtensionContext;
+	goal: GoalRecord;
+	reason: string;
+	attemptedActions: string[];
+	settings: ResolvedGoalOracleSettings;
+	recentEvidence: string;
+	signal?: AbortSignal;
+	createSession?: (...args: unknown[]) => Promise<{ session: OracleSessionFactory }>;
+}): Promise<OracleRunResult> {
+	const model = resolveOracleModel(args.ctx, args.settings);
+	if (!model.ok) return { ok: false, errorCode: "config", message: model.message };
+
+	const submitted: { settled: boolean; advice?: OracleAdvice } = { settled: false };
+	const submitTool = defineTool({
+		name: "submit_goal_oracle_advice",
+		label: "Submit Oracle Advice",
+		description: "Submit your structured blocker advice. This is the ONLY way to return a result.",
+		promptSnippet: "Submit structured advice via submit_goal_oracle_advice.",
+		parameters: OracleAdviceSchema,
+		async execute(_toolCallId, params) {
+			const validated = validateAdvice(params);
+			if ("error" in validated) {
+				return { content: [{ type: "text", text: `Invalid advice: ${validated.error}` }], details: {} };
+			}
+			submitted.advice = validated;
+			submitted.settled = true;
+			return { content: [{ type: "text", text: "Advice recorded." }], details: {} };
+		},
+	});
+
+	try {
+		const createSession = args.createSession ?? (await import("@earendil-works/pi-coding-agent")).createAgentSession as unknown as (...sessionArgs: unknown[]) => Promise<{ session: OracleSessionFactory }>;
+		// Read-only tool profile: NO bash/write/edit is exposed to the Oracle.
+		const { session } = await createSession({
+			cwd: args.ctx.cwd,
+			model: model.model,
+			thinkingLevel: args.settings.thinkingLevel,
+			...resolveAuditorSessionModelOptions(args.ctx),
+			sessionManager: SessionManager.inMemory(args.ctx.cwd),
+			settingsManager: SettingsManager.inMemory({ compaction: { enabled: false } }),
+			...(!args.settings.projectResources ? { resourceLoader: makeAuditorResourceLoader(
+				"You are a read-only blocker adviser. Inspect evidence and suggest concrete alternative paths. Never modify files or decide goal outcomes. Return advice through submit_goal_oracle_advice.",
+			) } : {}),
+			tools: ["read", "grep", "find", "ls", "submit_goal_oracle_advice"],
+			customTools: [submitTool],
+		});
+
+		const abort = () => session.abort();
+		args.signal?.addEventListener("abort", abort, { once: true });
+		try {
+			if (args.signal?.aborted) return { ok: false, errorCode: "aborted", message: "Oracle consultation aborted." };
+			await session.prompt(buildBlockerOraclePrompt({
+				goal: args.goal,
+				reason: args.reason,
+				attemptedActions: args.attemptedActions.slice(0, 8),
+				recentEvidence: args.recentEvidence,
+			}));
+		} finally {
+			args.signal?.removeEventListener("abort", abort);
+			session.dispose?.();
+		}
+
+		if (args.signal?.aborted) return { ok: false, errorCode: "aborted", message: "Oracle consultation aborted." };
+		if (!submitted.settled || !submitted.advice) {
+			return { ok: false, errorCode: "invalid_output", message: "Oracle returned no structured advice." };
+		}
+		return { ok: true, advice: submitted.advice };
+	} catch (error) {
+		if (args.signal?.aborted) return { ok: false, errorCode: "aborted", message: "Oracle consultation aborted." };
+		return { ok: false, errorCode: "provider", message: error instanceof Error ? error.message : String(error) };
+	}
+}
+
+type OracleSessionFactory = {
+	prompt: (promptText: string) => Promise<void>;
+	abort: () => void;
+	dispose?: () => void;
+	subscribe?: (listener: (event: unknown) => void) => () => void;
+};
+
+// ── armed follow-up marker (session-scoped) ────────────────────────────────
+
+interface ArmedAdvice {
+	goalId: string;
+	fingerprint: string;
+	adviceId: string;
+	text: string;
+}
+
+const armedByGoalId = new Map<string, ArmedAdvice>();
+
+export function armOracleAdvice(goalId: string, fingerprint: string, advice: OracleAdvice): string {
+	const adviceId = `${fingerprint}-${safeIdPart(advice.alternatives[advice.recommendedIndex]?.title ?? "advice").slice(0, 24)}`;
+	const recommended = advice.alternatives[advice.recommendedIndex]!;
+	armedByGoalId.set(goalId, {
+		goalId,
+		fingerprint,
+		adviceId,
+		text: [
+			"Oracle suggested an alternative path:",
+			`${recommended.title} — ${recommended.rationale}`,
+			"Steps:",
+			...recommended.steps.map((s, i) => `  ${i + 1}. ${s}`),
+			recommended.expectedEvidence.length > 0 ? `Expected evidence: ${recommended.expectedEvidence.join("; ")}` : "",
+			"Attempt this path before reporting blocked again.",
+		].filter(Boolean).join("\n"),
+	});
+	return adviceId;
+}
+
+export function hasPendingOracleAdviceForFocusedGoal(goalId: string): boolean {
+	return armedByGoalId.has(goalId);
+}
+
+/** Consume the armed marker after a meaningful work attempt. */
+export function consumeOracleFollowupMarker(goalId: string): ArmedAdvice | undefined {
+	const armed = armedByGoalId.get(goalId);
+	armedByGoalId.delete(goalId);
+	return armed;
+}
+
+export function renderActionableOracleAdvice(advice: OracleAdvice): string {
+	const recommended = advice.alternatives[advice.recommendedIndex]!;
+	return [
+		`Oracle diagnosis: ${advice.diagnosis}`,
+		`Recommended alternative: ${recommended.title} — ${recommended.rationale}`,
+		...recommended.steps.map((s, i) => `  ${i + 1}. ${s}`),
+		"Try this path before calling update_goal({status:\"blocked\"}) again.",
+	].join("\n");
+}
+
+export function renderOracleAdviceReminder(armed: ArmedAdvice): string {
+	return `${armed.text}\n(The same blocker fingerprint already received Oracle advice; no new consultation will run until you attempt it.)`;
+}