peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/services/preferences/preferences-service.js

@@ -0,0 +1,208 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { DEFAULT_PREFERENCES, FANOUT_MODES, isFanoutMode, PREFERENCES_SCHEMA_VERSION, } from './preferences-types.js';
+const PREFS_REL_PATH = '.peaks/preferences.json';
+export { DEFAULT_PREFERENCES, PREFERENCES_SCHEMA_VERSION };
+export function preferencesPath(projectRoot) {
+    return join(projectRoot, PREFS_REL_PATH);
+}
+export function loadPreferences(projectRoot) {
+    const filePath = preferencesPath(projectRoot);
+    if (!existsSync(filePath)) {
+        // Slice 2026-07-22-orchestrator-memory-preflight: when
+        // .peaks/preferences.json is missing, this returns a clone of
+        // DEFAULT_PREFERENCES, which now carries the `memoryPreflight`
+        // block (see preferences-types.ts). Partial overlays fall through
+        // to mergePreferences below, where the new `memoryPreflight` block
+        // shallow-replaces the default block — `mergePreferences` does not
+        // deep-merge `memoryPreflight` (only `fanout` is deep-merged), so a
+        // partial overlay will replace the whole block. Resolution still
+        // works because `resolveMemoryPreflightConfig` applies field-level
+        // defaults over the partial input (see memory-preflight-config.ts).
+        return structuredClone(DEFAULT_PREFERENCES);
+    }
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(filePath, 'utf8'));
+    }
+    catch (err) {
+        throw new Error(`PREFERENCES_JSON_INVALID: failed to parse ${filePath}: ${err.message}`);
+    }
+    if (typeof raw !== 'object' ||
+        raw === null ||
+        raw.schema_version !== PREFERENCES_SCHEMA_VERSION) {
+        throw new Error(`PREFERENCES_SCHEMA_MISMATCH: expected schema_version=${PREFERENCES_SCHEMA_VERSION} in ${filePath}, got ${raw?.schema_version}`);
+    }
+    // Slice 2026-06-24-audit-5th-p2: fail fast on any fanout mode value
+    // outside the closed set `['fan-out']`. The previous 'serial' opt-out
+    // was removed by user direction — a saved `defaultMode = 'serial'`
+    // (or a hand-edited unknown value) now throws at load rather than
+    // being silently coerced, so callers see the break loudly and can
+    // remove the block from preferences.json. Migration of legacy v2
+    // preferences.json files with `fanout = {defaultMode: 'serial'}` is
+    // handled by `migratePreferences` further down — that path rewrites
+    // to `defaultMode: 'fan-out'` before `loadPreferences` re-reads.
+    const rawObj = raw;
+    if (typeof rawObj.fanout === 'object' &&
+        rawObj.fanout !== null &&
+        !Array.isArray(rawObj.fanout)) {
+        const fanoutObj = rawObj.fanout;
+        if ('defaultMode' in fanoutObj && !isFanoutMode(fanoutObj.defaultMode)) {
+            const known = FANOUT_MODES.join(' | ');
+            throw new Error(`PREFERENCES_FANOUT_INVALID: fanout.defaultMode must be one of ${known} (got ${JSON.stringify(fanoutObj.defaultMode)}) in ${filePath}. The 'serial' opt-out was removed in 2.8.4 — remove the fanout block to use the fan-out default.`);
+        }
+    }
+    return mergePreferences(DEFAULT_PREFERENCES, raw);
+}
+export function savePreferences(projectRoot, overrides) {
+    const filePath = preferencesPath(projectRoot);
+    const current = loadPreferences(projectRoot);
+    const merged = mergePreferences(current, overrides);
+    // Slice 2026-06-23-audit-4th #A2: use tmp + rename so a crash
+    // mid-write cannot leave a zero-byte or half-written preferences
+    // file. Before the fix, a power-cut or OOM-kill between
+    // writeFileSync's open and the final byte would leave
+    // .peaks/preferences.json unreadable, and the next loadPreferences
+    // would throw PREFERENCES_JSON_INVALID with no recovery path.
+    // The tmp+rename pattern matches dispatch-record-writer.ts:409-420
+    // and shared-channel.ts:336-349.
+    writeAtomic(filePath, merged);
+    return merged;
+}
+/**
+ * Atomic write helper for preferences.json. Writes to `<path>.tmp-<pid>-<ts>`
+ * and renames over the target. On Windows, `rename` is atomic for files
+ * on the same volume; on POSIX, `rename(2)` is atomic by spec.
+ */
+export function writeAtomic(filePath, prefs) {
+    const dir = dirname(filePath);
+    mkdirSync(dir, { recursive: true });
+    const tmp = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+    writeFileSync(tmp, JSON.stringify(prefs, null, 2) + '\n', 'utf8');
+    renameSync(tmp, filePath);
+}
+function mergePreferences(base, overrides) {
+    const definedEntries = Object.entries(overrides).filter(([, value]) => value !== undefined);
+    // Shallow merge at the top level, BUT merge the `fanout` object
+    // deeply so a partial override like `{"fanout": {"perTouchpoint": {...}}}`
+    // does not silently drop `defaultMode`. Slice
+    // 2026-06-23-audit-p0-cleanup: today the fanout schema is 1 level
+    // deep, so shallow merge happens to be safe — but the field is
+    // likely to grow (perTouchpoint / perRole are obvious next additions),
+    // and a future bug fix should not silently regress opt-out callers
+    // that already specified `defaultMode` in their preferences.json.
+    const shallow = {
+        ...base,
+        ...Object.fromEntries(definedEntries),
+    };
+    const overrideFanout = overrides.fanout;
+    if (overrideFanout !== undefined &&
+        typeof overrideFanout === 'object' &&
+        overrideFanout !== null &&
+        !Array.isArray(overrideFanout)) {
+        shallow.fanout = {
+            ...base.fanout,
+            ...overrideFanout
+        };
+    }
+    return {
+        ...shallow,
+        schema_version: PREFERENCES_SCHEMA_VERSION,
+    };
+}
+export function migratePreferences(projectRoot, opts = {}) {
+    const filePath = preferencesPath(projectRoot);
+    if (!existsSync(filePath)) {
+        return null;
+    }
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(filePath, 'utf8'));
+    }
+    catch (err) {
+        throw new Error(`PREFERENCES_JSON_INVALID: failed to parse ${filePath}: ${err.message}`);
+    }
+    const fromVersion = typeof raw.schema_version === 'string'
+        ? raw.schema_version
+        : 'unknown';
+    if (fromVersion === PREFERENCES_SCHEMA_VERSION) {
+        return {
+            fromVersion,
+            toVersion: PREFERENCES_SCHEMA_VERSION,
+            migrated: mergePreferences(DEFAULT_PREFERENCES, raw),
+            changes: [],
+            written: false
+        };
+    }
+    const changes = [];
+    // v1 → v2: headroom.perTouchpoint fill-in (v1 only had defaultMode).
+    const headroomRaw = (raw.headroom ?? {});
+    const defaultMode = isHeadroomModeString(headroomRaw.defaultMode)
+        ? headroomRaw.defaultMode
+        : 'balanced';
+    const perTouchpoint = {
+        subAgentDispatch: defaultMode,
+        memorySearch: defaultMode,
+        retrospectiveSearch: defaultMode,
+        doctorScan: defaultMode,
+        doctorRoute: 'conservative'
+    };
+    changes.push(`headroom.perTouchpoint filled in with defaultMode='${defaultMode}' (v1 lacked per-touchpoint overrides)`);
+    if (typeof headroomRaw.compressMinBytes === 'number') {
+        changes.push(`headroom.compressMinBytes preserved at ${headroomRaw.compressMinBytes}`);
+    }
+    else {
+        changes.push(`headroom.compressMinBytes defaulted to 4096`);
+    }
+    // v1 → v2: fanout block was absent; v2 needs it. Default to the
+    // pre-v2 behavior (fan-out when ≥ 2 leaves).
+    if (raw.fanout === undefined) {
+        changes.push(`fanout.defaultMode set to 'fan-out' (matches pre-v2 default behavior)`);
+    }
+    else if (typeof raw.fanout === 'object' &&
+        raw.fanout !== null &&
+        !Array.isArray(raw.fanout) &&
+        raw.fanout.defaultMode === 'serial') {
+        // Slice 2026-06-24-audit-5th-p2: 2.8.3-era preferences.json files
+        // that opted into serial dispatch must be migrated to fan-out on
+        // load. The user's directive ("禁止单 sub-agent") makes the serial
+        // opt-out a breaking change for any project that used it.
+        changes.push(`fanout.defaultMode rewrote 'serial' → 'fan-out' (the 'serial' opt-out was removed in 2.8.4; single-sub-agent dispatch is no longer permitted when DAG has >= 2 leaves)`);
+    }
+    else {
+        changes.push(`fanout block preserved from v1`);
+    }
+    // Apply the migration through mergePreferences so the result is a
+    // fully-valid v2 ProjectPreferences.
+    const migrated = mergePreferences(DEFAULT_PREFERENCES, {
+        ...raw,
+        headroom: {
+            enabled: typeof headroomRaw.enabled === 'boolean' ? headroomRaw.enabled : true,
+            defaultMode,
+            perTouchpoint,
+            compressMinBytes: typeof headroomRaw.compressMinBytes === 'number'
+                ? headroomRaw.compressMinBytes
+                : 4096
+        },
+        fanout: typeof raw.fanout === 'object' && raw.fanout !== null && !Array.isArray(raw.fanout)
+            ? (raw.fanout.defaultMode === 'serial'
+                ? { defaultMode: 'fan-out' }
+                : raw.fanout)
+            : { defaultMode: 'fan-out' }
+    });
+    let written = false;
+    if (opts.write === true) {
+        writeAtomic(filePath, migrated);
+        written = true;
+    }
+    return {
+        fromVersion,
+        toVersion: PREFERENCES_SCHEMA_VERSION,
+        migrated,
+        changes,
+        written
+    };
+}
+function isHeadroomModeString(value) {
+    return value === 'balanced' || value === 'aggressive' || value === 'conservative';
+}

package/dist/services/preferences/preferences-types.d.ts

@@ -0,0 +1,161 @@
+/**
+ * peaks-loop 2.0 project-local preferences schema.
+ * Per spec §8.4 — per-project state lives in `.peaks/preferences.json`,
+ * NOT in `~/.peaks/config.json` (which is slim global).
+ *
+ * Spec reference: docs/superpowers/specs/2026-06-11-peaks-loop-l1-l2-l3-redesign.md §8.4
+ */
+export declare const PREFERENCES_SCHEMA_VERSION = "2.0.0";
+/**
+ * Per-task-level UA install UX prompt decision.
+ * Values:
+ *   - 'unset'              — ask every session (default)
+ *   - 'skip-this-session'  — skip prompt for current session only
+ *   - 'skip-forever'       — never ask, never install
+ */
+export type UaPromptDecision = 'unset' | 'skip-this-session' | 'skip-forever';
+/**
+ * L1a task classification conservatism.
+ * Values:
+ *   - 'default'  — use default signal thresholds
+ *   - 'strict'   — always upgrade to next level (slower, safer)
+ *   - 'lax'      — always downgrade to previous level (faster, riskier)
+ */
+export type ClassifyConservatism = 'default' | 'strict' | 'lax';
+/**
+ * Per-touchpoint headroom-AI mode override.
+ * Spec §7.4 — default 'balanced'.
+ */
+export type HeadroomMode = 'balanced' | 'aggressive' | 'conservative';
+export interface HeadroomPreferences {
+    /** Whether headroom integration is enabled globally. Default: true */
+    readonly enabled: boolean;
+    /** Default mode if a touchpoint doesn't override. Default: 'balanced' */
+    readonly defaultMode: HeadroomMode;
+    /** Per-touchpoint mode overrides */
+    readonly perTouchpoint: {
+        subAgentDispatch: HeadroomMode;
+        memorySearch: HeadroomMode;
+        retrospectiveSearch: HeadroomMode;
+        doctorScan: HeadroomMode;
+        doctorRoute: HeadroomMode;
+    };
+    /** Minimum joined-result byte count before search-touchpoint compression runs. Default: 4096. */
+    readonly compressMinBytes: number;
+}
+export interface ClassifyRuleOverrides {
+    /** File count threshold above which a task is promoted to 'feature' */
+    readonly feature_threshold_files?: number;
+    /** Line count threshold above which a task is promoted to 'feature' */
+    readonly feature_threshold_lines?: number;
+    /** Whether to require a 24h grace before cleaning recently-active sessions */
+    readonly runtime_clean_grace_hours?: number;
+}
+export interface SwarmSpeculativePreferences {
+    /** Whether speculative dispatch is enabled. Default: true */
+    readonly enabled: boolean;
+    /** Max concurrent speculative sub-agents. Default: 3 (slice 2026-06-24-efficiency-4p-bundle, G3/P1.1) */
+    readonly maxConcurrent: number;
+    /** Min hit rate below which speculative auto-disables. Default: 0.5 */
+    readonly minHitRate: number;
+}
+export interface ProjectPreferences {
+    /**
+     * On-disk schema version. The JSON key is `schema_version` (snake_case) — this matches the
+     * raw on-disk key in `.peaks/preferences.json`, NOT the camelCase used by the rest of this
+     * interface. preferences-service.ts validates this value against PREFERENCES_SCHEMA_VERSION
+     * on load and writes the current value on save. Any mismatch throws PREFERENCES_SCHEMA_MISMATCH.
+     */
+    readonly schema_version: typeof PREFERENCES_SCHEMA_VERSION;
+    /**
+     * Slice 2026-06-28-code-mode-bypass-fix: economyMode is a
+     * **MODEL-SELECTION** knob only — it chooses between the cheap
+     * configured provider (`getConfiguredExecutionModelId`) and the
+     * strongest planner/reviewer model (`getStrongestModelId(...)`). It does
+     * NOT throttle concurrency, fan-out, or worker count. Per user
+     * direction 2026-06-28: "效率比省钱更重要，是在效率达到最大值的时
+     * 候，再去考虑经济问题" (efficiency first; economy is only considered
+     * after efficiency is maxed out).
+     *
+     * Concurrency is governed by:
+     *   - `swarmMode` (project-policy opt-out for the swarm subgraph),
+     *   - `fanout.defaultMode` (HARD constraint: `'fan-out'` per slice
+     *     2026-06-24-audit-5th-p2),
+     *   - the slice DAG leaf count (≥ 2 leaves at one topological level
+     *     forces parallel dispatch via `peaks sub-agent dispatch --from-dag`).
+     *
+     * Even with `economyMode: true` AND `swarmMode: false`, a 2-leaf DAG
+     * MUST dispatch in parallel — the `fanout-mandatory` rule is
+     * unconditional. Economy ≠ concurrency.
+     */
+    readonly economyMode: boolean;
+    /**
+     * Slice 2026-06-28: swarmMode controls whether the swarm subgraph
+     * (peaks-rd/qa worker graph) is generated at all. It does NOT
+     * control fan-out. Fan-out is governed by the slice DAG + the
+     * `fanout.defaultMode` preference; swarmMode only decides the
+     * dispatch *shape* (worker graph vs flat dispatch).
+     */
+    readonly swarmMode: boolean;
+    readonly uaPrompt: UaPromptDecision;
+    readonly agentShieldPrompt: UaPromptDecision;
+    readonly classifyConservatism: ClassifyConservatism;
+    readonly classifyRules: ClassifyRuleOverrides;
+    readonly headroom: HeadroomPreferences;
+    readonly swarmSpeculative: SwarmSpeculativePreferences;
+    /** Loop Autonomous (L4 14.5) toggle. Default: false — never auto-enable. */
+    readonly loopAutonomousEnabled: boolean;
+    /**
+     * L2.3 P2-a: ECC AgentShield subprocess toggle. Default: false.
+     *
+     * When true, `peaks audit static` spawns `npx ecc-agentshield scan --json`
+     * and merges its findings into the audit report. When false (default),
+     * the audit runs peaks-loop-only and the subprocess is never spawned.
+     *
+     * The preference is independent of whether ECC is installed — i.e.
+     * `agentShieldEnabled: true` with ECC missing surfaces a soft
+     * "ECC not installed" warning and the audit still completes.
+     */
+    readonly agentShieldEnabled: boolean;
+    /**
+     * Slice 2026-06-24-audit-5th-p2: fan-out is now a HARD constraint.
+     * The previous opt-out (`defaultMode = 'serial'`) is removed by user
+     * direction. Single-sub-agent dispatch is no longer permitted when
+     * the slice DAG has ≥ 2 leaves at the same topological level; the
+     * LLM-side runner MUST use `peaks sub-agent dispatch --from-dag`
+     * (N parallel `buildToolCall` per dispatch).
+     *
+     * The field is kept on `ProjectPreferences` for backward-compatible
+     * load (legacy preferences.json files still parse) but the runtime
+     * shape is fixed: `defaultMode === 'fan-out'`. Any other value in a
+     * saved file is rejected at load time.
+     */
+    readonly fanout: FanoutPreference;
+    /**
+     * Slice 2026-07-22-orchestrator-memory-preflight: orchestrator-side memory
+     * preflight knobs. Optional — `resolveMemoryPreflightConfig` (see
+     * src/services/context/memory-preflight-config.ts) merges over a hard-coded
+     * default block when this key is absent, so legacy preferences.json files
+     * keep working unchanged.
+     */
+    readonly memoryPreflight?: {
+        readonly enabled?: boolean;
+        readonly maxTokens?: number;
+        readonly listCap?: number;
+        readonly contentCacheBytes?: number;
+    };
+}
+export type FanoutMode = 'fan-out';
+export declare const FANOUT_MODES: readonly FanoutMode[];
+/**
+ * Runtime type guard for `FanoutMode`. Slice 2026-06-24-audit-5th-p2
+ * narrowed the closed set from `['fan-out','serial']` to `['fan-out']`
+ * — stale preferences.json files with `"serial"` must now fail-fast at
+ * load (see `preferences-service.ts`) instead of being silently coerced.
+ */
+export declare function isFanoutMode(value: unknown): value is FanoutMode;
+export interface FanoutPreference {
+    /** Hard-coded mode. Slice 2026-06-24-audit-5th-p2 removed the serial opt-out. */
+    readonly defaultMode: FanoutMode;
+}
+export declare const DEFAULT_PREFERENCES: ProjectPreferences;

package/dist/services/preferences/preferences-types.js

@@ -0,0 +1,64 @@
+/**
+ * peaks-loop 2.0 project-local preferences schema.
+ * Per spec §8.4 — per-project state lives in `.peaks/preferences.json`,
+ * NOT in `~/.peaks/config.json` (which is slim global).
+ *
+ * Spec reference: docs/superpowers/specs/2026-06-11-peaks-loop-l1-l2-l3-redesign.md §8.4
+ */
+export const PREFERENCES_SCHEMA_VERSION = '2.0.0';
+export const FANOUT_MODES = ['fan-out'];
+/**
+ * Runtime type guard for `FanoutMode`. Slice 2026-06-24-audit-5th-p2
+ * narrowed the closed set from `['fan-out','serial']` to `['fan-out']`
+ * — stale preferences.json files with `"serial"` must now fail-fast at
+ * load (see `preferences-service.ts`) instead of being silently coerced.
+ */
+export function isFanoutMode(value) {
+    return typeof value === 'string' && FANOUT_MODES.includes(value);
+}
+export const DEFAULT_PREFERENCES = {
+    schema_version: PREFERENCES_SCHEMA_VERSION,
+    economyMode: true,
+    swarmMode: true,
+    uaPrompt: 'unset',
+    agentShieldPrompt: 'unset',
+    classifyConservatism: 'default',
+    classifyRules: {
+        feature_threshold_files: 10,
+        feature_threshold_lines: 100,
+        runtime_clean_grace_hours: 24,
+    },
+    headroom: {
+        enabled: true,
+        defaultMode: 'balanced',
+        perTouchpoint: {
+            subAgentDispatch: 'balanced',
+            memorySearch: 'balanced',
+            retrospectiveSearch: 'balanced',
+            doctorScan: 'balanced',
+            doctorRoute: 'conservative',
+        },
+        compressMinBytes: 4096,
+    },
+    swarmSpeculative: {
+        enabled: true,
+        maxConcurrent: 3,
+        minHitRate: 0.5,
+    },
+    loopAutonomousEnabled: false,
+    agentShieldEnabled: false,
+    fanout: {
+        defaultMode: 'fan-out'
+    },
+    // Slice 2026-07-22-orchestrator-memory-preflight: defaults aligned with
+    // memory-preflight-config.ts::DEFAULTS. Kept in sync manually because
+    // loadPreferences() returns DEFAULT_PREFERENCES verbatim when the on-disk
+    // file is absent, and partial overlays rely on memoryPreflight being
+    // defined here.
+    memoryPreflight: {
+        enabled: true,
+        maxTokens: 1200,
+        listCap: 12,
+        contentCacheBytes: 6000,
+    },
+};

package/dist/services/profiles/profile-service.d.ts

@@ -0,0 +1,6 @@
+export type Profile = {
+    name: string;
+    description: string;
+    capabilities: string[];
+};
+export declare function listProfiles(): Profile[];

package/dist/services/profiles/profile-service.js

@@ -0,0 +1,19 @@
+export function listProfiles() {
+    return [
+        {
+            name: 'refactor-guard',
+            description: 'Soft gate profile for refactor coverage, slice spec, artifact retention, and commit boundaries.',
+            capabilities: ['refactor-coverage-gate', 'refactor-slice-spec', 'artifact-retention']
+        },
+        {
+            name: 'strict-refactor',
+            description: 'Strict profile that can enable CLI-managed hooks, agents, and artifact repository checks after approval.',
+            capabilities: ['refactor-guard', 'hook-profile', 'artifact-repository', 'doctor']
+        },
+        {
+            name: 'refactor-swarm',
+            description: 'Optional swarm orchestration profile for large multi-module refactors.',
+            capabilities: ['agent-profile', 'swarm-task-graph', 'handoff-reports']
+        }
+    ];
+}

package/dist/services/progress/progress-service.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Sub-agent progress file for the RD/QA sub-agents in `peaks-code`'s
+ * Swarm phase. A sub-agent (or the LLM via the `peaks progress step`
+ * CLI) writes a stable JSON file at
+ * `.peaks/_sub_agents/<sid>/subagent-progress.json`. The dispatch +
+ * heartbeat flow (slice #009 + #010) reads this file as the source
+ * of truth for "is this sub-agent still alive?".
+ *
+ * Token cost design (the binding constraint of this feature):
+ *   - The LLM side (step CLI) writes the file at most once per
+ *     phase transition. That is approximately one Bash call per
+ *     RD/QA sub-step. In a typical 5-step sub-agent slice the
+ *     cost is < 10 output tokens.
+ *   - The dispatch side polls the file via `peaks sub-agent
+ *     heartbeat`, not the LLM. Zero token cost.
+ *
+ * Slice #014: the legacy `peaks progress start|watch|close` auto-spawn
+ * surface is DELETED. With dispatch + heartbeat (slice #009 + #010), the
+ * same sub-agent now runs in the same IDE/terminal as the main loop, so
+ * a separate watch window is dead weight. The only remaining consumer
+ * of this module is the `peaks progress step` write path + the
+ * dispatcher's read-back of the progress file.
+ *
+ * This module is pure filesystem. It does NOT import the LLM
+ * harness, does NOT spawn terminals, and does NOT talk to any
+ * IPC. The dispatch-side consumption is in
+ * `src/services/dispatch/sub-agent-dispatcher.ts` and reads the
+ * progress file via `subAgentProgressPath`.
+ */
+export type SubAgentProgressPhase = 'starting' | 'running' | 'verifying' | 'completing' | 'finished' | 'failed' | 'idle';
+export type SubAgentProgressStep = {
+    /** ISO-8601 timestamp at which the sub-agent started. */
+    startedAt: string;
+    /** ISO-8601 timestamp at which the sub-agent finished (or now, if still running). */
+    updatedAt: string;
+    /** Free-form human-readable sub-step label, e.g. "running test/ut". */
+    step: string;
+    /** Current phase bucket. `idle` is the pre-start sentinel. */
+    phase: SubAgentProgressPhase;
+    /** When set, the sub-agent is finished and reports the verdict here. */
+    verdict?: 'pass' | 'return-to-rd' | 'blocked';
+    /** Optional count of in-scope files touched, assertions run, etc. */
+    counts?: {
+        filesTouched?: number;
+        testsRun?: number;
+    };
+};
+export type SubAgentProgress = {
+    version: 1;
+    sessionId: string;
+    outerSessionId?: string;
+    /** Outer-agent role that owns the slice (e.g. "rd", "qa"). */
+    role: string;
+    /** Per-slice identifier. */
+    requestId: string;
+    /** When the sub-agent entered the first non-idle state. */
+    startedAt: string;
+    /** When the sub-agent last touched the file. */
+    updatedAt: string;
+    /** Current step. */
+    current: SubAgentProgressStep;
+    /**
+     * History of completed steps. Length is unbounded; the watch
+     * tool renders the most recent N. Kept for after-the-fact
+     * forensics ("how long did step 3 take?").
+     */
+    history: SubAgentProgressStep[];
+};
+export type ReadProgressOptions = {
+    projectRoot: string;
+};
+export type ReadProgressResult = {
+    ok: true;
+    data: SubAgentProgress;
+    path: string;
+} | {
+    ok: false;
+    reason: 'no-binding' | 'no-progress-file' | 'invalid-json';
+};
+export type WriteProgressOptions = {
+    projectRoot: string;
+    requestId: string;
+    role: string;
+    step: string;
+    phase: SubAgentProgressPhase;
+    verdict?: 'pass' | 'return-to-rd' | 'blocked';
+    counts?: SubAgentProgressStep['counts'];
+    outerSessionId?: string;
+};
+/**
+ * Read the current progress file. Returns a tagged result so
+ * the CLI can map each failure mode to a distinct nextActions
+ * hint (no-binding → run peaks workspace init; no-progress-file
+ * → sub-agent has not started yet; invalid-json → the LLM wrote
+ * garbage; recover by writing a fresh file).
+ */
+export declare function readSubAgentProgress(options: ReadProgressOptions): ReadProgressResult;
+/**
+ * Append-or-replace the current step. Idempotent on identical
+ * (step, phase) — the file is rewritten with the same payload
+ * (no new history entry) so heartbeats from the same phase do
+ * not pollute the history. Phase transitions append a new step
+ * to the history and replace `current`.
+ */
+export declare function writeSubAgentProgress(options: WriteProgressOptions): SubAgentProgress;
+/**
+ * Resolve the project root for a CLI invocation: --project
+ * override wins, otherwise the canonical git-root promotion
+ * (so the sub-agent's writes land in the same `.peaks/_runtime/<sid>/`
+ * the user's manual CLI would use). Re-exports the same
+ * helper peaks workspace init / session rotate already use
+ * for symmetry.
+ */
+export declare function resolveProgressProjectRoot(override: string | undefined, cwd: string): string;
+/**
+ * Compute the absolute path to the progress file for a given
+ * project root, for callers that need to display / fs.watch it
+ * (the dispatcher's read-back, the LLM-side step write banner,
+ * etc.). This MUST agree with `progressPath` — the read/write
+ * helpers resolve through `progressPath` and use the session
+ * sub-directory, so the displayed path does too. Without this
+ * agreement the dispatcher's read-back would point at a path
+ * the writer never touches.
+ */
+export declare function subAgentProgressPath(projectRoot: string): string;