@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

package/dist/activities/execute-cursor/turn.js

@@ -0,0 +1,247 @@
+/**
+ * One Cursor engine turn — the SDK slice of the Cursor harness, behind the
+ * turn runtime's contract (`harness/types.ts`).
+ *
+ * `runCursorTurn` is what `adapter.ts`'s `runTurn` delegates to: the HITL
+ * gate, the agent (parked, created or resumed), the prompt, the stream, the
+ * turn boundary, `run.wait()` and its recovery spines, and its own teardown
+ * (the denial watcher, the gate, the run's trace span, and what becomes of the agent
+ * handle). Everything else about a turn is the runtime's
+ * (`harness/run-turn.ts`): the resolution phases, the persist chokepoint, the
+ * watchdog, the cost cap, the interruption table, the completion epilogue,
+ * the lock.
+ *
+ * This module is where `@cursor/sdk` enters the adapter's graph (through
+ * `turn-setup.ts` and its siblings), which is WHY it is a separate module
+ * from `adapter.ts` and is loaded there with a dynamic import inside `boot`:
+ * the adapter's HTTP/2 interceptor must patch `node:http2` before the SDK
+ * (and, through it, `@connectrpc/connect-node`) is first imported, and the
+ * composition roots import `adapter.ts` before they boot it. Nothing outside
+ * `adapter.ts` imports this module.
+ *
+ * Never throws out of `runCursorTurn` (an SDK failure is `failed` with the
+ * classifier's sentence; a turn the agent's tool lists, its hooks or the
+ * workspace's hook files refused at setup is `failed` on the `actionable`
+ * surface with the refusal's own sentence; an
+ * unexpected exception is `failed` on the `internal` surface; a
+ * `CancelledFailure` never exists here), never branches
+ * on why `stopSignal` aborted, never writes a phase or a terminal copy, never
+ * imports `@temporalio/*` (`__tests__/adapter-is-temporal-free.test.ts`).
+ *
+ * Engine disposition, one rule per outcome: the agent is PARKED
+ * for the session's next turn on every exit but a failure — `completed`,
+ * `cancelled`, `awaiting_approval` and `interrupted` alike (a wedged handle
+ * after a stall is caught by the poisoned-handle recovery on the next turn;
+ * before #1070 a pause, a shutdown and a stall dropped the handle, leaking the
+ * executor lease). A `failed` turn keeps the orchestrator's three
+ * dispositions: an engine-reported failure parks (a bad key is not a bad
+ * handle), a user-actionable failure closes, an internal failure drops.
+ *
+ * Extracted from `index.ts` `executeCursorInner` and moved out of
+ * `adapter.ts` in #1070; the seventeen hermetic goldens under `__tests__/hermetic/`
+ * pin the result byte for byte.
+ */
+import { describeExecutionError } from "../../shared/model-error.js";
+import { HookSetupError } from "../../shared/hooks/setup.js";
+import { ToolListResolutionError } from "../../shared/tool-lists.js";
+import { cacheSessionAgent } from "./agent-session-cache.js";
+import { formatClassifiedError, synthesizeError } from "./error-classifier.js";
+import { setInterceptorExecutionId } from "./fetch-interceptor.js";
+import { closeProxySessions } from "./http2-interceptor.js";
+import { clearCapturedRejection, getCapturedRejection } from "./rejection-capture.js";
+import { newTurnStreamState } from "./turn-stream.js";
+import { CursorWorkspaceHooksRefusal } from "./workspace-hook-files.js";
+import { CursorRunTelemetry } from "./run-telemetry.js";
+import { streamAndSettle, usageSnapshotFor } from "./turn-settle.js";
+import { buildTurnPrompt, checkToolScope, checkWorkspaceHookFiles, CursorToolListRefusal, installGate, prepareHooks, readAdjudicatedRows, resolveCursorMode, resolveEngine, } from "./turn-setup.js";
+export async function runCursorTurn(input, sink, config) {
+    const { executionId, sessionId } = input;
+    // Ensure fresh HTTP/2 transport — prevents a degraded session from a
+    // prior execution on this worker from poisoning this one's agent stream.
+    closeProxySessions();
+    // The module-level fallback the interceptors read when no execution
+    // context is entered (the runtime enters one around the whole activity;
+    // the SDK warm-up in main.ts has none). Deprecated; its removal is #1132.
+    setInterceptorExecutionId(executionId);
+    if (sink.stopSignal.aborted)
+        return { kind: "interrupted" };
+    let engine;
+    let gate;
+    let finishTurnTelemetry;
+    let outcome;
+    try {
+        // The flags the stream produces that outlive the loop: created before the
+        // gate so the denial watcher can write into them.
+        const streamState = newTurnStreamState();
+        const mode = resolveCursorMode(input, config);
+        checkToolScope(input, mode);
+        await checkWorkspaceHookFiles(input);
+        const hooks = await prepareHooks(input, sink, config, mode);
+        const rows = readAdjudicatedRows(input, sink.rows);
+        gate = await installGate(input, sink, rows, streamState, hooks);
+        if (sink.stopSignal.aborted)
+            return (outcome = { kind: "interrupted" });
+        engine = await resolveEngine(input, sink, config, mode, hooks);
+        sink.recordActivity();
+        if (sink.stopSignal.aborted)
+            return (outcome = { kind: "interrupted" });
+        const prompt = await buildTurnPrompt(input, sink, engine, rows);
+        // The Cursor run's trace span (`run-telemetry.ts`): the whole engine
+        // stretch (agent.send + stream + any recovery retry + the turn
+        // boundary), its tool calls under it, ended once from the finally so it
+        // never leaks on a non-happy path, with every usage report's tokens.
+        const telemetry = CursorRunTelemetry.start({ model: engine.validatedModel, mode: engine.agentMode });
+        let turnTelemetryFinished = false;
+        const resolvedEngine = engine;
+        finishTurnTelemetry = async () => {
+            if (turnTelemetryFinished)
+                return;
+            turnTelemetryFinished = true;
+            telemetry.end(outcome);
+            const usage = usageSnapshotFor(sink);
+            try {
+                const { recordTurnMetrics } = await import("../../otel.js");
+                const startedAt = sink.status.startedAt ? new Date(sink.status.startedAt).getTime() : Date.now();
+                await recordTurnMetrics({
+                    durationMs: Date.now() - startedAt,
+                    inputTokens: Number(usage.inputTokens),
+                    outputTokens: Number(usage.outputTokens),
+                    model: resolvedEngine.validatedModel,
+                    mode: resolvedEngine.agentMode,
+                });
+            }
+            catch {
+                // Metrics not initialized — silently skip.
+            }
+        };
+        outcome = await streamAndSettle({ input, sink, engine, gate, prompt, rows, streamState, telemetry });
+        return outcome;
+    }
+    catch (err) {
+        outcome = await classifyThrown(err, input, config, engine);
+        return outcome;
+    }
+    finally {
+        // End the Cursor run's spans + record metrics on EVERY exit path (idempotent).
+        await finishTurnTelemetry?.();
+        // Close the denial-ledger watcher on EVERY exit path (idempotent) so no
+        // orphaned fs.watch handle survives the turn.
+        gate?.stopDenialWatcher();
+        // Tear down the HITL gate on EVERY exit path (success, error, approval
+        // pause, stop) so attaching a real repo leaves the user's .cursor/hooks.json
+        // untouched between turns (issue #173). Best-effort: a leftover hooks.json
+        // is inert because the scope guard allows all invocations once this
+        // runner PID is gone. The `.stigmer` link is the runtime's to remove,
+        // after this.
+        if (gate) {
+            try {
+                await gate.removeGate();
+            }
+            catch (cleanupErr) {
+                console.warn(`ExecuteCursor HITL gate teardown failed (non-fatal): ` +
+                    `execution=${executionId}, error=${cleanupErr instanceof Error ? cleanupErr.message : cleanupErr}`);
+            }
+        }
+        if (engine)
+            disposeEngine(engine, sessionId, outcome);
+    }
+}
+/**
+ * What becomes of the agent handle (see the header). Parking keeps the
+ * executor lease (and its MCP subprocesses) warm for the session's next
+ * turn; the idle TTL / shutdown hooks in agent-session-cache own the
+ * eventual release, so cache buildup across sessions stays bounded (#215).
+ */
+function disposeEngine(engine, sessionId, outcome) {
+    const park = () => cacheSessionAgent(sessionId, engine.resolution.agent, engine.agentFingerprint);
+    const close = () => {
+        try {
+            engine.resolution.agent.close();
+        }
+        catch {
+            /* best effort */
+        }
+    };
+    if (outcome === undefined) {
+        // No outcome means the catch itself threw; nothing sane to do with the handle.
+        return;
+    }
+    switch (outcome.kind) {
+        case "completed":
+        case "cancelled":
+        case "awaiting_approval":
+        case "interrupted":
+        // The Cursor SDK has no tool-round budget, so this adapter never ends a
+        // turn `tool_call_limit`; were it to, the engine would be parked like any
+        // other non-failed exit (the conversation continues on the next message).
+        case "tool_call_limit":
+            park();
+            return;
+        case "failed":
+            switch (outcome.surface) {
+                case "engine":
+                    park();
+                    return;
+                case "actionable":
+                    close();
+                    return;
+                case "internal":
+                    return;
+                default: {
+                    const exhaustive = outcome.surface;
+                    throw new Error(`cursor adapter: unknown failure surface ${String(exhaustive)}`);
+                }
+            }
+        default: {
+            const exhaustive = outcome;
+            throw new Error(`cursor adapter: unknown outcome ${JSON.stringify(exhaustive)}`);
+        }
+    }
+}
+/**
+ * An exception that escaped the turn, classified: a thrown `CursorSdkError`
+ * carries structured fields (code/status/endpoint/requestId) the generic
+ * description would flatten, so it goes through the same classifier as the
+ * `run.wait()` error path; anything else is described by
+ * `describeExecutionError` (a model error arrives MiddlewareError-wrapped
+ * with raw provider prose; non-model errors keep the root error's identity).
+ * Both are the `internal` surface: the runner or its transport broke. A turn
+ * refused at setup is the exception: by the agent's tool lists
+ * (`ToolListResolutionError`, `CursorToolListRefusal`), by a hook that
+ * cannot run as written (`HookSetupError`), or by a person's own folder
+ * whose `.claude` settings carry hooks (`CursorWorkspaceHooksRefusal`). It
+ * is `failed` on the `actionable` surface with the error's own sentence,
+ * since the fix is the agent's author's or the folder owner's, exactly as
+ * the native engine settles its own.
+ */
+async function classifyThrown(err, input, config, engine) {
+    const { executionId } = input;
+    if (err instanceof ToolListResolutionError ||
+        err instanceof CursorToolListRefusal ||
+        err instanceof HookSetupError ||
+        err instanceof CursorWorkspaceHooksRefusal) {
+        console.warn(`ExecuteCursor refused the turn: execution=${executionId}, ${err.message}`);
+        return { kind: "failed", surface: "actionable", message: err.message, cause: err };
+    }
+    const fallbackContext = engine
+        ? { model: engine.validatedModel, mode: engine.agentMode, agentId: engine.resolution.agentId }
+        : { model: input.model.requested, mode: "local", agentId: "" };
+    const { CursorSdkError } = await import("@cursor/sdk");
+    if (err instanceof CursorSdkError) {
+        console.error(`ExecuteCursor SDK error: execution=${executionId}, sdkError=${JSON.stringify(err.toJSON())}`);
+        const classified = synthesizeError({
+            sdkError: { code: err.code, status: err.status, message: err.message },
+            sdkResultFields: undefined,
+            streamErrorMessage: undefined,
+            capturedRejection: getCapturedRejection(executionId),
+            isResumedHandle: false,
+            fallbackContext,
+        });
+        clearCapturedRejection(executionId);
+        return { kind: "failed", surface: "internal", message: formatClassifiedError(classified), cause: err };
+    }
+    const { errorType, errorMessage } = describeExecutionError(err, { proxyMode: !!config.proxyEndpoint });
+    console.error(`ExecuteCursor failed: execution=${executionId}, [${errorType}] ${errorMessage}`);
+    return { kind: "failed", surface: "internal", message: `[${errorType}] ${errorMessage}`, cause: err };
+}
+//# sourceMappingURL=turn.js.map

package/dist/activities/execute-cursor/turn.js.map

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

package/dist/activities/execute-cursor/usage-pricing.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The Cursor harness's half of usage accounting: pricing one `turn-ended`
+ * delta at the rates of the variant this turn requested, and naming that
+ * basis on the priced delta the runtime accumulates.
+ *
+ * The runtime cannot price without the vendor's table and variant semantics,
+ * and it must not import them, so the adapter hands
+ * `TurnSink.reportUsage` a delta that already carries `estimatedCostUsd`
+ * and the basis (`model`, the catalog-validated id; `requestedModelParams`,
+ * the JSON of the params sent with every create/resume) the runtime writes
+ * into `streaming_usage`. Split out of the accumulator in #1070
+ * (`harness/usage-accumulator.ts` keeps the sums); the arithmetic and the
+ * rounding are unchanged, so the estimate is byte-for-byte the old one.
+ *
+ * Estimate at the rates of the variant we explicitly requested: a FAST run
+ * priced at base rates would understate the display estimate ~4x relative
+ * to the authoritative bill (#357). Thinking is price-neutral (#772) and
+ * never enters the estimate.
+ */
+import type { ModelParameterValue } from "@cursor/sdk";
+import { ServiceTier } from "@stigmer/apis/ai/stigmer/agentic/run/v1/enum_pb";
+import type { UsageDelta } from "../../harness/types.js";
+/** The token counts of one `turn-ended` delta as the Cursor SDK reports them. */
+export interface TurnUsage {
+    readonly inputTokens?: number;
+    readonly outputTokens?: number;
+    readonly cacheReadTokens?: number;
+    readonly cacheWriteTokens?: number;
+}
+export declare class CursorUsagePricer {
+    private readonly model;
+    private readonly requestedServiceTier;
+    /** JSON-encoded params the runner sent with the model selection (#357); "" when none. */
+    private readonly requestedModelParams;
+    constructor(model: string, requestedServiceTier: ServiceTier, requestedModelParams?: readonly ModelParameterValue[]);
+    /** One SDK usage delta, priced and attributed, ready for `TurnSink.reportUsage`. */
+    price(usage: TurnUsage): UsageDelta;
+}

package/dist/activities/execute-cursor/usage-pricing.js

@@ -0,0 +1,50 @@
+/**
+ * The Cursor harness's half of usage accounting: pricing one `turn-ended`
+ * delta at the rates of the variant this turn requested, and naming that
+ * basis on the priced delta the runtime accumulates.
+ *
+ * The runtime cannot price without the vendor's table and variant semantics,
+ * and it must not import them, so the adapter hands
+ * `TurnSink.reportUsage` a delta that already carries `estimatedCostUsd`
+ * and the basis (`model`, the catalog-validated id; `requestedModelParams`,
+ * the JSON of the params sent with every create/resume) the runtime writes
+ * into `streaming_usage`. Split out of the accumulator in #1070
+ * (`harness/usage-accumulator.ts` keeps the sums); the arithmetic and the
+ * rounding are unchanged, so the estimate is byte-for-byte the old one.
+ *
+ * Estimate at the rates of the variant we explicitly requested: a FAST run
+ * priced at base rates would understate the display estimate ~4x relative
+ * to the authoritative bill (#357). Thinking is price-neutral (#772) and
+ * never enters the estimate.
+ */
+import { ServiceTier } from "@stigmer/apis/ai/stigmer/agentic/run/v1/enum_pb";
+import { getCursorModelPricingForVariant, computeTurnCost } from "./model-pricing.js";
+export class CursorUsagePricer {
+    model;
+    requestedServiceTier;
+    /** JSON-encoded params the runner sent with the model selection (#357); "" when none. */
+    requestedModelParams;
+    constructor(model, requestedServiceTier, requestedModelParams = []) {
+        this.model = model;
+        this.requestedServiceTier = requestedServiceTier;
+        this.requestedModelParams = requestedModelParams.length > 0 ? JSON.stringify(requestedModelParams) : "";
+    }
+    /** One SDK usage delta, priced and attributed, ready for `TurnSink.reportUsage`. */
+    price(usage) {
+        const inputTokens = usage.inputTokens ?? 0;
+        const outputTokens = usage.outputTokens ?? 0;
+        const cacheReadTokens = usage.cacheReadTokens ?? 0;
+        const cacheWriteTokens = usage.cacheWriteTokens ?? 0;
+        const pricing = getCursorModelPricingForVariant(this.model, this.requestedServiceTier === ServiceTier.FAST ? "fast" : null);
+        return {
+            inputTokens,
+            outputTokens,
+            cacheReadTokens,
+            cacheWriteTokens,
+            estimatedCostUsd: computeTurnCost(pricing, inputTokens, outputTokens, cacheWriteTokens, cacheReadTokens),
+            model: this.model,
+            requestedModelParams: this.requestedModelParams,
+        };
+    }
+}
+//# sourceMappingURL=usage-pricing.js.map

package/dist/activities/execute-cursor/usage-pricing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-pricing.js","sourceRoot":"","sources":["../../../src/activities/execute-cursor/usage-pricing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,EAAE,WAAW,EAAE,MAAM,iDAAiD,CAAC;AAG9E,OAAO,EAAE,+BAA+B,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAUtF,MAAM,OAAO,iBAAiB;IAKT;IACA;IALnB,yFAAyF;IACxE,oBAAoB,CAAS;IAE9C,YACmB,KAAa,EACb,oBAAiC,EAClD,uBAAuD,EAAE;QAFxC,UAAK,GAAL,KAAK,CAAQ;QACb,yBAAoB,GAApB,oBAAoB,CAAa;QAGlD,IAAI,CAAC,oBAAoB,GAAG,oBAAoB,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC1G,CAAC;IAED,oFAAoF;IACpF,KAAK,CAAC,KAAgB;QACpB,MAAM,WAAW,GAAG,KAAK,CAAC,WAAW,IAAI,CAAC,CAAC;QAC3C,MAAM,YAAY,GAAG,KAAK,CAAC,YAAY,IAAI,CAAC,CAAC;QAC7C,MAAM,eAAe,GAAG,KAAK,CAAC,eAAe,IAAI,CAAC,CAAC;QACnD,MAAM,gBAAgB,GAAG,KAAK,CAAC,gBAAgB,IAAI,CAAC,CAAC;QACrD,MAAM,OAAO,GAAG,+BAA+B,CAC7C,IAAI,CAAC,KAAK,EACV,IAAI,CAAC,oBAAoB,KAAK,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAC/D,CAAC;QACF,OAAO;YACL,WAAW;YACX,YAAY;YACZ,eAAe;YACf,gBAAgB;YAChB,gBAAgB,EAAE,eAAe,CAAC,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,gBAAgB,EAAE,eAAe,CAAC;YACxG,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,oBAAoB,EAAE,IAAI,CAAC,oBAAoB;SAChD,CAAC;IACJ,CAAC;CACF"}

package/dist/activities/execute-cursor/workspace-hook-files.d.ts

@@ -0,0 +1,116 @@
+/**
+ * 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 type { ProvisionResult } from "../../shared/workspace/types.js";
+/** One workspace folder, and whether the runner owns it. */
+export interface WorkspaceFolder {
+    readonly dir: string;
+    readonly runnerOwned: boolean;
+}
+/**
+ * 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 declare function workspaceFolders(dirs: readonly string[], provisionResults: readonly ProvisionResult[]): WorkspaceFolder[];
+/**
+ * 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 declare class CursorWorkspaceHooksRefusal extends Error {
+    constructor(files: readonly string[], why?: "own-folder" | "linked" | "gate-link");
+}
+/** Refuse the turn when the gate's `.cursor/hooks.json`, or `.cursor`, is a link. Throws {@link CursorWorkspaceHooksRefusal}. */
+export declare function refuseLinkedGateFile(workspaceRoot: string): Promise<void>;
+/** The `.claude` settings files under `dir` that carry a non-empty `hooks` object. */
+export declare function claudeSettingsWithHooks(dir: string): Promise<string[]>;
+/**
+ * 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 declare function refuseOwnFolderHooks(folders: readonly WorkspaceFolder[]): Promise<void>;
+/** How a rewritten file's original is put back over an agent's edit. */
+export type RewriteKind = "cursor-hooks" | "claude-settings";
+/** One file the gate rewrites for the turn. */
+export interface WorkspaceFileRewrite {
+    readonly path: string;
+    readonly kind: RewriteKind;
+    /** The bytes to restore; `null` when the file did not exist. */
+    readonly original: string | null;
+    /** The bytes the gate writes. */
+    readonly written: string;
+}
+/** The `.claude` settings rewrites for the runner-owned folders: each file with a `hooks` key, without it. */
+export declare function claudeSettingsRewrites(folders: readonly WorkspaceFolder[]): Promise<WorkspaceFileRewrite[]>;
+/**
+ * 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 declare function rewriteWorkspaceFiles(gateDir: string, rewrites: readonly WorkspaceFileRewrite[]): Promise<void>;
+/**
+ * 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 declare function restoreWorkspaceFiles(gateDir: string): Promise<void>;
+/**
+ * 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 declare function restoreAbandonedWorkspaceFiles(gatesRoot: string): Promise<void>;