agentic-workflow-manager 9.7.1 → 9.9.0

package/README.md

@@ -41,9 +41,13 @@ This generates the runnable output under `dist/index.js`.
 ### 4. Running the Tests
 Before submitting a PR, ensure that the core discovery/executor functionality passes the existing test suite:
 ```bash
+npm run native:build
 npm test
 ```
-The goal is to maintain 100% passing tests for any new CLI parameter flags.
+`native:build` creates the ignored, host-specific `secure-fs` artifact required
+by the integration fixtures; it must be run again after a clean checkout or a
+change under `native/`. The goal is to maintain 100% passing tests for any new
+CLI parameter flags.
 
 ### 5. Local Execution (Testing changes locally)
 

package/dist/src/commands/job/exec-wrapper.js

@@ -17,19 +17,33 @@ const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const child_process_1 = require("child_process");
 const process_1 = require("../../core/journal/process");
+const paths_1 = require("../../core/journal/paths");
+const types_1 = require("../../core/journal/types");
+const native_bridge_1 = require("../../core/secure-fs/native-bridge");
 const fingerprint_1 = require("../../core/journal/fingerprint");
 const redact_1 = require("../../core/journal/redact");
 const atomic_file_1 = require("../../core/atomic-file");
+function validateSidecarIdentity(logsRoot, jobId, nonce) {
+    if (typeof logsRoot !== 'string' || logsRoot.length === 0 || logsRoot.length > 4096 || /[\u0000-\u001F\u007F]/.test(logsRoot)
+        || typeof jobId !== 'string' || !/^[A-Za-z0-9_-][A-Za-z0-9_.-]{0,127}$/.test(jobId)
+        || typeof nonce !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(nonce)
+        || jobId.length + nonce.length > 230)
+        throw new Error('unsafe or unbounded sidecar identity');
+}
 function claimPath(logsRoot, jobId, nonce) {
+    validateSidecarIdentity(logsRoot, jobId, nonce);
     return path_1.default.join(logsRoot, `${jobId}.${nonce}.claim`);
 }
 function identityPath(logsRoot, jobId, nonce) {
+    validateSidecarIdentity(logsRoot, jobId, nonce);
     return path_1.default.join(logsRoot, `${jobId}.${nonce}.identity.json`);
 }
 function resultPath(logsRoot, jobId, nonce) {
+    validateSidecarIdentity(logsRoot, jobId, nonce);
     return path_1.default.join(logsRoot, `${jobId}.${nonce}.result.json`);
 }
 function logPath(logsRoot, jobId, nonce) {
+    validateSidecarIdentity(logsRoot, jobId, nonce);
     return path_1.default.join(logsRoot, `${jobId}.${nonce}.log`);
 }
 function replayVerdict(logsRoot, jobId, nonce) {
@@ -45,11 +59,46 @@ const MAX_LOG_BYTES = 1024 * 1024; // retencion acotada (R2.5)
 // dispara, tipicamente entregados en 1 tick del event loop) sin acercarse a
 // una espera perceptible si un descendiente hereda los fds y nunca cierra.
 const STDIO_GRACE_MS = 300;
+/** Only a committed generation intent may suppress controller output. A user
+ * job with the same name retains normal verifier logs. Never persist model
+ * output (which may include prompts/source bodies) in generation custody. */
+function isCommittedController(logsRoot, repoRoot, jobId, nonce, argv) {
+    if (!/^controller-gen-[1-9][0-9]*$/.test(jobId))
+        return false;
+    try {
+        const bytes = native_bridge_1.secureFs.readRegularFile(path_1.default.resolve(logsRoot, '..', 'state.json'), 1024 * 1024).bytes;
+        const state = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+        if (!(0, types_1.isWellFormedState)(state))
+            throw new Error('controller custody journal invalid');
+        const actual = fs_1.default.lstatSync(logsRoot, { bigint: true });
+        const expected = fs_1.default.lstatSync((0, paths_1.logsDir)(repoRoot, state.branch), { bigint: true });
+        if (!actual.isDirectory() || actual.isSymbolicLink() || !expected.isDirectory() || expected.isSymbolicLink()
+            || actual.ino === 0n || actual.dev !== expected.dev || actual.ino !== expected.ino)
+            throw new Error('controller custody directory identity invalid');
+        const committed = state.generations.some(gen => gen.controllerJobId === jobId && jobId === `controller-gen-${gen.n}`
+            && gen.spawnNonce === nonce && gen.resumePrompt === undefined && (0, types_1.isControllerRecoveryAction)(gen.resumeAction)
+            && gen.launchArgvDigest === (0, process_1.argvDigest)(argv));
+        if (committed)
+            return true;
+        const ordinary = state.jobs[jobId];
+        if (ordinary?.spawnNonce === nonce && (0, process_1.argvDigest)(ordinary.argv) === (0, process_1.argvDigest)(argv))
+            return false;
+        throw new Error('controller custody launch identity unproven');
+    }
+    catch {
+        throw new Error('controller custody identity unavailable or unsafe: refusing launch before claim');
+    }
+}
 async function runExecWrapper(opts) {
     const { logsRoot, jobId, nonce, argv, cwd } = opts;
+    validateSidecarIdentity(logsRoot, jobId, nonce);
     const repoRoot = opts.repoRoot ?? process.cwd();
-    if (argv.length === 0)
-        throw new Error('argv vacio');
+    if (!Array.isArray(argv) || argv.length === 0 || argv.length > 256
+        || argv.some(argument => typeof argument !== 'string' || argument.length > 65536 || argument.includes('\0'))
+        || argv[0].length === 0 || argv.reduce((bytes, argument) => bytes + Buffer.byteLength(argument, 'utf8'), 0) > 1024 * 1024)
+        throw new Error('argv invalid or unbounded');
+    const safeCwd = (0, fingerprint_1.resolveWorkingDirectory)(repoRoot, cwd).absolute;
+    const omitControllerOutput = isCommittedController(logsRoot, repoRoot, jobId, nonce, argv);
     fs_1.default.mkdirSync(logsRoot, { recursive: true, mode: 0o700 });
     // (1) claim exclusivo DURABLE — wx + fsync de archivo y de directorio
     let fd;
@@ -77,7 +126,6 @@ async function runExecWrapper(opts) {
     // process group por job, independiente del supervisor (R4.7: shell:false,
     // argv como array, secretos solo por referencia de entorno).
     const [exe, ...args] = argv;
-    const safeCwd = (0, fingerprint_1.resolveWorkingDirectory)(repoRoot, cwd).absolute;
     const child = (0, child_process_1.spawn)(exe, args, {
         cwd: safeCwd, shell: false, detached: true,
         env: { ...process.env, [process_1.NONCE_ENV]: nonce },
@@ -105,6 +153,8 @@ async function runExecWrapper(opts) {
     const outputChunks = [];
     const logFile = logPath(logsRoot, jobId, nonce);
     const capture = (chunk) => {
+        if (omitControllerOutput)
+            return;
         if (captured >= MAX_LOG_BYTES)
             return;
         const accepted = chunk.subarray(0, MAX_LOG_BYTES - captured);

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

@@ -3,6 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.computeGate = computeGate;
 exports.computeTrackGate = computeTrackGate;
 const LIVE = ['received', 'spawn-intent', 'claimed', 'running', 'cancel-requested'];
+function sameSelection(left, right) {
+    return left.selector.kind === right.selector.kind && left.selector.id === right.selector.id && left.effort.kind === right.effort.kind && left.effort.value === right.effort.value;
+}
 function evaluateEvidence(state, fingerprintNow, scope) {
     const reasons = [];
     if (state.cycle.status === 'BLOCKED') {
@@ -123,6 +126,21 @@ function evaluateEvidence(state, fingerprintNow, scope) {
         }
     }
     for (const v of state.verdicts) {
+        if (v.routingAttemptId !== undefined) {
+            const attempt = state.routingAttempts?.find((candidate) => candidate.id === v.routingAttemptId);
+            const binding = state.planBinding;
+            const bound = binding !== undefined && binding.digest === attempt?.envelope.planDigest && binding.executionDigest === attempt?.envelope.executionDigest;
+            const observed = attempt?.observed;
+            const selectionMatches = attempt !== undefined && observed !== undefined && sameSelection(observed, attempt.envelope.resolved);
+            // A reported actual selection is authoritative: degradation may
+            // explain absent observability, never excuse an observed mismatch.
+            const nativeObservationValid = observed !== undefined
+                ? selectionMatches
+                : attempt?.envelope.outcome === 'degraded' && (attempt.envelope.unavailableEvidence.length ?? 0) > 0 && Boolean(attempt.reasonCode);
+            if (attempt === undefined || !['active', 'complete'].includes(attempt.state) || !attempt.nativeAgentId || attempt.obligationId !== v.obligationId || attempt.fingerprint !== v.fingerprint || !bound || !nativeObservationValid) {
+                reasons.push({ category: 'routing-evidence', detail: `verdict routed ${v.id} no tiene evidencia de intento observado, vigente y ligado` });
+            }
+        }
         if (v.result !== 'pass') {
             const fix = state.fixes.find((f) => f.verdictId === v.id);
             if (fix === undefined || !fix.closed)

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

@@ -23,6 +23,9 @@ 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 journal_1 = require("../../core/model-policy/journal");
+const types_1 = require("../../core/journal/types");
+const json_1 = require("../../core/plan/json");
 const fs_1 = __importDefault(require("fs"));
 function branchOf(cwd) {
     // stdio explicito (ver EXEC_STDIO en journal/process.ts): evita el relay
@@ -43,6 +46,19 @@ function realFingerprintNow(repo) {
         }
     };
 }
+function readBoundedJson(file) {
+    if (typeof file !== 'string' || file.length === 0 || file.length > 4096)
+        throw new Error('routing file path is invalid');
+    const stat = fs_1.default.lstatSync(file);
+    if (stat.isSymbolicLink() || !stat.isFile() || stat.size > 256 * 1024)
+        throw new Error('routing file must be a bounded non-symlink regular file');
+    try {
+        return (0, json_1.parseJsonNoDuplicate)(fs_1.default.readFileSync(file, 'utf8'));
+    }
+    catch {
+        throw new Error('routing file must contain JSON without duplicate keys');
+    }
+}
 /** 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
@@ -143,6 +159,36 @@ function registerJobCommand(program) {
         assertAuthenticatedCwd(repo, branch);
         (0, heartbeat_1.emitHeartbeat)(repo, branch, opts.generation);
     });
+    job.command('routing-reserve')
+        .requiredOption('--generation <token>').requiredOption('--obligation <id>').requiredOption('--lineage <id>')
+        .requiredOption('--envelope-file <file>').requiredOption('--fingerprint <sha>').option('--cwd <root>', 'repository root', '.').option('--json')
+        .action((opts) => {
+        const envelope = readBoundedJson(opts.envelopeFile);
+        if (!(0, types_1.isRoutingEnvelope)(envelope) || !/^[a-f0-9]{64}$/.test(opts.fingerprint))
+            throw new Error('routing-reserve requires a valid envelope and fingerprint');
+        const repo = path_1.default.resolve(opts.cwd);
+        const branch = branchOf(repo);
+        assertAuthenticatedCwd(repo, branch);
+        const emitted = (0, requests_1.emitRequest)(repo, branch, { kind: 'routing-reserve', generationToken: opts.generation, idempotencyKey: crypto_1.default.createHash('sha256').update(`routing-reserve:${opts.generation}:${opts.obligation}:${opts.lineage}:${opts.fingerprint}:${JSON.stringify(envelope)}`).digest('hex'), payload: { obligationId: opts.obligation, lineageId: opts.lineage, envelope, fingerprint: opts.fingerprint } });
+        process.stdout.write(JSON.stringify({ requestId: emitted.requestId }) + '\n');
+    });
+    job.command('routing-observe')
+        .requiredOption('--generation <token>').requiredOption('--attempt <id>').requiredOption('--native-agent-id <id>')
+        .requiredOption('--observation-file <file>').option('--cwd <root>', 'repository root', '.').option('--json')
+        .action((opts) => {
+        const observation = readBoundedJson(opts.observationFile);
+        if (typeof observation !== 'object' || observation === null || Array.isArray(observation))
+            throw new Error('routing-observe requires an observation object');
+        const observed = observation.observed;
+        const unavailableReason = observation.unavailableReason;
+        if ((observed !== undefined && !(0, types_1.isRoutingSelection)(observed)) || (unavailableReason !== undefined && typeof unavailableReason !== 'string'))
+            throw new Error('routing-observe requires a valid observation');
+        const repo = path_1.default.resolve(opts.cwd);
+        const branch = branchOf(repo);
+        assertAuthenticatedCwd(repo, branch);
+        const emitted = (0, requests_1.emitRequest)(repo, branch, { kind: 'routing-observe', generationToken: opts.generation, idempotencyKey: crypto_1.default.createHash('sha256').update(`routing-observe:${opts.generation}:${opts.attempt}:${opts.nativeAgentId}:${JSON.stringify(observation)}`).digest('hex'), payload: { attemptId: opts.attempt, nativeAgentId: opts.nativeAgentId, ...(observed === undefined ? {} : { observed }), ...(unavailableReason === undefined ? {} : { unavailableReason }) } });
+        process.stdout.write(JSON.stringify({ requestId: emitted.requestId }) + '\n');
+    });
     job.command('ps').action(() => {
         const repo = process.cwd();
         const branch = branchOf(repo);
@@ -216,6 +262,21 @@ function registerJobCommand(program) {
         if (!g.pass)
             process.exit(1); // falla cerrado (R3.2)
     });
+    job.command('routing-report')
+        .description('informe de routing read-only; nunca expone envelopes ni identidad nativa')
+        .option('--json', 'emit the routing report as JSON')
+        .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 }) + '\n');
+            process.exit(1);
+            return;
+        }
+        process.stdout.write(JSON.stringify((0, journal_1.routingReport)(r.state), null, 2) + '\n');
+    });
     job.command('reap')
         .description('lista procesos de jobs (identidad completa); --execute --jobs <ids...> para terminar confirmando')
         .option('--execute', 'ejecutar la terminacion de los jobs listados en --jobs')

package/dist/src/commands/model-policy/index.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerModelPolicyCommand = registerModelPolicyCommand;
+const crypto_1 = require("crypto");
+const providers_1 = require("../../providers");
+const store_1 = require("../../core/model-policy/store");
+const validate_1 = require("../../core/model-policy/validate");
+const capabilities_1 = require("../../core/model-policy/capabilities");
+const roles = ['implementer', 'specification-reviewer', 'code-quality-reviewer', 'final-reviewer', 'architecture', 'track-a-qa', 'track-b-qa', 'controller', 'documentation', 'retro', 'finishing'];
+const implementerProfiles = ['mechanical', 'integration', 'judgment'];
+const contract = { schema: 'routing-protocol/v1', supportedPlanSchemas: ['compact-slices/v1', 'compact-slices/v2'], roles, implementerProfiles, limits: { maxFileBytes: validate_1.MAX_POLICY_BYTES, maxMappings: validate_1.MAX_MAPPINGS, maxIdentifierChars: 128, maxDiagnostics: 20, maxDiagnosticChars: 4096 } };
+const protocolDigest = (0, crypto_1.createHash)('sha256').update(JSON.stringify(contract), 'utf8').digest('hex');
+function text(value, label) { if (typeof value !== 'string' || value.length === 0 || value.startsWith('--') || value.length > 4096 || /[\u0000-\u001f\u007f-\u009f]/.test(value))
+    throw new Error(`${label} requires a non-empty value without control characters`); }
+function output(value, json) { process.stdout.write(json ? `${JSON.stringify(value)}\n` : `${JSON.stringify(value, null, 2)}\n`); }
+function registerModelPolicyCommand(program, deps = {}) {
+    if (!program || typeof program.command !== 'function')
+        throw new Error('program must be a Commander command');
+    const approve = deps.approvePolicy ?? store_1.approvePolicy;
+    const read = deps.readEffectivePolicy ?? store_1.readEffectivePolicy;
+    const approveReceipt = deps.approveCapabilities ?? capabilities_1.approveCapabilities;
+    const readReceipt = deps.readCapabilities ?? capabilities_1.readCapabilities;
+    const command = program.command('model-policy').description('inspect and explicitly approve portable routing policy');
+    command.command('contract').option('--cwd <path>').option('--json').action((options) => { if (options.cwd !== undefined)
+        text(options.cwd, '--cwd'); output({ ...contract, protocolDigest }, options.json === true); });
+    command.command('approve').requiredOption('--file <path>').requiredOption('--scope <scope>').requiredOption('--expected-digest <sha>').option('--replace-digest <sha>').option('--cwd <path>').option('--json').action((options) => {
+        text(options.file, '--file');
+        text(options.scope, '--scope');
+        text(options.expectedDigest, '--expected-digest');
+        if (options.cwd !== undefined)
+            text(options.cwd, '--cwd');
+        if (options.replaceDigest !== undefined)
+            text(options.replaceDigest, '--replace-digest');
+        (0, validate_1.assertDigest)(options.expectedDigest, 'expectedDigest');
+        if (options.replaceDigest !== undefined)
+            (0, validate_1.assertDigest)(options.replaceDigest, 'replaceDigest');
+        const policy = approve({ file: options.file, scope: options.scope, cwd: options.cwd ?? process.cwd(), expectedDigest: options.expectedDigest, replaceDigest: options.replaceDigest });
+        output({ state: 'approved', policy }, options.json === true);
+    });
+    command.command('capabilities approve').requiredOption('--file <path>').requiredOption('--expected-digest <sha>').option('--replace-digest <sha>').option('--cwd <path>').option('--json').action((options) => {
+        text(options.file, '--file');
+        text(options.expectedDigest, '--expected-digest');
+        if (options.replaceDigest !== undefined)
+            text(options.replaceDigest, '--replace-digest');
+        if (options.cwd !== undefined)
+            text(options.cwd, '--cwd');
+        (0, validate_1.assertDigest)(options.expectedDigest, 'expectedDigest');
+        if (options.replaceDigest)
+            (0, validate_1.assertDigest)(options.replaceDigest, 'replaceDigest');
+        output({ state: 'approved', receipt: approveReceipt({ file: options.file, cwd: options.cwd ?? process.cwd(), expectedDigest: options.expectedDigest, replaceDigest: options.replaceDigest }) }, options.json === true);
+    });
+    command.command('status').requiredOption('--provider <target>').requiredOption('--runtime-kind <kind>').requiredOption('--runtime-version <version>').requiredOption('--account-scope-digest <sha>').option('--cwd <path>').option('--json').action((options) => {
+        text(options.provider, '--provider');
+        text(options.runtimeKind, '--runtime-kind');
+        text(options.runtimeVersion, '--runtime-version');
+        text(options.accountScopeDigest, '--account-scope-digest');
+        if (options.cwd !== undefined)
+            text(options.cwd, '--cwd');
+        if (!providers_1.AGENT_TARGETS.includes(options.provider))
+            throw new Error('--provider is invalid');
+        if (!/^[a-z0-9][a-z0-9_-]{0,127}$/.test(options.runtimeKind))
+            throw new Error('--runtime-kind is invalid');
+        if (!/^\d+\.\d+\.\d+$/.test(options.runtimeVersion))
+            throw new Error('--runtime-version must be numeric semver');
+        (0, validate_1.assertDigest)(options.accountScopeDigest, 'accountScopeDigest');
+        const cwd = options.cwd ?? process.cwd();
+        const effective = read(cwd);
+        const capability = readReceipt({ target: options.provider, kind: options.runtimeKind, version: options.runtimeVersion, accountScopeDigest: options.accountScopeDigest }, new Date());
+        output({ policy: effective, capability }, options.json === true);
+        if (effective.state !== 'approved' || capability.state !== 'current')
+            process.exitCode = 2;
+    });
+}

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

@@ -1,13 +1,43 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.exitCodeFor = exitCodeFor;
 exports.formatReport = formatReport;
 exports.registerPlanCommand = registerPlanCommand;
 const validate_1 = require("../../core/plan/validate");
-const SUPPORTED_SCHEMA = 'compact-slices/v1';
+const admission_1 = require("../../core/admission");
+const check_1 = require("../../core/currentness/check");
+const run_1 = require("../sensors/run");
+const config_1 = require("../../utils/config");
+const providers_1 = require("../../providers");
+const registries_1 = require("../../core/registries");
+const registry_contracts_1 = require("../../core/admission/registry-contracts");
+const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
+const store_1 = require("../../core/journal/store");
+const migration_1 = require("../../core/migration");
+const store_2 = require("../../core/model-policy/store");
+const capabilities_1 = require("../../core/model-policy/capabilities");
+const resolve_1 = require("../../core/model-policy/resolve");
+const journal_1 = require("../../core/model-policy/journal");
+const SUPPORTED_SCHEMA = 'compact-slices/v1, compact-slices/v2';
 const MAX_PATH_LENGTH = 4096;
 const MAX_DIAGNOSTICS = 20;
 const MAX_DIAGNOSTIC_LENGTH = 4096;
+function journalObservation(cwd) {
+    try {
+        const branch = (0, child_process_1.execFileSync)('git', ['branch', '--show-current'], { cwd, encoding: 'utf8', stdio: 'pipe' }).trim();
+        if (!branch)
+            return { journalState: null, journalCorrupt: true };
+        const journal = (0, store_1.readJournal)(cwd, branch);
+        return { journalState: journal.state, journalCorrupt: journal.corrupt };
+    }
+    catch {
+        return { journalState: null, journalCorrupt: true };
+    }
+}
 function assertText(value, name) {
     if (typeof value !== 'string' || value.length === 0 || value.length > MAX_PATH_LENGTH || value.startsWith('--') || /[\u0000-\u001F\u007F-\u009F]/.test(value)) {
         throw new Error(`${name} must be a non-empty path without control characters`);
@@ -19,6 +49,15 @@ function terminalSafe(value) {
 function assertDependencies(deps) {
     if (!deps || typeof deps.validatePlanFile !== 'function')
         throw new Error('validatePlanFile must be a function');
+    if (deps.admitPlan !== undefined && typeof deps.admitPlan !== 'function')
+        throw new Error('admitPlan must be a function');
+}
+function admissionOutput(report, json) {
+    report = (0, admission_1.sanitizeAdmissionReport)(report);
+    if (json)
+        return `${JSON.stringify(report)}\n`;
+    const diagnostic = report.diagnostics[0];
+    return `Plan admission: ${report.state}${report.provider ? ` (${terminalSafe(report.provider)})` : ''}${diagnostic ? `\n- ${terminalSafe(diagnostic.code)}: ${terminalSafe(diagnostic.message)}` : ''}\n`;
 }
 function boundedDiagnostics(diagnostics) {
     if (!Array.isArray(diagnostics))
@@ -34,16 +73,42 @@ function boundedDiagnostics(diagnostics) {
         };
     });
 }
+function assertReport(report) {
+    if (!report || typeof report !== 'object' || Array.isArray(report))
+        throw new Error('plan validator returned an invalid report');
+    switch (report.state) {
+        case 'valid':
+            (0, validate_1.assertVerifiedValidPlanReport)(report);
+            return;
+        case 'migration-required':
+            if (report.reason !== 'unmarked-plan')
+                throw new Error('plan validator returned an invalid migration reason');
+            return;
+        case 'invalid':
+            boundedDiagnostics(report.diagnostics);
+            return;
+        case 'unsupported':
+            if (typeof report.schema !== 'string' || report.schema.length === 0 || report.schema.length > MAX_PATH_LENGTH) {
+                throw new Error('plan validator returned an invalid unsupported schema');
+            }
+            boundedDiagnostics(report.diagnostics);
+            return;
+        default:
+            throw new Error('plan validator returned an unknown report state');
+    }
+}
 function reportPayload(report, planPath) {
+    assertReport(report);
     switch (report.state) {
         case 'valid':
             return {
                 state: report.state, path: planPath, schema: report.schema, planId: report.manifest.planId,
+                planDigest: report.planDigest,
                 requirements: report.manifest.requirements.length, sources: report.manifest.sources.length,
                 commands: report.manifest.commands.length, slices: report.manifest.slices.length, completeOwnership: true,
             };
-        case 'legacy':
-            return { state: report.state, path: planPath, message: 'existing full-quality path applies; compact optimization was not requested.' };
+        case 'migration-required':
+            return { state: report.state, path: planPath, reason: report.reason };
         case 'invalid':
             return { state: report.state, path: planPath, diagnostics: boundedDiagnostics(report.diagnostics) };
         case 'unsupported':
@@ -56,15 +121,16 @@ function reportPayload(report, planPath) {
     }
 }
 function exitCodeFor(report) {
-    return report.state === 'valid' || report.state === 'legacy' ? 0 : 2;
+    assertReport(report);
+    return report.state === 'valid' ? 0 : 2;
 }
 function formatReport(report, planPath) {
     const payload = reportPayload(report, planPath);
     switch (report.state) {
         case 'valid':
             return `Plan validation: valid "${terminalSafe(planPath)}" (${terminalSafe(report.schema)}; ${payload.slices} slices; ${payload.requirements} requirements; complete ownership)\n`;
-        case 'legacy':
-            return `Plan validation: legacy "${terminalSafe(planPath)}" — existing full-quality path applies; compact optimization was not requested.\n`;
+        case 'migration-required':
+            return `Plan validation: migration-required "${terminalSafe(planPath)}" (${terminalSafe(report.reason)})\nMigrate this plan to compact-slices/v1 before execution.\n`;
         case 'invalid':
             return `Plan validation: invalid "${terminalSafe(planPath)}"\n${payload.diagnostics.map(diagnostic => `- ${terminalSafe(diagnostic.code)}: ${terminalSafe(diagnostic.message)}${diagnostic.field ? ` (${terminalSafe(diagnostic.field)})` : ''}`).join('\n')}\n`;
         case 'unsupported':
@@ -73,11 +139,72 @@ function formatReport(report, planPath) {
             throw new Error('plan validator returned an unknown report state');
     }
 }
-function registerPlanCommand(program, deps = { validatePlanFile: validate_1.validatePlanFile }) {
+function registerPlanCommand(program, deps = { validatePlanFile: validate_1.validatePlanFile, admitPlan: admission_1.admitPlan }) {
     if (!program || typeof program.command !== 'function')
         throw new Error('program must be a Commander command');
     assertDependencies(deps);
     const plan = program.command('plan').description('inspect plan contracts');
+    plan.command('resolve <plan-path>').requiredOption('--provider <target>').requiredOption('--runtime-kind <kind>').requiredOption('--runtime-version <version>').requiredOption('--account-scope-digest <sha>').requiredOption('--role <role>').option('--opt-in-v1').option('--slice <id>').option('--lineage <id>').option('--cwd <path>').option('--json').action((planPath, options) => {
+        assertText(planPath, 'plan path');
+        for (const [value, label] of [[options.provider, '--provider'], [options.runtimeKind, '--runtime-kind'], [options.runtimeVersion, '--runtime-version'], [options.accountScopeDigest, '--account-scope-digest'], [options.role, '--role']])
+            assertText(value, label);
+        if (options.slice)
+            assertText(options.slice, '--slice');
+        if (options.lineage)
+            assertText(options.lineage, '--lineage');
+        const cwd = options.cwd ?? process.cwd();
+        assertText(cwd, '--cwd');
+        const report = deps.validatePlanFile(planPath, cwd);
+        assertReport(report);
+        if (report.state !== 'valid') {
+            process.stdout.write(options.json ? `${JSON.stringify({ state: 'blocked', diagnostics: report.state === 'invalid' ? report.diagnostics : [{ code: 'ROUTING_PLAN_INVALID', message: 'Plan must validate before resolution.' }] })}\n` : 'Plan routing: blocked\n');
+            process.exitCode = 2;
+            return;
+        }
+        if (options.lineage) {
+            if (report.schema !== 'compact-slices/v2') {
+                process.stdout.write(options.json ? `${JSON.stringify({ state: 'blocked', diagnostics: [{ code: 'ROUTING_LINEAGE_V1', message: 'Lineage routing is only available for compact v2 plans.' }] })}\n` : 'Plan routing: blocked\n');
+                process.exitCode = 2;
+                return;
+            }
+            const observed = journalObservation(cwd);
+            const binding = observed.journalState?.planBinding;
+            const attempts = observed.journalState?.routingAttempts?.filter((attempt) => attempt.lineageId === options.lineage) ?? [];
+            const lineage = observed.journalState?.implementationLineages?.find((candidate) => candidate.id === options.lineage);
+            const bound = !observed.journalCorrupt && binding?.digest === report.planDigest && binding.executionDigest === report.executionDigest;
+            const lineageMatches = lineage !== undefined && lineage.sliceId === options.slice && lineage.planDigest === report.planDigest && lineage.executionDigest === report.executionDigest && attempts.every((attempt) => attempt.obligationId === lineage.obligationId && attempt.envelope.sliceId === options.slice);
+            if (!bound || !lineageMatches || attempts.length > 3 || attempts.some((attempt) => attempt.envelope.planDigest !== report.planDigest || attempt.envelope.executionDigest !== report.executionDigest || ['unknown', 'reserved', 'active'].includes(attempt.state))) {
+                process.stdout.write(options.json ? `${JSON.stringify({ state: 'blocked', diagnostics: [{ code: 'ROUTING_LINEAGE_UNBOUND', message: 'Lineage routing requires a current journal binding and non-unknown matching attempts.' }] })}\n` : 'Plan routing: blocked\n');
+                process.exitCode = 2;
+                return;
+            }
+        }
+        const roles = ['implementer', 'specification-reviewer', 'code-quality-reviewer', 'final-reviewer', 'architecture', 'track-a-qa', 'track-b-qa', 'controller', 'documentation', 'retro', 'finishing'];
+        if (!roles.includes(options.role))
+            throw new Error('--role is invalid');
+        const runtime = (0, capabilities_1.validateRuntimeKey)({ target: options.provider, kind: options.runtimeKind, version: options.runtimeVersion, accountScopeDigest: options.accountScopeDigest });
+        const result = report.schema === 'compact-slices/v1' && !options.optInV1 ? (0, resolve_1.resolveDispatch)({ plan: report, role: options.role, policy: undefined, capabilities: undefined, runtime, now: new Date(), optInV1: false }) : (() => { const policy = (deps.readEffectivePolicy ?? store_2.readEffectivePolicy)(cwd); const capabilities = (deps.readCapabilities ?? capabilities_1.readCapabilities)(runtime, new Date()); if (!options.lineage)
+            return (0, resolve_1.resolveDispatch)({ plan: report, role: options.role, sliceId: options.slice, policy: policy.state === 'approved' ? policy.policy : undefined, capabilities: capabilities.state === 'current' ? capabilities.receipt : undefined, runtime, now: new Date(), optInV1: options.optInV1 === true }); const state = journalObservation(cwd).journalState; const lineage = state.implementationLineages.find(candidate => candidate.id === options.lineage); const next = (0, journal_1.resolveLineageEscalation)(state, options.lineage, lineage.initialProfile); const resolved = (0, resolve_1.resolveSelection)({ role: 'implementer', requestedProfile: next.profile, policy: policy.state === 'approved' ? policy.policy : undefined, capabilities: capabilities.state === 'current' ? capabilities.receipt : undefined, runtime, now: new Date() }); if (resolved.state === 'blocked')
+            return resolved; const highRequiresFull = next.effort !== 'high' || (policy.state === 'approved' && (() => { const full = policy.policy.content.mappings.find(row => row.target === runtime.target && row.runtimeKind === runtime.kind)?.fullCapability; return full?.selector.kind === resolved.selection.selector.kind && full.selector.id === resolved.selection.selector.id && full.effort.kind === 'explicit' && full.effort.value === 'high'; })()); if (resolved.selection.effort.kind !== 'explicit' || resolved.selection.effort.value !== next.effort || !highRequiresFull)
+            return { state: 'blocked', diagnostics: [{ code: 'ROUTING_ESCALATION_EFFORT_UNAVAILABLE', message: 'The approved selected effort does not match the next lineage escalation.' }] }; return { ...resolved, envelope: { schema: 'routing-envelope/v1', runtime, role: 'implementer', planDigest: report.planDigest, executionDigest: report.executionDigest, sliceId: lineage.sliceId, requestedProfile: lineage.initialProfile, effectiveProfile: next.profile, resolved: resolved.selection, policyDigest: resolved.policyDigest, capabilityDigest: resolved.capabilityDigest, outcome: resolved.outcome, unavailableEvidence: resolved.unavailableEvidence }, custodyHandoff: { kind: 'routing-reserve', obligationId: lineage.obligationId, lineageId: lineage.id } }; })();
+        process.stdout.write(options.json ? `${JSON.stringify(result)}\n` : `Plan routing: ${result.state}\n`);
+        if (result.state === 'blocked')
+            process.exitCode = 2;
+    });
+    plan.command('migration-facts <plan-path>')
+        .description('collect read-only durable migration facts')
+        .option('--cwd <path>')
+        .option('--historical-root <path>', 'admitted sibling #148 worktree')
+        .requiredOption('--issue <https-url...>', 'durable issue links, including #126')
+        .option('--json')
+        .action((planPath, options) => {
+        assertText(planPath, 'plan path');
+        const cwd = options.cwd ?? process.cwd();
+        assertText(cwd, '--cwd');
+        const report = options.historicalRoot ? (0, migration_1.collectIssue148HistoricalFacts)(options.historicalRoot, options.issue) : (deps.collectMigrationFacts ?? migration_1.collectMigrationFacts)(planPath, cwd, options.issue);
+        process.stdout.write(options.json ? `${JSON.stringify(report)}\n` : `Migration facts: ${report.state}\n`);
+        process.exitCode = report.state === 'supported-completion' ? 0 : 2;
+    });
     plan
         .command('validate <plan-path>')
         .description('validate a compact plan without modifying it')
@@ -95,4 +222,52 @@ function registerPlanCommand(program, deps = { validatePlanFile: validate_1.vali
         const code = exitCodeFor(report);
         process.exitCode = code;
     });
+    plan
+        .command('admit <plan-path>')
+        .description('read-only fail-closed compact-plan admission')
+        .requiredOption('--provider <target>', 'target provider')
+        .requiredOption('--cwd <path>', 'repository root for plan containment and source resolution')
+        .option('--execution-mode <mode>', 'explicit override: interactivo or desatendido')
+        .option('--require-current', 'require authoritative consumed-contract currentness')
+        .option('--verify-sensors', 'require an empirical sensor pass')
+        .option('--runtime-kind <kind>', 'routing runtime kind for compact v2')
+        .option('--runtime-version <version>', 'routing runtime version for compact v2')
+        .option('--account-scope-digest <sha>', 'routing account scope digest for compact v2')
+        .option('--json', 'emit one stable JSON report')
+        .action(async (planPath, options) => {
+        assertText(planPath, 'plan path');
+        assertText(options.cwd, '--cwd');
+        assertText(options.provider, '--provider');
+        const admission = deps.admitPlan ?? admission_1.admitPlan;
+        const preferences = deps.readPreferences ?? config_1.readPreferences;
+        const currentnessCheck = deps.checkCurrentness ?? check_1.checkCurrentness;
+        const sensorRun = deps.runSensors ?? run_1.runSensors;
+        const registryInventory = deps.listRegistries ?? registries_1.listRegistries;
+        const planReport = deps.validatePlanFile(planPath, options.cwd);
+        // The mode comes from the same authenticated bytes/digest that produced
+        // planReport. Never reopen the path to parse a mutable header.
+        const executionMode = options.executionMode === undefined
+            ? planReport.state === 'valid' ? (planReport.executionMode ?? 'interactivo') : 'interactivo'
+            : options.executionMode === 'desatendido' ? 'desatendido' : options.executionMode === 'interactivo' ? 'interactivo' : options.executionMode;
+        const journal = executionMode === 'desatendido' ? journalObservation(options.cwd) : {};
+        const normalizedPlanPath = path_1.default.relative(options.cwd, path_1.default.resolve(options.cwd, planPath)).replace(/\\/g, '/');
+        const enabledAgents = preferences().enabledAgents;
+        // The documented order is plan, provider, currentness, sensors, journal,
+        // capabilities. Do not call the full composer early: that would resolve a
+        // capability before empirical evidence gates have had their ordered turn.
+        const earlyBoundary = planReport.state !== 'valid' || !(0, providers_1.isAgentTarget)(options.provider) || !enabledAgents.includes(options.provider);
+        if (earlyBoundary) {
+            const report = await admission({ plan: planReport, provider: options.provider, cwd: options.cwd, enabledAgents, executionMode, planPath: normalizedPlanPath, ...journal });
+            process.stdout.write(admissionOutput(report, options.json === true));
+            process.exitCode = 2;
+            return;
+        }
+        const readRouting = () => { if (!options.runtimeKind || !options.runtimeVersion || !options.accountScopeDigest)
+            return undefined; const runtime = (0, capabilities_1.validateRuntimeKey)({ target: options.provider, kind: options.runtimeKind, version: options.runtimeVersion, accountScopeDigest: options.accountScopeDigest }); const policy = (deps.readEffectivePolicy ?? store_2.readEffectivePolicy)(options.cwd); const at = deps.routingNow?.() ?? new Date(); if (!(at instanceof Date) || !Number.isFinite(at.getTime()))
+            throw new Error('routingNow must return a finite Date'); const capabilities = (deps.readCapabilities ?? capabilities_1.readCapabilities)(runtime, at); return { runtime, policy: policy.state === 'approved' ? policy.policy : undefined, capabilities: capabilities.state === 'current' ? capabilities.receipt : undefined, now: at }; };
+        const report = await (0, registry_contracts_1.admitRegistryPlan)({ plan: planReport, provider: options.provider, cwd: options.cwd, enabledAgents, executionMode, planPath: normalizedPlanPath, ...journal, requireCurrent: options.requireCurrent === true, verifySensors: options.verifySensors === true }, { admitPlan: admission, listRegistries: registryInventory, checkCurrentness: currentnessCheck, runSensors: sensorRun, readRouting });
+        process.stdout.write(admissionOutput(report, options.json === true));
+        if (report.state !== 'admitted')
+            process.exitCode = 2;
+    });
 }