agentic-workflow-manager 6.2.1 → 6.3.0

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WATCH_PROVIDERS = void 0;
+exports.CONTROLLER_ARGV_ENV = exports.WATCH_PROVIDERS = void 0;
 exports.isWatchProvider = isWatchProvider;
 exports.adapterFor = adapterFor;
 const process_1 = require("./process");
@@ -27,10 +27,50 @@ exports.WATCH_PROVIDERS = ['codex', 'claude-code'];
 function isWatchProvider(value) {
     return typeof value === 'string' && exports.WATCH_PROVIDERS.includes(value);
 }
+/** Nombre del env var que redirige el LANZAMIENTO del controller a un comando propio.
+ *  Exportado para que tests y documentacion nunca reescriban el literal. */
+exports.CONTROLLER_ARGV_ENV = 'AWM_CONTROLLER_ARGV';
+/**
+ * El supervisor declara no conocer providers: conoce el contrato `ControllerAdapter`. Esa
+ * afirmacion era INFALSIFICABLE desde afuera mientras los unicos adapters posibles fueran
+ * `codex` y `claude-code` — no habia forma de plantar un controller ajeno y comprobar que
+ * el supervisor se comporta igual.
+ *
+ * `AWM_CONTROLLER_ARGV` cierra eso: un array JSON de strings que reemplaza el argv de
+ * lanzamiento, conservando TODO lo demas del adapter elegido (actividad, `safeToReplace`,
+ * fencing, custodia). El prompt de la generacion se agrega como ultimo argumento, igual que
+ * hacen los adapters nativos, para que el controller reciba su token por la misma via.
+ *
+ * Array JSON y jamas una linea de shell: es la misma doctrina que el argv de integracion de
+ * los tracks (C4) — una string interpretada por un shell convierte un nombre de archivo en
+ * un operador. Se valida en el borde: cualquier cosa que no sea un array no vacio de strings
+ * no vacios es un error explicito, nunca un fallback silencioso al provider nativo (un
+ * override mal escrito que "funciona igual" lanzaria el agente real sin que nadie lo note).
+ */
+function controllerArgvOverride() {
+    const raw = process.env[exports.CONTROLLER_ARGV_ENV]?.trim();
+    if (raw === undefined || raw.length === 0)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`${exports.CONTROLLER_ARGV_ENV} debe ser un array JSON de strings, no una linea de shell: ${raw}`);
+    }
+    if (!Array.isArray(parsed) || parsed.length === 0 || parsed.some((x) => typeof x !== 'string' || x.length === 0)) {
+        throw new Error(`${exports.CONTROLLER_ARGV_ENV} debe ser un array JSON no vacio de strings no vacios: ${raw}`);
+    }
+    return parsed;
+}
 function adapterFor(provider) {
-    if (provider === 'codex')
-        return codexAdapter;
-    if (provider === 'claude-code')
-        return claudeAdapter;
-    throw new Error(`provider desconocido: ${provider} (validos: ${exports.WATCH_PROVIDERS.join(', ')})`);
+    const base = provider === 'codex' ? codexAdapter
+        : provider === 'claude-code' ? claudeAdapter
+            : null;
+    if (base === null)
+        throw new Error(`provider desconocido: ${provider} (validos: ${exports.WATCH_PROVIDERS.join(', ')})`);
+    const override = controllerArgvOverride();
+    if (override === null)
+        return base;
+    return { ...base, launchArgv: (resumePrompt) => [...override, resumePrompt] };
 }

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

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.branchSlug = branchSlug;
 exports.journalDir = journalDir;
 exports.supervisorLockPath = supervisorLockPath;
+exports.integrationLockPath = integrationLockPath;
 exports.statePath = statePath;
 exports.requestsDir = requestsDir;
 exports.acksDir = acksDir;
@@ -36,6 +37,14 @@ function journalDir(repoRoot, branch) {
 function supervisorLockPath(repoRoot) {
     return path_1.default.join(fs_1.default.realpathSync(repoRoot), '.awm', 'journal', 'supervisor.lock');
 }
+/** Lock de integración (R5.8/R5.9/C7, Task 10): único por PLAN físico, fuera
+ *  de cualquier dir de rama — mismo criterio de `supervisorLockPath` (clavado
+ *  por realpath). Se adquiere ANTES del primer join de una cohorte y retiene
+ *  ownership mientras la generación del plan está pausada y ningún controller
+ *  administrado corre. */
+function integrationLockPath(repoRoot) {
+    return path_1.default.join(fs_1.default.realpathSync(repoRoot), '.awm', 'journal', 'integration.lock');
+}
 function statePath(repoRoot, branch) {
     return path_1.default.join(journalDir(repoRoot, branch), 'state.json');
 }

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

@@ -381,6 +381,17 @@ function refIsAlive(ref) {
     if ((0, paths_1.isWindowsNative)()) {
         if (!pidExistsNative(ref.pid))
             return false;
+        // DELIBERADO (Ronda 3, ver el test 'refIsAlive en win32 usa process.kill(pid,0),
+        // NUNCA ps/pgrep'): esta rama NO consulta identidad — ni ps/pgrep ni WMI. La razon
+        // es un bug real de CI: `ps`/`pgrep` emulados por MSYS son ciegos a procesos nativos
+        // y devuelven exit 1 para pids genuinamente vivos, y confiar en ellos declaraba
+        // muertes falsas. `process.kill(pid, 0)` es la unica observacion no ciega.
+        //
+        // CONSECUENCIA CONOCIDA Y ACEPTADA: un pid RECICLADO por un proceso ajeno se reporta
+        // como "nuestro proceso sigue vivo". Eso sobre-reporta vida, que es la direccion
+        // SEGURA — jamas autoriza matar nada ajeno (de eso se encarga `win32LeaderReused`
+        // antes de cualquier senial) — a costa de que un teardown pueda quedarse esperando a
+        // un proceso que nunca fue nuestro. Se prefiere la espera sobre el riesgo.
         return ref.processGroup === ref.pid;
     }
     try {
@@ -530,10 +541,83 @@ async function terminateGroupConfirmed(ref, opts) {
     catch { /* idem */ }
     return waitUntilGone(opts.killGraceMs);
 }
+/** true <=> el slot de PID que identifica al grupo (`ref.processGroup` — para
+ *  todo caller real de esta funcion coincide con `ref.pid`, el lider que el
+ *  propio caller spawneo: `captureRefFor`/`spawnStructured` siempre fijan
+ *  `processGroup` al pgid real de ese pid recien creado, que en un detached
+ *  spawn -setsid- es su PROPIO pid) esta hoy ocupado por un proceso VIVO cuya
+ *  identidad (startTime + digest de `ps args`) NO coincide con la que
+ *  capturamos para `ref`. Cubre reuso de PGID (post-review, hallazgo de
+ *  revision de Task 13): el SO reciclo ese numero de pid hacia un proceso
+ *  nuevo y no relacionado que se convirtio en lider de su propio grupo
+ *  (`setpgid`/`setsid`) con el MISMO numero — sin este chequeo, la senial de
+ *  `terminatePreviouslyOwnedGroup` de mas abajo alcanzaria a ese proceso
+ *  ajeno. Una ausencia total o un zombie en ese slot NUNCA cuentan como
+ *  reuso: o es nuestro propio lider aun sin reap (zombie), o el slot esta
+ *  libre y cualquier miembro remanente del pgid es necesariamente
+ *  descendiente nuestro (el SO no puede reutilizar el NUMERO de pid del
+ *  lider para un proceso nuevo mientras ese pid siga ocupado, vivo o
+ *  zombie). Fail-closed ante cualquier duda (R2.1/R4.8): un `ps` que no pudo
+ *  correr, o cualquier campo indeterminado, se trata como reuso — nunca
+ *  como autorizacion para senializar. */
+/** Hermano win32 de `groupLeaderReused` (R4.8). Mismo contrato, distinta fuente de verdad:
+ *  POSIX pregunta a `ps` por lstart/pgid/args; win32 pregunta a WMI por creationDate y
+ *  commandLine, exactamente los dos campos con los que `captureRefFor` construyo el `ref`
+ *  en esta plataforma. `true` <=> el PID esta ocupado por algo que NO es nuestro proceso.
+ *
+ *  Fail-closed identico al POSIX: WMI indisponible o ilegible (`null`) NO prueba que el
+ *  proceso sea nuestro, asi que se trata como ajeno y la senial jamas sale. Un `ref`
+ *  degradado a `'unknown'` (WMI no respondio al capturarlo) tampoco autoriza nada — es la
+ *  consecuencia correcta de no haber podido probar identidad al momento del spawn.
+ *  `'absent'` es el unico caso que devuelve `false`: no hay nadie ahi a quien confundir. */
+function win32LeaderReused(ref) {
+    const info = win32ProcessInfo(ref.processGroup);
+    if (info === 'absent')
+        return false;
+    if (info === null)
+        return true;
+    if (info.creationDate !== ref.startTime)
+        return true;
+    return identityDigest(info.commandLine, ref.spawnNonce, ref.argvDigest) !== ref.psArgsDigest;
+}
+function groupLeaderReused(ref) {
+    try {
+        const stat = psField(ref.processGroup, 'stat');
+        if (stat === null || stat.startsWith('Z'))
+            return false; // ausente o zombie: nunca un impostor vivo
+        const start = psField(ref.processGroup, 'lstart');
+        if (start === null || start !== ref.startTime)
+            return true;
+        const argsDig = psArgsDigestOf(ref.processGroup, ref.spawnNonce, ref.argvDigest);
+        if (argsDig === null || argsDig !== ref.psArgsDigest)
+            return true;
+        return false;
+    }
+    catch {
+        return true; // sin evidencia, jamas autorizar la senial (R2.1)
+    }
+}
 /** Drena un grupo cuya propiedad fue capturada por el caller mientras el
  * lider aun estaba vivo. Se usa inmediatamente tras el exit del lider para
  * eliminar descendientes remanentes; el PGID no puede reutilizarse mientras
- * esos miembros sigan presentes. */
+ * esos miembros sigan presentes.
+ *
+ * Post-review (hallazgo de revision de Task 13): a diferencia de
+ * `terminateGroupConfirmed`, esta funcion se usa PRECISAMENTE cuando el lider
+ * ya se espera muerto — por eso no puede reusar `refIsAlive` (exige lider
+ * vivo) como gate de identidad. `groupLeaderReused` cubre el mismo riesgo
+ * (R4.8: jamas senializar sin identidad verificada) sin asumir que el lider
+ * sigue vivo. Antes de este fix, esta funcion confiaba en que el CALLER
+ * hubiera verificado identidad momentos antes: `exec-wrapper.ts` lo hace por
+ * construccion (llama esto en una ventana de milisegundos justo tras
+ * observar el exit del propio hijo), y el caller de Task 13
+ * (`stopOwnSupervisor` en `tracks.ts`) tambien, indirectamente — la capa de
+ * arriba (`gatherTeardownObservation`) ya recalcula `refIsAlive` en la MISMA
+ * tick antes de siquiera elegir la decision `stop-own-supervisor`. Pero esa
+ * garantia era implicita y externa al primitivo: un caller futuro (o un
+ * cambio en esa capa de arriba) podia perderla sin que este archivo lo
+ * notara. Con el chequeo ACA DENTRO, el primitivo deja de depender de la
+ * disciplina del caller — se auto-defiende, igual que `terminateGroupConfirmed`. */
 async function terminatePreviouslyOwnedGroup(ref, opts) {
     const waitUntilGone = async (maxMs) => {
         const deadline = Date.now() + maxMs;
@@ -546,13 +630,29 @@ async function terminatePreviouslyOwnedGroup(ref, opts) {
     };
     if (groupIsGone(ref.processGroup))
         return true;
+    // Windows PRIMERO: sale sin tocar la logica de grupos, que es semantica POSIX.
+    // El guard `groupLeaderReused` de abajo razona sobre PGIDs y no aplica aca — pero el
+    // PELIGRO que evita si aplica, y durante un tiempo win32 no tuvo ninguna proteccion
+    // equivalente: `groupIsGone` en esta plataforma solo pregunta si el PID existe
+    // (`pidExistsNative`), sin verificar identidad, asi que un PID reciclado por un proceso
+    // AJENO vivo se leia como "nuestro supervisor sigue vivo" y `killTreeWindows` lo mataba.
+    // Eso es exactamente el `kill(pid)` crudo que R4.8 prohibe. `win32LeaderReused` es el
+    // hermano que faltaba, con el mismo criterio fail-closed: sin prueba positiva de que el
+    // proceso es NUESTRO, jamas se le manda una senial.
     if ((0, paths_1.isWindowsNative)()) {
+        if (win32LeaderReused(ref))
+            return false;
         killTreeWindows(ref.pid);
         if (await waitUntilGone(opts.termGraceMs))
             return true;
         killTreeWindows(ref.pid);
         return waitUntilGone(opts.killGraceMs);
     }
+    // Un PGID cuyo slot de lider fue reciclado hacia un proceso vivo ajeno
+    // NUNCA se confunde con el nuestro (mismo criterio que `refIsAlive`
+    // aplica en `terminateGroupConfirmed`, adaptado a un lider ya-muerto).
+    if (groupLeaderReused(ref))
+        return false;
     try {
         process.kill(-ref.processGroup, 'SIGTERM');
     }

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

@@ -65,7 +65,11 @@ function emitRequest(repoRoot, branch, env) {
     (0, atomic_file_1.fsyncDirSync)(dir); // la ENTRADA renombrada tambien debe sobrevivir un crash (R1.3)
     return { requestId, idempotencyKey: env.idempotencyKey, payloadDigest: digestOf(payload), file: final };
 }
-const KNOWN_KINDS = ['job-request', 'register-entity', 'controller-heartbeat', 'verdict'];
+const KNOWN_KINDS = [
+    'job-request', 'register-entity', 'controller-heartbeat', 'verdict',
+    'track-prepare-request', 'track-freeze-request', 'track-join-request',
+    'track-teardown-request', 'track-finalize-request',
+];
 function isRecord(x) {
     return typeof x === 'object' && x !== null && !Array.isArray(x);
 }

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

@@ -8,12 +8,17 @@ exports.readJournal = readJournal;
 exports.writeJournal = writeJournal;
 exports.appendEvent = appendEvent;
 const fs_1 = __importDefault(require("fs"));
+const crypto_1 = __importDefault(require("crypto"));
 const atomic_file_1 = require("../atomic-file");
 const types_1 = require("./types");
 const paths_1 = require("./paths");
-/** Schema 1 evoluciono de forma aditiva durante R1. Normalizamos solamente
+/** Schema 1 evoluciono de forma aditiva durante R1/R5. Normalizamos solamente
  * campos que antes no existian; evidencia legacy queda deliberadamente con
- * fingerprint vacio para que el gate la considere stale, nunca certificada. */
+ * fingerprint vacio para que el gate la considere stale, nunca certificada.
+ * `tracks`/`trackContext` NO se normalizan por ausencia: son opcionales
+ * (solo el journal de un plan-con-tracks o de un track individual los
+ * lleva), asi que faltar es una forma legitima, no legacy — no se les
+ * inventa un default para un journal que jamas los tuvo (R9.2). */
 function normalizeSchemaOne(value) {
     if (typeof value !== 'object' || value === null || Array.isArray(value))
         return value;
@@ -24,12 +29,39 @@ function normalizeSchemaOne(value) {
         parsed.requestProblems = [];
     if (parsed.custodyDecisions === undefined)
         parsed.custodyDecisions = [];
+    // R9.3: journals legacy pre-R5 no tenian journalId. Se materializa
+    // DETERMINISTICAMENTE desde (branch, cycle.startedAt) para que dos
+    // lecturas del MISMO snapshot legacy nunca produzcan identidades
+    // distintas (a diferencia de emptyState, que usa randomUUID solo para
+    // journals genuinamente nuevos). Se persiste en la siguiente escritura
+    // CAS normal — la lectura por si sola sigue siendo read-only.
+    if (parsed.journalId === undefined) {
+        const branch = typeof parsed.branch === 'string' ? parsed.branch : '';
+        const cycle = typeof parsed.cycle === 'object' && parsed.cycle !== null
+            ? parsed.cycle : {};
+        const startedAt = typeof cycle.startedAt === 'string' ? cycle.startedAt : '';
+        parsed.journalId = `legacy-${crypto_1.default.createHash('sha256')
+            .update(`${branch}\0${startedAt}`).digest('hex').slice(0, 32)}`;
+    }
     if (typeof parsed.cycle === 'object' && parsed.cycle !== null && !Array.isArray(parsed.cycle)) {
         const cycle = parsed.cycle;
         if (cycle.status === 'IN_PROGRESS' && cycle.nextAction === undefined) {
             cycle.nextAction = { actionId: 'bootstrap-cycle', type: 'plan-cycle', target: 'cycle', preconditions: [], attempt: 0, state: 'pending' };
         }
     }
+    // R7 Task 12: `Job.satisfies` migró de `string` a `string[]` (varios items
+    // satisfechos por un mismo job, ej. el job canónico de integración final).
+    // Un journal legacy con `satisfies` string se normaliza a un array de un
+    // elemento — jamás se pierde el enlace ya persistido.
+    if (typeof parsed.jobs === 'object' && parsed.jobs !== null && !Array.isArray(parsed.jobs)) {
+        for (const job of Object.values(parsed.jobs)) {
+            if (typeof job !== 'object' || job === null || Array.isArray(job))
+                continue;
+            const j = job;
+            if (typeof j.satisfies === 'string')
+                j.satisfies = [j.satisfies];
+        }
+    }
     if (Array.isArray(parsed.verdicts)) {
         for (const item of parsed.verdicts) {
             if (typeof item !== 'object' || item === null || Array.isArray(item))

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

@@ -1,12 +1,17 @@
 "use strict";
 // Única fuente de tipos del journal. CONSTITUTION: estados separados, nunca
 // sobrecargados; shape validation antes de usar campos deserializados.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GENERATION_STATES = exports.EXECUTION_STATES = void 0;
 exports.emptyState = emptyState;
 exports.isWellFormedState = isWellFormedState;
 exports.isWellFormedProcessRef = isWellFormedProcessRef;
 exports.isWellFormedJob = isWellFormedJob;
+const crypto_1 = __importDefault(require("crypto"));
+const types_1 = require("../tracks/types");
 exports.EXECUTION_STATES = [
     'received', 'spawn-intent', 'claimed', 'running',
     'exited', 'cancel-requested', 'cancelled', 'orphaned',
@@ -14,9 +19,21 @@ exports.EXECUTION_STATES = [
 exports.GENERATION_STATES = [
     'active', 'controller-suspected-stall', 'terminated', 'superseded',
 ];
+/** Debe permanecer sincronizado con el union type `CohortPhase` de
+ *  `../tracks/types` — ese módulo no exporta un const array propio (a
+ *  diferencia de TRACK_PHASES), así que replicamos la lista SOLO para shape
+ *  validation en el journal (nunca para lógica de protocolo, que vive en
+ *  tracks/protocol.ts). */
+const COHORT_PHASES = [
+    'PREPARING', 'ACTIVE', 'JOINING', 'FINAL_QA',
+    'FINAL_INTEGRATION', 'FINAL_INTERLOCK', 'COMPLETE',
+    'FALLBACK_PENDING', 'SERIAL', 'BLOCKED',
+];
+const _cohortPhasesComplete = true;
+const VERIFICATION_KINDS = ['test', 'lint', 'sensors', 'review', 'qa', 'interlock', 'track-integration'];
 function emptyState(branch) {
     return {
-        schema: 1, revision: 0, branch,
+        schema: 1, revision: 0, journalId: `j-${crypto_1.default.randomUUID()}`, branch,
         cycle: {
             status: 'IN_PROGRESS', startedAt: new Date().toISOString(),
             nextAction: { actionId: 'bootstrap-cycle', type: 'plan-cycle', target: 'cycle', preconditions: [], attempt: 0, state: 'pending' },
@@ -35,6 +52,8 @@ function isWellFormedState(x) {
         return false;
     if (typeof x.revision !== 'number')
         return false;
+    if (typeof x.journalId !== 'string' || x.journalId.length === 0)
+        return false;
     if (typeof x.branch !== 'string')
         return false;
     if (!isObj(x.cycle) || !['IN_PROGRESS', 'COMPLETE', 'BLOCKED'].includes(String(x.cycle.status))
@@ -48,7 +67,7 @@ function isWellFormedState(x) {
         return false;
     if (!Array.isArray(x.cycleVerificationPlan) || !Array.isArray(x.verdicts) || !Array.isArray(x.fixes))
         return false;
-    if (!Array.isArray(x.requiredVerifiers) || !x.requiredVerifiers.every((kind) => ['test', 'lint', 'sensors', 'review', 'qa', 'interlock'].includes(String(kind)))
+    if (!Array.isArray(x.requiredVerifiers) || !x.requiredVerifiers.every((kind) => VERIFICATION_KINDS.includes(kind))
         || !Array.isArray(x.dispatches) || !x.dispatches.every(isWellFormedDispatch))
         return false;
     if (!isObj(x.jobs) || !Object.values(x.jobs).every(isWellFormedJob))
@@ -65,6 +84,33 @@ function isWellFormedState(x) {
         return false;
     if (!x.verdicts.every(isWellFormedVerdict) || !x.fixes.every(isWellFormedFix))
         return false;
+    if (x.tracks !== undefined && (!Array.isArray(x.tracks) || !x.tracks.every(isWellFormedTrackRef)))
+        return false;
+    if (x.trackContext !== undefined && !isWellFormedTrackContext(x.trackContext))
+        return false;
+    if (x.cohortPhase !== undefined && !COHORT_PHASES.includes(String(x.cohortPhase)))
+        return false;
+    if (x.cohortBaseSha !== undefined && typeof x.cohortBaseSha !== 'string')
+        return false;
+    if (x.cohortPlanHeadSha !== undefined && typeof x.cohortPlanHeadSha !== 'string')
+        return false;
+    if (x.cohortFallbackReason !== undefined && typeof x.cohortFallbackReason !== 'string')
+        return false;
+    if (x.trackIntegration !== undefined && !isWellFormedTrackIntegration(x.trackIntegration))
+        return false;
+    if (x.freezeRequested !== undefined && typeof x.freezeRequested !== 'boolean')
+        return false;
+    if (x.frozen !== undefined && !(isObj(x.frozen) && typeof x.frozen.headSha === 'string' && typeof x.frozen.at === 'string'))
+        return false;
+    if (x.cohortParallelInvalidatedBy !== undefined && !strings(x.cohortParallelInvalidatedBy))
+        return false;
+    if (x.globalQaHeadSha !== undefined && typeof x.globalQaHeadSha !== 'string')
+        return false;
+    if (x.finalIntegrationJobId !== undefined && typeof x.finalIntegrationJobId !== 'string')
+        return false;
+    if (x.qaFinalizeRequested !== undefined
+        && !(isObj(x.qaFinalizeRequested) && typeof x.qaFinalizeRequested.headSha === 'string' && typeof x.qaFinalizeRequested.at === 'string'))
+        return false;
     return true;
 }
 function isWellFormedNextAction(x) {
@@ -80,7 +126,7 @@ function strings(x) {
 }
 function isWellFormedVerificationItem(x) {
     return isObj(x) && typeof x.id === 'string'
-        && ['test', 'lint', 'sensors', 'review', 'qa', 'interlock'].includes(String(x.kind))
+        && VERIFICATION_KINDS.includes(x.kind)
         && (x.satisfiedBy === undefined || typeof x.satisfiedBy === 'string');
 }
 function isWellFormedReviewObligation(x) {
@@ -159,7 +205,50 @@ function isWellFormedJob(x) {
         && (x.logPath === undefined || typeof x.logPath === 'string')
         && (x.result === undefined || (isObj(x.result) && typeof x.result.exitCode === 'number'
             && typeof x.result.endedAt === 'string' && typeof x.result.resultPath === 'string'))
-        && (x.satisfies === undefined || typeof x.satisfies === 'string')
+        && (x.satisfies === undefined || strings(x.satisfies))
         && (x.attemptOf === undefined || typeof x.attemptOf === 'string')
         && exports.EXECUTION_STATES.includes(x.executionState);
 }
+function isWellFormedTrackContext(x) {
+    return isObj(x) && typeof x.trackId === 'string' && x.trackId.length > 0
+        && strings(x.taskIds)
+        && typeof x.planDigest === 'string'
+        && typeof x.baseSha === 'string'
+        && typeof x.planJournalId === 'string' && x.planJournalId.length > 0;
+}
+function isWellFormedSupervisorIntent(x) {
+    return isObj(x) && typeof x.nonce === 'string' && x.nonce.length > 0
+        && strings(x.argv) && typeof x.claimPath === 'string';
+}
+function isWellFormedJoinIntent(x) {
+    return isObj(x) && typeof x.expectedPlanHeadSha === 'string' && typeof x.expectedTrackHeadSha === 'string'
+        && x.strategy === types_1.JOIN_STRATEGY_NO_FF;
+}
+function isWellFormedTeardownIntent(x) {
+    return isObj(x) && typeof x.worktreePath === 'string' && typeof x.branch === 'string'
+        && (x.supervisorNonce === undefined || typeof x.supervisorNonce === 'string');
+}
+/** Shape completa (R9.2/R9.7): fencingToken y readinessNonce nunca vacios —
+ *  igual criterio que ProcessRef, la identidad es todo-o-nada. */
+function isWellFormedTrackRef(x) {
+    if (!isObj(x))
+        return false;
+    return typeof x.trackId === 'string' && x.trackId.length > 0
+        && typeof x.worktreePath === 'string' && x.worktreePath.length > 0
+        && typeof x.branch === 'string' && x.branch.length > 0
+        && strings(x.ownership) && strings(x.sharedResources) && strings(x.dependsOn)
+        && typeof x.fencingToken === 'string' && x.fencingToken.length > 0
+        && types_1.TRACK_PHASES.includes(x.phase)
+        && typeof x.readinessNonce === 'string' && x.readinessNonce.length > 0
+        && (x.readinessAt === undefined || typeof x.readinessAt === 'string')
+        && (x.frozenHeadSha === undefined || typeof x.frozenHeadSha === 'string')
+        && (x.supervisorIntent === undefined || isWellFormedSupervisorIntent(x.supervisorIntent))
+        && (x.supervisorProcessRef === undefined || isWellFormedProcessRef(x.supervisorProcessRef))
+        && (x.joinIntent === undefined || isWellFormedJoinIntent(x.joinIntent))
+        && (x.teardownIntent === undefined || isWellFormedTeardownIntent(x.teardownIntent))
+        && (x.joinedCommitSha === undefined || typeof x.joinedCommitSha === 'string')
+        && (x.blockedReason === undefined || typeof x.blockedReason === 'string');
+}
+function isWellFormedTrackIntegration(x) {
+    return isObj(x) && strings(x.argv) && strings(x.paths) && typeof x.planDigest === 'string';
+}

package/dist/src/core/paths.js

@@ -12,6 +12,7 @@ exports.isWindowsNative = isWindowsNative;
 exports.platformLabel = platformLabel;
 exports.noteWindowsCaveat = noteWindowsCaveat;
 exports.resolveOnPath = resolveOnPath;
+exports.sameExistingPath = sameExistingPath;
 // cli/src/core/paths.ts
 //
 // Single source of truth for home / AWM_HOME resolution and platform detection.
@@ -158,3 +159,53 @@ function resolveOnPath(bin) {
     const entries = (process.env.PATH ?? '').split(path_1.default.delimiter).filter(Boolean);
     return entries.some((dir) => matches(path_1.default.join(dir, bin)));
 }
+/**
+ * ¿Dos rutas nombran el MISMO directorio/archivo existente?
+ *
+ * Comparar `fs.realpathSync(a) !== fs.realpathSync(b)` como strings parece obvio y es
+ * incorrecto en Windows: el mismo directorio tiene más de una grafía legítima —
+ * `C:\Users\RUNNER~1\AppData\...` (nombre corto 8.3, lo que devuelve `os.tmpdir()`) y
+ * `C:/Users/runneradmin/AppData/...` (lo que devuelve `git worktree list`, con separadores
+ * POSIX) — y `realpathSync` NO reconcilia las dos. En CI eso hacía que
+ * `ownedWorktreeExists` respondiera "este worktree no es mío" sobre un worktree propio.
+ *
+ * Falla cerrado, así que no corrompía nada — pero dejaba la adopción tras crash inservible
+ * en Windows: el teardown no podía probar propiedad, los tracks quedaban `BLOCKED`, y la
+ * cohorte no llegaba nunca ni a `SERIAL` ni a `ACTIVE`. Un solo bug de comparación, quince
+ * tests en cascada.
+ *
+ * La identidad se toma del filesystem — `(dev, ino)` — que es agnóstica a separadores, a
+ * mayúsculas y a nombres cortos. Cuando el volumen no expone inode (`ino === 0`, posible en
+ * algunos filesystems de Windows) se cae a `realpathSync.native` — que sí resuelve 8.3 vía
+ * la API del SO — normalizando separadores y capitalización.
+ *
+ * Cualquier fallo de `stat` significa que al menos una no existe: `false`. La identidad
+ * nunca se afirma sin prueba.
+ */
+function sameExistingPath(a, b) {
+    let sa;
+    let sb;
+    try {
+        sa = fs_1.default.statSync(a);
+        sb = fs_1.default.statSync(b);
+    }
+    catch {
+        return false;
+    }
+    // `ino === 0` en AMBOS lados no prueba identidad: probaría que el filesystem no la
+    // reporta. Tratarlo como match haría coincidir dos rutas cualesquiera del mismo volumen.
+    if (sa.ino !== 0 && sb.ino !== 0)
+        return sa.dev === sb.dev && sa.ino === sb.ino;
+    const canonical = (p) => {
+        try {
+            const real = fs_1.default.realpathSync.native(p).replaceAll('\\', '/');
+            return isWindowsNative() ? real.toLowerCase() : real;
+        }
+        catch {
+            return null;
+        }
+    };
+    const ca = canonical(a);
+    const cb = canonical(b);
+    return ca !== null && ca === cb;
+}

package/dist/src/core/tracks/concurrency.js

@@ -0,0 +1,85 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveDefaultParallelism = deriveDefaultParallelism;
+exports.parseMaxParallel = parseMaxParallel;
+exports.scheduleTracks = scheduleTracks;
+exports.loadDefaultParallelism = loadDefaultParallelism;
+// R10.2/R10.3: tope de paralelismo derivado de una medición real (fingerprint
+// budget, ver docs/research/r5/benchmark-fingerprint.mjs), nunca de un número
+// escrito a mano. Funciones puras/testeables — sin I/O aquí salvo
+// loadDefaultParallelism, que es un loader delgado sobre el artefacto
+// empaquetado y cae a serial (1) si no lo puede resolver (nunca crashea `awm watch`).
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+/** R10.3: el mayor N de supervisores concurrentes cuyo p95 medido no supera
+ *  1.5x el baseline serial (N=1) ni el 20% del tick — nunca N=1 si ninguna
+ *  medición lo habilita (R10.2, fail-closed hacia serial). */
+function deriveDefaultParallelism(budget) {
+    if (!Number.isInteger(budget.cpuCount) || budget.cpuCount < 1 || budget.samples.length === 0)
+        throw new Error('budget inválido');
+    const baseline = budget.samples.find((s) => s.supervisors === 1);
+    if (baseline === undefined || baseline.p95Ms <= 0)
+        throw new Error('budget sin baseline N=1');
+    return budget.samples
+        .filter((s) => Number.isInteger(s.supervisors) && s.supervisors <= budget.cpuCount
+        && s.p95Ms <= baseline.p95Ms * 1.5 && s.p95Ms <= budget.tickMs * 0.2)
+        .reduce((max, s) => Math.max(max, s.supervisors), 1);
+}
+/** Parsea `--max-parallel <n>`, mismo estilo de validación que `minutes()` en
+ *  watch/index.ts: entero >= 1, fail-closed en cualquier otro caso. */
+function parseMaxParallel(raw) {
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n < 1)
+        throw new Error('--max-parallel requiere un entero >= 1');
+    return n;
+}
+/** Todos los tracks alcanzan ARMED; solo hasta `maxParallel` (menos los ya
+ *  activos) pasan a arrancar. El resto queda `waiting` — el wrapper excedente
+ *  espera sin arrancar su loop de watch/fingerprint hasta que un slot libere. */
+function scheduleTracks(tracks, active, maxParallel) {
+    if (!Number.isInteger(maxParallel) || maxParallel < 1)
+        throw new Error('maxParallel debe ser entero >= 1');
+    const capacity = Math.max(0, maxParallel - active.size);
+    const candidates = tracks.filter((t) => !active.has(t));
+    return { start: candidates.slice(0, capacity), waiting: candidates.slice(capacity) };
+}
+/** Busca `docs/research/r5/fingerprint-budget.json` subiendo desde `startDir`
+ *  (por defecto este archivo), sin asumir una profundidad fija de directorios.
+ *  `startDir` es parametrizable solo para poder testear los caminos de fallo
+ *  de `loadDefaultParallelism` con un árbol de directorios controlado —
+ *  ver docs/research/r5/benchmark-fingerprint.mjs para el estado real de
+ *  distribución de este artefacto (hoy NO viaja en el npm publish). */
+function findBudgetArtifact(startDir) {
+    let dir = startDir;
+    for (let i = 0; i < 8; i += 1) {
+        const candidate = path_1.default.join(dir, 'docs', 'research', 'r5', 'fingerprint-budget.json');
+        if (fs_1.default.existsSync(candidate))
+            return candidate;
+        const parent = path_1.default.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+/** `derivedDefault` del artefacto, si se puede resolver y es válido. Si el
+ *  artefacto no resuelve, tiene JSON corrupto, o `derivedDefault` falta / no
+ *  es entero / es < 1, cae a serial (1) — nunca crashea `awm watch` por esto.
+ *  `startDir` default = este archivo; solo se sobreescribe en tests. */
+function loadDefaultParallelism(startDir = __dirname) {
+    const artifactPath = findBudgetArtifact(startDir);
+    if (artifactPath === null)
+        return 1;
+    try {
+        const data = JSON.parse(fs_1.default.readFileSync(artifactPath, 'utf8'));
+        if (Number.isInteger(data.derivedDefault) && data.derivedDefault >= 1)
+            return data.derivedDefault;
+        return 1;
+    }
+    catch {
+        return 1;
+    }
+}