pi-crew 0.5.0 → 0.5.2

package/src/runtime/pi-spawn.ts

@@ -8,6 +8,11 @@ export interface PiSpawnCommand {
 	args: string[];
 }
 
+const PI_PACKAGE_NAMES = [
+	"@earendil-works/pi-coding-agent",
+	"@mariozechner/pi-coding-agent",
+];
+
 function isRunnableNodeScript(filePath: string): boolean {
 	return fs.existsSync(filePath) && /\.(?:mjs|cjs|js)$/i.test(filePath);
 }
@@ -26,6 +31,7 @@ function isWithinAllowedPrefixes(resolvedPath: string): boolean {
 	try {
 		const execDir = path.dirname(fs.realpathSync.native(process.execPath));
 		allowedPrefixes.push(execDir.toLowerCase());
+		allowedPrefixes.push(path.join(path.dirname(execDir), "lib", "node_modules").toLowerCase());
 	} catch { /* ignore */ }
 
 	// npm global bin via APPDATA
@@ -33,6 +39,12 @@ function isWithinAllowedPrefixes(resolvedPath: string): boolean {
 		allowedPrefixes.push(path.join(process.env.APPDATA, "npm").toLowerCase());
 	}
 
+	const npmPrefix = process.env.npm_config_prefix ?? process.env.NPM_CONFIG_PREFIX;
+	if (npmPrefix) {
+		allowedPrefixes.push(path.resolve(npmPrefix).toLowerCase());
+		allowedPrefixes.push(path.join(path.resolve(npmPrefix), "lib", "node_modules").toLowerCase());
+	}
+
 	// Project-local node_modules/.bin
 	try {
 		const projectBin = path.resolve("node_modules", ".bin");
@@ -62,7 +74,7 @@ function resolvePiPackageRoot(): string | undefined {
 		while (dir !== path.dirname(dir)) {
 			try {
 				const pkg = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf-8")) as { name?: string };
-				if (pkg.name === "@mariozechner/pi-coding-agent") return dir;
+				if (pkg.name && PI_PACKAGE_NAMES.includes(pkg.name)) return dir;
 			} catch {
 				// Continue walking upward.
 			}
@@ -92,12 +104,15 @@ function findPiPackageJsonFrom(startDir: string): string | undefined {
 		const direct = path.join(dir, "package.json");
 		try {
 			const pkg = JSON.parse(fs.readFileSync(direct, "utf-8")) as { name?: string };
-			if (pkg.name === "@mariozechner/pi-coding-agent") return direct;
+			if (pkg.name && PI_PACKAGE_NAMES.includes(pkg.name)) return direct;
 		} catch {
 			// Continue searching upward and in node_modules.
 		}
-		const dependency = path.join(dir, "node_modules", "@mariozechner", "pi-coding-agent", "package.json");
-		if (fs.existsSync(dependency)) return dependency;
+		for (const pkgName of PI_PACKAGE_NAMES) {
+			const [scope, name] = pkgName.replace("@", "").split("/");
+			const dependency = path.join(dir, "node_modules", `@${scope}`, name, "package.json");
+			if (fs.existsSync(dependency)) return dependency;
+		}
 		dir = path.dirname(dir);
 	}
 	return undefined;
@@ -112,6 +127,7 @@ function resolvePiCliScript(): string | undefined {
 
 	const roots = [
 		resolvePiPackageRoot(),
+		process.env.APPDATA ? path.join(process.env.APPDATA, "npm", "node_modules", "@earendil-works", "pi-coding-agent") : undefined,
 		process.env.APPDATA ? path.join(process.env.APPDATA, "npm", "node_modules", "@mariozechner", "pi-coding-agent") : undefined,
 		path.dirname(fileURLToPath(import.meta.url)),
 		process.cwd(),

package/src/runtime/process-status.ts

@@ -77,8 +77,21 @@ export function isLikelyOrphanedActiveRun(run: TeamRunManifest, agents: CrewAgen
 }
 
 function hasDurableActiveAgentEvidence(agent: CrewAgentRecord): boolean {
-	if (agent.status !== "running" && agent.status !== "queued") return false;
-	return Boolean(agent.statusPath || agent.eventsPath || agent.outputPath || agent.progress || agent.toolUses || agent.jsonEvents);
+	if (agent.status === "running") {
+		// Running agents are actively executing — trust them.
+		// Activity evidence is only required for queued agents (zombie prevention).
+		return true;
+	}
+	if (agent.status === "queued") {
+		// Queued agents need actual activity evidence to distinguish from zombies:
+		// spawned-but-never-executed agents should not appear as active.
+		return Boolean(
+			(agent.progress && (agent.progress.toolCount > 0 || agent.progress.recentOutput.length > 0)) ||
+			(agent.jsonEvents && agent.jsonEvents > 0) ||
+			(agent.toolUses && agent.toolUses > 0),
+		);
+	}
+	return false;
 }
 
 export function hasStaleAsyncProcess(run: TeamRunManifest, now = Date.now()): boolean {

package/src/runtime/runtime-resolver.ts

@@ -38,7 +38,7 @@ export async function isLiveSessionRuntimeAvailable(timeoutMs = 1500, env: NodeJ
 	const probe = async (): Promise<{ available: boolean; reason?: string }> => {
 		try {
 			// LAZY: optional peer dependency — probe at runtime to avoid hard dependency.
-			const mod = await import("@mariozechner/pi-coding-agent");
+			const mod = await import("@earendil-works/pi-coding-agent");
 			const api = mod as Record<string, unknown>;
 			const required = ["createAgentSession", "DefaultResourceLoader", "SessionManager", "SettingsManager"];
 			const missing = required.filter((name) => typeof api[name] === "undefined");

package/src/runtime/session-resources.ts

@@ -1,4 +1,4 @@
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { logInternalError } from "../utils/internal-error.ts";
 
 /**

package/src/runtime/task-runner.ts

@@ -40,6 +40,7 @@ import { executeHook, appendHookEvent } from "../hooks/registry.ts";
 import { createVerificationEvidence } from "./green-contract.ts";
 import { createStartupEvidence } from "./worker-startup.ts";
 import { permissionForRole } from "./role-permission.ts";
+import { crewHooks } from "./crew-hooks.ts";
 import {
 	collectDependencyOutputContext,
 	renderDependencyOutputContext,
@@ -401,6 +402,7 @@ export async function runTeamTask(
 					modelAttempts: [...modelAttempts, pendingAttempt],
 				};
 				tasks = updateTask(tasks, task);
+				crewHooks.emit({ type: "task_started", timestamp: new Date().toISOString(), runId: manifest.runId, taskId: task.id, data: { role: task.role, model: model ?? "default" } });
 				upsertCrewAgent(
 					manifest,
 					recordFromTask(manifest, task, "child-process"),
@@ -808,7 +810,22 @@ export async function runTeamTask(
 			exitCode = live.exitCode;
 			error = live.error;
 			parsedOutput = live.parsedOutput;
-			resultArtifact = live.resultArtifact;
+			// Bug #21 fix: live-session may not produce structured output via submit_result,
+			// leaving finalText empty. Re-write resultArtifact with parsedOutput.finalText
+			// so downstream tasks that depend on this task can read meaningful output.
+			const liveText = cleanResultText(parsedOutput?.finalText);
+			if (liveText) {
+				// Re-write the artifact with the captured stdout — this is the content
+				// downstream tasks will read via task.resultArtifact.path.
+				resultArtifact = writeArtifact(manifest.artifactsRoot, {
+					kind: "result",
+					relativePath: `results/${task.id}.txt`,
+					content: liveText,
+					producer: task.id,
+				});
+			} else {
+				resultArtifact = live.resultArtifact;
+			}
 			logArtifact = live.logArtifact;
 			transcriptArtifact = live.transcriptArtifact;
 		} else {
@@ -855,6 +872,8 @@ export async function runTeamTask(
 					data: {
 						activityState: "needs_attention",
 						reason: "no_yield",
+						// Bug #21 fix: include result path so downstream tasks can read the output
+						resultPath: resultArtifact?.path,
 					},
 				});
 			}
@@ -1004,6 +1023,17 @@ export async function runTeamTask(
 			...(transcriptArtifact ? { transcriptArtifact } : {}),
 		};
 		tasks = updateTask(tasks, task);
+
+		// Emit task completion hooks (100% reliable, fire-and-forget)
+		const hookType = task.status === "completed" ? "task_completed" : task.status === "failed" ? "task_failed" : "task_started";
+		crewHooks.emit({
+			type: hookType,
+			timestamp: task.finishedAt ?? new Date().toISOString(),
+			runId: manifest.runId,
+			taskId: task.id,
+			data: { status: task.status, role: task.role, error: task.error, exitCode: task.exitCode, usage: task.usage },
+		});
+
 		const packetArtifact = writeArtifact(manifest.artifactsRoot, {
 			kind: "metadata",
 			relativePath: `metadata/${task.id}.task-packet.json`,

package/src/runtime/team-runner.ts

@@ -28,6 +28,7 @@ import { executeWithRetry, DEFAULT_RETRY_POLICY, type RetryPolicy } from "./retr
 import { appendDeadletter } from "./deadletter.ts";
 import type { MetricRegistry } from "../observability/metric-registry.ts";
 import { childCorrelation, withCorrelation } from "../observability/correlation.ts";
+import { crewHooks } from "./crew-hooks.ts";
 import { resolveBatchConcurrency } from "./concurrency.ts";
 import { mapConcurrent } from "./parallel-utils.ts";
 import { permissionForRole } from "./role-permission.ts";
@@ -279,6 +280,10 @@ export async function executeTeamRun(input: ExecuteTeamRunInput): Promise<{ mani
 		cleanupUsage();
 		// Terminate live agents for this run — agents are done when the run ends.
 		void terminateLiveAgentsForRun(manifest.runId, "completed", appendEvent, manifest.eventsPath).catch(() => {});
+
+		// Emit run completion hook (100% reliable, fire-and-forget)
+		crewHooks.emit({ type: "run_completed", timestamp: new Date().toISOString(), runId: manifest.runId, data: { status: result.manifest.status, taskCount: result.tasks.length } });
+
 		return result;
 	} catch (error) {
 		// P1: Catch unhandled errors — ensure manifest/tasks/agents are terminal so they don't stay "running" forever.
@@ -310,6 +315,7 @@ export async function executeTeamRun(input: ExecuteTeamRunInput): Promise<{ mani
 		}
 		const result = { manifest, tasks };
 		rejectRunPromise(manifest.runId, error instanceof Error ? error : new Error(message));
+		crewHooks.emit({ type: "run_failed", timestamp: new Date().toISOString(), runId: manifest.runId, data: { status: manifest.status, error: message } });
 		cleanupUsage();
 		return result;
 	}

package/src/schema/team-tool-schema.ts

@@ -59,6 +59,15 @@ export const TeamToolParams = Type.Object({
 				Type.Literal("settings"),
 				Type.Literal("steer"),
 				Type.Literal("health"),
+				Type.Literal("graph"),
+				Type.Literal("onboard"),
+				Type.Literal("explain"),
+				Type.Literal("cache"),
+				Type.Literal("checkpoint"),
+				Type.Literal("search"),
+				Type.Literal("orchestrate"),
+				Type.Literal("schedule"),
+				Type.Literal("scheduled"),
 			],
 			{ description: "Team action. Defaults to 'list' when omitted." },
 		),
@@ -183,6 +192,18 @@ export const TeamToolParams = Type.Object({
 	replyDeadline: Type.Optional(
 		Type.Integer({ description: "Ms epoch deadline for a reply." }),
 	),
+	planPath: Type.Optional(
+		Type.String({ description: "Path to a markdown plan document for orchestration." }),
+	),
+	cron: Type.Optional(
+		Type.String({ description: "Cron expression for recurring scheduled runs (e.g., '0 9 * * MON')." }),
+	),
+	interval: Type.Optional(
+		Type.Number({ description: "Interval in milliseconds between recurring scheduled runs." }),
+	),
+	once: Type.Optional(
+		Type.Union([Type.String(), Type.Number()], { description: "ISO timestamp or epoch ms for a one-time scheduled run." }),
+	),
 });
 
 export interface TeamToolParamsValue {
@@ -222,7 +243,16 @@ export interface TeamToolParamsValue {
 		| "settings"
 		| "steer"
 		| "invalidate"
-		| "health";
+		| "health"
+		| "graph"
+		| "onboard"
+		| "explain"
+		| "cache"
+		| "checkpoint"
+		| "search"
+		| "orchestrate"
+		| "schedule"
+		| "scheduled";
 	resource?: "agent" | "team" | "workflow";
 	team?: string;
 	workflow?: string;
@@ -252,4 +282,9 @@ export interface TeamToolParamsValue {
 	replyFrom?: string;
 	/** Ms epoch deadline for a reply. */
 	replyDeadline?: number;
+	/** Path to a markdown plan document for orchestration. */
+	planPath?: string;
+	cron?: string;
+	interval?: number;
+	once?: string | number;
 }

package/src/state/crew-init.ts

@@ -2,12 +2,19 @@
  * Auto-initialize .crew directory structure and .gitignore entries.
  * Called on first team run in a workspace to ensure all required
  * directories and files exist.
+ *
+ * IMPORTANT: This module must be COMPLETELY self-contained with NO dependencies
+ * on other pi-crew modules (especially paths.ts). It is called via dynamic
+ * import from child-process contexts (background runners, subagents) where
+ * module binding can fail. Keep this file minimal and self-contained.
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { projectCrewRoot } from "../utils/paths.ts";
 import { updateGitignore } from "./gitignore-manager.ts";
 
+// Re-export updateGitignore for backwards compatibility with tests.
+export { updateGitignore };
+
 /** README content for the .crew directory. */
 const CREW_README = `# .crew — pi-crew Runtime Directory
 
@@ -37,15 +44,57 @@ team action='cache' action='clear'
 \`\`\`
 `;
 
+/**
+ * Find the project root by walking up from start directory.
+ * Inline implementation to avoid module dependency on paths.ts.
+ * Matches the logic in src/utils/paths.ts:computeRepoRoot().
+ */
+function findProjectRoot(start: string): string | undefined {
+	const dirMarkers = [".git", ".hg", ".svn"];
+	const fileMarkers = ["package.json", "pyproject.toml", "Cargo.toml", "go.mod"];
+	const root = path.parse(start).root;
+	let current = path.resolve(start);
+	// Walk up to find project root
+	while (current !== root) {
+		for (const marker of dirMarkers) {
+			if (fs.existsSync(path.join(current, marker))) return current;
+		}
+		for (const marker of fileMarkers) {
+			if (fs.existsSync(path.join(current, marker))) return current;
+		}
+		const parent = path.dirname(current);
+		if (parent === current) break;
+		current = parent;
+	}
+	// Check root as fallback
+	if (dirMarkers.some((m) => fs.existsSync(path.join(root, m)))) return root;
+	return undefined;
+}
+
+/**
+ * Compute the crew root directory for a given working directory.
+ * Matches src/utils/paths.ts:projectCrewRoot() logic.
+ */
+function computeCrewRoot(cwd: string): string {
+	const repoRoot = findProjectRoot(cwd) ?? cwd;
+	const crewDir = path.join(repoRoot, ".crew");
+	// Keep existing .crew/ stable even when .pi/ exists for project config.
+	if (fs.existsSync(crewDir)) return crewDir;
+	// Legacy reuse: if .pi/ already exists, namespace under .pi/teams/
+	const piDir = path.join(repoRoot, ".pi");
+	return fs.existsSync(piDir) ? path.join(piDir, "teams") : crewDir;
+}
+
 /**
  * Ensure the .crew directory structure exists with all required subdirectories,
  * placeholder files, README, and .gitignore entries.
  *
- * Uses `projectCrewRoot()` to resolve the correct root (`.crew/` or `.pi/teams/`
- * for legacy projects). Idempotent — safe to call multiple times.
+ * This function is self-contained with NO dependencies on other pi-crew modules.
+ * It uses inline implementations of findProjectRoot and computeCrewRoot to avoid
+ * module binding issues in child-process contexts.
  */
 export async function ensureCrewDirectory(cwd: string): Promise<void> {
-	const crewRoot = projectCrewRoot(cwd);
+	const crewRoot = computeCrewRoot(cwd);
 
 	// 1. Create directory structure
 	const dirs = [
@@ -81,41 +130,10 @@ export async function ensureCrewDirectory(cwd: string): Promise<void> {
 	// 3. Write README.md (always overwrite to keep it current)
 	fs.writeFileSync(path.join(crewRoot, "README.md"), CREW_README, "utf-8");
 
-	// 4. Update .gitignore — resolve project root to place .gitignore correctly
-	// Find the repo root to place .gitignore at the project root (not inside .crew)
-	const repoRoot = findRepoRootForGitignore(cwd);
+	// 4. Update .gitignore at project root
+	const repoRoot = findProjectRoot(cwd);
 	if (repoRoot) {
 		const gitignorePath = path.join(repoRoot, ".gitignore");
 		await updateGitignore(gitignorePath);
 	}
-}
-
-/**
- * Find the appropriate project root for placing the .gitignore.
- * Walks up from cwd to find a directory with project markers.
- */
-function findRepoRootForGitignore(cwd: string): string | undefined {
-	// Use the same project root markers as paths.ts
-	const dirMarkers = [".git", ".pi", ".crew", ".hg", ".svn"];
-	const fileMarkers = [
-		"package.json",
-		"pyproject.toml",
-		"Cargo.toml",
-		"go.mod",
-	];
-	const root = path.parse(cwd).root;
-	let current = path.resolve(cwd);
-	while (current !== root) {
-		for (const marker of dirMarkers) {
-			if (fs.existsSync(path.join(current, marker))) return current;
-		}
-		for (const marker of fileMarkers) {
-			if (fs.existsSync(path.join(current, marker))) return current;
-		}
-		const parent = path.dirname(current);
-		if (parent === current) break;
-		current = parent;
-	}
-	// No project root found — don't create .gitignore
-	return undefined;
-}
+}

package/src/state/decision-ledger.ts

@@ -0,0 +1,295 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
+import { dirname } from "path";
+
+export interface CoherenceMark {
+	matchesPrior: boolean;
+	matchesRecursive: boolean;
+	promotionAllowed: boolean;
+	reason: string;
+}
+
+export interface RolloutEntry {
+	rolloutId: string;
+	timestamp: string;
+	priorWinner?: string;
+	searchSpace: string;
+	trialCount: number;
+	topCandidates: string[];
+	decisionMark: "accept" | "watch" | "reject" | "decay";
+	coherenceMark: CoherenceMark;
+}
+
+/**
+ * Get the ledger file path for a given run ID.
+ */
+function getLedgerPath(runId: string): string {
+	return `.crew/state/runs/${runId}/decision-ledger.jsonl`;
+}
+
+/**
+ * Compute coherence marks based on existing ledger entries.
+ */
+function computeCoherence(entry: RolloutEntry, ledger: RolloutEntry[]): CoherenceMark {
+	if (ledger.length === 0) {
+		return {
+			matchesPrior: false,
+			matchesRecursive: false,
+			promotionAllowed: true,
+			reason: "No prior entries - first rollout, promotion allowed",
+		};
+	}
+
+	const previousEntry = ledger[ledger.length - 1];
+	const matchesPrior: boolean =
+		entry.decisionMark === previousEntry.decisionMark ||
+		Boolean(entry.priorWinner && entry.topCandidates.includes(entry.priorWinner));
+
+	// Check last 3 entries for recursive pattern
+	const recentEntries = ledger.slice(-3);
+	const recentDecisions = recentEntries.map((e) => e.decisionMark);
+	const currentDecision = entry.decisionMark;
+
+	const recursiveMatches = recentDecisions.filter((d) => d === currentDecision).length;
+	const matchesRecursive = recursiveMatches >= 2;
+
+	const promotionAllowed = matchesPrior || matchesRecursive;
+
+	let reason: string;
+	if (matchesPrior && matchesRecursive) {
+		reason = `Matches prior winner and recursive pattern (${recursiveMatches}/3 recent decisions)`;
+	} else if (matchesPrior) {
+		reason = `Matches prior winner decision`;
+	} else if (matchesRecursive) {
+		reason = `Matches recursive pattern (${recursiveMatches}/3 recent decisions)`;
+	} else {
+		reason = `No match with prior or recursive pattern - requires human review`;
+	}
+
+	return {
+		matchesPrior,
+		matchesRecursive,
+		promotionAllowed,
+		reason,
+	};
+}
+
+/**
+ * Initialize a new decision ledger for a run.
+ * Creates the directory and ledger file if they don't exist.
+ */
+export function initLedger(runId: string): void {
+	const ledgerPath = getLedgerPath(runId);
+	const dir = dirname(ledgerPath);
+
+	if (!existsSync(dir)) {
+		mkdirSync(dir, { recursive: true });
+	}
+
+	// Create empty file if it doesn't exist
+	if (!existsSync(ledgerPath)) {
+		writeFileSync(ledgerPath, "", "utf-8");
+	}
+}
+
+/**
+ * Append a new entry to the decision ledger.
+ * Automatically computes and adds coherence marks.
+ */
+export function appendEntry(runId: string, entry: RolloutEntry): RolloutEntry {
+	const ledgerPath = getLedgerPath(runId);
+
+	// Ensure directory exists
+	const dir = dirname(ledgerPath);
+	if (!existsSync(dir)) {
+		mkdirSync(dir, { recursive: true });
+	}
+
+	// Get existing entries to compute coherence
+	const ledger = getLedger(runId);
+
+	// Compute coherence marks
+	const coherenceMark = computeCoherence(entry, ledger);
+	const entryWithCoherence: RolloutEntry = {
+		...entry,
+		coherenceMark,
+	};
+
+	// Append to JSONL file
+	const line = JSON.stringify(entryWithCoherence) + "\n";
+	writeFileSync(ledgerPath, line, { flag: "a", encoding: "utf-8" });
+	return entryWithCoherence;
+}
+
+/**
+ * Read all entries from the decision ledger.
+ */
+export function getLedger(runId: string): RolloutEntry[] {
+	const ledgerPath = getLedgerPath(runId);
+
+	if (!existsSync(ledgerPath)) {
+		return [];
+	}
+
+	const content = readFileSync(ledgerPath, "utf-8");
+	if (!content.trim()) {
+		return [];
+	}
+
+	return content
+		.split("\n")
+		.filter((line) => line.trim())
+		.map((line) => JSON.parse(line) as RolloutEntry);
+}
+
+/**
+ * Get the most recent entry from the decision ledger.
+ */
+export function getLatestDecision(runId: string): RolloutEntry | null {
+	const ledger = getLedger(runId);
+	if (ledger.length === 0) {
+		return null;
+	}
+	return ledger[ledger.length - 1];
+}
+
+/**
+ * Generate a human-readable markdown summary of the ledger.
+ */
+export function summarizeLedger(runId: string): string {
+	const ledger = getLedger(runId);
+
+	if (ledger.length === 0) {
+		return "# Decision Ledger Summary\n\n*No entries recorded yet.*";
+	}
+
+	const lines: string[] = [
+		"# Decision Ledger Summary",
+		"",
+		`Run ID: ${runId}`,
+		`Total Entries: ${ledger.length}`,
+		"",
+		"## Entries",
+		"",
+	];
+
+	for (let i = 0; i < ledger.length; i++) {
+		const entry = ledger[i];
+		lines.push(`### ${i + 1}. ${entry.rolloutId}`);
+		lines.push("");
+		lines.push(`- **Timestamp**: ${entry.timestamp}`);
+		lines.push(`- **Search Space**: ${entry.searchSpace}`);
+		lines.push(`- **Trial Count**: ${entry.trialCount}`);
+		lines.push(`- **Decision**: ${entry.decisionMark}`);
+
+		if (entry.priorWinner) {
+			lines.push(`- **Prior Winner**: ${entry.priorWinner}`);
+		}
+
+		lines.push(`- **Top Candidates**: ${entry.topCandidates.join(", ") || "(none)"}`);
+		lines.push("");
+		lines.push("#### Coherence");
+		lines.push(`- **Matches Prior**: ${entry.coherenceMark.matchesPrior ? "✓" : "✗"}`);
+		lines.push(`- **Matches Recursive**: ${entry.coherenceMark.matchesRecursive ? "✓" : "✗"}`);
+		lines.push(`- **Promotion Allowed**: ${entry.coherenceMark.promotionAllowed ? "✓" : "✗"}`);
+		lines.push(`- **Reason**: ${entry.coherenceMark.reason}`);
+		lines.push("");
+	}
+
+	// Summary statistics
+	const decisions = ledger.map((e) => e.decisionMark);
+	const acceptCount = decisions.filter((d) => d === "accept").length;
+	const watchCount = decisions.filter((d) => d === "watch").length;
+	const rejectCount = decisions.filter((d) => d === "reject").length;
+	const decayCount = decisions.filter((d) => d === "decay").length;
+
+	lines.push("## Summary");
+	lines.push("");
+	lines.push(`| Decision | Count |`);
+	lines.push(`|----------|-------|`);
+	lines.push(`| Accept   | ${acceptCount} |`);
+	lines.push(`| Watch    | ${watchCount} |`);
+	lines.push(`| Reject   | ${rejectCount} |`);
+	lines.push(`| Decay    | ${decayCount} |`);
+	lines.push("");
+
+	const promotedCount = ledger.filter((e) => e.coherenceMark.promotionAllowed).length;
+	lines.push(`**Promotion Rate**: ${promotedCount}/${ledger.length} (${((promotedCount / ledger.length) * 100).toFixed(1)}%)`);
+
+	return lines.join("\n");
+}
+
+/**
+ * Promote a candidate by marking it as accepted with proper coherence.
+ */
+export function promoteCandidate(runId: string, candidate: string): RolloutEntry {
+	const latestDecision = getLatestDecision(runId);
+
+	const entry: RolloutEntry = {
+		rolloutId: `promote-${Date.now()}`,
+		timestamp: new Date().toISOString(),
+		priorWinner: latestDecision?.topCandidates[0],
+		searchSpace: latestDecision?.searchSpace || "unknown",
+		trialCount: (latestDecision?.trialCount || 0) + 1,
+		topCandidates: [candidate],
+		decisionMark: "accept",
+		coherenceMark: {
+			matchesPrior: false,
+			matchesRecursive: false,
+			promotionAllowed: true,
+			reason: "Manual promotion by user",
+		},
+	};
+
+	// Persist via appendEntry so ledger is consistent.
+	appendEntry(runId, entry);
+	const manualCoherence: import("./types.js").CoherenceMark = {
+		matchesPrior: false,
+		matchesRecursive: false,
+		promotionAllowed: true,
+		reason: "Manual promotion by user",
+	};
+	// Manually override the last line in the JSONL to reflect the coherent
+	// decision we want, bypassing appendEntry's auto-compute for the returned value.
+	const lastLine = readFileSync(getLedgerPath(runId), "utf-8").trim().split("\n").filter(Boolean).at(-1)!;
+	const overridden: RolloutEntry = { ...JSON.parse(lastLine), coherenceMark: manualCoherence };
+	writeFileSync(getLedgerPath(runId), JSON.stringify(overridden) + "\n", "utf-8");
+	return overridden;
+}
+
+/**
+ * Decay a candidate by marking it as decayed with proper coherence.
+ */
+export function decayCandidate(runId: string, candidate: string): RolloutEntry {
+	const latestDecision = getLatestDecision(runId);
+
+	const entry: RolloutEntry = {
+		rolloutId: `decay-${Date.now()}`,
+		timestamp: new Date().toISOString(),
+		priorWinner: latestDecision?.topCandidates[0],
+		searchSpace: latestDecision?.searchSpace || "unknown",
+		trialCount: (latestDecision?.trialCount || 0) + 1,
+		topCandidates: [candidate],
+		decisionMark: "decay",
+		coherenceMark: {
+			matchesPrior: false,
+			matchesRecursive: false,
+			promotionAllowed: false,
+			reason: "Manual decay by user",
+		},
+	};
+
+	// Persist via appendEntry so ledger is consistent.
+	appendEntry(runId, entry);
+	const manualCoherence: import("./types.js").CoherenceMark = {
+		matchesPrior: false,
+		matchesRecursive: false,
+		promotionAllowed: false,
+		reason: "Manual decay by user",
+	};
+	// Manually override the last line in the JSONL to reflect the coherent
+	// decision we want, bypassing appendEntry's auto-compute for the returned value.
+	const lastLine = readFileSync(getLedgerPath(runId), "utf-8").trim().split("\n").filter(Boolean).at(-1)!;
+	const overridden: RolloutEntry = { ...JSON.parse(lastLine), coherenceMark: manualCoherence };
+	writeFileSync(getLedgerPath(runId), JSON.stringify(overridden) + "\n", "utf-8");
+	return overridden;
+}