@telora/daemon 0.22.85 → 0.22.91

package/dist/queries/agent-resolvable-promotion.js

@@ -1,84 +1,119 @@
 // PINNED-BY-BEGIN (generated by gen:pinned-by -- do not hand-edit; checked by lint:pinned-by)
-// Pinned by: packages/daemon/src/queries/agent-resolvable-promotion-sweep.test.ts,
+// Pinned by: packages/daemon/src/integration/resolution-class-routing-flow.test.ts,
+//   packages/daemon/src/queries/agent-resolvable-promotion-sweep.test.ts,
 //   packages/daemon/src/queries/agent-resolvable-promotion.test.ts,
-//   packages/daemon/src/queries/agent-resolvable-retired-focus.test.ts
+//   packages/daemon/src/queries/agent-resolvable-retired-focus.test.ts,
+//   packages/daemon/src/spawn/routing-decider-spawn.test.ts
 // PINNED-BY-END
 /**
- * agent_resolvable promotion safety net (delivery "agent_resolvable never
- * reaches the human inbox", TEL-3).
+ * The agent_resolvable ROUTING HAND-OFF (formerly the promotion backstop).
  *
- * agent_resolvable filings are machine-owned: hidden from the operator inbox
- * (TEL-1) and ridden into the focus's next coding spawn to be resolved (TEL-2).
- * That is only safe if a filing the machine CANNOT actually clear eventually
- * surfaces to a human -- otherwise it lingers forever, invisible. This module is
- * that backstop: an agent_resolvable filing that has stayed open past a bound
- * (it rode into many spawn cycles and none resolved it -- "bounded failures") is
- * PROMOTED to a human by resolving the machine-routed row and refiling the same
- * content as a needs_operator escalation, which the operator inbox DOES show.
+ * agent_resolvable filings are machine-owned: hidden from the operator inbox and
+ * ridden into the focus's next coding spawn, whose agent resolves or routes each.
+ * Every daemon detector files into this lane (the createEscalation chokepoint
+ * turns any other disposition into an OBSERVATION, metadata.observation), so the
+ * daemon has NO human-facing route of its own. Some observations no coding spawn
+ * will ever route: the focus is un-armed or stop-held, the filing has no focus,
+ * the condition outlives a converged focus, or spawns rode it in and none cleared
+ * it. This module is how those still reach a decision.
  *
- * Gate: RECORDED ATTEMPT EVIDENCE, not elapsed open-age. Open-age was the
- * original proxy for "it survived N spawn cycles unresolved", but the proxy is
- * inverted in practice: a filing anchored to an un-armed or wedged focus ages
- * past the bound having had ZERO agent sessions, and promoting it hands a human a
- * FIRST attempt dressed up as an exhausted machine. So promotion now gates on the
- * actual count of agent sessions that ran on the filing's focus since it was
- * created (countFocusSessionsSince): a filing with zero recorded attempts NEVER
- * promotes, regardless of age. Open-age is retained only as a cheap CANDIDATE
- * pre-filter (don't even count sessions for a fresh filing, which matters for the
- * org-wide sweep's up-to-500-row scan); the promotion DECISION is the attempt
- * count, and the count is carried into the promoted row's metadata so the human
- * lane shows the evidence of the machine attempts that failed.
+ * Only an AGENT makes a filing human-facing. The old backstop refiled such a
+ * filing as needs_operator deterministically -- surfacing it to a human with no
+ * agent deciding (the verify shortfall this delivery closes). Now the org-wide
+ * sweep HANDS each eligible observation to a one-shot ROUTING DECIDER
+ * (spawn/routing-decider.ts, injected here as `decide`): an agent that assembles
+ * the intent ladder, then resolves the condition itself, declines noise, keeps it
+ * in the lane with a recorded decision, or files ONE telora_agent escalate naming
+ * the specific act only a human can perform, with sourceEscalationId lineage.
  *
- * A filing that cannot accrue attempts -- one with no focus anchor -- therefore
- * does not promote either: it has no machine lane to be attempted in. New
- * anchorless agent_resolvable filings are refused at the filing boundary, and
- * un-taken machine-lane filings are made observable by the aging observer rather
- * than dumped on a human.
+ * ELIGIBILITY (evaluateCandidate):
+ *  - immediately, with no age bound:
+ *      stop_held      -- anchored to a focus a stop-kind hold blocks (isStopHoldObservation
+ *                        on any open observation of that focus): no coding team spawns there.
+ *      unreachable    -- no focus anchor, or an un-armed focus: no coding spawn reaches it.
+ *      outlives_focus -- its focus retired but the condition outlives it (agent-resolvable-retirement.ts).
+ *  - past the age bound (TELORA_AGENT_RESOLVABLE_PROMOTE_HOURS), on RECORDED ATTEMPT
+ *    EVIDENCE (promotionBasis): 'exhausted' (>= minAttempts agent sessions ran on its
+ *    focus and none cleared it) or 'unreachable' (a zero-attempt observation). Open-age
+ *    alone never hands off a plain filing.
+ *  A focus-scoped candidate on a retired focus is still retired auto_swept.
  *
- * Promotion is idempotent: the needs_operator refile rides the shared cause-keyed
- * gate keyed on the original escalation id, and the source row is resolved in the
- * same step, so a filing is promoted at most once.
+ * BOUNDS: at most maxPerSweep hand-offs per sweep (ROUTING_DECIDER_MAX_PER_SWEEP),
+ * each needing a governor slot inside the decider. Each hand-off whose decider RAN is
+ * recorded on the observation (metadata decider_attempts / last_decided_at /
+ * last_decider_outcome) and is not re-handed inside the decider window. A decider
+ * that cannot run (no slot, spawn error) or fails leaves the observation OPEN in the
+ * lane -- there is no deterministic human fallback -- and is counted `undecided` in
+ * the sweep counts the loop tick logs.
+ *
+ * CLOSE THE SOURCE: an open human-lane row whose metadata.originalEscalationId names
+ * an open observation means a decider already made it human-facing; the sweep closes
+ * the observation auto_swept (no actor, so never judged -- the mis-route measurement
+ * judges the decider row's eventual resolver against this source's lane).
  */
-import { ESCALATION_REASONS, ESCALATION_DISPOSITIONS, DELIVERY_STATUS, loadEnvConfig, } from '@telora/daemon-core';
-import { markEscalationResolved as defaultMarkEscalationResolved, ESCALATION_DESCRIPTION_MAX } from './escalations.js';
-import { getFocusDeliveries as defaultGetFocusDeliveries } from './focuses.js';
-import { getActiveFocuses as defaultGetActiveFocuses } from './focus-discovery.js';
+import { loadEnvConfig } from '@telora/daemon-core';
+import { markEscalationResolved as defaultMarkEscalationResolved } from './escalations.js';
+import { checkFocusRetirement, defaultFocusRetired, defaultPriorRetirementOfCause, defaultRetireSwept, memoizeFocusRetired, peekFocusRetirement, } from './agent-resolvable-retirement.js';
 import { countFocusSessionsSince as defaultCountFocusSessionsSince } from './sessions.js';
-import { listOpenAgentResolvableForFocus as defaultListOpenAgentResolvableForFocus, listOpenAgentResolvableForOrg as defaultListOpenAgentResolvableForOrg } from './escalation-consumption.js';
-import { fileEscalationIdempotent as defaultFileEscalationIdempotent, } from './escalation-suppression.js';
-import { computeCauseKey } from './cause-key.js';
+import { isMachineStopObservation } from './holds.js';
+import { listOpenAgentResolvableForFocus as defaultListOpenAgentResolvableForFocus, listOpenAgentResolvableForOrg as defaultListOpenAgentResolvableForOrg, listOpenLineageCarriersForOrg as defaultListOpenLineageCarriersForOrg, } from './escalation-consumption.js';
+import { callApi } from './shared.js';
 import { createLogger } from '../shell/log.js';
 const log = createLogger({ module: 'escalations' });
-/** Default hours an agent_resolvable filing may stay open before it is a promotion CANDIDATE. */
+/** Default hours an agent_resolvable filing may stay open before the attempt-evidence gate applies. */
 export const DEFAULT_AGENT_RESOLVABLE_PROMOTE_HOURS = 24;
 /**
  * Minimum recorded agent sessions on a filing's focus (since it was created)
- * before it may be promoted to a human. The decisive gate: at least this many
- * spawns rode the filing in and none cleared it -- an exhausted machine, not a
- * first attempt. A candidate below this floor is NOT promoted regardless of age.
+ * before an over-age filing is handed to a routing decider on the 'exhausted'
+ * basis: at least this many spawns rode it in and none cleared it.
  */
 export const DEFAULT_AGENT_RESOLVABLE_PROMOTE_MIN_ATTEMPTS = 1;
-/** Pure: whether a filing's recorded attempts meet the promotion floor. */
+/**
+ * Hand-offs per sweep. Recorded choice: 2. Each hand-off is an Opus one-shot
+ * session (spawn/routing-decider-spawn.ts ROUTING_DECIDER_MODEL); on the 30-minute
+ * sweep cadence 2 bounds worst-case decider spend to ~96 sessions/day while a
+ * backlog still drains in priority order (stop_held first). Eligible observations
+ * past the cap are counted `deferred` and handed on a later sweep.
+ */
+export const ROUTING_DECIDER_MAX_PER_SWEEP = 2;
+/** Pure: whether a filing's recorded attempts meet the floor. */
 export function meetsAttemptFloor(attempts, minAttempts) {
     return attempts >= minAttempts;
 }
 /**
- * Resolve the promotion threshold (hours -> ms) from the typed, Zod-validated
- * env-config -- the single declaration site for every operational knob
+ * Pure: the evidence basis on which an OVER-AGE candidate is handed off, or null
+ * (it stays in the machine lane).
+ *  - 'exhausted': at least minAttempts agent sessions ran on its focus since it
+ *    was filed and none cleared it.
+ *  - 'unreachable': it is a detector OBSERVATION and NO agent session has reached it.
+ * A plain (non-observation) filing with zero attempts is not handed off.
+ */
+export function promotionBasis(attempts, minAttempts, isObservation) {
+    if (meetsAttemptFloor(attempts, minAttempts))
+        return 'exhausted';
+    if (attempts === 0 && isObservation)
+        return 'unreachable';
+    return null;
+}
+/** Pure: whole hours a filing has been open (>= 1; an unparseable createdAt reads as 1). */
+export function openAgeHours(createdAt, nowMs) {
+    const created = Date.parse(createdAt);
+    if (Number.isNaN(created))
+        return 1;
+    return Math.max(1, Math.floor((nowMs - created) / 3_600_000));
+}
+/**
+ * Resolve the age bound (hours -> ms) from the typed, Zod-validated env-config
  * (packages/daemon-core/src/env-config.ts). An unset value yields the schema
- * default (DEFAULT_AGENT_RESOLVABLE_PROMOTE_HOURS); an invalid one fails loudly
- * at startup rather than silently degrading to a default here.
- *
- * Same shape as resolveStuckBranchThresholdMs in merge-back-loop.ts.
+ * default; an invalid one fails loudly at startup.
  */
 export function resolveAgentResolvablePromoteMs(env = process.env) {
     return loadEnvConfig(env).TELORA_AGENT_RESOLVABLE_PROMOTE_HOURS * 3_600_000;
 }
 /**
- * Pure: split the open agent_resolvable filings into the ones that should still
- * RIDE into this spawn and the ones that are past the age bound and should be
- * PROMOTED to a human. A filing with an unparseable/absent createdAt is treated
- * as fresh (ride) -- promotion must never fire on a missing timestamp.
+ * Pure: split open filings into the ones still within the age bound (ride) and
+ * the ones past it (promote = over-age candidates). An absent/unparseable
+ * createdAt is treated as fresh -- nothing is ever decided on a missing timestamp.
  */
 export function partitionAgentResolvableByAge(items, nowMs, thresholdMs) {
     const ride = [];
@@ -94,303 +129,293 @@ export function partitionAgentResolvableByAge(items, nowMs, thresholdMs) {
     }
     return { ride, promote };
 }
-/** The cause key that makes a promotion refile idempotent (one per original filing). */
-export function agentResolvablePromotionCauseKey(originalEscalationId) {
-    return computeCauseKey('agent_resolvable_promoted', { escalationId: originalEscalationId });
-}
-/** escalation_kind for a promoted (formerly agent_resolvable) filing. */
-export const AGENT_RESOLVABLE_PROMOTED_KIND = 'agent_resolvable_promoted';
+// ---------------------------------------------------------------------------
+// Stop-kind holds
+// ---------------------------------------------------------------------------
 /**
- * Fit a promotion refile's description under the escalation cap. The invariant
- * `head` (the promotion preamble: attempt count, original kind, original filing
- * id) is always kept; only the variable-length original `body` is truncated,
- * ending with a marker pointing at the original filing (which carries the full
- * text) so nothing is silently dropped and no refile is ever rejected for length.
- *
- * Without this, a candidate filed at exactly the cap (Nexus notifications fit to
- * ESCALATION_DESCRIPTION_MAX with zero headroom) produced a ~5300-char refile the
- * edge rejected on every sweep tick -- the row could never leave the machine
- * lane, and `description` is not writable through product-api to trim in place.
- * Modeled on nexus/return.ts fitNotificationDescription (invariant head kept,
- * variable tail trimmed with a pointer). Pure + exported for direct unit testing.
+ * Blocks respawn by KIND alone, whatever it proposes and whatever its disposition
+ * (queries/escalations.ts REVIEW_COVERAGE_INCOMPLETE_ESCALATION_KIND, parked by the
+ * respawn guard directly).
  */
-export function fitPromotionDescription(head, body, originalFilingId, cap = ESCALATION_DESCRIPTION_MAX) {
-    const full = `${head}${body}`;
-    if (full.length <= cap)
-        return full;
-    const marker = `...\n\n[Original filing body truncated to fit the ${cap}-char escalation ` +
-        `cap -- full text on escalation ${originalFilingId}.]`;
-    const budget = cap - head.length - marker.length;
-    if (budget <= 0) {
-        // Even head + marker do not fit: keep the head, drop the body, point to the record.
-        const minimal = `${head}[Original filing body omitted for length -- see escalation ${originalFilingId}.]`;
-        return minimal.length <= cap ? minimal : head.slice(0, cap);
-    }
-    return `${head}${body.slice(0, budget)}${marker}`;
-}
+const COVERAGE_HOLD_KIND = 'review_coverage_incomplete';
 /**
- * Pure: build the needs_operator refile params for a filing the machine could
- * not resolve autonomously. Carries the original description + kind so the
- * operator sees what was tried and why it now needs them; anchored to the focus
- * WHEN one is present.
- *
- * focusId is OPTIONAL. The case that most needs the backstop -- a filing from an
- * interactive MCP session -- carries no focus by construction, and the
- * needs_operator refile does not need a focus to be VISIBLE: the operator inbox
- * predicate (isOperatorInboxDisposition, src/lib/escalations.ts) keys on
- * disposition alone, so an unanchored needs_operator promotion is renderable. An
- * anchorless promotion simply files org-scoped with an empty anchor; a
- * focus-anchored one still stamps the focus for provenance.
+ * Pure: whether an open filing is a STOP-kind hold observation -- one whose presence
+ * blocks the focus's respawn, so no coding team will reach that focus's observations.
+ * The rule is the holds contract's ONE definition, isMachineStopObservation
+ * (queries/holds.ts: a MACHINE_STOP_KINDS observation carrying its detector's
+ * proposed_human_act), plus a review_coverage_incomplete observation, which the
+ * respawn guard parks by kind.
  */
-export function buildAgentResolvablePromotionParams(item, ctx, ageHours, attempts) {
-    const originalKind = item.escalationKind ?? 'agent_resolvable';
-    return {
-        causeKey: agentResolvablePromotionCauseKey(item.id),
-        organizationId: ctx.organizationId,
-        issueId: null,
-        reasonType: ESCALATION_REASONS.BLOCKED_BY_EXTERNAL,
-        // It was machine-routable, but ${attempts} agent session(s) rode it in over
-        // ~${ageHours}h and none cleared it -- an exhausted machine, so a human takes it.
-        disposition: ESCALATION_DISPOSITIONS.NEEDS_OPERATOR,
-        // Anchor to the focus only when one exists; an anchorless filing files
-        // org-scoped (still visible in the operator inbox, keyed on disposition).
-        anchor: ctx.focusId ? { focusId: ctx.focusId } : {},
-        ...(ctx.productId ? { productId: ctx.productId } : {}),
-        escalationKind: AGENT_RESOLVABLE_PROMOTED_KIND,
-        // Compose the invariant preamble (head) + the original filing body (tail),
-        // then fit under the server-side cap: a candidate filed at the cap would
-        // otherwise produce an over-cap refile the edge rejects on every sweep tick.
-        description: fitPromotionDescription(`A machine-routable (agent_resolvable) filing has had ${attempts} agent ` +
-            `session(s) on its focus (over ~${ageHours}h) without any of them clearing ` +
-            `it, so it is promoted to you.\n\n` +
-            `**Original kind:** ${originalKind}\n` +
-            `**Original filing:** ${item.id}\n` +
-            `**Machine attempts that failed:** ${attempts}\n\n`, `${item.description ?? ''}`, item.id),
-        whatWasTried: `The filing rode into the focus's coding spawns across ${attempts} recorded ` +
-            `agent session(s) over ~${ageHours}h (disposition agent_resolvable) but was ` +
-            `never resolved, so the machine has exhausted its autonomous attempts.`,
-        helpNeeded: `Resolve the underlying condition manually, or re-file with clearer intent if ` +
-            `the machine cannot act on it.`,
-        metadata: {
-            cause: AGENT_RESOLVABLE_PROMOTED_KIND,
-            originalEscalationId: item.id,
-            originalKind,
-            ageHours,
-            // Attempt evidence: the recorded agent sessions that failed to clear this
-            // filing. This is the proof the human lane carries that the machine was
-            // exhausted, not merely that time elapsed.
-            spawnsInWindow: attempts,
-        },
-    };
+export function isStopHoldObservation(item) {
+    if (!item.observation)
+        return false;
+    if (item.escalationKind === COVERAGE_HOLD_KIND)
+        return true;
+    // The item's observation was already read from metadata.observation; hand the holds
+    // rule that same parsed observation so the two can never disagree.
+    return isMachineStopObservation({
+        escalationKind: item.escalationKind,
+        metadata: { ...(item.metadata ?? {}), observation: item.observation },
+    });
+}
+/** Pure: the focuses a stop-kind hold observation blocks. */
+export function stopHeldFocusIds(items) {
+    const held = new Set();
+    for (const item of items) {
+        if (item.focusId && isStopHoldObservation(item))
+            held.add(item.focusId);
+    }
+    return held;
+}
+// ---------------------------------------------------------------------------
+// Decider attempts (recorded on the observation row)
+// ---------------------------------------------------------------------------
+/** metadata keys a hand-off writes on the observation (escalation_update shallow-merges them). */
+export const DECIDER_ATTEMPTS_KEY = 'decider_attempts';
+export const LAST_DECIDED_AT_KEY = 'last_decided_at';
+export const LAST_DECIDER_OUTCOME_KEY = 'last_decider_outcome';
+/** Pure: the recorded decider attempts on a row (0 / null when absent or malformed). */
+export function readDeciderAttempts(metadata) {
+    const raw = metadata?.[DECIDER_ATTEMPTS_KEY];
+    const attempts = typeof raw === 'number' && Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : 0;
+    const at = metadata?.[LAST_DECIDED_AT_KEY];
+    const parsed = typeof at === 'string' ? Date.parse(at) : NaN;
+    return { attempts, lastDecidedAtMs: Number.isNaN(parsed) ? null : parsed };
+}
+/** Pure: whether a decider already ran on this row inside the window (do not re-hand it). */
+export function withinDeciderWindow(metadata, nowMs, windowMs) {
+    const { lastDecidedAtMs } = readDeciderAttempts(metadata);
+    return lastDecidedAtMs !== null && nowMs - lastDecidedAtMs < windowMs;
+}
+/** Record one decider attempt on the observation row (escalation_update merges fields.metadata). */
+export async function recordDeciderAttempt(escalationId, patch, deps = {}) {
+    const call = deps.callApi ?? callApi;
+    await call('escalation_update', { escalationId, fields: { metadata: { ...patch } } });
+}
+/** The default when no decider is wired: nothing runs, every eligible observation stays in the lane (counted undecided). */
+export const NO_ROUTING_DECIDER = async () => ({
+    ran: false,
+    decided: false,
+    detail: 'no routing decider wired',
+});
+const HANDOFF_PRIORITY = { stop_held: 0, unreachable: 1, outlives_focus: 2, exhausted: 3 };
+/** Pure: hand-off order -- stop_held, unreachable, outlives_focus, exhausted; oldest first within a basis. */
+export function orderHandoffs(requests) {
+    return [...requests].sort((a, b) => HANDOFF_PRIORITY[a.basis] - HANDOFF_PRIORITY[b.basis] || a.item.createdAt.localeCompare(b.item.createdAt));
 }
+/** The retired-focus defaults both paths wire. */
+const defaultRetirementDeps = {
+    focusRetired: defaultFocusRetired,
+    retireSwept: defaultRetireSwept,
+    priorRetirementOfCause: (causeKey, focusId, excludeId) => defaultPriorRetirementOfCause(causeKey, focusId, excludeId),
+};
 function defaultDeps() {
     return {
         listOpen: defaultListOpenAgentResolvableForFocus,
-        markResolved: defaultMarkEscalationResolved,
-        file: defaultFileEscalationIdempotent,
-        countSessionsSince: defaultCountFocusSessionsSince,
         now: () => Date.now(),
         thresholdMs: resolveAgentResolvablePromoteMs(),
-        minAttempts: DEFAULT_AGENT_RESOLVABLE_PROMOTE_MIN_ATTEMPTS,
-        focusRetired: defaultFocusRetired,
-        retireSwept: defaultRetireSwept,
+        ...defaultRetirementDeps,
     };
 }
 /**
- * Reconcile a focus's open agent_resolvable filings and return the ones that
- * should ride into THIS spawn. Over-age filings are promoted (needs_operator
- * refile + resolve the source) so they leave the machine lane and reach the
- * human inbox; the rest are returned to ride in as before.
- *
- * Best-effort per filing: a promotion failure is logged and the filing is left
- * to ride (it will be retried next spawn), never thrown -- reconciling must never
- * block a spawn. This is the single entry point the spawn path calls instead of
- * listOpenAgentResolvableForFocus.
- */
-/**
- * Whether a candidate's focus has RETIRED -- converged (every delivery done or
- * cancelled) or no longer active (its status is complete/cancelled, so it is
- * absent from the org's active-focus set). A candidate anchored to such a focus
- * describes work that is finished; promoting it to a human would dump a stale row
- * on the operator inbox (2026-09-09: escalation 9465a40e promoted onto a focus
- * closed for hours). Fail-quiet: any read error returns not-retired, so a
- * transient DB blip never wrongly retires a live candidate (it promotes as before).
- */
-export async function defaultFocusRetired(focusId, ctx) {
-    try {
-        const dels = await defaultGetFocusDeliveries(focusId);
-        if (dels.length > 0 &&
-            dels.every(x => x.executionStatus === DELIVERY_STATUS.DONE || x.executionStatus === DELIVERY_STATUS.CANCELLED)) {
-            return { retire: true, reason: 'focus converged -- all deliveries done/cancelled' };
-        }
-        const active = await defaultGetActiveFocuses(ctx.organizationId, ctx.productId);
-        if (!active.some(f => f.focus_id === focusId)) {
-            return { retire: true, reason: 'focus is not active (complete/cancelled)' };
-        }
-    }
-    catch {
-        // Fail-quiet: do not retire on a read error (promote as before).
-    }
-    return { retire: false, reason: '' };
-}
-/** Retire a candidate whose focus has converged/terminated: resolve auto_swept. */
-function defaultRetireSwept(id, notes) {
-    return defaultMarkEscalationResolved(id, notes, {}, 'auto_swept');
-}
-/**
- * If the candidate's focus has retired, resolve the filing auto_swept and return
- * true (the caller then skips promotion). Best-effort; a retire failure falls
- * through to the normal promotion path. Absent deps => never retires.
+ * Reconcile a focus's open agent_resolvable filings and return the ones that ride
+ * into THIS spawn. The spawned agent is itself a routing authority over what rides
+ * in, so nothing is filed here: an over-age focus-scoped filing on a retired focus is
+ * retired auto_swept; every other filing rides (a condition outliving the focus rides
+ * too -- the org-wide sweep hands it to a routing decider). Best-effort: never throws
+ * past the list read. The single entry point the spawn path calls.
  */
-async function maybeRetireForRetiredFocus(d, itemId, focusId, ctx) {
-    if (!focusId || !d.focusRetired || !d.retireSwept)
-        return false;
-    let verdict;
-    try {
-        verdict = await d.focusRetired(focusId, ctx);
-    }
-    catch (err) {
-        log.warn(`[escalations] focusRetired check failed for ${itemId} (focus ${focusId}): ${err.message}`);
-        return false;
-    }
-    if (!verdict.retire)
-        return false;
-    try {
-        await d.retireSwept(itemId, `Focus retired (${verdict.reason}); this agent_resolvable filing is stale -- auto-swept, not promoted.`);
-        log.info(`[escalations] Retired (NOT promoted) agent_resolvable ${itemId}: ${verdict.reason} (focus ${focusId}).`);
-        return true;
-    }
-    catch (err) {
-        log.warn(`[escalations] Failed to retire agent_resolvable ${itemId} for retired focus ${focusId}: ${err.message}`);
-        return false;
-    }
-}
 export async function reconcileAgentResolvableForFocus(ctx, deps = {}) {
     const d = { ...defaultDeps(), ...deps };
+    const retirement = { ...d, focusRetired: memoizeFocusRetired(d.focusRetired) };
     const open = await d.listOpen(ctx.focusId);
-    const { ride, promote } = partitionAgentResolvableByAge(open, (d.now ?? Date.now)(), d.thresholdMs);
-    for (const item of promote) {
-        // Retired-focus guard: never promote a candidate whose focus has converged or
-        // is complete/cancelled -- retire it auto_swept instead (see maybeRetireForRetiredFocus).
-        if (await maybeRetireForRetiredFocus(d, item.id, ctx.focusId, ctx))
-            continue;
-        const ageHours = Math.max(1, Math.floor(((d.now ?? Date.now)() - Date.parse(item.createdAt)) / 3_600_000));
-        // Attempt-evidence gate: only promote a candidate the machine actually TRIED
-        // and failed to clear. A candidate with zero agent sessions since it was
-        // filed is not exhausted -- it rides on (and the aging observer keeps it
-        // visible in the machine lane), never dumped on a human as a first attempt.
-        const attempts = await d.countSessionsSince(ctx.focusId, item.createdAt);
-        if (!meetsAttemptFloor(attempts, d.minAttempts)) {
-            log.info(`[escalations] Not promoting agent_resolvable ${item.id} (focus ${ctx.focusId}): ` +
-                `${attempts} recorded attempt(s) < floor ${d.minAttempts}; it rides on unattempted`);
-            ride.push(item);
-            continue;
-        }
-        try {
-            const result = await d.file(buildAgentResolvablePromotionParams(item, ctx, ageHours, attempts));
-            // Only retire the machine-routed row once the human-facing refile is in
-            // place (filed OR already suppressed by a prior promotion) -- never resolve
-            // the source without a landing spot, which would drop the signal entirely.
-            if (result.filed || result.suppressed) {
-                await d.markResolved(item.id, `Promoted to a needs_operator escalation after ~${ageHours}h open without ` +
-                    `autonomous resolution (agent_resolvable -> needs_operator).`);
-                log.info(`[escalations] Promoted agent_resolvable ${item.id} to needs_operator (focus ${ctx.focusId}, ~${ageHours}h)`);
-            }
-        }
-        catch (err) {
-            log.warn(`[escalations] Failed to promote agent_resolvable ${item.id} for focus ${ctx.focusId}: ${err.message}`);
-            // Leave it to ride this spawn; next reconcile retries the promotion.
+    const { ride, promote: overAge } = partitionAgentResolvableByAge(open, (d.now ?? Date.now)(), d.thresholdMs);
+    for (const item of overAge) {
+        const retired = await checkFocusRetirement(retirement, item, ctx.focusId, ctx);
+        if (retired.kind !== 'retired')
             ride.push(item);
-        }
     }
     return ride;
 }
 function defaultSweepDeps() {
     return {
         listOpenForOrg: defaultListOpenAgentResolvableForOrg,
+        listLineageCarriers: defaultListOpenLineageCarriersForOrg,
         markResolved: defaultMarkEscalationResolved,
-        file: defaultFileEscalationIdempotent,
+        decide: NO_ROUTING_DECIDER,
+        recordDeciderAttempt: (id, patch) => recordDeciderAttempt(id, patch),
         countSessionsSince: defaultCountFocusSessionsSince,
         now: () => Date.now(),
         thresholdMs: resolveAgentResolvablePromoteMs(),
         minAttempts: DEFAULT_AGENT_RESOLVABLE_PROMOTE_MIN_ATTEMPTS,
-        focusRetired: defaultFocusRetired,
-        retireSwept: defaultRetireSwept,
+        maxPerSweep: ROUTING_DECIDER_MAX_PER_SWEEP,
+        ...defaultRetirementDeps,
     };
 }
 /**
- * Sweep the org's OPEN agent_resolvable filings and promote every one that has
- * stayed open past the age bound to a needs_operator escalation -- WITHOUT any
- * focus spawning. Idempotent (shared cause key + source resolve) and best-effort
- * per filing: a promotion failure is logged and the filing left open for the
- * next sweep, never thrown, so one bad row never aborts the sweep.
- *
- * The refile is org-scoped, so the ONLY hard requirement is an organizationId; a
- * filing that lacks even that cannot be refiled and is skipped (logged). A focus
- * anchor is NOT required: an interactive-session filing carries no focus by
- * construction, yet its needs_operator promotion is still visible (the operator
- * inbox keys on disposition, not on a focus), so an anchorless over-age filing IS
- * promoted -- it is exactly the write-only-sink case this backstop must drain.
+ * Sweep the org's OPEN agent_resolvable filings: close the observations a decider
+ * already made human-facing, retire stale ones, and hand every eligible observation
+ * (see the module ELIGIBILITY) to the routing decider, bounded by maxPerSweep. The
+ * sweep itself never files an escalation. Best-effort per filing: a failure is
+ * logged and the filing left open for the next sweep, never thrown.
  */
 export async function sweepAgentResolvablePromotions(deps = {}) {
     const d = { ...defaultSweepDeps(), ...deps };
     const open = await d.listOpenForOrg();
-    const { promote } = partitionAgentResolvableByAge(open, (d.now ?? Date.now)(), d.thresholdMs);
-    let promoted = 0;
-    let retired = 0;
-    for (const item of promote) {
-        if (!item.organizationId) {
-            log.warn(`[escalations] agent_resolvable ${item.id} is over-age but lacks an org anchor; ` +
-                `cannot org-scope the refile (skipping)`);
+    const nowMs = (d.now ?? Date.now)();
+    const counts = {
+        scanned: open.length, retired: 0, sourcesClosed: 0, handed: 0, decided: 0, undecided: 0, deferred: 0,
+    };
+    const lane = await closeDecidedSources(d, open, counts);
+    const ordered = orderHandoffs(await collectHandoffs(d, lane, nowMs, counts));
+    const batch = ordered.slice(0, Math.max(0, d.maxPerSweep));
+    counts.deferred = ordered.length - batch.length;
+    counts.handed = batch.length;
+    const outcomes = await Promise.all(batch.map((request) => handOff(d, request)));
+    for (const decided of outcomes) {
+        if (decided)
+            counts.decided++;
+        else
+            counts.undecided++;
+    }
+    return counts;
+}
+/**
+ * Close every open observation an open human-lane row names as its source
+ * (auto_swept -- no actor). Returns the rest of the lane. A failed carrier read
+ * closes nothing this sweep; a failed close leaves the source open but still
+ * withholds it from a second decider (it has been decided).
+ */
+async function closeDecidedSources(d, open, counts) {
+    let carriers;
+    try {
+        carriers = await d.listLineageCarriers();
+    }
+    catch (err) {
+        log.warn(`[escalations] lineage-carrier read failed; no sources closed this sweep: ${err.message}`);
+        return [...open];
+    }
+    const carrierBySource = new Map(carriers.map((c) => [c.sourceEscalationId, c.id]));
+    const lane = [];
+    for (const item of open) {
+        const carrierId = carrierBySource.get(item.id);
+        if (carrierId === undefined) {
+            lane.push(item);
             continue;
         }
-        // Retired-focus guard: a candidate whose focus has converged / is
-        // complete/cancelled is stale -- retire it auto_swept instead of promoting a
-        // dead row onto the operator inbox (2026-09-09). Runs BEFORE the attempt floor.
-        if (await maybeRetireForRetiredFocus(d, item.id, item.focusId, { organizationId: item.organizationId, ...(item.productId ? { productId: item.productId } : {}) })) {
-            retired++;
-            continue;
+        try {
+            await d.markResolved(item.id, 'auto_swept', `A routing decider made this observation human-facing as escalation ${carrierId} ` +
+                `(metadata.originalEscalationId). Closed here; that row's resolver is what the routing measurement judges.`);
+            counts.sourcesClosed++;
         }
-        // Attempt-evidence gate. A filing with no focus anchor cannot accrue agent
-        // sessions -- there is no machine lane to be attempted in -- so it has zero
-        // attempts and is NOT promoted (new anchorless filings are refused at the
-        // filing boundary; the aging observer keeps any residue visible). A
-        // focus-anchored candidate promotes only once the machine has actually tried
-        // and failed it minAttempts times.
-        const attempts = item.focusId
-            ? await d.countSessionsSince(item.focusId, item.createdAt)
-            : 0;
-        if (!meetsAttemptFloor(attempts, d.minAttempts)) {
-            log.info(`[escalations] Org-wide sweep not promoting agent_resolvable ${item.id} ` +
-                `(focus ${item.focusId ?? '<none>'}): ${attempts} recorded attempt(s) < floor ${d.minAttempts}`);
-            continue;
+        catch (err) {
+            log.warn(`[escalations] Failed to close decided observation ${item.id} (carrier ${carrierId}): ${err.message}`);
         }
-        const ageHours = Math.max(1, Math.floor(((d.now ?? Date.now)() - Date.parse(item.createdAt)) / 3_600_000));
-        const ctx = {
-            organizationId: item.organizationId,
-            ...(item.focusId ? { focusId: item.focusId } : {}),
-            ...(item.productId ? { productId: item.productId } : {}),
-        };
+    }
+    return lane;
+}
+/** Evaluate every lane filing outside the decider window; returns the eligible hand-offs. */
+async function collectHandoffs(d, lane, nowMs, counts) {
+    const stopHeld = stopHeldFocusIds(lane);
+    // One retired-focus read per focus for the whole sweep, however many candidates share it.
+    const retirement = { ...d, focusRetired: memoizeFocusRetired(d.focusRetired) };
+    const windowMs = d.deciderWindowMs ?? d.thresholdMs;
+    const requests = [];
+    for (const item of lane) {
+        if (withinDeciderWindow(item.metadata, nowMs, windowMs))
+            continue;
+        const verdict = await evaluateCandidate(d, retirement, item, nowMs, stopHeld);
+        if (verdict === 'retired')
+            counts.retired++;
+        else if (verdict !== null)
+            requests.push(verdict);
+    }
+    return requests;
+}
+/** Pure: whether a filing is past the age bound (an unparseable createdAt is not). */
+function isOverAge(createdAt, nowMs, thresholdMs) {
+    const created = Date.parse(createdAt);
+    return !Number.isNaN(created) && nowMs - created > thresholdMs;
+}
+/**
+ * One lane filing: retire it, hand it off (a request), or leave it (null). See the
+ * module ELIGIBILITY. An over-age candidate goes through the full retired-focus guard
+ * (which may retire it); a fresh one only READS its focus's state.
+ */
+async function evaluateCandidate(d, retirement, item, nowMs, stopHeld) {
+    if (!item.organizationId) {
+        log.warn(`[escalations] agent_resolvable ${item.id} lacks an org anchor; not handed to a routing decider`);
+        return null;
+    }
+    const base = {
+        item,
+        ageHours: openAgeHours(item.createdAt, nowMs),
+        deciderAttempts: readDeciderAttempts(item.metadata).attempts,
+    };
+    if (!item.focusId)
+        return { ...base, basis: 'unreachable', attempts: 0 };
+    const scope = { organizationId: item.organizationId, ...(item.productId ? { productId: item.productId } : {}) };
+    const overAge = isOverAge(item.createdAt, nowMs, d.thresholdMs);
+    const state = overAge
+        ? await checkFocusRetirement(retirement, item, item.focusId, scope)
+        : await peekFocusRetirement(retirement, item, item.focusId, scope);
+    if (state.kind === 'retired')
+        return 'retired';
+    if (state.kind === 'awaiting_retirement')
+        return null;
+    if (state.kind === 'outlives') {
+        return { ...base, basis: 'outlives_focus', attempts: 0, retiredFocusReason: state.reason };
+    }
+    const withFocus = state.focus ? { focus: state.focus } : {};
+    if (stopHeld.has(item.focusId))
+        return { ...base, ...withFocus, basis: 'stop_held', attempts: 0 };
+    if (state.focus && !state.focus.armed)
+        return { ...base, ...withFocus, basis: 'unreachable', attempts: 0 };
+    if (!overAge)
+        return null;
+    const attempts = await d.countSessionsSince(item.focusId, item.createdAt);
+    const basis = promotionBasis(attempts, d.minAttempts, item.observation !== undefined);
+    if (!basis) {
+        log.info(`[escalations] Not handing off agent_resolvable ${item.id} (focus ${item.focusId}): ` +
+            `${attempts} recorded attempt(s) < floor ${d.minAttempts}; it stays in the lane`);
+        return null;
+    }
+    return { ...base, ...withFocus, basis, attempts };
+}
+/**
+ * Hand one observation to the decider. A decider that RAN records the attempt on the
+ * row (so it is not re-handed inside the window); one that did not complete cleanly
+ * leaves the observation in the lane -- no deterministic human fallback. Returns
+ * whether it decided.
+ */
+async function handOff(d, request) {
+    const { item, basis } = request;
+    let result;
+    try {
+        result = await d.decide(request);
+    }
+    catch (err) {
+        result = { ran: false, decided: false, detail: `decider threw: ${err.message}` };
+    }
+    if (result.ran) {
         try {
-            const result = await d.file(buildAgentResolvablePromotionParams(item, ctx, ageHours, attempts));
-            // Only retire the source once the human-facing refile is in place (filed OR
-            // already suppressed by a prior promotion) -- never resolve without a
-            // landing spot, which would drop the signal entirely.
-            if (result.filed || result.suppressed) {
-                await d.markResolved(item.id, `Promoted to a needs_operator escalation after ~${ageHours}h open without ` +
-                    `autonomous resolution, via the org-wide sweep (its focus never spawned a ` +
-                    `team). agent_resolvable -> needs_operator.`);
-                promoted++;
-                log.info(`[escalations] Org-wide sweep promoted agent_resolvable ${item.id} to needs_operator ` +
-                    `(focus ${item.focusId ?? '<none>'}, ~${ageHours}h)`);
-            }
+            await d.recordDeciderAttempt(item.id, {
+                [DECIDER_ATTEMPTS_KEY]: request.deciderAttempts + 1,
+                [LAST_DECIDED_AT_KEY]: new Date((d.now ?? Date.now)()).toISOString(),
+                [LAST_DECIDER_OUTCOME_KEY]: result.detail,
+            });
         }
         catch (err) {
-            log.warn(`[escalations] Org-wide sweep failed to promote agent_resolvable ${item.id}: ` +
-                `${err.message}`);
-            // Left open; the next sweep retries.
+            log.warn(`[escalations] Failed to record decider attempt on ${item.id}: ${err.message}`);
         }
     }
-    return { scanned: open.length, promoted, retired };
+    if (result.decided) {
+        log.info(`[escalations] Routing decider ran on agent_resolvable ${item.id} (basis ${basis}): ${result.detail}`);
+    }
+    else {
+        log.warn(`[escalations] UNDECIDED agent_resolvable ${item.id} (basis ${basis}, focus ${item.focusId ?? '<none>'}): ` +
+            `${result.detail}. It stays in the machine lane; no deterministic human fallback.`);
+    }
+    return result.decided;
 }
 //# sourceMappingURL=agent-resolvable-promotion.js.map