@mobrienv/autoloop-harness 0.7.4 → 0.9.1

package/dist/acceptance.d.ts

@@ -0,0 +1,31 @@
+import type { LoopContext } from "./types.js";
+export interface AcceptanceFailure {
+    command: string;
+    exitCode: number;
+    timedOut: boolean;
+    tail: string;
+}
+export interface AcceptanceResult {
+    /** False when no verify commands are configured (gate is a no-op). */
+    ran: boolean;
+    /** True when the gate ran and every command exited 0. */
+    passed: boolean;
+    failures: AcceptanceFailure[];
+}
+/**
+ * Run the out-of-band acceptance gate for a done-claim. The HARNESS executes
+ * each `verifyCmds` entry in a clean shell rooted at the work dir — never the
+ * agent's session — so the pass/fail status is captured harness-side and cannot
+ * be faked by a prompt. Returns `passed: true` (and `ran: false`) when no
+ * commands are configured, preserving prior completion behavior.
+ *
+ * Every command's exit code and output tail is journaled as a verification
+ * artifact regardless of outcome.
+ */
+export declare function runAcceptanceGate(loop: LoopContext, iteration: number): AcceptanceResult;
+/**
+ * Re-inject a failed acceptance gate's output as operator guidance so the next
+ * iteration's prompt carries the concrete failure instead of completing. This
+ * is the "do not complete; fix it" path of a deterministic gate.
+ */
+export declare function reinjectAcceptanceFailure(loop: LoopContext, iteration: number, result: AcceptanceResult): void;

package/dist/acceptance.js

@@ -0,0 +1,69 @@
+import { spawnSync } from "node:child_process";
+import { jsonBool, jsonField, jsonFieldRaw } from "@mobrienv/autoloop-core";
+import { appendEvent, appendOperatorEvent, } from "@mobrienv/autoloop-core/journal";
+import { lastNChars } from "./display.js";
+const TAIL_CHARS = 2000;
+/**
+ * Run the out-of-band acceptance gate for a done-claim. The HARNESS executes
+ * each `verifyCmds` entry in a clean shell rooted at the work dir — never the
+ * agent's session — so the pass/fail status is captured harness-side and cannot
+ * be faked by a prompt. Returns `passed: true` (and `ran: false`) when no
+ * commands are configured, preserving prior completion behavior.
+ *
+ * Every command's exit code and output tail is journaled as a verification
+ * artifact regardless of outcome.
+ */
+export function runAcceptanceGate(loop, iteration) {
+    const commands = loop.acceptance.verifyCmds;
+    const iter = String(iteration);
+    if (commands.length === 0) {
+        return { ran: false, passed: true, failures: [] };
+    }
+    appendEvent(loop.paths.journalFile, loop.runtime.runId, iter, "acceptance.start", jsonField("count", String(commands.length)));
+    const failures = [];
+    for (const command of commands) {
+        const res = spawnSync(command, {
+            shell: "/bin/sh",
+            cwd: loop.paths.workDir,
+            encoding: "utf-8",
+            timeout: loop.acceptance.timeoutMs,
+            maxBuffer: 50 * 1024 * 1024,
+        });
+        const timedOut = res.signal === "SIGTERM" ||
+            res.error?.code === "ETIMEDOUT";
+        const exitCode = timedOut ? 124 : (res.status ?? 1);
+        const tail = lastNChars(`${res.stdout ?? ""}${res.stderr ?? ""}`, TAIL_CHARS);
+        appendEvent(loop.paths.journalFile, loop.runtime.runId, iter, "acceptance.command", jsonField("command", command) +
+            ", " +
+            jsonField("exit_code", String(exitCode)) +
+            ", " +
+            jsonFieldRaw("timed_out", jsonBool(timedOut)) +
+            ", " +
+            jsonField("output_tail", tail));
+        if (exitCode !== 0) {
+            failures.push({ command, exitCode, timedOut, tail });
+        }
+    }
+    const passed = failures.length === 0;
+    appendEvent(loop.paths.journalFile, loop.runtime.runId, iter, "acceptance.result", jsonFieldRaw("passed", jsonBool(passed)) +
+        ", " +
+        jsonField("failed", String(failures.length)) +
+        ", " +
+        jsonField("total", String(commands.length)));
+    return { ran: true, passed, failures };
+}
+/**
+ * Re-inject a failed acceptance gate's output as operator guidance so the next
+ * iteration's prompt carries the concrete failure instead of completing. This
+ * is the "do not complete; fix it" path of a deterministic gate.
+ */
+export function reinjectAcceptanceFailure(loop, iteration, result) {
+    const detail = result.failures
+        .map((f) => `- \`${f.command}\` exited ${f.exitCode}${f.timedOut ? " (timed out)" : ""}:\n${f.tail}`)
+        .join("\n\n");
+    const message = "Completion was blocked: the harness acceptance gate failed. " +
+        "Do not announce completion until every verify command passes. " +
+        `Failing command(s):\n\n${detail}`;
+    appendOperatorEvent(loop.paths.journalFile, loop.runtime.runId, String(iteration), "operator.guidance", message);
+}
+//# sourceMappingURL=acceptance.js.map

package/dist/acceptance.js.map

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

package/dist/ask.d.ts

@@ -0,0 +1,16 @@
+export interface AwaitResponseOptions {
+    /** Run state dir (loop.paths.stateDir) — control requests live under it. */
+    stateDir: string;
+    runId: string;
+    questionId: string;
+    timeoutMs: number;
+    pollMs?: number;
+    signal?: AbortSignal;
+}
+/**
+ * Block until a `respond` control request matching `questionId` appears, the
+ * timeout elapses, or the run is aborted. Returns the answer string, or `null`
+ * on timeout/abort. `questionId` is unique per ask, so any pre-existing respond
+ * requests for other questions are naturally ignored.
+ */
+export declare function awaitHumanResponse(opts: AwaitResponseOptions): Promise<string | null>;

package/dist/ask.js

@@ -0,0 +1,47 @@
+// Blocking human-in-the-loop: pause the loop until an operator responds.
+//
+// autoloop is turn-based, so HITL maps cleanly to *between-iteration* blocking:
+// an agent emits the reserved ask event, the harness journals `ask.pending` and
+// blocks here until a matching `respond` control request arrives (the same
+// channel `autoloop control respond` writes to) or the timeout elapses, then
+// injects the answer into the next prompt as guidance. This lets an external
+// supervisor (e.g. ralph relaying a Telegram reply) drive HITL over the
+// subprocess engine without a mid-turn hook.
+import { appendStatus, readRequests } from "./control/queue.js";
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Block until a `respond` control request matching `questionId` appears, the
+ * timeout elapses, or the run is aborted. Returns the answer string, or `null`
+ * on timeout/abort. `questionId` is unique per ask, so any pre-existing respond
+ * requests for other questions are naturally ignored.
+ */
+export async function awaitHumanResponse(opts) {
+    const pollMs = opts.pollMs && opts.pollMs > 0 ? opts.pollMs : 500;
+    const deadline = Date.now() + Math.max(0, opts.timeoutMs);
+    for (;;) {
+        if (opts.signal?.aborted)
+            return null;
+        const match = readRequests(opts.stateDir).find((r) => r.verb === "respond" &&
+            r.runId === opts.runId &&
+            r.payload.questionId === opts.questionId);
+        if (match) {
+            // Ack so the consumed response does not linger as a pending request.
+            appendStatus(opts.stateDir, {
+                id: match.id,
+                runId: match.runId,
+                verb: "respond",
+                state: "applied",
+                at: new Date().toISOString(),
+                detail: "delivered to human-ask",
+            });
+            return match.payload.answer;
+        }
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            return null;
+        await sleep(Math.min(pollMs, remaining));
+    }
+}
+//# sourceMappingURL=ask.js.map

package/dist/ask.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ask.js","sourceRoot":"","sources":["../src/ask.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,EAAE;AACF,gFAAgF;AAChF,gFAAgF;AAChF,2EAA2E;AAC3E,6EAA6E;AAC7E,6EAA6E;AAC7E,wEAAwE;AACxE,6CAA6C;AAE7C,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGhE,SAAS,KAAK,CAAC,EAAU;IACvB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC3D,CAAC;AAYD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,IAA0B;IAE1B,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC;IAClE,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;IAE1D,SAAS,CAAC;QACR,IAAI,IAAI,CAAC,MAAM,EAAE,OAAO;YAAE,OAAO,IAAI,CAAC;QAEtC,MAAM,KAAK,GAAG,YAAY,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,CAC5C,CAAC,CAAC,EAAE,EAAE,CACJ,CAAC,CAAC,IAAI,KAAK,SAAS;YACpB,CAAC,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK;YACrB,CAAC,CAAC,OAA0B,CAAC,UAAU,KAAK,IAAI,CAAC,UAAU,CAC/D,CAAC;QACF,IAAI,KAAK,EAAE,CAAC;YACV,qEAAqE;YACrE,YAAY,CAAC,IAAI,CAAC,QAAQ,EAAE;gBAC1B,EAAE,EAAE,KAAK,CAAC,EAAE;gBACZ,KAAK,EAAE,KAAK,CAAC,KAAK;gBAClB,IAAI,EAAE,SAAS;gBACf,KAAK,EAAE,SAAS;gBAChB,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;gBAC5B,MAAM,EAAE,wBAAwB;aACjC,CAAC,CAAC;YACH,OAAQ,KAAK,CAAC,OAA0B,CAAC,MAAM,CAAC;QAClD,CAAC;QAED,MAAM,SAAS,GAAG,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACxC,IAAI,SAAS,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;QAChC,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;IAC3C,CAAC;AACH,CAAC"}

package/dist/backend/types.d.ts

@@ -0,0 +1,16 @@
+import type { LoopContext } from "../types.js";
+export interface ResolvedIterationBackend {
+    kind: string;
+    provider: string;
+    command: string;
+    args: string[];
+    promptMode: string;
+    timeoutMs: number;
+    trustAllTools: boolean;
+    agent: string;
+    model: string;
+    profile: string;
+    disallowedTools: string[];
+    usageFrom: string;
+}
+export declare function resolvedFromLoopBackend(loop: LoopContext): ResolvedIterationBackend;

package/dist/backend/types.js

@@ -0,0 +1,17 @@
+export function resolvedFromLoopBackend(loop) {
+    return {
+        kind: loop.backend.kind,
+        provider: loop.backend.provider,
+        command: loop.backend.command,
+        args: [...loop.backend.args],
+        promptMode: loop.backend.promptMode,
+        timeoutMs: loop.backend.timeoutMs,
+        trustAllTools: loop.backend.trustAllTools,
+        agent: loop.backend.agent,
+        model: loop.backend.model,
+        profile: loop.backend.profile ?? "",
+        disallowedTools: [...(loop.backend.disallowedTools ?? [])],
+        usageFrom: loop.backend.usageFrom ?? "",
+    };
+}
+//# sourceMappingURL=types.js.map

package/dist/backend/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/backend/types.ts"],"names":[],"mappings":"AAiBA,MAAM,UAAU,uBAAuB,CACrC,IAAiB;IAEjB,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI;QACvB,QAAQ,EAAE,IAAI,CAAC,OAAO,CAAC,QAAQ;QAC/B,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO;QAC7B,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;QAC5B,UAAU,EAAE,IAAI,CAAC,OAAO,CAAC,UAAU;QACnC,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,SAAS;QACjC,aAAa,EAAE,IAAI,CAAC,OAAO,CAAC,aAAa;QACzC,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,KAAK;QACzB,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,KAAK;QACzB,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE;QACnC,eAAe,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,eAAe,IAAI,EAAE,CAAC,CAAC;QAC1D,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,SAAS,IAAI,EAAE;KACxC,CAAC;AACJ,CAAC"}

package/dist/circuit-breaker.d.ts

@@ -0,0 +1,27 @@
+import type { BackendErrorClass } from "@mobrienv/autoloop-backends";
+import type { StopReason } from "./types.js";
+export interface CircuitDecision {
+    /** `pause`: back off and retry the run; `stop`: terminate with `reason`. */
+    action: "pause" | "stop";
+    /**
+     * Typed stop reason to journal (also used as the pause's error class).
+     * Narrowed to the subset of `StopReason` this classifier can produce.
+     */
+    reason: Extract<StopReason, "auth_failed" | "quota_exhausted" | "rate_limited" | "transient_error" | "backend_failed">;
+}
+/**
+ * Circuit-breaker policy for a classified backend error. Non-retryable classes
+ * (auth/quota) stop immediately with a typed reason. Retryable classes
+ * (rate-limit/transient) pause-and-retry rather than fast-failing, until the
+ * breaker opens after `maxPauses` pauses — then they stop with the typed reason
+ * instead of being laundered into a confident verdict or a generic failure.
+ */
+export declare function circuitDecision(errorClass: BackendErrorClass, transientPauseCount: number, maxPauses: number): CircuitDecision;
+/** How many transient pauses this run has already taken (breaker memory). */
+export declare function countTransientPauses(runLines: string[]): number;
+/**
+ * Exponential backoff for the retry ladder: `base * 2^(attempt-1)`, clamped to
+ * `cap` and never negative. `attempt` is 1-indexed (the first retry waits
+ * `base`). A `base` of 0 disables the wait entirely (used in tests).
+ */
+export declare function backoffDelayMs(attempt: number, baseMs: number, capMs: number): number;

package/dist/circuit-breaker.js

@@ -0,0 +1,41 @@
+import { extractTopic } from "@mobrienv/autoloop-core/journal";
+/**
+ * Circuit-breaker policy for a classified backend error. Non-retryable classes
+ * (auth/quota) stop immediately with a typed reason. Retryable classes
+ * (rate-limit/transient) pause-and-retry rather than fast-failing, until the
+ * breaker opens after `maxPauses` pauses — then they stop with the typed reason
+ * instead of being laundered into a confident verdict or a generic failure.
+ */
+export function circuitDecision(errorClass, transientPauseCount, maxPauses) {
+    switch (errorClass) {
+        case "auth_failed":
+            return { action: "stop", reason: "auth_failed" };
+        case "quota_exhausted":
+            return { action: "stop", reason: "quota_exhausted" };
+        case "rate_limited":
+        case "transient_error":
+            return transientPauseCount >= maxPauses
+                ? { action: "stop", reason: errorClass }
+                : { action: "pause", reason: errorClass };
+        default:
+            // An unclassified failure is a plain backend failure.
+            return { action: "stop", reason: "backend_failed" };
+    }
+}
+/** How many transient pauses this run has already taken (breaker memory). */
+export function countTransientPauses(runLines) {
+    return runLines.filter((l) => extractTopic(l) === "backend.transient").length;
+}
+/**
+ * Exponential backoff for the retry ladder: `base * 2^(attempt-1)`, clamped to
+ * `cap` and never negative. `attempt` is 1-indexed (the first retry waits
+ * `base`). A `base` of 0 disables the wait entirely (used in tests).
+ */
+export function backoffDelayMs(attempt, baseMs, capMs) {
+    if (baseMs <= 0)
+        return 0;
+    const n = Math.max(1, Math.floor(attempt));
+    const delay = baseMs * 2 ** (n - 1);
+    return Math.min(Math.max(0, capMs), delay);
+}
+//# sourceMappingURL=circuit-breaker.js.map

package/dist/circuit-breaker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.js","sourceRoot":"","sources":["../src/circuit-breaker.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAoB/D;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAC7B,UAA6B,EAC7B,mBAA2B,EAC3B,SAAiB;IAEjB,QAAQ,UAAU,EAAE,CAAC;QACnB,KAAK,aAAa;YAChB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC;QACnD,KAAK,iBAAiB;YACpB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC;QACvD,KAAK,cAAc,CAAC;QACpB,KAAK,iBAAiB;YACpB,OAAO,mBAAmB,IAAI,SAAS;gBACrC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE;gBACxC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;QAC9C;YACE,sDAAsD;YACtD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC;IACxD,CAAC;AACH,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,oBAAoB,CAAC,QAAkB;IACrD,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC,KAAK,mBAAmB,CAAC,CAAC,MAAM,CAAC;AAChF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAC5B,OAAe,EACf,MAAc,EACd,KAAa;IAEb,IAAI,MAAM,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IAC1B,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;IAC3C,MAAM,KAAK,GAAG,MAAM,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACpC,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC;AAC7C,CAAC"}

package/dist/completion-lint.d.ts

@@ -0,0 +1,29 @@
+export interface CompletionContractInput {
+    /** Completion promise string (stdout fallback). */
+    promise: string;
+    /** Completion event topic. */
+    event: string;
+    /** Required-evidence events that must precede completion. */
+    requiredEvents: string[];
+    /** Out-of-band acceptance verify commands. */
+    verifyCmds: string[];
+    /** Intent-binding acceptance criteria (may bind `text :: cmd` checks). */
+    criteria: string[];
+}
+export interface ContractLintFinding {
+    level: "warn" | "info";
+    rule: string;
+    message: string;
+}
+/**
+ * Does the contract have ANY deterministic, harness-checkable completion
+ * condition (verify command, required event, or a criterion-bound check)? If
+ * not, completion is self-asserted with nothing to falsify it.
+ */
+export declare function hasDeterministicCheck(c: CompletionContractInput): boolean;
+/**
+ * Lint a completion contract for falsifiability and triviality BEFORE a run
+ * burns iterations on a bad stop condition. Returns [] for a well-formed
+ * contract; warnings for trivial/un-falsifiable ones.
+ */
+export declare function lintCompletionContract(c: CompletionContractInput): ContractLintFinding[];

package/dist/completion-lint.js

@@ -0,0 +1,51 @@
+import { parseCriterion } from "./intent.js";
+// Trivial promise strings an agent can satisfy incidentally.
+const TRIVIAL_PROMISE = /^(done|ok|okay|complete|completed|finished|yes|true|success)$/i;
+/**
+ * Does the contract have ANY deterministic, harness-checkable completion
+ * condition (verify command, required event, or a criterion-bound check)? If
+ * not, completion is self-asserted with nothing to falsify it.
+ */
+export function hasDeterministicCheck(c) {
+    if (c.verifyCmds.length > 0)
+        return true;
+    if (c.requiredEvents.length > 0)
+        return true;
+    return c.criteria.some((line) => parseCriterion(line).check !== undefined);
+}
+/**
+ * Lint a completion contract for falsifiability and triviality BEFORE a run
+ * burns iterations on a bad stop condition. Returns [] for a well-formed
+ * contract; warnings for trivial/un-falsifiable ones.
+ */
+export function lintCompletionContract(c) {
+    const findings = [];
+    const deterministic = hasDeterministicCheck(c);
+    if (!deterministic) {
+        findings.push({
+            level: "warn",
+            rule: "unfalsifiable_completion",
+            message: "Completion has no deterministic check — the agent can satisfy it without proof. Add acceptance.verify_cmds, event_loop.required_events, or a criterion-bound check (`text :: cmd`).",
+        });
+    }
+    // A trivial promise is only a real hazard when nothing else gates completion
+    // (otherwise the deterministic check backs it up).
+    if (c.promise && !deterministic && TRIVIAL_PROMISE.test(c.promise.trim())) {
+        findings.push({
+            level: "warn",
+            rule: "trivial_promise",
+            message: `Completion promise "${c.promise}" is trivially printable; the agent can emit it without doing the work. Use a distinctive promise plus a deterministic check.`,
+        });
+    }
+    // Criteria present but all advisory — they won't gate completion.
+    if (c.criteria.length > 0 &&
+        !c.criteria.some((line) => parseCriterion(line).check !== undefined)) {
+        findings.push({
+            level: "info",
+            rule: "advisory_criteria_only",
+            message: "Acceptance criteria are advisory only (no `::` checks); they are recorded but do not gate completion. Bind a check to enforce them.",
+        });
+    }
+    return findings;
+}
+//# sourceMappingURL=completion-lint.js.map

package/dist/completion-lint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion-lint.js","sourceRoot":"","sources":["../src/completion-lint.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAqB7C,6DAA6D;AAC7D,MAAM,eAAe,GACnB,gEAAgE,CAAC;AAEnE;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,CAA0B;IAC9D,IAAI,CAAC,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACzC,IAAI,CAAC,CAAC,cAAc,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAC7C,OAAO,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC;AAC7E,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CACpC,CAA0B;IAE1B,MAAM,QAAQ,GAA0B,EAAE,CAAC;IAC3C,MAAM,aAAa,GAAG,qBAAqB,CAAC,CAAC,CAAC,CAAC;IAE/C,IAAI,CAAC,aAAa,EAAE,CAAC;QACnB,QAAQ,CAAC,IAAI,CAAC;YACZ,KAAK,EAAE,MAAM;YACb,IAAI,EAAE,0BAA0B;YAChC,OAAO,EACL,qLAAqL;SACxL,CAAC,CAAC;IACL,CAAC;IAED,6EAA6E;IAC7E,mDAAmD;IACnD,IAAI,CAAC,CAAC,OAAO,IAAI,CAAC,aAAa,IAAI,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;QAC1E,QAAQ,CAAC,IAAI,CAAC;YACZ,KAAK,EAAE,MAAM;YACb,IAAI,EAAE,iBAAiB;YACvB,OAAO,EAAE,uBAAuB,CAAC,CAAC,OAAO,+HAA+H;SACzK,CAAC,CAAC;IACL,CAAC;IAED,kEAAkE;IAClE,IACE,CAAC,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC;QACrB,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,KAAK,KAAK,SAAS,CAAC,EACpE,CAAC;QACD,QAAQ,CAAC,IAAI,CAAC;YACZ,KAAK,EAAE,MAAM;YACb,IAAI,EAAE,wBAAwB;YAC9B,OAAO,EACL,qIAAqI;SACxI,CAAC,CAAC;IACL,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/config-helpers.d.ts

@@ -1,20 +1,28 @@
 import * as config from "@mobrienv/autoloop-core/config";
 import * as topo from "@mobrienv/autoloop-core/topology";
 import type { LoopContext, RunOptions } from "./types.js";
-export declare function resolvePrompt(projectDir: string, cfg: config.Config, override: string | null): string;
+export interface ResolvePromptOptions {
+    workDir?: string;
+    stateDir?: string;
+    baseStateDir?: string;
+}
+export declare function resolvePrompt(projectDir: string, cfg: config.Config, override: string | null, options?: ResolvePromptOptions): string;
 export declare function resolveReviewPrompt(projectDir: string, cfg: config.Config): string;
 export declare function readOptionalProjectFile(projectDir: string, relativePath: string): string;
 export declare function resolveReviewEvery(cfg: config.Config, topoData: topo.Topology): number;
 export declare function truthySetting(value: string): boolean;
 export declare function ensureLayout(stateDir: string): void;
 export declare function installRuntimeTools(loop: LoopContext): void;
-export declare function resolveProcessKind(kind: string, command: string): string;
+export declare function resolveProcessKind(kind: string, command: string, opts?: {
+    hasCustomArgs?: boolean;
+}): string;
 export declare function normalizePromptMode(value: string): string;
 export declare function configListWithFallback(cfg: config.Config, key: string, fallback: string[]): string[];
 export declare function injectClaudePermissions(command: string, args: string[]): string[];
 export declare function processStringOverride(override: Record<string, unknown>, key: string, fallback: string): string;
 export declare function processListOverride(override: Record<string, unknown>, key: string, fallback: string[]): string[];
 export declare function processIntOverride(override: Record<string, unknown>, key: string, fallback: number): number;
+export declare function processBoolOverride(override: Record<string, unknown>, key: string, fallback: boolean): boolean;
 export declare function claudeBackend(command: string): boolean;
 export declare function nextRunId(path: string, cfg: config.Config): string;
 export declare function iterationFieldForRun(journalFile: string, runId: string, iteration: string, topic: string, field: string): string;