peaks-loop 3.0.3 → 3.1.1

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

package/dist/src/services/job/job-state-store.js

@@ -0,0 +1,60 @@
+import { mkdirSync, readFileSync, writeFileSync, existsSync, unlinkSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { JobStateSchema } from './job-types.js';
+export class JobStateStore {
+    rootDir;
+    constructor(rootDir) {
+        this.rootDir = rootDir;
+    }
+    jobDir(jobId) {
+        return join(this.rootDir, jobId);
+    }
+    init(input) {
+        const state = JobStateSchema.parse({
+            jobId: input.jobId,
+            sessionId: input.sessionId,
+            startedAt: new Date().toISOString(),
+            lastCheckpointAt: new Date().toISOString(),
+            parallelismHint: input.parallelismHint,
+            exitPolicy: input.exitPolicy,
+            mainLoopStrategy: input.mainLoopStrategy,
+            rotateEvery: input.rotateEvery,
+            mainSessionCycle: 0,
+            slices: input.sliceList.map((label, i) => ({
+                sliceId: `slice-${String(i + 1).padStart(3, '0')}`,
+                label,
+                status: 'pending',
+                repairCycles: 0,
+            })),
+        });
+        this.save(state);
+        return state;
+    }
+    load(jobId) {
+        const p = join(this.jobDir(jobId), 'state.json');
+        if (!existsSync(p))
+            throw new Error(`JobStateStore.load: no state for ${jobId} at ${p}`);
+        return JobStateSchema.parse(JSON.parse(readFileSync(p, 'utf8')));
+    }
+    save(state) {
+        // Re-parse to fail loudly on schema regression (M2 unit-test expects this).
+        const valid = JobStateSchema.parse(state);
+        const dir = this.jobDir(valid.jobId);
+        mkdirSync(dir, { recursive: true });
+        const path = join(dir, 'state.json');
+        writeFileSync(path, JSON.stringify(valid, null, 2) + '\n', 'utf8');
+    }
+    tryAcquireLock(jobId) {
+        const lockPath = join(this.jobDir(jobId), 'state.lock');
+        mkdirSync(dirname(lockPath), { recursive: true });
+        if (existsSync(lockPath))
+            throw new Error(`JobStateStore: state already locked at ${lockPath}`);
+        writeFileSync(lockPath, `${process.pid}@${new Date().toISOString()}\n`, 'utf8');
+        return { jobId, path: lockPath };
+    }
+    releaseLock(lock) {
+        if (existsSync(lock.path)) {
+            unlinkSync(lock.path);
+        }
+    }
+}