@open-agent-toolkit/cli 0.3.15 → 0.3.17

package/dist/commands/project/archive/archive-utils.js

@@ -1,6 +1,6 @@
 import { execFile as execFileCallback } from 'node:child_process';
 import { createHash, randomUUID } from 'node:crypto';
-import { lstat, readFile, readdir, realpath, rename, rm, writeFile, } from 'node:fs/promises';
+import { link, lstat, mkdir, mkdtemp, readFile, readdir, realpath, rename, rm, writeFile, } from 'node:fs/promises';
 import { basename, dirname, isAbsolute, join, posix as path, relative, resolve, sep, } from 'node:path';
 import { promisify } from 'node:util';
 import { defaultGitRunner } from '../../project/sync/git.js';
@@ -10,6 +10,7 @@ import { probeSyncedTerminalRefs } from '../../project/sync/resolve-target.js';
 import { canonicalizePath, resolveProjectScope, resolveScopeRoot, syncedRecordPath, } from '../../shared/project-scope.js';
 import { CliError } from '../../../errors/cli-error.js';
 import { copyDirectory, copySingleFile, dirExists, ensureDir, fileExists, } from '../../../fs/io.js';
+import { decodeHTMLAttribute } from 'entities/decode';
 import { loadExplainerPackageCoverage } from './explainer-package-coverage.js';
 const execFileAsync = promisify(execFileCallback);
 export const ARCHIVE_SNAPSHOT_METADATA_FILENAME = '.oat-archive-source.json';
@@ -415,7 +416,7 @@ async function resolveRecordlessSyncedArchiveIdentity(options, target, git, depe
     }
     return matches[0];
 }
-async function exportProjectSummary(archivePath, snapshotName, summaryExportPath, repoRoot, dependencies) {
+async function exportProjectSummary(archivePath, snapshotName, summaryExportPath, repoRoot, dependencies, recapExport) {
     const summarySource = join(archivePath, 'summary.md');
     const exists = dependencies.fileExists ?? fileExists;
     if (!(await exists(summarySource))) {
@@ -423,17 +424,35 @@ async function exportProjectSummary(archivePath, snapshotName, summaryExportPath
     }
     const summaryTarget = join(repoRoot, summaryExportPath, `${snapshotName}.md`);
     const copySummary = dependencies.copySingleFile ?? copySingleFile;
+    const sourceContents = await readFile(summarySource);
+    let expectedContents = sourceContents;
+    if (recapExport) {
+        const pageLink = relative(dirname(summaryTarget), recapExport.exportRoot)
+            .split(sep)
+            .join('/');
+        const receipt = `Recap: [View the recap](${pageLink})\n\nRun: \`${recapExport.runId}\`  \nOriginal page SHA-256: \`${recapExport.page.originalSha256}\`  \nExported page SHA-256: \`${recapExport.page.exportedSha256}\`\n`;
+        const text = sourceContents.toString('utf8');
+        const outcome = /(^## Explainer Outcome[^\n]*\n)([\s\S]*?)(?=^## |$(?![\s\S]))/m;
+        const rewriteLinks = (body) => body.replace(/\[([^\]]+)\]\(([^)]+)\)/g, (markdownLink, label, href) => /(?:explainers\/|project-recaps\/)/.test(href)
+            ? `[${label}](${pageLink})`
+            : markdownLink);
+        expectedContents = Buffer.from(outcome.test(text)
+            ? text.replace(outcome, (_match, heading, body) => `${heading}${rewriteLinks(body).trimEnd()}\n\n${receipt}\n`)
+            : `${text.trimEnd()}\n\n## Explainer Outcome\n\n${receipt}`);
+    }
     if (await pathExists(summaryTarget)) {
-        const [sourceContents, targetContents] = await Promise.all([
-            readFile(summarySource),
-            readFile(summaryTarget),
-        ]);
-        if (!sourceContents.equals(targetContents)) {
+        const targetContents = await readFile(summaryTarget);
+        if (!expectedContents.equals(targetContents)) {
             throw new CliError(`Existing summary export \`${summaryTarget}\` does not match persisted snapshot \`${snapshotName}\`; refusing to overwrite it.`);
         }
         return summaryTarget;
     }
     await copySummary(summarySource, summaryTarget);
+    if (recapExport)
+        await writeFile(summaryTarget, expectedContents);
+    if (!expectedContents.equals(await readFile(summaryTarget))) {
+        throw new CliError(`Summary export \`${summaryTarget}\` failed byte verification.`);
+    }
     return summaryTarget;
 }
 async function parseProjectRecapManifest(contents) {
@@ -444,11 +463,48 @@ async function parseProjectRecapManifest(contents) {
     catch {
         throw new CliError('Selected project recap has an invalid manifest.json.');
     }
-    if (!isProjectRecapManifestV2(value)) {
+    if (!isProjectRecapManifestV2(value) &&
+        !isLegacyProjectRecapManifest(value)) {
         throw new CliError('Selected project recap manifest does not match the explainer-kit manifest contract.');
     }
     return value;
 }
+// Compatibility is derived from the captured July v1 packages. Their manifest
+// and build record receive durability attestations after immutable recording.
+function isLegacyProjectRecapManifest(value) {
+    if (!isRecord(value) ||
+        value.schemaVersion !== 'explainer-kit.manifest/v1' ||
+        !isNonEmptyString(value.runId) ||
+        !isNonEmptyString(value.slug) ||
+        !isDateTime(value.createdAt) ||
+        !isRecord(value.recipe) ||
+        value.recipe.id !== 'project-recap' ||
+        !isRecord(value.source) ||
+        !isSafeRelativePath(value.source.factBasePath) ||
+        !isSha256(value.source.factBaseHash) ||
+        !isHashMap(value.source.inputHashes) ||
+        !isRecord(value.theme) ||
+        value.theme.path !== 'theme.resolved.json' ||
+        !isSha256(value.theme.hash) ||
+        !isRecord(value.buildRecord) ||
+        value.buildRecord.path !== 'build-record.json' ||
+        !isSha256(value.buildRecord.hash) ||
+        !isHashMap(value.immutableHashes) ||
+        !Array.isArray(value.source.authorResultPaths) ||
+        !value.source.authorResultPaths.every(isSafeRelativePath) ||
+        !Array.isArray(value.artifacts) ||
+        value.artifacts.length !== 1 ||
+        !['built', 'built-needs-review', 'built-durable'].includes(String(value.outcome)))
+        return false;
+    return value.artifacts.every((artifact) => isRecord(artifact) &&
+        isNonEmptyString(artifact.id) &&
+        artifact.status === 'built' &&
+        isSafeRelativePath(artifact.contentPath) &&
+        isSafeRelativePath(artifact.renderedPath) &&
+        artifact.renderedPath.startsWith('site/') &&
+        artifact.mediaType === 'text/html' &&
+        isSha256(artifact.hash));
+}
 function isProjectRecapManifestV2(value) {
     if (!isRecord(value) ||
         !hasExactKeys(value, [
@@ -603,6 +659,34 @@ async function verifyProjectRecapImmutableHashes(stagedRoot, manifest) {
     }
     return entries.length;
 }
+async function verifyRecapInventory(root, files) {
+    const allowed = new Set(files);
+    const directories = new Set();
+    for (const file of files) {
+        let parent = dirname(file);
+        while (parent !== '.') {
+            directories.add(parent);
+            parent = dirname(parent);
+        }
+    }
+    const present = new Set();
+    async function inspect(current = '') {
+        for (const entry of await readdir(join(root, current), {
+            withFileTypes: true,
+        })) {
+            const entryPath = current ? `${current}/${entry.name}` : entry.name;
+            if (entry.isDirectory() && directories.has(entryPath))
+                await inspect(entryPath);
+            else if (entry.isFile() && allowed.has(entryPath))
+                present.add(entryPath);
+            else
+                throw new CliError('Selected project recap package inventory is invalid.');
+        }
+    }
+    await inspect();
+    if (files.some((file) => !present.has(file)))
+        throw new CliError('Selected project recap package inventory is invalid.');
+}
 async function loadVerifiedProjectRecap(projectPath, projectRecapRun) {
     const sourceRunRoot = await resolveSelectedProjectRecapRun(projectPath, projectRecapRun);
     const manifestContents = await readFile(join(sourceRunRoot, 'manifest.json'), 'utf8');
@@ -610,11 +694,69 @@ async function loadVerifiedProjectRecap(projectPath, projectRecapRun) {
     if (manifest.recipe.id !== 'project-recap') {
         throw new CliError('Selected project recap manifest recipe must be exactly `project-recap`.');
     }
-    if (!['built', 'built-needs-review'].includes(manifest.outcome) ||
+    if (![
+        'built',
+        'built-needs-review',
+        ...(manifest.schemaVersion === 'explainer-kit.manifest/v1'
+            ? ['built-durable']
+            : []),
+    ].includes(manifest.outcome) ||
         manifest.artifacts.some((artifact) => artifact.status !== 'built')) {
         throw new CliError('Selected project recap must have a satisfied outcome and built artifacts.');
     }
     const verifiedArtifactCount = await verifyProjectRecapImmutableHashes(sourceRunRoot, manifest);
+    if (manifest.schemaVersion === 'explainer-kit.manifest/v1') {
+        const raw = JSON.parse(manifestContents);
+        // July v1 hashes fact-base/theme canonical JSON identities separately
+        // from immutableHashes' exact file-byte digests (captured writer contract).
+        const canonicalize = (value) => {
+            if (Array.isArray(value))
+                return value.map(canonicalize);
+            if (isRecord(value))
+                return Object.fromEntries(Object.keys(value)
+                    .sort()
+                    .map((key) => [key, canonicalize(value[key])]));
+            return value;
+        };
+        const canonicalFileHash = async (file) => sha256(JSON.stringify(canonicalize(JSON.parse(await readFile(join(sourceRunRoot, file), 'utf8')))));
+        const required = [
+            'run-request.json',
+            'source/fact-base.json',
+            'source/fact-base.md',
+            'source/content-approval.json',
+            'theme.resolved.json',
+            ...raw.source.authorResultPaths,
+            ...manifest.artifacts.flatMap((artifact) => [
+                artifact.contentPath,
+                artifact.renderedPath,
+            ]),
+        ];
+        if (required.some((file) => !(file in manifest.immutableHashes)) ||
+            manifest.source.factBaseHash !==
+                (await canonicalFileHash(manifest.source.factBasePath)) ||
+            manifest.theme.hash !== (await canonicalFileHash(manifest.theme.path)) ||
+            manifest.artifacts.some((artifact) => artifact.hash !== manifest.immutableHashes[artifact.renderedPath])) {
+            throw new CliError('Selected legacy recap has incomplete immutable package hashes.');
+        }
+        const packagePaths = [
+            ...Object.keys(manifest.immutableHashes),
+            'manifest.json',
+            'build-record.json',
+        ].sort();
+        await verifyRecapInventory(sourceRunRoot, packagePaths);
+        const record = JSON.parse(await readFile(join(sourceRunRoot, 'build-record.json'), 'utf8'));
+        if (record.schemaVersion !== 'explainer-kit.build-record/v1' ||
+            record.runId !== manifest.runId ||
+            record.outcome !== manifest.outcome)
+            throw new CliError('Legacy recap build record identity does not match its manifest.');
+        return {
+            sourceRunRoot,
+            manifestContents,
+            manifest,
+            verifiedArtifactCount,
+            packagePaths,
+        };
+    }
     const packageCoverage = await loadExplainerPackageCoverage();
     const missingCoverage = packageCoverage
         .requiredImmutablePackagePaths(manifest)
@@ -656,88 +798,353 @@ async function loadVerifiedProjectRecap(projectPath, projectRecapRun) {
 export async function verifySelectedProjectRecapForArchive(projectPath, projectRecapRun) {
     await loadVerifiedProjectRecap(projectPath, projectRecapRun);
 }
-async function exportSelectedProjectRecap(options, snapshotName, dependencies) {
-    const selectedRun = options.projectRecapRun?.trim();
-    if (!selectedRun) {
-        return null;
+function sha256(bytes) {
+    return `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+}
+async function transformRecapPage(html, sourcePage, sourceRunRoot, stagedRoot, exportPage, options) {
+    const external = (url) => /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i.test(url);
+    const resolveAssetPath = async (url, base) => {
+        const assetPath = resolve(dirname(base), decodeURIComponent(url.split(/[?#]/)[0]));
+        if (!isInsidePath(sourceRunRoot, assetPath) ||
+            !isInsidePath(await realpath(sourceRunRoot), await realpath(assetPath)))
+            throw new CliError(`Recap asset escapes its verified package: ${url}`);
+        return assetPath;
+    };
+    const asset = async (url, base) => {
+        if (external(url) || url.startsWith('#'))
+            return url;
+        const assetPath = await resolveAssetPath(url, base);
+        const bytes = await readFile(join(stagedRoot, relative(sourceRunRoot, assetPath)));
+        const mime = {
+            png: 'image/png',
+            svg: 'image/svg+xml',
+            jpg: 'image/jpeg',
+            jpeg: 'image/jpeg',
+            gif: 'image/gif',
+            webp: 'image/webp',
+            woff: 'font/woff',
+            woff2: 'font/woff2',
+        };
+        const type = mime[assetPath.split('.').pop() ?? ''] ?? 'application/octet-stream';
+        return `data:${type};base64,${bytes.toString('base64')}`;
+    };
+    const replaceAsync = async (text, pattern, callback) => {
+        const matches = [...text.matchAll(pattern)];
+        const replacements = await Promise.all(matches.map(callback));
+        for (let index = matches.length - 1; index >= 0; index--) {
+            const match = matches[index];
+            text =
+                text.slice(0, match.index) +
+                    replacements[index] +
+                    text.slice(match.index + match[0].length);
+        }
+        return text;
+    };
+    const decodeCssUrl = (url) => url.replace(/\\(?:([0-9a-f]{1,6})(?:\r\n|[ \t\n\r\f])?|\r\n|[\n\r\f]|([\s\S]))/gi, (_match, hex, escaped) => {
+        if (hex === undefined)
+            return escaped ?? '';
+        const codePoint = Number.parseInt(hex, 16);
+        return String.fromCodePoint(codePoint === 0 ||
+            codePoint > 0x10ffff ||
+            (codePoint >= 0xd800 && codePoint <= 0xdfff)
+            ? 0xfffd
+            : codePoint);
+    });
+    const quoteCssUrl = (url) => `"${url.replace(/["\\<\p{Cc}]/gu, (character) => character === '"' || character === '\\'
+        ? `\\${character}`
+        : `\\${character.charCodeAt(0).toString(16)} `)}"`;
+    const css = async (text, base) => replaceAsync(text, 
+    // Consume CSS comments/strings before recognizing a resource URL. Text in
+    // those bodies can describe markup or url(...) without referencing an asset.
+    /\/\*[\s\S]*?(?:\*\/|$)|"(?:\\[\s\S]|[^"\\])*"|'(?:\\[\s\S]|[^'\\])*'|(?<![\w-])url\(\s*(?:"((?:\\[\s\S]|[^"\\])+)"|'((?:\\[\s\S]|[^'\\])+)'|((?:\\[\s\S]|[^)'"\\\s])+))\s*\)/gi, async (match) => {
+        const url = match[1] ?? match[2] ?? match[3];
+        return url === undefined
+            ? match[0]
+            : `url(${quoteCssUrl(await asset(decodeCssUrl(url), base))})`;
+    });
+    // Match complete attributes, including unrelated quoted values. Looking only
+    // for href/src would also find those strings inside title/data attributes.
+    const attributePattern = /\s+([^\s"'<>/=]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'`=<>]+)))?/g;
+    const attributeValue = (match) => {
+        const value = match[2] ?? match[3] ?? match[4];
+        return value === undefined ? undefined : decodeHTMLAttribute(value);
+    };
+    const emitAttribute = (name, value, quote = '"') => ` ${name}=${quote}${value
+        .replaceAll('&', '&amp;')
+        .replaceAll(quote, quote === '"' ? '&quot;' : '&#39;')}${quote}`;
+    const attributes = (tag) => new Map([...tag.matchAll(attributePattern)].map((match) => [
+        match[1].toLowerCase(),
+        attributeValue(match),
+    ]));
+    const markup = /<!--[\s\S]*?(?:-->|$)|<![^>]*>|<\?[^>]*>|<[a-z][a-z0-9:-]*(?=[\s/>])(?:[^"'<>]|"[^"]*"|'[^']*')*>/gi;
+    const rawText = /^(script|style|textarea|title|xmp|iframe|noembed|noframes|plaintext)$/;
+    const fragmentTargets = new Set();
+    let targetMatch;
+    // Use the same markup/attribute readers for forward targets. Descriptions of
+    // markup inside comments, attribute values, and raw-text bodies are not targets.
+    while ((targetMatch = markup.exec(html))) {
+        const name = /^<([a-z][a-z0-9:-]*)/i
+            .exec(targetMatch[0])?.[1]
+            ?.toLowerCase();
+        if (!name)
+            continue;
+        const values = attributes(targetMatch[0]);
+        for (const attribute of ['id', 'name']) {
+            const value = values.get(attribute);
+            if (value !== undefined)
+                fragmentTargets.add(value);
+        }
+        if (rawText.test(name)) {
+            const closing = new RegExp(`</${name}\\s*>`, 'gi');
+            closing.lastIndex = markup.lastIndex;
+            const end = name === 'plaintext' ? null : closing.exec(html);
+            markup.lastIndex = end ? closing.lastIndex : html.length;
+        }
     }
-    const verified = await loadVerifiedProjectRecap(options.projectPath, selectedRun);
-    const { sourceRunRoot, manifestContents: sourceManifestContents, packagePaths, } = verified;
-    const exportRoot = join(options.repoRoot, '.oat', 'repo', 'reference', 'project-recaps', snapshotName);
-    if (await pathExists(exportRoot)) {
-        let exportedManifestContents;
-        try {
-            exportedManifestContents = await readFile(join(exportRoot, 'manifest.json'), 'utf8');
+    const rewriteAttributes = async (tag, removeScriptSource = false) => replaceAsync(tag, attributePattern, async (match) => {
+        const name = match[1].toLowerCase();
+        const url = attributeValue(match);
+        if (url === undefined)
+            return match[0];
+        if (name === 'style') {
+            const value = await css(url, sourcePage);
+            if (value === url)
+                return match[0];
+            const quote = match[3] !== undefined ? "'" : '"';
+            return emitAttribute(match[1], value, quote);
         }
-        catch {
-            throw new CliError(`Project recap export destination \`${exportRoot}\` already exists and cannot be verified for retry.`);
+        if (name !== 'href' && name !== 'src')
+            return match[0];
+        if (name === 'src' && removeScriptSource)
+            return '';
+        if (external(url))
+            return match[0];
+        if (name === 'src') {
+            const quote = match[3] !== undefined ? "'" : '"';
+            return emitAttribute('src', await asset(url, sourcePage), quote);
+        }
+        const [pathname, fragment] = url.split('#');
+        if (!pathname) {
+            if (fragment && !fragmentTargets.has(fragment))
+                return '';
+            return match[0];
+        }
+        const original = resolve(dirname(sourcePage), decodeURIComponent(pathname.split('?')[0]));
+        if (original === sourcePage) {
+            if (!fragment || !fragmentTargets.has(fragment))
+                return '';
+            return emitAttribute('href', `#${fragment}`);
+        }
+        let target = original;
+        if (original === resolve(options.projectPath, 'summary.md') &&
+            options.summaryExportPath)
+            target = resolve(options.repoRoot, options.summaryExportPath, `${basename(exportPage, '.html')}.md`);
+        const referenceRoot = resolve(options.repoRoot, '.oat/repo/reference');
+        const preserved = isInsidePath(referenceRoot, target) &&
+            !isInsidePath(resolve(referenceRoot, 'project-recaps'), target) &&
+            (await fileExists(target));
+        // This provisional link is removed from attempt-owned output if completion
+        // cannot verify the summary export; an adopted page is never rewritten.
+        const pendingSummary = original === resolve(options.projectPath, 'summary.md') &&
+            Boolean(options.summaryExportPath) &&
+            (await fileExists(original));
+        if (!preserved && !pendingSummary)
+            return '';
+        if (fragment) {
+            const contents = await readFile(preserved ? target : original, 'utf8');
+            const anchors = [...contents.matchAll(/^#+\s+(.+)$/gm)].map((heading) => heading[1]
+                .toLowerCase()
+                .replace(/[^\w\s-]/g, '')
+                .trim()
+                .replace(/\s+/g, '-'));
+            if (!anchors.includes(fragment) &&
+                !contents.includes(`id="${fragment}"`))
+                return '';
         }
-        if (exportedManifestContents !== sourceManifestContents) {
-            throw new CliError(`Existing project recap export \`${exportRoot}\` does not match persisted snapshot \`${snapshotName}\`.`);
+        return emitAttribute('href', `${relative(dirname(exportPage), target).split(sep).join('/')}${fragment ? `#${fragment}` : ''}`);
+    });
+    // Walk markup once. Comments and raw-text elements are opaque to attribute
+    // rewriting; generated script/style bodies are never fed back into the walk.
+    let output = '';
+    let cursor = 0;
+    let match;
+    markup.lastIndex = 0;
+    while ((match = markup.exec(html))) {
+        output += html.slice(cursor, match.index);
+        const tag = match[0];
+        const name = /^<([a-z][a-z0-9:-]*)/i.exec(tag)?.[1]?.toLowerCase();
+        cursor = markup.lastIndex;
+        if (!name) {
+            output += tag;
+            continue;
+        }
+        const values = attributes(tag);
+        if (name === 'link' && values.get('rel')?.toLowerCase() === 'stylesheet') {
+            const url = values.get('href');
+            if (url !== undefined && !external(url)) {
+                const file = await resolveAssetPath(url, sourcePage);
+                output += `<style>${await css(await readFile(join(stagedRoot, relative(sourceRunRoot, file)), 'utf8'), file)}</style>`;
+                continue;
+            }
+        }
+        if (rawText.test(name)) {
+            const closing = new RegExp(`</${name}\\s*>`, 'gi');
+            closing.lastIndex = cursor;
+            const end = name === 'plaintext' ? null : closing.exec(html);
+            let body = html.slice(cursor, end?.index ?? html.length);
+            let inlineScript = false;
+            const url = values.get('src');
+            if (name === 'script' &&
+                end &&
+                !body.trim() &&
+                url !== undefined &&
+                !external(url)) {
+                const file = await resolveAssetPath(url, sourcePage);
+                body = (await readFile(join(stagedRoot, relative(sourceRunRoot, file)), 'utf8')).replace(/<\/script/gi, '<\\/script');
+                inlineScript = true;
+            }
+            else if (name === 'style') {
+                body = await css(body, sourcePage);
+            }
+            output +=
+                (await rewriteAttributes(tag, inlineScript)) + body + (end?.[0] ?? '');
+            cursor = end ? closing.lastIndex : html.length;
+            markup.lastIndex = cursor;
         }
-        const exportedManifest = await parseProjectRecapManifest(exportedManifestContents);
-        const verifiedArtifactCount = await verifyProjectRecapImmutableHashes(exportRoot, exportedManifest);
-        const exactCoverage = (await loadExplainerPackageCoverage());
+        else {
+            output += await rewriteAttributes(tag);
+        }
+    }
+    return output + html.slice(cursor);
+}
+async function cleanupOwnedRecapPath(target, identity, removePath, renamePath, expectedHash) {
+    if (!(await pathExists(target)))
+        return;
+    // Claim into a private, exclusively created namespace before inspecting bytes.
+    // Other writers retain the original public pathname; deletion uses only our claim.
+    const claimRoot = await mkdtemp(join(dirname(target), '.recap-cleanup-claim-'));
+    const claimedPath = join(claimRoot, basename(target));
+    try {
+        await renamePath(target, claimedPath);
+    }
+    catch (error) {
+        await rm(claimRoot, { recursive: true, force: true });
+        if (isRecord(error) && error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    const stat = await lstat(claimedPath);
+    const owned = stat.dev === identity.dev &&
+        stat.ino === identity.ino &&
+        stat.birthtimeMs === identity.birthtimeMs &&
+        (expectedHash === undefined
+            ? stat.isDirectory()
+            : stat.isFile() && sha256(await readFile(claimedPath)) === expectedHash);
+    if (owned) {
+        await removePath(claimedPath, { recursive: true, force: true });
+        await rm(claimRoot, { recursive: true, force: true });
+        return;
+    }
+    if (stat.isFile()) {
         try {
-            await exactCoverage.enforceRunPackageInventory(exportRoot, exportedManifest);
+            // link is an atomic no-clobber restoration, even if a third writer arrives.
+            await link(claimedPath, target);
         }
-        catch {
-            throw new CliError(`Existing project recap export \`${exportRoot}\` has invalid content.`);
+        catch (error) {
+            throw new CliError(`Recap cleanup preserved foreign content at ${claimedPath}; refusing to overwrite ${target}: ${error instanceof Error ? error.message : String(error)}`);
         }
-        return {
-            export: {
-                sourceRunRoot,
-                exportRoot,
-                manifest: {
-                    relativePath: 'manifest.json',
-                    verifiedArtifactCount,
-                },
-            },
-            createdByAttempt: false,
-        };
+        await rm(claimedPath);
+        await rm(claimRoot, { recursive: true, force: true });
+        return;
     }
+    // Node has no portable atomic no-clobber rename for a directory. Keep its
+    // bytes in the diagnostic claim rather than overwriting any new public path.
+    throw new CliError(`Recap cleanup preserved a foreign replacement at ${claimedPath}; safe no-clobber directory restoration is unavailable for ${target}.`);
+}
+async function removeAttemptRecapExport(attempt, removePath, renamePath) {
+    if (!attempt?.createdByAttempt || !attempt.identity)
+        return;
+    await cleanupOwnedRecapPath(attempt.export.exportRoot, attempt.identity, removePath, renamePath, attempt.export.page.exportedSha256);
+}
+async function exportSelectedProjectRecap(options, snapshotName, dependencies) {
+    const selectedRun = options.projectRecapRun?.trim();
+    if (!selectedRun)
+        return null;
+    const verified = await loadVerifiedProjectRecap(options.projectPath, selectedRun);
+    if (verified.manifest.artifacts.length !== 1)
+        throw new CliError('Selected project recap must declare exactly one rendered HTML page.');
+    const pagePath = verified.manifest.artifacts[0].renderedPath ??
+        verified.manifest.artifacts[0].contentPath;
+    if (!pagePath.startsWith('site/') || !pagePath.endsWith('.html'))
+        throw new CliError('Selected project recap must declare a rendered HTML page.');
+    const exportRoot = join(options.repoRoot, '.oat/repo/reference/project-recaps', `${snapshotName}.html`);
     const temporaryRoot = `${exportRoot}.tmp-${randomUUID()}`;
     const makeDir = dependencies.ensureDir ?? ensureDir;
     const copyFile = dependencies.copySingleFile ?? copySingleFile;
     const removePath = dependencies.removePath ??
         (async (target, removeOptions) => rm(target, removeOptions));
-    const renamePath = dependencies.renamePath ?? rename;
     await makeDir(dirname(exportRoot));
+    await mkdir(temporaryRoot);
+    const temporaryIdentity = await lstat(temporaryRoot);
     try {
-        for (const relativePath of packagePaths) {
-            const destination = join(temporaryRoot, relativePath);
-            await makeDir(dirname(destination));
-            await copyFile(join(sourceRunRoot, relativePath), destination);
-        }
-        const stagedManifestContents = await readFile(join(temporaryRoot, 'manifest.json'), 'utf8');
-        if (stagedManifestContents !== sourceManifestContents) {
-            throw new CliError('Selected project recap manifest changed while staging the export.');
+        // Stage and re-verify the complete source, even though only its page is exported.
+        for (const file of verified.packagePaths) {
+            await makeDir(dirname(join(temporaryRoot, file)));
+            await copyFile(join(verified.sourceRunRoot, file), join(temporaryRoot, file));
         }
-        const stagedManifest = await parseProjectRecapManifest(stagedManifestContents);
-        const verifiedArtifactCount = await verifyProjectRecapImmutableHashes(temporaryRoot, stagedManifest);
-        const exactCoverage = (await loadExplainerPackageCoverage());
-        try {
-            await exactCoverage.enforceRunPackageInventory(temporaryRoot, stagedManifest);
-        }
-        catch {
-            throw new CliError('Staged project recap package inventory is invalid.');
+        if ((await readFile(join(temporaryRoot, 'manifest.json'), 'utf8')) !==
+            verified.manifestContents)
+            throw new CliError('Selected recap manifest changed while staging the export.');
+        await verifyProjectRecapImmutableHashes(temporaryRoot, verified.manifest);
+        await verifyRecapInventory(temporaryRoot, verified.packagePaths);
+        const original = await readFile(join(temporaryRoot, pagePath));
+        const transformed = await transformRecapPage(original.toString('utf8'), join(verified.sourceRunRoot, pagePath), verified.sourceRunRoot, temporaryRoot, exportRoot, options);
+        const report = {
+            sourceRunRoot: verified.sourceRunRoot,
+            exportRoot,
+            runId: verified.manifest.runId,
+            page: {
+                sourceRelativePath: pagePath,
+                originalSha256: sha256(original),
+                exportedSha256: sha256(transformed),
+            },
+            verifiedArtifactCount: verified.verifiedArtifactCount,
+        };
+        if (await pathExists(exportRoot)) {
+            const stat = await lstat(exportRoot);
+            if (stat.isFile()) {
+                const existingHash = sha256(await readFile(exportRoot));
+                if (existingHash !== report.page.exportedSha256 &&
+                    options.summaryExportPath) {
+                    // A warning-only completion may have published this verified package
+                    // without its unavailable summary link. Preserve that page on retry,
+                    // including when the summary destination has since been repaired.
+                    const withoutSummary = await transformRecapPage(original.toString('utf8'), join(verified.sourceRunRoot, pagePath), verified.sourceRunRoot, temporaryRoot, exportRoot, { ...options, summaryExportPath: null });
+                    if (sha256(withoutSummary) === existingHash)
+                        report.page.exportedSha256 = existingHash;
+                }
+                if (existingHash === report.page.exportedSha256)
+                    return { export: report, createdByAttempt: false };
+            }
+            throw new CliError(`Existing project recap export ${exportRoot} already exists and does not match persisted snapshot ${snapshotName}.`);
         }
-        await renamePath(temporaryRoot, exportRoot);
+        const temporaryPage = join(temporaryRoot, 'export.html');
+        await writeFile(temporaryPage, transformed, { flag: 'wx' });
+        // A hard-link promotion is atomic and refuses an intervening writer, unlike rename.
+        await link(temporaryPage, exportRoot);
+        const identity = await lstat(temporaryPage);
         return {
-            export: {
-                sourceRunRoot,
-                exportRoot,
-                manifest: {
-                    relativePath: 'manifest.json',
-                    verifiedArtifactCount,
-                },
-            },
+            export: report,
             createdByAttempt: true,
+            identity: {
+                dev: identity.dev,
+                ino: identity.ino,
+                birthtimeMs: identity.birthtimeMs,
+            },
         };
     }
-    catch (error) {
-        await removePath(temporaryRoot, { recursive: true, force: true });
-        throw error;
+    finally {
+        await cleanupOwnedRecapPath(temporaryRoot, temporaryIdentity, removePath, dependencies.renamePath ?? rename);
     }
 }
 export async function archiveProjectOnCompletion(options, dependencies = {}) {
@@ -854,8 +1261,8 @@ export async function archiveProjectOnCompletion(options, dependencies = {}) {
     const projectSourcePath = (await pathExists(options.projectPath))
         ? options.projectPath
         : archivePath;
-    const attemptedProjectRecapExport = await exportSelectedProjectRecap({ ...options, projectPath: projectSourcePath }, exportIdentity, dependencies);
-    const projectRecapExport = attemptedProjectRecapExport?.export ?? null;
+    let attemptedProjectRecapExport = await exportSelectedProjectRecap({ ...options, projectPath: projectSourcePath }, exportIdentity, dependencies);
+    let projectRecapExport = attemptedProjectRecapExport?.export ?? null;
     if (!archiveExists) {
         try {
             await makeDir(dirname(archivePath));
@@ -870,47 +1277,57 @@ export async function archiveProjectOnCompletion(options, dependencies = {}) {
         }
         catch (error) {
             await removePath(archivePath, { recursive: true, force: true });
-            if (attemptedProjectRecapExport?.createdByAttempt) {
-                await removePath(attemptedProjectRecapExport.export.exportRoot, {
-                    recursive: true,
-                    force: true,
-                });
-            }
+            await removeAttemptRecapExport(attemptedProjectRecapExport, removePath, dependencies.renamePath ?? rename);
             throw error;
         }
     }
     try {
+        if (projectRecapExport && options.projectRecapRun) {
+            const archivedRecap = await loadVerifiedProjectRecap(archivePath, options.projectRecapRun);
+            const archivedPage = projectRecapExport.page.sourceRelativePath;
+            if (archivedRecap.manifest.runId !== projectRecapExport.runId ||
+                sha256(await readFile(join(archivedRecap.sourceRunRoot, archivedPage))) !== projectRecapExport.page.originalSha256) {
+                throw new CliError('Archived recap identity differs from the verified exported page.');
+            }
+        }
         if (!syncTarget) {
             await removePath(options.projectPath, { recursive: true, force: true });
         }
     }
     catch (error) {
-        if (attemptedProjectRecapExport?.createdByAttempt) {
-            await removePath(attemptedProjectRecapExport.export.exportRoot, {
-                recursive: true,
-                force: true,
-            });
-        }
+        await removeAttemptRecapExport(attemptedProjectRecapExport, removePath, dependencies.renamePath ?? rename);
         throw error;
     }
     const warnings = [];
     let summaryExportFile = null;
     if (options.summaryExportPath) {
         try {
-            summaryExportFile = await exportProjectSummary(archivePath, exportIdentity, options.summaryExportPath, options.repoRoot, dependencies);
+            summaryExportFile = await exportProjectSummary(archivePath, exportIdentity, options.summaryExportPath, options.repoRoot, dependencies, projectRecapExport);
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
+            const summaryFailure = `Summary export to \`${options.summaryExportPath}\` failed: ${message}`;
             if (syncTarget) {
-                if (attemptedProjectRecapExport?.createdByAttempt) {
-                    await removePath(attemptedProjectRecapExport.export.exportRoot, {
-                        recursive: true,
-                        force: true,
-                    });
+                await removeAttemptRecapExport(attemptedProjectRecapExport, removePath, dependencies.renamePath ?? rename);
+                throw new CliError(summaryFailure, 1);
+            }
+            warnings.push(summaryFailure);
+            if (attemptedProjectRecapExport) {
+                // Rebuild only through the existing identity/hash-aware cleanup and
+                // no-clobber publisher. Adopted or foreign linked output is preserved
+                // and refused if it differs from the required link-free page.
+                try {
+                    await removeAttemptRecapExport(attemptedProjectRecapExport, removePath, dependencies.renamePath ?? rename);
+                    attemptedProjectRecapExport = await exportSelectedProjectRecap({ ...options, projectPath: archivePath, summaryExportPath: null }, exportIdentity, dependencies);
+                    projectRecapExport = attemptedProjectRecapExport?.export ?? null;
+                }
+                catch (repairError) {
+                    const repairMessage = repairError instanceof Error
+                        ? repairError.message
+                        : String(repairError);
+                    throw new CliError(`${summaryFailure}\nRecap repair without the summary link failed: ${repairMessage}\nRepair the summary destination \`${options.summaryExportPath}\` and retry archive completion.`, repairError instanceof CliError ? repairError.exitCode : 2);
                 }
-                throw new CliError(`Summary export to \`${options.summaryExportPath}\` failed: ${message}`, 1);
             }
-            warnings.push(`Summary export to \`${options.summaryExportPath}\` failed: ${message}`);
         }
     }
     let s3Path = null;
@@ -973,8 +1390,7 @@ export async function archiveProjectOnCompletion(options, dependencies = {}) {
             throw new CliError(`Synced checkout became ${removed.status} during archive; run oat project push ${options.projectName} and retry.`, 1);
         }
         if (projectRecapExport) {
-            recapExportPaths = (await listArchiveExportFiles(projectRecapExport.exportRoot)).filter((filePath) => basename(filePath) !== 'manifest.json' &&
-                basename(filePath) !== 'build-record.json');
+            recapExportPaths = [projectRecapExport.exportRoot];
         }
         await (dependencies.removeSyncedRecord
             ? dependencies.removeSyncedRecord(recordPath)
@@ -1057,16 +1473,6 @@ async function recoverSyncedLifecycleCommit(repoRoot, pathspecs, projectName, ex
     }
     return candidate;
 }
-async function listArchiveExportFiles(root, current = root) {
-    const entries = await readdir(current, { withFileTypes: true });
-    const files = await Promise.all(entries.map(async (entry) => {
-        const entryPath = join(current, entry.name);
-        return entry.isDirectory()
-            ? listArchiveExportFiles(root, entryPath)
-            : [entryPath];
-    }));
-    return files.flat().sort();
-}
 export async function ensureS3ArchiveAccess(options, dependencies = {}) {
     if (!requiresRemoteAccess(options)) {
         return { ok: true, warnings: [] };