@zq-silk/yui 0.4.2 → 0.5.0

package/dist/cli/commandCatalog.js

@@ -226,6 +226,36 @@ const taskChildren = [
         options: ["--integrated", "--abandon"]
     },
     { name: "reconcile", summary: "Run one immediate Controller reconciliation.", usage: "yui task reconcile <id>" },
+    {
+        name: "rebuild",
+        summary: "Rebuild a legacy Task workspace under its canonical identity.",
+        usage: "yui task rebuild <task>",
+        options: []
+    },
+    {
+        name: "history",
+        summary: "Inspect and archive legacy Task refs in the Home repository.",
+        sections: [{ id: "manage", title: "Commands", entries: ["list", "archive"] }],
+        children: [
+            {
+                name: "list",
+                summary: "List legacy Task refs and their live owners.",
+                usage: "yui task history list [--task <task>]"
+            },
+            {
+                name: "archive",
+                summary: "Archive legacy Task refs without a live owner.",
+                usage: "yui task history archive [<task>] [--force]",
+                options: ["--force"]
+            }
+        ]
+    },
+    {
+        name: "replace",
+        summary: "Create a draft successor for a terminal Task.",
+        usage: "yui task replace <task> [--title <text>]",
+        options: ["--title"]
+    },
     {
         name: "message",
         summary: "Manage durable Task messages.",
@@ -860,7 +890,7 @@ export const ROOT_COMMAND = buildNode({
             name: "task",
             summary: "Manage Tasks, WorkItems, Agent Runs, and integration.",
             sections: [
-                { id: "lifecycle", title: "Lifecycle", entries: ["create", "project", "update", "activate", "complete", "reopen", "retire", "list", "show", "context", "archive", "reconcile"] },
+                { id: "lifecycle", title: "Lifecycle", entries: ["create", "project", "update", "activate", "complete", "reopen", "retire", "list", "show", "context", "archive", "rebuild", "history", "replace", "reconcile"] },
                 { id: "collaboration", title: "Collaboration", entries: ["message", "input", "work", "run", "review", "integration", "role", "enter"] },
                 { id: "knowledge", title: "Task Knowledge", entries: ["brief", "decision", "milestone", "event"] }
             ],

package/dist/cli.js

@@ -28,6 +28,7 @@ import { runProfileCommand } from "./commands/profileCommands.js";
 import { dispatchPreparedReviewRound, failPendingReviewRound, RESUMED_PENDING_FINAL_REVIEW, TERMINALIZED_LEADER_BEFORE_FINAL_REVIEW, TaskFinalReviewDispatchDriftError, preserveReviewRoundWorkspace, parseTaskCompletionRequest, preflightTaskCompletion, runTaskCommand, normalizedExecutionLanePlan, validateTaskArchiveRequest } from "./commands/taskCommands.js";
 import { taskActor } from "./commands/taskActor.js";
 import { runTaskIntegrationCommand } from "./commands/taskIntegrationCommands.js";
+import { runTaskWorkspaceCommand } from "./commands/taskWorkspaceCommands.js";
 import { reconcileTaskRemoteBaselines } from "./commands/taskCompletionGate.js";
 import { FileCompletionManager, resolveCliIdentity } from "./completion/fileCompletionManager.js";
 import { assertFileTaskControllerStorageCompatible, ensureFileTaskController, FileTaskWorkflowRuntime, refreshRunningFileTaskControllerConfiguration, refreshRunningFileTaskControllerEnvironment, restartFileTaskController, stopFileTaskController } from "./controller/clientRuntime.js";
@@ -446,6 +447,13 @@ export async function main() {
             emit(result.output, false, result.data);
             return;
         }
+        if (resolved[1] === "rebuild"
+            || resolved[1] === "history"
+            || resolved[1] === "replace") {
+            const result = await runTaskWorkspaceCommand(resolved.slice(1), store, workspacePreparer);
+            emit(result.output, false, result.data);
+            return;
+        }
         const enteringTask = (resolved[1] === "enter")
             || (resolved[1] === "role" && resolved[2] === "enter");
         if (enteringTask) {

package/dist/commands/projectCommands.js

@@ -1,9 +1,10 @@
+import { existsSync } from "node:fs";
 import { readdir, rm } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { usageError } from "../errors/cliError.js";
 import { defaultTableWidth, renderTable } from "../output/table.js";
 import { NodeGitWorkspace } from "../repository/gitWorkspace.js";
-import { addProjectKnowledge, createProject, retireProjectKnowledge, resolveProject, updateProjectKnowledge, updateProjectMetadata, validateProjectName } from "../repository/project.js";
+import { addProjectKnowledge, createProject, managedProjectPath, retireProjectKnowledge, resolveProject, updateProjectKnowledge, updateProjectMetadata, validateProject, validateProjectName } from "../repository/project.js";
 export async function runProjectCommand(args, store, options = {}) {
     const [command, ...rest] = args;
     if (command === "add" || command === "clone") {
@@ -24,6 +25,15 @@ export async function runProjectCommand(args, store, options = {}) {
             data: refreshed
         };
     }
+    if (command === "migrate") {
+        const migrated = await migrateProject(rest, store, options);
+        return {
+            output: migrated.preflight
+                ? `Project ${migrated.project.id} can be migrated to a Home-managed repository at ${migrated.path}\n`
+                : `Migrated project ${migrated.project.id} to a Home-managed repository at ${migrated.path}\n`,
+            data: migrated
+        };
+    }
     if (command === "update") {
         const project = await updateProject(rest, store, options);
         return {
@@ -123,24 +133,37 @@ function renderDiscoveredProjects(projects) {
     ]), defaultTableWidth())}\n`;
 }
 async function cloneProject(args, store, options) {
-    const usage = "Project clone usage: yui project clone <name> <remote> [--alias <name> ...] [--stable <ref>] [--development <ref>].";
+    const usage = "Project clone usage: yui project clone <name> <remote> [--alias <name> ...] [--stable <ref>] [--development <ref>] [--external].";
     const parsed = parseCloneArguments(args, usage);
-    const workspace = store.getConfig().defaultWorkspace;
-    if (workspace === undefined)
-        throw usageError("No default workspace is configured; run yui setup.");
     const git = options.git ?? new NodeGitWorkspace();
     const name = validateProjectName(parsed.name);
-    const workspaceRoot = resolve(workspace);
-    const destination = resolve(workspaceRoot, name);
-    if (dirname(destination) !== workspaceRoot) {
-        throw usageError("Project clone destination must be directly inside the configured workspace.");
-    }
-    assertOutsideManagedWorktrees(destination, workspace);
     const stableRef = parsed.stable ?? "HEAD";
     const developmentRef = parsed.development ?? stableRef;
     const projectId = store.nextProjectId();
     const now = (options.now ?? (() => new Date()))();
-    const candidate = createProject(projectId, name, destination, { stable: stableRef, development: developmentRef }, now, { aliases: parsed.aliases, remoteUrl: parsed.remote });
+    // A remote-URL binding is Home-managed by default: its canonical repository
+    // lives below the persistent Home, so the runtime never depends on a
+    // user-controlled checkout path. --external is an explicit opt-in to the
+    // legacy clone-inside-the-workspace mode.
+    let destination;
+    let ownership;
+    if (parsed.external) {
+        const workspace = store.getConfig().defaultWorkspace;
+        if (workspace === undefined)
+            throw usageError("No default workspace is configured; run yui setup.");
+        const workspaceRoot = resolve(workspace);
+        destination = resolve(workspaceRoot, name);
+        if (dirname(destination) !== workspaceRoot) {
+            throw usageError("Project clone destination must be directly inside the configured workspace.");
+        }
+        assertOutsideManagedWorktrees(destination, workspace);
+        ownership = "external";
+    }
+    else {
+        destination = managedProjectPath(store.rootDirectory(), projectId);
+        ownership = "managed";
+    }
+    const candidate = createProject(projectId, name, destination, { stable: stableRef, development: developmentRef }, now, { aliases: parsed.aliases, remoteUrl: parsed.remote, ownership });
     assertProjectAvailable(store, candidate);
     let cloned = false;
     try {
@@ -157,7 +180,16 @@ async function cloneProject(args, store, options) {
         if (developmentRef !== stableRef) {
             await git.ensureLocalBranch(destination, developmentRef);
         }
-        const project = createProject(projectId, name, head.root, { stable: stableRef, development: developmentRef }, now, { aliases: parsed.aliases, remoteUrl: parsed.remote });
+        // Verify both configured branches against the SHAs the remote advertises
+        // now. A network race or a ref that moved during the clone fails closed
+        // before any binding is persisted.
+        await assertRemoteBranchesVerified(git, destination, parsed.remote, [
+            { ref: stableRef, localCommit: head.baseCommit },
+            ...(developmentRef === stableRef
+                ? []
+                : [{ ref: developmentRef, localCommit: (await git.inspect(destination, developmentRef)).baseCommit }])
+        ]);
+        const project = createProject(projectId, name, head.root, { stable: stableRef, development: developmentRef }, now, { aliases: parsed.aliases, remoteUrl: parsed.remote, ownership });
         assertProjectAvailable(store, project);
         const created = store.createProjectIfAbsent(project);
         if (created === null)
@@ -171,6 +203,135 @@ async function cloneProject(args, store, options) {
         throw error;
     }
 }
+/**
+ * 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.
+ */
+async function migrateProject(args, store, options) {
+    const usage = "Project migrate usage: yui project migrate <project> [--preflight].";
+    const parsed = parseMigrateArguments(args, usage);
+    const project = requireProject(store, parsed.project);
+    if (project.ownership === "managed") {
+        throw usageError(`Project is already Home-managed: ${project.id}.`);
+    }
+    if (project.remoteUrl === undefined) {
+        throw usageError(`Project migrate requires a remote URL: ${project.id}.`);
+    }
+    const git = options.git ?? new NodeGitWorkspace();
+    const destination = managedProjectPath(store.rootDirectory(), project.id);
+    // Preflight verifies the remote into a throwaway clone: it changes neither
+    // the catalog nor the persistent projects directory.
+    const verifyRoot = parsed.preflight
+        ? join(store.rootDirectory(), "projects", `.preflight-${project.id}`)
+        : destination;
+    if (!parsed.preflight) {
+        // A crashed earlier attempt can leave an unreferenced managed clone
+        // behind. It is safe to remove only because no catalog record points at
+        // it; a registered path fails closed instead.
+        await removeUnreferencedClone(store, destination, project.id);
+    }
+    else if (existsSync(verifyRoot)) {
+        // A crashed preflight can only leave its own throwaway clone behind.
+        await rm(verifyRoot, { recursive: true, force: true });
+    }
+    let prepared = false;
+    try {
+        const head = await git.clone({
+            remoteUrl: project.remoteUrl,
+            destination: verifyRoot,
+            ...(project.stableBranch === "HEAD" ? {} : { branch: project.stableBranch })
+        });
+        prepared = true;
+        const stable = project.stableBranch === "HEAD"
+            ? head
+            : await git.inspect(verifyRoot, project.stableBranch);
+        if (head.baseCommit !== stable.baseCommit) {
+            throw new Error(`Project checkout is not on its stable ref: ${project.stableBranch}.`);
+        }
+        if (project.developmentBranch !== project.stableBranch) {
+            await git.ensureLocalBranch(verifyRoot, project.developmentBranch);
+        }
+        await assertRemoteBranchesVerified(git, verifyRoot, project.remoteUrl, [
+            { ref: project.stableBranch, localCommit: head.baseCommit },
+            ...(project.developmentBranch === project.stableBranch
+                ? []
+                : [{
+                        ref: project.developmentBranch,
+                        localCommit: (await git.inspect(verifyRoot, project.developmentBranch)).baseCommit
+                    }])
+        ]);
+        if (parsed.preflight) {
+            return { project, path: destination, preflight: true };
+        }
+        const switched = store.transaction((tx) => {
+            const latest = requireProject(tx, project.id);
+            if (latest.ownership !== "external"
+                || latest.path !== project.path
+                || latest.remoteUrl !== project.remoteUrl) {
+                throw new Error(`Project changed while migrating: ${project.id}.`);
+            }
+            // The switch only changes ownership and path; every other field is
+            // frozen, and the catalog validator re-checks the whole record.
+            const next = validateProject({
+                ...latest,
+                path: destination,
+                ownership: "managed",
+                updatedAt: (options.now ?? (() => new Date()))().toISOString()
+            });
+            assertProjectAvailable(tx, next, latest.id);
+            tx.saveProject(next);
+            return next;
+        });
+        return { project: switched, path: switched.path, preflight: false };
+    }
+    catch (error) {
+        if (prepared && !parsed.preflight
+            && !store.listProjects().some(({ path }) => path === destination)) {
+            await rm(destination, { recursive: true, force: true });
+        }
+        throw error;
+    }
+    finally {
+        if (parsed.preflight) {
+            await rm(verifyRoot, { recursive: true, force: true });
+        }
+    }
+}
+/**
+ * Remove a managed clone left behind by a crashed migration attempt. Such a
+ * directory is unreferenced garbage; a path any catalog record points at is
+ * never deleted.
+ */
+async function removeUnreferencedClone(store, destination, migratingProjectId) {
+    if (!existsSync(destination))
+        return;
+    const registered = store.listProjects().find(({ path }) => path === destination);
+    if (registered !== undefined && registered.id !== migratingProjectId) {
+        throw new Error(`Managed Project path is already registered: ${destination}.`);
+    }
+    await rm(destination, { recursive: true, force: true });
+}
+/**
+ * Verify that the local SHAs of the configured branches exactly match the
+ * commits the remote advertises right now. Any mismatch fails closed.
+ */
+async function assertRemoteBranchesVerified(git, repositoryPath, remoteUrl, branches) {
+    for (const branch of branches) {
+        const resolved = await git.resolveRemoteBaseline({
+            repositoryPath,
+            remoteUrl,
+            developmentRef: branch.ref
+        });
+        if (resolved.commit.toLowerCase() !== branch.localCommit.toLowerCase()) {
+            throw new Error(`Project remote branch ${resolved.branch} moved while it was fetched: `
+                + `advertised ${resolved.commit}, local ${branch.localCommit}.`);
+        }
+    }
+}
 async function addProject(args, store, options) {
     const usage = "Project add usage: yui project add <name> <path> [--alias <name> ...] [--remote <url>] [--stable <ref>] [--development <ref>].";
     const parsed = parseAddArguments(args, usage);
@@ -246,6 +407,7 @@ function renderAddedProject(created) {
     return [
         `Added project ${created.id}`,
         `Name: ${created.name}`,
+        `Ownership: ${created.ownership}`,
         `Path: ${created.path}`,
         `Stable: ${created.stableBranch}`,
         `Development: ${created.developmentBranch}`
@@ -286,11 +448,17 @@ function listProjects(args, store) {
     return `${renderTable("Projects", [
         { header: "Project", minWidth: 8, maxWidth: 24 },
         { header: "Name", minWidth: 4, maxWidth: 28 },
+        { header: "Ownership", minWidth: 9, maxWidth: 10 },
         { header: "Path", minWidth: 8, maxWidth: 64 },
         { header: "Stable", minWidth: 6, maxWidth: 24 },
         { header: "Development", minWidth: 11, maxWidth: 24 }
     ], projects.map((project) => [
-        project.id, project.name, project.path, project.stableBranch, project.developmentBranch
+        project.id,
+        project.name,
+        project.ownership,
+        project.path,
+        project.stableBranch,
+        project.developmentBranch
     ]), defaultTableWidth())}\n`;
 }
 function showProject(args, store) {
@@ -300,6 +468,7 @@ function showProject(args, store) {
     return [
         `Project: ${project.id}`,
         `Name: ${project.name}`,
+        `Ownership: ${project.ownership}`,
         `Aliases: ${project.aliases.length === 0 ? "-" : project.aliases.join(", ")}`,
         `Path: ${project.path}`,
         ...(project.remoteUrl === undefined ? [] : [`Remote: ${project.remoteUrl}`]),
@@ -579,8 +748,13 @@ function parseCloneArguments(args, usage) {
     const aliases = [];
     let stable;
     let development;
+    let external = false;
     for (let index = 0; index < args.length; index += 1) {
         const value = args[index];
+        if (value === "--external") {
+            external = true;
+            continue;
+        }
         if (["--alias", "--stable", "--development"].includes(value)) {
             const next = args[index + 1];
             if (next === undefined || next.startsWith("--")) {
@@ -613,9 +787,26 @@ function parseCloneArguments(args, usage) {
         remote: requireText(positionals[1], "Project remote"),
         aliases,
         ...(stable === undefined ? {} : { stable }),
-        ...(development === undefined ? {} : { development })
+        ...(development === undefined ? {} : { development }),
+        external
     };
 }
+function parseMigrateArguments(args, usage) {
+    const positionals = [];
+    let preflight = false;
+    for (const value of args) {
+        if (value === "--preflight") {
+            preflight = true;
+            continue;
+        }
+        if (value.startsWith("--"))
+            throw usageError(`Unknown option: ${value}. ${usage}`);
+        positionals.push(value);
+    }
+    if (positionals.length !== 1)
+        throw usageError(usage);
+    return { project: requireText(positionals[0], "Project reference"), preflight };
+}
 function parseSingleOption(args, option, usage) {
     const positionals = [];
     let found;

package/dist/commands/taskWorkspaceCommands.js

@@ -0,0 +1,135 @@
+import { usageError } from "../errors/cliError.js";
+import { createMilestone } from "../milestone/milestone.js";
+import { defaultTableWidth, renderTable } from "../output/table.js";
+import { runTaskCommand } from "./taskCommands.js";
+/**
+ * Task workspace lifecycle commands that sit outside the sync task command
+ * surface because they drive Git: controlled rebuild of a legacy Task
+ * workspace, legacy ref history inspection/archival, and the
+ * replacement-creating path for terminal Tasks.
+ */
+export async function runTaskWorkspaceCommand(args, store, preparer, options = {}) {
+    const [command, ...rest] = args;
+    if (command === "rebuild")
+        return rebuildTaskCommand(rest, preparer);
+    if (command === "history")
+        return historyCommand(rest, preparer);
+    if (command === "replace")
+        return replaceTaskCommand(rest, store, options);
+    throw usageError("Unknown task workspace command. Available: yui task rebuild <task>, "
+        + "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 taskId = args[0];
+    if (taskId === undefined || args.length !== 1)
+        throw usageError(usage);
+    const result = await preparer.rebuildTaskWorkspace(taskId);
+    const archived = result.archived.length === 0
+        ? "no legacy refs"
+        : `${result.archived.length} legacy ref(s) archived`;
+    const resumed = result.resumed ? " (resumed pending cleanup)" : "";
+    return {
+        output: `Rebuilt Task workspace ${result.task.id} at ${result.task.cwd ?? "its configured workspace"}: `
+            + `${archived}${resumed}.`,
+        data: {
+            taskId: result.task.id,
+            archived: result.archived,
+            resumed: result.resumed
+        }
+    };
+}
+async function historyCommand(args, preparer) {
+    const usage = "Task history usage: yui task history list|archive [task].";
+    const action = args[0];
+    if (action !== "list" && action !== "archive")
+        throw usageError(usage);
+    const taskId = args[1];
+    if (args.length > 2)
+        throw usageError(usage);
+    if (action === "list") {
+        const refs = await preparer.listLegacyTaskRefs(taskId);
+        if (refs.length === 0) {
+            return { output: "No legacy Task refs.", data: { refs: [] } };
+        }
+        return {
+            output: renderTable("Legacy Task refs", [
+                { header: "Project", minWidth: 8, maxWidth: 24 },
+                { header: "Task", minWidth: 8, maxWidth: 16 },
+                { header: "Legacy ref", minWidth: 16, maxWidth: 64 }
+            ], refs.map((entry) => [entry.projectId, entry.taskId, entry.ref]), defaultTableWidth()),
+            data: { refs }
+        };
+    }
+    const result = await preparer.archiveLegacyTaskRefs(taskId);
+    const lines = [];
+    if (result.archived.length > 0) {
+        lines.push(`Archived ${result.archived.length} legacy ref(s):`);
+        lines.push(...result.archived.map((entry) => `  ${entry}`));
+    }
+    if (result.refused.length > 0) {
+        lines.push(`Refused ${result.refused.length} live ref(s) owned by an open Task:`);
+        lines.push(...result.refused.map((entry) => `  ${entry}`));
+    }
+    if (lines.length === 0)
+        lines.push("No legacy Task refs to archive.");
+    return {
+        output: lines.join("\n"),
+        data: { archived: result.archived, refused: result.refused }
+    };
+}
+/**
+ * A terminal (retired/completed/archived) Task is never rewritten in place.
+ * This creates a fresh draft Task bound to the same Projects at the same
+ * bases and records the relationship as a milestone on the replacement, so
+ * the original Task, its refs, and its evidence stay untouched.
+ */
+function replaceTaskCommand(args, store, options) {
+    const usage = "Task replace usage: yui task replace <task> [--title <text>].";
+    const oldId = args[0];
+    if (oldId === undefined)
+        throw usageError(usage);
+    const old = store.getTask(oldId);
+    if (old === null)
+        throw usageError(`Task not found: ${oldId}.`);
+    if (old.status === "draft" || old.status === "active") {
+        throw usageError(`Task is open and can be rebuilt instead of replaced: ${old.id}.`);
+    }
+    let title = `Replaces ${old.id}: ${old.title}`;
+    for (let index = 1; index < args.length; index += 1) {
+        if (args[index] === "--title") {
+            const value = args[index + 1];
+            if (value === undefined || value.startsWith("--"))
+                throw usageError(usage);
+            title = value;
+            index += 1;
+            continue;
+        }
+        throw usageError(usage);
+    }
+    const createArgs = ["create", title];
+    for (const binding of old.projectBindings) {
+        createArgs.push("--project", binding.projectId);
+        createArgs.push("--base", `${binding.projectId}=${binding.baseRef}`);
+    }
+    if (old.requireIntegration)
+        createArgs.push("--require-integration");
+    const created = runTaskCommand(createArgs, store);
+    if (created.kind !== "output") {
+        throw new Error(`Task replacement could not be created for ${old.id}.`);
+    }
+    const data = created.data;
+    const replacement = data?.task;
+    if (replacement === undefined) {
+        throw new Error(`Task replacement result did not name the new Task for ${old.id}.`);
+    }
+    const now = options.now?.() ?? new Date();
+    const milestone = createMilestone(store.nextMilestoneId(replacement.id), replacement.id, `Replaces ${old.id}`, `Replacement Task for ${old.id} (${old.status}); the original Task, its refs, `
+        + "and its evidence are preserved and were not rewritten.", now);
+    store.saveMilestone(replacement.id, milestone);
+    return {
+        output: `${created.output}\nRecorded replacement of ${old.id} on ${replacement.id} `
+            + `(milestone ${milestone.id}).`,
+        data: { task: replacement, replaces: old.id, milestone: milestone.id }
+    };
+}

package/dist/integration/gitIntegrationService.js

@@ -7,6 +7,7 @@ import { selectEnvironment } from "../agent/launchEnvironment.js";
 import { controllerSocketPath } from "../core/controllerEndpoint.js";
 import { NodeGitWorkspace, RemoteBaselineConflictError } from "../repository/gitWorkspace.js";
 import { resolveWorktreeRoot } from "../repository/taskWorkspacePreparer.js";
+import { taskWorkspaceRefSegment } from "../repository/taskWorkspaceIdentity.js";
 import { FileTaskRuntimeIsolation } from "../runtime/taskRuntimeIsolation.js";
 import { yuiTmuxServerName } from "../tmux/tmuxManager.js";
 import { requireLeaderDecision, updateIntegrationAttempt } from "./integrationAttempt.js";
@@ -78,7 +79,7 @@ export class GitIntegrationService {
             prepared = await this.git.ensureIntegrationWorktree({
                 repositoryPath: project.path,
                 container: join(this.worktreeRoot, project.name),
-                taskId: task.id,
+                taskSegment: taskWorkspaceRefSegment(task),
                 integrationId: initial.id,
                 baseRef: initial.expectedHead
             });
@@ -212,7 +213,7 @@ export class GitIntegrationService {
         const result = await this.git.removeIntegrationWorktree({
             repositoryPath: project.path,
             container: join(this.worktreeRoot, project.name),
-            taskId: task.id,
+            taskSegment: taskWorkspaceRefSegment(task),
             integrationId: integration.id,
             discardChanges: integration.status === "failed"
         });

package/dist/repository/gitWorkspace.js

@@ -171,6 +171,13 @@ export class NodeGitWorkspace {
             "-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 {
@@ -300,6 +307,52 @@ export class NodeGitWorkspace {
             baseCommit: baseCommit.toLowerCase()
         };
     }
+    async refExists(repositoryPath, ref) {
+        const root = (await this.inspect(repositoryPath)).root;
+        return gitSucceeds([
+            "-C", root, "rev-parse", "--verify", "--quiet", "--end-of-options",
+            `${safeRef(ref)}^{commit}`
+        ]);
+    }
+    async listRefs(repositoryPath, pattern) {
+        const root = (await this.inspect(repositoryPath)).root;
+        const output = await git([
+            "-C", root, "for-each-ref", "--format=%(refname)", "--", safeRef(pattern)
+        ]);
+        return output.length === 0 ? [] : output.split("\n").map((line) => line.trim())
+            .filter((line) => line.length > 0);
+    }
+    async archiveRef(input) {
+        const root = (await this.inspect(input.repositoryPath)).root;
+        const source = safeRef(input.sourceRef);
+        const target = safeRef(input.archiveRef);
+        const commit = (await gitLine([
+            "-C", root, "rev-parse", "--verify", "--end-of-options", `${source}^{commit}`
+        ])).toLowerCase();
+        if (await this.refExists(root, target)) {
+            // Resumable: a previous attempt already created the archive ref. Only
+            // the same commit may be resumed; a different archive fails closed.
+            const archived = (await gitLine([
+                "-C", root, "rev-parse", "--verify", "--end-of-options", `${target}^{commit}`
+            ])).toLowerCase();
+            if (archived !== commit) {
+                throw new Error(`Archive ref already exists at a different commit: ${target}.`);
+            }
+        }
+        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)
+            ]);
+        }
+        // Delete the source only if it still exists and still points at the
+        // archived commit; an already-deleted source makes the archive a no-op.
+        if (await this.refExists(root, source)) {
+            await git([
+                "-C", root, "update-ref", "-d", "--no-deref", source, commit
+            ]);
+        }
+    }
     async isAncestor(repositoryPath, ancestor, descendant) {
         const root = (await this.inspect(repositoryPath)).root;
         return gitSucceeds([
@@ -387,7 +440,7 @@ export class NodeGitWorkspace {
         return this.#ensureManagedWorktree({
             repositoryPath: input.repositoryPath,
             container: input.container,
-            identity: worktreeIdentity(input.taskId, input.roleName),
+            identity: worktreeIdentity(input.taskSegment, input.roleName),
             baseRef: input.baseRef
         });
     }
@@ -395,7 +448,7 @@ export class NodeGitWorkspace {
         return this.#ensureManagedWorktree({
             repositoryPath: input.repositoryPath,
             container: input.container,
-            identity: integrationWorktreeIdentity(input.taskId, input.integrationId),
+            identity: integrationWorktreeIdentity(input.taskSegment, input.integrationId),
             baseRef: input.baseRef
         });
     }
@@ -441,7 +494,7 @@ export class NodeGitWorkspace {
         if (state === "dirty")
             return state;
         const container = resolve(input.container);
-        const identity = worktreeIdentity(input.taskId, input.roleName);
+        const identity = worktreeIdentity(input.taskSegment, input.roleName);
         const path = managedPath(container, identity.directory);
         const project = await this.inspect(input.repositoryPath);
         if (state === "missing") {
@@ -459,7 +512,7 @@ export class NodeGitWorkspace {
     }
     async inspectWorktree(input) {
         const container = resolve(input.container);
-        const path = managedPath(container, worktreeIdentity(input.taskId, input.roleName).directory);
+        const path = managedPath(container, worktreeIdentity(input.taskSegment, input.roleName).directory);
         const kind = await pathKind(path);
         if (kind === undefined)
             return "missing";
@@ -475,7 +528,7 @@ export class NodeGitWorkspace {
         return this.#removeManagedWorktree({
             repositoryPath: input.repositoryPath,
             container: input.container,
-            identity: integrationWorktreeIdentity(input.taskId, input.integrationId),
+            identity: integrationWorktreeIdentity(input.taskSegment, input.integrationId),
             discardChanges: input.discardChanges
         });
     }