fix: make worktree lifecycle failures durable

packages/protocol/src/messages.ts

@@ -4735,6 +4735,8 @@ export const PaseoWorktreeArchiveResponseSchema = z.object({
   payload: z.object({
     success: z.boolean(),
     removedAgents: z.array(z.string()).optional(),
+    removedDirectory: z.boolean().optional(),
+    cleanupPending: z.boolean().optional(),
     error: CheckoutErrorSchema.nullable(),
     requestId: z.string(),
   }),

packages/server/src/server/agent/agent-loading.ts

@@ -22,6 +22,7 @@ export type AgentLoaderManager = Pick<
   AgentManager,
   | "createAgent"
   | "getAgent"
+  | "getAgentInitializationState"
   | "getRegisteredProviderIds"
   | "hydrateTimelineFromProvider"
   | "resumeAgentFromPersistence"
@@ -63,28 +64,26 @@ export async function ensureAgentLoaded(
   agentId: string,
   deps: EnsureAgentLoadedDeps,
 ): Promise<ManagedAgent> {
-  await deps.agentManager.waitForAgentClose?.(agentId);
+  while (true) {
+    await deps.agentManager.waitForAgentClose?.(agentId);
 
-  const inflight = pendingAgentInitializations.get(agentId);
-  if (inflight) {
-    inflight.options.broadcastTimeline ||= deps.broadcastTimeline === true;
-    return inflight.promise;
-  }
-
-  const existing = deps.agentManager.getAgent(agentId);
-  if (existing) {
-    return existing;
-  }
-
-  // A close may have started after the first barrier observed no in-flight
-  // work. Once the live lookup is empty, this second barrier closes that gap
-  // before storage-backed resume begins.
-  await deps.agentManager.waitForAgentClose?.(agentId);
+    const inflight = pendingAgentInitializations.get(agentId);
+    if (inflight) {
+      inflight.options.broadcastTimeline ||= deps.broadcastTimeline === true;
+      return inflight.promise;
+    }
 
-  const laterInflight = pendingAgentInitializations.get(agentId);
-  if (laterInflight) {
-    laterInflight.options.broadcastTimeline ||= deps.broadcastTimeline === true;
-    return laterInflight.promise;
+    // The close barrier and the runtime lookup cannot be made atomic across an
+    // await. Re-read both pieces of state synchronously so a close that starts
+    // in that gap is joined on the next pass instead of returning its runtime.
+    const initializationState = deps.agentManager.getAgentInitializationState(agentId);
+    if (initializationState.closeInFlight) {
+      continue;
+    }
+    if (initializationState.agent) {
+      return initializationState.agent;
+    }
+    break;
   }
 
   const pendingOptions = {
@@ -109,7 +108,10 @@ export async function ensureAgentLoaded(
         handle,
         buildConfigOverrides(record),
         agentId,
-        extractTimestamps(record),
+        {
+          ...extractTimestamps(record),
+          autoArchiveObligation: record.autoArchiveObligation,
+        },
         record.archivedAt ? { purpose: "history" } : undefined,
       );
       deps.logger.info({ agentId, provider: record.provider }, "Agent resumed from persistence");
@@ -124,6 +126,7 @@ export async function ensureAgentLoaded(
         labels: record.labels,
         workspaceId: record.workspaceId,
         owner: record.owner,
+        autoArchiveObligation: record.autoArchiveObligation,
       });
       deps.logger.info({ agentId, provider: record.provider }, "Agent created from stored config");
     }

packages/server/src/server/agent/agent-manager.test.ts

@@ -248,6 +248,7 @@ class HeldReloadCloseClient extends TestAgentClient {
   private readonly closeAllowed = deferred<void>();
   originalSessionClosed = false;
   replacementSessionClosed = false;
+  resumeCount = 0;
 
   override async createSession(config: AgentSessionConfig): Promise<AgentSession> {
     const signalCloseStarted = () => this.closeStarted.resolve();
@@ -268,6 +269,7 @@ class HeldReloadCloseClient extends TestAgentClient {
     _handle: AgentPersistenceHandle,
     config?: Partial<AgentSessionConfig>,
   ): Promise<AgentSession> {
+    this.resumeCount += 1;
     const recordReplacementClosed = () => {
       this.replacementSessionClosed = true;
     };
@@ -7916,6 +7918,58 @@ test("load waits for an in-flight explicit close and creates one resumed runtime
   }
 });
 
+test("load joins a close that starts after its barrier but before runtime lookup", async () => {
+  const workdir = mkdtempSync(join(tmpdir(), "agent-manager-close-start-gap-"));
+  const storage = new AgentStorage(join(workdir, "agents"), logger);
+  const client = new HeldReloadCloseClient();
+  const manager = new AgentManager({ clients: { codex: client }, registry: storage, logger });
+  const agentId = "00000000-0000-4000-8000-000000000218";
+  let closeTask: Promise<void> | null = null;
+
+  try {
+    await manager.createAgent({ provider: "codex", cwd: workdir }, agentId, {
+      workspaceId: undefined,
+    });
+    const waitForAgentClose = manager.waitForAgentClose.bind(manager);
+    vi.spyOn(manager, "waitForAgentClose")
+      .mockImplementation(async (id) => waitForAgentClose(id))
+      .mockImplementationOnce(async () => {
+        queueMicrotask(() => {
+          closeTask = manager.closeAgent(agentId);
+        });
+      });
+
+    let loadSettled = false;
+    const load = ensureAgentLoaded(agentId, {
+      agentManager: manager,
+      agentStorage: storage,
+      logger,
+    }).then((agent) => {
+      loadSettled = true;
+      return agent;
+    });
+
+    await client.waitForCloseToStart();
+    await Promise.resolve();
+    expect(loadSettled).toBe(false);
+    expect(client.resumeCount).toBe(0);
+
+    client.finishClosing();
+    const resumed = await load;
+    await closeTask;
+
+    expect(resumed).toMatchObject({ id: agentId, lifecycle: "idle" });
+    expect(client.originalSessionClosed).toBe(true);
+    expect(client.resumeCount).toBe(1);
+  } finally {
+    client.finishClosing();
+    await closeTask?.catch(() => undefined);
+    await manager.closeAgent(agentId).catch(() => undefined);
+    await storage.flush().catch(() => undefined);
+    rmSync(workdir, { recursive: true, force: true });
+  }
+});
+
 test("concurrent explicit closes tear down the runtime once", async () => {
   const workdir = mkdtempSync(join(tmpdir(), "agent-manager-concurrent-close-"));
   const closeStarted = deferred<void>();

packages/server/src/server/agent/agent-manager.ts

@@ -44,7 +44,7 @@ import {
   type ListImportableSessionsOptions,
 } from "./agent-sdk-types.js";
 import { buildArchivedAgentRecord, type ArchivedStoredAgentRecord } from "./agent-archive.js";
-import type { StoredAgentRecord, AgentStorage } from "./agent-storage.js";
+import type { AutoArchiveObligation, StoredAgentRecord, AgentStorage } from "./agent-storage.js";
 import type { AgentOwner } from "./agent-owner.js";
 import {
   InMemoryAgentTimelineStore,
@@ -246,6 +246,7 @@ export interface CreateAgentOptions {
   // undefined is an explicit decision: the agent never appears in the sidebar.
   workspaceId: string | undefined;
   owner?: AgentOwner;
+  autoArchiveObligation?: AutoArchiveObligation;
 }
 
 export interface AgentManagerOptions {
@@ -1000,6 +1001,17 @@ export class AgentManager {
     return agent ? { ...agent } : null;
   }
 
+  getAgentInitializationState(id: string): {
+    agent: ManagedAgent | null;
+    closeInFlight: boolean;
+  } {
+    const closeInFlight = this.inFlightAgentCloses.has(id);
+    return {
+      agent: closeInFlight ? null : this.getAgent(id),
+      closeInFlight,
+    };
+  }
+
   async waitForAgentClose(agentId: string): Promise<void> {
     await this.inFlightAgentCloses?.get(agentId)?.catch(() => undefined);
   }
@@ -1052,6 +1064,10 @@ export class AgentManager {
     return this.trackAgentRegistrationOperation(this.createAgentInternal(config, agentId, options));
   }
 
+  allocateAgentId(): string {
+    return validateAgentId(this.idFactory(), "allocateAgentId");
+  }
+
   private async createAgentInternal(
     config: AgentSessionConfig,
     agentId: string | undefined,
@@ -1083,6 +1099,7 @@ export class AgentManager {
       initialTitle: options.initialTitle,
       workspaceId: options.workspaceId,
       owner: options.owner,
+      autoArchiveObligation: options.autoArchiveObligation,
     });
   }
 
@@ -1107,6 +1124,7 @@ export class AgentManager {
       labels?: Record<string, string>;
       workspaceId?: string;
       owner?: AgentOwner;
+      autoArchiveObligation?: AutoArchiveObligation;
     },
     resumeOptions?: AgentResumeSessionOptions,
   ): Promise<ManagedAgent> {
@@ -1126,6 +1144,7 @@ export class AgentManager {
       labels?: Record<string, string>;
       workspaceId?: string;
       owner?: AgentOwner;
+      autoArchiveObligation?: AutoArchiveObligation;
     },
     resumeOptions?: AgentResumeSessionOptions,
   ): Promise<ManagedAgent> {
@@ -2801,6 +2820,7 @@ export class AgentManager {
       publishWhenReady?: boolean;
       workspaceId?: string;
       owner?: AgentOwner;
+      autoArchiveObligation?: AutoArchiveObligation;
     },
   ): Promise<ManagedAgent> {
     let registered = false;
@@ -2841,6 +2861,7 @@ export class AgentManager {
       this.assertAgentRegistrationActive(managed);
       await this.persistSnapshot(managed, {
         title: initialPersistedTitle,
+        autoArchiveObligation: options?.autoArchiveObligation,
       });
       this.assertAgentRegistrationActive(managed);
       if (!options?.publishWhenReady) {
@@ -3191,7 +3212,11 @@ export class AgentManager {
 
   private async persistSnapshot(
     agent: ManagedAgent,
-    options?: { title?: string | null; internal?: boolean },
+    options?: {
+      title?: string | null;
+      internal?: boolean;
+      autoArchiveObligation?: AutoArchiveObligation;
+    },
   ): Promise<void> {
     if (!this.registry) {
       return;

packages/server/src/server/agent/agent-storage.test.ts

@@ -192,6 +192,114 @@ describe("AgentStorage", () => {
     expect(persisted.config?.extra?.claude).toMatchObject({ maxThinkingTokens: 1024 });
   });
 
+  test("persists auto-archive obligations across restart", async () => {
+    await storage.applySnapshot(createManagedAgent({ id: "agent-auto-archive" }), {
+      autoArchiveObligation: {
+        phase: "armed",
+        target: { kind: "workspace", workspaceId: "ws-auto-archive" },
+      },
+    });
+
+    const reloaded = new AgentStorage(storagePath, logger);
+    await expect(reloaded.get("agent-auto-archive")).resolves.toMatchObject({
+      autoArchiveObligation: {
+        phase: "armed",
+        target: { kind: "workspace", workspaceId: "ws-auto-archive" },
+      },
+    });
+  });
+
+  test("persists pending creation intent separately from visible agents", async () => {
+    await storage.beginPendingAgentCreation("agent-pending-create");
+    await storage.planPendingAgentCreationWorktree(
+      "agent-pending-create",
+      "/tmp/paseo/worktrees/project/feature-2",
+      {
+        worktreeIncarnationId: "4d2ce498-4c27-4ea2-8ed3-46720de7194e",
+        metadataBaseRefName: "main",
+      },
+    );
+    await expect(storage.listPendingAgentCreations()).resolves.toMatchObject([
+      {
+        cleanupTarget: {
+          kind: "worktree",
+          targetPath: "/tmp/paseo/worktrees/project/feature-2",
+          worktreeIncarnationId: "4d2ce498-4c27-4ea2-8ed3-46720de7194e",
+          directoryIdentity: null,
+        },
+      },
+    ]);
+    await storage.identifyPendingAgentCreationWorktree(
+      "agent-pending-create",
+      "/tmp/paseo/worktrees/project/feature-2",
+      {
+        worktreeIncarnationId: "4d2ce498-4c27-4ea2-8ed3-46720de7194e",
+        directoryIdentity: { device: "7", inode: "42" },
+        metadataBaseRefName: "main",
+      },
+    );
+
+    const reloaded = new AgentStorage(storagePath, logger);
+    await expect(reloaded.list()).resolves.toEqual([]);
+    await expect(reloaded.listPendingAgentCreations()).resolves.toEqual([
+      {
+        agentId: "agent-pending-create",
+        createdAt: expect.any(String),
+        ownerKind: "agent",
+        cleanupTarget: {
+          kind: "worktree",
+          targetPath: "/tmp/paseo/worktrees/project/feature-2",
+          worktreeIncarnationId: "4d2ce498-4c27-4ea2-8ed3-46720de7194e",
+          directoryIdentity: { device: "7", inode: "42" },
+          metadataBaseRefName: "main",
+        },
+      },
+    ]);
+
+    await reloaded.removePendingAgentCreation("agent-pending-create");
+    await expect(reloaded.listPendingAgentCreations()).resolves.toEqual([]);
+  });
+
+  test.each(["armed", "pending"] as const)(
+    "explicit undefined preserves a persisted %s auto-archive obligation",
+    async (phase) => {
+      const agent = createManagedAgent({ id: `agent-auto-archive-${phase}` });
+      await storage.applySnapshot(agent, {
+        autoArchiveObligation: { phase, target: { kind: "agent" } },
+      });
+
+      await storage.applySnapshot(
+        { ...agent, updatedAt: new Date("2025-02-01") },
+        {
+          autoArchiveObligation: undefined,
+        },
+      );
+
+      const reloaded = new AgentStorage(storagePath, logger);
+      await expect(reloaded.get(agent.id)).resolves.toMatchObject({
+        autoArchiveObligation: { phase, target: { kind: "agent" } },
+      });
+    },
+  );
+
+  test("serialized snapshots cannot overwrite a pending auto-archive obligation", async () => {
+    const agent = createManagedAgent({ id: "agent-auto-archive-race" });
+    await storage.applySnapshot(agent, {
+      autoArchiveObligation: { phase: "armed", target: { kind: "agent" } },
+    });
+
+    const pending = storage.update(agent.id, (record) => ({
+      ...record,
+      autoArchiveObligation: { phase: "pending", target: { kind: "agent" } },
+    }));
+    const snapshot = storage.applySnapshot({ ...agent, updatedAt: new Date("2025-02-01") });
+    await Promise.all([pending, snapshot]);
+
+    await expect(storage.get(agent.id)).resolves.toMatchObject({
+      autoArchiveObligation: { phase: "pending", target: { kind: "agent" } },
+    });
+  });
+
   test("applySnapshot stores and reloads featureValues when present", async () => {
     await storage.applySnapshot(
       createManagedAgent({