@lucascouts/claude-agent-tui 0.1.0

package/dist/event-switch.js

@@ -0,0 +1,206 @@
+/**
+ * Narrowing helper: a non-null plain object (mirrors ./jsonl.ts `isObject`). Arrays and `null` are
+ * excluded so we can read string-keyed props safely.
+ */
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Default drift sink: log the record to STDERR via `console.error`. NEVER `console.log`/stdout —
+ * stdout is the ACP protocol channel (see ./index.ts, which redirects all `console.*` to stderr for
+ * exactly this reason). Used when the caller supplies no `onDrift`. Logging-only: billing-free and
+ * side-effect-free beyond the log line.
+ */
+function defaultDriftSink(record) {
+    console.error(`[jsonl-drift] ${JSON.stringify({
+        kind: record.kind,
+        type: record.type,
+        fields: record.fields,
+        version: record.version,
+    })}`);
+}
+/**
+ * The documented top-level keys of {@link JsonlEvent} (the universal fields + per-type extras).
+ * Used ONLY for KEY-drift detection — naming top-level fields that are NOT in this set. This is a
+ * SEPARATE concern from the type-routing `switch`, whose arms stay explicit and individually
+ * removable; this Set is NOT a `KNOWN_TYPES.has(type)` membership shortcut and never gates routing.
+ */
+const KNOWN_EVENT_FIELDS = new Set([
+    "uuid",
+    "type",
+    "timestamp",
+    "sessionId",
+    "message",
+    "parentToolUseId",
+    "userType",
+    "parentUuid",
+    "cwd",
+    "gitBranch",
+    "version",
+    "isSidechain",
+    "entrypoint",
+    "requestId",
+    "promptId",
+    "toolUseResult",
+    "permissionMode",
+]);
+/**
+ * The event's top-level keys that are NOT in {@link KNOWN_EVENT_FIELDS} — the "unrecognised" fields.
+ * A non-object event yields `[]` (nothing to inspect).
+ *
+ * @param event the typed event (or any value — non-objects yield no fields).
+ * @returns the unrecognised top-level key names (empty when all keys are documented).
+ */
+function unrecognisedFields(event) {
+    if (!isObject(event))
+        return [];
+    return Object.keys(event).filter((key) => !KNOWN_EVENT_FIELDS.has(key));
+}
+/**
+ * Field-level drift for a KNOWN, routed type: if the event carries unrecognised top-level field(s),
+ * emit ONE `unknown-fields` drift record naming them. Routing is UNCHANGED — this is observational
+ * only. A fully-documented event emits nothing. Called from every documented arm (via {@link
+ * classifyContent} / {@link classifyLifecycle}) so the check covers all routed types in one place.
+ *
+ * @param event the routed typed event.
+ * @param onDrift the resolved drift sink.
+ */
+function reportFieldDrift(event, onDrift) {
+    const fields = unrecognisedFields(event);
+    if (fields.length === 0)
+        return;
+    onDrift({ kind: "unknown-fields", type: event.type, fields, version: event.version, event });
+}
+/**
+ * Content normaliser for the content path: produce a UNIFORM block array so every downstream branch
+ * (and the §7 translators of story 018) can `.map`/index over content without ever tripping on the
+ * raw-string form documented in §6. Three shapes:
+ *   - ARRAY  → returned VERBATIM (same reference; arbitrary block fields preserved untouched, which
+ *     Task 1.4's block typing relies on). We never mutate it.
+ *   - STRING → wrapped as a single `[{ type: 'text', text: <string> }]` block (a FRESH array, so the
+ *     input event is left untouched).
+ *   - absent / anything else → `[]`.
+ * This is the SINGLE source for both the `assistant` and `user` content arms, applied BEFORE any
+ * block-type inspection so a string `message.content` can never throw an indexing/`.map` (Task 1.3).
+ *
+ * @param message the API message object (or any value — non-matching shapes yield `[]`).
+ * @returns the normalised {@link ContentBlock} array (string → one text block; non-array/non-string → `[]`).
+ */
+function normaliseContent(message) {
+    if (!isObject(message))
+        return [];
+    const content = message.content;
+    // The array passes through UNCHANGED (no mutation). `Array.isArray` only narrows to `unknown[]`,
+    // so we assert to `ContentBlock[]`: the open catch-all union member (`{type,...}`) makes any block
+    // structurally assignable, so this cast is sound and PRESERVES arbitrary extras (caller, tool_reference).
+    if (Array.isArray(content))
+        return content;
+    // A raw string becomes a single TextBlock (a FRESH array; the input event is left untouched).
+    if (typeof content === "string")
+        return [{ type: "text", text: content }];
+    return []; // absent / non-string / non-array
+}
+/**
+ * Build the content-path classification for a content-bearing event. Factored out so both the
+ * `assistant` and `user` arms route through one place and the extraction stays naive-but-isolated.
+ * Surfaces field-level drift (via {@link reportFieldDrift}) WITHOUT altering routing.
+ */
+function classifyContent(type, event, onDrift) {
+    // Field-drift is observational and must not change the result — report before building it.
+    reportFieldDrift(event, onDrift);
+    return {
+        class: "content",
+        type,
+        // For `assistant` / `user`, the message role equals the event type.
+        role: type,
+        content: normaliseContent(event.message),
+        event,
+    };
+}
+/**
+ * Build the lifecycle-path classification for a recognised non-content event. Surfaces field-level
+ * drift (via {@link reportFieldDrift}) WITHOUT altering routing.
+ */
+function classifyLifecycle(event, onDrift) {
+    reportFieldDrift(event, onDrift);
+    return { class: "lifecycle", type: event.type, event };
+}
+/**
+ * Route a story-015 typed {@link JsonlEvent} by its `.type` to the appropriate classification.
+ *
+ * The two content-bearing types are dispatched to the content-block path consumed by the §7
+ * translators; the 13 documented lifecycle/metadata types (`system`, `result`, `started`, `mode`,
+ * `permission-mode`, `file-history-snapshot`, `attachment`, `queue-operation`, `last-prompt`,
+ * `ai-title`, `pr-link`, `agent-name`, and the post-`/compact` `summary`) are classified as
+ * recognised, NON-content events that neither crash nor reach a content translator. Every documented
+ * type has its OWN explicit `case` arm (no membership check) so drift against the DEFAULT branch is
+ * observable.
+ *
+ * No custom parsing is performed — the event already arrives typed from story 015's `projectEvent`;
+ * this function ONLY dispatches on `event.type`.
+ *
+ * Drift telemetry (R1.2, R3, R6): an UNRECOGNISED `.type` is a LOGGED, NON-FATAL drop — it emits an
+ * `unknown-type` record through `onDrift`, then returns a `drift` classification WITHOUT throwing and
+ * WITHOUT producing any ACP SessionUpdate. A KNOWN, routed type carrying unexpected top-level field(s)
+ * additionally emits an `unknown-fields` record (its routing is UNCHANGED). When `opts.onDrift` is
+ * omitted, drift is logged to STDERR via {@link defaultDriftSink}. Telemetry is billing-free and
+ * side-effect-free beyond logging, so the read path never assumes a fixed `.type` set.
+ *
+ * @param event the typed event projected by story 015's `projectEvent`.
+ * @param opts injectable `onDrift` seam; defaults to the stderr {@link defaultDriftSink}.
+ * @returns the {@link EventClassification} for the event.
+ */
+export function classifyEvent(event, opts = {}) {
+    // Resolve the drift sink once: caller-supplied seam, else the stderr default (never stdout).
+    const onDrift = opts.onDrift ?? defaultDriftSink;
+    switch (event.type) {
+        // --- Content-bearing types → the §7 translator content-block path -------------------------
+        case "assistant":
+            return classifyContent("assistant", event, onDrift);
+        case "user":
+            return classifyContent("user", event, onDrift);
+        // --- Lifecycle / metadata types → recognised, classified, NON-content ---------------------
+        // Each is an EXPLICIT, individually-removable `case` label (NOT a membership check) so that
+        // drift against the DEFAULT branch stays observable. The post-`/compact` `summary` is included.
+        case "system":
+            return classifyLifecycle(event, onDrift);
+        case "result":
+            return classifyLifecycle(event, onDrift);
+        case "started":
+            return classifyLifecycle(event, onDrift);
+        case "mode":
+            return classifyLifecycle(event, onDrift);
+        case "permission-mode":
+            return classifyLifecycle(event, onDrift);
+        case "file-history-snapshot":
+            return classifyLifecycle(event, onDrift);
+        case "attachment":
+            return classifyLifecycle(event, onDrift);
+        case "queue-operation":
+            return classifyLifecycle(event, onDrift);
+        case "last-prompt":
+            return classifyLifecycle(event, onDrift);
+        case "ai-title":
+            return classifyLifecycle(event, onDrift);
+        case "pr-link":
+            return classifyLifecycle(event, onDrift);
+        case "agent-name":
+            return classifyLifecycle(event, onDrift);
+        case "summary":
+            return classifyLifecycle(event, onDrift);
+        // --- DEFAULT (drift) ----------------------------------------------------------------------
+        // An UNRECOGNISED type: a type added in a future `claude` 2.1.x. Emit ONE `unknown-type` drift
+        // record (naming the new type + any unrecognised top-level fields + version), then return a
+        // `drift` classification WITHOUT throwing. A drift contributes nothing downstream — it is neither
+        // content nor lifecycle, so the §7 translators never see it and NO ACP SessionUpdate is produced.
+        default:
+            onDrift({
+                kind: "unknown-type",
+                type: event.type,
+                fields: unrecognisedFields(event),
+                version: event.version,
+                event,
+            });
+            return { class: "drift", type: event.type, event };
+    }
+}

package/dist/gate/port.d.ts

@@ -0,0 +1,38 @@
+/** Bounded retry budget — re-select this many times before failing loudly (R1.4). */
+export declare const DEFAULT_PORT_ATTEMPTS = 10;
+/** Loopback host the gate hook server binds; the hook URL is `http://127.0.0.1:<port>` (story 007). */
+export declare const LOOPBACK_HOST = "127.0.0.1";
+/**
+ * Minimal `net`-server surface {@link findFreePort} needs. Factored out as an injectable seam (the
+ * same discipline as `AgentDeps.schedule` / `GuardHooks`) so a test can drive bind exhaustion
+ * deterministically WITHOUT monkey-patching the frozen `node:net` module namespace (which is
+ * read-only under ESM). Defaults to `node:net`'s real `createServer`.
+ */
+export interface PortServer {
+    listen(port: number, host: string): void;
+    close(cb?: () => void): void;
+    address(): {
+        port: number;
+    } | string | null;
+    once(event: "listening" | "error", cb: (...args: unknown[]) => void): void;
+    removeListener(event: "listening" | "error", cb: (...args: unknown[]) => void): void;
+}
+/** Factory for a fresh, unbound {@link PortServer}. Injected for tests; defaults to `node:net`. */
+export type ServerFactory = () => PortServer;
+/**
+ * Allocate an OS-assigned ephemeral port and PROVE it is actually free by binding `127.0.0.1:<port>`
+ * before returning it (global port-in-use rule; R1.1, R1.2). On a bind conflict
+ * (`EADDRINUSE`/`EACCES`) the candidate is discarded and another is selected (R1.3). After
+ * {@link DEFAULT_PORT_ATTEMPTS} exhausted attempts the promise REJECTS with a diagnostic naming the
+ * attempt count and the last bind error rather than returning an unverified port (R1.4).
+ *
+ * @param attempts bounded retry budget (default {@link DEFAULT_PORT_ATTEMPTS}); each attempt
+ *   OS-assigns a fresh candidate and re-verifies it binds free.
+ * @param makeServer injectable `net`-server factory (defaults to `node:net`'s `createServer`);
+ *   tests drive bind exhaustion through it without monkey-patching the frozen module.
+ * @returns a port number, in the ephemeral range, that bound free on `127.0.0.1` at adoption time.
+ * @throws {Error} if no candidate binds free within `attempts` tries — message names the count and
+ *   the last bind error.
+ */
+export declare function findFreePort(attempts?: number, makeServer?: ServerFactory): Promise<number>;
+//# sourceMappingURL=port.d.ts.map

package/dist/gate/port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"port.d.ts","sourceRoot":"","sources":["../../src/gate/port.ts"],"names":[],"mappings":"AAsBA,qFAAqF;AACrF,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAExC,uGAAuG;AACvG,eAAO,MAAM,aAAa,cAAc,CAAC;AAEzC;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,KAAK,CAAC,EAAE,CAAC,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAC7B,OAAO,IAAI;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,GAAG,IAAI,CAAC;IAC5C,IAAI,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,EAAE,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,IAAI,CAAC;IAC3E,cAAc,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,EAAE,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,IAAI,CAAC;CACtF;AAED,mGAAmG;AACnG,MAAM,MAAM,aAAa,GAAG,MAAM,UAAU,CAAC;AA4C7C;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,YAAY,CAChC,QAAQ,GAAE,MAA8B,EACxC,UAAU,GAAE,aAAoC,GAC/C,OAAO,CAAC,MAAM,CAAC,CAkDjB"}

package/dist/gate/port.js

@@ -0,0 +1,126 @@
+// Story 032 / Task 1.1 — dynamic free-port allocator with 127.0.0.1 bind verification (R1).
+//
+// The Degrau-2 permission gate (HYBRID prototype, story 007 / GATE_FINDINGS.md) attaches a
+// `PreToolUse` type:http hook to the real `claude` TUI over **TCP loopback**. That hook needs an
+// endpoint port for the fork's local hook server. Per the global project rule on port-in-use, the
+// port MUST be:
+//   - allocated DYNAMICALLY (OS-assigned / ephemeral) — NEVER a hard-coded constant; and
+//   - PROVEN free by actually binding `127.0.0.1:<port>` before it is adopted (a stale "looks free"
+//     check is not enough — a service could be on the box).
+//
+// STRATEGY (TOCTOU-aware): we OS-assign a candidate by listening on `127.0.0.1:0` (the kernel hands
+// back a currently-free ephemeral port), read it, close that probe, then RE-BIND `127.0.0.1:<port>`
+// to confirm it is still free at adoption time. A small race window remains between the two binds —
+// that is inherent to any "pick then use" scheme — but if the re-bind races a `EADDRINUSE`/`EACCES`
+// we simply re-select another candidate rather than returning an unverified port. After a bounded
+// retry budget we REJECT loudly with the attempt count and the last bind error (R1.4) so the spawn
+// path fails fast instead of hanging on an endless retry loop.
+//
+// OFFLINE: this module binds/closes loopback sockets only; it spawns NO `claude` and bills nothing.
+import { createServer } from "node:net";
+/** Bounded retry budget — re-select this many times before failing loudly (R1.4). */
+export const DEFAULT_PORT_ATTEMPTS = 10;
+/** Loopback host the gate hook server binds; the hook URL is `http://127.0.0.1:<port>` (story 007). */
+export const LOOPBACK_HOST = "127.0.0.1";
+const defaultServerFactory = () => createServer();
+/**
+ * Listen on `host:port` and resolve once bound, or reject on the bind error. The caller decides
+ * whether to keep the server open (to read its assigned port) or close it. Every error path removes
+ * the `listening` handler implicitly via the one-shot promise, and the server is the caller's to
+ * close — `listenOnce` itself never leaks a half-open socket because a failed `listen` does not bind.
+ */
+function listenOnce(makeServer, host, port) {
+    return new Promise((resolve, reject) => {
+        const server = makeServer();
+        const onError = (...args) => {
+            server.removeListener("listening", onListening);
+            // A server that failed to listen holds no bound socket; close defensively and surface the error.
+            try {
+                server.close();
+            }
+            catch {
+                // ignore — nothing was bound
+            }
+            reject(args[0] ?? new Error("listen failed"));
+        };
+        const onListening = () => {
+            server.removeListener("error", onError);
+            resolve(server);
+        };
+        server.once("error", onError);
+        server.once("listening", onListening);
+        server.listen(port, host);
+    });
+}
+/** Close a probe server, swallowing any close error (a probe must never leak a socket — R1 note). */
+function closeQuietly(server) {
+    return new Promise((resolve) => {
+        try {
+            server.close(() => resolve());
+        }
+        catch {
+            resolve();
+        }
+    });
+}
+/**
+ * Allocate an OS-assigned ephemeral port and PROVE it is actually free by binding `127.0.0.1:<port>`
+ * before returning it (global port-in-use rule; R1.1, R1.2). On a bind conflict
+ * (`EADDRINUSE`/`EACCES`) the candidate is discarded and another is selected (R1.3). After
+ * {@link DEFAULT_PORT_ATTEMPTS} exhausted attempts the promise REJECTS with a diagnostic naming the
+ * attempt count and the last bind error rather than returning an unverified port (R1.4).
+ *
+ * @param attempts bounded retry budget (default {@link DEFAULT_PORT_ATTEMPTS}); each attempt
+ *   OS-assigns a fresh candidate and re-verifies it binds free.
+ * @param makeServer injectable `net`-server factory (defaults to `node:net`'s `createServer`);
+ *   tests drive bind exhaustion through it without monkey-patching the frozen module.
+ * @returns a port number, in the ephemeral range, that bound free on `127.0.0.1` at adoption time.
+ * @throws {Error} if no candidate binds free within `attempts` tries — message names the count and
+ *   the last bind error.
+ */
+export async function findFreePort(attempts = DEFAULT_PORT_ATTEMPTS, makeServer = defaultServerFactory) {
+    if (!Number.isInteger(attempts) || attempts < 1) {
+        throw new Error(`findFreePort: attempts must be a positive integer, got ${String(attempts)}`);
+    }
+    let lastError = null;
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+        // 1) OS-assign a currently-free ephemeral port by listening on :0.
+        let candidate;
+        let probe;
+        try {
+            probe = await listenOnce(makeServer, LOOPBACK_HOST, 0);
+        }
+        catch (err) {
+            lastError = err;
+            continue;
+        }
+        const address = probe.address();
+        if (address === null || typeof address === "string") {
+            // Unexpected (a TCP server should yield an AddressInfo); discard and retry.
+            lastError = new Error("findFreePort: OS-assigned listener returned no numeric port");
+            await closeQuietly(probe);
+            continue;
+        }
+        candidate = address.port;
+        await closeQuietly(probe);
+        // 2) Re-bind the SAME port to PROVE it is still free at adoption time (verification bind).
+        let verify;
+        try {
+            verify = await listenOnce(makeServer, LOOPBACK_HOST, candidate);
+        }
+        catch (err) {
+            // EADDRINUSE / EACCES — the port got taken (or is privileged); re-select another candidate.
+            lastError = err;
+            continue;
+        }
+        await closeQuietly(verify);
+        return candidate;
+    }
+    const detail = lastError instanceof Error
+        ? `${lastError.message}`
+        : lastError === null
+            ? "no candidate could be OS-assigned"
+            : String(lastError);
+    throw new Error(`findFreePort: could not obtain a verified-free 127.0.0.1 port after ${attempts} attempt(s); ` +
+        `last bind error: ${detail}. Refusing to return an unverified port (global port-in-use rule).`);
+}

package/dist/gate/settings-writer.d.ts

@@ -0,0 +1,130 @@
+/** Fixed fork-owned sentinel path segment embedded in the hook URL — the surgical-removal marker. */
+export declare const FORK_HOOK_MARKER_PATH = "/__fork-acp-gate__";
+/** Key stamped on the fork's matcher group for human-readability; the URL path is authoritative. */
+export declare const FORK_HOOK_MARKER_KEY = "__forkAcpGate";
+/** Default hook timeout in SECONDS (claude default is 600); kept a parameter so nothing is magic. */
+export declare const DEFAULT_HOOK_TIMEOUT_SECONDS = 600;
+/** Tool matcher for the gate hook; `"*"` matches all tools (the shape the story-007 probe fired). */
+export declare const FORK_HOOK_MATCHER = "*";
+/** A single http-hook entry as it appears inside a matcher group's `hooks` array (story-007 shape). */
+export interface HttpHookEntry {
+    type: "http";
+    url: string;
+    timeout: number;
+}
+/** The `{ matcher, hooks:[…] }` group as it appears under `PreToolUse`, plus the fork sentinel key. */
+export interface PreToolUseGroup {
+    matcher: string;
+    hooks: HttpHookEntry[];
+    /** Present (and `true`) only on the FORK's own group — never on a user's group. */
+    [FORK_HOOK_MARKER_KEY]?: true;
+}
+/**
+ * Build the fork's `PreToolUse` `type:http` hook group, pointing at the 127.0.0.1 TCP-loopback
+ * endpoint for the dynamically allocated free port (R1 / R2.3). The URL carries the fork-owned
+ * sentinel path ({@link FORK_HOOK_MARKER_PATH}) so teardown can surgically remove ONLY this group.
+ *
+ * @param port the verified-free port from {@link import("./port.js").findFreePort} — a positive integer.
+ * @param timeout hook timeout in SECONDS (default {@link DEFAULT_HOOK_TIMEOUT_SECONDS}).
+ * @returns the `{ matcher, hooks:[{type:"http",…}], __forkAcpGate:true }` group.
+ * @throws {Error} if `port` is not a positive integer (a bad port would produce a malformed/ungated
+ *   hook — fail loud rather than silently emit a hook claude ignores).
+ */
+export declare function buildHookEntry(port: number, timeout?: number): PreToolUseGroup;
+/** True iff `group` is the FORK's own injected hook group (sentinel key OR sentinel URL path). */
+export declare function isForkHookGroup(group: unknown): boolean;
+/** Minimal structural view of a settings document's hooks block (only what the merge touches). */
+export interface SettingsLike {
+    hooks?: {
+        PreToolUse?: unknown[];
+        [event: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+/**
+ * Merge the fork hook `group` into an existing-or-absent settings object, preserving EVERY
+ * pre-existing key/value AND the user's own hooks (R2.1, R2.2, R2.4). Never mutates `prior`.
+ *
+ *   - `prior` null/absent  → return a minimal object containing ONLY the fork hook (R2.2).
+ *   - `prior` present      → deep-clone it, then APPEND the fork group to `hooks.PreToolUse`
+ *                            without dropping/overwriting any existing entry (R2.4). An existing
+ *                            fork group (idempotent re-inject) is replaced in place, not duplicated.
+ *
+ * @param prior the parsed prior settings object, or `null` if the file was absent.
+ * @param group the fork hook group from {@link buildHookEntry}.
+ * @returns a NEW settings object — a superset of `prior` differing only by the added fork hook.
+ * @throws {Error} if `prior` is a non-object (array/scalar) — a corrupt root is surfaced loudly, not
+ *   silently overwritten (R2.1: a corrupt user file is never clobbered blindly).
+ */
+export declare function mergeHook(prior: SettingsLike | null, group: PreToolUseGroup): SettingsLike;
+/**
+ * Parse settings text tolerantly (JSONC — a user may have hand-edited comments/trailing commas) into
+ * a {@link SettingsLike} object. Reuses zed-register's `parseJsonc`. A parse failure is surfaced as a
+ * clear error (NOT silently swallowed) so a corrupt user file is never clobbered blindly (R2.1).
+ *
+ * @param text the raw on-disk file contents.
+ * @returns the parsed object.
+ * @throws {Error} wrapping the underlying parse error with a clear, attributable message.
+ */
+export declare function parsePriorSettings(text: string): SettingsLike;
+/**
+ * Captured prior on-disk state of `settings.local.json`, returned by {@link injectHook} and consumed
+ * by {@link restore}. Either the exact prior file bytes (`existed:true`) or a record of absence
+ * (`existed:false`) — enough to leave the user's config byte-equivalent on teardown (R4.1).
+ */
+export interface Backup {
+    /** Absolute path of the settings file this backup covers. */
+    settingsPath: string;
+    /** Whether the file existed on disk before inject. */
+    existed: boolean;
+    /** The exact prior file bytes (only when `existed` is true). */
+    priorBytes: Buffer | null;
+}
+/** Result of {@link restore}: which removal path ran (`'surgical'` preferred, `'backup'` fallback). */
+export interface RestoreResult {
+    path: "surgical" | "backup";
+}
+/**
+ * Capture the prior on-disk state, compute the merged settings, and DURABLY write
+ * `settings.local.json` BEFORE the claude PTY is spawned (R3.1, R3.2, R4.1).
+ *
+ * CALLER CONTRACT (BLOCKER c — setup ordering): the spawn path MUST `await injectHook(...)` BEFORE it
+ * spawns the `claude` PTY, because `claude` reads hook config only at startup; a write that lands
+ * after spawn misses the first tool call. The engine-wiring that enforces this ordering is a separate
+ * Degrau-2 story (out of scope here — this module is the standalone seam).
+ * TODO(degrau-2 engine wiring): call `await injectHook(...)` in createSession BEFORE spawnPty, and
+ * `await restore(backup)` on session teardown. Tracked by the Degrau-2 engine-integration story.
+ *
+ * @param opts.settingsPath absolute path to the `settings.local.json` to mutate.
+ * @param opts.port the verified-free port from {@link import("./port.js").findFreePort} (R1).
+ * @param opts.timeout optional hook timeout in SECONDS (default {@link DEFAULT_HOOK_TIMEOUT_SECONDS}).
+ * @returns a {@link Backup} handle carrying the exact prior bytes (or absence) for {@link restore}.
+ * @throws {Error} if the prior file is unreadable for a reason other than absence, or if the merged
+ *   config cannot be written — on a write failure the prior bytes are restored (or the partial temp
+ *   deleted) before rejecting, so a failed inject never leaves a file claude could read half-written.
+ */
+export declare function injectHook(opts: {
+    settingsPath: string;
+    port: number;
+    timeout?: number;
+}): Promise<Backup>;
+/**
+ * Teardown: remove the fork's injected hook, leaving ZERO residue (R4.2, R4.3).
+ *
+ * Preferred path (`'surgical'`): re-read the current on-disk file; if it parses, delete ONLY the
+ * group bearing the fork-owned marker ({@link isForkHookGroup}) and re-write the rest — preserving
+ * any edits the user made AFTER inject. If removing the fork group empties `hooks.PreToolUse`/`hooks`,
+ * and the backup recorded absence (the fork created the file), the file is deleted so no empty husk
+ * is left behind.
+ *
+ * Fallback path (`'backup'`): if the current file is unparseable, or surgical isolation of the fork
+ * entry is not possible, restore the captured prior state — delete the file if it did not previously
+ * exist, else rewrite the exact prior bytes.
+ *
+ * @param backup the handle returned by {@link injectHook}.
+ * @returns which path ran, so the caller can log it (R4.3).
+ * @throws {Error} only if BOTH the surgical path AND the backup fallback fail — the message names the
+ *   underlying error so teardown never silently strands the fork hook.
+ */
+export declare function restore(backup: Backup): Promise<RestoreResult>;
+//# sourceMappingURL=settings-writer.d.ts.map

package/dist/gate/settings-writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-writer.d.ts","sourceRoot":"","sources":["../../src/gate/settings-writer.ts"],"names":[],"mappings":"AA6BA,qGAAqG;AACrG,eAAO,MAAM,qBAAqB,uBAAuB,CAAC;AAE1D,oGAAoG;AACpG,eAAO,MAAM,oBAAoB,kBAAkB,CAAC;AAEpD,qGAAqG;AACrG,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAEhD,qGAAqG;AACrG,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAErC,uGAAuG;AACvG,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,uGAAuG;AACvG,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,mFAAmF;IACnF,CAAC,oBAAoB,CAAC,CAAC,EAAE,IAAI,CAAC;CAC/B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,MAAqC,GAAG,eAAe,CAkB5G;AAED,kGAAkG;AAClG,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAuBvD;AAED,kGAAkG;AAClG,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,EAAE;QACN,UAAU,CAAC,EAAE,OAAO,EAAE,CAAC;QACvB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;KAC1B,CAAC;IACF,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,EAAE,KAAK,EAAE,eAAe,GAAG,YAAY,CAsB1F;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAc7D;AAYD;;;;GAIG;AACH,MAAM,WAAW,MAAM;IACrB,6DAA6D;IAC7D,YAAY,EAAE,MAAM,CAAC;IACrB,sDAAsD;IACtD,OAAO,EAAE,OAAO,CAAC;IACjB,gEAAgE;IAChE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,uGAAuG;AACvG,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,UAAU,GAAG,QAAQ,CAAC;CAC7B;AA2DD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE;IACrC,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,OAAO,CAAC,MAAM,CAAC,CAuClB;AAWD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAgEpE"}