agentic-workflow-manager 6.2.1 → 6.4.0

package/README.md

@@ -60,3 +60,20 @@ npm run build
 npm link
 ```
 Now simply type `awm` from any path on your machine.
+
+### Parallel tracks
+
+Plans without `## Tracks` run serially exactly as before — parallelism is opt-in and there is
+nothing to migrate. A parallel plan must declare task membership, dependency/resource rows,
+and one JSON argv integration command. Start or resume with `awm watch`; inspect with
+`awm track status`. Track workers commit only their assigned files and request
+`awm track join`. The plan supervisor freezes and merges tracks, runs global QA once on the
+final HEAD, executes the canonical integration job once, then applies the interlock.
+
+Any missing declaration, overlap, global file class, unavailable worktree, or failed
+preparation degrades to serial with an event naming the cause. `BLOCKED` means ownership or
+identity was **not provable** and needs operator evidence; never delete a worktree, branch,
+lock, or process merely to make it proceed — that destroys the evidence of why it blocked.
+
+Full operating guide, including the fallback table and the `BLOCKED` diagnostic path:
+[`docs/guides/parallel-tracks.md`](../docs/guides/parallel-tracks.md).

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

@@ -1,12 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.computeGate = computeGate;
+exports.computeTrackGate = computeTrackGate;
 const LIVE = ['received', 'spawn-intent', 'claimed', 'running', 'cancel-requested'];
-function computeGate(state, corrupt, fingerprintNow) {
+function evaluateEvidence(state, fingerprintNow, scope) {
     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'}` });
     }
@@ -18,22 +16,25 @@ function computeGate(state, corrupt, fingerprintNow) {
             reasons.push({ category: 'live-job', detail: `job ${j.id} en ${j.executionState}` });
         }
     }
-    for (const t of state.tasks) {
+    const tasksInScope = scope.taskIds === undefined ? state.tasks : state.tasks.filter((t) => scope.taskIds.has(t.id));
+    for (const t of tasksInScope) {
         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}'` });
+    if (scope.requireGlobalKinds) {
+        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 allPlans = [...tasksInScope.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)) {
@@ -81,7 +82,7 @@ function computeGate(state, corrupt, fingerprintNow) {
             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 t of tasksInScope) {
         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}` });
@@ -116,3 +117,26 @@ function computeGate(state, corrupt, fingerprintNow) {
     }
     return { pass: reasons.length === 0, reasons };
 }
+function computeGate(state, corrupt, fingerprintNow) {
+    if (corrupt || state === null) {
+        return { pass: false, reasons: [{ category: 'corrupt', detail: 'state.json corrupto o ilegible: la corrupcion jamas certifica' }] };
+    }
+    return evaluateEvidence(state, fingerprintNow, { requireGlobalKinds: true });
+}
+/** Gate local de un track (C6, R3.5): NUNCA exige QA/interlock de ambito de
+ *  plan — solo la evidencia que el propio track declaro. Antes de evaluar,
+ *  exige `trackContext` (R3.2: la lista de tareas viene EXCLUSIVAMENTE de
+ *  ahi) y rechaza cualquier tarea que aparezca en el journal pero no en la
+ *  asignacion del track (R2.3) — nunca certifica por una tarea ajena que se
+ *  haya colado. */
+function computeTrackGate(state, corruptState, fingerprintNow) {
+    if (corruptState || state === null)
+        return { pass: false, reasons: [{ category: 'corrupt-state', detail: 'journal ausente o corrupto' }] };
+    if (state.trackContext === undefined)
+        return { pass: false, reasons: [{ category: 'wrong-context', detail: 'gate local requiere trackContext' }] };
+    const assigned = new Set(state.trackContext.taskIds);
+    const foreign = state.tasks.filter((task) => !assigned.has(task.id));
+    if (foreign.length > 0)
+        return { pass: false, reasons: foreign.map((task) => ({ category: 'foreign-task', detail: `task ${task.id} fuera del track` })) };
+    return evaluateEvidence(state, fingerprintNow, { requireGlobalKinds: false, taskIds: assigned });
+}

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

@@ -22,6 +22,7 @@ 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 context_1 = require("../../core/tracks/context");
 const fs_1 = __importDefault(require("fs"));
 function branchOf(cwd) {
     // stdio explicito (ver EXEC_STDIO en journal/process.ts): evita el relay
@@ -42,6 +43,20 @@ function realFingerprintNow(repo) {
         }
     };
 }
+/** Guard de entrada (R9.4): sin descriptor de track, es un no-op — el caso
+ *  comun de siempre no paga costo ni riesgo nuevo. Con descriptor presente
+ *  que no autentica (fencing/realpath/journalId no coinciden), rechaza ANTES
+ *  de que el verbo emita o consulte nada, mismo patron de salida que
+ *  verifyBranchInvariant mas abajo (stderr + exit 1). */
+function assertAuthenticatedCwd(repo, branch) {
+    try {
+        (0, context_1.resolveCommandContext)(repo, branch);
+    }
+    catch (e) {
+        process.stderr.write(`${e.message}\n`);
+        process.exit(1);
+    }
+}
 // CONSTITUTION: commander valida los tokens de las options declaradas; los
 // variadicos van tras `--`. Los flags numericos/JSON se validan fail-fast.
 function registerJobCommand(program) {
@@ -55,7 +70,9 @@ function registerJobCommand(program) {
         .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 });
+        const branch = branchOf(repo);
+        assertAuthenticatedCwd(repo, branch);
+        const r = (0, request_1.requestJob)(repo, branch, 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')
@@ -74,7 +91,9 @@ function registerJobCommand(program) {
         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), {
+        const branch = branchOf(repo);
+        assertAuthenticatedCwd(repo, branch);
+        const r = (0, requests_1.emitRequest)(repo, branch, {
             kind: 'register-entity', generationToken: opts.generation,
             idempotencyKey: crypto_1.default.createHash('sha256').update(`${opts.entity}:${opts.json}`).digest('hex'),
             payload: { entity: opts.entity, ...payload },
@@ -91,6 +110,8 @@ function registerJobCommand(program) {
         if (!['pass', 'fail', 'inconclusive'].includes(opts.result))
             throw new Error('--result debe ser pass | fail | inconclusive');
         const repo = process.cwd();
+        const branch = branchOf(repo);
+        assertAuthenticatedCwd(repo, branch);
         const reviewArgv = ['awm-review', opts.obligation];
         const reviewFingerprint = (0, fingerprint_1.computeFingerprint)(repo, reviewArgv, [], '.');
         // Determinista a partir de los MISMOS inputs que idempotencyKey, INCLUYENDO
@@ -104,7 +125,7 @@ function registerJobCommand(program) {
         // 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), {
+        (0, requests_1.emitRequest)(repo, branch, {
             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: {
@@ -116,17 +137,31 @@ function registerJobCommand(program) {
     });
     job.command('controller-heartbeat')
         .requiredOption('--generation <token>')
-        .action((opts) => { (0, heartbeat_1.emitHeartbeat)(process.cwd(), branchOf(process.cwd()), opts.generation); });
+        .action((opts) => {
+        const repo = process.cwd();
+        const branch = branchOf(repo);
+        assertAuthenticatedCwd(repo, branch);
+        (0, heartbeat_1.emitHeartbeat)(repo, branch, opts.generation);
+    });
     job.command('ps').action(() => {
-        process.stdout.write(JSON.stringify((0, query_1.queryPs)(process.cwd(), branchOf(process.cwd())), null, 2) + '\n');
+        const repo = process.cwd();
+        const branch = branchOf(repo);
+        assertAuthenticatedCwd(repo, branch);
+        process.stdout.write(JSON.stringify((0, query_1.queryPs)(repo, branch), null, 2) + '\n');
     });
     job.command('list').action(() => {
-        process.stdout.write(JSON.stringify((0, query_1.queryList)(process.cwd(), branchOf(process.cwd())), null, 2) + '\n');
+        const repo = process.cwd();
+        const branch = branchOf(repo);
+        assertAuthenticatedCwd(repo, branch);
+        process.stdout.write(JSON.stringify((0, query_1.queryList)(repo, branch), null, 2) + '\n');
     });
     job.command('show')
         .argument('<jobId>')
         .action((jobId) => {
-        const out = (0, query_1.queryShow)(process.cwd(), branchOf(process.cwd()), jobId);
+        const repo = process.cwd();
+        const branch = branchOf(repo);
+        assertAuthenticatedCwd(repo, branch);
+        const out = (0, query_1.queryShow)(repo, branch, jobId);
         process.stdout.write(JSON.stringify(out, null, 2) + '\n');
         if (out.corruptState || out.job === null)
             process.exit(1);
@@ -136,6 +171,7 @@ function registerJobCommand(program) {
         .action(() => {
         const repo = process.cwd();
         const branch = branchOf(repo);
+        assertAuthenticatedCwd(repo, branch);
         const r = (0, store_1.readJournal)(repo, branch);
         if (r.corrupt || r.state === null) {
             process.stdout.write(JSON.stringify({ corruptState: true }, null, 2) + '\n');
@@ -164,6 +200,7 @@ function registerJobCommand(program) {
         .action(() => {
         const repo = process.cwd();
         const branch = branchOf(repo);
+        assertAuthenticatedCwd(repo, branch);
         const r = (0, store_1.readJournal)(repo, branch);
         if (r.state !== null) {
             try {
@@ -185,7 +222,9 @@ function registerJobCommand(program) {
         .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));
+        const branch = branchOf(repo);
+        assertAuthenticatedCwd(repo, branch);
+        const r = (0, store_1.readJournal)(repo, branch);
         if (r.corrupt || r.state === null) {
             process.stderr.write('journal corrupto o ausente\n');
             process.exit(1);
@@ -205,6 +244,7 @@ function registerJobCommand(program) {
         .action((opts) => {
         const repo = process.cwd();
         const branch = branchOf(repo);
+        assertAuthenticatedCwd(repo, branch);
         const r = (0, store_1.readJournal)(repo, branch);
         if (r.corrupt || r.state === null) {
             process.stderr.write('journal corrupto\n');

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

@@ -7,21 +7,59 @@ exports.requestJob = requestJob;
 const crypto_1 = __importDefault(require("crypto"));
 const fingerprint_1 = require("../../core/journal/fingerprint");
 const requests_1 = require("../../core/journal/requests");
+const store_1 = require("../../core/journal/store");
+const git_1 = require("../../core/tracks/git");
+function argvDigest(argv) {
+    return crypto_1.default.createHash('sha256').update(JSON.stringify(argv)).digest('hex');
+}
 /** El agente NO ejecuta: registra la intencion (design R3.1). La idempotencyKey
- *  es hash(fingerprint + commandDigest) => get-or-create atomico (RNF-T.7).
- *  El cwd relativo REAL es parte del fingerprint (R3.4). `satisfies` enlaza el
- *  job con el item de VerificationPlan que pretende satisfacer (R1.4c). */
+ *  es hash(fingerprint + commandDigest + satisfies) => get-or-create atomico
+ *  (RNF-T.7). El cwd relativo REAL es parte del fingerprint (R3.4). `satisfies`
+ *  enlaza el job con el/los item(s) de VerificationPlan que pretende satisfacer
+ *  (R1.4c). R7 Task 12: `satisfies` migra a `string | string[]` — un caller
+ *  singular (todo el codigo pre-Task-12) produce la MISMA idempotencyKey que
+ *  antes (`[opts.satisfies].join('\0') === opts.satisfies`, y
+ *  `[].join('\0') === ''` para `undefined`): la identidad mecanica de jobs
+ *  existentes no cambia. El finalizer es el ÚNICO caller que pasa un array con
+ *  MÁS de un elemento — siempre el conjunto COMPLETO y ordenado de
+ *  `track-integration:*` de la cohorte (nunca un subconjunto, ver Step 5). */
 function requestJob(repoRoot, branch, generationToken, argv, paths, cwdRel, opts = {}) {
     const fp = (0, fingerprint_1.computeFingerprint)(repoRoot, argv, paths, cwdRel);
     // La obligacion es parte de la identidad de la REQUEST, no de la ejecucion:
-    // apply.ts reutiliza el job mecanicamente equivalente y enlaza el nuevo item.
-    const idempotencyKey = crypto_1.default.createHash('sha256').update(`${fp.fingerprint}:${fp.commandDigest}:${opts.satisfies ?? ''}`).digest('hex');
+    // apply.ts reutiliza el job mecanicamente equivalente y enlaza los items
+    // nuevos. El set se deduplica y ordena SIEMPRE — dos pedidos del mismo
+    // comando con el mismo conjunto de satisfiers (en cualquier orden) deben
+    // colapsar a la MISMA idempotencyKey.
+    const satisfies = opts.satisfies === undefined ? []
+        : Array.isArray(opts.satisfies) ? [...new Set(opts.satisfies)].sort() : [opts.satisfies];
+    const idempotencyKey = crypto_1.default.createHash('sha256')
+        .update(`${fp.fingerprint}:${fp.commandDigest}:${satisfies.join('\0')}`).digest('hex');
+    if (opts.verificationKind === 'track-integration') {
+        // Step 6 (R7.1/C3/C4): el job canónico de integración final SOLO se
+        // pide con todos los merges aplicados, árbol limpio, y exactamente el
+        // argv registrado como contrato de la cohorte — cualquier desviación
+        // se rechaza ANTES de tocar el requestsDir (fail-closed, nunca se
+        // emite una request que `apply.ts` tendría que rechazar después).
+        const r = (0, store_1.readJournal)(repoRoot, branch);
+        if (r.corrupt || r.state === null)
+            throw new Error('track-integration requiere journal legible (R1.6)');
+        const s = r.state;
+        if (s.tracks?.some((t) => t.phase !== 'MERGED_UNVERIFIED')) {
+            throw new Error('track-integration requiere todos los merges aplicados');
+        }
+        if ((0, git_1.dirtyPaths)(repoRoot).length > 0)
+            throw new Error('track-integration requiere árbol limpio');
+        if (s.trackIntegration === undefined)
+            throw new Error('track-integration requiere un contrato canónico registrado');
+        if (argvDigest(argv) !== argvDigest(s.trackIntegration.argv))
+            throw new Error('argv de integración no canónico');
+    }
     return (0, requests_1.emitRequest)(repoRoot, branch, {
         kind: 'job-request', generationToken, idempotencyKey,
         payload: {
             argv, paths, cwd: cwdRel,
             fingerprint: fp.fingerprint, commandDigest: fp.commandDigest, expandedPaths: fp.expandedPaths,
-            ...(opts.satisfies !== undefined ? { satisfies: opts.satisfies } : {}),
+            ...(satisfies.length > 0 ? { satisfies } : {}),
         },
     });
 }

package/dist/src/commands/track/emit.js

@@ -0,0 +1,26 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.emitTrackRequest = emitTrackRequest;
+// Emisores de requests de track (R6.1): `add`/`join`/`remove` jamas mutan
+// Git ni el journal directamente — el unico efecto observable es publicar
+// una request inmutable que el supervisor del plan consume despues (mismo
+// modelo single-writer de R1). La idempotencyKey se liga al journal
+// (branch), al track y al tipo de intent, para que un retry genuino del
+// mismo comando produzca la MISMA key (colapso seguro) mientras que dos
+// intents distintos sobre el mismo track jamas colisionan.
+const crypto_1 = __importDefault(require("crypto"));
+const requests_1 = require("../../core/journal/requests");
+function emitTrackRequest(repoRoot, branch, generationToken, kind, trackId) {
+    if (trackId.length === 0)
+        throw new Error('trackId obligatorio');
+    const payload = { trackId };
+    return (0, requests_1.emitRequest)(repoRoot, branch, {
+        kind, generationToken,
+        idempotencyKey: crypto_1.default.createHash('sha256')
+            .update(`${kind}\0${branch}\0${trackId}`).digest('hex'),
+        payload,
+    });
+}

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

@@ -0,0 +1,194 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerTrackCommand = registerTrackCommand;
+const child_process_1 = require("child_process");
+const fs_1 = __importDefault(require("fs"));
+const emit_1 = require("./emit");
+const status_1 = require("./status");
+const store_1 = require("../../core/journal/store");
+const process_1 = require("../../core/journal/process");
+const context_1 = require("../../core/tracks/context");
+const plan_parser_1 = require("../../core/tracks/plan-parser");
+const ownership_1 = require("../../core/tracks/ownership");
+const git_1 = require("../../core/tracks/git");
+const descriptor_1 = require("../../core/tracks/descriptor");
+const supervisor_wrapper_1 = require("./supervisor-wrapper");
+// Mismo patron que cli/src/commands/job/index.ts (branchOf/assertAuthenticatedCwd):
+// duplicado deliberadamente en vez de exportado desde job/index.ts, que no
+// expone esos helpers y no forma parte del alcance de esta task.
+function branchOf(cwd) {
+    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;
+}
+/** Unico punto que escribe a stderr y sale != 0 por un fallo de guard —
+ *  ambos guards de abajo comparten esta forma (R9.4). */
+function failGuard(message) {
+    process.stderr.write(`${message}\n`);
+    process.exit(1);
+}
+/** Autentica el cwd (R9.4) y devuelve el contexto resuelto: sin descriptor
+ *  de track es un no-op que resuelve a modo plan (caso comun); con
+ *  descriptor presente que no autentica, rechaza ANTES de que el verbo
+ *  emita o consulte nada. */
+function resolveGuardedContext(repo, branch) {
+    try {
+        return (0, context_1.resolveCommandContext)(repo, branch);
+    }
+    catch (e) {
+        failGuard(e.message);
+    }
+}
+/** Guard de entrada identico al de `awm job`/`awm watch`: solo autentica. */
+function assertAuthenticatedCwd(repo, branch) {
+    resolveGuardedContext(repo, branch);
+}
+/** Guard mas estricto para `list`/`status`: ambos verbos agregan el journal
+ *  del PLAN (R9.5/R9.6 — `tracks` solo existe ahi, nunca en el journal de un
+ *  track individual). Sin esto, correrlos desde el worktree de un track
+ *  produce silenciosamente "sin tracks declarados" — indistinguible de un
+ *  plan serial/vacio genuino. */
+function assertPlanCwd(repo, branch) {
+    const ctx = resolveGuardedContext(repo, branch);
+    if (ctx.mode === 'track') {
+        failGuard(`este cwd es el worktree del track '${ctx.context.trackContext.trackId}', no la raiz del plan: `
+            + `'awm track list'/'status' agregan el journal del PLAN — corre el comando desde ahi`);
+    }
+}
+function registerTrackCommand(program) {
+    const track = program.command('track').description('tracks paralelos sobre worktrees (R5): superficie request-only + status agregado read-only');
+    // --- Verbos mutantes: SOLO emiten una request (R6.1). Jamas tocan Git ni
+    // el journal directamente — el supervisor del plan la consume despues.
+    track.command('add')
+        .description('emite track-prepare-request — el supervisor del plan la consume (R6.1)')
+        .requiredOption('--generation <token>', 'token de la generacion vigente')
+        .argument('<trackId>')
+        .action((trackId, opts) => {
+        const repo = process.cwd();
+        const branch = branchOf(repo);
+        assertAuthenticatedCwd(repo, branch);
+        const r = (0, emit_1.emitTrackRequest)(repo, branch, opts.generation, 'track-prepare-request', trackId);
+        process.stdout.write(JSON.stringify({ requestId: r.requestId, idempotencyKey: r.idempotencyKey }, null, 2) + '\n');
+    });
+    track.command('join')
+        .description('emite track-join-request — integracion es propiedad exclusiva del supervisor del plan (R6.1)')
+        .requiredOption('--generation <token>', 'token de la generacion vigente')
+        .argument('<trackId>')
+        .action((trackId, opts) => {
+        const repo = process.cwd();
+        const branch = branchOf(repo);
+        assertAuthenticatedCwd(repo, branch);
+        const r = (0, emit_1.emitTrackRequest)(repo, branch, opts.generation, 'track-join-request', trackId);
+        process.stdout.write(JSON.stringify({ requestId: r.requestId, idempotencyKey: r.idempotencyKey }, null, 2) + '\n');
+    });
+    track.command('remove')
+        .description('emite track-teardown-request — el supervisor del plan desmantela worktree/rama (R6.1)')
+        .requiredOption('--generation <token>', 'token de la generacion vigente')
+        .argument('<trackId>')
+        .action((trackId, opts) => {
+        const repo = process.cwd();
+        const branch = branchOf(repo);
+        assertAuthenticatedCwd(repo, branch);
+        const r = (0, emit_1.emitTrackRequest)(repo, branch, opts.generation, 'track-teardown-request', trackId);
+        process.stdout.write(JSON.stringify({ requestId: r.requestId, idempotencyKey: r.idempotencyKey }, null, 2) + '\n');
+    });
+    // --- Verbos read-only: nunca aceptan --generation ni emiten requests.
+    track.command('list')
+        .description('lista los TrackRef declarados en el journal del plan (read-only)')
+        .action(() => {
+        const repo = process.cwd();
+        const branch = branchOf(repo);
+        assertPlanCwd(repo, branch);
+        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);
+        }
+        process.stdout.write(JSON.stringify({ tracks: r.state.tracks ?? [] }, null, 2) + '\n');
+    });
+    track.command('status')
+        .description('agregado read-only: compone el gate de cada journal de track + fase de la cohorte (R9.5, R9.6)')
+        .action(() => {
+        const repo = process.cwd();
+        const branch = branchOf(repo);
+        assertPlanCwd(repo, branch);
+        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);
+        }
+        const out = (0, status_1.aggregateTrackStatus)(repo, r.state);
+        process.stdout.write(JSON.stringify(out, null, 2) + '\n');
+        // Fail-closed (R3.2 aplicado por composicion, R9.6): CUALQUIER
+        // track con gate rojo — corrupto, bloqueado o con evidencia
+        // pendiente — hace que `status` salga != 0, aunque el agregado
+        // completo ya se haya impreso arriba.
+        if (Object.values(out.tracks).some((t) => !t.gate.pass))
+            process.exit(1);
+    });
+    track.command('verify-independence')
+        .description('R5.10: verifica independencia declarada de un plan de tracks; invocable por argv, sale != 0 ante cualquier violacion')
+        .requiredOption('--plan <file>', 'ruta al plan markdown con membresia de Track y tabla ## Tracks')
+        .action((opts) => {
+        // R5.10: sale != 0 ante CUALQUIER violacion, incluyendo que la
+        // tuberia leer-plan -> parsear -> evaluar independencia lance
+        // sincronicamente (id de track peligroso, `Integration argv`
+        // no-JSON, `Shared resources` sin forma `<clase>:<valor>`, etc.)
+        // — nunca un stack trace crudo. El try envuelve la tuberia
+        // ENTERA a proposito (no solo el parseo) y el `process.exit` de
+        // abajo vive AFUERA de el: los tests mockean `process.exit` para
+        // que *lance*, y si ese exit ocurriera dentro del try se
+        // re-atraparia como un fallo de dominio mas.
+        let result;
+        try {
+            const source = fs_1.default.readFileSync(opts.plan, 'utf8');
+            const parsed = (0, plan_parser_1.parseTrackPlan)(source, git_1.gitCheckTrackId);
+            result = parsed.mode === 'serial'
+                // Un plan que ni siquiera califica como candidato paralelo
+                // (recursos compartidos sin declarar, dependencias entre
+                // tracks, etc.) es, por definicion, una violacion de R5.10.
+                ? { parallel: false, reasons: [parsed.reason] }
+                : (0, ownership_1.assessDeclaredIndependence)(Object.values(parsed.tracks));
+        }
+        catch (e) {
+            result = { parallel: false, reasons: [`parse-error:${e.message}`] };
+        }
+        process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+        if (!result.parallel)
+            process.exit(1);
+    });
+    // --- supervisor-wrapper: PROCESO EXTERNO detached (Step 5, R4.7-R4.10,
+    // C11). El supervisor del plan lo spawnea con el cwd fijado en el
+    // worktree del track — jamás se invoca a mano. Autentica el descriptor
+    // local (mismo patrón que R9.4) antes de reclamar nada: un cwd sin
+    // descriptor o con un descriptor que no coincide con el argv recibido
+    // jamás llega a tocar el claim.
+    track.command('supervisor-wrapper')
+        .description('PROCESO INTERNO: lanzado detached por el supervisor del plan (R4.7) — no invocar a mano')
+        .requiredOption('--track <id>')
+        .requiredOption('--readiness <nonce>')
+        .requiredOption('--fence <token>')
+        // R4.7/C11: el nonce del `supervisorIntent` persistido por el plan
+        // (tracks.ts) ANTES de spawnear este wrapper — NUNCA generado acá.
+        // Sin este flag, `observeSupervisorFromDisk` no tiene con qué
+        // comparar la identidad y todo wrapper legítimo quedaría 'foreign'.
+        .requiredOption('--nonce <n>')
+        .action(async (opts) => {
+        const worktreePath = process.cwd();
+        const descriptor = (0, descriptor_1.readDescriptor)(worktreePath);
+        if (descriptor === null)
+            failGuard('supervisor-wrapper: sin descriptor de track en este cwd — no autenticado');
+        if (descriptor.trackId !== opts.track || descriptor.fencingToken !== opts.fence) {
+            failGuard('supervisor-wrapper: descriptor no coincide con los argumentos recibidos — abortando');
+        }
+        await (0, supervisor_wrapper_1.runSupervisorWrapper)({
+            worktreePath, trackId: opts.track, nonce: opts.nonce, readinessNonce: opts.readiness, fencingToken: opts.fence,
+            planRoot: descriptor.planRoot, planBranch: descriptor.planBranch,
+        });
+        process.exit(0); // C11: tanto "ya reclamado" como "arrancado" salen 0 — jamás un segundo supervisor
+    });
+}

package/dist/src/commands/track/status.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fingerprintFor = fingerprintFor;
+exports.deriveCohortPhase = deriveCohortPhase;
+exports.aggregateTrackStatus = aggregateTrackStatus;
+// Agregado read-only de status por track (R9.5, R9.6): el journal del PLAN
+// jamas espeja el estado de los journals de track — cada consulta lee el
+// journal observado del track AL MOMENTO de necesitarlo y compone su gate,
+// sin escribir nada de vuelta al plan journal.
+const fingerprint_1 = require("../../core/journal/fingerprint");
+const store_1 = require("../../core/journal/store");
+const types_1 = require("../../core/tracks/types");
+const gate_1 = require("../job/gate");
+/** Espejo de `realFingerprintNow` (cli/src/commands/job/index.ts) pero
+ *  cerrado sobre el worktree OBSERVADO del track, no sobre el repo desde el
+ *  que corre el comando `awm track status` (que es el del plan). */
+function fingerprintFor(worktreePath) {
+    return (argv, paths, cwd) => {
+        try {
+            return (0, fingerprint_1.computeFingerprint)(worktreePath, argv, paths, cwd).fingerprint;
+        }
+        catch {
+            return null;
+        }
+    };
+}
+/** String de DISPLAY para un humano corriendo `awm track status` — no es
+ *  input de ninguna decision de protocolo (esa vive en tracks/protocol.ts).
+ *  Reporta el cuello de botella: cualquier track BLOCKED domina el mensaje;
+ *  si no hay ninguno, se muestra la fase MENOS avanzada segun el orden
+ *  canonico de TRACK_PHASES (la que atrasa a la cohorte) y cuantos tracks
+ *  comparten esa fase. */
+function deriveCohortPhase(tracks) {
+    if (tracks.length === 0)
+        return 'sin tracks declarados';
+    const blocked = tracks.filter((t) => t.phase === 'BLOCKED');
+    if (blocked.length > 0) {
+        return `BLOCKED: ${blocked.map((t) => t.trackId).sort().join(', ')}`;
+    }
+    const rank = (phase) => types_1.TRACK_PHASES.indexOf(phase);
+    const bottleneck = tracks.reduce((min, t) => (rank(t.phase) < rank(min.phase) ? t : min));
+    const atBottleneck = tracks.filter((t) => t.phase === bottleneck.phase).length;
+    return `${bottleneck.phase} (${atBottleneck}/${tracks.length})`;
+}
+/** `planRoot` no se usa para leer el journal del PLAN (ese ya se leyo antes
+ *  de llamar aca) — se recibe por simetria con la firma del plan y para que
+ *  el llamador no tenga que reconstruirla; cada TrackRef ya trae su propio
+ *  `worktreePath`/`branch` absolutos (R9.2), que es lo que efectivamente se
+ *  lee. Un journal de track que no puede leerse (corrupto o ausente) nunca
+ *  se descarta en silencio: su gate sale rojo con categoria `corrupt-state`,
+ *  igual que cualquier otra corrupcion en este codebase (R1.6). */
+function aggregateTrackStatus(planRoot, plan) {
+    const refs = plan.tracks ?? [];
+    const tracks = {};
+    for (const ref of refs) {
+        const observed = (0, store_1.readJournal)(ref.worktreePath, ref.branch);
+        tracks[ref.trackId] = {
+            phase: ref.phase,
+            gate: (0, gate_1.computeTrackGate)(observed.state, observed.corrupt, fingerprintFor(ref.worktreePath)),
+        };
+    }
+    return { cohort: deriveCohortPhase(refs), tracks };
+}