@telora/daemon 0.21.26 → 0.21.82

package/dist/focus/listener.js

@@ -0,0 +1,770 @@
+/**
+ * Polling-based listener for focus assignments.
+ *
+ * Since we're using HTTP API instead of direct Supabase access,
+ * we poll for ready focuses instead of using Realtime subscriptions.
+ * Agent assignment is at the focus level — the daemon spawns a
+ * single Agent Team per focus that manages all deliveries.
+ */
+import { getAgentRoles } from '../queries/roles.js';
+import { checkDeliveryAutoAdvance, checkVerifyDeliveriesForOpenIssues, checkDeliveryWorkStart } from './listener-auto-advance.js';
+import { runReconcilerShadow } from '../delivery/delivery-reconciler-shadow.js';
+import { spawnFocusTeam, hasActiveTeam, getActiveTeamCount, getActiveTeams, checkAndMergeCompletedDeliveries } from './focus-executor.js';
+import { applyRespawnGuard } from './focus-respawn-guard.js';
+import { checkResolvedMergeConflicts } from '../merge/focus-merge.js';
+import { runCascadeChecks } from '../completion/state-cascade.js';
+import { runStageLifecycleTransitions } from '../focus-stage-lifecycle/index.js';
+import { recordActivity } from '../shell/heartbeat.js';
+import { safeInterval, withRetry } from '@telora/daemon-core';
+import { getActiveSessions, updateSession } from '../queries/sessions.js';
+import { ensureFocusWorktrees, checkForDeactivatedFocuses } from './focus-lifecycle.js';
+import { detectGitStates } from '../git/index.js';
+import { detectFocusMerges } from '../merge/merge-detector.js';
+import { checkControlStateChanges, reapDisarmedTeams } from '../shell/control-state.js';
+import { isDaemonShuttingDown } from '../shell/shutdown-state.js';
+import { registerPollTrigger, triggerCheck } from '../poll-trigger.js';
+// Re-exported for existing importers; the live trigger is registered below.
+export { triggerCheck };
+import { configForProduct, findProduct } from '../shell/config.js';
+import { checkIncomingRequests } from '../nexus/index.js';
+import { checkIntakePendingRequests } from '../nexus/index.js';
+import { checkResolvedRequests } from '../nexus/index.js';
+import { checkEndpointClearance } from '../nexus/index.js';
+import { checkDirectives, seedLastProcessedStage, getPendingSpawnFocusIds, getPendingSpawnDirective, clearPendingSpawnDirective, shouldReapPendingSpawnDirective } from '../directive/directive-executor.js';
+import { decideNullRoleSpawn, resolveReviewerFallbackRole, shouldWarnNullRoleSkip, DEFAULT_REVIEWER_ROLE_NAME } from '../spawn/review-role-fallback.js';
+import { getActiveFocuses, getReadyFocuses, clearAnswerRearm } from '../queries/deliveries.js';
+import { isAuditPhaseFocusRow } from '../audit/audit-shape.js';
+import { isIntakeDraining } from '../shell/intake-control.js';
+import { checkDiscoveryRequests } from '../host-control/discovery-poll.js';
+// Track focuses that have been logged as idle (no actionable deliveries).
+// Only log on state change: first skip after an active session or after startup.
+const idleLoggedFocuses = new Set();
+// Track focuses already warned this blocked episode for a null-role coding
+// off-state pending directive (Play/queue toggle cleared, no operator stop).
+// Without this, the "no assigned_agent_role_id; skipping spawn (coding off-state)"
+// warning fires every 30s poll for as long as the directive sits queued. We warn
+// once on entry and suppress until the focus resumes (role assigned, directive
+// cleared, or focus leaves the active set), at which point it is removed so a
+// later re-entry warns again. Operator-stop suppression does NOT use this set --
+// it drops the directive, so it is inherently once-per-episode.
+const nullRoleSkipWarnedFocuses = new Set();
+// Depth of the ready-focus queue as of the most recent completed poll. Read by
+// the auto-updater's batch-safe idle predicate (auto-update-idle.ts): a drained
+// queue (0) plus no active team is a safe restart seam. Stale-but-recent is fine
+// -- the idle gate is debounced well past the poll interval.
+let lastReadyFocusCount = 0;
+/**
+ * Number of focuses with actionable (queued) work as of the last poll. Zero
+ * means the focus queue is drained. Used by the batch-safe idle predicate so a
+ * transient between-delivery gap (which still has queued focuses) does not read
+ * as idle.
+ */
+export function getReadyFocusQueueDepth() {
+    return lastReadyFocusCount;
+}
+let config = null;
+const roles = new Map();
+let pollInterval = null;
+let pollState = 'idle';
+// Polling interval in milliseconds (default: 30 seconds)
+const POLL_INTERVAL_MS = 30000;
+// Roles refresh: re-fetch from DB periodically to pick up changes
+const ROLES_REFRESH_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
+let lastRolesRefreshAt = 0;
+// Health check backoff: track consecutive failures to avoid hammering a broken API
+let healthCheckConsecutiveFailures = 0;
+const HEALTH_CHECK_MAX_SKIP_CYCLES = 10; // max backoff = 10 * 30s = 5 minutes
+// Spawn cooldown imported from dedicated module (avoids circular deps)
+import { isInSpawnCooldown } from '../spawn/spawn-cooldown.js';
+import { shouldSkipPendingSpawn, recordPendingSpawnAttempt } from '../spawn/index.js';
+import { createLogger } from '../shell/log.js';
+const log = createLogger({ module: 'listener' });
+/**
+ * Initialize the listener with configuration.
+ */
+export async function initListener(daemonConfig) {
+    config = daemonConfig;
+    // Load all roles
+    try {
+        const roleList = await getAgentRoles(config.organizationId);
+        roles.clear();
+        for (const role of roleList) {
+            roles.set(role.id, role);
+        }
+        lastRolesRefreshAt = Date.now();
+        log.info(`Loaded ${roles.size} agent roles`);
+        // Seed directive executor with current stage IDs to prevent
+        // re-firing directives for stages already processed before restart.
+        //
+        // Skip focuses with review_requested_at set: those need the
+        // reviewing-stage spawn directive to fire fresh on the next poll
+        // (the user clicked Review, the team was supposed to spawn, the
+        // pending-spawn map was wiped on restart). Without this skip, the
+        // directive sees the seeded stage as already processed and never
+        // fires -- leaving the focus stuck in `reviewing` indefinitely
+        // because nothing else routes verify deliveries to a terminal
+        // status.
+        let seededCount = 0;
+        let skippedReviewCount = 0;
+        for (const product of daemonConfig.products) {
+            try {
+                const focuses = await getActiveFocuses(daemonConfig.organizationId, product.id);
+                for (const focus of focuses) {
+                    if (!focus.current_workflow_stage_id)
+                        continue;
+                    if (focus.review_requested_at) {
+                        skippedReviewCount++;
+                        continue;
+                    }
+                    seedLastProcessedStage(focus.focus_id, focus.current_workflow_stage_id);
+                    seededCount++;
+                }
+            }
+            catch (err) {
+                log.warn(`Failed to seed directive stages for product ${product.id}: ${err.message}`);
+            }
+        }
+        if (seededCount > 0) {
+            log.info(`Seeded directive stage tracking for ${seededCount} active focuses`);
+        }
+        if (skippedReviewCount > 0) {
+            log.info(`Skipped seeding for ${skippedReviewCount} focus(es) with pending review request -- directive will re-fire`);
+        }
+    }
+    catch (error) {
+        const msg = error.message ?? '';
+        if (msg.includes('API response validation failed for agent_role_list')) {
+            throw new Error('Agent role schema mismatch -- your Telora backend edge functions need to be redeployed. '
+                + 'The daemon expects full role details (organizationId, description, allowedFilePatterns, '
+                + 'allowedTools, systemPromptTemplate, color, icon) but the backend returned partial data. '
+                + 'Redeploy your Supabase edge functions and restart the daemon.');
+        }
+        throw error;
+    }
+}
+/**
+ * Start polling for ready focuses.
+ */
+export function startDeliveryListener() {
+    if (!config) {
+        throw new Error('Listener not initialized. Call initListener first.');
+    }
+    // Initial check
+    processReadyFocuses();
+    // Start polling with error boundary — check for work and main advancement
+    // Per-product functions are called with product-scoped configs so that
+    // config.productId and config.repoPath resolve to the correct product.
+    pollInterval = safeInterval(async () => {
+        for (const product of config.products) {
+            const pc = configForProduct(config, product);
+            await ensureFocusWorktrees(pc, roles);
+            await checkForDeactivatedFocuses(pc);
+            await checkControlStateChanges(pc);
+            // Disarm reaper: clearing assigned_agent_role_id (dashboard Stop) only
+            // removes the focus from the spawn set; this stops the in-flight team via
+            // the same cooperative-stop -> SIGTERM path so Stop means stop. Runs after
+            // checkForDeactivatedFocuses (which owns genuine status!=active teardown).
+            await reapDisarmedTeams(pc);
+            await checkDeliveryAutoAdvance(pc);
+            await checkVerifyDeliveriesForOpenIssues(pc);
+            // Work-START edge: cross queued -> coding the moment a work issue is In
+            // Progress, during active execution (restores the deleted
+            // auto_advance_delivery_on_issue_active trigger via the single-writer
+            // reconciler). Runs for active-team focuses too, unlike checkDeliveryAutoAdvance.
+            await checkDeliveryWorkStart(pc);
+            // Single-writer consolidation (injection #10), SHADOW step: compute the
+            // reconciler's target for each delivery and log divergence from the live
+            // status. Writes nothing; default-OFF (opt-in via TELORA_RECONCILER_SHADOW),
+            // so this is a no-op until an operator enables it.
+            await runReconcilerShadow(pc);
+            // Nexus: pick up incoming cross-product requests and apply the accept gate.
+            await checkIncomingRequests(pc);
+            // Nexus: spawn a target-side scoping agent for each accepted, not-yet-
+            // materialized request so the receiving team authors a per-request focus
+            // (no server-side authoring, no dead-letter inbox).
+            await checkIntakePendingRequests(pc);
+            // Nexus: close the loop -- resolve done deliveries + notify blocked sources.
+            await checkResolvedRequests(pc);
+            // Nexus: clear externally-owned obstacles whose endpoint-typed request has
+            // been fulfilled (registry-shape), advancing the consumer's frontier.
+            await checkEndpointClearance(pc);
+        }
+        // Endpoint discovery (D5): org-scoped, once per cycle. Best-effort -- the
+        // daemon is the only LAN-reachable component, so it resolves the add-model
+        // form's pending {baseUrl}/models lookups. FIRE-AND-FORGET (TEL-7): never
+        // awaited, so a slow/blocked endpoint fetch can't delay spawn/merge work.
+        // Its own module-level re-entrancy guard drops overlapping cycles.
+        void checkDiscoveryRequests().catch((err) => log.warn('discovery poll failed:', err.message));
+        await processReadyFocuses();
+        await checkAndMergeCompletedDeliveries(config);
+        // checkDirectives runs syncFocusPhase (writing
+        // focus.current_workflow_stage_id) and fires stage-change directives
+        // -- including the spawn directive that starts the review team on
+        // entry to the `reviewing` phase. Run it before the cascade so phase
+        // and directive state are settled when the cascade reads them.
+        await checkDirectives(config);
+        // Pick up focuses that have a pending spawn directive but weren't
+        // surfaced by getReadyFocuses (e.g., review-stage spawns on focuses
+        // whose deliveries are all in verify).
+        await processPendingSpawnFocuses();
+        // The cascade no longer auto-completes reviews -- closing out a
+        // review and routing verify deliveries to done/verify_failed is the
+        // exclusive responsibility of focus-completion.ts's review exit
+        // handler, which gates on the exiting team's sessionType === 'review'
+        // (positive signal that an actual review ran).
+        await runCascadeChecks(config);
+        // New focus workflow lifecycle transitions (D2):
+        //   - verify -> review when pipeline_config.review.enabled
+        //   - review -> close_loop on state-based convergence
+        //   - review -> review_nonconvergent escalation past the N-iter cap
+        // Runs after the legacy cascade so the new authoritative `stage`
+        // column reflects any updates the cascade may have made.
+        await runStageLifecycleTransitions(config);
+        await checkResolvedMergeConflicts(config);
+        await detectGitStates(config);
+        await detectFocusMerges(config);
+        // NOTE: the targeted daemon-owned stall detectors (verify_failed re-code cap
+        // + review-window staleness) run INSIDE runCascadeChecks above -- they ride
+        // its existing per-focus review-handling loop (reusing the deliveries +
+        // review phase it already fetched) rather than fanning out a second pass.
+        await checkSessionHealth();
+    }, POLL_INTERVAL_MS, 'focus-poll', { skipIfRunning: true });
+    log.info(`Started focus polling (every ${POLL_INTERVAL_MS / 1000}s)`);
+}
+/**
+ * Start session listener (no-op for polling mode).
+ * Kept for API compatibility with the original implementation.
+ */
+export function startSessionListener() {
+    if (!config) {
+        throw new Error('Listener not initialized. Call initListener first.');
+    }
+    // In polling mode, session changes are handled by checking ready focuses
+    log.info('Session monitoring via polling (included in focus polling)');
+}
+export function decideFocusSpawn(gate) {
+    if (!gate.hasRole)
+        return 'skip_unknown_role';
+    if (gate.hasActiveTeam)
+        return 'skip_active_team';
+    if (gate.inSpawnCooldown)
+        return 'skip_cooldown';
+    if (gate.activeTeamCount >= gate.maxTotalSessions)
+        return 'stop_capacity';
+    return 'spawn';
+}
+/**
+ * Process any focuses ready for agent work.
+ *
+ * For each ready focus without an active team, spawns a single
+ * Agent Team that manages all deliveries within that focus.
+ * Also detects focuses that have been deactivated and shuts down
+ * their teams.
+ */
+export async function processReadyFocuses() {
+    if (!config)
+        return;
+    // Prevent concurrent processing, and skip cycles during health check backoff
+    if (pollState === 'processing' || pollState === 'backing_off') {
+        return;
+    }
+    pollState = 'processing';
+    try {
+        // Periodically refresh agent roles to pick up changes
+        if (Date.now() - lastRolesRefreshAt > ROLES_REFRESH_INTERVAL_MS) {
+            try {
+                const roleList = await getAgentRoles(config.organizationId);
+                roles.clear();
+                for (const role of roleList) {
+                    roles.set(role.id, role);
+                }
+                lastRolesRefreshAt = Date.now();
+                log.info(`Refreshed agent roles (${roles.size} roles loaded)`);
+            }
+            catch (err) {
+                log.warn(`Failed to refresh agent roles: ${err.message}`);
+            }
+        }
+        // Record activity: proves the poll ran even if no work was found
+        recordActivity();
+        // Snapshot active teams before processing (for idle detection)
+        const previouslyActiveIds = new Set(getActiveTeams().keys());
+        // Deactivation detection is now handled by checkForDeactivatedFocuses()
+        // in the poll loop (called before processReadyFocuses).
+        // Get ready focuses across all configured products
+        const readyFocuses = [];
+        for (const product of config.products) {
+            try {
+                const focuses = await getReadyFocuses(config.organizationId, product.id);
+                readyFocuses.push(...focuses);
+            }
+            catch (err) {
+                log.warn(`Failed to fetch ready focuses for product ${product.id}: ${err.message}`);
+            }
+        }
+        // Publish the queue depth for the auto-updater's batch-safe idle predicate.
+        // Set before any early-return below so a drained queue is observable.
+        lastReadyFocusCount = readyFocuses.length;
+        // Track which focuses are ready this cycle (for idle logging)
+        const readyFocusIds = new Set(readyFocuses.map(s => s.focus_id));
+        // Idle queue logging: detect focuses that were previously active
+        // but now have no ready deliveries. Only log on state change.
+        for (const focusId of previouslyActiveIds) {
+            if (!readyFocusIds.has(focusId) && !hasActiveTeam(focusId) && !idleLoggedFocuses.has(focusId)) {
+                const nextPollSec = POLL_INTERVAL_MS / 1000;
+                log.info(`Focus queue idle: "${focusId}" -- no actionable deliveries, next poll in ${nextPollSec}s`);
+                idleLoggedFocuses.add(focusId);
+            }
+        }
+        if (readyFocuses.length === 0) {
+            return;
+        }
+        // Intake drain (auto-update delivery C): a pending update has been stale
+        // past threshold while the daemon stays busy, so we stop accepting new focus
+        // teams to let the current batch become the safe seam. Active teams continue
+        // to completion; we simply do not spawn more. The held queue does not block
+        // the batch boundary because isBatchSafeIdle honors isIntakeDraining().
+        if (isIntakeDraining()) {
+            log.info(`[listener] Intake drained for pending update -- holding ${readyFocuses.length} ready focus(es); no new teams will spawn`);
+            return;
+        }
+        const productLabel = config.products.length > 1
+            ? ` across ${config.products.length} product(s)`
+            : '';
+        log.info(`Found ${readyFocuses.length} ready focuses${productLabel}`);
+        for (const focus of readyFocuses) {
+            const role = roles.get(focus.assigned_agent_role_id);
+            // Resolve the per-focus spawn-gate decision (pure; see decideFocusSpawn).
+            // The capacity input is the LIVE team count sampled this iteration, so a
+            // spawn earlier in this loop is reflected for the next focus.
+            const action = decideFocusSpawn({
+                hasRole: role !== undefined,
+                hasActiveTeam: hasActiveTeam(focus.focus_id),
+                inSpawnCooldown: isInSpawnCooldown(focus.focus_id),
+                activeTeamCount: getActiveTeamCount(),
+                maxTotalSessions: config.maxTotalSessions,
+            });
+            if (action === 'skip_unknown_role') {
+                log.error(`Unknown agent role: ${focus.assigned_agent_role_id}`);
+                continue;
+            }
+            if (action === 'skip_active_team') {
+                // Focus is active -- clear idle state so we re-log if it goes idle again
+                idleLoggedFocuses.delete(focus.focus_id);
+                // A re-arm flag may have landed while a team is up. Do NOT clear it here:
+                // the answer is consumed only at (re)spawn time via the escalation.answers
+                // resolver, and a still-live team does not re-run assembly mid-session
+                // (the wake-message handoff does not carry answers). Leaving the flag set
+                // lets the force-spawn deliver the answer once this team exits; clearing
+                // it now would strand the answer. The clear happens on the force-spawn
+                // below (one answer -> one re-spawn).
+                continue;
+            }
+            // Skip focuses that were recently torn down (spawn cooldown).
+            if (action === 'skip_cooldown') {
+                continue;
+            }
+            // Total capacity reached -- stop the whole loop, not just this focus.
+            if (action === 'stop_capacity') {
+                log.info(`Total session limit reached, stopping`);
+                break;
+            }
+            // action === 'spawn'. role is guaranteed defined (hasRole was true);
+            // this guard narrows the type and is otherwise unreachable.
+            if (!role)
+                continue;
+            const isRearm = focus.answer_rearm_requested_at != null;
+            // Clear idle state before spawn attempt -- if spawn succeeds,
+            // the focus is active. If it skips (no actionable deliveries),
+            // spawnFocusTeam logs the skip and we mark it idle here.
+            const wasIdle = idleLoggedFocuses.has(focus.focus_id);
+            idleLoggedFocuses.delete(focus.focus_id);
+            // Use product-scoped config so the team uses the correct repoPath
+            const productEntry = focus.product_id ? findProduct(config, focus.product_id) : undefined;
+            const spawnConfig = productEntry ? configForProduct(config, productEntry) : config;
+            // Spawn a focus team (one team per focus). forceSpawn lets a re-armed
+            // focus spawn past findActionableDeliveries' 'skip' to consume the
+            // pending escalation answer.
+            // Audit-phase focus (explicit read_only=true OR the second structural
+            // signal: audit_origin && not-yet-ratified, TEL-3) spawns read-only, so a
+            // flag-absent audit focus is not driven into scoping/write/commit ahead of
+            // ratification (2f253da6). See isAuditPhaseFocusRow.
+            await spawnFocusTeam({ config: spawnConfig, focusId: focus.focus_id, focusName: focus.focus_name, role, pipelineConfig: focus.pipeline_config, readOnly: isAuditPhaseFocusRow(focus), lastClaudeSessionId: focus.last_claude_session_id, claudeSessionIds: focus.claude_session_ids, engineOverride: focus.engine_override, localModelOverride: focus.local_model_override, orgDefaultEngine: focus.org_default_engine, pinnedBranch: focus.branch_name, forceSpawn: isRearm });
+            // Clear the re-arm flag only once a team is actually live to consume the
+            // answer: one answer -> one re-spawn. If the force-spawn did NOT produce an
+            // active team (worktree/governor failure, etc.), leave the flag set so a
+            // later poll retries delivery rather than stranding the answer. (Cooldown
+            // and capacity exit above without reaching here, so they also keep the
+            // flag.) Done before the idle check below so a consumed re-arm is not
+            // re-surfaced next poll.
+            if (isRearm && hasActiveTeam(focus.focus_id)) {
+                await clearAnswerRearm(focus.focus_id).catch((err) => log.warn(`Failed to clear answer re-arm for "${focus.focus_name}": ${err.message}`));
+            }
+            // If the spawn was skipped (no active team after spawn), mark as idle
+            if (!hasActiveTeam(focus.focus_id) && !wasIdle) {
+                const nextPollSec = POLL_INTERVAL_MS / 1000;
+                log.info(`Focus queue idle: "${focus.focus_name}" -- no actionable deliveries after pre-spawn check, next poll in ${nextPollSec}s`);
+                idleLoggedFocuses.add(focus.focus_id);
+            }
+        }
+    }
+    catch (error) {
+        log.error('Error processing ready focuses:', error);
+    }
+    finally {
+        pollState = healthCheckConsecutiveFailures > 0 ? 'backing_off' : 'idle';
+    }
+}
+/**
+ * Spawn teams for focuses that have a pending spawn directive but were
+ * not surfaced by getReadyFocuses.
+ *
+ * getReadyFocuses (daemon-focus-handlers.ts) only returns focuses with
+ * queued/coding deliveries (or zero deliveries). A review-stage spawn
+ * directive on a focus whose deliveries are all in verify never makes
+ * it to processReadyFocuses -- the pending directive sits forever and
+ * the team never starts. This function bridges that gap: scan the
+ * pending-spawn map directly and spawn for any focus that's not
+ * already running.
+ */
+export async function processPendingSpawnFocuses() {
+    if (!config)
+        return;
+    if (isDaemonShuttingDown())
+        return;
+    const pendingIds = getPendingSpawnFocusIds().filter(id => !hasActiveTeam(id));
+    if (pendingIds.length === 0)
+        return;
+    // Fetch focus details for all configured products. getActiveFocuses
+    // returns the metadata spawnFocusTeam needs.
+    const focusDetailsById = new Map();
+    // Whether ANY product's getActiveFocuses read failed this tick. A fetch failure
+    // makes the active set incomplete, so a pending focus can look absent purely
+    // because its product's read failed -- absence is only trustworthy when this is
+    // false. Gates the zombie-directive reap below.
+    let anyFetchFailed = false;
+    for (const product of config.products) {
+        try {
+            const focuses = await getActiveFocuses(config.organizationId, product.id);
+            for (const f of focuses) {
+                if (pendingIds.includes(f.focus_id)) {
+                    focusDetailsById.set(f.focus_id, f);
+                }
+            }
+        }
+        catch (err) {
+            anyFetchFailed = true;
+            log.warn(`[listener] processPendingSpawnFocuses: failed to fetch active focuses for product ${product.id}: ${err.message}`);
+        }
+    }
+    for (const focusId of pendingIds) {
+        const focus = focusDetailsById.get(focusId);
+        if (!focus) {
+            // Focus is absent from the active set. If the read was complete this tick
+            // (no fetch failure), the focus has genuinely left the active set -- its
+            // directive is a zombie: reap it once instead of retrying forever. On a
+            // fetch-failure tick the absence is untrustworthy, so keep retrying.
+            if (shouldReapPendingSpawnDirective({ anyFetchFailed, focusPresentInActiveSet: false })) {
+                clearPendingSpawnDirective(focusId);
+                // Focus left the active set -- the blocked episode is over. Clear its
+                // once-per-episode warn marker so a future re-entry warns again.
+                nullRoleSkipWarnedFocuses.delete(focusId);
+                log.info(`[listener] Dropping stale spawn directive for focus ${focusId.slice(0, 8)}: ` +
+                    `confirmed absent from every product's active set (focus completed/deactivated).`);
+            }
+            else {
+                log.warn(`[listener] Pending spawn directive for focus ${focusId.slice(0, 8)} but focus not found in active set; ` +
+                    `active-set read incomplete this tick (fetch failure) -- retrying next poll.`);
+            }
+            continue;
+        }
+        let role;
+        if (!focus.assigned_agent_role_id) {
+            // A null assigned_agent_role_id now means ONE OF TWO things, and they are
+            // NOT interchangeable:
+            //   - operator_stopped_at set  => an operator pulled the Play toggle to
+            //     halt the focus. Authoritative: it wins over the review fallback.
+            //   - operator_stopped_at null => auto_terminate_focus_team() cleared the
+            //     role at completion (lifecycle). Here the review fallback applies:
+            //     a review is a SECOND team that must spawn AFTER completion; a coding
+            //     directive is the intended off-state and must NOT auto-spawn.
+            // decideNullRoleSpawn disambiguates via operatorStopped; the listener then
+            // acts on the decision (drop the directive on a stop, throttle the
+            // off-state warning, or spawn the lifecycle review fallback).
+            const operatorStopped = !!focus.operator_stopped_at;
+            const pending = getPendingSpawnDirective(focus.focus_id);
+            const decision = decideNullRoleSpawn({
+                sessionType: pending?.sessionType,
+                fallbackRole: resolveReviewerFallbackRole(roles.values()),
+                operatorStopped,
+            });
+            if (decision.action === 'skip') {
+                if (operatorStopped) {
+                    // Operator STOP wins over the review fallback. Drop any directive
+                    // queued while stopped so it does not silently survive to resume and
+                    // fire the path the stop was meant to prevent. Dropping also removes
+                    // the focus from the pending set, so this suppression is logged once
+                    // per focus (per stop), never once per poll.
+                    if (pending)
+                        clearPendingSpawnDirective(focus.focus_id);
+                    nullRoleSkipWarnedFocuses.delete(focus.focus_id);
+                    log.info(`[listener] Focus ${focusId.slice(0, 8)} ("${focus.focus_name}") is held by an operator stop; ` +
+                        `suppressing the queued ${pending?.sessionType ?? 'spawn'} directive (dropped, not carried to resume).`);
+                    continue;
+                }
+                // Coding off-state (Play/queue toggle cleared, no operator stop): the
+                // directive legitimately stays queued. Bound the warning to once per
+                // blocked episode so a stopped focus does not spin-log every 30s poll.
+                if (shouldWarnNullRoleSkip(nullRoleSkipWarnedFocuses, focus.focus_id)) {
+                    log.warn(`[listener] Pending spawn directive for focus ${focusId.slice(0, 8)} ("${focus.focus_name}") but no assigned_agent_role_id; ` +
+                        `skipping spawn (coding off-state). Suppressing further per-poll warnings until it resumes.`);
+                }
+                continue;
+            }
+            // Past the skip paths: this is a genuine lifecycle clear (operatorStopped
+            // is false here). The episode is over either way, so clear the marker.
+            nullRoleSkipWarnedFocuses.delete(focus.focus_id);
+            if (decision.action === 'clear') {
+                // Review strand with no resolvable fallback role: drop the directive so
+                // the stranded-review re-fire suppression (directive-executor) cannot
+                // spin-log forever. review_window_stalled remains the escalation path,
+                // and now fires promptly rather than after 6h of churn.
+                clearPendingSpawnDirective(focus.focus_id);
+                log.warn(`[listener] Stranded review directive for focus ${focusId.slice(0, 8)} ("${focus.focus_name}") has a null assigned_agent_role_id ` +
+                    `and no seeded '${DEFAULT_REVIEWER_ROLE_NAME}' fallback role resolved -- dropping the directive so it stops re-firing; ` +
+                    `review_window_stalled will escalate.`);
+                continue;
+            }
+            role = decision.role;
+            // Reachable only when operatorStopped is false (an operator stop takes the
+            // skip path above), so "(coding team completed)" is a true provenance
+            // claim here rather than an assumption stamped on every null-role spawn.
+            log.info(`[listener] Review directive for focus ${focusId.slice(0, 8)} ("${focus.focus_name}") has a null assigned_agent_role_id ` +
+                `(coding team completed); spawning review with fallback role "${role.name}".`);
+        }
+        else {
+            // Focus has a role again -- any prior null-role blocked episode is over.
+            nullRoleSkipWarnedFocuses.delete(focus.focus_id);
+            role = roles.get(focus.assigned_agent_role_id);
+            if (!role) {
+                log.warn(`[listener] Pending spawn directive for focus ${focusId.slice(0, 8)} ("${focus.focus_name}") references unknown role ${focus.assigned_agent_role_id}; ` +
+                    `skipping spawn.`);
+                continue;
+            }
+        }
+        // Park focuses with an unhealed team_failure escalation BEFORE attempting
+        // the spawn. spawnFocusTeam applies the same guard, but it returns after
+        // the guard fires without consuming the pending directive -- so the
+        // directive stays queued and this loop re-attempts (and the guard re-logs)
+        // every poll. Checking here skips the misleading "Spawning team" log and
+        // the wasted spawn call; the directive intentionally stays queued so the
+        // (re)review resumes once a human resolves the escalation. The guard
+        // throttles its own log to once per blocked episode.
+        if (await applyRespawnGuard(focus.focus_id, focus.focus_name)) {
+            continue;
+        }
+        // Spawn cooldown: this path spawns teams for focuses that getReadyFocuses
+        // does NOT surface -- focuses with no actionable/queued deliveries (e.g. a
+        // reviewing-stage spawn over a focus whose deliveries are all in verify).
+        // Such a team idle-exits if its directive can't make progress; without a
+        // gate the directive re-fires every poll and the daemon respawns an
+        // immediately-idle team every cycle (the reinforcing auto-review/idle-spawn
+        // loop). See pending-spawn-guard.ts.
+        if (shouldSkipPendingSpawn(focus.focus_id)) {
+            continue;
+        }
+        if (getActiveTeamCount() >= config.maxTotalSessions) {
+            log.info(`Total session limit reached, deferring pending spawn for "${focus.focus_name}"`);
+            break;
+        }
+        const productEntry = focus.product_id ? findProduct(config, focus.product_id) : undefined;
+        const spawnConfig = productEntry ? configForProduct(config, productEntry) : config;
+        log.info(`[listener] Spawning team for focus "${focus.focus_name}" via pending spawn directive ` +
+            `(no actionable deliveries, but directive is queued)`);
+        // Audit-phase => read-only spawn (see the processReadyFocuses spawn above).
+        // The pending-spawn focus comes from getActiveFocuses, which carries
+        // audit_origin + ratified_at, so the second signal (TEL-3) resolves here too.
+        await spawnFocusTeam({
+            config: spawnConfig,
+            focusId: focus.focus_id,
+            focusName: focus.focus_name,
+            role,
+            pipelineConfig: focus.pipeline_config,
+            readOnly: isAuditPhaseFocusRow(focus),
+            lastClaudeSessionId: null,
+            claudeSessionIds: focus.claude_session_ids,
+            engineOverride: focus.engine_override,
+            localModelOverride: focus.local_model_override,
+            orgDefaultEngine: focus.org_default_engine,
+            pinnedBranch: focus.branch_name,
+        });
+        // Record a teardown so repeated spawns through this no-actionable-work path
+        // back off exponentially instead of recurring every poll. A team that
+        // genuinely makes progress moves the focus into a state getReadyFocuses
+        // surfaces (and clearSpawnCooldown can reset it); a team that idle-exits is
+        // rate-limited by the growing cooldown. This bounds spawn count on a
+        // wedged-in-verify focus. See pending-spawn-guard.ts.
+        recordPendingSpawnAttempt(focus.focus_id);
+    }
+}
+/**
+ * Check that every session recorded as 'starting' or 'running' in the DB
+ * has a corresponding active team in memory.
+ *
+ * If a session has been in a live status for more than 2 minutes but no
+ * active team claims it (e.g. the process was OOM-killed or the close
+ * handler failed to update the DB), the session is marked as 'failed' so
+ * subsequent poll cycles can respawn the focus.
+ */
+export async function checkSessionHealth() {
+    const GRACE_PERIOD_MS = 2 * 60 * 1000; // 2 minutes
+    // Backoff: skip this cycle if we've had consecutive failures.
+    // After N failures, skip N poll cycles before retrying (capped at max).
+    if (healthCheckConsecutiveFailures > 0) {
+        // Use the failure count as the number of cycles to skip
+        const skipCycles = Math.min(healthCheckConsecutiveFailures, HEALTH_CHECK_MAX_SKIP_CYCLES);
+        healthCheckConsecutiveFailures++;
+        if (healthCheckConsecutiveFailures % skipCycles !== 0) {
+            return; // skip this cycle
+        }
+        log.info(`[health] Retrying after ${healthCheckConsecutiveFailures} consecutive failures (backoff: every ${skipCycles} cycles)`);
+    }
+    // Aggregate active sessions across all configured products
+    const activeSessions = [];
+    try {
+        for (const product of (config?.products ?? [])) {
+            const sessions = await getActiveSessions(product.id);
+            activeSessions.push(...sessions);
+        }
+        // Reset backoff on success
+        if (healthCheckConsecutiveFailures > 0) {
+            log.info(`[health] Session health check recovered after ${healthCheckConsecutiveFailures} failures`);
+            healthCheckConsecutiveFailures = 0;
+            pollState = 'idle';
+        }
+    }
+    catch (err) {
+        healthCheckConsecutiveFailures++;
+        pollState = 'backing_off';
+        log.warn(`[health] Failed to fetch active sessions (failure #${healthCheckConsecutiveFailures}): ${err.message}`);
+        return;
+    }
+    if (activeSessions.length === 0) {
+        return;
+    }
+    log.info(`[health] Checking ${activeSessions.length} active session(s) for orphaned processes`);
+    // Build a set of all leadSessionIds currently tracked in memory
+    const activeTeams = getActiveTeams();
+    const trackedSessionIds = new Set();
+    for (const team of activeTeams.values()) {
+        if (team.leadSessionId) {
+            trackedSessionIds.add(team.leadSessionId);
+        }
+    }
+    const now = Date.now();
+    const staleSessionIds = [];
+    for (const session of activeSessions) {
+        // Skip if this session is tracked by an active in-memory team
+        if (trackedSessionIds.has(session.id)) {
+            continue;
+        }
+        // Apply grace period: ignore sessions that started very recently
+        // (in case the team is still being set up and hasn't registered yet)
+        const startedAt = session.started_at ?? session.queued_at;
+        if (!startedAt) {
+            // Cannot determine session age — skip conservatively
+            continue;
+        }
+        const sessionAgeMs = now - new Date(startedAt).getTime();
+        if (sessionAgeMs < GRACE_PERIOD_MS) {
+            continue;
+        }
+        // PID liveness check: if the session's process is still alive,
+        // skip orphan detection. This prevents false positives when the
+        // in-memory tracking is stale but the process is genuinely running.
+        //
+        // Note: full re-registration into activeTeams is not attempted here because
+        // FocusTeamState requires stdin handles, execution config, pipeline config,
+        // and other fields that cannot be reconstructed from a DB session row alone.
+        // The process will continue running; the next daemon restart will recover state.
+        const pid = session.pid;
+        if (pid != null) {
+            try {
+                process.kill(pid, 0); // signal 0 = test if process exists
+                log.warn(`[health] Session ${session.id} not tracked in-memory but PID ${pid} is alive — skipping orphan detection` +
+                    ` (focus=${session.focus_id ?? 'none'})`);
+                continue;
+            }
+            catch (err) {
+                // process.kill throws if PID does not exist — proceed to mark as orphaned
+                log.debug('process.kill throws if PID does not exist — proceed to mark as orphaned', { error: String(err?.message ?? err) });
+            }
+        }
+        staleSessionIds.push(session.id);
+        log.warn(`[health] Orphaned session detected: ${session.id} ` +
+            `(status=${session.status}, age=${Math.round(sessionAgeMs / 1000)}s, ` +
+            `focus=${session.focus_id ?? 'none'}, delivery=${session.delivery_id ?? 'none'})`);
+    }
+    if (staleSessionIds.length === 0) {
+        return;
+    }
+    log.info(`[health] Marking ${staleSessionIds.length} orphaned session(s) as failed`);
+    const updateResults = await Promise.allSettled(staleSessionIds.map(sessionId => withRetry(() => updateSession(sessionId, {
+        status: 'failed',
+        exit_reason: 'Session health check: no active team found for running session',
+        ended_at: new Date().toISOString(),
+    }), { maxAttempts: 3, baseDelayMs: 1000, label: 'health-check-session-update' })));
+    for (let i = 0; i < updateResults.length; i++) {
+        const result = updateResults[i];
+        if (result.status === 'rejected') {
+            log.error(`[health] Failed to mark session ${staleSessionIds[i]} as failed: ${result.reason.message}`);
+        }
+        else {
+            log.info(`[health] Marked session ${staleSessionIds[i]} as failed`);
+        }
+    }
+}
+/**
+ * Stop all listeners.
+ */
+export async function stopListeners() {
+    if (pollInterval) {
+        clearInterval(pollInterval);
+        pollInterval = null;
+    }
+    log.info('Stopped polling');
+}
+/**
+ * Refresh roles from API.
+ */
+export async function refreshRoles() {
+    if (!config)
+        return;
+    const roleList = await getAgentRoles(config.organizationId);
+    roles.clear();
+    for (const role of roleList) {
+        roles.set(role.id, role);
+    }
+    lastRolesRefreshAt = Date.now();
+    log.info(`Refreshed ${roles.size} agent roles`);
+}
+/**
+ * Register the poll-loop trigger with the poll-trigger leaf so completion
+ * handling can nudge an immediate check for ready focuses after a session
+ * completes (to auto-advance to the next delivery) WITHOUT importing this
+ * module -- a direct completion -> listener import would close a static import
+ * cycle. No-ops during daemon shutdown to prevent spawn attempts after the
+ * resource governor has been shut down.
+ */
+registerPollTrigger(() => {
+    if (isDaemonShuttingDown())
+        return;
+    processReadyFocuses();
+});
+// Note: Detection of completed guard agents and re-evaluation of paused deliveries
+// is handled by the Human Routing UI. When a human makes a routing decision,
+// the UI updates the transition_blocks.decision_path and sets the delivery back to 'queued',
+// which the normal poll loop picks up. For spawn_agent triggers, the spawned agent's
+// completion triggers a re-poll via triggerCheck(), and the delivery will be re-evaluated
+// on the next spawn cycle since it remains in 'paused' status until the human routes it.
+//# sourceMappingURL=listener.js.map