@telora/daemon 0.19.47 → 0.19.82

package/dist/focus-stage-lifecycle.js

@@ -20,843 +20,35 @@
  *                         (Issue 3: review_nonconvergent escalation, focus
  *                         stays at review until a human intervenes).
  *
- * This module owns all four daemon-side transitions. 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.
+ * This module owns the poll-loop dispatcher `runStageLifecycleTransitions` and
+ * re-exports the decomposed transition logic, which lives in three 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.
+ *
+ * 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.
  *
  * @module focus-stage-lifecycle
  */
 import { configForProduct } from './config.js';
 import { getActiveFocuses as defaultGetActiveFocuses } from './supabase.js';
-import { getFocusDeliveries as defaultGetFocusDeliveries, getLatestCompletedFocusReview as defaultGetLatestCompletedFocusReview, getInFlightRemediationCount as defaultGetInFlightRemediationCount, getFocusReviewIterationCount as defaultGetFocusReviewIterationCount, updateFocusStage as defaultUpdateFocusStage, updateFocusReadOnly as defaultUpdateFocusReadOnly, } from './queries/focuses.js';
-import { updateDeliveryStatus as defaultUpdateDeliveryStatus } from './queries/deliveries.js';
-import { createEscalation as defaultCreateEscalation, hasOpenWedgedFocusEscalation as defaultHasOpenWedgedFocusEscalation, WEDGED_FOCUS_ESCALATION_KIND, } from './queries/issues.js';
-import { ESCALATION_REASONS, ESCALATION_KINDS, ESCALATION_DISPOSITIONS, FOCUS_STAGE, DELIVERY_STATUS, } from '@telora/daemon-core';
-import { emitLoopTrigger } from './loop-event-bus.js';
-import { isReviewEnabled } from './pipeline-config.js';
-import { deriveFocusPhase } from './focus-phase.js';
-import { hasActiveTeam as defaultHasActiveTeam } from './focus-team-state.js';
-import { isAuditPhaseFocus } from './audit-shape.js';
-// ── Constants ─────────────────────────────────────────────────────
-/**
- * Default cap on review iterations before the daemon files a
- * `review_nonconvergent` escalation and pauses the focus.
- *
- * Configurable per focus via `pipeline_config.review.maxIterations`.
- */
-export const DEFAULT_REVIEW_MAX_ITERATIONS = 3;
-// ── Pure helpers (Issue 2 + Issue 3) ──────────────────────────────
-/**
- * Decide whether a focus has converged out of review. Convergence is
- * deterministic and state-based:
- *
- *   - If there are no in-flight remediation deliveries created during/after
- *     the latest review pass, the focus has converged.
- *
- * Pure function: takes the in-flight count and returns the decision.
- * Exported so tests can drive it with synthetic counts.
- */
-export function hasReviewConverged(inFlightRemediationCount) {
-    return inFlightRemediationCount <= 0;
-}
-/**
- * Compute the configured review iteration cap for a focus. Pulls
- * `pipeline_config.review.maxIterations` and falls back to
- * `DEFAULT_REVIEW_MAX_ITERATIONS` when unset or non-positive.
- *
- * Exported for unit testing.
- */
-export function getReviewIterationCap(pipelineConfig) {
-    const raw = pipelineConfig?.review?.maxIterations;
-    if (typeof raw !== 'number' || !Number.isFinite(raw) || raw <= 0) {
-        return DEFAULT_REVIEW_MAX_ITERATIONS;
-    }
-    return Math.floor(raw);
-}
-// ── Convergence check (Issue 2) ───────────────────────────────────
-/**
- * Returns true when the focus has any in-flight remediation deliveries
- * created during/after the latest review pass.
- *
- * "Latest review pass" is the `started_at` of the most recent focus_reviews
- * row; when no review has run yet, this returns false (no remediation
- * deliveries can exist before a review pass).
- *
- * In-flight means execution_status is NOT one of done/cancelled/verify.
- *
- * Exported for unit testing the convergence query independently of the
- * surrounding transition logic.
- */
-export async function hasInFlightRemediations(focusId, latestReviewPassTimestamp, deps = { getInFlightRemediationCount: defaultGetInFlightRemediationCount }) {
-    if (!latestReviewPassTimestamp) {
-        return false;
-    }
-    const count = await deps.getInFlightRemediationCount(focusId, latestReviewPassTimestamp);
-    return count > 0;
-}
-const defaultVerifyToReviewDeps = {
-    updateFocusStage: defaultUpdateFocusStage,
-    emitLoopTrigger,
-};
-/**
- * When a focus's stage is `verify` and auto-review is enabled, advance it to
- * `review`. Auto-review is default-on (`isReviewEnabled`): only an explicit
- * `pipeline_config.review.enabled === false` keeps the focus at `verify` until
- * a human signals review. A focus with no stored review key auto-advances.
- *
- * Returns true when an advance was performed.
- */
-export async function advanceVerifyToReviewIfEnabled(focus, deps = defaultVerifyToReviewDeps) {
-    if (focus.stage !== FOCUS_STAGE.VERIFY)
-        return false;
-    // Default-on: only an explicit review.enabled === false keeps the focus at
-    // verify. Missing / undefined review reads as enabled (mirrors isCiEnabled).
-    if (!isReviewEnabled(focus.pipelineConfig))
-        return false;
-    try {
-        await deps.updateFocusStage(focus.focusId, 'review');
-        console.log(`[focus-stage-lifecycle] Focus "${focus.focusName}" stage verify -> review ` +
-            `(auto: pipeline_config.review.enabled)`);
-        deps.emitLoopTrigger({
-            type: 'focus_status_changed',
-            focusId: focus.focusId,
-            detail: 'stage:verify->review',
-        });
-        return true;
-    }
-    catch (err) {
-        console.warn(`[focus-stage-lifecycle] Failed to advance "${focus.focusName}" ` +
-            `verify -> review: ${err.message}`);
-        return false;
-    }
-}
-const defaultReviewConvergeDeps = {
-    getLatestCompletedFocusReview: defaultGetLatestCompletedFocusReview,
-    getInFlightRemediationCount: defaultGetInFlightRemediationCount,
-    getFocusReviewIterationCount: defaultGetFocusReviewIterationCount,
-    updateFocusStage: defaultUpdateFocusStage,
-    createEscalation: defaultCreateEscalation,
-    emitLoopTrigger,
-};
-/**
- * Evaluate the review -> close_loop transition for a focus and apply the
- * appropriate action. Returns a structured outcome so callers can log /
- * test the decision path.
- *
- * Logic:
- *   1. If stage is not `review`, do nothing.
- *   2. If the review iteration count is >= the cap, file a
- *      `review_nonconvergent` escalation (idempotent best-effort) and
- *      LEAVE the focus stage at `review`. The focus is paused until a
- *      human intervenes.
- *   3. Otherwise, check in-flight remediations against the latest review
- *      pass. If zero, advance stage `review -> close_loop`.
- *   4. Otherwise, do nothing -- remediations are still in flight.
- *
- * Exported with injectable deps for unit testing.
- */
-export async function advanceReviewToCloseLoopIfConverged(focus, deps = defaultReviewConvergeDeps) {
-    if (focus.stage !== FOCUS_STAGE.REVIEW) {
-        return { kind: 'no_action', reason: 'stage_not_review' };
-    }
-    const cap = getReviewIterationCap(focus.pipelineConfig);
-    let iterations = 0;
-    try {
-        iterations = await deps.getFocusReviewIterationCount(focus.focusId);
-    }
-    catch (err) {
-        console.warn(`[focus-stage-lifecycle] Failed to read review iteration count for ` +
-            `"${focus.focusName}": ${err.message}`);
-        // On read failure, fall through to the convergence check rather than
-        // false-escalating; if iterations were actually high the next tick
-        // will catch it.
-    }
-    if (iterations >= cap) {
-        // N-iteration cap exceeded -- file an escalation and leave the focus
-        // at review. The escalation is best-effort; downstream dedup keeps it
-        // from spamming via the agent_escalations idx_kind_status partial index
-        // (status in ('pending', 'in_review')).
-        try {
-            await deps.createEscalation({
-                organizationId: focus.organizationId,
-                sessionId: '',
-                issueId: null,
-                reasonType: ESCALATION_REASONS.DECISION_NEEDED,
-                // The intent owner must decide: descope, extend the cap, or close.
-                disposition: ESCALATION_DISPOSITIONS.NEEDS_INTENT,
-                anchor: { focusId: focus.focusId },
-                description: `Focus "${focus.focusName}" has not converged after ${iterations} ` +
-                    `review iteration(s) (cap: ${cap}). The review self-loop has been ` +
-                    `paused; a human must decide whether to descope remaining gaps, ` +
-                    `extend the cap via pipeline_config.review.maxIterations, or close ` +
-                    `the focus.`,
-                escalationKind: ESCALATION_KINDS.REVIEW_NONCONVERGENT,
-                // Evidence only -- focus provenance lives on the columns via the anchor.
-                metadata: {
-                    iterations,
-                    cap,
-                },
-            });
-            console.warn(`[focus-stage-lifecycle] review_nonconvergent escalation filed for ` +
-                `"${focus.focusName}" (iterations=${iterations}, cap=${cap}); focus ` +
-                `remains at stage=review.`);
-        }
-        catch (err) {
-            console.warn(`[focus-stage-lifecycle] Failed to file review_nonconvergent ` +
-                `escalation for "${focus.focusName}": ${err.message}`);
-        }
-        return { kind: 'nonconvergent', iterations, cap };
-    }
-    // Look up the latest completed review's started_at. If no review has
-    // completed yet, there are no remediations created against it; treat as
-    // "not yet converged" rather than "converged on zero" -- the agent must
-    // produce a review before we can claim convergence.
-    let latestReviewStartedAt = null;
-    try {
-        const latest = await deps.getLatestCompletedFocusReview(focus.focusId);
-        latestReviewStartedAt = latest?.startedAt ?? null;
-    }
-    catch (err) {
-        console.warn(`[focus-stage-lifecycle] Failed to read latest focus_review for ` +
-            `"${focus.focusName}": ${err.message}`);
-        return { kind: 'no_action', reason: 'review_read_failed' };
-    }
-    if (!latestReviewStartedAt) {
-        return { kind: 'no_action', reason: 'no_completed_review_yet' };
-    }
-    let inFlightCount = 0;
-    try {
-        inFlightCount = await deps.getInFlightRemediationCount(focus.focusId, latestReviewStartedAt);
-    }
-    catch (err) {
-        console.warn(`[focus-stage-lifecycle] Failed to count in-flight remediations for ` +
-            `"${focus.focusName}": ${err.message}`);
-        return { kind: 'no_action', reason: 'remediation_query_failed' };
-    }
-    if (!hasReviewConverged(inFlightCount)) {
-        return { kind: 'no_action', reason: 'remediations_in_flight' };
-    }
-    try {
-        await deps.updateFocusStage(focus.focusId, 'close_loop');
-        console.log(`[focus-stage-lifecycle] Focus "${focus.focusName}" stage review -> ` +
-            `close_loop (converged after ${iterations} iteration(s))`);
-        deps.emitLoopTrigger({
-            type: 'focus_status_changed',
-            focusId: focus.focusId,
-            detail: 'stage:review->close_loop',
-        });
-        return { kind: 'converged', from: 'review', to: 'close_loop' };
-    }
-    catch (err) {
-        console.warn(`[focus-stage-lifecycle] Failed to advance "${focus.focusName}" ` +
-            `review -> close_loop: ${err.message}`);
-        return { kind: 'no_action', reason: 'stage_write_failed' };
-    }
-}
-// ── Ratify-to-execute release (Safe audit-to-remediation D3) ──────
-/**
- * Pure predicate: a read-only focus is ready to cross planning->execution
- * exactly when a human has ratified its remediation plan.
- *
- *   read_only === true  => the focus is in the audit/read-only phase, its
- *                          remediation deliveries held in 'planning'.
- *   ratified_at != null => a human stamped the distinct ratification signal.
- *
- * Both must hold. read_only=false (already crossed / a normal execute focus)
- * fails the predicate, which is what makes the release idempotent: after the
- * crossing flips read_only=false the predicate no longer holds, so re-runs are
- * no-ops. A null ratified_at means the gate has NOT been crossed -- the human
- * signal is absent -- so the focus stays held.
- *
- * Exported so tests can drive it with synthetic focus shapes.
- */
-export function isFocusRatifiedForExecute(focus) {
-    return focus.readOnly === true && focus.ratifiedAt != null;
-}
-const defaultRatifyReleaseDeps = {
-    getFocusDeliveries: defaultGetFocusDeliveries,
-    updateFocusReadOnly: defaultUpdateFocusReadOnly,
-    updateDeliveryStatus: defaultUpdateDeliveryStatus,
-    emitLoopTrigger,
-};
-/**
- * The SOLE planning->execution crossing for a read-only audit focus.
- *
- * When `isFocusRatifiedForExecute(focus)` holds (read_only=true AND a human
- * stamped ratified_at), atomically-in-effect:
- *   (a) flip read_only=false, and
- *   (b) release every held delivery (execution_status 'planning') to 'queued'.
- *
- * This is the ONLY path that does either, which is what makes the gate
- * non-procedural: the gate cannot be crossed by an agent or a stage transition;
- * it requires the distinct human ratification signal that this function reads.
- *
- * Idempotent by construction:
- *   - flipping read_only=false first means the predicate fails on re-entry, so a
- *     second tick is a no-op;
- *   - the delivery move is guarded to ONLY touch 'planning' rows, so deliveries
- *     already queued (or further along) are left untouched.
- *
- * Returns the number of deliveries released (0 when the predicate does not hold
- * or there were no held deliveries).
- *
- * Runs regardless of stage: a read-only audit focus may sit at planning/queued/
- * in_progress, so this is NOT gated on focus.stage.
- */
-export async function releaseRatifiedReadOnlyFocus(focus, deps = defaultRatifyReleaseDeps) {
-    if (!isFocusRatifiedForExecute(focus))
-        return 0;
-    // Crash-safety ordering: release held deliveries FIRST, and flip
-    // read_only=false ONLY after every held 'planning' delivery has been queued.
-    // The flip is what makes the predicate fail on re-entry, so deferring it
-    // until the release is complete means a crash (or a partial failure)
-    // mid-release leaves the predicate TRUE (read_only still true) and the next
-    // tick retries the whole release. Flipping first would orphan any
-    // not-yet-released held delivery: the predicate would already be false and
-    // those deliveries would never be queued.
-    // (a) Release held deliveries: planning -> queued. Guarded so only 'planning'
-    // rows move; anything already queued/further-along is left untouched
-    // (idempotency + safety).
-    let deliveries;
-    try {
-        deliveries = await deps.getFocusDeliveries(focus.focusId);
-    }
-    catch (err) {
-        console.warn(`[focus-stage-lifecycle] Ratify-release: failed to fetch deliveries to ` +
-            `release for "${focus.focusName}" (leaving read_only=true to retry next ` +
-            `tick): ${err.message}`);
-        return 0;
-    }
-    let released = 0;
-    let allReleased = true;
-    for (const d of deliveries) {
-        if (d.executionStatus !== DELIVERY_STATUS.PLANNING)
-            continue;
-        try {
-            await deps.updateDeliveryStatus(d.id, DELIVERY_STATUS.QUEUED, undefined, undefined, undefined, { organizationId: focus.organizationId, fromStatus: DELIVERY_STATUS.PLANNING });
-            released += 1;
-        }
-        catch (err) {
-            allReleased = false;
-            console.warn(`[focus-stage-lifecycle] Ratify-release: failed to queue held delivery ` +
-                `${d.id.slice(0, 8)} on "${focus.focusName}": ${err.message}`);
-        }
-    }
-    // (b) Flip read_only=false ONLY when every held delivery was queued. If any
-    // release failed, leave read_only=true so the predicate stays satisfied and
-    // the next tick retries the (planning-only, idempotent) release -- never
-    // crossing the gate with held deliveries still stuck in planning.
-    if (!allReleased) {
-        console.warn(`[focus-stage-lifecycle] Ratify-release: not all held deliveries queued ` +
-            `for "${focus.focusName}" (released ${released}); leaving read_only=true ` +
-            `to retry next tick.`);
-        return released;
-    }
-    try {
-        await deps.updateFocusReadOnly(focus.focusId, false);
-    }
-    catch (err) {
-        console.warn(`[focus-stage-lifecycle] Ratify-release: held deliveries queued for ` +
-            `"${focus.focusName}" but failed to flip read_only=false (will retry ` +
-            `next tick): ${err.message}`);
-        return released;
-    }
-    console.log(`[focus-stage-lifecycle] Focus "${focus.focusName}" ratified -> execute: ` +
-        `read_only=false, released ${released} held planning ` +
-        `deliver${released === 1 ? 'y' : 'ies'} to queued.`);
-    deps.emitLoopTrigger({
-        type: 'focus_status_changed',
-        focusId: focus.focusId,
-        detail: 'ratify:read_only->execute',
-    });
-    return released;
-}
-// ── Writable-focus planning->queued release (planning-wedge prevention D1) ──
-/**
- * Pure predicate: a writable focus is PAST its planning/kickoff window -- i.e. a
- * lingering 'planning' delivery on it is a WEDGE to release, not work a scoping
- * team is still shaping.
- *
- * Stage-column-INDEPENDENT by design. The previous version gated on
- * `isPostPlanning(focus.stage)`, but `product_focuses.stage` is a documented-stale
- * column: NO live path advances it to 'queued'/'in_progress' (the daemon writes
- * only review/close_loop/done; everything else keeps the 'planning' default).
- * supabase/.../focus/lifecycle.ts says so explicitly ("nothing advances `stage`
- * to 'verify'"), which is why the newer code (checkAutoReview, focus_transition_stage)
- * gates on the DERIVED phase instead. The old stage gate therefore NEVER fired for
- * the founding wedge -- a post-backfill writable focus whose stage stays 'planning'
- * forever (review finding, delivery 18055ddd). Worse, it was self-defeating: a
- * delivery is born 'planning' PRECISELY because focus.stage was not post-planning
- * (MCP resolveDefaultExecutionStatus reads the same column), and nothing changes
- * the column before this tick -- so the release could never see a post-planning
- * stage for exactly the focuses that have born-planning deliveries.
- *
- * The replacement uses two stage-free signals:
- *   1. read_only === false -- a NORMAL execute focus, not a read-only audit focus
- *      (whose held planning deliveries are released only by the human-ratified
- *      `releaseRatifiedReadOnlyFocus`).
- *   2. "past kickoff" via the delivery aggregate + active-team:
- *        - deriveFocusPhase(deliveries) !== 'kickoff'  => real work already exists
- *          (some delivery is queued/coding/verify/done), so a lingering 'planning'
- *          row is a wedge behind/ahead of it -> past kickoff.
- *        - phase === 'kickoff' (all deliveries planning/draft, or none): genuinely
- *          ambiguous between a live scoping window and a full wedge. An ACTIVE TEAM
- *          is the discriminator -- a scoping team running for the focus is (or just
- *          was) creating/releasing deliveries, so DON'T pre-empt it; no team means
- *          nothing can make progress (the rank-0 planning delivery blocks the ready
- *          selector so no team will ever spawn) -> wedge -> past kickoff.
- *
- * Second discovery-only signal (injection #7, TEL-3): signal 1 is widened from a
- * bare `read_only === false` to "NOT audit-phase". An audit-origin, not-yet-
- * ratified focus whose `read_only` is silently absent (coerced false) is STILL an
- * audit focus -- its born-planning remediation deliveries are owned by the ratify
- * path and must NOT be swept to queued here, or the remediation executes ahead of
- * the human ratify gate (2f253da6). `isAuditPhaseFocus` captures read_only===true
- * OR (audit_origin AND !ratified); a RATIFIED audit focus (read_only=false,
- * ratified_at set) is NOT audit-phase and IS released normally, and a NORMAL focus
- * (audit_origin=false) is unaffected. Keyed on audit_origin + ratified_at
- * (provenance + phase) -- it never writes read_only, so it is not a second source
- * of truth for the flag.
- *
- * Exported so tests can drive it with synthetic shapes.
- */
-export function isWritableFocusPastKickoff(input) {
-    // Audit-phase focuses (explicit read_only=true OR the second structural signal:
-    // audit_origin && not-yet-ratified) are owned by the ratify-release path.
-    if (isAuditPhaseFocus({
-        readOnly: input.readOnly === true,
-        auditOrigin: input.auditOrigin === true,
-        ratified: input.ratifiedAt != null,
-    })) {
-        return false;
-    }
-    if (input.readOnly !== false)
-        return false;
-    const phase = deriveFocusPhase({
-        deliveries: input.deliveries.map((d) => ({ executionStatus: d.executionStatus })),
-        reviewRequestedAt: input.reviewRequestedAt ?? null,
-    });
-    // Any non-kickoff phase => real work exists => a held planning row is a wedge.
-    if (phase !== 'kickoff')
-        return true;
-    // Pure all-planning/draft (or empty) 'kickoff': a wedge only when no team is
-    // (or can be) working it. An active scoping team is shaping deliveries -- leave it.
-    return !input.hasActiveTeam;
-}
-const defaultWritableReleaseDeps = {
-    getFocusDeliveries: defaultGetFocusDeliveries,
-    updateDeliveryStatus: defaultUpdateDeliveryStatus,
-    emitLoopTrigger,
-    hasActiveTeam: defaultHasActiveTeam,
-};
-/**
- * The writable-focus analogue of `releaseRatifiedReadOnlyFocus`: the missing
- * planning->queued release for a NORMAL (read_only=false) executing focus.
- *
- * Closes the silent wedge: a writable focus whose deliveries were born
- * 'planning' (created during the planning stage, or via the MCP focus_list
- * lookup falling back to 'planning') has NO transition that releases them once
- * the focus is past planning -- the only planning->queued release in the
- * codebase (`releaseRatifiedReadOnlyFocus`) is gated to ratified read-only audit
- * focuses, and listener-auto-advance only moves queued/coding -> verify. So
- * `daemon_get_ready_focuses` hits the rank-0 'planning' delivery, treats it as a
- * hard block, and the focus never spawns a team.
- *
- * Fetch the focus's deliveries, and when `isWritableFocusPastKickoff` holds (the
- * stage-column-independent gate), sweep every held delivery (execution_status
- * 'planning') to 'queued'. Guarded so ONLY 'planning' rows move --
- * draft/paused/queued/further-along are left untouched, which also makes the
- * release idempotent: once swept, there are no 'planning' rows left so a re-run is
- * a no-op. Unlike the ratify path there is no read_only flip to defer, so each
- * delivery move stands on its own; a per-delivery failure is logged and retried on
- * the next tick.
- *
- * FRT effect #6 (a completed/merged delivery stuck in 'planning' must advance out
- * of 'planning' and never block at rank 0): planning's ONLY valid forward
- * transition is 'queued' (DELIVERY_STATUS machine: planning -> queued|cancelled;
- * planning -> done is illegal). So 'queued' is the correct -- and only -- forward
- * move here even for a complete-but-mislabeled row: it advances out of 'planning'
- * and re-enters the normal lifecycle, which re-settles already-done work quickly
- * (its issues are already Done -> coding -> verify -> done). Re-running merged work
- * is bounded by that; skipping the row instead would leave it 'planning' and
- * re-wedge the focus, which is worse.
- *
- * Returns the number of deliveries released (0 when the gate does not hold or
- * there were no held deliveries).
- */
-export async function releaseWritableFocusPlanningDeliveries(focus, deps = defaultWritableReleaseDeps) {
-    // Audit-phase focuses -- explicit read_only=true OR the second structural signal
-    // (audit_origin && not-yet-ratified) -- are owned by the ratify-release path.
-    // Cheap exit before the fetch (isWritableFocusPastKickoff re-checks). Without
-    // this a flag-absent audit focus (read_only silently false) would sweep its
-    // born-planning remediation delivery to queued ahead of ratification (2f253da6).
-    if (isAuditPhaseFocus({
-        readOnly: focus.readOnly === true,
-        auditOrigin: focus.auditOrigin === true,
-        ratified: focus.ratifiedAt != null,
-    })) {
-        return 0;
-    }
-    if (focus.readOnly !== false)
-        return 0;
-    let deliveries;
-    try {
-        deliveries = await deps.getFocusDeliveries(focus.focusId);
-    }
-    catch (err) {
-        console.warn(`[focus-stage-lifecycle] Writable-release: failed to fetch deliveries to ` +
-            `release for "${focus.focusName}" (retry next tick): ${err.message}`);
-        return 0;
-    }
-    // Stage-column-INDEPENDENT gate: derived phase + active-team, never focus.stage.
-    if (!isWritableFocusPastKickoff({
-        readOnly: focus.readOnly,
-        auditOrigin: focus.auditOrigin,
-        ratifiedAt: focus.ratifiedAt,
-        deliveries,
-        reviewRequestedAt: focus.reviewRequestedAt,
-        hasActiveTeam: deps.hasActiveTeam(focus.focusId),
-    })) {
-        return 0;
-    }
-    let released = 0;
-    for (const d of deliveries) {
-        if (d.executionStatus !== DELIVERY_STATUS.PLANNING)
-            continue;
-        try {
-            await deps.updateDeliveryStatus(d.id, DELIVERY_STATUS.QUEUED, undefined, undefined, undefined, { organizationId: focus.organizationId, fromStatus: DELIVERY_STATUS.PLANNING });
-            released += 1;
-        }
-        catch (err) {
-            console.warn(`[focus-stage-lifecycle] Writable-release: failed to queue held delivery ` +
-                `${d.id.slice(0, 8)} on "${focus.focusName}": ${err.message}`);
-        }
-    }
-    if (released > 0) {
-        console.log(`[focus-stage-lifecycle] Focus "${focus.focusName}" (writable, past kickoff): ` +
-            `released ${released} born-planning deliver${released === 1 ? 'y' : 'ies'} to queued.`);
-        deps.emitLoopTrigger({
-            type: 'focus_status_changed',
-            focusId: focus.focusId,
-            detail: 'writable:planning->queued',
-        });
-    }
-    return released;
-}
-// ── Planning-wedge watchdog + zero-actionable log (D2 + D3) ───────
-/**
- * Delivery execution_status sets that mirror the server-side ready-focus
- * selector (supabase/functions/product-api/handlers/daemon-focus-handlers.ts:
- * NON_BLOCKING_STATUSES / ACTIONABLE_STATUSES). The edge is the SSOT; this
- * daemon-side mirror exists because the daemon receives an empty ready list for
- * a blocked focus and has no other window onto WHY. The status->class mapping is
- * kept in lockstep with the edge -- a divergence there would make the wedge log /
- * escalation disagree with what the daemon actually surfaces.
- *
- *   non-blocking  = terminal-ish; never blocks a focus (skipped in the walk).
- *   actionable    = a delivery the daemon can spawn a team for.
- *   everything else (planning, draft, paused) is non-terminal + non-actionable:
- *                   it BLOCKS the focus when encountered first in rank order.
- *
- * DELIBERATE simplification vs the edge (review finding, deliveries 66c7d4d8 /
- * bbe01d7d): the edge ALSO skips an actionable delivery that already has an active
- * agent_session (`if (activeDeliveryIds.has(d.id)) continue;`), continuing the
- * rank walk past it. This daemon mirror does NOT model per-delivery active
- * sessions -- it has no equivalent of that DB query, and its in-memory team map is
- * focus-grained, not delivery-grained. The omission is BENIGN for wedge detection:
- * an actionable delivery with an active session means a team IS running, i.e. the
- * focus is making progress and is definitionally NOT wedged -- exactly what
- * `surfacesActionable: true` already reports. So the mirror can over-report
- * "surfaces actionable" relative to the edge's "ready" list, but never under-report
- * a wedge. We do not claim byte-for-byte parity, only that the wedge verdict agrees.
- */
-const WEDGE_NON_BLOCKING_STATUSES = new Set([
-    DELIVERY_STATUS.DONE,
-    DELIVERY_STATUS.CANCELLED,
-    DELIVERY_STATUS.VERIFY,
-]);
-const WEDGE_ACTIONABLE_STATUSES = new Set([
-    DELIVERY_STATUS.QUEUED,
-    DELIVERY_STATUS.CODING,
-    DELIVERY_STATUS.VERIFY_FAILED,
-]);
-/**
- * Held statuses that constitute a WEDGE worth escalating: work that should be
- * advancing but is stuck. Deliberately EXCLUDES 'paused' -- a pause is an
- * intentional human hold, not a wedge (AC: the watchdog must not fire for a
- * focus paused by a human).
- */
-const WEDGE_HELD_STATUSES = new Set([
-    DELIVERY_STATUS.PLANNING,
-    DELIVERY_STATUS.DRAFT,
-]);
-/**
- * Replicate the server-side ready-focus rank-walk to decide whether a focus
- * surfaces actionable work, and if not, which delivery blocks it.
- *
- * The walk (rank-ascending, matching the edge): skip terminal-ish deliveries;
- * the FIRST non-terminal delivery decides -- actionable => the focus surfaces
- * (not wedged); non-actionable (planning/draft/paused) => that delivery blocks
- * the focus and everything behind it. This is why a low-rank 'planning' delivery
- * wedges a focus even when a higher-rank 'queued' delivery exists.
- *
- * Pure and exported for unit testing. Expects deliveries pre-sorted by
- * priorityRank ascending (as daemon_get_focus_deliveries returns them); it does
- * not re-sort, mirroring the edge which relies on the query's ORDER BY.
- */
-export function classifyFocusActionability(deliveries) {
-    const totalCount = deliveries.length;
-    for (const d of deliveries) {
-        const status = d.executionStatus ?? '';
-        if (WEDGE_NON_BLOCKING_STATUSES.has(status))
-            continue;
-        if (WEDGE_ACTIONABLE_STATUSES.has(status)) {
-            return { totalCount, surfacesActionable: true, blockingDelivery: null, allTerminal: false };
-        }
-        // First non-terminal, non-actionable delivery -- it blocks the focus.
-        return {
-            totalCount,
-            surfacesActionable: false,
-            blockingDelivery: {
-                id: d.id,
-                name: d.name,
-                status,
-                priorityRank: d.priorityRank,
-                updatedAt: d.updatedAt ?? null,
-            },
-            allTerminal: false,
-        };
-    }
-    // Every delivery was terminal-ish (or there were none): not a wedge.
-    return { totalCount, surfacesActionable: false, blockingDelivery: null, allTerminal: true };
-}
-// Per-focus watchdog state. Module-level so it persists across poll ticks.
-//   firstSeenAt: in-memory first-seen (ms) FALLBACK clock, used only when the
-//                blocking delivery has no updatedAt to ground the wedge age on.
-//   logSig:      last D3 log signature (blockingDeliveryId:status:char), for dampening.
-const focusWedgeFirstSeenAt = new Map();
-const focusZeroActionableLogSig = new Map();
-/** Clear a focus's watchdog state (called when it is no longer zero-actionable). */
-function clearFocusWedgeState(focusId) {
-    focusWedgeFirstSeenAt.delete(focusId);
-    focusZeroActionableLogSig.delete(focusId);
-}
-/**
- * Evict watchdog state for any focus NOT in `liveFocusIds`. A focus that goes
- * terminal (complete/cancelled) or whose product is unclaimed simply stops being
- * returned by getActiveFocuses, so `evaluateFocusWedge` never runs again to clear
- * its entry -- leaving a slow unbounded leak keyed by focusId (review finding,
- * delivery 66c7d4d8). The poll loop calls this once per run with the set of
- * focusIds it actually saw, bounding both maps to currently-active focuses.
- */
-export function pruneWedgeWatchdogState(liveFocusIds) {
-    for (const id of focusWedgeFirstSeenAt.keys()) {
-        if (!liveFocusIds.has(id))
-            focusWedgeFirstSeenAt.delete(id);
-    }
-    for (const id of focusZeroActionableLogSig.keys()) {
-        if (!liveFocusIds.has(id))
-            focusZeroActionableLogSig.delete(id);
-    }
-}
-/** Test seam: reset all watchdog state between cases. */
-export function __resetWedgeWatchdogState() {
-    focusWedgeFirstSeenAt.clear();
-    focusZeroActionableLogSig.clear();
-}
-/** Default wedge threshold (minutes) when the env var is unset / invalid. */
-const DEFAULT_WEDGED_FOCUS_THRESHOLD_MIN = 30;
-/**
- * Resolve the wedge threshold (ms).
- *
- * The canonical typed declaration of this knob lives in @telora/daemon-core
- * env-config (TELORA_WEDGED_FOCUS_THRESHOLD_MIN, positiveInt default 30) -- the
- * single source of truth for every operational knob. We read it directly from
- * process.env here (rather than via loadEnvConfig) so the daemon works against
- * the currently-installed daemon-core (a registry dep, not a workspace symlink)
- * before that package is republished with the new field -- the same pattern the
- * drift-eval list backoff and the stuck-shutdown watchdog use. Non-numeric /
- * non-positive falls back to the 30-minute default.
- */
-function defaultWedgeThresholdMs() {
-    const raw = process.env.TELORA_WEDGED_FOCUS_THRESHOLD_MIN;
-    const parsed = raw === undefined || raw === '' ? NaN : Number(raw);
-    const minutes = Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_WEDGED_FOCUS_THRESHOLD_MIN;
-    return minutes * 60_000;
-}
-function defaultWedgeWatchdogDeps() {
-    return {
-        getFocusDeliveries: defaultGetFocusDeliveries,
-        hasOpenWedgedFocusEscalation: defaultHasOpenWedgedFocusEscalation,
-        createEscalation: defaultCreateEscalation,
-        hasActiveTeam: defaultHasActiveTeam,
-        now: () => Date.now(),
-        thresholdMs: defaultWedgeThresholdMs(),
-    };
-}
-/**
- * Per-focus, per-tick evaluation of the planning-wedge condition. Does two
- * things off ONE actionability classification:
- *
- *   D3 (log): when an active, role-assigned focus surfaces zero actionable
- *     deliveries, name the rank-0 blocking delivery + its state in the daemon
- *     log -- so a wedge is visible in ~/.telora/daemon.log, not only the
- *     edge-function log. Dampened to once per focus per state change.
- *
- *   D2 (escalate): when that focus is ALSO writable, the block is a WEDGE
- *     (planning/draft, not a human pause), NO team is running, and the wedge
- *     persists past the threshold, file a deduped wedged_focus escalation --
- *     defense-in-depth for wedge classes the rank-respecting release (D1) does
- *     not resolve (e.g. a 'draft' block, which D1 does not sweep).
- *
- * Runs AFTER the D1 release in the poll loop, so a focus D1 just unwedged is
- * already surfacing actionable work here and neither logs nor escalates.
- *
- * Gating (escalation): status active + assigned_agent_role_id set + read_only
- * false + wedge-held block + NO active team. The "no active team" check replaces
- * the old (broken) isPostPlanning(stage) gate -- the stage column is stale and
- * never reaches post-planning, so that gate never fired for the founding wedge
- * (review finding, delivery 66c7d4d8). It is the same kickoff-window discriminator
- * D1 uses: a running scoping team is shaping/releasing deliveries (don't escalate);
- * no team means nothing can make progress (the rank-0 block stops the ready
- * selector from spawning one) -- a true wedge. Zero-delivery focuses (planning
- * teams) and all-paused focuses (human hold) are excluded by the classifier (no
- * wedge-held blocking delivery).
- */
-export async function evaluateFocusWedge(focus, deps = defaultWedgeWatchdogDeps()) {
-    // Only active, role-assigned focuses can wedge an execution team. An
-    // unassigned or non-active focus has nothing to spawn -- not a wedge.
-    if (focus.status !== 'active' || !focus.assignedAgentRoleId) {
-        clearFocusWedgeState(focus.focusId);
-        return { kind: 'skipped', reason: 'not_active_or_unassigned' };
-    }
-    let deliveries;
-    try {
-        deliveries = await deps.getFocusDeliveries(focus.focusId);
-    }
-    catch (err) {
-        console.warn(`[focus-stage-lifecycle] Wedge eval: failed to fetch deliveries for ` +
-            `"${focus.focusName}": ${err.message}`);
-        return { kind: 'skipped', reason: 'delivery_fetch_failed' };
-    }
-    const actionability = classifyFocusActionability(deliveries);
-    // The focus surfaces actionable work (or has only terminal/zero deliveries):
-    // not zero-actionable-with-a-block -> clear any prior wedge state and return.
-    if (actionability.surfacesActionable || !actionability.blockingDelivery) {
-        clearFocusWedgeState(focus.focusId);
-        return actionability.surfacesActionable
-            ? { kind: 'surfaces_actionable' }
-            : { kind: 'skipped', reason: 'all_terminal_or_empty' };
-    }
-    const block = actionability.blockingDelivery;
-    const isWedgeHeld = WEDGE_HELD_STATUSES.has(block.status); // planning/draft vs paused
-    const teamActive = deps.hasActiveTeam(focus.focusId);
-    // ── D3: daemon-side zero-actionable log (dampened to state change) ──
-    // Characterization distinguishes THREE states (review finding, delivery
-    // bbe01d7d): a human pause (idle), a live kickoff/scoping window (team active,
-    // deliveries being shaped -- NOT a wedge), and a true wedge (held work, no team
-    // running). The old two-way split mislabeled a legitimate kickoff focus as
-    // "wedged"; the active-team signal separates them.
-    const characterization = !isWedgeHeld
-        ? 'idle (delivery paused by a human)'
-        : teamActive
-            ? 'scoping in progress (team active, deliveries being shaped -- not a wedge)'
-            : 'wedged (work held, no team running)';
-    // Fold team-active into the dampening signature so a kickoff->wedge transition
-    // (team exits while the block persists) re-logs with the updated characterization.
-    const logSig = `${block.id}:${block.status}:${teamActive ? 'team' : 'noteam'}`;
-    if (focusZeroActionableLogSig.get(focus.focusId) !== logSig) {
-        focusZeroActionableLogSig.set(focus.focusId, logSig);
-        console.log(`[focus-stage-lifecycle] Focus "${focus.focusName}" (stage=${focus.stage ?? 'unknown'}) ` +
-            `surfaced zero actionable deliveries: rank-${block.priorityRank} "${block.name}" in ` +
-            `"${block.status}" state -- ${characterization}.`);
-    }
-    // ── D2: wedged_focus escalation (writable + wedge-held + no active team) ──
-    // No isPostPlanning(stage) gate -- the stage column is stale (see header). The
-    // "no active team" check is the kickoff-window discriminator: a running scoping
-    // team means the focus is making progress, not wedged.
-    const escalationEligible = focus.readOnly === false &&
-        isWedgeHeld &&
-        !teamActive;
-    if (!escalationEligible) {
-        // Zero-actionable but not an escalation-worthy wedge (read-only audit, human
-        // pause, or a live scoping team). Logged above; clear the fallback timer.
-        focusWedgeFirstSeenAt.delete(focus.focusId);
-        return { kind: 'zero_actionable', escalated: false, wedged: false, blockingStatus: block.status };
-    }
-    // Threshold: escalate only once the wedge has persisted past the window --
-    // giving the D1 release time to fix it. Prefer the blocking delivery's
-    // updatedAt as a RESTART-DURABLE wedge-age proxy (how long the row has actually
-    // sat held; survives a daemon restart, fixing the process-memory reset --
-    // review finding, delivery 66c7d4d8). Fall back to the in-memory first-seen
-    // clock only when updatedAt is unavailable (older backends).
-    const now = deps.now();
-    const updatedAtMs = block.updatedAt ? Date.parse(block.updatedAt) : NaN;
-    let firstSeen;
-    if (Number.isFinite(updatedAtMs)) {
-        firstSeen = updatedAtMs;
-        focusWedgeFirstSeenAt.delete(focus.focusId); // DB-grounded; no in-memory clock needed
-    }
-    else {
-        firstSeen = focusWedgeFirstSeenAt.get(focus.focusId) ?? now;
-        if (!focusWedgeFirstSeenAt.has(focus.focusId)) {
-            focusWedgeFirstSeenAt.set(focus.focusId, now);
-        }
-    }
-    if (now - firstSeen < deps.thresholdMs) {
-        return { kind: 'zero_actionable', escalated: false, wedged: true, blockingStatus: block.status };
-    }
-    // Dedup: at most one open wedged_focus escalation per focus (survives restart).
-    try {
-        if (await deps.hasOpenWedgedFocusEscalation(focus.focusId)) {
-            return { kind: 'zero_actionable', escalated: false, wedged: true, blockingStatus: block.status };
-        }
-    }
-    catch (err) {
-        console.warn(`[focus-stage-lifecycle] Wedge eval: dedup check failed for ` +
-            `"${focus.focusName}" (skipping escalation this tick): ${err.message}`);
-        return { kind: 'zero_actionable', escalated: false, wedged: true, blockingStatus: block.status };
-    }
-    const wedgedMinutes = Math.round((now - firstSeen) / 60_000);
-    try {
-        await deps.createEscalation({
-            organizationId: focus.organizationId,
-            sessionId: '',
-            issueId: null,
-            reasonType: ESCALATION_REASONS.BLOCKED_BY_EXTERNAL,
-            disposition: ESCALATION_DISPOSITIONS.AGENT_RESOLVABLE,
-            anchor: { focusId: focus.focusId },
-            description: `Focus "${focus.focusName}" is wedged: it is active, role-assigned, ` +
-                `writable, and has no running team, but has zero actionable deliveries -- ` +
-                `the rank-${block.priorityRank} delivery "${block.name}" is stuck in ` +
-                `"${block.status}" state, blocking the focus, so no execution team ` +
-                `spawns. It has been wedged for ~${wedgedMinutes} minute(s). The ` +
-                `writable planning->queued release should normally clear a 'planning' ` +
-                `block; investigate why the delivery is not being released ` +
-                `(a 'draft' block is not swept by that release and needs attention).`,
-            // Local string const (mirrors ESCALATION_KINDS.WEDGED_FOCUS in
-            // daemon-core, the SSOT) so the write works against the currently-
-            // installed daemon-core before it is republished with the new enum value.
-            escalationKind: WEDGED_FOCUS_ESCALATION_KIND,
-            metadata: {
-                focusId: focus.focusId,
-                kind: WEDGED_FOCUS_ESCALATION_KIND,
-                blockingDeliveryId: block.id,
-                blockingDeliveryStatus: block.status,
-                wedgedMinutes,
-            },
-        });
-        console.warn(`[focus-stage-lifecycle] wedged_focus escalation filed for ` +
-            `"${focus.focusName}" (rank-${block.priorityRank} "${block.name}" in ` +
-            `"${block.status}", wedged ~${wedgedMinutes}m).`);
-        return { kind: 'zero_actionable', escalated: true, wedged: true, blockingStatus: block.status };
-    }
-    catch (err) {
-        console.warn(`[focus-stage-lifecycle] Failed to file wedged_focus escalation for ` +
-            `"${focus.focusName}": ${err.message}`);
-        return { kind: 'zero_actionable', escalated: false, wedged: true, blockingStatus: block.status };
-    }
-}
+import { getFocusDeliveries as defaultGetFocusDeliveries } from './queries/focuses.js';
+import { FOCUS_STAGE } from '@telora/daemon-core';
+import { advanceVerifyToReviewIfEnabled, advanceReviewToCloseLoopIfConverged, } from './focus-stage-lifecycle/review-convergence.js';
+import { releaseRatifiedReadOnlyFocus, releaseWritableFocusPlanningDeliveries, } from './focus-stage-lifecycle/planning-release.js';
+import { evaluateFocusWedge, pruneWedgeWatchdogState, } from './focus-stage-lifecycle/wedge-watchdog.js';
+// Re-export the decomposed surface so every importer + test keeps resolving
+// these names from './focus-stage-lifecycle.js' unchanged.
+export * from './focus-stage-lifecycle/review-convergence.js';
+export * from './focus-stage-lifecycle/planning-release.js';
+export * from './focus-stage-lifecycle/wedge-watchdog.js';
 // ── Poll-loop entry point ─────────────────────────────────────────
 /**
  * Per-product per-focus tick for the new stage lifecycle transitions.