@event4u/agent-config 16.3.0 → 16.4.0

package/src/scripts/sync_pr_branch.ts

@@ -26,8 +26,36 @@
  * conflict-count reduction and must not be banked as drawdown (AI council
  * 2026-08-21, both seats; roadmap road-to-merge-hotspot-drawdown).
  *
- * Exit codes: 0 = already current, or merged cleanly · 1 = conflict, or the base
- * could not be resolved · 2 = internal error. `scanned:` on every path.
+ * The base is the explicit `--base`, else the default branch. Nothing here asks
+ * a forge which pull request the branch belongs to: a caller acting on a pull
+ * request passes its base, and without `--base` the run is about the default
+ * branch, which is right only for a branch that targets it.
+ *
+ * Exit codes: 0 = already current, or merged cleanly, or `unverified` (the
+ * target resolved but its commit could not be fetched, or a base ref's own
+ * fetch failed; nothing was touched) ·
+ * 1 = conflict, git refusing the merge before it starts (a dirty tree, an
+ * untracked file in the way — git's own line is printed), a merge that stopped
+ * part-way (MERGE_HEAD set, or the merge half-applied in the index — the line
+ * names `git merge --abort` or `git reset --merge`), or the base could
+ * not be resolved (no `--base` and no default
+ * branch, a `--base` the server does not know, no origin, or origin unreachable
+ * at the ref lookup) · 2 = internal error · 3 = behind, and
+ * `git.update_strategy` is not `merge`, so the merge was refused (reason code
+ * `TARGET_POLICY_STALE` when the branch is current with its non-default target
+ * and that target is itself behind the default branch the policy adds — the
+ * target's update, not this branch's; a branch also behind the target gets the
+ * ordinary behind line first, naming the target's lag as a note) · 4 =
+ * `git.update_strategy` cannot be read (a settings file or a committed
+ * `.git-convention.yml` that does not parse, a value outside the schema, or a
+ * value only a user-global file carries), so nothing was checked or merged; the line carries a stable reason
+ * code (`git-convention-malformed` / `-invalid` / `-discarded` /
+ * `-unresolvable`) and the file.
+ * `scanned:` on every path.
+ *
+ * The merge has its own timeout, 300 s, since it runs hooks and writes the work
+ * tree; `AGENT_CONFIG_SYNC_MERGE_TIMEOUT_MS` overrides it. Every other git call
+ * stays on the 8 s network bound.
  */
 
 import * as path from 'node:path';
@@ -40,9 +68,25 @@ import {
     loadPolicyAtSha,
     type ShaFileReader,
 } from './_lib/branch_convergence.js';
+import { checkoutSource, describeRefusal, isRefusal, readGitConventionKey, type GitConventionReading } from './_lib/git_convention.js';
+import {
+    conventionRoot,
+    ignoredCarrierWarning,
+    makeTargetDeps,
+    memoTargetDeps,
+    parseSymrefDefault,
+    readCommittedConvention,
+    resolveTarget,
+    type ConventionTarget,
+    type TargetDeps,
+} from './_lib/git_convention_carrier.js';
+import { baseValueError, splitResolvedRef } from './_lib/git_base_ref.js';
 import { reportScanned } from './_lib/scan_scope.js';
 
+export { parseSymrefDefault };
+
 const NETWORK_TIMEOUT_MS = 8_000;
+const MERGE_TIMEOUT_MS = 300_000;
 
 /** Paths that are GENERATED — a conflict here is regenerated, never hand-merged. */
 const GENERATED = [
@@ -165,14 +209,28 @@ const GENERATED_PATTERNS: readonly { readonly re: RegExp; readonly why: string }
  */
 const REMEASURED = ['src/config/gate-violation-baselines.json'];
 
-function sh(cmd: string, args: readonly string[], cwd: string): { ok: boolean; out: string; err: string } {
+function sh(
+    cmd: string,
+    args: readonly string[],
+    cwd: string,
+    timeout: number = NETWORK_TIMEOUT_MS,
+): { ok: boolean; out: string; err: string; killed: boolean } {
     const r = spawnSync(cmd, [...args], {
         cwd,
         encoding: 'utf-8',
-        timeout: NETWORK_TIMEOUT_MS,
+        timeout,
         maxBuffer: 32 * 1024 * 1024,
     });
-    return { ok: r.status === 0, out: r.stdout ?? '', err: (r.stderr ?? '').trim() };
+    return { ok: r.status === 0, out: r.stdout ?? '', err: (r.stderr ?? '').trim(), killed: r.signal !== null };
+}
+
+/**
+ * A merge runs hooks and writes the work tree, so the network timeout is the
+ * wrong bound for it: killed mid-flight it leaves MERGE_HEAD behind.
+ */
+function mergeTimeoutMs(): number {
+    const n = Number(process.env['AGENT_CONFIG_SYNC_MERGE_TIMEOUT_MS']);
+    return Number.isInteger(n) && n > 0 ? n : MERGE_TIMEOUT_MS;
 }
 
 /** True when `rel` is a generated artefact rather than an authored one. */
@@ -232,6 +290,28 @@ export interface Plan {
     remeasured: string[];
     authored: string[];
     scanned: number;
+    /** Base refs the branch is behind — set by a dry run, so a caller can decide without parsing `message`. */
+    behind?: number;
+    /**
+     * Set when the policy added the default branch and the TARGET itself is
+     * behind it: updating the branch onto the target cannot make it current.
+     * `branchBehind` is how far the branch is behind the target itself; only at
+     * 0 is the target's update the one a reader needs, not this branch's.
+     */
+    targetStale?: { target: string; defaultRef: string; behind: number; branchBehind: number };
+    /** The base-set summary and the per-ref behind list a dry run found, so a caller can word its own line. */
+    summary?: string;
+    behindDetail?: string;
+}
+
+/** The refusal for a branch that is behind under a strategy other than `merge`. */
+export function behindRefusalMessage(plan: Plan, strategy: string): string {
+    const t = plan.targetStale;
+    return (
+        `⚠️  sync_pr_branch: refused — the branch is behind and git.update_strategy is \`${strategy}\`; this script only merges. ` +
+        `Rebase on request instead (git-workflow references/branch-update.md). ${plan.summary ?? ''}. Behind: ${plan.behindDetail ?? '?'}.` +
+        (t === undefined ? '' : ` The target ${t.target} is itself ${String(t.behind)} commit(s) behind ${t.defaultRef}; once this branch is current with it, the target needs updating too.`)
+    );
 }
 
 /**
@@ -297,15 +377,14 @@ export function renderConflictReport(plan: Plan): string {
 /**
  * Why the base is a SET now, and what each entry means.
  *
- * The old resolution was an EXCLUSIVE chain — `--base`, then the open PR's
- * base, then `origin/HEAD` — so a PR targeting a release line or a stacked
+ * The old resolution was an EXCLUSIVE chain — `--base`, then `origin/HEAD` —
+ * so a PR targeting a release line or a stacked
  * parent was kept current with its target and arbitrarily stale against the
  * default branch. Whether the default belongs in the set is a policy question
  * decided per target and read from the TARGET's own commit; see
  * `_lib/branch_convergence.ts` for the decision and the trust boundary.
  */
 export type BaseReason =
-    | 'pull-request-target'
     | 'explicit-base-override'
     | 'repository-default-branch'
     | 'branch-convergence-policy:include-default';
@@ -327,7 +406,7 @@ export interface ResolveBaseResult {
     readonly policyStatus: 'applied' | 'not-required' | 'disabled';
 }
 
-/** Neither an open PR nor a default branch answered. Distinct from a missing policy. */
+/** Neither `--base` nor a default branch answered. Distinct from a missing policy. */
 export class UnresolvableBase extends Error {
     constructor(detail: string) {
         super(`unresolvable — ${detail}`);
@@ -339,66 +418,17 @@ export class UnresolvableBase extends Error {
  * The git questions base resolution asks, as data.
  *
  * Injected rather than called inline so the twelve council fixtures can be
- * exercised without a network, a forge, or a real release line — this
+ * exercised without a network or a real release line — this
  * repository has none, so a live fixture could only ever cover the
  * default-target path.
  */
-export interface BaseDeps {
-    readonly currentBranch: () => string;
-    /** The open PR's `baseRefName`, bare (`release/1.x`), or null. */
-    readonly prBase: (branch: string) => string | null;
-    /** The default branch as a remote-tracking ref (`origin/main`), or null. */
-    readonly defaultBranch: () => string | null;
-    /** The SHA the server reports for a ref right now, or null. */
-    readonly remoteSha: (ref: string) => string | null;
+export interface BaseDeps extends TargetDeps {
     readonly readAtSha: ShaFileReader;
 }
 
 export function makeGitDeps(repo: string): BaseDeps {
     return {
-        currentBranch: (): string => sh('git', ['rev-parse', '--abbrev-ref', 'HEAD'], repo).out.trim(),
-        prBase: (branch: string): string | null => {
-            if (branch === '' || branch === 'HEAD') return null;
-            // The forge knows the REAL base, which matters for a stacked or
-            // release-line PR: measuring against the repo default would compare
-            // against a branch this PR never merges into.
-            const pr = sh('gh', ['pr', 'list', '--head', branch, '--state', 'open', '--json', 'baseRefName', '--limit', '1'], repo);
-            if (!pr.ok) return null;
-            try {
-                const rows = JSON.parse(pr.out || '[]') as Array<{ baseRefName?: string }>;
-                const b = rows[0]?.baseRefName;
-                return typeof b === 'string' && b !== '' ? b : null;
-            } catch {
-                return null;
-            }
-        },
-        // ASK THE SERVER first, and only then fall back to the local ref.
-        //
-        // The local-only form was this module's whole answer until the default
-        // branch became load-bearing here: the policy's `include` needs a ref to
-        // add, and the target-is-default identity check needs one to compare
-        // against. Measured in this worktree on 2026-09-03 — `refs/remotes/
-        // origin/HEAD` is not set, so the local form returned null and
-        // `sync_pr_branch` reported "no open PR and no origin/HEAD" while
-        // `check_branch_freshness`, standing three lines away in the same
-        // sequence, resolved `origin/main` from the server symref and passed.
-        // Two resolvers disagreeing about the base is the defect this roadmap
-        // exists to close, one layer down. Mirrors
-        // `check_branch_freshness.ts:223` `serverDefaultBase`.
-        defaultBranch: (): string | null => {
-            const remote = sh('git', ['ls-remote', '--symref', 'origin', 'HEAD'], repo);
-            const fromServer = remote.ok ? parseSymrefDefault(remote.out) : null;
-            if (fromServer !== null) return fromServer;
-            const head = sh('git', ['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'], repo);
-            return head.ok && head.out.trim() !== '' ? head.out.trim() : null;
-        },
-        remoteSha: (ref: string): string | null => {
-            const bare = ref.replace(/^origin\//, '');
-            const out = sh('git', ['ls-remote', '--heads', 'origin', bare], repo);
-            if (!out.ok) return null;
-            const sha = out.out.trim().split(/\s+/)[0];
-            return sha !== undefined && /^[0-9a-f]{40}$/.test(sha) ? sha : null;
-        },
+        ...makeTargetDeps(repo),
         // `git show <sha>:<path>` and nothing else. There is no filesystem read
         // here by construction: a policy the PR head carries must not be able to
         // change the criteria the PR is judged against.
@@ -409,36 +439,15 @@ export function makeGitDeps(repo: string): BaseDeps {
     };
 }
 
-/**
- * The default branch the SERVER reports, from `git ls-remote --symref origin HEAD`.
- *
- * Pure and exported so the parse is testable without a network round trip, and
- * because it closes a measured defect rather than a hypothetical one. Until
- * 2026-09-03 this module read the default branch from `refs/remotes/origin/HEAD`
- * alone — a clone-time ref that is simply absent in some checkouts. Measured in
- * a worktree of this repository the same day: the local form returned null, so
- * `sync_pr_branch` refused with "no open PR and no origin/HEAD" while
- * `check_branch_freshness`, three lines later in the same documented sequence,
- * resolved `origin/main` from the server symref and passed. Two resolvers
- * disagreeing about the base is this roadmap's own subject one layer down, and
- * the default branch stopped being cosmetic here the moment the policy's
- * `include` needed a ref to add. Mirrors `check_branch_freshness.ts:223`.
- */
-export function parseSymrefDefault(lsRemoteOut: string): string | null {
-    for (const line of lsRemoteOut.split('\n')) {
-        const t = line.trim();
-        if (!t.startsWith('ref:')) continue;
-        const name = t.slice('ref:'.length).trim().split(/\s+/)[0] ?? '';
-        if (!name.startsWith('refs/heads/')) continue;
-        const short = name.slice('refs/heads/'.length).trim();
-        if (short !== '') return `origin/${short}`;
-    }
-    return null;
-}
-
 /** Strip the remote prefix so a policy key is the branch name a human writes. */
 function bareName(ref: string): string {
-    return ref.replace(/^origin\//, '');
+    return splitResolvedRef(ref).branch;
+}
+
+function sameRemoteBranch(a: string, b: string): boolean {
+    const x = splitResolvedRef(a);
+    const y = splitResolvedRef(b);
+    return x.remote === y.remote && x.branch === y.branch;
 }
 
 /**
@@ -453,27 +462,24 @@ function bareName(ref: string): string {
 export function resolveBase(repo: string, override: string | null, deps: BaseDeps = makeGitDeps(repo)): ResolveBaseResult {
     const defaultRef = deps.defaultBranch();
 
-    let target: BaseEntry;
-    if (override !== null && override.trim() !== '') {
-        target = { ref: override.trim(), reason: 'explicit-base-override' };
-    } else {
-        const pr = deps.prBase(deps.currentBranch());
-        if (pr !== null) {
-            target = { ref: `origin/${pr}`, reason: 'pull-request-target' };
-        } else if (defaultRef !== null) {
-            target = { ref: defaultRef, reason: 'repository-default-branch' };
-        } else {
-            throw new UnresolvableBase('no open PR and no origin/HEAD');
-        }
+    const target = resolveTarget(deps, override, defaultRef);
+    if (target === null) {
+        throw new UnresolvableBase('no --base and no origin/HEAD');
     }
 
-    // A PR targeting the default branch needs no entry — identity by ref name,
-    // or by the SHA both names resolve to.
-    const sameName = defaultRef !== null && bareName(target.ref) === bareName(defaultRef);
+    // A PR targeting the default branch needs no entry — identity by remote and
+    // branch name, or by the SHA both names resolve to. The branch name alone is
+    // not identity: `upstream/main` can sit on a different commit than `origin/main`.
+    const sameName = defaultRef !== null && sameRemoteBranch(target.ref, defaultRef);
     const targetSha = deps.remoteSha(target.ref);
     const defaultSha = defaultRef === null ? null : deps.remoteSha(defaultRef);
     const sameSha = targetSha !== null && defaultSha !== null && targetSha === defaultSha;
-    if (sameName || sameSha) {
+    // A fork layout: the pull request targets the default branch of the
+    // remote it names (`upstream/main`), not a release line of origin.
+    const targetRemote = splitResolvedRef(target.ref).remote;
+    const ownDefault = sameName || sameSha || (defaultRef !== null && splitResolvedRef(defaultRef).remote === targetRemote) ? null : (deps.defaultBranchOf?.(targetRemote) ?? null);
+    const ownName = ownDefault !== null && sameRemoteBranch(target.ref, ownDefault);
+    if (sameName || sameSha || ownName) {
         return { entries: [target], policyStatus: 'not-required' };
     }
 
@@ -527,8 +533,6 @@ export function describeReason(reason: BaseReason): string {
     switch (reason) {
         case 'explicit-base-override':
             return 'given by --base';
-        case 'pull-request-target':
-            return 'the open PR base';
         case 'repository-default-branch':
             return 'the repo default branch';
         case 'branch-convergence-policy:include-default':
@@ -569,6 +573,8 @@ export interface IntegrationAttempt {
 
 export interface IntegrationOutcome {
     readonly ok: boolean;
+    /** Set when `checkPin` refused the pinned set: nothing was merged. */
+    readonly stopped?: boolean;
     readonly attempts: readonly IntegrationAttempt[];
     readonly conflicted: readonly string[];
     readonly message: string;
@@ -577,7 +583,10 @@ export interface IntegrationOutcome {
 /** The git operations the retry loop needs, injected so a moving base is testable. */
 export interface IntegrateOps {
     readonly remoteSha: (ref: string) => string | null;
-    readonly merge: (ref: string) => { ok: boolean; conflicted: string[] };
+    /** Merges `sha`, the pinned commit of `ref`; `error` is a refusal that is not a conflict. */
+    readonly merge: (ref: string, sha: string | null) => { ok: boolean; conflicted: string[]; error?: string };
+    /** Asked once, before the first merge, with the pinned OIDs; a message stops the run. */
+    readonly checkPin?: (pinned: readonly { ref: string; before: string | null }[]) => string | null;
 }
 
 function renderAttempts(attempts: readonly IntegrationAttempt[]): string {
@@ -600,10 +609,15 @@ export function integrateWithPinnedBase(refs: readonly string[], ops: IntegrateO
     const attempts: IntegrationAttempt[] = [];
     for (let n = 1; n <= MAX_BASE_ATTEMPTS; n++) {
         const pinned = refs.map((ref) => ({ ref, before: ops.remoteSha(ref) }));
+        // Only before the first merge: once one has landed, a "nothing was
+        // merged" stop would misreport the tree, so a later move is a base move.
+        const stop = n === 1 ? (ops.checkPin?.(pinned) ?? null) : null;
+        if (stop !== null) return { ok: false, stopped: true, attempts, conflicted: [], message: stop };
         let conflicted: string[] = [];
         let clean = true;
         for (const q of pinned) {
-            const m = ops.merge(q.ref);
+            const m = ops.merge(q.ref, q.before);
+            if (!m.ok && m.error !== undefined) return { ok: false, attempts, conflicted: [], message: m.error };
             if (!m.ok) {
                 clean = false;
                 conflicted = m.conflicted;
@@ -639,6 +653,69 @@ export function integrateWithPinnedBase(refs: readonly string[], ops: IntegrateO
     };
 }
 
+/**
+ * Merge exactly the commit the pin and the policy check were about.
+ *
+ * The run fetched once, before the pin, so the local tracking ref may name an
+ * older commit, or a newer one when the policy re-read fetched. It is fetched
+ * again when it differs from the pin, and the pinned SHA itself is merged when
+ * the ref still names another commit. A merge that leaves HEAD without the
+ * pinned commit is a refusal, never a success.
+ */
+function mergePinned(repo: string, ref: string, sha: string | null): { ok: boolean; conflicted: string[]; error?: string } {
+    const tracking = (): string => sh('git', ['rev-parse', '--verify', '-q', `${ref}^{commit}`], repo).out.trim();
+    let target = ref;
+    if (sha !== null && tracking() !== sha) {
+        const { remote, branch } = splitResolvedRef(ref);
+        sh('git', ['fetch', '--', remote, `+refs/heads/${branch}:refs/remotes/${remote}/${branch}`], repo);
+        if (tracking() !== sha) {
+            if (!sh('git', ['cat-file', '-e', `${sha}^{commit}`], repo).ok) {
+                return { ok: false, conflicted: [], error: `the pinned commit ${sha.slice(0, 12)} of ${ref} could not be fetched — nothing was merged for it.` };
+            }
+            target = sha;
+        }
+    }
+    const indexWasClean = sh('git', ['diff', '--cached', '--quiet'], repo).ok;
+    const m = sh('git', ['merge', '--no-edit', target], repo, mergeTimeoutMs());
+    if (!m.ok) {
+        // A merge git refuses before it starts (local changes it would
+        // overwrite, an untracked file in the way) leaves no unmerged path.
+        const conflicted = sh('git', ['diff', '--name-only', '--diff-filter=U'], repo).out.split('\n').filter((p) => p.trim() !== '');
+        if (conflicted.length > 0) return { ok: false, conflicted };
+        // A staged difference that was not there before came from this merge —
+        // a killed git leaves one with no MERGE_HEAD to abort. Staged work the
+        // user had is not a half-applied merge, and resetting it would lose it.
+        const how = m.killed ? `was stopped after ${String(mergeTimeoutMs() / 1000)} s` : 'did not complete';
+        if (sh('git', ['rev-parse', '-q', '--verify', 'MERGE_HEAD'], repo).ok) {
+            return {
+                ok: false,
+                conflicted: [],
+                error:
+                    `the merge of ${ref} ${how} and left a merge in progress (MERGE_HEAD is set) — ` +
+                    'finish it with `git commit` or discard it with `git merge --abort`.',
+            };
+        }
+        if (indexWasClean && !sh('git', ['diff', '--cached', '--quiet'], repo).ok) {
+            return {
+                ok: false,
+                conflicted: [],
+                error:
+                    `the merge of ${ref} ${how} and left it half-applied in the index (no MERGE_HEAD) — ` +
+                    'discard it with `git reset --merge`.',
+            };
+        }
+        if (m.killed) {
+            return { ok: false, conflicted: [], error: `the merge of ${ref} was stopped after ${String(mergeTimeoutMs() / 1000)} s before it changed anything — nothing was merged for it.` };
+        }
+        const why = (m.err || m.out).trim().split('\n').join(' ');
+        return { ok: false, conflicted: [], error: `git refused to merge ${ref}: ${why || 'no reason given'} — nothing was merged for it.` };
+    }
+    if (sha !== null && !sh('git', ['merge-base', '--is-ancestor', sha, 'HEAD'], repo).ok) {
+        return { ok: false, conflicted: [], error: `the merge of ${ref} left HEAD without its pinned commit ${sha.slice(0, 12)}.` };
+    }
+    return { ok: true, conflicted: [] };
+}
+
 /** The regeneration operations Phase 3 needs, injected so no real conflict is required. */
 export interface RegenOps {
     readonly regenerate: () => { ok: boolean; err: string };
@@ -731,10 +808,19 @@ function gitRegenOps(repo: string): RegenOps {
     };
 }
 
-export function sync(repo: string, baseOverride: string | null, dryRun: boolean, autoResolve = false): Plan {
+/**
+ * What the merge path needs beyond the base set. `live` answers the last-moment
+ * pin and is never memoised — a memoised pin could not see the target move.
+ */
+export interface SyncOptions {
+    readonly live?: TargetDeps;
+    readonly checkPin?: IntegrateOps['checkPin'];
+}
+
+export function sync(repo: string, baseOverride: string | null, dryRun: boolean, autoResolve = false, deps?: BaseDeps, opts: SyncOptions = {}): Plan {
     let resolved: ResolveBaseResult;
     try {
-        resolved = resolveBase(repo, baseOverride);
+        resolved = resolveBase(repo, baseOverride, deps ?? makeGitDeps(repo));
     } catch (exc) {
         // A missing policy, an unresolvable target SHA and an unresolvable base
         // are all REFUSALS carrying their own typed message. None of them
@@ -751,13 +837,14 @@ export function sync(repo: string, baseOverride: string | null, dryRun: boolean,
     const summary = renderBaseSummary(resolved);
     const order = integrationOrder(resolved);
 
-    const fetched = sh('git', ['fetch', 'origin', '--prune'], repo);
-    if (!fetched.ok) {
+    const remotes = [...new Set(['origin', ...order.map((ref) => splitResolvedRef(ref).remote)])];
+    const failed = remotes.map((remote) => ({ remote, ...sh('git', ['fetch', '--prune', '--', remote], repo) })).find((f) => !f.ok);
+    if (failed !== undefined) {
         // Unreachable remote is not "already current" — saying so is the whole
         // point, since a silent pass here reproduces the staleness this closes.
         return {
             exit: 0,
-            message: `unverified — could not fetch origin (${fetched.err.split('\n')[0] ?? '?'}). Base freshness NOT checked.`,
+            message: `unverified — could not fetch ${failed.remote} (${failed.err.split('\n')[0] ?? '?'}). Base freshness NOT checked.`,
             generated: [],
             remeasured: [],
             authored: [],
@@ -765,10 +852,49 @@ export function sync(repo: string, baseOverride: string | null, dryRun: boolean,
         };
     }
 
-    const behindEach = order.map((ref) => ({
-        ref,
-        behind: Number(sh('git', ['rev-list', '--count', `HEAD..${ref}`], repo).out.trim() || '0'),
-    }));
+    // A single-branch clone's refspec never moves a base tracking ref fetched
+    // once by hand, so the remote-wide fetch above can leave it stale and the
+    // count below would read "already current". Each ref is fetched by name.
+    // A failed one is unverified like the remote-wide fetch: the ref still names
+    // whatever it named before, and counting it would read a stale "current".
+    for (const ref of order) {
+        const { remote, branch } = splitResolvedRef(ref);
+        const f = sh('git', ['fetch', '-q', '--', remote, `+refs/heads/${branch}:refs/remotes/${remote}/${branch}`], repo);
+        if (!f.ok) {
+            return {
+                exit: 0,
+                message: `unverified — could not fetch ${ref} (${f.err.split('\n')[0] ?? '?'}). Base freshness NOT checked.`,
+                generated: [],
+                remeasured: [],
+                authored: [],
+                scanned: 0,
+            };
+        }
+    }
+
+    // A count git could not take is not a count of 0: a ref this checkout never
+    // fetched (a single-branch clone) would otherwise read as "already current".
+    const countBehind = (from: string, ref: string): number | null => {
+        const r = sh('git', ['rev-list', '--count', `${from}..${ref}`], repo);
+        const n = Number(r.out.trim());
+        return r.ok && r.out.trim() !== '' && Number.isInteger(n) ? n : null;
+    };
+    const uncountable = (ref: string): Plan => ({
+        exit: 1,
+        message:
+            `cannot count commits behind ${ref} — it is not in this checkout (a single-branch clone fetches only its own branch). ` +
+            `Fetch it: git fetch -- ${splitResolvedRef(ref).remote} +refs/heads/${bareName(ref)}:refs/remotes/${splitResolvedRef(ref).remote}/${bareName(ref)}`,
+        generated: [],
+        remeasured: [],
+        authored: [],
+        scanned: 0,
+    });
+    const behindEach: { ref: string; behind: number }[] = [];
+    for (const ref of order) {
+        const behind = countBehind('HEAD', ref);
+        if (behind === null) return uncountable(ref);
+        behindEach.push({ ref, behind });
+    }
     // De-duplicated by ancestry: a ref already contained in HEAD is 0 behind and
     // is not merged again, which is what keeps a target that already contains
     // the default from being merged twice.
@@ -778,28 +904,33 @@ export function sync(repo: string, baseOverride: string | null, dryRun: boolean,
     }
     if (dryRun) {
         const detail = stale.map((b) => `${b.ref} (${String(b.behind)} behind)`).join(', ');
+        const added = resolved.entries.find((e) => e.reason === 'branch-convergence-policy:include-default');
+        const target = resolved.entries[0]?.ref ?? '';
+        const targetBehind = added === undefined ? 0 : countBehind(target, added.ref);
+        if (targetBehind === null) return uncountable(added?.ref ?? target);
         return {
+            ...(targetBehind > 0 && added !== undefined
+                ? { targetStale: { target, defaultRef: added.ref, behind: targetBehind, branchBehind: behindEach.find((b) => b.ref === target)?.behind ?? 0 } }
+                : {}),
             exit: 0,
             message: `${summary}. Behind: ${detail} — would merge in that order. Dry run, nothing changed.`,
+            summary,
+            behindDetail: detail,
             generated: [],
             remeasured: [],
             authored: [],
             scanned: order.length,
+            behind: stale.length,
         };
     }
 
+    const live = opts.live ?? makeGitDeps(repo);
     const outcome = integrateWithPinnedBase(
         stale.map((b) => b.ref),
         {
-            remoteSha: (ref: string): string | null => makeGitDeps(repo).remoteSha(ref),
-            merge: (ref: string): { ok: boolean; conflicted: string[] } => {
-                const m = sh('git', ['merge', ref, '--no-edit'], repo);
-                if (m.ok) return { ok: true, conflicted: [] };
-                return {
-                    ok: false,
-                    conflicted: sh('git', ['diff', '--name-only', '--diff-filter=U'], repo).out.split('\n'),
-                };
-            },
+            remoteSha: (ref: string): string | null => live.remoteSha(ref),
+            ...(opts.checkPin === undefined ? {} : { checkPin: opts.checkPin }),
+            merge: (ref: string, sha: string | null) => mergePinned(repo, ref, sha),
         },
     );
 
@@ -816,8 +947,8 @@ export function sync(repo: string, baseOverride: string | null, dryRun: boolean,
         };
     }
     if (outcome.conflicted.length === 0) {
-        // The base kept moving. No conflict to classify; the evidence IS the
-        // per-attempt OID list already in the message.
+        // The base kept moving, or moved onto a commit carrying another
+        // strategy. No conflict to classify; the message carries the OIDs.
         return { exit: 1, message: `${summary}. ${outcome.message}`, generated: [], remeasured: [], authored: [], scanned: order.length };
     }
 
@@ -845,7 +976,82 @@ export function sync(repo: string, baseOverride: string | null, dryRun: boolean,
     };
 }
 
-export function main(argv?: readonly string[]): number {
+/**
+ * `git.update_strategy` in force for the repository: the committed
+ * `.git-convention.yml` at the target commit, over the developer layers
+ * (ADR-283). Absent everywhere reads as `merge`, the behaviour before the key
+ * existed; a file that does not parse, a typo, a user-global-only value and a
+ * target commit that cannot be resolved are refusals here.
+ */
+export function updateStrategy(repo: string, base: string | null = null, deps?: TargetDeps): GitConventionReading {
+    return readStrategy(repo, base, deps).reading;
+}
+
+function readStrategy(repo: string, base: string | null, deps?: TargetDeps): { reading: GitConventionReading; baseResolved: boolean; target: ConventionTarget | null } {
+    const read = readCommittedConvention(repo, { override: base, keys: ['update_strategy'], ...(deps ? { deps } : {}) });
+    return { reading: read.readings.update_strategy as GitConventionReading, baseResolved: read.target !== null && read.target.sha !== null, target: read.target };
+}
+
+export interface StrategyGate {
+    /** `null` — the strategy is readable, go on; otherwise the exit to return. */
+    exit: 0 | 1 | 4 | null;
+    line: string;
+    reading: GitConventionReading;
+    /** The ref and commit the strategy was read at, when `strategyGate` resolved one. */
+    target?: ConventionTarget | null;
+}
+
+/**
+ * The one place that maps an unreadable `git.update_strategy` to an exit.
+ *
+ * A developer file that is itself a refusal, and a carrier at the target that
+ * does not parse or is not accepted, are exit 4. A target that resolves to no
+ * commit — no `--base` and no default branch, a ref the server does not know,
+ * no origin, origin unreachable at the ref lookup — is the base failure, exit
+ * 1. A target the server named whose commit could not be fetched is
+ * `unverified`: exit 0 with a warning, and nothing is touched.
+ */
+export function strategyExit(reading: GitConventionReading, baseResolved: boolean, developer: GitConventionReading): StrategyGate {
+    if (!isRefusal(reading.state)) return { exit: null, line: '', reading };
+    const refused: StrategyGate = { exit: 4, line: `❌  sync_pr_branch: refused — ${describeRefusal(reading)}. Nothing was checked or merged.`, reading };
+    if (reading.state !== 'unresolvable' || isRefusal(developer.state)) return refused;
+    const why = reading.detail ?? 'the target commit is unknown';
+    if (!baseResolved) return { exit: 1, line: `❌  sync_pr_branch: base could not be resolved — ${why}. Nothing was checked or merged.`, reading };
+    return { exit: 0, line: `⚠️  sync_pr_branch: unverified — ${why}. Base freshness NOT checked, nothing was merged.`, reading };
+}
+
+export function strategyGate(repo: string, base: string | null, targetDeps: BaseDeps): StrategyGate {
+    const { reading, baseResolved, target } = readStrategy(repo, base, targetDeps);
+    return { ...strategyExit(reading, baseResolved, readGitConventionKey('update_strategy', checkoutSource(conventionRoot(repo).root))), target };
+}
+
+/** The strategy a reading puts in force, or its refusing state: what a plan is made with. */
+function strategyInForce(r: GitConventionReading): string {
+    return isRefusal(r.state) ? `unreadable (${r.state})` : (r.value ?? 'merge');
+}
+
+/**
+ * The stop for a target that moved between the strategy read and the pin.
+ *
+ * The commit being integrated is governed by the policy it carries, so the
+ * carrier is read again at the pinned commit through the same reader. The same
+ * strategy in force there goes on against the new commit; a different one, or
+ * one that cannot be read, stops before anything is merged — the plan was made
+ * under a policy the integrated commit no longer carries.
+ */
+export function policyMovedStop(from: string, to: string, planned: GitConventionReading, pinned: GitConventionReading): string | null {
+    const was = strategyInForce(planned);
+    const now = strategyInForce(pinned);
+    if (was === now) return null;
+    const why = isRefusal(pinned.state) ? ` (${describeRefusal(pinned)})` : '';
+    return (
+        `the target moved from ${from.slice(0, 12)} to ${to.slice(0, 12)} and its git.update_strategy changed from ${was} to ${now}${why} — ` +
+        'nothing was merged; run again so the plan is made under the strategy the new commit carries.'
+    );
+}
+
+/** `deps` answers the target questions; tests inject it, a run asks git. */
+export function main(argv?: readonly string[], deps?: BaseDeps): number {
     const args = argv ?? process.argv.slice(2);
     let repo = process.cwd();
     let base: string | null = null;
@@ -873,6 +1079,12 @@ export function main(argv?: readonly string[]): number {
                 reportScanned({ gate: 'sync_pr_branch', scanned: 0, units: 'base ref(s)', roots: ['origin'], allowEmpty: 'argument error' });
                 return 1;
             }
+            const blank = baseValueError(v);
+            if (blank !== null) {
+                process.stderr.write(`❌  sync_pr_branch: ${blank}\n`);
+                reportScanned({ gate: 'sync_pr_branch', scanned: 0, units: 'base ref(s)', roots: ['origin'], allowEmpty: 'argument error' });
+                return 2;
+            }
             base = v;
         } else if (a === '--dry-run') {
             dryRun = true;
@@ -884,7 +1096,18 @@ export function main(argv?: readonly string[]): number {
             process.stdout.write(
                 'usage: sync_pr_branch [--repo PATH] [--base REF] [--dry-run] [--auto-resolve-generated] [--quiet]\n' +
                     '  Merges the PR base into the current branch so the PR does not go stale.\n' +
-                    '  Resolves the base from the open PR when there is one. A conflict is\n' +
+                    '  Under a git.update_strategy other than merge it only checks: a current\n' +
+                    '  branch exits 0, a behind one exits 3 and is never merged (--dry-run and\n' +
+                    '  --auto-resolve-generated have nothing to change there). A strategy that\n' +
+                    '  cannot be read (unparsable file, typo, user-global-only) exits 4.\n' +
+                    '  The base is --base; without it the default branch, so a PR into any other\n' +
+                    '  base must pass --base <its base>; a branch name and refs/heads/<name> mean\n' +
+                    '  origin/<name>, and <remote>/<name> is used as given. A blank --base\n' +
+                    '  is a usage error, exit 2.\n' +
+                    '  A base that cannot be resolved or counted exits 1; one whose commit\n' +
+                    '  cannot be fetched is unverified, exit 0. A target that moves before the\n' +
+                    '  merge is read again at the new commit; another strategy there exits 1,\n' +
+                    '  nothing merged. A conflict is\n' +
                     '  reported and never auto-resolved; generated and authored conflicts are\n' +
                     '  listed separately because only the first has one correct resolution;\n' +
                     '  measured ratchet baselines are a third class, re-measured not merged.\n' +
@@ -903,9 +1126,52 @@ export function main(argv?: readonly string[]): number {
         }
     }
 
+    // This script only merges. Under any other strategy a merge of the base is
+    // the commit the setting excludes, and a rebase needs the user's request per
+    // git-history-discipline — so the branch is only CHECKED (dry run), and a
+    // branch that is behind is refused rather than merged. A current branch
+    // passes, so an automated pre-push sync stays green when nothing is to do.
+    const ignored = ignoredCarrierWarning(conventionRoot(repo).root);
+    if (ignored !== null) process.stdout.write(`⚠️  sync_pr_branch: ${ignored}\n`);
+    const live = deps ?? makeGitDeps(repo);
+    const targetDeps = memoTargetDeps(live);
     let plan: Plan;
     try {
-        plan = sync(repo, base, dryRun, autoResolve);
+        const gate = strategyGate(repo, base, targetDeps);
+        if (gate.exit !== null) {
+            process.stdout.write(`${gate.line}\n`);
+            const why = gate.exit === 0 ? 'target commit not fetched — stated above' : gate.exit === 1 ? 'base unresolvable — stated above' : 'git.update_strategy unreadable';
+            reportScanned({ gate: 'sync_pr_branch', scanned: 0, units: 'base ref(s)', roots: ['origin'], allowEmpty: why });
+            return gate.exit;
+        }
+        const strategy = gate.reading.value ?? 'merge';
+        if (strategy !== 'merge') {
+            plan = sync(repo, base, true, false, targetDeps);
+            const t = plan.targetStale;
+            if (plan.exit === 0 && t !== undefined && t.branchBehind === 0) {
+                process.stdout.write(
+                    `⚠️  sync_pr_branch: refused — TARGET_POLICY_STALE: the target ${t.target} is itself ${String(t.behind)} commit(s) behind ${t.defaultRef}, ` +
+                        `which the branch-convergence policy requires; updating this branch onto the target cannot make it current. ` +
+                        `The target needs updating first; this branch has nothing to do until then.\n`,
+                );
+                reportScanned({ gate: 'sync_pr_branch', scanned: plan.scanned, units: 'base ref(s)', roots: ['origin'] });
+                return 3;
+            }
+            if (plan.exit === 0 && (plan.behind ?? 0) > 0) {
+                process.stdout.write(`${behindRefusalMessage(plan, strategy)}\n`);
+                reportScanned({ gate: 'sync_pr_branch', scanned: plan.scanned, units: 'base ref(s)', roots: ['origin'] });
+                return 3;
+            }
+        } else {
+            const read = gate.target ?? null;
+            const checkPin = (pinned: readonly { ref: string; before: string | null }[]): string | null => {
+                const now = read === null ? null : (pinned.find((p) => p.ref === read.ref)?.before ?? null);
+                if (read === null || read.sha === null || now === null || now === read.sha) return null;
+                const again = strategyGate(repo, base, { ...targetDeps, remoteSha: () => now });
+                return policyMovedStop(read.sha, now, gate.reading, again.reading);
+            };
+            plan = sync(repo, base, dryRun, autoResolve, targetDeps, { live, checkPin });
+        }
     } catch (exc) {
         reportScanned({ gate: 'sync_pr_branch', scanned: 0, units: 'base ref(s)', roots: ['origin'], allowEmpty: 'internal error' });
         process.stderr.write(`❌  sync_pr_branch: internal error: ${exc instanceof Error ? exc.message : String(exc)}\n`);
@@ -936,9 +1202,14 @@ export function main(argv?: readonly string[]): number {
     return plan.exit;
 }
 
+// Inlined into the `git:convention` delegate bundle this module shares that
+// bundle's `import.meta.url`, so the URL comparison below would run `main` at
+// import time with the verb's argv. Defined by the esbuild builds only.
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
 const _HERE = fileURLToPath(import.meta.url);
 function _isCliEntry(): boolean {
     if (process.argv[1] === undefined) return false;
+    if (typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__) return path.basename(process.argv[1], '.js') === 'sync_pr_branch';
     return import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href || process.argv[1] === _HERE;
 }
 if (_isCliEntry()) {