crewly 1.12.1 → 1.13.1

package/dist/cli/backend/src/services/agent/agent-registration.service.js

@@ -0,0 +1,4548 @@
+import * as path from 'path';
+import * as os from 'os';
+import { readFile, readdir, stat, mkdir, writeFile, access } from 'fs/promises';
+import { existsSync } from 'fs';
+import { LoggerService } from '../core/logger.service.js';
+import { createSessionCommandHelper, getSessionBackendSync, createSessionBackend, getSessionStatePersistence, } from '../session/index.js';
+import { RuntimeServiceFactory } from './runtime-service.factory.js';
+import { registerInProcessRuntime, unregisterInProcessRuntime, } from './crewly-agent/in-process-runtime-registry.js';
+import { getCrewlyHomePath } from '../core/crewly-home.utils.js';
+import { CREWLY_CONSTANTS, ENV_CONSTANTS, AGENT_TIMEOUTS, ORCHESTRATOR_SESSION_NAME, ORCHESTRATOR_ROLE, RUNTIME_TYPES, SESSION_COMMAND_DELAYS, EVENT_DELIVERY_CONSTANTS, TERMINAL_PATTERNS, GEMINI_SHELL_MODE_CONSTANTS, GEMINI_STUCK_CONNECTIVITY_PATTERN, GEMINI_ERROR_STATE_CONSTANTS, } from '../../constants.js';
+import { WEB_CONSTANTS } from '../../../../config/constants.js';
+import { delay } from '../../utils/async.utils.js';
+import { getSettingsService } from '../settings/settings.service.js';
+import { SessionMemoryService } from '../memory/session-memory.service.js';
+import { ActiveWorkBriefingService } from './active-work-briefing.service.js';
+import { RuntimeExitMonitorService } from './runtime-exit-monitor.service.js';
+import { ContextWindowMonitorService } from './context-window-monitor.service.js';
+import { OAuthReloginMonitorService } from './oauth-relogin-monitor.service.js';
+import { SubAgentMessageQueue } from '../messaging/sub-agent-message-queue.service.js';
+import { AgentSuspendService } from './agent-suspend.service.js';
+import { PromptBuilderService, buildModuleConfigFromTeamMember, } from '../ai/prompt-builder.service.js';
+import { PromptAssemblyService } from '../ai/prompt-modules/prompt-assembly.service.js';
+import { stripAnsiCodes } from '../../utils/terminal-output.utils.js';
+import { isPromptLine, containsSpinnerOrWorkingIndicator, containsProcessingIndicator, containsBusyStatusBar, containsRewindMode, extractChatPrefix, stripTuiLineBorders, matchTuiPromptLine, } from '../../utils/terminal-string-ops.js';
+import { PtyActivityTrackerService } from './pty-activity-tracker.service.js';
+import { synthesizeSlackConversationId } from '../chat-v2/legacy-dto.utils.js';
+/**
+ * Error thrown when an agent role cannot be resolved to a valid value.
+ *
+ * Indicates a member with no `role` field in storage, or a caller passing
+ * `undefined`/empty/literal-"undefined". Surfaces the failure loudly so it
+ * cannot manifest as the silent "empty Claude prompt" symptom (Bug #1).
+ */
+export class InvalidAgentRoleError extends Error {
+    received;
+    constructor(received, context) {
+        const ctx = context ? ` (${context})` : '';
+        const display = received === undefined ? 'undefined'
+            : received === null ? 'null'
+                : typeof received === 'string' ? `"${received}"`
+                    : String(received);
+        super(`Invalid agent role${ctx}: received ${display}. Role must be a non-empty string ` +
+            `matching a directory under config/roles/. ` +
+            `Common cause: team member.role field missing or unset in storage.`);
+        this.received = received;
+        this.name = 'InvalidAgentRoleError';
+    }
+}
+/**
+ * Validate that an agent role is a usable string before it flows into session
+ * creation, env-var injection, or prompt-template path resolution.
+ *
+ * Rejects: undefined, null, non-strings, empty/whitespace strings, and the
+ * literal string "undefined" (which results from JS coercion when an undefined
+ * is interpolated into a template literal — the exact failure mode behind
+ * `CREWLY_ROLE="undefined"` in tmux env).
+ *
+ * @param role - The candidate role value
+ * @param context - Optional caller context for the error message (e.g. "startTeamMember")
+ * @throws {InvalidAgentRoleError} when role is unusable
+ */
+export function validateAgentRole(role, context) {
+    if (typeof role !== 'string') {
+        throw new InvalidAgentRoleError(role, context);
+    }
+    const trimmed = role.trim();
+    if (trimmed.length === 0 || trimmed.toLowerCase() === 'undefined' || trimmed.toLowerCase() === 'null') {
+        throw new InvalidAgentRoleError(role, context);
+    }
+}
+/**
+ * Service responsible for the complex, multi-step process of agent initialization and registration.
+ * Isolates the complex state management of agent startup with progressive escalation.
+ *
+ * Key capabilities:
+ * - Agent session creation and management
+ * - Runtime initialization and registration
+ * - Reliable message delivery to Claude Code with retry logic
+ * - Health checking and status management
+ */
+export class AgentRegistrationService {
+    logger;
+    _sessionHelper = null;
+    storageService;
+    projectRoot;
+    // Prompt file caching to eliminate file I/O contention during concurrent session creation
+    promptCache = new Map();
+    // Session creation locks to prevent concurrent createAgentSession calls for the same session
+    sessionCreationLocks = new Map();
+    // AbortControllers for pending registration prompts (keyed by session name)
+    registrationAbortControllers = new Map();
+    // Background stuck-message detector timer
+    stuckMessageDetectorTimer = null;
+    // Track TUI sessions for the stuck-message detector (sessionName → runtimeType)
+    tuiSessionRegistry = new Map();
+    // Track recently-sent messages for background stuck-detection (all runtimes).
+    // Key: sessionName, Value: array of tracked message entries
+    sentMessageTracker = new Map();
+    // Per-session delivery mutex to serialize message delivery.
+    // Prevents concurrent sendMessageWithRetry calls to the same session,
+    // which causes multiple Ctrl+C presses that can crash the runtime.
+    sessionDeliveryMutex = new Map();
+    // Per-session hash of last sent message to prevent duplicate writes (#128).
+    // Key: sessionName, Value: { hash, sentAt }
+    lastSentMessageHash = new Map();
+    // In-process Crewly Agent runtimes (sessionName → runtime instance).
+    // Used for crewly-agent runtimeType agents that run without PTY sessions.
+    inProcessRuntimes = new Map();
+    /** #167: Optional scheduler service for DLQ drain on agent activation. */
+    schedulerService = null;
+    /** Architecture Upgrade Phase 6: EventBusService for standing task subscriptions. */
+    eventBusService = null;
+    // Terminal patterns are now centralized in TERMINAL_PATTERNS constant
+    // Keeping prompt chars as static getter for backwards compatibility within the class
+    static get CLAUDE_PROMPT_INDICATORS() {
+        return TERMINAL_PATTERNS.PROMPT_CHARS;
+    }
+    constructor(_legacyTmuxService, // Legacy parameter for backwards compatibility
+    projectRoot, storageService) {
+        this.logger = LoggerService.getInstance().createComponentLogger('AgentRegistrationService');
+        this.storageService = storageService;
+        this.projectRoot = projectRoot || this.findProjectRoot();
+        // Wire up the exit monitor to cancel pending registrations on runtime exit
+        RuntimeExitMonitorService.getInstance().setOnExitDetectedCallback((sessionName) => {
+            this.cancelPendingRegistration(sessionName);
+            this.unregisterTuiSession(sessionName);
+            // Preserve queued messages for suspended agents (they'll be delivered on rehydrate)
+            if (!AgentSuspendService.getInstance().isSuspended(sessionName)) {
+                SubAgentMessageQueue.getInstance().clear(sessionName);
+            }
+        });
+    }
+    /**
+     * #167: Inject scheduler service for dead-letter queue drain on agent activation.
+     *
+     * @param scheduler - Scheduler service with drainDeadLetterQueue method
+     */
+    setSchedulerService(scheduler) {
+        this.schedulerService = scheduler;
+    }
+    /**
+     * Inject EventBusService for standing task workflow subscriptions at agent registration.
+     *
+     * @param eventBus - EventBusService instance with subscribe method
+     */
+    setEventBusService(eventBus) {
+        this.eventBusService = eventBus;
+    }
+    /**
+     * Cancel a pending registration prompt for a session.
+     * Called by RuntimeExitMonitorService when a runtime exit is detected.
+     *
+     * @param sessionName - The session whose registration to cancel
+     */
+    cancelPendingRegistration(sessionName) {
+        const controller = this.registrationAbortControllers.get(sessionName);
+        if (controller) {
+            controller.abort();
+            this.registrationAbortControllers.delete(sessionName);
+            this.logger.info('Cancelled pending registration', { sessionName });
+        }
+    }
+    /**
+     * Get or create the session helper with lazy initialization
+     */
+    async getSessionHelper() {
+        this.logger.debug('Getting session helper', {
+            hasExistingHelper: !!this._sessionHelper,
+        });
+        if (this._sessionHelper) {
+            return this._sessionHelper;
+        }
+        let backend = getSessionBackendSync();
+        this.logger.debug('Backend sync check', {
+            hasBackend: !!backend,
+        });
+        if (!backend) {
+            this.logger.info('Creating new PTY session backend');
+            backend = await createSessionBackend('pty');
+            this.logger.info('PTY session backend created', {
+                hasBackend: !!backend,
+            });
+        }
+        this._sessionHelper = createSessionCommandHelper(backend);
+        this.logger.debug('Session helper created');
+        return this._sessionHelper;
+    }
+    /**
+     * Get session helper synchronously (may throw if not initialized)
+     */
+    getSessionHelperSync() {
+        if (!this._sessionHelper) {
+            const backend = getSessionBackendSync();
+            if (!backend) {
+                throw new Error('Session backend not initialized');
+            }
+            this._sessionHelper = createSessionCommandHelper(backend);
+        }
+        return this._sessionHelper;
+    }
+    /**
+     * Resolve the runtime type for a session from storage.
+     * Checks orchestrator status first, then team member data.
+     * Falls back to CLAUDE_CODE if nothing is found.
+     *
+     * IMPORTANT: Callers should prefer passing runtimeType explicitly.
+     * This method exists as a safety net so that Ctrl+C (Claude Code
+     * cleanup) is never sent to a Gemini CLI session, which would
+     * trigger /quit and kill the agent.
+     */
+    async resolveSessionRuntimeType(sessionName) {
+        try {
+            // Check if this is the orchestrator session
+            if (sessionName === ORCHESTRATOR_SESSION_NAME) {
+                const orchestratorStatus = await this.storageService.getOrchestratorStatus();
+                if (orchestratorStatus?.runtimeType) {
+                    return orchestratorStatus.runtimeType;
+                }
+            }
+            // Check team member data
+            const memberInfo = await this.storageService.findMemberBySessionName(sessionName);
+            if (memberInfo?.member?.runtimeType) {
+                return memberInfo.member.runtimeType;
+            }
+        }
+        catch (error) {
+            this.logger.debug('Could not resolve runtime type from storage, using default', {
+                sessionName,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+        // Check in-process runtimes before defaulting to CLAUDE_CODE.
+        // crewly-agent runtimes may not have a team config entry yet.
+        if (this.inProcessRuntimes.has(sessionName)) {
+            return RUNTIME_TYPES.CREWLY_AGENT;
+        }
+        return RUNTIME_TYPES.CLAUDE_CODE;
+    }
+    /**
+     * Route a crewly-agent in-process response to the originating chat conversation.
+     *
+     * PTY-based runtimes emit [NOTIFY] markers that the terminal gateway parses.
+     * In-process crewly-agents have no terminal output, so this method provides
+     * the equivalent routing for their text responses.
+     *
+     * @param sessionName - Agent session that produced the response
+     * @param text - Response text from the agent
+     * @param conversationId - Chat conversation to route the response to
+     */
+    routeInProcessResponseToChat(sessionName, text, conversationId) {
+        // LEGACY PATH — chatGateway.processNotifyMessage → ChatService
+        // (JSON files in ~/.crewly/chat/). Kept until Phase 5 data
+        // migration retires the JSON store; until then the legacy file
+        // is what the frontend chat-v1 readers consume.
+        import('../../websocket/chat.gateway.js')
+            .then(({ getChatGateway }) => {
+            const chatGateway = getChatGateway();
+            if (!chatGateway) {
+                this.logger.debug('ChatGateway not available, skipping response routing', {
+                    sessionName, conversationId,
+                });
+                return;
+            }
+            // No metadata override here: processNotifyMessage already tags the
+            // turn `source: 'in-process-runtime'` — the canonical member of the
+            // closed RECORD_TURN_SOURCES enum for exactly this path. The old
+            // `'crewly-agent'` value was spread OVER that correct default and
+            // then failed enum validation, so every in-process reply to a web
+            // conversation was rejected with "unknown metadata.source" and
+            // silently dropped after the agent had already done the work.
+            return chatGateway.processNotifyMessage(sessionName, text, conversationId);
+        })
+            .then((chatMessage) => {
+            if (chatMessage) {
+                this.logger.debug('Routed in-process agent response to chat (legacy)', {
+                    sessionName, conversationId,
+                    messageId: typeof chatMessage === 'object' ? chatMessage.id : undefined,
+                });
+            }
+        })
+            .catch((err) => {
+            this.logger.warn('Failed to route in-process agent response to chat', {
+                sessionName, conversationId,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        });
+        // Phase 6β of unified-chat-message-store spec: the explicit
+        // chat-v2 recordTurn call that lived here during Phases 2-3
+        // was removed because `ChatService` is now a thin façade over
+        // `ChatV2Service` — the `processNotifyMessage` call above
+        // already writes through to chat-v2 internally. Keeping both
+        // paths would produce duplicate rows.
+    }
+    /**
+     * Auto-route an in-process agent's text response back to Slack.
+     *
+     * Mirrors the post-send side effects of POST /slack/send so that the
+     * Slack reply, thread-status bookkeeping, and V3 SLA cascade all stay in
+     * sync. Used as a finish-event hook for the in-process Crewly Agent
+     * runtime when:
+     *   1. The inbound message carried a `[SLACK:channelId:threadTs]` marker
+     *   2. The agent produced text output (`result.text` non-empty)
+     *   3. The agent did NOT explicitly call the `reply_slack` tool
+     *
+     * Without this hook, AI SDK agents that finish with `toolCalls=0,
+     * finishReason=stop` would drop their reply on the floor — unlike the
+     * claude-code PTY path, the in-process runtime has no stdout stream the
+     * SlackBridge can tail.
+     *
+     * Best-effort: a Slack-not-connected condition or a downstream
+     * bookkeeping failure is logged and swallowed; never throws. The chat
+     * route (`routeInProcessResponseToChat`) handles persistence to the chat
+     * service separately.
+     *
+     * @param sessionName - Agent session that produced the response
+     * @param text - Response text from the agent
+     * @param slackContext - Slack channel + thread metadata captured from the
+     *                       inbound `[SLACK:channelId:threadTs]` marker
+     */
+    routeInProcessResponseToSlack(sessionName, text, slackContext) {
+        // Lazy import to avoid module-load circular dependency between
+        // agent-registration ↔ slack ↔ messaging ↔ v3.
+        import('../slack/slack.service.js')
+            .then(async ({ getSlackService }) => {
+            const slack = getSlackService();
+            if (!slack.isConnected()) {
+                this.logger.warn('Slack not connected — cannot auto-route in-process agent response', {
+                    sessionName,
+                    channelId: slackContext.channelId,
+                    threadTs: slackContext.threadTs,
+                    textLength: text.length,
+                });
+                return;
+            }
+            // Auto-prefix with the agent display name (mirrors reply_slack tool
+            // behavior) so the message is attributable in the Slack thread.
+            // Skip if the text already starts with `[` — the agent supplied its
+            // own prefix.
+            let cleanText = text;
+            if (sessionName && !cleanText.startsWith('[')) {
+                const parts = sessionName.split('-');
+                const namePart = parts.length >= 3 ? parts[2] : parts[parts.length - 1];
+                if (namePart) {
+                    const capitalized = namePart.charAt(0).toUpperCase() + namePart.slice(1);
+                    cleanText = `[${capitalized}] ${cleanText}`;
+                }
+            }
+            await slack.sendMessage({
+                channelId: slackContext.channelId,
+                text: cleanText,
+                threadTs: slackContext.threadTs,
+            });
+            this.logger.info('Auto-routed in-process agent response to Slack', {
+                sessionName,
+                channelId: slackContext.channelId,
+                threadTs: slackContext.threadTs,
+                textLength: cleanText.length,
+            });
+            // Mirror /slack/send bookkeeping #4 — clear the pending-delivery
+            // reminder OrcDeliveryEnforcer holds for this thread. This is the one
+            // side-effect the auto-route never mirrored, and the gap is
+            // user-visible: when the agent answers with plain text instead of
+            // calling the reply_slack tool, the reply reaches Slack but the
+            // ledger entry survives, so the enforcer nudges again at 10 min and
+            // again at 30 min — and the agent posts the same answer each time.
+            // SlackService's dedup window is 30s, far too short to absorb
+            // reminders spaced minutes apart, so every nudge lands in the thread
+            // as a visible duplicate.
+            if (slackContext.threadTs) {
+                try {
+                    const { OrcDeliveryEnforcerService } = await import('../orc/orc-delivery-enforcer.service.js');
+                    OrcDeliveryEnforcerService.getInstance()?.markDelivered({
+                        channelId: slackContext.channelId,
+                        threadTs: slackContext.threadTs,
+                    });
+                }
+                catch (err) {
+                    this.logger.debug('Failed to clear pending delivery after auto-route (non-fatal)', {
+                        sessionName,
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                }
+            }
+            // Mirror /slack/send bookkeeping #3 — record `agent.action`
+            // with actionType='send_slack' so the auditor view and any
+            // V3 downstream analysis see the auto-routed reply. Without
+            // this entry the in-process auto-route is invisible in the
+            // behavior log (only `/slack/send`-originated replies show
+            // up). Follow-up #9 from PR #543 review.
+            try {
+                const { getAgentBehaviorLogService } = await import('../observability/agent-behavior-log.singleton.js');
+                getAgentBehaviorLogService()?.record({
+                    type: 'agent.action',
+                    agent: sessionName,
+                    actionType: 'send_slack',
+                    details: {
+                        channelId: slackContext.channelId,
+                        threadTs: slackContext.threadTs ?? null,
+                        textLength: cleanText.length,
+                        source: 'in_process_auto_route',
+                    },
+                });
+            }
+            catch (err) {
+                this.logger.debug('Failed to record send_slack agent.action (non-fatal)', {
+                    sessionName,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+            // Mirror /slack/send bookkeeping #1 — mark thread as
+            // replied_completed so the recovery loop on the next restart
+            // does not re-enqueue this inbound message. Without this, every
+            // backend restart would cause orc to re-reply.
+            //
+            // Race-protection: build the thread-status entry on the fly if
+            // it isn't tracked yet. The Slack listener's `trackInbound` is
+            // what normally populates the entry, but in a startup-race
+            // scenario the agent finish event can land before the listener
+            // has persisted the inbound. Without this fallback,
+            // `markReplied` short-circuits and the recovery loop on the
+            // next boot still re-fires the inbound (the exact bug
+            // /slack/send already guards against — keep parity).
+            if (slackContext.threadTs) {
+                try {
+                    const { ThreadStatusQueueService } = await import('../messaging/thread-status-queue.service.js');
+                    const tsq = ThreadStatusQueueService.getInstance();
+                    const threadKey = `${slackContext.channelId}:${slackContext.threadTs}`;
+                    if (!tsq.get(threadKey)) {
+                        tsq.trackInbound({
+                            threadKey,
+                            conversationId: synthesizeSlackConversationId(slackContext.channelId, slackContext.threadTs),
+                            source: 'slack',
+                            messagePreview: '[in-process auto-route — no inbound recorded]',
+                        });
+                    }
+                    tsq.markReplied(threadKey, 'replied_completed');
+                }
+                catch (err) {
+                    this.logger.debug('Failed to update thread-status after auto-route (non-fatal)', {
+                        sessionName,
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                }
+            }
+            // Mirror /slack/send bookkeeping #2 — fire the V3 SLA cascade so
+            // the matching Request transitions out of `queued`. Without
+            // this, requests whose acknowledgement came via this auto-route
+            // would never reach a terminal state.
+            if (slackContext.threadTs) {
+                try {
+                    const { getRequestSlaSubscriber } = await import('../v3/request-sla.subscriber.js');
+                    const sub = getRequestSlaSubscriber();
+                    if (sub) {
+                        await sub.markResolvedByThread(slackContext.threadTs);
+                    }
+                }
+                catch (err) {
+                    this.logger.debug('Failed to fire SLA cascade after auto-route (non-fatal)', {
+                        sessionName,
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                }
+            }
+        })
+            .catch((err) => {
+            this.logger.warn('Failed to auto-route in-process agent response to Slack', {
+                sessionName,
+                channelId: slackContext.channelId,
+                threadTs: slackContext.threadTs,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        });
+    }
+    /**
+     * Find the project root by looking for package.json
+     */
+    findProjectRoot() {
+        // Resolve from the compiled dist/ location to the package root (#209)
+        // dist/backend/src/services/agent/ → root (5 levels up)
+        // This works for both local dev and npm global installs
+        try {
+            // Use __dirname equivalent: path.dirname(fileURLToPath(import.meta.url))
+            // But since Jest doesn't support import.meta, we use the module path directly
+            const candidates = [
+                // From source: backend/src/services/agent/ → root
+                path.resolve(__dirname, '..', '..', '..', '..'),
+                // From compiled dist: dist/backend/src/services/agent/ → root
+                path.resolve(__dirname, '..', '..', '..', '..', '..'),
+            ];
+            for (const candidate of candidates) {
+                if (existsSync(path.join(candidate, 'config', 'skills'))) {
+                    return candidate;
+                }
+            }
+        }
+        catch {
+            // Path resolution failed — fall back
+        }
+        return process.cwd();
+    }
+    /**
+     * Resolve runtime flags from the agent's effective skills.
+     * Reads role config and skill configs to collect flags compatible with the runtime.
+     *
+     * @param role - The agent's role name
+     * @param runtimeType - The agent's runtime type (e.g. 'claude-code')
+     * @param skillOverrides - Additional skills assigned to the member
+     * @param excludedRoleSkills - Skills excluded from the role's default set
+     * @returns Array of CLI flags to inject (e.g. ['--chrome'])
+     */
+    async resolveRuntimeFlags(role, runtimeType, skillOverrides, excludedRoleSkills) {
+        const flags = new Set();
+        try {
+            // 1. Get role's assigned skills from config/roles/{role}/role.json
+            const roleName = role.toLowerCase().replace(/\s+/g, '-');
+            const rolePath = path.join(this.projectRoot, 'config', 'roles', roleName, 'role.json');
+            const roleContent = await readFile(rolePath, 'utf8');
+            const roleConfig = JSON.parse(roleContent);
+            const roleSkills = roleConfig.assignedSkills || [];
+            // 2. Apply skill overrides and exclusions
+            const effectiveSkills = new Set([...roleSkills, ...(skillOverrides || [])]);
+            for (const excluded of (excludedRoleSkills || [])) {
+                effectiveSkills.delete(excluded);
+            }
+            // 3. For each skill, read skill.json and collect flags matching runtime.
+            //    Skills live under agent/core/ or agent/marketplace/ subdirectories,
+            //    so search both paths when looking up skill.json.
+            for (const skillId of effectiveSkills) {
+                try {
+                    const skillJsonPath = await this.findSkillJsonPath(skillId);
+                    if (!skillJsonPath) {
+                        this.logger.debug('Skill config not found in any known directory (no runtime flags)', { skillId });
+                        continue;
+                    }
+                    const skillContent = await readFile(skillJsonPath, 'utf8');
+                    const skillConfig = JSON.parse(skillContent);
+                    if (skillConfig.runtime?.runtime === runtimeType && Array.isArray(skillConfig.runtime?.flags)) {
+                        for (const flag of skillConfig.runtime.flags) {
+                            flags.add(flag);
+                        }
+                    }
+                }
+                catch (skillErr) {
+                    this.logger.warn('Failed to read skill config', {
+                        skillId,
+                        error: skillErr instanceof Error ? skillErr.message : String(skillErr),
+                    });
+                }
+            }
+            if (flags.size > 0) {
+                this.logger.info('Resolved runtime flags from skills', {
+                    role, runtimeType, flags: Array.from(flags),
+                });
+            }
+        }
+        catch (error) {
+            this.logger.debug('Could not resolve runtime flags (no role config or read error)', {
+                role, runtimeType, error: error instanceof Error ? error.message : String(error),
+            });
+        }
+        return Array.from(flags);
+    }
+    /**
+     * Search known skill directories for a skill's skill.json file.
+     * Skills live under `config/skills/agent/core/` or `config/skills/agent/marketplace/`.
+     *
+     * @param skillId - The skill identifier (directory name)
+     * @returns Absolute path to skill.json, or null if not found
+     */
+    async findSkillJsonPath(skillId) {
+        const searchDirs = [
+            path.join(this.projectRoot, 'config', 'skills', 'agent', 'core', skillId, 'skill.json'),
+            path.join(this.projectRoot, 'config', 'skills', 'agent', 'marketplace', skillId, 'skill.json'),
+        ];
+        for (const candidate of searchDirs) {
+            try {
+                await access(candidate);
+                return candidate;
+            }
+            catch {
+                // Not found in this directory, try next
+            }
+        }
+        return null;
+    }
+    /**
+     * Create a runtime service instance for the given runtime type.
+     * Centralizes RuntimeServiceFactory creation to reduce code duplication.
+     */
+    createRuntimeService(runtimeType) {
+        return RuntimeServiceFactory.create(runtimeType, null, this.projectRoot);
+    }
+    /**
+     * Get an in-process Crewly Agent runtime by session name.
+     * Used by the terminal controller for force-delivery to in-process agents.
+     *
+     * @param sessionName - Session name to look up
+     * @returns The CrewlyAgentExternalRuntimeService if it exists, undefined otherwise
+     */
+    getInProcessRuntime(sessionName) {
+        return this.inProcessRuntimes.get(sessionName);
+    }
+    /**
+     * Check if an in-process Crewly Agent runtime is active and ready for a given session.
+     *
+     * Used by team status resolution to correctly report active status for
+     * crewly-agent runtimes that have no PTY session.
+     *
+     * @param sessionName - The session name to check
+     * @returns True if an in-process runtime exists and is ready
+     */
+    isInProcessRuntimeActive(sessionName) {
+        const runtime = this.inProcessRuntimes.get(sessionName);
+        return runtime !== undefined && runtime.isReady();
+    }
+    /**
+     * Get the check interval based on environment.
+     * Uses shorter intervals in test environment for faster tests.
+     */
+    getCheckInterval() {
+        return process.env.NODE_ENV === 'test' ? 1000 : 2000;
+    }
+    /**
+     * Update agent status with safe error handling (non-blocking).
+     * Returns true if successful, false if failed.
+     */
+    async updateAgentStatusSafe(sessionName, status, context) {
+        try {
+            await this.storageService.updateAgentStatus(sessionName, status);
+            this.logger.info(`Agent status updated to ${status}`, { sessionName, ...context });
+            return true;
+        }
+        catch (error) {
+            this.logger.warn('Failed to update agent status (non-critical)', {
+                sessionName,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return false;
+        }
+    }
+    /**
+     * Role aliases — common synonyms users naturally type in team configs
+     * mapped to the canonical directory name under `config/roles/`. Without
+     * these, a team-config role like `"tech-lead"` would fall through to a
+     * non-existent directory and trigger the ENOENT fallback path on every
+     * agent registration (Steve 2026-05-15 dogfood: CE team config used
+     * `role: "tech-lead"` while the canonical directory is `team-leader`,
+     * producing a steady drip of "Could not load prompt from config" warns
+     * for every member-start with no actionable resolution short of editing
+     * user data).
+     *
+     * Keep keys lowercased + dash-normalized (matches the post-normalization
+     * shape used by `getPromptFileForRole`).
+     */
+    static ROLE_DIR_ALIASES = new Map([
+        ['tech-lead', 'team-leader'],
+        ['techlead', 'team-leader'],
+        ['tl', 'team-leader'],
+        ['team-lead', 'team-leader'],
+    ]);
+    /**
+     * Get prompt file path for a specific role
+     * Uses the unified config/roles/{role}/prompt.md structure
+     */
+    async getPromptFileForRole(role) {
+        // Defensive: reject empty/undefined/literal-"undefined" before path concat,
+        // which would otherwise resolve to a non-existent `config/roles/undefined/prompt.md`
+        // and trigger the silent fallback path that left agents with empty prompts (Bug #1).
+        validateAgentRole(role, 'getPromptFileForRole');
+        // Normalize role name to directory name format
+        const normalized = role.toLowerCase().replace(/\s+/g, '-');
+        // Resolve aliases (e.g. tech-lead → team-leader). Falls through for
+        // any role that already matches its directory name.
+        const roleName = AgentRegistrationService.ROLE_DIR_ALIASES.get(normalized) ?? normalized;
+        return path.join(process.cwd(), 'config', 'roles', roleName, 'prompt.md');
+    }
+    /**
+     * Initialize agent with optimized 2-step escalation process
+     * Reduced from 4-step to 2-step with shorter timeouts for better concurrency
+     */
+    async initializeAgentWithRegistration(sessionName, role, projectPath, timeout = AGENT_TIMEOUTS.REGULAR_AGENT_INITIALIZATION, memberId, runtimeType = RUNTIME_TYPES.CLAUDE_CODE, runtimeFlags, additionalAllowlistPaths) {
+        const startTime = Date.now();
+        this.logger.info('Starting optimized agent initialization with registration', {
+            sessionName,
+            role,
+            timeout,
+            runtimeType,
+        });
+        // PHASE 4: agentStatus is now set immediately in API endpoints (startTeam/startTeamMember)
+        // No longer need to set it here - focus only on session creation
+        this.logger.info('Starting agent session initialization', { sessionName, role });
+        // Clear detection cache to ensure fresh runtime detection
+        const runtimeService = this.createRuntimeService(runtimeType);
+        runtimeService.clearDetectionCache(sessionName);
+        // Skip Step 1 (direct registration) as it often fails in concurrent scenarios
+        // Go directly to Step 2: Cleanup + reinit (more reliable)
+        try {
+            this.logger.info('Step 1: Attempting cleanup and reinitialization', {
+                sessionName,
+            });
+            const step1Success = await this.tryCleanupAndReinit(sessionName, role, 70000, // 70 seconds for cleanup and reinit (allows 60s for runtime ready)
+            projectPath, memberId, runtimeType, runtimeFlags, additionalAllowlistPaths);
+            if (step1Success) {
+                return {
+                    success: true,
+                    message: 'Agent registered successfully after cleanup and reinit',
+                };
+            }
+        }
+        catch (error) {
+            this.logger.warn('Step 1 (cleanup + reinit) failed', {
+                sessionName,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+        // Step 2: Full session recreation (30 seconds) - only if time remaining
+        if (Date.now() - startTime < timeout - 35000) {
+            try {
+                this.logger.info('Step 2: Attempting full session recreation', { sessionName });
+                const step2Success = await this.tryFullRecreation(sessionName, role, 30000, // Reduced from 45000 to 30000
+                projectPath, memberId, runtimeType, runtimeFlags);
+                if (step2Success) {
+                    return {
+                        success: true,
+                        message: 'Agent registered successfully after full recreation',
+                    };
+                }
+            }
+            catch (error) {
+                this.logger.warn('Step 2 (full recreation) failed', {
+                    sessionName,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        // Give up after 2 steps
+        const errorMsg = `Failed to initialize agent after optimized escalation attempts (${Math.round((Date.now() - startTime) / 1000)}s)`;
+        this.logger.error(errorMsg, { sessionName, role });
+        return { success: false, error: errorMsg };
+    }
+    /**
+     * Step 1: Try direct registration prompt
+     * Assumes Claude is already running and just needs a registration prompt
+     */
+    async tryDirectRegistration(sessionName, role, timeout, memberId, runtimeType = RUNTIME_TYPES.CLAUDE_CODE) {
+        // Clear any existing input. Claude already performs Ctrl+C cleanup during
+        // runtime detection, so avoid sending additional Ctrl+C sequences.
+        // Gemini CLI: Skip cleanup — Ctrl+C at an empty prompt triggers /quit.
+        // Escape defocuses the TUI. Ctrl+U is ignored by the TUI.
+        const helper = await this.getSessionHelper();
+        // First check if runtime is running before sending the prompt
+        // runtimeService2: Separate instance for pre-registration runtime detection
+        // This instance is isolated from main runtimeService to avoid cache interference
+        const runtimeService2 = this.createRuntimeService(runtimeType);
+        const runtimeRunning = await runtimeService2.detectRuntimeWithCommand(sessionName);
+        if (!runtimeRunning) {
+            this.logger.debug('Runtime not detected in Step 1, skipping direct registration', {
+                sessionName,
+                runtimeType,
+            });
+            return false;
+        }
+        this.logger.debug('Runtime detected, sending registration prompt', {
+            sessionName,
+            runtimeType,
+        });
+        // Clear any pending slash command from detection. Claude detection already
+        // exits slash mode. Gemini CLI: skip — Ctrl+C at empty prompt exits CLI,
+        // Escape defocuses TUI, Ctrl+U is ignored. The prompt should be clean.
+        const prompt = await this.loadRegistrationPrompt(role, sessionName, memberId, runtimeType);
+        const promptDelivered = await this.sendPromptRobustly(sessionName, prompt, runtimeType);
+        if (!promptDelivered) {
+            this.logger.warn('Failed to deliver registration prompt', { sessionName, role });
+            return false;
+        }
+        return await this.waitForRegistration(sessionName, role, timeout);
+    }
+    /**
+     * Step 2: Cleanup with Ctrl+C and reinitialize
+     * Tries to reset the runtime session and start fresh
+     */
+    async tryCleanupAndReinit(sessionName, role, timeout, projectPath, memberId, runtimeType = RUNTIME_TYPES.CLAUDE_CODE, runtimeFlags, additionalAllowlistPaths) {
+        // Clear Commandline
+        await (await this.getSessionHelper()).clearCurrentCommandLine(sessionName);
+        // Inject --resume flag if this was a previously running Claude Code session
+        const effectiveFlags = runtimeFlags ? [...runtimeFlags] : [];
+        if (runtimeType === RUNTIME_TYPES.CLAUDE_CODE) {
+            try {
+                const settings = await getSettingsService().getSettings();
+                if (settings.general.autoResumeOnRestart) {
+                    const persistence = getSessionStatePersistence();
+                    if (persistence.isRestoredSession(sessionName)) {
+                        const storedSessionId = persistence.getSessionId(sessionName);
+                        if (storedSessionId) {
+                            effectiveFlags.push('--resume', storedSessionId);
+                            this.logger.info('Injecting --resume flag for session restore', {
+                                sessionName, sessionId: storedSessionId,
+                            });
+                        }
+                    }
+                }
+                else {
+                    this.logger.info('Auto-resume disabled by settings, skipping session resume', { sessionName });
+                }
+            }
+            catch (resumeError) {
+                this.logger.debug('Could not resolve resume flag (non-fatal)', {
+                    sessionName, error: resumeError instanceof Error ? resumeError.message : String(resumeError),
+                });
+            }
+        }
+        // Write prompt file before launching runtime so --agent (Claude Code) or --append-system-prompt-file works
+        let promptFilePath;
+        let agentName;
+        if (runtimeType === RUNTIME_TYPES.CLAUDE_CODE) {
+            try {
+                const prompt = await this.loadRegistrationPrompt(role, sessionName, memberId, runtimeType);
+                promptFilePath = await this.writePromptFile(sessionName, prompt, {
+                    runtimeType,
+                    projectPath,
+                    role,
+                });
+                agentName = sessionName;
+            }
+            catch (promptError) {
+                this.logger.warn('Failed to pre-write prompt file (non-fatal, will fall back to direct delivery)', {
+                    sessionName,
+                    error: promptError instanceof Error ? promptError.message : String(promptError),
+                });
+            }
+        }
+        // Reinitialize runtime using the appropriate initialization script (always fresh start)
+        const runtimeService2 = this.createRuntimeService(runtimeType);
+        await runtimeService2.executeRuntimeInitScript(sessionName, projectPath, effectiveFlags, promptFilePath, agentName);
+        // Wait for runtime to be ready (simplified detection)
+        // Use shorter check interval in test environment, and reasonable interval in production
+        const checkInterval = this.getCheckInterval();
+        const isReady = await runtimeService2.waitForRuntimeReady(sessionName, 60000, checkInterval); // 60s timeout — Claude Code cold starts can take 30-60s
+        if (!isReady) {
+            throw new Error(`Failed to reinitialize ${runtimeType} within timeout`);
+        }
+        // Start runtime exit monitoring IMMEDIATELY after runtime is ready.
+        // Must be before postInitialize and sendRegistrationPromptAsync so exits
+        // during those phases are detected and the abort signal fires in time.
+        RuntimeExitMonitorService.getInstance().startMonitoring(sessionName, runtimeType, role);
+        // Start OAuth relogin monitoring for automatic re-authentication
+        OAuthReloginMonitorService.getInstance().startMonitoring(sessionName, runtimeType);
+        // Look up per-agent browser automation override from member config
+        let browserAutomationOverride;
+        if (memberId) {
+            try {
+                const teams = await this.storageService.getTeams();
+                for (const team of teams) {
+                    const member = team.members?.find((m) => m.id === memberId || m.sessionName === sessionName);
+                    if (member?.enableBrowserAutomation !== undefined) {
+                        browserAutomationOverride = member.enableBrowserAutomation;
+                        break;
+                    }
+                }
+            }
+            catch {
+                // Non-fatal — will use global setting
+            }
+        }
+        // Run post-initialization hook (e.g., Gemini CLI directory allowlist)
+        try {
+            await runtimeService2.postInitialize(sessionName, projectPath, additionalAllowlistPaths, browserAutomationOverride);
+            // Drain stale terminal escape sequences (e.g. DA1 [?1;2c) that may have
+            // arrived during postInitialize commands, so they don't leak into the prompt input
+            await delay(500);
+            // Clear any pending input after post-initialization.
+            // Claude Code: Ctrl+C + Ctrl+U (clearCurrentCommandLine) — standard cleanup.
+            // Gemini CLI: Skip cleanup entirely — the TUI just started with a clean
+            // prompt. Ctrl+C at an empty Gemini CLI prompt triggers /quit and exits
+            // the CLI. Escape defocuses the TUI. Ctrl+U is ignored. The delay(500)
+            // above is sufficient to drain stale escape sequences.
+            if (runtimeType === RUNTIME_TYPES.CLAUDE_CODE) {
+                await (await this.getSessionHelper()).clearCurrentCommandLine(sessionName);
+            }
+        }
+        catch (postInitError) {
+            this.logger.warn('Post-initialization hook failed (non-fatal)', {
+                sessionName,
+                runtimeType,
+                error: postInitError instanceof Error ? postInitError.message : String(postInitError),
+            });
+        }
+        // For PTY sessions, once runtime is detected as ready, consider initialization successful
+        // MCP registration will happen async when the agent processes its first prompt
+        this.logger.info('Runtime detected as ready, session initialization successful', {
+            sessionName,
+            role,
+            runtimeType,
+        });
+        // Background: detect and store session ID for resume-on-restart
+        if (runtimeType === RUNTIME_TYPES.CLAUDE_CODE) {
+            const detectPath = projectPath || process.cwd();
+            setTimeout(() => {
+                this.detectAndStoreSessionId(sessionName, detectPath).catch(() => { });
+            }, 10000);
+        }
+        // Send the registration prompt in background (don't block on it)
+        this.sendRegistrationPromptAsync(sessionName, role, memberId, runtimeType).catch((err) => {
+            this.logger.warn('Background registration prompt failed (non-blocking)', {
+                sessionName,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        });
+        // Update agent status to 'started' since the runtime is running
+        // The agent will become 'active' only after it registers via the API endpoint
+        try {
+            await this.storageService.updateAgentStatus(sessionName, CREWLY_CONSTANTS.AGENT_STATUSES.STARTED);
+            this.logger.info('Agent status updated to started (runtime running, awaiting registration)', { sessionName, role });
+        }
+        catch (statusError) {
+            this.logger.warn('Failed to update agent status (non-critical)', {
+                sessionName,
+                error: statusError instanceof Error ? statusError.message : String(statusError),
+            });
+        }
+        return true;
+    }
+    /**
+     * Detect and store the Claude Code session ID by scanning the filesystem.
+     * Claude Code stores conversations as <UUID>.jsonl files in
+     * ~/.claude/projects/<path-slug>/ where path-slug is the absolute
+     * project path with / replaced by -.
+     *
+     * Runs in background after agent init to capture the session ID
+     * for resume-on-restart support.
+     *
+     * @param sessionName - PTY session name
+     * @param projectPath - Absolute path to the agent's project directory
+     */
+    async detectAndStoreSessionId(sessionName, projectPath) {
+        try {
+            const slug = projectPath.replace(/\//g, '-');
+            const claudeProjectDir = path.join(os.homedir(), '.claude', 'projects', slug);
+            const files = await readdir(claudeProjectDir);
+            const jsonlFiles = files.filter(f => f.endsWith('.jsonl'));
+            if (jsonlFiles.length === 0)
+                return;
+            // Find most recent .jsonl by mtime
+            let latestFile = '';
+            let latestMtime = 0;
+            for (const file of jsonlFiles) {
+                const fileStat = await stat(path.join(claudeProjectDir, file));
+                if (fileStat.mtimeMs > latestMtime) {
+                    latestMtime = fileStat.mtimeMs;
+                    latestFile = file;
+                }
+            }
+            if (!latestFile)
+                return;
+            // Extract UUID from filename (remove .jsonl extension)
+            const sessionId = latestFile.replace('.jsonl', '');
+            const persistence = getSessionStatePersistence();
+            persistence.updateSessionId(sessionName, sessionId);
+            this.logger.info('Detected and stored Claude session ID from filesystem', {
+                sessionName,
+                sessionId,
+                claudeProjectDir,
+            });
+        }
+        catch (error) {
+            this.logger.debug('Could not detect Claude session ID from filesystem (non-fatal)', {
+                sessionName,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    /**
+     * Provision the runtime-specific project config file.
+     *
+     * Each agent CLI reads a different file for project configuration:
+     * - Claude Code  → .crewly/CLAUDE.md
+     * - Gemini CLI   → GEMINI.md (project root)
+     * - Codex        → AGENTS.md (project root)
+     *
+     * Uses 'wx' flag to avoid overwriting existing files.
+     *
+     * @param projectPath - Project directory path
+     * @param runtimeType - Agent runtime type
+     */
+    async provisionRuntimeConfigFile(projectPath, runtimeType) {
+        // Map runtime type to template file and output path
+        const configMap = {
+            [RUNTIME_TYPES.CLAUDE_CODE]: {
+                template: 'agent-claude-md.md',
+                outputPath: path.join(projectPath, '.crewly', 'CLAUDE.md'),
+            },
+            [RUNTIME_TYPES.GEMINI_CLI]: {
+                template: 'agent-gemini-md.md',
+                outputPath: path.join(projectPath, 'GEMINI.md'),
+            },
+            [RUNTIME_TYPES.CODEX_CLI]: {
+                template: 'agent-agents-md.md',
+                outputPath: path.join(projectPath, 'AGENTS.md'),
+            },
+        };
+        const config = configMap[runtimeType];
+        if (!config)
+            return; // Unknown runtime — skip
+        try {
+            // Ensure parent directory exists
+            const dir = path.dirname(config.outputPath);
+            await mkdir(dir, { recursive: true });
+            const templatePath = path.join(this.projectRoot, 'config', 'templates', config.template);
+            let content = this.promptCache.get(templatePath);
+            if (!content) {
+                content = await readFile(templatePath, 'utf8');
+                this.promptCache.set(templatePath, content);
+            }
+            // Substitute path placeholders before writing (#209). The cache holds
+            // the RAW template; resolve into a per-project copy so skill-script and
+            // project paths in the provisioned config file point at real locations
+            // (mirrors the placeholder substitution done for the registration prompt).
+            const agentSkillsPath = path.join(this.projectRoot, 'config', 'skills', 'agent');
+            const orchestratorSkillsPath = path.join(this.projectRoot, 'config', 'skills', 'orchestrator');
+            const marketplaceSkillsPath = path.join(os.homedir(), '.crewly', 'marketplace', 'skills');
+            const resolved = content
+                .replace(/\{\{PROJECT_PATH\}\}/g, projectPath)
+                .replace(/\{\{AGENT_SKILLS_PATH\}\}/g, agentSkillsPath)
+                .replace(/\{\{ORCHESTRATOR_SKILLS_PATH\}\}/g, orchestratorSkillsPath)
+                .replace(/\{\{MARKETPLACE_SKILLS_PATH\}\}/g, marketplaceSkillsPath);
+            await writeFile(config.outputPath, resolved, { flag: 'wx' }).catch(() => {
+                // File already exists — no action needed
+            });
+        }
+        catch (err) {
+            this.logger.warn('Could not provision runtime config file (non-critical)', {
+                runtimeType,
+                outputPath: config.outputPath,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    /**
+     * Send registration prompt asynchronously (non-blocking).
+     * Uses an AbortController so the operation can be cancelled if the
+     * runtime exits before registration completes.
+     */
+    async sendRegistrationPromptAsync(sessionName, role, memberId, runtimeType = RUNTIME_TYPES.CLAUDE_CODE) {
+        // Create AbortController for this registration
+        const controller = new AbortController();
+        this.registrationAbortControllers.set(sessionName, controller);
+        try {
+            this.logger.info('Loading registration prompt', { sessionName, role, runtimeType });
+            if (controller.signal.aborted)
+                return;
+            const prompt = await this.loadRegistrationPrompt(role, sessionName, memberId, runtimeType);
+            this.logger.info('Registration prompt loaded, sending to agent', {
+                sessionName, role, runtimeType, promptLength: prompt.length,
+            });
+            if (controller.signal.aborted)
+                return;
+            const sent = await this.sendPromptRobustly(sessionName, prompt, runtimeType, controller.signal);
+            if (sent) {
+                this.logger.info('Registration prompt sent successfully', { sessionName, role });
+            }
+            else {
+                this.logger.warn('Registration prompt delivery returned false', { sessionName, role, runtimeType });
+            }
+        }
+        catch (error) {
+            if (controller.signal.aborted) {
+                this.logger.info('Registration prompt cancelled (runtime exited)', { sessionName });
+                return;
+            }
+            this.logger.warn('Failed to send registration prompt asynchronously', {
+                sessionName,
+                error: error instanceof Error ? error.message : String(error),
+                stack: error instanceof Error ? error.stack : undefined,
+            });
+        }
+        finally {
+            this.registrationAbortControllers.delete(sessionName);
+        }
+    }
+    /**
+     * Step 3: Kill session and recreate completely
+     * Most aggressive approach - completely recreates the session from scratch
+     */
+    async tryFullRecreation(sessionName, role, timeout, projectPath, memberId, runtimeType = RUNTIME_TYPES.CLAUDE_CODE, runtimeFlags) {
+        // Kill existing session
+        await (await this.getSessionHelper()).killSession(sessionName);
+        // Wait for cleanup
+        await delay(1000);
+        // Inject --resume flag if this was a previously running Claude Code session
+        const effectiveFlags = runtimeFlags ? [...runtimeFlags] : [];
+        if (runtimeType === RUNTIME_TYPES.CLAUDE_CODE) {
+            try {
+                const settings = await getSettingsService().getSettings();
+                if (settings.general.autoResumeOnRestart) {
+                    const persistence = getSessionStatePersistence();
+                    if (persistence.isRestoredSession(sessionName)) {
+                        const storedSessionId = persistence.getSessionId(sessionName);
+                        if (storedSessionId) {
+                            effectiveFlags.push('--resume', storedSessionId);
+                            this.logger.info('Injecting --resume flag for session restore (full recreation)', {
+                                sessionName, sessionId: storedSessionId,
+                            });
+                        }
+                    }
+                }
+                else {
+                    this.logger.info('Auto-resume disabled by settings, skipping session resume after recreation', { sessionName });
+                }
+            }
+            catch (resumeError) {
+                this.logger.debug('Could not resolve resume flag (non-fatal)', {
+                    sessionName, error: resumeError instanceof Error ? resumeError.message : String(resumeError),
+                });
+            }
+        }
+        // Write prompt file before launching runtime so --agent (Claude Code) or --append-system-prompt-file works
+        let promptFilePath;
+        let agentName;
+        if (runtimeType === RUNTIME_TYPES.CLAUDE_CODE) {
+            try {
+                const prompt = await this.loadRegistrationPrompt(role, sessionName, memberId, runtimeType);
+                promptFilePath = await this.writePromptFile(sessionName, prompt, {
+                    runtimeType,
+                    projectPath,
+                    role,
+                });
+                agentName = sessionName;
+            }
+            catch (promptError) {
+                this.logger.warn('Failed to pre-write prompt file in full recreation (non-fatal)', {
+                    sessionName,
+                    error: promptError instanceof Error ? promptError.message : String(promptError),
+                });
+            }
+        }
+        // Recreate session based on role
+        if (role === ORCHESTRATOR_ROLE) {
+            await this.createOrchestratorSession({
+                sessionName,
+                projectPath: projectPath || process.cwd(),
+            });
+            // Initialize runtime for orchestrator using script (always fresh start)
+            const runtimeService = this.createRuntimeService(runtimeType);
+            await runtimeService.executeRuntimeInitScript(sessionName, process.cwd(), effectiveFlags, promptFilePath, agentName);
+            // Wait for runtime to be ready
+            const checkInterval = this.getCheckInterval();
+            // runtimeService3: Separate instance for orchestrator ready-state detection
+            // Isolated from runtimeService to prevent interference between init and ready checks
+            const runtimeService3 = this.createRuntimeService(runtimeType);
+            const isReady = await runtimeService3.waitForRuntimeReady(sessionName, 45000, checkInterval);
+            if (!isReady) {
+                throw new Error(`Failed to initialize ${runtimeType} in recreated orchestrator session within timeout`);
+            }
+            // Start runtime exit monitoring immediately after runtime is ready
+            RuntimeExitMonitorService.getInstance().startMonitoring(sessionName, runtimeType, role);
+            // Start OAuth relogin monitoring for automatic re-authentication
+            OAuthReloginMonitorService.getInstance().startMonitoring(sessionName, runtimeType);
+            // Additional verification: Use runtime detection to confirm runtime is responding
+            // Wait a bit longer for runtime to fully load after showing welcome message
+            this.logger.debug('Runtime ready detected for orchestrator, waiting for full startup before verification', { sessionName, runtimeType });
+            await delay(5000);
+            // Codex CLI is sensitive to active key-probe verification (it may drop to
+            // the shell when probe keys are interpreted outside the TUI). We already
+            // passed waitForRuntimeReady above, so skip the extra command probe here.
+            if (runtimeType !== RUNTIME_TYPES.CODEX_CLI) {
+                this.logger.debug('Verifying orchestrator runtime responsiveness', {
+                    sessionName,
+                    runtimeType,
+                });
+                // runtimeService4: Final verification instance for orchestrator responsiveness
+                // Clean instance for post-initialization responsiveness testing
+                const runtimeService4 = this.createRuntimeService(runtimeType);
+                const runtimeResponding = await runtimeService4.detectRuntimeWithCommand(sessionName);
+                if (!runtimeResponding) {
+                    throw new Error(`${runtimeType} not responding to commands after orchestrator recreation`);
+                }
+            }
+            else {
+                this.logger.debug('Skipping active runtime probe for Codex orchestrator recreation', {
+                    sessionName,
+                    runtimeType,
+                });
+            }
+            this.logger.debug('Runtime confirmed ready for orchestrator in Step 3', { sessionName, runtimeType });
+        }
+        else {
+            // For other roles, create basic session and initialize Claude (always fresh start)
+            await (await this.getSessionHelper()).createSession(sessionName, projectPath || process.cwd());
+            const runtimeService = this.createRuntimeService(runtimeType);
+            await runtimeService.executeRuntimeInitScript(sessionName, projectPath, effectiveFlags, promptFilePath, agentName);
+            // Wait for runtime to be ready (simplified detection)
+            const checkInterval = this.getCheckInterval();
+            const isReady = await this.createRuntimeService(runtimeType)
+                .waitForRuntimeReady(sessionName, 25000, checkInterval); // 25s timeout
+            if (!isReady) {
+                throw new Error(`Failed to initialize ${runtimeType} in recreated session within timeout`);
+            }
+            // Start runtime exit monitoring immediately after runtime is ready
+            RuntimeExitMonitorService.getInstance().startMonitoring(sessionName, runtimeType, role);
+            // Start OAuth relogin monitoring for automatic re-authentication
+            OAuthReloginMonitorService.getInstance().startMonitoring(sessionName, runtimeType);
+        }
+        // Look up per-agent browser automation override from member config
+        let browserOverrideForRecreation;
+        if (memberId) {
+            try {
+                const teams = await this.storageService.getTeams();
+                for (const team of teams) {
+                    const member = team.members?.find((m) => m.id === memberId || m.sessionName === sessionName);
+                    if (member?.enableBrowserAutomation !== undefined) {
+                        browserOverrideForRecreation = member.enableBrowserAutomation;
+                        break;
+                    }
+                }
+            }
+            catch {
+                // Non-fatal — will use global setting
+            }
+        }
+        // Run post-initialization hook (e.g., Gemini CLI directory allowlist)
+        try {
+            const postInitService = this.createRuntimeService(runtimeType);
+            await postInitService.postInitialize(sessionName, projectPath, undefined, browserOverrideForRecreation);
+            // Drain stale terminal escape sequences (e.g. DA1 [?1;2c) that may have
+            // arrived during postInitialize commands, so they don't leak into the prompt input
+            await delay(500);
+            // Claude Code: Ctrl+C + Ctrl+U to clear any stale input.
+            // Gemini CLI (Ink TUI): Do NOT send any cleanup keystrokes.
+            // Escape defocuses the Ink TUI input permanently. Ctrl+C at empty
+            // prompt triggers /quit. Ctrl+U is ignored. The delay above is
+            // sufficient to drain stale escape sequences.
+            if (runtimeType === RUNTIME_TYPES.CLAUDE_CODE) {
+                await (await this.getSessionHelper()).clearCurrentCommandLine(sessionName);
+            }
+        }
+        catch (postInitError) {
+            this.logger.warn('Post-initialization hook failed after recreation (non-fatal)', {
+                sessionName,
+                runtimeType,
+                error: postInitError instanceof Error ? postInitError.message : String(postInitError),
+            });
+        }
+        // For PTY sessions, once runtime is detected as ready, consider initialization successful
+        this.logger.info('Runtime detected as ready after full recreation, session initialization successful', {
+            sessionName,
+            role,
+            runtimeType,
+        });
+        // Background: detect and store session ID for resume-on-restart
+        if (runtimeType === RUNTIME_TYPES.CLAUDE_CODE) {
+            const detectPath = projectPath || process.cwd();
+            setTimeout(() => {
+                this.detectAndStoreSessionId(sessionName, detectPath).catch(() => { });
+            }, 10000);
+        }
+        // Send the registration prompt in background (don't block on it)
+        this.sendRegistrationPromptAsync(sessionName, role, memberId, runtimeType).catch((err) => {
+            this.logger.warn('Background registration prompt failed after recreation (non-blocking)', {
+                sessionName,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        });
+        // Update agent status to 'started' since the runtime is running
+        // The agent will become 'active' only after it registers via the API endpoint
+        try {
+            await this.storageService.updateAgentStatus(sessionName, CREWLY_CONSTANTS.AGENT_STATUSES.STARTED);
+            this.logger.info('Agent status updated to started after recreation (awaiting registration)', { sessionName, role });
+        }
+        catch (statusError) {
+            this.logger.warn('Failed to update agent status after recreation (non-critical)', {
+                sessionName,
+                error: statusError instanceof Error ? statusError.message : String(statusError),
+            });
+        }
+        return true;
+    }
+    /**
+     * Register a crewly-agent member as active by updating its team config directly.
+     * In-process agents cannot run bash scripts, so this performs the registration
+     * that the register-self skill would normally do for PTY-based runtimes.
+     *
+     * @param sessionName - Agent session name
+     * @param role - Agent role
+     * @param memberId - Optional member UUID
+     * @returns True if registration succeeded
+     */
+    async registerMemberActive(sessionName, role, memberId) {
+        try {
+            // Handle orchestrator separately — its config is stored outside getTeams()
+            if (sessionName === ORCHESTRATOR_SESSION_NAME) {
+                await this.storageService.updateOrchestratorStatus(CREWLY_CONSTANTS.AGENT_STATUSES.ACTIVE);
+                this.logger.info('Orchestrator registered as active via config', { sessionName });
+                return true;
+            }
+            const teams = await this.storageService.getTeams();
+            for (const team of teams) {
+                const member = team.members.find((m) => (m.sessionName === sessionName) ||
+                    (memberId !== undefined && m.id === memberId));
+                if (member) {
+                    member.agentStatus = 'active';
+                    member.workingStatus = 'idle';
+                    member.updatedAt = new Date().toISOString();
+                    // Pre-populate sessionName so register_self tool can find this member
+                    if (!member.sessionName && sessionName) {
+                        member.sessionName = sessionName;
+                    }
+                    await this.storageService.saveTeam(team);
+                    this.logger.info('Member registered as active', { sessionName, teamId: team.id });
+                    // #167: Drain dead-letter queue for newly active agent
+                    if (this.schedulerService) {
+                        this.schedulerService.drainDeadLetterQueue(sessionName).catch((err) => {
+                            this.logger.warn('Failed to drain DLQ on activation (non-critical)', {
+                                sessionName,
+                                error: err.message,
+                            });
+                        });
+                    }
+                    // Architecture Upgrade Phase 6: set up standing task event subscriptions
+                    this.setupStandingSubscriptions(sessionName, member.canDelegate ? 'team-lead' : 'executor', team.id);
+                    return true;
+                }
+            }
+            this.logger.warn('Could not find member to register as active', { sessionName, memberId });
+            return false;
+        }
+        catch (error) {
+            this.logger.error('Failed to register member as active', {
+                sessionName,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return false;
+        }
+    }
+    /**
+     * Set up standing event subscriptions for task workflow events based on org role.
+     * Called once at agent registration. Subscriptions are long-lived (24h TTL)
+     * and NOT oneShot — they persist for the agent's session lifetime.
+     *
+     * Orchestrator: task:verified, task:blocked, task:failed (all teams)
+     * Team Lead: task:done, task:blocked, task:failed, task:needs_clarification (own team)
+     * Executor: task:assigned (self scope)
+     *
+     * @param sessionName - Agent session name
+     * @param orgRole - Organizational role (orchestrator, team-lead, executor)
+     * @param teamId - Team ID for scoping (optional for orchestrator)
+     */
+    setupStandingSubscriptions(sessionName, orgRole, teamId) {
+        if (!this.eventBusService) {
+            this.logger.debug('EventBusService not available, skipping standing subscriptions', { sessionName });
+            return;
+        }
+        const TTL_MINUTES = 60 * 24; // 24 hours
+        try {
+            if (orgRole === 'orchestrator') {
+                // Orchestrator: awareness-only subscriptions for all teams
+                for (const eventType of ['task:verified', 'task:blocked', 'task:failed', 'team:all_tasks_done']) {
+                    this.eventBusService.subscribe({
+                        eventType,
+                        filter: {},
+                        subscriberSession: sessionName,
+                        oneShot: false,
+                        ttlMinutes: TTL_MINUTES,
+                    });
+                }
+                this.logger.info('Standing subscriptions set up for orchestrator', { sessionName });
+            }
+            else if (orgRole === 'team-lead') {
+                // TL: own team scope
+                for (const eventType of ['task:done', 'task:blocked', 'task:failed', 'task:needs_clarification']) {
+                    this.eventBusService.subscribe({
+                        eventType,
+                        filter: teamId ? { teamId } : {},
+                        subscriberSession: sessionName,
+                        oneShot: false,
+                        ttlMinutes: TTL_MINUTES,
+                    });
+                }
+                this.logger.info('Standing subscriptions set up for team-lead', { sessionName, teamId });
+            }
+            else {
+                // Executor: self scope only
+                this.eventBusService.subscribe({
+                    eventType: 'task:assigned',
+                    filter: { sessionName },
+                    subscriberSession: sessionName,
+                    oneShot: false,
+                    ttlMinutes: TTL_MINUTES,
+                });
+                this.logger.info('Standing subscription set up for executor', { sessionName });
+            }
+        }
+        catch (err) {
+            this.logger.warn('Failed to set up standing subscriptions (non-fatal)', {
+                sessionName,
+                orgRole,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    /**
+     * Load registration prompt from config files (with caching to prevent file I/O contention)
+     */
+    async loadRegistrationPrompt(role, sessionName, memberId, runtimeType = RUNTIME_TYPES.CLAUDE_CODE) {
+        try {
+            // Cache key is role only - the template file is the same regardless of memberId
+            const cacheKey = role;
+            // Check cache first to avoid file I/O during concurrent operations
+            if (!this.promptCache.has(cacheKey)) {
+                this.logger.debug('Loading prompt template from file', { role, cacheKey });
+                // Get the prompt file path from team roles configuration
+                const promptPath = await this.getPromptFileForRole(role);
+                const promptTemplate = await readFile(promptPath, 'utf8');
+                this.promptCache.set(cacheKey, promptTemplate);
+                this.logger.debug('Prompt template cached', { role, cacheKey, promptPath });
+            }
+            else {
+                this.logger.debug('Using cached prompt template', { role, cacheKey });
+            }
+            // Get cached template and apply variable replacements
+            let prompt = this.promptCache.get(cacheKey);
+            // Replace all template placeholders
+            prompt = prompt.replace(/\{\{SESSION_ID\}\}/g, sessionName);
+            prompt = prompt.replace(/\{\{SESSION_NAME\}\}/g, sessionName);
+            prompt = prompt.replace(/\{\{ROLE\}\}/g, role);
+            if (memberId) {
+                prompt = prompt.replace(/\{\{MEMBER_ID\}\}/g, memberId);
+            }
+            else {
+                // For orchestrator or cases without member ID, remove the memberId parameter
+                prompt = prompt.replace(/,\s*"memberId":\s*"\{\{MEMBER_ID\}\}"/g, '');
+            }
+            // Look up project path and TL hierarchy for team members
+            let projectPath = process.cwd();
+            let foundTeam = null;
+            let foundMember = null;
+            try {
+                const teams = await this.storageService.getTeams();
+                for (const team of teams) {
+                    const member = team.members?.find((m) => m.sessionName === sessionName);
+                    if (member) {
+                        foundTeam = team;
+                        foundMember = member;
+                        if (team.projectIds[0]) {
+                            const projects = await this.storageService.getProjects();
+                            const project = projects.find((p) => p.id === team.projectIds[0]);
+                            if (project?.path) {
+                                projectPath = project.path;
+                            }
+                        }
+                        break;
+                    }
+                }
+            }
+            catch {
+                // Non-critical - use default project path
+            }
+            // Write runtime-specific project config file so the agent CLI
+            // recognizes Crewly as a legitimate project configuration (fixes #33)
+            // Claude Code → .crewly/CLAUDE.md, Gemini CLI → GEMINI.md, Codex → AGENTS.md
+            if (role !== ORCHESTRATOR_ROLE) {
+                await this.provisionRuntimeConfigFile(projectPath, runtimeType);
+            }
+            // Replace project path placeholder (must happen after project path lookup above)
+            prompt = prompt.replace(/\{\{PROJECT_PATH\}\}/g, projectPath);
+            // Replace agent skills path placeholder
+            const agentSkillsPath = path.join(this.projectRoot, 'config', 'skills', 'agent');
+            prompt = prompt.replace(/\{\{AGENT_SKILLS_PATH\}\}/g, agentSkillsPath);
+            // Replace orchestrator skills path placeholder — ensures skill scripts
+            // resolve correctly regardless of the orchestrator's working directory
+            const orchestratorSkillsPath = path.join(this.projectRoot, 'config', 'skills', 'orchestrator');
+            prompt = prompt.replace(/\{\{ORCHESTRATOR_SKILLS_PATH\}\}/g, orchestratorSkillsPath);
+            // Replace marketplace skills path placeholder
+            const marketplaceSkillsPath = path.join(os.homedir(), '.crewly', 'marketplace', 'skills');
+            prompt = prompt.replace(/\{\{MARKETPLACE_SKILLS_PATH\}\}/g, marketplaceSkillsPath);
+            // #210: Inject member's systemPrompt if available
+            // This contains role context and authorization info that the agent needs at startup
+            if (foundTeam && foundMember?.id) {
+                try {
+                    const memberPrompt = await this.storageService.getMemberPrompt(foundTeam.id, foundMember.id);
+                    if (memberPrompt && memberPrompt.trim()) {
+                        prompt = memberPrompt.trim() + '\n\n' + prompt;
+                        this.logger.info('Member systemPrompt prepended to init prompt', {
+                            sessionName,
+                            memberId: foundMember.id,
+                            systemPromptLength: memberPrompt.length,
+                        });
+                    }
+                }
+                catch (err) {
+                    this.logger.warn('Failed to load member systemPrompt (non-critical)', {
+                        sessionName,
+                        memberId: foundMember.id,
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                }
+            }
+            // Inject skill authorization section — tells agents about available capabilities
+            prompt += '\n\n## Available Capabilities\n\n'
+                + 'This session has browser automation enabled via the Playwright MCP server. '
+                + 'Browser skills (e.g. remote-browser) are the preferred way to perform browser tasks. '
+                + 'Bash skills in the Crewly skills directory are available for team communication and status reporting.';
+            // Inject Team Lead addon for members with canDelegate=true and subordinates
+            if (foundMember?.canDelegate && foundMember.subordinateIds && foundMember.subordinateIds.length > 0 && foundTeam) {
+                try {
+                    // Resolve subordinateIds to SubordinateInfo[]
+                    const subordinates = foundMember.subordinateIds
+                        .map((subId) => {
+                        const subMember = foundTeam.members?.find((m) => m.id === subId);
+                        if (!subMember)
+                            return null;
+                        return {
+                            name: subMember.name,
+                            sessionName: subMember.sessionName || '',
+                            role: subMember.role || 'developer',
+                            memberId: subMember.id || subId,
+                        };
+                    })
+                        .filter((s) => s !== null);
+                    if (subordinates.length > 0) {
+                        const tlConfig = {
+                            name: sessionName,
+                            role: role,
+                            systemPrompt: '',
+                            projectPath,
+                            memberId,
+                            teamId: foundTeam.id,
+                            canDelegate: true,
+                            subordinates,
+                        };
+                        const promptBuilder = new PromptBuilderService(this.projectRoot);
+                        const tlSection = await promptBuilder.buildTeamLeadSection(tlConfig);
+                        if (tlSection) {
+                            prompt += `\n\n---\n\n${tlSection}`;
+                            this.logger.info('TL addon injected into init prompt', {
+                                sessionName,
+                                subordinateCount: subordinates.length,
+                                subordinateNames: subordinates.map((s) => s.name),
+                                tlSectionLength: tlSection.length,
+                            });
+                        }
+                    }
+                }
+                catch (tlError) {
+                    this.logger.warn('Failed to inject TL addon (non-critical)', {
+                        sessionName,
+                        error: tlError instanceof Error ? tlError.message : String(tlError),
+                    });
+                }
+            }
+            // Issue #395: Inject the authoritative active-work briefing FIRST,
+            // so the agent's reading order is "what am I on the hook for RIGHT
+            // NOW" before the supplementary memory context. Soft-fail with WARN
+            // — TaskPool/Request hiccups must not block agent boot.
+            try {
+                // ActiveWorkBriefingService.getInstance() is async — see service
+                // JSDoc. Dynamic-import migration was the build-fix for PR #494's
+                // broken relative-path resolution under entry-script anchoring.
+                const activeWorkService = await ActiveWorkBriefingService.getInstance();
+                const activeWorkBriefing = await activeWorkService.generateActiveWorkBriefing(sessionName, role);
+                const activeWorkMd = activeWorkService.formatBriefingAsMarkdown(activeWorkBriefing);
+                if (activeWorkMd && activeWorkMd.length > 30) {
+                    prompt += `\n\n---\n\n${activeWorkMd}`;
+                    this.logger.info('Active-work briefing injected into prompt', {
+                        sessionName,
+                        role,
+                        openRequests: activeWorkBriefing.openRequests.length,
+                        activeWorkItems: activeWorkBriefing.activeWorkItems.length,
+                        pendingReviews: activeWorkBriefing.pendingReviews.length,
+                        outboundDelegations: activeWorkBriefing.outboundDelegations.length,
+                        recentlyAutoResolved: activeWorkBriefing.recentlyAutoResolved.length,
+                        truncated: activeWorkBriefing.truncated,
+                        briefingLength: activeWorkMd.length,
+                    });
+                }
+            }
+            catch (activeWorkError) {
+                this.logger.warn('Failed to generate active-work briefing (non-critical)', {
+                    sessionName,
+                    error: activeWorkError instanceof Error ? activeWorkError.message : String(activeWorkError),
+                });
+            }
+            // Generate and inject startup briefing from session memory
+            try {
+                const sessionMemoryService = SessionMemoryService.getInstance();
+                await sessionMemoryService.onSessionStart(sessionName, role, projectPath);
+                const briefing = await sessionMemoryService.generateStartupBriefing(sessionName, role, projectPath);
+                const briefingMd = sessionMemoryService.formatBriefingAsMarkdown(briefing);
+                if (briefingMd && briefingMd.length > 30) {
+                    prompt += `\n\n---\n\n${briefingMd}`;
+                    this.logger.info('Startup briefing injected into prompt', { sessionName, role, briefingLength: briefingMd.length });
+                }
+            }
+            catch (briefingError) {
+                this.logger.warn('Failed to generate startup briefing (non-critical)', {
+                    sessionName,
+                    error: briefingError instanceof Error ? briefingError.message : String(briefingError),
+                });
+            }
+            // Inject mandatory session recovery protocol (recall + get-my-context)
+            try {
+                const recoveryBuilder = new PromptBuilderService(this.projectRoot);
+                const recoverySection = recoveryBuilder.buildSessionRecoverySection(sessionName, role, projectPath);
+                prompt += `\n\n---\n\n${recoverySection}`;
+                this.logger.info('Session recovery protocol injected into prompt', { sessionName, role });
+            }
+            catch (recoveryError) {
+                this.logger.warn('Failed to inject session recovery protocol (non-critical)', {
+                    sessionName,
+                    error: recoveryError instanceof Error ? recoveryError.message : String(recoveryError),
+                });
+            }
+            // Append identity section so the agent knows its session name and project path
+            prompt += `\n\n---\n\n## Your Identity\n- **Session Name:** ${sessionName}\n- **Project Path:** ${projectPath}`;
+            if (memberId) {
+                prompt += `\n- **Member ID:** ${memberId}`;
+            }
+            // Conditionally append Self Evolution instructions for the orchestrator
+            if (role === ORCHESTRATOR_ROLE) {
+                try {
+                    const settings = await getSettingsService().getSettings();
+                    if (settings.general.enableSelfEvolution) {
+                        const selfEvoPath = path.join(this.projectRoot, 'config', 'roles', 'orchestrator', 'self-evolution.md');
+                        const selfEvoPrompt = await readFile(selfEvoPath, 'utf8');
+                        prompt += `\n\n---\n\n${selfEvoPrompt}`;
+                        this.logger.info('Self Evolution prompt injected', { sessionName });
+                    }
+                }
+                catch (selfEvoError) {
+                    this.logger.warn('Failed to load self-evolution prompt (non-critical)', {
+                        sessionName,
+                        error: selfEvoError instanceof Error ? selfEvoError.message : String(selfEvoError),
+                    });
+                }
+            }
+            // Phase 5: Use modular prompt assembly (enabled by default, disable with CREWLY_USE_MODULAR_PROMPTS=false).
+            // Replaces the entire monolithic template with PromptAssemblyService — handling identity,
+            // skills, communication, recovery, lifecycle, memory, soul, and team-reference modules
+            // with token budget enforcement.
+            if (process.env.CREWLY_USE_MODULAR_PROMPTS !== 'false') {
+                this.logger.info('Using modular prompt assembly (Phase 5)', { sessionName, role });
+                const agentSkillsPath = path.join(this.projectRoot, 'config', 'skills', 'agent');
+                const tlSkillsPath = path.join(this.projectRoot, 'config', 'skills', 'team-leader');
+                // Pre-compute the subordinate roster — used by both the helper
+                // path (passed via runtime.subordinates) and the orchestrator
+                // fallback path below.
+                const subordinates = foundMember?.subordinateIds
+                    ?.map((subId) => {
+                    const subMember = foundTeam?.members?.find((m) => m.id === subId);
+                    if (!subMember)
+                        return null;
+                    return {
+                        name: subMember.name,
+                        sessionName: subMember.sessionName || '',
+                        role: subMember.role || 'developer',
+                        memberId: subMember.id || subId,
+                    };
+                })
+                    .filter((s) => s !== null);
+                const teamNormsPath = foundTeam?.id
+                    ? path.join(os.homedir(), CREWLY_CONSTANTS.PATHS.CREWLY_HOME, 'teams', foundTeam.id, 'norms')
+                    : undefined;
+                let moduleConfig;
+                if (foundMember && foundTeam) {
+                    // WIRE-2: When the agent is a TeamMember of a Team, build the
+                    // canonical ModuleConfig via the shared helper so every
+                    // autonomy / org / team-level field reaches the assembler.
+                    // Caller-side overlay covers the two registration-specific
+                    // fields the helper doesn't know about (teamNormsPath +
+                    // the registration's `memberId` override which may differ
+                    // from member.id when the caller passed an explicit id).
+                    const runtime = {
+                        sessionName,
+                        projectPath,
+                        runtimeType: runtimeType,
+                        subordinates,
+                        agentSkillsPath,
+                        tlSkillsPath,
+                        projectRoot: this.projectRoot,
+                    };
+                    moduleConfig = {
+                        ...buildModuleConfigFromTeamMember(foundMember, foundTeam, runtime),
+                        memberId: memberId ?? foundMember.id ?? '',
+                        teamNormsPath,
+                    };
+                }
+                else {
+                    // Orchestrator + legacy paths: foundMember/foundTeam not
+                    // present (orchestrator config lives outside getTeams()).
+                    // Keep the inline fallback so registration still works for
+                    // the orchestrator and any caller without team context.
+                    moduleConfig = {
+                        sessionName,
+                        memberId: memberId ?? '',
+                        role,
+                        teamId: foundTeam?.id,
+                        projectPath,
+                        runtimeType: runtimeType,
+                        canDelegate: foundMember?.canDelegate,
+                        subordinates,
+                        agentSkillsPath,
+                        tlSkillsPath,
+                        projectRoot: this.projectRoot,
+                        orgRole: role === 'orchestrator' ? 'orchestrator'
+                            : foundMember?.canDelegate ? 'team-lead'
+                                : 'executor',
+                        autonomyLevel: foundMember?.autonomyLevel ?? 'directed',
+                        teamNormsPath,
+                    };
+                }
+                const assembler = new PromptAssemblyService();
+                const { prompt: modularPrompt, report } = await assembler.assemble(moduleConfig);
+                this.logger.info('Modular prompt assembled for registration', {
+                    sessionName,
+                    role,
+                    totalTokens: report.totalTokens,
+                    moduleCount: report.moduleBreakdown.length,
+                    truncatedCount: report.truncated.length,
+                    modules: report.moduleBreakdown.map(m => m.name),
+                });
+                return modularPrompt;
+            }
+            return prompt;
+        }
+        catch (error) {
+            // Fallback to inline prompt if file doesn't exist
+            const attemptedPath = await this.getPromptFileForRole(role);
+            // Distinguish "role prompt simply absent" (team-config uses a
+            // custom role string, fallback covers it) from genuine read
+            // failures (permission denied, corrupt file). ENOENT is a
+            // common case — e.g. CE team config currently uses
+            // `role: "tech-lead"` while the filesystem canonical is
+            // `team-leader`. The fallback inline prompt is functionally
+            // sufficient; ERROR-level noise just buries real issues.
+            const msg = error instanceof Error ? error.message : String(error);
+            const isMissingFile = /ENOENT/.test(msg);
+            this.logger[isMissingFile ? 'warn' : 'error']('Could not load prompt from config, using fallback', {
+                role,
+                promptPath: attemptedPath,
+                error: msg,
+                ...(isMissingFile ? {} : { stack: error instanceof Error ? error.stack : undefined }),
+            });
+            const memberIdJson = memberId ? `,"teamMemberId":"${memberId}"` : '';
+            const skillsPath = path.join(this.projectRoot, 'config', 'skills', 'agent');
+            return `Hey! I need your help with some tasks on this project.
+
+## Quick context about this setup
+
+This project uses Crewly for team coordination. You have bash skills available at \`${skillsPath}/\` that communicate with the Crewly backend running locally. Read the skills catalog at \`~/.crewly/skills/AGENT_SKILLS_CATALOG.md\` for a full reference of available skills.
+
+## First thing - please check in
+
+Please run the register-self skill to let the team dashboard know you're available:
+\`\`\`bash
+bash ${skillsPath}/core/register-self/execute.sh '{"role":"${role}","sessionName":"${sessionName}"${memberIdJson}}'
+\`\`\`
+All it does is update a local status flag so the web UI shows you as online - nothing more.
+
+## Default Execution Loop
+
+When assigned a task, do not wait passively.
+
+Loop until done, blocked, or explicitly reassigned:
+1. Restate the expected outcome in one sentence.
+2. Identify the fastest safe path to produce a usable result.
+3. Execute immediately.
+4. Run cheapest meaningful validation.
+5. If validation fails, fix and retry.
+6. If blocked by missing goal/outcome/eval, escalate to your TL.
+7. If blocked by implementation detail, decide reasonably and continue.
+8. Report only when you have a result, blocker, or decision exceeding your authority.`;
+        }
+    }
+    /**
+     * Write the registration prompt to a file on disk.
+     *
+     * For Claude Code agents (#207): writes to `{projectPath}/.claude/agents/{sessionName}.md`
+     * with YAML frontmatter so the `--agent` flag can load it as a custom agent definition.
+     * For other runtimes: writes to `~/.crewly/prompts/{sessionName}-init.md`.
+     *
+     * @param sessionName - Session name (used for filename)
+     * @param prompt - The full prompt content
+     * @param options - Optional: projectPath, runtimeType, and role for claude-code agent mode
+     * @returns The absolute path to the written file, or undefined on error
+     */
+    async writePromptFile(sessionName, prompt, options) {
+        const isClaudeAgent = options?.runtimeType === RUNTIME_TYPES.CLAUDE_CODE && options?.projectPath;
+        const promptFilePath = isClaudeAgent
+            ? path.join(options.projectPath, '.claude', 'agents', `${sessionName}.md`)
+            : this.getInitPromptFilePath(sessionName);
+        const promptsDir = path.dirname(promptFilePath);
+        // Quote YAML values to prevent injection via sessionName or role containing special chars
+        const yamlSafeName = sessionName.replace(/"/g, '\\"');
+        const yamlSafeRole = (options?.role || 'developer').replace(/"/g, '\\"');
+        const fileContent = isClaudeAgent
+            ? `---\nname: "${yamlSafeName}"\ndescription: "${yamlSafeRole} agent for Crewly orchestration"\n---\n\n${prompt}`
+            : prompt;
+        try {
+            await mkdir(promptsDir, { recursive: true });
+            await writeFile(promptFilePath, fileContent, 'utf8');
+            this.logger.debug('Wrote init prompt to file', {
+                sessionName,
+                promptFilePath,
+                promptLength: fileContent.length,
+                mode: isClaudeAgent ? 'claude-agent' : 'legacy',
+            });
+            return promptFilePath;
+        }
+        catch (error) {
+            this.logger.warn('Failed to write init prompt file', {
+                sessionName,
+                promptFilePath,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return undefined;
+        }
+    }
+    /**
+     * Build the unified init prompt path used by non-Claude-Code runtimes.
+     *
+     * Anchored on {@link getCrewlyHomePath} so test profiles, KR3 livewalk
+     * dry-runs, and ESTestNode acceptance harnesses that export
+     * `CREWLY_HOME=/tmp/...` write into the test profile, not the
+     * developer's real `~/.crewly/prompts`. WI-F (2026-05-07): the
+     * previous `path.join(os.homedir(), CREWLY_CONSTANTS.PATHS.CREWLY_HOME,
+     * ...)` form ignored the env var and let Mia's KR3 livewalk overwrite
+     * 27 occurrences of `~/.crewly/prompts/crewly-orc-init.md` and 26 of
+     * `crewly-auditor-init.md` in Steve's user-prod tree at 02:37Z.
+     */
+    getInitPromptFilePath(sessionName) {
+        return path.join(getCrewlyHomePath(), 'prompts', `${sessionName}-init.md`);
+    }
+    /**
+     * Wait for agent registration to complete
+     */
+    async waitForRegistration(sessionName, role, timeout) {
+        const startTime = Date.now();
+        const checkInterval = 5000; // Check every 5 seconds to prevent overlapping with `/` detection
+        while (Date.now() - startTime < timeout) {
+            try {
+                if (await this.checkAgentRegistration(sessionName, role)) {
+                    this.logger.info('Agent registration confirmed', { sessionName, role });
+                    return true;
+                }
+                await delay(checkInterval);
+            }
+            catch (error) {
+                this.logger.warn('Error checking registration', {
+                    sessionName,
+                    role,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                await delay(checkInterval);
+            }
+        }
+        this.logger.warn('Timeout waiting for agent registration', { sessionName, role, timeout });
+        return false;
+    }
+    /**
+     * Check if agent is properly registered
+     */
+    async checkAgentRegistration(sessionName, role) {
+        try {
+            if (role === ORCHESTRATOR_ROLE) {
+                // For orchestrator, check agentStatus is active
+                const orchestratorStatus = await this.storageService.getOrchestratorStatus();
+                return orchestratorStatus?.agentStatus === CREWLY_CONSTANTS.AGENT_STATUSES.ACTIVE;
+            }
+            // For team members, check teams data
+            const teams = await this.storageService.getTeams();
+            // Find team member with matching sessionName and check agentStatus
+            for (const team of teams) {
+                if (team.members) {
+                    for (const member of team.members) {
+                        if (member.sessionName === sessionName && member.role === role) {
+                            return member.agentStatus === CREWLY_CONSTANTS.AGENT_STATUSES.ACTIVE;
+                        }
+                    }
+                }
+            }
+            return false;
+        }
+        catch (error) {
+            this.logger.debug('Error checking agent registration', {
+                sessionName,
+                role,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return false;
+        }
+    }
+    /**
+     * Fast registration with verification and retry mechanism
+     * Sends system prompt to runtime which triggers MCP registration via teams.json
+     * @param skipInitialCleanup If true, skips Ctrl+C on first attempt (when runtime was just initialized)
+     */
+    async attemptRegistrationWithVerification(sessionName, role, timeout, memberId, maxRetries = 3, skipInitialCleanup = false, runtimeType = RUNTIME_TYPES.CLAUDE_CODE) {
+        for (let attempt = 1; attempt <= maxRetries; attempt++) {
+            this.logger.info('Attempting system prompt registration with MCP flow', {
+                sessionName,
+                role,
+                runtimeType,
+                attempt,
+                maxRetries,
+            });
+            try {
+                // Step 1: Send Ctrl+C to clear any pending commands (skip on first attempt if Claude was just initialized)
+                if (!skipInitialCleanup || attempt > 1) {
+                    await (await this.getSessionHelper()).clearCurrentCommandLine(sessionName);
+                    await delay(500);
+                    this.logger.debug('Sent Ctrl+C to clear terminal state', {
+                        sessionName,
+                        attempt,
+                    });
+                }
+                else {
+                    this.logger.debug('Skipping Ctrl+C on first attempt (Claude was just initialized)', { sessionName, attempt });
+                }
+                // Step 2: Verify runtime is running (skip detection if runtime was just initialized and verified)
+                let runtimeRunning = true; // Assume true if we skip detection
+                if (!skipInitialCleanup || attempt > 1) {
+                    // Only do runtime detection on retries or when runtime wasn't just initialized
+                    const forceRefresh = attempt > 1; // Force refresh on retry attempts
+                    const runtimeService5 = this.createRuntimeService(runtimeType);
+                    runtimeRunning = await runtimeService5.detectRuntimeWithCommand(sessionName, forceRefresh);
+                    if (!runtimeRunning) {
+                        this.logger.warn('Runtime not detected, cannot send system prompt', {
+                            sessionName,
+                            runtimeType,
+                            attempt,
+                            forceRefresh,
+                        });
+                        // Clear detection cache before continuing to retry
+                        const runtimeService6 = this.createRuntimeService(runtimeType);
+                        runtimeService6.clearDetectionCache(sessionName);
+                        // Add longer delay between failed detection attempts
+                        if (attempt < maxRetries) {
+                            await delay(2000);
+                        }
+                        continue; // Try again
+                    }
+                }
+                else {
+                    this.logger.debug('Skipping runtime detection (runtime was just initialized and verified)', {
+                        sessionName,
+                        runtimeType,
+                        attempt,
+                    });
+                }
+                // Step 3: Send system prompt with robust delivery mechanism
+                const prompt = await this.loadRegistrationPrompt(role, sessionName, memberId, runtimeType);
+                const promptDelivered = await this.sendPromptRobustly(sessionName, prompt, runtimeType);
+                if (!promptDelivered) {
+                    this.logger.warn('Failed to deliver system prompt reliably', {
+                        sessionName,
+                        attempt,
+                        promptLength: prompt.length,
+                    });
+                    continue; // Try again
+                }
+                this.logger.debug('System prompt delivered successfully', {
+                    sessionName,
+                    promptLength: prompt.length,
+                });
+                this.logger.debug('Terminal activity detected, waiting for MCP registration', {
+                    sessionName,
+                });
+                // Step 5: Wait for registration API call to update teams.json (agentStatus: activating -> active)
+                const registrationTimeout = Math.min(timeout, 25000); // Max 25s per attempt
+                const registered = await this.waitForRegistrationFast(sessionName, role, registrationTimeout);
+                if (registered) {
+                    this.logger.info('MCP registration successful (teams.json updated)', {
+                        sessionName,
+                        role,
+                        attempt,
+                    });
+                    return true;
+                }
+                this.logger.warn('MCP registration timeout, retrying', {
+                    sessionName,
+                    role,
+                    attempt,
+                    nextAttempt: attempt < maxRetries,
+                });
+            }
+            catch (error) {
+                this.logger.error('System prompt registration attempt failed', {
+                    sessionName,
+                    role,
+                    attempt,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+            // Short delay before retry
+            if (attempt < maxRetries) {
+                await delay(1000);
+            }
+        }
+        this.logger.warn('Background MCP registration did not complete within timeout (agent still running)', {
+            sessionName,
+            role,
+            runtimeType,
+            maxRetries,
+        });
+        return false;
+    }
+    /**
+     * Fast registration polling with shorter intervals
+     */
+    async waitForRegistrationFast(sessionName, role, timeout) {
+        const startTime = Date.now();
+        const fastCheckInterval = 2000; // Check every 2 seconds (faster than original 5s)
+        while (Date.now() - startTime < timeout) {
+            try {
+                if (await this.checkAgentRegistration(sessionName, role)) {
+                    this.logger.info('Fast registration confirmation', { sessionName, role });
+                    return true;
+                }
+                await delay(fastCheckInterval);
+            }
+            catch (error) {
+                this.logger.debug('Error in fast registration check', {
+                    sessionName,
+                    role,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                await delay(1000); // Shorter error delay
+            }
+        }
+        this.logger.warn('Fast registration timeout', { sessionName, role, timeout });
+        return false;
+    }
+    /**
+     * Create orchestrator session - extracted from the original tmux service
+     */
+    async createOrchestratorSession(config) {
+        this.logger.info('Creating orchestrator session', {
+            sessionName: config.sessionName,
+            projectPath: config.projectPath,
+        });
+        // Check if session already exists
+        if (await (await this.getSessionHelper()).sessionExists(config.sessionName)) {
+            this.logger.info('Orchestrator session already exists', {
+                sessionName: config.sessionName,
+            });
+            return;
+        }
+        // Create new session for orchestrator
+        await (await this.getSessionHelper()).createSession(config.sessionName, config.projectPath
+        // windowName not used in PTY backend
+        );
+        this.logger.info('Orchestrator session created successfully', {
+            sessionName: config.sessionName,
+        });
+    }
+    /**
+     * Unified session creation that handles both orchestrator and team members
+     * @param config Session configuration
+     * @returns Promise with success/error information
+     */
+    async createAgentSession(config) {
+        // Fail fast if role is unusable. Without this guard, an undefined role
+        // flows through the entire pipeline, gets stringified to "undefined" in
+        // the CREWLY_ROLE env var, and silently breaks prompt resolution. We
+        // surface the misconfiguration here instead of spawning a dead session.
+        try {
+            validateAgentRole(config.role, 'createAgentSession');
+        }
+        catch (err) {
+            const error = err instanceof Error ? err.message : String(err);
+            this.logger.error('Refusing to create agent session with invalid role', {
+                sessionName: config.sessionName,
+                memberId: config.memberId,
+                teamId: config.teamId,
+                receivedRole: config.role,
+                error,
+            });
+            return {
+                success: false,
+                sessionName: config.sessionName,
+                error,
+            };
+        }
+        // If another creation is in progress for this session, wait for it
+        const existingLock = this.sessionCreationLocks.get(config.sessionName);
+        if (existingLock) {
+            this.logger.info('Waiting for existing session creation to complete', { sessionName: config.sessionName });
+            try {
+                return await existingLock;
+            }
+            catch {
+                // Previous creation failed, proceed with our own attempt
+                this.logger.info('Previous session creation failed, proceeding with new attempt', { sessionName: config.sessionName });
+            }
+        }
+        // Create and store the lock promise
+        const creationPromise = this._createAgentSessionImpl(config);
+        this.sessionCreationLocks.set(config.sessionName, creationPromise);
+        try {
+            const result = await creationPromise;
+            return result;
+        }
+        finally {
+            // Only delete lock if it's still ours — a concurrent caller may have
+            // replaced it with a new promise after our catch path above.
+            if (this.sessionCreationLocks.get(config.sessionName) === creationPromise) {
+                this.sessionCreationLocks.delete(config.sessionName);
+            }
+        }
+    }
+    /**
+     * Internal implementation of createAgentSession, guarded by sessionCreationLocks.
+     * @param config Session configuration
+     * @returns Promise with success/error information
+     */
+    async _createAgentSessionImpl(config) {
+        const { sessionName, role, projectPath = process.cwd(), windowName, memberId } = config;
+        const forceRecreate = config.forceRecreate ?? false;
+        // Get runtime type from config or default to claude-code
+        let runtimeType = config.runtimeType || RUNTIME_TYPES.CLAUDE_CODE;
+        // Resolve runtime flags from the agent's effective skills
+        let runtimeFlags = [];
+        // For team members, try to get runtime type from storage and resolve skill flags
+        if (!config.runtimeType && role !== ORCHESTRATOR_ROLE) {
+            try {
+                const teams = await this.storageService.getTeams();
+                for (const team of teams) {
+                    const member = team.members?.find((m) => m.sessionName === sessionName);
+                    if (member) {
+                        if (member.runtimeType) {
+                            runtimeType = member.runtimeType;
+                        }
+                        // Resolve runtime flags from role skills + member overrides
+                        runtimeFlags = await this.resolveRuntimeFlags(role, runtimeType, member.skillOverrides, member.excludedRoleSkills);
+                        break;
+                    }
+                }
+            }
+            catch (error) {
+                this.logger.warn('Failed to get runtime type or flags from storage, using defaults', {
+                    sessionName,
+                    role,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        else if (role !== ORCHESTRATOR_ROLE) {
+            // Config-provided runtimeType, still resolve flags
+            try {
+                const teams = await this.storageService.getTeams();
+                for (const team of teams) {
+                    const member = team.members?.find((m) => m.sessionName === sessionName);
+                    if (member) {
+                        runtimeFlags = await this.resolveRuntimeFlags(role, runtimeType, member.skillOverrides, member.excludedRoleSkills);
+                        break;
+                    }
+                }
+            }
+            catch (error) {
+                this.logger.warn('Failed to resolve runtime flags', {
+                    sessionName, role,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        // For orchestrator, try to get runtime type from orchestrator status
+        if (role === ORCHESTRATOR_ROLE && !config.runtimeType) {
+            try {
+                const orchestratorStatus = await this.storageService.getOrchestratorStatus();
+                if (orchestratorStatus?.runtimeType) {
+                    runtimeType = orchestratorStatus.runtimeType;
+                }
+            }
+            catch (error) {
+                this.logger.warn('Failed to get orchestrator runtime type from storage, using default', {
+                    sessionName,
+                    role,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        try {
+            this.logger.info('Creating agent session (unified approach)', {
+                sessionName,
+                role,
+                runtimeType,
+                projectPath,
+                windowName,
+                memberId,
+            });
+            // Get session helper first
+            this.logger.debug('Getting session helper for session creation');
+            const sessionHelper = await this.getSessionHelper();
+            this.logger.debug('Session helper obtained', {
+                hasHelper: !!sessionHelper,
+            });
+            // Check if session already exists
+            const sessionExists = sessionHelper.sessionExists(sessionName);
+            this.logger.debug('Checked if session exists', {
+                sessionName,
+                sessionExists,
+            });
+            if (!sessionExists) {
+                // Session doesn't exist, go directly to creating a new session
+                this.logger.info('Session does not exist, will create new session', { sessionName });
+            }
+            else if (forceRecreate) {
+                // Skip recovery, kill immediately (used during server startup for stale sessions)
+                this.logger.info('Session exists but forceRecreate is set, killing for clean restart', { sessionName });
+                try {
+                    const runtimeService = this.createRuntimeService(runtimeType);
+                    runtimeService.clearDetectionCache(sessionName);
+                    await (await this.getSessionHelper()).killSession(sessionName);
+                    await delay(1000);
+                }
+                catch (killError) {
+                    this.logger.warn('Failed to kill session during forceRecreate, continuing with recreation', {
+                        sessionName,
+                        error: killError instanceof Error ? killError.message : String(killError),
+                    });
+                }
+            }
+            else {
+                this.logger.info('Session already exists, attempting intelligent recovery instead of killing', {
+                    sessionName,
+                });
+                // Step 1: Try to detect if runtime is already running using slash command
+                const runtimeService = this.createRuntimeService(runtimeType);
+                let recoverySuccess = false;
+                try {
+                    const runtimeRunning = await runtimeService.detectRuntimeWithCommand(sessionName);
+                    if (runtimeRunning) {
+                        this.logger.info('Runtime detected in existing session, attempting direct registration', {
+                            sessionName,
+                        });
+                        // Try to send registration prompt directly
+                        const registrationResult = await this.attemptRegistrationWithVerification(sessionName, role, 25000, // 25 second timeout
+                        memberId, 1, // single attempt for now
+                        true, // skip initial cleanup since runtime is confirmed running
+                        runtimeType);
+                        if (registrationResult) {
+                            recoverySuccess = true;
+                            this.logger.info('Successfully registered existing session with runtime', { sessionName });
+                        }
+                    }
+                    // Step 2: If runtime not detected or registration failed, try Ctrl+C restart
+                    // only for Claude. Gemini/Codex treat Ctrl+C as destructive at prompt
+                    // and can exit the runtime instead of recovering.
+                    if (!recoverySuccess) {
+                        if (runtimeType !== RUNTIME_TYPES.CLAUDE_CODE) {
+                            this.logger.info('Skipping Ctrl+C recovery for non-Claude runtime; falling back to recreation', { sessionName, runtimeType });
+                            throw new Error(`${runtimeType} recovery requires full recreation`);
+                        }
+                        this.logger.info('Runtime not detected or registration failed, attempting Ctrl+C restart', {
+                            sessionName,
+                        });
+                        // Send Ctrl+C twice to try to restart Claude
+                        await (await this.getSessionHelper()).sendCtrlC(sessionName);
+                        await delay(1000);
+                        await (await this.getSessionHelper()).sendCtrlC(sessionName);
+                        await delay(2000);
+                        // Clear runtime detection cache after Ctrl+C restart
+                        runtimeService.clearDetectionCache(sessionName);
+                        // Try registration after Ctrl+C restart
+                        const postCtrlCResult = await this.attemptRegistrationWithVerification(sessionName, role, 25000, memberId, 1, // single attempt
+                        false, // don't skip cleanup after Ctrl+C
+                        runtimeType);
+                        if (postCtrlCResult) {
+                            recoverySuccess = true;
+                            this.logger.info('Successfully recovered session after Ctrl+C restart', { sessionName });
+                        }
+                    }
+                }
+                catch (error) {
+                    this.logger.warn('Error during intelligent session recovery', {
+                        sessionName,
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                }
+                // If recovery succeeded, register for persistence, start monitoring, and return early
+                if (recoverySuccess) {
+                    // Register session for state persistence so it survives restarts
+                    try {
+                        const persistence = getSessionStatePersistence();
+                        persistence.registerSession(sessionName, {
+                            cwd: projectPath || process.cwd(),
+                            command: process.env.SHELL || '/bin/bash',
+                            args: [],
+                        }, runtimeType, role, config.teamId, config.memberId);
+                    }
+                    catch (persistError) {
+                        this.logger.warn('Failed to register recovered session for persistence (non-critical)', {
+                            sessionName,
+                            error: persistError instanceof Error ? persistError.message : String(persistError),
+                        });
+                    }
+                    // Start context window monitoring for recovered non-orchestrator session
+                    if (role !== ORCHESTRATOR_ROLE && config.teamId && config.memberId) {
+                        ContextWindowMonitorService.getInstance().startSessionMonitoring(sessionName, config.memberId, config.teamId, role, runtimeType);
+                    }
+                    // Start OAuth relogin monitoring for recovered session
+                    OAuthReloginMonitorService.getInstance().startMonitoring(sessionName, runtimeType);
+                    return {
+                        success: true,
+                        sessionName,
+                        message: 'Agent session recovered and registered successfully',
+                    };
+                }
+                // Step 3: Last resort - fall back to killing session for clean restart
+                this.logger.warn('All recovery attempts failed, falling back to session recreation', {
+                    sessionName,
+                });
+                await (await this.getSessionHelper()).killSession(sessionName);
+                await delay(1000); // Wait for cleanup
+            }
+            // ===== In-process Crewly Agent branch =====
+            // Crewly Agent runs inside the Node.js process — no PTY session needed.
+            if (runtimeType === RUNTIME_TYPES.CREWLY_AGENT) {
+                this.logger.info('Starting in-process Crewly Agent runtime', { sessionName, role });
+                const crewlyRuntime = this.createRuntimeService(runtimeType);
+                // Look up modelId for this session.
+                //
+                // Resolution order:
+                //   1. Team-member lookup (storage.service.getTeams iterates persisted
+                //      team configs, matched by config.memberId).
+                //   2. Orchestrator fallback — storage.service.getTeams() explicitly
+                //      EXCLUDES the orchestrator directory (storage.service.ts:413),
+                //      so the orchestrator's modelId lives in teams/orchestrator/config.json
+                //      and must be read separately via getOrchestratorStatus().
+                //
+                // Without this orchestrator branch, the orchestrator's modelId would
+                // silently default to DEFAULT_MODEL even when configured.
+                let memberModelId;
+                if (config.memberId) {
+                    try {
+                        const teams = await this.storageService.getTeams();
+                        for (const team of teams) {
+                            const member = team.members?.find(m => m.id === config.memberId);
+                            if (member?.modelId) {
+                                memberModelId = member.modelId;
+                                break;
+                            }
+                        }
+                    }
+                    catch {
+                        // Non-critical — fall back to orchestrator/default model
+                    }
+                }
+                // Orchestrator fallback: getTeams() doesn't surface the orchestrator,
+                // so look it up via getOrchestratorStatus when this is the orchestrator
+                // session (or its virtual member id) and no team-level modelId was found.
+                const isOrchestrator = sessionName === ORCHESTRATOR_SESSION_NAME
+                    || config.memberId === 'orchestrator-member';
+                if (!memberModelId && isOrchestrator) {
+                    try {
+                        const orchestratorStatus = await this.storageService.getOrchestratorStatus();
+                        if (orchestratorStatus?.modelId) {
+                            memberModelId = orchestratorStatus.modelId;
+                        }
+                    }
+                    catch {
+                        // Non-critical — fall back to default model
+                    }
+                }
+                // Parse modelId into model config (falls back to DEFAULT_MODEL)
+                const { parseModelId } = await import('./crewly-agent/types.js');
+                const modelConfig = memberModelId ? { model: parseModelId(memberModelId) } : {};
+                // Determine role name for system prompt lookup
+                const roleName = role === ORCHESTRATOR_ROLE ? 'orchestrator' : role.toLowerCase().replace(/\s+/g, '-');
+                const memberId = config.memberId;
+                await crewlyRuntime.initializeInProcess(sessionName, { projectPath, memberId, ...modelConfig }, roleName);
+                // Track the in-process runtime for message routing.
+                // Mirror to the module-level registry so callers without an
+                // AgentRegistrationService reference (e.g. orchestrator-status
+                // service) can probe runtime liveness — fixes B0 isActive bug.
+                this.inProcessRuntimes.set(sessionName, crewlyRuntime);
+                registerInProcessRuntime(sessionName, crewlyRuntime);
+                // Auto-register agent as active — crewly-agent cannot run bash scripts,
+                // so we register on its behalf instead of relying on the register_self tool.
+                try {
+                    const registerResult = await this.registerMemberActive(sessionName, role, memberId);
+                    this.logger.info('Auto-registered crewly-agent as active', {
+                        sessionName, role, success: registerResult,
+                    });
+                }
+                catch (registerErr) {
+                    this.logger.warn('Auto-registration failed (non-fatal)', {
+                        sessionName,
+                        error: registerErr instanceof Error ? registerErr.message : String(registerErr),
+                    });
+                }
+                // For crewly-agent, the system prompt is already loaded during initializeInProcess().
+                // Do NOT deliver the full registration prompt as a message — that would trigger
+                // a redundant generateText call (60K chars → rate limits). Instead, send a
+                // lightweight activation message that tells the agent to start working.
+                //
+                // B0/B1 cold-start invariant: the orchestrator's `register_self` is performed
+                // by registerMemberActive() above (which writes directly to storage), so the
+                // orchestrator does NOT need an activation message. Skipping it here keeps
+                // `conversationHistory.messageCount === 0` after a fresh setup, which B1's
+                // fresh-install detector relies on. Subordinate agents still receive the
+                // activation kickoff because they are not auto-registered via storage.
+                if (sessionName !== ORCHESTRATOR_SESSION_NAME) {
+                    crewlyRuntime.handleMessage(`You are now active as "${role}" (session: ${sessionName}). ` +
+                        'Your system prompt is already loaded. Begin by calling register_self, ' +
+                        'then wait for tasks.').catch(promptError => {
+                        this.logger.warn('Initial activation message failed (non-fatal for crewly-agent)', {
+                            sessionName,
+                            error: promptError instanceof Error ? promptError.message : String(promptError),
+                        });
+                    });
+                }
+                else {
+                    this.logger.debug('Skipping initial activation message for orchestrator (cold-start invariant)', {
+                        sessionName,
+                    });
+                }
+                // Start context window monitoring if applicable
+                if (role !== ORCHESTRATOR_ROLE && config.teamId && config.memberId) {
+                    ContextWindowMonitorService.getInstance().startSessionMonitoring(sessionName, config.memberId, config.teamId, role, runtimeType);
+                }
+                return {
+                    success: true,
+                    sessionName,
+                    message: 'Crewly Agent in-process runtime initialized and registered',
+                };
+            }
+            // Create new session (same approach for both orchestrator and team members)
+            // #222: Use projectRoot (crewly install dir) as fallback instead of process.cwd()
+            const cwdToUse = projectPath || this.projectRoot || process.cwd();
+            this.logger.info('Creating PTY session', {
+                sessionName,
+                cwd: cwdToUse,
+            });
+            try {
+                const createdSession = await sessionHelper.createSession(sessionName, cwdToUse);
+                this.logger.info('PTY session created successfully', {
+                    sessionName,
+                    pid: createdSession.pid,
+                    cwd: createdSession.cwd,
+                });
+            }
+            catch (createError) {
+                this.logger.error('Failed to create PTY session', {
+                    sessionName,
+                    cwd: cwdToUse,
+                    error: createError instanceof Error ? createError.message : String(createError),
+                    stack: createError instanceof Error ? createError.stack : undefined,
+                });
+                throw createError;
+            }
+            // Verify session was created
+            const sessionCreatedCheck = sessionHelper.sessionExists(sessionName);
+            this.logger.info('Session creation verification', {
+                sessionName,
+                exists: sessionCreatedCheck,
+            });
+            if (!sessionCreatedCheck) {
+                throw new Error(`Session '${sessionName}' was not created successfully`);
+            }
+            // Register session for state persistence so it survives restarts
+            try {
+                const persistence = getSessionStatePersistence();
+                persistence.registerSession(sessionName, {
+                    cwd: cwdToUse,
+                    command: process.env.SHELL || '/bin/bash',
+                    args: [],
+                }, runtimeType, role, config.teamId, config.memberId);
+            }
+            catch (persistError) {
+                this.logger.warn('Failed to register session for persistence (non-critical)', {
+                    sessionName,
+                    error: persistError instanceof Error ? persistError.message : String(persistError),
+                });
+            }
+            // Set environment variables for MCP connection
+            await sessionHelper.setEnvironmentVariable(sessionName, ENV_CONSTANTS.CREWLY_SESSION_NAME, sessionName);
+            await sessionHelper.setEnvironmentVariable(sessionName, ENV_CONSTANTS.CREWLY_ROLE, role);
+            await sessionHelper.setEnvironmentVariable(sessionName, ENV_CONSTANTS.CREWLY_API_URL, `http://localhost:${WEB_CONSTANTS.PORTS.BACKEND}`);
+            // #187: Set project path so memory skills can auto-inject it
+            await sessionHelper.setEnvironmentVariable(sessionName, ENV_CONSTANTS.CREWLY_PROJECT_PATH, cwdToUse);
+            // #222: Set install dir so agents can resolve skill paths regardless of CWD
+            await sessionHelper.setEnvironmentVariable(sessionName, ENV_CONSTANTS.CREWLY_INSTALL_DIR, this.projectRoot);
+            // Inject API keys from settings (with override chain) for all runtimes
+            const settingsService = getSettingsService();
+            const runtimeContext = { runtime: runtimeType };
+            // Gemini key — needed by gemini-cli and crewly-agent
+            const geminiKey = await settingsService.getApiKey('gemini', runtimeContext);
+            if (geminiKey) {
+                await sessionHelper.setEnvironmentVariable(sessionName, 'GOOGLE_GENERATIVE_AI_API_KEY', geminiKey);
+                await sessionHelper.setEnvironmentVariable(sessionName, ENV_CONSTANTS.GEMINI_API_KEY, geminiKey);
+            }
+            // Anthropic key — needed by claude-code and crewly-agent
+            const anthropicKey = await settingsService.getApiKey('anthropic', runtimeContext);
+            if (anthropicKey) {
+                await sessionHelper.setEnvironmentVariable(sessionName, 'ANTHROPIC_API_KEY', anthropicKey);
+            }
+            // OpenAI key — needed by codex-cli and crewly-agent
+            const openaiKey = await settingsService.getApiKey('openai', runtimeContext);
+            if (openaiKey) {
+                await sessionHelper.setEnvironmentVariable(sessionName, 'OPENAI_API_KEY', openaiKey);
+            }
+            // Token tracking telemetry — inject env vars for runtimes that need them
+            const settings = await settingsService.getSettings();
+            if (settings.general?.tokenTracking && runtimeType === RUNTIME_TYPES.CLAUDE_CODE) {
+                await sessionHelper.setEnvironmentVariable(sessionName, ENV_CONSTANTS.CLAUDE_CODE_ENABLE_TELEMETRY, '1');
+                this.logger.debug('Token tracking enabled: set CLAUDE_CODE_ENABLE_TELEMETRY=1', { sessionName });
+            }
+            this.logger.info('Agent session created and environment variables set, initializing with registration', {
+                sessionName,
+                role,
+                runtimeType,
+            });
+            // Use the existing unified registration system
+            // #227: Claude Code gets extended timeout for PI protection evaluation
+            const timeout = role === ORCHESTRATOR_ROLE
+                ? AGENT_TIMEOUTS.ORCHESTRATOR_INITIALIZATION
+                : runtimeType === RUNTIME_TYPES.CLAUDE_CODE
+                    ? AGENT_TIMEOUTS.CLAUDE_CODE_INITIALIZATION
+                    : AGENT_TIMEOUTS.REGULAR_AGENT_INITIALIZATION;
+            const initResult = await this.initializeAgentWithRegistration(sessionName, role, projectPath, timeout, memberId, runtimeType, runtimeFlags, config.additionalAllowlistPaths);
+            if (!initResult.success) {
+                return {
+                    success: false,
+                    sessionName,
+                    error: initResult.error || 'Failed to initialize and register agent',
+                };
+            }
+            // Start context window monitoring for newly created non-orchestrator session
+            if (role !== ORCHESTRATOR_ROLE && config.teamId && config.memberId) {
+                ContextWindowMonitorService.getInstance().startSessionMonitoring(sessionName, config.memberId, config.teamId, role, runtimeType);
+            }
+            // Start OAuth relogin monitoring for newly created session
+            OAuthReloginMonitorService.getInstance().startMonitoring(sessionName, runtimeType);
+            return {
+                success: true,
+                sessionName,
+                message: initResult.message || 'Agent session created and registered successfully',
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger.error('Failed to create agent session', {
+                sessionName,
+                role,
+                error: errorMessage,
+            });
+            return {
+                success: false,
+                sessionName,
+                error: errorMessage,
+            };
+        }
+    }
+    /**
+     * Unified session termination that handles both orchestrator and team members
+     * @param sessionName The session to terminate
+     * @param role The role for proper status updates
+     * @returns Promise with success/error information
+     */
+    async terminateAgentSession(sessionName, role = 'unknown') {
+        try {
+            this.logger.info('Terminating agent session (unified approach)', { sessionName, role });
+            // Stop runtime exit monitoring before killing the session
+            RuntimeExitMonitorService.getInstance().stopMonitoring(sessionName);
+            // Stop OAuth relogin monitoring before killing the session
+            OAuthReloginMonitorService.getInstance().stopMonitoring(sessionName);
+            // Stop context window monitoring before killing the session
+            ContextWindowMonitorService.getInstance().stopSessionMonitoring(sessionName);
+            // Shut down in-process Crewly Agent runtime if present.
+            // Both maps must stay in sync: the local instance map and the
+            // module-level registry consumed by orchestrator-status service.
+            const inProcessRuntime = this.inProcessRuntimes.get(sessionName);
+            if (inProcessRuntime) {
+                inProcessRuntime.shutdown();
+                this.inProcessRuntimes.delete(sessionName);
+                unregisterInProcessRuntime(sessionName);
+                this.logger.info('In-process Crewly Agent runtime shut down', { sessionName });
+            }
+            // Get session helper once to avoid repeated async calls
+            const sessionHelper = await this.getSessionHelper();
+            const sessionExists = sessionHelper.sessionExists(sessionName);
+            if (sessionExists) {
+                // Kill the tmux session
+                await sessionHelper.killSession(sessionName);
+                this.logger.info('Session terminated successfully', { sessionName });
+            }
+            else if (!inProcessRuntime) {
+                this.logger.info('Session already terminated or does not exist', { sessionName });
+            }
+            // Capture session end for memory persistence
+            try {
+                const sessionMemoryService = SessionMemoryService.getInstance();
+                await sessionMemoryService.onSessionEnd(sessionName, role, process.cwd());
+                this.logger.info('Session memory captured on termination', { sessionName, role });
+            }
+            catch (memoryError) {
+                this.logger.warn('Failed to capture session memory on termination (non-critical)', {
+                    sessionName,
+                    error: memoryError instanceof Error ? memoryError.message : String(memoryError),
+                });
+            }
+            // Update agent status to inactive (works for both orchestrator and team members)
+            await this.storageService.updateAgentStatus(sessionName, CREWLY_CONSTANTS.AGENT_STATUSES.INACTIVE);
+            this.logger.info('Agent status updated to inactive', { sessionName, role });
+            // Unregister from persistence so explicitly stopped agents don't reappear in resume popup
+            try {
+                const persistence = getSessionStatePersistence();
+                persistence.unregisterSession(sessionName);
+            }
+            catch (persistError) {
+                this.logger.warn('Failed to unregister session from persistence (non-critical)', {
+                    sessionName,
+                    error: persistError instanceof Error ? persistError.message : String(persistError),
+                });
+            }
+            return {
+                success: true,
+                message: sessionExists
+                    ? 'Agent session terminated successfully'
+                    : 'Agent session was already terminated',
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger.error('Failed to terminate agent session', {
+                sessionName,
+                role,
+                error: errorMessage,
+            });
+            return {
+                success: false,
+                error: errorMessage,
+            };
+        }
+    }
+    /**
+     * Send a message to any agent session with reliable delivery.
+     * Uses robust delivery mechanism with retry logic to ensure messages
+     * are properly delivered to Claude Code's input.
+     *
+     * @param sessionName - The agent session name
+     * @param message - The message to send
+     * @returns Promise with success status and optional error message
+     *
+     * @example
+     * ```typescript
+     * const result = await agentRegistrationService.sendMessageToAgent(
+     *   'crewly-orc',
+     *   '[CHAT:123] Hello, orchestrator!'
+     * );
+     * if (result.success) {
+     *   console.log('Message delivered');
+     * } else {
+     *   console.error('Delivery failed:', result.error);
+     * }
+     * ```
+     */
+    async sendMessageToAgent(sessionName, message, runtimeType) {
+        // Per-session delivery serialization: chain this delivery after any
+        // in-flight delivery to the same session. This prevents concurrent
+        // sendMessageWithRetry calls that each send Ctrl+C on retry attempts,
+        // which can kill the runtime when 25+ scheduled checks fire at once.
+        const previousDelivery = this.sessionDeliveryMutex.get(sessionName);
+        let releaseMutex;
+        const currentDelivery = new Promise((r) => { releaseMutex = r; });
+        this.sessionDeliveryMutex.set(sessionName, currentDelivery);
+        if (previousDelivery) {
+            this.logger.info('Waiting for in-flight delivery to complete before sending', {
+                sessionName,
+                messageLength: message.length,
+            });
+            await previousDelivery.catch(() => { });
+        }
+        try {
+            if (!message || typeof message !== 'string') {
+                return {
+                    success: false,
+                    error: 'Message is required and must be a string',
+                };
+            }
+            // Auto-resolve runtime type if not provided.
+            // CRITICAL: defaulting to CLAUDE_CODE is dangerous because
+            // Ctrl+C cleanup (Claude Code behavior) triggers /quit on Gemini CLI.
+            if (!runtimeType) {
+                runtimeType = await this.resolveSessionRuntimeType(sessionName);
+            }
+            // ===== In-process Crewly Agent delivery =====
+            // Route directly to the in-process runtime, bypassing PTY entirely.
+            // Fire-and-forget: mirrors PTY runtimes where the write returns immediately.
+            // The LLM processes the message asynchronously in the background.
+            //
+            // IMPORTANT: Always check inProcessRuntimes map first, regardless of
+            // the runtimeType parameter. This makes delivery robust against runtime
+            // type misresolution — e.g., when storage lookup fails and defaults to
+            // claude-code for what is actually a crewly-agent session. Without this
+            // fallback, messages to crewly-agent sessions silently fail when routed
+            // through the PTY path (no PTY session exists).
+            const crewlyRuntime = this.inProcessRuntimes.get(sessionName);
+            if (crewlyRuntime || runtimeType === RUNTIME_TYPES.CREWLY_AGENT) {
+                if (!crewlyRuntime || !crewlyRuntime.isReady()) {
+                    return {
+                        success: false,
+                        error: `Crewly Agent runtime for '${sessionName}' is not initialized`,
+                    };
+                }
+                // Extract conversationId from [CHAT:xxx] or [GCHAT:xxx ...] prefix for response routing
+                const chatPrefixMatch = message.match(/^\[(?:G?CHAT):([^\]\s]+)[^\]]*\]\s*/);
+                const incomingConversationId = chatPrefixMatch?.[1];
+                // Extract Slack context from [SLACK:channelId:threadTs] marker if present (Bug 5).
+                // This allows crewly-agent to auto-fill reply_slack with the correct thread.
+                let slackMetadata;
+                const slackPrefixMatch = message.match(/\[SLACK:([^:\]]+)(?::([^\]]+))?\]/);
+                if (slackPrefixMatch) {
+                    slackMetadata = { channelId: slackPrefixMatch[1] };
+                    if (slackPrefixMatch[2])
+                        slackMetadata.threadTs = slackPrefixMatch[2];
+                }
+                // Process message asynchronously — don't block the caller
+                crewlyRuntime.handleMessage(message, slackMetadata)
+                    .then((result) => {
+                    this.logger.info('Crewly Agent finished processing message', {
+                        sessionName, messageLength: message.length,
+                        responseLength: result.text?.length ?? 0,
+                    });
+                    // Route response text back to the originating chat conversation.
+                    // Without this, crewly-agent responses are discarded — the agent
+                    // has no terminal output for the NOTIFY pathway used by PTY runtimes.
+                    //
+                    // For Slack-sourced messages: check if the agent already sent a
+                    // reply via reply_slack tool during processing. If so, skip routing
+                    // to avoid duplicates. If not, route normally to ensure delivery.
+                    const agentAlreadyReplied = result.toolCalls?.some(tc => tc.toolName === 'reply_slack' || tc.toolName === 'reply-slack') ?? false;
+                    if (result.text && incomingConversationId && !agentAlreadyReplied) {
+                        this.routeInProcessResponseToChat(sessionName, result.text, incomingConversationId);
+                    }
+                    else if (agentAlreadyReplied) {
+                        this.logger.debug('Skipping chat routing — agent already replied via reply_slack', {
+                            sessionName, conversationId: incomingConversationId,
+                        });
+                    }
+                    // Auto-route to Slack when the message originated from Slack and the
+                    // agent finished with text-only output (toolCalls=0, finishReason=stop)
+                    // without explicitly invoking the reply_slack tool. Without this hook,
+                    // the in-process AI SDK runtime drops Slack replies silently — unlike
+                    // claude-code PTY where TerminalGateway tails stdout into SlackBridge,
+                    // the in-process runtime has no stream the bridge can listen to.
+                    //
+                    // Skipped when the agent already called reply_slack (which posts via
+                    // /slack/send) to prevent double-posting on the same thread.
+                    if (slackMetadata?.channelId && result.text && !agentAlreadyReplied) {
+                        this.routeInProcessResponseToSlack(sessionName, result.text, {
+                            channelId: slackMetadata.channelId,
+                            threadTs: slackMetadata.threadTs,
+                        });
+                    }
+                })
+                    .catch(async (agentError) => {
+                    const errMsg = agentError instanceof Error ? agentError.message : String(agentError);
+                    this.logger.error('Crewly Agent message handling failed', {
+                        sessionName, error: errMsg,
+                        messageLength: message.length,
+                        messagePreview: message.substring(0, 200),
+                    });
+                    // Log to InProcessLogBuffer so orchestrator can see the error via get-agent-logs
+                    try {
+                        const { InProcessLogBuffer } = await import('./crewly-agent/in-process-log-buffer.js');
+                        InProcessLogBuffer.getInstance().append(sessionName, 'error', `Message handling failed: ${errMsg}`);
+                    }
+                    catch { /* non-critical */ }
+                    // Update workingStatus to idle so the agent is not stuck as in_progress
+                    try {
+                        const memberInfo = await this.storageService.findMemberBySessionName(sessionName);
+                        if (memberInfo) {
+                            memberInfo.member.workingStatus = 'idle';
+                            memberInfo.member.updatedAt = new Date().toISOString();
+                            await this.storageService.saveTeam(memberInfo.team);
+                            this.logger.info('Reset workingStatus to idle after crewly-agent error', { sessionName });
+                        }
+                    }
+                    catch (statusError) {
+                        this.logger.warn('Failed to reset workingStatus after error', {
+                            sessionName,
+                            error: statusError instanceof Error ? statusError.message : String(statusError),
+                        });
+                    }
+                });
+                this.logger.info('Message dispatched to in-process Crewly Agent', {
+                    sessionName, messageLength: message.length,
+                });
+                return { success: true, message: 'Message delivered to Crewly Agent' };
+            }
+            // Get session helper once for this method
+            const sessionHelper = await this.getSessionHelper();
+            // Check if session exists
+            if (!sessionHelper.sessionExists(sessionName)) {
+                return {
+                    success: false,
+                    error: `Session '${sessionName}' does not exist`,
+                };
+            }
+            // Guard: refuse to deliver if the runtime process has exited.
+            // When Claude Code exits (e.g. context exhaustion), the PTY shell
+            // stays alive. Writing to it would execute garbage as shell commands.
+            const backend = typeof sessionHelper.getBackend === 'function'
+                ? sessionHelper.getBackend()
+                : getSessionBackendSync();
+            const childAlive = backend?.isChildProcessAlive?.(sessionName);
+            if (childAlive === false) {
+                this.logger.error('Runtime process not alive, refusing to deliver message', {
+                    sessionName,
+                    messageLength: message.length,
+                });
+                return {
+                    success: false,
+                    error: 'Runtime has exited — no child process in session',
+                };
+            }
+            // Use robust message delivery with proper waiting mechanism.
+            // Gemini CLI: use 2 attempts — one retry is needed for TUI focus
+            // issues (Tab+Enter recovery). Previously set to 1 which caused
+            // Google Chat messages to fail permanently on first TUI hiccup.
+            const maxDeliveryAttempts = runtimeType === RUNTIME_TYPES.GEMINI_CLI ? 2 : 3;
+            const delivered = await this.sendMessageWithRetry(sessionName, message, maxDeliveryAttempts, runtimeType);
+            if (!delivered) {
+                // Check if the agent is actively processing (busy) — queue for later delivery.
+                // Use PTY idle time instead of regex patterns for robust cross-runtime detection.
+                const idleMs = PtyActivityTrackerService.getInstance().getIdleTimeMs(sessionName);
+                const isBusy = idleMs < SESSION_COMMAND_DELAYS.AGENT_BUSY_IDLE_THRESHOLD_MS;
+                if (isBusy) {
+                    // #236: Queue message for delivery when agent becomes idle
+                    SubAgentMessageQueue.getInstance().enqueue(sessionName, message);
+                    this.logger.info('Agent busy — message queued for later delivery', {
+                        sessionName,
+                        messageLength: message.length,
+                    });
+                    return {
+                        success: true,
+                        queued: true,
+                        message: '[AGENT_BUSY] Message queued for delivery when agent becomes idle',
+                    };
+                }
+                return {
+                    success: false,
+                    error: 'Failed to deliver message after multiple attempts',
+                };
+            }
+            this.logger.info('Message sent to agent successfully', {
+                sessionName,
+                messageLength: message.length,
+            });
+            return {
+                success: true,
+                message: 'Message sent to agent successfully',
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger.error('Failed to send message to agent', {
+                sessionName,
+                error: errorMessage,
+            });
+            return {
+                success: false,
+                error: errorMessage,
+            };
+        }
+        finally {
+            releaseMutex();
+            if (this.sessionDeliveryMutex.get(sessionName) === currentDelivery) {
+                this.sessionDeliveryMutex.delete(sessionName);
+            }
+        }
+    }
+    /**
+     * Wait for an agent session to be at a ready prompt before sending messages.
+     *
+     * Subscribes to terminal output and polls capturePane to detect when the
+     * agent returns to an input prompt. This is critical for sequential message
+     * processing: after the orchestrator responds to a message it may continue
+     * working (managing agents, running commands) before returning to prompt.
+     *
+     * @param sessionName - The session name to wait on
+     * @param timeoutMs - Maximum time to wait (default 120s)
+     * @returns true if agent is ready, false if timed out
+     */
+    async waitForAgentReady(sessionName, timeoutMs = EVENT_DELIVERY_CONSTANTS.AGENT_READY_TIMEOUT, runtimeType) {
+        // In-process Crewly Agent is always "ready" (no prompt to wait for)
+        const inProcessRuntime = this.inProcessRuntimes.get(sessionName);
+        if (inProcessRuntime) {
+            return inProcessRuntime.isReady();
+        }
+        const sessionHelper = await this.getSessionHelper();
+        // Check if session exists
+        if (!sessionHelper.sessionExists(sessionName)) {
+            this.logger.warn('Session does not exist for waitForAgentReady', { sessionName });
+            return false;
+        }
+        // Quick check - already at prompt?
+        const currentOutput = sessionHelper.capturePane(sessionName);
+        if (this.isClaudeAtPrompt(currentOutput, runtimeType)) {
+            this.logger.debug('Agent already at prompt', { sessionName });
+            return true;
+        }
+        this.logger.info('Waiting for agent to return to prompt', { sessionName, timeoutMs });
+        const session = sessionHelper.getSession(sessionName);
+        if (!session) {
+            return false;
+        }
+        const waitStartMs = Date.now();
+        return new Promise((resolve) => {
+            let resolved = false;
+            let pollCount = 0;
+            const pollInterval = EVENT_DELIVERY_CONSTANTS.AGENT_READY_POLL_INTERVAL;
+            const cleanup = () => {
+                if (resolved)
+                    return;
+                resolved = true;
+                clearTimeout(timeoutId);
+                clearInterval(pollId);
+                clearInterval(deepScanId);
+                unsubscribe();
+            };
+            // Timeout - give up waiting
+            const timeoutId = setTimeout(() => {
+                this.logger.warn('Timed out waiting for agent to be ready', { sessionName, timeoutMs });
+                cleanup();
+                resolve(false);
+            }, timeoutMs);
+            // Poll capturePane periodically as a fallback
+            const pollId = setInterval(() => {
+                if (resolved)
+                    return;
+                pollCount++;
+                const output = sessionHelper.capturePane(sessionName);
+                if (this.isClaudeAtPrompt(output, runtimeType)) {
+                    const elapsedMs = Date.now() - waitStartMs;
+                    this.logger.info('Agent ready after polling', { sessionName, pollCount, elapsedMs });
+                    cleanup();
+                    resolve(true);
+                }
+            }, pollInterval);
+            // Deep scan with larger buffer every DEEP_SCAN_INTERVAL to catch prompts
+            // that the fast poll misses (e.g. when prompt is beyond the default 200 lines)
+            const deepScanId = setInterval(() => {
+                if (resolved)
+                    return;
+                pollCount++;
+                const output = sessionHelper.capturePane(sessionName, EVENT_DELIVERY_CONSTANTS.DEEP_SCAN_LINES);
+                if (this.isClaudeAtPrompt(output, runtimeType)) {
+                    const elapsedMs = Date.now() - waitStartMs;
+                    this.logger.info('Agent ready after polling', { sessionName, pollCount, elapsedMs });
+                    cleanup();
+                    resolve(true);
+                }
+            }, EVENT_DELIVERY_CONSTANTS.DEEP_SCAN_INTERVAL);
+            // Also subscribe to terminal data for faster detection
+            const unsubscribe = session.onData((data) => {
+                if (resolved)
+                    return;
+                // Strip ANSI escape sequences before testing — raw PTY data contains
+                // cursor positioning, color codes, etc. that break pattern matching (#106)
+                const cleanData = stripAnsiCodes(data);
+                // Check each line for prompt pattern (string-based, no regex)
+                const hasPromptInStream = cleanData.split('\n').some(line => line.trim().length > 0 && isPromptLine(line, runtimeType));
+                if (hasPromptInStream) {
+                    // Double-check with capturePane to avoid false positives from partial data
+                    const output = sessionHelper.capturePane(sessionName);
+                    if (this.isClaudeAtPrompt(output, runtimeType)) {
+                        this.logger.debug('Agent at prompt (detected via stream)', { sessionName });
+                        cleanup();
+                        resolve(true);
+                    }
+                }
+            });
+        });
+    }
+    /**
+     * Send message with retry logic for reliable delivery to Claude Code.
+     * Uses SessionCommandHelper.sendMessage() (proven two-step write pattern)
+     * with stuck-message detection and retry on failure.
+     *
+     * @param sessionName - The session name
+     * @param message - The message to send
+     * @param maxAttempts - Maximum number of delivery attempts
+     * @returns true if message was delivered successfully
+     */
+    async sendMessageWithRetry(sessionName, message, maxAttempts = 3, runtimeType = RUNTIME_TYPES.CLAUDE_CODE) {
+        const sessionHelper = await this.getSessionHelper();
+        const isClaudeCode = runtimeType === RUNTIME_TYPES.CLAUDE_CODE;
+        const isCodexCli = runtimeType === RUNTIME_TYPES.CODEX_CLI;
+        const isGeminiCli = runtimeType === RUNTIME_TYPES.GEMINI_CLI;
+        // Register TUI sessions for TUI prompt-line scanning (Part 1 of scanner).
+        // The scanner itself is started lazily by trackSentMessage() which
+        // runs after every message send, covering all runtimes.
+        if (!isClaudeCode) {
+            this.tuiSessionRegistry.set(sessionName, runtimeType);
+        }
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            try {
+                this.logger.debug('Attempting message delivery', {
+                    sessionName,
+                    attempt,
+                    maxAttempts,
+                    messageLength: message.length,
+                    runtimeType,
+                });
+                // Verify agent is at prompt before sending
+                const output = sessionHelper.capturePane(sessionName);
+                // Gemini CLI stuck-connectivity guard (#128): If the CLI is in a
+                // "Trying to reach <model>" retry loop, it will never process
+                // new messages. Bail out immediately so the caller gets a clear
+                // failure signal and the runtime-exit-monitor can trigger recovery.
+                if (runtimeType === RUNTIME_TYPES.GEMINI_CLI && GEMINI_STUCK_CONNECTIVITY_PATTERN.test(output)) {
+                    this.logger.warn('Gemini CLI stuck in connectivity retry loop, aborting message delivery (#128)', {
+                        sessionName,
+                        attempt,
+                    });
+                    return false;
+                }
+                if (!this.isClaudeAtPrompt(output, runtimeType)) {
+                    if (attempt === maxAttempts) {
+                        // On the final attempt, check if the agent is DEFINITELY busy
+                        // before force-delivering. Use PTY idle time for robust
+                        // cross-runtime detection instead of fragile regex patterns.
+                        const idleMs = PtyActivityTrackerService.getInstance().getIdleTimeMs(sessionName);
+                        const isBusy = idleMs < SESSION_COMMAND_DELAYS.AGENT_BUSY_IDLE_THRESHOLD_MS;
+                        if (isBusy) {
+                            this.logger.warn('Agent is busy (processing indicators detected), skipping force delivery', {
+                                sessionName,
+                                attempt,
+                                runtimeType,
+                            });
+                            return false;
+                        }
+                        // Not clearly busy — fall back to direct delivery. The agent
+                        // may be at a prompt that doesn't match our detection patterns,
+                        // or the terminal buffer may be stale.
+                        this.logger.warn('Prompt detection failed on final attempt, delivering message directly', {
+                            sessionName,
+                            attempt,
+                            runtimeType,
+                        });
+                        // Fall through to message delivery below
+                    }
+                    else {
+                        this.logger.debug('Not at prompt, waiting before retry', { sessionName, attempt });
+                        await delay(SESSION_COMMAND_DELAYS.CLAUDE_RECOVERY_DELAY);
+                        continue;
+                    }
+                }
+                // Gemini CLI shell mode guard: if the prompt shows `!` instead of `>`,
+                // input will be executed as a shell command. Send Escape to exit first.
+                if (runtimeType === RUNTIME_TYPES.GEMINI_CLI && this.isGeminiInShellMode(output)) {
+                    const escaped = await this.escapeGeminiShellMode(sessionName, sessionHelper);
+                    if (!escaped) {
+                        this.logger.warn('Could not exit Gemini shell mode, skipping attempt', {
+                            sessionName,
+                            attempt,
+                        });
+                        await delay(SESSION_COMMAND_DELAYS.MESSAGE_RETRY_DELAY);
+                        continue;
+                    }
+                }
+                // Clear any stale text before sending.
+                // Claude Code: Ctrl+C to cancel any pending input — but ONLY on
+                // retry attempts. On the first attempt, waitForAgentReady already
+                // confirmed the agent is idle at the prompt, so Ctrl+C is
+                // unnecessary and can disrupt Claude Code's input handler if the
+                // 300ms settling delay isn't enough.
+                // Gemini CLI (Ink TUI): escalating recovery to refocus input box.
+                // The TUI input can lose focus after idle periods, auto-update
+                // notifications, or dialog overlays. When defocused, writes are
+                // silently consumed by the Ink framework but NOT routed to the
+                // InputPrompt.
+                // Do NOT send Escape (defocuses permanently), Ctrl+C (triggers
+                // /quit on empty prompt), or Ctrl+U (ignored by TUI).
+                //
+                // Recovery strategies (escalating per attempt):
+                // 1. Tab + Enter: Tab triggers Ink's focusNext() which cycles
+                //    focus through focusable components. If InputPrompt is the
+                //    only/next focusable element, it gets refocused. Enter then
+                //    dismisses any overlay or acts as safe no-op on empty prompt.
+                // 2-3. PTY resize + Tab + Enter: Resize sends SIGWINCH to the
+                //    child process, forcing Ink to re-render the entire TUI.
+                //    This may restore the internal focus state. Then Tab + Enter
+                //    for focus cycling and overlay dismissal.
+                if (isClaudeCode) {
+                    if (attempt > 1) {
+                        // On retry: Ctrl+C to cancel stale input, then PTY resize to force
+                        // TUI re-render (SIGWINCH), then Tab to cycle Ink focus.
+                        await sessionHelper.sendCtrlC(sessionName);
+                        await delay(300);
+                    }
+                    // PTY resize on ALL attempts to force SIGWINCH → Ink TUI re-render.
+                    // Claude Code's Ink TUI can lose internal input focus after stop hooks
+                    // (especially ones that error), state transitions, or idle periods.
+                    // When defocused, the `❯` prompt is visible in the terminal buffer
+                    // but writes are silently consumed by the framework — NOT routed to
+                    // the InputPrompt. Tab alone was insufficient; PTY resize forces a
+                    // full TUI re-render that reliably restores focus state.
+                    // This matches the manual workaround where pressing a key in the
+                    // frontend terminal "wakes up" the input handler.
+                    try {
+                        const session = sessionHelper.getSession(sessionName);
+                        if (session) {
+                            session.resize(81, 25);
+                            await delay(200);
+                            session.resize(80, 24);
+                            await delay(300);
+                        }
+                    }
+                    catch { /* non-fatal */ }
+                    await sessionHelper.sendKey(sessionName, 'Tab');
+                    await delay(300);
+                }
+                else if (isCodexCli) {
+                    // #246: Codex CLI TUI recovery — simpler than Gemini.
+                    // Codex uses Ink-based TUI with › prompt. Avoid Gemini-specific
+                    // F12/compress/error-state logic which is irrelevant for Codex.
+                    if (attempt > 1) {
+                        // PTY resize to trigger SIGWINCH → Ink re-render
+                        try {
+                            const session = sessionHelper.getSession(sessionName);
+                            if (session) {
+                                session.resize(81, 25);
+                                await delay(200);
+                                session.resize(80, 24);
+                                await delay(300);
+                            }
+                        }
+                        catch { /* non-fatal */ }
+                        // Ctrl+U to clear any stale input text
+                        await sessionHelper.sendKey(sessionName, 'C-u');
+                        await delay(300);
+                    }
+                }
+                else {
+                    // Gemini CLI TUI recovery
+                    // Detect recent /compress — Ink TUI loses internal focus after
+                    // /compress re-renders, causing subsequent messages to be silently
+                    // dropped even though the prompt `>` is visible (#114).
+                    // Always force PTY resize on attempt 1 if /compress detected.
+                    // Also detect ✖ error state (#130) — MCP connection errors
+                    // cause a persistent error indicator that steals TUI focus.
+                    const recentOutput = sessionHelper.capturePane(sessionName, 40);
+                    const compressDetected = recentOutput.includes('/compress') ||
+                        recentOutput.includes('Context compressed') ||
+                        recentOutput.includes('Compressing context');
+                    // Check for Gemini CLI error indicators ONLY in the status bar area (#130).
+                    // The ✖ marker must be in the bottom status lines, not in content area —
+                    // checking the full 40-line output causes false positives when ✖ appears
+                    // in normal response content (e.g., diffs, lists), triggering spurious
+                    // F12 keypresses that open DevTools or disrupt the TUI.
+                    const statusArea = recentOutput.split('\n').slice(-GEMINI_ERROR_STATE_CONSTANTS.STATUS_AREA_LINES).join('\n');
+                    const errorStateDetected = statusArea.includes(GEMINI_ERROR_STATE_CONSTANTS.ERROR_MARKER) ||
+                        GEMINI_ERROR_STATE_CONSTANTS.ERROR_COUNT_PATTERN.test(statusArea);
+                    const needsResize = attempt > 1 || compressDetected || errorStateDetected;
+                    // Force a PTY resize to trigger SIGWINCH, making Ink
+                    // re-render the TUI and potentially restore focus state.
+                    if (needsResize) {
+                        try {
+                            const session = sessionHelper.getSession(sessionName);
+                            if (session) {
+                                // Resize slightly then back to trigger SIGWINCH
+                                session.resize(81, 25);
+                                await delay(200);
+                                session.resize(80, 24);
+                                await delay(500);
+                                this.logger.debug('PTY resize sent to trigger TUI re-render', {
+                                    sessionName,
+                                    attempt,
+                                    compressDetected,
+                                });
+                            }
+                        }
+                        catch (resizeErr) {
+                            this.logger.debug('PTY resize failed (non-fatal)', {
+                                sessionName,
+                                error: resizeErr instanceof Error ? resizeErr.message : String(resizeErr),
+                            });
+                        }
+                    }
+                    // If error state detected (✖), dismiss the error overlay first (#130).
+                    // F12 toggles the error details panel in Gemini CLI, Enter dismisses
+                    // any overlay/notification, and the combination restores the TUI to a
+                    // state where the InputPrompt can accept input.
+                    if (errorStateDetected) {
+                        this.logger.info('Gemini CLI error state detected (✖), dismissing before delivery (#130)', {
+                            sessionName,
+                            attempt,
+                        });
+                        // F12 to close error details panel if open
+                        await sessionHelper.sendKey(sessionName, 'F12');
+                        await delay(300);
+                        // Enter to dismiss any remaining overlay/notification
+                        await sessionHelper.sendEnter(sessionName);
+                        await delay(500);
+                    }
+                    // Send Tab to cycle Ink focus. In Ink v6, Tab triggers
+                    // focusNext() in FocusContext, which moves focus to the next
+                    // focusable component (InputPrompt). This works even when the
+                    // input is defocused because the Tab handler runs at the Ink
+                    // framework level, not the component level.
+                    // Send two Tabs to cycle through error/notification components
+                    // that may be in the focus chain (#130).
+                    await sessionHelper.sendKey(sessionName, 'Tab');
+                    await delay(200);
+                    await sessionHelper.sendKey(sessionName, 'Tab');
+                    await delay(300);
+                    // Then Enter to dismiss any notification overlay and ensure
+                    // the input is engaged. Enter on an empty `> ` prompt is a
+                    // safe no-op (just shows a new blank prompt line).
+                    await sessionHelper.sendEnter(sessionName);
+                    // Extra settling time after /compress or error state to let Ink TUI stabilize
+                    await delay((compressDetected || errorStateDetected) ? 1000 : 500);
+                }
+                // For Gemini CLI: detect and gently escape interactive modes before
+                // sending the message. Avoid Ctrl-C here — Gemini interprets it as
+                // destructive cancellation/quit in some states.
+                if (isGeminiCli) {
+                    const preOutput = sessionHelper.capturePane(sessionName, 10);
+                    const interactiveModePatterns = [
+                        'Select a file', // /resume file picker
+                        '❯', // Interactive list selector
+                        'Choose an option', // Generic interactive prompt
+                        '/resume', // Resume command active
+                    ];
+                    const inInteractiveMode = interactiveModePatterns.some(p => preOutput.includes(p));
+                    if (inInteractiveMode) {
+                        this.logger.warn('Gemini CLI in interactive mode, using non-destructive recovery', {
+                            sessionName,
+                            detectedPattern: interactiveModePatterns.find(p => preOutput.includes(p)),
+                        });
+                        await sessionHelper.sendKey(sessionName, 'Tab');
+                        await delay(250);
+                        await sessionHelper.sendEnter(sessionName);
+                        await delay(1000);
+                    }
+                }
+                // Capture output BEFORE sending to detect changes for ALL runtimes.
+                // Claude Code: progressive output-change detection prevents false-positive
+                // Ctrl+C by giving Claude up to 6.5s to start rendering output.
+                // TUI runtimes: same output-change detection as before.
+                // Use a small pane capture (20 lines) to reduce noise from TUI
+                // border redraws that can cause length changes unrelated to delivery.
+                const beforeOutput = sessionHelper.capturePane(sessionName, 20);
+                const beforeLength = beforeOutput.length;
+                // Deduplication guard (#128): Check if the agent is already
+                // processing on ALL attempts (not just retries). A previous
+                // write may have succeeded but verification failed. Re-writing
+                // the same message creates a duplicate in the input buffer.
+                //
+                // IMPORTANT: Only skip the write when we have a positive hash
+                // match (isRecentDuplicate). The `attempt > 1` condition was
+                // removed because the spinner could be from a DIFFERENT message
+                // that the agent is still processing — skipping the write for
+                // a new message causes silent message loss.
+                {
+                    const preWriteCheck = sessionHelper.capturePane(sessionName);
+                    const hasSpinner = containsSpinnerOrWorkingIndicator(preWriteCheck);
+                    if (hasSpinner) {
+                        // Hash-based dedup: if the same message was recently sent
+                        // and the agent is processing, it's very likely our message.
+                        const msgHash = message.substring(0, 200);
+                        const lastSent = this.lastSentMessageHash.get(sessionName);
+                        const isRecentDuplicate = lastSent
+                            && lastSent.hash === msgHash
+                            && (Date.now() - lastSent.sentAt) < 60000;
+                        if (isRecentDuplicate) {
+                            this.logger.info('Agent already processing — skipping write to prevent duplicate (#128)', {
+                                sessionName,
+                                attempt,
+                                isRecentDuplicate: true,
+                            });
+                            return true;
+                        }
+                        // Agent is busy with a different message. On retries,
+                        // log but still proceed to write — the message will be
+                        // queued in the PTY input buffer for when the agent
+                        // finishes its current work.
+                        if (attempt > 1) {
+                            this.logger.info('Agent busy with different message, proceeding with write on retry', {
+                                sessionName,
+                                attempt,
+                            });
+                        }
+                    }
+                    // On retries: log informationally if the agent is mid-task and
+                    // our message text isn't visible at the bottom of the pane.
+                    // Historically this branch returned `true` (silent skip) on
+                    // `notAtPrompt && !textStuck`, which silently dropped Slack
+                    // messages whenever the orc was busy on a prior task and the
+                    // force-deliver fallback's first internal write had been
+                    // suppressed by the spinner-dedup guard above. Steve's
+                    // 2026-04-30 UTC 17:28 / 18:37 incident: messages acked by
+                    // the queue, never reached the orc PTY.
+                    //
+                    // Correct semantics: the only safe condition for skipping is
+                    // a positive recent-duplicate hash match (handled in the
+                    // `hasSpinner` block above via `isRecentDuplicate`). If we
+                    // reach this point we KNOW the new message has not been
+                    // confirmed-written this round, so proceed to the actual
+                    // `session.write` below — the PTY input buffer will queue
+                    // the bytes until the agent is ready to consume them. A
+                    // duplicate is recoverable on the agent side; a silent loss
+                    // is not.
+                    if (attempt > 1) {
+                        const notAtPrompt = !this.isClaudeAtPrompt(preWriteCheck, runtimeType);
+                        if (notAtPrompt) {
+                            const msgSnippet = (message.length > 20
+                                ? message.substring(0, 80)
+                                : message).replace(/\s+/g, ' ').trim();
+                            const bottomLines = preWriteCheck.split('\n').slice(-10).join(' ').replace(/\s+/g, ' ');
+                            const textStuck = bottomLines.includes(msgSnippet);
+                            this.logger.info('Agent busy on retry — proceeding to write (no silent skip)', {
+                                sessionName,
+                                attempt,
+                                textStuck,
+                            });
+                            // No early return — fall through to session.write.
+                        }
+                    }
+                }
+                // Use SessionCommandHelper.sendMessage() — proven two-step write:
+                // 1. session.write(message)    — triggers bracketed paste
+                // 2. await delay(scaled)       — waits for paste processing
+                // 3. session.write('\r')       — sends Enter separately
+                // 4. await delay(KEY_DELAY)    — waits for key processing
+                await sessionHelper.sendMessage(sessionName, message);
+                // Register for background stuck-detection safety net (all runtimes).
+                // If progressive verification below misses an Enter drop, the
+                // background scanner will catch it within 30s.
+                this.trackSentMessage(sessionName, message);
+                // Track message hash for deduplication on retry (#128)
+                this.lastSentMessageHash.set(sessionName, {
+                    hash: message.substring(0, 200),
+                    sentAt: Date.now(),
+                });
+                // Wait for agent to start processing, then verify delivery.
+                // TUI runtimes need a longer delay (3s) for the TUI to redraw
+                // and show processing indicators after accepting input.
+                const processingDelay = isClaudeCode
+                    ? SESSION_COMMAND_DELAYS.MESSAGE_PROCESSING_DELAY
+                    : 3000;
+                await delay(processingDelay);
+                // === Delivery verification ===
+                // Claude Code: prompt disappears during processing, so check
+                // isMessageStuckAtPrompt (text still at prompt = stuck).
+                // TUI runtimes (Gemini CLI): use TWO-PHASE verification:
+                //   Phase 1: Direct check — is the message text sitting ON the
+                //            `> ` prompt line? If yes, Enter was dropped. Try
+                //            pressing Enter to recover before falling through to retry.
+                //   Phase 2: Output-change detection — compare before/after captures
+                //            to see if the agent started processing.
+                if (isClaudeCode) {
+                    // Progressive verification for Claude Code.
+                    // Claude Code routinely takes 3-8s to start rendering with large
+                    // context. The old 2.5s window caused false-positive Ctrl+C that
+                    // cancelled valid in-progress prompts. Now we progressively check
+                    // at [1s, 2s, 3s] intervals (total ~6.5s including processing delay).
+                    //
+                    // Progressive verification: check at [1s, 2s, 3s] intervals whether
+                    // the agent accepted the message and started processing it.
+                    //
+                    // Uses runtime-agnostic detection — no hardcoded prompt characters.
+                    // This stays correct when the agent runtime upgrades its prompt.
+                    //
+                    // Three signals checked per interval:
+                    // 1. Processing indicators (⠋ ⏺ spinners) — definitive success
+                    // 2. isClaudeAtPrompt() — if still true, agent is idle, wait more
+                    // 3. Message text in bottom lines — if found, Enter was dropped
+                    //    (message pasted at prompt but not submitted)
+                    // If prompt gone AND message text NOT at bottom → success
+                    let claudeDelivered = false;
+                    for (const intervalMs of SESSION_COMMAND_DELAYS.CLAUDE_VERIFICATION_INTERVALS) {
+                        const currentOutput = sessionHelper.capturePane(sessionName);
+                        // 1. Processing indicators (spinners, working marker) are
+                        //    definitive proof the agent accepted and is working.
+                        //    Only check spinner/⏺ chars — NOT text words like
+                        //    "thinking" which appear in historical response text.
+                        if (containsSpinnerOrWorkingIndicator(currentOutput)) {
+                            this.logger.debug('Processing indicators detected — message accepted', {
+                                sessionName,
+                                attempt,
+                            });
+                            claudeDelivered = true;
+                            break;
+                        }
+                        // 2. Is the agent still at its standard idle prompt?
+                        //    Reuse isClaudeAtPrompt() — the single source of truth
+                        //    for prompt detection. This avoids hardcoding prompt
+                        //    characters and stays correct when the runtime upgrades.
+                        if (this.isClaudeAtPrompt(currentOutput, runtimeType)) {
+                            // Prompt is visible. Before just waiting, check if our
+                            // message text is also at the bottom — this means the
+                            // text was pasted but Enter was dropped. Press Enter.
+                            // Normalize whitespace: enhanced messages contain literal \n from
+                            // addContinuationInstructions(). join(' ') replaces line breaks with
+                            // spaces, but the snippet still has \n chars, so includes() fails.
+                            const promptMsgSnippet = (message.length > 20
+                                ? message.substring(0, 80)
+                                : message).replace(/\s+/g, ' ').trim();
+                            const promptBottomLines = currentOutput.split('\n').slice(-10).join(' ').replace(/\s+/g, ' ');
+                            if (promptBottomLines.includes(promptMsgSnippet)) {
+                                this.logger.warn('At prompt with message text at bottom — pressing Tab+Enter', {
+                                    sessionName,
+                                    attempt,
+                                    intervalMs,
+                                });
+                                // Tab restores Ink TUI focus before Enter — without this,
+                                // Enter may be consumed by the framework but not routed to
+                                // the input component if focus was lost during a re-render
+                                // (e.g., after stop hooks, state transitions).
+                                await sessionHelper.sendKey(sessionName, 'Tab');
+                                await delay(200);
+                                await sessionHelper.sendEnter(sessionName);
+                                await delay(500);
+                                await sessionHelper.sendEnter(sessionName); // backup
+                                await delay(SESSION_COMMAND_DELAYS.MESSAGE_PROCESSING_DELAY);
+                                // Verify recovery
+                                const postEnterOutput = sessionHelper.capturePane(sessionName);
+                                if (containsSpinnerOrWorkingIndicator(postEnterOutput) ||
+                                    !this.isClaudeAtPrompt(postEnterOutput, runtimeType)) {
+                                    this.logger.info('Enter recovery from prompt successful', {
+                                        sessionName,
+                                        attempt,
+                                    });
+                                    claudeDelivered = true;
+                                    break;
+                                }
+                            }
+                            // Fast-response detection: if the terminal output changed since
+                            // we sent the message, Claude processed it and returned to prompt
+                            // before our first check. Without this, fast responses (e.g.,
+                            // simple IP queries) cause false "delivery unconfirmed" verdicts
+                            // and trigger duplicate sends (#retry-storm).
+                            const outputChanged = currentOutput !== beforeOutput;
+                            if (outputChanged) {
+                                this.logger.info('Agent at prompt but output changed — fast response detected, delivery confirmed', {
+                                    sessionName,
+                                    attempt,
+                                    intervalMs,
+                                    beforeLength: beforeOutput.length,
+                                    currentLength: currentOutput.length,
+                                });
+                                claudeDelivered = true;
+                                break;
+                            }
+                            this.logger.debug('Agent still at prompt, waiting before re-check', {
+                                sessionName,
+                                attempt,
+                                intervalMs,
+                            });
+                            await delay(intervalMs);
+                            continue;
+                        }
+                        // 3. Prompt not in its standard idle form. Before declaring
+                        //    success, check if our message text is stuck at the
+                        //    bottom of the terminal. When Enter is dropped, the
+                        //    pasted text appears on the prompt line — the terminal
+                        //    shows the prompt char followed by our message text.
+                        //    This check is runtime-agnostic: it works regardless
+                        //    of what prompt character the runtime uses.
+                        // Normalize whitespace in snippet (see Step 2 comment above).
+                        const msgSnippet = (message.length > 20
+                            ? message.substring(0, 80)
+                            : message).replace(/\s+/g, ' ').trim();
+                        const bottomLines = currentOutput.split('\n').slice(-10).join(' ').replace(/\s+/g, ' ');
+                        if (bottomLines.includes(msgSnippet)) {
+                            // Message text is at the bottom of the terminal but the
+                            // prompt is no longer in its idle form — Enter was dropped.
+                            // Instead of waiting and doing a full Ctrl+C + resend retry,
+                            // use Tab to restore TUI focus, then Enter to submit.
+                            this.logger.warn('Message text stuck at bottom — pressing Tab+Enter to recover', {
+                                sessionName,
+                                attempt,
+                                intervalMs,
+                            });
+                            await sessionHelper.sendKey(sessionName, 'Tab');
+                            await delay(200);
+                            await sessionHelper.sendEnter(sessionName);
+                            await delay(500);
+                            await sessionHelper.sendEnter(sessionName); // backup Enter
+                            // Give the agent a moment to start processing after Enter
+                            await delay(SESSION_COMMAND_DELAYS.MESSAGE_PROCESSING_DELAY);
+                            // Verify recovery: check if processing started
+                            const recoveryOutput = sessionHelper.capturePane(sessionName);
+                            if (containsSpinnerOrWorkingIndicator(recoveryOutput)) {
+                                this.logger.info('Enter recovery successful — processing started', {
+                                    sessionName,
+                                    attempt,
+                                });
+                                claudeDelivered = true;
+                                break;
+                            }
+                            // Check if prompt reappeared (Enter submitted but processed instantly)
+                            // or if output changed from the stuck state
+                            const recoveryBottom = recoveryOutput.split('\n').slice(-10).join(' ').replace(/\s+/g, ' ');
+                            if (!recoveryBottom.includes(msgSnippet)) {
+                                this.logger.info('Enter recovery successful — stuck text cleared', {
+                                    sessionName,
+                                    attempt,
+                                });
+                                claudeDelivered = true;
+                                break;
+                            }
+                            // Still stuck after Enter recovery — continue to next interval
+                            this.logger.debug('Still stuck after Enter recovery, continuing verification', {
+                                sessionName,
+                                attempt,
+                            });
+                            await delay(intervalMs);
+                            continue;
+                        }
+                        // Prompt gone AND no stuck text → agent started processing
+                        this.logger.debug('Prompt gone, no stuck text — message delivered', {
+                            sessionName,
+                            attempt,
+                        });
+                        claudeDelivered = true;
+                        break;
+                    }
+                    // --- Extended confirmation loop ---
+                    // If progressive verification didn't confirm delivery, run an
+                    // extended check loop (every 3s, up to 30s total). Each iteration
+                    // captures the pane, checks for spinner/working indicators, and
+                    // presses Tab+Enter if message text is still stuck at the bottom.
+                    if (!claudeDelivered) {
+                        const CONFIRM_INTERVAL_MS = 3000;
+                        const CONFIRM_MAX_MS = 30000;
+                        const confirmStart = Date.now();
+                        let confirmAttempt = 0;
+                        // Normalize snippet once for reuse
+                        const confirmSnippet = (message.length > 20
+                            ? message.substring(0, 80)
+                            : message).replace(/\s+/g, ' ').trim();
+                        while (Date.now() - confirmStart < CONFIRM_MAX_MS) {
+                            await delay(CONFIRM_INTERVAL_MS);
+                            confirmAttempt++;
+                            const loopOutput = sessionHelper.capturePane(sessionName);
+                            const loopBottom = loopOutput.split('\n').slice(-10).join(' ').replace(/\s+/g, ' ');
+                            const textStuck = loopBottom.includes(confirmSnippet);
+                            // Spinner or working indicator → delivered
+                            if (containsSpinnerOrWorkingIndicator(loopOutput)) {
+                                this.logger.info('Confirmation loop: processing detected', {
+                                    sessionName, attempt, confirmAttempt,
+                                });
+                                claudeDelivered = true;
+                                break;
+                            }
+                            // Text still stuck → Enter was dropped, NOT delivered. Try
+                            // Tab+Enter recovery and re-check next iteration. This is
+                            // checked BEFORE the output-change shortcut below: when our
+                            // own pasted message is echoed at the prompt the output DID
+                            // change vs the pre-send baseline, but that change is the
+                            // stuck echo, not a response — treating it as "delivered"
+                            // is the false-positive that masked the orc 假死 (#686
+                            // follow-up: a hung session looked "delivered" forever).
+                            if (textStuck) {
+                                this.logger.warn('Confirmation loop: text still stuck, pressing Tab+Enter', {
+                                    sessionName, attempt, confirmAttempt,
+                                });
+                                await sessionHelper.sendKey(sessionName, 'Tab');
+                                await delay(200);
+                                await sessionHelper.sendEnter(sessionName);
+                                await delay(500);
+                                await sessionHelper.sendEnter(sessionName); // backup
+                                continue;
+                            }
+                            // Fast-response detection: output changed since send AND our
+                            // message text is NOT stuck at the prompt → a real response
+                            // landed and returned to prompt before we looked. Delivered.
+                            if (loopOutput !== beforeOutput) {
+                                this.logger.info('Confirmation loop: output changed from pre-send — fast response confirmed', {
+                                    sessionName, attempt, confirmAttempt,
+                                });
+                                claudeDelivered = true;
+                                break;
+                            }
+                            // Not at prompt and text not stuck → delivered
+                            if (!this.isClaudeAtPrompt(loopOutput, runtimeType)) {
+                                this.logger.info('Confirmation loop: prompt gone, text cleared', {
+                                    sessionName, attempt, confirmAttempt,
+                                });
+                                claudeDelivered = true;
+                                break;
+                            }
+                        }
+                        if (!claudeDelivered) {
+                            this.logger.error('Confirmation loop exhausted — delivery unconfirmed', {
+                                sessionName, attempt, confirmAttempts: confirmAttempt,
+                            });
+                        }
+                    }
+                    if (claudeDelivered) {
+                        return true;
+                    }
+                }
+                else {
+                    // --- Gemini CLI: lightweight verification ---
+                    // Gemini CLI's PTY write is reliable. The aggressive verification
+                    // (stuck detection + Tab+Enter recovery + output-change diff) causes
+                    // false "stuck" judgments that trigger visible retry error spam even
+                    // when the message was successfully delivered (#retry-storm fix).
+                    //
+                    // Strategy: only check for the definitive stuck signal (message text
+                    // literally sitting on the `> ` prompt line). If not stuck, trust the
+                    // write. Skip the output-change heuristics that cause false negatives.
+                    const isGemini = runtimeType === RUNTIME_TYPES.GEMINI_CLI;
+                    if (isGemini) {
+                        // Single stuck-at-prompt check — the only reliable failure signal
+                        const stuckAtPrompt = this.isTextStuckAtTuiPrompt(sessionName, message);
+                        if (stuckAtPrompt) {
+                            const recovered = await this.recoverStuckTuiMessage(sessionName, message);
+                            if (recovered) {
+                                this.logger.info('Gemini CLI: message recovered via Enter re-press', {
+                                    sessionName,
+                                    attempt,
+                                });
+                                return true;
+                            }
+                            this.logger.warn('Gemini CLI: message still stuck after Enter recovery', {
+                                sessionName,
+                                attempt,
+                            });
+                            // Fall through to retry cleanup below
+                        }
+                        else {
+                            // Not stuck at prompt — PTY write succeeded, trust delivery.
+                            // The old code did output-change detection here, but TUI redraws
+                            // and minimal length diffs caused false "not delivered" verdicts.
+                            this.logger.debug('Gemini CLI: message not stuck at prompt — delivery trusted', {
+                                sessionName,
+                                attempt,
+                            });
+                            return true;
+                        }
+                    }
+                    else {
+                        // --- Non-Gemini TUI runtimes: full verification ---
+                        // Phase 1: Direct stuck-at-prompt detection
+                        const stuckAtPrompt = this.isTextStuckAtTuiPrompt(sessionName, message);
+                        if (stuckAtPrompt) {
+                            const recovered = await this.recoverStuckTuiMessage(sessionName, message);
+                            if (recovered) {
+                                this.logger.info('Message recovered via Enter re-press', {
+                                    sessionName,
+                                    attempt,
+                                });
+                                return true;
+                            }
+                            this.logger.warn('Message still stuck after Enter recovery, will retry', {
+                                sessionName,
+                                attempt,
+                            });
+                        }
+                        else {
+                            // Phase 2: Output-change detection
+                            const afterOutput = sessionHelper.capturePane(sessionName, 20);
+                            const lengthDiff = afterOutput.length - beforeLength;
+                            const contentChanged = beforeOutput !== afterOutput;
+                            let newContent = '';
+                            if (contentChanged && afterOutput.length > beforeOutput.length) {
+                                newContent = afterOutput.slice(beforeLength);
+                            }
+                            else if (contentChanged) {
+                                const beforeLines = new Set(beforeOutput.split('\n'));
+                                newContent = afterOutput
+                                    .split('\n')
+                                    .filter((line) => !beforeLines.has(line))
+                                    .join('\n');
+                            }
+                            const hasProcessingIndicators = containsProcessingIndicator(newContent || afterOutput.slice(-500));
+                            const significantLengthChange = Math.abs(lengthDiff) > 10;
+                            const delivered = (lengthDiff > 20)
+                                || (contentChanged && significantLengthChange)
+                                || hasProcessingIndicators;
+                            if (delivered) {
+                                const hasStrongSignal = hasProcessingIndicators;
+                                const logLevel = hasStrongSignal ? 'debug' : 'warn';
+                                this.logger[logLevel](`Message delivery verified (${hasStrongSignal ? 'strong' : 'weak'} signal)`, {
+                                    sessionName,
+                                    attempt,
+                                    lengthDiff,
+                                    contentChanged,
+                                    hasProcessingIndicators,
+                                    newContentLength: newContent.length,
+                                    signal: hasStrongSignal ? 'processing-indicators' : 'output-length-change-only',
+                                });
+                                return true;
+                            }
+                            this.logger.warn('TUI output did not change after send — message may not have been accepted', {
+                                sessionName,
+                                attempt,
+                                lengthDiff,
+                                contentChanged,
+                                hasProcessingIndicators,
+                                newContentLength: newContent.length,
+                            });
+                        }
+                    }
+                }
+                // Message stuck at prompt — clear line and retry.
+                this.logger.warn('Message stuck at prompt after send, clearing for retry', {
+                    sessionName,
+                    attempt,
+                });
+                if (isClaudeCode) {
+                    await sessionHelper.clearCurrentCommandLine(sessionName);
+                }
+                else {
+                    // Gemini CLI retry cleanup: NEVER send Ctrl+C — it triggers /quit
+                    // and kills the CLI entirely, regardless of whether text is in the
+                    // input box or not. Use Tab to cycle Ink focus back to the input
+                    // prompt, then Enter to submit any pending text.
+                    this.logger.warn('Gemini CLI message stuck — using Tab focus recovery (no Ctrl+C)', {
+                        sessionName,
+                        attempt,
+                    });
+                    await sessionHelper.sendKey(sessionName, 'Tab');
+                    await delay(300);
+                    await sessionHelper.sendEnter(sessionName);
+                    await delay(300);
+                }
+                await delay(SESSION_COMMAND_DELAYS.CLEAR_COMMAND_DELAY);
+                if (attempt < maxAttempts) {
+                    await delay(SESSION_COMMAND_DELAYS.MESSAGE_RETRY_DELAY);
+                }
+            }
+            catch (error) {
+                this.logger.error('Error during message delivery', {
+                    sessionName,
+                    attempt,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                if (attempt < maxAttempts) {
+                    await delay(SESSION_COMMAND_DELAYS.MESSAGE_RETRY_DELAY);
+                }
+            }
+        }
+        this.logger.warn('Message delivery verification failed — all attempts exhausted', {
+            sessionName,
+            maxAttempts,
+            messageLength: message.length,
+        });
+        this.logger.error('Message delivery failed after all retry attempts', {
+            sessionName,
+            maxAttempts,
+            messageLength: message.length,
+        });
+        return false;
+    }
+    /**
+     * Check if a sent message is stuck at the terminal prompt (Enter was not accepted).
+     *
+     * Captures the current terminal pane and looks for the message text still visible
+     * on the last few lines. If the text is found, Enter was not processed and the
+     * message is stuck.
+     *
+     * @param sessionName - The session to check
+     * @param message - The original message that was sent
+     * @returns true if the message text is still visible at the prompt (stuck)
+     */
+    async isMessageStuckAtPrompt(sessionName, message) {
+        try {
+            const sessionHelper = await this.getSessionHelper();
+            const output = sessionHelper.capturePane(sessionName);
+            if (!output || output.trim().length === 0) {
+                return false;
+            }
+            // Extract a search token from the message:
+            // Strip [CHAT:uuid] prefix if present, then take the first 40 chars
+            const { prefixLength } = extractChatPrefix(message);
+            const contentAfterPrefix = prefixLength > 0
+                ? message.slice(prefixLength)
+                : message;
+            const searchToken = contentAfterPrefix.slice(0, 40).trim();
+            // Also use [CHAT: as a secondary token if message has a CHAT prefix
+            const chatToken = prefixLength > 0 ? '[CHAT:' : null;
+            // Check last 20 non-empty lines for either token.
+            // Gemini CLI TUI has status bars at the bottom (branch, sandbox, model info)
+            // that push input content further up. 5 lines was insufficient.
+            const lines = output.split('\n').filter((line) => line.trim().length > 0);
+            const linesToCheck = lines.slice(-20);
+            const isStuck = linesToCheck.some((line) => {
+                // Strip TUI box-drawing borders before checking (Gemini CLI wraps content in │...│)
+                const stripped = stripTuiLineBorders(line);
+                if (searchToken && (line.includes(searchToken) || stripped.includes(searchToken)))
+                    return true;
+                if (chatToken && (line.includes(chatToken) || stripped.includes(chatToken)))
+                    return true;
+                return false;
+            });
+            this.logger.debug('isMessageStuckAtPrompt result', {
+                sessionName,
+                isStuck,
+                searchToken: searchToken.slice(0, 20),
+                linesChecked: linesToCheck.length,
+            });
+            return isStuck;
+        }
+        catch (error) {
+            this.logger.warn('Error checking if message stuck at prompt', {
+                sessionName,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return false;
+        }
+    }
+    /**
+     * Check if message text is stuck at the TUI prompt line (Enter was not pressed).
+     *
+     * Unlike `isMessageStuckAtPrompt` which checks the last 20 lines for the message
+     * text ANYWHERE, this method specifically checks whether the message text appears
+     * ON the prompt line itself (the line starting with `> ` or `│ > `).
+     *
+     * After Enter is successfully pressed, the text moves from the prompt line to the
+     * chat history area. So if the text is still on the prompt line, Enter was dropped.
+     *
+     * This avoids the false positive problem where `isMessageStuckAtPrompt` matches
+     * the message text in the TUI's chat history (which echoes submitted messages).
+     *
+     * @param sessionName - The session to check
+     * @param message - The original message that was sent
+     * @returns true if the message text is visible on the TUI prompt line (stuck)
+     */
+    isTextStuckAtTuiPrompt(sessionName, message) {
+        try {
+            const sessionHelper = this._sessionHelper;
+            if (!sessionHelper)
+                return false;
+            const output = sessionHelper.capturePane(sessionName);
+            if (!output || output.trim().length === 0)
+                return false;
+            // Extract search token: first 30 chars of the message content
+            // (after stripping any [CHAT:uuid] prefix)
+            const { prefixLength } = extractChatPrefix(message);
+            const contentAfterPrefix = prefixLength > 0
+                ? message.slice(prefixLength)
+                : message;
+            const searchToken = contentAfterPrefix.slice(0, 30).trim();
+            if (!searchToken)
+                return false;
+            // Find lines that look like a TUI prompt with text after it.
+            // Gemini CLI TUI wraps content in box-drawing borders: │ > text │
+            // Or without borders: > text
+            // The prompt line is the line with `> ` followed by actual content.
+            const lines = output.split('\n');
+            for (let i = lines.length - 1; i >= Math.max(0, lines.length - 25); i--) {
+                const line = lines[i];
+                const promptContent = matchTuiPromptLine(line);
+                if (promptContent !== null) {
+                    const trimmedContent = stripTuiLineBorders(promptContent).trim();
+                    // Check if the prompt line content contains our message text.
+                    // Only check the BOTTOMMOST prompt line — historical echoes of
+                    // submitted messages also appear as `> text` further up in the
+                    // TUI conversation history. Without this break, those echoes
+                    // cause false "stuck" detections even after the message was
+                    // successfully delivered.
+                    if (trimmedContent.length > 5 && trimmedContent.includes(searchToken)) {
+                        this.logger.warn('Text stuck at TUI prompt — Enter was not pressed', {
+                            sessionName,
+                            searchToken: searchToken.slice(0, 20),
+                            promptContent: promptContent.slice(0, 60),
+                        });
+                        return true;
+                    }
+                    break; // Only check the first (bottommost) prompt line
+                }
+            }
+            return false;
+        }
+        catch (error) {
+            this.logger.debug('Error in isTextStuckAtTuiPrompt', {
+                sessionName,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return false;
+        }
+    }
+    /**
+     * Attempt to recover from text stuck at TUI prompt by pressing Enter.
+     * Checks if text is stuck, sends Enter, waits, then verifies.
+     *
+     * @param sessionName - The session to recover
+     * @param message - The original message
+     * @returns true if recovery succeeded (text is no longer at prompt)
+     */
+    async recoverStuckTuiMessage(sessionName, message) {
+        const sessionHelper = await this.getSessionHelper();
+        // Tab restores Ink TUI focus, then Enter to submit the stuck text.
+        // Without Tab, Enter may be consumed by the framework but not routed
+        // to the input component if focus was lost during a re-render.
+        this.logger.info('Pressing Tab+Enter to recover stuck TUI message', { sessionName });
+        await sessionHelper.sendKey(sessionName, 'Tab');
+        await delay(200);
+        await sessionHelper.sendEnter(sessionName);
+        await delay(500);
+        // Double-tap: send a backup Enter in case the first was consumed
+        await sessionHelper.sendEnter(sessionName);
+        await delay(2000);
+        // Verify text is no longer at prompt
+        const stillStuck = this.isTextStuckAtTuiPrompt(sessionName, message);
+        if (!stillStuck) {
+            this.logger.info('TUI message recovery succeeded — Enter accepted', { sessionName });
+            return true;
+        }
+        this.logger.warn('TUI message still stuck after Enter recovery', { sessionName });
+        return false;
+    }
+    /**
+     * Start a background scanner that periodically checks all registered TUI
+     * sessions for text stuck at the prompt (Enter not pressed).
+     *
+     * This is a safety net that catches messages missed by the per-send
+     * verification in `sendMessageWithRetry`. It scans every 30 seconds.
+     *
+     * When stuck text is detected, the scanner presses Enter to recover.
+     * If text has been sitting at the prompt for multiple consecutive scans,
+     * it escalates to Tab + Enter (TUI focus recovery).
+     */
+    startStuckMessageDetector() {
+        if (this.stuckMessageDetectorTimer) {
+            this.logger.debug('Stuck message detector already running');
+            return;
+        }
+        const SCAN_INTERVAL_MS = 30000; // 30 seconds
+        this.logger.info('Starting background stuck-message detector', {
+            intervalMs: SCAN_INTERVAL_MS,
+        });
+        this.stuckMessageDetectorTimer = setInterval(async () => {
+            try {
+                await this.scanForStuckMessages();
+            }
+            catch (error) {
+                this.logger.debug('Stuck message scan error (non-fatal)', {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }, SCAN_INTERVAL_MS);
+    }
+    /**
+     * Stop the background stuck-message detector.
+     */
+    stopStuckMessageDetector() {
+        if (this.stuckMessageDetectorTimer) {
+            clearInterval(this.stuckMessageDetectorTimer);
+            this.stuckMessageDetectorTimer = null;
+            this.logger.info('Stopped background stuck-message detector');
+        }
+    }
+    /**
+     * Scan all sessions for stuck messages. Two complementary strategies:
+     *
+     * 1. TUI prompt-line scanning (existing): checks registered TUI sessions
+     *    for text sitting on the `> ` prompt line.
+     * 2. Tracked-message scanning (new, all runtimes): checks if any recently
+     *    sent message text is still visible at the bottom of the terminal
+     *    after 15+ seconds — runtime-agnostic Enter-drop detection.
+     */
+    async scanForStuckMessages() {
+        const sessionHelper = this._sessionHelper;
+        if (!sessionHelper)
+            return;
+        // --- Part 0: Rewind mode detection (all sessions) ---
+        // If Claude Code is stuck in Rewind mode (triggered by ESC during
+        // processing), send 'q' to exit before any other recovery attempts.
+        for (const sessionName of sessionHelper.listSessions()) {
+            try {
+                const output = sessionHelper.capturePane(sessionName);
+                if (containsRewindMode(output)) {
+                    this.logger.warn('Rewind mode detected, sending q to exit', { sessionName });
+                    sessionHelper.writeRaw(sessionName, 'q');
+                    await delay(500);
+                }
+            }
+            catch {
+                // Non-fatal: session may have been destroyed
+            }
+        }
+        // --- Part 1: Existing TUI prompt-line scanning ---
+        for (const [sessionName, runtimeType] of this.tuiSessionRegistry) {
+            try {
+                // Skip Gemini CLI sessions — their TUI prompt behaves differently
+                // and false-positive stuck detection causes Tab+Enter spam.
+                if (runtimeType === RUNTIME_TYPES.GEMINI_CLI) {
+                    continue;
+                }
+                // #213: Skip orchestrator — it frequently waits for long-running
+                // agent tasks (30+ min), and false stuck detection causes disruptive
+                // Tab+Enter key injections that interrupt its workflow.
+                if (sessionName === ORCHESTRATOR_SESSION_NAME) {
+                    continue;
+                }
+                // Skip sessions that no longer exist
+                if (!sessionHelper.sessionExists(sessionName)) {
+                    this.tuiSessionRegistry.delete(sessionName);
+                    continue;
+                }
+                const output = sessionHelper.capturePane(sessionName);
+                if (!output || output.trim().length === 0)
+                    continue;
+                // Look for any text sitting on the prompt line
+                const lines = output.split('\n');
+                for (let i = lines.length - 1; i >= Math.max(0, lines.length - 25); i--) {
+                    const promptContent = matchTuiPromptLine(lines[i]);
+                    if (promptContent !== null) {
+                        const trimmedContent = stripTuiLineBorders(promptContent).trim();
+                        // Only act on substantial text (> 10 chars) to avoid false positives
+                        // from TUI rendering artifacts or short status text
+                        if (trimmedContent.length > 10) {
+                            // Skip known idle placeholder text that sits at
+                            // the `> ` prompt when no user input is present. These are
+                            // NOT stuck messages — they are TUI decoration.
+                            const lowerContent = trimmedContent.toLowerCase();
+                            const isPlaceholder = lowerContent.startsWith('type your message') ||
+                                trimmedContent.startsWith('@'); // e.g., "@path/to/file"
+                            if (isPlaceholder) {
+                                break;
+                            }
+                            this.logger.warn('Background scan: text stuck at TUI prompt, pressing Tab+Enter', {
+                                sessionName,
+                                promptContent: promptContent.slice(0, 80),
+                            });
+                            // Tab restores Ink TUI focus before Enter
+                            await sessionHelper.sendKey(sessionName, 'Tab');
+                            await delay(200);
+                            await sessionHelper.sendEnter(sessionName);
+                            await delay(500);
+                            // Backup Enter
+                            await sessionHelper.sendEnter(sessionName);
+                        }
+                        break; // Only check the first prompt line found from the bottom
+                    }
+                }
+            }
+            catch (error) {
+                this.logger.debug('Error scanning session for stuck messages', {
+                    sessionName,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        // --- Part 2: Tracked-message scanning (non-Gemini runtimes) ---
+        const now = Date.now();
+        const MIN_AGE_MS = 10000; // Check messages older than 10s
+        const MAX_RECOVERY_ATTEMPTS = 5; // Give up after 5 Tab+Enter attempts
+        for (const [sessionName, entries] of this.sentMessageTracker) {
+            if (!sessionHelper.sessionExists(sessionName)) {
+                this.sentMessageTracker.delete(sessionName);
+                continue;
+            }
+            // Skip Gemini CLI sessions — Tab+Enter recovery causes more harm
+            // than good because the Gemini TUI handles input differently.
+            const trackedRuntime = this.tuiSessionRegistry.get(sessionName);
+            if (trackedRuntime === RUNTIME_TYPES.GEMINI_CLI) {
+                continue;
+            }
+            try {
+                const output = sessionHelper.capturePane(sessionName);
+                if (!output || output.trim().length === 0)
+                    continue;
+                const bottomText = output.split('\n').slice(-15).join(' ').replace(/\s+/g, ' ');
+                for (const entry of entries) {
+                    if (entry.recovered)
+                        continue;
+                    if (now - entry.sentAt < MIN_AGE_MS)
+                        continue;
+                    if (entry.recoveryAttempts >= MAX_RECOVERY_ATTEMPTS) {
+                        // Exhausted recovery attempts — mark as recovered to stop retrying
+                        entry.recovered = true;
+                        this.logger.error('Background scan: max recovery attempts exhausted', {
+                            sessionName,
+                            snippet: entry.snippet.slice(0, 50),
+                            attempts: entry.recoveryAttempts,
+                        });
+                        continue;
+                    }
+                    if (bottomText.includes(entry.snippet)) {
+                        entry.recoveryAttempts++;
+                        this.logger.warn('Background scan: tracked message stuck, pressing Tab+Enter', {
+                            sessionName,
+                            snippet: entry.snippet.slice(0, 50),
+                            ageMs: now - entry.sentAt,
+                            attempt: entry.recoveryAttempts,
+                            maxAttempts: MAX_RECOVERY_ATTEMPTS,
+                        });
+                        // Tab restores Ink TUI focus before Enter
+                        await sessionHelper.sendKey(sessionName, 'Tab');
+                        await delay(200);
+                        await sessionHelper.sendEnter(sessionName);
+                        await delay(500);
+                        await sessionHelper.sendEnter(sessionName); // backup
+                        break; // One recovery per session per scan cycle
+                    }
+                }
+            }
+            catch (error) {
+                this.logger.debug('Error scanning tracked messages for session', {
+                    sessionName,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        // Clean up old tracked-message entries
+        for (const [sessionName, entries] of this.sentMessageTracker) {
+            const fresh = entries.filter(e => now - e.sentAt < 5 * 60 * 1000);
+            if (fresh.length === 0) {
+                this.sentMessageTracker.delete(sessionName);
+            }
+            else {
+                this.sentMessageTracker.set(sessionName, fresh);
+            }
+        }
+    }
+    /**
+     * Unregister a TUI session from the stuck-message detector.
+     * Call this when a session is destroyed or agent is stopped.
+     *
+     * @param sessionName - The session to unregister
+     */
+    unregisterTuiSession(sessionName) {
+        this.tuiSessionRegistry.delete(sessionName);
+        this.sentMessageTracker.delete(sessionName);
+    }
+    /**
+     * Register a message that was sent to a session for background
+     * stuck-detection. The scanner will periodically check if the
+     * message text is still visible at the bottom of the terminal.
+     *
+     * @param sessionName - The session the message was sent to
+     * @param message - The full message text
+     */
+    trackSentMessage(sessionName, message) {
+        // Extract a search snippet: skip [CHAT:uuid] prefix, take first 80 chars
+        const { prefixLength } = extractChatPrefix(message);
+        const contentStart = prefixLength;
+        // Normalize whitespace: messages may contain \n from enhanced templates.
+        // Terminal bottom text is join(' '), so \n in snippet would never match.
+        const snippet = message.slice(contentStart, contentStart + 80).replace(/\s+/g, ' ').trim();
+        if (snippet.length < 10)
+            return; // Too short to reliably match
+        const entries = this.sentMessageTracker.get(sessionName) || [];
+        entries.push({ snippet, sentAt: Date.now(), recovered: false, recoveryAttempts: 0 });
+        // Keep only last 5 minutes of entries
+        const cutoff = Date.now() - 5 * 60 * 1000;
+        this.sentMessageTracker.set(sessionName, entries.filter(e => e.sentAt > cutoff));
+        // Ensure the background scanner is running
+        this.startStuckMessageDetector();
+    }
+    /**
+     * Check if the agent appears to be at an input prompt.
+     * Delegates to the regex-free isAgentAtPrompt() from terminal-string-ops,
+     * with additional logging and per-line prompt detection using isPromptLine().
+     *
+     * @param terminalOutput - The terminal output to check
+     * @param runtimeType - The runtime type for pattern selection
+     * @returns true if the agent appears to be at a prompt
+     */
+    isClaudeAtPrompt(terminalOutput, runtimeType) {
+        // Handle null/undefined/empty input — return false since an empty buffer
+        // may indicate a crashed session or one that hasn't started yet
+        if (!terminalOutput || typeof terminalOutput !== 'string') {
+            this.logger.debug('Terminal output is empty or invalid, cannot detect prompt', { runtimeType });
+            return false;
+        }
+        // Only analyze the tail of the buffer to avoid matching historical prompts.
+        // Use 5000 chars to accommodate large tool outputs that push the prompt
+        // further back in the buffer (#106).
+        const tailSection = terminalOutput.slice(-5000);
+        // Check for prompt FIRST. Processing indicators like "thinking" or "analyzing"
+        // can appear in the agent's previous response text and persist in the terminal
+        // scroll buffer, causing false negatives if checked before the prompt.
+        const lines = tailSection.split('\n').filter((line) => line.trim().length > 0);
+        const linesToCheck = lines.slice(-10);
+        const hasPrompt = linesToCheck.some(line => isPromptLine(line, runtimeType));
+        if (hasPrompt) {
+            return true;
+        }
+        // No prompt found — check if still processing.
+        // Check last 10 lines (not just 5) because tool output can push processing
+        // indicators further up while the status bar stays at the bottom.
+        const recentLines = linesToCheck.join('\n');
+        if (containsProcessingIndicator(recentLines)) {
+            this.logger.debug('Processing indicators present near bottom of output');
+            return false;
+        }
+        // Check for "esc to interrupt" in the status bar — this is a definitive
+        // busy signal. Claude Code only shows this text while actively processing.
+        // It disappears when the agent returns to idle at the prompt.
+        if (containsBusyStatusBar(recentLines)) {
+            this.logger.debug('Busy status bar detected (esc to interrupt)');
+            return false;
+        }
+        this.logger.debug('No prompt detected in terminal output', {
+            tailLength: tailSection.length,
+            lastLines: linesToCheck.slice(-3).map(l => l.substring(0, 80)),
+            runtimeType,
+        });
+        return false;
+    }
+    /**
+     * Detect if Gemini CLI is currently in shell mode.
+     *
+     * In shell mode, Gemini CLI changes its prompt from `>` to `!`. Any input
+     * sent in this mode is executed as a shell command instead of being passed
+     * to the model. This method examines the last few lines of terminal output
+     * for shell mode prompt indicators.
+     *
+     * @param terminalOutput - Captured terminal pane content
+     * @returns true if the terminal shows a shell mode prompt
+     */
+    isGeminiInShellMode(terminalOutput) {
+        if (!terminalOutput || typeof terminalOutput !== 'string') {
+            return false;
+        }
+        const lines = terminalOutput.split('\n').filter((line) => line.trim().length > 0);
+        const linesToCheck = lines.slice(-10);
+        return linesToCheck.some((line) => {
+            const trimmed = line.trim();
+            // Strip TUI box-drawing borders
+            const stripped = trimmed.replace(/^[│┃|]+\s*/, '').replace(/\s*[│┃|]+$/, '');
+            // Shell mode prompt: `!` alone or `! ` with text (not `> ` which is normal mode)
+            // Check stripped line — after removing box-drawing, if it starts with `! ` or equals `!`
+            if (stripped === '!' || stripped.startsWith('! ')) {
+                return true;
+            }
+            // Also check pattern-based detection for bordered prompts
+            return GEMINI_SHELL_MODE_CONSTANTS.SHELL_MODE_PROMPT_PATTERNS.some((pattern) => pattern.test(trimmed));
+        });
+    }
+    /**
+     * Escape from Gemini CLI shell mode by sending Escape key.
+     *
+     * Sends Escape and waits for the prompt to change from `!` back to `>`.
+     * Retries up to MAX_ESCAPE_ATTEMPTS times.
+     *
+     * @param sessionName - The session running Gemini CLI
+     * @param sessionHelper - SessionCommandHelper instance
+     * @returns true if successfully escaped shell mode, false if still in shell mode
+     */
+    async escapeGeminiShellMode(sessionName, sessionHelper) {
+        for (let attempt = 1; attempt <= GEMINI_SHELL_MODE_CONSTANTS.MAX_ESCAPE_ATTEMPTS; attempt++) {
+            this.logger.info('Gemini CLI in shell mode, sending Escape to exit', {
+                sessionName,
+                attempt,
+            });
+            await sessionHelper.sendEscape(sessionName);
+            await delay(GEMINI_SHELL_MODE_CONSTANTS.ESCAPE_DELAY_MS);
+            // Check if we're back to normal mode
+            const output = sessionHelper.capturePane(sessionName);
+            if (!this.isGeminiInShellMode(output)) {
+                this.logger.info('Successfully exited Gemini CLI shell mode', {
+                    sessionName,
+                    attempt,
+                });
+                return true;
+            }
+        }
+        this.logger.warn('Failed to exit Gemini CLI shell mode after max attempts', {
+            sessionName,
+            maxAttempts: GEMINI_SHELL_MODE_CONSTANTS.MAX_ESCAPE_ATTEMPTS,
+        });
+        return false;
+    }
+    /**
+     * Generic key sending to any agent session
+     * @param sessionName The agent session name
+     * @param key The key to send (e.g., 'Enter', 'Ctrl+C')
+     * @returns Promise with success/error information
+     */
+    async sendKeyToAgent(sessionName, key) {
+        try {
+            // Get session helper once to avoid repeated async calls
+            const sessionHelper = await this.getSessionHelper();
+            // Check if session exists
+            const sessionExists = sessionHelper.sessionExists(sessionName);
+            if (!sessionExists) {
+                return {
+                    success: false,
+                    error: `Session '${sessionName}' does not exist`,
+                };
+            }
+            // Send key using session command helper
+            await sessionHelper.sendKey(sessionName, key);
+            this.logger.info('Key sent to agent successfully', {
+                sessionName,
+                key,
+            });
+            return {
+                success: true,
+                message: `${key} key sent to agent successfully`,
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger.error('Failed to send key to agent', {
+                sessionName,
+                key,
+                error: errorMessage,
+            });
+            return {
+                success: false,
+                error: errorMessage,
+            };
+        }
+    }
+    /**
+     * Generic health check for any agent session
+     * @param sessionName The agent session name
+     * @param role The agent role for additional context
+     * @param timeout Timeout for health check in milliseconds
+     * @returns Promise with health status information
+     */
+    async checkAgentHealth(sessionName, role, timeout = 1000) {
+        try {
+            // Lightweight health check with timeout
+            const agentRunning = await Promise.race([
+                (await this.getSessionHelper()).sessionExists(sessionName),
+                new Promise((_, reject) => setTimeout(() => reject(new Error('Health check timeout')), timeout)),
+            ]).catch(() => false);
+            return {
+                success: true,
+                data: {
+                    agent: {
+                        sessionName,
+                        role,
+                        running: agentRunning,
+                        status: agentRunning
+                            ? CREWLY_CONSTANTS.AGENT_STATUSES.ACTIVE
+                            : CREWLY_CONSTANTS.AGENT_STATUSES.INACTIVE,
+                    },
+                    timestamp: new Date().toISOString(),
+                },
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger.error('Failed to check agent health', {
+                sessionName,
+                role,
+                error: errorMessage,
+            });
+            return {
+                success: false,
+                error: errorMessage,
+            };
+        }
+    }
+    /**
+     * Write the prompt to a file and send a short instruction to the agent to read it.
+     *
+     * Instead of pasting large multi-line prompts directly into the terminal (which
+     * causes bracketed paste issues, shell interpretation errors, and truncation),
+     * we write the prompt to ~/.crewly/prompts/{sessionName}-init.md and send a
+     * single-line instruction telling the agent to read that file.
+     *
+     * @param sessionName The session name
+     * @param prompt The full system prompt to deliver
+     * @param runtimeType The agent runtime type
+     * @param abortSignal Optional signal to cancel the operation (e.g. on runtime exit)
+     * @returns true if the instruction was delivered successfully
+     */
+    async sendPromptRobustly(sessionName, prompt, runtimeType = RUNTIME_TYPES.CLAUDE_CODE, abortSignal) {
+        const isClaudeCode = runtimeType === RUNTIME_TYPES.CLAUDE_CODE;
+        const sessionHelper = await this.getSessionHelper();
+        // Step 1: Write prompt to a file (idempotent — may already exist from pre-launch write).
+        const promptFilePath = await this.writePromptFile(sessionName, prompt);
+        if (!promptFilePath) {
+            // File write failure is fatal — all runtimes use the file-read approach.
+            return false;
+        }
+        // Step 2: Build the message to send.
+        // Claude Code: prompt was already loaded via --agent flag at launch (#207),
+        // so the agent already has all instructions as its agent definition. Just send a short
+        // kickoff trigger — no need to ask it to read the file again.
+        // Gemini CLI / other runtimes: need the file-read instruction since the prompt
+        // was NOT loaded via system prompt.
+        const messageToSend = isClaudeCode
+            ? 'Begin your work now. Follow the step-by-step instructions in your agent definition EXACTLY — start with Step 1, then Step 2, then Step 3 (register-self). Do NOT skip or reorder steps. Registration is required before the system will deliver messages to you.'
+            : `Read the file at ${promptFilePath} and follow all instructions in it.`;
+        // Note: kickoff message is intentionally imperative for reliable agent bootstrapping.
+        // The --agent flag (Claude Code) loads the prompt as trusted system context, so this
+        // short trigger is not subject to PI detection.
+        // Single attempt for all runtimes. Retrying causes duplicate messages because:
+        // - Claude Code: returns to its prompt between tool calls, making retry
+        //   checks think the first message wasn't received.
+        // - Gemini CLI: the echoed message "Read the file at..." starts with `> `
+        //   which isClaudeAtPrompt misdetects as an idle prompt, and the TUI's
+        //   input box shows `> ` even during processing. Both cause false-negative
+        //   delivery verification and unnecessary retries.
+        // The sendMessage helper reliably writes to the PTY — if it succeeds,
+        // the message was delivered.
+        const maxAttempts = 1;
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            // Check abort before each attempt
+            if (abortSignal?.aborted) {
+                this.logger.info('Prompt delivery aborted (runtime exited)', { sessionName, attempt });
+                return false;
+            }
+            try {
+                this.logger.info('Sending prompt to agent', {
+                    sessionName,
+                    attempt,
+                    runtimeType,
+                    promptFilePath,
+                    deliveryMethod: isClaudeCode ? 'system-prompt-kickoff' : 'file-read',
+                });
+                // Check abort before sending to terminal
+                if (abortSignal?.aborted) {
+                    this.logger.info('Prompt delivery aborted before send (runtime exited)', { sessionName });
+                    return false;
+                }
+                // Clear any pending input before sending the instruction (first attempt only).
+                if (attempt === 1) {
+                    if (isClaudeCode) {
+                        // Claude Code: Escape closes slash menus + Ctrl+U clears line.
+                        await sessionHelper.sendEscape(sessionName);
+                        await delay(200);
+                        await sessionHelper.sendKey(sessionName, 'C-u');
+                        await delay(300);
+                    }
+                    else if (runtimeType === RUNTIME_TYPES.CODEX_CLI) {
+                        // #246: Codex CLI — Ctrl+U to clear any stale input text.
+                        // Unlike Gemini, Codex doesn't need Enter flush; its Ink TUI
+                        // handles Ctrl+U for line clear similar to Claude Code.
+                        await sessionHelper.sendKey(sessionName, 'C-u');
+                        await delay(300);
+                    }
+                    else {
+                        // Gemini CLI (Ink TUI): After /directory add processing, the TUI
+                        // input may lose focus or have stale invisible characters.
+                        // Send Enter to flush any residual input, then wait for the
+                        // prompt to settle before sending the real instruction.
+                        this.logger.debug('Gemini CLI pre-send: flushing input with Enter', { sessionName });
+                        await sessionHelper.sendEnter(sessionName);
+                        await delay(1000);
+                    }
+                }
+                // Check abort right before writing instruction to terminal
+                if (abortSignal?.aborted) {
+                    this.logger.info('Prompt delivery aborted before instruction send (runtime exited)', { sessionName });
+                    return false;
+                }
+                // Send the kickoff / file-read instruction
+                await sessionHelper.sendMessage(sessionName, messageToSend);
+                // Claude Code: rapid-check verification.
+                // Check every 1s for up to 24s (Claude v2 first-token can be slow: MCP/skill load) whether Claude started processing.
+                // If Claude leaves the prompt at any point, the message was received.
+                // This avoids the old length-comparison approach which was unreliable
+                // (Claude's TUI redraws change output length unpredictably).
+                if (isClaudeCode) {
+                    for (let i = 0; i < 24; i++) {
+                        await delay(1000);
+                        if (abortSignal?.aborted)
+                            return false;
+                        const currentOutput = sessionHelper.capturePane(sessionName);
+                        // Processing indicators (spinners) = definitive success
+                        if (containsSpinnerOrWorkingIndicator(currentOutput)) {
+                            this.logger.debug('Kickoff delivered — processing indicators detected', {
+                                sessionName, checkIndex: i,
+                            });
+                            return true;
+                        }
+                        // Claude left the prompt = started working on the message
+                        if (!this.isClaudeAtPrompt(currentOutput, RUNTIME_TYPES.CLAUDE_CODE)) {
+                            this.logger.debug('Kickoff delivered — Claude left prompt', {
+                                sessionName, checkIndex: i,
+                            });
+                            return true;
+                        }
+                    }
+                    // Claude still at prompt after 8s — message likely not received.
+                    // For Claude Code with --append-system-prompt-file, don't retry
+                    // (would cause duplicate). Log warning and return false.
+                    // Still at prompt — the kickoff was likely typed but not submitted (PTY submit
+                    // can be dropped). A missing agent costs far more than a duplicate kickoff
+                    // (idempotent: it just re-reads the prompt file), so resend ONCE and re-poll.
+                    this.logger.warn('Kickoff unconfirmed after 24s — resending once', { sessionName, runtimeType });
+                    await sessionHelper.sendMessage(sessionName, messageToSend);
+                    for (let j = 0; j < 12; j++) {
+                        await delay(1000);
+                        if (abortSignal?.aborted)
+                            return false;
+                        const out2 = sessionHelper.capturePane(sessionName);
+                        if (containsSpinnerOrWorkingIndicator(out2) || !this.isClaudeAtPrompt(out2, RUNTIME_TYPES.CLAUDE_CODE)) {
+                            this.logger.debug('Kickoff delivered on resend', { sessionName, checkIndex: j });
+                            return true;
+                        }
+                    }
+                    this.logger.warn('Kickoff delivery unconfirmed after resend — giving up', { sessionName, runtimeType });
+                    return false;
+                }
+                // Gemini CLI / other runtimes: trust the PTY delivery.
+                // sendMessage writes directly to the PTY — if it didn't throw,
+                // the message was delivered. Terminal-based verification is unreliable
+                // because Gemini's TUI always shows `> ` (even during processing)
+                // and our echoed message starts with `> `, both causing false
+                // "at prompt" detection.
+                this.logger.info('Prompt instruction sent to PTY (trusting delivery)', {
+                    sessionName, attempt, runtimeType,
+                    messageLength: messageToSend.length,
+                });
+                return true;
+            }
+            catch (error) {
+                this.logger.error('Error during prompt instruction delivery', {
+                    sessionName,
+                    attempt,
+                    runtimeType,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                if (attempt === maxAttempts) {
+                    return false;
+                }
+            }
+        }
+        this.logger.warn('Prompt instruction delivery unconfirmed after all attempts (agent may still process it)', {
+            sessionName,
+            maxAttempts,
+            runtimeType,
+        });
+        return false;
+    }
+    /**
+     * Capture the current PTY output of a running agent session.
+     *
+     * Used by the queue processor to verify that a force-delivered message
+     * was actually seen by the agent (pending-ack verification).
+     *
+     * @param sessionName - The agent session name
+     * @param lines - Number of lines to capture (default 200)
+     * @returns The captured terminal output, or empty string if session not found
+     */
+    async captureAgentOutput(sessionName, lines = 200) {
+        try {
+            const sessionHelper = await this.getSessionHelper();
+            if (!sessionHelper.sessionExists(sessionName)) {
+                return '';
+            }
+            return sessionHelper.capturePane(sessionName, lines);
+        }
+        catch {
+            return '';
+        }
+    }
+}
+//# sourceMappingURL=agent-registration.service.js.map