@zq-silk/yui 0.15.11 → 0.16.0

package/dist/repository/gitWorkspace.js

@@ -3,7 +3,18 @@ import { createHash, randomBytes } from "node:crypto";
 import { lstat, mkdir, readFile, realpath, rm } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { promisify } from "node:util";
+import { cleanupFailure } from "../workspace/cleanupInspection.js";
+import { externalProgramConfigViolations } from "../artifacts/managedGit.js";
 const executeFile = promisify(execFile);
+/** Observed partial effects, not a rollback or permission to replay a refresh. */
+export class GitWorkspaceRefreshError extends Error {
+    result;
+    constructor(message, result, options) {
+        super(message, options);
+        this.result = result;
+        this.name = "GitWorkspaceRefreshError";
+    }
+}
 /** A remote baseline merge stopped for an explicit Leader resolution. */
 export class RemoteBaselineConflictError extends Error {
     affectedPaths;
@@ -86,6 +97,7 @@ export class NodeGitWorkspace {
         return git([
             "-C", input.repositoryPath,
             "diff", "--no-color", "--no-ext-diff",
+            ...(input.exact ? ["--no-textconv", "--binary", "--full-index", "--no-renames"] : []),
             input.fromCommit, input.toCommit
         ]);
     }
@@ -172,47 +184,117 @@ export class NodeGitWorkspace {
         const initial = await this.inspect(input.repositoryPath, "HEAD");
         await this.#assertRefreshCheckout(initial.root, configuredStableRef, initial.baseCommit);
         const stableBranch = configuredStableRef === "HEAD"
-            ? await resolveRemoteHeadBranch(remote)
+            ? await resolveRemoteHeadBranch(remote, initial.root)
             : configuredStableRef;
         if (stableBranch !== configuredStableRef) {
             await this.#assertRefreshCheckout(initial.root, stableBranch, initial.baseCommit);
         }
-        const stableRemoteRef = `refs/heads/${stableBranch}`;
-        await git(["-C", initial.root, "fetch", "--no-tags", remote, stableRemoteRef]);
-        const fetchedCommit = (await gitLine([
-            "-C", initial.root,
-            "rev-parse", "--verify", "--end-of-options", "FETCH_HEAD^{commit}"
-        ])).toLowerCase();
-        // The advertised SHA must match what was fetched. A network race, a ref
-        // that moved mid-fetch, or any inconsistency fails closed: the stable
-        // checkout is never advanced to an unverified commit.
-        const advertisedCommit = await resolveRemoteBranchCommit(remote, stableBranch);
-        if (fetchedCommit !== advertisedCommit) {
-            throw new Error(`Project remote stable branch changed while it was fetched: ${stableBranch}.`);
-        }
-        await this.#assertRefreshCheckout(initial.root, stableBranch, initial.baseCommit);
-        if (fetchedCommit === initial.baseCommit) {
-            return {
-                fromCommit: initial.baseCommit,
-                toCommit: fetchedCommit,
-                changed: false
-            };
+        const mapping = await resolveFetchTracking(initial.root, remote, stableBranch);
+        const previous = mapping.status === "managed"
+            ? await readDirectTrackingRef(initial.root, mapping.ref)
+            : null;
+        let tracking = mapping.status === "managed"
+            ? { status: "current", remoteName: mapping.remoteName, ref: mapping.ref,
+                fromCommit: previous, toCommit: previous }
+            : { status: "unmanaged", reason: mapping.reason };
+        const temporaryRef = `refs/yui/project-refresh/${randomBytes(16).toString("hex")}`;
+        let fetchedCommit;
+        let verifiedCommit;
+        let failure;
+        let cleanupFailed = false;
+        const assertMapping = async () => {
+            const current = await resolveFetchTracking(initial.root, remote, stableBranch);
+            if (JSON.stringify(current) !== JSON.stringify(mapping)) {
+                throw new Error("Project fetch URL or tracking mapping changed during refresh.");
+            }
+        };
+        try {
+            // An empty refmap disables opportunistic tracking updates even when the
+            // Project URL is a named remote. Ignore configured prune/submodule effects.
+            await git([
+                "-C", initial.root, "fetch", "--no-tags", "--no-prune", "--no-prune-tags",
+                "--no-recurse-submodules", "--no-auto-maintenance", "--no-write-fetch-head", "--refmap=",
+                remote, `refs/heads/${stableBranch}:${temporaryRef}`
+            ]);
+            fetchedCommit = await resolveFetchedCommit(initial.root, temporaryRef);
+            const advertisedCommit = await resolveRemoteBranchCommit(remote, stableBranch, initial.root);
+            if (fetchedCommit !== advertisedCommit) {
+                throw new Error(`Project remote stable branch changed while it was fetched: ${stableBranch}.`);
+            }
+            verifiedCommit = fetchedCommit;
+            await assertMapping();
+            await this.#assertRefreshCheckout(initial.root, stableBranch, initial.baseCommit);
+            if (fetchedCommit !== initial.baseCommit) {
+                if (!await this.isAncestor(initial.root, initial.baseCommit, fetchedCommit)) {
+                    throw new Error(`Project checkout cannot be fast-forwarded from ${initial.baseCommit} to ${fetchedCommit}.`);
+                }
+                await git(["-C", initial.root, "merge", "--ff-only", "--no-edit", fetchedCommit]);
+            }
+            await this.#assertRefreshCheckout(initial.root, stableBranch, fetchedCommit);
+            await assertMapping();
+            if (mapping.status === "managed") {
+                // Do not follow a symbolic tracking ref into somebody else's branch.
+                await readDirectTrackingRef(initial.root, mapping.ref);
+                const old = previous ?? "0".repeat(fetchedCommit.length);
+                // Verify the stable branch and CAS the one configured destination in
+                // the same Git transaction. HEAD/index/worktree still use normal ff.
+                await git(["-C", initial.root, "update-ref", "--stdin"], { input: [
+                        "start", "option no-deref",
+                        `verify refs/heads/${stableBranch} ${fetchedCommit}`,
+                        "option no-deref",
+                        `update ${mapping.ref} ${fetchedCommit} ${old}`,
+                        "prepare", "commit", ""
+                    ].join("\n") });
+                tracking = {
+                    status: previous === fetchedCommit ? "current" : "updated",
+                    remoteName: mapping.remoteName, ref: mapping.ref,
+                    fromCommit: previous, toCommit: fetchedCommit
+                };
+            }
+            await this.#assertRefreshCheckout(initial.root, stableBranch, fetchedCommit);
+            await assertMapping();
+            if (mapping.status === "managed"
+                && await readDirectTrackingRef(initial.root, mapping.ref) !== fetchedCommit) {
+                throw new Error(`Project tracking ref changed after refresh: ${mapping.ref}.`);
+            }
         }
-        if (!await gitSucceeds([
-            "-C", initial.root,
-            "merge-base", "--is-ancestor", initial.baseCommit, fetchedCommit
-        ])) {
-            throw new Error(`Project checkout cannot be fast-forwarded from ${initial.baseCommit} to ${fetchedCommit}.`);
+        catch (error) {
+            failure = error;
+        }
+        finally {
+            if (fetchedCommit !== undefined) {
+                cleanupFailed = !await gitSucceeds([
+                    "-C", initial.root, "update-ref", "--no-deref", "-d", temporaryRef, fetchedCommit
+                ]);
+                if (cleanupFailed && failure === undefined) {
+                    failure = new Error(`Project refresh temporary ref cleanup failed: ${temporaryRef}.`);
+                }
+            }
+        }
+        if (failure !== undefined) {
+            const head = await this.inspect(initial.root, "HEAD").then((value) => value.baseCommit, () => null);
+            const detail = failure instanceof Error ? failure.message : String(failure);
+            if (mapping.status === "managed") {
+                tracking = {
+                    status: "failed", remoteName: mapping.remoteName, ref: mapping.ref,
+                    fromCommit: previous,
+                    toCommit: await readDirectTrackingRef(initial.root, mapping.ref).catch(() => null),
+                    reason: detail
+                };
+            }
+            throw new GitWorkspaceRefreshError(`Project refresh failed: ${detail} HEAD ${initial.baseCommit} -> ${head ?? "unknown"}; ` +
+                (tracking.status === "unmanaged" ? `tracking unmanaged: ${tracking.reason}` :
+                    `tracking ${tracking.ref}: ${tracking.fromCommit ?? "absent"} -> ${tracking.toCommit ?? "absent or unreadable"}`) +
+                (cleanupFailed ? `; temporary ref retained: ${temporaryRef}` : ""), { fromCommit: initial.baseCommit, toCommit: head,
+                changed: head === null ? null : head !== initial.baseCommit,
+                ...(verifiedCommit === undefined ? {} : { verifiedCommit }), tracking,
+                ...(cleanupFailed || fetchedCommit === undefined ? { temporaryRef } : {}) }, { cause: failure });
         }
-        await git([
-            "-C", initial.root,
-            "merge", "--ff-only", "--no-edit", fetchedCommit
-        ]);
-        await this.#assertRefreshCheckout(initial.root, stableBranch, fetchedCommit);
         return {
             fromCommit: initial.baseCommit,
-            toCommit: fetchedCommit,
-            changed: true
+            toCommit: verifiedCommit,
+            changed: initial.baseCommit !== verifiedCommit,
+            tracking
         };
     }
     /**
@@ -513,47 +595,17 @@ export class NodeGitWorkspace {
     }
     async inspectRemoteTracking(input) {
         const root = (await this.inspect(input.repositoryPath)).root;
-        const wantedUrl = requireText(input.remoteUrl, "Project remote URL");
-        let output;
-        try {
-            output = await git([
-                "-C", root,
-                "config", "--get-regexp", "--null",
-                "^remote\\..*\\.url$"
-            ]);
-        }
-        catch {
-            return null;
-        }
-        const records = output.split("\0").filter((record) => record.length > 0);
-        const matches = [];
-        for (const record of records) {
-            const separator = record.indexOf("\n");
-            if (separator < 0)
-                continue;
-            const key = record.slice(0, separator).trim();
-            const url = record.slice(separator + 1).trim();
-            const prefix = "remote.";
-            const suffix = ".url";
-            if (!key.startsWith(prefix) || !key.endsWith(suffix) || url !== wantedUrl)
-                continue;
-            matches.push({ remoteName: key.slice(prefix.length, -suffix.length), url });
-        }
-        if (matches.length !== 1)
-            return null;
-        const remoteName = requireText(matches[0].remoteName, "Git remote name");
         const branch = await safeFetchBranch(input.branch);
-        const ref = `refs/remotes/${remoteName}/${branch}`;
-        if (!await gitSucceeds(["check-ref-format", ref])) {
-            throw new Error("Git remote tracking ref is invalid.");
-        }
-        if (!await this.refExists(root, ref))
+        const mapping = await resolveFetchTracking(root, safeRemote(input.remoteUrl), branch);
+        if (mapping.status !== "managed")
+            return null;
+        if (!await this.refExists(root, mapping.ref))
             return null;
         return {
-            remoteName,
-            remoteUrl: matches[0].url,
-            ref,
-            commit: (await this.inspect(root, ref)).baseCommit
+            remoteName: mapping.remoteName,
+            remoteUrl: mapping.remoteUrl,
+            ref: mapping.ref,
+            commit: (await this.inspect(root, mapping.ref)).baseCommit
         };
     }
     async mergeBase(input) {
@@ -571,9 +623,13 @@ export class NodeGitWorkspace {
     }
     async isClean(repositoryPath) {
         const root = (await this.inspect(repositoryPath)).root;
-        const status = await git([
-            "-C", root, "status", "--porcelain=v1", "--untracked-files=all"
-        ]);
+        const status = await git(["--no-optional-locks", "-C", root,
+            "status", "--porcelain=v1", "--untracked-files=all"]);
+        return status.length === 0;
+    }
+    async inspectClean(repositoryPath) {
+        const root = (await this.inspect(repositoryPath)).root;
+        const status = await readWorktreeStatus(root);
         return status.length === 0;
     }
     async mergeWorktree(input) {
@@ -660,6 +716,11 @@ export class NodeGitWorkspace {
             .filter((line) => line.length > 0);
     }
     async #assertRefreshCheckout(repositoryPath, stableRef, expectedCommit) {
+        // Status can take time. Re-read branch and HEAD after it so a checkout
+        // switched while status was running is not subsequently fast-forwarded.
+        if (!await this.isClean(repositoryPath)) {
+            throw new Error("Project checkout must be clean before it can be refreshed.");
+        }
         if (stableRef !== "HEAD") {
             const currentBranch = await this.headRef(repositoryPath);
             if (currentBranch !== stableRef) {
@@ -671,9 +732,6 @@ export class NodeGitWorkspace {
         if (head.baseCommit !== expectedCommit) {
             throw new Error("Project checkout changed while it was being refreshed.");
         }
-        if (!await this.isClean(head.root)) {
-            throw new Error("Project checkout must be clean before it can be refreshed.");
-        }
     }
     async ensureWorktree(input) {
         return this.#ensureManagedWorktree({
@@ -786,34 +844,40 @@ export class NodeGitWorkspace {
         return "removed";
     }
     async removeTaskClone(input) {
+        const state = await this.inspectTaskClone(input);
+        if (state !== "clean")
+            return state;
+        await rm(managedPath(resolve(input.container), input.directory), { recursive: true });
+        return "removed";
+    }
+    async inspectTaskClone(input) {
         const identity = worktreeIdentity(input.taskSegment, "main");
         const expected = managedPath(resolve(input.container), input.directory);
         if (resolve(input.path) !== expected || input.branch !== identity.branch) {
-            throw new Error("Task clone does not match its recorded managed identity.");
+            cleanupFailure("workspace-identity-mismatch", "Task clone does not match its recorded managed identity.", { branch: identity.branch }, { branch: input.branch, pathMatches: resolve(input.path) === expected });
         }
         const kind = await pathKind(expected);
         if (kind === undefined)
             return "missing";
         if (kind === "symlink")
-            throw new Error("Task clone must not be a symbolic link.");
+            cleanupFailure("workspace-identity-mismatch", "Task clone must not be a symbolic link.", "real directory", "symbolic link");
         await canonicalContainer(input.container, false);
         if (await realpath(expected) !== expected || await pathKind(join(expected, ".git")) !== "directory") {
-            throw new Error("Task clone is not a standalone owned Git directory.");
+            cleanupFailure("workspace-identity-mismatch", "Task clone is not a standalone owned Git directory.", "standalone owned clone", "different Git layout or symbolic ancestor");
         }
         const repository = await this.inspect(expected);
         if (repository.root !== expected || repository.gitDirectory !== join(expected, ".git")) {
-            throw new Error("Task clone Git ownership cannot be established.");
+            cleanupFailure("workspace-identity-mismatch", "Task clone Git ownership cannot be established.", "exact root and Git directory", "different Git ownership");
         }
         await assertExpectedBranch(expected, input.branch);
-        if (!await this.isClean(expected))
+        if (!await this.inspectClean(expected))
             return "dirty";
         const worktrees = (await git(["-C", expected, "worktree", "list", "--porcelain", "-z"]))
             .split("\0").filter(line => line.startsWith("worktree "));
         if (worktrees.length !== 1 || worktrees[0] !== `worktree ${expected}`) {
-            throw new Error("Task clone still owns Git worktree registrations; retained.");
+            cleanupFailure("git-worktree-registrations", "Task clone still owns Git worktree registrations; retained.", 1, worktrees.length);
         }
-        await rm(expected, { recursive: true });
-        return "removed";
+        return "clean";
     }
     async inspectRecordedWorktree(input) {
         const inspected = await inspectExactRecordedWorktree(input);
@@ -862,14 +926,19 @@ export class NodeGitWorkspace {
         const container = resolve(input.container);
         const path = managedPath(container, input.directory);
         const kind = await pathKind(path);
-        if (kind === undefined)
+        const branch = input.expectedBranch ?? worktreeIdentity(input.taskSegment, input.roleName).branch;
+        if (kind === undefined) {
+            const project = await this.inspect(input.repositoryPath);
+            await inspectMissingWorktreeRegistration(project.root, path, branch);
             return "missing";
+        }
         if (kind === "symlink")
-            throw new Error("Managed worktree path must not be a symbolic link.");
+            cleanupFailure("workspace-identity-mismatch", "Managed worktree path must not be a symbolic link.", "real directory", "symbolic link");
         const canonicalContainerPath = await canonicalContainer(container, false);
         const project = await this.inspect(input.repositoryPath);
         await assertOwnedWorktree(project, canonicalContainerPath, path);
-        const porcelain = await git(["-C", path, "status", "--porcelain=v1", "--untracked-files=all"]);
+        await assertExpectedBranch(path, branch);
+        const porcelain = await readWorktreeStatus(path);
         return porcelain.length > 0 ? "dirty" : "clean";
     }
     async removeIntegrationWorktree(input) {
@@ -901,9 +970,7 @@ export class NodeGitWorkspace {
                 await git(["-C", repository.root, "worktree", "remove", "--force", "--", path]);
             }
             else {
-                const porcelain = await git([
-                    "-C", path, "status", "--porcelain=v1", "--untracked-files=all"
-                ]);
+                const porcelain = await readWorktreeStatus(path);
                 if (porcelain.length > 0)
                     return "dirty";
                 if (input.expectedBaseCommit !== undefined
@@ -930,16 +997,22 @@ export class NodeGitWorkspace {
  * workspace's registration as a side effect of cleaning this exact owner.
  */
 async function removeMissingWorktreeRegistration(repositoryRoot, path, branch) {
+    if (!await inspectMissingWorktreeRegistration(repositoryRoot, path, branch))
+        return;
+    if (await pathKind(path) !== undefined)
+        throw new Error(`Worktree reappeared before metadata cleanup: ${path}.`);
+    await git(["-C", repositoryRoot, "worktree", "remove", "--force", "--", path]);
+}
+async function inspectMissingWorktreeRegistration(repositoryRoot, path, branch) {
     const records = (await git(["-C", repositoryRoot, "worktree", "list", "--porcelain", "-z"])).split("\0\0");
     const fields = records.map(record => record.split("\0")).find(record => record.includes(`worktree ${path}`));
     if (fields === undefined)
-        return;
+        return false;
     if (!fields.includes(`branch refs/heads/${branch}`) || fields.some(field => field.startsWith("locked"))) {
-        throw new Error(`Missing worktree has uncertain or locked Git ownership: ${path}; metadata retained.`);
+        cleanupFailure("git-registration-mismatch", "Missing worktree has uncertain or locked Git ownership; metadata retained.", { branch, locked: false }, { branch: fields.find(field => field.startsWith("branch "))?.slice(7) ?? null,
+            locked: fields.some(field => field.startsWith("locked")) });
     }
-    if (await pathKind(path) !== undefined)
-        throw new Error(`Worktree reappeared before metadata cleanup: ${path}.`);
-    await git(["-C", repositoryRoot, "worktree", "remove", "--force", "--", path]);
+    return true;
 }
 async function deleteBranchIfPresent(repositoryRoot, branch) {
     const branchRef = `refs/heads/${branch}`;
@@ -999,7 +1072,7 @@ async function assertExpectedBranch(path, expected, allowRebase = false) {
     }
     const branch = await gitLine(["-C", path, "symbolic-ref", "--short", "HEAD"]);
     if (branch !== expected) {
-        throw new Error(`Managed worktree is on an unexpected branch: ${branch}.`);
+        cleanupFailure("workspace-identity-mismatch", "Managed worktree is on an unexpected branch.", expected, branch);
     }
 }
 async function assertOwnedWorktree(project, container, path) {
@@ -1012,7 +1085,7 @@ async function assertOwnedWorktree(project, container, path) {
         throw new Error("Managed worktree root does not match its deterministic path.");
     const common = await canonicalDirectory(await gitLine(["-C", path, "rev-parse", "--path-format=absolute", "--git-common-dir"]), "Managed Git common directory");
     if (common !== project.gitDirectory) {
-        throw new Error("Managed worktree belongs to another project.");
+        cleanupFailure("workspace-identity-mismatch", "Managed worktree belongs to another project.", "Task main Git common directory", "different Git common directory");
     }
 }
 async function inspectExactRecordedWorktree(input) {
@@ -1147,13 +1220,72 @@ async function pathKind(path) {
         throw error;
     }
 }
-async function git(args) {
+/** Status can execute clean/process filters to compare equal-size changed
+ * files. Preserve native normalization: report unknown instead of disabling
+ * a filter and misclassifying its output as clean/dirty. Include scopes so a
+ * native global/worktree include cannot hide the same execution requirement.
+ */
+async function readWorktreeStatus(path) {
+    await assertStatusProgramsAbsent(path);
+    return readStatusGit(path, ["status", "--porcelain=v1", "--untracked-files=all"]);
+}
+async function readStatusGit(path, args) {
+    return git(["--no-optional-locks", "-c", "core.fsmonitor=false",
+        "-c", "protocol.allow=never", "-c", "protocol.file.allow=never",
+        "-C", path, ...args], { environment: { GIT_NO_LAZY_FETCH: "1" } });
+}
+async function assertStatusProgramsAbsent(path) {
+    const configuration = await readStatusGit(path, ["config", "--list", "--null", "--includes"]);
+    const filters = externalProgramConfigViolations(configuration)
+        .filter(key => key.startsWith("filter.") && (key.endsWith(".clean") || key.endsWith(".process")));
+    const files = (await readStatusGit(path, ["ls-files", "--stage", "-z"])).split("\0");
+    if (filters.length > 0) {
+        // Merely having native LFS configured globally is not a violation. Only
+        // filters selected by tracked regular files' effective attributes can run
+        // during status. check-attr reads those selections without executing them.
+        const configured = new Set(filters.map(key => key.slice(7, key.lastIndexOf("."))));
+        const tracked = [...new Set(files.filter(line => line.startsWith("100"))
+                .map(line => line.slice(line.indexOf("\t") + 1)))];
+        for (let offset = 0; offset < tracked.length; offset += 128) {
+            const attributes = (await readStatusGit(path, ["check-attr", "-z", "filter", "--",
+                ...tracked.slice(offset, offset + 128)])).split("\0");
+            for (let index = 2; index < attributes.length; index += 3) {
+                if (!configured.has(attributes[index].toLowerCase()))
+                    continue;
+                cleanupFailure("git-status-requires-filter", "Git status may execute a selected filter program; read-only inspection will not run it.", "status without external filter execution", { trackedPath: attributes[index - 2], filter: attributes[index] }, "unknown");
+            }
+        }
+    }
+    // Status also examines initialized submodules. Inspect their configuration
+    // before asking Git to recurse; uninitialized gitlinks execute nothing.
+    for (const record of files.filter(line => line.startsWith("160000 "))) {
+        const child = join(path, record.slice(record.indexOf("\t") + 1));
+        assertContained(path, child);
+        const gitEntry = await lstat(join(child, ".git")).catch(error => {
+            if (isErrno(error, "ENOENT"))
+                return undefined;
+            throw error;
+        });
+        if (gitEntry === undefined)
+            continue;
+        if (await realpath(child) !== child
+            || (await readStatusGit(child, ["rev-parse", "--show-toplevel"])).trimEnd() !== child) {
+            cleanupFailure("workspace-identity-mismatch", "Submodule identity cannot be safely inspected.", "owned submodule directory", "different or symbolic root");
+        }
+        await assertStatusProgramsAbsent(child);
+    }
+}
+async function git(args, options = {}) {
     try {
-        const result = await executeFile("git", [...args], {
+        const execution = executeFile("git", [...args], {
             encoding: "utf8",
             maxBuffer: 1024 * 1024,
-            timeout: 30_000
+            timeout: 30_000,
+            ...(options.environment === undefined ? {} : { env: { ...process.env, ...options.environment } })
         });
+        if (options.input !== undefined)
+            execution.child.stdin.end(options.input);
+        const result = await execution;
         return result.stdout;
     }
     catch (error) {
@@ -1181,6 +1313,134 @@ async function gitLine(args) {
     }
     return lines[0];
 }
+/** Match one exact or one-star Git refspec, in either direction. */
+function refspecCapture(pattern, ref) {
+    const star = pattern.indexOf("*");
+    if (star < 0)
+        return pattern === ref ? "" : null;
+    const prefix = pattern.slice(0, star);
+    const suffix = pattern.slice(star + 1);
+    return ref.startsWith(prefix) && ref.endsWith(suffix)
+        && ref.length >= prefix.length + suffix.length
+        ? ref.slice(prefix.length, ref.length - suffix.length) : null;
+}
+async function parseFetchSpec(value) {
+    const negative = value.startsWith("^");
+    const text = value.replace(/^[+^]/u, "");
+    const parts = text.split(":");
+    const source = parts[0];
+    const destination = parts[1] || undefined;
+    if (parts.length > 2 || (negative && parts.length !== 1)
+        || !source.startsWith("refs/")
+        || !await gitSucceeds(["check-ref-format", "--refspec-pattern", source])
+        || (destination !== undefined && (!destination.startsWith("refs/")
+            || !await gitSucceeds(["check-ref-format", "--refspec-pattern", destination])
+            || source.includes("*") !== destination.includes("*"))))
+        return null;
+    return { source, ...(destination === undefined ? {} : { destination }), negative };
+}
+async function gitConfigValues(root, key) {
+    try {
+        return (await git(["-C", root, "config", "--null", "--get-all", key]))
+            .split("\0").filter((value) => value.length > 0);
+    }
+    catch (error) {
+        const cause = error instanceof Error ? error.cause : undefined;
+        if (typeof cause === "object" && cause !== null && "code" in cause && cause.code === 1) {
+            return [];
+        }
+        throw error;
+    }
+}
+/**
+ * Prove a unique configured fetch destination, never infer it from a remote
+ * name. Git resolves insteadOf aliases; push URLs are deliberately irrelevant.
+ * Unsafe/ambiguous configurations remain usable for HEAD-only refresh.
+ */
+async function resolveFetchTracking(root, remote, branch) {
+    const wantedUrl = await gitLine(["-C", root, "ls-remote", "--get-url", "--", remote]);
+    const names = (await git(["-C", root, "remote"])).trim().split("\n").filter(Boolean).sort();
+    const remotes = await Promise.all(names.map(async (name) => ({
+        name,
+        urls: (await git(["-C", root, "remote", "get-url", "--all", "--", name])).trimEnd().split("\n"),
+        specs: await gitConfigValues(root, `remote.${name}.fetch`)
+    })));
+    const evidence = JSON.stringify({ wantedUrl, remotes });
+    const unmanaged = (reason) => ({ status: "unmanaged", reason, evidence });
+    const matching = remotes.filter(({ urls }) => urls[0] === wantedUrl);
+    if (matching.length !== 1 || matching[0].urls.length !== 1) {
+        return unmanaged("Project fetch URL does not identify exactly one single-URL Git remote.");
+    }
+    const selected = matching[0];
+    const candidates = await Promise.all(remotes.map(async (entry) => ({
+        ...entry, parsed: await Promise.all(entry.specs.map(parseFetchSpec))
+    })));
+    if (candidates.some(({ parsed: specs }) => specs.some((spec) => spec === null))) {
+        return unmanaged("A configured fetch refspec is outside the supported full-ref exact/one-star mapping.");
+    }
+    const parsed = candidates.map((entry) => ({
+        ...entry, parsed: entry.parsed.filter((spec) => spec !== null)
+    }));
+    const source = `refs/heads/${branch}`;
+    const excluded = (specs, ref) => specs.some((spec) => spec.negative && refspecCapture(spec.source, ref) !== null);
+    const selectedSpecs = parsed.find(({ name }) => name === selected.name).parsed;
+    if (excluded(selectedSpecs, source))
+        return unmanaged(`Fetch refspec excludes ${source}.`);
+    const destinations = new Set();
+    for (const spec of selectedSpecs) {
+        if (spec.negative || spec.destination === undefined)
+            continue;
+        const capture = refspecCapture(spec.source, source);
+        if (capture !== null)
+            destinations.add(spec.destination.replace("*", capture));
+    }
+    if (destinations.size !== 1) {
+        return unmanaged(`Fetch refspec does not map ${source} to exactly one destination.`);
+    }
+    const ref = [...destinations][0];
+    if (!ref.startsWith("refs/remotes/") || !await gitSucceeds(["check-ref-format", ref])) {
+        return unmanaged(`Fetch destination is not a supported remote-tracking ref: ${ref}.`);
+    }
+    for (const entry of parsed) {
+        for (const spec of entry.parsed) {
+            if (spec.negative || spec.destination === undefined)
+                continue;
+            const capture = refspecCapture(spec.destination, ref);
+            if (capture === null)
+                continue;
+            const otherSource = spec.source.replace("*", capture);
+            if (!excluded(entry.parsed, otherSource)
+                && (entry.name !== selected.name || otherSource !== source)) {
+                return unmanaged(`Another fetch source also manages ${ref}.`);
+            }
+        }
+    }
+    try {
+        await readDirectTrackingRef(root, ref);
+    }
+    catch (error) {
+        return unmanaged(error instanceof Error ? error.message : String(error));
+    }
+    return { status: "managed", remoteName: selected.name, remoteUrl: wantedUrl, ref, evidence };
+}
+async function readDirectTrackingRef(root, ref) {
+    const output = await git([
+        "-C", root, "for-each-ref", "--format=%(refname)%09%(objectname)%09%(symref)", "--", ref
+    ]);
+    const record = output.split("\n").find((line) => line.split("\t")[0] === ref);
+    if (record === undefined) {
+        // for-each-ref omits dangling symbolic refs. Never treat those as absent.
+        if (await gitSucceeds(["-C", root, "symbolic-ref", "--quiet", ref])) {
+            throw new Error(`Tracking destination is symbolic: ${ref}.`);
+        }
+        return null;
+    }
+    const [, commit, symbolic] = record.split("\t");
+    if (symbolic !== "" || commit === undefined || !isCommit(commit)) {
+        throw new Error(`Tracking destination is not a direct object ref: ${ref}.`);
+    }
+    return commit.toLowerCase();
+}
 function safeIdentity(value, label) {
     const identity = requireText(value, label);
     if ([".", "..", "__proto__", "prototype", "constructor"].includes(identity)
@@ -1208,10 +1468,13 @@ async function safeFetchBranch(value) {
     }
     return branch;
 }
-async function resolveRemoteHeadBranch(remote) {
+async function resolveRemoteHeadBranch(remote, repositoryPath) {
     let output;
     try {
-        output = await git(["ls-remote", "--symref", remote, "HEAD"]);
+        output = await git([
+            ...(repositoryPath === undefined ? [] : ["-C", repositoryPath]),
+            "ls-remote", "--symref", remote, "HEAD"
+        ]);
     }
     catch (error) {
         const detail = error instanceof Error ? error.message : "Git command failed.";
@@ -1234,11 +1497,14 @@ async function resolveRemoteHeadBranch(remote) {
         throw invalidRemoteHead();
     }
 }
-async function resolveRemoteBranchCommit(remote, branch) {
+async function resolveRemoteBranchCommit(remote, branch, repositoryPath) {
     const target = `refs/heads/${branch}`;
     let output;
     try {
-        output = await git(["ls-remote", "--refs", remote, target]);
+        output = await git([
+            ...(repositoryPath === undefined ? [] : ["-C", repositoryPath]),
+            "ls-remote", "--refs", remote, target
+        ]);
     }
     catch (error) {
         const detail = error instanceof Error ? error.message : "Git command failed.";