peaks-loop 3.0.2 → 3.1.0

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

package/dist/src/services/job/job-types.d.ts

@@ -0,0 +1,444 @@
+import { z } from 'zod';
+export declare const SliceStateSchema: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodObject<{
+    sliceId: z.ZodString;
+    label: z.ZodString;
+    status: z.ZodEnum<["pending", "in-progress", "done", "failed", "blocked", "skipped"]>;
+    commitSha: z.ZodOptional<z.ZodString>;
+    finishedAt: z.ZodOptional<z.ZodString>;
+    failureReason: z.ZodOptional<z.ZodString>;
+    repairCycles: z.ZodDefault<z.ZodNumber>;
+    blockedReason: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    status: "pending" | "skipped" | "done" | "failed" | "blocked" | "in-progress";
+    label: string;
+    sliceId: string;
+    repairCycles: number;
+    commitSha?: string | undefined;
+    finishedAt?: string | undefined;
+    failureReason?: string | undefined;
+    blockedReason?: string | undefined;
+}, {
+    status: "pending" | "skipped" | "done" | "failed" | "blocked" | "in-progress";
+    label: string;
+    sliceId: string;
+    commitSha?: string | undefined;
+    finishedAt?: string | undefined;
+    failureReason?: string | undefined;
+    repairCycles?: number | undefined;
+    blockedReason?: string | undefined;
+}>, {
+    status: "pending" | "skipped" | "done" | "failed" | "blocked" | "in-progress";
+    label: string;
+    sliceId: string;
+    repairCycles: number;
+    commitSha?: string | undefined;
+    finishedAt?: string | undefined;
+    failureReason?: string | undefined;
+    blockedReason?: string | undefined;
+}, {
+    status: "pending" | "skipped" | "done" | "failed" | "blocked" | "in-progress";
+    label: string;
+    sliceId: string;
+    commitSha?: string | undefined;
+    finishedAt?: string | undefined;
+    failureReason?: string | undefined;
+    repairCycles?: number | undefined;
+    blockedReason?: string | undefined;
+}>, {
+    status: "pending" | "skipped" | "done" | "failed" | "blocked" | "in-progress";
+    label: string;
+    sliceId: string;
+    repairCycles: number;
+    commitSha?: string | undefined;
+    finishedAt?: string | undefined;
+    failureReason?: string | undefined;
+    blockedReason?: string | undefined;
+}, {
+    status: "pending" | "skipped" | "done" | "failed" | "blocked" | "in-progress";
+    label: string;
+    sliceId: string;
+    commitSha?: string | undefined;
+    finishedAt?: string | undefined;
+    failureReason?: string | undefined;
+    repairCycles?: number | undefined;
+    blockedReason?: string | undefined;
+}>, {
+    status: "pending" | "skipped" | "done" | "failed" | "blocked" | "in-progress";
+    label: string;
+    sliceId: string;
+    repairCycles: number;
+    commitSha?: string | undefined;
+    finishedAt?: string | undefined;
+    failureReason?: string | undefined;
+    blockedReason?: string | undefined;
+}, {
+    status: "pending" | "skipped" | "done" | "failed" | "blocked" | "in-progress";
+    label: string;
+    sliceId: string;
+    commitSha?: string | undefined;
+    finishedAt?: string | undefined;
+    failureReason?: string | undefined;
+    repairCycles?: number | undefined;
+    blockedReason?: string | undefined;
+}>;
+export declare const JobStateSchema: z.ZodObject<{
+    jobId: z.ZodString;
+    sessionId: z.ZodString;
+    startedAt: z.ZodString;
+    lastCheckpointAt: z.ZodString;
+    parallelismHint: z.ZodDefault<z.ZodEnum<["serial", "llm-decides"]>>;
+    exitPolicy: z.ZodDefault<z.ZodEnum<["strict", "best-effort"]>>;
+    mainLoopStrategy: z.ZodDefault<z.ZodEnum<["single", "rotating"]>>;
+    rotateEvery: z.ZodDefault<z.ZodNumber>;
+    mainSessionCycle: z.ZodDefault<z.ZodNumber>;
+    mainLoopOverride: z.ZodOptional<z.ZodObject<{
+        from: z.ZodLiteral<"rotating">;
+        to: z.ZodLiteral<"single">;
+        reason: z.ZodString;
+        at: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        at: string;
+        reason: string;
+        from: "rotating";
+        to: "single";
+    }, {
+        at: string;
+        reason: string;
+        from: "rotating";
+        to: "single";
+    }>>;
+    slices: z.ZodArray<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodObject<{
+        sliceId: z.ZodString;
+        label: z.ZodString;
+        status: z.ZodEnum<["pending", "in-progress", "done", "failed", "blocked", "skipped"]>;
+        commitSha: z.ZodOptional<z.ZodString>;
+        finishedAt: z.ZodOptional<z.ZodString>;
+        failureReason: z.ZodOptional<z.ZodString>;
+        repairCycles: z.ZodDefault<z.ZodNumber>;
+        blockedReason: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        status: "pending" | "skipped" | "done" | "failed" | "blocked" | "in-progress";
+        label: string;
+        sliceId: string;
+        repairCycles: number;
+        commitSha?: string | undefined;
+        finishedAt?: string | undefined;
+        failureReason?: string | undefined;
+        blockedReason?: string | undefined;
+    }, {
+        status: "pending" | "skipped" | "done" | "failed" | "blocked" | "in-progress";
+        label: string;
+        sliceId: string;
+        commitSha?: string | undefined;
+        finishedAt?: string | undefined;
+        failureReason?: string | undefined;
+        repairCycles?: number | undefined;
+        blockedReason?: string | undefined;
+    }>, {
+        status: "pending" | "skipped" | "done" | "failed" | "blocked" | "in-progress";
+        label: string;
+        sliceId: string;
+        repairCycles: number;
+        commitSha?: string | undefined;
+        finishedAt?: string | undefined;
+        failureReason?: string | undefined;
+        blockedReason?: string | undefined;
+    }, {
+        status: "pending" | "skipped" | "done" | "failed" | "blocked" | "in-progress";
+        label: string;
+        sliceId: string;
+        commitSha?: string | undefined;
+        finishedAt?: string | undefined;
+        failureReason?: string | undefined;
+        repairCycles?: number | undefined;
+        blockedReason?: string | undefined;
+    }>, {
+        status: "pending" | "skipped" | "done" | "failed" | "blocked" | "in-progress";
+        label: string;
+        sliceId: string;
+        repairCycles: number;
+        commitSha?: string | undefined;
+        finishedAt?: string | undefined;
+        failureReason?: string | undefined;
+        blockedReason?: string | undefined;
+    }, {
+        status: "pending" | "skipped" | "done" | "failed" | "blocked" | "in-progress";
+        label: string;
+        sliceId: string;
+        commitSha?: string | undefined;
+        finishedAt?: string | undefined;
+        failureReason?: string | undefined;
+        repairCycles?: number | undefined;
+        blockedReason?: string | undefined;
+    }>, {
+        status: "pending" | "skipped" | "done" | "failed" | "blocked" | "in-progress";
+        label: string;
+        sliceId: string;
+        repairCycles: number;
+        commitSha?: string | undefined;
+        finishedAt?: string | undefined;
+        failureReason?: string | undefined;
+        blockedReason?: string | undefined;
+    }, {
+        status: "pending" | "skipped" | "done" | "failed" | "blocked" | "in-progress";
+        label: string;
+        sliceId: string;
+        commitSha?: string | undefined;
+        finishedAt?: string | undefined;
+        failureReason?: string | undefined;
+        repairCycles?: number | undefined;
+        blockedReason?: string | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    sessionId: string;
+    startedAt: string;
+    slices: {
+        status: "pending" | "skipped" | "done" | "failed" | "blocked" | "in-progress";
+        label: string;
+        sliceId: string;
+        repairCycles: number;
+        commitSha?: string | undefined;
+        finishedAt?: string | undefined;
+        failureReason?: string | undefined;
+        blockedReason?: string | undefined;
+    }[];
+    jobId: string;
+    lastCheckpointAt: string;
+    parallelismHint: "serial" | "llm-decides";
+    exitPolicy: "strict" | "best-effort";
+    mainLoopStrategy: "single" | "rotating";
+    rotateEvery: number;
+    mainSessionCycle: number;
+    mainLoopOverride?: {
+        at: string;
+        reason: string;
+        from: "rotating";
+        to: "single";
+    } | undefined;
+}, {
+    sessionId: string;
+    startedAt: string;
+    slices: {
+        status: "pending" | "skipped" | "done" | "failed" | "blocked" | "in-progress";
+        label: string;
+        sliceId: string;
+        commitSha?: string | undefined;
+        finishedAt?: string | undefined;
+        failureReason?: string | undefined;
+        repairCycles?: number | undefined;
+        blockedReason?: string | undefined;
+    }[];
+    jobId: string;
+    lastCheckpointAt: string;
+    parallelismHint?: "serial" | "llm-decides" | undefined;
+    exitPolicy?: "strict" | "best-effort" | undefined;
+    mainLoopStrategy?: "single" | "rotating" | undefined;
+    rotateEvery?: number | undefined;
+    mainSessionCycle?: number | undefined;
+    mainLoopOverride?: {
+        at: string;
+        reason: string;
+        from: "rotating";
+        to: "single";
+    } | undefined;
+}>;
+export declare const ResourceSnapshotSchema: z.ZodObject<{
+    capturedAt: z.ZodString;
+    cpuPercent: z.ZodNumber;
+    memMb: z.ZodNumber;
+    diskMb: z.ZodNumber;
+    contextRatio: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    capturedAt: string;
+    cpuPercent: number;
+    memMb: number;
+    diskMb: number;
+    contextRatio: number;
+}, {
+    capturedAt: string;
+    cpuPercent: number;
+    memMb: number;
+    diskMb: number;
+    contextRatio: number;
+}>;
+export declare const JobStatusSummarySchema: z.ZodObject<{
+    total: z.ZodNumber;
+    done: z.ZodNumber;
+    failed: z.ZodNumber;
+    blocked: z.ZodNumber;
+    skipped: z.ZodNumber;
+    currentSlice: z.ZodOptional<z.ZodString>;
+    lastCheckpoint: z.ZodString;
+    mainLoopStrategy: z.ZodEnum<["single", "rotating"]>;
+    mainSessionCycle: z.ZodNumber;
+    etaSec: z.ZodOptional<z.ZodNumber>;
+    resourcesNow: z.ZodOptional<z.ZodObject<{
+        capturedAt: z.ZodString;
+        cpuPercent: z.ZodNumber;
+        memMb: z.ZodNumber;
+        diskMb: z.ZodNumber;
+        contextRatio: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        capturedAt: string;
+        cpuPercent: number;
+        memMb: number;
+        diskMb: number;
+        contextRatio: number;
+    }, {
+        capturedAt: string;
+        cpuPercent: number;
+        memMb: number;
+        diskMb: number;
+        contextRatio: number;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    skipped: number;
+    done: number;
+    failed: number;
+    blocked: number;
+    mainLoopStrategy: "single" | "rotating";
+    mainSessionCycle: number;
+    total: number;
+    lastCheckpoint: string;
+    currentSlice?: string | undefined;
+    etaSec?: number | undefined;
+    resourcesNow?: {
+        capturedAt: string;
+        cpuPercent: number;
+        memMb: number;
+        diskMb: number;
+        contextRatio: number;
+    } | undefined;
+}, {
+    skipped: number;
+    done: number;
+    failed: number;
+    blocked: number;
+    mainLoopStrategy: "single" | "rotating";
+    mainSessionCycle: number;
+    total: number;
+    lastCheckpoint: string;
+    currentSlice?: string | undefined;
+    etaSec?: number | undefined;
+    resourcesNow?: {
+        capturedAt: string;
+        cpuPercent: number;
+        memMb: number;
+        diskMb: number;
+        contextRatio: number;
+    } | undefined;
+}>;
+export type SliceState = z.infer<typeof SliceStateSchema>;
+export type JobState = z.infer<typeof JobStateSchema>;
+export type ResourceSnapshot = z.infer<typeof ResourceSnapshotSchema>;
+export type JobStatusSummary = z.infer<typeof JobStatusSummarySchema>;
+export declare const JobInitInputSchema: z.ZodObject<{
+    jobId: z.ZodString;
+    sessionId: z.ZodString;
+    sliceList: z.ZodArray<z.ZodString, "many">;
+    parallelismHint: z.ZodDefault<z.ZodEnum<["serial", "llm-decides"]>>;
+    exitPolicy: z.ZodDefault<z.ZodEnum<["strict", "best-effort"]>>;
+    mainLoopStrategy: z.ZodDefault<z.ZodEnum<["single", "rotating"]>>;
+    rotateEvery: z.ZodDefault<z.ZodNumber>;
+    project: z.ZodString;
+    json: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    project: string;
+    sessionId: string;
+    json: boolean;
+    jobId: string;
+    parallelismHint: "serial" | "llm-decides";
+    exitPolicy: "strict" | "best-effort";
+    mainLoopStrategy: "single" | "rotating";
+    rotateEvery: number;
+    sliceList: string[];
+}, {
+    project: string;
+    sessionId: string;
+    jobId: string;
+    sliceList: string[];
+    json?: boolean | undefined;
+    parallelismHint?: "serial" | "llm-decides" | undefined;
+    exitPolicy?: "strict" | "best-effort" | undefined;
+    mainLoopStrategy?: "single" | "rotating" | undefined;
+    rotateEvery?: number | undefined;
+}>;
+export type JobInitInput = z.infer<typeof JobInitInputSchema>;
+export declare const JobCheckpointInputSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
+    jobId: z.ZodString;
+    sliceId: z.ZodString;
+    state: z.ZodEnum<["done", "failed", "skipped"]>;
+    commitSha: z.ZodOptional<z.ZodString>;
+    reason: z.ZodOptional<z.ZodString>;
+    project: z.ZodString;
+    json: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    project: string;
+    json: boolean;
+    state: "skipped" | "done" | "failed";
+    sliceId: string;
+    jobId: string;
+    reason?: string | undefined;
+    commitSha?: string | undefined;
+}, {
+    project: string;
+    state: "skipped" | "done" | "failed";
+    sliceId: string;
+    jobId: string;
+    json?: boolean | undefined;
+    reason?: string | undefined;
+    commitSha?: string | undefined;
+}>, {
+    project: string;
+    json: boolean;
+    state: "skipped" | "done" | "failed";
+    sliceId: string;
+    jobId: string;
+    reason?: string | undefined;
+    commitSha?: string | undefined;
+}, {
+    project: string;
+    state: "skipped" | "done" | "failed";
+    sliceId: string;
+    jobId: string;
+    json?: boolean | undefined;
+    reason?: string | undefined;
+    commitSha?: string | undefined;
+}>, {
+    project: string;
+    json: boolean;
+    state: "skipped" | "done" | "failed";
+    sliceId: string;
+    jobId: string;
+    reason?: string | undefined;
+    commitSha?: string | undefined;
+}, {
+    project: string;
+    state: "skipped" | "done" | "failed";
+    sliceId: string;
+    jobId: string;
+    json?: boolean | undefined;
+    reason?: string | undefined;
+    commitSha?: string | undefined;
+}>;
+export type JobCheckpointInput = z.infer<typeof JobCheckpointInputSchema>;
+export declare const JobBlockInputSchema: z.ZodObject<{
+    jobId: z.ZodString;
+    sliceId: z.ZodString;
+    reason: z.ZodString;
+    project: z.ZodString;
+    json: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    project: string;
+    json: boolean;
+    reason: string;
+    sliceId: string;
+    jobId: string;
+}, {
+    project: string;
+    reason: string;
+    sliceId: string;
+    jobId: string;
+    json?: boolean | undefined;
+}>;
+export type JobBlockInput = z.infer<typeof JobBlockInputSchema>;

package/dist/src/services/job/job-types.js

@@ -0,0 +1,87 @@
+import { z } from 'zod';
+// ── Spec §4.2, verbatim from spec ────────────────────────────────────────
+export const SliceStateSchema = z
+    .object({
+    sliceId: z.string(),
+    label: z.string(),
+    status: z.enum(['pending', 'in-progress', 'done', 'failed', 'blocked', 'skipped']),
+    commitSha: z.string().optional(), // required when status=done
+    finishedAt: z.string().datetime().optional(),
+    failureReason: z.string().optional(), // required when status=failed
+    repairCycles: z.number().int().nonnegative().default(0),
+    blockedReason: z.string().optional(), // required when status=blocked
+})
+    .refine((v) => v.status !== 'done' || !!(v.commitSha && v.commitSha.length >= 7), { message: 'commitSha required (≥7 hex) when status=done', path: ['commitSha'] })
+    .refine((v) => v.status !== 'failed' || !!(v.failureReason && v.failureReason.length >= 1), { message: 'failureReason required when status=failed', path: ['failureReason'] })
+    .refine((v) => v.status !== 'blocked' || !!(v.blockedReason && v.blockedReason.length >= 1), { message: 'blockedReason required when status=blocked', path: ['blockedReason'] });
+export const JobStateSchema = z.object({
+    jobId: z.string(),
+    sessionId: z.string(),
+    startedAt: z.string().datetime(),
+    lastCheckpointAt: z.string().datetime(),
+    parallelismHint: z.enum(['serial', 'llm-decides']).default('llm-decides'),
+    exitPolicy: z.enum(['strict', 'best-effort']).default('strict'),
+    mainLoopStrategy: z.enum(['single', 'rotating']).default('rotating'),
+    rotateEvery: z.number().int().positive().default(3),
+    mainSessionCycle: z.number().int().nonnegative().default(0),
+    mainLoopOverride: z
+        .object({
+        from: z.literal('rotating'),
+        to: z.literal('single'),
+        reason: z.string().min(10),
+        at: z.string().datetime(),
+    })
+        .optional(),
+    slices: z.array(SliceStateSchema),
+});
+export const ResourceSnapshotSchema = z.object({
+    capturedAt: z.string().datetime(),
+    cpuPercent: z.number().min(0).max(100),
+    memMb: z.number().nonnegative(),
+    diskMb: z.number().nonnegative(),
+    contextRatio: z.number().min(0).max(1),
+});
+export const JobStatusSummarySchema = z.object({
+    total: z.number().int(),
+    done: z.number().int(),
+    failed: z.number().int(),
+    blocked: z.number().int(),
+    skipped: z.number().int(),
+    currentSlice: z.string().optional(),
+    lastCheckpoint: z.string().datetime(),
+    mainLoopStrategy: z.enum(['single', 'rotating']),
+    mainSessionCycle: z.number().int(),
+    etaSec: z.number().int().optional(),
+    resourcesNow: ResourceSnapshotSchema.optional(),
+});
+// ── Spec §4.1 CLI input schemas (used by M3) ─────────────────────────────
+export const JobInitInputSchema = z.object({
+    jobId: z.string().min(1),
+    sessionId: z.string().min(1),
+    sliceList: z.array(z.string().min(1)).min(1),
+    parallelismHint: z.enum(['serial', 'llm-decides']).default('llm-decides'),
+    exitPolicy: z.enum(['strict', 'best-effort']).default('strict'),
+    mainLoopStrategy: z.enum(['single', 'rotating']).default('rotating'),
+    rotateEvery: z.number().int().positive().default(3),
+    project: z.string(),
+    json: z.boolean().default(true),
+});
+export const JobCheckpointInputSchema = z
+    .object({
+    jobId: z.string(),
+    sliceId: z.string(),
+    state: z.enum(['done', 'failed', 'skipped']),
+    commitSha: z.string().optional(),
+    reason: z.string().optional(),
+    project: z.string(),
+    json: z.boolean().default(true),
+})
+    .refine((v) => v.state !== 'done' || (v.commitSha && v.commitSha.length >= 7), { message: 'commitSha required (≥7 hex) when state=done', path: ['commitSha'] })
+    .refine((v) => v.state !== 'failed' && v.state !== 'skipped' ? true : !!(v.reason && v.reason.length >= 3), { message: 'reason required (≥3 chars) when state=failed|skipped', path: ['reason'] });
+export const JobBlockInputSchema = z.object({
+    jobId: z.string(),
+    sliceId: z.string(),
+    reason: z.string().min(3),
+    project: z.string(),
+    json: z.boolean().default(true),
+});

package/dist/src/services/job/subagent-job-wrapper.d.ts

@@ -0,0 +1,35 @@
+import { JobStateStore } from './job-state-store.js';
+export interface WrapInput {
+    jobId: string;
+    role: 'prd' | 'rd' | 'qa' | 'ui' | 'txt' | 'sc' | 'agent';
+    prompt: string;
+    budgetMb?: number;
+}
+export interface DispatchResult {
+    batchId: string;
+}
+export interface DispatchOpts {
+    budgetMb: number;
+    jobScope: true;
+    batchId: string;
+}
+export type DispatchFn = (role: string, prompt: string, opts: DispatchOpts) => Promise<DispatchResult>;
+export interface WrapOutput {
+    batchId: string;
+    requiresCleanup: true;
+}
+export declare class SubAgentJobWrapper {
+    private readonly store;
+    private readonly dispatch;
+    private readonly dispatchedBatches;
+    constructor(store: JobStateStore, dispatch: DispatchFn);
+    wrap(input: WrapInput): Promise<WrapOutput>;
+    canCheckpointDone(jobId: string, batchId: string): boolean;
+    cleanup(input: {
+        jobId: string;
+        batchId: string;
+        force: boolean;
+    }): Promise<{
+        cleaned: boolean;
+    }>;
+}

package/dist/src/services/job/subagent-job-wrapper.js

@@ -0,0 +1,30 @@
+export class SubAgentJobWrapper {
+    store;
+    dispatch;
+    dispatchedBatches = new Map(); // jobId -> set of batchIds pending cleanup
+    constructor(store, dispatch) {
+        this.store = store;
+        this.dispatch = dispatch;
+    }
+    async wrap(input) {
+        const budgetMb = input.budgetMb ?? 512;
+        const candidateBatchId = `batch-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        const result = await this.dispatch(input.role, input.prompt, { budgetMb, jobScope: true, batchId: candidateBatchId });
+        const batchId = result.batchId;
+        if (!this.dispatchedBatches.has(input.jobId))
+            this.dispatchedBatches.set(input.jobId, new Set());
+        this.dispatchedBatches.get(input.jobId).add(batchId);
+        return { batchId, requiresCleanup: true };
+    }
+    canCheckpointDone(jobId, batchId) {
+        const set = this.dispatchedBatches.get(jobId);
+        return !set?.has(batchId);
+    }
+    async cleanup(input) {
+        const set = this.dispatchedBatches.get(input.jobId);
+        if (!set?.has(input.batchId))
+            return { cleaned: true };
+        set.delete(input.batchId);
+        return { cleaned: true };
+    }
+}

package/dist/src/shared/version.d.ts

@@ -1 +1 @@
-export declare const CLI_VERSION = "3.0.2";
+export declare const CLI_VERSION = "3.1.0";

package/dist/src/shared/version.js

@@ -1 +1 @@
-export const CLI_VERSION = "3.0.2";
+export const CLI_VERSION = "3.1.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-loop",
-  "version": "3.0.2",
+  "version": "3.1.0",
   "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
   "author": "SquabbyZ",
   "license": "MIT",