opensquid 0.5.407 → 0.5.426

package/dist/runtime/hooks/session_id.js

@@ -70,12 +70,7 @@ export async function recordCurrentSession(sessionId, cwd) {
         // pointer and can't clobber this one. Skipped (no error) for a cwd that
         // isn't inside a uuid-bound project (`.opensquid/project.json` absent).
         if (cwd !== undefined && cwd !== '') {
-            const uuid = await resolveProjectUuid({ cwd });
-            if (uuid !== null) {
-                const scoped = projectCurrentSessionPath(uuid);
-                await mkdir(dirname(scoped), { recursive: true });
-                await writeFile(scoped, sessionId, 'utf-8');
-            }
+            await writeSessionPointer(sessionId, cwd, process.env);
         }
     }
     catch {
@@ -102,6 +97,32 @@ export async function readProjectCurrentSession(projectUuid) {
         return null;
     }
 }
+/** wg-16803ed82901: the dir to start the project-uuid walk from for SESSION-POINTER
+ *  purposes — the authoritative project root `CLAUDE_PROJECT_DIR` when set, else the
+ *  local cwd. Internal: the ONLY place the pointer's start dir is decided, so the
+ *  read and write sides can never diverge (the MCP keys on CLAUDE_PROJECT_DIR while a
+ *  session's working cwd may be a sub-repo with its own project card). */
+function pointerUuidStart(cwd, env) {
+    const pd = env.CLAUDE_PROJECT_DIR;
+    return pd !== undefined && pd !== '' ? pd : cwd;
+}
+/** Read the project-scoped live-session id, keyed the ONE canonical way. The single
+ *  chokepoint every reader (resolveMcpSessionId, the handoff CLI, handoff_session_start)
+ *  routes through — no site resolves the pointer uuid itself. */
+export async function readSessionPointer(cwd, env = process.env) {
+    const uuid = await resolveProjectUuid({ cwd: pointerUuidStart(cwd, env), env });
+    return uuid === null ? null : readProjectCurrentSession(uuid);
+}
+/** Write the project-scoped live-session id, keyed the SAME canonical way as the read.
+ *  Best-effort is the caller's contract (recordCurrentSession's try/catch). */
+export async function writeSessionPointer(sessionId, cwd, env = process.env) {
+    const uuid = await resolveProjectUuid({ cwd: pointerUuidStart(cwd, env), env });
+    if (uuid !== null) {
+        const scoped = projectCurrentSessionPath(uuid);
+        await mkdir(dirname(scoped), { recursive: true });
+        await writeFile(scoped, sessionId, 'utf-8');
+    }
+}
 /**
  * FU.7 — does `sessions/<id>/` exist? The existence of the per-session dir
  * (created by the session's own hooks when they first write state) is the
@@ -174,12 +195,9 @@ export async function resolveMcpSessionId() {
         return ccEnv;
     const projectDir = env.CLAUDE_PROJECT_DIR;
     if (projectDir !== undefined && projectDir.length > 0) {
-        const uuid = await resolveProjectUuid({ cwd: projectDir, env });
-        if (uuid !== null) {
-            const scoped = await readProjectCurrentSession(uuid);
-            if (scoped !== null)
-                return scoped;
-        }
+        const scoped = await readSessionPointer(projectDir, env);
+        if (scoped !== null)
+            return scoped;
     }
     return readCurrentSession();
 }

package/dist/runtime/hooks/session_id.js.map

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

package/dist/runtime/protected_paths.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The single writable home for the "is this change docs-only (non-code)?" predicate.
+ *
+ * Shared by the EXECUTE-gate boundary (`src/setup/cli/gate.ts`) and the in-session commit
+ * nudge (via the `staged_docs_only` primitive, `src/functions/staged_docs_only.ts`) so the
+ * two enforcement points can never diverge. A pure leaf — zero imports — so the hot
+ * function-registry layer can import it without dragging in the gate's CLI/runtime chain.
+ *
+ * Imported by: src/setup/cli/gate.ts, src/functions/staged_docs_only.ts.
+ */
+/** The code prefixes the coding-flow protects. A change touching NONE of these is "docs-only"
+ *  (non-code: README, banner, docs/, LICENSE, CI config…). Keep in sync with the
+ *  scope-lifecycle write-gate substrings — the drift pin in gate.test.ts enforces it. */
+export declare const PROTECTED_PREFIXES: readonly ["src/", "packs/", "test/"];
+/** True iff every changed file is OUTSIDE the protected (code) prefixes. Empty set → `false`
+ *  (fail closed: "nothing proves this docs-only"). Paths are git repo-relative. */
+export declare const isDocsOnly: (files: string[]) => boolean;
+//# sourceMappingURL=protected_paths.d.ts.map

package/dist/runtime/protected_paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protected_paths.d.ts","sourceRoot":"","sources":["../../src/runtime/protected_paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;yFAEyF;AACzF,eAAO,MAAM,kBAAkB,sCAAuC,CAAC;AAEvE;mFACmF;AACnF,eAAO,MAAM,UAAU,GAAI,OAAO,MAAM,EAAE,KAAG,OAC6C,CAAC"}

package/dist/runtime/protected_paths.js

@@ -0,0 +1,18 @@
+/**
+ * The single writable home for the "is this change docs-only (non-code)?" predicate.
+ *
+ * Shared by the EXECUTE-gate boundary (`src/setup/cli/gate.ts`) and the in-session commit
+ * nudge (via the `staged_docs_only` primitive, `src/functions/staged_docs_only.ts`) so the
+ * two enforcement points can never diverge. A pure leaf — zero imports — so the hot
+ * function-registry layer can import it without dragging in the gate's CLI/runtime chain.
+ *
+ * Imported by: src/setup/cli/gate.ts, src/functions/staged_docs_only.ts.
+ */
+/** The code prefixes the coding-flow protects. A change touching NONE of these is "docs-only"
+ *  (non-code: README, banner, docs/, LICENSE, CI config…). Keep in sync with the
+ *  scope-lifecycle write-gate substrings — the drift pin in gate.test.ts enforces it. */
+export const PROTECTED_PREFIXES = ['src/', 'packs/', 'test/'];
+/** True iff every changed file is OUTSIDE the protected (code) prefixes. Empty set → `false`
+ *  (fail closed: "nothing proves this docs-only"). Paths are git repo-relative. */
+export const isDocsOnly = (files) => files.length > 0 && files.every((f) => !PROTECTED_PREFIXES.some((p) => f.startsWith(p)));
+//# sourceMappingURL=protected_paths.js.map

package/dist/runtime/protected_paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protected_paths.js","sourceRoot":"","sources":["../../src/runtime/protected_paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;yFAEyF;AACzF,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAU,CAAC;AAEvE;mFACmF;AACnF,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,KAAe,EAAW,EAAE,CACrD,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC"}

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

@@ -0,0 +1,18 @@
+export type DecisionVerdict = 'DECIDE' | 'ESCALATE' | 'DEFER';
+export interface DecisionClassification {
+    verdict: DecisionVerdict;
+    confidence: number;
+    source: 'heuristic';
+    matched: string[];
+}
+/**
+ * Classify a decision. ESCALATE wins over DECIDE when both fire (a destructive boundary in a
+ * cosmetically-worded change is still a boundary). No signal → DEFER (agent decides, Inv 3 → DECIDE).
+ */
+export declare function classifyDecision(decision: string): DecisionClassification;
+/**
+ * Record a misclassification as a session drift event (the residual-shrink path). `expected` is the
+ * verdict that turned out correct (e.g. the agent escalated something the heuristic called DECIDE).
+ */
+export declare function recordMisclassification(sessionId: string, expected: DecisionVerdict, got: DecisionVerdict, decision: string, nowIso: string): Promise<void>;
+//# sourceMappingURL=decision_classifier.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"decision_classifier.d.ts","sourceRoot":"","sources":["../../../src/runtime/ralph/decision_classifier.ts"],"names":[],"mappings":"AAoBA,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,UAAU,GAAG,OAAO,CAAC;AAE9D,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,eAAe,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,WAAW,CAAC;IACpB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AA+BD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,sBAAsB,CAQzE;AAED;;;GAGG;AACH,wBAAsB,uBAAuB,CAC3C,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,eAAe,EACzB,GAAG,EAAE,eAAe,EACpB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAQf"}

package/dist/runtime/ralph/decision_classifier.js

@@ -0,0 +1,72 @@
+/**
+ * GR.2 — the execution-time DECIDE-vs-ESCALATE classifier (deterministic-first).
+ *
+ * When a lap hits a decision, the question is: do the locked principles SETTLE it (DECIDE and proceed,
+ * per [[feedback-no-questions-after-scoping]]) or is it a genuine fork / irreversible boundary that
+ * needs the human (ESCALATE, per Inv 8)? This module is the cheap, deterministic FIRST layer — it fires
+ * only on high-confidence signals and otherwise returns DEFER, meaning "no cheap signal → the in-lap
+ * agent's own judgment decides" (the lap is already an LLM running RALPH.md; a separate `llm_classify`
+ * call would be a redundant second model invocation that also needs the flows executor context — the
+ * simpler-correct design defers ambiguous cases to the agent that already holds the full context).
+ *
+ * Inv 3 bias: DEFER resolves to DECIDE unless the agent itself raises a typed HUMAN_REQUIRED. A
+ * misclassification (an escalation that was principle-settleable, or a barreled-through genuine fork)
+ * is recorded as a drift event → the residual-shrink path (the classifier earns trust through the
+ * existing lesson channel, never assumed correct).
+ *
+ * Imports from: ../drift_catalog.js.
+ */
+import { appendSessionDriftEvent } from '../drift_catalog.js';
+// Irreversible / outward-facing / human-only boundaries → ESCALATE. These ENCODE the "irreversible
+// boundary" principle as deterministic signals (the unambiguous cases the agent must never decide).
+const ESCALATE_SIGNALS = [
+    /\bnpm\s+publish\b/i,
+    /\bpublish\s+(?:the\s+)?(?:package|release|npm)\b/i,
+    /\botp\b/i,
+    /\bforce[-\s]?push\b/i,
+    /\b--force(?:-with-lease)?\b/i,
+    /\bdelete\s+(?:the\s+)?branch\b/i,
+    /\bdrop\s+(?:table|database)\b/i,
+    /\brm\s+-rf\b/i,
+    /\bdeploy\s+to\s+prod(?:uction)?\b/i,
+    /\bgenuine(?:ly)?\s+new\s+product\b/i,
+    /\bwhich\s+(?:product|ux|business)\s+(?:direction|trade-?off)\b/i,
+];
+// Principle-settleable surface decisions → DECIDE (the Simplicity/style principles settle these).
+const DECIDE_SIGNALS = [
+    /\b(?:rename|naming|name)\b/i,
+    /\b(?:format|prettier|lint|whitespace|indent)\b/i,
+    /\b(?:typo|comment|docstring|wording)\b/i,
+    /\b(?:file\s+location|which\s+directory|where\s+to\s+put)\b/i,
+    /\b(?:refactor|extract|inline)\b/i,
+];
+function firstMatches(text, signals) {
+    return signals.filter((re) => re.test(text)).map((re) => re.source);
+}
+/**
+ * Classify a decision. ESCALATE wins over DECIDE when both fire (a destructive boundary in a
+ * cosmetically-worded change is still a boundary). No signal → DEFER (agent decides, Inv 3 → DECIDE).
+ */
+export function classifyDecision(decision) {
+    const esc = firstMatches(decision, ESCALATE_SIGNALS);
+    if (esc.length > 0)
+        return { verdict: 'ESCALATE', confidence: 1, source: 'heuristic', matched: esc };
+    const dec = firstMatches(decision, DECIDE_SIGNALS);
+    if (dec.length > 0)
+        return { verdict: 'DECIDE', confidence: 1, source: 'heuristic', matched: dec };
+    return { verdict: 'DEFER', confidence: 0, source: 'heuristic', matched: [] };
+}
+/**
+ * Record a misclassification as a session drift event (the residual-shrink path). `expected` is the
+ * verdict that turned out correct (e.g. the agent escalated something the heuristic called DECIDE).
+ */
+export async function recordMisclassification(sessionId, expected, got, decision, nowIso) {
+    await appendSessionDriftEvent(sessionId, {
+        timestamp: nowIso,
+        pack: '<session>',
+        ruleId: 'decision-classifier',
+        level: 'surface',
+        message: `MISCLASSIFIED decide-vs-escalate: expected ${expected}, got ${got} — "${decision.slice(0, 120)}"`,
+    });
+}
+//# sourceMappingURL=decision_classifier.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"decision_classifier.js","sourceRoot":"","sources":["../../../src/runtime/ralph/decision_classifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAW9D,mGAAmG;AACnG,oGAAoG;AACpG,MAAM,gBAAgB,GAAsB;IAC1C,oBAAoB;IACpB,mDAAmD;IACnD,UAAU;IACV,sBAAsB;IACtB,8BAA8B;IAC9B,iCAAiC;IACjC,gCAAgC;IAChC,eAAe;IACf,oCAAoC;IACpC,qCAAqC;IACrC,iEAAiE;CAClE,CAAC;AAEF,kGAAkG;AAClG,MAAM,cAAc,GAAsB;IACxC,6BAA6B;IAC7B,iDAAiD;IACjD,yCAAyC;IACzC,6DAA6D;IAC7D,kCAAkC;CACnC,CAAC;AAEF,SAAS,YAAY,CAAC,IAAY,EAAE,OAA0B;IAC5D,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC;AACtE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAgB;IAC/C,MAAM,GAAG,GAAG,YAAY,CAAC,QAAQ,EAAE,gBAAgB,CAAC,CAAC;IACrD,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC;QAChB,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC;IACnF,MAAM,GAAG,GAAG,YAAY,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC;IACnD,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC;QAChB,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC;IACjF,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;AAC/E,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,SAAiB,EACjB,QAAyB,EACzB,GAAoB,EACpB,QAAgB,EAChB,MAAc;IAEd,MAAM,uBAAuB,CAAC,SAAS,EAAE;QACvC,SAAS,EAAE,MAAM;QACjB,IAAI,EAAE,WAAW;QACjB,MAAM,EAAE,qBAAqB;QAC7B,KAAK,EAAE,SAAS;QAChB,OAAO,EAAE,8CAA8C,QAAQ,SAAS,GAAG,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG;KAC5G,CAAC,CAAC;AACL,CAAC"}

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

@@ -0,0 +1,31 @@
+/**
+ * GR.3 — the UNDROPPABLE lap escalation. When a lap returns HUMAN_REQUIRED (or the supervisor exhausts
+ * to UNRECOVERABLE_WEDGE), the orchestrator escalates the typed reason to the human — and a delivery
+ * FAILURE is fatal, never swallowed (Inv 6: no silent death). The actual transport is the existing
+ * critical-tier path (`escalateSeverity` → NotificationRouter multicast); GR.4 injects an adapter so
+ * this module stays decoupled from the notification stack and unit-testable.
+ *
+ * Imported by: src/runtime/ralph/orchestrator.ts (GR.4).
+ */
+import type { HumanRequiredReason } from './lap_outcome.js';
+/** The injected transport. GR.4 wires this to `escalateSeverity` with the user's routing + router. */
+export type LapEscalator = (msg: {
+    reason: HumanRequiredReason;
+    item?: string;
+    payload?: unknown;
+    text: string;
+}) => Promise<{
+    escalated: boolean;
+    reason?: string;
+}>;
+export declare class EscalationUndeliverableError extends Error {
+    readonly humanRequiredReason: HumanRequiredReason;
+    readonly fallthrough: string | undefined;
+    constructor(humanRequiredReason: HumanRequiredReason, fallthrough: string | undefined);
+}
+export declare function escalateLap(reason: HumanRequiredReason, opts: {
+    item?: string;
+    payload?: unknown;
+    escalate: LapEscalator;
+}): Promise<void>;
+//# sourceMappingURL=escalate_lap.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"escalate_lap.d.ts","sourceRoot":"","sources":["../../../src/runtime/ralph/escalate_lap.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAE5D,sGAAsG;AACtG,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,EAAE;IAC/B,MAAM,EAAE,mBAAmB,CAAC;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACd,KAAK,OAAO,CAAC;IAAE,SAAS,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEvD,qBAAa,4BAA6B,SAAQ,KAAK;aAEnC,mBAAmB,EAAE,mBAAmB;aACxC,WAAW,EAAE,MAAM,GAAG,SAAS;gBAD/B,mBAAmB,EAAE,mBAAmB,EACxC,WAAW,EAAE,MAAM,GAAG,SAAS;CAOlD;AAED,wBAAsB,WAAW,CAC/B,MAAM,EAAE,mBAAmB,EAC3B,IAAI,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,YAAY,CAAA;CAAE,GACjE,OAAO,CAAC,IAAI,CAAC,CASf"}

package/dist/runtime/ralph/escalate_lap.js

@@ -0,0 +1,22 @@
+export class EscalationUndeliverableError extends Error {
+    humanRequiredReason;
+    fallthrough;
+    constructor(humanRequiredReason, fallthrough) {
+        super(`gated-ralph escalation UNDELIVERABLE for ${humanRequiredReason}: ${fallthrough ?? 'no channel'}`);
+        this.humanRequiredReason = humanRequiredReason;
+        this.fallthrough = fallthrough;
+        this.name = 'EscalationUndeliverableError';
+    }
+}
+export async function escalateLap(reason, opts) {
+    const text = `🦑 HUMAN_REQUIRED(${reason})${opts.item === undefined ? '' : ` [${opts.item}]`}`;
+    const res = await opts.escalate({
+        reason,
+        text,
+        ...(opts.item === undefined ? {} : { item: opts.item }),
+        ...(opts.payload === undefined ? {} : { payload: opts.payload }),
+    });
+    if (!res.escalated)
+        throw new EscalationUndeliverableError(reason, res.reason); // never silently drop
+}
+//# sourceMappingURL=escalate_lap.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"escalate_lap.js","sourceRoot":"","sources":["../../../src/runtime/ralph/escalate_lap.ts"],"names":[],"mappings":"AAmBA,MAAM,OAAO,4BAA6B,SAAQ,KAAK;IAEnC;IACA;IAFlB,YACkB,mBAAwC,EACxC,WAA+B;QAE/C,KAAK,CACH,4CAA4C,mBAAmB,KAAK,WAAW,IAAI,YAAY,EAAE,CAClG,CAAC;QALc,wBAAmB,GAAnB,mBAAmB,CAAqB;QACxC,gBAAW,GAAX,WAAW,CAAoB;QAK/C,IAAI,CAAC,IAAI,GAAG,8BAA8B,CAAC;IAC7C,CAAC;CACF;AAED,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,MAA2B,EAC3B,IAAkE;IAElE,MAAM,IAAI,GAAG,qBAAqB,MAAM,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,IAAI,GAAG,EAAE,CAAC;IAC/F,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC;QAC9B,MAAM;QACN,IAAI;QACJ,GAAG,CAAC,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC;QACvD,GAAG,CAAC,IAAI,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;KACjE,CAAC,CAAC;IACH,IAAI,CAAC,GAAG,CAAC,SAAS;QAAE,MAAM,IAAI,4BAA4B,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,sBAAsB;AACxG,CAAC"}

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

@@ -0,0 +1,34 @@
+/**
+ * GR.4 — a chat-daemon-backed `LapEscalator` (the gated-ralph escalation transport).
+ *
+ * When a lap returns HUMAN_REQUIRED (or the supervisor exhausts to UNRECOVERABLE_WEDGE), the orchestrator
+ * escalates the typed reason to the HUMAN. The human is on chat (Telegram), so the real escalation path is
+ * the live chat-daemon — the SAME UDS `send` the `chat_send` MCP tool uses. Chosen over `escalateSeverity`
+ * for GR.4-first because the critical-tier NotificationRouter has no runtime assembly yet; the
+ * escalateSeverity critical-tier is a future enhancement (the escalator is injected, so swapping it is local).
+ *
+ * The transport (`send`) is INJECTED so this stays unit-testable without a running daemon; the CLI wires
+ * the real daemon UDS client. UNDROPPABLE (Inv 6): a delivery failure (or a throw) → `{escalated:false}`,
+ * and `escalateLap` (GR.3) then THROWS — the loop never silently drops an escalation.
+ *
+ * Imports from: ./escalate_lap.js (the LapEscalator contract).
+ */
+import type { LapEscalator } from './escalate_lap.js';
+/** The injected chat transport — the CLI wires this to the chat-daemon UDS `send`. */
+export type ChatSend = (params: {
+    channel: string;
+    text: string;
+}) => Promise<{
+    ok: boolean;
+    reason?: string;
+}>;
+/**
+ * Build a `LapEscalator` that delivers the lap's typed `text` to `channel` via the injected chat `send`.
+ * Never throws (the contract reports delivery via `escalated`); a transport error is reported, not swallowed
+ * — `escalateLap` turns a `false` into the undroppable throw.
+ */
+export declare function chatEscalator(deps: {
+    send: ChatSend;
+    channel: string;
+}): LapEscalator;
+//# sourceMappingURL=escalator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"escalator.d.ts","sourceRoot":"","sources":["../../../src/runtime/ralph/escalator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD,sFAAsF;AACtF,MAAM,MAAM,QAAQ,GAAG,CAAC,MAAM,EAAE;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd,KAAK,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEhD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,YAAY,CAWrF"}

package/dist/runtime/ralph/escalator.js

@@ -0,0 +1,19 @@
+/**
+ * Build a `LapEscalator` that delivers the lap's typed `text` to `channel` via the injected chat `send`.
+ * Never throws (the contract reports delivery via `escalated`); a transport error is reported, not swallowed
+ * — `escalateLap` turns a `false` into the undroppable throw.
+ */
+export function chatEscalator(deps) {
+    return async (msg) => {
+        try {
+            const res = await deps.send({ channel: deps.channel, text: msg.text });
+            return res.ok
+                ? { escalated: true }
+                : { escalated: false, reason: res.reason ?? 'send failed' };
+        }
+        catch (e) {
+            return { escalated: false, reason: e instanceof Error ? e.message : String(e) };
+        }
+    };
+}
+//# sourceMappingURL=escalator.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"escalator.js","sourceRoot":"","sources":["../../../src/runtime/ralph/escalator.ts"],"names":[],"mappings":"AAuBA;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,IAAyC;IACrE,OAAO,KAAK,EAAE,GAAG,EAAE,EAAE;QACnB,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;YACvE,OAAO,GAAG,CAAC,EAAE;gBACX,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE;gBACrB,CAAC,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,IAAI,aAAa,EAAE,CAAC;QAChE,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;QAClF,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,43 @@
+/**
+ * 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).
+ */
+/** The only escalation vocabulary — every human-required exit is one of these (Inv 5/8). */
+export type HumanRequiredReason = 'IRREVERSIBLE_BOUNDARY' | 'SCOPE_FORK' | 'UNRECOVERABLE_WEDGE' | 'BUDGET' | 'RATE_BUDGET' | 'BOARD_EMPTY';
+export type LapOutcome = {
+    kind: 'SHIPPED';
+} | {
+    kind: 'HUMAN_REQUIRED';
+    reason: HumanRequiredReason;
+    item?: string;
+    payload?: unknown;
+} | {
+    kind: 'WEDGE';
+} | {
+    kind: 'TIMEOUT';
+} | {
+    kind: 'CRASH';
+};
+/**
+ * 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 declare function extractTypedExit(resultText: string): LapOutcome | null;
+/** Parse the headless JSON envelope into a total `LapOutcome` + the lap's cost. Never throws. */
+export declare function parseLapOutcome(stdout: string): {
+    outcome: LapOutcome;
+    costUsd: number;
+};
+//# sourceMappingURL=lap_outcome.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lap_outcome.d.ts","sourceRoot":"","sources":["../../../src/runtime/ralph/lap_outcome.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,4FAA4F;AAC5F,MAAM,MAAM,mBAAmB,GAC3B,uBAAuB,GACvB,YAAY,GACZ,qBAAqB,GACrB,QAAQ,GACR,aAAa,GACb,aAAa,CAAC;AAElB,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,mBAAmB,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GACzF;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GACjB;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAgBtB;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAkCtE;AAED,iGAAiG;AACjG,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAcxF"}

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"}