talking-stick 0.2.0 → 0.4.0

package/dist/cli/startup-maintenance.js

@@ -1,7 +1,20 @@
 import { syncInstalledSkills } from "../skill-install.js";
+import { runFirstRunMcpMigration } from "../update-migration.js";
+import { detectInstallSource, resolveCurrentBinaryPath } from "../self-update.js";
 import { isKnownHarnessCliEnv } from "./identity.js";
 import { getCommand } from "./registry.js";
-export function runStartupMaintenance(parsed, env = process.env) {
+export async function runStartupMaintenance(parsed, cliEntryUrl, env = process.env) {
+    if (shouldRunFirstRunMcpMigration(parsed, cliEntryUrl, env)) {
+        try {
+            await runFirstRunMcpMigration({
+                installOptions: { env }
+            });
+        }
+        catch {
+            // Startup cleanup is best-effort. Explicit install, uninstall, and
+            // self-update paths surface cleanup failures directly.
+        }
+    }
     if (!shouldAutoSyncInstalledSkills(parsed, env)) {
         return;
     }
@@ -13,6 +26,19 @@ export function runStartupMaintenance(parsed, env = process.env) {
         // unrelated tt command fail.
     }
 }
+export function shouldRunFirstRunMcpMigration(parsed, cliEntryUrl, env = process.env) {
+    if (env.TALKING_STICK_DISABLE_MCP_MIGRATION?.trim()) {
+        return false;
+    }
+    const command = getCommand(parsed.name);
+    if (!command?.startupMaintenance) {
+        return false;
+    }
+    const source = detectInstallSource({
+        binaryPath: resolveCurrentBinaryPath(cliEntryUrl)
+    });
+    return source !== "dev" && source !== "unknown";
+}
 export function shouldAutoSyncInstalledSkills(parsed, env = process.env) {
     if (env.TALKING_STICK_DISABLE_SKILL_SYNC?.trim()) {
         return false;

package/dist/cli.js

@@ -11,10 +11,10 @@ import { runStartupMaintenance } from "./cli/startup-maintenance.js";
 export { checkGuardianLiveness } from "./cli/guardian.js";
 export { parseHandoffJson } from "./cli/handoff.js";
 export { formatRelativeTime, shouldUseJson } from "./cli/output.js";
-export { shouldAutoSyncInstalledSkills } from "./cli/startup-maintenance.js";
+export { shouldAutoSyncInstalledSkills, shouldRunFirstRunMcpMigration } from "./cli/startup-maintenance.js";
 export async function runCli(argv = process.argv.slice(2)) {
     const parsed = parseCommand(argv);
-    runStartupMaintenance(parsed);
+    await runStartupMaintenance(parsed, import.meta.url);
     if (!parsed.name || parsed.name === "help" || parsed.name === "--help") {
         printHelp();
         return;

package/dist/config.js

@@ -4,9 +4,9 @@ export const defaultPolicy = {
     ownerLeaseTtlMs: 45 * 60 * 1000,
     heartbeatIntervalMs: 5 * 60 * 1000,
     claimTtlMs: 20 * 60 * 1000,
-    waitForTurnMaxWaitMs: 30 * 1000,
+    waitForTurnMaxWaitMs: 110 * 1000,
     waitForTurnPollMs: 250,
-    waitForEventsMaxWaitMs: 30 * 1000,
+    waitForEventsMaxWaitMs: 110 * 1000,
     waitForEventsPollMs: 250,
     waitForEventsBatchLimit: 100,
     presenceTtlMs: 4 * 60 * 60 * 1000,

package/dist/identity.js

@@ -127,13 +127,13 @@ function harnessAgentId(harness, sessionId, hostId, username) {
 function resolveHarnessSessionId(signal, env, parentPid, parentInspection, username, hostId, inspector) {
     if (signal.sessionId)
         return `harness:${signal.sessionId}`;
-    const terminalId = resolveTerminalSessionId(env);
-    if (terminalId)
-        return terminalId;
     const harnessRoot = findHarnessRootInAncestry(signal.harness, parentPid, parentInspection, inspector);
     if (harnessRoot) {
         return `pid:${harnessRoot.pid}@${harnessRoot.startTime}`;
     }
+    const terminalId = resolveTerminalSessionId(env);
+    if (terminalId)
+        return terminalId;
     if (parentInspection?.startTime) {
         return `pid:${parentPid}@${parentInspection.startTime}`;
     }
@@ -224,7 +224,7 @@ function detectHarnessSignal(env) {
     if (env.CLAUDECODE === "1") {
         return {
             harness: "claude",
-            sessionId: null,
+            sessionId: nonEmpty(env.CLAUDE_CODE_SESSION_ID),
             pidHint: parsePositiveInteger(env.CMUX_CLAUDE_PID)
         };
     }

package/dist/index.js

@@ -4,9 +4,10 @@ export { applyPragmas, assertLocalFilesystem, detectFilesystemType, migrate, ope
 export { ProtocolError, isProtocolError } from "./errors.js";
 export { deriveHarnessCliIdentity, deriveHumanCliIdentity, deriveMcpHarnessIdentity } from "./identity.js";
 export { ancestorPaths, canonicalizeContextPath, resolveContextPath, resolveWorkspaceRoot } from "./path-resolution.js";
-export { createMcpServer, runStdioServer } from "./mcp-server.js";
-export { SUPPORTED_HARNESSES, MissingHarnessError, detectHarness, parseHarnessList, planInstall, planUninstall, resolveHarnessConfigDir, resolveOpencodeConfigDir, resolveOpencodeConfigPath, runAction, skipAction } from "./install.js";
+export { DEFAULT_MAX_INSTRUCTION_FILE_BYTES, DEFAULT_INSTRUCTIONS_MARKDOWN, editInstructions, extractHarnessInstructions, normalizeInstructionHarness, parseInstructionScope, resetInstructions, resolveInstructionHarness, resolveInstructionPaths, showInstructions } from "./instructions.js";
+export { SUPPORTED_HARNESSES, MissingHarnessError, detectHarness, parseHarnessList, planUninstall, resolveHarnessConfigDir, resolveOpencodeConfigDir, resolveOpencodeConfigPath, runAction, skipAction } from "./install.js";
 export { DEFAULT_SKILL_NAME, planSkillInstall, planSkillUninstall, resolveBundledSkillPath, resolveSkillTargetPath, syncInstalledSkills } from "./skill-install.js";
+export { readPackageVersion, readUpdateMigrationState, resolveUpdateMigrationStatePath, runFirstRunMcpMigration, runStaleMcpCleanup, writeUpdateMigrationState } from "./update-migration.js";
 export { createSystemProcessInspector, terminateKnownProcess } from "./process-utils.js";
 export { clearCliSessionLease, findCliSessionByRoom, findCliSessionForContextPath, readCliSessions, removeCliSession, removeCliSessionsForRoom, resolveCliSessionPath, upsertCliSession, upsertJoinedCliSession, writeCliSessions } from "./session-store.js";
 export { TalkingStickService, createDefaultProcessLivenessChecker } from "./service.js";

package/dist/install-audit.js

@@ -0,0 +1,21 @@
+import fs from "node:fs";
+import path from "node:path";
+export class FileAuditLog {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    append(entry) {
+        const fullEntry = { ts: entry.ts ?? new Date().toISOString(), ...entry };
+        fs.mkdirSync(path.dirname(this.filePath), { recursive: true });
+        fs.appendFileSync(this.filePath, `${JSON.stringify(fullEntry)}\n`, "utf8");
+    }
+}
+export class NoopAuditLog {
+    append() {
+        // intentionally blank
+    }
+}
+export function defaultAuditLogPath(dataDir) {
+    return path.join(dataDir, "update-migrations.log");
+}

package/dist/install-migration.js

@@ -0,0 +1,84 @@
+import { SUPPORTED_HARNESSES, planUninstall, runAction } from "./install.js";
+import { NoopAuditLog } from "./install-audit.js";
+export async function removeStaleMcpRegistrations(options) {
+    const audit = options.audit ?? new NoopAuditLog();
+    const strict = options.strict ?? true;
+    const harnesses = options.harnesses === undefined || options.harnesses === "all"
+        ? [...SUPPORTED_HARNESSES]
+        : options.harnesses;
+    const installOptions = {
+        skipMissing: true,
+        ...(options.installOptions ?? {})
+    };
+    const results = [];
+    for (const harness of harnesses) {
+        const result = await removeOneHarness(harness, installOptions, strict);
+        results.push(result);
+        audit.append({
+            reason: options.reason,
+            package_version_from: options.packageVersionFrom,
+            package_version_to: options.packageVersionTo,
+            harness,
+            config_path: result.configPath,
+            action: result.action,
+            server_name: result.serverName,
+            detail: result.message
+        });
+    }
+    return results.map(({ harness, action, message }) => ({ harness, action, message }));
+}
+async function removeOneHarness(harness, installOptions, strict) {
+    const action = planUninstall(harness, installOptions);
+    if (action.kind === "skip") {
+        return {
+            harness,
+            action: "skipped",
+            message: action.message,
+            serverName: installOptions.serverName ?? "talking-stick"
+        };
+    }
+    if (action.kind === "file-patch") {
+        const state = action.inspect ? action.inspect() : "unknown";
+        const serverName = action.serverName ?? "talking-stick";
+        if (state === "absent") {
+            return {
+                harness,
+                action: "absent",
+                message: `${harness}: no Talking Stick MCP entry to remove`,
+                configPath: action.filePath,
+                serverName
+            };
+        }
+        if (strict && state !== "present") {
+            return {
+                harness,
+                action: "preserved",
+                message: `${harness}: hand-edited entry left alone (state=${state})`,
+                configPath: action.filePath,
+                serverName
+            };
+        }
+    }
+    const installResult = await runAction(action, installOptions);
+    return mapInstallResult(harness, action, installResult);
+}
+function mapInstallResult(harness, action, result) {
+    let serverName = "talking-stick";
+    if ("serverName" in action && typeof action.serverName === "string") {
+        serverName = action.serverName;
+    }
+    const configPath = action.kind === "file-patch" ? action.filePath : undefined;
+    if (!result.ok) {
+        return { harness, action: "failed", message: result.message, configPath, serverName };
+    }
+    switch (result.status) {
+        case "already_absent":
+            return { harness, action: "absent", message: result.message, configPath, serverName };
+        case "removed":
+            return { harness, action: "removed", message: result.message, configPath, serverName };
+        case "skipped":
+            return { harness, action: "skipped", message: result.message, configPath, serverName };
+        default:
+            return { harness, action: "failed", message: result.message, configPath, serverName };
+    }
+}

package/dist/install.js

@@ -115,75 +115,6 @@ function resolveHarnessConfigDirFromResolved(harness, resolved) {
             throw new Error(`Unknown harness: ${harness}`);
     }
 }
-export function planInstall(harness, options = {}) {
-    const resolved = resolveOptions(options);
-    const [serverBin, ...serverArgs] = resolved.serverCommand;
-    if (!serverBin)
-        throw new Error("serverCommand must include at least the binary");
-    switch (harness) {
-        case "claude-code":
-            if (resolved.skipMissing && !resolved.hooks.which("claude")) {
-                return skipAction(harness, "claude not on PATH");
-            }
-            return {
-                kind: "exec",
-                harness,
-                command: "claude",
-                args: ["mcp", "add", "-s", "user", resolved.serverName, "--", serverBin, ...serverArgs],
-                description: `claude mcp add -s user ${resolved.serverName} -- ${resolved.serverCommand.join(" ")}`,
-                operation: "install",
-                serverName: resolved.serverName,
-                serverCommand: resolved.serverCommand
-            };
-        case "codex":
-            if (resolved.skipMissing && !resolved.hooks.which("codex")) {
-                return skipAction(harness, "codex not on PATH");
-            }
-            return {
-                kind: "exec",
-                harness,
-                command: "codex",
-                args: ["mcp", "add", resolved.serverName, "--", serverBin, ...serverArgs],
-                description: `codex mcp add ${resolved.serverName} -- ${resolved.serverCommand.join(" ")}`,
-                operation: "install",
-                serverName: resolved.serverName,
-                serverCommand: resolved.serverCommand
-            };
-        case "gemini":
-            if (resolved.skipMissing && !resolved.hooks.which("gemini")) {
-                return skipAction(harness, "gemini not on PATH");
-            }
-            return {
-                kind: "exec",
-                harness,
-                command: "gemini",
-                args: ["mcp", "add", "-s", "user", "-t", "stdio", resolved.serverName, serverBin, ...serverArgs],
-                description: `gemini mcp add -s user -t stdio ${resolved.serverName} ${resolved.serverCommand.join(" ")}`,
-                operation: "install",
-                serverName: resolved.serverName,
-                serverCommand: resolved.serverCommand
-            };
-        case "opencode": {
-            const filePath = resolveOpencodeConfigPath(options);
-            const configDir = path.dirname(filePath);
-            if (resolved.skipMissing && !resolved.hooks.pathExists(configDir)) {
-                return skipAction(harness, `opencode config directory not found: ${configDir}`);
-            }
-            return {
-                kind: "file-patch",
-                harness,
-                filePath,
-                description: `merge mcp.${resolved.serverName} into ${filePath}`,
-                operation: "install",
-                serverName: resolved.serverName,
-                inspect: () => inspectOpencodeConfig(filePath, resolved),
-                apply: () => patchOpencodeConfig(filePath, resolved, "install")
-            };
-        }
-        default:
-            throw new Error(`Unknown harness: ${harness}`);
-    }
-}
 export function planUninstall(harness, options = {}) {
     const resolved = resolveOptions(options);
     switch (harness) {

package/dist/instructions.js

@@ -0,0 +1,256 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { resolveDataDir } from "./config.js";
+import { resolveContextPath } from "./path-resolution.js";
+export const DEFAULT_MAX_INSTRUCTION_FILE_BYTES = 256 * 1024;
+export const DEFAULT_INSTRUCTIONS_MARKDOWN = `# Talking Stick collaboration instructions
+
+Keep using Talking Stick until the shared task is done. After releasing or handing off, re-enter the wait loop by default. Prefer continued action unless the task is complete or the operator explicitly redirects or stops the room.
+
+Use phase names in handoffs when they clarify the work: draft, adversarial review, convergence, implementation, implementation review, test review, and release. These phases are vocabulary, not protocol state.
+
+Typical fits are advisory. Claude is usually strong at prose, first-pass synthesis, tool-running, implementation review, and test review. Codex is usually strong at adversarial review, convergence, implementation, edge cases, and release mechanics after operator approval. Gemini and OpenCode start with conservative local guidance until project dogfood says otherwise.
+
+For multi-agent design work, prefer independent read-only drafts first, then adversarial review and convergence. Do not impose a draft file structure on the workspace by default. If scratch draft files are useful, delete superseded pre-convergence drafts after the converged plan exists unless the operator asks to keep them.
+
+Default to normal release handoffs. Use named assignment only when a specific member must go next because of unique context, credentials, capability, or direct operator routing.
+
+## Claude
+
+Lean into drafting, synthesis, tool-running, implementation review, and test review. Watch for scope creep and messy first-pass artifacts. When implementation belongs elsewhere, make the next phase explicit in the handoff.
+
+## Codex
+
+Lean into adversarial review, convergence, precise implementation, edge-case sweeps, and release mechanics after operator approval. Watch for over-indexing on mechanics when the operator still needs to decide direction.
+
+## Gemini
+
+Use broad context review and exploration conservatively until the project has stronger Gemini-specific dogfood. Keep handoffs concrete and do not assume responsibility that the operator assigned to another harness.
+
+## OpenCode
+
+Use terminal-native local exploration and implementation conservatively until the project has stronger OpenCode-specific dogfood. Keep coordination safety ahead of speed.
+`;
+const HARNESS_ALIASES = {
+    all: "all",
+    base: "all",
+    claude: "claude",
+    "claude-code": "claude",
+    codex: "codex",
+    gemini: "gemini",
+    opencode: "opencode"
+};
+export function resolveInstructionPaths(options = {}) {
+    const contextPath = options.contextPath ?? process.cwd();
+    const workspaceRoot = resolveContextPath(contextPath).workspace_root;
+    return {
+        user: path.join(resolveDataDir(options), "instructions.md"),
+        project: path.join(workspaceRoot, ".talking-stick", "instructions.md")
+    };
+}
+export function showInstructions(input = {}) {
+    const options = input.options ?? {};
+    const harness = resolveInstructionHarness(input.harness, options.identity);
+    const scope = input.scope ?? "effective";
+    const paths = resolveInstructionPaths(options);
+    const layers = readInstructionLayers(paths, options.maxInstructionFileBytes ?? DEFAULT_MAX_INSTRUCTION_FILE_BYTES);
+    const selectedLayers = selectLayers(scope, layers);
+    const text = joinInstructionTexts(selectedLayers.map((layer) => extractHarnessInstructions(layer.text, harness)));
+    return {
+        harness,
+        scope,
+        text,
+        sources: selectedLayers.map((layer) => ({
+            scope: layer.scope,
+            path: layer.path
+        })),
+        paths
+    };
+}
+export async function editInstructions(input = {}) {
+    const scope = input.scope ?? "user";
+    const options = input.options ?? {};
+    const paths = resolveInstructionPaths(options);
+    const filePath = paths[scope];
+    const created = ensureInstructionFile(filePath);
+    const editor = chooseEditor(options);
+    if (!editor) {
+        return { scope, path: filePath, created, opened: false, editor: null };
+    }
+    await runEditor(editor, filePath);
+    return { scope, path: filePath, created, opened: true, editor };
+}
+export function resetInstructions(input) {
+    const paths = resolveInstructionPaths(input.options ?? {});
+    const filePath = paths[input.scope];
+    const removed = fs.existsSync(filePath);
+    if (removed) {
+        fs.rmSync(filePath, { force: true });
+    }
+    return { scope: input.scope, path: filePath, removed };
+}
+export function resolveInstructionHarness(explicitHarness, identity) {
+    if (explicitHarness) {
+        return normalizeInstructionHarness(explicitHarness);
+    }
+    const displayName = identity?.process_metadata.display_name ?? undefined;
+    const fromDisplay = displayName ? HARNESS_ALIASES[normalizeKey(displayName)] : undefined;
+    if (fromDisplay) {
+        return fromDisplay;
+    }
+    const prefix = identity?.agent_id.split(":")[0];
+    const fromPrefix = prefix ? HARNESS_ALIASES[normalizeKey(prefix)] : undefined;
+    return fromPrefix ?? "all";
+}
+export function normalizeInstructionHarness(value) {
+    const normalized = HARNESS_ALIASES[normalizeKey(value)];
+    if (!normalized) {
+        throw new Error(`--harness must be one of claude, codex, gemini, opencode, all (got ${value}).`);
+    }
+    return normalized;
+}
+export function parseInstructionScope(value) {
+    if (!value) {
+        return "effective";
+    }
+    if (value === "effective" ||
+        value === "bundled" ||
+        value === "user" ||
+        value === "project") {
+        return value;
+    }
+    throw new Error(`--scope must be one of effective, bundled, user, project (got ${value}).`);
+}
+export function extractHarnessInstructions(markdown, harness) {
+    const trimmed = markdown.trim();
+    if (!trimmed || harness === "all") {
+        return trimmed;
+    }
+    const lines = markdown.replace(/\r\n/g, "\n").split("\n");
+    const shared = [];
+    const sections = new Map();
+    let current = null;
+    let sawSection = false;
+    for (const line of lines) {
+        const header = parseHarnessHeader(line);
+        if (header) {
+            sawSection = true;
+            current = header;
+            if (!sections.has(current)) {
+                sections.set(current, []);
+            }
+            sections.get(current)?.push(line);
+            continue;
+        }
+        if (!sawSection) {
+            shared.push(line);
+            continue;
+        }
+        if (current) {
+            sections.get(current)?.push(line);
+        }
+    }
+    return joinInstructionTexts([
+        shared.join("\n").trim(),
+        sections.get(harness)?.join("\n").trim() ?? ""
+    ]);
+}
+function readInstructionLayers(paths, maxInstructionFileBytes) {
+    const layers = [
+        { scope: "bundled", path: null, text: DEFAULT_INSTRUCTIONS_MARKDOWN }
+    ];
+    for (const scope of ["user", "project"]) {
+        const filePath = paths[scope];
+        if (!fs.existsSync(filePath)) {
+            continue;
+        }
+        const stat = fs.statSync(filePath);
+        if (stat.size > maxInstructionFileBytes) {
+            throw new Error(`${scope} instructions file is too large (${stat.size} bytes, max ${maxInstructionFileBytes}): ${filePath}`);
+        }
+        const text = fs.readFileSync(filePath, "utf8");
+        layers.push({ scope, path: filePath, text });
+    }
+    return layers;
+}
+function selectLayers(scope, layers) {
+    if (scope === "effective") {
+        return layers;
+    }
+    return layers.filter((layer) => layer.scope === scope);
+}
+function joinInstructionTexts(parts) {
+    return parts
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0)
+        .join("\n\n");
+}
+function ensureInstructionFile(filePath) {
+    if (fs.existsSync(filePath)) {
+        return false;
+    }
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, DEFAULT_INSTRUCTIONS_MARKDOWN);
+    return true;
+}
+function parseHarnessHeader(line) {
+    const match = line.match(/^##\s+(.+?)\s*$/);
+    if (!match) {
+        return null;
+    }
+    const key = normalizeKey(match[1]);
+    if (key.startsWith("claude"))
+        return "claude";
+    if (key.startsWith("codex"))
+        return "codex";
+    if (key.startsWith("gemini"))
+        return "gemini";
+    if (key.startsWith("opencode"))
+        return "opencode";
+    return null;
+}
+function chooseEditor(options) {
+    const env = options.env ?? process.env;
+    const explicit = env.VISUAL?.trim() || env.EDITOR?.trim();
+    if (explicit) {
+        return explicit;
+    }
+    switch (options.platform ?? process.platform) {
+        case "darwin":
+            return "open -t";
+        case "win32":
+            return "notepad.exe";
+        default:
+            if (env.DISPLAY || env.WAYLAND_DISPLAY) {
+                return "xdg-open";
+            }
+            return null;
+    }
+}
+function runEditor(editor, filePath) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(`${editor} ${shellQuote(filePath)}`, {
+            stdio: "inherit",
+            shell: true
+        });
+        child.on("error", reject);
+        child.on("close", (code) => {
+            if (code === 0) {
+                resolve();
+                return;
+            }
+            reject(new Error(`${editor} exited with code ${code}.`));
+        });
+    });
+}
+function shellQuote(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+function normalizeKey(value) {
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}

package/dist/update-migration.js

@@ -0,0 +1,135 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveDataDir } from "./config.js";
+import { FileAuditLog, defaultAuditLogPath } from "./install-audit.js";
+import { removeStaleMcpRegistrations } from "./install-migration.js";
+export const UPDATE_MIGRATION_STATE_FILE = "update-migrations-state.json";
+export async function runStaleMcpCleanup(options) {
+    const packageVersionTo = options.packageVersionTo ?? options.packageVersion ?? readPackageVersion();
+    const dataDir = options.dataDir ?? resolveMigrationDataDir(options.installOptions);
+    const statePath = resolveUpdateMigrationStatePath(dataDir);
+    const auditPath = defaultAuditLogPath(dataDir);
+    const audit = options.audit ?? new FileAuditLog(auditPath);
+    const results = await removeStaleMcpRegistrations({
+        harnesses: options.harnesses ?? "all",
+        reason: options.reason,
+        packageVersionFrom: options.packageVersionFrom,
+        packageVersionTo,
+        audit,
+        installOptions: options.installOptions
+    });
+    if (options.updateState !== false && !results.some((result) => result.action === "failed")) {
+        writeUpdateMigrationState(statePath, {
+            mcp_cleanup_version: packageVersionTo,
+            updated_at: new Date().toISOString()
+        });
+    }
+    return {
+        status: "ran",
+        packageVersionFrom: options.packageVersionFrom,
+        packageVersionTo,
+        statePath,
+        auditPath,
+        results
+    };
+}
+export async function runFirstRunMcpMigration(options = {}) {
+    const packageVersion = options.packageVersion ?? readPackageVersion();
+    const dataDir = options.dataDir ?? resolveMigrationDataDir(options.installOptions);
+    const statePath = resolveUpdateMigrationStatePath(dataDir);
+    const auditPath = defaultAuditLogPath(dataDir);
+    const state = readUpdateMigrationState(statePath);
+    if (state.mcp_cleanup_version === packageVersion) {
+        return {
+            status: "current",
+            packageVersion,
+            statePath,
+            auditPath,
+            results: []
+        };
+    }
+    return runStaleMcpCleanup({
+        harnesses: "all",
+        reason: "first-run",
+        packageVersionFrom: state.mcp_cleanup_version,
+        packageVersionTo: packageVersion,
+        dataDir,
+        audit: options.audit,
+        installOptions: options.installOptions
+    });
+}
+export function resolveUpdateMigrationStatePath(dataDir) {
+    return path.join(dataDir, UPDATE_MIGRATION_STATE_FILE);
+}
+export function readUpdateMigrationState(statePath) {
+    try {
+        const raw = fs.readFileSync(statePath, "utf8");
+        const parsed = JSON.parse(raw);
+        if (!isPlainObject(parsed))
+            return {};
+        return {
+            mcp_cleanup_version: typeof parsed.mcp_cleanup_version === "string"
+                ? parsed.mcp_cleanup_version
+                : undefined,
+            updated_at: typeof parsed.updated_at === "string" ? parsed.updated_at : undefined
+        };
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return {};
+        return {};
+    }
+}
+export function writeUpdateMigrationState(statePath, state) {
+    fs.mkdirSync(path.dirname(statePath), { recursive: true });
+    const tmpPath = `${statePath}.${process.pid}.tmp`;
+    fs.writeFileSync(tmpPath, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+    fs.renameSync(tmpPath, statePath);
+}
+export function readPackageVersion(startUrl = import.meta.url) {
+    const root = findPackageRoot(fileURLToPath(startUrl));
+    if (!root)
+        return "unknown";
+    try {
+        const raw = fs.readFileSync(path.join(root, "package.json"), "utf8");
+        const parsed = JSON.parse(raw);
+        return typeof parsed.version === "string" && parsed.version.trim()
+            ? parsed.version
+            : "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+function resolveMigrationDataDir(installOptions) {
+    const options = {
+        env: installOptions?.env,
+        platform: installOptions?.platform,
+        homeDir: installOptions?.homeDir
+    };
+    return resolveDataDir(options);
+}
+function findPackageRoot(startPath) {
+    let current;
+    try {
+        current = fs.statSync(startPath).isDirectory()
+            ? startPath
+            : path.dirname(startPath);
+    }
+    catch {
+        current = path.dirname(startPath);
+    }
+    while (true) {
+        const candidate = path.join(current, "package.json");
+        if (fs.existsSync(candidate))
+            return current;
+        const parent = path.dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}