Skip to content

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

Refresh run config before reusing workspaces (#8797)

Devin Foleya8f0ebaa8015
diff --git a/doc/CLI.md b/doc/CLI.md
index fd190a0e80..b42399d0ce 100644
--- a/doc/CLI.md
+++ b/doc/CLI.md
@@ -300,6 +300,8 @@ pnpm paperclipai agent instructions-file:put <agent-id> --path AGENTS.md --conte
pnpm paperclipai agent instructions-file:delete <agent-id> --path AGENTS.md
```
+Agent config, instructions, skills, project env, environment, secret, and workspace edits affect the next run. Active runs finish with the config they started with. When a saved session, reused workspace, or sandbox lease no longer matches the effective next-run config, Paperclip may start fresh execution and records non-sensitive freshness categories in run result JSON and workspace operation logs.
+
`agent local-cli` is the quickest way to run local Claude/Codex manually as a Paperclip agent:
- creates a new long-lived agent API key
diff --git a/doc/DEVELOPING.md b/doc/DEVELOPING.md
index aa47541b0a..7b784a3213 100644
--- a/doc/DEVELOPING.md
+++ b/doc/DEVELOPING.md
@@ -277,6 +277,12 @@ If the `codex` CLI is not installed or not on `PATH`, `codex_local` agent runs f
Local adapters require their corresponding CLI/session setup on the machine running Paperclip. External adapters are installed through the adapter/plugin flow and should not require hardcoded imports in `server/` or `ui/`.
+## Config Freshness
+
+Agent, project, environment, secret, skill, and workspace config edits are sampled at the next run boundary. A heartbeat that is already running finishes with the config it started with.
+
+When effective run config changes, Paperclip may intentionally skip a saved adapter session, refresh persisted workspace runtime config, replace a reused execution workspace, or avoid reusing a sandbox/environment lease. Fresh execution can lose adapter-specific session, workspace, or sandbox state; correctness of the next run's config takes priority over continuity. Plain environment values affect freshness through value hashes; run result JSON and workspace operation logs expose only the non-sensitive freshness decision categories, without storing secret values, full env maps, provider credentials, or private path details.
+
## Worktree-local Instances
When developing from multiple git worktrees, do not point two Paperclip servers at the same embedded PostgreSQL data directory.
diff --git a/packages/shared/src/types/workspace-operation.ts b/packages/shared/src/types/workspace-operation.ts
index 30043396c9..18a3788e02 100644
--- a/packages/shared/src/types/workspace-operation.ts
+++ b/packages/shared/src/types/workspace-operation.ts
@@ -1,5 +1,6 @@
export type WorkspaceOperationPhase =
| "worktree_prepare"
+ | "workspace_config_freshness"
| "workspace_provision"
| "workspace_teardown"
| "worktree_cleanup"
diff --git a/server/src/__tests__/effective-run-config-fingerprints.test.ts b/server/src/__tests__/effective-run-config-fingerprints.test.ts
new file mode 100644
index 0000000000..02afa38a4c
--- /dev/null
+++ b/server/src/__tests__/effective-run-config-fingerprints.test.ts
@@ -0,0 +1,303 @@
+import { describe, expect, it } from "vitest";
+import {
+ canonicalizeEffectiveRunConfigCategory,
+ createEffectiveRunConfigFingerprints,
+ diffEffectiveRunConfigFingerprints,
+} from "../services/effective-run-config-fingerprints.ts";
+
+describe("effective run config fingerprints", () => {
+ it("emits versioned deterministic fingerprints with stable object ordering", () => {
+ const first = createEffectiveRunConfigFingerprints({
+ session: {
+ adapterType: "codex_local",
+ adapterConfig: {
+ env: {
+ ZETA: "raw-zeta",
+ ALPHA: "raw-alpha",
+ PAPERCLIP_RUN_ID: "run-one",
+ },
+ model: "gpt-5.2",
+ },
+ },
+ workspace: {
+ repoRef: "main",
+ repoUrl: "https://github.com/example/repo.git",
+ workspaceRuntime: {
+ services: [
+ {
+ env: { PORT: "3100", FEATURE_FLAG: "enabled" },
+ command: "pnpm dev",
+ },
+ ],
+ },
+ },
+ lease: {
+ environmentId: "environment-1",
+ config: { beta: true, alpha: 1 },
+ },
+ });
+
+ const second = createEffectiveRunConfigFingerprints({
+ lease: {
+ config: { alpha: 1, beta: true },
+ environmentId: "environment-1",
+ },
+ workspace: {
+ workspaceRuntime: {
+ services: [
+ {
+ command: "pnpm dev",
+ env: { FEATURE_FLAG: "enabled", PORT: "3100" },
+ },
+ ],
+ },
+ repoUrl: "https://github.com/example/repo.git",
+ repoRef: "main",
+ },
+ session: {
+ adapterConfig: {
+ model: "gpt-5.2",
+ env: {
+ PAPERCLIP_RUN_ID: "run-two",
+ ALPHA: "raw-alpha",
+ ZETA: "raw-zeta",
+ },
+ },
+ adapterType: "codex_local",
+ },
+ });
+
+ expect(first.version).toBe(1);
+ expect(first.categories).toEqual(["session", "workspace", "lease"]);
+ expect(first.sessionFingerprint).toMatchObject({
+ version: 1,
+ category: "session",
+ algorithm: "sha256",
+ });
+ expect(first.sessionFingerprint.fingerprint).toMatch(/^v1:sha256:[a-f0-9]{64}$/);
+ expect(second).toEqual(first);
+ });
+
+ it("reports changed categories independently", () => {
+ const base = createEffectiveRunConfigFingerprints({
+ session: { adapterType: "codex_local", model: "gpt-5.2" },
+ workspace: { workspaceStrategy: { type: "git_worktree", branchTemplate: "{{issue.identifier}}" } },
+ lease: { environmentId: "environment-1", reuseLease: true },
+ });
+
+ expect(diffEffectiveRunConfigFingerprints(
+ base,
+ createEffectiveRunConfigFingerprints({
+ session: { adapterType: "codex_local", model: "gpt-5.3" },
+ workspace: { workspaceStrategy: { type: "git_worktree", branchTemplate: "{{issue.identifier}}" } },
+ lease: { environmentId: "environment-1", reuseLease: true },
+ }),
+ )).toMatchObject({
+ hasChanges: true,
+ changedCategories: ["session"],
+ changed: { session: true, workspace: false, lease: false },
+ });
+
+ expect(diffEffectiveRunConfigFingerprints(
+ base,
+ createEffectiveRunConfigFingerprints({
+ session: { adapterType: "codex_local", model: "gpt-5.2" },
+ workspace: { workspaceStrategy: { type: "git_worktree", branchTemplate: "custom-{{issue.identifier}}" } },
+ lease: { environmentId: "environment-1", reuseLease: true },
+ }),
+ ).changedCategories).toEqual(["workspace"]);
+
+ expect(diffEffectiveRunConfigFingerprints(
+ base,
+ createEffectiveRunConfigFingerprints({
+ session: { adapterType: "codex_local", model: "gpt-5.2" },
+ workspace: { workspaceStrategy: { type: "git_worktree", branchTemplate: "{{issue.identifier}}" } },
+ lease: { environmentId: "environment-2", reuseLease: true },
+ }),
+ ).changedCategories).toEqual(["lease"]);
+ });
+
+ it("uses resolved secret version metadata without raw secret values", () => {
+ const v7 = createEffectiveRunConfigFingerprints({
+ session: {
+ adapterConfig: {
+ env: {
+ OPENAI_API_KEY: "resolved-secret-value",
+ PLAIN_TEXT: "plain env value",
+ },
+ },
+ },
+ secretManifest: [
+ {
+ configPath: "env.OPENAI_API_KEY",
+ envKey: "OPENAI_API_KEY",
+ secretId: "secret-1",
+ bindingId: "binding-1",
+ version: 7,
+ provider: "local_encrypted",
+ providerVersionRef: "provider-version-7",
+ outcome: "success",
+ },
+ ],
+ });
+ const canonical = v7.sessionFingerprint.canonicalJson;
+
+ expect(canonical).toContain("secret-1");
+ expect(canonical).toContain("binding-1");
+ expect(canonical).toContain("provider-version-7");
+ expect(canonical).toContain("\"version\":7");
+ expect(canonical).not.toContain("resolved-secret-value");
+ expect(canonical).not.toContain("plain env value");
+ expect(canonical).not.toContain("fingerprintSha256");
+
+ const rawValueChanged = createEffectiveRunConfigFingerprints({
+ session: {
+ adapterConfig: {
+ env: {
+ OPENAI_API_KEY: "different-resolved-secret-value",
+ PLAIN_TEXT: "plain env value",
+ },
+ },
+ },
+ secretManifest: [
+ {
+ configPath: "env.OPENAI_API_KEY",
+ envKey: "OPENAI_API_KEY",
+ secretId: "secret-1",
+ bindingId: "binding-1",
+ version: 7,
+ provider: "local_encrypted",
+ providerVersionRef: "provider-version-7",
+ outcome: "success",
+ },
+ ],
+ });
+ expect(rawValueChanged.sessionFingerprint.fingerprint).toBe(v7.sessionFingerprint.fingerprint);
+
+ const versionChanged = createEffectiveRunConfigFingerprints({
+ session: {
+ adapterConfig: {
+ env: {
+ OPENAI_API_KEY: "different-resolved-secret-value",
+ PLAIN_TEXT: "plain env value",
+ },
+ },
+ },
+ secretManifest: [
+ {
+ configPath: "env.OPENAI_API_KEY",
+ envKey: "OPENAI_API_KEY",
+ secretId: "secret-1",
+ bindingId: "binding-1",
+ version: 8,
+ provider: "local_encrypted",
+ providerVersionRef: "provider-version-8",
+ outcome: "success",
+ },
+ ],
+ });
+ expect(versionChanged.sessionFingerprint.fingerprint).not.toBe(v7.sessionFingerprint.fingerprint);
+ });
+
+ it("detects plain env value drift without storing raw values", () => {
+ const base = createEffectiveRunConfigFingerprints({
+ session: {
+ adapterConfig: {
+ env: {
+ FEATURE_FLAG: "enabled",
+ },
+ },
+ },
+ });
+ const changed = createEffectiveRunConfigFingerprints({
+ session: {
+ adapterConfig: {
+ env: {
+ FEATURE_FLAG: "disabled",
+ },
+ },
+ },
+ });
+
+ expect(changed.sessionFingerprint.fingerprint).not.toBe(base.sessionFingerprint.fingerprint);
+ expect(base.sessionFingerprint.canonicalJson).toContain('"valueHash":"sha256:');
+ expect(base.sessionFingerprint.canonicalJson).not.toContain("enabled");
+ expect(changed.sessionFingerprint.canonicalJson).not.toContain("disabled");
+ });
+
+ it("excludes generated run values, sensitive tokens, timestamps, and session path noise", () => {
+ const first = createEffectiveRunConfigFingerprints({
+ session: {
+ sessionId: "generated-session-one",
+ runId: "run-one",
+ cwd: "/runtime/noise/project-a",
+ updatedAt: "2026-06-01T00:00:00.000Z",
+ adapterConfig: {
+ token: "token-one",
+ nested: {
+ authorization: "Bearer first",
+ },
+ env: {
+ PAPERCLIP_API_KEY: "runtime-api-key-one",
+ NORMAL_VALUE: "first",
+ },
+ },
+ },
+ lease: {
+ leaseId: "lease-one",
+ providerLeaseId: "provider-lease-one",
+ remoteCwd: "/runtime/noise/remote-a",
+ createdAt: "2026-06-01T00:00:00.000Z",
+ driver: "daytona",
+ },
+ });
+ const second = createEffectiveRunConfigFingerprints({
+ session: {
+ sessionId: "generated-session-two",
+ runId: "run-two",
+ cwd: "/runtime/noise/project-b",
+ updatedAt: "2026-06-02T00:00:00.000Z",
+ adapterConfig: {
+ token: "token-two",
+ nested: {
+ authorization: "Bearer second",
+ },
+ env: {
+ PAPERCLIP_API_KEY: "runtime-api-key-two",
+ NORMAL_VALUE: "first",
+ },
+ },
+ },
+ lease: {
+ leaseId: "lease-two",
+ providerLeaseId: "provider-lease-two",
+ remoteCwd: "/runtime/noise/remote-b",
+ createdAt: "2026-06-02T00:00:00.000Z",
+ driver: "daytona",
+ },
+ });
+
+ expect(second.sessionFingerprint.fingerprint).toBe(first.sessionFingerprint.fingerprint);
+ expect(second.leaseFingerprint.fingerprint).toBe(first.leaseFingerprint.fingerprint);
+ const canonical = [
+ first.sessionFingerprint.canonicalJson,
+ first.leaseFingerprint.canonicalJson,
+ ].join("\n");
+ expect(canonical).not.toContain("generated-session-one");
+ expect(canonical).not.toContain("run-one");
+ expect(canonical).not.toContain("/runtime/noise/project-a");
+ expect(canonical).not.toContain("runtime-api-key-one");
+ expect(canonical).not.toContain("token-one");
+ expect(canonical).not.toContain("Bearer first");
+ expect(canonical).not.toContain("lease-one");
+ expect(canonical).not.toContain("/runtime/noise/remote-a");
+
+ expect(canonicalizeEffectiveRunConfigCategory({
+ category: "workspace",
+ value: { cwd: "/explicit/runtime/workspace", workspaceStrategy: { type: "git_worktree" } },
+ })).toEqual({
+ cwd: "/explicit/runtime/workspace",
+ workspaceStrategy: { type: "git_worktree" },
+ });
+ });
+});
diff --git a/server/src/__tests__/environment-runtime.test.ts b/server/src/__tests__/environment-runtime.test.ts
index 4ec89cbe1c..ee7ce887f0 100644
--- a/server/src/__tests__/environment-runtime.test.ts
+++ b/server/src/__tests__/environment-runtime.test.ts
@@ -392,7 +392,7 @@ describeEmbeddedPostgres("environmentRuntimeService", () => {
},
});
- return { pluginId, companyId, executionWorkspaceId, reusableLease };
+ return { pluginId, companyId, agentId, environment, runId, executionWorkspaceId, reusableLease };
}
it("acquires and releases a local run lease through the runtime seam", async () => {
@@ -1217,6 +1217,413 @@ describeEmbeddedPostgres("environmentRuntimeService", () => {
});
});
+ it("does not resume released reusable plugin sandbox leases after provider config drift", async () => {
+ const pluginId = randomUUID();
+ const { companyId, agentId, environment: baseEnvironment, runId } = await seedEnvironment();
+ const providerConfig = {
+ provider: "fake-plugin",
+ image: "template-a",
+ timeoutMs: 1234,
+ reuseLease: true,
+ };
+ const environment = {
+ ...baseEnvironment,
+ name: "Reusable Plugin Sandbox",
+ driver: "sandbox",
+ config: providerConfig,
+ };
+ await environmentService(db).update(environment.id, {
+ driver: "sandbox",
+ name: environment.name,
+ config: providerConfig,
+ });
+ await db.insert(plugins).values({
+ id: pluginId,
+ pluginKey: "acme.fake-sandbox-provider",
+ packageName: "@acme/fake-sandbox-provider",
+ version: "1.0.0",
+ apiVersion: 1,
+ categories: ["automation"],
+ manifestJson: {
+ id: "acme.fake-sandbox-provider",
+ apiVersion: 1,
+ version: "1.0.0",
+ displayName: "Fake Sandbox Provider",
+ description: "Test schema-driven provider",
+ author: "Paperclip",
+ categories: ["automation"],
+ capabilities: ["environment.drivers.register"],
+ entrypoints: { worker: "dist/worker.js" },
+ environmentDrivers: [
+ {
+ driverKey: "fake-plugin",
+ kind: "sandbox_provider",
+ displayName: "Fake Plugin",
+ supportsReusableLeases: true,
+ configSchema: {
+ type: "object",
+ properties: {
+ image: { type: "string" },
+ timeoutMs: { type: "number" },
+ reuseLease: { type: "boolean" },
+ },
+ },
+ },
+ ],
+ },
+ status: "ready",
+ installOrder: 1,
+ updatedAt: new Date(),
+ } as any);
+ const executionWorkspaceId = randomUUID();
+ const projectId = randomUUID();
+ await db.insert(projects).values({
+ id: projectId,
+ companyId,
+ name: `Workspace ${projectId.slice(0, 8)}`,
+ status: "active",
+ createdAt: new Date(),
+ updatedAt: new Date(),
+ });
+ await db.insert(executionWorkspaces).values({
+ id: executionWorkspaceId,
+ companyId,
+ projectId,
+ mode: "shared_workspace",
+ strategyType: "project_primary",
+ name: "Reusable workspace",
+ status: "active",
+ providerType: "local_fs",
+ createdAt: new Date(),
+ updatedAt: new Date(),
+ });
+
+ const workerManager = {
+ isRunning: vi.fn((id: string) => id === pluginId),
+ call: vi.fn(async (_pluginId: string, method: string, params: any) => {
+ if (method === "environmentAcquireLease") {
+ return {
+ providerLeaseId: `lease-${params.config.image}`,
+ metadata: {
+ provider: "fake-plugin",
+ image: params.config.image,
+ timeoutMs: params.config.timeoutMs,
+ reuseLease: true,
+ remoteCwd: "/workspace",
+ },
+ };
+ }
+ if (method === "environmentReleaseLease" || method === "environmentDestroyLease") {
+ return undefined;
+ }
+ throw new Error(`Unexpected plugin method: ${method}`);
+ }),
+ } as unknown as PluginWorkerManager;
+ const runtimeWithPlugin = environmentRuntimeService(db, { pluginWorkerManager: workerManager });
+
+ const first = await runtimeWithPlugin.acquireRunLease({
+ companyId,
+ environment,
+ issueId: null,
+ agentId,
+ heartbeatRunId: runId,
+ persistedExecutionWorkspace: {
+ id: executionWorkspaceId,
+ mode: "shared_workspace",
+ },
+ });
+ expect(first.lease.metadata?.reusableSandboxLease).toMatchObject({
+ provider: "fake-plugin",
+ leaseFingerprint: expect.objectContaining({
+ category: "lease",
+ fingerprint: expect.stringMatching(/^v1:sha256:[a-f0-9]{64}$/),
+ }),
+ });
+ await runtimeWithPlugin.releaseRunLeases(runId);
+
+ const nextRunId = randomUUID();
+ await db.insert(heartbeatRuns).values({
+ id: nextRunId,
+ companyId,
+ agentId,
+ invocationSource: "manual",
+ status: "running",
+ createdAt: new Date(),
+ updatedAt: new Date(),
+ });
+ const updatedEnvironment = {
+ ...environment,
+ config: {
+ ...providerConfig,
+ image: "template-b",
+ },
+ };
+ await environmentService(db).update(environment.id, {
+ config: updatedEnvironment.config,
+ });
+
+ const second = await runtimeWithPlugin.acquireRunLease({
+ companyId,
+ environment: updatedEnvironment,
+ issueId: null,
+ agentId,
+ heartbeatRunId: nextRunId,
+ persistedExecutionWorkspace: {
+ id: executionWorkspaceId,
+ mode: "shared_workspace",
+ },
+ });
+
+ expect(second.lease.providerLeaseId).toBe("lease-template-b");
+ expect(workerManager.call).not.toHaveBeenCalledWith(
+ pluginId,
+ "environmentResumeLease",
+ expect.anything(),
+ expect.anything(),
+ );
+ expect(workerManager.call).toHaveBeenCalledWith(pluginId, "environmentDestroyLease", expect.objectContaining({
+ providerLeaseId: "lease-template-a",
+ }), 31234);
+ await expect(environmentService(db).getLeaseById(first.lease.id)).resolves.toMatchObject({
+ status: "expired",
+ cleanupStatus: "success",
+ failureReason: "lease_fingerprint_mismatch",
+ });
+ });
+
+ it("does not resume released reusable plugin sandbox leases after secret version drift", async () => {
+ const pluginId = randomUUID();
+ const { companyId, agentId, environment: baseEnvironment, runId } = await seedEnvironment();
+ const apiSecret = await secretService(db).create(companyId, {
+ name: `secure-plugin-api-key-${randomUUID()}`,
+ provider: "local_encrypted",
+ value: "resolved-provider-key",
+ });
+ const providerConfig = {
+ provider: "secure-plugin",
+ template: "base",
+ apiKey: apiSecret.id,
+ timeoutMs: 1234,
+ reuseLease: true,
+ };
+ const environment = {
+ ...baseEnvironment,
+ name: "Secure Plugin Sandbox",
+ driver: "sandbox",
+ config: providerConfig,
+ };
+ await secretService(db).createBinding({
+ companyId,
+ secretId: apiSecret.id,
+ targetType: "environment",
+ targetId: environment.id,
+ configPath: "apiKey",
+ });
+ await environmentService(db).update(environment.id, {
+ driver: "sandbox",
+ name: environment.name,
+ config: providerConfig,
+ });
+ await db.insert(plugins).values({
+ id: pluginId,
+ pluginKey: "acme.secure-sandbox-provider",
+ packageName: "@acme/secure-sandbox-provider",
+ version: "1.0.0",
+ apiVersion: 1,
+ categories: ["automation"],
+ manifestJson: {
+ id: "acme.secure-sandbox-provider",
+ apiVersion: 1,
+ version: "1.0.0",
+ displayName: "Secure Sandbox Provider",
+ description: "Test schema-driven provider",
+ author: "Paperclip",
+ categories: ["automation"],
+ capabilities: ["environment.drivers.register"],
+ entrypoints: { worker: "dist/worker.js" },
+ environmentDrivers: [
+ {
+ driverKey: "secure-plugin",
+ kind: "sandbox_provider",
+ displayName: "Secure Sandbox",
+ supportsReusableLeases: true,
+ configSchema: {
+ type: "object",
+ properties: {
+ template: { type: "string" },
+ apiKey: { type: "string", format: "secret-ref" },
+ timeoutMs: { type: "number" },
+ reuseLease: { type: "boolean" },
+ },
+ },
+ },
+ ],
+ },
+ status: "ready",
+ installOrder: 1,
+ updatedAt: new Date(),
+ } as any);
+ const executionWorkspaceId = randomUUID();
+ const projectId = randomUUID();
+ await db.insert(projects).values({
+ id: projectId,
+ companyId,
+ name: `Workspace ${projectId.slice(0, 8)}`,
+ status: "active",
+ createdAt: new Date(),
+ updatedAt: new Date(),
+ });
+ await db.insert(executionWorkspaces).values({
+ id: executionWorkspaceId,
+ companyId,
+ projectId,
+ mode: "shared_workspace",
+ strategyType: "project_primary",
+ name: "Reusable workspace",
+ status: "active",
+ providerType: "local_fs",
+ createdAt: new Date(),
+ updatedAt: new Date(),
+ });
+
+ const workerManager = {
+ isRunning: vi.fn((id: string) => id === pluginId),
+ call: vi.fn(async (_pluginId: string, method: string, params: any) => {
+ if (method === "environmentAcquireLease") {
+ return {
+ providerLeaseId: `lease-${params.config.apiKey}`,
+ metadata: {
+ provider: "secure-plugin",
+ template: params.config.template,
+ apiKey: params.config.apiKey,
+ timeoutMs: params.config.timeoutMs,
+ reuseLease: true,
+ remoteCwd: "/workspace",
+ },
+ };
+ }
+ if (method === "environmentReleaseLease" || method === "environmentDestroyLease") {
+ return undefined;
+ }
+ throw new Error(`Unexpected plugin method: ${method}`);
+ }),
+ } as unknown as PluginWorkerManager;
+ const runtimeWithPlugin = environmentRuntimeService(db, { pluginWorkerManager: workerManager });
+
+ const first = await runtimeWithPlugin.acquireRunLease({
+ companyId,
+ environment,
+ issueId: null,
+ agentId,
+ heartbeatRunId: runId,
+ persistedExecutionWorkspace: {
+ id: executionWorkspaceId,
+ mode: "shared_workspace",
+ },
+ });
+ await runtimeWithPlugin.releaseRunLeases(runId);
+ await secretService(db).rotate(apiSecret.id, { value: "rotated-provider-key" });
+
+ const nextRunId = randomUUID();
+ await db.insert(heartbeatRuns).values({
+ id: nextRunId,
+ companyId,
+ agentId,
+ invocationSource: "manual",
+ status: "running",
+ createdAt: new Date(),
+ updatedAt: new Date(),
+ });
+ const second = await runtimeWithPlugin.acquireRunLease({
+ companyId,
+ environment,
+ issueId: null,
+ agentId,
+ heartbeatRunId: nextRunId,
+ persistedExecutionWorkspace: {
+ id: executionWorkspaceId,
+ mode: "shared_workspace",
+ },
+ });
+
+ expect(second.lease.providerLeaseId).toBe("lease-rotated-provider-key");
+ expect(workerManager.call).not.toHaveBeenCalledWith(
+ pluginId,
+ "environmentResumeLease",
+ expect.anything(),
+ expect.anything(),
+ );
+ expect(workerManager.call).toHaveBeenCalledWith(pluginId, "environmentDestroyLease", expect.objectContaining({
+ providerLeaseId: "lease-resolved-provider-key",
+ }), 31234);
+ await expect(environmentService(db).getLeaseById(first.lease.id)).resolves.toMatchObject({
+ status: "expired",
+ cleanupStatus: "success",
+ failureReason: "lease_fingerprint_mismatch",
+ });
+ const firstMetadata = JSON.stringify(first.lease.metadata);
+ expect(firstMetadata).not.toContain("resolved-provider-key");
+ expect(firstMetadata).not.toContain("rotated-provider-key");
+ });
+
+ it("preserves active reusable sandbox leases held by another running run", async () => {
+ const { pluginId, companyId, agentId, environment, executionWorkspaceId, reusableLease } =
+ await seedReusablePluginSandboxLease();
+ const nextRunId = randomUUID();
+ await db.insert(heartbeatRuns).values({
+ id: nextRunId,
+ companyId,
+ agentId,
+ invocationSource: "manual",
+ status: "running",
+ createdAt: new Date(),
+ updatedAt: new Date(),
+ });
+ const workerManager = {
+ isRunning: vi.fn((id: string) => id === pluginId),
+ call: vi.fn(async (_pluginId: string, method: string) => {
+ if (method === "environmentAcquireLease") {
+ return {
+ providerLeaseId: "fresh-plugin-lease",
+ metadata: {
+ provider: "fake-plugin",
+ image: "fake:test",
+ timeoutMs: 1234,
+ reuseLease: true,
+ remoteCwd: "/workspace",
+ },
+ };
+ }
+ throw new Error(`Unexpected plugin method: ${method}`);
+ }),
+ } as unknown as PluginWorkerManager;
+ const runtimeWithPlugin = environmentRuntimeService(db, { pluginWorkerManager: workerManager });
+
+ const acquired = await runtimeWithPlugin.acquireRunLease({
+ companyId,
+ environment,
+ issueId: null,
+ agentId,
+ heartbeatRunId: nextRunId,
+ persistedExecutionWorkspace: {
+ id: executionWorkspaceId,
+ mode: "shared_workspace",
+ },
+ });
+
+ expect(acquired.lease.providerLeaseId).toBe("fresh-plugin-lease");
+ expect(workerManager.call).toHaveBeenCalledOnce();
+ expect(workerManager.call).toHaveBeenCalledWith(pluginId, "environmentAcquireLease", expect.objectContaining({
+ agentId,
+ executionWorkspaceId,
+ runId: nextRunId,
+ }), 31234);
+ await expect(environmentService(db).getLeaseById(reusableLease.id)).resolves.toMatchObject({
+ status: "active",
+ cleanupStatus: null,
+ });
+ });
+
it("does not retain or resume plugin-backed sandbox leases unless the provider opts in", async () => {
const pluginId = randomUUID();
const { companyId, agentId, environment: baseEnvironment, runId } = await seedEnvironment();
diff --git a/server/src/__tests__/heartbeat-workspace-session.test.ts b/server/src/__tests__/heartbeat-workspace-session.test.ts
index a22507f7fd..cdce55dd7b 100644
--- a/server/src/__tests__/heartbeat-workspace-session.test.ts
+++ b/server/src/__tests__/heartbeat-workspace-session.test.ts
@@ -11,8 +11,10 @@ import {
applyPersistedExecutionWorkspaceConfig,
assertGitSensitiveAdapterWorkspaceValid,
assertPushCapabilityCheckoutValid,
- buildRealizedExecutionWorkspaceFromPersisted,
buildExplicitResumeSessionOverride,
+ buildEffectiveRunSessionConfigMetadata,
+ buildEffectiveRunWorkspaceConfigMetadata,
+ buildWorkspaceConfigFreshnessOperation,
deriveTaskKeyWithHeartbeatFallback,
extractWakeCommentIds,
formatRuntimeWorkspaceWarningLog,
@@ -21,7 +23,9 @@ import {
preflightLowTrustWorkspaceIsolation,
prioritizeProjectWorkspaceCandidatesForRun,
parseSessionCompactionPolicy,
+ resolveExecutionWorkspaceConfigFreshness,
resolveNextSessionState,
+ resolveTaskSessionConfigFreshness,
requiresPushCapabilityPreflight,
resolveWorkspaceAfterLowTrustPreflight,
resolveRuntimeSessionParamsForWorkspace,
@@ -30,6 +34,7 @@ import {
stripWorkspaceRuntimeFromExecutionRunConfig,
shouldResetTaskSessionForModelChange,
stripConfiguredModelFromSessionParams,
+ stripPaperclipSessionMetadataFromSessionParams,
normalizeSessionParams,
shouldResetTaskSessionForWake,
type ResolvedWorkspaceForRun,
@@ -812,48 +817,266 @@ describe("mergeExecutionWorkspaceMetadataForPersistence", () => {
});
});
-describe("buildRealizedExecutionWorkspaceFromPersisted", () => {
- it("reuses the persisted execution workspace path instead of deriving a new worktree", () => {
- const result = buildRealizedExecutionWorkspaceFromPersisted({
- base: buildResolvedWorkspace({
- cwd: "/tmp/project-primary",
- repoRef: "main",
+type WorkspaceConfigMetadata = ReturnType<typeof buildEffectiveRunWorkspaceConfigMetadata>;
+
+function buildWorkspaceConfigMetadata(
+ overrides: Partial<Parameters<typeof buildEffectiveRunWorkspaceConfigMetadata>[0]> = {},
+) {
+ return buildEffectiveRunWorkspaceConfigMetadata({
+ mode: "isolated_workspace",
+ projectId: "project-1",
+ projectWorkspaceId: "workspace-1",
+ strategyType: "git_worktree",
+ workspaceStrategy: {
+ type: "git_worktree",
+ baseRef: "origin/main",
+ branchTemplate: "{{issue.identifier}}-{{slug}}",
+ worktreeParentDir: ".paperclip/worktrees",
+ },
+ repoUrl: "https://github.com/example/repo.git",
+ repoRef: "origin/main",
+ configSnapshot: {
+ provisionCommand: "pnpm install",
+ teardownCommand: "pnpm stop",
+ cleanupCommand: "pnpm clean",
+ desiredState: "running",
+ serviceStates: { "0": "running" },
+ workspaceRuntime: {
+ services: [{ name: "web", command: "pnpm dev", port: 3100 }],
+ },
+ },
+ environment: {
+ selectedEnvironmentId: "environment-1",
+ driver: "local",
+ config: { provider: "local" },
+ },
+ realization: {
+ environmentDriver: "local",
+ environmentProvider: "local",
+ },
+ evaluatedAt: "2026-06-26T00:00:00.000Z",
+ ...overrides,
+ });
+}
+
+function persistedWorkspaceConfigFingerprint(metadata: WorkspaceConfigMetadata) {
+ return {
+ configFingerprint: {
+ version: metadata.version,
+ workspaceHash: metadata.fingerprint,
+ categories: metadata.categories,
+ categoryFingerprints: metadata.categoryFingerprints,
+ lastEvaluatedAt: metadata.evaluatedAt,
+ },
+ };
+}
+
+describe("effective run execution workspace config freshness", () => {
+ it("reuses an existing workspace when the stored workspace fingerprint is unchanged", () => {
+ const metadata = buildWorkspaceConfigMetadata();
+
+ const decision = resolveExecutionWorkspaceConfigFreshness({
+ hasExistingWorkspace: true,
+ existingWorkspaceMetadata: persistedWorkspaceConfigFingerprint(metadata),
+ nextMetadata: metadata,
+ });
+
+ expect(decision).toMatchObject({
+ action: "reuse",
+ shouldReuseExisting: true,
+ shouldRefreshConfigSnapshot: false,
+ changedCategories: [],
+ storedFingerprintPresent: true,
+ });
+ });
+
+ it("refreshes metadata and config for runtime-service-only drift without replacing the workspace", () => {
+ const base = buildWorkspaceConfigMetadata();
+ const next = buildWorkspaceConfigMetadata({
+ configSnapshot: {
+ provisionCommand: "pnpm install",
+ teardownCommand: "pnpm stop",
+ cleanupCommand: "pnpm clean",
+ desiredState: "running",
+ serviceStates: { "0": "running" },
+ workspaceRuntime: {
+ services: [{ name: "web", command: "pnpm dev -- --host 0.0.0.0", port: 3200 }],
+ },
+ },
+ });
+
+ const decision = resolveExecutionWorkspaceConfigFreshness({
+ hasExistingWorkspace: true,
+ existingWorkspaceMetadata: persistedWorkspaceConfigFingerprint(base),
+ nextMetadata: next,
+ });
+
+ expect(decision).toMatchObject({
+ action: "refresh",
+ shouldReuseExisting: true,
+ shouldRefreshConfigSnapshot: true,
+ changedCategories: ["runtimeServices"],
+ });
+
+ const metadata = mergeExecutionWorkspaceMetadataForPersistence({
+ existingMetadata: {
+ config: {
+ workspaceRuntime: { services: [{ name: "web", command: "pnpm dev", port: 3100 }] },
+ },
+ ...persistedWorkspaceConfigFingerprint(base),
+ },
+ source: "task_session",
+ createdByRuntime: false,
+ configSnapshot: {
+ workspaceRuntime: {
+ services: [{ name: "web", command: "pnpm dev -- --host 0.0.0.0", port: 3200 }],
+ },
+ desiredState: "running",
+ serviceStates: { "0": "running" },
+ },
+ shouldReuseExisting: true,
+ shouldRefreshConfigSnapshot: true,
+ workspaceConfigMetadata: next,
+ baseRef: "origin/main",
+ baseRefSha: "abc123",
+ });
+
+ expect(metadata?.config).toMatchObject({
+ workspaceRuntime: {
+ services: [{ name: "web", command: "pnpm dev -- --host 0.0.0.0", port: 3200 }],
+ },
+ });
+ expect(metadata?.configFingerprint).toMatchObject({
+ workspaceHash: next.fingerprint,
+ categories: next.categories,
+ });
+ });
+
+ it.each([
+ {
+ name: "mode",
+ category: "mode",
+ next: buildWorkspaceConfigMetadata({ mode: "shared_workspace" }),
+ },
+ {
+ name: "workspace strategy",
+ category: "strategy",
+ next: buildWorkspaceConfigMetadata({
+ workspaceStrategy: {
+ type: "git_worktree",
+ baseRef: "origin/main",
+ branchTemplate: "custom-{{issue.identifier}}",
+ worktreeParentDir: ".paperclip/worktrees",
+ },
}),
- workspace: {
- id: "execution-workspace-1",
- companyId: "company-1",
- projectId: "project-1",
- projectWorkspaceId: "workspace-1",
- sourceIssueId: "issue-1",
- mode: "isolated_workspace",
- strategyType: "git_worktree",
- name: "PAP-880-thumbs-capture-for-evals-feature",
- status: "active",
- cwd: "/tmp/reused-worktree",
- repoUrl: "https://example.com/paperclip.git",
- baseRef: "main",
- branchName: "PAP-880-thumbs-capture-for-evals-feature",
- providerType: "git_worktree",
- providerRef: "/tmp/reused-worktree",
- derivedFromExecutionWorkspaceId: null,
- lastUsedAt: new Date(),
- openedAt: new Date(),
- closedAt: null,
- cleanupEligibleAt: null,
- cleanupReason: null,
- config: null,
- metadata: null,
- createdAt: new Date(),
- updatedAt: new Date(),
- },
- });
-
- expect(result.created).toBe(false);
- expect(result.strategy).toBe("git_worktree");
- expect(result.cwd).toBe("/tmp/reused-worktree");
- expect(result.worktreePath).toBe("/tmp/reused-worktree");
- expect(result.branchName).toBe("PAP-880-thumbs-capture-for-evals-feature");
- expect(result.source).toBe("task_session");
+ },
+ {
+ name: "project workspace",
+ category: "projectWorkspace",
+ next: buildWorkspaceConfigMetadata({ projectWorkspaceId: "workspace-2" }),
+ },
+ {
+ name: "base ref",
+ category: "repo",
+ next: buildWorkspaceConfigMetadata({
+ repoRef: "origin/release",
+ workspaceStrategy: {
+ type: "git_worktree",
+ baseRef: "origin/release",
+ branchTemplate: "{{issue.identifier}}-{{slug}}",
+ worktreeParentDir: ".paperclip/worktrees",
+ },
+ }),
+ },
+ {
+ name: "environment realization",
+ category: "environment",
+ next: buildWorkspaceConfigMetadata({
+ environment: {
+ selectedEnvironmentId: "environment-2",
+ driver: "sandbox",
+ config: { provider: "daytona" },
+ },
+ realization: {
+ environmentDriver: "sandbox",
+ environmentProvider: "daytona",
+ },
+ }),
+ },
+ ] as const)("replaces the workspace when $name changes", ({ category, next }) => {
+ const base = buildWorkspaceConfigMetadata();
+
+ const decision = resolveExecutionWorkspaceConfigFreshness({
+ hasExistingWorkspace: true,
+ existingWorkspaceMetadata: persistedWorkspaceConfigFingerprint(base),
+ nextMetadata: next,
+ });
+
+ expect(decision.action).toBe("replace");
+ expect(decision.shouldReuseExisting).toBe(false);
+ expect(decision.changedCategories).toContain(category);
+ });
+
+ it("formats a safe workspace operation payload for config drift decisions", () => {
+ const decision = resolveExecutionWorkspaceConfigFreshness({
+ hasExistingWorkspace: true,
+ existingWorkspaceMetadata: persistedWorkspaceConfigFingerprint(buildWorkspaceConfigMetadata()),
+ nextMetadata: buildWorkspaceConfigMetadata({
+ configSnapshot: {
+ workspaceRuntime: {
+ services: [{ name: "web", command: "pnpm dev -- --host 0.0.0.0", port: 3200 }],
+ },
+ },
+ }),
+ });
+
+ const operation = buildWorkspaceConfigFreshnessOperation({
+ decision,
+ hasExistingWorkspace: true,
+ reuseRequested: true,
+ workspaceReused: true,
+ configSnapshotRefreshed: true,
+ previousWorkspaceId: "workspace-old",
+ activeWorkspaceId: "workspace-old",
+ });
+
+ expect(operation).toMatchObject({
+ metadata: {
+ kind: "config_freshness",
+ action: "refresh",
+ changedCategories: ["lifecycleCommands", "runtimeServices"],
+ changedCategoryLabels: ["workspace lifecycle commands", "runtime services"],
+ reuseRequested: true,
+ workspaceReused: true,
+ configSnapshotRefreshed: true,
+ previousWorkspaceId: "workspace-old",
+ activeWorkspaceId: "workspace-old",
+ },
+ system: expect.stringContaining("refreshed execution workspace config"),
+ });
+ const serialized = JSON.stringify(operation);
+ expect(serialized).toContain("runtime services");
+ expect(serialized).not.toContain("pnpm dev");
+ expect(serialized).not.toContain("0.0.0.0");
+ });
+
+ it("does not record a freshness operation when an unchanged workspace is simply reused", () => {
+ const metadata = buildWorkspaceConfigMetadata();
+ const decision = resolveExecutionWorkspaceConfigFreshness({
+ hasExistingWorkspace: true,
+ existingWorkspaceMetadata: persistedWorkspaceConfigFingerprint(metadata),
+ nextMetadata: metadata,
+ });
+
+ expect(buildWorkspaceConfigFreshnessOperation({
+ decision,
+ hasExistingWorkspace: true,
+ reuseRequested: true,
+ workspaceReused: true,
+ configSnapshotRefreshed: false,
+ previousWorkspaceId: "workspace-1",
+ activeWorkspaceId: "workspace-1",
+ })).toBeNull();
});
});
@@ -1075,6 +1298,332 @@ describe("shouldResetTaskSessionForModelChange", () => {
});
});
+type SessionConfigMetadata = Awaited<ReturnType<typeof buildEffectiveRunSessionConfigMetadata>>;
+
+async function buildSessionConfigMetadata(
+ overrides: Partial<Parameters<typeof buildEffectiveRunSessionConfigMetadata>[0]> = {},
+) {
+ return buildEffectiveRunSessionConfigMetadata({
+ adapterType: "codex_local",
+ effectiveAdapterConfig: {
+ command: "codex",
+ model: "gpt-5.4-mini",
+ env: {
+ OPENAI_API_KEY: "resolved-secret-value",
+ PLAIN_FLAG: "plain-value",
+ },
+ },
+ agentRuntimeConfig: {
+ heartbeat: {
+ maxConcurrentRuns: 1,
+ },
+ },
+ modelProfile: null,
+ issueOverrides: null,
+ workspaceConfig: {
+ requestedMode: "agent_default",
+ effectiveMode: "agent_default",
+ projectConfigRevisionAt: "2026-06-01T00:00:00.000Z",
+ },
+ environment: {
+ selectionSource: "default",
+ selectedEnvironmentId: "environment-1",
+ selectedEnvironment: {
+ id: "environment-1",
+ driver: "local",
+ configRevisionAt: "2026-06-01T00:00:00.000Z",
+ },
+ },
+ environmentEnv: {
+ ENVIRONMENT_FLAG: "enabled",
+ },
+ projectEnv: {
+ PROJECT_FLAG: "enabled",
+ },
+ routineEnv: null,
+ secretManifest: [
+ {
+ configPath: "env.OPENAI_API_KEY",
+ envKey: "OPENAI_API_KEY",
+ secretId: "secret-1",
+ bindingId: "binding-1",
+ secretKey: "openai-api-key",
+ version: 7,
+ provider: "local_encrypted",
+ outcome: "success",
+ },
+ ],
+ runtimeSkills: [
+ {
+ key: "paperclip",
+ runtimeName: "paperclip",
+ source: "/tmp/paperclip/runtime-skills/paperclip",
+ versionId: null,
+ currentVersionId: "skill-version-1",
+ sourceStatus: "available",
+ missingDetail: null,
+ },
+ ],
+ agentConfigRevision: {
+ id: "agent-config-revision-1",
+ changedKeys: ["adapterConfig"],
+ configRevisionAt: "2026-06-01T00:00:00.000Z",
+ },
+ ...overrides,
+ });
+}
+
+function sessionParamsWithConfigMetadata(
+ metadata: SessionConfigMetadata,
+ configuredModel = "gpt-5.4-mini",
+) {
+ return {
+ sessionId: "thread-1",
+ __paperclipConfiguredModel: configuredModel,
+ __paperclipConfigFingerprint: metadata.fingerprint,
+ __paperclipConfigFingerprintVersion: metadata.version,
+ __paperclipConfigCategories: metadata.categories,
+ __paperclipConfigCategoryFingerprints: metadata.categoryFingerprints,
+ };
+}
+
+describe("effective run session config freshness", () => {
+ it("resets when effective adapter config changes after model/profile/env resolution", async () => {
+ const base = await buildSessionConfigMetadata();
+ const next = await buildSessionConfigMetadata({
+ effectiveAdapterConfig: {
+ command: "codex",
+ model: "gpt-5.4-mini",
+ approvalPolicy: "never",
+ },
+ });
+
+ const decision = resolveTaskSessionConfigFreshness({
+ hasTaskSession: true,
+ configuredModel: "gpt-5.4-mini",
+ taskSessionParams: sessionParamsWithConfigMetadata(base),
+ configMetadata: next,
+ });
+
+ expect(decision).toMatchObject({
+ reset: true,
+ changedCategories: ["adapterConfig"],
+ });
+ expect(decision.reasons.join("\n")).toContain("adapter config");
+ });
+
+ it("keeps model-only compatibility as an additional reset reason", async () => {
+ const base = await buildSessionConfigMetadata();
+
+ const decision = resolveTaskSessionConfigFreshness({
+ hasTaskSession: true,
+ configuredModel: "gpt-5.4-mini",
+ taskSessionParams: sessionParamsWithConfigMetadata(base, "opencode/mimo-v2-pro-free"),
+ configMetadata: base,
+ });
+
+ expect(decision.reset).toBe(true);
+ expect(decision.reasons).toEqual([
+ 'configured model changed from "opencode/mimo-v2-pro-free" to "gpt-5.4-mini"',
+ ]);
+ });
+
+ it("freshens legacy task sessions that lack versioned config metadata", async () => {
+ const metadata = await buildSessionConfigMetadata();
+
+ const decision = resolveTaskSessionConfigFreshness({
+ hasTaskSession: true,
+ configuredModel: "gpt-5.4-mini",
+ taskSessionParams: {
+ sessionId: "thread-1",
+ __paperclipConfiguredModel: "gpt-5.4-mini",
+ },
+ configMetadata: metadata,
+ });
+
+ expect(decision.reset).toBe(true);
+ expect(decision.changedCategories).toEqual(metadata.categories);
+ expect(decision.reasons).toEqual(["effective run configuration fingerprint metadata is missing"]);
+ });
+
+ it("preserves legacy metadata gaps only for active accepted-plan continuation sessions", async () => {
+ const metadata = await buildSessionConfigMetadata();
+
+ const decision = resolveTaskSessionConfigFreshness({
+ hasTaskSession: true,
+ configuredModel: "gpt-5.4-mini",
+ taskSessionParams: {
+ sessionId: "thread-1",
+ __paperclipConfiguredModel: "gpt-5.4-mini",
+ },
+ configMetadata: metadata,
+ preserveLegacySessionWithoutConfigMetadata: true,
+ });
+
+ expect(decision.reset).toBe(false);
+ expect(decision.changedCategories).toEqual([]);
+ expect(decision.reasons).toEqual([]);
+ });
+
+ it("names safe categories for model profile, issue override, env, secret, and runtime skill drift", async () => {
+ const base = await buildSessionConfigMetadata();
+ const cases: Array<{
+ name: string;
+ category: string;
+ metadata: SessionConfigMetadata;
+ }> = [
+ {
+ name: "model profile",
+ category: "modelProfile",
+ metadata: await buildSessionConfigMetadata({
+ modelProfile: {
+ requested: "cheap",
+ applied: true,
+ configSource: "agent_runtime",
+ },
+ }),
+ },
+ {
+ name: "issue overrides",
+ category: "issueOverrides",
+ metadata: await buildSessionConfigMetadata({
+ issueOverrides: {
+ adapterConfig: {
+ reasoningEffort: "high",
+ },
+ },
+ }),
+ },
+ {
+ name: "project env bindings",
+ category: "envBindings",
+ metadata: await buildSessionConfigMetadata({
+ projectEnv: {
+ PROJECT_FLAG: "enabled",
+ NEW_PROJECT_FLAG: "present",
+ },
+ }),
+ },
+ {
+ name: "secret version",
+ category: "secrets",
+ metadata: await buildSessionConfigMetadata({
+ secretManifest: [
+ {
+ configPath: "env.OPENAI_API_KEY",
+ envKey: "OPENAI_API_KEY",
+ secretId: "secret-1",
+ bindingId: "binding-1",
+ secretKey: "openai-api-key",
+ version: 8,
+ provider: "local_encrypted",
+ outcome: "success",
+ },
+ ],
+ }),
+ },
+ {
+ name: "runtime skills",
+ category: "runtimeSkills",
+ metadata: await buildSessionConfigMetadata({
+ runtimeSkills: [
+ {
+ key: "paperclip",
+ runtimeName: "paperclip",
+ source: "/tmp/paperclip/runtime-skills/paperclip",
+ versionId: null,
+ currentVersionId: "skill-version-2",
+ sourceStatus: "available",
+ missingDetail: null,
+ },
+ ],
+ }),
+ },
+ ];
+
+ for (const testCase of cases) {
+ const decision = resolveTaskSessionConfigFreshness({
+ hasTaskSession: true,
+ configuredModel: "gpt-5.4-mini",
+ taskSessionParams: sessionParamsWithConfigMetadata(base),
+ configMetadata: testCase.metadata,
+ });
+
+ expect(decision.reset, testCase.name).toBe(true);
+ expect(decision.changedCategories, testCase.name).toContain(testCase.category);
+ }
+ });
+
+ it("detects instructions content drift without storing the contents", async () => {
+ const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-session-fingerprint-"));
+ const instructionsPath = path.join(root, "AGENTS.md");
+ await fs.writeFile(instructionsPath, "Version one instructions.\n", "utf8");
+ const base = await buildSessionConfigMetadata({
+ effectiveAdapterConfig: {
+ command: "codex",
+ model: "gpt-5.4-mini",
+ instructionsBundleMode: "managed",
+ instructionsRootPath: root,
+ instructionsEntryFile: "AGENTS.md",
+ instructionsFilePath: instructionsPath,
+ },
+ });
+ await fs.writeFile(instructionsPath, "Version two instructions.\n", "utf8");
+ const next = await buildSessionConfigMetadata({
+ effectiveAdapterConfig: {
+ command: "codex",
+ model: "gpt-5.4-mini",
+ instructionsBundleMode: "managed",
+ instructionsRootPath: root,
+ instructionsEntryFile: "AGENTS.md",
+ instructionsFilePath: instructionsPath,
+ },
+ });
+
+ const decision = resolveTaskSessionConfigFreshness({
+ hasTaskSession: true,
+ configuredModel: "gpt-5.4-mini",
+ taskSessionParams: sessionParamsWithConfigMetadata(base),
+ configMetadata: next,
+ });
+
+ expect(decision.reset).toBe(true);
+ expect(decision.changedCategories).toContain("instructions");
+ expect(next.fingerprints.sessionFingerprint.canonicalJson).not.toContain("Version two instructions");
+ });
+
+ it("does not read unbounded legacy instructions paths for config fingerprints", async () => {
+ const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-session-fingerprint-"));
+ const instructionsPath = path.join(root, "AGENTS.md");
+ await fs.writeFile(instructionsPath, "Legacy direct-path instructions.\n", "utf8");
+ const metadata = await buildSessionConfigMetadata({
+ effectiveAdapterConfig: {
+ command: "codex",
+ model: "gpt-5.4-mini",
+ instructionsFilePath: instructionsPath,
+ },
+ });
+
+ const canonical = metadata.fingerprints.sessionFingerprint.canonicalJson;
+
+ expect(canonical).toContain("missing_absolute_root");
+ expect(canonical).not.toContain("Legacy direct-path instructions");
+ expect(canonical).not.toContain("contentHash");
+ });
+
+ it("does not include raw secret or plain env values in canonical session metadata", async () => {
+ const metadata = await buildSessionConfigMetadata();
+ const canonical = metadata.fingerprints.sessionFingerprint.canonicalJson;
+
+ expect(canonical).toContain("secret-1");
+ expect(canonical).toContain('"version":7');
+ expect(canonical).not.toContain("resolved-secret-value");
+ expect(canonical).not.toContain("plain-value");
+ expect(canonical).not.toContain("enabled");
+ expect(canonical).not.toContain("openai-api-key");
+ });
+});
+
describe("stripConfiguredModelFromSessionParams", () => {
it("removes the internal model key from persisted session params", () => {
expect(
@@ -1108,6 +1657,25 @@ describe("stripConfiguredModelFromSessionParams", () => {
});
});
+describe("stripPaperclipSessionMetadataFromSessionParams", () => {
+ it("removes all internal Paperclip session metadata before adapter invocation", () => {
+ expect(
+ stripPaperclipSessionMetadataFromSessionParams({
+ sessionId: "thread-1",
+ cwd: "/tmp/project",
+ __paperclipConfiguredModel: "gpt-5.4-mini",
+ __paperclipConfigFingerprint: "v1:sha256:abc",
+ __paperclipConfigFingerprintVersion: 1,
+ __paperclipConfigCategories: ["adapterConfig"],
+ __paperclipConfigCategoryFingerprints: { adapterConfig: "v1:sha256:def" },
+ }),
+ ).toEqual({
+ sessionId: "thread-1",
+ cwd: "/tmp/project",
+ });
+ });
+});
+
describe("normalizeSessionParams", () => {
it("collapses an empty object to null", () => {
expect(normalizeSessionParams({})).toBeNull();
diff --git a/server/src/__tests__/workspace-runtime.test.ts b/server/src/__tests__/workspace-runtime.test.ts
index e9111520c3..4f066822dd 100644
--- a/server/src/__tests__/workspace-runtime.test.ts
+++ b/server/src/__tests__/workspace-runtime.test.ts
@@ -2057,6 +2057,45 @@ describe("realizeExecutionWorkspace", () => {
expect(actualHead).toBe(expectedHead);
}, 15_000);
+ it("does not reuse a missing persisted local filesystem workspace", async () => {
+ const baseCwd = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-workspace-base-"));
+ const missingCwd = path.join(baseCwd, "missing-workspace");
+
+ const restored = await ensurePersistedExecutionWorkspaceAvailable({
+ base: {
+ baseCwd,
+ source: "project_primary",
+ projectId: "project-1",
+ workspaceId: null,
+ repoUrl: null,
+ repoRef: null,
+ },
+ workspace: {
+ mode: "shared_workspace",
+ strategyType: "project_primary",
+ cwd: missingCwd,
+ providerRef: null,
+ projectId: "project-1",
+ projectWorkspaceId: null,
+ repoUrl: null,
+ baseRef: null,
+ branchName: null,
+ },
+ issue: {
+ id: "issue-1",
+ identifier: "PAP-453",
+ title: "Missing local workspace",
+ },
+ agent: {
+ id: "agent-1",
+ name: "Codex Coder",
+ companyId: "company-1",
+ },
+ });
+
+ expect(restored).toBeNull();
+ });
+
it("reprovisions an existing persisted git worktree before manual control starts it", async () => {
const repoRoot = await createTempRepo();
await fs.mkdir(path.join(repoRoot, "scripts"), { recursive: true });
@@ -2195,6 +2234,7 @@ describe("realizeExecutionWorkspace", () => {
it("auto-detects the default branch via symbolic-ref when origin/HEAD is set", async () => {
const repoRoot = await createTempRepo("main");
+ await runGit(repoRoot, ["branch", "-f", "master", "main"]);
const bareRemote = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-worktree-bare-symref-"));
await runGit(bareRemote, ["init", "--bare"]);
diff --git a/server/src/services/effective-run-config-fingerprints.ts b/server/src/services/effective-run-config-fingerprints.ts
new file mode 100644
index 0000000000..3dd19c1782
--- /dev/null
+++ b/server/src/services/effective-run-config-fingerprints.ts
@@ -0,0 +1,492 @@
+import { createHash } from "node:crypto";
+import type { RuntimeSecretManifestEntry } from "./secrets.js";
+
+export const EFFECTIVE_RUN_CONFIG_FINGERPRINT_VERSION = 1;
+export const EFFECTIVE_RUN_CONFIG_FINGERPRINT_ALGORITHM = "sha256";
+export const EFFECTIVE_RUN_CONFIG_FINGERPRINT_CATEGORIES = ["session", "workspace", "lease"] as const;
+
+export type EffectiveRunConfigFingerprintCategory =
+ (typeof EFFECTIVE_RUN_CONFIG_FINGERPRINT_CATEGORIES)[number];
+
+export type EffectiveRunConfigChangedCategory = EffectiveRunConfigFingerprintCategory;
+
+export type EffectiveRunConfigCanonicalValue =
+ | null
+ | boolean
+ | number
+ | string
+ | EffectiveRunConfigCanonicalValue[]
+ | { [key: string]: EffectiveRunConfigCanonicalValue };
+
+export interface EffectiveRunConfigSecretVersionMetadata {
+ configPath: string;
+ envKey: string | null;
+ secretId: string;
+ bindingId?: string | null;
+ version: number | string;
+ provider?: string | null;
+ providerVersionRef?: string | null;
+ outcome?: "success" | "failure" | null;
+}
+
+export type EffectiveRunConfigSecretManifestEntry =
+ | RuntimeSecretManifestEntry
+ | EffectiveRunConfigSecretVersionMetadata;
+
+export interface EffectiveRunConfigFingerprintInput {
+ session?: unknown;
+ workspace?: unknown;
+ lease?: unknown;
+ secretManifest?: readonly EffectiveRunConfigSecretManifestEntry[];
+}
+
+export interface EffectiveRunConfigFingerprint {
+ version: typeof EFFECTIVE_RUN_CONFIG_FINGERPRINT_VERSION;
+ category: EffectiveRunConfigFingerprintCategory;
+ algorithm: typeof EFFECTIVE_RUN_CONFIG_FINGERPRINT_ALGORITHM;
+ fingerprint: string;
+ canonicalJson: string;
+}
+
+export interface EffectiveRunConfigFingerprints {
+ version: typeof EFFECTIVE_RUN_CONFIG_FINGERPRINT_VERSION;
+ categories: readonly EffectiveRunConfigFingerprintCategory[];
+ sessionFingerprint: EffectiveRunConfigFingerprint;
+ workspaceFingerprint: EffectiveRunConfigFingerprint;
+ leaseFingerprint: EffectiveRunConfigFingerprint;
+}
+
+export interface EffectiveRunConfigFingerprintDiff {
+ version: typeof EFFECTIVE_RUN_CONFIG_FINGERPRINT_VERSION;
+ hasChanges: boolean;
+ changedCategories: EffectiveRunConfigChangedCategory[];
+ changed: Record<EffectiveRunConfigChangedCategory, boolean>;
+}
+
+const OMIT = Symbol("omit-from-effective-run-config-fingerprint");
+const REDACTED_VALUE: EffectiveRunConfigCanonicalValue = { type: "redacted", present: true };
+
+const GENERATED_RUNTIME_ENV_KEY_RE = /^PAPERCLIP_/;
+const SENSITIVE_CONFIG_KEY_RE =
+ /(?:api[_-]?key|access[_-]?token|auth(?:orization)?|bearer|cookie|credential|jwt|password|passwd|private[_-]?key|secret|token)$/i;
+const VOLATILE_CONFIG_KEYS = new Set([
+ "checkoutRunId",
+ "executionRunId",
+ "externalRunId",
+ "heartbeatRunId",
+ "invocationId",
+ "leaseId",
+ "providerLeaseId",
+ "requestId",
+ "runId",
+ "sessionDisplayId",
+ "sessionId",
+ "spanId",
+ "traceId",
+]);
+const HOST_NOISE_KEYS = new Set([
+ "agentHome",
+ "homeDir",
+ "hostCwd",
+ "localHome",
+ "tempDir",
+ "tmpDir",
+ "userHome",
+]);
+const SESSION_HOST_PATH_KEYS = new Set([
+ "cwd",
+ "localPath",
+ "remoteCwd",
+ "workspaceCwd",
+ "workspacePath",
+ "workspaceRemoteDir",
+ "worktreePath",
+]);
+
+type SecretManifestIndex = {
+ byConfigPath: Map<string, EffectiveRunConfigSecretVersionMetadata>;
+ byEnvKey: Map<string, EffectiveRunConfigSecretVersionMetadata>;
+};
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+ return Boolean(value)
+ && typeof value === "object"
+ && !Array.isArray(value)
+ && !(value instanceof Date);
+}
+
+function readString(value: unknown) {
+ return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+function readVersion(value: unknown) {
+ if (typeof value === "number" && Number.isFinite(value)) return value;
+ return readString(value);
+}
+
+function normalizeSecretManifestEntry(
+ entry: EffectiveRunConfigSecretManifestEntry,
+): EffectiveRunConfigSecretVersionMetadata | null {
+ const record = entry as Record<string, unknown>;
+ const secretId = readString(record.secretId);
+ const version = readVersion(record.version);
+ if (!secretId || version === null) return null;
+
+ const normalized: EffectiveRunConfigSecretVersionMetadata = {
+ configPath: readString(record.configPath) ?? "",
+ envKey: readString(record.envKey),
+ secretId,
+ version,
+ };
+ const bindingId = readString(record.bindingId);
+ const provider = readString(record.provider);
+ const providerVersionRef = readString(record.providerVersionRef);
+ const outcome = record.outcome === "success" || record.outcome === "failure"
+ ? record.outcome
+ : null;
+ if (bindingId !== null) normalized.bindingId = bindingId;
+ if (provider !== null) normalized.provider = provider;
+ if (providerVersionRef !== null) normalized.providerVersionRef = providerVersionRef;
+ if (outcome !== null) normalized.outcome = outcome;
+ return normalized;
+}
+
+function buildSecretManifestIndex(
+ manifest: readonly EffectiveRunConfigSecretManifestEntry[] | undefined,
+): SecretManifestIndex {
+ const byConfigPath = new Map<string, EffectiveRunConfigSecretVersionMetadata>();
+ const byEnvKey = new Map<string, EffectiveRunConfigSecretVersionMetadata>();
+ for (const entry of manifest ?? []) {
+ const normalized = normalizeSecretManifestEntry(entry);
+ if (!normalized) continue;
+ if (normalized.configPath) byConfigPath.set(normalized.configPath, normalized);
+ if (normalized.envKey) byEnvKey.set(normalized.envKey, normalized);
+ }
+ return { byConfigPath, byEnvKey };
+}
+
+function canonicalSecretMetadata(
+ metadata: EffectiveRunConfigSecretVersionMetadata,
+): EffectiveRunConfigCanonicalValue {
+ return omitNullish({
+ type: "secret_ref",
+ configPath: metadata.configPath || undefined,
+ envKey: metadata.envKey ?? undefined,
+ secretId: metadata.secretId,
+ bindingId: metadata.bindingId ?? undefined,
+ version: metadata.version,
+ provider: metadata.provider ?? undefined,
+ providerVersionRef: metadata.providerVersionRef ?? undefined,
+ outcome: metadata.outcome ?? undefined,
+ });
+}
+
+function isSecretRefBinding(value: unknown): value is Record<string, unknown> {
+ return isPlainObject(value)
+ && value.type === "secret_ref"
+ && typeof value.secretId === "string"
+ && value.secretId.trim().length > 0;
+}
+
+function canonicalSecretRefBinding(
+ value: Record<string, unknown>,
+ configPath: string,
+): EffectiveRunConfigCanonicalValue {
+ return omitNullish({
+ type: "secret_ref",
+ configPath,
+ secretId: readString(value.secretId),
+ versionSelector: readVersion(value.version) ?? "latest",
+ unresolved: true,
+ });
+}
+
+function omitNullish(record: Record<string, unknown>): EffectiveRunConfigCanonicalValue {
+ return Object.fromEntries(
+ Object.entries(record).filter(([, value]) => value !== undefined && value !== null),
+ ) as EffectiveRunConfigCanonicalValue;
+}
+
+function isTimestampNoiseKey(key: string) {
+ return /(created|updated|started|finished|completed|cancelled|resolved|used|heartbeat)At$/i.test(key)
+ && !/(revision|version)/i.test(key);
+}
+
+function shouldOmitObjectKey(
+ category: EffectiveRunConfigFingerprintCategory,
+ key: string,
+) {
+ if (VOLATILE_CONFIG_KEYS.has(key)) return true;
+ if (HOST_NOISE_KEYS.has(key)) return true;
+ if (isTimestampNoiseKey(key)) return true;
+ if (category === "session" && SESSION_HOST_PATH_KEYS.has(key)) return true;
+ if (category === "lease" && (key === "remoteCwd" || key === "workspaceRemoteDir")) return true;
+ return false;
+}
+
+function stableStringify(value: EffectiveRunConfigCanonicalValue): string {
+ if (Array.isArray(value)) {
+ return `[${value.map((entry) => stableStringify(entry)).join(",")}]`;
+ }
+ if (value && typeof value === "object") {
+ const record = value as Record<string, EffectiveRunConfigCanonicalValue>;
+ return `{${Object.keys(record)
+ .sort()
+ .map((key) => `${JSON.stringify(key)}:${stableStringify(record[key] ?? null)}`)
+ .join(",")}}`;
+ }
+ return JSON.stringify(value);
+}
+
+function canonicalizePlainEnvValueForHash(value: unknown): EffectiveRunConfigCanonicalValue {
+ if (value === undefined || value === null) return null;
+ if (Array.isArray(value)) {
+ return value.map((entry) => canonicalizePlainEnvValueForHash(entry));
+ }
+ if (isPlainObject(value)) {
+ const out: Record<string, EffectiveRunConfigCanonicalValue> = {};
+ for (const key of Object.keys(value).sort()) {
+ const next = canonicalizePlainEnvValueForHash(value[key]);
+ if (next !== null) out[key] = next;
+ }
+ return out;
+ }
+ if (typeof value === "number") {
+ return Number.isFinite(value) ? value : null;
+ }
+ if (typeof value === "bigint") {
+ return value.toString();
+ }
+ if (typeof value === "boolean" || typeof value === "string") {
+ return value;
+ }
+ return String(value);
+}
+
+function hashPlainEnvValue(value: unknown): string | null {
+ if (value === undefined || value === null) return null;
+ const canonicalJson = stableStringify(canonicalizePlainEnvValueForHash(value));
+ return `sha256:${createHash("sha256").update(canonicalJson).digest("hex")}`;
+}
+
+function canonicalizeEnvRecord(
+ envValue: unknown,
+ context: CanonicalizeContext,
+): EffectiveRunConfigCanonicalValue | typeof OMIT {
+ if (!isPlainObject(envValue)) return {};
+ const canonicalEnv: Record<string, EffectiveRunConfigCanonicalValue> = {};
+ for (const key of Object.keys(envValue).sort()) {
+ if (GENERATED_RUNTIME_ENV_KEY_RE.test(key)) continue;
+ const manifestEntry = context.secrets.byConfigPath.get(`env.${key}`) ?? context.secrets.byEnvKey.get(key);
+ if (manifestEntry) {
+ canonicalEnv[key] = canonicalSecretMetadata(manifestEntry);
+ continue;
+ }
+ const rawBinding = envValue[key];
+ if (isSecretRefBinding(rawBinding)) {
+ canonicalEnv[key] = canonicalSecretRefBinding(rawBinding, `env.${key}`);
+ continue;
+ }
+ canonicalEnv[key] = omitNullish({
+ type: "plain_env",
+ present: rawBinding !== undefined && rawBinding !== null,
+ valueHash: hashPlainEnvValue(rawBinding),
+ });
+ }
+ return Object.keys(canonicalEnv).length > 0 ? canonicalEnv : OMIT;
+}
+
+type CanonicalizeContext = {
+ category: EffectiveRunConfigFingerprintCategory;
+ path: string[];
+ secrets: SecretManifestIndex;
+};
+
+function canonicalizeValue(
+ value: unknown,
+ context: CanonicalizeContext,
+): EffectiveRunConfigCanonicalValue | typeof OMIT {
+ if (value === undefined || value instanceof Date) return OMIT;
+ if (value === null) return null;
+ if (Array.isArray(value)) {
+ return value.map((entry, index) => {
+ const next = canonicalizeValue(entry, { ...context, path: [...context.path, String(index)] });
+ return next === OMIT ? null : next;
+ });
+ }
+ if (isSecretRefBinding(value)) {
+ return canonicalSecretRefBinding(value, context.path.join("."));
+ }
+ if (isPlainObject(value)) {
+ const canonicalObject: Record<string, EffectiveRunConfigCanonicalValue> = {};
+ for (const key of Object.keys(value).sort()) {
+ if (key === "env") {
+ const env = canonicalizeEnvRecord(value[key], { ...context, path: [...context.path, key] });
+ if (env !== OMIT) canonicalObject[key] = env;
+ continue;
+ }
+ if (shouldOmitObjectKey(context.category, key)) continue;
+ if (SENSITIVE_CONFIG_KEY_RE.test(key)) {
+ canonicalObject[key] = REDACTED_VALUE;
+ continue;
+ }
+ const next = canonicalizeValue(value[key], { ...context, path: [...context.path, key] });
+ if (next !== OMIT) canonicalObject[key] = next;
+ }
+ return Object.keys(canonicalObject).length > 0 ? canonicalObject : {};
+ }
+ if (typeof value === "number") {
+ return Number.isFinite(value) ? value : null;
+ }
+ if (typeof value === "bigint") {
+ return value.toString();
+ }
+ if (typeof value === "boolean" || typeof value === "string") {
+ return value;
+ }
+ return null;
+}
+
+export function canonicalizeEffectiveRunConfigCategory(input: {
+ category: EffectiveRunConfigFingerprintCategory;
+ value: unknown;
+ secretManifest?: readonly EffectiveRunConfigSecretManifestEntry[];
+}): EffectiveRunConfigCanonicalValue {
+ const canonical = canonicalizeValue(input.value ?? {}, {
+ category: input.category,
+ path: [],
+ secrets: buildSecretManifestIndex(input.secretManifest),
+ });
+ return canonical === OMIT ? {} : canonical;
+}
+
+function createCategoryFingerprint(input: {
+ category: EffectiveRunConfigFingerprintCategory;
+ value: unknown;
+ secretManifest?: readonly EffectiveRunConfigSecretManifestEntry[];
+}): EffectiveRunConfigFingerprint {
+ const canonicalValue = canonicalizeEffectiveRunConfigCategory(input);
+ const canonicalJson = stableStringify({
+ version: EFFECTIVE_RUN_CONFIG_FINGERPRINT_VERSION,
+ category: input.category,
+ value: canonicalValue,
+ });
+ const digest = createHash("sha256").update(canonicalJson).digest("hex");
+ return {
+ version: EFFECTIVE_RUN_CONFIG_FINGERPRINT_VERSION,
+ category: input.category,
+ algorithm: EFFECTIVE_RUN_CONFIG_FINGERPRINT_ALGORITHM,
+ fingerprint: `v${EFFECTIVE_RUN_CONFIG_FINGERPRINT_VERSION}:sha256:${digest}`,
+ canonicalJson,
+ };
+}
+
+function createCategoryFingerprintFromCanonicalValue(input: {
+ category: EffectiveRunConfigFingerprintCategory;
+ value: EffectiveRunConfigCanonicalValue;
+}): EffectiveRunConfigFingerprint {
+ const canonicalJson = stableStringify({
+ version: EFFECTIVE_RUN_CONFIG_FINGERPRINT_VERSION,
+ category: input.category,
+ value: input.value,
+ });
+ const digest = createHash("sha256").update(canonicalJson).digest("hex");
+ return {
+ version: EFFECTIVE_RUN_CONFIG_FINGERPRINT_VERSION,
+ category: input.category,
+ algorithm: EFFECTIVE_RUN_CONFIG_FINGERPRINT_ALGORITHM,
+ fingerprint: `v${EFFECTIVE_RUN_CONFIG_FINGERPRINT_VERSION}:sha256:${digest}`,
+ canonicalJson,
+ };
+}
+
+function canonicalRecord(value: EffectiveRunConfigCanonicalValue) {
+ return value && typeof value === "object" && !Array.isArray(value)
+ ? value as Record<string, EffectiveRunConfigCanonicalValue>
+ : {};
+}
+
+export function createEffectiveRunConfigSubcategoryFingerprints<T extends string>(input: {
+ category: EffectiveRunConfigFingerprintCategory;
+ value: Record<T, unknown>;
+ subcategories: readonly T[];
+ secretManifest?: readonly EffectiveRunConfigSecretManifestEntry[];
+}): Record<T, string> {
+ const canonicalValue = canonicalizeEffectiveRunConfigCategory({
+ category: input.category,
+ value: input.value,
+ secretManifest: input.secretManifest,
+ });
+ const record = canonicalRecord(canonicalValue);
+ return Object.fromEntries(
+ input.subcategories.map((subcategory) => {
+ const value = Object.prototype.hasOwnProperty.call(record, subcategory)
+ ? { [subcategory]: record[subcategory] ?? null }
+ : {};
+ return [
+ subcategory,
+ createCategoryFingerprintFromCanonicalValue({
+ category: input.category,
+ value,
+ }).fingerprint,
+ ];
+ }),
+ ) as Record<T, string>;
+}
+
+export function createEffectiveRunConfigFingerprints(
+ input: EffectiveRunConfigFingerprintInput,
+): EffectiveRunConfigFingerprints {
+ return {
+ version: EFFECTIVE_RUN_CONFIG_FINGERPRINT_VERSION,
+ categories: EFFECTIVE_RUN_CONFIG_FINGERPRINT_CATEGORIES,
+ sessionFingerprint: createCategoryFingerprint({
+ category: "session",
+ value: input.session,
+ secretManifest: input.secretManifest,
+ }),
+ workspaceFingerprint: createCategoryFingerprint({
+ category: "workspace",
+ value: input.workspace,
+ secretManifest: input.secretManifest,
+ }),
+ leaseFingerprint: createCategoryFingerprint({
+ category: "lease",
+ value: input.lease,
+ secretManifest: input.secretManifest,
+ }),
+ };
+}
+
+function fingerprintForCategory(
+ fingerprints: EffectiveRunConfigFingerprints,
+ category: EffectiveRunConfigFingerprintCategory,
+) {
+ switch (category) {
+ case "session":
+ return fingerprints.sessionFingerprint.fingerprint;
+ case "workspace":
+ return fingerprints.workspaceFingerprint.fingerprint;
+ case "lease":
+ return fingerprints.leaseFingerprint.fingerprint;
+ }
+}
+
+export function diffEffectiveRunConfigFingerprints(
+ previous: EffectiveRunConfigFingerprints,
+ next: EffectiveRunConfigFingerprints,
+): EffectiveRunConfigFingerprintDiff {
+ const changed = Object.fromEntries(
+ EFFECTIVE_RUN_CONFIG_FINGERPRINT_CATEGORIES.map((category) => [
+ category,
+ fingerprintForCategory(previous, category) !== fingerprintForCategory(next, category),
+ ]),
+ ) as Record<EffectiveRunConfigChangedCategory, boolean>;
+ const changedCategories = EFFECTIVE_RUN_CONFIG_FINGERPRINT_CATEGORIES.filter((category) => changed[category]);
+ return {
+ version: EFFECTIVE_RUN_CONFIG_FINGERPRINT_VERSION,
+ hasChanges: changedCategories.length > 0,
+ changedCategories,
+ changed,
+ };
+}
diff --git a/server/src/services/environment-runtime.ts b/server/src/services/environment-runtime.ts
index bf3de1e2e5..151b181a7c 100644
--- a/server/src/services/environment-runtime.ts
+++ b/server/src/services/environment-runtime.ts
@@ -1,7 +1,7 @@
import { createHash, randomUUID } from "node:crypto";
import { and, eq, inArray } from "drizzle-orm";
import type { Db } from "@paperclipai/db";
-import { environmentLeases } from "@paperclipai/db";
+import { companySecrets, companySecretVersions, environmentLeases } from "@paperclipai/db";
import type {
Environment,
EnvironmentLease,
@@ -18,10 +18,16 @@ import type {
import { ensureSshWorkspaceReady } from "@paperclipai/adapter-utils/ssh";
import { environmentService } from "./environments.js";
import {
+ collectEnvironmentSecretRefs,
parseEnvironmentDriverConfig,
resolveEnvironmentDriverConfigForRuntime,
stripSandboxProviderEnvelope,
} from "./environment-config.js";
+import {
+ createEffectiveRunConfigFingerprints,
+ type EffectiveRunConfigFingerprint,
+ type EffectiveRunConfigSecretVersionMetadata,
+} from "./effective-run-config-fingerprints.js";
import {
acquireSandboxProviderLease,
destroySandboxProviderLease,
@@ -255,6 +261,146 @@ function reusableRuntimeFingerprint(input: {
.digest("hex");
}
+function serializeLeaseFingerprint(
+ fingerprint: EffectiveRunConfigFingerprint | null | undefined,
+): Record<string, unknown> | null {
+ if (!fingerprint) return null;
+ return {
+ version: fingerprint.version,
+ category: fingerprint.category,
+ algorithm: fingerprint.algorithm,
+ fingerprint: fingerprint.fingerprint,
+ };
+}
+
+function readLeaseFingerprint(value: unknown): string | null {
+ return isRecord(value) ? readString(value.fingerprint) : null;
+}
+
+async function buildEnvironmentSecretMetadataForLeaseFingerprint(input: {
+ db: Db;
+ companyId: string;
+ environment: Environment;
+}): Promise<EffectiveRunConfigSecretVersionMetadata[]> {
+ const refs = await collectEnvironmentSecretRefs({
+ db: input.db,
+ environment: input.environment,
+ });
+ if (refs.length === 0) return [];
+
+ const secretIds = [...new Set(refs.map((ref) => ref.secretId))];
+ const secretRows = await input.db
+ .select()
+ .from(companySecrets)
+ .where(inArray(companySecrets.id, secretIds));
+ const secretsById = new Map(
+ secretRows
+ .filter((secret) => secret.companyId === input.companyId)
+ .map((secret) => [secret.id, secret]),
+ );
+
+ const versionRequests = refs.flatMap((ref) => {
+ const secret = secretsById.get(ref.secretId);
+ if (!secret) return [];
+ const resolvedVersion = ref.versionSelector === "latest" || ref.versionSelector === undefined
+ ? secret.latestVersion
+ : ref.versionSelector;
+ return typeof resolvedVersion === "number"
+ ? [{ secretId: secret.id, version: resolvedVersion }]
+ : [];
+ });
+ const versionSecretIds = [...new Set(versionRequests.map((request) => request.secretId))];
+ const versions = [...new Set(versionRequests.map((request) => request.version))];
+ const versionRows = versionSecretIds.length > 0 && versions.length > 0
+ ? await input.db
+ .select()
+ .from(companySecretVersions)
+ .where(
+ and(
+ inArray(companySecretVersions.secretId, versionSecretIds),
+ inArray(companySecretVersions.version, versions),
+ ),
+ )
+ : [];
+ const versionsBySecretAndNumber = new Map(
+ versionRows.map((row) => [`${row.secretId}:${row.version}`, row]),
+ );
+
+ const metadata: EffectiveRunConfigSecretVersionMetadata[] = [];
+ for (const ref of refs) {
+ const secret = secretsById.get(ref.secretId);
+ if (!secret) {
+ metadata.push({
+ configPath: ref.configPath,
+ envKey: null,
+ secretId: ref.secretId,
+ version: typeof ref.versionSelector === "number" ? ref.versionSelector : "unresolved",
+ outcome: "failure",
+ });
+ continue;
+ }
+
+ const resolvedVersion = ref.versionSelector === "latest" || ref.versionSelector === undefined
+ ? secret.latestVersion
+ : ref.versionSelector;
+ const versionRow = typeof resolvedVersion === "number"
+ ? versionsBySecretAndNumber.get(`${secret.id}:${resolvedVersion}`) ?? null
+ : null;
+
+ metadata.push({
+ configPath: ref.configPath,
+ envKey: null,
+ secretId: secret.id,
+ version: resolvedVersion,
+ provider: secret.provider,
+ providerVersionRef: versionRow?.providerVersionRef ?? null,
+ outcome: versionRow ? "success" : "failure",
+ });
+ }
+
+ return metadata;
+}
+
+async function buildReusableSandboxLeaseFingerprint(input: {
+ db: Db;
+ companyId: string;
+ environment: Environment;
+ executionWorkspaceId: string | null;
+ agentId: string | null;
+ adapterType: string | null;
+ provider: string;
+ providerConfig: Record<string, unknown>;
+ providerPlugin?: {
+ id: string;
+ pluginKey: string;
+ packageName: string;
+ version: string;
+ } | null;
+}): Promise<EffectiveRunConfigFingerprint> {
+ const secretMetadata = await buildEnvironmentSecretMetadataForLeaseFingerprint({
+ db: input.db,
+ companyId: input.companyId,
+ environment: input.environment,
+ });
+ return createEffectiveRunConfigFingerprints({
+ lease: {
+ companyId: input.companyId,
+ environment: {
+ id: input.environment.id,
+ driver: input.environment.driver,
+ },
+ executionWorkspaceId: input.executionWorkspaceId,
+ agentId: input.agentId,
+ adapterType: input.adapterType,
+ provider: input.provider,
+ providerPlugin: input.providerPlugin ?? null,
+ providerConfig: input.providerConfig,
+ secrets: secretMetadata,
+ },
+ secretManifest: secretMetadata,
+ }).leaseFingerprint;
+}
+
function buildReusableSandboxLeaseScope(input: {
companyId: string;
environmentId: string;
@@ -263,6 +409,7 @@ function buildReusableSandboxLeaseScope(input: {
adapterType: string | null;
provider: string;
config: Record<string, unknown>;
+ leaseFingerprint?: EffectiveRunConfigFingerprint | null;
providerMetadata?: Record<string, unknown> | null;
}): Record<string, unknown> | null {
if (!input.executionWorkspaceId || !input.agentId) return null;
@@ -285,6 +432,9 @@ function buildReusableSandboxLeaseScope(input: {
adapterType,
config: input.config,
}),
+ ...(input.leaseFingerprint
+ ? { leaseFingerprint: serializeLeaseFingerprint(input.leaseFingerprint) }
+ : {}),
...(remoteCwd ? { remoteCwd } : {}),
...(workspaceSentinel ? { workspaceSentinel } : {}),
};
@@ -299,24 +449,48 @@ function reusableSandboxLeaseScopeMatches(input: {
adapterType: string | null;
provider: string;
config: Record<string, unknown>;
+ leaseFingerprint?: EffectiveRunConfigFingerprint | null;
+ allowLegacyRuntimeFingerprint?: boolean;
}): boolean {
if (!input.executionWorkspaceId || !input.agentId) return false;
const scope = input.lease.metadata?.reusableSandboxLease;
if (!isRecord(scope)) return false;
const adapterType = input.adapterType ?? null;
- return (
+ const baseScopeMatches =
scope.companyId === input.companyId &&
scope.environmentId === input.environmentId &&
scope.executionWorkspaceId === input.executionWorkspaceId &&
scope.agentId === input.agentId &&
scope.adapterType === adapterType &&
- scope.provider === input.provider &&
- scope.runtimeFingerprint === reusableRuntimeFingerprint({
- provider: input.provider,
- adapterType,
- config: input.config,
- })
- );
+ scope.provider === input.provider;
+ if (!baseScopeMatches) return false;
+
+ const expectedLeaseFingerprint = input.leaseFingerprint?.fingerprint ?? null;
+ if (expectedLeaseFingerprint) {
+ const storedLeaseFingerprint = readLeaseFingerprint(scope.leaseFingerprint);
+ if (storedLeaseFingerprint) {
+ return storedLeaseFingerprint === expectedLeaseFingerprint;
+ }
+ if (!input.allowLegacyRuntimeFingerprint) return false;
+ }
+
+ return scope.runtimeFingerprint === reusableRuntimeFingerprint({
+ provider: input.provider,
+ adapterType,
+ config: input.config,
+ });
+}
+
+function reusableLeaseCanBeResumed(input: {
+ lease: Pick<EnvironmentLease, "status" | "heartbeatRunId">;
+ heartbeatRunId: string | null;
+}): boolean {
+ if (input.lease.status === "released" || input.lease.status === "retained") return true;
+ return input.lease.status === "active" && input.heartbeatRunId !== null && input.lease.heartbeatRunId === input.heartbeatRunId;
+}
+
+function reusableLeaseCanBeCleanedUp(lease: Pick<EnvironmentLease, "status">): boolean {
+ return lease.status === "released" || lease.status === "retained";
}
export function findReusableSandboxLeaseId(input: {
@@ -531,6 +705,23 @@ function createSandboxEnvironmentDriver(
};
}
+ async function cleanupObsoleteReusableSandboxLeases(input: {
+ environment: Environment;
+ leases: EnvironmentLease[];
+ reusableLeases: EnvironmentLease[];
+ }) {
+ const reusableIds = new Set(input.reusableLeases.map((lease) => lease.id));
+ for (const lease of input.leases) {
+ if (reusableIds.has(lease.id)) continue;
+ if (!reusableLeaseCanBeCleanedUp(lease)) continue;
+ await destroyReusableSandboxLease({
+ environment: input.environment,
+ lease,
+ failureReason: "lease_fingerprint_mismatch",
+ });
+ }
+ }
+
return {
driver: "sandbox",
@@ -573,14 +764,38 @@ function createSandboxEnvironmentDriver(
const workerConfig = stripSandboxProviderEnvelope(parsed.config);
const storedConfig = storedParsed.config;
+ const providerConfigForLease = sandboxConfigForLeaseMetadata(storedConfig);
const supportsReusableLeases = pluginProvider.resolved.driver.supportsReusableLeases === true;
+ const leaseFingerprint =
+ supportsReusableLeases &&
+ parsed.config.reuseLease &&
+ input.heartbeatRunId !== null &&
+ input.executionWorkspaceId !== null &&
+ input.agentId !== null
+ ? await buildReusableSandboxLeaseFingerprint({
+ db,
+ companyId: input.companyId,
+ environment: input.environment,
+ executionWorkspaceId: input.executionWorkspaceId,
+ agentId: input.agentId,
+ adapterType: input.adapterType,
+ provider: parsed.config.provider,
+ providerConfig: providerConfigForLease,
+ providerPlugin: {
+ id: pluginProvider.resolved.plugin.id,
+ pluginKey: pluginProvider.resolved.plugin.pluginKey,
+ packageName: pluginProvider.resolved.plugin.packageName,
+ version: pluginProvider.resolved.plugin.version,
+ },
+ })
+ : null;
// Ad-hoc tests (heartbeatRunId === null) must never resume an existing
// provider lease. If they did, releasing the test lease at the end of
// the probe would tear down the live heartbeat run that owns it.
// We also filter out leases whose policy is not reuse_by_environment
// and whose status is not reusable so non-reusable, cleanup-pending,
// or terminal rows cannot be matched.
- const reusableExistingLeases =
+ const reusableCandidateLeases =
supportsReusableLeases &&
parsed.config.reuseLease &&
input.heartbeatRunId !== null &&
@@ -589,21 +804,35 @@ function createSandboxEnvironmentDriver(
? (await environmentsSvc.listLeases(input.environment.id))
.filter((lease) =>
lease.leasePolicy === "reuse_by_environment" &&
- ["active", "released", "retained"].includes(lease.status) &&
+ reusableLeaseCanBeResumed({ lease, heartbeatRunId: input.heartbeatRunId }) &&
lease.executionWorkspaceId === input.executionWorkspaceId &&
- lease.metadata?.agentId === input.agentId &&
- reusableSandboxLeaseScopeMatches({
- lease,
- companyId: input.companyId,
- environmentId: input.environment.id,
- executionWorkspaceId: input.executionWorkspaceId,
- agentId: input.agentId,
- adapterType: input.adapterType,
- provider: parsed.config.provider,
- config: sandboxConfigForLeaseMetadata(storedConfig),
- }),
+ lease.metadata?.agentId === input.agentId,
)
: [];
+ const reusableExistingLeases = reusableCandidateLeases.filter((lease) =>
+ reusableSandboxLeaseScopeMatches({
+ lease,
+ companyId: input.companyId,
+ environmentId: input.environment.id,
+ executionWorkspaceId: input.executionWorkspaceId,
+ agentId: input.agentId,
+ adapterType: input.adapterType,
+ provider: parsed.config.provider,
+ config: providerConfigForLease,
+ leaseFingerprint,
+ allowLegacyRuntimeFingerprint:
+ lease.status === "active" &&
+ input.heartbeatRunId !== null &&
+ lease.heartbeatRunId === input.heartbeatRunId,
+ }),
+ );
+ if (reusableCandidateLeases.length > reusableExistingLeases.length) {
+ await cleanupObsoleteReusableSandboxLeases({
+ environment: input.environment,
+ leases: reusableCandidateLeases,
+ reusableLeases: reusableExistingLeases,
+ });
+ }
const reusableProviderLeaseId =
supportsReusableLeases &&
parsed.config.reuseLease &&
@@ -694,7 +923,8 @@ function createSandboxEnvironmentDriver(
agentId: input.agentId,
adapterType: input.adapterType,
provider: parsed.config.provider,
- config: sandboxConfigForLeaseMetadata(storedConfig),
+ config: providerConfigForLease,
+ leaseFingerprint,
providerMetadata: sanitizedProviderMetadata,
})
: null;
@@ -730,38 +960,72 @@ function createSandboxEnvironmentDriver(
// so non-reusable, cleanup-pending, or terminal rows can never be matched.
const builtinSandboxProvider = getBuiltinSandboxProvider(parsed.config.provider);
const supportsReusableLeases = builtinSandboxProvider?.supportsReusableLeases === true;
+ const providerConfigForLease = sandboxConfigForLeaseMetadata(parsed.config);
+ const leaseFingerprint =
+ supportsReusableLeases &&
+ parsed.config.reuseLease &&
+ input.heartbeatRunId !== null &&
+ input.executionWorkspaceId !== null &&
+ input.agentId !== null
+ ? await buildReusableSandboxLeaseFingerprint({
+ db,
+ companyId: input.companyId,
+ environment: input.environment,
+ executionWorkspaceId: input.executionWorkspaceId,
+ agentId: input.agentId,
+ adapterType: input.adapterType,
+ provider: parsed.config.provider,
+ providerConfig: providerConfigForLease,
+ })
+ : null;
+ const reusableCandidateLeases =
+ supportsReusableLeases &&
+ parsed.config.reuseLease &&
+ input.heartbeatRunId !== null &&
+ input.executionWorkspaceId !== null &&
+ input.agentId !== null
+ ? (await environmentsSvc.listLeases(input.environment.id))
+ .filter((lease) =>
+ lease.leasePolicy === "reuse_by_environment" &&
+ reusableLeaseCanBeResumed({ lease, heartbeatRunId: input.heartbeatRunId }) &&
+ lease.executionWorkspaceId === input.executionWorkspaceId &&
+ lease.metadata?.agentId === input.agentId,
+ )
+ : [];
+ const reusableExistingLeases = reusableCandidateLeases.filter((lease) =>
+ reusableSandboxLeaseScopeMatches({
+ lease,
+ companyId: input.companyId,
+ environmentId: input.environment.id,
+ executionWorkspaceId: input.executionWorkspaceId,
+ agentId: input.agentId,
+ adapterType: input.adapterType,
+ provider: parsed.config.provider,
+ config: providerConfigForLease,
+ leaseFingerprint,
+ allowLegacyRuntimeFingerprint:
+ lease.status === "active" &&
+ input.heartbeatRunId !== null &&
+ lease.heartbeatRunId === input.heartbeatRunId,
+ }),
+ );
+ if (reusableCandidateLeases.length > reusableExistingLeases.length) {
+ await cleanupObsoleteReusableSandboxLeases({
+ environment: input.environment,
+ leases: reusableCandidateLeases,
+ reusableLeases: reusableExistingLeases,
+ });
+ }
const reusableProviderLeaseId =
supportsReusableLeases &&
parsed.config.reuseLease &&
input.heartbeatRunId !== null &&
input.executionWorkspaceId !== null &&
input.agentId !== null
- ? (await environmentsSvc
- .listLeases(input.environment.id)
- .then((leases) =>
- findReusableSandboxLeaseId({
- config: parsed.config,
- leases: leases.filter((lease) =>
- lease.leasePolicy === "reuse_by_environment" &&
- ["active", "released", "retained"].includes(lease.status) &&
- lease.executionWorkspaceId === input.executionWorkspaceId &&
- lease.metadata?.agentId === input.agentId &&
- reusableSandboxLeaseScopeMatches({
- lease,
- companyId: input.companyId,
- environmentId: input.environment.id,
- executionWorkspaceId: input.executionWorkspaceId,
- agentId: input.agentId,
- adapterType: input.adapterType,
- provider: parsed.config.provider,
- config: sandboxConfigForLeaseMetadata(parsed.config),
- }),
- ),
- }),
- ))
+ ? findReusableSandboxLeaseId({ config: parsed.config, leases: reusableExistingLeases })
: null;
const reusableLease = reusableProviderLeaseId
- ? (await environmentsSvc.listLeases(input.environment.id)).find((lease) => lease.providerLeaseId === reusableProviderLeaseId)
+ ? reusableExistingLeases.find((lease) => lease.providerLeaseId === reusableProviderLeaseId)
: null;
let providerLease;
@@ -806,7 +1070,8 @@ function createSandboxEnvironmentDriver(
agentId: input.agentId,
adapterType: input.adapterType,
provider: parsed.config.provider,
- config: sandboxConfigForLeaseMetadata(parsed.config),
+ config: providerConfigForLease,
+ leaseFingerprint,
providerMetadata: providerLease.metadata,
})
: null;
diff --git a/server/src/services/heartbeat.ts b/server/src/services/heartbeat.ts
index 739b4dc47e..5c6a2b17d1 100644
--- a/server/src/services/heartbeat.ts
+++ b/server/src/services/heartbeat.ts
@@ -2,7 +2,7 @@ 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 { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
import { and, asc, desc, eq, getTableColumns, gt, gte, inArray, isNull, lt, lte, notInArray, or, sql } from "drizzle-orm";
import type { Db } from "@paperclipai/db";
import {
@@ -26,6 +26,7 @@ import {
} from "@paperclipai/shared";
import {
agents,
+ agentConfigRevisions,
agentRuntimeState,
agentTaskSessions,
agentWakeupRequests,
@@ -123,7 +124,7 @@ import {
} from "./issue-continuation-summary.js";
import { buildPlanReviewContext } from "./plan-review-context.js";
import { executionWorkspaceService, mergeExecutionWorkspaceConfig } from "./execution-workspaces.js";
-import { workspaceOperationService } from "./workspace-operations.js";
+import { workspaceOperationService, type WorkspaceOperationRecorder } from "./workspace-operations.js";
import { isProcessGroupAlive, terminateLocalService } from "./local-service-supervisor.js";
import {
buildExecutionWorkspaceAdapterConfig,
@@ -208,6 +209,13 @@ import {
assertLowTrustWorkspaceIsolation,
} from "./low-trust-runtime-containment.js";
import { resolveCoreTrustPreset, type TrustPresetResolution } from "./trust-preset-resolver.js";
+import {
+ createEffectiveRunConfigFingerprints,
+ createEffectiveRunConfigSubcategoryFingerprints,
+ EFFECTIVE_RUN_CONFIG_FINGERPRINT_VERSION,
+ type EffectiveRunConfigFingerprints,
+ type EffectiveRunConfigSecretManifestEntry,
+} from "./effective-run-config-fingerprints.js";
import type { PluginWorkerManager } from "./plugin-worker-manager.js";
const MAX_LIVE_LOG_CHUNK_BYTES = 8 * 1024;
@@ -915,6 +923,8 @@ export function mergeExecutionWorkspaceMetadataForPersistence(input: {
createdByRuntime: boolean;
configSnapshot: Record<string, unknown> | null;
shouldReuseExisting: boolean;
+ shouldRefreshConfigSnapshot?: boolean;
+ workspaceConfigMetadata?: EffectiveRunWorkspaceConfigMetadata | null;
baseRef: string | null | undefined;
baseRefSha: string | null | undefined;
}) {
@@ -935,7 +945,17 @@ export function mergeExecutionWorkspaceMetadataForPersistence(input: {
};
}
- if (input.shouldReuseExisting || !input.configSnapshot) {
+ if (input.workspaceConfigMetadata) {
+ base[WORKSPACE_CONFIG_FINGERPRINT_METADATA_KEY] = {
+ version: input.workspaceConfigMetadata.version,
+ workspaceHash: input.workspaceConfigMetadata.fingerprint,
+ categories: input.workspaceConfigMetadata.categories,
+ categoryFingerprints: input.workspaceConfigMetadata.categoryFingerprints,
+ lastEvaluatedAt: input.workspaceConfigMetadata.evaluatedAt,
+ };
+ }
+
+ if ((input.shouldReuseExisting && !input.shouldRefreshConfigSnapshot) || !input.configSnapshot) {
return base;
}
@@ -948,35 +968,6 @@ export function stripWorkspaceRuntimeFromExecutionRunConfig(config: Record<strin
return nextConfig;
}
-export function buildRealizedExecutionWorkspaceFromPersisted(input: {
- base: ExecutionWorkspaceInput;
- workspace: ExecutionWorkspace;
-}): RealizedExecutionWorkspace | null {
- const cwd = readNonEmptyString(input.workspace.cwd) ?? readNonEmptyString(input.workspace.providerRef);
- if (!cwd) {
- return null;
- }
-
- const strategy = input.workspace.strategyType === "git_worktree" ? "git_worktree" : "project_primary";
- const baseRefSnapshot = parseObject(input.workspace.metadata?.baseRefSnapshot);
- const baseRefSha = typeof baseRefSnapshot.resolvedSha === "string" ? baseRefSnapshot.resolvedSha : null;
- return {
- baseCwd: input.base.baseCwd,
- source: input.workspace.mode === "shared_workspace" ? "project_primary" : "task_session",
- projectId: input.workspace.projectId ?? input.base.projectId,
- workspaceId: input.workspace.projectWorkspaceId ?? input.base.workspaceId,
- repoUrl: input.workspace.repoUrl ?? input.base.repoUrl,
- repoRef: input.workspace.baseRef ?? input.base.repoRef,
- strategy,
- cwd,
- branchName: input.workspace.branchName ?? null,
- worktreePath: strategy === "git_worktree" ? (readNonEmptyString(input.workspace.providerRef) ?? cwd) : null,
- warnings: [],
- created: false,
- baseRefSha,
- };
-}
-
function buildExecutionWorkspaceConfigSnapshot(
config: Record<string, unknown>,
environmentId?: string | null,
@@ -2473,6 +2464,704 @@ export function shouldDeferFollowupWakeForSameIssue(input: {
}
const SESSION_CONFIGURED_MODEL_KEY = "__paperclipConfiguredModel";
+const SESSION_CONFIG_FINGERPRINT_KEY = "__paperclipConfigFingerprint";
+const SESSION_CONFIG_FINGERPRINT_VERSION_KEY = "__paperclipConfigFingerprintVersion";
+const SESSION_CONFIG_CATEGORIES_KEY = "__paperclipConfigCategories";
+const SESSION_CONFIG_CATEGORY_FINGERPRINTS_KEY = "__paperclipConfigCategoryFingerprints";
+const PAPERCLIP_SESSION_METADATA_KEYS = new Set([
+ SESSION_CONFIGURED_MODEL_KEY,
+ SESSION_CONFIG_FINGERPRINT_KEY,
+ SESSION_CONFIG_FINGERPRINT_VERSION_KEY,
+ SESSION_CONFIG_CATEGORIES_KEY,
+ SESSION_CONFIG_CATEGORY_FINGERPRINTS_KEY,
+]);
+const WORKSPACE_CONFIG_FINGERPRINT_METADATA_KEY = "configFingerprint";
+const EFFECTIVE_RUN_SESSION_CONFIG_CATEGORIES = [
+ "adapter",
+ "adapterConfig",
+ "agentRuntimeConfig",
+ "modelProfile",
+ "instructions",
+ "issueOverrides",
+ "workspaceConfig",
+ "environment",
+ "envBindings",
+ "secrets",
+ "runtimeSkills",
+] as const;
+const EFFECTIVE_RUN_WORKSPACE_CONFIG_CATEGORIES = [
+ "mode",
+ "projectWorkspace",
+ "strategy",
+ "repo",
+ "lifecycleCommands",
+ "runtimeServices",
+ "environment",
+ "realization",
+] as const;
+
+type EffectiveRunSessionConfigCategory = (typeof EFFECTIVE_RUN_SESSION_CONFIG_CATEGORIES)[number];
+type EffectiveRunWorkspaceConfigCategory = (typeof EFFECTIVE_RUN_WORKSPACE_CONFIG_CATEGORIES)[number];
+
+type EffectiveRunSessionConfigMetadata = {
+ version: typeof EFFECTIVE_RUN_CONFIG_FINGERPRINT_VERSION;
+ fingerprint: string;
+ categories: EffectiveRunSessionConfigCategory[];
+ categoryFingerprints: Record<EffectiveRunSessionConfigCategory, string>;
+ fingerprints: EffectiveRunConfigFingerprints;
+};
+
+type TaskSessionConfigFreshnessDecision = {
+ reset: boolean;
+ reasons: string[];
+ changedCategories: EffectiveRunSessionConfigCategory[];
+ storedFingerprint: string | null;
+ nextFingerprint: string | null;
+};
+
+export type EffectiveRunWorkspaceConfigMetadata = {
+ version: typeof EFFECTIVE_RUN_CONFIG_FINGERPRINT_VERSION;
+ fingerprint: string;
+ categories: EffectiveRunWorkspaceConfigCategory[];
+ categoryFingerprints: Record<EffectiveRunWorkspaceConfigCategory, string>;
+ fingerprints: EffectiveRunConfigFingerprints;
+ evaluatedAt: string;
+};
+
+type WorkspaceConfigFreshnessDecisionAction = "create" | "reuse" | "refresh" | "replace";
+
+type ExecutionWorkspaceConfigFreshnessDecision = {
+ action: WorkspaceConfigFreshnessDecisionAction;
+ shouldReuseExisting: boolean;
+ shouldRefreshConfigSnapshot: boolean;
+ reasons: string[];
+ changedCategories: EffectiveRunWorkspaceConfigCategory[];
+ storedFingerprint: string | null;
+ inferredFingerprint: string | null;
+ nextFingerprint: string | null;
+ storedFingerprintPresent: boolean;
+};
+
+type WorkspaceConfigFreshnessOperationInput = {
+ decision: ExecutionWorkspaceConfigFreshnessDecision;
+ hasExistingWorkspace: boolean;
+ reuseRequested: boolean;
+ workspaceReused: boolean;
+ configSnapshotRefreshed: boolean;
+ previousWorkspaceId: string | null;
+ activeWorkspaceId: string | null;
+};
+
+const EFFECTIVE_RUN_SESSION_CONFIG_CATEGORY_LABELS: Record<EffectiveRunSessionConfigCategory, string> = {
+ adapter: "adapter",
+ adapterConfig: "adapter config",
+ agentRuntimeConfig: "agent runtime config",
+ modelProfile: "model profile",
+ instructions: "instructions",
+ issueOverrides: "issue overrides",
+ workspaceConfig: "workspace config",
+ environment: "environment",
+ envBindings: "env bindings",
+ secrets: "secrets",
+ runtimeSkills: "runtime skills",
+};
+const EFFECTIVE_RUN_WORKSPACE_CONFIG_CATEGORY_LABELS: Record<EffectiveRunWorkspaceConfigCategory, string> = {
+ mode: "workspace mode",
+ projectWorkspace: "project workspace",
+ strategy: "workspace strategy",
+ repo: "repo/base ref",
+ lifecycleCommands: "workspace lifecycle commands",
+ runtimeServices: "runtime services",
+ environment: "environment",
+ realization: "workspace realization",
+};
+const WORKSPACE_REPLACEMENT_CONFIG_CATEGORIES = new Set<EffectiveRunWorkspaceConfigCategory>([
+ "mode",
+ "projectWorkspace",
+ "strategy",
+ "repo",
+ "environment",
+ "realization",
+]);
+
+function parseStoredConfigCategoryFingerprints(value: unknown) {
+ const parsed = parseObject(value);
+ const out: Partial<Record<EffectiveRunSessionConfigCategory, string>> = {};
+ for (const category of EFFECTIVE_RUN_SESSION_CONFIG_CATEGORIES) {
+ const fingerprint = readNonEmptyString(parsed[category]);
+ if (fingerprint) out[category] = fingerprint;
+ }
+ return out;
+}
+
+function readConfigCategoriesFromSessionParams(
+ sessionParams: Record<string, unknown> | null | undefined,
+) {
+ const rawCategories = Array.isArray(sessionParams?.[SESSION_CONFIG_CATEGORIES_KEY])
+ ? sessionParams?.[SESSION_CONFIG_CATEGORIES_KEY]
+ : [];
+ return rawCategories.filter(
+ (category): category is EffectiveRunSessionConfigCategory =>
+ typeof category === "string" &&
+ (EFFECTIVE_RUN_SESSION_CONFIG_CATEGORIES as readonly string[]).includes(category),
+ );
+}
+
+function readConfigFingerprintFromSessionParams(
+ sessionParams: Record<string, unknown> | null | undefined,
+) {
+ if (!sessionParams) return null;
+ const fingerprint = readNonEmptyString(sessionParams[SESSION_CONFIG_FINGERPRINT_KEY]);
+ const version = asNumber(sessionParams[SESSION_CONFIG_FINGERPRINT_VERSION_KEY], 0);
+ if (!fingerprint || version <= 0) return null;
+ return {
+ fingerprint,
+ version,
+ categories: readConfigCategoriesFromSessionParams(sessionParams),
+ categoryFingerprints: parseStoredConfigCategoryFingerprints(
+ sessionParams[SESSION_CONFIG_CATEGORY_FINGERPRINTS_KEY],
+ ),
+ };
+}
+
+function describeEffectiveRunConfigCategories(categories: readonly EffectiveRunSessionConfigCategory[]) {
+ return categories.map((category) => EFFECTIVE_RUN_SESSION_CONFIG_CATEGORY_LABELS[category]).join(", ");
+}
+
+function changedEffectiveRunSessionConfigCategories(input: {
+ previous: Partial<Record<EffectiveRunSessionConfigCategory, string>>;
+ next: Record<EffectiveRunSessionConfigCategory, string>;
+}) {
+ const changed = EFFECTIVE_RUN_SESSION_CONFIG_CATEGORIES.filter(
+ (category) => input.previous[category] !== input.next[category],
+ );
+ return changed.length > 0 ? changed : [...EFFECTIVE_RUN_SESSION_CONFIG_CATEGORIES];
+}
+
+function parseStoredWorkspaceConfigCategoryFingerprints(value: unknown) {
+ const parsed = parseObject(value);
+ const out: Partial<Record<EffectiveRunWorkspaceConfigCategory, string>> = {};
+ for (const category of EFFECTIVE_RUN_WORKSPACE_CONFIG_CATEGORIES) {
+ const fingerprint = readNonEmptyString(parsed[category]);
+ if (fingerprint) out[category] = fingerprint;
+ }
+ return out;
+}
+
+function readWorkspaceConfigCategoriesFromMetadata(value: unknown) {
+ const rawCategories = Array.isArray(value) ? value : [];
+ return rawCategories.filter(
+ (category): category is EffectiveRunWorkspaceConfigCategory =>
+ typeof category === "string" &&
+ (EFFECTIVE_RUN_WORKSPACE_CONFIG_CATEGORIES as readonly string[]).includes(category),
+ );
+}
+
+function readWorkspaceConfigFingerprintFromMetadata(
+ metadata: Record<string, unknown> | null | undefined,
+) {
+ const raw = parseObject(metadata?.[WORKSPACE_CONFIG_FINGERPRINT_METADATA_KEY]);
+ const fingerprint = readNonEmptyString(raw.workspaceHash) ?? readNonEmptyString(raw.fingerprint);
+ const version = asNumber(raw.version, 0);
+ if (!fingerprint || version <= 0) return null;
+ return {
+ fingerprint,
+ version,
+ categories: readWorkspaceConfigCategoriesFromMetadata(raw.categories),
+ categoryFingerprints: parseStoredWorkspaceConfigCategoryFingerprints(raw.categoryFingerprints),
+ };
+}
+
+function describeEffectiveRunWorkspaceConfigCategories(
+ categories: readonly EffectiveRunWorkspaceConfigCategory[],
+) {
+ return categories.map((category) => EFFECTIVE_RUN_WORKSPACE_CONFIG_CATEGORY_LABELS[category]).join(", ");
+}
+
+function changedEffectiveRunWorkspaceConfigCategories(input: {
+ previous: Partial<Record<EffectiveRunWorkspaceConfigCategory, string>>;
+ next: Record<EffectiveRunWorkspaceConfigCategory, string>;
+}) {
+ const changed = EFFECTIVE_RUN_WORKSPACE_CONFIG_CATEGORIES.filter(
+ (category) => input.previous[category] !== input.next[category],
+ );
+ return changed.length > 0 ? changed : [...EFFECTIVE_RUN_WORKSPACE_CONFIG_CATEGORIES];
+}
+
+function workspaceConfigFreshnessActionLabel(action: WorkspaceConfigFreshnessDecisionAction) {
+ switch (action) {
+ case "refresh":
+ return "refreshed execution workspace config";
+ case "replace":
+ return "replaced execution workspace";
+ case "reuse":
+ return "updated execution workspace freshness metadata";
+ case "create":
+ return "created execution workspace";
+ }
+}
+
+export function buildWorkspaceConfigFreshnessOperation(input: WorkspaceConfigFreshnessOperationInput) {
+ if (!input.reuseRequested || !input.hasExistingWorkspace || input.decision.reasons.length === 0) {
+ return null;
+ }
+
+ const changedCategoryLabels = input.decision.changedCategories.map(
+ (category) => EFFECTIVE_RUN_WORKSPACE_CONFIG_CATEGORY_LABELS[category],
+ );
+ const categorySummary =
+ changedCategoryLabels.length > 0 ? ` (${changedCategoryLabels.join(", ")})` : "";
+ const reasonSummary = input.decision.reasons.join("; ");
+
+ return {
+ metadata: {
+ kind: "config_freshness",
+ action: input.decision.action,
+ changedCategories: input.decision.changedCategories,
+ changedCategoryLabels,
+ reasons: input.decision.reasons,
+ reuseRequested: input.reuseRequested,
+ workspaceReused: input.workspaceReused,
+ configSnapshotRefreshed: input.configSnapshotRefreshed,
+ storedFingerprintPresent: input.decision.storedFingerprintPresent,
+ previousWorkspaceId: input.previousWorkspaceId,
+ activeWorkspaceId: input.activeWorkspaceId,
+ },
+ system:
+ `[paperclip] ${workspaceConfigFreshnessActionLabel(input.decision.action)} after config freshness check${categorySummary}: ${reasonSummary}\n`,
+ };
+}
+
+async function recordWorkspaceConfigFreshnessOperation(input: WorkspaceConfigFreshnessOperationInput & {
+ recorder: WorkspaceOperationRecorder;
+ runId: string;
+}) {
+ const operation = buildWorkspaceConfigFreshnessOperation(input);
+ if (!operation) return;
+
+ try {
+ await input.recorder.recordOperation({
+ phase: "workspace_config_freshness",
+ metadata: operation.metadata,
+ run: async () => ({
+ status: "succeeded",
+ system: operation.system,
+ }),
+ });
+ } catch (error) {
+ logger.warn(
+ {
+ err: error instanceof Error ? error.message : String(error),
+ runId: input.runId,
+ previousWorkspaceId: input.previousWorkspaceId,
+ activeWorkspaceId: input.activeWorkspaceId,
+ action: input.decision.action,
+ },
+ "failed to record workspace config freshness operation",
+ );
+ }
+}
+
+function sanitizeSecretManifestForConfigFingerprint(
+ manifest: readonly EffectiveRunConfigSecretManifestEntry[],
+) {
+ return manifest.map((entry) => {
+ const record = entry as Record<string, unknown>;
+ return {
+ configPath: readNonEmptyString(record.configPath) ?? "",
+ envKey: readNonEmptyString(record.envKey),
+ secretId: readNonEmptyString(record.secretId) ?? "",
+ bindingId: readNonEmptyString(record.bindingId),
+ version: typeof record.version === "number" && Number.isFinite(record.version)
+ ? record.version
+ : readNonEmptyString(record.version),
+ provider: readNonEmptyString(record.provider),
+ providerVersionRef: readNonEmptyString(record.providerVersionRef),
+ outcome: record.outcome === "success" || record.outcome === "failure" ? record.outcome : null,
+ };
+ });
+}
+
+async function hashFileContentsForConfigFingerprint(filePath: string) {
+ const contents = await fs.readFile(filePath);
+ return `sha256:${createHash("sha256").update(contents).digest("hex")}`;
+}
+
+function isPathInsideRoot(input: { rootPath: string; filePath: string }) {
+ const relative = path.relative(input.rootPath, input.filePath);
+ return relative === "" || (
+ relative.length > 0
+ && !relative.startsWith("..")
+ && !path.isAbsolute(relative)
+ );
+}
+
+function resolveRootBoundInstructionsFingerprintPath(input: {
+ instructionsFilePath: string | null;
+ instructionsRootPath: string | null;
+ instructionsEntryFile: string | null;
+}): { filePath: string; skippedReason: null } | { filePath: null; skippedReason: string | null } {
+ if (!input.instructionsRootPath || !path.isAbsolute(input.instructionsRootPath)) {
+ return {
+ filePath: null,
+ skippedReason: input.instructionsFilePath ? "missing_absolute_root" : null,
+ };
+ }
+
+ const rootPath = path.resolve(input.instructionsRootPath);
+ const candidatePath = input.instructionsEntryFile ?? input.instructionsFilePath;
+ if (!candidatePath) return { filePath: null, skippedReason: "missing_entry_file" };
+
+ const resolvedPath = path.isAbsolute(candidatePath)
+ ? path.resolve(candidatePath)
+ : path.resolve(rootPath, candidatePath);
+
+ if (!isPathInsideRoot({ rootPath, filePath: resolvedPath })) {
+ return { filePath: null, skippedReason: "outside_root" };
+ }
+
+ return { filePath: resolvedPath, skippedReason: null };
+}
+
+async function resolveInstructionsConfigFingerprintMetadata(config: Record<string, unknown>) {
+ const instructionsFilePath = readNonEmptyString(config.instructionsFilePath);
+ const instructionsRootPath = readNonEmptyString(config.instructionsRootPath);
+ const instructionsEntryFile = readNonEmptyString(config.instructionsEntryFile);
+ const resolved = resolveRootBoundInstructionsFingerprintPath({
+ instructionsFilePath,
+ instructionsRootPath,
+ instructionsEntryFile,
+ });
+ const configuredPath = resolved.filePath ?? instructionsFilePath ?? (
+ instructionsRootPath && instructionsEntryFile
+ ? path.resolve(instructionsRootPath, instructionsEntryFile)
+ : null
+ );
+ if (!configuredPath && !instructionsRootPath && !instructionsEntryFile) return null;
+
+ const metadata: Record<string, unknown> = {
+ configured: true,
+ bundleMode: readNonEmptyString(config.instructionsBundleMode),
+ entryFile: instructionsEntryFile,
+ pathKind: configuredPath ? (path.isAbsolute(configuredPath) ? "absolute" : "relative") : null,
+ readPolicy: "root_bound",
+ };
+ if (resolved.skippedReason) metadata.readSkippedReason = resolved.skippedReason;
+ if (resolved.filePath) {
+ try {
+ metadata.contentHash = await hashFileContentsForConfigFingerprint(resolved.filePath);
+ metadata.readable = true;
+ } catch {
+ metadata.readable = false;
+ }
+ }
+ return metadata;
+}
+
+function buildSessionConfigCategoryValues(input: {
+ adapterType: string;
+ effectiveAdapterConfig: Record<string, unknown>;
+ agentRuntimeConfig: unknown;
+ modelProfile: unknown;
+ instructions: unknown;
+ issueOverrides: unknown;
+ workspaceConfig: unknown;
+ environment: unknown;
+ environmentEnv: unknown;
+ projectEnv: unknown;
+ routineEnv: unknown;
+ secretManifest: readonly EffectiveRunConfigSecretManifestEntry[];
+ runtimeSkills: unknown;
+ agentConfigRevision: unknown;
+}) {
+ const sanitizedSecretManifest = sanitizeSecretManifestForConfigFingerprint(input.secretManifest);
+ return {
+ adapter: {
+ adapterType: input.adapterType,
+ agentConfigRevision: input.agentConfigRevision,
+ },
+ adapterConfig: input.effectiveAdapterConfig,
+ agentRuntimeConfig: input.agentRuntimeConfig,
+ modelProfile: input.modelProfile,
+ instructions: input.instructions,
+ issueOverrides: input.issueOverrides,
+ workspaceConfig: input.workspaceConfig,
+ environment: input.environment,
+ envBindings: {
+ environment: { env: input.environmentEnv },
+ project: { env: input.projectEnv },
+ routine: { env: input.routineEnv },
+ },
+ secrets: sanitizedSecretManifest,
+ runtimeSkills: input.runtimeSkills,
+ } satisfies Record<EffectiveRunSessionConfigCategory, unknown>;
+}
+
+export async function buildEffectiveRunSessionConfigMetadata(input: {
+ adapterType: string;
+ effectiveAdapterConfig: Record<string, unknown>;
+ agentRuntimeConfig: unknown;
+ modelProfile: unknown;
+ issueOverrides: unknown;
+ workspaceConfig: unknown;
+ environment: unknown;
+ environmentEnv: unknown;
+ projectEnv: unknown;
+ routineEnv: unknown;
+ secretManifest?: readonly EffectiveRunConfigSecretManifestEntry[];
+ runtimeSkills: unknown;
+ agentConfigRevision?: unknown;
+}): Promise<EffectiveRunSessionConfigMetadata> {
+ const secretManifest = input.secretManifest ?? [];
+ const instructions = await resolveInstructionsConfigFingerprintMetadata(input.effectiveAdapterConfig);
+ const categoryValues = buildSessionConfigCategoryValues({
+ adapterType: input.adapterType,
+ effectiveAdapterConfig: input.effectiveAdapterConfig,
+ agentRuntimeConfig: input.agentRuntimeConfig,
+ modelProfile: input.modelProfile,
+ instructions,
+ issueOverrides: input.issueOverrides,
+ workspaceConfig: input.workspaceConfig,
+ environment: input.environment,
+ environmentEnv: input.environmentEnv,
+ projectEnv: input.projectEnv,
+ routineEnv: input.routineEnv,
+ secretManifest,
+ runtimeSkills: input.runtimeSkills,
+ agentConfigRevision: input.agentConfigRevision ?? null,
+ });
+ const fingerprints = createEffectiveRunConfigFingerprints({
+ session: categoryValues,
+ secretManifest,
+ });
+ const categoryFingerprints = createEffectiveRunConfigSubcategoryFingerprints({
+ category: "session",
+ value: categoryValues,
+ subcategories: EFFECTIVE_RUN_SESSION_CONFIG_CATEGORIES,
+ secretManifest,
+ });
+ return {
+ version: EFFECTIVE_RUN_CONFIG_FINGERPRINT_VERSION,
+ fingerprint: fingerprints.sessionFingerprint.fingerprint,
+ categories: [...EFFECTIVE_RUN_SESSION_CONFIG_CATEGORIES],
+ categoryFingerprints,
+ fingerprints,
+ };
+}
+
+function buildWorkspaceConfigCategoryValues(input: {
+ mode: unknown;
+ projectId: unknown;
+ projectWorkspaceId: unknown;
+ strategyType: unknown;
+ workspaceStrategy: unknown;
+ repoUrl: unknown;
+ repoRef: unknown;
+ branchName: unknown;
+ configSnapshot: Partial<ExecutionWorkspaceConfig> | null;
+ environment: unknown;
+ realization: unknown;
+}) {
+ const snapshot = input.configSnapshot ?? {};
+ return {
+ mode: {
+ mode: input.mode ?? null,
+ },
+ projectWorkspace: {
+ projectId: input.projectId ?? null,
+ projectWorkspaceId: input.projectWorkspaceId ?? null,
+ },
+ strategy: {
+ strategyType: input.strategyType ?? null,
+ workspaceStrategy: input.workspaceStrategy ?? null,
+ },
+ repo: {
+ repoUrl: input.repoUrl ?? null,
+ repoRef: input.repoRef ?? null,
+ branchName: input.branchName ?? null,
+ },
+ lifecycleCommands: {
+ provisionCommand: snapshot.provisionCommand ?? null,
+ teardownCommand: snapshot.teardownCommand ?? null,
+ cleanupCommand: snapshot.cleanupCommand ?? null,
+ },
+ runtimeServices: {
+ workspaceRuntime: snapshot.workspaceRuntime ?? null,
+ desiredState: snapshot.desiredState ?? null,
+ serviceStates: snapshot.serviceStates ?? null,
+ },
+ environment: input.environment ?? null,
+ realization: input.realization ?? null,
+ } satisfies Record<EffectiveRunWorkspaceConfigCategory, unknown>;
+}
+
+export function buildEffectiveRunWorkspaceConfigMetadata(input: {
+ mode: unknown;
+ projectId: unknown;
+ projectWorkspaceId: unknown;
+ strategyType: unknown;
+ workspaceStrategy: unknown;
+ repoUrl: unknown;
+ repoRef: unknown;
+ branchName?: unknown;
+ configSnapshot: Partial<ExecutionWorkspaceConfig> | null;
+ environment: unknown;
+ realization: unknown;
+ secretManifest?: readonly EffectiveRunConfigSecretManifestEntry[];
+ evaluatedAt?: string | Date | null;
+}): EffectiveRunWorkspaceConfigMetadata {
+ const secretManifest = input.secretManifest ?? [];
+ const categoryValues = buildWorkspaceConfigCategoryValues({
+ mode: input.mode,
+ projectId: input.projectId,
+ projectWorkspaceId: input.projectWorkspaceId,
+ strategyType: input.strategyType,
+ workspaceStrategy: input.workspaceStrategy,
+ repoUrl: input.repoUrl,
+ repoRef: input.repoRef,
+ branchName: input.branchName ?? null,
+ configSnapshot: input.configSnapshot,
+ environment: input.environment,
+ realization: input.realization,
+ });
+ const fingerprints = createEffectiveRunConfigFingerprints({
+ workspace: categoryValues,
+ secretManifest,
+ });
+ const categoryFingerprints = createEffectiveRunConfigSubcategoryFingerprints({
+ category: "workspace",
+ value: categoryValues,
+ subcategories: EFFECTIVE_RUN_WORKSPACE_CONFIG_CATEGORIES,
+ secretManifest,
+ });
+ const evaluatedAt = input.evaluatedAt instanceof Date
+ ? input.evaluatedAt.toISOString()
+ : readNonEmptyString(input.evaluatedAt) ?? new Date().toISOString();
+ return {
+ version: EFFECTIVE_RUN_CONFIG_FINGERPRINT_VERSION,
+ fingerprint: fingerprints.workspaceFingerprint.fingerprint,
+ categories: [...EFFECTIVE_RUN_WORKSPACE_CONFIG_CATEGORIES],
+ categoryFingerprints,
+ fingerprints,
+ evaluatedAt,
+ };
+}
+
+export function resolveExecutionWorkspaceConfigFreshness(input: {
+ hasExistingWorkspace: boolean;
+ existingWorkspaceMetadata: Record<string, unknown> | null | undefined;
+ inferredMetadata?: EffectiveRunWorkspaceConfigMetadata | null;
+ nextMetadata: EffectiveRunWorkspaceConfigMetadata | null;
+}): ExecutionWorkspaceConfigFreshnessDecision {
+ if (!input.hasExistingWorkspace) {
+ return {
+ action: "create",
+ shouldReuseExisting: false,
+ shouldRefreshConfigSnapshot: false,
+ reasons: [],
+ changedCategories: [],
+ storedFingerprint: null,
+ inferredFingerprint: null,
+ nextFingerprint: input.nextMetadata?.fingerprint ?? null,
+ storedFingerprintPresent: false,
+ };
+ }
+
+ const stored = readWorkspaceConfigFingerprintFromMetadata(input.existingWorkspaceMetadata);
+ const previous = stored
+ ? {
+ version: stored.version,
+ fingerprint: stored.fingerprint,
+ categoryFingerprints: stored.categoryFingerprints,
+ }
+ : input.inferredMetadata
+ ? {
+ version: input.inferredMetadata.version,
+ fingerprint: input.inferredMetadata.fingerprint,
+ categoryFingerprints: input.inferredMetadata.categoryFingerprints,
+ }
+ : null;
+
+ if (!input.nextMetadata) {
+ return {
+ action: "reuse",
+ shouldReuseExisting: true,
+ shouldRefreshConfigSnapshot: false,
+ reasons: [],
+ changedCategories: [],
+ storedFingerprint: stored?.fingerprint ?? null,
+ inferredFingerprint: stored ? null : input.inferredMetadata?.fingerprint ?? null,
+ nextFingerprint: null,
+ storedFingerprintPresent: Boolean(stored),
+ };
+ }
+
+ if (!previous) {
+ return {
+ action: "replace",
+ shouldReuseExisting: false,
+ shouldRefreshConfigSnapshot: false,
+ reasons: ["execution workspace configuration fingerprint metadata is missing"],
+ changedCategories: [...input.nextMetadata.categories],
+ storedFingerprint: null,
+ inferredFingerprint: null,
+ nextFingerprint: input.nextMetadata.fingerprint,
+ storedFingerprintPresent: false,
+ };
+ }
+
+ if (previous.version !== input.nextMetadata.version) {
+ return {
+ action: "replace",
+ shouldReuseExisting: false,
+ shouldRefreshConfigSnapshot: false,
+ reasons: [
+ `execution workspace configuration fingerprint version changed from ${previous.version} to ${input.nextMetadata.version}`,
+ ],
+ changedCategories: [...input.nextMetadata.categories],
+ storedFingerprint: stored?.fingerprint ?? null,
+ inferredFingerprint: stored ? null : input.inferredMetadata?.fingerprint ?? null,
+ nextFingerprint: input.nextMetadata.fingerprint,
+ storedFingerprintPresent: Boolean(stored),
+ };
+ }
+
+ if (previous.fingerprint === input.nextMetadata.fingerprint) {
+ return {
+ action: "reuse",
+ shouldReuseExisting: true,
+ shouldRefreshConfigSnapshot: !stored,
+ reasons: stored ? [] : ["execution workspace configuration fingerprint metadata is missing"],
+ changedCategories: [],
+ storedFingerprint: stored?.fingerprint ?? null,
+ inferredFingerprint: stored ? null : input.inferredMetadata?.fingerprint ?? null,
+ nextFingerprint: input.nextMetadata.fingerprint,
+ storedFingerprintPresent: Boolean(stored),
+ };
+ }
+
+ const changedCategories = changedEffectiveRunWorkspaceConfigCategories({
+ previous: previous.categoryFingerprints,
+ next: input.nextMetadata.categoryFingerprints,
+ });
+ const replacementRequired = changedCategories.some((category) =>
+ WORKSPACE_REPLACEMENT_CONFIG_CATEGORIES.has(category)
+ );
+ const action: WorkspaceConfigFreshnessDecisionAction = replacementRequired ? "replace" : "refresh";
+ return {
+ action,
+ shouldReuseExisting: action !== "replace",
+ shouldRefreshConfigSnapshot: action === "refresh",
+ reasons: [
+ `execution workspace configuration changed: ${describeEffectiveRunWorkspaceConfigCategories(changedCategories)}`,
+ ],
+ changedCategories,
+ storedFingerprint: stored?.fingerprint ?? null,
+ inferredFingerprint: stored ? null : input.inferredMetadata?.fingerprint ?? null,
+ nextFingerprint: input.nextMetadata.fingerprint,
+ storedFingerprintPresent: Boolean(stored),
+ };
+}
function readConfiguredModelFromAdapterConfig(
adapterConfig: Record<string, unknown> | null | undefined,
@@ -2480,13 +3169,20 @@ function readConfiguredModelFromAdapterConfig(
return readNonEmptyString(adapterConfig?.model);
}
-function attachConfiguredModelToSessionParams(
+function attachPaperclipSessionMetadataToSessionParams(
sessionParams: Record<string, unknown> | null | undefined,
configuredModel: string | null,
+ configMetadata?: EffectiveRunSessionConfigMetadata | null,
) {
- if (!configuredModel) return sessionParams ?? null;
+ if (!configuredModel && !configMetadata) return sessionParams ?? null;
const next = { ...(sessionParams ?? {}) };
- next[SESSION_CONFIGURED_MODEL_KEY] = configuredModel;
+ if (configuredModel) next[SESSION_CONFIGURED_MODEL_KEY] = configuredModel;
+ if (configMetadata) {
+ next[SESSION_CONFIG_FINGERPRINT_KEY] = configMetadata.fingerprint;
+ next[SESSION_CONFIG_FINGERPRINT_VERSION_KEY] = configMetadata.version;
+ next[SESSION_CONFIG_CATEGORIES_KEY] = configMetadata.categories;
+ next[SESSION_CONFIG_CATEGORY_FINGERPRINTS_KEY] = configMetadata.categoryFingerprints;
+ }
return next;
}
@@ -2515,6 +3211,78 @@ export function stripConfiguredModelFromSessionParams(
return next;
}
+export function stripPaperclipSessionMetadataFromSessionParams(
+ sessionParams: Record<string, unknown> | null | undefined,
+) {
+ if (!sessionParams) return null;
+ const next = { ...sessionParams };
+ for (const key of PAPERCLIP_SESSION_METADATA_KEYS) {
+ delete next[key];
+ }
+ return next;
+}
+
+export function resolveTaskSessionConfigFreshness(input: {
+ hasTaskSession: boolean;
+ configuredModel: string | null;
+ taskSessionParams: Record<string, unknown> | null | undefined;
+ configMetadata: EffectiveRunSessionConfigMetadata | null;
+ wakeResetReason?: string | null;
+ preserveLegacySessionWithoutConfigMetadata?: boolean;
+}): TaskSessionConfigFreshnessDecision {
+ if (!input.hasTaskSession) {
+ return {
+ reset: false,
+ reasons: [],
+ changedCategories: [],
+ storedFingerprint: null,
+ nextFingerprint: input.configMetadata?.fingerprint ?? null,
+ };
+ }
+
+ const reasons: string[] = [];
+ const storedConfig = readConfigFingerprintFromSessionParams(input.taskSessionParams);
+ const taskSessionConfiguredModel = readConfiguredModelFromSessionParams(input.taskSessionParams);
+ const modelChangedSinceTaskSession = shouldResetTaskSessionForModelChange({
+ configuredModel: input.configuredModel,
+ taskSessionParams: input.taskSessionParams,
+ });
+ if (modelChangedSinceTaskSession && taskSessionConfiguredModel) {
+ reasons.push(`configured model changed from "${taskSessionConfiguredModel}" to "${input.configuredModel}"`);
+ }
+
+ let changedCategories: EffectiveRunSessionConfigCategory[] = [];
+ if (input.configMetadata) {
+ if (!storedConfig && !input.preserveLegacySessionWithoutConfigMetadata) {
+ changedCategories = [...input.configMetadata.categories];
+ reasons.push("effective run configuration fingerprint metadata is missing");
+ } else if (storedConfig && storedConfig.version !== input.configMetadata.version) {
+ changedCategories = [...input.configMetadata.categories];
+ reasons.push(
+ `effective run configuration fingerprint version changed from ${storedConfig.version} to ${input.configMetadata.version}`,
+ );
+ } else if (storedConfig && storedConfig.fingerprint !== input.configMetadata.fingerprint) {
+ changedCategories = changedEffectiveRunSessionConfigCategories({
+ previous: storedConfig.categoryFingerprints,
+ next: input.configMetadata.categoryFingerprints,
+ });
+ reasons.push(
+ `effective run configuration changed: ${describeEffectiveRunConfigCategories(changedCategories)}`,
+ );
+ }
+ }
+
+ if (input.wakeResetReason) reasons.push(input.wakeResetReason);
+
+ return {
+ reset: reasons.length > 0,
+ reasons,
+ changedCategories,
+ storedFingerprint: storedConfig?.fingerprint ?? null,
+ nextFingerprint: input.configMetadata?.fingerprint ?? null,
+ };
+}
+
function shouldAutoCheckoutIssueForWake(input: {
contextSnapshot: Record<string, unknown> | null | undefined;
issueStatus: string | null;
@@ -3728,6 +4496,7 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})
originKind: issues.originKind,
originId: issues.originId,
originRunId: issues.originRunId,
+ updatedAt: issues.updatedAt,
})
.from(issues)
.where(and(eq(issues.id, issueId), eq(issues.companyId, companyId)))
@@ -3794,6 +4563,20 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})
.then((rows) => rows[0] ?? null);
}
+ async function getLatestAgentConfigRevision(companyId: string, agentId: string) {
+ return db
+ .select({
+ id: agentConfigRevisions.id,
+ changedKeys: agentConfigRevisions.changedKeys,
+ createdAt: agentConfigRevisions.createdAt,
+ })
+ .from(agentConfigRevisions)
+ .where(and(eq(agentConfigRevisions.companyId, companyId), eq(agentConfigRevisions.agentId, agentId)))
+ .orderBy(desc(agentConfigRevisions.createdAt), desc(agentConfigRevisions.id))
+ .limit(1)
+ .then((rows) => rows[0] ?? null);
+ }
+
async function getTaskSession(
companyId: string,
agentId: string,
@@ -8567,24 +9350,27 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})
id: projects.id,
executionWorkspacePolicy: projects.executionWorkspacePolicy,
env: projects.env,
+ updatedAt: projects.updatedAt,
})
.from(projects)
.where(and(eq(projects.id, executionProjectId), eq(projects.companyId, agent.companyId)))
.then((rows) => rows[0] ?? null)
: null;
+ const acceptedPlanContinuationWake = issueContext
+ ? readNonEmptyString(context.workspaceRefreshReason) === "accepted_plan_confirmation"
+ || (
+ issueContext.workMode === "planning"
+ && readNonEmptyString(context.interactionKind) === "request_confirmation"
+ && readNonEmptyString(context.interactionStatus) === "accepted"
+ )
+ : false;
const acceptedPlanWakeRoutingDecision = issueContext
? await resolveAcceptedPlanWakeRoutingDecision({
db,
companyId: agent.companyId,
agentId: agent.id,
issueId,
- acceptedPlanContinuationWake:
- readNonEmptyString(context.workspaceRefreshReason) === "accepted_plan_confirmation"
- || (
- issueContext.workMode === "planning"
- && readNonEmptyString(context.interactionKind) === "request_confirmation"
- && readNonEmptyString(context.interactionStatus) === "accepted"
- ),
+ acceptedPlanContinuationWake,
contextSnapshot: context,
})
: null;
@@ -8628,27 +9414,12 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})
: null,
});
const config = parseObject(agent.adapterConfig);
- const configuredModel = readConfiguredModelFromAdapterConfig(config);
const taskSession = taskKey
? await getTaskSession(agent.companyId, agent.id, agent.adapterType, taskKey)
: null;
const taskSessionDecodedParams = normalizeSessionParams(
sessionCodec.deserialize(taskSession?.sessionParamsJson ?? null),
);
- const modelChangedSinceTaskSession = shouldResetTaskSessionForModelChange({
- configuredModel,
- taskSessionParams: taskSessionDecodedParams,
- });
- const resetTaskSession = shouldResetTaskSessionForWake(context) || modelChangedSinceTaskSession;
- const wakeSessionResetReason = describeSessionResetReason(context);
- const taskSessionConfiguredModel = readConfiguredModelFromSessionParams(taskSessionDecodedParams);
- const modelSessionResetReason = modelChangedSinceTaskSession && taskSessionConfiguredModel
- ? `configured model changed from "${taskSessionConfiguredModel}" to "${configuredModel}"`
- : null;
- const sessionResetReason = [modelSessionResetReason, wakeSessionResetReason]
- .filter((value): value is string => Boolean(value))
- .join("; ") || null;
- const taskSessionForRun = resetTaskSession ? null : taskSession;
const explicitResumeSessionParams = normalizeResumeParamsForAdapter(
agent.adapterType,
sessionCodec.deserialize(parseObject(context.resumeSessionParams)),
@@ -8658,17 +9429,6 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})
(sessionCodec.getDisplayId ? sessionCodec.getDisplayId(explicitResumeSessionParams) : null) ??
readNonEmptyString(explicitResumeSessionParams?.sessionId),
);
- const previousSessionParams =
- explicitResumeSessionParams ??
- (isCanonicalSessionIdForAdapter(agent.adapterType, explicitResumeSessionDisplayId)
- ? { sessionId: explicitResumeSessionDisplayId }
- : null) ??
- normalizeResumeParamsForAdapter(
- agent.adapterType,
- stripConfiguredModelFromSessionParams(
- sessionCodec.deserialize(taskSessionForRun?.sessionParamsJson ?? null),
- ),
- );
const resolvedExecutionWorkspaceMode = resolveExecutionWorkspaceMode({
projectPolicy: projectExecutionWorkspacePolicy,
issueSettings: issueExecutionWorkspaceSettings,
@@ -8800,19 +9560,8 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})
instanceDefaultEnvironmentId: resolvedInstanceSettings.defaultEnvironmentId ?? null,
localDefaultEnvironmentId: localEnvironment.id,
});
- const shouldReuseExisting = requestedShouldReuseExisting;
- const reusableExecutionWorkspaceConfig = shouldReuseExisting
- ? requestedReusableExecutionWorkspaceConfig
- : null;
- const persistedExecutionWorkspaceMode = shouldReuseExisting && existingExecutionWorkspace
- ? issueExecutionWorkspaceModeForPersistedWorkspace(existingExecutionWorkspace.mode)
- : null;
const effectiveExecutionWorkspaceMode: ReturnType<typeof resolveExecutionWorkspaceMode> =
- persistedExecutionWorkspaceMode === "isolated_workspace" ||
- persistedExecutionWorkspaceMode === "operator_branch" ||
- persistedExecutionWorkspaceMode === "agent_default"
- ? persistedExecutionWorkspaceMode
- : requestedExecutionWorkspaceMode;
+ requestedExecutionWorkspaceMode;
const executionPolicy = { executionMode: (await instanceSettings.getGeneral()).executionMode };
let selectedEnvironmentId = environmentResolution.environmentId;
if (isExecutionForcedToKubernetes(executionPolicy)) {
@@ -8879,50 +9628,12 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})
}
selectedEnvironmentId = kubernetesEnvironment.id;
}
- const {
- selectedEnvironmentDriver: lowTrustPreflightEnvironmentDriver,
- workspace: resolvedWorkspace,
- } = await resolveWorkspaceAfterLowTrustPreflight({
- db,
- trustPreset,
- isolatedWorkspacesEnabled,
- effectiveExecutionWorkspaceMode,
- issue: issueRef
- ? {
- companyId: agent.companyId,
- id: issueRef.id,
- projectId: issueRef.projectId,
- }
- : null,
- resolveSelectedEnvironmentDriver: async () => {
- const preflightEnvironment = await envOrchestrator.resolveEnvironment({
- companyId: agent.companyId,
- selectedEnvironmentId,
- localEnvironmentId: localEnvironment.id,
- });
- return preflightEnvironment.driver;
- },
- resolveWorkspace: () =>
- resolveWorkspaceForRun(
- agent,
- context,
- previousSessionParams,
- { useProjectWorkspace: requestedExecutionWorkspaceMode !== "agent_default" },
- ),
- });
- const workspaceManagedConfig = shouldReuseExisting
- ? { ...config }
- : buildExecutionWorkspaceAdapterConfig({
- agentConfig: config,
- projectPolicy: projectExecutionWorkspacePolicy,
- issueSettings: issueExecutionWorkspaceSettings,
- mode: requestedExecutionWorkspaceMode,
- legacyUseProjectWorkspace: issueAssigneeOverrides?.useProjectWorkspace ?? null,
- });
- const persistedWorkspaceManagedConfig = applyPersistedExecutionWorkspaceConfig({
- config: workspaceManagedConfig,
- workspaceConfig: reusableExecutionWorkspaceConfig,
- mode: effectiveExecutionWorkspaceMode,
+ const workspaceManagedConfig = buildExecutionWorkspaceAdapterConfig({
+ agentConfig: config,
+ projectPolicy: projectExecutionWorkspacePolicy,
+ issueSettings: issueExecutionWorkspaceSettings,
+ mode: requestedExecutionWorkspaceMode,
+ legacyUseProjectWorkspace: issueAssigneeOverrides?.useProjectWorkspace ?? null,
});
let adapterModelProfiles: AdapterModelProfileDefinition[] = [];
let profileResolutionFallbackReason: string | null = null;
@@ -8956,7 +9667,7 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})
delete context.paperclipModelProfile;
}
const mergedConfig = mergeModelProfileAdapterConfig({
- baseConfig: persistedWorkspaceManagedConfig,
+ baseConfig: workspaceManagedConfig,
modelProfile: modelProfileApplication,
issueAdapterConfig: issueAssigneeOverrides?.adapterConfig ?? null,
});
@@ -9021,17 +9732,126 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})
...effectiveResolvedConfig,
paperclipRuntimeSkills: runtimeSkillEntries,
};
+ const latestAgentConfigRevision = await getLatestAgentConfigRevision(agent.companyId, agent.id);
+ const sessionConfigMetadata = await buildEffectiveRunSessionConfigMetadata({
+ adapterType: agent.adapterType,
+ effectiveAdapterConfig: runtimeConfig,
+ agentRuntimeConfig: agent.runtimeConfig,
+ modelProfile: modelProfileMetadata,
+ issueOverrides: issueAssigneeOverrides,
+ workspaceConfig: {
+ requestedMode: requestedExecutionWorkspaceMode,
+ effectiveMode: effectiveExecutionWorkspaceMode,
+ issueConfigRevisionAt: issueContext?.updatedAt instanceof Date
+ ? issueContext.updatedAt.toISOString()
+ : issueContext?.updatedAt ?? null,
+ projectConfigRevisionAt: projectContext?.updatedAt instanceof Date
+ ? projectContext.updatedAt.toISOString()
+ : projectContext?.updatedAt ?? null,
+ projectPolicy: projectExecutionWorkspacePolicy,
+ issueSettings: issueExecutionWorkspaceSettings,
+ reusableExecutionWorkspaceConfig: requestedReusableExecutionWorkspaceConfig,
+ existingExecutionWorkspace: existingExecutionWorkspace
+ ? {
+ id: existingExecutionWorkspace.id,
+ mode: existingExecutionWorkspace.mode,
+ strategyType: existingExecutionWorkspace.strategyType,
+ projectWorkspaceId: existingExecutionWorkspace.projectWorkspaceId,
+ repoUrl: existingExecutionWorkspace.repoUrl,
+ baseRef: existingExecutionWorkspace.baseRef,
+ branchName: existingExecutionWorkspace.branchName,
+ config: existingExecutionWorkspace.config,
+ }
+ : null,
+ },
+ environment: {
+ selectionSource: environmentResolution.source,
+ selectedEnvironmentId,
+ selectedEnvironment: selectedEnvironmentForConfig
+ ? {
+ id: selectedEnvironmentForConfig.id,
+ driver: selectedEnvironmentForConfig.driver,
+ config: selectedEnvironmentForConfig.config,
+ configRevisionAt: selectedEnvironmentForConfig.updatedAt instanceof Date
+ ? selectedEnvironmentForConfig.updatedAt.toISOString()
+ : selectedEnvironmentForConfig.updatedAt ?? null,
+ }
+ : null,
+ executionPolicy,
+ },
+ environmentEnv: selectedEnvironmentForConfig?.envVars ?? null,
+ projectEnv: projectContext?.env ?? null,
+ routineEnv: routineEnvContext.env,
+ secretManifest,
+ runtimeSkills: runtimeSkillEntries,
+ agentConfigRevision: latestAgentConfigRevision
+ ? {
+ id: latestAgentConfigRevision.id,
+ changedKeys: latestAgentConfigRevision.changedKeys,
+ configRevisionAt: latestAgentConfigRevision.createdAt.toISOString(),
+ }
+ : null,
+ });
+ const configuredModel = readConfiguredModelFromAdapterConfig(runtimeConfig);
+ const wakeSessionResetReason = describeSessionResetReason(context);
+ const sessionConfigFreshness = resolveTaskSessionConfigFreshness({
+ hasTaskSession: taskSession != null,
+ configuredModel,
+ taskSessionParams: taskSessionDecodedParams,
+ configMetadata: sessionConfigMetadata,
+ wakeResetReason: wakeSessionResetReason,
+ preserveLegacySessionWithoutConfigMetadata: acceptedPlanContinuationWake && !acceptedPlanWakeRoutingDecision,
+ });
+ const resetTaskSession = shouldResetTaskSessionForWake(context) || sessionConfigFreshness.reset;
+ const sessionResetReason = sessionConfigFreshness.reasons.join("; ") || null;
+ const taskSessionForRun = resetTaskSession ? null : taskSession;
+ const previousSessionParams =
+ explicitResumeSessionParams ??
+ (isCanonicalSessionIdForAdapter(agent.adapterType, explicitResumeSessionDisplayId)
+ ? { sessionId: explicitResumeSessionDisplayId }
+ : null) ??
+ normalizeResumeParamsForAdapter(
+ agent.adapterType,
+ stripPaperclipSessionMetadataFromSessionParams(
+ sessionCodec.deserialize(taskSessionForRun?.sessionParamsJson ?? null),
+ ),
+ );
+ const {
+ selectedEnvironmentDriver: lowTrustPreflightEnvironmentDriver,
+ workspace: resolvedWorkspace,
+ } = await resolveWorkspaceAfterLowTrustPreflight({
+ db,
+ trustPreset,
+ isolatedWorkspacesEnabled,
+ effectiveExecutionWorkspaceMode,
+ issue: issueRef
+ ? {
+ companyId: agent.companyId,
+ id: issueRef.id,
+ projectId: issueRef.projectId,
+ }
+ : null,
+ resolveSelectedEnvironmentDriver: async () => {
+ const preflightEnvironment = await envOrchestrator.resolveEnvironment({
+ companyId: agent.companyId,
+ selectedEnvironmentId,
+ localEnvironmentId: localEnvironment.id,
+ });
+ return preflightEnvironment.driver;
+ },
+ resolveWorkspace: () =>
+ resolveWorkspaceForRun(
+ agent,
+ context,
+ previousSessionParams,
+ { useProjectWorkspace: requestedExecutionWorkspaceMode !== "agent_default" },
+ ),
+ });
const hostExecutionWorkspaceConfig = stripHostWorkspaceProvisionForLowTrustSandbox({
- config: runtimeConfig,
+ config: mergedConfig,
trustPreset,
selectedEnvironmentDriver: lowTrustPreflightEnvironmentDriver,
});
- const workspaceOperationRecorder = workspaceOperationsSvc.createRecorder({
- companyId: agent.companyId,
- heartbeatRunId: run.id,
- executionWorkspaceId: existingExecutionWorkspace?.id ?? null,
- issueId,
- });
const executionWorkspaceBase = {
baseCwd: resolvedWorkspace.cwd,
source: resolvedWorkspace.source,
@@ -9040,6 +9860,88 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})
repoUrl: resolvedWorkspace.repoUrl,
repoRef: resolvedWorkspace.repoRef,
} satisfies ExecutionWorkspaceInput;
+ const workspaceStrategyForFingerprint = parseObject(hostExecutionWorkspaceConfig.workspaceStrategy);
+ const workspaceStrategyFingerprintValue =
+ Object.keys(workspaceStrategyForFingerprint).length > 0 ? workspaceStrategyForFingerprint : null;
+ const latestWorkspaceStrategyType =
+ readNonEmptyString(workspaceStrategyForFingerprint.type) ??
+ (requestedExecutionWorkspaceMode === "agent_default"
+ ? "adapter_managed"
+ : requestedExecutionWorkspaceMode === "isolated_workspace" ||
+ requestedExecutionWorkspaceMode === "operator_branch"
+ ? "git_worktree"
+ : "project_primary");
+ const selectedEnvironmentConfigForFingerprint = parseObject(selectedEnvironmentForConfig?.config);
+ const workspaceEnvironmentFingerprint = selectedEnvironmentForConfig
+ ? {
+ selectionSource: environmentResolution.source,
+ selectedEnvironmentId,
+ driver: selectedEnvironmentForConfig.driver,
+ provider: readNonEmptyString(selectedEnvironmentConfigForFingerprint.provider),
+ config: selectedEnvironmentForConfig.config,
+ configRevisionAt: selectedEnvironmentForConfig.updatedAt instanceof Date
+ ? selectedEnvironmentForConfig.updatedAt.toISOString()
+ : selectedEnvironmentForConfig.updatedAt ?? null,
+ executionPolicy,
+ }
+ : null;
+ const workspaceRealizationFingerprint = {
+ environmentDriver: selectedEnvironmentForConfig?.driver ?? null,
+ environmentProvider: readNonEmptyString(selectedEnvironmentConfigForFingerprint.provider),
+ trustPreset: trustPreset.kind,
+ lowTrustSandboxDriver: lowTrustPreflightEnvironmentDriver,
+ };
+ const latestWorkspaceConfigMetadata = buildEffectiveRunWorkspaceConfigMetadata({
+ mode: requestedExecutionWorkspaceMode,
+ projectId: executionWorkspaceBase.projectId,
+ projectWorkspaceId: executionWorkspaceBase.workspaceId,
+ strategyType: latestWorkspaceStrategyType,
+ workspaceStrategy: workspaceStrategyFingerprintValue,
+ repoUrl: executionWorkspaceBase.repoUrl,
+ repoRef: readNonEmptyString(workspaceStrategyForFingerprint.baseRef) ?? executionWorkspaceBase.repoRef,
+ configSnapshot,
+ environment: workspaceEnvironmentFingerprint,
+ realization: workspaceRealizationFingerprint,
+ secretManifest,
+ });
+ const inferredExistingWorkspaceConfigMetadata = existingExecutionWorkspace
+ ? buildEffectiveRunWorkspaceConfigMetadata({
+ mode: issueExecutionWorkspaceModeForPersistedWorkspace(existingExecutionWorkspace.mode),
+ projectId: existingExecutionWorkspace.projectId,
+ projectWorkspaceId: existingExecutionWorkspace.projectWorkspaceId,
+ strategyType: existingExecutionWorkspace.strategyType,
+ workspaceStrategy: workspaceStrategyFingerprintValue
+ ? {
+ ...workspaceStrategyFingerprintValue,
+ type: existingExecutionWorkspace.strategyType,
+ ...(existingExecutionWorkspace.baseRef
+ ? { baseRef: existingExecutionWorkspace.baseRef }
+ : {}),
+ }
+ : { type: existingExecutionWorkspace.strategyType },
+ repoUrl: existingExecutionWorkspace.repoUrl,
+ repoRef: existingExecutionWorkspace.baseRef,
+ configSnapshot: existingExecutionWorkspace.config,
+ environment: workspaceEnvironmentFingerprint,
+ realization: workspaceRealizationFingerprint,
+ secretManifest,
+ evaluatedAt: latestWorkspaceConfigMetadata.evaluatedAt,
+ })
+ : null;
+ const workspaceConfigFreshness = resolveExecutionWorkspaceConfigFreshness({
+ hasExistingWorkspace: requestedShouldReuseExisting && Boolean(existingExecutionWorkspace),
+ existingWorkspaceMetadata: existingExecutionWorkspace?.metadata ?? null,
+ inferredMetadata: inferredExistingWorkspaceConfigMetadata,
+ nextMetadata: latestWorkspaceConfigMetadata,
+ });
+ const shouldReuseExisting = requestedShouldReuseExisting && workspaceConfigFreshness.shouldReuseExisting;
+ const shouldRefreshWorkspaceConfigSnapshot = shouldReuseExisting && workspaceConfigFreshness.shouldRefreshConfigSnapshot;
+ const workspaceOperationRecorder = workspaceOperationsSvc.createRecorder({
+ companyId: agent.companyId,
+ heartbeatRunId: run.id,
+ executionWorkspaceId: shouldReuseExisting ? existingExecutionWorkspace?.id ?? null : null,
+ issueId,
+ });
const reusedExecutionWorkspace = shouldReuseExisting && existingExecutionWorkspace
? await ensurePersistedExecutionWorkspaceAvailable({
base: executionWorkspaceBase,
@@ -9056,7 +9958,8 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})
metadata: existingExecutionWorkspace.metadata as Record<string, unknown> | null,
config: {
provisionCommand:
- existingExecutionWorkspace.config?.provisionCommand
+ configSnapshot?.provisionCommand
+ ?? existingExecutionWorkspace.config?.provisionCommand
?? projectExecutionWorkspacePolicy?.workspaceStrategy?.provisionCommand
?? null,
},
@@ -9068,31 +9971,30 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})
companyId: agent.companyId,
},
recorder: workspaceOperationRecorder,
- }) ?? buildRealizedExecutionWorkspaceFromPersisted({
- base: executionWorkspaceBase,
- workspace: existingExecutionWorkspace,
})
: null;
const executionWorkspace = reusedExecutionWorkspace ?? await realizeExecutionWorkspace({
- base: executionWorkspaceBase,
- config: hostExecutionWorkspaceConfig,
- issue: issueRef,
- agent: {
- id: agent.id,
- name: agent.name,
- companyId: agent.companyId,
- },
- recorder: workspaceOperationRecorder,
- });
+ base: executionWorkspaceBase,
+ config: hostExecutionWorkspaceConfig,
+ issue: issueRef,
+ agent: {
+ id: agent.id,
+ name: agent.name,
+ companyId: agent.companyId,
+ },
+ recorder: workspaceOperationRecorder,
+ });
const resolvedProjectId = executionWorkspace.projectId ?? issueRef?.projectId ?? executionProjectId ?? null;
const resolvedProjectWorkspaceId = issueRef?.projectWorkspaceId ?? resolvedWorkspace.workspaceId ?? null;
let persistedExecutionWorkspace = null;
const nextExecutionWorkspaceMetadata = mergeExecutionWorkspaceMetadataForPersistence({
- existingMetadata: existingExecutionWorkspace?.metadata ?? null,
+ existingMetadata: shouldReuseExisting ? existingExecutionWorkspace?.metadata ?? null : null,
source: executionWorkspace.source,
createdByRuntime: executionWorkspace.created,
configSnapshot,
shouldReuseExisting,
+ shouldRefreshConfigSnapshot: shouldRefreshWorkspaceConfigSnapshot,
+ workspaceConfigMetadata: latestWorkspaceConfigMetadata,
baseRef: executionWorkspace.repoRef,
baseRefSha: executionWorkspace.baseRefSha ?? null,
});
@@ -9180,6 +10082,17 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})
throw error;
}
await workspaceOperationRecorder.attachExecutionWorkspaceId(persistedExecutionWorkspace?.id ?? null);
+ await recordWorkspaceConfigFreshnessOperation({
+ recorder: workspaceOperationRecorder,
+ runId: run.id,
+ decision: workspaceConfigFreshness,
+ hasExistingWorkspace: Boolean(existingExecutionWorkspace),
+ reuseRequested: requestedShouldReuseExisting,
+ workspaceReused: Boolean(reusedExecutionWorkspace),
+ configSnapshotRefreshed: shouldRefreshWorkspaceConfigSnapshot,
+ previousWorkspaceId: existingExecutionWorkspace?.id ?? null,
+ activeWorkspaceId: persistedExecutionWorkspace?.id ?? null,
+ });
if (
existingExecutionWorkspace &&
persistedExecutionWorkspace &&
@@ -9328,6 +10241,11 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})
...resolvedWorkspace.warnings,
...executionWorkspace.warnings,
...(runtimeSessionResolution.warning ? [runtimeSessionResolution.warning] : []),
+ ...(requestedShouldReuseExisting && workspaceConfigFreshness.reasons.length > 0
+ ? [
+ `Execution workspace reuse freshness action "${workspaceConfigFreshness.action}" because ${workspaceConfigFreshness.reasons.join("; ")}.`,
+ ]
+ : []),
...(resetTaskSession && sessionResetReason
? [
taskKey
@@ -9356,7 +10274,7 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})
};
context.paperclipWorkspaces = resolvedWorkspace.workspaceHints;
const runtimeServiceIntents = (() => {
- const runtimeConfig = parseObject(resolvedConfig.workspaceRuntime);
+ const runtimeConfig = parseObject(hostExecutionWorkspaceConfig.workspaceRuntime);
return Array.isArray(runtimeConfig.services)
? runtimeConfig.services.filter(
(value): value is Record<string, unknown> => typeof value === "object" && value !== null,
@@ -9397,7 +10315,7 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})
let runtimeSessionIdForAdapter =
readNonEmptyString(runtimeSessionParams?.sessionId) ?? runtimeSessionFallback;
let runtimeSessionParamsForAdapter = normalizeSessionParams(
- stripConfiguredModelFromSessionParams(runtimeSessionParams),
+ stripPaperclipSessionMetadataFromSessionParams(runtimeSessionParams),
);
const sessionCompaction = await evaluateSessionCompaction({
@@ -9430,6 +10348,36 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})
sessionDisplayId: previousSessionDisplayId,
taskKey,
};
+ const configFreshnessResultMetadata = {
+ version: sessionConfigMetadata.version,
+ session: {
+ fingerprintVersion: sessionConfigMetadata.version,
+ categories: sessionConfigMetadata.categories,
+ reset: resetTaskSession,
+ resetReasons: sessionConfigFreshness.reasons,
+ changedCategories: sessionConfigFreshness.changedCategories,
+ taskSessionAvailable: taskSession != null,
+ taskSessionReused: taskSessionForRun != null,
+ storedFingerprintPresent: Boolean(sessionConfigFreshness.storedFingerprint),
+ nextFingerprint: sessionConfigFreshness.nextFingerprint,
+ },
+ workspace: {
+ fingerprintVersion: latestWorkspaceConfigMetadata.version,
+ categories: latestWorkspaceConfigMetadata.categories,
+ action: workspaceConfigFreshness.action,
+ changedCategories: workspaceConfigFreshness.changedCategories,
+ reasons: workspaceConfigFreshness.reasons,
+ reuseRequested: requestedShouldReuseExisting,
+ workspaceReused: Boolean(reusedExecutionWorkspace),
+ configSnapshotRefreshed: shouldRefreshWorkspaceConfigSnapshot,
+ storedFingerprintPresent: workspaceConfigFreshness.storedFingerprintPresent,
+ storedFingerprint: workspaceConfigFreshness.storedFingerprint,
+ inferredFingerprint: workspaceConfigFreshness.inferredFingerprint,
+ nextFingerprint: workspaceConfigFreshness.nextFingerprint,
+ previousWorkspaceId: existingExecutionWorkspace?.id ?? null,
+ activeWorkspaceId: persistedExecutionWorkspace?.id ?? null,
+ },
+ };
let seq = 1;
let handle: RunLogHandle | null = null;
@@ -9439,10 +10387,10 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})
let lastOutputFlushAt: Date | null = run.lastOutputAt ?? null;
const outputProgressState: {
pending: {
- at: Date;
- seq: number;
- stream: "stdout" | "stderr";
- bytes: number;
+ at: Date;
+ seq: number;
+ stream: "stdout" | "stderr";
+ bytes: number;
} | null;
} = { pending: null };
let persistedLogBytes = Number(run.logBytes ?? 0);
@@ -9649,7 +10597,7 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})
issue: issueRef,
workspace: executionWorkspace,
executionWorkspaceId: persistedExecutionWorkspace?.id ?? issueRef?.executionWorkspaceId ?? null,
- config: effectiveResolvedConfig,
+ config: hostExecutionWorkspaceConfig,
adapterEnv,
onLog,
});
@@ -9925,6 +10873,7 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})
freshSession: runtimeForAdapter.sessionId == null && runtimeForAdapter.sessionDisplayId == null,
sessionRotated: sessionCompaction.rotate,
sessionRotationReason: sessionCompaction.reason,
+ configFreshness: configFreshnessResultMetadata,
provider: readNonEmptyString(adapterResult.provider) ?? "unknown",
biller: resolveLedgerBiller(adapterResult),
model: readNonEmptyString(adapterResult.model) ?? "unknown",
@@ -9937,7 +10886,10 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})
mergeRunStopMetadataForAgent(agent, outcome, {
resultJson: mergeModelProfileRunMetadata(
mergeAdapterRecoveryMetadata({
- resultJson: adapterResult.resultJson ?? null,
+ resultJson: {
+ ...parseObject(adapterResult.resultJson),
+ configFreshness: configFreshnessResultMetadata,
+ },
errorFamily: adapterResult.errorFamily ?? null,
retryNotBefore: adapterResult.retryNotBefore ?? null,
}),
@@ -10119,7 +11071,11 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})
agentId: agent.id,
adapterType: agent.adapterType,
taskKey,
- sessionParamsJson: attachConfiguredModelToSessionParams(nextSessionState.params, configuredModel),
+ sessionParamsJson: attachPaperclipSessionMetadataToSessionParams(
+ nextSessionState.params,
+ configuredModel,
+ sessionConfigMetadata,
+ ),
sessionDisplayId: nextSessionState.displayId,
lastRunId: finalizedRun.id,
lastError: outcome === "succeeded" ? null : (adapterResult.errorMessage ?? "run_failed"),
@@ -10221,7 +11177,11 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})
agentId: agent.id,
adapterType: agent.adapterType,
taskKey,
- sessionParamsJson: attachConfiguredModelToSessionParams(previousSessionParams, configuredModel),
+ sessionParamsJson: attachPaperclipSessionMetadataToSessionParams(
+ previousSessionParams,
+ configuredModel,
+ sessionConfigMetadata,
+ ),
sessionDisplayId: previousSessionDisplayId,
lastRunId: failedRun.id,
lastError: message,
diff --git a/server/src/services/secrets.ts b/server/src/services/secrets.ts
index 69fefbbe3d..860c5a7ff6 100644
--- a/server/src/services/secrets.ts
+++ b/server/src/services/secrets.ts
@@ -244,6 +244,7 @@ export type RuntimeSecretManifestEntry = {
secretKey: string;
version: number;
provider: SecretProvider;
+ providerVersionRef?: string | null;
outcome: "success" | "failure";
errorCode?: string | null;
};
@@ -696,6 +697,7 @@ export function secretService(db: Db) {
secretKey: secret.key,
version: resolvedVersion,
provider: providerId,
+ providerVersionRef: versionRow.providerVersionRef,
outcome: "success",
},
};
diff --git a/server/src/services/workspace-runtime.ts b/server/src/services/workspace-runtime.ts
index 6d486a923b..5b29ffcfbb 100644
--- a/server/src/services/workspace-runtime.ts
+++ b/server/src/services/workspace-runtime.ts
@@ -1471,6 +1471,9 @@ export async function ensurePersistedExecutionWorkspaceAvailable(input: {
const provisionCommand = asString(input.workspace.config?.provisionCommand, "").trim();
if (strategy !== "git_worktree") {
+ if (!await directoryExists(cwd)) {
+ return null;
+ }
return realized;
}
const repoRoot = await runGit(["rev-parse", "--show-toplevel"], input.base.baseCwd);
diff --git a/ui/src/pages/AgentDetail.tsx b/ui/src/pages/AgentDetail.tsx
index 8005509165..d591392f3e 100644
--- a/ui/src/pages/AgentDetail.tsx
+++ b/ui/src/pages/AgentDetail.tsx
@@ -431,6 +431,8 @@ function workspaceOperationPhaseLabel(phase: WorkspaceOperation["phase"]) {
switch (phase) {
case "worktree_prepare":
return "Worktree setup";
+ case "workspace_config_freshness":
+ return "Config freshness";
case "workspace_provision":
return "Provision";
case "workspace_teardown":
@@ -1671,6 +1673,9 @@ function ConfigurationTab({
hideInstructionsFile={hideInstructionsFile}
sectionLayout="cards"
/>
+ <p className="text-xs text-muted-foreground">
+ Saved adapter config affects the next run. Active runs keep the config they started with, and config changes may start a fresh adapter session.
+ </p>
<TrustPresetSection
permissions={agent.permissions}
@@ -2114,6 +2119,9 @@ function PromptsTab({
))}
</div>
)}
+ <p className="text-xs text-muted-foreground">
+ Saved instructions affect the next run. Active runs keep the instructions they started with, and instruction changes may start a fresh adapter session.
+ </p>
<Collapsible defaultOpen={currentMode === "external"}>
<CollapsibleTrigger className="flex items-center gap-1 text-xs text-muted-foreground hover:text-foreground transition-colors group">
diff --git a/ui/src/pages/CompanyEnvironments.tsx b/ui/src/pages/CompanyEnvironments.tsx
index b405d0fc28..2f475fddb3 100644
--- a/ui/src/pages/CompanyEnvironments.tsx
+++ b/ui/src/pages/CompanyEnvironments.tsx
@@ -1049,7 +1049,7 @@ export function CompanyEnvironments() {
<DialogHeader className="border-b border-border/60 px-6 pb-4 pr-12 pt-6">
<DialogTitle>{editingEnvironmentId ? "Edit environment" : "Add environment"}</DialogTitle>
<DialogDescription>
- Configure a reusable execution target for your agents.
+ Configure a reusable execution target for your agents. Saved changes affect future runs; Paperclip may start fresh sessions or sandbox leases after environment config changes.
</DialogDescription>
</DialogHeader>
diff --git a/ui/src/pages/ExecutionWorkspaceDetail.tsx b/ui/src/pages/ExecutionWorkspaceDetail.tsx
index 97e333b004..75141c3094 100644
--- a/ui/src/pages/ExecutionWorkspaceDetail.tsx
+++ b/ui/src/pages/ExecutionWorkspaceDetail.tsx
@@ -259,6 +259,25 @@ function Field({
);
}
+function workspaceOperationPhaseLabel(phase: string) {
+ switch (phase) {
+ case "worktree_prepare":
+ return "Worktree setup";
+ case "workspace_config_freshness":
+ return "Config freshness";
+ case "workspace_provision":
+ return "Provision";
+ case "workspace_teardown":
+ return "Teardown";
+ case "worktree_cleanup":
+ return "Worktree cleanup";
+ case "workspace_finalize":
+ return "Finalize";
+ default:
+ return phase;
+ }
+}
+
function DetailRow({ label, children }: { label: string; children: React.ReactNode }) {
return (
<div className="flex flex-col gap-1.5 py-1.5 sm:flex-row sm:items-start sm:gap-3">
@@ -845,7 +864,7 @@ export function ExecutionWorkspaceDetail() {
<CardHeader>
<CardTitle>Workspace settings</CardTitle>
<CardDescription>
- Edit the concrete path, repo, branch, provisioning, teardown, and runtime overrides attached to this execution workspace.
+ Edit the concrete path, repo, branch, provisioning, teardown, and runtime overrides attached to this execution workspace. Saved changes affect future runs; Paperclip may refresh or replace a reused workspace when config changes.
</CardDescription>
<CardAction>
<Button
@@ -1173,7 +1192,7 @@ export function ExecutionWorkspaceDetail() {
<div key={operation.id} className="rounded-none border border-border/80 bg-background px-4 py-3">
<div className="flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between">
<div className="space-y-1">
- <div className="text-sm font-medium">{operation.command ?? operation.phase}</div>
+ <div className="text-sm font-medium">{operation.command ?? workspaceOperationPhaseLabel(operation.phase)}</div>
<div className="text-xs text-muted-foreground">
{formatDateTime(operation.startedAt)}
{operation.finishedAt ? ` → ${formatDateTime(operation.finishedAt)}` : ""}