chati-dev 4.3.0 → 4.4.0

package/src/executors/runner.js

@@ -0,0 +1,204 @@
+/**
+ * @fileoverview Execution-kind runner for deterministic, zero-LLM script tasks.
+ *
+ * When a task declares `execution_kind: script` (and the execution_kinds feature
+ * flag is on), the orchestrator runs it here instead of spawning an agent. The
+ * runner resolves the executor from chati.dev/executors/registry.yaml, spawns it
+ * as a child process under the executor contract (JSON request on stdin, JSON
+ * result on stdout), enforces a timeout, and shapes a synthetic handoff so the
+ * pipeline continues exactly as it would after an agent.
+ *
+ * Contract result: { status: 'passed'|'failed'|'error', summary, details }.
+ *   passed  -> the task is done; advance.
+ *   failed  -> the deterministic check is negative; route to dev (CODE fault).
+ *   error   -> the executor could not run; surface to the human.
+ */
+
+import { spawn } from 'child_process';
+import { existsSync, readFileSync } from 'fs';
+import { join, resolve, sep } from 'path';
+import yaml from 'js-yaml';
+import { resolveFrameworkDir } from '../utils/framework-dir.js';
+
+/**
+ * Split an execution_ref into executor id and argument. The split is on the
+ * FIRST colon, so an argument may itself contain colons.
+ *
+ * @param {string} ref - e.g. "npm-script:test" or "path-check:dist,build"
+ * @returns {{ id: string, arg: string }}
+ */
+export function parseExecutionRef(ref) {
+  const s = String(ref || '').trim();
+  if (!s) return { id: '', arg: '' };
+  const i = s.indexOf(':');
+  if (i === -1) return { id: s, arg: '' };
+  return { id: s.slice(0, i).trim(), arg: s.slice(i + 1).trim() };
+}
+
+/**
+ * Load and parse the executor registry for a project.
+ *
+ * @param {string} projectDir
+ * @returns {{ version?: string, executors: Record<string, {path:string, description?:string, timeout_ms?:number}> }}
+ */
+export function loadExecutorRegistry(projectDir) {
+  const path = join(projectDir, resolveFrameworkDir(projectDir), 'executors', 'registry.yaml');
+  if (!existsSync(path)) return { executors: {} };
+  try {
+    const parsed = yaml.load(readFileSync(path, 'utf-8'));
+    return parsed && typeof parsed === 'object' ? { executors: {}, ...parsed } : { executors: {} };
+  } catch {
+    return { executors: {} };
+  }
+}
+
+/**
+ * Spawn an executor script, feed it the JSON request, and resolve its JSON
+ * result. Never rejects: a spawn failure, a timeout, or non-JSON output all
+ * resolve to a structured `error` result.
+ *
+ * @param {string} execPath - absolute path to the executor script
+ * @param {string} request - JSON string written to the executor's stdin
+ * @param {number} timeoutMs
+ * @returns {Promise<{status:string, summary:string, details?:object}>}
+ */
+function spawnExecutor(execPath, request, timeoutMs) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (r) => { if (!settled) { settled = true; resolve(r); } };
+
+    const child = spawn(process.execPath, [execPath], { shell: false });
+    let out = '';
+    let err = '';
+
+    const timer = setTimeout(() => {
+      child.kill('SIGKILL');
+      done({ status: 'error', summary: `Executor timed out after ${timeoutMs}ms.` });
+    }, timeoutMs);
+
+    child.stdout.on('data', (c) => { out += c; });
+    child.stderr.on('data', (c) => { err += c; });
+    child.on('error', (e) => {
+      clearTimeout(timer);
+      done({ status: 'error', summary: `Executor could not be spawned: ${e.message}.` });
+    });
+    child.on('close', () => {
+      clearTimeout(timer);
+      try {
+        const parsed = JSON.parse(out.trim());
+        if (!parsed || typeof parsed !== 'object' || !parsed.status) {
+          done({ status: 'error', summary: 'Executor returned JSON without a status field.', details: { stdout: out.slice(0, 500) } });
+          return;
+        }
+        done(parsed);
+      } catch {
+        done({ status: 'error', summary: 'Executor did not return valid JSON.', details: { stdout: out.slice(0, 500), stderr: err.slice(0, 500) } });
+      }
+    });
+
+    child.stdin.write(request);
+    child.stdin.end();
+  });
+}
+
+/**
+ * Run a `script` task through its executor.
+ *
+ * @param {string} projectDir
+ * @param {{id?:string, title?:string, execution_ref?:string}} task
+ * @returns {Promise<{executor:string, arg:string, status:string, summary:string, details?:object, durationMs:number}>}
+ */
+export async function runScriptTask(projectDir, task) {
+  const startedAt = Date.now();
+  const ref = task?.execution_ref || '';
+  const { id, arg } = parseExecutionRef(ref);
+
+  const wrap = (r) => ({ executor: id, arg, durationMs: Date.now() - startedAt, ...r });
+
+  if (!id) {
+    return wrap({ status: 'error', summary: 'Script task has no execution_ref (expected "executor-id:arg").' });
+  }
+
+  const registry = loadExecutorRegistry(projectDir);
+  const entry = registry.executors?.[id];
+  if (!entry) {
+    const known = Object.keys(registry.executors || {}).join(', ') || '(none)';
+    return wrap({ status: 'error', summary: `No executor "${id}" in the registry. Known: ${known}.` });
+  }
+
+  const execRoot = join(projectDir, resolveFrameworkDir(projectDir), 'executors');
+  const execPath = join(projectDir, resolveFrameworkDir(projectDir), entry.path);
+  // Containment: a tampered or supply-chain-compromised registry must not point
+  // the runner at a file outside the framework's executors directory.
+  const resolvedExec = resolve(execPath);
+  const resolvedRoot = resolve(execRoot);
+  if (resolvedExec !== resolvedRoot && !resolvedExec.startsWith(resolvedRoot + sep)) {
+    return wrap({ status: 'error', summary: `Executor path "${entry.path}" is outside the executors directory and was refused.` });
+  }
+  if (!existsSync(execPath)) {
+    return wrap({ status: 'error', summary: `Executor file is missing: ${entry.path}.` });
+  }
+
+  const request = JSON.stringify({
+    task: { id: task.id, title: task.title, execution_ref: ref },
+    projectDir,
+    arg,
+  });
+
+  const result = await spawnExecutor(execPath, request, entry.timeout_ms || 60000);
+  return wrap(result);
+}
+
+/**
+ * Shape a synthetic handoff for a completed script task so the pipeline reads it
+ * the same way it reads an agent handoff.
+ *
+ * @param {{id?:string, title?:string}} task
+ * @param {{executor:string, arg:string, status:string, summary:string, details?:object, durationMs:number}} result
+ * @param {string} [timestamp] - ISO timestamp (caller supplies; the runner does not read the clock for handoff text)
+ * @returns {string} handoff markdown
+ */
+export function formatScriptHandoff(task, result, timestamp) {
+  const status = result.status === 'passed' ? 'completed'
+    : result.status === 'failed' ? 'blocked'
+    : 'error';
+  const score = result.status === 'passed' ? 100 : 0;
+  // failed is a real negative result routed to dev (CODE). An error means the
+  // executor could not run; that is surfaced to the human, not backlogged, so it
+  // carries no fault_origin (DEFER would wrongly signal "out of scope").
+  const faultOrigin = result.status === 'failed' ? 'CODE' : null;
+
+  const lines = [];
+  lines.push('---');
+  lines.push(`task: ${task?.id || '(unknown)'}`);
+  lines.push('execution_kind: script');
+  lines.push(`executor: ${result.executor}${result.arg ? `:${result.arg}` : ''}`);
+  lines.push(`status: ${status}`);
+  lines.push(`score: ${score}`);
+  if (faultOrigin) lines.push(`fault_origin: ${faultOrigin}`);
+  if (timestamp) lines.push(`completed_at: ${timestamp}`);
+  lines.push('---');
+  lines.push('');
+  lines.push(`# Script task ${task?.id || ''}: ${task?.title || ''}`.trim());
+  lines.push('');
+  lines.push(`Ran deterministically with no LLM call (executor \`${result.executor}\`, ${result.durationMs}ms).`);
+  lines.push('');
+  lines.push('## Summary');
+  lines.push('');
+  lines.push(result.summary || 'Script task completed.');
+  if (result.details) {
+    lines.push('');
+    lines.push('```json');
+    lines.push(JSON.stringify(result.details, null, 2));
+    lines.push('```');
+  }
+  if (result.status === 'failed') {
+    lines.push('');
+    lines.push('The deterministic check is negative. Route to dev for a fix (Fault Vector Protocol: CODE), then re-run the script task.');
+  } else if (result.status === 'error') {
+    lines.push('');
+    lines.push('The executor could not run. Surface to the human: check the execution_ref and the executor registry.');
+  }
+  lines.push('');
+  return lines.join('\n');
+}

package/src/installer/core.js

@@ -147,6 +147,15 @@ export async function installFramework(config) {
     join(frameworkDir, '_cli', 'node_modules')      // .chati.dev/_cli/node_modules/
   );
 
+  // v4.3.1+ — Write version stamp so chati-router.js can detect bundle/canonical
+  // mismatch on subsequent invocations. Pre-v4.3.1 installs lack this file;
+  // mismatch detection silent-skips when it's missing (graceful degradation).
+  writeFileSync(
+    join(frameworkDir, '_cli', 'version.json'),
+    JSON.stringify({ version, bundled_at: new Date().toISOString() }, null, 2),
+    'utf-8'
+  );
+
   // Write config.yaml
   writeFileSync(
     join(frameworkDir, 'config.yaml'),
@@ -235,6 +244,7 @@ const FRAMEWORK_DIRS_TO_COPY = [
   'presets',
   'scripts',
   'scaffold',
+  'executors',
 ];
 
 /**
@@ -701,7 +711,7 @@ function createDir(dir) {
  * Used to bundle the CLI source into the user's .chati.dev/_cli/ folder so
  * the framework runs self-contained (no `npx chati-dev` dependency).
  */
-function copyCliSource(srcDir, destDir) {
+export function copyCliSource(srcDir, destDir) {
   if (!existsSync(srcDir)) return;
   createDir(destDir);
   const entries = readdirSync(srcDir);
@@ -748,7 +758,7 @@ function copyDirVerbatim(srcDir, destDir) {
  * which works whether the package is hoisted or nested in the user's
  * node_modules (npx cache, npm install, etc.).
  */
-function copyCliDependencies(pkgDir, destNodeModules) {
+export function copyCliDependencies(pkgDir, destNodeModules) {
   let pkg;
   try {
     pkg = JSON.parse(readFileSync(join(pkgDir, 'package.json'), 'utf-8'));
@@ -760,7 +770,7 @@ function copyCliDependencies(pkgDir, destNodeModules) {
   if (deps.length === 0) return;
 
   // Resolve each dep from the package.json location (works for hoisted + nested layouts).
-  // eslint-disable-next-line no-undef
+   
   const require = createRequire(join(pkgDir, 'package.json'));
   createDir(destNodeModules);
 

package/src/installer/templates.js

@@ -130,7 +130,6 @@ export function generateConfigYaml(config) {
     rate_limiter_integration: true,
     l5_keywords: true,
     prompt_size_guard: true,
-    ids_decision_engine: true,
     surface_criteria: true,
     parallel_fallback: true,
     tool_mesh: true,
@@ -219,7 +218,7 @@ description: >
 
 # Chati.dev Orchestrator
 
-## CRITICAL — Language Override
+## CRITICAL: Language Override
 
 Read \`.chati/session.yaml\` field \`language\` BEFORE anything else.
 ALL responses MUST be in this language. This overrides any global setting.
@@ -236,14 +235,14 @@ If session.yaml does not exist or has no language field, default to English.
 ## Load
 
 The orchestrator and all agent files are **pre-configured for Codex CLI**.
-No translation needed — follow all instructions as written.
+No translation needed; follow all instructions as written.
 
 Read and execute the full orchestrator at \`${orchPath}\`.
 
 **NEVER create or reference CLAUDE.md, CLAUDE.local.md, or .claude/ directories.**
 
 **Context to pass:**
-- \`.chati/session.yaml\` (session state — includes language)
+- \`.chati/session.yaml\` (session state, includes language)
 - \`AGENTS.md\` (project context)
 - \`artifacts/handoffs/\` (latest handoff)
 - \`.chati.dev/config.yaml\` (version info)
@@ -265,13 +264,13 @@ ALL responses MUST be in this language (en, pt, es, fr).
 If session.yaml does not exist or has no language field, default to English.
 
 The orchestrator and all agent files are pre-configured for Gemini CLI.
-No translation needed — follow all instructions as written.
+No translation needed; follow all instructions as written.
 
 Read and execute the full orchestrator at ${orchPath}.
 NEVER create or reference CLAUDE.md, CLAUDE.local.md, or .claude/ directories.
 
 Context to load:
-- .chati/session.yaml (session state — includes language)
+- .chati/session.yaml (session state, includes language)
 - GEMINI.md (project context)
 - artifacts/handoffs/ (latest handoff)
 - .chati.dev/config.yaml (version info)

package/src/intelligence/registry-manager.js

@@ -144,7 +144,7 @@ export function runHealthCheck(targetDir) {
     const content = readFileSync(constitutionPath, 'utf-8');
     const articleCount = (content.match(/^## Article/gm) || []).length;
     checks.constitution.pass = articleCount >= 22;
-    checks.constitution.details = `${articleCount}/23 articles`;
+    checks.constitution.details = `${articleCount} articles`;
   } else {
     checks.constitution.details = 'Not found';
   }

package/src/license/client.js

@@ -1,5 +1,5 @@
 import { homedir } from 'os';
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync } from 'fs';
 import { join } from 'path';
 import yaml from 'js-yaml';
 import { getMachineId, getMachineName } from './machine-id.js';
@@ -27,8 +27,14 @@ function readGlobal() {
 }
 
 function writeGlobal(data) {
-  mkdirSync(getGlobalDir(), { recursive: true });
-  writeFileSync(getGlobalLicensePath(), yaml.dump(data, { lineWidth: -1 }));
+  const dir = getGlobalDir();
+  const path = getGlobalLicensePath();
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(path, yaml.dump(data, { lineWidth: -1 }));
+  // Restrict to owner read/write only (0o600). On multi-user machines this
+  // prevents other local users from reading the license key from the
+  // world-readable default. POSIX-only; chmodSync is a no-op on Windows.
+  try { chmodSync(path, 0o600); } catch { /* non-POSIX FS — skip silently */ }
 }
 
 // ---------------------------------------------------------------------------

package/src/license/commands.js

@@ -10,6 +10,15 @@ import { activateLicense, deactivateLicense, getLicenseKey, getLicenseStatus, va
 // activate
 // ---------------------------------------------------------------------------
 
+/**
+ * Run the interactive license activation flow.
+ *
+ * Returns `{ ok: boolean, cancelled?: boolean, plan?, days?, error? }`.
+ * On failure this function does NOT call `process.exit` — callers (typically
+ * `bin/chati.js`) decide whether to exit non-zero based on the returned `ok`
+ * flag. This keeps the function unit-testable and reusable from programmatic
+ * call sites.
+ */
 export async function runActivate(projectDir, keyArg) {
   let key = keyArg;
 
@@ -25,7 +34,7 @@ export async function runActivate(projectDir, keyArg) {
     });
     if (isCancel(input)) {
       console.log('Activation cancelled.');
-      return;
+      return { ok: false, cancelled: true };
     }
     key = input.trim();
   }
@@ -39,10 +48,11 @@ export async function runActivate(projectDir, keyArg) {
     console.log(`\n✓ Activated! Plan: ${plan} — ${days} day(s) remaining.`);
     console.log(`  Key saved to ~/.chati-dev/license.yaml`);
     console.log(`  Run /chati to start.\n`);
+    return { ok: true, plan, days };
   } catch (err) {
     console.error(`\n✗ Activation failed: ${err.message}`);
     console.error(`  Visit https://chati.dev/pricing to get a key.\n`);
-    process.exit(1);
+    return { ok: false, error: err.message };
   }
 }
 

package/src/license/machine-id.js

@@ -1,9 +1,49 @@
 import os from 'os';
 import crypto from 'crypto';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync } from 'fs';
+import { join } from 'path';
+
+const PERSISTENT_ID_FILE = '.chati-dev/machine-id';
+
+/**
+ * Read or mint a persistent random per-installation salt at
+ * `~/.chati-dev/machine-id`. Used to disambiguate machines that share
+ * everything OS-visible (hostname, platform, arch, CPU, username, MAC) —
+ * e.g. virtual machines or containers with no external NIC where the prior
+ * `'no-mac'` fallback collapsed many machines onto a single fingerprint.
+ *
+ * The file is created lazily on first call. Format is a single 32-hex-char
+ * string with mode 0600 so other local users cannot read it.
+ */
+function getPersistentSalt() {
+  const path = join(os.homedir(), PERSISTENT_ID_FILE);
+  try {
+    if (existsSync(path)) {
+      const raw = readFileSync(path, 'utf-8').trim();
+      if (/^[0-9a-f]{16,}$/i.test(raw)) return raw;
+    }
+  } catch { /* fall through to mint */ }
+  // Mint a new salt.
+  try {
+    const salt = crypto.randomBytes(16).toString('hex');
+    mkdirSync(join(os.homedir(), '.chati-dev'), { recursive: true });
+    writeFileSync(path, salt);
+    try { chmodSync(path, 0o600); } catch { /* non-POSIX FS — skip */ }
+    return salt;
+  } catch {
+    // FS write failed (read-only homedir?). Return a deterministic-empty
+    // string — fingerprint then falls back to the OS-visible properties
+    // only, matching pre-fix behaviour rather than crashing.
+    return '';
+  }
+}
 
 /**
  * Generates a stable 16-char machine fingerprint.
- * Based on: hostname, platform, arch, CPU model, username, MAC address.
+ * Inputs: hostname, platform, arch, CPU model, username, MAC address, and a
+ * persistent random per-installation salt (see getPersistentSalt). The salt
+ * eliminates fingerprint collisions on VMs/containers that share all
+ * OS-visible properties and report `'no-mac'`.
  */
 export function getMachineId() {
   const ifaces = Object.values(os.networkInterfaces()).flat();
@@ -15,6 +55,7 @@ export function getMachineId() {
     os.cpus()[0]?.model ?? '',
     os.userInfo().username,
     mac,
+    getPersistentSalt(),
   ].join('|');
   return crypto.createHash('sha256').update(raw).digest('hex').substring(0, 16);
 }

package/src/memory/gotchas.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
 import { join, dirname } from 'path';
 import { createHash } from 'crypto';
+import { acquireLock } from '../utils/file-lock.js';
 
 const GOTCHAS_FILE = '.chati/memories/shared/gotchas.json';
 const ERROR_LOG_FILE = '.chati/memories/shared/error-log.json';
@@ -203,53 +204,70 @@ export function recordError(projectDir, error) {
   });
 
   if (recentErrors.length >= ERROR_PATTERN_THRESHOLD) {
-    // Promote to gotcha
-    const gotchas = loadGotchas(projectDir);
-
-    // Check if already exists
-    const existingGotcha = gotchas.find(g => g.pattern === hash);
+    // Promote to gotcha — read-then-write must be atomic across concurrent
+    // agents. Without a lock two parallel terminals can both compute the
+    // same next ID (G001, G002, …) and overwrite each other's entry, since
+    // generateGotchaId() picks max+1 by scanning the file. Hold an advisory
+    // lock on the gotchas file for the full read-modify-write window.
+    const gotchasPath = join(projectDir, GOTCHAS_FILE);
+    const dir = dirname(gotchasPath);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    const lock = acquireLock(gotchasPath, { timeout: 5000 });
+    if (!lock.acquired) {
+      // Degraded path: still record but skip promotion. Avoids hanging on a
+      // stale lock during pipeline execution.
+      return { recorded: true, promoted: false, gotcha: null };
+    }
+    try {
+      const gotchas = loadGotchas(projectDir);
+
+      // Check if already exists
+      const existingGotcha = gotchas.find(g => g.pattern === hash);
+
+      if (existingGotcha) {
+        // Update existing gotcha
+        existingGotcha.count = recentErrors.length;
+        existingGotcha.last_seen = timestamp;
+        saveGotchas(projectDir, gotchas);
+
+        return {
+          recorded: true,
+          promoted: false,
+          gotcha: existingGotcha,
+        };
+      }
+
+      // Create new gotcha
+      const gotchaId = generateGotchaId(gotchas);
+      const classification = classifyError(message);
+      const newGotcha = {
+        id: gotchaId,
+        pattern: hash,
+        message: normalizeErrorMessage(message),
+        original_message: message,
+        agent,
+        task,
+        count: recentErrors.length,
+        first_seen: recentErrors[0].timestamp,
+        last_seen: timestamp,
+        promoted_at: timestamp,
+        resolution: null,
+        category: classification.category,
+        severity: classification.severity,
+        context,
+      };
 
-    if (existingGotcha) {
-      // Update existing gotcha
-      existingGotcha.count = recentErrors.length;
-      existingGotcha.last_seen = timestamp;
+      gotchas.push(newGotcha);
       saveGotchas(projectDir, gotchas);
 
       return {
         recorded: true,
-        promoted: false,
-        gotcha: existingGotcha,
+        promoted: true,
+        gotcha: newGotcha,
       };
+    } finally {
+      lock.release();
     }
-
-    // Create new gotcha
-    const gotchaId = generateGotchaId(gotchas);
-    const classification = classifyError(message);
-    const newGotcha = {
-      id: gotchaId,
-      pattern: hash,
-      message: normalizeErrorMessage(message),
-      original_message: message,
-      agent,
-      task,
-      count: recentErrors.length,
-      first_seen: recentErrors[0].timestamp,
-      last_seen: timestamp,
-      promoted_at: timestamp,
-      resolution: null,
-      category: classification.category,
-      severity: classification.severity,
-      context,
-    };
-
-    gotchas.push(newGotcha);
-    saveGotchas(projectDir, gotchas);
-
-    return {
-      recorded: true,
-      promoted: true,
-      gotcha: newGotcha,
-    };
   }
 
   return {

package/src/memory/magic-docs.js

@@ -44,7 +44,7 @@ export function updateClaudeMd(projectDir, context = {}) {
     lines.push('');
     lines.push('### Recent Decisions');
     for (const d of context.decisions.slice(0, 5)) {
-      const text = typeof d === 'object' ? `${d.what} — ${d.why}` : String(d);
+      const text = typeof d === 'object' ? `${d.what}: ${d.why}` : String(d);
       lines.push(`- ${text}`);
     }
   }

package/src/memory/session-digest.js

@@ -177,18 +177,23 @@ export function buildStructuredDigest(projectDir, sessionState, enrichment = {})
     },
   };
 
-  // Final budget enforcement — iterative truncation until within budget
+  // Final budget enforcement — iterative truncation until within budget.
+  // Cache `JSON.stringify(digest).length` and refresh only after a real
+  // mutation; the prior implementation serialised the entire object twice
+  // per iteration, which became expensive for large sessions.
   const truncOrder = ['next_steps', 'gotchas_found', 'files_changed', 'blockers', 'decisions_made'];
+  const measure = () => JSON.stringify(digest).length;
+  let size = measure();
   let pass = 0;
-  while (JSON.stringify(digest).length > MAX_STRUCTURED_CHARS && pass < truncOrder.length) {
+  while (size > MAX_STRUCTURED_CHARS && pass < truncOrder.length) {
     const field = truncOrder[pass];
     if (Array.isArray(digest[field]) && digest[field].length > 1) {
       digest[field] = digest[field].slice(0, Math.max(1, Math.ceil(digest[field].length / 2)));
+      size = measure();
+      if (size > MAX_STRUCTURED_CHARS) pass++; // still too big — move on
     } else {
       pass++;
     }
-    // If we halved and still too big, move to next field
-    if (JSON.stringify(digest).length > MAX_STRUCTURED_CHARS) pass++;
   }
 
   return digest;