@tickernelz/paperclip-pro-adapter-utils 2026.1006.0 → 2026.1006.2

package/dist/directory-merge-lock.test.js

@@ -0,0 +1,166 @@
+import { execFile, spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { once } from "node:events";
+import { access, link, mkdir, mkdtemp, readFile, realpath, rm, stat, symlink, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { withDirectoryMergeLock, WORKSPACE_RESTORE_LOCK_TIMEOUT_CODE } from "./workspace-restore-merge.js";
+describe("directory merge lock process lifetime", () => {
+    // Load tsx as an --import hook, not tsx's own CLI entry point. The CLI entry
+    // point re-spawns the evaluated code in a further child process, so killing
+    // the process this file spawns would leave that further child as an orphan
+    // that still holds the lock. The --import hook runs the evaluated code in
+    // the process this file spawns directly, so killing it really does release
+    // the lock.
+    const loader = fileURLToPath(new URL("../../../cli/node_modules/tsx/dist/loader.mjs", import.meta.url));
+    const module = fileURLToPath(new URL("./workspace-restore-merge.ts", import.meta.url));
+    const directories = [];
+    const children = [];
+    afterEach(async () => {
+        vi.restoreAllMocks();
+        for (const child of children.splice(0)) {
+            if (child.exitCode === null && child.signalCode === null) {
+                const exited = once(child, "exit");
+                child.kill("SIGKILL");
+                await exited;
+            }
+        }
+        await Promise.all(directories.splice(0).map((dir) => rm(dir, { recursive: true, force: true })));
+    });
+    async function fixture() {
+        const root = await mkdtemp(path.join(os.tmpdir(), "paperclip-lock-process-"));
+        directories.push(root);
+        const target = path.join(root, "target");
+        await mkdir(target);
+        const env = { ...process.env, PAPERCLIP_HOME: path.join(root, "home"), PAPERCLIP_INSTANCE_ID: "test" };
+        const key = createHash("sha256").update(await realpath(target)).digest("hex");
+        const lock = path.join(env.PAPERCLIP_HOME, "instances", "test", "locks", "directory-merge", `${key}.lock`);
+        return { target, env, lock };
+    }
+    async function holder(target, env) {
+        const child = spawn(process.execPath, ["--import", loader, "--eval", `
+      import { withDirectoryMergeLock } from ${JSON.stringify(module)};
+      withDirectoryMergeLock(${JSON.stringify(target)}, async () => {
+        process.send?.("locked");
+        await new Promise(resolve => process.once("message", resolve));
+      }).then(() => process.exit(0)).catch(error => { console.error(error); process.exit(1); });
+    `], { env, stdio: ["ignore", "ignore", "pipe", "ipc"] });
+        children.push(child);
+        let stderr = "";
+        child.stderr?.on("data", (chunk) => { stderr += chunk; });
+        await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => reject(new Error(`Child did not acquire lock: ${stderr}`)), 10_000);
+            child.once("message", () => { clearTimeout(timer); resolve(); });
+            child.once("error", (error) => { clearTimeout(timer); reject(error); });
+            child.once("exit", (code) => { clearTimeout(timer); reject(new Error(`Child exited ${code}: ${stderr}`)); });
+        });
+        return child;
+    }
+    // Both protocols carry diagnostic owner records. This also lets the crash
+    // regression demonstrate the old implementation's PID-reuse failure.
+    async function ownerPath(lock) {
+        return await access(`${lock}.owner.json`).then(() => `${lock}.owner.json`, () => path.join(lock, "owner.json"));
+    }
+    // A short real wait budget for a test that asserts a timeout. 200 ms still
+    // lets the implementation's 50 ms retry interval run at least 4 retries, so
+    // the timeout is reached because the lock is genuinely held, not because
+    // the clock was replaced.
+    const TIMEOUT_ASSERTION_WAIT_MS = 200;
+    // A short real wait budget for the crash-recovery test, which asserts a
+    // successful acquisition. It must absorb ordinary scheduling jitter around
+    // the crash while still resolving well inside the test timeout below.
+    const CRASH_RECOVERY_WAIT_MS = 5_000;
+    it("recovers a killed holder even when its recorded PID has been reused", async () => {
+        const { target, env, lock } = await fixture();
+        const child = await holder(target, env);
+        const exited = once(child, "exit");
+        child.kill("SIGKILL");
+        await exited;
+        const recordPath = await ownerPath(lock);
+        const record = JSON.parse(await readFile(recordPath, "utf8"));
+        await writeFile(recordPath, JSON.stringify({ ...record, pid: process.pid }));
+        await expect(withDirectoryMergeLock(target, async () => "restored", env, undefined, CRASH_RECOVERY_WAIT_MS)).resolves.toBe("restored");
+    }, 15_000);
+    it("protects a live holder in another process regardless of diagnostic PID or age", async () => {
+        const { target, env, lock } = await fixture();
+        const child = await holder(target, env);
+        const recordPath = await ownerPath(lock);
+        await writeFile(recordPath, JSON.stringify({ pid: 2_147_483_647, createdAt: "2000-01-01T00:00:00.000Z" }));
+        const contender = vi.fn();
+        await expect(withDirectoryMergeLock(target, contender, env, undefined, TIMEOUT_ASSERTION_WAIT_MS)).rejects.toMatchObject({ code: WORKSPACE_RESTORE_LOCK_TIMEOUT_CODE });
+        expect(contender).not.toHaveBeenCalled();
+        const exited = once(child, "exit");
+        child.send("release");
+        await exited;
+        await expect(withDirectoryMergeLock(target, async () => "released", env)).resolves.toBe("released");
+    }, 15_000);
+    it("releases ownership when the protected operation throws", async () => {
+        const { target, env } = await fixture();
+        await expect(withDirectoryMergeLock(target, async () => { throw new Error("operation failed"); }, env)).rejects.toThrow("operation failed");
+        await expect(withDirectoryMergeLock(target, async () => "next", env)).resolves.toBe("next");
+    });
+    it("keeps the OS lock when a same-process contender closes its connection", async () => {
+        const { target, env } = await fixture();
+        await withDirectoryMergeLock(target, async () => {
+            await expect(withDirectoryMergeLock(target, async () => undefined, env, undefined, TIMEOUT_ASSERTION_WAIT_MS)).rejects.toMatchObject({ code: WORKSPACE_RESTORE_LOCK_TIMEOUT_CODE });
+            // A same-process test alone cannot prove that the OS lock survived: on
+            // POSIX, closing an unmanaged descriptor can drop process-wide locks.
+            const result = await promisify(execFile)(process.execPath, ["--import", loader, "--eval", `
+        import { withDirectoryMergeLock, WORKSPACE_RESTORE_LOCK_TIMEOUT_CODE } from ${JSON.stringify(module)};
+        withDirectoryMergeLock(${JSON.stringify(target)}, async () => "entered", undefined, undefined, ${TIMEOUT_ASSERTION_WAIT_MS})
+          .then(() => { console.error("Entered a live holder's lock"); process.exit(1); })
+          .catch(error => {
+            if (error.code !== WORKSPACE_RESTORE_LOCK_TIMEOUT_CODE) { console.error(error); process.exit(1); }
+            console.log("blocked");
+          });
+      `], { env, timeout: 10_000 });
+            expect(result.stdout.trim()).toBe("blocked");
+        }, env);
+    }, 15_000);
+    it("does not serialize unrelated target directories", async () => {
+        const { target, env } = await fixture();
+        const other = `${target}-other`;
+        await mkdir(other);
+        await withDirectoryMergeLock(target, async () => {
+            await expect(withDirectoryMergeLock(other, async () => "independent", env)).resolves.toBe("independent");
+        }, env);
+    });
+    it("retains the same database inode across holders", async () => {
+        const { target, env, lock } = await fixture();
+        await withDirectoryMergeLock(target, async () => undefined, env);
+        const before = await stat(`${lock}.sqlite`);
+        await withDirectoryMergeLock(target, async () => undefined, env);
+        const after = await stat(`${lock}.sqlite`);
+        expect({ dev: after.dev, ino: after.ino }).toEqual({ dev: before.dev, ino: before.ino });
+    });
+    it("closes the kernel lock when writing diagnostics fails", async () => {
+        const { target, env, lock } = await fixture();
+        await mkdir(`${lock}.owner.json`, { recursive: true });
+        await expect(withDirectoryMergeLock(target, async () => undefined, env)).rejects.toThrow();
+        await rm(`${lock}.owner.json`, { recursive: true });
+        await expect(withDirectoryMergeLock(target, async () => "next", env)).resolves.toBe("next");
+    });
+    it.each(["missing", "malformed", "dead PID"])("does not guess ownership of a legacy lock with %s metadata", async (kind) => {
+        const { target, env, lock } = await fixture();
+        await mkdir(lock, { recursive: true });
+        if (kind !== "missing")
+            await writeFile(path.join(lock, "owner.json"), kind === "malformed" ? "{broken" : JSON.stringify({ pid: 2_147_483_647, createdAt: "2000-01-01T00:00:00.000Z" }));
+        const contender = vi.fn();
+        await expect(withDirectoryMergeLock(target, contender, env, undefined, TIMEOUT_ASSERTION_WAIT_MS)).rejects.toMatchObject({ code: WORKSPACE_RESTORE_LOCK_TIMEOUT_CODE });
+        expect(contender).not.toHaveBeenCalled();
+        expect((await stat(lock)).isDirectory()).toBe(true);
+    });
+    it.skipIf(process.platform === "win32").each(["symlink", "hard link"])("rejects a lock database that is a %s", async (kind) => {
+        const { target, env, lock } = await fixture();
+        await mkdir(path.dirname(lock), { recursive: true });
+        const decoy = `${target}-decoy`;
+        await writeFile(decoy, "keep");
+        await (kind === "symlink" ? symlink(decoy, `${lock}.sqlite`) : link(decoy, `${lock}.sqlite`));
+        await expect(withDirectoryMergeLock(target, async () => undefined, env)).rejects.toThrow("not a plain, unshared file");
+        await expect(readFile(decoy, "utf8")).resolves.toBe("keep");
+    });
+});
+//# sourceMappingURL=directory-merge-lock.test.js.map

package/dist/directory-merge-lock.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"directory-merge-lock.test.js","sourceRoot":"","sources":["../src/directory-merge-lock.test.ts"],"names":[],"mappings":"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"}

package/dist/execution-phase.d.ts

@@ -0,0 +1,10 @@
+/** Content-free, in-memory diagnostic scopes. These never establish stop proof. */
+export declare const ADAPTER_EXECUTION_PHASES: readonly ["host_execution", "adapter_execution", "end_session", "cancel_turn", "close_session", "settle_reuse", "stop_transport", "sync_back", "instruction_collection", "workspace_restore", "phase_reporting", "instruction_cleanup", "lease_release"];
+export type AdapterExecutionPhase = (typeof ADAPTER_EXECUTION_PHASES)[number];
+export type AdapterExecutionPhaseSink = (phase: AdapterExecutionPhase) => (() => void) | void;
+export declare function isAdapterExecutionPhase(value: unknown): value is AdapterExecutionPhase;
+/** A broken diagnostic sink must not change execution or teardown outcomes. */
+export declare function withAdapterExecutionPhase<T>(context: {
+    onExecutionPhase?: AdapterExecutionPhaseSink;
+}, phase: AdapterExecutionPhase, operation: () => T | Promise<T>): Promise<T>;
+//# sourceMappingURL=execution-phase.d.ts.map

package/dist/execution-phase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-phase.d.ts","sourceRoot":"","sources":["../src/execution-phase.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,eAAO,MAAM,wBAAwB,YACnC,gBAAgB,EAAE,mBAAmB,EAAE,aAAa,EAAE,aAAa,EAAE,eAAe,EACpF,cAAc,EAAE,gBAAgB,EAAE,WAAW,EAAE,wBAAwB,EACvE,mBAAmB,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,eAAe,CACtE,CAAC;AAEX,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAC;AAC9E,MAAM,MAAM,yBAAyB,GAAG,CAAC,KAAK,EAAE,qBAAqB,KAAK,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAAC;AAE9F,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,qBAAqB,CAEtF;AAED,+EAA+E;AAC/E,wBAAsB,yBAAyB,CAAC,CAAC,EAC/C,OAAO,EAAE;IAAE,gBAAgB,CAAC,EAAE,yBAAyB,CAAA;CAAE,EACzD,KAAK,EAAE,qBAAqB,EAC5B,SAAS,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAC9B,OAAO,CAAC,CAAC,CAAC,CAQZ"}

package/dist/execution-phase.js

@@ -0,0 +1,27 @@
+/** Content-free, in-memory diagnostic scopes. These never establish stop proof. */
+export const ADAPTER_EXECUTION_PHASES = [
+    "host_execution", "adapter_execution", "end_session", "cancel_turn", "close_session",
+    "settle_reuse", "stop_transport", "sync_back", "instruction_collection",
+    "workspace_restore", "phase_reporting", "instruction_cleanup", "lease_release",
+];
+export function isAdapterExecutionPhase(value) {
+    return ADAPTER_EXECUTION_PHASES.some((phase) => phase === value);
+}
+/** A broken diagnostic sink must not change execution or teardown outcomes. */
+export async function withAdapterExecutionPhase(context, phase, operation) {
+    let release = undefined;
+    try {
+        release = context.onExecutionPhase?.(phase);
+    }
+    catch { /* diagnostics only */ }
+    try {
+        return await operation();
+    }
+    finally {
+        try {
+            release?.();
+        }
+        catch { /* diagnostics only */ }
+    }
+}
+//# sourceMappingURL=execution-phase.js.map

package/dist/execution-phase.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-phase.js","sourceRoot":"","sources":["../src/execution-phase.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACtC,gBAAgB,EAAE,mBAAmB,EAAE,aAAa,EAAE,aAAa,EAAE,eAAe;IACpF,cAAc,EAAE,gBAAgB,EAAE,WAAW,EAAE,wBAAwB;IACvE,mBAAmB,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,eAAe;CACtE,CAAC;AAKX,MAAM,UAAU,uBAAuB,CAAC,KAAc;IACpD,OAAO,wBAAwB,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC;AACnE,CAAC;AAED,+EAA+E;AAC/E,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,OAAyD,EACzD,KAA4B,EAC5B,SAA+B;IAE/B,IAAI,OAAO,GAAwB,SAAS,CAAC;IAC7C,IAAI,CAAC;QAAC,OAAO,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,KAAK,CAAC,CAAC;IAAC,CAAC;IAAC,MAAM,CAAC,CAAC,sBAAsB,CAAC,CAAC;IACrF,IAAI,CAAC;QACH,OAAO,MAAM,SAAS,EAAE,CAAC;IAC3B,CAAC;YAAS,CAAC;QACT,IAAI,CAAC;YAAC,OAAO,EAAE,EAAE,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC,CAAC,sBAAsB,CAAC,CAAC;IACvD,CAAC;AACH,CAAC"}

package/dist/execution-phase.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=execution-phase.test.d.ts.map

package/dist/execution-phase.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-phase.test.d.ts","sourceRoot":"","sources":["../src/execution-phase.test.ts"],"names":[],"mappings":""}

package/dist/execution-phase.test.js

@@ -0,0 +1,26 @@
+import { expect, it, vi } from "vitest";
+import { withAdapterExecutionPhase } from "./execution-phase.js";
+it("enters before a stalled await and releases only when that operation settles", async () => {
+    const release = vi.fn();
+    const enter = vi.fn(() => release);
+    let resolve;
+    const operation = new Promise((done) => { resolve = done; });
+    const result = withAdapterExecutionPhase({ onExecutionPhase: enter }, "instruction_collection", () => operation);
+    expect(enter).toHaveBeenCalledWith("instruction_collection");
+    await Promise.resolve();
+    expect(release).not.toHaveBeenCalled();
+    resolve(7);
+    await expect(result).resolves.toBe(7);
+    expect(release).toHaveBeenCalledOnce();
+});
+it.each(["enter", "release"])("preserves values and errors when the %s diagnostic callback throws", async (where) => {
+    const context = { onExecutionPhase: () => {
+            if (where === "enter")
+                throw new Error("diagnostic failure");
+            return () => { throw new Error("diagnostic failure"); };
+        } };
+    await expect(withAdapterExecutionPhase(context, "workspace_restore", () => 3)).resolves.toBe(3);
+    const failure = new Error("operation failure");
+    await expect(withAdapterExecutionPhase(context, "workspace_restore", () => { throw failure; })).rejects.toBe(failure);
+});
+//# sourceMappingURL=execution-phase.test.js.map

package/dist/execution-phase.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-phase.test.js","sourceRoot":"","sources":["../src/execution-phase.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AACxC,OAAO,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AAEjE,EAAE,CAAC,6EAA6E,EAAE,KAAK,IAAI,EAAE;IAC3F,MAAM,OAAO,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;IACxB,MAAM,KAAK,GAAG,EAAE,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,CAAC;IACnC,IAAI,OAAiC,CAAC;IACtC,MAAM,SAAS,GAAG,IAAI,OAAO,CAAS,CAAC,IAAI,EAAE,EAAE,GAAG,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IACrE,MAAM,MAAM,GAAG,yBAAyB,CAAC,EAAE,gBAAgB,EAAE,KAAK,EAAE,EAAE,wBAAwB,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IACjH,MAAM,CAAC,KAAK,CAAC,CAAC,oBAAoB,CAAC,wBAAwB,CAAC,CAAC;IAC7D,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;IACxB,MAAM,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,gBAAgB,EAAE,CAAC;IACvC,OAAO,CAAC,CAAC,CAAC,CAAC;IACX,MAAM,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACtC,MAAM,CAAC,OAAO,CAAC,CAAC,oBAAoB,EAAE,CAAC;AACzC,CAAC,CAAC,CAAC;AAEH,EAAE,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,oEAAoE,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;IAClH,MAAM,OAAO,GAAG,EAAE,gBAAgB,EAAE,GAAG,EAAE;YACvC,IAAI,KAAK,KAAK,OAAO;gBAAE,MAAM,IAAI,KAAK,CAAC,oBAAoB,CAAC,CAAC;YAC7D,OAAO,GAAG,EAAE,GAAG,MAAM,IAAI,KAAK,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1D,CAAC,EAAE,CAAC;IACJ,MAAM,MAAM,CAAC,yBAAyB,CAAC,OAAO,EAAE,mBAAmB,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAChG,MAAM,OAAO,GAAG,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC;IAC/C,MAAM,MAAM,CAAC,yBAAyB,CAAC,OAAO,EAAE,mBAAmB,EAAE,GAAG,EAAE,GAAG,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AACxH,CAAC,CAAC,CAAC"}

package/dist/execution-target-sandbox.test.js

@@ -480,7 +480,7 @@ describe("sandbox adapter execution targets", () => {
             target: {
                 kind: "remote", transport: "sandbox", providerKey: "local-test", remoteCwd: rootDir,
                 runner: { execute: async (input) => {
-                        if (input.args?.[1]?.includes("command.b64.paperclip-upload.b64") && input.args[1].includes(">>")) {
+                        if (/command\.b64\.[^/]+\.paperclip-upload\.b64/.test(input.args?.[1] ?? "") && input.args[1].includes(">>")) {
                             throw new Error("Upload interrupted");
                         }
                         return delegate.execute(input);
@@ -1569,6 +1569,7 @@ describe("sandbox adapter execution targets", () => {
                     execs.push({
                         useSession: input.useSession,
                         bypassSession: input.bypassSession,
+                        timeoutMs: input.timeoutMs,
                         script: input.args?.[1] ?? "",
                     });
                     return delegate.execute(input);
@@ -1591,7 +1592,7 @@ describe("sandbox adapter execution targets", () => {
                 args: [childPath],
                 cwd: rootDir,
                 env: {},
-                timeoutSec: 5,
+                timeoutSec: 4 * 60 * 60,
                 onLog: async () => { },
                 streamOutputViaSession: true,
             });
@@ -1607,6 +1608,7 @@ describe("sandbox adapter execution targets", () => {
                 const sessionExecs = execs.filter((exec) => exec.useSession === true);
                 expect(sessionExecs).toHaveLength(1);
                 expect(sessionExecs[0].bypassSession).not.toBe(true);
+                expect(sessionExecs[0].timeoutMs).toBe(4 * 60 * 60 * 1000);
                 expect(sessionExecs[0].script).toContain("node ");
                 // Every other exec is bridge control-plane plumbing. Each must force
                 // itself off the persistent session so it never queues behind the agent
@@ -1615,6 +1617,7 @@ describe("sandbox adapter execution targets", () => {
                 expect(controlExecs.length).toBeGreaterThan(0);
                 for (const exec of controlExecs) {
                     expect(exec.bypassSession).toBe(true);
+                    expect(exec.timeoutMs).toBe(30_000);
                 }
             }
             finally {
@@ -1622,6 +1625,43 @@ describe("sandbox adapter execution targets", () => {
             }
         });
     });
+    it.each(["launch", "payload setup"])("bounds a hung process-session %s", async (stage) => {
+        vi.useFakeTimers();
+        try {
+            const runner = {
+                execute: vi.fn(async (input) => {
+                    const script = input.args?.[1] ?? "";
+                    if ((stage === "launch" && script.includes("nohup")) ||
+                        (stage === "payload setup" && script.startsWith("chmod 600"))) {
+                        return new Promise(() => { });
+                    }
+                    return {
+                        exitCode: 0, signal: null, timedOut: false, stdout: '{"uploaded":true}', stderr: "",
+                        pid: null, startedAt: new Date().toISOString(),
+                    };
+                }),
+            };
+            let error;
+            const operation = startAdapterExecutionTargetProcessSessionBridge({
+                runId: "run-hung-setup",
+                runtimeRootDir: "/workspace/runtime",
+                target: { kind: "remote", transport: "sandbox", remoteCwd: "/workspace", runner },
+                adapterKey: "acpx", command: "cat", args: [], cwd: "/workspace",
+                env: stage === "payload setup" ? { LARGE_VALUE: "x".repeat(70_000) } : {},
+                timeoutSec: 4 * 60 * 60,
+            }).catch((caught) => { error = caught; });
+            await vi.advanceTimersByTimeAsync(30_000);
+            expect(error).toEqual(new Error("Sandbox bridge control command timed out after 30000ms."));
+            await operation;
+            expect(runner.execute.mock.calls.filter(([input]) => input.args?.[1]?.includes("nohup")))
+                .toHaveLength(stage === "launch" ? 1 : 0);
+            expect(runner.execute).toHaveBeenLastCalledWith(expect.objectContaining({ timeoutMs: 30_000 }));
+            expect(vi.getTimerCount()).toBe(0);
+        }
+        finally {
+            vi.useRealTimers();
+        }
+    });
     it("applies the remote sandbox fallback when adapter timeoutSec is unset", () => {
         const sandboxTarget = {
             kind: "remote",
@@ -1629,9 +1669,8 @@ describe("sandbox adapter execution targets", () => {
             remoteCwd: "/workspace",
             runner: createLocalSandboxRunner(),
         };
-        // The sandbox default is a 4h wall-clock backstop matching the recovery
-        // watchdog critical threshold (ACTIVE_RUN_OUTPUT_CRITICAL_THRESHOLD_MS);
-        // the output-inactivity monitor remains the primary hang detector.
+        // The sandbox default stays at four hours independently of the earlier
+        // informational output-silence warnings and bridge control deadlines.
         expect(DEFAULT_REMOTE_SANDBOX_ADAPTER_TIMEOUT_SEC).toBe(4 * 60 * 60);
         expect(resolveAdapterExecutionTargetTimeoutSec(sandboxTarget, 0)).toBe(DEFAULT_REMOTE_SANDBOX_ADAPTER_TIMEOUT_SEC);
         expect(resolveAdapterExecutionTargetTimeoutSec(sandboxTarget, 90)).toBe(90);
@@ -2319,7 +2358,7 @@ describe("sandbox adapter execution targets", () => {
             await new Promise((resolve) => apiServer.close(() => resolve()));
         }
     });
-    it("uses the effective adapter timeout when starting the sandbox callback bridge", async () => {
+    it("bounds callback bridge operations independently of the adapter run timeout", async () => {
         const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-execution-target-bridge-timeout-"));
         cleanupDirs.push(rootDir);
         const remoteCwd = path.join(rootDir, "workspace");
@@ -2363,7 +2402,10 @@ describe("sandbox adapter execution targets", () => {
         try {
             expect(bridge).not.toBeNull();
             expect(runner.execute).toHaveBeenCalled();
-            expect(runner.execute.mock.calls.some(([input]) => input.timeoutMs === DEFAULT_REMOTE_SANDBOX_ADAPTER_TIMEOUT_SEC * 1000)).toBe(true);
+            for (const [input] of runner.execute.mock.calls) {
+                expect(input.timeoutMs).toBeGreaterThan(0);
+                expect(input.timeoutMs).toBeLessThanOrEqual(30_000);
+            }
         }
         finally {
             await bridge?.stop();