agentic-workflow-manager 6.2.1 → 6.4.0

package/dist/src/commands/watch/supervisor.js

@@ -10,10 +10,91 @@ const fingerprint_1 = require("../../core/journal/fingerprint");
 const adapter_1 = require("../../core/journal/adapter");
 const process_1 = require("../../core/journal/process");
 const gate_1 = require("../job/gate");
+const git_1 = require("../../core/tracks/git");
 const lock_1 = require("./lock");
 const apply_1 = require("./apply");
 const runner_1 = require("./runner");
+const tracks_1 = require("./tracks");
 const generations_1 = require("./generations");
+/** R7/C3/C4 (Task 12) + fix post-review #2 (re-derivado desde cero tras
+ *  encontrar que la justificación original no probaba lo que decía — ver
+ *  finding 1 del segundo round de re-review): fases de `CohortPhase` en las
+ *  que una cohorte de tracks todavía puede "ganarle la carrera" a su propio
+ *  `run-final-interlock`, es decir donde el `computeGate` GENÉRICO de este
+ *  mismo `tick()` (línea de abajo, calculado DESPUÉS de `runnerTick`) puede
+ *  certificar pass antes de que `reconcileTracks` (que corrió ANTES de
+ *  `runnerTick`, arriba en este mismo `tick()`) haya tenido chance de
+ *  observar ese mismo resultado y mover `cohortPhase` a `COMPLETE`.
+ *
+ *  Cadena causal EXACTA, trazada contra `protocol.ts`/`tracks.ts`/`apply.ts`:
+ *    1. `nextProtocolEffect` (protocol.ts) solo emite `request-final-integration`
+ *       cuando `s.globalQaHeadSha !== undefined` — y ese campo se asigna
+ *       (`reconcileProtocol`, observación `global-qa-pass`) EN LA MISMA
+ *       transición que pone `cohortPhase = 'FINAL_INTEGRATION'`. No existe
+ *       ningún camino donde `request-final-integration` se emita con
+ *       `cohortPhase` todavía en `'ACTIVE'`/`'JOINING'`.
+ *    2. `runRequestFinalIntegration` (tracks.ts) es quien llama a `requestJob`
+ *       con `verificationKind: 'track-integration'` — el ÚNICO lugar que
+ *       pide el job canónico. Por (1), esto solo puede ocurrir con
+ *       `cohortPhase === 'FINAL_INTEGRATION'`.
+ *    3. `apply.ts::applyRequestToState` (rama `job-request`) es quien enlaza
+ *       `VerificationItem.satisfiedBy` — y lo hace a REQUEST time (job recién
+ *       creado en `executionState: 'received'`, o job "equivalente" ya en
+ *       vuelo), nunca esperando a que el job termine. Por (2), el primer
+ *       tick en que esto puede pasar ya tiene `cohortPhase === 'FINAL_INTEGRATION'`.
+ *    4. Cada tick corre COMO MÁXIMO una mutación de protocolo por invocación
+ *       de `reconcileTracks` (invariante propio de esa función, ver su
+ *       comment de cabecera) y esa invocación sucede ANTES de `runnerTick`
+ *       (que despacha/recolecta jobs) y ANTES del `computeGate` genérico de
+ *       abajo. Entonces: en el tick donde el job canónico recién enlazado
+ *       pasa a `verdict: 'pass'` (recolectado por `runnerTick`, que corre
+ *       DESPUÉS de que `reconcileTracks` ya intentó — y no pudo, porque el
+ *       job seguía vivo — avanzar el protocolo este mismo tick), el
+ *       `computeGate` genérico de abajo puede certificar `pass` con
+ *       `liveJobs === 0` mientras `cohortPhase` sigue en
+ *       `'FINAL_INTEGRATION'` (el job pasó, pero `finalIntegrationJobId`
+ *       todavía no se asignó — eso requiere la observación `integration-pass`,
+ *       que recién corre el PRÓXIMO tick). Esta es la primera fase en riesgo.
+ *    5. Una vez que ese próximo tick observa `integration-pass` y mueve
+ *       `cohortPhase` a `'FINAL_INTERLOCK'` (dentro de `reconcileTracks`,
+ *       otra vez ANTES del `computeGate` genérico de ESE tick), el gate
+ *       genérico sigue viendo el mismo job ya-pasado satisfaciendo el mismo
+ *       item — sigue en riesgo de certificar en ESE tick, con `cohortPhase`
+ *       todavía en `'FINAL_INTERLOCK'` (la transición real a `COMPLETE` la
+ *       hace `runRunFinalInterlock`, que corre recién el tick SIGUIENTE,
+ *       otra vez antes que el gate genérico de ese tick). Segunda y última
+ *       fase en riesgo.
+ *    6. Cuando `runRunFinalInterlock` sí corre y su propio `computeGate`
+ *       interno pasa, mueve `cohortPhase` a `'COMPLETE'` SINCRÓNICAMENTE
+ *       dentro de `reconcileTracks`, antes de que el gate genérico de ese
+ *       mismo tick se calcule — por eso `'COMPLETE'` nunca necesita estar en
+ *       este set (ya lo cubre `cohortDone` por igualdad directa).
+ *
+ *  Por (1)-(3): `'ACTIVE'`/`'JOINING'` NO califican. Más fuerte todavía:
+ *  `registerTrackIntegrationItems` (apply.ts) agrega cada `track-integration:*`
+ *  al `cycleVerificationPlan` SIN `satisfiedBy` en cuanto el track se declara
+ *  (mucho antes de `ACTIVE`/`JOINING`) — mientras al menos uno siga sin
+ *  `satisfiedBy`, `computeGate` (gate.ts) nunca puede dar `pass`, así que el
+ *  gate genérico es estructuralmente incapaz de certificar durante
+ *  `ACTIVE`/`JOINING`, con o sin este guard.
+ *  `'FINAL_QA'` tampoco califica — y no es solo "no está en riesgo", es
+ *  DEAD: se rastreó cada asignación a `cohortPhase` en `protocol.ts`
+ *  (`initialCohort`, `reconcileProtocol`, `observeProtocolEffect`) y ese
+ *  valor nunca se produce; queda en el tipo `CohortPhase` pero ninguna
+ *  transición real lo alcanza.
+ *  Quedan fuera por lo ya documentado en la versión anterior de este
+ *  comentario (verificado de nuevo, sigue siendo cierto): `'SERIAL'` (sin
+ *  camino de vuelta a COMPLETE, `nextProtocolEffect` devuelve `null`
+ *  incondicional), `'BLOCKED'` (lo maneja `enterCustody` aparte),
+ *  `'PREPARING'`/`'FALLBACK_PENDING'` (todavía no existe job canónico
+ *  enlazable) y `'COMPLETE'` (es el destino, no una fase "todavía corriendo").
+ *
+ *  Las ÚNICAS dos fases donde el job canónico ya puede estar enlazado
+ *  (`satisfiedBy` set) sin que la cohorte misma haya llegado a `COMPLETE`
+ *  son `'FINAL_INTEGRATION'` y `'FINAL_INTERLOCK'`. */
+const LIVE_COHORT_PHASES = new Set([
+    'FINAL_INTEGRATION', 'FINAL_INTERLOCK',
+]);
 exports.DEFAULT_SUPERVISOR_CONFIG = {
     provider: 'codex',
     heartbeatTimeoutMs: 5 * 60000, // R4.2 default 5 min
@@ -23,6 +104,7 @@ exports.DEFAULT_SUPERVISOR_CONFIG = {
     killGraceMs: 5000,
     reconcileGraceMs: 10000,
     jobStallObservationMs: 5 * 60000, // R3.5 default: mismo orden de magnitud que heartbeatTimeoutMs, concern independiente
+    maxParallelTracks: 1, // overridden en tiempo de ejecución con loadDefaultParallelism() (watch/index.ts)
 };
 const LIVE = ['received', 'spawn-intent', 'claimed', 'running', 'cancel-requested'];
 class Supervisor {
@@ -34,11 +116,13 @@ class Supervisor {
     relaunchNotBefore = 0;
     lastActivity = null;
     lastGenerationToken = null;
-    constructor(repoRoot, branch, cfg, spawner) {
+    trackRuntime;
+    constructor(repoRoot, branch, cfg, spawner, trackRuntime) {
         this.repoRoot = repoRoot;
         this.branch = branch;
         this.cfg = cfg;
         this.spawner = spawner;
+        this.trackRuntime = trackRuntime ?? (0, tracks_1.defaultTrackRuntime)(repoRoot, branch, { termGraceMs: cfg.termGraceMs, killGraceMs: cfg.killGraceMs });
     }
     fingerprintNow = (argv, paths, cwd) => {
         try {
@@ -74,13 +158,29 @@ class Supervisor {
         }
     }
     async tick() {
-        const before = (0, store_1.readJournal)(this.repoRoot, this.branch);
-        if (before.corrupt || before.state === null)
+        const before0 = (0, store_1.readJournal)(this.repoRoot, this.branch);
+        if (before0.corrupt || before0.state === null)
             throw new Error('journal corrupto: el supervisor no opera sobre corrupcion (R1.6)');
-        (0, lock_1.verifyBranchInvariant)(this.repoRoot, before.state.branch);
-        if (before.state.cycle.status === 'COMPLETE')
+        // R6.2/R6.8/C7 (Task 11): reconciliar un `MERGE_HEAD` abierto por un
+        // crash a mitad de un merge ANTES de cualquier guard general — hoy
+        // ningún guard existente (`verifyBranchInvariant` incluido) rechaza
+        // por `MERGE_HEAD`, pero esto corre primero de todos modos para que
+        // uno agregado en el futuro nunca pueda rechazar un estado ya
+        // reconciliable. `openJoin.handled` evita una SEGUNDA mutación real
+        // de tracks más abajo en este mismo tick (a lo sumo una por tick).
+        const openJoin = await (0, tracks_1.reconcileOpenJoin)(this.repoRoot, this.branch, before0.state, this.trackRuntime, this.cfg.maxParallelTracks);
+        const before = openJoin.state;
+        (0, lock_1.verifyBranchInvariant)(this.repoRoot, before.branch);
+        if (before.cycle.status === 'COMPLETE')
             return 'complete';
-        const pending = before.state?.cycle.nextAction;
+        // R5.2/R6.3 (Task 10): restart-safe — un track ya `frozen` (crash del
+        // loop DESPUÉS de persistir el paso 6 pero ANTES de que
+        // `runSupervisorLoop` liberara el lock/saliera) jamás debe relanzar
+        // un controller nuevo ni volver a despachar; simplemente reafirma el
+        // mismo resultado terminal.
+        if (before.frozen !== undefined)
+            return 'frozen';
+        const pending = before.cycle.nextAction;
         const resumePrompt = pending !== undefined ? `el next_action ${pending.actionId} del journal` : 'el plan del ciclo desde el journal';
         if (this.ensureController(resumePrompt) === 'custody')
             return 'custody';
@@ -89,37 +189,99 @@ class Supervisor {
             throw new Error('journal corrupto: el supervisor no opera sobre corrupcion (R1.6)');
         const gen = (0, generations_1.activeGeneration)(r0.state);
         (0, apply_1.consumePendingRequests)(this.repoRoot, this.branch, gen?.token ?? null);
+        // P1/P2 (R4.1-R4.10): a lo sumo un side effect de bootstrap de tracks
+        // por tick, ANTES de tocar jobs — mientras la cohorte está PREPARING,
+        // ningún job de track se despacha (eso lo maneja `runnerTick` con los
+        // `Job` ya existentes; el bootstrap de tracks es un canal separado).
+        // Task 11: si `reconcileOpenJoin` ya ejecutó una mutación real este
+        // mismo tick (reconcilió un `MERGE_HEAD` abierto), no se vuelve a
+        // invocar `reconcileTracks` acá — a lo sumo una mutación real de
+        // tracks por tick, mismo invariante que ya sostenía `reconcileTracks`
+        // por sí solo antes de que existiera esta ruta temprana.
+        if (!openJoin.handled) {
+            const preTracks = (0, store_1.readJournal)(this.repoRoot, this.branch);
+            if (!preTracks.corrupt && preTracks.state !== null) {
+                // Task 9: `reconcileTracks` es `async` desde que `begin-teardown`
+                // puede terminar el grupo del supervisor de un track con
+                // `terminatePreviouslyOwnedGroup` (espera real de gracia,
+                // R4.8) — awaitear acá es obligatorio, nunca fire-and-forget.
+                await (0, tracks_1.reconcileTracks)(this.repoRoot, this.branch, preTracks.state, this.trackRuntime, this.cfg.maxParallelTracks);
+            }
+        }
         const afterRequests = (0, store_1.readJournal)(this.repoRoot, this.branch);
-        if (afterRequests.state !== null && (0, generations_1.activeGeneration)(afterRequests.state) === undefined
+        // R7/C3 (Task 12): mientras la cohorte corre el job canónico de
+        // integración final o espera el interlock, NADIE debe relanzar el
+        // controller — `runRequestFinalIntegration`/`runRunFinalInterlock`
+        // (watch/tracks.ts) ya pausaron esa generación explícitamente
+        // (R7.3/C3) precisamente para que el árbol quede quieto durante esa
+        // ventana; sin este guard, esta misma rama la revivía en el mismo
+        // tick (o el siguiente) apenas la generación quedaba `terminated`,
+        // exactamente la mutación concurrente que la pausa buscaba evitar.
+        const finalizing = afterRequests.state?.cohortPhase === 'FINAL_INTEGRATION' || afterRequests.state?.cohortPhase === 'FINAL_INTERLOCK';
+        if (!finalizing && afterRequests.state !== null && (0, generations_1.activeGeneration)(afterRequests.state) === undefined
             && afterRequests.state.generations.length > 0 && afterRequests.state.cycle.status === 'IN_PROGRESS') {
             (0, generations_1.beginGeneration)(this.repoRoot, this.branch);
             if (this.ensureController(resumePrompt) === 'custody')
                 return 'custody';
         }
-        (0, runner_1.runnerTick)(this.repoRoot, this.branch, this.spawner, { reconcileGraceMs: this.cfg.reconcileGraceMs, stallObservationMs: this.cfg.jobStallObservationMs });
+        // R5.2/R6.3 (Task 10): recién leído tras `consumePendingRequests` —
+        // si el request `track-freeze-request` llegó en ESTE tick, `apply.ts`
+        // ya lo tradujo a `freezeRequested`. `dispatch:false` corta SOLO el
+        // arranque de trabajo NUEVO; el drenaje de lo ya vivo sigue intacto
+        // (paso 2 del freeze — "consume/reconcilia jobs existentes").
+        const freezeCheck = (0, store_1.readJournal)(this.repoRoot, this.branch);
+        const freezing = !freezeCheck.corrupt && freezeCheck.state !== null
+            && freezeCheck.state.freezeRequested === true && freezeCheck.state.frozen === undefined;
+        (0, runner_1.runnerTick)(this.repoRoot, this.branch, this.spawner, {
+            reconcileGraceMs: this.cfg.reconcileGraceMs, stallObservationMs: this.cfg.jobStallObservationMs, dispatch: !freezing,
+        });
         const custody = await this.superviseController();
         if (custody)
             return 'custody';
+        if (freezing)
+            return this.attemptFreeze();
         const r = (0, store_1.readJournal)(this.repoRoot, this.branch);
         const gate = (0, gate_1.computeGate)(r.state, r.corrupt, this.fingerprintNow);
         const liveJobs = r.state === null ? 1 : Object.values(r.state.jobs).filter((j) => LIVE.includes(j.executionState)).length;
-        if (gate.pass && liveJobs === 0) { // gate verde YA implica cero vivos; doble cinturon (R4.5)
+        // R7/C3/C4 (Task 12): un journal de PLAN con cohorte de tracks NUNCA
+        // declara `cycle.status = COMPLETE` por este camino genérico mientras
+        // la cohorte no llegó ELLA MISMA a `cohortPhase === 'COMPLETE'` — sin
+        // este guard, `computeGate` certifica en cuanto el job canónico de
+        // integración se REQUIERE (apply.ts enlaza `satisfiedBy` al crear el
+        // job, antes de que termine) y pasa, ganándole la carrera al propio
+        // `run-final-interlock` (watch/tracks.ts): el ciclo se declararía
+        // COMPLETE mientras `cohortPhase` sigue en FINAL_INTEGRATION/
+        // FINAL_INTERLOCK, los tracks nunca llegan a JOINED y
+        // `integration.lock` queda retenido para siempre (este mismo check,
+        // arriba en `tick()`, corta el loop apenas ve `cycle.status ===
+        // COMPLETE` y jamás vuelve a llamar `reconcileTracks`).
+        //
+        // Fix post-review: la primera versión de este guard usaba
+        // `(tracks?.length ?? 0) >= 2` como único criterio de "gobernada" —
+        // pero el array `tracks` NUNCA se vacía ni se acorta cuando la
+        // cohorte cae a fallback SERIAL (Task 9: los tracks quedan
+        // `REMOVED`/`DECLARED` en el array, ver `track-bootstrap-crash.test.ts`),
+        // y `protocol.ts` no tiene (ni debe inventarse acá — single-authority)
+        // ningún camino de SERIAL de vuelta a COMPLETE. Con el criterio viejo,
+        // CUALQUIER plan cuya cohorte degradara a SERIAL quedaba
+        // PERMANENTEMENTE incapaz de completar su ciclo por este único lugar
+        // del código que fija `cycle.status = 'COMPLETE'`. El criterio
+        // correcto no es "¿existe un array de tracks?" sino "¿está la
+        // cohorte, AHORA MISMO, en una fase viva del ciclo de vida paralelo
+        // que todavía podría adelantarse a su propio interlock?"
+        // (`LIVE_COHORT_PHASES`, arriba). Una cohorte en SERIAL, BLOCKED,
+        // PREPARING o FALLBACK_PENDING — o un journal sin cohorte real — sigue
+        // el camino de siempre, sin cambios, igual que si nunca hubiera
+        // tenido tracks.
+        const cohortGoverned = r.state !== null && (r.state.tracks?.length ?? 0) >= 2
+            && r.state.cohortPhase !== undefined && LIVE_COHORT_PHASES.has(r.state.cohortPhase);
+        const cohortDone = !cohortGoverned || r.state.cohortPhase === 'COMPLETE';
+        if (gate.pass && liveJobs === 0 && cohortDone) { // gate verde YA implica cero vivos; doble cinturon (R4.5)
             const s = r.state;
-            for (const generation of s.generations) {
-                for (const ref of [generation.processRef, generation.wrapperRef]) {
-                    // Los tests pueden ejecutar el wrapper in-process; nunca
-                    // enviar una senial al propio supervisor.
-                    if (ref?.pid === process.pid)
-                        continue;
-                    if (ref === undefined || (0, process_1.groupIsGone)(ref.processGroup))
-                        continue;
-                    const confirmed = await (0, process_1.terminateGroupConfirmed)(ref, { termGraceMs: this.cfg.termGraceMs, killGraceMs: this.cfg.killGraceMs });
-                    if (!confirmed) {
-                        (0, generations_1.enterCustody)(this.repoRoot, this.branch, `no se pudo terminar con identidad confirmada la generacion ${generation.n} antes de COMPLETE`);
-                        return 'custody';
-                    }
-                }
-                generation.state = 'terminated';
+            const terminated = await this.terminateAllGenerationsConfirmed(s);
+            if (!terminated.ok) {
+                (0, generations_1.enterCustody)(this.repoRoot, this.branch, `no se pudo terminar con identidad confirmada la generacion ${terminated.n} antes de COMPLETE`);
+                return 'custody';
             }
             s.cycle.status = 'COMPLETE';
             s.cycle.completedAt = new Date().toISOString();
@@ -129,6 +291,65 @@ class Supervisor {
         }
         return 'continue';
     }
+    /** Termina, con identidad CONFIRMADA (jamás un `kill(pid)` crudo), toda
+     *  generación de `s` que todavía tenga un `processRef`/`wrapperRef` vivo
+     *  — muta `s` en memoria (incluye marcar `state = 'terminated'`) pero
+     *  JAMÁS persiste por sí sola: el caller combina esta mutación con la
+     *  suya propia (`cycle.status = 'COMPLETE'` o `frozen = {...}`) en UN
+     *  solo `writeJournal` (R1.3 — dos escrituras secuenciales sobre el
+     *  mismo objeto violarían el CAS por revisión de `writeJournal`).
+     *  Compartida entre el camino COMPLETE y el camino FROZEN (Task 10): el
+     *  mismo requisito ("ningún controller administrado sigue vivo") aplica
+     *  a ambos. */
+    async terminateAllGenerationsConfirmed(s) {
+        for (const generation of s.generations) {
+            for (const ref of [generation.processRef, generation.wrapperRef]) {
+                // Los tests pueden ejecutar el wrapper in-process; nunca
+                // enviar una senial al propio supervisor.
+                if (ref?.pid === process.pid)
+                    continue;
+                if (ref === undefined || (0, process_1.groupIsGone)(ref.processGroup))
+                    continue;
+                const confirmed = await (0, process_1.terminateGroupConfirmed)(ref, { termGraceMs: this.cfg.termGraceMs, killGraceMs: this.cfg.killGraceMs });
+                if (!confirmed)
+                    return { ok: false, n: generation.n };
+            }
+            generation.state = 'terminated';
+        }
+        return { ok: true };
+    }
+    /** Paso 2-6 del freeze (R5.2/R6.3, Task 10 — paso 1 "deja de despachar"
+     *  ya lo hizo `dispatch:false` en `runnerTick`, arriba en `tick()`):
+     *  fail-closed en cada paso — cualquier hecho todavía no demostrable
+     *  simplemente pospone (`'continue'`, el próximo tick reintenta), JAMÁS
+     *  fuerza `frozen` sobre evidencia incompleta. Solo cuando los 4 hechos
+     *  restantes (cero vivos, gate local verde, worktree/index limpios,
+     *  generación propia terminada CONFIRMADA) son TODOS demostrables se
+     *  persiste `frozenHeadSha` + el marcador `frozen` — en el MISMO
+     *  `writeJournal` que la terminación de generación de arriba. */
+    async attemptFreeze() {
+        const r = (0, store_1.readJournal)(this.repoRoot, this.branch);
+        if (r.corrupt || r.state === null)
+            throw new Error('journal corrupto: el supervisor no opera sobre corrupcion (R1.6)');
+        const s = r.state;
+        const liveJobs = Object.values(s.jobs).filter((j) => LIVE.includes(j.executionState)).length;
+        if (liveJobs > 0)
+            return 'continue'; // paso 2: drenando todavía
+        const gate = (0, gate_1.computeTrackGate)(s, false, this.fingerprintNow);
+        if (!gate.pass)
+            return 'continue'; // paso 3: gate local todavía rojo
+        if (!(0, git_1.isWorktreeClean)(this.repoRoot))
+            return 'continue'; // paso 4: worktree/index todavía sucios
+        const terminated = await this.terminateAllGenerationsConfirmed(s); // paso 5
+        if (!terminated.ok) {
+            (0, generations_1.enterCustody)(this.repoRoot, this.branch, `no se pudo terminar con identidad confirmada la generacion ${terminated.n} antes de FROZEN (R5.2/R6.3)`);
+            return 'custody';
+        }
+        s.frozen = { headSha: (0, git_1.headSha)(this.repoRoot), at: new Date().toISOString() }; // paso 4/6: SHA congelado, durable
+        (0, store_1.writeJournal)(this.repoRoot, this.branch, s);
+        (0, store_1.appendEvent)(this.repoRoot, this.branch, { kind: 'track-frozen', headSha: s.frozen.headSha });
+        return 'frozen'; // paso 6 ("libera el lock y sale"): runSupervisorLoop trata 'frozen' igual que 'complete'
+    }
     /** true => custodia (el caller NO libera lock ni sale). */
     async superviseController() {
         const r = (0, store_1.readJournal)(this.repoRoot, this.branch);
@@ -194,7 +415,7 @@ exports.Supervisor = Supervisor;
 /** Foreground, visible, terminable (R2.4): sin daemons. SIGINT/SIGTERM libera
  *  el lock y sale; COMPLETE => auto-exit liberando lock y terminando la
  *  generacion propia (cero huerfanos). */
-async function runSupervisorLoop(repoRoot, branch, cfg, spawner = (0, runner_1.defaultWrapperSpawner)()) {
+async function runSupervisorLoop(repoRoot, branch, cfg, spawner = (0, runner_1.defaultWrapperSpawner)(), trackRuntime) {
     const r = (0, store_1.readJournal)(repoRoot, branch);
     if (r.corrupt || r.state === null)
         throw new Error('journal ausente o corrupto: corre `awm watch --init` primero');
@@ -208,7 +429,7 @@ async function runSupervisorLoop(repoRoot, branch, cfg, spawner = (0, runner_1.d
     const onSignal = () => { shutdownRequested = true; wakeSleep?.(); };
     process.on('SIGINT', onSignal);
     process.on('SIGTERM', onSignal);
-    const sup = new Supervisor(repoRoot, branch, cfg, spawner);
+    const sup = new Supervisor(repoRoot, branch, cfg, spawner, trackRuntime);
     try {
         const s0 = (0, store_1.readJournal)(repoRoot, branch).state;
         if ((0, generations_1.activeGeneration)(s0) === undefined) {
@@ -218,7 +439,10 @@ async function runSupervisorLoop(repoRoot, branch, cfg, spawner = (0, runner_1.d
             if (shutdownRequested)
                 break;
             const out = await sup.tick();
-            if (out === 'complete')
+            // 'frozen' (Task 10): mismo camino de salida que 'complete' —
+            // drenar ownership y liberar el lock, el track ya cumplió su
+            // freeze y no debe seguir despachando ni corriendo su loop.
+            if (out === 'complete' || out === 'frozen')
                 break;
             // 'custody': NO liberar lock, NO salir — seguir auditando (R4.5)
             await new Promise((resolve) => {

package/dist/src/commands/watch/teardown-driver.js

@@ -0,0 +1,189 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runBeginTeardown = runBeginTeardown;
+// Task 13 (R4.2/R4.3/R4.6/R4.10/C2/C9): extraído de `tracks.ts` (post-review
+// de Task 13 — el archivo venía creciendo dos ciclos consecutivos de review
+// hacia "actively harming reviewability") — mismo criterio que `join.ts` con
+// `decideJoinReconciliation`/`acquireIntegrationLock`: la lógica de
+// gathering + driver de UN concern vive en su propio módulo, `tracks.ts`
+// sigue siendo el ÚNICO lugar con la orquestación (`reconcileTracks`,
+// `executeRuntimeEffect`'s dispatch table) y el wiring de producción
+// (`defaultTrackRuntime`). Esto es una extracción puramente MECÁNICA: cero
+// cambio de comportamiento, `decideTeardown` sigue viviendo exclusivamente en
+// `protocol.ts` (autoridad única, sin tocar).
+const fs_1 = __importDefault(require("fs"));
+const paths_1 = require("../../core/journal/paths");
+const process_1 = require("../../core/journal/process");
+const protocol_1 = require("../../core/tracks/protocol");
+const git_1 = require("../../core/tracks/git");
+const teardown_1 = require("../../core/tracks/teardown");
+const store_1 = require("../../core/journal/store");
+const tracks_1 = require("./tracks");
+/** Task 13 (R4.2/R4.3/R4.6/R4.10/C2/C9): gathering READ-ONLY del estado real
+ *  de UN track en teardown — jamás cuenta como el side effect del tick
+ *  (mismo criterio que `ownedWorktreeExists`/`foreignPathExists` en
+ *  `runCreateWorktree`). Solo reúne los campos que la fase ACTUAL necesita
+ *  (`decideTeardown` ignora el resto): `ownSupervisorAlive` en
+ *  `TEARDOWN_INTENT`, `ownedWorktreeExists`/`foreignWorktree` en
+ *  `SUPERVISOR_STOPPED`, `ownedBranchExists` en `WORKTREE_REMOVED`.
+ *  `foreignSupervisor` deliberadamente nunca se produce acá: `refIsAlive`
+ *  compara identidad completa (pid+startTime+pgid+argsDigest), así que un
+ *  PID reciclado por otro proceso ya se reporta como "nuestro está muerto"
+ *  (`ownSupervisorAlive: false`), nunca como "ajeno" — el campo existe en
+ *  `TeardownObservation`/`decideTeardown` para la matriz pura y como defensa
+ *  fail-closed, mismo criterio que `begin-fallback` en `decidePrepare`
+ *  (nunca seleccionado por el driver real, pero cubierto por la autoridad
+ *  única igual). */
+function gatherTeardownObservation(planRoot, s, ref) {
+    if (ref.phase === 'TEARDOWN_INTENT') {
+        // Step 4 del plan: "supervisor propio muerto confirmado Y lock
+        // ausente" — un proceso identity-verified muerto que dejó su lock
+        // advisory sin liberar (crash a mitad de su propia salida, mismo
+        // riesgo que `runFreezeTrack` ya trata con `supervisorAlive ||
+        // lockExists`) todavía no prueba que sea seguro tocar el worktree.
+        // `ownSupervisorAlive: true` acá simplemente reintenta
+        // `stop-own-supervisor` en el próximo tick — inofensivo si el
+        // proceso ya está muerto (`groupIsGone` ya es `true`, no-op real),
+        // fail-closed si el lock sigue de verdad retenido.
+        const processAlive = ref.supervisorProcessRef !== undefined && (0, process_1.refIsAlive)(ref.supervisorProcessRef);
+        // `supervisorLockPath` exige un directorio real (`fs.realpathSync`)
+        // — un track abandonado ANTES de que su worktree llegara a existir
+        // (ej. `create-worktree` falló para el track siguiente, R4.5) nunca
+        // tuvo dónde escribir un lock: ausencia de directorio = ausencia de
+        // lock, nunca "indemostrable".
+        const lockExists = fs_1.default.existsSync(ref.worktreePath) && fs_1.default.existsSync((0, paths_1.supervisorLockPath)(ref.worktreePath));
+        return { ownSupervisorAlive: processAlive || lockExists };
+    }
+    if (ref.phase === 'SUPERVISOR_STOPPED') {
+        if (!fs_1.default.existsSync(ref.worktreePath))
+            return { ownedWorktreeExists: false };
+        if ((0, teardown_1.worktreeOwnershipProven)(planRoot, ref, s.journalId))
+            return { ownedWorktreeExists: true };
+        // Existe, pero no se pudo probar que es nuestro (R4.6/R4.10): jamás
+        // se adopta ni se borra a ciegas — bloquea en vez de saltear.
+        return { foreignWorktree: true };
+    }
+    if (ref.phase === 'WORKTREE_REMOVED') {
+        return { ownedBranchExists: (0, git_1.branchExists)(planRoot, ref.branch) };
+    }
+    return {};
+}
+/** Task 13 (R4.2/R4.3/R4.6/R4.10/C2/C9): reemplaza el `teardownOwned(ref,
+ *  step)` TEMPORAL de Task 9 por el state machine completo de
+ *  `decideTeardown` (`protocol.ts`, autoridad única) — a lo sumo UN efecto
+ *  real por invocación, siempre persistido a través de `observeProtocolEffect`
+ *  (nunca un `withRef` directo con una fase inventada acá, salvo para el
+ *  snapshot no-decisional de `teardownIntent`), mismo criterio "gather ->
+ *  decide -> tocar el mundo real como mucho una vez -> persistir -> stop"
+ *  que `runCreateWorktree`/`runFreezeTrack`/`runMergeTrack`.
+ *
+ *  Cada llamada a `decideTeardown` ocurre sobre la observación YA reunida
+ *  (`observed`, antes de cualquier efecto): las decisiones "ya resuelto"
+ *  (`accept-supervisor-stopped`, `mark-removed`, `block-foreign`) no
+ *  necesitan tocar `runtime` — la observación existente alcanza para
+ *  persistir el avance. Las decisiones "falta trabajo real"
+ *  (`stop-own-supervisor`, `remove-owned-worktree`, `remove-owned-branch`)
+ *  ejecutan EXACTAMENTE un efecto y vuelven a observar el mundo real después,
+ *  persistiendo esa observación fresca — es `reconcileProtocol` quien, sobre
+ *  ESA observación, vuelve a llamar `decideTeardown` para fijar la fase
+ *  resultante (mismo patrón exacto que `runMergeTrack` con
+ *  `decideJoinReconciliation`, T11: nunca se confía en que el efecto en sí
+ *  haya funcionado, la relectura es la única fuente de verdad). */
+async function runBeginTeardown(planRoot, branch, s, protocol, effect, runtime) {
+    const trackId = effect.trackId;
+    const ref = (0, tracks_1.refOf)(s, trackId);
+    const observed = gatherTeardownObservation(planRoot, s, ref);
+    const decision = (0, protocol_1.decideTeardown)(protocol.tracks[trackId], observed);
+    if (decision === 'persist-intent') {
+        // Único paso que además de la fase (`EFFECT_APPLIED_PHASE` ya mapea
+        // `begin-teardown` -> `TEARDOWN_INTENT`) captura el snapshot durable
+        // que Step 4 exige para probar ownership del worktree más adelante —
+        // dato del journal, no del protocolo puro, así que se aplica con
+        // `withRef` en la MISMA persistencia (una sola frontera, no dos).
+        const applied = (0, protocol_1.observeProtocolEffect)(protocol, effect, { kind: 'effect-applied', effect });
+        const withIntent = (0, tracks_1.withRef)((0, tracks_1.applyProtocolToState)(s, applied), trackId, {
+            teardownIntent: { worktreePath: ref.worktreePath, branch: ref.branch, supervisorNonce: ref.supervisorProcessRef?.spawnNonce },
+        });
+        const next = (0, tracks_1.persist)(planRoot, branch, withIntent);
+        (0, store_1.appendEvent)(planRoot, branch, { kind: 'track-teardown-step', trackId, step: 'TEARDOWN_INTENT' });
+        return { state: next, stop: true, executed: effect.kind };
+    }
+    if (decision === 'block-foreign') {
+        const blocked = (0, protocol_1.observeProtocolEffect)(protocol, effect, { kind: 'teardown-observation', trackId, ...observed });
+        const next = (0, tracks_1.persist)(planRoot, branch, (0, tracks_1.applyProtocolToState)(s, blocked));
+        (0, store_1.appendEvent)(planRoot, branch, {
+            kind: 'track-blocked', trackId,
+            reason: observed.foreignSupervisor ? 'identidad de supervisor ajena' : 'worktree preexistente ajeno',
+        });
+        return { state: next, stop: true, executed: null };
+    }
+    if (decision === 'accept-supervisor-stopped' || decision === 'mark-removed') {
+        // Ya resuelto por la observación reunida — ningún touch nuevo de
+        // `runtime` este tick (mismo criterio que 'accept-worktree' en
+        // `runCreateWorktree`).
+        const applied = (0, protocol_1.observeProtocolEffect)(protocol, effect, { kind: 'teardown-observation', trackId, ...observed });
+        const next = (0, tracks_1.persist)(planRoot, branch, (0, tracks_1.applyProtocolToState)(s, applied));
+        (0, store_1.appendEvent)(planRoot, branch, { kind: 'track-teardown-step', trackId, step: (0, tracks_1.refOf)(next, trackId).phase });
+        return { state: next, stop: true, executed: effect.kind };
+    }
+    if (decision === 'stop-own-supervisor') {
+        // R4.8: identity-verified — jamás un `kill(pid)` crudo. `true` <=>
+        // grupo confirmado ausente (recién ahora, o ya lo estaba).
+        const confirmed = await runtime.stopOwnSupervisor(ref);
+        const after = { ownSupervisorAlive: !confirmed };
+        const applied = (0, protocol_1.observeProtocolEffect)(protocol, effect, { kind: 'teardown-observation', trackId, ...after });
+        const next = (0, tracks_1.persist)(planRoot, branch, (0, tracks_1.applyProtocolToState)(s, applied));
+        (0, store_1.appendEvent)(planRoot, branch, { kind: 'track-teardown-step', trackId, step: confirmed ? 'SUPERVISOR_STOPPED' : 'TEARDOWN_INTENT' });
+        return { state: next, stop: true, executed: effect.kind };
+    }
+    if (decision === 'remove-owned-worktree') {
+        // Ownership YA probado por `gatherTeardownObservation`
+        // (`worktreeOwnershipProven`) para que `decideTeardown` llegara acá —
+        // lo único que falta es el efecto real (`git.ts` aplica el guard de
+        // limpieza, bloqueando si está sucio, y nunca usa `--force`).
+        try {
+            runtime.removeOwnedWorktree(planRoot, ref);
+        }
+        catch (error) {
+            const failed = (0, protocol_1.observeProtocolEffect)(protocol, effect, { kind: 'effect-failed', trackId, effect: effect.kind, detail: error.message });
+            const next = (0, tracks_1.persist)(planRoot, branch, (0, tracks_1.applyProtocolToState)(s, failed));
+            (0, store_1.appendEvent)(planRoot, branch, { kind: 'track-effect-failed', trackId, effect: effect.kind, detail: error.message });
+            return { state: next, stop: true, executed: effect.kind };
+        }
+        const applied = (0, protocol_1.observeProtocolEffect)(protocol, effect, { kind: 'teardown-observation', trackId, ownedWorktreeExists: false });
+        const next = (0, tracks_1.persist)(planRoot, branch, (0, tracks_1.applyProtocolToState)(s, applied));
+        (0, store_1.appendEvent)(planRoot, branch, { kind: 'track-teardown-step', trackId, step: 'WORKTREE_REMOVED' });
+        return { state: next, stop: true, executed: effect.kind };
+    }
+    // decision === 'remove-owned-branch': dos fases de origen posibles
+    // (mismo valor de decisión, mismo criterio de dualidad que el resto de
+    // esta interfaz — ver el comentario de `decideTeardown`).
+    if (ref.phase === 'SUPERVISOR_STOPPED') {
+        // Sin worktree propio que remover (nunca existió, o ya se quitó en
+        // un intento previo que crasheó antes de persistir esto): avance
+        // puramente mecánico a `WORKTREE_REMOVED`, sin tocar `runtime` — el
+        // próximo tick, ya en esa fase, decide la branch de nuevo con una
+        // observación fresca.
+        const applied = (0, protocol_1.observeProtocolEffect)(protocol, effect, { kind: 'teardown-observation', trackId, ownedWorktreeExists: false });
+        const next = (0, tracks_1.persist)(planRoot, branch, (0, tracks_1.applyProtocolToState)(s, applied));
+        (0, store_1.appendEvent)(planRoot, branch, { kind: 'track-teardown-step', trackId, step: 'WORKTREE_REMOVED' });
+        return { state: next, stop: true, executed: effect.kind };
+    }
+    // ref.phase === 'WORKTREE_REMOVED': la branch existe de verdad, efecto real.
+    try {
+        runtime.removeOwnedBranch(planRoot, ref.branch);
+    }
+    catch (error) {
+        const failed = (0, protocol_1.observeProtocolEffect)(protocol, effect, { kind: 'effect-failed', trackId, effect: effect.kind, detail: error.message });
+        const next = (0, tracks_1.persist)(planRoot, branch, (0, tracks_1.applyProtocolToState)(s, failed));
+        (0, store_1.appendEvent)(planRoot, branch, { kind: 'track-effect-failed', trackId, effect: effect.kind, detail: error.message });
+        return { state: next, stop: true, executed: effect.kind };
+    }
+    const applied = (0, protocol_1.observeProtocolEffect)(protocol, effect, { kind: 'teardown-observation', trackId, ownedBranchExists: false });
+    const next = (0, tracks_1.persist)(planRoot, branch, (0, tracks_1.applyProtocolToState)(s, applied));
+    (0, store_1.appendEvent)(planRoot, branch, { kind: 'track-teardown-step', trackId, step: 'BRANCH_REMOVED' });
+    return { state: next, stop: true, executed: effect.kind };
+}