Skip to content

The open-source app everyone uses to manage agents at work

Avoid resuming stale remote sessions (Pi adapter) (#5120)

Devin Foley09eceb952af7
diff --git a/packages/adapters/pi-local/src/server/execute.remote.test.ts b/packages/adapters/pi-local/src/server/execute.remote.test.ts
index 9a36bad71d..140ec36659 100644
--- a/packages/adapters/pi-local/src/server/execute.remote.test.ts
+++ b/packages/adapters/pi-local/src/server/execute.remote.test.ts
@@ -221,6 +221,22 @@ describe("pi remote execution", () => {
const workspaceDir = path.join(rootDir, "workspace");
await mkdir(workspaceDir, { recursive: true });
+ runSshCommand.mockImplementation(async (...args: unknown[]) => {
+ const command = String(args[1] ?? "");
+ if (command.includes("head -n 1") && command.includes("session-123.jsonl")) {
+ return {
+ stdout: `${JSON.stringify({ type: "session", cwd: "/remote/workspace" })}\n`,
+ stderr: "",
+ exitCode: 0,
+ };
+ }
+ return {
+ stdout: "",
+ stderr: "",
+ exitCode: 0,
+ };
+ });
+
await execute({
runId: "run-ssh-resume",
agent: {
@@ -275,4 +291,218 @@ describe("pi remote execution", () => {
expect(call?.[2]).toContain("--session");
expect(call?.[2]).toContain("/remote/workspace/.paperclip-runtime/pi/sessions/session-123.jsonl");
});
+
+ it("starts a fresh remote Pi session when the saved session header cwd points at a different workspace", async () => {
+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-pi-remote-stale-session-"));
+ cleanupDirs.push(rootDir);
+ const workspaceDir = path.join(rootDir, "workspace");
+ await mkdir(workspaceDir, { recursive: true });
+
+ runSshCommand.mockImplementation(async (...args: unknown[]) => {
+ const command = String(args[1] ?? "");
+ if (command.includes("head -n 1") && command.includes("session-123.jsonl")) {
+ return {
+ stdout: `${JSON.stringify({ type: "session", cwd: "/remote/old-workspace" })}\n`,
+ stderr: "",
+ exitCode: 0,
+ };
+ }
+ return {
+ stdout: "",
+ stderr: "",
+ exitCode: 0,
+ };
+ });
+
+ await execute({
+ runId: "run-ssh-stale-session",
+ agent: {
+ id: "agent-1",
+ companyId: "company-1",
+ name: "Pi Builder",
+ adapterType: "pi_local",
+ adapterConfig: {},
+ },
+ runtime: {
+ sessionId: "/remote/workspace/.paperclip-runtime/pi/sessions/session-123.jsonl",
+ sessionParams: {
+ sessionId: "/remote/workspace/.paperclip-runtime/pi/sessions/session-123.jsonl",
+ cwd: "/remote/workspace",
+ remoteExecution: {
+ transport: "ssh",
+ host: "127.0.0.1",
+ port: 2222,
+ username: "fixture",
+ remoteCwd: "/remote/workspace",
+ },
+ },
+ sessionDisplayId: "session-123",
+ taskKey: null,
+ },
+ config: {
+ command: "pi",
+ model: "openai/gpt-5.4-mini",
+ },
+ context: {
+ paperclipWorkspace: {
+ cwd: workspaceDir,
+ source: "project_primary",
+ },
+ },
+ executionTransport: {
+ remoteExecution: {
+ host: "127.0.0.1",
+ port: 2222,
+ username: "fixture",
+ remoteWorkspacePath: "/remote/workspace",
+ remoteCwd: "/remote/workspace",
+ privateKey: "PRIVATE KEY",
+ knownHosts: "[127.0.0.1]:2222 ssh-ed25519 AAAA",
+ strictHostKeyChecking: true,
+ },
+ },
+ onLog: async () => {},
+ });
+
+ const call = runChildProcess.mock.calls[0] as unknown as [string, string, string[]] | undefined;
+ const sessionIndex = call?.[2].indexOf("--session") ?? -1;
+ expect(sessionIndex).toBeGreaterThanOrEqual(0);
+ const usedSession = sessionIndex >= 0 ? call?.[2][sessionIndex + 1] : null;
+ expect(usedSession).toContain("/remote/workspace/.paperclip-runtime/pi/sessions/");
+ expect(usedSession).not.toBe("/remote/workspace/.paperclip-runtime/pi/sessions/session-123.jsonl");
+ });
+
+ it("starts a fresh remote Pi session when the saved session header is empty or unreadable", async () => {
+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-pi-remote-empty-header-"));
+ cleanupDirs.push(rootDir);
+ const workspaceDir = path.join(rootDir, "workspace");
+ await mkdir(workspaceDir, { recursive: true });
+
+ runSshCommand.mockImplementation(async (...args: unknown[]) => {
+ const command = String(args[1] ?? "");
+ if (command.includes("head -n 1") && command.includes("session-123.jsonl")) {
+ return { stdout: "", stderr: "", exitCode: 0 };
+ }
+ return { stdout: "", stderr: "", exitCode: 0 };
+ });
+
+ await execute({
+ runId: "run-ssh-empty-header",
+ agent: {
+ id: "agent-1",
+ companyId: "company-1",
+ name: "Pi Builder",
+ adapterType: "pi_local",
+ adapterConfig: {},
+ },
+ runtime: {
+ sessionId: "/remote/workspace/.paperclip-runtime/pi/sessions/session-123.jsonl",
+ sessionParams: {
+ sessionId: "/remote/workspace/.paperclip-runtime/pi/sessions/session-123.jsonl",
+ cwd: "/remote/workspace",
+ remoteExecution: {
+ transport: "ssh",
+ host: "127.0.0.1",
+ port: 2222,
+ username: "fixture",
+ remoteCwd: "/remote/workspace",
+ },
+ },
+ sessionDisplayId: "session-123",
+ taskKey: null,
+ },
+ config: { command: "pi", model: "openai/gpt-5.4-mini" },
+ context: {
+ paperclipWorkspace: { cwd: workspaceDir, source: "project_primary" },
+ },
+ executionTransport: {
+ remoteExecution: {
+ host: "127.0.0.1",
+ port: 2222,
+ username: "fixture",
+ remoteWorkspacePath: "/remote/workspace",
+ remoteCwd: "/remote/workspace",
+ privateKey: "PRIVATE KEY",
+ knownHosts: "[127.0.0.1]:2222 ssh-ed25519 AAAA",
+ strictHostKeyChecking: true,
+ },
+ },
+ onLog: async () => {},
+ });
+
+ const call = runChildProcess.mock.calls[0] as unknown as [string, string, string[]] | undefined;
+ const sessionIndex = call?.[2].indexOf("--session") ?? -1;
+ expect(sessionIndex).toBeGreaterThanOrEqual(0);
+ const usedSession = sessionIndex >= 0 ? call?.[2][sessionIndex + 1] : null;
+ expect(usedSession).not.toBe("/remote/workspace/.paperclip-runtime/pi/sessions/session-123.jsonl");
+ });
+
+ it("starts a fresh remote Pi session when the remote head command fails", async () => {
+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-pi-remote-head-failure-"));
+ cleanupDirs.push(rootDir);
+ const workspaceDir = path.join(rootDir, "workspace");
+ await mkdir(workspaceDir, { recursive: true });
+
+ runSshCommand.mockImplementation(async (...args: unknown[]) => {
+ const command = String(args[1] ?? "");
+ if (command.includes("head -n 1") && command.includes("session-123.jsonl")) {
+ throw Object.assign(new Error("ssh: connect failed"), {
+ stdout: "",
+ stderr: "ssh: connect failed",
+ code: "ENOENT",
+ });
+ }
+ return { stdout: "", stderr: "", exitCode: 0 };
+ });
+
+ await execute({
+ runId: "run-ssh-head-failure",
+ agent: {
+ id: "agent-1",
+ companyId: "company-1",
+ name: "Pi Builder",
+ adapterType: "pi_local",
+ adapterConfig: {},
+ },
+ runtime: {
+ sessionId: "/remote/workspace/.paperclip-runtime/pi/sessions/session-123.jsonl",
+ sessionParams: {
+ sessionId: "/remote/workspace/.paperclip-runtime/pi/sessions/session-123.jsonl",
+ cwd: "/remote/workspace",
+ remoteExecution: {
+ transport: "ssh",
+ host: "127.0.0.1",
+ port: 2222,
+ username: "fixture",
+ remoteCwd: "/remote/workspace",
+ },
+ },
+ sessionDisplayId: "session-123",
+ taskKey: null,
+ },
+ config: { command: "pi", model: "openai/gpt-5.4-mini" },
+ context: {
+ paperclipWorkspace: { cwd: workspaceDir, source: "project_primary" },
+ },
+ executionTransport: {
+ remoteExecution: {
+ host: "127.0.0.1",
+ port: 2222,
+ username: "fixture",
+ remoteWorkspacePath: "/remote/workspace",
+ remoteCwd: "/remote/workspace",
+ privateKey: "PRIVATE KEY",
+ knownHosts: "[127.0.0.1]:2222 ssh-ed25519 AAAA",
+ strictHostKeyChecking: true,
+ },
+ },
+ onLog: async () => {},
+ });
+
+ const call = runChildProcess.mock.calls[0] as unknown as [string, string, string[]] | undefined;
+ const sessionIndex = call?.[2].indexOf("--session") ?? -1;
+ expect(sessionIndex).toBeGreaterThanOrEqual(0);
+ const usedSession = sessionIndex >= 0 ? call?.[2][sessionIndex + 1] : null;
+ expect(usedSession).not.toBe("/remote/workspace/.paperclip-runtime/pi/sessions/session-123.jsonl");
+ });
});
diff --git a/packages/adapters/pi-local/src/server/execute.ts b/packages/adapters/pi-local/src/server/execute.ts
index 1d1172b701..f0b659b889 100644
--- a/packages/adapters/pi-local/src/server/execute.ts
+++ b/packages/adapters/pi-local/src/server/execute.ts
@@ -17,6 +17,7 @@ import {
readAdapterExecutionTarget,
resolveAdapterExecutionTargetCommandForLogs,
runAdapterExecutionTargetProcess,
+ runAdapterExecutionTargetShellCommand,
startAdapterExecutionTargetPaperclipBridge,
} from "@paperclipai/adapter-utils/execution-target";
import {
@@ -41,6 +42,7 @@ import {
DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE,
runChildProcess,
} from "@paperclipai/adapter-utils/server-utils";
+import { shellQuote } from "@paperclipai/adapter-utils/ssh";
import { isPiUnknownSessionError, parsePiJsonl } from "./parse.js";
import { ensurePiModelConfiguredAndAvailable } from "./models.js";
@@ -143,6 +145,68 @@ function buildRemoteSessionPath(runtimeRootDir: string, agentId: string, timesta
return path.posix.join(runtimeRootDir, "sessions", `${safeTimestamp}-${agentId}.jsonl`);
}
+function normalizeExecutionCwd(candidate: string, remote: boolean): string {
+ return remote ? path.posix.normalize(candidate) : path.resolve(candidate);
+}
+
+function executionCwdsMatch(saved: string, current: string, remote: boolean): boolean {
+ return normalizeExecutionCwd(saved, remote) === normalizeExecutionCwd(current, remote);
+}
+
+function readSessionHeaderCwd(raw: string): string | null {
+ const headerLine = raw
+ .split(/\r?\n/)
+ .map((line) => line.trim())
+ .find(Boolean);
+ if (!headerLine) return null;
+ try {
+ const parsed = JSON.parse(headerLine) as Record<string, unknown>;
+ if (parsed.type !== "session") return null;
+ const cwd = typeof parsed.cwd === "string" ? parsed.cwd.trim() : "";
+ return cwd.length > 0 ? cwd : null;
+ } catch {
+ return null;
+ }
+}
+
+async function readSavedSessionCwd(input: {
+ runId: string;
+ sessionPath: string;
+ executionTarget: ReturnType<typeof readAdapterExecutionTarget>;
+ cwd: string;
+ env: Record<string, string>;
+ timeoutSec: number;
+ graceSec: number;
+}): Promise<string | null> {
+ if (!input.sessionPath.trim()) return null;
+
+ if (!adapterExecutionTargetIsRemote(input.executionTarget)) {
+ try {
+ return readSessionHeaderCwd(await fs.readFile(input.sessionPath, "utf8"));
+ } catch {
+ return null;
+ }
+ }
+
+ try {
+ const sessionHeader = await runAdapterExecutionTargetShellCommand(
+ input.runId,
+ input.executionTarget,
+ `if [ -f ${shellQuote(input.sessionPath)} ]; then head -n 1 ${shellQuote(input.sessionPath)}; fi`,
+ {
+ cwd: input.cwd,
+ env: input.env,
+ timeoutSec: input.timeoutSec > 0 ? Math.min(input.timeoutSec, 15) : 15,
+ graceSec: input.graceSec,
+ },
+ );
+ if (sessionHeader.timedOut || (sessionHeader.exitCode ?? 0) !== 0) return null;
+ return readSessionHeaderCwd(sessionHeader.stdout);
+ } catch {
+ return null;
+ }
+}
+
export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecutionResult> {
const { runId, agent, runtime, config, context, onLog, onMeta, onSpawn, authToken } = ctx;
const executionTarget = readAdapterExecutionTarget({
@@ -373,10 +437,31 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
const runtimeSessionId = asString(runtimeSessionParams.sessionId, runtime.sessionId ?? "");
const runtimeSessionCwd = asString(runtimeSessionParams.cwd, "");
const runtimeRemoteExecution = parseObject(runtimeSessionParams.remoteExecution);
+ const sessionTargetMatches = adapterExecutionTargetSessionMatches(runtimeRemoteExecution, executionTarget);
+ const sessionParamsCwdMatches =
+ runtimeSessionCwd.length === 0 ||
+ executionCwdsMatch(runtimeSessionCwd, effectiveExecutionCwd, executionTargetIsRemote);
+ const savedSessionCwd =
+ runtimeSessionId.length > 0
+ ? await readSavedSessionCwd({
+ runId,
+ sessionPath: runtimeSessionId,
+ executionTarget,
+ cwd,
+ env,
+ timeoutSec,
+ graceSec,
+ })
+ : null;
+ const sessionHeaderCwdMatches =
+ runtimeSessionId.length === 0 ||
+ (savedSessionCwd !== null &&
+ executionCwdsMatch(savedSessionCwd, effectiveExecutionCwd, executionTargetIsRemote));
const canResumeSession =
runtimeSessionId.length > 0 &&
- (runtimeSessionCwd.length === 0 || path.resolve(runtimeSessionCwd) === path.resolve(effectiveExecutionCwd)) &&
- adapterExecutionTargetSessionMatches(runtimeRemoteExecution, executionTarget);
+ sessionTargetMatches &&
+ sessionParamsCwdMatches &&
+ sessionHeaderCwdMatches;
const sessionPath = canResumeSession
? runtimeSessionId
: executionTargetIsRemote && remoteRuntimeRootDir
@@ -384,11 +469,15 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
: buildSessionPath(agent.id, new Date().toISOString());
if (runtimeSessionId && !canResumeSession) {
+ const staleSessionCwdNote =
+ savedSessionCwd !== null && !sessionHeaderCwdMatches
+ ? ` Pi stored cwd "${savedSessionCwd}" in the session header, so Paperclip will start a fresh session for "${effectiveExecutionCwd}".`
+ : "";
await onLog(
"stdout",
executionTargetIsRemote
- ? `[paperclip] Pi session "${runtimeSessionId}" does not match the current remote execution identity and will not be resumed in "${effectiveExecutionCwd}". Starting a fresh remote session.\n`
- : `[paperclip] Pi session "${runtimeSessionId}" was saved for cwd "${runtimeSessionCwd}" and will not be resumed in "${effectiveExecutionCwd}".\n`,
+ ? `[paperclip] Pi session "${runtimeSessionId}" does not match the current remote execution state and will not be resumed in "${effectiveExecutionCwd}".${staleSessionCwdNote} Starting a fresh remote session.\n`
+ : `[paperclip] Pi session "${runtimeSessionId}" was saved for cwd "${runtimeSessionCwd}" and will not be resumed in "${effectiveExecutionCwd}".${staleSessionCwdNote}\n`,
);
}