The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
refactor(heartbeat): extract instruction working-copy lifecycle (#15984)
Dottace08872dfb54
diff --git a/doc/DEVELOPING.md b/doc/DEVELOPING.mdindex 48e7704aaa..441b13685a 100644--- a/doc/DEVELOPING.md+++ b/doc/DEVELOPING.md@@ -1284,6 +1284,14 @@ services and primary URLs, and posts workspace-ready notices. Process registriesand leases stay in `workspace-runtime.ts`; the executor keeps release ordering inits existing cleanup path. Public-path tests use real local service processes.+Instruction working-copy coordination is in+`server/src/services/heartbeat/instruction-working-copy.ts`. Its per-run controller+prepares copies, tracks save receipts, and coordinates warm-directory handoffs.+Live getters preserve updated copies and expose acquired reservations even if+preparation fails. The executor keeps release and environment-cleanup ordering;+a separate release closure defers cleanup failures without replacing run results.+See `tests/e2e/instruction-working-copy/README.md` for isolated browser acceptance.+Task assignment Markdown is rendered by `server/src/services/heartbeat/task-markdown.ts`.`heartbeat.ts` re-exports it for existing callers. Keep promptformatting changes in the renderer and its tests, separate from run orchestration.diff --git a/server/src/__tests__/heartbeat-instruction-working-copy.test.ts b/server/src/__tests__/heartbeat-instruction-working-copy.test.tsnew file mode 100644index 0000000000..8af787a548--- /dev/null+++ b/server/src/__tests__/heartbeat-instruction-working-copy.test.ts@@ -0,0 +1,159 @@+import { randomUUID } from "node:crypto";+import fs from "node:fs/promises";+import os from "node:os";+import path from "node:path";+import { eq } from "drizzle-orm";+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";+import { agents, authUsers, companies, companyMemberships, createDb, heartbeatRuns, heartbeatRunEvents, issues, principalPermissionGrants } from "@paperclipai/db";+import { registerServerAdapter, unregisterServerAdapter } from "../adapters/index.js";+import { heartbeatService } from "../services/heartbeat.js";+import { resolveManagedInstructionsRoot } from "../services/agent-instructions.js";+import { getEmbeddedPostgresTestSupport, startEmbeddedPostgresTestDatabase } from "./helpers/embedded-postgres.js";++const cleanup = vi.hoisted(() => ({ failures: new Set<string>(), revocations: new Set<string>(), attempts: new Map<string, number>() }));+vi.mock("../services/agent-instruction-working-copies.js", async importOriginal => {+ const actual = await importOriginal<typeof import("../services/agent-instruction-working-copies.js")>();+ return { ...actual, agentInstructionWorkingCopyService: (...args: Parameters<typeof actual.agentInstructionWorkingCopyService>) => {+ const copies = actual.agentInstructionWorkingCopyService(...args);+ return { ...copies, prepare: async (input: Parameters<typeof copies.prepare>[0]) => {+ if (cleanup.revocations.has(input.companyId)) {+ await args[0].update(companyMemberships).set({ status: "suspended" }).where(eq(companyMemberships.companyId, input.companyId));+ }+ return copies.prepare(input);+ }, release: async (companyId: string, runId: string) => {+ cleanup.attempts.set(runId, (cleanup.attempts.get(runId) ?? 0) + 1);+ if (cleanup.failures.has(companyId)) throw new Error("Fixture cleanup unavailable");+ return copies.release(companyId, runId);+ } };+ } };+});++const support = await getEmbeddedPostgresTestSupport();+const describePostgres = support.supported ? describe : describe.skip;+if (!support.supported) console.warn(`Skipping heartbeat instruction copies tests: ${support.reason}`);++describePostgres("heartbeat instruction working-copy lifecycle", () => {+ const adapterType = "instruction_working_copy_test";+ const entryFile = "policy/INSTRUCTIONS.txt";+ const initial = "\uFEFF# Original\r\n☃\n", edited = "\uFEFF# Saved\r\nKeep across runs. ☃\n";+ const previousHome = process.env.PAPERCLIP_HOME;+ let home: string;+ let temporary: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>>;+ let db: ReturnType<typeof createDb>;+ let heartbeat: ReturnType<typeof heartbeatService>;+ const captured = new Map<string, { instructionPath: string | null; before: string | null; context: Record<string, unknown> }>();+ const failures = new Set<string>();++ beforeAll(async () => {+ home = await fs.realpath(await fs.mkdtemp(path.join(os.tmpdir(), "heartbeat-instruction-copies-")));+ process.env.PAPERCLIP_HOME = home;+ temporary = await startEmbeddedPostgresTestDatabase("heartbeat-instruction-copies-db-");+ db = createDb(temporary.connectionString);+ heartbeat = heartbeatService(db);+ registerServerAdapter({+ type: adapterType, supportsLocalAgentJwt: false, supportsInstructionsBundle: true,+ execute: async input => {+ const instructionPath = typeof input.config.instructionsFilePath === "string" ? input.config.instructionsFilePath : null;+ captured.set(input.runId, { instructionPath, before: instructionPath ? await fs.readFile(instructionPath, "utf8") : null, context: structuredClone(input.context) });+ if (instructionPath) await fs.writeFile(instructionPath, edited);+ await db.update(issues).set({ status: "in_review" }).where(eq(issues.id, String(input.context.issueId)));+ await input.onProviderStopped?.();+ if (failures.has(input.agent.id)) throw new Error("Invalid fixture adapter configuration");+ return { exitCode: 0, signal: null, timedOut: false, resultJson: {} };+ },+ testEnvironment: async () => ({ adapterType, status: "pass", checks: [], testedAt: new Date().toISOString() }),+ });+ }, 30_000);++ afterAll(async () => {+ await heartbeat?.drainActiveRunExecutions();+ unregisterServerAdapter(adapterType);+ await db?.$client.end({ timeout: 0 });+ await temporary?.cleanup();+ if (previousHome === undefined) delete process.env.PAPERCLIP_HOME; else process.env.PAPERCLIP_HOME = previousHome;+ if (home) {+ const makeRemovable = async (directory: string): Promise<void> => {+ await fs.chmod(directory, 0o700);+ for (const child of await fs.readdir(directory, { withFileTypes: true })) if (child.isDirectory()) await makeRemovable(path.join(directory, child.name));+ };+ await makeRemovable(home);+ await fs.rm(home, { recursive: true, force: true });+ }+ });++ async function seed() {+ const companyId = randomUUID(), agentId = randomUUID(), issueId = randomUUID(), userId = randomUUID();+ await db.insert(companies).values({ id: companyId, name: "Instruction lifecycle fixture", issuePrefix: `I${companyId.slice(0, 6)}` });+ await db.insert(authUsers).values({ id: userId, name: "Editor", email: `${userId}@example.test`, createdAt: new Date(), updatedAt: new Date() });+ await db.insert(companyMemberships).values({ companyId, principalType: "user", principalId: userId, membershipRole: "operator" });+ await db.insert(principalPermissionGrants).values({ companyId, principalType: "user", principalId: userId, permissionKey: "agents:configure", scope: { agentIds: [agentId] } });+ const root = resolveManagedInstructionsRoot({ companyId, id: agentId, name: "Editor", adapterConfig: {} });+ await fs.mkdir(path.dirname(path.join(root, entryFile)), { recursive: true });+ await fs.writeFile(path.join(root, entryFile), initial);+ const cwd = await fs.mkdtemp(path.join(home, "workspace-"));+ await db.insert(agents).values({ id: agentId, companyId, name: "Editor", adapterType, status: "idle", adapterConfig: { cwd, instructionsBundleMode: "managed", instructionsRootPath: root, instructionsEntryFile: entryFile } });+ await db.insert(companyMemberships).values({ companyId, principalType: "agent", principalId: agentId, membershipRole: "member" });+ await db.insert(issues).values({ id: issueId, companyId, title: "Save agent instructions", status: "todo", assigneeAgentId: agentId, responsibleUserId: userId, issueNumber: 1 });+ return { companyId, agentId, issueId, root };+ }++ async function execute(f: Awaited<ReturnType<typeof seed>>) {+ const run = await heartbeat.wakeup(f.agentId, { source: "on_demand", triggerDetail: "manual", reason: "manual", payload: { issueId: f.issueId }, contextSnapshot: { issueId: f.issueId } });+ expect(run).not.toBeNull();+ await heartbeat.drainActiveRunExecutions();+ const [finished] = await db.select().from(heartbeatRuns).where(eq(heartbeatRuns.id, run!.id));+ const events = await db.select().from(heartbeatRunEvents).where(eq(heartbeatRunEvents.runId, run!.id));+ return { finished: finished!, events, input: captured.get(run!.id)! };+ }++ it("dispatches a private copy, saves exact bytes on provider stop, and restores them on the next run", async () => {+ const f = await seed();+ const first = await execute(f);+ expect(first.finished.status, first.finished.error ?? undefined).toBe("succeeded");+ expect(first.input.before).toBe(initial);+ expect(first.input.instructionPath).not.toBe(path.join(f.root, entryFile));+ expect(first.input.context.paperclipTaskMarkdown).toContain("Your persistent agent directory is");+ expect(first.finished.resultJson?.instructionSave).toMatchObject({ state: "saved", contract: "agent_files", entryFile });+ expect(first.events.some(event => event.eventType === "instruction_save" && event.payload?.state === "saved")).toBe(true);+ expect(await fs.readFile(path.join(f.root, entryFile), "utf8")).toBe(edited);+ await expect(fs.stat(first.input.instructionPath!)).rejects.toMatchObject({ code: "ENOENT" });+ const second = await execute(f);+ expect(second.finished.status, second.finished.error ?? undefined).toBe("succeeded");+ expect(second.input.before).toBe(edited);+ expect(second.finished.resultJson?.instructionSave).toMatchObject({ state: "unchanged" });+ });++ it("continues without a copy or save claim when access is revoked after dispatch admission", async () => {+ const f = await seed();+ cleanup.revocations.add(f.companyId);+ const { finished, input, events } = await execute(f);+ expect(finished.status, finished.error ?? undefined).toBe("succeeded");+ expect(input.instructionPath).toBeNull();+ expect(input.context.paperclipTaskMarkdown).toContain("No editable agent instruction working copy is registered");+ expect(finished.resultJson?.instructionSave).toBeUndefined();+ expect(events.some(event => event.eventType === "instruction_save" && event.payload?.state === "unavailable")).toBe(true);+ expect(await fs.readFile(path.join(f.root, entryFile), "utf8")).toBe(initial);+ });++ it("keeps the successful save and result when cleanup fails, without repeating that failure in outer teardown", async () => {+ const f = await seed();+ cleanup.failures.add(f.companyId);+ const { finished, events } = await execute(f);+ expect(finished.status, finished.error ?? undefined).toBe("succeeded");+ expect(finished.resultJson?.instructionSave).toMatchObject({ state: "saved" });+ expect(await fs.readFile(path.join(f.root, entryFile), "utf8")).toBe(edited);+ expect(cleanup.attempts.get(finished.id)).toBe(1);+ expect(events.filter(event => event.eventType === "instruction_cleanup")).toEqual([expect.objectContaining({ level: "warn", payload: { state: "deferred" } })]);+ });++ it("preserves stopped-provider edits and releases the copy even if adapter dispatch then fails", async () => {+ const f = await seed();+ failures.add(f.agentId);+ const { finished, input, events } = await execute(f);+ expect(finished.status).toBe("failed");+ expect(finished.error).toContain("Invalid fixture adapter configuration");+ expect(events.some(event => event.eventType === "instruction_save" && event.payload?.state === "saved")).toBe(true);+ expect(await fs.readFile(path.join(f.root, entryFile), "utf8")).toBe(edited);+ await expect(fs.stat(input.instructionPath!)).rejects.toMatchObject({ code: "ENOENT" });+ });+});diff --git a/server/src/services/heartbeat.ts b/server/src/services/heartbeat.tsindex 1f62017a68..db99e407a3 100644--- a/server/src/services/heartbeat.ts+++ b/server/src/services/heartbeat.ts@@ -1,3 +1,4 @@+import { createHeartbeatInstructionCopyRelease, createHeartbeatInstructionWorkingCopy } from "./heartbeat/instruction-working-copy.js";import { prepareHeartbeatRuntimeServiceIntents, startHeartbeatRuntimeServices, recordHeartbeatAdapterRuntimeServices } from "./heartbeat/runtime-services.js";import { prepareHeartbeatExecutionConfiguration } from "./heartbeat/execution-configuration.js";import { createHeartbeatRunOutput } from "./heartbeat/run-output.js";@@ -216,7 +217,6 @@ import {import {prepareChatCompletionTurn,} from "./chat-completion-delivery.js";-import { AgentDirectoryReuseInvalidatedError, isAgentDirectoryCopy } from "./agent-directory-working-copies.js";import {NativeWorkspaceFinalizationBusyError,@@ -283,15 +283,12 @@ import {prepareGitHubExecutionEnvironment,startAdapterExecutionTargetPaperclipBridge,} from "@paperclipai/adapter-utils/execution-target";-import { agentInstructionWorkingCopyService, collectStoppedInstructionCopyWithRetries, instructionWorkingCopyGuidance } from "./agent-instruction-working-copies.js";+import { agentInstructionWorkingCopyService } from "./agent-instruction-working-copies.js";import fs from "node:fs/promises";import path from "node:path";import { execFile as execFileCallback } from "node:child_process";import { promisify } from "node:util";-import {- createHash,-} from "node:crypto";import {and,eq,@@ -336,9 +333,6 @@ import {} from "./issue-queued-comment-queue.js";import {- claimWarmNativeInstructionCopy,- nativeSessionWorkspaceScope,- reserveWarmNativeInstructionDirectory,dispatchNativeSessionResumptions,NativeCancellationPendingRecoveryError,NativeControllerDetachedForRestartError,@@ -348,7 +342,6 @@ import {} from "./native-runtime/index.js";import {- parseNativeExecutionInput,type NativeExecutionInput,type NativeSessionBackend,} from "../vendor/paperclip-runner/index.js";@@ -1855,29 +1848,7 @@ export function heartbeatService(run = claimed;}- const instructionCleanupRun = run;- let instructionCleanupDeferred = false;- const releaseInstructionCopy = async () => {- // Cleanup is retried from the durable working-copy receipt by the- // recovery sweep. It must not replace the provider result (or prevent- // lease release), and a timeout must not be repeated in outer teardown.- if (instructionCleanupDeferred) return;- try {- await instructionCopies.release(instructionCleanupRun.companyId, instructionCleanupRun.id);- } catch (err) {- instructionCleanupDeferred = true;- logger.warn({ err, runId: instructionCleanupRun.id }, "Agent file cleanup deferred; run outcome preserved");- await appendRunEvent(instructionCleanupRun, {- eventType: "instruction_cleanup",- stream: "system",- level: "warn",- message: "Agent file cleanup was deferred. The run outcome and file-save receipt are unchanged.",- payload: { state: "deferred" },- }).catch((eventError) => {- logger.warn({ err: eventError, runId: instructionCleanupRun.id }, "Failed to record deferred agent file cleanup");- });- }- };+ const releaseInstructionCopy = createHeartbeatInstructionCopyRelease(run, instructionCopies, appendRunEvent);if (runOptions.nativeLeaseOwner &&@@ -1978,8 +1949,7 @@ export function heartbeatService(Parameters<typeof cleanupGitHubOperationLaunchers>[0] | null = null;let nativeSessionResumeScheduled = false;let nativeOwnershipHeld = false;- let releaseWarmInstructionPreparation: (() => Promise<void>) | null = null;- let nativeInstructionReservation: Awaited<ReturnType<typeof reserveWarmNativeInstructionDirectory>> = null;+ let instructionWorkingCopy: ReturnType<typeof createHeartbeatInstructionWorkingCopy> | null = null;let nativeDispatchStarted = false;let nativeWorkspaceFinalizeScheduled = false;let nativeWorkspaceSync: Awaited<@@ -2740,49 +2710,12 @@ export function heartbeatService(appendRunEvent,},});- let instructionCopy: Awaited<ReturnType<typeof instructionCopies.prepare>> = null;- let instructionSave: Record<string, unknown> | null = null;- const instructionPreparationKey = createHash("sha256").update(JSON.stringify({- adapterType: agent.adapterType, adapterConfig: agent.adapterConfig, runtimeConfig: agent.runtimeConfig, sessionConfigMetadata,- workspace: nativeSessionWorkspaceScope({- binding: { runId: run.id, executionWorkspaceId: persistedExecutionWorkspace?.id ?? run.id },- workspace: executionWorkspace,- }), cwd: executionWorkspace.cwd,- })).digest("hex");- const recordInstructionSave = async (saved: NonNullable<Awaited<ReturnType<typeof instructionCopies.get>>>) => {- const receipt = parseObject(saved.receipt);- const storageWarning = readNonEmptyString(receipt.storageWarning);- const state = saved.errorCode === "AGENT_FILES_CHECKPOINT_UNSTABLE" ? "pending_collection"- : saved.state === "warm_saved" ? readNonEmptyString(receipt.checkpointState) ?? "saved" : saved.state;- instructionSave = { state, entryFile: saved.entryFile,- ...(isAgentDirectoryCopy(saved) ? { contract: "agent_files", appliedCandidateHash: saved.candidateHash, checkpointStats: receipt.checkpointStats }- : { revisionId: parseObject(receipt.revision).id ?? null }), storageWarning, errorCode: saved.errorCode, errorMessage: saved.errorMessage };- await appendRunEvent(run, { eventType: "instruction_save", stream: "system",- level: !saved.errorCode && !storageWarning && ["saved", "unchanged", "resolved"].includes(state) ? "info" : "warn",- message: storageWarning ?? (state === "saved" ? "Agent files saved."- : state === "unchanged" ? "Instruction working copy is unchanged."- : saved.errorMessage ?? "Instruction edits were not saved."), payload: instructionSave });- };- const collectStoppedInstructions = async () => {- if (!instructionCopy) return;- const saved = await collectStoppedInstructionCopyWithRetries(() => instructionCopies.collectStopped({- companyId: agent.companyId, runId: run.id, target: executionTarget,- }));- if (!saved) return;- if (saved.state !== "superseded") await recordInstructionSave(saved);- };- const nativeInstructionWorkingCopy = () => instructionCopy ? {- ...(isAgentDirectoryCopy(instructionCopy) ? { runId: run.id, preparationKey: instructionPreparationKey } : {}),- root: instructionCopy.executionRoot,- ...(instructionCopy.receipt?.warm === true ? { checkpointWarm: async () => {- const saved = await instructionCopies.checkpointWarm({ companyId: agent.companyId, runId: run.id, target: executionTarget });- if (saved) await recordInstructionSave(saved);- return saved?.state === "warm_saved" && saved.errorCode === null;- } } : {}),- hasChanges: () => instructionCopies.hasChanges({ companyId: agent.companyId, runId: run.id, target: executionTarget }),- collectStopped: collectStoppedInstructions,- retirementFailed: async () => { await instructionCopies.reportRetirementUnconfirmed(agent.companyId, run.id); },- } : undefined;+ const preparedInstructions = instructionWorkingCopy = createHeartbeatInstructionWorkingCopy({+ db, instructionCopies, readRun: () => run!, agent, context,+ session: { taskSession, taskSessionForRun, sessionConfigMetadata },+ workspace: { executionTarget, executionWorkspace, persistedExecutionWorkspace },+ appendRunEvent,+ });if (managedAiRuntime && aiBinding) {try { await assertManagedAiProjectAuth({ ...resolvedConfig, cwd: executionWorkspace.cwd }, aiBinding.provider, executionTarget); }catch { throw new ConfigurationIncompleteFailure("Project authentication conflicts with this agent’s managed AI connection", { configurationIncomplete: { reason: "ai_connection_incompatible", actionUrl: `/agents/${agent.id}/runtime` } }); }@@ -3287,100 +3220,7 @@ export function heartbeatService(const hasInstructionFilesystem = nativeRuntimeResolution.kind !== "native"? adapter.supportsInstructionsBundle === true: !["claude_managed_agents_api", "aws_agentcore_harness_api", "openai_dot_mcp"].includes(nativeRuntimeResolution.profile.backend);- if (hasInstructionFilesystem) {- try {- // Missing contract fields on a restored session mean the deployed- // legacy format. New sessions opt into whole-directory persistence.- const priorFileRun = taskSession?.lastRunId- ? await db.select({ profile: heartbeatRuns.runnerProfileJson }).from(heartbeatRuns).where(and(- eq(heartbeatRuns.id, taskSession.lastRunId), eq(heartbeatRuns.companyId, agent.companyId), eq(heartbeatRuns.agentId, agent.id))).then(rows => rows[0])- : null;- const savedFileInput = parseObject(parseObject(run.runnerProfileJson).nativeExecutionInput);- const priorFileInput = Object.keys(savedFileInput).length ? savedFileInput : parseObject(parseObject(priorFileRun?.profile).nativeExecutionInput);- const priorWorkingCopy = parseObject(parseObject(parseObject(priorFileInput.runtimeContext).instructions).workingCopy);- const warmFiles = nativeRuntimeResolution.kind === "native" && (nativeRuntimeResolution.profile.backend === "codex_app_server" ||- (nativeRuntimeResolution.profile.backend === "acpx_runtime" && parseObject(agent.adapterConfig).acpxAgent === "cursor")) &&- (executionTarget?.kind === "remote" && executionTarget.transport === "sandbox"- ? executionTarget.runnerLifecyclePolicy?.mode === "warm"- : parseObject(agent.adapterConfig).lifecycleMode === "warm");- if (warmFiles && taskSessionForRun?.lastRunId) {- nativeInstructionReservation = await reserveWarmNativeInstructionDirectory({ companyId: agent.companyId, agentId: agent.id,- previousRunId: taskSessionForRun.lastRunId, runId: run.id, target: executionTarget,- canReuse: () => instructionCopies.canReuseWarm(agent.companyId, agent.id, taskSessionForRun!.lastRunId!),- });- }- if (!warmFiles && nativeRuntimeResolution.kind === "native" && priorWorkingCopy.kind === "agent_files" && taskSession) {- releaseWarmInstructionPreparation = await claimWarmNativeInstructionCopy({- priorExecution: parseNativeExecutionInput(priorFileInput), companyId: agent.companyId, agentId: agent.id,- executionWorkspaceId: persistedExecutionWorkspace?.id ?? run.id, workspace: executionWorkspace,- environmentId: executionTarget?.environmentId ?? null, runId: run.id, preparationKey: instructionPreparationKey, forceRetirement: !taskSessionForRun,- adopt: async previousRunId => {- instructionCopy = await instructionCopies.adopt({ companyId: agent.companyId, agentId: agent.id,- runId: run.id, previousRunId, target: executionTarget, cwd: executionWorkspace.cwd, allowRetirementHandoff: true });- return nativeInstructionWorkingCopy() ?? null;- },- });- // A collection-only handoff was retired. Re-enter normal- // preparation instead of composing a root already collected.- if (!releaseWarmInstructionPreparation) instructionCopy = null;- }- const prepareInstructions = (reuseRunId?: string) => instructionCopies.prepare({- companyId: agent.companyId, agentId: agent.id, runId: run.id,- target: executionTarget, cwd: executionWorkspace.cwd,- legacy: Object.keys(priorFileInput).length > 0 && priorWorkingCopy.kind !== "agent_files",- warm: warmFiles, reuseRunId,- onWarmHandoff: copy => {- instructionCopy = copy;- nativeInstructionReservation?.adopt(copy.executionRoot, collectStoppedInstructions);- },- });- try {- instructionCopy ??= await prepareInstructions(nativeInstructionReservation?.reuseRunId);- } catch (error) {- if (!(error instanceof AgentDirectoryReuseInvalidatedError)) throw error;- // prepare has released its canonical lock. Retirement can now- // collect under that same lock before a fresh restore starts.- await nativeInstructionReservation?.release();- nativeInstructionReservation = null;- instructionCopy = await prepareInstructions();- }- } catch (error) {- if ((error as { status?: number }).status !== 403) throw error;- // Missing write identity must not break a background run's read-only- // prompt. It must also never imply that ordinary file edits will save.- await appendRunEvent(run, { eventType: "instruction_save", stream: "system", level: "warn",- message: "Persistent instruction editing is unavailable. Use an authenticated user with instruction edit access and a managed instruction bundle.",- payload: { state: "unavailable", code: "INSTRUCTION_COPY_UNAVAILABLE" } });- const guidance = "No editable agent instruction working copy is registered for this turn. Use authenticated agent file tools for persistent edits; do not edit a private copy named in an earlier turn or claim its changes will persist.";- for (const key of ["paperclipTaskMarkdown", "paperclipTaskMarkdownCompact"]) {- context[key] = [readNonEmptyString(context[key]), guidance].filter(Boolean).join("\n\n");- }- }- if (instructionCopy) {- const storageWarning = readNonEmptyString(instructionCopy.receipt?.storageWarning);- if (storageWarning) {- instructionSave = { state: "prepared", contract: "agent_files", storageWarning };- // This is an advisory on the run, never an agent pause, execution- // failure, or scheduling gate. Keep it visible while work runs.- await db.update(heartbeatRuns).set({ resultJson: sql`coalesce(${heartbeatRuns.resultJson}, '{}'::jsonb) || ${JSON.stringify({ instructionSave })}::jsonb` }).where(eq(heartbeatRuns.id, run.id));- await appendRunEvent(run, { eventType: "instruction_save", stream: "system", level: "warn",- message: storageWarning, payload: instructionSave });- }- runtimeConfig = { ...runtimeConfig, instructionsFilePath: path.join(instructionCopy.localRoot, instructionCopy.entryFile) };- if (isAgentDirectoryCopy(instructionCopy)) {- const workspace = parseObject(context.paperclipWorkspace);- context.paperclipWorkspace = { ...workspace, agentHome: instructionCopy.executionRoot,- // Keep the pre-existing permission root stable for ACP session- // identity. The per-run copy is already under the company root.- agentHomeForPermissions: workspace.agentHome,- };- }- const guidance = instructionWorkingCopyGuidance(instructionCopy);- for (const key of ["paperclipTaskMarkdown", "paperclipTaskMarkdownCompact"]) {- context[key] = [readNonEmptyString(context[key]), guidance].filter(Boolean).join("\n\n");- }- }- }+ runtimeConfig = await preparedInstructions.prepare({ runtimeConfig, nativeRuntimeResolution, hasInstructionFilesystem });const runtimeSelection = await selectHeartbeatRuntime(db, {run,agent,@@ -3416,7 +3256,7 @@ export function heartbeatService(runtimeConfig,runtimeSkillEntries,runScopedMentionedSkillKeys,- instructionCopy,+ instructionCopy: preparedInstructions.instructionCopy,agentIdentity,issueAssigneeOverrides,resolvedConfig,@@ -3490,12 +3330,12 @@ export function heartbeatService(goalCheckpointSession,},instructions: {- nativeInstructionWorkingCopy,- collectStoppedInstructions,- nativeInstructionReservation,+ nativeInstructionWorkingCopy: preparedInstructions.nativeInstructionWorkingCopy,+ collectStoppedInstructions: preparedInstructions.collectStoppedInstructions,+ nativeInstructionReservation: preparedInstructions.nativeInstructionReservation,releaseInstructionCopy,- get instructionCopy() { return instructionCopy; },- getInstructionSave: () => instructionSave,+ get instructionCopy() { return preparedInstructions.instructionCopy; },+ getInstructionSave: preparedInstructions.getInstructionSave,},trace: {providerTraceCapture,@@ -3764,7 +3604,7 @@ export function heartbeatService(});}} finally {- await nativeInstructionReservation?.release().catch(error => logger.warn({ runId: run.id, err: error }, "Managed warm session preparation cleanup failed"));+ await instructionWorkingCopy?.nativeInstructionReservation?.release().catch(error => logger.warn({ runId: run.id, err: error }, "Managed warm session preparation cleanup failed"));if (managedAiRuntime) await managedAiRuntime.cleanup().catch(() => logger.warn({ runId: run.id }, "AI connection refresh or cleanup failed"));let latestRun = await getRun(run.id).catch(() => null);try {@@ -3852,7 +3692,7 @@ export function heartbeatService(}// A retained or unverified process stays above this release boundary.// If no stopped-copy capture occurred, preserve an explicit loss report.- await releaseWarmInstructionPreparation?.();+ await instructionWorkingCopy?.releaseWarmInstructionPreparation?.();const uncapturedInstructions = await instructionCopies.reportUnavailable(run.companyId, run.id);if (uncapturedInstructions?.state === "unavailable") {await appendRunEvent(run, { eventType: "instruction_save", stream: "system", level: "warn",diff --git a/server/src/services/heartbeat/instruction-working-copy.test.ts b/server/src/services/heartbeat/instruction-working-copy.test.tsnew file mode 100644index 0000000000..3ed57790ea--- /dev/null+++ b/server/src/services/heartbeat/instruction-working-copy.test.ts@@ -0,0 +1,100 @@+import { beforeEach, describe, expect, it, vi } from "vitest";+import { createHeartbeatInstructionWorkingCopy } from "./instruction-working-copy.js";+import { AGENT_FILES_CONTRACT } from "../agent-file-store.js";+import { AgentDirectoryReuseInvalidatedError } from "../agent-directory-working-copies.js";++const native = vi.hoisted(() => ({ reserve: vi.fn(), claim: vi.fn() }));+vi.mock("../native-runtime/index.js", async importOriginal => ({+ ...await importOriginal<typeof import("../native-runtime/index.js")>(),+ reserveWarmNativeInstructionDirectory: native.reserve,+ claimWarmNativeInstructionCopy: native.claim,+}));++type Input = Parameters<typeof createHeartbeatInstructionWorkingCopy>[0];+type Prepare = Parameters<ReturnType<typeof createHeartbeatInstructionWorkingCopy>["prepare"]>[0];+type Copy = NonNullable<Awaited<ReturnType<Input["instructionCopies"]["prepare"]>>>;++function fixture() {+ let run = { id: "current-run", companyId: "company", agentId: "agent", runnerProfileJson: null, status: "queued" } as ReturnType<Input["readRun"]>;+ const copy = { runId: run.id, companyId: run.companyId, agentId: run.agentId,+ localRoot: "/workspace/copy", executionRoot: "/workspace/copy", entryFile: "AGENTS.md",+ state: "prepared", receipt: { schema: AGENT_FILES_CONTRACT, warm: true }, errorCode: null, errorMessage: null,+ } as unknown as Copy;+ const copies = {+ prepare: vi.fn<Input["instructionCopies"]["prepare"]>().mockResolvedValue(copy),+ collectStopped: vi.fn<Input["instructionCopies"]["collectStopped"]>().mockResolvedValue({ ...copy, state: "saved" }),+ checkpointWarm: vi.fn<Input["instructionCopies"]["checkpointWarm"]>().mockResolvedValue({ ...copy, state: "warm_saved", receipt: { ...copy.receipt, checkpointState: "unchanged" } }),+ hasChanges: vi.fn().mockResolvedValue(false), canReuseWarm: vi.fn().mockResolvedValue(true),+ reportRetirementUnconfirmed: vi.fn().mockResolvedValue(null),+ };+ const appendRunEvent = vi.fn().mockResolvedValue(undefined);+ const context = { paperclipWorkspace: { agentHome: "/canonical" } } as Record<string, unknown>;+ const controller = createHeartbeatInstructionWorkingCopy({+ db: {} as Input["db"], instructionCopies: copies as unknown as Input["instructionCopies"],+ readRun: () => run,+ agent: { id: "agent", companyId: "company", adapterType: "codex_local", adapterConfig: { lifecycleMode: "warm" }, runtimeConfig: {} } as unknown as Input["agent"],+ context,+ session: { taskSession: null, taskSessionForRun: { lastRunId: "previous-run" }, sessionConfigMetadata: {} as Input["session"]["sessionConfigMetadata"] },+ workspace: { executionTarget: null, executionWorkspace: { cwd: "/workspace" } as Input["workspace"]["executionWorkspace"], persistedExecutionWorkspace: null },+ appendRunEvent,+ });+ const prepare: Prepare = { runtimeConfig: { retained: true }, hasInstructionFilesystem: true,+ nativeRuntimeResolution: { kind: "native", profile: { backend: "codex_app_server" } } as Prepare["nativeRuntimeResolution"] };+ const reservation = { reuseRunId: "previous-run", adopt: vi.fn(), release: vi.fn().mockResolvedValue(undefined) };+ native.reserve.mockResolvedValue(reservation);+ return { controller, copies, copy, context, prepare, reservation, appendRunEvent,+ replaceRun: () => { run = { ...run, status: "running" }; return run; } };+}++beforeEach(() => { vi.clearAllMocks(); native.claim.mockResolvedValue(null); });++describe("instruction working-copy extraction boundary", () => {+ it("retains a warm reservation for outer cleanup when subsequent preparation throws", async () => {+ const f = fixture();+ f.copies.prepare.mockRejectedValue(new Error("preparation interrupted"));+ await expect(f.controller.prepare(f.prepare)).rejects.toThrow("preparation interrupted");+ expect(f.controller.nativeInstructionReservation).toBe(f.reservation);+ expect(f.controller.instructionCopy).toBeNull();+ await f.controller.nativeInstructionReservation?.release();+ expect(f.reservation.release).toHaveBeenCalledOnce();+ });++ it("publishes transferred copy ownership before fallible preparation bookkeeping", async () => {+ const f = fixture();+ f.copies.prepare.mockImplementation(async input => {+ input.onWarmHandoff?.(f.copy);+ throw new Error("bookkeeping interrupted");+ });+ await expect(f.controller.prepare(f.prepare)).rejects.toThrow("bookkeeping interrupted");+ expect(f.controller.instructionCopy).toBe(f.copy);+ expect(f.reservation.adopt).toHaveBeenCalledWith(f.copy.executionRoot, f.controller.collectStoppedInstructions);+ await f.controller.nativeInstructionReservation?.release();+ expect(f.reservation.release).toHaveBeenCalledOnce();+ });++ it("releases invalidated reuse before fresh preparation and exposes the replacement copy", async () => {+ const f = fixture(), order: string[] = [];+ f.reservation.release.mockImplementation(async () => { order.push("release"); });+ f.copies.prepare.mockImplementationOnce(async () => { order.push("reuse"); throw new AgentDirectoryReuseInvalidatedError("canonical changed"); })+ .mockImplementationOnce(async () => { order.push("fresh"); return f.copy; });+ const config = await f.controller.prepare(f.prepare);+ expect(order).toEqual(["reuse", "release", "fresh"]);+ expect(f.copies.prepare.mock.calls.map(([input]) => input.reuseRunId)).toEqual(["previous-run", undefined]);+ expect(f.controller.nativeInstructionReservation).toBeNull();+ expect(config).toMatchObject({ retained: true, instructionsFilePath: "/workspace/copy/AGENTS.md" });+ expect(f.controller.instructionCopy).toBe(f.copy);+ });++ it("reads the current run row and receipt during stopped collection and warm checkpoints", async () => {+ const f = fixture();+ await f.controller.prepare(f.prepare);+ const running = f.replaceRun();+ await f.controller.collectStoppedInstructions();+ expect(f.appendRunEvent.mock.calls.at(-1)?.[0]).toBe(running);+ expect(f.controller.getInstructionSave()).toMatchObject({ state: "saved" });+ expect(await f.controller.nativeInstructionWorkingCopy()?.checkpointWarm?.()).toBe(true);+ expect(f.controller.getInstructionSave()).toMatchObject({ state: "unchanged" });+ expect(f.appendRunEvent.mock.calls.at(-1)?.[0]).toBe(running);+ expect(f.context.paperclipWorkspace).toMatchObject({ agentHome: f.copy.executionRoot, agentHomeForPermissions: "/canonical" });+ });+});diff --git a/server/src/services/heartbeat/instruction-working-copy.ts b/server/src/services/heartbeat/instruction-working-copy.tsnew file mode 100644index 0000000000..87b443b92a--- /dev/null+++ b/server/src/services/heartbeat/instruction-working-copy.ts@@ -0,0 +1,233 @@+import { createHash } from "node:crypto";+import path from "node:path";+import { and, eq, sql } from "drizzle-orm";+import { heartbeatRuns, type Db } from "@paperclipai/db";+import { parseObject } from "../../adapters/utils.js";+import { logger } from "../../middleware/logger.js";+import { AgentDirectoryReuseInvalidatedError, isAgentDirectoryCopy } from "../agent-directory-working-copies.js";+import { collectStoppedInstructionCopyWithRetries, instructionWorkingCopyGuidance, type agentInstructionWorkingCopyService } from "../agent-instruction-working-copies.js";+import { claimWarmNativeInstructionCopy, nativeSessionWorkspaceScope, reserveWarmNativeInstructionDirectory } from "../native-runtime/index.js";+import { parseNativeExecutionInput } from "../../vendor/paperclip-runner/index.js";+import type { HeartbeatRuntimeSelectionInput } from "./runtime-selection.js";+import type { createHeartbeatLifecycle } from "./run-lifecycle.js";+import type { EffectiveRunSessionConfigMetadata } from "./workspaces.js";++type Copies = ReturnType<typeof agentInstructionWorkingCopyService>;+type Selection = HeartbeatRuntimeSelectionInput;+type AppendRunEvent = ReturnType<typeof createHeartbeatLifecycle>["appendRunEvent"];++function readNonEmptyString(value: unknown): string | null {+ return typeof value === "string" && value.trim().length > 0 ? value : null;+}++/** A failed cleanup is deferred once per run; it cannot replace the run result. */+export function createHeartbeatInstructionCopyRelease(+ instructionCleanupRun: Selection["run"],+ instructionCopies: Pick<Copies, "release">,+ appendRunEvent: AppendRunEvent,+) {+ let instructionCleanupDeferred = false;+ const releaseInstructionCopy = async () => {+ // Cleanup is retried from the durable working-copy receipt by the+ // recovery sweep. It must not replace the provider result (or prevent+ // lease release), and a timeout must not be repeated in outer teardown.+ if (instructionCleanupDeferred) return;+ try {+ await instructionCopies.release(instructionCleanupRun.companyId, instructionCleanupRun.id);+ } catch (err) {+ instructionCleanupDeferred = true;+ logger.warn({ err, runId: instructionCleanupRun.id }, "Agent file cleanup deferred; run outcome preserved");+ await appendRunEvent(instructionCleanupRun, {+ eventType: "instruction_cleanup",+ stream: "system",+ level: "warn",+ message: "Agent file cleanup was deferred. The run outcome and file-save receipt are unchanged.",+ payload: { state: "deferred" },+ }).catch((eventError) => {+ logger.warn({ err: eventError, runId: instructionCleanupRun.id }, "Failed to record deferred agent file cleanup");+ });+ }+ };+ return releaseInstructionCopy;+}++interface InstructionWorkingCopyInput {+ db: Db;+ instructionCopies: Copies;+ // The executor replaces its run row before preparation. Callbacks must see it.+ readRun: () => Selection["run"];+ agent: Selection["agent"];+ context: Selection["task"]["context"];+ session: {+ taskSession: { lastRunId: string | null } | null;+ taskSessionForRun: Selection["session"]["taskSessionForRun"];+ sessionConfigMetadata: EffectiveRunSessionConfigMetadata;+ };+ workspace: Pick<Selection["workspace"], "executionTarget" | "executionWorkspace" | "persistedExecutionWorkspace">;+ appendRunEvent: AppendRunEvent;+}++/** Per-run copy, receipt, and warm ownership; the executor orders final releases. */+export function createHeartbeatInstructionWorkingCopy(input: InstructionWorkingCopyInput) {+ const { db, instructionCopies, readRun, agent, context, appendRunEvent } = input;+ const { taskSession, taskSessionForRun, sessionConfigMetadata } = input.session;+ const { executionTarget, executionWorkspace, persistedExecutionWorkspace } = input.workspace;+ let releaseWarmInstructionPreparation: (() => Promise<void>) | null = null;+ let nativeInstructionReservation: Awaited<ReturnType<typeof reserveWarmNativeInstructionDirectory>> = null;+ let instructionCopy: Awaited<ReturnType<typeof instructionCopies.prepare>> = null;+ let instructionSave: Record<string, unknown> | null = null;+ const instructionPreparationKey = createHash("sha256").update(JSON.stringify({+ adapterType: agent.adapterType, adapterConfig: agent.adapterConfig, runtimeConfig: agent.runtimeConfig, sessionConfigMetadata,+ workspace: nativeSessionWorkspaceScope({+ binding: { runId: readRun().id, executionWorkspaceId: persistedExecutionWorkspace?.id ?? readRun().id },+ workspace: executionWorkspace,+ }), cwd: executionWorkspace.cwd,+ })).digest("hex");+ const recordInstructionSave = async (saved: NonNullable<Awaited<ReturnType<typeof instructionCopies.get>>>) => {+ const receipt = parseObject(saved.receipt);+ const storageWarning = readNonEmptyString(receipt.storageWarning);+ const state = saved.errorCode === "AGENT_FILES_CHECKPOINT_UNSTABLE" ? "pending_collection"+ : saved.state === "warm_saved" ? readNonEmptyString(receipt.checkpointState) ?? "saved" : saved.state;+ instructionSave = { state, entryFile: saved.entryFile,+ ...(isAgentDirectoryCopy(saved) ? { contract: "agent_files", appliedCandidateHash: saved.candidateHash, checkpointStats: receipt.checkpointStats }+ : { revisionId: parseObject(receipt.revision).id ?? null }), storageWarning, errorCode: saved.errorCode, errorMessage: saved.errorMessage };+ await appendRunEvent(readRun(), { eventType: "instruction_save", stream: "system",+ level: !saved.errorCode && !storageWarning && ["saved", "unchanged", "resolved"].includes(state) ? "info" : "warn",+ message: storageWarning ?? (state === "saved" ? "Agent files saved."+ : state === "unchanged" ? "Instruction working copy is unchanged."+ : saved.errorMessage ?? "Instruction edits were not saved."), payload: instructionSave });+ };+ const collectStoppedInstructions = async () => {+ if (!instructionCopy) return;+ const saved = await collectStoppedInstructionCopyWithRetries(() => instructionCopies.collectStopped({+ companyId: agent.companyId, runId: readRun().id, target: executionTarget,+ }));+ if (!saved) return;+ if (saved.state !== "superseded") await recordInstructionSave(saved);+ };+ const nativeInstructionWorkingCopy = () => instructionCopy ? {+ ...(isAgentDirectoryCopy(instructionCopy) ? { runId: readRun().id, preparationKey: instructionPreparationKey } : {}),+ root: instructionCopy.executionRoot,+ ...(instructionCopy.receipt?.warm === true ? { checkpointWarm: async () => {+ const saved = await instructionCopies.checkpointWarm({ companyId: agent.companyId, runId: readRun().id, target: executionTarget });+ if (saved) await recordInstructionSave(saved);+ return saved?.state === "warm_saved" && saved.errorCode === null;+ } } : {}),+ hasChanges: () => instructionCopies.hasChanges({ companyId: agent.companyId, runId: readRun().id, target: executionTarget }),+ collectStopped: collectStoppedInstructions,+ retirementFailed: async () => { await instructionCopies.reportRetirementUnconfirmed(agent.companyId, readRun().id); },+ } : undefined;++ async function prepare({ runtimeConfig, nativeRuntimeResolution, hasInstructionFilesystem }: {+ runtimeConfig: Record<string, unknown>;+ nativeRuntimeResolution: Selection["nativeRuntimeResolution"];+ hasInstructionFilesystem: boolean;+ }) {+ if (hasInstructionFilesystem) {+ try {+ // Missing contract fields on a restored session mean the deployed+ // legacy format. New sessions opt into whole-directory persistence.+ const priorFileRun = taskSession?.lastRunId+ ? await db.select({ profile: heartbeatRuns.runnerProfileJson }).from(heartbeatRuns).where(and(+ eq(heartbeatRuns.id, taskSession.lastRunId), eq(heartbeatRuns.companyId, agent.companyId), eq(heartbeatRuns.agentId, agent.id))).then(rows => rows[0])+ : null;+ const savedFileInput = parseObject(parseObject(readRun().runnerProfileJson).nativeExecutionInput);+ const priorFileInput = Object.keys(savedFileInput).length ? savedFileInput : parseObject(parseObject(priorFileRun?.profile).nativeExecutionInput);+ const priorWorkingCopy = parseObject(parseObject(parseObject(priorFileInput.runtimeContext).instructions).workingCopy);+ const warmFiles = nativeRuntimeResolution.kind === "native" && (nativeRuntimeResolution.profile.backend === "codex_app_server" ||+ (nativeRuntimeResolution.profile.backend === "acpx_runtime" && parseObject(agent.adapterConfig).acpxAgent === "cursor")) &&+ (executionTarget?.kind === "remote" && executionTarget.transport === "sandbox"+ ? executionTarget.runnerLifecyclePolicy?.mode === "warm"+ : parseObject(agent.adapterConfig).lifecycleMode === "warm");+ if (warmFiles && taskSessionForRun?.lastRunId) {+ nativeInstructionReservation = await reserveWarmNativeInstructionDirectory({ companyId: agent.companyId, agentId: agent.id,+ previousRunId: taskSessionForRun.lastRunId, runId: readRun().id, target: executionTarget,+ canReuse: () => instructionCopies.canReuseWarm(agent.companyId, agent.id, taskSessionForRun!.lastRunId!),+ });+ }+ if (!warmFiles && nativeRuntimeResolution.kind === "native" && priorWorkingCopy.kind === "agent_files" && taskSession) {+ releaseWarmInstructionPreparation = await claimWarmNativeInstructionCopy({+ priorExecution: parseNativeExecutionInput(priorFileInput), companyId: agent.companyId, agentId: agent.id,+ executionWorkspaceId: persistedExecutionWorkspace?.id ?? readRun().id, workspace: executionWorkspace,+ environmentId: executionTarget?.environmentId ?? null, runId: readRun().id, preparationKey: instructionPreparationKey, forceRetirement: !taskSessionForRun,+ adopt: async previousRunId => {+ instructionCopy = await instructionCopies.adopt({ companyId: agent.companyId, agentId: agent.id,+ runId: readRun().id, previousRunId, target: executionTarget, cwd: executionWorkspace.cwd, allowRetirementHandoff: true });+ return nativeInstructionWorkingCopy() ?? null;+ },+ });+ // A collection-only handoff was retired. Re-enter normal+ // preparation instead of composing a root already collected.+ if (!releaseWarmInstructionPreparation) instructionCopy = null;+ }+ const prepareInstructions = (reuseRunId?: string) => instructionCopies.prepare({+ companyId: agent.companyId, agentId: agent.id, runId: readRun().id,+ target: executionTarget, cwd: executionWorkspace.cwd,+ legacy: Object.keys(priorFileInput).length > 0 && priorWorkingCopy.kind !== "agent_files",+ warm: warmFiles, reuseRunId,+ onWarmHandoff: copy => {+ instructionCopy = copy;+ nativeInstructionReservation?.adopt(copy.executionRoot, collectStoppedInstructions);+ },+ });+ try {+ instructionCopy ??= await prepareInstructions(nativeInstructionReservation?.reuseRunId);+ } catch (error) {+ if (!(error instanceof AgentDirectoryReuseInvalidatedError)) throw error;+ // prepare has released its canonical lock. Retirement can now+ // collect under that same lock before a fresh restore starts.+ await nativeInstructionReservation?.release();+ nativeInstructionReservation = null;+ instructionCopy = await prepareInstructions();+ }+ } catch (error) {+ if ((error as { status?: number }).status !== 403) throw error;+ // Missing write identity must not break a background run's read-only+ // prompt. It must also never imply that ordinary file edits will save.+ await appendRunEvent(readRun(), { eventType: "instruction_save", stream: "system", level: "warn",+ message: "Persistent instruction editing is unavailable. Use an authenticated user with instruction edit access and a managed instruction bundle.",+ payload: { state: "unavailable", code: "INSTRUCTION_COPY_UNAVAILABLE" } });+ const guidance = "No editable agent instruction working copy is registered for this turn. Use authenticated agent file tools for persistent edits; do not edit a private copy named in an earlier turn or claim its changes will persist.";+ for (const key of ["paperclipTaskMarkdown", "paperclipTaskMarkdownCompact"]) {+ context[key] = [readNonEmptyString(context[key]), guidance].filter(Boolean).join("\n\n");+ }+ }+ if (instructionCopy) {+ const storageWarning = readNonEmptyString(instructionCopy.receipt?.storageWarning);+ if (storageWarning) {+ instructionSave = { state: "prepared", contract: "agent_files", storageWarning };+ // This is an advisory on the run, never an agent pause, execution+ // failure, or scheduling gate. Keep it visible while work runs.+ await db.update(heartbeatRuns).set({ resultJson: sql`coalesce(${heartbeatRuns.resultJson}, '{}'::jsonb) || ${JSON.stringify({ instructionSave })}::jsonb` }).where(eq(heartbeatRuns.id, readRun().id));+ await appendRunEvent(readRun(), { eventType: "instruction_save", stream: "system", level: "warn",+ message: storageWarning, payload: instructionSave });+ }+ runtimeConfig = { ...runtimeConfig, instructionsFilePath: path.join(instructionCopy.localRoot, instructionCopy.entryFile) };+ if (isAgentDirectoryCopy(instructionCopy)) {+ const workspace = parseObject(context.paperclipWorkspace);+ context.paperclipWorkspace = { ...workspace, agentHome: instructionCopy.executionRoot,+ // Keep the pre-existing permission root stable for ACP session+ // identity. The per-run copy is already under the company root.+ agentHomeForPermissions: workspace.agentHome,+ };+ }+ const guidance = instructionWorkingCopyGuidance(instructionCopy);+ for (const key of ["paperclipTaskMarkdown", "paperclipTaskMarkdownCompact"]) {+ context[key] = [readNonEmptyString(context[key]), guidance].filter(Boolean).join("\n\n");+ }+ }+ }+ return runtimeConfig;+ }++ return {+ prepare,+ collectStoppedInstructions,+ nativeInstructionWorkingCopy,+ get instructionCopy() { return instructionCopy; },+ getInstructionSave: () => instructionSave,+ // These getters remain usable after partial acquisition failures.+ get nativeInstructionReservation() { return nativeInstructionReservation; },+ get releaseWarmInstructionPreparation() { return releaseWarmInstructionPreparation; },+ };+}diff --git a/tests/e2e/instruction-working-copy/README.md b/tests/e2e/instruction-working-copy/README.mdnew file mode 100644index 0000000000..027f57ddd2--- /dev/null+++ b/tests/e2e/instruction-working-copy/README.md@@ -0,0 +1,24 @@+# Instruction working-copy acceptance++Run a disposable server with an instruction-capable fixture around the real+process adapter. The capability override exists only in this launcher. The child+reads and edits its registered private copy and completes a task through the+run-scoped API. No provider calls are made.++```sh+node cli/node_modules/tsx/dist/cli.mjs tests/e2e/instruction-working-copy/launch.ts+```++Use its printed ready URL:++```sh+INSTRUCTION_COPY_TEST_URL=http://127.0.0.1:3100 \+pnpm exec playwright test --config tests/e2e/instruction-working-copy/playwright.config.ts+```++The browser checks completed tasks across two turns, exact saved bytes through+the agent-file API, the next process's restored contents, each run's save receipt,+and private-copy cleanup. The fixture refuses non-loopback servers and requires+its dedicated company. Screenshots and failure traces are in+`test-results/instruction-working-copy`. Stop the launcher with Ctrl-C; its+isolated data remains available for inspection.diff --git a/tests/e2e/instruction-working-copy/launch.ts b/tests/e2e/instruction-working-copy/launch.tsnew file mode 100644index 0000000000..557799edce--- /dev/null+++ b/tests/e2e/instruction-working-copy/launch.ts@@ -0,0 +1,23 @@+import { prepareTestDriveEnvironment, testDriveCommand } from "../../../cli/src/commands/test-drive.js";++const options = { harness: "codex", apiKeyEnv: "INSTRUCTION_FIXTURE_KEY", companyName: "Instruction Lifecycle QA", browser: false } as const;+process.env.INSTRUCTION_FIXTURE_KEY = "not-a-provider-key";+await prepareTestDriveEnvironment(options);+process.env.NODE_ENV = "test";+// Only this disposable server exposes the process adapter as an instruction-+// capable fixture. Production process-adapter capabilities are unchanged.+const { registerServerAdapter } = await import("../../../server/src/adapters/index.js");+const { processAdapter } = await import("../../../server/src/adapters/process/index.js");+registerServerAdapter({+ ...processAdapter,+ supportsInstructionsBundle: true,+ execute: async input => {+ const result = await processAdapter.execute({ ...input, config: { ...input.config,+ env: { ...(input.config.env as Record<string, unknown>), INSTRUCTION_FIXTURE_PATH: input.config.instructionsFilePath },+ } });+ // execute returns only after the real child process exits.+ await input.onProviderStopped?.();+ return result;+ },+});+await testDriveCommand(options);diff --git a/tests/e2e/instruction-working-copy/lifecycle.spec.ts b/tests/e2e/instruction-working-copy/lifecycle.spec.tsnew file mode 100644index 0000000000..94b6d18856--- /dev/null+++ b/tests/e2e/instruction-working-copy/lifecycle.spec.ts@@ -0,0 +1,47 @@+import { test, expect } from "@playwright/test";+import { mkdtemp, rm, stat } from "node:fs/promises";+import os from "node:os";+import path from "node:path";++const base = process.env.INSTRUCTION_COPY_TEST_URL;+test.skip(!base, "Launch this suite's disposable instruction-capable test-drive; see README.md");++test("saves stopped-process edits, shows completed tasks, and restores saved bytes on the next task", async ({ page }, info) => {+ expect(new URL(base!).hostname).toBe("127.0.0.1");+ const api = async (route: string, method = "GET", body?: unknown) => {+ const response = await page.request.fetch(`${base}/api${route}`, { method, data: body });+ expect(response.ok(), await response.text()).toBe(true);+ return response.json();+ };+ expect((await api("/health")).deploymentMode).toBe("local_trusted");+ const [company] = await api("/companies");+ expect(company.name).toBe("Instruction Lifecycle QA");+ const cwd = await mkdtemp(path.join(os.tmpdir(), "instruction-acceptance-"));+ try {+ const agent = await api(`/companies/${company.id}/agents`, "POST", {+ name: `Instruction worker ${path.basename(cwd)}`, role: "engineer", adapterType: "process",+ adapterConfig: { command: process.execPath, args: [path.resolve(import.meta.dirname, "worker.mjs")], cwd },+ instructionsBundle: { entryFile: "AGENTS.md", files: { "AGENTS.md": "# Original\n" } },+ runtimeConfig: { heartbeat: { enabled: false, wakeOnDemand: true } },+ });+ for (const turn of [0, 1]) {+ const issue = await api(`/companies/${company.id}/issues`, "POST", { title: `Persist instructions turn ${turn}`, status: "todo", assigneeAgentId: agent.id });+ await page.goto(`${base}/${company.issuePrefix}/issues/${issue.identifier}`);+ const runs = async () => (await api(`/companies/${company.id}/heartbeat-runs`)).filter((run: { contextSnapshot: { issueId?: string } }) => run.contextSnapshot?.issueId === issue.id);+ await expect.poll(async () => (await runs()).some((run: { status: string }) => run.status === "succeeded"), { timeout: 45_000 }).toBe(true);+ const history = await runs();+ expect(history).toHaveLength(1);+ const run = await api(`/heartbeat-runs/${history[0].id}`);+ expect(run.resultJson.instructionSave).toMatchObject({ state: turn === 0 ? "saved" : "unchanged", contract: "agent_files", entryFile: "AGENTS.md" });+ const outputLine = run.stdoutExcerpt.split("\n").find((line: string) => line.startsWith('{"before":'));+ expect(outputLine).toBeTruthy();+ const output = JSON.parse(outputLine!);+ expect(output.before).toBe(turn === 0 ? "# Original\n" : "# Saved by the real worker\n☃\n");+ expect((await api(`/agents/${agent.id}/instructions-bundle/file?path=AGENTS.md`)).content).toBe("# Saved by the real worker\n☃\n");+ await expect.poll(async () => stat(output.instructionPath).then(() => true, () => false)).toBe(false);+ await page.reload();+ await expect(page.getByRole("button", { name: /^Change status \(current: Done/ }).first()).toBeVisible();+ await page.screenshot({ path: info.outputPath(`completed-turn-${turn}.png`), fullPage: true });+ }+ } finally { await rm(cwd, { recursive: true, force: true }); }+});diff --git a/tests/e2e/instruction-working-copy/playwright.config.ts b/tests/e2e/instruction-working-copy/playwright.config.tsnew file mode 100644index 0000000000..d9a3dcc12b--- /dev/null+++ b/tests/e2e/instruction-working-copy/playwright.config.ts@@ -0,0 +1,6 @@+import { defineConfig } from "@playwright/test";+export default defineConfig({+ testDir: ".", testMatch: "*.spec.ts", workers: 1, timeout: 90_000,+ use: { viewport: { width: 1440, height: 1080 }, screenshot: "only-on-failure", trace: "retain-on-failure" },+ outputDir: "../../../test-results/instruction-working-copy", reporter: [["list"]],+});diff --git a/tests/e2e/instruction-working-copy/worker.mjs b/tests/e2e/instruction-working-copy/worker.mjsnew file mode 100644index 0000000000..9bc3ed0e86--- /dev/null+++ b/tests/e2e/instruction-working-copy/worker.mjs@@ -0,0 +1,14 @@+import { readFile, writeFile } from "node:fs/promises";+import assert from "node:assert/strict";+const env = process.env;+assert(env.INSTRUCTION_FIXTURE_PATH, "The adapter must receive the registered copy");+const before = await readFile(env.INSTRUCTION_FIXTURE_PATH, "utf8");+assert(["# Original\n", "# Saved by the real worker\n☃\n"].includes(before));+await writeFile(env.INSTRUCTION_FIXTURE_PATH, "# Saved by the real worker\n☃\n");+console.log(JSON.stringify({ before, instructionPath: env.INSTRUCTION_FIXTURE_PATH }));+const headers = { Authorization: `Bearer ${env.PAPERCLIP_API_KEY}`, "X-Paperclip-Run-Id": env.PAPERCLIP_RUN_ID, "Content-Type": "application/json" };+const runResponse = await fetch(`${env.PAPERCLIP_API_URL}/api/heartbeat-runs/${env.PAPERCLIP_RUN_ID}`, { headers });+assert(runResponse.ok);+const run = await runResponse.json();+const response = await fetch(`${env.PAPERCLIP_API_URL}/api/issues/${run.contextSnapshot.issueId}`, { method: "PATCH", headers, body: JSON.stringify({ status: "done", comment: "Read and updated the registered instruction working copy." }) });+assert(response.ok, await response.text());