agentic-workflow-manager 3.4.0 → 3.6.0

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

@@ -0,0 +1,352 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.consumePendingRequests = consumePendingRequests;
+// Consumo transaccional de requests (bloqueador 4): mutar estado ->
+// writeJournal -> RECIEN AHI borrar archivos. El replay es seguro por
+// requestId + idempotencyKey + digest.
+const fs_1 = __importDefault(require("fs"));
+const crypto_1 = __importDefault(require("crypto"));
+const store_1 = require("../../core/journal/store");
+const requests_1 = require("../../core/journal/requests");
+const paths_1 = require("../../core/journal/paths");
+const atomic_file_1 = require("../../core/atomic-file");
+const redact_1 = require("../../core/journal/redact");
+function now() { return new Date().toISOString(); }
+const VERIFICATION_KINDS = ['test', 'lint', 'sensors', 'review', 'qa', 'interlock'];
+function verificationItems(value, field) {
+    if (!Array.isArray(value) || !value.every((item) => typeof item === 'object' && item !== null
+        && typeof item.id === 'string'
+        && VERIFICATION_KINDS.includes(item.kind)
+        && (item.satisfiedBy === undefined || typeof item.satisfiedBy === 'string'))) {
+        throw new Error(`${field} requiere items de verificacion validos`);
+    }
+    return value;
+}
+function reviewObligations(value, taskId) {
+    if (!Array.isArray(value) || !value.every((item) => typeof item === 'object' && item !== null
+        && typeof item.id === 'string'
+        && (item.kind === 'spec' || item.kind === 'quality'))) {
+        throw new Error('reviewObligations requiere obligaciones spec|quality validas');
+    }
+    return value.map((item) => ({ ...item, taskId }));
+}
+function stringArray(value, field) {
+    if (!Array.isArray(value) || !value.every((item) => typeof item === 'string'))
+        throw new Error(`${field} requiere array de strings`);
+    return value;
+}
+function linkSatisfies(s, itemId, jobId) {
+    const items = [...s.tasks.flatMap((t) => t.verificationPlan), ...s.cycleVerificationPlan];
+    const item = items.find((i) => i.id === itemId);
+    if (item === undefined)
+        throw new Error(`VerificationItem desconocido: ${itemId}`);
+    item.satisfiedBy = jobId;
+}
+function applyRequestToState(s, env, digest) {
+    const base = { requestId: env.requestId, idempotencyKey: env.idempotencyKey, payloadDigest: digest };
+    if (env.kind === 'controller-heartbeat') {
+        s.controllerHeartbeatAt = now();
+        (0, requests_1.applyOutcome)(s, { ...base, outcome: 'applied' });
+        return;
+    }
+    if (env.kind === 'job-request') {
+        // get-or-create por idempotencyKey (RNF-T.7); duplicado => applyOutcome
+        // registra el ALIAS con el mismo resultRef (Task 8).
+        const prior = Object.values(s.appliedRequests).find((a) => a.idempotencyKey === env.idempotencyKey && a.outcome === 'applied');
+        if (prior !== undefined) {
+            (0, requests_1.applyOutcome)(s, { ...base, outcome: 'applied' });
+            return;
+        }
+        const p = env.payload;
+        if (!Array.isArray(p.argv) || !p.argv.every((arg) => typeof arg === 'string') || p.argv.length === 0)
+            throw new Error('job-request requiere argv no vacio');
+        if (typeof p.fingerprint !== 'string' || typeof p.commandDigest !== 'string')
+            throw new Error('job-request requiere fingerprint y commandDigest');
+        // Un mismo resultado mecanico puede satisfacer mas de un item. La
+        // request sigue teniendo identidad propia, pero no duplica ejecucion.
+        const equivalent = Object.values(s.jobs).find((j) => j.fingerprint === p.fingerprint && j.commandDigest === p.commandDigest
+            && (['received', 'spawn-intent', 'claimed', 'running'].includes(j.executionState)
+                || (j.executionState === 'exited' && j.verdict === 'pass')));
+        if (equivalent !== undefined) {
+            if (typeof p.satisfies === 'string')
+                linkSatisfies(s, p.satisfies, equivalent.id);
+            (0, requests_1.applyOutcome)(s, { ...base, outcome: 'applied', resultRef: equivalent.id });
+            return;
+        }
+        const jobId = `job-${Object.keys(s.jobs).length + 1}-${crypto_1.default.randomBytes(3).toString('hex')}`;
+        const job = {
+            id: jobId,
+            fingerprint: String(p.fingerprint), commandDigest: String(p.commandDigest),
+            argv: p.argv,
+            cwd: typeof p.cwd === 'string' ? p.cwd : '.',
+            paths: p.paths === undefined ? [] : stringArray(p.paths, 'job-request paths'),
+            expandedPaths: p.expandedPaths === undefined ? [] : stringArray(p.expandedPaths, 'job-request expandedPaths'),
+            executionState: 'received', observationState: 'progressing',
+            phaseTimestamps: { received: now() },
+            ...(typeof p.satisfies === 'string' ? { satisfies: p.satisfies } : {}),
+        };
+        s.jobs[jobId] = job;
+        if (typeof p.satisfies === 'string')
+            linkSatisfies(s, p.satisfies, jobId);
+        (0, requests_1.applyOutcome)(s, { ...base, outcome: 'applied', resultRef: jobId });
+        return;
+    }
+    if (env.kind === 'register-entity') {
+        const p = env.payload;
+        if (p.entity === 'task') {
+            if (typeof p.taskId !== 'string' || p.taskId.length === 0)
+                throw new Error('register --entity task requiere taskId (string no vacio)');
+            const taskId = p.taskId;
+            if (!s.tasks.some((t) => t.id === taskId)) {
+                const plan = p.verificationPlan === undefined ? [] : verificationItems(p.verificationPlan, 'verificationPlan');
+                // R1.4b/R3.6: rechazo EN REGISTRO (no solo en gate) si el plan no
+                // cubre los verificadores mecanicamente requeridos por el repo.
+                const missingKinds = s.requiredVerifiers.filter((k) => !plan.some((item) => item.kind === k));
+                if (missingKinds.length > 0) {
+                    throw new Error(`register --entity task: verificationPlan no cubre los verificadores requeridos: ${missingKinds.join(', ')}`);
+                }
+                const obligations = p.reviewObligations === undefined ? [] : reviewObligations(p.reviewObligations, taskId);
+                s.tasks.push({
+                    id: taskId, title: String(p.title ?? taskId), status: 'pending', attempts: 0,
+                    verificationPlan: plan, reviewObligations: obligations, createdAt: now(),
+                });
+            }
+            (0, requests_1.applyOutcome)(s, { ...base, outcome: 'applied', resultRef: taskId });
+            return;
+        }
+        if (p.entity === 'cycle-plan') {
+            const items = verificationItems(p.items, 'register --entity cycle-plan items');
+            // Idempotente por creacion-unica (Task 4): un re-registro defensivo
+            // (ej. tras crash sin memoria de si ya se registro) NUNCA debe pisar
+            // un plan ya existente y perder los `satisfiedBy` ya enlazados.
+            if (s.cycleVerificationPlan.length === 0) {
+                s.cycleVerificationPlan = items;
+            }
+            (0, requests_1.applyOutcome)(s, { ...base, outcome: 'applied' });
+            return;
+        }
+        if (p.entity === 'dispatch') {
+            if (typeof p.dispatchId !== 'string' || p.dispatchId.length === 0)
+                throw new Error('register --entity dispatch requiere dispatchId (string no vacio)');
+            if (typeof p.taskId !== 'string' || p.taskId.length === 0)
+                throw new Error('register --entity dispatch requiere taskId (string no vacio)');
+            const dispatchId = p.dispatchId;
+            const taskId = p.taskId;
+            if (!s.tasks.some((task) => task.id === taskId))
+                throw new Error('register --entity dispatch: taskId desconocido');
+            if (!s.dispatches.some((d) => d.id === dispatchId)) {
+                s.dispatches.push({ id: dispatchId, taskId, at: now() });
+                const task = s.tasks.find((t) => t.id === taskId);
+                if (task !== undefined)
+                    task.attempts += 1;
+            }
+            (0, requests_1.applyOutcome)(s, { ...base, outcome: 'applied', resultRef: dispatchId });
+            return;
+        }
+        if (p.entity === 'task-status') {
+            if (typeof p.taskId !== 'string' || p.taskId.length === 0)
+                throw new Error('register --entity task-status requiere taskId (string no vacio)');
+            if (p.status !== 'pending' && p.status !== 'in-progress' && p.status !== 'done')
+                throw new Error('register --entity task-status requiere status pending|in-progress|done');
+            const taskId = p.taskId;
+            const status = p.status;
+            const task = s.tasks.find((t) => t.id === taskId);
+            // Fake-success eliminado: una referencia a un taskId inexistente NO
+            // es un no-op silencioso con outcome 'applied' — se rechaza (Fix 1
+            // Parte C lo captura sin tumbar el supervisor).
+            if (task === undefined)
+                throw new Error('register --entity task-status: taskId desconocido');
+            task.status = status;
+            if (status === 'done')
+                task.completedAt = now();
+            (0, requests_1.applyOutcome)(s, { ...base, outcome: 'applied' });
+            return;
+        }
+        if (p.entity === 'next-action') {
+            if (typeof p.actionId !== 'string' || typeof p.type !== 'string' || typeof p.target !== 'string') {
+                throw new Error('register --entity next-action requiere actionId, type, target (strings)');
+            }
+            s.cycle.nextAction = {
+                actionId: p.actionId,
+                type: p.type,
+                target: p.target,
+                preconditions: p.preconditions === undefined ? [] : stringArray(p.preconditions, 'next-action preconditions'),
+                attempt: typeof p.attempt === 'number' ? p.attempt : 0,
+                state: p.state === 'in-progress' ? 'in-progress' : 'pending',
+            };
+            (0, requests_1.applyOutcome)(s, { ...base, outcome: 'applied', resultRef: p.actionId });
+            return;
+        }
+        if (p.entity === 'custody-decision') {
+            if (p.decision !== 'resume' || typeof p.reason !== 'string' || p.reason.trim().length === 0) {
+                throw new Error('register --entity custody-decision requiere decision=resume y reason no vacio');
+            }
+            if (s.cycle.status !== 'BLOCKED')
+                throw new Error('custody-decision solo aplica a un ciclo BLOCKED');
+            s.custodyDecisions ??= [];
+            s.custodyDecisions.push({ at: now(), decision: 'resume', reason: p.reason, generationToken: env.generationToken });
+            for (const generation of s.generations) {
+                if (generation.state === 'active' || generation.state === 'controller-suspected-stall')
+                    generation.state = 'superseded';
+            }
+            s.cycle.status = 'IN_PROGRESS';
+            s.cycle.blockedReason = undefined;
+            (0, requests_1.applyOutcome)(s, { ...base, outcome: 'applied' });
+            return;
+        }
+        throw new Error(`register-entity desconocida: ${String(p.entity)}`);
+    }
+    if (env.kind === 'verdict') {
+        const p = env.payload;
+        if (typeof p.verdictId !== 'string' || p.verdictId.length === 0)
+            throw new Error('verdict requiere verdictId');
+        if (typeof p.obligationId !== 'string' || p.obligationId.length === 0)
+            throw new Error('verdict requiere obligationId');
+        if (typeof p.fingerprint !== 'string' || typeof p.cwd !== 'string') {
+            throw new Error('verdict requiere evidencia de fingerprint reproducible');
+        }
+        const verdictArgv = stringArray(p.argv, 'verdict argv');
+        const verdictPaths = stringArray(p.paths, 'verdict paths');
+        if (p.result !== 'pass' && p.result !== 'fail' && p.result !== 'inconclusive')
+            throw new Error('verdict requiere result pass|fail|inconclusive');
+        const verdictId = String(p.verdictId);
+        const obligationId = String(p.obligationId);
+        if (!s.tasks.some((task) => task.reviewObligations.some((obligation) => obligation.id === obligationId))) {
+            throw new Error(`verdict refiere obligationId desconocido: ${obligationId}`);
+        }
+        if (!s.verdicts.some((v) => v.id === verdictId)) {
+            const result = p.result;
+            // R2.3: redaccion tambien en el `detail` de texto libre humano, no
+            // solo en argv — antes de cualquier escritura durable.
+            s.verdicts.push({
+                id: verdictId, obligationId, result, detail: (0, redact_1.redactText)(String(p.detail ?? '')), receivedAt: now(),
+                fingerprint: p.fingerprint, argv: verdictArgv, paths: verdictPaths, cwd: p.cwd,
+            });
+            for (const t of s.tasks) {
+                const o = t.reviewObligations.find((x) => x.id === obligationId);
+                if (o !== undefined)
+                    o.verdictId = verdictId;
+                for (const item of t.verificationPlan) {
+                    if (item.kind === 'review' && item.id === obligationId)
+                        item.satisfiedBy = verdictId;
+                }
+            }
+            // Veredicto adverso => FixObligation ATOMICA: misma mutacion, misma
+            // escritura de estado (R1.4c, bloqueador 5).
+            if (result !== 'pass') {
+                s.fixes.push({ id: `fix-${verdictId}`, verdictId, closed: false });
+            }
+            else {
+                // pass sobre la MISMA obligacion cierra cualquier fix abierto de
+                // un veredicto adverso anterior — un ciclo real fail->fix->pass
+                // debe poder llegar a COMPLETE (bloqueador de este dispatch).
+                const priorAdverseIds = s.verdicts
+                    .filter((v) => v.obligationId === obligationId && v.id !== verdictId && v.result !== 'pass')
+                    .map((v) => v.id);
+                for (const fix of s.fixes) {
+                    if (priorAdverseIds.includes(fix.verdictId))
+                        fix.closed = true;
+                }
+            }
+        }
+        (0, requests_1.applyOutcome)(s, { ...base, outcome: 'applied', resultRef: verdictId });
+        return;
+    }
+}
+/** Consume TODAS las requests pendientes en orden. ORDEN CRITICO (R1.3,
+ *  bloqueador 4): (1) mutar estado, (2) writeJournal, (3) borrar archivos,
+ *  (4) fsync del directorio. Solo el supervisor llama esto (single-writer). */
+function consumePendingRequests(repoRoot, branch, activeToken) {
+    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)');
+    let s = r.state;
+    const pending = (0, requests_1.listPendingRequests)(repoRoot, branch);
+    const processedFiles = [];
+    const deferredRenames = [];
+    let applied = 0, rejectedStale = 0, rejectedDigest = 0, rejectedInvalid = 0, corrupt = 0;
+    let dirChanged = false; // corrupt-rename O borrado normal: cualquiera muta el directorio
+    let stateTouched = false;
+    for (const p of pending) {
+        if (p.corrupt) {
+            corrupt++;
+            deferredRenames.push({ from: p.file, to: `${p.file}.corrupt` });
+            if (!s.requestProblems.some((problem) => problem.file === p.file && problem.kind === 'corrupt')) {
+                s.requestProblems.push({ file: p.file, kind: 'corrupt', detail: 'request JSON/shape invalido', at: now() });
+            }
+            (0, store_1.appendEvent)(repoRoot, branch, { kind: 'request-corrupt', file: p.file });
+            dirChanged = true;
+            stateTouched = true;
+            continue;
+        }
+        const env = p.envelope;
+        const digest = (0, requests_1.digestOf)(env.payload);
+        if (s.appliedRequests[env.requestId] !== undefined) {
+            // replay tras crash post-journal/pre-borrado: ya aplicada, solo borrar
+            processedFiles.push(p.file);
+            dirChanged = true;
+            continue;
+        }
+        // Fix 1: idempotencyKey reutilizada con payload DISTINTO se detecta
+        // PROACTIVAMENTE aca, antes de mutar nada — jamas dejamos que
+        // applyOutcome('applied') tire (eso encallaria al supervisor para
+        // siempre, con el archivo ofensor nunca borrado). Se rechaza visible
+        // via el outcome ya existente 'rejected-digest-mismatch'.
+        const priorSameKey = Object.values(s.appliedRequests).find((a) => a.idempotencyKey === env.idempotencyKey);
+        if (priorSameKey !== undefined && priorSameKey.payloadDigest !== digest) {
+            (0, requests_1.applyOutcome)(s, { requestId: env.requestId, idempotencyKey: env.idempotencyKey, payloadDigest: digest, outcome: 'rejected-digest-mismatch' });
+            (0, store_1.appendEvent)(repoRoot, branch, { kind: 'request-rejected-digest-mismatch', requestId: env.requestId });
+            rejectedDigest++;
+        }
+        else if (activeToken !== null && env.generationToken !== activeToken) {
+            (0, requests_1.applyOutcome)(s, { requestId: env.requestId, idempotencyKey: env.idempotencyKey, payloadDigest: digest, outcome: 'rejected-stale-generation' });
+            (0, store_1.appendEvent)(repoRoot, branch, { kind: 'request-rejected-stale', requestId: env.requestId });
+            rejectedStale++;
+        }
+        else {
+            // Defensa en profundidad (Fix 1 Parte C): CUALQUIER error de
+            // validacion inesperado (Fix 6/7 u otro futuro) jamas debe tumbar
+            // al supervisor. Se trata como el .corrupt existente — visible,
+            // jamas descartado en silencio — pero con sufijo distinto porque
+            // esto es rechazo de CONTENIDO, no de forma (R1.6).
+            try {
+                // Toda request se valida/muta sobre una copia. Un fallo profundo
+                // nunca deja un estado parcialmente contaminado que luego no se
+                // pueda serializar o reintentar.
+                const candidate = structuredClone(s);
+                applyRequestToState(candidate, env, digest);
+                s = candidate;
+                applied++;
+                stateTouched = true;
+            }
+            catch (e) {
+                rejectedInvalid++;
+                deferredRenames.push({ from: p.file, to: `${p.file}.rejected` });
+                if (!s.requestProblems.some((problem) => problem.file === p.file && problem.kind === 'rejected')) {
+                    s.requestProblems.push({ file: p.file, kind: 'rejected', detail: (0, redact_1.redactText)(e.message), at: now() });
+                }
+                (0, store_1.appendEvent)(repoRoot, branch, { kind: 'request-rejected-invalid', requestId: env.requestId, detail: e.message });
+                dirChanged = true;
+                stateTouched = true;
+                continue;
+            }
+        }
+        processedFiles.push(p.file);
+        dirChanged = true;
+    }
+    if (processedFiles.length > 0 || stateTouched) {
+        (0, store_1.writeJournal)(repoRoot, branch, s); // (2) journal ANTES del borrado
+    }
+    for (const rename of deferredRenames) {
+        if (fs_1.default.existsSync(rename.from))
+            fs_1.default.renameSync(rename.from, rename.to);
+    }
+    for (const f of processedFiles)
+        fs_1.default.rmSync(f, { force: true }); // (3)
+    if (dirChanged)
+        (0, atomic_file_1.fsyncDirSync)((0, paths_1.requestsDir)(repoRoot, branch)); // (4) — incluye batches solo-corrupt
+    return { applied, rejectedStale, rejectedDigest, rejectedInvalid, corrupt };
+}

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