sinapse-ai 1.6.1 → 1.8.0

package/.sinapse-ai/core/execution/subagent-dispatcher.js

@@ -9,26 +9,45 @@
  */
 
 const EventEmitter = require('events');
-const { spawn } = require('child_process');
 const _path = require('path');
+const { runSafe } = require('../utils/spawn-safe');
 
-// Import AI Provider Factory
+// epic: orchestration-consolidation, F2 — resolves any of the 189 agent ids to
+// its real persona on disk (squads/ + framework agents). Optional: degrades to a
+// generic prompt if the module is missing.
+let SquadAgentResolver;
+try {
+  SquadAgentResolver = require('../registry/squad-agent-resolver');
+} catch {
+  SquadAgentResolver = null;
+}
+
+// Import AI Provider Factory (factory module directly — the index barrel
+// requires a removed gemini-provider and would throw on load).
 let AIProviderFactory;
 try {
-  AIProviderFactory = require('../../infrastructure/integrations/ai-providers');
+  AIProviderFactory = require('../../infrastructure/integrations/ai-providers/ai-provider-factory');
 } catch {
-  AIProviderFactory = null;
+  try {
+    AIProviderFactory = require('../../infrastructure/integrations/ai-providers');
+  } catch {
+    AIProviderFactory = null;
+  }
 }
 
 // Import dependencies with fallbacks
 let MemoryQuery, GotchasMemory;
 try {
-  MemoryQuery = require('../memory/memory-query');
+  const memoryQueryModule = require('../memory/memory-query');
+  MemoryQuery = memoryQueryModule.MemoryQuery || memoryQueryModule;
+  if (typeof MemoryQuery !== 'function') MemoryQuery = null;
 } catch {
   MemoryQuery = null;
 }
 try {
-  GotchasMemory = require('../memory/gotchas-memory');
+  const gotchasModule = require('../memory/gotchas-memory');
+  GotchasMemory = gotchasModule.GotchasMemory || gotchasModule;
+  if (typeof GotchasMemory !== 'function') GotchasMemory = null;
 } catch {
   GotchasMemory = null;
 }
@@ -94,16 +113,42 @@ class SubagentDispatcher extends EventEmitter {
     this.maxRetries = config.maxRetries || 2;
     this.retryDelay = config.retryDelay || 2000;
 
-    // Dependencies
-    this.memoryQuery = config.memoryQuery || (MemoryQuery ? new MemoryQuery() : null);
-    this.gotchasMemory = config.gotchasMemory || (GotchasMemory ? new GotchasMemory() : null);
+    // Claude CLI execution timeout (per spawn), 10 min default
+    this.claudeTimeout = config.claudeTimeout || 10 * 60 * 1000;
 
-    // Dispatch log
+    // Dispatch log (initialized before optional deps — _tryConstruct logs failures)
     this.dispatchLog = [];
     this.maxLogSize = 100;
 
-    // Root path for project
+    // Root path for project (resolved before memory deps — they need it)
     this.rootPath = config.rootPath || process.cwd();
+
+    // Agent persona resolver (F2): make every squad/framework agent addressable.
+    this.agentResolver =
+      config.agentResolver ||
+      (SquadAgentResolver ? new SquadAgentResolver(this.rootPath) : null);
+
+    // Dependencies (never let optional memory enrichment break the dispatcher)
+    this.memoryQuery = config.memoryQuery || this._tryConstruct(MemoryQuery, this.rootPath);
+    this.gotchasMemory = config.gotchasMemory || this._tryConstruct(GotchasMemory, this.rootPath);
+  }
+
+  /**
+   * Safely construct an optional dependency. Memory enrichment is best-effort:
+   * a broken/missing memory module must never break real agent dispatch.
+   * @param {Function|null} Ctor - Constructor (or null when unavailable)
+   * @param {string} rootPath - Project root passed to the constructor
+   * @returns {Object|null} - Instance or null
+   * @private
+   */
+  _tryConstruct(Ctor, rootPath) {
+    if (typeof Ctor !== 'function') return null;
+    try {
+      return new Ctor(rootPath);
+    } catch (error) {
+      this.log?.('optional_dependency_failed', { dep: Ctor.name, error: error.message });
+      return null;
+    }
   }
 
   /**
@@ -134,7 +179,13 @@ class SubagentDispatcher extends EventEmitter {
 
     // Enrich context
     const enrichedContext = await this.enrichContext(task, context);
-    dispatchRecord.contextSize = JSON.stringify(enrichedContext).length;
+    // Context may contain non-serializable/circular values injected by callers;
+    // size accounting is best-effort and must never break dispatch.
+    try {
+      dispatchRecord.contextSize = JSON.stringify(enrichedContext).length;
+    } catch {
+      dispatchRecord.contextSize = -1;
+    }
 
     // Execute with retries
     let lastError = null;
@@ -211,6 +262,12 @@ class SubagentDispatcher extends EventEmitter {
       return this.agentMapping[task.type.toLowerCase()];
     }
 
+    // F2: if the task names a real agent id directly (any of the 189 squad/
+    // framework personas), honor it instead of inferring a generic one.
+    if (this.agentResolver && task.name && this.agentResolver.has(task.name)) {
+      return `@${this.agentResolver.resolve(task.name).id}`;
+    }
+
     // Check task tags
     if (task.tags && Array.isArray(task.tags)) {
       for (const tag of task.tags) {
@@ -303,6 +360,42 @@ class SubagentDispatcher extends EventEmitter {
     }
   }
 
+  /**
+   * Resolve the fallback provider name for a given primary.
+   * Reads ai_providers.fallback / primary from the factory config instead of
+   * the old hardcoded claude<->gemini pair. Falls back safely when config or
+   * factory is unavailable.
+   * @param {string} primaryName - The provider that just failed/was unavailable.
+   * @returns {string|null} - Fallback provider name, or null if none distinct.
+   */
+  getFallbackProviderName(primaryName) {
+    let config = null;
+    if (AIProviderFactory && typeof AIProviderFactory.getConfig === 'function') {
+      try {
+        config = AIProviderFactory.getConfig();
+      } catch (error) {
+        this.log('fallback_config_error', { error: error.message });
+      }
+    }
+
+    const providers = config?.ai_providers || {};
+    const configuredFallback = providers.fallback;
+    const configuredPrimary = providers.primary;
+
+    // Prefer explicit fallback when it differs from the failing provider.
+    if (configuredFallback && configuredFallback !== primaryName) {
+      return configuredFallback;
+    }
+
+    // If the failing provider IS the configured fallback, try the primary.
+    if (configuredPrimary && configuredPrimary !== primaryName) {
+      return configuredPrimary;
+    }
+
+    // Last-resort safe default: never return the same provider that just failed.
+    return primaryName === 'claude' ? null : 'claude';
+  }
+
   /**
    * Enrich context with memory and gotchas
    * @param {Object} task - Task being dispatched
@@ -399,11 +492,25 @@ class SubagentDispatcher extends EventEmitter {
 
     // Try to use AI Provider Factory if available
     if (this.multiProviderEnabled && AIProviderFactory) {
-      return this.executeWithProvider(prompt, providerName, task);
+      return this.executeWithProvider(prompt, providerName, task, agentId);
     }
 
     // Fallback to direct Claude CLI
-    return this.executeClaude(prompt);
+    return this.executeClaude(prompt, agentId);
+  }
+
+  /**
+   * Build the env for a spawned agent process. Declares the active agent via
+   * SINAPSE_ACTIVE_AGENT so the autonomous path is observable AND the Article
+   * VIII delegation hook can enforce when the spawned agent is an orchestrator.
+   * (Interactive chat activations don't go through here — they're opt-in.)
+   * @param {string} agentId - Resolved agent id (with or without '@')
+   * @returns {Object} env additions
+   * @private
+   */
+  _agentEnv(agentId) {
+    const id = String(agentId || '').replace(/^@/, '').trim();
+    return id ? { SINAPSE_ACTIVE_AGENT: id } : {};
   }
 
   /**
@@ -413,7 +520,7 @@ class SubagentDispatcher extends EventEmitter {
    * @param {Object} task - Original task for context
    * @returns {Promise<Object>} - Execution result
    */
-  async executeWithProvider(prompt, providerName, task) {
+  async executeWithProvider(prompt, providerName, task, agentId) {
     const startTime = Date.now();
 
     // Get primary provider
@@ -422,7 +529,7 @@ class SubagentDispatcher extends EventEmitter {
     if (!provider) {
       this.log('provider_unavailable', { provider: providerName });
       // Fallback to legacy Claude execution
-      return this.executeClaude(prompt);
+      return this.executeClaude(prompt, agentId);
     }
 
     // Check availability
@@ -431,21 +538,21 @@ class SubagentDispatcher extends EventEmitter {
     if (!isAvailable) {
       this.log('provider_not_available', { provider: providerName });
 
-      // Try fallback provider
-      const fallbackName = providerName === 'claude' ? 'gemini' : 'claude';
-      const fallback = this.getAIProvider(fallbackName);
+      // Try fallback provider (config-driven, not hardcoded)
+      const fallbackName = this.getFallbackProviderName(providerName);
+      const fallback = fallbackName ? this.getAIProvider(fallbackName) : null;
 
       if (fallback && (await fallback.checkAvailability())) {
         this.log('using_fallback_provider', { original: providerName, fallback: fallbackName });
-        return this.executeWithSingleProvider(fallback, prompt, task);
+        return this.executeWithSingleProvider(fallback, prompt, task, agentId);
       }
 
       // Last resort: legacy Claude
-      return this.executeClaude(prompt);
+      return this.executeClaude(prompt, agentId);
     }
 
     // Execute with selected provider
-    return this.executeWithSingleProvider(provider, prompt, task);
+    return this.executeWithSingleProvider(provider, prompt, task, agentId);
   }
 
   /**
@@ -455,10 +562,11 @@ class SubagentDispatcher extends EventEmitter {
    * @param {Object} task - Original task
    * @returns {Promise<Object>} - Execution result
    */
-  async executeWithSingleProvider(provider, prompt, task) {
+  async executeWithSingleProvider(provider, prompt, task, agentId) {
     try {
       const response = await provider.executeWithRetry(prompt, {
         workingDir: this.rootPath,
+        env: this._agentEnv(agentId),
       });
 
       this.emit('provider_execution_complete', {
@@ -591,7 +699,29 @@ class SubagentDispatcher extends EventEmitter {
    * @returns {string} - Formatted prompt
    */
   buildPrompt(agentId, task, context) {
-    let prompt = `You are ${agentId}, a specialized agent in the SINAPSE framework.\n\n`;
+    let prompt = '';
+
+    // F2: inject the FULL real persona when the agent is known on disk. This is
+    // the difference between "act as a generic dev" and "act as Nimbus, the cloud
+    // security engineer with these exact frameworks". Falls back to the one-liner
+    // only when the agent is unknown or the resolver is unavailable.
+    let personaLoaded = false;
+    if (this.agentResolver) {
+      const persona = this.agentResolver.loadPersona(agentId);
+      if (persona && persona.trim().length > 0) {
+        prompt += '## Your Agent Definition (adopt this persona fully)\n\n';
+        prompt += persona.trim();
+        prompt += '\n\n---\n\n';
+        personaLoaded = true;
+      }
+    }
+    if (!personaLoaded) {
+      prompt += `You are ${agentId}, a specialized agent in the SINAPSE framework.\n\n`;
+    }
+
+    // Always state the role label so the dispatched run knows which agent it is,
+    // on top of (or instead of) the injected persona.
+    prompt += `## Acting as\n${agentId}\n\n`;
 
     prompt += '## Task\n';
     prompt += `**ID:** ${task.id}\n`;
@@ -642,49 +772,60 @@ class SubagentDispatcher extends EventEmitter {
   }
 
   /**
-   * Execute prompt via Claude CLI
+   * Execute prompt via Claude CLI.
+   *
+   * Hardened: the prompt is delivered through stdin (never the command line)
+   * and the process is spawned by argv via cross-spawn — so the prompt can
+   * contain quotes, pipes, `;`, `$()` or any shell metacharacter without ever
+   * being interpreted as a command (shell-injection is structurally impossible).
+   * cross-spawn also resolves `claude.cmd` on Windows (native spawn → ENOENT).
+   *
    * @param {string} prompt - Prompt to execute
-   * @returns {Promise<Object>} - Execution result
+   * @returns {Promise<Object>} - { success, output, filesModified }
    */
-  executeClaude(prompt) {
-    return new Promise((resolve, reject) => {
-      const args = ['--print', '--dangerously-skip-permissions'];
-      const escapedPrompt = prompt.replace(/'/g, "'\\''");
-      const fullCommand = `echo '${escapedPrompt}' | claude ${args.join(' ')}`;
-
-      const child = spawn('sh', ['-c', fullCommand], {
-        cwd: this.rootPath,
-        env: { ...process.env },
-        stdio: ['pipe', 'pipe', 'pipe'],
-      });
+  async executeClaude(prompt, agentId) {
+    if (!prompt || typeof prompt !== 'string') {
+      throw new Error('executeClaude requires a non-empty string prompt');
+    }
 
-      let stdout = '';
-      let stderr = '';
+    const args = ['--print', '--dangerously-skip-permissions'];
 
-      child.stdout.on('data', (data) => {
-        stdout += data.toString();
-      });
+    const result = await runSafe('claude', args, {
+      cwd: this.rootPath,
+      env: { ...process.env, ...this._agentEnv(agentId) },
+      timeout: this.claudeTimeout,
+      input: prompt,
+    });
 
-      child.stderr.on('data', (data) => {
-        stderr += data.toString();
-      });
+    const stdout = (result.stdout || '').trim();
+    const stderr = (result.stderr || '').trim();
 
-      child.on('close', (code) => {
-        if (code === 0) {
-          resolve({
-            success: true,
-            output: stdout,
-            filesModified: this.extractModifiedFiles(stdout),
-          });
-        } else {
-          reject(new Error(`Claude CLI exited with code ${code}: ${stderr || stdout}`));
-        }
-      });
+    if (result.success) {
+      return {
+        success: true,
+        output: stdout,
+        filesModified: this.extractModifiedFiles(stdout),
+      };
+    }
 
-      child.on('error', (error) => {
-        reject(error);
-      });
-    });
+    if (result.signal) {
+      throw new Error(`Claude CLI killed by signal ${result.signal}: ${stderr || stdout}`);
+    }
+
+    // User-environment hooks (SessionEnd etc.) can fail AFTER the model already
+    // printed its full response, poisoning the exit code. In --print mode a
+    // non-empty stdout + hook-related stderr means the work was done — accept it
+    // instead of discarding paid output and retrying.
+    if (stdout.length > 0 && /hook/i.test(stderr)) {
+      this.log('exit_code_poisoned_by_hook', { code: result.code, stderr: stderr.slice(0, 200) });
+      return {
+        success: true,
+        output: stdout,
+        filesModified: this.extractModifiedFiles(stdout),
+      };
+    }
+
+    throw new Error(`Claude CLI exited with code ${result.code}: ${stderr || stdout}`);
   }
 
   /**

package/.sinapse-ai/core/execution/wave-executor.js

@@ -12,7 +12,10 @@ const _path = require('path');
 // Import dependencies with fallbacks
 let WaveAnalyzer;
 try {
-  WaveAnalyzer = require('../../workflow-intelligence/engine/wave-analyzer');
+  // Named export — the module exports { WaveAnalyzer, ... }. Requiring the
+  // whole object and calling `new WaveAnalyzer()` (line ~37) would throw
+  // "not a constructor". Destructure the class.
+  ({ WaveAnalyzer } = require('../../workflow-intelligence/engine/wave-analyzer'));
 } catch {
   WaveAnalyzer = null;
 }

package/.sinapse-ai/core/grounding/README.md

@@ -1,4 +1,4 @@
-# Grounding Hooks (Story 10.47)
+# Grounding Hooks (Story 10.47 + GA-1.6)
 
 Hooks shipped by SINAPSE-AI that read user-supplied grounding sources and
 inject relevant context into agent prompts. Each hook is **opt-in**:
@@ -6,18 +6,78 @@ absence of `~/.claude/sinapse-ai-config.yaml` or `enabled: false` in the
 matching section means the hook is a complete no-op (no I/O, no warnings,
 no errors).
 
-| Hook | Reads | Behavior when disabled |
-|------|-------|------------------------|
-| `vault.cjs` | `~/.claude/sinapse-ai-config.yaml` → `grounding.vault` | no-op |
-| `design-system.cjs` | `~/.claude/sinapse-ai-config.yaml` → `grounding.designSystem` | no-op |
-| `brand.cjs` | `~/.claude/sinapse-ai-config.yaml` → `grounding.brand` | no-op |
+## Architecture: Two layers
+
+### Layer 1 — Executable hooks (`.sinapse-ai/hooks/`, story GA-1.6) ✅ ACTIVE
+
+These are the hooks Claude Code actually runs via `UserPromptSubmit`. They
+read real files and inject context into prompts. Registered automatically
+during `npx sinapse-ai install` into `~/.claude/settings.json`.
+
+| Executable hook | Reads | Injects |
+|-----------------|-------|---------|
+| `sinapse-vault-grounding.cjs` | `grounding.vault.path` → top-5 `.md` notes | `<vault-grounding>` |
+| `sinapse-ds-grounding.cjs` | `grounding.designSystem.rootPath` → DS law file | `<ds-grounding>` |
+| `sinapse-brand-grounding.cjs` | `grounding.brand.brandbookPath` → brandbook | `<brand-grounding>` |
+
+**Caller:** `bin/lib/register-grounding-hooks.js` (invoked by `bin/commands/install.js`
+phase 6b). Hook registration is idempotent and non-destructive.
+
+### Layer 2 — Library resolvers (`core/grounding/`, story 10.47) — DEFER
+
+These library stubs (`vault.cjs`, `design-system.cjs`, `brand.cjs`) are
+shallow wrappers around `config-loader.cjs`. They return a structured envelope
+describing what is configured, but do **not** inject context into prompts.
+
+**Why defer:** The executable hooks in Layer 1 (GA-1.6) already implement
+the concrete content injection logic directly. The library resolvers were
+designed as the "integration point" for future use cases where something
+other than the Claude Code hook chain needs to consume grounding data
+(e.g., a CLI command, a report generator, or a programmatic API). No such
+consumer exists today.
+
+**Trigger to activate library resolvers:** a concrete caller (e.g., a new
+CLI sub-command `sinapse grounding status`, or a report generator) that
+needs to query grounding config programmatically. At that point, extend
+`vault.cjs` / `design-system.cjs` / `brand.cjs` to read actual files and
+return rich structured data. Do **not** create a caller just to justify
+activating these resolvers (Article XI — no orphans).
+
+**Current callers of library resolvers:** `bin/lib/prompts.js` and
+`bin/commands/update.js` import `grounding-config` (the wizard package, not
+these library hooks). The library hooks themselves have no production caller
+beyond their own test suite.
+
+| Library resolver | Status | Defer trigger |
+|-----------------|--------|---------------|
+| `vault.cjs` | stub — returns config envelope | new CLI/API consumer |
+| `design-system.cjs` | stub — returns config envelope | new CLI/API consumer |
+| `brand.cjs` | stub — returns config envelope | new CLI/API consumer |
+| `config-loader.cjs` | functional — reads YAML | used by all three stubs |
+
+---
+
+## Configuration
 
 Configure interactively via `npx sinapse-ai install` (Story 10.46+10.47
 wizard) or by editing the YAML file directly. See
 `docs/guides/grounding-setup.md` for the full guide.
 
-> Note: this story establishes the **shipping foundation** for grounding
-> hooks (config schema, no-op default, entry point). The concrete domain
-> integration logic (vault parser, DS lookup, brandbook reader) is
-> deliberately out-of-scope and will land in follow-up stories per
-> grounding type.
+`~/.claude/sinapse-ai-config.yaml` schema:
+
+```yaml
+version: '1'
+grounding:
+  vault:
+    enabled: true
+    path: /abs/path/to/vault
+    domains: [sinapse, personal]
+  designSystem:
+    enabled: true
+    profileName: SINAPSE
+    rootPath: /abs/path/to/brandbook
+  brand:
+    enabled: true
+    profileName: SINAPSE
+    brandbookPath: /abs/path/to/brandbook/0.0-guidelines.md
+```

package/.sinapse-ai/core/health-check/checks/project/framework-config.js

@@ -45,7 +45,7 @@ class FrameworkConfigCheck extends BaseCheck {
       severity: CheckSeverity.HIGH,
       timeout: 3000,
       cacheable: true,
-      healingTier: 0, // Cannot auto-fix framework setup
+      healingTier: 1, // Can auto-create .sinapse local config dir
       tags: ['sinapse', 'config', 'framework'],
     });
   }
@@ -111,7 +111,9 @@ class FrameworkConfigCheck extends BaseCheck {
     if (missingRecommended.length > 0) {
       const missing = missingRecommended.map((c) => c.path).join(', ');
       return this.warning(`Missing recommended configuration: ${missing}`, {
-        recommendation: 'Consider adding recommended configuration for full SINAPSE functionality',
+        recommendation: 'Run health check with --fix to create missing recommended configuration',
+        healable: true,
+        healingTier: 1,
         details: {
           missingRecommended: missingRecommended.map((c) => ({
             path: c.path,
@@ -126,6 +128,40 @@ class FrameworkConfigCheck extends BaseCheck {
       details: { found: found.map((c) => c.path) },
     });
   }
+
+  /**
+   * Get healer for this check
+   * @returns {Object} Healer configuration
+   */
+  getHealer() {
+    return {
+      name: 'create-sinapse-local-config',
+      action: 'create-config',
+      successMessage: 'Created .sinapse local configuration directory',
+      fix: async (_result) => {
+        const projectRoot = process.cwd();
+        const sinapseDir = path.join(projectRoot, '.sinapse');
+
+        await fs.mkdir(sinapseDir, { recursive: true });
+
+        const configPath = path.join(sinapseDir, 'config.yaml');
+        try {
+          await fs.access(configPath);
+        } catch {
+          // Create minimal config stub if it doesn't exist
+          const stub = [
+            '# SINAPSE local configuration',
+            '# Generated by SINAPSE Health Check auto-heal',
+            'permissions:',
+            '  mode: ask',
+          ].join('\n') + '\n';
+          await fs.writeFile(configPath, stub, 'utf8');
+        }
+
+        return { success: true, message: 'Created .sinapse/config.yaml' };
+      },
+    };
+  }
 }
 
 module.exports = FrameworkConfigCheck;

package/.sinapse-ai/core/health-check/checks/project/package-json.js

@@ -28,7 +28,7 @@ class PackageJsonCheck extends BaseCheck {
       severity: CheckSeverity.CRITICAL,
       timeout: 2000,
       cacheable: true,
-      healingTier: 0, // Cannot auto-fix missing/invalid package.json
+      healingTier: 1, // Can auto-patch cosmetic fields (name/version stubs) when JSON is valid
       tags: ['npm', 'config', 'required'],
     });
   }
@@ -70,8 +70,10 @@ class PackageJsonCheck extends BaseCheck {
 
       if (issues.length > 0) {
         return this.warning(`package.json has issues: ${issues.join(', ')}`, {
-          recommendation: 'Fix the package.json fields to match npm requirements',
-          details: { issues, path: packagePath },
+          recommendation: 'Run health check with --fix to patch missing fields',
+          healable: true,
+          healingTier: 1,
+          details: { issues, path: packagePath, packagePath },
         });
       }
 
@@ -100,6 +102,48 @@ class PackageJsonCheck extends BaseCheck {
       return this.error(`Failed to read package.json: ${error.message}`, error);
     }
   }
+
+  /**
+   * Get healer for this check
+   * Patches stub name/version fields when JSON is valid but incomplete
+   * @returns {Object} Healer configuration
+   */
+  getHealer() {
+    return {
+      name: 'patch-package-json-fields',
+      action: 'patch-fields',
+      successMessage: 'Patched missing package.json fields with safe defaults',
+      targetFile: 'package.json',
+      fix: async (_result) => {
+        const projectRoot = process.cwd();
+        const packagePath = path.join(projectRoot, 'package.json');
+
+        const content = await fs.readFile(packagePath, 'utf8');
+        const packageJson = JSON.parse(content);
+
+        let patched = false;
+
+        if (!packageJson.name) {
+          packageJson.name = path.basename(projectRoot).toLowerCase().replace(/[^a-z0-9-]/g, '-');
+          patched = true;
+        }
+
+        if (!packageJson.version) {
+          packageJson.version = '0.1.0';
+          patched = true;
+        }
+
+        if (patched) {
+          await fs.writeFile(packagePath, JSON.stringify(packageJson, null, 2) + '\n', 'utf8');
+        }
+
+        return {
+          success: true,
+          message: patched ? 'Patched package.json with stub fields' : 'No patches needed',
+        };
+      },
+    };
+  }
 }
 
 module.exports = PackageJsonCheck;