peaks-loop 3.0.3 → 3.1.1

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/services/solo/job-shape-decision.d.ts

@@ -0,0 +1,71 @@
+/**
+ * v3.1.1 Step 0.8 — Job-shape decision recorder.
+ *
+ * The CLI is a *recorder and gate*, not a judge. The LLM makes the
+ * semantic call ("is this a Job?") and writes the verdict via
+ * `peaks solo detect-job`; this service persists the verdict to
+ * `.peaks/_runtime/<sessionId>/job-shape.json` and refuses downstream
+ * steps that need a decision when the file is missing.
+ *
+ * Karpathy §2 (Simplicity First): ~100 lines, pure validation + fs
+ * writes, NO keyword regex, NO LLM call inside. The LLM is the
+ * source of truth for whether the request is Job-shaped; this file
+ * just enforces that a decision was made at all.
+ *
+ * Decision file lives at `.peaks/_runtime/<sessionId>/job-shape.json`
+ * (sibling of `session.json`, NOT under `job/<jid>/` because no jid
+ * exists yet at the moment of Step 0.8).
+ */
+export type JobStrategy = 'single' | 'rotating';
+export type JobConfidence = 'high' | 'medium' | 'low';
+export interface JobShapeDecision {
+    readonly isJob: boolean;
+    readonly rationale: string;
+    readonly suggestedJobId: string;
+    readonly suggestedStrategy: JobStrategy;
+    readonly confidence: JobConfidence;
+    /** ISO 8601; stamped server-side in `writeJobShapeDecision`. */
+    readonly decidedAt: string;
+}
+export interface JobShapeRecord {
+    readonly sessionId: string;
+    /** sha1 of the user prompt (first 16 hex). */
+    readonly promptHash: string;
+    readonly decision: JobShapeDecision;
+    readonly schemaVersion: 1;
+}
+export declare const JOB_SHAPE_SCHEMA_VERSION: 1;
+export declare const JOB_SHAPE_FILE_NAME = "job-shape.json";
+export declare const JOB_SHAPE_ALREADY_DECIDED: "JOB_SHAPE_ALREADY_DECIDED";
+export declare const JOB_SHAPE_NOT_DECIDED: "JOB_SHAPE_NOT_DECIDED";
+export declare const JOB_SHAPE_INVALID: "JOB_SHAPE_INVALID";
+export declare class JobShapeDecisionError extends Error {
+    readonly code: typeof JOB_SHAPE_NOT_DECIDED | typeof JOB_SHAPE_ALREADY_DECIDED | typeof JOB_SHAPE_INVALID;
+    readonly details?: unknown;
+    constructor(opts: {
+        code: typeof JobShapeDecisionError.prototype.code;
+        message: string;
+        details?: unknown;
+    });
+}
+/** Pure validator; throws on bad input. No fs IO. */
+export declare function validateJobShapeDecision(input: unknown): JobShapeDecision;
+/** Read the canonical record; throws JOB_SHAPE_NOT_DECIDED if absent or malformed. */
+export declare function readJobShapeDecision(projectRoot: string, sessionId: string): JobShapeRecord;
+export interface WriteJobShapeDecisionInput {
+    readonly isJob: boolean;
+    readonly rationale: string;
+    readonly suggestedJobId: string;
+    readonly suggestedStrategy: JobStrategy;
+    readonly confidence: JobConfidence;
+    readonly prompt: string;
+}
+/**
+ * Persist a new decision; refuses overwrite unless `force: true`.
+ * Stamps `decidedAt` server-side via `now` (defaults to `new Date()`)
+ * so the LLM cannot back-date.
+ */
+export declare function writeJobShapeDecision(projectRoot: string, sessionId: string, decision: WriteJobShapeDecisionInput, opts?: {
+    force?: boolean;
+    now?: () => Date;
+}): JobShapeRecord;