agentic-workflow-manager 6.2.1 → 6.4.0

package/dist/src/core/tracks/context.js

@@ -0,0 +1,89 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.planDigest = planDigest;
+exports.assertTrackTask = assertTrackTask;
+exports.resolveAuthenticatedContext = resolveAuthenticatedContext;
+exports.resolveCommandContext = resolveCommandContext;
+// Resolucion de contexto autenticado (R2.6, R9.4, R9.5): un track SOLO se
+// autentica leyendo el journal del PLAN que su propio descriptor declara —
+// jamas enumera ni abre journals hermanos (R2.7). La lectura es siempre
+// read-only al momento de necesitarse (R9.5): nada aqui espeja ni cachea
+// estado ajeno.
+const fs_1 = __importDefault(require("fs"));
+const crypto_1 = __importDefault(require("crypto"));
+const paths_1 = require("../paths");
+const descriptor_1 = require("./descriptor");
+const store_1 = require("../journal/store");
+function planDigest(source) {
+    return crypto_1.default.createHash('sha256').update(source.replace(/\r\n/g, '\n')).digest('hex');
+}
+/** R2.3/R2.4: un track jamas ejecuta una tarea fuera de su asignacion, y un
+ *  planDigest divergente bloquea ANTES de mirar taskIds — el plan cambio
+ *  bajo los pies del track, la asignacion entera dejo de ser confiable. */
+function assertTrackTask(ctx, taskId, currentPlanDigest) {
+    if (ctx.planDigest !== currentPlanDigest)
+        throw new Error('BLOCKED: planDigest divergente');
+    if (!ctx.taskIds.includes(taskId))
+        throw new Error(`task ${taskId} fuera de la asignación ${ctx.trackId}`);
+}
+/** Autentica un cwd contra el journal del plan que su descriptor declara
+ *  (R2.6, R9.4). Recibe los JournalState YA leidos (localState del propio
+ *  cwd, planState del journal del plan) — la funcion en si es pura, para que
+ *  la autenticacion sea testeable sin tocar disco; el I/O real vive en
+ *  `resolveCommandContext` mas abajo. */
+function resolveAuthenticatedContext(cwd, localState, planState = localState) {
+    const root = fs_1.default.realpathSync(cwd);
+    const descriptor = (0, descriptor_1.readDescriptor)(root);
+    if (descriptor === null)
+        return { mode: 'plan', repoRoot: root, journal: localState };
+    if (localState.trackContext === undefined)
+        throw new Error('descriptor presente sin trackContext');
+    const planRoot = fs_1.default.realpathSync(descriptor.planRoot);
+    const ref = planState.tracks?.find((candidate) => candidate.trackId === descriptor.trackId);
+    if (planState.journalId !== descriptor.planJournalId || localState.trackContext.planJournalId !== descriptor.planJournalId) {
+        throw new Error('planJournalId no coincide');
+    }
+    if (ref === undefined)
+        throw new Error('TrackRef ausente en journal del plan');
+    if (ref.fencingToken !== descriptor.fencingToken)
+        throw new Error('fencingToken no coincide');
+    // Identidad de filesystem, no de string: en Windows `process.cwd()` y el path guardado
+    // en el journal pueden ser dos grafías de la misma carpeta (8.3 vs nombre largo).
+    if (!(0, paths_1.sameExistingPath)(ref.worktreePath, root) || (0, paths_1.sameExistingPath)(planRoot, root))
+        throw new Error('realpath de track no coincide');
+    if (localState.trackContext.trackId !== descriptor.trackId)
+        throw new Error('trackId no coincide');
+    return { mode: 'track', repoRoot: root, descriptor, trackContext: localState.trackContext };
+}
+/** Guard de entrada para los verbos `awm job`/`awm watch` (R9.4). Sin
+ *  descriptor => modo plan de siempre, SIN leer ningun journal — el caso
+ *  comun (todo repo sin tracks) no paga ningun costo ni riesgo nuevo; la
+ *  logica propia de cada verbo sigue leyendo el journal como ya lo hacia.
+ *  Con descriptor presente, lee el journal local y el del plan (SOLO ese,
+ *  R2.7/R9.5) y delega la autenticacion real a resolveAuthenticatedContext;
+ *  cualquier fallo se homogeniza bajo un mensaje que SIEMPRE contiene
+ *  "cwd no autenticado", para que el CLI lo reporte con un patron unico. */
+function resolveCommandContext(repoRoot, branch) {
+    const root = fs_1.default.realpathSync(repoRoot);
+    const descriptor = (0, descriptor_1.readDescriptor)(root);
+    if (descriptor === null)
+        return { mode: 'plan' };
+    try {
+        const local = (0, store_1.readJournal)(root, branch);
+        if (local.corrupt || local.state === null)
+            throw new Error('journal local corrupto o ausente');
+        const plan = (0, store_1.readJournal)(descriptor.planRoot, descriptor.planBranch);
+        if (plan.corrupt || plan.state === null)
+            throw new Error('journal del plan corrupto o ausente');
+        const authenticated = resolveAuthenticatedContext(root, local.state, plan.state);
+        if (authenticated.mode !== 'track')
+            throw new Error('descriptor presente pero no resolvio a modo track');
+        return { mode: 'track', context: authenticated };
+    }
+    catch (error) {
+        throw new Error(`cwd no autenticado: ${error.message}`);
+    }
+}

package/dist/src/core/tracks/descriptor.js

@@ -0,0 +1,40 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.descriptorPath = void 0;
+exports.writeDescriptor = writeDescriptor;
+exports.readDescriptor = readDescriptor;
+// Descriptor local de un worktree de track (R2.5): NUNCA versionado, vive
+// bajo .awm/ igual que el journal. Es la unica prueba local de pertenencia a
+// un plan — el resto de la autenticacion (R2.6) se hace en context.ts contra
+// el TrackRef del journal del plan, jamas confiando solo en este archivo.
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const atomic_file_1 = require("../atomic-file");
+const descriptorPath = (trackRoot) => path_1.default.join(trackRoot, '.awm', 'track.json');
+exports.descriptorPath = descriptorPath;
+/** 0600 + escritura durable (mismo contrato que el journal, R1.2): un
+ *  descriptor a medio escribir jamas debe autenticar un cwd. */
+function writeDescriptor(trackRoot, value) {
+    if (value.schema !== 1 || !path_1.default.isAbsolute(value.planRoot) || value.trackId.length === 0
+        || value.planJournalId.length === 0 || value.fencingToken.length < 32) {
+        throw new Error('descriptor de track inválido');
+    }
+    fs_1.default.mkdirSync(path_1.default.dirname((0, exports.descriptorPath)(trackRoot)), { recursive: true, mode: 0o700 });
+    (0, atomic_file_1.writeFileAtomicDurable)((0, exports.descriptorPath)(trackRoot), JSON.stringify({ ...value, planRoot: fs_1.default.realpathSync(value.planRoot) }, null, 2) + '\n', 0o600);
+}
+/** null = sin descriptor (modo plan, el caso comun). Forma invalida SIEMPRE
+ *  lanza — un descriptor corrupto jamas autentica por omision (R1.6). */
+function readDescriptor(trackRoot) {
+    const file = (0, exports.descriptorPath)(trackRoot);
+    if (!fs_1.default.existsSync(file))
+        return null;
+    const x = JSON.parse(fs_1.default.readFileSync(file, 'utf8'));
+    if (x.schema !== 1 || typeof x.planRoot !== 'string' || typeof x.planBranch !== 'string'
+        || typeof x.trackId !== 'string' || typeof x.planJournalId !== 'string'
+        || typeof x.fencingToken !== 'string')
+        throw new Error('track.json corrupto');
+    return x;
+}

package/dist/src/core/tracks/git.js

@@ -0,0 +1,318 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isAwmGitignored = isAwmGitignored;
+exports.headSha = headSha;
+exports.isWorktreeClean = isWorktreeClean;
+exports.assertPlanHead = assertPlanHead;
+exports.foreignPathExists = foreignPathExists;
+exports.ownedWorktreeExists = ownedWorktreeExists;
+exports.branchExists = branchExists;
+exports.removeOwnedBranch = removeOwnedBranch;
+exports.gitCheckTrackId = gitCheckTrackId;
+exports.mergeBase = mergeBase;
+exports.addOwnedWorktree = addOwnedWorktree;
+exports.removeOwnedWorktree = removeOwnedWorktree;
+exports.readMergeHead = readMergeHead;
+exports.dirtyPaths = dirtyPaths;
+exports.isAncestor = isAncestor;
+exports.mergeFrozenTrack = mergeFrozenTrack;
+exports.abortOwnedMerge = abortOwnedMerge;
+exports.changedPaths = changedPaths;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
+const process_1 = require("../journal/process");
+const paths_1 = require("../paths");
+const git = (repo, args) => (0, child_process_1.execFileSync)('git', args, { cwd: repo, encoding: 'utf8', stdio: process_1.EXEC_STDIO });
+/** R4.1/C2: `.awm` debe estar demostrablemente ignorado o el journal del
+ *  track podría terminar versionado. `git check-ignore` es una operación de
+ *  working-tree/index — responde por el árbol REALMENTE checkeado en `dir`,
+ *  nunca por un commit arbitrario. Por eso el caller (`defaultTrackRuntime`)
+ *  DEBE pasar el path del worktree ya creado (checkeado en `baseSha`), no el
+ *  repo del plan en su HEAD vivo: ese HEAD puede estar en un commit distinto
+ *  de `baseSha` y dar una respuesta stale (post-review: bug crítico
+ *  encontrado en la primera versión de esta función). `exit 0` = ignorado;
+ *  `exit 1` = no ignorado; cualquier otro fallo tampoco prueba nada — todo lo
+ *  que no sea éxito confirmado se trata como "no ignorado" (fail-closed). */
+function isAwmGitignored(dir) {
+    try {
+        git(dir, ['check-ignore', '-q', '.awm/probe']);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function headSha(repo) {
+    return git(repo, ['rev-parse', 'HEAD']).trim();
+}
+/** R6.4 (Task 10): guard de LIMPIEZA del worktree/index, distinto del guard
+ *  de OWNERSHIP (`changedPaths`/`assessActualOwnership`, que nunca consulta
+ *  `git status` — ver el comentario grande del plan R5-T10 Step 6). `status
+ *  --porcelain` vacío es la única prueba honesta de "nada sin commitear";
+ *  cualquier fallo de git (repo corrupto, permisos) NO prueba limpieza —
+ *  fail-closed, se trata como sucio. */
+function isWorktreeClean(repo) {
+    try {
+        return git(repo, ['status', '--porcelain']).trim().length === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** R5.8/R5.9/C7 (Task 10): comparación fail-closed de HEAD. "Un humano puede
+ *  mutar el repo, pero la mutación se detecta y bloquea" — cualquier fallo de
+ *  `git rev-parse` (repo desaparecido, corrupto) NUNCA se interpreta como
+ *  "no cambió"; el silencio no es prueba, así que se bloquea igual que un
+ *  drift confirmado. */
+function assertPlanHead(repo, expectedSha) {
+    let actual;
+    try {
+        actual = headSha(repo);
+    }
+    catch (error) {
+        throw new Error(`assertPlanHead: HEAD de ${repo} indemostrable — BLOQUEADO (no se asume sin cambios): ${error.message}`);
+    }
+    if (actual !== expectedSha) {
+        throw new Error(`assertPlanHead: HEAD del plan cambió — esperado ${expectedSha}, actual ${actual}: BLOQUEADO`);
+    }
+}
+/** R4.6: nada se considera "nuestro" antes de que lo hayamos creado — si el
+ *  destino ya existe y no está vacío, es por definición ajeno (todavía no
+ *  intentamos crear nada ahí). Devuelve `true` también si no se puede
+ *  *probar* que está vacío (fail-closed: silencio nunca es prueba de nada). */
+function foreignPathExists(target) {
+    try {
+        return fs_1.default.existsSync(target) && fs_1.default.readdirSync(target).length > 0;
+    }
+    catch {
+        return true;
+    }
+}
+/** Task 9 (R4.2/R4.6/C11): true <=> `worktreePath` YA está registrado por
+ *  `git worktree list` como worktree real, checked out exactamente en
+ *  `branch` — el único caso legítimo de "destino no vacío pero nuestro":
+ *  `branch`/`worktreePath` son deterministas (derivados 1:1 del trackId al
+ *  declarar la cohorte, antes del primer intento de `create-worktree`), así
+ *  que nada más los crea con ese nombre y ese path exactos. Distingue "esto
+ *  es un intento propio interrumpido" de "esto es genuinamente ajeno" sin
+ *  ningún estado persistido adicional al que ya vive en el `TrackRef`.
+ *  Fail-closed (R4.6): cualquier fallo en preguntarle a git, o un
+ *  `worktreePath` que ni siquiera se puede resolver, es "no probado" ->
+ *  `false` — el caller sigue tratando el destino como potencialmente ajeno
+ *  vía `foreignPathExists`, nunca lo adopta a ciegas. */
+function ownedWorktreeExists(repo, worktreePath, branch) {
+    if (!fs_1.default.existsSync(worktreePath))
+        return false; // nada ahí todavía: no puede ser "nuestro" de un intento previo
+    let out;
+    try {
+        out = git(repo, ['worktree', 'list', '--porcelain']);
+    }
+    catch {
+        return false;
+    }
+    const wantedRef = `refs/heads/${branch}`;
+    for (const block of out.split('\n\n')) {
+        const lines = block.split('\n');
+        const wtLine = lines.find((l) => l.startsWith('worktree '));
+        const branchLine = lines.find((l) => l.startsWith('branch '));
+        if (wtLine === undefined || branchLine === undefined)
+            continue;
+        // Identidad de filesystem, NUNCA comparación de strings: git imprime los paths con
+        // separadores POSIX y el nombre largo, mientras el `worktreePath` del journal puede
+        // venir en 8.3 con backslashes. Son la misma carpeta escrita de dos formas.
+        if ((0, paths_1.sameExistingPath)(wtLine.slice('worktree '.length), worktreePath)
+            && branchLine.slice('branch '.length) === wantedRef)
+            return true;
+    }
+    return false;
+}
+/** Task 13 (R4.10/C9): `true` <=> la branch local determinista existe. Nombre
+ *  determinista (derivado 1:1 del trackId al declarar la cohorte), así que
+ *  su mera existencia ya es prueba de ownership — a diferencia de un
+ *  worktree (contenido de filesystem que SÍ podría ser ajeno), una branch es
+ *  solo un ref; nada más crea una con ese nombre exacto. */
+function branchExists(repo, branch) {
+    try {
+        git(repo, ['show-ref', '--verify', '--quiet', `refs/heads/${branch}`]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Task 9 (paso BRANCH_REMOVED, Task 13 endurece el guard — R4.10/C9): borra
+ *  la branch local determinista de un track SOLO después de que su worktree
+ *  ya se quitó. `-d` (nunca `-D`, Step 4 del plan T13): un track que se
+ *  aborta durante el teardown durable normalmente nunca divergió de su
+ *  `baseSha` (si divergió, esos commits merecen quedar vivos hasta que un
+ *  operador decida, no borrarse a la fuerza) — `-d` rehúsa por sí solo si no
+ *  está mergeada, que es exactamente el comportamiento fail-closed que C9
+ *  exige. Verifica explícitamente que la branch no siga checked out en
+ *  ningún worktree ANTES de intentar el borrado (git también lo rehúsa
+ *  nativamente, pero el chequeo explícito produce un mensaje diagnóstico
+ *  claro y, sobre todo, trata un `git worktree list` indemostrable como
+ *  bloqueo — nunca como "no está checked out"). Nunca lanza si la branch ya
+ *  no existe — idempotente ante reintentos tras crash (R4.2). */
+function removeOwnedBranch(repo, branch) {
+    if (!branchExists(repo, branch))
+        return; // ya no existe: nada que hacer
+    let out;
+    try {
+        out = git(repo, ['worktree', 'list', '--porcelain']);
+    }
+    catch (error) {
+        throw new Error(`no se pudo verificar si ${branch} sigue checked out — indemostrable: ${error.message}`);
+    }
+    if (out.split('\n').includes(`branch refs/heads/${branch}`)) {
+        throw new Error(`branch ${branch} sigue checked out en un worktree: no se borra`);
+    }
+    git(repo, ['branch', '-d', branch]);
+}
+function gitCheckTrackId(id) {
+    if (!id || id === '.' || id === '..' || id.startsWith('-') || id.includes('/') || id.includes('\\'))
+        return false;
+    try {
+        git(process.cwd(), ['check-ref-format', '--branch', id]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function mergeBase(repo, left, right) {
+    return git(repo, ['merge-base', left, right]).trim();
+}
+/** R4.1/R4.6: crea el worktree del track SOLO si el destino está
+ *  demostrablemente vacío. El caller (`tracks.ts`) es responsable de haber
+ *  verificado `foreignPathExists`/`isAwmGitignored` ANTES de llamar esto —
+ *  esta función es la única frontera que efectivamente ejecuta `git worktree
+ *  add`, y nunca adopta ni sobreescribe contenido preexistente. */
+function addOwnedWorktree(repo, ref, baseSha) {
+    const parent = path_1.default.dirname(ref.worktreePath);
+    fs_1.default.mkdirSync(parent, { recursive: true });
+    if (fs_1.default.existsSync(ref.worktreePath) && fs_1.default.readdirSync(ref.worktreePath).length > 0) {
+        throw new Error(`destino no vacío: ${ref.worktreePath}`);
+    }
+    git(repo, ['worktree', 'add', '-b', ref.branch, ref.worktreePath, baseSha]);
+}
+/** El worktree es NUESTRO — o recién creado en la misma llamada (C2, ej.
+ *  `.awm` no ignorado en `baseSha`), o probado por ownership completo antes
+ *  de llegar acá (Task 13, ver `worktreeOwnershipProven` en `teardown.ts`) —
+ *  esto jamás borra algo ajeno (R4.6). Task 13 (R4.10/C9, Step 4 del plan)
+ *  endurece el guard: YA NO fuerza (`--force` eliminado) — un worktree sucio
+ *  bloquea, nombrando los paths sin commitear, en vez de descartar trabajo
+ *  real sin dejar rastro. `dirtyPaths` sobre el WORKTREE mismo (no sobre
+ *  `repo`): cada worktree tiene su propio árbol de trabajo/index, así que
+ *  `git status` corrido ahí es la única fuente honesta de su propia
+ *  limpieza. */
+function removeOwnedWorktree(repo, worktreePath) {
+    const dirty = dirtyPaths(worktreePath);
+    if (dirty.length > 0) {
+        throw new Error(`worktree sucio, no se remueve sin --force: ${[...dirty].sort().join(', ')}`);
+    }
+    git(repo, ['worktree', 'remove', worktreePath]);
+}
+/** R6.2/R6.6-R6.9/C7 (Task 11): lee el `MERGE_HEAD` REAL del repo — no
+ *  asume nada de un plain `.git/MERGE_HEAD` porque el plan del cohorte
+ *  siempre opera sobre el repo PRINCIPAL (nunca un worktree secundario acá),
+ *  pero `--git-path` es la única forma honesta de resolverlo sin asumir la
+ *  estructura de `.git` (podría ser un dir o, en teoría, otra cosa).
+ *  `null` <=> demostrablemente SIN merge en curso (el archivo no existe);
+ *  cualquier fallo en RESOLVER el path, o el archivo presente pero
+ *  ilegible, es indemostrable y BLOQUEA (fail-closed) — nunca se interpreta
+ *  silencio como "no hay merge". */
+function readMergeHead(repo) {
+    let gitPath;
+    try {
+        gitPath = git(repo, ['rev-parse', '--git-path', 'MERGE_HEAD']).trim();
+    }
+    catch (error) {
+        throw new Error(`readMergeHead: no se pudo resolver el path de MERGE_HEAD en ${repo} — indemostrable: ${error.message}`);
+    }
+    const abs = path_1.default.isAbsolute(gitPath) ? gitPath : path_1.default.join(repo, gitPath);
+    if (!fs_1.default.existsSync(abs))
+        return null;
+    try {
+        return fs_1.default.readFileSync(abs, 'utf8').trim();
+    }
+    catch (error) {
+        throw new Error(`readMergeHead: MERGE_HEAD existe en ${abs} pero es ilegible — indemostrable: ${error.message}`);
+    }
+}
+/** R6.4/R6.5 (Task 11, reutilizado por `abortOwnedMerge`): mismo criterio
+ *  fail-closed que `isWorktreeClean` pero devolviendo los paths (nunca se
+ *  descartan — R6.5). Un fallo de `git status` NUNCA prueba limpieza: un
+ *  centinela no vacío obliga a cualquier caller a tratar el árbol como
+ *  sucio en vez de asumir silenciosamente cero paths sucios. */
+function dirtyPaths(repo) {
+    let out;
+    try {
+        out = git(repo, ['status', '--porcelain']);
+    }
+    catch {
+        return ['<estado indemostrable: git status falló>'];
+    }
+    return out.split('\n').filter((line) => line.length > 0).map((line) => line.slice(3));
+}
+/** R6.6/R6.7 (Task 11): `true` <=> `ancestor` es alcanzable desde
+ *  `descendant` — usado SOLO cuando `readMergeHead` ya probó que no hay
+ *  merge en curso, para distinguir "todavía no se intentó" de "ya se
+ *  mergeó" (un merge `--no-ff` exitoso siempre deja al track como ancestro
+ *  del nuevo HEAD). Fail-closed hacia `false`: cualquier fallo de git (SHA
+ *  inválido, repo corrupto) nunca se interpreta como ancestría probada —
+ *  eso empujaría a `decideJoinReconciliation` hacia `accept-merge` sin
+ *  evidencia real. */
+function isAncestor(repo, ancestor, descendant) {
+    try {
+        git(repo, ['merge-base', '--is-ancestor', ancestor, descendant]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** R6.2/R6.3/C7 (Task 11, Step 4 del plan — snippet reproducido exacto):
+ *  único punto que ejecuta el merge real `no-ff` de un track ya `FROZEN`
+ *  sobre la rama del plan. `assertPlanHead` ANTES de mutar nada (TOCTOU,
+ *  C7): un HEAD movido bajo nuestros pies bloquea en vez de mergear a
+ *  ciegas. Si `git merge` falla (conflicto real, u otra causa), la
+ *  excepción se propaga tal cual — el caller (`runMergeTrack` en
+ *  `watch/tracks.ts`) NUNCA interpreta la excepción por sí misma: relee el
+ *  estado real del repo después para decidir qué pasó de verdad. */
+function mergeFrozenTrack(repo, intent) {
+    assertPlanHead(repo, intent.expectedPlanHeadSha);
+    git(repo, ['merge', '--no-ff', '--no-edit', intent.expectedTrackHeadSha]);
+}
+/** R6.2/R6.3/C7 (Task 11, Step 4 del plan — snippet exacto): aborta
+ *  ÚNICAMENTE un merge cuyo `MERGE_HEAD` observado coincide con el
+ *  `expectedTrackHeadSha` del intent propio — jamás un `MERGE_HEAD` ajeno
+ *  (protege contra abortar el merge de otro proceso). Verifica, tras el
+ *  abort, que el árbol quedó demostrablemente limpio (sin `MERGE_HEAD`, sin
+ *  paths sucios); si no, lanza en vez de reportar éxito sobre un estado que
+ *  no se pudo probar recuperado. */
+function abortOwnedMerge(repo, intent) {
+    const observed = readMergeHead(repo);
+    if (observed !== intent.expectedTrackHeadSha)
+        throw new Error('no se aborta MERGE_HEAD ajeno');
+    git(repo, ['merge', '--abort']);
+    if (readMergeHead(repo) !== null || dirtyPaths(repo).length > 0)
+        throw new Error('merge --abort no restauró árbol limpio');
+}
+function changedPaths(repo, base, head) {
+    const fields = git(repo, ['diff', '--name-status', '-z', '--find-renames', base, head]).split('\0');
+    const out = [];
+    for (let i = 0; i < fields.length && fields[i] !== '';) {
+        const status = fields[i++];
+        if (status.startsWith('R') || status.startsWith('C')) {
+            out.push({ status, oldPath: fields[i++], path: fields[i++] });
+        }
+        else {
+            out.push({ status, path: fields[i++] });
+        }
+    }
+    return out;
+}

package/dist/src/core/tracks/join.js

@@ -0,0 +1,185 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IntegrationLockBlockedError = exports.decideJoinReconciliation = void 0;
+exports.validateJoinReadiness = validateJoinReadiness;
+exports.planJoinOrder = planJoinOrder;
+exports.acquireIntegrationLock = acquireIntegrationLock;
+exports.releaseIntegrationLock = releaseIntegrationLock;
+exports.stopControllerGenerationConfirmed = stopControllerGenerationConfirmed;
+// R5.2/R5.8/R5.9/R6.3/R6.4/R6.5/C7 (Task 10): quiescencia del plan y
+// precondiciones de join. Dos familias de funciones acá:
+//   - `validateJoinReadiness`/`planJoinOrder`: PURAS, sin I/O — misma
+//     autoridad única que `protocol.ts`, pero para el momento previo al
+//     primer merge (Task 11 las consume; acá solo se construyen y prueban).
+//   - `acquireIntegrationLock`/`releaseIntegrationLock`/
+//     `stopControllerGenerationConfirmed`: efectos reales, modelados 1:1
+//     sobre `watch/lock.ts` (`acquireLock`/`releaseLock`/`LockBlockedError`)
+//     y sobre el patrón de terminación con identidad confirmada que
+//     `supervisor.ts` ya usa en su camino COMPLETE — nunca un kill crudo.
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const crypto_1 = __importDefault(require("crypto"));
+const store_1 = require("../journal/store");
+const paths_1 = require("../journal/paths");
+const process_1 = require("../journal/process");
+const atomic_file_1 = require("../atomic-file");
+const types_1 = require("../journal/types");
+// R6.8/R6.9/C7 (Task 11): `decideJoinReconciliation` YA vive en `protocol.ts`
+// desde Task 1 (`reconcileProtocol` la llama para su handler de
+// `join-observation`) — regla de autoridad única: esta task NO crea una
+// segunda copia acá. `join-reconcile.test.ts` prueba la matriz completa
+// IMPORTANDO este re-export, así que cualquier fix que la matriz descubra
+// tiene que vivir en `protocol.ts` (y volver a correr la exploración de
+// Task 1 en el mismo commit) para que el test del gate siga significando algo.
+var protocol_1 = require("./protocol");
+Object.defineProperty(exports, "decideJoinReconciliation", { enumerable: true, get: function () { return protocol_1.decideJoinReconciliation; } });
+/** Autoridad única de precondiciones de join: TODO hecho indemostrable o
+ *  adverso bloquea — nunca se descarta un dirty path del mensaje (R6.5), y
+ *  el HEAD congelado se compara byte a byte contra el HEAD real observado
+ *  (protege contra el track mutando su propio worktree después de FROZEN). */
+function validateJoinReadiness(x) {
+    const reasons = [];
+    if (x.actualHeadSha !== x.frozenHeadSha)
+        reasons.push(`HEAD cambió: esperado ${x.frozenHeadSha}, actual ${x.actualHeadSha}`);
+    if (x.dirtyPaths.length > 0)
+        reasons.push(`worktree sucio: ${[...x.dirtyPaths].sort().join(', ')}`);
+    if (!x.gatePass)
+        reasons.push('gate local rojo');
+    if (x.liveJobs > 0)
+        reasons.push(`${x.liveJobs} jobs vivos`);
+    if (x.supervisorAlive)
+        reasons.push('supervisor de track vivo');
+    if (x.lockExists)
+        reasons.push('lock de track retenido');
+    return reasons.length === 0 ? { ok: true } : { ok: false, reasons };
+}
+/** Ownership REAL (post-hoc, desde commits ya congelados — ver
+ *  `assessActualOwnership` en `ownership.ts`), no la declaración de T4: un
+ *  solo track con `outsideOwnership` no vacío serializa el ORDEN de los
+ *  joins restantes (R5.8/R5.9) — nunca revierte merges ya hechos. Un
+ *  `globalClasses` no vacío además invalida el paralelismo de la cohorte
+ *  entera (C5): `parallelInvalidatedBy` nombra `<trackId>:<clase>` para cada
+ *  hallazgo, para que el consumidor (T10 Step 6 en `tracks.ts`) lo persista
+ *  como `cohortParallelInvalidatedBy` y ningún `awm watch` futuro lo pierda. */
+function planJoinOrder(trackIds, assessments) {
+    const violations = {};
+    const parallelInvalidatedBy = [];
+    let serial = false;
+    for (const trackId of trackIds) {
+        const a = assessments[trackId];
+        if (a === undefined)
+            continue;
+        if (a.outsideOwnership.length > 0) {
+            violations[trackId] = [...a.outsideOwnership];
+            serial = true;
+        }
+        if (a.globalClasses.length > 0) {
+            serial = true;
+            for (const cls of a.globalClasses)
+                parallelInvalidatedBy.push(`${trackId}:${cls}`);
+        }
+    }
+    return { mode: serial ? 'serial-joins' : 'parallel-joins', order: [...trackIds], violations, parallelInvalidatedBy };
+}
+// --- Lock de integración (R5.8/R5.9/C7) -------------------------------------
+/** Identidad indemostrable en el lock: BLOQUEAR con error distinto — mismo
+ *  criterio que `LockBlockedError` de `watch/lock.ts`, nunca se reclama lo
+ *  que no se puede probar muerto. */
+class IntegrationLockBlockedError extends Error {
+    constructor(message) { super(message); this.name = 'IntegrationLockBlockedError'; }
+}
+exports.IntegrationLockBlockedError = IntegrationLockBlockedError;
+function isWellFormedIntegrationLockBody(x) {
+    return (0, types_1.isWellFormedProcessRef)(x)
+        && typeof x.planJournalId === 'string'
+        && typeof x.expectedPlanHeadSha === 'string';
+}
+/** Modelado 1:1 sobre `acquireLock` (`watch/lock.ts`): creación EXCLUSIVA
+ *  real (`wx`), 0600, fsync de archivo + directorio, identidad completa
+ *  (`ProcessRef`) más el contexto de integración (`planJournalId` +
+ *  `expectedPlanHeadSha`) para que cualquier lector externo pueda auditar
+ *  QUÉ mutación se autorizó, no solo QUIÉN la retiene. */
+function acquireIntegrationLock(planRoot, ctx) {
+    const lp = (0, paths_1.integrationLockPath)(planRoot);
+    fs_1.default.mkdirSync(path_1.default.dirname(lp), { recursive: true, mode: 0o700 });
+    const self = (0, process_1.captureSelfRef)(crypto_1.default.randomBytes(8).toString('hex'));
+    const body = { ...self, ...ctx };
+    const serialized = JSON.stringify(body, null, 2) + '\n';
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            const fd = fs_1.default.openSync(lp, 'wx', 0o600);
+            try {
+                fs_1.default.writeFileSync(fd, serialized);
+                fs_1.default.fsyncSync(fd);
+            }
+            finally {
+                fs_1.default.closeSync(fd);
+            }
+            (0, atomic_file_1.fsyncDirSync)(path_1.default.dirname(lp));
+            return { ref: self, path: lp };
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+        }
+        let prior;
+        try {
+            prior = JSON.parse(fs_1.default.readFileSync(lp, 'utf8'));
+        }
+        catch {
+            throw new IntegrationLockBlockedError(`integration.lock ilegible en ${lp}: identidad indemostrable — BLOQUEADO (no se reclama)`);
+        }
+        if (!isWellFormedIntegrationLockBody(prior)) {
+            throw new IntegrationLockBlockedError(`integration.lock con shape inválido en ${lp}: identidad indemostrable — BLOQUEADO (no se reclama)`);
+        }
+        if ((0, process_1.refIsAlive)(prior)) {
+            throw new Error(`integración activa (pid ${prior.pid}) sobre este plan`);
+        }
+        process.stderr.write('awm watch: integration.lock previo con identidad muerta probada — reclamando\n');
+        fs_1.default.rmSync(lp, { force: true });
+    }
+    throw new Error('no se pudo adquirir integration.lock tras reintento único (carrera persistente)');
+}
+function releaseIntegrationLock(handle) {
+    try {
+        const onDisk = JSON.parse(fs_1.default.readFileSync(handle.path, 'utf8'));
+        if (onDisk.spawnNonce === handle.ref.spawnNonce)
+            fs_1.default.rmSync(handle.path);
+    }
+    catch { /* ya ausente o ilegible: no tocar lo que no es nuestro */ }
+}
+// --- Pausa de la generación del plan (R5.8/C7) ------------------------------
+/** "Ningún controller administrado sigue corriendo durante el lease" (Step 5
+ *  del plan R5-T10): a diferencia de `resolveGeneration` (generations.ts,
+ *  gobierna reemplazo POR STALL, con backoff/adapter), esto es una pausa
+ *  ADMINISTRATIVA incondicional antes de integrar — termina, con identidad
+ *  confirmada, cualquier generación del PLAN todavía activa. Sin generación
+ *  activa, es un no-op (ya está pausado). Cualquier fallo en confirmar la
+ *  terminación lanza — jamás se adquiere el lock de integración con un
+ *  controller potencialmente vivo. */
+async function stopControllerGenerationConfirmed(planRoot, branch, grace) {
+    const r = (0, store_1.readJournal)(planRoot, branch);
+    if (r.corrupt || r.state === null)
+        throw new Error('journal corrupto: no se puede pausar la generación del plan (R1.6)');
+    const s = r.state;
+    // Misma definición que `activeGeneration` (`watch/generations.ts`),
+    // reimplementada inline: `core/tracks` no depende de `commands/watch`
+    // (dirección de capas), y esto es una sola línea sin lógica propia que
+    // proteger de una duplicación real.
+    const gen = s.generations.find((g) => g.state === 'active' || g.state === 'controller-suspected-stall');
+    if (gen === undefined)
+        return;
+    for (const ref of [gen.processRef, gen.wrapperRef]) {
+        if (ref === undefined || (0, process_1.groupIsGone)(ref.processGroup))
+            continue;
+        const confirmed = await (0, process_1.terminateGroupConfirmed)(ref, grace);
+        if (!confirmed)
+            throw new Error(`no se pudo confirmar la terminación de la generación ${gen.n} del plan antes de integrar (C7)`);
+    }
+    gen.state = 'terminated';
+    (0, store_1.writeJournal)(planRoot, branch, s);
+    (0, store_1.appendEvent)(planRoot, branch, { kind: 'plan-generation-stopped', n: gen.n });
+}