@zq-silk/yui 0.5.1 → 0.5.3

package/dist/cli/commandCatalog.js

@@ -229,8 +229,8 @@ const taskChildren = [
     {
         name: "rebuild",
         summary: "Rebuild a legacy Task workspace under its canonical identity.",
-        usage: "yui task rebuild <task>",
-        options: []
+        usage: "yui task rebuild <task> [--latest]",
+        options: ["--latest"]
     },
     {
         name: "history",

package/dist/commands/projectCommands.js

@@ -205,11 +205,11 @@ async function cloneProject(args, store, options) {
 }
 /**
  * Migrate an external Project binding to a Home-managed repository. The
- * remote is cloned and both configured branches are verified against the
- * advertised remote SHAs before the catalog record switches; the old
- * checkout is never touched and stays usable until the switch commits. A
- * failed migration leaves no partial state: the unfinished managed clone is
- * removed so the command can be retried cleanly.
+ * remote is cloned, both configured branches are verified against the
+ * advertised remote SHAs, and local Yui refs are imported before the catalog
+ * record switches. The old checkout is never touched. A failed migration
+ * leaves no partial state: the unfinished managed clone is removed so the
+ * command can be retried cleanly.
  */
 async function migrateProject(args, store, options) {
     const usage = "Project migrate usage: yui project migrate <project> [--preflight].";
@@ -264,6 +264,15 @@ async function migrateProject(args, store, options) {
                         localCommit: (await git.inspect(verifyRoot, project.developmentBranch)).baseCommit
                     }])
         ]);
+        const copyRefs = git.copyRefs;
+        if (typeof copyRefs !== "function") {
+            throw new Error(`Git workspace cannot preserve local Yui refs for Project: ${project.id}.`);
+        }
+        await copyRefs.call(git, {
+            sourceRepositoryPath: project.path,
+            destinationRepositoryPath: verifyRoot,
+            patterns: ["refs/heads/yui/", "refs/yui/archive/"]
+        });
         if (parsed.preflight) {
             return { project, path: destination, preflight: true };
         }

package/dist/commands/taskWorkspaceCommands.js

@@ -20,11 +20,17 @@ export async function runTaskWorkspaceCommand(args, store, preparer, options = {
         + "yui task history list|archive [task], yui task replace <task>.");
 }
 async function rebuildTaskCommand(args, preparer) {
-    const usage = "Task rebuild usage: yui task rebuild <task>.";
+    const usage = "Task rebuild usage: yui task rebuild <task> [--latest].";
     const taskId = args[0];
-    if (taskId === undefined || args.length !== 1)
+    const options = new Set(args.slice(1));
+    if (taskId === undefined
+        || options.size !== args.length - 1
+        || [...options].some((option) => option !== "--latest")) {
         throw usageError(usage);
-    const result = await preparer.rebuildTaskWorkspace(taskId);
+    }
+    const result = await preparer.rebuildTaskWorkspace(taskId, {
+        latestRemote: options.has("--latest")
+    });
     const archived = result.archived.length === 0
         ? "no legacy refs"
         : `${result.archived.length} legacy ref(s) archived`;
@@ -35,7 +41,8 @@ async function rebuildTaskCommand(args, preparer) {
         data: {
             taskId: result.task.id,
             archived: result.archived,
-            resumed: result.resumed
+            resumed: result.resumed,
+            latestRemote: options.has("--latest")
         }
     };
 }

package/dist/repository/gitWorkspace.js

@@ -1,5 +1,5 @@
 import { execFile } from "node:child_process";
-import { createHash } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 import { lstat, mkdir, realpath, rm } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { promisify } from "node:util";
@@ -322,6 +322,73 @@ export class NodeGitWorkspace {
         return output.length === 0 ? [] : output.split("\n").map((line) => line.trim())
             .filter((line) => line.length > 0);
     }
+    async copyRefs(input) {
+        const source = await this.inspect(input.sourceRepositoryPath);
+        const destination = await this.inspect(input.destinationRepositoryPath);
+        if (source.gitDirectory === destination.gitDirectory)
+            return [];
+        const refs = [...new Set((await Promise.all(input.patterns.map((pattern) => this.listRefs(source.root, pattern)))).flat())].sort();
+        const snapshots = [];
+        for (const ref of refs) {
+            const name = safeRef(ref);
+            const commit = await resolveRefCommit(source.root, name);
+            if (await this.refExists(destination.root, name)) {
+                const existing = await resolveRefCommit(destination.root, name);
+                if (existing !== commit) {
+                    throw new Error(`Destination ref already exists at a different commit: ${name}.`);
+                }
+            }
+            snapshots.push({ ref: name, commit });
+        }
+        const importRoot = `refs/yui/migration-import/${randomBytes(16).toString("hex")}`;
+        const temporary = [];
+        try {
+            for (const [index, snapshot] of snapshots.entries()) {
+                const importedRef = `${importRoot}/${index}`;
+                await git([
+                    "-C", destination.root,
+                    "fetch", "--no-tags", "--no-write-fetch-head", "--",
+                    source.root, `${snapshot.ref}:${importedRef}`
+                ]);
+                const imported = await resolveRefCommit(destination.root, importedRef);
+                if (imported !== snapshot.commit) {
+                    throw new Error(`Imported ref did not preserve its exact commit: ${snapshot.ref}.`);
+                }
+                temporary.push({ ref: importedRef, commit: imported });
+            }
+            // Freeze the source snapshots through publication. A moving local ref is
+            // never silently copied under an earlier/later identity.
+            for (const snapshot of snapshots) {
+                if (await resolveRefCommit(source.root, snapshot.ref) !== snapshot.commit) {
+                    throw new Error(`Source ref changed while it was being copied: ${snapshot.ref}.`);
+                }
+            }
+            for (const snapshot of snapshots) {
+                if (await this.refExists(destination.root, snapshot.ref)) {
+                    if (await resolveRefCommit(destination.root, snapshot.ref) !== snapshot.commit) {
+                        throw new Error(`Destination ref changed while it was being copied: ${snapshot.ref}.`);
+                    }
+                    continue;
+                }
+                await git([
+                    "-C", destination.root,
+                    "update-ref", "--no-deref", snapshot.ref, snapshot.commit,
+                    "0".repeat(snapshot.commit.length)
+                ]);
+            }
+            return snapshots.map(({ ref }) => ref);
+        }
+        finally {
+            for (const entry of temporary) {
+                if (await this.refExists(destination.root, entry.ref)) {
+                    await git([
+                        "-C", destination.root,
+                        "update-ref", "-d", "--no-deref", entry.ref, entry.commit
+                    ]);
+                }
+            }
+        }
+    }
     async archiveRef(input) {
         const root = (await this.inspect(input.repositoryPath)).root;
         const source = safeRef(input.sourceRef);
@@ -342,7 +409,7 @@ export class NodeGitWorkspace {
         else {
             // Create the archive ref only if it does not exist yet (old value zero).
             await git([
-                "-C", root, "update-ref", "--no-deref", target, commit, "0".repeat(40)
+                "-C", root, "update-ref", "--no-deref", target, commit, "0".repeat(commit.length)
             ]);
         }
         // Delete the source only if it still exists and still points at the
@@ -510,6 +577,37 @@ export class NodeGitWorkspace {
         }
         return "removed";
     }
+    async inspectRecordedWorktree(input) {
+        const inspected = await inspectExactRecordedWorktree(input);
+        return inspected?.state ?? "missing";
+    }
+    async removeRecordedWorktree(input) {
+        const inspected = await inspectExactRecordedWorktree(input);
+        if (inspected === undefined)
+            return "missing";
+        if (inspected.state === "dirty")
+            return "dirty";
+        // Revalidate immediately before asking the worktree's own Git common-dir
+        // to remove it. This never relies on the Project catalog's former path.
+        const current = await inspectExactRecordedWorktree(input);
+        if (current === undefined)
+            return "missing";
+        if (current.state === "dirty")
+            return "dirty";
+        await retainCommitRef(current.destinationRoot, input.retainedRef, current.head);
+        await git(["-C", current.path, "worktree", "remove", "--", current.path]);
+        if (await pathKind(current.path) !== undefined) {
+            throw new Error(`Recorded managed worktree remained after removal: ${current.path}.`);
+        }
+        if (current.gitDirectory !== current.destinationGitDirectory) {
+            await git([
+                `--git-dir=${current.gitDirectory}`,
+                "update-ref", "-d", "--no-deref", `refs/heads/${safeRef(input.branch)}`,
+                current.head
+            ]);
+        }
+        return "removed";
+    }
     async inspectWorktree(input) {
         const container = resolve(input.container);
         const path = managedPath(container, worktreeIdentity(input.taskSegment, input.roleName).directory);
@@ -625,6 +723,75 @@ async function assertOwnedWorktree(project, container, path) {
         throw new Error("Managed worktree belongs to another project.");
     }
 }
+async function inspectExactRecordedWorktree(input) {
+    const container = resolve(input.container);
+    const identity = worktreeIdentity(input.taskSegment, input.roleName);
+    const expectedPath = managedPath(container, identity.directory);
+    if (resolve(input.path) !== expectedPath || input.branch !== identity.branch) {
+        throw new Error("Recorded managed worktree identity is invalid.");
+    }
+    const kind = await pathKind(expectedPath);
+    if (kind === undefined)
+        return undefined;
+    if (kind === "symlink") {
+        throw new Error("Recorded managed worktree path must not be a symbolic link.");
+    }
+    const canonicalContainerPath = await canonicalContainer(container, false);
+    const path = await canonicalDirectory(expectedPath, "Recorded managed worktree");
+    assertContained(canonicalContainerPath, path);
+    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");
+    if (root !== path) {
+        throw new Error("Recorded managed worktree root does not match its deterministic path.");
+    }
+    const branch = await gitLine(["-C", path, "symbolic-ref", "--short", "HEAD"]);
+    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 destination = await new NodeGitWorkspace().inspect(input.repositoryPath);
+    const head = await resolveRefCommit(path, "HEAD");
+    const retained = await resolveRefCommit(destination.root, `refs/heads/${input.branch}`);
+    if (retained !== head) {
+        throw new Error(`Recorded managed worktree is not retained by the current Project: ${input.branch}.`);
+    }
+    const status = await git(["-C", path, "status", "--porcelain=v1", "--untracked-files=all"]);
+    return {
+        path,
+        gitDirectory,
+        destinationGitDirectory: destination.gitDirectory,
+        destinationRoot: destination.root,
+        head,
+        state: status.length === 0 ? "clean" : "dirty"
+    };
+}
+async function resolveRefCommit(repositoryPath, ref) {
+    const commit = (await gitLine([
+        "-C", repositoryPath,
+        "rev-parse", "--verify", "--end-of-options", `${safeRef(ref)}^{commit}`
+    ])).toLowerCase();
+    if (!isCommit(commit))
+        throw new Error("Git returned an invalid ref commit.");
+    return commit;
+}
+async function retainCommitRef(repositoryPath, ref, commit) {
+    const target = safeRef(ref);
+    if (await gitSucceeds([
+        "-C", repositoryPath,
+        "rev-parse", "--verify", "--quiet", "--end-of-options", `${target}^{commit}`
+    ])) {
+        if (await resolveRefCommit(repositoryPath, target) !== commit) {
+            throw new Error(`Retained ref already exists at a different commit: ${target}.`);
+        }
+        return;
+    }
+    await git([
+        "-C", repositoryPath,
+        "update-ref", "--no-deref", target, commit, "0".repeat(commit.length)
+    ]);
+}
 async function canonicalContainer(path, create) {
     const lexical = resolve(path);
     if (create)

package/dist/repository/taskWorkspacePreparer.js

@@ -1485,7 +1485,7 @@ export class FileTaskWorkspacePreparer {
      * A Task that already carries an identity takes the resume path: only the
      * pending legacy archive and old-worktree removal run.
      */
-    async rebuildTaskWorkspace(taskId) {
+    async rebuildTaskWorkspace(taskId, options = {}) {
         const task = requireTask(this.store, taskId);
         if (!["draft", "active"].includes(task.status)) {
             throw new Error(`Only a draft or active Task can be rebuilt in place: ${task.id}/${task.status}.`);
@@ -1508,7 +1508,7 @@ export class FileTaskWorkspacePreparer {
             throw new Error(`Task main workspace ownership is invalid: ${task.id}.`);
         }
         if (existing !== null
-            && await this.#inspectEntries(task.id, MAIN_WORKTREE, existing.entries) === "dirty") {
+            && await this.#inspectLegacyTaskEntries(task, existing.entries) === "dirty") {
             throw new Error(`Task workspace is dirty and blocks the rebuild: ${task.id}.`);
         }
         // Resolve verified remote SHAs before any Git side effect, mirroring the
@@ -1518,9 +1518,12 @@ export class FileTaskWorkspacePreparer {
         const pins = new Map();
         for (const binding of task.projectBindings) {
             const project = requireProject(this.store, binding.projectId);
-            const useRemoteDefault = defaultProjects.has(project.id)
-                && project.remoteUrl !== undefined
-                && !looksLikeCommit(binding.baseRef);
+            // `--latest` explicitly re-resolves every remote-backed Project. Without
+            // it, only a still-symbolic creation default is refreshed; an explicit
+            // or previously pinned commit retains the established rebuild behavior.
+            const useRemoteDefault = (options.latestRemote === true
+                || (defaultProjects.has(project.id) && !looksLikeCommit(binding.baseRef)))
+                && project.remoteUrl !== undefined;
             if (useRemoteDefault) {
                 const resolver = this.git.resolveRemoteBaseline;
                 if (typeof resolver !== "function") {
@@ -1529,9 +1532,9 @@ export class FileTaskWorkspacePreparer {
                 const remote = await resolver.call(this.git, {
                     repositoryPath: project.path,
                     remoteUrl: project.remoteUrl,
-                    // The binding captured the configured development ref at Task
-                    // creation; use that snapshot even if the Project catalog changed.
-                    developmentRef: binding.baseRef
+                    developmentRef: options.latestRemote === true
+                        ? project.developmentBranch
+                        : binding.baseRef
                 });
                 pins.set(project.id, remote.commit);
             }
@@ -1792,9 +1795,14 @@ export class FileTaskWorkspacePreparer {
     async #removeLegacyWorktrees(task, projectIds) {
         for (const projectId of projectIds) {
             const project = requireProject(this.store, projectId);
-            const removal = await this.git.removeWorktree({
+            const container = this.#projectContainer(project.name);
+            const branch = worktreeIdentity(task.id, MAIN_WORKTREE).branch;
+            const removal = await this.git.removeRecordedWorktree({
                 repositoryPath: project.path,
-                container: this.#projectContainer(project.name),
+                container,
+                path: join(container, task.id, MAIN_WORKTREE),
+                branch,
+                retainedRef: taskArchiveRef(this.store.getHomeIdentity().homeId, `refs/heads/${branch}`),
                 taskSegment: task.id,
                 roleName: MAIN_WORKTREE
             });
@@ -1803,6 +1811,24 @@ export class FileTaskWorkspacePreparer {
             }
         }
     }
+    async #inspectLegacyTaskEntries(task, entries) {
+        let found = false;
+        for (const entry of entries) {
+            const project = requireProject(this.store, entry.projectId);
+            const state = await this.git.inspectRecordedWorktree({
+                repositoryPath: project.path,
+                container: this.#projectContainer(project.name),
+                path: entry.path,
+                branch: entry.branch,
+                taskSegment: task.id,
+                roleName: MAIN_WORKTREE
+            });
+            if (state === "dirty")
+                return state;
+            found ||= state === "clean";
+        }
+        return found ? "clean" : "missing";
+    }
     #recordWorkspaceRemoval(task, workspace, fallback, workItem) {
         this.store.transaction((tx) => {
             if (workspace.owner.type === "task") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zq-silk/yui",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Local control plane for long-running native agent CLI sessions backed by tmux.",
   "license": "MIT",
   "private": false,