@parall/codex-agent 1.44.0 → 1.46.0

package/dist/jsonrpc-client.js

@@ -1,3 +1,21 @@
+/** JSON-RPC 2.0 spec code for "Method not found". */
+export const JSON_RPC_METHOD_NOT_FOUND = -32601;
+/**
+ * Rejection error that preserves the JSON-RPC error object's code (and data),
+ * so callers can branch on protocol-level conditions — e.g. method-not-found
+ * on an older CLI — without matching on server message text, whose wording
+ * shifts between codex versions.
+ */
+export class JsonRpcError extends Error {
+    code;
+    data;
+    constructor(code, message, data) {
+        super(message || 'JSON-RPC error');
+        this.code = code;
+        this.data = data;
+        this.name = 'JsonRpcError';
+    }
+}
 /** Maximum time to wait for a JSON-RPC response before rejecting. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 120_000;
 /**
@@ -16,6 +34,7 @@ export class JsonRpcStdioClient {
     pending = new Map();
     buffer = '';
     onNotification = null;
+    onServerRequest = null;
     disposed = false;
     constructor(proc, requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS, killProcess) {
         this.proc = proc;
@@ -30,10 +49,23 @@ export class JsonRpcStdioClient {
     setNotificationHandler(handler) {
         this.onNotification = handler;
     }
-    sendRequest(method, params) {
+    setServerRequestHandler(handler) {
+        this.onServerRequest = handler;
+    }
+    /**
+     * `options.timeoutMs` overrides the client-wide budget for this request.
+     * `options.lethalTimeout: false` makes a timeout reject WITHOUT killing the
+     * subprocess — for best-effort side requests (e.g. the compaction watcher's
+     * turn/interrupt) where "no answer" must not translate into a delayed
+     * subprocess kill landing on an unrelated later dispatch. Default (true)
+     * keeps the existing assume-hung semantics.
+     */
+    sendRequest(method, params, options) {
         if (this.disposed) {
             return Promise.reject(new Error('JSON-RPC client disposed'));
         }
+        const timeoutMs = options?.timeoutMs ?? this.requestTimeoutMs;
+        const lethalTimeout = options?.lethalTimeout ?? true;
         const id = this.nextId++;
         const request = { jsonrpc: '2.0', id, method, params };
         const promise = new Promise((resolve, reject) => {
@@ -42,9 +74,11 @@ export class JsonRpcStdioClient {
                 if (!pending)
                     return;
                 this.pending.delete(id);
-                reject(new Error(`JSON-RPC request "${method}" timed out after ${this.requestTimeoutMs}ms`));
-                this.killUnhealthy(new Error(`request "${method}" timed out; subprocess assumed hung`));
-            }, this.requestTimeoutMs);
+                reject(new Error(`JSON-RPC request "${method}" timed out after ${timeoutMs}ms`));
+                if (lethalTimeout) {
+                    this.killUnhealthy(new Error(`request "${method}" timed out; subprocess assumed hung`));
+                }
+            }, timeoutMs);
             this.pending.set(id, { resolve, reject, timer });
         });
         this.writeFrame(request);
@@ -114,21 +148,59 @@ export class JsonRpcStdioClient {
             this.pending.delete(message.id);
             clearTimeout(pending.timer);
             if (message.error) {
-                pending.reject(new Error(message.error.message || 'JSON-RPC error'));
+                pending.reject(new JsonRpcError(message.error.code, message.error.message, message.error.data));
             }
             else {
                 pending.resolve(message.result);
             }
             return;
         }
+        if (isServerRequest(message)) {
+            this.answerServerRequest(message);
+            return;
+        }
         if (isNotification(message)) {
             this.onNotification?.(message.method, message.params);
         }
     }
+    answerServerRequest(request) {
+        let answer;
+        try {
+            answer = this.onServerRequest?.(request.method, request.params);
+        }
+        catch (err) {
+            this.writeFrame({
+                jsonrpc: '2.0',
+                id: request.id,
+                error: { code: -32603, message: `server request handler failed: ${String(err)}` },
+            });
+            return;
+        }
+        if (answer !== undefined) {
+            // undefined → null: a dropped `result` member would produce a frame
+            // that is neither a success nor an error response.
+            this.writeFrame({
+                jsonrpc: '2.0',
+                id: request.id,
+                result: answer.result === undefined ? null : answer.result,
+            });
+            return;
+        }
+        this.writeFrame({
+            jsonrpc: '2.0',
+            id: request.id,
+            error: { code: -32601, message: `unsupported server request: ${request.method}` },
+        });
+    }
 }
 function isResponse(m) {
     return !!m && typeof m === 'object' && 'id' in m && ('result' in m || 'error' in m);
 }
+// A server→client request carries BOTH `method` and `id` (and no
+// result/error). It must be answered — see ServerRequestHandler.
+function isServerRequest(m) {
+    return !!m && typeof m === 'object' && 'method' in m && 'id' in m;
+}
 function isNotification(m) {
     return !!m && typeof m === 'object' && 'method' in m && !('id' in m);
 }

package/dist/legacy-workspace-config-migration.d.ts

@@ -0,0 +1,112 @@
+export declare function legacyWorkspaceConfigPath(workspaceDir: string): string;
+export declare function migrationSentinelPath(workspaceDir: string): string;
+/**
+ * Byte-exact reconstruction of the retired serializer. Verified identical across
+ * every released bridge that wrote this file (v1.37.0 … v1.44.0 — the line is
+ * byte-for-byte the same in all of them), so a single reconstruction covers the
+ * whole legacy fleet. The deletion gate compares raw bytes against this: it must
+ * never drift.
+ */
+export declare function legacyWorkspaceConfigToml(prompt: string): string;
+/**
+ * The PRE-OVERWRITE `.parall/system-prompt.md`. The retired bridge wrote the
+ * reference copy and the config from the SAME string in the same call, so a byte
+ * match against `legacyWorkspaceConfigToml(prompt)` is what identifies our own
+ * artifact.
+ *
+ * `absent` (ENOENT — the bridge never bootstrapped this workspace) and
+ * `unreadable` (it is there, but an I/O error hid it) both mean "cannot prove
+ * ownership, so do not delete" — but they are different facts, and reporting the
+ * second as the first tells the operator the wrong reason for a preserved file.
+ */
+export type AuthorshipProof = {
+    kind: 'present';
+    prompt: string;
+} | {
+    kind: 'absent';
+} | {
+    kind: 'unreadable';
+};
+/**
+ * What the filesystem says about the legacy config. Gathered by the executor;
+ * the classifier below sees nothing else — no fs, no clock, no env.
+ */
+export type LegacyConfigFacts = {
+    /** lstat of the legacy path — never a stat: a symlink must not be followed. `null` = ENOENT. */
+    entry: {
+        isPlainFile: boolean;
+        hardLinks: number;
+    } | null;
+    /** Raw bytes of the legacy file. `null` = not a plain file, or unreadable. */
+    rawContent: string | null;
+    proof: AuthorshipProof;
+};
+export type LegacyConfigVerdict = {
+    action: 'none';
+} | {
+    action: 'remove';
+} | {
+    action: 'preserve';
+    reason: PreserveReason;
+};
+export type PreserveReason = 
+/** Symlink (a dotfiles arrangement) or a directory — unlink-by-path would sever the operator's link. */
+'not-a-plain-file'
+/** Extra hard links: the same inode is reachable from a path we know nothing about. */
+ | 'extra-hard-links'
+/** No `.parall/system-prompt.md` from a previous boot — no proof can exist. */
+ | 'no-authorship-proof'
+/** The proof copy exists but could not be read, so ownership cannot be evaluated. */
+ | 'authorship-proof-unreadable'
+/** Could not read the legacy config's own bytes, so the proof cannot be applied. */
+ | 'config-unreadable'
+/** Bytes differ from what the retired bridge would have written (operator-authored, comments, hand-edited). */
+ | 'content-mismatch';
+/**
+ * Pure. Decides the fate of the legacy config from filesystem facts alone.
+ *
+ * The only path to `remove` is: plain regular file + exactly one hard link + a
+ * pre-overwrite reference copy exists + raw bytes are EXACTLY the retired
+ * serializer's output for that reference prompt. Every other combination
+ * preserves — including value-level near-misses (an operator file carrying the
+ * same `developer_instructions` value plus a comment would be destroyed together
+ * with the comment by a value-level compare).
+ */
+export declare function classifyLegacyWorkspaceConfig(facts: LegacyConfigFacts): LegacyConfigVerdict;
+export type MigrationClaim = 'claimed' | 'already-claimed';
+/**
+ * Atomically take the one-way claim. `wx` makes this a single filesystem
+ * operation, so concurrent boots cannot both win.
+ *
+ * THROWS if the claim cannot be persisted (EACCES, EIO, EROFS …). That is
+ * deliberate and load-bearing: the caller runs this BEFORE overwriting
+ * `.parall/system-prompt.md`, so a boot that cannot record its claim must die
+ * with the legacy evidence still intact rather than proceed to manufacture a
+ * prompt that a later boot would mistake for that evidence.
+ */
+export declare function claimLegacyWorkspaceConfigMigration(workspaceDir: string): MigrationClaim;
+/**
+ * The migration lifecycle: claim, then — only if we won the claim — read the
+ * proof and clean up.
+ *
+ * `readProof` is a THUNK, not a value, and that is the whole point. Reading the
+ * proof is not free of side effects: an unreadable `.parall/system-prompt.md`
+ * warns. Passed as an already-evaluated argument, that warning fires before the
+ * claim is even checked — so an already-claimed later boot, or a concurrent
+ * loser, would emit a migration warning about a decision it is not making. The
+ * thunk makes "only the winner touches the proof" a property of the type rather
+ * than of the caller's evaluation order.
+ *
+ * The caller still owns `.parall/system-prompt.md` and must hand over the
+ * PRE-OVERWRITE copy: the winner evaluates the thunk here, before anything
+ * writes a new prompt.
+ *
+ * A boot that does not win the claim returns silently — it must not delete, it
+ * must not read, and it must not warn: the winner may be deleting the very file
+ * it would warn about, and a stale warning about a file that is already gone is
+ * exactly the misleading diagnostic this module exists to avoid.
+ */
+export declare function runLegacyWorkspaceConfigMigration(workspaceDir: string, readProof: () => AuthorshipProof, log?: {
+    warn: (msg: string) => void;
+}): void;
+//# sourceMappingURL=legacy-workspace-config-migration.d.ts.map

package/dist/legacy-workspace-config-migration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"legacy-workspace-config-migration.d.ts","sourceRoot":"","sources":["../src/legacy-workspace-config-migration.ts"],"names":[],"mappings":"AAqDA,wBAAgB,yBAAyB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAElE;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,eAAe,GACvB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,CAAC;AAE3B;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,gGAAgG;IAChG,KAAK,EAAE;QAAE,WAAW,EAAE,OAAO,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC1D,8EAA8E;IAC9E,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,KAAK,EAAE,eAAe,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAC3B;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAClB;IAAE,MAAM,EAAE,QAAQ,CAAA;CAAE,GACpB;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,cAAc,CAAA;CAAE,CAAC;AAEnD,MAAM,MAAM,cAAc;AACxB,wGAAwG;AACtG,kBAAkB;AACpB,uFAAuF;GACrF,kBAAkB;AACpB,+EAA+E;GAC7E,qBAAqB;AACvB,qFAAqF;GACnF,6BAA6B;AAC/B,oFAAoF;GAClF,mBAAmB;AACrB,+GAA+G;GAC7G,kBAAkB,CAAC;AAEvB;;;;;;;;;GASG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,iBAAiB,GAAG,mBAAmB,CAc3F;AA6BD,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,iBAAiB,CAAC;AAE3D;;;;;;;;;GASG;AACH,wBAAgB,mCAAmC,CAAC,YAAY,EAAE,MAAM,GAAG,cAAc,CAYxF;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iCAAiC,CAC/C,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,eAAe,EAChC,GAAG,CAAC,EAAE;IAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GACpC,IAAI,CAGN"}

package/dist/legacy-workspace-config-migration.js

@@ -0,0 +1,229 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+/**
+ * One-shot migration for workspaces last bootstrapped by a pre-protocol-delivery
+ * bridge.
+ *
+ * Those generations (every released bridge up to and including v1.44.0) injected
+ * the system prompt by writing `<workspace>/.codex/config.toml`
+ * (`developer_instructions`) and marking the workspace trusted in the operator's
+ * global codex config. Instructions now ride the app-server's per-thread
+ * `developerInstructions` param, so a leftover bridge-authored file would DOUBLE
+ * the instructions on any workspace codex still considers trusted.
+ *
+ * Deleting a file in someone's workspace is the destructive direction, so the
+ * gate is fail-closed: we remove ONLY what is provably the retired bridge's own
+ * artifact, and preserve (with a warning) everything else. A duplicated prompt
+ * is a degraded agent; a deleted operator file is lost work.
+ *
+ * WHY THIS IS ONE-SHOT AND NOT MERELY IDEMPOTENT. The authorship proof is
+ * `.parall/system-prompt.md`, and the bridge REWRITES that file on every boot.
+ * So it is legacy-era evidence exactly once: on the first protocol-delivery boot,
+ * before anything overwrites it. A gate that merely re-ran each boot would, from
+ * boot 2 on, be comparing the legacy config against a prompt THIS bridge wrote —
+ * evidence it manufactured itself. That is not hypothetical: prompt assembly is
+ * deterministic, so a file the first boot explicitly preserved as "not provably
+ * ours" can match on the next boot and be silently deleted, contradicting the
+ * warning the operator was just given. Fail-closed has to hold across the whole
+ * migration lifecycle, not per function call.
+ *
+ * Hence a versioned, one-way CLAIM (`.parall/legacy-workspace-config-migration.v1`),
+ * created atomically (`wx`) BEFORE any prompt write:
+ *   - exactly one boot ever wins the claim — it alone may delete;
+ *   - every later boot (and every concurrent loser) skips, silently, forever;
+ *   - a claim that cannot be persisted FAILS the boot before the proof is
+ *     overwritten, so a retry still has real evidence;
+ *   - a boot that dies mid-migration leaves the claim behind, so the file is
+ *     preserved forever rather than re-judged against fabricated evidence.
+ *
+ * The whole module is dead code once no workspace can still hold a pre-#1866
+ * artifact — sunset conditions in
+ * docs/tech-debt/codex-legacy-workspace-config-shim.md.
+ */
+/** Relative location of the retired bridge's workspace config. */
+const LEGACY_CONFIG_RELPATH = ['.codex', 'config.toml'];
+/**
+ * The one-way claim. Versioned: a future migration gets its own sentinel rather
+ * than reusing (or re-arming) this one.
+ */
+const MIGRATION_SENTINEL_RELPATH = ['.parall', 'legacy-workspace-config-migration.v1'];
+export function legacyWorkspaceConfigPath(workspaceDir) {
+    return path.join(workspaceDir, ...LEGACY_CONFIG_RELPATH);
+}
+export function migrationSentinelPath(workspaceDir) {
+    return path.join(workspaceDir, ...MIGRATION_SENTINEL_RELPATH);
+}
+/**
+ * Byte-exact reconstruction of the retired serializer. Verified identical across
+ * every released bridge that wrote this file (v1.37.0 … v1.44.0 — the line is
+ * byte-for-byte the same in all of them), so a single reconstruction covers the
+ * whole legacy fleet. The deletion gate compares raw bytes against this: it must
+ * never drift.
+ */
+export function legacyWorkspaceConfigToml(prompt) {
+    return `developer_instructions = """\n${prompt.replace(/\\/g, '\\\\').replace(/"""/g, '\\"""')}\n"""\n`;
+}
+/**
+ * Pure. Decides the fate of the legacy config from filesystem facts alone.
+ *
+ * The only path to `remove` is: plain regular file + exactly one hard link + a
+ * pre-overwrite reference copy exists + raw bytes are EXACTLY the retired
+ * serializer's output for that reference prompt. Every other combination
+ * preserves — including value-level near-misses (an operator file carrying the
+ * same `developer_instructions` value plus a comment would be destroyed together
+ * with the comment by a value-level compare).
+ */
+export function classifyLegacyWorkspaceConfig(facts) {
+    const { entry, rawContent, proof } = facts;
+    if (!entry)
+        return { action: 'none' };
+    if (!entry.isPlainFile)
+        return { action: 'preserve', reason: 'not-a-plain-file' };
+    if (entry.hardLinks !== 1)
+        return { action: 'preserve', reason: 'extra-hard-links' };
+    if (proof.kind === 'absent')
+        return { action: 'preserve', reason: 'no-authorship-proof' };
+    if (proof.kind === 'unreadable') {
+        return { action: 'preserve', reason: 'authorship-proof-unreadable' };
+    }
+    if (rawContent === null)
+        return { action: 'preserve', reason: 'config-unreadable' };
+    if (rawContent !== legacyWorkspaceConfigToml(proof.prompt)) {
+        return { action: 'preserve', reason: 'content-mismatch' };
+    }
+    return { action: 'remove' };
+}
+const PRESERVE_DETAIL = {
+    'not-a-plain-file': 'it is a symlink or directory, not a plain file the bridge could have written',
+    'extra-hard-links': 'the file has more than one hard link, so another path shares this inode',
+    'no-authorship-proof': 'this workspace has no .parall/system-prompt.md from a previous boot, so nothing here can be proven ours',
+    'authorship-proof-unreadable': 'the .parall/system-prompt.md authorship proof exists but could not be read, so ownership cannot be evaluated',
+    'config-unreadable': 'its own bytes could not be read, so authorship cannot be proven',
+    'content-mismatch': 'its bytes are not what the retired bridge would have written',
+};
+const SENTINEL_BODY = `Parall codex bridge — one-shot workspace migration record (v1)
+
+The legacy workspace-config cleanup has been CLAIMED for this workspace. Only the
+boot that created this file was allowed to remove a bridge-authored
+.codex/config.toml, and only under a byte-exact authorship proof.
+
+While this file exists the bridge will NEVER auto-remove .codex/config.toml again.
+Deleting this file does not safely re-arm the migration: the evidence it relied on
+(.parall/system-prompt.md as written by a pre-protocol-delivery bridge) has since
+been overwritten by this bridge, so a re-run could mistake a prompt it wrote itself
+for legacy evidence and delete a file that is not ours.
+
+If a stale .codex/config.toml is still present, remove it by hand.
+`;
+/**
+ * Atomically take the one-way claim. `wx` makes this a single filesystem
+ * operation, so concurrent boots cannot both win.
+ *
+ * THROWS if the claim cannot be persisted (EACCES, EIO, EROFS …). That is
+ * deliberate and load-bearing: the caller runs this BEFORE overwriting
+ * `.parall/system-prompt.md`, so a boot that cannot record its claim must die
+ * with the legacy evidence still intact rather than proceed to manufacture a
+ * prompt that a later boot would mistake for that evidence.
+ */
+export function claimLegacyWorkspaceConfigMigration(workspaceDir) {
+    const sentinel = migrationSentinelPath(workspaceDir);
+    // The module owns its own sentinel, directory included — a caller that has not
+    // created `.parall` yet must still get a real claim, not an ENOENT throw.
+    fs.mkdirSync(path.dirname(sentinel), { recursive: true });
+    try {
+        fs.writeFileSync(sentinel, SENTINEL_BODY, { flag: 'wx' });
+        return 'claimed';
+    }
+    catch (err) {
+        if (err.code === 'EEXIST')
+            return 'already-claimed';
+        throw err;
+    }
+}
+/**
+ * The migration lifecycle: claim, then — only if we won the claim — read the
+ * proof and clean up.
+ *
+ * `readProof` is a THUNK, not a value, and that is the whole point. Reading the
+ * proof is not free of side effects: an unreadable `.parall/system-prompt.md`
+ * warns. Passed as an already-evaluated argument, that warning fires before the
+ * claim is even checked — so an already-claimed later boot, or a concurrent
+ * loser, would emit a migration warning about a decision it is not making. The
+ * thunk makes "only the winner touches the proof" a property of the type rather
+ * than of the caller's evaluation order.
+ *
+ * The caller still owns `.parall/system-prompt.md` and must hand over the
+ * PRE-OVERWRITE copy: the winner evaluates the thunk here, before anything
+ * writes a new prompt.
+ *
+ * A boot that does not win the claim returns silently — it must not delete, it
+ * must not read, and it must not warn: the winner may be deleting the very file
+ * it would warn about, and a stale warning about a file that is already gone is
+ * exactly the misleading diagnostic this module exists to avoid.
+ */
+export function runLegacyWorkspaceConfigMigration(workspaceDir, readProof, log) {
+    if (claimLegacyWorkspaceConfigMigration(workspaceDir) === 'already-claimed')
+        return;
+    cleanupLegacyWorkspaceConfig(workspaceDir, readProof(), log);
+}
+/**
+ * Filesystem execution for the one boot that holds the claim. Reads the facts,
+ * asks the classifier, applies the verdict.
+ *
+ * Never throws: a workspace that cannot be migrated must still boot. Every
+ * non-ENOENT problem warns.
+ */
+function cleanupLegacyWorkspaceConfig(workspaceDir, proof, log) {
+    const configPath = legacyWorkspaceConfigPath(workspaceDir);
+    let entry;
+    try {
+        entry = fs.lstatSync(configPath);
+    }
+    catch (err) {
+        // Only ENOENT means "nothing to clean up". Anything else (EACCES, EIO, …)
+        // leaves an unverifiable file behind — surface it rather than silently
+        // treating it as absent.
+        if (err.code !== 'ENOENT') {
+            log?.warn(`could not inspect legacy workspace codex config ${configPath}: ${String(err)}`);
+        }
+        return;
+    }
+    const isPlainFile = entry.isFile();
+    let rawContent = null;
+    if (isPlainFile) {
+        try {
+            rawContent = fs.readFileSync(configPath, 'utf8');
+        }
+        catch (err) {
+            // Read failure → rawContent stays null → the classifier preserves
+            // ('config-unreadable'). Log the cause here; the verdict warning follows.
+            log?.warn(`could not read legacy workspace codex config ${configPath}: ${String(err)}`);
+        }
+    }
+    const verdict = classifyLegacyWorkspaceConfig({
+        entry: { isPlainFile, hardLinks: entry.nlink },
+        rawContent,
+        proof,
+    });
+    if (verdict.action === 'none')
+        return;
+    if (verdict.action === 'remove') {
+        try {
+            fs.unlinkSync(configPath);
+        }
+        catch (err) {
+            // ENOENT here means the file went away between our lstat and this unlink
+            // — a second bridge booting the same workspace (rapid daemon respawn) got
+            // there first. That is exactly the end state we wanted, so it is not a
+            // failure: warning "could not remove" about a file that is already gone
+            // would send the operator after nothing. Concurrent migrations converge.
+            if (err.code === 'ENOENT')
+                return;
+            log?.warn(`could not remove legacy workspace codex config ${configPath}: ${String(err)}`);
+        }
+        return;
+    }
+    log?.warn(`leaving ${configPath} in place — ${PRESERVE_DETAIL[verdict.reason]}, so it is not provably ` +
+        "the retired bridge's own artifact. Codex loads it for trusted workspaces IN ADDITION to " +
+        'the platform instructions; remove it manually if it is a stale artifact.');
+}

package/dist/server-requests.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Returns the response payload for a server request, or `undefined` when the
+ * method is not one we can meaningfully answer (the JSON-RPC client then
+ * replies -32601, which also unblocks the app-server). Own-property lookup
+ * only — a method named like an Object.prototype member (`toString`,
+ * `constructor`) must fall through to -32601, not return an inherited
+ * function that would serialize into a result-less frame.
+ */
+export declare function answerServerRequest(method: string): unknown | undefined;
+//# sourceMappingURL=server-requests.d.ts.map

package/dist/server-requests.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-requests.d.ts","sourceRoot":"","sources":["../src/server-requests.ts"],"names":[],"mappings":"AA6BA;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAEvE"}

package/dist/server-requests.js

@@ -0,0 +1,39 @@
+/**
+ * Answers for codex app-server server→client requests.
+ *
+ * The bridge runs headless with `approvalPolicy: "never"`, so approval-shaped
+ * requests should not occur — but the protocol allows the app-server to send
+ * them (e.g. a thread that fell back to `on-request`), and an unanswered
+ * request parks its turn until the dispatch deadline. Every known
+ * approval-shaped method is answered with an explicit denial; unknown methods
+ * get a method-not-found error from the JSON-RPC layer (`undefined` here).
+ *
+ * Wire shapes verified against codex-rs 0.144.1
+ * (`app-server-protocol/src/protocol/common.rs` server_request_definitions):
+ * - v2 `item/commandExecution/requestApproval` / `item/fileChange/requestApproval`
+ *   respond `{ decision }` with camelCase variants — `decline` denies but lets
+ *   the turn continue (vs `cancel`, which also interrupts the turn).
+ * - legacy v1 `execCommandApproval` / `applyPatchApproval` (SendUserTurn-era,
+ *   unused by this bridge) respond `{ decision }` with snake_case
+ *   ReviewDecision values.
+ */
+const APPROVAL_DENIALS = {
+    'item/commandExecution/requestApproval': { decision: 'decline' },
+    'item/fileChange/requestApproval': { decision: 'decline' },
+    // NOT listed: `item/permissions/requestApproval` — its response shape is a
+    // permission GRANT (no deny variant), so denial is correctly expressed by
+    // the -32601 error fallback.
+    execCommandApproval: { decision: 'denied' },
+    applyPatchApproval: { decision: 'denied' },
+};
+/**
+ * Returns the response payload for a server request, or `undefined` when the
+ * method is not one we can meaningfully answer (the JSON-RPC client then
+ * replies -32601, which also unblocks the app-server). Own-property lookup
+ * only — a method named like an Object.prototype member (`toString`,
+ * `constructor`) must fall through to -32601, not return an inherited
+ * function that would serialize into a result-less frame.
+ */
+export function answerServerRequest(method) {
+    return Object.hasOwn(APPROVAL_DENIALS, method) ? APPROVAL_DENIALS[method] : undefined;
+}

package/dist/session-manager.d.ts

@@ -13,10 +13,22 @@ export declare class CodexSessionManager {
     private readonly stateFilePath;
     private readonly logger?;
     private readonly threadIds;
+    private readonly effectiveInstructionsShas;
     constructor(mainSessionKey: string, stateFilePath: string, logger?: Logger | undefined);
     isMain(sessionKey: string): boolean;
     getThreadId(sessionKey: string): string | undefined;
     recordThreadId(sessionKey: string, threadId: string): void;
+    /**
+     * Record a freshly-STARTED thread together with the sha of the
+     * instructions baked into it — one atomic state-file write. Two separate
+     * writes (thread id, then sha) would leave a crash window whose survivor
+     * looks exactly like a pre-tracking legacy file, and the reconcile path
+     * deliberately does NOT compact legacy state — a stale thread would then
+     * be recorded as carrying instructions it never saw.
+     */
+    recordStartedThread(sessionKey: string, threadId: string, effectiveSha: string | undefined): void;
+    getEffectiveInstructionsSha(sessionKey: string): string | undefined;
+    recordEffectiveInstructionsSha(sessionKey: string, sha: string): void;
     createForkSessionKey(): ForkSessionHandle;
     cleanupFork(sessionKey: string): void;
     /** Clear the main thread id when app-server rejects it (stale / deleted). */

package/dist/session-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-manager.d.ts","sourceRoot":"","sources":["../src/session-manager.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAO5D,KAAK,MAAM,GAAG;IAAE,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AAE9C;;;;;GAKG;AACH,qBAAa,mBAAmB;IAI5B,QAAQ,CAAC,cAAc,EAAE,MAAM;IAC/B,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IAL1B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA6B;gBAG5C,cAAc,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,EACrB,MAAM,CAAC,EAAE,MAAM,YAAA;IAKlC,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAInC,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAInD,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;IAOnD,oBAAoB,IAAI,iBAAiB;IAOzC,WAAW,CAAC,UAAU,EAAE,MAAM;IAI9B,6EAA6E;IAC7E,eAAe;IAWf,OAAO,CAAC,OAAO;IAoBf,OAAO,CAAC,OAAO;CAqBhB"}
+{"version":3,"file":"session-manager.d.ts","sourceRoot":"","sources":["../src/session-manager.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAuB5D,KAAK,MAAM,GAAG;IAAE,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AAE9C;;;;;GAKG;AACH,qBAAa,mBAAmB;IAK5B,QAAQ,CAAC,cAAc,EAAE,MAAM;IAC/B,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IAN1B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA6B;IACvD,OAAO,CAAC,QAAQ,CAAC,yBAAyB,CAA6B;gBAG5D,cAAc,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,EACrB,MAAM,CAAC,EAAE,MAAM,YAAA;IAKlC,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAInC,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAInD,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;IAcnD;;;;;;;OAOG;IACH,mBAAmB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,SAAS;IAY1F,2BAA2B,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAInE,8BAA8B,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM;IAO9D,oBAAoB,IAAI,iBAAiB;IAOzC,WAAW,CAAC,UAAU,EAAE,MAAM;IAK9B,6EAA6E;IAC7E,eAAe;IAYf,OAAO,CAAC,OAAO;IA6Bf,OAAO,CAAC,OAAO;CAuBhB"}

package/dist/session-manager.js

@@ -11,6 +11,7 @@ export class CodexSessionManager {
     stateFilePath;
     logger;
     threadIds = new Map();
+    effectiveInstructionsShas = new Map();
     constructor(mainSessionKey, stateFilePath, logger) {
         this.mainSessionKey = mainSessionKey;
         this.stateFilePath = stateFilePath;
@@ -24,9 +25,45 @@ export class CodexSessionManager {
         return this.threadIds.get(sessionKey);
     }
     recordThreadId(sessionKey, threadId) {
+        // An effective-instructions sha is a fact about one specific thread.
+        // Recording a DIFFERENT thread id under the same session invalidates it;
+        // re-recording the same id (the resume path) must preserve it, or every
+        // bridge restart would trigger a redundant refresh.
+        if (this.threadIds.get(sessionKey) !== threadId) {
+            this.effectiveInstructionsShas.delete(sessionKey);
+        }
+        this.threadIds.set(sessionKey, threadId);
+        if (sessionKey === this.mainSessionKey) {
+            this.persist();
+        }
+    }
+    /**
+     * Record a freshly-STARTED thread together with the sha of the
+     * instructions baked into it — one atomic state-file write. Two separate
+     * writes (thread id, then sha) would leave a crash window whose survivor
+     * looks exactly like a pre-tracking legacy file, and the reconcile path
+     * deliberately does NOT compact legacy state — a stale thread would then
+     * be recorded as carrying instructions it never saw.
+     */
+    recordStartedThread(sessionKey, threadId, effectiveSha) {
         this.threadIds.set(sessionKey, threadId);
+        if (effectiveSha) {
+            this.effectiveInstructionsShas.set(sessionKey, effectiveSha);
+        }
+        else {
+            this.effectiveInstructionsShas.delete(sessionKey);
+        }
+        if (sessionKey === this.mainSessionKey) {
+            this.persist();
+        }
+    }
+    getEffectiveInstructionsSha(sessionKey) {
+        return this.effectiveInstructionsShas.get(sessionKey);
+    }
+    recordEffectiveInstructionsSha(sessionKey, sha) {
+        this.effectiveInstructionsShas.set(sessionKey, sha);
         if (sessionKey === this.mainSessionKey) {
-            this.persist(threadId);
+            this.persist();
         }
     }
     createForkSessionKey() {
@@ -37,10 +74,12 @@ export class CodexSessionManager {
     }
     cleanupFork(sessionKey) {
         this.threadIds.delete(sessionKey);
+        this.effectiveInstructionsShas.delete(sessionKey);
     }
     /** Clear the main thread id when app-server rejects it (stale / deleted). */
     clearMainThread() {
         this.threadIds.delete(this.mainSessionKey);
+        this.effectiveInstructionsShas.delete(this.mainSessionKey);
         try {
             fs.rmSync(this.stateFilePath, { force: true });
         }
@@ -56,6 +95,10 @@ export class CodexSessionManager {
                 typeof parsed.threadId === 'string' &&
                 parsed.threadId.trim()) {
                 this.threadIds.set(this.mainSessionKey, parsed.threadId.trim());
+                if (typeof parsed.effectiveInstructionsSha === 'string' &&
+                    parsed.effectiveInstructionsSha.trim()) {
+                    this.effectiveInstructionsShas.set(this.mainSessionKey, parsed.effectiveInstructionsSha.trim());
+                }
             }
         }
         catch (error) {
@@ -64,7 +107,10 @@ export class CodexSessionManager {
             }
         }
     }
-    persist(threadId) {
+    persist() {
+        const threadId = this.threadIds.get(this.mainSessionKey);
+        if (!threadId)
+            return;
         // Atomic write: truncate-in-place risks leaving a half-written / zero-byte
         // state file if the process dies between `open(O_TRUNC)` and the final
         // fsync. Since this file is the sole source of cross-restart `resume`
@@ -74,7 +120,11 @@ export class CodexSessionManager {
         try {
             fs.mkdirSync(path.dirname(this.stateFilePath), { recursive: true });
             const tmpPath = `${this.stateFilePath}.tmp`;
-            fs.writeFileSync(tmpPath, JSON.stringify({ runtimeKey: this.mainSessionKey, threadId }, null, 2));
+            const state = { runtimeKey: this.mainSessionKey, threadId };
+            const effectiveSha = this.effectiveInstructionsShas.get(this.mainSessionKey);
+            if (effectiveSha)
+                state.effectiveInstructionsSha = effectiveSha;
+            fs.writeFileSync(tmpPath, JSON.stringify(state, null, 2));
             fs.renameSync(tmpPath, this.stateFilePath);
         }
         catch (error) {