@open-agent-toolkit/cli 0.2.50 → 0.2.51

package/dist/commands/project/pull/index.js

@@ -1,7 +1,11 @@
+import { isAbsolute, relative, resolve, sep } from 'node:path';
 import { buildCommandContext, } from '../../../app/command-context.js';
 import { defaultGitRunner } from '../../project/sync/git.js';
-import { abortSynced as defaultAbortSynced, commitRecordChange as defaultCommitRecordChange, continueSynced as defaultContinueSynced, pullChildren as defaultPullChildren, pullSynced as defaultPullSynced, } from '../../project/sync/ref-sync.js';
-import { resolveSyncedTarget, } from '../../project/sync/resolve-target.js';
+import { readSyncedRecord } from '../../project/sync/record.js';
+import { abortSynced as defaultAbortSynced, commitRecordChange as defaultCommitRecordChange, continueSynced as defaultContinueSynced, pullChildren as defaultPullChildren, pullSynced as defaultPullSynced, buildSyncTarget, classifyRemoteRefLookup, } from '../../project/sync/ref-sync.js';
+import { probeSyncedTerminalRefs, resolveSyncedTarget, } from '../../project/sync/resolve-target.js';
+import { resolveProjectsRoot } from '../../shared/oat-paths.js';
+import { completedSyncedRefName, resolveProjectScope, resolveScopeRoot, syncedRecordPath, } from '../../shared/project-scope.js';
 import { readGlobalOptions } from '../../shared/shared.utils.js';
 import { CliError } from '../../../errors/cli-error.js';
 import { resolveProjectRoot } from '../../../fs/paths.js';
@@ -9,6 +13,8 @@ import { Command } from 'commander';
 const DEFAULT_DEPENDENCIES = {
     buildCommandContext,
     resolveProjectRoot,
+    resolveProjectsRoot,
+    guardSyncedTerminalTarget,
     resolveSyncedTarget,
     pullSynced: defaultPullSynced,
     pullChildren: defaultPullChildren,
@@ -21,6 +27,66 @@ const DEFAULT_DEPENDENCIES = {
 function shellQuote(value) {
     return `'${value.replaceAll("'", "'\\''")}'`;
 }
+function slugForTerminalGuard(repoRoot, projectsRoot, pathOrSlug) {
+    if (!pathOrSlug)
+        return null;
+    if (!pathOrSlug.includes('/') && !pathOrSlug.includes('\\')) {
+        return pathOrSlug;
+    }
+    const absolute = isAbsolute(pathOrSlug)
+        ? resolve(pathOrSlug)
+        : resolve(repoRoot, pathOrSlug);
+    const syncedRoot = resolveScopeRoot(repoRoot, projectsRoot, 'synced');
+    if (resolveProjectScope(absolute, resolveScopeRoot(repoRoot, projectsRoot, 'shared'), repoRoot) !== 'synced') {
+        return null;
+    }
+    const child = relative(syncedRoot, absolute);
+    return child && !child.includes(sep) ? child : null;
+}
+function terminalActionError(slug, action, state, completedRef, sha) {
+    const alias = state === 'both'
+        ? ' The matching active ref is only a stale terminal alias and is ignored.'
+        : '';
+    return new CliError(`Synced project ${slug} is already archived at ${completedRef}@${sha} and cannot be ${action === 'pull' ? 'pulled' : 'opened'}.${alias} Inspect the durable archive, or use oat project prune ${shellQuote(slug)} only to intentionally remove retained terminal ref reachability.`, 1);
+}
+export async function guardSyncedTerminalTarget(repoRoot, projectsRoot, pathOrSlug, action, git) {
+    const slug = slugForTerminalGuard(repoRoot, projectsRoot, pathOrSlug);
+    if (!slug)
+        return;
+    const target = buildSyncTarget(repoRoot, projectsRoot, slug);
+    const record = await readSyncedRecord(syncedRecordPath(target.syncedRoot, slug));
+    if (record?.status === 'complete') {
+        if (record.archiveSourceRefSha) {
+            const probe = await probeSyncedTerminalRefs(target, record.archiveSourceRefSha, git);
+            if (probe.state === 'wrong-sha') {
+                throw new CliError(`Invalid terminal refs for ${slug}: active ${probe.activeRef} is ${probe.activeSha ?? 'absent'}, completed ${probe.completedRef} is ${probe.completedSha ?? 'absent'}, expected archived source ${record.archiveSourceRefSha}. Repair the ref mismatch before retrying completion or prune; the project was not ${action === 'pull' ? 'pulled' : 'opened'}.`, 1);
+            }
+        }
+        const detail = record.archiveSnapshot
+            ? 'Its durable archive exists, but legacy terminal cleanup is still pending.'
+            : 'Its archive snapshot metadata is incomplete.';
+        throw new CliError(`Synced project ${slug} has a legacy complete record and cannot be ${action === 'pull' ? 'pulled' : 'opened'}. ${detail} Retry oat-project-complete to finish archive retirement; do not rematerialize the checkout.`, 1);
+    }
+    const completedRef = completedSyncedRefName(slug);
+    const lookup = await git.run(['ls-remote', '--exit-code', target.remote, completedRef], { cwd: repoRoot, allowFailure: true });
+    if (classifyRemoteRefLookup(lookup, target.remote, completedRef) === 'absent') {
+        return;
+    }
+    const rows = lookup.stdout.split('\n').filter(Boolean);
+    const [sha, advertisedRef] = rows[0]?.trim().split(/\s+/) ?? [];
+    if (rows.length !== 1 ||
+        advertisedRef !== completedRef ||
+        !/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/i.test(sha ?? '')) {
+        throw new CliError(`Unable to verify terminal identity for ${slug}: origin returned a malformed completed-ref advertisement.`, 2);
+    }
+    const probe = await probeSyncedTerminalRefs(target, sha, git);
+    if (probe.state === 'wrong-sha') {
+        throw new CliError(`Invalid terminal refs for ${slug}: active ${probe.activeRef} is ${probe.activeSha ?? 'absent'}, completed ${probe.completedRef} is ${probe.completedSha ?? 'absent'}, expected ${sha}. Repair the ref mismatch before retrying completion or prune; the project was not ${action === 'pull' ? 'pulled' : 'opened'}.`, 1);
+    }
+    if (probe.state === 'completed-only' || probe.state === 'both') {
+        throw terminalActionError(slug, action, probe.state, completedRef, sha);
+    }
+}
 function reportPullResult(context, result, target, targetArg, children = []) {
     const payload = {
         ...result,
@@ -89,7 +155,20 @@ async function runPull(context, pathOrSlug, options, dependencies) {
             throw new CliError('`--continue` and `--abort` are mutually exclusive.', 1);
         }
         const repoRoot = await dependencies.resolveProjectRoot(context.cwd);
-        const target = await dependencies.resolveSyncedTarget({ repoRoot, env: dependencies.processEnv }, pathOrSlug, {}, { allowMissingCheckout: !options.continue && !options.abort });
+        const projectsRoot = await dependencies.resolveProjectsRoot(repoRoot, dependencies.processEnv);
+        let target;
+        try {
+            target = await dependencies.resolveSyncedTarget({ repoRoot, env: dependencies.processEnv }, pathOrSlug, {}, { allowMissingCheckout: !options.continue && !options.abort });
+        }
+        catch (error) {
+            if (error instanceof CliError &&
+                error.exitCode === 1 &&
+                error.message.startsWith('No synced project named ')) {
+                await dependencies.guardSyncedTerminalTarget(repoRoot, projectsRoot, pathOrSlug, 'pull', dependencies.gitRunner);
+            }
+            throw error;
+        }
+        await dependencies.guardSyncedTerminalTarget(repoRoot, projectsRoot, pathOrSlug ?? target.projectPath, 'pull', dependencies.gitRunner);
         const targetArg = pathOrSlug ?? target.projectPath;
         if (options.abort) {
             await dependencies.abortSynced(target, dependencies.gitRunner);

package/dist/commands/project/sync/git.d.ts

@@ -12,7 +12,16 @@ export interface GitRunOptions {
 export interface GitRunner {
     run(args: string[], options: GitRunOptions): Promise<GitResult>;
 }
+export interface AtomicRefTransition {
+    remote: string;
+    sourceSha: string;
+    activeRef: string;
+    completedRef: string;
+    completedExpectedSha: string | null;
+}
 export type ExecFileImplementation = (file: string, args: readonly string[], options: ExecFileOptionsWithStringEncoding, callback: (error: ExecFileException | null, stdout: string, stderr: string) => void) => unknown;
+export declare function pushAtomicRefTransition(git: GitRunner, cwd: string, transition: AtomicRefTransition): Promise<GitResult>;
+export declare function isAtomicPushUnsupported(result: GitResult): boolean;
 export declare function createGitRunner(execFileImpl?: ExecFileImplementation): GitRunner;
 export declare const defaultGitRunner: GitRunner;
 //# sourceMappingURL=git.d.ts.map

package/dist/commands/project/sync/git.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"git.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/sync/git.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,iCAAiC,EACvC,MAAM,oBAAoB,CAAC;AAI5B,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,SAAS;IACxB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;CACjE;AAED,MAAM,MAAM,sBAAsB,GAAG,CACnC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,EAAE,iCAAiC,EAC1C,QAAQ,EAAE,CACR,KAAK,EAAE,iBAAiB,GAAG,IAAI,EAC/B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,KACX,IAAI,KACN,OAAO,CAAC;AAqCb,wBAAgB,eAAe,CAC7B,YAAY,GAAE,sBAAiC,GAC9C,SAAS,CAqCX;AAED,eAAO,MAAM,gBAAgB,WAAoB,CAAC"}
+{"version":3,"file":"git.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/sync/git.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,iCAAiC,EACvC,MAAM,oBAAoB,CAAC;AAI5B,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,SAAS;IACxB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;CACjE;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC;AAED,MAAM,MAAM,sBAAsB,GAAG,CACnC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,EAAE,iCAAiC,EAC1C,QAAQ,EAAE,CACR,KAAK,EAAE,iBAAiB,GAAG,IAAI,EAC/B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,KACX,IAAI,KACN,OAAO,CAAC;AAEb,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,SAAS,EACd,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,mBAAmB,GAC9B,OAAO,CAAC,SAAS,CAAC,CAapB;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CASlE;AAqCD,wBAAgB,eAAe,CAC7B,YAAY,GAAE,sBAAiC,GAC9C,SAAS,CAqCX;AAED,eAAO,MAAM,gBAAgB,WAAoB,CAAC"}

package/dist/commands/project/sync/git.js

@@ -1,5 +1,23 @@
 import { execFile, } from 'node:child_process';
 import { CliError } from '../../../errors/cli-error.js';
+export function pushAtomicRefTransition(git, cwd, transition) {
+    return git.run([
+        'push',
+        '--atomic',
+        `--force-with-lease=${transition.activeRef}:${transition.sourceSha}`,
+        `--force-with-lease=${transition.completedRef}:${transition.completedExpectedSha ?? ''}`,
+        transition.remote,
+        `${transition.sourceSha}:${transition.completedRef}`,
+        `:${transition.activeRef}`,
+    ], { cwd, allowFailure: true });
+}
+export function isAtomicPushUnsupported(result) {
+    if (result.code === 0)
+        return false;
+    const detail = `${result.stderr}\n${result.stdout}`;
+    return (/(?:does not support|not supported).*(?:--atomic|atomic push)/i.test(detail) ||
+        /(?:--atomic|atomic push).*(?:does not support|not supported)/i.test(detail));
+}
 function numericExitCode(error) {
     return typeof error?.code === 'number' ? error.code : 0;
 }

package/dist/commands/project/sync/ref-sync.d.ts

@@ -1,7 +1,7 @@
 import { ensureScopedRootGitignore } from '../../init/gitignore.js';
 import { readOatLocalConfig, writeOatLocalConfig } from '../../../config/oat-config.js';
 import { copyDirectory } from '../../../fs/io.js';
-import type { GitRunner } from './git.js';
+import { type GitRunner } from './git.js';
 export interface SyncTarget {
     repoRoot: string;
     sharedRoot: string;
@@ -62,6 +62,18 @@ export type MigrateResult = {
     lifecycleCommit: string | null;
     sha: string;
 };
+export type SyncedRefRetirementReceipt = {
+    status: 'retired' | 'already-retired';
+    state: 'completed-only' | 'matching-aliases';
+    activeAliasRetained: boolean;
+    activeRef: string;
+    completedRef: string;
+    verifiedSha: string;
+};
+export type CompletedSyncedRefDeletionReceipt = {
+    completedRef: string;
+    deleted: boolean;
+};
 export declare function classifyRemoteRefLookup(result: {
     code: number;
     stdout: string;
@@ -105,9 +117,12 @@ export declare function preflightSyncedCheckout(target: SyncTarget, git: GitRunn
 export declare function removeSyncedCheckout(target: SyncTarget, git: GitRunner, options?: {
     force?: boolean;
 }): Promise<RemoveResult>;
+export declare function retireSyncedRef(target: SyncTarget, sourceSha: string, git: GitRunner): Promise<SyncedRefRetirementReceipt>;
+export declare function deleteCompletedSyncedRefForPrune(target: SyncTarget, git: GitRunner): Promise<CompletedSyncedRefDeletionReceipt>;
 export declare function pruneSynced(target: SyncTarget, git: GitRunner, options: {
     force: boolean;
     commit: boolean;
+    expectedActiveAliasSha?: string;
 }): Promise<PruneResult>;
 export declare function migrateSharedToSynced(target: SyncTarget, git: GitRunner, options: MigrateSharedToSyncedOptions): Promise<MigrateResult>;
 /**

package/dist/commands/project/sync/ref-sync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ref-sync.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/sync/ref-sync.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ref-sync.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/sync/ref-sync.ts"],"names":[],"mappings":"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"}

package/dist/commands/project/sync/ref-sync.js

@@ -2,11 +2,12 @@ import { lstat, mkdir, readFile, readdir, realpath, rm, stat, writeFile, } from
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { ensureScopedRootGitignore } from '../../init/gitignore.js';
 import { getFrontmatterBlock } from '../../shared/frontmatter.js';
-import { canonicalizePath, isSyncedCheckout, resolveScopeRoot, SYNCED_REMOTE, syncedRefName, syncedRecordPath, } from '../../shared/project-scope.js';
+import { canonicalizePath, completedSyncedRefName, isSyncedCheckout, resolveScopeRoot, SYNCED_REMOTE, syncedRefName, syncedRecordPath, } from '../../shared/project-scope.js';
 import { readOatLocalConfig, writeOatLocalConfig } from '../../../config/oat-config.js';
 import { CliError } from '../../../errors/cli-error.js';
 import { copyDirectory } from '../../../fs/io.js';
 import YAML from 'yaml';
+import { isAtomicPushUnsupported, pushAtomicRefTransition, } from './git.js';
 import { buildSyncedRecord, readSyncedRecord, writeSyncedRecord, } from './record.js';
 export function classifyRemoteRefLookup(result, remote, ref) {
     if (result.code === 0)
@@ -442,6 +443,32 @@ async function prepareAdoptionRecord(target, result, adoptionRecord, now, additi
         pendingRecordPaths: [recordPath, ...additionalPendingPaths],
     };
 }
+async function probeChildRemoteRefs(target, git) {
+    const completedRef = completedSyncedRefName(target.slug);
+    const lookup = await git.run(['ls-remote', '--exit-code', target.remote, target.ref, completedRef], { cwd: target.repoRoot, allowFailure: true });
+    if (classifyRemoteRefLookup(lookup, target.remote, `${target.ref} and ${completedRef}`) === 'absent') {
+        return { activeSha: null, completedSha: null };
+    }
+    const expectedRefs = new Set([target.ref, completedRef]);
+    const advertised = new Map();
+    for (const row of lookup.stdout.split('\n').filter(Boolean)) {
+        const fields = row.trim().split(/\s+/);
+        if (fields.length !== 2 ||
+            !/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/i.test(fields[0] ?? '') ||
+            !expectedRefs.has(fields[1] ?? '') ||
+            advertised.has(fields[1] ?? '')) {
+            throw new CliError(`Unable to verify terminal refs for child ${target.slug}: origin returned a malformed ref advertisement.`, 2);
+        }
+        advertised.set(fields[1], fields[0]);
+    }
+    if (advertised.size === 0) {
+        throw new CliError(`Unable to verify terminal refs for child ${target.slug}: origin returned a malformed empty advertisement.`, 2);
+    }
+    return {
+        activeSha: advertised.get(target.ref) ?? null,
+        completedSha: advertised.get(completedRef) ?? null,
+    };
+}
 export async function pullChildren(parentTarget, git) {
     await assertCanonicalSyncTargetIdentity(parentTarget);
     const statePath = resolve(parentTarget.projectPath, 'state.md');
@@ -477,11 +504,9 @@ export async function pullChildren(parentTarget, git) {
         };
         try {
             await assertCanonicalSyncTargetIdentity(childTarget);
-            const adoptionRecord = await classifyAdoptionRecord(childTarget, git);
-            const remote = await git.run(['ls-remote', '--exit-code', childTarget.remote, childTarget.ref], { cwd: parentTarget.repoRoot, allowFailure: true });
-            if (remote.code === 2 &&
-                remote.stdout.trim() === '' &&
-                remote.stderr.trim() === '') {
+            const completedRef = completedSyncedRefName(slug);
+            const { activeSha, completedSha } = await probeChildRemoteRefs(childTarget, git);
+            if (activeSha === null && completedSha === null) {
                 results.push({
                     slug,
                     status: 'missing',
@@ -490,15 +515,27 @@ export async function pullChildren(parentTarget, git) {
                 });
                 continue;
             }
-            if (remote.code !== 0) {
+            if (activeSha !== null &&
+                completedSha !== null &&
+                activeSha !== completedSha) {
+                results.push({
+                    slug,
+                    status: 'error',
+                    message: `Invalid terminal refs for child ${slug}: active ${childTarget.ref} is ${activeSha}, completed ${completedRef} is ${completedSha}. Repair the ref mismatch before retrying; the child was not pulled.`,
+                    exitCode: 1,
+                });
+                continue;
+            }
+            if (completedSha !== null) {
                 results.push({
                     slug,
                     status: 'error',
-                    message: `git ls-remote ${childTarget.remote} ${childTarget.ref} failed (exit ${remote.code}): ${remote.stderr || remote.stdout || 'unknown Git error'}`,
-                    exitCode: 2,
+                    message: `Synced child ${slug} is already archived at ${completedRef}@${completedSha} and will not be pulled.${activeSha === completedSha ? ` The matching active ref ${childTarget.ref} is only an inert alias.` : ''}`,
+                    exitCode: 1,
                 });
                 continue;
             }
+            const adoptionRecord = await classifyAdoptionRecord(childTarget, git);
             const result = await pullSynced(childTarget, git, {
                 adopt: adoptionRecord !== 'durable',
                 adoptionRecord,
@@ -613,6 +650,216 @@ async function removePreflightedSyncedCheckout(target, git, force) {
     await git.run(['worktree', 'prune'], { cwd: target.repoRoot });
     return { status: 'removed' };
 }
+async function probeTerminalRefs(target, expectedSha, git) {
+    const { probeSyncedTerminalRefs } = await import('./resolve-target.js');
+    return probeSyncedTerminalRefs(target, expectedSha, git);
+}
+function assertRetirementProbe(target, expectedSha, probe) {
+    if (probe.state === 'wrong-sha') {
+        if (probe.completedSha !== null && probe.completedSha !== expectedSha) {
+            throw new CliError(`Refusing to retire ${target.slug}: completed ref ${probe.completedRef} points to a different SHA (${probe.completedSha}) than the bound source SHA ${expectedSha}.`, 2);
+        }
+        throw new CliError(`Refusing to retire ${target.slug}: active source ref ${probe.activeRef} points to ${probe.activeSha ?? 'an unknown SHA'}, not the bound source SHA ${expectedSha}.`, 2);
+    }
+    if (probe.state === 'absent') {
+        throw new CliError(`Refusing to retire ${target.slug}: source ref ${probe.activeRef} is missing and completed ref ${probe.completedRef} does not preserve ${expectedSha}.`, 2);
+    }
+}
+function isTerminalRetirementProbe(probe) {
+    return probe.state === 'completed-only' || probe.state === 'both';
+}
+async function fallbackRemoteRefTransition(target, sourceSha, completedRef, completedExpectedSha, git) {
+    const create = await git.run([
+        'push',
+        `--force-with-lease=${completedRef}:${completedExpectedSha ?? ''}`,
+        target.remote,
+        `${sourceSha}:${completedRef}`,
+    ], { cwd: target.repoRoot, allowFailure: true });
+    if (create.code !== 0) {
+        const afterFailure = await probeTerminalRefs(target, sourceSha, git);
+        assertRetirementProbe(target, sourceSha, afterFailure);
+        if (isTerminalRetirementProbe(afterFailure))
+            return;
+        throw new CliError(`Remote ref retirement for ${target.slug} was rejected while creating ${completedRef}: ${create.stderr || create.stdout || 'unknown Git error'}`, 2);
+    }
+    const afterCreate = await probeTerminalRefs(target, sourceSha, git);
+    assertRetirementProbe(target, sourceSha, afterCreate);
+    if (!isTerminalRetirementProbe(afterCreate)) {
+        throw new CliError(`Remote ref retirement for ${target.slug} did not preserve both refs after completed-ref creation.`, 2);
+    }
+}
+async function transitionRemoteRefs(target, sourceSha, completedRef, completedExpectedSha, git) {
+    const result = await pushAtomicRefTransition(git, target.repoRoot, {
+        remote: target.remote,
+        sourceSha,
+        activeRef: target.ref,
+        completedRef,
+        completedExpectedSha,
+    });
+    if (result.code === 0)
+        return;
+    if (isAtomicPushUnsupported(result)) {
+        await fallbackRemoteRefTransition(target, sourceSha, completedRef, completedExpectedSha, git);
+        return;
+    }
+    const afterFailure = await probeTerminalRefs(target, sourceSha, git);
+    assertRetirementProbe(target, sourceSha, afterFailure);
+    if (!isTerminalRetirementProbe(afterFailure)) {
+        throw new CliError(`Remote ref retirement for ${target.slug} was rejected; active ref ${target.ref} was retained: ${result.stderr || result.stdout || 'unknown Git error'}`, 2);
+    }
+}
+async function localRefSha(target, ref, git) {
+    const result = await git.run(['show-ref', '--hash', ref], {
+        cwd: target.repoRoot,
+        allowFailure: true,
+    });
+    assertExpectedGitResult(`git show-ref --hash ${ref}`, result, [0, 1]);
+    return result.code === 0 ? result.stdout : null;
+}
+async function reconcileLocalTerminalRefs(target, sourceSha, completedRef, git) {
+    const [activeSha, completedSha] = await Promise.all([
+        localRefSha(target, target.ref, git),
+        localRefSha(target, completedRef, git),
+    ]);
+    if (activeSha !== null && activeSha !== sourceSha) {
+        throw new CliError(`Refusing local ref cleanup for ${target.slug}: ${target.ref} points to ${activeSha}, not ${sourceSha}.`, 2);
+    }
+    if (completedSha !== null && completedSha !== sourceSha) {
+        throw new CliError(`Refusing local ref cleanup for ${target.slug}: ${completedRef} points to ${completedSha}, not ${sourceSha}.`, 2);
+    }
+    if (completedSha === null) {
+        const object = await git.run(['cat-file', '-e', `${sourceSha}^{commit}`], {
+            cwd: target.repoRoot,
+            allowFailure: true,
+        });
+        if (object.code !== 0) {
+            await git.run([
+                'fetch',
+                '--no-tags',
+                '--no-write-fetch-head',
+                target.remote,
+                completedRef,
+            ], { cwd: target.repoRoot });
+            const afterFetch = await probeTerminalRefs(target, sourceSha, git);
+            assertRetirementProbe(target, sourceSha, afterFetch);
+            if (!isTerminalRetirementProbe(afterFetch)) {
+                throw new CliError(`Refusing local ref reconciliation for ${target.slug}: remote terminal refs changed while fetching ${completedRef}.`, 2);
+            }
+            await git.run(['cat-file', '-e', `${sourceSha}^{commit}`], {
+                cwd: target.repoRoot,
+            });
+        }
+        await git.run(['update-ref', completedRef, sourceSha], {
+            cwd: target.repoRoot,
+        });
+    }
+    if (activeSha !== null) {
+        await git.run(['update-ref', '-d', target.ref, sourceSha], {
+            cwd: target.repoRoot,
+        });
+    }
+    const [finalActiveSha, finalCompletedSha] = await Promise.all([
+        localRefSha(target, target.ref, git),
+        localRefSha(target, completedRef, git),
+    ]);
+    if (finalActiveSha !== null || finalCompletedSha !== sourceSha) {
+        throw new CliError(`Unable to verify local terminal refs for ${target.slug} after remote retirement.`, 2);
+    }
+}
+export async function retireSyncedRef(target, sourceSha, git) {
+    await assertCanonicalSyncTargetIdentity(target);
+    const initial = await probeTerminalRefs(target, sourceSha, git);
+    assertRetirementProbe(target, sourceSha, initial);
+    const completedRef = initial.completedRef;
+    if (initial.state === 'active-only') {
+        await transitionRemoteRefs(target, sourceSha, completedRef, initial.completedSha, git);
+    }
+    const terminal = await probeTerminalRefs(target, sourceSha, git);
+    assertRetirementProbe(target, sourceSha, terminal);
+    if (!isTerminalRetirementProbe(terminal)) {
+        throw new CliError(`Unable to verify a completed terminal state for ${target.slug}; completed ref ${completedRef} was not safely established.`, 2);
+    }
+    await reconcileLocalTerminalRefs(target, sourceSha, completedRef, git);
+    const activeAliasRetained = terminal.state === 'both';
+    return {
+        status: isTerminalRetirementProbe(initial) ? 'already-retired' : 'retired',
+        state: activeAliasRetained ? 'matching-aliases' : 'completed-only',
+        activeAliasRetained,
+        activeRef: target.ref,
+        completedRef,
+        verifiedSha: sourceSha,
+    };
+}
+function exactRemoteRefSha(result, remote, ref) {
+    if (classifyRemoteRefLookup(result, remote, ref) === 'absent')
+        return null;
+    const rows = result.stdout.split('\n').filter((row) => row.length > 0);
+    if (rows.length !== 1) {
+        throw new CliError(`Unable to verify ${remote}/${ref}: git ls-remote returned an unexpected number of exact-ref rows.`, 2);
+    }
+    const fields = rows[0]?.trim().split(/\s+/) ?? [];
+    if (fields.length !== 2 ||
+        fields[1] !== ref ||
+        !/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/i.test(fields[0] ?? '')) {
+        throw new CliError(`Unable to verify ${remote}/${ref}: git ls-remote returned a malformed or unexpected row.`, 2);
+    }
+    const [sha] = fields;
+    return sha;
+}
+export async function deleteCompletedSyncedRefForPrune(target, git) {
+    await assertCanonicalSyncTargetIdentity(target);
+    const completedRef = completedSyncedRefName(target.slug);
+    const [remote, localSha] = await Promise.all([
+        git.run(['ls-remote', '--exit-code', target.remote, completedRef], {
+            cwd: target.repoRoot,
+            allowFailure: true,
+        }),
+        localRefSha(target, completedRef, git),
+    ]);
+    const remoteSha = exactRemoteRefSha(remote, target.remote, completedRef);
+    if (remoteSha !== null) {
+        const deletion = await git.run([
+            'push',
+            `--force-with-lease=${completedRef}:${remoteSha}`,
+            target.remote,
+            `:${completedRef}`,
+        ], { cwd: target.repoRoot, allowFailure: true });
+        if (deletion.code !== 0) {
+            const afterRejection = exactRemoteRefSha(await git.run(['ls-remote', '--exit-code', target.remote, completedRef], { cwd: target.repoRoot, allowFailure: true }), target.remote, completedRef);
+            if (afterRejection !== null) {
+                if (afterRejection !== remoteSha) {
+                    throw new CliError(`Explicit prune stopped because remote completed ref ${completedRef} advanced from observed ${remoteSha} to ${afterRejection}; the advanced ref was retained. Review the new terminal identity and retry the destructive prune.`, 2);
+                }
+                throw new CliError(`Explicit prune could not delete retained terminal history at ${completedRef}; the local completed ref was retained. Restore access to ${target.remote} and retry the destructive prune: ${deletion.stderr || deletion.stdout || 'unknown Git error'}`, 2);
+            }
+        }
+        else {
+            const verifiedSha = exactRemoteRefSha(await git.run(['ls-remote', '--exit-code', target.remote, completedRef], { cwd: target.repoRoot, allowFailure: true }), target.remote, completedRef);
+            if (verifiedSha !== null) {
+                if (verifiedSha !== remoteSha) {
+                    throw new CliError(`Explicit prune stopped because remote completed ref ${completedRef} advanced from observed ${remoteSha} to ${verifiedSha}; the advanced ref was retained. Review the new terminal identity and retry the destructive prune.`, 2);
+                }
+                throw new CliError(`Explicit prune could not verify deletion of retained terminal history at ${completedRef}; the local completed ref was retained.`, 2);
+            }
+        }
+    }
+    if (localSha !== null) {
+        const localDeletion = await git.run(['update-ref', '-d', completedRef, localSha], { cwd: target.repoRoot, allowFailure: true });
+        if (localDeletion.code !== 0) {
+            const currentLocalSha = await localRefSha(target, completedRef, git);
+            if (currentLocalSha !== null) {
+                if (currentLocalSha !== localSha) {
+                    throw new CliError(`Explicit prune stopped because local completed ref ${completedRef} advanced from observed ${localSha} to ${currentLocalSha}; the advanced ref was retained. Review the new terminal identity and retry the destructive prune.`, 2);
+                }
+                throw new CliError(`Explicit prune could not delete local completed ref ${completedRef} at observed SHA ${localSha}; the ref was retained. Retry after resolving the local Git error: ${localDeletion.stderr || localDeletion.stdout || 'unknown Git error'}`, 2);
+            }
+        }
+    }
+    return {
+        completedRef,
+        deleted: remoteSha !== null || localSha !== null,
+    };
+}
 export async function pruneSynced(target, git, options) {
     await assertCanonicalSyncTargetIdentity(target);
     const scopeRelativeSyncedRoot = relative(resolve(target.repoRoot), resolve(target.syncedRoot));
@@ -678,15 +925,39 @@ export async function pruneSynced(target, git, options) {
             throw new CliError(`Refusing to prune ${target.slug}: checkout ${checkout.projectPath} is ${preflight.status}. Push it first or pass --force. Pinned PR links will stop resolving after prune.`, 1);
         }
     }
-    try {
-        await git.run(['push', target.remote, `:${target.ref}`], {
-            cwd: target.repoRoot,
-        });
+    if (options.expectedActiveAliasSha) {
+        const expectedSha = options.expectedActiveAliasSha;
+        const deletion = await git.run([
+            'push',
+            `--force-with-lease=${target.ref}:${expectedSha}`,
+            target.remote,
+            `:${target.ref}`,
+        ], { cwd: target.repoRoot, allowFailure: true });
+        const afterDeletion = await probeTerminalRefs(target, expectedSha, git);
+        if (afterDeletion.activeSha === null &&
+            afterDeletion.completedSha === expectedSha) {
+            // A rejected transport may still have applied the deletion. The
+            // authoritative postcondition is safe, so cleanup may continue.
+        }
+        else if (afterDeletion.activeSha !== null &&
+            afterDeletion.activeSha !== expectedSha) {
+            throw new CliError(`Explicit prune stopped because active alias ${target.ref} advanced from observed ${expectedSha} to ${afterDeletion.activeSha}; the advanced active ref, all checkouts, the discovery record, and completed history were retained. Reconcile the terminal ref mismatch before retrying.`, 1);
+        }
+        else {
+            throw new CliError(`Unable to safely delete matching active alias ${target.ref} at ${expectedSha}; no local checkouts or discovery records were removed and completed history was retained. Restore access to ${target.remote}, verify both terminal refs, and retry explicit prune: ${deletion.stderr || deletion.stdout || 'terminal postcondition was not established'}`, 2);
+        }
     }
-    catch (error) {
-        const detail = error instanceof Error ? error.message : String(error);
-        const forceFlag = options.force ? ' --force' : '';
-        throw new CliError(`Unable to delete remote ref ${target.ref}; no local checkouts were removed. Restore access to ${target.remote}, then retry oat project prune ${shellQuote(target.slug)}${forceFlag}. ${detail}`, 2);
+    else {
+        try {
+            await git.run(['push', target.remote, `:${target.ref}`], {
+                cwd: target.repoRoot,
+            });
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            const forceFlag = options.force ? ' --force' : '';
+            throw new CliError(`Unable to delete remote ref ${target.ref}; no local checkouts were removed. Restore access to ${target.remote}, then retry oat project prune ${shellQuote(target.slug)}${forceFlag}. ${detail}`, 2);
+        }
     }
     try {
         for (const checkout of checkouts) {

package/dist/commands/project/sync/resolve-target.d.ts

@@ -23,5 +23,15 @@ export interface ResolvedSyncTarget extends SyncTarget {
     adopt: boolean;
     adoptionRecord: AdoptionRecordState;
 }
+export type SyncedTerminalRefState = 'absent' | 'active-only' | 'completed-only' | 'both' | 'wrong-sha';
+export interface SyncedTerminalRefProbe {
+    state: SyncedTerminalRefState;
+    activeRef: string;
+    completedRef: string;
+    expectedSha: string;
+    activeSha: string | null;
+    completedSha: string | null;
+}
+export declare function probeSyncedTerminalRefs(target: SyncTarget, expectedSha: string, git: GitRunner): Promise<SyncedTerminalRefProbe>;
 export declare function resolveSyncedTarget(context: ResolveSyncedTargetContext, pathOrSlug?: string, overrides?: Partial<ResolveSyncedTargetDependencies>, options?: ResolveSyncedTargetOptions): Promise<ResolvedSyncTarget>;
 //# sourceMappingURL=resolve-target.d.ts.map

package/dist/commands/project/sync/resolve-target.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-target.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/sync/resolve-target.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAQ,MAAM,kBAAkB,CAAC;AAGlD,OAAO,EAAoB,KAAK,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAC9E,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAOjE,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAG7E,OAAO,EAIL,sBAAsB,EACtB,KAAK,mBAAmB,EACxB,KAAK,UAAU,EAChB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,0BAA0B;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB;AAED,MAAM,WAAW,0BAA0B;IACzC,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,wBAAwB,CAAC,EAAE,OAAO,CAAC;CACpC;AAED,MAAM,WAAW,+BAA+B;IAC9C,mBAAmB,EAAE,OAAO,mBAAmB,CAAC;IAChD,sBAAsB,EAAE,OAAO,sBAAsB,CAAC;IACtD,kBAAkB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAClE,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/C,QAAQ,EAAE,OAAO,QAAQ,CAAC;IAC1B,SAAS,EAAE,SAAS,CAAC;CACtB;AAED,MAAM,WAAW,kBAAmB,SAAQ,UAAU;IACpD,KAAK,EAAE,OAAO,CAAC;IACf,cAAc,EAAE,mBAAmB,CAAC;CACrC;AAsFD,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,0BAA0B,EACnC,UAAU,CAAC,EAAE,MAAM,EACnB,SAAS,GAAE,OAAO,CAAC,+BAA+B,CAAM,EACxD,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,kBAAkB,CAAC,CA+H7B"}
+{"version":3,"file":"resolve-target.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/sync/resolve-target.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAQ,MAAM,kBAAkB,CAAC;AAGlD,OAAO,EAAoB,KAAK,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAC9E,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAQjE,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAG7E,OAAO,EAIL,sBAAsB,EACtB,KAAK,mBAAmB,EACxB,KAAK,UAAU,EAChB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,0BAA0B;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB;AAED,MAAM,WAAW,0BAA0B;IACzC,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,wBAAwB,CAAC,EAAE,OAAO,CAAC;CACpC;AAED,MAAM,WAAW,+BAA+B;IAC9C,mBAAmB,EAAE,OAAO,mBAAmB,CAAC;IAChD,sBAAsB,EAAE,OAAO,sBAAsB,CAAC;IACtD,kBAAkB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAClE,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/C,QAAQ,EAAE,OAAO,QAAQ,CAAC;IAC1B,SAAS,EAAE,SAAS,CAAC;CACtB;AAED,MAAM,WAAW,kBAAmB,SAAQ,UAAU;IACpD,KAAK,EAAE,OAAO,CAAC;IACf,cAAc,EAAE,mBAAmB,CAAC;CACrC;AAED,MAAM,MAAM,sBAAsB,GAC9B,QAAQ,GACR,aAAa,GACb,gBAAgB,GAChB,MAAM,GACN,WAAW,CAAC;AAEhB,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,sBAAsB,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AA+DD,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,UAAU,EAClB,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,SAAS,GACb,OAAO,CAAC,sBAAsB,CAAC,CA+BjC;AAsFD,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,0BAA0B,EACnC,UAAU,CAAC,EAAE,MAAM,EACnB,SAAS,GAAE,OAAO,CAAC,+BAA+B,CAAM,EACxD,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,kBAAkB,CAAC,CA+H7B"}