agentic-workflow-manager 3.3.1 → 3.5.0

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

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

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

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

package/dist/src/core/export/pack.js

@@ -13,6 +13,12 @@ exports.packSkill = packSkill;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const child_process_1 = require("child_process");
+// stdio explicito: sin esto, spawnSync relayea el stderr del `zip` hijo hacia
+// el stderr del proceso llamante (default `inheritStderr` de Node cuando no
+// se pasa `stdio`) — si ese fd fuera un pipe roto/destruido, el relay mismo
+// dispara un EPIPE no catcheable que crashea al llamante (mismo bug de raiz
+// que motivo EXEC_STDIO en core/journal/process.ts).
+const EXEC_STDIO = ['ignore', 'pipe', 'pipe'];
 /** Refuses symlinks anywhere in the tree — copying/zipping them could dereference
  * into content outside the registry (info-leak) or embed a broken/unexpected
  * link for the recipient. Exported artifacts are plain files only. */
@@ -28,7 +34,7 @@ function assertNoSymlinks(dir) {
 }
 /** Capa 1: binario `zip` del sistema. ENOENT → missing (capa 2: carpeta). */
 const defaultZip = (cwd, zipName, folderName) => {
-    const r = (0, child_process_1.spawnSync)('zip', ['-r', '-q', zipName, folderName], { cwd });
+    const r = (0, child_process_1.spawnSync)('zip', ['-r', '-q', zipName, folderName], { cwd, stdio: EXEC_STDIO });
     if (r.error && r.error.code === 'ENOENT') {
         return { ok: false, missing: true };
     }

package/dist/src/core/export/transform.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFERENCE_LINE = void 0;
+exports.stripIntraRegistryPaths = stripIntraRegistryPaths;
 exports.claudeAiTransform = claudeAiTransform;
 // cli/src/core/export/transform.ts
 //
@@ -9,6 +10,53 @@ exports.claudeAiTransform = claudeAiTransform;
 // línea) — sin parser YAML a propósito (YAGNI, cero deps).
 const DEFERENCE_LINE = (skillName) => `In environments with AWM installed (Claude Code), defer to the registry's ${skillName} skill — this port is for environments without filesystem access.`;
 exports.DEFERENCE_LINE = DEFERENCE_LINE;
+// Paths intra-registry: resuelven en Claude Code (donde el registry está en
+// disco) y nunca en claude.ai, donde solo se sube la skill portable. Se limpian
+// en el artefacto exportado en vez de editar el SKILL.md canónico, que en Claude
+// Code sí los necesita.
+const SKILL_NAME = '[a-z0-9][a-z0-9-]*';
+const REF_FILE = '[A-Za-z0-9._-]+';
+const PATH_SRC = '(?:skills\\/' + SKILL_NAME + '\\/references\\/' + REF_FILE + '\\.md'
+    + '|skills\\/' + SKILL_NAME + '\\/SKILL\\.md)';
+/** Reconoce, en una sola pasada sobre el body ORIGINAL, tanto el caso
+ * "paréntesis cuyo único contenido es un path" (grupo 1) como el path suelto
+ * en cualquier otra posición (grupo 2). Una sola pasada evita un bug real de
+ * splicing encontrado en code review: si se borrara el paréntesis en una
+ * pasada separada, un path inmediatamente siguiente podría quedar pegado a
+ * texto que antes terminaba en `/` (el cierre de una URL, p. ej.), y el guard
+ * de "embebido en URL" (que mira el carácter previo) confundiría eso con un
+ * path genuinamente embebido. Matcheando todo en una sola pasada contra el
+ * string original, cada offset que llega a `isEmbeddedInUrl` es siempre real,
+ * nunca un artefacto de un borrado previo. */
+const PATH_OR_DROPPED_PAREN = new RegExp('([ \\t]*\\((?:see[ \\t]+)?`?' + PATH_SRC + '`?\\))' + '|' + '(`?' + PATH_SRC + '`?)', 'g');
+/** Un path precedido por `/` es el final de una URL o de un path más largo (un
+ * enlace a GitHub, por ejemplo). Esas referencias SÍ resuelven para quien lee la
+ * skill en claude.ai, así que no se tocan. */
+function isEmbeddedInUrl(haystack, matchStart, matched) {
+    const pathStart = matchStart + matched.indexOf('skills/');
+    return pathStart > 0 && haystack[pathStart - 1] === '/';
+}
+const PATH_MATCHER = new RegExp('^skills\\/(' + SKILL_NAME + ')\\/references\\/(' + REF_FILE + ')\\.md$'
+    + '|^skills\\/(' + SKILL_NAME + ')\\/SKILL\\.md$');
+function pathlessForm(p) {
+    const m = PATH_MATCHER.exec(p);
+    if (!m)
+        throw new Error(`unreachable: "${p}" matched PATH_SRC but not PATH_MATCHER — the two must stay in sync`);
+    const [, refSkill, refFile, skillOnlyName] = m;
+    if (skillOnlyName !== undefined)
+        return `the \`${skillOnlyName}\` skill`;
+    return `the \`${refSkill}\` skill's ${refFile.replace(/-/g, ' ')} reference`;
+}
+function stripIntraRegistryPaths(body) {
+    return body.replace(PATH_OR_DROPPED_PAREN, (match, parenForm, bareForm, offset) => {
+        if (isEmbeddedInUrl(body, offset, match))
+            return match;
+        if (parenForm !== undefined)
+            return '';
+        const path = bareForm.replace(/^`|`$/g, '');
+        return pathlessForm(path);
+    });
+}
 function claudeAiTransform(skillMd, skillName) {
     // \r?\n-tolerant, same rationale as readArtifactDescription in discovery.ts:
     // SKILL.md files may be CRLF-terminated and that's still valid frontmatter.
@@ -53,5 +101,7 @@ function claudeAiTransform(skillMd, skillName) {
             ? `${value.slice(0, -1)} ${deference.replace(/'/g, "''")}'`
             : `${value} ${deference}`;
     fmLines[descIdx] = `description: ${newValue}`;
-    return `---\n${fmLines.join('\n')}\n---\n${body}`;
+    // Solo el body: el frontmatter ya se editó arriba y sus campos no son prosa
+    // navegable (R2.4).
+    return `---\n${fmLines.join('\n')}\n---\n${stripIntraRegistryPaths(body)}`;
 }

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

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.adapterFor = adapterFor;
+const process_1 = require("./process");
+const RESUME_PROMPT_PREFIX = 'Sos el orquestador SDD de este repo. Corre `awm job reconcile` y ejecuta ';
+function baseSafeToReplace(ref) {
+    return (0, process_1.refIsAlive)(ref) ? 'indeterminate' : 'safe';
+}
+const codexAdapter = {
+    provider: 'codex',
+    launchArgv: (resumePrompt) => ['codex', 'exec', `${RESUME_PROMPT_PREFIX}${resumePrompt}`],
+    activity: process_1.activitySnapshot,
+    safeToReplace: baseSafeToReplace,
+};
+const claudeAdapter = {
+    provider: 'claude-code',
+    launchArgv: (resumePrompt) => ['claude', '-p', `${RESUME_PROMPT_PREFIX}${resumePrompt}`],
+    activity: process_1.activitySnapshot,
+    safeToReplace: baseSafeToReplace,
+};
+function adapterFor(provider) {
+    if (provider === 'codex')
+        return codexAdapter;
+    if (provider === 'claude-code')
+        return claudeAdapter;
+    throw new Error(`provider desconocido: ${provider} (validos: codex, claude-code)`);
+}

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

@@ -0,0 +1,80 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveWorkingDirectory = resolveWorkingDirectory;
+exports.computeFingerprint = computeFingerprint;
+const crypto_1 = __importDefault(require("crypto"));
+const path_1 = __importDefault(require("path"));
+const fs_1 = __importDefault(require("fs"));
+const child_process_1 = require("child_process");
+const process_1 = require("./process");
+function sha(parts) {
+    return crypto_1.default.createHash('sha256').update(parts.join('\0')).digest('hex');
+}
+// Sin ceiling de maxBuffer: repos grandes (`ls-files` / `ls-files --stage` en
+// miles de archivos) pueden superar el default de Node (1MB) y abortar con ENOBUFS.
+// stdio explicito (ver EXEC_STDIO en process.ts): sin esto, execFileSync relayea
+// el stderr de git hacia el stderr DEL SUPERVISOR — si ese fd es un pipe roto, el
+// relay dispara un EPIPE no catcheable que crashea el proceso ENTERO (este helper
+// backea computeFingerprint, invocado en CADA tick via FingerprintNow/computeGate).
+function git(cwd, args) {
+    return (0, child_process_1.execFileSync)('git', args, { cwd, encoding: 'utf8', maxBuffer: Infinity, stdio: process_1.EXEC_STDIO });
+}
+function resolveWorkingDirectory(repoRoot, cwdRel) {
+    if (typeof cwdRel !== 'string' || cwdRel.length === 0)
+        throw new Error('cwd relativo requerido');
+    const relative = path_1.default.normalize(cwdRel);
+    if (path_1.default.isAbsolute(relative) || relative === '..' || relative.startsWith(`..${path_1.default.sep}`)) {
+        throw new Error(`cwd fuera del repo: ${JSON.stringify(cwdRel)}`);
+    }
+    const root = fs_1.default.realpathSync(repoRoot);
+    let cursor = root;
+    for (const segment of relative.split(path_1.default.sep).filter((part) => part !== '.')) {
+        cursor = path_1.default.join(cursor, segment);
+        const stat = fs_1.default.lstatSync(cursor);
+        if (stat.isSymbolicLink())
+            throw new Error(`cwd contiene symlink no permitido: ${JSON.stringify(cwdRel)}`);
+    }
+    const absolute = fs_1.default.realpathSync(path_1.default.join(root, relative));
+    if (absolute !== root && !absolute.startsWith(`${root}${path_1.default.sep}`))
+        throw new Error(`cwd fuera del repo: ${JSON.stringify(cwdRel)}`);
+    if (!fs_1.default.statSync(absolute).isDirectory())
+        throw new Error(`cwd no es directorio: ${JSON.stringify(cwdRel)}`);
+    return { relative: relative.split(path_1.default.sep).join('/'), absolute };
+}
+/** El journal jamás invalida evidencia: .awm/ queda fuera de toda expansión. */
+const EXCLUDE_JOURNAL = ':(exclude).awm';
+/** Componentes SEPARADOS (design R3.4, bloqueador 7 de la review):
+ *  argv exacto + cwd relativo REAL + HEAD + índice real (`ls-files --stage`
+ *  hasheado) + digest de contenido por archivo tracked/untracked/deleted. */
+function computeFingerprint(repoRoot, argv, pathGlobs, cwdRel) {
+    if (!Array.isArray(argv) || argv.length === 0)
+        throw new Error('argv vacio');
+    const cwdNorm = resolveWorkingDirectory(repoRoot, cwdRel).relative;
+    const commandDigest = sha(argv);
+    const head = git(repoRoot, ['rev-parse', 'HEAD']).trim();
+    const pathspecs = pathGlobs.length > 0 ? pathGlobs : ['.'];
+    // Índice REAL: modos + blobs + stages + paths — un cambio staged-only con
+    // worktree idéntico produce salida distinta aquí. Sin -z a propósito: esta
+    // salida se hashea completa como texto opaco, nunca se separa en paths
+    // individuales, así que el quoting de core.quotePath es inofensivo aquí
+    // (a diferencia de expandedPaths abajo, cuyos paths SÍ se re-extraen para
+    // pasarlos a `hash-object` — por eso ese caso sí necesita -z).
+    const indexRaw = git(repoRoot, ['ls-files', '--stage', '--', ...pathspecs, EXCLUDE_JOURNAL]);
+    const indexDigest = sha([indexRaw]);
+    const expandedPaths = git(repoRoot, ['ls-files', '-z', '--cached', '--others', '--exclude-standard', '--', ...pathspecs, EXCLUDE_JOURNAL])
+        .split('\0').filter(Boolean).sort();
+    const perFile = expandedPaths.map((p) => {
+        try {
+            return `${p}:${git(repoRoot, ['hash-object', '--', p]).trim()}`;
+        }
+        catch {
+            return `${p}:deleted`; // listado pero ilegible/borrado del worktree: cuenta como cambio
+        }
+    });
+    const declaredPaths = pathGlobs.length > 0 ? pathGlobs : ['.'];
+    const fingerprint = sha([commandDigest, `cwd:${cwdNorm}`, `paths:${JSON.stringify(declaredPaths)}`, `head:${head}`, `index:${indexDigest}`, ...perFile]);
+    return { fingerprint, commandDigest, expandedPaths };
+}

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

@@ -0,0 +1,56 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.branchSlug = branchSlug;
+exports.journalDir = journalDir;
+exports.supervisorLockPath = supervisorLockPath;
+exports.statePath = statePath;
+exports.requestsDir = requestsDir;
+exports.acksDir = acksDir;
+exports.logsDir = logsDir;
+exports.eventsPath = eventsPath;
+exports.exportDir = exportDir;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+function branchSlug(branch) {
+    if (!branch || branch === '.' || branch.includes('..')) {
+        throw new Error(`branch inválida para slug: ${JSON.stringify(branch)}`);
+    }
+    // Escapa PRIMERO el propio caracter de escape (_), despues / y \ — así
+    // ningún guion bajo literal sobrevive sin escapar, lo que hace la
+    // codificación biyectiva: dos ramas distintas nunca pueden colisionar
+    // (bloqueador encontrado en code-quality review de Task 3).
+    return branch
+        .replace(/_/g, '_5F')
+        .replace(/\//g, '_2F')
+        .replace(/\\/g, '_5C');
+}
+function journalDir(repoRoot, branch) {
+    return path_1.default.join(repoRoot, '.awm', 'journal', branchSlug(branch));
+}
+/** Lock único por worktree FÍSICO: clavado por realpath, fuera del dir de rama
+ *  (design R1.1, bloqueante v5-5: dos ramas jamás toman locks distintos sobre
+ *  el mismo árbol). */
+function supervisorLockPath(repoRoot) {
+    return path_1.default.join(fs_1.default.realpathSync(repoRoot), '.awm', 'journal', 'supervisor.lock');
+}
+function statePath(repoRoot, branch) {
+    return path_1.default.join(journalDir(repoRoot, branch), 'state.json');
+}
+function requestsDir(repoRoot, branch) {
+    return path_1.default.join(journalDir(repoRoot, branch), 'requests');
+}
+function acksDir(repoRoot, branch) {
+    return path_1.default.join(journalDir(repoRoot, branch), 'acks');
+}
+function logsDir(repoRoot, branch) {
+    return path_1.default.join(journalDir(repoRoot, branch), 'logs');
+}
+function eventsPath(repoRoot, branch) {
+    return path_1.default.join(journalDir(repoRoot, branch), 'events.jsonl');
+}
+function exportDir(repoRoot, branch) {
+    return path_1.default.join(journalDir(repoRoot, branch), 'export');
+}