@soleri/core 9.11.0 → 9.13.0

package/src/__tests__/subagent/process-lifecycle.test.ts

@@ -0,0 +1,422 @@
+/**
+ * Process lifecycle integration tests.
+ *
+ * These tests spawn real child processes to verify orphan detection,
+ * kill escalation, process group management, and the full dispatch
+ * lifecycle. No mocking of process.kill — real signals, real PIDs.
+ */
+
+import { describe, it, expect, afterEach } from 'vitest';
+import { spawn, ChildProcess, execSync } from 'node:child_process';
+import { OrphanReaper } from '../../subagent/orphan-reaper.js';
+
+// Collect all spawned processes for cleanup
+const spawnedChildren: ChildProcess[] = [];
+
+/** Spawn a long-running node process that does nothing. */
+function spawnIdleProcess(opts?: { detached?: boolean }): ChildProcess {
+  const child = spawn('node', ['-e', 'setInterval(()=>{},1000)'], {
+    stdio: 'ignore',
+    detached: opts?.detached ?? false,
+  });
+  spawnedChildren.push(child);
+  return child;
+}
+
+/** Spawn a parent that spawns a grandchild, both idle. */
+function spawnWithGrandchild(): ChildProcess {
+  // The parent spawns a child which also idles.
+  // Using detached so the parent becomes a process group leader.
+  const child = spawn(
+    'node',
+    [
+      '-e',
+      `
+      const { spawn } = require('child_process');
+      const gc = spawn('node', ['-e', 'setInterval(()=>{},1000)'], { stdio: 'ignore' });
+      // Write grandchild PID to stdout so the test can track it
+      process.stdout.write(String(gc.pid));
+      setInterval(()=>{}, 1000);
+    `,
+    ],
+    {
+      stdio: ['ignore', 'pipe', 'ignore'],
+      detached: true,
+    },
+  );
+  spawnedChildren.push(child);
+  return child;
+}
+
+/** Check if a PID is alive using signal 0. */
+function isAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Wait until a condition is true, polling every intervalMs. */
+async function waitFor(fn: () => boolean, timeoutMs = 10_000, intervalMs = 100): Promise<void> {
+  const start = Date.now();
+  while (!fn()) {
+    if (Date.now() - start > timeoutMs) {
+      throw new Error(`waitFor timed out after ${timeoutMs}ms`);
+    }
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+}
+
+/** Force-kill a PID, ignoring errors if already dead. */
+function safeKill(pid: number, signal: NodeJS.Signals = 'SIGKILL'): void {
+  try {
+    process.kill(pid, signal);
+  } catch {
+    // already dead — fine
+  }
+}
+
+afterEach(() => {
+  // Kill every process we spawned, best-effort
+  for (const child of spawnedChildren) {
+    if (child.pid) {
+      // Try group kill first (for detached), then single
+      try {
+        process.kill(-child.pid, 'SIGKILL');
+      } catch {
+        safeKill(child.pid);
+      }
+    }
+  }
+  spawnedChildren.length = 0;
+});
+
+describe('Process Lifecycle Integration', { timeout: 15_000 }, () => {
+  // ── a. Orphan detection ─────────────────────────────────────────
+
+  describe('orphan detection', () => {
+    it('detects a killed process via reap()', async () => {
+      const child = spawnIdleProcess();
+      const pid = child.pid!;
+      expect(pid).toBeGreaterThan(0);
+
+      const reaper = new OrphanReaper();
+      reaper.register(pid, 'orphan-test');
+
+      // Process should be alive initially
+      expect(isAlive(pid)).toBe(true);
+      const initialReap = reaper.reap();
+      expect(initialReap.reaped).toHaveLength(0);
+      expect(reaper.isTracked(pid)).toBe(true);
+
+      // Kill it externally
+      process.kill(pid, 'SIGKILL');
+      await waitFor(() => !isAlive(pid));
+
+      // Now reap should detect it
+      const result = reaper.reap();
+      expect(result.reaped).toHaveLength(1);
+      expect(result.reaped[0]).toBe('orphan-test');
+      expect(reaper.isTracked(pid)).toBe(false);
+    });
+
+    it('invokes onOrphan callback for dead processes', async () => {
+      const orphanEvents: Array<{ taskId: string; pid: number }> = [];
+      const reaper = new OrphanReaper((taskId, pid) => {
+        orphanEvents.push({ taskId, pid });
+      });
+
+      const child = spawnIdleProcess();
+      const pid = child.pid!;
+      reaper.register(pid, 'callback-test');
+
+      process.kill(pid, 'SIGKILL');
+      await waitFor(() => !isAlive(pid));
+
+      reaper.reap();
+      expect(orphanEvents).toHaveLength(1);
+      expect(orphanEvents[0]).toEqual({ taskId: 'callback-test', pid });
+    });
+
+    it('handles multiple tracked processes with mixed liveness', async () => {
+      const alive = spawnIdleProcess();
+      const dead = spawnIdleProcess();
+      const alivePid = alive.pid!;
+      const deadPid = dead.pid!;
+
+      const reaper = new OrphanReaper();
+      reaper.register(alivePid, 'alive-task');
+      reaper.register(deadPid, 'dead-task');
+
+      // Kill only one
+      process.kill(deadPid, 'SIGKILL');
+      await waitFor(() => !isAlive(deadPid));
+
+      const result = reaper.reap();
+      expect(result.reaped).toHaveLength(1);
+      expect(result.reaped[0]).toBe('dead-task');
+      expect(reaper.isTracked(alivePid)).toBe(true);
+      expect(reaper.isTracked(deadPid)).toBe(false);
+    });
+  });
+
+  // ── b. Timeout escalation (killProcessGroup with SIGKILL) ──────
+
+  describe('kill escalation', () => {
+    it('kills a process with SIGTERM via killProcessGroup', async () => {
+      const child = spawnIdleProcess({ detached: true });
+      const pid = child.pid!;
+
+      const reaper = new OrphanReaper();
+      reaper.register(pid, 'kill-test');
+
+      const result = reaper.killProcessGroup(pid, 'SIGTERM');
+      expect(result.killed).toBe(true);
+
+      await waitFor(() => !isAlive(pid));
+      expect(isAlive(pid)).toBe(false);
+    });
+
+    it('escalates to SIGKILL when SIGTERM is ignored', async () => {
+      // Spawn a process that traps SIGTERM
+      const child = spawn(
+        'node',
+        ['-e', "process.on('SIGTERM', () => {}); setInterval(()=>{},1000)"],
+        { stdio: 'ignore', detached: true },
+      );
+      spawnedChildren.push(child);
+      const pid = child.pid!;
+
+      const reaper = new OrphanReaper();
+      reaper.register(pid, 'escalation-test');
+
+      // Send SIGTERM — process should still be alive after a short wait
+      reaper.killProcessGroup(pid, 'SIGTERM');
+      await new Promise((r) => setTimeout(r, 500));
+
+      // Process should still be alive (it traps SIGTERM)
+      if (isAlive(pid)) {
+        // Escalate to SIGKILL
+        const result = reaper.killProcessGroup(pid, 'SIGKILL');
+        expect(result.killed).toBe(true);
+        await waitFor(() => !isAlive(pid));
+        expect(isAlive(pid)).toBe(false);
+      }
+      // If it died from SIGTERM that's fine too — OS-dependent behavior
+    });
+
+    it('killProcessGroup returns killed:false for already-dead process', async () => {
+      const child = spawnIdleProcess({ detached: true });
+      const pid = child.pid!;
+
+      // Kill it first
+      process.kill(pid, 'SIGKILL');
+      await waitFor(() => !isAlive(pid));
+
+      const reaper = new OrphanReaper();
+      const result = reaper.killProcessGroup(pid, 'SIGTERM');
+      // Should indicate failure since process is dead
+      expect(result.killed).toBe(false);
+    });
+  });
+
+  // ── c. Process group kill ──────────────────────────────────────
+
+  describe('process group management', () => {
+    it('killProcessGroup kills the parent process group', async () => {
+      const child = spawnIdleProcess({ detached: true });
+      const pid = child.pid!;
+
+      const reaper = new OrphanReaper();
+      const result = reaper.killProcessGroup(pid);
+
+      expect(result.killed).toBe(true);
+      // Windows doesn't support negative-PID group signals, falls back to 'single'
+      expect(result.method).toBe(process.platform === 'win32' ? 'single' : 'group');
+
+      await waitFor(() => !isAlive(pid));
+      expect(isAlive(pid)).toBe(false);
+    });
+
+    it('killProcessGroup with grandchild kills the entire tree', async () => {
+      const parent = spawnWithGrandchild();
+      const parentPid = parent.pid!;
+
+      // Read grandchild PID from stdout
+      const grandchildPid = await new Promise<number>((resolve, reject) => {
+        let data = '';
+        const timer = setTimeout(() => reject(new Error('timeout reading grandchild PID')), 5000);
+        parent.stdout!.on('data', (chunk: Buffer) => {
+          data += chunk.toString();
+          const pid = parseInt(data, 10);
+          if (!isNaN(pid) && pid > 0) {
+            clearTimeout(timer);
+            resolve(pid);
+          }
+        });
+        parent.on('error', (err) => {
+          clearTimeout(timer);
+          reject(err);
+        });
+      });
+
+      expect(isAlive(parentPid)).toBe(true);
+      expect(isAlive(grandchildPid)).toBe(true);
+
+      // Kill the process group
+      const reaper = new OrphanReaper();
+      const result = reaper.killProcessGroup(parentPid, 'SIGKILL');
+      expect(result.killed).toBe(true);
+      // Windows doesn't support negative-PID group signals, falls back to 'single'
+      expect(result.method).toBe(process.platform === 'win32' ? 'single' : 'group');
+
+      // Both parent and grandchild should be dead
+      await waitFor(() => !isAlive(parentPid) && !isAlive(grandchildPid), 5000);
+      expect(isAlive(parentPid)).toBe(false);
+      expect(isAlive(grandchildPid)).toBe(false);
+    });
+
+    it('killAll kills all tracked processes', async () => {
+      const child1 = spawnIdleProcess({ detached: true });
+      const child2 = spawnIdleProcess({ detached: true });
+      const pid1 = child1.pid!;
+      const pid2 = child2.pid!;
+
+      const reaper = new OrphanReaper();
+      reaper.register(pid1, 'task-1');
+      reaper.register(pid2, 'task-2');
+
+      const results = reaper.killAll('SIGKILL');
+
+      expect(results.size).toBe(2);
+      expect(results.get(pid1)!.killed).toBe(true);
+      expect(results.get(pid2)!.killed).toBe(true);
+
+      // Tracking should be cleared
+      expect(reaper.listTracked()).toHaveLength(0);
+
+      await waitFor(() => !isAlive(pid1) && !isAlive(pid2));
+      expect(isAlive(pid1)).toBe(false);
+      expect(isAlive(pid2)).toBe(false);
+    });
+
+    it('killAll handles empty tracking gracefully', () => {
+      const reaper = new OrphanReaper();
+      const results = reaper.killAll();
+      expect(results.size).toBe(0);
+    });
+  });
+
+  // ── d. Full lifecycle ─────────────────────────────────────────
+
+  describe('full lifecycle', () => {
+    it('register → kill externally → reap → verify cleanup', async () => {
+      const reaper = new OrphanReaper();
+
+      // Simulate a dispatch wave: register multiple processes
+      const children = [spawnIdleProcess(), spawnIdleProcess(), spawnIdleProcess()];
+      const pids = children.map((c) => c.pid!);
+
+      pids.forEach((pid, i) => reaper.register(pid, `wave-task-${i}`));
+      expect(reaper.listTracked()).toHaveLength(3);
+
+      // All alive initially
+      const earlyReap = reaper.reap();
+      expect(earlyReap.reaped).toHaveLength(0);
+
+      // Kill two of three externally
+      process.kill(pids[0], 'SIGKILL');
+      process.kill(pids[2], 'SIGKILL');
+      await waitFor(() => !isAlive(pids[0]) && !isAlive(pids[2]));
+
+      // Reap should detect the two dead ones
+      const result = reaper.reap();
+      expect(result.reaped).toHaveLength(2);
+      expect(result.reaped.sort()).toEqual(['wave-task-0', 'wave-task-2']);
+
+      // One should still be tracked
+      expect(reaper.listTracked()).toHaveLength(1);
+      expect(reaper.isTracked(pids[1])).toBe(true);
+
+      // Clean up the survivor
+      reaper.killAll('SIGKILL');
+      expect(reaper.listTracked()).toHaveLength(0);
+    });
+
+    it('reap in finally block pattern works correctly', async () => {
+      const reaper = new OrphanReaper();
+      const child = spawnIdleProcess();
+      const pid = child.pid!;
+      reaper.register(pid, 'finally-test');
+
+      let reapedInFinally: ReturnType<typeof reaper.reap> | null = null;
+
+      try {
+        // Simulate dispatch work
+        process.kill(pid, 'SIGKILL');
+        await waitFor(() => !isAlive(pid));
+      } finally {
+        // This is what orchestrate-ops.ts does in the finally block
+        reapedInFinally = reaper.reap();
+      }
+
+      expect(reapedInFinally!.reaped).toHaveLength(1);
+      expect(reapedInFinally!.reaped[0]).toBe('finally-test');
+      expect(reaper.listTracked()).toHaveLength(0);
+    });
+  });
+
+  // ── e. Facade integration (admin_reap_orphans structure) ──────
+
+  describe('admin facade integration', () => {
+    it('dispatcher.reapOrphans() returns correct report structure', async () => {
+      // We test the dispatcher's reapOrphans method shape which is what
+      // admin_reap_orphans calls. We create an OrphanReaper directly since
+      // the dispatcher requires a full RuntimeAdapterRegistry.
+
+      const reaper = new OrphanReaper();
+      const child = spawnIdleProcess();
+      const pid = child.pid!;
+      reaper.register(pid, 'facade-test');
+
+      // Kill it
+      process.kill(pid, 'SIGKILL');
+      await waitFor(() => !isAlive(pid));
+
+      // Simulate what dispatcher.reapOrphans() does internally
+      const result = reaper.reap();
+
+      // reap() returns { reaped: string[], alive: string[] }
+      expect(result.reaped).toHaveLength(1);
+      expect(result.reaped[0]).toBe('facade-test');
+      expect(result.alive).toHaveLength(0);
+
+      // Verify report structure matches what admin_reap_orphans builds
+      const report = {
+        reaped: result.reaped.length,
+        tasks: result.reaped,
+      };
+
+      expect(report.reaped).toBe(1);
+      expect(report.tasks).toEqual(['facade-test']);
+    });
+
+    it('returns empty report when no orphans exist', () => {
+      const reaper = new OrphanReaper();
+      const child = spawnIdleProcess();
+      reaper.register(child.pid!, 'alive-task');
+
+      // All alive — reap returns nothing reaped
+      const result = reaper.reap();
+      const report = {
+        reaped: result.reaped.length,
+        tasks: result.reaped,
+      };
+
+      expect(report).toEqual({ reaped: 0, tasks: [] });
+      expect(result.alive).toHaveLength(1);
+    });
+  });
+});

package/src/__tests__/subagent/workspace-resolver.test.ts

@@ -54,7 +54,7 @@ describe('WorkspaceResolver', () => {
     warnSpy.mockRestore();
   });
 
-  it('cleanup() calls git worktree remove and git branch -D', () => {
+  it('cleanup() calls git worktree remove and git branch -D but not git push', () => {
     (execSync as ReturnType<typeof vi.fn>).mockReturnValue('');
 
     // First create a worktree
@@ -71,6 +71,11 @@ describe('WorkspaceResolver', () => {
       expect.stringContaining('git branch -D'),
       expect.objectContaining({ cwd: baseDir }),
     );
+    // Worktree branches are local-only — should NOT push to remote
+    expect(execSync).not.toHaveBeenCalledWith(
+      expect.stringContaining('git push'),
+      expect.anything(),
+    );
   });
 
   it('cleanup() silently handles errors', () => {

package/src/adapters/types.ts

@@ -47,6 +47,8 @@ export interface AdapterExecutionResult {
   exitCode: number;
   /** Whether execution timed out */
   timedOut?: boolean;
+  /** PID of the spawned child process (if available) */
+  pid?: number;
   /** Token usage */
   usage?: AdapterTokenUsage;
   /** Session state to persist for next run */

package/src/brain/brain.ts

@@ -10,7 +10,8 @@ import {
   cosineSimilarity,
   jaccardSimilarity,
 } from '../text/similarity.js';
-import { rowToEntry } from '../vault/vault-entries.js';
+import { rowToEntry, cosineSearch, getVector } from '../vault/vault-entries.js';
+import type { EmbeddingProvider } from '../embeddings/types.js';
 import type {
   ScoringWeights,
   ScoreBreakdown,
@@ -33,6 +34,21 @@ const SEVERITY_SCORES: Record<string, number> = {
   suggestion: 0.4,
 };
 
+// ─── Vector cosine similarity (dense float arrays) ────────────────
+
+function vectorCosineSimilarity(a: number[], b: number[]): number {
+  if (a.length !== b.length || a.length === 0) return 0;
+  let dot = 0,
+    normA = 0,
+    normB = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+    normA += a[i] * a[i];
+    normB += b[i] * b[i];
+  }
+  return dot / (Math.sqrt(normA) * Math.sqrt(normB) || 1);
+}
+
 // ─── Brain Class ─────────────────────────────────────────────────
 
 const DEFAULT_WEIGHTS: ScoringWeights = {
@@ -44,6 +60,16 @@ const DEFAULT_WEIGHTS: ScoringWeights = {
   domainMatch: 0.15,
 };
 
+/** Weights used when an embedding provider is active — vector gets 0.15, semantic drops to 0.25. */
+const DEFAULT_WEIGHTS_HYBRID: ScoringWeights = {
+  semantic: 0.25,
+  vector: 0.15,
+  severity: 0.15,
+  temporalDecay: 0.15,
+  tagOverlap: 0.15,
+  domainMatch: 0.15,
+};
+
 const WEIGHT_BOUND = 0.15;
 const FEEDBACK_THRESHOLD = 30;
 const DUPLICATE_BLOCK_THRESHOLD = 0.8;
@@ -53,16 +79,24 @@ const RECENCY_HALF_LIFE_DAYS = 365;
 export class Brain {
   private vault: Vault;
   private vaultManager: VaultManager | undefined;
+  private embeddingProvider: EmbeddingProvider | undefined;
   private vocabulary: Map<string, number> = new Map();
   private weights: ScoringWeights = { ...DEFAULT_WEIGHTS };
 
-  constructor(vault: Vault, vaultManager?: VaultManager) {
+  constructor(vault: Vault, vaultManager?: VaultManager, embeddingProvider?: EmbeddingProvider) {
     this.vault = vault;
     this.vaultManager = vaultManager;
+    this.embeddingProvider = embeddingProvider;
     this.loadVocabularyFromDb();
     this.recomputeWeights();
   }
 
+  /** Set or replace the embedding provider at runtime. */
+  setEmbeddingProvider(provider: EmbeddingProvider | undefined): void {
+    this.embeddingProvider = provider;
+    this.recomputeWeights();
+  }
+
   async intelligentSearch(query: string, options?: SearchOptions): Promise<RankedResult[]> {
     const limit = options?.limit ?? 10;
     const fetchLimit = Math.max(limit * 3, 30);
@@ -91,9 +125,8 @@ export class Brain {
       });
     }
 
-    if (rawResults.length === 0) return [];
+    if (rawResults.length === 0 && !this.embeddingProvider) return [];
 
-    const seedCount = rawResults.length;
     const queryTokens = tokenize(query);
     const queryTags = options?.tags ?? [];
     const queryDomain = options?.domain;
@@ -105,9 +138,53 @@ export class Brain {
         ? calculateTfIdf(queryTokens, this.vocabulary)
         : null;
 
+    // ── Vector recall: embed query and merge cosineSearch candidates ──
+    let queryEmbedding: number[] | null = null;
+    const vectorSimilarityMap = new Map<string, number>();
+
+    if (this.embeddingProvider) {
+      try {
+        const embResult = await this.embeddingProvider.embed([query]);
+        if (embResult.vectors.length > 0 && embResult.vectors[0].length > 0) {
+          queryEmbedding = embResult.vectors[0];
+          const provider = this.vault.getProvider();
+          const vectorHits = cosineSearch(provider, queryEmbedding, fetchLimit);
+
+          // Build similarity lookup and merge vector-only candidates into rawResults
+          const ftsIds = new Set(rawResults.map((r) => r.entry.id));
+          for (const hit of vectorHits) {
+            vectorSimilarityMap.set(hit.entryId, hit.similarity);
+            if (!ftsIds.has(hit.entryId)) {
+              // Vector-only candidate — fetch full entry and add to pool
+              const entry = this.vault.get(hit.entryId);
+              if (entry) {
+                rawResults.push({ entry, score: hit.similarity });
+              }
+            }
+          }
+        }
+      } catch {
+        // Embedding failed — graceful degradation, continue with FTS-only
+      }
+    }
+
+    if (rawResults.length === 0) return [];
+
+    const seedCount = rawResults.length;
+
     const ranked = rawResults.map((result) => {
       const entry = result.entry;
-      const breakdown = this.scoreEntry(entry, queryTokens, queryTags, queryDomain, now, queryVec);
+      const vectorSim = vectorSimilarityMap.get(entry.id) ?? null;
+      const breakdown = this.scoreEntry(
+        entry,
+        queryTokens,
+        queryTags,
+        queryDomain,
+        now,
+        queryVec,
+        queryEmbedding,
+        vectorSim,
+      );
       return { entry, score: breakdown.total, breakdown };
     });
 
@@ -499,6 +576,8 @@ export class Brain {
     queryDomain: string | undefined,
     now: number,
     queryVec: Map<string, number> | null = null,
+    queryEmbedding: number[] | null = null,
+    precomputedVectorSim: number | null = null,
   ): ScoreBreakdown {
     const w = this.weights;
 
@@ -523,7 +602,22 @@ export class Brain {
 
     const domainMatch = queryDomain && entry.domain === queryDomain ? 1.0 : 0;
 
-    const vector = 0;
+    // Use precomputed cosine similarity from the vector recall phase when available.
+    // If we have a query embedding but no precomputed similarity (entry wasn't in
+    // cosineSearch results), try to compute it from the entry's stored vector.
+    let vector = 0;
+    if (precomputedVectorSim !== null) {
+      vector = precomputedVectorSim;
+    } else if (queryEmbedding) {
+      try {
+        const stored = getVector(this.vault.getProvider(), entry.id);
+        if (stored) {
+          vector = vectorCosineSimilarity(queryEmbedding, stored.vector);
+        }
+      } catch {
+        // No stored vector — vector stays 0
+      }
+    }
 
     const total =
       w.semantic * semantic +
@@ -681,7 +775,9 @@ export class Brain {
       }
     ).count;
     if (feedbackCount < FEEDBACK_THRESHOLD) {
-      this.weights = { ...DEFAULT_WEIGHTS };
+      this.weights = this.embeddingProvider
+        ? { ...DEFAULT_WEIGHTS_HYBRID }
+        : { ...DEFAULT_WEIGHTS };
       return;
     }
 
@@ -707,8 +803,20 @@ export class Brain {
       DEFAULT_WEIGHTS.semantic + WEIGHT_BOUND,
     );
 
-    // vector stays 0 in base weights (only active during hybrid search)
-    newWeights.vector = 0;
+    // When no embedding provider is configured, vector weight stays 0.
+    // When provider IS available, vector participates in weight adaptation.
+    if (!this.embeddingProvider) {
+      newWeights.vector = 0;
+    } else {
+      // With embeddings active, give vector a meaningful default weight
+      // by redistributing from semantic (the closest signal).
+      newWeights.vector = DEFAULT_WEIGHTS_HYBRID.vector;
+      newWeights.semantic = clamp(
+        newWeights.semantic - DEFAULT_WEIGHTS_HYBRID.vector,
+        DEFAULT_WEIGHTS.semantic - WEIGHT_BOUND,
+        DEFAULT_WEIGHTS.semantic + WEIGHT_BOUND,
+      );
+    }
 
     const remaining = 1.0 - newWeights.semantic - newWeights.vector;
     const otherSum =