@telora/daemon 0.21.83 → 0.21.134

package/dist/focus/tick-deadline.js

@@ -0,0 +1,91 @@
+/**
+ * Poll-tick deadline watchdog (TEL-3).
+ *
+ * The focus poll tick runs under daemon-core's safeInterval, which has NO
+ * deadline: it wraps the callback in try/catch and (with skipIfRunning) drops
+ * overlapping ticks, but a tick that stops making progress -- hung on a slow
+ * DB call, a wedged await -- simply never returns, silently. recordActivity()
+ * (the heartbeat) is emitted INSIDE the tick, so a stalled tick also stops the
+ * heartbeat: from outside the process a stalled daemon looks exactly like an
+ * idle one. Nothing surfaces the difference.
+ *
+ * This module arms a deadline timer around the tick body. If the body has not
+ * settled by `deadlineMs`, it emits a warning-level health event (code
+ * `poll.stalled`) naming the tick and its elapsed time -- the external signal
+ * that distinguishes stalled from idle. When the body finally settles, a paired
+ * recovery is surfaced (resolveByCode) and the elapsed overrun logged. The tick
+ * itself cannot be force-aborted in JS (there is no cooperative cancellation on
+ * an arbitrary await); safeInterval's skipIfRunning already prevents a pile-up
+ * of overlapping ticks while the hung one drains, so surfacing IS the
+ * reclamation the daemon can offer: the stall becomes observable and the next
+ * clean tick resumes once the hung body returns.
+ *
+ * The emit/log effects are injected (deps) and the stall decision is a pure
+ * function so the whole thing is unit-testable with no real timers.
+ */
+import { healthEvents } from '@telora/daemon-core';
+import { createLogger } from '../shell/log.js';
+const log = createLogger({ module: 'tick-deadline' });
+/** Default: a poll tick still running this long past its start is "stalled". */
+export const DEFAULT_TICK_DEADLINE_MS = 90_000;
+/**
+ * Pure stall decision: has a tick that started at `startMs` and is observed at
+ * `nowMs` exceeded `deadlineMs`? Extracted so the deadline arithmetic is tested
+ * without any timer. Returns the elapsed time so callers can log/emit it.
+ */
+export function evaluateTickStall(startMs, nowMs, deadlineMs) {
+    const elapsedMs = nowMs - startMs;
+    return { stalled: elapsedMs >= deadlineMs, elapsedMs };
+}
+function defaultArm(fn, ms) {
+    const t = setTimeout(fn, ms);
+    // Never keep the process alive just for the watchdog.
+    t.unref?.();
+    return () => clearTimeout(t);
+}
+function defaultOnStall(label, deadlineMs) {
+    log.warn(`[${label}] Poll tick has not completed within ${deadlineMs}ms -- it is STALLED, ` +
+        'not idle. The heartbeat is emitted inside the tick, so the daemon may look ' +
+        'dead from outside; investigate the wedged await (slow DB call / blocked I/O).');
+    healthEvents.emit({
+        severity: 'warn',
+        source: `poll:${label}`,
+        code: 'poll.stalled',
+        message: `Poll tick '${label}' exceeded its ${deadlineMs}ms deadline and is still ` +
+            'running. A stalled tick is distinct from an idle one: no work is advancing ' +
+            'and the heartbeat has stopped for this cycle.',
+    });
+}
+function defaultOnRecover(label, elapsedMs) {
+    log.warn(`[${label}] Poll tick recovered after ${elapsedMs}ms (was flagged stalled).`);
+    healthEvents.resolveByCode('poll.stalled');
+}
+/**
+ * Run `body` under the deadline watchdog. Resolves/rejects exactly as `body`
+ * does; the watchdog only observes. If the body overruns `deadlineMs`, the
+ * stall is surfaced once; when it settles after a flagged stall, recovery is
+ * surfaced. The watchdog timer is always cleared in `finally`, so a fast tick
+ * emits nothing.
+ */
+export async function runWithTickDeadline(label, deadlineMs, body, deps) {
+    const now = deps?.now ?? Date.now;
+    const arm = deps?.arm ?? defaultArm;
+    const onStall = deps?.onStall ?? defaultOnStall;
+    const onRecover = deps?.onRecover ?? defaultOnRecover;
+    const startMs = now();
+    let stalled = false;
+    const cancel = arm(() => {
+        stalled = true;
+        onStall(label, deadlineMs);
+    }, deadlineMs);
+    try {
+        await body();
+    }
+    finally {
+        cancel();
+        if (stalled) {
+            onRecover(label, now() - startMs);
+        }
+    }
+}
+//# sourceMappingURL=tick-deadline.js.map

package/dist/focus/tick-deadline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tick-deadline.js","sourceRoot":"","sources":["../../src/focus/tick-deadline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE/C,MAAM,GAAG,GAAG,YAAY,CAAC,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC,CAAC;AAEtD,gFAAgF;AAChF,MAAM,CAAC,MAAM,wBAAwB,GAAG,MAAM,CAAC;AAE/C;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAAe,EACf,KAAa,EACb,UAAkB;IAElB,MAAM,SAAS,GAAG,KAAK,GAAG,OAAO,CAAC;IAClC,OAAO,EAAE,OAAO,EAAE,SAAS,IAAI,UAAU,EAAE,SAAS,EAAE,CAAC;AACzD,CAAC;AAaD,SAAS,UAAU,CAAC,EAAc,EAAE,EAAU;IAC5C,MAAM,CAAC,GAAG,UAAU,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;IAC7B,sDAAsD;IACrD,CAA4B,CAAC,KAAK,EAAE,EAAE,CAAC;IACxC,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;AAC/B,CAAC;AAED,SAAS,cAAc,CAAC,KAAa,EAAE,UAAkB;IACvD,GAAG,CAAC,IAAI,CACN,IAAI,KAAK,wCAAwC,UAAU,uBAAuB;QAChF,6EAA6E;QAC7E,+EAA+E,CAClF,CAAC;IACF,YAAY,CAAC,IAAI,CAAC;QAChB,QAAQ,EAAE,MAAM;QAChB,MAAM,EAAE,QAAQ,KAAK,EAAE;QACvB,IAAI,EAAE,cAAc;QACpB,OAAO,EACL,cAAc,KAAK,kBAAkB,UAAU,2BAA2B;YAC1E,6EAA6E;YAC7E,+CAA+C;KAClD,CAAC,CAAC;AACL,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAa,EAAE,SAAiB;IACxD,GAAG,CAAC,IAAI,CAAC,IAAI,KAAK,+BAA+B,SAAS,2BAA2B,CAAC,CAAC;IACvF,YAAY,CAAC,aAAa,CAAC,cAAc,CAAC,CAAC;AAC7C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,KAAa,EACb,UAAkB,EAClB,IAAyB,EACzB,IAAuB;IAEvB,MAAM,GAAG,GAAG,IAAI,EAAE,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC;IAClC,MAAM,GAAG,GAAG,IAAI,EAAE,GAAG,IAAI,UAAU,CAAC;IACpC,MAAM,OAAO,GAAG,IAAI,EAAE,OAAO,IAAI,cAAc,CAAC;IAChD,MAAM,SAAS,GAAG,IAAI,EAAE,SAAS,IAAI,gBAAgB,CAAC;IAEtD,MAAM,OAAO,GAAG,GAAG,EAAE,CAAC;IACtB,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,MAAM,MAAM,GAAG,GAAG,CAAC,GAAG,EAAE;QACtB,OAAO,GAAG,IAAI,CAAC;QACf,OAAO,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;IAC7B,CAAC,EAAE,UAAU,CAAC,CAAC;IAEf,IAAI,CAAC;QACH,MAAM,IAAI,EAAE,CAAC;IACf,CAAC;YAAS,CAAC;QACT,MAAM,EAAE,CAAC;QACT,IAAI,OAAO,EAAE,CAAC;YACZ,SAAS,CAAC,KAAK,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,CAAC;QACpC,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/focus-stage-lifecycle/index.d.ts

@@ -1,36 +1,33 @@
 /**
  * Focus workflow lifecycle stage transitions (D2).
  *
- * The "Focus Workflow Lifecycle and Tree Closure" focus introduces a new
- * authoritative lifecycle on `product_focuses.stage`:
- *
- *   planning -> queued -> in_progress -> verify -> review -> close_loop -> done
- *
- * The daemon advances `stage` along this axis based on deterministic checks:
- *
- *   verify  -> review     unless pipeline_config.review.enabled is explicitly
- *                         false (default-on; Issue 4: auto-enter review on
- *                         verify-stage entry)
- *
- *   review  -> close_loop when there are no in-flight remediation deliveries
- *                         (Issue 2: state-based convergence) AND we have not
- *                         exceeded the N-iteration cap.
- *
- *   review  -> (escalate) when iteration count exceeds the cap
- *                         (Issue 3: review_nonconvergent escalation, focus
- *                         stays at review until a human intervenes).
+ * Historically the daemon advanced a `product_focuses.stage` column along
+ * `planning -> queued -> in_progress -> verify -> review -> close_loop -> done`.
+ * That machine-driven stage axis is being retired in favour of a single derived
+ * lifecycle (`deriveFocusPhase`): review ENTRY is owned by
+ * state-cascade.checkAutoReview (`review_requested_at`), and both the machine
+ * verify->review advance (TEL-6) and the review->close_loop advance (TEL-4) have
+ * been removed. Review completion is derived (`winding_down`), never a
+ * stage='close_loop' write; a non-convergent review is bounded by the
+ * review-cycle churn meter + review_window_stalled detector, not a permanent
+ * stage hold awaiting a human.
  *
  * This module owns the poll-loop dispatcher `runStageLifecycleTransitions` and
- * re-exports the decomposed transition logic, which lives in three cohesive
+ * re-exports the decomposed transition logic, which lives in two cohesive
  * submodules:
  *
- *   - `focus-stage-lifecycle/review-convergence` -- the verify->review and
- *     review->close_loop transitions plus their pure convergence helpers.
  *   - `focus-stage-lifecycle/planning-release`  -- the ratify-to-execute and
  *     writable-focus planning->queued delivery releases.
  *   - `focus-stage-lifecycle/wedge-watchdog`    -- the planning-wedge watchdog +
  *     zero-actionable log.
  *
+ * The former `review-convergence` submodule (the machine-driven
+ * verify->review and review->close_loop stage advances) was removed: review
+ * ENTRY is owned by state-cascade.checkAutoReview (review_requested_at), and
+ * review COMPLETION is derived (`winding_down`) rather than written as
+ * stage='close_loop'. A non-convergent review is bounded by the review-cycle
+ * churn meter + review_window_stalled detector, not a permanent stage hold.
+ *
  * It does not advance `current_workflow_stage_id` directly -- the existing
  * `syncFocusPhase` does that on the next poll, after the daemon's `stage` write
  * lands.
@@ -40,10 +37,8 @@
 import type { DaemonConfig, FocusDeliveryInfo } from '../types/index.js';
 import { getActiveFocuses as defaultGetActiveFocuses } from '../queries/deliveries.js';
 import { getFocusDeliveries as defaultGetFocusDeliveries } from '../queries/focuses.js';
-import { advanceVerifyToReviewIfEnabled, advanceReviewToCloseLoopIfConverged, type ReviewTransitionOutcome } from './review-convergence.js';
 import { releaseRatifiedReadOnlyFocus, releaseWritableFocusPlanningDeliveries } from './planning-release.js';
 import { evaluateFocusWedge, type WedgeOutcome } from './wedge-watchdog.js';
-export * from './review-convergence.js';
 export * from './planning-release.js';
 export * from './wedge-watchdog.js';
 /**
@@ -53,8 +48,6 @@ export * from './wedge-watchdog.js';
 export declare function runStageLifecycleTransitions(config: DaemonConfig, deps?: {
     getActiveFocuses: typeof defaultGetActiveFocuses;
     getFocusDeliveries: typeof defaultGetFocusDeliveries;
-    advanceVerifyToReview: (focus: Parameters<typeof advanceVerifyToReviewIfEnabled>[0]) => Promise<boolean>;
-    advanceReviewToCloseLoop: (focus: Parameters<typeof advanceReviewToCloseLoopIfConverged>[0]) => Promise<ReviewTransitionOutcome>;
     releaseRatifiedReadOnly: (focus: Parameters<typeof releaseRatifiedReadOnlyFocus>[0]) => Promise<number>;
     releaseWritablePlanning: (focus: Parameters<typeof releaseWritableFocusPlanningDeliveries>[0]) => Promise<number>;
     evaluateWedge: (focus: Parameters<typeof evaluateFocusWedge>[0]) => Promise<WedgeOutcome>;

package/dist/focus-stage-lifecycle/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/focus-stage-lifecycle/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEzE,OAAO,EAAE,gBAAgB,IAAI,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AACvF,OAAO,EAAE,kBAAkB,IAAI,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AAExF,OAAO,EACL,8BAA8B,EAC9B,mCAAmC,EACnC,KAAK,uBAAuB,EAC7B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,4BAA4B,EAC5B,sCAAsC,EACvC,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,kBAAkB,EAElB,KAAK,YAAY,EAClB,MAAM,qBAAqB,CAAC;AAQ7B,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AAIpC;;;GAGG;AACH,wBAAsB,4BAA4B,CAChD,MAAM,EAAE,YAAY,EACpB,IAAI,GAAE;IACJ,gBAAgB,EAAE,OAAO,uBAAuB,CAAC;IACjD,kBAAkB,EAAE,OAAO,yBAAyB,CAAC;IACrD,qBAAqB,EAAE,CACrB,KAAK,EAAE,UAAU,CAAC,OAAO,8BAA8B,CAAC,CAAC,CAAC,CAAC,KACxD,OAAO,CAAC,OAAO,CAAC,CAAC;IACtB,wBAAwB,EAAE,CACxB,KAAK,EAAE,UAAU,CAAC,OAAO,mCAAmC,CAAC,CAAC,CAAC,CAAC,KAC7D,OAAO,CAAC,uBAAuB,CAAC,CAAC;IACtC,uBAAuB,EAAE,CACvB,KAAK,EAAE,UAAU,CAAC,OAAO,4BAA4B,CAAC,CAAC,CAAC,CAAC,KACtD,OAAO,CAAC,MAAM,CAAC,CAAC;IACrB,uBAAuB,EAAE,CACvB,KAAK,EAAE,UAAU,CAAC,OAAO,sCAAsC,CAAC,CAAC,CAAC,CAAC,KAChE,OAAO,CAAC,MAAM,CAAC,CAAC;IACrB,aAAa,EAAE,CACb,KAAK,EAAE,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC,CAAC,CAAC,KAC5C,OAAO,CAAC,YAAY,CAAC,CAAC;CAS5B,GACA,OAAO,CAAC,IAAI,CAAC,CA2Hf;AAGD,YAAY,EAAE,iBAAiB,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/focus-stage-lifecycle/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEzE,OAAO,EAAE,gBAAgB,IAAI,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AACvF,OAAO,EAAE,kBAAkB,IAAI,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AACxF,OAAO,EACL,4BAA4B,EAC5B,sCAAsC,EACvC,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,kBAAkB,EAElB,KAAK,YAAY,EAClB,MAAM,qBAAqB,CAAC;AAQ7B,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AAIpC;;;GAGG;AACH,wBAAsB,4BAA4B,CAChD,MAAM,EAAE,YAAY,EACpB,IAAI,GAAE;IACJ,gBAAgB,EAAE,OAAO,uBAAuB,CAAC;IACjD,kBAAkB,EAAE,OAAO,yBAAyB,CAAC;IACrD,uBAAuB,EAAE,CACvB,KAAK,EAAE,UAAU,CAAC,OAAO,4BAA4B,CAAC,CAAC,CAAC,CAAC,KACtD,OAAO,CAAC,MAAM,CAAC,CAAC;IACrB,uBAAuB,EAAE,CACvB,KAAK,EAAE,UAAU,CAAC,OAAO,sCAAsC,CAAC,CAAC,CAAC,CAAC,KAChE,OAAO,CAAC,MAAM,CAAC,CAAC;IACrB,aAAa,EAAE,CACb,KAAK,EAAE,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC,CAAC,CAAC,KAC5C,OAAO,CAAC,YAAY,CAAC,CAAC;CAO5B,GACA,OAAO,CAAC,IAAI,CAAC,CAuHf;AAGD,YAAY,EAAE,iBAAiB,EAAE,CAAC"}

package/dist/focus-stage-lifecycle/index.js

@@ -1,36 +1,33 @@
 /**
  * Focus workflow lifecycle stage transitions (D2).
  *
- * The "Focus Workflow Lifecycle and Tree Closure" focus introduces a new
- * authoritative lifecycle on `product_focuses.stage`:
- *
- *   planning -> queued -> in_progress -> verify -> review -> close_loop -> done
- *
- * The daemon advances `stage` along this axis based on deterministic checks:
- *
- *   verify  -> review     unless pipeline_config.review.enabled is explicitly
- *                         false (default-on; Issue 4: auto-enter review on
- *                         verify-stage entry)
- *
- *   review  -> close_loop when there are no in-flight remediation deliveries
- *                         (Issue 2: state-based convergence) AND we have not
- *                         exceeded the N-iteration cap.
- *
- *   review  -> (escalate) when iteration count exceeds the cap
- *                         (Issue 3: review_nonconvergent escalation, focus
- *                         stays at review until a human intervenes).
+ * Historically the daemon advanced a `product_focuses.stage` column along
+ * `planning -> queued -> in_progress -> verify -> review -> close_loop -> done`.
+ * That machine-driven stage axis is being retired in favour of a single derived
+ * lifecycle (`deriveFocusPhase`): review ENTRY is owned by
+ * state-cascade.checkAutoReview (`review_requested_at`), and both the machine
+ * verify->review advance (TEL-6) and the review->close_loop advance (TEL-4) have
+ * been removed. Review completion is derived (`winding_down`), never a
+ * stage='close_loop' write; a non-convergent review is bounded by the
+ * review-cycle churn meter + review_window_stalled detector, not a permanent
+ * stage hold awaiting a human.
  *
  * This module owns the poll-loop dispatcher `runStageLifecycleTransitions` and
- * re-exports the decomposed transition logic, which lives in three cohesive
+ * re-exports the decomposed transition logic, which lives in two cohesive
  * submodules:
  *
- *   - `focus-stage-lifecycle/review-convergence` -- the verify->review and
- *     review->close_loop transitions plus their pure convergence helpers.
  *   - `focus-stage-lifecycle/planning-release`  -- the ratify-to-execute and
  *     writable-focus planning->queued delivery releases.
  *   - `focus-stage-lifecycle/wedge-watchdog`    -- the planning-wedge watchdog +
  *     zero-actionable log.
  *
+ * The former `review-convergence` submodule (the machine-driven
+ * verify->review and review->close_loop stage advances) was removed: review
+ * ENTRY is owned by state-cascade.checkAutoReview (review_requested_at), and
+ * review COMPLETION is derived (`winding_down`) rather than written as
+ * stage='close_loop'. A non-convergent review is bounded by the review-cycle
+ * churn meter + review_window_stalled detector, not a permanent stage hold.
+ *
  * It does not advance `current_workflow_stage_id` directly -- the existing
  * `syncFocusPhase` does that on the next poll, after the daemon's `stage` write
  * lands.
@@ -40,15 +37,12 @@
 import { configForProduct } from '../shell/config.js';
 import { getActiveFocuses as defaultGetActiveFocuses } from '../queries/deliveries.js';
 import { getFocusDeliveries as defaultGetFocusDeliveries } from '../queries/focuses.js';
-import { FOCUS_STAGE } from '@telora/daemon-core';
-import { advanceVerifyToReviewIfEnabled, advanceReviewToCloseLoopIfConverged, } from './review-convergence.js';
 import { releaseRatifiedReadOnlyFocus, releaseWritableFocusPlanningDeliveries, } from './planning-release.js';
 import { evaluateFocusWedge, pruneWedgeWatchdogState, } from './wedge-watchdog.js';
 import { createLogger } from '../shell/log.js';
 const log = createLogger({ module: 'focus-stage-lifecycle' });
 // Re-export the decomposed surface so every importer + test keeps resolving
 // these names from './index.js' unchanged.
-export * from './review-convergence.js';
 export * from './planning-release.js';
 export * from './wedge-watchdog.js';
 // ── Poll-loop entry point ─────────────────────────────────────────
@@ -59,8 +53,6 @@ export * from './wedge-watchdog.js';
 export async function runStageLifecycleTransitions(config, deps = {
     getActiveFocuses: defaultGetActiveFocuses,
     getFocusDeliveries: defaultGetFocusDeliveries,
-    advanceVerifyToReview: (f) => advanceVerifyToReviewIfEnabled(f),
-    advanceReviewToCloseLoop: (f) => advanceReviewToCloseLoopIfConverged(f),
     releaseRatifiedReadOnly: (f) => releaseRatifiedReadOnlyFocus(f),
     releaseWritablePlanning: (f) => releaseWritableFocusPlanningDeliveries(f),
     evaluateWedge: (f) => evaluateFocusWedge(f),
@@ -158,18 +150,14 @@ export async function runStageLifecycleTransitions(config, deps = {
                 log.warn(`[focus-stage-lifecycle] Wedge watchdog tick failed for ` +
                     `"${focus.focus_name}": ${err.message}`);
             }
-            try {
-                if (baseArgs.stage === FOCUS_STAGE.VERIFY) {
-                    await deps.advanceVerifyToReview(baseArgs);
-                }
-                else if (baseArgs.stage === FOCUS_STAGE.REVIEW) {
-                    await deps.advanceReviewToCloseLoop(baseArgs);
-                }
-            }
-            catch (err) {
-                log.warn(`[focus-stage-lifecycle] Tick failed for "${focus.focus_name}": ` +
-                    `${err.message}`);
-            }
+            // Review ENTRY is owned solely by state-cascade.checkAutoReview (which
+            // writes review_requested_at, the axis the derived 'reviewing' phase and
+            // the review team actually key on). The former verify->review auto-advance
+            // (advanceVerifyToReviewIfEnabled, TEL-6) and review->close_loop machine
+            // advance (advanceReviewToCloseLoopIfConverged, TEL-4) are both removed:
+            // review completion is derived (`winding_down`), never a stage='close_loop'
+            // write, and a non-convergent review is bounded by the review-cycle churn
+            // meter + review_window_stalled detector rather than a permanent hold.
         }
     }
     // Evict wedge watchdog state for focuses no longer active anywhere, so the

package/dist/focus-stage-lifecycle/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/focus-stage-lifecycle/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/focus-stage-lifecycle/index.ts"],"names":[],"mappings":"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"}

package/dist/focus-stage-lifecycle/wedge-cause-arbiter.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The single wedge-cause ARBITER (TEL-3 of "One decision path, one wedge
+ * arbiter").
+ *
+ * A wedged focus can trip up to ~ten independent cap detectors, each of which
+ * files its own escalation kind (its "evidence"): team_failure, daemon_gate_stuck,
+ * wedged_focus, review_window_stalled, verify_gate_unclearable,
+ * respawn_cycle_exhausted, stuck_focus_branch, review_coverage_incomplete,
+ * review_cycle_cap_exceeded, review_handoff_exhausted. Before this, the cause a
+ * wedge REPORTED was whichever detector's bound crossed FIRST -- so the same
+ * underlying wedge got a different label depending on poll timing.
+ *
+ * This arbiter removes the timing dependence: given the SET of causes whose
+ * detectors have fired for a focus (their open escalations), it returns ONE
+ * authoritative cause by a STATED PRECEDENCE, independent of the order the bounds
+ * crossed. The precedence puts the ROOT blocker above the SYMPTOM: a specific
+ * blocker (an unclearable verify gate, a stuck branch, a review that cannot
+ * converge) outranks the generic "the team keeps failing" / "respawns halted"
+ * symptoms those blockers ultimately produce. So an operator (or a downstream
+ * reader) is pointed at the cause to fix, not the loudest or earliest alarm.
+ */
+/**
+ * Wedge causes highest-precedence (ROOT) first. A cause earlier in this list
+ * outranks every cause after it when both are present. Every wedge/stall
+ * escalation kind the daemon files appears exactly once; a kind not listed here
+ * is not a wedge cause and is ignored by the arbiter.
+ */
+export declare const WEDGE_CAUSE_PRECEDENCE: readonly string[];
+/** True when `kind` is a wedge cause the arbiter ranks. */
+export declare function isWedgeCause(kind: string): boolean;
+/**
+ * Decide the ONE authoritative wedge cause from the set of causes whose
+ * detectors have fired. Deterministic and order-independent: the result depends
+ * only on WHICH causes are present, never on the order they were observed or
+ * passed in. Non-wedge kinds are ignored. Returns null when no wedge cause is
+ * present (an empty or all-non-wedge input).
+ */
+export declare function arbitrateWedgeCause(crossedKinds: Iterable<string>): string | null;
+/** IO seam for getFocusWedgeCause (default reaches the real query; tests stub it). */
+export interface WedgeCauseReaderDeps {
+    listOpenFocusEscalationKinds: (focusId: string) => Promise<string[]>;
+}
+/**
+ * Report the ONE authoritative wedge cause for a focus, arbitrated from the
+ * evidence its detectors have filed (its open escalations). Deterministic: the
+ * result depends only on WHICH detectors have fired, never on the order they
+ * crossed. Returns null when the focus has no open wedge-cause escalation.
+ * Best-effort: on a read failure it returns null (the caller degrades to its own
+ * local cause) rather than throwing.
+ */
+export declare function getFocusWedgeCause(focusId: string, deps: WedgeCauseReaderDeps): Promise<string | null>;
+//# sourceMappingURL=wedge-cause-arbiter.d.ts.map

package/dist/focus-stage-lifecycle/wedge-cause-arbiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wedge-cause-arbiter.d.ts","sourceRoot":"","sources":["../../src/focus-stage-lifecycle/wedge-cause-arbiter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,MAAM,EAqBnD,CAAC;AAMF,2DAA2D;AAC3D,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAElD;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,MAAM,GAAG,IAAI,CAYjF;AAED,sFAAsF;AACtF,MAAM,WAAW,oBAAoB;IACnC,4BAA4B,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CACtE;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,oBAAoB,GACzB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAQxB"}

package/dist/focus-stage-lifecycle/wedge-cause-arbiter.js

@@ -0,0 +1,94 @@
+/**
+ * The single wedge-cause ARBITER (TEL-3 of "One decision path, one wedge
+ * arbiter").
+ *
+ * A wedged focus can trip up to ~ten independent cap detectors, each of which
+ * files its own escalation kind (its "evidence"): team_failure, daemon_gate_stuck,
+ * wedged_focus, review_window_stalled, verify_gate_unclearable,
+ * respawn_cycle_exhausted, stuck_focus_branch, review_coverage_incomplete,
+ * review_cycle_cap_exceeded, review_handoff_exhausted. Before this, the cause a
+ * wedge REPORTED was whichever detector's bound crossed FIRST -- so the same
+ * underlying wedge got a different label depending on poll timing.
+ *
+ * This arbiter removes the timing dependence: given the SET of causes whose
+ * detectors have fired for a focus (their open escalations), it returns ONE
+ * authoritative cause by a STATED PRECEDENCE, independent of the order the bounds
+ * crossed. The precedence puts the ROOT blocker above the SYMPTOM: a specific
+ * blocker (an unclearable verify gate, a stuck branch, a review that cannot
+ * converge) outranks the generic "the team keeps failing" / "respawns halted"
+ * symptoms those blockers ultimately produce. So an operator (or a downstream
+ * reader) is pointed at the cause to fix, not the loudest or earliest alarm.
+ */
+/**
+ * Wedge causes highest-precedence (ROOT) first. A cause earlier in this list
+ * outranks every cause after it when both are present. Every wedge/stall
+ * escalation kind the daemon files appears exactly once; a kind not listed here
+ * is not a wedge cause and is ignored by the arbiter.
+ */
+export const WEDGE_CAUSE_PRECEDENCE = [
+    // Infra / merge root: nothing in the focus can advance until the branch is
+    // un-stuck, so it outranks every downstream symptom.
+    'stuck_focus_branch',
+    // Delivery-level root: the verify gate cannot be cleared by re-work.
+    'verify_gate_unclearable',
+    // Review roots: the review itself cannot converge / cover / hand off.
+    'review_coverage_incomplete',
+    'review_cycle_cap_exceeded',
+    'review_handoff_exhausted',
+    // Review timing: the review window went stale.
+    'review_window_stalled',
+    // A generic guard is stuck (operator triages from gate_state).
+    'daemon_gate_stuck',
+    // A planning-stage rank-0 block wedges the ready selector.
+    'wedged_focus',
+    // Symptoms of a repeatedly-failing focus (lowest precedence): the machine
+    // halted respawns / the team keeps giving up. These are what the roots above
+    // ultimately CAUSE, so a root, when present, always wins over them.
+    'respawn_cycle_exhausted',
+    'team_failure',
+];
+const PRECEDENCE_RANK = new Map(WEDGE_CAUSE_PRECEDENCE.map((kind, i) => [kind, i]));
+/** True when `kind` is a wedge cause the arbiter ranks. */
+export function isWedgeCause(kind) {
+    return PRECEDENCE_RANK.has(kind);
+}
+/**
+ * Decide the ONE authoritative wedge cause from the set of causes whose
+ * detectors have fired. Deterministic and order-independent: the result depends
+ * only on WHICH causes are present, never on the order they were observed or
+ * passed in. Non-wedge kinds are ignored. Returns null when no wedge cause is
+ * present (an empty or all-non-wedge input).
+ */
+export function arbitrateWedgeCause(crossedKinds) {
+    let best = null;
+    let bestRank = Number.POSITIVE_INFINITY;
+    for (const kind of crossedKinds) {
+        const rank = PRECEDENCE_RANK.get(kind);
+        if (rank === undefined)
+            continue; // not a wedge cause
+        if (rank < bestRank) {
+            bestRank = rank;
+            best = kind;
+        }
+    }
+    return best;
+}
+/**
+ * Report the ONE authoritative wedge cause for a focus, arbitrated from the
+ * evidence its detectors have filed (its open escalations). Deterministic: the
+ * result depends only on WHICH detectors have fired, never on the order they
+ * crossed. Returns null when the focus has no open wedge-cause escalation.
+ * Best-effort: on a read failure it returns null (the caller degrades to its own
+ * local cause) rather than throwing.
+ */
+export async function getFocusWedgeCause(focusId, deps) {
+    let kinds;
+    try {
+        kinds = await deps.listOpenFocusEscalationKinds(focusId);
+    }
+    catch {
+        return null;
+    }
+    return arbitrateWedgeCause(kinds);
+}
+//# sourceMappingURL=wedge-cause-arbiter.js.map

package/dist/focus-stage-lifecycle/wedge-cause-arbiter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wedge-cause-arbiter.js","sourceRoot":"","sources":["../../src/focus-stage-lifecycle/wedge-cause-arbiter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAsB;IACvD,2EAA2E;IAC3E,qDAAqD;IACrD,oBAAoB;IACpB,qEAAqE;IACrE,yBAAyB;IACzB,sEAAsE;IACtE,4BAA4B;IAC5B,2BAA2B;IAC3B,0BAA0B;IAC1B,+CAA+C;IAC/C,uBAAuB;IACvB,+DAA+D;IAC/D,mBAAmB;IACnB,2DAA2D;IAC3D,cAAc;IACd,0EAA0E;IAC1E,6EAA6E;IAC7E,oEAAoE;IACpE,yBAAyB;IACzB,cAAc;CACf,CAAC;AAEF,MAAM,eAAe,GAAgC,IAAI,GAAG,CAC1D,sBAAsB,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CACnD,CAAC;AAEF,2DAA2D;AAC3D,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,OAAO,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACnC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,YAA8B;IAChE,IAAI,IAAI,GAAkB,IAAI,CAAC;IAC/B,IAAI,QAAQ,GAAG,MAAM,CAAC,iBAAiB,CAAC;IACxC,KAAK,MAAM,IAAI,IAAI,YAAY,EAAE,CAAC;QAChC,MAAM,IAAI,GAAG,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACvC,IAAI,IAAI,KAAK,SAAS;YAAE,SAAS,CAAC,oBAAoB;QACtD,IAAI,IAAI,GAAG,QAAQ,EAAE,CAAC;YACpB,QAAQ,GAAG,IAAI,CAAC;YAChB,IAAI,GAAG,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAOD;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,OAAe,EACf,IAA0B;IAE1B,IAAI,KAAe,CAAC;IACpB,IAAI,CAAC;QACH,KAAK,GAAG,MAAM,IAAI,CAAC,4BAA4B,CAAC,OAAO,CAAC,CAAC;IAC3D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,mBAAmB,CAAC,KAAK,CAAC,CAAC;AACpC,CAAC"}

package/dist/focus-stage-lifecycle/wedge-watchdog.d.ts

@@ -10,7 +10,7 @@
  * @module focus-stage-lifecycle/wedge-watchdog
  */
 import { getFocusDeliveries as defaultGetFocusDeliveries } from '../queries/focuses.js';
-import { createEscalation as defaultCreateEscalation, hasOpenWedgedFocusEscalation as defaultHasOpenWedgedFocusEscalation } from '../queries/issues.js';
+import { createEscalation as defaultCreateEscalation, hasOpenWedgedFocusEscalation as defaultHasOpenWedgedFocusEscalation, listOpenFocusEscalationKinds as defaultListOpenFocusEscalationKinds } from '../queries/issues.js';
 /** A delivery as seen by the actionability classifier (rank-ascending walk). */
 export interface WedgeBlockingDelivery {
     id: string;
@@ -23,6 +23,12 @@ export interface WedgeBlockingDelivery {
      * daemon restart cannot reset the wedge clock (review finding, delivery 66c7d4d8).
      */
     updatedAt: string | null;
+    /**
+     * True iff this held delivery carries a HUMAN/EXTERNAL provenance hold
+     * (gate_state.operatorHold / externalHold), which exempts it from the wedge
+     * escalation. A machine pause (guard block, no hold) is false -> a wedge.
+     */
+    humanHold: boolean;
 }
 /** Pure classification of a focus's deliveries against the ready-focus walk. */
 export interface FocusActionability {
@@ -54,6 +60,15 @@ export declare function classifyFocusActionability(deliveries: ReadonlyArray<{
     executionStatus: string | null;
     priorityRank: number;
     updatedAt?: string | null;
+    /**
+     * The delivery's gate_state. Its operatorHold / externalHold fields are the
+     * HUMAN/EXTERNAL provenance markers (an operator-blocked escalation, or an
+     * irreducibly-external dependency). A pause with neither is machine-produced
+     * (a guard block writes `blocking`, not a hold) -- and a machine pause that
+     * stays stuck IS a wedge, per TEL-2. Typed `unknown` (the query surfaces the
+     * gate_state JSONB untyped); narrowed in hasHumanProvenanceHold.
+     */
+    gateState?: unknown;
 }>): FocusActionability;
 /**
  * Evict watchdog state for any focus NOT in `liveFocusIds`. A focus that goes
@@ -73,6 +88,8 @@ export declare function __resetWedgeWatchdogState(): void;
 export interface WedgeWatchdogDeps {
     getFocusDeliveries: typeof defaultGetFocusDeliveries;
     hasOpenWedgedFocusEscalation: typeof defaultHasOpenWedgedFocusEscalation;
+    /** Evidence for the wedge-cause arbiter (TEL-3): every open escalation kind naming the focus. */
+    listOpenFocusEscalationKinds: typeof defaultListOpenFocusEscalationKinds;
     createEscalation: typeof defaultCreateEscalation;
     /** Kickoff-window discriminator: a running scoping team means "not a wedge". */
     hasActiveTeam: (focusId: string) => boolean;

package/dist/focus-stage-lifecycle/wedge-watchdog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wedge-watchdog.d.ts","sourceRoot":"","sources":["../../src/focus-stage-lifecycle/wedge-watchdog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,kBAAkB,IAAI,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AACxF,OAAO,EACL,gBAAgB,IAAI,uBAAuB,EAC3C,4BAA4B,IAAI,mCAAmC,EAEpE,MAAM,sBAAsB,CAAC;AA8D9B,gFAAgF;AAChF,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,gFAAgF;AAChF,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,iHAAiH;IACjH,kBAAkB,EAAE,OAAO,CAAC;IAC5B,sGAAsG;IACtG,gBAAgB,EAAE,qBAAqB,GAAG,IAAI,CAAC;IAC/C,yFAAyF;IACzF,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,0BAA0B,CACxC,UAAU,EAAE,aAAa,CAAC;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,CAAC,GACD,kBAAkB,CAwBpB;AAsED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,YAAY,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,IAAI,CAE/E;AAED,yDAAyD;AACzD,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD;AAeD;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,kBAAkB,EAAE,OAAO,yBAAyB,CAAC;IACrD,4BAA4B,EAAE,OAAO,mCAAmC,CAAC;IACzE,gBAAgB,EAAE,OAAO,uBAAuB,CAAC;IACjD,gFAAgF;IAChF,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IAC5C,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;CACrB;AAaD,uEAAuE;AACvE,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,qBAAqB,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,SAAS,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7F;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE;IACL,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,gFAAgF;IAChF,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB,EACD,IAAI,GAAE,iBAA8C,GACnD,OAAO,CAAC,YAAY,CAAC,CA+JvB"}
+{"version":3,"file":"wedge-watchdog.d.ts","sourceRoot":"","sources":["../../src/focus-stage-lifecycle/wedge-watchdog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,kBAAkB,IAAI,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AACxF,OAAO,EACL,gBAAgB,IAAI,uBAAuB,EAC3C,4BAA4B,IAAI,mCAAmC,EACnE,4BAA4B,IAAI,mCAAmC,EAEpE,MAAM,sBAAsB,CAAC;AAkF9B,gFAAgF;AAChF,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB;;;;OAIG;IACH,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,gFAAgF;AAChF,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,iHAAiH;IACjH,kBAAkB,EAAE,OAAO,CAAC;IAC5B,sGAAsG;IACtG,gBAAgB,EAAE,qBAAqB,GAAG,IAAI,CAAC;IAC/C,yFAAyF;IACzF,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,0BAA0B,CACxC,UAAU,EAAE,aAAa,CAAC;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,CAAC,GACD,kBAAkB,CAyBpB;AAsED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,YAAY,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,IAAI,CAE/E;AAED,yDAAyD;AACzD,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD;AAeD;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,kBAAkB,EAAE,OAAO,yBAAyB,CAAC;IACrD,4BAA4B,EAAE,OAAO,mCAAmC,CAAC;IACzE,iGAAiG;IACjG,4BAA4B,EAAE,OAAO,mCAAmC,CAAC;IACzE,gBAAgB,EAAE,OAAO,uBAAuB,CAAC;IACjD,gFAAgF;IAChF,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IAC5C,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;CACrB;AAcD,uEAAuE;AACvE,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,qBAAqB,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,SAAS,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7F;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE;IACL,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,gFAAgF;IAChF,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB,EACD,IAAI,GAAE,iBAA8C,GACnD,OAAO,CAAC,YAAY,CAAC,CA+LvB"}