crewly 1.6.4 → 1.7.0

package/dist/backend/backend/src/services/reconciler/reconciler-data-provider.js

@@ -17,11 +17,100 @@ import { AgentSuspendService } from '../agent/agent-suspend.service.js';
 import { LoggerService } from '../core/logger.service.js';
 import { TokenUsageService } from '../monitoring/token-usage.service.js';
 import { isUnderMemoryPressure, getMemoryStats } from '../core/system-health.util.js';
+import { WEB_CONSTANTS, AGENT_SUSPEND_CONSTANTS } from '../../constants.js';
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
 /** How long an agent can be unseen before we consider it stale (5 min). */
 const AGENT_STALE_THRESHOLD_MS = 5 * 60 * 1000;
+/**
+ * Heuristic: detect "storage not yet hydrated" errors so the data
+ * provider can demote them from `error` to `debug` log level.
+ *
+ * Symptom in production (F-CYCLE7-3, 2026-05-07 11:19→11:21Z): when
+ * the Reconciler's 10s fast-loop runs before the Task Pool's
+ * `pool.json` finishes loading after a SQLite-related restart, an
+ * inner method calls `.filter()` on a still-undefined array slot. The
+ * thrown TypeError carries the canonical V8 message
+ * "Cannot read properties of undefined (reading 'filter')". The catch
+ * already returns `[]`, but it logs at `error` — every 10s for ~110s
+ * — flooding logs and hiding real errors.
+ *
+ * **F-CYCLE7-3-FU (2026-05-07, PR review #511 follow-up):** The original
+ * implementation enumerated `'filter'|'find'|'map'|'forEach'|'length'`
+ * in the message. That whitelist was brittle — adjacent reconciler /
+ * future-consumer code reaches for `.some()` / `.every()` / `.reduce()` /
+ * `.includes()` / `.indexOf()` / `.slice()` / property accesses that
+ * throw the SAME V8 TypeError shape during the same hydration window
+ * but are silently dropped from this classifier, re-introducing the
+ * noise pattern this PR is trying to silence.
+ *
+ * The fix mirrors the discipline used in
+ * `backend/src/utils/native-binding.utils.ts#isNativeArchMismatchError`
+ * (F-CYCLE7-1): match the **structural** error shape, not enumerated
+ * call sites.
+ *
+ * Contract:
+ *   1. Must be a real `TypeError` (not just any thrown value with a
+ *      matching string — that narrows the false-positive surface).
+ *   2. Message must carry both readonly anchors of the V8 shape:
+ *      `"Cannot read"` AND `"of undefined"`. The middle (`property` /
+ *      `properties of undefined (reading 'X')` / older `property 'X'
+ *      of undefined`) varies between Node versions; we don't anchor
+ *      on it.
+ *
+ * Negative cases this MUST reject (all tested):
+ *   - `Cannot read properties of null (reading 'filter')` — a null
+ *     pointer is a different bug class from hydration-not-ready.
+ *   - `TypeError: foo is not a function` — symptom of a missing API.
+ *   - Non-TypeError throws (`new Error('Cannot read … of undefined')`)
+ *     — strings can match by accident; the type narrow guards.
+ *   - `'Database connection refused'` — genuine downstream failure.
+ *
+ * @param error - The thrown value to classify. Anything not a
+ *   TypeError fails immediately, so callers can pass `error: unknown`
+ *   without pre-checks.
+ * @returns True iff the error is the V8 hydration-not-ready shape.
+ */
+function isStorageNotReadyError(error) {
+    if (!(error instanceof TypeError))
+        return false;
+    const lower = error.message.toLowerCase();
+    // The two readonly anchors of the V8 / Node error shape, present
+    // across all engine versions and all property/method accesses on
+    // an undefined value:
+    //   modern V8: "Cannot read properties of undefined (reading 'X')"
+    //   older V8:  "Cannot read property 'X' of undefined"
+    return lower.includes('cannot read') && lower.includes('of undefined');
+}
+// ---------------------------------------------------------------------------
+// Tunables
+// ---------------------------------------------------------------------------
+/**
+ * Cap on concurrent active agents while the system is under memory
+ * pressure. Named `WAKE_FLOOR` for historical reasons — the value
+ * acts as a CEILING on wake actions under pressure, not a guaranteed
+ * floor. The reconciler does not proactively bring the active count
+ * up to this value; it only permits wakes when `activeCount < N` and
+ * blocks them otherwise.
+ *
+ * Behaviour:
+ *  - `activeCount <  N` AND memory pressure → wake allowed (keeps the
+ *    system minimally productive instead of fully wedged).
+ *  - `activeCount >= N` AND memory pressure → wake blocked (prevents
+ *    an OOM cascade by capping additional spawns during a crisis).
+ *  - No memory pressure → this gate is not consulted.
+ *
+ * History: an earlier implementation blocked EVERY wake under memory
+ * pressure, which wedged the system on 2026-05-13 (6+ hours, free RAM
+ * 16-33 MB, queued WIs piling up). On 2026-05-14 the system stalled
+ * again — this gate worked as designed, but `IdleDetectionService`
+ * silently stopped releasing idle agents, so `activeCount` stayed
+ * above N for ~20 hours. The cap itself is not the bug; the absence
+ * of forward progress when the cap is held is. See the heartbeat
+ * additions in `idle-detection.service.ts`.
+ */
+export const WAKE_FLOOR_UNDER_PRESSURE = 3;
 // ---------------------------------------------------------------------------
 // LiveReconcilerDataProvider
 // ---------------------------------------------------------------------------
@@ -42,10 +131,46 @@ const AGENT_STALE_THRESHOLD_MS = 5 * 60 * 1000;
 export class LiveReconcilerDataProvider {
     logger;
     storage;
+    eventBus = null;
+    // Injected at boot time by `index.ts` so eviction can terminate an
+    // agent's full session (monitors + tmux + in-process runtime). The
+    // dep is optional — tests that don't exercise the pressure path leave
+    // it null, which makes `evictIdleAgent` fall back to "no candidate"
+    // and the wake-pressure path skips as before.
+    agentRegistration = null;
+    // Memory-pressure broadcast state. Per-instance to keep counters
+    // isolated, but the publish throttle ensures we don't flood orc even
+    // if multiple providers exist (each will throttle independently and
+    // EventBus deduplicates on event id).
+    consecutivePressureSkips = 0;
+    lastPressureNotifiedAt = 0;
     constructor() {
         this.logger = LoggerService.getInstance().createComponentLogger('ReconcilerDataProvider');
         this.storage = StorageService.getInstance();
     }
+    /**
+     * Inject the EventBus used to broadcast `system:memory_pressure` to
+     * orc. Optional — when not set, the reconciler still functions but
+     * no user-facing notification is emitted. Called once from the
+     * server bootstrap after both services are constructed.
+     *
+     * @param eventBus - The EventBusService singleton wired in `index.ts`
+     */
+    setEventBus(eventBus) {
+        this.eventBus = eventBus;
+    }
+    /**
+     * Inject the AgentRegistrationService so the memory-pressure eviction
+     * path can terminate idle agents (the same primitive
+     * `IdleDetectionService` uses). Optional — when not wired, eviction
+     * is disabled and the reconciler falls back to the prior skip-on-floor
+     * behaviour.
+     *
+     * @param svc - AgentRegistrationService instance from the bootstrap
+     */
+    setAgentRegistrationService(svc) {
+        this.agentRegistration = svc;
+    }
     /**
      * Returns all non-terminal WorkItems from the Task Pool.
      * Non-terminal means items that are not 'done' or 'cancelled'.
@@ -111,17 +236,41 @@ export class LiveReconcilerDataProvider {
     /**
      * Returns all active/expiring TaskClaims.
      *
-     * @returns Active claims
+     * **F-CYCLE7-3 (2026-05-07):** Returns `[]` defensively if the pool
+     * returns a non-array (e.g. partial post-restart hydration where
+     * `pool.json` is missing the `claims` field). Storage-not-ready is
+     * logged at `debug`, not `error`, to avoid the post-restart error
+     * storm seen at 11:19→11:21Z. Genuine failures (thrown errors) keep
+     * their `error`-level log.
+     *
+     * @returns Active claims (always an array)
      */
     async getActiveClaims() {
         try {
             const pool = TaskPoolService.getInstance();
-            return await pool.getActiveClaims();
+            const claims = await pool.getActiveClaims();
+            if (!Array.isArray(claims)) {
+                this.logger.debug('Active claims unavailable (storage not yet hydrated)', {
+                    received: typeof claims,
+                });
+                return [];
+            }
+            return claims;
         }
         catch (error) {
-            this.logger.error('Failed to get active claims', {
-                error: error instanceof Error ? error.message : String(error),
-            });
+            // Storage-not-ready manifests as ".filter() / .some() / etc. on
+            // undefined" during the post-restart hydration window. The
+            // classifier checks `instanceof TypeError` + the V8 message
+            // shape — see the doc-comment on `isStorageNotReadyError` for
+            // why we no longer enumerate method names.
+            if (isStorageNotReadyError(error)) {
+                this.logger.debug('Active claims unavailable (storage not yet hydrated)', {
+                    error: error.message,
+                });
+                return [];
+            }
+            const msg = error instanceof Error ? error.message : String(error);
+            this.logger.error('Failed to get active claims', { error: msg });
             return [];
         }
     }
@@ -156,6 +305,40 @@ export class LiveReconcilerDataProvider {
                     healthMap.set(member.sessionName, health);
                 }
             }
+            // Add the orchestrator. orc is a virtual team member — it does NOT
+            // appear in `storage.getTeams()`, so the loop above misses it. Without
+            // this entry, any WorkItem with `target=crewly-orc` that transitions
+            // to `running` is mis-identified by `detectStuckWorkItems` as having
+            // a "missing agent", and gets force-demoted back to `blocked`. The
+            // dogfood symptom (2026-05-09): a Plan WI auto-claimed by orc bounced
+            // running → blocked → running → blocked in a wedged loop, the chained
+            // Execute + Review never unlocked, and the parent Slack Request
+            // emitted hours of identical "still 3 blocked" heartbeats.
+            //
+            // We treat any orchestrator status persisted via OrchestratorStatus
+            // as `active` for health-map purposes — the reconciler only needs
+            // "exists / does not exist" granularity here. If the orc isn't
+            // running we'd rather skip the entry than fabricate a stale one,
+            // so we honour the persisted agentStatus when available.
+            try {
+                const orcStatus = await this.storage.getOrchestratorStatus();
+                if (orcStatus?.sessionName) {
+                    healthMap.set(orcStatus.sessionName, {
+                        sessionName: orcStatus.sessionName,
+                        status: this.mapAgentStatus(orcStatus.agentStatus),
+                        lastSeenAt: orcStatus.updatedAt,
+                        role: 'orchestrator',
+                        tags: [],
+                        activeWorkItemCount: 0,
+                        // teamId/memberId intentionally undefined — orc is virtual.
+                    });
+                }
+            }
+            catch (orcErr) {
+                this.logger.debug('Failed to add orchestrator to health map (non-fatal)', {
+                    error: orcErr instanceof Error ? orcErr.message : String(orcErr),
+                });
+            }
             // Enrich with active claim counts from the pool
             try {
                 const pool = TaskPoolService.getInstance();
@@ -187,7 +370,11 @@ export class LiveReconcilerDataProvider {
         try {
             if (correction.entityType === 'work_item') {
                 const pool = TaskPoolService.getInstance();
-                await pool.updateItemStatus(correction.entityId, correction.newState);
+                // Forward the reconciler's reason (e.g. "queued for 61 minutes
+                // without pickup", "Cascade cancel: ancestor failed") through
+                // to the WorkItem so it persists alongside the status flip.
+                // The activity timeline reads this field for cancelled items.
+                await pool.updateItemStatus(correction.entityId, correction.newState, 'system', correction.reason);
                 this.logger.info('Applied work item correction', {
                     workItemId: correction.entityId,
                     from: correction.previousState,
@@ -295,17 +482,35 @@ export class LiveReconcilerDataProvider {
      * Returns all available (queued, unclaimed) WorkItems from the Task Pool.
      * Used by Hybrid Wake to find items that need agents.
      *
-     * @returns Available pool items
+     * **F-CYCLE7-3 (2026-05-07):** Returns `[]` defensively if the pool
+     * returns a non-array (e.g. partial post-restart hydration where
+     * `pool.json` is missing the `workItems` field). Storage-not-ready is
+     * logged at `debug`, not `error`, to avoid the post-restart error
+     * storm seen at 11:19→11:21Z.
+     *
+     * @returns Available pool items (always an array)
      */
     async getAvailablePoolItems() {
         try {
             const pool = TaskPoolService.getInstance();
-            return await pool.getAvailableItems();
+            const items = await pool.getAvailableItems();
+            if (!Array.isArray(items)) {
+                this.logger.debug('Available pool items unavailable (storage not yet hydrated)', {
+                    received: typeof items,
+                });
+                return [];
+            }
+            return items;
         }
         catch (error) {
-            this.logger.error('Failed to get available pool items', {
-                error: error instanceof Error ? error.message : String(error),
-            });
+            if (isStorageNotReadyError(error)) {
+                this.logger.debug('Available pool items unavailable (storage not yet hydrated)', {
+                    error: error.message,
+                });
+                return [];
+            }
+            const msg = error instanceof Error ? error.message : String(error);
+            this.logger.error('Failed to get available pool items', { error: msg });
             return [];
         }
     }
@@ -319,21 +524,350 @@ export class LiveReconcilerDataProvider {
      * @param action - The wake action to execute
      * @returns True if the wake was initiated successfully
      */
-    async executeWakeAction(action) {
-        const { agentSessionName, strategy } = action;
-        // Skip wake action under system memory pressure (>90% used).
-        // Prevents spawning new agent processes when the system is already low on memory,
-        // which would cause OOM → kill → reconciler wakes again → OOM loop.
-        if (isUnderMemoryPressure()) {
-            const stats = getMemoryStats();
-            this.logger.warn('Skipping wake action due to memory pressure', {
-                agent: agentSessionName,
-                strategy,
+    /**
+     * Count agent sessions currently in an alive state. Used by the
+     * memory-pressure gate in {@link executeWakeAction} to decide whether
+     * a new wake would push us past the concurrency floor.
+     *
+     * Counts `'active'`, `'started'`, and `'starting'` — anything that
+     * has a live process consuming RAM. `started` and `starting` cover
+     * in-flight wakes from prior reconciler ticks that haven't fully
+     * promoted to active yet. `suspended` / `inactive` are NOT alive and
+     * don't contribute (suspended drops the runtime; inactive never had
+     * one).
+     *
+     * @returns The number of agent sessions currently alive
+     */
+    async countActiveAgentSessions() {
+        try {
+            const teams = await this.storage.getTeams();
+            let count = 0;
+            for (const team of teams) {
+                for (const member of team.members || []) {
+                    const s = member.agentStatus;
+                    if (s === 'active' || s === 'started' || s === 'starting') {
+                        count += 1;
+                    }
+                }
+            }
+            return count;
+        }
+        catch (err) {
+            // Storage hiccup → fail closed (assume floor reached, skip wake).
+            // Better to defer a wake than to overshoot under crisis pressure.
+            this.logger.debug('countActiveAgentSessions failed — assuming floor reached', {
+                error: err instanceof Error ? err.message : String(err),
+            });
+            return WAKE_FLOOR_UNDER_PRESSURE;
+        }
+    }
+    /**
+     * Broadcast `system:memory_pressure` to the EventBus when wake actions
+     * have been skipped enough consecutive times to indicate a sustained
+     * stall. Throttled so a long pressure episode emits at most one event
+     * per `MEMORY_PRESSURE_REFIRE_MS` window — orc only needs to surface
+     * the condition once per stuck period, not on every reconciler tick.
+     *
+     * The 2026-05-14 incident skipped wakes ~4,200 times across 20 hours
+     * with zero user-visible signal. After this change, orc receives a
+     * critical event within ~50 seconds of the stall starting and every
+     * ~5 minutes thereafter until pressure clears.
+     *
+     * @param stats - Snapshot of memory stats at the skip moment
+     * @param activeCount - Current active agent count (already computed)
+     */
+    maybeBroadcastMemoryPressure(stats, activeCount) {
+        this.consecutivePressureSkips += 1;
+        if (!this.eventBus) {
+            return;
+        }
+        // First-fire threshold: 5 consecutive skips (~50s at 10s reconciler
+        // tick). Picked so a transient pressure spike that resolves on its
+        // own doesn't page orc; sustained pressure does.
+        const FIRST_FIRE_THRESHOLD = 5;
+        // Re-fire window: don't re-broadcast more often than once per 5min
+        // while pressure persists. Matches the EventBus dedup window order
+        // of magnitude and avoids spamming orc's terminal.
+        const MEMORY_PRESSURE_REFIRE_MS = 5 * 60 * 1000;
+        if (this.consecutivePressureSkips < FIRST_FIRE_THRESHOLD) {
+            return;
+        }
+        const now = Date.now();
+        if (this.lastPressureNotifiedAt > 0 && now - this.lastPressureNotifiedAt < MEMORY_PRESSURE_REFIRE_MS) {
+            return;
+        }
+        try {
+            this.eventBus.publish({
+                id: `system-memory-pressure-${now}`,
+                type: 'system:memory_pressure',
+                timestamp: new Date(now).toISOString(),
+                teamId: '',
+                teamName: '',
+                memberId: '',
+                memberName: 'system',
+                sessionName: 'system',
+                previousValue: 'ok',
+                newValue: 'critical',
+                changedField: 'agentStatus',
+            });
+            this.lastPressureNotifiedAt = now;
+            this.logger.warn('Broadcast system:memory_pressure to EventBus', {
                 memoryUsedPercent: stats.usedPercent,
                 freeMemMB: stats.freeMB,
+                activeAgents: activeCount,
+                consecutiveSkips: this.consecutivePressureSkips,
+            });
+        }
+        catch (err) {
+            // Failure isolation — never let a telemetry failure break the
+            // reconciler's primary control flow.
+            this.logger.warn('Failed to broadcast system:memory_pressure (non-fatal)', {
+                error: err instanceof Error ? err.message : String(err),
             });
+        }
+    }
+    /**
+     * Reset the memory-pressure broadcast state. Called on every wake
+     * that runs without pressure so the next sustained episode re-fires
+     * the first-time threshold instead of being silenced by stale state.
+     */
+    resetMemoryPressureBroadcast() {
+        if (this.consecutivePressureSkips > 0 || this.lastPressureNotifiedAt > 0) {
+            this.consecutivePressureSkips = 0;
+            this.lastPressureNotifiedAt = 0;
+        }
+    }
+    /**
+     * Find one idle, evictable agent that can be terminated to free a wake
+     * slot under memory pressure.
+     *
+     * An agent is "evictable" when ALL of the following hold:
+     *   - `agentStatus === 'active'` (no point evicting an already-dead one)
+     *   - `workingStatus === 'idle'` (don't kill a mid-task agent)
+     *   - role is NOT in `ALWAYS_ON_ROLES` (orchestrator, auditor)
+     *   - no non-terminal WorkItem in the pool targets this sessionName
+     *     (otherwise eviction would orphan that WI just like Atlas's)
+     *   - sessionName !== `incomingAgent` (don't evict ourselves)
+     *
+     * Among eligible agents, returns the longest-idle one (oldest
+     * `updatedAt`). This biases towards freeing agents that have been sitting
+     * quietly without work — the freshest idle agent might be about to claim
+     * something via the auto-claim path.
+     *
+     * @param incomingAgent - sessionName of the agent we want to wake;
+     *   excluded from the eviction pool so we never recommend evicting the
+     *   very agent we're trying to wake.
+     * @returns Eviction candidate metadata, or `null` if no agent qualifies.
+     */
+    async findEvictableIdleAgent(incomingAgent) {
+        let teams;
+        try {
+            teams = await this.storage.getTeams();
+        }
+        catch (err) {
+            this.logger.warn('findEvictableIdleAgent: failed to load teams', {
+                error: err instanceof Error ? err.message : String(err),
+            });
+            return null;
+        }
+        // Collect sessions that have any non-terminal WorkItem targeting them.
+        // Eviction would orphan those WIs (recreating the very stall we're
+        // trying to fix), so they're excluded.
+        const targetedSessions = new Set();
+        try {
+            const pool = TaskPoolService.getInstance();
+            const allItems = await pool.getAllItems();
+            for (const wi of allItems) {
+                if (wi.status === 'done' || wi.status === 'cancelled')
+                    continue;
+                const t = wi.target;
+                if (typeof t === 'string' && t.length > 0)
+                    targetedSessions.add(t);
+            }
+        }
+        catch (err) {
+            // Pool unavailable → be conservative, refuse eviction so we don't
+            // accidentally kill an agent who's about to claim a queued WI.
+            this.logger.warn('findEvictableIdleAgent: pool query failed — refusing eviction', {
+                error: err instanceof Error ? err.message : String(err),
+            });
+            return null;
+        }
+        const now = Date.now();
+        const candidates = [];
+        for (const team of teams) {
+            for (const member of team.members || []) {
+                if (member.agentStatus !== 'active')
+                    continue;
+                if (member.workingStatus !== 'idle')
+                    continue;
+                if (AGENT_SUSPEND_CONSTANTS.ALWAYS_ON_ROLES.includes(member.role)) {
+                    continue;
+                }
+                if (member.sessionName === incomingAgent)
+                    continue;
+                if (targetedSessions.has(member.sessionName))
+                    continue;
+                const lastActive = member.updatedAt
+                    ? new Date(member.updatedAt).getTime()
+                    : member.createdAt
+                        ? new Date(member.createdAt).getTime()
+                        : 0;
+                const idleMs = lastActive > 0 ? Math.max(0, now - lastActive) : 0;
+                candidates.push({
+                    sessionName: member.sessionName,
+                    teamId: team.id,
+                    memberId: member.id,
+                    role: member.role,
+                    idleMs,
+                });
+            }
+        }
+        if (candidates.length === 0)
+            return null;
+        // Longest-idle first.
+        candidates.sort((a, b) => b.idleMs - a.idleMs);
+        return candidates[0];
+    }
+    /**
+     * Terminate an evicted agent so the wake slot is freed.
+     *
+     * Uses the same `terminateAgentSession` + `updateAgentStatus(..,
+     * 'idle_exit_pressure')` pair that `IdleDetectionService` uses for the
+     * regular auto-stop path, just with a different dropoutReason so the
+     * pressure-driven evictions are distinguishable in audit logs.
+     *
+     * @param victim - Eviction candidate returned by `findEvictableIdleAgent`
+     * @returns `true` if the agent was terminated AND marked inactive;
+     *   `false` if either step failed (the caller falls back to skip).
+     */
+    async evictIdleAgent(victim) {
+        if (!this.agentRegistration) {
+            this.logger.warn('evictIdleAgent: AgentRegistrationService not wired — eviction disabled', { sessionName: victim.sessionName });
             return false;
         }
+        try {
+            await this.agentRegistration.terminateAgentSession(victim.sessionName, victim.role);
+            // `terminateAgentSession` already marks the row inactive without a
+            // dropoutReason; overwrite it with `idle_exit_pressure` so this
+            // path is distinguishable from the IdleDetectionService auto-stop
+            // path (`idle_exit`) in audit logs.
+            await this.storage.updateAgentStatus(victim.sessionName, 'inactive', 'idle_exit_pressure');
+            return true;
+        }
+        catch (err) {
+            this.logger.error('evictIdleAgent failed', {
+                sessionName: victim.sessionName,
+                role: victim.role,
+                error: err instanceof Error ? err.message : String(err),
+            });
+            return false;
+        }
+    }
+    async executeWakeAction(action) {
+        const { agentSessionName, strategy } = action;
+        // Memory-pressure gate with a concurrency floor.
+        //
+        // Previous behaviour (unconditional skip on >=90% used) wedged the
+        // system in the 2026-05-13 dogfood scenario: free RAM hovered at
+        // 16-33 MB for hours, the reconciler refused EVERY wake, and the
+        // user saw orc/think-tank/marketing all stuck inactive with queued
+        // WIs piling up. Nothing made progress until manual intervention.
+        //
+        // New behaviour: under memory pressure, still allow wakes up to
+        // `WAKE_FLOOR_UNDER_PRESSURE` concurrent active agents so the
+        // system stays minimally productive. Wakes beyond that cap are
+        // still blocked — we don't want to spawn an unbounded number of
+        // agents under crisis pressure and trigger an OOM cascade.
+        //
+        // The count includes 'active' and 'started' sessions (counting
+        // 'started' covers an in-flight wake from a prior reconciler tick
+        // that hasn't fully promoted to 'active' yet). Slight overshoot
+        // is possible across concurrent pass executions; acceptable
+        // because the cap is a SAFETY FLOOR, not a hard limit.
+        if (isUnderMemoryPressure()) {
+            const stats = getMemoryStats();
+            const activeCount = await this.countActiveAgentSessions();
+            if (activeCount >= WAKE_FLOOR_UNDER_PRESSURE) {
+                // Last-resort eviction: rather than silently skipping forever,
+                // look for an idle agent that is doing nothing productive and
+                // terminate it to free a slot for `agentSessionName` (which has
+                // a queued WI waiting). This is the failure mode that stranded
+                // Atlas on 2026-05-16 — the wake floor was held by idle product
+                // / marketing agents while a queued WI for an inactive Atlas
+                // never made progress.
+                //
+                // Eviction is intentionally narrow: ALWAYS_ON_ROLES are exempt,
+                // agents with any non-terminal WI of their own are exempt, and
+                // anything mid-task (workingStatus=in_progress) is exempt.
+                // We pick the longest-idle eligible agent (oldest `updatedAt`)
+                // so a freshly-idle agent that may auto-claim something stays
+                // alive.
+                const victim = await this.findEvictableIdleAgent(agentSessionName);
+                if (!victim) {
+                    this.logger.warn('Skipping wake action — memory pressure AND at concurrency floor', {
+                        agent: agentSessionName,
+                        strategy,
+                        memoryUsedPercent: stats.usedPercent,
+                        freeMemMB: stats.freeMB,
+                        activeAgents: activeCount,
+                        wakeFloor: WAKE_FLOOR_UNDER_PRESSURE,
+                        reason: 'no evictable idle agent — all active agents are busy or always-on',
+                    });
+                    this.maybeBroadcastMemoryPressure(stats, activeCount);
+                    return false;
+                }
+                this.logger.warn('Evicting idle agent under memory pressure to free wake slot', {
+                    evictingAgent: victim.sessionName,
+                    evictingRole: victim.role,
+                    idleMs: victim.idleMs,
+                    incomingAgent: agentSessionName,
+                    incomingStrategy: strategy,
+                    memoryUsedPercent: stats.usedPercent,
+                    freeMemMB: stats.freeMB,
+                    activeAgents: activeCount,
+                    wakeFloor: WAKE_FLOOR_UNDER_PRESSURE,
+                });
+                const evicted = await this.evictIdleAgent(victim);
+                if (!evicted) {
+                    // Eviction failed — fall back to the historical skip behaviour
+                    // rather than overshooting the floor with both agents alive.
+                    this.logger.warn('Eviction failed — falling back to skip', {
+                        agent: agentSessionName,
+                        evictAttempted: victim.sessionName,
+                        memoryUsedPercent: stats.usedPercent,
+                        freeMemMB: stats.freeMB,
+                        activeAgents: activeCount,
+                    });
+                    this.maybeBroadcastMemoryPressure(stats, activeCount);
+                    return false;
+                }
+                // Slot freed — proceed with the wake. Net activeCount stays
+                // the same (one out, one in), so the floor invariant holds.
+                this.consecutivePressureSkips = 0;
+            }
+            else {
+                this.logger.info('Memory pressure detected — allowing wake (under concurrency floor)', {
+                    agent: agentSessionName,
+                    strategy,
+                    memoryUsedPercent: stats.usedPercent,
+                    freeMemMB: stats.freeMB,
+                    activeAgents: activeCount,
+                    wakeFloor: WAKE_FLOOR_UNDER_PRESSURE,
+                });
+                // Pressure persists but a wake is proceeding — clear the skip
+                // counter so the FIRST_FIRE_THRESHOLD must be crossed again
+                // before the next broadcast. Keep `lastPressureNotifiedAt` so
+                // the 5min refire throttle still applies — we don't want the
+                // skip→wake→skip oscillation to slip past the throttle window.
+                // (Follow-up #6 from PR #543 review.)
+                this.consecutivePressureSkips = 0;
+            }
+        }
+        else {
+            // Pressure cleared — reset state so the next episode re-fires.
+            this.resetMemoryPressureBroadcast();
+        }
         this.logger.info('Executing wake action', {
             agent: agentSessionName,
             strategy,
@@ -355,14 +889,25 @@ export class LiveReconcilerDataProvider {
                 // For inactive agents, we need to start them via the registration service.
                 // The agent session creation is complex — use the team-member-start API endpoint.
                 const { teamId, memberId } = action;
-                let url = `http://localhost:${process.env.PORT || 8787}/api/teams/members/start`;
+                // Follow-up #10 from PR #543 review: replace the hardcoded
+                // 8787 with the canonical backend port constant. `process.env.PORT`
+                // still wins when set so deployments overriding the default keep
+                // working unchanged.
+                const port = process.env.PORT || WEB_CONSTANTS.PORTS.BACKEND;
+                let url = `http://localhost:${port}/api/teams/members/start`;
                 if (teamId && memberId) {
-                    url = `http://localhost:${process.env.PORT || 8787}/api/teams/${teamId}/members/${memberId}/start`;
+                    url = `http://localhost:${port}/api/teams/${teamId}/members/${memberId}/start`;
                 }
+                // Pass `workItemId` so the team-controller wake-gate can verify
+                // that this wake is pool-driven (path 1 of the gate). Reconciler
+                // hybrid-wake has already decided which WI triggered the wake;
+                // the gate trusts that decision rather than re-scanning the pool.
+                // Without this, the gate would still pass via path 2 (pool scan)
+                // — but explicit is better when we already have the evidence.
                 const response = await fetch(url, {
                     method: 'POST',
                     headers: { 'Content-Type': 'application/json' },
-                    body: JSON.stringify({ sessionName: agentSessionName }),
+                    body: JSON.stringify({ sessionName: agentSessionName, workItemId: action.workItemId }),
                 });
                 if (!response.ok) {
                     const errorText = await response.text();