chati-dev 4.3.1 → 4.4.0

package/framework/executors/registry.yaml

@@ -0,0 +1,36 @@
+# Executor Registry - deterministic, zero-LLM task executors.
+#
+# Each executor is a standalone Node script that reads a JSON request on stdin
+# and writes a JSON result on stdout. The runner (packages/chati-dev/src/
+# executors/runner.js) resolves an executor by id, spawns it, enforces a
+# timeout, and writes a synthetic handoff. Executors run ONLY when a task
+# declares execution_kind: script AND the execution_kinds feature flag is on.
+#
+# Contract:
+#   stdin   {"task": {id, title, execution_ref}, "projectDir": "...", "arg": "..."}
+#   stdout  {"status": "passed" | "failed" | "error", "summary": "...", "details": {...}}
+#   arg     the part after the first colon in execution_ref
+#           (e.g. "npm-script:test" resolves executor "npm-script", arg "test").
+#   status  passed = the deterministic check succeeded;
+#           failed  = it ran and the result is negative (route to dev);
+#           error   = the executor could not run (bad arg, spawn failure).
+#
+# Adding an executor: write a standalone script under executors/, register it
+# here with a path and a timeout, and cover it with a test. Executors must be
+# deterministic, side-effect-light, and never call an LLM.
+
+version: "1.0.0"
+
+executors:
+  npm-script:
+    path: executors/npm-script.js
+    description: "Run a project npm script and report deterministic pass/fail. arg is the script name; only lint, test, typecheck, build, and format are allowed (no arbitrary or long-running commands)."
+    timeout_ms: 600000
+  path-check:
+    path: executors/path-check.js
+    description: "Assert that one or more paths exist (a deterministic verification gate). arg is a comma-separated list of project-relative paths."
+    timeout_ms: 30000
+  json-validate:
+    path: executors/json-validate.js
+    description: "Parse JSON files and report any that are malformed (a deterministic well-formedness check). arg is a comma-separated list of project-relative .json paths."
+    timeout_ms: 60000

package/framework/hooks/advance-trigger.js

@@ -17,10 +17,33 @@
  * ignored so it outlives the hook process.
  */
 
-import { existsSync, readFileSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
 import { join } from 'path';
 import { spawn } from 'child_process';
 
+// Canonical gate thresholds live in data/qa-rubrics.yaml. These literals are
+// only a last-resort fallback for when that file is briefly unavailable (for
+// example mid-upgrade); they must match the YAML.
+const FALLBACK_QA_THRESHOLDS = { 'qa-planning': 95, 'qa-implementation': 95, 'qa-visual': 90 };
+
+function loadQaThresholds(cwd) {
+  const candidates = [
+    join(cwd, '.chati.dev', 'data', 'qa-rubrics.yaml'),
+    join(cwd, 'chati.dev', 'data', 'qa-rubrics.yaml'),
+  ];
+  let raw = null;
+  for (const p of candidates) {
+    if (existsSync(p)) { try { raw = readFileSync(p, 'utf-8'); break; } catch { /* fall through */ } }
+  }
+  if (!raw) return { ...FALLBACK_QA_THRESHOLDS };
+  const out = {};
+  for (const key of Object.keys(FALLBACK_QA_THRESHOLDS)) {
+    const m = raw.match(new RegExp(`^\\s*${key}:\\s*(\\d+)`, 'm'));
+    out[key] = m ? parseInt(m[1], 10) : FALLBACK_QA_THRESHOLDS[key];
+  }
+  return out;
+}
+
 async function readStdin() {
   let data = '';
   for await (const chunk of process.stdin) data += chunk;
@@ -95,7 +118,7 @@ async function main() {
 
   // Decide whether to fire under interactive mode.
   if (profile !== 'autonomous') {
-    const QA_THRESHOLDS = { 'qa-planning': 95, 'qa-implementation': 95, 'qa-visual': 90 };
+    const QA_THRESHOLDS = loadQaThresholds(cwd);
     const threshold = QA_THRESHOLDS[agent];
     const isQA = threshold !== undefined;
     const verdict = (fm.verdict || '').toUpperCase();
@@ -118,14 +141,35 @@ async function main() {
   if (!routerPath) return;
 
   // Fire and forget: detach so the router outlives this hook process.
+  // A silent spawn failure would stall the pipeline with no signal. Warn on
+  // stderr (Claude Code surfaces it immediately as a non-blocking hook warning)
+  // and drop a durable post-mortem marker in .chati/failures/ for inspection.
+  // The stderr warning is the surfaced signal; nothing scans the marker dir
+  // automatically yet.
+  const recordFailure = (err) => {
+    const msg = (err && err.message) ? err.message : String(err);
+    try {
+      const failuresDir = join(cwd, '.chati', 'failures');
+      mkdirSync(failuresDir, { recursive: true });
+      writeFileSync(
+        join(failuresDir, `advance-${agent}-${Date.now()}.json`),
+        JSON.stringify({ type: 'advance_spawn_failure', agent, score, error: msg, timestamp: new Date().toISOString() }),
+        'utf-8'
+      );
+    } catch { /* truly non-fatal: filesystem unavailable */ }
+    try { process.stderr.write(`[chati] advance-trigger: pipeline advance for "${agent}" failed to spawn: ${msg}\n`); } catch { /* ignore */ }
+  };
   try {
     const child = spawn('node', [routerPath, 'advance', '--agent', agent, '--score', String(score)], {
       cwd,
       detached: true,
       stdio: 'ignore',
     });
+    child.on('error', recordFailure);
     child.unref();
-  } catch { /* non-fatal */ }
+  } catch (err) {
+    recordFailure(err);
+  }
 }
 
 main().catch(() => process.stdout.write('{}\n'));

package/framework/hooks/constitution-guard.js

@@ -137,10 +137,15 @@ async function main() {
 
     process.stdout.write(JSON.stringify(allowOutput()));
   } catch (err) {
-    process.stderr.write(`[chati-hook-error] constitution-guard: ${err?.message || 'unknown'}\n`);
-    // Fail-open on hook errors: a broken hook should not block legitimate work.
-    // Real security checks above are explicit and run before this catch.
-    process.stdout.write(JSON.stringify(allowOutput()));
+    const msg = err?.message || 'unknown';
+    process.stderr.write(`[chati-hook-error] constitution-guard: ${msg}\n`);
+    // Fail CLOSED. A security/integrity guard that crashes must not
+    // silently permit the operation. The cost of a false block (user re-runs)
+    // is far lower than a false pass (a secret leak or governance violation
+    // slipping through). Deny with a clear, actionable reason.
+    process.stdout.write(JSON.stringify(denyOutput(
+      `constitution-guard could not complete its security checks (internal error: ${msg}). The operation was blocked as a precaution. Re-run once resolved, or report this if it keeps happening.`
+    )));
   }
 }
 

package/framework/hooks/git-push-authority.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview Git-push authority hook — PreToolUse (Bash).
+ *
+ * During an active pipeline, only the devops agent may push to a remote or open
+ * a pull request. This stops a non-devops agent (for example dev, mid
+ * implementation) from pushing unreviewed work past the quality gates.
+ *
+ * Scope is deliberately narrow so normal git use is never blocked:
+ *   - it only ever denies push / PR-creation / release-creation commands;
+ *   - it only enforces while a pipeline is active (session.mode is a pipeline
+ *     phase) AND the current agent is set AND is not devops;
+ *   - outside an active session (no session, completed session) it does
+ *     nothing.
+ *
+ * Fails open (with an stderr log) on any internal error: a guard crash must
+ * never block every Bash command.
+ */
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+const PUSH_PATTERNS = [
+  // git push, including global options that carry a value (git -C <path> push,
+  // git -c k=v push) so an agent cannot side-step the guard with -C.
+  /\bgit\s+(?:-{1,2}\S+(?:\s+\S+)?\s+)*push\b/i,
+  /\bgh\s+pr\s+(?:create|merge)\b/i,
+  /\bgh\s+release\s+create\b/i,
+];
+
+// Pipeline phases during which a non-devops agent is actively driving work.
+const ACTIVE_MODES = ['discover', 'plan', 'build', 'validate', 'deploy'];
+
+function isPushCommand(command) {
+  return PUSH_PATTERNS.some((p) => p.test(command || ''));
+}
+
+/**
+ * Block only when a push/PR command runs while a pipeline is active (mode is a
+ * pipeline phase) and the current driver is a non-devops agent.
+ */
+function shouldBlockPush(command, mode, agent) {
+  if (!isPushCommand(command)) return false;
+  return Boolean(mode && ACTIVE_MODES.includes(mode) && agent && agent !== 'devops');
+}
+
+function readSessionField(projectDir, key) {
+  const p = join(projectDir, '.chati', 'session.yaml');
+  if (!existsSync(p)) return null;
+  try {
+    const raw = readFileSync(p, 'utf-8');
+    const m = raw.match(new RegExp(`^\\s*${key}:\\s*(.+)$`, 'm'));
+    if (!m) return null;
+    const v = m[1].trim().replace(/^["']|["']$/g, '');
+    return v === 'null' || v === '' ? null : v;
+  } catch {
+    return null;
+  }
+}
+
+async function main() {
+  let input = '';
+  for await (const chunk of process.stdin) input += chunk;
+
+  try {
+    const event = JSON.parse(input);
+    if ((event.tool_name || '') !== 'Bash') {
+      process.stdout.write('{}');
+      return;
+    }
+    const command = (event.tool_input && event.tool_input.command) || '';
+    if (!isPushCommand(command)) {
+      process.stdout.write('{}');
+      return;
+    }
+
+    const projectDir = event.cwd || process.cwd();
+    const mode = readSessionField(projectDir, 'mode');
+    const agent = readSessionField(projectDir, 'current_agent');
+
+    // Only enforce while a pipeline is active with a non-devops driver.
+    if (shouldBlockPush(command, mode, agent)) {
+      process.stdout.write(JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: 'PreToolUse',
+          permissionDecision: 'deny',
+          permissionDecisionReason: `[Article IV] Only the devops agent may push to a remote or open a pull request during an active pipeline. The current agent is "${agent}". Let the pipeline reach the deploy phase (devops), or run /chati exit to take manual control.`,
+        },
+      }));
+      return;
+    }
+
+    process.stdout.write('{}');
+  } catch (err) {
+    // Fail open: a guard crash must not block every Bash command. Log so the
+    // failure is visible instead of silently disabling enforcement.
+    process.stderr.write(`[chati] git-push-authority error (allowing operation): ${err && err.message ? err.message : err}\n`);
+    process.stdout.write('{}');
+  }
+}
+
+export { PUSH_PATTERNS, ACTIVE_MODES, isPushCommand, shouldBlockPush, readSessionField };
+
+// Only run main when executed directly (not when imported by tests).
+// realpathSync resolves symlinks on both sides (macOS /tmp -> /private/tmp).
+import { fileURLToPath } from 'url';
+import { realpathSync } from 'fs';
+if (process.argv[1]) {
+  try {
+    if (realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
+      main();
+    }
+  } catch { /* path resolution failed — not invoked as a script */ }
+}

package/framework/hooks/license-guard.js

@@ -19,7 +19,7 @@
  * Telemetry pings are owned by session-digest.js (PreCompact event), not here.
  */
 
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
 
@@ -70,9 +70,21 @@ export async function checkLicense() {
   // cache or detects revocation. Network failures NEVER block the user.
   try {
     const machineId = await computeMachineId();
+    // The license key travels in a request header, never in the URL query
+    // string (which lands in server access, CDN and proxy logs in plaintext).
+    // Server contract: POST /license/validate, key in X-License-Key header,
+    // machine_id in the JSON body.
     const res = await fetch(
-      `${API_BASE}/license/validate?key=${encodeURIComponent(licenseKey)}&machine_id=${encodeURIComponent(machineId)}`,
-      { signal: AbortSignal.timeout(5000) }
+      `${API_BASE}/license/validate`,
+      {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-License-Key': licenseKey,
+        },
+        body: JSON.stringify({ machine_id: machineId }),
+        signal: AbortSignal.timeout(5000),
+      }
     );
     const data = await res.json();
 
@@ -89,6 +101,8 @@ export async function checkLicense() {
     };
     mkdirSync(GLOBAL_DIR, { recursive: true });
     writeFileSync(LICENSE_PATH, dumpYaml(updated));
+    // The license file holds the activation key; restrict to owner-only.
+    try { chmodSync(LICENSE_PATH, 0o600); } catch { /* no-op on Windows / read-only FS */ }
 
     if (data.status === 'VALID') return { valid: true, status: 'VALID' };
     return { valid: false, reason: buildMessage(data.status, data.reason), status: data.status };
@@ -138,7 +152,12 @@ async function main() {
         process.exit(2);
       }
     }
-  } catch { /* fail open */
+  } catch (err) {
+    // Fail open by design: a license-guard crash must never brick a paying
+    // user (an unreadable or corrupt license file, a transient FS error). But
+    // it must not be silent: log to stderr so the failure is visible instead
+    // of silently bypassing enforcement.
+    process.stderr.write(`[chati] license-guard error (allowing operation): ${err && err.message ? err.message : err}\n`);
     process.stdout.write(isPreToolUse
       ? JSON.stringify({ hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'allow' } })
       : '{}');
@@ -169,9 +188,26 @@ function buildMessage(status, reason) {
 // YAML helpers (no external deps)
 // ---------------------------------------------------------------------------
 
+/**
+ * Unquote a scalar. Single-quoted values un-double the '' escape; double-quoted
+ * values are taken verbatim; bare values are returned trimmed.
+ */
+function unquoteYaml(s) {
+  s = s.trim();
+  if (s.length >= 2 && s.startsWith("'") && s.endsWith("'")) {
+    return s.slice(1, -1).replace(/''/g, "'");
+  }
+  if (s.length >= 2 && s.startsWith('"') && s.endsWith('"')) {
+    return s.slice(1, -1);
+  }
+  return s;
+}
+
 function readYamlField(raw, field) {
-  const match = raw.match(new RegExp(`^${field}:\\s*(.+)$`, 'm'));
-  return match ? match[1].trim().replace(/^["']|["']$/g, '') : null;
+  const match = raw.match(new RegExp(`^${field}:\\s*(.*)$`, 'm'));
+  if (!match) return null;
+  const value = unquoteYaml(match[1]);
+  return value === '' ? null : value;
 }
 
 /** Minimal YAML object parser for simple key:value files */
@@ -179,15 +215,29 @@ function parseYaml(raw) {
   const obj = {};
   for (const line of raw.split('\n')) {
     const m = line.match(/^(\w+):\s*(.*)$/);
-    if (m) obj[m[1]] = m[2].trim().replace(/^["']|["']$/g, '');
+    if (m) obj[m[1]] = unquoteYaml(m[2]);
   }
   return obj;
 }
 
-/** Minimal YAML serializer for simple flat objects */
+/**
+ * Minimal YAML serializer for simple flat objects.
+ * Single-quotes any value that contains ':', a quote, '#' or surrounding
+ * whitespace, and doubles inner single-quotes ('' is the YAML single-quote
+ * escape). Newlines are collapsed to spaces so a multi-line reason can never
+ * split the record across lines and corrupt later fields. A naive serializer
+ * that wraps colon-bearing values in single quotes without escaping inner
+ * quotes can write a file the parser then cannot read back, which would brick
+ * the license cache until manually deleted.
+ */
 function dumpYaml(obj) {
   return Object.entries(obj)
-    .map(([k, v]) => `${k}: ${v == null ? '' : String(v).includes(':') ? `'${v}'` : v}`)
+    .map(([k, v]) => {
+      if (v == null) return `${k}: `;
+      const s = String(v).replace(/\r?\n/g, ' ').trim();
+      const needsQuote = s === '' || /[:'#]/.test(s) || /^\s|\s$/.test(s);
+      return needsQuote ? `${k}: '${s.replace(/'/g, "''")}'` : `${k}: ${s}`;
+    })
     .join('\n') + '\n';
 }
 

package/framework/hooks/model-governance.js

@@ -43,20 +43,6 @@ const AGENT_MODELS = {
   devops: { provider: 'claude', model: 'sonnet', tier: 'sonnet' },
 };
 
-/**
- * Upgrade conditions per agent. When context matches, the model
- * should be upgraded to the specified target.
- */
-const UPGRADE_CONDITIONS = {
-  orchestrator: { to: 'opus', condition: 'complex routing or deviation handling' },
-  'greenfield-wu': { to: 'sonnet', condition: 'multi-stack or enterprise' },
-  brief: { to: 'opus', condition: '10+ integrations' },
-  ux: { to: 'opus', condition: 'design system from scratch' },
-  phases: { to: 'opus', condition: '20+ requirements' },
-  tasks: { to: 'opus', condition: '50+ tasks' },
-  devops: { to: 'opus', condition: 'multi-environment or IaC' },
-};
-
 function getCurrentAgent(projectDir) {
   const sessionPath = join(projectDir, '.chati', 'session.yaml');
   if (!existsSync(sessionPath)) return null;
@@ -66,6 +52,27 @@ function getCurrentAgent(projectDir) {
   return match ? match[1].trim().replace(/^["']|["']$/g, '') : null;
 }
 
+function getSessionField(projectDir, key) {
+  const sessionPath = join(projectDir, '.chati', 'session.yaml');
+  if (!existsSync(sessionPath)) return null;
+  const raw = readFileSync(sessionPath, 'utf-8');
+  const match = raw.match(new RegExp(`^\\s*${key}:\\s*(.+)$`, 'm'));
+  if (!match) return null;
+  const v = match[1].trim().replace(/^["']|["']$/g, '');
+  return v === 'null' || v === '' ? null : v;
+}
+
+// Collapse a model id to its family so opus and opus[1m] count as the same
+// model for parity purposes (Article XXIV).
+function modelFamily(m) {
+  if (!m) return null;
+  const s = String(m).toLowerCase();
+  for (const fam of ['opus', 'sonnet', 'haiku', 'pro', 'flash', 'codex', 'gemini', 'gpt']) {
+    if (s.includes(fam)) return fam;
+  }
+  return s;
+}
+
 async function main() {
   let input = '';
   for await (const chunk of process.stdin) {
@@ -77,15 +84,31 @@ async function main() {
     const projectDir = event.cwd || process.cwd();
     const agent = getCurrentAgent(projectDir);
 
+    // Advisory context injection via the canonical UserPromptSubmit schema.
+    const lines = [];
+
     if (agent && AGENT_MODELS[agent]) {
       const assignment = AGENT_MODELS[agent];
       const expected = assignment.model || assignment;
       const provider = assignment.provider || 'claude';
-      // Advisory context injection via canonical UserPromptSubmit schema.
+      lines.push(`[Article XVI] Agent "${agent}" assigned model: ${expected} (provider: ${provider})`);
+    }
+
+    // Article XXIV: Model-Harness Parity. When the active model family differs
+    // from the model at the last harness audit, advise a re-audit. Advisory
+    // only, never blocks; the family comparison ignores variant changes such
+    // as opus vs opus[1m].
+    const activeModel = getSessionField(projectDir, 'active_model');
+    const modelAtLastAudit = getSessionField(projectDir, 'model_at_last_audit');
+    if (activeModel && modelAtLastAudit && modelFamily(activeModel) !== modelFamily(modelAtLastAudit)) {
+      lines.push(`[Article XXIV] Active model "${activeModel}" differs from the model at the last harness audit ("${modelAtLastAudit}"). Consider running /chati-update to re-audit the harness for this model. This is advisory and does not block your work.`);
+    }
+
+    if (lines.length > 0) {
       process.stdout.write(JSON.stringify({
         hookSpecificOutput: {
           hookEventName: 'UserPromptSubmit',
-          additionalContext: `[Article XVI] Agent "${agent}" assigned model: ${expected} (provider: ${provider})`,
+          additionalContext: lines.join('\n'),
         },
       }));
     } else {
@@ -97,7 +120,7 @@ async function main() {
   }
 }
 
-export { AGENT_MODELS, UPGRADE_CONDITIONS, getCurrentAgent };
+export { AGENT_MODELS, getCurrentAgent };
 
 // Only run main when executed directly (not imported by tests).
 // realpathSync resolves symlinks on both sides — important on macOS where

package/framework/hooks/prism-engine.js

@@ -32,9 +32,26 @@
  * Claude Code Hook: triggers on every user message submission.
  */
 
-import { existsSync, readFileSync, writeFileSync, renameSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync, renameSync, statSync } from 'fs';
 import { join } from 'path';
 
+// mtime-keyed read cache. This is a no-op for the per-prompt hook process
+// (it starts fresh each invocation and must read at least once), but it
+// spares repeated disk reads for long-lived importers of these helpers
+// (status --watch, context-status, tests) that call them many times in one
+// process. The mtime key guarantees a changed file is always re-read, so the
+// cache can never serve stale state.
+const _fileReadCache = new Map(); // absPath -> { mtimeMs, content }
+function readFileCached(absPath) {
+  let mtimeMs;
+  try { mtimeMs = statSync(absPath).mtimeMs; } catch { return null; }
+  const hit = _fileReadCache.get(absPath);
+  if (hit && hit.mtimeMs === mtimeMs) return hit.content;
+  const content = readFileSync(absPath, 'utf-8');
+  _fileReadCache.set(absPath, { mtimeMs, content });
+  return content;
+}
+
 // ---------------------------------------------------------------------------
 // Context window limits — load from shared JSON, fall back to embedded.
 // ---------------------------------------------------------------------------
@@ -47,18 +64,23 @@ function loadLimits(projectDir) {
   for (const candidate of candidates) {
     if (existsSync(candidate)) {
       try {
-        return JSON.parse(readFileSync(candidate, 'utf-8'));
+        const content = readFileCached(candidate);
+        if (content != null) return JSON.parse(content);
       } catch { /* malformed — fall through */ }
     }
   }
   // Last-resort fallback. Matches chati.dev/data/model-limits.json verbatim.
-  // Scan-stale check #25 guards parity between this block and the JSON.
+  // Scan-stale check #25 guards parity between this block AND the JSON.
+  // 2026-04-18 (context-window-auto-detect-v2): opus and sonnet families
+  // default to 1M; haiku stays at 200K. The prior `opus: 200_000` here was a
+  // stale regression-lock from PR #3 that silently degraded users to a 5x
+  // smaller context budget whenever model-limits.json was unreadable.
   return {
-    providers: { claude: 200_000, gemini: 1_000_000, codex: 128_000 },
+    providers: { claude: 1_000_000, gemini: 1_000_000, codex: 128_000 },
     models: {
-      opus:         200_000,
+      opus:         1_000_000,
       'opus[1m]':   1_000_000,
-      sonnet:       200_000,
+      sonnet:       1_000_000,
       'sonnet[1m]': 1_000_000,
       haiku:        200_000,
       pro:          1_000_000,
@@ -117,7 +139,8 @@ function readSessionState(projectDir) {
   const sessionPath = join(projectDir, '.chati', 'session.yaml');
   if (!existsSync(sessionPath)) return null;
 
-  const raw = readFileSync(sessionPath, 'utf-8');
+  const raw = readFileCached(sessionPath);
+  if (raw == null) return null;
   const extract = (key) => {
     const match = raw.match(new RegExp(`^\\s*${key}:\\s*(.+)$`, 'm'));
     if (!match) return null;
@@ -152,6 +175,7 @@ function readSessionState(projectDir) {
     provider: extract('active_provider') || extract('provider') || 'claude',
     // v1.2 context detection fields.
     activeModel: extract('active_model'),
+    modelAtLastAudit: extract('model_at_last_audit'),
     contextTokensUsed: extractNum('context_tokens_used') || 0,
     contextWindowTokens: extractNum('context_window_tokens'),
     activeTeamId,
@@ -302,6 +326,12 @@ async function main() {
         context_last_bracket:   bracket,
         // If we detected a model and the session did not have one, cache it.
         ...(detectedModel && !session.activeModel ? { active_model: detectedModel } : {}),
+        // Seed the harness-audit baseline once (Article XXIV). Only when unset,
+        // so a later model change leaves the old baseline in place for the
+        // model-governance advisory to detect.
+        ...((detectedModel || session.activeModel) && !session.modelAtLastAudit
+          ? { model_at_last_audit: detectedModel || session.activeModel }
+          : {}),
       });
     } catch (err) {
       process.stderr.write(`[chati] prism-engine write-back failed (non-fatal): ${err.message}\n`);
@@ -319,6 +349,35 @@ async function main() {
       }
     }
 
+    // 5b. Gotchas block. Surface the most relevant known gotchas to every agent
+    // per turn. This is the reliable per-turn, all-agent delivery path; gotchas
+    // attached to a handoff alone do not reach interactive agents and do not
+    // survive the first agent memory write. Read straight from the shared store;
+    // no src/ import (hooks are standalone).
+    let gotchasBlock = '';
+    if (session.currentAgent && bracket !== 'CRITICAL') {
+      const gotchasPath = join(projectDir, '.chati', 'memories', 'shared', 'gotchas.json');
+      const rawGotchas = readFileCached(gotchasPath);
+      if (rawGotchas) {
+        try {
+          const all = JSON.parse(rawGotchas);
+          const SEV = { CRITICAL: 3, WARNING: 2, INFO: 1 };
+          const ranked = (Array.isArray(all) ? all : [])
+            .filter((g) => g && !g.resolution)
+            .map((g) => ({ g, score: (g.agent === session.currentAgent ? 10 : 0) + (SEV[g.severity] || 1) + Math.min(5, g.count || 1) }))
+            .sort((a, b) => b.score - a.score)
+            .slice(0, 3);
+          if (ranked.length) {
+            const items = ranked.map(({ g }) => {
+              const msg = String(g.original_message || g.message || '').replace(/[<>]/g, '').replace(/\s+/g, ' ').slice(0, 160);
+              return `    <gotcha id="${g.id}" severity="${g.severity || 'INFO'}">${msg}</gotcha>`;
+            });
+            gotchasBlock = ['  <known-gotchas>', ...items, '  </known-gotchas>'].join('\n');
+          }
+        } catch { /* malformed gotchas store — skip */ }
+      }
+    }
+
     // 6. Team context block (unchanged).
     let teamContextBlock = '';
     if (session.activeTeamId && bracket !== 'CRITICAL') {
@@ -335,10 +394,16 @@ async function main() {
 
     // 7. Advisories.
     const frustrationDetected = detectFrustration(promptText);
-    const microcompactAdvisory =
-      (bracket === 'DEPLETED' || bracket === 'CRITICAL')
-        ? '  <advisory priority="medium">Context constrained. Avoid re-reading files already in context. Summarize stale outputs before proceeding.</advisory>'
-        : '';
+    const lowContext = bracket === 'DEPLETED' || bracket === 'CRITICAL';
+    const microcompactAdvisory = lowContext
+      ? '  <advisory priority="medium">Context constrained. Avoid re-reading files already in context. Summarize stale outputs before proceeding.</advisory>'
+      : '';
+    // During BUILD at low context, prefer a clean session reset (handoff + fresh
+    // session) over in-place compaction: compaction keeps the model wrapping up
+    // prematurely while code is being written (Article XII reset preference).
+    const buildResetAdvisory = (lowContext && session.mode === 'build')
+      ? '  <advisory priority="high">BUILD phase at low context. Prefer a clean reset: write a handoff and continue in a fresh session, rather than compacting in place.</advisory>'
+      : '';
 
     // 8. Compose the context block.
     const contextBlock = [
@@ -347,9 +412,11 @@ async function main() {
       session.currentAgent ? `  <agent>${session.currentAgent}</agent>` : '',
       session.pipelinePosition ? `  <pipeline-position>${session.pipelinePosition}</pipeline-position>` : '',
       memoryBlock,
+      gotchasBlock,
       teamContextBlock,
       bracket === 'CRITICAL' ? '  <advisory>Context running low. Consider handoff or summary.</advisory>' : '',
       microcompactAdvisory,
+      buildResetAdvisory,
       frustrationDetected ? '  <advisory priority="high">User shows signs of frustration. Be more direct, acknowledge the issue explicitly, focus on the solution, avoid repeating previous suggestions.</advisory>' : '',
       '</chati-context>',
     ].filter(Boolean).join('\n');

package/framework/hooks/session-digest.js

@@ -6,7 +6,8 @@
  * recovered after context compaction. Writes to .chati/memories/shared/session/.
  */
 
-import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, chmodSync } from 'fs';
+import { createHash } from 'crypto';
 import { join } from 'path';
 
 /**
@@ -250,11 +251,19 @@ async function main() {
               content += newEntry;
             }
             writeFileSync(pingsPath, content, 'utf-8');
+            // pings.yaml records the installation and private project paths;
+            // restrict to owner-only.
+            try { chmodSync(pingsPath, 0o600); } catch { /* no-op on Windows / read-only FS */ }
 
-            // Fire-and-forget telemetry (3s timeout, never blocks)
+            // Fire-and-forget telemetry (3s timeout, never blocks).
+            // The raw license key is never transmitted. The body carries only a
+            // non-reversible installation_id (sha256 of the key, 16 hex) so the
+            // server can group sessions per install without ever seeing, logging
+            // or storing the key.
             try {
+              const installationId = createHash('sha256').update(licenseKey).digest('hex').slice(0, 16);
               const body = JSON.stringify({
-                license_key: licenseKey,
+                installation_id: installationId,
                 project_name: digest.currentAgent || 'unknown',
                 events: [{ type: 'session_active', timestamp: nowIso, properties: { pipeline_phase: digest.mode, current_agent: digest.currentAgent } }],
               });