peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/cli/commands/core/standards-command.js

@@ -0,0 +1,95 @@
+import { summarizeProjectStandardsInitResult, summarizeProjectStandardsUpdateResult } from '../../../services/standards/project-standards-service.js';
+import { executeProjectStandardsInitIdeAware, executeProjectStandardsUpdateIdeAware } from '../../../services/standards/ide-aware-standards-service.js';
+import { migrateStandards } from '../../../services/standards/migrate-service.js';
+import { migrateClaudeRules } from '../../../services/standards/migrate-claude-rules-service.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, getErrorMessage, printResult } from '../../cli-helpers.js';
+export function registerStandardsCommand(program, io) {
+    const standards = program.command('standards').description('Manage project-local coding standards');
+    addJsonOption(standards
+        .command('init')
+        .description('Initialize project-local coding standards for Peaks skill preflight')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--language <language>', 'standards language pack')
+        .option('--ide <id>', 'override IDE detection (e.g. claude-code, trae)')
+        .option('--dry-run', 'preview writes without changing files')
+        .option('--apply', 'write missing standards into the target project')).action((options) => {
+        if (options.dryRun === true && options.apply === true) {
+            printResult(io, fail('standards.init', 'INVALID_STANDARDS_INIT_FLAGS', 'Use either --dry-run or --apply, not both', {}, ['Run without --apply to preview writes, or omit --dry-run when applying standards']), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            const result = executeProjectStandardsInitIdeAware({ projectRoot: options.project, ...(options.language !== undefined ? { language: options.language } : {}), ...(options.ide !== undefined ? { ideId: options.ide } : {}), apply: options.apply === true });
+            printResult(io, ok('standards.init', summarizeProjectStandardsInitResult(result)), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('standards.init', 'STANDARDS_INIT_FAILED', getErrorMessage(error), {}, ['Check the project path and existing .claude/rules directory before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(standards
+        .command('update')
+        .description('Append managed standards metadata to an existing CLAUDE.md without rewriting the body')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--language <language>', 'standards language pack')
+        .option('--ide <id>', 'override IDE detection (e.g. claude-code, trae)')
+        .option('--dry-run', 'preview writes without changing files')
+        .option('--apply', 'append managed metadata to the target project')).action((options) => {
+        if (options.dryRun === true && options.apply === true) {
+            printResult(io, fail('standards.update', 'INVALID_STANDARDS_UPDATE_FLAGS', 'Use either --dry-run or --apply, not both', {}, ['Run without --apply to preview writes, or omit --dry-run when applying standards updates']), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            const result = executeProjectStandardsUpdateIdeAware({ projectRoot: options.project, ...(options.language !== undefined ? { language: options.language } : {}), ...(options.ide !== undefined ? { ideId: options.ide } : {}), apply: options.apply === true });
+            const summary = summarizeProjectStandardsUpdateResult(result);
+            const response = summary.reviewSuggestions.length > 0
+                ? fail('standards.update', 'STANDARDS_UPDATE_REVIEW_REQUIRED', 'Standards update requires manual review', summary, summary.reviewSuggestions)
+                : ok('standards.update', summary);
+            printResult(io, response, options.json);
+            if (summary.reviewSuggestions.length > 0) {
+                process.exitCode = 1;
+            }
+        }
+        catch (error) {
+            printResult(io, fail('standards.update', 'STANDARDS_UPDATE_FAILED', getErrorMessage(error), {}, ['Check the project path, CLAUDE.md contents, and existing .claude/rules directory before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(standards
+        .command('migrate')
+        .description('Rewrite a consumer project CLAUDE.md to drop the legacy heartbeat block (slice 028). Dry-run by default; pass --apply to write. With --from-claude-rules, thins the 1.x .claude/rules/ tree to 2-line pointers and scaffolds .peaks/standards/ (slice 2026-06-12-standards-migrate-claude-rules).')
+        .option('--project <path>', 'target project root')
+        .option('--apply', 'rewrite the legacy block in place; default is dry-run')
+        .option('--from-claude-rules', 'thin .claude/rules/ to pointers and scaffold .peaks/standards/ (used by `peaks upgrade --to 2.0`)')).action((options) => {
+        const projectRoot = options.project ?? process.cwd();
+        if (options.fromClaudeRules === true) {
+            try {
+                const result = migrateClaudeRules({ projectRoot, apply: options.apply === true });
+                printResult(io, ok('standards.migrate', result.data, [], [...result.data.nextActions]), options.json);
+            }
+            catch (error) {
+                printResult(io, fail('standards.migrate', 'STANDARDS_MIGRATE_FAILED', getErrorMessage(error), {
+                    backupPath: null,
+                    thinnedFiles: [],
+                    scaffoldedFiles: [],
+                    preservedFiles: [],
+                    wouldChange: false,
+                    applied: false,
+                    nextActions: [],
+                }, [getErrorMessage(error)]), options.json);
+                process.exitCode = 1;
+            }
+            return;
+        }
+        try {
+            const result = migrateStandards({ project: projectRoot, apply: options.apply === true });
+            printResult(io, ok('standards.migrate', result.data, [], result.data.nextActions), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('standards.migrate', 'STANDARDS_MIGRATE_FAILED', getErrorMessage(error), { file: null, foundOldBlock: false, wouldChange: false, applied: false, before: null, after: null, nextActions: [] }, [getErrorMessage(error)]), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/commands/core-artifact-commands.d.ts

@@ -0,0 +1,15 @@
+import type { Command } from 'commander';
+import type { ProgramIO } from '../cli-helpers.js';
+export type { DoctorLogsSection, BindingSource } from './core/doctor-command.js';
+/**
+ * Top-level CLI command registrar for the "core + artifact" surface.
+ *
+ * Slice 2026-06-24-handoff-path-canonicalization split this orchestrator
+ * out of a single 889-line file so each subcommand group lives in its
+ * own module under `src/cli/commands/core/`. The orchestrator stays
+ * thin (~this file) and forwards to the per-group registrars; the
+ * public `registerCoreAndArtifactCommands(program, io)` signature is
+ * preserved verbatim so `src/cli/program.ts` and the cli-command-branches
+ * unit tests keep importing it from the same path.
+ */
+export declare function registerCoreAndArtifactCommands(program: Command, io: ProgramIO): void;

package/dist/cli/commands/core-artifact-commands.js

@@ -0,0 +1,31 @@
+import { registerArtifactsCommand } from './core/artifacts-command.js';
+import { registerBindingCommands } from './core/binding-commands.js';
+import { registerDoctorCommand } from './core/doctor-command.js';
+import { registerMemoryCommand } from './core/memory-command.js';
+import { registerProfileCommand } from './core/profile-command.js';
+import { registerProxyCommand } from './core/proxy-command.js';
+import { registerSessionCommand } from './core/session-command.js';
+import { registerSkillCommand } from './core/skill-command.js';
+import { registerStandardsCommand } from './core/standards-command.js';
+/**
+ * Top-level CLI command registrar for the "core + artifact" surface.
+ *
+ * Slice 2026-06-24-handoff-path-canonicalization split this orchestrator
+ * out of a single 889-line file so each subcommand group lives in its
+ * own module under `src/cli/commands/core/`. The orchestrator stays
+ * thin (~this file) and forwards to the per-group registrars; the
+ * public `registerCoreAndArtifactCommands(program, io)` signature is
+ * preserved verbatim so `src/cli/program.ts` and the cli-command-branches
+ * unit tests keep importing it from the same path.
+ */
+export function registerCoreAndArtifactCommands(program, io) {
+    registerDoctorCommand(program, io);
+    registerBindingCommands(program, io);
+    registerSkillCommand(program, io);
+    registerSessionCommand(program, io);
+    registerProfileCommand(program, io);
+    registerStandardsCommand(program, io);
+    registerMemoryCommand(program, io);
+    registerProxyCommand(program, io);
+    registerArtifactsCommand(program, io);
+}

package/dist/cli/commands/cron-commands.d.ts

@@ -0,0 +1,57 @@
+/**
+ * `peaks cron` — slice 2026-07-29-worktree-l2-extended Part 14.
+ *
+ * Persistent scheduled-task system. Stores a JSON schedule at
+ * `.peaks/cron/schedule.json` and lets the LLM-side runner
+ * trigger tasks synchronously (`peaks cron run <id>`) or
+ * register a built-in periodic lease gc that the runbook
+ * (`skills/peaks-code/`) checks on every session start.
+ *
+ * Built-in tasks (the only ones auto-registered today):
+ *   - `lease-gc-daily` — runs `peaks worktree gc --all-sessions
+ *     --project .` once every 24h. Cleans up orphan leases that
+ *     leaked past their auto-release hook (Part 3.A) — the
+ *     safety net for the safety net.
+ *
+ * Why a JSON file (not a real cron daemon): peaks-loop is a CLI
+ * tool, not a service. The schedule is best-effort: the runbook
+ * checks it on session start and surfaces overdue tasks. A
+ * proper system cron / systemd timer is the production
+ * deployment story; this CLI is the portable fallback.
+ *
+ * File layout:
+ *   .peaks/cron/schedule.json — registered tasks with their
+ *     interval + lastRunAt
+ *   .peaks/cron/history.jsonl — append-only run history
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+declare const SCHEDULE_VERSION: 1;
+export type ScheduleEntry = {
+    readonly id: string;
+    readonly name: string;
+    readonly command: string;
+    readonly args: ReadonlyArray<string>;
+    readonly intervalMs: number;
+    readonly lastRunAt: number | null;
+    readonly enabled: boolean;
+    readonly createdAt: number;
+};
+export type ScheduleFile = {
+    readonly version: typeof SCHEDULE_VERSION;
+    readonly entries: ReadonlyArray<ScheduleEntry>;
+};
+export type RunRecord = {
+    readonly id: string;
+    readonly taskId: string;
+    readonly startedAt: number;
+    readonly finishedAt: number;
+    readonly exitCode: number;
+    readonly stderr: string;
+};
+export declare function readSchedule(projectRoot: string): ScheduleFile;
+export declare function appendHistory(projectRoot: string, record: RunRecord): void;
+export declare function runTask(projectRoot: string, task: ScheduleEntry): RunRecord;
+export declare function listDueTasks(projectRoot: string, now?: number): ReadonlyArray<ScheduleEntry>;
+export declare function registerCronCommand(program: Command, io: ProgramIO): void;
+export {};

package/dist/cli/commands/cron-commands.js

@@ -0,0 +1,257 @@
+/**
+ * `peaks cron` — slice 2026-07-29-worktree-l2-extended Part 14.
+ *
+ * Persistent scheduled-task system. Stores a JSON schedule at
+ * `.peaks/cron/schedule.json` and lets the LLM-side runner
+ * trigger tasks synchronously (`peaks cron run <id>`) or
+ * register a built-in periodic lease gc that the runbook
+ * (`skills/peaks-code/`) checks on every session start.
+ *
+ * Built-in tasks (the only ones auto-registered today):
+ *   - `lease-gc-daily` — runs `peaks worktree gc --all-sessions
+ *     --project .` once every 24h. Cleans up orphan leases that
+ *     leaked past their auto-release hook (Part 3.A) — the
+ *     safety net for the safety net.
+ *
+ * Why a JSON file (not a real cron daemon): peaks-loop is a CLI
+ * tool, not a service. The schedule is best-effort: the runbook
+ * checks it on session start and surfaces overdue tasks. A
+ * proper system cron / systemd timer is the production
+ * deployment story; this CLI is the portable fallback.
+ *
+ * File layout:
+ *   .peaks/cron/schedule.json — registered tasks with their
+ *     interval + lastRunAt
+ *   .peaks/cron/history.jsonl — append-only run history
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { execSync } from 'node:child_process';
+import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+const SCHEDULE_VERSION = 1;
+const SCHEDULE_FILENAME = 'schedule.json';
+const HISTORY_FILENAME = 'history.jsonl';
+const DEFAULT_INTERVAL_MS = 24 * 60 * 60 * 1_000; // 24h
+function cronDir(projectRoot) {
+    return join(projectRoot, '.peaks', 'cron');
+}
+function schedulePath(projectRoot) {
+    return join(cronDir(projectRoot), SCHEDULE_FILENAME);
+}
+function historyPath(projectRoot) {
+    return join(cronDir(projectRoot), HISTORY_FILENAME);
+}
+export function readSchedule(projectRoot) {
+    const path = schedulePath(projectRoot);
+    if (!existsSync(path))
+        return { version: SCHEDULE_VERSION, entries: [] };
+    const raw = readFileSync(path, 'utf8');
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`schedule.json malformed: ${err.message}`);
+    }
+    if (typeof parsed !== 'object' || parsed === null) {
+        throw new Error('schedule.json root must be an object');
+    }
+    const obj = parsed;
+    if (obj.version !== SCHEDULE_VERSION) {
+        throw new Error(`schedule.json version mismatch (got ${String(obj.version)}, expected ${SCHEDULE_VERSION})`);
+    }
+    if (!Array.isArray(obj.entries)) {
+        throw new Error('schedule.json entries must be an array');
+    }
+    const entries = [];
+    for (const e of obj.entries) {
+        if (typeof e !== 'object' || e === null)
+            continue;
+        const ent = e;
+        if (typeof ent.id !== 'string' || typeof ent.name !== 'string' || typeof ent.command !== 'string')
+            continue;
+        if (!Array.isArray(ent.args) || !ent.args.every((a) => typeof a === 'string'))
+            continue;
+        if (typeof ent.intervalMs !== 'number' || typeof ent.createdAt !== 'number')
+            continue;
+        entries.push({
+            id: ent.id,
+            name: ent.name,
+            command: ent.command,
+            args: ent.args,
+            intervalMs: ent.intervalMs,
+            lastRunAt: typeof ent.lastRunAt === 'number' ? ent.lastRunAt : null,
+            enabled: ent.enabled !== false,
+            createdAt: ent.createdAt
+        });
+    }
+    return { version: SCHEDULE_VERSION, entries };
+}
+function writeSchedule(projectRoot, file) {
+    const dir = cronDir(projectRoot);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    writeFileSync(schedulePath(projectRoot), `${JSON.stringify(file, null, 2)}\n`, 'utf8');
+}
+export function appendHistory(projectRoot, record) {
+    const dir = cronDir(projectRoot);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    const path = historyPath(projectRoot);
+    const line = `${JSON.stringify(record)}\n`;
+    if (!existsSync(path)) {
+        writeFileSync(path, line, 'utf8');
+    }
+    else {
+        // Append — small file, OK to read+write
+        const existing = readFileSync(path, 'utf8');
+        writeFileSync(path, existing + line, 'utf8');
+    }
+}
+function ensureLeaseGcEntry(file) {
+    if (file.entries.some((e) => e.id === 'lease-gc-daily'))
+        return file;
+    const entry = {
+        id: 'lease-gc-daily',
+        name: 'Daily lease listing — refresh the alive-lease set; operators run peaks worktree gc --lease-id <id> manually on stale entries',
+        command: 'worktree',
+        args: ['list'],
+        intervalMs: DEFAULT_INTERVAL_MS,
+        lastRunAt: null,
+        enabled: true,
+        createdAt: Date.now()
+    };
+    return { version: SCHEDULE_VERSION, entries: [...file.entries, entry] };
+}
+export function runTask(projectRoot, task) {
+    const id = randomUUID();
+    const startedAt = Date.now();
+    let exitCode = 0;
+    let stderr = '';
+    try {
+        execSync(`peaks ${task.command} ${task.args.map((a) => `"${a.replace(/"/g, '\\"')}"`).join(' ')}`, {
+            cwd: projectRoot,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            encoding: 'utf8',
+            timeout: 5 * 60_000
+        });
+    }
+    catch (err) {
+        const e = err;
+        exitCode = typeof e.status === 'number' ? e.status : 1;
+        stderr = (e.stderr ?? getErrorMessage(err)).slice(0, 2000);
+    }
+    const record = {
+        id,
+        taskId: task.id,
+        startedAt,
+        finishedAt: Date.now(),
+        exitCode,
+        stderr
+    };
+    appendHistory(projectRoot, record);
+    return record;
+}
+export function listDueTasks(projectRoot, now = Date.now()) {
+    const file = readSchedule(projectRoot);
+    return file.entries.filter((e) => {
+        if (!e.enabled)
+            return false;
+        if (e.lastRunAt === null)
+            return true;
+        return now - e.lastRunAt >= e.intervalMs;
+    });
+}
+export function registerCronCommand(program, io) {
+    const cmd = program
+        .command('cron')
+        .description('Persistent scheduled tasks (Part 14; companion to peaks worktree / peaks container).');
+    addJsonOption(cmd.command('init')
+        .description('Create .peaks/cron/schedule.json with the built-in tasks (currently: lease-gc-daily). Idempotent.')
+        .option('--project <path>', 'project root (default: findProjectRoot(cwd))')).action((options) => {
+        try {
+            const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+            const file = readSchedule(projectRoot);
+            const updated = ensureLeaseGcEntry(file);
+            writeSchedule(projectRoot, updated);
+            const added = updated.entries.length - file.entries.length;
+            printResult(io, ok('cron.init', { projectRoot, schedulePath: schedulePath(projectRoot), totalEntries: updated.entries.length, added }, [], [
+                added > 0
+                    ? `Added ${added} built-in task(s). Use 'peaks cron list' to inspect.`
+                    : 'Schedule already contains the built-in tasks; no change made.'
+            ]), options.json);
+        }
+        catch (err) {
+            printResult(io, fail('cron.init', 'CRON_INIT_FAILED', getErrorMessage(err), { projectRoot: options.project }, [
+                'Verify the project root is a peaks-loop project (.peaks/ exists).',
+                'Check filesystem permissions.'
+            ]), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(cmd.command('list')
+        .description('List all registered cron tasks + their due status (relative to now).')
+        .option('--project <path>', 'project root (default: findProjectRoot(cwd))')).action((options) => {
+        try {
+            const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+            const file = readSchedule(projectRoot);
+            const now = Date.now();
+            const annotated = file.entries.map((e) => ({
+                ...e,
+                due: e.enabled && (e.lastRunAt === null || now - e.lastRunAt >= e.intervalMs),
+                nextDueAt: e.lastRunAt === null ? now : e.lastRunAt + e.intervalMs
+            }));
+            annotated.sort((a, b) => a.nextDueAt - b.nextDueAt);
+            printResult(io, ok('cron.list', { projectRoot, schedulePath: schedulePath(projectRoot), entries: annotated }, [], [
+                `${annotated.length} task(s); ${annotated.filter((e) => e.due).length} due now.`
+            ]), options.json);
+        }
+        catch (err) {
+            printResult(io, fail('cron.list', 'CRON_LIST_FAILED', getErrorMessage(err), { projectRoot: options.project }, [
+                "If schedule.json is missing, run 'peaks cron init' first."
+            ]), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(cmd.command('run')
+        .description('Run the specified task (by id) immediately, update lastRunAt, append a history record.')
+        .option('--id <taskId>', 'task id to run (default: all due tasks)')
+        .option('--project <path>', 'project root (default: findProjectRoot(cwd))')).action((options) => {
+        try {
+            const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+            const file = readSchedule(projectRoot);
+            const targets = options.id
+                ? file.entries.filter((e) => e.id === options.id)
+                : listDueTasks(projectRoot);
+            if (targets.length === 0) {
+                printResult(io, ok('cron.run', { projectRoot, ran: 0, records: [] }, [], ['No due tasks; nothing to run.']), options.json);
+                return;
+            }
+            const records = [];
+            const updatedEntries = [];
+            const now = Date.now();
+            for (const task of file.entries) {
+                if (!targets.some((t) => t.id === task.id)) {
+                    updatedEntries.push(task);
+                    continue;
+                }
+                const record = runTask(projectRoot, task);
+                records.push(record);
+                updatedEntries.push({ ...task, lastRunAt: record.finishedAt });
+            }
+            writeSchedule(projectRoot, { version: SCHEDULE_VERSION, entries: updatedEntries });
+            printResult(io, ok('cron.run', { projectRoot, ran: records.length, records }, records.filter((r) => r.exitCode !== 0).map((r) => `Task ${r.taskId} failed (exit=${r.exitCode}): ${r.stderr.slice(0, 200)}`), [`Ran ${records.length} task(s); ${records.filter((r) => r.exitCode === 0).length} succeeded.`]), options.json);
+            if (records.some((r) => r.exitCode !== 0))
+                process.exitCode = 1;
+        }
+        catch (err) {
+            printResult(io, fail('cron.run', 'CRON_RUN_FAILED', getErrorMessage(err), { projectRoot: options.project }, [
+                "If schedule.json is missing, run 'peaks cron init' first."
+            ]), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/commands/cron-scheduler-commands.d.ts

@@ -0,0 +1,47 @@
+/**
+ * `peaks cron scheduler start|stop|status|run-once` — slice 2026-07-29 Part 15.
+ *
+ * Companion CLI to Part 14 (peaks cron init/list/run). The
+ * scheduler is a long-running background daemon that wakes up
+ * once per minute, reads `.peaks/cron/schedule.json`, and runs
+ * any due tasks via detached execSync (so a misbehaving task
+ * cannot block the scheduler). Best-effort persistence via
+ * `.peaks/cron/scheduler.pid` (advisory — operators can `kill
+ * $(cat scheduler.pid)` if a stale entry lingers).
+ *
+ * Why a separate `peaks-cron-scheduler` CLI (not a peaks
+ * subcommand) — long-running daemons that are spawned from a
+ * `peaks ...` invocation confuse a future "which peaks version
+ * is running" check. A dedicated binary name keeps the
+ * scheduler's startup visible to operators.
+ *
+ * Windows: the scheduler writes its pid to a file. To run as
+ * a real Windows service, the operator wires NSSM (or
+ * node-windows) to call `peaks-cron-scheduler start` on
+ * service start. Future slice: ship an NSSM install recipe
+ * in the operator docs.
+ *
+ * POSIX: same pid-file pattern; an init.d / systemd unit
+ * file would call `peaks-cron-scheduler start` and rely on
+ * the scheduler to write its own pid. Or just run from
+ * `nohup peaks-cron-scheduler start &` if you don't need
+ * restart-on-crash.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerCronSchedulerCommand(program: Command, io: ProgramIO): void;
+/**
+ * Standalone scheduler entry point (the process the CLI spawns).
+ * Runs a setInterval tick + reads schedule + runs due tasks.
+ * Exits cleanly on SIGTERM.
+ *
+ * Exported as `runSchedulerLoop` so the dedicated
+ * `peaks-cron-scheduler.js` entry shim can call it; the
+ * command-side `registerCronSchedulerCommand` only uses
+ * start/stop/status, not the loop.
+ */
+export declare function runSchedulerLoop(args: {
+    projectRoot: string;
+    tickMs?: number;
+    signal?: AbortSignal;
+}): Promise<void>;