@telora/daemon 0.22.239 → 0.22.289

package/dist/supervision/agent-resolvable-retirement.js

@@ -0,0 +1,228 @@
+// PINNED-BY-BEGIN (generated by gen:pinned-by -- do not hand-edit; checked by lint:pinned-by)
+// Pinned by: packages/daemon/src/supervision/agent-resolvable-retired-focus.test.ts
+// PINNED-BY-END
+/**
+ * The retired-focus guard of the agent_resolvable routing hand-off, and what the
+ * guard learns about a live focus on the way.
+ *
+ * Before handing a candidate to a routing decider, both paths
+ * (agent-resolvable-promotion.ts) ask whether its focus has RETIRED -- converged
+ * (every delivery done or cancelled) or no longer active (complete/cancelled). A
+ * candidate describing the focus's own finished work is stale: it is retired
+ * auto_swept.
+ *
+ * RULE (which conditions are retired, and which are not):
+ *
+ *  - A condition that OUTLIVES the focus is HANDED TO A ROUTING DECIDER, never
+ *    retired. It outlives the focus when it lives on a branch, the integration
+ *    line, or the host rather than in the focus's own work: its kind is in
+ *    OUTLIVES_FOCUS_KINDS, or its metadata names a branch (BRANCH_METADATA_KEYS).
+ *    A converged focus does not clear a stuck, conflicted or dirty focus branch,
+ *    a red integration CI run, a failed CD push, or a stale daemon; retiring one
+ *    swallows a live condition, and its detector (which a resolved row does not
+ *    suppress) re-files it on the next tick -- a file -> retire -> re-file cycle
+ *    minting a fresh row per tick.
+ *  - Only a FOCUS-SCOPED condition is retired.
+ *  - Cycle guard for a misclassified kind: a focus-scoped candidate whose
+ *    cause_key was already retired auto_swept on the same focus has been
+ *    re-observed after the focus retired, which is itself evidence the condition
+ *    outlives the focus -- it is handed off too. A cause is retired at most once.
+ *    The observation stays OPEN (suppressing its detector) until a decider acts; a
+ *    decider's human-facing filing carries the source's cause key as
+ *    metadata.original_cause_key (telora_agent escalate sourceCauseKey), which
+ *    escalation-suppression matches, so the detector stays silent while it is open.
+ *
+ * The retirement read already fetches the org's active focuses, so a LIVE
+ * verdict carries the focus's title and arm state (PromotionFocusSnapshot), which
+ * the hand-off uses (an un-armed focus is unreachable) and hands to the decider.
+ *
+ * History: docs/daemon/history-platform.md (supervision/agent-resolvable-retirement.ts).
+ */
+import { DELIVERY_STATUS } from '@telora/daemon-core';
+import { markEscalationResolved as defaultMarkEscalationResolved } from '../queries/escalations/escalations.js';
+import { getFocusDeliveries as defaultGetFocusDeliveries } from '../queries/focuses/focuses.js';
+import { getActiveFocuses as defaultGetActiveFocuses } from '../queries/focuses/focus-discovery.js';
+import { callApi } from '../queries/api-client/shared.js';
+import { focusMayRunTeam } from './null-role-spawn.js';
+import { createLogger } from '../log/daemon-log.js';
+const log = createLogger({ module: 'escalations' });
+/**
+ * escalation_kind values whose condition lives on a branch, the integration line
+ * or the host, so it outlives the focus that filed it. Daemon-local literals: the
+ * kind constants live in merge/, ci/ and drift/ modules this query leaf must not
+ * import (they import the query layer). Keep in sync with STUCK_FOCUS_BRANCH_KIND,
+ * CD_PUSH_FAILED_KIND, CI_RUN_RED_ESCALATION_KIND, MERGE_CONFLICT_ESCALATION_KIND,
+ * MERGE_REFUSED_DIRTY_ESCALATION_KIND and PROPAGATION_STALE_ESCALATION_KIND.
+ */
+export const OUTLIVES_FOCUS_KINDS = new Set([
+    'stuck_focus_branch',
+    'cd_push_failed',
+    'ci_run_red',
+    'merge_conflict',
+    'merge_refused_dirty',
+    'propagation_stale',
+]);
+/**
+ * Metadata keys a branch-anchored filing stamps: stuck_focus_branch branch_name,
+ * ci_run_red branch, cd_push_failed integration_branch. A filing of any kind that
+ * names a branch here outlives its focus.
+ */
+const BRANCH_METADATA_KEYS = ['branch_name', 'branch', 'integration_branch'];
+/** Pure: the branch a filing's metadata names, or null. */
+export function branchOfFiling(metadata) {
+    if (!metadata)
+        return null;
+    for (const key of BRANCH_METADATA_KEYS) {
+        const value = metadata[key];
+        if (typeof value === 'string' && value.trim().length > 0)
+            return value.trim();
+    }
+    return null;
+}
+/** Pure: whether a filing's condition outlives its focus (see the module RULE). */
+export function conditionOutlivesFocus(item) {
+    if (item.escalationKind !== null && OUTLIVES_FOCUS_KINDS.has(item.escalationKind))
+        return true;
+    return branchOfFiling(item.metadata) !== null;
+}
+/**
+ * Whether a candidate's focus has RETIRED -- converged (every delivery done or
+ * cancelled) or no longer active (absent from the org's active-focus set). A live
+ * focus's verdict carries its title + arm state. Fail-quiet: any read error
+ * returns not-retired with no snapshot, 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);
+        const live = active.find(f => f.focus_id === focusId);
+        if (!live) {
+            return { retire: true, reason: 'focus is not active (complete/cancelled)' };
+        }
+        return {
+            retire: false,
+            reason: '',
+            focus: { name: live.focus_name, armed: focusMayRunTeam(live.assigned_agent_role_id) },
+        };
+    }
+    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. */
+export function defaultRetireSwept(id, notes) {
+    const resolutionClass = 'auto_swept';
+    return defaultMarkEscalationResolved(id, resolutionClass, notes);
+}
+/** Resolved rows scanned per focus for the cycle guard (bounded; newest first). */
+export const RETIREMENT_MEMORY_SCAN_LIMIT = 200;
+/**
+ * Whether an escalation carrying `causeKey` was already resolved auto_swept on the
+ * focus (excluding the candidate itself). Only consulted for a candidate the guard
+ * is about to retire, so it runs at most once per retire decision. THROWS on a
+ * hard API error; the caller fails toward retiring (the prior behaviour).
+ */
+export async function defaultPriorRetirementOfCause(causeKey, focusId, excludeId) {
+    const result = await callApi('escalation_list', {
+        fields: { statuses: ['resolved'], focusId },
+        limit: RETIREMENT_MEMORY_SCAN_LIMIT,
+        detail: 'full',
+    });
+    return (result.escalations ?? []).some((e) => e.id !== excludeId && e.resolutionClass === 'auto_swept' && e.metadata?.cause_key === causeKey);
+}
+/**
+ * Pure wrapper: memoize the retired-focus read per focusId for ONE promotion pass,
+ * so a sweep over many candidates on the same focus reads that focus once.
+ */
+export function memoizeFocusRetired(fn) {
+    if (!fn)
+        return undefined;
+    const cache = new Map();
+    return (focusId, ctx) => {
+        let verdict = cache.get(focusId);
+        if (!verdict) {
+            verdict = fn(focusId, ctx);
+            cache.set(focusId, verdict);
+        }
+        return verdict;
+    };
+}
+async function causeRetiredBefore(d, item, focusId) {
+    const causeKey = item.metadata?.cause_key;
+    if (typeof causeKey !== 'string' || !d.priorRetirementOfCause)
+        return false;
+    try {
+        return await d.priorRetirementOfCause(causeKey, focusId, item.id);
+    }
+    catch (err) {
+        log.warn(`[escalations] prior-retirement read failed for ${item.id} (focus ${focusId}): ${err.message}`);
+        return false;
+    }
+}
+/**
+ * READ-ONLY sibling of checkFocusRetirement for a candidate still within the age
+ * bound: it learns the focus's state (arm state, retired or not) without retiring
+ * anything. 'outlives' (a retired focus + an outliving condition) is handed to a
+ * routing decider at once; a focus-scoped condition on a retired focus reads
+ * 'awaiting_retirement' (retired by checkFocusRetirement once over-age); otherwise
+ * 'live'. Best-effort: a failed read is 'live' with no snapshot.
+ */
+export async function peekFocusRetirement(d, item, focusId, ctx) {
+    if (!d.focusRetired)
+        return { kind: 'live' };
+    let verdict;
+    try {
+        verdict = await d.focusRetired(focusId, ctx);
+    }
+    catch (err) {
+        log.warn(`[escalations] focusRetired read failed for ${item.id} (focus ${focusId}): ${err.message}`);
+        return { kind: 'live' };
+    }
+    if (!verdict.retire)
+        return verdict.focus ? { kind: 'live', focus: verdict.focus } : { kind: 'live' };
+    return conditionOutlivesFocus(item) ? { kind: 'outlives', reason: verdict.reason } : { kind: 'awaiting_retirement' };
+}
+/**
+ * Decide a candidate's retired-focus outcome (see the module RULE): 'retired'
+ * (resolved auto_swept here; the caller skips it), 'outlives' (its focus retired
+ * but the condition outlives it; the caller hands it to a routing decider), or
+ * 'live' (hand off / ride as usual, carrying the focus snapshot when known).
+ * Best-effort: a failed read or a failed retire falls through to 'live'.
+ */
+export async function checkFocusRetirement(d, item, focusId, ctx) {
+    if (!focusId || !d.focusRetired)
+        return { kind: 'live' };
+    let verdict;
+    try {
+        verdict = await d.focusRetired(focusId, ctx);
+    }
+    catch (err) {
+        log.warn(`[escalations] focusRetired check failed for ${item.id} (focus ${focusId}): ${err.message}`);
+        return { kind: 'live' };
+    }
+    if (!verdict.retire)
+        return verdict.focus ? { kind: 'live', focus: verdict.focus } : { kind: 'live' };
+    if (conditionOutlivesFocus(item))
+        return { kind: 'outlives', reason: verdict.reason };
+    if (await causeRetiredBefore(d, item, focusId)) {
+        return { kind: 'outlives', reason: `${verdict.reason}; the same cause re-filed after an earlier retirement` };
+    }
+    if (!d.retireSwept)
+        return { kind: 'live' };
+    try {
+        await d.retireSwept(item.id, `Focus retired (${verdict.reason}); this agent_resolvable filing is stale -- auto-swept, not promoted.`);
+        log.info(`[escalations] Retired (NOT promoted) agent_resolvable ${item.id}: ${verdict.reason} (focus ${focusId}).`);
+        return { kind: 'retired' };
+    }
+    catch (err) {
+        log.warn(`[escalations] Failed to retire agent_resolvable ${item.id} for retired focus ${focusId}: ${err.message}`);
+        return { kind: 'live' };
+    }
+}
+//# sourceMappingURL=agent-resolvable-retirement.js.map

package/dist/supervision/agent-resolvable-retirement.js.map

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

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

@@ -0,0 +1,84 @@
+/**
+ * The CLOSE-HALVES of the escalation kinds the daemon files for itself: once the
+ * daemon observes a filed condition clear, resolve the rows that describe it and
+ * retire the matching symptoms absorbed onto the scope's other open rows
+ * (./incident-correlation.ts retireClearedSymptoms, contract rule 6), so no row
+ * or symptom outlives its condition.
+ *
+ * Which rows a clearing resolves is decided here (the per-focus kind, the
+ * worktree-dirty siblings, the focus-convergence terminated kinds); the row
+ * predicates are queries/escalations/incident-record.ts and the resolve write is
+ * queries/escalations/escalations.ts markEscalationResolved.
+ *
+ * @module supervision/escalation-clearing
+ */
+import type { EscalationResolutionClass } from '@telora/daemon-core';
+import { type IncidentRow } from '../queries/escalations/incident-record.js';
+import { type SymptomClearing } from './incident-correlation.js';
+/**
+ * The close half for a per-FOCUS escalation kind: resolve every open (pending or
+ * in_review) escalation of `escalationKind` for the focus, once the daemon has
+ * observed its clearing condition. Mirrors resolveOpenWorktreeDirtyEscalations
+ * (the delivery-scoped precedent) for the focus-scoped blocking kinds that
+ * applyRespawnGuard reads as a spawn block (team_failure) -- so a machine-filed
+ * spawn block clears itself the moment its own condition (genuine progress)
+ * clears, and the armed focus resumes spawning with no human act.
+ *
+ * Best-effort: a resolve failure for one row is logged and skipped, never thrown,
+ * so the caller's primary work (advancing a delivery) is not blocked. Returns the
+ * count resolved.
+ */
+export declare function resolveOpenFocusEscalationsOfKind(focusId: string, escalationKind: string, resolutionClass: EscalationResolutionClass, resolutionNotes: string): Promise<number>;
+/**
+ * Retire a clearing's absorbed symptoms over the API (./incident-correlation.ts retireClearedSymptoms,
+ * rule 6) -- for the resolve helpers here and for sweeps elsewhere that resolve their own rows.
+ * Best-effort: logs, never throws. Returns the count of symptoms retired.
+ */
+export declare function retireAbsorbedSymptoms(clearing: SymptomClearing, opts?: {
+    rows?: readonly IncidentRow[];
+    skipIds?: readonly string[];
+}): Promise<number>;
+/**
+ * The escalation kinds that describe a focus that cannot converge -- the review
+ * hand-off breaker family plus team_failure. When the focus DOES converge, each
+ * of these rows describes nothing and must retire itself (there is no reason for
+ * a converged focus to carry a pending operator row). The review kinds and
+ * event-escalations' team_failure also stamp `terminates_when: 'focus_converged'`
+ * in their metadata; the stalled-team-backstop team_failure files through a
+ * causeKey path without metadata, so this kind list is the robust matcher.
+ */
+export declare const FOCUS_CONVERGENCE_TERMINATED_KINDS: ReadonlySet<string>;
+/**
+ * Retire every open (pending/in_review) escalation on a focus that carries a
+ * focus-convergence terminator -- either its kind is in
+ * FOCUS_CONVERGENCE_TERMINATED_KINDS or its metadata declares
+ * `terminates_when: 'focus_converged'`. Called from the review-exit convergence
+ * hook when the focus converges (its verify deliveries reached done and
+ * review_requested_at cleared): the rows describe a focus that could not
+ * converge, and it just did, so they are resolved auto_swept with a note naming
+ * the converging review. Best-effort per row; returns the count resolved.
+ */
+export declare function resolveConvergedFocusEscalations(focusId: string, resolutionNotes: string): Promise<number>;
+/**
+ * Auto-resolve the open worktree-dirty escalations for a focus once their
+ * underlying condition has cleared (the worktree is observed clean again, or a
+ * merge conflict has been merged through). Lists the open rows for the focus
+ * narrowed to `kinds`, resolves each with a daemon-remediation note, and
+ * returns the count resolved.
+ *
+ * This is the close half of the disposition-aware model: an agent_resolvable
+ * condition that auto-remediates should also stop showing in the human inbox
+ * the moment it clears, instead of lingering as a resolved-in-fact but
+ * still-pending row. Best-effort: a resolve failure for one row is logged and
+ * skipped, never thrown, so the caller's primary work is not blocked.
+ *
+ * Callers MUST pass `kinds` narrowed to the conditions the clearing event
+ * actually resolves -- e.g. a clean worktree clears advance_blocked /
+ * merge_refused_dirty but NOT merge_conflict (a content conflict is not a dirty
+ * worktree), and a successful merge clears merge_conflict.
+ *
+ * `resolutionClass` is REQUIRED: the class of actor that observed the clearing
+ * (the daemon's condition-cleared callers pass 'auto_swept').
+ */
+export declare function resolveOpenWorktreeDirtyEscalations(focusId: string, kinds: readonly string[], resolutionClass: EscalationResolutionClass, resolutionNotes?: string): Promise<number>;
+//# sourceMappingURL=escalation-clearing.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"escalation-clearing.d.ts","sourceRoot":"","sources":["../../src/supervision/escalation-clearing.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAIrE,OAAO,EAAgD,KAAK,WAAW,EAAE,MAAM,2CAA2C,CAAC;AAC3H,OAAO,EAAyC,KAAK,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAKxG;;;;;;;;;;;;GAYG;AACH,wBAAsB,iCAAiC,CACrD,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,MAAM,EACtB,eAAe,EAAE,yBAAyB,EAC1C,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,MAAM,CAAC,CAOjB;AAqBD;;;;GAIG;AACH,wBAAsB,sBAAsB,CAAC,QAAQ,EAAE,eAAe,EAAE,IAAI,GAAE;IAAE,IAAI,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;IAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAKlK;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,kCAAkC,EAAE,WAAW,CAAC,MAAM,CAKjE,CAAC;AAEH;;;;;;;;;GASG;AACH,wBAAsB,gCAAgC,CACpD,OAAO,EAAE,MAAM,EACf,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,MAAM,CAAC,CAmBjB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,mCAAmC,CACvD,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,eAAe,EAAE,yBAAyB,EAC1C,eAAe,SAAuE,GACrF,OAAO,CAAC,MAAM,CAAC,CAQjB"}

package/dist/supervision/escalation-clearing.js

@@ -0,0 +1,143 @@
+// PINNED-BY-BEGIN (generated by gen:pinned-by -- do not hand-edit; checked by lint:pinned-by)
+// Pinned by: packages/daemon/src/queries/escalations/has-open-worktree-dirty-escalation.test.ts,
+//   packages/daemon/src/queries/escalations/resolve-converged-focus-escalations.test.ts,
+//   packages/daemon/src/supervision/incident-correlation.test.ts
+// PINNED-BY-END
+import { callApi } from '../queries/api-client/shared.js';
+import { markEscalationResolved } from '../queries/escalations/escalations.js';
+import { OPEN_ESCALATION_STATUSES } from '../queries/escalations/escalation-dispositions.js';
+import { isOpenFocusKindRow, isOpenWorktreeDirtyMatch } from '../queries/escalations/incident-record.js';
+import { incidentIoOver, retireClearedSymptoms } from './incident-correlation.js';
+import { createLogger } from '../log/daemon-log.js';
+const log = createLogger({ module: 'escalations' });
+/**
+ * The close half for a per-FOCUS escalation kind: resolve every open (pending or
+ * in_review) escalation of `escalationKind` for the focus, once the daemon has
+ * observed its clearing condition. Mirrors resolveOpenWorktreeDirtyEscalations
+ * (the delivery-scoped precedent) for the focus-scoped blocking kinds that
+ * applyRespawnGuard reads as a spawn block (team_failure) -- so a machine-filed
+ * spawn block clears itself the moment its own condition (genuine progress)
+ * clears, and the armed focus resumes spawning with no human act.
+ *
+ * Best-effort: a resolve failure for one row is logged and skipped, never thrown,
+ * so the caller's primary work (advancing a delivery) is not blocked. Returns the
+ * count resolved.
+ */
+export async function resolveOpenFocusEscalationsOfKind(focusId, escalationKind, resolutionClass, resolutionNotes) {
+    const result = await callApi('escalation_list', {
+        fields: { statuses: ['pending', 'in_review'], escalationKind, focusId },
+        limit: 500,
+    });
+    const open = (result.escalations ?? []).filter((e) => isOpenFocusKindRow(e, focusId, escalationKind));
+    return resolveAndRetire(open, { kinds: [escalationKind], scope: { focusId }, resolutionClass }, resolutionNotes, `${escalationKind} escalation for focus ${focusId}`);
+}
+/**
+ * The shared close-half body: resolve each own-kind row (best-effort per row), then retire the
+ * clearing's ABSORBED symptoms from the scope's other open rows (reusing `rows` when given, else
+ * reading them) so no symptom outlives its condition. Returns the count resolved.
+ */
+async function resolveAndRetire(own, clearing, resolutionNotes, label, rows) {
+    let resolved = 0;
+    for (const e of own) {
+        try {
+            await markEscalationResolved(e.id, clearing.resolutionClass, resolutionNotes);
+            resolved++;
+        }
+        catch (err) {
+            log.warn(`[escalations] Failed to auto-resolve ${label} (escalation ${e.id}): ${err.message}`);
+        }
+    }
+    await retireAbsorbedSymptoms(clearing, { ...(rows ? { rows } : {}), skipIds: own.map((e) => e.id) });
+    return resolved;
+}
+/**
+ * Retire a clearing's absorbed symptoms over the API (./incident-correlation.ts retireClearedSymptoms,
+ * rule 6) -- for the resolve helpers here and for sweeps elsewhere that resolve their own rows.
+ * Best-effort: logs, never throws. Returns the count of symptoms retired.
+ */
+export async function retireAbsorbedSymptoms(clearing, opts = {}) {
+    const outcome = await retireClearedSymptoms(clearing, incidentIoOver(callApi), opts);
+    for (const warning of outcome.warnings)
+        log.warn(`[escalations] ${warning}`);
+    if (outcome.retired > 0)
+        log.info(`[escalations] Retired ${outcome.retired} absorbed symptom(s) whose condition cleared.`);
+    return outcome.retired;
+}
+/**
+ * The escalation kinds that describe a focus that cannot converge -- the review
+ * hand-off breaker family plus team_failure. When the focus DOES converge, each
+ * of these rows describes nothing and must retire itself (there is no reason for
+ * a converged focus to carry a pending operator row). The review kinds and
+ * event-escalations' team_failure also stamp `terminates_when: 'focus_converged'`
+ * in their metadata; the stalled-team-backstop team_failure files through a
+ * causeKey path without metadata, so this kind list is the robust matcher.
+ */
+export const FOCUS_CONVERGENCE_TERMINATED_KINDS = new Set([
+    'review_handoff_exhausted',
+    'review_cycle_cap_exceeded',
+    'review_gaps_without_issue',
+    'team_failure',
+]);
+/**
+ * Retire every open (pending/in_review) escalation on a focus that carries a
+ * focus-convergence terminator -- either its kind is in
+ * FOCUS_CONVERGENCE_TERMINATED_KINDS or its metadata declares
+ * `terminates_when: 'focus_converged'`. Called from the review-exit convergence
+ * hook when the focus converges (its verify deliveries reached done and
+ * review_requested_at cleared): the rows describe a focus that could not
+ * converge, and it just did, so they are resolved auto_swept with a note naming
+ * the converging review. Best-effort per row; returns the count resolved.
+ */
+export async function resolveConvergedFocusEscalations(focusId, resolutionNotes) {
+    const result = await callApi('escalation_list', {
+        fields: { statuses: ['pending', 'in_review'], focusId },
+        limit: 500,
+    });
+    const open = (result.escalations ?? []).filter((e) => {
+        if (e.status && !OPEN_ESCALATION_STATUSES.has(e.status))
+            return false;
+        const meta = e.metadata ?? null;
+        const belongs = e.focusId === focusId || meta?.focusId === focusId;
+        if (!belongs)
+            return false;
+        const kind = e.escalationKind ?? meta?.kind ?? '';
+        return FOCUS_CONVERGENCE_TERMINATED_KINDS.has(kind) || meta?.terminates_when === 'focus_converged';
+    });
+    const clearing = { kinds: [...FOCUS_CONVERGENCE_TERMINATED_KINDS], scope: { focusId }, resolutionClass: 'auto_swept' };
+    const resolved = await resolveAndRetire(open, clearing, resolutionNotes, `converged-focus escalation for focus ${focusId}`, result.escalations ?? []);
+    if (resolved > 0) {
+        log.info(`[escalations] Auto-swept ${resolved} convergence-terminated escalation(s) for focus ${focusId}.`);
+    }
+    return resolved;
+}
+/**
+ * Auto-resolve the open worktree-dirty escalations for a focus once their
+ * underlying condition has cleared (the worktree is observed clean again, or a
+ * merge conflict has been merged through). Lists the open rows for the focus
+ * narrowed to `kinds`, resolves each with a daemon-remediation note, and
+ * returns the count resolved.
+ *
+ * This is the close half of the disposition-aware model: an agent_resolvable
+ * condition that auto-remediates should also stop showing in the human inbox
+ * the moment it clears, instead of lingering as a resolved-in-fact but
+ * still-pending row. Best-effort: a resolve failure for one row is logged and
+ * skipped, never thrown, so the caller's primary work is not blocked.
+ *
+ * Callers MUST pass `kinds` narrowed to the conditions the clearing event
+ * actually resolves -- e.g. a clean worktree clears advance_blocked /
+ * merge_refused_dirty but NOT merge_conflict (a content conflict is not a dirty
+ * worktree), and a successful merge clears merge_conflict.
+ *
+ * `resolutionClass` is REQUIRED: the class of actor that observed the clearing
+ * (the daemon's condition-cleared callers pass 'auto_swept').
+ */
+export async function resolveOpenWorktreeDirtyEscalations(focusId, kinds, resolutionClass, resolutionNotes = 'Auto-resolved by the daemon: the worktree-dirty condition cleared.') {
+    const kindSet = new Set(kinds);
+    const result = await callApi('escalation_list', {
+        fields: { statuses: ['pending', 'in_review'], focusId },
+        limit: 500,
+    });
+    const open = (result.escalations ?? []).filter((e) => isOpenWorktreeDirtyMatch(e, focusId, kindSet));
+    return resolveAndRetire(open, { kinds, scope: { focusId }, resolutionClass }, resolutionNotes, `worktree-dirty escalation for focus ${focusId}`, result.escalations ?? []);
+}
+//# sourceMappingURL=escalation-clearing.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"escalation-clearing.js","sourceRoot":"","sources":["../../src/supervision/escalation-clearing.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,iGAAiG;AACjG,yFAAyF;AACzF,iEAAiE;AACjE,gBAAgB;AAkBhB,OAAO,EAAE,OAAO,EAAE,MAAM,iCAAiC,CAAC;AAC1D,OAAO,EAAE,sBAAsB,EAAE,MAAM,uCAAuC,CAAC;AAC/E,OAAO,EAAE,wBAAwB,EAAE,MAAM,mDAAmD,CAAC;AAC7F,OAAO,EAAE,kBAAkB,EAAE,wBAAwB,EAAoB,MAAM,2CAA2C,CAAC;AAC3H,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAwB,MAAM,2BAA2B,CAAC;AACxG,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEpD,MAAM,GAAG,GAAG,YAAY,CAAC,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC,CAAC;AAEpD;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,iCAAiC,CACrD,OAAe,EACf,cAAsB,EACtB,eAA0C,EAC1C,eAAuB;IAEvB,MAAM,MAAM,GAAG,MAAM,OAAO,CAAiC,iBAAiB,EAAE;QAC9E,MAAM,EAAE,EAAE,QAAQ,EAAE,CAAC,SAAS,EAAE,WAAW,CAAC,EAAE,cAAc,EAAE,OAAO,EAAE;QACvE,KAAK,EAAE,GAAG;KACX,CAAC,CAAC;IACH,MAAM,IAAI,GAAG,CAAC,MAAM,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,kBAAkB,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC;IACtG,OAAO,gBAAgB,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,CAAC,cAAc,CAAC,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,EAAE,eAAe,EAAE,EAAE,eAAe,EAAE,GAAG,cAAc,yBAAyB,OAAO,EAAE,CAAC,CAAC;AACxK,CAAC;AAED;;;;GAIG;AACH,KAAK,UAAU,gBAAgB,CAAC,GAA2B,EAAE,QAAyB,EAAE,eAAuB,EAAE,KAAa,EAAE,IAA6B;IAC3J,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,KAAK,MAAM,CAAC,IAAI,GAAG,EAAE,CAAC;QACpB,IAAI,CAAC;YACH,MAAM,sBAAsB,CAAC,CAAC,CAAC,EAAE,EAAE,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC,CAAC;YAC9E,QAAQ,EAAE,CAAC;QACb,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,GAAG,CAAC,IAAI,CAAC,wCAAwC,KAAK,gBAAgB,CAAC,CAAC,EAAE,MAAO,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QAC5G,CAAC;IACH,CAAC;IACD,MAAM,sBAAsB,CAAC,QAAQ,EAAE,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACrG,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,QAAyB,EAAE,OAAuE,EAAE;IAC/I,MAAM,OAAO,GAAG,MAAM,qBAAqB,CAAC,QAAQ,EAAE,cAAc,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,CAAC;IACrF,KAAK,MAAM,OAAO,IAAI,OAAO,CAAC,QAAQ;QAAE,GAAG,CAAC,IAAI,CAAC,iBAAiB,OAAO,EAAE,CAAC,CAAC;IAC7E,IAAI,OAAO,CAAC,OAAO,GAAG,CAAC;QAAE,GAAG,CAAC,IAAI,CAAC,yBAAyB,OAAO,CAAC,OAAO,+CAA+C,CAAC,CAAC;IAC3H,OAAO,OAAO,CAAC,OAAO,CAAC;AACzB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,kCAAkC,GAAwB,IAAI,GAAG,CAAC;IAC7E,0BAA0B;IAC1B,2BAA2B;IAC3B,2BAA2B;IAC3B,cAAc;CACf,CAAC,CAAC;AAEH;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,gCAAgC,CACpD,OAAe,EACf,eAAuB;IAEvB,MAAM,MAAM,GAAG,MAAM,OAAO,CAAiC,iBAAiB,EAAE;QAC9E,MAAM,EAAE,EAAE,QAAQ,EAAE,CAAC,SAAS,EAAE,WAAW,CAAC,EAAE,OAAO,EAAE;QACvD,KAAK,EAAE,GAAG;KACX,CAAC,CAAC;IACH,MAAM,IAAI,GAAG,CAAC,MAAM,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE;QACnD,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,wBAAwB,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC;YAAE,OAAO,KAAK,CAAC;QACtE,MAAM,IAAI,GAAI,CAAC,CAAC,QAA2C,IAAI,IAAI,CAAC;QACpE,MAAM,OAAO,GAAG,CAAC,CAAC,OAAO,KAAK,OAAO,IAAI,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC;QACnE,IAAI,CAAC,OAAO;YAAE,OAAO,KAAK,CAAC;QAC3B,MAAM,IAAI,GAAG,CAAC,CAAC,cAAc,IAAK,IAAI,EAAE,IAA2B,IAAI,EAAE,CAAC;QAC1E,OAAO,kCAAkC,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,EAAE,eAAe,KAAK,iBAAiB,CAAC;IACrG,CAAC,CAAC,CAAC;IACH,MAAM,QAAQ,GAAoB,EAAE,KAAK,EAAE,CAAC,GAAG,kCAAkC,CAAC,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,EAAE,eAAe,EAAE,YAAY,EAAE,CAAC;IACxI,MAAM,QAAQ,GAAG,MAAM,gBAAgB,CAAC,IAAI,EAAE,QAAQ,EAAE,eAAe,EAAE,wCAAwC,OAAO,EAAE,EAAE,MAAM,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC;IACtJ,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;QACjB,GAAG,CAAC,IAAI,CAAC,4BAA4B,QAAQ,mDAAmD,OAAO,GAAG,CAAC,CAAC;IAC9G,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,KAAK,UAAU,mCAAmC,CACvD,OAAe,EACf,KAAwB,EACxB,eAA0C,EAC1C,eAAe,GAAG,oEAAoE;IAEtF,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;IAC/B,MAAM,MAAM,GAAG,MAAM,OAAO,CAAiC,iBAAiB,EAAE;QAC9E,MAAM,EAAE,EAAE,QAAQ,EAAE,CAAC,SAAS,EAAE,WAAW,CAAC,EAAE,OAAO,EAAE;QACvD,KAAK,EAAE,GAAG;KACX,CAAC,CAAC;IACH,MAAM,IAAI,GAAG,CAAC,MAAM,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,wBAAwB,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;IACrG,OAAO,gBAAgB,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,EAAE,eAAe,EAAE,EAAE,eAAe,EAAE,uCAAuC,OAAO,EAAE,EAAE,MAAM,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC;AAC7K,CAAC"}

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

@@ -0,0 +1,114 @@
+import { type EscalationAnchor, type ResolvedProvenance } from '../queries/escalations/escalation-provenance.js';
+import type { HumanAct } from '../queries/escalations/filing-observation.js';
+import { type FilingRefusal, type SendEscalationCreateDeps } from './escalation-refusal.js';
+/**
+ * Parameters for creating an escalation request.
+ */
+export interface CreateEscalationParams {
+    organizationId: string;
+    /** Session context (informational only -- not forwarded to the edge fn). Optional for daemon-side non-team callers. */
+    sessionId?: string;
+    issueId: string | null;
+    reasonType: string;
+    description: string;
+    whatWasTried?: string;
+    helpNeeded?: string;
+    /**
+     * Optional discriminator for the kind of escalation (e.g. 'stuck_focus_branch').
+     * Persisted on `agent_escalations.escalation_kind` when present.
+     */
+    escalationKind?: string;
+    /**
+     * Optional structured metadata (e.g. { branch_name, focus_id }).
+     * Persisted on `agent_escalations.metadata` when present.
+     */
+    metadata?: Record<string, unknown>;
+    /**
+     * Optional first-class provenance: where this escalation came from.
+     * Persisted on the agent_escalations product_id/focus_id/delivery_id
+     * columns. Prefer deriving these via resolveProvenance(anchor) so no
+     * site files an anonymous escalation when an anchor is available.
+     */
+    productId?: string;
+    focusId?: string;
+    deliveryId?: string;
+    /**
+     * Optional disposition: the resolution routing axis (who/what can resolve
+     * this). Distinct from escalationKind (the diagnosis). One of
+     * EscalationDisposition. Persisted on agent_escalations.disposition.
+     */
+    disposition?: string;
+    /**
+     * Optional cross-product TARGET provenance: the product this escalation is a
+     * blocker AGAINST (distinct from productId, which is the SOURCE product the
+     * escalation came from). Forwarded to the edge as fields.targetProductId. The
+     * edge escalation_create handler may or may not persist this on the
+     * agent_escalations.target_product_id column yet -- the escalation -> Nexus
+     * bridge does not depend on that, since the audit row also carries the target
+     * in metadata.target_product_id.
+     */
+    targetProductId?: string;
+    /**
+     * Optional provenance anchor: whatever the creation site holds (a delivery,
+     * focus, issue, session id, or branch). When present, the shared path runs
+     * resolveProvenance(anchor) and stamps the derived product/focus/delivery
+     * columns -- so no site files an anonymous escalation when an anchor is
+     * available. Explicitly-passed productId/focusId/deliveryId on params WIN
+     * over the derived values (caller intent beats derivation).
+     */
+    anchor?: EscalationAnchor;
+    /**
+     * The act the detector PROPOSES only a human can perform (irreversible / outward /
+     * unreachable capability), or NO_HUMAN_ACT. Never a route: it travels as
+     * metadata.observation.proposed_human_act on the machine-lane observation
+     * (supervision/filing-route.ts routeFilingDisposition).
+     */
+    humanAct?: HumanAct | null;
+}
+/**
+ * The filer's collaborators, all required: resolveProvenance (derives the anchor's
+ * product/focus/delivery columns), the ISO-8601 clock stamping the symptom's
+ * observed_at (and a refusal's refused_at), and the refusal memory. The row write
+ * and the correlation reads go through the one installed product-api transport
+ * (queries/api-client/shared.ts callApi). createEscalation binds the production
+ * set; a test calls createEscalationWith with its own complete set.
+ */
+export interface CreateEscalationDeps extends SendEscalationCreateDeps {
+    resolveProvenance: (anchor: EscalationAnchor) => Promise<ResolvedProvenance>;
+}
+/** Outcome of a filing through the chokepoint. */
+export interface CreateEscalationResult {
+    /** The row filed; null when correlated onto an existing row (or the create returned no id). */
+    escalationId: string | null;
+    /** Whether the filing was attached to (or already carried by) its incident's open lane row instead of filed. */
+    correlated?: boolean;
+    /** The lane row it correlated onto, or whose attach failed before this row was filed; else null. */
+    incidentEscalationId?: string | null;
+    /** Set when the server refused the filing non-transiently (supervision/escalation-refusal.ts); escalationId is then its refusal record's. */
+    refusal?: FilingRefusal;
+}
+/**
+ * Create an escalation request -- the single filing chokepoint. Provenance is
+ * derived from `anchor` via resolveProvenance (explicit productId/focusId/deliveryId
+ * win; a derivation miss degrades, never aborts). The disposition is routed by
+ * routeFilingDisposition: a daemon filing enters the machine lane WHATEVER
+ * disposition it names -- needs_operator / external_wait / needs_intent /
+ * needs_clarification are sent agent_resolvable as an observation carrying the
+ * proposed disposition and any proposed human act. The daemon files no
+ * human-facing row; only an agent that has assembled the intent ladder makes a
+ * filing human-facing (MCP escalate). A stop or hold the detector reported stays
+ * in force on its observation (supervision/holds.ts isMachineStopObservation and
+ * findOpenOperatorHoldForDelivery). The RESOLVED provenance (plus a branch the site carries) yields metadata.incident_key
+ * (a key already in metadata wins; inbound-notification kinds carry none), and the
+ * ONE incident reducer (supervision/incident-correlation.ts correlateFiling) either
+ * attaches the filing to its incident's open row in the same lane -- no row filed
+ * -- or the row is filed stamped with the key and its own symptom.
+ */
+export declare function createEscalationWith(params: CreateEscalationParams, deps: CreateEscalationDeps): Promise<CreateEscalationResult>;
+/**
+ * The production filer -- what the composition root binds and every daemon filing
+ * site calls: createEscalationWith over the product-api provenance reader, the wall
+ * clock and the process-wide refusal memory.
+ */
+export declare function createEscalation(params: CreateEscalationParams): Promise<CreateEscalationResult>;
+//# sourceMappingURL=escalation-filing.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"escalation-filing.d.ts","sourceRoot":"","sources":["../../src/supervision/escalation-filing.ts"],"names":[],"mappings":"AAyBA,OAAO,EAAqB,KAAK,gBAAgB,EAAE,KAAK,kBAAkB,EAAE,MAAM,iDAAiD,CAAC;AAEpI,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,8CAA8C,CAAC;AAG7E,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,wBAAwB,EAC9B,MAAM,yBAAyB,CAAC;AAUjC;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,cAAc,EAAE,MAAM,CAAC;IACvB,uHAAuH;IACvH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;CAC5B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,oBAAqB,SAAQ,wBAAwB;IACpE,iBAAiB,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;CAC9E;AAED,kDAAkD;AAClD,MAAM,WAAW,sBAAsB;IACrC,+FAA+F;IAC/F,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,gHAAgH;IAChH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,oGAAoG;IACpG,oBAAoB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,6IAA6I;IAC7I,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,sBAAsB,EAC9B,IAAI,EAAE,oBAAoB,GACzB,OAAO,CAAC,sBAAsB,CAAC,CAyCjC;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,sBAAsB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAMhG"}