@loicngr/kobo 1.11.32 → 1.11.34

package/AGENTS.md

@@ -263,6 +263,8 @@ Sequence: `captureRestoreData` (best-effort forge lookup for PR number / URL / m
 
 **Auto-restore on manual recreation.** When the user manually recreates the worktree folder (`gh pr checkout <pr-number>` or `git worktree add <path> <branch>`), the pr-watcher detects the folder reappearing on its next 30 s tick via `autoRestoreManuallyRecreatedWorktrees()`: it iterates archived workspaces with `worktreePurgedAt`, checks `fs.existsSync(worktreePath)`, and on a hit calls `restoreWorktreeFromDisk(id)` which clears `worktree_purged_at` + `worktree_purge_restore_data` + `archived_at` in one transaction, then emits `workspace:worktree-restored`. The client websocket store reuses the same handler as `workspace:archived`/`unarchived` to refresh both the active and archived workspace lists. No UI action needed.
 
+**Restore**: `POST /api/workspaces/:id/restore-worktree` calls `worktree-restore-service.ts` to recreate the exact checkout and only then clear purge/archive metadata via `restoreWorktreeFromDisk`. Source order: surviving local branch → optional `headCommitSha` in the existing restore JSON → exact branch fetched from `origin`. No SQL migration is needed for the optional JSON key; older records remain supported. No reset, overwrite, agent/dev-server start or setup script. `workspace-lifecycle-guard.ts` excludes overlapping restore/purge/delete operations, while the existing common-Git-directory lock serializes Git mutations. The watcher shares `isMatchingWorkspaceWorktree` validation and invalidates in-flight PR checks on restoration; delayed auto-purges carry their expected archive timestamp to avoid purging a workspace restored in the meantime. The context menu and purged banner expose the action; HTTP and the existing `workspace:worktree-restored` event reconcile client lists. Discarded uncommitted/ignored files and dependencies are not recoverable.
+
 ### Workspace attention indicators
 
 `src/client/src/utils/workspace-attention.ts` derives a small set of badges (CI failure, changes-requested) from the PR snapshot + git stats stored on each workspace. `WorkspaceAttentionLabels.vue` renders them inline on the workspace cards in the left drawer. The derivation is a pure function, easy to unit-test and free of IO. Drawer cards therefore stay reactive to whatever the pr-watcher / bulk-info refresh writes back into the store.

package/CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to Kōbō are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/). Each release is an `## <version>`
 section — the in-app "What's new" dialog reads this file.
 
+## 1.11.34
+
+- feat(workspaces): restore purged workspaces and improve startup display
+
+## 1.11.33
+
+- fix(onboarding): quitting a tour marks it seen for good
+
 ## 1.11.32
 
 - chore(deps): npm update in the server and client trees

package/dist/server/index.js

@@ -46,8 +46,9 @@ import * as wakeupService from './services/wakeup-service.js';
 import { emit, emitEphemeral, handleConnection, setMessageHandler } from './services/websocket-service.js';
 import { getActiveSession, getWorkspace, updateWorkspaceStatus } from './services/workspace-service.js';
 import { pruneWsEvents, resolveRetentionConfig } from './services/ws-events-retention-service.js';
-import { getClientSpaPath, getDbPath, getKoboHome, getPackageVersion, resolveSpaFile } from './utils/paths.js';
-console.log(`[kobo] Kōbō home: ${getKoboHome()}`);
+import { getChangelogPath, getClientSpaPath, getDbPath, getKoboHome, getPackageVersion, resolveSpaFile, } from './utils/paths.js';
+import { formatStartupBanner, readStartupNotes, startStartupSpinner, startupDebug } from './utils/startup-display.js';
+startupDebug(`[kobo] Kōbō home: ${getKoboHome()}`);
 // Initialize DB + run migrations
 const db = getDb();
 // Pre-migration backup: snapshot the DB before applying any pending schema
@@ -57,9 +58,9 @@ try {
     const pending = getPendingMigrations(db);
     if (pending.length > 0) {
         const result = await createPreMigrationBackup(db, getDbPath(), `v${pending[pending.length - 1]}`);
-        console.log(`[kobo] Pre-migration backup before applying ${pending.length} migration(s): ${result.created}`);
+        startupDebug(`[kobo] Pre-migration backup before applying ${pending.length} migration(s): ${result.created}`);
         if (result.deleted.length > 0) {
-            console.log(`[kobo] Rotated ${result.deleted.length} old pre-migration backup(s)`);
+            startupDebug(`[kobo] Rotated ${result.deleted.length} old pre-migration backup(s)`);
         }
     }
 }
@@ -105,9 +106,9 @@ retentionTimer.unref?.();
 void createDailyDbBackupIfNeeded(db, getDbPath())
     .then((r) => {
     if (r.created) {
-        console.log(`[kobo] Daily DB backup: ${r.created}`);
+        startupDebug(`[kobo] Daily DB backup: ${r.created}`);
         if (r.deleted.length > 0) {
-            console.log(`[kobo] Rotated ${r.deleted.length} old DB backup(s)`);
+            startupDebug(`[kobo] Rotated ${r.deleted.length} old DB backup(s)`);
         }
     }
 })
@@ -223,21 +224,25 @@ if (Object.keys(networkAccessEnvOverrides).length > 0) {
     updateNetworkAccessSettings(patch);
 }
 const bindHost = resolveBindHost(getGlobalSettings().networkAccessEnabled);
+const stopStartupSpinner = startStartupSpinner();
 const server = serve({
     fetch: app.fetch,
     port: PORT,
     hostname: bindHost,
 }, (info) => {
     setBackendPort(info.port);
-    if (getGlobalSettings().networkAccessEnabled) {
-        console.log(`Server running — network access ON (port ${info.port})`);
-        for (const url of getLanUrls(info.port))
-            console.log(`  LAN: ${url}`);
-        console.log(`  Token: ${getGlobalSettings().networkAccessToken}`);
-    }
-    else {
-        console.log(`Server running at http://localhost:${info.port} (localhost only)`);
-    }
+    stopStartupSpinner();
+    const settings = getGlobalSettings();
+    console.log(formatStartupBanner({
+        version: getPackageVersion(),
+        port: info.port,
+        devClientOrigin: resolveDevClientOrigin(),
+        networkEnabled: settings.networkAccessEnabled,
+        lanUrls: settings.networkAccessEnabled ? getLanUrls(info.port) : [],
+        token: settings.networkAccessToken,
+        changelog: readStartupNotes(getChangelogPath()),
+        color: Boolean(process.stdout.isTTY && process.env.TERM !== 'dumb' && !('NO_COLOR' in process.env)),
+    }));
     // Content migration runs AFTER the HTTP listener is up so the frontend
     // can observe progress via WS broadcasts + GET /api/migration/status.
     // Not awaited — the callback returns quickly, the migration runs in the
@@ -246,6 +251,16 @@ const server = serve({
         console.error('[boot] content migration failed:', err);
     });
 });
+server.on('error', (err) => {
+    stopStartupSpinner();
+    if (err.code === 'EADDRINUSE') {
+        console.error(`[kobo] Port ${PORT} is already in use. Stop the other server or choose another SERVER_PORT.`);
+    }
+    else {
+        console.error('[kobo] Unable to start the server:', err);
+    }
+    void gracefulShutdown('server error', 1);
+});
 // Create WebSocketServer attached to the HTTP server
 const wss = new WebSocketServer({ noServer: true });
 const terminalWss = new WebSocketServer({ noServer: true });

package/dist/server/routes/changelog.js

@@ -1,31 +1,10 @@
 import fs from 'node:fs';
 import { Hono } from 'hono';
+import { parseChangelog } from '../utils/changelog.js';
 import { getChangelogPath, getPackageVersion } from '../utils/paths.js';
+export { parseChangelog } from '../utils/changelog.js';
 /** Hono sub-router for the in-app "What's new" dialog. */
 const app = new Hono();
-/**
- * Parse a Keep-a-Changelog markdown file into ordered version sections. Each
- * `## <version>` heading starts a new entry; everything until the next heading
- * is its notes. A leading `v` on the version is stripped.
- */
-export function parseChangelog(markdown) {
-    const entries = [];
-    let current = null;
-    for (const line of markdown.split('\n')) {
-        const heading = line.match(/^##\s+v?(\d+\.\d+\.\d+[\w./-]*)\s*$/);
-        if (heading) {
-            if (current)
-                entries.push({ version: current.version, notes: current.lines.join('\n').trim() });
-            current = { version: heading[1], lines: [] };
-        }
-        else if (current) {
-            current.lines.push(line);
-        }
-    }
-    if (current)
-        entries.push({ version: current.version, notes: current.lines.join('\n').trim() });
-    return entries;
-}
 /**
  * Latest version published to npm, looked up at most once a day.
  *

package/dist/server/routes/workspaces.js

@@ -40,12 +40,14 @@ import * as permissionPolicyService from '../services/workspace-permission-polic
 import * as workspaceService from '../services/workspace-service.js';
 import { presetFromWorkspace } from '../services/workspace-template-service.js';
 import * as purgeWorktreeService from '../services/worktree-purge-service.js';
+import { restorePurgedWorktree, WorktreeRestoreError } from '../services/worktree-restore-service.js';
 import * as worktreeService from '../services/worktree-service.js';
 import { resolveUniqueBranchAndPath } from '../utils/branch-resolver.js';
 import * as gitOps from '../utils/git-ops.js';
 import { logError } from '../utils/logger.js';
 import { slugifyProjectName } from '../utils/project-slug.js';
 import * as safePath from '../utils/safe-path.js';
+import { WorkspaceLifecycleBusyError, withWorkspaceLifecycleGuard } from '../utils/workspace-lifecycle-guard.js';
 import { resolveExtractedName } from '../utils/workspace-name.js';
 import { resolveSiblingWorkspaceWorktreePath } from '../utils/worktree-paths.js';
 /** Hono sub-router for workspace CRUD, tasks, agent lifecycle, git operations, and PR creation. */
@@ -2904,10 +2906,31 @@ app.post('/:id/purge-worktree', migrationGuard, async (c) => {
         return c.json({ workspace, warnings: result.warnings, outcome: result.outcome });
     }
     catch (err) {
+        if (err instanceof WorkspaceLifecycleBusyError)
+            return c.json({ code: err.code, error: err.message }, 409);
         const message = err instanceof Error ? err.message : String(err);
         return c.json({ error: message }, 500);
     }
 });
+// Recreate the checkout before unarchiving; never starts agents or setup scripts.
+app.post('/:id/restore-worktree', migrationGuard, async (c) => {
+    try {
+        return c.json(await restorePurgedWorktree(c.req.param('id')));
+    }
+    catch (err) {
+        if (err instanceof WorktreeRestoreError) {
+            const status = err.code === 'not-found'
+                ? 404
+                : ['not-purged', 'workspace-busy', 'path-conflict', 'branch-in-use'].includes(err.code)
+                    ? 409
+                    : ['worktree-not-owned', 'project-unavailable', 'recovery-source-unavailable'].includes(err.code)
+                        ? 422
+                        : 500;
+            return c.json({ code: err.code, error: err.message }, status);
+        }
+        return c.json({ code: 'git-failed', error: 'Unable to restore the worktree.' }, 500);
+    }
+});
 // POST /api/workspaces/:id/unarchive — restore an archived workspace
 app.post('/:id/unarchive', migrationGuard, (c) => {
     try {
@@ -2940,6 +2963,18 @@ app.post('/:id/unarchive', migrationGuard, (c) => {
 // rather than thrown, so a bulk delete never aborts mid-batch. Returns the
 // list of user-facing warning messages (empty when everything was clean).
 async function deleteWorkspaceWithSideEffects(workspace, opts) {
+    return withWorkspaceLifecycleGuard(workspace.id, async () => {
+        const current = workspaceService.getWorkspace(workspace.id);
+        if (!current)
+            throw new Error(`Workspace '${workspace.id}' not found`);
+        // A bulk deletion may have captured the list before restoration completed.
+        if (workspace.archivedAt && !current.archivedAt) {
+            throw new Error('Workspace was unarchived while deletion was pending. Retry from its current state.');
+        }
+        return deleteWorkspaceWithSideEffectsUnlocked(current, opts);
+    });
+}
+async function deleteWorkspaceWithSideEffectsUnlocked(workspace, opts) {
     // Stop the agent and WAIT for it to die. `git worktree remove --force` runs
     // a few lines below: firing and forgetting here pulled the directory from
     // under an agent still writing to it, destroying uncommitted work.
@@ -3079,6 +3114,8 @@ app.delete('/:id', migrationGuard, async (c) => {
         return c.json({ ok: true, warnings }, 200);
     }
     catch (err) {
+        if (err instanceof WorkspaceLifecycleBusyError)
+            return c.json({ code: err.code, error: err.message }, 409);
         const message = err instanceof Error ? err.message : String(err);
         return c.json({ error: message }, 500);
     }

package/dist/server/services/pr-watcher-service.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
-import { fetchSourceBranchAsync, isGitWorktree } from '../utils/git-ops.js';
+import { fetchSourceBranchAsync } from '../utils/git-ops.js';
 import { withGitRepoLock } from '../utils/git-repo-lock.js';
+import { isWorkspaceLifecycleBusy } from '../utils/workspace-lifecycle-guard.js';
 import { hasController } from './agent/orchestrator.js';
 import { stopDevServer } from './dev-server-service.js';
 import { getForgeProvider } from './forge/registry.js';
@@ -12,6 +13,7 @@ import { destroyTerminal } from './terminal-service.js';
 import { emitEphemeral } from './websocket-service.js';
 import { archiveWorkspace, getWorkspace, listArchivedWorkspaces, listWorkspaces, markWorkspaceUnread, restoreWorktreeFromDisk, updateWorkspaceSourceBranch, } from './workspace-service.js';
 import { purgeWorktree } from './worktree-purge-service.js';
+import { isMatchingWorkspaceWorktree } from './worktree-service.js';
 // ── PR Watcher ────────────────────────────────────────────────────────────────
 // Polls GitHub every POLL_INTERVAL_MS to detect merged/closed PRs and
 // automatically archive the corresponding workspace.
@@ -41,6 +43,14 @@ async function runBounded(items, concurrency, worker) {
 const lastKnownPr = new Map();
 /** Latest git-stats snapshot per workspace, refreshed each watcher tick. */
 const lastKnownGitStats = new Map();
+const activeChecks = new Map();
+/** Also cancels stale results from checks that started before restoration. */
+export function invalidateWorkspacePrCaches(workspaceId) {
+    lastKnownPr.delete(workspaceId);
+    lastKnownGitStats.delete(workspaceId);
+    for (const check of activeChecks.get(workspaceId) ?? [])
+        check.invalidated = true;
+}
 /**
  * Read-only snapshot map, keyed by workspace id. Used by the drawer indicator
  * AND the Git panel. Workspaces without a known PR are absent.
@@ -91,19 +101,15 @@ function markUnread(workspaceId) {
 }
 function autoRestoreManuallyRecreatedWorktrees() {
     for (const ws of listArchivedWorkspaces()) {
-        if (!ws.worktreePurgedAt)
+        if (!ws.worktreePurgedAt || !ws.worktreeOwned || isWorkspaceLifecycleBusy(ws.id))
             continue;
         if (!fs.existsSync(ws.worktreePath))
             continue;
-        // Only a genuinely recreated worktree (gh pr checkout / git worktree add)
-        // should trigger restore. A purge that failed to fully remove the folder
-        // (e.g. root-owned Docker files) leaves a residual non-git directory that
-        // satisfies existsSync but is NOT a valid worktree — restoring it would
-        // wrongly un-archive the workspace and flood git fetches with "(null)".
-        if (!isGitWorktree(ws.worktreePath))
+        if (!isMatchingWorkspaceWorktree(ws))
             continue;
         try {
             const restored = restoreWorktreeFromDisk(ws.id);
+            invalidateWorkspacePrCaches(ws.id);
             emitEphemeral(ws.id, 'workspace:worktree-restored', { workspace: restored });
             console.log(`[pr-watcher] auto-restored worktree for workspace '${ws.name}' (manual restore detected)`);
         }
@@ -129,8 +135,20 @@ export async function checkPrStatuses() {
     await runBounded(workspaces, WORKSPACE_CHECK_CONCURRENCY, async (ws) => {
         // Without this guard, every git/forge spawn below fails with ENOENT and
         // floods the logs when a worktree was deleted externally.
-        if (!fs.existsSync(ws.worktreePath))
+        if (isWorkspaceLifecycleBusy(ws.id) || !fs.existsSync(ws.worktreePath))
             return;
+        const check = { invalidated: false };
+        const checks = activeChecks.get(ws.id) ?? new Set();
+        checks.add(check);
+        activeChecks.set(ws.id, checks);
+        const stale = () => {
+            const current = getWorkspace(ws.id);
+            return (check.invalidated ||
+                isWorkspaceLifecycleBusy(ws.id) ||
+                !current ||
+                current.archivedAt !== ws.archivedAt ||
+                current.worktreePurgedAt !== ws.worktreePurgedAt);
+        };
         try {
             // Opt-out: skip the forge call entirely for a workspace with PR-watch
             // disabled — no PR-status fetch, no auto-archive/purge, no PR-derived
@@ -140,6 +158,8 @@ export async function checkPrStatuses() {
             const pr = ws.prWatchDisabledAt
                 ? null
                 : await getForgeProvider(resolveForge(ws.projectPath)).getPrStatus(ws.worktreePath, ws.workingBranch);
+            if (stale())
+                return;
             // Detect a PR base change BEFORE computing git stats so the new base
             // is used in commitCount / behindCount / diffStats. Otherwise the
             // user keeps seeing stale ahead/behind counts vs the OLD base until
@@ -174,12 +194,17 @@ export async function checkPrStatuses() {
                 // concurrently across four worktrees made them fight over the same file
                 // lock, with the error swallowed.
                 await withGitRepoLock(ws.worktreePath, () => fetchSourceBranchAsync(ws.worktreePath, ws.sourceBranch));
-                lastKnownGitStats.set(ws.id, await computeGitStats(ws, pr));
+                if (stale())
+                    return;
+                const stats = await computeGitStats(ws, pr);
+                if (stale())
+                    return;
+                lastKnownGitStats.set(ws.id, stats);
             }
             catch (err) {
                 console.error(`[pr-watcher] computeGitStats failed for '${ws.name}':`, err instanceof Error ? err.message : err);
             }
-            if (!pr)
+            if (stale() || !pr)
                 return;
             const prev = lastKnownPr.get(ws.id);
             // We delay updating `lastKnownPr` until after the actions succeed.
@@ -224,13 +249,18 @@ export async function checkPrStatuses() {
                 catch (err) {
                     console.error(`[pr-watcher] stopDevServer failed for '${ws.name}':`, err instanceof Error ? err.message : err);
                 }
+                if (stale())
+                    return;
+                const current = getWorkspace(ws.id);
+                if (!current || ['extracting', 'brainstorming', 'executing'].includes(current.status) || hasController(ws.id))
+                    return;
                 try {
                     destroyTerminal(ws.id);
                 }
                 catch {
                     // Terminal may not exist — ignore
                 }
-                archiveWorkspace(ws.id);
+                const archived = archiveWorkspace(ws.id);
                 lastKnownPr.delete(ws.id);
                 emitEphemeral(ws.id, 'workspace:archived', {
                     reason: `PR ${pr.state.toLowerCase()}`,
@@ -245,7 +275,10 @@ export async function checkPrStatuses() {
                             // `onPrMerged` never rejects and is capped by the script-runner's
                             // own timeout, so this cannot hang the watcher indefinitely.
                             await prMergedHook;
-                            void purgeWorktree(ws.id)
+                            const current = getWorkspace(ws.id);
+                            if (check.invalidated || !archived.archivedAt || current?.archivedAt !== archived.archivedAt)
+                                return;
+                            void purgeWorktree(ws.id, archived.archivedAt)
                                 .then((result) => {
                                 // Auto-purge runs with nobody watching: without this trace an
                                 // outcome of 'removal-failed' left no record anywhere.
@@ -317,6 +350,11 @@ export async function checkPrStatuses() {
         catch (err) {
             console.error(`[pr-watcher] Failed to check PR for workspace '${ws.name}':`, err instanceof Error ? err.message : err);
         }
+        finally {
+            checks.delete(check);
+            if (!checks.size)
+                activeChecks.delete(ws.id);
+        }
     });
 }
 /**
@@ -332,31 +370,51 @@ export async function refreshPrSnapshot(workspaceId) {
     const ws = getWorkspace(workspaceId);
     if (!ws)
         throw new Error(`Workspace '${workspaceId}' not found`);
-    const snap = await getForgeProvider(resolveForge(ws.projectPath)).getPrStatus(ws.worktreePath, ws.workingBranch);
-    if (snap === null) {
-        lastKnownPr.delete(workspaceId);
+    if (isWorkspaceLifecycleBusy(workspaceId))
         return null;
-    }
-    // Mirror the watcher's base-change detection so a manual refresh fixes a
-    // stale `sourceBranch` (typical scenario: user ran `gh pr edit --base …`
-    // and clicks the GitPanel refresh button instead of waiting for the next
-    // 30s tick). Best-effort: a DB write failure here leaves the snapshot
-    // cached but the metadata stale — the watcher will retry on its own.
-    if (snap.state === 'OPEN' && snap.base && snap.base !== ws.sourceBranch) {
-        try {
-            updateWorkspaceSourceBranch(workspaceId, snap.base);
-            emitEphemeral(workspaceId, 'pr:base-changed', {
-                oldBase: ws.sourceBranch,
-                newBase: snap.base,
-                prUrl: snap.url,
-            });
+    const check = { invalidated: false };
+    const checks = activeChecks.get(workspaceId) ?? new Set();
+    checks.add(check);
+    activeChecks.set(workspaceId, checks);
+    try {
+        const snap = await getForgeProvider(resolveForge(ws.projectPath)).getPrStatus(ws.worktreePath, ws.workingBranch);
+        const current = getWorkspace(workspaceId);
+        if (check.invalidated ||
+            isWorkspaceLifecycleBusy(workspaceId) ||
+            !current ||
+            current.archivedAt !== ws.archivedAt ||
+            current.worktreePurgedAt !== ws.worktreePurgedAt)
+            return null;
+        if (snap === null) {
+            lastKnownPr.delete(workspaceId);
+            return null;
         }
-        catch (err) {
-            console.error(`[pr-watcher] updateWorkspaceSourceBranch (refresh) failed for '${ws.name}':`, err instanceof Error ? err.message : err);
+        // Mirror the watcher's base-change detection so a manual refresh fixes a
+        // stale `sourceBranch` (typical scenario: user ran `gh pr edit --base …`
+        // and clicks the GitPanel refresh button instead of waiting for the next
+        // 30s tick). Best-effort: a DB write failure here leaves the snapshot
+        // cached but the metadata stale — the watcher will retry on its own.
+        if (snap.state === 'OPEN' && snap.base && snap.base !== ws.sourceBranch) {
+            try {
+                updateWorkspaceSourceBranch(workspaceId, snap.base);
+                emitEphemeral(workspaceId, 'pr:base-changed', {
+                    oldBase: ws.sourceBranch,
+                    newBase: snap.base,
+                    prUrl: snap.url,
+                });
+            }
+            catch (err) {
+                console.error(`[pr-watcher] updateWorkspaceSourceBranch (refresh) failed for '${ws.name}':`, err instanceof Error ? err.message : err);
+            }
         }
+        lastKnownPr.set(workspaceId, snap);
+        return snap;
+    }
+    finally {
+        checks.delete(check);
+        if (!checks.size)
+            activeChecks.delete(workspaceId);
     }
-    lastKnownPr.set(workspaceId, snap);
-    return snap;
 }
 /**
  * Runs a single check while honouring the `checking` re-entrancy guard. Used

package/dist/server/services/worktree-purge-service.js

@@ -1,5 +1,8 @@
+import { execFile } from 'node:child_process';
 import fs from 'node:fs';
+import { promisify } from 'node:util';
 import { logError, logWarn } from '../utils/logger.js';
+import { withWorkspaceLifecycleGuard } from '../utils/workspace-lifecycle-guard.js';
 import * as agentManager from './agent/orchestrator.js';
 import * as devServerService from './dev-server-service.js';
 import { getForgeProvider } from './forge/registry.js';
@@ -8,10 +11,17 @@ import { destroyTerminal } from './terminal-service.js';
 import { emitEphemeral } from './websocket-service.js';
 import { archiveWorkspace, getWorkspace, markWorktreePurged, } from './workspace-service.js';
 import { isPermissionError, removeWorktree } from './worktree-service.js';
-export async function purgeWorktree(workspaceId) {
+const execFileAsync = promisify(execFile);
+export async function purgeWorktree(workspaceId, expectedArchivedAt) {
+    return withWorkspaceLifecycleGuard(workspaceId, () => purgeWorktreeGuarded(workspaceId, expectedArchivedAt));
+}
+async function purgeWorktreeGuarded(workspaceId, expectedArchivedAt) {
     const workspace = getWorkspace(workspaceId);
     if (!workspace)
         return { outcome: 'not-found', warnings: [] };
+    if (expectedArchivedAt !== undefined && workspace.archivedAt !== expectedArchivedAt) {
+        return { outcome: 'cancelled', warnings: [] };
+    }
     if (workspace.worktreePurgedAt)
         return { outcome: 'already-purged', warnings: [] };
     if (!workspace.worktreeOwned)
@@ -98,6 +108,19 @@ function buildRemovalFailureMessage(worktreePath, projectPath, errMsg) {
 }
 async function captureRestoreData(workspace) {
     const forge = resolveForge(workspace.projectPath);
+    let headCommitSha = null;
+    try {
+        const { stdout } = await execFileAsync('git', ['rev-parse', '--verify', 'HEAD'], {
+            cwd: workspace.worktreePath,
+            encoding: 'utf8',
+            timeout: 30_000,
+            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+        });
+        headCommitSha = stdout.trim() || null;
+    }
+    catch {
+        // A missing or broken checkout must not prevent a best-effort purge.
+    }
     let prNumber = null;
     let prUrl = null;
     // Direct provider call (not the pr-watcher cache) avoids an import cycle
@@ -123,6 +146,7 @@ async function captureRestoreData(workspace) {
         prUrl,
         forge: forge,
         mergeCommitSha: null,
+        headCommitSha,
         originalWorktreePath: workspace.worktreePath,
         originalSourceBranch: workspace.sourceBranch,
         originalWorkingBranch: workspace.workingBranch,

package/dist/server/services/worktree-restore-service.js

@@ -0,0 +1,79 @@
+import { withGitRepoLock } from '../utils/git-repo-lock.js';
+import { withWorkspaceLifecycleGuard } from '../utils/workspace-lifecycle-guard.js';
+import { invalidateWorkspacePrCaches } from './pr-watcher-service.js';
+import { emitEphemeral } from './websocket-service.js';
+import { getWorkspace, restoreWorktreeFromDisk } from './workspace-service.js';
+import { isMatchingWorkspaceWorktree, restoreWorktreeCheckoutUnlocked, } from './worktree-service.js';
+export class WorktreeRestoreError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+function savedHead(json) {
+    try {
+        const data = JSON.parse(json ?? 'null');
+        if (data && typeof data === 'object' && 'headCommitSha' in data && typeof data.headCommitSha === 'string') {
+            return /^[a-f0-9]{40,64}$/i.test(data.headCommitSha) ? data.headCommitSha : null;
+        }
+    }
+    catch {
+        // Older/hand-edited metadata does not prevent restoring a surviving branch.
+    }
+    return null;
+}
+export async function restorePurgedWorktree(id) {
+    try {
+        return await withWorkspaceLifecycleGuard(id, async () => {
+            const initial = getWorkspace(id);
+            if (!initial)
+                throw new WorktreeRestoreError('not-found', 'Workspace not found.');
+            return withGitRepoLock(initial.projectPath, async () => {
+                const workspace = getWorkspace(id);
+                if (!workspace)
+                    throw new WorktreeRestoreError('not-found', 'Workspace not found.');
+                if (!workspace.worktreeOwned) {
+                    throw new WorktreeRestoreError('worktree-not-owned', 'This workspace uses an externally managed worktree.');
+                }
+                const input = {
+                    projectPath: workspace.projectPath,
+                    worktreePath: workspace.worktreePath,
+                    workingBranch: workspace.workingBranch,
+                    headCommitSha: savedHead(workspace.worktreePurgeRestoreData),
+                };
+                if (!workspace.worktreePurgedAt) {
+                    if (!isMatchingWorkspaceWorktree(input)) {
+                        throw new WorktreeRestoreError('not-purged', 'Workspace is not marked as purged and its checkout is missing or different.');
+                    }
+                    return { workspace, outcome: 'already-restored', source: 'existing-worktree' };
+                }
+                const checkout = await restoreWorktreeCheckoutUnlocked(input);
+                if (!isMatchingWorkspaceWorktree(input)) {
+                    throw new WorktreeRestoreError('path-conflict', 'The recreated checkout does not match this workspace.');
+                }
+                // Preserve a valid checkout on DB failure. A retry or manual detection can
+                // safely complete the metadata update without deleting any Git history.
+                const restored = restoreWorktreeFromDisk(id);
+                invalidateWorkspacePrCaches(id);
+                emitEphemeral(id, 'workspace:worktree-restored', { workspace: restored });
+                return { workspace: restored, outcome: 'restored', source: checkout.source };
+            });
+        });
+    }
+    catch (err) {
+        if (err instanceof WorktreeRestoreError)
+            throw err;
+        const code = err && typeof err === 'object' && 'code' in err ? err.code : null;
+        const known = [
+            'workspace-busy',
+            'project-unavailable',
+            'path-conflict',
+            'branch-in-use',
+            'recovery-source-unavailable',
+        ];
+        const matched = known.find((candidate) => candidate === code);
+        // Don't expose Git stderr: remote URLs can contain credentials.
+        throw new WorktreeRestoreError(matched ?? 'git-failed', 'Unable to restore the worktree. Check the project and Git recovery source, then retry.');
+    }
+}