diff --git a/docs/plugins.md b/docs/plugins.md index e177d438f3..e370283a11 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -471,6 +471,18 @@ Workspace records decide ownership, including explicit non-ownership after recov ownership checks prefer the marker-verified worktree root over the legacy path shape: a plugin can place a worktree several directories below the default worktrees root. +A plugin can also take over worktree creation, removal, and restoration with +`server.registerWorktreeManager({ create, remove?, restore? })`. It runs after +`worktree.create.before` and before `worktree.create.after`, with a 120-second timeout matching Git +worktree commands. Paseo snapshots existing worktree paths before calling `create` so a manager +cannot adopt a pre-existing directory as Paseo-owned, verifies Git worktree postconditions, records +`worktreeManagerPluginId` in `paseo/worktree.json` and on the workspace record, +and skips first-agent branch auto-rename. Removal saves `refs/paseo/kept-commits/` before +calling the owning plugin's `remove`, and `create`, `remove`, and `restore` carry `untrusted` for fork +change requests; `remove` and `restore` fall back to built-in Git when the plugin declines or is disabled. See the +[worktree managers reference](../public-docs/plugins/reference.md#worktree-managers) and +`plugin-examples/worktrunk`. + Emit from the operation owner, not a client subscription. Provider history replay must not trigger live hooks. Notifications must not be awaited inside agent mutations: a handler can send a prompt or answer a permission through its own daemon session. Awaiting it there deadlocks that command. diff --git a/packages/cli/src/commands/worktree/create-input.test.ts b/packages/cli/src/commands/worktree/create-input.test.ts index 2091fcd6e4..17d4ed9d45 100644 --- a/packages/cli/src/commands/worktree/create-input.test.ts +++ b/packages/cli/src/commands/worktree/create-input.test.ts @@ -1,4 +1,5 @@ import { describe, expect, it } from "vitest"; +import { runCreateCommandWithDeps } from "./create.js"; import { buildCreateWorktreeRequest, type WorktreeCreateOptions } from "./create-input.js"; const REPO = "/tmp/repo"; @@ -77,3 +78,52 @@ describe("buildCreateWorktreeRequest", () => { }); }); }); + +it("uses the explicit worktree creation RPC and returns the created worktree details", async () => { + const result = await runCreateCommandWithDeps( + { + daemonTarget: { kind: "endpoint", host: "example.test:12345" }, + mode: "branch-off", + newBranch: "topic", + base: "main", + cwd: REPO, + }, + { + connectToDaemon: async () => ({ + createPaseoWorktree: async (input) => { + expect(input).toEqual({ + cwd: REPO, + worktreeSlug: "topic", + action: "branch-off", + refName: "main", + }); + return { + workspace: { + id: "wks_topic", + projectId: "project", + projectDisplayName: "Repo", + projectRootPath: REPO, + workspaceDirectory: `${REPO}/topic`, + projectKind: "git", + workspaceKind: "worktree", + name: "topic", + status: "idle", + statusEnteredAt: null, + activityAt: null, + archivingAt: null, + scripts: [], + }, + error: null, + requestId: "worktree-create", + }; + }, + close: async () => {}, + }), + }, + ); + expect(result.data).toEqual({ + name: "topic", + branchName: "topic", + worktreePath: `${REPO}/topic`, + }); +}); diff --git a/packages/cli/src/commands/worktree/create.ts b/packages/cli/src/commands/worktree/create.ts index da7d873b5a..9f165316f4 100644 --- a/packages/cli/src/commands/worktree/create.ts +++ b/packages/cli/src/commands/worktree/create.ts @@ -26,11 +26,22 @@ function cmdError(code: string, message: string, details?: string): CommandError export async function runCreateCommand( options: WorktreeCreateOptions, _command: Command, +): Promise> { + return runCreateCommandWithDeps(options, { connectToDaemon }); +} + +export async function runCreateCommandWithDeps( + options: WorktreeCreateOptions, + deps: { + connectToDaemon( + options: Parameters[0], + ): Promise>, "createPaseoWorktree" | "close">>; + }, ): Promise> { const cwd = options.cwd ?? process.cwd(); const request = buildCreateWorktreeRequest(options, cwd); - const client = await connectToDaemon({ target: options.daemonTarget }); + const client = await deps.connectToDaemon({ target: options.daemonTarget }); try { const response = await client.createPaseoWorktree(request); diff --git a/packages/client/src/daemon-client.test.ts b/packages/client/src/daemon-client.test.ts index af1f2edd1f..9826a287c3 100644 --- a/packages/client/src/daemon-client.test.ts +++ b/packages/client/src/daemon-client.test.ts @@ -1623,6 +1623,106 @@ test("defaults session RPC waiters to sixty seconds", async () => { await expect(responsePromise).rejects.toThrow("No response to fetch_agent_request after 60000ms"); }); +test.each([ + [ + "archive_workspace_request", + (client: DaemonClient) => client.archiveWorkspace("workspace-1"), + (requestId: string) => ({ + type: "archive_workspace_response" as const, + payload: { + requestId, + workspaceId: "workspace-1", + archivedAt: "2026-01-01T00:00:00.000Z", + error: null, + }, + }), + ], + [ + "paseo_worktree_archive_request", + (client: DaemonClient) => client.archivePaseoWorktree({ worktreePath: "/repo/worktree" }), + (requestId: string) => ({ + type: "paseo_worktree_archive_response" as const, + payload: { requestId, success: true, removedAgents: [], error: null }, + }), + ], + [ + "workspace.recovery.restore.request", + (client: DaemonClient) => client.restoreWorkspace("workspace-1"), + (requestId: string) => ({ + type: "workspace.recovery.restore.response" as const, + payload: { requestId, workspaceId: "workspace-1", accepted: true, error: null }, + }), + ], + [ + "workspace.archive.undo.request", + (client: DaemonClient) => client.undoWorkspaceArchive("workspace-1"), + (requestId: string) => ({ + type: "workspace.archive.undo.response" as const, + payload: { requestId, workspaceId: "workspace-1", accepted: true, error: null }, + }), + ], + [ + "open_project_request", + (client: DaemonClient) => client.openProject("/repo/worktree"), + (requestId: string) => ({ + type: "open_project_response" as const, + payload: { requestId, workspace: null, error: null }, + }), + ], + [ + "create_paseo_worktree_request", + (client: DaemonClient) => client.createPaseoWorktree({ cwd: "/repo", worktreeSlug: "topic" }), + (requestId: string) => ({ + type: "create_paseo_worktree_response" as const, + payload: { requestId, workspace: null, error: null, setupTerminalId: null }, + }), + ], +] as const)( + "waits on %s across queued and bounded daemon stages until response or disconnect", + async (_type, run, buildResponse) => { + useHeartbeatClock(); + const transport = createMockTransport(); + const client = new DaemonClient({ + url: "ws://test", + clientId: "worktree-lifecycle-wait-test", + logger: createMockLogger(), + reconnect: { enabled: false }, + transportFactory: () => transport.transport, + }); + clients.push(client); + + const connecting = client.connect(); + transport.triggerOpen(); + await connecting; + + const pending = run(client); + const sentFrame = JSON.parse(assertStr(transport.sent.at(-1))) as { + message: { requestId: string }; + }; + let settled = false; + void pending.then( + () => { + settled = true; + return undefined; + }, + () => { + settled = true; + return undefined; + }, + ); + await vi.advanceTimersByTimeAsync(200_000); + await Promise.resolve(); + expect(settled).toBe(false); + + transport.triggerMessage(wrapSessionMessage(buildResponse(sentFrame.message.requestId))); + await expect(pending).resolves.not.toThrow(); + + const disconnected = run(client); + transport.triggerClose({ code: 1006, reason: "gone" }); + await expect(disconnected).rejects.toMatchObject({ code: "DAEMON_CONNECTION_LOST" }); + }, +); + test("honors explicit fetchAgent timeout below the session RPC default", async () => { useHeartbeatClock(); const logger = createMockLogger(); diff --git a/packages/client/src/daemon-client.ts b/packages/client/src/daemon-client.ts index 8bc2baa8ef..aa68f82c4c 100644 --- a/packages/client/src/daemon-client.ts +++ b/packages/client/src/daemon-client.ts @@ -3188,6 +3188,9 @@ export class DaemonClient { cwd, }, responseType: "open_project_response", + // Opening a path whose checkout is currently archiving waits on the daemon checkout gate; + // wait for the terminal response or transport disconnect instead of timing out while queued. + timeout: 0, }); } @@ -3319,6 +3322,9 @@ export class DaemonClient { workspaceId, }, responseType: "archive_workspace_response", + // Archive may wait for a queued checkout operation and then run teardown/manager removal, + // each bounded on the daemon; wait for the terminal response or transport disconnect. + timeout: 0, }); } @@ -3841,7 +3847,9 @@ export class DaemonClient { type: "workspace.recovery.restore.request", workspaceId, }, - timeout: 150_000, + // Restore may wait behind an active archive/removal before running a bounded restore stage; + // wait for the terminal response or transport disconnect instead of timing out mid-workflow. + timeout: 0, }); if (!payload.accepted) { throw new Error(payload.error ?? "Workspace recovery was rejected by the host"); @@ -3857,8 +3865,9 @@ export class DaemonClient { type: "workspace.archive.undo.request", workspaceId, }, - // Undoing a finished worktree archive recreates the worktree, like recovery does. - timeout: 150_000, + // Undo may wait for an in-flight archive to settle and then recreate the worktree; + // wait for the terminal response or transport disconnect. + timeout: 0, }); if (!payload.accepted) { throw new Error(payload.error ?? "The host could not undo the workspace archive"); @@ -5439,6 +5448,9 @@ export class DaemonClient { ...(input.scope !== undefined ? { scope: input.scope } : {}), }, responseType: "paseo_worktree_archive_response", + // Archive may wait for a queued checkout operation and then run teardown/manager removal, + // each bounded on the daemon; wait for the terminal response or transport disconnect. + timeout: 0, }); } @@ -5462,6 +5474,10 @@ export class DaemonClient { ...(input.githubPrNumber !== undefined ? { githubPrNumber: input.githubPrNumber } : {}), }, responseType: "create_paseo_worktree_response", + // Every daemon stage (before hooks, shared 120s manager budget, Git, after hooks) enforces + // its own deadline, and transport heartbeats/close reject if the host drops, so wait for the + // terminal worktree response instead of aborting prematurely mid-workflow. + timeout: 0, }); } diff --git a/packages/plugin/src/boundaries.test.ts b/packages/plugin/src/boundaries.test.ts index 8b8cae6630..eff1af756a 100644 --- a/packages/plugin/src/boundaries.test.ts +++ b/packages/plugin/src/boundaries.test.ts @@ -589,3 +589,75 @@ describe("sidebar data SDK boundary", () => { ).toEqual([]); }); }); + +describe("worktree manager SDK boundary", () => { + it("types create, remove, and restore handlers with discriminated results and cleanup", () => { + expect( + typeErrors(` + import type { + PluginServerContext, + WorktreeManagerRegistration, + PluginWorktreeCreateInput, + PluginWorktreeCreateResult, + PluginWorktreeRemoveRequest, + PluginWorktreeRemoveResult, + PluginWorktreeRestoreRequest, + PluginWorktreeRestoreResult, + } from "@getpaseo/plugin/server"; + + export default function contribute(server: PluginServerContext) { + const manager: WorktreeManagerRegistration = { + async create(request: PluginWorktreeCreateInput, { paseo, signal }) { + const untrusted: boolean = request.untrusted; + const headSha: string | undefined = request.headSha; + void headSha; + // @ts-expect-error untrusted is read-only + request.untrusted = true; + // @ts-expect-error headSha is read-only + request.headSha = "deadbeef"; + if (request.kind === "branch-off") { + const start: string = request.startPoint ?? request.baseRef; + // @ts-expect-error startPoint is read-only + request.startPoint = "other"; + if (!start || untrusted) return; + } + if (signal.aborted) return; + void paseo; + const result: PluginWorktreeCreateResult = { type: "created", path: request.path }; + return result; + }, + async remove(request: PluginWorktreeRemoveRequest, { signal }) { + const reason: "archive" | "rollback" = request.reason; + const force: boolean = request.force; + const untrusted: boolean = request.untrusted; + // @ts-expect-error remove request fields are read-only + request.path = "/other"; + if (!reason || !force || untrusted || signal.aborted) return; + const result: PluginWorktreeRemoveResult = { type: "removed" }; + return result; + }, + async restore(request: PluginWorktreeRestoreRequest) { + const untrusted: boolean = request.untrusted; + void untrusted; + if (request.target.type === "commit") return; + if (request.target.type === "from-base") { + const base: string = request.target.baseRef; + void base; + } + const result: PluginWorktreeRestoreResult = { type: "restored", path: request.path }; + return result; + }, + }; + const dispose: () => void = server.registerWorktreeManager(manager); + server.registerWorktreeManager({ + // @ts-expect-error create result requires discriminant + async create() { + return { path: "/tmp/wt" }; + }, + }); + return dispose; + } + `), + ).toEqual([]); + }); +}); diff --git a/packages/plugin/src/server/contracts.ts b/packages/plugin/src/server/contracts.ts index 45b283743d..8c46d3a14a 100644 --- a/packages/plugin/src/server/contracts.ts +++ b/packages/plugin/src/server/contracts.ts @@ -5,6 +5,7 @@ import type { PluginCleanup } from "../contracts.js"; import type { ProviderRegistration } from "./provider.js"; import type { UsageSourceRegistration } from "./usage.js"; import type { PluginLifecycleRegistration } from "./lifecycle.js"; +import type { WorktreeManagerRegistration } from "./worktree.js"; export interface PluginHandlerContext { paseo: PaseoApi; @@ -64,6 +65,7 @@ export interface PluginServerContext extends PluginLifecycleRegistration { ): void; registerProvider(provider: ProviderRegistration): void; registerUsageSource(source: UsageSourceRegistration): void; + registerWorktreeManager(manager: WorktreeManagerRegistration): () => void; } export type PluginServerContribution = (server: PluginServerContext) => PluginCleanup; diff --git a/packages/plugin/src/server/index.ts b/packages/plugin/src/server/index.ts index 4ff70ae74d..fe41fac10c 100644 --- a/packages/plugin/src/server/index.ts +++ b/packages/plugin/src/server/index.ts @@ -35,3 +35,14 @@ export { spawnProcess, execCommand, terminateProcess } from "./process.js"; export { defineAgentTool } from "./agent-tools.js"; export type { AgentToolDefinition, AgentToolResult, AgentToolContext } from "./agent-tools.js"; +export type { + PluginWorktreeContext, + PluginWorktreeCreateInput, + PluginWorktreeCreateResult, + PluginWorktreeRemoveRequest, + PluginWorktreeRemoveResult, + PluginWorktreeRestoreTarget, + PluginWorktreeRestoreRequest, + PluginWorktreeRestoreResult, + WorktreeManagerRegistration, +} from "./worktree.js"; diff --git a/packages/plugin/src/server/lifecycle.ts b/packages/plugin/src/server/lifecycle.ts index cedc2e3019..133e718b12 100644 --- a/packages/plugin/src/server/lifecycle.ts +++ b/packages/plugin/src/server/lifecycle.ts @@ -37,7 +37,12 @@ export type PluginWorktreeCreateRequest = { slug: string; path: string; } & ( - | { kind: "branch-off"; baseRef: string } + | { + kind: "branch-off"; + baseRef: string; + /** Where the new branch starts when that is not `baseRef`, such as a fork's head. */ + readonly startPoint?: string; + } | { kind: "checkout-branch" } | { kind: "checkout-change-request"; diff --git a/packages/plugin/src/server/worktree.ts b/packages/plugin/src/server/worktree.ts new file mode 100644 index 0000000000..511f442d36 --- /dev/null +++ b/packages/plugin/src/server/worktree.ts @@ -0,0 +1,69 @@ +import type { PluginHookContext, PluginWorktreeCreateRequest } from "./lifecycle.js"; + +/** Context passed to worktree manager callbacks. */ +export type PluginWorktreeContext = PluginHookContext; + +/** Resolved creation request handed to a worktree manager after `worktree.create.before`. */ +export type PluginWorktreeCreateInput = PluginWorktreeCreateRequest & { + /** True when the worktree comes from an untrusted source such as a fork change request; skip repository-defined hooks. */ + readonly untrusted: boolean; + /** Resolved remote head commit SHA for change-request checkouts when available. */ + readonly headSha?: string; +}; + +/** Return `{ type: "created", path }` to claim creation, or `undefined` to decline. */ +export interface PluginWorktreeCreateResult { + type: "created"; + path: string; +} + +export interface PluginWorktreeRemoveRequest { + readonly repoRoot: string | null; + readonly path: string; + readonly branch: string | null; + readonly reason: "archive" | "rollback"; + readonly force: boolean; + /** True when the worktree came from an untrusted source such as a fork change request; skip repository-defined hooks. */ + readonly untrusted: boolean; +} + +/** Return `{ type: "removed" }` after removing the worktree, or `undefined` to fall back to Git. */ +export interface PluginWorktreeRemoveResult { + type: "removed"; +} + +export type PluginWorktreeRestoreTarget = + | { readonly type: "branch"; readonly branch: string } + | { readonly type: "commit"; readonly commit: string } + | { readonly type: "from-base"; readonly branch: string; readonly baseRef: string }; + +export interface PluginWorktreeRestoreRequest { + readonly repoRoot: string; + /** Recorded path the worktree must be restored to. */ + readonly path: string; + readonly target: PluginWorktreeRestoreTarget; + readonly baseRef: string | null; + /** True when the worktree came from an untrusted source such as a fork change request; skip repository-defined hooks. */ + readonly untrusted: boolean; +} + +/** Return `{ type: "restored", path }` after recreating the worktree, or `undefined` to fall back to Git. */ +export interface PluginWorktreeRestoreResult { + type: "restored"; + path: string; +} + +export interface WorktreeManagerRegistration { + create( + request: PluginWorktreeCreateInput, + context: PluginWorktreeContext, + ): Promise; + remove?( + request: PluginWorktreeRemoveRequest, + context: PluginWorktreeContext, + ): Promise; + restore?( + request: PluginWorktreeRestoreRequest, + context: PluginWorktreeContext, + ): Promise; +} diff --git a/packages/server/package.json b/packages/server/package.json index 15da911f62..2ab683c29f 100644 --- a/packages/server/package.json +++ b/packages/server/package.json @@ -90,7 +90,7 @@ "speech:transcribe:local": "tsx scripts/transcribe-local-wav.ts", "test": "npm run test:unit && npm run test:integration", "test:unit": "vitest run --fileParallelism --exclude \"**/*.e2e.test.ts\"", - "test:integration": "vitest run --maxWorkers=1 src/server/git-filename-diffs.e2e.test.ts src/server/daemon-e2e/checkout-diff-content.e2e.test.ts src/server/daemon-e2e/create-agent-mode.e2e.test.ts src/server/daemon-e2e/filesystem.e2e.test.ts src/server/daemon-e2e/file-download.e2e.test.ts src/server/daemon-e2e/cli-logs-follow.e2e.test.ts src/server/creation/creation.e2e.test.ts src/server/daemon-e2e/creation-status.e2e.test.ts src/server/daemon-e2e/persisted-creation-caller.e2e.test.ts src/server/daemon-e2e/terminal-workspace-sdk.e2e.test.ts src/server/daemon-e2e/terminal-worker-lifecycle.e2e.test.ts src/server/workspace-create-worktree-source.e2e.test.ts src/server/daemon-e2e/models.e2e.test.ts src/server/daemon-e2e/live-preferences.e2e.test.ts src/server/daemon-e2e/oversized-message.e2e.test.ts src/server/agent/model-catalog.e2e.test.ts src/server/plugins/plugin-paseo-api.e2e.test.ts src/server/plugins/usage-sources.e2e.test.ts src/server/plugins/lifecycle.e2e.test.ts src/server/connected-hosts/hosts.e2e.test.ts src/server/owned-subscriptions.e2e.test.ts && vitest run --maxWorkers=1 src/server/agent/providers/omp/history.e2e.test.ts src/server/daemon-e2e/git-operations.e2e.test.ts src/server/session.create-agent-worktree-autoarchive.e2e.test.ts src/server/agent/providers/opencode-bridge.local.e2e.test.ts src/server/daemon-e2e/relay-transport.e2e.test.ts -t \"merges into|creates a worktree and auto-archives both|versioned runtime|oversized attachments|connected hosts|password-protected daemon refuses|replays selected OMP history\"", + "test:integration": "vitest run --maxWorkers=1 src/server/git-filename-diffs.e2e.test.ts src/server/daemon-e2e/checkout-diff-content.e2e.test.ts src/server/daemon-e2e/create-agent-mode.e2e.test.ts src/server/daemon-e2e/filesystem.e2e.test.ts src/server/daemon-e2e/file-download.e2e.test.ts src/server/daemon-e2e/cli-logs-follow.e2e.test.ts src/server/creation/creation.e2e.test.ts src/server/daemon-e2e/creation-status.e2e.test.ts src/server/daemon-e2e/persisted-creation-caller.e2e.test.ts src/server/daemon-e2e/terminal-workspace-sdk.e2e.test.ts src/server/daemon-e2e/terminal-worker-lifecycle.e2e.test.ts src/server/workspace-create-worktree-source.e2e.test.ts src/server/daemon-e2e/models.e2e.test.ts src/server/daemon-e2e/live-preferences.e2e.test.ts src/server/daemon-e2e/oversized-message.e2e.test.ts src/server/agent/model-catalog.e2e.test.ts src/server/plugins/plugin-paseo-api.e2e.test.ts src/server/plugins/usage-sources.e2e.test.ts src/server/plugins/lifecycle.e2e.test.ts src/server/plugins/worktree-manager.e2e.test.ts src/server/connected-hosts/hosts.e2e.test.ts src/server/owned-subscriptions.e2e.test.ts && vitest run --maxWorkers=1 src/server/agent/providers/omp/history.e2e.test.ts src/server/daemon-e2e/git-operations.e2e.test.ts src/server/session.create-agent-worktree-autoarchive.e2e.test.ts src/server/agent/providers/opencode-bridge.local.e2e.test.ts src/server/daemon-e2e/relay-transport.e2e.test.ts -t \"merges into|creates a worktree and auto-archives both|versioned runtime|oversized attachments|connected hosts|password-protected daemon refuses|replays selected OMP history\"", "test:hub-cli-contract": "vitest run --maxWorkers=1 src/server/hub/hub-cli-contract.test.ts", "test:integration:all": "npm run test:e2e", "test:integration:real": "vitest run real.e2e.test.ts", diff --git a/packages/server/src/server/agent/create-agent-lifecycle-dispatch.ts b/packages/server/src/server/agent/create-agent-lifecycle-dispatch.ts index 2cbf71313b..4736dfbf5d 100644 --- a/packages/server/src/server/agent/create-agent-lifecycle-dispatch.ts +++ b/packages/server/src/server/agent/create-agent-lifecycle-dispatch.ts @@ -4,7 +4,11 @@ import type pino from "pino"; import type { ForgeService } from "../../services/forge-service.js"; import { isPaseoOwnedWorktreeCwd } from "../../utils/worktree.js"; -import { archiveByScope, type ActiveWorkspaceRef } from "../workspace-archive-service.js"; +import { + archiveByScope, + type ActiveWorkspaceRef, + type ArchiveDependencies, +} from "../workspace-archive-service.js"; import type { CreatePaseoWorktreeWorkflowFn, CreatePaseoWorktreeWorkflowResult, @@ -17,10 +21,15 @@ import type { } from "../messages.js"; import type { AgentManager, AgentSubscriber, SubscribeOptions } from "./agent-manager.js"; import type { AgentStorage } from "./agent-storage.js"; +import type { PluginWorktreeManagerRuntime } from "../plugins/runtime.js"; interface CreateAgentLifecycleDispatchDependencies { paseoHome: string; worktreesRoot?: string; + worktreeManagers?: Pick; + workspaceArchiveOperations?: ArchiveDependencies["workspaceArchiveOperations"]; + getWorkspace?: ArchiveDependencies["getWorkspace"]; + isCheckoutUntrusted?: ArchiveDependencies["isCheckoutUntrusted"]; agentManager: AgentManager; agentStorage: AgentStorage; github: ForgeService; @@ -184,11 +193,15 @@ export class CreateAgentLifecycleDispatch { { paseoHome: this.dependencies.paseoHome, paseoWorktreesBaseRoot: this.dependencies.worktreesRoot, + worktreeManagers: this.dependencies.worktreeManagers, + workspaceArchiveOperations: this.dependencies.workspaceArchiveOperations, github: this.dependencies.github, workspaceGitService: this.dependencies.workspaceGitService, agentManager: this.dependencies.agentManager, agentStorage: this.dependencies.agentStorage, findWorkspaceIdForCwd: this.dependencies.findWorkspaceIdForCwd, + getWorkspace: this.dependencies.getWorkspace, + isCheckoutUntrusted: this.dependencies.isCheckoutUntrusted, listActiveWorkspaces: this.dependencies.listActiveWorkspaces, archiveWorkspaceRecord: this.dependencies.archiveWorkspaceRecord, emitWorkspaceUpdatesForWorkspaceIds: this.dependencies.emitWorkspaceUpdatesForWorkspaceIds, diff --git a/packages/server/src/server/agent/tools/paseo-tools.ts b/packages/server/src/server/agent/tools/paseo-tools.ts index 06e7ccff9c..7ed87a8451 100644 --- a/packages/server/src/server/agent/tools/paseo-tools.ts +++ b/packages/server/src/server/agent/tools/paseo-tools.ts @@ -139,6 +139,9 @@ export interface PaseoToolHostDependencies { "getSnapshot" | "listWorktrees" | "resolveRepoRoot" | "invalidateWorktrees" >; findWorkspaceIdForCwd?: ArchiveDependencies["findWorkspaceIdForCwd"]; + worktreeManagers?: ArchiveDependencies["worktreeManagers"]; + workspaceArchiveOperations?: ArchiveDependencies["workspaceArchiveOperations"]; + isCheckoutUntrusted?: ArchiveDependencies["isCheckoutUntrusted"]; listActiveWorkspaces?: ArchiveDependencies["listActiveWorkspaces"]; archiveWorkspaceRecord?: ArchiveDependencies["archiveWorkspaceRecord"]; emitWorkspaceUpdatesForWorkspaceIds?: ArchiveDependencies["emitWorkspaceUpdatesForWorkspaceIds"]; @@ -3415,11 +3418,17 @@ function archiveWorktreeDependencies( return { paseoHome: options.paseoHome, paseoWorktreesBaseRoot: options.worktreesRoot, + worktreeManagers: options.worktreeManagers, + workspaceArchiveOperations: options.workspaceArchiveOperations, + isCheckoutUntrusted: options.isCheckoutUntrusted, github: options.github, workspaceGitService: options.workspaceGitService, agentManager: context.agentManager, agentStorage: context.agentStorage, findWorkspaceIdForCwd: options.findWorkspaceIdForCwd, + ...(options.workspaceRegistry + ? { getWorkspace: (workspaceId: string) => options.workspaceRegistry!.get(workspaceId) } + : {}), listActiveWorkspaces: options.listActiveWorkspaces, archiveWorkspaceRecord: options.archiveWorkspaceRecord, emitWorkspaceUpdatesForWorkspaceIds: options.emitWorkspaceUpdatesForWorkspaceIds, diff --git a/packages/server/src/server/auto-archive-on-merge/archive-if-safe.ts b/packages/server/src/server/auto-archive-on-merge/archive-if-safe.ts index 7ea7604b3e..8f0e09fec5 100644 --- a/packages/server/src/server/auto-archive-on-merge/archive-if-safe.ts +++ b/packages/server/src/server/auto-archive-on-merge/archive-if-safe.ts @@ -6,6 +6,7 @@ import type { DaemonConfigStore } from "../daemon-config-store.js"; import { archiveByScope, type ActiveWorkspaceRef, + type ArchiveDependencies, killTerminalsForWorkspace, } from "../workspace-archive-service.js"; import type { @@ -16,10 +17,15 @@ import type { ForgeService } from "../../services/forge-service.js"; import type { TerminalManager } from "../../terminal/terminal-manager.js"; import { isPaseoOwnedWorktreeCwd } from "../../utils/worktree.js"; import type { WorkspaceArchiveContext } from "../workspace-registry.js"; +import type { PluginWorktreeManagerRuntime } from "../plugins/runtime.js"; export interface AutoArchiveArchiveOptions { paseoHome: string; paseoWorktreesBaseRoot?: string; + worktreeManagers?: Pick; + workspaceArchiveOperations?: ArchiveDependencies["workspaceArchiveOperations"]; + getWorkspace?: ArchiveDependencies["getWorkspace"]; + isCheckoutUntrusted?: ArchiveDependencies["isCheckoutUntrusted"]; daemonConfigStore: DaemonConfigStore; workspaceGitService: WorkspaceGitServiceImpl; github: ForgeService; @@ -99,11 +105,15 @@ export async function archiveIfSafe(input: { { paseoHome: options.paseoHome, paseoWorktreesBaseRoot: options.paseoWorktreesBaseRoot, + worktreeManagers: options.worktreeManagers, + workspaceArchiveOperations: options.workspaceArchiveOperations, github: options.github, workspaceGitService: options.workspaceGitService, agentManager: options.agentManager, agentStorage: options.agentStorage, findWorkspaceIdForCwd: options.findWorkspaceIdForCwd, + getWorkspace: options.getWorkspace, + isCheckoutUntrusted: options.isCheckoutUntrusted, listActiveWorkspaces: options.listActiveWorkspaces, archiveWorkspaceRecord: (workspaceIdToArchive, archivedAt) => options.archiveWorkspaceRecord( diff --git a/packages/server/src/server/bootstrap.ts b/packages/server/src/server/bootstrap.ts index d2db7d42a6..4186660911 100644 --- a/packages/server/src/server/bootstrap.ts +++ b/packages/server/src/server/bootstrap.ts @@ -184,6 +184,7 @@ import { killTerminalsForWorkspace, type ActiveWorkspaceRef, } from "./workspace-archive-service.js"; +import { WorkspaceArchiveOperations } from "./workspace-archive-operations.js"; import { setupAutoArchiveOnMerge } from "./auto-archive-on-merge/index.js"; import { wrapSessionMessage, type SessionOutboundMessage } from "./messages.js"; import type { TerminalManager } from "../terminal/terminal-manager.js"; @@ -214,7 +215,10 @@ import { ScriptHealthMonitor } from "./script-health-monitor.js"; import { createScriptStatusEmitter } from "./script-status-projection.js"; import { WorkspaceScriptRuntimeStore } from "./workspace-script-runtime-store.js"; import { createWorkspaceScriptsService } from "./session/workspace-scripts/workspace-scripts-service.js"; -import { assertWorkspaceAutomationAllowedForWorkspace } from "./workspace-automation-gate.js"; +import { + assertWorkspaceAutomationAllowedForWorkspace, + isCheckoutUntrusted, +} from "./workspace-automation-gate.js"; import { spawnWorkspaceScript } from "./worktree-bootstrap.js"; import { createManagedProcessRegistry, @@ -743,6 +747,7 @@ export async function createPaseoDaemon( }); const scriptRuntimeStore = new WorkspaceScriptRuntimeStore(); const workspaceSetupRuntime = new WorkspaceSetupRuntime(); + const workspaceArchiveOperations = new WorkspaceArchiveOperations(); let configuredHostnames = config.hostnames ?? config.allowedHosts; let appBaseUrl = config.appBaseUrl ?? "https://app.paseo.sh"; daemonConfigStore.onFieldChange("hostnames", (value) => { @@ -1166,6 +1171,8 @@ export async function createPaseoDaemon( worktreeRoot: workspace.worktreeRoot, isPaseoOwnedWorktree: workspace.isPaseoOwnedWorktree, mainRepoRoot: workspace.mainRepoRoot, + worktreeManagerPluginId: workspace.worktreeManagerPluginId, + untrustedSource: workspace.untrustedSource, })); }; const markWorkspaceArchivingExternal = (workspaceIds: Iterable, archivingAt: string) => { @@ -1224,6 +1231,8 @@ export async function createPaseoDaemon( setupAutoArchiveOnMerge({ paseoHome: config.paseoHome, paseoWorktreesBaseRoot: config.worktreesRoot, + worktreeManagers: pluginRuntime, + workspaceArchiveOperations, daemonConfigStore, workspaceGitService, github, @@ -1232,6 +1241,8 @@ export async function createPaseoDaemon( terminalManager, logger, findWorkspaceIdForCwd: findWorkspaceIdForCwdExternal, + getWorkspace: (workspaceId) => workspaceRegistry.get(workspaceId), + isCheckoutUntrusted: (checkoutPath) => isCheckoutUntrusted(workspaceRegistry, checkoutPath), listActiveWorkspaces: listActiveWorkspacesExternal, getAutoArchivedChangeRequestUrl: async (workspaceId) => (await workspaceRegistry.get(workspaceId))?.autoArchivedChangeRequestUrl ?? null, @@ -1252,6 +1263,7 @@ export async function createPaseoDaemon( createPaseoWorktree: async (workflowInput, workflowOptions) => { return createRegisteredPaseoWorktree(workflowInput, { lifecycle: pluginRuntime, + worktreeManagers: pluginRuntime, github, ...(workflowOptions?.resolveDefaultBranch ? { @@ -1312,6 +1324,8 @@ export async function createPaseoDaemon( { paseoHome: config.paseoHome, paseoWorktreesBaseRoot: config.worktreesRoot, + worktreeManagers: pluginRuntime, + workspaceArchiveOperations, github, workspaceGitService, agentManager, @@ -1329,6 +1343,7 @@ export async function createPaseoDaemon( stopWorkspaceSetup: (workspaceIdToStop) => workspaceSetupRuntime.stop(workspaceIdToStop), assertWorkspaceAutomationAllowed: (guardedWorkspaceId) => assertWorkspaceAutomationAllowedForWorkspace(workspaceRegistry, guardedWorkspaceId), + isCheckoutUntrusted: (checkoutPath) => isCheckoutUntrusted(workspaceRegistry, checkoutPath), sessionLogger: logger, }, { scope: { kind: "workspace", workspaceId }, requestId }, @@ -1336,6 +1351,10 @@ export async function createPaseoDaemon( const hubAgentLifecycle = new CreateAgentLifecycleDispatch({ paseoHome: config.paseoHome, worktreesRoot: config.worktreesRoot, + worktreeManagers: pluginRuntime, + workspaceArchiveOperations, + getWorkspace: (workspaceId) => workspaceRegistry.get(workspaceId), + isCheckoutUntrusted: (checkoutPath) => isCheckoutUntrusted(workspaceRegistry, checkoutPath), agentManager, agentStorage, github, @@ -1434,6 +1453,8 @@ export async function createPaseoDaemon( { paseoHome: config.paseoHome, paseoWorktreesBaseRoot: config.worktreesRoot, + worktreeManagers: pluginRuntime, + workspaceArchiveOperations, github, workspaceGitService, agentManager, @@ -1457,6 +1478,7 @@ export async function createPaseoDaemon( stopWorkspaceSetup: (workspaceIdToStop) => workspaceSetupRuntime.stop(workspaceIdToStop), assertWorkspaceAutomationAllowed: (guardedWorkspaceId) => assertWorkspaceAutomationAllowedForWorkspace(workspaceRegistry, guardedWorkspaceId), + isCheckoutUntrusted: (checkoutPath) => isCheckoutUntrusted(workspaceRegistry, checkoutPath), sessionLogger: logger, }, { @@ -1583,6 +1605,9 @@ export async function createPaseoDaemon( daemonConfigStore, github, workspaceGitService, + worktreeManagers: pluginRuntime, + workspaceArchiveOperations, + isCheckoutUntrusted: (checkoutPath) => isCheckoutUntrusted(workspaceRegistry, checkoutPath), findWorkspaceIdForCwd: findWorkspaceIdForCwdExternal, listActiveWorkspaces: listActiveWorkspacesExternal, archiveWorkspaceRecord: (workspaceId, archivedAt) => @@ -1930,6 +1955,7 @@ export async function createPaseoDaemon( pluginRuntime, orchestrationSkills, workspaceLabelService, + workspaceArchiveOperations, ); pluginRuntime.bindPaseoSessionHost(wsServer); await pluginRuntime.start(); diff --git a/packages/server/src/server/paseo-worktree-service.ts b/packages/server/src/server/paseo-worktree-service.ts index ff02d3fa8c..9a40e3ffaa 100644 --- a/packages/server/src/server/paseo-worktree-service.ts +++ b/packages/server/src/server/paseo-worktree-service.ts @@ -1,5 +1,6 @@ import type { JsonValue } from "@getpaseo/protocol/agent-types"; import type { PluginLifecycle } from "./plugins/lifecycle/index.js"; +import type { PluginWorktreeManagerRuntime } from "./plugins/runtime.js"; import { stat } from "node:fs/promises"; import { resolve } from "node:path"; @@ -63,6 +64,10 @@ export interface AttemptFirstAgentBranchAutoNameResult { export interface CreatePaseoWorktreeDeps extends CreateWorktreeCoreDeps { lifecycle?: Pick; + worktreeManagers?: Pick< + PluginWorktreeManagerRuntime, + "hasWorktreeManager" | "createWorktree" | "removeWorktree" + >; workspaceGitService: WorkspaceGitService; workspaceProvisioning: Pick; } @@ -114,22 +119,13 @@ async function createPaseoWorktreeWithPriority( worktreeRoot: createdWorktree.worktree.worktreePath, branch: createdWorktree.worktree.branchName || null, baseBranch: createdWorktree.worktree.comparisonBaseRef, + worktreeManagerPluginId: createdWorktree.worktree.worktreeManagerPluginId ?? null, title: input.title?.trim() || resolveFirstAgentPromptTitle(input.firstAgentContext), metadata: input.metadata, expectsInitialAgent: Boolean(input.firstAgentContext), background: input.background, callerWorkspaceId: input.callerWorkspaceId, - ...(createdWorktree.intent.kind === "checkout-change-request" && - createdWorktree.intent.headRepository - ? { - untrustedSource: { - kind: "change_request" as const, - forge: createdWorktree.intent.forge, - number: createdWorktree.intent.changeRequestNumber, - headRepository: createdWorktree.intent.headRepository, - }, - } - : {}), + untrustedSource: createdWorktree.untrustedSource, }); deps.github.invalidate({ cwd: createdWorktree.worktree.worktreePath }); @@ -152,6 +148,10 @@ async function createPaseoWorktreeWithPriority( teardownCwds: [], paseoHome: input.paseoHome, worktreesBaseRoot: input.worktreesRoot, + worktreeManagers: deps.worktreeManagers, + worktreeManagerPluginId: createdWorktree.worktree.worktreeManagerPluginId ?? null, + removeReason: "rollback", + untrusted: Boolean(createdWorktree.untrustedSource), }, error, ); @@ -286,6 +286,10 @@ async function maybeMarkFirstAgentBranchAutoNameEligible(options: { if (!createdWorktree.created || createdWorktree.intent.kind !== "branch-off") { return; } + // A worktree manager plugin owns branch and directory naming, so skip silent renames. + if (createdWorktree.worktree.worktreeManagerPluginId) { + return; + } // A branch the caller named is their choice; only a placeholder slug is replaced. if (input.branchName !== undefined) { return; diff --git a/packages/server/src/server/plugins/index.ts b/packages/server/src/server/plugins/index.ts index 89f09275bf..373e0c29e8 100644 --- a/packages/server/src/server/plugins/index.ts +++ b/packages/server/src/server/plugins/index.ts @@ -24,7 +24,7 @@ import { type ManagedPluginCandidate, ManagedPluginSources } from "./managed-sou import { readPluginManifest } from "./manifest.js"; import { expandTilde } from "../../utils/path.js"; import { runPluginBuild } from "./preparation.js"; -import { PluginRuntime } from "./runtime.js"; +import { PluginRuntime, type PluginWorktreeManagerRuntime } from "./runtime.js"; import type { PluginRuntimeSubscription } from "./runtime-subscription.js"; import { BuiltinPluginLoader, type BuiltinPlugin } from "./builtin/index.js"; import type { @@ -50,6 +50,10 @@ interface PluginRuntimePort { drainEvents?: PluginRuntime["drainEvents"]; before?: PluginLifecycle["before"]; wait?: PluginLifecycle["wait"]; + hasWorktreeManager?: PluginWorktreeManagerRuntime["hasWorktreeManager"]; + createWorktree?: PluginWorktreeManagerRuntime["createWorktree"]; + removeWorktree?: PluginWorktreeManagerRuntime["removeWorktree"]; + restoreWorktree?: PluginWorktreeManagerRuntime["restoreWorktree"]; catalog: PluginRuntime["catalog"]; invoke(pluginId: string, method: string, input: unknown): Promise; startSubscription: PluginRuntime["startSubscription"]; @@ -192,6 +196,31 @@ export class PluginService { return request; }; + readonly hasWorktreeManager: PluginWorktreeManagerRuntime["hasWorktreeManager"] = (options) => { + return this.runtime.hasWorktreeManager?.(options) ?? false; + }; + + readonly createWorktree: PluginWorktreeManagerRuntime["createWorktree"] = async ( + request, + options, + ) => { + return (await this.runtime.createWorktree?.(request, options)) ?? null; + }; + + readonly removeWorktree: PluginWorktreeManagerRuntime["removeWorktree"] = async ( + request, + options, + ) => { + return (await this.runtime.removeWorktree?.(request, options)) ?? null; + }; + + readonly restoreWorktree: PluginWorktreeManagerRuntime["restoreWorktree"] = async ( + request, + options, + ) => { + return (await this.runtime.restoreWorktree?.(request, options)) ?? null; + }; + subscribeSettings(listener: (pluginId: string, settingsId: string) => void): () => void { this.settingsListeners.add(listener); return () => this.settingsListeners.delete(listener); diff --git a/packages/server/src/server/plugins/lifecycle/index.ts b/packages/server/src/server/plugins/lifecycle/index.ts index 46e2a87d66..e9145f3cf5 100644 --- a/packages/server/src/server/plugins/lifecycle/index.ts +++ b/packages/server/src/server/plugins/lifecycle/index.ts @@ -57,7 +57,12 @@ const changeRequestFields = { }; const worktreeRequestSchema = z.discriminatedUnion("kind", [ z - .object({ ...worktreeRequestFields, kind: z.literal("branch-off"), baseRef: z.string().min(1) }) + .object({ + ...worktreeRequestFields, + kind: z.literal("branch-off"), + baseRef: z.string().min(1), + startPoint: z.string().min(1).optional(), + }) .strict(), z .object({ @@ -239,6 +244,28 @@ function changesSessionOpenTarget(previous: SessionOpenRequest, next: SessionOpe ); } +type WorktreeBeforeRequest = z.infer<(typeof beforeSchemas)["worktree.create.before"]>; + +function validateWorktreeBeforeResult( + previous: WorktreeBeforeRequest, + next: WorktreeBeforeRequest, +): WorktreeBeforeRequest { + if (previous.repoRoot !== next.repoRoot || previous.sourceCheckout !== next.sourceCheckout) { + throw new Error("worktree.create.before hooks cannot change repoRoot or sourceCheckout"); + } + if (previous.kind === "branch-off" && next.kind === "branch-off") { + if (next.startPoint !== undefined && next.startPoint !== previous.startPoint) { + throw new Error("worktree.create.before hooks cannot change startPoint"); + } + if (next.startPoint === undefined && previous.startPoint !== undefined) { + return { ...next, startPoint: previous.startPoint }; + } + } else if (next.kind === "branch-off" && next.startPoint !== undefined) { + throw new Error("worktree.create.before hooks cannot change startPoint"); + } + return next; +} + export async function validateBeforeResult( name: Name, input: PluginWireBeforeRequests[Name], @@ -280,9 +307,7 @@ export async function validateBeforeResult = z.dis }) .strict(), z.object({ type: z.literal("hook.cancel"), requestId: z.string() }).strict(), + z + .object({ + type: z.enum(["worktree.create", "worktree.remove", "worktree.restore"]), + requestId: z.string().min(1), + request: z.unknown(), + }) + .strict(), + z.object({ type: z.literal("worktree.cancel"), requestId: z.string().min(1) }).strict(), z .object({ type: z.literal("usage.fetch"), @@ -356,6 +384,12 @@ export const PluginProcessMessageSchema: z.ZodType = z.dis [ z.object({ type: z.literal("settings.changed"), settingsId: z.string() }).strict(), z.object({ type: z.literal("hooks.changed"), hooks: hooksSchema }).strict(), + z + .object({ + type: z.literal("worktree_manager.changed"), + worktreeManager: worktreeManagerCapabilitiesSchema.nullable(), + }) + .strict(), z .object({ type: z.literal("ready"), @@ -364,6 +398,7 @@ export const PluginProcessMessageSchema: z.ZodType = z.dis providers: z.array(providerMetadataSchema), usageSources: z.array(usageSourceMetadataSchema).optional(), hooks: hooksSchema.optional(), + worktreeManager: worktreeManagerCapabilitiesSchema.nullable().optional(), }) .strict(), z diff --git a/packages/server/src/server/plugins/plugin-process.ts b/packages/server/src/server/plugins/plugin-process.ts index d95078d23b..17d7ff40ba 100644 --- a/packages/server/src/server/plugins/plugin-process.ts +++ b/packages/server/src/server/plugins/plugin-process.ts @@ -16,6 +16,10 @@ import type { PluginHandlerContext, PluginServerContext, PluginServerContribution, + PluginWorktreeCreateInput, + PluginWorktreeRemoveRequest, + PluginWorktreeRestoreRequest, + WorktreeManagerRegistration, } from "@getpaseo/plugin/server"; import { assertPluginWireValue } from "@getpaseo/protocol/binary-frames/index"; import { @@ -115,6 +119,8 @@ export function createPluginWorker(options: { const subscriptions = new PluginSubscriptionHandlers({ send, sendAndWait }); const providers = new Map(); const usageSources = new Map(); + let worktreeManager: WorktreeManagerRegistration | null = null; + const worktreeRequests = new Map(); const providerConnections = new Map< string, { connection: ProviderConnection; unsubscribe: () => void; closing?: Promise } @@ -228,6 +234,36 @@ export function createPluginWorker(options: { usageSources.set(id, { ...source, id }); } + function worktreeManagerCapabilities() { + if (!worktreeManager) return null; + return { + hasRemove: worktreeManager.remove !== undefined, + hasRestore: worktreeManager.restore !== undefined, + }; + } + + function registerWorktreeManager(manager: WorktreeManagerRegistration): () => void { + if (!manager || typeof manager.create !== "function") { + throw new Error("Plugin worktree manager must implement create()"); + } + if (manager.remove !== undefined && typeof manager.remove !== "function") { + throw new Error("Invalid remove callback for plugin worktree manager"); + } + if (manager.restore !== undefined && typeof manager.restore !== "function") { + throw new Error("Invalid restore callback for plugin worktree manager"); + } + if (worktreeManager !== null) { + throw new Error("Plugin already registered a worktree manager"); + } + worktreeManager = manager; + send({ type: "worktree_manager.changed", worktreeManager: worktreeManagerCapabilities() }); + return () => { + if (worktreeManager !== manager) return; + worktreeManager = null; + send({ type: "worktree_manager.changed", worktreeManager: null }); + }; + } + function providerMetadata(provider: ProviderRegistration) { return { id: provider.id, @@ -433,6 +469,7 @@ export function createPluginWorker(options: { handle, registerProvider, registerUsageSource, + registerWorktreeManager, registerSettings, addHook: hooks.addHook, on: hooks.on, @@ -459,6 +496,7 @@ export function createPluginWorker(options: { methods: [...handlers.keys()].sort(), subscriptions: subscriptions.catalog(), hooks: hooks.catalog(), + worktreeManager: worktreeManagerCapabilities(), providers: [...providers.values()] .sort((left, right) => left.id.localeCompare(right.id)) .map(providerMetadata), @@ -478,6 +516,8 @@ export function createPluginWorker(options: { for (const pending of pendingProviderConnections.values()) pending.tombstoned = true; for (const request of installationRequests.values()) request.abort(new Error("Plugin is stopping")); + for (const request of worktreeRequests.values()) request.abort(new Error("Plugin is stopping")); + worktreeManager = null; const currentCleanup = cleanup; cleanup = null; try { @@ -519,6 +559,9 @@ export function createPluginWorker(options: { message.type === "provider.catalog_key" || message.type === "usage.fetch" || message.type === "usage.discover" || + message.type === "worktree.create" || + message.type === "worktree.remove" || + message.type === "worktree.restore" || message.type === "subscribe" ) { send({ type: "error", requestId: message.requestId, error: "Plugin is stopping" }); @@ -704,6 +747,10 @@ export function createPluginWorker(options: { handleHookMessage(message); return; } + if (isWorktreeMessage(message)) { + handleWorktreeMessage(message); + return; + } if (message.type === "invoke") invoke(message); else handleSubscriptionMessage(message); } @@ -769,6 +816,88 @@ export function createPluginWorker(options: { ): message is Extract { return message.type === "hook" || message.type === "hook.cancel"; } + + function isWorktreeMessage( + message: PluginProcessRequest, + ): message is Extract< + PluginProcessRequest, + { type: "worktree.create" | "worktree.remove" | "worktree.restore" | "worktree.cancel" } + > { + return ( + message.type === "worktree.create" || + message.type === "worktree.remove" || + message.type === "worktree.restore" || + message.type === "worktree.cancel" + ); + } + + function handleWorktreeMessage( + message: Extract< + PluginProcessRequest, + { type: "worktree.create" | "worktree.remove" | "worktree.restore" | "worktree.cancel" } + >, + ): void { + if (message.type === "worktree.cancel") { + worktreeRequests.get(message.requestId)?.abort(new Error("Worktree request canceled")); + return; + } + if (!paseo) { + send({ + type: "error", + requestId: message.requestId, + error: "Plugin Paseo API is unavailable", + }); + return; + } + const manager = worktreeManager; + if (!manager) { + send({ + type: "error", + requestId: message.requestId, + error: "Plugin has no registered worktree manager", + }); + return; + } + const controller = new AbortController(); + worktreeRequests.set(message.requestId, controller); + const context = { paseo, signal: controller.signal }; + void (async () => { + if (message.type === "worktree.create") { + return ( + (await manager.create( + structuredClone(message.request) as PluginWorktreeCreateInput, + context, + )) ?? null + ); + } + if (message.type === "worktree.remove") { + if (!manager.remove) { + throw new Error("Plugin worktree manager does not implement remove"); + } + return ( + (await manager.remove( + structuredClone(message.request) as PluginWorktreeRemoveRequest, + context, + )) ?? null + ); + } + if (!manager.restore) { + throw new Error("Plugin worktree manager does not implement restore"); + } + return ( + (await manager.restore( + structuredClone(message.request) as PluginWorktreeRestoreRequest, + context, + )) ?? null + ); + })() + .then( + (output) => send({ type: "result", requestId: message.requestId, output }), + (error) => + send({ type: "error", requestId: message.requestId, error: describeError(error) }), + ) + .finally(() => worktreeRequests.delete(message.requestId)); + } return { shutdown }; } diff --git a/packages/server/src/server/plugins/runtime.posix.test.ts b/packages/server/src/server/plugins/runtime.posix.test.ts index ccaf00a332..7c69e2a950 100644 --- a/packages/server/src/server/plugins/runtime.posix.test.ts +++ b/packages/server/src/server/plugins/runtime.posix.test.ts @@ -257,6 +257,59 @@ afterEach(async () => { }); describe("PluginRuntime", () => { + it("reports a spent create budget without blaming a manager it did not call", async () => { + const first = await createPlugin( + "first-manager", + `import { existsSync, writeFileSync } from "node:fs"; +import path from "node:path"; + +export default function contribute(server) { + return server.registerWorktreeManager({ + async create({ path: directory }, { signal }) { + writeFileSync(path.join(directory, "started"), ""); + while (!existsSync(path.join(directory, "decline"))) { + signal.throwIfAborted(); + await new Promise((resolve) => setTimeout(resolve, 20)); + } + }, + }); +}`, + ); + const second = await createPlugin( + "second-manager", + `export default function contribute(server) { + return server.registerWorktreeManager({ + async create() { throw new Error("Second manager was called"); }, + }); +}`, + ); + const runtime = createTestRuntime(); + try { + await runtime.startPlugin("first-manager", first); + await runtime.startPlugin("second-manager", second); + // Advance the deadline clock while real subprocess IPC and timers keep running. + vi.useFakeTimers({ toFake: ["Date"] }); + const creation = runtime.createWorktree({ + kind: "branch-off", + repoRoot: first, + sourceCheckout: first, + branch: "topic", + slug: "topic", + path: first, + baseRef: "main", + untrusted: false, + }); + const failure = creation.catch((error: unknown) => error); + await expect.poll(() => readTextIfPresent(path.join(first, "started"))).toBe(""); + vi.setSystemTime(Date.now() + 120_000); + await writeFile(path.join(first, "decline"), ""); + expect(await failure).toMatchObject({ message: "Worktree creation manager budget expired" }); + } finally { + vi.useRealTimers(); + await runtime.stopAll(); + } + }); + it.each([ { specifier: "@getpaseo/plugin", moduleDirectory: "shared" }, { specifier: "@getpaseo/plugin", moduleDirectory: "server" }, diff --git a/packages/server/src/server/plugins/runtime.ts b/packages/server/src/server/plugins/runtime.ts index d4adb5a374..49dc6a5e4f 100644 --- a/packages/server/src/server/plugins/runtime.ts +++ b/packages/server/src/server/plugins/runtime.ts @@ -18,7 +18,15 @@ import { type ProviderStatus, type ProviderStatusRequest, } from "@getpaseo/plugin/server/provider"; -import type { PluginHookEvents, PluginHookAgent, AgentToolResult } from "@getpaseo/plugin/server"; +import type { + PluginHookEvents, + PluginHookAgent, + AgentToolResult, + PluginWorktreeCreateInput, + PluginWorktreeRemoveRequest, + PluginWorktreeRestoreRequest, +} from "@getpaseo/plugin/server"; +import { z } from "zod"; import { validateBeforeRequest, validateBeforeResult } from "./lifecycle/index.js"; import { fork } from "node:child_process"; import path from "node:path"; @@ -42,6 +50,7 @@ import type { PluginProcessRequest, PluginProviderMetadata, PluginUsageSourceMetadata, + PluginWorktreeManagerCapabilities, } from "./plugin-process-protocol.js"; import { PluginProcessMessageSchema } from "./plugin-process-protocol.js"; import { @@ -53,7 +62,40 @@ import { InternalPluginChild } from "./internal-child.js"; import { evaluateBundle } from "./bundle-evaluator.js"; const REQUEST_TIMEOUT_MS = 30_000; +const WORKTREE_MANAGER_TIMEOUT_MS = 120_000; const TOOL_CALL_TIMEOUT_MS = 10 * 60_000; + +const worktreeCreateResultSchema = z + .object({ type: z.literal("created"), path: z.string().min(1) }) + .strict() + .nullable(); +const worktreeRemoveResultSchema = z + .object({ type: z.literal("removed") }) + .strict() + .nullable(); +const worktreeRestoreResultSchema = z + .object({ type: z.literal("restored"), path: z.string().min(1) }) + .strict() + .nullable(); + +export interface PluginWorktreeManagerRuntime { + hasWorktreeManager(options?: { + operation?: "create" | "remove" | "restore"; + preferredPluginId?: string; + }): boolean; + createWorktree( + request: PluginWorktreeCreateInput, + options?: { signal?: AbortSignal }, + ): Promise<{ pluginId: string; path: string } | null>; + removeWorktree( + request: PluginWorktreeRemoveRequest, + options?: { preferredPluginId?: string; signal?: AbortSignal }, + ): Promise<{ pluginId: string } | null>; + restoreWorktree( + request: PluginWorktreeRestoreRequest, + options?: { preferredPluginId?: string; signal?: AbortSignal }, + ): Promise<{ pluginId: string; path: string } | null>; +} const MAX_LOG_ENTRIES = 500; const MAX_LOG_BYTES = 256 * 1024; const MAX_LOG_LINE_BYTES = 16 * 1024; @@ -87,6 +129,8 @@ interface PluginRequestOptions { signal?: AbortSignal; /** Receives `provider.installation.report` messages for the request. */ report?: (report: ProviderUpdateReport) => void; + /** Overrides the default per-message timeout (e.g. shared budget across serial worktree managers). */ + timeoutMs?: number; } interface LoadedPlugin { @@ -100,6 +144,7 @@ interface LoadedPlugin { subscriptionMethods: ReadonlySet; subscriptions: Map; hooks: string[]; + worktreeManager: PluginWorktreeManagerCapabilities | null; providers: readonly PluginProviderMetadata[]; usageSources: readonly PluginUsageSourceMetadata[]; child: PluginChild | null; @@ -293,8 +338,17 @@ function isInstallationRequest(message: PluginProcessRequest): boolean { ); } +function isWorktreeManagerRequest(message: PluginProcessRequest): boolean { + return ( + message.type === "worktree.create" || + message.type === "worktree.remove" || + message.type === "worktree.restore" + ); +} + function requestTimeoutMs(message: PluginProcessRequest): number | null { if (message.type === "tool.call") return TOOL_CALL_TIMEOUT_MS; + if (isWorktreeManagerRequest(message)) return WORKTREE_MANAGER_TIMEOUT_MS; // An updater runs as long as it needs; daemon shutdown aborts it. if (message.type === "provider.installation.update") return null; return REQUEST_TIMEOUT_MS; @@ -752,6 +806,109 @@ export class PluginRuntime { return request; } + hasWorktreeManager(options?: { + operation?: "create" | "remove" | "restore"; + preferredPluginId?: string; + }): boolean { + const operation = options?.operation ?? "create"; + const supports = (manager: PluginWorktreeManagerCapabilities | null): boolean => { + if (!manager) return false; + if (operation === "remove") return manager.hasRemove; + if (operation === "restore") return manager.hasRestore; + return true; + }; + if (options?.preferredPluginId) { + return supports(this.plugins.get(options.preferredPluginId)?.worktreeManager ?? null); + } + for (const loaded of this.plugins.values()) { + if (supports(loaded.worktreeManager)) return true; + } + return false; + } + + async createWorktree( + request: PluginWorktreeCreateInput, + options?: { signal?: AbortSignal }, + ): Promise<{ pluginId: string; path: string } | null> { + const plugins = [...this.plugins.values()] + .filter((plugin) => plugin.worktreeManager !== null) + .sort((left, right) => left.id.localeCompare(right.id)); + // All create callbacks share one timeout budget. + const deadline = Date.now() + WORKTREE_MANAGER_TIMEOUT_MS; + for (const loaded of plugins) { + const remainingMs = deadline - Date.now(); + if (remainingMs <= 0) { + throw new Error("Worktree creation manager budget expired"); + } + try { + const raw = await this.request( + loaded, + { type: "worktree.create", requestId: randomUUID(), request }, + { signal: options?.signal, timeoutMs: remainingMs }, + ); + const parsed = worktreeCreateResultSchema.parse(raw ?? null); + if (parsed !== null) { + return { pluginId: loaded.id, path: parsed.path }; + } + } catch (error) { + throw new Error(`Plugin ${loaded.id} worktree.create failed: ${describeError(error)}`, { + cause: error, + }); + } + } + return null; + } + + async removeWorktree( + request: PluginWorktreeRemoveRequest, + options?: { preferredPluginId?: string; signal?: AbortSignal }, + ): Promise<{ pluginId: string } | null> { + if (!options?.preferredPluginId) return null; + const loaded = this.plugins.get(options.preferredPluginId); + if (!loaded?.worktreeManager?.hasRemove) return null; + try { + const raw = await this.request( + loaded, + { type: "worktree.remove", requestId: randomUUID(), request }, + { signal: options.signal }, + ); + const parsed = worktreeRemoveResultSchema.parse(raw ?? null); + if (parsed !== null) { + return { pluginId: loaded.id }; + } + return null; + } catch (error) { + throw new Error(`Plugin ${loaded.id} worktree.remove failed: ${describeError(error)}`, { + cause: error, + }); + } + } + + async restoreWorktree( + request: PluginWorktreeRestoreRequest, + options?: { preferredPluginId?: string; signal?: AbortSignal }, + ): Promise<{ pluginId: string; path: string } | null> { + if (!options?.preferredPluginId) return null; + const loaded = this.plugins.get(options.preferredPluginId); + if (!loaded?.worktreeManager?.hasRestore) return null; + try { + const raw = await this.request( + loaded, + { type: "worktree.restore", requestId: randomUUID(), request }, + { signal: options.signal }, + ); + const parsed = worktreeRestoreResultSchema.parse(raw ?? null); + if (parsed !== null) { + return { pluginId: loaded.id, path: parsed.path }; + } + return null; + } catch (error) { + throw new Error(`Plugin ${loaded.id} worktree.restore failed: ${describeError(error)}`, { + cause: error, + }); + } + } + async getProviderCatalogCacheKey( pluginId: string, providerId: string, @@ -853,12 +1010,14 @@ export class PluginRuntime { loaded.pending.delete(requestId); if (message.type === "tool.call") void send(child, { type: "tool.cancel", requestId }).catch(() => {}); + if (isWorktreeManagerRequest(message)) + void send(child, { type: "worktree.cancel", requestId }).catch(() => {}); if (isInstallationRequest(message)) void send(child, { type: "provider.installation.cancel", requestId }).catch(() => {}); signal?.removeEventListener("abort", cancel); - reject(signal?.reason ?? new Error("Tool call canceled")); + reject(signal?.reason ?? new Error("Plugin request canceled")); }; - const timeoutMs = requestTimeoutMs(message); + const timeoutMs = options.timeoutMs ?? requestTimeoutMs(message); const timeout = timeoutMs === null ? undefined @@ -870,6 +1029,9 @@ export class PluginRuntime { if (message.type === "hook") { void send(child, { type: "hook.cancel", requestId }).catch(() => {}); } + if (isWorktreeManagerRequest(message)) { + void send(child, { type: "worktree.cancel", requestId }).catch(() => {}); + } // The handler may still start after the daemon gave up on it. if (message.type === "subscribe") { const { subscriptionId } = message; @@ -935,6 +1097,7 @@ export class PluginRuntime { subscriptionMethods: new Set(), subscriptions: new Map(), hooks: [], + worktreeManager: null, providers: [], usageSources: [], child: null, @@ -1067,6 +1230,7 @@ export class PluginRuntime { subscriptionMethods: new Set(ready.subscriptions ?? []), subscriptions: new Map(), hooks: ready.hooks ?? [], + worktreeManager: ready.worktreeManager ?? null, providers: ready.providers ?? [], usageSources: ready.usageSources ?? [], child, @@ -1156,6 +1320,10 @@ export class PluginRuntime { } return; } + if (message.type === "worktree_manager.changed") { + loaded.worktreeManager = message.worktreeManager; + return; + } if (message.type === "settings.changed") { this.dependencies.onSettingsChanged?.(loaded.id, message.settingsId); return; diff --git a/packages/server/src/server/plugins/worktree-manager.e2e.test.ts b/packages/server/src/server/plugins/worktree-manager.e2e.test.ts new file mode 100644 index 0000000000..82f18bb3ac --- /dev/null +++ b/packages/server/src/server/plugins/worktree-manager.e2e.test.ts @@ -0,0 +1,1587 @@ +import { execFileSync } from "node:child_process"; +import { chmod, mkdir, mkdtemp, readFile, realpath, rm, stat, writeFile } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import path from "node:path"; +import { fileURLToPath } from "node:url"; +import { expect, test } from "vitest"; +import { DaemonClient } from "../test-utils/daemon-client.js"; +import { createTestPaseoDaemon } from "../test-utils/paseo-daemon.js"; +import { readPaseoWorktreeMetadata } from "../../utils/worktree-metadata.js"; + +const REPO_ROOT = path.resolve(fileURLToPath(new URL("../../../../..", import.meta.url))); +const WORKTRUNK_EXAMPLE = path.join(REPO_ROOT, "plugin-examples", "worktrunk"); + +function git(cwd: string, args: string[]): string { + return execFileSync( + "git", + [ + "-c", + "user.name=Test", + "-c", + "user.email=test@example.com", + "-c", + "commit.gpgsign=false", + ...args, + ], + { cwd, encoding: "utf8", stdio: "pipe" }, + ).trim(); +} + +async function createRepo(dir: string): Promise { + await mkdir(dir, { recursive: true }); + git(dir, ["init", "-b", "main"]); + await writeFile(path.join(dir, "README.md"), "hello\n"); + git(dir, ["add", "README.md"]); + git(dir, ["commit", "-m", "initial"]); + return realpath(dir); +} + +async function createFakeWorktrunkCli(dir: string, logFile: string): Promise { + const scriptPath = path.join(dir, "fake-wt.mjs"); + await writeFile( + scriptPath, + `#!/usr/bin/env node +import { execFileSync } from "node:child_process"; +import { appendFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs"; +import path from "node:path"; + +const rawArgs = process.argv.slice(2); +let cwd = process.cwd(); +const args = []; +for (let index = 0; index < rawArgs.length; index++) { + if (rawArgs[index] === "-C" && rawArgs[index + 1]) { + cwd = path.resolve(rawArgs[++index]); + } else { + args.push(rawArgs[index]); + } +} + +const command = args[0]; +if (command === "switch") { + const create = args.includes("--create"); + const baseIdx = args.indexOf("--base"); + const base = baseIdx !== -1 ? args[baseIdx + 1] : undefined; + const pathIdx = args.indexOf("--path"); + const explicitPath = pathIdx !== -1 ? args[pathIdx + 1] : undefined; + const skip = new Set(["switch", "--create", "--no-cd", "--yes", "--no-hooks", "--format=json"]); + if (baseIdx !== -1) { + skip.add("--base"); + skip.add(base); + } + if (pathIdx !== -1) { + skip.add("--path"); + skip.add(explicitPath); + } + const branch = args.find((arg) => !skip.has(arg)); + if (!branch) { + console.error("missing branch"); + process.exit(1); + } + if (!create && !explicitPath && branch === "main") { + appendFileSync( + ${JSON.stringify(logFile)}, + JSON.stringify({ command: "switch", cwd, branch, action: "existing", args }) + "\\n", + ); + process.stdout.write(JSON.stringify({ path: cwd, branch, action: "existing" }) + "\\n"); + process.exit(0); + } + const repoName = path.basename(cwd); + const target = + explicitPath ?? path.join(path.dirname(cwd), \`\${repoName}.\${branch.replaceAll("/", "-")}\`); + mkdirSync(path.dirname(target), { recursive: true }); + const gitArgs = create + ? ["worktree", "add", "-b", branch, target, ...(base ? [base] : [])] + : ["worktree", "add", target, branch]; + execFileSync("git", gitArgs, { cwd, stdio: "pipe" }); + writeFileSync(path.join(target, ".wt-hook-ran"), create ? "pre-start" : "reopen"); + appendFileSync( + ${JSON.stringify(logFile)}, + JSON.stringify({ command: "switch", cwd, branch, base, create, explicitPath, target, args }) + "\\n", + ); + process.stdout.write(JSON.stringify({ path: target, branch, action: "created", created_branch: create }) + "\\n"); + if (branch.endsWith("fail-pre-start") && !existsSync(path.join(cwd, ".setup-fixed"))) { + console.error("pre-start hook failed"); + process.exit(1); + } + process.exit(0); +} + +if (command === "remove") { + const target = path.resolve(args.at(-1)); + const keptRefs = execFileSync("git", ["for-each-ref", "--format=%(refname)", "refs/paseo/kept-commits"], { + cwd, + encoding: "utf8", + stdio: "pipe", + }) + .trim() + .split("\\n") + .filter(Boolean); + appendFileSync( + ${JSON.stringify(logFile)}, + JSON.stringify({ command: "remove", cwd, target, args, keptRefsCount: keptRefs.length }) + "\\n", + ); + execFileSync("git", ["worktree", "remove", target, "--force"], { cwd, stdio: "pipe" }); + process.exit(0); +} + +if (command === "config" && args[1] === "state" && args[2] === "marker") { + appendFileSync( + ${JSON.stringify(logFile)}, + JSON.stringify({ command: "marker", cwd, args: args.slice(3) }) + "\\n", + ); + process.exit(0); +} + +console.error("unexpected wt command: " + rawArgs.join(" ")); +process.exit(1); +`, + ); + if (process.platform === "win32") { + const cmdPath = path.join(dir, "fake-wt.cmd"); + await writeFile(cmdPath, `@node "${scriptPath}" %*\r\n`); + return cmdPath; + } + await chmod(scriptPath, 0o755); + return scriptPath; +} + +test("plugin-examples/worktrunk manages create, before-hook chaining, archive with kept-commits, and restore across daemon restarts", async () => { + const root = await mkdtemp(path.join(tmpdir(), "paseo-worktrunk-example-")); + const repository = await createRepo(path.join(root, "repo")); + git(repository, ["branch", "release"]); + const wtLog = path.join(root, "wt-log.jsonl"); + const fakeWt = await createFakeWorktrunkCli(root, wtLog); + const previousBin = process.env.WORKTRUNK_BIN; + process.env.WORKTRUNK_BIN = fakeWt; + + const transformPluginDir = path.join(root, "a-branch-transform"); + await mkdir(transformPluginDir); + await writeFile( + path.join(transformPluginDir, "paseo-plugin.json"), + JSON.stringify({ id: "a-branch-transform", requirements: { paseo: ">=0.14.0" } }), + ); + await writeFile( + path.join(transformPluginDir, "index.server.ts"), + `import { existsSync } from "node:fs"; +import path from "node:path"; +export default function contribute(server) { + const removeBefore = server.addHook("worktree.create.before", async ({ request }) => { + if (request.kind !== "branch-off") return; + return { ...request, branch: "team/" + request.branch, baseRef: "release" }; + }); + const removeAfter = server.addHook("worktree.create.after", async ({ worktree }) => { + if (worktree.branch === "team/fail-after" && !existsSync(path.join(worktree.sourceCheckout, ".after-fixed"))) { + throw new Error("Paseo after-hook failed"); + } + }); + return () => { + removeBefore(); + removeAfter(); + }; +} +`, + ); + + let daemon = await createTestPaseoDaemon({ + paseoHomeRoot: path.join(root, "state"), + cleanup: false, + }); + let client = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws` }); + try { + await client.connect(); + await client.patchDaemonConfig({ pluginsEnabled: true }); + expect((await client.installDirectoryPlugin(transformPluginDir)).status).toBe("running"); + expect((await client.installDirectoryPlugin(WORKTRUNK_EXAMPLE)).status).toBe("running"); + + const created = await client.createWorkspace({ + source: { kind: "worktree", cwd: repository, worktreeSlug: "feat-one" }, + }); + expect(created.error).toBeNull(); + const workspaceId = created.workspace!.id; + const worktreePath = created.workspace!.workspaceDirectory; + const expectedPath = path.join(path.dirname(repository), "repo.team-feat-one"); + expect(await realpath(worktreePath)).toBe(await realpath(expectedPath)); + expect(git(worktreePath, ["branch", "--show-current"])).toBe("team/feat-one"); + expect(await readFile(path.join(worktreePath, ".wt-hook-ran"), "utf8")).toBe("pre-start"); + + const metadata = await readPaseoWorktreeMetadata(worktreePath); + expect(metadata).toMatchObject({ + baseRefName: "release", + baseRef: "refs/heads/release", + worktreeManagerPluginId: "worktrunk", + changeRequestLookupTarget: { + headRef: "team/feat-one", + localBranchName: "team/feat-one", + }, + }); + // Worktree manager plugins own branch/directory naming, so auto-rename must stay skipped. + expect( + metadata && "firstAgentBranchAutoName" in metadata + ? metadata.firstAgentBranchAutoName + : undefined, + ).toBeUndefined(); + + // Checking out a branch already checked out in the main repo causes wt to return + // action="existing", so the example declines and Paseo falls back to Git. + const checkedOutMain = await client.createWorkspace({ + source: { kind: "worktree", cwd: repository, action: "checkout", refName: "main" }, + }); + expect(checkedOutMain.error).toBeNull(); + expect( + (await readPaseoWorktreeMetadata(checkedOutMain.workspace!.workspaceDirectory)) + ?.worktreeManagerPluginId, + ).toBeUndefined(); + await client.archiveWorkspace(checkedOutMain.workspace!.id); + + // If wt exits non-zero after creating the worktree (e.g. pre-start hook failure), + // the example cleans up the partial worktree from stdout before rethrowing. + const failedPreStart = await client.createWorkspace({ + source: { kind: "worktree", cwd: repository, worktreeSlug: "fail-pre-start" }, + }); + expect(failedPreStart.workspace).toBeNull(); + expect(failedPreStart.error).toContain("pre-start hook failed"); + await expect( + stat(path.join(path.dirname(repository), "repo.team-fail-pre-start")), + ).rejects.toMatchObject({ code: "ENOENT" }); + + await writeFile(path.join(repository, ".setup-fixed"), ""); + const retried = await client.createWorkspace({ + source: { kind: "worktree", cwd: repository, worktreeSlug: "fail-pre-start" }, + }); + expect(retried.error).toBeNull(); + const retriedPath = retried.workspace!.workspaceDirectory; + expect(git(retriedPath, ["branch", "--show-current"])).toBe("team/fail-pre-start"); + expect(await readFile(path.join(retriedPath, ".wt-hook-ran"), "utf8")).toBe("pre-start"); + + const rejectedAfter = await client.createWorkspace({ + source: { kind: "worktree", cwd: repository, worktreeSlug: "fail-after" }, + }); + expect(rejectedAfter.error).toContain("Paseo after-hook failed"); + expect(git(repository, ["branch", "--list", "team/fail-after"])).toBe(""); + await writeFile(path.join(repository, ".after-fixed"), ""); + const retriedAfter = await client.createWorkspace({ + source: { kind: "worktree", cwd: repository, worktreeSlug: "fail-after" }, + }); + expect(retriedAfter.error).toBeNull(); + const retriedAfterPath = retriedAfter.workspace!.workspaceDirectory; + expect(git(retriedAfterPath, ["branch", "--show-current"])).toBe("team/fail-after"); + expect(await readFile(path.join(retriedAfterPath, ".wt-hook-ran"), "utf8")).toBe("pre-start"); + + // Archive delegates removal to `wt remove` (run from repoRoot) AFTER Paseo writes refs/paseo/kept-commits/*. + const archived = await client.archiveWorkspace(workspaceId); + expect(archived.error).toBeNull(); + await expect(stat(worktreePath)).rejects.toMatchObject({ code: "ENOENT" }); + + // Restart daemon and restore: delegates to `wt switch --path `. + await client.close(); + await daemon.close(); + daemon = await createTestPaseoDaemon({ + paseoHomeRoot: path.join(root, "state"), + cleanup: false, + pluginsEnabled: true, + plugins: { + "a-branch-transform": { source: "directory", path: transformPluginDir, enabled: true }, + worktrunk: { source: "directory", path: WORKTRUNK_EXAMPLE, enabled: true }, + }, + }); + client = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws` }); + await client.connect(); + + await client.restoreWorkspace(workspaceId); + expect(git(worktreePath, ["branch", "--show-current"])).toBe("team/feat-one"); + expect(await readFile(path.join(worktreePath, ".wt-hook-ran"), "utf8")).toBe("reopen"); + expect(await readPaseoWorktreeMetadata(worktreePath)).toMatchObject({ + worktreeManagerPluginId: "worktrunk", + baseRefName: "release", + }); + + const events = (await readFile(wtLog, "utf8")) + .trim() + .split("\n") + .map((line) => JSON.parse(line)); + expect(events).toEqual([ + expect.objectContaining({ + command: "switch", + branch: "team/feat-one", + base: "refs/heads/release", + create: true, + }), + expect.objectContaining({ + command: "switch", + branch: "main", + action: "existing", + }), + expect.objectContaining({ + command: "switch", + branch: "team/fail-pre-start", + create: true, + }), + expect.objectContaining({ + command: "remove", + cwd: repository, + args: expect.arrayContaining([ + "remove", + "--foreground", + "--no-delete-branch", + "--no-hooks", + "--force", + ]), + }), + expect.objectContaining({ + command: "switch", + branch: "team/fail-pre-start", + create: true, + }), + expect.objectContaining({ command: "switch", branch: "team/fail-after", create: true }), + expect.objectContaining({ + command: "remove", + target: path.join(path.dirname(repository), "repo.team-fail-after"), + }), + expect.objectContaining({ command: "switch", branch: "team/fail-after", create: true }), + expect.objectContaining({ + command: "remove", + cwd: repository, + keptRefsCount: 1, + args: expect.arrayContaining([ + "remove", + "--foreground", + "--no-delete-branch", + "--yes", + "--force", + ]), + }), + expect.objectContaining({ + command: "switch", + branch: "team/feat-one", + create: false, + explicitPath: expect.any(String), + }), + ]); + expect(path.resolve(events.at(-1).explicitPath)).toBe(await realpath(worktreePath)); + } finally { + if (previousBin === undefined) delete process.env.WORKTRUNK_BIN; + else process.env.WORKTRUNK_BIN = previousBin; + await client.close(); + await daemon.close(); + await rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 }); + } +}, 60_000); + +test("worktree manager supports decline fallback, rollback delegation, and disabled-plugin fallback on archive and restore", async () => { + const root = await mkdtemp(path.join(tmpdir(), "paseo-worktree-manager-fallback-")); + const repository = await createRepo(path.join(root, "repo")); + const eventsFile = path.join(root, "events.jsonl"); + + const pluginDir = path.join(root, "custom-manager"); + await mkdir(pluginDir); + await writeFile( + path.join(pluginDir, "paseo-plugin.json"), + JSON.stringify({ id: "custom-manager", requirements: { paseo: ">=0.17.0" } }), + ); + await writeFile( + path.join(pluginDir, "index.server.ts"), + `import { execFileSync } from "node:child_process"; +import { appendFileSync } from "node:fs"; +import path from "node:path"; + +export default function contribute(server) { + const removeManager = server.registerWorktreeManager({ + async create(request) { + if (request.branch === "decline-me") return; + const target = path.join(path.dirname(request.repoRoot), "managed-" + request.branch); + execFileSync("git", ["worktree", "add", "-b", request.branch, target, request.baseRef], { + cwd: request.repoRoot, + stdio: "pipe", + }); + appendFileSync(${JSON.stringify(eventsFile)}, JSON.stringify({ op: "create", branch: request.branch, target }) + "\\n"); + return { type: "created", path: target }; + }, + async restore(request) { + execFileSync("git", ["worktree", "add", "-b", "wrong-restore", request.path, "main"], { + cwd: request.repoRoot, + stdio: "pipe", + }); + return { type: "restored", path: request.path }; + }, + async remove(request) { + appendFileSync(${JSON.stringify(eventsFile)}, JSON.stringify({ op: "remove", reason: request.reason, path: request.path }) + "\\n"); + execFileSync("git", ["worktree", "remove", request.path, "--force"], { + cwd: request.repoRoot, + stdio: "pipe", + }); + return { type: "removed" }; + }, + }); + const removeAfter = server.addHook("worktree.create.after", async ({ worktree }) => { + if (worktree.branch === "abort-after") { + throw new Error("rejected after creation"); + } + }); + return () => { + removeAfter(); + removeManager(); + }; +} +`, + ); + + const daemon = await createTestPaseoDaemon({ + paseoHomeRoot: path.join(root, "state"), + cleanup: false, + }); + const client = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws` }); + try { + await client.connect(); + await client.patchDaemonConfig({ pluginsEnabled: true }); + expect((await client.installDirectoryPlugin(pluginDir)).status).toBe("running"); + + // 1. Declining falls back cleanly to Paseo's built-in git worktree creation. + const declined = await client.createWorkspace({ + source: { kind: "worktree", cwd: repository, branchName: "decline-me" }, + }); + expect(declined.error).toBeNull(); + const declinedMeta = await readPaseoWorktreeMetadata(declined.workspace!.workspaceDirectory); + expect(declinedMeta?.worktreeManagerPluginId).toBeUndefined(); + + // 2. Failure in worktree.create.after rolls back through the manager's remove(reason: "rollback"). + const aborted = await client.createWorkspace({ + source: { kind: "worktree", cwd: repository, branchName: "abort-after" }, + }); + expect(aborted.workspace).toBeNull(); + expect(aborted.error).toContain("rejected after creation"); + await expect( + stat(path.join(path.dirname(repository), "managed-abort-after")), + ).rejects.toMatchObject({ + code: "ENOENT", + }); + + // 3. Create a managed worktree, then disable the plugin: archive & restore fall back to Git. + const managed = await client.createWorkspace({ + source: { kind: "worktree", cwd: repository, branchName: "survive-disable" }, + }); + expect(managed.error).toBeNull(); + const managedPath = managed.workspace!.workspaceDirectory; + await client.disablePlugin("custom-manager"); + + const archived = await client.archiveWorkspace(managed.workspace!.id); + expect(archived.error).toBeNull(); + await expect(stat(managedPath)).rejects.toMatchObject({ code: "ENOENT" }); + + await client.enablePlugin("custom-manager"); + await expect(client.restoreWorkspace(managed.workspace!.id)).rejects.toThrow( + "expected branch survive-disable", + ); + await expect(stat(managedPath)).rejects.toMatchObject({ code: "ENOENT" }); + await client.disablePlugin("custom-manager"); + + await client.restoreWorkspace(managed.workspace!.id); + expect(git(managedPath, ["branch", "--show-current"])).toBe("survive-disable"); + // Re-enabling the plugin must not route removal of a Git-restored worktree back to the plugin. + await client.enablePlugin("custom-manager"); + await client.archiveWorkspace(managed.workspace!.id); + await expect(stat(managedPath)).rejects.toMatchObject({ code: "ENOENT" }); + + const events = (await readFile(eventsFile, "utf8")) + .trim() + .split("\n") + .map((line) => JSON.parse(line)); + expect(events).toEqual([ + expect.objectContaining({ op: "create", branch: "abort-after" }), + expect.objectContaining({ op: "remove", reason: "rollback" }), + expect.objectContaining({ op: "create", branch: "survive-disable" }), + expect.objectContaining({ op: "remove", reason: "rollback" }), + ]); + } finally { + await client.close(); + await daemon.close(); + await rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 }); + } +}, 60_000); + +test("worktree manager rejects pre-existing worktrees, detached HEAD, wrong repos, and non-worktree paths without modifying them", async () => { + const root = await mkdtemp(path.join(tmpdir(), "paseo-worktree-manager-guards-")); + const repository = await createRepo(path.join(root, "repo")); + const otherRepo = await createRepo(path.join(root, "other-repo")); + + // Pre-existing manual worktree the user created outside Paseo. + const existingManual = path.join(root, "manual-existing"); + git(repository, ["worktree", "add", "-b", "manual-branch", existingManual, "main"]); + + const plainDir = path.join(root, "not-a-worktree"); + await mkdir(plainDir); + + const pluginDir = path.join(root, "bad-manager"); + await mkdir(pluginDir); + await writeFile( + path.join(pluginDir, "paseo-plugin.json"), + JSON.stringify({ id: "bad-manager", requirements: { paseo: ">=0.17.0" } }), + ); + await writeFile( + path.join(pluginDir, "index.server.ts"), + `import { execFileSync } from "node:child_process"; +import fs from "node:fs"; +import path from "node:path"; + +export default function contribute(server) { + return server.registerWorktreeManager({ + async create(request) { + if (request.branch === "existing") { + return { type: "created", path: ${JSON.stringify(existingManual)} }; + } + if (request.branch === "plain-dir") { + return { type: "created", path: ${JSON.stringify(plainDir)} }; + } + if (request.branch === "other-repo") { + const target = path.join(${JSON.stringify(root)}, "other-wt"); + execFileSync("git", ["worktree", "add", "-b", "other-wt", target, "main"], { + cwd: ${JSON.stringify(otherRepo)}, + stdio: "pipe", + }); + return { type: "created", path: target }; + } + if (request.branch === "detached") { + const target = path.join(${JSON.stringify(root)}, "detached-wt"); + execFileSync("git", ["worktree", "add", "--detach", target, "main"], { + cwd: request.repoRoot, + stdio: "pipe", + }); + return { type: "created", path: target }; + } + if (request.branch === "concurrent") { + const root = path.dirname(request.repoRoot); + const { writeFileSync, existsSync } = await import("node:fs"); + writeFileSync(path.join(root, "manager-started"), ""); + const deadline = Date.now() + 10_000; + while (!existsSync(path.join(root, "reject-manager"))) { + if (Date.now() > deadline) throw new Error("test did not release manager"); + await new Promise((resolve) => setTimeout(resolve, 20)); + } + throw new Error("manager rejected checkout"); + } + if (request.branch === "relative") { + return { type: "created", path: "relative/path" }; + } + if (request.branch === "ancestor") { + return { type: "created", path: path.dirname(request.repoRoot) }; + } + return; + }, + }); +} +`, + ); + + const daemon = await createTestPaseoDaemon(); + const client = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws` }); + try { + await client.connect(); + await client.patchDaemonConfig({ pluginsEnabled: true }); + expect((await client.installDirectoryPlugin(pluginDir)).status).toBe("running"); + + const cases: Array<[string, string]> = [ + ["existing", "already-existing worktree"], + ["plain-dir", "did not create a Git worktree"], + ["other-repo", "outside the repository"], + ["detached", "detached HEAD"], + ["relative", "Plugin bad-manager worktree.create failed: The returned path is relative"], + [ + "ancestor", + "Plugin bad-manager worktree.create failed: The returned path is an ancestor of the repository", + ], + ]; + for (const [branchName, expectedError] of cases) { + const created = await client.createWorkspace({ + source: { kind: "worktree", cwd: repository, branchName }, + }); + expect(created.workspace).toBeNull(); + expect(created.error).toContain(expectedError); + } + + // The pre-existing manual worktree must stay untouched and un-owned by Paseo. + expect(await readPaseoWorktreeMetadata(existingManual)).toBeNull(); + expect((await stat(existingManual)).isDirectory()).toBe(true); + // The newly created detached worktree failed adoption and must be rolled back cleanly. + await expect(stat(path.join(root, "detached-wt"))).rejects.toMatchObject({ code: "ENOENT" }); + expect(git(repository, ["worktree", "list", "--porcelain"])).not.toContain("detached-wt"); + const pending = client.createWorkspace({ + source: { kind: "worktree", cwd: repository, branchName: "concurrent" }, + }); + await expect + .poll(() => + stat(path.join(root, "manager-started")).then( + () => true, + () => false, + ), + ) + .toBe(true); + const concurrent = path.join(root, "concurrent-manual"); + git(repository, ["worktree", "add", "-b", "concurrent", concurrent, "main"]); + await writeFile(path.join(concurrent, "local.txt"), "uncommitted work"); + await writeFile(path.join(root, "reject-manager"), ""); + const rejected = await pending; + expect(rejected.workspace).toBeNull(); + expect(rejected.error).toContain("manager rejected checkout"); + expect(await readFile(path.join(concurrent, "local.txt"), "utf8")).toBe("uncommitted work"); + expect(git(concurrent, ["branch", "--show-current"])).toBe("concurrent"); + } finally { + await client.close(); + await daemon.close(); + await rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 }); + } +}, 60_000); + +test("worktree manager rejects duplicate registration and fails removal when the directory remains on disk", async () => { + const root = await mkdtemp(path.join(tmpdir(), "paseo-worktree-manager-edge-")); + const repository = await createRepo(path.join(root, "repo")); + + const dupPluginDir = path.join(root, "dup-manager"); + await mkdir(dupPluginDir); + await writeFile( + path.join(dupPluginDir, "paseo-plugin.json"), + JSON.stringify({ id: "dup-manager", requirements: { paseo: ">=0.17.0" } }), + ); + await writeFile( + path.join(dupPluginDir, "index.server.ts"), + `export default function contribute(server) { + server.registerWorktreeManager({ async create() {} }); + server.registerWorktreeManager({ async create() {} }); + return () => {}; +} +`, + ); + + const leakyRemoveDir = path.join(root, "leaky-remove"); + await mkdir(leakyRemoveDir); + await writeFile( + path.join(leakyRemoveDir, "paseo-plugin.json"), + JSON.stringify({ id: "leaky-remove", requirements: { paseo: ">=0.17.0" } }), + ); + await writeFile( + path.join(leakyRemoveDir, "index.server.ts"), + `import { execFileSync } from "node:child_process"; +import fs from "node:fs"; +import path from "node:path"; + +export default function contribute(server) { + return server.registerWorktreeManager({ + async create(request) { + const target = path.join(path.dirname(request.repoRoot), "leaky-" + request.branch); + execFileSync("git", ["worktree", "add", "-b", request.branch, target, request.baseRef], { + cwd: request.repoRoot, + stdio: "pipe", + }); + return { type: "created", path: target }; + }, + async remove({ branch }) { + if (branch === "remove-throws") throw new Error("Remove failed before touching the checkout"); + return { type: "removed" }; + }, + }); +} +`, + ); + + const daemon = await createTestPaseoDaemon(); + const client = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws` }); + try { + await client.connect(); + await client.patchDaemonConfig({ pluginsEnabled: true }); + + await expect(client.installDirectoryPlugin(dupPluginDir)).rejects.toThrow( + "Plugin already registered a worktree manager", + ); + + expect((await client.installDirectoryPlugin(leakyRemoveDir)).status).toBe("running"); + for (const branchName of ["still-here", "remove-throws"]) { + const created = await client.createWorkspace({ + source: { kind: "worktree", cwd: repository, branchName }, + }); + expect(created.error).toBeNull(); + const worktreePath = created.workspace!.workspaceDirectory; + + const archived = await client.archiveWorkspace(created.workspace!.id); + expect(archived.error).toBeNull(); + expect((await stat(worktreePath)).isDirectory()).toBe(true); + } + } finally { + await client.close(); + await daemon.close(); + await rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 }); + } +}, 60_000); + +test("untrusted workspaces pass untrusted=true to worktree manager remove and restore, and worktrunk skips hooks", async () => { + const root = await mkdtemp(path.join(tmpdir(), "paseo-worktrunk-untrusted-")); + const repository = await createRepo(path.join(root, "repo")); + const wtLog = path.join(root, "wt-log.jsonl"); + const fakeWt = await createFakeWorktrunkCli(root, wtLog); + const previousBin = process.env.WORKTRUNK_BIN; + process.env.WORKTRUNK_BIN = fakeWt; + + const stateDir = path.join(root, "state"); + let daemon = await createTestPaseoDaemon({ + paseoHomeRoot: stateDir, + cleanup: false, + }); + let client = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws` }); + try { + await client.connect(); + await client.patchDaemonConfig({ pluginsEnabled: true }); + expect((await client.installDirectoryPlugin(WORKTRUNK_EXAMPLE)).status).toBe("running"); + + git(repository, ["branch", "existing-topic"]); + git(repository, ["commit", "--allow-empty", "-m", "advance main"]); + const collision = await client.createWorkspace({ + source: { kind: "worktree", cwd: repository, branchName: "existing-topic" }, + }); + expect(collision.error).toBeNull(); + const collisionPath = collision.workspace!.workspaceDirectory; + expect(git(collisionPath, ["branch", "--show-current"])).not.toBe("existing-topic"); + expect(git(collisionPath, ["rev-parse", "HEAD"])).toBe( + git(repository, ["rev-parse", "existing-topic"]), + ); + await client.archiveWorkspace(collision.workspace!.id); + + const remote = await createRepo(path.join(root, "remote")); + git(repository, ["remote", "add", "origin", remote]); + git(repository, ["fetch", "origin", "main"]); + const cached = git(repository, ["rev-parse", "refs/remotes/origin/main"]); + git(remote, ["commit", "--allow-empty", "-m", "advance remote main"]); + const remoteTip = git(remote, ["rev-parse", "HEAD"]); + expect(cached).not.toBe(remoteTip); + + const created = await client.createWorkspace({ + source: { + kind: "worktree", + cwd: repository, + action: "branch-off", + baseBranch: "refs/remotes/origin/main", + branchName: "fork-pr-branch", + }, + }); + expect(created.error).toBeNull(); + const workspaceId = created.workspace!.id; + const worktreePath = created.workspace!.workspaceDirectory; + + expect(git(worktreePath, ["rev-parse", "HEAD"])).toBe(remoteTip); + + // Mark the persisted workspace record as originating from an untrusted fork PR and reload daemon. + await client.close(); + await daemon.close(); + const workspacesPath = path.join(daemon.paseoHome, "projects", "workspaces.json"); + const records = JSON.parse(await readFile(workspacesPath, "utf8")) as Array< + Record + >; + for (const record of records) { + if (record.workspaceId === workspaceId) { + record.untrustedSource = { + kind: "change_request", + forge: "github", + number: 42, + headRepository: "fork-owner/repo", + }; + } + } + await writeFile(workspacesPath, JSON.stringify(records, null, 2)); + + daemon = await createTestPaseoDaemon({ + paseoHomeRoot: stateDir, + cleanup: false, + pluginsEnabled: true, + plugins: { + worktrunk: { source: "directory", path: WORKTRUNK_EXAMPLE, enabled: true }, + }, + }); + client = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws` }); + await client.connect(); + + const archived = await client.archiveWorkspace(workspaceId); + expect(archived.error).toBeNull(); + await expect(stat(worktreePath)).rejects.toMatchObject({ code: "ENOENT" }); + + await client.restoreWorkspace(workspaceId); + expect(git(worktreePath, ["branch", "--show-current"])).toBe("fork-pr-branch"); + + const events = (await readFile(wtLog, "utf8")) + .trim() + .split("\n") + .map((line) => JSON.parse(line) as { command: string; cwd: string; args: string[] }); + const removeEvent = events.find((event) => event.command === "remove"); + expect(removeEvent).toBeDefined(); + expect(removeEvent!.cwd).toBe(repository); + expect(removeEvent!.args).toContain("--no-hooks"); + expect(removeEvent!.args).not.toContain("--yes"); + + const restoreEvent = events.at(-1); + expect(restoreEvent?.command).toBe("switch"); + expect(restoreEvent?.args).toContain("--no-hooks"); + expect(restoreEvent?.args).not.toContain("--yes"); + + // Sibling workspace created on a subdirectory of the same unapproved fork checkout must also + // skip hooks on both last-sibling archive and subsequent restore. + const subDir = path.join(worktreePath, "packages", "sub"); + await mkdir(subDir, { recursive: true }); + await writeFile(path.join(subDir, "README.md"), "sub"); + git(worktreePath, ["add", "packages/sub/README.md"]); + git(worktreePath, ["commit", "-m", "add subpackage"]); + const siblingCreated = await client.createWorkspace({ + source: { kind: "directory", path: subDir }, + }); + expect(siblingCreated.error).toBeNull(); + const siblingId = siblingCreated.workspace!.id; + + expect((await client.archiveWorkspace(workspaceId)).error).toBeNull(); + expect((await stat(worktreePath)).isDirectory()).toBe(true); + + expect((await client.archiveWorkspace(siblingId)).error).toBeNull(); + await expect(stat(worktreePath)).rejects.toMatchObject({ code: "ENOENT" }); + + await client.restoreWorkspace(siblingId); + expect(git(worktreePath, ["branch", "--show-current"])).toBe("fork-pr-branch"); + + const allEvents = (await readFile(wtLog, "utf8")) + .trim() + .split("\n") + .map((line) => JSON.parse(line) as { command: string; cwd: string; args: string[] }); + const siblingEvents = allEvents.slice(events.length); + const siblingRemoveEvent = siblingEvents.find((event) => event.command === "remove"); + expect(siblingRemoveEvent).toBeDefined(); + expect(siblingRemoveEvent!.args).toContain("--no-hooks"); + expect(siblingRemoveEvent!.args).not.toContain("--yes"); + const siblingRestoreEvent = siblingEvents.at(-1); + expect(siblingRestoreEvent?.command).toBe("switch"); + expect(siblingRestoreEvent?.args).toContain("--no-hooks"); + expect(siblingRestoreEvent?.args).not.toContain("--yes"); + } finally { + if (previousBin === undefined) delete process.env.WORKTRUNK_BIN; + else process.env.WORKTRUNK_BIN = previousBin; + await client.close(); + await daemon.close(); + await rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 }); + } +}, 60_000); + +test("concurrent restores across two daemon clients wait for the in-flight manager restore and share its failure", async () => { + const root = await mkdtemp(path.join(tmpdir(), "paseo-worktree-restore-race-")); + const repository = await createRepo(path.join(root, "repo")); + const dirCreatedMarker = path.join(root, "restore-dir-created"); + const releaseMarker = path.join(root, "release-restore"); + const allowSucceedMarker = path.join(root, "allow-restore-succeed"); + + const pluginDir = path.join(root, "slow-restore-manager"); + await mkdir(pluginDir); + await writeFile( + path.join(pluginDir, "paseo-plugin.json"), + JSON.stringify({ id: "slow-restore-manager", requirements: { paseo: ">=0.17.0" } }), + ); + await writeFile( + path.join(pluginDir, "index.server.ts"), + `import { execFileSync } from "node:child_process"; +import { existsSync, writeFileSync } from "node:fs"; +import path from "node:path"; + +export default function contribute(server) { + return server.registerWorktreeManager({ + async create(request) { + const target = path.join(path.dirname(request.repoRoot), "managed-" + request.branch); + execFileSync("git", ["worktree", "add", "-b", request.branch, target, request.baseRef], { + cwd: request.repoRoot, + stdio: "pipe", + }); + return { type: "created", path: target }; + }, + async remove(request) { + execFileSync("git", ["worktree", "remove", request.path, "--force"], { + cwd: request.repoRoot, + stdio: "pipe", + }); + return { type: "removed" }; + }, + async restore(request) { + if (request.target.type !== "branch") return; + execFileSync("git", ["worktree", "add", request.path, request.target.branch], { + cwd: request.repoRoot, + stdio: "pipe", + }); + if (!existsSync(${JSON.stringify(allowSucceedMarker)})) { + writeFileSync(${JSON.stringify(dirCreatedMarker)}, "ready"); + const deadline = Date.now() + 15_000; + while (!existsSync(${JSON.stringify(releaseMarker)})) { + if (Date.now() > deadline) throw new Error("test did not release restore"); + await new Promise((resolve) => setTimeout(resolve, 20)); + } + execFileSync("git", ["worktree", "remove", request.path, "--force"], { + cwd: request.repoRoot, + stdio: "pipe", + }); + throw new Error("restore setup failed"); + } + return { type: "restored", path: request.path }; + }, + }); +} +`, + ); + + const daemon = await createTestPaseoDaemon(); + const client1 = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws` }); + const client2 = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws` }); + try { + await Promise.all([client1.connect(), client2.connect()]); + await client1.patchDaemonConfig({ pluginsEnabled: true }); + expect((await client1.installDirectoryPlugin(pluginDir)).status).toBe("running"); + + const created = await client1.createWorkspace({ + source: { kind: "worktree", cwd: repository, branchName: "race-branch" }, + }); + expect(created.error).toBeNull(); + const workspaceId = created.workspace!.id; + const worktreePath = created.workspace!.workspaceDirectory; + + const archived = await client1.archiveWorkspace(workspaceId); + expect(archived.error).toBeNull(); + await expect(stat(worktreePath)).rejects.toMatchObject({ code: "ENOENT" }); + + // Start first restore and wait until the worktree directory exists on disk while setup is still paused. + const firstRestore = client1.restoreWorkspace(workspaceId); + await expect + .poll( + () => + stat(dirCreatedMarker).then( + () => true, + () => false, + ), + { timeout: 10_000 }, + ) + .toBe(true); + expect((await stat(worktreePath)).isDirectory()).toBe(true); + + // Second client restores while the first is still running: must wait instead of prematurely unarchiving. + let secondSettled = false; + const secondRestore = client2.restoreWorkspace(workspaceId); + void secondRestore.then( + () => { + secondSettled = true; + return undefined; + }, + () => { + secondSettled = true; + return undefined; + }, + ); + await new Promise((resolve) => setTimeout(resolve, 150)); + expect(secondSettled).toBe(false); + + // Release the first restore to fail and roll back its partial directory: both callers must reject. + await writeFile(releaseMarker, "go"); + await expect(firstRestore).rejects.toThrow("restore setup failed"); + await expect(secondRestore).rejects.toThrow("restore setup failed"); + await expect(stat(worktreePath)).rejects.toMatchObject({ code: "ENOENT" }); + + // Workspace remains archived and can be restored cleanly on retry. + const recovery = await client1.inspectWorkspaceRecovery(workspaceId); + expect(recovery.kind).toBe("recoverable"); + await writeFile(allowSucceedMarker, "ok"); + await client1.restoreWorkspace(workspaceId); + expect(git(worktreePath, ["branch", "--show-current"])).toBe("race-branch"); + } finally { + await client1.close(); + await client2.close(); + await daemon.close(); + await rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 }); + } +}, 60_000); + +test("restore waits for an in-flight CLI worktree archive remove before recreating the checkout", async () => { + const root = await mkdtemp(path.join(tmpdir(), "paseo-worktree-cli-archive-race-")); + const repository = await createRepo(path.join(root, "repo")); + const removeStartedMarker = path.join(root, "remove-started"); + const releaseRemoveMarker = path.join(root, "release-remove"); + + const pluginDir = path.join(root, "slow-remove-manager"); + await mkdir(pluginDir); + await writeFile( + path.join(pluginDir, "paseo-plugin.json"), + JSON.stringify({ id: "slow-remove-manager", requirements: { paseo: ">=0.17.0" } }), + ); + await writeFile( + path.join(pluginDir, "index.server.ts"), + `import { execFileSync } from "node:child_process"; +import { existsSync, writeFileSync } from "node:fs"; +import path from "node:path"; + +export default function contribute(server) { + return server.registerWorktreeManager({ + async create(request) { + const target = path.join(path.dirname(request.repoRoot), "managed-" + request.branch); + execFileSync("git", ["worktree", "add", "-b", request.branch, target, request.baseRef], { + cwd: request.repoRoot, + stdio: "pipe", + }); + return { type: "created", path: target }; + }, + async remove(request) { + writeFileSync(${JSON.stringify(removeStartedMarker)}, "paused"); + const deadline = Date.now() + 15_000; + while (!existsSync(${JSON.stringify(releaseRemoveMarker)})) { + if (Date.now() > deadline) throw new Error("test did not release remove"); + await new Promise((resolve) => setTimeout(resolve, 20)); + } + execFileSync("git", ["worktree", "remove", request.path, "--force"], { + cwd: request.repoRoot, + stdio: "pipe", + }); + return { type: "removed" }; + }, + async restore(request) { + if (request.target.type !== "branch") return; + execFileSync("git", ["worktree", "add", request.path, request.target.branch], { + cwd: request.repoRoot, + stdio: "pipe", + }); + return { type: "restored", path: request.path }; + }, + }); +} +`, + ); + + const daemon = await createTestPaseoDaemon(); + const client1 = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws` }); + const client2 = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws` }); + try { + await Promise.all([client1.connect(), client2.connect()]); + await client1.patchDaemonConfig({ pluginsEnabled: true }); + expect((await client1.installDirectoryPlugin(pluginDir)).status).toBe("running"); + + const created = await client1.createWorkspace({ + source: { kind: "worktree", cwd: repository, branchName: "cli-race-branch" }, + }); + expect(created.error).toBeNull(); + const workspaceId = created.workspace!.id; + const worktreePath = created.workspace!.workspaceDirectory; + + // Client 1 starts a CLI worktree archive (scope: "worktree"); pause inside manager.remove after the record is archived. + const cliArchive = client1.archivePaseoWorktree({ worktreePath, scope: "worktree" }); + await expect + .poll( + () => + stat(removeStartedMarker).then( + () => true, + () => false, + ), + { timeout: 10_000 }, + ) + .toBe(true); + + // Client 2 opens the project path while manager.remove holds the checkout: openProject must wait, + // then reject with directory_not_found instead of unarchiving a deleted checkout. + let openSettled = false; + const openPromise = client2.openProject(worktreePath); + void openPromise.then( + () => { + openSettled = true; + return undefined; + }, + () => { + openSettled = true; + return undefined; + }, + ); + + // Client 2 also restores while manager.remove still holds the checkout: restore must wait, not unarchive early. + let restoreSettled = false; + const restorePromise = client2.restoreWorkspace(workspaceId); + void restorePromise.then( + () => { + restoreSettled = true; + return undefined; + }, + () => { + restoreSettled = true; + return undefined; + }, + ); + await new Promise((resolve) => setTimeout(resolve, 150)); + expect(openSettled).toBe(false); + expect(restoreSettled).toBe(false); + + // Release manager.remove to delete the checkout; openProject sees it gone, and restore recreates it cleanly. + await writeFile(releaseRemoveMarker, "go"); + const archiveResult = await cliArchive; + expect(archiveResult.success).toBe(true); + const openResult = await openPromise; + expect(openResult.workspace).toBeNull(); + expect(openResult.errorCode).toBe("directory_not_found"); + await restorePromise; + + expect((await stat(worktreePath)).isDirectory()).toBe(true); + expect(git(worktreePath, ["branch", "--show-current"])).toBe("cli-race-branch"); + } finally { + await client1.close(); + await client2.close(); + await daemon.close(); + await rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 }); + } +}, 60_000); + +test("git fallback restore clears manager ownership across sibling workspaces sharing a checkout", async () => { + const root = await mkdtemp(path.join(tmpdir(), "paseo-worktree-sibling-owner-")); + const repository = await createRepo(path.join(root, "repo")); + await mkdir(path.join(repository, "packages", "sub"), { recursive: true }); + await writeFile(path.join(repository, "packages", "sub", "README.md"), "sub"); + git(repository, ["add", "."]); + git(repository, ["commit", "-m", "add subpackage"]); + const removeCallsFile = path.join(root, "remove-calls.log"); + + const pluginDir = path.join(root, "owner-tracking-manager"); + await mkdir(pluginDir); + await writeFile( + path.join(pluginDir, "paseo-plugin.json"), + JSON.stringify({ id: "owner-tracking-manager", requirements: { paseo: ">=0.17.0" } }), + ); + await writeFile( + path.join(pluginDir, "index.server.ts"), + `import { execFileSync } from "node:child_process"; +import { appendFileSync } from "node:fs"; +import path from "node:path"; + +export default function contribute(server) { + return server.registerWorktreeManager({ + async create(request) { + const target = path.join(path.dirname(request.repoRoot), "managed-" + request.branch); + execFileSync("git", ["worktree", "add", "-b", request.branch, target, request.baseRef], { + cwd: request.repoRoot, + stdio: "pipe", + }); + return { type: "created", path: target }; + }, + async remove(request) { + appendFileSync(${JSON.stringify(removeCallsFile)}, request.path + "\\n"); + execFileSync("git", ["worktree", "remove", request.path, "--force"], { + cwd: request.repoRoot, + stdio: "pipe", + }); + return { type: "removed" }; + }, + }); +} +`, + ); + + const daemon = await createTestPaseoDaemon(); + const client = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws` }); + try { + await client.connect(); + await client.patchDaemonConfig({ pluginsEnabled: true }); + expect((await client.installDirectoryPlugin(pluginDir)).status).toBe("running"); + + const created = await client.createWorkspace({ + source: { kind: "worktree", cwd: repository, branchName: "shared-checkout" }, + }); + expect(created.error).toBeNull(); + const firstWorkspaceId = created.workspace!.id; + const worktreePath = created.workspace!.workspaceDirectory; + + // Create a second workspace on a subdirectory of the same managed checkout, sharing ownership. + const secondCreated = await client.createWorkspace({ + source: { kind: "directory", path: path.join(worktreePath, "packages", "sub") }, + }); + expect(secondCreated.error).toBeNull(); + const secondWorkspaceId = secondCreated.workspace!.id; + + // Persist the same manager owner on both records, disable the plugin, archive both, and restore via Git fallback. + await client.disablePlugin("owner-tracking-manager"); + const archived = await client.archivePaseoWorktree({ worktreePath, scope: "worktree" }); + expect(archived.success).toBe(true); + await expect(stat(worktreePath)).rejects.toMatchObject({ code: "ENOENT" }); + + // First restore recreates via Git fallback; second restore joins the existing checkout. + await client.restoreWorkspace(firstWorkspaceId); + await client.restoreWorkspace(secondWorkspaceId); + expect((await stat(worktreePath)).isDirectory()).toBe(true); + + // Re-enable the plugin and archive both workspaces: neither should invoke the former manager's remove. + await client.enablePlugin("owner-tracking-manager"); + expect((await client.archiveWorkspace(firstWorkspaceId)).error).toBeNull(); + expect((await client.archiveWorkspace(secondWorkspaceId)).error).toBeNull(); + await expect(stat(worktreePath)).rejects.toMatchObject({ code: "ENOENT" }); + await expect(readFile(removeCallsFile, "utf8")).rejects.toMatchObject({ code: "ENOENT" }); + } finally { + await client.close(); + await daemon.close(); + await rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 }); + } +}, 60_000); + +test("undo after a restore queued behind a running archive still cancels before checkout removal", async () => { + const root = await mkdtemp(path.join(tmpdir(), "paseo-worktree-restore-undo-race-")); + const repository = await createRepo(path.join(root, "repo")); + const teardownStartedMarker = path.join(root, "teardown-started"); + const releaseTeardownMarker = path.join(root, "release-teardown"); + const teardownScript = path.join(root, "wait-teardown.mjs"); + await writeFile( + teardownScript, + `import { existsSync, writeFileSync } from "node:fs"; +writeFileSync(${JSON.stringify(teardownStartedMarker)}, "paused"); +const deadline = Date.now() + 15_000; +while (!existsSync(${JSON.stringify(releaseTeardownMarker)})) { + if (Date.now() > deadline) throw new Error("test did not release teardown"); + await new Promise((resolve) => setTimeout(resolve, 20)); +} +`, + ); + await writeFile( + path.join(repository, "paseo.json"), + JSON.stringify({ + worktree: { + teardown: [`node "${teardownScript}"`], + }, + }), + ); + git(repository, ["add", "paseo.json"]); + git(repository, ["commit", "-m", "add teardown hook"]); + + const daemon = await createTestPaseoDaemon(); + const client1 = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws` }); + const client2 = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws` }); + try { + await Promise.all([client1.connect(), client2.connect()]); + const created = await client1.createWorkspace({ + source: { kind: "worktree", cwd: repository, branchName: "undo-race-branch" }, + }); + expect(created.error).toBeNull(); + const workspaceId = created.workspace!.id; + const worktreePath = created.workspace!.workspaceDirectory; + const uncommittedFile = path.join(worktreePath, "uncommitted.txt"); + await writeFile(uncommittedFile, "keep-me"); + + const archivePromise = client1.archiveWorkspace(workspaceId); + await expect + .poll( + () => + stat(teardownStartedMarker).then( + () => true, + () => false, + ), + { timeout: 10_000 }, + ) + .toBe(true); + + // Send Restore, then Undo while teardown is still running. + const restorePromise = client2.restoreWorkspace(workspaceId); + await new Promise((resolve) => setTimeout(resolve, 100)); + const undoPromise = client1.undoWorkspaceArchive(workspaceId); + await new Promise((resolve) => setTimeout(resolve, 100)); + + await writeFile(releaseTeardownMarker, "go"); + const archiveResult = await archivePromise; + expect(archiveResult.canceled).toBe(true); + await Promise.all([restorePromise, undoPromise]); + + expect(await readFile(uncommittedFile, "utf8")).toBe("keep-me"); + } finally { + await client1.close(); + await client2.close(); + await daemon.close(); + await rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 }); + } +}, 60_000); + +test("worktree manager rejects nested and enclosing secondary worktrees without deleting existing work", async () => { + const root = await mkdtemp(path.join(tmpdir(), "paseo-worktree-nested-reject-")); + const repository = await createRepo(path.join(root, "repo")); + const worktreesBase = path.join(root, "wt-layout"); + + const pluginDir = path.join(root, "nested-layout-manager"); + await mkdir(pluginDir); + await writeFile( + path.join(pluginDir, "paseo-plugin.json"), + JSON.stringify({ id: "nested-layout-manager", requirements: { paseo: ">=0.17.0" } }), + ); + await writeFile( + path.join(pluginDir, "index.server.ts"), + `import { execFileSync } from "node:child_process"; +import fs from "node:fs"; +import path from "node:path"; + +export default function contribute(server) { + return server.registerWorktreeManager({ + async create(request) { + let target; + if (request.branch === "team") { + target = path.join(${JSON.stringify(worktreesBase)}, "team"); + } else if (request.branch === "topic") { + target = path.join(${JSON.stringify(worktreesBase)}, "team", "topic"); + } else if (request.branch === "inner") { + target = path.join(${JSON.stringify(worktreesBase)}, "outer", "inner"); + } else if (request.branch === "outer") { + target = path.join(${JSON.stringify(worktreesBase)}, "outer"); + const staged = path.join(${JSON.stringify(worktreesBase)}, "outer-staged"); + execFileSync("git", ["worktree", "add", "-b", request.branch, staged, request.baseRef], { + cwd: request.repoRoot, + stdio: "pipe", + }); + fs.cpSync(staged, target, { recursive: true, force: true }); + fs.rmSync(staged, { recursive: true, force: true }); + execFileSync("git", ["worktree", "repair", target], { + cwd: request.repoRoot, + stdio: "pipe", + }); + return { type: "created", path: target }; + } else { + return; + } + execFileSync("git", ["worktree", "add", "-b", request.branch, target, request.baseRef], { + cwd: request.repoRoot, + stdio: "pipe", + }); + return { type: "created", path: target }; + }, + async remove(request) { + execFileSync("git", ["worktree", "remove", request.path, "--force"], { + cwd: request.repoRoot, + stdio: "pipe", + }); + return { type: "removed" }; + }, + }); +} +`, + ); + + const daemon = await createTestPaseoDaemon(); + const client = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws` }); + try { + await client.connect(); + await client.patchDaemonConfig({ pluginsEnabled: true }); + expect((await client.installDirectoryPlugin(pluginDir)).status).toBe("running"); + + // 1. Reject creating a secondary worktree nested inside an existing secondary worktree. + const team = await client.createWorkspace({ + source: { kind: "worktree", cwd: repository, branchName: "team" }, + }); + expect(team.error).toBeNull(); + const teamPath = team.workspace!.workspaceDirectory; + await writeFile(path.join(teamPath, "team-dirty.txt"), "team-work"); + + const nested = await client.createWorkspace({ + source: { kind: "worktree", cwd: repository, branchName: "topic" }, + }); + expect(nested.error).toContain("nested inside an existing worktree"); + await expect(stat(path.join(teamPath, "topic"))).rejects.toMatchObject({ code: "ENOENT" }); + expect(await readFile(path.join(teamPath, "team-dirty.txt"), "utf8")).toBe("team-work"); + + // 2. Reject creating a worktree enclosing an existing worktree without deleting the inner worktree. + const inner = await client.createWorkspace({ + source: { kind: "worktree", cwd: repository, branchName: "inner" }, + }); + expect(inner.error).toBeNull(); + const innerPath = inner.workspace!.workspaceDirectory; + await writeFile(path.join(innerPath, "inner-dirty.txt"), "inner-work"); + + const outer = await client.createWorkspace({ + source: { kind: "worktree", cwd: repository, branchName: "outer" }, + }); + expect(outer.error).toContain("enclosing an existing worktree"); + expect(await readFile(path.join(innerPath, "inner-dirty.txt"), "utf8")).toBe("inner-work"); + } finally { + await client.close(); + await daemon.close(); + await rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 }); + } +}, 60_000); + +async function addNestedGitContent(checkout: string, dependency: string, middle: string) { + await writeFile(path.join(checkout, ".gitignore"), ".build/\n"); + const checkouts = path.join(checkout, ".build", "checkouts"); + await mkdir(checkouts, { recursive: true }); + git(checkout, ["clone", dependency, path.join(checkouts, "dependency")]); + git(checkout, ["-c", "protocol.file.allow=always", "submodule", "add", middle, "middle"]); + git(checkout, [ + "-c", + "protocol.file.allow=always", + "submodule", + "update", + "--init", + "--recursive", + ]); + expect((await stat(path.join(checkout, "middle", "leaf", "README.md"))).isFile()).toBe(true); +} + +test("built-in archive removes the worktree with dependency clones and recursive submodules", async () => { + const root = await mkdtemp(path.join(tmpdir(), "paseo-built-in-archive-")); + const daemon = await createTestPaseoDaemon(); + const client = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws` }); + try { + const repository = await createRepo(path.join(root, "repo")); + const leaf = await createRepo(path.join(root, "leaf")); + const middle = await createRepo(path.join(root, "middle")); + git(middle, ["-c", "protocol.file.allow=always", "submodule", "add", leaf, "leaf"]); + git(middle, ["commit", "-am", "Add leaf submodule"]); + + await client.connect(); + const created = await client.createWorkspace({ + source: { kind: "worktree", cwd: repository, branchName: "built-in" }, + }); + expect(created.error).toBeNull(); + const checkout = created.workspace!.workspaceDirectory; + await addNestedGitContent(checkout, leaf, middle); + + const archived = await client.archiveWorkspace(created.workspace!.id); + expect(archived.error).toBeNull(); + await expect(stat(checkout)).rejects.toMatchObject({ code: "ENOENT" }); + expect(git(repository, ["worktree", "list", "--porcelain"])).not.toContain( + "refs/heads/built-in", + ); + } finally { + await client.close(); + await daemon.close(); + await rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 }); + } +}, 60_000); + +test("archive and rollback refuse to delete a worktree containing a live nested Git worktree", async () => { + const root = await mkdtemp(path.join(tmpdir(), "paseo-worktree-nested-delete-guard-")); + const repository = await createRepo(path.join(root, "repo")); + const detachedCreatedMarker = path.join(root, "detached-created"); + const releaseDetachedMarker = path.join(root, "release-detached"); + const removeCallsFile = path.join(root, "remove-calls.log"); + + const pluginDir = path.join(root, "nested-delete-guard-manager"); + await mkdir(pluginDir); + await writeFile( + path.join(pluginDir, "paseo-plugin.json"), + JSON.stringify({ id: "nested-delete-guard-manager", requirements: { paseo: ">=0.17.0" } }), + ); + await writeFile( + path.join(pluginDir, "index.server.ts"), + `import { execFileSync } from "node:child_process"; +import { appendFileSync, existsSync, writeFileSync } from "node:fs"; +import path from "node:path"; + +export default function contribute(server) { + return server.registerWorktreeManager({ + async create(request) { + const target = path.join(path.dirname(request.repoRoot), "managed-" + request.branch); + if (request.branch === "detached-outer") { + execFileSync("git", ["worktree", "add", "--detach", target, request.baseRef], { + cwd: request.repoRoot, + stdio: "pipe", + }); + writeFileSync(${JSON.stringify(detachedCreatedMarker)}, target); + const deadline = Date.now() + 15_000; + while (!existsSync(${JSON.stringify(releaseDetachedMarker)})) { + if (Date.now() > deadline) throw new Error("test did not release detached create"); + await new Promise((resolve) => setTimeout(resolve, 20)); + } + return { type: "created", path: target }; + } + execFileSync("git", ["worktree", "add", "-b", request.branch, target, request.baseRef], { + cwd: request.repoRoot, + stdio: "pipe", + }); + return { type: "created", path: target }; + }, + async remove(request) { + appendFileSync(${JSON.stringify(removeCallsFile)}, request.path + "\\n"); + execFileSync("git", ["worktree", "remove", request.path, "--force"], { + cwd: request.repoRoot, + stdio: "pipe", + }); + return { type: "removed" }; + }, + }); +} +`, + ); + + const daemon = await createTestPaseoDaemon(); + const client = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws` }); + try { + await client.connect(); + await client.patchDaemonConfig({ pluginsEnabled: true }); + expect((await client.installDirectoryPlugin(pluginDir)).status).toBe("running"); + + // 1. Archive of outer worktree must preserve a live nested Git worktree that Paseo does not track. + const created = await client.createWorkspace({ + source: { kind: "worktree", cwd: repository, branchName: "outer-archive" }, + }); + expect(created.error).toBeNull(); + const outerPath = created.workspace!.workspaceDirectory; + const nestedArchivePath = path.join(outerPath, "untracked-nested"); + git(repository, ["worktree", "add", "-b", "untracked-nested", nestedArchivePath]); + const nestedArchiveFile = path.join(nestedArchivePath, "uncommitted.txt"); + await writeFile(nestedArchiveFile, "keep-archive-nested"); + + const archived = await client.archiveWorkspace(created.workspace!.id); + expect(archived.error).toBeNull(); + expect(await readFile(nestedArchiveFile, "utf8")).toBe("keep-archive-nested"); + await expect(readFile(removeCallsFile, "utf8")).rejects.toMatchObject({ code: "ENOENT" }); + + // 2. Rollback of a failed create must preserve a nested Git worktree added while create paused. + const detachedCreate = client.createWorkspace({ + source: { kind: "worktree", cwd: repository, branchName: "detached-outer" }, + }); + await expect + .poll( + () => + stat(detachedCreatedMarker).then( + () => true, + () => false, + ), + { timeout: 10_000 }, + ) + .toBe(true); + const detachedOuterPath = await readFile(detachedCreatedMarker, "utf8"); + const nestedRollbackPath = path.join(detachedOuterPath, "nested-during-create"); + git(repository, ["worktree", "add", "-b", "nested-during-create", nestedRollbackPath]); + const nestedRollbackFile = path.join(nestedRollbackPath, "uncommitted.txt"); + await writeFile(nestedRollbackFile, "keep-rollback-nested"); + + await writeFile(releaseDetachedMarker, "go"); + const detachedResult = await detachedCreate; + expect(detachedResult.error).toContain("detached HEAD"); + expect(detachedResult.error).toContain("contains nested Git worktree"); + expect(await readFile(nestedRollbackFile, "utf8")).toBe("keep-rollback-nested"); + await expect(readFile(removeCallsFile, "utf8")).rejects.toMatchObject({ code: "ENOENT" }); + + // 3. Archive of repo A's worktree must preserve a nested linked worktree belonging to another repo B. + const otherRepo = await createRepo(path.join(root, "repo-b")); + const crossRepoOuter = await client.createWorkspace({ + source: { kind: "worktree", cwd: repository, branchName: "cross-repo-outer" }, + }); + expect(crossRepoOuter.error).toBeNull(); + const crossRepoOuterPath = crossRepoOuter.workspace!.workspaceDirectory; + const otherRepoNestedPath = path.join(crossRepoOuterPath, "repo-b-nested"); + git(otherRepo, ["worktree", "add", "-b", "other-nested", otherRepoNestedPath]); + const otherRepoDirtyFile = path.join(otherRepoNestedPath, "uncommitted.txt"); + await writeFile(otherRepoDirtyFile, "keep-repo-b"); + + const crossRepoArchived = await client.archiveWorkspace(crossRepoOuter.workspace!.id); + expect(crossRepoArchived.error).toBeNull(); + expect(await readFile(otherRepoDirtyFile, "utf8")).toBe("keep-repo-b"); + await expect(readFile(removeCallsFile, "utf8")).rejects.toMatchObject({ code: "ENOENT" }); + + const middle = await createRepo(path.join(root, "middle")); + git(middle, ["-c", "protocol.file.allow=always", "submodule", "add", otherRepo, "leaf"]); + git(middle, ["commit", "-am", "Add leaf submodule"]); + const managed = await client.createWorkspace({ + source: { kind: "worktree", cwd: repository, branchName: "nested-content" }, + }); + expect(managed.error).toBeNull(); + const checkout = managed.workspace!.workspaceDirectory; + await addNestedGitContent(checkout, otherRepo, middle); + + const archivedWithContent = await client.archiveWorkspace(managed.workspace!.id); + expect(archivedWithContent.error).toBeNull(); + expect(path.normalize((await readFile(removeCallsFile, "utf8")).trim())).toBe( + path.normalize(checkout), + ); + await expect(stat(checkout)).rejects.toMatchObject({ code: "ENOENT" }); + } finally { + await client.close(); + await daemon.close(); + await rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 }); + } +}, 60_000); diff --git a/packages/server/src/server/resolve-worktree-creation-intent.ts b/packages/server/src/server/resolve-worktree-creation-intent.ts index 011384a61e..749b8c77ff 100644 --- a/packages/server/src/server/resolve-worktree-creation-intent.ts +++ b/packages/server/src/server/resolve-worktree-creation-intent.ts @@ -1,10 +1,25 @@ import type { ForgeService, PullRequestCheckoutTarget } from "../services/forge-service.js"; import type { WorktreeCheckoutRef, WorktreeSource } from "../utils/worktree.js"; +import type { UntrustedWorkspaceSource } from "./workspace-automation-gate.js"; export type WorktreeCreationIntent = Exclude< WorktreeSource, { kind: "restore" | "restore-from-base" | "restore-commit" } ->; +> & { untrustedSource?: UntrustedWorkspaceSource }; + +export function worktreeUntrustedSource( + intent: WorktreeCreationIntent, +): UntrustedWorkspaceSource | undefined { + if (intent.kind === "checkout-change-request" && intent.headRepository) { + return { + kind: "change_request", + forge: intent.forge, + number: intent.changeRequestNumber, + headRepository: intent.headRepository, + }; + } + return intent.untrustedSource; +} export interface ResolveWorktreeCreationIntentInput { worktreeSlug?: string; @@ -156,7 +171,11 @@ async function fetchChangeRequestHead(params: { changeRequest: { number: number; forge?: string }; repoRoot: string; deps: ResolveWorktreeCreationIntentDeps; -}): Promise<{ baseBranch: string; startPoint: string }> { +}): Promise<{ + baseBranch: string; + startPoint: string; + untrustedSource?: UntrustedWorkspaceSource; +}> { const { input, changeRequest, repoRoot, deps } = params; assertCheckoutSourceMatchesResolvedForge(changeRequest, deps); const checkout = await resolvePrCheckoutIntent({ @@ -165,6 +184,7 @@ async function fetchChangeRequestHead(params: { repoRoot, deps, }); + const untrustedSource = worktreeUntrustedSource(checkout); const startPoint = `refs/paseo/change-requests/${changeRequest.number}`; const remote = await deps.fetchRef({ repoRoot, @@ -180,10 +200,10 @@ async function fetchChangeRequestHead(params: { sources: [{ remoteName: remote, remoteRef: `refs/heads/${baseName}` }], destination: baseBranch, }); - return { baseBranch, startPoint }; + return { baseBranch, startPoint, untrustedSource }; } catch { // Without the remote's copy, the base resolves as any base branch name does. - return { baseBranch: baseName, startPoint }; + return { baseBranch: baseName, startPoint, untrustedSource }; } } diff --git a/packages/server/src/server/session.test.ts b/packages/server/src/server/session.test.ts index c4b9cb818c..a3da96067e 100644 --- a/packages/server/src/server/session.test.ts +++ b/packages/server/src/server/session.test.ts @@ -529,6 +529,10 @@ test("routes plugin requests and releases its owned catalog subscription on clea return request; }, emit: () => {}, + hasWorktreeManager: () => false, + createWorktree: async () => null, + removeWorktree: async () => null, + restoreWorktree: async () => null, listPlugins: async () => [plugin], getLogs: () => [ { @@ -670,6 +674,10 @@ test("leaves out the client bundles a catalog request already holds", async () = const pluginRuntime: NonNullable = { before: async (_name, request) => request, emit: () => {}, + hasWorktreeManager: () => false, + createWorktree: async () => null, + removeWorktree: async () => null, + restoreWorktree: async () => null, listPlugins: async () => [], getLogs: () => [], installDirectory: async () => { diff --git a/packages/server/src/server/session.ts b/packages/server/src/server/session.ts index defab9bfd2..a3d5976508 100644 --- a/packages/server/src/server/session.ts +++ b/packages/server/src/server/session.ts @@ -113,6 +113,7 @@ import { assertWorkspaceAutomationAllowedForWorkspace, clearWorkspaceAutomationBlock, formatWorkspaceAutomationBlockedMessage, + isCheckoutUntrusted, } from "./workspace-automation-gate.js"; import { WorkspaceLabelError, @@ -246,7 +247,12 @@ import { matchesAgentUpdatesFilter, type AgentUpdatesService, } from "./session/agent-updates/agent-updates-service.js"; -import { expandTilde } from "../utils/path.js"; +import { + createRealpathAwarePathMatcher, + expandTilde, + isRealpathInsideRoot, + normalizePathForIdentity, +} from "../utils/path.js"; import { searchDirectoryEntries, WORKSPACE_SEARCH_HIDDEN_DIRECTORIES, @@ -287,7 +293,11 @@ import { handleWorkspaceSetupStatusRequest as handleWorkspaceSetupStatusRequestMessage, handleWorkspaceSetupRunRequest as handleWorkspaceSetupRunRequestMessage, } from "./worktree-session.js"; -import { archiveByScope, type ActiveWorkspaceRef } from "./workspace-archive-service.js"; +import { + archiveByScope, + resolveWorkspaceBackingPath, + type ActiveWorkspaceRef, +} from "./workspace-archive-service.js"; import { WorkspaceArchiveOperations, type WorkspaceArchiveUndoInput, @@ -529,6 +539,10 @@ export interface SessionOptions { wait: import("./plugins/lifecycle/index.js").PluginLifecycle["wait"]; before: import("./plugins/lifecycle/index.js").PluginLifecycle["before"]; emit: import("./plugins/lifecycle/index.js").PluginLifecycle["emit"]; + hasWorktreeManager: import("./plugins/runtime.js").PluginWorktreeManagerRuntime["hasWorktreeManager"]; + createWorktree: import("./plugins/runtime.js").PluginWorktreeManagerRuntime["createWorktree"]; + removeWorktree: import("./plugins/runtime.js").PluginWorktreeManagerRuntime["removeWorktree"]; + restoreWorktree: import("./plugins/runtime.js").PluginWorktreeManagerRuntime["restoreWorktree"]; listPlugins(): Promise; getLogs(pluginId: string): import("@getpaseo/protocol/messages").PluginLogEntry[]; installDirectory(input: { @@ -1034,12 +1048,34 @@ export class Session { this.workspaceRecovery = createWorkspaceRecoveryService({ paseoHome: this.paseoHome, worktreesRoot: this.worktreesRoot, + worktreeManagers: this.pluginRuntime, getWorkspace: (workspaceId) => this.workspaceRegistry.get(workspaceId), getProject: (projectId) => this.projectRegistry.get(projectId), isDirectory: (path) => this.filesystem.isDirectory(path), unarchiveWorkspace: async (workspace) => { await this.workspaceProvisioning.ensureWorkspaceRecordUnarchived(workspace); }, + isCheckoutUntrusted: (checkoutPath) => + isCheckoutUntrusted(this.workspaceRegistry, checkoutPath), + syncCheckoutWorktreeManager: async ({ + worktreeRoot, + worktreeManagerPluginId, + excludeWorkspaceId, + }) => { + const matchesCheckout = createRealpathAwarePathMatcher(worktreeRoot); + const workspaces = await this.workspaceRegistry.listAll(); + const timestamp = new Date().toISOString(); + for (const candidate of workspaces) { + if (candidate.workspaceId === excludeWorkspaceId) continue; + if (!matchesCheckout(candidate.worktreeRoot ?? candidate.cwd)) continue; + if ((candidate.worktreeManagerPluginId ?? null) === worktreeManagerPluginId) continue; + const { worktreeManagerPluginId: _previous, ...withoutManager } = candidate; + const updated: PersistedWorkspaceRecord = worktreeManagerPluginId + ? { ...withoutManager, worktreeManagerPluginId, updatedAt: timestamp } + : { ...withoutManager, updatedAt: timestamp }; + await this.workspaceRegistry.upsert(updated); + } + }, }); this.diffSession = new DiffSession(checkoutDiffManager.streams, this.sessionLogger); this.checkoutSession = new CheckoutSession({ @@ -1251,9 +1287,15 @@ export class Session { ), logger: this.sessionLogger, }); + this.workspaceArchiveOperations = resolveWorkspaceArchiveOperations(workspaceArchiveOperations); this.createAgentLifecycleDispatch = new CreateAgentLifecycleDispatch({ paseoHome: this.paseoHome, worktreesRoot: this.worktreesRoot, + worktreeManagers: this.pluginRuntime, + workspaceArchiveOperations: this.workspaceArchiveOperations, + getWorkspace: (workspaceId) => this.workspaceRegistry.get(workspaceId), + isCheckoutUntrusted: (checkoutPath) => + isCheckoutUntrusted(this.workspaceRegistry, checkoutPath), agentManager: this.agentManager, agentStorage: this.agentStorage, github: this.github, @@ -1292,7 +1334,6 @@ export class Session { }, ); this.workspaceSetupRuntime = resolveWorkspaceSetupRuntime(workspaceSetupRuntime); - this.workspaceArchiveOperations = resolveWorkspaceArchiveOperations(workspaceArchiveOperations); this.getDaemonTcpPort = getDaemonTcpPort ?? null; this.getDaemonTcpHost = getDaemonTcpHost ?? null; this.serviceProxyPublicBaseUrl = serviceProxyPublicBaseUrl ?? null; @@ -5782,11 +5823,14 @@ export class Session { { paseoHome: this.paseoHome, paseoWorktreesBaseRoot: this.worktreesRoot, + worktreeManagers: this.pluginRuntime, + workspaceArchiveOperations: this.workspaceArchiveOperations, github: this.github, workspaceGitService: this.workspaceGitService, agentManager: this.agentManager, agentStorage: this.agentStorage, findWorkspaceIdForCwd: (cwd) => this.findWorkspaceIdForCwd(cwd), + getWorkspace: (workspaceId) => this.workspaceRegistry.get(workspaceId), listActiveWorkspaces: () => this.listActiveWorkspaceRefs(), archiveWorkspaceRecord: (workspaceId, archivedAt) => this.archiveWorkspaceRecord(workspaceId, archivedAt), @@ -5798,6 +5842,8 @@ export class Session { clearWorkspaceArchiving: (workspaceIds) => this.clearWorkspaceArchiving(workspaceIds), killTerminalsForWorkspace: (workspaceId) => this.terminalController.killTerminalsForWorkspace(workspaceId), + isCheckoutUntrusted: (checkoutPath) => + isCheckoutUntrusted(this.workspaceRegistry, checkoutPath), sessionLogger: this.sessionLogger, }, msg, @@ -6503,9 +6549,60 @@ export class Session { }; } + private async withWorkspaceCheckout(workspaceId: string, run: () => Promise): Promise { + const workspace = await this.workspaceRegistry.get(workspaceId); + if (!workspace) { + return run(); + } + const checkoutPath = await resolveWorkspaceBackingPath(workspace, { + paseoHome: this.paseoHome, + paseoWorktreesBaseRoot: this.worktreesRoot, + }); + return this.workspaceArchiveOperations.withCheckout(checkoutPath, run); + } + + private async withCheckoutForDirectory(cwd: string, run: () => Promise): Promise { + const normalizedCwd = resolve(cwd); + const matchesCwd = createRealpathAwarePathMatcher(normalizedCwd); + const workspaces = await this.workspaceRegistry.listAll(); + let matchingWorkspace = workspaces.find((workspace) => matchesCwd(workspace.cwd)); + if (!matchingWorkspace) { + let bestDepth = -1; + for (const workspace of workspaces) { + if ( + workspace.worktreeRoot !== null && + isRealpathInsideRoot(workspace.worktreeRoot, normalizedCwd) + ) { + const depth = normalizePathForIdentity(workspace.worktreeRoot).length; + if (depth > bestDepth) { + bestDepth = depth; + matchingWorkspace = workspace; + } + } + } + } + let checkoutPath = normalizedCwd; + if (matchingWorkspace) { + checkoutPath = await resolveWorkspaceBackingPath(matchingWorkspace, { + paseoHome: this.paseoHome, + paseoWorktreesBaseRoot: this.worktreesRoot, + }); + } else { + const checkout = await this.workspaceGitService.getCheckout(normalizedCwd); + if (checkout.isGit && checkout.worktreeRoot) { + checkoutPath = resolve(checkout.worktreeRoot); + } + } + return this.workspaceArchiveOperations.withCheckout(checkoutPath, run); + } + private async restoreWorkspaceAndEmit(workspaceId: string): Promise { - await this.workspaceRecovery.restore(workspaceId); - await this.publishRecoveredWorkspace(workspaceId); + await this.workspaceArchiveOperations.restore(workspaceId, () => + this.withWorkspaceCheckout(workspaceId, async () => { + await this.workspaceRecovery.restore(workspaceId); + await this.publishRecoveredWorkspace(workspaceId); + }), + ); } private async publishRecoveredWorkspace(workspaceId: string): Promise { @@ -6552,6 +6649,7 @@ export class Session { ): Promise { const result = await createPaseoWorktree(input, { lifecycle: this.pluginRuntime, + worktreeManagers: this.pluginRuntime, github: this.github, ...(options?.resolveDefaultBranch ? { resolveDefaultBranch: options.resolveDefaultBranch } @@ -6582,6 +6680,8 @@ export class Session { worktreeRoot: workspace.worktreeRoot, isPaseoOwnedWorktree: workspace.isPaseoOwnedWorktree, mainRepoRoot: workspace.mainRepoRoot, + worktreeManagerPluginId: workspace.worktreeManagerPluginId, + untrustedSource: workspace.untrustedSource, })); } @@ -7436,24 +7536,29 @@ export class Session { } const cwd = expandTilde(request.source.path); - const directoryExists = await this.filesystem.isDirectory(cwd).catch(() => false); - if (!directoryExists) { - throw new SessionRequestError("directory_not_found", `Directory not found: ${cwd}`); - } - const explicitTitle = request.title?.trim() || null; const promptTitle = resolveFirstAgentPromptTitle(request.firstAgentContext); - const workspace = await this.workspaceProvisioning.createWorkspaceForDirectory( - cwd, - explicitTitle ?? promptTitle, - request.source.projectId, - { - expectsInitialAgent: Boolean(request.firstAgentContext), - workspaceId, - metadata: request.metadata, - ...(await this.workspaceBackgroundIntent(request.background, request.callerAgentId)), - }, + const backgroundIntent = await this.workspaceBackgroundIntent( + request.background, + request.callerAgentId, ); + const workspace = await this.withCheckoutForDirectory(cwd, async () => { + const directoryExists = await this.filesystem.isDirectory(cwd).catch(() => false); + if (!directoryExists) { + throw new SessionRequestError("directory_not_found", `Directory not found: ${cwd}`); + } + return this.workspaceProvisioning.createWorkspaceForDirectory( + cwd, + explicitTitle ?? promptTitle, + request.source.projectId, + { + expectsInitialAgent: Boolean(request.firstAgentContext), + workspaceId, + metadata: request.metadata, + ...backgroundIntent, + }, + ); + }); await this.syncWorkspaceGitObserverForWorkspace(workspace); const descriptor = await this.describeWorkspaceRecord(workspace); await this.emitCreatedWorkspaceUpdate( @@ -7535,34 +7640,41 @@ export class Session { ): Promise { const requestedCwd = request.cwd; const cwd = expandTilde(requestedCwd); - const directoryExists = await this.filesystem.isDirectory(cwd).catch(() => false); - if (!directoryExists) { - this.sessionLogger.info( - { requestedCwd, resolvedCwd: cwd, reason: "directory_not_found" }, - "Open project rejected", - ); - this.emit({ - type: "open_project_response", - payload: { - requestId: request.requestId, - workspace: null, - error: `Directory not found: ${cwd}`, - errorCode: "directory_not_found", - }, - }); - return; - } try { - const projectsBefore = new Map(); - for (const project of await this.projectRegistry.list()) { - projectsBefore.set(project.projectId, project); + const opened = await this.withCheckoutForDirectory(cwd, async () => { + const directoryExists = await this.filesystem.isDirectory(cwd).catch(() => false); + if (!directoryExists) { + return null; + } + const projectsBefore = new Map(); + for (const project of await this.projectRegistry.list()) { + projectsBefore.set(project.projectId, project); + } + const workspacesBefore = new Map(); + for (const workspaceRecord of await this.workspaceRegistry.listActive()) { + workspacesBefore.set(workspaceRecord.workspaceId, workspaceRecord); + } + const workspace = await this.workspaceProvisioning.findOrCreateWorkspaceForDirectory(cwd); + return { workspace, projectsBefore, workspacesBefore }; + }); + if (!opened) { + this.sessionLogger.info( + { requestedCwd, resolvedCwd: cwd, reason: "directory_not_found" }, + "Open project rejected", + ); + this.emit({ + type: "open_project_response", + payload: { + requestId: request.requestId, + workspace: null, + error: `Directory not found: ${cwd}`, + errorCode: "directory_not_found", + }, + }); + return; } - const workspacesBefore = new Map(); - for (const workspaceRecord of await this.workspaceRegistry.listActive()) { - workspacesBefore.set(workspaceRecord.workspaceId, workspaceRecord); - } - const workspace = await this.workspaceProvisioning.findOrCreateWorkspaceForDirectory(cwd); + const { workspace, projectsBefore, workspacesBefore } = opened; const project = await this.projectRegistry.get(workspace.projectId); await this.syncWorkspaceGitObserverForWorkspace(workspace); const descriptor = await this.describeWorkspaceRecord(workspace); @@ -8130,6 +8242,8 @@ export class Session { { paseoHome: this.paseoHome, paseoWorktreesBaseRoot: this.worktreesRoot, + worktreeManagers: this.pluginRuntime, + workspaceArchiveOperations: this.workspaceArchiveOperations, github: this.github, workspaceGitService: this.workspaceGitService, agentManager: this.agentManager, @@ -8146,6 +8260,8 @@ export class Session { clearWorkspaceArchiving: (workspaceIds) => this.clearWorkspaceArchiving(workspaceIds), assertWorkspaceAutomationAllowed: (workspaceId) => assertWorkspaceAutomationAllowedForWorkspace(this.workspaceRegistry, workspaceId), + isCheckoutUntrusted: (checkoutPath) => + isCheckoutUntrusted(this.workspaceRegistry, checkoutPath), killTerminalsForWorkspace: (workspaceId) => this.terminalController.killTerminalsForWorkspace(workspaceId), stopWorkspaceSetup: (workspaceId) => this.workspaceSetupRuntime.stop(workspaceId), @@ -8208,7 +8324,9 @@ export class Session { ): Promise { try { await this.workspaceArchiveOperations.undo(request.workspaceId, (input) => - this.restoreArchivedWorkspaceAndAgents(request.workspaceId, input), + this.withWorkspaceCheckout(request.workspaceId, () => + this.restoreArchivedWorkspaceAndAgents(request.workspaceId, input), + ), ); this.emit({ type: "workspace.archive.undo.response", diff --git a/packages/server/src/server/session/workspace-provisioning/workspace-provisioning-service.ts b/packages/server/src/server/session/workspace-provisioning/workspace-provisioning-service.ts index cec8850e37..6727df1025 100644 --- a/packages/server/src/server/session/workspace-provisioning/workspace-provisioning-service.ts +++ b/packages/server/src/server/session/workspace-provisioning/workspace-provisioning-service.ts @@ -52,6 +52,7 @@ export interface CreateWorktreeWorkspaceInput { worktreeRoot: string; branch: string | null; baseBranch: string | null; + worktreeManagerPluginId?: string | null; title: string | null; metadata?: Record; expectsInitialAgent?: boolean; @@ -273,14 +274,23 @@ export function createWorkspaceProvisioningService(deps: { checkout.isGit && checkout.isPaseoOwnedWorktree ? await readPaseoWorktreeMetadata(checkout.worktreeRoot ?? normalizedCwd) : null; + const checkoutRoot = checkout.worktreeRoot ?? normalizedCwd; + const matchesCheckout = createRealpathAwarePathMatcher(checkoutRoot); + const inheritedUntrustedSource = (await workspaceRegistry.listAll()).find( + (candidate) => + Boolean(candidate.untrustedSource) && + matchesCheckout(candidate.worktreeRoot ?? candidate.cwd), + )?.untrustedSource; const timestamp = new Date().toISOString(); const workspace = createPersistedWorkspaceRecord({ workspaceId: context?.workspaceId ?? generateWorkspaceId(), projectId: project.projectId, ...initialWorkspacePlacement({ source: "checkout", cwd: normalizedCwd, checkout }), baseBranch: baseMetadata?.baseRef ?? baseMetadata?.baseRefName ?? null, + worktreeManagerPluginId: baseMetadata?.worktreeManagerPluginId ?? null, title: title?.trim() || null, metadata: context?.metadata, + ...(inheritedUntrustedSource ? { untrustedSource: inheritedUntrustedSource } : {}), createdAt: timestamp, updatedAt: timestamp, ...(await resolveCreationMetadata(context)), @@ -320,6 +330,7 @@ export function createWorkspaceProvisioningService(deps: { baseBranch: input.baseBranch, mainRepoRoot: repoRoot, }), + worktreeManagerPluginId: input.worktreeManagerPluginId ?? null, title: input.title, metadata: input.metadata, createdAt: timestamp, diff --git a/packages/server/src/server/session/workspace-recovery/workspace-recovery-service.ts b/packages/server/src/server/session/workspace-recovery/workspace-recovery-service.ts index 38c95cb421..0a0786c706 100644 --- a/packages/server/src/server/session/workspace-recovery/workspace-recovery-service.ts +++ b/packages/server/src/server/session/workspace-recovery/workspace-recovery-service.ts @@ -9,8 +9,11 @@ import { isPaseoOwnedWorktreeCwd, mapWorkspaceCwdToWorktree, rollbackCreatedPaseoWorktree, + runPluginWorktreeManagerCheckout, type WorktreeSource, } from "../../../utils/worktree.js"; +import type { PluginWorktreeManagerRuntime } from "../../plugins/runtime.js"; +import type { PluginWorktreeRestoreTarget } from "@getpaseo/plugin/server"; import { WorktreeRequestError, toWorktreeRequestError } from "../../worktree-errors.js"; import { resolveWorkspaceDisplayName, @@ -64,10 +67,20 @@ type UnavailableRecoveryState = Extract; getWorkspace: (workspaceId: string) => Promise; getProject: (projectId: string) => Promise; isDirectory: (path: string) => Promise; unarchiveWorkspace: (workspace: PersistedWorkspaceRecord) => Promise; + isCheckoutUntrusted?: (checkoutPath: string) => Promise; + syncCheckoutWorktreeManager?: (input: { + worktreeRoot: string; + worktreeManagerPluginId: string | null; + excludeWorkspaceId: string; + }) => Promise; }): WorkspaceRecoveryService { async function resolveRecovery( workspaceId: string, @@ -140,17 +153,32 @@ export function createWorkspaceRecoveryService(deps: { throw new Error(resolved.message); } + let workspaceToUnarchive = resolved.workspace; + let recreated: { worktreePath: string; pluginId: string | null } | null = null; if (resolved.kind === "restore") { - await recreateArchivedWorktree(resolved.workspace, resolved.sourceRepoRoot); + recreated = await recreateArchivedWorktree(resolved.workspace, resolved.sourceRepoRoot); + if ((resolved.workspace.worktreeManagerPluginId ?? null) !== recreated.pluginId) { + const { worktreeManagerPluginId: _previous, ...withoutManager } = resolved.workspace; + workspaceToUnarchive = recreated.pluginId + ? { ...withoutManager, worktreeManagerPluginId: recreated.pluginId } + : withoutManager; + } + } + await deps.unarchiveWorkspace(workspaceToUnarchive); + if (recreated) { + await deps.syncCheckoutWorktreeManager?.({ + worktreeRoot: recreated.worktreePath, + worktreeManagerPluginId: recreated.pluginId, + excludeWorkspaceId: workspaceId, + }); } - await deps.unarchiveWorkspace(resolved.workspace); return { workspaceId, action: resolved.kind }; } async function recreateArchivedWorktree( workspace: PersistedWorkspaceRecord, sourceRepoRoot: string, - ): Promise { + ): Promise<{ worktreePath: string; pluginId: string | null }> { let source: WorktreeSource; const checkout = parseWorkspaceHead(workspace); if (checkout.kind === "branch") { @@ -194,18 +222,22 @@ export function createWorkspaceRecoveryService(deps: { hasRecordedWorktreePath = ownership.allowed; } + const untrusted = + Boolean(workspace.untrustedSource) || + Boolean(await deps.isCheckoutUntrusted?.(previousWorktreePath)); let recreatedWorktreePath: string; + let restoredByPluginId: string | null = null; try { - const result = await createWorktree({ - cwd: sourceRepoRoot, - worktreeSlug: basename(previousWorktreePath), + const restored = await recreateWorktreeCheckout({ + workspace, + sourceRepoRoot, source, - - paseoHome: deps.paseoHome, - worktreesRoot: deps.worktreesRoot, - ...(hasRecordedWorktreePath ? { worktreePath: previousWorktreePath } : {}), + previousWorktreePath, + hasRecordedWorktreePath, + untrusted, }); - recreatedWorktreePath = result.worktreePath; + recreatedWorktreePath = restored.worktreePath; + restoredByPluginId = restored.pluginId; } catch (error) { throw toWorktreeRequestError(error); } @@ -236,15 +268,98 @@ export function createWorkspaceRecoveryService(deps: { teardownCwds: [], paseoHome: deps.paseoHome, worktreesBaseRoot: deps.worktreesRoot, + worktreeManagers: deps.worktreeManagers, + worktreeManagerPluginId: restoredByPluginId, + removeReason: "rollback", + untrusted, }, error, ); } + return { worktreePath: recreatedWorktreePath, pluginId: restoredByPluginId }; + } + + async function recreateWorktreeCheckout(options: { + workspace: PersistedWorkspaceRecord; + sourceRepoRoot: string; + source: Extract; + previousWorktreePath: string; + hasRecordedWorktreePath: boolean; + untrusted: boolean; + }): Promise<{ worktreePath: string; pluginId: string | null }> { + const { + workspace, + sourceRepoRoot, + source, + previousWorktreePath, + hasRecordedWorktreePath, + untrusted, + } = options; + const managerPluginId = workspace.worktreeManagerPluginId; + if (managerPluginId && hasRecordedWorktreePath && deps.worktreeManagers) { + const adopted = await runPluginWorktreeManagerCheckout({ + cwd: sourceRepoRoot, + source, + operation: "restore", + preferredPluginId: managerPluginId, + untrusted, + paseoHome: deps.paseoHome, + worktreesBaseRoot: deps.worktreesRoot, + worktreeManagers: deps.worktreeManagers, + run: () => + deps.worktreeManagers!.restoreWorktree( + { + repoRoot: sourceRepoRoot, + path: previousWorktreePath, + target: restoreTargetFromWorktreeSource(source), + baseRef: workspace.baseBranch, + untrusted, + }, + { preferredPluginId: managerPluginId }, + ), + verifyValidatedPath: (validatedPath, pluginId) => { + if (!createRealpathAwarePathMatcher(previousWorktreePath)(validatedPath)) { + throw new WorktreeRequestError({ + code: "unknown", + message: `Plugin ${pluginId} restored worktree to ${validatedPath}, expected ${previousWorktreePath}`, + }); + } + }, + }); + if (adopted) { + return { + worktreePath: adopted.worktreePath, + pluginId: adopted.worktreeManagerPluginId ?? managerPluginId, + }; + } + } + + const result = await createWorktree({ + cwd: sourceRepoRoot, + worktreeSlug: basename(previousWorktreePath), + source, + paseoHome: deps.paseoHome, + worktreesRoot: deps.worktreesRoot, + ...(hasRecordedWorktreePath ? { worktreePath: previousWorktreePath } : {}), + }); + return { worktreePath: result.worktreePath, pluginId: null }; } return { inspect, restore }; } +function restoreTargetFromWorktreeSource( + source: Extract, +): PluginWorktreeRestoreTarget { + if (source.kind === "restore") { + return { type: "branch", branch: source.branchName }; + } + if (source.kind === "restore-commit") { + return { type: "commit", commit: source.commit }; + } + return { type: "from-base", branch: source.branchName, baseRef: source.baseRef }; +} + async function resolveRecoveryBase(repoRoot: string, recordedBase: string | null): Promise { if (recordedBase) { try { diff --git a/packages/server/src/server/websocket-server.ts b/packages/server/src/server/websocket-server.ts index 7aabed0d23..4a683907a4 100644 --- a/packages/server/src/server/websocket-server.ts +++ b/packages/server/src/server/websocket-server.ts @@ -70,6 +70,12 @@ import type { HubRelationshipManagement } from "./hub/relationship-controller.js import { WorkspaceSetupObservation } from "./workspace-setup-observation.js"; import { WorkspaceSetupRuntime } from "./workspace-setup-runtime.js"; import { WorkspaceArchiveOperations } from "./workspace-archive-operations.js"; + +function resolveWorkspaceArchiveOperations( + operations: WorkspaceArchiveOperations | undefined, +): WorkspaceArchiveOperations { + return operations ?? new WorkspaceArchiveOperations(); +} import type { HubExecutionAgents } from "./hub/daemon-executions.js"; import type { AgentProvider } from "./agent/agent-sdk-types.js"; import { ProviderSnapshotManager } from "./agent/provider-snapshot-manager.js"; @@ -618,9 +624,9 @@ export class VoiceAssistantWebSocketServer { private readonly voiceCallerContexts = new Map(); private readonly workspaceSetupObservation = new WorkspaceSetupObservation(); private readonly workspaceSetupRuntime: WorkspaceSetupRuntime; - // One lane per workspace across every connection, so an undo from any client can cancel an - // archive another connection started. - private readonly workspaceArchiveOperations = new WorkspaceArchiveOperations(); + // One lane per workspace and per checkout across the daemon, so archive, undo, and restore + // from any client or background caller coordinate through one boundary. + private readonly workspaceArchiveOperations: WorkspaceArchiveOperations; private readonly providerSnapshotManager: ProviderSnapshotManager; private onLifecycleIntent!: ((intent: SessionLifecycleIntent) => void) | null; private onBranchChanged!: @@ -711,9 +717,11 @@ export class VoiceAssistantWebSocketServer { pluginRuntime?: SessionOptions["pluginRuntime"], orchestrationSkills?: SessionOptions["orchestrationSkills"], workspaceLabelService?: WorkspaceLabelService, + workspaceArchiveOperations?: WorkspaceArchiveOperations, ) { this.logger = logger.child({ module: "websocket-server" }); this.workspaceSetupRuntime = workspaceSetupRuntime; + this.workspaceArchiveOperations = resolveWorkspaceArchiveOperations(workspaceArchiveOperations); this.advertiseDaemonStatusRpc = wsConfig.daemonStatusRpc !== false; this.advertiseRelayConfig = wsConfig.relayConfig !== false; this.connectionLifecycle = wsConfig.startPaused === true ? "starting" : "accepting"; diff --git a/packages/server/src/server/workspace-archive-operations.test.ts b/packages/server/src/server/workspace-archive-operations.test.ts index 4c6264d484..b3bc8cb38c 100644 --- a/packages/server/src/server/workspace-archive-operations.test.ts +++ b/packages/server/src/server/workspace-archive-operations.test.ts @@ -273,4 +273,146 @@ describe("WorkspaceArchiveOperations", () => { kind: "archived", }); }); + + test("concurrent restores join the in-flight restore and share its outcome", async () => { + const operations = new WorkspaceArchiveOperations(); + let release!: () => void; + const gate = new Promise((resolve) => { + release = resolve; + }); + let calls = 0; + + const first = operations.restore("ws", async () => { + calls += 1; + await gate; + throw new Error("restore setup failed"); + }); + const second = operations.restore("ws", async () => { + calls += 1; + }); + + release(); + await expect(first).rejects.toThrow("restore setup failed"); + await expect(second).rejects.toThrow("restore setup failed"); + expect(calls).toBe(1); + + await operations.restore("ws", async () => { + calls += 1; + }); + expect(calls).toBe(2); + }); + + test("undo after a restore queued behind a running archive still aborts the archive and shares the undo outcome", async () => { + const operations = new WorkspaceArchiveOperations(); + const archive = parkedArchive(["agent-a"]); + const order: string[] = []; + let restoreCalls = 0; + + const archiveDone = operations.archive("ws", async (signal) => { + try { + return await archive.run(signal); + } finally { + order.push("archive stopped"); + } + }); + await archive.started; + + const restoreDone = operations.restore("ws", async () => { + restoreCalls += 1; + order.push("restore"); + }); + expect(archive.aborted).toBe(false); + + const undoDone = operations.undo("ws", async ({ archivedAt }) => { + order.push(`undo:${archivedAt}`); + }); + expect(archive.aborted).toBe(true); + + archive.release(); + await expect(archiveDone).resolves.toEqual({ kind: "canceled", archivedAt: "stamp" }); + await Promise.all([restoreDone, undoDone]); + + expect(restoreCalls).toBe(0); + expect(order).toEqual(["archive stopped", "undo:stamp"]); + }); + + test("restore queued behind a running archive waits without aborting it when no undo arrives", async () => { + const operations = new WorkspaceArchiveOperations(); + const archive = parkedArchive(["agent-a"]); + const order: string[] = []; + + const archiveDone = operations.archive("ws", async (signal) => { + const result = await archive.run(signal); + order.push("archived"); + return result; + }); + await archive.started; + + const restoreDone = operations.restore("ws", async () => { + order.push("restored"); + }); + expect(archive.aborted).toBe(false); + + archive.release(); + await expect(archiveDone).resolves.toMatchObject({ kind: "archived" }); + await restoreDone; + expect(order).toEqual(["archived", "restored"]); + }); + + test("undo after restore has already started joins the running restore", async () => { + const operations = new WorkspaceArchiveOperations(); + await operations.archive("ws", async () => archived(["agent-a"])); + + const restoreGate = deferred(); + let restoreCalls = 0; + let undoCalls = 0; + const restoreDone = operations.restore("ws", async () => { + restoreCalls += 1; + await restoreGate.promise; + }); + // Flush microtask so restore has moved past any settled archive check. + await Promise.resolve(); + + const undoDone = operations.undo("ws", async () => { + undoCalls += 1; + }); + restoreGate.resolve(); + await Promise.all([restoreDone, undoDone]); + + expect(restoreCalls).toBe(1); + expect(undoCalls).toBe(0); + }); + + test("withCheckout serializes operations on the same checkout path while allowing independent checkouts in parallel", async () => { + const operations = new WorkspaceArchiveOperations(); + const firstGate = deferred(); + const firstStarted = deferred(); + const order: string[] = []; + + const first = operations.withCheckout("/tmp/paseo-checkout-a", async () => { + order.push("a1-start"); + firstStarted.resolve(); + await firstGate.promise; + order.push("a1-end"); + return "first"; + }); + await firstStarted.promise; + + const second = operations.withCheckout("/tmp/paseo-checkout-a/", async () => { + order.push("a2"); + return "second"; + }); + const other = operations.withCheckout("/tmp/paseo-checkout-b", async () => { + order.push("b"); + return "other"; + }); + + await expect(other).resolves.toBe("other"); + expect(order).toEqual(["a1-start", "b"]); + + firstGate.resolve(); + await expect(first).resolves.toBe("first"); + await expect(second).resolves.toBe("second"); + expect(order).toEqual(["a1-start", "b", "a1-end", "a2"]); + }); }); diff --git a/packages/server/src/server/workspace-archive-operations.ts b/packages/server/src/server/workspace-archive-operations.ts index 6083b07cc5..44ba6f4caf 100644 --- a/packages/server/src/server/workspace-archive-operations.ts +++ b/packages/server/src/server/workspace-archive-operations.ts @@ -1,3 +1,6 @@ +import { resolve } from "node:path"; + +import { normalizePathForIdentity } from "../utils/path.js"; import { type ArchiveResult, WorkspaceArchiveCanceledError } from "./workspace-archive-service.js"; export type WorkspaceArchiveOutcome = @@ -8,23 +11,42 @@ export interface WorkspaceArchiveUndoInput { archivedAt?: string; } +interface PendingArchive { + controller: AbortController; + done: Promise; +} + type LaneEntry = | { kind: "archiving"; controller: AbortController; done: Promise } + | { + kind: "restoring"; + pendingArchive: PendingArchive | null; + supersededBy: Promise | null; + done: Promise; + } | { kind: "undoing"; done: Promise }; /** - * One lane per workspace for archive and its undo, shared by every session on the daemon. + * Daemon-wide coordinator for workspace archive, undo, and restore operations. * + * Per-workspace lanes: * - An archive while one runs joins it. - * - An undo while an archive runs aborts it, waits for it to stop, then restores. - * - An archive while an undo runs waits for the undo, then archives. - * - An undo while an undo runs joins it. + * - An undo while an archive runs (including when a restore queued behind it) aborts the archive, + * waits for it to stop, then restores. + * - A restore while an archive runs waits for the archive without aborting it, then restores. + * - An archive while an undo or restore runs waits for it, then archives. + * - A duplicate undo or restore while recovery runs joins it. * - * Each call claims the lane synchronously, so whichever request arrives last decides the - * workspace's final state no matter how the earlier work interleaves. + * Per-checkout gates: + * - Any archive or recovery mutating the same backing checkout directory (including CLI worktree + * archives covering multiple workspace records, background auto-archives, and sibling workspaces + * sharing one checkout) serializes through `withCheckout` so a restore cannot inspect or unarchive + * a checkout while an archive is still deleting it. + * - Lock order is strictly workspace lane -> checkout gate, preventing deadlocks. */ export class WorkspaceArchiveOperations { private readonly lanes = new Map(); + private readonly checkoutGates = new Map>(); archive( workspaceId: string, @@ -57,16 +79,92 @@ export class WorkspaceArchiveOperations { if (current?.kind === "undoing") { return current.done; } - current?.controller.abort(); + if (current?.kind === "restoring" && current.pendingArchive === null) { + return current.done; + } + let pendingArchive: PendingArchive | null = null; + if (current?.kind === "archiving") { + pendingArchive = { controller: current.controller, done: current.done }; + } else if (current?.kind === "restoring") { + pendingArchive = current.pendingArchive; + } + pendingArchive?.controller.abort(); const done = (async () => { - const outcome = - current?.kind === "archiving" ? await current.done.catch(() => undefined) : undefined; + const outcome = pendingArchive ? await pendingArchive.done.catch(() => undefined) : undefined; await restore({ archivedAt: outcome?.kind === "canceled" ? outcome.archivedAt : undefined }); })(); + if (current?.kind === "restoring") { + current.supersededBy = done; + } this.claim(workspaceId, { kind: "undoing", done }); return done; } + /** + * Run a workspace recovery restore on the per-workspace lane so concurrent restores + * across daemon sessions share one outcome and wait for checkout + validation to settle. + * When queued behind an in-flight archive, the archive stays cancelable by a subsequent undo. + */ + restore(workspaceId: string, run: () => Promise): Promise { + const current = this.lanes.get(workspaceId); + if (current?.kind === "undoing" || current?.kind === "restoring") { + return current.done; + } + const pendingArchive: PendingArchive | null = + current?.kind === "archiving" ? { controller: current.controller, done: current.done } : null; + const entry: Extract = { + kind: "restoring", + pendingArchive, + supersededBy: null, + done: Promise.resolve(), + }; + entry.done = (async () => { + if (pendingArchive) { + await settled(pendingArchive.done); + entry.pendingArchive = null; + if (entry.supersededBy) { + await entry.supersededBy; + return; + } + } else { + await settled(current?.done); + } + await run(); + })(); + this.claim(workspaceId, entry); + return entry.done; + } + + /** + * Serialize mutations touching the same backing checkout directory across all daemon callers + * (UI archive, CLI worktree archive, background auto-archive, undo, and recovery restore). + */ + withCheckout(checkoutPath: string, run: () => Promise): Promise { + const key = normalizePathForIdentity(resolve(checkoutPath)); + const previous = this.checkoutGates.get(key); + let release!: () => void; + const current = new Promise((resolveGate) => { + release = resolveGate; + }); + const gate = previous ? previous.then(() => current) : current; + this.checkoutGates.set(key, gate); + const cleanup = () => { + if (this.checkoutGates.get(key) === gate) { + this.checkoutGates.delete(key); + } + }; + void gate.then(cleanup, cleanup); + + return (async () => { + await settled(previous); + try { + return await run(); + } finally { + release(); + } + })(); + } + private claim(workspaceId: string, entry: LaneEntry): void { this.lanes.set(workspaceId, entry); const release = () => { diff --git a/packages/server/src/server/workspace-archive-service.test.ts b/packages/server/src/server/workspace-archive-service.test.ts index b5d656bf7c..c93dffa589 100644 --- a/packages/server/src/server/workspace-archive-service.test.ts +++ b/packages/server/src/server/workspace-archive-service.test.ts @@ -1290,3 +1290,59 @@ test("a canceled archive with no matching agents leaves earlier closed agents ar }); expect(restored).toEqual([]); }); + +test.each(["outer", "inner"])( + "archive keeps nested workspace when %s is managed", + async (managed) => { + const { repoDir } = createGitRepo(); + const rootDir = path.dirname(repoDir); + const outerPath = path.join(rootDir, "worktrees", "team"); + const innerPath = path.join(outerPath, "topic"); + mkdirSync(path.dirname(outerPath), { recursive: true }); + execFileSync("git", ["worktree", "add", "-b", "team", outerPath], { + cwd: repoDir, + stdio: "pipe", + }); + execFileSync("git", ["worktree", "add", "-b", "topic", innerPath], { + cwd: repoDir, + stdio: "pipe", + }); + const dirtyFile = path.join(innerPath, "uncommitted.txt"); + writeFileSync(dirtyFile, "keep-inner"); + + const activeWorkspaces: ActiveWorkspaceRef[] = [ + { + workspaceId: "ws-team", + cwd: outerPath, + kind: "worktree", + worktreeRoot: outerPath, + worktreeManagerPluginId: managed === "outer" ? "manager" : null, + isPaseoOwnedWorktree: true, + mainRepoRoot: repoDir, + }, + { + workspaceId: "ws-topic", + cwd: innerPath, + kind: "worktree", + worktreeRoot: innerPath, + worktreeManagerPluginId: managed === "inner" ? "manager" : null, + isPaseoOwnedWorktree: true, + mainRepoRoot: repoDir, + }, + ]; + const deps = createArchiveDeps({ + paseoHome: rootDir, + activeWorkspaces, + }); + + const result = await archiveByScope(deps, { + scope: { kind: "workspace", workspaceId: "ws-team" }, + requestId: "archive-outer", + }); + + expect(result.archivedWorkspaceIds).toEqual(["ws-team"]); + expect(result.removedDirectory).toBe(false); + expect(existsSync(outerPath)).toBe(true); + expect(readFileSync(dirtyFile, "utf8")).toBe("keep-inner"); + }, +); diff --git a/packages/server/src/server/workspace-archive-service.ts b/packages/server/src/server/workspace-archive-service.ts index 5f6fb473e7..d5c5299106 100644 --- a/packages/server/src/server/workspace-archive-service.ts +++ b/packages/server/src/server/workspace-archive-service.ts @@ -19,19 +19,26 @@ import type { WorkspaceArchiveContext, WorkspaceRegistry, } from "./workspace-registry.js"; -import { createRealpathAwarePathMatcher } from "../utils/path.js"; +import { createRealpathAwarePathMatcher, isRealpathInsideRoot } from "../utils/path.js"; import { runWithGitCommandPriority } from "../utils/run-git-command.js"; import { WorkspaceAutomationBlockedError } from "./workspace-automation-gate.js"; +import type { PluginWorktreeManagerRuntime } from "./plugins/runtime.js"; +import type { WorkspaceArchiveOperations } from "./workspace-archive-operations.js"; export type ActiveWorkspaceRef = Pick< PersistedWorkspaceRecord, "workspaceId" | "cwd" | "kind" | "worktreeRoot" | "isPaseoOwnedWorktree" | "mainRepoRoot" ->; +> & { + worktreeManagerPluginId?: string | null; + untrustedSource?: PersistedWorkspaceRecord["untrustedSource"]; +}; export interface ArchiveDependencies { paseoHome?: string; // Base directory that may hold worktrees across repositories. paseoWorktreesBaseRoot?: string; + worktreeManagers?: Pick; + workspaceArchiveOperations?: Pick; github: ForgeService; workspaceGitService: Pick; agentManager: Pick; @@ -53,6 +60,7 @@ export interface ArchiveDependencies { killTerminalsForWorkspace: (workspaceId: string) => Promise; stopWorkspaceSetup?: (workspaceId: string) => Promise; assertWorkspaceAutomationAllowed?: (workspaceId: string) => Promise; + isCheckoutUntrusted?: (checkoutPath: string) => Promise; sessionLogger?: Logger; } @@ -119,6 +127,8 @@ interface BackingDirectory { registryProven: boolean; mainRepoRoot: string | null; paseoWorktreesRoot: string | null; + worktreeManagerPluginId: string | null; + untrusted: boolean; } interface ArchiveTarget { @@ -142,6 +152,13 @@ export async function resolveWorkspaceIdAtPath( return dependencies.findWorkspaceIdForCwd(targetPath); } +export async function resolveWorkspaceBackingPath( + workspace: ActiveWorkspaceRef, + dependencies: Pick, +): Promise { + return (await resolveWorkspaceBackingDirectory(workspace, dependencies)).path; +} + // Resolves the in-scope record set, tears each down // (agents + terminals + record), then removes the backing directory iff it is // Paseo-owned AND no active workspace still references it. @@ -164,69 +181,98 @@ async function archiveByScopeWithPriority( }; checkpoint(); - const target = await resolveArchiveTarget(dependencies, request.scope); - const targetWorkspaceIds = target.workspaceIds; + const runArchive = async (): Promise => { + checkpoint(); + const target = await resolveArchiveTarget(dependencies, request.scope); + const targetWorkspaceIds = target.workspaceIds; - await stopWorkspaceSetups(dependencies, target.setupWorkspaceIds, request.requestId); - checkpoint(); + await stopWorkspaceSetups(dependencies, target.setupWorkspaceIds, request.requestId); + checkpoint(); - if (targetWorkspaceIds.length > 0) { - dependencies.markWorkspaceArchiving(targetWorkspaceIds, new Date().toISOString()); - } - - let removedDirectory = false; - let directoryLeftBehind: ArchiveResult["directoryLeftBehind"]; - - try { if (targetWorkspaceIds.length > 0) { - await dependencies.emitWorkspaceUpdatesForWorkspaceIds(targetWorkspaceIds); + dependencies.markWorkspaceArchiving(targetWorkspaceIds, new Date().toISOString()); } - checkpoint(); - const { archivedAgents, archivedWorkspaceIds } = await archiveTargetRecords( - dependencies, - targetWorkspaceIds, - { requestId: request.requestId, checkpoint, archivedAt }, - ); - checkpoint(); + let removedDirectory = false; + let directoryLeftBehind: ArchiveResult["directoryLeftBehind"]; - if (target.backing?.mainRepoRoot) { - try { - await dependencies.workspaceGitService.getSnapshot(target.backing.mainRepoRoot, { - force: true, - reason: "archive-worktree", - }); - } catch (error) { - dependencies.sessionLogger?.warn( - { err: error, cwd: target.backing.mainRepoRoot, requestId: request.requestId }, - "Failed to force-refresh workspace git snapshot after archiving", + try { + if (targetWorkspaceIds.length > 0) { + await dependencies.emitWorkspaceUpdatesForWorkspaceIds(targetWorkspaceIds); + } + checkpoint(); + + const { archivedAgents, archivedWorkspaceIds } = await archiveTargetRecords( + dependencies, + targetWorkspaceIds, + { requestId: request.requestId, checkpoint, archivedAt }, + ); + checkpoint(); + + if (target.backing?.mainRepoRoot) { + try { + await dependencies.workspaceGitService.getSnapshot(target.backing.mainRepoRoot, { + force: true, + reason: "archive-worktree", + }); + } catch (error) { + dependencies.sessionLogger?.warn( + { err: error, cwd: target.backing.mainRepoRoot, requestId: request.requestId }, + "Failed to force-refresh workspace git snapshot after archiving", + ); + } + } + + if (target.backing !== null) { + const removal = await maybeRemoveDirectory( + dependencies, + { requestId: request.requestId, checkpoint }, + target, + archivedWorkspaceIds, ); + removedDirectory = removal.removedDirectory; + directoryLeftBehind = removal.directoryLeftBehind; + } + + return { + archivedAgentIds: Array.from(archivedAgents), + archivedWorkspaceIds, + removedDirectory, + ...(directoryLeftBehind ? { directoryLeftBehind } : {}), + }; + } finally { + if (targetWorkspaceIds.length > 0) { + dependencies.clearWorkspaceArchiving(targetWorkspaceIds); + await dependencies.emitWorkspaceUpdatesForWorkspaceIds(targetWorkspaceIds); } } + }; - if (target.backing !== null) { - const removal = await maybeRemoveDirectory( - dependencies, - { requestId: request.requestId, checkpoint }, - target, - archivedWorkspaceIds, - ); - removedDirectory = removal.removedDirectory; - directoryLeftBehind = removal.directoryLeftBehind; - } - - return { - archivedAgentIds: Array.from(archivedAgents), - archivedWorkspaceIds, - removedDirectory, - ...(directoryLeftBehind ? { directoryLeftBehind } : {}), - }; - } finally { - if (targetWorkspaceIds.length > 0) { - dependencies.clearWorkspaceArchiving(targetWorkspaceIds); - await dependencies.emitWorkspaceUpdatesForWorkspaceIds(targetWorkspaceIds); - } + const checkoutPath = dependencies.workspaceArchiveOperations + ? await resolveArchiveCheckoutPath(dependencies, request.scope) + : null; + if (dependencies.workspaceArchiveOperations && checkoutPath) { + return dependencies.workspaceArchiveOperations.withCheckout(checkoutPath, runArchive); } + return runArchive(); +} + +async function resolveArchiveCheckoutPath( + dependencies: ArchiveDependencies, + scope: ArchiveScope, +): Promise { + if (scope.kind === "workspace") { + const record = + (await dependencies.getWorkspace?.(scope.workspaceId)) ?? + (await dependencies.listActiveWorkspaces()).find( + (workspace) => workspace.workspaceId === scope.workspaceId, + ); + if (!record) { + return null; + } + return resolveWorkspaceBackingPath(record, dependencies); + } + return (await resolveBackingDirectory(scope.targetPath, dependencies)).path; } async function resolveArchiveTarget( @@ -313,6 +359,8 @@ async function resolveWorkspaceBackingDirectory( workspace: ActiveWorkspaceRef, dependencies: Pick, ): Promise { + const worktreeManagerPluginId = workspace.worktreeManagerPluginId ?? null; + const untrusted = Boolean(workspace.untrustedSource); if (workspace.isPaseoOwnedWorktree === false) { return { path: resolve(workspace.worktreeRoot ?? workspace.cwd), @@ -321,6 +369,8 @@ async function resolveWorkspaceBackingDirectory( registryProven: false, mainRepoRoot: workspace.mainRepoRoot ?? null, paseoWorktreesRoot: null, + worktreeManagerPluginId, + untrusted, }; } if (workspace.isPaseoOwnedWorktree && workspace.worktreeRoot && workspace.mainRepoRoot) { @@ -331,6 +381,8 @@ async function resolveWorkspaceBackingDirectory( registryProven: true, mainRepoRoot: workspace.mainRepoRoot, paseoWorktreesRoot: null, + worktreeManagerPluginId, + untrusted, }; } if (workspace.kind !== "worktree") { @@ -341,6 +393,8 @@ async function resolveWorkspaceBackingDirectory( registryProven: false, mainRepoRoot: workspace.mainRepoRoot ?? null, paseoWorktreesRoot: null, + worktreeManagerPluginId, + untrusted, }; } @@ -350,7 +404,12 @@ async function resolveWorkspaceBackingDirectory( workspace.worktreeRoot ?? workspace.cwd, dependencies, ); - return { ...backing, mainRepoRoot: workspace.mainRepoRoot ?? backing.mainRepoRoot }; + return { + ...backing, + mainRepoRoot: workspace.mainRepoRoot ?? backing.mainRepoRoot, + worktreeManagerPluginId: worktreeManagerPluginId ?? backing.worktreeManagerPluginId, + untrusted: untrusted || backing.untrusted, + }; } async function resolveBackingDirectory( @@ -369,6 +428,8 @@ async function resolveBackingDirectory( registryProven: false, mainRepoRoot: ownership.repoRoot ?? null, paseoWorktreesRoot: ownership.worktreeRoot ?? null, + worktreeManagerPluginId: null, + untrusted: false, }; } @@ -453,11 +514,16 @@ async function maybeRemoveDirectory( teardownTarget.workspaceId === null || archivedWorkspaceIdSet.has(teardownTarget.workspaceId), ); + let untrustedBacking = + backing.untrusted || Boolean(await dependencies.isCheckoutUntrusted?.(backing.path)); try { const allowedTeardownTargets = await filterAllowedTeardownTargets( dependencies, teardownTargets, ); + if (allowedTeardownTargets.length < teardownTargets.length) { + untrustedBacking = true; + } for (const teardownTarget of uniqueTeardownTargets(allowedTeardownTargets)) { request.checkpoint(); await runWorktreeTeardownCommands({ @@ -481,7 +547,7 @@ async function maybeRemoveDirectory( if ( !(await isDirectoryUnreferenced( remainingActive, - backing.path, + backing, new Set(archivedWorkspaceIds), dependencies, )) @@ -501,6 +567,10 @@ async function maybeRemoveDirectory( paseoHome: dependencies.paseoHome, worktreesBaseRoot: dependencies.paseoWorktreesBaseRoot, registryProven: backing.registryProven, + worktreeManagers: dependencies.worktreeManagers, + worktreeManagerPluginId: backing.worktreeManagerPluginId, + removeReason: "archive", + untrusted: untrustedBacking, }); dependencies.workspaceGitService.invalidateWorktrees(); dependencies.github.invalidate({ cwd: backing.path }); @@ -618,21 +688,28 @@ export async function archiveWorkspaceContents( return archivedAgents; } -// True when, after archiving -// the in-scope records, no active workspace still points at targetDir. Derived -// from records each call — no stored counter. +// Active workspaces on the same checkout keep it alive. A manager can place +// a checkout anywhere, so also protect nested workspaces when either checkout +// is manager-owned. async function isDirectoryUnreferenced( activeWorkspaces: ActiveWorkspaceRef[], - targetDir: string, + targetDirectory: BackingDirectory, archivedWorkspaceIds: ReadonlySet, dependencies: Pick, ): Promise { - const target = resolve(targetDir); + const target = targetDirectory.path; const matchesTarget = createRealpathAwarePathMatcher(target); for (const workspace of activeWorkspaces) { if (archivedWorkspaceIds.has(workspace.workspaceId)) continue; const backingDirectory = await resolveWorkspaceBackingDirectory(workspace, dependencies); if (matchesTarget(backingDirectory.path)) return false; + if ( + (targetDirectory.worktreeManagerPluginId || backingDirectory.worktreeManagerPluginId) && + (isRealpathInsideRoot(target, backingDirectory.path) || + isRealpathInsideRoot(target, workspace.cwd)) + ) { + return false; + } } return true; } diff --git a/packages/server/src/server/workspace-automation-gate.ts b/packages/server/src/server/workspace-automation-gate.ts index 652903ae6f..525c81bda6 100644 --- a/packages/server/src/server/workspace-automation-gate.ts +++ b/packages/server/src/server/workspace-automation-gate.ts @@ -1,3 +1,4 @@ +import { createRealpathAwarePathMatcher } from "../utils/path.js"; import type { WorkspaceRegistry } from "./workspace-registry.js"; export interface UntrustedWorkspaceSource { @@ -34,17 +35,44 @@ export async function assertWorkspaceAutomationAllowedForWorkspace( assertWorkspaceAutomationAllowed(workspace.untrustedSource); } +export async function isCheckoutUntrusted( + registry: Pick, + checkoutPath: string, +): Promise { + const matchesCheckout = createRealpathAwarePathMatcher(checkoutPath); + const workspaces = await registry.listAll(); + return workspaces.some( + (workspace) => + Boolean(workspace.untrustedSource) && + matchesCheckout(workspace.worktreeRoot ?? workspace.cwd), + ); +} + export async function clearWorkspaceAutomationBlock( - registry: Pick, + registry: Pick, workspaceId: string, ): Promise { let cleared = false; + const timestamp = new Date().toISOString(); const workspace = await registry.update(workspaceId, (record) => { if (!record.untrustedSource) return record; cleared = true; const { untrustedSource: _removed, ...trusted } = record; - return { ...trusted, updatedAt: new Date().toISOString() }; + return { ...trusted, updatedAt: timestamp }; }); if (!workspace) throw new Error(`Workspace not found: ${workspaceId}`); + const checkoutPath = workspace.worktreeRoot ?? workspace.cwd; + const matchesCheckout = createRealpathAwarePathMatcher(checkoutPath); + const siblings = await registry.listAll(); + for (const sibling of siblings) { + if (sibling.workspaceId === workspaceId || !sibling.untrustedSource) continue; + if (!matchesCheckout(sibling.worktreeRoot ?? sibling.cwd)) continue; + await registry.update(sibling.workspaceId, (record) => { + if (!record.untrustedSource) return record; + cleared = true; + const { untrustedSource: _removed, ...trusted } = record; + return { ...trusted, updatedAt: timestamp }; + }); + } return cleared; } diff --git a/packages/server/src/server/workspace-registry.ts b/packages/server/src/server/workspace-registry.ts index 04265da0c2..acbd5abef3 100644 --- a/packages/server/src/server/workspace-registry.ts +++ b/packages/server/src/server/workspace-registry.ts @@ -88,6 +88,7 @@ const PersistedWorkspaceRecordSchema = z.object({ .transform((value) => value ?? null), isPaseoOwnedWorktree: z.boolean().default(false), mainRepoRoot: z.string().nullable().default(null), + worktreeManagerPluginId: z.string().min(1).optional(), createdAt: z.string(), updatedAt: z.string(), archivedAt: z.string().nullable(), @@ -698,6 +699,7 @@ export function createPersistedWorkspaceRecord(input: { baseBranch?: string | null; isPaseoOwnedWorktree?: boolean; mainRepoRoot?: string | null; + worktreeManagerPluginId?: string | null; createdAt: string; updatedAt: string; archivedAt?: string | null; @@ -708,7 +710,7 @@ export function createPersistedWorkspaceRecord(input: { untrustedSource?: UntrustedWorkspaceSource; background?: boolean; }): PersistedWorkspaceRecord { - const { background, ...rest } = input; + const { background, worktreeManagerPluginId, ...rest } = input; return PersistedWorkspaceRecordSchema.parse({ ...rest, background: background ?? false, @@ -718,6 +720,7 @@ export function createPersistedWorkspaceRecord(input: { baseBranch: input.baseBranch ?? null, isPaseoOwnedWorktree: input.isPaseoOwnedWorktree ?? false, mainRepoRoot: input.mainRepoRoot ?? null, + ...(worktreeManagerPluginId ? { worktreeManagerPluginId } : {}), archivedAt: input.archivedAt ?? null, autoArchivedChangeRequestUrl: input.autoArchivedChangeRequestUrl ?? null, pinnedAt: input.pinnedAt ?? null, diff --git a/packages/server/src/server/worktree-core.posix.test.ts b/packages/server/src/server/worktree-core.posix.test.ts index f8417d01ab..239751aa36 100644 --- a/packages/server/src/server/worktree-core.posix.test.ts +++ b/packages/server/src/server/worktree-core.posix.test.ts @@ -25,9 +25,15 @@ import { readPaseoWorktreeMetadata, } from "../utils/worktree-metadata.js"; import { validateBeforeRequest, validateBeforeResult } from "./plugins/lifecycle/index.js"; -import { UnknownBranchError } from "../utils/worktree.js"; +import { + isPaseoOwnedWorktreeCwd, + listGitWorktrees, + listPaseoWorktrees, + UnknownBranchError, +} from "../utils/worktree.js"; import { createWorktreeCore as createCoreWorktree } from "./worktree-core.js"; import { isPlatform } from "../test-utils/platform.js"; +import { createWithWorktrunk } from "../../../../plugin-examples/worktrunk/server/wt.js"; function createGitHubServiceStub(): ForgeService { return { @@ -1035,6 +1041,87 @@ describe.skipIf(isPlatform("win32"))("worktree-core POSIX-only", () => { expect(getBranchUpstream(result.worktree.worktreePath)).toBeNull(); }); + test.each([true, false])( + "checks out the fetched PR head with local branch collision=%s", + async (collision) => { + const { tempDir, repoDir, remoteDir, paseoHome } = createSameRepoGitHubPrRemoteRepo(); + cleanupPaths.push(tempDir); + const branch = "daemon-shutdown-diagnostics"; + const cached = execFileSync("git", ["rev-parse", "main"], { + cwd: repoDir, + encoding: "utf8", + }).trim(); + if (collision) execFileSync("git", ["branch", "-f", branch, cached], { cwd: repoDir }); + const expected = execFileSync( + "git", + ["--git-dir", remoteDir, "rev-parse", "refs/pull/1790/head"], + { encoding: "utf8" }, + ).trim(); + expect(cached).not.toBe(expected); + + const wt = path.join(tempDir, "wt"); + writeFileSync( + wt, + `#!/bin/sh +if [ "$3" = remove ]; then + exec git -C "$2" worktree remove --force "$2-pr-checkout" +fi +repo="$2" +shift 2 +branch="" +base="" +while [ "$#" -gt 0 ]; do + case "$1" in + --create) branch="$2"; shift 2 ;; + --base) base="$2"; shift 2 ;; + *) shift ;; + esac +done +git -C "$repo" worktree add --quiet -b "$branch" "$repo-pr-checkout" "$base" || exit $? +printf '{"action":"created","path":"%s","branch":"%s","created_branch":true}\\n' "$repo-pr-checkout" "$branch" +printf 'setup' > "$repo-pr-checkout/.worktrunk-setup" +`, + { mode: 0o755 }, + ); + const previous = process.env.WORKTRUNK_BIN; + process.env.WORKTRUNK_BIN = wt; + try { + const result = await createCoreWorktree( + { cwd: repoDir, action: "checkout", refName: branch, githubPrNumber: 1790, paseoHome }, + { + ...createCoreDeps(), + worktreeManagers: { + hasWorktreeManager: () => true, + createWorktree: async (request) => { + const managed = await createWithWorktrunk(request, new AbortController().signal); + return managed ? { pluginId: "worktrunk", path: managed.path } : null; + }, + removeWorktree: async () => null, + }, + }, + ); + expect( + execFileSync("git", ["rev-parse", "HEAD"], { + cwd: result.worktree.worktreePath, + encoding: "utf8", + }).trim(), + ).toBe(expected); + expect( + execFileSync("git", ["rev-parse", `refs/heads/${branch}`], { + cwd: repoDir, + encoding: "utf8", + }).trim(), + ).toBe(collision ? cached : expected); + expect(existsSync(path.join(result.worktree.worktreePath, ".worktrunk-setup"))).toBe( + !collision, + ); + } finally { + if (previous === undefined) delete process.env.WORKTRUNK_BIN; + else process.env.WORKTRUNK_BIN = previous; + } + }, + ); + test("pushes a deduplicated same-repo GitHub PR branch to the PR head", async () => { const { tempDir, repoDir, remoteDir, paseoHome } = createSameRepoGitHubPrRemoteRepo(); cleanupPaths.push(tempDir); @@ -1467,6 +1554,454 @@ describe.skipIf(isPlatform("win32"))("worktree-core POSIX-only", () => { expect(getBranchUpstream(second.worktree.worktreePath)).toBe("paseo-pr-526/main"); }); + test("rejects and rolls back a managed fork PR checkout whose HEAD is behind the current PR head", async () => { + const { tempDir, repoDir, headRemoteDir, paseoHome } = createForkGitHubPrRemoteRepo(); + cleanupPaths.push(tempDir); + const staleBranch = "archived-fork-pr-526"; + const staleWorktreePath = path.join(tempDir, "stale-fork-pr"); + git(repoDir, "branch", staleBranch, "main"); + const github = { + ...createGitHubServiceStub(), + getPullRequestCheckoutTarget: async () => ({ + number: 526, + baseRefName: "main", + headRefName: "main", + headOwnerLogin: "therainisme", + headRepositorySshUrl: headRemoteDir, + headRepositoryUrl: headRemoteDir, + isCrossRepository: true, + }), + }; + + await expect( + createCoreWorktree( + { + cwd: repoDir, + worktreeSlug: "fork-pr-stale", + action: "checkout", + githubPrNumber: 526, + refName: "main", + paseoHome, + }, + { + ...createCoreDeps({ github }), + worktreeManagers: { + hasWorktreeManager: () => true, + createWorktree: async () => { + git(repoDir, "worktree", "add", staleWorktreePath, staleBranch); + return { pluginId: "stale-manager", path: staleWorktreePath }; + }, + removeWorktree: async () => null, + }, + }, + ), + ).rejects.toThrow("expected change request head"); + expect(existsSync(staleWorktreePath)).toBe(false); + }); + + test("fails before calling the manager when the remote PR ref cannot be fetched", async () => { + const { tempDir, repoDir, headRemoteDir, paseoHome } = createForkGitHubPrRemoteRepo(); + cleanupPaths.push(tempDir); + let managerCalled = false; + git(repoDir, "remote", "set-url", "origin", path.join(tempDir, "missing-remote.git")); + const github = { + ...createGitHubServiceStub(), + getPullRequestCheckoutTarget: async () => ({ + number: 526, + baseRefName: "main", + headRefName: "main", + headOwnerLogin: "therainisme", + headRepositorySshUrl: headRemoteDir, + headRepositoryUrl: headRemoteDir, + isCrossRepository: true, + }), + }; + + await expect( + createCoreWorktree( + { + cwd: repoDir, + worktreeSlug: "fork-pr-offline", + action: "checkout", + githubPrNumber: 526, + refName: "main", + paseoHome, + }, + { + ...createCoreDeps({ github }), + worktreeManagers: { + hasWorktreeManager: () => true, + createWorktree: async () => { + managerCalled = true; + return null; + }, + removeWorktree: async () => null, + }, + }, + ), + ).rejects.toThrow("Unable to fetch change request refs"); + expect(managerCalled).toBe(false); + }); + + test("accepts a managed fork PR checkout matching the pre-fetched headSha even after multiple mid-setup pushes", async () => { + const { tempDir, repoDir, headRemoteDir, paseoHome } = createForkGitHubPrRemoteRepo(); + cleanupPaths.push(tempDir); + const baseRemoteDir = path.join(tempDir, "base.git"); + const initialPrHead = git(repoDir, "ls-remote", "origin", "refs/pull/526/head").split( + /\s+/, + )[0]; + const managedPath = path.join(tempDir, "mid-push-fork-pr"); + const github = { + ...createGitHubServiceStub(), + getPullRequestCheckoutTarget: async () => ({ + number: 526, + baseRefName: "main", + headRefName: "main", + headOwnerLogin: "therainisme", + headRepositorySshUrl: headRemoteDir, + headRepositoryUrl: headRemoteDir, + isCrossRepository: true, + }), + }; + + const pushCommit = (message: string) => { + const headCloneDir = path.join(tempDir, "therainisme-clone"); + writeFileSync(path.join(headCloneDir, "README.md"), `${message}\n`); + git(headCloneDir, "add", "README.md"); + git(headCloneDir, "-c", "commit.gpgsign=false", "commit", "-m", message); + const head = git(headCloneDir, "rev-parse", "HEAD"); + git(headCloneDir, "push", "origin", "main"); + execFileSync("git", [`--git-dir=${baseRemoteDir}`, "fetch", headRemoteDir, "main"], { + stdio: "pipe", + }); + execFileSync( + "git", + [`--git-dir=${baseRemoteDir}`, "update-ref", "refs/pull/526/head", head], + { stdio: "pipe" }, + ); + }; + + const result = await createCoreWorktree( + { + cwd: repoDir, + worktreeSlug: "fork-pr-mid-push", + action: "checkout", + githubPrNumber: 526, + refName: "main", + paseoHome, + }, + { + ...createCoreDeps({ github }), + worktreeManagers: { + hasWorktreeManager: () => true, + createWorktree: async (request) => { + expect(request.headSha).toBe(initialPrHead); + // Two pushes happen while the manager creates the worktree from request.headSha. + pushCommit("mid-setup push B"); + git(repoDir, "worktree", "add", "-b", "pr-526-snap", managedPath, request.headSha!); + pushCommit("mid-setup push C"); + return { pluginId: "mid-push-manager", path: managedPath }; + }, + removeWorktree: async () => null, + }, + }, + ); + + expect(git(result.worktree.worktreePath, "rev-parse", "HEAD")).toBe(initialPrHead); + }); + + test("configures fork push remote on a managed Worktrunk PR checkout so Push updates the fork branch", async () => { + const { tempDir, repoDir, headRemoteDir, paseoHome } = createForkGitHubPrRemoteRepo(); + cleanupPaths.push(tempDir); + const baseRemoteDir = path.join(tempDir, "base.git"); + const wt = path.join(tempDir, "fake-wt-fork-push"); + writeFileSync( + wt, + `#!/bin/sh +repo="$2" +shift 2 +branch="" +base="" +while [ "$#" -gt 0 ]; do + case "$1" in + --create) branch="$2"; shift 2 ;; + --base) base="$2"; shift 2 ;; + *) shift ;; + esac +done +git -C "$repo" worktree add --quiet -b "$branch" "$repo-fork-managed" "$base" || exit $? +printf '{"action":"created","path":"%s","branch":"%s","created_branch":true}\\n' "$repo-fork-managed" "$branch" +`, + { mode: 0o755 }, + ); + + const github = { + ...createGitHubServiceStub(), + getPullRequestCheckoutTarget: async () => ({ + number: 526, + baseRefName: "main", + headRefName: "main", + headOwnerLogin: "therainisme", + headRepositorySshUrl: headRemoteDir, + headRepositoryUrl: headRemoteDir, + isCrossRepository: true, + }), + }; + + const previous = process.env.WORKTRUNK_BIN; + process.env.WORKTRUNK_BIN = wt; + try { + const result = await createCoreWorktree( + { + cwd: repoDir, + worktreeSlug: "fork-pr-managed-push", + action: "checkout", + githubPrNumber: 526, + refName: "main", + paseoHome, + }, + { + ...createCoreDeps({ github }), + worktreeManagers: { + hasWorktreeManager: () => true, + createWorktree: async (request) => { + const managed = await createWithWorktrunk(request, new AbortController().signal); + return managed ? { pluginId: "worktrunk", path: managed.path } : null; + }, + removeWorktree: async () => null, + }, + }, + ); + expect(result.worktree.worktreeManagerPluginId).toBe("worktrunk"); + expect(result.worktree.branchName).toBe("therainisme/main"); + writeFileSync(path.join(result.worktree.worktreePath, "README.md"), "pushed from wt\n"); + git(result.worktree.worktreePath, "add", "README.md"); + git( + result.worktree.worktreePath, + "-c", + "commit.gpgsign=false", + "commit", + "-m", + "managed fork commit", + ); + const pushedSha = git(result.worktree.worktreePath, "rev-parse", "HEAD"); + await pushCurrentBranch(result.worktree.worktreePath); + + expect( + execFileSync("git", [`--git-dir=${headRemoteDir}`, "rev-parse", "refs/heads/main"], { + encoding: "utf8", + }).trim(), + ).toBe(pushedSha); + expect( + execFileSync( + "git", + [`--git-dir=${baseRemoteDir}`, "for-each-ref", "refs/heads/therainisme/main"], + { encoding: "utf8" }, + ).trim(), + ).toBe(""); + } finally { + if (previous === undefined) delete process.env.WORKTRUNK_BIN; + else process.env.WORKTRUNK_BIN = previous; + } + }); + + test("falls back to built-in Git without calling managers when Git rejects worktree list -z", async () => { + const { tempDir, repoDir, paseoHome } = createGitRepo(); + cleanupPaths.push(tempDir); + const trailingSpaceWorktree = path.join(tempDir, "detached space "); + git(repoDir, "worktree", "add", "--detach", trailingSpaceWorktree, "main"); + writeFileSync(path.join(trailingSpaceWorktree, "keep.txt"), "do not delete\n"); + + const realGit = execFileSync("which", ["git"], { encoding: "utf8" }).trim(); + const shimDir = path.join(tempDir, "legacy-git-bin"); + mkdirSync(shimDir, { recursive: true }); + writeFileSync( + path.join(shimDir, "git"), + `#!/bin/sh +for arg in "$@"; do + if [ "$arg" = "-z" ]; then + echo 'error: unknown switch -z' >&2 + exit 129 + fi +done +exec "${realGit}" "$@" +`, + { mode: 0o755 }, + ); + + let managerCalled = false; + const previousPath = process.env.PATH; + process.env.PATH = `${shimDir}:${previousPath ?? ""}`; + try { + const result = await createCoreWorktree( + { + cwd: repoDir, + worktreeSlug: "legacy-git-fallback", + action: "branch-off", + branchName: "legacy-git-fallback", + paseoHome, + }, + { + ...createCoreDeps(), + worktreeManagers: { + hasWorktreeManager: () => true, + createWorktree: async () => { + managerCalled = true; + return { pluginId: "bad-manager", path: trailingSpaceWorktree }; + }, + removeWorktree: async () => null, + }, + }, + ); + expect(managerCalled).toBe(false); + expect(result.worktree.branchName).toBe("legacy-git-fallback"); + expect(result.worktree.worktreeManagerPluginId).toBeUndefined(); + expect(readFileSync(path.join(trailingSpaceWorktree, "keep.txt"), "utf8")).toBe( + "do not delete\n", + ); + } finally { + if (previousPath === undefined) delete process.env.PATH; + else process.env.PATH = previousPath; + } + }); + + test("protects pre-existing and discovers newly managed worktrees whose paths contain a line break", async () => { + const { tempDir, repoDir, paseoHome } = createGitRepo(); + cleanupPaths.push(tempDir); + const newlineWorktree = path.join(tempDir, "manual\nworktree"); + git(repoDir, "worktree", "add", "-b", "newline-branch", newlineWorktree, "main"); + writeFileSync(path.join(newlineWorktree, "keep.txt"), "uncommitted\n"); + + await expect( + createCoreWorktree( + { + cwd: repoDir, + worktreeSlug: "newline-hijack", + action: "branch-off", + branchName: "newline-hijack", + paseoHome, + }, + { + ...createCoreDeps(), + worktreeManagers: { + hasWorktreeManager: () => true, + createWorktree: async () => ({ + pluginId: "bad-manager", + path: newlineWorktree, + }), + removeWorktree: async () => null, + }, + }, + ), + ).rejects.toThrow("already-existing worktree"); + + expect(readFileSync(path.join(newlineWorktree, "keep.txt"), "utf8")).toBe("uncommitted\n"); + expect(await readPaseoWorktreeMetadata(newlineWorktree)).toBeNull(); + + // A newly created managed worktree inside a directory containing a line break must remain + // visible to discovery and marker-based ownership checks. + const managedNewlineDir = path.join(tempDir, "parent\nbreak", "managed-wt"); + mkdirSync(path.dirname(managedNewlineDir), { recursive: true }); + const created = await createCoreWorktree( + { + cwd: repoDir, + worktreeSlug: "newline-managed", + action: "branch-off", + branchName: "newline-managed", + paseoHome, + }, + { + ...createCoreDeps(), + worktreeManagers: { + hasWorktreeManager: () => true, + createWorktree: async (request) => { + git(repoDir, "worktree", "add", "-b", request.branch, managedNewlineDir, "main"); + return { pluginId: "newline-manager", path: managedNewlineDir }; + }, + removeWorktree: async () => null, + }, + }, + ); + + const expectedPath = realpathSync(managedNewlineDir); + expect(created.worktree.worktreePath).toBe(expectedPath); + const allGitWorktrees = await listGitWorktrees({ cwd: repoDir }); + expect(allGitWorktrees.map((entry) => entry.path)).toContain(expectedPath); + const paseoWorktrees = await listPaseoWorktrees({ cwd: repoDir, paseoHome }); + expect(paseoWorktrees.map((entry) => entry.path)).toContain(expectedPath); + const ownership = await isPaseoOwnedWorktreeCwd(expectedPath, { paseoHome }); + expect(ownership.allowed).toBe(true); + expect(ownership.worktreePath).toBe(expectedPath); + }); + + test("declines a Worktrunk fork PR checkout when the archived local branch already exists so Git checks out the latest PR head", async () => { + const { tempDir, repoDir, headRemoteDir, paseoHome } = createForkGitHubPrRemoteRepo(); + cleanupPaths.push(tempDir); + const archivedBranch = "therainisme/main"; + const archivedTip = git(repoDir, "rev-parse", "main"); + git(repoDir, "branch", archivedBranch, archivedTip); + const latestPrHead = git(repoDir, "ls-remote", "origin", "refs/pull/526/head").split( + /\s+/, + )[0]; + expect(latestPrHead).not.toBe(archivedTip); + + const wt = path.join(tempDir, "fake-wt-fork-pr"); + writeFileSync( + wt, + `#!/bin/sh +echo "wt should not be invoked when local branch already exists" >&2 +exit 1 +`, + { mode: 0o755 }, + ); + + const github = { + ...createGitHubServiceStub(), + getPullRequestCheckoutTarget: async () => ({ + number: 526, + baseRefName: "main", + headRefName: "main", + headOwnerLogin: "therainisme", + headRepositorySshUrl: headRemoteDir, + headRepositoryUrl: headRemoteDir, + isCrossRepository: true, + }), + }; + + const previous = process.env.WORKTRUNK_BIN; + process.env.WORKTRUNK_BIN = wt; + try { + const result = await createCoreWorktree( + { + cwd: repoDir, + worktreeSlug: "fork-pr-reopen", + action: "checkout", + githubPrNumber: 526, + refName: "main", + paseoHome, + }, + { + ...createCoreDeps({ github }), + worktreeManagers: { + hasWorktreeManager: () => true, + createWorktree: async (request) => { + expect(request.untrusted).toBe(true); + expect(request.headSha).toBe(latestPrHead); + const managed = await createWithWorktrunk(request, new AbortController().signal); + return managed ? { pluginId: "worktrunk", path: managed.path } : null; + }, + removeWorktree: async () => null, + }, + }, + ); + expect(git(result.worktree.worktreePath, "rev-parse", "HEAD")).toBe(latestPrHead); + expect(git(repoDir, "rev-parse", `refs/heads/${archivedBranch}`)).toBe(archivedTip); + } finally { + if (previous === undefined) delete process.env.WORKTRUNK_BIN; + else process.env.WORKTRUNK_BIN = previous; + } + }); + test("throws a typed error for an unknown checkout branch", async () => { const { tempDir, repoDir, paseoHome } = createGitRepo(); cleanupPaths.push(tempDir); @@ -1648,9 +2183,26 @@ describe.skipIf(isPlatform("win32"))("worktree-core POSIX-only", () => { branchName: "follow-up", paseoHome, }, - createCoreDeps({ github }), + { + ...createCoreDeps({ github }), + worktreeManagers: { + hasWorktreeManager: () => true, + async createWorktree(request) { + expect(request.untrusted).toBe(true); + return null; + }, + async removeWorktree() { + return null; + }, + }, + }, ); + expect(result.untrustedSource).toMatchObject({ + kind: "change_request", + forge: "github", + number: 526, + }); const readme = readFileSync(path.join(result.worktree.worktreePath, "README.md"), "utf8"); // The fork's branch is not in this repository, so a pull request from the new branch goes // into the fork pull request's base, compared as the remote has it now. diff --git a/packages/server/src/server/worktree-core.ts b/packages/server/src/server/worktree-core.ts index 41f6363cdd..34681ac352 100644 --- a/packages/server/src/server/worktree-core.ts +++ b/packages/server/src/server/worktree-core.ts @@ -1,12 +1,19 @@ -import type { PluginWorktreeCreateRequest } from "@getpaseo/plugin/server"; +import type { + PluginWorktreeCreateInput, + PluginWorktreeCreateRequest, +} from "@getpaseo/plugin/server"; import type { PluginLifecycle } from "./plugins/lifecycle/index.js"; +import type { PluginWorktreeManagerRuntime } from "./plugins/runtime.js"; import { createNameId } from "mnemonic-id"; import type { ForgeService } from "../services/forge-service.js"; import { createWorktree, fetchFirstAvailableRef, + prepareWorktreeBranchOff, + type PreparedWorktreeBranchOff, resolveDefaultWorktreePath, + runPluginWorktreeManagerCheckout, slugify, validateBranchSlug, type CreatedWorktree, @@ -16,11 +23,14 @@ import { type ResolveWorktreeCreationIntentInput, UnsupportedForgeCheckoutTargetError, type WorktreeCreationIntent, + worktreeUntrustedSource, } from "./resolve-worktree-creation-intent.js"; import type { ChangeRequestCheckoutSource, FirstAgentContext } from "@getpaseo/protocol/messages"; import type { WorkspaceGitService } from "./workspace-git-service.js"; import { runGitCommand, runWithGitCommandPriority } from "../utils/run-git-command.js"; +import type { UntrustedWorkspaceSource } from "./workspace-automation-gate.js"; + export interface CreateWorktreeCoreInput { cwd: string; worktreeSlug?: string; @@ -36,6 +46,10 @@ export interface CreateWorktreeCoreInput { export interface CreateWorktreeCoreDeps { lifecycle?: Pick; + worktreeManagers?: Pick< + PluginWorktreeManagerRuntime, + "hasWorktreeManager" | "createWorktree" | "removeWorktree" + >; github: ForgeService; workspaceGitService?: Pick< WorkspaceGitService, @@ -47,6 +61,7 @@ export interface CreateWorktreeCoreDeps { export interface CreateWorktreeCoreResult { worktree: CreatedWorktree; intent: WorktreeCreationIntent; + untrustedSource?: UntrustedWorkspaceSource; repoRoot: string; created: boolean; } @@ -146,8 +161,28 @@ async function createWorktreeCoreWithPriority( const transformed = deps.lifecycle ? await deps.lifecycle.before("worktree.create.before", request) : request; + const originalUntrustedSource = worktreeUntrustedSource(intent); normalizedSlug = validateWorktreeSlug(transformed.slug); intent = creationIntentFromRequest(transformed, intent); + const untrustedSource = originalUntrustedSource ?? worktreeUntrustedSource(intent); + + const { worktree: managedWorktree, preparedBranchOff } = await tryCreateWithWorktreeManager({ + repoRoot, + transformed, + intent, + untrusted: Boolean(untrustedSource), + input, + deps, + }); + if (managedWorktree) { + return { + worktree: managedWorktree, + intent, + untrustedSource, + repoRoot, + created: true, + }; + } return { worktree: await createWorktree({ @@ -155,15 +190,51 @@ async function createWorktreeCoreWithPriority( worktreeSlug: normalizedSlug, worktreePath: transformed.path, source: intent, + preparedBranchOff, paseoHome: input.paseoHome, worktreesRoot: input.worktreesRoot, }), intent, + untrustedSource, repoRoot, created: true, }; } +async function tryCreateWithWorktreeManager(options: { + repoRoot: string; + transformed: PluginWorktreeCreateRequest; + intent: WorktreeCreationIntent; + untrusted: boolean; + input: Pick; + deps: Pick; +}): Promise<{ worktree: CreatedWorktree | null; preparedBranchOff?: PreparedWorktreeBranchOff }> { + const { repoRoot, transformed, intent, untrusted, input, deps } = options; + let preparedBranchOff: PreparedWorktreeBranchOff | undefined; + const worktree = await runPluginWorktreeManagerCheckout({ + cwd: repoRoot, + source: intent, + operation: "create", + untrusted, + paseoHome: input.paseoHome, + worktreesBaseRoot: input.worktreesRoot, + worktreeManagers: deps.worktreeManagers, + run: async ({ changeRequestHeadSha }) => { + let request: PluginWorktreeCreateInput = { + ...transformed, + untrusted, + ...(changeRequestHeadSha ? { headSha: changeRequestHeadSha } : {}), + }; + if (request.kind === "branch-off" && intent.kind === "branch-off") { + preparedBranchOff = await prepareWorktreeBranchOff(repoRoot, intent); + request = { ...request, baseRef: preparedBranchOff.baseRef }; + } + return deps.worktreeManagers!.createWorktree(request); + }, + }); + return { worktree, preparedBranchOff }; +} + function describeCreationRequest( intent: WorktreeCreationIntent, placement: Pick, @@ -174,6 +245,7 @@ function describeCreationRequest( kind: intent.kind, branch: intent.branchName, baseRef: intent.baseBranch, + ...(intent.startPoint ? { startPoint: intent.startPoint } : {}), }; if (intent.kind === "checkout-branch") return { ...placement, kind: intent.kind, branch: intent.branchName }; diff --git a/packages/server/src/utils/path.ts b/packages/server/src/utils/path.ts index 45cb8b01b5..d7cbeaa454 100644 --- a/packages/server/src/utils/path.ts +++ b/packages/server/src/utils/path.ts @@ -78,7 +78,7 @@ export function isPathInsideRoot(root: string, candidate: string): boolean { } export function normalizePathForIdentity(value: string): string { - const canonicalPath = resolveRealpathVariants(value)[0] ?? value; + const canonicalPath = resolveNearestExistingAncestorRealpath(value); return normalizePathForComparison(canonicalPath, looksLikeDefiniteWindowsPath(canonicalPath)); } @@ -150,6 +150,26 @@ function resolveRealpathVariants(value: string): string[] { return variants; } +function resolveNearestExistingAncestorRealpath(value: string): string { + if (process.platform !== "win32" && looksLikeDefiniteWindowsPath(value)) { + return value; + } + const tail: string[] = []; + let current = value; + while (true) { + const resolved = resolveRealpathVariants(current)[0]; + if (resolved) { + return tail.length === 0 ? resolved : nodePath.join(resolved, ...tail.toReversed()); + } + const parent = nodePath.dirname(current); + if (parent === current) { + return value; + } + tail.push(nodePath.basename(current)); + current = parent; + } +} + function shouldCompareAsWindows(left: string, right: string): boolean { return looksLikeDefiniteWindowsPath(left) || looksLikeDefiniteWindowsPath(right); } diff --git a/packages/server/src/utils/worktree-metadata.ts b/packages/server/src/utils/worktree-metadata.ts index fc4488d742..845e2de4b2 100644 --- a/packages/server/src/utils/worktree-metadata.ts +++ b/packages/server/src/utils/worktree-metadata.ts @@ -22,6 +22,7 @@ const PaseoWorktreeMetadataV1Schema = z.object({ baseRefName: z.string().min(1), baseRef: z.string().min(1).optional(), changeRequestLookupTarget: ChangeRequestLookupTargetSchema.optional(), + worktreeManagerPluginId: z.string().min(1).optional(), }); const PaseoWorktreeMetadataV2Schema = z.object({ @@ -29,6 +30,7 @@ const PaseoWorktreeMetadataV2Schema = z.object({ baseRefName: z.string().min(1), baseRef: z.string().min(1).optional(), changeRequestLookupTarget: ChangeRequestLookupTargetSchema.optional(), + worktreeManagerPluginId: z.string().min(1).optional(), firstAgentBranchAutoName: z .discriminatedUnion("status", [ z.object({ @@ -227,6 +229,7 @@ export async function writePaseoWorktreeMetadata( baseRefName: string; baseRef?: string; changeRequestLookupTarget?: PaseoWorktreeChangeRequestHint; + worktreeManagerPluginId?: string; }, ): Promise { return mutateMetadata(worktreeRoot, async (root) => { @@ -244,6 +247,9 @@ export async function writePaseoWorktreeMetadata( ...(options.changeRequestLookupTarget ? { changeRequestLookupTarget: options.changeRequestLookupTarget } : {}), + ...(options.worktreeManagerPluginId + ? { worktreeManagerPluginId: options.worktreeManagerPluginId } + : {}), }; await writePaseoWorktreeMetadataFile(root, metadata); }); diff --git a/packages/server/src/utils/worktree-path.ts b/packages/server/src/utils/worktree-path.ts index d36abea762..5f0952a58e 100644 --- a/packages/server/src/utils/worktree-path.ts +++ b/packages/server/src/utils/worktree-path.ts @@ -47,24 +47,24 @@ async function pathExists(path: string): Promise { export async function validateWorktreePath(options: { candidate: string; repoPath: string; + /** The worktree manager already created the destination, so it is expected to exist. */ + allowExistingPath?: boolean; }): Promise { - const { candidate, repoPath } = options; + const { candidate, repoPath, allowExistingPath = false } = options; if (!isAbsolute(candidate)) { - throw new Error( - `Worktree hook returned a relative path '${candidate}'; it must be an absolute path`, - ); + throw new Error(`The returned path is relative: ${candidate}. Use an absolute path.`); } const normalized = await normalizeCandidatePath(candidate); const normalizedRepoPath = await normalizeAbsolute(repoPath); if (normalized === parse(normalized).root) { - throw new Error("Worktree hook returned the filesystem root, which is not allowed"); + throw new Error("The filesystem root cannot be a worktree destination"); } if (normalized === (await normalizeAbsolute(homedir()))) { - throw new Error("Worktree hook returned the user's home directory, which is not allowed"); + throw new Error("The user's home directory cannot be a worktree destination"); } if (normalized === normalizedRepoPath) { - throw new Error("Worktree hook returned the repository root itself, which is not allowed"); + throw new Error("The repository root cannot be a worktree destination"); } if ( [normalized, resolve(candidate)].some((path) => @@ -73,15 +73,15 @@ export async function validateWorktreePath(options: { .some((part) => (process.platform === "win32" ? part.toLowerCase() : part) === ".git"), ) ) { - throw new Error(`Worktree hook returned a path inside a .git directory: ${normalized}`); + throw new Error(`The returned path is inside a .git directory: ${normalized}`); } const relativeToCandidate = getRelativePathInsideRoot(normalized, normalizedRepoPath); if (relativeToCandidate !== null && relativeToCandidate !== "") { - throw new Error(`Worktree hook returned an ancestor of the repository: ${normalized}`); + throw new Error(`The returned path is an ancestor of the repository: ${normalized}`); } - if ((await pathExists(normalized)) || (await pathExists(candidate))) { + if (!allowExistingPath && ((await pathExists(normalized)) || (await pathExists(candidate)))) { throw new Error( - `Worktree hook returned a path that already exists: ${normalized}. Paseo creates the returned path.`, + `The returned path already exists: ${normalized}. Paseo creates the returned path.`, ); } return normalized; diff --git a/packages/server/src/utils/worktree.ts b/packages/server/src/utils/worktree.ts index fcde189857..94191f53f0 100644 --- a/packages/server/src/utils/worktree.ts +++ b/packages/server/src/utils/worktree.ts @@ -1,7 +1,7 @@ import { execFile } from "child_process"; import { promisify } from "util"; -import { constants as fsConstants, realpath } from "fs"; -import { copyFile, mkdir, rm, stat } from "fs/promises"; +import { constants as fsConstants, type Dirent, realpath } from "fs"; +import { copyFile, mkdir, readdir, rm, stat } from "fs/promises"; import { join, basename, dirname, isAbsolute, resolve, sep } from "path"; import net from "node:net"; import { createHash } from "node:crypto"; @@ -41,12 +41,16 @@ import { resolvePaseoHome } from "../server/paseo-home.js"; import { createExternalProcessEnv } from "../server/paseo-env.js"; import { parseGitRevParsePath, resolveGitRevParsePath } from "./git-rev-parse-path.js"; import { + createRealpathAwarePathMatcher, expandTilde, getRealpathAwareRelativePath, getRelativePathInsideRoot, isPathInsideRoot, + normalizePathForIdentity, } from "./path.js"; import { terminateWithTreeKill } from "./tree-kill.js"; +import { validateWorktreePath } from "./worktree-path.js"; +import type { PluginWorktreeManagerRuntime } from "../server/plugins/runtime.js"; export { slugify, validateBranchSlug } from "@getpaseo/protocol/branch-slug"; @@ -62,6 +66,7 @@ export interface WorktreeConfig { export interface CreatedWorktree extends WorktreeConfig { comparisonBaseRef: string | null; + worktreeManagerPluginId?: string; } export interface WorktreeRuntimeEnv { @@ -228,10 +233,17 @@ export type WorktreeSource = trackOriginHead?: boolean; }; +export interface PreparedWorktreeBranchOff { + baseRef: string; + checkoutRef: string; + branchExists: boolean; +} + export interface CreateWorktreeOptions { cwd: string; worktreeSlug: string; source: WorktreeSource; + preparedBranchOff?: PreparedWorktreeBranchOff; paseoHome?: string; worktreesRoot?: string; worktreePath?: string; @@ -1060,11 +1072,8 @@ async function resolveMetadataOwnedWorktree( const candidate = await normalizePathForOwnership(root); if (repoRoot !== undefined && candidate === (await normalizePathForOwnership(repoRoot))) return null; - const { stdout: listOutput } = await runGitCommand(["worktree", "list", "--porcelain"], { - cwd: candidate, - envOverlay: READ_ONLY_GIT_ENV, - }); - for (const entry of parseWorktreeList(listOutput)) { + const { entries } = await readGitWorktreeEntries(candidate); + for (const entry of entries) { if ((await normalizePathForOwnership(entry.path)) === candidate) { return { worktreePath: candidate, worktreeRoot: dirname(candidate) }; } @@ -1082,20 +1091,51 @@ interface ParsedWorktreeEntry extends ParsedPaseoWorktreeInfo { unusable?: true; } -function parseWorktreeList(output: string): ParsedPaseoWorktreeInfo[] { - return parseWorktreeEntries(output).map(({ unusable: _unusable, ...entry }) => entry); +/** + * Single worktree-list reader shared by adoption snapshots, discovery, and marker ownership. + * Uses Git 2.36+'s NUL-delimited `-z` output (`exact: true`) to preserve paths containing + * line breaks or trailing whitespace, falling back to line-delimited `--porcelain` + * (`exact: false`) on Git 2.35 and earlier. + */ +async function readGitWorktreeEntries( + cwd: string, +): Promise<{ entries: ParsedWorktreeEntry[]; exact: boolean }> { + const nulResult = await runGitCommand(["worktree", "list", "--porcelain", "-z"], { + cwd, + envOverlay: READ_ONLY_GIT_ENV, + acceptExitCodes: [0, 129], + }); + if (nulResult.exitCode === 0) { + return { + entries: parseWorktreeEntriesTokens(nulResult.stdout.split("\0"), false), + exact: true, + }; + } + const { stdout } = await runGitCommand(["worktree", "list", "--porcelain"], { + cwd, + envOverlay: READ_ONLY_GIT_ENV, + }); + return { + entries: parseWorktreeEntriesTokens(stdout.split("\n"), true), + exact: false, + }; } -function parseWorktreeEntries(output: string): ParsedWorktreeEntry[] { +function parseWorktreeEntriesTokens( + tokens: readonly string[], + lineDelimited: boolean, +): ParsedWorktreeEntry[] { const entries: ParsedWorktreeEntry[] = []; let current: ParsedWorktreeEntry | null = null; - for (const line of output.split("\n")) { - if (line.startsWith("worktree ")) { + for (const rawToken of tokens) { + const token = lineDelimited ? rawToken.replace(/\r$/, "") : rawToken; + if (token.startsWith("worktree ")) { if (current?.path) { entries.push(current); } - current = { path: line.slice("worktree ".length).trim() }; + // Preserve trailing spaces in worktree paths even on line-delimited output. + current = { path: token.slice("worktree ".length) }; continue; } @@ -1103,14 +1143,14 @@ function parseWorktreeEntries(output: string): ParsedWorktreeEntry[] { continue; } - if (line.startsWith("branch ")) { - const ref = line.slice("branch ".length).trim(); + if (token.startsWith("branch ")) { + const ref = token.slice("branch ".length).trim(); current.branchName = ref.startsWith("refs/heads/") ? ref.slice("refs/heads/".length) : ref; - } else if (line.startsWith("HEAD ")) { - current.head = line.slice("HEAD ".length).trim(); - } else if (line === "bare" || line.startsWith("prunable")) { + } else if (token.startsWith("HEAD ")) { + current.head = token.slice("HEAD ".length).trim(); + } else if (token === "bare" || token.startsWith("prunable")) { current.unusable = true; - } else if (line.trim().length === 0) { + } else if ((lineDelimited ? token.trim() : token).length === 0) { if (current.path) { entries.push(current); } @@ -1154,17 +1194,14 @@ export interface GitWorktree { * Unlike `listPaseoWorktrees`, ownership plays no part. */ export async function listGitWorktrees({ cwd }: { cwd: string }): Promise { - const { stdout } = await runGitCommand(["worktree", "list", "--porcelain"], { - cwd, - envOverlay: READ_ONLY_GIT_ENV, - }); + const { entries } = await readGitWorktreeEntries(cwd); const { stdout: toplevel } = await runGitCommand(["rev-parse", "--show-toplevel"], { cwd, envOverlay: READ_ONLY_GIT_ENV, }); - const cwdWorktree = await normalizePathForOwnership(toplevel.trim()); + const cwdWorktree = await normalizePathForOwnership(toplevel.replace(/\r?\n$/, "")); const worktrees: GitWorktree[] = []; - for (const entry of parseWorktreeEntries(stdout)) { + for (const entry of entries) { if (entry.unusable) continue; // A locked worktree whose directory was deleted is neither prunable nor workable. if (!(await pathExists(entry.path))) continue; @@ -1190,16 +1227,13 @@ export async function listPaseoWorktrees({ worktreesRoot?: string; }): Promise { const projectWorktreesRoot = await getPaseoWorktreesRoot(cwd, paseoHome, worktreesRoot); - const { stdout } = await runGitCommand(["worktree", "list", "--porcelain"], { - cwd, - envOverlay: READ_ONLY_GIT_ENV, - }); + const { entries } = await readGitWorktreeEntries(cwd); const mainCheckoutPath = await resolveRepoRootFromGitCommonDir(await getGitCommonDir(cwd)); const roots = await ownershipPathVariants(projectWorktreesRoot); const worktrees: PaseoWorktreeInfo[] = []; // Inspect foreign paths sequentially; a large worktree list must not consume the FS pool. - for (const entry of parseWorktreeList(stdout)) { + for (const { unusable: _unusable, ...entry } of entries) { const path = await normalizePathForOwnership(entry.path); if ( !roots.some((root) => getRelativePathInsideRoot(root, path) !== null) && @@ -1211,6 +1245,21 @@ export async function listPaseoWorktrees({ return worktrees; } +/** + * Exact normalized paths of all currently registered worktrees for the repo containing `cwd`. + * Returns `null` on Git <= 2.35 where `--porcelain -z` is unavailable, so manager checkout + * falls back to built-in Git rather than trusting an inexact snapshot for adoption or rollback. + */ +async function listExactGitWorktreePaths(cwd: string): Promise | null> { + const { entries, exact } = await readGitWorktreeEntries(cwd); + if (!exact) return null; + const paths = new Set(); + for (const entry of entries) { + paths.add(normalizePathForIdentity(entry.path)); + } + return paths; +} + export interface DeletePaseoWorktreeOptions { cwd: string | null; worktreePath?: string; @@ -1225,6 +1274,11 @@ export interface DeletePaseoWorktreeOptions { // gone, where the marker proof can no longer be verified. Only pass // this when the record was matched against the path by the caller. registryProven?: boolean; + worktreeManagers?: Pick; + worktreeManagerPluginId?: string | null; + removeReason?: "archive" | "rollback"; + untrusted?: boolean; + signal?: AbortSignal; } // Project scoping for delete: a proof for some other repo's worktree must @@ -1280,6 +1334,11 @@ export async function deletePaseoWorktree({ paseoHome, worktreesBaseRoot, registryProven, + worktreeManagers, + worktreeManagerPluginId, + removeReason = "archive", + untrusted = false, + signal, }: DeletePaseoWorktreeOptions): Promise { if (!worktreePath && !worktreeSlug) { throw new Error("worktreePath or worktreeSlug is required"); @@ -1320,17 +1379,19 @@ export async function deletePaseoWorktree({ } if (await pathExists(resolvedWorktree)) { - for (const teardownCwd of teardownCwds ?? [resolvedWorktree]) { - await runWorktreeTeardownCommands({ - worktreePath: resolvedWorktree, - teardownCwd, - }); - } - const commit = await readWorktreeHead(resolvedWorktree); - if (commit) { - await runGitCommand(["update-ref", `refs/paseo/kept-commits/${commit}`, commit], { - cwd: resolvedWorktree, - }); + const removedByPlugin = await prepareAndTryPluginWorktreeRemove({ + cwd, + resolvedWorktree, + teardownCwds, + worktreeManagers, + worktreeManagerPluginId, + removeReason, + untrusted, + signal, + }); + if (removedByPlugin) { + await pruneWorktreesBestEffort(cwd); + return; } } @@ -1349,16 +1410,124 @@ export async function deletePaseoWorktree({ } await removeDirectoryWithRetries(resolvedWorktree); + await pruneWorktreesBestEffort(cwd); +} - if (cwd) { +async function assertNoNestedLinkedWorktrees(worktreePath: string): Promise { + const pending = [worktreePath]; + for (let directory = pending.pop(); directory !== undefined; directory = pending.pop()) { + let entries: Dirent[]; try { - await runGitCommand(["worktree", "prune"], { cwd, timeout: 30_000 }); - } catch { - // not critical; git will prune lazily + entries = await readdir(directory, { withFileTypes: true }); + } catch (error) { + if ((error as NodeJS.ErrnoException).code === "ENOENT") continue; + throw error; + } + if ( + directory !== worktreePath && + entries.some((entry) => entry.name === ".git" && !entry.isDirectory()) && + (await isLinkedGitWorktree(directory)) + ) { + throw new Error( + `Refusing to delete worktree ${worktreePath}: contains nested Git worktree ${directory}`, + ); + } + for (const entry of entries) { + if (entry.name !== ".git" && entry.isDirectory()) { + pending.push(join(directory, entry.name)); + } } } } +async function isLinkedGitWorktree(directory: string): Promise { + // A linked worktree's Git directory contains a commondir file pointing to the + // shared repository. A submodule or a clone with a separate Git directory + // uses its own Git directory as the common directory. + const result = await runGitCommand( + ["rev-parse", "--path-format=absolute", "--git-path", "commondir"], + { cwd: directory, envOverlay: READ_ONLY_GIT_ENV }, + ).catch(() => null); + return result !== null && (await pathExists(result.stdout.replace(/\r?\n$/, ""))); +} + +async function pruneWorktreesBestEffort(cwd: string | null): Promise { + if (!cwd) return; + try { + await runGitCommand(["worktree", "prune"], { cwd, timeout: 30_000 }); + } catch { + // not critical; git will prune lazily + } +} + +async function prepareAndTryPluginWorktreeRemove(options: { + cwd: string | null; + resolvedWorktree: string; + teardownCwds?: string[]; + worktreeManagers?: Pick; + worktreeManagerPluginId?: string | null; + removeReason: "archive" | "rollback"; + untrusted: boolean; + signal?: AbortSignal; +}): Promise { + const { + cwd, + resolvedWorktree, + teardownCwds, + worktreeManagers, + worktreeManagerPluginId, + removeReason, + untrusted, + signal, + } = options; + for (const teardownCwd of teardownCwds ?? [resolvedWorktree]) { + await runWorktreeTeardownCommands({ + worktreePath: resolvedWorktree, + teardownCwd, + }); + } + const effectiveManagerPluginId = + worktreeManagerPluginId !== undefined + ? worktreeManagerPluginId + : ((await readPaseoWorktreeMetadata(resolvedWorktree).catch(() => null)) + ?.worktreeManagerPluginId ?? null); + if (effectiveManagerPluginId) { + await assertNoNestedLinkedWorktrees(resolvedWorktree); + } + const branch = effectiveManagerPluginId + ? await getCurrentBranch(resolvedWorktree).catch(() => null) + : null; + const commit = await readWorktreeHead(resolvedWorktree); + if (commit) { + await runGitCommand(["update-ref", `refs/paseo/kept-commits/${commit}`, commit], { + cwd: resolvedWorktree, + }); + } + if (!effectiveManagerPluginId || !worktreeManagers) { + return false; + } + const removedByPlugin = await worktreeManagers.removeWorktree( + { + repoRoot: cwd, + path: resolvedWorktree, + branch, + reason: removeReason, + force: true, + untrusted, + }, + { preferredPluginId: effectiveManagerPluginId, signal }, + ); + if (removedByPlugin === null) { + return false; + } + if (await pathExists(resolvedWorktree)) { + throw new Error( + `Plugin ${removedByPlugin.pluginId} worktree.remove reported removed, but the directory still exists: ${resolvedWorktree}`, + ); + } + return true; +} + export async function rollbackCreatedPaseoWorktree( options: DeletePaseoWorktreeOptions, cause: unknown, @@ -1494,6 +1663,7 @@ export function createWorktree( export async function createWorktree({ cwd, source, + preparedBranchOff, worktreeSlug, paseoHome, worktreesRoot, @@ -1507,7 +1677,12 @@ export async function createWorktree({ source.kind === "checkout-github-pr" ? await listLocalBranchNames(cwd) : new Set(); - const sourcePlan = await resolveWorktreeSourcePlan({ cwd, source, desiredSlug: worktreeSlug }); + const sourcePlan = await resolveWorktreeSourcePlan({ + cwd, + source, + desiredSlug: worktreeSlug, + preparedBranchOff, + }); const fetchedBranch = planCreatedLocalBranch(source, sourcePlan); const fetchedTip = fetchedBranch && !branchesBefore.has(fetchedBranch) @@ -1526,19 +1701,8 @@ export async function createWorktree({ }); worktreePath = await normalizePathForOwnership(worktreePath); - if (sourcePlan.pushRemote && sourcePlan.branchName) { - await configureWorktreePushRemote({ - cwd, - branchName: sourcePlan.branchName, - remote: sourcePlan.pushRemote, - }); - } - if (sourcePlan.trackingRemote && sourcePlan.branchName) { - await configureWorktreeTrackingRemote({ - cwd, - branchName: sourcePlan.branchName, - remote: sourcePlan.trackingRemote, - }); + if (sourcePlan.branchName) { + await applyWorktreeRemotePlan(cwd, sourcePlan.branchName, sourcePlan); } await writePaseoWorktreeMetadata(worktreePath, { @@ -1568,10 +1732,523 @@ export async function createWorktree({ } } +interface AdoptPluginWorktreeOptions { + cwd: string; + source: WorktreeSource; + worktreePath: string; + worktreeManagerPluginId: string; + /** Worktree paths that existed before creation; an overlap fails instead of hijacking user worktrees. */ + existingWorktreePaths?: ReadonlySet; + /** Remote head commit resolved before invoking the manager for change-request checkouts (`null` if unresolvable). */ + expectedChangeRequestHeadSha?: string | null; +} + +export interface RunPluginWorktreeManagerCheckoutOptions< + Source extends WorktreeSource = WorktreeSource, +> { + cwd: string; + source: Source; + operation: "create" | "restore"; + preferredPluginId?: string; + untrusted: boolean; + paseoHome?: string; + worktreesBaseRoot?: string; + worktreeManagers?: Pick; + run: (context: { + changeRequestHeadSha?: string; + }) => Promise<{ pluginId: string; path: string } | null>; + verifyValidatedPath?: (validatedPath: string, pluginId: string) => void; +} + +/** + * Run a worktree manager plugin's `create` or `restore` callback with a single + * shared sequence: capability guard, pre-call snapshot, Git validation and + * adoption, and rollback of a checkout reported by the manager. + * Returns `null` without spawning Git when no eligible manager is registered + * or when the manager declines. + */ +export function runPluginWorktreeManagerCheckout( + options: RunPluginWorktreeManagerCheckoutOptions< + Exclude + >, +): Promise; +export function runPluginWorktreeManagerCheckout( + options: RunPluginWorktreeManagerCheckoutOptions, +): Promise<(Omit & { branchName: string | null }) | null>; +export async function runPluginWorktreeManagerCheckout( + options: RunPluginWorktreeManagerCheckoutOptions, +): Promise<(Omit & { branchName: string | null }) | null> { + const { + cwd, + source, + operation, + preferredPluginId, + untrusted, + paseoHome, + worktreesBaseRoot, + worktreeManagers, + run, + verifyValidatedPath, + } = options; + if (!worktreeManagers?.hasWorktreeManager({ operation, preferredPluginId })) { + return null; + } + const existingWorktreePaths = await listExactGitWorktreePaths(cwd); + if (!existingWorktreePaths) { + return null; + } + const expectedChangeRequestHeadSha = + operation === "create" && + (source.kind === "checkout-change-request" || source.kind === "checkout-github-pr") + ? await fetchChangeRequestHeadSha(cwd, source) + : undefined; + const managed = await run( + expectedChangeRequestHeadSha ? { changeRequestHeadSha: expectedChangeRequestHeadSha } : {}, + ); + if (!managed) return null; + try { + const validatedPath = await validateWorktreePath({ + candidate: managed.path, + repoPath: cwd, + allowExistingPath: true, + }).catch((error: unknown) => { + const detail = error instanceof Error ? error.message : String(error); + throw new Error(`Plugin ${managed.pluginId} worktree.${operation} failed: ${detail}`, { + cause: error, + }); + }); + verifyValidatedPath?.(validatedPath, managed.pluginId); + return await adoptPluginWorktree({ + cwd, + source, + worktreePath: validatedPath, + worktreeManagerPluginId: managed.pluginId, + existingWorktreePaths, + expectedChangeRequestHeadSha, + }); + } catch (error) { + return cleanupFailedPluginWorktree( + { + cwd, + candidatePath: managed.path, + existingWorktreePaths, + worktreeManagers, + worktreeManagerPluginId: managed.pluginId, + untrusted, + paseoHome, + worktreesBaseRoot, + }, + error, + ); + } +} + +/** + * Roll back a newly created worktree that failed adoption or path verification. + * Only touches a directory that was absent from `existingWorktreePaths` and + * shares the source repository's Git common dir; preserves rollback failures + * alongside the adoption error via `rollbackCreatedPaseoWorktree`. + */ +async function cleanupFailedPluginWorktree( + options: { + cwd: string; + candidatePath: string; + existingWorktreePaths?: ReadonlySet; + worktreeManagers?: Pick; + worktreeManagerPluginId: string; + untrusted?: boolean; + paseoHome?: string; + worktreesBaseRoot?: string; + }, + cause: unknown, +): Promise { + const { + cwd, + candidatePath, + existingWorktreePaths, + worktreeManagers, + worktreeManagerPluginId, + untrusted, + paseoHome, + worktreesBaseRoot, + } = options; + let rootPath: string; + try { + const { stdout } = await runGitCommand(["rev-parse", "--show-toplevel"], { + cwd: candidatePath, + }); + rootPath = await normalizePathForOwnership(stdout.replace(/\r?\n$/, "")); + } catch { + throw cause; + } + const rootIdentity = normalizePathForIdentity(rootPath); + if ( + !createRealpathAwarePathMatcher(rootPath)(candidatePath) || + Array.from(existingWorktreePaths ?? []).some( + (existing) => existing === rootIdentity || isPathInsideRoot(rootIdentity, existing), + ) + ) { + throw cause; + } + const [worktreeCommonDir, repoCommonDir] = await Promise.all([ + getGitCommonDir(rootPath).catch(() => null), + getGitCommonDir(cwd).catch(() => null), + ]); + if ( + !worktreeCommonDir || + !repoCommonDir || + !createRealpathAwarePathMatcher(worktreeCommonDir)(repoCommonDir) + ) { + throw cause; + } + return rollbackCreatedPaseoWorktree( + { + cwd, + worktreePath: rootPath, + teardownCwds: [], + paseoHome, + worktreesBaseRoot, + registryProven: true, + worktreeManagers, + worktreeManagerPluginId, + removeReason: "rollback", + untrusted, + }, + cause, + ); +} + +async function assertNonOverlappingWorktreePath(input: { + worktreeManagerPluginId: string; + normalizedPath: string; + normalizedIdentity: string; + repoCommonDir: string; + existingWorktreePaths: ReadonlySet | undefined; +}): Promise { + const { + worktreeManagerPluginId, + normalizedPath, + normalizedIdentity, + repoCommonDir, + existingWorktreePaths, + } = input; + if (!existingWorktreePaths) return; + const mainRepoRoot = await resolveRepoRootFromGitCommonDir(repoCommonDir).catch(() => undefined); + const mainRepoIdentity = mainRepoRoot ? normalizePathForIdentity(mainRepoRoot) : null; + for (const existing of existingWorktreePaths) { + if (isPathInsideRoot(normalizedIdentity, existing)) { + throw new Error( + `Plugin ${worktreeManagerPluginId} created a worktree enclosing an existing worktree (${existing}): ${normalizedPath}`, + ); + } + if (existing !== mainRepoIdentity && isPathInsideRoot(existing, normalizedIdentity)) { + throw new Error( + `Plugin ${worktreeManagerPluginId} created a worktree nested inside an existing worktree (${existing}): ${normalizedPath}`, + ); + } + } +} + +/** + * Verify and adopt a worktree created or restored by a worktree manager plugin. + * Paseo validates Git worktree postconditions and writes `paseo/worktree.json` + * so diffs, PR/MR lookup hints, listing, ownership, and removal continue to work. + */ +async function adoptPluginWorktree( + options: AdoptPluginWorktreeOptions, +): Promise & { branchName: string | null }> { + const { + cwd, + source, + worktreePath, + worktreeManagerPluginId, + existingWorktreePaths, + expectedChangeRequestHeadSha, + } = options; + const normalizedPath = await normalizePathForOwnership(worktreePath); + const normalizedIdentity = normalizePathForIdentity(normalizedPath); + if (existingWorktreePaths?.has(normalizedIdentity)) { + throw new Error( + `Plugin ${worktreeManagerPluginId} returned an already-existing worktree: ${normalizedPath}`, + ); + } + const { stdout: rootStdout } = await runGitCommand(["rev-parse", "--show-toplevel"], { + cwd: normalizedPath, + }).catch(() => { + throw new Error( + `Plugin ${worktreeManagerPluginId} did not create a Git worktree at: ${normalizedPath}`, + ); + }); + if (!createRealpathAwarePathMatcher(rootStdout.replace(/\r?\n$/, ""))(normalizedPath)) { + throw new Error( + `Plugin ${worktreeManagerPluginId} created a worktree whose root is not the returned path: ${normalizedPath}`, + ); + } + const [worktreeCommonDir, repoCommonDir] = await Promise.all([ + getGitCommonDir(normalizedPath), + getGitCommonDir(cwd), + ]); + if (!createRealpathAwarePathMatcher(worktreeCommonDir)(repoCommonDir)) { + throw new Error( + `Plugin ${worktreeManagerPluginId} created a worktree outside the repository: ${normalizedPath}`, + ); + } + await assertNonOverlappingWorktreePath({ + worktreeManagerPluginId, + normalizedPath, + normalizedIdentity, + repoCommonDir, + existingWorktreePaths, + }); + const { stdout: branchStdout } = await runGitCommand(["rev-parse", "--abbrev-ref", "HEAD"], { + cwd: normalizedPath, + }); + const rawBranch = branchStdout.trim(); + const detached = !rawBranch || rawBranch === "HEAD"; + if (detached && source.kind !== "restore-commit") { + throw new Error( + `Plugin ${worktreeManagerPluginId} created a worktree with a detached HEAD: ${normalizedPath}`, + ); + } + const branchName = detached ? null : rawBranch; + + await verifyPluginCheckoutTarget({ + cwd, + source, + worktreePath: normalizedPath, + branchName, + worktreeManagerPluginId, + expectedChangeRequestHeadSha, + }); + + if ( + (source.kind === "checkout-change-request" || source.kind === "checkout-github-pr") && + branchName + ) { + const remotePlan = await resolveChangeRequestRemotePlan(cwd, source, branchName); + await applyWorktreeRemotePlan(cwd, branchName, remotePlan); + } + + const metadata = await resolveWorktreeMetadata({ cwd, source, branchName }); + await writePaseoWorktreeMetadata(normalizedPath, { + baseRefName: metadata.metadataBaseRefName, + ...(metadata.metadataBaseRef ? { baseRef: metadata.metadataBaseRef } : {}), + ...(metadata.changeRequestLookupTarget + ? { changeRequestLookupTarget: metadata.changeRequestLookupTarget } + : {}), + worktreeManagerPluginId, + }); + await seedPaseoConfigFile({ sourceCwd: cwd, targetCwd: normalizedPath }); + + return { + branchName, + worktreePath: normalizedPath, + comparisonBaseRef: metadata.metadataBaseRef ?? metadata.metadataBaseRefName, + worktreeManagerPluginId, + }; +} + +/** + * Fetch the remote change-request head once into `refs/paseo/change-requests/` so both the + * worktree manager (via `request.headSha`) and adoption verification agree on one commit. + */ +async function fetchChangeRequestHeadSha( + cwd: string, + source: Extract, +): Promise { + const changeRequestNumber = + source.kind === "checkout-github-pr" ? source.githubPrNumber : source.changeRequestNumber; + const destination = `refs/paseo/change-requests/${changeRequestNumber}`; + await fetchFirstAvailableRef({ + cwd, + destination, + sources: source.checkoutRefs ?? [ + { remoteName: "origin", remoteRef: `refs/pull/${changeRequestNumber}/head` }, + ], + }); + const { stdout } = await runGitCommand(["rev-parse", "--verify", `${destination}^{commit}`], { + cwd, + }); + return stdout.trim(); +} + +async function verifyPluginChangeRequestHead(options: { + cwd: string; + source: Extract; + worktreePath: string; + worktreeManagerPluginId: string; + expectedChangeRequestHeadSha?: string | null; +}): Promise { + const { cwd, source, worktreePath, worktreeManagerPluginId, expectedChangeRequestHeadSha } = + options; + const expectedHead = + expectedChangeRequestHeadSha ?? (await fetchChangeRequestHeadSha(cwd, source)); + const { stdout: headStdout } = await runGitCommand(["rev-parse", "--verify", "HEAD^{commit}"], { + cwd: worktreePath, + }); + const actualHead = headStdout.trim(); + if (actualHead !== expectedHead) { + throw new Error( + `Plugin ${worktreeManagerPluginId} checked out ${actualHead}, expected change request head ${expectedHead}`, + ); + } +} + +async function verifyPluginCheckoutTarget(options: { + cwd: string; + source: WorktreeSource; + worktreePath: string; + branchName: string | null; + worktreeManagerPluginId: string; + expectedChangeRequestHeadSha?: string | null; +}): Promise { + const { + cwd, + source, + worktreePath, + branchName, + worktreeManagerPluginId, + expectedChangeRequestHeadSha, + } = options; + if (source.kind === "checkout-change-request" || source.kind === "checkout-github-pr") { + return verifyPluginChangeRequestHead({ + cwd, + source, + worktreePath, + worktreeManagerPluginId, + expectedChangeRequestHeadSha, + }); + } + if (source.kind === "restore" || source.kind === "restore-from-base") { + if (branchName !== source.branchName) { + throw new Error( + `Plugin ${worktreeManagerPluginId} restored ${branchName ?? "detached HEAD"}, expected branch ${source.branchName}`, + ); + } + } + if (source.kind === "restore-commit" || source.kind === "restore-from-base") { + const target = + source.kind === "restore-commit" + ? source.commit + : await resolveBaseBranchForWorktree(cwd, source.baseRef); + const [head, expected] = await Promise.all([ + runGitCommand(["rev-parse", "--verify", "HEAD^{commit}"], { cwd: worktreePath }), + runGitCommand(["rev-parse", "--verify", `${target}^{commit}`], { cwd }), + ]); + if ( + head.stdout.trim() !== expected.stdout.trim() || + (source.kind === "restore-commit" && branchName !== null) + ) { + const description = source.kind === "restore-commit" ? "detached commit" : "base commit"; + throw new Error( + `Plugin ${worktreeManagerPluginId} did not restore the expected ${description} ${expected.stdout.trim()}`, + ); + } + } +} + +async function tryResolveExactBaseRef(cwd: string, ref: string): Promise { + try { + return await resolveBaseBranchForWorktree(cwd, ref); + } catch { + return undefined; + } +} + +function branchChangeRequestHint( + branchName: string | null, +): { changeRequestLookupTarget: PaseoWorktreeChangeRequestHint } | Record { + if (!branchName) return {}; + return { + changeRequestLookupTarget: createPaseoWorktreeChangeRequestHint({ + headRef: branchName, + localBranchName: branchName, + }), + }; +} + +interface ResolvedWorktreeMetadata { + metadataBaseRefName: string; + metadataBaseRef?: string; + changeRequestLookupTarget?: PaseoWorktreeChangeRequestHint; +} + +function resolveChangeRequestMetadata( + source: Extract, + branchName: string | null, +): ResolvedWorktreeMetadata { + const changeRequestNumber = + source.kind === "checkout-github-pr" ? source.githubPrNumber : source.changeRequestNumber; + return { + metadataBaseRefName: normalizeRequiredBaseBranch(source.baseRefName), + changeRequestLookupTarget: createPaseoWorktreeChangeRequestHint({ + headRef: source.headRef, + ...(source.headRepositoryOwner ? { headRepositoryOwner: source.headRepositoryOwner } : {}), + changeRequestNumber, + ...(branchName ? { localBranchName: branchName } : {}), + }), + }; +} + +/** + * Single source of truth for worktree comparison-base and change-request metadata, + * shared between built-in Git checkout plans and plugin worktree adoption. + */ +async function resolveWorktreeMetadata(options: { + cwd: string; + source: WorktreeSource; + branchName: string | null; + resolvedBaseRef?: string; +}): Promise { + const { cwd, source, branchName, resolvedBaseRef } = options; + if (source.kind === "checkout-change-request" || source.kind === "checkout-github-pr") { + return resolveChangeRequestMetadata(source, branchName); + } + if (source.kind === "checkout-branch") { + const resolvedBranch = branchName ?? source.branchName; + const metadataBaseRefName = + resolvedBaseRef ?? (await resolveCheckoutBranchBaseRef(cwd, resolvedBranch)); + return { metadataBaseRefName, ...branchChangeRequestHint(resolvedBranch) }; + } + if (source.kind === "branch-off") { + const metadataBaseRefName = normalizeRequiredBaseBranch(source.baseBranch); + const metadataBaseRef = + resolvedBaseRef ?? (await tryResolveExactBaseRef(cwd, source.baseBranch)); + return { + metadataBaseRefName, + ...(metadataBaseRef ? { metadataBaseRef } : {}), + ...branchChangeRequestHint(branchName), + }; + } + if (source.kind === "restore") { + const metadataBaseRefName = normalizeRequiredBaseBranch( + source.baseRef ?? branchName ?? source.branchName, + ); + const metadataBaseRef = + resolvedBaseRef ?? + (source.baseRef && isQualifiedRef(source.baseRef) + ? await tryResolveExactBaseRef(cwd, source.baseRef) + : undefined); + return { + metadataBaseRefName, + ...(metadataBaseRef ? { metadataBaseRef } : {}), + ...branchChangeRequestHint(branchName), + }; + } + const metadataBaseRefName = normalizeRequiredBaseBranch(source.baseRef); + const metadataBaseRef = + resolvedBaseRef ?? + (source.kind === "restore-from-base" || isQualifiedRef(source.baseRef) + ? await tryResolveExactBaseRef(cwd, source.baseRef) + : undefined); + return { metadataBaseRefName, ...(metadataBaseRef ? { metadataBaseRef } : {}) }; +} + interface ResolveWorktreeSourcePlanOptions { cwd: string; source: WorktreeSource; desiredSlug: string; + preparedBranchOff?: PreparedWorktreeBranchOff; } interface WorktreeSourcePlan { @@ -1604,22 +2281,10 @@ async function resolveRestoredWorktreeSourcePlan( if (await isBranchCheckedOut(cwd, source.branchName)) { throw new BranchAlreadyCheckedOutError(source.branchName); } - let exactBase: string | undefined; - if (source.baseRef && isQualifiedRef(source.baseRef)) { - try { - exactBase = await resolveBaseBranchForWorktree(cwd, source.baseRef); - } catch { - // Restore the saved branch even when its comparison ref no longer exists. - } - } + const metadata = await resolveWorktreeMetadata({ cwd, source, branchName: source.branchName }); return { branchName: source.branchName, - metadataBaseRefName: normalizeRequiredBaseBranch(source.baseRef ?? source.branchName), - ...(exactBase ? { metadataBaseRef: exactBase } : {}), - changeRequestLookupTarget: createPaseoWorktreeChangeRequestHint({ - headRef: source.branchName, - localBranchName: source.branchName, - }), + ...metadata, addArguments: [source.branchName], }; } @@ -1628,18 +2293,10 @@ async function resolveRestoredCommitSourcePlan( cwd: string, source: Extract, ): Promise { - let exactBase: string | undefined; - if (isQualifiedRef(source.baseRef)) { - try { - exactBase = await resolveBaseBranchForWorktree(cwd, source.baseRef); - } catch { - // Restore the saved commit even when its comparison ref no longer exists. - } - } + const metadata = await resolveWorktreeMetadata({ cwd, source, branchName: null }); return { branchName: null, - metadataBaseRefName: normalizeRequiredBaseBranch(source.baseRef), - ...(exactBase ? { metadataBaseRef: exactBase } : {}), + ...metadata, addArguments: ["--detach", source.commit], }; } @@ -1651,38 +2308,59 @@ async function resolveRestoredWorktreeFromBasePlan( await validateGitBranchName(cwd, source.branchName); const baseRef = await resolveBaseBranchForWorktree(cwd, source.baseRef); const branchName = await resolveUniqueLocalBranchName(cwd, source.branchName); + const metadata = await resolveWorktreeMetadata({ + cwd, + source, + branchName, + resolvedBaseRef: baseRef, + }); return { branchName, - metadataBaseRefName: normalizeRequiredBaseBranch(source.baseRef), - metadataBaseRef: baseRef, + ...metadata, addArguments: ["-b", branchName, "--no-track", baseRef], }; } +export async function prepareWorktreeBranchOff( + cwd: string, + source: Extract, + previous?: PreparedWorktreeBranchOff, +): Promise { + const baseRef = previous?.baseRef ?? (await resolveBaseBranchForWorktree(cwd, source.baseBranch)); + const branchExists = await localBranchExists(cwd, source.branchName); + const checkoutRef = branchExists ? source.branchName : (source.startPoint ?? baseRef); + if (checkoutRef !== previous?.checkoutRef) { + await refreshRemoteTrackingBaseRef(cwd, checkoutRef); + } + return { baseRef, branchExists, checkoutRef }; +} + async function resolveBranchOffWorktreeSourcePlan( cwd: string, source: Extract, desiredSlug: string, + preparedBranchOff?: PreparedWorktreeBranchOff, ): Promise { const branchName = source.branchName; await validateGitBranchName(cwd, branchName); - const normalizedBaseBranch = normalizeRequiredBaseBranch(source.baseBranch); - const resolvedBaseBranch = await resolveBaseBranchForWorktree(cwd, source.baseBranch); - const branchExists = await localBranchExists(cwd, branchName); - const base = branchExists ? branchName : (source.startPoint ?? resolvedBaseBranch); - await refreshRemoteTrackingBaseRef(cwd, base); + const { baseRef, branchExists, checkoutRef } = await prepareWorktreeBranchOff( + cwd, + source, + preparedBranchOff, + ); const candidateBranch = branchExists ? desiredSlug : branchName; const newBranchName = await resolveUniqueLocalBranchName(cwd, candidateBranch); + const metadata = await resolveWorktreeMetadata({ + cwd, + source, + branchName: newBranchName, + resolvedBaseRef: baseRef, + }); return { branchName: newBranchName, - metadataBaseRefName: normalizedBaseBranch, - metadataBaseRef: resolvedBaseBranch, - changeRequestLookupTarget: createPaseoWorktreeChangeRequestHint({ - headRef: newBranchName, - localBranchName: newBranchName, - }), - addArguments: ["-b", newBranchName, "--no-track", base], + ...metadata, + addArguments: ["-b", newBranchName, "--no-track", checkoutRef], }; } @@ -1690,10 +2368,11 @@ async function resolveWorktreeSourcePlan({ cwd, source, desiredSlug, + preparedBranchOff, }: ResolveWorktreeSourcePlanOptions): Promise { switch (source.kind) { case "branch-off": - return resolveBranchOffWorktreeSourcePlan(cwd, source, desiredSlug); + return resolveBranchOffWorktreeSourcePlan(cwd, source, desiredSlug, preparedBranchOff); case "restore": return resolveRestoredWorktreeSourcePlan(cwd, source); case "restore-commit": @@ -1706,24 +2385,28 @@ async function resolveWorktreeSourcePlan({ const baseRef = await resolveCheckoutBranchBaseRef(cwd, source.branchName); if (await isBranchCheckedOut(cwd, source.branchName)) { const branchName = await resolveUniqueLocalBranchName(cwd, source.branchName); + const metadata = await resolveWorktreeMetadata({ + cwd, + source, + branchName, + resolvedBaseRef: baseRef, + }); return { branchName, - metadataBaseRefName: baseRef, - changeRequestLookupTarget: createPaseoWorktreeChangeRequestHint({ - headRef: branchName, - localBranchName: branchName, - }), + ...metadata, addArguments: ["-b", branchName, "--no-track", source.branchName], }; } + const metadata = await resolveWorktreeMetadata({ + cwd, + source, + branchName: source.branchName, + resolvedBaseRef: baseRef, + }); return { branchName: source.branchName, - metadataBaseRefName: baseRef, - changeRequestLookupTarget: createPaseoWorktreeChangeRequestHint({ - headRef: source.branchName, - localBranchName: source.branchName, - }), + ...metadata, addArguments: [source.branchName], }; } @@ -1732,7 +2415,6 @@ async function resolveWorktreeSourcePlan({ const localBranchCandidate = source.localBranchName ?? source.headRef; await validateGitBranchName(cwd, localBranchCandidate); const localBranchName = await resolveUniqueLocalBranchName(cwd, localBranchCandidate); - const normalizedBaseRefName = normalizeRequiredBaseBranch(source.baseRefName); const changeRequestNumber = source.kind === "checkout-github-pr" ? source.githubPrNumber : source.changeRequestNumber; await fetchFirstAvailableRef({ @@ -1742,49 +2424,16 @@ async function resolveWorktreeSourcePlan({ { remoteName: "origin", remoteRef: `refs/pull/${changeRequestNumber}/head` }, ], }); - const shouldTrackOriginHead = source.trackOriginHead === true; - const trackingRemote = shouldTrackOriginHead - ? await tryFetchWorktreeTrackingRemote({ - cwd, - remoteName: "origin", - headRef: source.headRef, - }) - : undefined; - const remotePlan: Pick = {}; - if (source.pushRemoteUrl) { - const remoteName = `paseo-pr-${changeRequestNumber}`; - remotePlan.pushRemote = { - name: remoteName, - url: source.pushRemoteUrl, - headRef: source.headRef, - track: true, - }; - } else if (shouldTrackOriginHead && localBranchName !== source.headRef) { - const originUrl = await getWorktreeRemotePushUrl(cwd, "origin"); - if (originUrl) { - remotePlan.pushRemote = { - name: `paseo-pr-${changeRequestNumber}`, - url: originUrl, - headRef: source.headRef, - track: false, - }; - } - } - if (trackingRemote) { - remotePlan.trackingRemote = trackingRemote; - } + const remotePlan = await resolveChangeRequestRemotePlan(cwd, source, localBranchName); + const metadata = await resolveWorktreeMetadata({ + cwd, + source, + branchName: localBranchName, + }); return { branchName: localBranchName, - metadataBaseRefName: normalizedBaseRefName, - changeRequestLookupTarget: createPaseoWorktreeChangeRequestHint({ - headRef: source.headRef, - ...(source.headRepositoryOwner - ? { headRepositoryOwner: source.headRepositoryOwner } - : {}), - changeRequestNumber, - localBranchName, - }), + ...metadata, addArguments: [localBranchName], ...remotePlan, }; @@ -1792,6 +2441,67 @@ async function resolveWorktreeSourcePlan({ } } +async function resolveChangeRequestRemotePlan( + cwd: string, + source: Extract, + localBranchName: string, +): Promise> { + const changeRequestNumber = + source.kind === "checkout-github-pr" ? source.githubPrNumber : source.changeRequestNumber; + const shouldTrackOriginHead = source.trackOriginHead === true; + const trackingRemote = shouldTrackOriginHead + ? await tryFetchWorktreeTrackingRemote({ + cwd, + remoteName: "origin", + headRef: source.headRef, + }) + : undefined; + const remotePlan: Pick = {}; + if (source.pushRemoteUrl) { + remotePlan.pushRemote = { + name: `paseo-pr-${changeRequestNumber}`, + url: source.pushRemoteUrl, + headRef: source.headRef, + track: true, + }; + } else if (shouldTrackOriginHead && localBranchName !== source.headRef) { + const originUrl = await getWorktreeRemotePushUrl(cwd, "origin"); + if (originUrl) { + remotePlan.pushRemote = { + name: `paseo-pr-${changeRequestNumber}`, + url: originUrl, + headRef: source.headRef, + track: false, + }; + } + } + if (trackingRemote) { + remotePlan.trackingRemote = trackingRemote; + } + return remotePlan; +} + +async function applyWorktreeRemotePlan( + cwd: string, + branchName: string, + remotePlan: Pick, +): Promise { + if (remotePlan.pushRemote) { + await configureWorktreePushRemote({ + cwd, + branchName, + remote: remotePlan.pushRemote, + }); + } + if (remotePlan.trackingRemote) { + await configureWorktreeTrackingRemote({ + cwd, + branchName, + remote: remotePlan.trackingRemote, + }); + } +} + async function configureWorktreePushRemote(options: { cwd: string; branchName: string; @@ -2140,9 +2850,6 @@ async function resolveUniqueLocalBranchName(cwd: string, candidateBranch: string } async function isBranchCheckedOut(cwd: string, branchName: string): Promise { - const { stdout } = await runGitCommand(["worktree", "list", "--porcelain"], { - cwd, - envOverlay: READ_ONLY_GIT_ENV, - }); - return parseWorktreeList(stdout).some((entry) => entry.branchName === branchName); + const { entries } = await readGitWorktreeEntries(cwd); + return entries.some((entry) => entry.branchName === branchName); } diff --git a/plugin-examples/worktrunk/README.md b/plugin-examples/worktrunk/README.md new file mode 100644 index 0000000000..38c7696936 --- /dev/null +++ b/plugin-examples/worktrunk/README.md @@ -0,0 +1,22 @@ +# Worktrunk plugin example + +Delegates Paseo worktree creation, removal, and restoration to [Worktrunk](https://worktrunk.dev) (`wt`), and updates `wt list` activity markers (`🤖` / `💬`) as agents run. + +## What it does + +- **Create:** routes branch-off, branch checkout, and change-request (PR/MR) creation through `wt switch --no-cd --format=json` (using Paseo's fetched `headSha` for PR/MR checkouts, and `--no-hooks` on untrusted fork checkouts) so Worktrunk controls placement, branch setup, and `pre-start` / `post-start` hooks. Local branch collisions decline and fall back to Paseo's Git checkout. +- **Remove:** routes archive and creation rollback through `wt remove --foreground --no-delete-branch --yes` so Worktrunk runs `pre-remove` and `post-remove` hooks while keeping the branch for Paseo's restore flow. +- **Restore:** routes archived worktree restoration through `wt switch --path ` for branch restores, and falls back to Paseo for detached-commit restores. +- **Activity markers:** sets `🤖` when an agent turn starts, `💬` when a turn ends or awaits permission, and clears the marker on close or archive. Background helpers are skipped. + +## Prerequisites + +Use [Worktrunk v0.82.0](https://github.com/max-sixty/worktrunk/releases/tag/v0.82.0) with Git 2.43.0 or later on the daemon host. + +Install Worktrunk (`wt`, or `git-wt.exe` on Windows) on `PATH`, or set `WORKTRUNK_BIN` in the daemon environment. + +## Install + +```bash +paseo plugin install /absolute/path/to/plugin-examples/worktrunk +``` diff --git a/plugin-examples/worktrunk/index.server.ts b/plugin-examples/worktrunk/index.server.ts new file mode 100644 index 0000000000..e85b803e80 --- /dev/null +++ b/plugin-examples/worktrunk/index.server.ts @@ -0,0 +1,44 @@ +import type { PluginServerContext } from "@getpaseo/plugin/server"; +import { + WAITING_MARKER, + WORKING_MARKER, + createWithWorktrunk, + removeWithWorktrunk, + restoreWithWorktrunk, + setActivityMarker, +} from "./server/wt.js"; + +export default function contribute(server: PluginServerContext) { + const cleanups = [ + server.registerWorktreeManager({ + create: (request, { signal }) => createWithWorktrunk(request, signal), + remove: (request, { signal }) => removeWithWorktrunk(request, signal), + restore: (request, { signal }) => restoreWithWorktrunk(request, signal), + }), + + server.addHook("agent.turn.before", async ({ agent }, { signal }) => { + if (agent.background) return; + await setActivityMarker(agent.cwd, WORKING_MARKER, signal); + }), + server.addHook("agent.turn.after", async ({ agent }, { signal }) => { + if (agent.background) return; + await setActivityMarker(agent.cwd, WAITING_MARKER, signal); + }), + server.addHook("agent.permission.before", async ({ agent }, { signal }) => { + if (agent.background) return; + await setActivityMarker(agent.cwd, WAITING_MARKER, signal); + }), + server.addHook("agent.close.after", async ({ agent }, { signal }) => { + if (agent.background) return; + await setActivityMarker(agent.cwd, null, signal); + }), + server.addHook("agent.archive.after", async ({ agent }, { signal }) => { + if (agent.background) return; + await setActivityMarker(agent.cwd, null, signal); + }), + ]; + + return () => { + for (const cleanup of cleanups) cleanup(); + }; +} diff --git a/plugin-examples/worktrunk/paseo-plugin.json b/plugin-examples/worktrunk/paseo-plugin.json new file mode 100644 index 0000000000..ca14710384 --- /dev/null +++ b/plugin-examples/worktrunk/paseo-plugin.json @@ -0,0 +1,6 @@ +{ + "id": "worktrunk", + "name": "Worktrunk", + "description": "Manage Git worktrees and agent activity markers through Worktrunk (wt).", + "requirements": { "paseo": ">=0.17.0" } +} diff --git a/plugin-examples/worktrunk/server/wt.ts b/plugin-examples/worktrunk/server/wt.ts new file mode 100644 index 0000000000..bfabb165c7 --- /dev/null +++ b/plugin-examples/worktrunk/server/wt.ts @@ -0,0 +1,317 @@ +import { lstatSync } from "node:fs"; +import { readFile, writeFile } from "node:fs/promises"; +import { delimiter, join } from "node:path"; +import { + execCommand, + type PluginWorktreeCreateInput, + type PluginWorktreeRemoveRequest, + type PluginWorktreeRestoreRequest, +} from "@getpaseo/plugin/server"; + +const MAX_OUTPUT_BYTES = 16 * 1024 * 1024; +const CREATED_BRANCH_FILE = "paseo-worktrunk-created-branch"; + +export const WORKING_MARKER = "🤖"; +export const WAITING_MARKER = "💬"; + +interface SwitchJsonOutput { + path: string; + action?: string; + branch?: string; + createdBranch: boolean; +} + +/** + * Resolve the Worktrunk CLI executable. + * Honors `WORKTRUNK_BIN` first; on Windows prefers `git-wt.exe` and skips the + * WindowsApps alias that points to Windows Terminal. + */ +export function resolveWorktrunkBin(): string | null { + const configured = process.env.WORKTRUNK_BIN?.trim(); + if (configured) return configured; + if (process.platform !== "win32") return "wt"; + + const dirs = (process.env.PATH ?? "").split(delimiter).filter(Boolean); + const findOnPath = (name: string) => + dirs + .map((dir) => join(dir, name)) + .find((candidate) => { + try { + lstatSync(candidate); + return true; + } catch { + return false; + } + }); + + if (findOnPath("git-wt.exe")) return "git-wt.exe"; + const wt = findOnPath("wt.exe"); + return wt && !/[\\/]WindowsApps[\\/]/i.test(wt) ? "wt" : null; +} + +async function runWt( + args: string[], + options: { cwd?: string; signal?: AbortSignal } = {}, +): Promise { + const bin = resolveWorktrunkBin(); + if (!bin) { + throw new Error( + "Worktrunk CLI not found on PATH. Install wt (or git-wt.exe on Windows) or set WORKTRUNK_BIN.", + ); + } + try { + const { stdout } = await execCommand(bin, args, { + cwd: options.cwd, + signal: options.signal, + maxBuffer: MAX_OUTPUT_BYTES, + }); + return stdout; + } catch (error) { + const stderr = (error as { stderr?: string }).stderr?.trim(); + throw new Error(stderr || (error instanceof Error ? error.message : String(error)), { + cause: error, + }); + } +} + +function tryParseSwitchOutput(stdout: string | undefined): SwitchJsonOutput | null { + if (!stdout?.trim()) return null; + try { + const parsed = JSON.parse(stdout) as { + path?: unknown; + action?: unknown; + branch?: unknown; + created_branch?: unknown; + from_remote?: unknown; + }; + if (typeof parsed.path !== "string" || parsed.path.length === 0) return null; + return { + path: parsed.path, + // Worktrunk sets from_remote when switch creates a branch that tracks a remote. + createdBranch: + parsed.created_branch === true || + (typeof parsed.from_remote === "string" && parsed.from_remote.length > 0), + ...(typeof parsed.branch === "string" && parsed.branch ? { branch: parsed.branch } : {}), + ...(typeof parsed.action === "string" ? { action: parsed.action } : {}), + }; + } catch { + return null; + } +} + +function parseSwitchOutput(stdout: string): SwitchJsonOutput { + const parsed = tryParseSwitchOutput(stdout); + if (!parsed) { + throw new Error("wt switch --format=json output did not include a worktree path"); + } + return parsed; +} + +function hookFlags(untrusted: boolean): string[] { + // Never approve repository-defined hooks on untrusted checkouts such as fork PRs. + return untrusted ? ["--no-hooks"] : ["--yes"]; +} + +export function buildCreateArgs(request: PluginWorktreeCreateInput): string[] | null { + const common = [ + "-C", + request.repoRoot, + "switch", + "--no-cd", + ...hookFlags(request.untrusted), + "--format=json", + ]; + switch (request.kind) { + case "branch-off": + return [ + ...common, + "--create", + request.branch, + "--base", + request.startPoint ?? request.baseRef, + ]; + case "checkout-branch": + return [...common, request.branch]; + case "checkout-change-request": + case "checkout-github-pr": + if (!request.headSha) return null; + return [...common, "--create", request.branch, "--base", request.headSha]; + } +} + +function failedSwitchOutput(error: unknown): SwitchJsonOutput | null { + // Worktrunk reports the checkout and whether it created the branch even if a hook fails. + const stdout = + error instanceof Error && error.cause && typeof error.cause === "object" + ? (error.cause as { stdout?: string }).stdout + : undefined; + return tryParseSwitchOutput(stdout); +} + +async function createdBranchFile(worktreePath: string): Promise { + const { stdout } = await execCommand("git", ["rev-parse", "--absolute-git-dir"], { + cwd: worktreePath, + }); + return join(stdout.trim(), CREATED_BRANCH_FILE); +} + +async function cleanupPartiallyCreatedWorktree( + repoRoot: string, + output: SwitchJsonOutput | null, +): Promise { + if (output?.action !== "created") return; + await runWt([ + "-C", + repoRoot, + "remove", + "--foreground", + "--no-delete-branch", + "--no-hooks", + "--force", + output.path, + ]); + if (output.createdBranch && output.branch) { + await execCommand("git", ["branch", "-D", "--", output.branch], { cwd: repoRoot }); + } +} + +async function recordCreatedBranch(repoRoot: string, output: SwitchJsonOutput): Promise { + if (output.action !== "created" || !output.createdBranch || !output.branch) return; + try { + // The linked worktree owns this record until removal. An archive keeps the branch. + await writeFile(await createdBranchFile(output.path), output.branch, { flag: "wx" }); + } catch (error) { + await cleanupPartiallyCreatedWorktree(repoRoot, output).catch(() => {}); + throw error; + } +} + +async function hasLocalBranch( + repoRoot: string, + branch: string, + signal: AbortSignal, +): Promise { + const ref = `refs/heads/${branch}`; + const { stdout } = await execCommand("git", ["for-each-ref", "--format=%(refname)", ref], { + cwd: repoRoot, + signal, + }); + return stdout.trim().split(/\r?\n/).includes(ref); +} + +export async function createWithWorktrunk( + request: PluginWorktreeCreateInput, + signal: AbortSignal, +): Promise<{ type: "created"; path: string } | undefined> { + const args = buildCreateArgs(request); + if (!args) return undefined; + // With a local branch collision, decline so Paseo's Git checkout allocates a unique branch + // name without disturbing the existing local branch. + const createsLocalBranch = + request.kind === "branch-off" || + request.kind === "checkout-change-request" || + request.kind === "checkout-github-pr"; + if (createsLocalBranch && (await hasLocalBranch(request.repoRoot, request.branch, signal))) { + return undefined; + } + let stdout: string; + try { + stdout = await runWt(args, { signal }); + } catch (error) { + await cleanupPartiallyCreatedWorktree(request.repoRoot, failedSwitchOutput(error)).catch( + () => {}, + ); + throw error; + } + const output = parseSwitchOutput(stdout); + // If Worktrunk switched to an already-existing checkout instead of creating one, + // decline so Paseo falls back to Git (which creates a unique branch). + if (output.action !== undefined && output.action !== "created") { + return undefined; + } + await recordCreatedBranch(request.repoRoot, output); + return { type: "created", path: output.path }; +} + +export async function removeWithWorktrunk( + request: PluginWorktreeRemoveRequest, + signal: AbortSignal, +): Promise<{ type: "removed" }> { + // Run from the main repository root when available and skip repository hooks for + // untrusted workspaces (or when repoRoot is unknown) so fork PRs cannot run hooks. + const runDir = request.repoRoot ?? request.path; + const skipHooks = request.untrusted || request.repoRoot === null; + const args = [ + "-C", + runDir, + "remove", + "--foreground", + "--no-delete-branch", + ...hookFlags(skipHooks), + ...(request.force ? ["--force"] : []), + request.path, + ]; + const createdBranch = + request.reason === "rollback" && request.repoRoot && request.branch + ? await createdBranchFile(request.path) + .then((file) => readFile(file, "utf8")) + .catch(() => null) + : null; + await runWt(args, { signal }); + if (createdBranch && createdBranch === request.branch && request.repoRoot) { + await execCommand("git", ["branch", "-D", "--", createdBranch], { cwd: request.repoRoot }); + } + return { type: "removed" }; +} + +export async function restoreWithWorktrunk( + request: PluginWorktreeRestoreRequest, + signal: AbortSignal, +): Promise<{ type: "restored"; path: string } | undefined> { + if (request.target.type === "commit") { + // Detached-commit restores fall back to Paseo's built-in Git restore. + return undefined; + } + const common = [ + "-C", + request.repoRoot, + "switch", + "--path", + request.path, + "--no-cd", + ...hookFlags(request.untrusted), + "--format=json", + ]; + const args = + request.target.type === "branch" + ? [...common, request.target.branch] + : [...common, "--create", request.target.branch, "--base", request.target.baseRef]; + let stdout: string; + try { + stdout = await runWt(args, { signal }); + } catch (error) { + await cleanupPartiallyCreatedWorktree(request.repoRoot, failedSwitchOutput(error)).catch( + () => {}, + ); + throw error; + } + const output = parseSwitchOutput(stdout); + await recordCreatedBranch(request.repoRoot, output); + return { type: "restored", path: output.path }; +} + +export async function setActivityMarker( + cwd: string, + marker: string | null, + signal: AbortSignal, +): Promise { + const args = + marker === null + ? ["config", "state", "marker", "clear"] + : ["config", "state", "marker", "set", marker]; + try { + await runWt(args, { cwd, signal }); + } catch { + // Activity markers are best-effort and must not disrupt agent sessions. + } +} diff --git a/public-docs/plugins/hooks.md b/public-docs/plugins/hooks.md index ec498f5918..12214c6d33 100644 --- a/public-docs/plugins/hooks.md +++ b/public-docs/plugins/hooks.md @@ -208,7 +208,7 @@ Every field except `repoRoot` and `sourceCheckout` is transformable. Return all Paseo resolves symlinked parents and validates the returned path. It must be absolute, must not exist, and must not be the filesystem root, your home directory, the repository root, inside a `.git` directory, or an ancestor of the repository. An existing destination fails creation; Paseo never adds a suffix to a plugin-chosen path. The plugin must leave directory creation to Paseo. -Ordering: `worktree.create.before` → `git worktree add` → `worktree.create.after` → workspace registration. Restoring a missing worktree recreates it at its recorded path without running either worktree creation hook. +Ordering: `worktree.create.before` → worktree manager `create` (or `git worktree add`) → `worktree.create.after` → workspace registration. To delegate `git worktree add`, removal, and restoration to an external tool such as Worktrunk, register a [worktree manager](/docs/plugins/reference#worktree-managers) with `server.registerWorktreeManager()` instead of creating directories inside `worktree.create.before`. Restoring a missing worktree recreates it at its recorded path without running creation hooks, delegating to the owning manager's optional `restore` handler when present. ## worktree.create.after @@ -700,6 +700,7 @@ replaces that scope's prior value. | [lifecycle-actions](https://github.com/getpaseo/paseo/tree/main/plugin-examples/lifecycle-actions) | Follow-ups, permissions, environment, provider switching, worktree selection | | [agent-configuration](https://github.com/getpaseo/paseo/tree/main/plugin-examples/agent-configuration) | MCP injection and Codex sandbox/approval options | | [agent-tools](https://github.com/getpaseo/paseo/tree/main/plugin-examples/agent-tools) | Label-targeted tools and file operations in the plugin process | +| [worktrunk](https://github.com/getpaseo/paseo/tree/main/plugin-examples/worktrunk) | Worktree manager (`create`, `remove`, `restore`) and agent activity markers | Read logger output with `paseo plugin logs lifecycle-logger` or the host's `daemon.log`. diff --git a/public-docs/plugins/hooks.zh-CN.md b/public-docs/plugins/hooks.zh-CN.md index 5bdb94a61b..7bffe7150a 100644 --- a/public-docs/plugins/hooks.zh-CN.md +++ b/public-docs/plugins/hooks.zh-CN.md @@ -205,7 +205,7 @@ server.addHook("worktree.create.before", async ({ request }) => ({ Paseo 解析父目录中的符号链接并验证返回的路径。路径必须为绝对路径且不存在,不能是文件系统根目录、用户主目录、仓库根目录、`.git` 目录内的路径或仓库的祖先目录。目标已存在时创建失败,Paseo 不会为插件选择的路径添加后缀。插件应让 Paseo 创建目录。 -顺序:`worktree.create.before` → `git worktree add` → `worktree.create.after` → 注册工作区。恢复缺失的 worktree 时使用记录的原路径,不运行这两个创建钩子。 +顺序:`worktree.create.before` → worktree 管理器 `create`(或 `git worktree add`)→ `worktree.create.after` → 注册工作区。若要将 `git worktree add`、移除和恢复委托给 Worktrunk 等外部工具,请使用 `server.registerWorktreeManager()` 注册 [worktree 管理器](/docs/plugins/reference#worktree-managers),而不是在 `worktree.create.before` 中创建目录。恢复缺失的 worktree 时使用记录的原路径,不运行创建钩子,并在对应管理器提供可选 `restore` 处理函数时委托给它。 ## worktree.create.after {#worktreecreateafter} @@ -677,12 +677,13 @@ Creation request ## 完整示例 {#complete-examples} -| 插件 | 包含 | -| ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------- | -| [lifecycle-logger](https://github.com/getpaseo/paseo/tree/main/plugin-examples/lifecycle-logger) | Agent、工作区和 worktree 钩子;隐去环境变量值的 JSON 日志 | -| [lifecycle-actions](https://github.com/getpaseo/paseo/tree/main/plugin-examples/lifecycle-actions) | 后续消息、权限、环境变量、切换 Provider、选择 worktree | -| [agent-configuration](https://github.com/getpaseo/paseo/tree/main/plugin-examples/agent-configuration) | MCP 注入以及 Codex 沙盒/批准选项 | -| [agent-tools](https://github.com/getpaseo/paseo/tree/main/plugin-examples/agent-tools) | 按标签选择 Agent,并在插件进程中执行文件操作的工具 | +| 插件 | 包含 | +| ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------- | +| [lifecycle-logger](https://github.com/getpaseo/paseo/tree/main/plugin-examples/lifecycle-logger) | Agent、工作区和 worktree 钩子;隐去环境变量值的 JSON 日志 | +| [lifecycle-actions](https://github.com/getpaseo/paseo/tree/main/plugin-examples/lifecycle-actions) | 后续消息、权限、环境变量、切换 Provider、选择 worktree | +| [agent-configuration](https://github.com/getpaseo/paseo/tree/main/plugin-examples/agent-configuration) | MCP 注入以及 Codex 沙盒/批准选项 | +| [agent-tools](https://github.com/getpaseo/paseo/tree/main/plugin-examples/agent-tools) | 按标签选择 Agent,并在插件进程中执行文件操作的工具 | +| [worktrunk](https://github.com/getpaseo/paseo/tree/main/plugin-examples/worktrunk) | worktree 管理器(`create`、`remove`、`restore`)与 Agent 活动标记 | 用 `paseo plugin logs lifecycle-logger` 或主机的 `daemon.log` 读取 logger 的输出。 diff --git a/public-docs/plugins/reference.md b/public-docs/plugins/reference.md index 2b482aaac4..965291c66b 100644 --- a/public-docs/plugins/reference.md +++ b/public-docs/plugins/reference.md @@ -696,6 +696,114 @@ for 0.10 clients and renders problems into its `error` string. The source icon is a file path with the same rules as a provider icon. +## Worktree managers {#worktree-managers} + +**Requires Paseo 0.17.** Register a worktree manager from `index.server.ts` with +`server.registerWorktreeManager()` when an external tool such as Worktrunk should own creating, +removing, and restoring Git worktrees instead of Paseo running `git worktree add` and +`git worktree remove` directly. + +```ts +import { execCommand, type PluginServerContext } from "@getpaseo/plugin/server"; + +export default function contribute(server: PluginServerContext) { + return server.registerWorktreeManager({ + async create(request, { signal }) { + if (request.kind !== "branch-off") return; + const { stdout } = await execCommand( + "wt", + [ + "-C", + request.repoRoot, + "switch", + "--create", + request.branch, + "--base", + request.startPoint ?? request.baseRef, + "--no-cd", + request.untrusted ? "--no-hooks" : "--yes", + "--format=json", + ], + { signal }, + ); + const { path } = JSON.parse(stdout) as { path: string }; + return { type: "created", path }; + }, + async remove({ repoRoot, path, force, untrusted }, { signal }) { + const skipHooks = untrusted || repoRoot === null; + await execCommand( + "wt", + [ + "-C", + repoRoot ?? path, + "remove", + "--foreground", + "--no-delete-branch", + skipHooks ? "--no-hooks" : "--yes", + ...(force ? ["--force"] : []), + path, + ], + { signal }, + ); + return { type: "removed" }; + }, + async restore({ repoRoot, path, target, untrusted }, { signal }) { + if (target.type !== "branch") return; + const { stdout } = await execCommand( + "wt", + [ + "-C", + repoRoot, + "switch", + target.branch, + "--path", + path, + "--no-cd", + untrusted ? "--no-hooks" : "--yes", + "--format=json", + ], + { signal }, + ); + const { path: restoredPath } = JSON.parse(stdout) as { path: string }; + return { type: "restored", path: restoredPath }; + }, + }); +} +``` + +- **Create** runs after all `worktree.create.before` hooks and before `worktree.create.after`. + All managers share 120 seconds for each create request. Return `{ type: "created", path }` to + claim creation. If you return `undefined`, Paseo tries the next manager or uses built-in Git. + For branch-off, Paseo resolves `baseRef` and refreshes a remote-tracking starting ref before + calling the manager. If the fetch fails, Paseo uses the cached ref. When `request.untrusted` is `true` (for + example, a fork change request), skip repository-defined hooks. Paseo verifies that `path` is a + safe, newly created Git worktree of the same repository on a named branch, then records the + checked-out `HEAD` branch (managers may normalize or uniquely name the branch, and should create a + new branch for `branch-off`), writes comparison-base metadata, and seeds `paseo.json`. Paseo uses the + returned path to roll back a failed adoption or later creation step. If the callback throws or + its signal aborts before it returns, the manager is responsible for cleaning up any worktree it + created. First-agent branch auto-rename is skipped for manager-created worktrees. +- **Remove** is optional and runs on workspace archive and creation rollback, after Paseo runs + `paseo.json` teardown and saves `refs/paseo/kept-commits/` for restore. Return + `{ type: "removed" }` after removing the directory, or `undefined` to fall back to Git. When + `untrusted` is `true` (for example, a fork change request) or `repoRoot` is `null`, skip + repository-defined hooks and run against `repoRoot` when available. Paseo routes removal to the + plugin that created the worktree and falls back to Git when that plugin is disabled or uninstalled. + Paseo keeps the directory if it contains another linked Git worktree. Standalone clones and + submodules follow normal removal. During archive, an active workspace nested inside the directory + also keeps it on disk. If the callback throws or times out after 120 seconds, Paseo skips Git + fallback. During archive, Paseo logs the callback failure and still archives the workspace. + Any files the callback left stay on disk. +- **Restore** is optional and runs when unarchiving a workspace whose worktree directory was deleted. + It receives the recorded `path` that the recreated worktree must occupy, `target` (`branch`, + `commit`, or `from-base`), and `untrusted`. Return `{ type: "restored", path }` or `undefined` to + fall back to Git. Paseo verifies the checkout matches the requested branch, detached commit, or + new branch at the requested base commit. The same cleanup rules apply as for create. When + `restore` falls back to Git, Paseo clears the workspace's manager ownership + so subsequent archives also use Git. + +See the complete [worktrunk example](https://github.com/getpaseo/paseo/tree/main/plugin-examples/worktrunk). + ## Entry point and cleanup Each present entry default-exports one contribution function and returns cleanup. Client entries diff --git a/public-docs/plugins/reference.zh-CN.md b/public-docs/plugins/reference.zh-CN.md index e6c2b7fd77..0ec7b1aa8c 100644 --- a/public-docs/plugins/reference.zh-CN.md +++ b/public-docs/plugins/reference.zh-CN.md @@ -542,6 +542,84 @@ export default function contribute(server: PluginServerContext) { 来源图标是一个文件路径,规则与 Provider 图标相同。 +## worktree 管理器 {#worktree-managers} + +**需要 Paseo 0.17**。在服务端入口 `index.server.ts` 中调用 `server.registerWorktreeManager()`,可将 Git worktree 的创建、移除和恢复委托给 Worktrunk 等外部工具,而无需由 Paseo 直接运行 `git worktree add` 和 `git worktree remove`。 + +```ts +import { execCommand, type PluginServerContext } from "@getpaseo/plugin/server"; + +export default function contribute(server: PluginServerContext) { + return server.registerWorktreeManager({ + async create(request, { signal }) { + if (request.kind !== "branch-off") return; + const { stdout } = await execCommand( + "wt", + [ + "-C", + request.repoRoot, + "switch", + "--create", + request.branch, + "--base", + request.startPoint ?? request.baseRef, + "--no-cd", + request.untrusted ? "--no-hooks" : "--yes", + "--format=json", + ], + { signal }, + ); + const { path } = JSON.parse(stdout) as { path: string }; + return { type: "created", path }; + }, + async remove({ repoRoot, path, force, untrusted }, { signal }) { + const skipHooks = untrusted || repoRoot === null; + await execCommand( + "wt", + [ + "-C", + repoRoot ?? path, + "remove", + "--foreground", + "--no-delete-branch", + skipHooks ? "--no-hooks" : "--yes", + ...(force ? ["--force"] : []), + path, + ], + { signal }, + ); + return { type: "removed" }; + }, + async restore({ repoRoot, path, target, untrusted }, { signal }) { + if (target.type !== "branch") return; + const { stdout } = await execCommand( + "wt", + [ + "-C", + repoRoot, + "switch", + target.branch, + "--path", + path, + "--no-cd", + untrusted ? "--no-hooks" : "--yes", + "--format=json", + ], + { signal }, + ); + const { path: restoredPath } = JSON.parse(stdout) as { path: string }; + return { type: "restored", path: restoredPath }; + }, + }); +} +``` + +- **Create**:在所有 `worktree.create.before` 钩子之后、`worktree.create.after` 之前运行,超时为 120 秒。返回 `{ type: "created", path }` 表示接管创建,返回 `undefined` 表示放弃并交由下一个管理器或 Paseo 内置 Git 检出处理。创建新分支时,Paseo 会在调用管理器前解析 `baseRef`,并刷新用作起点的远程跟踪引用。如果获取失败,则使用本地缓存的引用。当 `request.untrusted` 为 `true`(例如来自 fork 变更请求)时,请跳过仓库内定义的钩子。Paseo 会验证 `path` 是同一仓库下新建且安全的命名分支 Git worktree,并记录实际检出的 `HEAD` 分支(管理器可自行规范或生成唯一分支名,但在 `branch-off` 时应创建新分支),随后写入基准元数据并生成 `paseo.json`。如果采纳或后续创建步骤失败,Paseo 会根据返回的路径回滚。回调在返回前抛出错误或收到中止信号时,由管理器清理自己创建的 worktree。由管理器创建的 worktree 会跳过首个 Agent 的分支自动重命名。 +- **Remove**:可选。在工作区归档和创建回滚时运行,位于 Paseo 执行 `paseo.json` 清理并保存 `refs/paseo/kept-commits/` 之后。删除目录后返回 `{ type: "removed" }`,或返回 `undefined` 回退到 Git。当 `untrusted` 为 `true`(例如来自 fork 变更请求)或 `repoRoot` 为 `null` 时,请跳过仓库内定义的钩子,并在可用时从 `repoRoot` 运行。Paseo 会将移除路由到创建该 worktree 的插件;若该插件已停用或移除,则回退到内置 Git。 +- **Restore**:可选。在取消归档且 worktree 目录已被删除时运行,接收必须恢复到的原路径 `path`、目标 `target`(`branch`、`commit` 或 `from-base`)以及 `untrusted`。返回 `{ type: "restored", path }`,或返回 `undefined` 回退到 Git。Paseo 会验证检出结果是否为指定的分支、分离 HEAD 的提交,或位于指定基准提交的新分支。清理规则与 Create 相同。当 `restore` 回退到 Git 时,Paseo 会清除该工作区的管理器归属,后续归档也会使用 Git。 + +完整插件见 [worktrunk 示例](https://github.com/getpaseo/paseo/tree/main/plugin-examples/worktrunk)。 + ## 入口与清理 {#entry-point-and-cleanup} 每个存在的入口都默认导出一个贡献函数,并返回清理函数。客户端入口接收 `PluginClientContext`;服务端入口接收 `PluginServerContext`。客户端注册方法返回幂等的移除函数,但标题栏按钮和 Composer 标签除外,它们返回 `{ update, remove }` 句柄。入口的清理函数会在 Paseo 移除剩余的注册之前运行。