@made-by-moonlight/athene-core 0.9.1

package/dist/session-manager.js

@@ -0,0 +1,3077 @@
+import { existsSync, statSync, mkdirSync, writeFileSync, unlinkSync, utimesSync } from 'node:fs';
+import { recordActivityEvent } from './activity-events.js';
+import { execFile } from 'node:child_process';
+import { join, resolve, basename } from 'node:path';
+import { homedir } from 'node:os';
+import { promisify } from 'node:util';
+import { PR_STATE, isRestorable, SessionNotFoundError, SessionNotRestorableError, NON_RESTORABLE_STATUSES, WorkspaceMissingError, isTerminalSession, isIssueNotFoundError } from './types.js';
+import { listMetadata, readMetadataRaw, updateMetadata, mutateMetadata, deleteMetadata, writeMetadata, applyMetadataUpdates, reserveSessionId } from './metadata.js';
+import { deriveLegacyStatus, parseCanonicalLifecycle, cloneLifecycle, buildLifecycleMetadataPatch, clearTerminalMarkersForNonTerminalState, createInitialCanonicalLifecycle } from './lifecycle-state.js';
+import { buildPrompt } from './prompt-builder.js';
+import { createActivitySignal, classifyActivitySignal } from './activity-signal.js';
+import { getProjectSessionsDir, getProjectWorktreesDir, getProjectDir, generateSessionName } from './paths.js';
+import { asValidOpenCodeSessionId } from './opencode-session-id.js';
+import { getOpenCodeChildEnv, invalidateOpenCodeSessionListCache, getCachedOpenCodeSessionList } from './opencode-shared.js';
+import { writeWorkspaceOpenCodeAgentsMd } from './opencode-agents-md.js';
+import { writeOpenCodeConfig } from './opencode-config.js';
+import { CleanupStack } from './cleanup-stack.js';
+import { getOrchestratorSessionId, normalizeOrchestratorSessionStrategy } from './orchestrator-session-strategy.js';
+import { sessionFromMetadata } from './utils/session-from-metadata.js';
+import { dedupePrUrls } from './utils/pr.js';
+import { safeJsonParse, validateStatus } from './utils/validation.js';
+import { isGitBranchNameSafe } from './utils.js';
+import { resolveAgentSelectionForSession, resolveAgentSelection } from './agent-selection.js';
+import { PREFERRED_GH_PATH, buildAgentPath, setupPathWrapperWorkspace } from './agent-workspace-hooks.js';
+
+/**
+ * Session Manager — CRUD for agent sessions.
+ *
+ * Orchestrates Runtime, Agent, and Workspace plugins to:
+ * - Spawn new sessions (create workspace → create runtime → launch agent)
+ * - List sessions (from metadata + live runtime checks)
+ * - Kill sessions (agent → runtime → workspace cleanup)
+ * - Cleanup completed sessions (PR merged / issue closed)
+ * - Send messages to running sessions
+ *
+ * Reference: scripts/claude-ao-session, scripts/send-to-session
+ */
+const execFileAsync = promisify(execFile);
+const OPENCODE_DISCOVERY_TIMEOUT_MS = 10_000;
+const OPENCODE_INTERACTIVE_DISCOVERY_TIMEOUT_MS = 10_000;
+const INDEXED_PR_METADATA_KEY_REGEX = /^(prEnrichment|prReviewComments)_\d+$/;
+// On Windows, execFile cannot resolve .cmd shim extensions without invoking the shell.
+// windowsHide:true suppresses the conhost popup that the shell would otherwise flash.
+const EXEC_SHELL_OPTION = process.platform === "win32" ? { shell: true, windowsHide: true } : {};
+function errorIncludesSessionNotFound(err) {
+    if (!(err instanceof Error))
+        return false;
+    const e = err;
+    const combined = [err.message, e.stderr, e.stdout].filter(Boolean).join("\n");
+    return /session not found/i.test(combined);
+}
+async function deleteOpenCodeSession(sessionId) {
+    const validatedSessionId = asValidOpenCodeSessionId(sessionId);
+    if (!validatedSessionId)
+        return;
+    const retryDelaysMs = [0, 200, 600];
+    let lastError;
+    for (const delayMs of retryDelaysMs) {
+        if (delayMs > 0) {
+            await new Promise((resolve) => setTimeout(resolve, delayMs));
+        }
+        try {
+            await execFileAsync("opencode", ["session", "delete", validatedSessionId], {
+                timeout: 30_000,
+                ...EXEC_SHELL_OPTION,
+                env: getOpenCodeChildEnv(),
+            });
+            // Drop cached list immediately so reuse / remap / restore call sites
+            // do not observe the deleted id for the remainder of the TTL window.
+            invalidateOpenCodeSessionListCache();
+            return;
+        }
+        catch (err) {
+            if (errorIncludesSessionNotFound(err)) {
+                invalidateOpenCodeSessionListCache();
+                return;
+            }
+            lastError = err;
+        }
+    }
+    throw lastError instanceof Error ? lastError : new Error(String(lastError));
+}
+async function fetchOpenCodeSessionList(timeoutMs = OPENCODE_DISCOVERY_TIMEOUT_MS) {
+    return getCachedOpenCodeSessionList({ timeoutMs });
+}
+async function discoverOpenCodeSessionIdsByTitle(sessionId, timeoutMs = OPENCODE_DISCOVERY_TIMEOUT_MS, sessionListPromise) {
+    const sessions = await (sessionListPromise ?? fetchOpenCodeSessionList(timeoutMs));
+    const title = `AO:${sessionId}`;
+    return sessions
+        .filter((entry) => entry.title === title)
+        .sort((a, b) => {
+        const ta = a.updatedAt ?? -Infinity;
+        const tb = b.updatedAt ?? -Infinity;
+        if (ta === tb)
+            return 0;
+        return tb - ta;
+    })
+        .map((entry) => entry.id);
+}
+async function discoverOpenCodeSessionIdByTitle(sessionId, timeoutMs, sessionListPromise) {
+    const matches = await discoverOpenCodeSessionIdsByTitle(sessionId, timeoutMs, sessionListPromise);
+    return matches[0];
+}
+/** Escape regex metacharacters in a string. */
+function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/** Get the next session number for a project. */
+function getNextSessionNumber(existingSessions, prefix) {
+    let max = 0;
+    const pattern = new RegExp(`^${escapeRegex(prefix)}-(\\d+)$`);
+    for (const name of existingSessions) {
+        const match = name.match(pattern);
+        if (match) {
+            const num = parseInt(match[1], 10);
+            if (num > max)
+                max = num;
+        }
+    }
+    return max + 1;
+}
+function getSessionNumber(sessionId, prefix) {
+    const match = sessionId.match(new RegExp(`^${escapeRegex(prefix)}-(\\d+)$`));
+    if (!match)
+        return undefined;
+    const parsed = Number.parseInt(match[1], 10);
+    return Number.isNaN(parsed) ? undefined : parsed;
+}
+const PR_TRACKING_STATUSES = new Set([
+    "pr_open",
+    "ci_failed",
+    "review_pending",
+    "changes_requested",
+    "approved",
+    "mergeable",
+]);
+const STALE_PR_OWNERSHIP_STATUSES = new Set([
+    ...PR_TRACKING_STATUSES,
+    "merged",
+]);
+/**
+ * Maximum length for the `displayName` metadata field.
+ * Long enough to express intent ("Refactor session manager to use flat metadata files")
+ * without overflowing kanban cards and tabs in the dashboard.
+ */
+const DISPLAY_NAME_MAX_LENGTH = 80;
+/**
+ * Derive a human-readable display name from any available task context.
+ *
+ * Priority:
+ *   1. Issue title (always the best signal when present)
+ *   2. First meaningful line of a freeform prompt
+ *
+ * The result is trimmed, collapsed to single-line, and truncated to
+ * {@link DISPLAY_NAME_MAX_LENGTH} characters (with an ellipsis).
+ * Returns `undefined` when no usable context exists so callers can skip
+ * writing the field entirely.
+ */
+function deriveDisplayName(input) {
+    const pickLine = (text) => {
+        const line = text
+            .split(/\r?\n/)
+            .map((l) => l.trim())
+            .find((l) => l.length > 0);
+        return line ?? "";
+    };
+    const truncate = (text) => {
+        const collapsed = text.replace(/\s+/g, " ").trim();
+        // Split on code points so emoji / astral characters aren't cleaved into
+        // lone UTF-16 surrogates at the truncation boundary.
+        const codePoints = Array.from(collapsed);
+        if (codePoints.length <= DISPLAY_NAME_MAX_LENGTH)
+            return collapsed;
+        // Leave room for the ellipsis character.
+        return `${codePoints
+            .slice(0, DISPLAY_NAME_MAX_LENGTH - 1)
+            .join("")
+            .trimEnd()}…`;
+    };
+    if (input.issueTitle && input.issueTitle.trim()) {
+        return truncate(input.issueTitle);
+    }
+    if (input.prompt && input.prompt.trim()) {
+        const line = pickLine(input.prompt).replace(/^#{1,6}\s+/, "");
+        if (line)
+            return truncate(line);
+    }
+    return undefined;
+}
+const SEND_RESTORE_READY_TIMEOUT_MS = 5_000;
+const SEND_RESTORE_READY_POLL_MS = 500;
+const SEND_CONFIRMATION_ATTEMPTS = 6;
+const SEND_CONFIRMATION_POLL_MS = 500;
+const SEND_CONFIRMATION_OUTPUT_LINES = 20;
+const SEND_BOOTSTRAP_READY_TIMEOUT_MS = 20_000;
+const SEND_BOOTSTRAP_STABLE_POLLS = 2;
+const ENSURE_ORCHESTRATOR_CONFLICT_WAIT_MS = 20_000;
+const ENSURE_ORCHESTRATOR_CONFLICT_POLL_MS = 250;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function isAgentProcessNotDefinitelyMissing(agent, handle) {
+    try {
+        return (await agent.isProcessRunning(handle)) !== false;
+    }
+    catch {
+        // Send/restore readiness should only block on a definitive "process missing"
+        // verdict. Probe failures are no verdict, so keep waiting or fall back to
+        // terminal output instead of forcing a restore.
+        return true;
+    }
+}
+function isFixedOrchestratorReservationError(err, sessionId) {
+    return err instanceof Error && err.message.includes(`Orchestrator session "${sessionId}" already exists`);
+}
+async function getTmuxForegroundCommand(sessionName) {
+    try {
+        const { stdout } = await execFileAsync("tmux", ["display-message", "-p", "-t", sessionName, "#{pane_current_command}"], { timeout: 5_000, windowsHide: true });
+        const command = stdout.trim();
+        return command.length > 0 ? command : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Parse lifecycle from raw metadata for writeMetadata (restore path). */
+function parseLifecycleFromRaw(raw) {
+    const source = raw["lifecycle"] ?? raw["statePayload"];
+    if (!source)
+        return undefined;
+    try {
+        return JSON.parse(source);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Reconstruct a Session object from raw metadata key=value pairs. */
+function metadataToSession(sessionId, meta, options) {
+    const sessionKind = meta["role"] === "orchestrator" ||
+        (options.sessionPrefix
+            ? new RegExp(`^${escapeRegex(options.sessionPrefix)}-orchestrator-\\d+$`).test(sessionId)
+            : false)
+        ? "orchestrator"
+        : "worker";
+    return sessionFromMetadata(sessionId, meta, {
+        projectId: options.projectId,
+        workspacePathFallback: options.workspacePathFallback,
+        sessionKind,
+        createdAt: options.createdAt,
+        lastActivityAt: options.modifiedAt ?? new Date(),
+    });
+}
+/** Create a SessionManager instance. */
+function createSessionManager(deps) {
+    const { config, registry } = deps;
+    function normalizePath(path) {
+        return resolve(path).replace(/[/\\]$/, "");
+    }
+    function isPathInside(path, parentPath) {
+        const normalizedPath = normalizePath(path);
+        const normalizedParent = normalizePath(parentPath);
+        const sep = process.platform === "win32" ? "\\" : "/";
+        return (normalizedPath === normalizedParent || normalizedPath.startsWith(`${normalizedParent}${sep}`));
+    }
+    function getManagedWorkspaceRoots(projectId, projectPath) {
+        const roots = [getProjectWorktreesDir(projectId)];
+        // Legacy: some worktrees live under ~/.worktrees/{basename}
+        const legacyIds = new Set();
+        legacyIds.add(projectId);
+        legacyIds.add(basename(projectPath));
+        for (const id of legacyIds) {
+            roots.push(join(homedir(), ".worktrees", id));
+        }
+        return roots;
+    }
+    function shouldDestroyWorkspacePath(project, projectId, workspacePath) {
+        if (!project || !projectId)
+            return false;
+        if (normalizePath(workspacePath) === normalizePath(project.path))
+            return false;
+        const roots = getManagedWorkspaceRoots(projectId, project.path);
+        return roots.some((root) => isPathInside(workspacePath, root));
+    }
+    function isOrchestratorSessionRecord(sessionId, raw, sessionPrefix) {
+        if (!raw)
+            return false;
+        if (raw["role"] === "orchestrator")
+            return true;
+        // Check the -orchestrator-N pattern only when the prefix is known so the
+        // regex is anchored to the project prefix, preventing false-positives when
+        // the user-configured sessionPrefix itself ends with "-orchestrator".
+        if (sessionPrefix) {
+            if (sessionId === `${sessionPrefix}-orchestrator`) {
+                return true;
+            }
+            return new RegExp(`^${escapeRegex(sessionPrefix)}-orchestrator-\\d+$`).test(sessionId);
+        }
+        return false;
+    }
+    function isCleanupProtectedSession(project, sessionId, metadata) {
+        if (sessionId === `${project.sessionPrefix}-orchestrator`) {
+            return true;
+        }
+        return isOrchestratorSessionRecord(sessionId, metadata ?? {}, project.sessionPrefix);
+    }
+    function applyMetadataUpdatesToRaw(raw, updates) {
+        let next = { ...raw };
+        for (const [key, value] of Object.entries(updates)) {
+            if (value === undefined)
+                continue;
+            if (value === "") {
+                const { [key]: _removed, ...rest } = next;
+                next = rest;
+                continue;
+            }
+            next[key] = value;
+        }
+        return next;
+    }
+    function buildUpdatedLifecycle(sessionId, raw, updater) {
+        const lifecycle = cloneLifecycle(parseCanonicalLifecycle(raw, {
+            sessionId,
+            status: validateStatus(raw["status"]),
+        }));
+        updater(lifecycle);
+        clearTerminalMarkersForNonTerminalState(lifecycle);
+        return lifecycle;
+    }
+    function lifecycleMetadataUpdates(raw, lifecycle) {
+        return buildLifecycleMetadataPatch(lifecycle);
+    }
+    function updateMetadataPreservingMtime(sessionsDir, sessionName, updates, modifiedAt) {
+        const metaPath = join(sessionsDir, `${sessionName}.json`);
+        let preservedMtime = modifiedAt;
+        if (!preservedMtime) {
+            try {
+                preservedMtime = statSync(metaPath).mtime;
+            }
+            catch {
+                preservedMtime = undefined;
+            }
+        }
+        updateMetadata(sessionsDir, sessionName, updates);
+        if (!preservedMtime)
+            return;
+        try {
+            utimesSync(metaPath, preservedMtime, preservedMtime);
+        }
+        catch {
+        }
+    }
+    const SESSION_CACHE_TTL_MS = 35_000;
+    let sessionCache = null;
+    const ensureOrchestratorPromises = new Map();
+    const relaunchOrchestratorPromises = new Map();
+    function invalidateCache() {
+        sessionCache = null;
+    }
+    function deduplicatePRStorageOnStartup() {
+        let migrated = false;
+        for (const [projectId] of Object.entries(config.projects)) {
+            const sessionsDir = getProjectSessionsDir(projectId);
+            if (!existsSync(sessionsDir))
+                continue;
+            for (const sessionName of listMetadata(sessionsDir)) {
+                const raw = readMetadataRaw(sessionsDir, sessionName);
+                if (!raw)
+                    continue;
+                const rawPrUrls = raw["prs"]
+                    ? raw["prs"].split(",").map((url) => url.trim()).filter(Boolean)
+                    : [];
+                const uniquePrUrls = dedupePrUrls(rawPrUrls);
+                const updates = {};
+                if (rawPrUrls.length !== uniquePrUrls.length) {
+                    updates["prs"] = uniquePrUrls.join(",");
+                }
+                let deletedIndexedKeyCount = 0;
+                for (const key of Object.keys(raw)) {
+                    if (!INDEXED_PR_METADATA_KEY_REGEX.test(key))
+                        continue;
+                    updates[key] = "";
+                    deletedIndexedKeyCount += 1;
+                }
+                if (Object.keys(updates).length === 0)
+                    continue;
+                updateMetadata(sessionsDir, sessionName, updates);
+                migrated = true;
+                recordActivityEvent({
+                    projectId,
+                    sessionId: sessionName,
+                    source: "session-manager",
+                    kind: "metadata.deduplicated",
+                    summary: `deduplicated PR metadata: ${sessionName}`,
+                    data: {
+                        beforePrCount: rawPrUrls.length,
+                        afterPrCount: uniquePrUrls.length,
+                        deletedIndexedKeyCount,
+                    },
+                });
+            }
+        }
+        if (migrated)
+            invalidateCache();
+    }
+    deduplicatePRStorageOnStartup();
+    function repairSessionAgentMetadataOnRead(sessionsDir, record, project) {
+        if (record.raw["agent"])
+            return record;
+        const agent = resolveSelectionForSession(project, record.sessionName, record.raw).agentName;
+        updateMetadataPreservingMtime(sessionsDir, record.sessionName, { agent }, record.modifiedAt);
+        return {
+            ...record,
+            raw: applyMetadataUpdatesToRaw(record.raw, { agent }),
+        };
+    }
+    function repairSingleSessionMetadataOnRead(sessionsDir, record, sessionPrefix) {
+        const repaired = { ...record, raw: { ...record.raw } };
+        if (!isOrchestratorSessionRecord(repaired.sessionName, repaired.raw, sessionPrefix)) {
+            return repaired;
+        }
+        const updates = {};
+        if (repaired.raw["role"] !== "orchestrator") {
+            updates["role"] = "orchestrator";
+        }
+        if (repaired.raw["pr"]) {
+            updates["pr"] = "";
+        }
+        if (repaired.raw["prAutoDetect"] !== "off" && repaired.raw["prAutoDetect"] !== "false") {
+            updates["prAutoDetect"] = "false";
+        }
+        if (STALE_PR_OWNERSHIP_STATUSES.has(repaired.raw["status"] ?? "")) {
+            updates["status"] = "working";
+        }
+        if (Object.keys(updates).length > 0) {
+            const lifecycle = buildUpdatedLifecycle(repaired.sessionName, repaired.raw, (next) => {
+                next.session.kind = "orchestrator";
+                next.pr.state = "none";
+                next.pr.reason = "not_created";
+                next.pr.number = null;
+                next.pr.url = null;
+                next.pr.lastObservedAt = null;
+                if (updates["status"] === "working") {
+                    next.session.state = "working";
+                    next.session.reason = "task_in_progress";
+                }
+            });
+            updateMetadataPreservingMtime(sessionsDir, repaired.sessionName, { ...updates, ...lifecycleMetadataUpdates(repaired.raw, lifecycle) }, repaired.modifiedAt);
+            repaired.raw = applyMetadataUpdatesToRaw(repaired.raw, {
+                ...updates,
+                ...lifecycleMetadataUpdates(repaired.raw, lifecycle),
+            });
+        }
+        return repaired;
+    }
+    function sessionMetadataTimestamp(record) {
+        const metadataTimestamp = Date.parse(record.raw["restoredAt"] ?? record.raw["createdAt"] ?? "");
+        if (record.modifiedAt)
+            return record.modifiedAt.getTime();
+        return Number.isNaN(metadataTimestamp) ? 0 : metadataTimestamp;
+    }
+    function repairSessionMetadataOnRead(sessionsDir, records, project) {
+        const repaired = records.map((record) => ({ ...record, raw: { ...record.raw } }));
+        const duplicatePRAttachments = new Map();
+        for (const record of repaired) {
+            if (!record.raw["lifecycle"] && (!record.raw["statePayload"] || record.raw["stateVersion"] !== "2")) {
+                const lifecycle = cloneLifecycle(parseCanonicalLifecycle(record.raw, {
+                    sessionId: record.sessionName,
+                    status: validateStatus(record.raw["status"]),
+                    createdAt: record.raw["createdAt"] ? new Date(record.raw["createdAt"]) : undefined,
+                    sessionKind: isOrchestratorSessionRecord(record.sessionName, record.raw, project.sessionPrefix)
+                        ? "orchestrator"
+                        : "worker",
+                }));
+                const canonicalUpdates = lifecycleMetadataUpdates(record.raw, lifecycle);
+                updateMetadataPreservingMtime(sessionsDir, record.sessionName, canonicalUpdates, record.modifiedAt);
+                record.raw = applyMetadataUpdatesToRaw(record.raw, canonicalUpdates);
+            }
+            if (isOrchestratorSessionRecord(record.sessionName, record.raw, project.sessionPrefix)) {
+                record.raw = repairSingleSessionMetadataOnRead(sessionsDir, record, project.sessionPrefix).raw;
+                record.raw = repairSessionAgentMetadataOnRead(sessionsDir, record, project).raw;
+                continue;
+            }
+            record.raw = repairSessionAgentMetadataOnRead(sessionsDir, record, project).raw;
+            const prUrl = record.raw["pr"];
+            if (!prUrl)
+                continue;
+            const attached = duplicatePRAttachments.get(prUrl) ?? [];
+            attached.push(record);
+            duplicatePRAttachments.set(prUrl, attached);
+        }
+        for (const attachedRecords of duplicatePRAttachments.values()) {
+            if (attachedRecords.length < 2)
+                continue;
+            const [owner, ...staleRecords] = [...attachedRecords].sort((a, b) => {
+                const trackingDiff = Number(PR_TRACKING_STATUSES.has(b.raw["status"] ?? "")) -
+                    Number(PR_TRACKING_STATUSES.has(a.raw["status"] ?? ""));
+                if (trackingDiff !== 0)
+                    return trackingDiff;
+                const timestampDiff = sessionMetadataTimestamp(b) - sessionMetadataTimestamp(a);
+                if (timestampDiff !== 0)
+                    return timestampDiff;
+                return b.sessionName.localeCompare(a.sessionName);
+            });
+            for (const record of staleRecords) {
+                const updates = {
+                    pr: "",
+                    prAutoDetect: "false",
+                    ...(PR_TRACKING_STATUSES.has(record.raw["status"] ?? "") ? { status: "working" } : {}),
+                };
+                const lifecycle = buildUpdatedLifecycle(record.sessionName, record.raw, (next) => {
+                    next.pr.state = "none";
+                    next.pr.reason = "not_created";
+                    next.pr.number = null;
+                    next.pr.url = null;
+                    next.pr.lastObservedAt = null;
+                    if (updates["status"] === "working") {
+                        next.session.state = "working";
+                        next.session.reason = "task_in_progress";
+                    }
+                });
+                const lifecycleUpdates = lifecycleMetadataUpdates(record.raw, lifecycle);
+                updateMetadataPreservingMtime(sessionsDir, record.sessionName, { ...updates, ...lifecycleUpdates }, record.modifiedAt);
+                record.raw = applyMetadataUpdatesToRaw(record.raw, { ...updates, ...lifecycleUpdates });
+            }
+        }
+        return repaired;
+    }
+    function loadActiveSessionRecords(projectId, project) {
+        const sessionsDir = getProjectSessionsDir(projectId);
+        if (!existsSync(sessionsDir))
+            return [];
+        const records = listMetadata(sessionsDir).flatMap((sessionName) => {
+            const raw = readMetadataRaw(sessionsDir, sessionName);
+            if (!raw)
+                return [];
+            let modifiedAt;
+            try {
+                modifiedAt = statSync(join(sessionsDir, `${sessionName}.json`)).mtime;
+            }
+            catch {
+            }
+            return [{ sessionName, raw, modifiedAt }];
+        });
+        return repairSessionMetadataOnRead(sessionsDir, records, project);
+    }
+    function sortSessionIdsForReuse(ids) {
+        const numericSuffix = (id) => {
+            const match = id.match(/-(\d+)$/);
+            if (!match)
+                return undefined;
+            const parsed = Number.parseInt(match[1], 10);
+            return Number.isNaN(parsed) ? undefined : parsed;
+        };
+        return [...ids].sort((a, b) => {
+            const aNum = numericSuffix(a);
+            const bNum = numericSuffix(b);
+            if (aNum !== undefined && bNum !== undefined && aNum !== bNum) {
+                return bNum - aNum;
+            }
+            if (aNum !== undefined && bNum === undefined)
+                return -1;
+            if (aNum === undefined && bNum !== undefined)
+                return 1;
+            return b.localeCompare(a);
+        });
+    }
+    function findOpenCodeSessionIds(sessionsDir, criteria) {
+        const matchesCriteria = (id, raw) => {
+            if (!raw)
+                return false;
+            if (raw["agent"] !== "opencode")
+                return false;
+            if (criteria.issueId !== undefined && raw["issue"] !== criteria.issueId)
+                return false;
+            if (criteria.sessionId !== undefined && id !== criteria.sessionId)
+                return false;
+            return true;
+        };
+        const ids = [];
+        const maybeAdd = (id, raw) => {
+            if (!matchesCriteria(id, raw))
+                return;
+            const mapped = asValidOpenCodeSessionId(raw?.["opencodeSessionId"]);
+            if (!mapped)
+                return;
+            ids.push(mapped);
+        };
+        for (const id of sortSessionIdsForReuse(listMetadata(sessionsDir))) {
+            maybeAdd(id, readMetadataRaw(sessionsDir, id));
+        }
+        return [...new Set(ids)];
+    }
+    async function resolveOpenCodeSessionReuse(options) {
+        const { sessionsDir, criteria, strategy, includeTitleDiscoveryForSessionId = false } = options;
+        if (strategy === "ignore")
+            return undefined;
+        let candidateIds = findOpenCodeSessionIds(sessionsDir, criteria);
+        if (strategy === "delete") {
+            if (includeTitleDiscoveryForSessionId && criteria.sessionId) {
+                candidateIds = [
+                    ...candidateIds,
+                    ...(await discoverOpenCodeSessionIdsByTitle(criteria.sessionId)),
+                ];
+            }
+            for (const openCodeSessionId of [...new Set(candidateIds)]) {
+                await deleteOpenCodeSession(openCodeSessionId);
+            }
+            return undefined;
+        }
+        if (candidateIds.length === 0 && criteria.sessionId) {
+            candidateIds = await discoverOpenCodeSessionIdsByTitle(criteria.sessionId);
+        }
+        return candidateIds[0];
+    }
+    async function listRemoteSessionNumbers(project) {
+        try {
+            const { stdout } = await execFileAsync("git", ["ls-remote", "--heads", "origin", `session/${project.sessionPrefix}-*`], {
+                cwd: project.path,
+                timeout: 5_000,
+                ...EXEC_SHELL_OPTION,
+            });
+            return stdout
+                .split("\n")
+                .flatMap((line) => {
+                const trimmed = line.trim();
+                if (!trimmed)
+                    return [];
+                const ref = trimmed.split(/\s+/)[1] ?? "";
+                const match = ref.match(new RegExp(`refs/heads/session/${escapeRegex(project.sessionPrefix)}-(\\d+)$`));
+                if (!match)
+                    return [];
+                const parsed = Number.parseInt(match[1], 10);
+                return Number.isNaN(parsed) ? [] : [parsed];
+            })
+                .filter((num, index, values) => values.indexOf(num) === index);
+        }
+        catch {
+            return [];
+        }
+    }
+    async function reserveNextSessionIdentity(project, sessionsDir) {
+        const usedNumbers = new Set();
+        for (const sessionName of listMetadata(sessionsDir)) {
+            const num = getSessionNumber(sessionName, project.sessionPrefix);
+            if (num !== undefined)
+                usedNumbers.add(num);
+        }
+        for (const num of await listRemoteSessionNumbers(project)) {
+            usedNumbers.add(num);
+        }
+        let num = getNextSessionNumber([...usedNumbers].map((value) => `${project.sessionPrefix}-${value}`), project.sessionPrefix);
+        for (let attempts = 0; attempts < 10_000; attempts++) {
+            const sessionId = `${project.sessionPrefix}-${num}`;
+            const tmuxName = project.path
+                ? generateSessionName(project.sessionPrefix, num)
+                : undefined;
+            if (!usedNumbers.has(num) && reserveSessionId(sessionsDir, sessionId)) {
+                return { num, sessionId, tmuxName };
+            }
+            usedNumbers.add(num);
+            num += 1;
+        }
+        throw new Error(`Failed to reserve session ID after 10000 attempts (prefix: ${project.sessionPrefix})`);
+    }
+    function reserveFixedOrchestratorIdentity(project, sessionsDir) {
+        const sessionId = getOrchestratorSessionId(project);
+        if (!reserveSessionId(sessionsDir, sessionId)) {
+            throw new Error(`Orchestrator session "${sessionId}" already exists. Use ensureOrchestrator() to reuse or restore it.`);
+        }
+        return {
+            sessionId,
+            tmuxName: config.configPath ? sessionId : undefined,
+        };
+    }
+    /** Resolve which plugins to use for a project. */
+    function resolvePlugins(project, agentName) {
+        const runtime = registry.get("runtime", project.runtime ?? config.defaults.runtime);
+        const agent = registry.get("agent", agentName ?? project.agent ?? config.defaults.agent);
+        const workspace = registry.get("workspace", project.workspace ?? config.defaults.workspace);
+        // After config validation, plugin is always set if tracker/scm exists
+        // (either from user config or auto-generated from package/path)
+        const tracker = project.tracker?.plugin
+            ? registry.get("tracker", project.tracker.plugin)
+            : null;
+        const scm = project.scm?.plugin ? registry.get("scm", project.scm.plugin) : null;
+        return { runtime, agent, workspace, tracker, scm };
+    }
+    function resolveSelectionForSession(project, sessionId, metadata) {
+        return resolveAgentSelectionForSession({
+            sessionId,
+            metadata,
+            project,
+            defaults: config.defaults,
+            allSessionPrefixes: Object.values(config.projects).map((p) => p.sessionPrefix),
+        });
+    }
+    async function ensureOpenCodeSessionMapping(session, sessionName, sessionsDir, effectiveAgentName, sessionListPromise) {
+        if (effectiveAgentName !== "opencode")
+            return;
+        if (asValidOpenCodeSessionId(session.metadata["opencodeSessionId"]))
+            return;
+        const discovered = await discoverOpenCodeSessionIdByTitle(sessionName, OPENCODE_DISCOVERY_TIMEOUT_MS, sessionListPromise);
+        if (!discovered)
+            return;
+        session.metadata["opencodeSessionId"] = discovered;
+        updateMetadata(sessionsDir, sessionName, { opencodeSessionId: discovered });
+    }
+    function findSessionRecord(sessionId) {
+        for (const [projectId, project] of Object.entries(config.projects)) {
+            const sessionsDir = getProjectSessionsDir(projectId);
+            const raw = readMetadataRaw(sessionsDir, sessionId);
+            if (!raw)
+                continue;
+            let modifiedAt;
+            try {
+                modifiedAt = statSync(join(sessionsDir, `${sessionId}.json`)).mtime;
+            }
+            catch {
+                modifiedAt = undefined;
+            }
+            const repaired = repairSessionAgentMetadataOnRead(sessionsDir, repairSingleSessionMetadataOnRead(sessionsDir, { sessionName: sessionId, raw, modifiedAt }, project.sessionPrefix), project);
+            return { raw: repaired.raw, sessionsDir, project, projectId };
+        }
+        return null;
+    }
+    function requireSessionRecord(sessionId) {
+        const located = findSessionRecord(sessionId);
+        if (!located) {
+            throw new SessionNotFoundError(sessionId);
+        }
+        return located;
+    }
+    /**
+     * Ensure session has a runtime handle (fabricate one if missing) and enrich
+     * with live runtime state + activity detection. Used by both list() and get().
+     */
+    async function ensureHandleAndEnrich(session, sessionName, sessionsDir, project, effectiveAgentName, plugins, sessionListPromise) {
+        await ensureOpenCodeSessionMapping(session, sessionName, sessionsDir, effectiveAgentName, sessionListPromise);
+        const tmuxNameFromMetadata = session.metadata["tmuxName"]?.trim();
+        const hasTmuxNameFromMetadata = typeof tmuxNameFromMetadata === "string" && tmuxNameFromMetadata.length > 0;
+        const handleFromMetadata = session.runtimeHandle !== null || hasTmuxNameFromMetadata;
+        if (!handleFromMetadata) {
+            session.runtimeHandle = {
+                id: sessionName,
+                runtimeName: project.runtime ?? config.defaults.runtime,
+                data: {},
+            };
+        }
+        else if (!session.runtimeHandle && hasTmuxNameFromMetadata) {
+            session.runtimeHandle = {
+                id: tmuxNameFromMetadata,
+                runtimeName: project.runtime ?? config.defaults.runtime,
+                data: {},
+            };
+        }
+        await enrichSessionWithRuntimeState(session, plugins, handleFromMetadata, sessionsDir);
+    }
+    /**
+     * Enrich session with live runtime state (alive/exited) and activity detection.
+     * Mutates the session object in place.
+     */
+    const TERMINAL_SESSION_STATUSES = new Set(["killed", "done", "merged", "terminated", "cleanup"]);
+    function hasPersistedNativeRestoreMetadata(session, agent) {
+        const metadata = session.metadata ?? {};
+        switch (agent.name) {
+            case "claude-code":
+                return typeof metadata["claudeSessionUuid"] === "string" && metadata["claudeSessionUuid"].trim().length > 0;
+            case "codex":
+                return typeof metadata["codexThreadId"] === "string" && metadata["codexThreadId"].trim().length > 0;
+            case "opencode":
+                return asValidOpenCodeSessionId(metadata["opencodeSessionId"]) !== null;
+            default:
+                return false;
+        }
+    }
+    function canDiscoverSessionInfoAfterRuntimeExit(agent) {
+        return agent.name === "claude-code" || agent.name === "codex";
+    }
+    async function enrichSessionWithRuntimeState(session, plugins, handleFromMetadata, sessionsDir) {
+        async function persistAgentSessionInfo(options) {
+            if (!plugins.agent)
+                return;
+            if (options?.skipIfNativeRestoreMetadataPresent &&
+                hasPersistedNativeRestoreMetadata(session, plugins.agent)) {
+                return;
+            }
+            let info;
+            try {
+                info = await plugins.agent.getSessionInfo(session);
+            }
+            catch {
+                // Can't get session info — keep existing values
+                info = null;
+            }
+            if (!info)
+                return;
+            session.agentInfo = info;
+            const metadataUpdates = info.metadata ?? {};
+            const allAlreadyPersisted = Object.keys(metadataUpdates).every((key) => session.metadata?.[key] === metadataUpdates[key]);
+            if (allAlreadyPersisted)
+                return;
+            if (Object.keys(metadataUpdates).length > 0) {
+                try {
+                    updateMetadata(sessionsDir, session.id, metadataUpdates);
+                    session.metadata = applyMetadataUpdates(session.metadata, metadataUpdates);
+                    invalidateCache();
+                }
+                catch {
+                    // Persisting agent metadata is best-effort; keep live agent info.
+                }
+            }
+        }
+        // Check runtime liveness first — for all statuses except "spawning".
+        // Skip spawning sessions because tmux may not be fully initialized yet,
+        // and a false-negative from isAlive() would permanently mark the session
+        // as "killed" (see #1035).
+        // This also fixes #1081: terminal statuses (merged, done, etc.) should not
+        // force activity to "exited" if the agent process is still alive.
+        // Fabricated handles (constructed as fallback for external sessions) should
+        // NOT override status to "killed" — we don't know if the session ever had
+        // a tmux session, and we'd clobber meaningful statuses like "pr_open".
+        if (handleFromMetadata &&
+            session.runtimeHandle &&
+            plugins.runtime &&
+            session.status !== "spawning") {
+            try {
+                const alive = await plugins.runtime.isAlive(session.runtimeHandle);
+                if (!alive) {
+                    session.lifecycle.runtime.state = "missing";
+                    session.lifecycle.runtime.reason =
+                        session.runtimeHandle.runtimeName === "tmux" ? "tmux_missing" : "process_missing";
+                    session.lifecycle.runtime.lastObservedAt = new Date().toISOString();
+                    if (session.lifecycle.session.state !== "done" &&
+                        session.lifecycle.session.state !== "terminated") {
+                        session.lifecycle.session.state = "detecting";
+                        session.lifecycle.session.reason = "runtime_lost";
+                        session.lifecycle.session.lastTransitionAt = new Date().toISOString();
+                    }
+                    // Process is confirmed dead — set activity to exited.
+                    // Only update status to "killed" if not already in a terminal state.
+                    if (!TERMINAL_SESSION_STATUSES.has(session.status)) {
+                        session.status = "killed";
+                    }
+                    session.activity = "exited";
+                    session.activitySignal = createActivitySignal("valid", {
+                        activity: "exited",
+                        source: "runtime",
+                    });
+                    // Dead-runtime session info discovery is intentionally limited to
+                    // agents that recover restore metadata from persisted local files.
+                    if (plugins.agent && canDiscoverSessionInfoAfterRuntimeExit(plugins.agent)) {
+                        await persistAgentSessionInfo({ skipIfNativeRestoreMetadataPresent: true });
+                    }
+                    return;
+                }
+            }
+            catch {
+                // Can't check liveness — continue to activity detection
+                session.lifecycle.runtime.state = "probe_failed";
+                session.lifecycle.runtime.reason = "probe_error";
+                session.lifecycle.runtime.lastObservedAt = new Date().toISOString();
+            }
+        }
+        // Detect activity independently of runtime handle and session status.
+        // Activity detection reads JSONL files on disk — it only needs workspacePath,
+        // not a runtime handle. Gating on runtimeHandle caused sessions created by
+        // external scripts (which don't store runtimeHandle) to always show "unknown".
+        // This now runs for ALL sessions, including terminal statuses, so a merged
+        // session with a live agent shows accurate activity (ready/idle/waiting_input).
+        session.activitySignal = createActivitySignal("unavailable");
+        if (plugins.agent) {
+            try {
+                const detected = await plugins.agent.getActivityState(session, config.readyThresholdMs);
+                if (detected !== null) {
+                    session.activitySignal = classifyActivitySignal(detected, "native");
+                    session.activity = detected.state;
+                    session.lifecycle.runtime.state = "alive";
+                    session.lifecycle.runtime.reason = "process_running";
+                    session.lifecycle.runtime.lastObservedAt = new Date().toISOString();
+                    if (detected.timestamp && detected.timestamp > session.lastActivityAt) {
+                        session.lastActivityAt = detected.timestamp;
+                    }
+                }
+                else {
+                    session.activitySignal = createActivitySignal("null", { source: "native" });
+                }
+            }
+            catch {
+                session.activitySignal = createActivitySignal("probe_failure", { source: "native" });
+            }
+            // Enrich with agent session info (summary, cost, native restore metadata).
+            await persistAgentSessionInfo();
+        }
+    }
+    // Define methods as local functions so `this` is not needed
+    async function spawn(spawnConfig) {
+        recordActivityEvent({
+            projectId: spawnConfig.projectId,
+            source: "session-manager",
+            kind: "session.spawn_started",
+            summary: "spawn started",
+            data: { agent: spawnConfig.agent ?? undefined },
+        });
+        try {
+            return await _spawnInner(spawnConfig);
+        }
+        catch (err) {
+            recordActivityEvent({
+                projectId: spawnConfig.projectId,
+                source: "session-manager",
+                kind: "session.spawn_failed",
+                level: "error",
+                summary: `spawn failed`,
+                data: { reason: err instanceof Error ? err.message : String(err) },
+            });
+            throw err;
+        }
+    }
+    async function _spawnInner(spawnConfig) {
+        const project = config.projects[spawnConfig.projectId];
+        if (!project) {
+            throw new Error(`Unknown project: ${spawnConfig.projectId}`);
+        }
+        const selection = resolveAgentSelection({
+            role: "worker",
+            project,
+            defaults: config.defaults,
+            spawnAgentOverride: spawnConfig.agent,
+        });
+        const plugins = resolvePlugins(project, selection.agentName);
+        if (!plugins.runtime) {
+            throw new Error(`Runtime plugin '${project.runtime ?? config.defaults.runtime}' not found`);
+        }
+        if (!plugins.agent) {
+            throw new Error(`Agent plugin '${selection.agentName}' not found`);
+        }
+        // Validate issue exists BEFORE creating any resources
+        let resolvedIssue;
+        if (spawnConfig.issueId && plugins.tracker) {
+            try {
+                // Fetch and validate the issue exists
+                resolvedIssue = await plugins.tracker.getIssue(spawnConfig.issueId, project);
+            }
+            catch (err) {
+                // Issue fetch failed - determine why
+                if (isIssueNotFoundError(err)) ;
+                else {
+                    // Other error (auth, network, etc) - fail fast
+                    recordActivityEvent({
+                        projectId: spawnConfig.projectId,
+                        source: "session-manager",
+                        kind: "tracker.issue_fetch_failed",
+                        level: "error",
+                        summary: `tracker getIssue failed for ${spawnConfig.issueId}`,
+                        data: {
+                            issueId: spawnConfig.issueId,
+                            tracker: plugins.tracker.name,
+                            reason: err instanceof Error ? err.message : String(err),
+                        },
+                    });
+                    throw new Error(`Failed to fetch issue ${spawnConfig.issueId}: ${err}`, { cause: err });
+                }
+            }
+        }
+        // Get the sessions directory for this project
+        const sessionsDir = getProjectSessionsDir(spawnConfig.projectId);
+        // CleanupStack: each side effect pushes its undo as soon as the resource
+        // exists. On any failure below we runAll() in LIFO order; on success we
+        // dismiss(). Replaces the previous nested rollback ladder — adding a new
+        // step now requires pushing one cleanup, with no risk of forgetting prior
+        // ones.
+        const cleanupStack = new CleanupStack();
+        let sessionId;
+        try {
+            // Determine session ID — atomically reserve to prevent concurrent collisions
+            let tmuxName;
+            ({ sessionId, tmuxName } = await reserveNextSessionIdentity(project, sessionsDir));
+            const reservedSessionId = sessionId;
+            cleanupStack.push(() => deleteMetadata(sessionsDir, reservedSessionId));
+            // Determine branch name — explicit branch always takes priority
+            let branch;
+            if (spawnConfig.branch) {
+                branch = spawnConfig.branch;
+            }
+            else if (spawnConfig.issueId && plugins.tracker && resolvedIssue) {
+                const fromIssue = resolvedIssue.branchName;
+                branch =
+                    fromIssue && isGitBranchNameSafe(fromIssue)
+                        ? fromIssue
+                        : plugins.tracker.branchName(spawnConfig.issueId, project);
+            }
+            else if (spawnConfig.issueId) {
+                // If the issueId is already branch-safe (e.g. "INT-9999"), use as-is.
+                // Otherwise sanitize free-text (e.g. "fix login bug") into a valid slug.
+                const id = spawnConfig.issueId;
+                const isBranchSafe = /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(id) && !id.includes("..");
+                const slug = isBranchSafe
+                    ? id
+                    : id
+                        .toLowerCase()
+                        .replace(/[^a-z0-9]+/g, "-")
+                        .slice(0, 60)
+                        .replace(/^-+|-+$/g, "");
+                branch = `feat/${slug || sessionId}`;
+            }
+            else {
+                branch = `session/${sessionId}`;
+            }
+            // Create workspace (if workspace plugin is available)
+            let workspacePath = project.path;
+            if (plugins.workspace) {
+                const wsInfo = await plugins.workspace.create({
+                    projectId: spawnConfig.projectId,
+                    project,
+                    sessionId,
+                    branch,
+                    worktreeDir: getProjectWorktreesDir(spawnConfig.projectId),
+                });
+                workspacePath = wsInfo.path;
+                // Only register destroy when the path is inside a managed root —
+                // matches the prior shouldDestroyWorkspacePath gate so we never
+                // destroy a user-owned project directory.
+                if (shouldDestroyWorkspacePath(project, spawnConfig.projectId, workspacePath)) {
+                    const ws = plugins.workspace;
+                    cleanupStack.push(() => ws.destroy(workspacePath));
+                }
+                if (plugins.workspace.postCreate) {
+                    await plugins.workspace.postCreate(wsInfo, project);
+                }
+            }
+            // Generate prompt with validated issue
+            let issueContext;
+            if (spawnConfig.issueId && plugins.tracker && resolvedIssue) {
+                try {
+                    issueContext = await plugins.tracker.generatePrompt(spawnConfig.issueId, project);
+                }
+                catch (err) {
+                    // Non-fatal: continue without detailed issue context. Surface the
+                    // failure via AE so RCA can answer "did the agent get an enriched
+                    // prompt or just the bare issue ID?"
+                    recordActivityEvent({
+                        projectId: spawnConfig.projectId,
+                        sessionId,
+                        source: "session-manager",
+                        kind: "tracker.generate_prompt_failed",
+                        level: "warn",
+                        summary: `tracker generatePrompt failed for ${spawnConfig.issueId}`,
+                        data: {
+                            issueId: spawnConfig.issueId,
+                            tracker: plugins.tracker.name,
+                            reason: err instanceof Error ? err.message : String(err),
+                        },
+                    });
+                }
+            }
+            // If an orchestrator session exists on disk for this project, give the
+            // worker the literal command to message it. Existence-on-disk is the
+            // signal: if metadata was ever written for the canonical orchestrator
+            // ID, the orchestrator workflow is in play here.
+            const orchestratorSessionId = `${project.sessionPrefix}-orchestrator`;
+            const orchestratorExists = readMetadataRaw(sessionsDir, orchestratorSessionId) !== null;
+            const { systemPrompt, taskPrompt } = buildPrompt({
+                project,
+                projectId: spawnConfig.projectId,
+                issueId: spawnConfig.issueId,
+                issueContext,
+                userPrompt: spawnConfig.prompt,
+                ...(orchestratorExists && { orchestratorSessionId }),
+            });
+            const baseDir = getProjectDir(spawnConfig.projectId);
+            mkdirSync(baseDir, { recursive: true });
+            const systemPromptFile = join(baseDir, `worker-prompt-${sessionId}.md`);
+            writeFileSync(systemPromptFile, systemPrompt, "utf-8");
+            cleanupStack.push(() => unlinkSync(systemPromptFile));
+            // need a seperate config file to pass instructions for opencode session
+            let opencodeConfigFile;
+            if (plugins.agent.name === "opencode") {
+                opencodeConfigFile = writeOpenCodeConfig(baseDir, sessionId, [systemPromptFile]);
+                const cfg = opencodeConfigFile;
+                cleanupStack.push(() => unlinkSync(cfg));
+            }
+            // Get agent launch config and create runtime
+            const opencodeIssueSessionStrategy = project.opencodeIssueSessionStrategy ?? "reuse";
+            const reusedOpenCodeSessionId = plugins.agent.name === "opencode" && spawnConfig.issueId
+                ? await resolveOpenCodeSessionReuse({
+                    sessionsDir,
+                    criteria: { issueId: spawnConfig.issueId },
+                    strategy: opencodeIssueSessionStrategy,
+                })
+                : undefined;
+            const agentLaunchConfig = {
+                sessionId,
+                projectConfig: {
+                    ...project,
+                    agentConfig: {
+                        ...selection.agentConfig,
+                        ...(reusedOpenCodeSessionId ? { opencodeSessionId: reusedOpenCodeSessionId } : {}),
+                    },
+                },
+                workspacePath,
+                issueId: spawnConfig.issueId,
+                prompt: taskPrompt,
+                systemPromptFile,
+                permissions: selection.permissions,
+                model: selection.model,
+                subagent: spawnConfig.subagent ?? selection.subagent,
+            };
+            const launchCommand = plugins.agent.getLaunchCommand(agentLaunchConfig);
+            const environment = plugins.agent.getEnvironment(agentLaunchConfig);
+            if (plugins.agent.preLaunchSetup) {
+                await plugins.agent.preLaunchSetup(workspacePath);
+            }
+            // Install workspace hooks before launching the agent so that
+            // PostToolUse hooks (e.g. Claude Code's metadata-updater) are
+            // in place before the agent's first tool call.
+            if (plugins.agent.setupWorkspaceHooks) {
+                await plugins.agent.setupWorkspaceHooks(workspacePath, { dataDir: sessionsDir });
+            }
+            if (plugins.agent.name !== "claude-code") {
+                await setupPathWrapperWorkspace(workspacePath);
+            }
+            const handle = await plugins.runtime.create({
+                sessionId: tmuxName ?? sessionId, // Use tmux name for runtime if available
+                workspacePath,
+                launchCommand,
+                environment: {
+                    ...environment,
+                    ...(opencodeConfigFile ? { OPENCODE_CONFIG: opencodeConfigFile } : {}),
+                    ...(project.env ?? {}),
+                    PATH: buildAgentPath(environment["PATH"] ?? process.env["PATH"]),
+                    GH_PATH: PREFERRED_GH_PATH,
+                    ...(process.env["AO_AGENT_GH_TRACE"] && {
+                        AO_AGENT_GH_TRACE: process.env["AO_AGENT_GH_TRACE"],
+                    }),
+                    AO_SESSION: sessionId,
+                    AO_DATA_DIR: sessionsDir, // Pass sessions directory (not root dataDir)
+                    AO_SESSION_NAME: sessionId, // User-facing session name
+                    ...(tmuxName && { AO_TMUX_NAME: tmuxName }), // Tmux session name if using new arch
+                    AO_CALLER_TYPE: "agent",
+                    AO_PROJECT_ID: spawnConfig.projectId,
+                    AO_CONFIG_PATH: config.configPath,
+                    ...(config.port !== undefined &&
+                        config.port !== null && { AO_PORT: String(config.port) }),
+                },
+            });
+            const rt = plugins.runtime;
+            cleanupStack.push(() => rt.destroy(handle));
+            // Derive a stable display name from task context. Unlike issue-title
+            // enrichment (which is a live tracker API call), this value is captured at
+            // spawn time and persisted, so the dashboard has a good name even when the
+            // tracker is unavailable or the session has no attached PR yet.
+            const displayName = deriveDisplayName({
+                issueTitle: resolvedIssue?.title,
+                prompt: spawnConfig.prompt,
+            });
+            // Write metadata and run post-launch setup
+            const createdAt = new Date();
+            const lifecycle = createInitialCanonicalLifecycle("worker", createdAt);
+            lifecycle.runtime.handle = handle;
+            lifecycle.runtime.tmuxName = tmuxName ?? null;
+            const session = {
+                id: sessionId,
+                projectId: spawnConfig.projectId,
+                status: deriveLegacyStatus(lifecycle),
+                activity: "active",
+                activitySignal: createActivitySignal("valid", {
+                    activity: "active",
+                    timestamp: createdAt,
+                    source: "runtime",
+                }),
+                lifecycle,
+                branch,
+                issueId: spawnConfig.issueId ?? null,
+                pr: null,
+                prs: [],
+                workspacePath,
+                runtimeHandle: handle,
+                agentInfo: null,
+                createdAt,
+                lastActivityAt: createdAt,
+                metadata: {
+                    ...(reusedOpenCodeSessionId ? { opencodeSessionId: reusedOpenCodeSessionId } : {}),
+                    ...(spawnConfig.prompt ? { userPrompt: spawnConfig.prompt } : {}),
+                    ...(displayName ? { displayName } : {}),
+                },
+            };
+            writeMetadata(sessionsDir, sessionId, {
+                worktree: workspacePath,
+                branch,
+                status: deriveLegacyStatus(lifecycle),
+                ...buildLifecycleMetadataPatch(lifecycle),
+                // Override stringified lifecycle/runtimeHandle from the patch
+                // with their canonical object forms. `buildLifecycleMetadataPatch`
+                // produces `Partial<Record<string, string>>` for the
+                // updateMetadata/mutateMetadata path; spreading it directly into
+                // a typed `SessionMetadata` literal silently widens the
+                // `lifecycle`/`runtimeHandle` fields to strings, which then get
+                // re-encoded by `JSON.stringify` and rejected by
+                // `parseLifecycleField` on the next read.
+                lifecycle,
+                tmuxName, // Store tmux name for mapping
+                issue: spawnConfig.issueId,
+                issueTitle: resolvedIssue?.title, // Store issue title for event enrichment
+                project: spawnConfig.projectId,
+                agent: selection.agentName, // Persist agent name for lifecycle manager
+                createdAt: createdAt.toISOString(),
+                runtimeHandle: handle,
+                opencodeSessionId: reusedOpenCodeSessionId,
+                userPrompt: spawnConfig.prompt,
+                displayName,
+            });
+            if (plugins.agent.postLaunchSetup) {
+                await plugins.agent.postLaunchSetup(session);
+            }
+            if (plugins.agent.promptDelivery === "post-launch" && agentLaunchConfig.prompt) {
+                await plugins.runtime.sendMessage(handle, agentLaunchConfig.prompt);
+            }
+            if (plugins.agent.name === "opencode" &&
+                opencodeIssueSessionStrategy === "reuse" &&
+                !session.metadata["opencodeSessionId"]) {
+                const discovered = await discoverOpenCodeSessionIdByTitle(sessionId, OPENCODE_INTERACTIVE_DISCOVERY_TIMEOUT_MS);
+                if (discovered) {
+                    session.metadata["opencodeSessionId"] = discovered;
+                }
+            }
+            if (Object.keys(session.metadata || {}).length > 0) {
+                updateMetadata(sessionsDir, sessionId, session.metadata);
+            }
+            invalidateCache();
+            // Past this point every resource that needed an undo is on disk in its
+            // final form. Dismiss the stack so nothing below can trigger a rollback.
+            cleanupStack.dismiss();
+            // Prompt is delivered inline via the agent's launch command (positional argument).
+            // No post-launch polling needed — the prompt is part of process invocation.
+            recordActivityEvent({
+                projectId: spawnConfig.projectId,
+                sessionId,
+                source: "session-manager",
+                kind: "session.spawned",
+                summary: `spawned: ${sessionId}`,
+                data: { agent: plugins.agent.name, branch: session.branch ?? undefined },
+            });
+            return session;
+        }
+        catch (err) {
+            // Log cleanup failures so they don't disappear silently. The original
+            // code used /* best effort */ swallows; the stack preserves that
+            // behavior (cleanup errors don't propagate) but surfaces them for debug.
+            recordActivityEvent({
+                projectId: spawnConfig.projectId,
+                sessionId,
+                source: "session-manager",
+                kind: "session.rollback_started",
+                level: "warn",
+                summary: "spawn rollback started",
+                data: { reason: err instanceof Error ? err.message : String(err) },
+            });
+            await cleanupStack.runAll((cleanupErr) => {
+                console.error("[session-manager] spawn rollback step failed:", cleanupErr);
+                // B25: emit per-step rollback failure so each leaked resource is queryable.
+                recordActivityEvent({
+                    projectId: spawnConfig.projectId,
+                    sessionId,
+                    source: "session-manager",
+                    kind: "session.rollback_step_failed",
+                    level: "error",
+                    summary: "spawn rollback step failed",
+                    data: {
+                        reason: cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr),
+                    },
+                });
+            });
+            throw err;
+        }
+    }
+    function recordOrchestratorSpawnFailed(orchestratorConfig, err, sessionId) {
+        recordActivityEvent({
+            projectId: orchestratorConfig.projectId,
+            ...(sessionId ? { sessionId } : {}),
+            source: "session-manager",
+            kind: "session.spawn_failed",
+            level: "error",
+            summary: "orchestrator spawn failed",
+            data: {
+                role: "orchestrator",
+                reason: err instanceof Error ? err.message : String(err),
+            },
+        });
+    }
+    async function spawnOrchestrator(orchestratorConfig, options) {
+        recordActivityEvent({
+            projectId: orchestratorConfig.projectId,
+            source: "session-manager",
+            kind: "session.spawn_started",
+            summary: "orchestrator spawn started",
+            data: { agent: orchestratorConfig.agent ?? undefined, role: "orchestrator" },
+        });
+        try {
+            return await _spawnOrchestratorInner(orchestratorConfig);
+        }
+        catch (err) {
+            const project = config.projects[orchestratorConfig.projectId];
+            const sessionId = project ? getOrchestratorSessionId(project) : undefined;
+            const shouldSuppressRecoverableConflict = options?.suppressFixedReservationFailure === true &&
+                sessionId !== undefined &&
+                isFixedOrchestratorReservationError(err, sessionId);
+            if (!shouldSuppressRecoverableConflict) {
+                recordOrchestratorSpawnFailed(orchestratorConfig, err, sessionId);
+            }
+            throw err;
+        }
+    }
+    async function _spawnOrchestratorInner(orchestratorConfig) {
+        const project = config.projects[orchestratorConfig.projectId];
+        if (!project) {
+            throw new Error(`Unknown project: ${orchestratorConfig.projectId}`);
+        }
+        const selection = resolveAgentSelection({
+            role: "orchestrator",
+            project,
+            defaults: config.defaults,
+            spawnAgentOverride: orchestratorConfig.agent,
+        });
+        const plugins = resolvePlugins(project, selection.agentName);
+        if (!plugins.runtime) {
+            throw new Error(`Runtime plugin '${project.runtime ?? config.defaults.runtime}' not found`);
+        }
+        if (!plugins.agent) {
+            throw new Error(`Agent plugin '${selection.agentName}' not found`);
+        }
+        // Get the sessions directory for this project
+        const sessionsDir = getProjectSessionsDir(orchestratorConfig.projectId);
+        const orchestratorSessionStrategy = normalizeOrchestratorSessionStrategy(project.orchestratorSessionStrategy);
+        const identity = reserveFixedOrchestratorIdentity(project, sessionsDir);
+        const sessionId = identity.sessionId;
+        const tmuxName = identity.tmuxName;
+        // The main orchestrator is deterministic, but still uses an isolated worktree.
+        const branch = `orchestrator/${sessionId}`;
+        if (!plugins.workspace) {
+            try {
+                deleteMetadata(sessionsDir, sessionId);
+            }
+            catch {
+                /* best effort */
+            }
+            throw new Error(`spawnOrchestrator requires a workspace plugin but none is configured for project '${orchestratorConfig.projectId}'`);
+        }
+        const workspaceConfig = {
+            projectId: orchestratorConfig.projectId,
+            project,
+            sessionId,
+            branch,
+            worktreeDir: getProjectWorktreesDir(orchestratorConfig.projectId),
+        };
+        let workspacePath;
+        let adoptedManagedWorkspace = false;
+        try {
+            const adoptedInfo = await plugins.workspace.findManagedWorkspace?.(workspaceConfig);
+            const wsInfo = adoptedInfo ?? (await plugins.workspace.create(workspaceConfig));
+            workspacePath = wsInfo.path;
+            adoptedManagedWorkspace = adoptedInfo !== undefined && adoptedInfo !== null;
+        }
+        catch (err) {
+            recordActivityEvent({
+                projectId: orchestratorConfig.projectId,
+                sessionId,
+                source: "session-manager",
+                kind: "session.spawn_step_failed",
+                level: "error",
+                summary: "orchestrator workspace.create failed",
+                data: {
+                    role: "orchestrator",
+                    stage: "workspace_create",
+                    reason: err instanceof Error ? err.message : String(err),
+                },
+            });
+            try {
+                deleteMetadata(sessionsDir, sessionId);
+            }
+            catch {
+                /* best effort */
+            }
+            throw err;
+        }
+        // Helper: undo worktree + metadata if anything between workspace creation
+        // and a fully-written metadata record fails.
+        const cleanupWorktreeAndMetadata = async (promptFile) => {
+            if (!adoptedManagedWorkspace) {
+                try {
+                    // plugins.workspace is guaranteed non-null here: we threw above if it was null
+                    await plugins.workspace.destroy(workspacePath);
+                }
+                catch {
+                    /* best effort */
+                }
+            }
+            try {
+                deleteMetadata(sessionsDir, sessionId);
+            }
+            catch {
+                /* best effort */
+            }
+            if (promptFile) {
+                try {
+                    unlinkSync(promptFile);
+                }
+                catch {
+                    /* best effort */
+                }
+            }
+        };
+        // Setup agent hooks for automatic metadata updates.
+        // Claude Code uses native PostToolUse hooks for metadata writes — skip
+        // PATH wrappers to avoid two concurrent writers (wrapper + hook) hitting
+        // the same metadata file with no locking.
+        try {
+            if (plugins.agent.setupWorkspaceHooks) {
+                await plugins.agent.setupWorkspaceHooks(workspacePath, { dataDir: sessionsDir });
+            }
+            if (plugins.agent.name !== "claude-code") {
+                await setupPathWrapperWorkspace(workspacePath);
+            }
+        }
+        catch (err) {
+            // PR tracking and CI fetch hooks are wired here — emit a dedicated AE
+            // before rolling back so RCA can answer "did the orchestrator launch
+            // succeed but lose its hook integration?".
+            recordActivityEvent({
+                projectId: orchestratorConfig.projectId,
+                sessionId,
+                source: "session-manager",
+                kind: "session.workspace_hooks_failed",
+                level: "error",
+                summary: "orchestrator workspace hooks installation failed",
+                data: {
+                    agent: plugins.agent.name,
+                    reason: err instanceof Error ? err.message : String(err),
+                },
+            });
+            await cleanupWorktreeAndMetadata();
+            throw err;
+        }
+        // Write system prompt to a file to avoid shell/tmux truncation.
+        // Long prompts (2000+ chars) get mangled when inlined in shell commands
+        // via tmux send-keys or paste-buffer. File-based approach is reliable.
+        let systemPromptFile;
+        if (orchestratorConfig.systemPrompt) {
+            try {
+                const projectDir = getProjectDir(orchestratorConfig.projectId);
+                mkdirSync(projectDir, { recursive: true });
+                systemPromptFile = join(projectDir, `orchestrator-prompt-${sessionId}.md`);
+                writeFileSync(systemPromptFile, orchestratorConfig.systemPrompt, "utf-8");
+            }
+            catch (err) {
+                recordActivityEvent({
+                    projectId: orchestratorConfig.projectId,
+                    sessionId,
+                    source: "session-manager",
+                    kind: "session.spawn_step_failed",
+                    level: "error",
+                    summary: "orchestrator systemPrompt write failed",
+                    data: {
+                        role: "orchestrator",
+                        stage: "system_prompt_write",
+                        reason: err instanceof Error ? err.message : String(err),
+                    },
+                });
+                await cleanupWorktreeAndMetadata(systemPromptFile);
+                throw err;
+            }
+        }
+        if (plugins.agent.name === "opencode" && systemPromptFile) {
+            try {
+                writeWorkspaceOpenCodeAgentsMd(workspacePath, systemPromptFile);
+            }
+            catch (err) {
+                recordActivityEvent({
+                    projectId: orchestratorConfig.projectId,
+                    sessionId,
+                    source: "session-manager",
+                    kind: "session.spawn_step_failed",
+                    level: "error",
+                    summary: "orchestrator AGENTS.md write failed",
+                    data: {
+                        role: "orchestrator",
+                        stage: "agents_md_write",
+                        reason: err instanceof Error ? err.message : String(err),
+                    },
+                });
+                await cleanupWorktreeAndMetadata(systemPromptFile);
+                throw err;
+            }
+        }
+        let reusableOpenCodeSessionId;
+        try {
+            reusableOpenCodeSessionId =
+                plugins.agent.name === "opencode" && orchestratorSessionStrategy === "reuse"
+                    ? await resolveOpenCodeSessionReuse({
+                        sessionsDir,
+                        criteria: { sessionId },
+                        strategy: "reuse",
+                    })
+                    : undefined;
+            if (plugins.agent.name === "opencode" && orchestratorSessionStrategy === "delete") {
+                await resolveOpenCodeSessionReuse({
+                    sessionsDir,
+                    criteria: { sessionId },
+                    strategy: "delete",
+                    includeTitleDiscoveryForSessionId: true,
+                });
+            }
+        }
+        catch (err) {
+            recordActivityEvent({
+                projectId: orchestratorConfig.projectId,
+                sessionId,
+                source: "session-manager",
+                kind: "session.spawn_step_failed",
+                level: "error",
+                summary: "orchestrator opencode session resolution failed",
+                data: {
+                    role: "orchestrator",
+                    stage: "opencode_session_reuse",
+                    reason: err instanceof Error ? err.message : String(err),
+                },
+            });
+            await cleanupWorktreeAndMetadata(systemPromptFile);
+            throw err;
+        }
+        // Get agent launch config — uses systemPromptFile, no issue/tracker interaction.
+        // Orchestrator ALWAYS gets permissionless mode — it must run ao CLI commands autonomously.
+        const agentLaunchConfig = {
+            sessionId,
+            projectConfig: {
+                ...project,
+                agentConfig: {
+                    ...selection.agentConfig,
+                    permissions: "permissionless",
+                    ...(reusableOpenCodeSessionId ? { opencodeSessionId: reusableOpenCodeSessionId } : {}),
+                },
+            },
+            workspacePath,
+            permissions: "permissionless",
+            model: selection.model,
+            systemPromptFile,
+            subagent: selection.subagent,
+        };
+        const launchCommand = plugins.agent.getLaunchCommand(agentLaunchConfig);
+        const environment = plugins.agent.getEnvironment(agentLaunchConfig);
+        if (plugins.agent.preLaunchSetup) {
+            await plugins.agent.preLaunchSetup(workspacePath);
+        }
+        // Create runtime — clean up worktree and metadata on failure
+        let handle;
+        try {
+            handle = await plugins.runtime.create({
+                sessionId: tmuxName ?? sessionId,
+                workspacePath,
+                launchCommand,
+                environment: {
+                    ...environment,
+                    ...(project.env ?? {}),
+                    PATH: buildAgentPath(environment["PATH"] ?? process.env["PATH"]),
+                    GH_PATH: PREFERRED_GH_PATH,
+                    ...(process.env["AO_AGENT_GH_TRACE"] && {
+                        AO_AGENT_GH_TRACE: process.env["AO_AGENT_GH_TRACE"],
+                    }),
+                    AO_SESSION: sessionId,
+                    AO_DATA_DIR: sessionsDir,
+                    AO_SESSION_NAME: sessionId,
+                    ...(tmuxName && { AO_TMUX_NAME: tmuxName }),
+                    AO_CALLER_TYPE: "orchestrator",
+                    AO_PROJECT_ID: orchestratorConfig.projectId,
+                    AO_CONFIG_PATH: config.configPath,
+                    ...(config.port !== undefined &&
+                        config.port !== null && { AO_PORT: String(config.port) }),
+                },
+            });
+        }
+        catch (err) {
+            // Outer envelope catches and emits session.spawn_failed; this step emit
+            // tags the runtime.create failure path specifically so RCA can answer
+            // "did the orchestrator runtime fail to start at all?".
+            recordActivityEvent({
+                projectId: orchestratorConfig.projectId,
+                sessionId,
+                source: "session-manager",
+                kind: "session.spawn_step_failed",
+                level: "error",
+                summary: "orchestrator runtime.create failed",
+                data: {
+                    role: "orchestrator",
+                    stage: "runtime_create",
+                    reason: err instanceof Error ? err.message : String(err),
+                },
+            });
+            await cleanupWorktreeAndMetadata(systemPromptFile);
+            throw err;
+        }
+        // Derive a stable display name from the orchestrator's system prompt so
+        // the dashboard shows something more useful than "Ao Orchestrator 8".
+        const displayName = deriveDisplayName({
+            prompt: orchestratorConfig.systemPrompt,
+        });
+        // Write metadata and run post-launch setup
+        const createdAt = new Date();
+        const lifecycle = createInitialCanonicalLifecycle("orchestrator", createdAt);
+        lifecycle.session.state = "working";
+        lifecycle.session.reason = "task_in_progress";
+        lifecycle.session.startedAt = createdAt.toISOString();
+        lifecycle.session.lastTransitionAt = createdAt.toISOString();
+        lifecycle.runtime.handle = handle;
+        lifecycle.runtime.tmuxName = tmuxName ?? null;
+        const session = {
+            id: sessionId,
+            projectId: orchestratorConfig.projectId,
+            status: deriveLegacyStatus(lifecycle),
+            activity: "active",
+            activitySignal: createActivitySignal("valid", {
+                activity: "active",
+                timestamp: createdAt,
+                source: "runtime",
+            }),
+            lifecycle,
+            branch,
+            issueId: null,
+            pr: null,
+            prs: [],
+            workspacePath,
+            runtimeHandle: handle,
+            agentInfo: null,
+            createdAt,
+            lastActivityAt: createdAt,
+            metadata: {
+                ...(reusableOpenCodeSessionId ? { opencodeSessionId: reusableOpenCodeSessionId } : {}),
+                ...(displayName ? { displayName } : {}),
+            },
+        };
+        try {
+            writeMetadata(sessionsDir, sessionId, {
+                worktree: workspacePath,
+                branch,
+                status: deriveLegacyStatus(lifecycle),
+                ...buildLifecycleMetadataPatch(lifecycle),
+                // Object overrides for the typed writeMetadata path —
+                // see the spawnSession site for the rationale.
+                lifecycle,
+                role: "orchestrator",
+                tmuxName,
+                project: orchestratorConfig.projectId,
+                agent: selection.agentName,
+                createdAt: createdAt.toISOString(),
+                runtimeHandle: handle,
+                opencodeSessionId: reusableOpenCodeSessionId,
+                displayName,
+            });
+            if (plugins.agent.postLaunchSetup) {
+                await plugins.agent.postLaunchSetup(session);
+            }
+            if (plugins.agent.promptDelivery === "post-launch" && orchestratorConfig.systemPrompt) {
+                // The orchestrator prompt is already passed via systemPromptFile in the launch command.
+                // Send only a minimal trigger so interactive post-launch agents start without
+                // receiving their system instructions again as a user message.
+                await plugins.runtime.sendMessage(handle, "Begin.");
+            }
+            if (plugins.agent.name === "opencode" &&
+                orchestratorSessionStrategy === "reuse" &&
+                !session.metadata["opencodeSessionId"]) {
+                const discovered = await discoverOpenCodeSessionIdByTitle(sessionId, OPENCODE_INTERACTIVE_DISCOVERY_TIMEOUT_MS);
+                if (discovered) {
+                    session.metadata["opencodeSessionId"] = discovered;
+                }
+            }
+            if (Object.keys(session.metadata || {}).length > 0) {
+                updateMetadata(sessionsDir, sessionId, session.metadata);
+            }
+            invalidateCache();
+        }
+        catch (err) {
+            recordActivityEvent({
+                projectId: orchestratorConfig.projectId,
+                sessionId,
+                source: "session-manager",
+                kind: "session.spawn_step_failed",
+                level: "error",
+                summary: "orchestrator post-launch metadata write failed",
+                data: {
+                    role: "orchestrator",
+                    stage: "post_launch_metadata",
+                    reason: err instanceof Error ? err.message : String(err),
+                },
+            });
+            // Clean up runtime on post-launch failure
+            try {
+                await plugins.runtime.destroy(handle);
+            }
+            catch {
+                /* best effort */
+            }
+            await cleanupWorktreeAndMetadata(systemPromptFile);
+            throw err;
+        }
+        recordActivityEvent({
+            projectId: orchestratorConfig.projectId,
+            sessionId,
+            source: "session-manager",
+            kind: "session.spawned",
+            summary: `spawned: ${sessionId}`,
+            data: {
+                agent: plugins.agent.name,
+                branch: session.branch ?? undefined,
+                role: "orchestrator",
+            },
+        });
+        return session;
+    }
+    async function waitForConcurrentOrchestrator(sessionId) {
+        const deadline = Date.now() + ENSURE_ORCHESTRATOR_CONFLICT_WAIT_MS;
+        while (Date.now() < deadline) {
+            const existing = await get(sessionId);
+            if (existing?.metadata["role"] === "orchestrator") {
+                return existing;
+            }
+            await sleep(ENSURE_ORCHESTRATOR_CONFLICT_POLL_MS);
+        }
+        return null;
+    }
+    async function ensureOrchestratorInternal(orchestratorConfig) {
+        const project = config.projects[orchestratorConfig.projectId];
+        if (!project) {
+            throw new Error(`Unknown project: ${orchestratorConfig.projectId}`);
+        }
+        const sessionId = getOrchestratorSessionId(project);
+        // If a relaunch is mid-flight for this sessionId, wait it out — otherwise
+        // we could return a session that relaunch is about to kill, or race the
+        // relaunch's spawnOrchestrator on the same reservation.
+        const pendingRelaunch = relaunchOrchestratorPromises.get(sessionId);
+        if (pendingRelaunch) {
+            await pendingRelaunch.catch((err) => {
+                console.warn(`[ensureOrchestrator] in-flight relaunch for ${sessionId} failed before ensure proceeded:`, err);
+            });
+        }
+        const existing = await get(sessionId);
+        if (existing) {
+            const orchestratorSessionStrategy = normalizeOrchestratorSessionStrategy(project.orchestratorSessionStrategy);
+            if (orchestratorSessionStrategy === "delete" ||
+                orchestratorSessionStrategy === "ignore") {
+                await kill(sessionId, { purgeOpenCode: orchestratorSessionStrategy === "delete" });
+                deleteMetadata(getProjectSessionsDir(orchestratorConfig.projectId), sessionId);
+                return spawnOrchestrator(orchestratorConfig);
+            }
+            if (existing.lifecycle.session.state === "done") {
+                throw new SessionNotRestorableError(sessionId, `canonical orchestrator session is terminal with status "${existing.status}". Remove or clean up this session before starting a new orchestrator.`);
+            }
+            if (isRestorable(existing)) {
+                return restore(sessionId);
+            }
+            if (!isTerminalSession(existing)) {
+                return existing;
+            }
+            throw new SessionNotRestorableError(sessionId, `canonical orchestrator session is terminal with status "${existing.status}". Remove or clean up this session before starting a new orchestrator.`);
+        }
+        try {
+            return await spawnOrchestrator(orchestratorConfig, {
+                suppressFixedReservationFailure: true,
+            });
+        }
+        catch (err) {
+            if (!isFixedOrchestratorReservationError(err, sessionId)) {
+                throw err;
+            }
+            recordActivityEvent({
+                projectId: orchestratorConfig.projectId,
+                sessionId,
+                source: "session-manager",
+                kind: "session.orchestrator_conflict",
+                level: "warn",
+                summary: "concurrent orchestrator reservation conflict",
+                data: { reason: err instanceof Error ? err.message : String(err) },
+            });
+            const concurrent = await waitForConcurrentOrchestrator(sessionId);
+            if (concurrent)
+                return concurrent;
+            recordOrchestratorSpawnFailed(orchestratorConfig, err, sessionId);
+            throw err;
+        }
+    }
+    async function ensureOrchestrator(orchestratorConfig) {
+        const project = config.projects[orchestratorConfig.projectId];
+        if (!project) {
+            throw new Error(`Unknown project: ${orchestratorConfig.projectId}`);
+        }
+        const sessionId = getOrchestratorSessionId(project);
+        const existingPromise = ensureOrchestratorPromises.get(sessionId);
+        if (existingPromise)
+            return existingPromise;
+        const promise = ensureOrchestratorInternal(orchestratorConfig).finally(() => {
+            ensureOrchestratorPromises.delete(sessionId);
+        });
+        ensureOrchestratorPromises.set(sessionId, promise);
+        return promise;
+    }
+    async function relaunchOrchestratorInternal(orchestratorConfig) {
+        const project = config.projects[orchestratorConfig.projectId];
+        if (!project) {
+            throw new Error(`Unknown project: ${orchestratorConfig.projectId}`);
+        }
+        const sessionId = getOrchestratorSessionId(project);
+        const sessionsDir = getProjectSessionsDir(orchestratorConfig.projectId);
+        // If ensureOrchestrator is mid-flight for this sessionId, wait it out.
+        // Otherwise get() would return null (metadata not yet written) and we'd
+        // skip the kill, then race the in-flight spawnOrchestrator on the same
+        // reservation — surfacing "session already exists" instead of replacing.
+        const pendingEnsure = ensureOrchestratorPromises.get(sessionId);
+        if (pendingEnsure) {
+            await pendingEnsure.catch((err) => {
+                console.warn(`[relaunchOrchestrator] in-flight ensure for ${sessionId} failed before relaunch proceeded:`, err);
+            });
+        }
+        const existing = await get(sessionId);
+        if (existing) {
+            const existingAgent = resolveSelectionForSession(project, sessionId, readMetadataRaw(sessionsDir, sessionId) ?? {}).agentName;
+            await kill(sessionId, { purgeOpenCode: existingAgent === "opencode" });
+            deleteMetadata(sessionsDir, sessionId);
+        }
+        return spawnOrchestrator(orchestratorConfig);
+    }
+    async function relaunchOrchestrator(orchestratorConfig) {
+        const project = config.projects[orchestratorConfig.projectId];
+        if (!project) {
+            throw new Error(`Unknown project: ${orchestratorConfig.projectId}`);
+        }
+        const sessionId = getOrchestratorSessionId(project);
+        const existingPromise = relaunchOrchestratorPromises.get(sessionId);
+        if (existingPromise)
+            return existingPromise;
+        const promise = relaunchOrchestratorInternal(orchestratorConfig).finally(() => {
+            relaunchOrchestratorPromises.delete(sessionId);
+        });
+        relaunchOrchestratorPromises.set(sessionId, promise);
+        return promise;
+    }
+    async function list(projectId) {
+        const allSessions = Object.entries(config.projects).flatMap(([entryProjectId, project]) => {
+            if (projectId && entryProjectId !== projectId)
+                return [];
+            return loadActiveSessionRecords(entryProjectId, project).map((record) => ({
+                sessionName: record.sessionName,
+                projectId: entryProjectId,
+                raw: record.raw,
+            }));
+        });
+        let openCodeSessionListPromise;
+        const tasks = allSessions.map(async ({ sessionName, projectId: sessionProjectId, raw }) => {
+            const project = config.projects[sessionProjectId];
+            if (!project)
+                return null;
+            const sessionsDir = getProjectSessionsDir(sessionProjectId);
+            let createdAt;
+            let modifiedAt;
+            try {
+                const metaPath = join(sessionsDir, `${sessionName}.json`);
+                const stats = statSync(metaPath);
+                createdAt = stats.birthtime;
+                modifiedAt = stats.mtime;
+            }
+            catch {
+                // If stat fails, timestamps will fall back to current time
+            }
+            const session = metadataToSession(sessionName, raw, {
+                projectId: sessionProjectId,
+                sessionPrefix: project.sessionPrefix,
+                createdAt,
+                modifiedAt,
+                workspacePathFallback: project.path,
+            });
+            const selection = resolveSelectionForSession(project, sessionName, raw);
+            const effectiveAgentName = selection.agentName;
+            const plugins = resolvePlugins(project, effectiveAgentName);
+            const sessionListPromise = effectiveAgentName === "opencode"
+                ? (openCodeSessionListPromise ??= fetchOpenCodeSessionList())
+                : undefined;
+            let enrichTimeoutId = null;
+            const enrichTimeout = new Promise((resolve) => {
+                enrichTimeoutId = setTimeout(resolve, OPENCODE_DISCOVERY_TIMEOUT_MS + 2_000);
+            });
+            const enrichPromise = ensureHandleAndEnrich(session, sessionName, sessionsDir, project, effectiveAgentName, plugins, sessionListPromise).catch(() => { });
+            try {
+                await Promise.race([enrichPromise, enrichTimeout]);
+            }
+            finally {
+                if (enrichTimeoutId) {
+                    clearTimeout(enrichTimeoutId);
+                }
+            }
+            // Persist runtime probe result to disk so the lifecycle manager sees it
+            // on next poll. We only persist the runtime signal and detecting state —
+            // the lifecycle manager's resolveProbeDecision pipeline is the single
+            // authority on terminal decisions (terminated/done). See #1735.
+            // Check the on-disk state (raw) to avoid re-writing when already
+            // detecting — enrichment sets detecting in-memory, but we only need
+            // to persist the transition once to avoid resetting lastTransitionAt.
+            const onDiskLifecycle = parseCanonicalLifecycle(raw, {
+                sessionId: sessionName,
+                status: validateStatus(raw["status"]),
+            });
+            if (session.lifecycle &&
+                (session.lifecycle.runtime.state === "missing" ||
+                    session.lifecycle.runtime.state === "exited") &&
+                onDiskLifecycle.session.state !== "terminated" &&
+                onDiskLifecycle.session.state !== "done" &&
+                onDiskLifecycle.session.state !== "detecting") {
+                const runtimeStateBefore = session.lifecycle.runtime.state;
+                const runtimeReasonBefore = session.lifecycle.runtime.reason;
+                try {
+                    const persisted = buildUpdatedLifecycle(sessionName, raw, (next) => {
+                        next.session.state = "detecting";
+                        next.session.reason = "runtime_lost";
+                        next.session.lastTransitionAt = new Date().toISOString();
+                        next.runtime.state = runtimeStateBefore;
+                        next.runtime.reason = runtimeReasonBefore;
+                        next.runtime.lastObservedAt = new Date().toISOString();
+                    });
+                    // B1: persist BEFORE emitting the event
+                    updateMetadata(sessionsDir, sessionName, lifecycleMetadataUpdates(raw, persisted));
+                    session.lifecycle = persisted;
+                    session.status = deriveLegacyStatus(persisted);
+                    recordActivityEvent({
+                        projectId: sessionProjectId,
+                        sessionId: sessionName,
+                        source: "session-manager",
+                        kind: "runtime.lost_detected",
+                        level: "warn",
+                        summary: `runtime lost reconciled: ${sessionName}`,
+                        data: {
+                            runtimeState: runtimeStateBefore,
+                            runtimeReason: runtimeReasonBefore,
+                        },
+                    });
+                }
+                catch (err) {
+                    // Persist failed — in-memory state is still correct for this request
+                    recordActivityEvent({
+                        projectId: sessionProjectId,
+                        sessionId: sessionName,
+                        source: "session-manager",
+                        kind: "runtime.lost_persist_failed",
+                        level: "error",
+                        summary: `runtime_lost persist failed: ${sessionName}`,
+                        data: { reason: err instanceof Error ? err.message : String(err) },
+                    });
+                }
+            }
+            return session;
+        });
+        const resolved = await Promise.all(tasks);
+        return resolved.filter((session) => session !== null);
+    }
+    async function listCached(projectId) {
+        if (sessionCache && Date.now() < sessionCache.expiresAt) {
+            return projectId
+                ? sessionCache.sessions.filter((session) => session.projectId === projectId)
+                : sessionCache.sessions;
+        }
+        const sessions = await list();
+        sessionCache = {
+            sessions,
+            expiresAt: Date.now() + SESSION_CACHE_TTL_MS,
+        };
+        return projectId ? sessions.filter((session) => session.projectId === projectId) : sessions;
+    }
+    async function get(sessionId) {
+        // Try to find the session in any project's sessions directory
+        for (const [projectId, project] of Object.entries(config.projects)) {
+            const sessionsDir = getProjectSessionsDir(projectId);
+            const raw = readMetadataRaw(sessionsDir, sessionId);
+            if (!raw)
+                continue;
+            // Get file timestamps for createdAt/lastActivityAt
+            let createdAt;
+            let modifiedAt;
+            try {
+                const metaPath = join(sessionsDir, `${sessionId}.json`);
+                const stats = statSync(metaPath);
+                createdAt = stats.birthtime;
+                modifiedAt = stats.mtime;
+            }
+            catch {
+                // If stat fails, timestamps will fall back to current time
+            }
+            const repaired = repairSessionAgentMetadataOnRead(sessionsDir, repairSingleSessionMetadataOnRead(sessionsDir, { sessionName: sessionId, raw, modifiedAt }, project.sessionPrefix), project);
+            const session = metadataToSession(sessionId, repaired.raw, {
+                projectId,
+                sessionPrefix: project.sessionPrefix,
+                createdAt,
+                modifiedAt,
+                workspacePathFallback: project.path,
+            });
+            const selection = resolveSelectionForSession(project, sessionId, repaired.raw);
+            const effectiveAgentName = selection.agentName;
+            const plugins = resolvePlugins(project, effectiveAgentName);
+            await ensureHandleAndEnrich(session, sessionId, sessionsDir, project, effectiveAgentName, plugins);
+            return session;
+        }
+        return null;
+    }
+    async function kill(sessionId, options) {
+        const located = findSessionRecord(sessionId);
+        if (!located) {
+            // Session not found via findSessionRecord — check if it exists with
+            // a terminated lifecycle so auto-cleanup retries don't throw.
+            for (const [killProjectId] of Object.entries(config.projects)) {
+                const sessionsDir = getProjectSessionsDir(killProjectId);
+                const raw = readMetadataRaw(sessionsDir, sessionId);
+                if (raw) {
+                    const lifecycle = parseLifecycleFromRaw(raw);
+                    if (lifecycle?.session.state === "terminated") {
+                        return { cleaned: false, alreadyTerminated: true };
+                    }
+                }
+            }
+            throw new SessionNotFoundError(sessionId);
+        }
+        const { raw, sessionsDir, project, projectId } = located;
+        // Idempotency: if lifecycle already says terminated, don't re-run destroys
+        // (which could double-purge opencode or race with concurrent kills).
+        const existingLifecycle = parseCanonicalLifecycle(raw);
+        if (existingLifecycle?.session.state === "terminated") {
+            return { cleaned: false, alreadyTerminated: true };
+        }
+        const killReason = options?.reason ?? "manually_killed";
+        const cleanupAgent = resolveSelectionForSession(project, sessionId, raw).agentName;
+        // Emit kill_started up-front — this is the only signal that the kill
+        // intent reached the manager (the destroys below are silent on failure).
+        recordActivityEvent({
+            projectId,
+            sessionId,
+            source: "session-manager",
+            kind: "session.kill_started",
+            summary: `kill started: ${sessionId}`,
+            data: { reason: killReason },
+        });
+        // Destroy runtime — prefer handle.runtimeName to find the correct plugin
+        if (raw["runtimeHandle"]) {
+            const handle = safeJsonParse(raw["runtimeHandle"]);
+            if (handle) {
+                const runtimePlugin = registry.get("runtime", handle.runtimeName ??
+                    (project ? (project.runtime ?? config.defaults.runtime) : config.defaults.runtime));
+                if (runtimePlugin) {
+                    try {
+                        await runtimePlugin.destroy(handle);
+                    }
+                    catch (err) {
+                        // Runtime might already be gone — surface as AE so leaks are queryable.
+                        recordActivityEvent({
+                            projectId,
+                            sessionId,
+                            source: "session-manager",
+                            kind: "runtime.destroy_failed",
+                            level: "warn",
+                            summary: `runtime.destroy failed during kill: ${sessionId}`,
+                            data: {
+                                runtime: handle.runtimeName ?? null,
+                                reason: err instanceof Error ? err.message : String(err),
+                            },
+                        });
+                    }
+                }
+            }
+        }
+        const worktree = raw["worktree"];
+        if (worktree && shouldDestroyWorkspacePath(project, projectId, worktree)) {
+            const workspacePlugin = project
+                ? resolvePlugins(project).workspace
+                : registry.get("workspace", config.defaults.workspace);
+            if (workspacePlugin) {
+                try {
+                    await workspacePlugin.destroy(worktree);
+                }
+                catch (err) {
+                    // Workspace might already be gone — emit AE so abandoned worktrees
+                    // surface for cleanup tooling.
+                    recordActivityEvent({
+                        projectId,
+                        sessionId,
+                        source: "session-manager",
+                        kind: "workspace.destroy_failed",
+                        level: "warn",
+                        summary: `workspace.destroy failed during kill: ${sessionId}`,
+                        data: {
+                            workspace: workspacePlugin.name,
+                            reason: err instanceof Error ? err.message : String(err),
+                        },
+                    });
+                }
+            }
+        }
+        let didPurgeOpenCodeSession = false;
+        if (options?.purgeOpenCode === true && cleanupAgent === "opencode") {
+            const mappedOpenCodeSessionId = asValidOpenCodeSessionId(raw["opencodeSessionId"]) ??
+                (await discoverOpenCodeSessionIdByTitle(sessionId, OPENCODE_INTERACTIVE_DISCOVERY_TIMEOUT_MS));
+            if (mappedOpenCodeSessionId) {
+                try {
+                    await deleteOpenCodeSession(mappedOpenCodeSessionId);
+                    didPurgeOpenCodeSession = true;
+                }
+                catch (err) {
+                    // Dangling opencode session is a real leak — surface for RCA.
+                    recordActivityEvent({
+                        projectId,
+                        sessionId,
+                        source: "session-manager",
+                        kind: "agent.opencode_purge_failed",
+                        level: "warn",
+                        summary: `opencode session purge failed: ${sessionId}`,
+                        data: {
+                            opencodeSessionId: mappedOpenCodeSessionId,
+                            reason: err instanceof Error ? err.message : String(err),
+                        },
+                    });
+                }
+            }
+        }
+        const runtimeReason = killReason === "pr_merged"
+            ? "pr_merged_cleanup"
+            : killReason === "auto_cleanup"
+                ? "auto_cleanup"
+                : "manual_kill_requested";
+        const terminatedLifecycle = buildUpdatedLifecycle(sessionId, raw, (next) => {
+            next.session.state = "terminated";
+            next.session.reason = killReason;
+            next.session.terminatedAt = new Date().toISOString();
+            next.session.lastTransitionAt = next.session.terminatedAt;
+            next.runtime.state = raw["runtimeHandle"] || raw["tmuxName"] ? "missing" : "exited";
+            next.runtime.reason = runtimeReason;
+            next.runtime.lastObservedAt = new Date().toISOString();
+        });
+        updateMetadata(sessionsDir, sessionId, {
+            ...lifecycleMetadataUpdates(raw, terminatedLifecycle),
+            ...(didPurgeOpenCodeSession && {
+                opencodeSessionId: "",
+                opencodeCleanedAt: new Date().toISOString(),
+            }),
+        });
+        invalidateCache();
+        recordActivityEvent({
+            projectId,
+            sessionId,
+            source: "session-manager",
+            kind: "session.killed",
+            summary: `killed: ${sessionId}`,
+            data: { reason: killReason },
+        });
+        return { cleaned: true, alreadyTerminated: false };
+    }
+    async function cleanup(projectId, options) {
+        const result = { killed: [], skipped: [], errors: [] };
+        const sessions = await list(projectId);
+        const killedKeys = new Set();
+        const skippedKeys = new Set();
+        const toEntryKey = (entryProjectId, id) => `${entryProjectId}:${id}`;
+        const fromEntryKey = (entryKey) => {
+            const separatorIndex = entryKey.indexOf(":");
+            if (separatorIndex === -1) {
+                return { projectId: "", id: entryKey };
+            }
+            return {
+                projectId: entryKey.slice(0, separatorIndex),
+                id: entryKey.slice(separatorIndex + 1),
+            };
+        };
+        const pushKilled = (entryProjectId, id) => {
+            const key = toEntryKey(entryProjectId, id);
+            skippedKeys.delete(key);
+            killedKeys.add(key);
+        };
+        const pushSkipped = (entryProjectId, id) => {
+            const key = toEntryKey(entryProjectId, id);
+            if (killedKeys.has(key))
+                return;
+            skippedKeys.add(key);
+        };
+        const shouldPurgeOpenCode = options?.purgeOpenCode !== false;
+        for (const session of sessions) {
+            try {
+                const project = config.projects[session.projectId];
+                if (!project) {
+                    pushSkipped(session.projectId, session.id);
+                    continue;
+                }
+                if (isCleanupProtectedSession(project, session.id, session.metadata)) {
+                    pushSkipped(session.projectId, session.id);
+                    continue;
+                }
+                const plugins = resolvePlugins(project);
+                let shouldKill = false;
+                // Check if all tracked PRs are closed without merging.
+                // For multi-PR sessions, keep alive as long as any PR is still open.
+                const prsToCheck = session.prs.length > 0 ? session.prs : session.pr ? [session.pr] : [];
+                if (prsToCheck.length > 0 && plugins.scm) {
+                    try {
+                        const states = await Promise.all(prsToCheck.map((pr) => plugins.scm.getPRState(pr)));
+                        if (states.every((state) => state === PR_STATE.CLOSED)) {
+                            shouldKill = true;
+                        }
+                    }
+                    catch {
+                        // Can't check PR — skip
+                    }
+                }
+                // Check if issue is completed
+                if (!shouldKill && session.issueId && plugins.tracker) {
+                    try {
+                        const completed = await plugins.tracker.isCompleted(session.issueId, project);
+                        if (completed)
+                            shouldKill = true;
+                    }
+                    catch {
+                        // Can't check issue — skip
+                    }
+                }
+                // Check if runtime is dead
+                if (!shouldKill && session.runtimeHandle && plugins.runtime) {
+                    try {
+                        const alive = await plugins.runtime.isAlive(session.runtimeHandle);
+                        if (!alive)
+                            shouldKill = true;
+                    }
+                    catch {
+                        // Can't check — skip
+                    }
+                }
+                if (shouldKill) {
+                    if (!options?.dryRun) {
+                        await kill(session.id, { purgeOpenCode: shouldPurgeOpenCode });
+                    }
+                    pushKilled(session.projectId, session.id);
+                }
+                else {
+                    pushSkipped(session.projectId, session.id);
+                }
+            }
+            catch (err) {
+                const errorMessage = err instanceof Error ? err.message : String(err);
+                result.errors.push({
+                    sessionId: session.id,
+                    error: errorMessage,
+                });
+                recordActivityEvent({
+                    projectId: session.projectId,
+                    sessionId: session.id,
+                    source: "session-manager",
+                    kind: "session.cleanup_error",
+                    level: "warn",
+                    summary: `cleanup error: ${session.id}`,
+                    data: { reason: errorMessage },
+                });
+            }
+        }
+        // Clean up terminated sessions with uncleaned OpenCode mappings.
+        // These sessions are already in sessions/ (returned by listMetadata) and may
+        // have been processed by the first loop via list(). We skip sessions that were
+        // already killed above, but still process those that were only skipped.
+        for (const [projectKey, project] of Object.entries(config.projects)) {
+            if (projectId && projectKey !== projectId)
+                continue;
+            const sessionsDir = getProjectSessionsDir(projectKey);
+            for (const terminatedId of listMetadata(sessionsDir)) {
+                const entryKey = toEntryKey(projectKey, terminatedId);
+                if (killedKeys.has(entryKey))
+                    continue;
+                const terminatedRaw = readMetadataRaw(sessionsDir, terminatedId);
+                if (!terminatedRaw)
+                    continue;
+                const lifecycle = parseLifecycleFromRaw(terminatedRaw);
+                if (lifecycle?.session.state !== "terminated")
+                    continue;
+                if (isCleanupProtectedSession(project, terminatedId, terminatedRaw)) {
+                    pushSkipped(projectKey, terminatedId);
+                    continue;
+                }
+                const cleanupAgent = resolveSelectionForSession(project, terminatedId, terminatedRaw).agentName;
+                const mappedOpenCodeSessionId = asValidOpenCodeSessionId(terminatedRaw["opencodeSessionId"]);
+                if (cleanupAgent === "opencode" && terminatedRaw["opencodeCleanedAt"]) {
+                    pushSkipped(projectKey, terminatedId);
+                    continue;
+                }
+                if (cleanupAgent === "opencode" && mappedOpenCodeSessionId && shouldPurgeOpenCode) {
+                    if (!options?.dryRun) {
+                        try {
+                            await deleteOpenCodeSession(mappedOpenCodeSessionId);
+                            mutateMetadata(sessionsDir, terminatedId, (existing) => ({
+                                ...existing,
+                                opencodeSessionId: "",
+                                opencodeCleanedAt: new Date().toISOString(),
+                            }), { activityEventSource: "session-manager" });
+                        }
+                        catch (err) {
+                            const errorMessage = err instanceof Error ? err.message : String(err);
+                            result.errors.push({
+                                sessionId: terminatedId,
+                                error: `Failed to delete OpenCode session ${mappedOpenCodeSessionId}: ${errorMessage}`,
+                            });
+                            recordActivityEvent({
+                                projectId: projectKey,
+                                sessionId: terminatedId,
+                                source: "session-manager",
+                                kind: "agent.opencode_purge_failed",
+                                level: "warn",
+                                summary: `opencode session purge failed during cleanup: ${terminatedId}`,
+                                data: {
+                                    opencodeSessionId: mappedOpenCodeSessionId,
+                                    reason: errorMessage,
+                                },
+                            });
+                            continue;
+                        }
+                    }
+                    pushKilled(projectKey, terminatedId);
+                }
+                else {
+                    pushSkipped(projectKey, terminatedId);
+                }
+            }
+        }
+        const allEntryKeys = [...killedKeys, ...skippedKeys];
+        const idCounts = new Map();
+        for (const entryKey of allEntryKeys) {
+            const { id } = fromEntryKey(entryKey);
+            idCounts.set(id, (idCounts.get(id) ?? 0) + 1);
+        }
+        const formatEntry = (entryKey) => {
+            const { projectId: entryProjectId, id } = fromEntryKey(entryKey);
+            return (idCounts.get(id) ?? 0) > 1 ? `${entryProjectId}:${id}` : id;
+        };
+        result.killed = [...killedKeys].map(formatEntry);
+        result.skipped = [...skippedKeys].map(formatEntry);
+        return result;
+    }
+    async function send(sessionId, message) {
+        const { raw, sessionsDir, project, projectId } = requireSessionRecord(sessionId);
+        const selection = resolveSelectionForSession(project, sessionId, raw);
+        const selectedAgent = selection.agentName;
+        if (selectedAgent === "opencode" && !asValidOpenCodeSessionId(raw["opencodeSessionId"])) {
+            const discovered = await discoverOpenCodeSessionIdByTitle(sessionId, OPENCODE_INTERACTIVE_DISCOVERY_TIMEOUT_MS);
+            if (discovered) {
+                raw["opencodeSessionId"] = discovered;
+                updateMetadata(sessionsDir, sessionId, { opencodeSessionId: discovered });
+                invalidateCache();
+            }
+        }
+        const parsedHandle = raw["runtimeHandle"]
+            ? safeJsonParse(raw["runtimeHandle"])
+            : null;
+        const runtimeName = parsedHandle?.runtimeName ?? project.runtime ?? config.defaults.runtime;
+        const agentName = selectedAgent;
+        const runtimePlugin = registry.get("runtime", runtimeName);
+        if (!runtimePlugin) {
+            throw new Error(`No runtime plugin for session ${sessionId}`);
+        }
+        const agentPlugin = registry.get("agent", agentName);
+        if (!agentPlugin) {
+            throw new Error(`No agent plugin for session ${sessionId}`);
+        }
+        const captureOutput = async (handle) => {
+            try {
+                return (await runtimePlugin.getOutput(handle, SEND_CONFIRMATION_OUTPUT_LINES)) ?? "";
+            }
+            catch {
+                return "";
+            }
+        };
+        const detectActivityFromOutput = (output) => {
+            if (!output)
+                return null;
+            try {
+                return agentPlugin.detectActivity(output);
+            }
+            catch {
+                return null;
+            }
+        };
+        const hasQueuedMessage = (output) => {
+            return output.includes("Press up to edit queued messages");
+        };
+        const getOpenCodeSessionUpdatedAt = async () => {
+            const mappedSessionId = asValidOpenCodeSessionId(raw["opencodeSessionId"]);
+            if (agentName !== "opencode" || !mappedSessionId) {
+                return undefined;
+            }
+            const sessions = await fetchOpenCodeSessionList(OPENCODE_DISCOVERY_TIMEOUT_MS);
+            return sessions.find((entry) => entry.id === mappedSessionId)?.updatedAt;
+        };
+        const waitForInteractiveReadiness = async (session, timeoutMs) => {
+            const handle = session.runtimeHandle;
+            if (!handle) {
+                return;
+            }
+            const deadline = Date.now() + timeoutMs;
+            let lastSettledOutput = null;
+            let stablePolls = 0;
+            while (true) {
+                const [runtimeAlive, processRunning, output, foregroundCommand] = await Promise.all([
+                    runtimePlugin.isAlive(handle).catch(() => true),
+                    isAgentProcessNotDefinitelyMissing(agentPlugin, handle),
+                    captureOutput(handle),
+                    handle.runtimeName === "tmux"
+                        ? getTmuxForegroundCommand(handle.id)
+                        : Promise.resolve(agentPlugin.processName),
+                ]);
+                const outputReady = output.trim().length > 0;
+                const foregroundReady = foregroundCommand === null || foregroundCommand === agentPlugin.processName;
+                const settledOutput = outputReady ? output.trimEnd() : null;
+                const isStable = settledOutput !== null && settledOutput === lastSettledOutput;
+                if (runtimeAlive &&
+                    processRunning &&
+                    foregroundReady &&
+                    (hasQueuedMessage(output) || isStable)) {
+                    stablePolls += 1;
+                    if (stablePolls >= SEND_BOOTSTRAP_STABLE_POLLS) {
+                        return;
+                    }
+                }
+                else {
+                    stablePolls = 0;
+                }
+                lastSettledOutput = settledOutput;
+                if (Date.now() >= deadline) {
+                    return;
+                }
+                await sleep(SEND_RESTORE_READY_POLL_MS);
+            }
+        };
+        const waitForRestoredSession = async (restoredSession) => {
+            const handle = restoredSession.runtimeHandle;
+            if (!handle) {
+                return false;
+            }
+            const deadline = Date.now() + SEND_RESTORE_READY_TIMEOUT_MS;
+            while (true) {
+                const [runtimeAlive, processRunning, output, foregroundCommand] = await Promise.all([
+                    runtimePlugin.isAlive(handle).catch(() => true),
+                    isAgentProcessNotDefinitelyMissing(agentPlugin, handle),
+                    captureOutput(handle),
+                    handle.runtimeName === "tmux"
+                        ? getTmuxForegroundCommand(handle.id)
+                        : Promise.resolve(agentPlugin.processName),
+                ]);
+                const foregroundReady = foregroundCommand === null || foregroundCommand === agentPlugin.processName;
+                if (runtimeAlive && foregroundReady && (processRunning || output.trim().length > 0)) {
+                    return true;
+                }
+                if (Date.now() >= deadline) {
+                    return false;
+                }
+                await sleep(SEND_RESTORE_READY_POLL_MS);
+            }
+        };
+        const restoreForDelivery = async (reason, session) => {
+            if (session.lifecycle.session.state === "done") {
+                throw new Error(`Cannot send to session ${sessionId}: ${reason}`);
+            }
+            let restored;
+            try {
+                restored = await restore(sessionId);
+            }
+            catch (err) {
+                const detail = err instanceof Error ? err.message : String(err);
+                throw new Error(`Cannot send to session ${sessionId}: ${reason} (${detail})`, {
+                    cause: err,
+                });
+            }
+            const ready = await waitForRestoredSession(restored);
+            if (!ready) {
+                const detail = "restored session did not become ready for delivery";
+                recordActivityEvent({
+                    projectId,
+                    sessionId,
+                    source: "session-manager",
+                    kind: "session.restore_failed",
+                    level: "error",
+                    summary: `restore for delivery failed: ${sessionId}`,
+                    data: { stage: "ready_timeout", reason: detail, trigger: "send" },
+                });
+                throw new Error(`Cannot send to session ${sessionId}: ${reason} (${detail})`);
+            }
+            return restored;
+        };
+        const prepareSession = async (forceRestore = false) => {
+            const current = await get(sessionId);
+            if (!current) {
+                throw new SessionNotFoundError(sessionId);
+            }
+            const handle = current.runtimeHandle ??
+                {
+                    id: sessionId,
+                    runtimeName,
+                    data: {},
+                };
+            const normalized = current.runtimeHandle ? current : { ...current, runtimeHandle: handle };
+            if (forceRestore || isRestorable(normalized)) {
+                return restoreForDelivery(forceRestore
+                    ? "session needed to be restarted before delivery"
+                    : "session is not running", normalized);
+            }
+            let [runtimeAlive, processRunning] = await Promise.all([
+                runtimePlugin.isAlive(handle).catch(() => true),
+                isAgentProcessNotDefinitelyMissing(agentPlugin, handle),
+            ]);
+            if (normalized.status === "spawning" && runtimeAlive) {
+                await waitForInteractiveReadiness(normalized, SEND_BOOTSTRAP_READY_TIMEOUT_MS);
+                [runtimeAlive, processRunning] = await Promise.all([
+                    runtimePlugin.isAlive(handle).catch(() => true),
+                    isAgentProcessNotDefinitelyMissing(agentPlugin, handle),
+                ]);
+            }
+            if (!runtimeAlive || !processRunning) {
+                return restoreForDelivery(!runtimeAlive ? "runtime is not alive" : "agent process is not running", normalized);
+            }
+            return normalized;
+        };
+        const sendWithConfirmation = async (session) => {
+            const handle = session.runtimeHandle;
+            if (!handle) {
+                throw new Error(`Session ${sessionId} has no runtime handle`);
+            }
+            const baselineOutput = await captureOutput(handle);
+            const baselineActivity = detectActivityFromOutput(baselineOutput) ?? session.activity;
+            const baselineUpdatedAt = await getOpenCodeSessionUpdatedAt();
+            await runtimePlugin.sendMessage(handle, message);
+            for (let attempt = 1; attempt <= SEND_CONFIRMATION_ATTEMPTS; attempt++) {
+                // Sleep before each check (including the first) so the runtime has time
+                // to reflect the message in its output.
+                await sleep(SEND_CONFIRMATION_POLL_MS);
+                const output = await captureOutput(handle);
+                const activity = detectActivityFromOutput(output) ?? session.activity;
+                const updatedAt = await getOpenCodeSessionUpdatedAt();
+                const delivered = (baselineUpdatedAt !== undefined &&
+                    updatedAt !== undefined &&
+                    updatedAt > baselineUpdatedAt) ||
+                    hasQueuedMessage(output) ||
+                    (output.length > 0 && output !== baselineOutput) ||
+                    (baselineActivity !== "active" && activity === "active") ||
+                    (baselineActivity !== "waiting_input" && activity === "waiting_input");
+                if (delivered) {
+                    return;
+                }
+            }
+            // Message was already sent via runtimePlugin.sendMessage above — if we
+            // cannot *confirm* delivery (e.g. agent is slow to show output), treat it
+            // as a soft success rather than throwing.  Throwing here caused the caller
+            // to report failure, which prevented the dispatch-hash from updating and
+            // led to duplicate messages on the next poll cycle.
+            return;
+        };
+        // Top-level try/catch: any final send failure (initial preparation,
+        // retry-with-restore, etc.) emits a single `session.send_failed` event
+        // (B16 — failure-only). Stage tag distinguishes which branch failed.
+        let stage = "prepare";
+        try {
+            let prepared = await prepareSession();
+            try {
+                stage = "initial";
+                await sendWithConfirmation(prepared);
+            }
+            catch (err) {
+                const shouldRetryWithRestore = prepared.restoredAt === undefined && isRestorable(prepared);
+                if (!shouldRetryWithRestore) {
+                    if (err instanceof Error) {
+                        throw err;
+                    }
+                    throw new Error(String(err), { cause: err });
+                }
+                stage = "restore_retry";
+                prepared = await prepareSession(true);
+                try {
+                    await sendWithConfirmation(prepared);
+                }
+                catch (retryErr) {
+                    if (retryErr instanceof Error) {
+                        throw retryErr;
+                    }
+                    throw new Error(String(retryErr), { cause: retryErr });
+                }
+            }
+        }
+        catch (err) {
+            recordActivityEvent({
+                projectId,
+                sessionId,
+                source: "session-manager",
+                kind: "session.send_failed",
+                level: "error",
+                summary: `send failed: ${sessionId}`,
+                data: {
+                    stage,
+                    reason: err instanceof Error ? err.message : String(err),
+                },
+            });
+            throw err;
+        }
+    }
+    async function claimPR(sessionId, prRef, options) {
+        const reference = prRef.trim();
+        if (!reference)
+            throw new Error("PR reference is required");
+        const { raw, sessionsDir, project, projectId } = requireSessionRecord(sessionId);
+        if (isOrchestratorSessionRecord(sessionId, raw, project.sessionPrefix)) {
+            throw new Error(`Session ${sessionId} is an orchestrator session and cannot claim PRs`);
+        }
+        const plugins = resolvePlugins(project, resolveSelectionForSession(project, sessionId, raw).agentName);
+        const scm = plugins.scm;
+        if (!scm?.resolvePR || !scm.checkoutPR) {
+            throw new Error(`SCM plugin ${project.scm?.plugin ? `"${project.scm.plugin}" ` : ""}does not support claiming existing PRs`);
+        }
+        const pr = await scm.resolvePR(reference, project);
+        const prState = await scm.getPRState(pr);
+        if (prState !== PR_STATE.OPEN) {
+            throw new Error(`Cannot claim PR #${pr.number} because it is ${prState}`);
+        }
+        const conflictingSessions = new Set();
+        const activeRecords = loadActiveSessionRecords(projectId, project).filter((record) => record.sessionName !== sessionId);
+        for (const { sessionName, raw: otherRaw } of activeRecords) {
+            if (!otherRaw || isOrchestratorSessionRecord(sessionName, otherRaw, project.sessionPrefix))
+                continue;
+            const otherPrUrls = new Set([
+                otherRaw["pr"],
+                ...(typeof otherRaw["prs"] === "string" ? otherRaw["prs"].split(",") : []),
+            ]
+                .map((u) => (typeof u === "string" ? u.trim() : ""))
+                .filter(Boolean));
+            const samePr = otherPrUrls.has(pr.url);
+            const sameBranch = otherRaw["branch"] === pr.branch && (otherRaw["prAutoDetect"] ?? "on") !== "off" && otherRaw["prAutoDetect"] !== "false";
+            if (samePr || sameBranch) {
+                conflictingSessions.add(sessionName);
+            }
+        }
+        const takenOverFrom = [...conflictingSessions];
+        const workspacePath = raw["worktree"];
+        if (!workspacePath) {
+            throw new Error(`Session ${sessionId} has no workspace to check out PR #${pr.number}`);
+        }
+        const branchChanged = await scm.checkoutPR(pr, workspacePath);
+        const claimLifecycle = buildUpdatedLifecycle(sessionId, raw, (next) => {
+            next.pr.state = "open";
+            next.pr.reason = "in_progress";
+            next.pr.number = pr.number;
+            next.pr.url = pr.url;
+            next.pr.lastObservedAt = new Date().toISOString();
+        });
+        // Stack: push claimed PR to front — it becomes primary (prs[0]) on next load.
+        // Filter out duplicates, keep all other tracked PRs at the back.
+        const existingPrs = raw["prs"] ?? raw["pr"] ?? "";
+        const otherPrs = dedupePrUrls(existingPrs.split(",").filter((u) => u.trim() !== pr.url)).join(",");
+        const newPrs = otherPrs ? `${pr.url},${otherPrs}` : pr.url;
+        // Clear stale positional enrichment blobs — claimPR reorders prs[] so
+        // index-keyed blobs no longer match. Lifecycle poll rewrites them within ~30s.
+        const staleEnrichmentKeys = {
+            prEnrichment: "",
+            prReviewComments: "",
+        };
+        for (const key of Object.keys(raw)) {
+            if (/^prEnrichment_\d+$/.test(key) || /^prReviewComments_\d+$/.test(key)) {
+                staleEnrichmentKeys[key] = "";
+            }
+        }
+        updateMetadata(sessionsDir, sessionId, {
+            pr: pr.url,
+            prs: newPrs,
+            status: deriveLegacyStatus(claimLifecycle),
+            branch: pr.branch,
+            prAutoDetect: "",
+            ...staleEnrichmentKeys,
+            ...lifecycleMetadataUpdates(raw, claimLifecycle),
+        });
+        invalidateCache();
+        for (const previousSessionId of takenOverFrom) {
+            const previousRaw = readMetadataRaw(sessionsDir, previousSessionId);
+            if (!previousRaw)
+                continue;
+            const previousLifecycle = buildUpdatedLifecycle(previousSessionId, previousRaw, (next) => {
+                next.pr.state = "none";
+                next.pr.reason = "not_created";
+                next.pr.number = null;
+                next.pr.url = null;
+                next.pr.lastObservedAt = null;
+                if (PR_TRACKING_STATUSES.has(previousRaw["status"] ?? "")) {
+                    next.session.state = "working";
+                    next.session.reason = "task_in_progress";
+                }
+            });
+            updateMetadata(sessionsDir, previousSessionId, {
+                pr: "",
+                prs: "",
+                prAutoDetect: "false",
+                ...(PR_TRACKING_STATUSES.has(previousRaw["status"] ?? "")
+                    ? { status: "working" }
+                    : {}),
+                ...lifecycleMetadataUpdates(previousRaw, previousLifecycle),
+            });
+            invalidateCache();
+        }
+        let githubAssigned = false;
+        let githubAssignmentError;
+        if (options?.assignOnGithub) {
+            if (!scm.assignPRToCurrentUser) {
+                githubAssignmentError = `SCM plugin "${scm.name}" does not support assigning PRs`;
+            }
+            else {
+                try {
+                    await scm.assignPRToCurrentUser(pr);
+                    githubAssigned = true;
+                }
+                catch (err) {
+                    githubAssignmentError = err instanceof Error ? err.message : String(err);
+                }
+            }
+        }
+        return {
+            sessionId,
+            projectId,
+            pr,
+            branchChanged,
+            githubAssigned,
+            githubAssignmentError,
+            takenOverFrom,
+        };
+    }
+    async function remap(sessionId, force = false) {
+        const { raw, sessionsDir, project } = requireSessionRecord(sessionId);
+        const selection = resolveSelectionForSession(project, sessionId, raw);
+        const selectedAgent = selection.agentName;
+        if (selectedAgent !== "opencode") {
+            throw new Error(`Session ${sessionId} is not using the opencode agent`);
+        }
+        const mapped = asValidOpenCodeSessionId(raw["opencodeSessionId"]);
+        const discovered = force
+            ? await discoverOpenCodeSessionIdByTitle(sessionId, OPENCODE_INTERACTIVE_DISCOVERY_TIMEOUT_MS)
+            : (mapped ??
+                (await discoverOpenCodeSessionIdByTitle(sessionId, OPENCODE_INTERACTIVE_DISCOVERY_TIMEOUT_MS)));
+        if (!discovered) {
+            throw new Error(`OpenCode session mapping is missing for ${sessionId}`);
+        }
+        updateMetadata(sessionsDir, sessionId, { opencodeSessionId: discovered });
+        return discovered;
+    }
+    async function restore(sessionId) {
+        // 1. Find session metadata across all projects
+        const activeRecord = findSessionRecord(sessionId);
+        if (!activeRecord) {
+            throw new SessionNotFoundError(sessionId);
+        }
+        let raw = activeRecord.raw;
+        const sessionsDir = activeRecord.sessionsDir;
+        const project = activeRecord.project;
+        const projectId = activeRecord.projectId;
+        const selection = resolveSelectionForSession(project, sessionId, raw);
+        const selectedAgent = selection.agentName;
+        if (selectedAgent === "opencode" && !asValidOpenCodeSessionId(raw["opencodeSessionId"])) {
+            const discovered = await discoverOpenCodeSessionIdByTitle(sessionId, OPENCODE_INTERACTIVE_DISCOVERY_TIMEOUT_MS);
+            if (!discovered) {
+                throw new SessionNotRestorableError(sessionId, "OpenCode session mapping is missing");
+            }
+            raw = { ...raw, opencodeSessionId: discovered };
+            updateMetadata(sessionsDir, sessionId, { opencodeSessionId: discovered });
+        }
+        // 2. Reconstruct Session from metadata and enrich with live runtime state.
+        //    metadataToSession sets activity: null, so without enrichment a crashed
+        //    session (status "working", agent exited) would not be detected as terminal
+        //    and isRestorable would reject it.
+        const session = metadataToSession(sessionId, raw, {
+            projectId,
+            sessionPrefix: project.sessionPrefix,
+            workspacePathFallback: project.path,
+        });
+        const plugins = resolvePlugins(project, selection.agentName);
+        await enrichSessionWithRuntimeState(session, plugins, true, sessionsDir);
+        // 3. Validate restorability
+        if (!isRestorable(session)) {
+            const reason = NON_RESTORABLE_STATUSES.has(session.status)
+                ? `status "${session.status}" is not restorable`
+                : `session is not in a terminal state (status: "${session.status}", activity: "${session.activity}")`;
+            recordActivityEvent({
+                projectId,
+                sessionId,
+                source: "session-manager",
+                kind: "session.restore_failed",
+                level: "error",
+                summary: `restore not allowed: ${sessionId}`,
+                data: {
+                    stage: "validation",
+                    status: session.status,
+                    activity: session.activity,
+                    reason,
+                },
+            });
+            throw new SessionNotRestorableError(sessionId, reason);
+        }
+        // 4. Validate required plugins (plugins already resolved above for enrichment)
+        if (!plugins.runtime) {
+            throw new Error(`Runtime plugin '${project.runtime ?? config.defaults.runtime}' not found`);
+        }
+        if (!plugins.agent) {
+            throw new Error(`Agent plugin '${selection.agentName}' not found`);
+        }
+        // 5. Check workspace
+        const workspacePath = raw["worktree"] || project.path;
+        const workspaceExists = plugins.workspace?.exists
+            ? await plugins.workspace.exists(workspacePath)
+            : existsSync(workspacePath);
+        if (!workspaceExists) {
+            // Try to restore workspace if plugin supports it
+            if (!plugins.workspace?.restore) {
+                recordActivityEvent({
+                    projectId,
+                    sessionId,
+                    source: "session-manager",
+                    kind: "session.restore_failed",
+                    level: "error",
+                    summary: `restore workspace failed: ${sessionId}`,
+                    data: {
+                        stage: "workspace_restore",
+                        workspacePath,
+                        reason: "workspace plugin does not support restore",
+                    },
+                });
+                throw new WorkspaceMissingError(workspacePath, "workspace plugin does not support restore");
+            }
+            if (!session.branch) {
+                recordActivityEvent({
+                    projectId,
+                    sessionId,
+                    source: "session-manager",
+                    kind: "session.restore_failed",
+                    level: "error",
+                    summary: `restore workspace failed: ${sessionId}`,
+                    data: {
+                        stage: "workspace_restore",
+                        workspacePath,
+                        reason: "branch metadata is missing",
+                    },
+                });
+                throw new WorkspaceMissingError(workspacePath, "branch metadata is missing");
+            }
+            try {
+                const wsInfo = await plugins.workspace.restore({
+                    projectId,
+                    project,
+                    sessionId,
+                    branch: session.branch,
+                    worktreeDir: getProjectWorktreesDir(projectId),
+                }, workspacePath);
+                // Run post-create hooks on restored workspace
+                if (plugins.workspace.postCreate) {
+                    await plugins.workspace.postCreate(wsInfo, project);
+                }
+            }
+            catch (err) {
+                recordActivityEvent({
+                    projectId,
+                    sessionId,
+                    source: "session-manager",
+                    kind: "session.restore_failed",
+                    level: "error",
+                    summary: `workspace restore failed: ${sessionId}`,
+                    data: {
+                        stage: "workspace_restore",
+                        workspacePath,
+                        reason: err instanceof Error ? err.message : String(err),
+                    },
+                });
+                throw new WorkspaceMissingError(workspacePath, `restore failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        if (plugins.agent.name === "opencode" && selection.role === "orchestrator") {
+            const projectDir = getProjectDir(projectId);
+            const systemPromptFile = join(projectDir, `orchestrator-prompt-${sessionId}.md`);
+            if (existsSync(systemPromptFile)) {
+                try {
+                    writeWorkspaceOpenCodeAgentsMd(workspacePath, systemPromptFile);
+                }
+                catch (err) {
+                    throw new Error(`failed to restore OpenCode orchestrator AGENTS.md: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+                }
+            }
+        }
+        let opencodeConfigPath;
+        if (plugins.agent.name === "opencode" && selection.role !== "orchestrator") {
+            const baseDir = getProjectDir(projectId);
+            const systemPromptFile = join(baseDir, `worker-prompt-${sessionId}.md`);
+            if (existsSync(systemPromptFile)) {
+                opencodeConfigPath = writeOpenCodeConfig(baseDir, sessionId, [systemPromptFile]);
+            }
+        }
+        // 6. Destroy old runtime if still alive (e.g. tmux session survives agent crash)
+        if (session.runtimeHandle) {
+            try {
+                await plugins.runtime.destroy(session.runtimeHandle);
+            }
+            catch {
+                // Best effort — may already be gone
+            }
+        }
+        // 7. Get launch command — try restore command first, fall back to fresh launch
+        let launchCommand;
+        const projectConfigForLaunch = {
+            ...project,
+            agentConfig: {
+                ...selection.agentConfig,
+                ...(selection.role === "orchestrator" ? { permissions: "permissionless" } : {}),
+                ...(session.metadata?.opencodeSessionId
+                    ? { opencodeSessionId: session.metadata.opencodeSessionId }
+                    : {}),
+            },
+        };
+        // Orchestrator launches need the original systemPromptFile so the agent
+        // boots as the orchestrator (not a bare TUI). spawnOrchestrator wrote it to
+        // {baseDir}/orchestrator-prompt-{sessionId}.md and references it via
+        // agentLaunchConfig.systemPromptFile. On restore we must re-attach it,
+        // otherwise getLaunchCommand() (the fallback when getRestoreCommand returns
+        // null — e.g. Codex with no resumable thread for the worktree) starts a
+        // plain agent without orchestrator instructions.
+        const orchestratorSystemPromptFile = (() => {
+            if (selection.role !== "orchestrator")
+                return undefined;
+            // V2 storage: orchestrator-prompt-{sessionId}.md lives in the project dir
+            // (~/.agent-orchestrator/projects/{projectId}/), not the legacy hashed base dir.
+            const baseDir = getProjectDir(projectId);
+            const file = join(baseDir, `orchestrator-prompt-${sessionId}.md`);
+            return existsSync(file) ? file : undefined;
+        })();
+        const agentLaunchConfig = {
+            sessionId,
+            projectConfig: projectConfigForLaunch,
+            workspacePath,
+            issueId: session.issueId ?? undefined,
+            permissions: selection.role === "orchestrator" ? "permissionless" : selection.permissions,
+            model: selection.model,
+            subagent: selection.subagent,
+            ...(orchestratorSystemPromptFile && { systemPromptFile: orchestratorSystemPromptFile }),
+        };
+        if (plugins.agent.getRestoreCommand) {
+            const restoreCmd = await plugins.agent.getRestoreCommand(session, projectConfigForLaunch);
+            if (restoreCmd) {
+                launchCommand = restoreCmd;
+                updateMetadata(sessionsDir, sessionId, { restoreFallbackReason: "" });
+            }
+            else {
+                // Agents with native restore can still launch fresh when no resumable
+                // session metadata exists; this keeps restore from becoming a hard stop.
+                const reason = `${plugins.agent.name}.getRestoreCommand returned null`;
+                updateMetadata(sessionsDir, sessionId, {
+                    restoreFallbackReason: reason,
+                });
+                // Surface that AO fell back to a fresh launch instead of native restore.
+                recordActivityEvent({
+                    projectId,
+                    sessionId,
+                    source: "session-manager",
+                    kind: "session.restore_fallback",
+                    level: "warn",
+                    summary: `using fresh launch instead of native restore: ${sessionId}`,
+                    data: { agent: plugins.agent.name, reason },
+                });
+                launchCommand = plugins.agent.getLaunchCommand(agentLaunchConfig);
+            }
+        }
+        else {
+            launchCommand = plugins.agent.getLaunchCommand(agentLaunchConfig);
+            updateMetadata(sessionsDir, sessionId, { restoreFallbackReason: "" });
+        }
+        const environment = plugins.agent.getEnvironment(agentLaunchConfig);
+        if (plugins.agent.preLaunchSetup) {
+            await plugins.agent.preLaunchSetup(workspacePath);
+        }
+        // 8. Create runtime (reuse tmuxName from metadata)
+        const tmuxName = raw["tmuxName"];
+        const handle = await plugins.runtime.create({
+            sessionId: tmuxName ?? sessionId,
+            workspacePath,
+            launchCommand,
+            environment: {
+                ...environment,
+                ...(opencodeConfigPath ? { OPENCODE_CONFIG: opencodeConfigPath } : {}),
+                ...(project.env ?? {}),
+                PATH: buildAgentPath(environment["PATH"] ?? process.env["PATH"]),
+                GH_PATH: PREFERRED_GH_PATH,
+                ...(process.env["AO_AGENT_GH_TRACE"] && {
+                    AO_AGENT_GH_TRACE: process.env["AO_AGENT_GH_TRACE"],
+                }),
+                AO_SESSION: sessionId,
+                AO_DATA_DIR: sessionsDir,
+                AO_SESSION_NAME: sessionId,
+                ...(tmuxName && { AO_TMUX_NAME: tmuxName }),
+                AO_CALLER_TYPE: "agent",
+                ...(projectId && { AO_PROJECT_ID: projectId }),
+                AO_CONFIG_PATH: config.configPath,
+                ...(config.port !== undefined && config.port !== null && { AO_PORT: String(config.port) }),
+            },
+        });
+        // 9. Update metadata — reset lifecycle to working state
+        const now = new Date().toISOString();
+        const restoredLifecycle = cloneLifecycle(session.lifecycle);
+        restoredLifecycle.session.state = "working";
+        restoredLifecycle.session.reason = "task_in_progress";
+        restoredLifecycle.session.lastTransitionAt = now;
+        restoredLifecycle.session.terminatedAt = null;
+        restoredLifecycle.session.completedAt = null;
+        restoredLifecycle.runtime.state = "alive";
+        restoredLifecycle.runtime.reason = "process_running";
+        restoredLifecycle.runtime.handle = handle;
+        restoredLifecycle.runtime.lastObservedAt = now;
+        // Reset terminal PR state so the lifecycle manager doesn't immediately
+        // re-terminate the session. The old PR is done — if the agent creates
+        // a new one, PR auto-detect will pick it up.
+        if (restoredLifecycle.pr.state === "merged" || restoredLifecycle.pr.state === "closed") {
+            restoredLifecycle.pr.state = "none";
+            restoredLifecycle.pr.reason = "cleared_on_restore";
+            restoredLifecycle.pr.number = null;
+            restoredLifecycle.pr.url = null;
+            restoredLifecycle.pr.lastObservedAt = null;
+        }
+        updateMetadata(sessionsDir, sessionId, {
+            ...buildLifecycleMetadataPatch(restoredLifecycle),
+            agent: selection.agentName,
+            restoredAt: now,
+            mergedPendingCleanupSince: "",
+        });
+        invalidateCache();
+        // 10. Run postLaunchSetup (non-fatal)
+        const restoredStatus = deriveLegacyStatus(restoredLifecycle);
+        const restoredSession = {
+            ...session,
+            status: restoredStatus,
+            activity: "active",
+            workspacePath,
+            runtimeHandle: handle,
+            restoredAt: new Date(now),
+        };
+        if (plugins.agent.postLaunchSetup) {
+            try {
+                const metadataBeforePostLaunch = { ...(restoredSession.metadata ?? {}) };
+                await plugins.agent.postLaunchSetup(restoredSession);
+                const metadataAfterPostLaunch = restoredSession.metadata ?? {};
+                const metadataUpdates = Object.fromEntries(Object.entries(metadataAfterPostLaunch).filter(([key, value]) => metadataBeforePostLaunch[key] !== value));
+                if (Object.keys(metadataUpdates).length > 0) {
+                    updateMetadata(sessionsDir, sessionId, metadataUpdates);
+                    invalidateCache();
+                }
+            }
+            catch {
+                // Non-fatal — session is already running
+            }
+        }
+        return restoredSession;
+    }
+    return {
+        spawn,
+        spawnOrchestrator,
+        ensureOrchestrator,
+        relaunchOrchestrator,
+        restore,
+        list,
+        listCached,
+        invalidateCache,
+        get,
+        kill,
+        cleanup,
+        send,
+        claimPR,
+        remap,
+    };
+}
+
+export { createSessionManager };
+//# sourceMappingURL=session-manager.js.map