agentic-workflow-manager 3.3.1 → 3.5.0

package/dist/src/core/journal/process.js

@@ -0,0 +1,284 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXEC_STDIO = exports.NONCE_ENV = void 0;
+exports.argvDigest = argvDigest;
+exports.psArgsDigestOf = psArgsDigestOf;
+exports.captureRefFor = captureRefFor;
+exports.captureSelfRef = captureSelfRef;
+exports.spawnStructured = spawnStructured;
+exports.refIsAlive = refIsAlive;
+exports.processStatesAreGone = processStatesAreGone;
+exports.groupIsGone = groupIsGone;
+exports.activitySnapshot = activitySnapshot;
+exports.terminateGroupConfirmed = terminateGroupConfirmed;
+exports.terminatePreviouslyOwnedGroup = terminatePreviouslyOwnedGroup;
+const crypto_1 = __importDefault(require("crypto"));
+const child_process_1 = require("child_process");
+exports.NONCE_ENV = 'AWM_SPAWN_NONCE';
+/** Contrato dual, a proposito (tomo 3 rondas de fixes reales llegar aca —
+ *  ver historial de Task 10): devuelve `null` SOLO cuando `ps` corrio y
+ *  confirmo positivamente que el pid no existe (exit status 1). Cualquier
+ *  otro fallo (ENOENT del binario, permisos, error transitorio) se
+ *  RELANZA — nunca se traduce a `null`, porque un `null` aca significaria
+ *  "muerte confirmada" para cualquier caller que no distinga los casos.
+ *  Hay DOS formas correctas de consumir esto, segun el contexto:
+ *  - Declaracion de muerte (`refIsAlive`, `activitySnapshot`): el caller
+ *    DEBE envolver en su propio try/catch y fallar A FAVOR de "vivo" —
+ *    nunca asumir muerto por un throw. El silencio jamas es prueba.
+ *  - Captura de identidad en spawn (`captureRefFor`, `stablePsArgs`): usar
+ *    `psFieldSafe` en vez de esta funcion — ahi "no se pudo determinar" ya
+ *    tiene un fallback seguro documentado ('unknown'), sin riesgo de
+ *    declarar muerte por error. */
+/** stdio explicito en TODOS los execFileSync de este archivo (ver EXEC_STDIO):
+ *  sin esto, `execFileSync` por defecto hace `inheritStderr` — relayea el
+ *  stderr del subproceso hacia el stderr DEL PROCESO LLAMANTE. Si ese stderr
+ *  llegara a ser un pipe roto/destruido (ej. wrapper detached, ver
+ *  spawnStructured), el relay mismo dispara el EPIPE que crashea al
+ *  llamante — el mismo bug de raiz, reintroducido via esta funcion en vez
+ *  de via el spawn del hijo. Con stdio explicito ('pipe' para stdout/stderr)
+ *  ese relay jamas ocurre: `execFileSync` captura el stderr del subproceso
+ *  internamente y listo, sin tocar el fd real del proceso actual. */
+exports.EXEC_STDIO = ['ignore', 'pipe', 'pipe'];
+function psField(pid, field) {
+    try {
+        const out = (0, child_process_1.execFileSync)('ps', ['-o', `${field}=`, '-p', String(pid)], { encoding: 'utf8', stdio: exports.EXEC_STDIO }).trim();
+        return out.length > 0 ? out : null;
+    }
+    catch (error) {
+        const status = error.status;
+        if (status === 1)
+            return null; // ps corrio y confirmo: el pid no existe
+        throw error; // ps no pudo ejecutarse (ENOENT/permisos/etc): NO es prueba de nada
+    }
+}
+function sleepSync(seconds) {
+    try {
+        (0, child_process_1.execFileSync)('sleep', [seconds], { stdio: exports.EXEC_STDIO });
+    }
+    catch { /* sin sleep: seguimos */ }
+}
+/** Variante de psField para contextos de CAPTURA de identidad (spawn time):
+ *  aqui "no se pudo determinar" ya tiene un fallback seguro documentado
+ *  ('unknown') — no es un contexto de declaracion de muerte, asi que
+ *  cualquier fallo de ps se traga, igual que siempre. */
+function psFieldSafe(pid, field) {
+    try {
+        return psField(pid, field);
+    }
+    catch {
+        return null;
+    }
+}
+/** ps args estable: dos lecturas consecutivas iguales (evita capturar el
+ *  estado pre-exec del fork). null si el proceso ya no existe O si ps
+ *  fallo en ejecutarse (via psFieldSafe) — ambos casos son "no se pudo
+ *  determinar" aca, sin riesgo: este es un contexto de captura, no de
+ *  declaracion de muerte. */
+function stablePsArgs(pid) {
+    for (let i = 0; i < 5; i++) {
+        const a = psFieldSafe(pid, 'args');
+        if (a === null)
+            return null;
+        sleepSync('0.05');
+        const b = psFieldSafe(pid, 'args');
+        if (b === a)
+            return a;
+    }
+    return psFieldSafe(pid, 'args');
+}
+function argvDigest(argv) {
+    return crypto_1.default.createHash('sha256').update(argv.join('\0')).digest('hex').slice(0, 16);
+}
+/** EXPORTADA pero hereda el contrato crudo de psField (throws si ps falla
+ *  en ejecutarse, mas alla de "pid no existe"). Hoy el unico caller es
+ *  refIsAlive, que ya envuelve en su propio try/catch fail-safe — cualquier
+ *  caller NUEVO que la use standalone debe hacer lo mismo (ver comentario
+ *  de psField) o usar psFieldSafe si esta en un contexto de captura. */
+function identityDigest(psArgs, spawnNonce, requestedArgvDigest) {
+    return crypto_1.default.createHash('sha256').update(`${psArgs}\0${spawnNonce}\0${requestedArgvDigest}`).digest('hex').slice(0, 16);
+}
+function psArgsDigestOf(pid, spawnNonce = '', requestedArgvDigest = '') {
+    const args = psField(pid, 'args');
+    if (args === null)
+        return null;
+    return identityDigest(args, spawnNonce, requestedArgvDigest);
+}
+/** Captura la identidad COMPLETA de un pid recien spawneado (R2.1):
+ *  startTime + pgid reales de ps + digest de `ps -o args=` estable. */
+function captureRefFor(pid, nonce, argv) {
+    let start = null;
+    for (let i = 0; i < 5 && start === null; i++) {
+        start = psFieldSafe(pid, 'lstart');
+        if (start === null)
+            sleepSync('0.05');
+    }
+    const pgid = psFieldSafe(pid, 'pgid');
+    const args = stablePsArgs(pid);
+    const requestedArgvDigest = argvDigest(argv);
+    return {
+        pid,
+        startTime: start ?? 'unknown',
+        spawnNonce: nonce,
+        argvDigest: requestedArgvDigest,
+        processGroup: pgid !== null ? Number(pgid) : pid,
+        // Liga nonce + argv solicitado con la observacion real de ps. Alterar
+        // cualquier miembro de la tupla invalida la identidad completa.
+        psArgsDigest: args !== null ? identityDigest(args, nonce, requestedArgvDigest) : 'unknown',
+    };
+}
+/** Identidad del proceso ACTUAL (la usa el wrapper externo y el lock). */
+function captureSelfRef(nonce) {
+    return captureRefFor(process.pid, nonce, process.argv);
+}
+/** Ejecucion segura (design R4.7): executable+argv como array, shell:false,
+ *  nonce por entorno (referencia, no valor persistido), grupo propio (detached). */
+function spawnStructured(argv, cwd, nonce, extraEnv = {}) {
+    const [exe, ...args] = argv;
+    const child = (0, child_process_1.spawn)(exe, args, {
+        cwd, shell: false, detached: true,
+        env: { ...process.env, [exports.NONCE_ENV]: nonce, ...extraEnv },
+        // stdio:'ignore' completo (nada de pipes): un pipe destruido/abandonado
+        // por el padre puede EPIPE-crashear al hijo si este escribe a su propio
+        // stdout/stderr despues (ver defaultWrapperSpawner) — el hijo maneja su
+        // stdio propio, el padre no necesita capturarlo.
+        stdio: 'ignore',
+    });
+    if (child.pid === undefined)
+        throw new Error(`spawn fallo para ${exe}`);
+    return { child, ref: captureRefFor(child.pid, nonce, argv) };
+}
+/** Vivo Y con la MISMA identidad — tupla completa, nunca PID solo (R2.1,
+ *  bloqueador 6): startTime + pgid + digest de ps args. */
+function refIsAlive(ref) {
+    try {
+        const stat = psField(ref.pid, 'stat');
+        if (stat === null || stat.startsWith('Z'))
+            return false; // zombie = proceso terminado, solo espera reap
+        const start = psField(ref.pid, 'lstart');
+        if (start === null || start !== ref.startTime)
+            return false;
+        const pgid = psField(ref.pid, 'pgid');
+        if (pgid === null || Number(pgid) !== ref.processGroup)
+            return false;
+        const argsDig = psArgsDigestOf(ref.pid, ref.spawnNonce, ref.argvDigest);
+        if (argsDig === null || argsDig !== ref.psArgsDigest)
+            return false;
+        return true;
+    }
+    catch {
+        // ps no pudo ejecutarse: sin evidencia, jamas declarar muerte — se
+        // trata como vivo (R2.1, bloqueador de Task 10: silencio no es prueba).
+        return true;
+    }
+}
+/** true <=> pgrep no encuentra miembros ejecutables en el grupo. Los zombies
+ *  ya terminaron y solo esperan reap; no pueden responder seniales ni retener
+ *  trabajo. Un fallo de observacion devuelve false (R2.1). */
+function processStatesAreGone(states) {
+    return states.every((stat) => stat === null || stat.startsWith('Z'));
+}
+function groupIsGone(pgid) {
+    let pids;
+    try {
+        const out = (0, child_process_1.execFileSync)('pgrep', ['-g', String(pgid)], { encoding: 'utf8', stdio: exports.EXEC_STDIO });
+        pids = out.split('\n').filter(Boolean).map(Number).filter(Number.isInteger);
+    }
+    catch (error) {
+        const status = error.status;
+        return status === 1; // pgrep exit 1 = cero matches; cualquier otra cosa NO confirma
+    }
+    if (pids.length === 0)
+        return true;
+    try {
+        // `pgrep` tambien devuelve zombies. No pueden ejecutar, mantener FDs ni
+        // responder seniales; contarlos como vivos fuerza esperas completas y
+        // custodia falsa hasta que el parent haga reap. Solo un miembro no-zombie
+        // conserva ownership ejecutable del grupo.
+        return processStatesAreGone(pids.map((pid) => psField(pid, 'stat')));
+    }
+    catch {
+        return false; // sin observacion completa, falla cerrado
+    }
+}
+function activitySnapshot(ref) {
+    if (!refIsAlive(ref))
+        return null;
+    let cpu = '0';
+    try {
+        cpu = psField(ref.pid, 'time') ?? '0';
+    }
+    catch {
+        cpu = '0';
+    }
+    let groupSize = 1;
+    try {
+        groupSize = (0, child_process_1.execFileSync)('pgrep', ['-g', String(ref.processGroup)], { encoding: 'utf8', stdio: exports.EXEC_STDIO })
+            .split('\n').filter(Boolean).length;
+    }
+    catch {
+        groupSize = 1;
+    }
+    return { cpuTime: cpu, groupSize };
+}
+/** Escalera de gracia (design R4.2b): SIGTERM -> confirmar -> SIGKILL -> confirmar.
+ *  true <=> lider muerto por identidad Y grupo entero desaparecido (pgrep -g
+ *  vacio) — jamas confirmar solo el lider (bloqueador 6). */
+async function terminateGroupConfirmed(ref, opts) {
+    const waitUntilGone = async (maxMs) => {
+        const deadline = Date.now() + maxMs;
+        while (Date.now() < deadline) {
+            if (groupIsGone(ref.processGroup))
+                return true;
+            await new Promise((resolve) => setTimeout(resolve, Math.min(25, Math.max(1, deadline - Date.now()))));
+        }
+        return groupIsGone(ref.processGroup);
+    };
+    if (groupIsGone(ref.processGroup))
+        return true;
+    // Un PGID ocupado con lider de identidad distinta NO es nuestro. Nunca
+    // usar la falta de match como autorizacion para senializar ese grupo.
+    if (!refIsAlive(ref))
+        return false;
+    try {
+        process.kill(-ref.processGroup, 'SIGTERM');
+    }
+    catch { /* grupo ya ausente */ }
+    if (await waitUntilGone(opts.termGraceMs))
+        return true;
+    try {
+        process.kill(-ref.processGroup, 'SIGKILL');
+    }
+    catch { /* idem */ }
+    return waitUntilGone(opts.killGraceMs);
+}
+/** Drena un grupo cuya propiedad fue capturada por el caller mientras el
+ * lider aun estaba vivo. Se usa inmediatamente tras el exit del lider para
+ * eliminar descendientes remanentes; el PGID no puede reutilizarse mientras
+ * esos miembros sigan presentes. */
+async function terminatePreviouslyOwnedGroup(ref, opts) {
+    const waitUntilGone = async (maxMs) => {
+        const deadline = Date.now() + maxMs;
+        while (Date.now() < deadline) {
+            if (groupIsGone(ref.processGroup))
+                return true;
+            await new Promise((resolve) => setTimeout(resolve, Math.min(25, Math.max(1, deadline - Date.now()))));
+        }
+        return groupIsGone(ref.processGroup);
+    };
+    if (groupIsGone(ref.processGroup))
+        return true;
+    try {
+        process.kill(-ref.processGroup, 'SIGTERM');
+    }
+    catch { /* ya ausente */ }
+    if (await waitUntilGone(opts.termGraceMs))
+        return true;
+    try {
+        process.kill(-ref.processGroup, 'SIGKILL');
+    }
+    catch { /* ya ausente */ }
+    return waitUntilGone(opts.killGraceMs);
+}

package/dist/src/core/journal/redact.js

@@ -0,0 +1,142 @@
+"use strict";
+// Redacción EN EL EMISOR, antes de cualquier escritura (design R2.3).
+// Patrones alineados con el sensor-pack de secretos del registry baseline.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.redactText = redactText;
+exports.findLiteralSecretFlag = findLiteralSecretFlag;
+exports.redactArgv = redactArgv;
+const SECRET_WORD = /(password|passwd|secret|api[-_]?key|apikey|token|credential)/i;
+// ASSIGNMENT (regex de único backtracking) tuvo 3 rondas de fallas reales:
+// sin cota => ReDoS cuadrático (corridas largas sin match, o muchas
+// ocurrencias sueltas del keyword sin separador); cotado en ambos lados =>
+// fuga de secretos con identificadores largos entre el keyword y el "=".
+// Sustituido por escaneo manual caracter-a-caracter: O(n) sin backtracking,
+// sin cota de longitud posible en ningún lado, inmune a ambos hallazgos.
+const KEYWORD_RE = /password|passwd|secret|api[-_]?key|apikey|token|credential/gi;
+const IDENT_CHAR = /[a-z0-9_-]/i;
+const WHITESPACE = /\s/;
+// Distinto de SECRET_WORD (substring, para nombres de flag reales): aquí el
+// keyword debe ser un segmento completo delimitado por -, _ o los bordes del
+// string. Se usa SOLO dentro de redactArgv para decidir hasta dónde extender
+// la redacción en cadena — nunca para decidir SI redactar: ver comentario en
+// redactArgv sobre por qué la ambigüedad siempre se resuelve redactando de
+// más, nunca de menos.
+const SECRET_FLAG_SEGMENT = /(^|[-_])(password|passwd|secret|api[-_]?key|apikey|token|credential)($|[-_])/i;
+function looksLikeSensitiveFlag(token) {
+    if (!token.startsWith('-'))
+        return false;
+    const eq = token.indexOf('=');
+    const flag = eq === -1 ? token : token.slice(0, eq);
+    return SECRET_FLAG_SEGMENT.test(flag.replace(/^-+/, ''));
+}
+function redactText(text) {
+    let result = '';
+    let cursor = 0;
+    KEYWORD_RE.lastIndex = 0;
+    let m;
+    while ((m = KEYWORD_RE.exec(text)) !== null) {
+        if (m.index < cursor)
+            continue;
+        let keyEnd = m.index + m[0].length;
+        while (keyEnd < text.length && IDENT_CHAR.test(text[keyEnd]))
+            keyEnd++;
+        let sepStart = keyEnd;
+        while (sepStart < text.length && WHITESPACE.test(text[sepStart]))
+            sepStart++;
+        if (sepStart >= text.length || (text[sepStart] !== '=' && text[sepStart] !== ':')) {
+            KEYWORD_RE.lastIndex = keyEnd;
+            continue;
+        }
+        let valueStart = sepStart + 1;
+        while (valueStart < text.length && WHITESPACE.test(text[valueStart]))
+            valueStart++;
+        if (valueStart >= text.length) {
+            KEYWORD_RE.lastIndex = keyEnd;
+            continue;
+        }
+        let valueEnd = valueStart;
+        while (valueEnd < text.length && !WHITESPACE.test(text[valueEnd]))
+            valueEnd++;
+        result += text.slice(cursor, valueStart) + '[REDACTED]';
+        cursor = valueEnd;
+        KEYWORD_RE.lastIndex = cursor;
+    }
+    result += text.slice(cursor);
+    return result;
+}
+/** Flag sensible que porta un secreto LITERAL (no una referencia `-env`):
+ *  la request se rechaza, no se persiste ni redactada (R2.3). Deliberadamente
+ *  NO intenta distinguir "el siguiente token es un flag hermano" de "es el
+ *  valor literal": el rechazo es todo-o-nada (emitRequest lanza antes de
+ *  persistir nada), así que la ambigüedad nunca importa — cualquier token
+ *  después de un flag sensible ya es motivo suficiente de rechazo.
+ *
+ *  LIMITACIÓN ACEPTADA (no es un bug pendiente): esta función solo reconoce
+ *  secretos cuyo NOMBRE de flag contiene una palabra clave (password/token/
+ *  secret/api-key/credential), sea con cualquier cantidad de guiones (-token, --token).
+ *  Mnemónicos de una sola letra sin texto ninguno (ej. `-p` de mysql, `-i` de
+ *  ssh, `-u` de curl) son indistinguibles de cualquier otro flag corto por
+ *  texto solo — cerrar ese caso exigiría una tabla fija de convenciones por
+ *  herramienta externa, que es enumeración no acotada y no pertenece a un
+ *  mecanismo genérico (ver CLAUDE.md, frontera genérico/específico). Si esto
+ *  resulta ser un problema real y recurrente en este proyecto, se resuelve
+ *  vía harness-retro con una regla específica, no aquí. */
+function findLiteralSecretFlag(argv) {
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (!arg.startsWith('-'))
+            continue;
+        const eq = arg.indexOf('=');
+        const flag = eq === -1 ? arg : arg.slice(0, eq);
+        const inlineValue = eq === -1 ? undefined : arg.slice(eq + 1);
+        if (!SECRET_WORD.test(flag))
+            continue;
+        if (/-env$/i.test(flag))
+            continue; // referencia, permitida (R4.7)
+        const value = inlineValue !== undefined ? inlineValue : argv[i + 1];
+        if (value !== undefined)
+            return flag;
+    }
+    return null;
+}
+/** A diferencia de findLiteralSecretFlag (todo-o-nada), esta función SÍ debe
+ *  devolver un array persistible — no puede simplemente rechazar. Cuando el
+ *  token que sigue a un flag sensible también PARECE un flag sensible, es
+ *  imposible distinguir por texto solo "es un flag hermano real" de "es el
+ *  valor literal (adversario) del flag anterior disfrazado de flag" — ambas
+ *  lecturas son indistinguibles sin un esquema de flags real (hallazgo de
+ *  spec-review, R2.3). Ante esa ambigüedad se redacta TODA la cadena de
+ *  tokens con forma de flag sensible más el token final que la cierra,
+ *  nunca menos: sobre-redactar un nombre de flag es un costo cosmético,
+ *  dejar pasar un secreto no lo es. */
+function redactArgv(argv) {
+    const out = [];
+    let i = 0;
+    while (i < argv.length) {
+        const arg = argv[i];
+        const eq = arg.indexOf('=');
+        const flag = eq === -1 ? arg : arg.slice(0, eq);
+        const isSensitive = arg.startsWith('-') && SECRET_WORD.test(flag) && !/-env$/i.test(flag);
+        if (!isSensitive) {
+            out.push(redactText(arg));
+            i++;
+            continue;
+        }
+        if (eq !== -1) {
+            out.push(`${flag}=[REDACTED]`);
+            i++;
+            continue;
+        }
+        out.push(arg);
+        i++;
+        while (i < argv.length && looksLikeSensitiveFlag(argv[i])) {
+            out.push('[REDACTED]');
+            i++;
+        }
+        if (i < argv.length) {
+            out.push('[REDACTED]');
+            i++;
+        }
+    }
+    return out;
+}

package/dist/src/core/journal/requests.js

@@ -0,0 +1,132 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.digestOf = digestOf;
+exports.emitRequest = emitRequest;
+exports.listPendingRequests = listPendingRequests;
+exports.applyOutcome = applyOutcome;
+exports.ackFor = ackFor;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const crypto_1 = __importDefault(require("crypto"));
+const paths_1 = require("./paths");
+const redact_1 = require("./redact");
+const atomic_file_1 = require("../atomic-file");
+function digestOf(payload) {
+    return crypto_1.default.createHash('sha256').update(JSON.stringify(payload)).digest('hex');
+}
+function countPendingRequests(dir) {
+    try {
+        return fs_1.default.readdirSync(dir).filter((f) => f.endsWith('.json')).length;
+    }
+    catch {
+        return 0;
+    }
+}
+/** Publicacion atomica Y durable (R1.3, bloqueador 4): tmp + fsync + close +
+ *  rename + fsync del DIRECTORIO. Redaccion EN EL EMISOR; secreto literal en
+ *  flag sensible => rechazo sin persistir (R2.3). El segmento `seq` es un
+ *  conteo del directorio de requests AL MOMENTO DE EMITIR (no un contador
+ *  en memoria del proceso): las emisiones causalmente dependientes son, por
+ *  definicion, secuenciales desde la perspectiva del emisor (el agente
+ *  orquestador espera a que el proceso A termine — incluyendo su
+ *  fsyncDirSync — antes de lanzar el proceso B), asi que el archivo de A ya
+ *  esta durablemente presente cuando B escanea el directorio. Esto preserva
+ *  el orden causal AUN ENTRE PROCESOS SEPARADOS, a diferencia de un
+ *  contador en memoria por proceso (que reinicia en 0 en cada invocacion
+ *  nueva de la CLI). Emisores genuinamente independientes/concurrentes
+ *  pueden empatar en el conteo y caer al sufijo hex aleatorio — aceptable,
+ *  porque requests independientes no requieren orden relativo. */
+function emitRequest(repoRoot, branch, env) {
+    const payload = { ...env.payload };
+    if (Array.isArray(payload.argv)) {
+        const secretFlag = (0, redact_1.findLiteralSecretFlag)(payload.argv);
+        if (secretFlag !== null)
+            throw new Error(`secreto literal en ${secretFlag}: pasalo por referencia (-env), no por valor`);
+        payload.argv = (0, redact_1.redactArgv)(payload.argv);
+    }
+    const dir = (0, paths_1.requestsDir)(repoRoot, branch);
+    const seq = countPendingRequests(dir).toString().padStart(10, '0');
+    const requestId = `req-${Date.now()}-${seq}-${crypto_1.default.randomBytes(4).toString('hex')}`;
+    const body = JSON.stringify({ requestId, ...env, payload }, null, 2) + '\n';
+    const tmp = path_1.default.join(dir, `.${requestId}.tmp`);
+    const final = path_1.default.join(dir, `${requestId}.json`);
+    const fd = fs_1.default.openSync(tmp, 'wx', 0o600);
+    try {
+        fs_1.default.writeFileSync(fd, body);
+        fs_1.default.fsyncSync(fd);
+    }
+    finally {
+        fs_1.default.closeSync(fd);
+    }
+    fs_1.default.renameSync(tmp, final);
+    (0, atomic_file_1.fsyncDirSync)(dir); // la ENTRADA renombrada tambien debe sobrevivir un crash (R1.3)
+    return { requestId, idempotencyKey: env.idempotencyKey, payloadDigest: digestOf(payload), file: final };
+}
+const KNOWN_KINDS = ['job-request', 'register-entity', 'controller-heartbeat', 'verdict'];
+function isRecord(x) {
+    return typeof x === 'object' && x !== null && !Array.isArray(x);
+}
+function isWellFormedEnvelope(x) {
+    if (!isRecord(x))
+        return false;
+    return typeof x.requestId === 'string' && x.requestId.length > 0
+        && KNOWN_KINDS.includes(x.kind)
+        && typeof x.generationToken === 'string' && x.generationToken.length > 0
+        && typeof x.idempotencyKey === 'string' && x.idempotencyKey.length > 0
+        && isRecord(x.payload);
+}
+function listPendingRequests(repoRoot, branch) {
+    const dir = (0, paths_1.requestsDir)(repoRoot, branch);
+    return fs_1.default.readdirSync(dir).filter((f) => f.endsWith('.json')).sort().map((f) => {
+        const file = path_1.default.join(dir, f);
+        try {
+            const parsed = JSON.parse(fs_1.default.readFileSync(file, 'utf8'));
+            // Shape completa antes de cualquier uso downstream. JSON valido no
+            // implica envelope valido: payload/generation/idempotency ausentes
+            // tambien son corrupcion visible, no una excepcion del supervisor.
+            if (!isWellFormedEnvelope(parsed)) {
+                return { requestId: f, envelope: null, file, corrupt: true };
+            }
+            if (f !== `${parsed.requestId}.json`) {
+                return { requestId: f, envelope: null, file, corrupt: true };
+            }
+            return { requestId: parsed.requestId, envelope: parsed, file, corrupt: false };
+        }
+        catch {
+            return { requestId: f, envelope: null, file, corrupt: true };
+        }
+    });
+}
+/** Registro del resultado en el state (el ack es derivable — R1.3).
+ *  - mismo requestId ya registrado => no-op (replay seguro);
+ *  - misma idempotencyKey con digest DISTINTO => error explicito;
+ *  - misma idempotencyKey con mismo digest => ALIAS: el requestId nuevo
+ *    registra SU PROPIA entrada con el mismo outcome/resultRef, para poder
+ *    regenerar su ack (bloqueador 4 de la review).
+ *  Devuelve el state mutado (el caller es el supervisor, que luego hace
+ *  writeJournal — orden estado -> journal -> borrado de archivos). */
+function applyOutcome(state, applied) {
+    if (state.appliedRequests[applied.requestId] !== undefined)
+        return state;
+    const prior = Object.values(state.appliedRequests).find((a) => a.idempotencyKey === applied.idempotencyKey);
+    if (prior !== undefined && prior.payloadDigest !== applied.payloadDigest) {
+        if (applied.outcome === 'applied') {
+            throw new Error(`idempotencyKey ${applied.idempotencyKey} reutilizada con payload digest distinto`);
+        }
+        // outcome de rechazo: ninguna mutacion ocurrio, seguro registrar aun con digest distinto
+        state.appliedRequests[applied.requestId] = applied;
+        return state;
+    }
+    if (prior !== undefined) {
+        state.appliedRequests[applied.requestId] = { ...applied, outcome: prior.outcome, resultRef: prior.resultRef };
+        return state;
+    }
+    state.appliedRequests[applied.requestId] = applied;
+    return state;
+}
+function ackFor(state, requestId) {
+    return state.appliedRequests[requestId] ?? null;
+}

package/dist/src/core/journal/store.js

@@ -0,0 +1,107 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initJournal = initJournal;
+exports.readJournal = readJournal;
+exports.writeJournal = writeJournal;
+exports.appendEvent = appendEvent;
+const fs_1 = __importDefault(require("fs"));
+const atomic_file_1 = require("../atomic-file");
+const types_1 = require("./types");
+const paths_1 = require("./paths");
+/** Schema 1 evoluciono de forma aditiva durante R1. Normalizamos solamente
+ * campos que antes no existian; evidencia legacy queda deliberadamente con
+ * fingerprint vacio para que el gate la considere stale, nunca certificada. */
+function normalizeSchemaOne(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return value;
+    const parsed = structuredClone(value);
+    if (parsed.schema !== 1)
+        return parsed;
+    if (parsed.requestProblems === undefined)
+        parsed.requestProblems = [];
+    if (parsed.custodyDecisions === undefined)
+        parsed.custodyDecisions = [];
+    if (typeof parsed.cycle === 'object' && parsed.cycle !== null && !Array.isArray(parsed.cycle)) {
+        const cycle = parsed.cycle;
+        if (cycle.status === 'IN_PROGRESS' && cycle.nextAction === undefined) {
+            cycle.nextAction = { actionId: 'bootstrap-cycle', type: 'plan-cycle', target: 'cycle', preconditions: [], attempt: 0, state: 'pending' };
+        }
+    }
+    if (Array.isArray(parsed.verdicts)) {
+        for (const item of parsed.verdicts) {
+            if (typeof item !== 'object' || item === null || Array.isArray(item))
+                continue;
+            const verdict = item;
+            if (verdict.fingerprint === undefined)
+                verdict.fingerprint = '';
+            if (verdict.argv === undefined)
+                verdict.argv = [];
+            if (verdict.paths === undefined)
+                verdict.paths = [];
+            if (verdict.cwd === undefined)
+                verdict.cwd = '.';
+        }
+    }
+    return parsed;
+}
+function initJournal(repoRoot, branch) {
+    for (const d of [(0, paths_1.journalDir)(repoRoot, branch), (0, paths_1.requestsDir)(repoRoot, branch), (0, paths_1.acksDir)(repoRoot, branch), (0, paths_1.logsDir)(repoRoot, branch), (0, paths_1.exportDir)(repoRoot, branch)]) {
+        fs_1.default.mkdirSync(d, { recursive: true, mode: 0o700 });
+        fs_1.default.chmodSync(d, 0o700); // mkdirSync mode es umask-dependiente: fijar explicito (R1.2)
+    }
+    const sp = (0, paths_1.statePath)(repoRoot, branch);
+    if (!fs_1.default.existsSync(sp)) {
+        (0, atomic_file_1.writeFileAtomicDurable)(sp, JSON.stringify((0, types_1.emptyState)(branch), null, 2) + '\n', 0o600);
+    }
+}
+/** Lectura corrupt-aware (R1.6): sintaxis invalida O shape invalido => corrupt:true.
+ *  Los CONSUMIDORES deciden: consultas muestran 'corrupt'; gate/reconcile bloquean. */
+function readJournal(repoRoot, branch) {
+    const sp = (0, paths_1.statePath)(repoRoot, branch);
+    let raw;
+    try {
+        raw = fs_1.default.readFileSync(sp, 'utf8');
+    }
+    catch {
+        return { state: null, corrupt: true };
+    }
+    let parsed;
+    try {
+        parsed = normalizeSchemaOne(JSON.parse(raw));
+    }
+    catch {
+        return { state: null, corrupt: true, raw };
+    }
+    if (!(0, types_1.isWellFormedState)(parsed))
+        return { state: null, corrupt: true, raw };
+    return { state: parsed, corrupt: false, raw };
+}
+/** Escritura canonica: SOLO el supervisor la invoca (single-writer). CAS por
+ *  revision monotonica: el snapshot que traes debe ser el vigente. */
+function writeJournal(repoRoot, branch, state) {
+    if (state.branch !== branch)
+        throw new Error(`writeJournal: branch del estado (${state.branch}) no coincide con branch destino (${branch})`);
+    const current = readJournal(repoRoot, branch);
+    if (current.corrupt)
+        throw new Error('journal corrupto: no se escribe sobre corrupcion (R1.6)');
+    if (current.state !== null && current.state.revision !== state.revision) {
+        throw new Error(`revision desactualizada: disco=${current.state.revision} propuesta=${state.revision}`);
+    }
+    const next = { ...state, revision: state.revision + 1 };
+    if (!(0, types_1.isWellFormedState)(next))
+        throw new Error('writeJournal: estado propuesto con forma invalida, no se persiste (R1.6)');
+    (0, atomic_file_1.writeFileAtomicDurable)((0, paths_1.statePath)(repoRoot, branch), JSON.stringify(next, null, 2) + '\n', 0o600);
+}
+/** Auditoria derivada best-effort (R4.6): la escribe SOLO el supervisor, un
+ *  fallo aqui jamas invalida el estado — state.json es la unica autoridad. */
+function appendEvent(repoRoot, branch, event) {
+    try {
+        fs_1.default.appendFileSync((0, paths_1.eventsPath)(repoRoot, branch), JSON.stringify({ at: new Date().toISOString(), ...event }) + '\n', { mode: 0o600 });
+    }
+    catch {
+        // best-effort: un evento perdido no se reconstruye ni bloquea (R4.6)
+    }
+}