@made-by-moonlight/athene-core 0.9.1 → 0.10.0

package/dist/session-manager.js

@@ -1,4 +1,4 @@
-import { existsSync, statSync, mkdirSync, writeFileSync, unlinkSync, utimesSync } from 'node:fs';
+import { existsSync, statSync, mkdirSync, writeFileSync, utimesSync, unlinkSync, openSync, rmSync, closeSync, readFileSync } from 'node:fs';
 import { recordActivityEvent } from './activity-events.js';
 import { execFile } from 'node:child_process';
 import { join, resolve, basename } from 'node:path';
@@ -9,7 +9,7 @@ import { listMetadata, readMetadataRaw, updateMetadata, mutateMetadata, deleteMe
 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 { getProjectSessionsDir, getProjectWorktreesDir, getProjectDir, getMetaSessionsDir, getMetaWorkspaceDir, 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';
@@ -20,8 +20,10 @@ 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 { checkSpawnCollision, formatHardRefusal } from './spawn-collision.js';
 import { resolveAgentSelectionForSession, resolveAgentSelection } from './agent-selection.js';
 import { PREFERRED_GH_PATH, buildAgentPath, setupPathWrapperWorkspace } from './agent-workspace-hooks.js';
+import { withLegacyEnvAliases, ENV, getEnvString } from './env.js';
 
 /**
  * Session Manager — CRUD for agent sessions.
@@ -199,6 +201,133 @@ const ENSURE_ORCHESTRATOR_CONFLICT_POLL_MS = 250;
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+/**
+ * Read a project's sessions directly from metadata files — NO enrichment (no
+ * runtime liveness probes, no agent getSessionInfo execFile calls). Used by the
+ * spawn collision guard so the per-project spawn lock is held only for a brief,
+ * disk-only window, and so the read reflects in-flight issue claims immediately.
+ */
+function listProjectSessionsFromDisk(projectId) {
+    const dir = getProjectSessionsDir(projectId);
+    const sessions = [];
+    for (const id of listMetadata(dir)) {
+        const raw = readMetadataRaw(dir, id);
+        if (!raw)
+            continue;
+        sessions.push(sessionFromMetadata(id, raw, { projectId }));
+    }
+    return sessions;
+}
+/**
+ * Whether a session is TRULY terminal for spawn-dedup purposes: only
+ * done/terminated (covers manually_killed) or a merged PR. A runtime-lost /
+ * `detecting` session is a PENDING decision (#1735), NOT terminal — its in-memory
+ * enriched view may show runtime.state==='missing', but on disk it is `detecting`
+ * and it still OWNS its issue, so it must keep blocking a duplicate same-issue
+ * spawn for BOTH coordinators. Deliberately does not use `isTerminalSession`,
+ * which treats runtime.state==='missing'/'exited' as terminal.
+ */
+function isSpawnTerminal(session) {
+    const state = session.lifecycle.session.state;
+    return state === "done" || state === "terminated" || session.lifecycle.pr.state === "merged";
+}
+/**
+ * Cross-platform process-liveness probe via signal 0. `process.kill(pid, 0)` is
+ * portable (Windows included). Per docs/CROSS_PLATFORM.md: a throw with code
+ * `ESRCH` means the process is gone (dead); `EPERM` means it EXISTS but we can't
+ * signal it (alive). Any other throw is treated as not-alive.
+ */
+function isPidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+/**
+ * Backstop for a spawn.lock whose holder PID can't be read/parsed (legacy format,
+ * mid-write, or corruption) — only such a lock is reaped by age, and only after a
+ * long window no real disk-only critical section could ever reach. A lock with a
+ * readable PID is reaped ONLY when that PID is dead, never by age, so an
+ * alive-but-slow holder is never reaped.
+ */
+/**
+ * Absolute age ceiling for a spawn.lock. The in-lock critical section is
+ * disk-only (no network/runtime work — the git ls-remote is hoisted out), so it
+ * never legitimately runs anywhere near this long. Any lock older than this is
+ * reapable regardless of holder PID — this clears both a corrupt/no-PID lock and
+ * a PID-bearing lock whose SIGKILLed holder's PID was recycled to an unrelated
+ * live process (which would otherwise look "alive" forever and block spawns).
+ */
+const SPAWN_LOCK_MAX_AGE_MS = 300_000;
+/**
+ * Per-acquisition owner token written into spawn.lock: `${pid}:${nonce}`. The pid
+ * prefix drives liveness reaping; the nonce makes the token UNIQUE per
+ * acquisition (pid alone is not — PIDs are reused), so release can verify the
+ * lock is still ours and never delete one re-acquired by another process.
+ */
+let spawnLockNonceCounter = 0;
+function nextSpawnLockToken() {
+    return `${process.pid}:${process.hrtime.bigint().toString(36)}-${(spawnLockNonceCounter++).toString(36)}`;
+}
+/** Extract the holder PID from a lock token (`${pid}:${nonce}` or a bare pid). */
+function spawnLockPid(content) {
+    const pidStr = content.split(":", 1)[0] ?? "";
+    const pid = Number.parseInt(pidStr, 10);
+    return Number.isInteger(pid) && pid > 0 && String(pid) === pidStr ? pid : null;
+}
+/**
+ * Whether a waiter may reap an existing spawn.lock:
+ *  - over the absolute age ceiling → always reapable (any lock); or
+ *  - holder PID is parseable and provably dead → reapable immediately.
+ * A fresh lock held by a live PID (or in its brief no-token mid-write window) is
+ * NOT reaped. Exported for tests.
+ */
+function isSpawnLockReapable(lockPath, now = Date.now()) {
+    let content;
+    let mtimeMs;
+    try {
+        content = readFileSync(lockPath, "utf8").trim();
+        mtimeMs = statSync(lockPath).mtimeMs;
+    }
+    catch {
+        // Vanished/unreadable between the open attempt and here — safe to retry.
+        return true;
+    }
+    // Absolute ceiling applies to ALL locks (PID-bearing included), so a recycled
+    // dead-holder PID can never block spawns indefinitely.
+    if (now - mtimeMs > SPAWN_LOCK_MAX_AGE_MS) {
+        return true;
+    }
+    const pid = spawnLockPid(content);
+    if (pid !== null) {
+        // Within the ceiling — reap only if the holder process is provably gone.
+        return !isPidAlive(pid);
+    }
+    // No parseable PID and still fresh (legacy/mid-write/corrupt) — keep waiting.
+    return false;
+}
+/**
+ * Release a spawn.lock ONLY if it still records our owner token. If the file is
+ * missing or holds a different token — meaning we were reaped (age ceiling) and
+ * another process now owns it — leave it alone. This closes the lock-steal race
+ * where a holder that overran the ceiling would otherwise delete the new owner's
+ * lock. Exported for tests.
+ */
+function releaseSpawnLockIfOwned(lockPath, ownerToken) {
+    try {
+        if (readFileSync(lockPath, "utf8").trim() === ownerToken) {
+            rmSync(lockPath, { force: true });
+        }
+    }
+    catch {
+        // Missing/unreadable — nothing of ours to release.
+    }
+}
 async function isAgentProcessNotDefinitelyMissing(agent, handle) {
     try {
         return (await agent.isProcessRunning(handle)) !== false;
@@ -354,6 +483,7 @@ function createSessionManager(deps) {
     let sessionCache = null;
     const ensureOrchestratorPromises = new Map();
     const relaunchOrchestratorPromises = new Map();
+    const ensureMetaOrchestratorPromises = new Map();
     function invalidateCache() {
         sessionCache = null;
     }
@@ -639,14 +769,90 @@ function createSessionManager(deps) {
             return [];
         }
     }
-    async function reserveNextSessionIdentity(project, sessionsDir) {
+    /**
+     * Serialize the spawn collision-check + id-reservation window per project,
+     * ACROSS processes (the project orchestrator and a meta orchestrator each run
+     * their own `athene spawn` process). Without this, two concurrent spawns could
+     * both pass the issue-collision guard before either persists its claim, and
+     * both create live sessions owning the same issue. The lock is held only for
+     * the brief guard+reserve+claim window, never across worktree/runtime creation.
+     */
+    async function withProjectSpawnLock(projectId, fn) {
+        const projectDir = getProjectDir(projectId);
+        mkdirSync(projectDir, { recursive: true });
+        const lockPath = join(projectDir, "spawn.lock");
+        const timeoutMs = 30_000;
+        const deadline = Date.now() + timeoutMs;
+        let fd = null;
+        let waitMs = 10;
+        while (fd === null) {
+            try {
+                fd = openSync(lockPath, "wx");
+            }
+            catch (err) {
+                if (err.code !== "EEXIST") {
+                    throw new Error(`Failed to acquire spawn lock: ${lockPath}`, { cause: err });
+                }
+                // Checked every iteration (before any `continue`) so a vanished-lock
+                // race can't spin past the timeout.
+                if (Date.now() > deadline) {
+                    throw new Error(`Timed out acquiring spawn lock for project '${projectId}'`, {
+                        cause: err,
+                    });
+                }
+                // Liveness-based reaping: reap ONLY when the recorded holder PID is
+                // provably dead (or the lock is corrupt and past the backstop). A live
+                // but slow holder is never reaped, so the cross-process collision
+                // guarantee holds regardless of critical-section duration.
+                if (isSpawnLockReapable(lockPath)) {
+                    rmSync(lockPath, { force: true });
+                    continue;
+                }
+                await sleep(waitMs);
+                waitMs = Math.min(waitMs * 2, 250);
+            }
+        }
+        // Record our unique owner token (pid:nonce). The pid lets other waiters probe
+        // our liveness; the nonce lets release verify the lock is still ours. The
+        // brief empty-file window before this write reads as "no parseable token" and
+        // is protected by the age ceiling (never reaped while fresh).
+        const ownerToken = nextSpawnLockToken();
+        try {
+            writeFileSync(lockPath, ownerToken);
+        }
+        catch {
+            /* best effort — a missing token just falls back to the age ceiling */
+        }
+        try {
+            return await fn();
+        }
+        finally {
+            try {
+                closeSync(fd);
+            }
+            catch {
+                /* best effort */
+            }
+            // Only delete the lock if it is STILL ours — if we overran the age ceiling
+            // and were reaped, another process may now own it; deleting it then would
+            // break mutual exclusion.
+            releaseSpawnLockIfOwned(lockPath, ownerToken);
+        }
+    }
+    /**
+     * Reserve the next free session id. DISK-ONLY and synchronous: the remote
+     * branch lookup (git ls-remote) is performed by the caller BEFORE acquiring
+     * the spawn lock and passed in via `remoteSessionNumbers`, so the per-project
+     * spawn lock never spans a network round-trip.
+     */
+    function reserveNextSessionIdentity(project, sessionsDir, remoteSessionNumbers) {
         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)) {
+        for (const num of remoteSessionNumbers) {
             usedNumbers.add(num);
         }
         let num = getNextSessionNumber([...usedNumbers].map((value) => `${project.sessionPrefix}-${value}`), project.sessionPrefix);
@@ -972,12 +1178,75 @@ function createSessionManager(deps) {
         // ones.
         const cleanupStack = new CleanupStack();
         let sessionId;
+        let tmuxName;
+        // Fetch remote session numbers (git ls-remote, up to ~5s) BEFORE acquiring
+        // the spawn lock so the network round-trip is never serialized behind the
+        // per-project mutex — the in-lock window stays disk-only.
+        const remoteSessionNumbers = await listRemoteSessionNumbers(project);
+        // Anti-collision guard + id reservation run together under a per-project
+        // spawn lock so the check-then-reserve window is atomic ACROSS processes
+        // (the project orchestrator and a meta orchestrator each spawn from their own
+        // process). The guard runs BEFORE any worktree/runtime creation so a refusal
+        // orphans nothing, and is the single authority protecting BOTH coordinators
+        // symmetrically. Issue-keyed work is a HARD refusal; freeform work is
+        // advisory (surfaced by the CLI, not blocked here). The lock window is
+        // DISK-ONLY (no network/enrichment) — the remote lookup above was hoisted out.
+        await withProjectSpawnLock(spawnConfig.projectId, async () => {
+            // Minimal disk-only read (no enrichment/probes) so the lock window stays
+            // brief and reflects in-flight issue claims. Detecting/runtime-lost peers
+            // are intentionally NOT excluded (isSpawnTerminal, not isTerminalSession):
+            // they still own their issue and must block a duplicate (#1735).
+            const liveInProject = listProjectSessionsFromDisk(spawnConfig.projectId).filter((s) => !isSpawnTerminal(s));
+            const collision = checkSpawnCollision(liveInProject, {
+                projectId: spawnConfig.projectId,
+                issueId: spawnConfig.issueId,
+            });
+            if (collision.hard) {
+                throw new Error(formatHardRefusal(collision.hard));
+            }
+            // Atomically reserve the session id, then immediately persist the issue
+            // claim so a concurrent spawn (next to acquire the lock) sees it via
+            // list() and hard-refuses — the empty reservation file carries no issueId.
+            //
+            // Accepted tradeoff of cross-process dedup: this claim writes
+            // issue + status:"spawning" with no lifecycle/runtime handle yet. If the
+            // spawn process crashes between here and the full writeMetadata below, the
+            // session is left on disk as a "spawning" phantom that still owns the issue
+            // (isSpawnTerminal treats only done/terminated/merged as terminal), so it
+            // keeps hard-refusing re-spawns of that issue until it is cleaned up. It is
+            // self-healing — lifecycle reconciliation probes the absent runtime and
+            // terminates it — and killable in the meantime via `athene session kill`.
+            ({ sessionId, tmuxName } = reserveNextSessionIdentity(project, sessionsDir, remoteSessionNumbers));
+            if (spawnConfig.issueId) {
+                try {
+                    updateMetadata(sessionsDir, sessionId, {
+                        issue: spawnConfig.issueId,
+                        project: spawnConfig.projectId,
+                        status: "spawning",
+                    });
+                }
+                catch (err) {
+                    // Roll back the reservation so a failed claim write inside the lock
+                    // can't leave an orphaned phantom session (the cleanupStack undo is
+                    // only registered after this block).
+                    try {
+                        deleteMetadata(sessionsDir, sessionId);
+                    }
+                    catch {
+                        /* best effort */
+                    }
+                    throw err;
+                }
+            }
+        });
+        if (!sessionId) {
+            // reserveNextSessionIdentity throws on exhaustion, so this is unreachable;
+            // the guard narrows `sessionId` to string for the rest of the function.
+            throw new Error("Failed to reserve a session id");
+        }
+        const reservedSessionId = sessionId;
+        cleanupStack.push(() => deleteMetadata(sessionsDir, reservedSessionId));
         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) {
@@ -1124,25 +1393,25 @@ function createSessionManager(deps) {
                 sessionId: tmuxName ?? sessionId, // Use tmux name for runtime if available
                 workspacePath,
                 launchCommand,
-                environment: {
+                environment: withLegacyEnvAliases({
                     ...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"],
+                    ...(getEnvString(ENV.AGENT_GH_TRACE) && {
+                        [ENV.AGENT_GH_TRACE]: getEnvString(ENV.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,
+                    [ENV.SESSION]: sessionId,
+                    [ENV.DATA_DIR]: sessionsDir, // Pass sessions directory (not root dataDir)
+                    [ENV.SESSION_NAME]: sessionId, // User-facing session name
+                    ...(tmuxName && { [ENV.TMUX_NAME]: tmuxName }), // Tmux session name if using new arch
+                    [ENV.CALLER_TYPE]: "agent",
+                    [ENV.PROJECT_ID]: spawnConfig.projectId,
+                    [ENV.CONFIG_PATH]: config.configPath,
                     ...(config.port !== undefined &&
-                        config.port !== null && { AO_PORT: String(config.port) }),
-                },
+                        config.port !== null && { [ENV.PORT]: String(config.port) }),
+                }),
             });
             const rt = plugins.runtime;
             cleanupStack.push(() => rt.destroy(handle));
@@ -1183,6 +1452,15 @@ function createSessionManager(deps) {
                     ...(reusedOpenCodeSessionId ? { opencodeSessionId: reusedOpenCodeSessionId } : {}),
                     ...(spawnConfig.prompt ? { userPrompt: spawnConfig.prompt } : {}),
                     ...(displayName ? { displayName } : {}),
+                    // Owner stamping: meta-dispatched workers carry ownerKind/metaOwner so
+                    // they are visible to BOTH the meta orchestrator and the per-project
+                    // orchestrator. Absent => project-owned (the default).
+                    ...(spawnConfig.ownerKind === "meta"
+                        ? {
+                            ownerKind: "meta",
+                            ...(spawnConfig.metaOwner ? { metaOwner: spawnConfig.metaOwner } : {}),
+                        }
+                        : {}),
                 },
             };
             writeMetadata(sessionsDir, sessionId, {
@@ -1558,24 +1836,24 @@ function createSessionManager(deps) {
                 sessionId: tmuxName ?? sessionId,
                 workspacePath,
                 launchCommand,
-                environment: {
+                environment: withLegacyEnvAliases({
                     ...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"],
+                    ...(getEnvString(ENV.AGENT_GH_TRACE) && {
+                        [ENV.AGENT_GH_TRACE]: getEnvString(ENV.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,
+                    [ENV.SESSION]: sessionId,
+                    [ENV.DATA_DIR]: sessionsDir,
+                    [ENV.SESSION_NAME]: sessionId,
+                    ...(tmuxName && { [ENV.TMUX_NAME]: tmuxName }),
+                    [ENV.CALLER_TYPE]: "orchestrator",
+                    [ENV.PROJECT_ID]: orchestratorConfig.projectId,
+                    [ENV.CONFIG_PATH]: config.configPath,
                     ...(config.port !== undefined &&
-                        config.port !== null && { AO_PORT: String(config.port) }),
-                },
+                        config.port !== null && { [ENV.PORT]: String(config.port) }),
+                }),
             });
         }
         catch (err) {
@@ -1801,6 +2079,292 @@ function createSessionManager(deps) {
         ensureOrchestratorPromises.set(sessionId, promise);
         return promise;
     }
+    /**
+     * Ensure a meta orchestrator session exists for `name`. Reuses a live one if
+     * present (read from the reserved `_meta` scope), else spawns fresh.
+     *
+     * Meta orchestrators are NOT scoped to a single project, so they live under
+     * `projects/_meta/<name>/sessions/<name>.json` and are reconstructed by
+     * reading that file directly — `get()`/`list()` only walk configured projects.
+     */
+    function readExistingMetaSession(name) {
+        const existing = readMetadataRaw(getMetaSessionsDir(name), name);
+        if (!existing)
+            return null;
+        // projectId "_meta" for parity with the freshly-spawned path (meta["project"]
+        // is also persisted as "_meta", but pass it explicitly to be unambiguous).
+        return sessionFromMetadata(name, existing, {
+            projectId: "_meta",
+            sessionKind: "meta-orchestrator",
+        });
+    }
+    /**
+     * Synthetic project context for the reserved `_meta` scope — a meta orchestrator
+     * has no repo/worktree. `workspacePath` is a plain scratch dir (agent cwd +
+     * PATH-wrapper home), never a git worktree, so the workspace plugin's create()
+     * is intentionally never called. Shared by spawn and the liveness probe.
+     */
+    function metaProjectContext(name, agentOverride) {
+        const metaProject = {
+            name: `${name} (meta)`,
+            path: getMetaWorkspaceDir(name),
+            defaultBranch: "main",
+            sessionPrefix: name,
+        };
+        const selection = resolveAgentSelection({
+            role: "orchestrator",
+            project: metaProject,
+            defaults: config.defaults,
+            spawnAgentOverride: agentOverride,
+        });
+        const plugins = resolvePlugins(metaProject, selection.agentName);
+        return { metaProject, selection, plugins };
+    }
+    async function ensureMetaOrchestratorInternal(metaConfig) {
+        const name = metaConfig.name;
+        const existing = readExistingMetaSession(name);
+        if (existing && !isTerminalSession(existing)) {
+            // _meta sessions are not runtime-enriched or supervised by the lifecycle
+            // manager, so their persisted state stays `working` even after the runtime
+            // dies. Probe the runtime handle: reuse only if it is NOT definitely
+            // missing; otherwise clear the stale metadata and relaunch (mirrors
+            // ensureOrchestratorInternal's enriched get() + restore behavior).
+            const { plugins } = metaProjectContext(name, metaConfig.agent);
+            const aliveOrUncertain = Boolean(existing.runtimeHandle &&
+                plugins.agent &&
+                (await isAgentProcessNotDefinitelyMissing(plugins.agent, existing.runtimeHandle)));
+            if (aliveOrUncertain) {
+                return existing;
+            }
+            deleteMetadata(getMetaSessionsDir(name), name);
+        }
+        return _spawnMetaOrchestratorInner(metaConfig);
+    }
+    async function ensureMetaOrchestrator(metaConfig) {
+        // In-flight dedup keyed by meta name — mirrors ensureOrchestrator, so two
+        // concurrent calls in the same process share one spawn rather than racing.
+        const name = metaConfig.name;
+        const existingPromise = ensureMetaOrchestratorPromises.get(name);
+        if (existingPromise)
+            return existingPromise;
+        const promise = ensureMetaOrchestratorInternal(metaConfig).finally(() => {
+            ensureMetaOrchestratorPromises.delete(name);
+        });
+        ensureMetaOrchestratorPromises.set(name, promise);
+        return promise;
+    }
+    async function _spawnMetaOrchestratorInner(metaConfig) {
+        const name = metaConfig.name;
+        const sessionId = name;
+        const sessionsDir = getMetaSessionsDir(name);
+        const workspacePath = getMetaWorkspaceDir(name);
+        recordActivityEvent({
+            projectId: "_meta",
+            source: "session-manager",
+            kind: "session.spawn_started",
+            summary: "meta orchestrator spawn started",
+            data: { agent: metaConfig.agent ?? undefined, role: "meta-orchestrator" },
+        });
+        const { metaProject, selection, plugins } = metaProjectContext(name, metaConfig.agent);
+        if (!plugins.runtime) {
+            throw new Error(`Runtime plugin '${config.defaults.runtime}' not found`);
+        }
+        if (!plugins.agent) {
+            throw new Error(`Agent plugin '${selection.agentName}' not found`);
+        }
+        mkdirSync(workspacePath, { recursive: true });
+        mkdirSync(sessionsDir, { recursive: true });
+        // Atomic cross-process reservation — mirrors reserveFixedOrchestratorIdentity.
+        // O_EXCL creates the metadata file iff it does not exist, so two concurrent
+        // `meta-start` processes for the same name cannot both proceed to runtime
+        // creation (the loser would otherwise overwrite metadata and orphan the
+        // winner's runtime). On conflict, reuse a live session or reclaim a stale one.
+        if (!reserveSessionId(sessionsDir, sessionId)) {
+            const existing = readExistingMetaSession(name);
+            // Probe the runtime before reusing — mirrors ensureMetaOrchestratorInternal.
+            // _meta sessions are not lifecycle-supervised, so a non-terminal persisted
+            // state can still front a dead runtime; under a truly-concurrent meta-start
+            // race the normal probe/delete in the caller may not have run yet. Reuse only
+            // if NOT definitely missing; otherwise reclaim and relaunch.
+            const aliveOrUncertain = existing &&
+                !isTerminalSession(existing) &&
+                Boolean(existing.runtimeHandle &&
+                    plugins.agent &&
+                    (await isAgentProcessNotDefinitelyMissing(plugins.agent, existing.runtimeHandle)));
+            if (aliveOrUncertain) {
+                return existing;
+            }
+            // Stale, dead, or terminal record left behind — reclaim the id.
+            deleteMetadata(sessionsDir, sessionId);
+            if (!reserveSessionId(sessionsDir, sessionId)) {
+                throw new Error(`Meta orchestrator '${name}' is already being created`);
+            }
+        }
+        const cleanup = async (handle) => {
+            if (handle) {
+                try {
+                    await plugins.runtime.destroy(handle);
+                }
+                catch {
+                    /* best effort */
+                }
+            }
+            try {
+                deleteMetadata(sessionsDir, sessionId);
+            }
+            catch {
+                /* best effort */
+            }
+        };
+        // Install metadata hooks / PATH wrappers so the meta orchestrator can run
+        // `athene` commands autonomously. Mirrors the orchestrator/worker paths.
+        try {
+            if (plugins.agent.setupWorkspaceHooks) {
+                await plugins.agent.setupWorkspaceHooks(workspacePath, { dataDir: sessionsDir });
+            }
+            if (plugins.agent.name !== "claude-code") {
+                await setupPathWrapperWorkspace(workspacePath);
+            }
+        }
+        catch (err) {
+            await cleanup();
+            throw err;
+        }
+        let systemPromptFile;
+        if (metaConfig.systemPrompt) {
+            systemPromptFile = join(workspacePath, `meta-orchestrator-prompt-${sessionId}.md`);
+            writeFileSync(systemPromptFile, metaConfig.systemPrompt, "utf-8");
+            // OpenCode does not consume systemPromptFile — it reads its prompt from a
+            // workspace AGENTS.md. Mirror the per-project orchestrator path so a meta
+            // orchestrator on the opencode agent actually receives its routing prompt.
+            if (plugins.agent.name === "opencode") {
+                writeWorkspaceOpenCodeAgentsMd(workspacePath, systemPromptFile);
+            }
+        }
+        // Meta orchestrator ALWAYS runs permissionless — it must run ao CLI commands.
+        const agentLaunchConfig = {
+            sessionId,
+            projectConfig: {
+                ...metaProject,
+                agentConfig: {
+                    ...selection.agentConfig,
+                    permissions: "permissionless",
+                },
+            },
+            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);
+        }
+        let handle;
+        try {
+            handle = await plugins.runtime.create({
+                sessionId,
+                workspacePath,
+                launchCommand,
+                environment: withLegacyEnvAliases({
+                    ...environment,
+                    PATH: buildAgentPath(environment["PATH"] ?? process.env["PATH"]),
+                    GH_PATH: PREFERRED_GH_PATH,
+                    [ENV.SESSION]: sessionId,
+                    [ENV.DATA_DIR]: sessionsDir,
+                    [ENV.SESSION_NAME]: sessionId,
+                    [ENV.CALLER_TYPE]: "meta-orchestrator",
+                    [ENV.PROJECT_ID]: "_meta",
+                    [ENV.META_NAME]: name,
+                    [ENV.CONFIG_PATH]: config.configPath,
+                    ...(config.port !== undefined &&
+                        config.port !== null && { [ENV.PORT]: String(config.port) }),
+                }),
+            });
+        }
+        catch (err) {
+            await cleanup();
+            throw err;
+        }
+        const createdAt = new Date();
+        const lifecycle = createInitialCanonicalLifecycle("meta-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;
+        const displayName = `${name} (meta)`;
+        const session = {
+            id: sessionId,
+            projectId: "_meta",
+            status: deriveLegacyStatus(lifecycle),
+            activity: "active",
+            activitySignal: createActivitySignal("valid", {
+                activity: "active",
+                timestamp: createdAt,
+                source: "runtime",
+            }),
+            lifecycle,
+            branch: null,
+            issueId: null,
+            pr: null,
+            prs: [],
+            workspacePath,
+            runtimeHandle: handle,
+            agentInfo: null,
+            createdAt,
+            lastActivityAt: createdAt,
+            metadata: {
+                role: "meta-orchestrator",
+                metaName: name,
+                ...(displayName ? { displayName } : {}),
+            },
+        };
+        try {
+            writeMetadata(sessionsDir, sessionId, {
+                worktree: workspacePath,
+                // Meta orchestrators have no git branch (no worktree). Persist an empty
+                // string to satisfy the metadata contract; session.branch stays null.
+                branch: "",
+                status: deriveLegacyStatus(lifecycle),
+                ...buildLifecycleMetadataPatch(lifecycle),
+                // Object overrides for the typed writeMetadata path — see the worker
+                // spawn site for the rationale.
+                lifecycle,
+                role: "meta-orchestrator",
+                project: "_meta",
+                agent: selection.agentName,
+                createdAt: createdAt.toISOString(),
+                runtimeHandle: handle,
+                displayName,
+            });
+            if (plugins.agent.postLaunchSetup) {
+                await plugins.agent.postLaunchSetup(session);
+            }
+            if (plugins.agent.promptDelivery === "post-launch" && metaConfig.systemPrompt) {
+                await plugins.runtime.sendMessage(handle, "Begin.");
+            }
+            if (Object.keys(session.metadata || {}).length > 0) {
+                updateMetadata(sessionsDir, sessionId, session.metadata);
+            }
+            invalidateCache();
+        }
+        catch (err) {
+            await cleanup(handle);
+            throw err;
+        }
+        recordActivityEvent({
+            projectId: "_meta",
+            sessionId,
+            source: "session-manager",
+            kind: "session.spawned",
+            summary: `spawned: ${sessionId}`,
+            data: { agent: plugins.agent.name, role: "meta-orchestrator" },
+        });
+        return session;
+    }
     async function relaunchOrchestratorInternal(orchestratorConfig) {
         const project = config.projects[orchestratorConfig.projectId];
         if (!project) {
@@ -2980,24 +3544,24 @@ function createSessionManager(deps) {
             sessionId: tmuxName ?? sessionId,
             workspacePath,
             launchCommand,
-            environment: {
+            environment: withLegacyEnvAliases({
                 ...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"],
+                ...(getEnvString(ENV.AGENT_GH_TRACE) && {
+                    [ENV.AGENT_GH_TRACE]: getEnvString(ENV.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) }),
-            },
+                [ENV.SESSION]: sessionId,
+                [ENV.DATA_DIR]: sessionsDir,
+                [ENV.SESSION_NAME]: sessionId,
+                ...(tmuxName && { [ENV.TMUX_NAME]: tmuxName }),
+                [ENV.CALLER_TYPE]: "agent",
+                ...(projectId && { [ENV.PROJECT_ID]: projectId }),
+                [ENV.CONFIG_PATH]: config.configPath,
+                ...(config.port !== undefined && config.port !== null && { [ENV.PORT]: String(config.port) }),
+            }),
         });
         // 9. Update metadata — reset lifecycle to working state
         const now = new Date().toISOString();
@@ -3059,6 +3623,7 @@ function createSessionManager(deps) {
         spawn,
         spawnOrchestrator,
         ensureOrchestrator,
+        ensureMetaOrchestrator,
         relaunchOrchestrator,
         restore,
         list,
@@ -3073,5 +3638,5 @@ function createSessionManager(deps) {
     };
 }
 
-export { createSessionManager };
+export { createSessionManager, isSpawnLockReapable, releaseSpawnLockIfOwned };
 //# sourceMappingURL=session-manager.js.map