@lesliechan721/aw 0.1.0-beta.4 → 0.1.0-beta.40

package/dist/src/commands/catalog-publish.js

@@ -1,374 +1,804 @@
 import crypto from 'node:crypto';
-import { execFile } from 'node:child_process';
 import os from 'node:os';
 import path from 'node:path';
-import { promisify } from 'node:util';
 import fs from 'fs-extra';
-import { assertStrictSemVer, preparePublishedWorkspaceCatalog, readPluginWorkspace, validatePublishedCatalogSnapshot, } from '@lesliechan721/aw-plugin-core';
-import { bundleLocalPlugin, createCatalogRuntimeImportResolver } from '../../scripts/plugin-staging.js';
-import { CLI_RESERVED_IMPORTS } from '../utils/manifest.js';
-import { resolveCliPackageRoot } from '../utils/paths.js';
-const execFileAsync = promisify(execFile);
-const LEGACY_ATTEMPTED_MARKER = path.join('.aw', 'publish', 'attempted.json');
-const INHERITED_GIT_AUTH_ENV = new Set([
-    'GIT_ASKPASS',
-    'GIT_HTTP_USER_AGENT',
-    'GIT_SSH',
-    'GIT_SSH_COMMAND',
-    'GIT_SSH_VARIANT',
-    'GIT_SSL_CAINFO',
-    'GIT_SSL_NO_VERIFY',
-    'GIT_TERMINAL_PROMPT',
-]);
-function digest(value) {
-    return `sha256:${crypto.createHash('sha256').update(value).digest('hex')}`;
+import { GENERATED_OUTPUT_MARKER_FILENAME, validatePublishedCatalogSnapshot, } from '@lesliechan721/aw-plugin-core';
+import { disposeCatalogPublicationInspection, inspectCatalogPublicationApplyContext, inspectCatalogPublicationLiveContext, parseRemoteRefs, prepareCatalogPublicationInspection, publicationGit, publicationGitExit, readCatalogPublicationBranchState, } from './catalog-publication-inspection.js';
+import { catalogPublicationDirectoryPath, catalogPublicationJournalPath, catalogPublicationPlanDigest, catalogPublicationRepositoryName, catalogPublicationRepositoryPath, findCatalogPublicationJournalByPlanDigest, readCatalogPublicationJournal, writeCatalogPublicationJournalAtomic, } from './catalog-publication-journal.js';
+import { resolveCatalogPublicationTarget, } from './catalog-publication-target.js';
+import { resolveCatalogWorkspaceRoot, } from './catalog-workspace-resolution.js';
+export { catalogPublicationPlanDigest, parseCatalogPublicationJournal, } from './catalog-publication-journal.js';
+export { safeRemoteIdentity, sanitizedGitEnvironment } from './catalog-publication-inspection.js';
+export const CATALOG_PUBLICATION_CLEANUP_WARNING = 'Catalog publication succeeded, but local repository cleanup did not complete. Retry apply with the same plan digest.';
+async function assertPublicationStatePathSafe(workspaceRoot) {
+    for (const candidate of [
+        path.join(workspaceRoot, '.aw'),
+        path.join(workspaceRoot, '.aw', 'publish'),
+    ]) {
+        if (!(await fs.pathExists(candidate)))
+            continue;
+        const stats = await fs.lstat(candidate);
+        if (!stats.isDirectory() || stats.isSymbolicLink()) {
+            throw new Error('Catalog publication state path must contain only regular local directories.');
+        }
+    }
 }
-export function sanitizedGitEnvironment(source) {
-    return Object.fromEntries(Object.entries(source).filter(([key]) => !key.startsWith('GIT_') || INHERITED_GIT_AUTH_ENV.has(key)));
+async function assertPublicationDirectorySafe(directoryPath, catalogVersion) {
+    let stats;
+    try {
+        stats = await fs.lstat(directoryPath);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+    if (!stats.isDirectory() || stats.isSymbolicLink()) {
+        throw new Error(`Catalog ${catalogVersion} publication state directory is damaged. Increase the Catalog version.`);
+    }
+    return true;
 }
-export function safeRemoteIdentity(value) {
-    if (/^[a-z][a-z\d+.-]*:\/\//iu.test(value)) {
-        try {
-            const url = new URL(value);
-            url.username = '';
-            url.password = '';
-            url.search = '';
-            url.hash = '';
-            return url.toString();
-        }
-        catch {
-            // Fall through to conservative display sanitization for malformed URLs.
+function sameDescriptor(left, right) {
+    const comparisonCommit = '0'.repeat(40);
+    return catalogPublicationPlanDigest(left, comparisonCommit)
+        === catalogPublicationPlanDigest(right, comparisonCommit);
+}
+async function clearWorktree(repositoryRoot) {
+    for (const name of await fs.readdir(repositoryRoot)) {
+        if (name !== '.git')
+            await fs.remove(path.join(repositoryRoot, name));
+    }
+}
+async function assertNoGitAttributes(root, relative = '') {
+    for (const entry of await fs.readdir(path.join(root, relative), { withFileTypes: true })) {
+        const child = relative ? path.posix.join(relative, entry.name) : entry.name;
+        if (entry.name === '.gitattributes') {
+            throw new Error(`Catalog publication snapshot must not contain .gitattributes (${child}).`);
         }
+        if (entry.isDirectory())
+            await assertNoGitAttributes(root, child);
+    }
+}
+async function assertSnapshotBinding(snapshotRoot, descriptor, display) {
+    const markerPath = path.join(snapshotRoot, GENERATED_OUTPUT_MARKER_FILENAME);
+    const [stats, markerStats] = await Promise.all([
+        fs.lstat(snapshotRoot),
+        fs.lstat(markerPath),
+    ]);
+    if (!stats.isDirectory() || stats.isSymbolicLink()) {
+        throw new Error('Prepared Catalog snapshot must be a regular local directory.');
+    }
+    if (!markerStats.isFile() || markerStats.isSymbolicLink()) {
+        throw new Error('Prepared Catalog snapshot marker must be a regular local file.');
     }
-    const withoutQuery = value.split(/[?#]/u, 1)[0];
-    return withoutQuery
-        .replace(/^([^/@\s:]+):([^/@\s]+)@/u, '')
-        .replace(/^[^@\s]+@(?=[^:/\s]+[/:])/u, '');
+    const [marker, validation] = await Promise.all([
+        fs.readJson(markerPath),
+        validatePublishedCatalogSnapshot(snapshotRoot),
+    ]);
+    const release = validation.manifest.release;
+    if (marker.workspaceIdentity !== descriptor.workspaceIdentity
+        || validation.manifest.catalogVersion !== display.catalogVersion
+        || validation.manifest.channel !== display.channel
+        || validation.manifest.entries.length !== display.pluginCount
+        || validation.snapshotDigest !== descriptor.snapshotDigest
+        || release.state !== 'published'
+        || release.sourceHead !== descriptor.sourceHead) {
+        throw new Error('Prepared Catalog descriptor, snapshot, or plan identity changed.');
+    }
+    await assertNoGitAttributes(snapshotRoot);
 }
-function attemptPath(workspaceRoot, catalogVersion) {
-    return path.join(workspaceRoot, '.aw', 'publish', 'attempts', `${catalogVersion}.json`);
+function displayFromPreparation(preparation) {
+    return {
+        catalogVersion: preparation.prepared.catalogVersion,
+        channel: preparation.prepared.channel,
+        pluginCount: preparation.prepared.pluginNames.length,
+    };
 }
-async function migrateLegacyAttempt(workspaceRoot, catalogVersion) {
-    const legacyPath = path.join(workspaceRoot, LEGACY_ATTEMPTED_MARKER);
-    if (!(await fs.pathExists(legacyPath)))
-        return;
-    let recordedVersion = catalogVersion;
-    try {
-        const legacy = await fs.readJson(legacyPath);
-        if (legacy.schemaVersion === 1 && typeof legacy.catalogVersion === 'string') {
-            recordedVersion = assertStrictSemVer(legacy.catalogVersion, 'legacy attempted Catalog version');
-        }
+function assertLiveContextMatchesDescriptor(context, descriptor) {
+    if (context.workspaceIdentity !== descriptor.workspaceIdentity
+        || context.sourceHead !== descriptor.sourceHead
+        || context.remoteName !== descriptor.remote.name
+        || context.remoteIdentityDigest !== descriptor.remote.identityDigest
+        || context.branch !== descriptor.branch
+        || context.tag !== descriptor.tag) {
+        throw new Error('Catalog publication identity changed. Increase the Catalog version and create a new plan.');
     }
-    catch {
-        // Bind an unreadable legacy marker to the current version. A later version uses a new file.
+}
+function assertApplyContextMatchesDescriptor(context, descriptor) {
+    if (context.workspaceIdentity !== descriptor.workspaceIdentity
+        || context.remoteIdentityDigest !== descriptor.remote.identityDigest
+        || context.branch !== descriptor.branch) {
+        throw new Error('Catalog publication identity changed. Increase the Catalog version and create a new plan.');
     }
-    const destination = attemptPath(workspaceRoot, recordedVersion);
-    await fs.ensureDir(path.dirname(destination));
-    if (await fs.pathExists(destination))
-        return;
-    await fs.rename(legacyPath, destination);
 }
-async function git(cwd, args, env, label) {
-    try {
-        const result = await execFileAsync('git', [...args], {
-            cwd,
-            env,
-            encoding: 'utf8',
-            maxBuffer: 16 * 1024 * 1024,
-        });
-        return result.stdout.trim();
+async function createPublicationCommit(preparation, descriptor, snapshotRoot, display) {
+    const { repositoryRoot, parent, tag, env } = preparation;
+    await assertSnapshotBinding(snapshotRoot, descriptor, display);
+    if (parent) {
+        await publicationGit(repositoryRoot, [
+            'checkout', '--quiet', '--detach', 'refs/aw/catalog-parent',
+        ], env, 'publicationCommitFailed', 'Could not select the publication parent.');
     }
-    catch (error) {
-        throw new Error(label, { cause: error });
+    else {
+        await publicationGit(repositoryRoot, [
+            'checkout', '--quiet', '--orphan', 'catalog-publication',
+        ], env, 'publicationCommitFailed', 'Could not create the initial Catalog publication.');
     }
+    await clearWorktree(repositoryRoot);
+    await fs.copy(snapshotRoot, repositoryRoot, { dereference: false });
+    await publicationGit(repositoryRoot, [
+        'add', '--force', '--all',
+    ], env, 'publicationCommitFailed', 'Could not stage the Catalog publication tree.');
+    await publicationGit(repositoryRoot, [
+        '-c', 'user.name=AW Catalog Publisher',
+        '-c', 'user.email=catalog-publisher@agent-workflows.invalid',
+        'commit', '--quiet', '-m', `Catalog ${display.catalogVersion}`,
+    ], env, 'publicationCommitFailed', 'Could not create the Catalog publication commit.');
+    const commit = await publicationGit(repositoryRoot, [
+        'rev-parse', 'HEAD',
+    ], env, 'publicationCommitFailed', 'Could not resolve the Catalog publication commit.');
+    const parents = (await publicationGit(repositoryRoot, [
+        'show', '-s', '--format=%P', commit,
+    ], env, 'publicationCommitFailed', 'Could not verify the Catalog publication parent.'))
+        .split(/\s+/u)
+        .filter(Boolean);
+    if ((parent && (parents.length !== 1 || parents[0] !== parent)) || (!parent && parents.length !== 0)) {
+        throw new Error('Catalog publication commit has an invalid parent.');
+    }
+    const verificationRoot = path.join(preparation.temporaryRoot, 'verification');
+    await fs.ensureDir(verificationRoot);
+    await publicationGit(repositoryRoot, [
+        '--work-tree', verificationRoot, 'checkout', '--quiet', commit, '--', '.',
+    ], env, 'publicationCommitFailed', 'Could not verify the Catalog publication commit tree.');
+    await assertSnapshotBinding(verificationRoot, descriptor, display);
+    await publicationGit(repositoryRoot, [
+        '-c', 'user.name=AW Catalog Publisher',
+        '-c', 'user.email=catalog-publisher@agent-workflows.invalid',
+        'tag', '--annotate', tag, '--message', `Catalog ${display.catalogVersion}`,
+    ], env, 'publicationCommitFailed', 'Could not create the annotated Catalog tag.');
+    return commit;
 }
-async function gitExit(cwd, args, env) {
-    try {
-        await execFileAsync('git', [...args], { cwd, env, encoding: 'utf8' });
-        return true;
+async function remoteRefState(cwd, remote, branchRef, tagRef, env) {
+    const refs = parseRemoteRefs(await publicationGit(cwd, [
+        'ls-remote', remote, branchRef, tagRef, `${tagRef}^{}`,
+    ], env, 'remoteReadFailed', 'Could not inspect the Catalog publication remote.'));
+    const tagPresent = refs.has(tagRef) || refs.has(`${tagRef}^{}`);
+    return {
+        branchCommit: refs.get(branchRef) ?? null,
+        tagCommit: refs.get(`${tagRef}^{}`) ?? null,
+        tagPresent,
+        tagAnnotated: refs.has(tagRef) && refs.has(`${tagRef}^{}`),
+    };
+}
+function assertReconciliableRemoteState(state, journal) {
+    const branchAtExpected = state.branchCommit === journal.expectedCommit;
+    const branchAtParent = state.branchCommit === journal.descriptor.parent;
+    const tagAtExpected = state.tagAnnotated && state.tagCommit === journal.expectedCommit;
+    const tagAbsent = !state.tagPresent;
+    if ((branchAtExpected && tagAtExpected)
+        || (branchAtParent && tagAbsent)
+        || (branchAtExpected && tagAbsent)
+        || (branchAtParent && tagAtExpected))
+        return;
+    throw new Error(`Catalog ${journal.display.catalogVersion} remote refs conflict with the prepared plan. Increase the Catalog version.`);
+}
+const PERSISTED_REPOSITORY_CONFIG = new Map([
+    ['core.repositoryformatversion', new Set(['0'])],
+    ['core.filemode', new Set(['true', 'false'])],
+    ['core.bare', new Set(['false'])],
+    ['core.logallrefupdates', new Set(['true'])],
+    ['core.ignorecase', new Set(['true'])],
+    ['core.precomposeunicode', new Set(['true'])],
+    ['core.hookspath', new Set([os.devNull])],
+    ['core.symlinks', new Set(['true'])],
+]);
+const REQUIRED_PERSISTED_REPOSITORY_CONFIG = [
+    'core.repositoryformatversion',
+    'core.filemode',
+    'core.bare',
+    'core.logallrefupdates',
+    'core.hookspath',
+    'core.symlinks',
+];
+async function assertRegularGitDirectory(root) {
+    const stats = await fs.lstat(root);
+    if (!stats.isDirectory() || stats.isSymbolicLink()) {
+        throw new Error('Pending Catalog publication Git directory is unsafe.');
     }
-    catch {
-        return false;
+}
+async function assertRegularGitFile(filePath) {
+    const stats = await fs.lstat(filePath);
+    if (!stats.isFile() || stats.isSymbolicLink()) {
+        throw new Error('Pending Catalog publication Git control file is unsafe.');
     }
 }
-function parseRemoteRefs(output) {
-    return new Map(output.split('\n').filter(Boolean).map((line) => {
-        const [objectId, ref] = line.split(/\s+/u);
-        return [ref, objectId];
-    }));
+async function assertGitTreeContainsOnlyLocalFiles(root) {
+    for (const entry of await fs.readdir(root, { withFileTypes: true })) {
+        const child = path.join(root, entry.name);
+        const stats = await fs.lstat(child);
+        if (stats.isSymbolicLink()) {
+            throw new Error('Pending Catalog publication Git data must not contain symbolic links.');
+        }
+        if (stats.isDirectory()) {
+            await assertGitTreeContainsOnlyLocalFiles(child);
+        }
+        else if (!stats.isFile()) {
+            throw new Error('Pending Catalog publication Git data must contain only regular local files.');
+        }
+    }
 }
-async function writeJsonAtomic(filePath, value) {
-    await fs.ensureDir(path.dirname(filePath));
-    const temporary = path.join(path.dirname(filePath), `.${path.basename(filePath)}.${crypto.randomUUID()}.tmp`);
-    await fs.writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { flag: 'wx', mode: 0o600 });
+async function assertPathMissing(filePath) {
     try {
-        await fs.rename(temporary, filePath);
+        await fs.lstat(filePath);
     }
     catch (error) {
-        await fs.remove(temporary);
+        if (error.code === 'ENOENT')
+            return;
         throw error;
     }
+    throw new Error('Pending Catalog publication repository must not use alternate object stores.');
 }
-async function clearWorktree(repositoryRoot) {
-    for (const name of await fs.readdir(repositoryRoot)) {
-        if (name !== '.git')
-            await fs.remove(path.join(repositoryRoot, name));
+async function validatePersistentRepositoryControlState(repositoryRoot, env) {
+    const gitRoot = path.join(repositoryRoot, '.git');
+    const configPath = path.join(gitRoot, 'config');
+    await assertRegularGitDirectory(gitRoot);
+    await assertRegularGitFile(configPath);
+    await assertRegularGitFile(path.join(gitRoot, 'HEAD'));
+    await assertRegularGitFile(path.join(gitRoot, 'index'));
+    await assertRegularGitDirectory(path.join(gitRoot, 'objects'));
+    await assertRegularGitDirectory(path.join(gitRoot, 'refs'));
+    await assertPathMissing(path.join(gitRoot, 'objects', 'info', 'alternates'));
+    await assertPathMissing(path.join(gitRoot, 'objects', 'info', 'http-alternates'));
+    await assertGitTreeContainsOnlyLocalFiles(gitRoot);
+    const entries = (await publicationGit(repositoryRoot, [
+        'config', '--file', configPath, '--no-includes', '--null', '--list',
+    ], env, 'pendingRepositoryInvalid', 'Pending Catalog publication config is damaged.'))
+        .split('\0')
+        .filter(Boolean);
+    const seen = new Set();
+    for (const entry of entries) {
+        const separator = entry.indexOf('\n');
+        if (separator <= 0)
+            throw new Error('Pending Catalog publication config is damaged.');
+        const key = entry.slice(0, separator).toLowerCase();
+        const value = entry.slice(separator + 1);
+        if (seen.has(key) || !PERSISTED_REPOSITORY_CONFIG.get(key)?.has(value)) {
+            throw new Error('Pending Catalog publication config contains unsafe local settings.');
+        }
+        seen.add(key);
+    }
+    if (REQUIRED_PERSISTED_REPOSITORY_CONFIG.some((key) => !seen.has(key))) {
+        throw new Error('Pending Catalog publication config is incomplete.');
     }
 }
-async function materializeSourceHead(options) {
-    const archivePath = path.join(options.temporaryRoot, 'source-head.tar');
-    await fs.ensureDir(options.outputRoot);
-    await git(options.repoRoot, [
-        'archive', '--format=tar', `--output=${archivePath}`, options.sourceHead,
-    ], options.env, 'Could not archive the committed source HEAD.');
-    const tarEnv = { ...options.env };
-    delete tarEnv.TAR_OPTIONS;
+async function validatePersistentRepository(repositoryRoot, journal, env) {
+    const version = journal.display.catalogVersion;
+    let stats;
     try {
-        await execFileAsync('tar', ['-xf', archivePath, '-C', options.outputRoot], {
-            env: tarEnv,
-            encoding: 'utf8',
-            maxBuffer: 16 * 1024 * 1024,
-        });
+        stats = await fs.lstat(repositoryRoot);
     }
     catch (error) {
-        throw new Error('Could not materialize the committed source HEAD.', { cause: error });
+        throw new Error(`Catalog ${version} pending publication repository is missing or damaged. Increase the Catalog version.`, { cause: error });
     }
-    finally {
-        await fs.remove(archivePath);
+    if (!stats.isDirectory() || stats.isSymbolicLink()) {
+        throw new Error(`Catalog ${version} pending publication repository is missing or damaged. Increase the Catalog version.`);
     }
-}
-async function validatePublishedSourceWorkspace(workspace, env) {
-    const validator = path.join(resolveCliPackageRoot(), 'dist', 'authoring', 'scripts', 'validate-plugin.mjs');
-    for (const plugin of workspace.plugins) {
+    try {
+        await validatePersistentRepositoryControlState(repositoryRoot, env);
+        const [head, tagCommit, tagType, remotes, parents] = await Promise.all([
+            publicationGit(repositoryRoot, ['rev-parse', '--verify', 'HEAD'], env, 'pendingRepositoryInvalid', 'Pending Catalog publication repository is damaged.'),
+            publicationGit(repositoryRoot, ['rev-parse', `${journal.descriptor.tag}^{commit}`], env, 'pendingRepositoryInvalid', 'Pending Catalog publication tag is damaged.'),
+            publicationGit(repositoryRoot, ['cat-file', '-t', `refs/tags/${journal.descriptor.tag}`], env, 'pendingRepositoryInvalid', 'Pending Catalog publication tag is damaged.'),
+            publicationGit(repositoryRoot, ['remote'], env, 'pendingRepositoryInvalid', 'Pending Catalog publication repository is damaged.'),
+            publicationGit(repositoryRoot, ['show', '-s', '--format=%P', journal.expectedCommit], env, 'pendingRepositoryInvalid', 'Pending Catalog publication commit is damaged.'),
+        ]);
+        const parentList = parents.split(/\s+/u).filter(Boolean);
+        if (head !== journal.expectedCommit
+            || tagCommit !== journal.expectedCommit
+            || tagType !== 'tag'
+            || remotes !== ''
+            || (journal.descriptor.parent === null
+                ? parentList.length !== 0
+                : parentList.length !== 1 || parentList[0] !== journal.descriptor.parent))
+            throw new Error('Pending Catalog publication repository identity changed.');
+        const verificationRoot = path.join(path.dirname(repositoryRoot), `.${path.basename(repositoryRoot)}.${crypto.randomUUID()}.verify`);
         try {
-            await execFileAsync(process.execPath, [
-                validator,
-                plugin.rootDir,
-                '--workspace-root', workspace.workspaceRoot,
-                '--json',
-            ], {
-                cwd: workspace.workspaceRoot,
-                env,
-                encoding: 'utf8',
-                maxBuffer: 16 * 1024 * 1024,
-            });
+            await fs.ensureDir(verificationRoot);
+            await publicationGit(repositoryRoot, [
+                '--work-tree', verificationRoot, 'checkout', '--quiet', journal.expectedCommit, '--', '.',
+            ], env, 'pendingRepositoryInvalid', 'Pending Catalog publication commit tree is damaged.');
+            await assertSnapshotBinding(verificationRoot, journal.descriptor, journal.display);
         }
-        catch (error) {
-            let details = '';
-            if (typeof error === 'object' && error !== null && 'stdout' in error && typeof error.stdout === 'string') {
-                try {
-                    const result = JSON.parse(error.stdout);
-                    details = (result.errors ?? [])
-                        .map((entry) => typeof entry.message === 'string' ? entry.message : '')
-                        .filter(Boolean)
-                        .join('; ');
-                }
-                catch {
-                    // Keep the public validator failure bounded to its plugin identity.
-                }
-            }
-            throw new Error(`Plugin ${plugin.manifest.name} failed public source validation before Catalog publication${details ? `: ${details}` : '.'}`);
+        finally {
+            await fs.remove(verificationRoot);
         }
     }
+    catch (error) {
+        throw new Error(`Catalog ${version} pending publication repository is missing or damaged. Increase the Catalog version.`, { cause: error });
+    }
 }
-const publishBuildAdapter = {
-    async build(options) {
-        await bundleLocalPlugin(options.plugin, options.outputRoot, {
-            buildMode: 'staging',
-            runtimeResolver: createCatalogRuntimeImportResolver(options.plugins),
-        });
-    },
-};
-export async function runCatalogPublishCommand(options) {
-    if (options.json && !options.yes)
-        throw new Error('Catalog publish with --json requires --yes.');
-    if (!options.interactive && !options.yes)
-        throw new Error('Non-interactive Catalog publish requires --yes.');
-    const remote = options.remote ?? 'origin';
-    const branch = options.branch ?? 'catalog';
-    const env = sanitizedGitEnvironment(options.env);
-    const workspaceRoot = await fs.realpath(path.resolve(options.workspaceRoot));
-    const repoRoot = await git(workspaceRoot, ['rev-parse', '--show-toplevel'], env, 'Workspace must be inside a real Git worktree.');
-    const sourceHead = await git(repoRoot, ['rev-parse', '--verify', 'HEAD'], env, 'Workspace Git HEAD must be committed and not unborn.');
-    const status = await git(repoRoot, [
-        'status', '--porcelain=v1', '--untracked-files=all', '--ignore-submodules=none',
-    ], env, 'Could not inspect the source worktree.');
-    if (status !== '')
-        throw new Error('Catalog publish requires the complete source Git worktree to be clean.');
-    const temporaryRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'aw-public-catalog-'));
-    let fetchUrl = '';
-    let pushUrl = '';
-    let safeFetchUrl = '';
-    let safePushUrl = '';
+async function persistPublicationState(preparation, finalStateRoot, journal, hooks) {
+    const parent = path.dirname(finalStateRoot);
+    await fs.ensureDir(parent);
+    const staging = path.join(parent, `.${path.basename(finalStateRoot)}.${crypto.randomUUID()}.tmp`);
+    const repositoryPath = path.join(staging, catalogPublicationRepositoryName());
+    const journalPath = path.join(staging, 'journal.json');
     try {
-        const sourceRoot = path.join(temporaryRoot, 'source');
-        await materializeSourceHead({ repoRoot, sourceHead, outputRoot: sourceRoot, temporaryRoot, env });
-        const workspaceRelative = path.relative(repoRoot, workspaceRoot);
-        if (workspaceRelative === '..' || workspaceRelative.startsWith(`..${path.sep}`) || path.isAbsolute(workspaceRelative)) {
-            throw new Error('Catalog workspace must stay inside its Git worktree root.');
+        await publicationGit(preparation.repositoryRoot, [
+            'remote', 'remove', 'publish',
+        ], preparation.env, 'temporaryRepositoryFailed', 'Could not seal the publication repository.');
+        await fs.ensureDir(staging);
+        await fs.copy(preparation.repositoryRoot, repositoryPath, { dereference: false, errorOnExist: true });
+        await writeCatalogPublicationJournalAtomic(journalPath, journal);
+        const persisted = await readCatalogPublicationJournal(journalPath, journal.display.catalogVersion);
+        if (!persisted || persisted.planDigest !== journal.planDigest) {
+            throw new Error(`Catalog ${journal.display.catalogVersion} publication state could not be verified.`);
         }
-        const sourceWorkspaceRoot = path.join(sourceRoot, workspaceRelative);
-        await git(repoRoot, ['check-ref-format', '--branch', branch], env, 'Invalid Catalog publication branch name.');
-        const workspace = await readPluginWorkspace(sourceWorkspaceRoot, { reservedImports: CLI_RESERVED_IMPORTS });
-        await validatePublishedSourceWorkspace(workspace, env);
-        const catalogVersion = workspace.metadata.catalog.version;
-        const tag = `catalog-v${catalogVersion}`;
-        await git(repoRoot, ['check-ref-format', `refs/tags/${tag}`], env, 'Invalid Catalog publication tag.');
-        const markerPath = attemptPath(workspaceRoot, catalogVersion);
-        if (!(await gitExit(repoRoot, ['check-ignore', '-q', markerPath], env))) {
-            throw new Error('Catalog publish state under .aw/publish must be ignored by Git. Add .aw/ to .gitignore.');
+        await validatePersistentRepository(repositoryPath, persisted, preparation.env);
+        await hooks.beforeFinalRename?.({
+            temporaryStateRoot: staging,
+            finalStateRoot,
+        });
+        try {
+            await fs.rename(staging, finalStateRoot);
+            return persisted;
         }
-        await migrateLegacyAttempt(workspaceRoot, catalogVersion);
-        if (await fs.pathExists(markerPath)) {
-            throw new Error(`Catalog ${catalogVersion} already has an attempted publication record. `
-                + 'Run aw catalog version <higher> before publishing again.');
+        catch (error) {
+            if (!(await fs.pathExists(finalStateRoot)))
+                throw error;
+            if (!(await assertPublicationDirectorySafe(finalStateRoot, journal.display.catalogVersion)))
+                throw error;
+            const existing = await readCatalogPublicationJournal(path.join(finalStateRoot, 'journal.json'), journal.display.catalogVersion);
+            if (!existing) {
+                throw new Error(`Catalog ${journal.display.catalogVersion} publication state is incomplete. Increase the Catalog version.`);
+            }
+            if (existing.planDigest !== journal.planDigest) {
+                throw new Error(`Catalog ${journal.display.catalogVersion} already has a different publication plan. Increase the Catalog version.`);
+            }
+            if (existing.state !== 'published') {
+                await validatePersistentRepository(path.join(finalStateRoot, catalogPublicationRepositoryName()), existing, preparation.env);
+            }
+            return existing;
         }
-        fetchUrl = await git(repoRoot, ['remote', 'get-url', remote], env, `Git remote ${JSON.stringify(remote)} is not configured.`);
-        pushUrl = await git(repoRoot, ['remote', 'get-url', '--push', remote], env, `Git remote ${JSON.stringify(remote)} has no push URL.`);
-        safeFetchUrl = safeRemoteIdentity(fetchUrl);
-        safePushUrl = safeRemoteIdentity(pushUrl);
-        const remoteIdentityDigest = digest(JSON.stringify({ fetchUrl, pushUrl }));
-        const branchRef = `refs/heads/${branch}`;
-        const tagRef = `refs/tags/${tag}`;
-        const repositoryRoot = path.join(temporaryRoot, 'repository');
-        await fs.ensureDir(repositoryRoot);
-        await git(repositoryRoot, ['init', '--quiet'], env, 'Could not create the isolated publication repository.');
-        await git(repositoryRoot, ['config', 'core.hooksPath', path.join(temporaryRoot, 'disabled-hooks')], env, 'Could not disable publication hooks.');
-        await git(repositoryRoot, ['config', 'core.symlinks', 'true'], env, 'Could not configure the isolated publication repository.');
-        await git(repositoryRoot, ['remote', 'add', 'publish', pushUrl], env, 'Could not configure the publication remote.');
-        const initialRefs = parseRemoteRefs(await git(repositoryRoot, [
-            'ls-remote', 'publish', branchRef, tagRef, `${tagRef}^{}`,
-        ], env, 'Could not inspect the Catalog publication remote.'));
-        if (initialRefs.has(tagRef) || initialRefs.has(`${tagRef}^{}`)) {
-            throw new Error(`Remote Catalog tag ${tag} already exists. Increase the Catalog version.`);
+    }
+    finally {
+        await fs.remove(staging);
+    }
+}
+function receiptBase(context, journal, resolution) {
+    const repositoryPath = journal.repository === null
+        ? null
+        : catalogPublicationRepositoryPath(context.catalogWorkspaceRoot, journal.display.catalogVersion);
+    return {
+        ok: true,
+        workspaceRoot: context.catalogWorkspaceRoot,
+        workspaceRootResolvedFrom: resolution.workspaceRootResolvedFrom ?? 'explicit',
+        workspaceIdentity: journal.descriptor.workspaceIdentity,
+        catalogVersion: journal.display.catalogVersion,
+        channel: journal.display.channel,
+        remote: context.remote,
+        remoteResolvedFrom: resolution.remoteResolvedFrom ?? 'explicit',
+        remoteUrl: context.safeFetchUrl,
+        fetchUrl: context.safeFetchUrl,
+        pushUrl: context.safePushUrl,
+        branch: journal.descriptor.branch,
+        branchResolvedFrom: resolution.branchResolvedFrom ?? 'explicit',
+        parent: journal.descriptor.parent,
+        tag: journal.descriptor.tag,
+        expectedCommit: journal.expectedCommit,
+        sourceHead: journal.descriptor.sourceHead,
+        pluginCount: journal.display.pluginCount,
+        snapshotDigest: journal.descriptor.snapshotDigest,
+        planDigest: journal.planDigest,
+        descriptor: journal.descriptor,
+        journalPath: catalogPublicationJournalPath(context.catalogWorkspaceRoot, journal.display.catalogVersion),
+        repositoryPath,
+    };
+}
+async function readExistingPlan(context, resolution) {
+    await assertPublicationStatePathSafe(context.catalogWorkspaceRoot);
+    const stateRoot = catalogPublicationDirectoryPath(context.catalogWorkspaceRoot, context.catalogVersion);
+    const journalPath = catalogPublicationJournalPath(context.catalogWorkspaceRoot, context.catalogVersion);
+    const repositoryPath = catalogPublicationRepositoryPath(context.catalogWorkspaceRoot, context.catalogVersion);
+    const stateRootExists = await assertPublicationDirectorySafe(stateRoot, context.catalogVersion);
+    const journal = await readCatalogPublicationJournal(journalPath, context.catalogVersion);
+    if (!journal) {
+        if (stateRootExists) {
+            throw new Error(`Catalog ${context.catalogVersion} pending publication journal is missing. Increase the Catalog version.`);
         }
-        const parent = initialRefs.get(branchRef) ?? null;
-        let previousSnapshotRoot;
-        if (parent) {
-            await git(repositoryRoot, ['fetch', '--quiet', '--no-tags', 'publish', `${branchRef}:refs/remotes/publish/catalog`], env, 'Could not fetch the published Catalog branch.');
-            previousSnapshotRoot = path.join(temporaryRoot, 'previous');
-            await fs.ensureDir(previousSnapshotRoot);
-            await git(repositoryRoot, ['--work-tree', previousSnapshotRoot, 'checkout', '--quiet', 'refs/remotes/publish/catalog', '--', '.'], env, 'Could not read the published Catalog snapshot.');
-            await validatePublishedCatalogSnapshot(previousSnapshotRoot);
+        return null;
+    }
+    assertLiveContextMatchesDescriptor(context, journal.descriptor);
+    if (journal.state !== 'published') {
+        await validatePersistentRepository(repositoryPath, journal, context.env);
+    }
+    const state = await remoteRefState(context.repoRoot, context.pushUrl, context.branchRef, context.tagRef, context.env);
+    if (journal.state === 'published'
+        && (state.branchCommit !== journal.expectedCommit
+            || !state.tagAnnotated
+            || state.tagCommit !== journal.expectedCommit)) {
+        throw new Error(`Catalog ${journal.display.catalogVersion} published journal conflicts with remote refs. Increase the Catalog version.`);
+    }
+    assertReconciliableRemoteState(state, journal);
+    return {
+        command: 'catalog:publish:plan',
+        state: journal.state,
+        ...receiptBase(context, journal, resolution),
+    };
+}
+async function persistNewPlan(options) {
+    const { preparation, descriptor, snapshotRoot, resolution } = options;
+    await assertPublicationStatePathSafe(preparation.catalogWorkspaceRoot);
+    if (!sameDescriptor(preparation.descriptor, descriptor)) {
+        throw new Error('Catalog publication descriptor changed during preparation.');
+    }
+    const display = displayFromPreparation(preparation);
+    const stateRoot = catalogPublicationDirectoryPath(preparation.catalogWorkspaceRoot, display.catalogVersion);
+    const journalPath = catalogPublicationJournalPath(preparation.catalogWorkspaceRoot, display.catalogVersion);
+    if (!(await publicationGitExit(preparation.repoRoot, ['check-ignore', '-q', journalPath], preparation.env))) {
+        throw new Error('Catalog publish state under .aw/publish must be ignored by Git. Add .aw/ to .gitignore.');
+    }
+    if (await fs.pathExists(stateRoot)) {
+        throw new Error(`Catalog ${display.catalogVersion} already has publication state. Use its existing plan or increase the Catalog version.`);
+    }
+    if (!preparation.tagAvailable) {
+        throw new Error(`Remote Catalog tag ${descriptor.tag} already exists. Increase the Catalog version.`);
+    }
+    const expectedCommit = await createPublicationCommit(preparation, descriptor, snapshotRoot, display);
+    let context = await inspectCatalogPublicationLiveContext({
+        workspaceRoot: preparation.catalogWorkspaceRoot,
+        ...(descriptor.remote.name === null ? { remoteUrl: preparation.pushUrl } : { remote: descriptor.remote.name }),
+        branch: descriptor.branch,
+        env: preparation.env,
+    });
+    assertLiveContextMatchesDescriptor(context, descriptor);
+    const liveRefs = await remoteRefState(preparation.repositoryRoot, 'publish', preparation.branchRef, preparation.tagRef, preparation.env);
+    if (liveRefs.branchCommit !== descriptor.parent || liveRefs.tagPresent) {
+        throw new Error(`Catalog ${display.catalogVersion} remote changed during plan creation. Increase the Catalog version.`);
+    }
+    const journal = {
+        schemaVersion: 2,
+        state: 'prepared',
+        planDigest: catalogPublicationPlanDigest(descriptor, expectedCommit),
+        descriptor,
+        expectedCommit,
+        repository: catalogPublicationRepositoryName(),
+        display,
+        preparedAt: new Date().toISOString(),
+    };
+    const persisted = await persistPublicationState(preparation, stateRoot, journal, {
+        beforeFinalRename: async (paths) => {
+            await options.beforeFinalRename?.(paths);
+            context = await inspectCatalogPublicationLiveContext({
+                workspaceRoot: preparation.catalogWorkspaceRoot,
+                ...(descriptor.remote.name === null
+                    ? { remoteUrl: preparation.pushUrl }
+                    : { remote: descriptor.remote.name }),
+                branch: descriptor.branch,
+                env: preparation.env,
+            });
+            assertLiveContextMatchesDescriptor(context, descriptor);
+            const finalRefs = await remoteRefState(context.repoRoot, context.pushUrl, context.branchRef, context.tagRef, context.env);
+            if (finalRefs.branchCommit !== descriptor.parent || finalRefs.tagPresent) {
+                throw new Error(`Catalog ${display.catalogVersion} remote changed during plan creation. Increase the Catalog version.`);
+            }
+        },
+    });
+    return {
+        command: 'catalog:publish:plan',
+        state: persisted.state,
+        ...receiptBase(context, persisted, resolution),
+    };
+}
+export async function persistCatalogPublicationPlan(options) {
+    return persistNewPlan({
+        preparation: options.preparation,
+        descriptor: options.descriptor ?? options.preparation.descriptor,
+        snapshotRoot: options.snapshotRoot ?? options.preparation.prepared.outputRoot,
+        resolution: options,
+        beforeFinalRename: options.beforeFinalRename,
+    });
+}
+export async function prepareCatalogPublicationPlan(options) {
+    const context = await inspectCatalogPublicationLiveContext(options);
+    const existing = await readExistingPlan(context, options);
+    if (existing)
+        return existing;
+    const initialState = await remoteRefState(context.repoRoot, context.pushUrl, context.branchRef, context.tagRef, context.env);
+    if (initialState.tagPresent) {
+        throw new Error(`Remote Catalog tag ${context.tag} already exists. Increase the Catalog version.`);
+    }
+    if (initialState.branchCommit !== null) {
+        const branchState = await readCatalogPublicationBranchState({
+            workspaceRoot: context.catalogWorkspaceRoot,
+            ...(options.remoteUrl === undefined ? { remote: options.remote } : { remoteUrl: options.remoteUrl }),
+            branch: context.branch,
+            env: options.env,
+        });
+        if (branchState?.version === context.catalogVersion) {
+            throw new Error(`Remote Catalog branch already contains version ${context.catalogVersion} without its journal. Increase the Catalog version.`);
         }
-        const prepared = await preparePublishedWorkspaceCatalog({
-            workspaceRoot: sourceWorkspaceRoot,
-            sourceHead,
-            previousSnapshotRoot,
-            adapter: publishBuildAdapter,
-            reservedImports: CLI_RESERVED_IMPORTS,
+    }
+    const preparation = await prepareCatalogPublicationInspection(options);
+    try {
+        return await persistNewPlan({
+            preparation,
+            descriptor: preparation.descriptor,
+            snapshotRoot: preparation.prepared.outputRoot,
+            resolution: options,
+            beforeFinalRename: options.beforeFinalRename,
         });
-        const preparedHead = await git(repoRoot, ['rev-parse', '--verify', 'HEAD'], env, 'Could not recheck the source Git HEAD.');
-        const preparedStatus = await git(repoRoot, [
-            'status', '--porcelain=v1', '--untracked-files=all', '--ignore-submodules=none',
-        ], env, 'Could not recheck the source worktree.');
-        if (preparedHead !== sourceHead || preparedStatus !== '') {
-            throw new Error('Source HEAD or worktree changed during Catalog preparation. Commit or clean it before publishing.');
+    }
+    finally {
+        await disposeCatalogPublicationInspection(preparation);
+    }
+}
+async function markUncertain(journalPath, journal) {
+    const uncertain = {
+        schemaVersion: 2,
+        state: 'uncertain',
+        planDigest: journal.planDigest,
+        descriptor: journal.descriptor,
+        expectedCommit: journal.expectedCommit,
+        repository: journal.repository,
+        display: journal.display,
+        preparedAt: journal.preparedAt,
+        uncertainAt: new Date().toISOString(),
+    };
+    await writeCatalogPublicationJournalAtomic(journalPath, uncertain);
+    return uncertain;
+}
+async function readAuthorizedPublicationPlan(options) {
+    await assertPublicationStatePathSafe(options.workspaceRoot);
+    const located = await findCatalogPublicationJournalByPlanDigest(options.workspaceRoot, options.expectedPlanDigest);
+    const context = await inspectCatalogPublicationApplyContext(options);
+    assertApplyContextMatchesDescriptor(context, located.journal.descriptor);
+    return {
+        context,
+        journalPath: located.journalPath,
+        repositoryPath: catalogPublicationRepositoryPath(context.catalogWorkspaceRoot, located.catalogVersion),
+        tagRef: `refs/tags/${located.journal.descriptor.tag}`,
+        journal: located.journal,
+    };
+}
+async function cleanupPublishedRepository(repositoryPath, journal, env, removeRepository) {
+    try {
+        await fs.lstat(repositoryPath);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        return [CATALOG_PUBLICATION_CLEANUP_WARNING];
+    }
+    const pendingJournal = {
+        schemaVersion: 2,
+        state: 'prepared',
+        planDigest: journal.planDigest,
+        descriptor: journal.descriptor,
+        expectedCommit: journal.expectedCommit,
+        repository: catalogPublicationRepositoryName(),
+        display: journal.display,
+        preparedAt: journal.preparedAt,
+    };
+    try {
+        await validatePersistentRepository(repositoryPath, pendingJournal, env);
+        await removeRepository(repositoryPath);
+        return [];
+    }
+    catch {
+        return [CATALOG_PUBLICATION_CLEANUP_WARNING];
+    }
+}
+async function inspectCatalogPublicationPlanForApply(options) {
+    const authorized = await readAuthorizedPublicationPlan(options);
+    const { context, journal, repositoryPath, tagRef } = authorized;
+    if (journal.state !== 'published') {
+        await validatePersistentRepository(repositoryPath, journal, context.env);
+    }
+    const state = await remoteRefState(journal.state === 'published' ? context.repoRoot : repositoryPath, context.pushUrl, context.branchRef, tagRef, context.env);
+    if (journal.state === 'published'
+        && (state.branchCommit !== journal.expectedCommit
+            || !state.tagAnnotated
+            || state.tagCommit !== journal.expectedCommit)) {
+        throw new Error(`Catalog ${journal.display.catalogVersion} published journal conflicts with remote refs. Increase the Catalog version.`);
+    }
+    assertReconciliableRemoteState(state, journal);
+    return {
+        command: 'catalog:publish:plan',
+        state: journal.state,
+        ...receiptBase(context, journal, options),
+    };
+}
+export async function applyCatalogPublicationPlan(options) {
+    if (!/^sha256:[0-9a-f]{64}$/u.test(options.expectedPlanDigest)) {
+        throw new Error('Catalog publish apply requires --expected-plan-digest from catalog publish plan.');
+    }
+    const authorized = await readAuthorizedPublicationPlan(options);
+    const { context, journalPath, repositoryPath, tagRef } = authorized;
+    let { journal } = authorized;
+    if (journal.state === 'published') {
+        const state = await remoteRefState(context.repoRoot, context.pushUrl, context.branchRef, tagRef, context.env);
+        if (state.branchCommit !== journal.expectedCommit || !state.tagAnnotated || state.tagCommit !== journal.expectedCommit) {
+            throw new Error(`Catalog ${journal.display.catalogVersion} published journal conflicts with remote refs. Increase the Catalog version.`);
         }
-        if (!options.yes) {
-            options.io.stderr([
-                `Source HEAD: ${sourceHead}`,
-                `Catalog: ${prepared.catalogVersion} (${prepared.channel})`,
-                `Push remote: ${remote} (${safePushUrl})`,
-                `Branch: ${branchRef}`,
-                `Tag: ${tagRef}`,
-                `Plugins: ${prepared.pluginNames.length}`,
-                'One atomic push will publish the branch and annotated tag.',
-            ].join('\n') + '\n');
-            if (!options.confirm || !(await options.confirm('Publish this Catalog snapshot?'))) {
-                options.io.stderr('Catalog publication cancelled.\n');
-                return null;
+        const warnings = await cleanupPublishedRepository(repositoryPath, journal, context.env, options.removeRepository ?? fs.remove);
+        return {
+            command: 'catalog:publish:apply',
+            state: 'published',
+            commit: journal.expectedCommit,
+            reconciliation: 'already-published',
+            warnings,
+            ...receiptBase(context, journal, options),
+        };
+    }
+    await validatePersistentRepository(repositoryPath, journal, context.env);
+    let state = await remoteRefState(repositoryPath, context.pushUrl, context.branchRef, tagRef, context.env);
+    assertReconciliableRemoteState(state, journal);
+    let reconciliation;
+    const branchAtExpected = state.branchCommit === journal.expectedCommit;
+    const tagAtExpected = state.tagAnnotated && state.tagCommit === journal.expectedCommit;
+    if (branchAtExpected && tagAtExpected) {
+        reconciliation = 'already-remote';
+    }
+    else {
+        await options.beforeRemoteWrite?.();
+        const writeContext = await inspectCatalogPublicationApplyContext(options);
+        assertApplyContextMatchesDescriptor(writeContext, journal.descriptor);
+        await validatePersistentRepository(repositoryPath, journal, writeContext.env);
+        state = await remoteRefState(repositoryPath, writeContext.pushUrl, writeContext.branchRef, tagRef, writeContext.env);
+        assertReconciliableRemoteState(state, journal);
+        try {
+            if (state.branchCommit === journal.expectedCommit
+                && state.tagAnnotated
+                && state.tagCommit === journal.expectedCommit) {
+                reconciliation = 'already-remote';
+            }
+            else if (state.branchCommit === journal.descriptor.parent && !state.tagPresent) {
+                reconciliation = 'atomic';
+                await publicationGit(repositoryPath, [
+                    'push', '--atomic',
+                    `--force-with-lease=${writeContext.branchRef}:${journal.descriptor.parent ?? ''}`,
+                    writeContext.pushUrl,
+                    `${journal.expectedCommit}:${writeContext.branchRef}`,
+                    `${tagRef}:${tagRef}`,
+                ], writeContext.env, 'publicationUncertain', 'Catalog atomic push failed or its result is uncertain.');
+            }
+            else if (state.branchCommit === journal.expectedCommit && !state.tagPresent) {
+                reconciliation = 'tag';
+                await publicationGit(repositoryPath, [
+                    'push', writeContext.pushUrl, `${tagRef}:${tagRef}`,
+                ], writeContext.env, 'publicationUncertain', 'Catalog tag push failed or its result is uncertain.');
+            }
+            else {
+                reconciliation = 'branch';
+                await publicationGit(repositoryPath, [
+                    'push', `--force-with-lease=${writeContext.branchRef}:${journal.descriptor.parent ?? ''}`,
+                    writeContext.pushUrl, `${journal.expectedCommit}:${writeContext.branchRef}`,
+                ], writeContext.env, 'publicationUncertain', 'Catalog branch push failed or its result is uncertain.');
             }
         }
-        if (parent)
-            await git(repositoryRoot, ['checkout', '--quiet', '--detach', 'refs/remotes/publish/catalog'], env, 'Could not select the publication parent.');
-        else
-            await git(repositoryRoot, ['checkout', '--quiet', '--orphan', 'catalog-publication'], env, 'Could not create the initial Catalog publication.');
-        await clearWorktree(repositoryRoot);
-        await fs.copy(prepared.outputRoot, repositoryRoot, { dereference: false });
-        await git(repositoryRoot, ['add', '--force', '--all'], env, 'Could not stage the Catalog publication tree.');
-        await git(repositoryRoot, [
-            '-c', 'user.name=AW Catalog Publisher',
-            '-c', 'user.email=catalog-publisher@agent-workflows.invalid',
-            'commit', '--quiet', '-m', `Catalog ${catalogVersion}`,
-        ], env, 'Could not create the Catalog publication commit.');
-        const commit = await git(repositoryRoot, ['rev-parse', 'HEAD'], env, 'Could not resolve the Catalog publication commit.');
-        const parents = (await git(repositoryRoot, ['show', '-s', '--format=%P', commit], env, 'Could not verify the Catalog publication parent.')).split(/\s+/u).filter(Boolean);
-        if ((parent && (parents.length !== 1 || parents[0] !== parent)) || (!parent && parents.length !== 0)) {
-            throw new Error('Catalog publication commit has an invalid parent.');
-        }
-        const verificationRoot = path.join(temporaryRoot, 'verification');
-        await fs.ensureDir(verificationRoot);
-        await git(repositoryRoot, ['--work-tree', verificationRoot, 'checkout', '--quiet', commit, '--', '.'], env, 'Could not verify the Catalog publication commit tree.');
-        const committed = await validatePublishedCatalogSnapshot(verificationRoot);
-        if (committed.snapshotDigest !== prepared.snapshotDigest)
-            throw new Error('Catalog publication commit tree differs from the prepared snapshot.');
-        await git(repositoryRoot, [
-            '-c', 'user.name=AW Catalog Publisher',
-            '-c', 'user.email=catalog-publisher@agent-workflows.invalid',
-            'tag', '--annotate', tag, '--message', `Catalog ${catalogVersion}`,
-        ], env, 'Could not create the annotated Catalog tag.');
-        const attemptedAt = new Date().toISOString();
-        const attempted = {
-            schemaVersion: 1,
-            state: 'attempted',
-            workspaceIdentity: digest(JSON.stringify({ repoRoot, workspaceRelative: path.relative(repoRoot, workspaceRoot) })),
-            catalogVersion,
-            sourceHead,
-            remote: { name: remote, identityDigest: remoteIdentityDigest },
-            branch,
-            tag,
-            preparedSnapshotDigest: prepared.snapshotDigest,
-            attemptedAt,
-        };
-        await writeJsonAtomic(markerPath, attempted);
-        const liveRefs = parseRemoteRefs(await git(repositoryRoot, [
-            'ls-remote', 'publish', branchRef, tagRef, `${tagRef}^{}`,
-        ], env, 'Could not recheck the Catalog publication remote.'));
-        if ((liveRefs.get(branchRef) ?? null) !== parent || liveRefs.has(tagRef) || liveRefs.has(`${tagRef}^{}`)) {
-            throw new Error('Catalog remote changed during preparation. Increase the Catalog version before publishing again.');
+        catch (error) {
+            journal = await markUncertain(journalPath, journal);
+            throw new Error(`Catalog ${journal.display.catalogVersion} publication result is uncertain. Retry apply with the same plan digest.`, { cause: error });
         }
         try {
-            await git(repositoryRoot, [
-                'push', '--atomic', 'publish', `${commit}:${branchRef}`, `${tagRef}:${tagRef}`,
-            ], env, `Catalog atomic push failed or its result is uncertain. Do not retry ${catalogVersion}; increase the Catalog version.`);
+            state = await remoteRefState(repositoryPath, writeContext.pushUrl, writeContext.branchRef, tagRef, writeContext.env);
         }
-        catch {
-            throw new Error(`Catalog atomic push failed or its result is uncertain. Do not retry ${catalogVersion}; run aw catalog version <higher>.`);
+        catch (error) {
+            journal = await markUncertain(journalPath, journal);
+            throw new Error(`Catalog ${journal.display.catalogVersion} publication result is uncertain. Retry apply with the same plan digest.`, { cause: error });
         }
-        const publishedRefs = parseRemoteRefs(await git(repositoryRoot, [
-            'ls-remote', 'publish', branchRef, tagRef, `${tagRef}^{}`,
-        ], env, `Catalog publication result is uncertain. Do not retry ${catalogVersion}; increase the Catalog version.`));
-        if (publishedRefs.get(branchRef) !== commit || publishedRefs.get(`${tagRef}^{}`) !== commit) {
-            throw new Error(`Catalog publication result is uncertain. Do not retry ${catalogVersion}; run aw catalog version <higher>.`);
+        if (state.branchCommit !== journal.expectedCommit || !state.tagAnnotated || state.tagCommit !== journal.expectedCommit) {
+            journal = await markUncertain(journalPath, journal);
+            throw new Error(`Catalog ${journal.display.catalogVersion} publication result is uncertain. Retry apply with the same plan digest.`);
         }
-        await writeJsonAtomic(markerPath, { ...attempted, state: 'published', commit, publishedAt: new Date().toISOString() });
-        return {
-            command: 'catalog:publish',
-            ok: true,
-            catalogVersion,
-            channel: prepared.channel,
-            remote,
-            remoteUrl: safeFetchUrl,
-            fetchUrl: safeFetchUrl,
-            pushUrl: safePushUrl,
-            branch,
-            tag,
-            commit,
-            sourceHead,
-            pluginCount: prepared.pluginNames.length,
-            snapshotDigest: prepared.snapshotDigest,
-        };
     }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        throw new Error(message
-            .replaceAll(temporaryRoot, '<temporary Catalog state>')
-            .replaceAll(fetchUrl, safeFetchUrl)
-            .replaceAll(pushUrl, safePushUrl));
+    const published = {
+        schemaVersion: 2,
+        state: 'published',
+        planDigest: journal.planDigest,
+        descriptor: journal.descriptor,
+        expectedCommit: journal.expectedCommit,
+        repository: null,
+        display: journal.display,
+        preparedAt: journal.preparedAt,
+        publishedAt: new Date().toISOString(),
+    };
+    await writeCatalogPublicationJournalAtomic(journalPath, published);
+    const warnings = await cleanupPublishedRepository(repositoryPath, published, context.env, options.removeRepository ?? fs.remove);
+    return {
+        command: 'catalog:publish:apply',
+        state: 'published',
+        commit: published.expectedCommit,
+        reconciliation,
+        warnings,
+        ...receiptBase(context, published, options),
+    };
+}
+export async function runCatalogPublishPlanCommand(options) {
+    const workspace = await resolveCatalogWorkspaceRoot({
+        cwd: options.cwd,
+        ...(options.workspaceRoot === undefined ? {} : { explicitRoot: options.workspaceRoot }),
+        mode: 'existing',
+    });
+    const target = await resolveCatalogPublicationTarget({
+        workspaceRoot: workspace.workspaceRoot,
+        remote: options.remote,
+        branch: options.branch,
+        env: options.env,
+        requireRemote: true,
+    });
+    return prepareCatalogPublicationPlan({
+        workspaceRoot: workspace.workspaceRoot,
+        remote: target.remote,
+        branch: target.branch,
+        env: options.env,
+        workspaceRootResolvedFrom: workspace.workspaceRootResolvedFrom,
+        remoteResolvedFrom: target.remoteResolvedFrom,
+        branchResolvedFrom: target.branchResolvedFrom,
+    });
+}
+export async function runCatalogPublishApplyCommand(options) {
+    if (options.json && !options.yes)
+        throw new Error('Catalog publish apply with --json requires --yes.');
+    if (!options.interactive && !options.yes)
+        throw new Error('Non-interactive Catalog publish apply requires --yes.');
+    if (!/^sha256:[0-9a-f]{64}$/u.test(options.expectedPlanDigest ?? '')) {
+        throw new Error('Catalog publish apply requires --expected-plan-digest from catalog publish plan.');
     }
-    finally {
-        await fs.remove(temporaryRoot);
+    const workspace = await resolveCatalogWorkspaceRoot({
+        cwd: options.cwd,
+        ...(options.workspaceRoot === undefined ? {} : { explicitRoot: options.workspaceRoot }),
+        mode: 'existing',
+    });
+    const target = await resolveCatalogPublicationTarget({
+        workspaceRoot: workspace.workspaceRoot,
+        remote: options.remote,
+        branch: options.branch,
+        env: options.env,
+        requireRemote: true,
+    });
+    if (!options.yes) {
+        const plan = await inspectCatalogPublicationPlanForApply({
+            workspaceRoot: workspace.workspaceRoot,
+            remote: target.remote,
+            branch: target.branch,
+            expectedPlanDigest: options.expectedPlanDigest,
+            env: options.env,
+            workspaceRootResolvedFrom: workspace.workspaceRootResolvedFrom,
+            remoteResolvedFrom: target.remoteResolvedFrom,
+            branchResolvedFrom: target.branchResolvedFrom,
+        });
+        options.io.stderr([
+            `Workspace identity: ${plan.workspaceIdentity}`,
+            `Source HEAD: ${plan.sourceHead}`,
+            `Remote: ${plan.remote}`,
+            `Fetch URL: ${plan.fetchUrl}`,
+            `Push URL: ${plan.pushUrl}`,
+            `Branch: refs/heads/${plan.branch}`,
+            `Parent: ${plan.parent ?? '<root>'}`,
+            `Tag: refs/tags/${plan.tag}`,
+            `Snapshot digest: ${plan.snapshotDigest}`,
+            `Expected commit: ${plan.expectedCommit}`,
+            `Plan digest: ${plan.planDigest}`,
+        ].join('\n') + '\n');
+        if (!options.confirm || !(await options.confirm('Apply this Catalog publication plan?'))) {
+            options.io.stderr('Catalog publication cancelled.\n');
+            return null;
+        }
     }
+    const result = await applyCatalogPublicationPlan({
+        workspaceRoot: workspace.workspaceRoot,
+        remote: target.remote,
+        branch: target.branch,
+        expectedPlanDigest: options.expectedPlanDigest,
+        env: options.env,
+        workspaceRootResolvedFrom: workspace.workspaceRootResolvedFrom,
+        remoteResolvedFrom: target.remoteResolvedFrom,
+        branchResolvedFrom: target.branchResolvedFrom,
+    });
+    for (const warning of result.warnings)
+        options.io.stderr(`${warning}\n`);
+    return result;
 }
 //# sourceMappingURL=catalog-publish.js.map