agentic-workflow-manager 3.4.0 → 3.6.0

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

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

@@ -0,0 +1,266 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Supervisor = exports.DEFAULT_SUPERVISOR_CONFIG = void 0;
+exports.runSupervisorLoop = runSupervisorLoop;
+// Loop foreground (R4.4/R4.5): tick = apply -> collect/spawn -> stall -> gate.
+// COMPLETE exige gate verde (que exige cero vivos): drenaje ANTES de declarar.
+// Custodia BLOCKED: el loop sigue, el lock NO se libera, nada se mata.
+const store_1 = require("../../core/journal/store");
+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 lock_1 = require("./lock");
+const apply_1 = require("./apply");
+const runner_1 = require("./runner");
+const generations_1 = require("./generations");
+exports.DEFAULT_SUPERVISOR_CONFIG = {
+    provider: 'codex',
+    heartbeatTimeoutMs: 5 * 60000, // R4.2 default 5 min
+    activityWindowMs: 10 * 60000, // R4.2 ventana propia adicional
+    tickMs: 5000,
+    termGraceMs: 30000, // R4.2b flush 30 s
+    killGraceMs: 5000,
+    reconcileGraceMs: 10000,
+    jobStallObservationMs: 5 * 60000, // R3.5 default: mismo orden de magnitud que heartbeatTimeoutMs, concern independiente
+};
+const LIVE = ['received', 'spawn-intent', 'claimed', 'running', 'cancel-requested'];
+class Supervisor {
+    repoRoot;
+    branch;
+    cfg;
+    spawner;
+    backoff = new generations_1.Backoff();
+    relaunchNotBefore = 0;
+    lastActivity = null;
+    lastGenerationToken = null;
+    constructor(repoRoot, branch, cfg, spawner) {
+        this.repoRoot = repoRoot;
+        this.branch = branch;
+        this.cfg = cfg;
+        this.spawner = spawner;
+    }
+    fingerprintNow = (argv, paths, cwd) => {
+        try {
+            return (0, fingerprint_1.computeFingerprint)(this.repoRoot, argv, paths, cwd).fingerprint;
+        }
+        catch {
+            return null;
+        } // no recomputable => el gate NO certifica (fail-closed)
+    };
+    ensureController(resumePrompt) {
+        if (Date.now() < this.relaunchNotBefore)
+            return 'deferred';
+        if (this.backoff.exhausted()) {
+            (0, generations_1.enterCustody)(this.repoRoot, this.branch, 'tope de intentos de launch/relaunch por hora alcanzado (R4.3)');
+            return 'custody';
+        }
+        try {
+            (0, generations_1.ensureControllerGeneration)(this.repoRoot, this.branch, this.cfg.provider, resumePrompt, this.spawner, this.cfg.reconcileGraceMs);
+            return 'ok';
+        }
+        catch (error) {
+            this.backoff.recordRelaunch();
+            const delayMs = this.backoff.nextMs();
+            this.relaunchNotBefore = Date.now() + delayMs;
+            (0, store_1.appendEvent)(this.repoRoot, this.branch, {
+                kind: 'controller-launch-failed', detail: error.message, retryAfterMs: delayMs,
+            });
+            if (this.backoff.exhausted()) {
+                (0, generations_1.enterCustody)(this.repoRoot, this.branch, 'tope de intentos de launch/relaunch por hora alcanzado (R4.3)');
+                return 'custody';
+            }
+            return 'deferred';
+        }
+    }
+    async tick() {
+        const before = (0, store_1.readJournal)(this.repoRoot, this.branch);
+        if (before.corrupt || before.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')
+            return 'complete';
+        const pending = before.state?.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';
+        const r0 = (0, store_1.readJournal)(this.repoRoot, this.branch);
+        if (r0.corrupt || r0.state === null)
+            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);
+        const afterRequests = (0, store_1.readJournal)(this.repoRoot, this.branch);
+        if (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 });
+        const custody = await this.superviseController();
+        if (custody)
+            return 'custody';
+        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)
+            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';
+            }
+            s.cycle.status = 'COMPLETE';
+            s.cycle.completedAt = new Date().toISOString();
+            (0, store_1.writeJournal)(this.repoRoot, this.branch, s);
+            (0, store_1.appendEvent)(this.repoRoot, this.branch, { kind: 'cycle-complete' });
+            return 'complete';
+        }
+        return 'continue';
+    }
+    /** true => custodia (el caller NO libera lock ni sale). */
+    async superviseController() {
+        const r = (0, store_1.readJournal)(this.repoRoot, this.branch);
+        if (r.corrupt || r.state === null)
+            throw new Error('journal corrupto (R1.6)');
+        const s = r.state;
+        const gen = (0, generations_1.activeGeneration)(s);
+        if (gen?.processRef === undefined)
+            return false; // sin controlador propio: nada que supervisar
+        if (this.lastGenerationToken !== gen.token) {
+            this.lastGenerationToken = gen.token;
+            this.lastActivity = null;
+        }
+        const adapter = (0, adapter_1.adapterFor)(this.cfg.provider);
+        const heartbeatAgeMs = Date.now() - Date.parse(s.controllerHeartbeatAt ?? gen.launchedAt);
+        const snap = adapter.activity(gen.processRef);
+        const key = JSON.stringify(snap);
+        if (this.lastActivity === null || this.lastActivity.key !== key) {
+            this.lastActivity = { key, changedAt: Date.now() };
+        }
+        const activityFrozenMs = Date.now() - this.lastActivity.changedAt;
+        const decision = (0, generations_1.decideStall)({ heartbeatAgeMs, activityFrozenMs, safeToReplace: adapter.safeToReplace(gen.processRef) }, { heartbeatTimeoutMs: this.cfg.heartbeatTimeoutMs, activityWindowMs: this.cfg.activityWindowMs });
+        if (decision === 'healthy') {
+            this.backoff.reset();
+            return false;
+        }
+        if (decision === 'suspected-stall-observe') {
+            if (gen.state !== 'controller-suspected-stall') {
+                gen.state = 'controller-suspected-stall'; // SOLO observacion (R4.2)
+                (0, store_1.writeJournal)(this.repoRoot, this.branch, s);
+                (0, store_1.appendEvent)(this.repoRoot, this.branch, { kind: 'controller-suspected-stall', n: gen.n });
+            }
+            return false;
+        }
+        if (decision === 'custody-blocked') {
+            (0, generations_1.enterCustody)(this.repoRoot, this.branch, 'doble senial de stall sin safeToReplace positivo del adapter (R4.2b)');
+            return true;
+        }
+        // resolve-generation
+        const resolved = await (0, generations_1.resolveGeneration)(this.repoRoot, this.branch, adapter, { termGraceMs: this.cfg.termGraceMs, killGraceMs: this.cfg.killGraceMs });
+        if (resolved === 'custody-blocked')
+            return true;
+        if (this.backoff.exhausted()) {
+            (0, generations_1.enterCustody)(this.repoRoot, this.branch, 'tope de relanzamientos por hora alcanzado (R4.3)');
+            return true;
+        }
+        if (Date.now() < this.relaunchNotBefore)
+            return false; // esperando backoff, auditando
+        (0, generations_1.beginGeneration)(this.repoRoot, this.branch);
+        const nextAction = (0, store_1.readJournal)(this.repoRoot, this.branch).state.cycle.nextAction;
+        const prompt = nextAction !== undefined ? `el next_action ${nextAction.actionId} del journal` : 'el plan del ciclo desde el journal';
+        const launched = this.ensureController(prompt);
+        if (launched === 'custody')
+            return true;
+        if (launched === 'ok') {
+            this.backoff.recordRelaunch();
+            this.relaunchNotBefore = Date.now() + this.backoff.nextMs();
+        }
+        return false;
+    }
+}
+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)()) {
+    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');
+    (0, lock_1.verifyBranchInvariant)(repoRoot, r.state.branch);
+    if (r.state.cycle.status === 'COMPLETE')
+        return;
+    const handle = (0, lock_1.acquireLock)(repoRoot);
+    let shutdownRequested = false;
+    let wakeSleep = null;
+    let safeToRelease = false;
+    const onSignal = () => { shutdownRequested = true; wakeSleep?.(); };
+    process.on('SIGINT', onSignal);
+    process.on('SIGTERM', onSignal);
+    const sup = new Supervisor(repoRoot, branch, cfg, spawner);
+    try {
+        const s0 = (0, store_1.readJournal)(repoRoot, branch).state;
+        if ((0, generations_1.activeGeneration)(s0) === undefined) {
+            (0, generations_1.beginGeneration)(repoRoot, branch);
+        }
+        for (;;) {
+            if (shutdownRequested)
+                break;
+            const out = await sup.tick();
+            if (out === 'complete')
+                break;
+            // 'custody': NO liberar lock, NO salir — seguir auditando (R4.5)
+            await new Promise((resolve) => {
+                let settled = false;
+                const finish = () => { if (!settled) {
+                    settled = true;
+                    clearTimeout(timer);
+                    wakeSleep = null;
+                    resolve();
+                } };
+                const timer = setTimeout(finish, cfg.tickMs);
+                wakeSleep = finish;
+            });
+        }
+        // En shutdown explicito, drenar ownership ANTES de liberar el lock. En
+        // COMPLETE, tick() ya hizo exactamente esta confirmacion antes de
+        // persistir el estado terminal; el loop solo verifica el invariante.
+        (0, generations_1.collectControllerGeneration)(repoRoot, branch);
+        const sEnd = (0, store_1.readJournal)(repoRoot, branch).state;
+        for (const g of sEnd.generations) {
+            if ((0, generations_1.controllerGenerationHasUnresolvedClaim)(repoRoot, branch, g)) {
+                throw new Error(`ownership retenido: generacion ${g.n} tiene claim sin identidad ni resultado`);
+            }
+            for (const ref of [g.processRef, g.wrapperRef]) {
+                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: cfg.termGraceMs, killGraceMs: cfg.killGraceMs });
+                if (!confirmed)
+                    throw new Error(`ownership retenido: generacion ${g.n} sigue viva o su identidad es indemostrable`);
+            }
+            g.state = 'terminated';
+        }
+        if (shutdownRequested)
+            (0, store_1.writeJournal)(repoRoot, branch, sEnd);
+        safeToRelease = true;
+    }
+    finally {
+        process.removeListener('SIGINT', onSignal);
+        process.removeListener('SIGTERM', onSignal);
+        if (safeToRelease)
+            (0, lock_1.releaseLock)(repoRoot, handle);
+    }
+}

package/dist/src/core/atomic-file.js

@@ -4,6 +4,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.writeFileAtomic = writeFileAtomic;
+exports.fsyncDirSync = fsyncDirSync;
+exports.writeFileAtomicDurable = writeFileAtomicDurable;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const crypto_1 = __importDefault(require("crypto"));
@@ -70,3 +72,32 @@ function writeFileAtomic(file, content, mode = 0o644) {
         throw error;
     }
 }
+/** fsync del directorio contenedor: garantiza que una ENTRADA creada/renombrada
+ *  sobrevive un crash del OS. Falla LANZANDO — la durabilidad de la transición
+ *  es parte del contrato, nunca un best-effort silencioso (design R1.2,
+ *  bloqueador 4 de la review del plan). */
+function fsyncDirSync(dir) {
+    let dirFd;
+    try {
+        dirFd = fs_1.default.openSync(dir, 'r');
+        fs_1.default.fsyncSync(dirFd);
+    }
+    catch (error) {
+        throw new Error(`fsync de directorio fallo para ${dir}: ${error.message}`);
+    }
+    finally {
+        if (dirFd !== undefined) {
+            try {
+                fs_1.default.closeSync(dirFd);
+            }
+            catch {
+                // best-effort SOLO el close: el fsync ya ocurrio o ya lanzo.
+            }
+        }
+    }
+}
+/** writeFileAtomic + fsync del directorio contenedor tras el rename. */
+function writeFileAtomicDurable(file, content, mode = 0o644) {
+    writeFileAtomic(file, content, mode);
+    fsyncDirSync(path_1.default.dirname(file));
+}