pantheon-opencode 1.5.0-beta.6 → 1.5.0-beta.8

package/src/pantheon/cost-command.ts

@@ -15,14 +15,19 @@
  *
  * @module cost-command
  */
-import { existsSync } from 'node:fs'
+import { execFile } from 'node:child_process'
+import { accessSync, constants, existsSync, statSync } from 'node:fs'
 import { homedir } from 'node:os'
-import { join } from 'node:path'
+import { delimiter, dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
 import { z } from 'zod'
 
 import type { ToolContextLike } from './delegation.ts'
 import type { NativeTaskStatus } from './native-task-status.ts'
 
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
 /** One aggregated token row (per agent and phase). */
 export interface CostRow {
   agent: string
@@ -37,6 +42,8 @@ export interface CostCommandOptions {
   dbPath?: string
   /** Injectable loader for tests; production always loads node:sqlite. */
   sqliteLoader?: () => Promise<SqliteModule>
+  /** Injectable CLI-fallback process boundary (tests / unusual runtimes). */
+  cliFallback?: CliFallbackDeps
 }
 
 export type OpenCodeVersion = 'v1' | 'v2'
@@ -220,6 +227,230 @@ function renderMarkdown(rows: readonly CostRow[], days: number): string {
   return lines.join('\n')
 }
 
+// ─── CLI fallback: resolve a REAL Node, not the plugin runtime ──────────
+//
+// Under Bun (the runtime that motivates this fallback), process.execPath IS
+// the Bun binary, which has no node:sqlite — so spawning it could never work.
+// Resolve a genuine Node instead: PANTHEON_NODE → `node` on PATH → clear error.
+
+/** First Node release exposing the built-in `node:sqlite` module. */
+const NODE_SQLITE_MIN_VERSION = '22.5'
+
+/** Minimal injectable child-process boundary (tests / unusual runtimes). */
+export type ExecFileLike = (
+  file: string,
+  args: readonly string[],
+) => Promise<{ stdout: string; stderr?: string }>
+
+/** Injectables so the fallback never depends on the real machine in tests. */
+export interface CliFallbackDeps {
+  /** Environment for PANTHEON_NODE / PATH lookup. Default: process.env. */
+  env?: NodeJS.ProcessEnv
+  /** Child-process boundary. Default: node:child_process.execFile. */
+  execFile?: ExecFileLike
+  /** Executable predicate used by the PANTHEON_NODE / PATH lookups. */
+  isExecutable?: (path: string) => boolean
+}
+
+/** A real Node executable located for the CLI fallback. */
+export interface ResolvedNode {
+  path: string
+  source: 'env' | 'path'
+}
+
+type ExecFailure = Error & { stdout?: string; stderr?: string }
+
+function defaultIsExecutable(path: string): boolean {
+  try {
+    accessSync(path, constants.X_OK)
+    return statSync(path).isFile()
+  } catch {
+    return false
+  }
+}
+
+function defaultExecFile(
+  file: string,
+  args: readonly string[],
+): Promise<{ stdout: string; stderr: string }> {
+  return new Promise((resolve, reject) => {
+    execFile(file, [...args], { encoding: 'utf8' }, (error, stdout, stderr) => {
+      if (error) {
+        // execFile's callback error does not always carry the captured output;
+        // attach it so callers can surface cost.mjs's structured {ok:false}.
+        const failure = error as ExecFailure
+        if (typeof failure.stdout !== 'string') failure.stdout = stdout
+        if (typeof failure.stderr !== 'string') failure.stderr = stderr
+        reject(failure)
+        return
+      }
+      resolve({ stdout, stderr })
+    })
+  })
+}
+
+/** Scan PATH (no shell) for a `node` executable. */
+export function resolveNodeFromPath(
+  env: NodeJS.ProcessEnv,
+  isExecutable: (path: string) => boolean = defaultIsExecutable,
+): string | undefined {
+  const pathValue = env.PATH ?? env.Path ?? ''
+  if (pathValue === '') return undefined
+  const isWindows = process.platform === 'win32'
+  const extensions = isWindows
+    ? (env.PATHEXT ?? '.EXE;.CMD;.BAT;.COM').split(';').filter((ext) => ext !== '')
+    : ['']
+  for (const dir of pathValue.split(delimiter)) {
+    if (dir === '') continue
+    for (const ext of extensions) {
+      const candidate = join(dir, `node${ext}`)
+      if (isExecutable(candidate)) return candidate
+    }
+  }
+  return undefined
+}
+
+/**
+ * Resolve a REAL Node.js binary for the CLI fallback.
+ *
+ * Order: PANTHEON_NODE (must exist and be executable — an explicit override
+ * that is unusable fails fast instead of being silently ignored) → `node`
+ * from PATH. Returns undefined only when neither source is available.
+ */
+export function resolveNodeExecutable(
+  env: NodeJS.ProcessEnv = process.env,
+  isExecutable: (path: string) => boolean = defaultIsExecutable,
+): ResolvedNode | undefined {
+  const explicit = env.PANTHEON_NODE
+  if (explicit !== undefined && explicit.trim() !== '') {
+    if (isExecutable(explicit)) return { path: explicit, source: 'env' }
+    throw new Error(
+      `PANTHEON_NODE is set to "${explicit}" but that is not an existing executable file`,
+    )
+  }
+  const fromPath = resolveNodeFromPath(env, isExecutable)
+  return fromPath === undefined ? undefined : { path: fromPath, source: 'path' }
+}
+
+function execErrorMessage(err: unknown): string {
+  if (err instanceof Error) {
+    const failure = err as ExecFailure
+    const stderr = typeof failure.stderr === 'string' ? failure.stderr.trim() : ''
+    if (stderr !== '') return stderr
+    return failure.message
+  }
+  return String(err)
+}
+
+function tryParseJson(text: string): unknown {
+  try {
+    return JSON.parse(text)
+  } catch {
+    return undefined
+  }
+}
+
+function truncateForError(text: string): string {
+  const trimmed = text.trim()
+  return trimmed.length > 200 ? `${trimmed.slice(0, 200)}…` : trimmed
+}
+
+/** Probe the resolved binary for built-in node:sqlite support. */
+async function assertNodeSqliteSupport(
+  nodePath: string,
+  execFileAsync: ExecFileLike,
+): Promise<void> {
+  try {
+    await execFileAsync(nodePath, ['-e', "require('node:sqlite')"])
+  } catch (err: unknown) {
+    throw new Error(
+      `resolved Node binary "${nodePath}" does not support node:sqlite (Node.js >= ${NODE_SQLITE_MIN_VERSION} required): ${execErrorMessage(err)}`,
+    )
+  }
+}
+
+/** Pull the structured failure message cost.mjs prints to stdout (exit 1). */
+function extractScriptFailure(err: unknown): string {
+  const failure = err as { stdout?: unknown; stderr?: unknown }
+  const stdout = typeof failure.stdout === 'string' ? failure.stdout : ''
+  const parsed = tryParseJson(stdout)
+  if (parsed !== null && typeof parsed === 'object') {
+    const record = parsed as { ok?: unknown; error?: unknown }
+    if (record.ok === false && typeof record.error === 'string' && record.error !== '') {
+      return record.error
+    }
+  }
+  const stderr = typeof failure.stderr === 'string' ? failure.stderr.trim() : ''
+  if (stderr !== '') return stderr
+  return execErrorMessage(err)
+}
+
+/**
+ * Spawn `node scripts/cost.mjs` as a CLI fallback when node:sqlite is
+ * unavailable in the plugin process (e.g. Bun runtime). Returns CostRow[] by
+ * parsing the JSON the script writes to stdout.
+ *
+ * Resolves a REAL Node binary (PANTHEON_NODE → PATH): process.execPath under
+ * Bun is the Bun binary, which cannot run node:sqlite. The resolved binary is
+ * probed for node:sqlite support and the script is always run read-only with
+ * an argument array (never a shell).
+ */
+export async function queryWithCliFallback(
+  dbPath: string,
+  days: number,
+  deps?: CliFallbackDeps,
+): Promise<CostRow[]> {
+  const env = deps?.env ?? process.env
+  const execFileAsync = deps?.execFile ?? defaultExecFile
+  const isExecutable = deps?.isExecutable ?? defaultIsExecutable
+
+  const costScript = join(__dirname, '..', '..', 'scripts', 'cost.mjs')
+  if (!existsSync(costScript)) {
+    throw new Error(`CLI fallback script not found: ${costScript}`)
+  }
+
+  const node = resolveNodeExecutable(env, isExecutable)
+  if (node === undefined) {
+    throw new Error(
+      `no Node.js executable found for the node:sqlite CLI fallback: set PANTHEON_NODE to a Node.js >= ${NODE_SQLITE_MIN_VERSION} binary or put "node" on PATH`,
+    )
+  }
+
+  await assertNodeSqliteSupport(node.path, execFileAsync)
+
+  let stdout: string
+  try {
+    ;({ stdout } = await execFileAsync(node.path, [
+      costScript,
+      '--db-path',
+      dbPath,
+      '--days',
+      String(days),
+    ]))
+  } catch (err: unknown) {
+    // cost.mjs sets exitCode=1 (execFile rejects) and writes {ok:false,error}
+    // to stdout before exiting — surface that structured failure.
+    throw new Error(`CLI fallback failed: ${extractScriptFailure(err)}`)
+  }
+
+  const parsed = tryParseJson(stdout)
+  if (parsed === null || typeof parsed !== 'object') {
+    throw new Error(`CLI fallback returned non-JSON output: ${truncateForError(stdout)}`)
+  }
+  const record = parsed as { ok?: unknown; rows?: unknown; error?: unknown }
+  if (record.ok !== true) {
+    const detail =
+      typeof record.error === 'string' && record.error !== ''
+        ? record.error
+        : 'unexpected response shape from scripts/cost.mjs'
+    throw new Error(`CLI fallback failed: ${detail}`)
+  }
+  if (!Array.isArray(record.rows)) {
+    throw new Error('CLI fallback failed: scripts/cost.mjs response is missing the rows array')
+  }
+  return record.rows as CostRow[]
+}
+
 export function createCostCommand(options?: CostCommandOptions): CostCommand {
   const loadSqlite =
     options?.sqliteLoader ?? (async () => (await import('node:sqlite')) as SqliteModule)
@@ -269,7 +500,22 @@ export function createCostCommand(options?: CostCommandOptions): CostCommand {
           `opencode.db not found (expected at ${expected}). No token history is available until opencode has stored session data.`,
         )
       }
-      const sqlite = await loadSqlite()
+      let sqlite: SqliteModule | undefined
+      try {
+        sqlite = await loadSqlite()
+      } catch (loadErr: unknown) {
+        // node:sqlite unavailable (e.g. Bun runtime) — fall back to CLI.
+        const status = statusForError(loadErr)
+        if (status === 'UNSUPPORTED') {
+          try {
+            const rows = await queryWithCliFallback(dbPath, days, options?.cliFallback)
+            return `status: OK\n${renderMarkdown(rows, days)}`
+          } catch (cliErr: unknown) {
+            return failure(statusForError(cliErr), diagnostic(cliErr))
+          }
+        }
+        throw loadErr
+      }
       const rows = await queryWithNodeSqlite(dbPath, days, sqlite)
       return `status: OK\n${renderMarkdown(rows, days)}`
     } catch (err: unknown) {

package/src/pantheon/delegation-finalize.ts

@@ -144,9 +144,25 @@ export interface DelegationOptions {
   promptTimeoutMs?: number
   /** Poll interval used by the bootstrap watchdog. */
   bootstrapPollIntervalMs?: number
+  /**
+   * Max completed jobs to keep per agent after pruning (default: 10).
+   * Matches the native delegate-manager default.
+   */
+  keepCompleted?: number
+  /**
+   * Hard cap on total board entries (default: 50).
+   * Matches the native delegate-manager default.
+   */
+  maxEntries?: number
   /** Injectable clock/sleeper for deterministic watchdog tests. */
   now?: () => number
   sleep?: (ms: number) => Promise<void>
+  /**
+   * Kill-switch: when false, all delegation tools (delegate/read/list) throw
+   * immediately. Mirrors `PANTHEON_DELEGATION=off` from the native manager.
+   * Defaults to true (delegation enabled) when not specified.
+   */
+  delegationEnabled?: boolean
 }
 
 /** Dependencies threaded to the finalize path. */
@@ -370,5 +386,21 @@ export async function finalizeDelegation(
     // Terminal in a DIFFERENT state (e.g. timeout already recorded) — the
     // report above still captures this finalize; the board state stands.
   }
+
+  // P1-1: Delete the auto-wake signal file to prevent leaks. The board
+  // writes .signal.json on every terminal transition, but the legacy path
+  // never called deleteSignal — only the native delegate-manager did.
+  // The consumer (auto-wake.ts consumeWakeSignals) is intentionally NOT
+  // wired in the event hook: finalizeDelegation already handles the
+  // terminal transition, so consuming signals would be redundant and risks
+  // double-processing. deleteSignal on finalize is sufficient.
+  await deps.board.deleteSignal(job.alias)
+
+  // P1-4: Prune old completed jobs and enforce the hard entry cap. The
+  // native delegate-manager called these in settle(), but the legacy
+  // finalize path omitted them, allowing unbounded board growth.
+  await deps.board.pruneCompleted(deps.options.keepCompleted ?? 10)
+  await deps.board.enforceEntryCap(deps.options.maxEntries ?? 50)
+
   return deps.board.get(childSessionID) ?? job
 }

package/src/pantheon/delegation.ts

@@ -61,6 +61,7 @@ import {
 import { finalizeIdleChildrenWithoutMd } from './delegation-notify.ts'
 import { createPantheonLogger } from './logger.ts'
 import { buildAgentListDescription } from './permission-globs.ts'
+import { safeSessionPath } from './session-guard.ts'
 import { buildStopInstruction, cappedSummary, DEFAULT_MAX_STEPS } from './step-cap.ts'
 
 export type {
@@ -96,6 +97,40 @@ function readIntegerEnv(
   return Number.isSafeInteger(value) && value >= minimum ? value : fallback
 }
 
+// ─── B1: unresolved session template guard ─────────────────────────────
+//
+// The TUI/runtime can hand a plugin surface the UNSUBSTITUTED template literal
+// `{sessionID}` (URL-encoded `%7BsessionID%7D`) when no session is focused.
+// Forwarding it to a session API makes the opencode server reject every call
+// (`Expected a string starting with "ses", got "%7BsessionID%7D"`), which the
+// beta.7 E2E recorded at ~1k errors/s. The delegation layer is a defensive
+// choke point too: it is downstream of the plugin adapter in production, but
+// tests, older hosts, and direct embedders can inject a raw client.
+//
+// This guard targets the placeholder ONLY. It is deliberately NOT the full
+// `isValidSessionId` contract: structural test hosts use non-"ses" ids on
+// purpose (delegation-bootstrap.test.ts), and rejecting those would be a
+// behavior change unrelated to this bug. `session-guard.ts` remains the
+// strict choke point for the plugin adapters.
+const UNRESOLVED_SESSION_TEMPLATE = /(?:\{sessionID\}|%7BsessionID%7D)/i
+
+/** True when a session id is an unresolved `{sessionID}` template placeholder. */
+export function isUnresolvedSessionTemplate(id: unknown): boolean {
+  return typeof id === 'string' && UNRESOLVED_SESSION_TEMPLATE.test(id)
+}
+
+/**
+ * Refuse a placeholder session id before it reaches a session API. Returns
+ * true (and logs a clear warning) when the caller must skip the operation.
+ */
+function refuseUnresolvedSessionTemplate(id: unknown, operation: string): boolean {
+  if (!isUnresolvedSessionTemplate(id)) return false
+  log.warn(
+    `[pantheon-delegate] ${operation} skipped: unresolved session template "${String(id)}" — the host did not substitute the session id`,
+  )
+  return true
+}
+
 type BootstrapOutcome =
   | { status: 'started'; elapsedMs: number; reason: string }
   | { status: 'startup_failed' | 'bootstrap_unknown'; elapsedMs: number; reason: string }
@@ -115,6 +150,9 @@ async function promptWithTimeout(
   input: Parameters<DelegationClient['session']['promptAsync']>[0],
   timeoutMs: number,
 ): Promise<PromptOutcome> {
+  if (refuseUnresolvedSessionTemplate(input.path.id, 'promptAsync')) {
+    return { status: 'rejected', reason: `invalid sessionID: ${input.path.id}` }
+  }
   const controller = new AbortController()
   let timer: NodeJS.Timeout | undefined
   const operation = client.session.promptAsync({ ...input, signal: controller.signal }).then(
@@ -190,6 +228,14 @@ async function bootstrapChild(
   const hasStatusAPI = typeof client.session.get === 'function'
   const acceptedRunning = isRunningSession(accepted)
 
+  if (refuseUnresolvedSessionTemplate(childSessionID, 'bootstrap probe')) {
+    return {
+      status: 'bootstrap_unknown',
+      elapsedMs: 0,
+      reason: `invalid child sessionID "${childSessionID}"`,
+    }
+  }
+
   if (!hasMessagesAPI && !hasStatusAPI) {
     return acceptedRunning
       ? {
@@ -403,6 +449,72 @@ function stateLabel(state: BackgroundJobRecord['state']): string {
   }
 }
 
+// ─── B2: session-scoped delegation target resolution ───────────────────
+//
+// Board aliases restart per parent session (apo-1 in every root), so an alias
+// lookup MUST be scoped to the calling session. `pantheon_delegation_read`
+// previously delegated to the board's first-match resolver and, when the id
+// was not found in the current session, the generic "Unknown delegation"
+// message hid the real cause (the alias belonged to another session). This
+// helper makes the scoping explicit and returns a CLEAR error for each
+// cross-session / ambiguous case.
+
+/** Resolution outcome for a delegation read by task ID or alias. */
+export type DelegationTargetResolution =
+  | { kind: 'found'; job: BackgroundJobRecord }
+  | { kind: 'error'; message: string }
+
+/**
+ * Resolve a `pantheon_delegation_read` target with strict session scoping:
+ *   - exact task-ID match first (must belong to `sessionID`);
+ *   - then alias matches WITHIN `sessionID` (exactly one required);
+ *   - an alias that exists only in another session → clear cross-session
+ *     error (never another session's job);
+ *   - two matches in this session → clear ambiguity error.
+ */
+export function resolveDelegationTarget(
+  board: Pick<BackgroundJobBoard, 'list'>,
+  sessionID: string,
+  idOrAlias: string,
+): DelegationTargetResolution {
+  const jobs = board.list()
+
+  const byTaskID = jobs.find((job) => job.taskID === idOrAlias)
+  if (byTaskID !== undefined) {
+    if (byTaskID.parentSessionID === sessionID) return { kind: 'found', job: byTaskID }
+    return {
+      kind: 'error',
+      message:
+        `Delegation "${idOrAlias}" belongs to a different session ` +
+        `(${byTaskID.parentSessionID}) and cannot be read from ${sessionID}.`,
+    }
+  }
+
+  const aliasMatches = jobs.filter((job) => job.alias === idOrAlias)
+  const inSession = aliasMatches.filter((job) => job.parentSessionID === sessionID)
+  if (inSession.length === 1) return { kind: 'found', job: inSession[0]! }
+  if (inSession.length > 1) {
+    return {
+      kind: 'error',
+      message:
+        `Delegation alias "${idOrAlias}" is ambiguous in session ${sessionID} ` +
+        `(${inSession.length} matches); read it by task ID instead.`,
+    }
+  }
+  if (aliasMatches.length > 0) {
+    return {
+      kind: 'error',
+      message:
+        `Delegation alias "${idOrAlias}" belongs to a different session — ` +
+        'aliases are session-scoped. Use pantheon_delegation_list in the session that created it.',
+    }
+  }
+  return {
+    kind: 'error',
+    message: `Unknown delegation "${idOrAlias}" for this session. Use pantheon_delegation_list to see active delegations.`,
+  }
+}
+
 /** Normalize the SDK-provided caller agent without inventing an identity. */
 const normalizeToolAgent = normalizeDelegationAgent
 
@@ -509,6 +621,7 @@ async function sampleChildActivity(
   collector: ActivityCollector,
 ): Promise<void> {
   if (typeof client.session.messages !== 'function') return
+  if (refuseUnresolvedSessionTemplate(childSessionID, 'activity sample')) return
   try {
     const bundles = await client.session.messages({ path: { id: childSessionID } })
     if (!Array.isArray(bundles)) return
@@ -534,6 +647,7 @@ async function lastChildActivity(
   childSessionID: string,
 ): Promise<string | undefined> {
   if (typeof client.session.messages !== 'function') return undefined
+  if (refuseUnresolvedSessionTemplate(childSessionID, 'last activity fetch')) return undefined
   try {
     const bundles = await client.session.messages({ path: { id: childSessionID } })
     if (!Array.isArray(bundles)) return undefined
@@ -740,10 +854,59 @@ export function createDelegationTools(input: CreateDelegationToolsInput): Delega
     return finalizeDelegationReport(deps, childSessionID, opts)
   }
 
+  // Kill-switch gate: when delegationEnabled is explicitly false (mirrors
+  // PANTHEON_DELEGATION=off from the native manager), all legacy tools throw.
+  function guardEnabled(): void {
+    if (options.delegationEnabled === false) {
+      throw new Error('pantheon delegation disabled (PANTHEON_DELEGATION=off)')
+    }
+  }
+
+  /**
+   * Best-effort teardown of a child session whose `registerLaunch` was refused
+   * because the per-agent concurrency limit was hit between the pre-check and
+   * the registration (a race with another concurrent dispatch). Removes every
+   * side effect of the aborted dispatch — known-child marker, read-only
+   * registry entry and any reserved budget slot — then deletes the session when
+   * the host client exposes `session.delete`. Never throws: cleanup must not
+   * mask the original rejection.
+   */
+  async function abortRejectedLaunch(
+    childSessionID: string,
+    wasReadOnly: boolean,
+    refund?: { key: string | undefined; reserved: boolean },
+  ): Promise<void> {
+    knownChildren.delete(childSessionID)
+    if (wasReadOnly) readOnlyRegistry.unregister(childSessionID)
+    if (refund?.reserved && refund.key !== undefined) {
+      budgetUsage.set(refund.key, Math.max(0, (budgetUsage.get(refund.key) ?? 1) - 1))
+    }
+    // The plugin's adapted client (adaptDelegationClient) does not expose
+    // session.delete, and older hosts may not either. Delete best-effort so the
+    // abandoned session is not left behind; the registry cleanup above already
+    // removes the side effects that matter for read-only enforcement.
+    const session = client.session as {
+      delete?: (input: { path: { id: string } }) => Promise<unknown>
+    }
+    if (typeof session.delete !== 'function') return
+    const sessionPath = safeSessionPath(childSessionID)
+    if (sessionPath === null) {
+      log.warn(`[pantheon-delegate] session.delete skipped: invalid sessionID "${childSessionID}"`)
+      return
+    }
+    try {
+      await session.delete(sessionPath)
+    } catch (err: unknown) {
+      const reason = err instanceof Error ? err.message : String(err)
+      log.warn(`[pantheon-delegate] failed to delete orphan session ${childSessionID}: ${reason}`)
+    }
+  }
+
   const pantheon_delegate: DelegationTool<typeof delegateArgs> = {
     description: buildDelegateDescription(options),
     args: delegateArgs,
     execute: async (args, ctx) => {
+      guardEnabled()
       if (!isRootSession(ctx.sessionID)) {
         throw new Error(
           `pantheon_delegate rejected: session ${ctx.sessionID} is a sub-session — only root sessions can delegate`,
@@ -855,6 +1018,18 @@ export function createDelegationTools(input: CreateDelegationToolsInput): Delega
         return `pantheon_delegate failed to create child session: ${reason}`
       }
       const childSessionID = created.id
+      // B1: a host that passes through the unresolved template must never
+      // produce a board job / bootstrap poll — reject it here with a clear
+      // message and refund the reserved budget (no child was started).
+      if (isUnresolvedSessionTemplate(childSessionID)) {
+        if (budgetReserved && budgetKey !== undefined) {
+          budgetUsage.set(budgetKey, Math.max(0, (budgetUsage.get(budgetKey) ?? 1) - 1))
+        }
+        log.warn(
+          `[pantheon-delegate] session.create returned unresolved session template "${childSessionID}" — child ignored`,
+        )
+        return `pantheon_delegate failed: host returned an unresolved child session template ("${childSessionID}"); expected an id starting with "ses".`
+      }
       knownChildren.add(childSessionID)
       options.registerChildSession?.(childSessionID, ctx.sessionID)
 
@@ -871,13 +1046,27 @@ export function createDelegationTools(input: CreateDelegationToolsInput): Delega
         readOnlyRegistry.register(childSessionID, entry)
       }
 
-      const job = await board.registerLaunch({
-        taskID: childSessionID,
-        parentSessionID: ctx.sessionID,
-        agent: args.agent,
-        description: args.description ?? effectivePrompt,
-        objective: effectivePrompt,
-      })
+      let job: BackgroundJobRecord
+      try {
+        job = await board.registerLaunch({
+          taskID: childSessionID,
+          parentSessionID: ctx.sessionID,
+          agent: args.agent,
+          description: args.description ?? effectivePrompt,
+          objective: effectivePrompt,
+        })
+      } catch (err: unknown) {
+        // Concurrency race: another dispatch claimed the last slot after the
+        // pre-check above but before this registration. Undo every side effect
+        // of the aborted dispatch so no orphan session/registry survives, then
+        // surface a clear rejection.
+        const reason = err instanceof Error ? err.message : String(err)
+        await abortRejectedLaunch(childSessionID, readOnly, {
+          key: budgetKey,
+          reserved: budgetReserved,
+        })
+        return `pantheon_delegate rejected: ${reason}`
+      }
 
       // Timeout manager: cleared on finalize, unref'd so the timer never
       // keeps the process alive on its own.
@@ -966,15 +1155,42 @@ export function createDelegationTools(input: CreateDelegationToolsInput): Delega
         return `[STARTUP FAILED] ${bootstrap.status}: ${bootstrap.reason}; retry creation failed: ${reason}`
       }
       const retryID = retry.id
+      if (isUnresolvedSessionTemplate(retryID)) {
+        log.warn(
+          `[pantheon-delegate] retry session.create returned unresolved session template "${retryID}" — retry ignored`,
+        )
+        return `[STARTUP FAILED] ${bootstrap.status}: ${bootstrap.reason}; host returned an unresolved retry session template ("${retryID}")`
+      }
       knownChildren.add(retryID)
       options.registerChildSession?.(retryID, ctx.sessionID)
-      const retryJob = await board.registerLaunch({
-        taskID: retryID,
-        parentSessionID: ctx.sessionID,
-        agent: args.agent,
-        description: args.description ?? effectivePrompt,
-        objective: effectivePrompt,
-      })
+
+      // Phase 4 read-only enforcement for the retry: recalculate readOnly
+      // (same logic as the initial child at :866-872) and register the retry
+      // session so the plugin's tool.execute.before guard enforces it.
+      const retryReadOnly =
+        args.read_only === true || (options.readOnlyAgents?.has(args.agent.toLowerCase()) ?? false)
+      if (retryReadOnly) {
+        const entry: { agent: string; readOnlyFlag?: boolean } = { agent: args.agent }
+        if (args.read_only !== undefined) entry.readOnlyFlag = args.read_only
+        readOnlyRegistry.register(retryID, entry)
+      }
+
+      let retryJob: BackgroundJobRecord
+      try {
+        retryJob = await board.registerLaunch({
+          taskID: retryID,
+          parentSessionID: ctx.sessionID,
+          agent: args.agent,
+          description: args.description ?? effectivePrompt,
+          objective: effectivePrompt,
+        })
+      } catch (err: unknown) {
+        // Same race as the initial child: the retry registration can be
+        // refused. Clean up the retry session + registry entry before failing.
+        const reason = err instanceof Error ? err.message : String(err)
+        await abortRejectedLaunch(retryID, retryReadOnly)
+        return `pantheon_delegate rejected: ${reason} (retry)`
+      }
       const retryTimer = setTimeout(() => {
         timers.delete(retryID)
         void finalize(retryID, {
@@ -1035,10 +1251,10 @@ export function createDelegationTools(input: CreateDelegationToolsInput): Delega
       'Resolves by alias or task ID.',
     args: readArgs,
     execute: async (args, ctx) => {
-      const job = board.resolve(ctx.sessionID, args.id)
-      if (!job) {
-        return `Unknown delegation "${args.id}" for this session. Use pantheon_delegation_list to see active delegations.`
-      }
+      guardEnabled()
+      const resolution = resolveDelegationTarget(board, ctx.sessionID, args.id)
+      if (resolution.kind === 'error') return resolution.message
+      const job = resolution.job
 
       // Sample the child's messages while waiting so the caller sees what the
       // agent is doing — fail-open: no messages support → report as before.
@@ -1093,6 +1309,7 @@ export function createDelegationTools(input: CreateDelegationToolsInput): Delega
       'List background delegations for the current session, with [unread] for finished jobs.',
     args: listArgs,
     execute: async (_args, ctx) => {
+      guardEnabled()
       const jobs = board.list(ctx.sessionID)
       if (jobs.length === 0) return 'No background delegations for this session.'