@bluewombat/runtime 0.10.0 → 0.11.1

package/dist/operator/supervise/council.d.ts

@@ -0,0 +1,45 @@
+import type { SupervisorConfig } from "./config.js";
+import { type Decision } from "./decision.js";
+import { type Exec } from "./exec.js";
+import { type Brief } from "./prompts.js";
+export type Deliberation = {
+    ok: true;
+    decision: Decision;
+    reports: Record<string, string>;
+} | {
+    ok: false;
+    reason: string;
+    reports: Record<string, string>;
+};
+export type AgentRunInput = {
+    config: SupervisorConfig;
+    exec: Exec;
+    role: string;
+    prompt: string;
+    /** Where the prompt and the answer are filed. */
+    dir: string;
+    cwd: string;
+    addDirs: string[];
+};
+/** One agent, once: its prompt written down, its answer kept. */
+export declare function runAgent(input: AgentRunInput): Promise<{
+    ok: boolean;
+    text: string;
+}>;
+/**
+ * Three members read the same stop from different seats; an arbiter decides.
+ *
+ * The members run together and apart: none sees another's answer, so they
+ * cannot settle on the first idea. The arbiter sees all three and the code.
+ * A member that fails does not stop the others; fewer than two answers is no
+ * council. An arbiter whose answer is refused for its shape has it corrected by a small
+ * agent from its own text; one that fails is asked again as before.
+ */
+export declare function deliberate(input: {
+    config: SupervisorConfig;
+    exec: Exec;
+    brief: Brief;
+    dir: string;
+    cwd: string;
+}): Promise<Deliberation>;
+//# sourceMappingURL=council.d.ts.map

package/dist/operator/supervise/council.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"council.d.ts","sourceRoot":"","sources":["../../../src/operator/supervise/council.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,KAAK,QAAQ,EAA2B,MAAM,eAAe,CAAC;AACvE,OAAO,EAAE,KAAK,IAAI,EAA0C,MAAM,WAAW,CAAC;AAC9E,OAAO,EAEL,KAAK,KAAK,EAKX,MAAM,cAAc,CAAC;AAEtB,MAAM,MAAM,YAAY,GACpB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GACjE;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CAAC;AAWnE,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,EAAE,gBAAgB,CAAC;IACzB,IAAI,EAAE,IAAI,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,CAAC;AAEF,iEAAiE;AACjE,wBAAsB,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAoB3F;AAWD;;;;;;;;GAQG;AACH,wBAAsB,UAAU,CAAC,KAAK,EAAE;IACtC,MAAM,EAAE,gBAAgB,CAAC;IACzB,IAAI,EAAE,IAAI,CAAC;IACX,KAAK,EAAE,KAAK,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb,GAAG,OAAO,CAAC,YAAY,CAAC,CAqDxB"}

package/dist/operator/supervise/council.js

@@ -0,0 +1,97 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { lastJson, parseDecision } from "./decision.js";
+import { fill, succeeded, tail } from "./exec.js";
+import { arbiterPrompt, formPrompt, remedyPrompt, rootcausePrompt, skepticPrompt, } from "./prompts.js";
+const ANALYSTS = [
+    ["rootcause", rootcausePrompt],
+    ["remedy", remedyPrompt],
+    ["skeptic", skepticPrompt],
+];
+/** Cap what one member's report adds to the arbiter's page. */
+const REPORT_CHARS = 30_000;
+/** One agent, once: its prompt written down, its answer kept. */
+export async function runAgent(input) {
+    mkdirSync(input.dir, { recursive: true });
+    const promptFile = join(input.dir, `${input.role}.prompt.md`);
+    writeFileSync(promptFile, input.prompt);
+    const spec = input.config.agents[input.role];
+    if (spec === undefined) {
+        return { ok: false, text: `no agent configured for ${input.role}` };
+    }
+    const result = await input.exec(fill(spec.cmd, { prompt: input.prompt, promptFile }, { addDirArgs: input.addDirs.flatMap((dir) => ["--add-dir", dir]) }), { cwd: input.cwd, timeoutMs: spec.timeoutMs });
+    const ok = succeeded(result) || answeredBeforeCeiling(result);
+    const text = ok ? result.stdout : tail(result);
+    writeFileSync(join(input.dir, `${input.role}.out.md`), text);
+    return { ok, text };
+}
+/**
+ * Every role ends its answer with a JSON block. An agent cut at its ceiling
+ * after writing one finished its work: the answer is kept, not counted as lost.
+ */
+function answeredBeforeCeiling(result) {
+    const value = result.atCeiling === true ? lastJson(result.stdout) : undefined;
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Three members read the same stop from different seats; an arbiter decides.
+ *
+ * The members run together and apart: none sees another's answer, so they
+ * cannot settle on the first idea. The arbiter sees all three and the code.
+ * A member that fails does not stop the others; fewer than two answers is no
+ * council. An arbiter whose answer is refused for its shape has it corrected by a small
+ * agent from its own text; one that fails is asked again as before.
+ */
+export async function deliberate(input) {
+    const addDirs = [...new Set([...input.brief.codeRoots, input.brief.ledgerRoot])];
+    const base = { config: input.config, exec: input.exec, dir: input.dir, cwd: input.cwd, addDirs };
+    const answers = await Promise.all(ANALYSTS.map(async ([role, prompt]) => ({
+        role,
+        ...(await runAgent({ ...base, role, prompt: prompt(input.brief) })),
+    })));
+    const reports = {};
+    for (const answer of answers) {
+        if (answer.ok) {
+            reports[answer.role] = answer.text.slice(-REPORT_CHARS);
+        }
+    }
+    if (Object.keys(reports).length < 2) {
+        return {
+            ok: false,
+            reason: `only ${Object.keys(reports).length} of ${ANALYSTS.length} members answered: ${answers
+                .filter((a) => !a.ok)
+                .map((a) => `${a.role}: ${a.text.slice(0, 200)}`)
+                .join(" | ")}`,
+            reports,
+        };
+    }
+    const targets = input.config.targets.map((target) => target.name);
+    const prompt = arbiterPrompt(input.brief, reports);
+    let reason = "";
+    for (let round = 0; round < 2; round++) {
+        const arbiter = await runAgent({ ...base, role: "arbiter", prompt });
+        if (!arbiter.ok) {
+            reason = `the arbiter failed: ${arbiter.text.slice(0, 300)}`;
+            continue;
+        }
+        const parsed = parseDecision(arbiter.text, targets);
+        if (parsed.ok) {
+            return { ok: true, decision: parsed.decision, reports };
+        }
+        reason = `the arbiter's answer was refused: ${parsed.reason}`;
+        const corrected = await runAgent({
+            ...base,
+            role: "reformatter",
+            prompt: formPrompt(arbiter.text, parsed.reason),
+            addDirs: [],
+        });
+        const again = corrected.ok ? parseDecision(corrected.text, targets) : undefined;
+        if (again?.ok) {
+            return { ok: true, decision: again.decision, reports };
+        }
+        reason = `the arbiter's answer was refused: ${again === undefined ? parsed.reason : again.reason}`;
+        break;
+    }
+    return { ok: false, reason, reports };
+}
+//# sourceMappingURL=council.js.map

package/dist/operator/supervise/council.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"council.js","sourceRoot":"","sources":["../../../src/operator/supervise/council.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAiB,QAAQ,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACvE,OAAO,EAA8B,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC9E,OAAO,EACL,aAAa,EAEb,UAAU,EACV,YAAY,EACZ,eAAe,EACf,aAAa,GACd,MAAM,cAAc,CAAC;AAMtB,MAAM,QAAQ,GAAG;IACf,CAAC,WAAW,EAAE,eAAe,CAAC;IAC9B,CAAC,QAAQ,EAAE,YAAY,CAAC;IACxB,CAAC,SAAS,EAAE,aAAa,CAAC;CAClB,CAAC;AAEX,+DAA+D;AAC/D,MAAM,YAAY,GAAG,MAAM,CAAC;AAa5B,iEAAiE;AACjE,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,KAAoB;IACjD,SAAS,CAAC,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1C,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,IAAI,YAAY,CAAC,CAAC;IAC9D,aAAa,CAAC,UAAU,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACxC,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC7C,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,2BAA2B,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;IACtE,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,IAAI,CAC7B,IAAI,CACF,IAAI,CAAC,GAAG,EACR,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,UAAU,EAAE,EACpC,EAAE,UAAU,EAAE,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,EAAE,CACnE,EACD,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAC9C,CAAC;IACF,MAAM,EAAE,GAAG,SAAS,CAAC,MAAM,CAAC,IAAI,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAC9D,MAAM,IAAI,GAAG,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC/C,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,IAAI,SAAS,CAAC,EAAE,IAAI,CAAC,CAAC;IAC7D,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;AACtB,CAAC;AAED;;;GAGG;AACH,SAAS,qBAAqB,CAAC,MAAkB;IAC/C,MAAM,KAAK,GAAG,MAAM,CAAC,SAAS,KAAK,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC9E,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,KAMhC;IACC,MAAM,OAAO,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IACjF,MAAM,IAAI,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,CAAC;IACjG,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAC/B,QAAQ,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC;QACtC,IAAI;QACJ,GAAG,CAAC,MAAM,QAAQ,CAAC,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;KACpE,CAAC,CAAC,CACJ,CAAC;IACF,MAAM,OAAO,GAA2B,EAAE,CAAC;IAC3C,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;YACd,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,YAAY,CAAC,CAAC;QAC1D,CAAC;IACH,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpC,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,QAAQ,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,OAAO,QAAQ,CAAC,MAAM,sBAAsB,OAAO;iBAC3F,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;iBACpB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;iBAChD,IAAI,CAAC,KAAK,CAAC,EAAE;YAChB,OAAO;SACR,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAClE,MAAM,MAAM,GAAG,aAAa,CAAC,KAAK,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACnD,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC;QACvC,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC;QACrE,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC;YAChB,MAAM,GAAG,uBAAuB,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;YAC7D,SAAS;QACX,CAAC;QACD,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACpD,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;YACd,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,OAAO,EAAE,CAAC;QAC1D,CAAC;QACD,MAAM,GAAG,qCAAqC,MAAM,CAAC,MAAM,EAAE,CAAC;QAC9D,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC;YAC/B,GAAG,IAAI;YACP,IAAI,EAAE,aAAa;YACnB,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC;YAC/C,OAAO,EAAE,EAAE;SACZ,CAAC,CAAC;QACH,MAAM,KAAK,GAAG,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,SAAS,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAChF,IAAI,KAAK,EAAE,EAAE,EAAE,CAAC;YACd,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,OAAO,EAAE,CAAC;QACzD,CAAC;QACD,MAAM,GAAG,qCAAqC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;QACnG,MAAM;IACR,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;AACxC,CAAC"}

package/dist/operator/supervise/decision.d.ts

@@ -0,0 +1,46 @@
+export declare const UNBLOCK_KINDS: readonly ["resume", "restart", "cancel", "start-worker", "restart-worker", "cleanup-disk"];
+export type UnblockKind = (typeof UNBLOCK_KINDS)[number];
+/** What puts the run back in motion, now or once the fixes have landed. */
+export type Unblock = {
+    do: UnblockKind;
+    key?: string;
+    reason: string;
+};
+/** A change to a repository the supervisor was given, so that this does not happen again. */
+export type Fix = {
+    target: string;
+    title: string;
+    /** The result to reach and what proves it, inside the rules. Not the design: the fixer designs. */
+    instruction: string;
+    /** The rules and accepted decisions the change touches, and why it conforms to each. */
+    conformity: string;
+    /**
+     * Set when no change can reach the result without revisiting an accepted decision or rule: which one.
+     * Such a fix is not made; a person decides.
+     */
+    revises?: string;
+};
+export type Decision = {
+    summary: string;
+    cause: string;
+    /** `file:line`, a log line, a command and what it printed. Nothing that was not seen. */
+    evidence: string[];
+    confidence: "high" | "medium" | "low";
+    /** The unblock needs the fixes first (the same stop would come straight back). */
+    unblockAfterFixes: boolean;
+    unblock: Unblock[];
+    fixes: Fix[];
+    /** Set when no one but a person can go on: what only they can decide. */
+    needsHuman?: string;
+};
+export type Parsed = {
+    ok: true;
+    decision: Decision;
+} | {
+    ok: false;
+    reason: string;
+};
+/** The last JSON object an agent printed: in a ```json fence, else the last balanced braces. */
+export declare function lastJson(output: string): unknown;
+export declare function parseDecision(output: string, targets: readonly string[]): Parsed;
+//# sourceMappingURL=decision.d.ts.map

package/dist/operator/supervise/decision.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision.d.ts","sourceRoot":"","sources":["../../../src/operator/supervise/decision.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,aAAa,4FAOhB,CAAC;AACX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzD,2EAA2E;AAC3E,MAAM,MAAM,OAAO,GAAG;IAAE,EAAE,EAAE,WAAW,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAExE,6FAA6F;AAC7F,MAAM,MAAM,GAAG,GAAG;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,mGAAmG;IACnG,WAAW,EAAE,MAAM,CAAC;IACpB,wFAAwF;IACxF,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,yFAAyF;IACzF,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IACtC,kFAAkF;IAClF,iBAAiB,EAAE,OAAO,CAAC;IAC3B,OAAO,EAAE,OAAO,EAAE,CAAC;IACnB,KAAK,EAAE,GAAG,EAAE,CAAC;IACb,yEAAyE;IACzE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,MAAM,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAItF,gGAAgG;AAChG,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAqBhD;AAUD,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CA2GhF"}

package/dist/operator/supervise/decision.js

@@ -0,0 +1,137 @@
+export const UNBLOCK_KINDS = [
+    "resume",
+    "restart",
+    "cancel",
+    "start-worker",
+    "restart-worker",
+    "cleanup-disk",
+];
+const NEEDS_KEY = ["resume", "restart", "cancel"];
+/** The last JSON object an agent printed: in a ```json fence, else the last balanced braces. */
+export function lastJson(output) {
+    const fenced = [...output.matchAll(/```json\s*([\s\S]*?)```/g)].map((m) => m[1] ?? "");
+    for (const body of fenced.reverse()) {
+        const value = tryParse(body);
+        if (value !== undefined) {
+            return value;
+        }
+    }
+    for (let end = output.lastIndexOf("}"); end >= 0; end = output.lastIndexOf("}", end - 1)) {
+        for (let start = output.lastIndexOf("{", end); start >= 0; start = output.lastIndexOf("{", start - 1)) {
+            const value = tryParse(output.slice(start, end + 1));
+            if (value !== undefined) {
+                return value;
+            }
+        }
+    }
+    return undefined;
+}
+function tryParse(body) {
+    try {
+        return JSON.parse(body);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function parseDecision(output, targets) {
+    const value = lastJson(output);
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return { ok: false, reason: "no JSON object in the arbiter's answer" };
+    }
+    const o = value;
+    const problems = [];
+    const str = (name) => {
+        const v = o[name];
+        if (typeof v !== "string" || v.trim().length === 0) {
+            problems.push(`${name} must be a non-empty string`);
+            return "";
+        }
+        return v;
+    };
+    const summary = str("summary");
+    const cause = str("cause");
+    const evidence = Array.isArray(o.evidence) ? o.evidence.map(String) : [];
+    if (evidence.length === 0) {
+        problems.push("evidence must name what was seen");
+    }
+    const confidence = o.confidence;
+    if (confidence !== "high" && confidence !== "medium" && confidence !== "low") {
+        problems.push("confidence must be high, medium or low");
+    }
+    const unblock = [];
+    for (const raw of Array.isArray(o.unblock) ? o.unblock : []) {
+        const u = (raw ?? {});
+        const kind = UNBLOCK_KINDS.find((k) => k === u.do);
+        if (kind === undefined) {
+            problems.push(`unblock.do ${JSON.stringify(u.do)} is not one of ${UNBLOCK_KINDS.join(", ")}`);
+            continue;
+        }
+        if (NEEDS_KEY.includes(kind) && typeof u.key !== "string") {
+            problems.push(`unblock ${kind} needs a key`);
+            continue;
+        }
+        unblock.push({
+            do: kind,
+            ...(typeof u.key === "string" ? { key: u.key } : {}),
+            reason: typeof u.reason === "string" ? u.reason : "",
+        });
+    }
+    const fixes = [];
+    for (const raw of Array.isArray(o.fixes) ? o.fixes : []) {
+        const f = (raw ?? {});
+        if (typeof f.target !== "string" || !targets.includes(f.target)) {
+            problems.push(`fix.target ${JSON.stringify(f.target)} is not one of ${targets.join(", ") || "(none configured)"}`);
+            continue;
+        }
+        if (typeof f.title !== "string" ||
+            typeof f.instruction !== "string" ||
+            f.instruction.length < 20) {
+            problems.push("a fix needs a title and an instruction a stranger could carry out");
+            continue;
+        }
+        if (typeof f.conformity !== "string" || f.conformity.trim().length < 20) {
+            problems.push("a fix needs its conformity: the rules and accepted decisions it touches, and why it conforms");
+            continue;
+        }
+        fixes.push({
+            target: f.target,
+            title: f.title,
+            instruction: f.instruction,
+            conformity: f.conformity,
+            ...(typeof f.revises === "string" && f.revises.trim().length > 0
+                ? { revises: f.revises }
+                : {}),
+        });
+    }
+    const asked = typeof o.needsHuman === "string" && o.needsHuman.length > 0 ? o.needsHuman : undefined;
+    if (asked !== undefined && unblock.length > 0) {
+        problems.push("needsHuman and unblock contradict: a stop for a person is not resumed");
+    }
+    // A change that would revisit an accepted decision is a product choice, not the supervisor's.
+    const revising = fixes.filter((fix) => fix.revises !== undefined);
+    const needsHuman = asked ??
+        (revising.length === 0
+            ? undefined
+            : `A person must decide: ${revising.map((fix) => `"${fix.title}" would revise ${fix.revises}`).join("; ")}.`);
+    if (o.unblockAfterFixes === true && unblock.length === 0) {
+        problems.push("unblockAfterFixes is true but there is nothing to unblock");
+    }
+    if (problems.length > 0) {
+        return { ok: false, reason: problems.join("; ") };
+    }
+    return {
+        ok: true,
+        decision: {
+            summary,
+            cause,
+            evidence,
+            confidence: confidence,
+            unblockAfterFixes: o.unblockAfterFixes === true,
+            unblock,
+            fixes,
+            ...(needsHuman === undefined ? {} : { needsHuman }),
+        },
+    };
+}
+//# sourceMappingURL=decision.js.map

package/dist/operator/supervise/decision.js.map

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

package/dist/operator/supervise/exec.d.ts

@@ -0,0 +1,28 @@
+export type ExecResult = {
+    /** Null when the command never ran or was cut at its ceiling. */
+    code: number | null;
+    stdout: string;
+    stderr: string;
+    /** Milliseconds the clock ran while the supervisor did not (machine asleep, paused). */
+    suspendedMs?: number;
+    /** The ceiling ended it; what it wrote before is in `stdout`. */
+    atCeiling?: boolean;
+    /** Why it did not run to its end, when it did not. */
+    error?: string;
+};
+export type Exec = (cmd: string[], options: {
+    cwd?: string;
+    timeoutMs: number;
+}) => Promise<ExecResult>;
+/** The supervisor's one way to start anything: a command, a ceiling, a result. Never throws. */
+export declare const exec: Exec;
+/**
+ * Replace `{name}` in each word of a command. A name nobody gave stays as
+ * written. A word that is only `{name}` and names a list becomes that list's
+ * words, so `{addDirArgs}` can stand for any number of `--add-dir X` pairs.
+ */
+export declare function fill(cmd: string[], vars: Record<string, string>, lists?: Record<string, string[]>): string[];
+export declare function succeeded(result: ExecResult): boolean;
+/** What a failed command said, cut to what a reader needs. */
+export declare function tail(result: ExecResult, chars?: number): string;
+//# sourceMappingURL=exec.d.ts.map

package/dist/operator/supervise/exec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec.d.ts","sourceRoot":"","sources":["../../../src/operator/supervise/exec.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,UAAU,GAAG;IACvB,iEAAiE;IACjE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,wFAAwF;IACxF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,sDAAsD;IACtD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,IAAI,GAAG,CACjB,GAAG,EAAE,MAAM,EAAE,EACb,OAAO,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,KACzC,OAAO,CAAC,UAAU,CAAC,CAAC;AAEzB,gGAAgG;AAChG,eAAO,MAAM,IAAI,EAAE,IAmBlB,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,IAAI,CAClB,GAAG,EAAE,MAAM,EAAE,EACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,KAAK,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAM,GACnC,MAAM,EAAE,CAQV;AAED,wBAAgB,SAAS,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAErD;AAED,8DAA8D;AAC9D,wBAAgB,IAAI,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,SAAO,GAAG,MAAM,CAK7D"}

package/dist/operator/supervise/exec.js

@@ -0,0 +1,47 @@
+import { runSlot } from "../../loop/run-slot.js";
+/** The supervisor's one way to start anything: a command, a ceiling, a result. Never throws. */
+export const exec = async (cmd, options) => {
+    const [command, ...args] = cmd;
+    if (command === undefined) {
+        return { code: null, stdout: "", stderr: "", error: "empty command" };
+    }
+    const run = await runSlot({
+        command,
+        args,
+        ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+        timeoutMs: options.timeoutMs,
+    });
+    return {
+        code: run.status,
+        stdout: run.stdout,
+        stderr: run.stderr,
+        ...(run.atCeiling ? { atCeiling: true } : {}),
+        ...(run.suspendedMs > 0 ? { suspendedMs: run.suspendedMs } : {}),
+        ...(run.error === undefined ? {} : { error: run.error.message }),
+    };
+};
+/**
+ * Replace `{name}` in each word of a command. A name nobody gave stays as
+ * written. A word that is only `{name}` and names a list becomes that list's
+ * words, so `{addDirArgs}` can stand for any number of `--add-dir X` pairs.
+ */
+export function fill(cmd, vars, lists = {}) {
+    return cmd.flatMap((word) => {
+        const whole = /^\{(\w+)\}$/.exec(word)?.[1];
+        if (whole !== undefined && lists[whole] !== undefined) {
+            return lists[whole];
+        }
+        return [word.replace(/\{(\w+)\}/g, (all, name) => vars[name] ?? all)];
+    });
+}
+export function succeeded(result) {
+    return result.code === 0 && result.error === undefined;
+}
+/** What a failed command said, cut to what a reader needs. */
+export function tail(result, chars = 4000) {
+    const text = [result.error, result.stderr, result.stdout]
+        .filter((part) => part !== undefined && part.length > 0)
+        .join("\n");
+    return text.length > chars ? `…${text.slice(-chars)}` : text;
+}
+//# sourceMappingURL=exec.js.map

package/dist/operator/supervise/exec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec.js","sourceRoot":"","sources":["../../../src/operator/supervise/exec.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAoBjD,gGAAgG;AAChG,MAAM,CAAC,MAAM,IAAI,GAAS,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE;IAC/C,MAAM,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,GAAG,GAAG,CAAC;IAC/B,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,eAAe,EAAE,CAAC;IACxE,CAAC;IACD,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC;QACxB,OAAO;QACP,IAAI;QACJ,GAAG,CAAC,OAAO,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC;QAC1D,SAAS,EAAE,OAAO,CAAC,SAAS;KAC7B,CAAC,CAAC;IACH,OAAO;QACL,IAAI,EAAE,GAAG,CAAC,MAAM;QAChB,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7C,GAAG,CAAC,GAAG,CAAC,WAAW,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAChE,GAAG,CAAC,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;KACjE,CAAC;AACJ,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,IAAI,CAClB,GAAa,EACb,IAA4B,EAC5B,QAAkC,EAAE;IAEpC,OAAO,GAAG,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE;QAC1B,MAAM,KAAK,GAAG,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QAC5C,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,KAAK,CAAC,KAAK,SAAS,EAAE,CAAC;YACtD,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC;IACxE,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,MAAkB;IAC1C,OAAO,MAAM,CAAC,IAAI,KAAK,CAAC,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS,CAAC;AACzD,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,IAAI,CAAC,MAAkB,EAAE,KAAK,GAAG,IAAI;IACnD,MAAM,IAAI,GAAG,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC;SACtD,MAAM,CAAC,CAAC,IAAI,EAAkB,EAAE,CAAC,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;SACvE,IAAI,CAAC,IAAI,CAAC,CAAC;IACd,OAAO,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAC/D,CAAC"}

package/dist/operator/supervise/memory.d.ts

@@ -0,0 +1,33 @@
+/** What the supervisor did about one subject, so that it does not do it forever. */
+export type Entry = {
+    attempts: number;
+    /** The last thing seen, as `observe` fingerprints it. */
+    fingerprint: string;
+    lastAt: number;
+    /** Handed to a person: nothing more is tried until the subject changes or ends. */
+    human: boolean;
+    /** One line each: what was decided and how it went. Fed back to the next council. */
+    history: string[];
+};
+export type Memory = {
+    entries: Record<string, Entry>;
+};
+export declare function loadMemory(dir: string): Memory;
+export declare function saveMemory(dir: string, memory: Memory): void;
+/** Append-only film of what the supervisor saw and did. Not truth: the ledger is. */
+export declare function note(dir: string, line: Record<string, unknown>, now?: () => Date): void;
+/**
+ * Whether this finding is the supervisor's to handle now.
+ *
+ * Not while a person holds it. Not while what it did last time may still be
+ * taking effect (the same thing seen again inside the cooldown). A different
+ * fingerprint is a different problem and starts again at the cost already paid.
+ */
+export declare function due(entry: Entry | undefined, fingerprint: string, now: number, cooldownMs: number): boolean;
+export declare function spent(entry: Entry | undefined, maxAttempts: number): boolean;
+/** Take one attempt at `subject`. */
+export declare function attempt(memory: Memory, subject: string, fingerprint: string, now: number): Entry;
+export declare function remember(entry: Entry, line: string): void;
+/** Forget what was kept of a subject that reached an end. */
+export declare function forgetKeys(memory: Memory, keys: string[]): void;
+//# sourceMappingURL=memory.d.ts.map

package/dist/operator/supervise/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../../src/operator/supervise/memory.ts"],"names":[],"mappings":"AAGA,oFAAoF;AACpF,MAAM,MAAM,KAAK,GAAG;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,mFAAmF;IACnF,KAAK,EAAE,OAAO,CAAC;IACf,qFAAqF;IACrF,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,MAAM,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;CAAE,CAAC;AAIxD,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAO9C;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAK5D;AAED,qFAAqF;AACrF,wBAAgB,IAAI,CAClB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,GAAG,GAAE,MAAM,IAAuB,GACjC,IAAI,CAMN;AAED;;;;;;GAMG;AACH,wBAAgB,GAAG,CACjB,KAAK,EAAE,KAAK,GAAG,SAAS,EACxB,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,GACjB,OAAO,CAQT;AAED,wBAAgB,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAE5E;AAED,qCAAqC;AACrC,wBAAgB,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,KAAK,CAchG;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAKzD;AAED,6DAA6D;AAC7D,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAM/D"}

package/dist/operator/supervise/memory.js

@@ -0,0 +1,73 @@
+import { appendFileSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+const FILE = "memory.json";
+export function loadMemory(dir) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(dir, FILE), "utf8"));
+        return { entries: parsed.entries ?? {} };
+    }
+    catch {
+        return { entries: {} };
+    }
+}
+export function saveMemory(dir, memory) {
+    mkdirSync(dir, { recursive: true });
+    const tmp = join(dir, `${FILE}.tmp`);
+    writeFileSync(tmp, `${JSON.stringify(memory, null, 2)}\n`);
+    renameSync(tmp, join(dir, FILE));
+}
+/** Append-only film of what the supervisor saw and did. Not truth: the ledger is. */
+export function note(dir, line, now = () => new Date()) {
+    mkdirSync(dir, { recursive: true });
+    appendFileSync(join(dir, "events.jsonl"), `${JSON.stringify({ ...line, at: now().toISOString() })}\n`);
+}
+/**
+ * Whether this finding is the supervisor's to handle now.
+ *
+ * Not while a person holds it. Not while what it did last time may still be
+ * taking effect (the same thing seen again inside the cooldown). A different
+ * fingerprint is a different problem and starts again at the cost already paid.
+ */
+export function due(entry, fingerprint, now, cooldownMs) {
+    if (entry === undefined) {
+        return true;
+    }
+    if (entry.human) {
+        return entry.fingerprint !== fingerprint;
+    }
+    return entry.fingerprint !== fingerprint || now - entry.lastAt >= cooldownMs;
+}
+export function spent(entry, maxAttempts) {
+    return entry !== undefined && entry.attempts >= maxAttempts;
+}
+/** Take one attempt at `subject`. */
+export function attempt(memory, subject, fingerprint, now) {
+    const entry = memory.entries[subject] ?? {
+        attempts: 0,
+        fingerprint,
+        lastAt: now,
+        human: false,
+        history: [],
+    };
+    entry.attempts += 1;
+    entry.fingerprint = fingerprint;
+    entry.lastAt = now;
+    entry.human = false;
+    memory.entries[subject] = entry;
+    return entry;
+}
+export function remember(entry, line) {
+    entry.history.push(line);
+    if (entry.history.length > 8) {
+        entry.history.splice(0, entry.history.length - 8);
+    }
+}
+/** Forget what was kept of a subject that reached an end. */
+export function forgetKeys(memory, keys) {
+    for (const subject of Object.keys(memory.entries)) {
+        if (keys.some((key) => subject.endsWith(`:${key}`))) {
+            delete memory.entries[subject];
+        }
+    }
+}
+//# sourceMappingURL=memory.js.map

package/dist/operator/supervise/memory.js.map

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

package/dist/operator/supervise/observe.d.ts

@@ -0,0 +1,47 @@
+export type Item = {
+    key: string;
+    scope: "ticket" | "feature";
+    state: string;
+    escalation?: {
+        report?: string;
+        refusedBy?: string;
+        at?: number;
+    };
+};
+/** What the supervisor can see of a run without asking anyone. */
+export type Snapshot = {
+    now: number;
+    items: Item[];
+    /** The process that holds the ledger, when it is alive. */
+    workerPid?: number;
+    /** When the journal last grew. */
+    journalAt?: number;
+    freeBytes?: number;
+    /** The supervisor is able to start a worker, so a missing one is its to fix. */
+    canStartWorker: boolean;
+};
+export type Thresholds = {
+    stallAfterMs: number;
+    diskMinBytes: number;
+    settleMs: number;
+};
+export type Finding = {
+    kind: "escalated" | "stalled" | "worker-down" | "disk-low";
+    /** What the memory is keyed by: one per thing that can go wrong in one place. */
+    subject: string;
+    /** Changes when the thing that went wrong changes. */
+    fingerprint: string;
+    key?: string;
+    scope?: "ticket" | "feature";
+    detail: string;
+};
+/**
+ * What is wrong, from what can be seen. Pure: no ledger, no clock, no disk.
+ *
+ * Judging is not done here. A finding says that something needs looking at,
+ * and carries enough to tell it from the same thing seen again.
+ */
+export declare function observe(snapshot: Snapshot, limits: Thresholds): Finding[];
+/** Keys that reached an end: whatever the supervisor remembered of them is spent. */
+export declare function finished(items: Item[]): string[];
+//# sourceMappingURL=observe.d.ts.map

package/dist/operator/supervise/observe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../../../src/operator/supervise/observe.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,IAAI,GAAG;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACnE,CAAC;AAEF,kEAAkE;AAClE,MAAM,MAAM,QAAQ,GAAG;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,cAAc,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1F,MAAM,MAAM,OAAO,GAAG;IACpB,IAAI,EAAE,WAAW,GAAG,SAAS,GAAG,aAAa,GAAG,UAAU,CAAC;IAC3D,iFAAiF;IACjF,OAAO,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAKF;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,EAAE,CAoDzE;AAED,qFAAqF;AACrF,wBAAgB,QAAQ,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,MAAM,EAAE,CAEhD"}