@parall/codex-agent 1.43.0 → 1.45.0

package/dist/app-server-process.d.ts

@@ -0,0 +1,9 @@
+/**
+ * OS-level plumbing for the `codex app-server` child process: the cwd invariant
+ * it requires (a git repo), and the Windows spawn/kill quirks.
+ */
+export declare const IS_WIN32: boolean;
+export declare function quoteWin32Arg(arg: string): string;
+export declare function killWin32Tree(pid: number): boolean;
+export declare function ensureGitRepo(workingDirectory: string): void;
+//# sourceMappingURL=app-server-process.d.ts.map

package/dist/app-server-process.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-server-process.d.ts","sourceRoot":"","sources":["../src/app-server-process.ts"],"names":[],"mappings":"AAIA;;;GAGG;AAEH,eAAO,MAAM,QAAQ,SAA+B,CAAC;AAErD,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGjD;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAOlD;AAED,wBAAgB,aAAa,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAiC5D"}

package/dist/app-server-process.js

@@ -0,0 +1,58 @@
+import { execSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import { ensureLocalAttachmentGitExclude } from '@parall/agent-core/internal/attachment-input';
+/**
+ * OS-level plumbing for the `codex app-server` child process: the cwd invariant
+ * it requires (a git repo), and the Windows spawn/kill quirks.
+ */
+export const IS_WIN32 = process.platform === 'win32';
+export function quoteWin32Arg(arg) {
+    if (!/[\s"&|^<>()]/.test(arg))
+        return arg;
+    return `"${arg.replace(/"/g, '""')}"`;
+}
+export function killWin32Tree(pid) {
+    try {
+        execSync(`taskkill /T /F /PID ${pid}`, { windowsHide: true, stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function ensureGitRepo(workingDirectory) {
+    fs.mkdirSync(workingDirectory, { recursive: true });
+    // Only `git init` if the workspace isn't already inside any git repo. A
+    // bare existsSync(.git) check would miss the common case of a user pointing
+    // PRLL_WORKSPACE_DIR at a subdirectory of their existing project,
+    // and silently creating a nested repo there would mangle their layout.
+    //
+    // The exclude write sits inside this try, so in principle its failure would
+    // read as "not a repo" and fall through to `git init` in the user's existing
+    // repository. It cannot: the helper swallows its own errors. Deliberately left
+    // as-is rather than fixed under review — latent, not live, and out of this
+    // PR's scope: docs/tech-debt/codex-ensure-git-repo-exclude-coupling.md.
+    try {
+        execSync('git rev-parse --is-inside-work-tree', { cwd: workingDirectory, stdio: 'pipe' });
+        ensureLocalAttachmentGitExclude(workingDirectory);
+        return;
+    }
+    catch {
+        // Not inside a repo — fall through to init.
+    }
+    const env = {
+        ...process.env,
+        GIT_AUTHOR_NAME: 'parall-codex-agent',
+        GIT_AUTHOR_EMAIL: 'agent@parall.local',
+        GIT_COMMITTER_NAME: 'parall-codex-agent',
+        GIT_COMMITTER_EMAIL: 'agent@parall.local',
+    };
+    try {
+        execSync('git init', { cwd: workingDirectory, stdio: 'pipe', env });
+        execSync('git commit --allow-empty -m init', { cwd: workingDirectory, stdio: 'pipe', env });
+        ensureLocalAttachmentGitExclude(workingDirectory);
+    }
+    catch {
+        // Non-fatal: codex app-server may still accept a bare directory. Let it raise at turn time.
+    }
+}

package/dist/app-server-protocol.d.ts

@@ -0,0 +1,19 @@
+import type { PreparedLocalImage } from '@parall/agent-core/internal/attachment-input';
+/**
+ * Wire shapes of the `codex app-server` JSON-RPC payloads: what we send as turn
+ * input, and how we read ids back out of responses and notifications. The
+ * protocol has shifted between CLI versions, so the tolerant field probing lives
+ * here rather than being spread through the adapter.
+ */
+export type CodexTurnInput = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'localImage';
+    path: string;
+};
+export declare function buildTurnInput(body: string, images: PreparedLocalImage[]): CodexTurnInput[];
+export declare function extractThreadId(result: unknown): string | undefined;
+export declare function extractTurnId(result: unknown): string | undefined;
+export declare function extractThreadIdFromNotification(params: unknown): string | undefined;
+//# sourceMappingURL=app-server-protocol.d.ts.map

package/dist/app-server-protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-server-protocol.d.ts","sourceRoot":"","sources":["../src/app-server-protocol.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8CAA8C,CAAC;AAEvF;;;;;GAKG;AAEH,MAAM,MAAM,cAAc,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnG,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,kBAAkB,EAAE,GAAG,cAAc,EAAE,CAK3F;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAOnE;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAOjE;AAED,wBAAgB,+BAA+B,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CASnF"}

package/dist/app-server-protocol.js

@@ -0,0 +1,42 @@
+export function buildTurnInput(body, images) {
+    return [
+        { type: 'text', text: body },
+        ...images.map((image) => ({ type: 'localImage', path: image.localPath })),
+    ];
+}
+export function extractThreadId(result) {
+    if (!result || typeof result !== 'object')
+        return undefined;
+    const r = result;
+    if (typeof r.threadId === 'string')
+        return r.threadId;
+    const thread = r.thread;
+    if (thread && typeof thread.id === 'string')
+        return thread.id;
+    return undefined;
+}
+export function extractTurnId(result) {
+    if (!result || typeof result !== 'object')
+        return undefined;
+    const r = result;
+    if (typeof r.turnId === 'string')
+        return r.turnId;
+    const turn = r.turn;
+    if (turn && typeof turn.id === 'string')
+        return turn.id;
+    return undefined;
+}
+export function extractThreadIdFromNotification(params) {
+    if (!params || typeof params !== 'object')
+        return undefined;
+    const p = params;
+    if (typeof p.threadId === 'string')
+        return p.threadId;
+    const thread = p.thread;
+    if (thread && typeof thread.id === 'string')
+        return thread.id;
+    const meta = (p._meta ?? p.meta);
+    if (meta && typeof meta.threadId === 'string')
+        return meta.threadId;
+    return undefined;
+}

package/dist/dispatch.d.ts

@@ -15,7 +15,41 @@ type CodexAppServerAdapterOptions = Pick<CodexAgentConfig, 'approvalPolicy' | 'c
      * on its next shell command — no respawn needed.
      */
     capabilityBinDir?: string;
+    /**
+     * Platform system prompt, delivered per-thread via the app-server's typed
+     * top-level `developerInstructions` param — the ONLY delivery channel. It
+     * replaces the legacy workspace `.codex/config.toml` + global trust entry,
+     * which coupled the prompt to codex's interactive workspace-trust concept
+     * and made the bridge write into the operator's own config on shared homes.
+     *
+     * Where it lands, live-probed on 0.144.1 — the CLI accepts the param on all
+     * three entrypoints but only `thread/start` APPLIES it (instructions are
+     * baked into the thread there). `thread/resume` keeps the thread's own copy;
+     * `thread/fork` inherits the parent's. The bridge sends it on all three
+     * anyway: a failed resume falls back to thread/start on the same params, and
+     * a future CLI that honors it then needs no bridge change.
+     *
+     * Consequence: updateConfig() changes what the NEXT thread/start sends; it
+     * cannot re-instruct an already-persisted thread. Inherited from the retired
+     * channel, not introduced —
+     * docs/tech-debt/codex-persisted-thread-prompt-refresh.md.
+     */
+    developerInstructions?: string;
 };
+/**
+ * Bridge driver backed by `codex app-server --listen stdio://`.
+ *
+ * Lifecycle:
+ *   - bridge startup: spawn one `codex app-server` subprocess, do the
+ *     `initialize` / `initialized` handshake once, keep the pipe open
+ *   - per Parall dispatch: `thread/start` (first time) or `thread/resume`,
+ *     then `turn/start`; forward server notifications until `turn/completed`
+ *   - fork-on-busy: `thread/fork` creates a disposable sibling thread
+ *
+ * Concurrency: agent-core routes one dispatch per sessionKey at a time, so
+ * main + fork can interleave turns on the same stdio pipe. We route
+ * notifications by threadId the server stamps on every item/turn event.
+ */
 export declare class CodexAppServerAdapter implements DispatchAdapter {
     private readonly opts;
     private client;
@@ -40,6 +74,7 @@ export declare class CodexAppServerAdapter implements DispatchAdapter {
     updateConfig(config: {
         model?: string | null;
         reasoningEffort?: string | null;
+        developerInstructions?: string | null;
     }): void;
     enqueueDuringDispatch(sessionKey: string, body: string): Promise<boolean>;
     abortDispatch(sessionKey: string): void;
@@ -50,11 +85,14 @@ export declare class CodexAppServerAdapter implements DispatchAdapter {
     cleanupFork({ fork }: CleanupForkOpts): void;
     private logForkFailure;
     /**
-     * Lazily restart the app-server before the NEXT turn: the workspace
-     * config.toml (developer_instructions, carrying capability fragments) is
-     * loaded at process start, so a changed fragment set needs a respawn to
-     * reach the prompt. Deferred to the next dispatch with no active turns —
-     * never kills an in-flight turn; thread state survives via thread/resume.
+     * Lazily restart the app-server before the NEXT turn, so a subprocess that
+     * has been running since before a capability change starts clean. Deferred
+     * to the next dispatch with no active turns — never kills an in-flight turn;
+     * thread state survives via thread/resume.
+     *
+     * A restart does NOT re-instruct an already-persisted thread — see the
+     * `developerInstructions` option doc. The capability shim dir on PATH is what
+     * makes a grant/revocation effective immediately.
      */
     requestProcessRestart(): void;
     private restartRequested;

package/dist/dispatch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../src/dispatch.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EACV,eAAe,EACf,eAAe,EACf,YAAY,EACZ,QAAQ,EACR,iBAAiB,EACjB,aAAa,EACb,YAAY,EACb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAIpD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEhE,KAAK,4BAA4B,GAAG,IAAI,CACtC,gBAAgB,EACd,gBAAgB,GAChB,UAAU,GACV,WAAW,GACX,OAAO,GACP,iBAAiB,GACjB,SAAS,GACT,cAAc,CACjB,GAAG;IACF,cAAc,EAAE,mBAAmB,CAAC;IACpC,GAAG,CAAC,EAAE,aAAa,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAqCF,qBAAa,qBAAsB,YAAW,eAAe;IA+B/C,OAAO,CAAC,QAAQ,CAAC,IAAI;IA9BjC,OAAO,CAAC,MAAM,CAAmC;IACjD,OAAO,CAAC,IAAI,CAA+C;IAC3D,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,YAAY,CAA8B;IAClD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA+B;IAC3D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA6B;IAC3D,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA6B;IAC/D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAqB;IACtD,OAAO,CAAC,QAAQ,CAAS;IAEzB;;;;;;;OAOG;IACH,OAAO,CAAC,aAAa;gBAYQ,IAAI,EAAE,4BAA4B;IAE/D,YAAY,CAAC,MAAM,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI;IAMhF,qBAAqB,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAqB/E,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAUvC,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAI1C,QAAQ,CAAC,EACd,KAAK,EACL,YAAY,EACZ,UAAU,EACV,OAAO,GACR,EAAE,YAAY,GAAG,aAAa,CAAC,YAAY,CAAC;IA8P7C,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAMjD,WAAW,CAAC,EAAE,UAAU,EAAE,gBAAgB,EAAE,EAAE,QAAQ,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAgChG,WAAW,CAAC,EAAE,IAAI,EAAE,EAAE,eAAe;IAIrC,OAAO,CAAC,cAAc;IAKtB;;;;;;OAMG;IACH,qBAAqB,IAAI,IAAI;IAI7B,OAAO,CAAC,gBAAgB,CAAS;YAEnB,mBAAmB;IAS3B,IAAI;YAuBI,aAAa;YA2Bb,OAAO;IAuGrB,OAAO,CAAC,qBAAqB;YAmCf,UAAU;IA6CxB,OAAO,CAAC,iBAAiB;CA2B1B"}
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../src/dispatch.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EACV,eAAe,EACf,eAAe,EACf,YAAY,EACZ,QAAQ,EACR,iBAAiB,EACjB,aAAa,EACb,YAAY,EACb,MAAM,oBAAoB,CAAC;AAQ5B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAGpD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAGhE,KAAK,4BAA4B,GAAG,IAAI,CACtC,gBAAgB,EACd,gBAAgB,GAChB,UAAU,GACV,WAAW,GACX,OAAO,GACP,iBAAiB,GACjB,SAAS,GACT,cAAc,CACjB,GAAG;IACF,cAAc,EAAE,mBAAmB,CAAC;IACpC,GAAG,CAAC,EAAE,aAAa,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;;;;;;;;;;;;;OAkBG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,qBAAa,qBAAsB,YAAW,eAAe;IA+B/C,OAAO,CAAC,QAAQ,CAAC,IAAI;IA9BjC,OAAO,CAAC,MAAM,CAAmC;IACjD,OAAO,CAAC,IAAI,CAA+C;IAC3D,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,YAAY,CAA8B;IAClD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA+B;IAC3D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA6B;IAC3D,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA6B;IAC/D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAqB;IACtD,OAAO,CAAC,QAAQ,CAAS;IAEzB;;;;;;;OAOG;IACH,OAAO,CAAC,aAAa;gBAYQ,IAAI,EAAE,4BAA4B;IAE/D,YAAY,CAAC,MAAM,EAAE;QACnB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAChC,qBAAqB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KACvC,GAAG,IAAI;IAQF,qBAAqB,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAqB/E,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAUvC,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAI1C,QAAQ,CAAC,EACd,KAAK,EACL,YAAY,EACZ,UAAU,EACV,OAAO,GACR,EAAE,YAAY,GAAG,aAAa,CAAC,YAAY,CAAC;IA8P7C,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAMjD,WAAW,CAAC,EAAE,UAAU,EAAE,gBAAgB,EAAE,EAAE,QAAQ,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAqChG,WAAW,CAAC,EAAE,IAAI,EAAE,EAAE,eAAe;IAIrC,OAAO,CAAC,cAAc;IAKtB;;;;;;;;;OASG;IACH,qBAAqB,IAAI,IAAI;IAI7B,OAAO,CAAC,gBAAgB,CAAS;YAEnB,mBAAmB;IAS3B,IAAI;YAuBI,aAAa;YA2Bb,OAAO;IAuGrB,OAAO,CAAC,qBAAqB;YAmCf,UAAU;IAoDxB,OAAO,CAAC,iBAAiB;CA2B1B"}

package/dist/dispatch.js

@@ -1,11 +1,12 @@
-import { execSync, spawn } from 'node:child_process';
+import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
-import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { appendPreparedLocalAttachmentRefs, ensureLocalAttachmentGitExclude, pinLocalAttachmentPaths, } from '@parall/agent-core/internal/attachment-input';
+import { appendPreparedLocalAttachmentRefs, pinLocalAttachmentPaths, } from '@parall/agent-core/internal/attachment-input';
+import { IS_WIN32, ensureGitRepo, killWin32Tree, quoteWin32Arg } from './app-server-process.js';
+import { buildTurnInput, extractThreadId, extractThreadIdFromNotification, extractTurnId, } from './app-server-protocol.js';
 import { normalizeApprovalPolicy, normalizeSandbox } from './config.js';
-import { EventMapper } from './event-mapping.js';
 import { JsonRpcStdioClient } from './jsonrpc-client.js';
+import { TurnSink } from './turn-sink.js';
 /**
  * Bridge driver backed by `codex app-server --listen stdio://`.
  *
@@ -20,21 +21,6 @@ import { JsonRpcStdioClient } from './jsonrpc-client.js';
  * main + fork can interleave turns on the same stdio pipe. We route
  * notifications by threadId the server stamps on every item/turn event.
  */
-const IS_WIN32 = process.platform === 'win32';
-function quoteWin32Arg(arg) {
-    if (!/[\s"&|^<>()]/.test(arg))
-        return arg;
-    return `"${arg.replace(/"/g, '""')}"`;
-}
-function killWin32Tree(pid) {
-    try {
-        execSync(`taskkill /T /F /PID ${pid}`, { windowsHide: true, stdio: 'ignore' });
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
 export class CodexAppServerAdapter {
     opts;
     client = null;
@@ -71,6 +57,8 @@ export class CodexAppServerAdapter {
             this.opts.model = config.model ?? undefined;
         if (config.reasoningEffort !== undefined)
             this.opts.reasoningEffort = config.reasoningEffort ?? undefined;
+        if (config.developerInstructions !== undefined)
+            this.opts.developerInstructions = config.developerInstructions ?? undefined;
     }
     async enqueueDuringDispatch(sessionKey, body) {
         const client = this.client;
@@ -381,6 +369,11 @@ export class CodexAppServerAdapter {
             if (this.opts.useParallProvider) {
                 forkParams.modelProvider = 'parall';
             }
+            if (this.opts.developerInstructions) {
+                // Accepted, but the fork inherits the parent's instructions instead —
+                // so it carries the platform prompt either way. See the option doc.
+                forkParams.developerInstructions = this.opts.developerInstructions;
+            }
             if (this.opts.model)
                 forkParams.model = this.opts.model;
             if (this.opts.reasoningEffort) {
@@ -408,11 +401,14 @@ export class CodexAppServerAdapter {
         return null;
     }
     /**
-     * Lazily restart the app-server before the NEXT turn: the workspace
-     * config.toml (developer_instructions, carrying capability fragments) is
-     * loaded at process start, so a changed fragment set needs a respawn to
-     * reach the prompt. Deferred to the next dispatch with no active turns —
-     * never kills an in-flight turn; thread state survives via thread/resume.
+     * Lazily restart the app-server before the NEXT turn, so a subprocess that
+     * has been running since before a capability change starts clean. Deferred
+     * to the next dispatch with no active turns — never kills an in-flight turn;
+     * thread state survives via thread/resume.
+     *
+     * A restart does NOT re-instruct an already-persisted thread — see the
+     * `developerInstructions` option doc. The capability shim dir on PATH is what
+     * makes a grant/revocation effective immediately.
      */
     requestProcessRestart() {
         this.restartRequested = true;
@@ -422,7 +418,7 @@ export class CodexAppServerAdapter {
         if (!this.restartRequested || this.activeTurns.size > 0)
             return;
         this.restartRequested = false;
-        (log ?? this.opts.log)?.info?.('restarting codex app-server to pick up updated developer_instructions');
+        (log ?? this.opts.log)?.info?.('restarting codex app-server after a capability change (new threads pick up the refreshed developerInstructions; an already-persisted thread keeps its own)');
         await this.stop();
     }
     async stop() {
@@ -617,6 +613,13 @@ export class CodexAppServerAdapter {
             commonParams.modelProvider = 'parall';
         }
         commonParams.sandbox = normalizeSandbox(this.opts.sandbox);
+        if (this.opts.developerInstructions) {
+            // Typed top-level param (camelCase), NOT a raw config.toml override —
+            // trust-independent, so the platform prompt loads regardless of any codex
+            // workspace-trust state. thread/start applies it; thread/resume keeps the
+            // thread's own copy. Sent on both — see the option doc.
+            commonParams.developerInstructions = this.opts.developerInstructions;
+        }
         if (this.opts.model)
             commonParams.model = this.opts.model;
         if (this.opts.reasoningEffort) {
@@ -667,117 +670,6 @@ export class CodexAppServerAdapter {
         }
     }
 }
-/** Per-turn buffered sink backed by an unbounded promise queue. */
-class TurnSink {
-    mapper = new EventMapper();
-    queue = [];
-    resolver = null;
-    closed = false;
-    push(envelope) {
-        if (this.closed)
-            return;
-        if (this.resolver) {
-            const r = this.resolver;
-            this.resolver = null;
-            r(envelope);
-            return;
-        }
-        this.queue.push(envelope);
-    }
-    next() {
-        // Drain any queued envelopes first, even after close(). Otherwise a final
-        // error envelope enqueued right before close() (e.g. by
-        // handleSubprocessClose) is silently dropped because the consumer would
-        // see turn_end before it.
-        const pending = this.queue.shift();
-        if (pending)
-            return Promise.resolve(pending);
-        if (this.closed) {
-            return Promise.resolve({ kind: 'turn_end' });
-        }
-        return new Promise((resolve) => {
-            this.resolver = resolve;
-        });
-    }
-    close() {
-        this.closed = true;
-        const r = this.resolver;
-        this.resolver = null;
-        r?.({ kind: 'turn_end' });
-    }
-}
-function ensureGitRepo(workingDirectory) {
-    fs.mkdirSync(workingDirectory, { recursive: true });
-    // Only `git init` if the workspace isn't already inside any git repo. A
-    // bare existsSync(.git) check would miss the common case of a user pointing
-    // PRLL_WORKSPACE_DIR at a subdirectory of their existing project,
-    // and silently creating a nested repo there would mangle their layout.
-    try {
-        execSync('git rev-parse --is-inside-work-tree', { cwd: workingDirectory, stdio: 'pipe' });
-        ensureLocalAttachmentGitExclude(workingDirectory);
-        return;
-    }
-    catch {
-        // Not inside a repo — fall through to init.
-    }
-    const env = {
-        ...process.env,
-        GIT_AUTHOR_NAME: 'parall-codex-agent',
-        GIT_AUTHOR_EMAIL: 'agent@parall.local',
-        GIT_COMMITTER_NAME: 'parall-codex-agent',
-        GIT_COMMITTER_EMAIL: 'agent@parall.local',
-    };
-    try {
-        execSync('git init', { cwd: workingDirectory, stdio: 'pipe', env });
-        execSync('git commit --allow-empty -m init', { cwd: workingDirectory, stdio: 'pipe', env });
-        ensureLocalAttachmentGitExclude(workingDirectory);
-    }
-    catch {
-        // Non-fatal: codex app-server may still accept a bare directory. Let it raise at turn time.
-    }
-}
-function buildTurnInput(body, images) {
-    return [
-        { type: 'text', text: body },
-        ...images.map((image) => ({ type: 'localImage', path: image.localPath })),
-    ];
-}
-function extractThreadId(result) {
-    if (!result || typeof result !== 'object')
-        return undefined;
-    const r = result;
-    if (typeof r.threadId === 'string')
-        return r.threadId;
-    const thread = r.thread;
-    if (thread && typeof thread.id === 'string')
-        return thread.id;
-    return undefined;
-}
-function extractTurnId(result) {
-    if (!result || typeof result !== 'object')
-        return undefined;
-    const r = result;
-    if (typeof r.turnId === 'string')
-        return r.turnId;
-    const turn = r.turn;
-    if (turn && typeof turn.id === 'string')
-        return turn.id;
-    return undefined;
-}
-function extractThreadIdFromNotification(params) {
-    if (!params || typeof params !== 'object')
-        return undefined;
-    const p = params;
-    if (typeof p.threadId === 'string')
-        return p.threadId;
-    const thread = p.thread;
-    if (thread && typeof thread.id === 'string')
-        return thread.id;
-    const meta = (p._meta ?? p.meta);
-    if (meta && typeof meta.threadId === 'string')
-        return meta.threadId;
-    return undefined;
-}
 function errToString(err) {
     if (err instanceof Error)
         return err.message;

package/dist/index.js

@@ -5,7 +5,7 @@ import { ApiError, ParallClient, ParallWs } from '@parall/sdk';
 import { buildCodexRuntimeKey, contextFilePathForSession, dispatchContextDirPath, resolveCodexAgentConfig, resolveWsUrl, sessionStateFilePathForRuntime, stepIdFilePathForSession, } from './config.js';
 import { CodexAppServerAdapter } from './dispatch.js';
 import { CodexSessionManager } from './session-manager.js';
-import { ensureCodexWorkspace, ensureParallProvider, ensureWorkspaceTrusted, isParallProxyMode, writeCodexSystemPrompt, } from './workspace.js';
+import { ensureCodexWorkspace, ensureParallProvider, isParallProxyMode, writeCodexSystemPrompt, } from './workspace.js';
 const log = createLogger('codex-agent');
 let activeLog = log;
 async function getAgentMeWithLegacyFallback(client, orgId) {
@@ -52,7 +52,6 @@ async function main() {
         const agentUserId = me.id;
         const agentLog = childLogger(activeLog, agentUserId);
         activeLog = agentLog;
-        ensureWorkspaceTrusted(config.codexHome, config.workspaceDir, agentLog);
         const useParallProvider = isParallProxyMode();
         if (useParallProvider) {
             ensureParallProvider(config.codexHome, config.apiUrl, agentLog);
@@ -89,11 +88,14 @@ async function main() {
             materializeChannelCapabilities(config.stateDir, caps, agentLog);
             return caps.map((c) => c.fragment);
         };
-        // Assemble the workspace AFTER the first config fetch so
-        // developer_instructions carries the capability declarations from boot.
+        // Assemble the workspace AFTER the first config fetch so the platform
+        // prompt carries the capability declarations from boot.
         const bootCapabilityFragments = applyChannelCapabilities();
         let lastCapabilityFragments = bootCapabilityFragments.join('\n\n');
-        ensureCodexWorkspace(config.workspaceDir, agentLog, agentIdentity, bootCapabilityFragments);
+        // Platform instructions are delivered per-thread via the app-server's
+        // developerInstructions param — no workspace config file, no dependence
+        // on codex's workspace-trust state, no writes to the operator's config.
+        const developerInstructions = ensureCodexWorkspace(config.workspaceDir, agentLog, agentIdentity, bootCapabilityFragments);
         // Model precedence: operator PIN (override) > env > server FLOOR. The server
         // now says which it is via model_is_pin (deriveModelIsPin presence-gates the
         // dual-read: old servers omit it → fall back to model_management). A PIN beats
@@ -120,6 +122,7 @@ async function main() {
             contextDirPath: dispatchContextDirPath(config.stateDir),
             useParallProvider,
             capabilityBinDir: capabilityBinDir(config.stateDir),
+            developerInstructions,
         });
         // Shared by onConfigUpdate + onSessionReady. /agents/me is only consumed as
         // deriveModelIsPin's legacy fallback when the server omits model_is_pin
@@ -145,15 +148,26 @@ async function main() {
                 model: resolveRuntimeModel(isPin, updated.model, config.model) ?? null,
                 reasoningEffort: updated.thinkingEffort ?? config.reasoningEffort ?? null,
             });
-            // Capability heat-update: re-materialize shims + rewrite the prompt
-            // surfaces. The write is refresh-tolerant (warn + retry next refresh);
-            // only a SUCCESSFUL write with a changed fragment set schedules the
-            // lazy app-server restart (developer_instructions loads at spawn).
+            // Capability heat-update: re-materialize shims + rebuild the prompt.
+            // The write is refresh-tolerant (warn + retry next refresh); only a
+            // SUCCESSFUL rebuild with a changed fragment set schedules the lazy
+            // app-server restart.
+            //
+            // What each half of the refresh actually reaches: the shim dir on PATH
+            // makes the granted TOOL work on the agent's next shell command, live,
+            // no restart needed. The refreshed PROMPT reaches the next thread that
+            // gets STARTED — codex bakes developerInstructions into a thread at
+            // thread/start and neither resume nor fork replaces them (live-probed on
+            // 0.144.1; the retired workspace-config channel had the same limitation).
+            // So an agent with a long-lived persisted thread keeps the older fragment
+            // text in its prompt until that thread is replaced —
+            // docs/tech-debt/codex-persisted-thread-prompt-refresh.md.
             const fragments = applyChannelCapabilities();
             const joinedFragments = fragments.join('\n\n');
             let promptWritten = true;
             try {
-                writeCodexSystemPrompt(config.workspaceDir, agentIdentity, fragments);
+                const refreshedPrompt = writeCodexSystemPrompt(config.workspaceDir, agentIdentity, fragments);
+                adapter.updateConfig({ developerInstructions: refreshedPrompt });
             }
             catch (err) {
                 promptWritten = false;

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"}