@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

package/dist/activities/execute-cursor/workspace-hook-files.js

@@ -0,0 +1,390 @@
+/**
+ * The hook files a workspace carries, kept from running for the Cursor
+ * engine's agent, so only the agent's own hooks run on this engine as on
+ * the native one.
+ *
+ * WHY. `@cursor/sdk` loads project hooks through its `project` setting
+ * source, which the gate needs for its own `.cursor/hooks.json`, and that
+ * source loads, with no option to separate them, `<cwd>/.cursor/hooks.json`,
+ * `<cwd>/.claude/settings.json` and `<cwd>/.claude/settings.local.json` (live
+ * probe, 2026-10-05: a Claude Code hook in either settings file ran on a
+ * shell call; a second workspace folder contributed none).
+ *
+ * WHAT IS DONE. A repository's own `.cursor/hooks.json` entries are set aside
+ * for the turn: the gate writes the file with its own entries only
+ * (`workspace-setup.ts`). A `.claude` settings file's `hooks` key is set
+ * aside for the turn in a folder the runner owns, one it cloned (`git_repo`)
+ * or created (a session's own directory); every other key is kept. A
+ * person's own folder (`local_path`) is never touched: Claude Code reloads
+ * hooks when the file changes, so stripping them would switch a team's
+ * hooks off in the person's open tools for as long as the turn runs.
+ * Instead the Cursor engine refuses the turn when either file there has a
+ * non-empty `hooks` object, naming the file ({@link CursorWorkspaceHooksRefusal}).
+ * The rule is simpler than the SDK's own load test on purpose, so an SDK
+ * bump cannot quietly widen what loads; a file that does not parse refuses
+ * nothing, since the SDK loads no hooks from it. Every folder is checked,
+ * not only the one the SDK reads today. A runner-owned folder's settings
+ * file reached through a link (one that is a link, or resolves outside the
+ * folder) is never edited either, since the file it reaches may be a
+ * person's own; carrying hooks, it refuses the turn the same way.
+ *
+ * RESTORING. Every file the gate rewrites is snapshotted under the gate
+ * directory, its original bytes beside the bytes the gate wrote, before it
+ * is written ({@link rewriteWorkspaceFiles}). At the turn's end
+ * ({@link restoreWorkspaceFiles}) `.cursor/hooks.json` gets its original
+ * back whatever the agent did to it: it is the gate's file, left out of the
+ * turn's file review (`CURSOR_RUNNER_OWNED_PATHS`), so no change to it may
+ * outlive the turn unseen. A `.claude` settings file, which the review does
+ * see, gets its original back when it still holds what the gate wrote,
+ * stays deleted when the agent deleted it, and otherwise keeps the agent's
+ * edit with the set-aside hooks put back (any the agent added kept beside
+ * them), with a log line.
+ * A snapshot a crashed runner left behind is restored when the next runner
+ * boots ({@link restoreAbandonedWorkspaceFiles}), before any turn pins the
+ * tree its file review compares against; restored later, the files would
+ * read as the agent's change. A snapshot names the runner that wrote it, so
+ * a booting runner leaves alone one whose writer still runs (another runner
+ * on the same machine, mid-turn). The next install restores any snapshot
+ * still left, before anything else. The snapshot is the owner's alone (mode
+ * 0600): a settings file can carry tokens in its `env`.
+ */
+import { execFileSync } from "node:child_process";
+import { lstat, mkdir, readdir, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join, sep } from "node:path";
+const CLAUDE_DIR = ".claude";
+const CLAUDE_SETTINGS_FILES = ["settings.json", "settings.local.json"];
+const SNAPSHOT_FILE = "workspace-files.json";
+/**
+ * Each folder of the turn, owned by the runner unless provisioning mounted
+ * it from a person's own directory (`local_path`). A session's own
+ * directory has no provision result and is the runner's.
+ */
+export function workspaceFolders(dirs, provisionResults) {
+    return dirs.map((dir) => ({
+        dir,
+        runnerOwned: !provisionResults.some((result) => result.rootDir === dir && result.sourceType === "local_path"),
+    }));
+}
+/**
+ * A Cursor turn the workspace's hook files would leave unsafe:
+ *  - `own-folder`: a person's own folder's `.claude` settings carry hooks
+ *    the SDK would run, and the runner does not edit a person's folder;
+ *  - `linked`: `.claude` settings that carry hooks are reached through a
+ *    link (a file that is one, or that resolves outside its folder), which
+ *    the runner never edits;
+ *  - `gate-link`: the gate's own `.cursor/hooks.json`, or `.cursor`, is a
+ *    link. `@cursor/sdk` 1.0.31 loads no project hook file through a link,
+ *    so the gate would not run at all.
+ */
+export class CursorWorkspaceHooksRefusal extends Error {
+    constructor(files, why = "own-folder") {
+        super(refusalMessage(files, why));
+        this.name = "CursorWorkspaceHooksRefusal";
+    }
+}
+function refusalMessage(files, why) {
+    const named = files.join(" and ");
+    const carry = files.length === 1 ? "carries" : "carry";
+    switch (why) {
+        case "own-folder":
+            return (`${named} ${carry} Claude Code hooks, which the Cursor engine would run beside the agent's own. ` +
+                "Stigmer does not edit a folder of yours, so it cannot set them aside for the turn. " +
+                "Run this session on Stigmer's native engine, or move the hooks out of the folder's .claude settings.");
+        case "linked":
+            return (`${named} ${carry} Claude Code hooks and ${files.length === 1 ? "is" : "are"} reached through a link. ` +
+                "Stigmer does not edit a file through a link, so it cannot set those hooks aside for the turn. " +
+                "Run this session on Stigmer's native engine, or replace the link with a file.");
+        case "gate-link":
+            return (`${named} is a link. The Cursor engine loads no hook file through a link, so Stigmer's approval gate would not run. ` +
+                "Replace the link with a file, or run this session on Stigmer's native engine.");
+    }
+}
+/** Refuse the turn when the gate's `.cursor/hooks.json`, or `.cursor`, is a link. Throws {@link CursorWorkspaceHooksRefusal}. */
+export async function refuseLinkedGateFile(workspaceRoot) {
+    if (workspaceRoot === "")
+        return;
+    for (const path of [join(workspaceRoot, ".cursor"), join(workspaceRoot, ".cursor", "hooks.json")]) {
+        if (await isLink(path))
+            throw new CursorWorkspaceHooksRefusal([path], "gate-link");
+    }
+}
+/** The `.claude` settings files under `dir` that carry a non-empty `hooks` object. */
+export async function claudeSettingsWithHooks(dir) {
+    const found = [];
+    for (const name of CLAUDE_SETTINGS_FILES) {
+        const path = join(dir, CLAUDE_DIR, name);
+        const parsed = parseObject(await readOrNull(path));
+        const hooks = parsed?.["hooks"];
+        if (isObject(hooks) && Object.keys(hooks).length > 0)
+            found.push(path);
+    }
+    return found;
+}
+/**
+ * Refuse the turn when `.claude` hooks would run that the runner may not set
+ * aside: a person's own folder's, or a runner-owned folder's reached through
+ * a link. Throws {@link CursorWorkspaceHooksRefusal}.
+ */
+export async function refuseOwnFolderHooks(folders) {
+    const own = [];
+    const linked = [];
+    for (const folder of folders) {
+        for (const path of await claudeSettingsWithHooks(folder.dir)) {
+            if (!folder.runnerOwned)
+                own.push(path);
+            else if (await linkedOut(folder.dir, path))
+                linked.push(path);
+        }
+    }
+    if (own.length > 0)
+        throw new CursorWorkspaceHooksRefusal(own);
+    if (linked.length > 0)
+        throw new CursorWorkspaceHooksRefusal(linked, "linked");
+}
+/**
+ * Whether a settings file is reached through a link: it is one, or it
+ * resolves outside its folder (a linked `.claude` directory). Editing it
+ * would edit a file the folder does not hold, a person's own settings
+ * perhaps.
+ */
+async function linkedOut(dir, path) {
+    if ((await lstat(path)).isSymbolicLink())
+        return true;
+    const root = await realpath(dir);
+    return !(await realpath(path)).startsWith(`${root}${sep}`);
+}
+/** The `.claude` settings rewrites for the runner-owned folders: each file with a `hooks` key, without it. */
+export async function claudeSettingsRewrites(folders) {
+    const rewrites = [];
+    for (const folder of folders) {
+        if (!folder.runnerOwned)
+            continue;
+        for (const name of CLAUDE_SETTINGS_FILES) {
+            const path = join(folder.dir, CLAUDE_DIR, name);
+            const original = await readOrNull(path);
+            const parsed = parseObject(original);
+            if (original === null || parsed === undefined || !("hooks" in parsed) || (await linkedOut(folder.dir, path)))
+                continue;
+            const { hooks: _hooks, ...rest } = parsed;
+            rewrites.push({ path, kind: "claude-settings", original, written: `${JSON.stringify(rest, null, 2)}\n` });
+        }
+    }
+    return rewrites;
+}
+/**
+ * Snapshot the rewrites under the gate directory, then write each file. The
+ * install restores any earlier snapshot first, so this one is the turn's own.
+ */
+export async function rewriteWorkspaceFiles(gateDir, rewrites) {
+    const snapshotPath = join(gateDir, SNAPSHOT_FILE);
+    await mkdir(gateDir, { recursive: true });
+    const tmp = `${snapshotPath}.${process.pid}.tmp`;
+    const snapshot = { writer: process.pid, writerStarted: PROCESS_STARTED, rewrites: [...rewrites] };
+    await writeFile(tmp, JSON.stringify(snapshot), { encoding: "utf-8", mode: 0o600 });
+    await rename(tmp, snapshotPath);
+    for (const rewrite of rewrites)
+        await writeFile(rewrite.path, rewrite.written, "utf-8");
+}
+/**
+ * Put every snapshotted file back (see the header) and drop the snapshot.
+ * Never throws: a file that cannot be restored is logged and the rest
+ * still are.
+ */
+export async function restoreWorkspaceFiles(gateDir) {
+    const snapshotPath = join(gateDir, SNAPSHOT_FILE);
+    const { rewrites } = await readSnapshot(snapshotPath);
+    for (const rewrite of rewrites) {
+        try {
+            await restoreOne(rewrite);
+        }
+        catch (err) {
+            console.warn(`[workspace hooks] could not restore ${rewrite.path} (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    await rm(snapshotPath, { force: true });
+}
+/**
+ * At a runner's boot: restore every gate directory's snapshot whose writer no
+ * longer runs (see the header). Never throws: a gate directory that cannot be
+ * read is logged and the rest still are.
+ */
+export async function restoreAbandonedWorkspaceFiles(gatesRoot) {
+    let dirs;
+    try {
+        dirs = await readdir(gatesRoot);
+    }
+    catch {
+        return;
+    }
+    for (const dir of dirs) {
+        const gateDir = join(gatesRoot, dir);
+        const { writer, writerStarted, rewrites } = await readSnapshot(join(gateDir, SNAPSHOT_FILE));
+        if (rewrites.length === 0 || (writer !== process.pid && isRunning(writer, writerStarted)))
+            continue;
+        console.log(`[workspace hooks] restoring the workspace files a stopped runner set aside (${gateDir})`);
+        await restoreWorkspaceFiles(gateDir);
+    }
+}
+/** When this process started, in epoch milliseconds. */
+const PROCESS_STARTED = Date.now() - Math.round(process.uptime() * 1000);
+/**
+ * Whether the runner that wrote a snapshot still runs: its process lives and,
+ * where `ps` can tell, started when the snapshot says (a process id can be
+ * taken again by another process once its runner stopped). One this user may
+ * not signal still runs.
+ */
+function isRunning(pid, started) {
+    if (pid === undefined)
+        return false;
+    try {
+        process.kill(pid, 0);
+    }
+    catch (err) {
+        if (err.code !== "EPERM")
+            return false;
+    }
+    return started === undefined || startedNear(pid, started);
+}
+/** Whether `ps` reports the process started within two seconds of `started`; true when it cannot tell. */
+function startedNear(pid, started) {
+    try {
+        const at = Date.parse(execFileSync("ps", ["-o", "lstart=", "-p", String(pid)], { encoding: "utf-8" }).trim());
+        return Number.isNaN(at) || Math.abs(at - started) <= 2000;
+    }
+    catch {
+        return true;
+    }
+}
+async function restoreOne(rewrite) {
+    if (rewrite.kind === "cursor-hooks") {
+        await restoreGateFile(rewrite);
+        return;
+    }
+    // A link put in the file's place, or its directory's, during the turn
+    // reaches a file the folder does not hold: never written through.
+    if ((await isLink(rewrite.path)) || (await isLink(dirname(rewrite.path)))) {
+        console.warn(`[workspace hooks] ${rewrite.path} became a link during the turn; it is left as it is`);
+        return;
+    }
+    const current = await readOrNull(rewrite.path);
+    if (current === null) {
+        // The agent deleted it: its edit, kept for the turn's review to show.
+        if (rewrite.original !== null)
+            console.log(`[workspace hooks] ${rewrite.path} was deleted during the turn; the deletion is kept`);
+        return;
+    }
+    // The gate never got to write it: the file is as its owners left it.
+    if (current === rewrite.original)
+        return;
+    if (current === rewrite.written) {
+        await putBack(rewrite);
+        return;
+    }
+    const edited = parseObject(current);
+    if (edited === undefined) {
+        console.warn(`[workspace hooks] ${rewrite.path} was changed during the turn and no longer parses; the change is kept as it is`);
+        return;
+    }
+    const merged = withOriginalHooks(edited, parseObject(rewrite.original) ?? {});
+    await writeFile(rewrite.path, `${JSON.stringify(merged, null, 2)}\n`, "utf-8");
+    console.log(`[workspace hooks] ${rewrite.path} was changed during the turn; the change is kept, with the gate's own change undone`);
+}
+/**
+ * The agent's edit of a settings file, with the `hooks` the gate set aside
+ * put back (the gate rewrites only a file that has one) and any the agent
+ * added kept beside them.
+ */
+function withOriginalHooks(edited, original) {
+    const originalHooks = original["hooks"];
+    const editedHooks = edited["hooks"];
+    if (!isObject(originalHooks) || !isObject(editedHooks))
+        return { ...edited, hooks: originalHooks };
+    return { ...edited, hooks: mergedEntries(editedHooks, originalHooks) };
+}
+/**
+ * The gate's own `.cursor/hooks.json`: its original returns whatever the
+ * agent did to it, since the turn's review leaves it out. A link the agent
+ * put in its place, or in `.cursor`'s, is removed, never written through.
+ */
+async function restoreGateFile(rewrite) {
+    const dir = dirname(rewrite.path);
+    const linked = (await isLink(dir)) || (await isLink(rewrite.path));
+    if (await isLink(dir)) {
+        await rm(dir, { force: true });
+        await mkdir(dir, { recursive: true });
+    }
+    if (await isLink(rewrite.path))
+        await rm(rewrite.path, { force: true });
+    const current = await readOrNull(rewrite.path);
+    if (linked || (current !== rewrite.written && current !== rewrite.original)) {
+        console.warn(`[workspace hooks] ${rewrite.path} was changed during the turn; it is outside the turn's review, so its original returns`);
+    }
+    await putBack(rewrite);
+}
+/** The original bytes back, or the file gone when there was none. */
+async function putBack(rewrite) {
+    if (rewrite.original === null)
+        await rm(rewrite.path, { force: true });
+    else
+        await writeFile(rewrite.path, rewrite.original, "utf-8");
+}
+/** Each event's original entries, then the edit's new ones. */
+function mergedEntries(editedHooks, originalHooks) {
+    const hooks = {};
+    for (const event of new Set([...Object.keys(originalHooks), ...Object.keys(editedHooks)])) {
+        const kept = Array.isArray(originalHooks[event]) ? originalHooks[event] : [];
+        const added = (Array.isArray(editedHooks[event]) ? editedHooks[event] : []).filter((entry) => !kept.some((k) => JSON.stringify(k) === JSON.stringify(entry)));
+        if (kept.length > 0 || added.length > 0 || event in originalHooks)
+            hooks[event] = [...kept, ...added];
+    }
+    return hooks;
+}
+async function readSnapshot(path) {
+    const parsed = parseObject(await readOrNull(path));
+    const rewrites = parsed !== undefined && Array.isArray(parsed["rewrites"]) ? parsed["rewrites"].filter(isRewrite) : [];
+    const writer = parsed?.["writer"];
+    const writerStarted = parsed?.["writerStarted"];
+    return {
+        rewrites,
+        ...(typeof writer === "number" ? { writer } : {}),
+        ...(typeof writerStarted === "number" ? { writerStarted } : {}),
+    };
+}
+function isRewrite(value) {
+    return (isObject(value) &&
+        typeof value["path"] === "string" &&
+        (value["kind"] === "cursor-hooks" || value["kind"] === "claude-settings") &&
+        (value["original"] === null || typeof value["original"] === "string") &&
+        typeof value["written"] === "string");
+}
+async function isLink(path) {
+    try {
+        return (await lstat(path)).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+async function readOrNull(path) {
+    try {
+        return await readFile(path, "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+function parseObject(text) {
+    if (text === null)
+        return undefined;
+    try {
+        const value = JSON.parse(text);
+        return isObject(value) ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=workspace-hook-files.js.map

package/dist/activities/execute-cursor/workspace-hook-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-hook-files.js","sourceRoot":"","sources":["../../../src/activities/execute-cursor/workspace-hook-files.ts"],"names":[],"mappings":"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"}

package/dist/activities/execute-cursor/workspace-setup.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Installs and tears down the Cursor HITL approval gate around an agent turn.
+ *
+ * The gate has two surfaces, kept deliberately separate (issue #173):
+ *
+ * 1. Runner-owned artifacts — the hook script, approval-state file, and denial
+ *    ledger — live in the session's HITL directory OUTSIDE the user's workspace
+ *    (`~/.stigmer/sessions/{id}/hitl/`). They never touch the attached repo.
+ *
+ * 2. Workspace surface — a single `.cursor/hooks.json` written into the
+ *    workspace, because the Cursor SDK only loads project hooks from that
+ *    hard-coded path. For the turn it holds the gate's entries ONLY: a
+ *    repository's own entries are set aside, on every event, so only the
+ *    agent's own hooks run on this engine (they run inside the runner,
+ *    `hook-server.ts`), as on the native one. Every other key of the file is
+ *    kept. It points at the hook script by ABSOLUTE path (so multi-root IDE
+ *    windows can always find it instead of failing closed), and is RESTORED
+ *    when the turn ends, through the snapshot every rewritten workspace file
+ *    shares (`workspace-hook-files.ts`, which also sets aside the `.claude`
+ *    settings hooks the SDK would load from a folder the runner owns). While
+ *    the turn runs, a Cursor IDE open on the repository runs none of the
+ *    repository's hooks either.
+ *
+ * Why this shape. The previous design wrote all four files into the workspace
+ * with a repo-relative hook command and never cleaned up. For a local-folder
+ * workspace (the user's real repo, often open in their Cursor IDE) that gated
+ * the user's own IDE, ingested the IDE's tool calls into the denial ledger,
+ * failed closed in multi-root windows (relative path → exit 127), and left the
+ * gate behind after the session. Relocating the artifacts, scoping the hook to
+ * the runner's own process (see hook-script.ts), and restoring hooks.json after
+ * every turn together leave the user's repo and tooling untouched.
+ *
+ * Durability model: the install runs before every agent create/resume (and on
+ * every HITL reinvocation / Temporal activity retry); the teardown runs in the
+ * activity's finally. Each turn snapshots and restores independently, so the
+ * repo is byte-identical between turns. If a crash skips teardown, the leftover
+ * hooks.json is inert: the scope guard allows every invocation once the runner
+ * PID is gone, and the relocated artifacts are not in the repo; the next
+ * install restores what the crashed turn set aside before anything else.
+ */
+import { type ApprovalStateFile } from "./approval-state.js";
+import { type WorkspaceFolder } from "./workspace-hook-files.js";
+/** One (event -> script) registration in `.cursor/hooks.json`. */
+interface HookRegistration {
+    event: string;
+    scriptPath: string;
+}
+/**
+ * The longest one of an agent's hooks may run on this engine, in seconds.
+ * `@cursor/sdk` reads `.cursor/hooks.json` once and keeps it (for the
+ * process, and for a parked agent's executor), so the gate's registration
+ * is the same for every turn: its timeout cannot follow the agent's hooks.
+ * An agent with a longer hook is refused (`turn-setup.ts` `prepareHooks`).
+ */
+export declare const MAX_HOOK_TIMEOUT_SECONDS = 3600;
+/** The agent's hooks as the gate installs them: where they are served. */
+export interface GateHooks {
+    readonly socketPath: string;
+    readonly token: string;
+}
+/**
+ * Handle returned by {@link installHitlGate}, consumed by {@link removeHitlGate}
+ * to restore the workspace to its pre-turn state.
+ */
+export interface HitlGateHandle {
+    /** Absolute path of the workspace hooks.json this turn manages. */
+    hooksJsonPath: string;
+    /**
+     * The `.cursor/rules/stigmer-tool-approval.mdc` this turn manages: its
+     * absolute path and the bytes to restore (null → teardown deletes the file,
+     * the normal case since the filename is runner-owned).
+     */
+    rule: WorkspaceFileSnapshot;
+    /**
+     * Workspace-scoped gate directory holding the stable hook script and the
+     * active-turn pointer. Teardown drops the pointer (see removeHitlGate) so the
+     * gate is inert between turns.
+     */
+    gateDir: string;
+}
+/** Absolute path + restore target for a single workspace file the gate manages. */
+interface WorkspaceFileSnapshot {
+    path: string;
+    restoreTo: string | null;
+}
+/**
+ * Install the HITL approval gate for one agent turn.
+ *
+ * Writes the runner-owned artifacts into {@link hitlDir} and installs the merged
+ * `.cursor/hooks.json` into {@link workspaceRoot}, returning a handle that
+ * {@link removeHitlGate} uses to restore the workspace afterward.
+ */
+export declare function installHitlGate(params: {
+    workspaceRoot: string;
+    hitlDir: string;
+    approvalState: ApprovalStateFile;
+    runnerPid: number;
+    /** The agent's hooks, when it has any. */
+    hooks?: GateHooks;
+    /** The turn's workspace folders: the runner-owned ones' `.claude` settings hooks are set aside for the turn. */
+    folders?: readonly WorkspaceFolder[];
+}): Promise<HitlGateHandle>;
+/**
+ * Restore the workspace to its pre-turn state.
+ *
+ * Best-effort and never throws: a teardown failure must not fail the execution,
+ * and a leftover hooks.json is inert anyway (see the module doc).
+ */
+export declare function removeHitlGate(handle: HitlGateHandle): Promise<void>;
+/**
+ * Identify a hook entry the gate itself wrote — in this turn, a prior
+ * crash-leftover turn, or a pre-#173 runner build — so a re-install never
+ * duplicates it and a restore strips it. Matches two runner-owned shapes, never
+ * a user's own hook:
+ *
+ * 1. Current: any script under the runner-owned `~/.stigmer/` tree (the session
+ *    HITL dir or the workspace gate dir, `~/.stigmer/.../*.sh`) — location-based,
+ *    so it covers every gate script regardless of name.
+ * 2. Legacy: a `stigmer-*.sh` script (historically the in-workspace
+ *    `.cursor/hooks/stigmer-approval.sh`) — recognized by its unmistakably
+ *    runner-owned basename. Without this, the old in-workspace hook is treated
+ *    as a user hook and preserved by the merge, so it keeps running alongside
+ *    (and vetoing) the current gate. The `stigmer-` prefix is the same
+ *    runner-owned namespace convention as the rule filename.
+ */
+export declare function isStigmerHookEntry(entry: unknown): boolean;
+/**
+ * Compute the turn's hooks.json and the content to restore afterward.
+ *
+ * The turn's file holds the gate's entries only: every event's repository
+ * entries are set aside for the turn (the module doc says why), and every
+ * other key of the file is kept.
+ *
+ * - No existing file → write the gate's config; restore by deleting (null).
+ * - Existing, parseable file → the gate's hooks in place of the file's,
+ *   every other field kept; restore the original bytes. Any stale Stigmer
+ *   entry from a prior crashed turn is stripped from the restore target
+ *   (self-healing).
+ * - Existing, unparseable file → replace for the turn with the gate's config;
+ *   restore the original bytes (we never "fix" a file).
+ *
+ * Exported for unit testing — this is the load-bearing data transformation.
+ */
+export declare function buildMergedConfig(originalRaw: string | null, registrations: HookRegistration[], timeoutSeconds?: number): {
+    merged: string;
+    restoreTo: string | null;
+};
+export {};