orbital-command 0.1.4 → 0.3.0

package/dist/server/server/services/git-service.js

@@ -1,7 +1,9 @@
 import { execFile as execFileCb } from 'child_process';
 import { promisify } from 'util';
 import { listWorktrees } from '../utils/worktree-manager.js';
+import { createLogger } from '../utils/logger.js';
 const execFile = promisify(execFileCb);
+const log = createLogger('git');
 const CACHE_TTL = 60_000; // 60 seconds
 function cached(cache, key) {
     const entry = cache.get(key);
@@ -115,7 +117,8 @@ export class GitService {
         try {
             raw = await this.git(args);
         }
-        catch {
+        catch (err) {
+            log.debug('Commits query failed', { branch: branch ?? 'all', error: String(err) });
             return [];
         }
         const commits = [];
@@ -172,7 +175,8 @@ export class GitService {
                 '--format=%(HEAD)|%(refname:short)|%(objectname:short)|%(committerdate:iso-strict)|%(subject)',
             ]);
         }
-        catch {
+        catch (err) {
+            log.debug('Branch listing failed', { error: String(err) });
             return [];
         }
         const now = Date.now();
@@ -230,7 +234,8 @@ export class GitService {
         try {
             wts = await listWorktrees(this.projectRoot);
         }
-        catch {
+        catch (err) {
+            log.warn('Failed to list worktrees', { error: String(err) });
             return [];
         }
         const results = [];
@@ -288,13 +293,76 @@ export class GitService {
                 });
                 pairs.push({ from, to, count: commits.length, commits });
             }
-            catch {
+            catch (err) {
+                log.debug('Drift query failed', { from, to, error: String(err) });
                 pairs.push({ from, to, count: 0, commits: [] });
             }
         }
         setCache(this.cache, cacheKey, pairs);
         return pairs;
     }
+    // ─── Activity Series ────────────────────────────────────────
+    async getActivitySeries(days = 30) {
+        const cacheKey = `activity:${days}`;
+        const hit = cached(this.cache, cacheKey);
+        if (hit)
+            return hit;
+        try {
+            const raw = await this.git(['log', `--since=${days}.days.ago`, '--format=%aI', '--all']);
+            const counts = new Map();
+            // Initialize all days to 0
+            const now = new Date();
+            for (let i = 0; i < days; i++) {
+                const d = new Date(now);
+                d.setDate(d.getDate() - i);
+                counts.set(d.toISOString().slice(0, 10), 0);
+            }
+            for (const line of raw.trim().split('\n')) {
+                if (!line)
+                    continue;
+                const dateKey = line.slice(0, 10);
+                counts.set(dateKey, (counts.get(dateKey) ?? 0) + 1);
+            }
+            const series = [...counts.entries()]
+                .map(([date, count]) => ({ date, count }))
+                .sort((a, b) => a.date.localeCompare(b.date));
+            setCache(this.cache, cacheKey, series);
+            return series;
+        }
+        catch (err) {
+            log.debug('Activity series query failed', { days, error: String(err) });
+            return [];
+        }
+    }
+    // ─── Health Metrics ────────────────────────────────────────
+    async getHealthMetrics(githubPrAges) {
+        // Commits per week
+        let commitsPerWeek = 0;
+        try {
+            const raw = await this.git(['log', '--since=7.days.ago', '--oneline', '--all']);
+            commitsPerWeek = raw.trim().split('\n').filter(Boolean).length;
+        }
+        catch { /* ok */ }
+        // Stale branches
+        const branches = await this.getBranches();
+        const staleBranchCount = branches.filter(b => b.isStale && !b.isRemote).length;
+        // Avg PR age
+        let avgPrAgeDays = 0;
+        if (githubPrAges && githubPrAges.length > 0) {
+            avgPrAgeDays = Math.round(githubPrAges.reduce((a, b) => a + b, 0) / githubPrAges.length);
+        }
+        // Drift severity (reuse cached data if available)
+        const driftSeverity = 'clean';
+        // Grade computation: start at 100
+        let score = 100;
+        score -= Math.min(30, staleBranchCount * 5);
+        if (commitsPerWeek < 5)
+            score -= 10;
+        if (avgPrAgeDays > 3)
+            score -= Math.min(25, (avgPrAgeDays - 3) * 5);
+        const grade = score >= 90 ? 'A' : score >= 80 ? 'B' : score >= 70 ? 'C' : score >= 60 ? 'D' : 'F';
+        return { commitsPerWeek, avgPrAgeDays, staleBranchCount, driftSeverity, grade };
+    }
     // ─── Git Status Polling ────────────────────────────────────
     async getStatusHash() {
         const [head, dirty] = await Promise.all([
@@ -303,6 +371,42 @@ export class GitService {
         ]);
         return `${head.trim()}:${dirty.trim().length > 0 ? 'dirty' : 'clean'}`;
     }
+    // ─── Pipeline Drift ─────────────────────────────────────────
+    async getPipelineDrift() {
+        const cacheKey = 'pipeline-drift';
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const hit = cached(this.cache, cacheKey);
+        if (hit)
+            return hit;
+        function parseDriftCommits(raw) {
+            if (!raw)
+                return [];
+            return raw.split('\n').map((line) => {
+                const [sha, date, message, author] = line.split('|');
+                return { sha, date, message: message ?? '', author: author ?? '' };
+            });
+        }
+        function parseHead(raw) {
+            const [sha, date, message] = raw.split('|');
+            return { sha: sha ?? '', date: date ?? '', message: message ?? '' };
+        }
+        const [devToStagingRaw, stagingToMainRaw, devHead, stagingHead, mainHead] = await Promise.all([
+            this.git(['log', 'origin/dev', '--not', 'origin/staging', '--reverse', '--format=%H|%aI|%s|%an']).catch(() => ''),
+            this.git(['log', 'origin/staging', '--not', 'origin/main', '--reverse', '--format=%H|%aI|%s|%an']).catch(() => ''),
+            this.git(['log', 'origin/dev', '-1', '--format=%H|%aI|%s']).catch(() => ''),
+            this.git(['log', 'origin/staging', '-1', '--format=%H|%aI|%s']).catch(() => ''),
+            this.git(['log', 'origin/main', '-1', '--format=%H|%aI|%s']).catch(() => ''),
+        ]);
+        const devToStaging = parseDriftCommits(devToStagingRaw);
+        const stagingToMain = parseDriftCommits(stagingToMainRaw);
+        const data = {
+            devToStaging: { count: devToStaging.length, commits: devToStaging, oldestDate: devToStaging[0]?.date ?? null },
+            stagingToMain: { count: stagingToMain.length, commits: stagingToMain, oldestDate: stagingToMain[0]?.date ?? null },
+            heads: { dev: parseHead(devHead), staging: parseHead(stagingHead), main: parseHead(mainHead) },
+        };
+        setCache(this.cache, cacheKey, data);
+        return data;
+    }
     clearCache() {
         this.cache.clear();
     }

package/dist/server/server/services/github-service.js

@@ -1,4 +1,4 @@
-import { execFile as execFileCb } from 'child_process';
+import { execFile as execFileCb, spawn } from 'child_process';
 import { promisify } from 'util';
 // Uses execFile (not exec) — safe against shell injection
 const execFile = promisify(execFileCb);
@@ -107,7 +107,7 @@ export class GitHubService {
         try {
             const raw = await this.gh([
                 'pr', 'list', '--state', 'open', '--json',
-                'number,title,author,headRefName,baseRefName,state,url,createdAt',
+                'number,title,author,headRefName,baseRefName,state,url,createdAt,updatedAt,reviewDecision',
                 '--limit', '30',
             ]);
             const parsed = JSON.parse(raw);
@@ -133,6 +133,8 @@ export class GitHubService {
                     url: String(pr.url ?? ''),
                     createdAt: String(pr.createdAt ?? ''),
                     scopeIds,
+                    reviewDecision: pr.reviewDecision || null,
+                    lastActivityAt: String(pr.updatedAt ?? pr.createdAt ?? ''),
                 };
             });
             this.prCache = { data: prs, ts: Date.now() };
@@ -142,4 +144,110 @@ export class GitHubService {
             return [];
         }
     }
+    // ─── Auth Flow ─────────────────────────────────────────────
+    /** Start OAuth flow via gh CLI — opens browser. Client polls getAuthStatus(). */
+    async connectOAuth() {
+        return new Promise((resolve) => {
+            // spawn is safe here: no shell, args are hardcoded literals
+            const child = spawn('gh', ['auth', 'login', '--web', '--git-protocol', 'https'], {
+                cwd: this.projectRoot,
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            let stderr = '';
+            child.stderr?.on('data', (data) => { stderr += data.toString(); });
+            // Resolve quickly — the gh process runs in background, client polls auth status
+            setTimeout(() => {
+                resolve({ success: true });
+            }, 500);
+            child.on('error', () => {
+                resolve({ success: false, error: stderr || 'Failed to start auth flow' });
+            });
+        });
+    }
+    /** Authenticate using a Personal Access Token piped to gh stdin. */
+    async connectWithToken(token) {
+        try {
+            // spawn is safe: no shell, args are hardcoded literals, token via stdin (not args)
+            const child = spawn('gh', ['auth', 'login', '--with-token'], {
+                cwd: this.projectRoot,
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            return new Promise((resolve) => {
+                let stderr = '';
+                child.stderr?.on('data', (data) => { stderr += data.toString(); });
+                child.on('close', (code) => {
+                    this.clearCaches();
+                    if (code === 0) {
+                        resolve({ success: true });
+                    }
+                    else {
+                        resolve({ success: false, error: stderr || 'Authentication failed' });
+                    }
+                });
+                child.on('error', () => {
+                    resolve({ success: false, error: 'Failed to run gh auth' });
+                });
+                child.stdin?.write(token);
+                child.stdin?.end();
+            });
+        }
+        catch {
+            return { success: false, error: 'Failed to authenticate' };
+        }
+    }
+    /** Lightweight auth check — returns current user if authenticated. */
+    async getAuthStatus() {
+        try {
+            const whoami = await this.gh(['api', 'user', '--jq', '.login']);
+            const user = whoami.trim();
+            return user ? { authenticated: true, user } : { authenticated: false };
+        }
+        catch {
+            return { authenticated: false };
+        }
+    }
+    /** Log out of GitHub CLI. */
+    async disconnect() {
+        try {
+            // execFile is safe — no shell injection
+            await execFile('gh', ['auth', 'logout', '--hostname', 'github.com'], {
+                cwd: this.projectRoot,
+                timeout: 10_000,
+                env: { ...process.env, GH_PROMPT_DISABLED: '1' },
+            });
+            this.clearCaches();
+            return { success: true };
+        }
+        catch (err) {
+            this.clearCaches();
+            return { success: false, error: String(err) };
+        }
+    }
+    // ─── CI Checks ─────────────────────────────────────────────
+    /** Fetch GitHub Actions check runs for a commit ref. */
+    async getCheckRuns(ref) {
+        // Validate ref to prevent path traversal — only allow hex SHA and branch-like names
+        if (!/^[a-zA-Z0-9._/-]+$/.test(ref))
+            return [];
+        try {
+            const raw = await this.gh([
+                'api', `repos/{owner}/{repo}/commits/${ref}/check-runs`,
+                '--jq', '.check_runs | map({name, status, conclusion, html_url})',
+            ]);
+            const parsed = JSON.parse(raw);
+            return parsed.map(c => ({
+                name: String(c.name ?? ''),
+                status: String(c.status ?? 'queued'),
+                conclusion: c.conclusion ? String(c.conclusion) : null,
+                url: String(c.html_url ?? ''),
+            }));
+        }
+        catch {
+            return [];
+        }
+    }
+    clearCaches() {
+        this.statusCache = null;
+        this.prCache = null;
+    }
 }

package/dist/server/server/services/readiness-service.test.js

@@ -0,0 +1,190 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { ReadinessService } from './readiness-service.js';
+import { WorkflowEngine } from '../../shared/workflow-engine.js';
+import { CONFIG_WITH_HOOKS } from '../../shared/__fixtures__/workflow-configs.js';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+function makeScope(overrides) {
+    return {
+        title: `Scope ${overrides.id}`,
+        slug: undefined,
+        status: 'backlog',
+        priority: null,
+        effort_estimate: null,
+        category: null,
+        tags: [],
+        blocked_by: [],
+        blocks: [],
+        file_path: `/scopes/backlog/${String(overrides.id).padStart(3, '0')}-test.md`,
+        created_at: null,
+        updated_at: null,
+        raw_content: '# Test Scope\nSome content here.',
+        sessions: {},
+        is_ghost: false,
+        favourite: false,
+        ...overrides,
+    };
+}
+describe('ReadinessService', () => {
+    let engine;
+    let tmpDir;
+    let service;
+    let mockScopeService;
+    let mockGateService;
+    let scopes;
+    beforeEach(() => {
+        engine = new WorkflowEngine(CONFIG_WITH_HOOKS);
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'readiness-test-'));
+        scopes = [
+            makeScope({ id: 1, status: 'backlog', sessions: { implementScope: ['sess-1'] } }),
+            makeScope({ id: 2, status: 'active', sessions: { implementScope: ['sess-1'] }, blocked_by: [99] }),
+            makeScope({ id: 3, status: 'active', sessions: { implementScope: ['sess-1'] }, raw_content: '# Scope\n- [ ] Task 1\n- [x] Task 2' }),
+            makeScope({ id: 99, status: 'shipped' }), // terminal blocker
+            makeScope({ id: 100, status: 'backlog' }), // non-terminal blocker
+        ];
+        mockScopeService = { getById: (id) => scopes.find(s => s.id === id) };
+        mockGateService = {
+            getLatestForScope: vi.fn().mockReturnValue([]),
+            getLatestRun: vi.fn().mockReturnValue([]),
+        };
+        service = new ReadinessService(mockScopeService, mockGateService, engine, tmpDir);
+    });
+    afterEach(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+    describe('getReadiness()', () => {
+        it('returns null for unknown scope', () => {
+            expect(service.getReadiness(999)).toBeNull();
+        });
+        it('returns readiness with transitions for known scope', () => {
+            const result = service.getReadiness(1);
+            expect(result).not.toBeNull();
+            expect(result.scope_id).toBe(1);
+            expect(result.transitions).toBeDefined();
+            expect(result.transitions.length).toBeGreaterThan(0);
+        });
+        it('includes hook statuses for each transition', () => {
+            const result = service.getReadiness(1);
+            const transition = result.transitions[0];
+            expect(transition.hooks).toBeDefined();
+            expect(Array.isArray(transition.hooks)).toBe(true);
+        });
+    });
+    describe('session-enforcer hook', () => {
+        it('passes when session key exists for target column', () => {
+            // Scope 1 is in backlog, transition to active requires implementScope session key
+            // Scope 1 has sessions.implementScope = ['sess-1']
+            const result = service.getReadiness(1);
+            const toActive = result.transitions.find(t => t.to === 'active');
+            if (toActive) {
+                const enforcer = toActive.hooks.find(h => h.id === 'session-enforcer');
+                // If session-enforcer is on this edge, it should look at the target session key
+                if (enforcer) {
+                    // The scope has the required session, so it should pass
+                    expect(['pass', 'unknown']).toContain(enforcer.status);
+                }
+            }
+        });
+    });
+    describe('blocker-check hook', () => {
+        it('passes when blocker is in terminal status', () => {
+            // Scope 2 blocked_by [99], scope 99 is shipped (terminal)
+            const result = service.getReadiness(2);
+            const transition = result.transitions.find(t => t.hooks.some(h => h.id === 'blocker-check'));
+            if (transition) {
+                const blockerHook = transition.hooks.find(h => h.id === 'blocker-check');
+                expect(blockerHook?.status).toBe('pass');
+            }
+        });
+        it('fails when blocker is not in terminal status', () => {
+            // Add a scope blocked by non-terminal scope
+            scopes.push(makeScope({ id: 5, status: 'active', blocked_by: [100], sessions: { implementScope: ['s'] } }));
+            const result = service.getReadiness(5);
+            const transition = result.transitions.find(t => t.hooks.some(h => h.id === 'blocker-check'));
+            if (transition) {
+                const blockerHook = transition.hooks.find(h => h.id === 'blocker-check');
+                expect(blockerHook?.status).toBe('fail');
+            }
+        });
+    });
+    describe('review-gate-check hook', () => {
+        it('passes when verdict file exists with PASS', () => {
+            const verdictDir = path.join(tmpDir, '.claude', 'review-verdicts');
+            fs.mkdirSync(verdictDir, { recursive: true });
+            fs.writeFileSync(path.join(verdictDir, '002.json'), JSON.stringify({ verdict: 'PASS' }));
+            // Scope 2 is in active, edge active→review has review-gate-check
+            const result = service.getReadiness(2);
+            const toReview = result.transitions.find(t => t.to === 'review');
+            if (toReview) {
+                const reviewHook = toReview.hooks.find(h => h.id === 'review-gate-check');
+                if (reviewHook) {
+                    expect(reviewHook.status).toBe('pass');
+                }
+            }
+        });
+        it('fails when verdict file is missing', () => {
+            const result = service.getReadiness(2);
+            const toReview = result.transitions.find(t => t.to === 'review');
+            if (toReview) {
+                const reviewHook = toReview.hooks.find(h => h.id === 'review-gate-check');
+                if (reviewHook) {
+                    expect(reviewHook.status).toBe('fail');
+                }
+            }
+        });
+    });
+    describe('completion-checklist hook', () => {
+        it('fails when scope has unchecked items', () => {
+            // Scope 3 has raw_content with "- [ ] Task 1" (unchecked)
+            const result = service.getReadiness(3);
+            for (const transition of result.transitions) {
+                const checklist = transition.hooks.find(h => h.id === 'completion-checklist');
+                if (checklist) {
+                    expect(checklist.status).toBe('fail');
+                }
+            }
+        });
+    });
+    describe('scope-create-gate hook', () => {
+        it('passes when scope has title and content', () => {
+            const result = service.getReadiness(1);
+            for (const transition of result.transitions) {
+                const gate = transition.hooks.find(h => h.id === 'scope-create-gate');
+                if (gate) {
+                    expect(gate.status).toBe('pass');
+                }
+            }
+        });
+        it('fails when scope has no content', () => {
+            scopes.push(makeScope({ id: 6, status: 'backlog', title: '', raw_content: '' }));
+            const result = service.getReadiness(6);
+            for (const transition of result.transitions) {
+                const gate = transition.hooks.find(h => h.id === 'scope-create-gate');
+                if (gate) {
+                    expect(gate.status).toBe('fail');
+                }
+            }
+        });
+    });
+    describe('lifecycle/observer hooks', () => {
+        it('scope-transition always passes', () => {
+            const result = service.getReadiness(1);
+            for (const transition of result.transitions) {
+                const lifecycle = transition.hooks.find(h => h.id === 'scope-transition');
+                if (lifecycle) {
+                    expect(lifecycle.status).toBe('pass');
+                }
+            }
+        });
+        it('dashboard-sync always passes', () => {
+            const result = service.getReadiness(1);
+            for (const transition of result.transitions) {
+                const observer = transition.hooks.find(h => h.id === 'dashboard-sync');
+                if (observer) {
+                    expect(observer.status).toBe('pass');
+                }
+            }
+        });
+    });
+});

package/dist/server/server/services/scope-cache.js

@@ -52,7 +52,8 @@ export class ScopeCache {
     }
     /** Get the maximum raw scope number excluding icebox scopes (for next-ID generation).
      *  Cache keys use encoded IDs (suffixed scopes like 047a → 1047, 075x → 9075),
-     *  but next-ID generation needs the raw scope number (047, 075, 087). */
+     *  but next-ID generation needs the raw scope number (047, 075, 087).
+     *  Skips IDs >= 500 to handle legacy icebox-origin files during migration. */
     maxNonIceboxId() {
         let max = 0;
         for (const [id, scope] of this.byId) {
@@ -60,6 +61,9 @@ export class ScopeCache {
                 continue;
             // Decode: encoded IDs ≥1000 have a suffix offset — raw number is id % 1000
             const raw = id >= 1000 ? id % 1000 : id;
+            // Skip legacy icebox-origin IDs (500+) to prevent namespace pollution
+            if (raw >= 500)
+                continue;
             if (raw > max)
                 max = raw;
         }

package/dist/server/server/services/scope-cache.test.js

@@ -0,0 +1,142 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { ScopeCache } from './scope-cache.js';
+function makeScope(overrides) {
+    return {
+        title: `Scope ${overrides.id}`,
+        slug: undefined,
+        status: 'backlog',
+        priority: null,
+        effort_estimate: null,
+        category: null,
+        tags: [],
+        blocked_by: [],
+        blocks: [],
+        file_path: `/scopes/backlog/${String(overrides.id).padStart(3, '0')}-test.md`,
+        created_at: null,
+        updated_at: null,
+        raw_content: '',
+        sessions: {},
+        is_ghost: false,
+        favourite: false,
+        ...overrides,
+    };
+}
+describe('ScopeCache', () => {
+    let cache;
+    beforeEach(() => {
+        cache = new ScopeCache();
+    });
+    describe('loadAll()', () => {
+        it('populates both indexes', () => {
+            const scopes = [makeScope({ id: 1 }), makeScope({ id: 2 })];
+            cache.loadAll(scopes);
+            expect(cache.size).toBe(2);
+            expect(cache.getById(1)).toBeDefined();
+            expect(cache.getById(2)).toBeDefined();
+        });
+        it('clears previous data on re-load', () => {
+            cache.loadAll([makeScope({ id: 1 })]);
+            expect(cache.size).toBe(1);
+            cache.loadAll([makeScope({ id: 5 }), makeScope({ id: 6 })]);
+            expect(cache.size).toBe(2);
+            expect(cache.has(1)).toBe(false);
+            expect(cache.has(5)).toBe(true);
+        });
+    });
+    describe('set()', () => {
+        it('adds new scope', () => {
+            cache.set(makeScope({ id: 10 }));
+            expect(cache.has(10)).toBe(true);
+            expect(cache.size).toBe(1);
+        });
+        it('updates existing scope', () => {
+            cache.set(makeScope({ id: 10, title: 'Original' }));
+            cache.set(makeScope({ id: 10, title: 'Updated' }));
+            expect(cache.getById(10)?.title).toBe('Updated');
+            expect(cache.size).toBe(1);
+        });
+        it('cleans up old file_path index when scope moves', () => {
+            const oldPath = '/scopes/backlog/010-test.md';
+            const newPath = '/scopes/implementing/010-test.md';
+            cache.set(makeScope({ id: 10, file_path: oldPath }));
+            expect(cache.idByFilePath(oldPath)).toBe(10);
+            cache.set(makeScope({ id: 10, file_path: newPath }));
+            expect(cache.idByFilePath(oldPath)).toBeUndefined();
+            expect(cache.idByFilePath(newPath)).toBe(10);
+        });
+    });
+    describe('removeByFilePath()', () => {
+        it('removes from both indexes and returns removed ID', () => {
+            const scope = makeScope({ id: 10 });
+            cache.set(scope);
+            const removedId = cache.removeByFilePath(scope.file_path);
+            expect(removedId).toBe(10);
+            expect(cache.has(10)).toBe(false);
+            expect(cache.idByFilePath(scope.file_path)).toBeUndefined();
+        });
+        it('returns undefined for unknown path', () => {
+            expect(cache.removeByFilePath('/nonexistent')).toBeUndefined();
+        });
+    });
+    describe('read operations', () => {
+        beforeEach(() => {
+            cache.loadAll([
+                makeScope({ id: 3, title: 'Three' }),
+                makeScope({ id: 1, title: 'One' }),
+                makeScope({ id: 2, title: 'Two' }),
+            ]);
+        });
+        it('getById() returns scope or undefined', () => {
+            expect(cache.getById(1)?.title).toBe('One');
+            expect(cache.getById(999)).toBeUndefined();
+        });
+        it('getAll() returns sorted by ID', () => {
+            const all = cache.getAll();
+            expect(all.map(s => s.id)).toEqual([1, 2, 3]);
+        });
+        it('has() returns boolean', () => {
+            expect(cache.has(1)).toBe(true);
+            expect(cache.has(999)).toBe(false);
+        });
+        it('idByFilePath() returns ID or undefined', () => {
+            const scope = cache.getById(1);
+            expect(cache.idByFilePath(scope.file_path)).toBe(1);
+            expect(cache.idByFilePath('/nonexistent')).toBeUndefined();
+        });
+    });
+    describe('maxNonIceboxId()', () => {
+        it('returns 0 for empty cache', () => {
+            expect(cache.maxNonIceboxId()).toBe(0);
+        });
+        it('returns highest raw ID', () => {
+            cache.loadAll([
+                makeScope({ id: 10, status: 'backlog' }),
+                makeScope({ id: 20, status: 'implementing' }),
+                makeScope({ id: 5, status: 'review' }),
+            ]);
+            expect(cache.maxNonIceboxId()).toBe(20);
+        });
+        it('ignores icebox-status scopes', () => {
+            cache.loadAll([
+                makeScope({ id: 10, status: 'backlog' }),
+                makeScope({ id: 50, status: 'icebox' }),
+            ]);
+            expect(cache.maxNonIceboxId()).toBe(10);
+        });
+        it('decodes encoded IDs (>= 1000) to raw numbers', () => {
+            // 1047 → suffix-encoded → raw is 1047 % 1000 = 47
+            cache.loadAll([
+                makeScope({ id: 1047, status: 'backlog' }),
+                makeScope({ id: 10, status: 'implementing' }),
+            ]);
+            expect(cache.maxNonIceboxId()).toBe(47);
+        });
+        it('skips raw IDs >= 500 (legacy icebox-origin)', () => {
+            cache.loadAll([
+                makeScope({ id: 501, status: 'backlog' }),
+                makeScope({ id: 30, status: 'implementing' }),
+            ]);
+            expect(cache.maxNonIceboxId()).toBe(30);
+        });
+    });
+});