orbital-command 0.2.0 → 1.0.0

package/server/update.ts

@@ -0,0 +1,263 @@
+/**
+ * Template update logic — extracted from init.ts for focused maintainability.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import {
+  loadManifest,
+  saveManifest,
+  buildTemplateInventory,
+  refreshFileStatuses,
+  templateFileRecord,
+  safeBackupFile,
+  safeCopyTemplate,
+  reverseRemapPath,
+} from './manifest.js';
+import { needsLegacyMigration, migrateFromLegacy } from './migrate-legacy.js';
+import { computeUpdatePlan, loadRenameMap, formatPlan, getFilesToBackup } from './update-planner.js';
+import { syncSettingsHooks, getTemplateChecksum } from './settings-sync.js';
+import { migrateConfig } from './config-migrator.js';
+import { validate, formatValidationReport } from './validator.js';
+import { createBackup } from './manifest.js';
+import {
+  TEMPLATES_DIR,
+  ensureDir,
+  cleanEmptyDirs,
+  chmodScripts,
+  writeManifest,
+  generateIndexMd,
+  seedGlobalPrimitives,
+  getPackageVersion,
+} from './init.js';
+
+// ─── Update ─────────────────────────────────────────────────
+
+export interface UpdateOptions {
+  dryRun?: boolean;
+  force?: boolean;
+}
+
+export function runUpdate(projectRoot: string, options: UpdateOptions = {}): void {
+  const { dryRun = false } = options;
+  const claudeDir = path.join(projectRoot, '.claude');
+  const newVersion = getPackageVersion();
+
+  console.log(`\nOrbital Command — update${dryRun ? ' (dry run)' : ''}`);
+  console.log(`Project root: ${projectRoot}\n`);
+
+  // 1. Load or create manifest (auto-migrate legacy installs)
+  let manifest = loadManifest(projectRoot);
+  if (!manifest) {
+    if (needsLegacyMigration(projectRoot)) {
+      console.log('  Migrating from legacy install...');
+      const result = migrateFromLegacy(projectRoot, TEMPLATES_DIR, newVersion);
+      console.log(`  Migrated ${result.synced} synced, ${result.modified} modified, ${result.userOwned} user-owned files`);
+      if (result.importedPins > 0) console.log(`  Imported ${result.importedPins} pinned files from orbital-sync.json`);
+      manifest = loadManifest(projectRoot);
+    }
+    if (!manifest) {
+      console.log('  No manifest found. Run `orbital` first.');
+      return;
+    }
+  }
+
+  const oldVersion = manifest.packageVersion;
+
+  // 1b. Refresh file statuses so outdated vs modified is accurate
+  refreshFileStatuses(manifest, claudeDir);
+
+  // 2. Compute update plan
+  const renameMap = loadRenameMap(TEMPLATES_DIR, oldVersion, newVersion);
+  const plan = computeUpdatePlan({
+    templatesDir: TEMPLATES_DIR,
+    claudeDir,
+    manifest,
+    newVersion,
+    renameMap,
+  });
+
+  // 3. Dry-run mode — print plan and exit
+  if (dryRun) {
+    console.log(formatPlan(plan, oldVersion, newVersion));
+    return;
+  }
+
+  if (plan.isEmpty && oldVersion === newVersion) {
+    console.log('  Everything up to date. No changes needed.');
+  }
+
+  // 4. Create backup of files that will be modified
+  const filesToBackup = getFilesToBackup(plan);
+  if (filesToBackup.length > 0) {
+    const backupDir = createBackup(claudeDir, filesToBackup);
+    if (backupDir) {
+      console.log(`  Backup   ${filesToBackup.length} files → ${path.relative(claudeDir, backupDir)}/`);
+    }
+  }
+
+  // 5. Execute plan
+  const templateInventory = buildTemplateInventory(TEMPLATES_DIR);
+
+  // 5a. Handle renames
+  for (const { from, to } of plan.toRename) {
+    const fromPath = path.join(claudeDir, from);
+    const toPath = path.join(claudeDir, to);
+    const toDir = path.dirname(toPath);
+    if (!fs.existsSync(toDir)) fs.mkdirSync(toDir, { recursive: true });
+
+    if (fs.existsSync(fromPath)) {
+      safeBackupFile(fromPath);
+      const stat = fs.lstatSync(fromPath);
+      if (stat.isSymbolicLink()) {
+        const target = fs.readlinkSync(fromPath);
+        fs.unlinkSync(fromPath);
+        fs.symlinkSync(target, toPath);
+      } else {
+        fs.renameSync(fromPath, toPath);
+      }
+    }
+
+    const record = manifest.files[from];
+    if (record) {
+      delete manifest.files[from];
+      const newHash = templateInventory.get(to);
+      manifest.files[to] = { ...record, templateHash: newHash, installedHash: newHash || record.installedHash };
+    }
+    console.log(`  RENAME  ${from} → ${to}`);
+  }
+
+  // 5b. Add new files
+  for (const filePath of plan.toAdd) {
+    const templateHash = templateInventory.get(filePath);
+    if (!templateHash) continue;
+
+    const destPath = path.join(claudeDir, filePath);
+    const destDir = path.dirname(destPath);
+    if (!fs.existsSync(destDir)) fs.mkdirSync(destDir, { recursive: true });
+
+    copyTemplateFile(filePath, destPath);
+    manifest.files[filePath] = templateFileRecord(templateHash);
+    console.log(`  ADD     ${filePath}`);
+  }
+
+  // 5c. Update changed synced/outdated files
+  for (const filePath of plan.toUpdate) {
+    const templateHash = templateInventory.get(filePath);
+    if (!templateHash) continue;
+
+    const destPath = path.join(claudeDir, filePath);
+    safeBackupFile(destPath);
+    copyTemplateFile(filePath, destPath);
+    manifest.files[filePath] = templateFileRecord(templateHash);
+    console.log(`  UPDATE  ${filePath}`);
+  }
+
+  // 5d. Remove deleted files
+  for (const filePath of plan.toRemove) {
+    const absPath = path.join(claudeDir, filePath);
+    if (fs.existsSync(absPath)) {
+      safeBackupFile(absPath);
+      fs.unlinkSync(absPath);
+    }
+    delete manifest.files[filePath];
+    console.log(`  REMOVE  ${filePath}`);
+  }
+
+  // 5e. Update pinned/modified file records (record new template hash without touching file)
+  for (const { file, reason, newTemplateHash } of plan.toSkip) {
+    if (manifest.files[file]) {
+      manifest.files[file].templateHash = newTemplateHash;
+    }
+    if (reason === 'modified') {
+      console.log(`  SKIP    ${file} (user modified)`);
+    } else {
+      console.log(`  SKIP    ${file} (pinned)`);
+    }
+  }
+
+  // 5f. Clean up empty directories
+  for (const dir of ['hooks', 'skills', 'agents', 'config/workflows']) {
+    const dirPath = path.join(claudeDir, dir);
+    if (fs.existsSync(dirPath)) cleanEmptyDirs(dirPath);
+  }
+
+  // 6. Bidirectional settings hook sync
+  const settingsTarget = path.join(claudeDir, 'settings.local.json');
+  const settingsSrc = path.join(TEMPLATES_DIR, 'settings-hooks.json');
+  const syncResult = syncSettingsHooks(settingsTarget, settingsSrc, manifest.settingsHooksChecksum, renameMap);
+  if (!syncResult.skipped) {
+    console.log(`  Settings +${syncResult.added} -${syncResult.removed} hooks (${syncResult.updated} renamed)`);
+    manifest.settingsHooksChecksum = getTemplateChecksum(settingsSrc);
+  }
+
+  // 7. Config migrations
+  const configPath = path.join(claudeDir, 'orbital.config.json');
+  const migrationResult = migrateConfig(configPath, manifest.appliedMigrations);
+  if (migrationResult.applied.length > 0) {
+    manifest.appliedMigrations.push(...migrationResult.applied);
+    console.log(`  Config   ${migrationResult.applied.length} migration(s) applied`);
+  }
+  if (migrationResult.defaultsFilled.length > 0) {
+    console.log(`  Config   ${migrationResult.defaultsFilled.length} default(s) filled`);
+  }
+
+  // 8. Regenerate derived artifacts (always)
+  const workflowManifestOk = writeManifest(claudeDir);
+  console.log(`  ${workflowManifestOk ? 'Updated' : 'Skipped'}  .claude/config/workflow-manifest.sh`);
+
+  const indexContent = generateIndexMd(projectRoot, claudeDir);
+  fs.writeFileSync(path.join(claudeDir, 'INDEX.md'), indexContent, 'utf8');
+  console.log(`  Updated  .claude/INDEX.md`);
+
+  // 9. Update agent-triggers.json (template-managed)
+  const triggersSrc = path.join(TEMPLATES_DIR, 'config', 'agent-triggers.json');
+  const triggersDest = path.join(claudeDir, 'config', 'agent-triggers.json');
+  if (fs.existsSync(triggersSrc)) {
+    fs.copyFileSync(triggersSrc, triggersDest);
+    console.log(`  Updated  .claude/config/agent-triggers.json`);
+  }
+
+  // 10. Update scope template
+  const scopeTemplateSrc = path.join(TEMPLATES_DIR, 'scopes', '_template.md');
+  const scopeTemplateDest = path.join(projectRoot, 'scopes', '_template.md');
+  if (fs.existsSync(scopeTemplateSrc)) {
+    ensureDir(path.join(projectRoot, 'scopes'));
+    fs.copyFileSync(scopeTemplateSrc, scopeTemplateDest);
+  }
+
+  // 11. Make hook scripts executable
+  chmodScripts(path.join(claudeDir, 'hooks'));
+
+  // 12. Refresh global primitives
+  seedGlobalPrimitives();
+
+  // 13. Update manifest metadata
+  manifest.previousPackageVersion = oldVersion;
+  manifest.packageVersion = newVersion;
+  manifest.updatedAt = new Date().toISOString();
+  saveManifest(projectRoot, manifest);
+
+  // 14. Validate
+  const report = validate(projectRoot, newVersion);
+  if (report.errors > 0) {
+    console.log(`\n  Validation: ${report.errors} errors found`);
+    console.log(formatValidationReport(report));
+  }
+
+  const totalChanges = plan.toAdd.length + plan.toUpdate.length + plan.toRemove.length + plan.toRename.length;
+  console.log(`\nUpdate complete. ${totalChanges} file changes, ${plan.toSkip.length} skipped.\n`);
+}
+
+// ─── Helpers ────────────────────────────────────────────────
+
+function copyTemplateFile(claudeRelPath: string, destPath: string): void {
+  const templateRelPath = reverseRemapPath(claudeRelPath);
+  const srcPath = path.join(TEMPLATES_DIR, templateRelPath);
+  if (!fs.existsSync(srcPath)) {
+    throw new Error(`Template file not found: ${templateRelPath}`);
+  }
+  const destDir = path.dirname(destPath);
+  if (!fs.existsSync(destDir)) fs.mkdirSync(destDir, { recursive: true });
+  safeCopyTemplate(srcPath, destPath);
+}

package/server/utils/cc-hooks-parser.test.ts

@@ -0,0 +1,96 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { parseCcHooks } from './cc-hooks-parser.js';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+describe('parseCcHooks', () => {
+  let tmpFile: string;
+
+  function writeSettings(data: Record<string, unknown>): string {
+    tmpFile = path.join(os.tmpdir(), `test-settings-${Date.now()}.json`);
+    fs.writeFileSync(tmpFile, JSON.stringify(data));
+    return tmpFile;
+  }
+
+  afterEach(() => {
+    if (tmpFile && fs.existsSync(tmpFile)) fs.unlinkSync(tmpFile);
+  });
+
+  it('parses all 4 event types', () => {
+    const file = writeSettings({
+      hooks: {
+        SessionStart: [{ hooks: [{ type: 'command', command: '$CLAUDE_PROJECT_DIR/.claude/hooks/init.sh', statusMessage: 'Initializing' }] }],
+        SessionEnd: [{ hooks: [{ type: 'command', command: '$CLAUDE_PROJECT_DIR/.claude/hooks/end.sh' }] }],
+        PreToolUse: [{ matcher: 'Edit', hooks: [{ type: 'command', command: '$CLAUDE_PROJECT_DIR/.claude/hooks/guard.sh', statusMessage: 'Checking' }] }],
+        PostToolUse: [{ hooks: [{ type: 'command', command: '$CLAUDE_PROJECT_DIR/.claude/hooks/log.sh' }] }],
+      },
+    });
+    const hooks = parseCcHooks(file);
+    expect(hooks).toHaveLength(4);
+    expect(hooks.map(h => h.event)).toEqual(['SessionStart', 'SessionEnd', 'PreToolUse', 'PostToolUse']);
+  });
+
+  it('extracts script path stripping $CLAUDE_PROJECT_DIR', () => {
+    const file = writeSettings({
+      hooks: {
+        SessionStart: [{ hooks: [{ type: 'command', command: '$CLAUDE_PROJECT_DIR/.claude/hooks/init-session.sh' }] }],
+      },
+    });
+    const hooks = parseCcHooks(file);
+    expect(hooks[0].scriptPath).toBe('.claude/hooks/init-session.sh');
+    expect(hooks[0].scriptName).toBe('init-session.sh');
+  });
+
+  it('derives ID from script filename', () => {
+    const file = writeSettings({
+      hooks: {
+        SessionStart: [{ hooks: [{ type: 'command', command: '$CLAUDE_PROJECT_DIR/.claude/hooks/init-session.sh' }] }],
+      },
+    });
+    const hooks = parseCcHooks(file);
+    expect(hooks[0].id).toBe('init-session');
+  });
+
+  it('extracts matcher from group', () => {
+    const file = writeSettings({
+      hooks: {
+        PreToolUse: [{ matcher: 'Edit', hooks: [{ type: 'command', command: 'test.sh' }] }],
+      },
+    });
+    const hooks = parseCcHooks(file);
+    expect(hooks[0].matcher).toBe('Edit');
+  });
+
+  it('sets matcher to null when absent', () => {
+    const file = writeSettings({
+      hooks: {
+        SessionStart: [{ hooks: [{ type: 'command', command: 'test.sh' }] }],
+      },
+    });
+    const hooks = parseCcHooks(file);
+    expect(hooks[0].matcher).toBeNull();
+  });
+
+  it('skips non-command entries', () => {
+    const file = writeSettings({
+      hooks: {
+        SessionStart: [{ hooks: [
+          { type: 'command', command: 'test.sh' },
+          { type: 'url', command: 'https://example.com' },
+        ] }],
+      },
+    });
+    const hooks = parseCcHooks(file);
+    expect(hooks).toHaveLength(1);
+  });
+
+  it('returns empty array for file not found', () => {
+    expect(parseCcHooks('/tmp/nonexistent-settings.json')).toEqual([]);
+  });
+
+  it('returns empty array when no hooks key in settings', () => {
+    const file = writeSettings({ other: 'config' });
+    expect(parseCcHooks(file)).toEqual([]);
+  });
+});

package/server/utils/cc-hooks-parser.ts

@@ -1,6 +1,9 @@
 import { readFileSync } from 'node:fs';
+import { createLogger } from './logger.js';
 import type { CcHookEvent, CcHookParsed } from '../../shared/workflow-config.js';
 
+const log = createLogger('config');
+
 const CC_HOOK_EVENTS: CcHookEvent[] = ['SessionStart', 'SessionEnd', 'PreToolUse', 'PostToolUse'];
 
 interface SettingsHookEntry {
@@ -36,6 +39,7 @@ export function parseCcHooks(settingsPath: string): CcHookParsed[] {
   try {
     raw = readFileSync(settingsPath, 'utf-8');
   } catch {
+    log.debug('Settings file not found', { path: settingsPath });
     return [];
   }
 

package/server/utils/dispatch-utils.test.ts

@@ -0,0 +1,245 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import {
+  resolveDispatchEvent,
+  resolveActiveDispatchesForScope,
+  resolveAbandonedDispatchesForScope,
+  linkPidToDispatch,
+  resolveDispatchesByPid,
+  resolveDispatchesByDispatchId,
+  getActiveScopeIds,
+  getAbandonedScopeIds,
+} from './dispatch-utils.js';
+import { createTestDb } from '../__tests__/helpers/db.js';
+import { createMockEmitter } from '../__tests__/helpers/mock-emitter.js';
+import { WorkflowEngine } from '../../shared/workflow-engine.js';
+import { CONFIG_WITH_HOOKS } from '../../shared/__fixtures__/workflow-configs.js';
+import type Database from 'better-sqlite3';
+import type { Emitter } from '../project-emitter.js';
+
+// Mock isSessionPidAlive since it checks real OS processes
+vi.mock('./terminal-launcher.js', () => ({
+  isSessionPidAlive: vi.fn().mockReturnValue(false),
+  launchInTerminal: vi.fn(),
+  buildSessionName: vi.fn(),
+  snapshotSessionPids: vi.fn().mockReturnValue([]),
+  discoverNewSession: vi.fn(),
+  renameSession: vi.fn(),
+  launchInCategorizedTerminal: vi.fn(),
+}));
+
+function insertDispatchEvent(db: Database.Database, overrides: Record<string, unknown> = {}) {
+  const id = overrides.id ?? `dispatch-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
+  const data = JSON.stringify({
+    command: '/scope-implement 1',
+    transition: { from: 'backlog', to: 'active' },
+    ...(overrides.data as Record<string, unknown> ?? {}),
+  });
+  db.prepare(
+    `INSERT INTO events (id, type, scope_id, session_id, agent, data, timestamp)
+     VALUES (?, 'DISPATCH', ?, ?, NULL, ?, ?)`
+  ).run(
+    id,
+    overrides.scope_id ?? 1,
+    overrides.session_id ?? 'sess-1',
+    data,
+    overrides.timestamp ?? new Date().toISOString(),
+  );
+  return id as string;
+}
+
+describe('dispatch-utils', () => {
+  let db: Database.Database;
+  let cleanup: () => void;
+  let emitter: Emitter & { emit: ReturnType<typeof vi.fn> };
+  let engine: WorkflowEngine;
+
+  beforeEach(() => {
+    ({ db, cleanup } = createTestDb());
+    emitter = createMockEmitter();
+    engine = new WorkflowEngine(CONFIG_WITH_HOOKS);
+  });
+
+  afterEach(() => {
+    cleanup?.();
+  });
+
+  // ─── resolveDispatchEvent() ───────────────────────────────
+
+  describe('resolveDispatchEvent()', () => {
+    it('marks dispatch as resolved with outcome', () => {
+      const id = insertDispatchEvent(db);
+      resolveDispatchEvent(db, emitter, id, 'completed');
+
+      const row = db.prepare('SELECT data FROM events WHERE id = ?').get(id) as { data: string };
+      const data = JSON.parse(row.data);
+      expect(data.resolved).toBeDefined();
+      expect(data.resolved.outcome).toBe('completed');
+      expect(data.resolved.at).toBeDefined();
+    });
+
+    it('emits dispatch:resolved event', () => {
+      const id = insertDispatchEvent(db);
+      resolveDispatchEvent(db, emitter, id, 'completed');
+      expect(emitter.emit).toHaveBeenCalledWith('dispatch:resolved', expect.objectContaining({ event_id: id }));
+    });
+
+    it('stores error message for failed dispatches', () => {
+      const id = insertDispatchEvent(db);
+      resolveDispatchEvent(db, emitter, id, 'failed', 'Timeout');
+
+      const row = db.prepare('SELECT data FROM events WHERE id = ?').get(id) as { data: string };
+      const data = JSON.parse(row.data);
+      expect(data.resolved.outcome).toBe('failed');
+      expect(data.resolved.error).toBe('Timeout');
+    });
+  });
+
+  // ─── resolveActiveDispatchesForScope() ────────────────────
+
+  describe('resolveActiveDispatchesForScope()', () => {
+    it('resolves all unresolved dispatches for a scope', () => {
+      insertDispatchEvent(db, { id: 'd1', scope_id: 42 });
+      insertDispatchEvent(db, { id: 'd2', scope_id: 42 });
+      insertDispatchEvent(db, { id: 'd3', scope_id: 99 }); // different scope
+
+      resolveActiveDispatchesForScope(db, emitter, 42, 'completed');
+
+      const rows = db.prepare("SELECT data FROM events WHERE scope_id = 42").all() as Array<{ data: string }>;
+      for (const row of rows) {
+        const data = JSON.parse(row.data);
+        expect(data.resolved).toBeDefined();
+        expect(data.resolved.outcome).toBe('completed');
+      }
+
+      // Scope 99 should NOT be resolved
+      const other = db.prepare("SELECT data FROM events WHERE scope_id = 99").get() as { data: string };
+      expect(JSON.parse(other.data).resolved).toBeUndefined();
+    });
+
+    it('handles no active dispatches gracefully', () => {
+      expect(() => resolveActiveDispatchesForScope(db, emitter, 999, 'completed')).not.toThrow();
+    });
+  });
+
+  // ─── resolveAbandonedDispatchesForScope() ─────────────────
+
+  describe('resolveAbandonedDispatchesForScope()', () => {
+    it('resolves abandoned dispatches as completed', () => {
+      insertDispatchEvent(db, { scope_id: 42, data: { resolved: true, outcome: 'abandoned' } });
+      const count = resolveAbandonedDispatchesForScope(db, emitter, 42);
+      expect(count).toBeGreaterThanOrEqual(0);
+    });
+  });
+
+  // ─── linkPidToDispatch() ──────────────────────────────────
+
+  describe('linkPidToDispatch()', () => {
+    it('stores PID in event data', () => {
+      const id = insertDispatchEvent(db);
+      linkPidToDispatch(db, id, 12345);
+
+      const row = db.prepare('SELECT data FROM events WHERE id = ?').get(id) as { data: string };
+      const data = JSON.parse(row.data);
+      expect(data.pid).toBe(12345);
+    });
+
+    it('handles non-existent event gracefully', () => {
+      expect(() => linkPidToDispatch(db, 'nonexistent', 12345)).not.toThrow();
+    });
+  });
+
+  // ─── resolveDispatchesByPid() ─────────────────────────────
+
+  describe('resolveDispatchesByPid()', () => {
+    it('resolves dispatches matching PID', () => {
+      const id = insertDispatchEvent(db, { scope_id: 1 });
+      linkPidToDispatch(db, id, 54321);
+
+      const ids = resolveDispatchesByPid(db, emitter, 54321);
+      expect(ids).toHaveLength(1);
+      expect(ids[0]).toBe(id);
+
+      const row = db.prepare('SELECT data FROM events WHERE id = ?').get(id) as { data: string };
+      expect(JSON.parse(row.data).resolved).toBeDefined();
+    });
+
+    it('returns empty array when no dispatches match PID', () => {
+      expect(resolveDispatchesByPid(db, emitter, 99999)).toHaveLength(0);
+    });
+  });
+
+  // ─── resolveDispatchesByDispatchId() ──────────────────────
+
+  describe('resolveDispatchesByDispatchId()', () => {
+    it('resolves single dispatch by event ID', () => {
+      const id = insertDispatchEvent(db);
+      const ids = resolveDispatchesByDispatchId(db, emitter, id);
+      expect(ids).toHaveLength(1);
+      expect(ids[0]).toBe(id);
+    });
+
+    it('returns empty array for non-existent dispatch', () => {
+      expect(resolveDispatchesByDispatchId(db, emitter, 'nonexistent')).toHaveLength(0);
+    });
+  });
+
+  // ─── getActiveScopeIds() ──────────────────────────────────
+
+  describe('getActiveScopeIds()', () => {
+    it('returns scope IDs with unresolved dispatches', () => {
+      insertDispatchEvent(db, { scope_id: 10 });
+      insertDispatchEvent(db, { scope_id: 20 });
+
+      const mockScopeService = {
+        getById: (id: number) => ({ id, status: 'active' }),
+      } as any;
+
+      const ids = getActiveScopeIds(db, mockScopeService, engine);
+      // May return empty if dispatches are stale (PID check fails), but shouldn't throw
+      expect(Array.isArray(ids)).toBe(true);
+    });
+
+    it('excludes scopes in terminal status', () => {
+      insertDispatchEvent(db, { scope_id: 30 });
+      const mockScopeService = {
+        getById: (id: number) => ({ id, status: 'shipped' }), // terminal
+      } as any;
+
+      const ids = getActiveScopeIds(db, mockScopeService, engine);
+      expect(ids).not.toContain(30);
+    });
+  });
+
+  // ─── getAbandonedScopeIds() ───────────────────────────────
+
+  describe('getAbandonedScopeIds()', () => {
+    it('returns recently abandoned scopes', () => {
+      insertDispatchEvent(db, {
+        scope_id: 50,
+        data: { resolved: true, outcome: 'abandoned', resolved_at: new Date().toISOString(), transition: { from: 'backlog', to: 'active' } },
+      });
+
+      const mockScopeService = {
+        getById: (id: number) => ({ id, status: 'active' }),
+      } as any;
+
+      const abandoned = getAbandonedScopeIds(db, mockScopeService, engine);
+      expect(Array.isArray(abandoned)).toBe(true);
+    });
+
+    it('excludes terminal scopes', () => {
+      insertDispatchEvent(db, {
+        scope_id: 60,
+        data: { resolved: true, outcome: 'abandoned', resolved_at: new Date().toISOString(), transition: { from: 'review', to: 'shipped' } },
+      });
+
+      const mockScopeService = {
+        getById: (id: number) => ({ id, status: 'shipped' }), // terminal
+      } as any;
+
+      const abandoned = getAbandonedScopeIds(db, mockScopeService, engine);
+      const ids = abandoned.map(a => a.scope_id);
+      expect(ids).not.toContain(60);
+    });
+  });
+});