@bluewombat/runtime 0.11.0 → 0.11.1

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

package/dist/operator/supervise/observe.js

@@ -0,0 +1,73 @@
+import { createHash } from "node:crypto";
+const ACTIVE = new Set(["running", "integrating", "submitted", "merging", "open"]);
+const TERMINAL = new Set(["done", "cancelled", "invalid"]);
+/**
+ * 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 function observe(snapshot, limits) {
+    const found = [];
+    if (snapshot.workerPid === undefined && snapshot.canStartWorker) {
+        found.push({
+            kind: "worker-down",
+            subject: "worker",
+            fingerprint: "worker-down",
+            detail: "No process holds the ledger.",
+        });
+    }
+    const active = snapshot.items.filter((item) => ACTIVE.has(item.state));
+    if (snapshot.workerPid !== undefined &&
+        snapshot.journalAt !== undefined &&
+        active.length > 0 &&
+        snapshot.now - snapshot.journalAt > limits.stallAfterMs) {
+        const minutes = Math.round((snapshot.now - snapshot.journalAt) / 60_000);
+        const oldest = active[0];
+        found.push({
+            kind: "stalled",
+            subject: `stalled:${oldest?.key ?? "?"}`,
+            fingerprint: `stalled:${active.map((item) => `${item.key}=${item.state}`).join(",")}`,
+            ...(oldest === undefined ? {} : { key: oldest.key, scope: oldest.scope }),
+            detail: `The journal has been silent for ${minutes} min with ${active.length} active: ${active
+                .map((item) => `${item.key} (${item.state})`)
+                .join(", ")}.`,
+        });
+    }
+    if (snapshot.freeBytes !== undefined && snapshot.freeBytes < limits.diskMinBytes) {
+        found.push({
+            kind: "disk-low",
+            subject: "disk",
+            fingerprint: "disk-low",
+            detail: `${(snapshot.freeBytes / 1024 ** 3).toFixed(1)} GiB free, under ${(limits.diskMinBytes / 1024 ** 3).toFixed(1)} GiB.`,
+        });
+    }
+    for (const item of snapshot.items) {
+        if (item.state !== "escalated" || youngerThanSettle(item, snapshot.now, limits.settleMs)) {
+            continue;
+        }
+        const report = item.escalation?.report ?? "";
+        found.push({
+            kind: "escalated",
+            subject: `escalated:${item.key}`,
+            fingerprint: `escalated:${item.key}:${hash(`${report}|${item.escalation?.at ?? ""}`)}`,
+            key: item.key,
+            scope: item.scope,
+            detail: report.split("\n")[0]?.slice(0, 200) ?? "",
+        });
+    }
+    return found;
+}
+/** Keys that reached an end: whatever the supervisor remembered of them is spent. */
+export function finished(items) {
+    return items.filter((item) => TERMINAL.has(item.state)).map((item) => item.key);
+}
+function youngerThanSettle(item, now, settleMs) {
+    const at = item.escalation?.at;
+    // The ledger's clock is not promised to be epoch milliseconds: only a value that looks like one counts.
+    return settleMs > 0 && at !== undefined && at > 1e12 && now - at < settleMs;
+}
+function hash(text) {
+    return createHash("sha1").update(text).digest("hex").slice(0, 12);
+}
+//# sourceMappingURL=observe.js.map

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

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

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

@@ -0,0 +1,60 @@
+import type { Finding } from "./observe.js";
+export type Brief = {
+    finding: Finding;
+    /** incident.md and incident.json, gathered by `mason incident`. */
+    dossierDir?: string;
+    configPath?: string;
+    ledgerRoot: string;
+    /** Where mason's code can be read: the repositories the supervisor may change, and where the Project installed it. */
+    codeRoots: string[];
+    targets: string[];
+    /** The documents where the repositories above write down what they must be (absolute paths). */
+    rules: string[];
+    /** What was tried on this subject before, and how it went. */
+    history: string[];
+};
+export declare function rootcausePrompt(brief: Brief): string;
+export declare function remedyPrompt(brief: Brief): string;
+export declare function skepticPrompt(brief: Brief): string;
+/**
+ * The cheap second ask of an arbiter whose answer was refused for its shape:
+ * the first answer and the reason, no reports, no code to reread.
+ */
+export declare function formPrompt(answer: string, reason: string): string;
+export declare function arbiterPrompt(brief: Brief, reports: Record<string, string>): string;
+export declare function fixerPrompt(input: {
+    target: string;
+    title: string;
+    instruction: string;
+    conformity: string;
+    /** What the guard could not check before the change existed. */
+    deferred?: string[];
+    cause: string;
+    evidence: string[];
+    deny: string[];
+    checks: string[];
+    failure?: string;
+}): string;
+/**
+ * The guard. It is given a change and the repository, never the stop that
+ * caused it: it judges the change against the product, not against the problem.
+ */
+export declare function reviewerPrompt(input: {
+    target: string;
+    title: string;
+    files: string[];
+    diff: string;
+    checks: string[];
+}): string;
+/**
+ * The guard, before anything is written: it reads the proposal against the rules.
+ * The cheapest place to refuse a change that cannot conform is before it is coded.
+ */
+export declare function proposalReviewerPrompt(input: {
+    target: string;
+    title: string;
+    instruction: string;
+    conformity: string;
+    rules: string[];
+}): string;
+//# sourceMappingURL=prompts.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../../src/operator/supervise/prompts.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C,MAAM,MAAM,KAAK,GAAG;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,sHAAsH;IACtH,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,gGAAgG;IAChG,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,8DAA8D;IAC9D,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,CAAC;AAqDF,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAwBpD;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CA8BjD;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAyBlD;AASD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAYjE;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAkDnF;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,MAAM,CAqCT;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,GAAG,MAAM,CA+CT;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB,GAAG,MAAM,CAsCT"}