@loicngr/kobo 1.11.35 → 1.11.37

package/dist/server/services/change-source-branch-service.js

@@ -1,3 +1,4 @@
+import { withWorkspaceLifecycleGuard } from '../utils/workspace-lifecycle-guard.js';
 // src/server/services/change-source-branch-service.ts
 import { spawn } from 'node:child_process';
 import * as path from 'node:path';
@@ -44,6 +45,15 @@ const BACKUP_BRANCHES_KEPT = 3;
  * running, unknown base). Returns a status discriminating the outcome.
  */
 export async function changeSourceBranch(workspaceId, newBase) {
+    // Always acquire workspace ownership before the shared repository lock.
+    return withWorkspaceLifecycleGuard(workspaceId, () => {
+        const workspace = getWorkspace(workspaceId);
+        if (!workspace)
+            throw new Error(`Workspace '${workspaceId}' not found`);
+        return withGitRepoLock(workspace.worktreePath, () => changeSourceBranchGuarded(workspaceId, newBase));
+    });
+}
+async function changeSourceBranchGuarded(workspaceId, newBase) {
     const workspace = getWorkspace(workspaceId);
     if (!workspace)
         throw new Error(`Workspace '${workspaceId}' not found`);
@@ -85,16 +95,16 @@ export async function changeSourceBranch(workspaceId, newBase) {
         }
         // A stale index.lock makes every git write fail half-way through, and the
         // raw git message tells the user nothing. Typical origin: a setup/cleanup
-        // script SIGKILLed at its timeout during a commit. The custom-script path
-        // does not go through the repository lock, so the check is immediate here.
+        // script SIGKILLed at its timeout during a commit. Both paths hold the lock.
         gitOps.assertNoIndexLock(worktreePath);
+        gitOps.assertCurrentBranch(worktreePath, workingBranch);
         return runCustomScript(workspace, oldBase, trimmedNew, effective.changeSourceBranchScript);
     }
-    // The whole built-in strategy runs under the repository lock: it fetches,
+    // Both strategies run under the repository lock: it fetches,
     // resets and cherry-picks, all of which touch the COMMON git dir shared by
     // every worktree of the project. A concurrent fetch from the PR watcher
     // during the cherry-pick leaves it aborted mid-way.
-    return withGitRepoLock(worktreePath, () => runBuiltInStrategy(workspaceId, worktreePath, workingBranch, workspace.projectPath, oldBase, trimmedNew));
+    return runBuiltInStrategy(workspaceId, worktreePath, workingBranch, workspace.projectPath, oldBase, trimmedNew);
 }
 /** The built-in cherry-pick strategy. Always called under the repository lock. */
 async function runBuiltInStrategy(workspaceId, worktreePath, workingBranch, projectPath, oldBase, trimmedNew) {
@@ -114,6 +124,10 @@ async function runBuiltInStrategy(workspaceId, worktreePath, workingBranch, proj
     catch {
         // offline / no remote — proceed with local refs
     }
+    assertWorkspaceUnchanged(workspaceId, worktreePath, workingBranch, oldBase);
+    gitOps.assertCurrentBranch(worktreePath, workingBranch);
+    if (getAgentStatus(workspaceId) !== null)
+        throw new Error('Cannot change the source branch while the agent is running');
     if (!gitOps.branchExists(worktreePath, trimmedNew, 'origin')) {
         throw new Error(`Source branch 'origin/${trimmedNew}' does not exist`);
     }
@@ -235,6 +249,12 @@ async function runCustomScript(workspace, oldBase, newBase, script) {
     catch (err) {
         console.warn('[change-source-branch] PR lookup failed, KOBO_PR_NUMBER will be empty:', err);
     }
+    assertWorkspaceUnchanged(workspace.id, workspace.worktreePath, workspace.workingBranch, oldBase);
+    gitOps.assertCurrentBranch(workspace.worktreePath, workspace.workingBranch);
+    if (gitOps.worktreeHasChangesStrict(workspace.worktreePath))
+        return { status: 'dirty', forcePushNeeded: false, commitCount: 0 };
+    if (getAgentStatus(workspace.id) !== null)
+        throw new Error('Cannot change the source branch while the agent is running');
     return new Promise((resolve, reject) => {
         const child = spawn('bash', ['-c', script], {
             cwd: workspace.worktreePath,
@@ -292,3 +312,15 @@ async function runCustomScript(workspace, oldBase, newBase, script) {
         });
     });
 }
+/** Async lookups must not authorize mutations using obsolete workspace metadata. */
+function assertWorkspaceUnchanged(id, worktreePath, branch, sourceBranch) {
+    const current = getWorkspace(id);
+    if (!current ||
+        current.archivedAt ||
+        current.worktreePurgedAt ||
+        current.worktreePath !== worktreePath ||
+        current.workingBranch !== branch ||
+        current.sourceBranch !== sourceBranch) {
+        throw new Error('Workspace changed during source-branch validation; retry the operation');
+    }
+}

package/dist/server/services/cron-service.js

@@ -2,6 +2,7 @@ import { CronExpressionParser } from 'cron-parser';
 import { nanoid } from 'nanoid';
 import { getDb } from '../db/index.js';
 import { slugifyProjectName } from '../utils/project-slug.js';
+import { isWorkspaceLifecycleBusy } from '../utils/workspace-lifecycle-guard.js';
 import { resolveWorkspaceWorktreePath } from '../utils/worktree-paths.js';
 import * as orchestrator from './agent/orchestrator.js';
 import * as settingsService from './settings-service.js';
@@ -15,6 +16,14 @@ export const MIN_DELAY_BETWEEN_FIRES_SECONDS = 60;
 // real fire time hasn't been reached yet.
 const MAX_SETTIMEOUT_MS = 2_000_000_000; // ~23 days, with margin under 2^31-1
 const timers = new Map();
+let suspended = false;
+/** Preserve cron intent and deadlines while the process is shutting down. */
+export function suspendForShutdown() {
+    suspended = true;
+    for (const timer of timers.values())
+        clearTimeout(timer);
+    timers.clear();
+}
 /**
  * Arm a setTimeout that fires `fireOrSkip(id)` when `fireAt` is reached.
  * Replaces any existing timer for this id. Handles long horizons by
@@ -22,6 +31,8 @@ const timers = new Map();
  * days.
  */
 function scheduleAt(id, fireAt) {
+    if (suspended)
+        return;
     const previous = timers.get(id);
     if (previous)
         clearTimeout(previous);
@@ -154,6 +165,8 @@ export function listAll() {
  * unexpected error is logged and the cron is preserved when possible.
  */
 function fireOrSkip(id) {
+    if (suspended)
+        return;
     try {
         timers.delete(id);
         const db = getDb();
@@ -168,6 +181,10 @@ function fireOrSkip(id) {
             cancel(id, wsRow ? 'archive' : 'deleted');
             return;
         }
+        if (isWorkspaceLifecycleBusy(row.workspace_id)) {
+            scheduleAt(id, new Date(Date.now() + 15_000));
+            return;
+        }
         let status = 'skipped-active';
         if (!orchestrator.hasController(row.workspace_id)) {
             try {
@@ -244,6 +261,8 @@ function fireOrSkip(id) {
  * Rows pointing at deleted/archived workspaces are removed without firing.
  */
 export function restoreOnBoot() {
+    suspendForShutdown();
+    suspended = false;
     try {
         // Boot semantics: clear any existing in-memory timers before rearming.
         for (const t of timers.values())

package/dist/server/services/db-backup-service.js

@@ -90,3 +90,33 @@ export async function createPreMigrationBackup(db, dbPath, tag, keepCount = DEFA
         throw err;
     }
 }
+/** Recheck daily-backup eligibility hourly, including on long-running servers. */
+export function startDailyDbBackupScheduler(backup, intervalMs = 60 * 60 * 1000) {
+    let inFlight = null;
+    let stopped = false;
+    const attempt = async () => {
+        try {
+            await backup();
+        }
+        catch (err) {
+            console.error('[kobo] Scheduled DB backup failed:', err);
+        }
+    };
+    const tick = () => {
+        if (stopped || inFlight)
+            return;
+        inFlight = attempt().finally(() => {
+            inFlight = null;
+        });
+    };
+    const timer = setInterval(tick, intervalMs);
+    timer.unref?.();
+    tick();
+    return {
+        async stop() {
+            stopped = true;
+            clearInterval(timer);
+            await inFlight;
+        },
+    };
+}

package/dist/server/services/dev-server-service.js

@@ -1,6 +1,7 @@
 import { execFile, spawn } from 'node:child_process';
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import path from 'node:path';
+import { assertWorkspaceLifecycleAvailable } from '../utils/workspace-lifecycle-guard.js';
 import { getProjectSettings } from './settings-service.js';
 import { emitEphemeral } from './websocket-service.js';
 import { getWorkspace, listWorkspaces, updateDevServerStatus } from './workspace-service.js';
@@ -23,9 +24,13 @@ function runCommand(command, args, options = {}) {
 // ── State ──────────────────────────────────────────────────────────────────────
 /** workspaceId -> spawned dev-server process */
 const trackedProcesses = new Map();
+const stoppingProcesses = new Map();
+const generations = new Map();
 /** Test-only: clear the tracked-processes map between tests. */
 export function _resetTrackedProcessesForTests() {
     trackedProcesses.clear();
+    stoppingProcesses.clear();
+    generations.clear();
 }
 // ── Pure helpers ───────────────────────────────────────────────────────────────
 /**
@@ -84,23 +89,29 @@ export function resolveInstance(projectPath, workingBranch) {
     }
     return null;
 }
-function containerBelongsToProject(containerName, projectName) {
-    const name = containerName.toLowerCase();
-    const project = projectName.toLowerCase();
-    return name === project || name.startsWith(`${project}-`) || name.startsWith(`${project}_`);
-}
 // ── Docker helpers ─────────────────────────────────────────────────────────────
 /**
  * List all running Docker container names.
  * Uses execFile so Docker inspection cannot block the Node event loop.
  */
-export async function listRunningContainers() {
+export async function listRunningContainers(projectName) {
     try {
-        const output = await runCommand('docker', ['ps', '--format', '{{.Names}}'], { timeout: 10_000 });
+        const args = projectName
+            ? [
+                'ps',
+                '--filter',
+                `label=com.docker.compose.project=${projectName}`,
+                '--format',
+                '{{.Names}}\t{{.Label "com.docker.compose.project"}}',
+            ]
+            : ['ps', '--format', '{{.Names}}'];
+        const output = await runCommand('docker', args, { timeout: 10_000 });
         return output
             .split('\n')
             .map((s) => s.trim())
-            .filter(Boolean);
+            .filter(Boolean)
+            .filter((line) => !projectName || line.split('\t')[1] === projectName)
+            .map((line) => (projectName ? line.split('\t')[0] : line));
     }
     catch {
         return [];
@@ -128,8 +139,7 @@ export async function getStatus(projectPath, workingBranch, workspaceId) {
             containers: [],
         };
     }
-    const running = await listRunningContainers();
-    const matching = running.filter((name) => containerBelongsToProject(name, config.projectName));
+    const matching = await listRunningContainers(config.projectName);
     if (matching.length > 0) {
         return {
             status: 'running',
@@ -167,6 +177,7 @@ export async function getStatus(projectPath, workingBranch, workspaceId) {
  * Start the dev-server for a workspace.
  */
 export function startDevServer(workspaceId) {
+    assertWorkspaceLifecycleAvailable(workspaceId);
     const workspace = getWorkspace(workspaceId);
     if (!workspace) {
         throw new Error(`Workspace '${workspaceId}' not found`);
@@ -179,6 +190,8 @@ export function startDevServer(workspaceId) {
     // silently overwriting the tracked process — the first process would
     // otherwise become untrackable (never killed by stopDevServer) and its
     // exit handler could later clobber state set by the second process.
+    if (stoppingProcesses.has(workspaceId))
+        throw new Error(`Dev server for workspace '${workspaceId}' is stopping`);
     if (trackedProcesses.has(workspaceId)) {
         throw new Error(`Dev server for workspace '${workspaceId}' is already starting`);
     }
@@ -196,6 +209,8 @@ export function startDevServer(workspaceId) {
         stdio: ['ignore', 'pipe', 'pipe'],
         detached: true,
     });
+    const generation = (generations.get(workspaceId) ?? 0) + 1;
+    generations.set(workspaceId, generation);
     trackedProcesses.set(workspaceId, proc);
     // Log stdout/stderr for debugging
     proc.stdout?.on('data', (data) => {
@@ -205,21 +220,35 @@ export function startDevServer(workspaceId) {
         console.error(`[dev-server:${instanceName}] ${data.toString().trim()}`);
     });
     proc.on('exit', (code) => {
-        trackedProcesses.delete(workspaceId);
-        void getStatus(workspace.projectPath, workspace.workingBranch)
-            .then((currentStatus) => {
-            updateDevServerStatus(workspaceId, currentStatus.status);
-            emitEphemeral(workspaceId, 'devserver:status', currentStatus);
-        })
-            .catch((err) => {
-            console.error(`[dev-server] Failed to refresh status for workspace ${workspaceId}:`, err);
+        // Shell exit does not imply that its background children have stopped.
+        void (async () => {
+            while (trackedProcesses.get(workspaceId) === proc && !stoppingProcesses.has(workspaceId)) {
+                if (proc.pid && (await hasLiveProcessGroup(proc.pid))) {
+                    await pollDelay(250);
+                    continue;
+                }
+                if (trackedProcesses.get(workspaceId) !== proc || stoppingProcesses.has(workspaceId))
+                    return;
+                trackedProcesses.delete(workspaceId);
+                const currentStatus = await getStatus(workspace.projectPath, workspace.workingBranch);
+                if (generations.get(workspaceId) !== generation || stoppingProcesses.has(workspaceId))
+                    return;
+                updateDevServerStatus(workspaceId, currentStatus.status);
+                emitEphemeral(workspaceId, 'devserver:status', currentStatus);
+                return;
+            }
+        })().catch((err) => {
+            console.error(`[dev-server] Failed to confirm process-group exit for workspace ${workspaceId}:`, err);
         });
-        if (code !== 0) {
+        if (code !== 0)
             console.error(`[dev-server] Process exited with code ${code} for workspace ${workspaceId}`);
-        }
     });
     proc.on('error', (err) => {
-        trackedProcesses.delete(workspaceId);
+        if (trackedProcesses.get(workspaceId) !== proc)
+            return;
+        // A signal failure is also an 'error' event; it does not prove process exit.
+        if (!proc.pid)
+            trackedProcesses.delete(workspaceId);
         updateDevServerStatus(workspaceId, 'error');
         console.error(`[dev-server] Process error for workspace ${workspaceId}:`, err);
         emitEphemeral(workspaceId, 'devserver:status', {
@@ -249,6 +278,96 @@ export function startDevServer(workspaceId) {
  * Stop the dev-server for a workspace.
  */
 export async function stopDevServer(workspaceId) {
+    const pending = stoppingProcesses.get(workspaceId);
+    if (pending)
+        return pending;
+    generations.set(workspaceId, (generations.get(workspaceId) ?? 0) + 1);
+    const stopping = stopDevServerOwned(workspaceId);
+    stoppingProcesses.set(workspaceId, stopping);
+    try {
+        return await stopping;
+    }
+    finally {
+        if (stoppingProcesses.get(workspaceId) === stopping)
+            stoppingProcesses.delete(workspaceId);
+    }
+}
+function pollDelay(ms) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        timer.unref?.();
+    });
+}
+/** A zombie cannot write files, even if the OS has not reaped its PID yet. */
+async function hasLiveProcessGroup(groupId) {
+    try {
+        process.kill(-groupId, 0);
+    }
+    catch (err) {
+        if (err.code === 'ESRCH')
+            return false;
+        throw err;
+    }
+    const processes = await runCommand('ps', ['-eo', 'pgid=,stat='], { timeout: 1000 });
+    return processes.split('\n').some((line) => {
+        const [group, state] = line.trim().split(/\s+/);
+        return Number(group) === groupId && !!state && !/^[ZX]/.test(state);
+    });
+}
+async function signalGroupAndWait(groupId, signal, timeoutMs) {
+    try {
+        process.kill(-groupId, signal);
+    }
+    catch (err) {
+        if (err.code === 'ESRCH')
+            return true;
+        throw err;
+    }
+    const deadline = Date.now() + timeoutMs;
+    while (await hasLiveProcessGroup(groupId)) {
+        if (Date.now() >= deadline)
+            return false;
+        await pollDelay(50);
+    }
+    return true;
+}
+function signalAndWait(proc, signal, timeoutMs) {
+    if (proc.pid)
+        return signalGroupAndWait(proc.pid, signal, timeoutMs);
+    if (proc.exitCode != null || proc.signalCode != null)
+        return Promise.resolve(true);
+    return new Promise((resolve, reject) => {
+        const finish = (exited) => {
+            clearTimeout(timer);
+            proc.removeListener('exit', onExit);
+            proc.removeListener('error', onError);
+            resolve(exited);
+        };
+        const onExit = () => finish(true);
+        const onError = (err) => {
+            clearTimeout(timer);
+            proc.removeListener('exit', onExit);
+            proc.removeListener('error', onError);
+            reject(err);
+        };
+        const timer = setTimeout(() => finish(false), timeoutMs);
+        proc.once('exit', onExit);
+        proc.once('error', onError);
+        try {
+            if (proc.pid)
+                process.kill(-proc.pid, signal);
+            else
+                proc.kill(signal);
+        }
+        catch (err) {
+            clearTimeout(timer);
+            proc.removeListener('exit', onExit);
+            proc.removeListener('error', onError);
+            reject(err);
+        }
+    });
+}
+async function stopDevServerOwned(workspaceId) {
     const workspace = getWorkspace(workspaceId);
     if (!workspace) {
         throw new Error(`Workspace '${workspaceId}' not found`);
@@ -260,20 +379,15 @@ export async function stopDevServer(workspaceId) {
     // Kill tracked process first (covers Node servers and any spawned process)
     const tracked = trackedProcesses.get(workspaceId);
     if (tracked) {
-        try {
-            if (tracked.pid) {
-                process.kill(-tracked.pid, 'SIGTERM');
-            }
-            else {
-                tracked.kill('SIGTERM');
-            }
-        }
-        catch (err) {
-            console.error('[dev-server] Failed to kill tracked process:', err instanceof Error ? err.message : err);
-        }
-        trackedProcesses.delete(workspaceId);
+        const exited = (await signalAndWait(tracked, 'SIGTERM', 3_000)) || (await signalAndWait(tracked, 'SIGKILL', 1_000));
+        if (!exited)
+            throw new Error('Dev server stop is not confirmed; retry after the process exits');
+        if (trackedProcesses.get(workspaceId) === tracked)
+            trackedProcesses.delete(workspaceId);
     }
     const settings = getProjectSettings(workspace.projectPath);
+    let stopError;
+    let customStopSucceeded = false;
     if (settings?.devServer.stopCommand) {
         try {
             await runCommand('bash', ['-c', settings.devServer.stopCommand], {
@@ -285,9 +399,10 @@ export async function stopDevServer(workspaceId) {
                 },
                 timeout: 30_000,
             });
+            customStopSucceeded = true;
         }
         catch (err) {
-            console.error(`[dev-server] Stop command failed:`, err instanceof Error ? err.message : err);
+            stopError = err;
         }
     }
     // Always try docker compose down with project name if we have one
@@ -295,11 +410,26 @@ export async function stopDevServer(workspaceId) {
     if (config?.projectName) {
         try {
             await runCommand('docker', ['compose', '-p', config.projectName, 'down'], { cwd, timeout: 30_000 });
+            stopError = undefined;
         }
-        catch {
-            // May already be stopped by the custom command — ignore
+        catch (err) {
+            stopError = err;
+            // The custom command may use -f/--env-file absent from the generic fallback.
+            // Only an independent, successful Docker query can confirm it stopped everything.
+            if (customStopSucceeded) {
+                try {
+                    const remaining = await runCommand('docker', ['ps', '--filter', `label=com.docker.compose.project=${config.projectName}`, '--format', '{{.ID}}'], { timeout: 10_000 });
+                    if (!remaining.trim())
+                        stopError = undefined;
+                }
+                catch {
+                    // An unavailable daemon is not confirmation of shutdown.
+                }
+            }
         }
     }
+    if (stopError)
+        throw new Error(`Dev server stop failed: ${stopError instanceof Error ? stopError.message : String(stopError)}`);
     const status = {
         status: 'stopped',
         instanceName,
@@ -338,8 +468,7 @@ export async function getDevServerLogs(workspaceId, tail = 200) {
     if (!config) {
         return 'No dev-server instance found';
     }
-    const running = await listRunningContainers();
-    const matching = running.filter((name) => containerBelongsToProject(name, config.projectName));
+    const matching = await listRunningContainers(config.projectName);
     if (matching.length === 0) {
         return 'No running containers found';
     }

package/dist/server/services/image-service.js

@@ -1,33 +1,15 @@
+import { randomUUID } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { nanoid } from 'nanoid';
+import { ensureDirectoryInside } from '../utils/safe-path.js';
 const ALLOWED_EXTENSIONS = new Set(['png', 'jpg', 'jpeg', 'gif', 'webp']);
 const IMAGES_DIR = '.ai/images';
 const INDEX_FILE = 'index.json';
 // Per-worktree lock to serialize index.json writes
 const locks = new Map();
 function ensureRealImagesDirectory(worktreePath) {
-    const realWorktree = fs.realpathSync(worktreePath);
-    let current = worktreePath;
-    for (const segment of ['.ai', 'images']) {
-        current = path.join(current, segment);
-        if (fs.existsSync(current)) {
-            const stat = fs.lstatSync(current);
-            if (stat.isSymbolicLink())
-                throw new Error(`Symbolic links are not allowed in image storage: ${current}`);
-            if (!stat.isDirectory())
-                throw new Error(`Image storage path is not a directory: ${current}`);
-        }
-        else {
-            fs.mkdirSync(current);
-        }
-        const realCurrent = fs.realpathSync(current);
-        const relative = path.relative(realWorktree, realCurrent);
-        if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
-            throw new Error('Image storage path escapes the worktree');
-        }
-    }
-    return fs.realpathSync(current);
+    return ensureDirectoryInside(worktreePath, '.ai/images');
 }
 function withLock(worktreePath, fn) {
     const prev = locks.get(worktreePath) ?? Promise.resolve();
@@ -56,9 +38,17 @@ function writeIndex(imagesDir, entries) {
     if (fs.existsSync(indexPath) && fs.lstatSync(indexPath).isSymbolicLink()) {
         throw new Error('Symbolic links are not allowed for image index');
     }
-    const tempPath = path.join(imagesDir, `.index-${process.pid}.tmp`);
-    fs.writeFileSync(tempPath, JSON.stringify(entries, null, 2));
-    fs.renameSync(tempPath, indexPath);
+    const tempPath = path.join(imagesDir, `.index-${randomUUID()}.tmp`);
+    let created = false;
+    try {
+        fs.writeFileSync(tempPath, JSON.stringify(entries, null, 2), { flag: 'wx', mode: 0o600 });
+        created = true;
+        fs.renameSync(tempPath, indexPath);
+    }
+    finally {
+        if (created && fs.existsSync(tempPath))
+            fs.unlinkSync(tempPath);
+    }
 }
 /** Save an image buffer to `.ai/images/` and update the index. Returns the UID and relative path. */
 export async function saveImage(worktreePath, fileBuffer, originalName) {
@@ -75,10 +65,17 @@ export async function saveImage(worktreePath, fileBuffer, originalName) {
     await withLock(worktreePath, () => {
         // Write the image file inside the lock so both the file write and index
         // update happen atomically — avoids orphan files on crash between the two.
-        fs.writeFileSync(path.join(imagesDir, filename), fileBuffer);
-        const entries = readIndex(imagesDir);
-        entries.push({ uid, originalName, createdAt: new Date().toISOString() });
-        writeIndex(imagesDir, entries);
+        const imagePath = path.join(imagesDir, filename);
+        fs.writeFileSync(imagePath, fileBuffer, { flag: 'wx', mode: 0o600 });
+        try {
+            const entries = readIndex(imagesDir);
+            entries.push({ uid, originalName, createdAt: new Date().toISOString() });
+            writeIndex(imagesDir, entries);
+        }
+        catch (err) {
+            fs.unlinkSync(imagePath);
+            throw err;
+        }
     });
     return { uid, relativePath: `${IMAGES_DIR}/${filename}` };
 }

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

@@ -5,7 +5,10 @@ import path from 'node:path';
 import * as gitOps from '../utils/git-ops.js';
 import { GitConflictError } from '../utils/git-ops.js';
 import { withGitRepoLock } from '../utils/git-repo-lock.js';
+import { fingerprintWorktree } from '../utils/git-worktree-fingerprint.js';
+import { withWorkspaceLifecycleGuard } from '../utils/workspace-lifecycle-guard.js';
 import { resolveWorkspaceWorktreePath } from '../utils/worktree-paths.js';
+import { hasController } from './agent/orchestrator.js';
 import { createWorktree, listWorktrees, removeWorktreeUnlocked } from './worktree-service.js';
 /**
  * A `pathCollision.worktreePath` decision is untrusted input reaching
@@ -114,8 +117,10 @@ function diagnoseChanges(worktreePath) {
 /** Classify the workspace, if any, that already tracks this branch.
  *  A purged worktree outranks the archived flag: purging always archives, and
  *  "recreate the worktree" is the useful offer, not "unarchive". */
-export function resolveWorkspaceState(workspaces, branch) {
-    const match = workspaces.find((w) => w.workingBranch === branch);
+export function resolveWorkspaceState(workspaces, branch, projectPath) {
+    const match = workspaces.find((w) => w.workingBranch === branch &&
+        typeof w.projectPath === 'string' &&
+        path.resolve(w.projectPath) === path.resolve(projectPath));
     if (!match)
         return { state: 'none' };
     if (match.worktreePurgedAt)
@@ -134,10 +139,13 @@ function safeRevParse(repoPath, ref) {
     }
 }
 /** Hash the observed state so `/resolve` can refuse a plan built on stale facts. */
-export function computeFingerprint(report) {
+export async function computeFingerprint(report) {
     const localHead = safeRevParse(report.projectPath, report.headBranch);
     const remoteHead = safeRevParse(report.projectPath, `origin/${report.headBranch}`);
     const payload = JSON.stringify({
+        contents: report.worktree.state === 'orphan' || report.worktree.state === 'attached'
+            ? await fingerprintWorktree(report.worktree.path)
+            : null,
         localHead,
         remoteHead,
         worktree: report.worktree,
@@ -174,7 +182,7 @@ export function diagnoseLocalState(projectPath, headBranch, worktreesPath, attac
         headBranch,
         targetWorktreePath,
         blockers,
-        workspace: resolveWorkspaceState(workspaces, headBranch),
+        workspace: resolveWorkspaceState(workspaces, headBranch, projectPath),
         worktree,
         localChanges: inspectPath ? diagnoseChanges(inspectPath) : EMPTY_CHANGES,
         ongoingOperation: inspectPath ? gitOps.getOngoingGitOperation(inspectPath) : null,
@@ -249,14 +257,35 @@ export class StaleDiagnosisError extends Error {
  * or a source-branch change.
  */
 export function resolvePrCheckout(input) {
+    const initial = diagnoseLocalState(input.projectPath, input.headBranch, input.worktreesPath, input.attachedPaths, input.workspaces);
+    const owner = initial.worktree.state === 'attached'
+        ? initial.worktree.workspaceId
+        : initial.workspace.state !== 'none'
+            ? initial.workspace.id
+            : null;
+    const resolve = () => resolvePrCheckoutLocked(input, owner);
+    return owner ? withWorkspaceLifecycleGuard(owner, resolve) : resolve();
+}
+function resolvePrCheckoutLocked(input, owner) {
     return withGitRepoLock(input.projectPath, async () => {
+        if (owner && hasController(owner))
+            throw new Error('Stop the workspace agent before changing its checkout');
         const applied = [];
         // 1. Refresh, then refuse a plan built on facts that no longer hold.
         gitOps.fetchSourceBranch(input.projectPath, input.headBranch);
         applied.push({ kind: 'fetch', detail: `origin/${input.headBranch}` });
         const fresh = diagnoseLocalState(input.projectPath, input.headBranch, input.worktreesPath, input.attachedPaths ?? new Map(), input.workspaces ?? []);
-        if (computeFingerprint(fresh) !== input.fingerprint)
+        if ((await computeFingerprint(fresh)) !== input.fingerprint)
             throw new StaleDiagnosisError(fresh);
+        if ((fresh.worktree.state === 'orphan' || fresh.worktree.state === 'attached') &&
+            input.decisions.orphanWorktree === 'create-elsewhere') {
+            throw new Error('Branch is already checked out. Attach its existing worktree instead.');
+        }
+        if (fresh.localChanges.present &&
+            (input.decisions.localChanges ?? 'keep') === 'keep' &&
+            input.decisions.divergence === 'reset-hard') {
+            throw new Error('Cannot preserve local changes during a hard reset. Stash or commit them first, or keep the branch.');
+        }
         // 2. Clear stale worktree metadata before anything needs the path.
         if (fresh.worktree.state === 'stale-metadata') {
             git(input.projectPath, ['worktree', 'prune']);