@zq-silk/yui 2.2.0 → 2.4.0

package/dist/repository/gitWorkspace.js

@@ -5,7 +5,13 @@ 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";
+import { compatibleGitArguments, gitOutputLine, supportedGit } from "./gitCompatibility.js";
+import { gitPath, readGitWorktrees } from "./gitWorktreeInventory.js";
 const executeFile = promisify(execFile);
+const isolatedFetchOptions = [
+    "--no-tags", "--no-prune", "--no-prune-tags", "--no-recurse-submodules",
+    "--no-auto-gc", "--no-write-commit-graph", "--no-write-fetch-head", "--refmap="
+];
 /** Observed partial effects, not a rollback or permission to replay a refresh. */
 export class GitWorkspaceRefreshError extends Error {
     result;
@@ -160,13 +166,13 @@ export class NodeGitWorkspace {
         const remote = safeRemote(input.remoteUrl);
         const configuredBranch = await safeFetchBranch(input.branch);
         const branch = configuredBranch === "HEAD"
-            ? await resolveRemoteHeadBranch(remote)
+            ? await resolveRemoteHeadBranch(remote, repositoryPath)
             : configuredBranch;
         const fetchedRef = remoteBaselineRef(remote, branch);
         try {
             await git([
                 "-C", repositoryPath,
-                "fetch", "--no-tags", "--no-write-fetch-head",
+                "fetch", ...isolatedFetchOptions,
                 remote,
                 `refs/heads/${branch}:${fetchedRef}`
             ]);
@@ -212,8 +218,7 @@ export class NodeGitWorkspace {
             // 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=",
+                "-C", initial.root, "fetch", ...isolatedFetchOptions,
                 remote, `refs/heads/${stableBranch}:${temporaryRef}`
             ]);
             fetchedCommit = await resolveFetchedCommit(initial.root, temporaryRef);
@@ -239,11 +244,11 @@ export class NodeGitWorkspace {
                 // 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",
+                        "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",
@@ -305,15 +310,15 @@ export class NodeGitWorkspace {
     async resolveRemoteBaseline(input) {
         const remote = safeRemote(input.remoteUrl);
         const configuredRef = await safeFetchBranch(input.developmentRef);
+        const repository = await this.inspect(input.repositoryPath, "HEAD");
         const branch = configuredRef === "HEAD"
-            ? await resolveRemoteHeadBranch(remote)
+            ? await resolveRemoteHeadBranch(remote, repository.root)
             : configuredRef;
-        const repository = await this.inspect(input.repositoryPath, "HEAD");
         const temporaryRef = remoteBaselineRef(remote, branch);
         try {
             await git([
                 "-C", repository.root,
-                "fetch", "--no-tags", "--no-write-fetch-head",
+                "fetch", ...isolatedFetchOptions,
                 remote,
                 `refs/heads/${branch}:${temporaryRef}`
             ]);
@@ -321,7 +326,7 @@ export class NodeGitWorkspace {
                 "-C", repository.root,
                 "rev-parse", "--verify", "--end-of-options", `${temporaryRef}^{commit}`
             ]);
-            const advertisedCommit = await resolveRemoteBranchCommit(remote, branch);
+            const advertisedCommit = await resolveRemoteBranchCommit(remote, branch, repository.root);
             if (fetchedCommit.toLowerCase() !== advertisedCommit) {
                 throw new Error(`Project remote development branch changed while it was fetched: ${branch}.`);
             }
@@ -341,8 +346,10 @@ export class NodeGitWorkspace {
         }
     }
     async clone(input) {
+        supportedGit();
         const remote = safeRemote(input.remoteUrl);
-        const destination = resolve(requireText(input.destination, "Project destination"));
+        requireText(input.destination, "Project destination");
+        const destination = resolve(input.destination);
         if (await pathKind(destination) !== undefined) {
             throw new Error(`Project destination already exists: ${destination}.`);
         }
@@ -415,10 +422,8 @@ export class NodeGitWorkspace {
     async inspect(repositoryPath, baseRef = "HEAD") {
         const requested = await canonicalDirectory(repositoryPath, "Project");
         const ref = safeRef(baseRef);
-        const root = await canonicalDirectory(await gitLine(["-C", requested, "rev-parse", "--show-toplevel"]), "Project root");
-        const gitDirectory = await canonicalDirectory(await gitLine([
-            "-C", root, "rev-parse", "--path-format=absolute", "--git-common-dir"
-        ]), "Git common directory");
+        const root = await canonicalDirectory(await gitPath(requested, ["--show-toplevel"]), "Project root");
+        const gitDirectory = await canonicalDirectory(await gitPath(root, ["--git-common-dir"]), "Git common directory");
         const baseCommit = await gitLine([
             "-C", root, "rev-parse", "--verify", "--end-of-options", `${ref}^{commit}`
         ]);
@@ -485,7 +490,7 @@ export class NodeGitWorkspace {
                 const importedRef = `${importRoot}/${index}`;
                 await git([
                     "-C", destination.root,
-                    "fetch", "--no-tags", "--no-write-fetch-head", "--",
+                    "fetch", ...isolatedFetchOptions, "--",
                     source.root, `${snapshot.ref}:${importedRef}`
                 ]);
                 const imported = await resolveRefCommit(destination.root, importedRef);
@@ -567,36 +572,11 @@ export class NodeGitWorkspace {
         const excluded = input.excludeWorktreePath === undefined
             ? undefined
             : await realpath(resolve(input.excludeWorktreePath)).catch(() => undefined);
-        const porcelain = await git(["-C", root, "worktree", "list", "--porcelain"]);
-        const records = [];
-        let current = { prunable: false };
-        for (const line of porcelain.split("\n")) {
-            if (line.length === 0) {
-                const path = current.path;
-                if (path !== undefined) {
-                    records.push({ path, branch: current.branch, prunable: current.prunable });
-                }
-                current = { prunable: false };
-                continue;
-            }
-            if (line.startsWith("worktree ")) {
-                current.path = line.slice("worktree ".length);
-            }
-            else if (line.startsWith("branch ")) {
-                current.branch = line.slice("branch ".length);
-            }
-            else if (line.startsWith("prunable")) {
-                current.prunable = true;
-            }
-        }
-        const lastPath = current.path;
-        if (lastPath !== undefined) {
-            records.push({ path: lastPath, branch: current.branch, prunable: current.prunable });
-        }
+        const records = await readGitWorktrees(root);
         for (const record of records) {
             // A dead registration (its directory is gone) occupies nothing; a
             // worktree on another ref or a detached HEAD does not occupy this one.
-            if (record.prunable || record.branch !== wanted)
+            if ((record.prunable && !record.locked) || record.branch !== wanted)
                 continue;
             // git reports canonical absolute paths; compare canonicals so a
             // symlinked workspace root cannot make the recorded worktree look
@@ -724,11 +704,7 @@ export class NodeGitWorkspace {
     }
     async listWorktrees(repositoryPath) {
         const root = await canonicalDirectory(repositoryPath, "Project");
-        const output = await git(["-C", root, "worktree", "list", "--porcelain"]);
-        return output
-            .split(/\r?\n/u)
-            .filter((line) => line.startsWith("worktree "))
-            .map((line) => line.slice("worktree ".length).trim());
+        return (await readGitWorktrees(root)).map(entry => entry.path);
     }
     async listCommitsBetween(input) {
         const root = await canonicalDirectory(input.repositoryPath, "Project");
@@ -821,7 +797,7 @@ export class NodeGitWorkspace {
         const state = await this.inspectWorktree(input);
         if (state === "dirty")
             return state;
-        const container = await canonicalContainer(input.container, false);
+        const container = await cleanupContainer(input.container);
         const branch = worktreeIdentity(input.taskSegment, input.roleName).branch;
         const path = managedPath(container, input.directory);
         const project = await this.inspect(input.repositoryPath);
@@ -919,9 +895,8 @@ export class NodeGitWorkspace {
         await assertExpectedBranch(expected, input.branch);
         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}`) {
+        const worktrees = await readGitWorktrees(expected);
+        if (worktrees.length !== 1 || worktrees[0].path !== expected) {
             cleanupFailure("git-worktree-registrations", "Task clone still owns Git worktree registrations; retained.", 1, worktrees.length);
         }
         return "clean";
@@ -970,13 +945,13 @@ export class NodeGitWorkspace {
         return "removed";
     }
     async inspectWorktree(input) {
-        const container = await canonicalContainer(input.container, false);
+        const container = await cleanupContainer(input.container);
         const path = managedPath(container, input.directory);
         const kind = await pathKind(path);
         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);
+            await inspectMissingWorktreeRegistration(project.root, path, branch, input.expectedBranch !== undefined);
             return "missing";
         }
         if (kind === "symlink")
@@ -984,7 +959,7 @@ export class NodeGitWorkspace {
         const canonicalContainerPath = await canonicalContainer(container, false);
         const project = await this.inspect(input.repositoryPath);
         await assertOwnedWorktree(project, canonicalContainerPath, path);
-        await assertExpectedBranch(path, branch);
+        await assertExpectedBranch(path, branch, input.expectedBranch !== undefined);
         const porcelain = await readWorktreeStatus(path);
         return porcelain.length > 0 ? "dirty" : "clean";
     }
@@ -1000,19 +975,19 @@ export class NodeGitWorkspace {
         });
     }
     async #removeManagedWorktree(input) {
-        const container = await canonicalContainer(input.container, false);
+        const container = await cleanupContainer(input.container);
         const path = managedPath(container, input.identity.directory);
         const kind = await pathKind(path);
         if (kind === "symlink")
             throw new Error("Managed worktree path must not be a symbolic link.");
         const repository = await this.inspect(input.repositoryPath);
         if (kind === undefined) {
-            await removeMissingWorktreeRegistration(repository.root, path, input.identity.branch);
+            await removeMissingWorktreeRegistration(repository.root, path, input.identity.branch, true);
         }
         if (kind === "directory") {
             const canonicalContainerPath = await canonicalContainer(container, false);
             await assertOwnedWorktree(repository, canonicalContainerPath, path);
-            await assertExpectedBranch(path, input.identity.branch);
+            await assertExpectedBranch(path, input.identity.branch, true);
             if (input.discardChanges === true) {
                 await git(["-C", repository.root, "worktree", "remove", "--force", "--", path]);
             }
@@ -1043,21 +1018,22 @@ export class NodeGitWorkspace {
 /** Missing paths do not imply missing Git metadata. Never prune another
  * workspace's registration as a side effect of cleaning this exact owner.
  */
-async function removeMissingWorktreeRegistration(repositoryRoot, path, branch) {
-    if (!await inspectMissingWorktreeRegistration(repositoryRoot, path, branch))
+async function removeMissingWorktreeRegistration(repositoryRoot, path, branch, allowDetached = false) {
+    if (!await inspectMissingWorktreeRegistration(repositoryRoot, path, branch, allowDetached))
         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)
+async function inspectMissingWorktreeRegistration(repositoryRoot, path, branch, allowDetached = false) {
+    const entry = (await readGitWorktrees(repositoryRoot)).find(record => record.path === path);
+    if (entry === undefined)
         return false;
-    if (!fields.includes(`branch refs/heads/${branch}`) || fields.some(field => field.startsWith("locked"))) {
-        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")) });
+    const pinnedDetached = allowDetached && entry.detached
+        && await gitSucceeds(["-C", repositoryRoot, "show-ref", "--verify", "--quiet", `refs/heads/${branch}`])
+        && entry.head === await resolveRefCommit(repositoryRoot, `refs/heads/${branch}`);
+    if ((entry.branch !== `refs/heads/${branch}` && !pinnedDetached) || entry.locked) {
+        cleanupFailure("git-registration-mismatch", "Missing worktree has uncertain or locked Git ownership; metadata retained.", { branch, locked: false }, { branch: entry.branch ?? null, locked: entry.locked });
     }
     return true;
 }
@@ -1100,8 +1076,7 @@ async function assertExpectedBranch(path, expected, allowRebase = false) {
         // Rebase temporarily detaches HEAD. Git's per-worktree metadata must still
         // identify this exact Integration branch; unrelated detachment is invalid.
         for (const backend of ["rebase-merge", "rebase-apply"]) {
-            const headNamePath = await gitLine(["-C", path, "rev-parse", "--path-format=absolute",
-                "--git-path", `${backend}/head-name`]);
+            const headNamePath = await gitPath(path, ["--git-path", `${backend}/head-name`]);
             let headName;
             try {
                 headName = (await readFile(headNamePath, "utf8")).trim();
@@ -1115,7 +1090,12 @@ async function assertExpectedBranch(path, expected, allowRebase = false) {
                 return;
             throw new Error(`Managed worktree is rebasing an unexpected branch: ${headName}.`);
         }
-        throw new Error("Managed worktree has detached HEAD without its expected rebase.");
+        // A terminal Integration can legitimately retain a detached checkout.
+        // Its exact owned path/common-dir were checked by the caller; require its
+        // retained branch to pin the same commit before allowing clean removal.
+        if (await resolveRefCommit(path, "HEAD") === await resolveRefCommit(path, `refs/heads/${expected}`))
+            return;
+        cleanupFailure("workspace-identity-mismatch", "Detached worktree is not pinned by its owned branch or rebase.", expected, "unproven detached HEAD");
     }
     const branch = await gitLine(["-C", path, "symbolic-ref", "--short", "HEAD"]);
     if (branch !== expected) {
@@ -1127,10 +1107,10 @@ async function assertOwnedWorktree(project, container, path) {
     assertContained(container, canonicalPath);
     if (canonicalPath !== path)
         throw new Error("Managed worktree resolves through a symbolic link.");
-    const root = await canonicalDirectory(await gitLine(["-C", path, "rev-parse", "--show-toplevel"]), "Managed worktree root");
+    const root = await canonicalDirectory(await gitPath(path, ["--show-toplevel"]), "Managed worktree root");
     if (root !== 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");
+    const common = await canonicalDirectory(await gitPath(path, ["--git-common-dir"]), "Managed Git common directory");
     if (common !== project.gitDirectory) {
         cleanupFailure("workspace-identity-mismatch", "Managed worktree belongs to another project.", "Task main Git common directory", "different Git common directory");
     }
@@ -1154,7 +1134,7 @@ async function inspectExactRecordedWorktree(input) {
     if (path !== expectedPath) {
         throw new Error("Recorded managed worktree resolves through a symbolic link.");
     }
-    const root = await canonicalDirectory(await gitLine(["-C", path, "rev-parse", "--show-toplevel"]), "Recorded managed worktree root");
+    const root = await canonicalDirectory(await gitPath(path, ["--show-toplevel"]), "Recorded managed worktree root");
     if (root !== path) {
         throw new Error("Recorded managed worktree root does not match its deterministic path.");
     }
@@ -1162,7 +1142,7 @@ async function inspectExactRecordedWorktree(input) {
     if (branch !== input.branch) {
         throw new Error(`Recorded managed worktree is on an unexpected branch: ${branch}.`);
     }
-    const gitDirectory = await canonicalDirectory(await gitLine(["-C", path, "rev-parse", "--path-format=absolute", "--git-common-dir"]), "Recorded managed Git common directory");
+    const gitDirectory = await canonicalDirectory(await gitPath(path, ["--git-common-dir"]), "Recorded managed Git common directory");
     const destination = await new NodeGitWorkspace().inspect(input.repositoryPath);
     const head = await resolveRefCommit(path, "HEAD");
     const retained = await resolveRefCommit(destination.root, `refs/heads/${input.branch}`);
@@ -1237,9 +1217,30 @@ async function canonicalContainer(path, create) {
     // stay rejected by the managed-path lstat checks.
     return canonicalDirectory(lexical, "Worktree container");
 }
+/** A previous removal may have deleted the whole owner container before its
+ * receipt committed. Resolve only surviving ancestors, without creating it.
+ * Git registration inspection remains mandatory even when this path is absent.
+ */
+async function cleanupContainer(path) {
+    const lexical = resolve(path);
+    if (await pathKind(lexical) === "symlink") {
+        cleanupFailure("workspace-identity-mismatch", "Cleanup container must not be a symbolic link.", "owned directory or missing path", "symbolic link");
+    }
+    try {
+        return await canonicalContainer(lexical, false);
+    }
+    catch (error) {
+        if (!isErrno(error, "ENOENT"))
+            throw error;
+        const parent = dirname(lexical);
+        if (parent === lexical)
+            throw error;
+        return join(await cleanupContainer(parent), relative(parent, lexical));
+    }
+}
 async function canonicalDirectory(path, label) {
-    const value = requireText(path, label);
-    const canonical = await realpath(isAbsolute(value) ? value : resolve(value));
+    requireText(path, label);
+    const canonical = await realpath(isAbsolute(path) ? path : resolve(path));
     return canonical;
 }
 function managedPath(container, directory) {
@@ -1278,7 +1279,7 @@ async function readWorktreeStatus(path) {
     return readStatusGit(path, ["status", "--porcelain=v1", "--untracked-files=all"]);
 }
 async function readStatusGit(path, args) {
-    return git(["--no-optional-locks", "-c", "core.fsmonitor=false",
+    return git(["--no-optional-locks", "-c", "core.fsmonitor=",
         "-c", "protocol.allow=never", "-c", "protocol.file.allow=never",
         "-C", path, ...args], { environment: { GIT_NO_LAZY_FETCH: "1" } });
 }
@@ -1324,8 +1325,10 @@ async function assertStatusProgramsAbsent(path) {
     }
 }
 async function git(args, options = {}) {
+    const program = supportedGit();
+    const invocation = compatibleGitArguments(args);
     try {
-        const execution = executeFile("git", [...args], {
+        const execution = executeFile(program.path, invocation, {
             encoding: "utf8",
             maxBuffer: 1024 * 1024,
             timeout: 30_000,
@@ -1346,6 +1349,7 @@ async function git(args, options = {}) {
     }
 }
 async function gitSucceeds(args) {
+    supportedGit();
     try {
         await git(args);
         return true;
@@ -1355,7 +1359,7 @@ async function gitSucceeds(args) {
     }
 }
 async function gitLine(args) {
-    const lines = (await git(args)).trimEnd().split("\n");
+    const lines = gitOutputLine(await git(args)).split("\n");
     if (lines.length !== 1 || lines[0]?.length === 0 || lines[0]?.includes("\0")) {
         throw new Error("Git returned invalid output.");
     }
@@ -1504,6 +1508,7 @@ function safeRef(value) {
     return ref;
 }
 async function safeFetchBranch(value) {
+    supportedGit();
     const configuredRef = safeRef(value);
     if (configuredRef === "HEAD")
         return configuredRef;
@@ -1595,7 +1600,8 @@ function isCommit(value) {
     return /^[a-f0-9]{40}(?:[a-f0-9]{24})?$/iu.test(value);
 }
 function safeRemote(value) {
-    const remote = requireText(value, "Git remote URL");
+    requireText(value, "Git remote URL");
+    const remote = value;
     if (remote.startsWith("-") || /[\r\n]/.test(remote)) {
         throw new Error("Git remote URL is invalid.");
     }

package/dist/repository/gitWorktreeInventory.js

@@ -0,0 +1,121 @@
+import { execFile } from "node:child_process";
+import { lstat, readFile, readdir, realpath } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { promisify } from "node:util";
+import { gitOutputLine, supportedGit } from "./gitCompatibility.js";
+const execute = promisify(execFile);
+async function run(args) {
+    return (await execute(supportedGit().path, args, {
+        encoding: "utf8", timeout: 10_000, maxBuffer: 1024 * 1024
+    })).stdout;
+}
+export async function gitPath(cwd, args) {
+    return resolve(cwd, gitOutputLine(await run(["-C", cwd, "rev-parse", ...args])));
+}
+async function exists(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+/**
+ * Old porcelain omits locks and does not delimit/quote arbitrary paths. Read
+ * Git's worktree administrative records instead. These are observations only:
+ * never write/prune them, and never infer ownership merely from a directory.
+ * Mutating consumers still check the recorded owner and ask Git to remove it.
+ */
+export async function readGitWorktrees(cwd) {
+    const common = await realpath(await gitPath(cwd, ["--git-common-dir"]));
+    const result = [];
+    // This is also Git's own main-worktree listing convention (including bare
+    // and separate-git-dir repositories), not a claim of managed ownership.
+    const main = basename(common) === ".git" ? dirname(common) : common;
+    result.push(await inspect(common, main, false));
+    const directory = join(common, "worktrees");
+    let entries;
+    try {
+        entries = await readdir(directory, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return result;
+        throw error;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            throw new Error(`Uncertain Git worktree administration: ${join(directory, entry.name)}; retained.`);
+        const admin = join(directory, entry.name);
+        const pointer = gitOutputLine(await readFile(join(admin, "gitdir"), "utf8"));
+        if (basename(pointer) !== ".git") {
+            throw new Error(`Invalid Git worktree back-pointer: ${admin}; retained.`);
+        }
+        // Relative back-pointers are based at the administrative directory,
+        // not the caller's cwd (Git's worktree.useRelativePaths setting).
+        const path = dirname(resolve(admin, pointer));
+        const adminCommon = await realpath(resolve(cwd, gitOutputLine(await run([
+            "-C", cwd, `--git-dir=${admin}`, "rev-parse", "--git-common-dir"
+        ]))));
+        if (adminCommon !== common)
+            throw new Error(`Git worktree common directory mismatch: ${admin}; retained.`);
+        if (await exists(path)) {
+            const actual = await realpath(await gitPath(path, ["--git-dir"]));
+            if (actual !== admin)
+                throw new Error(`Git worktree back-pointer mismatch: ${path}; retained.`);
+        }
+        result.push(await inspect(admin, path, true));
+    }
+    if (new Set(result.map(entry => entry.path)).size !== result.length) {
+        throw new Error("Duplicate Git worktree registrations; retained.");
+    }
+    return result;
+}
+async function inspect(admin, path, linked) {
+    // Ask Git rather than parsing HEAD: Git owns ref storage (including newer
+    // backends), symbolic resolution and per-worktree pseudorefs.
+    let branch;
+    try {
+        branch = gitOutputLine(await run([`--git-dir=${admin}`, "symbolic-ref", "--quiet", "HEAD"]));
+    }
+    catch (error) {
+        if (error.code !== 1)
+            throw error;
+    }
+    if (branch !== undefined && !branch.startsWith("refs/")) {
+        throw new Error(`Invalid Git worktree HEAD: ${admin}; retained.`);
+    }
+    let head;
+    try {
+        head = gitOutputLine(await run([`--git-dir=${admin}`, "rev-parse", "--verify", "HEAD"]));
+        if (!/^[a-f0-9]{40}(?:[a-f0-9]{24})?$/iu.test(head))
+            throw new Error("Invalid Git HEAD");
+    }
+    catch (error) {
+        // A genuinely unborn branch (main or linked) is valid discovery, not cleanup proof.
+        if (branch === undefined)
+            throw error;
+        try {
+            await run([`--git-dir=${admin}`, "show-ref", "--verify", "--quiet", branch]);
+        }
+        catch (missing) {
+            if (missing.code === 1) {
+                return {
+                    path, branch, detached: false, prunable: !await exists(path),
+                    locked: linked && await exists(join(admin, "locked"))
+                };
+            }
+            throw missing;
+        }
+        throw error;
+    }
+    return {
+        path, ...(head === undefined ? {} : { head }),
+        ...(branch === undefined ? {} : { branch }),
+        detached: branch === undefined, prunable: !await exists(path),
+        locked: linked && await exists(join(admin, "locked"))
+    };
+}