@soleri/core 9.11.0 → 9.13.0

package/src/skills/__tests__/sync-skills.test.ts

@@ -0,0 +1,132 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { mkdirSync, writeFileSync, rmSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+// =============================================================================
+// HELPERS
+// =============================================================================
+
+let sourceDir: string;
+let fakeHome: string;
+
+function setup(): void {
+  const base = join(tmpdir(), `soleri-sync-test-${Date.now()}`);
+  mkdirSync(base, { recursive: true });
+
+  sourceDir = join(base, 'source-skills');
+  mkdirSync(sourceDir, { recursive: true });
+
+  fakeHome = join(base, 'fake-home');
+  mkdirSync(join(fakeHome, '.claude', 'skills'), { recursive: true });
+}
+
+function teardown(): void {
+  if (fakeHome) {
+    const base = join(fakeHome, '..');
+    rmSync(base, { recursive: true, force: true });
+  }
+}
+
+/** Create a source skill directory with a minimal SKILL.md */
+function createSourceSkill(name: string, content?: string): string {
+  const dir = join(sourceDir, name);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(
+    join(dir, 'SKILL.md'),
+    content ?? `---\nname: ${name}\n---\n\n# ${name}\n\nA test skill.\n`,
+  );
+  return dir;
+}
+
+/** Create a directory in the fake ~/.claude/skills/ target */
+function createTargetSkillDir(name: string): string {
+  const dir = join(fakeHome, '.claude', 'skills', name);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, 'SKILL.md'), `---\nname: ${name}\n---\n\nStale skill.\n`);
+  return dir;
+}
+
+function targetSkillsDir(): string {
+  return join(fakeHome, '.claude', 'skills');
+}
+
+function targetDirExists(name: string): boolean {
+  return existsSync(join(targetSkillsDir(), name));
+}
+
+// =============================================================================
+// TESTS
+// =============================================================================
+
+describe('syncSkillsToClaudeCode — orphan cleanup', () => {
+  beforeEach(() => {
+    setup();
+    // Mock homedir() so syncSkillsToClaudeCode writes to our temp directory
+    vi.mock('node:os', async (importOriginal) => {
+      const original = await importOriginal<typeof import('node:os')>();
+      return {
+        ...original,
+        homedir: () => fakeHome,
+      };
+    });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    teardown();
+  });
+
+  it('removes orphan directories that match the agent prefix', async () => {
+    // Source has "my-skill", target has stale "test-agent-old-skill"
+    createSourceSkill('my-skill');
+    createTargetSkillDir('test-agent-old-skill');
+
+    const { syncSkillsToClaudeCode } = await import('../sync-skills.js');
+    const result = syncSkillsToClaudeCode([sourceDir], 'Test Agent');
+
+    // The orphan should be reported as removed
+    expect(result.removed).toContain('test-agent-old-skill');
+    // The orphan directory should be gone
+    expect(targetDirExists('test-agent-old-skill')).toBe(false);
+  });
+
+  it('does NOT remove directories that do not match the agent prefix', async () => {
+    createSourceSkill('my-skill');
+    // "other-agent-skill" does NOT start with "test-agent-"
+    createTargetSkillDir('other-agent-skill');
+
+    const { syncSkillsToClaudeCode } = await import('../sync-skills.js');
+    const result = syncSkillsToClaudeCode([sourceDir], 'Test Agent');
+
+    // Should still exist — not our prefix
+    expect(targetDirExists('other-agent-skill')).toBe(true);
+    expect(result.removed).not.toContain('other-agent-skill');
+  });
+
+  it('does NOT remove a skill directory that was just synced', async () => {
+    createSourceSkill('active-skill');
+    // This directory matches the prefix AND is a current skill
+    createTargetSkillDir('test-agent-active-skill');
+
+    const { syncSkillsToClaudeCode } = await import('../sync-skills.js');
+    const result = syncSkillsToClaudeCode([sourceDir], 'Test Agent');
+
+    // "active-skill" should be synced (installed/updated/skipped), not removed
+    const synced = [...result.installed, ...result.updated, ...result.skipped];
+    expect(synced).toContain('active-skill');
+    expect(result.removed).not.toContain('test-agent-active-skill');
+    expect(targetDirExists('test-agent-active-skill')).toBe(true);
+  });
+
+  it('returns an empty removed array when there are no orphans', async () => {
+    createSourceSkill('only-skill');
+
+    const { syncSkillsToClaudeCode } = await import('../sync-skills.js');
+    const result = syncSkillsToClaudeCode([sourceDir], 'Test Agent');
+
+    expect(result.removed).toBeDefined();
+    expect(Array.isArray(result.removed)).toBe(true);
+    expect(result.removed).toHaveLength(0);
+  });
+});

package/src/skills/step-tracker.ts

@@ -0,0 +1,162 @@
+/**
+ * Skill step tracker — converts skills from suggestions to enforceable protocols.
+ * Persists step state to .soleri/skill-runs/ for context compaction survival.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type EvidenceType = 'tool_called' | 'file_exists';
+
+export interface SkillStep {
+  id: string;
+  description: string;
+  evidence: EvidenceType;
+}
+
+export interface StepEvidence {
+  type: EvidenceType;
+  value: string;
+  timestamp: string;
+  verified: boolean;
+}
+
+export interface SkillStepTracker {
+  skillName: string;
+  runId: string;
+  steps: SkillStep[];
+  currentStep: number;
+  startedAt: string;
+  evidence: Record<string, StepEvidence>;
+  completedAt?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/** Sanitize a string for safe use in file paths. */
+function sanitizeForPath(name: string): string {
+  return name.replace(/[/\\:*?"<>|.]/g, '_');
+}
+
+export function createTracker(skillName: string, steps: SkillStep[]): SkillStepTracker {
+  return {
+    skillName,
+    runId: `${sanitizeForPath(skillName)}-${Date.now()}`,
+    steps,
+    currentStep: 0,
+    startedAt: new Date().toISOString(),
+    evidence: {},
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Operations
+// ---------------------------------------------------------------------------
+
+export function advanceStep(tracker: SkillStepTracker): SkillStepTracker {
+  if (tracker.currentStep < tracker.steps.length - 1) {
+    return { ...tracker, currentStep: tracker.currentStep + 1 };
+  }
+  return { ...tracker, completedAt: new Date().toISOString() };
+}
+
+export function recordEvidence(
+  tracker: SkillStepTracker,
+  stepId: string,
+  value: string,
+  verified: boolean = true,
+): SkillStepTracker {
+  const step = tracker.steps.find((s) => s.id === stepId);
+  if (!step) return tracker;
+
+  return {
+    ...tracker,
+    evidence: {
+      ...tracker.evidence,
+      [stepId]: {
+        type: step.evidence,
+        value,
+        timestamp: new Date().toISOString(),
+        verified,
+      },
+    },
+  };
+}
+
+export function generateCheckpoint(tracker: SkillStepTracker): string {
+  const completed = tracker.steps
+    .filter((s) => tracker.evidence[s.id]?.verified)
+    .map((s) => `${s.id} ✓`);
+
+  const current = tracker.steps[tracker.currentStep];
+  const total = tracker.steps.length;
+  const completedCount = completed.length;
+
+  const lines = [
+    `--- Skill Checkpoint: ${tracker.skillName} ---`,
+    `Completed: ${completed.length > 0 ? completed.join(', ') : 'none'}`,
+    `Current: ${current ? `${current.id} (step ${tracker.currentStep + 1} of ${total})` : 'all done'}`,
+  ];
+
+  if (current) {
+    lines.push(`Evidence required: ${current.evidence} → ${current.description}`);
+  }
+
+  lines.push(`Progress: ${completedCount}/${total}`, '---');
+  return lines.join('\n');
+}
+
+export interface CompletionResult {
+  complete: boolean;
+  skippedSteps: string[];
+  evidenceCount: number;
+  totalSteps: number;
+}
+
+export function validateCompletion(tracker: SkillStepTracker): CompletionResult {
+  const skippedSteps = tracker.steps
+    .filter((s) => !tracker.evidence[s.id]?.verified)
+    .map((s) => s.id);
+
+  return {
+    complete: skippedSteps.length === 0,
+    skippedSteps,
+    evidenceCount: Object.keys(tracker.evidence).length,
+    totalSteps: tracker.steps.length,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Persistence
+// ---------------------------------------------------------------------------
+
+function getRunsDir(): string {
+  return join(homedir(), '.soleri', 'skill-runs');
+}
+
+export function persistTracker(tracker: SkillStepTracker): string {
+  const dir = getRunsDir();
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+  const filePath = join(dir, `${tracker.runId}.json`);
+  writeFileSync(filePath, JSON.stringify(tracker, null, 2), 'utf-8');
+  return filePath;
+}
+
+export function loadTracker(runId: string): SkillStepTracker | null {
+  const filePath = join(getRunsDir(), `${runId}.json`);
+  if (!existsSync(filePath)) return null;
+
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf-8')) as SkillStepTracker;
+  } catch {
+    return null;
+  }
+}

package/src/skills/sync-skills.ts

@@ -1,12 +1,21 @@
 /**
  * Skill sync — discovers SKILL.md files in agent skills directories
- * and copies them to ~/.claude/commands/ for Claude Code discovery.
+ * and copies them to ~/.claude/skills/ for Claude Code discovery.
  *
  * Injects agent branding so users know which agent owns the skill.
  * Called automatically at engine startup and by admin_setup_global.
  */
 
-import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, statSync } from 'node:fs';
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
 import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import type { SkillMetadata, SourceType } from '../packs/types.js';
@@ -25,6 +34,7 @@ export interface SyncResult {
   updated: string[];
   skipped: string[];
   failed: string[];
+  removed: string[];
 }
 
 /** Error thrown when a skill requires approval due to scripts trust level */
@@ -86,30 +96,31 @@ function brandSkillContent(content: string, agentName: string, prefixedName?: st
 }
 
 /**
- * Sync skills from agent directory to ~/.claude/commands/.
+ * Sync skills from agent directory to ~/.claude/skills/.
  * - New skills are installed with agent branding
  * - Changed skills are overwritten (compared by mtime)
  * - Missing source skills leave target untouched (other agents may own them)
  */
 export function syncSkillsToClaudeCode(skillsDirs: string[], agentName?: string): SyncResult {
-  const commandsDir = join(homedir(), '.claude', 'commands');
+  const skillsDir = join(homedir(), '.claude', 'skills');
   const skills = discoverSkills(skillsDirs);
-  const result: SyncResult = { installed: [], updated: [], skipped: [], failed: [] };
+  const result: SyncResult = { installed: [], updated: [], skipped: [], failed: [], removed: [] };
 
   if (skills.length === 0) return result;
 
-  mkdirSync(commandsDir, { recursive: true });
-
   for (const skill of skills) {
     const prefix = agentName ? `${agentName.toLowerCase().replace(/\s+/g, '-')}-` : '';
-    const targetPath = join(commandsDir, `${prefix}${skill.name}.md`);
+    const skillName = `${prefix}${skill.name}`;
+    const targetDir = join(skillsDir, skillName);
+    const targetPath = join(targetDir, 'SKILL.md');
     try {
       const sourceContent = readFileSync(skill.sourcePath, 'utf-8');
       const branded = agentName
-        ? brandSkillContent(sourceContent, agentName, `${prefix}${skill.name}`)
+        ? brandSkillContent(sourceContent, agentName, skillName)
         : sourceContent;
 
       if (!existsSync(targetPath)) {
+        mkdirSync(targetDir, { recursive: true });
         writeFileSync(targetPath, branded);
         result.installed.push(skill.name);
       } else {
@@ -127,6 +138,40 @@ export function syncSkillsToClaudeCode(skillsDirs: string[], agentName?: string)
     }
   }
 
+  // Orphan cleanup: remove skills that belong to this agent but are no longer in source
+  if (agentName) {
+    const prefix = `${agentName.toLowerCase().replace(/\s+/g, '-')}-`;
+    const syncedNames = new Set<string>(
+      [...result.installed, ...result.updated, ...result.skipped, ...result.failed].map(
+        (name) => `${prefix}${name}`,
+      ),
+    );
+
+    try {
+      const entries = readdirSync(skillsDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        if (!entry.name.startsWith(prefix)) continue;
+        if (syncedNames.has(entry.name)) continue;
+
+        // Orphan detected — stage backup then remove
+        const orphanPath = join(skillsDir, entry.name);
+        try {
+          const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+          const stagingDir = join(homedir(), '.soleri', 'staging', timestamp);
+          mkdirSync(stagingDir, { recursive: true });
+          cpSync(orphanPath, join(stagingDir, entry.name), { recursive: true });
+          rmSync(orphanPath, { recursive: true, force: true });
+          result.removed.push(entry.name);
+        } catch {
+          result.failed.push(entry.name);
+        }
+      }
+    } catch {
+      // Skills directory doesn't exist or is unreadable — nothing to clean
+    }
+  }
+
   return result;
 }
 

package/src/subagent/dispatcher.ts

@@ -18,6 +18,7 @@ import { TaskCheckout } from './task-checkout.js';
 import { WorkspaceResolver } from './workspace-resolver.js';
 import { ConcurrencyManager } from './concurrency-manager.js';
 import { OrphanReaper } from './orphan-reaper.js';
+import type { ReapResult } from './orphan-reaper.js';
 import { aggregate } from './result-aggregator.js';
 import type { GoalRepository } from '../planning/goal-ancestry.js';
 import { GoalAncestry } from '../planning/goal-ancestry.js';
@@ -48,8 +49,9 @@ export class SubagentDispatcher {
       this.goalAncestry = new GoalAncestry(config.goalRepository);
     }
     this.workspace = new WorkspaceResolver(config.baseDir ?? process.cwd());
-    this.reaper = new OrphanReaper((taskId) => {
-      // On orphan: release the task claim and clean up workspace
+    this.reaper = new OrphanReaper((taskId, pid) => {
+      // On orphan: kill the process group, release the task claim, and clean up workspace
+      this.reaper.killProcessGroup(pid);
       this.checkout.release(taskId);
       this.workspace.cleanup(taskId);
     });
@@ -78,52 +80,49 @@ export class SubagentDispatcher {
     // Resolve dependency order
     const ordered = this.resolveDependencies(tasks);
 
-    if (parallel) {
-      // Run independent tasks in parallel, respecting dependencies
-      const results = await this.dispatchParallel(ordered, {
-        maxConcurrent,
-        worktreeIsolation,
-        timeout,
-        onTaskUpdate,
-      });
-      return aggregate(results);
-    }
+    try {
+      if (parallel) {
+        // Run independent tasks in parallel, respecting dependencies
+        const results = await this.dispatchParallel(ordered, {
+          maxConcurrent,
+          worktreeIsolation,
+          timeout,
+          onTaskUpdate,
+        });
+        return aggregate(results);
+      }
 
-    // Sequential dispatch — await in loop is intentional (tasks must run one at a time)
-    const results: SubagentResult[] = [];
-    for (const task of ordered) {
-      // eslint-disable-line no-await-in-loop
-      onTaskUpdate?.(task.taskId, 'running');
-      const result = await this.executeTask(task, worktreeIsolation, timeout);
-      results.push(result);
-      onTaskUpdate?.(task.taskId, result.status);
-
-      // Stop on failure in sequential mode
-      if (result.exitCode !== 0) break;
-    }
+      // Sequential dispatch — await in loop is intentional (tasks must run one at a time)
+      const results: SubagentResult[] = [];
+      for (const task of ordered) {
+        // eslint-disable-line no-await-in-loop
+        onTaskUpdate?.(task.taskId, 'running');
+        const result = await this.executeTask(task, worktreeIsolation, timeout);
+        results.push(result);
+        onTaskUpdate?.(task.taskId, result.status);
+
+        // Stop on failure in sequential mode
+        if (result.exitCode !== 0) break;
+      }
 
-    return aggregate(results);
+      return aggregate(results);
+    } finally {
+      // Event-driven orphan reaping: sweep after every dispatch cycle
+      this.reaper.reap();
+    }
   }
 
-  /** Clean up all resources (worktrees, claims, concurrency) */
+  /** Clean up all resources — kills tracked process groups, then cleans worktrees, claims, concurrency */
   cleanup(): void {
+    this.reaper.killAll();
     this.workspace.cleanupAll();
     this.checkout.releaseAll();
     this.concurrency.reset();
-    this.reaper.clear();
   }
 
   /** Run orphan detection and cleanup */
-  reapOrphans(): SubagentResult[] {
-    const orphaned = this.reaper.reap();
-    return orphaned.map((p) => ({
-      taskId: p.taskId,
-      status: 'orphaned' as const,
-      exitCode: 1,
-      error: `Process ${p.pid} died unexpectedly`,
-      durationMs: Date.now() - p.registeredAt,
-      pid: p.pid,
-    }));
+  reapOrphans(): ReapResult {
+    return this.reaper.reap();
   }
 
   // ── Internal ──────────────────────────────────────────────────────
@@ -261,21 +260,43 @@ export class SubagentDispatcher {
         this.goalAncestry.inject({ config: enrichedConfig }, goalId).config ?? enrichedConfig;
     }
 
-    // 5. Execute with timeout
+    // 5. Execute with timeout and active process killing
+    let childPid: number | undefined;
     try {
       const resultPromise = adapter.execute({
         runId: `subagent-${task.taskId}-${Date.now()}`,
         prompt: task.prompt,
         workspace,
         config: enrichedConfig,
+        onMeta: (meta) => {
+          // Adapters report their child PID via onMeta({ pid })
+          if (typeof meta.pid === 'number') {
+            childPid = meta.pid;
+            this.reaper.register(childPid, task.taskId);
+          }
+        },
       });
 
       const timeoutPromise = new Promise<never>((_, reject) => {
-        setTimeout(() => reject(new Error('Task timed out')), timeout);
+        setTimeout(() => {
+          reject(new Error('Task timed out'));
+          // Kill the child process if we have a PID
+          if (childPid !== undefined) {
+            // Fire-and-forget: kill with escalation (SIGTERM → wait 5s → SIGKILL)
+            void this.reaper.killProcess(childPid, true).then(() => {
+              this.reaper.unregister(childPid!);
+            });
+          }
+        }, timeout);
       });
 
       const adapterResult = await Promise.race([resultPromise, timeoutPromise]);
 
+      // Normal completion — unregister from reaper
+      if (childPid !== undefined) {
+        this.reaper.unregister(childPid);
+      }
+
       return {
         taskId: task.taskId,
         status: adapterResult.exitCode === 0 ? 'completed' : 'failed',
@@ -284,6 +305,7 @@ export class SubagentDispatcher {
         usage: adapterResult.usage,
         sessionState: adapterResult.sessionState,
         durationMs: Date.now() - startTime,
+        pid: childPid ?? adapterResult.pid,
       };
     } catch (err) {
       return {
@@ -292,6 +314,7 @@ export class SubagentDispatcher {
         exitCode: 1,
         error: err instanceof Error ? err.message : String(err),
         durationMs: Date.now() - startTime,
+        pid: childPid,
       };
     } finally {
       // Cleanup

package/src/subagent/index.ts

@@ -22,6 +22,7 @@ export { TaskCheckout } from './task-checkout.js';
 export { WorkspaceResolver } from './workspace-resolver.js';
 export { ConcurrencyManager } from './concurrency-manager.js';
 export { OrphanReaper } from './orphan-reaper.js';
+export type { ReapResult, ProcessGroupKillResult } from './orphan-reaper.js';
 export { aggregate as aggregateResults } from './result-aggregator.js';
 
 // Dispatcher