@webpresso/agent-kit 3.1.30 → 3.3.0

package/dist/esm/cli/commands/init/scaffolders/codex-mcp/index.js

@@ -18,15 +18,17 @@
  *      provisioned, exact-version binaries with environment-variable names
  *      forwarded through Codex's stdio `env_vars` allow-list.
  */
-import { execFileSync, spawnSync } from "node:child_process";
-import { accessSync, constants, existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-import lockfile from "proper-lockfile";
+import { agentKitMcpLaunchCommand, findWebpressoMcpEntry, resolveExecutableOnPath, resolveWebpressoMcpEntry, WEBPRESSO_MCP_SERVER_NAME, WEBPRESSO_MCP_SPEC, } from "#cli/commands/init/mcp-spec.js";
+// Re-exported so existing importers (tests) keep a stable path; the canonical
+// implementation now lives in `mcp-spec.ts`.
+export { findWebpressoMcpEntry, WEBPRESSO_MCP_SERVER_NAME };
+import { updateScaffolderTextFile } from "#cli/commands/init/scaffolders/file-transaction.js";
 import { isJsonRecord, isUnsafeRuntimeLauncher, parseJson, parseProjectMcpServers, parseTomlString, } from "#hooks/host-config-contract.js";
 import { appendGlobalCapableVpArgs, resolveGlobalCapableVpCommand, } from "#cli/global-vp.js";
-import { pathCandidates } from "#runtime/command-exists.js";
 import { writeFileAtomic } from "#shared-utils/write-json-file.js";
 export const PLAYWRIGHT_MCP_SERVER_NAME = "playwright";
 export const PLAYWRIGHT_MCP_VERSION = "0.0.78";
@@ -42,56 +44,8 @@ const PLAYWRIGHT_STDIO_MCP_DEFINITION = {
     command: "vp",
     args: ["dlx", PLAYWRIGHT_MCP_PACKAGE, ...PLAYWRIGHT_MCP_ARGS],
 };
-const CODEX_CONFIG_LOCK_TIMEOUT_MS = 5_000;
-const CODEX_CONFIG_LOCK_POLL_MS = 25;
-const CODEX_CONFIG_LOCK_STALE_MS = 30_000;
-function sleepSync(ms) {
-    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-}
-function acquireCodexConfigLock(configPath) {
-    mkdirSync(dirname(configPath), { recursive: true });
-    const startedAt = Date.now();
-    while (true) {
-        try {
-            return lockfile.lockSync(configPath, {
-                realpath: false,
-                stale: CODEX_CONFIG_LOCK_STALE_MS,
-                update: CODEX_CONFIG_LOCK_STALE_MS / 2,
-            });
-        }
-        catch (error) {
-            if (error.code !== "ELOCKED")
-                throw error;
-            if (Date.now() - startedAt >= CODEX_CONFIG_LOCK_TIMEOUT_MS) {
-                throw new Error(`Timed out waiting for Codex config lock: ${configPath}`, {
-                    cause: error,
-                });
-            }
-            sleepSync(CODEX_CONFIG_LOCK_POLL_MS);
-        }
-    }
-}
-function withCodexConfigLock(configPath, action) {
-    const release = acquireCodexConfigLock(configPath);
-    try {
-        return action();
-    }
-    finally {
-        release();
-    }
-}
-function readCodexConfig(configPath) {
-    return existsSync(configPath) ? readFileSync(configPath, "utf8") : "";
-}
 function updateCodexConfig(configPath, transform) {
-    return withCodexConfigLock(configPath, () => {
-        const existing = readCodexConfig(configPath);
-        const next = transform(existing);
-        if (next === existing)
-            return "unchanged";
-        writeFileAtomic(configPath, next, "utf8");
-        return "written";
-    });
+    return updateScaffolderTextFile(configPath, transform);
 }
 function tomlString(value) {
     return JSON.stringify(value);
@@ -118,15 +72,254 @@ export function commandMcpCodexBlock(definition) {
     if (definition.codexEnvVars && definition.codexEnvVars.length > 0) {
         lines.push(`env_vars = ${tomlStringArray(definition.codexEnvVars)}`);
     }
+    if (definition.codexEnv && Object.keys(definition.codexEnv).length > 0) {
+        const pairs = Object.entries(definition.codexEnv).map(([key, value]) => `${key} = ${tomlString(value)}`);
+        lines.push(`env = { ${pairs.join(", ")} }`);
+    }
     lines.push("enabled = true");
     for (const [key, value] of Object.entries(definition.codexFields ?? {})) {
         lines.push(`${key} = ${tomlValue(value)}`);
     }
     return `${lines.join("\n")}\n`;
 }
+function parseTomlTableHeader(line) {
+    const match = line.match(/^\s*\[\s*([\s\S]*?)\s*\]\s*(?:#.*)?$/u);
+    if (!match || line.trimStart().startsWith("[["))
+        return null;
+    return parseTomlDottedKey(match[1] ?? "");
+}
+function parseTomlArrayTableHeader(line) {
+    const match = line.match(/^\s*\[\[\s*([\s\S]*?)\s*\]\]\s*(?:#.*)?$/u);
+    if (!match)
+        return null;
+    return parseTomlDottedKey(match[1] ?? "");
+}
+function parseTomlDottedKey(raw) {
+    const segments = [];
+    let i = 0;
+    const skipSpace = () => {
+        while (/\s/u.test(raw[i] ?? ""))
+            i += 1;
+    };
+    while (i < raw.length) {
+        skipSpace();
+        const segment = parseTomlKeySegment(raw, i);
+        if (!segment)
+            return null;
+        segments.push(segment.value);
+        i = segment.next;
+        skipSpace();
+        if (i >= raw.length)
+            break;
+        if (raw[i] !== ".")
+            return null;
+        i += 1;
+    }
+    return segments.length > 0 ? segments : null;
+}
+function parseTomlKeySegment(raw, start) {
+    const first = raw[start];
+    if (first === "'") {
+        const end = raw.indexOf("'", start + 1);
+        if (end === -1)
+            return null;
+        return { value: raw.slice(start + 1, end), next: end + 1 };
+    }
+    if (first === '"') {
+        return parseBasicTomlKeySegment(raw, start);
+    }
+    let end = start;
+    while (/[A-Za-z0-9_-]/u.test(raw[end] ?? ""))
+        end += 1;
+    if (end === start)
+        return null;
+    return { value: raw.slice(start, end), next: end };
+}
+function parseBasicTomlKeySegment(raw, start) {
+    let value = "";
+    for (let i = start + 1; i < raw.length; i += 1) {
+        const ch = raw[i];
+        if (ch === '"')
+            return { value, next: i + 1 };
+        if (ch !== "\\") {
+            value += ch;
+            continue;
+        }
+        const escaped = raw[i + 1];
+        if (escaped === undefined)
+            return null;
+        const simple = {
+            b: "\b",
+            t: "\t",
+            n: "\n",
+            f: "\f",
+            r: "\r",
+            '"': '"',
+            "\\": "\\",
+        };
+        if (escaped in simple) {
+            value += simple[escaped];
+            i += 1;
+            continue;
+        }
+        if (escaped === "u" || escaped === "U") {
+            const width = escaped === "u" ? 4 : 8;
+            const hex = raw.slice(i + 2, i + 2 + width);
+            if (!new RegExp(`^[0-9A-Fa-f]{${width}}$`, "u").test(hex))
+                return null;
+            value += String.fromCodePoint(Number.parseInt(hex, 16));
+            i += 1 + width;
+            continue;
+        }
+        return null;
+    }
+    return null;
+}
+function isServerTableHeader(line, serverId) {
+    const segments = parseTomlTableHeader(line);
+    return segments?.length === 2 && segments[0] === "mcp_servers" && segments[1] === serverId;
+}
 function isOwnedSubTableHeader(line, serverId) {
-    const trimmed = line.trim();
-    return trimmed.startsWith(`[mcp_servers.${serverId}.`) && trimmed.endsWith("]");
+    const segments = parseTomlTableHeader(line);
+    return (segments !== null &&
+        segments.length > 2 &&
+        segments[0] === "mcp_servers" &&
+        segments[1] === serverId);
+}
+function isOwnedServerOrDescendantTableHeader(line, serverId) {
+    const segments = parseTomlArrayTableHeader(line) ?? parseTomlTableHeader(line);
+    return (segments !== null &&
+        segments.length >= 2 &&
+        segments[0] === "mcp_servers" &&
+        segments[1] === serverId);
+}
+function tomlLinesStartingInsideMultilineString(lines) {
+    const insideAtStart = [];
+    let delimiter = null;
+    for (const line of lines) {
+        insideAtStart.push(delimiter !== null);
+        for (let i = 0; i < line.length; i += 1) {
+            if (delimiter !== null) {
+                const end = findTomlMultilineStringEnd(line, i, delimiter);
+                if (end === -1)
+                    break;
+                i = end + delimiter.length - 1;
+                delimiter = null;
+                continue;
+            }
+            const ch = line[i];
+            if (ch === "#")
+                break;
+            if (line.startsWith('"""', i) || line.startsWith("'''", i)) {
+                delimiter = line.startsWith('"""', i) ? '"""' : "'''";
+                i += delimiter.length - 1;
+                continue;
+            }
+            if (ch === '"') {
+                i += 1;
+                while (i < line.length) {
+                    const inner = line[i];
+                    if (inner === "\\") {
+                        i += 2;
+                        continue;
+                    }
+                    if (inner === '"')
+                        break;
+                    i += 1;
+                }
+                continue;
+            }
+            if (ch === "'") {
+                const end = line.indexOf("'", i + 1);
+                if (end === -1)
+                    break;
+                i = end;
+            }
+        }
+    }
+    return insideAtStart;
+}
+function findTomlMultilineStringEnd(line, start, delimiter) {
+    if (delimiter === "'''")
+        return line.indexOf(delimiter, start);
+    for (let i = start; i < line.length; i += 1) {
+        if (!line.startsWith(delimiter, i))
+            continue;
+        let backslashes = 0;
+        for (let j = i - 1; j >= 0 && line[j] === "\\"; j -= 1)
+            backslashes += 1;
+        if (backslashes % 2 === 0)
+            return i;
+    }
+    return -1;
+}
+function tomlAssignmentKey(line) {
+    let quote = null;
+    let escaped = false;
+    for (let i = 0; i < line.length; i += 1) {
+        const ch = line[i];
+        if (quote !== null) {
+            if (quote === '"' && escaped) {
+                escaped = false;
+            }
+            else if (quote === '"' && ch === "\\") {
+                escaped = true;
+            }
+            else if (ch === quote) {
+                quote = null;
+            }
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            continue;
+        }
+        if (ch === "#")
+            return null;
+        if (ch === "=")
+            return parseTomlDottedKey(line.slice(0, i).trim());
+    }
+    return null;
+}
+function hasDottedServerDefinition(lines, startsInsideMultiline, serverId) {
+    let currentTable = null;
+    return lines.some((line, index) => {
+        if (startsInsideMultiline[index])
+            return false;
+        const arrayTable = parseTomlArrayTableHeader(line);
+        if (arrayTable !== null &&
+            arrayTable.length >= 2 &&
+            arrayTable[0] === "mcp_servers" &&
+            arrayTable[1] === serverId) {
+            return true;
+        }
+        const table = parseTomlTableHeader(line);
+        if (table !== null) {
+            currentTable = table;
+            return false;
+        }
+        const segments = tomlAssignmentKey(line);
+        return (segments !== null &&
+            ((segments.length >= 2 && segments[0] === "mcp_servers" && segments[1] === serverId) ||
+                (currentTable?.length === 1 &&
+                    currentTable[0] === "mcp_servers" &&
+                    segments[0] === serverId)));
+    });
+}
+export function hasAmbiguousMcpServerDottedDefinition(raw, serverId) {
+    const lines = raw.trimEnd().split(/\r?\n/);
+    const startsInsideMultiline = tomlLinesStartingInsideMultilineString(lines);
+    const start = lines.findIndex((line, index) => !startsInsideMultiline[index] && isServerTableHeader(line, serverId));
+    return start === -1 && hasDottedServerDefinition(lines, startsInsideMultiline, serverId);
+}
+export function hasManagedMcpServerTableConflict(raw, serverId) {
+    const lines = raw.trimEnd().split(/\r?\n/);
+    const startsInsideMultiline = tomlLinesStartingInsideMultilineString(lines);
+    const start = lines.findIndex((line, index) => !startsInsideMultiline[index] && isServerTableHeader(line, serverId));
+    if (start === -1)
+        return hasDottedServerDefinition(lines, startsInsideMultiline, serverId);
+    const end = managedSectionEnd(lines, startsInsideMultiline, start, serverId);
+    return hasOwnedServerTableOutsideManagedSection(lines, startsInsideMultiline, start, end, serverId);
 }
 /**
  * Find the exclusive end index of the managed section region: the parent block
@@ -136,9 +329,11 @@ function isOwnedSubTableHeader(line, serverId) {
  * sub-tables under foreign or absent parents are never touched (they remain
  * doctor-report-only territory).
  */
-function managedSectionEnd(lines, start, serverId) {
+function managedSectionEnd(lines, startsInsideMultiline, start, serverId) {
     let end = lines.length;
     for (let i = start + 1; i < lines.length; i += 1) {
+        if (startsInsideMultiline[i])
+            continue;
         if (!lines[i].trim().startsWith("["))
             continue;
         if (isOwnedSubTableHeader(lines[i], serverId))
@@ -146,20 +341,43 @@ function managedSectionEnd(lines, start, serverId) {
         end = i;
         break;
     }
+    // Trailing comment/blank lines between the managed block and the next table
+    // belong to the surrounding document (often annotating the *next* section) —
+    // leave them in place rather than swallowing them into the regenerated block.
+    while (end > start + 1) {
+        const previous = lines[end - 1].trim();
+        if (previous.length === 0 || previous.startsWith("#")) {
+            end -= 1;
+            continue;
+        }
+        break;
+    }
     return end;
 }
-function upsertMcpServerBlock(raw, serverId, block) {
-    const header = commandMcpHeader(serverId);
+function hasOwnedServerTableOutsideManagedSection(lines, startsInsideMultiline, start, end, serverId) {
+    return lines.some((line, index) => !startsInsideMultiline[index] &&
+        (index < start || index >= end) &&
+        isOwnedServerOrDescendantTableHeader(line, serverId));
+}
+export function upsertMcpServerBlock(raw, serverId, block) {
     const lines = raw.trimEnd().split(/\r?\n/);
     const hasContent = raw.trim().length > 0;
-    const start = lines.findIndex((line) => line.trim() === header);
+    const startsInsideMultiline = tomlLinesStartingInsideMultilineString(lines);
+    const start = lines.findIndex((line, index) => !startsInsideMultiline[index] && isServerTableHeader(line, serverId));
     if (start === -1) {
+        if (hasDottedServerDefinition(lines, startsInsideMultiline, serverId))
+            return raw;
         const prefix = hasContent ? `${raw.trimEnd()}\n\n` : "";
         return `${prefix}${block}`;
     }
-    const end = managedSectionEnd(lines, start, serverId);
+    const end = managedSectionEnd(lines, startsInsideMultiline, start, serverId);
+    if (hasOwnedServerTableOutsideManagedSection(lines, startsInsideMultiline, start, end, serverId)) {
+        return raw;
+    }
     const replacement = block.trimEnd().split("\n");
-    if (end < lines.length)
+    // Separate the block from a preserved tail — unless the tail already starts
+    // with its own blank line (kept by the trailing-comment walk-back).
+    if (end < lines.length && lines[end].trim().length !== 0)
         replacement.push("");
     return [...lines.slice(0, start), ...replacement, ...lines.slice(end)].join("\n") + "\n";
 }
@@ -176,31 +394,11 @@ export function commandMcpClaudeServer(definition) {
     }
     return server;
 }
-export const WEBPRESSO_MCP_SERVER_NAME = "webpresso";
 export const WEBPRESSO_MCP_HEADER = `[mcp_servers.${WEBPRESSO_MCP_SERVER_NAME}]`;
 function defaultConfigPath() {
     const codexHome = process.env.CODEX_HOME || join(process.env.HOME || homedir(), ".codex");
     return join(codexHome, "config.toml");
 }
-function resolvePinnedMcpExecutable(binary, env) {
-    for (const candidate of pathCandidates(binary, {
-        pathEnv: env.PATH,
-        pathExtEnv: env.PATHEXT,
-    })) {
-        try {
-            if (!statSync(candidate).isFile())
-                continue;
-            if (process.platform !== "win32")
-                accessSync(candidate, constants.X_OK);
-            return candidate;
-        }
-        catch {
-            // Continue scanning PATH. Returning the candidate, not its realpath, keeps
-            // the generated config anchored to Vite+'s stable global-bin symlink.
-        }
-    }
-    return null;
-}
 function installedGlobalPackageMetadata(vpCommand, packageName, spawn) {
     const listCommand = appendGlobalCapableVpArgs(vpCommand, [
         "list",
@@ -250,7 +448,7 @@ function selectPackageBinary(definition, metadata) {
 function provisionPinnedCodexMcp(input, definition) {
     const env = input.env ?? process.env;
     const spawn = input.spawn ?? spawnSync;
-    const resolveExecutable = input.resolveExecutable ?? ((binary) => resolvePinnedMcpExecutable(binary, env));
+    const resolveExecutable = input.resolveExecutable ?? ((binary) => resolveExecutableOnPath(binary, env));
     const vpCommand = input.resolveVpCommand !== undefined
         ? input.resolveVpCommand()
         : resolveGlobalCapableVpCommand(env.PATH ?? "", process.platform, env);
@@ -462,130 +660,13 @@ export function ensureClaudePlaywrightMcp(input) {
 // ────────────────────────────────────────────────────────────────────────────
 // Agent-kit MCP server registration
 // ────────────────────────────────────────────────────────────────────────────
-const WP_BIN_RELATIVE = join("bin", process.platform === "win32" ? "wp.cmd" : "wp");
-const WP_LAUNCHER_REQUIRED_RELATIVES = [
-    WP_BIN_RELATIVE,
-    join("bin", "_run.js"),
-    join("bin", "runtime-lanes.js"),
-    join("bin", "runtime-manifest.json"),
-];
-/**
- * Resolve the absolute path to webpresso's global `bin/wp` launcher on this machine. Probes
- * the locations consumers use to install webpresso, in order of stability:
- *
- *   1. the stable global `wp` shim available on PATH
- *   2. the currently executing `@webpresso/agent-kit` package
- *   3. Claude plugin install — `~/.claude/plugins/cache/.../agent-kit/`
- *      (path-stable; updated by Claude Code's plugin manager)
- *   4. bun global — `~/.bun/install/global/node_modules/@webpresso/agent-kit/`
- *   5. pnpm global — `$(pnpm root -g)/@webpresso/agent-kit/`
- *   6. npm global — `$(npm root -g)/@webpresso/agent-kit/`
- *
- * Returns `null` when none of the candidates contain `bin/wp`. The caller
- * surfaces a clear error rather than writing a broken codex config.
- */
-export function findWebpressoMcpEntry(probe = {}) {
-    return resolveWebpressoMcpEntry(probe).entryPath;
-}
-function isUsableWebpressoMcpRoot(root) {
-    return WP_LAUNCHER_REQUIRED_RELATIVES.every((relativePath) => existsSync(join(root, relativePath)));
-}
-function resolveWebpressoMcpEntry(probe = {}) {
-    const checked = [];
-    if (probe.candidates === undefined) {
-        const stableEntry = probe.stableEntry !== undefined
-            ? probe.stableEntry()
-            : resolvePinnedMcpExecutable("wp", process.env);
-        if (stableEntry)
-            return { entryPath: stableEntry, checked: [stableEntry] };
-    }
-    const candidateGroups = probe.candidates !== undefined ? [probe.candidates] : [defaultFixedCandidates()];
-    for (const candidates of candidateGroups) {
-        for (const root of candidates) {
-            if (!root)
-                continue;
-            checked.push(root);
-            const wpBin = join(root, WP_BIN_RELATIVE);
-            if (isUsableWebpressoMcpRoot(root))
-                return { entryPath: wpBin, checked };
-        }
-    }
-    if (probe.candidates === undefined) {
-        for (const root of defaultPackageManagerCandidates(probe)) {
-            if (!root)
-                continue;
-            checked.push(root);
-            const wpBin = join(root, WP_BIN_RELATIVE);
-            if (isUsableWebpressoMcpRoot(root))
-                return { entryPath: wpBin, checked };
-        }
-    }
-    return { entryPath: null, checked };
-}
-function defaultFixedCandidates() {
-    const home = process.env.HOME || homedir();
-    const packageRoot = currentAgentKitPackageRoot();
-    const claudePlugin = join(home, ".claude", "plugins", "cache", "webpresso", "agent-kit");
-    const bunGlobal = join(home, ".bun", "install", "global", "node_modules", "@webpresso", "agent-kit");
-    return [packageRoot ?? "", claudePlugin, bunGlobal];
-}
-function defaultPackageManagerCandidates(probe) {
-    const pnpmRoot = (probe.pnpmGlobalRoot ?? probePnpmGlobalRoot)();
-    const npmRoot = (probe.npmGlobalRoot ?? probeNpmGlobalRoot)();
-    return [
-        pnpmRoot ? join(pnpmRoot, "@webpresso", "agent-kit") : "",
-        npmRoot ? join(npmRoot, "@webpresso", "agent-kit") : "",
-    ];
-}
-function currentAgentKitPackageRoot() {
-    let current = dirname(fileURLToPath(import.meta.url));
-    for (let depth = 0; depth < 12; depth += 1) {
-        const packagePath = join(current, "package.json");
-        if (existsSync(packagePath)) {
-            try {
-                const pkg = JSON.parse(readFileSync(packagePath, "utf8"));
-                if (pkg.name === "@webpresso/agent-kit")
-                    return current;
-            }
-            catch {
-                return null;
-            }
-        }
-        const parent = dirname(current);
-        if (parent === current)
-            break;
-        current = parent;
-    }
-    return null;
-}
-function probePnpmGlobalRoot() {
-    return runQuiet("pnpm", ["root", "-g"]);
-}
-function probeNpmGlobalRoot() {
-    return runQuiet("npm", ["root", "-g"]);
-}
-function runQuiet(cmd, args) {
-    try {
-        const output = execFileSync(cmd, [...args], {
-            encoding: "utf8",
-            stdio: ["ignore", "pipe", "ignore"],
-        });
-        const trimmed = output.trim();
-        return trimmed.length > 0 ? trimmed : null;
-    }
-    catch {
-        return null;
-    }
-}
-export function agentKitMcpLaunchCommand(entryPath) {
-    return { command: entryPath, args: ["mcp"] };
-}
 export function agentKitMcpBlock(entryPath) {
     const launch = agentKitMcpLaunchCommand(entryPath);
     return commandMcpCodexBlock({
         id: WEBPRESSO_MCP_SERVER_NAME,
         command: launch.command,
         args: launch.args,
+        codexEnv: WEBPRESSO_MCP_SPEC.env,
     });
 }
 export function upsertWebpressoMcpServer(raw, entryPath) {
@@ -602,7 +683,12 @@ export function ensureCodexWebpressoMcp(input) {
         const checked = resolution?.checked ?? [];
         return { kind: "codex-webpresso-mcp-not-installed", path: configPath, checked };
     }
-    const result = updateCodexConfig(configPath, (existing) => upsertWebpressoMcpServer(existing, entryPath));
+    const existing = existsSync(configPath) ? readFileSync(configPath, "utf8") : "";
+    if (hasAmbiguousMcpServerDottedDefinition(existing, WEBPRESSO_MCP_SERVER_NAME) ||
+        hasManagedMcpServerTableConflict(existing, WEBPRESSO_MCP_SERVER_NAME)) {
+        return { kind: "codex-webpresso-mcp-ambiguous", path: configPath, entryPath };
+    }
+    const result = updateCodexConfig(configPath, (raw) => upsertWebpressoMcpServer(raw, entryPath));
     if (result === "unchanged") {
         return { kind: "codex-webpresso-mcp-unchanged", path: configPath, entryPath };
     }

package/dist/esm/cli/commands/init/scaffolders/file-transaction.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Test-only seams following the `claimInstallLock` options precedent. `isAlive`
+ * and `now` make liveness/age deterministic; `onBeforeReclaimDelete` fires while
+ * the reaper is held, just before a stale lock is removed, so a test can prove
+ * reclaim is serialized. Never supplied in production.
+ */
+export interface ScaffolderLockSeams {
+    readonly isAlive?: (pid: number) => boolean;
+    readonly now?: () => number;
+    readonly onBeforeReclaimDelete?: () => void;
+}
+/**
+ * Serialize a complete read/modify/write transaction for a host config file.
+ * These are local single-machine home-config locks (`~/.codex`, `~/.grok`), so
+ * owner-pid liveness is meaningful; this is not a shared-filesystem lock.
+ */
+export declare function withScaffolderFileLock<T>(path: string, action: () => T, seams?: ScaffolderLockSeams): T;
+/**
+ * Serialize a text-file read/modify/write and install the replacement strictly
+ * atomically without weakening an existing file's permissions.
+ */
+export declare function updateScaffolderTextFile(path: string, transform: (existing: string) => string): "written" | "unchanged";