peaks-loop 3.0.3 → 3.1.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 3.1.0 — 2026-07-03
+
+### Fixed — peaks-solo external-references authority declaration
+
+- `skills/peaks-solo/SKILL.md` External-references paragraph now ends with `Peaks-Loop Solo gates and artifacts remain authoritative.` to satisfy `tests/unit/skill-external-invocation.test.ts:63` (`PEAKS_AUTHORITATIVE_PATTERN`). One-line surgical patch; no behaviour change.
+
+### Added — Peaks-Loop Job
+
+- New `peaks job *` subcommand family: init / status / checkpoint / continue / resume / block / handoff / rotate-now / subagent-cleanup (9 commands).
+- New CLI flag `--main-loop-strategy single|rotating` on `job init`, with rotating-mode hard default for ≥3 slices and `rotateEvery=3` cadence.
+- New `--watch` poll mode + statusline event stub (`emitJobEvent`) for ambient progress visibility. Real statusline wire-up deferred to a follow-up slice.
+- Sub-agent wrapper `SubAgentJobWrapper` enforces `--budget-mb 512` default + cleanup gate before slice checkpoint.
+- New peaks-solo SKILL.md Steps 0.8 / 0.81 / 0.85 / 0.86 / 0.87 wrapping the existing single-rid runbook for multi-slice jobs.
+- 9 hard-red-line rules embedded in the skill prose (cost re-ask ban, slice-coalesce ban, fake-completion ban, detached-mode ban, cleanup-skip ban, rotate-skip ban, etc).
+
+### New services
+
+- `src/services/job/job-types.ts` — Zod schemas + types for SliceState, JobState, ResourceSnapshot, JobStatusSummary, plus CLI input schemas (JobInitInput, JobCheckpointInput, JobBlockInput).
+- `src/services/job/job-state-store.ts` — on-disk state store with per-job lockfile.
+- `src/services/job/job-orchestrator.ts` — state machine with strict / best-effort exit policies.
+- `src/services/job/job-rotation.ts` — main-session rotation cadence (single / rotating mode).
+- `src/services/job/subagent-job-wrapper.ts` — budget + cleanup gate.
+- `src/services/job/job-resource-snapshot.ts` — cpu / mem / disk / context collector.
+- `src/services/job/job-event-emitter.ts` — stderr-stub event emit (real statusline wire-up pending).
+
+### Migration
+
+- Existing single-rid flows are unchanged. The Job is opt-in via peaks-solo Step 0.8 detection; users who do not invoke multi-slice requests see no behavior difference.
+- The `peaks session rotate` and `peaks session cycle-summary` subcommands referenced in the spec are NOT shipped in v1; the rotation path uses constructor-injected stub callbacks. M6.5 follow-up will add the real subcommands.
+
+### Spec / plan
+
+- Design: `docs/superpowers/specs/2026-07-03-peaks-loop-job-design.md` (v3).
+- Plans: `docs/superpowers/plans/2026-07-03-peaks-job/` (M1-M7 + README).
+
 ## [3.0.3] — 2026-07-02 — auto-compact zero-pause (ide-native pathway)
 
 **PATCH bump from 3.0.2**. Closes the user-pause gap on long Claude Code sessions: at context ratio ≥ 0.95 the runner now compacts itself via a PreToolUse hook, no human intervention required.

package/dist/src/cli/commands/job-commands.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerJobCommands(program: Command, io?: ProgramIO): void;

package/dist/src/cli/commands/job-commands.js

@@ -0,0 +1,236 @@
+// src/cli/commands/job-commands.ts
+import { join } from 'node:path';
+import { Command } from 'commander';
+import { fail, ok } from '../../shared/result.js';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { JobStateStore } from '../../services/job/job-state-store.js';
+import { JobOrchestrator } from '../../services/job/job-orchestrator.js';
+import { JobRotation } from '../../services/job/job-rotation.js';
+import { SubAgentJobWrapper } from '../../services/job/subagent-job-wrapper.js';
+import { emitJobEvent } from '../../services/job/job-event-emitter.js';
+import { JobInitInputSchema, JobCheckpointInputSchema, JobBlockInputSchema, } from '../../services/job/job-types.js';
+import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
+function projectRoot(opts) {
+    // Reuse the workspace root resolver from peaks CLI; for now, CWD as a safe placeholder.
+    return opts.project ?? process.cwd();
+}
+/**
+ * Resolves the on-disk root for Job state files.
+ *
+ * Per spec §3.3 + §4.5 (2.7.1 single-scope-axis layout), Job state lives at:
+ *   `<projectRoot>/.peaks/_runtime/<sessionId>/job/<jobId>/state.json`
+ *
+ * The `JobStateStore` itself only knows its `rootDir` + `jobId` and joins them. We
+ * compute the canonical root here (per-call) so the store can stay layout-agnostic.
+ *
+ * Resolution order:
+ * 1. `--session-id` flag (explicit override)
+ * 2. `getCurrentSessionId(project)` — reads `.peaks/_runtime/session.json` per peaks-solo
+ * 3. Error (NO_ACTIVE_SESSION) — must never silently fall back to a random uuid
+ */
+function resolveJobStateRoot(opts) {
+    const project = projectRoot(opts);
+    const sessionId = opts.sessionId ?? getCurrentSessionId(project);
+    if (!sessionId) {
+        throw new Error('NO_ACTIVE_SESSION: peaks job requires --session-id or an active peaks-solo session via peaks workspace init');
+    }
+    const rootDir = join(project, '.peaks', '_runtime', sessionId, 'job');
+    return { rootDir, sessionId, projectRoot: project };
+}
+export function registerJobCommands(program, io = { stdout: (t) => process.stdout.write(t), stderr: (t) => process.stderr.write(t) }) {
+    const job = new Command('job').description('Drive long multi-slice work as one Job (peaks-solo Step 0.8+)');
+    job
+        .command('init')
+        .requiredOption('--job-id <jid>')
+        .requiredOption('--slice-list <list>')
+        .option('--parallelism-hint <serial|llm-decides>', 'llm-decides')
+        .option('--exit-policy <strict|best-effort>', 'strict')
+        .option('--main-loop-strategy <single|rotating>', 'rotating')
+        .option('--rotate-every <n>', 'rotate every N slices (rotating mode)', '3')
+        .option('--session-id <sid>', 'session id (default: read from .peaks/_runtime/session.json; required to land in the 2.7.1 single-scope-axis layout)')
+        .option('--project <repo>')
+        .action(async (opts) => {
+        const project = projectRoot(opts);
+        // Resolve sessionId: explicit flag > canonical session binding > FAIL.
+        // Per spec §3.3, Job state lives at .peaks/_runtime/<sessionId>/job/<jobId>/state.json —
+        // a random UUID would scatter state across dirs and break resume/auto-compact.
+        let sessionId = opts.sessionId ?? getCurrentSessionId(project);
+        if (!sessionId) {
+            return printResult(io, fail('init', 'NO_ACTIVE_SESSION', 'peaks job init requires --session-id (or an active peaks-solo session via peaks workspace init)', { project }, [
+                'Re-run with --session-id <sid>',
+                'Or run `peaks workspace init` to create a session first'
+            ]), opts);
+        }
+        const parsed = JobInitInputSchema.safeParse({
+            jobId: opts.jobId,
+            sessionId,
+            sliceList: opts.sliceList.split(',').map((s) => s.trim()).filter(Boolean),
+            parallelismHint: opts.parallelismHint,
+            exitPolicy: opts.exitPolicy,
+            mainLoopStrategy: opts.mainLoopStrategy,
+            rotateEvery: Number(opts.rotateEvery),
+            project,
+            json: opts.json,
+        });
+        if (!parsed.success)
+            return printResult(io, fail('init', 'INVALID_INIT', parsed.error.message, {}), opts);
+        const jobRoot = resolveJobStateRoot(opts);
+        const store = new JobStateStore(jobRoot.rootDir);
+        const orch = new JobOrchestrator(store);
+        const state = orch.init({
+            jobId: parsed.data.jobId,
+            sessionId: parsed.data.sessionId,
+            sliceList: parsed.data.sliceList,
+            parallelismHint: parsed.data.parallelismHint,
+            exitPolicy: parsed.data.exitPolicy,
+            mainLoopStrategy: parsed.data.mainLoopStrategy,
+            rotateEvery: parsed.data.rotateEvery,
+        });
+        try {
+            emitJobEvent({ kind: 'job-started', jobId: state.jobId, total: state.slices.length, strategy: state.mainLoopStrategy });
+        }
+        catch (e) {
+            // best-effort: event emission failures must not abort job init
+            void e;
+        }
+        printResult(io, ok('init', { jobId: state.jobId, sliceCount: state.slices.length, statePath: `${jobRoot.rootDir}/${state.jobId}/state.json` }), opts);
+    });
+    addJsonOption(job.commands.find(c => c.name() === 'init'));
+    job
+        .command('status')
+        .requiredOption('--job-id <jid>')
+        .option('--watch', 'poll every 3s')
+        .option('--show-cost', 'overlay cost from peaks budget')
+        .option('--project <repo>')
+        .action(async (opts) => {
+        const store = new JobStateStore(resolveJobStateRoot(opts).rootDir);
+        const orch = new JobOrchestrator(store);
+        const s = orch.status(opts.jobId);
+        if (opts.watch) {
+            const draw = () => {
+                const bar = `[${'='.repeat(s.done)}${' '.repeat(s.total - s.done)}]`;
+                process.stdout.write(`\rjob ${opts.jobId}: ${bar} ${s.done}/${s.total}${s.currentSlice ? ` next=${s.currentSlice}` : ''}    `);
+            };
+            draw();
+            const iv = setInterval(() => { const u = orch.status(opts.jobId); Object.assign(s, u); draw(); if (u.done + u.failed + u.skipped + u.blocked >= u.total)
+                clearInterval(iv); }, 3000);
+            process.on('SIGINT', () => { clearInterval(iv); process.stdout.write('\n'); process.exit(0); });
+            return;
+        }
+        try {
+            emitJobEvent({ kind: 'job-progress', jobId: opts.jobId, done: s.done, total: s.total, ...(s.currentSlice ? { currentSlice: s.currentSlice } : {}) });
+        }
+        catch (e) {
+            // best-effort: event emission failures must not abort job status
+            void e;
+        }
+        printResult(io, ok('status', s), opts);
+    });
+    addJsonOption(job.commands.find(c => c.name() === 'status'));
+    // M4.2: wire rotate-now to JobRotation (session-rotate callbacks are stubs pending M6.5 batch-fix).
+    job.command('rotate-now')
+        .requiredOption('--job-id <jid>')
+        .option('--project <repo>')
+        .action(async (opts) => {
+        const store = new JobStateStore(resolveJobStateRoot(opts).rootDir);
+        const rotation = new JobRotation(store, async (_jid) => { /* delegate to peaks session rotate — implementation wired in M6.5 batch-fix */ return { rotated: true }; }, async (jid) => ({ jobId: jid, cycle: 0 }));
+        const r = await rotation.rotateNow(opts.jobId);
+        printResult(io, ok('rotate-now', r), opts);
+    });
+    addJsonOption(job.commands.find(c => c.name() === 'rotate-now'));
+    job.command('subagent-cleanup')
+        .requiredOption('--job-id <jid>')
+        .requiredOption('--batch-id <bid>')
+        .option('--force')
+        .option('--project <repo>')
+        .action(async (opts) => {
+        const wrapper = new SubAgentJobWrapper(new JobStateStore(resolveJobStateRoot(opts).rootDir), async () => ({ batchId: opts.batchId }));
+        const r = await wrapper.cleanup({ jobId: opts.jobId, batchId: opts.batchId, force: !!opts.force });
+        printResult(io, ok('subagent-cleanup', r), opts);
+    });
+    addJsonOption(job.commands.find(c => c.name() === 'subagent-cleanup'));
+    // M3.2: wire the remaining 5 subcommand slots — block, checkpoint, continue, handoff, resume.
+    job
+        .command('checkpoint')
+        .requiredOption('--job-id <jid>')
+        .requiredOption('--slice-id <rid>')
+        .requiredOption('--state <done|failed|skipped>')
+        .option('--commit-sha <sha>')
+        .option('--reason <text>')
+        .option('--project <repo>')
+        .action(async (opts) => {
+        const parsed = JobCheckpointInputSchema.safeParse({
+            jobId: opts.jobId, sliceId: opts.sliceId, state: opts.state,
+            commitSha: opts.commitSha, reason: opts.reason,
+            project: projectRoot(opts), json: opts.json,
+        });
+        if (!parsed.success)
+            return printResult(io, fail('checkpoint', 'INVALID_CHECKPOINT', parsed.error.message, {}), opts);
+        const store = new JobStateStore(resolveJobStateRoot(opts).rootDir);
+        const orch = new JobOrchestrator(store);
+        if (parsed.data.state === 'done') {
+            await orch.checkpointDone({ jobId: parsed.data.jobId, sliceId: parsed.data.sliceId, ...(parsed.data.commitSha ? { commitSha: parsed.data.commitSha } : {}) });
+        }
+        else if (parsed.data.state === 'skipped') {
+            await orch.checkpointSkipped({ jobId: parsed.data.jobId, sliceId: parsed.data.sliceId, reason: parsed.data.reason });
+        }
+        else {
+            await orch.checkpointFailed({ jobId: parsed.data.jobId, sliceId: parsed.data.sliceId, reason: parsed.data.reason });
+        }
+        printResult(io, ok('checkpoint', { sliceId: parsed.data.sliceId, status: parsed.data.state }), opts);
+    });
+    addJsonOption(job.commands.find(c => c.name() === 'checkpoint'));
+    job
+        .command('block')
+        .requiredOption('--job-id <jid>')
+        .requiredOption('--slice-id <rid>')
+        .requiredOption('--reason <text>')
+        .option('--project <repo>')
+        .action(async (opts) => {
+        const parsed = JobBlockInputSchema.safeParse({
+            jobId: opts.jobId, sliceId: opts.sliceId, reason: opts.reason,
+            project: projectRoot(opts), json: opts.json,
+        });
+        if (!parsed.success)
+            return printResult(io, fail('block', 'INVALID_BLOCK', parsed.error.message, {}), opts);
+        const store = new JobStateStore(resolveJobStateRoot(opts).rootDir);
+        const orch = new JobOrchestrator(store);
+        await orch.blockSlice(parsed.data);
+        printResult(io, ok('block', { blocked: parsed.data.sliceId, reason: parsed.data.reason }), opts);
+    });
+    addJsonOption(job.commands.find(c => c.name() === 'block'));
+    job
+        .command('continue')
+        .requiredOption('--job-id <jid>')
+        .option('--project <repo>')
+        .action(async (opts) => {
+        const store = new JobStateStore(resolveJobStateRoot(opts).rootDir);
+        const orch = new JobOrchestrator(store);
+        const r = orch.continueNow(opts.jobId);
+        printResult(io, ok('continue', r), opts);
+    });
+    addJsonOption(job.commands.find(c => c.name() === 'continue'));
+    job
+        .command('resume')
+        .requiredOption('--job-id <jid>')
+        .option('--project <repo>')
+        .action(async (opts) => {
+        const store = new JobStateStore(resolveJobStateRoot(opts).rootDir);
+        const orch = new JobOrchestrator(store);
+        const s = orch.status(opts.jobId);
+        printResult(io, ok('resume', { resumed: opts.jobId, ...s }), opts);
+    });
+    addJsonOption(job.commands.find(c => c.name() === 'resume'));
+    job
+        .command('handoff')
+        .requiredOption('--job-id <jid>')
+        .option('--project <repo>')
+        .action(async (opts) => {
+        const store = new JobStateStore(resolveJobStateRoot(opts).rootDir);
+        const orch = new JobOrchestrator(store);
+        const s = orch.status(opts.jobId);
+        printResult(io, ok('handoff', { handoffFor: opts.jobId, ...s }), opts);
+    });
+    addJsonOption(job.commands.find(c => c.name() === 'handoff'));
+    program.addCommand(job);
+}

package/dist/src/cli/program.js

@@ -74,6 +74,8 @@ import { registerObservabilityCommands } from './commands/observability-commands
 // CLI primitives. See src/services/compact/ and
 // src/cli/commands/compact-command.ts.
 import { registerCompactCommands } from './commands/compact-command.js';
+// Slice 2026-07-01-job-m3.1: `peaks job init|status|...` — Job orchestration CLI surface.
+import { registerJobCommands } from './commands/job-commands.js';
 import { applyRetention } from '../services/log/retention.js';
 import { writeLogEntry, maybeWriteStderr } from '../services/log/logger.js';
 export { printResult } from './cli-helpers.js';
@@ -341,5 +343,9 @@ Run peaks (no arguments) for a quickstart. You likely want one of:
     // suggest|recommend|survival|dry-run|force` — strategic-compact CLI
     // primitives. See src/cli/commands/compact-command.ts.
     registerCompactCommands(program, io);
+    // Slice 2026-07-01-job-m3.1: `peaks job init|status|...` — Job
+    // orchestration CLI surface. M3.1 wires init + status + 2 stubs;
+    // the remaining 5 subcommands land in M3.2.
+    registerJobCommands(program, io);
     return program;
 }

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;
+}