chati-dev 4.2.2 → 4.3.0

package/src/installer/templates.js

@@ -6,36 +6,49 @@ import yaml from 'js-yaml';
 export function generateSessionYaml(config) {
   const { projectName, projectType, language, selectedIDEs, selectedMCPs, llmProvider, allProviders } = config;
 
+  // Schema MUST match session-manager.js DEFAULT_SESSION fields,
+  // otherwise validateSession() rejects installer-generated sessions.
   const session = {
     schema_version: '1.0',
+    version: '1.0',
+    mode: 'discover',
     project: {
       name: projectName,
       type: projectType,
       state: 'discover',
     },
-    execution_mode: 'interactive',
-    execution_profile: 'guided',
-    current_agent: '',
     language: language,
+    project_type: projectType,
+    started_at: new Date().toISOString(),
+    current_agent: '',
+    pipeline_position: 0,
+    execution_mode: 'interactive',
+    user_level: 'auto',
+    user_level_confidence: 0.0,
     ides: selectedIDEs,
     mcps: selectedMCPs,
     providers_enabled: allProviders && allProviders.length > 0 ? allProviders : [llmProvider || 'claude'],
     primary_provider: llmProvider || 'claude',
     active_provider: llmProvider || 'claude',
-    user_level: 'auto',
-    user_level_confidence: 0.0,
+    completed_agents: [],
+    agent_results: {},
+    mode_transitions: [],
+    deviations: [],
     agents: {},
     backlog: [],
     last_handoff: '',
-    deviations: [],
-    profile_transitions: [],
+    // Article XXIII — Reasoning Tier Governance.
+    // Tier starts at 'standard' and is promoted by reasoning-escalator.js
+    // in response to friction signals. See chati.dev/hooks/reasoning-escalator.js.
+    reasoning_tier: 'standard',
+    reasoning_escalations: [],
   };
 
-  // Initialize all 12 agent statuses
+  // Initialize all 13 agent statuses
   const agentNames = [
     'greenfield-wu', 'brownfield-wu', 'brief', 'detail',
     'architect', 'ux', 'phases', 'tasks',
-    'qa-planning', 'dev', 'qa-implementation', 'devops',
+    'qa-planning', 'dev', 'qa-implementation', 'qa-visual', 'devops',
   ];
 
   for (const agent of agentNames) {
@@ -62,7 +75,7 @@ export const PROVIDER_MODEL_MAPS = {
       orchestrator: 'sonnet', 'greenfield-wu': 'haiku', 'brownfield-wu': 'opus',
       brief: 'sonnet', detail: 'opus', architect: 'opus', ux: 'sonnet',
       phases: 'sonnet', tasks: 'sonnet', 'qa-planning': 'opus',
-      dev: 'opus', 'qa-implementation': 'opus', devops: 'sonnet',
+      dev: 'opus', 'qa-implementation': 'opus', 'qa-visual': 'opus', devops: 'sonnet',
     },
   },
   gemini: {
@@ -71,7 +84,7 @@ export const PROVIDER_MODEL_MAPS = {
       orchestrator: 'flash', 'greenfield-wu': 'flash', 'brownfield-wu': 'pro',
       brief: 'flash', detail: 'pro', architect: 'pro', ux: 'flash',
       phases: 'flash', tasks: 'flash', 'qa-planning': 'pro',
-      dev: 'pro', 'qa-implementation': 'pro', devops: 'flash',
+      dev: 'pro', 'qa-implementation': 'pro', 'qa-visual': 'pro', devops: 'flash',
     },
   },
   codex: {
@@ -80,7 +93,7 @@ export const PROVIDER_MODEL_MAPS = {
       orchestrator: 'mini', 'greenfield-wu': 'mini', 'brownfield-wu': 'codex',
       brief: 'mini', detail: 'codex', architect: 'codex', ux: 'mini',
       phases: 'mini', tasks: 'mini', 'qa-planning': 'codex',
-      dev: 'codex', 'qa-implementation': 'codex', devops: 'mini',
+      dev: 'codex', 'qa-implementation': 'codex', 'qa-visual': 'codex', devops: 'mini',
     },
   },
 };
@@ -89,7 +102,8 @@ export const PROVIDER_MODEL_MAPS = {
  * Generate config.yaml content
  */
 export function generateConfigYaml(config) {
-  const { version, projectType, language, selectedIDEs, llmProvider, allProviders } = config;
+  const { version, projectType, language, llmProvider, allProviders } = config;
+  const selectedIDEs = config.selectedIDEs || [];
   const provider = llmProvider || 'claude';
   const providers = allProviders && allProviders.length > 0 ? allProviders : [provider];
 
@@ -140,7 +154,7 @@ export function generateConfigYaml(config) {
     // pipeline silently. See plan: was previously false for "safe rollout"
     // but the v4.2.0 launch never actually shipped, so this is a fresh start.
     agent_teams: true,
-    team_planning_size: 3,
+    team_planning_size: 4,
     team_build_size: 2,
     team_echo_threshold: 0.92,
     team_correction_cycles_max: 2,
@@ -193,7 +207,7 @@ Type \`/chati\` to start.
  * Also reads AGENTS.md for project context (auto-generated by context-file-generator).
  */
 export function generateCodexSkill(options = {}) {
-  const orchPath = options.orchestratorPath || 'chati.dev/orchestrator/chati.md';
+  const orchPath = options.orchestratorPath || '.chati.dev/orchestrator/chati.md';
   return `---
 name: chati
 description: >
@@ -231,8 +245,8 @@ Read and execute the full orchestrator at \`${orchPath}\`.
 **Context to pass:**
 - \`.chati/session.yaml\` (session state — includes language)
 - \`AGENTS.md\` (project context)
-- \`chati.dev/artifacts/handoffs/\` (latest handoff)
-- \`chati.dev/config.yaml\` (version info)
+- \`artifacts/handoffs/\` (latest handoff)
+- \`.chati.dev/config.yaml\` (version info)
 
 **User input:** $ARGUMENTS
 `;
@@ -240,12 +254,9 @@ Read and execute the full orchestrator at \`${orchPath}\`.
 
 /**
  * Generate Gemini CLI TOML command (.gemini/commands/chati.toml)
- *
- * Gemini CLI custom commands use TOML format with `description` and `prompt` fields.
- * Supports {{args}} for user arguments and @{file} for file injection.
  */
 export function generateGeminiRouter(options = {}) {
-  const orchPath = options.orchestratorPath || 'chati.dev/orchestrator/chati.md';
+  const orchPath = options.orchestratorPath || '.chati.dev/orchestrator/chati.md';
   return `description = "Activate Chati.dev orchestrator"
 prompt = """
 CRITICAL — Language Override:
@@ -262,8 +273,8 @@ NEVER create or reference CLAUDE.md, CLAUDE.local.md, or .claude/ directories.
 Context to load:
 - .chati/session.yaml (session state — includes language)
 - GEMINI.md (project context)
-- chati.dev/artifacts/handoffs/ (latest handoff)
-- chati.dev/config.yaml (version info)
+- artifacts/handoffs/ (latest handoff)
+- .chati.dev/config.yaml (version info)
 
 User input: {{args}}
 """
@@ -276,15 +287,17 @@ User input: {{args}}
 export function generateClaudeLocalMd() {
   return `# Chati.dev Runtime State
 
+<!-- chati-lock:start -->
 ## Session Lock
 **Status: INACTIVE** — Type \`/chati\` to activate.
+<!-- chati-lock:end -->
 
-<!-- SESSION-LOCK:INACTIVE -->
-
+<!-- chati-state:start -->
 ## Current State
 - **Agent**: None (ready to start)
 - **Pipeline**: Pre-start
 - **Mode**: interactive
+<!-- chati-state:end -->
 
 ## Recent Decisions
 _No decisions yet. Start with /chati._
@@ -301,15 +314,17 @@ _Auto-updated by Chati.dev orchestrator_
 export function generateGeminiSessionLock() {
   return `# Chati.dev Runtime State
 
+<!-- chati-lock:start -->
 ## Session Lock
 **Status: INACTIVE** — Type \`/chati\` to activate.
+<!-- chati-lock:end -->
 
-<!-- SESSION-LOCK:INACTIVE -->
-
+<!-- chati-state:start -->
 ## Current State
 - **Agent**: None (ready to start)
 - **Pipeline**: Pre-start
 - **Mode**: interactive
+<!-- chati-state:end -->
 
 ## Recent Decisions
 _No decisions yet. Start with /chati._
@@ -326,15 +341,17 @@ _Auto-updated by Chati.dev orchestrator_
 export function generateAgentsOverrideMd() {
   return `# Chati.dev Runtime State
 
+<!-- chati-lock:start -->
 ## Session Lock
 **Status: INACTIVE** — Type \`$chati\` to activate.
+<!-- chati-lock:end -->
 
-<!-- SESSION-LOCK:INACTIVE -->
-
+<!-- chati-state:start -->
 ## Current State
 - **Agent**: None (ready to start)
 - **Pipeline**: Pre-start
 - **Mode**: interactive
+<!-- chati-state:end -->
 
 ## Recent Decisions
 _No decisions yet. Start with $chati._

package/src/installer/validator.js

@@ -6,6 +6,11 @@ import { loadManifest } from './manifest.js';
 import { ADAPTABLE_FILES } from '../config/framework-adapter.js';
 import { validateSchema, CONFIG_SCHEMA } from '../utils/schema-validator.js';
 
+function resolveFrameworkDir(targetDir) {
+  if (existsSync(join(targetDir, '.chati.dev'))) return '.chati.dev';
+  return 'chati.dev';
+}
+
 /**
  * Validate chati.dev installation
  * Checks all primary agents, constitution, session, schemas, etc.
@@ -47,7 +52,7 @@ export async function validateInstallation(targetDir) {
 
   let agentCount = 0;
   for (const file of agentFiles) {
-    const filePath = join(targetDir, 'chati.dev', file);
+    const filePath = join(targetDir, resolveFrameworkDir(targetDir), file);
     if (existsSync(filePath)) {
       const content = readFileSync(filePath, 'utf-8');
       // Check that agent implements protocols (look for key protocol references)
@@ -63,11 +68,11 @@ export async function validateInstallation(targetDir) {
   if (results.agents.pass) results.passed += 1;
 
   // Check constitution
-  const constitutionPath = join(targetDir, 'chati.dev', 'constitution.md');
+  const constitutionPath = join(targetDir, resolveFrameworkDir(targetDir), 'constitution.md');
   if (existsSync(constitutionPath)) {
     const content = readFileSync(constitutionPath, 'utf-8');
     const articleCount = (content.match(/^## Article/gm) || []).length;
-    results.constitution.pass = articleCount >= 19;
+    results.constitution.pass = articleCount >= 22;
     results.constitution.details.push({ articleCount });
   }
   results.total += 1;
@@ -86,7 +91,7 @@ export async function validateInstallation(targetDir) {
   ];
   let schemaCount = 0;
   for (const file of schemaFiles) {
-    if (existsSync(join(targetDir, 'chati.dev', 'schemas', file))) {
+    if (existsSync(join(targetDir, resolveFrameworkDir(targetDir), 'schemas', file))) {
       schemaCount++;
     }
   }
@@ -102,7 +107,7 @@ export async function validateInstallation(targetDir) {
   ];
   let workflowCount = 0;
   for (const file of workflowFiles) {
-    if (existsSync(join(targetDir, 'chati.dev', 'workflows', file))) {
+    if (existsSync(join(targetDir, resolveFrameworkDir(targetDir), 'workflows', file))) {
       workflowCount++;
     }
   }
@@ -118,7 +123,7 @@ export async function validateInstallation(targetDir) {
   ];
   let templateCount = 0;
   for (const file of templateFiles) {
-    if (existsSync(join(targetDir, 'chati.dev', 'templates', file))) {
+    if (existsSync(join(targetDir, resolveFrameworkDir(targetDir), 'templates', file))) {
       templateCount++;
     }
   }
@@ -137,7 +142,7 @@ export async function validateInstallation(targetDir) {
   ];
   let intelCount = 0;
   for (const file of intelligenceFiles) {
-    if (existsSync(join(targetDir, 'chati.dev', file))) {
+    if (existsSync(join(targetDir, resolveFrameworkDir(targetDir), file))) {
       intelCount++;
     }
   }
@@ -147,7 +152,7 @@ export async function validateInstallation(targetDir) {
   if (results.intelligence.pass) results.passed += 1;
 
   // Check entity registry
-  const registryPath = join(targetDir, 'chati.dev', 'data', 'entity-registry.yaml');
+  const registryPath = join(targetDir, resolveFrameworkDir(targetDir), 'data', 'entity-registry.yaml');
   results.registry.pass = existsSync(registryPath);
   results.total += 1;
   if (results.registry.pass) results.passed += 1;
@@ -164,7 +169,7 @@ export async function validateInstallation(targetDir) {
   let contextCount = 0;
   for (const file of contextFileNames) {
     // Check source (chati.dev/context/) OR deployed (.claude/rules/chati/)
-    const inSource = existsSync(join(targetDir, 'chati.dev', 'context', file));
+    const inSource = existsSync(join(targetDir, resolveFrameworkDir(targetDir), 'context', file));
     const inRules = existsSync(join(targetDir, '.claude', 'rules', 'chati', file));
     if (inSource || inRules) {
       contextCount++;
@@ -176,7 +181,7 @@ export async function validateInstallation(targetDir) {
   if (results.context.pass) results.passed += 1;
 
   // Check provider overlays (if multiple providers configured)
-  const configYamlPath = join(targetDir, 'chati.dev', 'config.yaml');
+  const configYamlPath = join(targetDir, resolveFrameworkDir(targetDir), 'config.yaml');
   if (existsSync(configYamlPath)) {
     try {
       const configContent = readFileSync(configYamlPath, 'utf-8');
@@ -208,7 +213,7 @@ export async function validateInstallation(targetDir) {
           const missingFiles = [];
 
           for (const file of ADAPTABLE_FILES) {
-            const overlayPath = join(targetDir, 'chati.dev', '.adapted', provider, file);
+            const overlayPath = join(targetDir, resolveFrameworkDir(targetDir), '.adapted', provider, file);
             if (existsSync(overlayPath)) {
               present++;
             } else {
@@ -253,7 +258,7 @@ export async function validateInstallation(targetDir) {
     const mismatches = [];
 
     for (const [relPath, entry] of Object.entries(manifest.files)) {
-      const absPath = join(targetDir, 'chati.dev', relPath);
+      const absPath = join(targetDir, resolveFrameworkDir(targetDir), relPath);
       if (existsSync(absPath)) {
         const currentHash = hashFile(absPath);
         if (currentHash === entry.hash) {

package/src/intelligence/registry-manager.js

@@ -1,14 +1,25 @@
 import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 import yaml from 'js-yaml';
+import { resolveFrameworkDir } from '../utils/framework-dir.js';
+import { flattenEntitiesMap } from '../utils/flatten-entities.js';
+
+/**
+ * Get the entity registry path for a given project.
+ * Supports both .chati.dev/ and chati.dev/ structures.
+ * @param {string} targetDir
+ * @returns {string} Relative path from project root
+ */
+function getRegistryPath(targetDir) {
+  return `${resolveFrameworkDir(targetDir)}/data/entity-registry.yaml`;
+}
 
-const REGISTRY_PATH = 'chati.dev/data/entity-registry.yaml';
 
 /**
  * Check registry integrity against filesystem
  */
 export function checkRegistry(targetDir) {
-  const registryPath = join(targetDir, REGISTRY_PATH);
+  const registryPath = join(targetDir, getRegistryPath(targetDir));
   if (!existsSync(registryPath)) {
     return { valid: false, error: 'Entity registry not found', missing: [], orphaned: [] };
   }
@@ -22,7 +33,7 @@ export function checkRegistry(targetDir) {
   const found = [];
 
   // Check each registered entity exists on disk
-  const entities = flattenEntities(registry.entities);
+  const entities = flattenEntitiesMap(registry.entities);
   for (const entity of entities) {
     const filePath = join(targetDir, entity.path);
     if (existsSync(filePath)) {
@@ -44,7 +55,7 @@ export function checkRegistry(targetDir) {
  * Get registry statistics
  */
 export function getRegistryStats(targetDir) {
-  const registryPath = join(targetDir, REGISTRY_PATH);
+  const registryPath = join(targetDir, getRegistryPath(targetDir));
   if (!existsSync(registryPath)) {
     return { exists: false, totalEntities: 0, byType: {} };
   }
@@ -54,7 +65,7 @@ export function getRegistryStats(targetDir) {
     return { exists: true, totalEntities: 0, byType: {}, error: 'Parse error' };
   }
 
-  const entities = flattenEntities(registry.entities);
+  const entities = flattenEntitiesMap(registry.entities);
   const byType = {};
   for (const entity of entities) {
     const type = entity.type || 'unknown';
@@ -111,9 +122,10 @@ export function runHealthCheck(targetDir) {
     'session.schema.json', 'config.schema.json', 'task.schema.json',
     'context.schema.json', 'memory.schema.json',
   ];
+  const fwDir = resolveFrameworkDir(targetDir);
   let validSchemas = 0;
   for (const file of schemaFiles) {
-    const schemaPath = join(targetDir, 'chati.dev', 'schemas', file);
+    const schemaPath = join(targetDir, fwDir, 'schemas', file);
     if (existsSync(schemaPath)) {
       try {
         JSON.parse(readFileSync(schemaPath, 'utf-8'));
@@ -127,12 +139,12 @@ export function runHealthCheck(targetDir) {
   checks.schemas.details = `${validSchemas}/${schemaFiles.length} valid`;
 
   // 3. Constitution check
-  const constitutionPath = join(targetDir, 'chati.dev', 'constitution.md');
+  const constitutionPath = join(targetDir, fwDir, 'constitution.md');
   if (existsSync(constitutionPath)) {
     const content = readFileSync(constitutionPath, 'utf-8');
     const articleCount = (content.match(/^## Article/gm) || []).length;
-    checks.constitution.pass = articleCount >= 19;
-    checks.constitution.details = `${articleCount}/19 articles`;
+    checks.constitution.pass = articleCount >= 22;
+    checks.constitution.details = `${articleCount}/23 articles`;
   } else {
     checks.constitution.details = 'Not found';
   }
@@ -149,7 +161,7 @@ export function runHealthCheck(targetDir) {
   ];
   let foundAgents = 0;
   for (const p of agentPaths) {
-    if (existsSync(join(targetDir, 'chati.dev', p))) foundAgents++;
+    if (existsSync(join(targetDir, fwDir, p))) foundAgents++;
   }
   checks.agents.pass = foundAgents === 13;
   checks.agents.details = `${foundAgents}/13 present`;
@@ -181,22 +193,3 @@ function loadRegistry(registryPath) {
   }
 }
 
-/**
- * Flatten nested entity categories into flat array
- */
-function flattenEntities(entities) {
-  if (!entities) return [];
-  const flat = [];
-
-  for (const [, items] of Object.entries(entities)) {
-    if (typeof items === 'object' && items !== null) {
-      for (const [name, entity] of Object.entries(items)) {
-        if (entity && entity.path) {
-          flat.push({ name, ...entity });
-        }
-      }
-    }
-  }
-
-  return flat;
-}

package/src/intelligence/timeline.js

@@ -6,11 +6,6 @@
  * results, handoffs, and deviations.
  */
 
-/**
- * @deprecated Not currently imported by any production module.
- * Retained for potential future integration. Review for removal or integration by v5.0.
- */
-
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
 import { join, dirname } from 'path';
 
@@ -38,6 +33,8 @@ export const EventType = {
   PROVIDER_SELECTED: 'provider_selected',
   SESSION_STARTED: 'session_started',
   SESSION_ENDED: 'session_ended',
+  CORRECTION_TRIGGERED: 'correction_triggered',
+  CORRECTION_ESCALATED: 'correction_escalated',
 };
 
 const TIMELINE_FILE = '.chati/timeline.json';
@@ -82,8 +79,16 @@ function saveTimeline(projectDir, timeline) {
  */
 export function recordEvent(projectDir, type, agent, data = {}) {
   const timeline = loadTimeline(projectDir);
-  _counter++;
 
+  // Dedup: skip if the last event of this type already targets the same agent.
+  // Prevents duplicate AGENT_ACTIVATED entries when handleAdvance chains into
+  // handleNext while the caller also invokes next separately.
+  const last = timeline[timeline.length - 1];
+  if (last && last.type === type && last.agent === agent) {
+    return last;
+  }
+
+  _counter++;
   const event = {
     id: `evt-${Date.now()}-${_counter}`,
     type,

package/src/license/commands.js

@@ -37,7 +37,7 @@ export async function runActivate(projectDir, keyArg) {
     const plan = result.plan ?? 'trial';
     const days = result.days_remaining ?? '?';
     console.log(`\n✓ Activated! Plan: ${plan} — ${days} day(s) remaining.`);
-    console.log(`  Key saved to chati.dev/config.yaml`);
+    console.log(`  Key saved to ~/.chati-dev/license.yaml`);
     console.log(`  Run /chati to start.\n`);
   } catch (err) {
     console.error(`\n✗ Activation failed: ${err.message}`);

package/src/license/wait.js

@@ -0,0 +1,102 @@
+/**
+ * @fileoverview Poll ~/.chati-dev/license.yaml until status=VALID.
+ *
+ * Part of the autonomous-completion workstream (ADR-AUTO-01): when a /chati
+ * session boots with no VALID license, the orchestrator tells the user to
+ * run `npx chati-dev activate --key=X` in another terminal, then calls
+ * this util to block until the file appears with VALID status.
+ *
+ * Design invariants:
+ *   - Never echo the license key to chat (the whole reason we don't use
+ *     chat-paste). We only check status.
+ *   - Bounded wait: default 60s timeout, 3s poll interval.
+ *   - Fast-fail on EXPIRED / INVALID / REVOKED — those need a NEW key,
+ *     polling won't resolve them.
+ *   - Pure function on time: cancellation via AbortSignal supported so
+ *     callers (tests, interactive CLI) can stop the loop.
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+export const DEFAULT_POLL_INTERVAL_MS = 3_000;
+export const DEFAULT_TIMEOUT_MS       = 60_000;
+
+const TERMINAL_BAD_STATUSES = new Set(['EXPIRED', 'INVALID', 'REVOKED']);
+
+/**
+ * Read ~/.chati-dev/license.yaml and extract the status field.
+ * Pure + synchronous — safe to call from poll loop.
+ *
+ * @param {string} home
+ * @returns {{ present: boolean, status: string|null, reason: string|null, error?: string }}
+ */
+export function readLicenseStatus(home) {
+  const licensePath = join(home, '.chati-dev', 'license.yaml');
+  if (!existsSync(licensePath)) {
+    return { present: false, status: null, reason: null };
+  }
+  try {
+    const raw = readFileSync(licensePath, 'utf-8');
+    const statusMatch = raw.match(/^\s*status:\s*["']?(\w+)/m);
+    const reasonMatch = raw.match(/^\s*reason:\s*["']?([^"'\n]+)/m);
+    return {
+      present: true,
+      status:  statusMatch ? statusMatch[1].toUpperCase() : null,
+      reason:  reasonMatch ? reasonMatch[1].trim() : null,
+    };
+  } catch (err) {
+    return { present: true, status: null, reason: null, error: err.message };
+  }
+}
+
+/**
+ * Poll for a VALID license. Resolves when:
+ *   - Status becomes VALID → { valid: true, status: 'VALID' }
+ *   - Status is terminal-bad (EXPIRED|INVALID|REVOKED) → { valid: false, status, reason }
+ *   - Timeout elapses → { valid: false, status: 'TIMEOUT', reason: 'No valid license detected within N seconds' }
+ *   - Caller aborts → { valid: false, status: 'ABORTED' }
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.home]         Override HOME (default: process.env.HOME).
+ * @param {number} [opts.intervalMs]   Poll period (default 3000).
+ * @param {number} [opts.timeoutMs]    Total wait (default 60_000).
+ * @param {AbortSignal} [opts.signal]  Cancel the loop externally.
+ * @param {(ms:number)=>Promise<void>} [opts.sleep]  Injectable sleep (tests).
+ * @returns {Promise<{ valid: boolean, status: string|null, reason: string|null, waitedMs: number }>}
+ */
+export async function waitForLicense(opts = {}) {
+  const home        = opts.home       || process.env.HOME || '';
+  const intervalMs  = opts.intervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+  const timeoutMs   = opts.timeoutMs  ?? DEFAULT_TIMEOUT_MS;
+  const signal      = opts.signal;
+  const sleep       = opts.sleep || ((ms) => new Promise(r => setTimeout(r, ms)));
+
+  const startedAt = Date.now();
+
+  for (;;) {
+    if (signal?.aborted) {
+      return { valid: false, status: 'ABORTED', reason: 'Poll aborted by caller', waitedMs: Date.now() - startedAt };
+    }
+
+    const snap = readLicenseStatus(home);
+    if (snap.status === 'VALID') {
+      return { valid: true, status: 'VALID', reason: null, waitedMs: Date.now() - startedAt };
+    }
+    if (snap.status && TERMINAL_BAD_STATUSES.has(snap.status)) {
+      return { valid: false, status: snap.status, reason: snap.reason || `License ${snap.status}`, waitedMs: Date.now() - startedAt };
+    }
+
+    const elapsed = Date.now() - startedAt;
+    if (elapsed >= timeoutMs) {
+      return {
+        valid:     false,
+        status:    'TIMEOUT',
+        reason:    `No VALID license detected at ~/.chati-dev/license.yaml within ${Math.round(timeoutMs / 1000)}s.`,
+        waitedMs:  elapsed,
+      };
+    }
+
+    await sleep(Math.min(intervalMs, timeoutMs - elapsed));
+  }
+}

package/src/memory/agent-memory.js

@@ -167,6 +167,87 @@ export function writeAgentMemory(projectDir, agentName, entry) {
   return { saved: true };
 }
 
+/**
+ * Write a minimal MEMORY.md for an agent that has none, derived from a
+ * session digest (memory-bootstrap-v1, F-A5-006).
+ *
+ * Rules:
+ *   - Only writes when the target MEMORY.md does not exist or is empty
+ *     (idempotent; second call on the same agent is a no-op).
+ *   - Entries are tagged `source: bootstrap` and confidence `low` so
+ *     dream.js can safely re-classify / deduplicate on a later full run.
+ *   - The produced file carries a `<!-- bootstrap-write: true -->` HTML
+ *     comment header for auditability.
+ *
+ * @param {string} projectDir
+ * @param {string} agentName
+ * @param {object} digest - Session digest shape from session-digest.js
+ * @returns {{ written: boolean, reason?: string, path?: string }}
+ */
+export function writeBootstrapMemory(projectDir, agentName, digest) {
+  if (!agentName || agentName === 'none') {
+    return { written: false, reason: 'no-agent' };
+  }
+  const memoryPath = getAgentMemoryPath(projectDir, agentName);
+
+  // Idempotency: skip if a non-empty MEMORY.md already exists.
+  if (existsSync(memoryPath)) {
+    try {
+      const existing = readFileSync(memoryPath, 'utf-8').trim();
+      if (existing.length > 0) {
+        return { written: false, reason: 'already-populated' };
+      }
+    } catch { /* fall through to write */ }
+  }
+
+  const dir = dirname(memoryPath);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+  const header = `<!-- bootstrap-write: true -->\n<!-- source: session-digest bootstrap (memory-bootstrap-v1) -->\n`;
+  const entries = [];
+
+  // Seed Episodic with the current pipeline context.
+  if (digest?.mode && digest?.pipelinePosition) {
+    entries.push({
+      category: 'Episodic',
+      content: `Resumed at mode=${digest.mode}, pipeline_position=${digest.pipelinePosition}, workflow=${digest.workflow || 'unknown'}.`,
+      confidence: 'low',
+      tags: ['source:bootstrap'],
+    });
+  }
+
+  // Seed Semantic from active_task (if digest has one).
+  if (digest?.active_task) {
+    entries.push({
+      category: 'Semantic',
+      content: `Active task on resume: ${String(digest.active_task).slice(0, 500)}`,
+      confidence: 'low',
+      tags: ['source:bootstrap'],
+    });
+  }
+
+  // Seed Procedural from gotchas_found (capped).
+  if (Array.isArray(digest?.gotchas_found) && digest.gotchas_found.length > 0) {
+    for (const g of digest.gotchas_found.slice(0, 5)) {
+      if (!g?.message) continue;
+      entries.push({
+        category: 'Procedural',
+        content: `Known gotcha [${g.severity || 'info'}] ${g.id || ''}: ${String(g.message).slice(0, 200)}`,
+        confidence: 'low',
+        tags: ['source:bootstrap', `severity:${g.severity || 'info'}`],
+      });
+    }
+  }
+
+  if (entries.length === 0) {
+    return { written: false, reason: 'no-content' };
+  }
+
+  const body = formatMemoryMarkdown(entries);
+  writeFileSync(memoryPath, header + '\n' + body, 'utf-8');
+  return { written: true, path: memoryPath };
+}
+
 /**
  * Search across all agent memories.
  * @param {string} projectDir - Project directory