agentic-workflow-manager 3.4.0 → 3.5.0

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

@@ -0,0 +1,249 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Backoff = void 0;
+exports.decideStall = decideStall;
+exports.activeGeneration = activeGeneration;
+exports.beginGeneration = beginGeneration;
+exports.launchControllerGeneration = launchControllerGeneration;
+exports.collectControllerGeneration = collectControllerGeneration;
+exports.controllerGenerationHasUnresolvedClaim = controllerGenerationHasUnresolvedClaim;
+exports.ensureControllerGeneration = ensureControllerGeneration;
+exports.enterCustody = enterCustody;
+exports.resolveGeneration = resolveGeneration;
+// State machine de generaciones (R4.2/R4.2b/R4.3): el silencio NUNCA autoriza
+// kill; custodia BLOCKED conserva lock y ownership (el loop de supervisor.ts
+// sigue vivo auditando — jamas sale dejando un vivo sin duenio).
+const crypto_1 = __importDefault(require("crypto"));
+const fs_1 = __importDefault(require("fs"));
+const store_1 = require("../../core/journal/store");
+const process_1 = require("../../core/journal/process");
+const adapter_1 = require("../../core/journal/adapter");
+const paths_1 = require("../../core/journal/paths");
+const exec_wrapper_1 = require("../job/exec-wrapper");
+const runner_1 = require("./runner");
+const types_1 = require("../../core/journal/types");
+/** Lectura obligatoria del journal (patron repetido en todo este archivo):
+ *  el supervisor jamas opera sobre corrupcion (R1.6) — falla ruidoso, nunca
+ *  sigue con un estado indemostrable. */
+function requireState(repoRoot, branch) {
+    const r = (0, store_1.readJournal)(repoRoot, branch);
+    if (r.corrupt || r.state === null)
+        throw new Error('journal corrupto: el supervisor no opera sobre corrupcion (R1.6)');
+    return r.state;
+}
+/** Doble senial + senial positiva del adapter (design R4.2/R4.2b):
+ *  - solo heartbeat vencido => observar (suspected-stall), JAMAS matar;
+ *  - doble senial sin 'safe' del adapter => custodia BLOCKED sin matar;
+ *  - doble senial + 'safe' => recien ahi resolver la generacion. */
+function decideStall(signals, cfg) {
+    if (signals.heartbeatAgeMs < cfg.heartbeatTimeoutMs)
+        return 'healthy';
+    if (signals.activityFrozenMs < cfg.activityWindowMs)
+        return 'suspected-stall-observe';
+    if (signals.safeToReplace !== 'safe')
+        return 'custody-blocked';
+    return 'resolve-generation';
+}
+const BACKOFF_MS = [60000, 300000, 900000];
+const MAX_RELAUNCHES_PER_HOUR = 6;
+class Backoff {
+    idx = -1;
+    stamps = [];
+    nextMs() {
+        this.idx = Math.min(this.idx + 1, BACKOFF_MS.length - 1);
+        return BACKOFF_MS[this.idx];
+    }
+    reset() { this.idx = -1; }
+    recordRelaunch() { this.stamps.push(Date.now()); }
+    exhausted() {
+        const hourAgo = Date.now() - 3600000;
+        this.stamps = this.stamps.filter((t) => t > hourAgo);
+        return this.stamps.length >= MAX_RELAUNCHES_PER_HOUR;
+    }
+}
+exports.Backoff = Backoff;
+function activeGeneration(s) {
+    return s.generations.find((g) => g.state === 'active' || g.state === 'controller-suspected-stall');
+}
+/** Emite generacion N+1: toda anterior queda superseded (fencing). NO lanza el
+ *  proceso aqui — launchControllerGeneration lo hace con el adapter. */
+function beginGeneration(repoRoot, branch) {
+    const s = requireState(repoRoot, branch);
+    for (const g of s.generations) {
+        if (g.state === 'active' || g.state === 'controller-suspected-stall')
+            g.state = 'superseded';
+    }
+    const gen = {
+        n: s.generations.length + 1,
+        token: crypto_1.default.randomBytes(8).toString('hex'),
+        state: 'active', launchedAt: new Date().toISOString(),
+    };
+    s.generations.push(gen);
+    s.controllerHeartbeatAt = undefined; // el heartbeat pertenece al fencing token anterior
+    (0, store_1.writeJournal)(repoRoot, branch, s);
+    (0, store_1.appendEvent)(repoRoot, branch, { kind: 'generation-begun', n: gen.n });
+    return gen;
+}
+function promptForGeneration(gen) {
+    return `${gen.resumePrompt}\nGeneracion activa: ${gen.token}. Incluye --generation ${gen.token} en cada comando awm job.`;
+}
+/** Persiste el intent completo ANTES de delegarlo al wrapper. El wrapper usa
+ * claim exclusivo por (controllerJobId, spawnNonce), por lo que reemitir este
+ * mismo intent tras un crash nunca lanza dos controllers. */
+function launchControllerGeneration(repoRoot, branch, provider, resumePrompt, spawner = (0, runner_1.defaultWrapperSpawner)()) {
+    const s = requireState(repoRoot, branch);
+    const gen = activeGeneration(s);
+    if (gen === undefined)
+        throw new Error('no hay generacion activa para lanzar');
+    gen.controllerJobId = gen.controllerJobId ?? `controller-gen-${gen.n}`;
+    gen.spawnNonce = gen.spawnNonce ?? crypto_1.default.randomBytes(8).toString('hex');
+    gen.provider = gen.provider ?? provider;
+    gen.resumePrompt = gen.resumePrompt ?? resumePrompt;
+    (0, store_1.writeJournal)(repoRoot, branch, s);
+    const argv = (0, adapter_1.adapterFor)(gen.provider).launchArgv(promptForGeneration(gen));
+    const job = {
+        id: gen.controllerJobId, fingerprint: `generation:${gen.token}`, commandDigest: `generation:${gen.token}`,
+        argv, cwd: '.', paths: [], expandedPaths: [], executionState: 'spawn-intent',
+        observationState: 'progressing', spawnNonce: gen.spawnNonce,
+        phaseTimestamps: { 'spawn-intent': gen.launchedAt },
+    };
+    const wrapperRef = spawner(job, gen.spawnNonce, (0, paths_1.logsDir)(repoRoot, branch), repoRoot);
+    if (wrapperRef !== undefined) {
+        const afterSpawn = requireState(repoRoot, branch);
+        const same = afterSpawn.generations.find((candidate) => candidate.token === gen.token);
+        if (same !== undefined)
+            same.wrapperRef = wrapperRef;
+        (0, store_1.writeJournal)(repoRoot, branch, afterSpawn);
+    }
+    (0, store_1.appendEvent)(repoRoot, branch, { kind: 'generation-launch-requested', provider: gen.provider, n: gen.n });
+}
+/** Adopta la identidad que el wrapper externo persistio. Nunca inventa PID y
+ * valida que el sidecar corresponda exactamente al intent de la generacion. */
+function collectControllerGeneration(repoRoot, branch) {
+    const s = requireState(repoRoot, branch);
+    const gen = activeGeneration(s);
+    if (gen?.controllerJobId === undefined || gen.spawnNonce === undefined)
+        return false;
+    let parsed;
+    try {
+        parsed = JSON.parse(fs_1.default.readFileSync((0, exec_wrapper_1.identityPath)((0, paths_1.logsDir)(repoRoot, branch), gen.controllerJobId, gen.spawnNonce), 'utf8'));
+    }
+    catch {
+        return false;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return false;
+    const identity = parsed;
+    if (identity.jobId !== gen.controllerJobId || identity.nonce !== gen.spawnNonce
+        || !(0, types_1.isWellFormedProcessRef)(identity.wrapper) || !(0, types_1.isWellFormedProcessRef)(identity.command)
+        || identity.wrapper.spawnNonce !== gen.spawnNonce || identity.command.spawnNonce !== gen.spawnNonce
+        || gen.provider === undefined || gen.resumePrompt === undefined
+        || identity.command.argvDigest !== (0, process_1.argvDigest)((0, adapter_1.adapterFor)(gen.provider).launchArgv(promptForGeneration(gen))))
+        return false;
+    const changed = gen.wrapperRef?.pid !== identity.wrapper.pid || gen.processRef?.pid !== identity.command.pid;
+    gen.wrapperRef = identity.wrapper;
+    gen.processRef = identity.command;
+    if (changed) {
+        (0, store_1.writeJournal)(repoRoot, branch, s);
+        (0, store_1.appendEvent)(repoRoot, branch, { kind: 'generation-launched', provider: gen.provider, pid: gen.processRef.pid, n: gen.n });
+    }
+    return true;
+}
+function controllerGenerationHasUnresolvedClaim(repoRoot, branch, gen) {
+    if (gen.controllerJobId === undefined || gen.spawnNonce === undefined || gen.processRef !== undefined)
+        return false;
+    const logs = (0, paths_1.logsDir)(repoRoot, branch);
+    return fs_1.default.existsSync((0, exec_wrapper_1.claimPath)(logs, gen.controllerJobId, gen.spawnNonce))
+        && !fs_1.default.existsSync((0, exec_wrapper_1.resultPath)(logs, gen.controllerJobId, gen.spawnNonce));
+}
+/** Recupera tanto crash-before-spawn como crash-after-spawn-before-journal.
+ * Claim sin identidad queda ambiguo y se conserva bajo custodia tras la gracia;
+ * nunca se resuelve lanzando otro token/nonce a ciegas. */
+function ensureControllerGeneration(repoRoot, branch, provider, resumePrompt, spawner, ambiguityGraceMs) {
+    if (collectControllerGeneration(repoRoot, branch))
+        return;
+    let gen = activeGeneration(requireState(repoRoot, branch));
+    if (gen === undefined)
+        return;
+    if (gen.processRef !== undefined || gen.wrapperRef !== undefined)
+        return;
+    if (gen.controllerJobId === undefined || gen.spawnNonce === undefined) {
+        launchControllerGeneration(repoRoot, branch, provider, resumePrompt, spawner);
+        return;
+    }
+    const logs = (0, paths_1.logsDir)(repoRoot, branch);
+    if (fs_1.default.existsSync((0, exec_wrapper_1.resultPath)(logs, gen.controllerJobId, gen.spawnNonce))) {
+        enterCustody(repoRoot, branch, `controller ${gen.n} termino sin identidad adoptable: decision explicita requerida`);
+        return;
+    }
+    const claim = (0, exec_wrapper_1.claimPath)(logs, gen.controllerJobId, gen.spawnNonce);
+    if (fs_1.default.existsSync(claim)) {
+        let claimAgeMs = Number.POSITIVE_INFINITY;
+        try {
+            claimAgeMs = Date.now() - fs_1.default.statSync(claim).mtimeMs;
+        }
+        catch { /* si no se puede probar reciente, falla cerrado */ }
+        if (claimAgeMs > ambiguityGraceMs) {
+            enterCustody(repoRoot, branch, `claim de controller ${gen.n} sin identidad demostrable: custodia`);
+        }
+        return;
+    }
+    // El intent ya estaba durable pero el spawn no ocurrio: es seguro reemitir
+    // exactamente el mismo nonce. Si el wrapper original solo estaba demorado,
+    // su claim wx arbitra cual de ambos ejecuta.
+    launchControllerGeneration(repoRoot, branch, gen.provider ?? provider, gen.resumePrompt ?? resumePrompt, spawner);
+}
+/** Custodia (R4.5): ciclo BLOCKED con razon auditada. QUIEN NO HACE NADA:
+ *  no mata, no relanza, no libera lock — el loop sigue vivo auditando. */
+function enterCustody(repoRoot, branch, reason) {
+    const s = requireState(repoRoot, branch);
+    if (s.cycle.status !== 'BLOCKED' || s.cycle.blockedReason !== reason) {
+        s.cycle.status = 'BLOCKED';
+        s.cycle.blockedReason = reason;
+        (0, store_1.writeJournal)(repoRoot, branch, s);
+        (0, store_1.appendEvent)(repoRoot, branch, { kind: 'custody-blocked', reason });
+    }
+}
+/** Resolucion de la generacion vigente (R4.2b). Con los adapters de R1,
+ *  'safe' solo ocurre con muerte probada; la escalera queda para adapters
+ *  que puedan observar llamadas en vuelo. */
+async function resolveGeneration(repoRoot, branch, adapter, grace) {
+    const gen = activeGeneration(requireState(repoRoot, branch));
+    if (gen?.processRef === undefined)
+        return 'proven-dead'; // nunca se lanzo: relanzar es seguro
+    const ref = gen.processRef;
+    if (adapter.safeToReplace(ref) !== 'safe') {
+        enterCustody(repoRoot, branch, 'stall confirmado pero el adapter no afirma safeToReplace: custodia sin matar (R4.2b)');
+        return 'custody-blocked';
+    }
+    // muerte confirmada sin intervencion nuestra: no corresponde marcarla
+    // 'terminated' aca, porque nadie la mato (esa transicion es solo para la
+    // rama con kill real, mas abajo). Queda 'active' hasta el proximo
+    // beginGeneration exitoso, que la supersede al relanzar. CAVEAT para
+    // Task 18 (superviseController): beginGeneration esta gateado por
+    // backoff/relanzamiento — si el backoff se agota, el loop entra en
+    // custodia SIN llamar beginGeneration, y esta generacion queda 'active'
+    // en el journal indefinidamente (superseded, nunca terminated, cuando
+    // eventualmente se relance). Hoy es inerte (ningun consumidor lee
+    // generation.state para reportar), pero cualquier futuro consumidor de
+    // observabilidad debe cruzar con cycle.status, no confiar en
+    // generation.state === 'active' como "puede seguir vivo un proceso".
+    if (!(0, process_1.refIsAlive)(ref) && (0, process_1.groupIsGone)(ref.processGroup))
+        return 'proven-dead';
+    // vivo + safe positivo (adapters futuros): SIGTERM -> gracia -> SIGKILL, confirmando
+    const confirmed = await (0, process_1.terminateGroupConfirmed)(ref, grace);
+    if (!confirmed) {
+        enterCustody(repoRoot, branch, 'terminacion inconfirmable: custodia (R4.2b caso c)');
+        return 'custody-blocked';
+    }
+    const s = (0, store_1.readJournal)(repoRoot, branch).state;
+    const g = activeGeneration(s);
+    if (g !== undefined)
+        g.state = 'terminated';
+    (0, store_1.writeJournal)(repoRoot, branch, s);
+    (0, store_1.appendEvent)(repoRoot, branch, { kind: 'generation-terminated-confirmed', n: g?.n });
+    return 'terminated-confirmed';
+}

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

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerWatchCommand = registerWatchCommand;
+const child_process_1 = require("child_process");
+const init_1 = require("./init");
+const supervisor_1 = require("./supervisor");
+const process_1 = require("../../core/journal/process");
+function currentBranch(cwd) {
+    // stdio explicito (ver EXEC_STDIO en journal/process.ts): evita el relay
+    // default de execFileSync del stderr de git hacia el stderr del llamante,
+    // que EPIPE-crashea si ese fd es un pipe roto.
+    const b = (0, child_process_1.execFileSync)('git', ['branch', '--show-current'], { cwd, encoding: 'utf8', stdio: process_1.EXEC_STDIO }).trim();
+    if (b.length === 0)
+        throw new Error('no hay rama actual (HEAD detached): el journal es por rama');
+    return b;
+}
+function minutes(flag, raw) {
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n <= 0)
+        throw new Error(`${flag} requiere un numero de minutos > 0`);
+    return n * 60000;
+}
+function registerWatchCommand(program) {
+    program
+        .command('watch')
+        .description('supervisor durable: ejecuta jobs, releva controladores caidos, nunca mata trabajo vivo')
+        .option('--init', 'bootstrap: crea el journal de la rama actual, detecta verificadores y sale')
+        .option('--provider <p>', 'codex | claude-code', 'codex')
+        .option('--heartbeat-timeout <min>', 'minutos de silencio de heartbeat', '5')
+        .option('--activity-window <min>', 'minutos extra sin actividad de proceso', '10')
+        .action(async (opts) => {
+        const repo = process.cwd();
+        const branch = currentBranch(repo);
+        if (opts.init) {
+            const out = (0, init_1.initWatch)(repo, branch);
+            process.stdout.write(`journal inicializado para ${branch}; verificadores requeridos: ${JSON.stringify(out.requiredVerifiers)}\n`);
+            return;
+        }
+        const cfg = {
+            ...supervisor_1.DEFAULT_SUPERVISOR_CONFIG,
+            provider: opts.provider,
+            heartbeatTimeoutMs: minutes('--heartbeat-timeout', opts.heartbeatTimeout),
+            activityWindowMs: minutes('--activity-window', opts.activityWindow),
+        };
+        process.stdout.write(`awm watch: supervisor activo (${cfg.provider}) — Ctrl-C para terminar\n`);
+        await (0, supervisor_1.runSupervisorLoop)(repo, branch, cfg);
+        process.stdout.write('gate verde: ciclo COMPLETE — drenado, lock liberado, apagando\n');
+    });
+}

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

@@ -0,0 +1,72 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectRequiredVerifiers = detectRequiredVerifiers;
+exports.ensureJournalGitignored = ensureJournalGitignored;
+exports.initWatch = initWatch;
+// Bootstrap unico writer (R4.1) + validacion MECANICA plan-vs-repo (R1.4b,
+// bloqueador 5): la config real del repo determina los verificadores exigidos.
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const store_1 = require("../../core/journal/store");
+function detectRequiredVerifiers(repoRoot) {
+    const kinds = new Set();
+    const visit = (dir) => {
+        const sensors = path_1.default.join(dir, '.awm', 'sensors.json');
+        if (fs_1.default.existsSync(sensors))
+            kinds.add('sensors');
+        let entries;
+        try {
+            entries = fs_1.default.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.isSymbolicLink())
+                continue;
+            if (entry.isFile() && entry.name === 'package.json') {
+                try {
+                    const pkg = JSON.parse(fs_1.default.readFileSync(path_1.default.join(dir, entry.name), 'utf8'));
+                    if (typeof pkg === 'object' && pkg !== null && typeof pkg.scripts === 'object' && pkg.scripts !== null && typeof pkg.scripts.test === 'string')
+                        kinds.add('test');
+                }
+                catch { /* package ilegible: no prueba disponibilidad */ }
+            }
+            if (entry.isDirectory() && !['node_modules', '.git', '.awm'].includes(entry.name))
+                visit(path_1.default.join(dir, entry.name));
+        }
+    };
+    visit(repoRoot);
+    return ['test', 'sensors'].filter((kind) => kinds.has(kind));
+}
+/** El journal es gitignoreado (R1.1): sus escrituras jamas alteran fingerprints. */
+function ensureJournalGitignored(repoRoot) {
+    const gi = path_1.default.join(repoRoot, '.gitignore');
+    let current = '';
+    try {
+        current = fs_1.default.readFileSync(gi, 'utf8');
+    }
+    catch {
+        current = '';
+    }
+    if (!current.split('\n').some((l) => l.trim() === '.awm/' || l.trim() === '.awm')) {
+        fs_1.default.writeFileSync(gi, current.length > 0 && !current.endsWith('\n') ? `${current}\n.awm/\n` : `${current}.awm/\n`);
+    }
+}
+function initWatch(repoRoot, branch) {
+    ensureJournalGitignored(repoRoot);
+    (0, store_1.initJournal)(repoRoot, branch);
+    const required = detectRequiredVerifiers(repoRoot);
+    const r = (0, store_1.readJournal)(repoRoot, branch);
+    if (r.corrupt || r.state === null)
+        throw new Error('journal corrupto tras init: no se continua (R1.6)');
+    const s = r.state;
+    if (JSON.stringify(s.requiredVerifiers) !== JSON.stringify(required)) {
+        s.requiredVerifiers = required;
+        (0, store_1.writeJournal)(repoRoot, branch, s);
+    }
+    return { requiredVerifiers: required };
+}

package/dist/src/commands/watch/lock.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.LockBlockedError = void 0;
+exports.acquireLock = acquireLock;
+exports.releaseLock = releaseLock;
+exports.verifyBranchInvariant = verifyBranchInvariant;
+// Exclusion fisica de supervisores (R4.1): un solo writer por worktree FISICO.
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const crypto_1 = __importDefault(require("crypto"));
+const child_process_1 = require("child_process");
+const paths_1 = require("../../core/journal/paths");
+const process_1 = require("../../core/journal/process");
+const types_1 = require("../../core/journal/types");
+const atomic_file_1 = require("../../core/atomic-file");
+/** Identidad indemostrable en el lock: BLOQUEAR con error DISTINTO — el
+ *  operador decide con evidencia; el codigo jamas reclama lo que no puede
+ *  probar muerto (bloqueador 6 de la review). */
+class LockBlockedError extends Error {
+    constructor(message) { super(message); this.name = 'LockBlockedError'; }
+}
+exports.LockBlockedError = LockBlockedError;
+function acquireLock(repoRoot) {
+    const lp = (0, paths_1.supervisorLockPath)(repoRoot);
+    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 = JSON.stringify(self, null, 2) + '\n';
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            const fd = fs_1.default.openSync(lp, 'wx', 0o600); // creacion EXCLUSIVA real: sin ventana existsSync/write
+            try {
+                fs_1.default.writeFileSync(fd, body);
+                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;
+        }
+        // EEXIST: leer + validar identidad COMPLETA
+        let prior;
+        try {
+            prior = JSON.parse(fs_1.default.readFileSync(lp, 'utf8'));
+        }
+        catch {
+            throw new LockBlockedError(`lock ilegible en ${lp}: identidad indemostrable — BLOQUEADO (no se reclama; intervencion manual con evidencia)`);
+        }
+        if (!(0, types_1.isWellFormedProcessRef)(prior)) {
+            throw new LockBlockedError(`lock con shape invalido en ${lp}: identidad indemostrable — BLOQUEADO (no se reclama)`);
+        }
+        if ((0, process_1.refIsAlive)(prior)) {
+            throw new Error(`supervisor activo (pid ${prior.pid}) sobre este worktree`);
+        }
+        // Muerto PROBADO (la tupla completa no matchea a ningun proceso vivo):
+        // rm + reintento wx UNA sola vez — si la carrera persiste, error.
+        process.stderr.write('awm watch: lock previo con identidad muerta probada — reclamando\n');
+        fs_1.default.rmSync(lp, { force: true });
+    }
+    throw new Error('no se pudo adquirir el lock tras reintento unico (carrera persistente)');
+}
+function releaseLock(repoRoot, handle) {
+    const lp = handle.path;
+    try {
+        const onDisk = JSON.parse(fs_1.default.readFileSync(lp, 'utf8'));
+        if (onDisk.spawnNonce === handle.ref.spawnNonce)
+            fs_1.default.rmSync(lp);
+    }
+    catch { /* ya ausente o ilegible: no tocar lo que no es nuestro */ }
+}
+/** WHILE el supervisor este activo, el cambio de rama del worktree se bloquea:
+ *  gate/reconcile/watch verifican rama actual == rama del journal (R1.1). */
+function verifyBranchInvariant(repoRoot, journalBranch) {
+    // stdio explicito (ver EXEC_STDIO en journal/process.ts): sin esto, execFileSync
+    // relayea el stderr del subproceso git al stderr DEL SUPERVISOR — si ese fd es
+    // un pipe roto, el relay dispara un EPIPE no catcheable que crashea el proceso
+    // ENTERO (verifyBranchInvariant corre en cada tick, via supervisor.ts).
+    const current = (0, child_process_1.execFileSync)('git', ['branch', '--show-current'], { cwd: repoRoot, encoding: 'utf8', stdio: process_1.EXEC_STDIO }).trim();
+    if (current !== journalBranch) {
+        throw new Error(`BLOCKED: rama actual (${current}) != rama del journal (${journalBranch}) — cambio de rama con journal activo (R1.1)`);
+    }
+}

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

@@ -0,0 +1,191 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_STALL_OBSERVATION_MS = void 0;
+exports.defaultWrapperSpawner = defaultWrapperSpawner;
+exports.spawnPendingWrappers = spawnPendingWrappers;
+exports.collectAndReconcile = collectAndReconcile;
+exports.runnerTick = runnerTick;
+// Runner concurrente (bloqueador 3): el supervisor spawnea wrappers DETACHED y
+// jamas los espera; el avance viene del scan de sidecars en cada tick.
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const crypto_1 = __importDefault(require("crypto"));
+const store_1 = require("../../core/journal/store");
+const paths_1 = require("../../core/journal/paths");
+const process_1 = require("../../core/journal/process");
+const exec_wrapper_1 = require("../job/exec-wrapper");
+const reconcile_1 = require("../job/reconcile");
+const types_1 = require("../../core/journal/types");
+/** Spawner real: `awm job exec-wrapper` como proceso EXTERNO detached via el
+ *  CLI compilado. fire-and-forget: unref + stdio propio del wrapper. */
+function defaultWrapperSpawner(cliEntry = path_1.default.resolve(__dirname, '..', '..', 'index.js')) {
+    return (job, nonce, logsRoot, repoRoot) => {
+        const argv = [
+            process.execPath, cliEntry, 'job', 'exec-wrapper',
+            '--job', job.id, '--nonce', nonce, '--logs', logsRoot, '--cwd', job.cwd,
+            '--', ...job.argv,
+        ];
+        const { child, ref } = (0, process_1.spawnStructured)(argv, repoRoot, nonce);
+        child.unref(); // el supervisor NO espera; el wrapper sobrevive incluso si el supervisor muere
+        return ref;
+    };
+}
+/** spawn-intent + nonce persistidos ANTES de cualquier spawn (R1.8): si el
+ *  supervisor muere entre journal y spawn, el replay decide por claim. */
+function spawnPendingWrappers(repoRoot, branch, spawner) {
+    const r = (0, store_1.readJournal)(repoRoot, 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 received = Object.values(s.jobs).filter((j) => j.executionState === 'received');
+    if (received.length === 0)
+        return 0;
+    for (const j of received) {
+        j.spawnNonce = crypto_1.default.randomBytes(8).toString('hex');
+        j.executionState = 'spawn-intent';
+        j.phaseTimestamps['spawn-intent'] = new Date().toISOString();
+    }
+    (0, store_1.writeJournal)(repoRoot, branch, s); // intent DURABLE antes del primer spawn
+    const logs = (0, paths_1.logsDir)(repoRoot, branch);
+    for (const j of received) {
+        // Un spawn que lanza sincronicamente NO debe abortar el resto del lote:
+        // el spawn-intent de cada job ya quedo durable arriba: el proximo tick
+        // lo recoge (claim=>claimed) o la matriz lo declara never-started.
+        try {
+            spawner(j, j.spawnNonce, logs, repoRoot);
+        }
+        catch { /* ver comentario: el intent ya persistio, el proximo tick decide */ }
+    }
+    return received.length;
+}
+const SCANNABLE = ['spawn-intent', 'claimed', 'running'];
+function lastPhaseAgeMs(j) {
+    const stamps = Object.values(j.phaseTimestamps).map((t) => Date.parse(t)).filter((n) => !Number.isNaN(n));
+    if (stamps.length === 0)
+        return Number.POSITIVE_INFINITY;
+    return Date.now() - Math.max(...stamps);
+}
+// Observacional puro (R3.5): la duracion NUNCA produce transicion terminal.
+// Señal de progreso = mtime del log del job (analogo al "output consumido por
+// el supervisor" del stall de CONTROLADOR en generations.ts, pero para el job
+// mismo). Sin campo nuevo de tracking de bytes: el propio `lastProgressAt` ya
+// persistido sirve de referencia — si el log crecio (mtime mas nuevo que la
+// ultima marca), hay progreso; si no, y ya paso el umbral, es sospecha de
+// estancamiento. `suspected-stall` jamas mata ni reintenta nada — eso solo lo
+// hace `awm job reap`, invocado por un humano.
+exports.DEFAULT_STALL_OBSERVATION_MS = 5 * 60000; // orden de magnitud de heartbeatTimeoutMs, pero independiente (jobs != controlador)
+function updateJobObservation(j, logs, stallObservationMs) {
+    if (j.executionState !== 'running')
+        return;
+    const nonce = j.spawnNonce ?? 'sin-nonce';
+    let mtimeMs = 0;
+    try {
+        mtimeMs = fs_1.default.statSync((0, exec_wrapper_1.logPath)(logs, j.id, nonce)).mtimeMs;
+    }
+    catch { /* log aun no existe: sin progreso nuevo */ }
+    const baselineIso = j.lastProgressAt ?? j.phaseTimestamps.running;
+    const baselineMs = baselineIso !== undefined ? Date.parse(baselineIso) : Number.NEGATIVE_INFINITY;
+    if (mtimeMs > baselineMs) {
+        j.lastProgressAt = new Date().toISOString();
+        j.observationState = 'progressing';
+        return;
+    }
+    if (Date.now() - baselineMs > stallObservationMs) {
+        j.observationState = 'suspected-stall';
+    }
+}
+/** Cada tick: sidecars primero (claim=>claimed, identity=>running con identidad
+ *  REAL, result=>exited+verdict), reconciliacion (matriz unica) despues — solo
+ *  para jobs fuera de su ventana de gracia post-spawn. */
+function collectAndReconcile(repoRoot, branch, opts = {}) {
+    const graceMs = opts.reconcileGraceMs ?? 10000;
+    const stallObservationMs = opts.stallObservationMs ?? exports.DEFAULT_STALL_OBSERVATION_MS;
+    const r = (0, store_1.readJournal)(repoRoot, 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 logs = (0, paths_1.logsDir)(repoRoot, branch);
+    let advanced = 0;
+    let observationTouched = false;
+    for (const j of Object.values(s.jobs)) {
+        if (!SCANNABLE.includes(j.executionState))
+            continue;
+        const nonce = j.spawnNonce ?? 'sin-nonce';
+        if (fs_1.default.existsSync((0, exec_wrapper_1.claimPath)(logs, j.id, nonce)) && fs_1.default.existsSync((0, exec_wrapper_1.resultPath)(logs, j.id, nonce))) {
+            try {
+                const parsed = JSON.parse(fs_1.default.readFileSync((0, exec_wrapper_1.resultPath)(logs, j.id, nonce), 'utf8'));
+                if (typeof parsed.exitCode !== 'number' || typeof parsed.endedAt !== 'string' || typeof parsed.resultPath !== 'string')
+                    continue;
+                j.executionState = 'exited';
+                j.result = parsed;
+                j.verdict = parsed.exitCode === 0 ? 'pass' : 'fail';
+                j.phaseTimestamps.exited = j.phaseTimestamps.exited ?? new Date().toISOString();
+                advanced++;
+            }
+            catch { /* resultado ilegible: la matriz decidira (unprovable) */ }
+            continue;
+        }
+        if (fs_1.default.existsSync((0, exec_wrapper_1.identityPath)(logs, j.id, nonce)) && j.executionState !== 'running') {
+            try {
+                const identity = JSON.parse(fs_1.default.readFileSync((0, exec_wrapper_1.identityPath)(logs, j.id, nonce), 'utf8'));
+                if (identity.jobId === j.id && identity.nonce === nonce
+                    && (0, types_1.isWellFormedProcessRef)(identity.wrapper) && (0, types_1.isWellFormedProcessRef)(identity.command)
+                    && identity.wrapper.spawnNonce === nonce && identity.command.spawnNonce === nonce
+                    && identity.command.argvDigest === (0, process_1.argvDigest)(j.argv)) {
+                    j.wrapperRef = identity.wrapper;
+                    j.processRef = identity.command; // identidad REAL, nunca pid 0 (bloqueador 3)
+                    j.executionState = 'running';
+                    j.phaseTimestamps.running = new Date().toISOString();
+                    j.lastProgressAt = new Date().toISOString();
+                    advanced++;
+                }
+            }
+            catch { /* sidecar a medio escribir: proximo tick */ }
+            continue;
+        }
+        if (fs_1.default.existsSync((0, exec_wrapper_1.claimPath)(logs, j.id, nonce)) && j.executionState === 'spawn-intent') {
+            j.executionState = 'claimed';
+            j.phaseTimestamps.claimed = new Date().toISOString();
+            advanced++;
+        }
+    }
+    // observationState (R3.5): puramente informativo, corre para TODO job aun
+    // 'running' tras el scan de arriba — jamas toca executionState ni participa
+    // de la matriz de abajo.
+    for (const j of Object.values(s.jobs)) {
+        const before = `${j.observationState}|${j.lastProgressAt ?? ''}`;
+        updateJobObservation(j, logs, stallObservationMs);
+        if (`${j.observationState}|${j.lastProgressAt ?? ''}` !== before)
+            observationTouched = true;
+    }
+    // Matriz unica SOLO fuera de la gracia post-spawn: un wrapper recien
+    // spawneado que aun no claimeo NO es un never-started.
+    const out = (0, reconcile_1.reconcileJobs)(s, logs, { eligible: (j) => lastPhaseAgeMs(j) > graceMs });
+    if (advanced > 0 || observationTouched || out.decisions.some((d) => d.action !== 'still-alive')) {
+        (0, store_1.writeJournal)(repoRoot, branch, s);
+    }
+    return { advanced, decisions: out.decisions };
+}
+function runnerTick(repoRoot, branch, spawner, opts = {}) {
+    const collected = collectAndReconcile(repoRoot, branch, opts);
+    const r = (0, store_1.readJournal)(repoRoot, branch);
+    if (r.corrupt || r.state === null)
+        throw new Error('journal corrupto: el supervisor no opera sobre corrupcion (R1.6)');
+    const logs = (0, paths_1.logsDir)(repoRoot, branch);
+    for (const decision of collected.decisions) {
+        if (decision.action !== 'retry-same-intent')
+            continue;
+        const job = r.state.jobs[decision.jobId];
+        if (job?.executionState !== 'spawn-intent' || job.spawnNonce === undefined)
+            continue;
+        try {
+            spawner(job, job.spawnNonce, logs, repoRoot);
+        }
+        catch { /* el mismo intent durable se reintentara en otro tick */ }
+    }
+    const spawned = spawnPendingWrappers(repoRoot, branch, spawner);
+    return { spawned, advanced: collected.advanced, decisions: collected.decisions };
+}