@doxbrix/doxloop 0.1.4 → 0.2.0

package/dist/sync-runs.js

@@ -0,0 +1,2244 @@
+import { mergeAgentUsage } from './agent-log.js';
+import { safePath } from './direct-edit.js';
+import { approvedBatchLimits, batchLimits } from './batch-limits.js';
+import { withProjectLock } from './project-lock.js';
+import { createHash, randomBytes } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { cp, mkdir, mkdtemp, readFile, readdir, rename, rm, unlink, writeFile, } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { isDeepStrictEqual, promisify } from 'node:util';
+import { EDIT_MIN_MAX_TURNS, EDIT_TURNS_PER_PAGE, agentExitMessage, editPrompt, runAuthor, } from './author.js';
+import { DoxloopError } from './errors.js';
+import { computeDrift } from './drift.js';
+import { assertInside, pathExists, readJson } from './fs.js';
+import { matchesGlob } from './globs.js';
+import { recordSourceSyncs, recordSyncRun, syncPageRegistry, } from './history.js';
+import { applyAuthoringPostPass, removeSupersededStarterPages } from './authoring-postpass.js';
+import { loadProject, pageExtensions as documentationPageExtensions, projectDefaultModel, readPage } from './project.js';
+import { listPages as listDocumentationPages, resolveEditScope } from './pages.js';
+import { recordReviewPreference } from './review-learning.js';
+import { SCREENSHOT_MANIFEST_FILE, adoptCapturedImages, collapseDuplicateCaptures, describeScreenshotManifestProgress, embedMissingCaptures, normalizeScreenshotIntent, screenshotPlanSummary, validateScreenshotManifest, } from './screenshot-workflow.js';
+import { changedSourcePaths, collectSourceChanges, formatSourceChanges, sourceSnapshotFingerprints } from './sync.js';
+import { lineHunks, textLines } from './text-diff.js';
+import { formatValidation, isStarterContent, validateProject } from './validation.js';
+export const SYNC_RUNS_DIRECTORY = join('.doxloop', 'runs');
+const RUN_FILE = 'run.json';
+/** The inputs an agent run was started with, kept so the run can be continued. */
+const AUTHORING_FILE = 'authoring.json';
+const WORKSPACE = 'workspace';
+const BEFORE = 'before';
+const OPERATIONAL_BEFORE = 'operational-before';
+const ACCEPTANCE_BEFORE = 'acceptance-before';
+const APPLIED = 'applied';
+/** Content hashes of every file as the run workspace was created. */
+const BASELINE_FILE = 'baseline.json';
+const EXCLUDED_PREFIXES = [
+    '.git',
+    '.agents',
+    '.claude',
+    '.codex',
+    '.gemini',
+    'node_modules',
+    '.doxloop/runs',
+    // Plan manifests are workflow state. The real plan advances from generating
+    // to generated after its proposal workspace is finalized, so offering that
+    // snapshot as a documentation change creates an unavoidable false conflict.
+    '.doxloop/plans',
+    '.doxloop/cache',
+    '.doxloop/last-run.json',
+    '.doxloop/sync.log',
+    '.doxloop/ui-jobs.json',
+    '.doxloop/ui-job-logs',
+    '.doxloop/review-preferences.json',
+    '.doxloop/screenshot-manifest.json',
+    '.doxloop/deliveries',
+    '.doxloop/locks',
+    '.doxloop/direct-edits',
+    '.doxloop/monitor-budget.json',
+    '.doxloop/monitor-interval.json',
+    '.doxloop/comments.json',
+    '.doxloop/sync.log.1',
+    // Raw browser captures are run scratch space. Adopted images are placed
+    // beside the pages that use them, so the staging folder is never a change.
+    '.doxloop/capture-output',
+    // Images a downgrade set aside stay with the run for recovery; they are
+    // never proposed.
+    '.doxloop/quarantine',
+    // History is a derived local index. Copying it into a proposal workspace would
+    // offer the database back as a binary documentation change.
+    '.doxloop/doxloop.db',
+    '.doxloop/doxloop.db-wal',
+    '.doxloop/doxloop.db-shm',
+    'build',
+    'dist',
+    'out',
+    'site',
+    '_build',
+];
+const INTERNAL_DIFF_PATHS = new Set([
+    '.doxloop/last-run.json',
+    '.doxloop/sync-state.json',
+    '.doxloop/sync.log',
+]);
+const runCommand = promisify(execFile);
+const BINARY_EXTENSIONS = new Set([
+    '.avif',
+    '.gif',
+    '.ico',
+    '.jpeg',
+    '.jpg',
+    '.pdf',
+    '.png',
+    '.ttf',
+    '.otf',
+    '.webp',
+    '.woff',
+    '.woff2',
+    '.zip',
+]);
+/** Generate and validate a proposal without changing the real documentation. */
+export async function createSyncRun(options) {
+    return withProjectLock(options.root, 'authoring', () => createSyncRunLocked(options), 0);
+}
+async function createSyncRunLocked(options) {
+    const previous = options.revisionOf ? await readSyncRun(options.root, options.revisionOf) : undefined;
+    const inheritedEditRequest = options.editRequest ?? previous?.editRequest;
+    const editRequest = inheritedEditRequest
+        ? { ...inheritedEditRequest, paths: [...new Set(inheritedEditRequest.paths)] }
+        : undefined;
+    const revisionScope = previous?.editRequest && editRequest
+        ? await resolveEditScope(options.root, options.project, editRequest.paths, editRequest.allowRelated)
+        : options.revisionOf
+            ? await resolveRevisionScope(options.root, options.revisionOf, options.revisionRequest)
+            : editRequest
+                ? await resolveEditScope(options.root, options.project, editRequest.paths, editRequest.allowRelated)
+                : undefined;
+    const id = options.id ?? createRunId();
+    assertRunId(id);
+    const pageSummaries = editRequest ? await listDocumentationPages(options.root) : [];
+    const editPages = editRequest
+        ? editRequest.paths.map((path) => ({ path, title: pageSummaries.find((page) => page.path === path)?.title ?? path.split('/').at(-1) ?? path }))
+        : [];
+    const directory = runDirectory(options.root, id);
+    await mkdir(directory, { recursive: true });
+    await ensureRunsIgnored(options.root);
+    if (options.plan)
+        await writeFile(join(directory, 'approved-plan.json'), JSON.stringify(options.plan), { mode: 0o600 });
+    const createdAt = new Date().toISOString();
+    const sourceSnapshot = await proposalSourceSnapshot(options.root, options.project);
+    await snapshotOperationalBefore(options.root, directory);
+    let run = {
+        schemaVersion: 2,
+        id,
+        status: 'generating',
+        mode: editRequest ? 'propose' : options.project.sync.mode === 'auto' ? 'auto' : 'propose',
+        trigger: options.trigger ?? (editRequest ? 'edit' : 'manual'),
+        createdAt,
+        summary: editRequest
+            ? editPages.length === 1 ? `Editing ${editPages[0].title}` : `Editing ${editPages.length} pages`
+            : options.plan ? `Writing ${options.plan.pages.filter((page) => ['create', 'update'].includes(page.action)).length} approved pages` : options.authoring ? 'Preparing the requested documentation update' : `Generating a review for ${options.drift.pages.length} stale page${options.drift.pages.length === 1 ? '' : 's'}`,
+        sourceSummary: sourceSummary(options.sourceChanges),
+        stalePages: options.drift.pages.map((page) => page.page),
+        changes: [],
+        sourceSnapshot,
+        ...(options.authoring?.mode ? { authoringMode: options.authoring.mode } : {}),
+        ...(options.plan ? { planId: options.plan.id } : {}),
+        ...(editRequest ? { editRequest } : {}),
+        ...(options.revisionOf ? { revisionOf: options.revisionOf } : {}),
+        retentionUntil: retentionDate(createdAt),
+        revisionRequests: options.revisionRequest ? [{
+                id: `revision-${randomBytes(3).toString('hex')}`,
+                createdAt,
+                instruction: options.revisionRequest.instruction,
+                changeIds: options.revisionRequest.changeIds,
+                hunkIds: options.revisionRequest.hunkIds ?? [],
+            }] : [],
+        humanEdits: [],
+    };
+    await writeRun(options.root, run);
+    const history = {
+        requestText: editRequest?.instruction ?? options.authoring?.historyRequest ?? options.authoring?.request,
+        agent: options.authoring?.agent ?? options.project.defaultAgent,
+        model: options.authoring?.model ?? projectDefaultModel(options.project, options.authoring?.agent ?? options.project.defaultAgent),
+        reasoningEffort: options.authoring?.reasoning ?? options.authoring?.effort,
+        runDir: join(SYNC_RUNS_DIRECTORY, id),
+    };
+    await recordSyncRun(options.root, run, history);
+    if (editRequest) {
+        const learned = editRequest.followUps.at(-1)?.instruction ?? editRequest.instruction;
+        await recordReviewPreference(options.root, { kind: 'edit', paths: editRequest.paths, instruction: learned }).catch(() => undefined);
+    }
+    const screenshotIntent = normalizeScreenshotIntent(options.authoring?.screenshots ?? (editRequest ? 'disabled' : undefined));
+    const expectedScreenshots = options.plan ? screenshotPlanSummary(options.plan) : { guides: 0, captures: 0 };
+    const changeSummary = options.sourceChanges.length > 0
+        ? formatSourceChanges(options.sourceChanges.map((change) => ({
+            ...change,
+            path: isAbsolute(change.path)
+                ? change.path
+                : resolve(options.root, change.path),
+        })))
+        : undefined;
+    // Everything the agent was started with is kept beside the run, so a run
+    // that stops part-way can be continued with the same instructions instead
+    // of being thrown away and generated again from nothing.
+    const persisted = {
+        schemaVersion: 1,
+        mode: options.authoring?.mode ?? 'update',
+        trigger: options.trigger ?? (editRequest ? 'edit' : 'manual'),
+        screenshots: screenshotIntent,
+        ...(options.authoring?.request ? { request: options.authoring.request } : {}),
+        ...(options.authoring?.historyRequest ? { historyRequest: options.authoring.historyRequest } : {}),
+        ...(options.authoring?.agent ?? options.project.defaultAgent
+            ? { agent: (options.authoring?.agent ?? options.project.defaultAgent) }
+            : {}),
+        ...(options.authoring?.model ?? projectDefaultModel(options.project, options.authoring?.agent ?? options.project.defaultAgent)
+            ? { model: (options.authoring?.model ?? projectDefaultModel(options.project, options.authoring?.agent ?? options.project.defaultAgent)) }
+            : {}),
+        ...(options.authoring?.reasoning ? { reasoning: options.authoring.reasoning } : {}),
+        ...(options.authoring?.effort ? { effort: options.authoring.effort } : {}),
+        ...((options.plan || options.project.sync.budget?.maxMinutes) ? { timeoutMinutes: Math.min(options.plan ? batchLimits(options.plan.execution.limits).maxMinutes : 120, options.project.sync.budget?.maxMinutes ?? 120) } : {}),
+        ...(changeSummary ? { changeSummary } : {}),
+        ...(options.authoringSources ? { authoringSources: options.authoringSources } : {}),
+        ...(options.nextSyncState ? { nextSyncState: options.nextSyncState } : {}),
+        ...(editRequest ? { editRequest } : {}),
+    };
+    await writeFile(join(directory, AUTHORING_FILE), `${JSON.stringify(persisted, null, 2)}\n`, 'utf8');
+    let workspaceCreated = false;
+    try {
+        const originalProjectText = await readFile(join(options.root, '.doxloop', 'project.json'), 'utf8');
+        const workspace = await createWorkspace(options.root, directory, options.project, options.authoringSources);
+        workspaceCreated = true;
+        if (options.revisionOf) {
+            await seedRevisionWorkspace(options.root, options.revisionOf, workspace);
+            await rewriteWorkspaceSources(workspace, options.root, {
+                ...options.project,
+                sources: options.authoringSources ?? options.project.sources,
+            });
+        }
+        const revisionBaseline = revisionScope ? await collectFiles(workspace) : undefined;
+        const scopedEditPrompt = editRequest ? editPrompt({
+            pages: editPages,
+            instruction: editRequest.instruction,
+            allowRelated: editRequest.allowRelated,
+            followUps: editRequest.followUps,
+        }) : undefined;
+        let failureDetail;
+        let usage;
+        const exitCode = await (options.author ?? runAuthor)({
+            onFailure: (detail) => { failureDetail = detail; },
+            onUsage: (recorded) => { usage = recorded; },
+            root: workspace,
+            captureAuthRoot: options.root,
+            mode: editRequest ? 'update' : persisted.mode,
+            nonInteractive: true,
+            recordHistory: false,
+            // A plan-first run writes its pages in short batches with Doxloop's
+            // repairs and validation between them; edits and revisions are one
+            // scoped session.
+            ...(options.plan && !editRequest && !options.revisionOf ? { planBatches: true } : {}),
+            ...(editRequest ? { recordOperationalState: false } : {}),
+            ...(changeSummary ? { changeSummary } : {}),
+            ...(options.project.defaultAgent ? { agent: options.project.defaultAgent } : {}),
+            ...(options.project.sync.budget?.maxMinutes
+                ? { timeoutMinutes: options.project.sync.budget.maxMinutes }
+                : {}),
+            ...(options.project.sync.budget?.maxUsd ? { maxBudgetUsd: options.project.sync.budget.maxUsd } : {}),
+            ...options.authoring,
+            ...(persisted.timeoutMinutes ? { timeoutMinutes: persisted.timeoutMinutes } : {}),
+            ...(scopedEditPrompt ? { request: scopedEditPrompt } : {}),
+            ...(editRequest ? {
+                maxTurns: Math.max(EDIT_MIN_MAX_TURNS, 40 + EDIT_TURNS_PER_PAGE * editRequest.paths.length),
+                timeoutMinutes: options.project.sync.budget?.maxMinutes ?? 15,
+                tolerateValidationErrors: true,
+                plannedPages: editRequest.paths.length,
+                progressLabel: 'Editing selected pages',
+            } : options.revisionOf ? { progressLabel: 'Revising proposed pages' } : {}),
+        });
+        if (usage)
+            run = { ...run, usage };
+        if (exitCode !== 0) {
+            throw new DoxloopError(agentExitMessage(exitCode, failureDetail));
+        }
+        if (revisionBaseline && revisionScope) {
+            await assertRevisionStayedInScope(workspace, revisionBaseline, revisionScope, Boolean(editRequest));
+        }
+        const finalized = await finalizeProposalWorkspace({
+            context: options,
+            directory,
+            workspace,
+            originalProjectText,
+            screenshotIntent,
+            label: 'generated',
+        });
+        run = {
+            ...run,
+            status: 'awaiting-review',
+            completedAt: new Date().toISOString(),
+            summary: proposalSummary(finalized.changes),
+            changes: finalized.changes,
+            validation: finalized.validation,
+            screenshots: finalized.screenshots,
+            ...withAdvisories(run, finalized.advisories),
+            undo: { status: 'unavailable', reason: 'Undo becomes available after the complete proposal is applied.' },
+        };
+        await writeRun(options.root, run);
+        if (options.revisionOf)
+            await markSuperseded(options.root, options.revisionOf, run.id);
+        await recordSyncRun(options.root, run, history);
+        return run;
+    }
+    catch (error) {
+        run = await failedRun(run, error, {
+            workspace: runWorkspace(options.root, run.id),
+            screenshotIntent,
+            expectedScreenshots,
+            recovery: { resumable: workspaceCreated && !options.revisionOf, ignorable: workspaceCreated },
+        });
+        await writeRun(options.root, run);
+        await recordSyncRun(options.root, run, history);
+        return run;
+    }
+}
+async function readPersistedAuthoring(root, id) {
+    const path = join(runDirectory(root, id), AUTHORING_FILE);
+    if (!(await pathExists(path)))
+        return undefined;
+    try {
+        const value = await readJson(path);
+        if (!value || value.schemaVersion !== 1 || (value.mode !== 'create' && value.mode !== 'update'))
+            return undefined;
+        return value;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function failedRun(run, error, details) {
+    const message = error instanceof Error ? error.message : String(error);
+    let captured = 0;
+    let textOnly = 0;
+    try {
+        captured = (await describeScreenshotManifestProgress(details.workspace, undefined)).verified;
+        const manifest = JSON.parse(await readFile(join(details.workspace, SCREENSHOT_MANIFEST_FILE), 'utf8'));
+        textOnly = (manifest.guides ?? []).flatMap((guide) => guide.steps ?? []).filter((step) => step.status === 'text-only' && step.textOnlyReason?.trim()).length;
+    }
+    catch { /* A failure before capture has no saved progress. */ }
+    return {
+        ...run,
+        status: 'failed',
+        completedAt: new Date().toISOString(),
+        error: message,
+        ...(details.expectedScreenshots.guides > 0 && details.screenshotIntent !== 'disabled' ? {
+            screenshots: {
+                intent: details.screenshotIntent,
+                status: 'failed',
+                planned: details.expectedScreenshots.captures,
+                captured,
+                textOnly,
+                guides: details.expectedScreenshots.guides,
+                message,
+            },
+        } : {}),
+        summary: 'Proposal generation failed',
+        recovery: details.recovery,
+    };
+}
+/**
+ * The post-agent pipeline every proposal goes through before review: restore
+ * the portable source bindings, check the screenshot manifest, validate the
+ * documentation, and turn the workspace into reviewable changes. Shared by a
+ * fresh run, a recovered run, and a resumed run so all three are judged alike.
+ */
+async function finalizeProposalWorkspace(input) {
+    const advisories = [];
+    const { context, workspace, directory } = input;
+    if (context.nextSyncState) {
+        await writeFile(join(workspace, '.doxloop', 'sync-state.json'), `${JSON.stringify(context.nextSyncState, null, 2)}\n`, 'utf8');
+    }
+    // The staged project uses absolute sources so it can live away from the real
+    // project. Restore the user's portable bindings before calculating changes.
+    await restoreWorkspaceSources(workspace, context.project, input.originalProjectText);
+    if (input.repairCaptures) {
+        // An agent that stopped early may have left real images unrecorded or
+        // unplaced; claim them the way a completed run would before judging.
+        await adoptCapturedImages(workspace, context.project.generator, context.plan);
+        await collapseDuplicateCaptures(workspace, context.plan);
+        await embedMissingCaptures(workspace, context.plan);
+    }
+    // A capture shortfall is never a reason to discard finished pages: every
+    // defect becomes a text-only step and is listed on the run for review.
+    const screenshotResult = await validateScreenshotManifest(workspace, context.plan, input.screenshotIntent, {
+        ...(input.tolerateScreenshotDefects !== false ? { tolerateDefects: true } : {}),
+    });
+    if (screenshotResult.manifest) {
+        await writeFile(join(directory, 'screenshots.json'), `${JSON.stringify(screenshotResult.manifest, null, 2)}\n`, 'utf8');
+    }
+    let validation = await validateProject(workspace);
+    if (validation.errors > 0 && !context.editRequest && context.plan) {
+        // The accept check is the same validation; running Doxloop's repairs here
+        // means a run that ends "generated" is one the reviewer can apply.
+        const repaired = await repairWorkspaceBeforeReview(workspace, context.project, context.plan, validation.issues);
+        for (const line of repaired)
+            advisories.push(`Repaired before review: ${line}`);
+        if (repaired.length > 0)
+            validation = await validateProject(workspace);
+    }
+    if (validation.errors > 0 && !context.editRequest) {
+        if (!context.plan) {
+            throw new DoxloopError(`The ${input.label} proposal did not pass validation:\n${formatValidation(validation)}`);
+        }
+        // A plan run already had Doxloop's repairs and fix sessions; what is left
+        // is for the reviewer to see and revise, and applying stays blocked until
+        // the errors are gone.
+        advisories.push(`${validation.errors} validation error${validation.errors === 1 ? '' : 's'} remain in this proposal; it cannot be applied until they are fixed. Use Repair proposal to let Doxloop fix links and navigation without an agent, or ask for a revision of the affected pages: ${[...new Set(validation.issues.filter((issue) => issue.severity === 'error').map((issue) => issue.file ?? 'project'))].slice(0, 12).join(', ')}.`);
+    }
+    const collected = await collectProposalChanges(context.root, workspace, directory, context.project);
+    if (context.plan) {
+        const limits = approvedBatchLimits(context.plan);
+        const outside = [];
+        let counted = 0;
+        for (const page of collected.filter((change) => change.category === 'page')) {
+            const planned = matchPlanPage(context.plan, page.path);
+            if (!planned) {
+                // Every brief tells the agent to replace generated starter pages, and
+                // the plan may put a starter's replacement at a new path or leave the
+                // starter out altogether. Removing the scaffold, or rewriting it in
+                // place when the site needs the file (a landing page), is part of the
+                // approved work, not an expansion of it.
+                if ((page.kind === 'deleted' || page.kind === 'modified') && await isStarterFile(join(directory, BEFORE, page.path))) {
+                    if (page.kind === 'modified')
+                        counted += 1;
+                    continue;
+                }
+                // An existing page the plan did not name but the writer touched (a
+                // landing page gaining links to the new pages, a related guide's
+                // cross-reference) is reviewable like any other change; only new or
+                // deleted pages expand the batch.
+                if (page.kind === 'modified') {
+                    counted += 1;
+                    advisories.push(`${page.path} was modified although the plan did not name it; review that change before accepting.`);
+                    continue;
+                }
+                outside.push(`${page.path} (${page.kind}, not in the plan)`);
+                continue;
+            }
+            if (planned.priority === 'later')
+                outside.push(`${page.path} (deferred to Later)`);
+            else if (planned.action === 'preserve')
+                outside.push(`${page.path} (planned to preserve)`);
+            else if (page.kind === 'deleted' && planned.action !== 'remove')
+                outside.push(`${page.path} (deleted, but planned to ${planned.action})`);
+            counted += 1;
+        }
+        // Scope overruns are reviewable, not fatal: the pages are in the
+        // proposal with a note, and the reviewer rejects the ones they do not
+        // want. Failing here discarded a finished run over one extra page.
+        if (outside.length > 0)
+            advisories.push(`Outside the approved plan (review before accepting): ${outside.join(', ')}.`);
+        if (counted > limits.maxPages)
+            advisories.push(`${counted} pages changed; the approved batch allows ${limits.maxPages}. Reject the extra pages if they are not wanted.`);
+        if (screenshotResult.summary.captured > limits.maxScreenshots)
+            advisories.push(`${screenshotResult.summary.captured} screenshots captured; the approved batch allows ${limits.maxScreenshots}.`);
+    }
+    advisories.push(...await repairProposalSourceScopes(workspace, collected, context.project));
+    const changes = await enrichProposalRationales(context.root, workspace, collected, context, validation);
+    if (changes.length === 0) {
+        throw new DoxloopError(input.label === 'generated'
+            ? 'The agent completed without proposing any documentation changes.'
+            : 'The preserved workspace contains no documentation changes to recover.');
+    }
+    return {
+        advisories,
+        changes,
+        validation: {
+            pages: validation.pages.length,
+            errors: validation.errors,
+            warnings: validation.warnings,
+            ...(context.editRequest && validation.issues.length > 0 ? { issues: validation.issues } : {}),
+        },
+        screenshots: screenshotResult.summary,
+    };
+}
+/**
+ * Doxloop's deterministic repairs over a finished workspace: navigation and
+ * frontmatter, links to pages that exist, embeds of images that do not, and
+ * the generated starter pages the plan superseded. No agent session.
+ */
+export async function repairWorkspaceBeforeReview(workspace, project, plan, issues) {
+    const lines = [];
+    try {
+        const report = await applyAuthoringPostPass({ workspace, project: await loadProject(workspace).catch(() => project), plan, pages: plan.pages, unlinkUnresolved: true, pruneEmptySpaces: true });
+        lines.push(...report.repairs);
+        const starters = await removeSupersededStarterPages(workspace, issues, report);
+        if (starters.length > 0) {
+            // Their navigation entries and links go with them.
+            const again = await applyAuthoringPostPass({ workspace, project: await loadProject(workspace).catch(() => project), plan, pages: plan.pages, unlinkUnresolved: true, pruneEmptySpaces: true });
+            lines.push(...starters.map((file) => `${file}: removed the starter page the plan superseded.`), ...again.repairs);
+        }
+    }
+    catch (error) {
+        lines.push(`post-pass could not run: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return lines;
+}
+/**
+ * Re-run the post-agent finalization pipeline on a failed run's preserved
+ * workspace and promote it to review. This recovers completed agent work when
+ * the failure happened after authoring — for example a screenshot-manifest
+ * validation defect — without paying for another full agent run.
+ */
+export async function recoverSyncRun(root, id, options = {}) {
+    return withProjectLock(root, 'authoring', () => recoverSyncRunLocked(root, id, options), 0);
+}
+async function recoverSyncRunLocked(root, id, options) {
+    const run = await readSyncRun(root, id);
+    if (run.archivedAt)
+        throw new DoxloopError(`Proposal ${id} is archived and cannot be recovered.`);
+    const repairable = options.repair === true && run.status === 'awaiting-review';
+    if (run.status !== 'failed' && run.status !== 'generating' && !repairable) {
+        throw new DoxloopError(`Only a failed or interrupted proposal can be recovered; ${id} is ${run.status}.`);
+    }
+    const workspace = runWorkspace(root, id);
+    if (!(await pathExists(workspace))) {
+        throw new DoxloopError(`Proposal ${id} no longer has a preserved workspace to recover. Generate a new proposal instead.`);
+    }
+    const project = await loadProject(root);
+    if (options.repair) {
+        const approved = await recoveryPlan(root, runDirectory(root, id), run.planId);
+        if (approved) {
+            const report = await applyAuthoringPostPass({ workspace, project: await loadProject(workspace).catch(() => project), plan: approved, pages: approved.pages, unlinkUnresolved: true, pruneEmptySpaces: true });
+            for (const line of report.repairs)
+                process.stdout.write(`Repaired: ${line}\n`);
+        }
+    }
+    // Sources that changed while the run sat failed never block continuing it:
+    // the work in the workspace is still worth reviewing, and the reviewer is
+    // told to read it against the current evidence instead.
+    const currentSnapshot = await proposalSourceSnapshot(root, project);
+    const sourcesChanged = Boolean(run.sourceSnapshot && currentSnapshot !== run.sourceSnapshot);
+    const directory = runDirectory(root, id);
+    const plan = await recoveryPlan(root, directory, run.planId);
+    const authoring = await readPersistedAuthoring(root, id);
+    const screenshotIntent = normalizeScreenshotIntent(authoring?.screenshots ?? run.screenshots?.intent ?? plan?.execution?.screenshots);
+    const history = authoring ? historyContext(id, authoring, project) : {};
+    try {
+        const originalProjectText = await readFile(join(root, '.doxloop', 'project.json'), 'utf8');
+        const context = {
+            root,
+            project,
+            drift: await computeDrift(root, project),
+            sourceChanges: await collectSourceChanges(root, project.sources),
+            ...(run.editRequest ? { editRequest: run.editRequest } : {}),
+            ...(plan ? { plan } : {}),
+            ...(authoring?.nextSyncState ? { nextSyncState: authoring.nextSyncState } : {}),
+            authoring: {
+                ...(authoring?.mode ? { mode: authoring.mode } : {}),
+                ...(authoring?.request ? { request: authoring.request } : {}),
+                ...(authoring?.agent ? { agent: authoring.agent } : {}),
+                ...(authoring?.model ? { model: authoring.model } : {}),
+                ...(authoring?.reasoning ? { reasoning: authoring.reasoning } : {}),
+                ...(authoring?.effort ? { effort: authoring.effort } : {}),
+                screenshots: screenshotIntent,
+            },
+        };
+        if (run.editRequest) {
+            await restoreWorkspaceSources(workspace, project, originalProjectText);
+            await assertRevisionStayedInScope(workspace, await collectFiles(root), await resolveEditScope(root, project, run.editRequest.paths, run.editRequest.allowRelated), true);
+        }
+        const finalized = await finalizeProposalWorkspace({
+            context,
+            directory,
+            workspace,
+            originalProjectText,
+            screenshotIntent,
+            repairCaptures: true,
+            ...(options.ignoreScreenshotProblems ? { tolerateScreenshotDefects: true } : {}),
+            label: options.repair ? 'repaired' : 'recovered',
+        });
+        // Advisories are rebuilt below from the repaired workspace; an empty result must not keep the old list.
+        const { error: _previousError, recovery: _recovery, advisories: _previousAdvisories, ...cleanRun } = run;
+        const next = {
+            ...cleanRun,
+            status: 'awaiting-review',
+            completedAt: new Date().toISOString(),
+            summary: proposalSummary(finalized.changes),
+            changes: finalized.changes,
+            validation: finalized.validation,
+            screenshots: finalized.screenshots,
+            sourceSnapshot: currentSnapshot,
+            ...withAdvisories(withAdvisoryRun(run, sourcesChanged ? SOURCES_CHANGED_RECOVERED : undefined), finalized.advisories, true),
+            undo: { status: 'unavailable', reason: 'Undo becomes available after the complete proposal is applied.' },
+        };
+        await writeRun(root, next);
+        await recordSyncRun(root, next, history);
+        return next;
+    }
+    catch (error) {
+        const failed = {
+            ...run,
+            status: 'failed',
+            error: error instanceof Error ? error.message : String(error),
+            recovery: { resumable: Boolean(authoring) && !run.revisionOf, ignorable: true },
+        };
+        await writeRun(root, failed);
+        await recordSyncRun(root, failed, history);
+        throw error;
+    }
+}
+const SOURCES_CHANGED_RECOVERED = 'Configured sources changed after this run stopped. Its pages were kept as generated; review their claims against the current sources before accepting.';
+const SOURCES_CHANGED_RESUMED = 'Configured sources changed after this run stopped. The resumed agent was told to re-check the pages it touched against the current sources.';
+const SOURCES_CHANGED_DURING_REVIEW = 'Configured sources changed after this proposal was generated. The proposal was kept and remains editable and applicable; review its claims against the current sources.';
+const LEGACY_STALE_SOURCE_ERROR = 'Configured source evidence changed after this proposal was generated.';
+/** Add a reviewer note to a run without repeating one it already carries. */
+function withAdvisory(run, advisory) {
+    return withAdvisories(run, advisory ? [advisory] : []);
+}
+/**
+ * Notes the finalize step writes from the workspace as it is now. A repair
+ * recomputes them, so earlier copies are dropped rather than kept as stale
+ * claims about a workspace that has since changed.
+ */
+function isFinalizeAdvisory(note) {
+    return /^Repaired before review: |validation errors? remains? in this proposal|was modified although the plan did not name it|^Outside the approved plan|; the approved batch allows /.test(note);
+}
+function withAdvisories(run, notes, replaceFinalize = false) {
+    const advisories = (run.advisories ?? []).filter((note) => !(replaceFinalize && isFinalizeAdvisory(note)));
+    for (const note of notes)
+        if (note && !advisories.includes(note))
+            advisories.push(note);
+    return advisories.length > 0 ? { advisories } : {};
+}
+function withAdvisoryRun(run, advisory) {
+    return { ...run, ...withAdvisory(run, advisory) };
+}
+function historyContext(id, authoring, project) {
+    return {
+        requestText: authoring.historyRequest ?? authoring.request,
+        agent: authoring.agent ?? project.defaultAgent,
+        model: authoring.model ?? projectDefaultModel(project, authoring.agent ?? project.defaultAgent),
+        reasoningEffort: authoring.reasoning ?? authoring.effort,
+        runDir: join(SYNC_RUNS_DIRECTORY, id),
+    };
+}
+/**
+ * Continue a failed or interrupted run's agent inside its preserved workspace.
+ *
+ * The agent is started with the same instructions as before plus a brief of
+ * what already exists — verified screenshots, finished guides, the reason the
+ * run stopped — so it completes only the unfinished part instead of writing
+ * every page and capturing every image again. The run keeps its id, so the
+ * plan that started it and its review history stay attached.
+ */
+export async function resumeSyncRun(root, id, options = {}) {
+    return withProjectLock(root, 'authoring', () => resumeSyncRunLocked(root, id, options), 0);
+}
+async function resumeSyncRunLocked(root, id, options) {
+    const run = await readSyncRun(root, id);
+    if (run.archivedAt)
+        throw new DoxloopError(`Proposal ${id} is archived and cannot be resumed.`);
+    if (run.status !== 'failed' && run.status !== 'generating') {
+        throw new DoxloopError(`Only a failed or interrupted proposal can be resumed; ${id} is ${run.status}.`);
+    }
+    if (run.revisionOf) {
+        throw new DoxloopError('A targeted revision cannot be resumed. Ask for the revision again from the proposal it revises.');
+    }
+    const workspace = runWorkspace(root, id);
+    if (!(await pathExists(workspace))) {
+        throw new DoxloopError(`Proposal ${id} no longer has a preserved workspace to resume. Generate a new proposal instead.`);
+    }
+    const authoring = (await readPersistedAuthoring(root, id))
+        ?? (options.fallbackAuthoring ? { schemaVersion: 1, ...options.fallbackAuthoring } : undefined);
+    if (!authoring) {
+        throw new DoxloopError(`Proposal ${id} did not record the instructions it was started with, so it cannot be resumed. Recover its output or generate a new proposal instead.`);
+    }
+    const project = await loadProject(root);
+    // A source edit made while the run was stopped is a reason to re-check the
+    // pages, not to discard them: the resumed agent reads the current sources.
+    const currentSnapshot = await proposalSourceSnapshot(root, project);
+    const sourcesChanged = Boolean(run.sourceSnapshot && currentSnapshot !== run.sourceSnapshot);
+    const directory = runDirectory(root, id);
+    const plan = await recoveryPlan(root, directory, run.planId);
+    const screenshotIntent = normalizeScreenshotIntent(authoring.screenshots);
+    const expectedScreenshots = plan ? screenshotPlanSummary(plan) : { guides: 0, captures: 0 };
+    const history = historyContext(id, authoring, project);
+    const { error: _previousError, recovery: _recovery, completedAt: _completedAt, validation: _validation, screenshots: _screenshots, ...cleanRun } = run;
+    let next = {
+        ...cleanRun,
+        status: 'generating',
+        resumedAt: new Date().toISOString(),
+        summary: 'Continuing the interrupted documentation run',
+        sourceSnapshot: currentSnapshot,
+        ...withAdvisory(run, sourcesChanged ? SOURCES_CHANGED_RESUMED : undefined),
+    };
+    await writeRun(root, next);
+    await recordSyncRun(root, next, history);
+    try {
+        const originalProjectText = await readFile(join(root, '.doxloop', 'project.json'), 'utf8');
+        const editScope = authoring.editRequest
+            ? await resolveEditScope(root, project, authoring.editRequest.paths, authoring.editRequest.allowRelated)
+            : undefined;
+        const editBaseline = editScope ? await collectFiles(root) : undefined;
+        await rewriteWorkspaceSources(workspace, root, {
+            ...project,
+            sources: authoring.authoringSources ?? project.sources,
+        });
+        const editPages = authoring.editRequest
+            ? (await listDocumentationPages(root)).filter((page) => authoring.editRequest.paths.includes(page.path))
+            : [];
+        const originalRequest = authoring.editRequest ? editPrompt({
+            pages: authoring.editRequest.paths.map((path) => ({ path, title: editPages.find((page) => page.path === path)?.title ?? path })),
+            instruction: authoring.editRequest.instruction,
+            allowRelated: authoring.editRequest.allowRelated,
+            followUps: authoring.editRequest.followUps,
+        }) : authoring.request;
+        const continuation = await continuationBrief(workspace, plan, run, screenshotIntent, originalRequest, sourcesChanged);
+        let failureDetail;
+        let usage;
+        const exitCode = await (options.author ?? runAuthor)({
+            onFailure: (detail) => { failureDetail = detail; },
+            onUsage: (recorded) => { usage = recorded; },
+            root: workspace,
+            captureAuthRoot: root,
+            mode: authoring.mode,
+            nonInteractive: true,
+            recordHistory: false,
+            ...(plan && !authoring.editRequest ? { planBatches: true } : {}),
+            ...(authoring.editRequest ? { recordOperationalState: false } : {}),
+            request: continuation,
+            screenshots: screenshotIntent,
+            ...(authoring.changeSummary ? { changeSummary: authoring.changeSummary } : {}),
+            ...(authoring.agent ? { agent: authoring.agent } : {}),
+            ...(authoring.model ? { model: authoring.model } : {}),
+            ...(authoring.reasoning ? { reasoning: authoring.reasoning } : {}),
+            ...(authoring.effort ? { effort: authoring.effort } : {}),
+            ...(authoring.timeoutMinutes ? { timeoutMinutes: authoring.timeoutMinutes } : {}),
+            ...(project.sync.budget?.maxUsd ? { maxBudgetUsd: project.sync.budget.maxUsd } : {}),
+            progressLabel: 'Continuing the interrupted authoring run',
+            ...(authoring.editRequest ? {
+                maxTurns: Math.max(EDIT_MIN_MAX_TURNS, 40 + EDIT_TURNS_PER_PAGE * authoring.editRequest.paths.length),
+                timeoutMinutes: authoring.timeoutMinutes ?? project.sync.budget?.maxMinutes ?? 15,
+                tolerateValidationErrors: true,
+                plannedPages: authoring.editRequest.paths.length,
+            } : {}),
+        });
+        if (usage)
+            next = { ...next, usage: mergeAgentUsage(run.usage, usage) ?? usage };
+        if (exitCode !== 0) {
+            throw new DoxloopError(agentExitMessage(exitCode, failureDetail));
+        }
+        if (editScope && editBaseline) {
+            await restoreWorkspaceSources(workspace, project, originalProjectText);
+            await assertRevisionStayedInScope(workspace, editBaseline, editScope, true);
+        }
+        const context = {
+            root,
+            project,
+            drift: await computeDrift(root, project),
+            sourceChanges: await collectSourceChanges(root, project.sources),
+            trigger: authoring.trigger,
+            ...(authoring.editRequest ? { editRequest: authoring.editRequest } : {}),
+            ...(plan ? { plan } : {}),
+            ...(authoring.authoringSources ? { authoringSources: authoring.authoringSources } : {}),
+            ...(authoring.nextSyncState ? { nextSyncState: authoring.nextSyncState } : {}),
+            authoring: {
+                mode: authoring.mode,
+                ...(authoring.request ? { request: authoring.request } : {}),
+                ...(authoring.agent ? { agent: authoring.agent } : {}),
+                ...(authoring.model ? { model: authoring.model } : {}),
+                ...(authoring.reasoning ? { reasoning: authoring.reasoning } : {}),
+                ...(authoring.effort ? { effort: authoring.effort } : {}),
+                screenshots: screenshotIntent,
+            },
+        };
+        const finalized = await finalizeProposalWorkspace({
+            context,
+            directory,
+            workspace,
+            originalProjectText,
+            screenshotIntent,
+            label: 'resumed',
+        });
+        next = {
+            ...next,
+            status: 'awaiting-review',
+            completedAt: new Date().toISOString(),
+            summary: proposalSummary(finalized.changes),
+            changes: finalized.changes,
+            validation: finalized.validation,
+            screenshots: finalized.screenshots,
+            ...withAdvisories(next, finalized.advisories),
+            undo: { status: 'unavailable', reason: 'Undo becomes available after the complete proposal is applied.' },
+        };
+        await writeRun(root, next);
+        await recordSyncRun(root, next, history);
+        return next;
+    }
+    catch (error) {
+        next = await failedRun(next, error, {
+            workspace,
+            screenshotIntent,
+            expectedScreenshots,
+            recovery: { resumable: true, ignorable: true },
+        });
+        await writeRun(root, next);
+        await recordSyncRun(root, next, history);
+        return next;
+    }
+}
+/**
+ * Tell a continuing agent what the workspace already holds and what is left.
+ * Verified captures are named so they are kept, unfinished guides are named
+ * with their start path, and the previous failure is quoted so the agent works
+ * on the actual problem instead of rediscovering it.
+ */
+async function continuationBrief(workspace, plan, run, intent, originalRequest, sourcesChanged = false) {
+    const progress = await describeScreenshotManifestProgress(workspace, plan);
+    let validationText = '';
+    let pageProgress = '';
+    try {
+        const validation = await validateProject(workspace);
+        // Warnings travel with the errors: the resumed run that fixed its
+        // thin-page warnings produced the documentation the reviewer preferred,
+        // and a writer that could not run validation in its sandbox has never
+        // seen them.
+        if (validation.errors > 0 || validation.warnings > 0)
+            validationText = formatValidation(validation);
+        const files = await listDocumentationPages(workspace);
+        const invalid = new Set(validation.issues.filter((issue) => issue.severity === 'error').map((issue) => issue.file));
+        pageProgress = `Existing pages (${files.length}; passing structural validation is not a factual verification):\n${files.map((page) => `${page.path}: ${invalid.has(page.path) ? 'needs validation fixes' : 'present; preserve unless incomplete'}`).join('\n')}`;
+    }
+    catch {
+        // Validation problems are reported again after the agent finishes.
+    }
+    const sections = [
+        'This run continues an earlier authoring run in this same workspace that stopped before Doxloop could accept its output. The workspace already holds the pages, navigation, evidence map, and application screenshots that run produced. Keep that work: do not rewrite pages that are already complete, do not recapture, rename, or delete screenshots that .doxloop/screenshot-manifest.json records as verified and whose files exist, and do not rebuild that manifest from scratch. Finish only what is listed below as unfinished or wrong, bring any page you touch to full depth, then run validation and finish.',
+        pageProgress,
+        run.error ? `Why the previous run stopped:\n${run.error}` : '',
+        sourcesChanged
+            ? 'The configured sources changed after the previous run stopped. Re-check the claims of every page you touch against the current source evidence, and update .doxloop/evidence-map.json for those pages; leave pages you do not touch as they are.'
+            : '',
+        progress.lines.length > 0
+            ? `Screenshot manifest progress (${progress.verified} verified, ${progress.unfinished} unfinished):\n${progress.lines.join('\n')}`
+            : '',
+        validationText ? `Documentation validation currently reports the following. Fix every error first; then resolve the thin-page, thin-procedure, and other warnings on pages this run wrote, bringing each such page to the depth contract. Leave pages with no finding as they are:\n${validationText}` : '',
+        intent === 'enabled'
+            ? 'Screenshots are required: every unfinished guide above needs at least one verified, embedded capture, or a specific text-only reason on each step whose state genuinely cannot be reached.'
+            : '',
+        originalRequest?.trim() ? `The original instructions for this run were:\n${originalRequest.trim()}` : '',
+    ];
+    return sections.filter(Boolean).join('\n\n');
+}
+/** The workspace's own plan copy, used when re-validating preserved agent output. */
+async function recoveryPlan(root, directory, planId) {
+    if (!planId)
+        return undefined;
+    // Trust the snapshot saved outside the agent workspace, never an agent-edited plan.
+    const trusted = join(directory, 'approved-plan.json');
+    if (await pathExists(trusted))
+        return readJson(trusted);
+    const path = join(root, '.doxloop', 'documentation-plan.json');
+    if (await pathExists(path)) {
+        const plan = await readJson(path);
+        if (plan.id === planId && plan.approvedHash)
+            return plan;
+    }
+    throw new DoxloopError('The approved plan snapshot is unavailable. Review and approve the plan again before retrying this run.');
+}
+export async function listSyncRuns(root) {
+    const directory = join(root, SYNC_RUNS_DIRECTORY);
+    if (!(await pathExists(directory)))
+        return [];
+    const entries = await readdir(directory, { withFileTypes: true });
+    const runs = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        try {
+            runs.push(await readSyncRun(root, entry.name));
+        }
+        catch {
+            // An interrupted directory without a valid manifest is not a review run.
+        }
+    }
+    return runs.sort((left, right) => right.createdAt.localeCompare(left.createdAt));
+}
+export async function readSyncRun(root, id) {
+    assertRunId(id);
+    const raw = await readJson(join(runDirectory(root, id), RUN_FILE));
+    const { run, migrated } = normalizeSyncRun(raw, id);
+    if (!run || run.id !== id || !Array.isArray(run.changes)) {
+        throw new DoxloopError(`Sync run ${id} is invalid.`);
+    }
+    if (migrated)
+        await writeRun(root, run);
+    const changes = run.changes.filter((change) => !isExcluded(change.path));
+    const excludedRuntimeConflict = run.status === 'conflicted' && Boolean(run.error && EXCLUDED_PREFIXES.some((prefix) => run.error.startsWith(`${prefix} `) || run.error.startsWith(`${prefix}/`)));
+    if (changes.length === run.changes.length && !excludedRuntimeConflict)
+        return run;
+    if (excludedRuntimeConflict) {
+        const { error: _excludedError, ...cleanRun } = run;
+        return {
+            ...cleanRun,
+            status: 'awaiting-review',
+            changes,
+            summary: proposalSummary(changes),
+        };
+    }
+    return {
+        ...run,
+        changes,
+        summary: proposalSummary(changes),
+    };
+}
+export async function rejectSyncRun(root, id) {
+    return rejectSyncChanges(root, id, undefined, 'Do not repeat this proposal without new evidence or explicit reviewer direction.');
+}
+export async function rejectSyncChanges(root, id, selections, reason = '') {
+    return withProjectLock(root, 'write', async () => {
+        const run = await readSyncRun(root, id);
+        if (run.archivedAt || !['awaiting-review', 'partially-applied', 'conflicted'].includes(run.status))
+            throw new DoxloopError('This proposal is not open for review.');
+        const requested = selections ?? run.changes.map((change) => ({ changeId: change.id }));
+        const now = new Date().toISOString();
+        const changes = run.changes.map((change) => ({ ...change, hunks: change.hunks.map((hunk) => ({ ...hunk })) }));
+        const paths = [];
+        for (const selection of requested) {
+            const change = changes.find((item) => item.id === selection.changeId);
+            if (!change)
+                throw new DoxloopError(`Unknown change ${selection.changeId}.`);
+            const ids = selection.hunkIds?.length ? selection.hunkIds : change.hunks.filter((hunk) => !hunk.acceptedAt && !hunk.rejectedAt).map((hunk) => hunk.id);
+            for (const id of ids) {
+                const hunk = change.hunks.find((item) => item.id === id);
+                if (!hunk)
+                    throw new DoxloopError(`Unknown change hunk ${id}.`);
+                if (hunk.acceptedAt)
+                    throw new DoxloopError('An accepted change cannot be rejected. Use Undo to revert accepted work.');
+                hunk.rejectedAt = now;
+                if (reason.trim())
+                    hunk.rejectionReason = reason.trim().slice(0, 2000);
+            }
+            if (ids.length)
+                paths.push(change.path);
+        }
+        if (!paths.length)
+            throw new DoxloopError('Select at least one undecided change.');
+        const complete = changes.every((change) => change.hunks.every((hunk) => hunk.acceptedAt || hunk.rejectedAt));
+        const accepted = changes.some((change) => change.hunks.some((hunk) => hunk.acceptedAt));
+        if (complete && accepted)
+            await snapshotChangeSet(root, join(runDirectory(root, id), APPLIED), changes.filter((change) => change.hunks.some((hunk) => hunk.acceptedAt)));
+        const next = { ...run, changes, status: complete ? accepted ? 'applied' : 'rejected' : accepted ? 'partially-applied' : 'awaiting-review', ...(complete && accepted ? { appliedAt: now, undo: { status: 'available' } } : {}), ...(complete && !accepted ? { rejectedAt: now } : {}) };
+        await writeRun(root, next);
+        await recordSyncRun(root, next);
+        await recordReviewPreference(root, { kind: 'rejection', paths, instruction: reason.trim() || 'The reviewer rejected these changes. Preserve the current wording unless new evidence or explicit direction calls for a change.' }).catch(() => undefined);
+        return next;
+    });
+}
+export async function reviseSyncRun(root, id, input) {
+    const run = await readSyncRun(root, id);
+    if (run.archivedAt)
+        throw new DoxloopError(`Proposal ${id} is archived and cannot be revised.`);
+    if (!['awaiting-review', 'partially-applied', 'conflicted', 'stale'].includes(run.status)) {
+        throw new DoxloopError(`Proposal ${id} cannot be revised from status ${run.status}.`);
+    }
+    const instruction = input.instruction.trim();
+    if (!instruction)
+        throw new DoxloopError('Describe how the selected documentation should change.');
+    const changeIds = [...new Set(input.changeIds)];
+    if (changeIds.length === 0)
+        throw new DoxloopError('Select at least one file or change to revise.');
+    const selected = changeIds.map((changeId) => {
+        const change = run.changes.find((item) => item.id === changeId);
+        if (!change)
+            throw new DoxloopError(`Unknown proposal change ${changeId}.`);
+        return change;
+    });
+    const hunkIds = [...new Set(input.hunkIds ?? [])];
+    for (const hunkId of hunkIds) {
+        if (!selected.some((change) => change.hunks.some((hunk) => hunk.id === hunkId))) {
+            throw new DoxloopError(`Unknown selected change hunk ${hunkId}.`);
+        }
+    }
+    const project = await loadProject(root);
+    const [drift, sourceChanges] = await Promise.all([
+        computeDrift(root, project),
+        collectSourceChanges(root, project.sources),
+    ]);
+    const scope = selected.map((change) => `- ${change.path}`).join('\n');
+    const hunkScope = hunkIds.length > 0
+        ? `\nSelected change hunks: ${hunkIds.join(', ')}. Keep unrelated parts of those files unchanged.`
+        : '';
+    const plan = await optionalApprovedPlan(root);
+    if (!run.editRequest) {
+        await recordReviewPreference(root, { kind: 'revision', paths: selected.map((change) => change.path), instruction }).catch(() => undefined);
+    }
+    const editRequest = run.editRequest ? {
+        ...run.editRequest,
+        followUps: [...run.editRequest.followUps, {
+                id: `follow-up-${randomBytes(3).toString('hex')}`,
+                createdAt: new Date().toISOString(),
+                instruction,
+            }],
+    } : undefined;
+    return createSyncRun({
+        root,
+        project,
+        drift,
+        sourceChanges,
+        revisionOf: run.id,
+        revisionRequest: { instruction, changeIds, hunkIds },
+        trigger: input.trigger ?? (run.editRequest ? 'edit' : run.trigger),
+        ...(editRequest ? { editRequest } : {}),
+        ...(plan ? { plan } : {}),
+        ...(input.author ? { author: input.author } : {}),
+        authoring: {
+            mode: run.authoringMode ?? 'update',
+            ...(editRequest ? { historyRequest: instruction } : {
+                request: `Revise only the selected proposal scope below. Preserve every other proposed file exactly as it is.\n\nSelected files:\n${scope}${hunkScope}\n\nReviewer instruction:\n${instruction}`,
+            }),
+            // The revision runs on the model and reasoning the proposal was written
+            // with. Passing only the agent let Codex fall back to its own default
+            // model, which a real run's installed CLI could not use at all.
+            ...revisionAgent(project, plan?.id === run.planId ? plan : undefined),
+            screenshots: 'disabled',
+        },
+    });
+}
+function revisionAgent(project, plan) {
+    const execution = plan?.execution;
+    const agent = execution?.agent ?? project.defaultAgent;
+    if (!agent)
+        return {};
+    if (execution && execution.agent === agent) {
+        return {
+            agent,
+            ...(execution.model ? { model: execution.model } : {}),
+            ...(execution.reasoning ? { reasoning: execution.reasoning } : {}),
+            ...(execution.effort ? { effort: execution.effort } : {}),
+        };
+    }
+    const model = projectDefaultModel(project, agent);
+    return { agent, ...(model ? { model } : {}) };
+}
+export async function readSyncRunChangeContent(root, id, changeId) {
+    const run = await readSyncRun(root, id);
+    const change = run.changes.find((item) => item.id === changeId);
+    if (!change)
+        throw new DoxloopError(`Unknown proposal change ${changeId}.`);
+    if (change.binary || change.kind === 'deleted')
+        throw new DoxloopError('Only proposed text files can be edited inline.');
+    const content = await readFile(assertInside(runWorkspace(root, id), resolve(runWorkspace(root, id), change.path)), 'utf8');
+    const edit = [...run.humanEdits].reverse().find((item) => item.path === change.path);
+    return { content, path: change.path, fingerprint: hash(Buffer.from(content)), evidenceDisposition: edit?.evidenceDisposition ?? 'preserved' };
+}
+export async function editSyncRunChange(root, id, changeId, content, evidenceDisposition, fingerprint) {
+    return withProjectLock(root, 'write', () => editSyncRunChangeLocked(root, id, changeId, content, evidenceDisposition, fingerprint));
+}
+async function editSyncRunChangeLocked(root, id, changeId, content, evidenceDisposition, fingerprint) {
+    let run = await readSyncRun(root, id);
+    if (run.archivedAt)
+        throw new DoxloopError(`Proposal ${id} is archived and cannot be edited.`);
+    if (!['awaiting-review', 'partially-applied'].includes(run.status))
+        throw new DoxloopError('Inline edits require an open proposal.');
+    run = await refreshProposalSourceSnapshot(root, run);
+    const change = run.changes.find((item) => item.id === changeId);
+    if (!change)
+        throw new DoxloopError(`Unknown proposal change ${changeId}.`);
+    if (change.hunks.some((hunk) => hunk.acceptedAt || hunk.rejectedAt))
+        throw new DoxloopError('This file already has review decisions. Edit an undecided file or request a new revision to preserve those decisions.');
+    if (change.binary || change.kind === 'deleted' || change.category !== 'page') {
+        throw new DoxloopError('Inline editing is available only for proposed text pages.');
+    }
+    if (Buffer.byteLength(content, 'utf8') > 1_000_000)
+        throw new DoxloopError('Inline page edits are limited to 1 MB.');
+    const workspace = runWorkspace(root, id);
+    const path = assertInside(workspace, resolve(workspace, change.path));
+    const previous = await readFile(path);
+    if (fingerprint && hash(previous) !== fingerprint)
+        throw new DoxloopError('The proposal changed while you were editing. Your draft is kept; reload and compare before saving.');
+    const evidencePath = join(workspace, '.doxloop', 'evidence-map.json');
+    const previousEvidence = (await pathExists(evidencePath)) ? await readFile(evidencePath) : undefined;
+    try {
+        await writeAtomic(path, Buffer.from(content));
+        if (evidenceDisposition === 'needs-review' && previousEvidence) {
+            const evidence = JSON.parse(previousEvidence.toString('utf8'));
+            const pageEvidence = evidence.pages[change.path];
+            if (pageEvidence) {
+                evidence.pages[change.path] = { ...pageEvidence, confidence: 'needs-human' };
+                await writeAtomic(evidencePath, Buffer.from(`${JSON.stringify(evidence, null, 2)}\n`));
+            }
+        }
+        const validation = await validateProject(workspace);
+        if (validation.errors > 0) {
+            throw new DoxloopError(`The inline edit did not pass validation:\n${formatValidation(validation)}`);
+        }
+        const project = await loadProject(root);
+        const sourceChanges = await collectSourceChanges(root, project.sources);
+        const plan = await optionalApprovedPlan(root);
+        const collected = await collectProposalChanges(root, workspace, runDirectory(root, id), project);
+        for (const note of await repairProposalSourceScopes(workspace, collected, project))
+            process.stdout.write(`${note}\n`);
+        let changes = await enrichProposalRationales(root, workspace, collected, {
+            root,
+            project,
+            drift: await computeDrift(root, project),
+            sourceChanges,
+            ...(plan ? { plan } : {}),
+            authoring: {
+                ...(change.rationale.request ? { request: change.rationale.request } : {}),
+                screenshots: 'disabled',
+            },
+        }, validation);
+        changes = changes.map((item) => {
+            const old = run.changes.find((candidate) => candidate.path === item.path);
+            if (item.path !== change.path)
+                return old ?? item;
+            const evidencePreserved = evidenceDisposition === 'preserved';
+            return {
+                ...item,
+                rationale: {
+                    ...(old?.rationale ?? item.rationale),
+                    reason: `A reviewer edited “${item.title}” directly before acceptance.`,
+                    confidence: evidencePreserved ? (old?.rationale.confidence ?? item.rationale.confidence) : 'needs-human',
+                    assumptions: evidencePreserved
+                        ? [...new Set([...(old?.rationale.assumptions ?? []), 'A reviewer changed the prose while preserving the recorded evidence associations.'])]
+                        : ['The reviewer marked the evidence associations for re-checking after this edit.'],
+                    authorship: 'human',
+                },
+            };
+        });
+        const next = {
+            ...run,
+            summary: proposalSummary(changes),
+            changes,
+            humanEdits: [...run.humanEdits, { changeId, path: change.path, editedAt: new Date().toISOString(), evidenceDisposition }],
+            validation: { pages: validation.pages.length, errors: validation.errors, warnings: validation.warnings },
+        };
+        await writeRun(root, next);
+        await recordSyncRun(root, next);
+        await recordReviewPreference(root, { kind: 'inline-edit', paths: [change.path], instruction: evidenceDisposition === 'preserved' ? 'Preserve this reviewer-authored wording while its supporting evidence remains valid.' : 'A reviewer changed this page and requires its evidence to be checked again.' }).catch(() => undefined);
+        return next;
+    }
+    catch (error) {
+        await writeAtomic(path, previous);
+        await writeAtomic(evidencePath, previousEvidence);
+        throw error;
+    }
+}
+export async function undoSyncRun(root, id) {
+    return withProjectLock(root, 'write', () => undoSyncRunLocked(root, id));
+}
+async function undoSyncRunLocked(root, id) {
+    const run = await readSyncRun(root, id);
+    if (run.status !== 'applied' || run.undo?.status === 'undone') {
+        throw new DoxloopError(`Proposal ${id} does not have an applied change set available to undo.`);
+    }
+    const originals = new Map();
+    const operationalPath = join(root, '.doxloop', 'sync-state.json');
+    const operationalCurrent = (await pathExists(operationalPath)) ? await readFile(operationalPath) : undefined;
+    try {
+        for (const change of run.changes.filter((item) => item.hunks.some((hunk) => hunk.acceptedAt))) {
+            const before = await proposalAcceptanceBefore(root, id, change.path);
+            const actualPath = await safePath(root, change.path);
+            const current = (await pathExists(actualPath)) ? await readFile(actualPath) : undefined;
+            const appliedSnapshot = await readChangeSnapshot(join(runDirectory(root, id), APPLIED), change.path);
+            const expected = appliedSnapshot.found
+                ? appliedSnapshot.content
+                : await materializeChange(await proposalBefore(root, id, change.path), change, acceptedIds(change), runWorkspace(root, id));
+            if (!buffersEqual(current, expected)) {
+                throw new DoxloopError(`${change.path} changed after this proposal was applied. Undo stopped without overwriting the newer edit.`);
+            }
+            originals.set(change.path, current);
+            await writeAtomic(actualPath, before);
+        }
+        if (run.changes.every((item) => item.hunks.every((hunk) => hunk.acceptedAt)))
+            await restoreOperationalBefore(root, id);
+        const validation = await validateProject(root);
+        if (validation.errors > 0)
+            throw new DoxloopError(`Undo would leave invalid documentation:\n${formatValidation(validation)}`);
+        const undoneAt = new Date().toISOString();
+        const next = { ...run, status: 'undone', undo: { status: 'undone', undoneAt } };
+        await writeRun(root, next);
+        await recordSyncRun(root, next);
+        await syncPageRegistry(root, undefined, next.id);
+        return next;
+    }
+    catch (error) {
+        await rollbackAppliedFiles(root, originals, operationalPath, operationalCurrent);
+        throw error;
+    }
+}
+export async function archiveSyncRun(root, id) {
+    const run = await readSyncRun(root, id);
+    if (run.status === 'generating')
+        throw new DoxloopError('A generating proposal cannot be archived.');
+    const next = { ...run, archivedAt: new Date().toISOString() };
+    await writeRun(root, next);
+    return next;
+}
+export async function pruneSyncRuns(root, now = new Date()) {
+    const removable = new Set(['rejected', 'failed', 'superseded', 'undone']);
+    const removed = [];
+    for (const run of await listSyncRuns(root)) {
+        const expired = run.retentionUntil && new Date(run.retentionUntil) <= now;
+        if (!(run.archivedAt || (expired && removable.has(run.status))))
+            continue;
+        await rm(runDirectory(root, run.id), { recursive: true, force: true });
+        removed.push(run.id);
+    }
+    return removed;
+}
+export async function acceptSyncChanges(root, id, selections, options = {}) {
+    return withProjectLock(root, 'write', () => acceptSyncChangesLocked(root, id, selections, options));
+}
+/** Project-relative paths of the proposal's changes that still have hunks neither accepted nor rejected. */
+export function pendingProposalPaths(changes) {
+    return new Set(changes
+        .filter((change) => change.hunks.some((hunk) => !hunk.acceptedAt && !hunk.rejectedAt))
+        .map((change) => change.path.replaceAll('\\', '/')));
+}
+const PAGE_FILE = /\.(?:mdx?|rst|ipynb|txt)$/i;
+/**
+ * Whether a validation error is one the not-yet-accepted part of the same
+ * proposal takes care of: an error on a file the proposal still replaces,
+ * or a page missing from a navigation the proposal still updates. Such an
+ * error is real for the workspace as it stands and gone once the reviewer
+ * accepts the rest, so it must not block accepting one file at a time.
+ */
+export function resolvedByPendingChanges(issue, pending) {
+    if (pending.size === 0)
+        return false;
+    const file = issue.file?.replaceAll('\\', '/');
+    if (file && pending.has(file))
+        return true;
+    if (issue.code === 'unnavigated-page') {
+        for (const path of pending) {
+            if (!PAGE_FILE.test(path) && !path.startsWith('.doxloop/') && !path.startsWith('assets/'))
+                return true;
+        }
+    }
+    if (issue.code === 'broken-link') {
+        // "Local link target does not exist: /administration/api-keys" — the
+        // target page is one the proposal still adds.
+        const target = (issue.message ?? '').match(/:\s*(\S+)\s*$/)?.[1]?.replace(/^\/+/, '').replace(/[#?].*$/, '').replace(/\/+$/, '');
+        if (target) {
+            const stem = target.replace(PAGE_FILE, '');
+            for (const path of pending) {
+                const pendingStem = path.replace(PAGE_FILE, '');
+                if (pendingStem === stem || pendingStem === `${stem}/index` || pendingStem.endsWith(`/${stem}`))
+                    return true;
+            }
+        }
+    }
+    return false;
+}
+/** Apply selected hunks after proving the real files still match this proposal. */
+async function acceptSyncChangesLocked(root, id, selections, options = {}) {
+    let run = await readSyncRun(root, id);
+    if (run.archivedAt)
+        throw new DoxloopError(`Proposal ${id} is archived and cannot be applied.`);
+    if (!['awaiting-review', 'partially-applied', 'conflicted'].includes(run.status)) {
+        throw new DoxloopError(`Sync run ${id} cannot be applied from status ${run.status}.`);
+    }
+    run = await refreshProposalSourceSnapshot(root, run);
+    const requested = new Map();
+    for (const selection of selections) {
+        const change = run.changes.find((candidate) => candidate.id === selection.changeId);
+        if (!change)
+            throw new DoxloopError(`Unknown change ${selection.changeId}.`);
+        const ids = new Set(selection.hunkIds && selection.hunkIds.length > 0
+            ? selection.hunkIds
+            : change.hunks.filter((hunk) => !hunk.acceptedAt && !hunk.rejectedAt).map((hunk) => hunk.id));
+        for (const hunkId of ids) {
+            if (change.hunks.some((hunk) => hunk.id === hunkId && hunk.rejectedAt))
+                throw new DoxloopError('A rejected change cannot be accepted. Request a new revision instead.');
+            if (!change.hunks.some((hunk) => hunk.id === hunkId)) {
+                throw new DoxloopError(`Unknown change hunk ${hunkId}.`);
+            }
+        }
+        if (change.changedDuringRun && !options.confirmChangedDuringRun) {
+            throw new DoxloopError(`${change.path} was edited in the project while the agent ran. Confirm that the proposal should replace that edit before applying it; no file was overwritten.`);
+        }
+        requested.set(change.id, ids);
+    }
+    if (requested.size === 0)
+        throw new DoxloopError('Select at least one documentation change.');
+    if (!run.changes.some((change) => change.hunks.some((hunk) => hunk.acceptedAt))) {
+        await snapshotOperationalBefore(root, runDirectory(root, id), true);
+        await snapshotChangeSet(root, join(runDirectory(root, id), ACCEPTANCE_BEFORE), run.changes);
+    }
+    const originals = new Map();
+    const operationalPath = join(root, '.doxloop', 'sync-state.json');
+    const operationalCurrent = await pathExists(operationalPath) ? await readFile(operationalPath) : undefined;
+    const now = new Date().toISOString();
+    let nextChanges = run.changes.map((change) => ({
+        ...change,
+        hunks: change.hunks.map((hunk) => ({ ...hunk })),
+    }));
+    try {
+        for (const change of nextChanges) {
+            const ids = requested.get(change.id);
+            if (!ids || ids.size === 0)
+                continue;
+            const actualPath = await safePath(root, change.path);
+            const before = await proposalBefore(root, run.id, change.path);
+            const current = (await pathExists(actualPath)) ? await readFile(actualPath) : undefined;
+            const expected = await materializeChange(before, change, acceptedIds(change), runWorkspace(root, run.id));
+            const accepted = new Set([...acceptedIds(change), ...ids]);
+            let result = await materializeChange(before, change, accepted, runWorkspace(root, run.id));
+            if (!buffersEqual(current, expected)) {
+                const merged = change.path === '.doxloop/evidence-map.json' && expected && current && result
+                    ? mergeConcurrentJson(expected, current, result)
+                    : undefined;
+                if (!merged) {
+                    throw new DoxloopError(`${change.path} changed after this proposal was generated. Regenerate or review the conflict; no file was overwritten.`);
+                }
+                result = merged;
+            }
+            originals.set(change.path, current);
+            await writeAtomic(actualPath, result);
+            change.hunks = change.hunks.map((hunk) => ids.has(hunk.id) && !hunk.rejectedAt ? { ...hunk, acceptedAt: now } : hunk);
+        }
+        const validation = await validateProject(root);
+        if (validation.errors > 0) {
+            // Only errors block; listing every depth warning alongside them hid
+            // the one line the reviewer had to act on. Errors that the rest of
+            // this proposal resolves (a starter page it replaces, a navigation
+            // entry its docs.json adds) do not block either: accepting one page
+            // of a new site before its navigation used to fail on exactly those.
+            const pending = pendingProposalPaths(nextChanges);
+            const blocking = {
+                ...validation,
+                issues: validation.issues.filter((issue) => issue.severity === 'error' && !resolvedByPendingChanges(issue, pending)),
+            };
+            if (blocking.issues.length > 0) {
+                throw new DoxloopError(`The selected changes were not applied because they would leave invalid documentation:\n${formatValidation({ ...blocking, errors: blocking.issues.length })}`);
+            }
+        }
+        const complete = nextChanges.every((change) => change.hunks.every((hunk) => hunk.acceptedAt !== undefined || hunk.rejectedAt !== undefined));
+        const allAccepted = nextChanges.every((change) => change.hunks.every((hunk) => hunk.acceptedAt));
+        if (complete && allAccepted && !run.editRequest)
+            await applyStagedSyncState(root, id);
+        if (complete)
+            await snapshotChangeSet(root, join(runDirectory(root, id), APPLIED), nextChanges);
+        const { error: _previousError, ...cleanRun } = run;
+        const next = {
+            ...cleanRun,
+            status: complete ? 'applied' : 'partially-applied',
+            ...(complete ? { appliedAt: now } : {}),
+            undo: complete
+                ? { status: 'available' }
+                : { status: 'unavailable', reason: 'Undo becomes available after the complete proposal is applied.' },
+            changes: nextChanges,
+            validation: {
+                pages: validation.pages.length,
+                errors: validation.errors,
+                warnings: validation.warnings,
+            },
+        };
+        await writeRun(root, next);
+        await recordSyncRun(root, next);
+        // Accepted hunks are now real files. Refresh the registry so page history
+        // and the external-edit check both start from what is actually on disk.
+        await syncPageRegistry(root, undefined, next.id);
+        if (complete) {
+            if (allAccepted && !run.editRequest)
+                await recordSourceSyncs(root, await readOptionalSyncState(root), next.id);
+            await recordAppliedAuthoringReceipt(root, next).catch(() => undefined);
+        }
+        return next;
+    }
+    catch (error) {
+        await rollbackAppliedFiles(root, originals, operationalPath, operationalCurrent);
+        const conflicted = {
+            ...run,
+            status: error instanceof DoxloopError && error.message.includes('changed after')
+                ? 'conflicted'
+                : run.status,
+            error: error instanceof Error ? error.message : String(error),
+        };
+        await writeRun(root, conflicted);
+        await recordSyncRun(root, conflicted);
+        throw error;
+    }
+}
+async function rollbackAppliedFiles(root, originals, operationalPath, operationalCurrent) {
+    const results = await Promise.allSettled([
+        ...[...originals].map(async ([path, content]) => writeAtomic(await safePath(root, path), content)),
+        writeAtomic(operationalPath, operationalCurrent),
+    ]);
+    const errors = results.filter((result) => result.status === 'rejected');
+    if (errors.length)
+        throw new AggregateError(errors.map((result) => result.reason), 'Rollback needs recovery. Original page snapshots are preserved in the proposal run directory.');
+}
+async function readOptionalSyncState(root) {
+    const path = join(root, '.doxloop', 'sync-state.json');
+    if (!(await pathExists(path)))
+        return undefined;
+    try {
+        return await readJson(path);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function recordAppliedAuthoringReceipt(root, run) {
+    if (!run.authoringMode || !run.validation || run.editRequest)
+        return;
+    await writeAtomic(join(root, '.doxloop', 'last-run.json'), Buffer.from(`${JSON.stringify({
+        schemaVersion: 1,
+        mode: run.authoringMode,
+        completedAt: run.appliedAt ?? new Date().toISOString(),
+        proposalId: run.id,
+        ...(run.planId ? { planId: run.planId } : {}),
+        validation: run.validation,
+    }, null, 2)}\n`));
+}
+const JSON_MISSING = Symbol('json-missing');
+function mergeConcurrentJson(base, current, proposed) {
+    try {
+        const merged = mergeJsonValue(JSON.parse(base.toString('utf8')), JSON.parse(current.toString('utf8')), JSON.parse(proposed.toString('utf8')));
+        if (merged === JSON_MISSING)
+            return undefined;
+        return Buffer.from(`${JSON.stringify(merged, null, 2)}\n`);
+    }
+    catch {
+        return undefined;
+    }
+}
+function mergeJsonValue(base, current, proposed) {
+    if (isDeepStrictEqual(current, base))
+        return proposed;
+    if (isDeepStrictEqual(proposed, base) || isDeepStrictEqual(current, proposed))
+        return current;
+    if (isJsonRecord(base) && isJsonRecord(current) && isJsonRecord(proposed)) {
+        const result = {};
+        const keys = new Set([...Object.keys(base), ...Object.keys(current), ...Object.keys(proposed)]);
+        for (const key of keys) {
+            const merged = mergeJsonValue(Object.hasOwn(base, key) ? base[key] : JSON_MISSING, Object.hasOwn(current, key) ? current[key] : JSON_MISSING, Object.hasOwn(proposed, key) ? proposed[key] : JSON_MISSING);
+            if (merged !== JSON_MISSING)
+                result[key] = merged;
+        }
+        return result;
+    }
+    // Both sides changed the same scalar or array. Preserve the newer accepted value.
+    return current;
+}
+function isJsonRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+export function formatSyncRunHistory(runs) {
+    if (runs.length === 0)
+        return 'No documentation sync runs yet.';
+    const lines = ['Documentation sync runs', ''];
+    for (const run of runs) {
+        const counts = changeCounts(run.changes);
+        lines.push(`  ${statusMark(run.status)} ${run.id}  ${run.status.padEnd(18)} ${counts}  ${run.createdAt}`, `      ${run.summary}`);
+    }
+    lines.push('', 'Review visually with: doxloop sync review --open');
+    return lines.join('\n');
+}
+export function pendingRunCount(runs) {
+    return runs.filter((run) => ['awaiting-review', 'partially-applied', 'conflicted'].includes(run.status)).length;
+}
+export function runWorkspace(root, id) {
+    assertRunId(id);
+    return join(runDirectory(root, id), WORKSPACE);
+}
+export function runBeforeRoot(root, id) {
+    assertRunId(id);
+    return join(runDirectory(root, id), BEFORE);
+}
+async function createWorkspace(root, runRoot, project, authoringSources) {
+    const temporary = await mkdtemp(join(tmpdir(), 'doxloop-sync-review-'));
+    const staged = join(temporary, WORKSPACE);
+    try {
+        await cp(root, staged, {
+            recursive: true,
+            preserveTimestamps: true,
+            filter: (source) => {
+                const rel = portable(relative(root, source));
+                return rel === '' || !isExcluded(rel);
+            },
+        });
+        // What the agent starts from. Review compares its output with this, not
+        // with whatever the project holds by the time the run finishes, so an
+        // edit made in the project during the run is never proposed as a revert.
+        await writeWorkspaceBaseline(runRoot, staged);
+        await rewriteWorkspaceSources(staged, root, {
+            ...project,
+            sources: authoringSources ?? project.sources,
+        });
+        await initializeWorkspaceGit(staged);
+        const target = join(runRoot, WORKSPACE);
+        await rename(staged, target);
+        return target;
+    }
+    finally {
+        await rm(temporary, { recursive: true, force: true });
+    }
+}
+async function seedRevisionWorkspace(root, revisionOf, workspace) {
+    const source = runWorkspace(root, revisionOf);
+    if (!(await pathExists(source)))
+        throw new DoxloopError(`Proposal ${revisionOf} no longer has an isolated workspace to revise.`);
+    await cp(source, workspace, {
+        recursive: true,
+        force: true,
+        preserveTimestamps: true,
+        filter: (path) => portable(relative(source, path)) !== '.git' && !portable(relative(source, path)).startsWith('.git/'),
+    });
+}
+async function initializeWorkspaceGit(workspace) {
+    await runCommand('git', ['init', '--initial-branch=doxloop-review'], { cwd: workspace });
+    await runCommand('git', ['add', '.'], { cwd: workspace });
+    await runCommand('git', [
+        '-c',
+        'user.name=Doxloop Review',
+        '-c',
+        'user.email=review@doxloop.local',
+        'commit',
+        '-m',
+        'Doxloop proposal baseline',
+    ], { cwd: workspace });
+}
+async function rewriteWorkspaceSources(workspace, root, project) {
+    const path = join(workspace, '.doxloop', 'project.json');
+    const staged = JSON.parse(await readFile(path, 'utf8'));
+    staged.sources = project.sources.map((source) => ({
+        ...source,
+        path: isAbsolute(source.path) ? source.path : resolve(root, source.path),
+    }));
+    await writeFile(path, `${JSON.stringify(staged, null, 2)}\n`, 'utf8');
+}
+async function restoreWorkspaceSources(workspace, project, originalText) {
+    const path = join(workspace, '.doxloop', 'project.json');
+    const staged = JSON.parse(await readFile(path, 'utf8'));
+    staged.sources = project.sources;
+    const original = JSON.parse(originalText);
+    await writeFile(path, JSON.stringify(staged) === JSON.stringify(original)
+        ? originalText
+        : `${JSON.stringify(staged, null, 2)}\n`, 'utf8');
+}
+async function collectProposalChanges(root, workspace, runRoot, project) {
+    const [beforeFiles, afterFiles, baseline] = await Promise.all([
+        collectFiles(root),
+        collectFiles(workspace),
+        readWorkspaceBaseline(runRoot),
+    ]);
+    const paths = [...new Set([...beforeFiles.keys(), ...afterFiles.keys()])].sort();
+    const pageExtensions = await documentationPageExtensions(root, project);
+    const changes = [];
+    for (const path of paths) {
+        if (INTERNAL_DIFF_PATHS.has(path))
+            continue;
+        const before = beforeFiles.get(path);
+        const after = afterFiles.get(path);
+        if (buffersEqual(before, after))
+            continue;
+        const relation = baseline ? compareWithBaseline(baseline.get(path), before, after) : 'agent-only';
+        // The agent left this file as it found it; only the project moved.
+        if (relation === 'project-only')
+            continue;
+        if (before) {
+            const target = join(runRoot, BEFORE, path);
+            await mkdir(dirname(target), { recursive: true });
+            await writeFile(target, before);
+        }
+        const binary = isBinary(path, before, after);
+        const kind = before === undefined ? 'added' : after === undefined ? 'deleted' : 'modified';
+        const changeId = `change-${changes.length + 1}`;
+        const hunks = binary
+            ? [{ id: `${changeId}-file`, oldStart: 0, oldLines: [], newStart: 0, newLines: [] }]
+            : lineHunks(before?.toString('utf8') ?? '', after?.toString('utf8') ?? '', changeId);
+        changes.push({
+            id: changeId,
+            path,
+            title: await changeTitle(path, before ? join(root, path) : join(workspace, path), project, pageExtensions),
+            kind,
+            category: changeCategory(path, project, pageExtensions),
+            binary,
+            ...(before ? { beforeHash: hash(before) } : {}),
+            ...(after ? { afterHash: hash(after) } : {}),
+            ...(!binary && before ? { beforeEndsWithNewline: before.toString('utf8').endsWith('\n') } : {}),
+            ...(!binary && after ? { afterEndsWithNewline: after.toString('utf8').endsWith('\n') } : {}),
+            hunks,
+            rationale: emptyRationale(kind),
+            ...(relation === 'both' ? { changedDuringRun: true } : {}),
+        });
+    }
+    return changes;
+}
+/**
+ * Where a file moved since the run started: only in the agent's workspace,
+ * only in the project, or in both. Hashes are enough — the live content is
+ * the "before" side either way, and a file the agent never touched is not a
+ * proposal change no matter what happened to it in the project.
+ */
+export function compareWithBaseline(baselineHash, live, proposed) {
+    const liveHash = live ? hash(live) : undefined;
+    const proposedHash = proposed ? hash(proposed) : undefined;
+    if (proposedHash === baselineHash)
+        return 'project-only';
+    return liveHash === baselineHash ? 'agent-only' : 'both';
+}
+async function writeWorkspaceBaseline(runRoot, workspace) {
+    const files = await collectFiles(workspace);
+    const hashes = {};
+    for (const [path, content] of [...files].sort(([left], [right]) => left.localeCompare(right)))
+        hashes[path] = hash(content);
+    await mkdir(runRoot, { recursive: true });
+    await writeFile(join(runRoot, BASELINE_FILE), `${JSON.stringify({ schemaVersion: 1, files: hashes }, null, 2)}\n`, 'utf8');
+}
+/** Absent for runs created before the baseline was recorded; those fall back to a live comparison. */
+async function readWorkspaceBaseline(runRoot) {
+    const path = join(runRoot, BASELINE_FILE);
+    if (!(await pathExists(path)))
+        return undefined;
+    try {
+        const value = await readJson(path);
+        if (value.schemaVersion !== 1 || !value.files || typeof value.files !== 'object')
+            return undefined;
+        return new Map(Object.entries(value.files).filter((entry) => typeof entry[1] === 'string'));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * A page attributed to a source scoped to another route is a bookkeeping
+ * slip, not a reason to discard the run: the attribution is removed from the
+ * evidence map and the reviewer is told. Before, one such entry failed the
+ * whole proposal after the pages were written.
+ */
+async function repairProposalSourceScopes(workspace, changes, project) {
+    const scoped = new Map(project.sources.filter((source) => source.scope?.routePrefix).map((source) => [source.name, source]));
+    if (!scoped.size)
+        return [];
+    let map;
+    try {
+        map = await readJson(join(workspace, '.doxloop', 'evidence-map.json'));
+    }
+    catch {
+        return [];
+    }
+    const prefix = project.contentDir.replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/$/, '');
+    const notes = [];
+    for (const change of changes.filter((item) => item.category === 'page')) {
+        const route = change.path.replace(/\\/g, '/').replace(new RegExp(`^${escapeRegExp(prefix)}/?`), '').replace(/\.[^.]+$/, '');
+        const entry = map.pages[change.path];
+        if (!entry)
+            continue;
+        entry.sources = entry.sources.filter((evidence) => {
+            const source = scoped.get(evidence.source);
+            if (!source?.scope?.routePrefix)
+                return true;
+            const owned = source.scope.routePrefix.replace(/^\/+|\/+$/g, '');
+            const shared = source.scope.sharedPages?.some((pattern) => matchesGlob(change.path, pattern) || matchesGlob(route, pattern)) ?? false;
+            if (route === owned || route.startsWith(`${owned}/`) || shared)
+                return true;
+            notes.push(`${change.path}: attribution to source "${source.name}" (scoped to "${owned}") was removed from the evidence map; move the page into that route or add it to source.scope.sharedPages if it belongs there.`);
+            return false;
+        });
+    }
+    if (notes.length > 0)
+        await writeFile(join(workspace, '.doxloop', 'evidence-map.json'), `${JSON.stringify(map, null, 2)}\n`, 'utf8');
+    return notes;
+}
+function escapeRegExp(value) { return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }
+async function enrichProposalRationales(root, workspace, changes, options, validation) {
+    let evidenceMap;
+    let existingEvidenceMap;
+    try {
+        evidenceMap = await readJson(join(workspace, '.doxloop', 'evidence-map.json'));
+    }
+    catch {
+        evidenceMap = undefined;
+    }
+    try {
+        existingEvidenceMap = await readJson(join(root, '.doxloop', 'evidence-map.json'));
+    }
+    catch {
+        existingEvidenceMap = undefined;
+    }
+    const availability = Object.fromEntries(await Promise.all(options.project.sources.map(async (source) => [
+        source.name,
+        /^https?:\/\//i.test(source.path) || await pathExists(isAbsolute(source.path) ? source.path : resolve(root, source.path)),
+    ])));
+    const revisions = sourceRevisionMap(options.sourceChanges);
+    const changedEvidence = options.sourceChanges.flatMap((change) => sourceChangePaths(change).map((path) => ({
+        source: change.name,
+        path,
+        ...(revisions[change.name] ? { revision: revisions[change.name] } : {}),
+        available: availability[change.name] ?? false,
+    })));
+    return changes.map((change) => {
+        const pageEvidence = evidenceMap?.pages?.[change.path] ?? existingEvidenceMap?.pages?.[change.path];
+        const planPage = matchPlanPage(options.plan, change.path);
+        const capabilities = options.plan?.capabilities.filter((capability) => planPage && capability.pageIds.includes(planPage.id)) ?? [];
+        const preciseEvidence = pageEvidence?.sources.flatMap((source) => [
+            ...(source.paths ?? []).map((path) => ({
+                source: source.source,
+                path,
+                ...((pageEvidence.verifiedAt?.[source.source] ?? revisions[source.source])
+                    ? { revision: pageEvidence.verifiedAt?.[source.source] ?? revisions[source.source] }
+                    : {}),
+                available: availability[source.source] ?? false,
+            })),
+            ...(source.operations ?? []).map((operation) => ({
+                source: source.source,
+                operation,
+                ...((pageEvidence.verifiedAt?.[source.source] ?? revisions[source.source])
+                    ? { revision: pageEvidence.verifiedAt?.[source.source] ?? revisions[source.source] }
+                    : {}),
+                available: availability[source.source] ?? false,
+            })),
+        ]) ?? [];
+        const evidence = uniqueRationaleEvidence(preciseEvidence.length > 0 ? preciseEvidence : [
+            ...capabilities.flatMap((capability) => capability.evidence.map((item) => ({
+                source: item.source,
+                path: item.path,
+                ...(revisions[item.source] ? { revision: revisions[item.source] } : {}),
+                available: availability[item.source] ?? false,
+            }))),
+            ...changedEvidence,
+        ]);
+        const claims = pageEvidence?.claims ?? [];
+        const confidence = pageEvidence?.confidence ?? (evidence.length > 0 ? 'inferred' : 'needs-human');
+        const assumptions = confidence === 'needs-human'
+            ? ['The generated claims require human verification against configured evidence.']
+            : [];
+        const fileIssues = validation.issues.filter((issue) => !issue.file || portable(issue.file) === change.path);
+        return {
+            ...change,
+            rationale: {
+                reason: planPage?.rationale || changeReason(change),
+                evidence,
+                affectedInterfaces: [...new Set(capabilities.flatMap((capability) => [capability.title, ...capability.evidence.flatMap((item) => item.label ? [item.label] : [])]))],
+                claims: {
+                    added: change.kind === 'added' ? claims : [],
+                    changed: change.kind === 'modified' ? claims : [],
+                    removed: change.kind === 'deleted' ? claims : [],
+                },
+                validation: {
+                    errors: fileIssues.filter((issue) => issue.severity === 'error').length,
+                    warnings: fileIssues.filter((issue) => issue.severity === 'warning').length,
+                },
+                confidence,
+                assumptions,
+                ...(options.plan ? { planId: options.plan.id } : {}),
+                ...(planPage ? { planPageId: planPage.id } : {}),
+                ...(options.authoring?.request ? { request: options.authoring.request } : {}),
+                authorship: 'agent',
+            },
+        };
+    });
+}
+async function collectFiles(root) {
+    const files = new Map();
+    await walkFiles(root, root, files);
+    return files;
+}
+async function walkFiles(root, directory, files) {
+    const entries = await readdir(directory, { withFileTypes: true });
+    for (const entry of entries) {
+        const absolute = resolve(directory, entry.name);
+        const path = portable(relative(root, absolute));
+        if (isExcluded(path))
+            continue;
+        if (entry.isDirectory())
+            await walkFiles(root, absolute, files);
+        else if (entry.isFile())
+            files.set(path, await readFile(absolute));
+    }
+}
+function isExcluded(path) {
+    return (path.startsWith('.agents/skills/doxloop-') ||
+        path.startsWith('.claude/skills/doxloop-') ||
+        EXCLUDED_PREFIXES.some((prefix) => path === prefix || path.startsWith(`${prefix}/`)));
+}
+async function materializeChange(before, change, accepted, workspace) {
+    if (change.binary) {
+        if (!accepted.has(change.hunks[0].id))
+            return before;
+        if (change.kind === 'deleted')
+            return undefined;
+        return readFile(join(workspace, change.path));
+    }
+    if (accepted.size === 0)
+        return before;
+    const beforeText = before?.toString('utf8') ?? '';
+    const lines = textLines(beforeText);
+    const output = [];
+    let cursor = 0;
+    for (const hunk of change.hunks) {
+        output.push(...lines.slice(cursor, hunk.oldStart));
+        output.push(...(accepted.has(hunk.id) ? hunk.newLines : hunk.oldLines));
+        cursor = hunk.oldStart + hunk.oldLines.length;
+    }
+    output.push(...lines.slice(cursor));
+    if (change.kind === 'deleted' && change.hunks.every((hunk) => accepted.has(hunk.id))) {
+        return undefined;
+    }
+    const allAccepted = change.hunks.every((hunk) => accepted.has(hunk.id));
+    const trailing = allAccepted
+        ? (change.afterEndsWithNewline ?? false)
+        : (change.beforeEndsWithNewline ?? false);
+    const text = `${output.join('\n')}${trailing && output.length > 0 ? '\n' : ''}`;
+    return Buffer.from(text);
+}
+async function proposalBefore(root, id, path) {
+    const before = join(runBeforeRoot(root, id), path);
+    return (await pathExists(before)) ? readFile(before) : undefined;
+}
+async function proposalAcceptanceBefore(root, id, path) {
+    const snapshot = await readChangeSnapshot(join(runDirectory(root, id), ACCEPTANCE_BEFORE), path);
+    return snapshot.found ? snapshot.content : proposalBefore(root, id, path);
+}
+async function snapshotChangeSet(root, directory, changes) {
+    await rm(directory, { recursive: true, force: true });
+    const absent = [];
+    for (const change of changes) {
+        const actual = safeRunPath(root, change.path);
+        if (!(await pathExists(actual))) {
+            absent.push(change.path);
+            continue;
+        }
+        const target = join(directory, 'files', change.path);
+        await mkdir(dirname(target), { recursive: true });
+        await writeFile(target, await readFile(actual));
+    }
+    await mkdir(directory, { recursive: true });
+    await writeFile(join(directory, 'manifest.json'), `${JSON.stringify({ absent }, null, 2)}\n`, 'utf8');
+}
+async function readChangeSnapshot(directory, path) {
+    const file = join(directory, 'files', path);
+    if (await pathExists(file))
+        return { found: true, content: await readFile(file) };
+    const manifest = join(directory, 'manifest.json');
+    if (!(await pathExists(manifest)))
+        return { found: false, content: undefined };
+    const value = await readJson(manifest);
+    return Array.isArray(value.absent) && value.absent.includes(path)
+        ? { found: true, content: undefined }
+        : { found: false, content: undefined };
+}
+async function applyStagedSyncState(root, id) {
+    const source = join(runWorkspace(root, id), '.doxloop', 'sync-state.json');
+    if (!(await pathExists(source)))
+        return;
+    await writeAtomic(join(root, '.doxloop', 'sync-state.json'), await readFile(source));
+}
+async function snapshotOperationalBefore(root, directory, overwrite = false) {
+    const targetRoot = join(directory, OPERATIONAL_BEFORE);
+    const stateTarget = join(targetRoot, 'sync-state.json');
+    const absentTarget = join(targetRoot, 'sync-state.absent');
+    if (!overwrite && ((await pathExists(stateTarget)) || (await pathExists(absentTarget))))
+        return;
+    await mkdir(targetRoot, { recursive: true });
+    await rm(stateTarget, { force: true });
+    await rm(absentTarget, { force: true });
+    const state = join(root, '.doxloop', 'sync-state.json');
+    if (await pathExists(state))
+        await writeFile(stateTarget, await readFile(state));
+    else
+        await writeFile(absentTarget, '', 'utf8');
+}
+async function restoreOperationalBefore(root, id) {
+    const snapshotRoot = join(runDirectory(root, id), OPERATIONAL_BEFORE);
+    const state = join(snapshotRoot, 'sync-state.json');
+    const target = join(root, '.doxloop', 'sync-state.json');
+    if (await pathExists(state)) {
+        await writeAtomic(target, await readFile(state));
+        return;
+    }
+    if (await pathExists(join(snapshotRoot, 'sync-state.absent')))
+        await writeAtomic(target, undefined);
+}
+async function resolveRevisionScope(root, id, request) {
+    if (!request || request.changeIds.length === 0) {
+        throw new DoxloopError('A targeted proposal revision requires at least one selected change.');
+    }
+    const previous = await readSyncRun(root, id);
+    const selectedPaths = new Set();
+    const hunkRanges = new Map();
+    for (const changeId of request.changeIds) {
+        const change = previous.changes.find((item) => item.id === changeId);
+        if (!change)
+            throw new DoxloopError(`Unknown proposal change ${changeId}.`);
+        selectedPaths.add(change.path);
+    }
+    for (const hunkId of request.hunkIds ?? []) {
+        const change = previous.changes.find((item) => item.hunks.some((hunk) => hunk.id === hunkId));
+        const hunk = change?.hunks.find((item) => item.id === hunkId);
+        if (!change || !hunk)
+            throw new DoxloopError(`Unknown selected change hunk ${hunkId}.`);
+        const ranges = hunkRanges.get(change.path) ?? [];
+        ranges.push({ start: hunk.newStart, end: hunk.newStart + Math.max(1, hunk.newLines.length) });
+        hunkRanges.set(change.path, ranges);
+    }
+    const supportingPaths = new Set(previous.changes
+        .filter((change) => ['navigation', 'configuration', 'evidence'].includes(change.category))
+        .map((change) => change.path));
+    return {
+        selectedPaths,
+        supportingPaths,
+        wholeProposal: selectedPaths.size === previous.changes.length && hunkRanges.size === 0,
+        hunkRanges,
+    };
+}
+export async function assertRevisionStayedInScope(workspace, baseline, scope, edit = false) {
+    const after = await collectFiles(workspace);
+    const paths = new Set([...baseline.keys(), ...after.keys()]);
+    const selectedChanged = scope.wholeProposal
+        ? [...paths].some((path) => !buffersEqual(baseline.get(path), after.get(path)))
+        : [...scope.selectedPaths].some((path) => !buffersEqual(baseline.get(path), after.get(path)));
+    if (!selectedChanged) {
+        throw new DoxloopError(edit
+            ? `The agent did not change ${scope.selectedPaths.size === 1 ? 'this page' : 'these pages'}. Nothing was applied.`
+            : 'The agent did not revise the selected proposal scope. The original proposal remains available.');
+    }
+    if (scope.wholeProposal)
+        return;
+    if (edit) {
+        const deleted = [...scope.selectedPaths].filter((path) => baseline.has(path) && !after.has(path));
+        if (deleted.length > 0) {
+            throw new DoxloopError(`The agent deleted ${deleted.join(', ')}. Page creation, deletion, and rename are not available in a scoped edit. Nothing was applied.`);
+        }
+    }
+    const outOfScope = [...paths].filter((path) => !buffersEqual(baseline.get(path), after.get(path))
+        && !scope.selectedPaths.has(path)
+        && !scope.supportingPaths.has(path)
+        && ![...(scope.supportingPrefixes ?? [])].some((prefix) => path.startsWith(prefix) && !scope.pageExtensions?.has(extname(path).toLowerCase())));
+    if (outOfScope.length > 0) {
+        throw new DoxloopError(edit
+            ? `The agent changed files outside ${scope.selectedPaths.size === 1 ? 'this page' : 'these pages'}: ${outOfScope.slice(0, 8).join(', ')}${outOfScope.length > 8 ? ', …' : ''}. Nothing was applied. Turn on "Also allow related changes" if those files should be part of the edit.`
+            : `The revision changed files outside the selected scope: ${outOfScope.slice(0, 8).join(', ')}${outOfScope.length > 8 ? ', …' : ''}. No proposal was replaced.`);
+    }
+    for (const [path, ranges] of scope.hunkRanges) {
+        const before = baseline.get(path);
+        const current = after.get(path);
+        if (!before || !current || isBinary(path, before, current)) {
+            throw new DoxloopError(`The selected hunk in ${path} cannot be safely revised as text.`);
+        }
+        const revisionHunks = lineHunks(before.toString('utf8'), current.toString('utf8'), 'revision-scope');
+        const outsideHunk = revisionHunks.some((hunk) => {
+            const start = hunk.oldStart;
+            const end = start + Math.max(1, hunk.oldLines.length);
+            return !ranges.some((range) => start < range.end + 1 && end > range.start - 1);
+        });
+        if (outsideHunk) {
+            throw new DoxloopError(`The revision changed text outside the selected hunk in ${path}. No proposal was replaced.`);
+        }
+    }
+}
+/**
+ * A proposal is a reviewed change set, so source movement while it waits must
+ * not discard or lock that work. Keep its snapshot current and surface the
+ * difference as review context; file-level concurrency checks still protect
+ * the real documentation from being overwritten during acceptance.
+ */
+async function refreshProposalSourceSnapshot(root, run) {
+    const project = await loadProject(root);
+    const current = await proposalSourceSnapshot(root, project);
+    if (current === run.sourceSnapshot)
+        return run;
+    const sourcesChanged = Boolean(run.sourceSnapshot);
+    return {
+        ...run,
+        sourceSnapshot: current,
+        ...withAdvisory(run, sourcesChanged ? SOURCES_CHANGED_DURING_REVIEW : undefined),
+    };
+}
+async function optionalApprovedPlan(root) {
+    const path = join(root, '.doxloop', 'documentation-plan.json');
+    if (!(await pathExists(path)))
+        return undefined;
+    try {
+        const plan = await readJson(path);
+        return plan.schemaVersion === 2 && plan.status === 'approved' ? plan : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function writeAtomic(path, content) {
+    if (content === undefined) {
+        await unlink(path).catch((error) => {
+            if (error.code !== 'ENOENT')
+                throw error;
+        });
+        return;
+    }
+    await mkdir(dirname(path), { recursive: true });
+    const temporary = `${path}.doxloop-${process.pid}-${randomBytes(4).toString('hex')}`;
+    await writeFile(temporary, content);
+    await rename(temporary, path);
+}
+function normalizeSyncRun(raw, id) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return { migrated: false };
+    const value = raw;
+    if ((value.schemaVersion !== 1 && value.schemaVersion !== 2) || value.id !== id || !Array.isArray(value.changes)) {
+        return { migrated: false };
+    }
+    const changes = value.changes.flatMap((item) => {
+        if (!item || typeof item !== 'object' || Array.isArray(item))
+            return [];
+        const change = item;
+        if (typeof change.id !== 'string' || typeof change.path !== 'string' || !Array.isArray(change.hunks))
+            return [];
+        return [{
+                ...change,
+                rationale: validRationale(change.rationale) ? change.rationale : emptyRationale(change.kind),
+            }];
+    });
+    const { authoringMode: _authoringMode, planId: _planId, ...stored } = value;
+    const run = {
+        ...stored,
+        schemaVersion: 2,
+        ...(value.authoringMode === 'create' || value.authoringMode === 'update' ? { authoringMode: value.authoringMode } : {}),
+        ...(typeof value.planId === 'string' && /^plan-[a-z0-9-]+$/.test(value.planId) ? { planId: value.planId } : {}),
+        changes,
+        revisionRequests: Array.isArray(value.revisionRequests) ? value.revisionRequests : [],
+        humanEdits: Array.isArray(value.humanEdits) ? value.humanEdits : [],
+    };
+    const legacySourceStale = run.status === 'stale' && Boolean(run.error?.includes(LEGACY_STALE_SOURCE_ERROR));
+    if (legacySourceStale) {
+        run.status = 'awaiting-review';
+        delete run.error;
+        Object.assign(run, withAdvisory(run, SOURCES_CHANGED_DURING_REVIEW));
+    }
+    return { run, migrated: value.schemaVersion === 1 || legacySourceStale };
+}
+function validRationale(value) {
+    return Boolean(value && typeof value === 'object' && !Array.isArray(value) && typeof value.reason === 'string');
+}
+/**
+ * A run left at "generating" by a process that is gone (cancelled, killed, or
+ * the UI server restarted) is marked failed so Review offers Resume instead
+ * of showing it as still being written. Only runs created after `since`
+ * are touched, so an older interrupted run keeps whatever it recorded.
+ */
+export async function markInterruptedSyncRuns(root, since, message) {
+    const marked = [];
+    const floor = Date.parse(since) - 5_000;
+    for (const run of await listSyncRuns(root)) {
+        if (run.status !== 'generating' || Date.parse(run.createdAt) < floor)
+            continue;
+        const failed = { ...run, status: 'failed', error: message, completedAt: new Date().toISOString() };
+        await writeRun(root, failed);
+        await recordSyncRun(root, failed).catch(() => undefined);
+        marked.push(run.id);
+    }
+    return marked;
+}
+async function writeRun(root, run) {
+    const path = join(runDirectory(root, run.id), RUN_FILE);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(run, null, 2)}\n`, 'utf8');
+}
+async function ensureRunsIgnored(root) {
+    const path = join(root, '.gitignore');
+    const line = '.doxloop/runs/';
+    const existing = (await pathExists(path)) ? await readFile(path, 'utf8') : '';
+    if (existing.split(/\r?\n/).includes(line))
+        return;
+    await writeFile(path, `${existing}${existing && !existing.endsWith('\n') ? '\n' : ''}${line}\n`, 'utf8');
+}
+function runDirectory(root, id) {
+    assertRunId(id);
+    return join(root, SYNC_RUNS_DIRECTORY, id);
+}
+function safeRunPath(root, path) {
+    if (path === '' || isAbsolute(path) || path.split(/[\\/]/).includes('..')) {
+        throw new DoxloopError(`Unsafe proposal path: ${path}`);
+    }
+    return assertInside(root, resolve(root, path));
+}
+function assertRunId(id) {
+    if (!/^[a-z0-9-]+$/.test(id))
+        throw new DoxloopError(`Invalid sync run id: ${id}`);
+}
+export function createRunId() {
+    const stamp = new Date().toISOString().replace(/[-:]/g, '').replace(/\.\d{3}Z$/, 'Z');
+    return `run-${stamp.toLowerCase()}-${randomBytes(3).toString('hex')}`;
+}
+function hash(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+function buffersEqual(left, right) {
+    if (left === undefined || right === undefined)
+        return left === right;
+    return left.equals(right);
+}
+function isBinary(path, before, after) {
+    if (BINARY_EXTENSIONS.has(extname(path).toLowerCase()))
+        return true;
+    return [before, after].some((content) => content?.subarray(0, 8_192).includes(0));
+}
+function acceptedIds(change) {
+    return new Set(change.hunks.filter((hunk) => hunk.acceptedAt).map((hunk) => hunk.id));
+}
+const NAVIGATION_PATTERN = /nav|sidebar|menu|site\.json|docs\.json|mkdocs\.yml|docusaurus\.config/i;
+function changeCategory(path, project, pageExtensions) {
+    if (path === '.doxloop/evidence-map.json')
+        return 'evidence';
+    const extension = extname(path).toLowerCase();
+    const content = portable(project.contentDir).replace(/\/+$/, '');
+    const insideContent = content === '' || path === content || path.startsWith(`${content}/`) || (project.generator === 'docusaurus' && /^(?:versioned_docs\/version-[\w.-]+\/|i18n\/[\w-]+\/docusaurus-plugin-content-docs\/(?:current|version-[\w.-]+)\/)/.test(path));
+    if (insideContent) {
+        if (pageExtensions.has(extension))
+            return 'page';
+        if (BINARY_EXTENSIONS.has(extension))
+            return 'asset';
+        // Data files inside the content directory — a Doxbrix `docs.json`, an
+        // MkDocs navigation file — configure the site rather than being read as
+        // pages, so they must not enter the page review flow.
+        return NAVIGATION_PATTERN.test(path) ? 'navigation' : 'configuration';
+    }
+    if (NAVIGATION_PATTERN.test(path))
+        return 'navigation';
+    return BINARY_EXTENSIONS.has(extension) ? 'asset' : 'configuration';
+}
+async function changeTitle(path, sourcePath, project, pageExtensions) {
+    if (changeCategory(path, project, pageExtensions) === 'page') {
+        try {
+            const page = await readPage(sourcePath);
+            if (page.title)
+                return page.title;
+        }
+        catch {
+            // Deleted or non-Markdown generator pages use their file name.
+        }
+    }
+    return path.split('/').at(-1) ?? path;
+}
+function sourceSummary(changes) {
+    const files = changes.flatMap((change) => [
+        ...('changedFiles' in change ? change.changedFiles : []),
+        ...('uncommittedFiles' in change ? change.uncommittedFiles : []),
+    ]);
+    return files.length > 0
+        ? `${files.length} changed source file${files.length === 1 ? '' : 's'}: ${files.slice(0, 12).join(', ')}${files.length > 12 ? ', …' : ''}`
+        : `${changes.length} configured source${changes.length === 1 ? '' : 's'} inspected`;
+}
+function emptyRationale(kind) {
+    return {
+        reason: kind === 'added' ? 'This file was added by the documentation request.'
+            : kind === 'deleted' ? 'This file was removed by the documentation request.'
+                : 'This file was changed by the documentation request.',
+        evidence: [],
+        affectedInterfaces: [],
+        claims: { added: [], changed: [], removed: [] },
+        validation: { errors: 0, warnings: 0 },
+        confidence: 'needs-human',
+        assumptions: ['Detailed rationale was not recorded for this legacy proposal.'],
+        authorship: 'agent',
+    };
+}
+function changeReason(change) {
+    if (change.category === 'evidence')
+        return 'Update the evidence map for the reader-facing claims in this proposal.';
+    if (change.category === 'navigation')
+        return 'Keep navigation aligned with the proposed documentation structure.';
+    if (change.category === 'configuration')
+        return 'Keep generator configuration aligned with the proposed documentation.';
+    if (change.category === 'asset')
+        return 'Add or update a supporting reader-facing asset.';
+    if (change.kind === 'added')
+        return `Add “${change.title}” to cover an approved reader outcome.`;
+    if (change.kind === 'deleted')
+        return `Remove “${change.title}” because it is no longer part of the approved documentation.`;
+    return `Update “${change.title}” to match the approved request and current evidence.`;
+}
+/** Whether the live copy of a page the agent removed was generated starter scaffolding. */
+async function isStarterFile(path) {
+    try {
+        return isStarterContent(await readFile(path, 'utf8'));
+    }
+    catch {
+        return false;
+    }
+}
+function matchPlanPage(plan, path) {
+    if (!plan)
+        return undefined;
+    const portablePath = portable(path).replace(/^\/+/, '');
+    return plan.pages.find((page) => {
+        const planned = portable(page.path).replace(/^\/+|\/+$/g, '');
+        const prefix = plan.target?.contentDir?.replace(/^\/+|\/+$/g, '');
+        const candidates = new Set([planned, ...(prefix && !planned.startsWith(`${prefix}/`) ? [`${prefix}/${planned}`] : [])]);
+        return [...candidates].some((candidate) => portablePath === candidate || portablePath.replace(/\.(mdx?|rst|html?)$/, '') === candidate);
+    });
+}
+function sourceRevisionMap(changes) {
+    return Object.fromEntries(changes.flatMap((change) => {
+        if ('head' in change && change.head)
+            return [[change.name, change.head]];
+        if ('baseline' in change && change.baseline)
+            return [[change.name, change.baseline]];
+        return [];
+    }));
+}
+function sourceChangePaths(change) {
+    return changedSourcePaths(change);
+}
+function uniqueRationaleEvidence(items) {
+    const seen = new Set();
+    return items.flatMap((item) => {
+        const normalized = {
+            source: item.source,
+            ...(item.path ? { path: item.path } : {}),
+            ...(item.operation ? { operation: item.operation } : {}),
+            ...(item.revision ? { revision: item.revision } : {}),
+            available: item.available,
+        };
+        const key = JSON.stringify(normalized);
+        if (seen.has(key))
+            return [];
+        seen.add(key);
+        return [normalized];
+    });
+}
+async function proposalSourceSnapshot(root, project) {
+    const fingerprints = await sourceSnapshotFingerprints(root, project.sources);
+    return hash(Buffer.from(JSON.stringify({ sources: project.sources, fingerprints })));
+}
+function retentionDate(createdAt) {
+    const date = new Date(createdAt);
+    date.setUTCDate(date.getUTCDate() + 30);
+    return date.toISOString();
+}
+async function markSuperseded(root, id, replacementId) {
+    const previous = await readSyncRun(root, id);
+    if (!['awaiting-review', 'partially-applied', 'conflicted', 'stale'].includes(previous.status))
+        return;
+    const next = { ...previous, status: 'superseded', supersededBy: replacementId };
+    await writeRun(root, next);
+    await recordSyncRun(root, next);
+}
+function proposalSummary(changes) {
+    const added = changes.filter((change) => change.kind === 'added').length;
+    const modified = changes.filter((change) => change.kind === 'modified').length;
+    const deleted = changes.filter((change) => change.kind === 'deleted').length;
+    return `${changes.length} proposed file change${changes.length === 1 ? '' : 's'} · ${added} added · ${modified} modified · ${deleted} deleted`;
+}
+function changeCounts(changes) {
+    const accepted = changes.reduce((count, change) => count + change.hunks.filter((hunk) => hunk.acceptedAt).length, 0);
+    const total = changes.reduce((count, change) => count + change.hunks.length, 0);
+    return `${changes.length} files · ${accepted}/${total} changes accepted`;
+}
+function statusMark(status) {
+    if (status === 'applied')
+        return '✓';
+    if (status === 'failed' || status === 'conflicted')
+        return '✗';
+    if (status === 'rejected')
+        return '–';
+    return '●';
+}
+function portable(path) {
+    return sep === '/' ? path : path.split(sep).join('/');
+}
+//# sourceMappingURL=sync-runs.js.map