chati-dev 4.5.28 → 4.5.29

package/src/orchestrator/rail-verification.js

@@ -0,0 +1,278 @@
+import { randomUUID } from 'node:crypto';
+import { readFileSync, realpathSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { canonicalSerialize, sha256 } from '@chati/core';
+import { validatePlanningMaterial, validateTaskVerificationPlan, validateTaskBrowserVerificationPlan } from '@chati/planning';
+import { validateBrowserLaunchRequest } from '@chati/browser-capability';
+import { browserEvidenceMaterial, completionMetricsReference, effortJournalDigest, providerProcessingMetric } from '@chati/rail';
+import { delegatedAuthorityPublicIdentity, signDelegatedAuthorityStatement } from '../installer-v2/installation-authority.js';
+import { persistImmutableInstallationFile, readSafeInstallationStorageFile } from '../installer-v2/catalog-client.js';
+import { runIsolatedVerificationCheck } from '../terminal/spawner.js';
+import { verificationProcessCompleted } from '../terminal/verification-process-facts.js';
+import { runIsolatedBrowserObservation } from '../terminal/browser-observer.js';
+import { browserObservationCompleted } from '../terminal/browser-process-facts.js';
+import { assertRailReadOnlyCommitWorkspaceUnchanged, cleanupRailReadOnlyCommitWorkspace, createRailReadOnlyCommitWorkspace } from '../terminal/rail-readonly-workspace.js';
+import { loadRuntimeInstallationV2, resolveRuntimeCouncilGatePolicyV2 } from './runtime-installation-v2.js';
+import { assertCouncilGateApproved } from './council-gate-runtime.js';
+import { assertRailHandoffCouncilBinding, collectRailProviderProcessing, resolveRailAttemptContext } from './rail-runtime.js';
+import { collectRailHumanEffort } from './rail-human-effort.js';
+import { resolveReviewGitSubject } from './review-runtime.js';
+import { signedRailEvidencePayload, verifyRailEvidenceAuthorityCertificate, verifyRailEvidenceReceipt } from './rail-evidence-authority.js';
+import { assertLocalBrowserArtifacts, browserRetentionPolicy, persistBrowserArtifact, pruneBrowserArtifacts } from './browser-artifact-store.js';
+
+function fail(code, message) { throw Object.assign(new Error(message), { code }); }
+function timestamp(clock) {
+  const value = new Date(clock());
+  if (!Number.isFinite(value.getTime())) fail('RAIL_VERIFICATION_TIME_INVALID', 'verification clock must be valid');
+  return value.toISOString();
+}
+
+function loadCertifiedIdentity({ projectDir, artifact, authorityDirectory, clock }) {
+  const source = readSafeInstallationStorageFile(join(projectDir, '.chati/v2/rail/evidence-authority.json'), {
+    allowMissing: true, maxBytes: 32 * 1024, label: 'RAIL evidence certificate',
+  });
+  if (source === null) fail('RAIL_EVIDENCE_AUTHORITY_NOT_CONFIGURED', 'enroll an approved CHATI-signed evidence authority before running local verification');
+  let certificate;
+  try { certificate = JSON.parse(source.content); }
+  catch { fail('INVALID_RAIL_EVIDENCE_CERTIFICATE', 'RAIL evidence certificate is not valid JSON'); }
+  const verifier = verifyRailEvidenceAuthorityCertificate({ certificate,
+    expected_project_id: artifact.project_id,
+    root_public_key: readFileSync(new URL('../installer/signing-public-key.pem', import.meta.url), 'utf8'), clock });
+  const signingOptions = { projectDir, projectId: artifact.project_id, kind: 'rail-evidence', authorityDirectory };
+  const identity = delegatedAuthorityPublicIdentity(signingOptions);
+  if (certificate.issuer_id !== identity.issuer_id || certificate.public_key !== identity.public_key) {
+    fail('RAIL_VERIFICATION_ISSUER_MISMATCH', 'enrolled certificate does not certify this local delegated identity');
+  }
+  return { verifier, identity, signingOptions, certificate_digest: sha256(certificate) };
+}
+
+function canonicalContext(options) {
+  const { projectDir, handoff_id, attempt_id, clock } = options;
+  const artifact = loadRuntimeInstallationV2(projectDir, { clock });
+  if (!artifact) fail('V2_INSTALLATION_REQUIRED', 'local verification requires a verified v2 installation');
+  const context = resolveRailAttemptContext({ projectDir, handoff_id, attempt_id, clock });
+  if (context.handoff.project_id !== artifact.project_id) fail('RAIL_VERIFICATION_PROJECT_MISMATCH', 'handoff belongs to another installation');
+  if (!['active', 'ready_to_merge'].includes(context.state)) fail('RAIL_VERIFICATION_ATTEMPT_INACTIVE', `attempt is ${context.state}`);
+  const material = validatePlanningMaterial(context.handoff, { required: true });
+  const plan = validateTaskVerificationPlan(context.task, { required: true });
+  // Same council gate as RAIL dispatch: a guided (single-provider) installation
+  // must be reconfigured, while an installation whose contract predates the
+  // council policy keeps the dispatch semantics instead of a stricter gate.
+  const council = resolveRuntimeCouncilGatePolicyV2({ artifact, stage: 'execution-design' });
+  if (!council.enabled && council.reason === 'GUIDED_COUNCIL_REQUIRED') {
+    fail('GUIDED_COUNCIL_REQUIRED', 'local verification requires installation reconfiguration with two selected review providers');
+  }
+  const approval = council.enabled
+    ? assertCouncilGateApproved({ projectDir, stage: 'execution-design', artifact,
+      policy: council.policy, handoff: context.handoff, clock })
+    : null;
+  if (approval) assertRailHandoffCouncilBinding({ projectDir, handoff: context.handoff, approval });
+  const subject = resolveReviewGitSubject({ projectDir, attempt_id, clock });
+  const authority = loadCertifiedIdentity({ ...options, artifact });
+  const browser = canonicalBrowserContext(context);
+  const effort = artifact.installation.external_integrations?.clickup === 'required' ? {
+    human: collectRailHumanEffort({ projectDir, attempt_id }),
+    processing: collectRailProviderProcessing({ projectDir, attempt_id, clock }),
+    source_journal_digest: effortJournalDigest(context.records, attempt_id),
+    rework_review_refs: context.records.filter((record) => record.type === 'review_decided'
+      && record.payload.attempt_id === attempt_id && record.payload.decision?.decision === 'normal-rework')
+      .map((record) => record.payload.review_ref),
+  } : null;
+  return { context, plan, material, subject, authority, effort, browser,
+    binding_digest: sha256({ installation: artifact, subject, plan, browser, effort, certificate_digest: authority.certificate_digest }) };
+}
+
+function canonicalBrowserContext(context) {
+  if (!context.task.requires_browser) return null;
+  const plan = validateTaskBrowserVerificationPlan(context.task, { required: true });
+  const policy = context.task.browser_policy;
+  browserRetentionPolicy(policy.artifact_policy.retention_class);
+  const manifest = [...context.records].reverse().find((record) => record.type === 'execution_dispatched'
+    && record.payload.attempt_id === context.attempt.attempt_id && record.payload.run_kind === 'initial'
+    && record.payload.browser_manifest)?.payload.browser_manifest;
+  const core = { ...manifest }; delete core.manifest_hash;
+  if (!manifest || manifest.manifest_type !== 'BrowserDelegationManifest' || manifest.schema_version !== 1
+    || manifest.evidence_class !== 'delegation-only' || manifest.manifest_hash !== sha256(core)
+    || manifest.delegation?.status !== 'delegated' || manifest.delegation?.evidence_status !== 'required'
+    || manifest.task_id !== context.task.task_id || manifest.policy_ref !== policy.policy_id
+    || manifest.mode !== policy.mode || manifest.tool !== policy.tool || manifest.profile_isolation !== policy.profile_isolation
+    || manifest.allowed_domain !== plan.observation.hostname || manifest.action_confirmation !== policy.action_confirmation
+    || sha256(manifest.artifact_policy) !== sha256(policy.artifact_policy)) {
+    fail('BROWSER_VERIFICATION_DELEGATION_INVALID', 'real observation requires the exact canonical delegation, approved tool policy and local scenario hostname');
+  }
+  validateBrowserLaunchRequest({ browser_session_id: manifest.browser_session_id, task_id: manifest.task_id,
+    url: `http://${manifest.allowed_domain}:${plan.observation.application.port}${plan.observation.steps[0].path}`,
+    classification: manifest.classification, ...(manifest.tenant_ref ? { tenant_ref: manifest.tenant_ref } : {}),
+    ...(manifest.action_confirmation_ref ? { action_confirmation_ref: manifest.action_confirmation_ref } : {}) }, policy);
+  return { plan, policy, manifest };
+}
+
+function persistReport(projectDir, record) {
+  const digest = sha256(record);
+  const report_path = `.chati/v2/rail/verifications/${digest}.json`;
+  persistImmutableInstallationFile(join(projectDir, report_path), `${canonicalSerialize(record)}\n`, {
+    label: 'immutable RAIL verification report', conflictCode: 'RAIL_VERIFICATION_REPORT_CONFLICT',
+  });
+  return { report_path, report_ref: `rail-verification://sha256/${digest}` };
+}
+
+/** Canonical observer: no caller-selected command, commit, result or verdict. */
+export async function observeRailVerification(input = {}) {
+  const allowed = ['projectDir', 'handoff_id', 'attempt_id', 'authorityDirectory', 'clock'];
+  if (!input || typeof input !== 'object' || Array.isArray(input)
+    || Object.keys(input).some((key) => !allowed.includes(key))
+    || ['projectDir', 'handoff_id', 'attempt_id'].some((key) => typeof input[key] !== 'string' || !input[key].trim())
+    || (input.clock !== undefined && typeof input.clock !== 'function')) {
+    fail('RAIL_VERIFICATION_INPUT_INVALID', 'verification accepts only the project, canonical handoff and attempt identifiers');
+  }
+  const options = { ...input, projectDir: resolve(input.projectDir), clock: input.clock ?? (() => new Date()) };
+  const initial = canonicalContext(options);
+  const scripts = new Map(initial.material.artifacts.map((entry) => [entry.ref, entry.content]));
+  const run_id = `verification-${randomUUID()}`;
+  const started_at = timestamp(options.clock);
+  const checks = [];
+  if (initial.browser) {
+    const cleanup = pruneBrowserArtifacts({ projectDir: options.projectDir, projectId: initial.context.handoff.project_id, clock: options.clock });
+    if (!cleanup.ok) fail('BROWSER_ARTIFACT_PRUNE_FAILED', `browser store has unresolved collection failures: ${cleanup.failures.map((item) => item.code).join(', ')}`);
+  }
+  for (const check of initial.plan.checks) {
+    let workspace;
+    let observed;
+    let errorCode = null;
+    let completionProven = false;
+    try {
+      workspace = createRailReadOnlyCommitWorkspace({ projectDir: options.projectDir,
+        baseCommitRef: initial.subject.base_commit_ref, resultCommitRef: initial.subject.result_commit_ref,
+        verificationSubject: true });
+      assertRailReadOnlyCommitWorkspaceUnchanged({ workspace, label: 'verification pre-spawn' });
+      observed = await runIsolatedVerificationCheck({ workingDir: workspace.subject_dir,
+        executableBinding: check.executable_binding, args: check.args,
+        stdin: scripts.get(check.stdin_ref), timeoutMs: check.timeout_ms, subjectReadOnly: true });
+      completionProven = verificationProcessCompleted(observed, { workingDir: workspace.subject_dir,
+        executableBinding: check.executable_binding, args: check.args, stdin: scripts.get(check.stdin_ref) });
+    } catch (error) { errorCode = error.code || 'RAIL_VERIFICATION_CHECK_FAILED'; }
+    finally {
+      if (workspace && process.platform !== 'darwin') {
+        try { cleanupRailReadOnlyCommitWorkspace(workspace); }
+        catch (error) { errorCode ??= error.code || 'RAIL_VERIFICATION_CLEANUP_FAILED'; }
+      }
+    }
+    const passed = !errorCode && observed?.exit_code === 0 && observed.signal === null
+      && observed.timed_out === false && observed.output_limit_exceeded === false
+      && observed.input_error === null && observed.subject_read_only === true && completionProven;
+    // Base64 preserves exact bounded output bytes without JSON control-character
+    // expansion or UTF-8 replacement changing the stored content's digest.
+    const facts = Object.fromEntries(Object.entries(observed ?? {}).filter(([key]) => !['stdout', 'stderr'].includes(key)));
+    const record = { schema_version: 1, evidence_class: 'local-isolated-verification-check', run_id,
+      execution_subject: initial.subject, check, observed_at: timestamp(options.clock), passed, error_code: errorCode, facts };
+    const persisted = persistReport(options.projectDir, record);
+    checks.push({ check_id: check.check_id, kind: check.kind, criterion_refs: check.criterion_refs,
+      passed, exit_code: observed?.exit_code ?? null, error_code: errorCode, ...persisted });
+  }
+  let browserCheck = null;
+  if (initial.browser) {
+    let workspace; let observed; let errorCode = null; let completionProven = false;
+    const frozen = initial.browser.plan.observation;
+    const { stdin_ref, ...application } = frozen.application;
+    try {
+      workspace = createRailReadOnlyCommitWorkspace({ projectDir: options.projectDir,
+        baseCommitRef: initial.subject.base_commit_ref, resultCommitRef: initial.subject.result_commit_ref, verificationSubject: true });
+      assertRailReadOnlyCommitWorkspaceUnchanged({ workspace, label: 'browser verification pre-spawn' });
+      const observation = { workingDir: realpathSync(workspace.subject_dir), ...frozen,
+        application: { ...application, stdin: scripts.get(stdin_ref) } };
+      observed = await runIsolatedBrowserObservation(observation);
+      completionProven = browserObservationCompleted(observed, observation);
+    } catch (error) { errorCode = error.code || 'BROWSER_VERIFICATION_FAILED'; }
+    finally {
+      if (workspace && process.platform !== 'darwin') {
+        try { cleanupRailReadOnlyCommitWorkspace(workspace); }
+        catch (error) { errorCode ??= error.code || 'BROWSER_VERIFICATION_CLEANUP_FAILED'; }
+      }
+    }
+    const captured_at = timestamp(options.clock);
+    const passed = !errorCode && observed?.passed === true && observed.tool === initial.browser.plan.tool_id
+      && completionProven;
+    const artifacts = [];
+    if (passed) {
+      for (const artifact of observed.artifacts) artifacts.push(persistBrowserArtifact({ projectDir: options.projectDir,
+        projectId: initial.context.handoff.project_id, run_id, attempt_id: options.attempt_id,
+        commit_ref: initial.subject.result_commit_ref, policy_ref: initial.browser.policy.policy_id,
+        browser_session_id: initial.browser.manifest.browser_session_id, artifact,
+        retention_class: initial.browser.policy.artifact_policy.retention_class, captured_at, clock: options.clock }));
+      if (artifacts.length === 0) fail('REAL_BROWSER_ARTIFACT_REQUIRED', 'successful observation did not produce a retained browser artifact');
+    }
+    // Raw/redacted content has one managed retention owner only. Permanent
+    // reports and receipts carry descriptors, hashes and process facts, not copies.
+    const facts = Object.fromEntries(Object.entries(observed ?? {}).filter(([key]) => key !== 'artifacts'));
+    browserCheck = { passed, error_code: errorCode || observed?.error_code || null, observed_at: captured_at,
+      artifacts, ...persistReport(options.projectDir, { schema_version: 1, evidence_class: 'local-isolated-browser-verification',
+        run_id, execution_subject: initial.subject, plan_digest: sha256(initial.browser.plan), captured_at, passed,
+        error_code: errorCode || observed?.error_code || null, artifacts, facts }) };
+  }
+  const current = canonicalContext(options);
+  if (current.binding_digest !== initial.binding_digest) fail('RAIL_VERIFICATION_SUBJECT_CHANGED', 'canonical result, verification plan or certification changed during observation');
+  const ok = checks.length === initial.plan.checks.length && checks.every((check) => check.passed) && (!browserCheck || browserCheck.passed);
+  const observed_at = timestamp(options.clock);
+  let evidence = null;
+  if (ok) {
+    const receipt = (kind, material, receiptObservedAt = observed_at) => {
+      const unsigned = signedRailEvidencePayload({ authority_kind: kind, issuer_id: current.authority.identity.issuer_id,
+        project_id: current.context.handoff.project_id, attempt_id: options.attempt_id,
+        commit_ref: current.subject.result_commit_ref, verdict: 'passed', evidence_digest: sha256(material), observed_at: receiptObservedAt });
+      const proof = signDelegatedAuthorityStatement(unsigned, current.authority.signingOptions);
+      const signed = { ...unsigned, signature: proof.signature };
+      if (proof.issuer_id !== unsigned.issuer_id || !verifyRailEvidenceReceipt(current.authority.verifier, signed, unsigned, options.clock)) {
+        fail('RAIL_VERIFICATION_SIGNATURE_INVALID', 'observed receipt does not validate against the enrolled authority');
+      }
+      return signed;
+    };
+    const ciRefs = checks.filter((check) => check.kind === 'ci').map((check) => check.report_ref);
+    const acceptanceRefs = checks.filter((check) => check.kind === 'acceptance').map((check) => check.report_ref);
+    let browserEvidence;
+    if (browserCheck) {
+      const delegation = current.browser.manifest;
+      assertLocalBrowserArtifacts({ projectDir: options.projectDir, projectId: current.context.handoff.project_id,
+        artifacts: browserCheck.artifacts, clock: options.clock, expected: { attempt_id: options.attempt_id,
+          commit_ref: current.subject.result_commit_ref, policy_ref: delegation.policy_ref,
+          browser_session_id: delegation.browser_session_id, captured_at: browserCheck.observed_at } });
+      const material = browserEvidenceMaterial({ schema_version: 1, manifest_type: 'BrowserRuntimeEvidenceManifest',
+        evidence_class: 'real-browser', browser_session_id: delegation.browser_session_id, task_id: current.context.task.task_id,
+        policy_ref: delegation.policy_ref, tool: delegation.tool, allowed_domain: delegation.allowed_domain,
+        classification: delegation.classification, commit_ref: current.subject.result_commit_ref,
+        delegation_manifest_hash: delegation.manifest_hash, observed_at: browserCheck.observed_at, artifacts: browserCheck.artifacts,
+        ...(delegation.tenant_ref ? { tenant_ref: delegation.tenant_ref } : {}) });
+      browserEvidence = { ...material, evidence_ref: `browser-evidence://sha256/${sha256(material)}`,
+        authority_receipt: receipt('rail_browser', material, browserCheck.observed_at) };
+      acceptanceRefs.push(browserCheck.report_ref, ...browserCheck.artifacts.map((artifact) => artifact.sanitized_ref), browserEvidence.evidence_ref);
+    }
+    let metrics;
+    if (current.effort) {
+      const metric = (source) => {
+        const persisted = persistReport(options.projectDir, { ...source, run_id,
+          execution_subject: current.subject, observed_at });
+        acceptanceRefs.push(persisted.report_ref);
+        return source.evidence_class === 'observed-provider-invocation-wall-time'
+          ? providerProcessingMetric(source, persisted.report_ref)
+          : { unit: 'minutes', value: source.value / 60000, evidence_ref: persisted.report_ref };
+      };
+      metrics = { actual_human_effort: metric(current.effort.human),
+        actual_ai_processing: metric(current.effort.processing),
+        source_journal_digest: current.effort.source_journal_digest,
+        rework_cycles: current.effort.rework_review_refs.length,
+        rework_review_refs: current.effort.rework_review_refs };
+      acceptanceRefs.push(completionMetricsReference({ attempt_id: options.attempt_id,
+        commit_ref: current.subject.result_commit_ref, metrics }));
+    }
+    evidence = {
+      ci: { verdict: 'passed', commit_ref: current.subject.result_commit_ref, evidence_refs: ciRefs, authority_receipt: receipt('rail_ci', ciRefs) },
+      acceptance_evidence_refs: acceptanceRefs, acceptance_authority_receipt: receipt('rail_acceptance', acceptanceRefs),
+      ...(metrics ? { metrics } : {}),
+      ...(browserEvidence ? { browser_evidence: browserEvidence } : {}),
+    };
+  }
+  const report = { schema_version: 1, evidence_class: 'local-isolated-verification', run_id, started_at, observed_at,
+    execution_subject: initial.subject, binding_digest: initial.binding_digest, checks, browser: browserCheck, ok, evidence };
+  const persisted = persistReport(options.projectDir, report);
+  return Object.freeze({ ok, action: 'rail_verification_observed', run_id,
+    execution_subject: initial.subject, checks, browser: browserCheck, evidence, ...persisted });
+}

package/src/orchestrator/review-runtime.js

@@ -3,7 +3,8 @@ import { realpathSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { acceptReview, decideReviewProgress } from '@chati/review-council';
 import { sha256 } from '@chati/core';
-import { loadRuntimeInstallationV2 } from './runtime-installation-v2.js';
+import { attemptExecutionBase } from '@chati/rail';
+import { assertRuntimeTaskReviewBindingV2, loadRuntimeInstallationV2 } from './runtime-installation-v2.js';
 import {
   createProjectRailEngine, loadLatestRailExecutionEvidence, loadRailHandoff, resolveRailAttemptContext,
 } from './rail-runtime.js';
@@ -13,6 +14,36 @@ import { assertRailReadOnlyCommitWorkspaceUnchanged } from '../terminal/rail-rea
 
 function fail(code, message) { const error = new Error(message); error.code = code; throw error; }
 
+function assertSealedTaskReviewInvocation({ artifact, task, invocation, clock }) {
+  if (!task?.review_binding) return;
+  const expected = assertRuntimeTaskReviewBindingV2({
+    artifact,
+    review_binding: task.review_binding,
+    builder_identity: {
+      provider_id: task.execution_binding.provider_id,
+      model_id: task.execution_binding.model_id,
+    },
+    ...(clock === undefined ? {} : { clock }),
+  });
+  const actual = {
+    provider_id: invocation?.provider_id,
+    harness_id: invocation?.harness_id,
+    model_id: invocation?.model_pin?.model_id,
+    reasoning_configuration: invocation?.model_pin?.reasoning_configuration,
+    catalog_snapshot_ref: invocation?.model_pin?.catalog_snapshot_ref,
+  };
+  const required = {
+    provider_id: expected.provider_id,
+    harness_id: expected.harness_id,
+    model_id: expected.model_pin.model_id,
+    reasoning_configuration: expected.model_pin.reasoning_configuration,
+    catalog_snapshot_ref: expected.model_pin.catalog_snapshot_ref,
+  };
+  if (Object.entries(required).some(([field, value]) => actual[field] !== value)) {
+    fail('RAIL_REVIEW_ROUTE_MISMATCH', 'review invocation does not match the sealed task review binding');
+  }
+}
+
 function trustedGitEnvironment(source = process.env) {
   const environment = Object.fromEntries(Object.entries(source).filter(([key]) => !key.startsWith('GIT_')));
   return {
@@ -80,6 +111,7 @@ export function recordRailReviewDispatch({
   })) fail('UNTRUSTED_REVIEW_LAUNCH', 'review dispatch requires a terminal-authority launch receipt');
   const artifact = loadRuntimeInstallationV2(projectDir, { ...(clock === undefined ? {} : { clock }) });
   if (!artifact) fail('V2_INSTALLATION_REQUIRED', 'RAIL review dispatch requires a v2 installation');
+  assertSealedTaskReviewInvocation({ artifact, task: context.task, invocation, clock });
   return engine.recordReviewDispatch({
       attempt_id, invocation, launch_receipt,
       installation: artifact.installation, snapshot: artifact.capability_snapshot,
@@ -104,7 +136,7 @@ function resolveAttemptLineage(projectDir, attemptId, clock) {
     handoff_id: handoff.handoff_id,
     handoff_manifest_digest: handoff.seal.manifest_digest,
     task_id: attempt.task_id,
-    base_commit_ref: attempt.git_commit_ref,
+    base_commit_ref: attemptExecutionBase(attempt),
   });
 }
 
@@ -181,6 +213,9 @@ export function recordRailReview({
   }
   const artifact = loadRuntimeInstallationV2(projectDir, { clock });
   if (!artifact) fail('V2_INSTALLATION_REQUIRED', 'RAIL review requires a v2 installation');
+  const reviewLineage = resolveAttemptLineage(projectDir, review?.attempt_id, clock);
+  const reviewContext = resolveRailAttemptContext({ projectDir, handoff_id: reviewLineage.handoff_id, attempt_id: review?.attempt_id, clock });
+  assertSealedTaskReviewInvocation({ artifact, task: reviewContext.task, invocation, clock });
   const validated = acceptReview({ review, invocation, installation: artifact.installation, snapshot: artifact.capability_snapshot, clock });
   const baseLineage = resolveAttemptLineage(projectDir, validated.attempt_id, clock);
   const engine = createProjectRailEngine({ projectDir, clock });

package/src/orchestrator/runtime-installation-v2.js

@@ -2,7 +2,7 @@ import { doctorV2 } from '../installer-v2/index.js';
 import { existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { assertEligibleInvocation } from '@chati/provider-registry';
-import { selectCanonicalReviewer } from '@chati/review-council';
+import { selectCanonicalReviewer, selectCouncilReviewers } from '@chati/review-council';
 import {
   readInstallationArtifactFile, verifyInstallationCatalogProvenance,
 } from '../installer-v2/catalog-client.js';
@@ -19,33 +19,36 @@ export const V2_PLANNING_AGENTS = Object.freeze([
   'detail', 'architect', 'ux', 'qa-planning', 'phases', 'tasks',
 ]);
 
-const V2_PLANNING_PREDECESSORS = Object.freeze({
-  brief: Object.freeze(['work-understanding']),
-  detail: Object.freeze(['work-understanding', 'brief']),
-  architect: Object.freeze(['work-understanding', 'brief']),
-  ux: Object.freeze(['work-understanding', 'brief']),
-  'qa-planning': Object.freeze(['work-understanding', 'brief', 'detail', 'architect', 'ux']),
-  phases: Object.freeze(['work-understanding', 'brief', 'detail', 'architect', 'ux', 'qa-planning']),
-  tasks: Object.freeze(['work-understanding', 'brief', 'detail', 'architect', 'ux', 'qa-planning', 'phases']),
-});
+const COUNCIL_GATE_STAGES = new Set(['discovery', 'planning', 'execution-design']);
 
-export function assertV2PlanningPredecessors(session, agent) {
-  const projectType = session?.project_type || session?.project?.type || 'greenfield';
-  const required = (V2_PLANNING_PREDECESSORS[agent] || []).map((name) =>
-    name === 'work-understanding' ? (projectType === 'brownfield' ? 'brownfield-wu' : 'greenfield-wu') : name
-  );
-  const incomplete = required.filter((name) =>
-    session?.agents?.[name]?.status !== 'completed' || !session?.completed_agents?.includes(name)
-  );
-  if (incomplete.length > 0) {
-    const error = new Error(`Agent ${agent} cannot advance before its canonical predecessors complete: ${incomplete.join(', ')}`);
-    error.code = 'V2_PLANNING_PREDECESSORS_INCOMPLETE';
-    error.incomplete = incomplete;
+/**
+ * Returns the installation-owned council contract for one stage. Artifacts
+ * created before this policy existed deliberately remain non-disruptive until
+ * their owner explicitly reconfigures the installation.
+ */
+export function resolveRuntimeCouncilGatePolicyV2({ artifact, stage } = {}) {
+  if (!COUNCIL_GATE_STAGES.has(stage)) {
+    const error = new Error(`Unknown council stage: ${stage}`);
+    error.code = 'COUNCIL_GATE_STAGE_INVALID';
     throw error;
   }
-  return Object.freeze({ valid: true, required: Object.freeze(required) });
+  const policy = artifact?.installation?.quality_council;
+  if (!policy || policy.mode !== 'autonomous' || !policy.stages?.includes(stage)) {
+    return Object.freeze({ enabled: false, reason: policy?.mode === 'guided' ? 'GUIDED_COUNCIL_REQUIRED' : 'COUNCIL_POLICY_NOT_CONFIGURED' });
+  }
+  return Object.freeze({
+    enabled: true,
+    policy: Object.freeze({
+      min_members: policy.min_members,
+      max_members: policy.max_members,
+      require_distinct_providers: policy.require_distinct_providers,
+      blocking_severities: [...policy.blocking_severities],
+    }),
+  });
 }
 
+export { assertV2PlanningPredecessors } from './agent-selector.js';
+
 const RAIL_ACTIONS = new Set(['build', 'review']);
 const REASONING_CONFIGURATIONS = Object.freeze(['low', 'medium', 'high', 'xhigh', 'max']);
 
@@ -169,6 +172,15 @@ export function resolveRuntimeExecutableBindingV2({ artifact, provider_id, harne
   });
 }
 
+function routingPriority(model, routingKey, action) {
+  const keys = Array.isArray(routingKey) ? routingKey : [routingKey];
+  for (const key of keys) {
+    const priority = model.routing_priority?.[key];
+    if (priority !== undefined) return priority;
+  }
+  return model.routing_priority?.[action] ?? 0;
+}
+
 function resolveRuntimeActionV2({ artifact, action, routingKey, binding, model_id, reasoning_configuration, clock = () => new Date() }) {
   let hasEligibleModel = false;
   const candidates = artifact.installation.enabled_providers.flatMap((candidateBinding) => {
@@ -193,7 +205,7 @@ function resolveRuntimeActionV2({ artifact, action, routingKey, binding, model_i
         binding: candidateBinding,
         model: catalogModel,
         reasoning,
-        priority: catalogModel.routing_priority?.[routingKey] ?? catalogModel.routing_priority?.[action] ?? 0,
+        priority: routingPriority(catalogModel, routingKey, action),
       }];
     });
   }).sort((left, right) =>
@@ -241,6 +253,93 @@ export function resolveRuntimeRailInvocationV2({ artifact, action = 'build', bin
   return resolveRuntimeActionV2({ artifact, action, routingKey: `rail:${action}`, binding, model_id, reasoning_configuration, clock });
 }
 
+const TASK_RISK_LEVELS = new Set(['low', 'medium', 'high', 'critical']);
+
+function normalizeTaskRoutingProfile(profile = {}) {
+  if (!profile || typeof profile !== 'object' || Array.isArray(profile) || !TASK_RISK_LEVELS.has(profile.risk_level)) {
+    const error = new Error('task routing_profile.risk_level must be low, medium, high or critical');
+    error.code = 'TASK_ROUTING_PROFILE_REQUIRED';
+    throw error;
+  }
+  return Object.freeze({ risk_level: profile.risk_level });
+}
+
+/**
+ * Selects the exact build and independent-review bindings at planning seal
+ * time. The model catalog owns the priorities, so an updated signed catalog
+ * can change the route without embedding personal ETCAR weights in CHATI.
+ */
+export function resolveRuntimeTaskRouteV2({ artifact, routing_profile, required_independence_level = 'A', clock = () => new Date() } = {}) {
+  if (!['A', 'B', 'C'].includes(required_independence_level)) {
+    const error = new Error('required_independence_level must be A, B or C');
+    error.code = 'TASK_ROUTING_PROFILE_INVALID';
+    throw error;
+  }
+  const profile = normalizeTaskRoutingProfile(routing_profile);
+  const execution = resolveRuntimeActionV2({
+    artifact,
+    action: 'build',
+    routingKey: [`task:build:${profile.risk_level}`, 'task:build', 'rail:build'],
+    clock,
+  });
+  const builder_identity = { provider_id: execution.provider_id, model_id: execution.model_pin.model_id };
+  const selectedReview = resolveRuntimeRailReviewerV2({ artifact, builder_identity, clock });
+  const attained = selectedReview.independence_level;
+  const strength = { A: 3, B: 2, C: 1 };
+  if (strength[attained] < strength[required_independence_level]) {
+    const error = new Error(`task requires independence ${required_independence_level}, but the selected catalog route attains ${attained}`);
+    error.code = 'TASK_REVIEW_INDEPENDENCE_UNAVAILABLE';
+    throw error;
+  }
+  return Object.freeze({
+    routing_profile: profile,
+    execution_binding: Object.freeze({
+      provider_id: execution.provider_id,
+      harness_id: execution.harness_id,
+      model_id: execution.model_pin.model_id,
+      reasoning_configuration: execution.model_pin.reasoning_configuration,
+    }),
+    review_binding: Object.freeze({
+      provider_id: selectedReview.provider_id,
+      harness_id: selectedReview.harness_id,
+      model_id: selectedReview.model_pin.model_id,
+      reasoning_configuration: selectedReview.model_pin.reasoning_configuration,
+      attained_independence_level: attained,
+    }),
+  });
+}
+
+/** Validates a sealed task review binding without allowing a runtime reroute. */
+export function assertRuntimeTaskReviewBindingV2({ artifact, review_binding, builder_identity, clock = () => new Date() } = {}) {
+  if (!review_binding || typeof review_binding !== 'object' || Array.isArray(review_binding)) {
+    const error = new Error('sealed task review binding is required');
+    error.code = 'TASK_REVIEW_BINDING_REQUIRED';
+    throw error;
+  }
+  const invocation = {
+    provider_id: review_binding.provider_id,
+    harness_id: review_binding.harness_id,
+    action: 'review',
+    model_pin: {
+      model_id: review_binding.model_id,
+      catalog_snapshot_ref: artifact.capability_snapshot.snapshot_id,
+      reasoning_configuration: review_binding.reasoning_configuration,
+    },
+  };
+  assertEligibleInvocation({ installation: artifact.installation, snapshot: artifact.capability_snapshot, invocation, clock });
+  const reviewer_identity = { provider_id: invocation.provider_id, model_id: invocation.model_pin.model_id };
+  const independence_level = builder_identity
+    ? (builder_identity.provider_id !== reviewer_identity.provider_id ? 'A'
+      : builder_identity.model_id !== reviewer_identity.model_id ? 'B' : 'C')
+    : null;
+  if (review_binding.attained_independence_level !== undefined && review_binding.attained_independence_level !== independence_level) {
+    const error = new Error('sealed task review binding independence level drifted');
+    error.code = 'TASK_REVIEW_BINDING_DRIFT';
+    throw error;
+  }
+  return Object.freeze({ ...invocation, reviewer_identity, independence_level });
+}
+
 /** Selects the highest-ranked installed reviewer at the strongest available independence level. */
 export function resolveRuntimeRailReviewerV2({ artifact, builder_identity, clock = () => new Date() }) {
   return selectCanonicalReviewer({
@@ -251,6 +350,26 @@ export function resolveRuntimeRailReviewerV2({ artifact, builder_identity, clock
   });
 }
 
+/**
+ * Resolves the planning-quality council from the providers the user selected
+ * during installation. The council is two or three distinct providers, never
+ * a hidden provider fallback and never a hard-coded vendor trio.
+ */
+export function resolveRuntimeCouncilInvocationsV2({
+  artifact,
+  builder_identity,
+  policy,
+  clock = () => new Date(),
+} = {}) {
+  return selectCouncilReviewers({
+    installation: artifact.installation,
+    snapshot: artifact.capability_snapshot,
+    builder_identity,
+    ...(policy ? { policy } : {}),
+    clock,
+  });
+}
+
 export function resolveRuntimeAdjudicationV2({ artifact, clock = () => new Date() }) {
   const candidates = artifact.installation.enabled_providers.flatMap((binding) =>
     binding.allowed_models.flatMap((modelId) => {