@telora/daemon 0.22.245 → 0.22.290

package/dist/supervision/routing-quality.d.ts

@@ -0,0 +1,59 @@
+import type { RoutingSampleRow } from '../queries/escalations/escalation-consumption.js';
+/**
+ * Default ceiling for the machine-lane mis-route rate. Above this, the demotion
+ * sweep holds: if MORE than half of the agent_resolvable filings whose resolver
+ * is observable were actually resolved by an operator (not an agent), the lane is
+ * not clearing what it is handed, so routing more into it is counter-productive.
+ */
+export declare const DEFAULT_MACHINE_LANE_MISROUTE_CEILING = 0.5;
+/**
+ * Minimum judged rows before the rate is trusted to gate a decision. A rate over
+ * a handful of rows is noise; below this we proceed as if unmeasured (never hold
+ * on thin evidence -- the same asymmetry as the promotion attempt gate).
+ */
+export declare const DEFAULT_MIN_ROUTING_SAMPLE = 10;
+/** The machine-lane mis-route measurement over a resolved-filing sample. */
+export interface MachineLaneMisRoute {
+    /** Rows filed agent_resolvable whose actual resolver was observable. */
+    judged: number;
+    /** Of those, how many were resolved by the wrong owner (an operator, not an agent). */
+    misRouted: number;
+    /** misRouted / judged, or 0 when judged === 0. */
+    rate: number;
+}
+/**
+ * Pure: the mis-route rate for the MACHINE lane only -- the share of
+ * agent_resolvable-filed rows that a non-machine actor actually resolved.
+ * Reuses computeMisRouteRate over the agent_resolvable-filed subset, so the one
+ * canonical mis-route definition serves both the general measure and this gate.
+ *
+ * The subset is taken AFTER promotion lineage (resolvePromotionLineage): a
+ * needs_operator row handed out of the machine lane (a routing decider's filing, or
+ * a historic promotion refile) belongs to that lane, so
+ * an operator closing it counts as the lane handing its work back -- the dominant
+ * real hand-back path, which a filter on the refile's own disposition would miss.
+ * Lineage units carry no lineage fields, so computeMisRouteRate re-applying it is
+ * the identity.
+ */
+export declare function machineLaneMisRoute(rows: readonly RoutingSampleRow[]): MachineLaneMisRoute;
+/**
+ * Pure: whether the demotion sweep should HOLD (not return more filings to the
+ * machine lane) given a measurement. Holds only on sufficient evidence AND a rate
+ * strictly above the ceiling -- thin or healthy samples never hold.
+ */
+export declare function shouldHoldDemotionForMisRoute(m: MachineLaneMisRoute, opts: {
+    ceiling: number;
+    minSample: number;
+}): boolean;
+/** The live measurement's read (production: escalation-consumption.ts listResolvedRoutingSample, bound at the composition root). */
+export interface RoutingQualityDeps {
+    listResolvedSample: () => Promise<RoutingSampleRow[]>;
+}
+/**
+ * Read the live resolved-escalation sample and compute the machine-lane
+ * mis-route measurement. This is the production entry point that makes
+ * routing-measurement.ts actually measure something -- it reads live rows and
+ * differences declared disposition against recorded resolution class.
+ */
+export declare function measureMachineLaneMisRoute(deps: RoutingQualityDeps): Promise<MachineLaneMisRoute>;
+//# sourceMappingURL=routing-quality.d.ts.map

package/dist/supervision/routing-quality.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing-quality.d.ts","sourceRoot":"","sources":["../../src/supervision/routing-quality.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kDAAkD,CAAC;AAEzF;;;;;GAKG;AACH,eAAO,MAAM,qCAAqC,MAAM,CAAC;AAEzD;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,KAAK,CAAC;AAE7C,4EAA4E;AAC5E,MAAM,WAAW,mBAAmB;IAClC,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC;IACf,uFAAuF;IACvF,SAAS,EAAE,MAAM,CAAC;IAClB,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,SAAS,gBAAgB,EAAE,GAAG,mBAAmB,CAK1F;AAED;;;;GAIG;AACH,wBAAgB,6BAA6B,CAC3C,CAAC,EAAE,mBAAmB,EACtB,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAC3C,OAAO,CAGT;AAED,oIAAoI;AACpI,MAAM,WAAW,kBAAkB;IACjC,kBAAkB,EAAE,MAAM,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAAC;CACvD;AAED;;;;;GAKG;AACH,wBAAsB,0BAA0B,CAC9C,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,mBAAmB,CAAC,CAG9B"}

package/dist/supervision/routing-quality.js

@@ -0,0 +1,77 @@
+// PINNED-BY-BEGIN (generated by gen:pinned-by -- do not hand-edit; checked by lint:pinned-by)
+// Pinned by: packages/daemon/src/completion/stall-escalations/machine-remediable-demotion.test.ts,
+//   packages/daemon/src/integration/resolution-class-routing-flow.test.ts,
+//   packages/daemon/src/supervision/routing-quality.test.ts
+// PINNED-BY-END
+/**
+ * Routing quality: measure the machine-owned lane's mis-route rate on LIVE
+ * resolved escalations and feed it back into how filings are classified.
+ *
+ * The measurement functions (computeMisRouteRate / computeActWorthyShare,
+ * routing-measurement.ts) difference a filing's declared disposition against the
+ * class that actually resolved it. This module is where that measurement meets
+ * production: it reads the org's resolved escalations, computes the mis-route
+ * rate for the MACHINE lane (disposition agent_resolvable), and turns it into a
+ * classification decision -- the demotion sweep consults it before returning more
+ * filings to the machine lane. If the machine lane is demonstrably mis-routing
+ * (its filings keep getting resolved by an operator, not an agent), pouring more
+ * work into it is the wrong move; the rate feeds back as a HOLD on demotion so
+ * those filings stay with the human until the lane earns the trust back.
+ *
+ * Closing this loop is the whole point of "routing becomes measurable": intent
+ * (declared disposition) minus reality (recorded resolution class) is computed
+ * AND acted on, rather than a one-shot guess with no correction signal.
+ */
+import { computeMisRouteRate, resolvePromotionLineage } from '../queries/escalations/routing-measurement.js';
+/**
+ * Default ceiling for the machine-lane mis-route rate. Above this, the demotion
+ * sweep holds: if MORE than half of the agent_resolvable filings whose resolver
+ * is observable were actually resolved by an operator (not an agent), the lane is
+ * not clearing what it is handed, so routing more into it is counter-productive.
+ */
+export const DEFAULT_MACHINE_LANE_MISROUTE_CEILING = 0.5;
+/**
+ * Minimum judged rows before the rate is trusted to gate a decision. A rate over
+ * a handful of rows is noise; below this we proceed as if unmeasured (never hold
+ * on thin evidence -- the same asymmetry as the promotion attempt gate).
+ */
+export const DEFAULT_MIN_ROUTING_SAMPLE = 10;
+/**
+ * Pure: the mis-route rate for the MACHINE lane only -- the share of
+ * agent_resolvable-filed rows that a non-machine actor actually resolved.
+ * Reuses computeMisRouteRate over the agent_resolvable-filed subset, so the one
+ * canonical mis-route definition serves both the general measure and this gate.
+ *
+ * The subset is taken AFTER promotion lineage (resolvePromotionLineage): a
+ * needs_operator row handed out of the machine lane (a routing decider's filing, or
+ * a historic promotion refile) belongs to that lane, so
+ * an operator closing it counts as the lane handing its work back -- the dominant
+ * real hand-back path, which a filter on the refile's own disposition would miss.
+ * Lineage units carry no lineage fields, so computeMisRouteRate re-applying it is
+ * the identity.
+ */
+export function machineLaneMisRoute(rows) {
+    const machineFiled = resolvePromotionLineage(rows).filter((r) => r.disposition === 'agent_resolvable');
+    return computeMisRouteRate(machineFiled);
+}
+/**
+ * Pure: whether the demotion sweep should HOLD (not return more filings to the
+ * machine lane) given a measurement. Holds only on sufficient evidence AND a rate
+ * strictly above the ceiling -- thin or healthy samples never hold.
+ */
+export function shouldHoldDemotionForMisRoute(m, opts) {
+    if (m.judged < opts.minSample)
+        return false;
+    return m.rate > opts.ceiling;
+}
+/**
+ * Read the live resolved-escalation sample and compute the machine-lane
+ * mis-route measurement. This is the production entry point that makes
+ * routing-measurement.ts actually measure something -- it reads live rows and
+ * differences declared disposition against recorded resolution class.
+ */
+export async function measureMachineLaneMisRoute(deps) {
+    const rows = await deps.listResolvedSample();
+    return machineLaneMisRoute(rows);
+}
+//# sourceMappingURL=routing-quality.js.map

package/dist/supervision/routing-quality.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing-quality.js","sourceRoot":"","sources":["../../src/supervision/routing-quality.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,mGAAmG;AACnG,2EAA2E;AAC3E,4DAA4D;AAC5D,gBAAgB;AAEhB;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,mBAAmB,EAAE,uBAAuB,EAA8B,MAAM,+CAA+C,CAAC;AAGzI;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qCAAqC,GAAG,GAAG,CAAC;AAEzD;;;;GAIG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,EAAE,CAAC;AAY7C;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAiC;IACnE,MAAM,YAAY,GAA4B,uBAAuB,CAAC,IAAI,CAAC,CAAC,MAAM,CAChF,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,KAAK,kBAAkB,CAC5C,CAAC;IACF,OAAO,mBAAmB,CAAC,YAAY,CAAC,CAAC;AAC3C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,6BAA6B,CAC3C,CAAsB,EACtB,IAA4C;IAE5C,IAAI,CAAC,CAAC,MAAM,GAAG,IAAI,CAAC,SAAS;QAAE,OAAO,KAAK,CAAC;IAC5C,OAAO,CAAC,CAAC,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC;AAC/B,CAAC;AAOD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC9C,IAAwB;IAExB,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,kBAAkB,EAAE,CAAC;IAC7C,OAAO,mBAAmB,CAAC,IAAI,CAAC,CAAC;AACnC,CAAC"}

package/dist/supervision/source-reliability.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Source reliability weighting for the machine-owned lane.
+ *
+ * Filings enter the agent_resolvable lane at full weight no matter what produced
+ * them -- including output from a producer with demonstrated misattribution. The
+ * dependency scanner mints "Security Remediation" focuses from npm audit output
+ * that misattributes findings on non-Node repositories; the filings on those
+ * focuses consume lane capacity AND corrupt the measurements that judge
+ * whether the lane is healthy (part of the "never-attempted" rate is the system
+ * arguably correctly declining that junk).
+ *
+ * A filing's producing source is carried by its FOCUS origin
+ * (product_focuses.origin, stamped 'deps_scanner' at the scanner focus-mint
+ * path), because the scanner produces focuses, not filings. This module maps an
+ * origin to a reliability weight in [0, 1] and applies it to a lane so a
+ * low-reliability source sorts/weights BELOW a full-weight peer -- without ever
+ * dropping a filing (down-weighting lowers priority; it never silences).
+ *
+ * Pure and dependency-free so the map + ordering are exercised from fixtures.
+ */
+/** Focus origin stamped by the dependency scanner's focus-mint path (the known-bad producer). */
+export declare const FOCUS_ORIGIN_DEPS_SCANNER = "deps_scanner";
+/** Full reliability: the default for a normal (user/unstamped) source. */
+export declare const FULL_RELIABILITY_WEIGHT = 1;
+/**
+ * Reduced reliability for a source with demonstrated misattribution. Below full
+ * so its filings deprioritize, but strictly > 0 so they are never dropped -- an
+ * unreliable source still occasionally produces a real filing.
+ */
+export declare const LOW_RELIABILITY_WEIGHT = 0.25;
+/**
+ * Reliability weight for a focus origin. Known-unreliable producers map below
+ * full; a null/absent or unrecognized origin is a normal source at full weight
+ * (down-weighting is opt-IN per demonstrated unreliability, never the default).
+ */
+export declare function focusOriginReliabilityWeight(origin: string | null | undefined): number;
+/** Whether a focus origin is a demonstrably-unreliable source (below full weight). */
+export declare function isLowReliabilityOrigin(origin: string | null | undefined): boolean;
+/** An item carrying (at least) the focus it is anchored to. */
+export interface FocusAnchoredItem {
+    focusId: string | null;
+}
+/** An item enriched with its source-reliability weight. */
+export type Weighted<T> = T & {
+    origin: string | null;
+    weight: number;
+};
+/**
+ * Attach a source-reliability weight to each item from its focus origin, and
+ * return them ordered by DESCENDING weight (full-weight sources first,
+ * low-reliability sources last). The sort is STABLE, so items of equal weight
+ * keep their input order (e.g. an age or priority order the caller already
+ * applied). No item is ever dropped -- a low-reliability filing sinks in the
+ * ordering, it does not disappear.
+ *
+ * `originByFocusId` maps a focusId to the origin of that focus; a focusId not in
+ * the map (or a null focusId) is treated as a normal full-weight source.
+ */
+export declare function weightByFocusOrigin<T extends FocusAnchoredItem>(items: readonly T[], originByFocusId: ReadonlyMap<string, string | null>): Weighted<T>[];
+//# sourceMappingURL=source-reliability.d.ts.map

package/dist/supervision/source-reliability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-reliability.d.ts","sourceRoot":"","sources":["../../src/supervision/source-reliability.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,iGAAiG;AACjG,eAAO,MAAM,yBAAyB,iBAAiB,CAAC;AAExD,0EAA0E;AAC1E,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,OAAO,CAAC;AAE3C;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAOtF;AAED,sFAAsF;AACtF,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAEjF;AAED,+DAA+D;AAC/D,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,2DAA2D;AAC3D,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG;IAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAExE;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,iBAAiB,EAC7D,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,eAAe,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,GAClD,QAAQ,CAAC,CAAC,CAAC,EAAE,CAUf"}

package/dist/supervision/source-reliability.js

@@ -0,0 +1,73 @@
+// PINNED-BY-BEGIN (generated by gen:pinned-by -- do not hand-edit; checked by lint:pinned-by)
+// Pinned by: packages/daemon/src/supervision/source-reliability.test.ts
+// PINNED-BY-END
+/**
+ * Source reliability weighting for the machine-owned lane.
+ *
+ * Filings enter the agent_resolvable lane at full weight no matter what produced
+ * them -- including output from a producer with demonstrated misattribution. The
+ * dependency scanner mints "Security Remediation" focuses from npm audit output
+ * that misattributes findings on non-Node repositories; the filings on those
+ * focuses consume lane capacity AND corrupt the measurements that judge
+ * whether the lane is healthy (part of the "never-attempted" rate is the system
+ * arguably correctly declining that junk).
+ *
+ * A filing's producing source is carried by its FOCUS origin
+ * (product_focuses.origin, stamped 'deps_scanner' at the scanner focus-mint
+ * path), because the scanner produces focuses, not filings. This module maps an
+ * origin to a reliability weight in [0, 1] and applies it to a lane so a
+ * low-reliability source sorts/weights BELOW a full-weight peer -- without ever
+ * dropping a filing (down-weighting lowers priority; it never silences).
+ *
+ * Pure and dependency-free so the map + ordering are exercised from fixtures.
+ */
+/** Focus origin stamped by the dependency scanner's focus-mint path (the known-bad producer). */
+export const FOCUS_ORIGIN_DEPS_SCANNER = 'deps_scanner';
+/** Full reliability: the default for a normal (user/unstamped) source. */
+export const FULL_RELIABILITY_WEIGHT = 1;
+/**
+ * Reduced reliability for a source with demonstrated misattribution. Below full
+ * so its filings deprioritize, but strictly > 0 so they are never dropped -- an
+ * unreliable source still occasionally produces a real filing.
+ */
+export const LOW_RELIABILITY_WEIGHT = 0.25;
+/**
+ * Reliability weight for a focus origin. Known-unreliable producers map below
+ * full; a null/absent or unrecognized origin is a normal source at full weight
+ * (down-weighting is opt-IN per demonstrated unreliability, never the default).
+ */
+export function focusOriginReliabilityWeight(origin) {
+    switch (origin) {
+        case FOCUS_ORIGIN_DEPS_SCANNER:
+            return LOW_RELIABILITY_WEIGHT;
+        default:
+            return FULL_RELIABILITY_WEIGHT;
+    }
+}
+/** Whether a focus origin is a demonstrably-unreliable source (below full weight). */
+export function isLowReliabilityOrigin(origin) {
+    return focusOriginReliabilityWeight(origin) < FULL_RELIABILITY_WEIGHT;
+}
+/**
+ * Attach a source-reliability weight to each item from its focus origin, and
+ * return them ordered by DESCENDING weight (full-weight sources first,
+ * low-reliability sources last). The sort is STABLE, so items of equal weight
+ * keep their input order (e.g. an age or priority order the caller already
+ * applied). No item is ever dropped -- a low-reliability filing sinks in the
+ * ordering, it does not disappear.
+ *
+ * `originByFocusId` maps a focusId to the origin of that focus; a focusId not in
+ * the map (or a null focusId) is treated as a normal full-weight source.
+ */
+export function weightByFocusOrigin(items, originByFocusId) {
+    const weighted = items.map((item) => {
+        const origin = item.focusId ? (originByFocusId.get(item.focusId) ?? null) : null;
+        return { ...item, origin, weight: focusOriginReliabilityWeight(origin) };
+    });
+    // Stable descending sort by weight: preserve input order within equal weights.
+    return weighted
+        .map((item, index) => ({ item, index }))
+        .sort((a, b) => b.item.weight - a.item.weight || a.index - b.index)
+        .map(({ item }) => item);
+}
+//# sourceMappingURL=source-reliability.js.map

package/dist/supervision/source-reliability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-reliability.js","sourceRoot":"","sources":["../../src/supervision/source-reliability.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,wEAAwE;AACxE,gBAAgB;AAEhB;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,iGAAiG;AACjG,MAAM,CAAC,MAAM,yBAAyB,GAAG,cAAc,CAAC;AAExD,0EAA0E;AAC1E,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC;AAEzC;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,IAAI,CAAC;AAE3C;;;;GAIG;AACH,MAAM,UAAU,4BAA4B,CAAC,MAAiC;IAC5E,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,yBAAyB;YAC5B,OAAO,sBAAsB,CAAC;QAChC;YACE,OAAO,uBAAuB,CAAC;IACnC,CAAC;AACH,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,sBAAsB,CAAC,MAAiC;IACtE,OAAO,4BAA4B,CAAC,MAAM,CAAC,GAAG,uBAAuB,CAAC;AACxE,CAAC;AAUD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CACjC,KAAmB,EACnB,eAAmD;IAEnD,MAAM,QAAQ,GAAkB,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACjD,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QACjF,OAAO,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,4BAA4B,CAAC,MAAM,CAAC,EAAE,CAAC;IAC3E,CAAC,CAAC,CAAC;IACH,+EAA+E;IAC/E,OAAO,QAAQ;SACZ,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;SACvC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC;SAClE,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC"}

package/dist/supervision/spawn-cooldown-window.d.ts

@@ -0,0 +1,15 @@
+import type { ModelProvider } from '../types/model-provider.js';
+import { type TeardownEntry } from './spawn-cooldown.js';
+/** A standing cooldown window. */
+export interface SpawnCooldownWindow {
+    /** Epoch ms of the latest teardown, or null when only a provider window holds the focus. */
+    sinceMs: number | null;
+    /** Epoch ms the hold ends; null when the respawn cycle is exhausted (no time ends it). */
+    untilMs: number | null;
+    exhausted: boolean;
+}
+/** When the teardown entry holds a spawn on `provider` until (Infinity = exhausted), or null when it holds nothing. Pure. */
+export declare function entryHoldUntilMs(entry: Readonly<TeardownEntry>, provider: ModelProvider | null): number | null;
+/** The window holding the focus's next spawn on `provider` now, or null when nothing holds it. */
+export declare function readSpawnCooldownWindow(focusId: string, provider: ModelProvider | null, nowMs?: number): SpawnCooldownWindow | null;
+//# sourceMappingURL=spawn-cooldown-window.d.ts.map

package/dist/supervision/spawn-cooldown-window.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn-cooldown-window.d.ts","sourceRoot":"","sources":["../../src/supervision/spawn-cooldown-window.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,EAA0B,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGjF,kCAAkC;AAClC,MAAM,WAAW,mBAAmB;IAClC,4FAA4F;IAC5F,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,0FAA0F;IAC1F,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,6HAA6H;AAC7H,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,QAAQ,CAAC,aAAa,CAAC,EAAE,QAAQ,EAAE,aAAa,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAM9G;AAED,kGAAkG;AAClG,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,aAAa,GAAG,IAAI,EAC9B,KAAK,GAAE,MAAmB,GACzB,mBAAmB,GAAG,IAAI,CAU5B"}

package/dist/supervision/spawn-cooldown-window.js

@@ -0,0 +1,46 @@
+// PINNED-BY-BEGIN (generated by gen:pinned-by -- do not hand-edit; checked by lint:pinned-by)
+// Pinned by: packages/daemon/src/focus/focus-activity-producers.test.ts
+// PINNED-BY-END
+/**
+ * The spawn-cooldown window a focus is inside NOW, as a reader shows it: when
+ * the hold began and when it ends. Display only -- no spawn decision reads this;
+ * the gates decide through isInSpawnCooldown (supervision/spawn-cooldown.ts) and
+ * the stop registry's `spawn_cooldown` / `provider_rate_limit_window` rows.
+ *
+ * It applies the same two holds the gate applies, for a spawn on `provider`
+ * (null: the provider cannot be named, so only the teardown streak holds):
+ *   - the focus's teardown entry: the exponential backoff from the latest
+ *     teardown, a rate-limit reset its own team recorded for this provider, or
+ *     an exhausted streak (holds with no end);
+ *   - the provider's account-wide rate-limit window.
+ * When both hold, the LATER end is when a spawn could run.
+ *
+ * @module supervision/spawn-cooldown-window
+ */
+import { CLAUDE_PROVIDER, providerWindowHoldUntilMs } from '../daemon-state/provider-window.js';
+import { readSpawnCooldownEntry } from './spawn-cooldown.js';
+import { spawnCooldownHoldUntilMs } from './stop-rows-spawn.js';
+/** When the teardown entry holds a spawn on `provider` until (Infinity = exhausted), or null when it holds nothing. Pure. */
+export function entryHoldUntilMs(entry, provider) {
+    if (entry.exhausted)
+        return Number.POSITIVE_INFINITY;
+    const foreignReset = entry.rateLimitResetAtMs != null && (entry.rateLimitProvider ?? CLAUDE_PROVIDER) !== provider;
+    if (!foreignReset)
+        return spawnCooldownHoldUntilMs(entry);
+    // Another provider's limit does not hold this spawn; a rate-limit-only entry then holds nothing.
+    return entry.count === 0 ? null : spawnCooldownHoldUntilMs({ ...entry, rateLimitResetAtMs: null });
+}
+/** The window holding the focus's next spawn on `provider` now, or null when nothing holds it. */
+export function readSpawnCooldownWindow(focusId, provider, nowMs = Date.now()) {
+    const entry = readSpawnCooldownEntry(focusId);
+    const ends = [
+        entry ? entryHoldUntilMs(entry, provider) : null,
+        provider !== null ? providerWindowHoldUntilMs(provider, nowMs) : null,
+    ].filter((t) => t !== null && t > nowMs);
+    if (ends.length === 0)
+        return null;
+    const until = Math.max(...ends);
+    const exhausted = until === Number.POSITIVE_INFINITY;
+    return { sinceMs: entry?.time ?? null, untilMs: exhausted ? null : until, exhausted };
+}
+//# sourceMappingURL=spawn-cooldown-window.js.map

package/dist/supervision/spawn-cooldown-window.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn-cooldown-window.js","sourceRoot":"","sources":["../../src/supervision/spawn-cooldown-window.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,wEAAwE;AACxE,gBAAgB;AAEhB;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,eAAe,EAAE,yBAAyB,EAAE,MAAM,oCAAoC,CAAC;AAEhG,OAAO,EAAE,sBAAsB,EAAsB,MAAM,qBAAqB,CAAC;AACjF,OAAO,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAWhE,6HAA6H;AAC7H,MAAM,UAAU,gBAAgB,CAAC,KAA8B,EAAE,QAA8B;IAC7F,IAAI,KAAK,CAAC,SAAS;QAAE,OAAO,MAAM,CAAC,iBAAiB,CAAC;IACrD,MAAM,YAAY,GAAG,KAAK,CAAC,kBAAkB,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,iBAAiB,IAAI,eAAe,CAAC,KAAK,QAAQ,CAAC;IACnH,IAAI,CAAC,YAAY;QAAE,OAAO,wBAAwB,CAAC,KAAK,CAAC,CAAC;IAC1D,iGAAiG;IACjG,OAAO,KAAK,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,wBAAwB,CAAC,EAAE,GAAG,KAAK,EAAE,kBAAkB,EAAE,IAAI,EAAE,CAAC,CAAC;AACrG,CAAC;AAED,kGAAkG;AAClG,MAAM,UAAU,uBAAuB,CACrC,OAAe,EACf,QAA8B,EAC9B,QAAgB,IAAI,CAAC,GAAG,EAAE;IAE1B,MAAM,KAAK,GAAG,sBAAsB,CAAC,OAAO,CAAC,CAAC;IAC9C,MAAM,IAAI,GAAG;QACX,KAAK,CAAC,CAAC,CAAC,gBAAgB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI;QAChD,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,yBAAyB,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI;KACtE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,GAAG,KAAK,CAAC,CAAC;IACtD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACnC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;IAChC,MAAM,SAAS,GAAG,KAAK,KAAK,MAAM,CAAC,iBAAiB,CAAC;IACrD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,IAAI,IAAI,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,EAAE,SAAS,EAAE,CAAC;AACxF,CAAC"}

package/dist/supervision/spawn-cooldown.d.ts

@@ -0,0 +1,287 @@
+import type { ModelProvider } from '../types/model-provider.js';
+/**
+ * Spawn cooldown: prevents crash loops by tracking recently-torn-down focuses.
+ *
+ * When a focus is torn down, it enters a cooldown period before it can be
+ * respawned. Consecutive teardowns increase the cooldown exponentially
+ * (1min, 2min, 4min, 8min, capped at 10min).
+ *
+ * The exponential backoff bounds the RATE of respawns but not their TOTAL
+ * DURATION: a cycle that never becomes productive saturates at one team per ten
+ * minutes and then runs at that rate forever, waiting for a human to notice. So
+ * a SECOND, terminating bound sits on top of the rate limiter: once a focus's
+ * teardown streak exceeds a total elapsed duration OR a cumulative teardown
+ * count (isRespawnCycleExhausted), the entry is marked `exhausted` and
+ * isInSpawnCooldown returns true INDEFINITELY -- respawns stop entirely rather
+ * than merely slowing. The caller (focus-poller-spawn.processPendingSpawnFocuses) files a
+ * legible respawn_cycle_exhausted escalation on that edge so the terminated
+ * cycle is never a silent strand. clearSpawnCooldown (genuine progress) resets
+ * the whole streak, so a focus that recovers starts fresh.
+ *
+ * DURABILITY: the teardown streak + `exhausted` latch are persisted to
+ * product_focuses (spawn_teardown_first_at / _last_at / _count /
+ * spawn_cooldown_exhausted) so they survive the auto-updater's routine daemon
+ * re-exec -- otherwise a deliberate halt silently re-opened and a spent
+ * terminating budget restarted from zero on every restart. The map here is the
+ * hot write-through cache: recordFocusTeardown / clearSpawnCooldown mutate it
+ * synchronously AND fire a best-effort DB write through the registered persister;
+ * clearSpawnCooldownDurably instead AWAITS the cleared state's write before it
+ * drops the entry, for a caller whose next act must not be undone by a restart.
+ * Every write for a focus is serialized (enqueueWrite), so the row ends with the
+ * LAST state recorded, never an older in-flight one;
+ * on boot, hydrateSpawnCooldownEntry restores the map from the persisted columns
+ * the first time each focus is seen. In-memory wins during a run (hydrate never
+ * clobbers a live entry); the DB is the restart-proof backing.
+ */
+/**
+ * Per-focus teardown tracking.
+ *   - firstTime: epoch ms of the FIRST teardown of the current streak. Preserved
+ *     across subsequent teardowns so the total-duration bound measures the whole
+ *     cycle, not just the latest teardown. Reset by clearSpawnCooldown.
+ *   - time: epoch ms of the LATEST teardown (drives the exponential rate limit).
+ *   - count: cumulative teardown count for the streak (drives both the
+ *     exponential backoff and the cumulative-count terminating bound).
+ *   - exhausted: true once a terminating bound crossed. Latches the focus into a
+ *     permanent skip until clearSpawnCooldown.
+ */
+export interface TeardownEntry {
+    firstTime: number;
+    time: number;
+    count: number;
+    exhausted: boolean;
+    /**
+     * Epoch ms of a provider rate-limit reset instant, when this focus's most
+     * recent teardown was a rate-limit rejection carrying one. When present it
+     * takes PRECEDENCE over the blind exponential cooldown: spawning holds until
+     * this instant (capacity returns), then resumes immediately. A rate-limit
+     * cooldown is recorded WITHOUT incrementing `count`/`exhausted` -- a provider
+     * limit is not a team failure, so it must not burn the respawn-cycle budget.
+     * Undefined for an ordinary (blind exponential) cooldown.
+     */
+    rateLimitResetAtMs?: number | null;
+    /**
+     * The provider whose limit `rateLimitResetAtMs` records (the provider of the
+     * team that saw it). A reader asking about another provider does not see the
+     * reset: that limit does not reach its spawn. Undefined reads as the claude
+     * backend's provider, the only one that recorded before windows were keyed.
+     */
+    rateLimitProvider?: ModelProvider;
+}
+/**
+ * The durable spawn-cooldown state persisted per focus (mirrors the
+ * product_focuses.spawn_teardown_* / spawn_cooldown_exhausted columns).
+ * firstAt/lastAt are ISO timestamps; null (with count 0, exhausted false) is the
+ * cleared state written by clearSpawnCooldown.
+ */
+export interface DurableSpawnCooldown {
+    firstAt: string | null;
+    lastAt: string | null;
+    count: number;
+    exhausted: boolean;
+}
+/**
+ * Write-through seam: persists a focus's spawn-cooldown state to durable storage.
+ * Registered once at daemon boot (setSpawnCooldownPersister) and called
+ * best-effort (fire-and-forget, a rejection logged) on every teardown/clear, and
+ * awaited by clearSpawnCooldownDurably. Unset by default in tests, where the
+ * module stays pure in-memory and nothing touches the DB.
+ */
+export type SpawnCooldownPersister = (focusId: string, state: DurableSpawnCooldown) => void | Promise<void>;
+/** Register (or clear, with null) the durable write-through persister at boot. */
+export declare function setSpawnCooldownPersister(fn: SpawnCooldownPersister | null): void;
+/**
+ * Restore a focus's teardown streak + `exhausted` latch from its persisted
+ * columns, the FIRST time the daemon sees the focus after a (re-)start. Idempotent
+ * and non-clobbering: an entry already tracked in memory this run always wins
+ * (hydrate never overwrites a live increment), and a focus with no persisted
+ * streak (count 0, not exhausted) is left untracked. This is what makes a halt
+ * stay halted and a spent budget stay spent across a daemon re-exec.
+ */
+export declare function hydrateSpawnCooldownEntry(focusId: string, state: DurableSpawnCooldown): void;
+/** Bounds for the respawn-cycle terminating condition. */
+export interface RespawnCycleBounds {
+    /** Max total elapsed ms since the streak's first teardown before terminating. */
+    maxTotalMs: number;
+    /** Max cumulative teardown count for the streak before terminating. */
+    maxCount: number;
+}
+/**
+ * Pure decision: has this teardown streak exhausted its terminating bounds?
+ *
+ * True when the streak has run for at least `maxTotalMs` since its FIRST
+ * teardown, OR has accumulated at least `maxCount` teardowns. Either bound alone
+ * terminates the cycle -- duration catches a slow saturated loop; count catches a
+ * fast one. Exported for direct unit testing (no clock, no daemon-core).
+ */
+export declare function isRespawnCycleExhausted(entry: Pick<TeardownEntry, 'firstTime' | 'count'>, nowMs: number, bounds: RespawnCycleBounds): boolean;
+/**
+ * Record a focus teardown for spawn cooldown tracking.
+ *
+ * Preserves the streak's firstTime, increments count, and -- when a terminating
+ * bound crosses -- latches `exhausted`. Returns the updated entry so the caller
+ * can detect the exhaustion edge and file the terminating escalation.
+ */
+export declare function recordFocusTeardown(focusId: string): TeardownEntry;
+/**
+ * True once a focus's respawn cycle has crossed its terminating bounds. Distinct
+ * from isInSpawnCooldown (which is also true during ordinary rate-limit cooldown):
+ * this is the TERMINAL signal the caller uses to file the one-per-focus
+ * respawn_cycle_exhausted escalation before skipping the spawn. Read-only.
+ */
+export declare function isRespawnCycleTerminated(focusId: string): boolean;
+/**
+ * Read a focus's current teardown-streak descriptor (firstTime + count), or null
+ * when no streak is tracked. Used by the respawn_cycle_exhausted escalation to
+ * report the elapsed duration and teardown count in its body. Read-only.
+ */
+export declare function getRespawnCycleStreak(focusId: string): {
+    firstTime: number;
+    count: number;
+} | null;
+/** A read-only copy of a focus's teardown entry, or null (supervision/spawn-cooldown-window.ts reads it for display). */
+export declare function readSpawnCooldownEntry(focusId: string): Readonly<TeardownEntry> | null;
+/**
+ * Pure: the epoch ms until which spawning is held for this teardown entry.
+ *
+ * Precedence:
+ *  - an EXHAUSTED streak is a permanent skip (the cycle is terminated, not
+ *    merely throttled) -> Infinity.
+ *  - a known rate-limit RESET instant takes precedence over the blind
+ *    exponential cooldown: hold until capacity returns, then resume the moment
+ *    it does (a reset instant already in the past yields a past `until`, i.e. no
+ *    hold).
+ *  - otherwise the ordinary exponential backoff from the latest teardown.
+ *
+ * Exported for direct unit testing (no clock, no daemon-core).
+ */
+export declare function resolveCooldownUntilMs(entry: Pick<TeardownEntry, 'time' | 'count' | 'exhausted' | 'rateLimitResetAtMs'>): number;
+/**
+ * The focusIds with a live teardown entry (any focus torn down and not yet
+ * cleared by genuine progress). A superset of those currently *inside* the
+ * cooldown window -- callers that need the held-now subset must additionally
+ * gate on isInSpawnCooldown. Read-only; used to seed the team-liveness-phase map's
+ * candidate focus set. Prunes stale entries as a side effect (same as the
+ * other readers).
+ */
+export declare function getSpawnCooldownFocusIds(): string[];
+/**
+ * A provider rate limit is ACCOUNT-wide, not per focus: when one team or one
+ * one-shot is rejected, every other spawn on that provider is rejected too,
+ * until the same reset instant. The per-focus entry above records the hold for
+ * the focus whose team saw the rejection; the provider's window records it for
+ * every spawn that would run on that provider -- and only for those
+ * (daemon-state/provider-window.ts keys the windows).
+ *
+ * Measured 2026-09-23 (mars): with only the per-focus hold, the verification
+ * loop and the routing decider kept spawning `claude --print` one-shots every
+ * tick for ten hours (each exited 1, each consumed as a result), and a second
+ * focus's team was spawned and torn down four times in one minute.
+ *
+ * The two functions below are the claude backend's window under the names the
+ * single window had, kept so the tests written against it still read it.
+ * Production code names the provider of the spawn it makes: it calls
+ * openProviderWindow / providerWindowHoldUntilMs, never these (pinned by
+ * provider-window.test.ts).
+ */
+export declare function recordProviderRateLimit(resetAtMs: number, nowMs?: number): boolean;
+/** The claude backend's window: the instant it closes, or null when not open. See recordProviderRateLimit. */
+export declare function providerRateLimitHoldUntilMs(nowMs?: number): number | null;
+/**
+ * Check if a focus is in spawn cooldown for a spawn on `provider`. True during
+ * that provider's rate-limit window whatever the focus's own entry says: a spawn
+ * now would be rejected on the same limit, and the teardown it costs is not a
+ * team failure. Another provider's window, and a reset the focus's entry records
+ * for another provider, do not hold it.
+ *
+ * `provider` is the provider of the spawn the caller is about to make. Omitted,
+ * it is the default engine's (a spawn with no engine selection runs on claude).
+ * `null` means the caller cannot yet name it (the spawn gate before the pass is
+ * resolved): no rate-limit window or reset is read, only the teardown streak,
+ * and the spawn checks its own provider once its engine is resolved
+ * (focus/focus-executor.ts).
+ */
+export declare function isInSpawnCooldown(focusId: string, provider?: ModelProvider | null): boolean;
+/**
+ * Record a provider rate-limit-induced cooldown: hold spawning until the reset
+ * instant `resetAtMs` (when capacity returns), taking precedence over the blind
+ * exponential cooldown. Deliberately does NOT increment the teardown `count` or
+ * latch `exhausted` -- a provider rate limit is not a team failure, so it must
+ * not burn the respawn-cycle terminating budget (isRespawnCycleExhausted). If a
+ * streak entry already exists (e.g. from prior genuine teardowns) its streak
+ * fields are preserved and only the reset instant is annotated; otherwise a
+ * minimal count-0 entry carrying just the reset instant is created.
+ *
+ * In-memory only (not written through the durable persister): a rate-limit hold
+ * is short-lived and a daemon restart re-reads capacity from the provider on the
+ * next spawn attempt anyway.
+ */
+export declare function recordRateLimitCooldown(focusId: string, resetAtMs: number, provider?: ModelProvider): void;
+/**
+ * What cooldown, if any, a team exit should record. Pure decision, exported for
+ * direct unit testing.
+ *
+ *  - 'none'      -- a GENUINE completion (classifyTeamExit disposition
+ *                   'completed' / work_complete): no respawn is coming, so the
+ *                   focus must NOT accrue toward the respawn-cycle halt.
+ *  - 'rate_limit'-- a provider rate-limit rejection carrying a FUTURE reset
+ *                   instant: hold until capacity returns via the reset-aware
+ *                   cooldown, WITHOUT burning the respawn-cycle budget (a
+ *                   provider limit is not a team failure).
+ *  - 'teardown'  -- any other exit ('stopped' / 'failed'): the ordinary
+ *                   terminate-and-respawn loop, which must accumulate the
+ *                   respawn-cycle streak so the exponential backoff grows and the
+ *                   exhaustion latch is reachable from the terminate path (not
+ *                   only from focus teardown / the pending-spawn path).
+ */
+export type RespawnCooldownAction = 'none' | 'rate_limit' | 'teardown';
+export declare function decideRespawnCooldown(args: {
+    disposition: 'completed' | 'stopped' | 'failed';
+    rateLimitResetAtMs: number | null | undefined;
+    nowMs: number;
+}): RespawnCooldownAction;
+/**
+ * Record the cooldown a team exit warrants, per decideRespawnCooldown. The
+ * single close-path entry point the terminate-and-respawn loop reaches, so the
+ * ordinary loop accumulates the respawn-cycle streak the same way the
+ * pending-spawn path already does (recordPendingSpawnAttempt) -- while a genuine
+ * completion records nothing and a rate-limit rejection stays budget-safe.
+ * Returns the action taken (for logging/testing).
+ */
+export declare function recordRespawnCooldown(args: {
+    focusId: string;
+    disposition: 'completed' | 'stopped' | 'failed';
+    rateLimitResetAtMs: number | null | undefined;
+    /** The provider the exiting team ran on (its limit opens only that window). Omitted = the claude backend's. */
+    provider?: ModelProvider;
+    nowMs?: number;
+}): RespawnCooldownAction;
+/**
+ * Record a reset-aware cooldown IFF a future reset instant is known. Returns
+ * true when it recorded one (the caller must then skip the ordinary blind
+ * teardown cooldown), false when there is no usable reset instant (the caller
+ * falls back to recordFocusTeardown). Pure decision + delegated write: the caller
+ * passes the clock reading, the writer (recordRateLimitCooldown) and the provider.
+ */
+export declare function maybeRecordRateLimitCooldown(focusId: string, rateLimitResetAtMs: number | null | undefined, nowMs: number, record: (focusId: string, resetAtMs: number, provider: ModelProvider) => void, provider: ModelProvider): boolean;
+/** Clear cooldown for a focus (e.g. after successful long-running session). */
+export declare function clearSpawnCooldown(focusId: string): void;
+/**
+ * Clear a focus's cooldown and CONFIRM the cleared state reached durable storage
+ * before reporting success. For a caller whose next act relies on the halt
+ * staying lifted across a restart (the operator-hold release in
+ * review-hold-park.ts): a fire-and-forget clear that failed, or had not landed
+ * when the daemon re-exec'd, re-hydrates the `exhausted` latch and re-halts the
+ * focus after the caller already acted on the release.
+ *
+ * The write is queued BEHIND every earlier write for the focus (enqueueWrite), so
+ * no older teardown write still in flight -- the ones that latched the halt --
+ * can land after it and restore the latch. It is then awaited, up to
+ * DURABLE_CLEAR_ATTEMPTS tries inside its own turn; only once it lands is the
+ * in-memory entry dropped. On failure the entry is left as it was and false is
+ * returned, so memory never claims a clear the DB would undo. With no persister
+ * registered (pure in-memory) the clear is memory-only and succeeds.
+ */
+export declare function clearSpawnCooldownDurably(focusId: string): Promise<boolean>;
+/** Test-only: drop every in-memory entry and write chain, as a daemon re-exec starts with neither. */
+export declare function __resetSpawnCooldownForTests(): void;
+//# sourceMappingURL=spawn-cooldown.d.ts.map