@tacuchi/agent-workflow-cli 25.7.0 → 25.9.0

package/dist/application/worktree-service.js

@@ -1,13 +1,18 @@
 import { dirname, join } from "node:path";
 import { parseUnitPath, unitBranch, unitPath, workspaceKey, } from "../domain/isolation-unit.js";
-import { resolveSourceBranches } from "./branch-resolver.js";
+import { isWorkingBranch, resolveSourceBranches } from "./branch-resolver.js";
+import { documentOfSession, resolveDocBranch } from "./doc-branch-ledger.js";
 import { locateRun, readRun } from "./flow/run-state-service.js";
 import { withCwdLock } from "./lock-service.js";
 import { runMultiroot } from "./multiroot-service.js";
 import { normalizePath } from "./multiroot/paths.js";
-import { readWorkspaceBlock } from "./parsers/project-block.js";
+import { readWorkspaceBlock, requireSourcePath, } from "./parsers/project-block.js";
 import { recordIntegration, recordUnitTaken } from "./session-custody-recorder.js";
-import { listSessionFolders, resolveSessionTarget, sessionFolderMatches, } from "./session-resolver.js";
+import { readCustody } from "./session-custody-service.js";
+import { listSessionFolders, readSessionState, resolveSessionTarget, sessionFolderMatches, } from "./session-resolver.js";
+import { linkUnitDependencies, removeUnitSafely, } from "./unit-dependencies.js";
+import { hubUnitPaths } from "./unit-membership.js";
+import { finishResidue } from "./unit-residue.js";
 import { ensureWorklineMaterialized } from "./workspace-materialization-service.js";
 /**
  * How long an integration waits for the workspace lock before giving up.
@@ -16,6 +21,67 @@ import { ensureWorklineMaterialized } from "./workspace-materialization-service.
  * a merge: the wait is bounded by another merge finishing, not by a file write.
  */
 const INTEGRATE_LOCK_WAIT_MS = 10_000;
+/** Read-only close classification: never treats an unreadable tree as empty. */
+export async function classifyListedUnits(deps, units) {
+    const block = await readWorkspaceBlock(deps.fs, deps.paths.workspaceDir(), deps.paths.blockMarkers());
+    const declared = new Set();
+    for (const source of block?.fuentes ?? []) {
+        const roles = resolveSourceBranches(source, block);
+        for (const name of [
+            roles.prod,
+            roles.work,
+            block?.qa_branches[source.alias] ?? block?.default_branches.qa,
+        ])
+            if (name)
+                declared.add(`refs/heads/${name}`);
+    }
+    return Promise.all(units.map(async (unit) => {
+        const classify = (classification, reason, preservedIn) => ({
+            ...unit,
+            classification,
+            classification_reason: reason,
+            ...(preservedIn ? { preserved_in: preservedIn } : {}),
+        });
+        try {
+            if (unit.dirty === null || unit.head === null)
+                return classify("retained", "no se pudo leer HEAD o limpieza de la unidad");
+            if ((await deps.git.operationState(unit.path)) !== "clean")
+                return classify("retained", "operación git a medio resolver");
+            if (unit.dirty)
+                return classify("retained", "cambios sin commitear");
+            const custody = await readCustody(deps.fs, join(deps.paths.cwdSessionsDir(), unit.session));
+            if (custody.status === "unreadable")
+                return classify("retained", `custodia ilegible: ${custody.reason}`);
+            const sealed = custody.status === "present"
+                ? custody.custody.sources.find((entry) => entry.alias === unit.alias)?.base_branch
+                : undefined;
+            const source = block?.fuentes.find((entry) => entry.alias === unit.alias);
+            const work = source ? resolveSourceBranches(source, block).work : null;
+            const base = sealed ?? work;
+            if (base === null || base === undefined)
+                return classify("pending", "sin base sellada ni rama de trabajo declarada");
+            const baseline = sealed !== undefined && custody.status === "present"
+                ? custody.custody.sources.find((entry) => entry.alias === unit.alias)?.baseline_head
+                : null;
+            if (baseline !== null && baseline !== undefined && unit.head === baseline)
+                return classify("empty", `sin commits sobre ${base}`);
+            const refs = await deps.git.refsContaining(unit.source_path, unit.head);
+            const baseRef = `refs/heads/${base}`;
+            const preserved = refs.includes(baseRef) && declared.has(baseRef)
+                ? baseRef
+                : refs.find((ref) => declared.has(ref) || ref.startsWith("refs/remotes/"));
+            if (preserved)
+                return {
+                    ...classify("preserved", `commits contenidos en ${preserved}`, preserved),
+                    integrated: preserved === baseRef,
+                };
+            return classify("pending", "commits no contenidos en una rama declarada ni remota");
+        }
+        catch (err) {
+            return classify("retained", `no se pudo verificar la unidad: ${err.message}`);
+        }
+    }));
+}
 export async function runWorktree(deps, input) {
     if (input.action === "list")
         return listUnits(deps, input);
@@ -49,6 +115,7 @@ export async function runWorktree(deps, input) {
 async function integrateSession(deps, input) {
     const resolution = await resolveSessionTarget(deps.fs, deps.paths, {
         intent: "write",
+        allowClosed: input.sessionCode !== undefined,
         ...(input.sessionCode !== undefined ? { code: input.sessionCode } : {}),
         ...(input.contextId !== undefined ? { contextId: input.contextId } : {}),
     });
@@ -66,8 +133,18 @@ async function integrateSession(deps, input) {
     // branch — so this cannot take the side of a merge nobody resolved.
     const swept = await reclaimUnits(deps, { action: "reclaim", sessionCode: session });
     const residue = "error" in swept
-        ? { reclaimed: [], retained: [], next: null }
+        ? {
+            reclaimed: [],
+            retained: [],
+            unreadable: [
+                { alias: "workspace", error: swept.message },
+            ],
+            next: null,
+        }
         : swept;
+    const unreadable = [
+        ...new Map([...listed.unreadable, ...residue.unreadable].map((item) => [item.alias, item])).values(),
+    ];
     // An alias whose unit was collected is no longer holding one, so it leaves
     // `pending`. That is not hiding its refusal — the refusal stays in `results` —
     // it is that a unit with nothing the working branch lacks had no merge pending
@@ -84,7 +161,12 @@ async function integrateSession(deps, input) {
         pending: holding,
         reclaimed: residue.reclaimed,
         retained: residue.retained,
-        next: (first !== undefined ? (nextOf.get(first) ?? null) : null) ?? residue.next,
+        ...(unreadable.length > 0 ? { unreadable } : {}),
+        next: (first !== undefined ? (nextOf.get(first) ?? null) : null) ??
+            residue.next ??
+            (unreadable[0]?.code === "SOURCE_PATH_MISSING"
+                ? `aw add-source ${unreadable[0].alias}:<ruta>`
+                : null),
     };
 }
 /**
@@ -137,6 +219,8 @@ async function planOf(deps, session) {
  */
 async function integrateUnit(deps, target) {
     const { source, path, branch, base, identity } = target;
+    if (base === null)
+        return undeclaredWorkBranch(source.alias);
     if (!(await deps.git.isGitRepo(source.path))) {
         return {
             error: "not_a_repo",
@@ -151,9 +235,13 @@ async function integrateUnit(deps, target) {
             hint: `creála con 'aw worktree ensure --source ${source.alias} --code ${identity.session}'`,
         };
     }
-    // Both preconditions are refusals BEFORE anything moves: a merge started over
-    // uncommitted work is the one state where "report the conflict" is no longer
-    // enough, because the losing side was never recorded anywhere.
+    if ((await deps.git.operationState(path)) !== "clean") {
+        return {
+            error: "unit_operation_in_progress",
+            message: `la unidad ${path} tiene una operación git pendiente`,
+            hint: `resolvé el merge con aw fix-git --path ${path} antes de integrar otra vez`,
+        };
+    }
     if (await deps.git.isDirty(path)) {
         return {
             error: "unit_not_committed",
@@ -161,47 +249,18 @@ async function integrateUnit(deps, target) {
             hint: "commiteá el trabajo del flujo en su unidad antes de integrarlo",
         };
     }
-    if (await deps.git.isDirty(source.path)) {
+    const current = await deps.git.currentBranch(source.path);
+    if (current === base && (await deps.git.isDirty(source.path))) {
         return {
             error: "checkout_dirty",
             message: `el checkout principal de ${source.alias} tiene cambios sin commitear`,
             hint: "commiteá o guardá esos cambios: la integración no los va a mezclar con los del flujo",
         };
     }
-    // Never switch the user's branch to make the command succeed. The declared
-    // working branch is where the checkout is SUPPOSED to be — the git-safe
-    // invariant says so — and a checkout that is somewhere else is a state the
-    // person has to see, not one to be quietly corrected under a merge.
-    const current = await deps.git.currentBranch(source.path);
-    if (current !== base) {
-        return {
-            error: "checkout_off_branch",
-            message: `el checkout principal de ${source.alias} está en '${current}' y la integración va a '${base}'`,
-            hint: `posicioná el checkout en '${base}' y volvé a integrar; la integración nunca cambia de rama por su cuenta`,
-        };
-    }
-    // The merge goes through GitPort, so it would otherwise bypass the command
-    // filesystem guard. All refusal/precondition reads are complete above; from
-    // here on this operation may change a source checkout.
     await ensureWorklineMaterialized(deps.fs, deps.paths);
-    // The merge itself is the serialized part, and only it. Two runs integrating
-    // into the same checkout would fight over one index and one MERGE_HEAD, and the
-    // loser would find a repository mid-merge it never started. Waiting rather than
-    // failing fast for the same reason a correlative claim waits: by the time this
-    // lock is taken there is committed work with nowhere else to go, so losing the
-    // race would lose real work instead of a retry.
-    //
-    // The pre-merge HEAD is read INSIDE the lock, next to the merge it describes.
-    // Reading it outside would leave a window in which another integration lands
-    // between the read and the merge, and the receipt would then attribute this
-    // integration over a value the branch no longer had.
-    const merged = await withCwdLock(deps.fs, deps.paths, async () => {
-        const before = await deps.git.head(source.path).catch(() => null);
-        const merge = await deps.git.merge(source.path, branch);
-        if (merge.ok)
-            return { ok: true, before };
-        return { ok: false, conflicted: merge.conflicted };
-    }, { waitMs: INTEGRATE_LOCK_WAIT_MS });
+    const merged = await withCwdLock(deps.fs, deps.paths, () => integrateLocked(deps, { ...target, base }), {
+        waitMs: INTEGRATE_LOCK_WAIT_MS,
+    });
     if ("error" in merged) {
         return {
             error: "integration_locked",
@@ -209,7 +268,9 @@ async function integrateUnit(deps, target) {
             hint: "esperá a que la otra integración termine y volvé a integrar; el merge no se empieza a medias",
         };
     }
-    if (!merged.ok) {
+    if (merged.state === "refused")
+        return merged.refusal;
+    if (merged.state === "conflict") {
         return {
             alias: source.alias,
             source_path: source.path,
@@ -221,15 +282,29 @@ async function integrateUnit(deps, target) {
             // The unit SURVIVES a conflict: its commits are the only copy of one side
             // of the merge, and releasing it here would delete them to tidy up.
             released: false,
-            next: `aw fix-git --path ${source.path}`,
+            next: `aw fix-git --path ${merged.path}`,
         };
     }
-    await recordIntegration(deps, identity.session, {
-        alias: source.alias,
-        sourcePath: source.path,
-        into: base,
-        before: merged.before,
-    });
+    if (merged.before !== null && merged.after !== null && merged.before !== merged.after) {
+        const tip = await deps.git.head(path);
+        if (tip === null)
+            return {
+                error: "custody_unreadable",
+                message: `no se pudo leer la punta de la unidad ${path} antes de liberarla`,
+            };
+        const recorded = await recordIntegration(deps, identity.session, {
+            alias: source.alias,
+            into: base,
+            before: merged.before,
+            after: merged.after,
+            unitTip: tip,
+        });
+        if (recorded.status === "unreadable")
+            return {
+                error: "custody_unreadable",
+                message: `la integración de ${source.alias} llegó a ${base}, pero no se pudo registrar la punta ${tip} en la custodia: ${recorded.reason}; la unidad conserva su rama`,
+            };
+    }
     const release = await releaseUnit(deps, target);
     return {
         alias: source.alias,
@@ -240,9 +315,100 @@ async function integrateUnit(deps, target) {
         integrated: true,
         conflicted: [],
         released: "released" in release ? release.released : false,
-        next: null,
+        ...("branch_kept" in release && release.branch_kept
+            ? { branch_kept: release.branch_kept }
+            : {}),
+        ...("visibility_error" in release && release.visibility_error
+            ? { visibility_error: release.visibility_error }
+            : {}),
+        ...("visibility_error" in release && release.visibility_error
+            ? { visibility_error: release.visibility_error }
+            : {}),
+        next: "released" in release && release.released
+            ? null
+            : `aw worktree release --source ${source.alias} --code ${identity.session}`,
     };
 }
+/** All ref reads, occupancy checks and the move happen under the integration lock. */
+async function integrateLocked(deps, target) {
+    const { source, path, branch, base, roles } = target;
+    const current = await deps.git.currentBranch(source.path);
+    if (current === base) {
+        const before = await deps.git.head(source.path);
+        const merge = await deps.git.merge(source.path, branch);
+        return merge.ok
+            ? { state: "done", before, after: await deps.git.head(source.path) }
+            : { state: "conflict", conflicted: merge.conflicted, path: source.path };
+    }
+    const ref = `refs/heads/${base}`;
+    const before = await deps.git.refValue(source.path, ref);
+    if (before === null)
+        return {
+            state: "refused",
+            refusal: {
+                error: "target_missing",
+                message: `la rama destino '${base}' no existe en local`,
+                hint: `restaurá ${base} antes de integrar; la unidad queda intacta`,
+            },
+        };
+    const trees = await deps.git.worktreeList(source.path);
+    const occupied = trees.find((tree) => tree.branch === base && !samePath(tree.path, source.path));
+    if (occupied)
+        return {
+            state: "refused",
+            refusal: {
+                error: "target_occupied",
+                message: `${base} está puesta en otro árbol: ${occupied.path}`,
+                hint: `liberá ese árbol antes de mover la referencia ${ref}`,
+            },
+        };
+    let head = await deps.git.head(path);
+    if (head === null)
+        return {
+            state: "refused",
+            refusal: {
+                error: "unit_not_committed",
+                message: `la unidad ${path} no tiene HEAD`,
+            },
+        };
+    if (await deps.git.isAncestor(source.path, head, before)) {
+        return { state: "done", before, after: before };
+    }
+    if (!(await deps.git.isAncestor(source.path, before, head))) {
+        if (!isWorkingBranch(base, roles))
+            return {
+                state: "refused",
+                refusal: {
+                    error: "checkout_off_branch",
+                    message: `la rama de rol ${base} no admite integración divergente fuera de su checkout`,
+                    hint: `posicioná el checkout en '${base}' y volvé a integrar`,
+                },
+            };
+        const merge = await deps.git.merge(path, base);
+        if (!merge.ok)
+            return { state: "conflict", conflicted: merge.conflicted, path };
+        head = await deps.git.head(path);
+        if (head === null)
+            return {
+                state: "refused",
+                refusal: {
+                    error: "unit_not_committed",
+                    message: `no se pudo leer HEAD de la unidad ${path} después del merge`,
+                },
+            };
+    }
+    const moved = await deps.git.updateRefCas(source.path, ref, head, before);
+    if (!moved.ok)
+        return {
+            state: "refused",
+            refusal: {
+                error: "integration_raced",
+                message: `la referencia ${ref} avanzó durante la integración: ${moved.why}`,
+                hint: `la unidad queda intacta: volvé a correr aw worktree integrate --source ${source.alias} --code ${target.identity.session}`,
+            },
+        };
+    return { state: "done", before, after: head };
+}
 async function resolveTarget(deps, input) {
     const block = await readWorkspaceBlock(deps.fs, deps.paths.workspaceDir(), deps.paths.blockMarkers());
     const sources = block?.fuentes ?? [];
@@ -250,7 +416,7 @@ async function resolveTarget(deps, input) {
         return {
             error: "no_sources_declared",
             message: "el bloque WORKSPACE no declara ninguna fuente",
-            hint: "declará la fuente en la tabla Fuentes antes de pedir una unidad",
+            hint: "declará la fuente con aw add-source <alias>:<ruta>:<rama> antes de pedir una unidad",
         };
     }
     if (input.alias === undefined) {
@@ -268,8 +434,16 @@ async function resolveTarget(deps, input) {
             hint: `fuentes declaradas: ${sources.map((s) => s.alias).join(", ")}`,
         };
     }
+    let sourcePath;
+    try {
+        sourcePath = await requireSourcePath(deps.fs, source);
+    }
+    catch (err) {
+        return { error: "SOURCE_PATH_MISSING", message: err.message };
+    }
     const resolution = await resolveSessionTarget(deps.fs, deps.paths, {
         intent: "write",
+        allowClosed: input.action !== "ensure" && input.sessionCode !== undefined,
         ...(input.sessionCode !== undefined ? { code: input.sessionCode } : {}),
         ...(input.contextId !== undefined ? { contextId: input.contextId } : {}),
     });
@@ -281,12 +455,58 @@ async function resolveTarget(deps, input) {
         alias: source.alias,
         session,
     };
+    const roles = resolveSourceBranches(source, block);
+    const custody = await readCustody(deps.fs, join(deps.paths.cwdSessionsDir(), session));
+    if (custody.status === "unreadable")
+        return {
+            error: "custody_unreadable",
+            message: `la custodia de ${session} no se puede leer: ${custody.reason}`,
+        };
+    const sealed = custody.status === "present"
+        ? custody.custody.sources.find((s) => s.alias === source.alias)?.base_branch
+        : undefined;
+    const recorded = custody.status === "present"
+        ? custody.custody.sources.find((s) => s.alias === source.alias)
+        : undefined;
+    if (recorded?.unit_path) {
+        const oldIdentity = parseUnitPath(await canonicalUnitsRootForRead(deps), recorded.unit_path);
+        if (oldIdentity?.alias === source.alias && oldIdentity.session === session)
+            identity.workspaceKey = oldIdentity.workspaceKey;
+    }
+    let previous;
+    if (custody.status === "absent") {
+        const root = await canonicalUnitsRootForRead(deps);
+        const owns = await hubUnitPaths(deps.fs, deps.paths, root);
+        try {
+            previous = (await deps.git.worktreeList(sourcePath)).find((tree) => {
+                const found = parseUnitPath(root, tree.path);
+                return found?.session === session && found.alias === source.alias && owns(tree.path);
+            });
+        }
+        catch {
+            /* a broken git inventory is reported by ensure/list itself */
+        }
+        if (previous) {
+            const found = parseUnitPath(root, previous.path);
+            if (found)
+                identity.workspaceKey = found.workspaceKey;
+        }
+    }
+    const effective = sealed === undefined
+        ? await resolveDocBranch(deps.fs, deps.paths, source, block, await documentOfSession(deps.fs, deps.paths, session))
+        : null;
+    if (effective?.origin === "unreadable")
+        return {
+            error: "custody_unreadable",
+            message: effective.reason ?? "custodia ilegible",
+        };
     return {
-        source,
+        source: { ...source, path: sourcePath },
         identity,
-        path: unitPath(await canonicalUnitsRoot(deps), identity),
-        branch: unitBranch(session),
-        base: resolveSourceBranches(source, block).work,
+        path: recorded?.unit_path ?? previous?.path ?? unitPath(await canonicalUnitsRoot(deps), identity),
+        branch: recorded?.unit_branch ?? previous?.branch ?? unitBranch(session, deps.paths.workspaceDir()),
+        base: sealed ?? effective?.branch ?? null,
+        roles,
     };
 }
 /**
@@ -306,6 +526,13 @@ function sessionRefusal(resolution) {
         hint: resolution.action,
     };
 }
+function undeclaredWorkBranch(alias) {
+    return {
+        error: "working_branch_undeclared",
+        message: `rama de trabajo no declarada para ${alias}`,
+        hint: `usá 'aw set-working-branch ${alias} <rama>'`,
+    };
+}
 /**
  * The units root in the OS's own spelling.
  *
@@ -346,6 +573,7 @@ async function ensureUnit(deps, target) {
             message: `${source.alias} (${source.path}) no es un repositorio git`,
         };
     }
+    const longpathsEnabled = await enableLongPaths(deps, source.path);
     // Vanished directories keep holding their branch until git is told, so the
     // prune runs BEFORE the occupancy read — otherwise a unit whose folder the
     // user deleted by hand would look occupied forever.
@@ -353,17 +581,47 @@ async function ensureUnit(deps, target) {
     // root, so materialize explicitly before this first Git mutation rather than
     // relying on a workspace-path filesystem write to notice it.
     await ensureWorklineMaterialized(deps.fs, deps.paths);
+    const unitsRoot = await canonicalUnitsRootForRead(deps);
+    const owns = await hubUnitPaths(deps.fs, deps.paths, unitsRoot);
+    const staleErrors = [];
+    for (const tree of await deps.git.worktreeList(source.path)) {
+        if (!tree.prunable || !owns(tree.path) || (await deps.fs.lstat(tree.path)) !== null)
+            continue;
+        const result = await detach(deps, tree.path);
+        if (result.error)
+            staleErrors.push(`${tree.path}: ${result.error}`);
+    }
     await deps.git.worktreePrune(source.path);
     const existing = await deps.git.worktreeList(source.path);
     const mine = existing.find((w) => samePath(w.path, path));
     if (mine !== undefined) {
+        const custody = await readCustody(deps.fs, join(deps.paths.cwdSessionsDir(), target.identity.session));
+        const recorded = custody.status === "present"
+            ? custody.custody.sources.find((s) => s.alias === source.alias)
+            : undefined;
+        if (custody.status === "present" &&
+            (recorded?.unit_path !== path || recorded.unit_branch !== branch || mine.branch !== branch)) {
+            return {
+                error: "unit_foreign",
+                message: `La unidad ${path} no está registrada en la custodia de esta sesión.`,
+            };
+        }
         // Idempotent: the unit is already there, on its own branch. The baseline is
         // sealed here too — it is idempotent by alias, so the FIRST reading wins and a
         // second `ensure` can never overwrite it with a state the session produced.
-        const sealed = await sealBaseline(deps, target);
+        const sealed = base === null ? null : await sealBaseline(deps, { ...target, base });
         if (sealed !== null)
             return sealed;
-        return { ...unitOf(target, false), visibility: await attach(deps, path) };
+        const visible = await attach(deps, path);
+        const visibilityError = [...staleErrors, visible.error].filter(Boolean).join("; ");
+        return {
+            ...unitOf(target, false),
+            base,
+            visibility: visible.state,
+            ...(visibilityError ? { visibility_error: visibilityError } : {}),
+            longpaths_enabled: longpathsEnabled,
+            dependencies: await linkUnitDependencies(deps.fs, deps.git, source.path, path),
+        };
     }
     const occupant = existing.find((w) => w.branch === branch);
     if (occupant !== undefined) {
@@ -378,7 +636,29 @@ async function ensureUnit(deps, target) {
     // An existing branch is checked out, not recreated: a flow that released its
     // unit and asks again must land back on its own commits, not on a fresh branch
     // that silently drops them.
-    const from = (await deps.git.branchExists(source.path, branch)) ? null : base;
+    const exists = await deps.git.branchExists(source.path, branch);
+    const custody = await readCustody(deps.fs, join(deps.paths.cwdSessionsDir(), target.identity.session));
+    const recorded = custody.status === "present"
+        ? custody.custody.sources.find((s) => s.alias === source.alias)
+        : undefined;
+    if (exists &&
+        custody.status === "present" &&
+        (recorded?.unit_branch !== branch || recorded.unit_path !== path)) {
+        return {
+            error: "unit_foreign",
+            message: `La rama ${branch} no está registrada en la custodia de esta sesión.`,
+        };
+    }
+    const from = exists ? null : base;
+    if (from === null && !exists)
+        return undeclaredWorkBranch(source.alias);
+    if (from !== null && !(await deps.git.branchExists(source.path, from))) {
+        return {
+            error: "base_missing",
+            message: `la rama base '${from}' no existe en ${source.alias}`,
+            hint: `restaurá '${from}' antes de abrir la unidad`,
+        };
+    }
     try {
         await deps.git.worktreeAdd(source.path, path, branch, from);
     }
@@ -386,13 +666,31 @@ async function ensureUnit(deps, target) {
         return {
             error: "worktree_add_failed",
             message: err.message,
-            hint: `verificá que la rama base '${base}' exista en ${source.alias}`,
         };
     }
-    const sealed = await sealBaseline(deps, target);
+    const sealed = base === null ? null : await sealBaseline(deps, { ...target, base });
     if (sealed !== null)
         return sealed;
-    return { ...unitOf(target, true), visibility: await attach(deps, path) };
+    const visible = await attach(deps, path);
+    const visibilityError = [...staleErrors, visible.error].filter(Boolean).join("; ");
+    return {
+        ...unitOf(target, true),
+        base,
+        visibility: visible.state,
+        ...(visibilityError ? { visibility_error: visibilityError } : {}),
+        longpaths_enabled: longpathsEnabled,
+        dependencies: await linkUnitDependencies(deps.fs, deps.git, source.path, path),
+    };
+}
+async function enableLongPaths(deps, repo) {
+    if ((deps.platform ?? process.platform) !== "win32")
+        return false;
+    if (!deps.git.readConfig || !deps.git.writeLocalConfig)
+        throw new Error("git no permite configurar core.longpaths localmente");
+    if ((await deps.git.readConfig(repo, "core.longpaths"))?.toLowerCase() === "true")
+        return false;
+    await deps.git.writeLocalConfig(repo, "core.longpaths", "true");
+    return true;
 }
 /**
  * Seal how the source stood before this unit gets edited, or refuse the unit.
@@ -430,38 +728,105 @@ async function releaseUnit(deps, target) {
         };
     }
     const existing = await deps.git.worktreeList(source.path);
-    if (!existing.some((w) => samePath(w.path, path))) {
+    const registered = existing.find((w) => samePath(w.path, path));
+    if (registered && (await deps.fs.lstat(path)) === null) {
+        await deps.git.worktreePrune(source.path);
+        if ((await deps.git.worktreeList(source.path)).some((w) => samePath(w.path, path)))
+            return { error: "remove_blocked", message: `git aún registra la unidad sin carpeta ${path}` };
+        return releaseUnit(deps, target);
+    }
+    if (registered === undefined) {
         await ensureWorklineMaterialized(deps.fs, deps.paths);
         await deps.git.worktreePrune(source.path);
+        let completed = false;
+        if ((await deps.fs.lstat(path)) !== null) {
+            try {
+                const blockers = await finishResidue(deps.fs, deps.git, source.path, path, branch);
+                if (blockers.length > 0)
+                    return {
+                        error: "remove_blocked",
+                        message: `quedó residuo en ${path}: ${blockers.join(", ")}`,
+                        hint: `revisá los archivos nombrados y volvé a correr 'aw worktree release --source ${source.alias} --code ${identity.session}'`,
+                    };
+                completed = true;
+            }
+            catch (err) {
+                return {
+                    error: "remove_blocked",
+                    message: `quedó residuo en ${path}: ${err.message}`,
+                };
+            }
+        }
+        const branchKept = await deleteContainedUnitBranch(deps, target);
+        const visible = await detach(deps, path);
         return {
             alias: source.alias,
             session: identity.session,
             path,
             branch,
-            released: false,
-            visibility: await detach(deps, path),
+            released: completed,
+            residue_completed: completed,
+            ...(branchKept ? { branch_kept: branchKept } : {}),
+            visibility: visible.state,
+            ...(visible.error ? { visibility_error: visible.error } : {}),
         };
     }
+    if (registered.branch !== branch)
+        return {
+            error: "unit_foreign",
+            message: `la unidad ${path} usa ${registered.branch}, no ${branch}`,
+        };
     await ensureWorklineMaterialized(deps.fs, deps.paths);
     try {
-        await deps.git.worktreeRemove(source.path, path);
+        await removeUnitSafely(deps.fs, deps.git, source.path, path);
     }
     catch (err) {
+        const now = await deps.git.worktreeList(source.path);
+        if (!now.some((w) => samePath(w.path, path)))
+            return releaseUnit(deps, target);
         return {
-            error: "unit_not_clean",
-            message: err.message,
-            hint: "commiteá o descartá los cambios de la unidad y volvé a liberarla; nada se borra por la fuerza",
+            error: (await deps.git.isDirty(path)) ? "unit_not_clean" : "remove_blocked",
+            message: `quedó ${path}: ${err.message}`,
+            hint: `revisá ${path} y volvé a correr 'aw worktree release --source ${source.alias} --code ${identity.session}'`,
         };
     }
+    if ((await deps.fs.lstat(path)) !== null) {
+        const blockers = await finishResidue(deps.fs, deps.git, source.path, path, branch);
+        if (blockers.length > 0)
+            return { error: "remove_blocked", message: `quedó ${path}: ${blockers.join(", ")}` };
+    }
+    const branchKept = await deleteContainedUnitBranch(deps, target);
+    const visible = await detach(deps, path);
     return {
         alias: source.alias,
         session: identity.session,
         path,
         branch,
         released: true,
-        visibility: await detach(deps, path),
+        ...(branchKept ? { branch_kept: branchKept } : {}),
+        visibility: visible.state,
+        ...(visible.error ? { visibility_error: visible.error } : {}),
     };
 }
+/** Only a unit branch, only with a sealed/effective base, only by the observed tip. */
+async function deleteContainedUnitBranch(deps, target) {
+    const { source, path, branch, base } = target;
+    if (!branch.startsWith("aw/") || branch === base)
+        return "no es una rama de unidad borrable";
+    if ((await deps.fs.lstat(path)) !== null ||
+        (await deps.git.worktreeList(source.path)).some((tree) => tree.branch === branch))
+        return "la carpeta o la rama siguen ocupadas; no se borra";
+    const tip = await deps.git.refValue(source.path, `refs/heads/${branch}`);
+    if (tip === null)
+        return null;
+    if (base === null)
+        return "sin base sellada o rama de trabajo; la rama se conserva";
+    const baseTip = await deps.git.refValue(source.path, `refs/heads/${base}`);
+    if (baseTip === null || !(await deps.git.isAncestor(source.path, tip, baseTip)))
+        return `commits de ${branch} no contenidos en ${base}; la rama se conserva`;
+    const deleted = await deps.git.deleteRef(source.path, `refs/heads/${branch}`, tip);
+    return deleted.ok ? null : `no se pudo borrar ${branch} con punta ${tip}: ${deleted.why}`;
+}
 /**
  * Collect the residue: one act over the whole workspace, or over one session.
  *
@@ -485,7 +850,7 @@ async function reclaimUnits(deps, input) {
         return {
             error: "no_sources_declared",
             message: "el bloque WORKSPACE no declara ninguna fuente",
-            hint: "declará la fuente en la tabla Fuentes antes de pedir una recogida",
+            hint: "declará la fuente con aw add-source <alias>:<ruta>:<rama> antes de pedir una recogida",
         };
     }
     if (input.alias !== undefined && !sources.some((s) => s.alias === input.alias)) {
@@ -498,6 +863,7 @@ async function reclaimUnits(deps, input) {
     const key = workspaceKey(deps.paths.workspaceDir());
     const root = await canonicalUnitsRootForRead(deps);
     const sessions = await sessionStates(deps);
+    const owns = await hubUnitPaths(deps.fs, deps.paths, root);
     const only = input.sessionCode ?? null;
     const reclaimed = [];
     const retained = [];
@@ -505,9 +871,13 @@ async function reclaimUnits(deps, input) {
     for (const source of sources) {
         if (input.alias !== undefined && source.alias !== input.alias)
             continue;
-        const swept = await sweepSource(deps, source, { root, key, only, sessions, block });
+        const swept = await sweepSource(deps, source, { root, key, only, sessions, block, owns });
         if ("error" in swept) {
-            unreadable.push({ alias: source.alias, error: swept.error });
+            unreadable.push({
+                alias: source.alias,
+                error: swept.error,
+                ...(swept.code ? { code: swept.code } : {}),
+            });
             continue;
         }
         reclaimed.push(...swept.reclaimed);
@@ -519,21 +889,30 @@ async function reclaimUnits(deps, input) {
         reclaimed,
         retained,
         unreadable,
-        next: retained[0]?.next ?? null,
+        next: retained[0]?.next ??
+            (unreadable[0]?.code === "SOURCE_PATH_MISSING"
+                ? `aw add-source ${unreadable[0].alias}:<ruta>`
+                : null),
     };
 }
 /** What one source's residue produced, or why its trees could not be read. */
 async function sweepSource(deps, source, ctx) {
-    if (!(await deps.git.isGitRepo(source.path)))
+    let repo;
+    try {
+        repo = await requireSourcePath(deps.fs, source);
+    }
+    catch (err) {
+        return { error: err.message, code: "SOURCE_PATH_MISSING" };
+    }
+    if (!(await deps.git.isGitRepo(repo)))
         return { reclaimed: [], retained: [] };
     let trees;
     try {
-        trees = await deps.git.worktreeList(source.path);
+        trees = await deps.git.worktreeList(repo);
     }
     catch (err) {
         return { error: err.message };
     }
-    const work = resolveSourceBranches(source, ctx.block).work;
     const reclaimed = [];
     const retained = [];
     const vanished = [];
@@ -541,7 +920,8 @@ async function sweepSource(deps, source, ctx) {
         const candidate = candidateOf(tree, ctx);
         if (candidate === null)
             continue;
-        const swept = await sweepOne(deps, source, tree, work, candidate);
+        const work = await baseForReclaim(deps, source.alias, candidate.session, resolveSourceBranches(source, ctx.block).work);
+        const swept = await sweepOne(deps, { ...source, path: repo }, tree, work, candidate);
         if ("retained" in swept) {
             retained.push(swept.retained);
             continue;
@@ -555,18 +935,124 @@ async function sweepSource(deps, source, ctx) {
             reclaimed.push(swept.reclaimed);
     }
     if (vanished.length > 0) {
-        const settled = await prune(deps, source, vanished);
+        const settled = await prune(deps, { ...source, path: repo }, vanished, ctx.block);
         reclaimed.push(...settled.reclaimed);
         retained.push(...settled.retained);
     }
+    const registered = new Set(trees.map((tree) => normalizePath(tree.path)));
+    // Also visit previous workspace keys registered by 075, without claiming another hub's units.
+    for (const keyEntry of (await deps.fs.lstat(ctx.root)) === null
+        ? []
+        : await deps.fs.list(ctx.root)) {
+        if (keyEntry.type !== "dir")
+            continue;
+        const aliasDir = join(keyEntry.path, source.alias);
+        if ((await deps.fs.lstat(aliasDir))?.type !== "dir")
+            continue;
+        for (const sessionEntry of await deps.fs.list(aliasDir)) {
+            if (sessionEntry.type !== "dir" ||
+                registered.has(normalizePath(sessionEntry.path)) ||
+                !ctx.owns(sessionEntry.path))
+                continue;
+            const identity = parseUnitPath(ctx.root, sessionEntry.path);
+            if (identity?.alias !== source.alias ||
+                (ctx.only !== null && !sessionFolderMatches(identity.session, ctx.only)))
+                continue;
+            const orphan = orphanReason(identity.session, ctx.sessions, false);
+            if (orphan === null && ctx.only === null)
+                continue;
+            const branch = await branchForResidue(deps, repo, identity, sessionEntry.path);
+            const where = {
+                alias: source.alias,
+                session: identity.session,
+                path: sessionEntry.path,
+                branch,
+            };
+            try {
+                const blockers = await finishResidue(deps.fs, deps.git, repo, sessionEntry.path, branch);
+                if (blockers.length > 0) {
+                    retained.push({
+                        ...where,
+                        reason: "archivos_no_recuperables",
+                        detail: blockers.join(", "),
+                        next: `revisá ${sessionEntry.path} y volvé a correr 'aw worktree reclaim --code ${identity.session}'`,
+                    });
+                    continue;
+                }
+                await deps.git.worktreePrune(repo);
+                const base = await baseForReclaim(deps, source.alias, identity.session, resolveSourceBranches(source, ctx.block).work);
+                const kept = await deleteContainedUnitBranch(deps, {
+                    source: { ...source, path: repo },
+                    path: sessionEntry.path,
+                    branch: branch ?? "",
+                    base,
+                });
+                const visible = await detach(deps, sessionEntry.path);
+                reclaimed.push({
+                    ...where,
+                    reason: orphan ?? "already_on_work_branch",
+                    ...(kept ? { branch_kept: kept } : {}),
+                    ...(visible.error ? { visibility_error: visible.error } : {}),
+                });
+            }
+            catch (err) {
+                retained.push({
+                    ...where,
+                    reason: "unreadable",
+                    detail: err.message,
+                    next: `revisá ${sessionEntry.path} antes de recoger`,
+                });
+            }
+        }
+    }
     return { reclaimed, retained };
 }
+async function branchForResidue(deps, repo, identity, path) {
+    const custody = await readCustody(deps.fs, join(deps.paths.cwdSessionsDir(), identity.session));
+    const recorded = custody.status === "present"
+        ? custody.custody.sources.find((s) => s.alias === identity.alias && s.unit_path === path)
+        : undefined;
+    if (recorded?.unit_branch)
+        return recorded.unit_branch;
+    const names = [
+        `aw/${identity.workspaceKey.slice(-8)}/${identity.session}`,
+        unitBranch(identity.session),
+    ];
+    for (const branch of names)
+        if (await deps.git.branchExists(repo, branch))
+            return branch;
+    return null;
+}
+async function baseForReclaim(deps, alias, session, fallback) {
+    const read = await readCustody(deps.fs, join(deps.paths.cwdSessionsDir(), session));
+    if (read.status === "unreadable")
+        return null;
+    return read.status === "present"
+        ? (read.custody.sources.find((source) => source.alias === alias)?.base_branch ?? fallback)
+        : fallback;
+}
 /** The vanished trees git dropped, or the same ones still listed and why. */
-async function prune(deps, source, vanished) {
+async function prune(deps, source, vanished, block) {
     await ensureWorklineMaterialized(deps.fs, deps.paths);
     try {
         await deps.git.worktreePrune(source.path);
-        return { reclaimed: vanished, retained: [] };
+        const reclaimed = [];
+        for (const unit of vanished) {
+            const base = await baseForReclaim(deps, unit.alias, unit.session, resolveSourceBranches(source, block).work);
+            const kept = await deleteContainedUnitBranch(deps, {
+                source,
+                path: unit.path,
+                branch: unit.branch ?? "",
+                base,
+            });
+            const visible = await detach(deps, unit.path);
+            reclaimed.push({
+                ...unit,
+                ...(kept ? { branch_kept: kept } : {}),
+                ...(visible.error ? { visibility_error: visible.error } : {}),
+            });
+        }
+        return { reclaimed, retained: [] };
     }
     catch (err) {
         return {
@@ -586,7 +1072,7 @@ async function prune(deps, source, vanished) {
 /** The identity and residue state of a tree this sweep may act on; `null` otherwise. */
 function candidateOf(tree, ctx) {
     const identity = tree.main ? null : parseUnitPath(ctx.root, tree.path);
-    if (identity === null || identity.workspaceKey !== ctx.key)
+    if (identity === null || !ctx.owns(tree.path))
         return null;
     if (ctx.only !== null && !sessionFolderMatches(identity.session, ctx.only))
         return null;
@@ -612,28 +1098,72 @@ async function sweepOne(deps, source, tree, work, candidate) {
         // was, so there is no work this can lose.
         return { reclaimed: { ...where, reason: candidate.orphan }, prune: true };
     }
+    if (work === null)
+        return {
+            retained: {
+                ...where,
+                reason: "unreadable",
+                detail: `no se pudo determinar la base sellada ni una rama de trabajo para ${source.alias}`,
+                next: `revisá la custodia de ${candidate.session} o usá 'aw set-working-branch ${source.alias} <rama>' antes de recoger`,
+            },
+        };
     const verdict = await reclaimability(deps, source, tree, work, candidate.orphan, candidate.session);
     if (!verdict.free)
         return { retained: { ...where, ...verdict.retention } };
     await ensureWorklineMaterialized(deps.fs, deps.paths);
     try {
-        await deps.git.worktreeRemove(source.path, tree.path);
+        await removeUnitSafely(deps.fs, deps.git, source.path, tree.path);
     }
     catch (err) {
-        // git refused, and git refusing is the last line of the same rule: never
-        // `--force`, so whatever it is holding stays held.
-        return {
-            retained: {
-                ...where,
-                reason: "remove_refused",
-                detail: err.message,
-                next: `revisá ${tree.path} y volvé a correr 'aw worktree reclaim'; nada se borra por la fuerza`,
-            },
-        };
+        if ((await deps.git.worktreeList(source.path)).some((w) => samePath(w.path, tree.path)))
+            return {
+                retained: {
+                    ...where,
+                    reason: "remove_refused",
+                    detail: err.message,
+                    next: `revisá ${tree.path} y volvé a correr 'aw worktree reclaim'; nada se borra por la fuerza`,
+                },
+            };
+    }
+    if ((await deps.fs.lstat(tree.path)) !== null) {
+        try {
+            const blockers = await finishResidue(deps.fs, deps.git, source.path, tree.path, tree.branch);
+            if (blockers.length > 0)
+                return {
+                    retained: {
+                        ...where,
+                        reason: "archivos_no_recuperables",
+                        detail: blockers.join(", "),
+                        next: `revisá ${tree.path} y volvé a recoger`,
+                    },
+                };
+        }
+        catch (err) {
+            return {
+                retained: {
+                    ...where,
+                    reason: "remove_refused",
+                    detail: err.message,
+                    next: `revisá ${tree.path} y volvé a recoger`,
+                },
+            };
+        }
     }
-    await detach(deps, tree.path);
+    await deps.git.worktreePrune(source.path);
+    const branchKept = await deleteContainedUnitBranch(deps, {
+        source,
+        path: tree.path,
+        branch: tree.branch ?? "",
+        base: work,
+    });
+    const visible = await detach(deps, tree.path);
     return {
-        reclaimed: { ...where, reason: candidate.orphan ?? "already_on_work_branch" },
+        reclaimed: {
+            ...where,
+            reason: candidate.orphan ?? "already_on_work_branch",
+            ...(branchKept ? { branch_kept: branchKept } : {}),
+            ...(visible.error ? { visibility_error: visible.error } : {}),
+        },
         prune: false,
     };
 }
@@ -675,6 +1205,9 @@ async function reclaimability(deps, source, tree, work, orphan, session) {
     if (tree.head === null) {
         return held("unreadable", "git no reportó el HEAD de la unidad", `revisá ${tree.path} a mano: sin HEAD no se puede decidir si sus commits ya están en '${work}'`);
     }
+    if ((await deps.git.refValue(source.path, `refs/heads/${work}`)) === null) {
+        return held("unreadable", `la base sellada '${work}' ya no existe en local`, `restaurá '${work}' antes de recoger la unidad ${tree.path}`);
+    }
     if (!(await deps.git.isAncestor(source.path, tree.head, work))) {
         return held("commits_outside_work_branch", `la unidad tiene commits que no están en '${work}'`, recoveryFor(source, tree, orphan, work, session));
     }
@@ -683,7 +1216,7 @@ async function reclaimability(deps, source, tree, work, orphan, session) {
 /** How the work of a unit that is not on the working branch gets back onto it. */
 function recoveryFor(source, tree, orphan, work, session) {
     if (orphan === "session_closed") {
-        return `aw session-resume --code ${session} --reopen y después 'aw worktree integrate --source ${source.alias} --code ${session}'`;
+        return `aw worktree integrate --source ${source.alias} --code ${session}`;
     }
     if (orphan === "session_absent") {
         return `la sesión ${session} ya no existe: revisá la rama ${tree.branch ?? unitBranch(session)} en ${source.path} y llevá sus commits a '${work}' antes de volver a recoger`;
@@ -713,16 +1246,21 @@ async function listUnits(deps, input) {
     const key = workspaceKey(deps.paths.workspaceDir());
     const root = await canonicalUnitsRootForRead(deps);
     const sessions = await sessionStates(deps);
+    const owns = await hubUnitPaths(deps.fs, deps.paths, root);
     const units = [];
     const orphans = [];
     const unreadable = [];
     for (const source of block?.fuentes ?? []) {
-        const scanned = await scanSource(deps, source, { root, key, only, sessions });
+        const scanned = await scanSource(deps, source, { root, key, only, sessions, owns });
         if ("error" in scanned) {
             // Reported, never skipped in silence: a source whose trees cannot be read
             // would otherwise show up as "no units", which is the one answer that is
             // certainly wrong — its flows are exactly the ones nobody would clean up.
-            unreadable.push({ alias: source.alias, error: scanned.error });
+            unreadable.push({
+                alias: source.alias,
+                error: scanned.error,
+                ...(scanned.code ? { code: scanned.code } : {}),
+            });
             continue;
         }
         units.push(...scanned.units);
@@ -741,11 +1279,18 @@ async function scanSource(deps, source, ctx) {
     const empty = { units: [], orphans: [] };
     // Not a repo is not unreadable: it has no worktrees to report, and calling it
     // an error would put every non-git source in front of the reader forever.
-    if (!(await deps.git.isGitRepo(source.path)))
+    let repo;
+    try {
+        repo = await requireSourcePath(deps.fs, source);
+    }
+    catch (err) {
+        return { error: err.message, code: "SOURCE_PATH_MISSING" };
+    }
+    if (!(await deps.git.isGitRepo(repo)))
         return empty;
     let trees;
     try {
-        trees = await deps.git.worktreeList(source.path);
+        trees = await deps.git.worktreeList(repo);
     }
     catch (err) {
         return { error: err.message };
@@ -754,13 +1299,13 @@ async function scanSource(deps, source, ctx) {
     const orphans = [];
     for (const tree of trees) {
         const identity = tree.main ? null : parseUnitPath(ctx.root, tree.path);
-        if (identity === null || identity.workspaceKey !== ctx.key)
+        if (identity === null || !ctx.owns(tree.path))
             continue;
         if (ctx.only !== null && identity.session !== ctx.only)
             continue;
         const reason = orphanReason(identity.session, ctx.sessions, tree.prunable);
         if (reason === null)
-            units.push(await liveUnit(deps, identity, source.path, tree));
+            units.push(await liveUnit(deps, identity, repo, tree));
         else
             orphans.push(orphanOf(identity, tree, reason));
     }
@@ -825,7 +1370,7 @@ async function sessionStates(deps) {
     for (const folder of folders) {
         // `.closed` is the only source of a session's state (the session resolver's
         // own rule); re-deriving it from anything else would let the two disagree.
-        if (!(await deps.fs.exists(join(folder.path, ".closed"))))
+        if ((await readSessionState(deps.fs, folder.path)) === "active")
             active.add(folder.name);
     }
     return { known: new Set(folders.map((f) => f.name)), active };
@@ -860,11 +1405,15 @@ function unitOf(target, created) {
  */
 async function attach(deps, path) {
     const result = await runMultiroot(deps.fs, deps.env, deps.paths, "attach", { paths: [path] });
-    return "error" in result ? "unavailable" : "attached";
+    return "error" in result
+        ? { state: "unavailable", error: `${result.error}: ${result.hint ?? "sin detalle"}` }
+        : { state: "attached" };
 }
 async function detach(deps, path) {
     const result = await runMultiroot(deps.fs, deps.env, deps.paths, "detach", { paths: [path] });
-    return "error" in result ? "unavailable" : "detached";
+    return "error" in result
+        ? { state: "unavailable", error: `${result.error}: ${result.hint ?? "sin detalle"}` }
+        : { state: "detached" };
 }
 function samePath(a, b) {
     return normalizePath(a) === normalizePath(b);