chati-dev 4.5.28 → 4.5.29

package/src/installer-v2/index.js

@@ -3,19 +3,23 @@
  *
  * It creates one provider-neutral installation artifact, inspects a target for
  * legacy v1 markers, and returns a migration/rollback plan. Artifact writes
- * are explicit through installV2 or authorized migrateV2. It never invokes a
- * provider CLI or reads credentials.
+ * are explicit through installV2 or authorized migrateV2. Internal writes
+ * require the existing machine-license entitlement check. It never invokes a
+ * provider CLI or reads provider credentials.
  */
 import { existsSync } from 'node:fs';
 import { join, relative, resolve, sep } from 'node:path';
 import { canonicalize, canonicalSerialize, sha256, ContractError } from '@chati/core';
 import { validateInstallation } from '@chati/provider-registry';
+import { selectCouncilReviewers } from '@chati/review-council';
 import {
   persistImmutableInstallationFile, readSafeInstallationStorageFile,
   replaceInstallationStorageFile, verifyInstallationCatalogProvenance,
 } from './catalog-client.js';
 import { authorizeInstallationArtifact } from './installation-authority.js';
 import { validateProviderExecutableBinding } from './provider-executable.js';
+import { requireLicenseEntitlement } from '../license/client.js';
+import { withUpgradeMaintenance } from '../upgrade/maintenance.js';
 
 export const INSTALLATION_SCHEMA_VERSION = 2;
 export const INSTALLATION_ARTIFACT_PATH = '.chati/v2/installation.json';
@@ -56,10 +60,20 @@ const ARTIFACT_KEYS = new Set([
 ]);
 const INSTALLATION_KEYS = new Set([
   'installation_id', 'profile', 'enabled_providers', 'capability_snapshot_ref',
+  'quality_council',
   // Read-only compatibility for early v2 artifacts. Current installers never
   // emit these fields and runtime routing does not consume them.
   'policy_ref', 'primary_binding', 'primary_harness', 'external_integrations',
 ]);
+const QUALITY_COUNCIL_KEYS = new Set([
+  'mode', 'stages', 'min_members', 'max_members',
+  'require_distinct_providers', 'blocking_severities',
+]);
+const QUALITY_COUNCIL_STAGES = new Set(['discovery', 'planning', 'execution-design']);
+// Artifacts created before this contract was introduced can still be loaded
+// read-only.  A current installer must never mint one: a caller-controlled
+// clock is useful for deterministic artifacts, but is not evidence that an
+// artifact really predates this security contract.
 const BINDING_KEYS = new Set([
   'provider_id', 'harness_id', 'allowed_models', 'allowed_reasoning_configurations',
   'executable_path', 'executable_sha256', 'supporting_executables',
@@ -73,6 +87,9 @@ const MODEL_KEYS = new Set([
 function assertClosedArtifactSchema(artifact) {
   assertExactKeys(artifact, ARTIFACT_KEYS, 'artifact');
   assertExactKeys(artifact.installation, INSTALLATION_KEYS, 'installation');
+  if (artifact.installation.quality_council !== undefined) {
+    assertExactKeys(artifact.installation.quality_council, QUALITY_COUNCIL_KEYS, 'quality council policy');
+  }
   for (const binding of artifact.installation.enabled_providers ?? []) {
     assertExactKeys(binding, BINDING_KEYS, 'enabled provider binding');
   }
@@ -92,6 +109,44 @@ function assertClosedArtifactSchema(artifact) {
   assertExactKeys(artifact.brain_read_capability, brainKeys, 'brain_read_capability');
 }
 
+function validateQualityCouncilConfiguration(configuration, { allowVerifiedLegacyArtifact = false } = {}) {
+  if (configuration === undefined) {
+    // Published releases up to 4.5.28 wrote v2 artifacts without a council
+    // policy whatever their date. Read paths (doctor, upgrade, runtime load)
+    // keep those verified artifacts inspectable and runnable; the runtime
+    // then reports COUNCIL_POLICY_NOT_CONFIGURED. Every creation and
+    // authorization path stays unconditional, so a new artifact can never
+    // omit the policy.
+    if (allowVerifiedLegacyArtifact) return;
+    throw new ContractError(
+      'QUALITY_COUNCIL_REQUIRED',
+      'current v2 installations require a complete quality_council policy; only verified pre-existing artifacts may omit it',
+    );
+  }
+  assertExactKeys(configuration, QUALITY_COUNCIL_KEYS, 'quality council policy');
+  if (!['autonomous', 'guided'].includes(configuration.mode)) {
+    throw new ContractError('INVALID_COUNCIL_POLICY', 'quality_council.mode must be autonomous or guided');
+  }
+  if (!Array.isArray(configuration.stages) || configuration.stages.length !== QUALITY_COUNCIL_STAGES.size
+    || !configuration.stages.every((stage) => QUALITY_COUNCIL_STAGES.has(stage))
+    || new Set(configuration.stages).size !== QUALITY_COUNCIL_STAGES.size) {
+    throw new ContractError('INVALID_COUNCIL_POLICY', 'quality_council.stages must contain exactly discovery, planning and execution-design');
+  }
+  if (!Number.isInteger(configuration.min_members) || configuration.min_members < 2
+    || !Number.isInteger(configuration.max_members) || configuration.max_members < configuration.min_members
+    || configuration.max_members > 3) {
+    throw new ContractError('INVALID_COUNCIL_POLICY', 'quality_council member bounds must be between 2 and 3');
+  }
+  if (configuration.require_distinct_providers !== true) {
+    throw new ContractError('INVALID_COUNCIL_POLICY', 'quality_council requires distinct providers');
+  }
+  if (!Array.isArray(configuration.blocking_severities) || configuration.blocking_severities.length !== 2
+    || !configuration.blocking_severities.every((severity) => ['critical', 'high'].includes(severity))
+    || new Set(configuration.blocking_severities).size !== 2) {
+    throw new ContractError('INVALID_COUNCIL_POLICY', 'quality_council blocking severities must contain exactly critical and high');
+  }
+}
+
 function readClock(clock) {
   if (typeof clock !== 'function') throw new ContractError('MISSING_CLOCK', 'a deterministic clock function is required');
   const result = clock();
@@ -147,6 +202,10 @@ function artifactCore(input, createdAt) {
   assertObject(input.capability_snapshot, 'INVALID_CATALOG', 'capability_snapshot');
   assertString(input.project_id, 'INVALID_INSTALLATION', 'project_id');
   validateInstallationExecutableBindings(input.installation);
+  // This is the creation boundary.  Never derive a legacy exception from the
+  // supplied clock here, because install/reconfigure subsequently authorizes
+  // this exact artifact on the local host.
+  validateQualityCouncilConfiguration(input.installation.quality_council);
   const installation = validateInstallation(input.installation, input.capability_snapshot, { clock: () => createdAt });
   const brain_read_capability = normalizeBrainReadCapability(input.brain_read_capability);
   const managed_paths = (input.managed_paths ?? [INSTALLATION_ARTIFACT_PATH]).map(ensureRelativePath);
@@ -212,6 +271,10 @@ export function doctorV2(artifact, { clock = () => new Date() } = {}) {
     assertString(installation_artifact_id, 'INVALID_ARTIFACT', 'installation_artifact_id');
     if (sha256(core) !== digest) throw new ContractError('INSTALLATION_ARTIFACT_DRIFT', 'installation artifact digest does not match its content');
     validateInstallation(artifact.installation, artifact.capability_snapshot, { clock: () => readClock(clock) });
+    // The runtime additionally requires a valid pre-existing host receipt.
+    // doctor itself is read-only and therefore keeps old on-disk artifacts
+    // inspectable, while every current creation path above is unconditional.
+    validateQualityCouncilConfiguration(artifact.installation.quality_council, { allowVerifiedLegacyArtifact: true });
     validateInstallationExecutableBindings(artifact.installation);
     if (artifact.capability_snapshot.snapshot_id.startsWith('wizard-catalog-')
       && !artifact.capability_snapshot.source_catalog_ref) {
@@ -296,15 +359,61 @@ export function dryRunV2(input, { projectDir, clock = () => new Date(), exists =
     .map(({ provider_id, harness_id }) => ({ code: 'V1_BINDING_NOT_SELECTED', provider_id, harness_id, message: 'legacy marker is not a selected v2 binding' }));
   const pathOutsideProject = artifact.managed_paths.some((managedPath) => relative(resolve(projectDir), resolve(projectDir, managedPath)).split(sep).includes('..'));
   if (pathOutsideProject) throw new ContractError('INVALID_MANAGED_PATH', 'managed path resolves outside project');
-  return Object.freeze(canonicalize({ schema_version: 1, mode: 'dry-run', writes_performed: false, artifact, doctor, detector, backup_plan, rollback_plan, incompatibilities }));
+  let council_readiness;
+  try {
+    const selection = assertExecutableV2Installation(artifact, { clock });
+    council_readiness = { ready: true, council_member_count: selection.member_count };
+  } catch (error) {
+    council_readiness = { ready: false, code: error.code || 'COUNCIL_READINESS_FAILED', message: error.message };
+  }
+  return Object.freeze(canonicalize({ schema_version: 1, mode: 'dry-run', writes_performed: false, artifact, doctor, detector, backup_plan, rollback_plan, incompatibilities, council_readiness }));
 }
 
-/** Explicit v2 installation. It writes only the provider-neutral artifact path. */
-export function installV2(input, {
-  projectDir, clock = () => new Date(), exists = existsSync, authorityDirectory,
-} = {}) {
-  const report = dryRunV2(input, { projectDir, clock, exists });
+/**
+ * Read-only operational precondition for new writes, shared with the wizard
+ * before it installs framework files. Historical guided artifacts stay readable
+ * but require explicit reconfiguration, never an implicit provider addition.
+ * This proves council eligibility, not CLI authentication or end-to-end health.
+ */
+export function assertExecutableV2Installation(artifact, { clock = () => new Date() } = {}) {
+  if (artifact?.installation?.quality_council?.mode !== 'autonomous') {
+    throw new ContractError('GUIDED_COUNCIL_REQUIRED',
+      'installation requires an autonomous council with at least two distinct selected providers capable of review; explicitly reconfigure guided installations');
+  }
+  return selectCouncilReviewers({
+    installation: artifact.installation,
+    snapshot: artifact.capability_snapshot,
+    policy: artifact.installation.quality_council,
+    clock,
+  });
+}
+
+async function authorizeV2Write(report, { projectDir, clock, licenseValidator }) {
   verifyInstallationCatalogProvenance(projectDir, report.artifact.capability_snapshot, { clock });
+  assertExecutableV2Installation(report.artifact, { clock });
+  if (report.artifact.installation.profile === 'authorized-internal') {
+    // A local profile/cache is not entitlement. Await the same authoritative
+    // check as the wizard before backups, host signatures or artifact writes.
+    await requireLicenseEntitlement('internal', { validate: licenseValidator });
+    verifyInstallationCatalogProvenance(projectDir, report.artifact.capability_snapshot, { clock });
+  }
+}
+
+async function withAuthorizedV2Write(report, options, action) {
+  // Read-only preflight precedes even maintenance bookkeeping: denied Internal
+  // authorization must leave both the project and host authority unchanged.
+  await authorizeV2Write(report, options);
+  return withUpgradeMaintenance(options.projectDir, async () => {
+    // Provenance may have changed during the authorization await. No backup,
+    // signature or artifact write is permitted before this check and the lease.
+    verifyInstallationCatalogProvenance(options.projectDir, report.artifact.capability_snapshot, { clock: options.clock });
+    assertExecutableV2Installation(report.artifact, { clock: options.clock });
+    return action();
+  }, { createState: true });
+}
+
+/** Private persistence primitive, reached only after authorizeV2Write. */
+function persistAuthorizedV2Report(report, { projectDir, authorityDirectory }) {
   const artifactPath = join(projectDir, INSTALLATION_ARTIFACT_PATH);
   const serialized = `${canonicalSerialize(report.artifact)}\n`;
   const existing = readSafeInstallationStorageFile(artifactPath, { allowMissing: true });
@@ -330,19 +439,32 @@ export function installV2(input, {
   }));
 }
 
+/** Explicit v2 installation, including Internal entitlement before persistence. */
+export async function installV2(input, {
+  projectDir, clock = () => new Date(), exists = existsSync, authorityDirectory, licenseValidator,
+} = {}) {
+  const report = dryRunV2(input, { projectDir, clock, exists });
+  return withAuthorizedV2Write(report, { projectDir, clock, licenseValidator },
+    () => persistAuthorizedV2Report(report, { projectDir, authorityDirectory }));
+}
+
 /**
  * Explicitly replaces an existing v2 artifact after preserving its exact
  * bytes in the project-local backup store. Provider-specific files are never
  * read or rewritten by this operation.
  */
-export function reconfigureV2(input, {
-  projectDir, clock = () => new Date(), exists = existsSync, authorityDirectory,
+export async function reconfigureV2(input, {
+  projectDir, clock = () => new Date(), exists = existsSync, authorityDirectory, licenseValidator,
 } = {}) {
   const report = dryRunV2(input, { projectDir, clock, exists });
-  verifyInstallationCatalogProvenance(projectDir, report.artifact.capability_snapshot, { clock });
+  return withAuthorizedV2Write(report, { projectDir, clock, licenseValidator }, () =>
+    reconfigureAuthorizedV2Report(report, { projectDir, authorityDirectory }));
+}
+
+function reconfigureAuthorizedV2Report(report, { projectDir, authorityDirectory }) {
   const artifactPath = join(projectDir, INSTALLATION_ARTIFACT_PATH);
   const existing = readSafeInstallationStorageFile(artifactPath, { allowMissing: true });
-  if (existing === null) return installV2(input, { projectDir, clock, exists, authorityDirectory });
+  if (existing === null) return persistAuthorizedV2Report(report, { projectDir, authorityDirectory });
   let existingArtifact;
   try { existingArtifact = JSON.parse(existing.content); } catch (error) {
     throw new ContractError('EXISTING_INSTALLATION_CORRUPT', `existing v2 artifact is not valid JSON: ${error.message}`);
@@ -374,14 +496,18 @@ export function reconfigureV2(input, {
  * legacy markers, writes the provider-neutral artifact, and never rewrites a
  * provider-specific configuration file.
  */
-export function migrateV2(input, {
-  projectDir, authorize = false, clock = () => new Date(), exists = existsSync, authorityDirectory,
+export async function migrateV2(input, {
+  projectDir, authorize = false, clock = () => new Date(), exists = existsSync, authorityDirectory, licenseValidator,
 } = {}) {
   const preview = dryRunV2(input, { projectDir, clock, exists });
   if (authorize !== true) {
     return Object.freeze(canonicalize({ ...preview, mode: 'migration-preview', writes_performed: false, requires_explicit_authorization: true }));
   }
+  return withAuthorizedV2Write(preview, { projectDir, clock, licenseValidator }, () =>
+    migrateAuthorizedV2Report(preview, { projectDir, authorityDirectory }));
+}
 
+function migrateAuthorizedV2Report(preview, { projectDir, authorityDirectory }) {
   const artifactPath = join(projectDir, INSTALLATION_ARTIFACT_PATH);
   const existingArtifact = readSafeInstallationStorageFile(artifactPath, { allowMissing: true });
   if (existingArtifact !== null) {
@@ -403,7 +529,7 @@ export function migrateV2(input, {
       conflictCode: 'MIGRATION_BACKUP_CONFLICT', label: 'legacy migration backup',
     })) backed_up.push(entry);
   }
-  const installed = installV2(input, { projectDir, clock, exists, authorityDirectory });
+  const installed = persistAuthorizedV2Report(preview, { projectDir, authorityDirectory });
   return Object.freeze(canonicalize({
     ...preview,
     mode: 'migrated',

package/src/installer-v2/installation-authority.js

@@ -3,13 +3,14 @@ import {
   sign as cryptoSign, verify as cryptoVerify,
 } from 'node:crypto';
 import { userInfo } from 'node:os';
-import { basename, dirname, join, relative, resolve } from 'node:path';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
 import { lstatSync, realpathSync } from 'node:fs';
 import { canonicalSerialize, ContractError } from '@chati/core';
 import {
   persistImmutableInstallationFile, readSafeInstallationStorageFile,
 } from './catalog-client.js';
 
+export { projectBinding as installationAuthorityProjectBinding };
 export const INSTALLATION_AUTHORITY_RECEIPT_VERSION = 1;
 export const INSTALLATION_AUTHORITY_RECEIPT_TYPE = 'chati-installation-authority';
 export const INSTALLATION_AUTHORITY_DIRECTORY = '.chati/v2/authorities';
@@ -66,7 +67,7 @@ function assertPrivateKeyPermissions(source) {
   }
 }
 
-function readOrCreateAuthorityKeyPair(authorityDirectory) {
+function readOrCreateAuthorityKeyPair(authorityDirectory, { create = true } = {}) {
   const root = authorityRoot(authorityDirectory);
   const privatePath = join(root, PRIVATE_KEY_FILENAME);
   const publicPath = installationAuthorityPublicKeyPath(authorityDirectory);
@@ -74,6 +75,7 @@ function readOrCreateAuthorityKeyPair(authorityDirectory) {
     allowMissing: true, label: 'installation authority private key', encoding: 'utf8', maxBytes: 64 * 1024,
   });
   if (privateSource === null) {
+    if (!create) fail('DELEGATED_AUTHORITY_IDENTITY_REQUIRED', 'create a public certification request before using the delegated authority');
     const generated = generateKeyPairSync('ed25519', {
       privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
       publicKeyEncoding: { type: 'spki', format: 'pem' },
@@ -204,7 +206,34 @@ function unsignedReceipt(receipt) {
 export function authorizeInstallationArtifact(projectDir, artifact, {
   authorityDirectory,
 } = {}) {
+  // A host receipt is minted only by a current explicit install or
+  // reconfigure action.  It must not be usable to manufacture a "historical"
+  // policy-less installation by passing an old deterministic clock.
+  if (artifact?.installation?.quality_council === undefined) {
+    fail('QUALITY_COUNCIL_REQUIRED', 'current host authority refuses to authorize an installation without quality_council');
+  }
   const authority = readOrCreateAuthorityKeyPair(authorityDirectory);
+  const path = receiptPath(projectDir, artifact);
+  const existing = readSafeInstallationStorageFile(path, {
+    allowMissing: true, label: 'installation authority receipt', encoding: 'utf8', maxBytes: 256 * 1024,
+  });
+  if (existing !== null) {
+    let receipt;
+    try { receipt = JSON.parse(existing.content); }
+    catch { fail('INVALID_INSTALLATION_AUTHORITY_RECEIPT', 'installation authority receipt is not valid JSON'); }
+    try {
+      verifyInstallationArtifactAuthority(projectDir, artifact, { authorityDirectory });
+    } catch (error) {
+      if (error?.code === 'INSTALLATION_AUTHORITY_MISMATCH') {
+        fail('INSTALLATION_AUTHORITY_RECEIPT_CONFLICT', 'installation authority receipt exists for a different host authority');
+      }
+      throw error;
+    }
+    return Object.freeze({
+      receipt: Object.freeze(receipt),
+      receipt_path: relative(resolve(projectDir), path).replaceAll('\\', '/'),
+    });
+  }
   const payload = {
     schema_version: INSTALLATION_AUTHORITY_RECEIPT_VERSION,
     receipt_type: INSTALLATION_AUTHORITY_RECEIPT_TYPE,
@@ -213,13 +242,14 @@ export function authorizeInstallationArtifact(projectDir, artifact, {
     installation_artifact_id: artifact.installation_artifact_id,
     installation_digest: artifact.digest,
     artifact_created_at: artifact.created_at,
-    issued_at: artifact.created_at,
+    // This is an actual authority issue time, never the artifact's
+    // caller-supplied deterministic timestamp.
+    issued_at: new Date().toISOString(),
   };
   const receipt = Object.freeze({
     ...payload,
     signature: cryptoSign(null, Buffer.from(canonicalSerialize(payload)), authority.privateKey).toString('base64'),
   });
-  const path = receiptPath(projectDir, artifact);
   persistImmutableInstallationFile(path, `${canonicalSerialize(receipt)}\n`, {
     conflictCode: 'INSTALLATION_AUTHORITY_RECEIPT_CONFLICT',
     label: 'installation authority receipt', maxBytes: 256 * 1024,
@@ -282,6 +312,70 @@ export function installationAuthorityStateDirectory(authorityDirectory) {
   return authorityRoot(authorityDirectory);
 }
 
+function delegatedAuthority({ projectDir, projectId, kind, authorityDirectory, create = false } = {}) {
+  if (!['rail-evidence', 'clickup-mcp'].includes(kind) || typeof projectId !== 'string' || !projectId.trim()) {
+    fail('INVALID_DELEGATED_AUTHORITY', 'delegated authority requires a project and a supported evidence kind');
+  }
+  const root = authorityRoot(authorityDirectory);
+  const project = realpathSync(resolve(projectDir));
+  if (root === project || root.startsWith(`${project}${sep}`) || project.startsWith(`${root}${sep}`)) {
+    fail('DELEGATED_AUTHORITY_PROJECT_OVERLAP', 'delegated private authority storage must not overlap the project');
+  }
+  const binding = projectBinding(project, projectId);
+  const bindingDigest = createHash('sha256').update(canonicalSerialize({ kind, binding })).digest('hex');
+  const delegatedRoot = join(root, 'evidence-issuers', bindingDigest);
+  const authority = readOrCreateAuthorityKeyPair(delegatedRoot, { create });
+  return { ...authority, bindingDigest,
+    issuer_id: `local-${kind}://${keyFingerprint(authority.publicKey)}/${bindingDigest}` };
+}
+
+/** A distinct delegated key, not an additional root of trust. Public output only. */
+export function delegatedAuthorityPublicIdentity(options) {
+  const authority = delegatedAuthority(options);
+  return Object.freeze({
+    issuer_id: authority.issuer_id, project_binding_digest: authority.bindingDigest,
+    public_key: authority.publicKey.export({ type: 'spki', format: 'pem' }),
+  });
+}
+
+/** Internal issuer primitive. No CLI accepts arbitrary statements to sign. */
+export function signDelegatedAuthorityStatement(statement, options) {
+  const authority = delegatedAuthority({ ...options, create: false });
+  return Object.freeze({ issuer_id: authority.issuer_id,
+    signature: cryptoSign(null, Buffer.from(canonicalSerialize(statement)), authority.privateKey).toString('base64') });
+}
+
+/** Internal ClickUp observer primitive, not a CLI accepting results to sign.
+ * The existing v2 MCP receipt verifier uses this ordered JSON wire format,
+ * whereas certification requests and RAIL statements use canonical JSON.
+ * Keep those domains distinct; never export or recreate the delegated key.
+ */
+export function signDelegatedClickUpMcpPayload(payload, options) {
+  const fields = ['schema_version', 'issuer_id', 'kind', 'projection_id', 'clickup_ref',
+    'idempotency_key', 'operation', 'delivery_attempt', 'delivery_attempted_at', 'observed_at', 'response_digest'];
+  const invalid = () => fail('INVALID_CLICKUP_SIGNING_PAYLOAD', 'ClickUp observation requires its exact v2 signing payload');
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)
+    || ![null, Object.prototype].includes(Object.getPrototypeOf(payload))
+    || Object.getOwnPropertySymbols(payload).length
+    || Object.keys(payload).sort().join(',') !== [...fields].sort().join(',')) invalid();
+  const descriptors = Object.getOwnPropertyDescriptors(payload);
+  if (fields.some((name) => !Object.hasOwn(descriptors[name], 'value'))) invalid();
+  // Reconstruct the verifier's exact order, independent of caller insertion order.
+  const statement = Object.fromEntries(fields.map((name) => [name, descriptors[name].value]));
+  if (statement.schema_version !== 2 || !['clickup_ack', 'clickup_lookup'].includes(statement.kind)
+    || !['create', 'update', 'close'].includes(statement.operation)
+    || !Number.isSafeInteger(statement.delivery_attempt) || statement.delivery_attempt < 1
+    || !fields.filter((name) => !['schema_version', 'delivery_attempt'].includes(name))
+      .every((name) => typeof statement[name] === 'string' && statement[name].length > 0 && statement[name].length <= 8192)
+    || !/^[a-f0-9]{64}$/.test(statement.response_digest)
+    || !Number.isFinite(Date.parse(statement.delivery_attempted_at)) || !Number.isFinite(Date.parse(statement.observed_at))
+    || (options?.kind !== undefined && options.kind !== 'clickup-mcp')) invalid();
+  const authority = delegatedAuthority({ ...options, kind: 'clickup-mcp', create: false });
+  if (statement.issuer_id !== authority.issuer_id) invalid();
+  return Object.freeze({ issuer_id: authority.issuer_id,
+    signature: cryptoSign(null, Buffer.from(JSON.stringify(statement)), authority.privateKey).toString('base64') });
+}
+
 /** Sign a domain-separated payload with the persistent host authority. */
 export function signHostAuthorityPayload(payload, {
   domain,

package/src/installer-v2/provider-executable.js

@@ -3,6 +3,7 @@ import {
   closeSync, constants, fstatSync, lstatSync, openSync, readSync, realpathSync,
 } from 'node:fs';
 import { basename, delimiter, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { homedir } from 'node:os';
 
 const MAX_PROVIDER_EXECUTABLE_BYTES = 1024 * 1024 * 1024;
 const PROVIDER_EXECUTABLE_DIGEST = /^[a-f0-9]{64}$/;
@@ -14,6 +15,11 @@ const CODEX_NATIVE_TARGETS = Object.freeze({
   'darwin/arm64': Object.freeze(['@openai/codex-darwin-arm64', 'aarch64-apple-darwin']),
 });
 
+/** A sealed native Grok launch must retain its npm launcher's managed marker. */
+export function sealedProviderRuntimeEnvironment(harnessId) {
+  return Object.freeze(harnessId === 'grok' ? { GROK_MANAGED_BY_NPM: '1' } : {});
+}
+
 function fail(code, message) {
   throw Object.assign(new Error(message), { code });
 }
@@ -87,19 +93,106 @@ function codexNativeExecutable(wrapperPath, { platform = process.platform, arch
   return fail('PROVIDER_EXECUTABLE_NOT_FOUND', 'Codex wrapper does not resolve to its installed native executable');
 }
 
-function effectiveProviderExecutable(harnessId, resolvedCommand, options) {
-  if (harnessId !== 'codex') return resolvedCommand;
+function executablePrefix(path) {
   let descriptor;
-  let prefix;
   try {
-    descriptor = openSync(resolvedCommand, constants.O_RDONLY | (constants.O_NOFOLLOW || 0));
+    descriptor = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW || 0) | (constants.O_NONBLOCK || 0));
+    assertExecutableStat(fstatSync(descriptor));
     const buffer = Buffer.alloc(64);
     const bytes = readSync(descriptor, buffer, 0, buffer.length, 0);
-    prefix = buffer.subarray(0, bytes).toString('utf8');
+    return buffer.subarray(0, bytes);
+  } finally {
+    if (descriptor !== undefined) closeSync(descriptor);
+  }
+}
+
+function isNativeImage(prefix) {
+  return ['7f454c46', 'feedface', 'cefaedfe', 'feedfacf', 'cffaedfe', 'cafebabe', 'bebafeca', 'cafebabf', 'bfbafeca']
+    .includes(prefix.subarray(0, 4).toString('hex'));
+}
+
+function knownNpmLauncherRoot(harnessId, path) {
+  const expected = harnessId === 'claude' ? '@anthropic-ai/claude-code' : '@xai-official/grok';
+  const root = dirname(dirname(path));
+  if (basename(dirname(path)) !== 'bin'
+    || `${basename(dirname(root))}/${basename(root)}` !== expected) return null;
+  let descriptor;
+  try {
+    descriptor = openSync(join(root, 'package.json'), constants.O_RDONLY | (constants.O_NOFOLLOW || 0) | (constants.O_NONBLOCK || 0));
+    const before = fstatSync(descriptor);
+    if (!before.isFile() || before.size > 64 * 1024) fail('PROVIDER_EXECUTABLE_BINDING_INVALID', 'provider package metadata must be a bounded regular file');
+    const bytes = Buffer.alloc((64 * 1024) + 1);
+    let offset = 0;
+    while (offset < bytes.length) {
+      const count = readSync(descriptor, bytes, offset, bytes.length - offset, null);
+      if (!count) break;
+      offset += count;
+    }
+    if (offset > 64 * 1024 || !sameSnapshot(snapshot(before), snapshot(fstatSync(descriptor)))) {
+      fail('PROVIDER_EXECUTABLE_DRIFT', 'provider package metadata changed during resolution');
+    }
+    const metadata = JSON.parse(bytes.subarray(0, offset).toString('utf8'));
+    if (metadata.name !== expected || typeof metadata.bin?.[harnessId] !== 'string'
+      || resolve(root, metadata.bin[harnessId]) !== path) {
+      fail('PROVIDER_EXECUTABLE_BINDING_INVALID', 'provider launcher does not match its installed package metadata');
+    }
+    return root;
+  } catch (error) {
+    if (error?.code?.startsWith('PROVIDER_EXECUTABLE_')) throw error;
+    return fail('PROVIDER_EXECUTABLE_BINDING_INVALID', `provider package metadata is unavailable or invalid: ${error.code || error.name}`);
   } finally {
     if (descriptor !== undefined) closeSync(descriptor);
   }
-  return prefix.startsWith('#!') ? codexNativeExecutable(resolvedCommand, options) : resolvedCommand;
+}
+
+function installedNativeCandidate(path) {
+  let resolved;
+  try { resolved = realpathSync(path); }
+  catch (error) { if (error?.code === 'ENOENT') return null; throw error; }
+  if (!isNativeImage(executablePrefix(resolved))) {
+    fail('PROVIDER_EXECUTABLE_BINDING_INVALID', 'provider native image resolved to a script or unsupported executable format');
+  }
+  return resolved;
+}
+
+function packageNativeExecutable(harnessId, root, { platform, arch, grokHome, libc }) {
+  if (!['linux', 'darwin'].includes(platform) || !['x64', 'arm64'].includes(arch)) {
+    fail('PROVIDER_EXECUTABLE_UNSUPPORTED', `${harnessId} native binding is unsupported on ${platform}/${arch}`);
+  }
+  if (harnessId === 'grok') {
+    // Follow the npm launcher's existing canonical installation, without
+    // running its decompression/bootstrap or changing any global CLI state.
+    const canonical = installedNativeCandidate(join(grokHome, 'bin', 'grok'));
+    if (canonical) return canonical;
+  }
+  if (platform === 'linux' && !['glibc', 'musl'].includes(libc)) {
+    fail('PROVIDER_EXECUTABLE_UNSUPPORTED', 'native provider binding requires a supported Linux libc');
+  }
+  const musl = harnessId === 'claude' && platform === 'linux' && libc === 'musl';
+  const scope = harnessId === 'claude' ? '@anthropic-ai' : '@xai-official';
+  const packageName = `${harnessId === 'claude' ? 'claude-code' : 'grok'}-${platform}-${arch}${musl ? '-musl' : ''}`;
+  const entry = harnessId === 'claude' ? 'claude' : join('bin', 'grok');
+  for (const candidate of [join(root, 'node_modules', scope, packageName, entry), join(dirname(root), packageName, entry)]) {
+    const native = installedNativeCandidate(candidate);
+    if (native) return native;
+  }
+  return fail('PROVIDER_EXECUTABLE_NOT_FOUND', `${harnessId} has no installed native image; complete that CLI's own installation before retrying Chati`);
+}
+
+function effectiveProviderExecutable(harnessId, resolvedCommand, options) {
+  const prefix = executablePrefix(resolvedCommand);
+  if (isNativeImage(prefix)) return resolvedCommand;
+  if (harnessId === 'claude' || harnessId === 'grok') {
+    const packageRoot = knownNpmLauncherRoot(harnessId, resolvedCommand);
+    if (packageRoot) return packageNativeExecutable(harnessId, packageRoot, options);
+  }
+  // Resolving a multicall shell alias loses its invocation name when sealed
+  // descriptors are executed. Never silently bind the shared dispatcher.
+  if (![harnessId, `${harnessId}.js`, `${harnessId}.cjs`, `${harnessId}.mjs`, `${harnessId}.exe`].includes(basename(resolvedCommand))) {
+    fail('PROVIDER_EXECUTABLE_WRAPPER_UNSUPPORTED', `${harnessId} resolves to a non-native shared or renamed launcher; expose the installed provider executable in the installation PATH`);
+  }
+  return harnessId === 'codex' && prefix.toString('utf8').startsWith('#!')
+    ? codexNativeExecutable(resolvedCommand, options) : resolvedCommand;
 }
 
 function digestExecutablePath(executablePath) {
@@ -107,7 +200,7 @@ function digestExecutablePath(executablePath) {
   try {
     const pathStat = lstatSync(executablePath);
     if (pathStat.isSymbolicLink()) fail('PROVIDER_EXECUTABLE_BINDING_INVALID', 'provider executable binding may not end in a symlink');
-    descriptor = openSync(executablePath, constants.O_RDONLY | (constants.O_NOFOLLOW || 0));
+    descriptor = openSync(executablePath, constants.O_RDONLY | (constants.O_NOFOLLOW || 0) | (constants.O_NONBLOCK || 0));
     const pinned = fstatSync(descriptor);
     if (pathStat.dev !== pinned.dev || pathStat.ino !== pinned.ino) {
       fail('PROVIDER_EXECUTABLE_DRIFT', 'provider executable changed before descriptor pinning');
@@ -133,6 +226,8 @@ export function resolveProviderExecutableBinding(harnessId, {
   pathEnv = process.env.PATH,
   platform = process.platform,
   arch = process.arch,
+  grokHome = process.env.GROK_HOME ?? join(homedir(), '.grok'),
+  libc = process.platform === 'linux' && !process.report?.getReport()?.header?.glibcVersionRuntime ? 'musl' : 'glibc',
 } = {}) {
   if (!['claude', 'codex', 'grok'].includes(harnessId)) {
     fail('PROVIDER_EXECUTABLE_UNSUPPORTED', `provider executable binding is unsupported for ${harnessId}`);
@@ -140,7 +235,7 @@ export function resolveProviderExecutableBinding(harnessId, {
   const executable_path = effectiveProviderExecutable(
     harnessId,
     resolveFromPath(harnessId, pathEnv),
-    { platform, arch },
+    { platform, arch, grokHome, libc },
   );
   const digest = digestExecutablePath(executable_path);
   return Object.freeze({
@@ -201,13 +296,13 @@ function assertOutsideProject(executablePath, projectDir) {
   }
 }
 
-function openPinnedExecutable(reference, { projectDir } = {}) {
+function openPinnedExecutable(reference, { projectDir, requireNativeImage = false } = {}) {
   assertOutsideProject(reference.executable_path, projectDir);
   let descriptor;
   try {
     const pathStat = lstatSync(reference.executable_path);
     if (pathStat.isSymbolicLink()) fail('PROVIDER_EXECUTABLE_BINDING_INVALID', 'provider executable binding may not end in a symlink');
-    descriptor = openSync(reference.executable_path, constants.O_RDONLY | (constants.O_NOFOLLOW || 0));
+    descriptor = openSync(reference.executable_path, constants.O_RDONLY | (constants.O_NOFOLLOW || 0) | (constants.O_NONBLOCK || 0));
     const pinned = fstatSync(descriptor);
     if (pathStat.dev !== pinned.dev || pathStat.ino !== pinned.ino) {
       fail('PROVIDER_EXECUTABLE_DRIFT', 'provider executable changed before descriptor pinning');
@@ -216,6 +311,16 @@ function openPinnedExecutable(reference, { projectDir } = {}) {
     if (executable.sha256 !== reference.executable_sha256) {
       fail('PROVIDER_EXECUTABLE_DRIFT', 'provider executable digest differs from the sealed installation binding');
     }
+    if (requireNativeImage) {
+      const prefix = Buffer.alloc(4);
+      const count = readSync(descriptor, prefix, 0, prefix.length, 0);
+      if (!sameSnapshot(snapshot(fstatSync(descriptor)), executable.snapshot)) {
+        fail('PROVIDER_EXECUTABLE_DRIFT', 'verification interpreter changed during native-format validation');
+      }
+      if (count !== prefix.length || !isNativeImage(prefix)) {
+        fail('PROVIDER_EXECUTABLE_NATIVE_REQUIRED', 'verification checks require a pinned native interpreter, not a shebang wrapper');
+      }
+    }
     return Object.freeze({ descriptor, binding: reference, executable });
   } catch (error) {
     if (descriptor !== undefined) closeSync(descriptor);
@@ -224,9 +329,9 @@ function openPinnedExecutable(reference, { projectDir } = {}) {
   }
 }
 
-export function openPinnedProviderExecutable(binding, { harnessId, projectDir } = {}) {
+export function openPinnedProviderExecutable(binding, { harnessId, projectDir, requireNativeImage = false } = {}) {
   const validated = validateProviderExecutableBinding(binding, { harnessId });
-  return openPinnedExecutable(validated, { projectDir });
+  return openPinnedExecutable(validated, { projectDir, requireNativeImage });
 }
 
 export function openPinnedProviderSupportingExecutables(binding, { harnessId, projectDir } = {}) {

package/src/installer-v2/wizard-installation.js

@@ -104,6 +104,17 @@ export function buildWizardV2InstallationInput({
     enabled_providers,
     capability_snapshot_ref: snapshotId,
     policy_ref: `policy://installation/${snapshotId}`,
+    // Preserve a descriptive guided artifact for previews and historical reads.
+    // New executable writes require autonomous mode and an eligible quorum;
+    // the installer enforces this without inventing an unselected reviewer.
+    quality_council: {
+      mode: providers.length >= 2 ? 'autonomous' : 'guided',
+      stages: ['discovery', 'planning', 'execution-design'],
+      min_members: 2,
+      max_members: 3,
+      require_distinct_providers: true,
+      blocking_severities: ['critical', 'high'],
+    },
     ...(installationMode === 'internal' ? { external_integrations: { clickup: 'required' } } : {}),
   };
   return Object.freeze({