peaks-cli 1.3.1 → 1.3.3

package/dist/src/services/slice/slice-archive-service.js

@@ -0,0 +1,111 @@
+/**
+ * Slice #009 / G5 RL-8 — sub-agent dispatch record archival + 30-day GC.
+ *
+ * Called by the `peaks session finish` / `peaks session abandon` /
+ * new-rid-startup hooks. Walks the per-session `.peaks/_sub_agents/<sid>/`
+ * tree and moves completed + disposed records to
+ * `.peaks/_runtime/<sid>/_archive/_sub_agents/<sliceId>/`.
+ *
+ * GC policy:
+ *   - Records with `disposed: true` AND `outcome ∈ {success, failed,
+ *     timeout, cancelled}` (not "no-execution") → archive + 30-day GC.
+ *   - Records with `disposed: false` (any outcome) → archive but NOT
+ *     GC'd. Next session will see them as still-pending in
+ *     `_archive/.../in-flight/` and can resume reducer work.
+ *
+ * Lazy GC: `archiveSubAgentRecords` also scans the archive dir and
+ * deletes entries older than 30 days. No cron, no background daemon.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { isDispatchStatus, isOutcome } from '../dispatch/dispatch-record-writer.js';
+export const ARCHIVE_RETENTION_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+/** Build the canonical archive dir for a given session + slice id. */
+export function archiveDir(projectRoot, sessionId, sliceId) {
+    return join(projectRoot, '.peaks', '_runtime', sessionId, '_archive', '_sub_agents', sliceId);
+}
+/** Build the in-flight subdir (records not yet disposed). */
+export function inFlightArchiveDir(projectRoot, sessionId, sliceId) {
+    return join(archiveDir(projectRoot, sessionId, sliceId), 'in-flight');
+}
+/**
+ * Archive the current `.peaks/_sub_agents/<sid>/` tree under
+ * `<archiveDir>` (per the sliceId), separating completed vs in-flight.
+ * Then run the 30-day GC over the archive dir.
+ */
+export function archiveSubAgentRecords(projectRoot, options) {
+    const now = options.now ?? (() => new Date());
+    const sourceDir = join(projectRoot, '.peaks', '_sub_agents', options.sessionId);
+    const completedDir = archiveDir(projectRoot, options.sessionId, options.sliceId);
+    const inFlightDir = inFlightArchiveDir(projectRoot, options.sessionId, options.sliceId);
+    mkdirSync(completedDir, { recursive: true });
+    mkdirSync(inFlightDir, { recursive: true });
+    let archivedCompleted = 0;
+    let archivedInFlight = 0;
+    if (existsSync(sourceDir)) {
+        for (const entry of readdirSync(sourceDir)) {
+            if (!entry.startsWith('dispatch-') || !entry.endsWith('.json'))
+                continue;
+            const src = join(sourceDir, entry);
+            const record = readRecordOrNull(src);
+            if (record === null)
+                continue;
+            if (record.disposed === true && isCompletedOutcome(record.outcome)) {
+                renameSync(src, join(completedDir, entry));
+                archivedCompleted += 1;
+            }
+            else {
+                renameSync(src, join(inFlightDir, entry));
+                archivedInFlight += 1;
+            }
+        }
+    }
+    // 30-day GC: walk the archive root (any sliceId), delete entries
+    // whose file mtime is older than the retention.
+    const gcDeleted = runGarbageCollection(completedDir, now().getTime());
+    return { archivedCompleted, archivedInFlight, gcDeleted };
+}
+function isCompletedOutcome(outcome) {
+    return outcome === 'success' || outcome === 'failed' || outcome === 'timeout' || outcome === 'cancelled';
+}
+function readRecordOrNull(path) {
+    try {
+        const raw = readFileSync(path, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== 'object' || parsed === null)
+            return null;
+        const obj = parsed;
+        if (!isOutcome(obj.outcome) || !isDispatchStatus(obj.status))
+            return null;
+        if (typeof obj.disposed !== 'boolean')
+            return null;
+        return obj;
+    }
+    catch {
+        return null;
+    }
+}
+function runGarbageCollection(dir, nowMs) {
+    if (!existsSync(dir))
+        return 0;
+    let deleted = 0;
+    for (const entry of readdirSync(dir)) {
+        const full = join(dir, entry);
+        try {
+            const stat = statSync(full);
+            if (stat.isDirectory()) {
+                deleted += runGarbageCollection(full, nowMs);
+                continue;
+            }
+            const ageMs = nowMs - stat.mtimeMs;
+            if (ageMs > ARCHIVE_RETENTION_MS) {
+                unlinkSync(full);
+                deleted += 1;
+            }
+        }
+        catch {
+            /* skip unreadable; do not crash the archive op */
+        }
+    }
+    return deleted;
+}

package/dist/src/services/slice/slice-check-service.js

@@ -210,7 +210,26 @@ export async function sliceCheck(options) {
     stages.push(await runTypecheck(options.projectRoot));
     // Stage 2: full vitest
     if (!options.skipTests) {
-        stages.push(await runUnitTests(options.projectRoot));
+        const unitTests = await runUnitTests(options.projectRoot);
+        // Opt-in override: if --allow-pre-existing-failures is set AND the
+        // unit-test stage failed, downgrade `failed` to `skipped` with a
+        // reason that names the failure count and points to the long-term
+        // fix. Does NOT affect the other 3 stages.
+        if (options.allowPreExistingFailures === true &&
+            unitTests.status === 'fail') {
+            const failureCount = unitTests.data?.failed ?? 0;
+            stages.push({
+                name: 'unit-tests',
+                description: 'npx vitest run (overridden via --allow-pre-existing-failures)',
+                status: 'skipped',
+                durationMs: unitTests.durationMs,
+                detail: `pre-existing failures: ${failureCount} failing test(s) under coverage.exclude or unrelated to this slice; user opted in via --allow-pre-existing-failures. For the long-term fix, mark these tests .skip or move to coverage.exclude (see dogfood-2-f1-f4.md F17c).`,
+                data: { ...(unitTests.data ?? {}), overriddenFrom: 'fail', failureCount }
+            });
+        }
+        else {
+            stages.push(unitTests);
+        }
     }
     else {
         stages.push({

package/dist/src/services/slice/slice-check-types.d.ts

@@ -58,4 +58,13 @@ export type SliceCheckOptions = {
      * tests (e.g. a docs-only or config-only slice).
      */
     skipTests: boolean;
+    /**
+     * When true, an `unit-tests` stage that fails is reported as `skipped`
+     * (with a `reason` naming the pre-existing failure count) instead of
+     * `failed`. Used to opt in to bypassing the 28 pre-existing Windows
+     * test failures documented in dogfood-2-f1-f4.md F17. Does NOT affect
+     * the other 3 stages (typecheck / review-fanout / gate-verify-pipeline).
+     * Default: false. The service treats `undefined` the same as `false`.
+     */
+    allowPreExistingFailures?: boolean;
 };

package/dist/src/services/solo/batch-heartbeat-poller.d.ts

@@ -0,0 +1,51 @@
+import { summarize, type SubAgentLiveView } from './status-line-renderer.js';
+export declare const DEFAULT_POLL_INTERVAL_MS = 10000;
+export declare const DEFAULT_STALE_THRESHOLD_MS: number;
+export type PollRecord = {
+    readonly path: string;
+    readonly role: string;
+};
+export type PollerStatusEvent = {
+    readonly kind: 'status';
+    readonly line: string;
+    readonly summary: ReturnType<typeof summarize>;
+    readonly views: readonly SubAgentLiveView[];
+};
+export type PollerStaleEvent = {
+    readonly kind: 'stale';
+    readonly path: string;
+    readonly role: string;
+    readonly lastBeatAgoSec: number;
+    readonly thresholdSec: number;
+};
+export type PollerDoneEvent = {
+    readonly kind: 'done';
+    readonly summary: ReturnType<typeof summarize>;
+};
+export type PollerEvent = PollerStatusEvent | PollerStaleEvent | PollerDoneEvent;
+export type PollerHandlers = {
+    onStatus?: (event: PollerStatusEvent) => void;
+    onStale?: (event: PollerStaleEvent) => void;
+    onDone?: (event: PollerDoneEvent) => void;
+    onError?: (error: unknown) => void;
+};
+export type PollerOptions = {
+    prefix: string;
+    intervalMs?: number;
+    staleThresholdMs?: number;
+    now?: () => Date;
+};
+export declare class BatchHeartbeatPoller {
+    private readonly records;
+    private readonly handlers;
+    private readonly options;
+    private timer;
+    private prevStale;
+    private prevSummaryDone;
+    private running;
+    constructor(records: readonly PollRecord[], handlers: PollerHandlers, options: PollerOptions);
+    start(): void;
+    stop(): void;
+    /** Force a tick (testing seam + low-level access for explicit invocation). */
+    tick(): void;
+}

package/dist/src/services/solo/batch-heartbeat-poller.js

@@ -0,0 +1,88 @@
+import { readRecords } from '../dispatch/dispatch-record-writer.js';
+import { renderStatusLine, summarize, viewSubAgent } from './status-line-renderer.js';
+export const DEFAULT_POLL_INTERVAL_MS = 10_000;
+export const DEFAULT_STALE_THRESHOLD_MS = 5 * 60 * 1000;
+const TERMINAL_STATUSES = ['done', 'failed'];
+const TERMINAL_RECORD_STATUSES = [
+    'done',
+    'failed',
+    'cancelled',
+    'no-execution'
+];
+export class BatchHeartbeatPoller {
+    records;
+    handlers;
+    options;
+    timer = null;
+    prevStale = new Set();
+    prevSummaryDone = 0;
+    running = false;
+    constructor(records, handlers, options) {
+        this.records = records;
+        this.handlers = handlers;
+        this.options = options;
+    }
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        this.tick();
+        const interval = this.options.intervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+        this.timer = setInterval(() => this.tick(), interval);
+        // Don't keep the process alive just for the poller.
+        this.timer.unref?.();
+    }
+    stop() {
+        this.running = false;
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    /** Force a tick (testing seam + low-level access for explicit invocation). */
+    tick() {
+        let recs;
+        try {
+            recs = readRecords(this.records.map((r) => r.path));
+        }
+        catch (error) {
+            this.handlers.onError?.(error);
+            return;
+        }
+        const now = this.options.now ?? (() => new Date());
+        const summary = summarize(recs);
+        const views = recs.map((r) => viewSubAgent(r, now));
+        const line = renderStatusLine(this.options.prefix, recs, now);
+        this.handlers.onStatus?.({ kind: 'status', line, summary, views });
+        const staleThresholdSec = Math.floor((this.options.staleThresholdMs ?? DEFAULT_STALE_THRESHOLD_MS) / 1000);
+        for (const rec of recs) {
+            const v = viewSubAgent(rec, now);
+            if (v.isStale) {
+                const key = `${rec.role}::${rec.requestId}`;
+                if (!this.prevStale.has(key)) {
+                    this.prevStale.add(key);
+                    this.handlers.onStale?.({
+                        kind: 'stale',
+                        path: this.records.find((p) => p.role === rec.role)?.path ?? '',
+                        role: rec.role,
+                        lastBeatAgoSec: v.lastBeatAgoSec ?? -1,
+                        thresholdSec: staleThresholdSec
+                    });
+                }
+            }
+        }
+        if (summary.total > 0 && summary.done === summary.total && this.prevSummaryDone !== summary.done) {
+            this.prevSummaryDone = summary.done;
+            this.handlers.onDone?.({ kind: 'done', summary });
+            this.stop();
+        }
+        else if (recs.length > 0 &&
+            recs.every((r) => TERMINAL_RECORD_STATUSES.includes(r.status) || TERMINAL_STATUSES.includes(r.status))) {
+            this.handlers.onDone?.({ kind: 'done', summary });
+            this.stop();
+        }
+        else {
+            this.prevSummaryDone = summary.done;
+        }
+    }
+}

package/dist/src/services/solo/status-line-renderer.d.ts

@@ -0,0 +1,34 @@
+/**
+ * G6.5 — status line renderer for the peaks-solo batch-sync wait period.
+ *
+ * Single line, 80-120 chars, status-line-friendly. The shape is
+ * documented in PRD §G6.5:
+ *
+ *   [peaks-solo] swarm 3/3 running | rd-planning 45% (12s ago) | qa-test-cases 30% (5s ago) | ui-design 20% (2s ago)
+ *   [peaks-solo] swarm 3/3 running | rd-planning 70% (8s ago) | qa-test-cases 50% (3s ago) | ui-design 30% (6s ago)
+ *   ...
+ *   [peaks-solo] swarm 3/3 done in 47.3s
+ *
+ * Pure helper; the poller calls it once per tick. No IO.
+ */
+import type { DispatchRecord } from '../dispatch/dispatch-record-writer.js';
+export type SubAgentLiveView = {
+    readonly role: string;
+    readonly status: string;
+    readonly progress: number | null;
+    readonly lastBeatAgoSec: number | null;
+    readonly isStale: boolean;
+};
+export type SwarmSummary = {
+    readonly total: number;
+    readonly running: number;
+    readonly done: number;
+    readonly failed: number;
+    readonly stale: number;
+};
+/** Build a per-sub-agent view of the current state of one record. */
+export declare function viewSubAgent(record: DispatchRecord, now?: () => Date): SubAgentLiveView;
+/** Aggregate swarm summary. */
+export declare function summarize(records: readonly DispatchRecord[]): SwarmSummary;
+/** Render a single status line. */
+export declare function renderStatusLine(prefix: string, records: readonly DispatchRecord[], now?: () => Date): string;

package/dist/src/services/solo/status-line-renderer.js

@@ -0,0 +1,55 @@
+const STALE_THRESHOLD_SEC = 5 * 60;
+/** Build a per-sub-agent view of the current state of one record. */
+export function viewSubAgent(record, now = () => new Date()) {
+    const latest = record.heartbeats[record.heartbeats.length - 1];
+    const lastBeatAgo = record.lastBeatAt
+        ? Math.max(0, Math.floor((now().getTime() - new Date(record.lastBeatAt).getTime()) / 1000))
+        : null;
+    const isStale = lastBeatAgo !== null && lastBeatAgo > STALE_THRESHOLD_SEC;
+    return {
+        role: record.role,
+        status: record.status,
+        progress: latest ? latest.progress : null,
+        lastBeatAgoSec: lastBeatAgo,
+        isStale
+    };
+}
+/** Aggregate swarm summary. */
+export function summarize(records) {
+    let running = 0;
+    let done = 0;
+    let failed = 0;
+    let stale = 0;
+    for (const r of records) {
+        const v = viewSubAgent(r);
+        if (v.isStale)
+            stale += 1;
+        if (r.status === 'done')
+            done += 1;
+        else if (r.status === 'failed' || r.status === 'cancelled')
+            failed += 1;
+        else
+            running += 1;
+    }
+    return { total: records.length, running, done, failed, stale };
+}
+/** Render a single status line. */
+export function renderStatusLine(prefix, records, now = () => new Date()) {
+    if (records.length === 0) {
+        return `${prefix} swarm 0/0 idle`;
+    }
+    const summary = summarize(records);
+    const allDone = summary.done === summary.total;
+    if (allDone) {
+        return `${prefix} swarm ${summary.done}/${summary.total} done`;
+    }
+    const parts = records.map((r) => renderOne(r, now));
+    return `${prefix} swarm ${summary.running}/${summary.total} running | ${parts.join(' | ')}`;
+}
+function renderOne(record, now) {
+    const view = viewSubAgent(record, now);
+    const pct = view.progress !== null ? `${view.progress}%` : '?%';
+    const ago = view.lastBeatAgoSec !== null ? `${view.lastBeatAgoSec}s ago` : 'no beat';
+    const stale = view.isStale ? ' ⚠ stale' : '';
+    return `${view.role} ${pct} (${ago})${stale}`;
+}

package/dist/src/services/workspace/migrate-service.js

@@ -1,5 +1,5 @@
 import { execFileSync } from 'node:child_process';
-import { mkdir, readFile, readdir, rm } from 'node:fs/promises';
+import { mkdir, readFile, readdir, rename, rm } from 'node:fs/promises';
 import { join } from 'node:path';
 import { isDirectory, pathExists } from '../../shared/fs.js';
 import { isPathInsideArtifactRoot, validateChangeIdOrThrow } from '../../shared/change-id.js';
@@ -325,6 +325,107 @@ async function planSession(sessionId, sessionPath) {
     }
     return { sessionId, path: sessionPath, empty: empty && plans.every((p) => p.skipped), files: plans, fallbackChangeId: fallback };
 }
+/**
+ * Slice 003 (2026-06-06-session-layout-canonicalize): one-shot
+ * consolidation of every top-level `.peaks/<sid>/` into
+ * `.peaks/_runtime/<sid>/`. Idempotent:
+ *
+ *   - If `.peaks/_runtime/<sid>/` does not exist → `fs.rename` the
+ *     top-level dir to the runtime location.
+ *   - If `.peaks/_runtime/<sid>/` already exists with the same
+ *     content → no-op, reported as `skipped-already-canonical`.
+ *   - If `.peaks/_runtime/<sid>/` already exists with different
+ *     content → log a conflict, do NOT overwrite.
+ *   - **F15 carve-out**: if `<sid>/rd/project-scan.md` differs from
+ *     the runtime copy already in place, log a
+ *     `f15-conflict-project-scan` and leave the file in place.
+ *
+ * Path-traversal is impossible because the target is always
+ * `peaks/_runtime/<sid>/` and the directory listing only returns
+ * names matching the session-id regex.
+ */
+async function migrateToRuntime(projectRoot, peaksRoot, apply) {
+    void projectRoot;
+    const plans = [];
+    const moved = [];
+    const skipped = [];
+    const conflicts = [];
+    const runtimeRoot = join(peaksRoot, '_runtime');
+    let topLevelEntries;
+    try {
+        topLevelEntries = await readdir(peaksRoot, { withFileTypes: true });
+    }
+    catch {
+        return { plans, moved, skipped, conflicts };
+    }
+    for (const entry of topLevelEntries) {
+        if (!entry.isDirectory())
+            continue;
+        if (PROTECTED_TOP_LEVEL_DIRS.has(entry.name))
+            continue;
+        if (!/^\d{4}-\d{2}-\d{2}-session-/.test(entry.name))
+            continue;
+        const sessionId = entry.name;
+        const fromPath = join(peaksRoot, sessionId);
+        const toPath = join(runtimeRoot, sessionId);
+        if (await isDirectory(toPath)) {
+            // F15 carve-out check
+            const fromScan = join(fromPath, 'rd', 'project-scan.md');
+            const toScan = join(toPath, 'rd', 'project-scan.md');
+            if (await pathExists(fromScan) && await pathExists(toScan)) {
+                const fromContent = await readFile(fromScan, 'utf8').catch(() => null);
+                const toContent = await readFile(toScan, 'utf8').catch(() => null);
+                if (fromContent !== null && toContent !== null && fromContent !== toContent) {
+                    plans.push({
+                        from: fromPath,
+                        to: toPath,
+                        sessionId,
+                        action: 'f15-conflict-project-scan',
+                        reason: 'F15 carve-out: top-level rd/project-scan.md differs from runtime copy; left in place.'
+                    });
+                    conflicts.push({
+                        from: fromScan,
+                        to: toScan,
+                        reason: 'f15-conflict-project-scan'
+                    });
+                    continue;
+                }
+            }
+            plans.push({
+                from: fromPath,
+                to: toPath,
+                sessionId,
+                action: 'skipped-already-canonical',
+                reason: 'target _runtime/<sid>/ already exists'
+            });
+            skipped.push(sessionId);
+            continue;
+        }
+        plans.push({
+            from: fromPath,
+            to: toPath,
+            sessionId,
+            action: 'moved',
+            reason: 'top-level session dir will be moved to _runtime/'
+        });
+        if (apply) {
+            try {
+                await mkdir(runtimeRoot, { recursive: true });
+                await rename(fromPath, toPath);
+                moved.push(sessionId);
+            }
+            catch (error) {
+                const msg = error instanceof Error ? error.message : String(error);
+                conflicts.push({
+                    from: fromPath,
+                    to: toPath,
+                    reason: `rename failed: ${msg}`
+                });
+            }
+        }
+    }
+    return { plans, moved, skipped, conflicts };
+}
 async function gitMv(from, to, projectRoot) {
     const parentDir = join(to, '..');
     await mkdir(parentDir, { recursive: true });
@@ -470,6 +571,23 @@ export async function migrateWorkspace(options) {
             deletedSessions.push(session.sessionId);
         }
     }
+    // Slice 003: the `--to-runtime` step. When set, move every
+    // top-level `.peaks/<sid>/` to `.peaks/_runtime/<sid>/`. Idempotent.
+    // The F15 carve-out (rd/project-scan.md) is honored: when the
+    // top-level `<sid>/rd/project-scan.md` differs from the runtime
+    // `<sid>/rd/project-scan.md` already in place, the file is
+    // left at the top-level and a conflict is recorded.
+    let toRuntimePlans = [];
+    let toRuntimeMoved = [];
+    let toRuntimeSkipped = [];
+    let toRuntimeConflicts = [];
+    if (options.toRuntime === true) {
+        const result = await migrateToRuntime(options.projectRoot, peaksRoot, options.apply);
+        toRuntimePlans = result.plans;
+        toRuntimeMoved = result.moved;
+        toRuntimeSkipped = result.skipped;
+        toRuntimeConflicts = result.conflicts;
+    }
     return {
         projectRoot: options.projectRoot,
         sessions: sessionPlans,
@@ -479,6 +597,10 @@ export async function migrateWorkspace(options) {
         wouldDeleteSessions: wouldDeleteSessions,
         conflicts,
         apply: options.apply,
-        totalFilesMoved: options.apply ? moved.length : 0
+        totalFilesMoved: options.apply ? moved.length : 0,
+        toRuntimePlans,
+        toRuntimeMoved,
+        toRuntimeSkipped,
+        toRuntimeConflicts
     };
 }

package/dist/src/services/workspace/migrate-types.d.ts

@@ -53,14 +53,48 @@ export type MigrateSessionPlan = {
     /** The fallback change-id derived from the session's most recent `rd/requests/` entry. Null if no requests exist. */
     fallbackChangeId: string | null;
 };
+export type MigrateOptions = {
+    projectRoot: string;
+    /** When true, actually `git mv` the files + `rm -rf` the emptied session dirs. */
+    apply: boolean;
+    /**
+     * Slice 003 (2026-06-06-session-layout-canonicalize): when true, the
+     * command performs the **session-dir consolidation** — moves every
+     * top-level `.peaks/<sid>/` to `.peaks/_runtime/<sid>/`. Idempotent;
+     * conflicts (target exists with different content) are logged but
+     * never overwrite. With `apply: false` (the default), the response
+     * lists what WOULD move + the conflicts.
+     *
+     * Mutually exclusive with the reviewable-content migration: the
+     * `--to-runtime` step is the data side of slice 003, while the
+     * default `migrate` step is the cross-cutting content side
+     * (reviewable files → retrospective). Both run when both flags are
+     * set; the order is `--to-runtime` first (so the cross-cutting
+     * step sees the canonical tree) and then the reviewable-content
+     * step.
+     */
+    toRuntime?: boolean;
+};
+export type MigrateToRuntimeFilePlan = {
+    /** Absolute source path (top-level `.peaks/<sid>/`). */
+    from: string;
+    /** Absolute target path (`.peaks/_runtime/<sid>/`). */
+    to: string;
+    /** The session id the dir belongs to. */
+    sessionId: string;
+    /** 'moved' or 'skipped-already-canonical' or 'conflict'. */
+    action: 'moved' | 'skipped-already-canonical' | 'conflict-target-exists-with-different-content' | 'f15-conflict-project-scan';
+    /** Human-readable reason for the action (for the conflicts list). */
+    reason: string;
+};
 export type MigrateResult = {
     /** Absolute project root the command operated on. */
     projectRoot: string;
     /** All discovered legacy session dirs, sorted by name. */
     sessions: MigrateSessionPlan[];
-    /** All moves the apply step WOULD perform (only populated when `apply === false` as well, for symmetry). */
+    /** All moves the apply step WOULD perform (only populated when `apply: false` as well, for symmetry). */
     wouldMove: MigrateFilePlan[];
-    /** All moves actually performed (only populated when `apply === true`). */
+    /** All moves actually performed (only populated when `apply: true`). */
     moved: MigrateFilePlan[];
     /** Sessions that became empty after the move and were/will be removed. */
     deletedSessions: string[];
@@ -76,9 +110,18 @@ export type MigrateResult = {
     apply: boolean;
     /** Total files moved or scheduled to move. */
     totalFilesMoved: number;
-};
-export type MigrateOptions = {
-    projectRoot: string;
-    /** When true, actually `git mv` the files + `rm -rf` the emptied session dirs. */
-    apply: boolean;
+    /**
+     * Slice 003: per-session-dir move plans for the `--to-runtime` step.
+     * Empty when `toRuntime` was not set. Conflicts include both the
+     * top-level/<sid>/ → _runtime/<sid>/ collisions AND the F15 carve-out
+     * for `rd/project-scan.md`.
+     */
+    toRuntimePlans?: MigrateToRuntimeFilePlan[];
+    toRuntimeMoved?: string[];
+    toRuntimeSkipped?: string[];
+    toRuntimeConflicts?: Array<{
+        from: string;
+        to: string;
+        reason: string;
+    }>;
 };