agentic-workflow-manager 6.2.1 → 6.3.0

package/dist/tests/commands/track/supervisor-wrapper.test.js

@@ -0,0 +1,131 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Task 8 (R5-T8, Step 5): claim exact-once + identity + readiness sidecars +
+// espera read-only al propio TrackRef del plan. Ningún proceso real se
+// spawnea (launchWatch es inyectado); el único I/O real es el journal del
+// plan y los sidecars bajo `.awm/` del propio worktree (tmpdirs).
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+const child_process_1 = require("child_process");
+const supervisor_wrapper_1 = require("../../../src/commands/track/supervisor-wrapper");
+const tracks_1 = require("../../../src/commands/watch/tracks");
+const store_1 = require("../../../src/core/journal/store");
+const paths_1 = require("../../../src/core/journal/paths");
+const fixtures_1 = require("./fixtures");
+const NONCE = 'the-real-supervisor-intent-nonce';
+function git(repo, args) {
+    (0, child_process_1.execFileSync)('git', args, { cwd: repo });
+}
+function gitInit(repo, branch) {
+    git(repo, ['-c', 'user.email=t@t.t', '-c', 'user.name=t', '-c', 'commit.gpgsign=false', 'init', '-q', '-b', branch]);
+    fs_1.default.writeFileSync(path_1.default.join(repo, 'f.txt'), 'x');
+    git(repo, ['-c', 'user.email=t@t.t', '-c', 'user.name=t', '-c', 'commit.gpgsign=false', 'add', '.']);
+    git(repo, ['-c', 'user.email=t@t.t', '-c', 'user.name=t', '-c', 'commit.gpgsign=false', 'commit', '-qm', 'c']);
+}
+describe('runSupervisorWrapper — claim exact-once + espera read-only del ACTIVE (R4.7-R4.10, C11)', () => {
+    let planRoot;
+    let worktreePath;
+    beforeEach(() => {
+        planRoot = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-wrapper-plan-'));
+        worktreePath = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-wrapper-wt-'));
+        gitInit(planRoot, 'main');
+        gitInit(worktreePath, 'awm-track/cli');
+        (0, store_1.initJournal)(planRoot, 'main');
+    });
+    afterEach(() => {
+        fs_1.default.rmSync(planRoot, { recursive: true, force: true });
+        fs_1.default.rmSync(worktreePath, { recursive: true, force: true });
+    });
+    function seedTrackRef(phase) {
+        const s = (0, store_1.readJournal)(planRoot, 'main').state;
+        s.tracks = [
+            (0, fixtures_1.trackRefFixture)({ trackId: 'cli', phase, readinessNonce: 'nonce-cli'.padEnd(32, '0') }, worktreePath),
+            (0, fixtures_1.trackRefFixture)({ trackId: 'docs', phase: 'ACTIVE' }, worktreePath),
+        ];
+        (0, store_1.writeJournal)(planRoot, 'main', s);
+    }
+    test('claim exact-once: identity + readiness sidecars, espera ACTIVE, lanza watch y espera el lock (R4.7, R4.8)', async () => {
+        seedTrackRef('ARMED');
+        let launched = null;
+        const wrapperPromise = (0, supervisor_wrapper_1.runSupervisorWrapper)({
+            worktreePath, trackId: 'cli', nonce: NONCE, readinessNonce: 'nonce-cli'.padEnd(32, '0'), fencingToken: 'fence',
+            planRoot, planBranch: 'main', pollMs: 5,
+            launchWatch: (wt) => {
+                launched = wt;
+                fs_1.default.mkdirSync(path_1.default.dirname((0, paths_1.supervisorLockPath)(wt)), { recursive: true });
+                fs_1.default.writeFileSync((0, paths_1.supervisorLockPath)(wt), '{}');
+            },
+        });
+        // Todavía ARMED: el wrapper debe seguir esperando (no lanza watch).
+        await new Promise((r) => setTimeout(r, 30));
+        expect(launched).toBeNull();
+        seedTrackRef('ACTIVE');
+        const outcome = await wrapperPromise;
+        expect(outcome).toBe('active');
+        expect(launched).toBe(worktreePath);
+        expect(fs_1.default.existsSync(path_1.default.join(worktreePath, '.awm', 'supervisor.claim'))).toBe(true);
+        const identity = JSON.parse(fs_1.default.readFileSync(path_1.default.join(worktreePath, '.awm', 'supervisor.identity.json'), 'utf8'));
+        expect(identity.trackId).toBe('cli');
+        const ready = JSON.parse(fs_1.default.readFileSync(path_1.default.join(worktreePath, '.awm', 'supervisor.ready.json'), 'utf8'));
+        expect(ready.readinessNonce).toBe('nonce-cli'.padEnd(32, '0'));
+    });
+    test('un segundo wrapper con el mismo claim detecta el claim existente y sale sin lanzar otro supervisor (C11)', async () => {
+        seedTrackRef('ACTIVE');
+        const first = await (0, supervisor_wrapper_1.runSupervisorWrapper)({
+            worktreePath, trackId: 'cli', nonce: NONCE, readinessNonce: 'nonce-cli'.padEnd(32, '0'), fencingToken: 'fence',
+            planRoot, planBranch: 'main', pollMs: 5,
+            launchWatch: () => {
+                fs_1.default.mkdirSync(path_1.default.dirname((0, paths_1.supervisorLockPath)(worktreePath)), { recursive: true });
+                fs_1.default.writeFileSync((0, paths_1.supervisorLockPath)(worktreePath), '{}');
+            },
+        });
+        expect(first).toBe('active');
+        let secondLaunched = false;
+        const second = await (0, supervisor_wrapper_1.runSupervisorWrapper)({
+            worktreePath, trackId: 'cli', nonce: NONCE, readinessNonce: 'nonce-cli'.padEnd(32, '0'), fencingToken: 'fence',
+            planRoot, planBranch: 'main', pollMs: 5,
+            launchWatch: () => { secondLaunched = true; },
+        });
+        expect(second).toBe('already-claimed');
+        expect(secondLaunched).toBe(false);
+    });
+    test('si el plan bloquea el track, el wrapper jamás lanza `awm watch` (C1, R4.9)', async () => {
+        seedTrackRef('BLOCKED');
+        let launched = false;
+        const outcome = await (0, supervisor_wrapper_1.runSupervisorWrapper)({
+            worktreePath, trackId: 'cli', nonce: NONCE, readinessNonce: 'nonce-cli'.padEnd(32, '0'), fencingToken: 'fence',
+            planRoot, planBranch: 'main', pollMs: 5,
+            launchWatch: () => { launched = true; },
+        });
+        expect(outcome).toBe('blocked');
+        expect(launched).toBe(false);
+    });
+    test('BLOCKER fix: el nonce recibido viaja al identity sidecar y observeSupervisorFromDisk jamás clasifica un wrapper legítimo como foreign (R4.7, R4.9)', async () => {
+        seedTrackRef('ARMED');
+        const wrapperPromise = (0, supervisor_wrapper_1.runSupervisorWrapper)({
+            worktreePath, trackId: 'cli', nonce: NONCE, readinessNonce: 'nonce-cli'.padEnd(32, '0'), fencingToken: 'fence',
+            planRoot, planBranch: 'main', pollMs: 5,
+            launchWatch: (wt) => {
+                fs_1.default.mkdirSync(path_1.default.dirname((0, paths_1.supervisorLockPath)(wt)), { recursive: true });
+                fs_1.default.writeFileSync((0, paths_1.supervisorLockPath)(wt), '{}');
+            },
+        });
+        // El claim/identity/ready sidecar se escriben ANTES del loop de
+        // espera por ACTIVE — no hace falta llegar a ACTIVE para probar el
+        // eco del nonce.
+        await new Promise((r) => setTimeout(r, 30));
+        const identity = JSON.parse(fs_1.default.readFileSync(path_1.default.join(worktreePath, '.awm', 'supervisor.identity.json'), 'utf8'));
+        expect(identity.nonce).toBe(NONCE); // el wrapper NUNCA genera el suyo propio
+        const claimPath = path_1.default.join(worktreePath, '.awm', 'supervisor.claim');
+        const matchingRef = (0, fixtures_1.trackRefFixture)({ trackId: 'cli', phase: 'SUPERVISOR_STARTING', supervisorIntent: { nonce: NONCE, argv: [], claimPath } }, worktreePath);
+        expect((0, tracks_1.observeSupervisorFromDisk)(matchingRef)).toEqual({ kind: 'ready', readinessNonce: 'nonce-cli'.padEnd(32, '0') });
+        const foreignRef = (0, fixtures_1.trackRefFixture)({ trackId: 'cli', phase: 'SUPERVISOR_STARTING', supervisorIntent: { nonce: 'a-completely-different-nonce', argv: [], claimPath } }, worktreePath);
+        expect((0, tracks_1.observeSupervisorFromDisk)(foreignRef).kind).toBe('foreign');
+        seedTrackRef('ACTIVE');
+        await wrapperPromise;
+    });
+});

package/dist/tests/commands/track/verbs.test.js

@@ -0,0 +1,326 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+const child_process_1 = require("child_process");
+const commander_1 = require("commander");
+const track_1 = require("../../../src/commands/track");
+const store_1 = require("../../../src/core/journal/store");
+const paths_1 = require("../../../src/core/journal/paths");
+const requests_1 = require("../../../src/core/journal/requests");
+const descriptor_1 = require("../../../src/core/tracks/descriptor");
+const fixtures_1 = require("./fixtures");
+// Superficie `awm track` (R5.10, R6.1, R9.5, R9.6): los verbos mutantes
+// (add/join/remove) SOLO emiten una request inmutable — jamas tocan Git ni
+// state.json (single-writer, R6.1); los verbos read-only (list/status/
+// verify-independence) jamas aceptan --generation ni emiten nada.
+class ExitSignal extends Error {
+    code;
+    constructor(code) {
+        super(`process.exit(${code})`);
+        this.code = code;
+    }
+}
+function git(repo, args) {
+    return (0, child_process_1.execFileSync)('git', args, { cwd: repo, encoding: 'utf8' }).trim();
+}
+function gitInit(repo, branch) {
+    (0, child_process_1.execFileSync)('git', ['-c', 'user.email=t@t.t', '-c', 'user.name=t', '-c', 'commit.gpgsign=false', 'init', '-q', '-b', branch], { cwd: repo });
+    fs_1.default.writeFileSync(path_1.default.join(repo, 'f.txt'), 'x');
+    (0, child_process_1.execFileSync)('git', ['-c', 'user.email=t@t.t', '-c', 'user.name=t', '-c', 'commit.gpgsign=false', 'add', '.'], { cwd: repo });
+    (0, child_process_1.execFileSync)('git', ['-c', 'user.email=t@t.t', '-c', 'user.name=t', '-c', 'commit.gpgsign=false', 'commit', '-qm', 'c'], { cwd: repo });
+}
+function readPendingKinds(repo, branch) {
+    return (0, requests_1.listPendingRequests)(repo, branch).filter((p) => !p.corrupt).map((p) => p.envelope.kind);
+}
+async function runCli(repo, argv) {
+    const prog = new commander_1.Command();
+    prog.exitOverride();
+    (0, track_1.registerTrackCommand)(prog);
+    const outSpy = jest.spyOn(process.stdout, 'write').mockImplementation(() => true);
+    const errSpy = jest.spyOn(process.stderr, 'write').mockImplementation(() => true);
+    const cwdSpy = jest.spyOn(process, 'cwd').mockReturnValue(repo);
+    let exitCode = 0;
+    const exitSpy = jest.spyOn(process, 'exit').mockImplementation(((code) => {
+        exitCode = code ?? 0;
+        throw new ExitSignal(exitCode);
+    }));
+    try {
+        await prog.parseAsync(['node', 'awm', ...argv]);
+    }
+    catch (e) {
+        if (e instanceof ExitSignal) {
+            // ya capturado por el spy de process.exit
+        }
+        else if (typeof e.exitCode === 'number') {
+            // exitOverride(): errores/--help propios de commander (opcion
+            // desconocida, --generation faltante, --help) nunca llaman a
+            // process.exit — lanzan un CommanderError con exitCode propio.
+            exitCode = e.exitCode;
+        }
+        else {
+            throw e;
+        }
+    }
+    finally {
+        cwdSpy.mockRestore();
+        exitSpy.mockRestore();
+    }
+    const out = outSpy.mock.calls.map((c) => String(c[0])).join('');
+    const err = errSpy.mock.calls.map((c) => String(c[0])).join('');
+    outSpy.mockRestore();
+    errSpy.mockRestore();
+    return { out, err, exitCode };
+}
+describe('awm track — verbos mutantes son request-only (R6.1)', () => {
+    let repo;
+    const branch = 'main';
+    beforeEach(() => {
+        repo = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-track-verbs-'));
+        gitInit(repo, branch);
+        (0, store_1.initJournal)(repo, branch);
+    });
+    afterEach(() => { fs_1.default.rmSync(repo, { recursive: true, force: true }); });
+    test.each([
+        ['add', 'track-prepare-request'],
+        ['join', 'track-join-request'],
+        ['remove', 'track-teardown-request'],
+    ])('%s emite %s y no muta Git/state (R6.1)', async (verb, kind) => {
+        const beforeHead = git(repo, ['rev-parse', 'HEAD']);
+        const beforeState = fs_1.default.readFileSync((0, paths_1.statePath)(repo, branch), 'utf8');
+        const out = await runCli(repo, ['track', verb, 'cli', '--generation', 'g1']);
+        expect(out.exitCode).toBe(0);
+        expect(readPendingKinds(repo, branch)).toContain(kind);
+        expect(git(repo, ['rev-parse', 'HEAD'])).toBe(beforeHead);
+        expect(fs_1.default.readFileSync((0, paths_1.statePath)(repo, branch), 'utf8')).toBe(beforeState);
+    });
+    test.each(['add', 'join', 'remove'])('%s exige --generation (Commander valida antes de emitir)', async (verb) => {
+        const out = await runCli(repo, ['track', verb, 'cli']);
+        expect(out.exitCode).not.toBe(0);
+        expect(readPendingKinds(repo, branch)).toEqual([]);
+    });
+    test.each(['add', 'join', 'remove'])('%s sin argumento <trackId> falla en commander, no emite nada', async (verb) => {
+        const out = await runCli(repo, ['track', verb, '--generation', 'g1']);
+        expect(out.exitCode).not.toBe(0);
+        expect(readPendingKinds(repo, branch)).toEqual([]);
+    });
+});
+describe('awm track list/status — read-only, sin --generation (R9.5)', () => {
+    let repo;
+    const branch = 'main';
+    beforeEach(() => {
+        repo = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-track-list-'));
+        gitInit(repo, branch);
+        (0, store_1.initJournal)(repo, branch);
+    });
+    afterEach(() => { fs_1.default.rmSync(repo, { recursive: true, force: true }); });
+    test('list no acepta --generation y no emite requests', async () => {
+        const out = await runCli(repo, ['track', 'list', '--generation', 'g1']);
+        expect(out.exitCode).not.toBe(0); // commander: opcion desconocida
+        expect(readPendingKinds(repo, branch)).toEqual([]);
+    });
+    test('list imprime los tracks del journal (vacio por defecto) sin mutar nada', async () => {
+        const beforeState = fs_1.default.readFileSync((0, paths_1.statePath)(repo, branch), 'utf8');
+        const out = await runCli(repo, ['track', 'list']);
+        expect(out.exitCode).toBe(0);
+        expect(JSON.parse(out.out)).toEqual({ tracks: [] });
+        expect(fs_1.default.readFileSync((0, paths_1.statePath)(repo, branch), 'utf8')).toBe(beforeState);
+    });
+    test('status no acepta --generation', async () => {
+        const out = await runCli(repo, ['track', 'status', '--generation', 'g1']);
+        expect(out.exitCode).not.toBe(0);
+        expect(readPendingKinds(repo, branch)).toEqual([]);
+    });
+    test('status con journal sin tracks agrega cohort "sin tracks declarados" y sale 0', async () => {
+        const out = await runCli(repo, ['track', 'status']);
+        expect(out.exitCode).toBe(0);
+        expect(JSON.parse(out.out)).toEqual({ cohort: 'sin tracks declarados', tracks: {} });
+    });
+});
+describe('awm track verify-independence — R5.10', () => {
+    const fixture = (name) => path_1.default.join(__dirname, '../../fixtures/tracks', name);
+    test('plan con tracks disjuntos: parallel:true, sale 0', async () => {
+        const out = await runCli(process.cwd(), ['track', 'verify-independence', '--plan', fixture('two-independent.md')]);
+        expect(out.exitCode).toBe(0);
+        expect(JSON.parse(out.out)).toEqual({ parallel: true, reasons: [] });
+    });
+    test('plan sin membresia de tracks degrada a serial: parallel:false, sale 1', async () => {
+        const out = await runCli(process.cwd(), ['track', 'verify-independence', '--plan', fixture('legacy-serial.md')]);
+        expect(out.exitCode).toBe(1);
+        expect(JSON.parse(out.out)).toEqual({ parallel: false, reasons: ['no-tracks'] });
+    });
+    test('tracks con ownership superpuesto: parallel:false, sale 1, nombra el path (R5.1)', async () => {
+        const overlapping = fs_1.default.readFileSync(fixture('two-independent.md'), 'utf8')
+            .replace('docs/a.md', 'cli/src/a.ts');
+        const tmp = path_1.default.join(os_1.default.tmpdir(), `awm-overlap-${Date.now()}.md`);
+        fs_1.default.writeFileSync(tmp, overlapping);
+        try {
+            const out = await runCli(process.cwd(), ['track', 'verify-independence', '--plan', tmp]);
+            expect(out.exitCode).toBe(1);
+            const parsed = JSON.parse(out.out);
+            expect(parsed.parallel).toBe(false);
+            expect(parsed.reasons).toContain('path:cli/src/a.ts');
+        }
+        finally {
+            fs_1.default.rmSync(tmp, { force: true });
+        }
+    });
+    test('plan con violacion a nivel de PARSER (id de track peligroso) reporta {parallel:false} y sale 1 — jamas un stack trace crudo', async () => {
+        // parseTrackPlan lanza sincronicamente ante un id de track peligroso
+        // (ver tests/core/tracks/plan-parser.test.ts) — antes del fix, este
+        // throw escapaba sin capturar y tumbaba el proceso entero.
+        const broken = fs_1.default.readFileSync(fixture('two-independent.md'), 'utf8').replaceAll('cli', '..');
+        const tmp = path_1.default.join(os_1.default.tmpdir(), `awm-badid-${Date.now()}.md`);
+        fs_1.default.writeFileSync(tmp, broken);
+        try {
+            const out = await runCli(process.cwd(), ['track', 'verify-independence', '--plan', tmp]);
+            expect(out.exitCode).toBe(1);
+            const parsed = JSON.parse(out.out);
+            expect(parsed.parallel).toBe(false);
+            expect(parsed.reasons).toHaveLength(1);
+            expect(parsed.reasons[0]).toMatch(/^parse-error:.*track id inválido/);
+        }
+        finally {
+            fs_1.default.rmSync(tmp, { force: true });
+        }
+    });
+    test('archivo de plan inexistente tambien reporta {parallel:false} estructurado, no un ENOENT crudo', async () => {
+        const out = await runCli(process.cwd(), ['track', 'verify-independence', '--plan', '/no/existe/plan.md']);
+        expect(out.exitCode).toBe(1);
+        const parsed = JSON.parse(out.out);
+        expect(parsed).toEqual({ parallel: false, reasons: [expect.stringMatching(/^parse-error:/)] });
+    });
+    test('shared resource sin forma <clase>:<valor> (canonicalResource, ownership.ts) tambien reporta JSON estructurado, no un stack trace (bug hermano post-fix)', async () => {
+        // El parser NUNCA valida la forma de "Shared resources" — solo revisa
+        // que la celda no este vacia (plan-parser.ts). `canonicalResource`
+        // lanza recien DENTRO de assessDeclaredIndependence, un paso despues
+        // del parseo: el primer fix de este verbo envolvia solo
+        // read+parseTrackPlan y dejaba escapar exactamente este throw.
+        const malformed = fs_1.default.readFileSync(fixture('two-independent.md'), 'utf8')
+            .replace('| cli | none | [] |', '| cli | none | badresource |');
+        const tmp = path_1.default.join(os_1.default.tmpdir(), `awm-badresource-${Date.now()}.md`);
+        fs_1.default.writeFileSync(tmp, malformed);
+        try {
+            const out = await runCli(process.cwd(), ['track', 'verify-independence', '--plan', tmp]);
+            expect(out.exitCode).toBe(1);
+            const parsed = JSON.parse(out.out);
+            expect(parsed.parallel).toBe(false);
+            expect(parsed.reasons).toHaveLength(1);
+            expect(parsed.reasons[0]).toMatch(/^parse-error:.*recurso debe usar/);
+        }
+        finally {
+            fs_1.default.rmSync(tmp, { force: true });
+        }
+    });
+    test('verify-independence no emite requests ni exige journal/branch', async () => {
+        // deliberadamente NO se llama gitInit/initJournal en process.cwd(): el
+        // verbo es puro sobre el archivo de plan, no toca .awm/journal.
+        const out = await runCli(process.cwd(), ['track', 'verify-independence', '--plan', fixture('two-independent.md')]);
+        expect(out.exitCode).toBe(0);
+    });
+});
+describe('awm track list/status — guard de contexto de PLAN (distinto de R9.4)', () => {
+    let planRoot;
+    let trackRoot;
+    beforeEach(() => {
+        planRoot = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-track-plan-'));
+        trackRoot = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-track-worktree-'));
+        gitInit(planRoot, 'main');
+        gitInit(trackRoot, 'track/cli');
+        (0, store_1.initJournal)(planRoot, 'main');
+        const planState = (0, store_1.readJournal)(planRoot, 'main').state;
+        planState.journalId = 'j-1';
+        planState.tracks = [(0, fixtures_1.trackRefFixture)({}, trackRoot)];
+        (0, store_1.writeJournal)(planRoot, 'main', planState);
+        (0, store_1.initJournal)(trackRoot, 'track/cli');
+        const trackState = (0, store_1.readJournal)(trackRoot, 'track/cli').state;
+        trackState.trackContext = { trackId: 'cli', taskIds: [], planDigest: 'x', baseSha: 'y', planJournalId: 'j-1' };
+        (0, store_1.writeJournal)(trackRoot, 'track/cli', trackState);
+        (0, descriptor_1.writeDescriptor)(trackRoot, (0, fixtures_1.descriptorFixture)({ planJournalId: 'j-1' }, planRoot));
+    });
+    afterEach(() => {
+        fs_1.default.rmSync(planRoot, { recursive: true, force: true });
+        fs_1.default.rmSync(trackRoot, { recursive: true, force: true });
+    });
+    test.each(['list', 'status'])('`track %s` desde la RAIZ DEL PLAN funciona con normalidad', async (verb) => {
+        const out = await runCli(planRoot, ['track', verb]);
+        expect(out.err).toBe('');
+        // "sin tracks declarados"/{tracks:[...]} — lo que sea, pero SIN
+        // reject por contexto (ese es el punto de este guard especifico).
+        expect(out.exitCode).not.toBeNull();
+    });
+    test.each(['list', 'status'])('`track %s` desde el WORKTREE DE UN TRACK rechaza con mensaje claro, no "sin tracks declarados" silencioso', async (verb) => {
+        const out = await runCli(trackRoot, ['track', verb]);
+        expect(out.exitCode).toBe(1);
+        expect(out.out).toBe(''); // nunca imprime un agregado vacio enganoso
+        expect(out.err).toContain('worktree del track');
+        expect(out.err).toContain('cli');
+        expect(out.err).not.toContain('cwd no autenticado'); // no es un fallo de R9.4, es de contexto
+    });
+    test('`track status` sigue rechazando un cwd que NO autentica en absoluto (R9.4 sigue vigente)', async () => {
+        const otherRoot = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-track-other-'));
+        try {
+            gitInit(otherRoot, 'track/cli');
+            (0, store_1.initJournal)(otherRoot, 'track/cli');
+            const otherState = (0, store_1.readJournal)(otherRoot, 'track/cli').state;
+            otherState.trackContext = { trackId: 'cli', taskIds: [], planDigest: 'x', baseSha: 'y', planJournalId: 'j-1' };
+            (0, store_1.writeJournal)(otherRoot, 'track/cli', otherState);
+            // mismo descriptor "logico" que trackRoot, pero su realpath JAMAS
+            // coincide con el TrackRef del plan — resolveCommandContext debe
+            // rechazar ANTES de que el guard de plan-vs-track entre en juego.
+            (0, descriptor_1.writeDescriptor)(otherRoot, (0, fixtures_1.descriptorFixture)({ planJournalId: 'j-1' }, planRoot));
+            const out = await runCli(otherRoot, ['track', 'status']);
+            expect(out.exitCode).toBe(1);
+            expect(out.err).toContain('cwd no autenticado');
+        }
+        finally {
+            fs_1.default.rmSync(otherRoot, { recursive: true, force: true });
+        }
+    });
+});
+describe('awm track status — sale 1 con gate rojo a nivel CLI (Gap: solo se probaba la funcion pura)', () => {
+    let planRoot;
+    let trackRoot;
+    beforeEach(() => {
+        planRoot = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-track-status-plan-'));
+        trackRoot = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-track-status-track-'));
+        gitInit(planRoot, 'main');
+        gitInit(trackRoot, 'track/cli');
+        (0, store_1.initJournal)(planRoot, 'main');
+        (0, store_1.initJournal)(trackRoot, 'track/cli');
+    });
+    afterEach(() => {
+        fs_1.default.rmSync(planRoot, { recursive: true, force: true });
+        fs_1.default.rmSync(trackRoot, { recursive: true, force: true });
+    });
+    test('un track con tarea pending hace que `track status` (CLI) salga 1, no solo la funcion pura', async () => {
+        // trackContext presente + una tarea 'pending' basta para que
+        // computeTrackGate falle (categoria pending-task) — sin necesidad de
+        // reconstruir un journal que pase entero, al reves del test de
+        // status.test.ts que si cubre el camino verde.
+        const trackState = (0, store_1.readJournal)(trackRoot, 'track/cli').state;
+        trackState.trackContext = { trackId: 'cli', taskIds: ['T1'], planDigest: 'x', baseSha: 'y', planJournalId: 'j-1' };
+        trackState.tasks.push({ id: 'T1', title: 't', status: 'pending', attempts: 0, verificationPlan: [], reviewObligations: [] });
+        (0, store_1.writeJournal)(trackRoot, 'track/cli', trackState);
+        const planState = (0, store_1.readJournal)(planRoot, 'main').state;
+        planState.tracks = [(0, fixtures_1.trackRefFixture)({}, trackRoot)];
+        (0, store_1.writeJournal)(planRoot, 'main', planState);
+        const out = await runCli(planRoot, ['track', 'status']);
+        expect(out.exitCode).toBe(1);
+        const parsed = JSON.parse(out.out);
+        expect(parsed.tracks.cli.gate.pass).toBe(false);
+        expect(parsed.tracks.cli.gate.reasons.some((r) => r.category === 'pending-task')).toBe(true);
+    });
+});
+describe('awm track --help lista exactamente los 6 verbos', () => {
+    test('help incluye add, list, status, verify-independence, join, remove', async () => {
+        const out = await runCli(process.cwd(), ['track', '--help']);
+        for (const verb of ['add', 'list', 'status', 'verify-independence', 'join', 'remove']) {
+            expect(out.out).toContain(verb);
+        }
+    });
+});

package/dist/tests/commands/watch/apply.test.js

@@ -39,7 +39,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const os_1 = __importDefault(require("os"));
+const child_process_1 = require("child_process");
 const apply_1 = require("../../../src/commands/watch/apply");
+const types_1 = require("../../../src/core/journal/types");
 const requests_1 = require("../../../src/core/journal/requests");
 const store_1 = require("../../../src/core/journal/store");
 const paths_1 = require("../../../src/core/journal/paths");
@@ -51,6 +53,57 @@ function jobPayload(argv) {
 function verdictPayload(verdictId, obligationId, result, detail) {
     return { verdictId, obligationId, result, detail, fingerprint: 'fp-review', argv: ['awm-review', obligationId], paths: [], cwd: '.' };
 }
+function trackRef(trackId) {
+    return {
+        trackId, worktreePath: `/tmp/${trackId}`, branch: `awm-track/${trackId}`,
+        ownership: [], sharedResources: [], dependsOn: [],
+        fencingToken: `fence-${trackId}`.padEnd(32, '0'), phase: 'MERGED_UNVERIFIED', readinessNonce: `ready-${trackId}`.padEnd(32, '0'),
+    };
+}
+describe('applyCyclePlanAppend / registerTrackIntegrationItems (R7.2/R7.3, Task 12)', () => {
+    function stateWithCycleItems(items) {
+        const s = (0, types_1.emptyState)('rama');
+        s.cycleVerificationPlan = items;
+        return s;
+    }
+    function stateWithTracks(trackIds) {
+        const s = (0, types_1.emptyState)('rama');
+        s.tracks = trackIds.map(trackRef);
+        return s;
+    }
+    test('cycle plan agrega items por id sin borrar satisfiedBy (R7.2)', () => {
+        const state = stateWithCycleItems([{ id: 'qa', kind: 'qa', satisfiedBy: 'job-qa' }]);
+        (0, apply_1.applyCyclePlanAppend)(state, [
+            { id: 'qa', kind: 'qa' },
+            { id: 'track-integration:a', kind: 'track-integration' },
+        ]);
+        expect(state.cycleVerificationPlan).toEqual([
+            { id: 'qa', kind: 'qa', satisfiedBy: 'job-qa' },
+            { id: 'track-integration:a', kind: 'track-integration' },
+        ]);
+    });
+    test('una colision de kind para el mismo id lanza (rechaza el request completo)', () => {
+        const state = stateWithCycleItems([{ id: 'qa', kind: 'qa' }]);
+        expect(() => (0, apply_1.applyCyclePlanAppend)(state, [{ id: 'qa', kind: 'interlock' }])).toThrow(/cambia kind/);
+        expect(state.cycleVerificationPlan).toEqual([{ id: 'qa', kind: 'qa' }]); // sin mutar ante el throw
+    });
+    test('registrar tracks deja gate rojo desde el inicio (R7.3)', () => {
+        const s = stateWithTracks(['a', 'b']);
+        (0, apply_1.registerTrackIntegrationItems)(s);
+        expect(s.cycleVerificationPlan.filter((x) => x.kind === 'track-integration'))
+            .toEqual([
+            { id: 'track-integration:a', kind: 'track-integration' },
+            { id: 'track-integration:b', kind: 'track-integration' },
+        ]);
+    });
+    test('registrar tracks es idempotente y aditivo: un track nuevo se agrega sin perder los previos', () => {
+        const s = stateWithTracks(['a']);
+        (0, apply_1.registerTrackIntegrationItems)(s);
+        s.tracks = [...s.tracks, trackRef('b')];
+        (0, apply_1.registerTrackIntegrationItems)(s);
+        expect(s.cycleVerificationPlan.map((x) => x.id).sort()).toEqual(['track-integration:a', 'track-integration:b']);
+    });
+});
 describe('aplicacion transaccional de requests', () => {
     let repo;
     beforeEach(() => { repo = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-apply-')); (0, store_1.initJournal)(repo, 'rama'); });
@@ -131,7 +184,7 @@ describe('aplicacion transaccional de requests', () => {
         const s = (0, store_1.readJournal)(repo, 'rama').state;
         const jobId = Object.keys(s.jobs)[0];
         expect(s.tasks[0].verificationPlan[0].satisfiedBy).toBe(jobId);
-        expect(s.jobs[jobId].satisfies).toBe('v1');
+        expect(s.jobs[jobId].satisfies).toEqual(['v1']); // R7 Task 12: satisfies migró a array
     });
     test('fencing: token de generacion vieja => rejected-stale-generation auditado (R4.6)', () => {
         (0, requests_1.emitRequest)(repo, 'rama', { kind: 'controller-heartbeat', generationToken: 'g-vieja', idempotencyKey: 'hb1', payload: {} });
@@ -295,7 +348,7 @@ describe('aplicacion transaccional de requests', () => {
         g = (0, gate_1.computeGate)(s, false, fpNull);
         expect(g.reasons.some((r) => r.category === 'open-fix')).toBe(false); // ya no bloquea por open-fix
     });
-    test('Fix4: register-entity cycle-plan es idempotente — un re-registro NO pisa el plan existente ni pierde satisfiedBy ya enlazado', () => {
+    test('Fix4/R7.2 (Task 12): register-entity cycle-plan es un append transaccional — un re-registro NUNCA pisa un item existente ni pierde satisfiedBy ya enlazado, pero SÍ agrega ids nuevos', () => {
         (0, requests_1.emitRequest)(repo, 'rama', { kind: 'register-entity', generationToken: 'g1', idempotencyKey: 'e1', payload: { entity: 'cycle-plan', items: [{ id: 'cv1', kind: 'qa' }] } });
         (0, apply_1.consumePendingRequests)(repo, 'rama', 'g1');
         (0, requests_1.emitRequest)(repo, 'rama', { kind: 'job-request', generationToken: 'g1', idempotencyKey: 'k1', payload: { ...jobPayload(['npm', 'run', 'qa']), satisfies: 'cv1' } });
@@ -303,11 +356,17 @@ describe('aplicacion transaccional de requests', () => {
         let s = (0, store_1.readJournal)(repo, 'rama').state;
         const jobId = Object.keys(s.jobs)[0];
         expect(s.cycleVerificationPlan[0].satisfiedBy).toBe(jobId);
-        // re-registro defensivo (ej. tras crash sin memoria de si ya se registro), incluso con items DISTINTOS
+        // re-registro defensivo (ej. tras crash sin memoria de si ya se registro), con un id NUEVO
         (0, requests_1.emitRequest)(repo, 'rama', { kind: 'register-entity', generationToken: 'g1', idempotencyKey: 'e2', payload: { entity: 'cycle-plan', items: [{ id: 'cv-otro', kind: 'interlock' }] } });
         (0, apply_1.consumePendingRequests)(repo, 'rama', 'g1');
         s = (0, store_1.readJournal)(repo, 'rama').state;
-        expect(s.cycleVerificationPlan).toEqual([{ id: 'cv1', kind: 'qa', satisfiedBy: jobId }]); // plan original preservado
+        // el item original conserva su satisfiedBy Y el nuevo id se agregó (R7.2: union, nunca reemplazo)
+        expect(s.cycleVerificationPlan).toEqual([{ id: 'cv1', kind: 'qa', satisfiedBy: jobId }, { id: 'cv-otro', kind: 'interlock' }]);
+        // re-registrar el MISMO id con un kind DISTINTO se rechaza (colisión de kind rechaza el request completo)
+        const badKind = (0, requests_1.emitRequest)(repo, 'rama', { kind: 'register-entity', generationToken: 'g1', idempotencyKey: 'e3', payload: { entity: 'cycle-plan', items: [{ id: 'cv1', kind: 'interlock' }] } });
+        expect((0, apply_1.consumePendingRequests)(repo, 'rama', 'g1').rejectedInvalid).toBe(1);
+        expect(fs_1.default.existsSync(`${badKind.file}.rejected`)).toBe(true);
+        expect((0, store_1.readJournal)(repo, 'rama').state.cycleVerificationPlan).toEqual([{ id: 'cv1', kind: 'qa', satisfiedBy: jobId }, { id: 'cv-otro', kind: 'interlock' }]);
     });
     test('Fix5: verdict --detail se redacta antes de persistir en state.json (R2.3)', () => {
         (0, requests_1.emitRequest)(repo, 'rama', {
@@ -394,4 +453,57 @@ describe('aplicacion transaccional de requests', () => {
         expect(s.generations[0].state).toBe('superseded');
         expect(s.custodyDecisions).toEqual([expect.objectContaining({ decision: 'resume', reason: 'operador verifico que no hay llamada en vuelo', generationToken: 'g1' })]);
     });
+    // ---- R7/C3/C4 (Task 12): register-entity track-integration, track-finalize-request ----
+    test('register --entity track-integration crea el contrato canonico UNA sola vez (creacion-unica, como cycle-plan)', () => {
+        (0, requests_1.emitRequest)(repo, 'rama', {
+            kind: 'register-entity', generationToken: 'g1', idempotencyKey: 'ti1',
+            payload: { entity: 'track-integration', argv: ['npm', 'test', '--', '--runInBand'], paths: ['cli/src/**'], planDigest: 'd1' },
+        });
+        (0, apply_1.consumePendingRequests)(repo, 'rama', 'g1');
+        expect((0, store_1.readJournal)(repo, 'rama').state.trackIntegration).toEqual({ argv: ['npm', 'test', '--', '--runInBand'], paths: ['cli/src/**'], planDigest: 'd1' });
+        // un segundo registro con OTRO contrato NUNCA lo pisa
+        (0, requests_1.emitRequest)(repo, 'rama', {
+            kind: 'register-entity', generationToken: 'g1', idempotencyKey: 'ti2',
+            payload: { entity: 'track-integration', argv: ['npm', 'run', 'otro'], paths: [], planDigest: 'd2' },
+        });
+        (0, apply_1.consumePendingRequests)(repo, 'rama', 'g1');
+        expect((0, store_1.readJournal)(repo, 'rama').state.trackIntegration).toEqual({ argv: ['npm', 'test', '--', '--runInBand'], paths: ['cli/src/**'], planDigest: 'd1' });
+    });
+    test('register --entity track-integration rechaza argv vacio', () => {
+        const r = (0, requests_1.emitRequest)(repo, 'rama', {
+            kind: 'register-entity', generationToken: 'g1', idempotencyKey: 'ti-bad',
+            payload: { entity: 'track-integration', argv: [], paths: [], planDigest: 'd1' },
+        });
+        expect((0, apply_1.consumePendingRequests)(repo, 'rama', 'g1').rejectedInvalid).toBe(1);
+        expect(fs_1.default.existsSync(`${r.file}.rejected`)).toBe(true);
+        expect((0, store_1.readJournal)(repo, 'rama').state.trackIntegration).toBeUndefined();
+    });
+    test('track-finalize-request persiste el autoreporte del controller (qaFinalizeRequested) — puramente declarativo (R7.2)', () => {
+        (0, requests_1.emitRequest)(repo, 'rama', {
+            kind: 'track-finalize-request', generationToken: 'g1', idempotencyKey: 'finalize-1',
+            payload: { qaHeadSha: 'sha-h3' },
+        });
+        expect((0, apply_1.consumePendingRequests)(repo, 'rama', 'g1').applied).toBe(1);
+        const s = (0, store_1.readJournal)(repo, 'rama').state;
+        expect(s.qaFinalizeRequested).toEqual({ headSha: 'sha-h3', at: expect.any(String) });
+    });
+    test('declarar un track (track-prepare-request) agrega de inmediato su track-integration:* al cycle plan (R7.3)', () => {
+        // El segundo track dispara `headSha(repoRoot)` (armado de la cohorte,
+        // R4.1) — a diferencia del resto de esta suite, este repo SÍ necesita
+        // ser un repo git real para llegar a ese punto.
+        (0, child_process_1.execFileSync)('git', ['init', '-q', '-b', 'rama'], { cwd: repo });
+        (0, child_process_1.execFileSync)('git', ['-c', 'user.email=t@t.t', '-c', 'user.name=t', 'commit', '--allow-empty', '-qm', 'seed'], { cwd: repo });
+        (0, requests_1.emitRequest)(repo, 'rama', { kind: 'track-prepare-request', generationToken: 'g1', idempotencyKey: 'tp-a', payload: { trackId: 'a' } });
+        (0, apply_1.consumePendingRequests)(repo, 'rama', 'g1');
+        let s = (0, store_1.readJournal)(repo, 'rama').state;
+        expect(s.cycleVerificationPlan).toEqual([{ id: 'track-integration:a', kind: 'track-integration' }]);
+        (0, requests_1.emitRequest)(repo, 'rama', { kind: 'track-prepare-request', generationToken: 'g1', idempotencyKey: 'tp-b', payload: { trackId: 'b' } });
+        (0, apply_1.consumePendingRequests)(repo, 'rama', 'g1');
+        s = (0, store_1.readJournal)(repo, 'rama').state;
+        expect(s.cycleVerificationPlan.map((i) => i.id).sort()).toEqual(['track-integration:a', 'track-integration:b']);
+        // R3.6/R7.3: el gate global ya está rojo por estos items sin satisfacer, desde el momento en que se declaran
+        const gate = (0, gate_1.computeGate)(s, false, () => 'fp-1');
+        expect(gate.pass).toBe(false);
+        expect(gate.reasons.some((r) => r.category === 'unsatisfied-plan' && /track-integration:a/.test(r.detail))).toBe(true);
+    });
 });