chati-dev 4.5.16 → 4.5.28

package/src/config/framework-adapter.js

@@ -49,10 +49,10 @@ export function stripLegacyBuildSurface(content) {
 const CODEX_CREDENTIAL_BOUNDARY = `
 ## Codex external provider credential boundary
 
-Commands returned in any \`spawn_command\`, \`parallel_spawn_command\` or
-\`parallel_spawn_commands\` start another provider CLI. Codex MUST execute each
-command through its native local execution path so the child CLI can access its
-existing local credentials:
+Commands returned in any \`spawn_command\`, \`deferred_spawn_command\`,
+\`parallel_spawn_command\` or \`parallel_spawn_commands\` start another provider
+CLI. Codex MUST execute each command through its native local execution path so
+the child CLI can access its existing local credentials:
 
 - If the active Codex host requires approval to leave a restricted workspace
   sandbox, request the narrow native approval it exposes for the exact command.

package/src/installer/core.js

@@ -1,17 +1,18 @@
-import { mkdirSync, writeFileSync, copyFileSync, existsSync, readFileSync, readdirSync, statSync, rmSync } from 'fs';
+import { mkdirSync, writeFileSync, copyFileSync, existsSync, readFileSync, readdirSync, statSync, lstatSync, rmSync } from 'fs';
 import { execFileSync } from 'child_process';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { createRequire } from 'module';
 import { IDE_CONFIGS, IDE_TO_PROVIDER } from '../config/ide-configs.js';
 import { mergeClaudeMCPConfig, upsertManagedMcpToml } from '../config/mcp-configs.js';
-import { generateSessionYaml, generateConfigYaml, generateProjectContext, generateClaudeMd, generateClaudeLocalMd, generateCodexSkill, generateGeminiRouter, generateGrokRouter, generateGeminiSessionLock, generateAgentsOverrideMd, generateCodexConstitutionGuardRules, generateCodexReadProtectionRules } from './templates.js';
+import { generateSessionYaml, generateConfigYaml, generateProjectContext, generateClaudeMd, generateClaudeLocalMd, generateCodexSkill, generateGeminiRouter, generateGrokRouter, generateGrokGovernanceRules, generateGeminiSessionLock, generateAgentsOverrideMd, generateCodexConstitutionGuardRules, generateCodexReadProtectionRules } from './templates.js';
 import { generateContextFiles } from '../config/context-file-generator.js';
 import { adaptFrameworkFile, ADAPTABLE_FILES, stripLegacyBuildSurface } from '../config/framework-adapter.js';
 import { generateClaudeSettings } from '../config/claude-settings-generator.js';
 import { generateProviderOverlays } from './provider-overlay.js';
 import { applyInstalledPathReplacement } from './path-replacement.js';
-import { verifyManifest } from './manifest.js';
+import { verifyFrameworkSource } from './manifest.js';
+import { initializeSessionDocument } from '../orchestrator/session-manager.js';
 import * as yaml from 'js-yaml';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -30,47 +31,35 @@ export async function installFramework(config) {
   const enabledProviders = allProviders?.length
     ? [...new Set(allProviders)]
     : [...new Set((selectedIDEs || []).map(ide => IDE_TO_PROVIDER[ide]).filter(Boolean))];
-  // Always derive version from package.json (single source of truth)
+  // The signed source is always anchored to the package version. `config.version`
+  // remains an installer/test presentation override and cannot redefine trust.
+  let packageVersion = null;
+  try {
+    const pkgPath = join(__dirname, '..', '..', 'package.json');
+    packageVersion = JSON.parse(readFileSync(pkgPath, 'utf-8')).version;
+  } catch { /* the integrity check below will still fail closed on source drift */ }
+
   let { version } = config;
-  if (!version) {
-    try {
-      const pkgPath = join(__dirname, '..', '..', 'package.json');
-      version = JSON.parse(readFileSync(pkgPath, 'utf-8')).version;
-    } catch { version = 'unknown'; }
-  }
+  if (!version) version = packageVersion || 'unknown';
 
   // 0. Verify framework signature (supply chain protection)
-  const manifestPath = join(FRAMEWORK_SOURCE, 'manifest.json');
-  const sigPath = join(FRAMEWORK_SOURCE, 'manifest.sig');
-
-  if (existsSync(manifestPath) && existsSync(sigPath)) {
-    const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
-    const signature = readFileSync(sigPath, 'utf-8').trim();
-    const result = verifyManifest(manifest, signature);
-
-    if (!result.valid && result.reason === 'signature-mismatch') {
-      throw new Error('Framework signature verification failed. Package may have been tampered with.');
-    }
-  }
-
-  // 1. Create .chati/ session directory
-  createDir(join(targetDir, '.chati'));
-  const sessionPath = join(targetDir, '.chati', 'session.yaml');
-  // Preserve existing session.yaml on reinstall/recovery (don't destroy pipeline state).
-  // Only write fresh session if one does not exist.
-  if (!existsSync(sessionPath)) {
-    writeFileSync(
-      sessionPath,
-      generateSessionYaml({ projectName, projectType, language, selectedIDEs, selectedMCPs, allProviders: enabledProviders }),
-      'utf-8'
-    );
+  const integrity = verifyFrameworkSource(FRAMEWORK_SOURCE, { expectedVersion: packageVersion });
+  if (!integrity.valid) {
+    throw new Error(`Framework integrity verification failed (${integrity.reason}). Package may have been tampered with.`);
   }
+  // 1. Create the canonical session through the lock-aware session manager.
+  // Reinstall/recovery always preserves an existing document.
+  const initialSession = initializeSessionDocument(
+    targetDir,
+    generateSessionYaml({ projectName, projectType, language, selectedIDEs, selectedMCPs, allProviders: enabledProviders }),
+  );
+  if (initialSession.error) throw new Error(initialSession.error);
 
   // 2. Create .chati.dev/ framework directory (hidden — dot prefix)
   // The source is chati.dev/ in the monorepo; installed as .chati.dev/ in user projects.
   // Text replacement during copy handles all internal path references.
   const frameworkDir = join(targetDir, '.chati.dev');
-  createDir(frameworkDir);
+  createSafeManagedDirectory(frameworkDir);
 
   // 2b. Create artifacts/ at PROJECT ROOT (visible to user — this is their output)
   const artifactsDir = join(targetDir, 'artifacts');
@@ -101,7 +90,7 @@ export async function installFramework(config) {
   ];
 
   for (const dir of frameworkDirs) {
-    createDir(join(frameworkDir, dir));
+    createSafeManagedDirectory(join(frameworkDir, dir));
   }
 
   // Create .chati/memories/ directory tree for Memory Layer
@@ -162,6 +151,9 @@ export async function installFramework(config) {
     join(__dirname, '..', '..', 'framework', 'hooks'),
     join(frameworkDir, 'framework', 'hooks')
   );
+  if (isRuntimeV2) {
+    rmSync(join(frameworkDir, 'framework', 'hooks', 'post-dev.js'), { force: true });
+  }
 
   // Also bundle production deps so the CLI can import js-yaml/chalk/etc. at runtime
   // without relying on a node_modules tree in the user's project.
@@ -330,11 +322,18 @@ function pruneLegacyExecutionSurface(frameworkDir, providers) {
 }
 
 export function ensureGitRepository(targetDir) {
+  const environment = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('GIT_')));
+  const gitEnvironment = {
+    ...environment,
+    GIT_CONFIG_NOSYSTEM: '1',
+    GIT_CONFIG_GLOBAL: process.platform === 'win32' ? 'NUL' : '/dev/null',
+    GIT_TERMINAL_PROMPT: '0',
+  };
   try {
-    execFileSync('git', ['-C', targetDir, 'rev-parse', '--show-toplevel'], { stdio: 'ignore' });
+    execFileSync('git', ['-C', targetDir, 'rev-parse', '--show-toplevel'], { stdio: 'ignore', env: gitEnvironment });
     return { initialized: false };
   } catch {
-    execFileSync('git', ['-C', targetDir, 'init', '-q'], { stdio: 'ignore' });
+    execFileSync('git', ['-C', targetDir, 'init', '-q'], { stdio: 'ignore', env: gitEnvironment });
     return { initialized: true };
   }
 }
@@ -401,7 +400,7 @@ const TEXT_EXTENSIONS = new Set(['.md', '.js', '.yaml', '.yml', '.json', '.html'
  */
 function copyDirRecursive(srcDir, destDir, provider, relBase = '') {
   if (!existsSync(srcDir)) return;
-  createDir(destDir);
+  createSafeManagedDirectory(destDir);
 
   const entries = readdirSync(srcDir, { withFileTypes: true });
   for (const entry of entries) {
@@ -425,10 +424,10 @@ function copyDirRecursive(srcDir, destDir, provider, relBase = '') {
         if (provider && ADAPTABLE_FILES.has(relPath)) {
           content = adaptFrameworkFile(content, relPath, provider);
         }
-        writeFileSync(destPath, content, 'utf-8');
+        writeSafeManagedFile(destPath, content, 'utf-8');
       } else {
         // Binary file: direct copy
-        copyFileSync(srcPath, destPath);
+        copySafeManagedFile(srcPath, destPath);
       }
     }
   }
@@ -451,13 +450,13 @@ export function copyFrameworkFiles(destDir, provider = null) {
     const src = join(FRAMEWORK_SOURCE, file);
     if (!existsSync(src)) continue;
     const dest = join(destDir, file);
-    createDir(dirname(dest));
+    createSafeManagedDirectory(dirname(dest));
     let content = readFileSync(src, 'utf-8');
     content = applyInstalledPathReplacement(content);
     if (provider && ADAPTABLE_FILES.has(file)) {
       content = adaptFrameworkFile(content, file, provider);
     }
-    writeFileSync(dest, content, 'utf-8');
+    writeSafeManagedFile(dest, content, 'utf-8');
   }
 
   // Copy each framework directory recursively
@@ -512,6 +511,14 @@ Parse the JSON output. This single command already handled: license validation,
 
 **The \`pipeline\` object contains the full JSON from \`orchestrate next\`.** Use its fields (agent_file, spawn_command, handoff_status, etc.) as documented in the orchestrator.
 
+**Pending interaction invariant:** If \`action\` is \`resume_pending_interaction\`,
+do not execute a provider command. Display exactly \`pipeline.question\`, with
+no preface, summary or paraphrase. After the user answers, write
+\`{"response":"<exact user response>"}\` to \`pipeline.response_file\` using the
+native file-write tool, never a shell command. Then execute
+\`pipeline.deferred_spawn_command\` exactly once and unchanged. Never execute a
+command merely because a command-shaped field is present.
+
 **User input:** $ARGUMENTS
 `;
     writeFileSync(join(targetDir, '.claude', 'commands', 'chati.md'), routerContent, 'utf-8');
@@ -544,14 +551,14 @@ Parse the JSON output. This single command already handled: license validation,
     writeFileSync(join(targetDir, '.codex', 'rules', 'constitution-guard.rules'), generateCodexConstitutionGuardRules(), 'utf-8');
     writeFileSync(join(targetDir, '.codex', 'rules', 'read-protection.rules'), generateCodexReadProtectionRules(), 'utf-8');
 
-    // .codex/hooks.json — license-guard wired to UserPromptSubmit (per-turn enforcement).
-    // Codex hooks require [features] hooks = true in the active project config.
-    // Without it, license enforcement only happens at skill entry and the router,
-    // entry — a long-running terminal session would not be re-validated.
+    // .codex/hooks.json — use Codex's native lifecycle surface for the same
+    // controller boundaries enforced in the other enabled harnesses. In
+    // particular, `PreToolUse` observes Bash and local mutation tools, not
+    // merely the prompt entrypoint. Codex hooks require [features] hooks = true
+    // in the active project config.
     writeFileSync(
       join(targetDir, '.codex', 'hooks.json'),
       JSON.stringify({
-        $comment: 'chati.dev Codex lifecycle hooks. Requires [features] hooks = true.',
         hooks: {
           UserPromptSubmit: [
             {
@@ -564,6 +571,34 @@ Parse the JSON output. This single command already handled: license validation,
               ],
             },
           ],
+          PreToolUse: [
+            {
+              matcher: '^Bash$',
+              hooks: [
+                {
+                  type: 'command',
+                  command: 'node .chati.dev/hooks/git-push-authority.js',
+                },
+              ],
+            },
+            {
+              matcher: '^(?:apply_patch|Edit|Write|NotebookEdit)$',
+              hooks: [
+                {
+                  type: 'command',
+                  command: 'node .chati.dev/hooks/mode-governance.js',
+                },
+                {
+                  type: 'command',
+                  command: 'node .chati.dev/hooks/team-quality-gate.js',
+                },
+                {
+                  type: 'command',
+                  command: 'node .chati.dev/hooks/reasoning-escalator.js',
+                },
+              ],
+            },
+          ],
         },
       }, null, 2) + '\n',
       'utf-8'
@@ -599,6 +634,8 @@ Parse the JSON output. This single command already handled: license validation,
   } else if (ideKey === 'grok-cli') {
     writeFileSync(join(targetDir, '.grok', 'commands', 'chati.md'), generateGrokRouter({ orchestratorPath }), 'utf-8');
     writeFileSync(join(targetDir, '.grok', 'session-lock.md'), generateClaudeLocalMd(), 'utf-8');
+    createDir(join(targetDir, '.grok', 'rules'));
+    writeFileSync(join(targetDir, '.grok', 'rules', 'chati-governance.md'), generateGrokGovernanceRules(), 'utf-8');
     const grokConfigPath = join(targetDir, '.grok', 'config.toml');
     if (selectedMCPs.length > 0 || existsSync(grokConfigPath)) {
       const existingConfig = existsSync(grokConfigPath) ? readFileSync(grokConfigPath, 'utf-8') : '';
@@ -699,6 +736,7 @@ export function updateGitignore(targetDir, selectedIDEs) {
     '',
     '# Runtime state (session, teams, timeline, transient memories)',
     '.chati/session.yaml',
+    '.chati/runtime/',
     '.chati/teams/',
     '.chati/timeline.json',
     '.chati/memories/*/session/',
@@ -745,6 +783,7 @@ export function updateGitignore(targetDir, selectedIDEs) {
       '',
       '# Grok provider framework files',
       '.grok/commands/',
+      '.grok/rules/',
       '.grok/session-lock.md',
     );
   }
@@ -961,6 +1000,58 @@ function createDir(dir) {
   }
 }
 
+function unsafeManagedPath(path, message) {
+  const error = new Error(`${message}: ${path}`);
+  error.code = 'UNSAFE_INSTALLATION_TARGET';
+  throw error;
+}
+
+/** Managed framework paths must never resolve through a user-provided link. */
+function createSafeManagedDirectory(dir) {
+  const missing = [];
+  let current = join(dir);
+  for (;;) {
+    try {
+      const stat = lstatSync(current);
+      if (stat.isSymbolicLink() || !stat.isDirectory()) unsafeManagedPath(current, 'managed directory must be a real directory');
+      break;
+    } catch (error) {
+      if (error?.code !== 'ENOENT') throw error;
+      missing.push(current);
+      const parent = dirname(current);
+      if (parent === current) unsafeManagedPath(current, 'could not resolve a managed directory ancestor');
+      current = parent;
+    }
+  }
+  for (const path of missing.reverse()) {
+    try { mkdirSync(path); }
+    catch (error) { if (error?.code !== 'EEXIST') throw error; }
+    const stat = lstatSync(path);
+    if (stat.isSymbolicLink() || !stat.isDirectory()) unsafeManagedPath(path, 'managed directory changed while being created');
+  }
+}
+
+function assertSafeManagedFileDestination(path) {
+  try {
+    const stat = lstatSync(path);
+    if (stat.isSymbolicLink() || !stat.isFile() || stat.nlink !== 1) {
+      unsafeManagedPath(path, 'managed file destination must be a single-link regular file');
+    }
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+  }
+}
+
+function writeSafeManagedFile(path, content, encoding) {
+  assertSafeManagedFileDestination(path);
+  writeFileSync(path, content, encoding);
+}
+
+function copySafeManagedFile(source, destination) {
+  assertSafeManagedFileDestination(destination);
+  copyFileSync(source, destination);
+}
+
 /**
  * Recursively copy CLI source (excluding tests, node_modules, hidden files).
  * Used to bundle the CLI source into the user's .chati.dev/_cli/ folder so
@@ -968,7 +1059,7 @@ function createDir(dir) {
  */
 export function copyCliSource(srcDir, destDir) {
   if (!existsSync(srcDir)) return;
-  createDir(destDir);
+  createSafeManagedDirectory(destDir);
   const entries = readdirSync(srcDir);
   for (const entry of entries) {
     if (entry.startsWith('.')) continue;
@@ -980,7 +1071,7 @@ export function copyCliSource(srcDir, destDir) {
     if (stat.isDirectory()) {
       copyCliSource(srcPath, destPath);
     } else {
-      copyFileSync(srcPath, destPath);
+      copySafeManagedFile(srcPath, destPath);
     }
   }
 }
@@ -990,7 +1081,7 @@ export function copyCliSource(srcDir, destDir) {
  */
 function copyDirVerbatim(srcDir, destDir) {
   if (!existsSync(srcDir)) return;
-  createDir(destDir);
+  createSafeManagedDirectory(destDir);
   for (const entry of readdirSync(srcDir)) {
     const srcPath = join(srcDir, entry);
     const destPath = join(destDir, entry);
@@ -999,7 +1090,11 @@ function copyDirVerbatim(srcDir, destDir) {
     if (stat.isDirectory()) {
       copyDirVerbatim(srcPath, destPath);
     } else {
-      try { copyFileSync(srcPath, destPath); } catch { /* skip unreadable */ }
+      try { copySafeManagedFile(srcPath, destPath); }
+      catch (error) {
+        if (error?.code === 'UNSAFE_INSTALLATION_TARGET') throw error;
+        /* skip unreadable source material */
+      }
     }
   }
 }
@@ -1027,7 +1122,7 @@ export function copyCliDependencies(pkgDir, destNodeModules) {
   // Resolve each dep from the package.json location (works for hoisted + nested layouts).
    
   const require = createRequire(join(pkgDir, 'package.json'));
-  createDir(destNodeModules);
+  createSafeManagedDirectory(destNodeModules);
 
   const visited = new Set();
   const queue = [...deps];

package/src/installer/manifest.js

@@ -1,5 +1,7 @@
-import { readFileSync, writeFileSync, existsSync, statSync, mkdirSync } from 'fs';
-import { join, dirname } from 'path';
+import {
+  readFileSync, writeFileSync, existsSync, statSync, lstatSync, mkdirSync, readdirSync,
+} from 'fs';
+import { join, dirname, posix } from 'path';
 import { fileURLToPath } from 'url';
 import { verify as cryptoVerify, createPublicKey } from 'crypto';
 import { hashFile } from './file-hasher.js';
@@ -139,15 +141,144 @@ export function compareManifests(oldManifest, newManifest) {
  * @returns {{ valid: boolean, reason: string }}
  */
 export function verifyManifest(manifest, signatureBase64, publicKeyPem = null) {
-  // publicKeyPem is a test seam: production callers use the embedded key.
-  const key = publicKeyPem ? createPublicKey(publicKeyPem) : SIGNING_PUBLIC_KEY;
-  if (!key) return { valid: false, reason: 'no-public-key' };
+  try {
+    // publicKeyPem is a test seam: production callers use the embedded key.
+    const key = publicKeyPem ? createPublicKey(publicKeyPem) : SIGNING_PUBLIC_KEY;
+    if (!key) return { valid: false, reason: 'no-public-key' };
+    if (typeof signatureBase64 !== 'string'
+      || !/^[A-Za-z0-9+/]+={0,2}$/.test(signatureBase64)
+      || Buffer.from(signatureBase64, 'base64').length !== 64) {
+      return { valid: false, reason: 'invalid-signature-encoding' };
+    }
+
+    const manifestJson = serializeManifest(manifest);
+    const signature = Buffer.from(signatureBase64, 'base64');
+    const valid = cryptoVerify(null, Buffer.from(manifestJson), key, signature);
+    return { valid, reason: valid ? 'ok' : 'signature-mismatch' };
+  } catch {
+    return { valid: false, reason: 'manifest-verification-error' };
+  }
+}
+
+function isCanonicalManifestPath(filePath) {
+  return typeof filePath === 'string'
+    && filePath.length > 0
+    && !filePath.includes('\\')
+    && !filePath.includes('\0')
+    && !posix.isAbsolute(filePath)
+    && posix.normalize(filePath) === filePath
+    && filePath !== '.'
+    && !filePath.startsWith('../')
+    && !['manifest.json', 'manifest.sig'].includes(filePath);
+}
+
+function collectFrameworkFiles(rootDir) {
+  const files = new Map();
+
+  function walk(directory, segments = []) {
+    const entries = readdirSync(directory, { withFileTypes: true })
+      .sort((left, right) => left.name.localeCompare(right.name));
+    for (const entry of entries) {
+      if (segments.length === 0 && ['manifest.json', 'manifest.sig'].includes(entry.name)) continue;
+      const entrySegments = [...segments, entry.name];
+      const relativePath = entrySegments.join('/');
+      const absolutePath = join(rootDir, ...entrySegments);
+      const stat = lstatSync(absolutePath);
+      if (stat.isSymbolicLink()) return { valid: false, reason: 'framework-symlink', file: relativePath };
+      if (stat.isDirectory()) {
+        const nested = walk(absolutePath, entrySegments);
+        if (!nested.valid) return nested;
+      } else if (stat.isFile()) {
+        if (stat.nlink !== 1) return { valid: false, reason: 'framework-hardlink', file: relativePath };
+        files.set(relativePath, { absolutePath, stat });
+      } else {
+        return { valid: false, reason: 'framework-special-file', file: relativePath };
+      }
+    }
+    return { valid: true };
+  }
 
-  const manifestJson = serializeManifest(manifest);
-  const signature = Buffer.from(signatureBase64, 'base64');
+  const rootStat = lstatSync(rootDir);
+  if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) {
+    return { valid: false, reason: 'invalid-framework-root', files };
+  }
+  const result = walk(rootDir);
+  return { ...result, files };
+}
+
+/**
+ * Verify that the signed manifest covers the exact framework file set and
+ * that every signed size/hash still matches the bytes about to be installed.
+ */
+export function verifyManifestFiles(rootDir, manifest) {
+  if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)
+    || !manifest.files || typeof manifest.files !== 'object' || Array.isArray(manifest.files)) {
+    return { valid: false, reason: 'invalid-manifest-schema' };
+  }
 
-  const valid = cryptoVerify(null, Buffer.from(manifestJson), key, signature);
-  return { valid, reason: valid ? 'ok' : 'signature-mismatch' };
+  const expected = new Map();
+  for (const [filePath, record] of Object.entries(manifest.files)) {
+    if (!isCanonicalManifestPath(filePath)) {
+      return { valid: false, reason: 'unsafe-manifest-path', file: filePath };
+    }
+    if (!record || typeof record !== 'object' || Array.isArray(record)
+      || !/^[a-f0-9]{64}$/.test(record.hash)
+      || !Number.isSafeInteger(record.size) || record.size < 0
+      || typeof record.type !== 'string') {
+      return { valid: false, reason: 'invalid-manifest-record', file: filePath };
+    }
+    expected.set(filePath, record);
+  }
+
+  let collected;
+  try { collected = collectFrameworkFiles(rootDir); }
+  catch (error) {
+    return { valid: false, reason: 'framework-read-error', detail: error.message };
+  }
+  if (!collected.valid) return collected;
+
+  for (const filePath of expected.keys()) {
+    if (!collected.files.has(filePath)) return { valid: false, reason: 'manifest-file-missing', file: filePath };
+  }
+  for (const filePath of collected.files.keys()) {
+    if (!expected.has(filePath)) return { valid: false, reason: 'unsigned-framework-file', file: filePath };
+  }
+
+  for (const [filePath, record] of expected) {
+    const actual = collected.files.get(filePath);
+    if (actual.stat.size !== record.size) return { valid: false, reason: 'framework-size-mismatch', file: filePath };
+    try {
+      if (hashFile(actual.absolutePath) !== record.hash) {
+        return { valid: false, reason: 'framework-hash-mismatch', file: filePath };
+      }
+    } catch (error) {
+      return { valid: false, reason: 'framework-read-error', file: filePath, detail: error.message };
+    }
+  }
+  return { valid: true, reason: 'ok', fileCount: expected.size };
+}
+
+/** Verify the complete signed framework source before the installer writes. */
+export function verifyFrameworkSource(rootDir, { publicKeyPem = null, expectedVersion = null } = {}) {
+  const manifestPath = join(rootDir, 'manifest.json');
+  const signaturePath = join(rootDir, 'manifest.sig');
+  if (!existsSync(manifestPath)) return { valid: false, reason: 'manifest-missing' };
+  if (!existsSync(signaturePath)) return { valid: false, reason: 'signature-missing' };
+
+  let manifest;
+  let signature;
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    signature = readFileSync(signaturePath, 'utf8').trim();
+  } catch (error) {
+    return { valid: false, reason: 'manifest-read-error', detail: error.message };
+  }
+  const signatureResult = verifyManifest(manifest, signature, publicKeyPem);
+  if (!signatureResult.valid) return signatureResult;
+  if (expectedVersion !== null && manifest.version !== expectedVersion) {
+    return { valid: false, reason: 'manifest-version-mismatch' };
+  }
+  return verifyManifestFiles(rootDir, manifest);
 }
 
 /**