agentic-workflow-manager 3.4.0 → 3.6.0

package/dist/src/commands/job/exec-wrapper.js

@@ -0,0 +1,136 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.claimPath = claimPath;
+exports.identityPath = identityPath;
+exports.resultPath = resultPath;
+exports.logPath = logPath;
+exports.replayVerdict = replayVerdict;
+exports.runExecWrapper = runExecWrapper;
+// PROCESO EXTERNO real (bloqueador 3): el supervisor lo spawnea detached y no
+// lo espera. Hace el spawn demostrable (design R1.8): claim exclusivo por
+// spawnNonce -> identidad real persistida -> ejecucion independiente ->
+// resultado terminal atomico. La matriz de replay es LA UNICA (R3.3).
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
+const process_1 = require("../../core/journal/process");
+const fingerprint_1 = require("../../core/journal/fingerprint");
+const redact_1 = require("../../core/journal/redact");
+const atomic_file_1 = require("../../core/atomic-file");
+function claimPath(logsRoot, jobId, nonce) {
+    return path_1.default.join(logsRoot, `${jobId}.${nonce}.claim`);
+}
+function identityPath(logsRoot, jobId, nonce) {
+    return path_1.default.join(logsRoot, `${jobId}.${nonce}.identity.json`);
+}
+function resultPath(logsRoot, jobId, nonce) {
+    return path_1.default.join(logsRoot, `${jobId}.${nonce}.result.json`);
+}
+function logPath(logsRoot, jobId, nonce) {
+    return path_1.default.join(logsRoot, `${jobId}.${nonce}.log`);
+}
+function replayVerdict(logsRoot, jobId, nonce) {
+    if (!fs_1.default.existsSync(claimPath(logsRoot, jobId, nonce)))
+        return 'never-started';
+    if (fs_1.default.existsSync(resultPath(logsRoot, jobId, nonce)))
+        return 'completed';
+    return 'unprovable';
+}
+const MAX_LOG_BYTES = 1024 * 1024; // retencion acotada (R2.5)
+// Ventana acotada post-exit para el flush de stdio (R1.8, R2.5). 300ms es
+// generoso frente al caso real (datos ya en vuelo en el pipe cuando 'exit'
+// dispara, tipicamente entregados en 1 tick del event loop) sin acercarse a
+// una espera perceptible si un descendiente hereda los fds y nunca cierra.
+const STDIO_GRACE_MS = 300;
+async function runExecWrapper(opts) {
+    const { logsRoot, jobId, nonce, argv, cwd } = opts;
+    const repoRoot = opts.repoRoot ?? process.cwd();
+    if (argv.length === 0)
+        throw new Error('argv vacio');
+    fs_1.default.mkdirSync(logsRoot, { recursive: true, mode: 0o700 });
+    // (1) claim exclusivo DURABLE — wx + fsync de archivo y de directorio
+    let fd;
+    try {
+        fd = fs_1.default.openSync(claimPath(logsRoot, jobId, nonce), 'wx', 0o600);
+    }
+    catch {
+        throw new Error(`claim ya existe para ${jobId}/${nonce}: spawn previo no descartable (R1.8)`);
+    }
+    try {
+        fs_1.default.writeFileSync(fd, JSON.stringify({ jobId, nonce, claimedAt: new Date().toISOString(), wrapperPid: process.pid }) + '\n');
+        fs_1.default.fsyncSync(fd);
+    }
+    finally {
+        fs_1.default.closeSync(fd);
+    }
+    (0, atomic_file_1.fsyncDirSync)(logsRoot);
+    const finish = (exitCode) => {
+        const result = { exitCode, endedAt: new Date().toISOString(), resultPath: resultPath(logsRoot, jobId, nonce) };
+        // (4) resultado terminal atomico junto al claim
+        (0, atomic_file_1.writeFileAtomicDurable)(result.resultPath, JSON.stringify(result, null, 2) + '\n', 0o600);
+        return result;
+    };
+    // (2) spawn del comando EN EL GRUPO DEL WRAPPER (detached:false): un solo
+    // process group por job, independiente del supervisor (R4.7: shell:false,
+    // argv como array, secretos solo por referencia de entorno).
+    const [exe, ...args] = argv;
+    const safeCwd = (0, fingerprint_1.resolveWorkingDirectory)(repoRoot, cwd).absolute;
+    const child = (0, child_process_1.spawn)(exe, args, {
+        cwd: safeCwd, shell: false, detached: true,
+        env: { ...process.env, [process_1.NONCE_ENV]: nonce },
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const spawnFailed = new Promise((resolve) => {
+        child.on('error', () => resolve(127));
+        child.on('spawn', () => resolve(null));
+    });
+    const failed = await spawnFailed;
+    if (failed !== null || child.pid === undefined)
+        return finish(127);
+    // (3) identidad REAL persistida ANTES de esperar el resultado: ProcessRef
+    // del wrapper Y del comando (bloqueador 3: nunca mas pid/pgid cero).
+    const identity = {
+        jobId, nonce,
+        wrapper: (0, process_1.captureSelfRef)(nonce),
+        command: (0, process_1.captureRefFor)(child.pid, nonce, argv),
+    };
+    (0, atomic_file_1.writeFileAtomicDurable)(identityPath(logsRoot, jobId, nonce), JSON.stringify(identity, null, 2) + '\n', 0o600);
+    // Salida acotada en memoria y redactada como UN flujo antes de la primera
+    // escritura durable. Redactar cada chunk aisladamente filtra asignaciones
+    // partidas por el pipe (p.ej. `API_` + `KEY=secreto`).
+    let captured = 0;
+    const outputChunks = [];
+    const logFile = logPath(logsRoot, jobId, nonce);
+    const capture = (chunk) => {
+        if (captured >= MAX_LOG_BYTES)
+            return;
+        const accepted = chunk.subarray(0, MAX_LOG_BYTES - captured);
+        outputChunks.push(accepted);
+        captured += accepted.length;
+    };
+    child.stdout?.on('data', capture);
+    child.stderr?.on('data', capture);
+    const exitCode = await new Promise((resolve) => {
+        child.on('exit', (code) => resolve(code ?? 1));
+        child.on('error', () => resolve(127));
+    });
+    // Ventana acotada para dejar llegar los ultimos chunks de stdio (exit puede
+    // dispararse antes que termine el flush de 'data') SIN bloquear indefinidamente
+    // si un descendiente hereda los fds y no los cierra — el wrapper SIEMPRE debe
+    // terminar (R1.8). 'close' sin cota reintroduce el riesgo de cuelgue.
+    await new Promise((resolve) => {
+        const timer = setTimeout(() => resolve(), STDIO_GRACE_MS);
+        child.once('close', () => { clearTimeout(timer); resolve(); });
+    });
+    if (outputChunks.length > 0) {
+        fs_1.default.writeFileSync(logFile, (0, redact_1.redactText)(Buffer.concat(outputChunks).toString('utf8')), { mode: 0o600 });
+    }
+    // El resultado terminal no se publica mientras queden descendientes en el
+    // grupo propio del comando. Como el wrapper vive en otro PGID, puede drenar
+    // el grupo completo sin auto-terminarse.
+    const drained = await (0, process_1.terminatePreviouslyOwnedGroup)(identity.command, { termGraceMs: 500, killGraceMs: 500 });
+    return finish(drained ? exitCode : 125);
+}

package/dist/src/commands/job/export.js

@@ -0,0 +1,94 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildExport = buildExport;
+// Export sanitizado y versionado (design R3.7, RNF-T.4/T.8/T.9): reproducible
+// desde checkout limpio; lo que el provider/baseline no reporta se declara
+// 'unobservable' — jamas un cero inventado.
+const fs_1 = __importDefault(require("fs"));
+const crypto_1 = __importDefault(require("crypto"));
+const exec_wrapper_1 = require("./exec-wrapper");
+function wallMs(from, to) {
+    if (from === undefined || to === undefined)
+        return 'unobservable';
+    const a = Date.parse(from);
+    const b = Date.parse(to);
+    if (Number.isNaN(a) || Number.isNaN(b) || b < a)
+        return 'unobservable';
+    return b - a;
+}
+function compare(current, baseline) {
+    const base = baseline ?? 'unobservable';
+    if (current === 'unobservable' || base === 'unobservable')
+        return { current, baseline: base, delta: 'unobservable' };
+    return { current, baseline: base, delta: current - base };
+}
+/** Dedup por fingerprint+commandDigest: el primero visto es el mecanico
+ *  real, cualquier repetido queda marcado (RNF-T.8/T.9). */
+function buildJobRows(jobs) {
+    const seen = new Set();
+    return jobs.map((j) => {
+        const k = `${j.fingerprint}:${j.commandDigest}`;
+        const deduplicated = seen.has(k);
+        seen.add(k);
+        return { id: j.id, fingerprint: j.fingerprint, executionState: j.executionState, verdict: j.verdict, phaseTimestamps: j.phaseTimestamps, deduplicated };
+    });
+}
+/** Hash del resultado real en disco (respaldado por reconcile.ts al adoptar,
+ *  ver spawnNonce en types.ts) + comando reproducible. Sin resultado
+ *  observable => 'unobservable', jamas un hash inventado (RNF-T.9). */
+function buildEvidence(jobs, logsRoot) {
+    return jobs.map((j) => {
+        let resultHash = 'unobservable';
+        if (logsRoot !== null && j.spawnNonce !== undefined) {
+            try {
+                resultHash = crypto_1.default.createHash('sha256').update(fs_1.default.readFileSync((0, exec_wrapper_1.resultPath)(logsRoot, j.id, j.spawnNonce), 'utf8')).digest('hex');
+            }
+            catch {
+                resultHash = 'unobservable';
+            }
+        }
+        // argv ya redactado por el emisor: reproducible sin secretos (R2.3)
+        return { jobId: j.id, resultHash, reproduce: `cd ${j.cwd} && ${j.argv.join(' ')}` };
+    });
+}
+function buildExport(state, provider, opts) {
+    const jobs = Object.values(state.jobs);
+    const jobRows = buildJobRows(jobs);
+    const evidence = buildEvidence(jobs, opts.logsRoot);
+    const cycleWall = wallMs(state.cycle.startedAt, state.cycle.completedAt);
+    const mechanicalRuns = jobRows.filter((j) => !j.deduplicated).length;
+    return {
+        schema: 2, provider, branch: state.branch, generatedBy: 'awm job export',
+        cycle: {
+            status: state.cycle.status,
+            startedAt: state.cycle.startedAt,
+            completedAt: state.cycle.completedAt ?? 'unobservable',
+            wallTimeMs: cycleWall,
+        },
+        tasks: state.tasks.map((t) => ({
+            id: t.id, status: t.status, attempts: t.attempts,
+            createdAt: t.createdAt ?? 'unobservable',
+            completedAt: t.completedAt ?? 'unobservable',
+            wallTimeMs: wallMs(t.createdAt, t.completedAt),
+        })),
+        jobs: jobRows,
+        evidence,
+        metrics: {
+            dispatches: state.dispatches.length,
+            mechanicalRunsReal: jobs.length,
+            mechanicalRunsDeduplicated: jobs.length - mechanicalRuns,
+            tokensPerRole: 'unobservable', // ningun provider lo expone mecanicamente hoy (R0)
+        },
+        baselineComparison: {
+            baselineDate: '2026-07-29',
+            source: opts.baseline?.source ?? 'unobservable',
+            wallTimeMs: compare(cycleWall, opts.baseline?.wallTimeMs),
+            dispatches: compare(state.dispatches.length, opts.baseline?.dispatches),
+            mechanicalRuns: compare(mechanicalRuns, opts.baseline?.mechanicalRuns),
+            tokensPerRole: 'unobservable',
+        },
+    };
+}

package/dist/src/commands/job/gate.js

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeGate = computeGate;
+const LIVE = ['received', 'spawn-intent', 'claimed', 'running', 'cancel-requested'];
+function computeGate(state, corrupt, fingerprintNow) {
+    const reasons = [];
+    if (corrupt || state === null) {
+        return { pass: false, reasons: [{ category: 'corrupt', detail: 'state.json corrupto o ilegible: la corrupcion jamas certifica' }] };
+    }
+    if (state.cycle.status === 'BLOCKED') {
+        reasons.push({ category: 'cycle-blocked', detail: `ciclo BLOCKED: ${state.cycle.blockedReason ?? 'sin razon registrada'}` });
+    }
+    for (const problem of state.requestProblems) {
+        reasons.push({ category: 'request-problem', detail: `request ${problem.kind} en ${problem.file}: ${problem.detail}` });
+    }
+    for (const j of Object.values(state.jobs)) {
+        if (LIVE.includes(j.executionState) || j.executionState === 'orphaned') {
+            reasons.push({ category: 'live-job', detail: `job ${j.id} en ${j.executionState}` });
+        }
+    }
+    for (const t of state.tasks) {
+        if (t.status !== 'done') {
+            reasons.push({ category: 'pending-task', detail: `task ${t.id} en ${t.status}` });
+        }
+    }
+    if (state.cycleVerificationPlan.length === 0) {
+        reasons.push({ category: 'empty-cycle-plan', detail: 'CycleVerificationPlan vacio: un ciclo sin plan de cierre jamas certifica (R1.4b)' });
+    }
+    for (const required of ['qa', 'interlock']) {
+        if (!state.cycleVerificationPlan.some((item) => item.kind === required)) {
+            reasons.push({ category: 'missing-verifier', detail: `CycleVerificationPlan requiere '${required}'` });
+        }
+    }
+    // Verificadores requeridos por la config REAL del repo (watch --init):
+    // cada kind requerido debe existir en algun plan (R1.4b, R3.6).
+    const allPlans = [...state.tasks.flatMap((t) => t.verificationPlan), ...state.cycleVerificationPlan];
+    const presentKinds = new Set(allPlans.map((i) => i.kind));
+    for (const mechanical of ['test', 'sensors']) {
+        if (!state.requiredVerifiers.includes(mechanical)) {
+            reasons.push({ category: 'missing-verifier', detail: `el repo no tiene '${mechanical}' configurado; no se certifica por ausencia (R3.6)` });
+        }
+    }
+    for (const required of state.requiredVerifiers) {
+        if (!presentKinds.has(required)) {
+            reasons.push({ category: 'missing-verifier', detail: `el repo exige verificador '${required}' y ningun plan lo contiene` });
+        }
+    }
+    for (const item of allPlans) {
+        if (item.satisfiedBy === undefined) {
+            reasons.push({ category: 'unsatisfied-plan', detail: `item ${item.id} (${item.kind}) sin satisfacer` });
+            continue;
+        }
+        if (item.kind === 'review') {
+            const v = state.verdicts.find((x) => x.id === item.satisfiedBy);
+            if (v === undefined) {
+                reasons.push({ category: 'dangling-reference', detail: `item ${item.id} cita verdict inexistente ${item.satisfiedBy}` });
+            }
+            else if (v.result !== 'pass') {
+                reasons.push({ category: 'adverse-verdict', detail: `item ${item.id} citado por verdict ${v.id} con result ${v.result}` });
+            }
+            else {
+                const now = fingerprintNow(v.argv, v.paths, v.cwd);
+                if (now === null || now !== v.fingerprint) {
+                    reasons.push({ category: 'stale-fingerprint', detail: `verdict ${v.id} es historico y no certifica` });
+                }
+            }
+            continue;
+        }
+        const j = state.jobs[item.satisfiedBy];
+        if (j === undefined) {
+            reasons.push({ category: 'dangling-reference', detail: `item ${item.id} cita job inexistente ${item.satisfiedBy}` });
+            continue;
+        }
+        if (j.verdict !== 'pass') {
+            reasons.push({ category: 'adverse-verdict', detail: `item ${item.id} citado por ${item.satisfiedBy} con verdict ${j.verdict ?? 'ausente'}` });
+            continue;
+        }
+        // Vigencia (RF-2.8): recomputar con argv/paths/cwd del job y comparar.
+        const now = fingerprintNow(j.argv, j.paths, j.cwd);
+        if (now === null || now !== j.fingerprint) {
+            reasons.push({ category: 'stale-fingerprint', detail: `item ${item.id}: la evidencia de ${j.id} es historica (fingerprint ${now === null ? 'no recomputable' : 'cambiado'}) — no certifica` });
+        }
+    }
+    for (const t of state.tasks) {
+        for (const requiredKind of ['spec', 'quality']) {
+            if (!t.reviewObligations.some((o) => o.kind === requiredKind)) {
+                reasons.push({ category: 'open-obligation', detail: `task ${t.id} carece de ReviewObligation ${requiredKind}` });
+            }
+        }
+        for (const o of t.reviewObligations) {
+            if (o.verdictId === undefined) {
+                reasons.push({ category: 'open-obligation', detail: `obligacion ${o.id} sin verdict` });
+                continue;
+            }
+            const v = state.verdicts.find((x) => x.id === o.verdictId);
+            if (v === undefined) {
+                reasons.push({ category: 'dangling-reference', detail: `obligacion ${o.id} cita verdict inexistente ${o.verdictId}` });
+            }
+            else if (v.result !== 'pass') {
+                reasons.push({ category: 'adverse-verdict', detail: `obligacion ${o.id} citada por verdict ${v.id} con result ${v.result}` });
+            }
+            else {
+                const now = fingerprintNow(v.argv, v.paths, v.cwd);
+                if (now === null || now !== v.fingerprint) {
+                    reasons.push({ category: 'stale-fingerprint', detail: `verdict ${v.id} de obligacion ${o.id} es historico y no certifica` });
+                }
+            }
+        }
+    }
+    for (const v of state.verdicts) {
+        if (v.result !== 'pass') {
+            const fix = state.fixes.find((f) => f.verdictId === v.id);
+            if (fix === undefined || !fix.closed)
+                reasons.push({ category: 'open-fix', detail: `verdict adverso ${v.id} sin fix cerrado` });
+        }
+    }
+    return { pass: reasons.length === 0, reasons };
+}

package/dist/src/commands/job/heartbeat.js

@@ -0,0 +1,15 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.emitHeartbeat = emitHeartbeat;
+const crypto_1 = __importDefault(require("crypto"));
+const requests_1 = require("../../core/journal/requests");
+function emitHeartbeat(repoRoot, branch, generationToken) {
+    (0, requests_1.emitRequest)(repoRoot, branch, {
+        kind: 'controller-heartbeat', generationToken,
+        idempotencyKey: crypto_1.default.randomBytes(8).toString('hex'), // cada latido es unico
+        payload: { at: new Date().toISOString() },
+    });
+}

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

@@ -0,0 +1,246 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerJobCommand = registerJobCommand;
+const child_process_1 = require("child_process");
+const path_1 = __importDefault(require("path"));
+const crypto_1 = __importDefault(require("crypto"));
+const request_1 = require("./request");
+const heartbeat_1 = require("./heartbeat");
+const query_1 = require("./query");
+const gate_1 = require("./gate");
+const reconcile_1 = require("./reconcile");
+const reap_1 = require("./reap");
+const export_1 = require("./export");
+const exec_wrapper_1 = require("./exec-wrapper");
+const requests_1 = require("../../core/journal/requests");
+const fingerprint_1 = require("../../core/journal/fingerprint");
+const process_1 = require("../../core/journal/process");
+const store_1 = require("../../core/journal/store");
+const paths_1 = require("../../core/journal/paths");
+const lock_1 = require("../watch/lock");
+const atomic_file_1 = require("../../core/atomic-file");
+const fs_1 = __importDefault(require("fs"));
+function branchOf(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 realFingerprintNow(repo) {
+    return (argv, paths, cwd) => {
+        try {
+            return (0, fingerprint_1.computeFingerprint)(repo, argv, paths, cwd).fingerprint;
+        }
+        catch {
+            return null;
+        }
+    };
+}
+// CONSTITUTION: commander valida los tokens de las options declaradas; los
+// variadicos van tras `--`. Los flags numericos/JSON se validan fail-fast.
+function registerJobCommand(program) {
+    const job = program.command('job').description('journal durable de trabajo del ciclo SDD (R1)');
+    job.command('request')
+        .description('registra la intencion de una verificacion — el supervisor la ejecuta')
+        .requiredOption('--generation <token>', 'token de la generacion vigente')
+        .option('--paths <globs...>', 'paths que el comando observa (default: arbol completo)')
+        .option('--cwd <dir>', 'cwd relativo del comando dentro del repo', '.')
+        .option('--satisfies <itemId>', 'id del item de VerificationPlan que este job satisface')
+        .argument('<cmd...>', 'comando tras --')
+        .action((cmd, opts) => {
+        const repo = process.cwd();
+        const r = (0, request_1.requestJob)(repo, branchOf(repo), opts.generation, cmd, opts.paths ?? [], opts.cwd, { satisfies: opts.satisfies });
+        process.stdout.write(JSON.stringify({ requestId: r.requestId, idempotencyKey: r.idempotencyKey }, null, 2) + '\n');
+    });
+    job.command('register')
+        .description('registra una entidad del ciclo (task | cycle-plan | dispatch | task-status | next-action | custody-decision) ANTES de actuar')
+        .requiredOption('--generation <token>')
+        .requiredOption('--entity <kind>', 'task | cycle-plan | dispatch | task-status | next-action | custody-decision')
+        .requiredOption('--json <payload>', 'payload JSON de la entidad')
+        .action((opts) => {
+        let payload;
+        try {
+            payload = JSON.parse(opts.json);
+        }
+        catch {
+            throw new Error('--json requiere un objeto JSON valido');
+        }
+        if (typeof payload !== 'object' || payload === null || Array.isArray(payload))
+            throw new Error('--json requiere un objeto JSON');
+        const repo = process.cwd();
+        const r = (0, requests_1.emitRequest)(repo, branchOf(repo), {
+            kind: 'register-entity', generationToken: opts.generation,
+            idempotencyKey: crypto_1.default.createHash('sha256').update(`${opts.entity}:${opts.json}`).digest('hex'),
+            payload: { entity: opts.entity, ...payload },
+        });
+        process.stdout.write(JSON.stringify({ requestId: r.requestId }, null, 2) + '\n');
+    });
+    job.command('verdict')
+        .description('registra el veredicto de una ReviewObligation AL RECIBIRSE')
+        .requiredOption('--generation <token>')
+        .requiredOption('--obligation <id>')
+        .requiredOption('--result <r>', 'pass | fail | inconclusive')
+        .option('--detail <texto>', 'detalle del veredicto', '')
+        .action((opts) => {
+        if (!['pass', 'fail', 'inconclusive'].includes(opts.result))
+            throw new Error('--result debe ser pass | fail | inconclusive');
+        const repo = process.cwd();
+        const reviewArgv = ['awm-review', opts.obligation];
+        const reviewFingerprint = (0, fingerprint_1.computeFingerprint)(repo, reviewArgv, [], '.');
+        // Determinista a partir de los MISMOS inputs que idempotencyKey, INCLUYENDO
+        // generation en ambos (alineado — bug post-624a4c0: idempotencyKey se habia
+        // quedado sin generation mientras verdictId si la incluia, lo que hacia que
+        // un veredicto genuinamente distinto en otra generacion colisionara en
+        // idempotencyKey pero difiriera en payloadDigest, cayendo a
+        // rejected-digest-mismatch en vez de aplicarse como veredicto nuevo):
+        // un retry genuino del mismo comando (misma generation) produce un payload
+        // byte-identico, no un rejected-digest-mismatch espurio (Fix 3); una
+        // generation distinta produce una idempotencyKey ENTERAMENTE distinta, no
+        // una colision con digest distinto.
+        const verdictId = `verd-${crypto_1.default.createHash('sha256').update(`${opts.generation}:${opts.obligation}:${opts.result}:${opts.detail}:${reviewFingerprint.fingerprint}`).digest('hex').slice(0, 16)}`;
+        (0, requests_1.emitRequest)(repo, branchOf(repo), {
+            kind: 'verdict', generationToken: opts.generation,
+            idempotencyKey: crypto_1.default.createHash('sha256').update(`verdict:${opts.generation}:${opts.obligation}:${opts.result}:${opts.detail}:${reviewFingerprint.fingerprint}`).digest('hex'),
+            payload: {
+                verdictId, obligationId: opts.obligation, result: opts.result, detail: opts.detail,
+                fingerprint: reviewFingerprint.fingerprint, argv: reviewArgv, paths: [], cwd: '.',
+            },
+        });
+        process.stdout.write(JSON.stringify({ verdictId }, null, 2) + '\n');
+    });
+    job.command('controller-heartbeat')
+        .requiredOption('--generation <token>')
+        .action((opts) => { (0, heartbeat_1.emitHeartbeat)(process.cwd(), branchOf(process.cwd()), opts.generation); });
+    job.command('ps').action(() => {
+        process.stdout.write(JSON.stringify((0, query_1.queryPs)(process.cwd(), branchOf(process.cwd())), null, 2) + '\n');
+    });
+    job.command('list').action(() => {
+        process.stdout.write(JSON.stringify((0, query_1.queryList)(process.cwd(), branchOf(process.cwd())), null, 2) + '\n');
+    });
+    job.command('show')
+        .argument('<jobId>')
+        .action((jobId) => {
+        const out = (0, query_1.queryShow)(process.cwd(), branchOf(process.cwd()), jobId);
+        process.stdout.write(JSON.stringify(out, null, 2) + '\n');
+        if (out.corruptState || out.job === null)
+            process.exit(1);
+    });
+    job.command('reconcile')
+        .description('informe read-only de la matriz unica R1.8 + next_action (la mutacion es del supervisor)')
+        .action(() => {
+        const repo = process.cwd();
+        const branch = branchOf(repo);
+        const r = (0, store_1.readJournal)(repo, branch);
+        if (r.corrupt || r.state === null) {
+            process.stdout.write(JSON.stringify({ corruptState: true }, null, 2) + '\n');
+            process.exit(1);
+        }
+        try {
+            (0, lock_1.verifyBranchInvariant)(repo, r.state.branch);
+        }
+        catch (e) {
+            process.stderr.write(`${e.message}\n`);
+            process.exit(1);
+        }
+        // copia en memoria: reconcileJobs muta SU copia, jamas el disco (R3.1)
+        const clone = JSON.parse(JSON.stringify(r.state));
+        const out = (0, reconcile_1.reconcileJobs)(clone, (0, paths_1.logsDir)(repo, branch));
+        const active = r.state.generations.find((g) => g.state === 'active' || g.state === 'controller-suspected-stall');
+        process.stdout.write(JSON.stringify({
+            decisions: out.decisions,
+            nextAction: r.state.cycle.nextAction ?? null,
+            cycleStatus: r.state.cycle.status,
+            generation: active === undefined ? null : { n: active.n, token: active.token },
+        }, null, 2) + '\n');
+    });
+    job.command('gate')
+        .description('interlock fail-closed: exit != 0 si CUALQUIER cosa impide certificar')
+        .action(() => {
+        const repo = process.cwd();
+        const branch = branchOf(repo);
+        const r = (0, store_1.readJournal)(repo, branch);
+        if (r.state !== null) {
+            try {
+                (0, lock_1.verifyBranchInvariant)(repo, r.state.branch);
+            }
+            catch (e) {
+                process.stderr.write(`${e.message}\n`);
+                process.exit(1);
+            }
+        }
+        const g = (0, gate_1.computeGate)(r.state, r.corrupt, realFingerprintNow(repo));
+        process.stdout.write(JSON.stringify(g, null, 2) + '\n');
+        if (!g.pass)
+            process.exit(1); // falla cerrado (R3.2)
+    });
+    job.command('reap')
+        .description('lista procesos de jobs (identidad completa); --execute --jobs <ids...> para terminar confirmando')
+        .option('--execute', 'ejecutar la terminacion de los jobs listados en --jobs')
+        .option('--jobs <ids...>', 'ids de jobs a terminar (obligatorio con --execute)')
+        .action(async (opts) => {
+        const repo = process.cwd();
+        const r = (0, store_1.readJournal)(repo, branchOf(repo));
+        if (r.corrupt || r.state === null) {
+            process.stderr.write('journal corrupto o ausente\n');
+            process.exit(1);
+        }
+        const plan = (0, reap_1.planReap)(r.state);
+        process.stdout.write(JSON.stringify(plan, null, 2) + '\n'); // R2.2: listar SIEMPRE primero
+        if (opts.execute) {
+            if (!Array.isArray(opts.jobs) || opts.jobs.length === 0)
+                throw new Error('--execute requiere --jobs <ids...>');
+            const killed = await (0, reap_1.executeReap)(r.state, opts.jobs);
+            process.stdout.write(JSON.stringify({ killed }, null, 2) + '\n');
+        }
+    });
+    job.command('export')
+        .option('--provider <p>', 'provider del ciclo', 'codex')
+        .option('--baseline <file>', 'JSON con metricas del baseline 2026-07-29 (source/wallTimeMs/dispatches/mechanicalRuns)')
+        .action((opts) => {
+        const repo = process.cwd();
+        const branch = branchOf(repo);
+        const r = (0, store_1.readJournal)(repo, branch);
+        if (r.corrupt || r.state === null) {
+            process.stderr.write('journal corrupto\n');
+            process.exit(1);
+        }
+        let baseline = null;
+        if (opts.baseline !== undefined) {
+            let parsed;
+            try {
+                parsed = JSON.parse(fs_1.default.readFileSync(opts.baseline, 'utf8'));
+            }
+            catch (e) {
+                throw new Error(`--baseline: no se pudo leer o parsear ${opts.baseline} como JSON (${e.message})`);
+            }
+            if (typeof parsed !== 'object' || parsed === null || typeof parsed.source !== 'string') {
+                throw new Error('--baseline requiere un JSON con al menos {source: string}');
+            }
+            baseline = parsed;
+        }
+        const e = (0, export_1.buildExport)(r.state, opts.provider, { logsRoot: (0, paths_1.logsDir)(repo, branch), baseline });
+        const out = path_1.default.join((0, paths_1.exportDir)(repo, branch), 'cycle-export.json');
+        (0, atomic_file_1.writeFileAtomicDurable)(out, JSON.stringify(e, null, 2) + '\n', 0o600);
+        process.stdout.write(out + '\n');
+    });
+    // Entrypoint INTERNO del wrapper externo (Task 9). Oculto del help: lo
+    // invoca el supervisor, no un humano — pero DEBE ser un comando real para
+    // que el wrapper sea un proceso independiente (bloqueador 3).
+    job.command('exec-wrapper', { hidden: true })
+        .requiredOption('--job <id>')
+        .requiredOption('--nonce <n>')
+        .requiredOption('--logs <dir>')
+        .option('--cwd <dir>', 'cwd del comando', '.')
+        .argument('<cmd...>')
+        .action(async (cmd, opts) => {
+        // El exit code del WRAPPER es 0 si registro el resultado (su exito
+        // propio); el exit code del COMANDO viaja en el result sidecar.
+        await (0, exec_wrapper_1.runExecWrapper)({ logsRoot: opts.logs, jobId: opts.job, nonce: opts.nonce, argv: cmd, cwd: opts.cwd });
+    });
+}

package/dist/src/commands/job/query.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.queryPs = queryPs;
+exports.queryList = queryList;
+exports.queryShow = queryShow;
+const store_1 = require("../../core/journal/store");
+const process_1 = require("../../core/journal/process");
+/** Fuente unica de "que hay corriendo": cruza identidad completa contra
+ *  procesos vivos. corrupt es VISIBLE, nunca descartado (R1.6). */
+function queryPs(repoRoot, branch) {
+    const r = (0, store_1.readJournal)(repoRoot, branch);
+    if (r.corrupt)
+        return { corruptState: true, jobs: [] };
+    const jobs = Object.values(r.state.jobs).map((j) => ({
+        id: j.id, executionState: j.executionState, observationState: j.observationState, verdict: j.verdict,
+        alive: j.processRef ? (0, process_1.refIsAlive)(j.processRef) : 'sin-pid',
+    }));
+    return { corruptState: false, jobs };
+}
+function queryList(repoRoot, branch) {
+    const r = (0, store_1.readJournal)(repoRoot, branch);
+    if (r.corrupt)
+        return { corruptState: true, cycleStatus: null, jobs: [] };
+    return {
+        corruptState: false,
+        cycleStatus: r.state.cycle.status,
+        jobs: Object.values(r.state.jobs).map((j) => ({
+            id: j.id, executionState: j.executionState, verdict: j.verdict, argv: j.argv, satisfies: j.satisfies,
+        })),
+    };
+}
+function queryShow(repoRoot, branch, jobId) {
+    const r = (0, store_1.readJournal)(repoRoot, branch);
+    if (r.corrupt)
+        return { corruptState: true, job: null };
+    return { corruptState: false, job: r.state.jobs[jobId] ?? null };
+}