localptp 0.1.0

package/dist/core/reviewEngine.js

@@ -0,0 +1,229 @@
+/**
+ * Review Engine (HLD-SRD §3.12; 0001_06).
+ *
+ * Powers the advisory `review` command: collect the current Git diff, build a
+ * reviewer context, ask the model to review it, and tolerantly parse the JSON
+ * report — falling back to the raw text on a parse failure so a local model's
+ * imperfect output never blocks the human. The engine NEVER edits, reverts, or
+ * applies code; it only reads the diff and returns a report.
+ *
+ * The tolerant extractor mirrors the 0001_04 planner extractor: strict
+ * whole-output parse, else the FIRST balanced `{...}` block, validated against
+ * `reviewReportSchema` (whose array fields default `[]`). A total failure
+ * returns `null`, and the caller prints the raw review.
+ */
+import { simpleGit } from "simple-git";
+import { buildContext } from "./contextBuilder.js";
+import { getPrompt } from "./promptManager.js";
+import { loadMemoryFiles } from "./memoryLoader.js";
+import { resolveActive } from "./activePointer.js";
+import { parseTask } from "./taskManager.js";
+import { loadSession } from "./sessionManager.js";
+import { ConfigManager } from "./configManager.js";
+import { layout } from "../utils/paths.js";
+import { readIfExists } from "../utils/fs.js";
+import { repoIndexSchema } from "../types/index.js";
+import { parseActiveTask, parseActiveSession } from "../types/context.js";
+import { reviewReportSchema } from "../types/review.js";
+import path from "node:path";
+/**
+ * Find the first balanced `{...}` substring, tracking string/escape state so
+ * braces inside strings do not unbalance the count. Mirrors the 0001_04
+ * planner extractor.
+ */
+function firstBalancedObject(raw) {
+    const start = raw.indexOf("{");
+    if (start === -1)
+        return undefined;
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    for (let i = start; i < raw.length; i++) {
+        const ch = raw[i];
+        if (inString) {
+            if (escaped)
+                escaped = false;
+            else if (ch === "\\")
+                escaped = true;
+            else if (ch === '"')
+                inString = false;
+            continue;
+        }
+        if (ch === '"')
+            inString = true;
+        else if (ch === "{")
+            depth += 1;
+        else if (ch === "}") {
+            depth -= 1;
+            if (depth === 0)
+                return raw.slice(start, i + 1);
+        }
+    }
+    return undefined;
+}
+/**
+ * Tolerantly extract + validate a review report from raw model output. Returns
+ * the parsed report, or `null` when nothing parseable + valid is found (the
+ * caller then prints the raw text).
+ */
+export function tolerantParseReviewReport(raw) {
+    // 1. Strict whole-output parse.
+    try {
+        const obj = JSON.parse(raw);
+        if (obj !== null && typeof obj === "object" && !Array.isArray(obj)) {
+            const r = reviewReportSchema.safeParse(obj);
+            if (r.success)
+                return r.data;
+        }
+    }
+    catch {
+        // fall through
+    }
+    // 2. First balanced {...} block.
+    const block = firstBalancedObject(raw);
+    if (block === undefined)
+        return null;
+    try {
+        const obj = JSON.parse(block);
+        const r = reviewReportSchema.safeParse(obj);
+        return r.success ? r.data : null;
+    }
+    catch {
+        return null;
+    }
+}
+const EMPTY_INDEX = {
+    generatedAt: "",
+    root: "",
+    files: [],
+};
+async function loadIndex(orchestratorDir) {
+    const raw = await readIfExists(path.join(orchestratorDir, "index.json"));
+    if (raw === undefined)
+        return EMPTY_INDEX;
+    try {
+        const parsed = repoIndexSchema.safeParse(JSON.parse(raw));
+        return parsed.success ? parsed.data : EMPTY_INDEX;
+    }
+    catch {
+        return EMPTY_INDEX;
+    }
+}
+/**
+ * The current working-tree diff for the repo at `root`: staged + unstaged
+ * changes to tracked files (`git diff HEAD`). Returns "" when nothing changed
+ * or the directory is not a git repo.
+ */
+export async function currentDiff(root) {
+    const git = simpleGit(root);
+    try {
+        if (!(await git.checkIsRepo()))
+            return "";
+        // `git diff HEAD` captures both staged and unstaged tracked changes.
+        return await git.diff(["HEAD"]);
+    }
+    catch {
+        // No commits yet, or git error — fall back to the plain working-tree diff.
+        try {
+            return await git.diff();
+        }
+        catch {
+            return "";
+        }
+    }
+}
+/** Parse the changed-file paths from a unified diff (`diff --git a/x b/x`). */
+export function changedFilesOf(diff) {
+    const files = new Set();
+    const re = /^diff --git a\/(.+?) b\/(.+)$/gm;
+    let m;
+    while ((m = re.exec(diff)) !== null) {
+        files.add(m[2]);
+    }
+    return [...files];
+}
+/**
+ * Build the reviewer system + user prompts. The Context Builder assembles the
+ * task/session/memory; the diff (which it does not model) is appended to the
+ * user prompt so the reviewer sees exactly what changed.
+ */
+export function buildReviewPrompt(inputs) {
+    const pkg = buildContext({
+        role: "reviewer",
+        config: inputs.config,
+        index: inputs.index,
+        memory: inputs.memory,
+        ...(inputs.taskRaw !== undefined ? { task: parseActiveTask(inputs.taskRaw) } : {}),
+        ...(inputs.sessionRaw !== undefined
+            ? { session: parseActiveSession(inputs.sessionRaw) }
+            : {}),
+        fileContents: {},
+    });
+    const changed = changedFilesOf(inputs.diff);
+    const reviewer = getPrompt("reviewer");
+    const userContext = pkg.userPrompt +
+        `\n\n## Changed files\n\n${changed.length > 0 ? changed.map((f) => `- ${f}`).join("\n") : "(none parsed)"}` +
+        `\n\n## Diff under review\n\n\`\`\`diff\n${inputs.diff}\n\`\`\``;
+    return {
+        systemPrompt: reviewer.system,
+        userPrompt: reviewer.renderUser(userContext),
+    };
+}
+/**
+ * Run the review: collect the diff, call the model, tolerantly parse the report.
+ * Returns `{ hadChanges: false }` when the diff is empty (the caller prints "No
+ * changes to review" and exits 0). A model error propagates to the caller.
+ */
+export async function runReviewEngine(deps) {
+    const { detectGitRoot } = await import("../utils/gitRoot.js");
+    const git = await detectGitRoot(deps.cwd);
+    const root = git.root ?? deps.cwd;
+    const l = layout(root);
+    const diff = await currentDiff(root);
+    if (diff.trim().length === 0) {
+        return { hadChanges: false };
+    }
+    const config = await new ConfigManager(l.configFile).load();
+    const index = await loadIndex(l.orchestratorDir);
+    const memory = await loadMemoryFiles(root);
+    // Active task/session are optional context — review works without them.
+    let taskRaw;
+    let sessionRaw;
+    const active = await resolveActive(l.orchestratorDir);
+    if (active.kind === "ok") {
+        try {
+            taskRaw = (await parseTask(active.pointer.taskPath)).raw;
+        }
+        catch {
+            // ignore
+        }
+        try {
+            sessionRaw = (await loadSession(active.pointer.sessionPath)).raw;
+        }
+        catch {
+            // ignore
+        }
+    }
+    const { systemPrompt, userPrompt } = buildReviewPrompt({
+        config,
+        index,
+        memory,
+        ...(taskRaw !== undefined ? { taskRaw } : {}),
+        ...(sessionRaw !== undefined ? { sessionRaw } : {}),
+        diff,
+    });
+    // A §12 ModelClientError propagates unchanged — the caller maps it to a
+    // non-zero exit with the connectivity guidance.
+    const response = await deps.client.complete({
+        role: "reviewer",
+        systemPrompt,
+        userPrompt,
+    });
+    const report = tolerantParseReviewReport(response.content);
+    return {
+        hadChanges: true,
+        ...(report !== null ? { report } : {}),
+        raw: response.content,
+    };
+}
+//# sourceMappingURL=reviewEngine.js.map

package/dist/core/reviewEngine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reviewEngine.js","sourceRoot":"","sources":["../../src/core/reviewEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAkB,MAAM,mBAAmB,CAAC;AACpE,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC1E,OAAO,EAAE,kBAAkB,EAAqB,MAAM,oBAAoB,CAAC;AAG3E,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B;;;;GAIG;AACH,SAAS,mBAAmB,CAAC,GAAW;IACtC,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC/B,IAAI,KAAK,KAAK,CAAC,CAAC;QAAE,OAAO,SAAS,CAAC;IACnC,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,KAAK,IAAI,CAAC,GAAG,KAAK,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACxC,MAAM,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;QAClB,IAAI,QAAQ,EAAE,CAAC;YACb,IAAI,OAAO;gBAAE,OAAO,GAAG,KAAK,CAAC;iBACxB,IAAI,EAAE,KAAK,IAAI;gBAAE,OAAO,GAAG,IAAI,CAAC;iBAChC,IAAI,EAAE,KAAK,GAAG;gBAAE,QAAQ,GAAG,KAAK,CAAC;YACtC,SAAS;QACX,CAAC;QACD,IAAI,EAAE,KAAK,GAAG;YAAE,QAAQ,GAAG,IAAI,CAAC;aAC3B,IAAI,EAAE,KAAK,GAAG;YAAE,KAAK,IAAI,CAAC,CAAC;aAC3B,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;YACpB,KAAK,IAAI,CAAC,CAAC;YACX,IAAI,KAAK,KAAK,CAAC;gBAAE,OAAO,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QAClD,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CAAC,GAAW;IACnD,gCAAgC;IAChC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAY,CAAC;QACvC,IAAI,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;YACnE,MAAM,CAAC,GAAG,kBAAkB,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;YAC5C,IAAI,CAAC,CAAC,OAAO;gBAAE,OAAO,CAAC,CAAC,IAAI,CAAC;QAC/B,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,eAAe;IACjB,CAAC;IACD,iCAAiC;IACjC,MAAM,KAAK,GAAG,mBAAmB,CAAC,GAAG,CAAC,CAAC;IACvC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACrC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAY,CAAC;QACzC,MAAM,CAAC,GAAG,kBAAkB,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;QAC5C,OAAO,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;IACnC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,WAAW,GAAc;IAC7B,WAAW,EAAE,EAAE;IACf,IAAI,EAAE,EAAE;IACR,KAAK,EAAE,EAAE;CACc,CAAC;AAE1B,KAAK,UAAU,SAAS,CAAC,eAAuB;IAC9C,MAAM,GAAG,GAAG,MAAM,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,YAAY,CAAC,CAAC,CAAC;IACzE,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,WAAW,CAAC;IAC1C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,eAAe,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;QAC1D,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC;IACpD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,WAAW,CAAC;IACrB,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAY;IAC5C,MAAM,GAAG,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IAC5B,IAAI,CAAC;QACH,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,WAAW,EAAE,CAAC;YAAE,OAAO,EAAE,CAAC;QAC1C,qEAAqE;QACrE,OAAO,MAAM,GAAG,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;IAClC,CAAC;IAAC,MAAM,CAAC;QACP,2EAA2E;QAC3E,IAAI,CAAC;YACH,OAAO,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;QAC1B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC;AACH,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,MAAM,EAAE,GAAG,iCAAiC,CAAC;IAC7C,IAAI,CAAyB,CAAC;IAC9B,OAAO,CAAC,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QACpC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IACD,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC;AACpB,CAAC;AAWD;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAA+B;IAI/D,MAAM,GAAG,GAAG,YAAY,CAAC;QACvB,IAAI,EAAE,UAAU;QAChB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,GAAG,CAAC,MAAM,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,eAAe,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAClF,GAAG,CAAC,MAAM,CAAC,UAAU,KAAK,SAAS;YACjC,CAAC,CAAC,EAAE,OAAO,EAAE,kBAAkB,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE;YACpD,CAAC,CAAC,EAAE,CAAC;QACP,YAAY,EAAE,EAAE;KACjB,CAAC,CAAC;IACH,MAAM,OAAO,GAAG,cAAc,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC5C,MAAM,QAAQ,GAAG,SAAS,CAAC,UAAU,CAAC,CAAC;IACvC,MAAM,WAAW,GACf,GAAG,CAAC,UAAU;QACd,2BAA2B,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,eAAe,EAAE;QAC3G,2CAA2C,MAAM,CAAC,IAAI,UAAU,CAAC;IACnE,OAAO;QACL,YAAY,EAAE,QAAQ,CAAC,MAAM;QAC7B,UAAU,EAAE,QAAQ,CAAC,UAAU,CAAC,WAAW,CAAC;KAC7C,CAAC;AACJ,CAAC;AAeD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,IAAsB;IAC1D,MAAM,EAAE,aAAa,EAAE,GAAG,MAAM,MAAM,CAAC,qBAAqB,CAAC,CAAC;IAC9D,MAAM,GAAG,GAAG,MAAM,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC1C,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,IAAI,IAAI,CAAC,GAAG,CAAC;IAClC,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;IAEvB,MAAM,IAAI,GAAG,MAAM,WAAW,CAAC,IAAI,CAAC,CAAC;IACrC,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;IAC/B,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,IAAI,aAAa,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,IAAI,EAAE,CAAC;IAC5D,MAAM,KAAK,GAAG,MAAM,SAAS,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC;IACjD,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC,IAAI,CAAC,CAAC;IAE3C,wEAAwE;IACxE,IAAI,OAA2B,CAAC;IAChC,IAAI,UAA8B,CAAC;IACnC,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC;IACtD,IAAI,MAAM,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;QACzB,IAAI,CAAC;YACH,OAAO,GAAG,CAAC,MAAM,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC;QAC3D,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;QACD,IAAI,CAAC;YACH,UAAU,GAAG,CAAC,MAAM,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC;QACnE,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;IACH,CAAC;IAED,MAAM,EAAE,YAAY,EAAE,UAAU,EAAE,GAAG,iBAAiB,CAAC;QACrD,MAAM;QACN,KAAK;QACL,MAAM;QACN,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7C,GAAG,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnD,IAAI;KACL,CAAC,CAAC;IAEH,wEAAwE;IACxE,gDAAgD;IAChD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC;QAC1C,IAAI,EAAE,UAAU;QAChB,YAAY;QACZ,UAAU;KACX,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,yBAAyB,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC3D,OAAO;QACL,UAAU,EAAE,IAAI;QAChB,GAAG,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACtC,GAAG,EAAE,QAAQ,CAAC,OAAO;KACtB,CAAC;AACJ,CAAC"}

package/dist/core/runLoop.d.ts

@@ -0,0 +1,26 @@
+import type { AppConfig } from "../types/config.js";
+import type { LoopState, StepOutcome, StopReason } from "../types/run.js";
+/** Extra iterations beyond the pending count before the hard cap trips. */
+export declare const ITERATION_SLACK = 5;
+export interface RunLoopDeps {
+    /** Run one step; resolves to its outcome or throws on an initial-patch refusal. */
+    step: () => Promise<StepOutcome>;
+    config: AppConfig;
+    /** The number of pending subtasks at loop start (sets the cap). */
+    pendingCount: number;
+    /** Output sink (defaults to process.stdout.write); injectable for tests. */
+    print?: (line: string) => void;
+}
+export interface RunLoopResult {
+    /** The reason the loop stopped. */
+    stopReason: StopReason;
+    /** The accumulated loop state at stop. */
+    state: LoopState;
+    /** The number of steps that applied a patch. */
+    applied: number;
+}
+/** Map a thrown initial-patch error to the matching stop reason. */
+export declare function errorToStopReason(err: unknown): StopReason;
+/** A human-readable progress line for one completed step. */
+export declare function progressLine(state: LoopState, outcome: StepOutcome): string;
+export declare function runLoop(deps: RunLoopDeps): Promise<RunLoopResult>;

package/dist/core/runLoop.js

@@ -0,0 +1,103 @@
+/**
+ * `run` loop driver (HLD-SRD §3.13, §11.2; 0001_06).
+ *
+ * Loops the shared step core over the active task's pending subtasks, printing a
+ * per-step progress line, consulting the pure `decideStop` after each step, and
+ * enforcing a HARD iteration cap (`pending + slack`) as an infinite-loop guard
+ * on top of `decideStop`. The actual step runner is injected so the loop is
+ * fully offline-testable with a scripted core.
+ *
+ * Initial-patch refusals THROW from the step core (preserving the 0001_05 `step`
+ * behavior); the loop catches them and maps them to the matching `StopReason`
+ * so a single `step` and a looped `run` report stop conditions identically.
+ */
+import { decideStop } from "./stopConditions.js";
+import { ModelClientError } from "../types/model.js";
+import { CommandError, } from "./runStep.js";
+import { PatchValidationError, PatchApplyError, WorkingTreeUnsafeError, } from "./patchManager.js";
+/** Extra iterations beyond the pending count before the hard cap trips. */
+export const ITERATION_SLACK = 5;
+/** Map a thrown initial-patch error to the matching stop reason. */
+export function errorToStopReason(err) {
+    if (err instanceof ModelClientError)
+        return "model-unavailable";
+    if (err instanceof WorkingTreeUnsafeError)
+        return "unsafe-tree";
+    if (err instanceof PatchValidationError || err instanceof PatchApplyError) {
+        return "patch-invalid";
+    }
+    if (err instanceof CommandError) {
+        const m = err.message.toLowerCase();
+        if (m.includes("did not return a valid unified diff"))
+            return "unparseable-output";
+        if (m.includes("too many changed files"))
+            return "broad-rewrite-requested";
+        if (m.includes("mid-merge") || m.includes("working tree"))
+            return "unsafe-tree";
+        if (m.includes("refusing to apply"))
+            return "risky-change";
+        return "patch-invalid";
+    }
+    // Unknown error — surface as a generic patch-invalid stop (the loop stops,
+    // the message is printed by the caller). Re-throwing would crash the run.
+    return "patch-invalid";
+}
+/** A human-readable progress line for one completed step. */
+export function progressLine(state, outcome) {
+    const subtask = outcome.subtaskId ?? "(none)";
+    const applied = outcome.applied ? "applied" : "no-op";
+    const tests = outcome.testResults.length;
+    const failed = outcome.testResults.filter((r) => r.exitCode !== 0).length;
+    const testPart = tests === 0
+        ? "no tests"
+        : failed === 0
+            ? `${tests} test(s) passing`
+            : `${failed}/${tests} test(s) failing`;
+    const fixPart = outcome.fixAttempts > 0 ? `, ${outcome.fixAttempts} fix attempt(s)` : "";
+    return `Step ${state.iterations + 1}: ${subtask} — ${applied}, ${testPart}${fixPart}`;
+}
+export async function runLoop(deps) {
+    const print = deps.print ?? ((line) => process.stdout.write(line));
+    const state = { iterations: 0, consecutiveFailures: 0, filesChanged: 0 };
+    const cap = deps.pendingCount + ITERATION_SLACK;
+    let applied = 0;
+    while (state.iterations < cap) {
+        let outcome;
+        try {
+            outcome = await deps.step();
+        }
+        catch (err) {
+            const reason = errorToStopReason(err);
+            const message = err instanceof Error ? err.message : String(err);
+            print(`${message}\n`);
+            print(`Stopping run — ${reason}\n`);
+            return { stopReason: reason, state, applied };
+        }
+        print(progressLine(state, outcome) + "\n");
+        if (outcome.applied)
+            applied += 1;
+        const reason = decideStop(outcome, state, deps.config);
+        if (reason !== null) {
+            if (reason === "acceptance-met") {
+                print("Acceptance criteria met — no pending subtasks remain.\n");
+                print("Recommend: run `localptp summarize` (0001_07) to close the session.\n");
+            }
+            else {
+                print(`Stopping run — ${reason}\n`);
+            }
+            return { stopReason: reason, state, applied };
+        }
+        // Continue: advance the loop bookkeeping.
+        state.iterations += 1;
+        if (outcome.testResults.some((r) => r.exitCode !== 0)) {
+            state.consecutiveFailures += 1;
+        }
+        else {
+            state.consecutiveFailures = 0;
+        }
+    }
+    // Fell through the cap without a decideStop reason — the hard guard.
+    print(`Stopping run — iteration-cap-exceeded\n`);
+    return { stopReason: "iteration-cap-exceeded", state, applied };
+}
+//# sourceMappingURL=runLoop.js.map

package/dist/core/runLoop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runLoop.js","sourceRoot":"","sources":["../../src/core/runLoop.ts"],"names":[],"mappings":"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"}

package/dist/core/runStep.d.ts

@@ -0,0 +1,42 @@
+import { type Approver } from "./approval.js";
+import type { ModelClient } from "../types/model.js";
+import type { AppConfig } from "../types/config.js";
+import type { StepOutcome } from "../types/run.js";
+/** A command error that carries an exit code (preserves 0001_05 `step` behavior). */
+export declare class CommandError extends Error {
+    readonly exitCode: number;
+    constructor(message: string, exitCode?: number);
+}
+export interface NeedsContext {
+    files: string[];
+    reason: string;
+}
+export interface StepDeps {
+    cwd: string;
+    /** Injectable for tests; defaults to the real LM Studio client. */
+    clientFactory?: (config: AppConfig) => ModelClient;
+    /** Injectable approval seam; defaults to a TTY yes/no prompt. */
+    approve?: Approver;
+    /** Injectable clock for deterministic patch artifact names. */
+    now?: Date;
+}
+/**
+ * The canonical step result: the structured `StepOutcome` (read by the run loop)
+ * plus the extra fields the `step` command surfaces (`done`, `needsContext`,
+ * `patchPath`).
+ */
+export interface StepCoreResult extends StepOutcome {
+    /** True when there was no pending subtask (task done). */
+    done: boolean;
+    /** Set when the model returned a `needs_context` request instead of a diff. */
+    needsContext?: NeedsContext;
+    /** The saved patch artifact path of the coder patch (when applied). */
+    patchPath?: string;
+}
+/**
+ * Detect a `needs_context` response. Tolerant of fences/prose: scans for a JSON
+ * object carrying `"status":"needs_context"` and parses it. Returns the request
+ * (files + reason), or undefined when the response is not a needs_context.
+ */
+export declare function parseNeedsContext(raw: string): NeedsContext | undefined;
+export declare function runStep(deps: StepDeps): Promise<StepCoreResult>;