pi-crew 0.5.1 → 0.5.5

package/src/state/decision-ledger.ts

@@ -0,0 +1,344 @@
+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
+	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");
+}
+
+/**
+ * Override the coherence mark of the last entry in the ledger.
+ * FIX: This preserves all previous entries while updating just the last one.
+ * Previously this would truncate the entire ledger!
+ */
+function overrideLastEntry(runId: string, coherenceMark: import("./types.js").CoherenceMark): RolloutEntry {
+	const ledger = getLedger(runId);
+	if (ledger.length === 0) {
+		throw new Error(`No ledger entries found for run ${runId}`);
+	}
+	// Update the last entry with the new coherence mark
+	const lastIndex = ledger.length - 1;
+	ledger[lastIndex] = { ...ledger[lastIndex], coherenceMark };
+	// Rewrite entire ledger to preserve all entries
+	const ledgerPath = getLedgerPath(runId);
+	writeFileSync(ledgerPath, ledger.map((e) => JSON.stringify(e)).join("\n") + "\n", "utf-8");
+	return ledger[lastIndex];
+}
+
+/**
+ * Promote a candidate by marking it as accepted with proper coherence.
+ */
+export function promoteCandidate(runId: string, candidate: string): RolloutEntry {
+	const latestDecision = getLatestDecision(runId);
+
+	// Get existing entries to compute proper coherence
+	const ledger = getLedger(runId);
+
+	// Create entry without coherence first
+	const entryWithoutCoherence = {
+		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" as const,
+	};
+
+	// Compute coherence (empty ledger = no matches)
+	const coherenceMark = computeCoherence(entryWithoutCoherence as RolloutEntry, ledger);
+
+	// Manual promotion always allows further promotion
+	coherenceMark.promotionAllowed = true;
+	coherenceMark.reason = "Manual promotion - promotion allowed";
+
+	// Create full entry with coherence
+	const entry: RolloutEntry = {
+		...entryWithoutCoherence,
+		coherenceMark,
+	};
+
+	// Update last entry in memory if there are existing entries
+	if (ledger.length > 0) {
+		const lastIndex = ledger.length - 1;
+		ledger[lastIndex] = entry;
+	} else {
+		// No existing entries - just write this one
+		ledger.push(entry);
+	}
+
+	// Rewrite entire ledger to preserve all entries
+	const ledgerPath = getLedgerPath(runId);
+	const dir = dirname(ledgerPath);
+	if (!existsSync(dir)) {
+		mkdirSync(dir, { recursive: true });
+	}
+	writeFileSync(ledgerPath, ledger.map((e) => JSON.stringify(e)).join("\n") + "\n", "utf-8");
+
+	return entry;
+}
+
+/**
+ * Decay a candidate by marking it as decayed with proper coherence.
+ */
+export function decayCandidate(runId: string, candidate: string): RolloutEntry {
+	const latestDecision = getLatestDecision(runId);
+
+	// Get existing entries to compute proper coherence
+	const ledger = getLedger(runId);
+
+	// Create entry without coherence first
+	const entryWithoutCoherence = {
+		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" as const,
+	};
+
+	// Compute coherence (empty ledger = no matches)
+	const coherenceMark = computeCoherence(entryWithoutCoherence as RolloutEntry, ledger);
+
+	// Manual decay never allows promotion
+	coherenceMark.promotionAllowed = false;
+	coherenceMark.reason = "Manual decay - promotion not allowed";
+
+	// Create full entry with coherence
+	const entry: RolloutEntry = {
+		...entryWithoutCoherence,
+		coherenceMark,
+	};
+
+	// Update last entry in memory if there are existing entries
+	if (ledger.length > 0) {
+		const lastIndex = ledger.length - 1;
+		ledger[lastIndex] = entry;
+	} else {
+		// No existing entries - just write this one
+		ledger.push(entry);
+	}
+
+	// Rewrite entire ledger to preserve all entries
+	const ledgerPath = getLedgerPath(runId);
+	const dir = dirname(ledgerPath);
+	if (!existsSync(dir)) {
+		mkdirSync(dir, { recursive: true });
+	}
+	writeFileSync(ledgerPath, ledger.map((e) => JSON.stringify(e)).join("\n") + "\n", "utf-8");
+
+	return entry;
+}

package/src/state/event-log.ts

@@ -63,12 +63,17 @@ let appendCounter = 0;
 
 /** Simple cross-process lock for an eventsPath to prevent JSONL interleave on concurrent append.
  *  Detects stale locks by checking the owner PID written inside the lock directory.
+ *
+ *  @deprecated Prefer `appendEventAsync()` for callers in async contexts. The sync lock
+ *  uses `sleepSync` which blocks the event loop and prevents AbortSignal handlers from firing.
  */
 export function withEventLogLockSync<T>(eventsPath: string, fn: () => T): T {
+	// Ensure parent directory exists before attempting lock
+	fs.mkdirSync(path.dirname(eventsPath), { recursive: true });
 	const lockDir = `${eventsPath}.lock`;
 	const pidFile = path.join(lockDir, "pid");
 	const start = Date.now();
-	const timeout = 5000;
+	const timeout = 120000; // 120s timeout for slow CI environments
 	const staleMs = 10000;
 	let acquired = false;
 	while (true) {
@@ -79,6 +84,8 @@ export function withEventLogLockSync<T>(eventsPath: string, fn: () => T): T {
 			break;
 		} catch {
 			if (Date.now() - start > timeout) {
+				// Log error and continue without lock — lock is held by live process.
+				// Stale detection will clean up dead locks on next attempt.
 				logInternalError("event-log.lock-timeout", new Error(`Event log lock timeout for ${eventsPath}`), `lockDir=${lockDir}`);
 				break;
 			}
@@ -112,9 +119,15 @@ export function withEventLogLockSync<T>(eventsPath: string, fn: () => T): T {
 	}
 }
 
-function evictOldestSequenceCacheEntry(): void {
-	const first = sequenceCache.keys().next().value;
-	if (first !== undefined) sequenceCache.delete(first);
+function evictOldestSequenceCacheEntries(): void {
+	// Batch evict oldest 50% of entries when cache is full
+	const toEvict = Math.ceil(MAX_SEQUENCE_CACHE_ENTRIES / 2);
+	let evicted = 0;
+	for (const key of sequenceCache.keys()) {
+		if (evicted >= toEvict) break;
+		sequenceCache.delete(key);
+		evicted++;
+	}
 }
 
 export function sequencePath(eventsPath: string): string {
@@ -174,10 +187,116 @@ export function computeEventFingerprint(event: Pick<TeamEvent, "type" | "runId"
 	return createHash("sha256").update(JSON.stringify({ type: event.type, runId: event.runId, taskId: event.taskId, data: event.data ?? null })).digest("hex").slice(0, 16);
 }
 
+/**
+ * @deprecated Prefer `appendEventAsync()` in async contexts. The sync lock uses
+ * `sleepSync` which blocks the Node.js event loop, preventing AbortSignal handlers
+ * from firing and degrading live-agent responsiveness.
+ */
 export function appendEvent(eventsPath: string, event: AppendTeamEvent): TeamEvent {
 	return withEventLogLockSync(eventsPath, () => appendEventInsideLock(eventsPath, event));
 }
 
+// --- Async write queue (non-blocking alternative to withEventLogLockSync) ---
+const asyncQueues = new Map<string, Promise<unknown>>();
+
+/**
+ * Append an event to the event log using non-blocking async I/O.
+ *
+ * Uses a per-eventsPath promise-chain queue to ensure sequential writes without
+ * blocking the Node.js event loop. This allows AbortSignal handlers and other
+ * async operations to proceed while events are being persisted.
+ *
+ * For callers that are already in an async context (team-runner, task-runner,
+ * foreground-control, etc.), prefer this over the sync `appendEvent()`.
+ */
+export async function appendEventAsync(eventsPath: string, event: AppendTeamEvent): Promise<TeamEvent> {
+	const queueKey = eventsPath;
+	const prev = asyncQueues.get(queueKey) ?? Promise.resolve();
+	const next = prev.then(async (): Promise<TeamEvent> => {
+		// Ensure directory exists
+		await fs.promises.mkdir(path.dirname(eventsPath), { recursive: true });
+
+		// Build metadata (same logic as appendEventInsideLock)
+		const baseMetadata = event.metadata;
+		let metadata: TeamEventMetadata = {
+			seq: baseMetadata?.seq ?? nextSequence(eventsPath),
+			provenance: baseMetadata?.provenance ?? "team_runner",
+			...(baseMetadata?.parentEventId ? { parentEventId: baseMetadata.parentEventId } : {}),
+			...(baseMetadata?.attemptId ? { attemptId: baseMetadata.attemptId } : {}),
+			...(baseMetadata?.branchId ? { branchId: baseMetadata.branchId } : {}),
+			...(baseMetadata?.causationId ? { causationId: baseMetadata.causationId } : {}),
+			...(baseMetadata?.correlationId ? { correlationId: baseMetadata.correlationId } : {}),
+			...(baseMetadata?.sessionIdentity ? { sessionIdentity: baseMetadata.sessionIdentity } : {}),
+			...(baseMetadata?.ownership ? { ownership: baseMetadata.ownership } : {}),
+			...(baseMetadata?.nudgeId ? { nudgeId: baseMetadata.nudgeId } : {}),
+			...(baseMetadata?.confidence ? { confidence: baseMetadata.confidence } : {}),
+		};
+		const fullEvent: TeamEvent = {
+			time: new Date().toISOString(),
+			...event,
+			metadata,
+		};
+		if (baseMetadata?.fingerprint || TERMINAL_EVENT_TYPES.has(fullEvent.type)) {
+			metadata = { ...metadata, fingerprint: baseMetadata?.fingerprint ?? computeEventFingerprint(fullEvent) };
+			fullEvent.metadata = metadata;
+		}
+
+		// Overflow handling: same logic as sync path
+		const isTerminal = TERMINAL_EVENT_TYPES.has(fullEvent.type);
+		let skippedDueToSize = false;
+		if (!isTerminal && fs.existsSync(eventsPath)) {
+			const stat = fs.statSync(eventsPath);
+			if (stat.size > MAX_EVENTS_BYTES) {
+				try {
+					compactEventLog(eventsPath);
+				} catch (error) {
+					logInternalError("event-log.immediate-compact", error, `eventsPath=${eventsPath}`);
+				}
+				if (fs.existsSync(eventsPath)) {
+					const afterCompact = fs.statSync(eventsPath);
+					if (afterCompact.size > MAX_EVENTS_BYTES) {
+						rotateEventLog(eventsPath);
+					}
+				}
+			}
+		}
+		try {
+			if (fs.existsSync(eventsPath) && fs.statSync(eventsPath).size > MAX_EVENTS_BYTES) {
+				logInternalError("event-log.size-limit", new Error(`events file ${eventsPath} exceeds ${MAX_EVENTS_BYTES} bytes after compaction`), `eventsPath=${eventsPath}`);
+				skippedDueToSize = true;
+			}
+		} catch (error) {
+			logInternalError("event-log.size-check", error, `eventsPath=${eventsPath}`);
+		}
+
+		if (!skippedDueToSize) {
+			const line = JSON.stringify(redactSecrets(fullEvent)) + "\n";
+			await fs.promises.appendFile(eventsPath, line, { encoding: "utf-8" });
+		}
+
+		appendCounter++;
+		if (appendCounter % 100 === 0 && needsRotation(eventsPath)) {
+			try { compactEventLog(eventsPath); } catch (error) { logInternalError("event-log.rotation", error, `eventsPath=${eventsPath}`); }
+		}
+		try { emitFromTeamEvent(fullEvent); } catch (error) { logInternalError("event-log.emit", error); }
+
+		const seq = fullEvent.metadata?.seq ?? 0;
+		try {
+			const stat = fs.statSync(eventsPath);
+			if (sequenceCache.size >= MAX_SEQUENCE_CACHE_ENTRIES) {
+				evictOldestSequenceCacheEntries();
+			}
+			sequenceCache.set(eventsPath, { size: stat.size, mtimeMs: stat.mtimeMs, seq });
+			persistSequence(eventsPath, seq);
+		} catch (error) {
+			logInternalError("event-log.persist-sequence", error, `eventsPath=${eventsPath}`);
+		}
+		return fullEvent;
+	});
+	asyncQueues.set(queueKey, next.catch(() => {}));
+	return next;
+}
+
 /**
  * Body of `appendEvent` assuming the caller already holds
  * `withEventLogLockSync` for `eventsPath`. Used by `appendEventBuffered` to
@@ -254,7 +373,7 @@ function appendEventInsideLock(eventsPath: string, event: AppendTeamEvent): Team
 	try {
 		const stat = fs.statSync(eventsPath);
 		if (sequenceCache.size >= MAX_SEQUENCE_CACHE_ENTRIES) {
-			evictOldestSequenceCacheEntry();
+			evictOldestSequenceCacheEntries();
 		}
 		sequenceCache.set(eventsPath, { size: stat.size, mtimeMs: stat.mtimeMs, seq });
 		persistSequence(eventsPath, seq);
@@ -283,6 +402,12 @@ const bufferedTimers = new Map<string, ReturnType<typeof setTimeout>>();
 const DEFAULT_BUFFER_MS = 20;
 
 export function appendEventBuffered(eventsPath: string, event: AppendTeamEvent, bufferMs = DEFAULT_BUFFER_MS): Promise<TeamEvent> {
+	// FIX: Terminal events must bypass buffer to ensure they're written immediately.
+	// Previously, terminal events like task.failed could be lost on process crash.
+	if (TERMINAL_EVENT_TYPES.has(event.type)) {
+		// For terminal events, write synchronously to ensure durability
+		return Promise.resolve(appendEvent(eventsPath, event));
+	}
 	return new Promise<TeamEvent>((resolve, reject) => {
 		const queue = bufferedQueues.get(eventsPath) ?? [];
 		queue.push({ event, resolve, reject });
@@ -325,12 +450,13 @@ export function flushEventLogBuffer(): void {
 }
 
 /**
- * 2.2 caller-migration helper — schedule a buffered append but do not return
- * the resulting Promise. Use only for events whose return value is ignored
- * (high-frequency `task.progress`). Errors are logged via logInternalError.
+ * Schedule an async event append without waiting for the result.
+ * Uses the non-blocking async queue to avoid blocking the event loop.
+ * Use only for events whose return value is ignored (high-frequency `task.progress`).
+ * Errors are logged via logInternalError.
  */
-export function appendEventFireAndForget(eventsPath: string, event: AppendTeamEvent, bufferMs = DEFAULT_BUFFER_MS): void {
-	appendEventBuffered(eventsPath, event, bufferMs).catch((error) => logInternalError("event-log.fire-and-forget", error, eventsPath));
+export function appendEventFireAndForget(eventsPath: string, event: AppendTeamEvent, _bufferMs = DEFAULT_BUFFER_MS): void {
+	appendEventAsync(eventsPath, event).catch((error) => logInternalError("event-log.fire-and-forget", error, eventsPath));
 }
 
 // Auto-flush on process exit so buffered events do not silently leak.

package/src/state/hook-instinct-bridge.ts

@@ -0,0 +1,90 @@
+/**
+ * Hook-to-instinct bridge - connects crewHooks events to instinct formation.
+ * Auto-initializes when imported.
+ */
+
+import { crewHooks } from "../runtime/crew-hooks.ts";
+
+// Lazy-initialized store and paths
+let storeInstance: import("./instinct-store.js").InstinctStore | null = null;
+let pathsInstance: typeof import("../utils/paths.js") | null = null;
+
+async function getStore() {
+	if (!storeInstance) {
+		const { InstinctStore } = await import("./instinct-store.js");
+		const paths = await import("../utils/paths.js");
+		storeInstance = new InstinctStore(paths.projectCrewRoot(process.cwd()));
+	}
+	return storeInstance;
+}
+
+async function getPaths() {
+	if (!pathsInstance) {
+		pathsInstance = await import("../utils/paths.js");
+	}
+	return pathsInstance;
+}
+
+// Subscribe to events
+crewHooks.register("task_completed", async (event) => {
+	try {
+		const store = await getStore();
+		if (event.data?.role) {
+			store.saveInstinct({
+				trigger: `role:${event.data.role}`,
+				action: "prefer",
+				confidence: 0.6,
+				scope: "global",
+				evidence: [`task:${event.taskId} completed`],
+			});
+		}
+	} catch {
+		// Best-effort - don't crash on instinct formation failures
+	}
+});
+
+crewHooks.register("task_failed", async (event) => {
+	try {
+		const store = await getStore();
+		if (event.data?.role) {
+			store.saveInstinct({
+				trigger: `role:${event.data.role}`,
+				action: "avoid",
+				confidence: 0.3,
+				scope: "global",
+				evidence: [`task:${event.taskId} failed`],
+			});
+		}
+	} catch {
+		// Best-effort
+	}
+});
+
+crewHooks.register("run_completed", async (event) => {
+	try {
+		const store = await getStore();
+		if (event.data?.taskCount) {
+			store.saveInstinct({
+				trigger: "run_completed",
+				action: `completed:${event.data.taskCount}tasks`,
+				confidence: 0.6,
+				scope: "global",
+				evidence: [`run:${event.runId}`],
+			});
+		}
+	} catch {
+		// Best-effort
+	}
+});
+
+/**
+ * Get instinct-based recommendations.
+ */
+export async function getInstinctRecommendations() {
+	try {
+		const store = await getStore();
+		return store.getInstincts().filter((i: { confidence: number }) => i.confidence >= 0.6);
+	} catch {
+		return [];
+	}
+}

package/src/state/hook-integrations.ts

@@ -0,0 +1,51 @@
+/**
+ * Hook integrations - subscribes to crewHooks and provides observability.
+ * Auto-initializes when imported.
+ */
+
+import { crewHooks } from "../runtime/crew-hooks.ts";
+
+// Statistics
+let tasksCompleted = 0;
+let tasksFailed = 0;
+let runsCompleted = 0;
+let runsFailed = 0;
+
+// Subscribe to events (fire-and-forget)
+crewHooks.register("task_completed", () => {
+	tasksCompleted++;
+});
+
+crewHooks.register("task_failed", () => {
+	tasksFailed++;
+});
+
+crewHooks.register("run_completed", () => {
+	runsCompleted++;
+});
+
+crewHooks.register("run_failed", () => {
+	runsFailed++;
+});
+
+/**
+ * Get current hook statistics.
+ */
+export function getHookStats(): {
+	tasksCompleted: number;
+	tasksFailed: number;
+	runsCompleted: number;
+	runsFailed: number;
+} {
+	return { tasksCompleted, tasksFailed, runsCompleted, runsFailed };
+}
+
+/**
+ * Reset statistics (useful for testing).
+ */
+export function resetHookStats(): void {
+	tasksCompleted = 0;
+	tasksFailed = 0;
+	runsCompleted = 0;
+	runsFailed = 0;
+}