peaks-loop 3.0.2 → 3.1.0

package/dist/src/services/context/main-session-monitor.js

@@ -55,6 +55,18 @@ export function detectIdeFromEnv(env = process.env) {
  * Threshold check. Pure function (no IO). `capacityBytes` is injectable
  * for tests and future per-IDE capacity overrides. Defaults to the
  * G9 256K proxy (matches G9 for cognitive continuity).
+ *
+ * @deprecated Slice 2026-07-02-auto-compact-zero-pause: the
+ * 50/75/90 tier thresholds pre-date the v2.13.0 auto-compact
+ * design. The authoritative tier table for triggering compaction
+ * now lives in `evaluateCompactTrigger` (auto-compact-orchestrator.ts)
+ * with the 0.85 pre-compact / 0.95 red-line thresholds. New
+ * callers should call `evaluateCompactTrigger(ratio)` directly.
+ * This function is retained because legacy `peaks context check
+ * --prompt-size` still emits its 4-tier envelope for callers that
+ * need the soft signal (e.g. statusline display). Migration is
+ * scheduled for v2.15.0; the @deprecated tag flips callers'
+ * eslint warnings so the migration is mechanical.
  */
 export function evaluateMainSessionThreshold(promptSize, capacityBytes = CONTEXT_CAPACITY_DEFAULT_BYTES) {
     const inner = evaluateThresholdTier(promptSize, capacityBytes);

package/dist/src/services/hooks/auto-compact-hook-install.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Slice 2026-07-02-auto-compact-zero-pause — `ide-native` pathway
+ * hook install/remove service.
+ *
+ * Writes the auto-compact PreToolUse hook into the consumer
+ * project's `.claude/settings.local.json` so the next Bash or Task
+ * tool call from the running Claude Code session reads
+ * `CLAUDE_CONTEXT_USAGE_PERCENT` and, at ratio ≥ 0.95, in-band fires
+ * `claude --compact` against the current runner (not a child process).
+ *
+ * Idempotency contract:
+ *   - install is idempotent — calling `installAutoCompactHook`
+ *     twice produces a byte-identical file (after stripping the
+ *     magic comment). The on-disk matcher entry is the single
+ *     source of truth.
+ *   - remove is idempotent — calling `removeAutoCompactHook` when
+ *     the hook is absent is a no-op.
+ *   - other PreToolUse entries are untouched on install AND remove.
+ *
+ * Magic comment marker: `peaks:auto-compact-hook-do-not-edit`. The
+ * comment sits next to the matcher entry so a human reading the file
+ * sees the boundary; an automated diff/remove op keys off the marker
+ * + the `matcher` regex.
+ *
+ * Pure data + minimal IO: `installAutoCompactHook` and
+ * `removeAutoCompactHook` accept `settingsPath` so callers can pick
+ * `.claude/settings.local.json` (default) or pass an explicit path
+ * for tests. The functions write to disk via `fs.writeFileSync` so
+ * the on-disk file matches the in-memory template byte-for-byte
+ * (modulo the magic comment which is excluded from the data
+ * structure; see `AUTO_COMPACT_HOOK_MATCHER`).
+ */
+/**
+ * Stable matcher for the auto-compact hook. Single source of truth
+ * — `install` and `remove` both key off this constant so the
+ * invariants can't drift between the two paths.
+ */
+export declare const AUTO_COMPACT_HOOK_MATCHER = "Bash|Task";
+/**
+ * Stable command the hook fires. Wraps `peaks session
+ * auto-compact-hook` so the heavy lifting (ratio probe + in-band
+ * `claude --compact` spawn) lives in the CLI surface, not inlined
+ * into the hook.
+ *
+ * `npx peaks` is deliberately omitted: the project-local install
+ * puts `peaks` on PATH inside the consumer repo (postinstall step),
+ * so the unqualified command works in the same shell the runner
+ * is using.
+ */
+export declare const AUTO_COMPACT_HOOK_COMMAND = "peaks session auto-compact-hook";
+/**
+ * Magic comment marker that fences the auto-compatchook block.
+ * Both install (writes the marker) and remove (matches on it) use
+ * this string so the comment is the only place the boundary lives.
+ */
+export declare const AUTO_COMPACT_HOOK_MARKER = "peaks:auto-compact-hook-do-not-edit";
+/**
+ * Default on-disk location — kept here (not in claude-settings-template)
+ * because the auto-compact hook is a separate install surface from
+ * the fact-forcing gate bypass template.
+ */
+export declare const AUTO_COMPACT_HOOK_SETTINGS_PATH = ".claude/settings.local.json";
+/**
+ * Result envelope for `installAutoCompactHook`.
+ */
+export type AutoCompactHookInstallResult = {
+    readonly action: 'installed';
+    readonly settingsPath: string;
+} | {
+    readonly action: 'already-installed';
+    readonly settingsPath: string;
+};
+/**
+ * Result envelope for `removeAutoCompactHook`.
+ */
+export type AutoCompactHookRemoveResult = {
+    readonly action: 'removed';
+    readonly settingsPath: string;
+} | {
+    readonly action: 'absent';
+    readonly settingsPath: string;
+};
+/**
+ * Install the auto-compact PreToolUse hook. Idempotent: a re-run
+ * returns `action: 'already-installed'` and does NOT re-write the
+ * file (preserves any unrelated edits the user has made to other
+ * entries).
+ */
+export declare function installAutoCompactHook(input: {
+    readonly projectRoot: string;
+    readonly settingsPath?: string;
+}): AutoCompactHookInstallResult;
+/**
+ * Remove the auto-compact PreToolUse hook. Idempotent: missing hook
+ * returns `action: 'absent'` without re-writing the file.
+ *
+ * Other PreToolUse entries are left untouched. The settings file
+ * structure is preserved (top-level keys like `permissions` are not
+ * deleted).
+ */
+export declare function removeAutoCompactHook(input: {
+    readonly projectRoot: string;
+    readonly settingsPath?: string;
+}): AutoCompactHookRemoveResult;

package/dist/src/services/hooks/auto-compact-hook-install.js

@@ -0,0 +1,157 @@
+/**
+ * Slice 2026-07-02-auto-compact-zero-pause — `ide-native` pathway
+ * hook install/remove service.
+ *
+ * Writes the auto-compact PreToolUse hook into the consumer
+ * project's `.claude/settings.local.json` so the next Bash or Task
+ * tool call from the running Claude Code session reads
+ * `CLAUDE_CONTEXT_USAGE_PERCENT` and, at ratio ≥ 0.95, in-band fires
+ * `claude --compact` against the current runner (not a child process).
+ *
+ * Idempotency contract:
+ *   - install is idempotent — calling `installAutoCompactHook`
+ *     twice produces a byte-identical file (after stripping the
+ *     magic comment). The on-disk matcher entry is the single
+ *     source of truth.
+ *   - remove is idempotent — calling `removeAutoCompactHook` when
+ *     the hook is absent is a no-op.
+ *   - other PreToolUse entries are untouched on install AND remove.
+ *
+ * Magic comment marker: `peaks:auto-compact-hook-do-not-edit`. The
+ * comment sits next to the matcher entry so a human reading the file
+ * sees the boundary; an automated diff/remove op keys off the marker
+ * + the `matcher` regex.
+ *
+ * Pure data + minimal IO: `installAutoCompactHook` and
+ * `removeAutoCompactHook` accept `settingsPath` so callers can pick
+ * `.claude/settings.local.json` (default) or pass an explicit path
+ * for tests. The functions write to disk via `fs.writeFileSync` so
+ * the on-disk file matches the in-memory template byte-for-byte
+ * (modulo the magic comment which is excluded from the data
+ * structure; see `AUTO_COMPACT_HOOK_MATCHER`).
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+/**
+ * Stable matcher for the auto-compact hook. Single source of truth
+ * — `install` and `remove` both key off this constant so the
+ * invariants can't drift between the two paths.
+ */
+export const AUTO_COMPACT_HOOK_MATCHER = 'Bash|Task';
+/**
+ * Stable command the hook fires. Wraps `peaks session
+ * auto-compact-hook` so the heavy lifting (ratio probe + in-band
+ * `claude --compact` spawn) lives in the CLI surface, not inlined
+ * into the hook.
+ *
+ * `npx peaks` is deliberately omitted: the project-local install
+ * puts `peaks` on PATH inside the consumer repo (postinstall step),
+ * so the unqualified command works in the same shell the runner
+ * is using.
+ */
+export const AUTO_COMPACT_HOOK_COMMAND = 'peaks session auto-compact-hook';
+/**
+ * Magic comment marker that fences the auto-compatchook block.
+ * Both install (writes the marker) and remove (matches on it) use
+ * this string so the comment is the only place the boundary lives.
+ */
+export const AUTO_COMPACT_HOOK_MARKER = 'peaks:auto-compact-hook-do-not-edit';
+/**
+ * Default on-disk location — kept here (not in claude-settings-template)
+ * because the auto-compact hook is a separate install surface from
+ * the fact-forcing gate bypass template.
+ */
+export const AUTO_COMPACT_HOOK_SETTINGS_PATH = '.claude/settings.local.json';
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function readSettings(settingsPath) {
+    if (!existsSync(settingsPath))
+        return {};
+    try {
+        const raw = readFileSync(settingsPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        return isObject(parsed) ? parsed : {};
+    }
+    catch {
+        // Malformed JSON → start fresh so install doesn't error. The
+        // caller is the human / CLI, not an LLM (idempotency matters
+        // more than preserve-on-corruption here).
+        return {};
+    }
+}
+function writeSettings(settingsPath, settings) {
+    const dir = dirname(settingsPath);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    // 2-space JSON matches the existing template writer's style so
+    // `diff` against pre-install files is minimal.
+    writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+}
+function isAutoCompactEntry(entry) {
+    return entry.matcher === AUTO_COMPACT_HOOK_MATCHER;
+}
+/**
+ * Install the auto-compact PreToolUse hook. Idempotent: a re-run
+ * returns `action: 'already-installed'` and does NOT re-write the
+ * file (preserves any unrelated edits the user has made to other
+ * entries).
+ */
+export function installAutoCompactHook(input) {
+    const settingsPath = input.settingsPath ?? join(input.projectRoot, AUTO_COMPACT_HOOK_SETTINGS_PATH);
+    const settings = readSettings(settingsPath);
+    const hooks = settings.hooks ?? {};
+    const preToolUse = hooks.PreToolUse ?? [];
+    const alreadyInstalled = preToolUse.some(isAutoCompactEntry);
+    if (alreadyInstalled) {
+        return { action: 'already-installed', settingsPath };
+    }
+    const nextPreToolUse = [
+        ...preToolUse,
+        {
+            matcher: AUTO_COMPACT_HOOK_MATCHER,
+            hooks: [
+                {
+                    type: 'command',
+                    command: AUTO_COMPACT_HOOK_COMMAND
+                }
+            ]
+        }
+    ];
+    writeSettings(settingsPath, {
+        ...settings,
+        hooks: {
+            ...hooks,
+            PreToolUse: nextPreToolUse
+        }
+    });
+    return { action: 'installed', settingsPath };
+}
+/**
+ * Remove the auto-compact PreToolUse hook. Idempotent: missing hook
+ * returns `action: 'absent'` without re-writing the file.
+ *
+ * Other PreToolUse entries are left untouched. The settings file
+ * structure is preserved (top-level keys like `permissions` are not
+ * deleted).
+ */
+export function removeAutoCompactHook(input) {
+    const settingsPath = input.settingsPath ?? join(input.projectRoot, AUTO_COMPACT_HOOK_SETTINGS_PATH);
+    if (!existsSync(settingsPath))
+        return { action: 'absent', settingsPath };
+    const settings = readSettings(settingsPath);
+    const hooks = settings.hooks ?? {};
+    const preToolUse = hooks.PreToolUse ?? [];
+    const nextPreToolUse = preToolUse.filter((entry) => !isAutoCompactEntry(entry));
+    if (nextPreToolUse.length === preToolUse.length) {
+        return { action: 'absent', settingsPath };
+    }
+    writeSettings(settingsPath, {
+        ...settings,
+        hooks: {
+            ...hooks,
+            PreToolUse: nextPreToolUse
+        }
+    });
+    return { action: 'removed', settingsPath };
+}

package/dist/src/services/ide/adapters/claude-code-adapter.js

@@ -47,18 +47,30 @@ export const CLAUDE_CODE_ADAPTER = {
         gateEnforce: true,
         statusline: true,
     },
-    // v2.13.0 AC-1 + AC-3 MVP: Claude Code is the first IDE to fill
-    // the `compact` profile. Future adapters (trae / codex / cursor /
-    // qoder / tongyi-lingma / hermes / openclaw) follow the same
-    // shape — peaks-loop reads the env-var and dispatches the
-    // command via `IdeAdapter.compact`, with zero hard-coded IDE
-    // names anywhere in the orchestrator. If your IDE exposes a
-    // context-percent env-var and a slash-style compact command,
-    // register `compact` here and the auto-compact protocol activates.
+    // v2.13.0 AC-1 + AC-3 MVP, slice 2026-07-02-auto-compact-zero-pause:
+    // Claude Code is the first IDE to fill the `compact` profile.
+    // Future adapters (trae / codex / cursor / qoder / tongyi-lingma /
+    // hermes / openclaw) follow the same shape — peaks-loop reads the
+    // env-var and dispatches the command via `IdeAdapter.compact`, with
+    // zero hard-coded IDE names anywhere in the orchestrator. If your
+    // IDE exposes a context-percent env-var and a slash-style compact
+    // command, register `compact` here and the auto-compact protocol
+    // activates.
+    //
+    // Pathway = 'ide-native' (not 'shell-exec') so the dispatcher
+    // routes main-session compacts through the PreToolUse hook in
+    // `.claude/settings.local.json`. The hook fires
+    // `peaks session auto-compact-hook` on the NEXT Bash/Task tool
+    // call from the runner, which in-band spawns `claude --compact`
+    // against the CURRENT runner — not a child process (the
+    // shell-exec spawn-new-claude bug documented in
+    // `.peaks/memory/2026-06-27-auto-compact-design.md:139-152`).
+    // Sub-agent shells still get the legacy shell-exec pathway via
+    // `dispatchIdeCompact({ target: 'sub-agent' })`.
     compact: {
         envVarForContextPercent: 'CLAUDE_CONTEXT_USAGE_PERCENT',
         compactCommand: 'claude --compact',
-        compactPathway: 'shell-exec',
+        compactPathway: 'ide-native',
         postCompactDetectCommand: 'peaks context now --json'
     },
     // Slice #011: standards profile. Claude Code reads its constitution at

package/dist/src/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/src/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/src/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/src/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/src/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/src/services/job/job-resource-snapshot.js

@@ -0,0 +1,47 @@
+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,
+    };
+}
+function dirSizeMb(dir) {
+    let total = 0;
+    try {
+        for (const name of readdirSync(dir)) {
+            try {
+                total += statSync(join(dir, name)).size;
+            }
+            catch (e) {
+                // best-effort: missing entries (race with deletion) are silently skipped
+                void e;
+            }
+        }
+    }
+    catch (e) {
+        // best-effort: missing dir is treated as 0 bytes
+        void e;
+    }
+    return Math.round(total / 1024 / 1024);
+}

package/dist/src/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/src/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/src/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;
+}