pi-crew 0.9.53 → 0.9.55

package/src/ui/widget/widget-model.ts

@@ -0,0 +1,110 @@
+/**
+ * Widget data model — fetching, filtering, and caching.
+ *
+ * Extracted from crew-widget.ts.
+ */
+
+import { listRecentRuns } from "../../extension/run-index.ts";
+import { reconcileAllStaleRuns } from "../../runtime/crash-recovery.ts";
+import { readCrewAgents } from "../../runtime/crew-agent-records.ts";
+import type { CrewAgentRecord } from "../../runtime/crew-agent-runtime.ts";
+import { evictStaleLiveAgentHandles } from "../../runtime/live-agent-manager.ts";
+import type { ManifestCache } from "../../runtime/manifest-cache.ts";
+import { isDisplayActiveRun } from "../../runtime/process-status.ts";
+import type { TeamRunManifest } from "../../state/types.ts";
+import type { RunSnapshotCache } from "../snapshot-types.ts";
+import type { WidgetRun } from "./widget-types.ts";
+
+let lastStaleReconcileAt = 0;
+const STALE_RECONCILE_INTERVAL_MS = 60_000;
+
+function agentsFor(run: TeamRunManifest): CrewAgentRecord[] {
+	try {
+		return readCrewAgents(run);
+	} catch {
+		return [];
+	}
+}
+
+/**
+ * Get active widget runs for display.
+ */
+export function activeWidgetRuns(
+	cwd: string,
+	manifestCache?: ManifestCache,
+	snapshotCache?: RunSnapshotCache,
+	preloadedManifests?: TeamRunManifest[],
+	workspaceId?: string,
+): WidgetRun[] {
+	evictStaleLiveAgentHandles();
+
+	const now = Date.now();
+	if (now - lastStaleReconcileAt > STALE_RECONCILE_INTERVAL_MS && manifestCache) {
+		lastStaleReconcileAt = now;
+		try {
+			reconcileAllStaleRuns(cwd, manifestCache);
+		} catch {
+			/* non-critical */
+		}
+	}
+
+	let runs = preloadedManifests ?? (manifestCache ? manifestCache.list(20) : listRecentRuns(cwd, 20));
+	if (workspaceId) {
+		runs = runs.filter((run) => !run.ownerSessionId || run.ownerSessionId === workspaceId);
+	}
+
+	return runs
+		.map((run) => {
+			try {
+				const snapshot = snapshotCache?.get(run.runId);
+				if (snapshot) {
+					return {
+						run: snapshot.manifest,
+						agents: snapshot.agents,
+						snapshot,
+					};
+				}
+				// P0-6: render from snapshots only — never read disk on every
+				// render tick. When the snapshot cache is provided but hasn't
+				// populated yet (first frame after `updateCrewWidget`), drop the
+				// run from the result so the widget paints "(loading…)" instead
+				// of calling `agentsFor(run) → readCrewAgents`. Legacy callers
+				// (no snapshotCache) keep the disk-read fallback for tests/dev.
+				if (snapshotCache) return null;
+				return { run, agents: agentsFor(run) };
+			} catch {
+				if (snapshotCache) return null;
+				return { run, agents: agentsFor(run) };
+			}
+		})
+		.filter((item): item is WidgetRun => item !== null && isDisplayActiveRun(item.run, item.agents));
+}
+
+/**
+ * Build a status summary string for the status bar.
+ */
+export function statusSummary(runs: WidgetRun[]): string {
+	const agents = runs.flatMap((item) => item.agents);
+	const runningAgents = agents.filter((a) => a.status === "running").length;
+	const queuedAgents = agents.filter((a) => a.status === "queued" || a.status === "waiting").length;
+	const completedAgents = agents.filter((a) => a.status === "completed").length;
+	const totalAgents = agents.length;
+	const totalRuns = runs.length;
+	const model = agents
+		.find((a) => a.model)
+		?.model?.split("/")
+		.at(-1);
+	const parts = [`⚙ ${runningAgents}r`];
+	if (queuedAgents > 0) parts.push(`${queuedAgents}q`);
+	if (completedAgents > 0) parts.push(`${completedAgents}/${totalAgents}done`);
+	if (totalRuns > 1) parts.push(`${totalRuns}runs`);
+	if (model) parts.push(model);
+	return parts.join(" · ");
+}
+
+/**
+ * Build the short run label (team/workflow).
+ */
+export function shortRunLabel(run: TeamRunManifest): string {
+	return `${run.team}/${run.workflow ?? "none"}`;
+}

package/src/ui/widget/widget-renderer.ts

@@ -0,0 +1,182 @@
+/**
+ * Widget rendering — builds and colorizes widget lines.
+ *
+ * Extracted from crew-widget.ts.
+ */
+
+import { listLiveAgents } from "../../runtime/live-agent-manager.ts";
+import { isFinishedRunStatus } from "../../runtime/process-status.ts";
+import { truncate } from "../../utils/visual.ts";
+import { Box, Text } from "../layout-primitives.ts";
+import { spinnerFrame } from "../spinner.ts";
+import { colorizeStatusGlyphs, iconForStatus } from "../status-colors.ts";
+import type { CrewTheme } from "../theme-adapter.ts";
+import { agentActivity, agentStats, notificationBadge } from "./widget-formatters.ts";
+import { activeWidgetRuns, shortRunLabel } from "./widget-model.ts";
+import type { WidgetRun } from "./widget-types.ts";
+
+const MAX_AGENTS_DISPLAY = 3;
+const FINISHED_LINGER_MAX_AGE = 1;
+/** Default terminal width when caller doesn't pass one explicitly. Keep <= 116
+ * (the same default used elsewhere in pi-crew tool renderers) so we never paint
+ * a line wider than the smallest expected TUI. Callers SHOULD pass the real
+ * width when known (via ctx.width || process.stdout.columns). */
+export const DEFAULT_WIDGET_WIDTH = 100;
+/** Cap per-component text so a single field cannot blow past width on its own. */
+export const TASK_DESC_MAX = 60;
+const ERROR_LINGER_MAX_AGE = 2;
+const ERROR_STATUSES = new Set(["failed", "cancelled", "stopped", "needs_attention"]);
+
+// ── Header ────────────────────────────────────────────────────────────
+
+export function widgetHeader(runs: WidgetRun[], runningGlyph: string, maxLines = 20, notificationCount = 0): string {
+	const agents = runs.flatMap((item) => item.agents);
+	const runningAgents = agents.filter((a) => a.status === "running").length;
+	const queuedAgents = agents.filter((a) => a.status === "queued").length;
+	const waitingAgents = agents.filter((a) => a.status === "waiting").length;
+	const completedAgents = agents.filter((a) => a.status === "completed").length;
+	const parts = [`${runningAgents} running`];
+	if (queuedAgents) parts.push(`${queuedAgents} queued`);
+	if (waitingAgents) parts.push(`${waitingAgents} waiting`);
+	if (completedAgents) parts.push(`${completedAgents}/${agents.length} done`);
+	return `${runningGlyph} Crew agents${notificationBadge(notificationCount)} · ${parts.join(" · ")} · /team-dashboard`;
+}
+
+// ── Line builder ──────────────────────────────────────────────────────
+
+export function buildWidgetLines(
+	cwd: string,
+	frame = 0,
+	maxLines = 8,
+	providedRuns?: WidgetRun[],
+	notificationCount = 0,
+	width = DEFAULT_WIDGET_WIDTH,
+): string[] {
+	// Match the legacy `buildCrewWidgetLines` API: when no runs are supplied,
+	// auto-fetch via activeWidgetRuns(cwd). Otherwise widgets calling with
+	// only `(cwd, frame)` would render an empty line set (regression vs. the
+	// pre-refactor implementation that called activeWidgetRuns here).
+	const runs = providedRuns ?? activeWidgetRuns(cwd);
+	if (!runs.length) return [];
+
+	const runningGlyph = spinnerFrame("widget-header");
+	const lines: string[] = [widgetHeader(runs, runningGlyph, maxLines, notificationCount)];
+
+	for (const { run, agents, snapshot } of runs) {
+		const activeAgents = agents.filter((a) => a.status === "running" || a.status === "queued" || a.status === "waiting");
+		const now = Date.now();
+		const finishedAgents = agents.filter((item) => {
+			if (item.status === "running" || item.status === "queued" || item.status === "waiting") return false;
+			if (!item.completedAt) return false;
+			const maxAgeMs = (ERROR_STATUSES.has(item.status) ? ERROR_LINGER_MAX_AGE : FINISHED_LINGER_MAX_AGE) * 60_000;
+			const age = now - new Date(item.completedAt).getTime();
+			return Number.isFinite(age) && age < maxAgeMs;
+		});
+		const completed = agents.filter((a) => a.status === "completed").length;
+		const runGlyph = iconForStatus(run.status, { runningGlyph });
+		const isTerminal = isFinishedRunStatus(run.status);
+		// Run progress line. v1–v3 flickered on snapshot.tasks state, v4 was
+		// too minimal (`0/1 agents` only), v5 duplicated the worker activity
+		// line (tools/tokens/duration already shown one row below). v6 (this)
+		// shows only data that is RUN-level (not already in the per-agent
+		// activity line) and is GUARANTEED stable across ticks:
+		//   - agents count — from `agents` array, always populated, never empty.
+		//   - run elapsed   — from `run.createdAt`, always set on manifest.
+		// Both come from sources with no race window — `agents` is read from
+		// snapshot.agents OR agentsFor(run) (both always return same length
+		// for a healthy run), and `run.createdAt` is immutable. The format
+		// shape `"X/Y agents · Ns"` is therefore truly invariant: same number
+		// of `·`-separated fields, same field meanings, every render tick.
+		//
+		// Bug 022 (timer-fix + label): for TERMINAL runs (failed/cancelled/
+		// completed) the elapsed counter previously kept ticking up forever
+		// from createdAt (a failed run showed `2028s` and climbing, read as
+		// "still running"). Now it FREEZES at updatedAt (when the run
+		// reached its terminal status). The status label is also surfaced
+		// explicitly so the row cannot be misread as an active run.
+		const agentCountText = `${completed}/${agents.length} agents`;
+		const runEndMs = isTerminal ? new Date(run.updatedAt).getTime() : now;
+		const runElapsedMs = Math.max(0, Number.isFinite(runEndMs) ? runEndMs - new Date(run.createdAt).getTime() : 0);
+		const runElapsedText = `${Math.floor(runElapsedMs / 1000)}s`;
+		const statusLabel = isTerminal ? ` · ${run.status}` : "";
+		const progressPart = `${agentCountText} · ${runElapsedText}${statusLabel}`;
+		lines.push(truncate(`├─ ${runGlyph} ${shortRunLabel(run)} · ${progressPart} · ${run.runId.slice(-8)}`, width));
+
+		const liveForRun = listLiveAgents().filter((a) => a.runId === run.runId);
+
+		// L-4: prioritize RUNNING > QUEUED > WAITING within the visible window so the
+		// most relevant live workers are always shown. Finished rows fill only the
+		// leftover budget and never steal slots from running agents.
+		const ACTIVE_PRIORITY: Record<string, number> = {
+			running: 0,
+			queued: 1,
+			waiting: 2,
+		};
+		const prioritizedActive = [...activeAgents].sort((a, b) => (ACTIVE_PRIORITY[a.status] ?? 9) - (ACTIVE_PRIORITY[b.status] ?? 9));
+		// Finished rows only appear in slots not used by active agents (max 2). When
+		// there are >= MAX_AGENTS_DISPLAY live workers, finished rows are suppressed
+		// entirely so they cannot push a live agent's activity line off-screen.
+		const finishedSlots = Math.max(0, Math.min(2, MAX_AGENTS_DISPLAY - activeAgents.length));
+
+		const visibleAgents = prioritizedActive.slice(0, MAX_AGENTS_DISPLAY);
+		for (const [index, agent] of visibleAgents.entries()) {
+			const last = index === visibleAgents.length - 1 && activeAgents.length <= MAX_AGENTS_DISPLAY && finishedSlots === 0;
+			const branch = last ? "└─" : "├─";
+			const agentGlyph = iconForStatus(agent.status, { runningGlyph });
+			const liveHandle = liveForRun.find((h) => h.taskId === agent.taskId);
+			const stats = agentStats(agent, liveHandle);
+			const name = liveHandle?.agent ?? agent.agent;
+			const desc = truncate(liveHandle?.description ?? agent.role ?? "", TASK_DESC_MAX);
+			const _activeMain = truncate(`│  ${branch} ${agentGlyph} ${name}${desc ? ` · ${desc}` : ` · ${agent.role}`}`, width);
+			lines.push(_activeMain);
+			const _activity = truncate(`│     ⊶ ${agentActivity(agent, liveHandle)}${stats ? ` · ${stats}` : ""}`, width);
+			lines.push(_activity);
+		}
+
+		if (activeAgents.length > MAX_AGENTS_DISPLAY) {
+			lines.push(truncate(`│  └─ … +${activeAgents.length - MAX_AGENTS_DISPLAY} more agents`, width));
+		}
+
+		for (const [index, agent] of finishedAgents.slice(0, finishedSlots).entries()) {
+			const liveHandle = liveForRun.find((h) => h.taskId === agent.taskId);
+			const name = liveHandle?.agent ?? agent.agent;
+			const icon =
+				agent.status === "completed" ? "✓" : agent.status === "failed" ? "✗" : agent.status === "needs_attention" ? "⚠" : "▪";
+			const stats = agentStats(agent, liveHandle);
+			const desc = truncate(liveHandle?.description ?? agent.role ?? "", TASK_DESC_MAX);
+			const isLastFinished = index === Math.min(finishedAgents.length, finishedSlots) - 1;
+			const branch = isLastFinished ? "└─" : "├─";
+			const _finished = truncate(`│  ${branch} ${icon} ${name} · ${desc}${stats ? ` · ${stats}` : ""}`, width);
+			lines.push(_finished);
+		}
+
+		if (lines.length >= maxLines) break;
+	}
+
+	return lines.slice(0, maxLines);
+}
+
+// ── Colorization ──────────────────────────────────────────────────────
+
+export function colorWidgetLine(line: string, index: number, theme: CrewTheme): string {
+	let result = line;
+	if (index === 0) {
+		result = result.replace("Crew agents", theme.bold(theme.fg("accent", "Crew agents")));
+	}
+	// Shared glyph colorizer covers ALL status glyphs — including ⏳ (waiting),
+	// ⚠ (needs_attention), and the braille spinner range ⠁-⣿ (running) — which the
+	// previous local statusGlyphColor map + regex omitted (F-1, V-3).
+	result = colorizeStatusGlyphs(result, theme);
+	if (index === 0) {
+		result = theme.fg("accent", result);
+	}
+	return result;
+}
+
+export function renderLines(lines: string[], width: number): string[] {
+	const box = new Box(0, 0);
+	for (const line of lines) {
+		box.addChild(new Text(line));
+	}
+	return box.render(width);
+}

package/src/ui/widget/widget-types.ts

@@ -0,0 +1,36 @@
+/**
+ * Widget type definitions.
+ */
+
+import type { CrewAgentRecord } from "../../runtime/crew-agent-runtime.ts";
+import type { ManifestCache } from "../../runtime/manifest-cache.ts";
+import type { TeamRunManifest } from "../../state/types.ts";
+import type { RunSnapshotCache, RunUiSnapshot } from "../snapshot-types.ts";
+
+export interface WidgetRun {
+	run: TeamRunManifest;
+	agents: CrewAgentRecord[];
+	snapshot?: RunUiSnapshot;
+}
+
+export interface CrewWidgetModel {
+	cwd: string;
+	frame: number;
+	maxLines: number;
+	notificationCount?: number;
+	manifestCache?: ManifestCache;
+	snapshotCache?: RunSnapshotCache;
+	preloadManifests?: TeamRunManifest[];
+}
+
+export interface CrewWidgetState {
+	frame: number;
+	lastPlacement?: string;
+	lastVisibility?: "hidden" | "visible";
+	lastKey?: string;
+	lastMaxLines?: number;
+	lastCwd?: string;
+	legacyCleared?: boolean;
+	model?: CrewWidgetModel;
+	notificationCount?: number;
+}

package/src/utils/bm25-search.ts

@@ -0,0 +1,235 @@
+import type { AgentConfig } from "../agents/agent-config.ts";
+import type { TeamConfig } from "../teams/team-config.ts";
+
+interface SearchDocument {
+	id: string;
+	fields: Record<string, string>;
+}
+
+interface SearchResult<T> {
+	item: T;
+	score: number;
+	matchedOn: string[];
+}
+
+interface BM25Config {
+	k1?: number;
+	b?: number;
+}
+
+export class BM25Search<T extends SearchDocument> {
+	private readonly documents: T[];
+	private readonly fieldWeights: Record<string, number>;
+	private readonly avgDocLen: number;
+	private readonly k1: number;
+	private readonly b: number;
+	private readonly docLenMap: Map<string, number>;
+	private readonly N: number;
+	/**
+	 * Precomputed document frequency per term. Cached at construction time
+	 * to avoid O(N) recomputation on every search() call. The cache is
+	 * immutable for a given document corpus, so it's safe to share across
+	 * search() invocations.
+	 */
+	private readonly dfCache: Map<string, number>;
+
+	constructor(documents: T[], fieldWeights: Record<string, number> = {}, config: BM25Config = {}) {
+		this.documents = documents;
+		this.fieldWeights = fieldWeights;
+		this.k1 = config.k1 ?? 1.5;
+		this.b = config.b ?? 0.75;
+		this.N = documents.length;
+
+		this.docLenMap = new Map();
+		this.dfCache = new Map();
+
+		for (const doc of documents) {
+			const fieldValues = Object.values(doc.fields).join(" ");
+			const len = fieldValues.split(/\s+/).filter(Boolean).length;
+			this.docLenMap.set(doc.id, len);
+		}
+
+		const totalLen = [...this.docLenMap.values()].reduce((a, b) => a + b, 0);
+		this.avgDocLen = totalLen / this.N || 1;
+
+		// Precompute df for all terms in the corpus. We do this once instead
+		// of on-demand to avoid the O(Q * N * field_count) cost per search call.
+		this.precomputeDocumentFrequencies();
+	}
+
+	/**
+	 * Build a map of term -> document frequency. O(N * avg_terms * field_count).
+	 * Called once in the constructor.
+	 */
+	private precomputeDocumentFrequencies(): void {
+		for (const doc of this.documents) {
+			for (const field of Object.keys(this.fieldWeights)) {
+				const text = (doc.fields[field] ?? "").toLowerCase();
+				// Extract unique terms via split on whitespace
+				const terms = new Set(text.split(/\s+/).filter(Boolean));
+				for (const term of terms) {
+					if (term.length === 0) continue;
+					this.dfCache.set(term, (this.dfCache.get(term) ?? 0) + 1);
+				}
+			}
+		}
+	}
+
+	/**
+	 * Get document frequency for a term. Returns the precomputed value.
+	 * O(1) lookup.
+	 */
+	private df(term: string): number {
+		return this.dfCache.get(term.toLowerCase()) ?? 0;
+	}
+
+	search(query: string, options?: { limit?: number; minScore?: number }): SearchResult<T>[] {
+		const queryTerms = query.toLowerCase().split(/\s+/).filter(Boolean);
+		if (queryTerms.length === 0) return [];
+
+		const results: SearchResult<T>[] = [];
+
+		for (const doc of this.documents) {
+			let totalScore = 0;
+			const matchedOn: string[] = [];
+
+			for (const [field, weight] of Object.entries(this.fieldWeights)) {
+				const text = doc.fields[field] ?? "";
+				const textLower = text.toLowerCase();
+				let fieldScore = 0;
+
+				for (const term of queryTerms) {
+					// Use indexOf for linear-time substring counting instead of regex
+					const termLower = term.toLowerCase();
+					let tf = 0;
+					let pos = 0;
+					while ((pos = textLower.indexOf(termLower, pos)) !== -1) {
+						tf++;
+						pos += termLower.length;
+						// Cap tf to prevent runaway on repeated patterns
+						if (tf > 100) break;
+					}
+					if (tf === 0) continue;
+
+					const df = this.df(termLower);
+					if (df === 0) continue;
+
+					const idf = Math.log((this.N - df + 0.5) / (df + 0.5) + 1);
+					const docLen = this.docLenMap.get(doc.id) ?? this.avgDocLen;
+					const numerator = tf * (this.k1 + 1);
+					const denominator = tf + this.k1 * (1 - this.b + (this.b * docLen) / this.avgDocLen);
+					fieldScore += idf * (numerator / denominator);
+
+					matchedOn.push(field);
+				}
+
+				totalScore += fieldScore * (weight || 1);
+			}
+
+			if (totalScore > 0) {
+				results.push({
+					item: doc,
+					score: totalScore,
+					matchedOn: [...new Set(matchedOn)],
+				});
+			}
+		}
+
+		results.sort((a, b) => b.score - a.score);
+
+		const limit = options?.limit ?? 10;
+		const minScore = options?.minScore ?? 0.01;
+
+		return results.filter((r) => r.score >= minScore).slice(0, limit);
+	}
+}
+
+// Agent search interface
+interface AgentSearchResult {
+	agent: AgentConfig;
+	score: number;
+	matchedOn: string[];
+}
+
+/**
+ * Search agents using BM25 ranking.
+ * Uses dynamic import to avoid ESM/CJS issues at module load time.
+ */
+export async function searchAgents(query: string, options?: { limit?: number }): Promise<AgentSearchResult[]> {
+	// LAZY: defer dynamic import of ../agents/discover-agents.ts to its call site.
+	const { discoverAgents, allAgents } = await import("../agents/discover-agents.ts");
+	const discovery = discoverAgents(process.cwd());
+	const all = allAgents(discovery);
+
+	const docs: (SearchDocument & { agent: AgentConfig })[] = all.map((agent: AgentConfig) => ({
+		id: agent.name,
+		fields: {
+			name: agent.name,
+			description: agent.description ?? "",
+			skills: (agent.skills ?? []).join(" "),
+		},
+		agent,
+	}));
+
+	const engine = new BM25Search(docs, {
+		name: 3.0,
+		description: 1.5,
+		skills: 1.0,
+	});
+
+	const results = engine.search(query, {
+		limit: options?.limit ?? 10,
+		minScore: 0.1,
+	});
+
+	return results.map((r) => ({
+		agent: r.item.agent,
+		score: r.score,
+		matchedOn: r.matchedOn,
+	}));
+}
+
+// Team search interface
+interface TeamSearchResult {
+	team: TeamConfig;
+	score: number;
+	matchedOn: string[];
+}
+
+/**
+ * Search teams using BM25 ranking.
+ * Uses dynamic import to avoid ESM/CJS issues at module load time.
+ */
+export async function searchTeams(query: string, options?: { limit?: number }): Promise<TeamSearchResult[]> {
+	// LAZY: defer dynamic import of ../teams/discover-teams.ts to its call site.
+	const { discoverTeams, allTeams } = await import("../teams/discover-teams.ts");
+	const discovery = discoverTeams(process.cwd());
+	const all = allTeams(discovery);
+
+	const docs: (SearchDocument & { team: TeamConfig })[] = all.map((team: TeamConfig) => ({
+		id: team.name,
+		fields: {
+			name: team.name,
+			description: team.description ?? "",
+			roles: (team.roles ?? []).map((r: { name: string }) => r.name).join(" "),
+		},
+		team,
+	}));
+
+	const engine = new BM25Search(docs, {
+		name: 2.0,
+		description: 1.5,
+		roles: 1.0,
+	});
+
+	const results = engine.search(query, {
+		limit: options?.limit ?? 5,
+		minScore: 0.1,
+	});
+
+	return results.map((r) => ({
+		team: r.item.team,
+		score: r.score,
+		matchedOn: r.matchedOn,
+	}));
+}

package/src/utils/completion-dedupe.ts

@@ -0,0 +1,63 @@
+interface CompletionDataLike {
+	id?: unknown;
+	agent?: unknown;
+	timestamp?: unknown;
+	sessionId?: unknown;
+	taskIndex?: unknown;
+	totalTasks?: unknown;
+	success?: unknown;
+}
+
+function asNonEmptyString(value: unknown): string | undefined {
+	if (typeof value !== "string") return undefined;
+	const trimmed = value.trim();
+	return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function asFiniteNumber(value: unknown): number | undefined {
+	if (typeof value !== "number") return undefined;
+	return Number.isFinite(value) ? value : undefined;
+}
+
+export function buildCompletionKey(data: CompletionDataLike, fallback: string): string {
+	const id = asNonEmptyString(data.id);
+	if (id) return `id:${id}`;
+	const sessionId = asNonEmptyString(data.sessionId) ?? "no-session";
+	const agent = asNonEmptyString(data.agent) ?? "unknown";
+	const timestamp = asFiniteNumber(data.timestamp);
+	const taskIndex = asFiniteNumber(data.taskIndex);
+	const totalTasks = asFiniteNumber(data.totalTasks);
+	const success = typeof data.success === "boolean" ? (data.success ? "1" : "0") : "?";
+	return [
+		"meta",
+		sessionId,
+		agent,
+		timestamp !== undefined ? String(timestamp) : "no-ts",
+		taskIndex !== undefined ? String(taskIndex) : "-",
+		totalTasks !== undefined ? String(totalTasks) : "-",
+		success,
+		fallback,
+	].join(":");
+}
+
+export function pruneSeenMap(seen: Map<string, number>, now: number, ttlMs: number): void {
+	for (const [key, ts] of seen.entries()) {
+		if (now - ts > ttlMs) seen.delete(key);
+	}
+}
+
+export function markSeenWithTtl(seen: Map<string, number>, key: string, now: number, ttlMs: number): boolean {
+	pruneSeenMap(seen, now, ttlMs);
+	if (seen.has(key)) return true;
+	seen.set(key, now);
+	return false;
+}
+
+export function getGlobalSeenMap(storeKey: string): Map<string, number> {
+	const globalStore = globalThis as Record<string, unknown>;
+	const existing = globalStore[storeKey];
+	if (existing instanceof Map) return existing as Map<string, number>;
+	const map = new Map<string, number>();
+	globalStore[storeKey] = map;
+	return map;
+}