opensquid 0.5.412 → 0.5.426

package/dist/runtime/ralph/lap_outcome.js

@@ -0,0 +1,119 @@
+/**
+ * GR.2 — the typed-exit contract for a gated-ralph lap (Inv 5: ONE typed exit).
+ *
+ * A lap is a headless `claude -p … --output-format json` run of `RALPH.md`. Its envelope is the
+ * empirically-verified shape `{ result, is_error, subtype, total_cost_usd, … }` (verified 2026-06-13).
+ * The lap signals its outcome by emitting a single greppable line in `result`:
+ *
+ *     RALPH-EXIT: {"kind":"HUMAN_REQUIRED","reason":"SCOPE_FORK","payload":{…}}
+ *
+ * `parseLapOutcome` is a TOTAL mapping of every envelope shape to a `LapOutcome` — it never throws and
+ * never returns a false `SHIPPED`: an unparseable envelope or `is_error` becomes `CRASH`; a clean
+ * envelope with no tag becomes `SHIPPED`. The orchestrator (GR.4) switches on the result.
+ *
+ * Imported by: src/runtime/ralph/orchestrator.ts (GR.4), src/runtime/ralph/supervisor.ts (GR.3).
+ */
+const HUMAN_REQUIRED_REASONS = [
+    'IRREVERSIBLE_BOUNDARY',
+    'SCOPE_FORK',
+    'UNRECOVERABLE_WEDGE',
+    'BUDGET',
+    'RATE_BUDGET',
+    'BOARD_EMPTY',
+];
+const isReason = (v) => typeof v === 'string' && HUMAN_REQUIRED_REASONS.includes(v);
+const TAG = 'RALPH-EXIT:';
+/**
+ * Scan the lap's free-text result for the LAST `RALPH-EXIT: {json}` line and validate it into a
+ * `LapOutcome`. Returns null when there is no well-formed tag (caller defaults to SHIPPED on a clean
+ * exit). Defensive by construction — a malformed tag is treated as "no tag".
+ */
+export function extractTypedExit(resultText) {
+    const idx = resultText.lastIndexOf(TAG);
+    if (idx === -1)
+        return null;
+    const after = resultText.slice(idx + TAG.length).trimStart();
+    const json = sliceFirstJsonObject(after);
+    if (json === null)
+        return null;
+    let obj;
+    try {
+        obj = JSON.parse(json);
+    }
+    catch {
+        return null;
+    }
+    if (obj === null || typeof obj !== 'object')
+        return null;
+    const rec = obj;
+    switch (rec.kind) {
+        case 'SHIPPED':
+            return { kind: 'SHIPPED' };
+        case 'WEDGE':
+            return { kind: 'WEDGE' };
+        case 'TIMEOUT':
+            return { kind: 'TIMEOUT' };
+        case 'CRASH':
+            return { kind: 'CRASH' };
+        case 'HUMAN_REQUIRED':
+            if (!isReason(rec.reason))
+                return null; // a HUMAN_REQUIRED without a valid reason is malformed
+            return {
+                kind: 'HUMAN_REQUIRED',
+                reason: rec.reason,
+                ...(typeof rec.item === 'string' ? { item: rec.item } : {}),
+                ...(rec.payload === undefined ? {} : { payload: rec.payload }),
+            };
+        default:
+            return null;
+    }
+}
+/** Parse the headless JSON envelope into a total `LapOutcome` + the lap's cost. Never throws. */
+export function parseLapOutcome(stdout) {
+    let env;
+    try {
+        const parsed = JSON.parse(stdout);
+        if (parsed === null || typeof parsed !== 'object')
+            return { outcome: { kind: 'CRASH' }, costUsd: 0 };
+        env = parsed;
+    }
+    catch {
+        return { outcome: { kind: 'CRASH' }, costUsd: 0 }; // unparseable envelope = CRASH, never SHIPPED
+    }
+    const costUsd = typeof env.total_cost_usd === 'number' ? env.total_cost_usd : 0;
+    if (env.is_error === true)
+        return { outcome: { kind: 'CRASH' }, costUsd };
+    const tagged = extractTypedExit(typeof env.result === 'string' ? env.result : '');
+    return { outcome: tagged ?? { kind: 'SHIPPED' }, costUsd }; // clean exit, no tag = SHIPPED
+}
+/** Return the first balanced `{…}` JSON object substring starting at `s[0]`, or null. */
+function sliceFirstJsonObject(s) {
+    if (!s.startsWith('{'))
+        return null;
+    let depth = 0;
+    let inStr = false;
+    let esc = false;
+    for (let i = 0; i < s.length; i++) {
+        const c = s[i];
+        if (inStr) {
+            if (esc)
+                esc = false;
+            else if (c === '\\')
+                esc = true;
+            else if (c === '"')
+                inStr = false;
+            continue;
+        }
+        if (c === '"')
+            inStr = true;
+        else if (c === '{')
+            depth++;
+        else if (c === '}') {
+            depth--;
+            if (depth === 0)
+                return s.slice(0, i + 1);
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=lap_outcome.js.map

package/dist/runtime/ralph/lap_outcome.js.map

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

package/dist/runtime/ralph/orchestrator.d.ts

@@ -0,0 +1,71 @@
+/**
+ * GR.4 — the gated-ralph orchestrator: a thin, non-LLM loop that composes GR.1–3.
+ *
+ * One pass: read the oldest ready item (GR.1 `listReady`) → atomically claim it (GR.1 CAS) → run a
+ * supervised lap (GR.3 `superviseLap` over an injected lap-runner that wraps `claude -p RALPH.md` +
+ * GR.2 `parseLapOutcome`) → act on the typed `LapOutcome` (GR.2) → repeat until BOARD_EMPTY or a
+ * stopping escalation. No new state store (claim/wedge are work-graph ops); no new gate logic (the lap
+ * is gated by the same coding-flow); ONE uniform escalation (GR.3 `escalateLap`).
+ *
+ * Dependencies are INJECTED (`RalphDeps`) so the loop is pure composition and unit-testable without the
+ * notification stack or a real `claude` subprocess — the CLI (`ralph.ts`) wires the real store, the
+ * `claude -p` lap-runner, and `escalateSeverity`.
+ *
+ * The S1 spike PROVED spawn-a-lap is safe (a nested `--dangerously-skip-permissions` lap's ungated
+ * commit was blocked by the gate), so this loop spawns laps directly rather than via Alternative F.
+ */
+import type { Issue, WorkGraphStore, ClaimAudience } from '../../workgraph/types.js';
+import type { HumanRequiredReason } from './lap_outcome.js';
+import type { LapResult, SuperviseOpts } from './supervisor.js';
+import { type LapEscalator } from './escalate_lap.js';
+import type { DecisionVerdict } from './decision_classifier.js';
+export interface RalphConfig {
+    /** Auth mode from CONFIG (Inv 11; no runtime auto-detect). API → dollar budget; subscription → W. */
+    authMode: 'api' | 'subscription';
+    /** API dollar bound — the running sum of the verified `total_cost_usd` (Inv 11). API mode only. */
+    maxBudgetUsd: number;
+    /** TTL for the per-item claim (GR.1). */
+    claimTtlSec: number;
+    /** Stop after one item (the `--once` flag). */
+    once: boolean;
+    /** GR.3 supervisor opts (retry cap, backoff, heartbeat). */
+    supervise: SuperviseOpts;
+}
+/** Why the loop stopped. NB: the per-item residual reasons (IRREVERSIBLE_BOUNDARY / SCOPE_FORK /
+ * UNRECOVERABLE_WEDGE) never STOP the loop — they park the item and the loop takes the next. Only the
+ * RESOURCE pauses + an explicit `--once` end the run. */
+export type RalphStop = 'BOARD_EMPTY' | 'BUDGET' | 'RATE_BUDGET' | 'once';
+export interface RalphResult {
+    stopped: RalphStop;
+    spent: number;
+    closed: string[];
+    parked: {
+        id: string;
+        reason: HumanRequiredReason;
+    }[];
+}
+export interface RalphDeps {
+    wg: WorkGraphStore;
+    /** Env-derived claim audience (GR.1 — never caller input). */
+    claimAudience: () => ClaimAudience;
+    /** Run ONE lap for an item → its typed outcome + cost. The CLI wraps `claude -p RALPH.md` + parseLapOutcome. */
+    runLap: (item: Issue) => Promise<LapResult>;
+    /** The undroppable escalation transport (GR.3) — the CLI wires `escalateSeverity`. */
+    escalate: LapEscalator;
+}
+export declare function runRalphLoop(cfg: RalphConfig, deps: RalphDeps): Promise<RalphResult>;
+/** GR.2's recordMisclassification, injected (kept testable / decoupled). */
+export type RecordMisclassification = (sessionId: string, expected: DecisionVerdict, got: DecisionVerdict, decision: string, nowIso: string) => Promise<void>;
+/**
+ * `opensquid loop resolve <itemId> --misclassified` — the human-override INPUT (post-hoc residual-shrink
+ * path; NOT the hot loop). The human marks a parked escalation as principle-settleable: we record the
+ * misclassification (the heuristic said ESCALATE, the correct verdict was DECIDE) and un-wedge the item so
+ * it re-enters `ready` for another lap. The SOLE caller of GR.2's recordMisclassification.
+ */
+export declare function resolveParked(itemId: string, deps: {
+    wg: WorkGraphStore;
+    recordMisclassification: RecordMisclassification;
+    sessionId: string;
+    nowIso: string;
+}): Promise<void>;
+//# sourceMappingURL=orchestrator.d.ts.map

package/dist/runtime/ralph/orchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../../src/runtime/ralph/orchestrator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACrF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhE,OAAO,EAAe,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACnE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAEhE,MAAM,WAAW,WAAW;IAC1B,qGAAqG;IACrG,QAAQ,EAAE,KAAK,GAAG,cAAc,CAAC;IACjC,mGAAmG;IACnG,YAAY,EAAE,MAAM,CAAC;IACrB,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,+CAA+C;IAC/C,IAAI,EAAE,OAAO,CAAC;IACd,4DAA4D;IAC5D,SAAS,EAAE,aAAa,CAAC;CAC1B;AAED;;yDAEyD;AACzD,MAAM,MAAM,SAAS,GAAG,aAAa,GAAG,QAAQ,GAAG,aAAa,GAAG,MAAM,CAAC;AAE1E,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,SAAS,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,MAAM,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,mBAAmB,CAAA;KAAE,EAAE,CAAC;CACvD;AAED,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,cAAc,CAAC;IACnB,8DAA8D;IAC9D,aAAa,EAAE,MAAM,aAAa,CAAC;IACnC,gHAAgH;IAChH,MAAM,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IAC5C,sFAAsF;IACtF,QAAQ,EAAE,YAAY,CAAC;CACxB;AAOD,wBAAsB,YAAY,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC,CA0D1F;AAED,4EAA4E;AAC5E,MAAM,MAAM,uBAAuB,GAAG,CACpC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,eAAe,EACzB,GAAG,EAAE,eAAe,EACpB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,KACX,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnB;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE;IACJ,EAAE,EAAE,cAAc,CAAC;IACnB,uBAAuB,EAAE,uBAAuB,CAAC;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB,GACA,OAAO,CAAC,IAAI,CAAC,CAMf"}

package/dist/runtime/ralph/orchestrator.js

@@ -0,0 +1,74 @@
+import { superviseLap } from './supervisor.js';
+import { escalateLap } from './escalate_lap.js';
+/** Resource pauses END the run; everything else is per-item decision-residual that parks + continues. */
+const RESOURCE_PAUSES = ['BUDGET', 'RATE_BUDGET', 'BOARD_EMPTY'];
+const isResourcePause = (r) => RESOURCE_PAUSES.includes(r);
+export async function runRalphLoop(cfg, deps) {
+    const { wg } = deps;
+    const closed = [];
+    const parked = [];
+    let spent = 0;
+    // THE single uniform stop-layer (Inv 5): every reason chat-escalates through ONE path — no per-trigger
+    // code paths (rejects Alt D). Two SEPARATE, explicit decisions ride alongside it: (a) wedge-mark ONLY the
+    // per-item residual (IRREVERSIBLE_BOUNDARY/SCOPE_FORK/UNRECOVERABLE_WEDGE) — a resource pause
+    // (BUDGET/RATE_BUDGET/BOARD_EMPTY) is TRANSIENT, so the item stays in `ready` to retry after the
+    // window/budget resets (wedge-marking it would PERMANENTLY park healthy work); (b) continue-vs-stop is
+    // isResourcePause at the call sites.
+    const parkAndEscalate = async (reason, item) => {
+        if (item !== undefined && !isResourcePause(reason)) {
+            await wg.wedgeMark(item.id, reason); // a marked item SKIPS on re-attempt (residual only — GR.3)
+            parked.push({ id: item.id, reason });
+        }
+        // GR.3 — undroppable. Omit `item` entirely when absent (exactOptionalPropertyTypes: no explicit undefined).
+        await escalateLap(reason, item === undefined ? { escalate: deps.escalate } : { item: item.id, escalate: deps.escalate });
+    };
+    for (;;) {
+        const ready = await wg.listReady(); // GR.1 ordering, claim+wedge aware (live-claimed items excluded)
+        if (ready.length === 0) {
+            await parkAndEscalate('BOARD_EMPTY'); // resource pause → escalate + STOP
+            return { stopped: 'BOARD_EMPTY', spent, closed, parked };
+        }
+        const item = ready[0]; // oldest-first (shipped listReady ORDER BY created_at; no priority column)
+        if (item === undefined)
+            continue; // unreachable (length checked) — narrows for strict indexing
+        const { won } = await wg.claimIssue(item.id, deps.claimAudience(), cfg.claimTtlSec); // GR.1 atomic CAS
+        if (!won)
+            continue; // another runner/harness won it — it now carries a live claim, excluded next pass
+        const outcome = await superviseLap(() => deps.runLap(item), cfg.supervise); // GR.3 → LapResult
+        spent += outcome.costUsd; // GR.3 propagates costUsd across retries
+        if (outcome.kind === 'SHIPPED') {
+            await wg.updateIssue(item.id, { status: 'closed' });
+            closed.push(item.id);
+        }
+        else {
+            // Non-SHIPPED → the ONE uniform path. HUMAN_REQUIRED carries its reason; WEDGE (and the
+            // post-supervision CRASH/TIMEOUT the type allows but superviseLap never returns — it exhausts
+            // them to HUMAN_REQUIRED{UNRECOVERABLE_WEDGE}) map to UNRECOVERABLE_WEDGE.
+            const reason = outcome.kind === 'HUMAN_REQUIRED' ? outcome.reason : 'UNRECOVERABLE_WEDGE';
+            await parkAndEscalate(reason, item);
+            if (isResourcePause(reason))
+                return { stopped: reason, spent, closed, parked }; // e.g. lap-emitted RATE_BUDGET
+            // else (IRREVERSIBLE_BOUNDARY / SCOPE_FORK / UNRECOVERABLE_WEDGE): parked, take the next item
+        }
+        if (cfg.authMode === 'api' && spent > cfg.maxBudgetUsd) {
+            await parkAndEscalate('BUDGET'); // Inv 11 API bound (verified total_cost_usd) → resource pause → STOP
+            return { stopped: 'BUDGET', spent, closed, parked };
+        }
+        if (cfg.once)
+            return { stopped: 'once', spent, closed, parked };
+    }
+}
+/**
+ * `opensquid loop resolve <itemId> --misclassified` — the human-override INPUT (post-hoc residual-shrink
+ * path; NOT the hot loop). The human marks a parked escalation as principle-settleable: we record the
+ * misclassification (the heuristic said ESCALATE, the correct verdict was DECIDE) and un-wedge the item so
+ * it re-enters `ready` for another lap. The SOLE caller of GR.2's recordMisclassification.
+ */
+export async function resolveParked(itemId, deps) {
+    const item = await deps.wg.getIssue(itemId);
+    if (item?.wedgeReason === undefined)
+        throw new Error(`resolveParked: not a parked item: ${itemId}`);
+    await deps.recordMisclassification(deps.sessionId, 'DECIDE', 'ESCALATE', item.title, deps.nowIso);
+    await deps.wg.clearWedge(itemId); // un-wedge → re-enters listReady
+}
+//# sourceMappingURL=orchestrator.js.map

package/dist/runtime/ralph/orchestrator.js.map

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

package/dist/runtime/ralph/ralph_template.d.ts

@@ -0,0 +1,18 @@
+/**
+ * GR.4 — the RALPH.md per-lap directive (the "Ralph constant").
+ *
+ * This is the STABLE prompt every lap runs (Brodie's Ralph: the same prompt, fresh context, every
+ * iteration — Inv 1 dumb-loop + Inv 2 fresh-context). It is NOT the orchestrator's logic; it is the
+ * instruction the spawned `claude -p` lap reads. The orchestrator stays a thin non-LLM loop; ALL the
+ * intelligence lives in the lap running this directive against the reloaded wedge-gated lessons.
+ *
+ * The one hard contract between lap and orchestrator: the lap MUST end by emitting a single greppable
+ * `RALPH-EXIT: {json}` line whose JSON is a `LapOutcome` (parsed by GR.2 `extractTypedExit`). Everything
+ * else (resume, lean load, the 7-phase flow, DECIDE-vs-ESCALATE) is the same discipline a human-driven
+ * session follows — the lap is gated identically (the gate is harness-agnostic, GDC).
+ *
+ * Exported as a string constant (not a shipped file) so the wizard (`ralph_writer.ts`) writes it to
+ * `~/.opensquid/RALPH.md` idempotently — no build-time file-copy-to-dist concern.
+ */
+export declare const RALPH_MD = "# RALPH.md \u2014 the gated-ralph per-lap directive\n\nYou are ONE lap of an autonomous gated loop. A thin orchestrator handed you exactly one already-claimed\nwork-item id via `--item <id>`. Your context is FRESH \u2014 nothing carried over from the previous lap\nexcept the durable disk (the work-graph + the wedge-gated lesson store). That is by design: you are the\ndumb loop's smart body (Inv 1/2). Do the item, then exit with a typed verdict. Do not try to do the\nwhole board \u2014 the orchestrator takes the next item.\n\n## What to do\n\n1. **Resume + load lean.** Read the item (`workgraph_get`) and recall only the lessons/memories relevant\n   to it (scoped recall). Do NOT bulk-load the whole store \u2014 fresh context is the point.\n2. **Run the flow.** Drive SCOPE \u2192 AUTHOR \u2192 the 7-phase exactly as an interactive session would. The gate\n   is identical for you (it is harness-agnostic). You CANNOT route around it \u2014 `--no-verify` is futile\n   (the PreToolUse + git-owned gates both hold), and that is the safety floor that lets you run unattended.\n3. **DECIDE, don't ask.** Surface decisions are yours to settle by the locked principles (rename, format,\n   file location, refactor \u2014 Simplicity). Decide and proceed. Permission-fishing is drift, not diligence.\n4. **ESCALATE only the genuine residual.** Stop and emit `HUMAN_REQUIRED` ONLY for: an irreversible /\n   outward boundary you cannot cross (npm publish, OTP, force-push, prod deploy, drop table) \u2192\n   `IRREVERSIBLE_BOUNDARY`; a genuine product/UX fork the principles cannot settle \u2192 `SCOPE_FORK`. These\n   are the things only the human can own. Everything else, you own.\n5. **Ship gated.** Land the work only through the flow (tests + gates green, commit, push if configured).\n   Flush any durable lessons learned.\n\n## How to exit (the ONE hard contract)\n\nEnd your run by printing EXACTLY ONE line of the form:\n\n```\nRALPH-EXIT: {\"kind\":\"SHIPPED\"}\n```\n\nThe JSON must be one of:\n\n- `{\"kind\":\"SHIPPED\"}` \u2014 the item is done, gated, committed.\n- `{\"kind\":\"HUMAN_REQUIRED\",\"reason\":\"IRREVERSIBLE_BOUNDARY\",\"payload\":{...}}` \u2014 parked for the human;\n  `reason` is one of IRREVERSIBLE_BOUNDARY | SCOPE_FORK | UNRECOVERABLE_WEDGE | BUDGET | RATE_BUDGET |\n  BOARD_EMPTY (you will normally only emit the first two; the orchestrator owns the resource reasons).\n- `{\"kind\":\"WEDGE\"}` \u2014 you are genuinely stuck and a fresh lap on the SAME item would not help (the\n  orchestrator wedge-marks it so it is not re-attempted, and escalates UNRECOVERABLE_WEDGE).\n\nIf you crash or time out, say nothing special \u2014 the orchestrator's supervisor treats a missing/erroring\nexit as a transient CRASH/TIMEOUT and bounds the retries itself. A clean run with NO tag = `SHIPPED`.\n";
+//# sourceMappingURL=ralph_template.d.ts.map

package/dist/runtime/ralph/ralph_template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ralph_template.d.ts","sourceRoot":"","sources":["../../../src/runtime/ralph/ralph_template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,eAAO,MAAM,QAAQ,ixFA2CpB,CAAC"}

package/dist/runtime/ralph/ralph_template.js

@@ -0,0 +1,61 @@
+/**
+ * GR.4 — the RALPH.md per-lap directive (the "Ralph constant").
+ *
+ * This is the STABLE prompt every lap runs (Brodie's Ralph: the same prompt, fresh context, every
+ * iteration — Inv 1 dumb-loop + Inv 2 fresh-context). It is NOT the orchestrator's logic; it is the
+ * instruction the spawned `claude -p` lap reads. The orchestrator stays a thin non-LLM loop; ALL the
+ * intelligence lives in the lap running this directive against the reloaded wedge-gated lessons.
+ *
+ * The one hard contract between lap and orchestrator: the lap MUST end by emitting a single greppable
+ * `RALPH-EXIT: {json}` line whose JSON is a `LapOutcome` (parsed by GR.2 `extractTypedExit`). Everything
+ * else (resume, lean load, the 7-phase flow, DECIDE-vs-ESCALATE) is the same discipline a human-driven
+ * session follows — the lap is gated identically (the gate is harness-agnostic, GDC).
+ *
+ * Exported as a string constant (not a shipped file) so the wizard (`ralph_writer.ts`) writes it to
+ * `~/.opensquid/RALPH.md` idempotently — no build-time file-copy-to-dist concern.
+ */
+export const RALPH_MD = `# RALPH.md — the gated-ralph per-lap directive
+
+You are ONE lap of an autonomous gated loop. A thin orchestrator handed you exactly one already-claimed
+work-item id via \`--item <id>\`. Your context is FRESH — nothing carried over from the previous lap
+except the durable disk (the work-graph + the wedge-gated lesson store). That is by design: you are the
+dumb loop's smart body (Inv 1/2). Do the item, then exit with a typed verdict. Do not try to do the
+whole board — the orchestrator takes the next item.
+
+## What to do
+
+1. **Resume + load lean.** Read the item (\`workgraph_get\`) and recall only the lessons/memories relevant
+   to it (scoped recall). Do NOT bulk-load the whole store — fresh context is the point.
+2. **Run the flow.** Drive SCOPE → AUTHOR → the 7-phase exactly as an interactive session would. The gate
+   is identical for you (it is harness-agnostic). You CANNOT route around it — \`--no-verify\` is futile
+   (the PreToolUse + git-owned gates both hold), and that is the safety floor that lets you run unattended.
+3. **DECIDE, don't ask.** Surface decisions are yours to settle by the locked principles (rename, format,
+   file location, refactor — Simplicity). Decide and proceed. Permission-fishing is drift, not diligence.
+4. **ESCALATE only the genuine residual.** Stop and emit \`HUMAN_REQUIRED\` ONLY for: an irreversible /
+   outward boundary you cannot cross (npm publish, OTP, force-push, prod deploy, drop table) →
+   \`IRREVERSIBLE_BOUNDARY\`; a genuine product/UX fork the principles cannot settle → \`SCOPE_FORK\`. These
+   are the things only the human can own. Everything else, you own.
+5. **Ship gated.** Land the work only through the flow (tests + gates green, commit, push if configured).
+   Flush any durable lessons learned.
+
+## How to exit (the ONE hard contract)
+
+End your run by printing EXACTLY ONE line of the form:
+
+\`\`\`
+RALPH-EXIT: {"kind":"SHIPPED"}
+\`\`\`
+
+The JSON must be one of:
+
+- \`{"kind":"SHIPPED"}\` — the item is done, gated, committed.
+- \`{"kind":"HUMAN_REQUIRED","reason":"IRREVERSIBLE_BOUNDARY","payload":{...}}\` — parked for the human;
+  \`reason\` is one of IRREVERSIBLE_BOUNDARY | SCOPE_FORK | UNRECOVERABLE_WEDGE | BUDGET | RATE_BUDGET |
+  BOARD_EMPTY (you will normally only emit the first two; the orchestrator owns the resource reasons).
+- \`{"kind":"WEDGE"}\` — you are genuinely stuck and a fresh lap on the SAME item would not help (the
+  orchestrator wedge-marks it so it is not re-attempted, and escalates UNRECOVERABLE_WEDGE).
+
+If you crash or time out, say nothing special — the orchestrator's supervisor treats a missing/erroring
+exit as a transient CRASH/TIMEOUT and bounds the retries itself. A clean run with NO tag = \`SHIPPED\`.
+`;
+//# sourceMappingURL=ralph_template.js.map

package/dist/runtime/ralph/ralph_template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ralph_template.js","sourceRoot":"","sources":["../../../src/runtime/ralph/ralph_template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,CAAC,MAAM,QAAQ,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2CvB,CAAC"}

package/dist/runtime/ralph/supervisor.d.ts

@@ -0,0 +1,30 @@
+/**
+ * GR.3 — the lap-supervisor: bounded respawn + observable heartbeat (Inv 6: no silent death, no
+ * unbounded retry).
+ *
+ * `superviseLap` runs a lap, retrying ONLY on CRASH/TIMEOUT (every other outcome — SHIPPED,
+ * HUMAN_REQUIRED, WEDGE — is terminal and returned as-is). Retries are BOUNDED by `maxRetries`; on
+ * exhaustion it returns a typed `HUMAN_REQUIRED{UNRECOVERABLE_WEDGE}` rather than looping forever or
+ * dying quietly. The `heartbeat` callback is the OBSERVABLE liveness tick (the orchestrator passes a
+ * lease-refresh, the `live_session_lease` freshness model) — liveness is a signal, not a hope.
+ *
+ * Cost propagates: each attempt bills `costUsd`, accumulated across retries, so GR.4 can sum the Inv 11
+ * running budget even when a crash-then-ship spent on both attempts.
+ *
+ * Imported by: src/runtime/ralph/orchestrator.ts (GR.4).
+ */
+import type { LapOutcome } from './lap_outcome.js';
+export type LapResult = LapOutcome & {
+    costUsd: number;
+};
+export interface SuperviseOpts {
+    maxRetries: number;
+    /** Backoff before the n-th retry (n is 0-based attempt index just completed). */
+    backoffMs: (attempt: number) => number;
+    /** Observable liveness tick, fired once per attempt (e.g. refreshLease). */
+    heartbeat: () => void;
+    /** Injectable sleep (tests pass a no-op); defaults to a real timer. */
+    sleep?: (ms: number) => Promise<void>;
+}
+export declare function superviseLap(run: () => Promise<LapResult>, opts: SuperviseOpts): Promise<LapResult>;
+//# sourceMappingURL=supervisor.d.ts.map

package/dist/runtime/ralph/supervisor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor.d.ts","sourceRoot":"","sources":["../../../src/runtime/ralph/supervisor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,MAAM,MAAM,SAAS,GAAG,UAAU,GAAG;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,iFAAiF;IACjF,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;IACvC,4EAA4E;IAC5E,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB,uEAAuE;IACvE,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAID,wBAAsB,YAAY,CAChC,GAAG,EAAE,MAAM,OAAO,CAAC,SAAS,CAAC,EAC7B,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,SAAS,CAAC,CAmBpB"}

package/dist/runtime/ralph/supervisor.js

@@ -0,0 +1,24 @@
+const realSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export async function superviseLap(run, opts) {
+    const sleep = opts.sleep ?? realSleep;
+    let costUsd = 0;
+    for (let attempt = 0; attempt <= opts.maxRetries; attempt++) {
+        opts.heartbeat();
+        let out = null;
+        try {
+            out = await run();
+            costUsd += out.costUsd;
+        }
+        catch {
+            out = null; // a thrown run is treated as CRASH (retryable)
+        }
+        if (out !== null && out.kind !== 'CRASH' && out.kind !== 'TIMEOUT') {
+            return { ...out, costUsd }; // terminal: SHIPPED / HUMAN_REQUIRED / WEDGE
+        }
+        if (attempt < opts.maxRetries)
+            await sleep(opts.backoffMs(attempt));
+    }
+    // bounded → escalate, never silent
+    return { kind: 'HUMAN_REQUIRED', reason: 'UNRECOVERABLE_WEDGE', costUsd };
+}
+//# sourceMappingURL=supervisor.js.map

package/dist/runtime/ralph/supervisor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor.js","sourceRoot":"","sources":["../../../src/runtime/ralph/supervisor.ts"],"names":[],"mappings":"AA6BA,MAAM,SAAS,GAAG,CAAC,EAAU,EAAiB,EAAE,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;AAEvF,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,GAA6B,EAC7B,IAAmB;IAEnB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,SAAS,CAAC;IACtC,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,IAAI,CAAC,UAAU,EAAE,OAAO,EAAE,EAAE,CAAC;QAC5D,IAAI,CAAC,SAAS,EAAE,CAAC;QACjB,IAAI,GAAG,GAAqB,IAAI,CAAC;QACjC,IAAI,CAAC;YACH,GAAG,GAAG,MAAM,GAAG,EAAE,CAAC;YAClB,OAAO,IAAI,GAAG,CAAC,OAAO,CAAC;QACzB,CAAC;QAAC,MAAM,CAAC;YACP,GAAG,GAAG,IAAI,CAAC,CAAC,+CAA+C;QAC7D,CAAC;QACD,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,CAAC,IAAI,KAAK,OAAO,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YACnE,OAAO,EAAE,GAAG,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC,6CAA6C;QAC3E,CAAC;QACD,IAAI,OAAO,GAAG,IAAI,CAAC,UAAU;YAAE,MAAM,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;IACtE,CAAC;IACD,mCAAmC;IACnC,OAAO,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,EAAE,qBAAqB,EAAE,OAAO,EAAE,CAAC;AAC5E,CAAC"}

package/dist/setup/cli/ralph.d.ts

@@ -0,0 +1,20 @@
+import type { Command } from 'commander';
+import { runOneShotCli } from '../../runtime/spawn_lifecycle.js';
+import type { Issue } from '../../workgraph/types.js';
+import { type RalphConfig } from '../../runtime/ralph/orchestrator.js';
+import type { LapResult } from '../../runtime/ralph/supervisor.js';
+import { type ChatSend } from '../../runtime/ralph/escalator.js';
+import { type RalphConfigFile } from '../wizard/ralph_writer.js';
+/** Hydrate the persisted scalar config into the orchestrator's runtime `RalphConfig` (closures rebuilt). */
+export declare function buildRalphConfig(file: RalphConfigFile, opts: {
+    once: boolean;
+    maxBudgetUsd?: number;
+}): RalphConfig;
+/** Build the per-lap runner: spawn `claude -p RALPH.md --item <id>`, parse the typed exit. A deadline
+ * overrun (group-SIGKILL) becomes the typed TIMEOUT, NOT a CRASH; a genuine spawn failure rethrows → CRASH. */
+export declare function makeSpawnLap(cfg: RalphConfig, file: RalphConfigFile, runCli?: typeof runOneShotCli): (item: Issue) => Promise<LapResult>;
+/** The real chat transport: a one-shot UDS JSON-RPC `send` to the chat-daemon (the live Telegram path
+ * `chat_send` uses). `ok:false` on any unreachable/error so the escalator stays undroppable. */
+export declare const daemonChatSend: ChatSend;
+export declare function registerRalph(program: Command): Command;
+//# sourceMappingURL=ralph.d.ts.map

package/dist/setup/cli/ralph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ralph.d.ts","sourceRoot":"","sources":["../../../src/setup/cli/ralph.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AAGjE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAA+B,KAAK,WAAW,EAAE,MAAM,qCAAqC,CAAC;AACpG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AAGnE,OAAO,EAAiB,KAAK,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AAChF,OAAO,EAAmB,KAAK,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAElF,4GAA4G;AAC5G,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,eAAe,EACrB,IAAI,EAAE;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7C,WAAW,CAYb;AAED;+GAC+G;AAC/G,wBAAgB,YAAY,CAC1B,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE,eAAe,EACrB,MAAM,GAAE,OAAO,aAA6B,GAC3C,CAAC,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,SAAS,CAAC,CA6BrC;AAED;gGACgG;AAChG,eAAO,MAAM,cAAc,EAAE,QAwCzB,CAAC;AAEL,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAqEvD"}

package/dist/setup/cli/ralph.js

@@ -0,0 +1,168 @@
+/**
+ * GR.4 — the `opensquid loop` CLI: the user-invoked entry that ASSEMBLES the orchestrator's injected deps
+ * and runs the gated-ralph loop. A thin wire — all logic lives in the unit-tested pieces it composes
+ * (runRalphLoop, chatEscalator, parseLapOutcome, the GR.1–3 store ops). The loop is a CLI COMMAND, not a
+ * daemon (opensquid stays an MCP server / tool provider; the agent loop runs inside the spawned harness).
+ *
+ * Commands:
+ *   opensquid loop [--once] [--max-budget-usd <n>]      — run the loop (read ready → claim → lap → repeat)
+ *   opensquid loop resolve <itemId> --misclassified     — the human-override residual-shrink path (GR.4)
+ *
+ * Imports from: commander, node:net, ../../runtime/paths.js, ../../runtime/spawn_lifecycle.js,
+ * ../../runtime/ralph/*, ../../workgraph/*, ../wizard/ralph_writer.js.
+ */
+import { connect } from 'node:net';
+import { join } from 'node:path';
+import { OPENSQUID_HOME, chatDaemonSockPath } from '../../runtime/paths.js';
+import { runOneShotCli } from '../../runtime/spawn_lifecycle.js';
+import { workGraphStore } from '../../workgraph/store.js';
+import { claimAudience } from '../../workgraph/audience.js';
+import { runRalphLoop, resolveParked } from '../../runtime/ralph/orchestrator.js';
+import { parseLapOutcome } from '../../runtime/ralph/lap_outcome.js';
+import { recordMisclassification } from '../../runtime/ralph/decision_classifier.js';
+import { chatEscalator } from '../../runtime/ralph/escalator.js';
+import { readRalphConfig } from '../wizard/ralph_writer.js';
+/** Hydrate the persisted scalar config into the orchestrator's runtime `RalphConfig` (closures rebuilt). */
+export function buildRalphConfig(file, opts) {
+    return {
+        authMode: file.authMode,
+        maxBudgetUsd: opts.maxBudgetUsd ?? file.maxBudgetUsd,
+        claimTtlSec: file.claimTtlSec,
+        once: opts.once,
+        supervise: {
+            maxRetries: file.maxRetries,
+            backoffMs: (attempt) => file.backoffBaseMs * 2 ** attempt, // exponential from the base
+            heartbeat: () => undefined, // a future lease-refresh; liveness tick is a no-op for the CLI run
+        },
+    };
+}
+/** Build the per-lap runner: spawn `claude -p RALPH.md --item <id>`, parse the typed exit. A deadline
+ * overrun (group-SIGKILL) becomes the typed TIMEOUT, NOT a CRASH; a genuine spawn failure rethrows → CRASH. */
+export function makeSpawnLap(cfg, file, runCli = runOneShotCli) {
+    return async (item) => {
+        let stdout;
+        try {
+            stdout = await runCli({
+                cli: file.harness.cli, // Inv 10 — harness is a parameter
+                args: [
+                    '-p',
+                    file.harness.ralphMdPath,
+                    '--item',
+                    item.id,
+                    '--output-format',
+                    'json',
+                    '--max-budget-usd',
+                    String(cfg.maxBudgetUsd),
+                    '--dangerously-skip-permissions',
+                ],
+                prompt: '',
+                timeoutMs: file.wallClockMs,
+                markSubagent: true,
+                timeoutError: () => Object.assign(new Error('lap timeout'), { __timeout: true }),
+            });
+        }
+        catch (e) {
+            if (e.__timeout === true)
+                return { kind: 'TIMEOUT', costUsd: 0 };
+            throw e; // genuine spawn/IO failure → superviseLap maps it to CRASH
+        }
+        const { outcome, costUsd } = parseLapOutcome(stdout);
+        return { ...outcome, costUsd };
+    };
+}
+/** The real chat transport: a one-shot UDS JSON-RPC `send` to the chat-daemon (the live Telegram path
+ * `chat_send` uses). `ok:false` on any unreachable/error so the escalator stays undroppable. */
+export const daemonChatSend = (params) => new Promise((resolve) => {
+    const sock = connect(chatDaemonSockPath());
+    let buf = '';
+    const done = (r) => {
+        try {
+            sock.end();
+        }
+        catch {
+            /* already closed */
+        }
+        resolve(r);
+    };
+    const timer = setTimeout(() => done({ ok: false, reason: 'chat-daemon RPC timeout (5s)' }), 5000);
+    sock.on('error', (e) => {
+        clearTimeout(timer);
+        done({ ok: false, reason: `chat-daemon unreachable: ${e.message}` });
+    });
+    sock.on('data', (d) => {
+        buf += d.toString('utf8');
+        const nl = buf.indexOf('\n');
+        if (nl === -1)
+            return;
+        clearTimeout(timer);
+        try {
+            const res = JSON.parse(buf.slice(0, nl));
+            done(res.error ? { ok: false, reason: res.error.message ?? 'send error' } : { ok: true });
+        }
+        catch (e) {
+            done({ ok: false, reason: e instanceof Error ? e.message : 'bad RPC response' });
+        }
+    });
+    sock.write(JSON.stringify({
+        jsonrpc: '2.0',
+        id: `ralph-${String(Date.now())}`,
+        method: 'send',
+        params: { channel: params.channel, text: params.text },
+    }) + '\n');
+});
+export function registerRalph(program) {
+    const loop = program
+        .command('loop')
+        .description('Run the gated-ralph autonomous loop (composes the work-graph + the coding-flow gate)');
+    loop
+        .option('--once', 'process a single ready item then stop', false)
+        .option('--max-budget-usd <n>', 'API-mode dollar budget for this run (overrides config)')
+        .action(async (opts) => {
+        const file = await readRalphConfig();
+        if (file === null) {
+            process.stderr.write('🦑 loop OFF: no ~/.opensquid/ralph.config.json. Run the wizard first.\n');
+            process.exitCode = 1;
+            return;
+        }
+        const cfg = buildRalphConfig(file, {
+            once: opts.once === true,
+            ...(opts.maxBudgetUsd === undefined ? {} : { maxBudgetUsd: Number(opts.maxBudgetUsd) }),
+        });
+        const wg = workGraphStore({
+            dbUrl: `file:${join(OPENSQUID_HOME(), 'workgraph.db')}`,
+            sourceDir: join(OPENSQUID_HOME(), 'store', 'issues'),
+        });
+        await wg.init();
+        const result = await runRalphLoop(cfg, {
+            wg,
+            claimAudience,
+            runLap: makeSpawnLap(cfg, file),
+            escalate: chatEscalator({ send: daemonChatSend, channel: 'project:telegram' }),
+        });
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    });
+    loop
+        .command('resolve <itemId>')
+        .description('Resolve a parked HUMAN_REQUIRED item (the human-override residual-shrink path)')
+        .option('--misclassified', 'the escalation was principle-settleable — record + un-wedge for another lap', false)
+        .action(async (itemId, opts) => {
+        if (opts.misclassified !== true) {
+            process.stderr.write('Nothing to do: pass --misclassified to record + un-wedge the item.\n');
+            return;
+        }
+        const wg = workGraphStore({
+            dbUrl: `file:${join(OPENSQUID_HOME(), 'workgraph.db')}`,
+            sourceDir: join(OPENSQUID_HOME(), 'store', 'issues'),
+        });
+        await wg.init();
+        await resolveParked(itemId, {
+            wg,
+            recordMisclassification,
+            sessionId: process.env.CLAUDE_SESSION_ID ?? '<cli>',
+            nowIso: new Date().toISOString(),
+        });
+        process.stdout.write(`resolved ${itemId}: misclassification recorded, item un-wedged → back in ready.\n`);
+    });
+    return loop;
+}
+//# sourceMappingURL=ralph.js.map