@telora/daemon 0.22.245 → 0.22.290

package/dist/supervision/escalation-spool.js

@@ -0,0 +1,231 @@
+// PINNED-BY-BEGIN (generated by gen:pinned-by -- do not hand-edit; checked by lint:pinned-by)
+// Pinned by: packages/daemon/src/focus/pending-spawn-review-next-step.test.ts,
+//   packages/daemon/src/supervision/escalation-spool.test.ts
+// PINNED-BY-END
+/**
+ * A durable local spool for escalations the filing chokepoint could not record.
+ *
+ * A bounded hold ends in teardown or an escalation. When the escalation writer
+ * (supervision/escalation-filing.ts createEscalation -- the product API) stays unavailable
+ * past the hold's own retry bound, the hold still has to end, and the escalation
+ * it owes must not end with it: a daemon log line is not a record anything reads.
+ * So the hold writes the owed filing HERE -- one JSON file per condition key under
+ * the global state dir, written atomically (temp + rename), so it survives a
+ * daemon restart and a reader never sees a torn entry -- and only then lets go.
+ *
+ * The spool has a reader: drainEscalationSpool, run once per focus poll (see
+ * focus/focus-poller-spawn.ts runPendingSpawnPass). It files every spooled entry
+ * through the SAME chokepoint, stamping metadata.spooled_at and
+ * metadata.spool_reason, and deletes an entry only once its filing resolved. A
+ * filing that still fails leaves the entry spooled for the next poll. Entries are
+ * keyed by the filing's cause key, so a condition spooled again replaces its
+ * earlier entry instead of queuing a duplicate, and a re-filed entry (the delete
+ * failed after a recorded filing) is absorbed by the chokepoint's cause-key
+ * correlation. A malformed entry is skipped and left in place for inspection.
+ *
+ * The poll never waits on a drain (startEscalationSpoolDrain). One drain runs per
+ * spool directory at a time, a poll that finds one in flight starts none, and
+ * every filing is bounded by ESCALATION_SPOOL_FILING_TIMEOUT_MS, so a slow or hung
+ * writer, or a backlog of entries, never delays the spawns the poll runs next.
+ *
+ * A bound only stops the drain WAITING; it cannot cancel the API call behind it.
+ * So a filing that outlives its bound keeps OWNING its entry until that call
+ * settles: the entry stays spooled, and no later drain starts a second filing of
+ * it meanwhile -- two overlapping filings could both read no open incident in
+ * their correlation lookups and record two rows. A late success removes the entry
+ * (one filing, one deletion); a late failure releases it for the next poll. A
+ * removal never deletes an entry spooled again since the filing read it.
+ *
+ * @module supervision/escalation-spool
+ */
+import { createHash } from 'node:crypto';
+import { mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { resolve, sep } from 'node:path';
+import { resolveGlobalStateDir } from '../daemon-state/daemon-process.js';
+import { createLogger } from '../log/daemon-log.js';
+const log = createLogger({ module: 'escalations' });
+/** Bound on one spooled filing: past it the entry stays spooled and the drain moves on. */
+export const ESCALATION_SPOOL_FILING_TIMEOUT_MS = 30_000;
+/** The production spool directory under the global state dir. */
+export function escalationSpoolDir() {
+    return resolve(resolveGlobalStateDir(), 'escalation-spool');
+}
+/** The entry file for a key: a readable slug plus a hash, so distinct keys never share a file. */
+export function escalationSpoolPath(key, dir = escalationSpoolDir()) {
+    const slug = key.replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 160);
+    const hash = createHash('sha256').update(key).digest('hex').slice(0, 12);
+    return resolve(dir, `${slug}-${hash}.json`);
+}
+/**
+ * Spool an owed escalation atomically and return the entry's path. THROWS when
+ * the entry could not be written -- the caller must not let go of what it holds.
+ */
+export function spoolEscalation(spooled, opts) {
+    const { dir } = opts;
+    const entry = {
+        key: spooled.key,
+        spooledAt: opts.now().toISOString(),
+        reason: spooled.reason,
+        params: spooled.params,
+    };
+    const path = escalationSpoolPath(spooled.key, dir);
+    const tmp = `${path}.${process.pid}.tmp`;
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(tmp, JSON.stringify(entry, null, 2), { mode: 0o600 });
+    renameSync(tmp, path);
+    return path;
+}
+/** Validate a parsed entry; null when it is not a well-formed spooled escalation. */
+function parseSpooled(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return null;
+    const r = raw;
+    if (typeof r.key !== 'string' || typeof r.spooledAt !== 'string' || typeof r.reason !== 'string')
+        return null;
+    if (typeof r.params !== 'object' || r.params === null)
+        return null;
+    const p = r.params;
+    if (typeof p.organizationId !== 'string' || typeof p.reasonType !== 'string' || typeof p.description !== 'string')
+        return null;
+    if (p.issueId !== null && typeof p.issueId !== 'string')
+        return null;
+    if (p.metadata !== undefined && (typeof p.metadata !== 'object' || p.metadata === null))
+        return null;
+    return { key: r.key, spooledAt: r.spooledAt, reason: r.reason, params: p };
+}
+/** Every well-formed entry in the spool (none when the directory does not exist). */
+export function readEscalationSpool(dir = escalationSpoolDir()) {
+    let names;
+    try {
+        names = readdirSync(dir).filter((name) => name.endsWith('.json')).sort();
+    }
+    catch {
+        return [];
+    }
+    const entries = [];
+    for (const name of names) {
+        const path = resolve(dir, name);
+        let entry = null;
+        try {
+            entry = parseSpooled(JSON.parse(readFileSync(path, 'utf8')));
+        }
+        catch {
+            entry = null;
+        }
+        if (entry)
+            entries.push({ path, entry });
+        else
+            log.warn(`[escalation-spool] skipping malformed spool entry ${path} (left in place)`);
+    }
+    return entries;
+}
+/** A filing's bound elapsed before its writer settled. */
+class FilingBoundElapsed extends Error {
+}
+/** A filing raced against its bound: rejects when it has not settled within `ms`. */
+function withinFilingBound(filing, ms) {
+    let timer;
+    const bound = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new FilingBoundElapsed(`the filing did not settle within ${ms}ms`)), ms);
+    });
+    return Promise.race([filing, bound]).finally(() => clearTimeout(timer));
+}
+/** Filings that outlived their bound, by entry path: each entry stays owned by its writer until it settles. */
+const unsettledFilings = new Map();
+/** Remove a filed entry -- unless it was spooled again since the filing read it: that newer entry stays for the next drain. */
+function removeFiledEntry(path, filed) {
+    let current = null;
+    try {
+        current = parseSpooled(JSON.parse(readFileSync(path, 'utf8')));
+    }
+    catch {
+        current = null;
+    }
+    if (current?.spooledAt !== filed.spooledAt) {
+        if (current)
+            log.info(`[escalation-spool] filed ${filed.key}; it was spooled again at ${current.spooledAt}, and that entry stays for the next poll`);
+        return;
+    }
+    try {
+        unlinkSync(path);
+    }
+    catch (err) {
+        log.warn(`[escalation-spool] filed ${filed.key} but could not remove ${path} (${err.message}); a re-file correlates by its cause key`);
+    }
+}
+/** Keep an outlived filing's entry owned until its writer settles, then remove the entry (success) or release it (failure). */
+function ownUntilSettled(path, entry, filing) {
+    const owned = filing.then(() => {
+        removeFiledEntry(path, entry);
+        log.info(`[escalation-spool] filed ${entry.key} after its filing outlived the bound (spooled at ${entry.spooledAt})`);
+    }, (err) => {
+        log.warn(`[escalation-spool] the outlived filing of ${entry.key} failed (${err instanceof Error ? err.message : String(err)}); it stays spooled for the next poll`);
+    }).finally(() => {
+        unsettledFilings.delete(path);
+    });
+    unsettledFilings.set(path, owned);
+}
+/**
+ * File every spooled escalation through the chokepoint. An entry is removed only
+ * once its filing resolved; a failing or timed-out filing leaves it for the next
+ * drain, and an entry whose earlier filing is still in flight is not filed again
+ * (see the module header). Never throws.
+ */
+export async function drainEscalationSpool(deps) {
+    const { createEscalation } = deps;
+    const filingTimeoutMs = deps.filingTimeoutMs ?? ESCALATION_SPOOL_FILING_TIMEOUT_MS;
+    const drain = { filed: [], retained: [] };
+    for (const { path, entry } of readEscalationSpool(deps.dir)) {
+        if (unsettledFilings.has(path)) {
+            drain.retained.push({ key: entry.key, error: 'an earlier filing of this entry is still in flight' });
+            continue;
+        }
+        const filing = Promise.resolve().then(() => createEscalation({
+            ...entry.params,
+            metadata: { ...entry.params.metadata, spooled_at: entry.spooledAt, spool_reason: entry.reason },
+        }));
+        try {
+            await withinFilingBound(filing, filingTimeoutMs);
+        }
+        catch (err) {
+            if (err instanceof FilingBoundElapsed)
+                ownUntilSettled(path, entry, filing);
+            const error = err instanceof Error ? err.message : String(err);
+            drain.retained.push({ key: entry.key, error });
+            log.warn(`[escalation-spool] ${entry.key} is still unfiled (${error}); it stays spooled at ${path} for the next poll`);
+            continue;
+        }
+        drain.filed.push(entry.key);
+        removeFiledEntry(path, entry);
+        log.info(`[escalation-spool] filed ${entry.key}, spooled at ${entry.spooledAt} (${entry.reason})`);
+    }
+    return drain;
+}
+/** Drains in flight, one per spool directory. */
+const inFlightDrains = new Map();
+/**
+ * Start a drain of the spool directory unless one is already in flight there,
+ * and return the drain in flight. The poll does not await it (see the module
+ * header).
+ */
+export function startEscalationSpoolDrain(deps) {
+    const { dir } = deps;
+    const running = inFlightDrains.get(dir);
+    if (running)
+        return running;
+    const drain = drainEscalationSpool(deps).finally(() => {
+        inFlightDrains.delete(dir);
+    });
+    inFlightDrains.set(dir, drain);
+    return drain;
+}
+/** Settles once no drain is in flight for the directory (at once when none is). */
+export async function escalationSpoolDrainSettled(dir = escalationSpoolDir()) {
+    await inFlightDrains.get(dir);
+}
+/** Settles once no filing that outlived its bound is still in flight for an entry in the directory. */
+export async function escalationSpoolFilingsSettled(dir = escalationSpoolDir()) {
+    const prefix = resolve(dir) + sep;
+    await Promise.all([...unsettledFilings].filter(([path]) => path.startsWith(prefix)).map(([, owned]) => owned));
+}
+//# sourceMappingURL=escalation-spool.js.map

package/dist/supervision/escalation-spool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"escalation-spool.js","sourceRoot":"","sources":["../../src/supervision/escalation-spool.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,+EAA+E;AAC/E,6DAA6D;AAC7D,gBAAgB;AAEhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACtG,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,qBAAqB,EAAE,MAAM,mCAAmC,CAAC;AAE1E,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEpD,MAAM,GAAG,GAAG,YAAY,CAAC,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC,CAAC;AAgCpD,2FAA2F;AAC3F,MAAM,CAAC,MAAM,kCAAkC,GAAG,MAAM,CAAC;AAUzD,iEAAiE;AACjE,MAAM,UAAU,kBAAkB;IAChC,OAAO,OAAO,CAAC,qBAAqB,EAAE,EAAE,kBAAkB,CAAC,CAAC;AAC9D,CAAC;AAED,kGAAkG;AAClG,MAAM,UAAU,mBAAmB,CAAC,GAAW,EAAE,MAAc,kBAAkB,EAAE;IACjF,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,CAAC,kBAAkB,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAChE,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACzE,OAAO,OAAO,CAAC,GAAG,EAAE,GAAG,IAAI,IAAI,IAAI,OAAO,CAAC,CAAC;AAC9C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC7B,OAAwE,EACxE,IAAsC;IAEtC,MAAM,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IACrB,MAAM,KAAK,GAAsB;QAC/B,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;QACnC,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,MAAM,EAAE,OAAO,CAAC,MAAM;KACvB,CAAC;IACF,MAAM,IAAI,GAAG,mBAAmB,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACnD,MAAM,GAAG,GAAG,GAAG,IAAI,IAAI,OAAO,CAAC,GAAG,MAAM,CAAC;IACzC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACpC,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACpE,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACtB,OAAO,IAAI,CAAC;AACd,CAAC;AAED,qFAAqF;AACrF,SAAS,YAAY,CAAC,GAAY;IAChC,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACzD,MAAM,CAAC,GAAG,GAA8B,CAAC;IACzC,IAAI,OAAO,CAAC,CAAC,GAAG,KAAK,QAAQ,IAAI,OAAO,CAAC,CAAC,SAAS,KAAK,QAAQ,IAAI,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC9G,IAAI,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACnE,MAAM,CAAC,GAAG,CAAC,CAAC,MAAiC,CAAC;IAC9C,IAAI,OAAO,CAAC,CAAC,cAAc,KAAK,QAAQ,IAAI,OAAO,CAAC,CAAC,UAAU,KAAK,QAAQ,IAAI,OAAO,CAAC,CAAC,WAAW,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC/H,IAAI,CAAC,CAAC,OAAO,KAAK,IAAI,IAAI,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACrE,IAAI,CAAC,CAAC,QAAQ,KAAK,SAAS,IAAI,CAAC,OAAO,CAAC,CAAC,QAAQ,KAAK,QAAQ,IAAI,CAAC,CAAC,QAAQ,KAAK,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACrG,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,CAAsC,EAAE,CAAC;AAClH,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,mBAAmB,CAAC,MAAc,kBAAkB,EAAE;IACpE,IAAI,KAAe,CAAC;IACpB,IAAI,CAAC;QACH,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC3E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,MAAM,OAAO,GAAiB,EAAE,CAAC;IACjC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAChC,IAAI,KAAK,GAA6B,IAAI,CAAC;QAC3C,IAAI,CAAC;YACH,KAAK,GAAG,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;QAC/D,CAAC;QAAC,MAAM,CAAC;YACP,KAAK,GAAG,IAAI,CAAC;QACf,CAAC;QACD,IAAI,KAAK;YAAE,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;;YACpC,GAAG,CAAC,IAAI,CAAC,qDAAqD,IAAI,kBAAkB,CAAC,CAAC;IAC7F,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,0DAA0D;AAC1D,MAAM,kBAAmB,SAAQ,KAAK;CAAG;AAEzC,qFAAqF;AACrF,SAAS,iBAAiB,CAAC,MAAwB,EAAE,EAAU;IAC7D,IAAI,KAAiC,CAAC;IACtC,MAAM,KAAK,GAAG,IAAI,OAAO,CAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE;QAC7C,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,kBAAkB,CAAC,oCAAoC,EAAE,IAAI,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC3G,CAAC,CAAC,CAAC;IACH,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;AAC1E,CAAC;AAED,+GAA+G;AAC/G,MAAM,gBAAgB,GAAG,IAAI,GAAG,EAAyB,CAAC;AAE1D,+HAA+H;AAC/H,SAAS,gBAAgB,CAAC,IAAY,EAAE,KAAwB;IAC9D,IAAI,OAAO,GAA6B,IAAI,CAAC;IAC7C,IAAI,CAAC;QACH,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IACjE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,GAAG,IAAI,CAAC;IACjB,CAAC;IACD,IAAI,OAAO,EAAE,SAAS,KAAK,KAAK,CAAC,SAAS,EAAE,CAAC;QAC3C,IAAI,OAAO;YAAE,GAAG,CAAC,IAAI,CAAC,4BAA4B,KAAK,CAAC,GAAG,6BAA6B,OAAO,CAAC,SAAS,0CAA0C,CAAC,CAAC;QACrJ,OAAO;IACT,CAAC;IACD,IAAI,CAAC;QACH,UAAU,CAAC,IAAI,CAAC,CAAC;IACnB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,GAAG,CAAC,IAAI,CAAC,4BAA4B,KAAK,CAAC,GAAG,yBAAyB,IAAI,KAAM,GAAa,CAAC,OAAO,0CAA0C,CAAC,CAAC;IACpJ,CAAC;AACH,CAAC;AAED,+HAA+H;AAC/H,SAAS,eAAe,CAAC,IAAY,EAAE,KAAwB,EAAE,MAAwB;IACvF,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CACvB,GAAG,EAAE;QACH,gBAAgB,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAC9B,GAAG,CAAC,IAAI,CAAC,4BAA4B,KAAK,CAAC,GAAG,oDAAoD,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC;IACxH,CAAC,EACD,CAAC,GAAY,EAAE,EAAE;QACf,GAAG,CAAC,IAAI,CAAC,6CAA6C,KAAK,CAAC,GAAG,YAAY,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,uCAAuC,CAAC,CAAC;IACtK,CAAC,CACF,CAAC,OAAO,CAAC,GAAG,EAAE;QACb,gBAAgB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAChC,CAAC,CAAC,CAAC;IACH,gBAAgB,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;AACpC,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,IAA8B;IACvE,MAAM,EAAE,gBAAgB,EAAE,GAAG,IAAI,CAAC;IAClC,MAAM,eAAe,GAAG,IAAI,CAAC,eAAe,IAAI,kCAAkC,CAAC;IACnF,MAAM,KAAK,GAAyB,EAAE,KAAK,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;IAChE,KAAK,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,mBAAmB,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5D,IAAI,gBAAgB,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAC/B,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,KAAK,EAAE,oDAAoD,EAAE,CAAC,CAAC;YACrG,SAAS;QACX,CAAC;QACD,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,gBAAgB,CAAC;YAC3D,GAAG,KAAK,CAAC,MAAM;YACf,QAAQ,EAAE,EAAE,GAAG,KAAK,CAAC,MAAM,CAAC,QAAQ,EAAE,UAAU,EAAE,KAAK,CAAC,SAAS,EAAE,YAAY,EAAE,KAAK,CAAC,MAAM,EAAE;SAChG,CAAC,CAAC,CAAC;QACJ,IAAI,CAAC;YACH,MAAM,iBAAiB,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;QACnD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,kBAAkB;gBAAE,eAAe,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;YAC5E,MAAM,KAAK,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC/D,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC;YAC/C,GAAG,CAAC,IAAI,CAAC,sBAAsB,KAAK,CAAC,GAAG,sBAAsB,KAAK,0BAA0B,IAAI,oBAAoB,CAAC,CAAC;YACvH,SAAS;QACX,CAAC;QACD,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC5B,gBAAgB,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAC9B,GAAG,CAAC,IAAI,CAAC,4BAA4B,KAAK,CAAC,GAAG,gBAAgB,KAAK,CAAC,SAAS,KAAK,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;IACrG,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,iDAAiD;AACjD,MAAM,cAAc,GAAG,IAAI,GAAG,EAAyC,CAAC;AAExE;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CAAC,IAA8B;IACtE,MAAM,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IACrB,MAAM,OAAO,GAAG,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACxC,IAAI,OAAO;QAAE,OAAO,OAAO,CAAC;IAC5B,MAAM,KAAK,GAAG,oBAAoB,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE;QACpD,cAAc,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC,CAAC,CAAC;IACH,cAAc,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC/B,OAAO,KAAK,CAAC;AACf,CAAC;AAED,mFAAmF;AACnF,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAAC,MAAc,kBAAkB,EAAE;IAClF,MAAM,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAChC,CAAC;AAED,uGAAuG;AACvG,MAAM,CAAC,KAAK,UAAU,6BAA6B,CAAC,MAAc,kBAAkB,EAAE;IACpF,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;IAClC,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;AACjH,CAAC"}

package/dist/supervision/escalation-suppression.d.ts

@@ -0,0 +1,89 @@
+import { type CreateEscalationParams, type CreateEscalationResult } from './escalation-filing.js';
+import { type IncidentRow } from '../queries/escalations/incident-record.js';
+/**
+ * The idempotent filer's collaborators, both required: the suppressing-row read
+ * and the filer. fileEscalationIdempotent binds the production pair
+ * (listSuppressingEscalationRows over the installed product-api transport, and
+ * createEscalation); a test calls fileEscalationIdempotentWith with its own.
+ */
+export interface EscalationSuppressionDeps {
+    /** Fetch the open+dismissed escalation rows to scan for a cause key. */
+    listSuppressingEscalations: (opts: {
+        focusId?: string;
+    }) => Promise<IncidentRow[]>;
+    /** File a fresh escalation through the chokepoint. */
+    createEscalation: (params: CreateEscalationParams) => Promise<CreateEscalationResult>;
+}
+/** The open+dismissed escalation rows (narrowed by focus when given), over the installed transport. */
+export declare function listSuppressingEscalationRows(opts: {
+    focusId?: string;
+}): Promise<IncidentRow[]>;
+/**
+ * Pure: whether already-fetched rows suppress a re-file of `causeKey` -- an OPEN
+ * or DISMISSED row carrying it as its own (or original) cause key, or an OPEN row
+ * carrying it as a correlated symptom.
+ */
+export declare function rowsSuppressCauseKey(rows: readonly IncidentRow[], causeKey: string): boolean;
+/**
+ * True when an OPEN (pending/in_review) or DISMISSED escalation already carries
+ * this cause key -- i.e. a new filing for the same cause must be suppressed.
+ *
+ * Narrows server-side by open+dismissed statuses (and by focusId when supplied,
+ * honored by the live escalation_list handler) so the 500-row page is scoped to
+ * the relevant rows rather than the org's newest 500. The cause-key match itself
+ * is client-side because cause_key lives in metadata JSONB, not a column.
+ */
+export declare function hasSuppressedCauseKey(causeKey: string, opts: {
+    focusId?: string;
+}, deps: Pick<EscalationSuppressionDeps, 'listSuppressingEscalations'>): Promise<boolean>;
+/** Params for an idempotent, cause-keyed filing. */
+export interface FileEscalationIdempotentParams extends CreateEscalationParams {
+    /** The deterministic cause key (queries/escalations/cause-key.ts). Stamped into metadata.cause_key. */
+    causeKey: string;
+}
+/** Outcome of an idempotent filing attempt. */
+export interface FileEscalationIdempotentResult {
+    /** Whether a new escalation row was created this call. */
+    filed: boolean;
+    /** Whether the call was suppressed by an existing open/dismissed cause-key row. */
+    suppressed: boolean;
+    /** The new escalation id when filed; null when suppressed, correlated, or the create returned no id. */
+    escalationId: string | null;
+    /**
+     * Whether createEscalation's incident reducer attached the observation to its
+     * incident's open lane row instead of filing (filed and suppressed are then both
+     * false). Always set by fileEscalationIdempotent; optional so hand-built stubs
+     * keep type-checking.
+     */
+    correlated?: boolean;
+    /**
+     * The lane row this observation was attached to (correlated), or whose attach
+     * failed before this row was filed; null otherwise.
+     */
+    incidentEscalationId?: string | null;
+    /**
+     * Whether the server refused the filing non-transiently (supervision/escalation-refusal.ts):
+     * filed is then false, and escalationId is the refusal record filed in its place (null
+     * while unfiled or itself refused).
+     */
+    refused?: boolean;
+}
+/**
+ * File an escalation ONLY if its cause key is not already suppressed (open,
+ * dismissed, or an open incident's symptom). The cause key is stamped into
+ * metadata.cause_key so a later re-observation of the same cause is suppressed;
+ * createEscalation then correlates the filing onto its incident (see the header).
+ *
+ * This is the single cause-keyed entry point every daemon detector should route
+ * through. It replaces per-detector ad-hoc dedup (hasOpenEscalationForDelivery,
+ * hasOpenWorktreeDirtyEscalation, hasOpenWedgedFocusEscalation, in-memory Sets)
+ * with one cause-keyed gate that also carries dismissal memory.
+ */
+export declare function fileEscalationIdempotentWith(params: FileEscalationIdempotentParams, deps: EscalationSuppressionDeps): Promise<FileEscalationIdempotentResult>;
+/**
+ * The production idempotent filer -- what the composition root binds and every
+ * cause-keyed detector calls: fileEscalationIdempotentWith over the installed
+ * transport's suppressing-row read and the production chokepoint.
+ */
+export declare function fileEscalationIdempotent(params: FileEscalationIdempotentParams): Promise<FileEscalationIdempotentResult>;
+//# sourceMappingURL=escalation-suppression.d.ts.map

package/dist/supervision/escalation-suppression.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"escalation-suppression.d.ts","sourceRoot":"","sources":["../../src/supervision/escalation-suppression.ts"],"names":[],"mappings":"AAoCA,OAAO,EAAoB,KAAK,sBAAsB,EAAE,KAAK,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAEpH,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,2CAA2C,CAAC;AAY7E;;;;;GAKG;AACH,MAAM,WAAW,yBAAyB;IACxC,wEAAwE;IACxE,0BAA0B,EAAE,CAAC,IAAI,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IACnF,sDAAsD;IACtD,gBAAgB,EAAE,CAAC,MAAM,EAAE,sBAAsB,KAAK,OAAO,CAAC,sBAAsB,CAAC,CAAC;CACvF;AAED,uGAAuG;AACvG,wBAAsB,6BAA6B,CACjD,IAAI,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GACzB,OAAO,CAAC,WAAW,EAAE,CAAC,CASxB;AAcD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,SAAS,WAAW,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAK5F;AAED;;;;;;;;GAQG;AACH,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,EAC1B,IAAI,EAAE,IAAI,CAAC,yBAAyB,EAAE,4BAA4B,CAAC,GAClE,OAAO,CAAC,OAAO,CAAC,CAElB;AAED,oDAAoD;AACpD,MAAM,WAAW,8BAA+B,SAAQ,sBAAsB;IAC5E,uGAAuG;IACvG,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,+CAA+C;AAC/C,MAAM,WAAW,8BAA8B;IAC7C,0DAA0D;IAC1D,KAAK,EAAE,OAAO,CAAC;IACf,mFAAmF;IACnF,UAAU,EAAE,OAAO,CAAC;IACpB,wGAAwG;IACxG,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,oBAAoB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,4BAA4B,CAChD,MAAM,EAAE,8BAA8B,EACtC,IAAI,EAAE,yBAAyB,GAC9B,OAAO,CAAC,8BAA8B,CAAC,CAuBzC;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,8BAA8B,GAAG,OAAO,CAAC,8BAA8B,CAAC,CAKxH"}

package/dist/supervision/escalation-suppression.js

@@ -0,0 +1,136 @@
+// PINNED-BY-BEGIN (generated by gen:pinned-by -- do not hand-edit; checked by lint:pinned-by)
+// Pinned by: 23 tests -- run: npm run gen:pinned-by -- --list packages/daemon/src/supervision/escalation-suppression.ts
+// PINNED-BY-END
+/**
+ * Cause-keyed escalation suppression + idempotent filing.
+ *
+ * Generalizes the narrow per-delivery precedent (hasOpenEscalationForDelivery in
+ * queries/escalations/escalations.ts) to EVERY daemon detector via a deterministic cause key
+ * (queries/escalations/cause-key.ts). Two properties, both DB-backed so they survive a
+ * daemon restart:
+ *
+ *   1. Idempotent while open. While a filing carrying this cause key is OPEN
+ *      (pending or in_review) -- as the row's own cause key OR as a symptom
+ *      correlated onto an open incident row -- a detector re-observing the same
+ *      cause does not file again (nor append a duplicate symptom).
+ *
+ *   2. Dismissal memory. A DISMISSED filing carrying this cause key keeps the
+ *      cause silent: the same cause cannot re-file until its subject state
+ *      changes. Because the subject is encoded IN the cause key, a changed subject
+ *      (a NEW sha going red) yields a DIFFERENT key with no matching dismissed row
+ *      and re-files naturally. Dismissal memory stays per cause key: a dismissed
+ *      incident row's correlated symptoms do not suppress.
+ *
+ * A RESOLVED filing does NOT suppress: resolve means the cause was addressed, so a
+ * recurrence should re-file. This is achieved simply by excluding 'resolved' from
+ * the suppression status set below.
+ *
+ * The cause key is stamped into agent_escalations.metadata.cause_key at file time.
+ * Cross-detector correlation (one incident per root cause) is NOT decided here: an
+ * unsuppressed filing goes to createEscalation, whose ONE incident reducer
+ * (supervision/incident-correlation.ts) attaches every daemon filing -- this path's and
+ * the direct filers' alike -- to its incident's open lane row.
+ */
+import { callApi } from '../queries/api-client/shared.js';
+import { createEscalation } from './escalation-filing.js';
+import { openRowSymptomCauseKeys } from './incident-correlation.js';
+import { createLogger } from '../log/daemon-log.js';
+const log = createLogger({ module: 'escalations' });
+/**
+ * Statuses that SUPPRESS a re-file for a cause key: OPEN (pending/in_review)
+ * gives idempotency-while-open; DISMISSED gives dismissal-memory. 'resolved' is
+ * deliberately ABSENT -- a resolved cause may recur and should re-file.
+ */
+const SUPPRESSING_STATUSES = ['pending', 'in_review', 'dismissed'];
+/** The open+dismissed escalation rows (narrowed by focus when given), over the installed transport. */
+export async function listSuppressingEscalationRows(opts) {
+    const result = await callApi('escalation_list', {
+        fields: {
+            statuses: SUPPRESSING_STATUSES,
+            ...(opts.focusId ? { focusId: opts.focusId } : {}),
+        },
+        limit: 500,
+    });
+    return result.escalations ?? [];
+}
+/**
+ * The cause keys a row answers for, tolerating the loose JSONB shape: its own
+ * metadata.cause_key, plus metadata.original_cause_key on a hand-off row -- a
+ * routing decider's human-facing filing (MCP escalate sourceCauseKey) or a historic
+ * promotion refile -- so an open hand-off row keeps the detector's original cause
+ * silent exactly as the source did.
+ */
+function rowCauseKeys(row) {
+    const meta = row.metadata ?? null;
+    return [meta?.cause_key, meta?.original_cause_key].filter((k) => typeof k === 'string');
+}
+/**
+ * Pure: whether already-fetched rows suppress a re-file of `causeKey` -- an OPEN
+ * or DISMISSED row carrying it as its own (or original) cause key, or an OPEN row
+ * carrying it as a correlated symptom.
+ */
+export function rowsSuppressCauseKey(rows, causeKey) {
+    return rows.some((e) => {
+        if (e.status && !SUPPRESSING_STATUSES.includes(e.status))
+            return false;
+        return rowCauseKeys(e).includes(causeKey) || openRowSymptomCauseKeys(e).includes(causeKey);
+    });
+}
+/**
+ * True when an OPEN (pending/in_review) or DISMISSED escalation already carries
+ * this cause key -- i.e. a new filing for the same cause must be suppressed.
+ *
+ * Narrows server-side by open+dismissed statuses (and by focusId when supplied,
+ * honored by the live escalation_list handler) so the 500-row page is scoped to
+ * the relevant rows rather than the org's newest 500. The cause-key match itself
+ * is client-side because cause_key lives in metadata JSONB, not a column.
+ */
+export async function hasSuppressedCauseKey(causeKey, opts, deps) {
+    return rowsSuppressCauseKey(await deps.listSuppressingEscalations({ focusId: opts.focusId }), causeKey);
+}
+/**
+ * File an escalation ONLY if its cause key is not already suppressed (open,
+ * dismissed, or an open incident's symptom). The cause key is stamped into
+ * metadata.cause_key so a later re-observation of the same cause is suppressed;
+ * createEscalation then correlates the filing onto its incident (see the header).
+ *
+ * This is the single cause-keyed entry point every daemon detector should route
+ * through. It replaces per-detector ad-hoc dedup (hasOpenEscalationForDelivery,
+ * hasOpenWorktreeDirtyEscalation, hasOpenWedgedFocusEscalation, in-memory Sets)
+ * with one cause-keyed gate that also carries dismissal memory.
+ */
+export async function fileEscalationIdempotentWith(params, deps) {
+    const { causeKey, ...createParams } = params;
+    const rows = await deps.listSuppressingEscalations({ focusId: createParams.focusId ?? createParams.anchor?.focusId });
+    if (rowsSuppressCauseKey(rows, causeKey)) {
+        log.info(`[escalations] Suppressed duplicate filing for cause key "${causeKey}" (open or dismissed row exists)`);
+        return { filed: false, suppressed: true, escalationId: null, correlated: false, incidentEscalationId: null };
+    }
+    const keyed = {
+        ...createParams,
+        metadata: { ...(createParams.metadata ?? {}), cause_key: causeKey },
+    };
+    const created = await deps.createEscalation(keyed);
+    const correlated = created.correlated === true;
+    const refused = created.refusal !== undefined;
+    return {
+        filed: !correlated && !refused,
+        suppressed: false,
+        escalationId: correlated ? null : created.escalationId,
+        correlated,
+        incidentEscalationId: created.incidentEscalationId ?? null,
+        refused,
+    };
+}
+/**
+ * The production idempotent filer -- what the composition root binds and every
+ * cause-keyed detector calls: fileEscalationIdempotentWith over the installed
+ * transport's suppressing-row read and the production chokepoint.
+ */
+export function fileEscalationIdempotent(params) {
+    return fileEscalationIdempotentWith(params, {
+        listSuppressingEscalations: listSuppressingEscalationRows,
+        createEscalation,
+    });
+}
+//# sourceMappingURL=escalation-suppression.js.map

package/dist/supervision/escalation-suppression.js.map

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

package/dist/supervision/filing-route.d.ts

@@ -0,0 +1,28 @@
+import { type HumanAct } from '../queries/escalations/filing-observation.js';
+/** The filing fields the routing rule reads and may rewrite. */
+export interface FilingRouteInput {
+    disposition?: string;
+    description: string;
+    helpNeeded?: string;
+    metadata?: Record<string, unknown>;
+    /** The detector's proposed human act -- carried into the observation, never routed on. */
+    humanAct?: HumanAct | null;
+}
+/** The routed filing: what createEscalation actually sends. */
+export interface FilingRoute {
+    /** agent_resolvable, or undefined when the filing named no disposition. Never a human-owning value. */
+    disposition: string | undefined;
+    description: string;
+    helpNeeded: string | undefined;
+    metadata: Record<string, unknown> | undefined;
+    /** Which branch of the rule applied (for logging + tests). There is no human-facing branch. */
+    route: 'observation' | 'pass_through';
+}
+/**
+ * Pure: apply the chokepoint routing rule (see the module header) to one filing.
+ * `_descriptionCap` (the server-side ESCALATION_DESCRIPTION_MAX createEscalation
+ * passes) is unused: no route rewrites the description any more. It stays in the
+ * signature so the createEscalation call site is unchanged.
+ */
+export declare function routeFilingDisposition(input: FilingRouteInput, _descriptionCap?: number): FilingRoute;
+//# sourceMappingURL=filing-route.d.ts.map

package/dist/supervision/filing-route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filing-route.d.ts","sourceRoot":"","sources":["../../src/supervision/filing-route.ts"],"names":[],"mappings":"AAyCA,OAAO,EAAuD,KAAK,QAAQ,EAAE,MAAM,8CAA8C,CAAC;AAElI,gEAAgE;AAChE,MAAM,WAAW,gBAAgB;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,0FAA0F;IAC1F,QAAQ,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;CAC5B;AAED,+DAA+D;AAC/D,MAAM,WAAW,WAAW;IAC1B,uGAAuG;IACvG,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAC9C,+FAA+F;IAC/F,KAAK,EAAE,aAAa,GAAG,cAAc,CAAC;CACvC;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,gBAAgB,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,WAAW,CAyBrG"}

package/dist/supervision/filing-route.js

@@ -0,0 +1,72 @@
+// PINNED-BY-BEGIN (generated by gen:pinned-by -- do not hand-edit; checked by lint:pinned-by)
+// Pinned by: packages/daemon/src/completion/review-cycle-budget/review-cycle-cap-regression.test.ts,
+//   packages/daemon/src/focus/pending-spawn-review-next-step.test.ts,
+//   packages/daemon/src/supervision/filing-chokepoint.test.ts
+// PINNED-BY-END
+/**
+ * The filing chokepoint's routing rule: detectors REPORT conditions; the daemon
+ * has NO human-facing route. Only an agent that has assembled the intent ladder
+ * makes a filing human-facing, through the MCP escalate surface.
+ *
+ * routeFilingDisposition is applied inside supervision/escalation-filing.ts createEscalation,
+ * so every daemon filing path (fileEscalationIdempotent, fileEscalation, direct
+ * callers) inherits it:
+ *
+ *  - ANY disposition other than agent_resolvable (needs_operator, external_wait,
+ *    needs_intent, needs_clarification -- and any value added later) -> sent
+ *    agent_resolvable as an OBSERVATION: metadata.observation =
+ *    { proposed_disposition, condition, proposed_human_act? }. The detector's
+ *    named `humanAct`, when it passed one, travels as proposed_human_act -- a
+ *    PROPOSAL for the deciding agent, never a routing decision. Description and
+ *    helpNeeded are the condition as filed, unchanged.
+ *  - agent_resolvable / no disposition -> untouched (a humanAct on them is ignored).
+ *
+ * The rule is by EXCLUSION (everything that is not already machine-lane enters
+ * the machine lane), so no branch here can return a human-owning disposition,
+ * and this module names none: supervision/detector-disposition-gate.test.ts fails
+ * if the source regains one, and supervision/filing-chokepoint.test.ts feeds every
+ * disposition value through the rule.
+ *
+ * This module does NOT write metadata.human_act. That key marks a row an AGENT
+ * made human-facing through the MCP escalate surface; the observation record it
+ * writes, and its readers, are queries/escalations/filing-observation.ts.
+ *
+ * Pure and dependency-light (no daemon-core VALUE import -- see the mock-loader
+ * note in queries/escalations/escalation-dispositions.ts).
+ *
+ * History: docs/daemon/history-platform.md (supervision/filing-route.ts).
+ */
+import { DISPOSITION_AGENT_RESOLVABLE } from '../queries/escalations/escalation-dispositions.js';
+import { conditionHead, readHumanAct } from '../queries/escalations/filing-observation.js';
+/**
+ * Pure: apply the chokepoint routing rule (see the module header) to one filing.
+ * `_descriptionCap` (the server-side ESCALATION_DESCRIPTION_MAX createEscalation
+ * passes) is unused: no route rewrites the description any more. It stays in the
+ * signature so the createEscalation call site is unchanged.
+ */
+export function routeFilingDisposition(input, _descriptionCap) {
+    const proposed = input.disposition;
+    if (proposed === undefined || proposed === DISPOSITION_AGENT_RESOLVABLE) {
+        return {
+            disposition: proposed,
+            description: input.description,
+            helpNeeded: input.helpNeeded,
+            metadata: input.metadata,
+            route: 'pass_through',
+        };
+    }
+    const act = readHumanAct(input.humanAct);
+    const observation = {
+        proposed_disposition: proposed,
+        condition: conditionHead(input.description),
+        ...(act ? { proposed_human_act: act } : {}),
+    };
+    return {
+        disposition: DISPOSITION_AGENT_RESOLVABLE,
+        description: input.description,
+        helpNeeded: input.helpNeeded,
+        metadata: { ...(input.metadata ?? {}), observation },
+        route: 'observation',
+    };
+}
+//# sourceMappingURL=filing-route.js.map

package/dist/supervision/filing-route.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filing-route.js","sourceRoot":"","sources":["../../src/supervision/filing-route.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,qGAAqG;AACrG,sEAAsE;AACtE,8DAA8D;AAC9D,gBAAgB;AAEhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAAE,4BAA4B,EAAE,MAAM,mDAAmD,CAAC;AACjG,OAAO,EAAE,aAAa,EAAE,YAAY,EAAyC,MAAM,8CAA8C,CAAC;AAuBlI;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAuB,EAAE,eAAwB;IACtF,MAAM,QAAQ,GAAG,KAAK,CAAC,WAAW,CAAC;IACnC,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,4BAA4B,EAAE,CAAC;QACxE,OAAO;YACL,WAAW,EAAE,QAAQ;YACrB,WAAW,EAAE,KAAK,CAAC,WAAW;YAC9B,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,KAAK,EAAE,cAAc;SACtB,CAAC;IACJ,CAAC;IAED,MAAM,GAAG,GAAG,YAAY,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IACzC,MAAM,WAAW,GAAsB;QACrC,oBAAoB,EAAE,QAAQ;QAC9B,SAAS,EAAE,aAAa,CAAC,KAAK,CAAC,WAAW,CAAC;QAC3C,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,kBAAkB,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC5C,CAAC;IACF,OAAO;QACL,WAAW,EAAE,4BAA4B;QACzC,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,QAAQ,EAAE,EAAE,GAAG,CAAC,KAAK,CAAC,QAAQ,IAAI,EAAE,CAAC,EAAE,WAAW,EAAE;QACpD,KAAK,EAAE,aAAa;KACrB,CAAC;AACJ,CAAC"}