agentic-workflow-manager 6.2.0 → 6.3.0

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

@@ -0,0 +1,85 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveDefaultParallelism = deriveDefaultParallelism;
+exports.parseMaxParallel = parseMaxParallel;
+exports.scheduleTracks = scheduleTracks;
+exports.loadDefaultParallelism = loadDefaultParallelism;
+// R10.2/R10.3: tope de paralelismo derivado de una medición real (fingerprint
+// budget, ver docs/research/r5/benchmark-fingerprint.mjs), nunca de un número
+// escrito a mano. Funciones puras/testeables — sin I/O aquí salvo
+// loadDefaultParallelism, que es un loader delgado sobre el artefacto
+// empaquetado y cae a serial (1) si no lo puede resolver (nunca crashea `awm watch`).
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+/** R10.3: el mayor N de supervisores concurrentes cuyo p95 medido no supera
+ *  1.5x el baseline serial (N=1) ni el 20% del tick — nunca N=1 si ninguna
+ *  medición lo habilita (R10.2, fail-closed hacia serial). */
+function deriveDefaultParallelism(budget) {
+    if (!Number.isInteger(budget.cpuCount) || budget.cpuCount < 1 || budget.samples.length === 0)
+        throw new Error('budget inválido');
+    const baseline = budget.samples.find((s) => s.supervisors === 1);
+    if (baseline === undefined || baseline.p95Ms <= 0)
+        throw new Error('budget sin baseline N=1');
+    return budget.samples
+        .filter((s) => Number.isInteger(s.supervisors) && s.supervisors <= budget.cpuCount
+        && s.p95Ms <= baseline.p95Ms * 1.5 && s.p95Ms <= budget.tickMs * 0.2)
+        .reduce((max, s) => Math.max(max, s.supervisors), 1);
+}
+/** Parsea `--max-parallel <n>`, mismo estilo de validación que `minutes()` en
+ *  watch/index.ts: entero >= 1, fail-closed en cualquier otro caso. */
+function parseMaxParallel(raw) {
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n < 1)
+        throw new Error('--max-parallel requiere un entero >= 1');
+    return n;
+}
+/** Todos los tracks alcanzan ARMED; solo hasta `maxParallel` (menos los ya
+ *  activos) pasan a arrancar. El resto queda `waiting` — el wrapper excedente
+ *  espera sin arrancar su loop de watch/fingerprint hasta que un slot libere. */
+function scheduleTracks(tracks, active, maxParallel) {
+    if (!Number.isInteger(maxParallel) || maxParallel < 1)
+        throw new Error('maxParallel debe ser entero >= 1');
+    const capacity = Math.max(0, maxParallel - active.size);
+    const candidates = tracks.filter((t) => !active.has(t));
+    return { start: candidates.slice(0, capacity), waiting: candidates.slice(capacity) };
+}
+/** Busca `docs/research/r5/fingerprint-budget.json` subiendo desde `startDir`
+ *  (por defecto este archivo), sin asumir una profundidad fija de directorios.
+ *  `startDir` es parametrizable solo para poder testear los caminos de fallo
+ *  de `loadDefaultParallelism` con un árbol de directorios controlado —
+ *  ver docs/research/r5/benchmark-fingerprint.mjs para el estado real de
+ *  distribución de este artefacto (hoy NO viaja en el npm publish). */
+function findBudgetArtifact(startDir) {
+    let dir = startDir;
+    for (let i = 0; i < 8; i += 1) {
+        const candidate = path_1.default.join(dir, 'docs', 'research', 'r5', 'fingerprint-budget.json');
+        if (fs_1.default.existsSync(candidate))
+            return candidate;
+        const parent = path_1.default.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+/** `derivedDefault` del artefacto, si se puede resolver y es válido. Si el
+ *  artefacto no resuelve, tiene JSON corrupto, o `derivedDefault` falta / no
+ *  es entero / es < 1, cae a serial (1) — nunca crashea `awm watch` por esto.
+ *  `startDir` default = este archivo; solo se sobreescribe en tests. */
+function loadDefaultParallelism(startDir = __dirname) {
+    const artifactPath = findBudgetArtifact(startDir);
+    if (artifactPath === null)
+        return 1;
+    try {
+        const data = JSON.parse(fs_1.default.readFileSync(artifactPath, 'utf8'));
+        if (Number.isInteger(data.derivedDefault) && data.derivedDefault >= 1)
+            return data.derivedDefault;
+        return 1;
+    }
+    catch {
+        return 1;
+    }
+}

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;
+}