peaks-loop 4.0.0-beta.8 → 4.0.0-beta.9

package/dist/services/impact/impact-scan-service.js

@@ -0,0 +1,197 @@
+/**
+ * v2.15.0 follow-up — G13: impact scan service.
+ *
+ * Lightweight, file-glob-based impact analysis (no AST, no type
+ * checking). For a given set of changed files, predict:
+ *   - which other files are likely affected (by path convention)
+ *   - which business flows touch them (config-driven)
+ *   - the risk level (high / medium / low)
+ *   - the "must-check" list (concrete business scenarios the user
+ *     must verify before shipping)
+ *
+ * Pure functions. The CLI wraps this with a `peaks impact scan`
+ * command; `peaks impact must-check` returns the must-check list
+ * subset. Persistence is per-invocation (no state file).
+ */
+/**
+ * Default business flow map (covers the most common B-end
+ * archetypes; users can override via --flows in the CLI).
+ */
+export const DEFAULT_BUSINESS_FLOWS = new Map([
+    ['用户管理', ['**/user/**', '**/users/**', '**/account/**']],
+    ['权限校验', ['**/auth/**', '**/permission/**', '**/rbac/**', '**/role/**']],
+    ['登录流程', ['**/login/**', '**/signin/**', '**/auth/**']],
+    ['订单/交易', ['**/order/**', '**/payment/**', '**/transaction/**', '**/checkout/**']],
+    ['Skill 权限', ['**/skill/**', '**/plugin/**']],
+    ['数据列表', ['**/list/**', '**/table/**', '**/grid/**']],
+    ['API 网关', ['**/api/**', '**/gateway/**', '**/routes/**']],
+    ['数据库 schema', ['**/schema/**', '**/migrations/**', '**/prisma/**', '**/drizzle/**']],
+    ['前端 UI 组件', ['**/components/**', '**/pages/**', '**/views/**']],
+    ['后端服务', ['**/services/**', '**/server/**', '**/controllers/**']]
+]);
+/**
+ * Convert a file path to a glob-friendly pattern. Returns 3 levels
+ * (the file itself, the parent dir, the project-wide pattern).
+ */
+function pathToGlobs(path) {
+    const normalized = path.replace(/\\/g, '/');
+    const parts = normalized.split('/');
+    // Drop the filename → get the parent pattern: "src/foo/" → "src/**"
+    const parent = parts.length > 1 ? parts.slice(0, -1).join('/') + '/**' : '**';
+    return [normalized, parent, `**/${parts[parts.length - 1]}`];
+}
+/** Simple glob matcher supporting `**` and `*`. */
+export function matchGlob(pattern, path) {
+    const normalizedPath = path.replace(/\\/g, '/');
+    // Build regex by splitting on glob tokens, escaping the rest.
+    // Order: ** (doublestar) → .* ; * → [^/]* ; other → escape
+    let regexStr = '';
+    let i = 0;
+    while (i < pattern.length) {
+        if (pattern[i] === '*' && pattern[i + 1] === '*') {
+            // ** may be followed by a slash — consume `**/` or just `**`
+            regexStr += '.*';
+            i += 2;
+            if (pattern[i] === '/')
+                i++;
+        }
+        else if (pattern[i] === '*') {
+            regexStr += '[^/]*';
+            i++;
+        }
+        else {
+            // Escape regex special char
+            regexStr += pattern[i].replace(/[.+^${}()|[\]\\]/g, '\\$&');
+            i++;
+        }
+    }
+    const re = new RegExp('^' + regexStr + '$');
+    return re.test(normalizedPath);
+}
+/** Risk of a single file based on its path patterns. */
+function fileRisk(path) {
+    if (matchGlob('**/auth/**', path) || matchGlob('**/permission/**', path) ||
+        matchGlob('**/rbac/**', path) || matchGlob('**/schema/**', path) ||
+        matchGlob('**/migrations/**', path) || matchGlob('**/prisma/**', path)) {
+        return 'high';
+    }
+    if (matchGlob('**/services/**', path) || matchGlob('**/api/**', path) ||
+        matchGlob('**/components/**', path)) {
+        return 'medium';
+    }
+    return 'low';
+}
+/**
+ * Run an impact scan. Pure function — no I/O.
+ */
+export function runImpactScan(opts) {
+    const flows = opts.businessFlows ?? DEFAULT_BUSINESS_FLOWS;
+    const changed = opts.changedFiles;
+    const warnings = [];
+    if (changed.length === 0) {
+        warnings.push('No changed files provided. Pass --files a.ts,b.ts to scan.');
+    }
+    // Build set of globs from changed files.
+    const changedGlobs = new Set();
+    for (const f of changed) {
+        for (const g of pathToGlobs(f))
+            changedGlobs.add(g);
+    }
+    // For each business flow, check if any changed file matches.
+    const affectedFlows = [];
+    for (const [name, patterns] of flows) {
+        const matches = changed.filter((f) => patterns.some((p) => matchGlob(p, f)));
+        if (matches.length > 0) {
+            affectedFlows.push({ name, reason: `changes touch ${matches.length} file(s) in this flow: ${matches.slice(0, 3).join(', ')}` });
+        }
+    }
+    // Predict other files that may be affected (siblings of changed files).
+    const impactedFiles = [];
+    for (const f of changed) {
+        const parts = f.replace(/\\/g, '/').split('/');
+        if (parts.length <= 1)
+            continue;
+        const parent = parts.slice(0, -1).join('/');
+        impactedFiles.push({
+            path: `${parent}/index.{ts,tsx,js,jsx}`,
+            reason: `sibling of changed file ${f}`,
+            risk: fileRisk(`${parent}/index.ts`)
+        });
+    }
+    // Deduplicate impacted files.
+    const seen = new Set();
+    const dedupedImpacted = impactedFiles.filter((f) => {
+        if (seen.has(f.path))
+            return false;
+        seen.add(f.path);
+        return true;
+    });
+    // Build must-check list.
+    const mustCheck = [];
+    for (const flow of affectedFlows) {
+        if (flow.name === '权限校验' || flow.name === '用户管理' || flow.name === '数据库 schema') {
+            mustCheck.push({
+                scenario: `回归测试: ${flow.name} 主流程跑通,边界 case(无权限/越权/迁移)不报错`,
+                category: 'business',
+                priority: 'P0'
+            });
+        }
+        if (flow.name === '登录流程') {
+            mustCheck.push({
+                scenario: '登录 / 登出 / 续签 / 失败提示 4 个流程手工跑一遍',
+                category: 'integration',
+                priority: 'P0'
+            });
+        }
+        if (flow.name === '前端 UI 组件' || flow.name === '数据列表') {
+            mustCheck.push({
+                scenario: `改动的 UI 页面在 3 种浏览器(Chrome / Edge / Safari)渲染正常,无白屏 / 错位 / 性能退化`,
+                category: 'ui',
+                priority: 'P1'
+            });
+        }
+        if (flow.name === 'API 网关' || flow.name === '后端服务') {
+            mustCheck.push({
+                scenario: `改动接口的 happy path + 3 个异常 case(超时/限流/鉴权失败)返回正确的 status code`,
+                category: 'integration',
+                priority: 'P0'
+            });
+        }
+    }
+    // Deduplicate by scenario.
+    const seenScenarios = new Set();
+    const dedupedMustCheck = mustCheck.filter((m) => {
+        if (seenScenarios.has(m.scenario))
+            return false;
+        seenScenarios.add(m.scenario);
+        return true;
+    });
+    // Overall risk = highest individual risk.
+    let overallRisk = 'low';
+    for (const f of dedupedImpacted) {
+        if (f.risk === 'high') {
+            overallRisk = 'high';
+            break;
+        }
+        if (f.risk === 'medium')
+            overallRisk = 'medium';
+    }
+    if (affectedFlows.length > 3)
+        overallRisk = 'high';
+    if (changed.length > 20)
+        overallRisk = 'high';
+    return {
+        changedFiles: changed,
+        impactedFiles: dedupedImpacted,
+        affectedFlows,
+        mustCheck: dedupedMustCheck,
+        overallRisk,
+        warnings
+    };
+}
+/**
+ * Extract just the must-check list from a scan report.
+ */
+export function mustCheckFromReport(report) {
+    return report.mustCheck;
+}

package/dist/services/job/job-event-emitter.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Stub Job event emitter. Logs to stderr so Job lifecycle is visible during CLI runs.
+ * M7.5 batch-fix task will wire to a real statusline event bus if/when the project
+ * adds one. Until then, this is the only Job-event surface.
+ */
+export type JobEvent = {
+    kind: 'job-started';
+    jobId: string;
+    total: number;
+    strategy: 'single' | 'rotating';
+} | {
+    kind: 'job-progress';
+    jobId: string;
+    done: number;
+    total: number;
+    currentSlice?: string;
+} | {
+    kind: 'job-blocked';
+    jobId: string;
+    sliceId: string;
+    reason: string;
+} | {
+    kind: 'job-completed';
+    jobId: string;
+    done: number;
+    failed: number;
+    blocked: number;
+    skipped: number;
+};
+export declare function emitJobEvent(event: JobEvent): void;

package/dist/services/job/job-event-emitter.js

@@ -0,0 +1,5 @@
+export function emitJobEvent(event) {
+    // Write to stderr so it doesn't pollute the JSON-envelope stdout that the CLI emits.
+    // Prepend a tag so downstream tools can grep for it.
+    process.stderr.write(`[job-event] ${JSON.stringify(event)}\n`);
+}

package/dist/services/job/job-orchestrator.d.ts

@@ -0,0 +1,50 @@
+import { JobStateStore, type JobInitInput } from './job-state-store.js';
+import { type JobState, type JobStatusSummary } from './job-types.js';
+export interface CheckpointDoneInput {
+    jobId: string;
+    sliceId: string;
+    commitSha?: string;
+}
+export interface CheckpointSkipInput {
+    jobId: string;
+    sliceId: string;
+    reason: string;
+}
+export interface BlockInput {
+    jobId: string;
+    sliceId: string;
+    reason: string;
+}
+export declare class JobOrchestrator {
+    private readonly store;
+    constructor(store: JobStateStore);
+    init(input: JobInitInput): JobState;
+    /**
+     * Atomically apply a mutation to a job's state under a single-process lock.
+     *
+     * Uses the M2.1 single-process lock model (lock file checked with `existsSync`).
+     * State is loaded before lock acquisition, so `fn` receives a consistent snapshot;
+     * if `tryAcquireLock` throws because the job is already locked, `fn` is never called
+     * and the error bubbles to the caller. Concurrent `mutate` calls in the same process
+     * will collide, so callers MUST serialize externally or wrap calls in a higher-level
+     * mutex if multi-process support is added later.
+     *
+     * @param jobId - The job identifier whose state will be mutated.
+     * @param fn - Pure transform applied to the loaded state to produce the next state.
+     * @returns The new state after the mutation is persisted.
+     */
+    private mutate;
+    checkpointDone(input: CheckpointDoneInput): Promise<JobState>;
+    checkpointSkipped(input: CheckpointSkipInput): Promise<JobState>;
+    checkpointFailed(input: {
+        jobId: string;
+        sliceId: string;
+        reason: string;
+    }): Promise<JobState>;
+    blockSlice(input: BlockInput): Promise<JobState>;
+    status(jobId: string): JobStatusSummary;
+    continueNow(jobId: string): {
+        remaining: number;
+        next: string | undefined;
+    };
+}

package/dist/services/job/job-orchestrator.js

@@ -0,0 +1,104 @@
+export class JobOrchestrator {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    init(input) {
+        return this.store.init(input);
+    }
+    /**
+     * Atomically apply a mutation to a job's state under a single-process lock.
+     *
+     * Uses the M2.1 single-process lock model (lock file checked with `existsSync`).
+     * State is loaded before lock acquisition, so `fn` receives a consistent snapshot;
+     * if `tryAcquireLock` throws because the job is already locked, `fn` is never called
+     * and the error bubbles to the caller. Concurrent `mutate` calls in the same process
+     * will collide, so callers MUST serialize externally or wrap calls in a higher-level
+     * mutex if multi-process support is added later.
+     *
+     * @param jobId - The job identifier whose state will be mutated.
+     * @param fn - Pure transform applied to the loaded state to produce the next state.
+     * @returns The new state after the mutation is persisted.
+     */
+    mutate(jobId, fn) {
+        const state = this.store.load(jobId);
+        const lock = this.store.tryAcquireLock(jobId);
+        try {
+            const next = fn(state);
+            this.store.save(next);
+            return next;
+        }
+        finally {
+            this.store.releaseLock(lock);
+        }
+    }
+    async checkpointDone(input) {
+        return this.mutate(input.jobId, (s) => {
+            if (!input.commitSha || input.commitSha.length < 7) {
+                throw new Error('checkpointDone: commitSha required (≥7 hex)');
+            }
+            return {
+                ...s,
+                lastCheckpointAt: new Date().toISOString(),
+                slices: s.slices.map((sl) => sl.sliceId === input.sliceId
+                    ? { ...sl, status: 'done', commitSha: input.commitSha, finishedAt: new Date().toISOString() }
+                    : sl),
+            };
+        });
+    }
+    async checkpointSkipped(input) {
+        return this.mutate(input.jobId, (s) => ({
+            ...s,
+            lastCheckpointAt: new Date().toISOString(),
+            slices: s.slices.map((sl) => sl.sliceId === input.sliceId ? { ...sl, status: 'skipped' } : sl),
+        }));
+    }
+    async checkpointFailed(input) {
+        return this.mutate(input.jobId, (s) => ({
+            ...s,
+            lastCheckpointAt: new Date().toISOString(),
+            slices: s.slices.map((sl) => sl.sliceId === input.sliceId
+                ? { ...sl, status: 'failed', failureReason: input.reason, finishedAt: new Date().toISOString() }
+                : sl),
+        }));
+    }
+    async blockSlice(input) {
+        return this.mutate(input.jobId, (s) => ({
+            ...s,
+            lastCheckpointAt: new Date().toISOString(),
+            slices: s.slices.map((sl) => sl.sliceId === input.sliceId
+                ? { ...sl, status: 'blocked', blockedReason: input.reason, finishedAt: new Date().toISOString() }
+                : sl),
+        }));
+    }
+    status(jobId) {
+        const s = this.store.load(jobId);
+        const counts = { done: 0, failed: 0, blocked: 0, skipped: 0 };
+        for (const sl of s.slices) {
+            if (sl.status === 'done')
+                counts.done++;
+            else if (sl.status === 'failed')
+                counts.failed++;
+            else if (sl.status === 'blocked')
+                counts.blocked++;
+            else if (sl.status === 'skipped')
+                counts.skipped++;
+        }
+        const pendingIdx = s.slices.findIndex(sl => sl.status === 'pending' || sl.status === 'in-progress');
+        return {
+            total: s.slices.length,
+            done: counts.done,
+            failed: counts.failed,
+            blocked: counts.blocked,
+            skipped: counts.skipped,
+            currentSlice: pendingIdx >= 0 ? s.slices[pendingIdx].label : undefined,
+            lastCheckpoint: s.lastCheckpointAt,
+            mainLoopStrategy: s.mainLoopStrategy,
+            mainSessionCycle: s.mainSessionCycle,
+        };
+    }
+    continueNow(jobId) {
+        const summary = this.status(jobId);
+        return { remaining: summary.total - summary.done - summary.skipped - summary.blocked - summary.failed, next: summary.currentSlice };
+    }
+}

package/dist/services/job/job-progress-store.d.ts

@@ -0,0 +1,60 @@
+/**
+ * v3.1.2 — On-disk slice progress mirror.
+ *
+ * After each `peaks job checkpoint --state done`, the orchestrator writes
+ * `.peaks/_runtime/<sessionId>/job/<jid>/progress.json` so the next LLM
+ * turn (after compact or resume) can read it before any Bash call lands.
+ *
+ * Shape (schemaVersion 1):
+ *   {
+ *     jobId, done, total, currentSlice, lastCommitSha, updatedAt
+ *   }
+ *
+ * The `peaks code gate-step-08` hook reads this file in its case-1 path
+ * (job-shape.json says isJob=true) and surfaces `Next: slice #N+1 of M
+ * (<currentSlice>)` to stdout. The LLM cannot "wake up cold" — the
+ * next-slice context is mechanically injected on every Bash call.
+ *
+ * Karpathy §2 (Simplicity First): ~50 lines, single-purpose writer +
+ * reader. Schema is zod-validated on read so a stale on-disk copy
+ * from an earlier peaks-loop release fails loud (no silent fallback).
+ */
+import { z } from 'zod';
+export declare const JOB_PROGRESS_SCHEMA_VERSION: 1;
+export declare const JobProgressSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    jobId: z.ZodString;
+    done: z.ZodNumber;
+    total: z.ZodNumber;
+    currentSlice: z.ZodString;
+    lastCommitSha: z.ZodNullable<z.ZodString>;
+    updatedAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    updatedAt: string;
+    done: number;
+    schemaVersion: 1;
+    jobId: string;
+    total: number;
+    currentSlice: string;
+    lastCommitSha: string | null;
+}, {
+    updatedAt: string;
+    done: number;
+    schemaVersion: 1;
+    jobId: string;
+    total: number;
+    currentSlice: string;
+    lastCommitSha: string | null;
+}>;
+export type JobProgress = z.infer<typeof JobProgressSchema>;
+export interface WriteProgressInput {
+    readonly jobId: string;
+    readonly done: number;
+    readonly total: number;
+    readonly currentSlice: string;
+    readonly lastCommitSha: string | null;
+    readonly updatedAt?: string;
+}
+export declare function writeJobProgress(projectRoot: string, sessionId: string, input: WriteProgressInput): JobProgress;
+export declare function readJobProgress(projectRoot: string, sessionId: string, jobId: string): JobProgress;
+export declare function tryReadJobProgress(projectRoot: string, sessionId: string, jobId: string): JobProgress | null;

package/dist/services/job/job-progress-store.js

@@ -0,0 +1,70 @@
+/**
+ * v3.1.2 — On-disk slice progress mirror.
+ *
+ * After each `peaks job checkpoint --state done`, the orchestrator writes
+ * `.peaks/_runtime/<sessionId>/job/<jid>/progress.json` so the next LLM
+ * turn (after compact or resume) can read it before any Bash call lands.
+ *
+ * Shape (schemaVersion 1):
+ *   {
+ *     jobId, done, total, currentSlice, lastCommitSha, updatedAt
+ *   }
+ *
+ * The `peaks code gate-step-08` hook reads this file in its case-1 path
+ * (job-shape.json says isJob=true) and surfaces `Next: slice #N+1 of M
+ * (<currentSlice>)` to stdout. The LLM cannot "wake up cold" — the
+ * next-slice context is mechanically injected on every Bash call.
+ *
+ * Karpathy §2 (Simplicity First): ~50 lines, single-purpose writer +
+ * reader. Schema is zod-validated on read so a stale on-disk copy
+ * from an earlier peaks-loop release fails loud (no silent fallback).
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+export const JOB_PROGRESS_SCHEMA_VERSION = 1;
+export const JobProgressSchema = z.object({
+    schemaVersion: z.literal(JOB_PROGRESS_SCHEMA_VERSION),
+    jobId: z.string(),
+    done: z.number().int().nonnegative(),
+    total: z.number().int().positive(),
+    currentSlice: z.string(),
+    lastCommitSha: z.string().nullable(),
+    updatedAt: z.string().datetime()
+});
+export function writeJobProgress(projectRoot, sessionId, input) {
+    const dir = join(projectRoot, '.peaks', '_runtime', sessionId, 'job', input.jobId);
+    mkdirSync(dir, { recursive: true });
+    const record = {
+        schemaVersion: JOB_PROGRESS_SCHEMA_VERSION,
+        jobId: input.jobId,
+        done: input.done,
+        total: input.total,
+        currentSlice: input.currentSlice,
+        lastCommitSha: input.lastCommitSha,
+        updatedAt: input.updatedAt ?? new Date().toISOString()
+    };
+    const path = join(dir, 'progress.json');
+    writeFileSync(path, JSON.stringify(record, null, 2) + '\n', 'utf8');
+    return record;
+}
+export function readJobProgress(projectRoot, sessionId, jobId) {
+    const path = join(projectRoot, '.peaks', '_runtime', sessionId, 'job', jobId, 'progress.json');
+    if (!existsSync(path)) {
+        throw new Error(`JobProgressStore: no progress for ${jobId} at ${path}`);
+    }
+    const raw = readFileSync(path, 'utf8');
+    return JobProgressSchema.parse(JSON.parse(raw));
+}
+export function tryReadJobProgress(projectRoot, sessionId, jobId) {
+    const path = join(projectRoot, '.peaks', '_runtime', sessionId, 'job', jobId, 'progress.json');
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, 'utf8');
+        return JobProgressSchema.parse(JSON.parse(raw));
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+}

package/dist/services/job/job-resource-snapshot.d.ts

@@ -0,0 +1,7 @@
+import type { ResourceSnapshot } from './job-types.js';
+/**
+ * Collects a coarse-grained snapshot of host + project resources.
+ * Numeric ranges are clamped to zod's domain — out-of-range values are clamped, not thrown,
+ * so callers can decide what to do.
+ */
+export declare function collectResourceSnapshot(jobDir: string): ResourceSnapshot;

package/dist/services/job/job-resource-snapshot.js

@@ -0,0 +1,75 @@
+import os from 'node:os';
+import { readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Collects a coarse-grained snapshot of host + project resources.
+ * Numeric ranges are clamped to zod's domain — out-of-range values are clamped, not thrown,
+ * so callers can decide what to do.
+ */
+export function collectResourceSnapshot(jobDir) {
+    const cpus = os.cpus();
+    const loadAvg = (os.loadavg()[0] ?? 0) / (cpus.length || 1);
+    const cpuPercent = Math.max(0, Math.min(100, loadAvg * 100));
+    const totalMemMb = os.totalmem() / 1024 / 1024;
+    const freeMemMb = os.freemem() / 1024 / 1024;
+    const usedMemMb = Math.max(0, totalMemMb - freeMemMb);
+    const memMb = Math.round(usedMemMb);
+    const diskMb = dirSizeMb(jobDir);
+    // contextRatio is best-effort: pull from the same env-var the v2.13.0 auto-compact uses.
+    const envVal = process.env.CLAUDE_CONTEXT_USAGE_PERCENT;
+    const contextRatio = envVal ? Math.max(0, Math.min(1, Number(envVal) / 100)) : 0;
+    return {
+        capturedAt: new Date().toISOString(),
+        cpuPercent,
+        memMb,
+        diskMb,
+        contextRatio,
+    };
+}
+// Non-enumerable internal attachment for test-time access via
+// `collectResourceSnapshot.dirSizeMb`. NOT a public export — keeps
+// the prod module surface clean per PRD while still allowing
+// targeted AC-1/AC-2/AC-3 unit tests to drive `dirSizeMb` directly.
+Object.defineProperty(collectResourceSnapshot, 'dirSizeMb', {
+    value: dirSizeMb,
+    enumerable: false,
+    writable: false,
+    configurable: false,
+});
+/**
+ * Best-effort, non-recursive size of one directory level, in rounded megabytes.
+ *
+ * - Missing directory → 0.
+ * - Per-entry stat failures (race with deletion, EBUSY on Windows) → silently skipped.
+ * - When `opts.maxEntries` > 0 and the directory has more entries than the cap,
+ *   the returned value is a partial sum (a lower bound), and no further `stat`
+ *   calls are issued past the cap. Callers must treat the value as a lower bound.
+ * - `opts.maxEntries` defaults to 0 (unbounded, legacy behaviour).
+ *
+ * NOTE: when maxEntries > 0 and the directory contains more entries than the
+ * cap, this is a partial sum. Callers must treat the value as a lower bound.
+ */
+function dirSizeMb(dir, opts) {
+    const cap = opts?.maxEntries ?? 0;
+    let total = 0;
+    let index = 0;
+    try {
+        for (const name of readdirSync(dir)) {
+            if (cap > 0 && index >= cap)
+                break;
+            try {
+                total += statSync(join(dir, name)).size;
+            }
+            catch (e) {
+                // best-effort: missing entries (race with deletion) are silently skipped
+                void e;
+            }
+            index++;
+        }
+    }
+    catch (e) {
+        // best-effort: missing dir is treated as 0 bytes
+        void e;
+    }
+    return Math.round(total / 1024 / 1024);
+}

package/dist/services/job/job-rotation.d.ts

@@ -0,0 +1,17 @@
+import { JobStateStore } from './job-state-store.js';
+export interface CycleOutcome {
+    rotated: boolean;
+    reason?: string;
+}
+export interface CycleSummary {
+    jobId: string;
+    cycle: number;
+}
+export declare class JobRotation {
+    private readonly store;
+    private readonly sessionRotateImpl;
+    private readonly sessionCycleSummaryImpl;
+    constructor(store: JobStateStore, sessionRotateImpl: (jobId: string) => Promise<CycleOutcome>, sessionCycleSummaryImpl: (jobId: string) => Promise<CycleSummary>);
+    cycleIfDue(jobId: string, slicesJustCompleted: number): Promise<CycleOutcome>;
+    rotateNow(jobId: string): Promise<CycleOutcome>;
+}

package/dist/services/job/job-rotation.js

@@ -0,0 +1,30 @@
+export class JobRotation {
+    store;
+    sessionRotateImpl;
+    sessionCycleSummaryImpl;
+    constructor(store, sessionRotateImpl, sessionCycleSummaryImpl) {
+        this.store = store;
+        this.sessionRotateImpl = sessionRotateImpl;
+        this.sessionCycleSummaryImpl = sessionCycleSummaryImpl;
+    }
+    async cycleIfDue(jobId, slicesJustCompleted) {
+        const state = this.store.load(jobId);
+        if (state.mainLoopStrategy !== 'rotating')
+            return { rotated: false, reason: 'single-mode' };
+        if (slicesJustCompleted <= 0)
+            return { rotated: false, reason: 'no-progress' };
+        if (slicesJustCompleted % state.rotateEvery !== 0)
+            return { rotated: false, reason: 'not-on-cadence' };
+        return this.rotateNow(jobId);
+    }
+    async rotateNow(jobId) {
+        const state = this.store.load(jobId);
+        const summary = await this.sessionCycleSummaryImpl(jobId);
+        const outcome = await this.sessionRotateImpl(jobId);
+        if (!outcome.rotated)
+            return { rotated: false, reason: 'session-rotate-refused' };
+        const nextCycle = state.mainSessionCycle + 1;
+        this.store.save({ ...state, mainSessionCycle: nextCycle, lastCheckpointAt: new Date().toISOString() });
+        return { rotated: true, reason: `cycle-${nextCycle} (${summary.cycle})` };
+    }
+}

package/dist/services/job/job-state-store.d.ts

@@ -0,0 +1,24 @@
+import { type JobState } from './job-types.js';
+export interface JobInitInput {
+    jobId: string;
+    sessionId: string;
+    sliceList: string[];
+    parallelismHint: 'serial' | 'llm-decides';
+    exitPolicy: 'strict' | 'best-effort';
+    mainLoopStrategy: 'single' | 'rotating';
+    rotateEvery: number;
+}
+export interface JobLock {
+    jobId: string;
+    path: string;
+}
+export declare class JobStateStore {
+    private readonly rootDir;
+    constructor(rootDir: string);
+    private jobDir;
+    init(input: JobInitInput): JobState;
+    load(jobId: string): JobState;
+    save(state: JobState): void;
+    tryAcquireLock(jobId: string): JobLock;
+    releaseLock(lock: JobLock): void;
+}