@luckypiggy/zhihu-ai-cli 0.2.1-test.4 → 0.2.1-test.5

package/dist/local-runner.js

@@ -0,0 +1,1717 @@
+/**
+ * Persist the running CLI so later Skill calls do not resolve it through npx.
+ * The first install may still enter through an exact-version npx command.
+ * After that, Codex uses a stable local wrapper that execs the copied package
+ * with the Node binary that performed the install.
+ *
+ * Lock order: persistLocalCliRunner acquires the runner lock and releases it
+ * before returning. Skill install calls it before any Profile lock. It refuses
+ * to run while a Profile lock is already held.
+ */
+import { createHash, randomBytes } from "node:crypto";
+import { chmodSync, closeSync, constants, cpSync, fstatSync, fsyncSync, linkSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { profileLocksHeld } from "./profile-lock.js";
+import { CLI_RUNNER } from "./release.js";
+const VERSION_PATTERN = /^[0-9A-Za-z][0-9A-Za-z._+-]*$/;
+const PACKAGE_NAME_PATTERN = /^(?:@[A-Za-z0-9._-]+\/)?[A-Za-z0-9._-]+$/;
+const SAFE_COMMAND_PATH = /^\/[A-Za-z0-9._@+:,/=-]+$/;
+const UNSAFE_PATH = /[\u0000-\u001f\u007f`]/;
+const COPY_FILES = ["package.json", "README.md"];
+const COPY_DIRECTORIES = ["bin", "dist", "assets"];
+const MARKER_NAME = ".zhihu-runner.json";
+const MARKER_SCHEMA = "2";
+const ENTRY_RELATIVE = "bin/zhihu.js";
+const WRAPPER_HEADER = "#!/bin/sh\n# zhihu-ai-cli-runner 2\n";
+const WRAPPER_SUFFIX = " \"$@\"\n";
+const METADATA_KEYS = ["digest", "entry", "generation", "node_path", "owner", "package", "schema", "version"];
+const DIGEST_PATTERN = /^[a-f0-9]{64}$/;
+const CONTENT_TAG_PATTERN = /^[A-Za-z0-9._-]{1,64}$/;
+const GENERATION_GRACE_MS = 10 * 60 * 1000;
+const RETENTION_NAME = "retention.json";
+export const RUNNER_LOCK_RECOVERY_CONFIRM = "recover-stale-runner-lock";
+const LOCK_FINGERPRINT_PATTERN = /^[a-f0-9]{16}$/;
+const LOCK_CLAIM_NAME = /^\.lock-claim-[a-f0-9]{24}$/;
+const LOCK_TEMP_NAME = /^\.lock-temp-[a-f0-9]{24}$/;
+const LOCK_GATE_NAME = ".lock-gate";
+const LOCK_GATE_KEYS = ["fingerprint", "pid", "purpose", "schema"];
+export class LocalRunnerError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "LocalRunnerError";
+        this.code = code;
+    }
+}
+function fail(code, message) {
+    throw new LocalRunnerError(code, message);
+}
+function isEnoent(error) {
+    return Boolean(error && typeof error === "object" && "code" in error && error.code === "ENOENT");
+}
+function isEexist(error) {
+    return Boolean(error && typeof error === "object" && "code" in error && error.code === "EEXIST");
+}
+function homeDirectory(environment) {
+    const raw = environment.HOME;
+    if (typeof raw === "string" && UNSAFE_PATH.test(raw)) {
+        fail("LOCAL_RUNNER_UNSAFE_PATH", "Local CLI runner path cannot be embedded in a command");
+    }
+    const value = raw?.trim();
+    return resolve(value || homedir());
+}
+export function localRunnerRoot(environment) {
+    return layoutFor(environment).runnerRoot;
+}
+export function localRunnerCommandPath(environment) {
+    return layoutFor(environment).command;
+}
+function layoutFor(environment) {
+    const home = homeDirectory(environment);
+    const configuredRaw = environment.XDG_DATA_HOME;
+    if (typeof configuredRaw === "string" && UNSAFE_PATH.test(configuredRaw)) {
+        fail("LOCAL_RUNNER_UNSAFE_PATH", "Local CLI runner path cannot be embedded in a command");
+    }
+    const configured = configuredRaw?.trim();
+    const dataRoot = configured ? resolve(configured) : join(home, ".local", "share");
+    const pilotRoot = join(dataRoot, "zhihu-pilot");
+    const runnerRoot = join(pilotRoot, "runner");
+    return {
+        home,
+        dataRoot,
+        pilotRoot,
+        runnerRoot,
+        generationRoot: join(runnerRoot, "generations"),
+        binDir: join(runnerRoot, "bin"),
+        command: join(runnerRoot, "bin", "zhihu"),
+        lockPath: join(runnerRoot, ".lock"),
+    };
+}
+function assertEmbeddableCommandPath(path) {
+    if (!isAbsolute(path) || UNSAFE_PATH.test(path)) {
+        fail("LOCAL_RUNNER_UNSAFE_PATH", "Local CLI runner path cannot be embedded in a command");
+    }
+}
+function shellQuote(value) {
+    assertEmbeddableCommandPath(value);
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+export function runnerCommandToken(path) {
+    assertEmbeddableCommandPath(path);
+    if (SAFE_COMMAND_PATH.test(path))
+        return path;
+    return shellQuote(path);
+}
+/**
+ * Replace the packaged runner token with the local command.
+ * A short `zhihu` runner is matched only at a command boundary so names such
+ * as `zhihu-aiops` stay intact. A multi-word npx runner is replaced exactly.
+ */
+export function retargetPackagedRunner(content, packagedRunner, localCommand) {
+    if (UNSAFE_PATH.test(localCommand)) {
+        fail("LOCAL_RUNNER_UNSAFE_PATH", "Local CLI runner path cannot be embedded in a command");
+    }
+    if (packagedRunner === "zhihu") {
+        return content.replace(/`zhihu(?=\s|`)/g, `\`${localCommand}`);
+    }
+    return content.split(packagedRunner).join(localCommand);
+}
+function packageRoot() {
+    return resolve(dirname(fileURLToPath(import.meta.url)), "..");
+}
+function assertNoSymlinks(path) {
+    let stat;
+    try {
+        stat = lstatSync(path);
+    }
+    catch {
+        fail("LOCAL_RUNNER_IO_ERROR", "Local CLI runner source cannot be read");
+    }
+    if (stat.isSymbolicLink())
+        fail("LOCAL_RUNNER_SYMLINK", "Local CLI runner source contains a symbolic link");
+    if (!stat.isDirectory())
+        return;
+    let entries;
+    try {
+        entries = readdirSync(path, { withFileTypes: true });
+    }
+    catch {
+        fail("LOCAL_RUNNER_IO_ERROR", "Local CLI runner source cannot be read");
+    }
+    for (const entry of entries) {
+        const child = join(path, entry.name);
+        if (entry.isSymbolicLink())
+            fail("LOCAL_RUNNER_SYMLINK", "Local CLI runner source contains a symbolic link");
+        if (entry.isDirectory())
+            assertNoSymlinks(child);
+    }
+}
+function readPackageIdentity(root) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+    }
+    catch {
+        fail("LOCAL_RUNNER_IO_ERROR", "Local CLI runner package identity cannot be read");
+    }
+    const name = parsed.name;
+    const version = parsed.version;
+    if (typeof name !== "string" || !PACKAGE_NAME_PATTERN.test(name)) {
+        fail("LOCAL_RUNNER_IO_ERROR", "Local CLI runner package identity cannot be read");
+    }
+    if (typeof version !== "string" || !VERSION_PATTERN.test(version) || version.includes("..")) {
+        fail("LOCAL_RUNNER_IO_ERROR", "Local CLI runner package version is not usable as a directory name");
+    }
+    return { name, version };
+}
+function metadataText(metadata) {
+    return `${JSON.stringify({
+        digest: metadata.digest,
+        entry: metadata.entry,
+        generation: metadata.generation,
+        node_path: metadata.node_path,
+        owner: metadata.owner,
+        package: metadata.package,
+        schema: metadata.schema,
+        version: metadata.version,
+    }, null, 2)}\n`;
+}
+function generationId(version, digest) {
+    return `${version}.${digest}`;
+}
+function generationMatches(version, digest, generation) {
+    const canonical = generationId(version, digest);
+    if (generation === canonical)
+        return true;
+    if (!generation.startsWith(`${canonical}.`) || generation.includes(".."))
+        return false;
+    return /^[A-Za-z0-9._-]{1,96}$/.test(generation.slice(canonical.length + 1));
+}
+function parseMetadata(text, generation) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+        return undefined;
+    const record = parsed;
+    if (Object.keys(record).sort().join("\0") !== METADATA_KEYS.join("\0"))
+        return undefined;
+    if (record.owner !== "zhihu-ai-cli" || record.schema !== MARKER_SCHEMA)
+        return undefined;
+    if (typeof record.package !== "string" || !PACKAGE_NAME_PATTERN.test(record.package))
+        return undefined;
+    if (typeof record.version !== "string" || !VERSION_PATTERN.test(record.version) || record.version.includes(".."))
+        return undefined;
+    if (typeof record.digest !== "string" || !DIGEST_PATTERN.test(record.digest))
+        return undefined;
+    if (record.generation !== generation || !generationMatches(record.version, record.digest, generation))
+        return undefined;
+    if (record.entry !== ENTRY_RELATIVE)
+        return undefined;
+    if (typeof record.node_path !== "string" || !isAbsolute(record.node_path) || UNSAFE_PATH.test(record.node_path))
+        return undefined;
+    return {
+        owner: "zhihu-ai-cli",
+        schema: MARKER_SCHEMA,
+        package: record.package,
+        version: record.version,
+        generation,
+        digest: record.digest,
+        node_path: record.node_path,
+        entry: ENTRY_RELATIVE,
+    };
+}
+function readMetadata(directory) {
+    const markerPath = join(directory, MARKER_NAME);
+    let stat;
+    try {
+        stat = lstatSync(markerPath);
+    }
+    catch {
+        return undefined;
+    }
+    if (stat.isSymbolicLink() || !stat.isFile())
+        return undefined;
+    try {
+        return parseMetadata(readFileSync(markerPath, "utf8"), basename(directory));
+    }
+    catch {
+        return undefined;
+    }
+}
+function ensureChildDirectory(parent, name) {
+    if (name.length === 0 || name === "." || name === ".." || name.includes("/") || name.includes("\\")) {
+        fail("LOCAL_RUNNER_UNSAFE_PATH", "Local CLI runner path cannot be embedded in a command");
+    }
+    const path = join(parent, name);
+    const accept = () => {
+        const stat = lstatSync(path);
+        if (stat.isSymbolicLink())
+            fail("LOCAL_RUNNER_SYMLINK", "Local CLI runner directory is a symbolic link");
+        if (!stat.isDirectory())
+            fail("LOCAL_RUNNER_FOREIGN", "Local CLI runner directory is not a directory");
+        return path;
+    };
+    try {
+        return accept();
+    }
+    catch (error) {
+        if (error instanceof LocalRunnerError)
+            throw error;
+        if (!isEnoent(error))
+            fail("LOCAL_RUNNER_IO_ERROR", "Local CLI runner directory cannot be created");
+    }
+    try {
+        mkdirSync(path, { mode: 0o755 });
+    }
+    catch (error) {
+        if (!isEexist(error))
+            fail("LOCAL_RUNNER_IO_ERROR", "Local CLI runner directory cannot be created");
+    }
+    return accept();
+}
+function ensureDataRoot(layout) {
+    let homeStat;
+    try {
+        homeStat = lstatSync(layout.home);
+    }
+    catch {
+        fail("LOCAL_RUNNER_IO_ERROR", "Local CLI runner data directory is unavailable");
+    }
+    if (homeStat.isSymbolicLink() || !homeStat.isDirectory()) {
+        fail("LOCAL_RUNNER_SYMLINK", "Local CLI runner directory is a symbolic link");
+    }
+    const insideHome = layout.dataRoot === layout.home || layout.dataRoot.startsWith(`${layout.home}${sep}`);
+    if (!insideHome) {
+        let dataStat;
+        try {
+            dataStat = lstatSync(layout.dataRoot);
+        }
+        catch {
+            fail("LOCAL_RUNNER_IO_ERROR", "Local CLI runner data directory is unavailable");
+        }
+        if (dataStat.isSymbolicLink())
+            fail("LOCAL_RUNNER_SYMLINK", "Local CLI runner directory is a symbolic link");
+        if (!dataStat.isDirectory())
+            fail("LOCAL_RUNNER_FOREIGN", "Local CLI runner directory is not a directory");
+        return;
+    }
+    const rel = relative(layout.home, layout.dataRoot);
+    let current = layout.home;
+    if (rel.length === 0)
+        return;
+    for (const part of rel.split(sep))
+        current = ensureChildDirectory(current, part);
+}
+function assertContained(layout, path) {
+    let rootReal = "";
+    let pathReal = "";
+    try {
+        rootReal = realpathSync(layout.dataRoot);
+        pathReal = realpathSync(path);
+    }
+    catch {
+        fail("LOCAL_RUNNER_IO_ERROR", "Local CLI runner directory cannot be created");
+    }
+    if (pathReal !== rootReal && !pathReal.startsWith(`${rootReal}${sep}`)) {
+        fail("LOCAL_RUNNER_SYMLINK", "Local CLI runner directory is a symbolic link");
+    }
+}
+function ensureManagedDirectories(layout) {
+    ensureDataRoot(layout);
+    ensureChildDirectory(layout.dataRoot, "zhihu-pilot");
+    ensureChildDirectory(layout.pilotRoot, "runner");
+    ensureChildDirectory(layout.runnerRoot, "generations");
+    ensureChildDirectory(layout.runnerRoot, "bin");
+}
+const LEGACY_WRAPPER_PREFIX = "#!/bin/sh\n# zhihu-ai-cli-runner 1\nexec ";
+function isCopiedPath(rel) {
+    if (COPY_FILES.includes(rel))
+        return true;
+    return COPY_DIRECTORIES.some((directory) => rel === directory || rel.startsWith(`${directory}/`));
+}
+function collectTree(root, include) {
+    const records = [];
+    const visit = (directory, prefix) => {
+        let entries;
+        try {
+            entries = readdirSync(directory, { withFileTypes: true });
+        }
+        catch {
+            return false;
+        }
+        for (const entry of entries) {
+            const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+            if (!include(rel))
+                continue;
+            const full = join(directory, entry.name);
+            let stat;
+            try {
+                stat = lstatSync(full);
+            }
+            catch {
+                return false;
+            }
+            if (stat.isSymbolicLink())
+                return false;
+            if (stat.isDirectory()) {
+                records.push({ rel, kind: "dir", executable: "", body: Buffer.alloc(0) });
+                if (!visit(full, rel))
+                    return false;
+                continue;
+            }
+            if (!stat.isFile())
+                return false;
+            try {
+                records.push({
+                    rel,
+                    kind: "file",
+                    executable: (stat.mode & 0o111) !== 0 ? "1" : "0",
+                    body: readFileSync(full),
+                });
+            }
+            catch {
+                return false;
+            }
+        }
+        return true;
+    };
+    if (!visit(root, ""))
+        return undefined;
+    records.sort((left, right) => (left.rel < right.rel ? -1 : left.rel > right.rel ? 1 : 0));
+    return records;
+}
+function hashRecords(records) {
+    const hash = createHash("sha256");
+    for (const record of records) {
+        hash.update(record.kind);
+        hash.update("\0");
+        hash.update(record.rel);
+        hash.update("\0");
+        if (record.kind === "file") {
+            hash.update(record.executable);
+            hash.update("\0");
+            hash.update(record.body);
+            hash.update("\0");
+        }
+    }
+    return hash.digest("hex");
+}
+/** Digest a generation tree. The marker is excluded. Symlinks make the result undefined. */
+export function runnerTreeDigest(root) {
+    const records = collectTree(root, (rel) => rel !== MARKER_NAME);
+    return records ? hashRecords(records) : undefined;
+}
+function sourceDigest(root) {
+    const records = collectTree(root, isCopiedPath);
+    if (!records)
+        fail("LOCAL_RUNNER_IO_ERROR", "Local CLI runner source cannot be read");
+    return hashRecords(records);
+}
+function wrapperScript(generationDir, metadata) {
+    const entryPath = join(generationDir, metadata.entry);
+    return `${WRAPPER_HEADER}# generation ${metadata.generation}\nexec ${shellQuote(metadata.node_path)} ${shellQuote(entryPath)}${WRAPPER_SUFFIX}`;
+}
+function wrapperGeneration(text) {
+    const marker = "# generation ";
+    if (!text.startsWith(`${WRAPPER_HEADER}${marker}`) || !text.endsWith(WRAPPER_SUFFIX))
+        return undefined;
+    const rest = text.slice(WRAPPER_HEADER.length + marker.length);
+    const newline = rest.indexOf("\n");
+    if (newline <= 0)
+        return undefined;
+    const generation = rest.slice(0, newline);
+    if (!/^[0-9A-Za-z][0-9A-Za-z._+-]*$/.test(generation) || generation.includes(".."))
+        return undefined;
+    const execLine = rest.slice(newline + 1);
+    if (!execLine.startsWith("exec "))
+        return undefined;
+    return generation;
+}
+function isReplaceableWrapper(text) {
+    if (text.startsWith(LEGACY_WRAPPER_PREFIX) && text.endsWith(WRAPPER_SUFFIX))
+        return true;
+    return wrapperGeneration(text) !== undefined;
+}
+function assertWrapperSafe(script, generationDir, metadata) {
+    if (script !== wrapperScript(generationDir, metadata)) {
+        fail("LOCAL_RUNNER_IO_ERROR", "Local CLI runner entry could not be verified");
+    }
+    const entryPath = join(generationDir, metadata.entry);
+    const structural = script.replaceAll(shellQuote(metadata.node_path), "").replaceAll(shellQuote(entryPath), "");
+    if (/\bnpx\b|\bnpm\b|registry/i.test(structural)) {
+        fail("LOCAL_RUNNER_IO_ERROR", "Local CLI runner entry could not be verified");
+    }
+}
+function assertEntryReplaceable(command) {
+    let stat;
+    try {
+        stat = lstatSync(command);
+    }
+    catch (error) {
+        if (isEnoent(error))
+            return;
+        fail("LOCAL_RUNNER_IO_ERROR", "Local CLI runner entry cannot be replaced");
+    }
+    if (stat.isSymbolicLink())
+        fail("LOCAL_RUNNER_SYMLINK", "Local CLI runner entry is a symbolic link");
+    if (!stat.isFile())
+        fail("LOCAL_RUNNER_FOREIGN", "Local CLI runner entry is not a regular file");
+    let text = "";
+    try {
+        text = readFileSync(command, "utf8");
+    }
+    catch {
+        fail("LOCAL_RUNNER_IO_ERROR", "Local CLI runner entry cannot be replaced");
+    }
+    if (!isReplaceableWrapper(text))
+        fail("LOCAL_RUNNER_FOREIGN", "Local CLI runner entry is not managed by this CLI");
+}
+function removeOwnDirectory(directory) {
+    try {
+        const stat = lstatSync(directory);
+        if (stat.isSymbolicLink() || !stat.isDirectory())
+            return;
+        rmSync(directory, { recursive: true, force: true });
+    }
+    catch {
+        // The directory is already gone.
+    }
+}
+function wrapperSelects(command, generation) {
+    try {
+        const stat = lstatSync(command);
+        if (stat.isSymbolicLink() || !stat.isFile())
+            return false;
+        return readFileSync(command, "utf8").includes(`\n# generation ${generation}\n`);
+    }
+    catch {
+        return false;
+    }
+}
+function wrapperMatches(command, expected) {
+    try {
+        const stat = lstatSync(command);
+        if (stat.isSymbolicLink() || !stat.isFile() || (stat.mode & 0o111) === 0)
+            return false;
+        return readFileSync(command, "utf8") === expected;
+    }
+    catch {
+        return false;
+    }
+}
+function writeStableEntry(binDir, generationDir, metadata, beforeRename) {
+    const command = join(binDir, "zhihu");
+    assertEntryReplaceable(command);
+    const script = wrapperScript(generationDir, metadata);
+    const temporary = join(binDir, `.zhihu.${randomBytes(8).toString("hex")}.tmp`);
+    let created = false;
+    try {
+        const descriptor = openSync(temporary, "wx", 0o644);
+        created = true;
+        try {
+            writeFileSync(descriptor, script);
+        }
+        finally {
+            closeSync(descriptor);
+        }
+        chmodSync(temporary, 0o755);
+        const temporaryStat = lstatSync(temporary);
+        if (temporaryStat.isSymbolicLink() || !temporaryStat.isFile() || (temporaryStat.mode & 0o111) === 0) {
+            fail("LOCAL_RUNNER_IO_ERROR", "Local CLI runner entry could not be verified");
+        }
+        assertWrapperSafe(readFileSync(temporary, "utf8"), generationDir, metadata);
+        if (beforeRename)
+            beforeRename();
+        assertEntryReplaceable(command);
+        renameSync(temporary, command);
+        created = false;
+    }
+    catch (error) {
+        if (created) {
+            try {
+                const stat = lstatSync(temporary);
+                if (!stat.isSymbolicLink() && stat.isFile())
+                    unlinkSync(temporary);
+            }
+            catch {
+                // The temporary file is already gone.
+            }
+        }
+        if (error instanceof LocalRunnerError)
+            throw error;
+        fail("LOCAL_RUNNER_IO_ERROR", "Local CLI runner entry cannot be replaced");
+    }
+}
+function safeGenerationName(value) {
+    return /^[0-9A-Za-z][0-9A-Za-z._+-]*$/.test(value) && !value.includes("..") && !value.includes("/") && !value.includes("\\");
+}
+function readRetention(layout) {
+    const path = join(layout.runnerRoot, RETENTION_NAME);
+    try {
+        const stat = lstatSync(path);
+        if (stat.isSymbolicLink() || !stat.isFile())
+            return undefined;
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (parsed.schema !== "1")
+            return undefined;
+        if (typeof parsed.active !== "string" || !safeGenerationName(parsed.active))
+            return undefined;
+        if (parsed.previous !== "" && (typeof parsed.previous !== "string" || !safeGenerationName(parsed.previous)))
+            return undefined;
+        if (Object.keys(parsed).sort().join("\0") !== "active\0previous\0schema")
+            return undefined;
+        return { active: parsed.active, previous: parsed.previous };
+    }
+    catch {
+        return undefined;
+    }
+}
+function writeRetention(layout, active, previous) {
+    const path = join(layout.runnerRoot, RETENTION_NAME);
+    let existing;
+    try {
+        existing = lstatSync(path);
+    }
+    catch (error) {
+        if (!isEnoent(error))
+            fail("LOCAL_RUNNER_IO_ERROR", "Local CLI runner could not be installed");
+        existing = undefined;
+    }
+    if (existing?.isSymbolicLink())
+        fail("LOCAL_RUNNER_SYMLINK", "Local CLI runner directory is a symbolic link");
+    const temporary = join(layout.runnerRoot, `.retention.${randomBytes(8).toString("hex")}.tmp`);
+    const body = `${JSON.stringify({ active, previous, schema: "1" })}\n`;
+    const descriptor = openSync(temporary, "wx", 0o644);
+    try {
+        writeFileSync(descriptor, body);
+    }
+    finally {
+        closeSync(descriptor);
+    }
+    try {
+        renameSync(temporary, path);
+    }
+    catch (error) {
+        try {
+            unlinkSync(temporary);
+        }
+        catch {
+            // The temporary file is already gone.
+        }
+        throw error;
+    }
+}
+function collectExpiredGenerations(layout, active, previous, graceMs) {
+    let names = [];
+    try {
+        names = readdirSync(layout.generationRoot);
+    }
+    catch {
+        return;
+    }
+    const retained = new Set([active, previous].filter((name) => name.length > 0));
+    for (const name of names) {
+        if (name.startsWith(".") || retained.has(name) || !safeGenerationName(name))
+            continue;
+        const directory = join(layout.generationRoot, name);
+        try {
+            const stat = lstatSync(directory);
+            if (stat.isSymbolicLink() || !stat.isDirectory())
+                continue;
+            if (Date.now() - stat.mtimeMs < graceMs)
+                continue;
+            const metadata = readMetadata(directory);
+            if (!metadata || metadata.generation !== name)
+                continue;
+            if (runnerTreeDigest(directory) !== metadata.digest)
+                continue;
+            rmSync(directory, { recursive: true, force: true });
+        }
+        catch {
+            // Cleanup must not break the active entry.
+        }
+    }
+}
+function sleepSync(milliseconds) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
+}
+function lockOwnerAlive(pid) {
+    if (pid === undefined)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        const code = error && typeof error === "object" && "code" in error ? error.code : undefined;
+        return code !== "ESRCH";
+    }
+}
+function isErrno(error, code) {
+    return Boolean(error && typeof error === "object" && "code" in error && error.code === code);
+}
+function parseLock(text) {
+    try {
+        const raw = JSON.parse(text);
+        const pid = typeof raw.pid === "number" && Number.isInteger(raw.pid) && raw.pid > 0 ? raw.pid : undefined;
+        return { nonce: typeof raw.nonce === "string" ? raw.nonce : "", pid };
+    }
+    catch {
+        return { nonce: "", pid: undefined };
+    }
+}
+function readLockBody(path) {
+    try {
+        return parseLock(readFileSync(path, "utf8"));
+    }
+    catch {
+        return { nonce: "", pid: undefined };
+    }
+}
+function recoveryRunner(environment) {
+    try {
+        const existing = existingLocalRunnerCommand(environment);
+        if (existing)
+            return runnerCommandToken(existing);
+    }
+    catch (error) {
+        if (error instanceof LocalRunnerError && error.code !== "LOCAL_RUNNER_IO_ERROR")
+            throw error;
+    }
+    return CLI_RUNNER;
+}
+export function runnerLockStatusCommand(environment = process.env) {
+    return `${recoveryRunner(environment)} runner lock status --json`;
+}
+export function runnerLockRecoverCommand(environment = process.env) {
+    return `${recoveryRunner(environment)} runner lock recover --confirm ${RUNNER_LOCK_RECOVERY_CONFIRM} --fingerprint <fingerprint> --json`;
+}
+export function localizedRunnerLockMessage(language, environment = process.env) {
+    const status = runnerLockStatusCommand(environment);
+    const recover = runnerLockRecoverCommand(environment);
+    if (language === "zh") {
+        return `安装锁超时。请运行 ${status}；若状态为 stale，再运行 ${recover} 后重试。不要手工删除锁。`;
+    }
+    return `The local runner install lock timed out. Run ${status}; if it is stale, run ${recover} and retry. Do not delete the lock by hand.`;
+}
+function runnerLockTimeoutMessage(environment) {
+    return `LOCAL_RUNNER_LOCK_TIMEOUT. ${localizedRunnerLockMessage("en", environment)} ${localizedRunnerLockMessage("zh", environment)}`;
+}
+function managedPublishName(path) {
+    const name = basename(path);
+    return name === ".lock" || name === LOCK_GATE_NAME || LOCK_TEMP_NAME.test(name);
+}
+function removeOwnedDirectoryEntry(path, dev, ino) {
+    if (!managedPublishName(path))
+        return;
+    try {
+        const stat = lstatSync(path);
+        if (stat.isSymbolicLink() || !stat.isFile() || stat.dev !== dev || stat.ino !== ino || (stat.mode & 0o077) !== 0)
+            return;
+        unlinkSync(path);
+    }
+    catch {
+        // The entry is already gone or no longer the inode owned by this publish.
+    }
+}
+function privateFileIdentity(path, dev, ino) {
+    try {
+        const stat = lstatSync(path);
+        return !stat.isSymbolicLink() && stat.isFile() && stat.dev === dev && stat.ino === ino && (stat.mode & 0o077) === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Write a complete private document to a temporary inode, then publish that
+ * inode at the stable path with link(2). The stable directory entry is never
+ * created empty and an existing stable entry is never replaced.
+ */
+function publishPrivateDocument(stablePath, document, failure, hooks = {}) {
+    if (hooks.beforeCreate)
+        hooks.beforeCreate();
+    const tempPath = join(dirname(stablePath), `.lock-temp-${randomBytes(12).toString("hex")}`);
+    const descriptor = openSync(tempPath, "wx", 0o600);
+    let identity;
+    try {
+        const created = fstatSync(descriptor);
+        identity = { dev: created.dev, ino: created.ino };
+        if (!created.isFile() || (created.mode & 0o077) !== 0)
+            fail(failure.code, failure.message);
+        if (hooks.afterCreate)
+            hooks.afterCreate();
+        writeFileSync(descriptor, document);
+        if (hooks.afterWrite)
+            hooks.afterWrite();
+        fsyncSync(descriptor);
+    }
+    catch (error) {
+        try {
+            closeSync(descriptor);
+        }
+        catch {
+            // The temporary descriptor is already closed.
+        }
+        if (identity)
+            removeOwnedDirectoryEntry(tempPath, identity.dev, identity.ino);
+        throw error;
+    }
+    try {
+        closeSync(descriptor);
+    }
+    catch {
+        // The temporary descriptor is already closed.
+    }
+    if (!identity || !privateFileIdentity(tempPath, identity.dev, identity.ino))
+        fail(failure.code, failure.message);
+    try {
+        linkSync(tempPath, stablePath);
+    }
+    catch (error) {
+        removeOwnedDirectoryEntry(tempPath, identity.dev, identity.ino);
+        throw error;
+    }
+    let stable;
+    try {
+        stable = lstatSync(stablePath);
+    }
+    catch (error) {
+        removeOwnedDirectoryEntry(tempPath, identity.dev, identity.ino);
+        throw error;
+    }
+    if (stable.isSymbolicLink() || !stable.isFile() || stable.dev !== identity.dev || stable.ino !== identity.ino) {
+        removeOwnedDirectoryEntry(tempPath, identity.dev, identity.ino);
+        fail(failure.code, failure.message);
+    }
+    try {
+        if (hooks.afterPublish)
+            hooks.afterPublish();
+    }
+    catch (error) {
+        removeOwnedDirectoryEntry(stablePath, identity.dev, identity.ino);
+        removeOwnedDirectoryEntry(tempPath, identity.dev, identity.ino);
+        throw error;
+    }
+    removeOwnedDirectoryEntry(tempPath, identity.dev, identity.ino);
+    return identity;
+}
+function acquireRunnerLock(lockPath, environment, options) {
+    const timeoutMs = options.lockTimeoutMs ?? 15000;
+    const staleMs = options.staleMs ?? 120000;
+    const retryMs = options.retryMs ?? 40;
+    if (!Number.isFinite(timeoutMs) || timeoutMs < 1 || !Number.isFinite(staleMs) || staleMs < 1) {
+        fail("LOCAL_RUNNER_IO_ERROR", "Local CLI runner could not be installed");
+    }
+    const runnerRoot = dirname(lockPath);
+    const nonce = randomBytes(12).toString("hex");
+    const started = Date.now();
+    let ownedDev = 0;
+    let ownedIno = 0;
+    const releaseOwned = () => {
+        removeOwnedLockEntries(runnerRoot, lockPath, ownedDev, ownedIno, nonce);
+        if (!ownsLockEntry(runnerRoot, lockPath, ownedDev, ownedIno, nonce))
+            removeDeadRecoveryGate(runnerRoot);
+    };
+    const rejectOwnLock = () => {
+        removeOwnedLockEntries(runnerRoot, lockPath, ownedDev, ownedIno, nonce);
+        if (options.afterOwnLockRejected)
+            options.afterOwnLockRejected();
+    };
+    while (Date.now() - started <= timeoutMs) {
+        const block = inspectRecoveryBlock(runnerRoot);
+        if (block === "symlink")
+            fail("LOCAL_RUNNER_SYMLINK", "Local CLI runner lock is a symbolic link");
+        if (block === "foreign")
+            fail("LOCAL_RUNNER_FOREIGN", "Local CLI runner lock is not a regular file");
+        if (block === "busy") {
+            if (options.onLockBusy)
+                options.onLockBusy();
+            sleepSync(retryMs);
+            continue;
+        }
+        if (options.afterPreLockCheck)
+            options.afterPreLockCheck();
+        try {
+            const existing = lstatSync(lockPath);
+            if (existing.isSymbolicLink())
+                fail("LOCAL_RUNNER_SYMLINK", "Local CLI runner lock is a symbolic link");
+        }
+        catch (error) {
+            if (error instanceof LocalRunnerError)
+                throw error;
+            if (!isEnoent(error))
+                fail("LOCAL_RUNNER_IO_ERROR", "Local CLI runner could not be installed");
+        }
+        try {
+            const published = publishPrivateDocument(lockPath, JSON.stringify({ pid: process.pid, created_at: Date.now(), nonce }), { code: "LOCAL_RUNNER_IO_ERROR", message: "Local CLI runner could not be installed" }, {
+                afterCreate: options.afterLockTempCreate,
+                afterWrite: options.afterLockTempWrite,
+                afterPublish: options.afterLockPublish,
+            });
+            ownedDev = published.dev;
+            ownedIno = published.ino;
+            const again = inspectRecoveryBlock(runnerRoot);
+            if (again !== "clear") {
+                rejectOwnLock();
+                if (again === "symlink")
+                    fail("LOCAL_RUNNER_SYMLINK", "Local CLI runner lock is a symbolic link");
+                if (again === "foreign")
+                    fail("LOCAL_RUNNER_FOREIGN", "Local CLI runner lock is not a regular file");
+                if (options.onLockBusy)
+                    options.onLockBusy();
+                sleepSync(retryMs);
+                continue;
+            }
+            return releaseOwned;
+        }
+        catch (error) {
+            if (error instanceof LocalRunnerError)
+                throw error;
+            if (!isEexist(error))
+                fail("LOCAL_RUNNER_IO_ERROR", "Local CLI runner could not be installed");
+            // A lock is never renamed or removed here. Stale locks wait until timeout.
+            if (options.onLockBusy)
+                options.onLockBusy();
+            sleepSync(retryMs);
+        }
+    }
+    fail("LOCAL_RUNNER_LOCK_TIMEOUT", runnerLockTimeoutMessage(environment));
+}
+function lockFingerprint(dev, ino, nonce) {
+    return createHash("sha256").update(`${dev}:${ino}:${nonce}`).digest("hex").slice(0, 16);
+}
+function lockDetail(state, environment) {
+    const status = runnerLockStatusCommand(environment);
+    const recover = runnerLockRecoverCommand(environment);
+    switch (state) {
+        case "held":
+            return `A local runner install may be in progress. Run ${status} and retry after it finishes. 可能有安装正在进行。请运行 ${status}，结束后再重试。`;
+        case "stale":
+            return `A previous install left a stale lock. Run ${recover}, then retry install. Do not delete the lock by hand. 请使用 status 返回的 fingerprint 运行 ${recover} 后重试安装。不要手工删除锁。`;
+        case "symlink":
+            return "The runner lock is a symbolic link and recovery will not remove it. Do not delete it by hand. 锁是符号链接，恢复命令不会删除它。不要手工删除。";
+        case "invalid":
+            return "The runner lock is not a recoverable regular file. Recovery will not remove it. Do not delete it by hand. 锁不是可恢复的普通文件，恢复命令不会删除它。不要手工删除。";
+        default: {
+            const unreachable = state;
+            return unreachable;
+        }
+    }
+}
+function lockClaimNames(runnerRoot) {
+    try {
+        return readdirSync(runnerRoot).filter((name) => LOCK_CLAIM_NAME.test(name)).sort();
+    }
+    catch {
+        return [];
+    }
+}
+function describeLock(stat, body, staleMs, environment) {
+    if (stat.isSymbolicLink())
+        return { state: "symlink", detail: lockDetail("symlink", environment) };
+    const age = Math.max(0, Date.now() - stat.mtimeMs);
+    if (!stat.isFile())
+        return { state: "invalid", age_ms: age, detail: lockDetail("invalid", environment) };
+    const fingerprint = body.nonce ? lockFingerprint(stat.dev, stat.ino, body.nonce) : undefined;
+    const common = {
+        age_ms: age,
+        ...(body.pid !== undefined ? { pid: body.pid } : {}),
+        ...(fingerprint ? { fingerprint } : {}),
+    };
+    if (!body.nonce)
+        return { state: "invalid", ...common, detail: lockDetail("invalid", environment) };
+    if (lockOwnerAlive(body.pid) || age < staleMs)
+        return { state: "held", ...common, detail: lockDetail("held", environment) };
+    return { state: "stale", ...common, detail: lockDetail("stale", environment) };
+}
+/** Read the install lock without creating, renaming, or removing it. */
+export function inspectLocalRunnerLock(environment = process.env, options = {}) {
+    const staleMs = options.staleMs ?? 120000;
+    if (!Number.isFinite(staleMs) || staleMs < 1)
+        fail("LOCAL_RUNNER_IO_ERROR", "Local CLI runner lock recovery could not be completed");
+    const layout = layoutFor(environment);
+    let path = layout.lockPath;
+    let stat;
+    try {
+        stat = lstatSync(path);
+    }
+    catch {
+        const claims = lockClaimNames(layout.runnerRoot);
+        if (claims.length === 0)
+            return describeRecoveryGate(layout.runnerRoot, environment);
+        path = join(layout.runnerRoot, claims[0]);
+        try {
+            stat = lstatSync(path);
+        }
+        catch {
+            return { state: "invalid", detail: lockDetail("invalid", environment) };
+        }
+    }
+    const body = stat.isSymbolicLink() || !stat.isFile()
+        ? { nonce: "", pid: undefined }
+        : readLockBody(path);
+    return describeLock(stat, body, staleMs, environment);
+}
+function openLockNoFollow(path) {
+    try {
+        return openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    }
+    catch (error) {
+        if (isErrno(error, "ELOOP"))
+            fail("LOCAL_RUNNER_SYMLINK", "Local CLI runner lock is a symbolic link");
+        if (isErrno(error, "EISDIR"))
+            fail("LOCAL_RUNNER_FOREIGN", "Local CLI runner lock is not a regular file");
+        if (isEnoent(error))
+            fail("LOCAL_RUNNER_LOCK_TIMEOUT", "Local CLI runner lock is still in use");
+        fail("LOCAL_RUNNER_IO_ERROR", "Local CLI runner lock recovery could not be completed");
+    }
+}
+function readLockFromDescriptor(descriptor) {
+    const stat = fstatSync(descriptor);
+    if (!stat.isFile())
+        fail("LOCAL_RUNNER_FOREIGN", "Local CLI runner lock is not a regular file");
+    const length = Math.min(Math.max(stat.size, 0), 4096);
+    if (length < 1)
+        return { nonce: "", pid: undefined };
+    const buffer = Buffer.alloc(length);
+    try {
+        readSync(descriptor, buffer, 0, length, 0);
+    }
+    catch {
+        return { nonce: "", pid: undefined };
+    }
+    return parseLock(buffer.toString("utf8"));
+}
+function acceptOpenLock(path, fingerprint, staleMs) {
+    let observed;
+    try {
+        observed = lstatSync(path);
+    }
+    catch (error) {
+        if (isEnoent(error))
+            fail("LOCAL_RUNNER_LOCK_TIMEOUT", "Local CLI runner lock is still in use");
+        fail("LOCAL_RUNNER_IO_ERROR", "Local CLI runner lock recovery could not be completed");
+    }
+    if (observed.isSymbolicLink())
+        fail("LOCAL_RUNNER_SYMLINK", "Local CLI runner lock is a symbolic link");
+    if (!observed.isFile())
+        fail("LOCAL_RUNNER_FOREIGN", "Local CLI runner lock is not a regular file");
+    const descriptor = openLockNoFollow(path);
+    try {
+        const current = fstatSync(descriptor);
+        const body = readLockFromDescriptor(descriptor);
+        const age = Date.now() - current.mtimeMs;
+        const actual = body.nonce ? lockFingerprint(current.dev, current.ino, body.nonce) : "";
+        if (!body.nonce || actual !== fingerprint || age < staleMs || lockOwnerAlive(body.pid) || current.dev !== observed.dev || current.ino !== observed.ino) {
+            fail("LOCAL_RUNNER_LOCK_TIMEOUT", "Local CLI runner lock is still in use");
+        }
+        return { descriptor, dev: current.dev, ino: current.ino };
+    }
+    catch (error) {
+        closeSync(descriptor);
+        throw error;
+    }
+}
+function lockEntryOwned(path, dev, ino, nonce) {
+    try {
+        const stat = lstatSync(path);
+        if (stat.isSymbolicLink() || !stat.isFile() || stat.dev !== dev || stat.ino !== ino)
+            return false;
+        return readLockBody(path).nonce === nonce;
+    }
+    catch {
+        return false;
+    }
+}
+function ownedLockPaths(runnerRoot, lockPath) {
+    return [lockPath, ...lockClaimNames(runnerRoot).map((name) => join(runnerRoot, name))];
+}
+function removeOwnedLockEntries(runnerRoot, lockPath, dev, ino, nonce) {
+    for (const path of ownedLockPaths(runnerRoot, lockPath)) {
+        if (!lockEntryOwned(path, dev, ino, nonce))
+            continue;
+        try {
+            unlinkSync(path);
+        }
+        catch {
+            // A replaced entry is no longer owned by this process.
+        }
+    }
+}
+function ownsLockEntry(runnerRoot, lockPath, dev, ino, nonce) {
+    return ownedLockPaths(runnerRoot, lockPath).some((path) => lockEntryOwned(path, dev, ino, nonce));
+}
+function recoveryGatePath(runnerRoot) {
+    return join(runnerRoot, LOCK_GATE_NAME);
+}
+function recoveryGateDocument(fingerprint, pid) {
+    return JSON.stringify({ fingerprint, pid, purpose: "recover", schema: "1" });
+}
+function parseRecoveryGate(text) {
+    try {
+        const raw = JSON.parse(text);
+        if (Object.keys(raw).sort().join(",") !== LOCK_GATE_KEYS.join(","))
+            return undefined;
+        if (raw.purpose !== "recover" || raw.schema !== "1")
+            return undefined;
+        if (typeof raw.fingerprint !== "string" || !LOCK_FINGERPRINT_PATTERN.test(raw.fingerprint))
+            return undefined;
+        if (typeof raw.pid !== "number" || !Number.isInteger(raw.pid) || raw.pid <= 0)
+            return undefined;
+        return { fingerprint: raw.fingerprint, pid: raw.pid, purpose: "recover", schema: "1" };
+    }
+    catch {
+        return undefined;
+    }
+}
+function readRecoveryGate(path) {
+    let descriptor;
+    try {
+        descriptor = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    }
+    catch (error) {
+        if (isEnoent(error))
+            return { kind: "missing" };
+        if (isErrno(error, "ELOOP"))
+            return { kind: "symlink" };
+        if (isErrno(error, "EISDIR"))
+            return { kind: "foreign" };
+        fail("LOCAL_RUNNER_IO_ERROR", "Local CLI runner lock recovery could not be completed");
+    }
+    try {
+        const stat = fstatSync(descriptor);
+        if (!stat.isFile())
+            return { kind: "foreign" };
+        if ((stat.mode & 0o077) !== 0)
+            return { kind: "invalid" };
+        const length = Math.min(Math.max(stat.size, 0), 4096);
+        const buffer = Buffer.alloc(length);
+        if (length > 0) {
+            try {
+                readSync(descriptor, buffer, 0, length, 0);
+            }
+            catch {
+                return { kind: "invalid" };
+            }
+        }
+        const body = parseRecoveryGate(buffer.toString("utf8"));
+        if (!body)
+            return { kind: "invalid" };
+        return { kind: "valid", stat, body };
+    }
+    finally {
+        closeSync(descriptor);
+    }
+}
+function inspectRecoveryBlock(runnerRoot) {
+    const gate = readRecoveryGate(recoveryGatePath(runnerRoot));
+    if (gate.kind === "symlink")
+        return "symlink";
+    if (gate.kind === "foreign")
+        return "foreign";
+    if (lockClaimNames(runnerRoot).length > 0)
+        return "busy";
+    if (gate.kind === "missing")
+        return "clear";
+    return "busy";
+}
+function describeRecoveryGate(runnerRoot, environment) {
+    const gate = readRecoveryGate(recoveryGatePath(runnerRoot));
+    if (gate.kind === "missing")
+        return { state: "missing" };
+    if (gate.kind === "symlink")
+        return { state: "symlink", detail: lockDetail("symlink", environment) };
+    if (gate.kind !== "valid")
+        return { state: "invalid", detail: lockDetail("invalid", environment) };
+    const state = lockOwnerAlive(gate.body.pid) ? "held" : "stale";
+    return {
+        state,
+        pid: gate.body.pid,
+        age_ms: Math.max(0, Date.now() - gate.stat.mtimeMs),
+        fingerprint: gate.body.fingerprint,
+        detail: lockDetail(state, environment),
+    };
+}
+function dropRecoveryGate(runnerRoot, identity) {
+    const path = recoveryGatePath(runnerRoot);
+    try {
+        const stat = lstatSync(path);
+        if (stat.isSymbolicLink() || !stat.isFile() || stat.dev !== identity.dev || stat.ino !== identity.ino)
+            return;
+        unlinkSync(path);
+    }
+    catch {
+        // The gate is already gone or no longer the inode this recovery held.
+    }
+}
+function removeDeadRecoveryGate(runnerRoot) {
+    const path = recoveryGatePath(runnerRoot);
+    const gate = readRecoveryGate(path);
+    if (gate.kind !== "valid" || lockOwnerAlive(gate.body.pid) || lockClaimNames(runnerRoot).length > 0)
+        return;
+    dropRecoveryGate(runnerRoot, gate.stat);
+}
+function cleanupDeadDisplacement(runnerRoot, lockPath) {
+    const gate = readRecoveryGate(recoveryGatePath(runnerRoot));
+    if (gate.kind !== "valid" || lockOwnerAlive(gate.body.pid))
+        return;
+    let lockStat;
+    try {
+        lockStat = lstatSync(lockPath);
+    }
+    catch {
+        return;
+    }
+    if (lockStat.isSymbolicLink() || !lockStat.isFile())
+        return;
+    let names = [];
+    try {
+        names = readdirSync(runnerRoot);
+    }
+    catch {
+        return;
+    }
+    let different = false;
+    for (const name of names) {
+        if (!LOCK_CLAIM_NAME.test(name))
+            continue;
+        const path = join(runnerRoot, name);
+        try {
+            const stat = lstatSync(path);
+            if (stat.isSymbolicLink() || !stat.isFile() || stat.dev !== lockStat.dev || stat.ino !== lockStat.ino) {
+                different = true;
+                continue;
+            }
+            try {
+                unlinkSync(path);
+            }
+            catch (unlinkError) {
+                if (!isEnoent(unlinkError))
+                    different = true;
+            }
+        }
+        catch (error) {
+            if (!isEnoent(error))
+                different = true;
+        }
+    }
+    if (!different)
+        dropRecoveryGate(runnerRoot, gate.stat);
+}
+/**
+ * Publish or adopt the recovery gate. One live holder excludes every other
+ * recovery. After that holder removes the gate, a later recovery may publish
+ * its own gate; exclusion is per holder, not one publish for the lifetime.
+ * The later recovery still fails closed when the target lock is already gone.
+ */
+function ensureRecoveryGate(runnerRoot, fingerprint, options = {}) {
+    const path = recoveryGatePath(runnerRoot);
+    try {
+        const published = publishPrivateDocument(path, recoveryGateDocument(fingerprint, process.pid), { code: "LOCAL_RUNNER_IO_ERROR", message: "Local CLI runner lock recovery could not be completed" }, {
+            beforeCreate: options.beforeGateTemp,
+            afterCreate: options.afterGateTempCreate,
+            afterWrite: options.afterGateTempWrite,
+            afterPublish: options.afterGatePublish,
+        });
+        return { dev: published.dev, ino: published.ino, fresh: true };
+    }
+    catch (error) {
+        if (error instanceof LocalRunnerError)
+            throw error;
+        if (!isEexist(error))
+            fail("LOCAL_RUNNER_IO_ERROR", "Local CLI runner lock recovery could not be completed");
+    }
+    const existing = readRecoveryGate(path);
+    if (existing.kind === "symlink")
+        fail("LOCAL_RUNNER_SYMLINK", "Local CLI runner lock is a symbolic link");
+    if (existing.kind === "foreign")
+        fail("LOCAL_RUNNER_FOREIGN", "Local CLI runner lock is not a regular file");
+    if (existing.kind !== "valid" || lockOwnerAlive(existing.body.pid) || existing.body.fingerprint !== fingerprint) {
+        fail("LOCAL_RUNNER_LOCK_TIMEOUT", "Local CLI runner lock is still in use");
+    }
+    return { dev: existing.stat.dev, ino: existing.stat.ino, fresh: false };
+}
+function restoreDisplacedLock(claimPath, lockPath) {
+    try {
+        linkSync(claimPath, lockPath);
+    }
+    catch {
+        return false;
+    }
+    return true;
+}
+function deleteVerifiedClaimInodes(runnerRoot, dev, ino) {
+    let names = [];
+    try {
+        names = readdirSync(runnerRoot);
+    }
+    catch {
+        fail("LOCAL_RUNNER_IO_ERROR", "Local CLI runner lock recovery could not be completed");
+    }
+    for (const name of names) {
+        if (!LOCK_CLAIM_NAME.test(name))
+            continue;
+        const path = join(runnerRoot, name);
+        try {
+            const stat = lstatSync(path);
+            if (stat.isSymbolicLink() || !stat.isFile() || stat.dev !== dev || stat.ino !== ino)
+                continue;
+            unlinkSync(path);
+        }
+        catch (error) {
+            if (isEnoent(error))
+                continue;
+            fail("LOCAL_RUNNER_IO_ERROR", "Local CLI runner lock recovery could not be completed");
+        }
+    }
+}
+function isolateVerifiedLock(source, lockPath, runnerRoot, identity, gate, options) {
+    const claimPath = join(runnerRoot, `.lock-claim-${randomBytes(12).toString("hex")}`);
+    try {
+        renameSync(source, claimPath);
+    }
+    catch (error) {
+        if (isEnoent(error)) {
+            dropRecoveryGate(runnerRoot, gate);
+            if (gate.fresh)
+                fail("LOCAL_RUNNER_LOCK_TIMEOUT", "Local CLI runner lock is still in use");
+            return;
+        }
+        fail("LOCAL_RUNNER_IO_ERROR", "Local CLI runner lock recovery could not be completed");
+    }
+    if (options.afterRename)
+        options.afterRename();
+    let claimStat;
+    try {
+        claimStat = lstatSync(claimPath);
+    }
+    catch (error) {
+        if (isEnoent(error)) {
+            dropRecoveryGate(runnerRoot, gate);
+            fail("LOCAL_RUNNER_LOCK_TIMEOUT", "Local CLI runner lock is still in use");
+        }
+        fail("LOCAL_RUNNER_IO_ERROR", "Local CLI runner lock recovery could not be completed");
+    }
+    if (claimStat.isSymbolicLink() || !claimStat.isFile() || claimStat.dev !== identity.dev || claimStat.ino !== identity.ino) {
+        if (!claimStat.isSymbolicLink() && claimStat.isFile() && restoreDisplacedLock(claimPath, lockPath)) {
+            if (options.afterRestore)
+                options.afterRestore();
+            let unlinked = false;
+            try {
+                unlinkSync(claimPath);
+                unlinked = true;
+            }
+            catch (error) {
+                if (isEnoent(error))
+                    unlinked = true;
+            }
+            if (unlinked)
+                dropRecoveryGate(runnerRoot, gate);
+        }
+        fail("LOCAL_RUNNER_LOCK_TIMEOUT", "Local CLI runner lock is still in use");
+    }
+    if (options.afterClaim)
+        options.afterClaim();
+    deleteVerifiedClaimInodes(runnerRoot, identity.dev, identity.ino);
+    if (options.afterDelete)
+        options.afterDelete();
+    dropRecoveryGate(runnerRoot, gate);
+}
+/**
+ * Remove one stale install lock after the caller repeats the confirmation
+ * phrase and the fingerprint from status. The deleted inode is the opened
+ * file, never a later directory entry at the stable lock path. Install does
+ * not call this.
+ *
+ * The gate guarantees mutual exclusion, not a single publish for the whole
+ * recovery lifetime. A later recovery may publish another gate after the
+ * first holder releases it, then return `LOCAL_RUNNER_LOCK_TIMEOUT` if the
+ * target lock is already gone. Two gate holds, and the recovery critical
+ * sections inside them, must not overlap.
+ */
+export function recoverLocalRunnerLock(environment = process.env, options = {}) {
+    if (options.confirm !== RUNNER_LOCK_RECOVERY_CONFIRM) {
+        fail("LOCAL_RUNNER_IO_ERROR", "Local CLI runner lock recovery requires explicit confirmation");
+    }
+    const staleMs = options.staleMs ?? 120000;
+    if (!Number.isFinite(staleMs) || staleMs < 1 || typeof options.fingerprint !== "string" || !LOCK_FINGERPRINT_PATTERN.test(options.fingerprint)) {
+        fail("LOCAL_RUNNER_IO_ERROR", "Local CLI runner lock recovery requires explicit confirmation");
+    }
+    const fingerprint = options.fingerprint;
+    const layout = layoutFor(environment);
+    cleanupDeadDisplacement(layout.runnerRoot, layout.lockPath);
+    let source = layout.lockPath;
+    try {
+        lstatSync(source);
+    }
+    catch (error) {
+        if (!isEnoent(error))
+            fail("LOCAL_RUNNER_IO_ERROR", "Local CLI runner lock recovery could not be completed");
+        const claims = lockClaimNames(layout.runnerRoot);
+        if (claims.length === 0) {
+            concludeAbsentRecovery(layout.runnerRoot, fingerprint);
+            return;
+        }
+        source = join(layout.runnerRoot, claims[0]);
+    }
+    const opened = acceptOpenLock(source, fingerprint, staleMs);
+    try {
+        if (options.beforeRename)
+            options.beforeRename();
+        const gate = ensureRecoveryGate(layout.runnerRoot, fingerprint, options);
+        if (options.afterGate)
+            options.afterGate();
+        isolateVerifiedLock(source, layout.lockPath, layout.runnerRoot, opened, gate, options);
+    }
+    finally {
+        closeSync(opened.descriptor);
+    }
+}
+function concludeAbsentRecovery(runnerRoot, fingerprint) {
+    const gate = readRecoveryGate(recoveryGatePath(runnerRoot));
+    if (gate.kind === "missing" || gate.kind === "invalid") {
+        fail("LOCAL_RUNNER_LOCK_TIMEOUT", "Local CLI runner lock is still in use");
+    }
+    if (gate.kind === "symlink")
+        fail("LOCAL_RUNNER_SYMLINK", "Local CLI runner lock is a symbolic link");
+    if (gate.kind === "foreign")
+        fail("LOCAL_RUNNER_FOREIGN", "Local CLI runner lock is not a regular file");
+    if (lockOwnerAlive(gate.body.pid) || gate.body.fingerprint !== fingerprint) {
+        fail("LOCAL_RUNNER_LOCK_TIMEOUT", "Local CLI runner lock is still in use");
+    }
+    dropRecoveryGate(runnerRoot, gate.stat);
+}
+function nodeIsUsable(nodePath) {
+    try {
+        const stat = statSync(nodePath);
+        return stat.isFile() && (stat.mode & 0o111) !== 0;
+    }
+    catch {
+        return false;
+    }
+}
+function entryIsUsable(entryPath) {
+    try {
+        const stat = lstatSync(entryPath);
+        return !stat.isSymbolicLink() && stat.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function classifyGeneration(directory, digest, nodePath) {
+    let stat;
+    try {
+        stat = lstatSync(directory);
+    }
+    catch (error) {
+        if (isEnoent(error))
+            return "missing";
+        fail("LOCAL_RUNNER_IO_ERROR", "Local CLI runner could not be installed");
+    }
+    if (stat.isSymbolicLink())
+        return "symlink";
+    if (!stat.isDirectory())
+        return "file";
+    const metadata = readMetadata(directory);
+    if (!metadata)
+        return "foreign";
+    if (metadata.digest !== digest || metadata.node_path !== nodePath || !entryIsUsable(join(directory, metadata.entry)))
+        return "damaged";
+    if (runnerTreeDigest(directory) !== metadata.digest)
+        return "damaged";
+    return "verified";
+}
+/** Read runner health without creating directories or files. */
+export function inspectLocalRunner(environment = process.env) {
+    const broken = (detail) => ({
+        command: CLI_RUNNER,
+        health: { state: "broken", detail },
+    });
+    let layout;
+    try {
+        layout = layoutFor(environment);
+        assertEmbeddableCommandPath(layout.command);
+    }
+    catch (error) {
+        if (error instanceof LocalRunnerError && error.code === "LOCAL_RUNNER_UNSAFE_PATH") {
+            return broken("runner path cannot be embedded");
+        }
+        return broken("runner installation is incomplete");
+    }
+    let stat;
+    try {
+        stat = lstatSync(layout.command);
+    }
+    catch (error) {
+        if (isEnoent(error))
+            return { command: CLI_RUNNER, health: { state: "missing" } };
+        return broken("runner installation is incomplete");
+    }
+    if (stat.isSymbolicLink() || !stat.isFile() || (stat.mode & 0o111) === 0) {
+        return broken("runner entry is not an executable file");
+    }
+    let text = "";
+    try {
+        text = readFileSync(layout.command, "utf8");
+    }
+    catch {
+        return broken("runner installation is incomplete");
+    }
+    const generation = wrapperGeneration(text);
+    if (!generation)
+        return broken("runner entry is not managed by this CLI");
+    const generationDir = join(layout.generationRoot, generation);
+    let generationStat;
+    try {
+        generationStat = lstatSync(generationDir);
+    }
+    catch {
+        return broken("runner installation is incomplete");
+    }
+    if (generationStat.isSymbolicLink() || !generationStat.isDirectory()) {
+        return broken("runner installation is incomplete");
+    }
+    const metadata = readMetadata(generationDir);
+    if (!metadata)
+        return broken("runner installation is incomplete");
+    let expected = "";
+    try {
+        expected = wrapperScript(generationDir, metadata);
+    }
+    catch {
+        return broken("runner installation is incomplete");
+    }
+    if (text !== expected)
+        return broken("runner entry is not managed by this CLI");
+    const entryPath = join(generationDir, metadata.entry);
+    if (!entryIsUsable(entryPath))
+        return broken("runner target is unavailable");
+    if (!nodeIsUsable(metadata.node_path))
+        return broken("runner node is unavailable");
+    if (runnerTreeDigest(generationDir) !== metadata.digest)
+        return broken("runner content does not match its generation");
+    return { command: layout.command, health: { state: "ready" } };
+}
+/** Read the stable wrapper when it is a ready managed entry. Does not create it. */
+export function existingLocalRunnerCommand(environment = process.env) {
+    const inspected = inspectLocalRunner(environment);
+    return inspected.health.state === "ready" ? inspected.command : undefined;
+}
+function stageGeneration(layout, root, destination, metadata, afterStageCopy) {
+    const stage = join(layout.generationRoot, `.${randomBytes(8).toString("hex")}.stage`);
+    mkdirSync(stage, { mode: 0o755 });
+    try {
+        for (const file of COPY_FILES)
+            cpSync(join(root, file), join(stage, file));
+        for (const directory of COPY_DIRECTORIES) {
+            cpSync(join(root, directory), join(stage, directory), { recursive: true, verbatimSymlinks: true });
+        }
+        if (afterStageCopy)
+            afterStageCopy(stage);
+        if (runnerTreeDigest(stage) !== metadata.digest)
+            fail("LOCAL_RUNNER_IO_ERROR", "Local CLI runner could not be installed");
+        writeFileSync(join(stage, MARKER_NAME), metadataText(metadata), { mode: 0o644 });
+        assertNoSymlinks(stage);
+        const written = parseMetadata(readFileSync(join(stage, MARKER_NAME), "utf8"), metadata.generation);
+        if (!written || written.digest !== metadata.digest || runnerTreeDigest(stage) !== metadata.digest) {
+            fail("LOCAL_RUNNER_IO_ERROR", "Local CLI runner could not be installed");
+        }
+        let existing;
+        try {
+            existing = lstatSync(destination);
+        }
+        catch (error) {
+            if (!isEnoent(error))
+                fail("LOCAL_RUNNER_IO_ERROR", "Local CLI runner could not be installed");
+            existing = undefined;
+        }
+        if (existing) {
+            removeOwnDirectory(stage);
+            if (existing.isSymbolicLink())
+                fail("LOCAL_RUNNER_SYMLINK", "Local CLI runner version directory is a symbolic link");
+            fail("LOCAL_RUNNER_FOREIGN", "Local CLI runner version directory is not managed by this CLI");
+        }
+        renameSync(stage, destination);
+        return destination;
+    }
+    catch (error) {
+        removeOwnDirectory(stage);
+        if (error instanceof LocalRunnerError)
+            throw error;
+        fail("LOCAL_RUNNER_IO_ERROR", "Local CLI runner could not be installed");
+    }
+}
+/** Copy the running package and point the stable wrapper at that copy. */
+export function persistLocalCliRunner(environment = process.env, options = {}) {
+    if (profileLocksHeld() > 0) {
+        fail("LOCAL_RUNNER_LOCK_ORDER", "Local CLI runner cannot be installed while a profile lock is held");
+    }
+    const contentTag = options.contentTag ?? "";
+    if (contentTag !== "" && !CONTENT_TAG_PATTERN.test(contentTag)) {
+        fail("LOCAL_RUNNER_IO_ERROR", "Local CLI runner could not be installed");
+    }
+    const graceMs = options.generationGraceMs ?? GENERATION_GRACE_MS;
+    if (!Number.isFinite(graceMs) || graceMs < 0)
+        fail("LOCAL_RUNNER_IO_ERROR", "Local CLI runner could not be installed");
+    const layout = layoutFor(environment);
+    assertEmbeddableCommandPath(layout.command);
+    assertEmbeddableCommandPath(process.execPath);
+    const root = packageRoot();
+    const identity = readPackageIdentity(root);
+    for (const file of COPY_FILES)
+        assertNoSymlinks(join(root, file));
+    for (const directory of COPY_DIRECTORIES)
+        assertNoSymlinks(join(root, directory));
+    let entryStat;
+    try {
+        entryStat = lstatSync(join(root, "bin", "zhihu.js"));
+    }
+    catch {
+        fail("LOCAL_RUNNER_IO_ERROR", "Local CLI runner entrypoint is missing");
+    }
+    if (entryStat.isSymbolicLink() || !entryStat.isFile())
+        fail("LOCAL_RUNNER_IO_ERROR", "Local CLI runner entrypoint is missing");
+    const digest = sourceDigest(root);
+    const canonical = generationId(identity.version, digest);
+    const preferredName = contentTag ? `${canonical}.${contentTag}` : canonical;
+    ensureManagedDirectories(layout);
+    const release = acquireRunnerLock(layout.lockPath, environment, options);
+    let createdGeneration = "";
+    let activeGeneration = "";
+    try {
+        if (options.insideLock)
+            options.insideLock();
+        ensureManagedDirectories(layout);
+        assertContained(layout, layout.runnerRoot);
+        assertContained(layout, layout.generationRoot);
+        assertContained(layout, layout.binDir);
+        assertEntryReplaceable(layout.command);
+        const priorText = (() => {
+            try {
+                return readFileSync(layout.command, "utf8");
+            }
+            catch {
+                return "";
+            }
+        })();
+        const priorGeneration = wrapperGeneration(priorText);
+        let metadata = chooseGeneration(layout, identity, digest, preferredName, contentTag !== "");
+        activeGeneration = metadata.generation;
+        const destination = join(layout.generationRoot, metadata.generation);
+        const state = classifyGeneration(destination, digest, process.execPath);
+        if (state === "symlink")
+            fail("LOCAL_RUNNER_SYMLINK", "Local CLI runner version directory is a symbolic link");
+        if (state === "file" || state === "foreign")
+            fail("LOCAL_RUNNER_FOREIGN", "Local CLI runner version directory is not managed by this CLI");
+        if (state === "missing") {
+            createdGeneration = stageGeneration(layout, root, destination, metadata, options.afterStageCopy);
+            assertContained(layout, destination);
+        }
+        const expected = wrapperScript(destination, metadata);
+        if (!wrapperMatches(layout.command, expected)) {
+            writeStableEntry(layout.binDir, destination, metadata, options.beforeEntryRename);
+            createdGeneration = "";
+        }
+        const retainedPrevious = priorGeneration && priorGeneration !== metadata.generation
+            ? priorGeneration
+            : readRetention(layout)?.active === metadata.generation ? readRetention(layout)?.previous ?? "" : "";
+        try {
+            if (options.beforeCleanup)
+                options.beforeCleanup();
+            writeRetention(layout, metadata.generation, retainedPrevious);
+            collectExpiredGenerations(layout, metadata.generation, retainedPrevious, graceMs);
+        }
+        catch {
+            // A cleanup failure leaves the new entry in place.
+        }
+        return layout.command;
+    }
+    catch (error) {
+        if (createdGeneration && !wrapperSelects(layout.command, activeGeneration))
+            removeOwnDirectory(createdGeneration);
+        if (error instanceof LocalRunnerError)
+            throw error;
+        fail("LOCAL_RUNNER_IO_ERROR", "Local CLI runner could not be installed");
+    }
+    finally {
+        release();
+    }
+}
+function chooseGeneration(layout, identity, digest, preferredName, exactName) {
+    const build = (generation) => ({
+        owner: "zhihu-ai-cli",
+        schema: MARKER_SCHEMA,
+        package: identity.name,
+        version: identity.version,
+        generation,
+        digest,
+        node_path: process.execPath,
+        entry: ENTRY_RELATIVE,
+    });
+    const preferred = join(layout.generationRoot, preferredName);
+    const preferredState = classifyGeneration(preferred, digest, process.execPath);
+    if (preferredState === "verified")
+        return build(preferredName);
+    if (!exactName) {
+        const selected = findVerifiedGeneration(layout, identity.version, digest);
+        if (selected)
+            return build(selected);
+    }
+    if (preferredState === "missing")
+        return build(preferredName);
+    if (preferredState === "symlink")
+        fail("LOCAL_RUNNER_SYMLINK", "Local CLI runner version directory is a symbolic link");
+    if (preferredState === "file" || preferredState === "foreign") {
+        fail("LOCAL_RUNNER_FOREIGN", "Local CLI runner version directory is not managed by this CLI");
+    }
+    const repair = unusedGenerationName(layout.generationRoot, preferredName);
+    return build(repair);
+}
+function findVerifiedGeneration(layout, version, digest) {
+    let names = [];
+    try {
+        names = readdirSync(layout.generationRoot);
+    }
+    catch {
+        return undefined;
+    }
+    const canonical = generationId(version, digest);
+    const matches = names.filter((name) => name === canonical || name.startsWith(`${canonical}.`)).sort();
+    const active = wrapperGeneration((() => {
+        try {
+            return readFileSync(layout.command, "utf8");
+        }
+        catch {
+            return "";
+        }
+    })());
+    const ordered = active && matches.includes(active) ? [active, ...matches.filter((name) => name !== active)] : matches;
+    for (const name of ordered) {
+        if (classifyGeneration(join(layout.generationRoot, name), digest, process.execPath) === "verified")
+            return name;
+    }
+    return undefined;
+}
+function unusedGenerationName(generationRoot, base) {
+    for (let attempt = 0; attempt < 5; attempt += 1) {
+        const name = `${base}.${randomBytes(8).toString("hex")}`;
+        try {
+            lstatSync(join(generationRoot, name));
+        }
+        catch (error) {
+            if (isEnoent(error))
+                return name;
+            fail("LOCAL_RUNNER_IO_ERROR", "Local CLI runner could not be installed");
+        }
+    }
+    fail("LOCAL_RUNNER_IO_ERROR", "Local CLI runner could not be installed");
+}