@fitchmultz/pi-subagents 0.44.7 → 0.45.0

package/dist/runs/background/async-status.js

@@ -1,442 +1,3 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { formatDuration, formatModelThinking, formatTokens, shortenPath } from "../../shared/formatters.js";
-import { formatRunAction, formatActivityLabel, formatParallelOutcome } from "../../shared/status-format.js";
-import {} from "../../shared/types.js";
-import { attachRootChildrenToSteps, findNestedRouteForRootId, projectNestedRegistryForRoot, sanitizeSummary } from "../shared/nested-events.js";
-import { formatNestedRunStatusLines } from "../shared/nested-render.js";
-import { flatToLogicalStepIndex, normalizeParallelGroups } from "./parallel-groups.js";
-import { reconcileAsyncRun, reconcileNestedAsyncDescendants } from "./stale-run-reconciler.js";
-import { asyncRunRoots, readAsyncRunRecord } from "./async-resume.js";
-import { RESULTS_DIR } from "../../shared/types.js";
-import { getRunMetadataDir, readRunJson } from "../shared/supervisor-questions.js";
-import { runSynchronously } from "../../shared/cooperative.js";
-function getErrorMessage(error) {
-    return error instanceof Error ? error.message : String(error);
-}
-function isNotFoundError(error) {
-    return typeof error === "object"
-        && error !== null
-        && "code" in error
-        && error.code === "ENOENT";
-}
-function isAsyncRunDir(root, entry) {
-    const entryPath = path.join(root, entry);
-    try {
-        return fs.statSync(entryPath).isDirectory();
-    }
-    catch (error) {
-        if (isNotFoundError(error))
-            return false;
-        throw new Error(`Failed to inspect async run path '${entryPath}': ${getErrorMessage(error)}`, {
-            cause: error instanceof Error ? error : undefined,
-        });
-    }
-}
-function outputFileMtime(outputFile) {
-    if (!outputFile)
-        return undefined;
-    try {
-        return fs.statSync(outputFile).mtimeMs;
-    }
-    catch (error) {
-        if (isNotFoundError(error))
-            return undefined;
-        throw new Error(`Failed to inspect async output file '${outputFile}': ${getErrorMessage(error)}`, {
-            cause: error instanceof Error ? error : undefined,
-        });
-    }
-}
-function deriveAsyncActivityState(asyncDir, status) {
-    if (status.state !== "running")
-        return { activityState: status.activityState, lastActivityAt: status.lastActivityAt };
-    const outputPath = status.outputFile ? (path.isAbsolute(status.outputFile) ? status.outputFile : path.join(asyncDir, status.outputFile)) : undefined;
-    const currentStep = typeof status.currentStep === "number" ? status.steps?.[status.currentStep] : undefined;
-    return {
-        activityState: status.activityState,
-        lastActivityAt: status.lastActivityAt ?? outputFileMtime(outputPath) ?? currentStep?.lastActivityAt ?? currentStep?.startedAt ?? status.startedAt,
-    };
-}
-function assertOptionalFields(record, fields, valid, expected, source) {
-    for (const field of fields) {
-        if (record[field] !== undefined && !valid(record[field])) {
-            throw new Error(`Invalid async status '${source}': ${field} must be ${expected}.`);
-        }
-    }
-}
-function validateTokenUsage(value, field, source) {
-    if (value === undefined)
-        return;
-    if (!value || typeof value !== "object" || Array.isArray(value)) {
-        throw new Error(`Invalid async status '${source}': ${field} must be an object.`);
-    }
-    const tokens = value;
-    if (![tokens.input, tokens.output, tokens.total].every((part) => typeof part === "number" && Number.isFinite(part))) {
-        throw new Error(`Invalid async status '${source}': ${field} must contain finite input, output, and total numbers.`);
-    }
-}
-function validateStatusForSummary(status, source) {
-    if (!status || typeof status !== "object" || Array.isArray(status)) {
-        throw new Error(`Invalid async status '${source}': status must be an object.`);
-    }
-    const record = status;
-    assertOptionalFields(record, ["runId", "sessionId", "currentTool", "currentPath", "cwd", "sessionDir", "outputFile", "sessionFile"], (value) => typeof value === "string", "a string", source);
-    assertOptionalFields(record, ["lastActivityAt", "currentToolStartedAt", "turnCount", "toolCount", "startedAt", "endedAt", "lastUpdate", "pid", "currentStep", "chainStepCount"], (value) => typeof value === "number" && Number.isFinite(value), "a finite number", source);
-    if (typeof record.runId !== "string")
-        throw new Error(`Invalid async status '${source}': runId must be a string.`);
-    if (typeof record.startedAt !== "number")
-        throw new Error(`Invalid async status '${source}': startedAt must be a number.`);
-    if (!["single", "parallel", "chain"].includes(record.mode))
-        throw new Error(`Invalid async status '${source}': mode is invalid.`);
-    if (!["queued", "running", "complete", "failed", "blocked", "paused"].includes(record.state))
-        throw new Error(`Invalid async status '${source}': state is invalid.`);
-    if (record.activityState !== undefined && record.activityState !== "needs_attention")
-        throw new Error(`Invalid async status '${source}': activityState is invalid.`);
-    validateTokenUsage(record.totalTokens, "totalTokens", source);
-    if (record.steps !== undefined && !Array.isArray(record.steps))
-        throw new Error(`Invalid async status '${source}': steps must be an array.`);
-    const steps = Array.isArray(record.steps) ? record.steps : [];
-    if (record.currentStep !== undefined && (typeof record.currentStep !== "number" || !Number.isSafeInteger(record.currentStep) || record.currentStep < 0 || record.currentStep >= steps.length)) {
-        throw new Error(`Invalid async status '${source}': currentStep must index a persisted step.`);
-    }
-    if (record.chainStepCount !== undefined && (typeof record.chainStepCount !== "number" || !Number.isSafeInteger(record.chainStepCount) || record.chainStepCount < 1)) {
-        throw new Error(`Invalid async status '${source}': chainStepCount must be a positive safe integer.`);
-    }
-    for (const [index, value] of steps.entries()) {
-        if (!value || typeof value !== "object" || Array.isArray(value))
-            throw new Error(`Invalid async status '${source}': steps[${index}] must be an object.`);
-        const step = value;
-        const stepSource = `${source} (steps[${index}])`;
-        assertOptionalFields(step, ["agent", "phase", "label", "outputName", "sessionFile", "currentTool", "currentToolArgs", "currentPath", "model", "thinking", "error"], (field) => typeof field === "string", "a string", stepSource);
-        assertOptionalFields(step, ["lastActivityAt", "currentToolStartedAt", "turnCount", "toolCount", "startedAt", "endedAt", "durationMs"], (field) => typeof field === "number" && Number.isFinite(field), "a finite number", stepSource);
-        if (typeof step.agent !== "string")
-            throw new Error(`Invalid async status '${source}': steps[${index}].agent must be a string.`);
-        if (!["pending", "running", "complete", "completed", "failed", "blocked", "paused", "timed-out"].includes(step.status))
-            throw new Error(`Invalid async status '${source}': steps[${index}].status is invalid.`);
-        if (step.activityState !== undefined && step.activityState !== "needs_attention")
-            throw new Error(`Invalid async status '${source}': steps[${index}].activityState is invalid.`);
-        if (step.structured !== undefined && typeof step.structured !== "boolean")
-            throw new Error(`Invalid async status '${source}': steps[${index}].structured must be a boolean.`);
-        for (const field of ["recentOutput", "skills", "attemptedModels"]) {
-            if (step[field] !== undefined && (!Array.isArray(step[field]) || !step[field].every((item) => typeof item === "string"))) {
-                throw new Error(`Invalid async status '${source}': steps[${index}].${field} must be an array of strings.`);
-            }
-        }
-        if (step.recentTools !== undefined) {
-            const validRecentTools = Array.isArray(step.recentTools) && step.recentTools.every((tool) => tool
-                && typeof tool === "object"
-                && !Array.isArray(tool)
-                && typeof tool.tool === "string"
-                && typeof tool.args === "string"
-                && typeof tool.endMs === "number"
-                && Number.isFinite(tool.endMs));
-            if (!validRecentTools)
-                throw new Error(`Invalid async status '${source}': steps[${index}].recentTools is invalid.`);
-        }
-        if (step.children !== undefined && !Array.isArray(step.children))
-            throw new Error(`Invalid async status '${source}': steps[${index}].children must be an array.`);
-        validateTokenUsage(step.tokens, `steps[${index}].tokens`, source);
-    }
-}
-export function asyncStatusToSummary(asyncDir, status, nestedWarnings = [], projectedChildren) {
-    validateStatusForSummary(status, path.join(asyncDir, "status.json"));
-    const { activityState, lastActivityAt } = deriveAsyncActivityState(asyncDir, status);
-    const steps = status.steps ?? [];
-    const chainStepCount = status.chainStepCount ?? steps.length;
-    const parallelGroups = normalizeParallelGroups(status.parallelGroups, steps.length, chainStepCount);
-    let nestedChildren = projectedChildren ?? [];
-    if (projectedChildren === undefined && nestedWarnings.length === 0) {
-        try {
-            nestedChildren = projectNestedRegistryForRoot(status.runId || path.basename(asyncDir))?.children ?? [];
-        }
-        catch (error) {
-            nestedWarnings.push(`Nested status unavailable: ${getErrorMessage(error)}`);
-        }
-    }
-    const summarizedSteps = steps.map((step, index) => {
-        const stepActivityState = step.activityState;
-        const stepLastActivityAt = step.lastActivityAt;
-        const stepChildren = (step.children ?? []).map((child) => sanitizeSummary(child)).filter((child) => Boolean(child));
-        return {
-            index,
-            agent: step.agent,
-            ...(step.sessionFile ? { sessionFile: step.sessionFile } : {}),
-            ...(step.label ? { label: step.label } : {}),
-            ...(step.phase ? { phase: step.phase } : {}),
-            ...(step.outputName ? { outputName: step.outputName } : {}),
-            ...(step.structured ? { structured: step.structured } : {}),
-            status: step.status,
-            ...(stepActivityState ? { activityState: stepActivityState } : {}),
-            ...(stepLastActivityAt ? { lastActivityAt: stepLastActivityAt } : {}),
-            ...(step.currentTool ? { currentTool: step.currentTool } : {}),
-            ...(step.currentToolArgs ? { currentToolArgs: step.currentToolArgs } : {}),
-            ...(step.currentToolStartedAt ? { currentToolStartedAt: step.currentToolStartedAt } : {}),
-            ...(step.currentPath ? { currentPath: step.currentPath } : {}),
-            ...(step.recentTools ? { recentTools: step.recentTools.map((tool) => ({ ...tool })) } : {}),
-            ...(step.recentOutput ? { recentOutput: [...step.recentOutput] } : {}),
-            ...(step.turnCount !== undefined ? { turnCount: step.turnCount } : {}),
-            ...(step.toolCount !== undefined ? { toolCount: step.toolCount } : {}),
-            ...(step.durationMs !== undefined ? { durationMs: step.durationMs } : {}),
-            ...(step.tokens ? { tokens: step.tokens } : {}),
-            ...(step.skills ? { skills: step.skills } : {}),
-            ...(step.model ? { model: step.model } : {}),
-            ...(step.thinking ? { thinking: step.thinking } : {}),
-            ...(step.attemptedModels ? { attemptedModels: step.attemptedModels } : {}),
-            ...(step.error ? { error: step.error } : {}),
-            ...(stepChildren.length ? { children: stepChildren } : {}),
-        };
-    });
-    attachRootChildrenToSteps(status.runId || path.basename(asyncDir), summarizedSteps, nestedChildren);
-    return {
-        id: status.runId || path.basename(asyncDir),
-        asyncDir,
-        ...(typeof status.pid === "number" ? { pid: status.pid } : {}),
-        ...(status.sessionId ? { sessionId: status.sessionId } : {}),
-        state: status.state,
-        activityState,
-        lastActivityAt,
-        currentTool: status.currentTool,
-        currentToolStartedAt: status.currentToolStartedAt,
-        currentPath: status.currentPath,
-        turnCount: status.turnCount,
-        toolCount: status.toolCount,
-        mode: status.mode,
-        cwd: status.cwd,
-        startedAt: status.startedAt,
-        lastUpdate: status.lastUpdate,
-        endedAt: status.endedAt,
-        currentStep: status.currentStep,
-        ...(status.chainStepCount !== undefined ? { chainStepCount: status.chainStepCount } : {}),
-        ...(parallelGroups.length ? { parallelGroups } : {}),
-        steps: summarizedSteps,
-        ...(nestedChildren.length ? { nestedChildren } : {}),
-        ...(nestedWarnings.length ? { nestedWarnings } : {}),
-        ...(status.sessionDir ? { sessionDir: status.sessionDir } : {}),
-        ...(status.outputFile ? { outputFile: status.outputFile } : {}),
-        ...(status.totalTokens ? { totalTokens: status.totalTokens } : {}),
-        ...(status.sessionFile ? { sessionFile: status.sessionFile } : {}),
-    };
-}
-function sortRuns(runs) {
-    const rank = (state) => {
-        switch (state) {
-            case "running": return 0;
-            case "queued": return 1;
-            case "failed": return 2;
-            case "blocked": return 2;
-            case "paused": return 2;
-            case "complete": return 3;
-        }
-    };
-    return [...runs].sort((a, b) => {
-        const byState = rank(a.state) - rank(b.state);
-        if (byState !== 0)
-            return byState;
-        const aTime = a.lastUpdate ?? a.endedAt ?? a.startedAt;
-        const bTime = b.lastUpdate ?? b.endedAt ?? b.startedAt;
-        return bTime - aTime;
-    });
-}
-/** Retry new/unpublished runs without retaining payloads or negative ownership facts. */
-export function createAsyncRunDiscovery(asyncDirRoot, options = {}) {
-    const owners = new Map();
-    const discovered = new Set();
-    const sessionIds = new Set([options.sessionId, options.ownerSessionId].filter((id) => Boolean(id)));
-    // A legacy file-path-only query cannot classify native UUID owners as foreign.
-    const ownerSessionId = options.ownerSessionId ?? (options.sessionId && !path.isAbsolute(options.sessionId) ? options.sessionId : undefined);
-    function* steps() {
-        const receipts = new Set(options.receiptRunIds?.());
-        const entries = new Set(receipts);
-        for (const root of asyncRunRoots(asyncDirRoot))
-            try {
-                for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
-                    yield;
-                    try {
-                        if (entry.isDirectory() || (entry.isSymbolicLink() && isAsyncRunDir(root, entry.name)))
-                            entries.add(entry.name);
-                    }
-                    catch (error) {
-                        if (!options.skipInvalid)
-                            throw error;
-                        console.error(`Skipping invalid async run '${path.join(root, entry.name)}':`, error);
-                    }
-                }
-            }
-            catch (error) {
-                if (isNotFoundError(error))
-                    continue;
-                throw new Error(`Failed to list async runs in '${asyncDirRoot}': ${getErrorMessage(error)}`, {
-                    cause: error instanceof Error ? error : undefined,
-                });
-            }
-        const records = [];
-        for (const entry of entries) {
-            yield;
-            try {
-                if (discovered.has(entry))
-                    continue;
-                let owner = owners.get(entry);
-                if (!owner && ownerSessionId) {
-                    try {
-                        const saved = readRunJson(path.join(getRunMetadataDir(entry), "question-owner.json"));
-                        if (typeof saved?.sessionId === "string" && saved.sessionId.trim()) {
-                            owner = saved.sessionId;
-                            owners.set(entry, owner);
-                        }
-                    }
-                    catch {
-                        // Missing/unusable identity metadata retains the legacy status fallback.
-                    }
-                }
-                const receipt = receipts.has(entry);
-                const matchingOwner = owner !== undefined && owner === ownerSessionId;
-                if (owner && !matchingOwner && !receipt)
-                    continue;
-                const record = readAsyncRunRecord(entry, asyncDirRoot, options.resultsDir ?? RESULTS_DIR);
-                const { asyncDir } = record.location;
-                if (!asyncDir)
-                    continue;
-                if (sessionIds.size && !receipt && !matchingOwner && !sessionIds.has(record.status?.sessionId ?? ""))
-                    continue;
-                if (options.reconcile !== false) {
-                    record.status = reconcileAsyncRun(asyncDir, { resultsDir: options.resultsDir, kill: options.kill, now: options.now }, record).status;
-                }
-                if (record.status) {
-                    validateStatusForSummary(record.status, path.join(asyncDir, "status.json"));
-                    discovered.add(entry);
-                }
-                records.push(record);
-            }
-            catch (error) {
-                if (!options.skipInvalid)
-                    throw error;
-                console.error(`Skipping invalid async run '${entry}':`, error);
-            }
-        }
-        return records;
-    }
-    return Object.assign(() => runSynchronously(steps()), { steps });
-}
-export function listAsyncRuns(asyncDirRoot, options = {}) {
-    const allowedStates = options.states ? new Set(options.states) : undefined;
-    const runs = [];
-    for (const { location, status } of options.records ?? createAsyncRunDiscovery(asyncDirRoot, options)()) {
-        const asyncDir = location.asyncDir;
-        if (!asyncDir)
-            continue;
-        try {
-            if (!status)
-                continue;
-            const nestedWarnings = [];
-            let nestedChildren;
-            try {
-                const nestedRoute = findNestedRouteForRootId(status.runId || path.basename(asyncDir));
-                if (nestedRoute)
-                    nestedChildren = reconcileNestedAsyncDescendants(nestedRoute, { resultsDir: options.resultsDir, kill: options.kill, now: options.now });
-            }
-            catch (error) {
-                nestedWarnings.push(`Nested status unavailable: ${getErrorMessage(error)}`);
-            }
-            const summary = asyncStatusToSummary(asyncDir, status, nestedWarnings, nestedChildren);
-            if (allowedStates && !allowedStates.has(summary.state))
-                continue;
-            runs.push(summary);
-        }
-        catch (error) {
-            if (!options.skipInvalid)
-                throw error;
-            console.error(`Skipping invalid async run '${location.resolvedId}':`, error);
-        }
-    }
-    const sorted = sortRuns(runs);
-    return options.limit !== undefined ? sorted.slice(0, options.limit) : sorted;
-}
-export function formatActivityFacts(input) {
-    const facts = [];
-    if (input.currentTool && input.currentToolStartedAt !== undefined)
-        facts.push(`tool ${input.currentTool} ${formatDuration(Math.max(0, Date.now() - input.currentToolStartedAt))}`);
-    else if (input.currentTool)
-        facts.push(`tool ${input.currentTool}`);
-    if (input.currentPath)
-        facts.push(shortenPath(input.currentPath));
-    if (input.turnCount !== undefined)
-        facts.push(`${input.turnCount} turns`);
-    if (input.toolCount !== undefined)
-        facts.push(`${input.toolCount} tools`);
-    const activity = formatActivityLabel(input.lastActivityAt, input.activityState);
-    return activity || facts.length ? [activity, ...facts].filter(Boolean).join(" | ") : undefined;
-}
-function formatStepLine(step) {
-    const display = step.label ? `${step.label} (${step.agent})` : step.agent;
-    const phase = step.phase ? `[${step.phase}] ` : "";
-    const parts = [`${step.index + 1}. ${phase}${display}`, step.status];
-    const activity = formatActivityFacts(step);
-    if (activity)
-        parts.push(activity);
-    const modelThinking = formatModelThinking(step.model, step.thinking);
-    if (modelThinking)
-        parts.push(modelThinking);
-    if (step.durationMs !== undefined)
-        parts.push(formatDuration(step.durationMs));
-    if (step.tokens)
-        parts.push(`${formatTokens(step.tokens.total)} tok`);
-    return parts.join(" | ");
-}
-export function formatAsyncRunOutputPath(run) {
-    if (!run.outputFile)
-        return undefined;
-    return path.isAbsolute(run.outputFile) ? run.outputFile : path.join(run.asyncDir, run.outputFile);
-}
-export function formatAsyncRunProgressLabel(run) {
-    const stepCount = run.steps.length || 1;
-    const chainStepCount = run.chainStepCount ?? stepCount;
-    const groups = normalizeParallelGroups(run.parallelGroups, run.steps.length, chainStepCount);
-    const activeGroup = run.currentStep !== undefined
-        ? groups.find((group) => run.currentStep >= group.start && run.currentStep < group.start + group.count)
-        : undefined;
-    if (activeGroup) {
-        const groupSteps = run.steps.slice(activeGroup.start, activeGroup.start + activeGroup.count);
-        const groupLabel = formatParallelOutcome(groupSteps, activeGroup.count, { showRunning: run.state === "running" });
-        if (run.mode === "parallel")
-            return groupLabel;
-        return `step ${activeGroup.stepIndex + 1}/${chainStepCount} · parallel group: ${groupLabel}`;
-    }
-    if (run.mode === "parallel")
-        return formatParallelOutcome(run.steps, stepCount, { showRunning: run.state === "running" });
-    if (run.mode === "chain" && run.currentStep !== undefined && groups.length > 0) {
-        const logicalStep = flatToLogicalStepIndex(run.currentStep, chainStepCount, groups);
-        return `step ${logicalStep + 1}/${chainStepCount}`;
-    }
-    return run.currentStep !== undefined ? `step ${run.currentStep + 1}/${stepCount}` : `steps ${stepCount}`;
-}
-function formatRunHeader(run) {
-    const stepLabel = formatAsyncRunProgressLabel(run);
-    const cwd = run.cwd ? shortenPath(run.cwd) : shortenPath(run.asyncDir);
-    const activity = formatActivityFacts(run);
-    return `${run.id} | ${run.state}${activity ? ` | ${activity}` : ""} | ${run.mode} | ${stepLabel} | ${cwd}`;
-}
-export function formatAsyncRunList(runs, heading = "Active async runs") {
-    if (runs.length === 0)
-        return `No ${heading.toLowerCase()}.`;
-    const lines = [`${heading}: ${runs.length}`, ""];
-    for (const run of runs) {
-        lines.push(`- ${formatRunHeader(run)}`);
-        lines.push(`  Status: ${formatRunAction("status", run.id)}`);
-        for (const step of run.steps) {
-            lines.push(`  ${formatStepLine(step)}`);
-            lines.push(...formatNestedRunStatusLines(step.children, { indent: "    ", maxLines: 12 }));
-        }
-        const attached = new Set(run.steps.flatMap((step) => step.children?.map((child) => child.id) ?? []));
-        const unattached = run.nestedChildren?.filter((child) => !attached.has(child.id)) ?? [];
-        lines.push(...formatNestedRunStatusLines(unattached, { indent: "  ", maxLines: 12 }));
-        for (const warning of run.nestedWarnings ?? [])
-            lines.push(`  Warning: ${warning}`);
-        const outputPath = formatAsyncRunOutputPath(run);
-        if (outputPath)
-            lines.push(`  output: ${shortenPath(outputPath)}`);
-        if (run.sessionFile)
-            lines.push(`  session: ${shortenPath(run.sessionFile)}`);
-        lines.push("");
-    }
-    return lines.join("\n").trimEnd();
-}
+export { asyncStatusToSummary } from "./async-status-projection.js";
+export { createAsyncRunDiscovery, listAsyncRuns } from "./async-run-discovery.js";
+export { formatActivityFacts, formatAsyncRunOutputPath, formatAsyncRunProgressLabel, formatAsyncRunList, } from "./async-status-render.js";

package/dist/runs/background/async-value.js

@@ -0,0 +1,21 @@
+import { inspect } from "node:util";
+/** Persisted JSON and event payloads enter background lifecycle code here. */
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function errorCode(error) {
+    return isRecord(error) && typeof error.code === "string" ? error.code : undefined;
+}
+export function errorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return typeof error === "string" ? error : inspect(error);
+}
+export function hasText(value) {
+    return value !== undefined && value !== null && value.length > 0;
+}
+export function stringField(record, key) {
+    const value = record[key];
+    return typeof value === "string" ? value : undefined;
+}

package/dist/runs/background/completion-dedupe.js

@@ -1,39 +1,53 @@
 import { createHash } from "node:crypto";
+import { isRecord, hasText } from "./async-value.js";
 function asNonEmptyString(value) {
-    if (typeof value !== "string")
+    if (typeof value !== "string") {
         return undefined;
+    }
     const trimmed = value.trim();
     return trimmed.length > 0 ? trimmed : undefined;
 }
 function asFiniteNumber(value) {
-    if (typeof value !== "number")
+    if (typeof value !== "number") {
         return undefined;
+    }
     return Number.isFinite(value) ? value : undefined;
 }
 function stableStringify(value) {
-    if (value === null || typeof value !== "object")
+    if (value === null || typeof value !== "object") {
         return JSON.stringify(value);
-    if (Array.isArray(value))
+    }
+    if (Array.isArray(value)) {
         return `[${value.map(stableStringify).join(",")}]`;
+    }
+    if (!isRecord(value)) {
+        throw new Error("Completion identity must contain JSON-compatible values.");
+    }
     const record = value;
-    return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`).join(",")}}`;
+    return `{${Object.keys(record)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`)
+        .join(",")}}`;
 }
 function payloadDigest(value) {
     return createHash("sha256").update(stableStringify(value)).digest("hex").slice(0, 16);
 }
 export function buildCompletionKey(data, fallback) {
     const completionId = asNonEmptyString(data.completionId);
-    if (completionId)
+    if (hasText(completionId)) {
         return `completion:${completionId}`;
+    }
     const id = asNonEmptyString(data.id);
-    if (id)
+    if (hasText(id)) {
         return `id:${id}:${payloadDigest(data)}`;
+    }
     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") : "?";
+    const success = data.success === true ? "1" : "?";
+    const successIdentity = data.success === false ? "0" : success;
     return [
         "meta",
         sessionId,
@@ -41,28 +55,38 @@ export function buildCompletionKey(data, fallback) {
         timestamp !== undefined ? String(timestamp) : "no-ts",
         taskIndex !== undefined ? String(taskIndex) : "-",
         totalTasks !== undefined ? String(totalTasks) : "-",
-        success,
+        successIdentity,
         fallback,
     ].join(":");
 }
 function pruneSeenMap(seen, now, ttlMs) {
     for (const [key, ts] of seen.entries()) {
-        if (now - ts > ttlMs)
+        if (now - ts > ttlMs) {
             seen.delete(key);
+        }
     }
 }
 export function markSeenWithTtl(seen, key, now, ttlMs) {
     pruneSeenMap(seen, now, ttlMs);
-    if (seen.has(key))
+    if (seen.has(key)) {
         return true;
+    }
     seen.set(key, now);
     return false;
 }
+function isSeenMap(value) {
+    if (!(value instanceof Map)) {
+        return false;
+    }
+    const entries = value;
+    return [...entries].every(([key, timestamp]) => typeof key === "string" && typeof timestamp === "number");
+}
 export function getGlobalSeenMap(storeKey) {
     const globalStore = globalThis;
     const existing = globalStore[storeKey];
-    if (existing instanceof Map)
+    if (isSeenMap(existing)) {
         return existing;
+    }
     const map = new Map();
     globalStore[storeKey] = map;
     return map;