@zq-silk/yui 0.2.0 → 0.4.2

package/dist/repository/gitWorkspace.js

@@ -1,15 +1,289 @@
 import { execFile } from "node:child_process";
 import { createHash } from "node:crypto";
-import { lstat, mkdir, realpath } from "node:fs/promises";
+import { lstat, mkdir, realpath, rm } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { promisify } from "node:util";
 const executeFile = promisify(execFile);
-/** The small Git boundary used by repository registration and Task workspaces. */
+/** A remote baseline merge stopped for an explicit Leader resolution. */
+export class RemoteBaselineConflictError extends Error {
+    affectedPaths;
+    constructor(affectedPaths, message, options) {
+        super(message, options);
+        this.name = "RemoteBaselineConflictError";
+        this.affectedPaths = [...affectedPaths];
+    }
+}
+/** The small Git boundary used by project registration and Task workspaces. */
 export class NodeGitWorkspace {
+    async findCommitWithSameTreeInHistory(input) {
+        const source = (await this.inspect(input.repositoryPath, input.sourceCommit)).baseCommit;
+        const history = (await this.inspect(input.repositoryPath, input.historyHead)).baseCommit;
+        if (await this.isAncestor(input.repositoryPath, source, history))
+            return source;
+        const sourceTree = await gitLine([
+            "-C", input.repositoryPath,
+            "rev-parse", "--verify", "--end-of-options", `${source}^{tree}`
+        ]);
+        const pageSize = 1000;
+        for (let skip = 0;; skip += pageSize) {
+            const output = await git([
+                "-C", input.repositoryPath,
+                "log", `--max-count=${pageSize}`, `--skip=${skip}`,
+                "--format=%H%x09%T", history
+            ]);
+            const lines = output.trimEnd().split("\n").filter(Boolean);
+            for (const line of lines) {
+                const [commit, tree, ...extra] = line.split("\t");
+                if (extra.length > 0 || commit === undefined || tree === undefined) {
+                    throw new Error("Git returned invalid publication history.");
+                }
+                if (tree === sourceTree)
+                    return commit;
+            }
+            if (lines.length < pageSize)
+                return null;
+        }
+    }
+    /**
+     * Resolve the configured Project branch directly from its remote.  This is
+     * deliberately read-only: unlike `refresh`, it never advances the stable
+     * Project checkout or changes its refs.
+     */
+    async resolveRemoteHead(input) {
+        const remote = safeRemote(input.remoteUrl);
+        const configuredBranch = await safeFetchBranch(input.branch);
+        const branch = configuredBranch === "HEAD"
+            ? await resolveRemoteHeadBranch(remote)
+            : configuredBranch;
+        const commit = await resolveRemoteBranchCommit(remote, branch);
+        return { branch, commit };
+    }
+    /**
+     * Merge a remote Project baseline into a clean, managed worktree.  The
+     * fetch is performed from that worktree and the stable checkout is never
+     * touched.  Fast-forward updates are preferred; a diverged baseline gets a
+     * deterministic merge commit so the caller can run its normal Integration
+     * checks and CAS the target ref.
+     */
+    async mergeRemoteIntoWorktree(input) {
+        const initial = await this.inspect(input.repositoryPath, "HEAD");
+        if (!await this.isClean(initial.root)) {
+            throw new Error("Managed Task/Integration worktree must be clean before remote merge.");
+        }
+        const fetched = await this.#fetchRemoteHeadIntoWorktree(input);
+        const fetchedCommit = fetched.commit;
+        const fetchedRef = fetched.fetchedRef;
+        try {
+            if (fetchedCommit === initial.baseCommit) {
+                return { fromCommit: initial.baseCommit, toCommit: fetchedCommit, changed: false };
+            }
+            if (await gitSucceeds([
+                "-C", initial.root,
+                "merge-base", "--is-ancestor", fetchedCommit, initial.baseCommit
+            ])) {
+                // The Task already contains the current remote baseline.
+                return { fromCommit: initial.baseCommit, toCommit: initial.baseCommit, changed: false };
+            }
+            if (await gitSucceeds([
+                "-C", initial.root,
+                "merge-base", "--is-ancestor", initial.baseCommit, fetchedCommit
+            ])) {
+                await git(["-C", initial.root, "merge", "--ff-only", "--no-edit", fetchedRef]);
+            }
+            else {
+                try {
+                    await git([
+                        "-C", initial.root,
+                        "-c", "user.name=Yui",
+                        "-c", "user.email=yui@local",
+                        "merge", "--no-edit", "--no-ff", fetchedRef
+                    ]);
+                }
+                catch (error) {
+                    const affected = (await git([
+                        "-C", initial.root,
+                        "diff", "--name-only", "--diff-filter=U"
+                    ])).trim().split("\n").filter(Boolean);
+                    const suffix = affected.length === 0 ? "" : ` (${affected.join(", ")})`;
+                    throw new RemoteBaselineConflictError(affected, `Remote baseline merge conflicts in managed worktree${suffix}; resolve it in the Integration workspace.`, { cause: error });
+                }
+            }
+            const mergedCommit = (await gitLine([
+                "-C", initial.root,
+                "rev-parse", "--verify", "--end-of-options", "HEAD^{commit}"
+            ])).toLowerCase();
+            if (!await this.isClean(initial.root)) {
+                throw new Error("Remote baseline merge left the managed worktree dirty.");
+            }
+            return { fromCommit: initial.baseCommit, toCommit: mergedCommit, changed: true };
+        }
+        finally {
+            await gitSucceeds(["-C", initial.root, "update-ref", "-d", fetchedRef]);
+        }
+    }
+    /** Fetch a remote branch into a managed worktree without changing HEAD. */
+    async fetchRemoteHeadIntoWorktree(input) {
+        const fetched = await this.#fetchRemoteHeadIntoWorktree(input);
+        try {
+            return { branch: fetched.branch, commit: fetched.commit };
+        }
+        finally {
+            await gitSucceeds(["-C", input.repositoryPath, "update-ref", "-d", fetched.fetchedRef]);
+        }
+    }
+    async #fetchRemoteHeadIntoWorktree(input) {
+        const repositoryPath = (await this.inspect(input.repositoryPath, "HEAD")).root;
+        const remote = safeRemote(input.remoteUrl);
+        const configuredBranch = await safeFetchBranch(input.branch);
+        const branch = configuredBranch === "HEAD"
+            ? await resolveRemoteHeadBranch(remote)
+            : configuredBranch;
+        const fetchedRef = remoteBaselineRef(remote, branch);
+        try {
+            await git([
+                "-C", repositoryPath,
+                "fetch", "--no-tags", "--no-write-fetch-head",
+                remote,
+                `refs/heads/${branch}:${fetchedRef}`
+            ]);
+            const commit = await resolveFetchedCommit(repositoryPath, fetchedRef);
+            return { branch, commit, fetchedRef };
+        }
+        catch (error) {
+            await gitSucceeds(["-C", repositoryPath, "update-ref", "-d", fetchedRef]);
+            throw error;
+        }
+    }
+    async refresh(input) {
+        const remote = safeRemote(input.remoteUrl);
+        const configuredStableRef = await safeFetchBranch(input.stableRef);
+        const initial = await this.inspect(input.repositoryPath, "HEAD");
+        await this.#assertRefreshCheckout(initial.root, configuredStableRef, initial.baseCommit);
+        const stableBranch = configuredStableRef === "HEAD"
+            ? await resolveRemoteHeadBranch(remote)
+            : 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();
+        await this.#assertRefreshCheckout(initial.root, stableBranch, initial.baseCommit);
+        if (fetchedCommit === initial.baseCommit) {
+            return {
+                fromCommit: initial.baseCommit,
+                toCommit: fetchedCommit,
+                changed: false
+            };
+        }
+        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}.`);
+        }
+        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
+        };
+    }
+    /**
+     * Fetch a Project's configured development branch into a temporary ref and
+     * return the commit confirmed by that fetch.  The stable checkout is only
+     * inspected; it is never checked out, reset, rebased, or fast-forwarded.
+     */
+    async resolveRemoteBaseline(input) {
+        const remote = safeRemote(input.remoteUrl);
+        const configuredRef = await safeFetchBranch(input.developmentRef);
+        const branch = configuredRef === "HEAD"
+            ? await resolveRemoteHeadBranch(remote)
+            : 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",
+                remote,
+                `refs/heads/${branch}:${temporaryRef}`
+            ]);
+            const fetchedCommit = await gitLine([
+                "-C", repository.root,
+                "rev-parse", "--verify", "--end-of-options", `${temporaryRef}^{commit}`
+            ]);
+            const advertisedCommit = await resolveRemoteBranchCommit(remote, branch);
+            if (fetchedCommit.toLowerCase() !== advertisedCommit) {
+                throw new Error(`Project remote development branch changed while it was fetched: ${branch}.`);
+            }
+            return {
+                branch,
+                commit: fetchedCommit.toLowerCase()
+            };
+        }
+        finally {
+            // A temporary namespace keeps the fetch independent from the stable
+            // branch and FETCH_HEAD.  Cleanup is best effort so the original fetch
+            // or consistency error remains the actionable diagnosis.
+            await gitSucceeds([
+                "-C", repository.root,
+                "update-ref", "-d", temporaryRef
+            ]);
+        }
+    }
+    async clone(input) {
+        const remote = safeRemote(input.remoteUrl);
+        const destination = resolve(requireText(input.destination, "Project destination"));
+        if (await pathKind(destination) !== undefined) {
+            throw new Error(`Project destination already exists: ${destination}.`);
+        }
+        await canonicalContainer(dirname(destination), true);
+        const branch = input.branch === undefined ? undefined : safeRef(input.branch);
+        try {
+            await git([
+                "clone",
+                ...(branch === undefined ? [] : ["--branch", branch]),
+                "--",
+                remote,
+                destination
+            ]);
+        }
+        catch (error) {
+            await rm(destination, { recursive: true, force: true });
+            throw error;
+        }
+        return this.inspect(destination, "HEAD");
+    }
+    async ensureLocalBranch(repositoryPath, branch) {
+        try {
+            return await this.inspect(repositoryPath, branch);
+        }
+        catch (originalError) {
+            const root = (await this.inspect(repositoryPath, "HEAD")).root;
+            const name = safeRef(branch);
+            if (!await gitSucceeds(["check-ref-format", "--branch", name]))
+                throw originalError;
+            const remoteRef = `refs/remotes/origin/${name}`;
+            if (!await gitSucceeds([
+                "-C", root, "show-ref", "--verify", "--quiet", remoteRef
+            ]))
+                throw originalError;
+            await git(["-C", root, "branch", "--", name, remoteRef]);
+            return this.inspect(root, name);
+        }
+    }
     async inspect(repositoryPath, baseRef = "HEAD") {
-        const requested = await canonicalDirectory(repositoryPath, "Repository");
+        const requested = await canonicalDirectory(repositoryPath, "Project");
         const ref = safeRef(baseRef);
-        const root = await canonicalDirectory(await gitLine(["-C", requested, "rev-parse", "--show-toplevel"]), "Repository root");
+        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");
@@ -19,11 +293,115 @@ export class NodeGitWorkspace {
         if (!/^[a-f0-9]{40}(?:[a-f0-9]{24})?$/i.test(baseCommit)) {
             throw new Error("Git returned an invalid base commit.");
         }
-        return { root, gitDirectory, baseRef: ref, baseCommit: baseCommit.toLowerCase() };
+        return {
+            root,
+            gitDirectory,
+            baseRef: ref,
+            baseCommit: baseCommit.toLowerCase()
+        };
+    }
+    async isAncestor(repositoryPath, ancestor, descendant) {
+        const root = (await this.inspect(repositoryPath)).root;
+        return gitSucceeds([
+            "-C", root,
+            "merge-base", "--is-ancestor",
+            safeRef(ancestor),
+            safeRef(descendant)
+        ]);
+    }
+    async headRef(repositoryPath) {
+        const requested = await canonicalDirectory(repositoryPath, "Project");
+        return gitLine(["-C", requested, "rev-parse", "--abbrev-ref", "HEAD"]);
+    }
+    async isClean(repositoryPath) {
+        const root = (await this.inspect(repositoryPath)).root;
+        const status = await git([
+            "-C", root, "status", "--porcelain=v1", "--untracked-files=all"
+        ]);
+        return status.length === 0;
+    }
+    async mergeWorktree(input) {
+        const target = await canonicalDirectory(input.targetPath, "Merge target");
+        const sources = input.sourceRefs.map((source) => safeRef(source));
+        if (sources.length === 0) {
+            throw new Error(`Git merge requires at least one source ref: ${target}.`);
+        }
+        if (!await this.isClean(target)) {
+            throw new Error(`Git merge target must be clean: ${target}.`);
+        }
+        try {
+            // Merge all selected Lane heads in one Git transaction.  A conflict in
+            // any Lane therefore aborts the complete Candidate materialization
+            // instead of leaving an earlier Lane merged into the WorkItem target.
+            await git(["-C", target, "merge", "--no-edit", "--no-ff", ...sources]);
+        }
+        catch (error) {
+            try {
+                await git(["-C", target, "merge", "--abort"]);
+            }
+            catch (abortError) {
+                throw new Error(`Git merge failed and conflict cleanup could not be completed for ${target}.`, { cause: abortError });
+            }
+            throw new Error(`Git merge failed for ${target} from ${sources.join(", ")}; Candidate materialization was not completed.`, { cause: error });
+        }
+    }
+    async resetWorktree(input) {
+        const target = await canonicalDirectory(input.targetPath, "Reset target");
+        const expectedHead = safeRef(input.expectedHead);
+        const restoreHead = safeRef(input.restoreHead);
+        if (!await this.isClean(target)) {
+            throw new Error(`Git reset target must be clean: ${target}.`);
+        }
+        const currentHead = (await this.inspect(target, "HEAD")).baseCommit;
+        if (currentHead !== expectedHead) {
+            throw new Error(`Git reset target changed before compensation: ${target} (${currentHead}).`);
+        }
+        try {
+            await git(["-C", target, "reset", "--hard", restoreHead]);
+            const restoredHead = (await this.inspect(target, "HEAD")).baseCommit;
+            if (restoredHead !== restoreHead || !await this.isClean(target)) {
+                throw new Error(`Git reset target did not restore its exact head: ${target}.`);
+            }
+        }
+        catch (error) {
+            throw new Error(`Git reset compensation failed for ${target}; Candidate materialization remains retained for diagnosis.`, { cause: error });
+        }
+    }
+    async #assertRefreshCheckout(repositoryPath, stableRef, expectedCommit) {
+        if (stableRef !== "HEAD") {
+            const currentBranch = await this.headRef(repositoryPath);
+            if (currentBranch !== stableRef) {
+                const found = currentBranch === "HEAD" ? "detached HEAD" : currentBranch;
+                throw new Error(`Project checkout must be on its stable branch: expected ${stableRef}, found ${found}.`);
+            }
+        }
+        const head = await this.inspect(repositoryPath, "HEAD");
+        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({
+            repositoryPath: input.repositoryPath,
+            container: input.container,
+            identity: worktreeIdentity(input.taskId, input.roleName),
+            baseRef: input.baseRef
+        });
+    }
+    async ensureIntegrationWorktree(input) {
+        return this.#ensureManagedWorktree({
+            repositoryPath: input.repositoryPath,
+            container: input.container,
+            identity: integrationWorktreeIdentity(input.taskId, input.integrationId),
+            baseRef: input.baseRef
+        });
+    }
+    async #ensureManagedWorktree(input) {
         const container = await canonicalContainer(input.container, true);
-        const identity = worktreeIdentity(input.taskId, input.roleName);
+        const identity = input.identity;
         const path = managedPath(container, identity.directory);
         const kind = await pathKind(path);
         if (kind === "symlink")
@@ -31,31 +409,55 @@ export class NodeGitWorkspace {
         if (kind === "directory") {
             // A worktree already created before a crash remains usable even if the
             // original base branch/tag is later deleted.
-            const repository = await this.inspect(input.repositoryPath);
-            await assertOwnedWorktree(repository, container, path);
+            const project = await this.inspect(input.repositoryPath);
+            await assertOwnedWorktree(project, container, path);
             await assertExpectedBranch(path, identity.branch);
             const head = await gitLine([
                 "-C", path, "rev-parse", "--verify", "--end-of-options", "HEAD^{commit}"
             ]);
             return { path, branch: identity.branch, baseCommit: head.toLowerCase() };
         }
-        const repository = await this.inspect(input.repositoryPath, input.baseRef);
+        const project = await this.inspect(input.repositoryPath, input.baseRef);
         await canonicalContainer(dirname(path), true);
         const branchRef = `refs/heads/${identity.branch}`;
         const branchExists = await gitSucceeds([
-            "-C", repository.root, "show-ref", "--verify", "--quiet", branchRef
+            "-C", project.root, "show-ref", "--verify", "--quiet", branchRef
         ]);
         await git(branchExists
-            ? ["-C", repository.root, "worktree", "add", "--", path, identity.branch]
+            ? ["-C", project.root, "worktree", "add", "--", path, identity.branch]
             : [
-                "-C", repository.root, "worktree", "add", "-b", identity.branch,
-                "--", path, repository.baseCommit
+                "-C", project.root, "worktree", "add", "-b", identity.branch,
+                "--", path, project.baseCommit
             ]);
-        await assertOwnedWorktree(repository, container, path);
+        await assertOwnedWorktree(project, container, path);
         await assertExpectedBranch(path, identity.branch);
-        return { path, branch: identity.branch, baseCommit: repository.baseCommit };
+        const head = await gitLine([
+            "-C", path, "rev-parse", "--verify", "--end-of-options", "HEAD^{commit}"
+        ]);
+        return { path, branch: identity.branch, baseCommit: head.toLowerCase() };
     }
     async removeWorktree(input) {
+        const state = await this.inspectWorktree(input);
+        if (state === "dirty")
+            return state;
+        const container = resolve(input.container);
+        const identity = worktreeIdentity(input.taskId, input.roleName);
+        const path = managedPath(container, identity.directory);
+        const project = await this.inspect(input.repositoryPath);
+        if (state === "missing") {
+            if (input.deleteBranch === true) {
+                await git(["-C", project.root, "worktree", "prune"]);
+                await deleteBranchIfPresent(project.root, identity.branch);
+            }
+            return state;
+        }
+        await git(["-C", project.root, "worktree", "remove", "--", path]);
+        if (input.deleteBranch === true) {
+            await deleteBranchIfPresent(project.root, identity.branch);
+        }
+        return "removed";
+    }
+    async inspectWorktree(input) {
         const container = resolve(input.container);
         const path = managedPath(container, worktreeIdentity(input.taskId, input.roleName).directory);
         const kind = await pathKind(path);
@@ -64,15 +466,67 @@ export class NodeGitWorkspace {
         if (kind === "symlink")
             throw new Error("Managed worktree path must not be a symbolic link.");
         const canonicalContainerPath = await canonicalContainer(container, false);
-        const repository = await this.inspect(input.repositoryPath);
-        await assertOwnedWorktree(repository, canonicalContainerPath, path);
+        const project = await this.inspect(input.repositoryPath);
+        await assertOwnedWorktree(project, canonicalContainerPath, path);
         const porcelain = await git(["-C", path, "status", "--porcelain=v1", "--untracked-files=all"]);
-        if (porcelain.length > 0)
-            return "dirty";
-        await git(["-C", repository.root, "worktree", "remove", "--", path]);
-        return "removed";
+        return porcelain.length > 0 ? "dirty" : "clean";
+    }
+    async removeIntegrationWorktree(input) {
+        return this.#removeManagedWorktree({
+            repositoryPath: input.repositoryPath,
+            container: input.container,
+            identity: integrationWorktreeIdentity(input.taskId, input.integrationId),
+            discardChanges: input.discardChanges
+        });
+    }
+    async #removeManagedWorktree(input) {
+        const container = resolve(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 === "directory") {
+            const canonicalContainerPath = await canonicalContainer(container, false);
+            await assertOwnedWorktree(repository, canonicalContainerPath, path);
+            await assertExpectedBranch(path, input.identity.branch);
+            if (input.discardChanges === true) {
+                await git(["-C", repository.root, "worktree", "remove", "--force", "--", path]);
+            }
+            else {
+                const porcelain = await git([
+                    "-C", path, "status", "--porcelain=v1", "--untracked-files=all"
+                ]);
+                if (porcelain.length > 0)
+                    return "dirty";
+                if (input.expectedBaseCommit !== undefined
+                    && input.allowCommittedChanges !== true) {
+                    const head = await gitLine([
+                        "-C", path, "rev-parse", "--verify", "--end-of-options", "HEAD^{commit}"
+                    ]);
+                    if (head.toLowerCase() !== input.expectedBaseCommit.toLowerCase())
+                        return "dirty";
+                }
+                await git(["-C", repository.root, "worktree", "remove", "--", path]);
+            }
+        }
+        const branchRef = `refs/heads/${input.identity.branch}`;
+        if (await gitSucceeds([
+            "-C", repository.root, "show-ref", "--verify", "--quiet", branchRef
+        ])) {
+            await git(["-C", repository.root, "branch", "-D", "--", input.identity.branch]);
+        }
+        return kind === "directory" ? "removed" : "missing";
     }
 }
+async function deleteBranchIfPresent(repositoryRoot, branch) {
+    const branchRef = `refs/heads/${branch}`;
+    if (!await gitSucceeds([
+        "-C", repositoryRoot, "show-ref", "--verify", "--quiet", branchRef
+    ]))
+        return;
+    await git(["-C", repositoryRoot, "branch", "-D", "--", branch]);
+}
 export function worktreeIdentity(taskId, roleName) {
     const taskKey = safeIdentity(taskId, "Task id");
     const roleKey = safeIdentity(roleName, "Role name");
@@ -81,6 +535,14 @@ export function worktreeIdentity(taskId, roleName) {
         branch: `yui/${gitRefSegment(taskKey)}/${gitRefSegment(roleKey)}`
     };
 }
+export function integrationWorktreeIdentity(taskId, integrationId) {
+    const taskKey = safeIdentity(taskId, "Task id");
+    const integrationKey = safeIdentity(integrationId, "Integration Attempt id");
+    return {
+        directory: join(taskKey, "integrations", integrationKey),
+        branch: `yui/${gitRefSegment(taskKey)}/integration/${gitRefSegment(integrationKey)}`
+    };
+}
 function gitRefSegment(identity) {
     if (/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(identity)
         && !identity.includes("..")
@@ -97,7 +559,7 @@ async function assertExpectedBranch(path, expected) {
         throw new Error(`Managed worktree is on an unexpected branch: ${branch}.`);
     }
 }
-async function assertOwnedWorktree(repository, container, path) {
+async function assertOwnedWorktree(project, container, path) {
     const canonicalPath = await canonicalDirectory(path, "Managed worktree");
     assertContained(container, canonicalPath);
     if (canonicalPath !== path)
@@ -106,8 +568,8 @@ async function assertOwnedWorktree(repository, container, path) {
     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");
-    if (common !== repository.gitDirectory) {
-        throw new Error("Managed worktree belongs to another repository.");
+    if (common !== project.gitDirectory) {
+        throw new Error("Managed worktree belongs to another project.");
     }
 }
 async function canonicalContainer(path, create) {
@@ -198,6 +660,98 @@ function safeRef(value) {
         throw new Error("Git base ref is invalid.");
     return ref;
 }
+async function safeFetchBranch(value) {
+    const configuredRef = safeRef(value);
+    if (configuredRef === "HEAD")
+        return configuredRef;
+    const branchPrefix = "refs/heads/";
+    const branch = configuredRef.startsWith(branchPrefix)
+        ? configuredRef.slice(branchPrefix.length)
+        : configuredRef;
+    if (!await gitSucceeds(["check-ref-format", "--branch", branch])) {
+        throw new Error("Git stable branch is invalid.");
+    }
+    return branch;
+}
+async function resolveRemoteHeadBranch(remote) {
+    let output;
+    try {
+        output = await git(["ls-remote", "--symref", remote, "HEAD"]);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : "Git command failed.";
+        throw new Error(`Project remote HEAD could not be resolved: ${detail}`, { cause: error });
+    }
+    const symbolicLines = output.split("\n").filter((line) => line.startsWith("ref: "));
+    const prefix = "ref: refs/heads/";
+    const suffix = "\tHEAD";
+    const symbolic = symbolicLines.length === 1 ? symbolicLines[0] : "";
+    if (!symbolic.startsWith(prefix) || !symbolic.endsWith(suffix)) {
+        throw invalidRemoteHead();
+    }
+    const branch = symbolic.slice(prefix.length, -suffix.length);
+    if (branch === "HEAD")
+        throw invalidRemoteHead();
+    try {
+        return await safeFetchBranch(branch);
+    }
+    catch {
+        throw invalidRemoteHead();
+    }
+}
+async function resolveRemoteBranchCommit(remote, branch) {
+    const target = `refs/heads/${branch}`;
+    let output;
+    try {
+        output = await git(["ls-remote", "--refs", remote, target]);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : "Git command failed.";
+        throw new Error(`Project remote development branch could not be resolved: ${branch}: ${detail}`, { cause: error });
+    }
+    const matches = output
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0)
+        .map((line) => line.split(/\s+/u))
+        .filter(([commit, ref]) => ref === target && commit !== undefined);
+    if (matches.length !== 1) {
+        throw new Error(`Project remote development branch could not be resolved: ${branch}.`);
+    }
+    const commit = matches[0][0];
+    if (!isCommit(commit)) {
+        throw new Error(`Project remote development branch returned an invalid commit: ${branch}.`);
+    }
+    return commit.toLowerCase();
+}
+async function resolveFetchedCommit(repositoryPath, fetchedRef) {
+    const commit = (await gitLine([
+        "-C", repositoryPath,
+        "rev-parse", "--verify", "--end-of-options", `${fetchedRef}^{commit}`
+    ])).toLowerCase();
+    if (!/^[a-f0-9]{40}(?:[a-f0-9]{24})?$/u.test(commit)) {
+        throw new Error("Git returned an invalid fetched remote commit.");
+    }
+    return commit;
+}
+function remoteBaselineRef(remote, branch) {
+    const identity = `${remote}\0${branch}\0${process.pid}\0${Date.now()}\0${Math.random()}`;
+    const digest = createHash("sha256").update(identity).digest("hex");
+    return `refs/yui/task-baselines/${digest}`;
+}
+function invalidRemoteHead() {
+    return new Error("Project remote HEAD must identify a valid symbolic branch under refs/heads/.");
+}
+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");
+    if (remote.startsWith("-") || /[\r\n]/.test(remote)) {
+        throw new Error("Git remote URL is invalid.");
+    }
+    return remote;
+}
 function requireText(value, label) {
     if (typeof value !== "string" || value.trim().length === 0 || value.includes("\0")) {
         throw new Error(`${label} is required.`);