peaks-loop 3.1.0 → 3.1.2

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

@@ -0,0 +1,70 @@
+/**
+ * v3.1.2 — On-disk slice progress mirror.
+ *
+ * After each `peaks job checkpoint --state done`, the orchestrator writes
+ * `.peaks/_runtime/<sessionId>/job/<jid>/progress.json` so the next LLM
+ * turn (after compact or resume) can read it before any Bash call lands.
+ *
+ * Shape (schemaVersion 1):
+ *   {
+ *     jobId, done, total, currentSlice, lastCommitSha, updatedAt
+ *   }
+ *
+ * The `peaks solo gate-step-08` hook reads this file in its case-1 path
+ * (job-shape.json says isJob=true) and surfaces `Next: slice #N+1 of M
+ * (<currentSlice>)` to stdout. The LLM cannot "wake up cold" — the
+ * next-slice context is mechanically injected on every Bash call.
+ *
+ * Karpathy §2 (Simplicity First): ~50 lines, single-purpose writer +
+ * reader. Schema is zod-validated on read so a stale on-disk copy
+ * from an earlier peaks-loop release fails loud (no silent fallback).
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+export const JOB_PROGRESS_SCHEMA_VERSION = 1;
+export const JobProgressSchema = z.object({
+    schemaVersion: z.literal(JOB_PROGRESS_SCHEMA_VERSION),
+    jobId: z.string(),
+    done: z.number().int().nonnegative(),
+    total: z.number().int().positive(),
+    currentSlice: z.string(),
+    lastCommitSha: z.string().nullable(),
+    updatedAt: z.string().datetime()
+});
+export function writeJobProgress(projectRoot, sessionId, input) {
+    const dir = join(projectRoot, '.peaks', '_runtime', sessionId, 'job', input.jobId);
+    mkdirSync(dir, { recursive: true });
+    const record = {
+        schemaVersion: JOB_PROGRESS_SCHEMA_VERSION,
+        jobId: input.jobId,
+        done: input.done,
+        total: input.total,
+        currentSlice: input.currentSlice,
+        lastCommitSha: input.lastCommitSha,
+        updatedAt: input.updatedAt ?? new Date().toISOString()
+    };
+    const path = join(dir, 'progress.json');
+    writeFileSync(path, JSON.stringify(record, null, 2) + '\n', 'utf8');
+    return record;
+}
+export function readJobProgress(projectRoot, sessionId, jobId) {
+    const path = join(projectRoot, '.peaks', '_runtime', sessionId, 'job', jobId, 'progress.json');
+    if (!existsSync(path)) {
+        throw new Error(`JobProgressStore: no progress for ${jobId} at ${path}`);
+    }
+    const raw = readFileSync(path, 'utf8');
+    return JobProgressSchema.parse(JSON.parse(raw));
+}
+export function tryReadJobProgress(projectRoot, sessionId, jobId) {
+    const path = join(projectRoot, '.peaks', '_runtime', sessionId, 'job', jobId, 'progress.json');
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, 'utf8');
+        return JobProgressSchema.parse(JSON.parse(raw));
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+}

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

@@ -192,6 +192,7 @@ export declare const JobStateSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     sessionId: string;
     startedAt: string;
+    jobId: string;
     slices: {
         status: "pending" | "skipped" | "done" | "failed" | "blocked" | "in-progress";
         label: string;
@@ -202,7 +203,6 @@ export declare const JobStateSchema: z.ZodObject<{
         failureReason?: string | undefined;
         blockedReason?: string | undefined;
     }[];
-    jobId: string;
     lastCheckpointAt: string;
     parallelismHint: "serial" | "llm-decides";
     exitPolicy: "strict" | "best-effort";
@@ -218,6 +218,7 @@ export declare const JobStateSchema: z.ZodObject<{
 }, {
     sessionId: string;
     startedAt: string;
+    jobId: string;
     slices: {
         status: "pending" | "skipped" | "done" | "failed" | "blocked" | "in-progress";
         label: string;
@@ -228,7 +229,6 @@ export declare const JobStateSchema: z.ZodObject<{
         repairCycles?: number | undefined;
         blockedReason?: string | undefined;
     }[];
-    jobId: string;
     lastCheckpointAt: string;
     parallelismHint?: "serial" | "llm-decides" | undefined;
     exitPolicy?: "strict" | "best-effort" | undefined;
@@ -296,9 +296,9 @@ export declare const JobStatusSummarySchema: z.ZodObject<{
     done: number;
     failed: number;
     blocked: number;
+    total: number;
     mainLoopStrategy: "single" | "rotating";
     mainSessionCycle: number;
-    total: number;
     lastCheckpoint: string;
     currentSlice?: string | undefined;
     etaSec?: number | undefined;
@@ -314,9 +314,9 @@ export declare const JobStatusSummarySchema: z.ZodObject<{
     done: number;
     failed: number;
     blocked: number;
+    total: number;
     mainLoopStrategy: "single" | "rotating";
     mainSessionCycle: number;
-    total: number;
     lastCheckpoint: string;
     currentSlice?: string | undefined;
     etaSec?: number | undefined;

package/dist/src/services/solo/emit-handoff.d.ts

@@ -0,0 +1,49 @@
+/**
+ * v3.1.2 Step 11 / final handoff — Size-fear ban.
+ *
+ * Refuses to emit a final handoff while a Job has remaining slices.
+ * Closes the v3.1.0 incident pattern: LLM writes a fake-completion
+ * message at high context-fill before Job mode kicks in.
+ *
+ * Decision tree:
+ *   - job-shape.json missing OR isJob === false  → ALLOW (normal handoff)
+ *   - isJob === true, no state.json              → JOB_NOT_INITIALIZED (LLM
+ *     skipped `peaks job init`)
+ *   - isJob === true, state.json, remaining > 0,
+ *     no --force-under-job                        → JOB_REMAINING_BLOCKED
+ *   - isJob === true, state.json, remaining === 0 → ALLOW (Job done)
+ *   - isJob === true, state.json, remaining > 0,
+ *     --force-under-job                            → ALLOW (override path)
+ *
+ * Karpathy §2 (Simplicity First): ~70 lines, no LLM call, no regex.
+ * Pure read + arithmetic. The CLI wrapper in solo-commands.ts
+ * translates the verdict into exit code + JSON envelope.
+ */
+export declare const JOB_NOT_INITIALIZED: "JOB_NOT_INITIALIZED";
+export declare const JOB_REMAINING_BLOCKED: "JOB_REMAINING_BLOCKED";
+export type EmitHandoffVerdict = {
+    readonly kind: 'allow-not-job';
+} | {
+    readonly kind: 'allow-done';
+    readonly remaining: number;
+} | {
+    readonly kind: 'allow-force-override';
+    readonly remaining: number;
+} | {
+    readonly kind: 'block-not-initialized';
+    readonly code: typeof JOB_NOT_INITIALIZED;
+    readonly jobId: string;
+} | {
+    readonly kind: 'block-remaining';
+    readonly code: typeof JOB_REMAINING_BLOCKED;
+    readonly jobId: string;
+    readonly remaining: number;
+};
+export interface EvaluateEmitHandoffInput {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    /** Suggested job id — read from job-shape.json when omitted. */
+    readonly jobId?: string;
+    readonly forceUnderJob?: boolean;
+}
+export declare function evaluateEmitHandoff(input: EvaluateEmitHandoffInput): EmitHandoffVerdict;

package/dist/src/services/solo/emit-handoff.js

@@ -0,0 +1,79 @@
+/**
+ * v3.1.2 Step 11 / final handoff — Size-fear ban.
+ *
+ * Refuses to emit a final handoff while a Job has remaining slices.
+ * Closes the v3.1.0 incident pattern: LLM writes a fake-completion
+ * message at high context-fill before Job mode kicks in.
+ *
+ * Decision tree:
+ *   - job-shape.json missing OR isJob === false  → ALLOW (normal handoff)
+ *   - isJob === true, no state.json              → JOB_NOT_INITIALIZED (LLM
+ *     skipped `peaks job init`)
+ *   - isJob === true, state.json, remaining > 0,
+ *     no --force-under-job                        → JOB_REMAINING_BLOCKED
+ *   - isJob === true, state.json, remaining === 0 → ALLOW (Job done)
+ *   - isJob === true, state.json, remaining > 0,
+ *     --force-under-job                            → ALLOW (override path)
+ *
+ * Karpathy §2 (Simplicity First): ~70 lines, no LLM call, no regex.
+ * Pure read + arithmetic. The CLI wrapper in solo-commands.ts
+ * translates the verdict into exit code + JSON envelope.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { readJobShapeDecision, JobShapeDecisionError, JOB_SHAPE_NOT_DECIDED } from './job-shape-decision.js';
+export const JOB_NOT_INITIALIZED = 'JOB_NOT_INITIALIZED';
+export const JOB_REMAINING_BLOCKED = 'JOB_REMAINING_BLOCKED';
+function countRemaining(statePath) {
+    let raw;
+    try {
+        raw = readFileSync(statePath, 'utf8');
+    }
+    catch {
+        return Number.NaN;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return Number.NaN;
+    }
+    if (!Array.isArray(parsed.slices))
+        return Number.NaN;
+    return parsed.slices.filter((sl) => sl.status !== 'done' && sl.status !== 'skipped').length;
+}
+function statePath(projectRoot, sessionId, jobId) {
+    return join(projectRoot, '.peaks', '_runtime', sessionId, 'job', jobId, 'state.json');
+}
+export function evaluateEmitHandoff(input) {
+    let decision = null;
+    try {
+        const record = readJobShapeDecision(input.projectRoot, input.sessionId);
+        decision = record.decision;
+    }
+    catch (err) {
+        if (err instanceof JobShapeDecisionError && err.code === JOB_SHAPE_NOT_DECIDED) {
+            return { kind: 'allow-not-job' };
+        }
+        throw err;
+    }
+    if (!decision.isJob)
+        return { kind: 'allow-not-job' };
+    const jobId = input.jobId ?? decision.suggestedJobId;
+    const path = statePath(input.projectRoot, input.sessionId, jobId);
+    if (!existsSync(path)) {
+        return { kind: 'block-not-initialized', code: JOB_NOT_INITIALIZED, jobId };
+    }
+    const remaining = countRemaining(path);
+    if (!Number.isFinite(remaining)) {
+        return { kind: 'block-not-initialized', code: JOB_NOT_INITIALIZED, jobId };
+    }
+    if (remaining === 0) {
+        return { kind: 'allow-done', remaining };
+    }
+    if (input.forceUnderJob === true) {
+        return { kind: 'allow-force-override', remaining };
+    }
+    return { kind: 'block-remaining', code: JOB_REMAINING_BLOCKED, jobId, remaining };
+}

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;

package/dist/src/services/solo/job-shape-decision.js

@@ -0,0 +1,151 @@
+/**
+ * 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).
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+export const JOB_SHAPE_SCHEMA_VERSION = 1;
+export const JOB_SHAPE_FILE_NAME = 'job-shape.json';
+export const JOB_SHAPE_ALREADY_DECIDED = 'JOB_SHAPE_ALREADY_DECIDED';
+export const JOB_SHAPE_NOT_DECIDED = 'JOB_SHAPE_NOT_DECIDED';
+export const JOB_SHAPE_INVALID = 'JOB_SHAPE_INVALID';
+const SUGGESTED_JID_RE = /^[a-z0-9][a-z0-9-]{2,40}$/;
+const JobShapeDecisionSchema = z.object({
+    isJob: z.boolean(),
+    rationale: z.string().min(1).max(2000),
+    suggestedJobId: z.string().regex(SUGGESTED_JID_RE, 'suggestedJobId must match /^[a-z0-9][a-z0-9-]{2,40}$/'),
+    suggestedStrategy: z.enum(['single', 'rotating']),
+    confidence: z.enum(['high', 'medium', 'low']),
+    decidedAt: z.string().datetime()
+});
+const JobShapeRecordSchema = z.object({
+    sessionId: z.string().min(1),
+    promptHash: z.string().regex(/^[a-f0-9]{16}$/, 'promptHash must be 16 hex chars'),
+    decision: JobShapeDecisionSchema,
+    schemaVersion: z.literal(JOB_SHAPE_SCHEMA_VERSION)
+});
+export class JobShapeDecisionError extends Error {
+    code;
+    details;
+    constructor(opts) {
+        super(opts.message);
+        this.name = 'JobShapeDecisionError';
+        this.code = opts.code;
+        if (opts.details !== undefined)
+            this.details = opts.details;
+    }
+}
+function runtimeDir(projectRoot, sessionId) {
+    return join(projectRoot, '.peaks', '_runtime', sessionId);
+}
+function decisionPath(projectRoot, sessionId) {
+    return join(runtimeDir(projectRoot, sessionId), JOB_SHAPE_FILE_NAME);
+}
+function sha1Prefix16(input) {
+    return createHash('sha1').update(input, 'utf8').digest('hex').slice(0, 16);
+}
+/** Pure validator; throws on bad input. No fs IO. */
+export function validateJobShapeDecision(input) {
+    return JobShapeDecisionSchema.parse(input);
+}
+function validateRecord(input) {
+    return JobShapeRecordSchema.parse(input);
+}
+/** Read the canonical record; throws JOB_SHAPE_NOT_DECIDED if absent or malformed. */
+export function readJobShapeDecision(projectRoot, sessionId) {
+    const path = decisionPath(projectRoot, sessionId);
+    if (!existsSync(path)) {
+        throw new JobShapeDecisionError({
+            code: JOB_SHAPE_NOT_DECIDED,
+            message: `No Job-shape decision recorded for session ${sessionId}. Run \`peaks solo detect-job\` to record a decision.`,
+            details: { path }
+        });
+    }
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch (err) {
+        throw new JobShapeDecisionError({
+            code: JOB_SHAPE_NOT_DECIDED,
+            message: `Job-shape decision file is unreadable for session ${sessionId}. Run \`peaks solo detect-job\` to re-record.`,
+            details: { path, cause: err instanceof Error ? err.message : String(err) }
+        });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new JobShapeDecisionError({
+            code: JOB_SHAPE_NOT_DECIDED,
+            message: `Job-shape decision file is malformed JSON for session ${sessionId}. Run \`peaks solo detect-job --force\` to overwrite.`,
+            details: { path, cause: err instanceof Error ? err.message : String(err) }
+        });
+    }
+    try {
+        return validateRecord(parsed);
+    }
+    catch (err) {
+        throw new JobShapeDecisionError({
+            code: JOB_SHAPE_NOT_DECIDED,
+            message: `Job-shape decision file is schema-invalid for session ${sessionId}. Run \`peaks solo detect-job --force\` to overwrite.`,
+            details: { path, cause: err instanceof Error ? err.message : String(err) }
+        });
+    }
+}
+/**
+ * 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 function writeJobShapeDecision(projectRoot, sessionId, decision, opts = {}) {
+    const path = decisionPath(projectRoot, sessionId);
+    if (existsSync(path) && opts.force !== true) {
+        throw new JobShapeDecisionError({
+            code: JOB_SHAPE_ALREADY_DECIDED,
+            message: `Job-shape decision already exists for session ${sessionId}. Re-run with --force to overwrite.`,
+            details: { path }
+        });
+    }
+    // Validate the LLM-supplied fields first so a bad call fails loud
+    // before we touch the filesystem.
+    const partial = {
+        isJob: decision.isJob,
+        rationale: decision.rationale,
+        suggestedJobId: decision.suggestedJobId,
+        suggestedStrategy: decision.suggestedStrategy,
+        confidence: decision.confidence
+    };
+    // Validate the LLM-supplied shape (decidedAt is server-stamped).
+    JobShapeDecisionSchema.omit({ decidedAt: true }).parse(partial);
+    const now = opts.now ?? (() => new Date());
+    const stamped = { ...partial, decidedAt: now().toISOString() };
+    const promptHash = sha1Prefix16(decision.prompt);
+    const record = {
+        sessionId,
+        promptHash,
+        decision: stamped,
+        schemaVersion: JOB_SHAPE_SCHEMA_VERSION
+    };
+    const dir = runtimeDir(projectRoot, sessionId);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(path, JSON.stringify(record, null, 2) + '\n', 'utf8');
+    return record;
+}

package/dist/src/services/solo/step-08-gate.d.ts

@@ -0,0 +1,90 @@
+/**
+ * v3.1.2 Step 0.8 — Mechanical PreToolUse gate.
+ *
+ * Wire-installed by `peaks workspace init` (extends the existing hook
+ * installer; does NOT replace the Write|Edit|MultiEdit fact-forcing
+ * bypass). The hook runs `peaks solo gate-step-08 --project .` before
+ * every Bash tool call. Exit code is the load-bearing contract:
+ *
+ *   exit 0 → allow (with structured stdout describing the decision)
+ *   exit 2 → block (stderr contains the BLOCKED: ... reason)
+ *
+ * Three decision paths:
+ *
+ *   1. `job-shape.json` exists with `decision.isJob === true`.
+ *      → allow, print `{ ok, allow, mode: 'job', decision }`. When a
+ *        matching `job/<jid>/progress.json` exists, also print
+ *        `Next: slice #<N+1> of <M> (<currentSlice>)` so the LLM sees
+ *        its resume context BEFORE any Bash call lands.
+ *   2. `job-shape.json` exists with `decision.isJob === false`.
+ *      → allow, print `{ ok, allow, mode: 'single' }`.
+ *   3. `job-shape.json` is MISSING — fail-closed guard. The LLM is the
+ *      source of truth, but if it never recorded a decision we run a
+ *      lightweight backup regex against the user's prompt:
+ *        /until|全部|until all done|disavow cost|不用考虑费用|all of them/i
+ *      match → block (exit 2) with the BLOCKED: stderr message.
+ *      no match → allow (exit 0) — most prompts are not Job-shaped.
+ *
+ * Karpathy §2 (Simplicity First): ~120 lines, no LLM call inside. The
+ * regex is the FIRST time peaks-loop accepts hardcoded keywords —
+ * explicitly scoped as a *fail-closed backup* (case 3), NOT a primary
+ * judgement. The LLM still owns the semantic call via
+ * `peaks solo detect-job`. The regex is a safety net for the v3.1.1
+ * incident class (LLM under load never records the decision at all).
+ */
+export declare const STEP_08_GATE_FILE_NAME: "job-shape.json";
+export declare const STEP_08_PROGRESS_FILE_NAME: "progress.json";
+/**
+ * Fail-closed backup regex — see module docstring case 3 for why this
+ * exists. Kept short and explicit; if the prompt mentions any of these
+ * triggers and `job-shape.json` is missing, the LLM is treated as
+ * having skipped `peaks solo detect-job` and the gate blocks.
+ *
+ * The list mirrors the v3.1.0 / v3.1.1 incident triggers verbatim:
+ *   继续执行下个 slice (until next slice) → until / 直到
+ *   全部添加完 / all of them            → 全部 / all of them
+ *   不用考虑费用                        → 不用考虑费用 / disavow cost
+ *   until all done                      → until all done
+ */
+export declare const STEP_08_BACKUP_REGEX: RegExp;
+export interface Step08Progress {
+    readonly jobId: string;
+    readonly done: number;
+    readonly total: number;
+    readonly currentSlice: string;
+    readonly lastCommitSha: string | null;
+    readonly updatedAt: string;
+}
+export type Step08Verdict = {
+    readonly kind: 'allow-job';
+    readonly decision: import('./job-shape-decision.js').JobShapeDecision;
+    readonly progress: Step08Progress | null;
+} | {
+    readonly kind: 'allow-single';
+} | {
+    readonly kind: 'block-missing-decision';
+    readonly promptHit: boolean;
+    readonly promptSource: 'flag' | 'last-prompt-file' | 'stdin-empty';
+};
+export declare function runtimeSessionDir(projectRoot: string, sessionId: string): string;
+export interface EvaluateStep08Input {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    /**
+     * Explicit prompt text. When omitted, falls back to
+     * `.peaks/_runtime/<sid>/txt/last-prompt.txt`, then to stdin (the
+     * caller passes stdin verbatim — usually empty in tests).
+     */
+    readonly prompt?: string;
+}
+export interface EvaluateStep08Result {
+    readonly allow: boolean;
+    readonly verdict: Step08Verdict;
+    readonly nextSliceLine: string | null;
+}
+/**
+ * Pure evaluator — does NOT write, does NOT exit. CLI wrapper in
+ * `src/cli/commands/solo-commands.ts` reads `allow` to set the process
+ * exit code (0 allow / 2 block) and prints the structured envelope.
+ */
+export declare function evaluateStep08(input: EvaluateStep08Input): EvaluateStep08Result;