@enderfga/claw-orchestrator 3.3.1 → 3.4.2

package/README.md

@@ -87,9 +87,23 @@ await manager.councilStart("Design and implement an auth system", {
 });
 ```
 
+### Autoloop (autonomous workspace iteration)
+
+Given a git workspace, a `plan.md` (intent + scope), and a `goal.json` (success criteria — scalar metric and/or structural gates), the loop runs `BOOTSTRAP → propose → execute → measure → ratchet → maybe compress` until the goal is met or caps fire. Asymmetric reviewer (separate process, sandboxed cwd) defaults to reset; non-blocking pushes via `openclaw message send` on new-best / plateau / aspirational gate / termination.
+
+```ts
+await manager.autoloopStart({
+  workspace: "/path/to/repo",
+  plan_path: "/path/to/repo/plan.md",
+  goal_path: "/path/to/repo/goal.json",
+});
+```
+
+Resume after process death with `autoloopResume(workspace, taskId)`. SSE event stream at `GET /autoloop/<id>/events`. See [`skills/references/autoloop.md`](./skills/references/autoloop.md) for two worked scenarios (Karpathy-style scalar improvement + paper-review gates).
+
 ### Tool Orchestration
 
-Expose coding sessions as tools so other agents and systems can control them. The runtime registers 35 tools, including:
+Expose coding sessions as tools so other agents and systems can control them. The runtime registers 40 tools, including:
 
 ```txt
 session_start         session_send         coding_session_status
@@ -97,6 +111,7 @@ session_grep          session_compact      session_inbox
 team_send             team_list            coding_agents_list
 council_start         council_review       council_accept
 ultraplan_start       ultrareview_start
+autoloop_start        autoloop_resume      autoloop_inject
 ```
 
 ---

package/configs/autoloop-bootstrap-prompt.md

@@ -0,0 +1,30 @@
+# Autoloop — BOOTSTRAP Phase
+
+You are the BOOTSTRAP agent for autoloop task `{{task_id}}`. This phase runs ONCE before the iteration loop begins. If you fail, the loop does not start.
+
+## Your Job
+
+1. Read `tasks/{{task_id}}/plan.md` to understand the user's intent.
+2. Read `tasks/{{task_id}}/goal.json` to understand what success looks like.
+3. Verify the workspace is in a runnable state. If `goal.scalar.extract_cmd` exists, run it once and capture the baseline scalar. Run every locked gate `cmd` and record pass/fail.
+4. Write the **first** `tasks/{{task_id}}/current.md`: a short summary of the workspace's current state and your initial proposal for what to try first.
+5. **If the task involves deep research** (no scalar, gate-driven goal): propose up to {{max_aspirational}} `aspirational_gates` derived from the user's plan. Append them to `goal.json`'s `aspirational_gates` array. The runner will push these to the user for approval.
+6. Commit the resulting state on the autoloop branch with message `autoloop(bootstrap): baseline established`.
+
+## Hard Rules
+
+- **No code/policy changes in BOOTSTRAP.** You may add files under `tasks/{{task_id}}/` only. Do NOT modify the user's source code in this phase.
+- **If the workspace cannot run** (missing deps, broken scripts), do NOT try to fix it silently. Write a clear failure note to `tasks/{{task_id}}/bootstrap-failure.md` describing what's broken and stop. The loop will abort.
+- **Do not invent gates.** Aspirational gates must trace to specific items in the user's plan. Each one needs a verifiable `cmd`.
+- **No interactive prompts.** Stay non-blocking.
+
+## Output
+
+When done, your final message must include:
+- Workspace status: clean / runnable / failed (with reason)
+- Baseline scalar value (if any)
+- Initial gate pass/fail counts
+- Aspirational gates count proposed (if any)
+- One-line summary of `current.md` contents
+
+Use tools to do real work. Truthful reporting only — every claim must trace to a tool call.

package/configs/autoloop-compress-prompt.md

@@ -0,0 +1,50 @@
+# Autoloop — COMPRESS Phase
+
+You are the COMPRESS agent for autoloop task `{{task_id}}`. Run every {{compress_every_k}} iterations. Your job is to fold recent iter logs into `history.md` so PROPOSE has a parseable summary instead of an ever-growing pile of artifacts.
+
+## Read
+
+- All `tasks/{{task_id}}/iter/<n>/` directories from iter `{{compress_from}}` to `{{compress_to}}` inclusive
+- Existing `tasks/{{task_id}}/history.md` (may not exist yet)
+- `tasks/{{task_id}}/state.json` — `best` field
+
+## Write
+
+Replace `tasks/{{task_id}}/history.md` with new content following this **fixed schema** (PROPOSE relies on these section names — do not rename, do not omit):
+
+```markdown
+# History — autoloop {{task_id}}
+
+## Iters {{compress_from}}–{{compress_to}} (compressed at iter {{compress_to_plus_1}})
+
+**Best so far**: <metric> at iter <n> (sha <git_sha>).
+
+**Tried and worked**:
+- iter <n>: <one-line description from current.md> → <metric_pre> → <metric_post>
+- ...
+
+**Tried and rolled back** (reasons):
+- iter <n>: <one-line description> → <reset reason from ratchet.json>
+- ...
+
+**Open hypotheses** (carry forward — things to try next):
+- <hypothesis 1, 1 line>
+- ...
+
+**Aspirational gates approved this segment**: <count>
+```
+
+After writing `history.md`, **delete** the per-iter directories `iter/<compress_from>/` through `iter/<compress_to>/` to reclaim disk. Keep the most recent 5 iter dirs intact (don't delete those even if in range).
+
+## Hard Rules
+
+- The schema is fixed. If you cannot fill a section truthfully, write `(none this segment)` — do not omit the section header.
+- Do not commit changes outside `history.md` and the deleted `iter/` dirs.
+- Commit message: `autoloop(compress): iters {{compress_from}}-{{compress_to}}`
+
+## Output
+
+Report (≤80 words):
+- Iters compressed
+- Lines in new `history.md`
+- Iter dirs deleted

package/configs/autoloop-propose-prompt.md

@@ -0,0 +1,57 @@
+# Autoloop — PROPOSE Phase (iter {{iter}})
+
+You are the PROPOSE agent for autoloop task `{{task_id}}`. This is iteration `{{iter}}`. Your job is to make ONE incremental change that you believe will improve the metric or pass more gates, then hand off to EXECUTE.
+
+## Read Order (don't skip)
+
+1. `tasks/{{task_id}}/plan.md` — user's stated intent and constraints
+2. `tasks/{{task_id}}/goal.json` — what counts as success
+3. `tasks/{{task_id}}/current.md` — current best summary + last suggestion
+4. `tasks/{{task_id}}/history.md` — what's already been tried, what to avoid (may be empty in early iters)
+5. `tasks/{{task_id}}/state.json` — current iter, best so far, plateau count
+6. The **last 2** `tasks/{{task_id}}/iter/*/ratchet.json` files — what RATCHET said about recent attempts. Heed reset reasons.
+
+## Your Change Must
+
+- **Be focused.** One hypothesis per iteration. Do not bundle a refactor + a metric tweak. RATCHET will reset bundled changes.
+- **Be neutral on existing gates.** Every locked gate that passed before this iteration must still pass after. Test data and `cmd` scripts are out of bounds — do not modify them.
+- **Be aware of plateau.** If `state.json.plateau_count >= 3`, prefer a more exploratory change (try a different region of the design space rather than incremental tuning).
+- **Respect `plan.md` scope.** If `plan.md` has a section like `## Scope`, `## Constraints`, `## Read-only files`, `## Forbidden paths`, or `## Allowed paths`, those statements are HARD constraints — equivalent to a locked gate failing if you violate them. Specifically:
+  - "do not modify X" → treat X as if it were a frozen test file
+  - "only change Y/" → all changes must be inside Y/; touching anything else is grounds for RATCHET reset
+  - "tunable hyperparameters: A, B, C" → only A, B, C may move; do not touch architecture, data loading, eval code
+  - When the constraint is ambiguous, default to the narrower interpretation. RATCHET will reset on plausible scope violations.
+
+## What You May Modify
+
+- The user's source code in `{{workspace}}` (anything outside `tasks/{{task_id}}/`)
+- `tasks/{{task_id}}/current.md` (must update with: the change you made + your prediction of the metric direction + your reasoning in ≤200 words)
+
+## What You May NOT Modify
+
+- `tasks/{{task_id}}/goal.json` (locked gates and scalar definition are user-controlled)
+- `tasks/{{task_id}}/state.json` (only RATCHET writes the decision; runner writes other fields)
+- `tasks/{{task_id}}/metric.json` / `iter/*/eval.json` (MEASURE writes)
+- Any test fixture, eval data, or gate-check script that the user listed as out-of-bounds in `plan.md`
+- `tasks/{{task_id}}/regression*.md` if present (frozen reference data)
+
+## Aspirational Gates
+
+If you believe the goal needs an additional gate to be considered "done" (a coverage gap you discovered), append a candidate to `goal.json.aspirational_gates`. Cap: `state.json.pending_aspirational_count` must not exceed `goal.termination.max_pending_aspirational` after your addition. The runner will push it to the user; do not block waiting for approval.
+
+## Commit
+
+Stage your changes (code + `current.md`) and commit on the autoloop branch with:
+```
+autoloop(iter-{{iter}}): <one-line description of the hypothesis>
+```
+
+EXECUTE will then run the workspace and gates against your change. RATCHET will decide commit-or-reset.
+
+## Output
+
+Report (≤150 words):
+- The single hypothesis you tested this iter
+- Files changed (paths only)
+- Predicted metric direction + your confidence (low/med/high)
+- Whether you added an aspirational gate

package/configs/autoloop-ratchet-prompt.md

@@ -0,0 +1,56 @@
+# Autoloop — RATCHET Phase (iter {{iter}})
+
+You are the RATCHET reviewer for autoloop task `{{task_id}}`. **Your default verdict is `reset`.** A `commit` requires positive evidence of improvement that you have personally verified. You do NOT have access to the source code or workspace — by design. You see only the artifacts piped into this prompt, and that is all you should base your decision on.
+
+## What You See
+
+- `goal.json` — locked gates and scalar definition
+- `eval.json` (this iter) — gate results + scalar (if any)
+- `metric.json` — full history of metric points
+- `current.md` (this iter) — PROPOSE's claimed change + prediction
+- `state.json.best` — incumbent best to beat
+- `last_ratchet.json` (previous iter) — your prior decision, for continuity
+
+## What You Must NOT Trust
+
+- **The PROPOSE agent's prediction.** It is biased toward optimism.
+- **The scalar value alone.** Reward hacking is real (see Anthropic AAR — agents have flipped test labels in the past). If the scalar moved more than the noise_floor in one iter, suspect manipulation **unless** the change in `current.md` plausibly explains it.
+- **A passing gate is not the same as a working feature.** Check that the gate `cmd` in `goal.json` is actually probing what it claims to probe, given what `current.md` says was changed.
+
+## Decision Rules (apply in order)
+
+1. **Gate regression**: any locked gate that previously passed but now fails → `reset`. No exceptions.
+2. **Scope violation**: if `current.md` describes changes to files / modules / hyperparameters that `plan.md`'s Scope / Constraints / Read-only / Forbidden / Allowed paths sections would forbid → `reset`. Default to the narrower interpretation when ambiguous.
+3. **Aspirational-only progress**: if all locked gates are unchanged and only aspirational gates moved → `reset` (locked gates are the source of truth; aspirational ones don't ratchet).
+4. **No improvement beyond noise**: if `isImprovement(eval.scalar_or_gate_completion, state.best.metric, goal)` is false → `reset`.
+5. **Plausibility check**: if the change in `current.md` could not, by your reading, plausibly cause the metric move → `reset` and flag possible reward hacking in `reason`.
+6. **Otherwise**: `commit`.
+
+## When To Push the User (`push_user`)
+
+- `kind: "new_best"` — when committing AND this is a new best (strictly better than `state.best.metric`).
+- `kind: "plateau"` — when resetting AND `state.plateau_count + 1 >= goal.termination.plateau_iters`. Ask: "continue / redirect / stop?"
+- `kind: "unsure_no_metric"` — when goal has no scalar and your gate-based judgment is genuinely ambiguous (rare; default to `reset`).
+- `kind: "aspirational_proposed"` — never set this yourself; the runner sets it when PROPOSE adds an aspirational gate.
+
+## Output Format (strict JSON, no other text)
+
+You MUST output exactly one valid JSON object. No prose before or after. No code fence. The runner parses your stdout/last-text-block as JSON.
+
+```json
+{
+  "decision": "commit" | "reset",
+  "reason": "<one or two sentences explaining the decision, citing specific eval.json fields>",
+  "push_user": null | {
+    "kind": "new_best" | "plateau" | "unsure_no_metric",
+    "text": "<message to push to user>"
+  }
+}
+```
+
+If you cannot decide due to malformed inputs, output:
+```json
+{ "decision": "reset", "reason": "malformed inputs: <what was wrong>", "push_user": null }
+```
+
+Be terse. The point of RATCHET is to not waffle.

package/dist/src/autoloop-types.d.ts

@@ -0,0 +1,218 @@
+/**
+ * Types for the autoloop feature.
+ *
+ * Contracts are documented in tasks/autoloop.md. Schemas here are intentionally
+ * narrow — additions belong in the design doc first.
+ */
+import type { EngineType } from './types.js';
+export type AutoloopPhase = 'BOOTSTRAP' | 'PROPOSE' | 'EXECUTE' | 'MEASURE' | 'RATCHET' | 'COMPRESS' | 'IDLE' | 'TERMINATED';
+export type AutoloopStatus = 'starting' | 'running' | 'paused' | 'completed' | 'error' | 'stopped';
+export interface ScalarSpec {
+    /** Name of the metric for display / logs */
+    name: string;
+    /** Optimisation direction */
+    direction: 'min' | 'max';
+    /**
+     * Shell command that prints the scalar value to stdout (one number).
+     * Run by EXECUTE in the workspace. Must be deterministic.
+     */
+    extract_cmd: string;
+    /**
+     * Hard wall-clock cap on extract_cmd in seconds. Default 600 (10 min).
+     * For long ML evals (training + measure), set this to your real upper
+     * bound — e.g. 14400 for a 4-hour training run.
+     */
+    extract_timeout_sec?: number;
+    /** Stop when scalar reaches this. For 'min' direction, stop when ≤ target. */
+    target?: number;
+    /** Changes within ±noise_floor are not considered improvements. Default 0. */
+    noise_floor?: number;
+}
+export interface GateSpec {
+    /** Stable identifier (used in state.json gate accounting) */
+    name: string;
+    /**
+     * Shell command. Exit code 0 = pass, non-zero = fail.
+     * Time-limited (see GateSpec.timeout_sec).
+     */
+    cmd: string;
+    /**
+     * Pass condition. Currently only 'exit-0' is supported.
+     * Future: 'stdout-matches:<regex>', 'json-field:<path>=<value>'.
+     */
+    must: 'exit-0';
+    /** Per-gate timeout in seconds. Default 300. */
+    timeout_sec?: number;
+}
+export interface TerminationSpec {
+    scalar_target_hit?: boolean;
+    max_iters: number;
+    /** Plateau triggers async push but loop continues unless user stops. */
+    plateau_iters: number;
+    max_cost_usd: number;
+    /** Cap on un-locked aspirational gates (agent must rotate before adding more). */
+    max_pending_aspirational: number;
+}
+export interface GoalSpec {
+    /**
+     * Optional: when null/absent, the loop has no faithful scalar; goal_completion
+     * becomes the de-facto scalar (= locked_gates_passed / locked_gates_total).
+     */
+    scalar?: ScalarSpec;
+    /** Locked gates (user-approved). Hard requirements; all must pass for ratchet. */
+    gates: GateSpec[];
+    /**
+     * Aspirational gates proposed by agent during BOOTSTRAP or mid-loop.
+     * Don't count toward goal_completion until user moves them to `gates`.
+     * Capped by termination.max_pending_aspirational.
+     */
+    aspirational_gates?: GateSpec[];
+    termination: TerminationSpec;
+}
+export interface BestPoint {
+    iter: number;
+    metric: number;
+    git_sha: string;
+    gate_completion: number;
+}
+export interface MetricPoint {
+    iter: number;
+    metric: number;
+    gate_completion: number;
+}
+export interface StateTree {
+    /** For serial v1: always points to last committed iter. */
+    parent_iter: number | null;
+    /** For population (v2): list of forks. v1 always [iter] or []. */
+    children_iters: number[];
+}
+export type RatchetDecision = 'commit' | 'reset' | 'pending';
+export interface AutoloopState {
+    task_id: string;
+    branch: string;
+    phase: AutoloopPhase;
+    status: AutoloopStatus;
+    iter: number;
+    started_at: string;
+    best: BestPoint | null;
+    last_metric: MetricPoint | null;
+    plateau_count: number;
+    /** Set by RATCHET only. PROPOSE / MEASURE may not write this. */
+    decision: RatchetDecision | null;
+    decision_reason: string | null;
+    /**
+     * Git sha of the BOOTSTRAP commit. Used as the floor for git reset when no
+     * `best` exists yet (otherwise we'd reset to HEAD~1, which after a failed
+     * propose-then-resume can be the wrong target).
+     */
+    bootstrap_sha: string | null;
+    tree: StateTree;
+    termination: {
+        fired: boolean;
+        reason: string | null;
+    };
+    cost_usd_so_far: number;
+    /** Pushed-but-not-yet-locked aspirational gates the agent has proposed. */
+    pending_aspirational_count: number;
+}
+export interface MetricHistoryEntry {
+    iter: number;
+    ts: string;
+    metric: number;
+    gate_completion: number;
+    phase_at_record: AutoloopPhase;
+    git_sha_pre?: string;
+    git_sha_post?: string;
+}
+export interface GateResult {
+    name: string;
+    passed: boolean;
+    exit_code: number;
+    duration_ms: number;
+    /** Truncated stdout/stderr tail for diagnostic context. */
+    output_tail: string;
+}
+export interface EvalOutput {
+    iter: number;
+    ts: string;
+    /** All locked-gate results, in goal.json order. */
+    gates: GateResult[];
+    /** null when no scalar in goal.json or extract_cmd failed. */
+    scalar: number | null;
+    /** Computed = (gates that passed) / (locked gates total). */
+    gate_completion: number;
+    /** True if every locked gate passed. */
+    all_gates_passed: boolean;
+}
+export interface RatchetOutput {
+    iter: number;
+    decision: RatchetDecision;
+    reason: string;
+    /** True if RATCHET wants the runner to push the user (e.g. unsure / new-best / plateau). */
+    push_user?: {
+        kind: 'new_best' | 'plateau' | 'unsure_no_metric' | 'aspirational_proposed';
+        text: string;
+    };
+}
+export type PushKind = 'bootstrap_aspirational' | 'new_best' | 'plateau' | 'unsure_no_metric' | 'aspirational_proposed' | 'termination' | 'hard_error';
+export interface PushEvent {
+    kind: PushKind;
+    text: string;
+    task_id: string;
+    iter: number;
+    ts: string;
+}
+export interface AutoloopConfig {
+    /** Workspace path — must be a git repo. tasks/<id>/ will be created here. */
+    workspace: string;
+    /** Path to plan.md (will be copied into tasks/<id>/plan.md). */
+    plan_path: string;
+    /** Path to goal.json (will be copied + validated into tasks/<id>/goal.json). */
+    goal_path: string;
+    /** Override for the task id; defaults to a timestamped slug. */
+    task_id?: string;
+    /** Engine for PROPOSE/BOOTSTRAP/COMPRESS. Default 'claude'. */
+    propose_engine?: EngineType;
+    /** Model for PROPOSE/BOOTSTRAP/COMPRESS. Default 'opus'. */
+    propose_model?: string;
+    /** Engine for RATCHET. Default 'claude'. */
+    ratchet_engine?: EngineType;
+    /** Model for RATCHET. Default 'opus'. */
+    ratchet_model?: string;
+    /** How often to run COMPRESS. Default 10. */
+    compress_every_k?: number;
+    /** Per-iter wall clock for PROPOSE/EXECUTE phases (ms). Default 600_000 (10 min). */
+    per_iter_timeout_ms?: number;
+    /** Push hook command (defaults to `openclaw message send`). Set to null to disable pushes. */
+    push_cmd?: string | null;
+}
+export interface AutoloopHandle {
+    id: string;
+    status: AutoloopStatus;
+    task_dir: string;
+    started_at: string;
+    ended_at?: string;
+    /** Last-known phase from state.json (cheap to read). */
+    current_phase?: AutoloopPhase;
+    current_iter?: number;
+    best_metric?: number;
+    error?: string;
+}
+export declare class GoalSpecError extends Error {
+    constructor(message: string);
+}
+export declare function validateGoalSpec(raw: unknown): GoalSpec;
+/**
+ * Derive the metric value used for ratcheting from an EvalOutput.
+ * Rule:
+ *   - If goal has a scalar AND eval produced one, use the scalar.
+ *   - Otherwise, use gate_completion (∈ [0, 1]).
+ */
+export declare function deriveMetric(eval_out: EvalOutput, goal: GoalSpec): number;
+/**
+ * Did `candidate` improve over `incumbent` for this goal? Honours noise_floor.
+ * If no scalar, "improve" means strictly higher gate_completion.
+ */
+export declare function isImprovement(candidate: number, incumbent: number | null, goal: GoalSpec): boolean;
+/** Has the scalar/gate target been hit? */
+export declare function isTargetReached(metric: number, gate_completion: number, goal: GoalSpec): boolean;

package/dist/src/autoloop-types.js

@@ -0,0 +1,130 @@
+/**
+ * Types for the autoloop feature.
+ *
+ * Contracts are documented in tasks/autoloop.md. Schemas here are intentionally
+ * narrow — additions belong in the design doc first.
+ */
+// ─── Validation Helpers ─────────────────────────────────────────────────────
+export class GoalSpecError extends Error {
+    constructor(message) {
+        super(`goal.json: ${message}`);
+        this.name = 'GoalSpecError';
+    }
+}
+export function validateGoalSpec(raw) {
+    if (!raw || typeof raw !== 'object')
+        throw new GoalSpecError('must be an object');
+    const o = raw;
+    if (!Array.isArray(o.gates))
+        throw new GoalSpecError('`gates` must be an array');
+    const gates = o.gates.map((g, i) => validateGate(g, `gates[${i}]`));
+    let scalar;
+    if (o.scalar != null)
+        scalar = validateScalar(o.scalar);
+    let aspirational_gates;
+    if (Array.isArray(o.aspirational_gates)) {
+        aspirational_gates = o.aspirational_gates.map((g, i) => validateGate(g, `aspirational_gates[${i}]`));
+    }
+    if (!o.termination || typeof o.termination !== 'object') {
+        throw new GoalSpecError('`termination` is required');
+    }
+    const termination = validateTermination(o.termination);
+    // Cross-check: if no scalar, gates must be non-empty (otherwise the loop has nothing to ratchet against)
+    if (!scalar && gates.length === 0) {
+        throw new GoalSpecError('must have at least one of `scalar` or `gates`');
+    }
+    return { scalar, gates, aspirational_gates, termination };
+}
+function validateScalar(raw) {
+    const o = raw;
+    if (typeof o.name !== 'string')
+        throw new GoalSpecError('scalar.name must be string');
+    if (o.direction !== 'min' && o.direction !== 'max') {
+        throw new GoalSpecError('scalar.direction must be "min" or "max"');
+    }
+    if (typeof o.extract_cmd !== 'string' || !o.extract_cmd.trim()) {
+        throw new GoalSpecError('scalar.extract_cmd must be a non-empty string');
+    }
+    return {
+        name: o.name,
+        direction: o.direction,
+        extract_cmd: o.extract_cmd,
+        extract_timeout_sec: typeof o.extract_timeout_sec === 'number' && o.extract_timeout_sec > 0 ? o.extract_timeout_sec : 600,
+        target: typeof o.target === 'number' ? o.target : undefined,
+        noise_floor: typeof o.noise_floor === 'number' ? o.noise_floor : 0,
+    };
+}
+function validateGate(raw, ctx) {
+    const o = raw;
+    if (typeof o.name !== 'string')
+        throw new GoalSpecError(`${ctx}.name must be string`);
+    if (typeof o.cmd !== 'string' || !o.cmd.trim()) {
+        throw new GoalSpecError(`${ctx}.cmd must be a non-empty string`);
+    }
+    if (o.must !== 'exit-0') {
+        throw new GoalSpecError(`${ctx}.must must be "exit-0" (other modes not yet supported)`);
+    }
+    return {
+        name: o.name,
+        cmd: o.cmd,
+        must: 'exit-0',
+        timeout_sec: typeof o.timeout_sec === 'number' && o.timeout_sec > 0 ? o.timeout_sec : 300,
+    };
+}
+function validateTermination(raw) {
+    const o = raw;
+    const num = (k, def) => {
+        if (typeof o[k] === 'number' && Number.isFinite(o[k]))
+            return o[k];
+        if (def !== undefined)
+            return def;
+        throw new GoalSpecError(`termination.${k} must be a number`);
+    };
+    return {
+        scalar_target_hit: o.scalar_target_hit !== false,
+        max_iters: num('max_iters', 200),
+        plateau_iters: num('plateau_iters', 10),
+        max_cost_usd: num('max_cost_usd', 200),
+        max_pending_aspirational: num('max_pending_aspirational', 5),
+    };
+}
+/**
+ * Derive the metric value used for ratcheting from an EvalOutput.
+ * Rule:
+ *   - If goal has a scalar AND eval produced one, use the scalar.
+ *   - Otherwise, use gate_completion (∈ [0, 1]).
+ */
+export function deriveMetric(eval_out, goal) {
+    if (goal.scalar && eval_out.scalar != null)
+        return eval_out.scalar;
+    return eval_out.gate_completion;
+}
+/**
+ * Did `candidate` improve over `incumbent` for this goal? Honours noise_floor.
+ * If no scalar, "improve" means strictly higher gate_completion.
+ */
+export function isImprovement(candidate, incumbent, goal) {
+    if (incumbent === null)
+        return true;
+    if (goal.scalar) {
+        const noise = goal.scalar.noise_floor ?? 0;
+        if (goal.scalar.direction === 'min')
+            return candidate < incumbent - noise;
+        return candidate > incumbent + noise;
+    }
+    // No scalar: gate_completion, higher is better, no noise floor.
+    return candidate > incumbent;
+}
+/** Has the scalar/gate target been hit? */
+export function isTargetReached(metric, gate_completion, goal) {
+    if (!goal.termination.scalar_target_hit)
+        return false;
+    if (goal.scalar?.target != null) {
+        if (goal.scalar.direction === 'min')
+            return metric <= goal.scalar.target;
+        return metric >= goal.scalar.target;
+    }
+    // No scalar target set; "done" means all gates passing.
+    return gate_completion >= 1.0;
+}
+//# sourceMappingURL=autoloop-types.js.map

package/dist/src/autoloop-types.js.map

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

package/dist/src/autoloop.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Autoloop driver — phase machine for autonomous workspace iteration.
+ *
+ * Contract: tasks/autoloop.md.  This file implements the runner; phase prompts
+ * live in configs/autoloop-*-prompt.md.
+ *
+ * Lifecycle (one runner per task):
+ *   start() → BOOTSTRAP → loop { PROPOSE → EXECUTE → MEASURE → RATCHET → maybe COMPRESS } → TERMINATED
+ *
+ * Termination triggers: scalar target hit, max_iters, max_cost_usd, hard error,
+ * explicit stop(). Plateau pushes the user but does NOT halt the loop (per
+ * design constraint C9 — proactivity).
+ */
+import { EventEmitter } from 'node:events';
+import type { SessionManager } from './session-manager.js';
+import type { Logger } from './logger.js';
+import type { EngineType } from './types.js';
+import type { AutoloopConfig, AutoloopHandle } from './autoloop-types.js';
+export declare class AutoloopRunner extends EventEmitter {
+    readonly id: string;
+    readonly config: AutoloopConfig;
+    readonly taskDir: string;
+    readonly branch: string;
+    private state;
+    private goal;
+    private stopRequested;
+    private startedAt;
+    private endedAt?;
+    private status;
+    private errorMsg?;
+    private readonly manager;
+    private readonly logger;
+    constructor(manager: SessionManager, config: AutoloopConfig, logger?: Logger);
+    /** Start the loop. Resolves after BOOTSTRAP; iteration runs in the background. */
+    start(): Promise<void>;
+    /**
+     * Resume an interrupted autoloop from on-disk state. Skips BOOTSTRAP and
+     * jumps straight to the iteration loop. Resets the workspace to the last
+     * known best (or the BOOTSTRAP baseline if no best yet) so any half-finished
+     * PROPOSE that crashed mid-flight is discarded.
+     */
+    resume(): Promise<void>;
+    /** Ask the loop to halt at the next phase boundary. Resolves when actually stopped. */
+    stop(): Promise<void>;
+    /** Inject a hint that the next PROPOSE will read. */
+    inject(text: string): void;
+    /** Cheap status snapshot from in-memory state. */
+    handle(): AutoloopHandle;
+    private prepareTaskDir;
+    private loadAndValidateGoal;
+    private initialState;
+    private ensureBranch;
+    private runBootstrap;
+    private runLoop;
+    private runPropose;
+    private runExecute;
+    private runMeasure;
+    private runRatchet;
+    private runCompress;
+    private persistState;
+    private gitSha;
+    private gitReset;
+    private readMetricHistory;
+    private readLastRatchet;
+    private tryRead;
+    private push;
+    private terminate;
+    private fail;
+}
+export type { EngineType };