@open-agent-toolkit/cli 0.2.49 → 0.2.51

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"}

package/dist/commands/project/sync/resolve-target.js

@@ -2,10 +2,65 @@ import { realpath, stat } from 'node:fs/promises';
 import { isAbsolute, relative, resolve, sep } from 'node:path';
 import { defaultGitRunner } from '../../project/sync/git.js';
 import { resolveProjectsRoot } from '../../shared/oat-paths.js';
-import { assertValidProjectSlug, resolveProjectScope, resolveScopeRoot, syncedRecordPath, } from '../../shared/project-scope.js';
+import { assertValidProjectSlug, completedSyncedRefName, resolveProjectScope, resolveScopeRoot, syncedRecordPath, } from '../../shared/project-scope.js';
 import { readOatLocalConfig } from '../../../config/oat-config.js';
 import { CliError } from '../../../errors/cli-error.js';
 import { assertCanonicalSyncTargetIdentity, buildSyncTarget, classifyRemoteRefLookup, classifyAdoptionRecord, } from './ref-sync.js';
+async function remoteTerminalRefShas(target, activeRef, completedRef, git) {
+    const result = await git.run(['ls-remote', '--exit-code', target.remote, activeRef, completedRef], { cwd: target.repoRoot, allowFailure: true });
+    if (classifyRemoteRefLookup(result, target.remote, `${activeRef} and ${completedRef}`) === 'absent') {
+        return { activeSha: null, completedSha: null };
+    }
+    const requestedRefs = new Set([activeRef, completedRef]);
+    const advertised = new Map();
+    const rows = result.stdout.split('\n').filter((row) => row.length > 0);
+    if (rows.length === 0) {
+        throw new CliError(`Unable to verify terminal refs for ${target.slug}: git ls-remote returned a malformed empty advertisement.`, 2);
+    }
+    for (const row of rows) {
+        const fields = row.trim().split(/\s+/);
+        if (fields.length !== 2 ||
+            !/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/i.test(fields[0] ?? '')) {
+            throw new CliError(`Unable to verify terminal refs for ${target.slug}: git ls-remote returned a malformed row.`, 2);
+        }
+        const [sha, ref] = fields;
+        if (!requestedRefs.has(ref)) {
+            throw new CliError(`Unable to verify terminal refs for ${target.slug}: git ls-remote returned unexpected ref ${ref}.`, 2);
+        }
+        if (advertised.has(ref)) {
+            throw new CliError(`Unable to verify terminal refs for ${target.slug}: git ls-remote returned duplicate rows for ${ref}.`, 2);
+        }
+        advertised.set(ref, sha);
+    }
+    return {
+        activeSha: advertised.get(activeRef) ?? null,
+        completedSha: advertised.get(completedRef) ?? null,
+    };
+}
+export async function probeSyncedTerminalRefs(target, expectedSha, git) {
+    const activeRef = target.ref;
+    const completedRef = completedSyncedRefName(target.slug);
+    const { activeSha, completedSha } = await remoteTerminalRefShas(target, activeRef, completedRef, git);
+    const wrongSha = (activeSha !== null && activeSha !== expectedSha) ||
+        (completedSha !== null && completedSha !== expectedSha);
+    const state = wrongSha
+        ? 'wrong-sha'
+        : activeSha !== null && completedSha !== null
+            ? 'both'
+            : activeSha !== null
+                ? 'active-only'
+                : completedSha !== null
+                    ? 'completed-only'
+                    : 'absent';
+    return {
+        state,
+        activeRef,
+        completedRef,
+        expectedSha,
+        activeSha,
+        completedSha,
+    };
+}
 async function pathExists(path) {
     try {
         await stat(path);

package/dist/commands/shared/project-scope.d.ts

@@ -1,6 +1,7 @@
 export type ProjectScope = 'shared' | 'local' | 'synced';
 export declare const PROJECT_SCOPES: readonly ["shared", "local", "synced"];
 export declare const SYNCED_REF_NAMESPACE = "refs/oat/projects";
+export declare const COMPLETED_SYNCED_REF_NAMESPACE = "refs/oat/completed";
 export declare const SYNCED_REMOTE = "origin";
 export declare function canonicalizePath(path: string): string;
 interface EffectiveConfigResult {
@@ -16,6 +17,7 @@ export declare function resolveScopeRoot(repoRoot: string, projectsRoot: string,
 export declare function resolveProjectScope(projectPath: string, projectsRoot: string, repoRoot: string): ProjectScope | null;
 export declare function assertValidProjectSlug(slug: string, exitCode?: 1 | 2): void;
 export declare function syncedRefName(slug: string): string;
+export declare function completedSyncedRefName(slug: string): string;
 export declare function syncedRecordPath(scopeRoot: string, slug: string): string;
 export declare function isSyncedCheckout(projectPath: string): Promise<boolean>;
 export declare function resolveDefaultScope(repoRoot: string, env: NodeJS.ProcessEnv, dependencies?: Partial<ProjectScopeDependencies>): Promise<ProjectScope>;

package/dist/commands/shared/project-scope.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"project-scope.d.ts","sourceRoot":"","sources":["../../../src/commands/shared/project-scope.ts"],"names":[],"mappings":"AAgBA,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEzD,eAAO,MAAM,cAAc,wCAIiB,CAAC;AAC7C,eAAO,MAAM,oBAAoB,sBAAsB,CAAC;AACxD,eAAO,MAAM,aAAa,WAAW,CAAC;AAItC,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAoBrD;AAED,UAAU,qBAAqB;IAC7B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CAC9C;AAED,UAAU,wBAAwB;IAChC,sBAAsB,EAAE,CACtB,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,qBAAqB,CAAC,CAAC;CACrC;AAMD,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,GACnB,MAAM,CAKR;AAED,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,YAAY,GAClB,MAAM,CAOR;AAED,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,GACf,YAAY,GAAG,IAAI,CAmBrB;AAED,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,QAAQ,GAAE,CAAC,GAAG,CAAK,GAClB,IAAI,CAON;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGlD;AAED,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAGxE;AAED,wBAAsB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAa5E;AAeD,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,CAAC,UAAU,EACtB,YAAY,GAAE,OAAO,CAAC,wBAAwB,CAAM,GACnD,OAAO,CAAC,YAAY,CAAC,CAqBvB"}
+{"version":3,"file":"project-scope.d.ts","sourceRoot":"","sources":["../../../src/commands/shared/project-scope.ts"],"names":[],"mappings":"AAgBA,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEzD,eAAO,MAAM,cAAc,wCAIiB,CAAC;AAC7C,eAAO,MAAM,oBAAoB,sBAAsB,CAAC;AACxD,eAAO,MAAM,8BAA8B,uBAAuB,CAAC;AACnE,eAAO,MAAM,aAAa,WAAW,CAAC;AAItC,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAoBrD;AAED,UAAU,qBAAqB;IAC7B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CAC9C;AAED,UAAU,wBAAwB;IAChC,sBAAsB,EAAE,CACtB,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,qBAAqB,CAAC,CAAC;CACrC;AAMD,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,GACnB,MAAM,CAKR;AAED,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,YAAY,GAClB,MAAM,CAOR;AAED,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,GACf,YAAY,GAAG,IAAI,CAmBrB;AAED,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,QAAQ,GAAE,CAAC,GAAG,CAAK,GAClB,IAAI,CAON;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGlD;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAG3D;AAED,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAGxE;AAED,wBAAsB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAa5E;AAeD,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,CAAC,UAAU,EACtB,YAAY,GAAE,OAAO,CAAC,wBAAwB,CAAM,GACnD,OAAO,CAAC,YAAY,CAAC,CAqBvB"}

package/dist/commands/shared/project-scope.js

@@ -10,6 +10,7 @@ export const PROJECT_SCOPES = [
     'synced',
 ];
 export const SYNCED_REF_NAMESPACE = 'refs/oat/projects';
+export const COMPLETED_SYNCED_REF_NAMESPACE = 'refs/oat/completed';
 export const SYNCED_REMOTE = 'origin';
 const PROJECT_SLUG_PATTERN = /^[a-zA-Z0-9_-]+$/;
 export function canonicalizePath(path) {
@@ -69,6 +70,10 @@ export function syncedRefName(slug) {
     assertValidProjectSlug(slug);
     return `${SYNCED_REF_NAMESPACE}/${slug}`;
 }
+export function completedSyncedRefName(slug) {
+    assertValidProjectSlug(slug);
+    return `${COMPLETED_SYNCED_REF_NAMESPACE}/${slug}`;
+}
 export function syncedRecordPath(scopeRoot, slug) {
     assertValidProjectSlug(slug);
     return join(scopeRoot, `${slug}.json`);

package/dist/commands/state/generate.d.ts

@@ -1,3 +1,4 @@
+import { type GitRunner } from '../project/sync/git.js';
 export interface GitOperations {
     isGitRepo(root: string): boolean;
     diffFileCount(root: string, sha: string): number;
@@ -7,6 +8,7 @@ export interface GenerateStateOptions {
     env?: NodeJS.ProcessEnv;
     today?: string;
     git?: GitOperations;
+    gitRunner?: GitRunner;
 }
 export interface GenerateStateResult {
     dashboardPath: string;

package/dist/commands/state/generate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../../src/commands/state/generate.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACjC,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CAClD;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,aAAa,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IAClC,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAiHD,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAEvE;AAydD,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,mBAAmB,CAAC,CA2C9B"}
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../../src/commands/state/generate.ts"],"names":[],"mappings":"AAQA,OAAO,EAAoB,KAAK,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAU9E,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACjC,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CAClD;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,aAAa,CAAC;IACpB,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED,MAAM,WAAW,mBAAmB;IAClC,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAiHD,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAEvE;AAsgBD,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,mBAAmB,CAAC,CAkF9B"}