@wpro-eng/opencode-config 1.0.2 → 1.1.2

package/plugin/wpromote-orchestration.ts

@@ -0,0 +1,1385 @@
+import { tool, type Plugin } from "@opencode-ai/plugin"
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs"
+import { spawnSync } from "node:child_process"
+import { join } from "node:path"
+import { homedir } from "node:os"
+import { parse as parseJsonc } from "jsonc-parser"
+
+type ProviderMode = "copilot" | "native"
+type TaskStatus = "queued" | "running" | "retrying" | "completed" | "failed" | "stopped"
+type TmuxLayout = "main-horizontal" | "main-vertical" | "tiled" | "even-horizontal" | "even-vertical"
+type TmuxState = "disabled" | "queued" | "attached" | "failed"
+
+interface OrchestrationConfig {
+  providerMode: ProviderMode
+  features: {
+    delegation: boolean
+    diagnostics: boolean
+    lookAt: boolean
+    continuousLoop: boolean
+    selfHealing: boolean
+  }
+  limits: {
+    maxConcurrent: number
+    maxRetries: number
+    maxIterations: number
+    retryBackoffMs: number
+    taskTimeoutMs: number
+  }
+  runtimeFallback: {
+    enabled: boolean
+    retryOnErrors: number[]
+    maxFallbackAttempts: number
+    cooldownSeconds: number
+    timeoutSeconds: number
+    notifyOnFallback: boolean
+    providerOrder: ProviderMode[]
+  }
+  hooks: {
+    disabled: string[]
+    telemetry: boolean
+  }
+  notifications: {
+    enabled: boolean
+    maxItems: number
+  }
+  categories: {
+    routing: Record<string, ProviderMode>
+    maxConcurrent: Record<string, number>
+  }
+  recovery: {
+    autoResumeOnStart: boolean
+  }
+  tmux: {
+    enabled: boolean
+    layout: TmuxLayout
+    mainPaneSize: number
+    mainPaneMinWidth: number
+    agentPaneMinWidth: number
+    sessionPrefix: string
+  }
+}
+
+interface ConfigLoadResult {
+  source: string
+  config: OrchestrationConfig
+}
+
+interface TaskRecord {
+  id: string
+  sessionID: string
+  title: string
+  agent: string
+  category: string | null
+  status: TaskStatus
+  createdAt: string
+  updatedAt: string
+  backgroundTaskID: string | null
+  retries: number
+  fallbackAttempts: number
+  details: string
+  fallbackReason: string | null
+  blockedBy: string[]
+  blocks: string[]
+  tmuxPaneID: string | null
+  tmuxSessionName: string | null
+  tmuxState: TmuxState
+}
+
+interface SessionState {
+  loopEnabled: boolean
+  tmuxMissingWarned: boolean
+  telemetry: {
+    created: number
+    resumed: number
+    completed: number
+    failed: number
+    retrying: number
+    stopped: number
+    timedOut: number
+  }
+  notifications: {
+    ts: string
+    level: "info" | "warn" | "error"
+    message: string
+    taskID: string
+  }[]
+  deferredTmuxQueue: string[]
+}
+
+const USER_HOME = process.env.HOME && process.env.HOME.trim().length > 0 ? process.env.HOME : homedir()
+const TASK_STORAGE_DIR = join(USER_HOME, ".cache", "opencode", "wpromote-config", "orchestration-tasks")
+
+const DEFAULT_CONFIG: OrchestrationConfig = {
+  providerMode: "copilot",
+  features: {
+    delegation: true,
+    diagnostics: true,
+    lookAt: true,
+    continuousLoop: true,
+    selfHealing: true,
+  },
+  limits: {
+    maxConcurrent: 3,
+    maxRetries: 2,
+    maxIterations: 25,
+    retryBackoffMs: 1500,
+    taskTimeoutMs: 120000,
+  },
+  runtimeFallback: {
+    enabled: true,
+    retryOnErrors: [400, 401, 403, 408, 429, 500, 502, 503, 504, 529],
+    maxFallbackAttempts: 2,
+    cooldownSeconds: 30,
+    timeoutSeconds: 30,
+    notifyOnFallback: true,
+    providerOrder: ["copilot", "native"],
+  },
+  hooks: {
+    disabled: [],
+    telemetry: true,
+  },
+  notifications: {
+    enabled: true,
+    maxItems: 100,
+  },
+  categories: {
+    routing: {},
+    maxConcurrent: {},
+  },
+  recovery: {
+    autoResumeOnStart: true,
+  },
+  tmux: {
+    enabled: false,
+    layout: "main-vertical",
+    mainPaneSize: 60,
+    mainPaneMinWidth: 120,
+    agentPaneMinWidth: 40,
+    sessionPrefix: "wpo",
+  },
+}
+
+const sessionStates = new Map<string, SessionState>()
+const taskRecords = new Map<string, TaskRecord>()
+const taskByCallID = new Map<string, string>()
+
+function getSessionState(sessionID: string): SessionState {
+  const existing = sessionStates.get(sessionID)
+  if (existing) return existing
+
+  const state: SessionState = {
+    loopEnabled: false,
+    tmuxMissingWarned: false,
+    telemetry: {
+      created: 0,
+      resumed: 0,
+      completed: 0,
+      failed: 0,
+      retrying: 0,
+      stopped: 0,
+      timedOut: 0,
+    },
+    notifications: [],
+    deferredTmuxQueue: [],
+  }
+  sessionStates.set(sessionID, state)
+  return state
+}
+
+function nowIso(): string {
+  return new Date().toISOString()
+}
+
+function isoToMs(value: string): number {
+  const stamp = Date.parse(value)
+  return Number.isNaN(stamp) ? 0 : stamp
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null
+}
+
+function asString(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined
+  const trimmed = value.trim()
+  return trimmed.length > 0 ? trimmed : undefined
+}
+
+function parseProviderMode(value: unknown): ProviderMode {
+  return value === "native" ? "native" : "copilot"
+}
+
+function parseProviderOrder(value: unknown): ProviderMode[] {
+  if (!Array.isArray(value)) return DEFAULT_CONFIG.runtimeFallback.providerOrder
+  const parsed: ProviderMode[] = []
+  for (const item of value) {
+    if (item === "copilot" || item === "native") {
+      if (!parsed.includes(item)) parsed.push(item)
+    }
+  }
+  return parsed.length > 0 ? parsed : DEFAULT_CONFIG.runtimeFallback.providerOrder
+}
+
+function parseRetryOnErrors(value: unknown): number[] {
+  if (!Array.isArray(value)) return DEFAULT_CONFIG.runtimeFallback.retryOnErrors
+  const parsed = value
+    .filter((item): item is number => typeof item === "number" && Number.isInteger(item) && item >= 100 && item <= 599)
+    .sort((a, b) => a - b)
+  return parsed.length > 0 ? parsed : DEFAULT_CONFIG.runtimeFallback.retryOnErrors
+}
+
+function parseDisabledHooks(value: unknown): string[] {
+  if (!Array.isArray(value)) return []
+  return value.filter((item): item is string => typeof item === "string" && item.trim().length > 0)
+}
+
+function normalizeCategoryName(value: string): string {
+  return value.trim().toLowerCase()
+}
+
+function parseCategoryRouting(value: unknown): Record<string, ProviderMode> {
+  if (!isRecord(value)) return {}
+  const parsed: Record<string, ProviderMode> = {}
+  for (const [rawKey, rawValue] of Object.entries(value)) {
+    const key = normalizeCategoryName(rawKey)
+    if (!key) continue
+    if (rawValue === "copilot" || rawValue === "native") {
+      parsed[key] = rawValue
+    }
+  }
+  return parsed
+}
+
+function parseCategoryConcurrency(value: unknown): Record<string, number> {
+  if (!isRecord(value)) return {}
+  const parsed: Record<string, number> = {}
+  for (const [rawKey, rawValue] of Object.entries(value)) {
+    const key = normalizeCategoryName(rawKey)
+    if (!key) continue
+    if (typeof rawValue !== "number" || !Number.isInteger(rawValue)) continue
+    if (rawValue < 1 || rawValue > 10) continue
+    parsed[key] = rawValue
+  }
+  return parsed
+}
+
+function parseTmuxLayout(value: unknown): TmuxLayout {
+  if (
+    value === "main-horizontal" ||
+    value === "main-vertical" ||
+    value === "tiled" ||
+    value === "even-horizontal" ||
+    value === "even-vertical"
+  ) {
+    return value
+  }
+  return DEFAULT_CONFIG.tmux.layout
+}
+
+function parseSessionPrefix(value: unknown): string {
+  if (typeof value !== "string") return DEFAULT_CONFIG.tmux.sessionPrefix
+  const trimmed = value.trim()
+  if (!/^[a-zA-Z0-9_-]{2,20}$/.test(trimmed)) return DEFAULT_CONFIG.tmux.sessionPrefix
+  return trimmed
+}
+
+function parseBoundedInt(value: unknown, fallback: number, min: number, max: number): number {
+  if (typeof value !== "number" || !Number.isInteger(value)) return fallback
+  return Math.max(min, Math.min(max, value))
+}
+
+function isHookEnabled(config: OrchestrationConfig, hookName: string): boolean {
+  return !config.hooks.disabled.includes(hookName)
+}
+
+function getConfigPaths(): string[] {
+  const filenames = ["wpromote.json", "wpromote.jsonc"]
+  return [
+    ...filenames.map((filename) => join(process.cwd(), ".opencode", filename)),
+    ...filenames.map((filename) => join(USER_HOME, ".config", "opencode", filename)),
+  ]
+}
+
+function parseConfigFromFile(): ConfigLoadResult {
+  const configPaths = getConfigPaths()
+
+  for (const configPath of configPaths) {
+    if (!existsSync(configPath)) continue
+
+    try {
+      const parseErrors: Parameters<typeof parseJsonc>[1] = []
+      const raw = parseJsonc(readFileSync(configPath, "utf-8"), parseErrors, {
+        disallowComments: false,
+        allowTrailingComma: true,
+      }) as unknown
+      if (parseErrors.length > 0) continue
+      if (!isRecord(raw)) continue
+      const orchestration = raw.orchestration
+      if (!isRecord(orchestration)) continue
+
+      const features = isRecord(orchestration.features) ? orchestration.features : {}
+      const limits = isRecord(orchestration.limits) ? orchestration.limits : {}
+      const runtimeFallback = isRecord(orchestration.runtimeFallback) ? orchestration.runtimeFallback : {}
+      const hooks = isRecord(orchestration.hooks) ? orchestration.hooks : {}
+      const notifications = isRecord(orchestration.notifications) ? orchestration.notifications : {}
+      const categories = isRecord(orchestration.categories) ? orchestration.categories : {}
+      const recovery = isRecord(orchestration.recovery) ? orchestration.recovery : {}
+      const tmux = isRecord(orchestration.tmux) ? orchestration.tmux : {}
+
+      return {
+        source: configPath,
+        config: {
+          providerMode: parseProviderMode(orchestration.providerMode),
+          features: {
+            delegation: features.delegation !== false,
+            diagnostics: features.diagnostics !== false,
+            lookAt: features.lookAt !== false,
+            continuousLoop: features.continuousLoop !== false,
+            selfHealing: features.selfHealing !== false,
+          },
+          limits: {
+            maxConcurrent: typeof limits.maxConcurrent === "number" ? limits.maxConcurrent : DEFAULT_CONFIG.limits.maxConcurrent,
+            maxRetries: typeof limits.maxRetries === "number" ? limits.maxRetries : DEFAULT_CONFIG.limits.maxRetries,
+            maxIterations: typeof limits.maxIterations === "number" ? limits.maxIterations : DEFAULT_CONFIG.limits.maxIterations,
+            retryBackoffMs: typeof limits.retryBackoffMs === "number" ? limits.retryBackoffMs : DEFAULT_CONFIG.limits.retryBackoffMs,
+            taskTimeoutMs: typeof limits.taskTimeoutMs === "number" ? limits.taskTimeoutMs : DEFAULT_CONFIG.limits.taskTimeoutMs,
+          },
+          runtimeFallback: {
+            enabled: runtimeFallback.enabled !== false,
+            retryOnErrors: parseRetryOnErrors(runtimeFallback.retryOnErrors),
+            maxFallbackAttempts:
+              typeof runtimeFallback.maxFallbackAttempts === "number"
+                ? runtimeFallback.maxFallbackAttempts
+                : DEFAULT_CONFIG.runtimeFallback.maxFallbackAttempts,
+            cooldownSeconds:
+              typeof runtimeFallback.cooldownSeconds === "number"
+                ? runtimeFallback.cooldownSeconds
+                : DEFAULT_CONFIG.runtimeFallback.cooldownSeconds,
+            timeoutSeconds:
+              typeof runtimeFallback.timeoutSeconds === "number"
+                ? runtimeFallback.timeoutSeconds
+                : DEFAULT_CONFIG.runtimeFallback.timeoutSeconds,
+            notifyOnFallback: runtimeFallback.notifyOnFallback !== false,
+            providerOrder: parseProviderOrder(runtimeFallback.providerOrder),
+          },
+          hooks: {
+            disabled: parseDisabledHooks(hooks.disabled),
+            telemetry: hooks.telemetry !== false,
+          },
+          notifications: {
+            enabled: notifications.enabled !== false,
+            maxItems:
+              typeof notifications.maxItems === "number"
+                ? notifications.maxItems
+                : DEFAULT_CONFIG.notifications.maxItems,
+          },
+          categories: {
+            routing: parseCategoryRouting(categories.routing),
+            maxConcurrent: parseCategoryConcurrency(categories.maxConcurrent),
+          },
+          recovery: {
+            autoResumeOnStart: recovery.autoResumeOnStart !== false,
+          },
+          tmux: {
+            enabled: tmux.enabled === true,
+            layout: parseTmuxLayout(tmux.layout),
+            mainPaneSize: parseBoundedInt(tmux.mainPaneSize, DEFAULT_CONFIG.tmux.mainPaneSize, 20, 80),
+            mainPaneMinWidth: parseBoundedInt(tmux.mainPaneMinWidth, DEFAULT_CONFIG.tmux.mainPaneMinWidth, 40, 400),
+            agentPaneMinWidth: parseBoundedInt(
+              tmux.agentPaneMinWidth,
+              DEFAULT_CONFIG.tmux.agentPaneMinWidth,
+              20,
+              200,
+            ),
+            sessionPrefix: parseSessionPrefix(tmux.sessionPrefix),
+          },
+        },
+      }
+    } catch {
+      continue
+    }
+  }
+
+  return {
+    source: "defaults",
+    config: DEFAULT_CONFIG,
+  }
+}
+
+function parseTaskInfo(args: unknown): { title: string; agent: string; category: string | null; details: string } {
+  if (!isRecord(args)) {
+    return {
+      title: "untitled-task",
+      agent: "category:unspecified",
+      category: null,
+      details: "No task arguments available",
+    }
+  }
+
+  const description = asString(args.description) ?? "untitled-task"
+  const category = asString(args.category)
+  const normalizedCategory = category ? normalizeCategoryName(category) : null
+  const subagentType = asString(args.subagent_type)
+  const agent = normalizedCategory ? `category:${normalizedCategory}` : subagentType ? `agent:${subagentType}` : "category:unspecified"
+
+  const details = [
+    `description=${description}`,
+    normalizedCategory ? `category=${normalizedCategory}` : null,
+    subagentType ? `subagent_type=${subagentType}` : null,
+  ]
+    .filter((value): value is string => value !== null)
+    .join(" ")
+
+  return {
+    title: description.length > 48 ? `${description.slice(0, 45)}...` : description,
+    agent,
+    category: normalizedCategory,
+    details,
+  }
+}
+
+function parseTaskDependencies(args: unknown): { blockedBy: string[]; blocks: string[] } {
+  if (!isRecord(args)) return { blockedBy: [], blocks: [] }
+  const blockedBy = Array.isArray(args.blockedBy)
+    ? args.blockedBy.filter((value): value is string => typeof value === "string" && value.trim().length > 0)
+    : []
+  const blocks = Array.isArray(args.blocks)
+    ? args.blocks.filter((value): value is string => typeof value === "string" && value.trim().length > 0)
+    : []
+  return { blockedBy, blocks }
+}
+
+function getTasksForSession(sessionID: string): TaskRecord[] {
+  hydrateSessionTasks(sessionID)
+  const result: TaskRecord[] = []
+  for (const record of taskRecords.values()) {
+    if (record.sessionID === sessionID) result.push(record)
+  }
+  return result.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt))
+}
+
+function getSessionTaskFile(sessionID: string): string {
+  return join(TASK_STORAGE_DIR, `${sessionID}.json`)
+}
+
+function extractCategoryFromAgent(agent: string): string | null {
+  if (!agent.startsWith("category:")) return null
+  const raw = agent.slice("category:".length).trim()
+  if (!raw || raw === "unspecified") return null
+  return normalizeCategoryName(raw)
+}
+
+function resolveTaskProvider(config: OrchestrationConfig, category: string | null): ProviderMode {
+  if (!category) return config.providerMode
+  return config.categories.routing[category] ?? config.providerMode
+}
+
+function getCategoryConcurrencyLimit(config: OrchestrationConfig, category: string | null): number {
+  if (!category) return config.limits.maxConcurrent
+  return config.categories.maxConcurrent[category] ?? config.limits.maxConcurrent
+}
+
+function isActiveTaskStatus(status: TaskStatus): boolean {
+  return status === "running" || status === "retrying" || status === "queued"
+}
+
+function countActiveTasks(sessionID: string): number {
+  return getTasksForSession(sessionID).filter((record) => isActiveTaskStatus(record.status)).length
+}
+
+function countActiveTasksByCategory(sessionID: string, category: string | null): number {
+  if (!category) return countActiveTasks(sessionID)
+  return getTasksForSession(sessionID).filter((record) => record.category === category && isActiveTaskStatus(record.status)).length
+}
+
+function safeTaskRecord(value: unknown): TaskRecord | null {
+  if (!isRecord(value)) return null
+  const id = asString(value.id)
+  const sessionID = asString(value.sessionID)
+  const title = asString(value.title)
+  const agent = asString(value.agent)
+  const categoryRaw = value.category
+  const categoryFromField = typeof categoryRaw === "string" ? normalizeCategoryName(categoryRaw) : null
+  const status = asString(value.status)
+  const createdAt = asString(value.createdAt)
+  const updatedAt = asString(value.updatedAt)
+  const backgroundTaskID = value.backgroundTaskID === null ? null : asString(value.backgroundTaskID) ?? null
+  const retries = typeof value.retries === "number" ? value.retries : 0
+  const fallbackAttempts = typeof value.fallbackAttempts === "number" ? value.fallbackAttempts : 0
+  const details = asString(value.details)
+  const fallbackReason = value.fallbackReason === null ? null : asString(value.fallbackReason) ?? null
+  const blockedBy = Array.isArray(value.blockedBy)
+    ? value.blockedBy.filter((item): item is string => typeof item === "string")
+    : []
+  const blocks = Array.isArray(value.blocks)
+    ? value.blocks.filter((item): item is string => typeof item === "string")
+    : []
+  const tmuxPaneID = value.tmuxPaneID === null ? null : asString(value.tmuxPaneID) ?? null
+  const tmuxSessionName = value.tmuxSessionName === null ? null : asString(value.tmuxSessionName) ?? null
+  const tmuxState = asString(value.tmuxState)
+
+  const validTmuxState =
+    tmuxState === "disabled" || tmuxState === "queued" || tmuxState === "attached" || tmuxState === "failed"
+
+  const validStatus =
+    status === "queued" ||
+    status === "running" ||
+    status === "retrying" ||
+    status === "completed" ||
+    status === "failed" ||
+    status === "stopped"
+
+  if (!id || !sessionID || !title || !agent || !validStatus || !createdAt || !updatedAt || !details) {
+    return null
+  }
+
+  return {
+    id,
+    sessionID,
+    title,
+    agent,
+    category: categoryFromField ?? extractCategoryFromAgent(agent),
+    status,
+    createdAt,
+    updatedAt,
+    backgroundTaskID,
+    retries,
+    fallbackAttempts,
+    details,
+    fallbackReason,
+    blockedBy,
+    blocks,
+    tmuxPaneID,
+    tmuxSessionName,
+    tmuxState: validTmuxState ? tmuxState : "disabled",
+  }
+}
+
+function hydrateSessionTasks(sessionID: string): void {
+  const filePath = getSessionTaskFile(sessionID)
+  if (!existsSync(filePath)) return
+
+  try {
+    const parsed = JSON.parse(readFileSync(filePath, "utf-8")) as unknown
+    if (!Array.isArray(parsed)) return
+    for (const entry of parsed) {
+      const record = safeTaskRecord(entry)
+      if (!record) continue
+      if (!taskRecords.has(record.id)) {
+        taskRecords.set(record.id, record)
+      }
+    }
+  } catch {
+    return
+  }
+}
+
+function persistSessionTasks(sessionID: string): void {
+  const tasks = [...taskRecords.values()]
+    .filter((record) => record.sessionID === sessionID)
+    .sort((a, b) => a.createdAt.localeCompare(b.createdAt))
+
+  mkdirSync(TASK_STORAGE_DIR, { recursive: true })
+  writeFileSync(getSessionTaskFile(sessionID), JSON.stringify(tasks, null, 2))
+}
+
+function pushNotification(
+  sessionID: string,
+  level: "info" | "warn" | "error",
+  message: string,
+  taskID: string
+): void {
+  const config = parseConfigFromFile().config
+  if (!config.notifications.enabled) return
+
+  const state = getSessionState(sessionID)
+  state.notifications.unshift({
+    ts: nowIso(),
+    level,
+    message,
+    taskID,
+  })
+
+  if (state.notifications.length > config.notifications.maxItems) {
+    state.notifications = state.notifications.slice(0, config.notifications.maxItems)
+  }
+}
+
+function notifyTmuxMissingOnce(sessionID: string): void {
+  const state = getSessionState(sessionID)
+  if (state.tmuxMissingWarned) return
+  state.tmuxMissingWarned = true
+  pushNotification(sessionID, "warn", "Tmux integration disabled for this session because tmux is not installed or not on PATH", "tmux")
+}
+
+function getPersistedTaskCount(): number {
+  if (!existsSync(TASK_STORAGE_DIR)) return 0
+  let total = 0
+  for (const file of readdirSync(TASK_STORAGE_DIR)) {
+    if (!file.endsWith(".json")) continue
+    const sessionID = file.replace(/\.json$/, "")
+    hydrateSessionTasks(sessionID)
+  }
+  for (const _ of taskRecords.values()) {
+    total += 1
+  }
+  return total
+}
+
+function recoverPersistedTasks(config: OrchestrationConfig): void {
+  if (!config.recovery.autoResumeOnStart) return
+  if (!existsSync(TASK_STORAGE_DIR)) return
+
+  for (const file of readdirSync(TASK_STORAGE_DIR)) {
+    if (!file.endsWith(".json")) continue
+    const sessionID = file.replace(/\.json$/, "")
+    const state = getSessionState(sessionID)
+    const tasks = getTasksForSession(sessionID)
+    let recovered = 0
+
+    for (const record of tasks) {
+      if (!isActiveTaskStatus(record.status)) continue
+      record.status = "queued"
+      record.updatedAt = nowIso()
+      record.details = "Recovered after restart; pending re-dispatch"
+      record.tmuxPaneID = null
+      record.tmuxSessionName = null
+      record.tmuxState = "disabled"
+      recovered += 1
+    }
+
+    if (recovered === 0) continue
+    state.telemetry.resumed += recovered
+    persistSessionTasks(sessionID)
+    pushNotification(sessionID, "info", `Recovered ${recovered} task(s) after restart`, "resume")
+  }
+}
+
+function createTaskRecord(sessionID: string, title: string, agent: string, category: string | null, details: string): TaskRecord {
+  const id = `tsk_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`
+  const stamp = nowIso()
+  const record: TaskRecord = {
+    id,
+    sessionID,
+    title,
+    agent,
+    category,
+    status: "running",
+    createdAt: stamp,
+    updatedAt: stamp,
+    backgroundTaskID: null,
+    retries: 0,
+    fallbackAttempts: 0,
+    details,
+    fallbackReason: null,
+    blockedBy: [],
+    blocks: [],
+    tmuxPaneID: null,
+    tmuxSessionName: null,
+    tmuxState: "disabled",
+  }
+  taskRecords.set(id, record)
+  persistSessionTasks(sessionID)
+  const config = parseConfigFromFile().config
+  if (config.hooks.telemetry) {
+    const state = getSessionState(sessionID)
+    state.telemetry.created += 1
+  }
+  return record
+}
+
+function enforceTaskTimeouts(sessionID: string, config: OrchestrationConfig): number {
+  const now = Date.now()
+  let timedOut = 0
+  for (const record of getTasksForSession(sessionID)) {
+    const isActive = record.status === "running" || record.status === "retrying" || record.status === "queued"
+    if (!isActive) continue
+    const ageMs = now - isoToMs(record.updatedAt)
+    if (ageMs > config.limits.taskTimeoutMs) {
+      setTaskStatus(record, "failed", `Timed out after ${config.limits.taskTimeoutMs}ms without progress`)
+      timedOut += 1
+    }
+  }
+  return timedOut
+}
+
+function setTaskStatus(record: TaskRecord, status: TaskStatus, details?: string): void {
+  const previousStatus = record.status
+  record.status = status
+  record.updatedAt = nowIso()
+  if (details) record.details = details
+  persistSessionTasks(record.sessionID)
+
+  const config = parseConfigFromFile().config
+  if (previousStatus === status) return
+
+  if (config.hooks.telemetry) {
+    const telemetry = getSessionState(record.sessionID).telemetry
+    if (status === "completed") telemetry.completed += 1
+    if (status === "failed") {
+      telemetry.failed += 1
+      if ((details ?? "").toLowerCase().includes("timed out")) telemetry.timedOut += 1
+    }
+    if (status === "retrying") telemetry.retrying += 1
+    if (status === "stopped") telemetry.stopped += 1
+  }
+
+  if (status === "completed") {
+    pushNotification(record.sessionID, "info", `Task completed: ${record.title}`, record.id)
+  }
+  if (status === "retrying") {
+    if (config.runtimeFallback.notifyOnFallback) {
+      pushNotification(record.sessionID, "warn", `Task retrying: ${record.title}`, record.id)
+    }
+  }
+  if (status === "failed") {
+    pushNotification(record.sessionID, "error", `Task failed: ${record.title}`, record.id)
+  }
+  if (status === "stopped") {
+    pushNotification(record.sessionID, "warn", `Task stopped: ${record.title}`, record.id)
+  }
+}
+
+function extractBackgroundTaskID(output: string): string | null {
+  const match = output.match(/Task ID:\s*([a-zA-Z0-9_-]+)/)
+  return match ? match[1] : null
+}
+
+function extractHttpStatus(output: string): number | null {
+  const match = output.match(/\b(4\d\d|5\d\d)\b/)
+  if (!match) return null
+  const code = Number.parseInt(match[1], 10)
+  return Number.isNaN(code) ? null : code
+}
+
+function classifyFailure(output: string): { code: number | null; reason: string } {
+  const lowered = output.toLowerCase()
+  const statusCode = extractHttpStatus(output)
+  if (statusCode !== null) return { code: statusCode, reason: `http-${statusCode}` }
+  if (lowered.includes("timeout") || lowered.includes("timed out")) return { code: 408, reason: "timeout" }
+  if (lowered.includes("rate limit") || lowered.includes("too many requests")) return { code: 429, reason: "rate-limit" }
+  if (lowered.includes("api key") || lowered.includes("credential")) return { code: 401, reason: "credential" }
+  if (lowered.includes("failed")) return { code: 500, reason: "failed" }
+  return { code: null, reason: "unknown" }
+}
+
+function getNextProvider(config: OrchestrationConfig, current: ProviderMode): ProviderMode | null {
+  const order = config.runtimeFallback.providerOrder
+  const index = order.indexOf(current)
+  if (index < 0 || index + 1 >= order.length) return null
+  return order[index + 1]
+}
+
+function hasTmuxBinary(): boolean {
+  const probe = spawnSync("tmux", ["-V"], { encoding: "utf-8" })
+  return probe.status === 0
+}
+
+function isInsideTmux(): boolean {
+  return typeof process.env.TMUX === "string" && process.env.TMUX.length > 0
+}
+
+function runTmux(args: string[]): { ok: boolean; stdout: string; stderr: string } {
+  const result = spawnSync("tmux", args, { encoding: "utf-8" })
+  return {
+    ok: result.status === 0,
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? "",
+  }
+}
+
+function normalizeTaskToken(value: string): string {
+  return value.toLowerCase().replace(/[^a-z0-9_-]/g, "-").slice(0, 18)
+}
+
+function getTmuxSessionName(config: OrchestrationConfig, record: TaskRecord): string {
+  const prefix = normalizeTaskToken(config.tmux.sessionPrefix)
+  const token = normalizeTaskToken(record.id)
+  return `${prefix}-${token}`
+}
+
+function getSplitDirection(layout: TmuxLayout): "-h" | "-v" {
+  return layout === "main-horizontal" ? "-v" : "-h"
+}
+
+function applyTmuxLayout(config: OrchestrationConfig): void {
+  runTmux(["select-layout", config.tmux.layout])
+  if (config.tmux.layout === "main-horizontal") {
+    runTmux(["set-window-option", "main-pane-height", `${config.tmux.mainPaneSize}%`])
+  }
+  if (config.tmux.layout === "main-vertical") {
+    runTmux(["set-window-option", "main-pane-width", `${config.tmux.mainPaneSize}%`])
+  }
+}
+
+function getWindowStats(): { width: number; height: number; paneCount: number } {
+  const info = runTmux(["display-message", "-p", "#{window_width},#{window_height},#{window_panes}"])
+  if (!info.ok) return { width: 0, height: 0, paneCount: 0 }
+  const [widthStr, heightStr, paneCountStr] = info.stdout.trim().split(",")
+  return {
+    width: Number.parseInt(widthStr ?? "0", 10) || 0,
+    height: Number.parseInt(heightStr ?? "0", 10) || 0,
+    paneCount: Number.parseInt(paneCountStr ?? "0", 10) || 0,
+  }
+}
+
+function estimateMaxAgentPanes(config: OrchestrationConfig): number {
+  const stats = getWindowStats()
+  if (stats.width <= 0 || stats.height <= 0) return 0
+  const divider = 1
+  const desiredMainWidth = Math.floor((stats.width - divider) * (config.tmux.mainPaneSize / 100))
+  const mainWidth = Math.max(config.tmux.mainPaneMinWidth, desiredMainWidth)
+  const rightWidth = Math.max(0, stats.width - mainWidth - divider)
+  if (rightWidth <= 0) return 0
+  const columns = Math.max(1, Math.floor((rightWidth + divider) / (config.tmux.agentPaneMinWidth + divider)))
+  const rows = Math.max(1, Math.floor((stats.height + divider) / (11 + divider)))
+  return columns * rows
+}
+
+function attachTaskPane(record: TaskRecord, config: OrchestrationConfig): { attached: boolean; reason: string } {
+  if (!config.tmux.enabled) {
+    record.tmuxState = "disabled"
+    record.tmuxPaneID = null
+    record.tmuxSessionName = null
+    return { attached: false, reason: "tmux disabled" }
+  }
+  if (!isInsideTmux()) {
+    record.tmuxState = "disabled"
+    record.tmuxPaneID = null
+    record.tmuxSessionName = null
+    return { attached: false, reason: "not inside tmux" }
+  }
+  if (!hasTmuxBinary()) {
+    record.tmuxState = "disabled"
+    record.tmuxPaneID = null
+    record.tmuxSessionName = null
+    notifyTmuxMissingOnce(record.sessionID)
+    return { attached: false, reason: "tmux binary unavailable" }
+  }
+
+  const currentAttachedCount = getTasksForSession(record.sessionID).filter((task) => task.tmuxState === "attached").length
+  const maxAgentPanes = estimateMaxAgentPanes(config)
+  if (maxAgentPanes > 0 && currentAttachedCount >= maxAgentPanes) {
+    record.tmuxState = "queued"
+    return { attached: false, reason: `no pane capacity (${currentAttachedCount}/${maxAgentPanes})` }
+  }
+
+  const splitDirection = getSplitDirection(config.tmux.layout)
+  const split = runTmux(["split-window", splitDirection, "-d", "-P", "-F", "#{pane_id}"])
+  if (!split.ok) {
+    record.tmuxState = "failed"
+    return { attached: false, reason: split.stderr.trim() || "split-window failed" }
+  }
+
+  const paneID = split.stdout.trim().split("\n")[0]?.trim()
+  if (!paneID) {
+    record.tmuxState = "failed"
+    return { attached: false, reason: "split-window returned empty pane id" }
+  }
+
+  const sessionName = getTmuxSessionName(config, record)
+  const title = `${sessionName}:${record.title.slice(0, 24)}`
+  runTmux(["select-pane", "-t", paneID, "-T", title])
+  runTmux(["send-keys", "-t", paneID, `printf \"[${sessionName}] tracking ${record.id}\\n\"`, "Enter"])
+  applyTmuxLayout(config)
+
+  record.tmuxState = "attached"
+  record.tmuxPaneID = paneID
+  record.tmuxSessionName = sessionName
+  return { attached: true, reason: paneID }
+}
+
+function closeTaskPane(record: TaskRecord, config: OrchestrationConfig): void {
+  if (!record.tmuxPaneID) {
+    record.tmuxPaneID = null
+    record.tmuxSessionName = null
+    record.tmuxState = "disabled"
+    persistSessionTasks(record.sessionID)
+    return
+  }
+
+  if (!config.tmux.enabled || !isInsideTmux() || !hasTmuxBinary()) {
+    record.tmuxPaneID = null
+    record.tmuxSessionName = null
+    record.tmuxState = "disabled"
+    if (!hasTmuxBinary()) notifyTmuxMissingOnce(record.sessionID)
+    persistSessionTasks(record.sessionID)
+    return
+  }
+  runTmux(["send-keys", "-t", record.tmuxPaneID, "C-c"])
+  runTmux(["kill-pane", "-t", record.tmuxPaneID])
+  record.tmuxPaneID = null
+  record.tmuxSessionName = null
+  record.tmuxState = "disabled"
+  persistSessionTasks(record.sessionID)
+}
+
+function enqueueDeferredTmuxTask(sessionID: string, taskID: string): void {
+  const state = getSessionState(sessionID)
+  if (!state.deferredTmuxQueue.includes(taskID)) state.deferredTmuxQueue.push(taskID)
+}
+
+function processDeferredTmuxQueue(sessionID: string, config: OrchestrationConfig): number {
+  if (!config.tmux.enabled) return 0
+  const state = getSessionState(sessionID)
+  if (state.deferredTmuxQueue.length === 0) return 0
+
+  let attached = 0
+  const remaining: string[] = []
+  for (const taskID of state.deferredTmuxQueue) {
+    const record = taskRecords.get(taskID)
+    if (!record || record.sessionID !== sessionID) continue
+    if (record.status === "completed" || record.status === "failed" || record.status === "stopped") continue
+    const result = attachTaskPane(record, config)
+    if (result.attached) {
+      attached += 1
+      pushNotification(sessionID, "info", `Tmux pane attached for ${record.title}`, record.id)
+      persistSessionTasks(sessionID)
+      continue
+    }
+    if (record.tmuxState === "queued") {
+      remaining.push(taskID)
+      break
+    }
+  }
+
+  state.deferredTmuxQueue = remaining
+  return attached
+}
+
+function verifyTaskPane(record: TaskRecord): boolean {
+  if (!record.tmuxPaneID) return false
+  const probe = runTmux(["display-message", "-p", "-t", record.tmuxPaneID, "#{pane_id}"])
+  return probe.ok
+}
+
+function reconcileTmuxState(sessionID: string, config: OrchestrationConfig): { staleClosed: number; missing: number; queuedAttached: number } {
+  if (!config.tmux.enabled || !isInsideTmux() || !hasTmuxBinary()) {
+    return { staleClosed: 0, missing: 0, queuedAttached: 0 }
+  }
+
+  let staleClosed = 0
+  let missing = 0
+  const tasks = getTasksForSession(sessionID)
+  for (const record of tasks) {
+    const terminal = record.status === "completed" || record.status === "failed" || record.status === "stopped"
+    if (terminal && record.tmuxPaneID) {
+      closeTaskPane(record, config)
+      staleClosed += 1
+      continue
+    }
+    if (record.tmuxState === "attached" && record.tmuxPaneID && !verifyTaskPane(record)) {
+      record.tmuxState = "failed"
+      record.tmuxPaneID = null
+      record.tmuxSessionName = null
+      missing += 1
+      persistSessionTasks(sessionID)
+      pushNotification(sessionID, "warn", `Tmux pane missing for ${record.title}`, record.id)
+    }
+  }
+  const queuedAttached = processDeferredTmuxQueue(sessionID, config)
+  return { staleClosed, missing, queuedAttached }
+}
+
+function formatTaskLine(record: TaskRecord): string {
+  const bg = record.backgroundTaskID ? ` bg=${record.backgroundTaskID}` : ""
+  const category = record.category ? ` category=${record.category}` : ""
+  const deps = record.blockedBy.length > 0 ? ` blockedBy=${record.blockedBy.join(",")}` : ""
+  const pane = record.tmuxPaneID ? ` pane=${record.tmuxPaneID}` : ""
+  const tmuxState = ` tmux=${record.tmuxState}`
+  return `- ${record.id} [${record.status}] ${record.agent} \"${record.title}\"${bg}${category}${deps}${pane}${tmuxState}`
+}
+
+interface DiagnosticCheck {
+  label: string
+  pass: boolean
+  remediation: string
+}
+
+function diagnosticsCheck(label: string, pass: boolean, remediation: string): DiagnosticCheck {
+  return { label, pass, remediation }
+}
+
+function formatCheck(check: DiagnosticCheck): string {
+  return `- ${check.pass ? "PASS" : "FAIL"} ${check.label}${check.pass ? "" : ` -> ${check.remediation}`}`
+}
+
+function runDiagnostics(sessionID: string): string {
+  const configResult = parseConfigFromFile()
+  const config = configResult.config
+  const timedOutTasks = isHookEnabled(config, "timeout-enforcement") ? enforceTaskTimeouts(sessionID, config) : 0
+  const tmuxHealth = reconcileTmuxState(sessionID, config)
+  const tasks = getTasksForSession(sessionID)
+  const activeTasks = tasks.filter((task) => task.status === "running" || task.status === "retrying" || task.status === "queued")
+  const activeByCategory = new Map<string, number>()
+  for (const task of activeTasks) {
+    const category = task.category
+    if (!category) continue
+    activeByCategory.set(category, (activeByCategory.get(category) ?? 0) + 1)
+  }
+  const categoryConcurrencyViolations = [...activeByCategory.entries()].filter(([category, active]) => {
+    const limit = getCategoryConcurrencyLimit(config, category)
+    return active > limit
+  })
+  const attachedTmuxTasks = tasks.filter((task) => task.tmuxState === "attached")
+  const queuedTmuxTasks = tasks.filter((task) => task.tmuxState === "queued")
+  const state = getSessionState(sessionID)
+
+  const requiredCommands = ["continue", "stop", "tasks", "task", "diagnostics", "look-at"]
+  const commandChecks: DiagnosticCheck[] = requiredCommands.map((name) => {
+    const exists = existsSync(join(process.cwd(), "command", `${name}.md`))
+    return diagnosticsCheck(`/` + name, exists, `add command/${name}.md`)
+  })
+
+  const lookAtPluginExists = existsSync(join(process.cwd(), "plugin", "wpromote-look-at.ts"))
+  const orchestrationPluginExists = existsSync(join(process.cwd(), "plugin", "wpromote-orchestration.ts"))
+  const configChecks: DiagnosticCheck[] = [
+    diagnosticsCheck("providerMode", config.providerMode === "copilot" || config.providerMode === "native", "set orchestration.providerMode to copilot or native"),
+    diagnosticsCheck("feature:delegation", config.features.delegation, "enable orchestration.features.delegation"),
+    diagnosticsCheck("feature:diagnostics", config.features.diagnostics, "enable orchestration.features.diagnostics"),
+    diagnosticsCheck("feature:continuousLoop", config.features.continuousLoop, "enable orchestration.features.continuousLoop"),
+    diagnosticsCheck("feature:selfHealing", config.features.selfHealing, "enable orchestration.features.selfHealing"),
+    diagnosticsCheck("limits:maxConcurrent", config.limits.maxConcurrent >= 1 && config.limits.maxConcurrent <= 10, "set orchestration.limits.maxConcurrent in range 1..10"),
+    diagnosticsCheck("limits:maxRetries", config.limits.maxRetries >= 0 && config.limits.maxRetries <= 5, "set orchestration.limits.maxRetries in range 0..5"),
+    diagnosticsCheck("limits:maxIterations", config.limits.maxIterations >= 1 && config.limits.maxIterations <= 100, "set orchestration.limits.maxIterations in range 1..100"),
+    diagnosticsCheck("limits:retryBackoffMs", config.limits.retryBackoffMs >= 100 && config.limits.retryBackoffMs <= 60000, "set orchestration.limits.retryBackoffMs in range 100..60000"),
+    diagnosticsCheck("limits:taskTimeoutMs", config.limits.taskTimeoutMs >= 1000 && config.limits.taskTimeoutMs <= 900000, "set orchestration.limits.taskTimeoutMs in range 1000..900000"),
+    diagnosticsCheck("runtime:activeWithinLimit", activeTasks.length <= config.limits.maxConcurrent, "reduce active subagent workload or increase orchestration.limits.maxConcurrent"),
+    diagnosticsCheck("categories:routing", typeof config.categories.routing === "object", "set orchestration.categories.routing as an object map"),
+    diagnosticsCheck("categories:maxConcurrent", typeof config.categories.maxConcurrent === "object", "set orchestration.categories.maxConcurrent as an object map"),
+    diagnosticsCheck(
+      "runtime:categoryConcurrency",
+      categoryConcurrencyViolations.length === 0,
+      "reduce active tasks per category or raise orchestration.categories.maxConcurrent entries"
+    ),
+    diagnosticsCheck("runtimeFallback:enabled", typeof config.runtimeFallback.enabled === "boolean", "set orchestration.runtimeFallback.enabled to true/false"),
+    diagnosticsCheck("runtimeFallback:maxFallbackAttempts", config.runtimeFallback.maxFallbackAttempts >= 1 && config.runtimeFallback.maxFallbackAttempts <= 5, "set orchestration.runtimeFallback.maxFallbackAttempts in range 1..5"),
+    diagnosticsCheck("runtimeFallback:cooldownSeconds", config.runtimeFallback.cooldownSeconds >= 0 && config.runtimeFallback.cooldownSeconds <= 600, "set orchestration.runtimeFallback.cooldownSeconds in range 0..600"),
+    diagnosticsCheck("runtimeFallback:timeoutSeconds", config.runtimeFallback.timeoutSeconds >= 0 && config.runtimeFallback.timeoutSeconds <= 300, "set orchestration.runtimeFallback.timeoutSeconds in range 0..300"),
+    diagnosticsCheck("runtimeFallback:providerOrder", config.runtimeFallback.providerOrder.length > 0, "set orchestration.runtimeFallback.providerOrder with at least one provider"),
+    diagnosticsCheck("hooks:disabled", Array.isArray(config.hooks.disabled), "set orchestration.hooks.disabled as a string array"),
+    diagnosticsCheck("hooks:telemetry", typeof config.hooks.telemetry === "boolean", "set orchestration.hooks.telemetry to true/false"),
+    diagnosticsCheck("notifications:enabled", typeof config.notifications.enabled === "boolean", "set orchestration.notifications.enabled to true/false"),
+    diagnosticsCheck("notifications:maxItems", config.notifications.maxItems >= 10 && config.notifications.maxItems <= 500, "set orchestration.notifications.maxItems in range 10..500"),
+    diagnosticsCheck("recovery:autoResumeOnStart", typeof config.recovery.autoResumeOnStart === "boolean", "set orchestration.recovery.autoResumeOnStart to true/false"),
+    diagnosticsCheck("tmux:enabled", typeof config.tmux.enabled === "boolean", "set orchestration.tmux.enabled to true/false"),
+    diagnosticsCheck("tmux:layout", ["main-horizontal", "main-vertical", "tiled", "even-horizontal", "even-vertical"].includes(config.tmux.layout), "set orchestration.tmux.layout to a supported layout"),
+    diagnosticsCheck("tmux:mainPaneSize", config.tmux.mainPaneSize >= 20 && config.tmux.mainPaneSize <= 80, "set orchestration.tmux.mainPaneSize in range 20..80"),
+    diagnosticsCheck("tmux:mainPaneMinWidth", config.tmux.mainPaneMinWidth >= 40 && config.tmux.mainPaneMinWidth <= 400, "set orchestration.tmux.mainPaneMinWidth in range 40..400"),
+    diagnosticsCheck("tmux:agentPaneMinWidth", config.tmux.agentPaneMinWidth >= 20 && config.tmux.agentPaneMinWidth <= 200, "set orchestration.tmux.agentPaneMinWidth in range 20..200"),
+    diagnosticsCheck("tmux:sessionPrefix", /^[a-zA-Z0-9_-]{2,20}$/.test(config.tmux.sessionPrefix), "set orchestration.tmux.sessionPrefix to 2..20 chars [a-zA-Z0-9_-]"),
+    diagnosticsCheck("tmux:insideSession", !config.tmux.enabled || isInsideTmux(), "run inside tmux or disable orchestration.tmux.enabled"),
+    diagnosticsCheck("tmux:binary", !config.tmux.enabled || hasTmuxBinary(), "install tmux and ensure it is on PATH"),
+  ]
+  const pluginChecks: DiagnosticCheck[] = [
+    diagnosticsCheck("plugin/wpromote-orchestration.ts", orchestrationPluginExists, "add plugin/wpromote-orchestration.ts"),
+    diagnosticsCheck("plugin/wpromote-look-at.ts", lookAtPluginExists, "add plugin/wpromote-look-at.ts"),
+  ]
+  const allChecks = [...configChecks, ...pluginChecks, ...commandChecks]
+  const failedChecks = allChecks.filter((check) => !check.pass)
+  const passCount = allChecks.length - failedChecks.length
+  const failCount = failedChecks.length
+
+  const lines = [
+    "# Wpromote Diagnostics (Full)",
+    "",
+    "## Summary",
+    `- Overall: ${failCount === 0 ? "PASS" : "FAIL"}`,
+    `- Checks: ${passCount} passed, ${failCount} failed`,
+    `- Config source: ${configResult.source}`,
+    "",
+    "## Configuration",
+    ...configChecks.map(formatCheck),
+    "",
+    "## Plugin Assets",
+    ...pluginChecks.map(formatCheck),
+    "",
+    "## Commands",
+    ...commandChecks.map(formatCheck),
+    "",
+    "## Runtime State",
+    `- Active task records in this session: ${tasks.length}`,
+    `- Persisted task records across sessions: ${getPersistedTaskCount()}`,
+    `- Active delegated tasks: ${activeTasks.length}/${config.limits.maxConcurrent}`,
+    `- Active tmux panes: ${attachedTmuxTasks.length}`,
+    `- Deferred tmux queue depth: ${state.deferredTmuxQueue.length}`,
+    `- Recovery auto-resume on startup: ${config.recovery.autoResumeOnStart ? "enabled" : "disabled"}`,
+    `- Timed out tasks auto-marked failed in this pass: ${timedOutTasks}`,
+    `- Tmux stale pane cleanups in this pass: ${tmuxHealth.staleClosed}`,
+    `- Tmux missing pane detections in this pass: ${tmuxHealth.missing}`,
+    `- Deferred tmux attaches completed in this pass: ${tmuxHealth.queuedAttached}`,
+    `- Loop mode: ${getSessionState(sessionID).loopEnabled ? "enabled" : "disabled"}`,
+    "",
+    "## Hook Health",
+    `- task-tracking: ${isHookEnabled(config, "task-tracking") ? "enabled" : "disabled"}`,
+    `- timeout-enforcement: ${isHookEnabled(config, "timeout-enforcement") ? "enabled" : "disabled"}`,
+    `- fallback-engine: ${isHookEnabled(config, "fallback-engine") ? "enabled" : "disabled"}`,
+    `- activity-feed: ${isHookEnabled(config, "activity-feed") ? "enabled" : "disabled"}`,
+    `- telemetry: ${config.hooks.telemetry ? "enabled" : "disabled"}`,
+    `- telemetry counters: created=${state.telemetry.created}, resumed=${state.telemetry.resumed}, completed=${state.telemetry.completed}, failed=${state.telemetry.failed}, retrying=${state.telemetry.retrying}, stopped=${state.telemetry.stopped}, timedOut=${state.telemetry.timedOut}`,
+    `- notifications: ${config.notifications.enabled ? "enabled" : "disabled"} (buffer=${state.notifications.length}/${config.notifications.maxItems})`,
+    `- tmux queue: ${config.tmux.enabled ? "enabled" : "disabled"} (queued=${queuedTmuxTasks.length})`,
+    "",
+    "## Provider Routing",
+    `- Current mode: ${config.providerMode}`,
+    `- Category routing overrides: ${Object.entries(config.categories.routing)
+      .map(([category, provider]) => `${category}:${provider}`)
+      .join(", ") || "none"}`,
+    `- Category concurrency overrides: ${Object.entries(config.categories.maxConcurrent)
+      .map(([category, limit]) => `${category}:${limit}`)
+      .join(", ") || "none"}`,
+    `- Runtime fallback: ${config.runtimeFallback.enabled ? "enabled" : "disabled"}`,
+    `- Fallback retries: ${config.runtimeFallback.maxFallbackAttempts}`,
+    `- Retry error codes: ${config.runtimeFallback.retryOnErrors.join(", ")}`,
+    `- Provider fallback chain: ${config.runtimeFallback.providerOrder.join(" -> ")}`,
+    config.providerMode === "copilot"
+      ? "- Routing profile: Copilot-first (Codex/Gemini through Copilot where configured)."
+      : "- Routing profile: Native provider mode (direct provider endpoints).",
+  ]
+
+  if (failedChecks.length > 0) {
+    lines.push("", "## Remediation")
+    for (const check of failedChecks) {
+      lines.push(`- ${check.label}: ${check.remediation}`)
+    }
+  }
+
+  return lines.join("\n")
+}
+
+function formatSingleTask(record: TaskRecord): string {
+  return [
+    `# Task ${record.id}`,
+    "",
+    `- Status: ${record.status}`,
+    `- Agent: ${record.agent}`,
+    `- Category: ${record.category ?? "n/a"}`,
+    `- Title: ${record.title}`,
+    `- Retries: ${record.retries}`,
+    `- Created: ${record.createdAt}`,
+    `- Updated: ${record.updatedAt}`,
+    `- Background ID: ${record.backgroundTaskID ?? "n/a"}`,
+    `- Tmux State: ${record.tmuxState}`,
+    `- Tmux Pane ID: ${record.tmuxPaneID ?? "n/a"}`,
+    `- Tmux Session: ${record.tmuxSessionName ?? "n/a"}`,
+    `- Blocked By: ${record.blockedBy.length > 0 ? record.blockedBy.join(", ") : "none"}`,
+    `- Blocks: ${record.blocks.length > 0 ? record.blocks.join(", ") : "none"}`,
+    `- Details: ${record.details}`,
+  ].join("\n")
+}
+
+const orchestrationTool = tool({
+  description:
+    "Controls wpromote orchestration state. Actions: continue, stop, tasks, task, diagnostics.",
+  args: {
+    action: tool.schema.enum(["continue", "stop", "tasks", "task", "diagnostics"]),
+    task_id: tool.schema.string().optional(),
+  },
+  execute: async (args, context) => {
+    const state = getSessionState(context.sessionID)
+
+    if (args.action === "continue") {
+      state.loopEnabled = true
+      return [
+        "Continuous loop mode enabled for this session.",
+        "- Loop remains active until /stop is invoked.",
+        "- Self-healing policies respect configured retry/timeout bounds.",
+      ].join("\n")
+    }
+
+    if (args.action === "stop") {
+      const config = parseConfigFromFile().config
+      state.loopEnabled = false
+      for (const record of getTasksForSession(context.sessionID)) {
+        if (record.status === "queued" || record.status === "running" || record.status === "retrying") {
+          setTaskStatus(record, "stopped", "Stopped by /stop command")
+        }
+        if (record.tmuxPaneID) {
+          closeTaskPane(record, config)
+        }
+      }
+      state.deferredTmuxQueue = []
+      return "Loop and queue processing halted for this session. Awaiting further instruction."
+    }
+
+    if (args.action === "tasks") {
+      const config = parseConfigFromFile().config
+      if (isHookEnabled(config, "timeout-enforcement")) {
+        enforceTaskTimeouts(context.sessionID, config)
+      }
+      const tmuxHealth = reconcileTmuxState(context.sessionID, config)
+      const tasks = getTasksForSession(context.sessionID)
+      if (tasks.length === 0) return "No tracked subagent tasks for this session yet."
+
+      const lines = ["# Active Subagent Tasks", "", ...tasks.slice(0, 20).map(formatTaskLine)]
+      lines.push(
+        "",
+        "# Tmux Runtime",
+        "",
+        `- enabled=${config.tmux.enabled}`,
+        `- attached=${tasks.filter((task) => task.tmuxState === "attached").length}`,
+        `- queued=${getSessionState(context.sessionID).deferredTmuxQueue.length}`,
+        `- staleClosed=${tmuxHealth.staleClosed}`,
+        `- missingDetected=${tmuxHealth.missing}`,
+        `- queuedAttached=${tmuxHealth.queuedAttached}`,
+      )
+      const notifications = getSessionState(context.sessionID).notifications.slice(0, 5)
+      if (notifications.length > 0) {
+        lines.push("", "# Recent Notifications", "")
+        for (const note of notifications) {
+          lines.push(`- [${note.level.toUpperCase()}] ${note.ts} ${note.message} (${note.taskID})`)
+        }
+      }
+
+      return lines.join("\n")
+    }
+
+    if (args.action === "task") {
+      if (!args.task_id) return "Missing task_id. Usage: action=task task_id=<id>"
+      const byID = taskRecords.get(args.task_id)
+      if (byID && byID.sessionID === context.sessionID) {
+        return formatSingleTask(byID)
+      }
+
+      for (const record of getTasksForSession(context.sessionID)) {
+        if (record.backgroundTaskID === args.task_id) {
+          return formatSingleTask(record)
+        }
+      }
+
+      return `Task not found for this session: ${args.task_id}`
+    }
+
+    return runDiagnostics(context.sessionID)
+  },
+})
+
+const WpromoteOrchestrationPlugin: Plugin = async () => {
+  recoverPersistedTasks(parseConfigFromFile().config)
+
+  return {
+    tool: {
+      wpromote_orchestration: orchestrationTool,
+    },
+    "tool.execute.before": async (input, output) => {
+      if (input.tool !== "task") return
+
+      const config = parseConfigFromFile().config
+      if (!isHookEnabled(config, "task-tracking")) return
+      const taskInfo = parseTaskInfo(output.args)
+      const activeBefore = countActiveTasks(input.sessionID)
+      const categoryActiveBefore = countActiveTasksByCategory(input.sessionID, taskInfo.category)
+      const deps = parseTaskDependencies(output.args)
+      const record = createTaskRecord(input.sessionID, taskInfo.title, taskInfo.agent, taskInfo.category, taskInfo.details)
+      const taskProvider = resolveTaskProvider(config, record.category)
+      record.details = `${taskInfo.details} provider=${taskProvider}`
+      record.blockedBy = deps.blockedBy
+      record.blocks = deps.blocks
+
+      if (config.tmux.enabled) {
+        const attach = attachTaskPane(record, config)
+        if (!attach.attached && record.tmuxState === "queued") {
+          enqueueDeferredTmuxTask(input.sessionID, record.id)
+        }
+      }
+
+      persistSessionTasks(input.sessionID)
+      taskByCallID.set(input.callID, record.id)
+
+      if (activeBefore >= config.limits.maxConcurrent) {
+        setTaskStatus(record, "queued", `Waiting for global slot (${activeBefore}/${config.limits.maxConcurrent} active)`)
+        return
+      }
+
+      const categoryLimit = getCategoryConcurrencyLimit(config, record.category)
+      if (categoryActiveBefore >= categoryLimit) {
+        const categoryLabel = record.category ?? "unspecified"
+        setTaskStatus(record, "queued", `Waiting for category ${categoryLabel} slot (${categoryActiveBefore}/${categoryLimit} active)`)
+      }
+    },
+    "tool.execute.after": async (input, output) => {
+      if (input.tool !== "task") return
+
+      const config = parseConfigFromFile().config
+      if (!isHookEnabled(config, "task-tracking")) return
+
+      const taskID = taskByCallID.get(input.callID)
+      if (!taskID) return
+
+      const record = taskRecords.get(taskID)
+      if (!record) return
+
+      const textOutput = typeof output.output === "string" ? output.output : ""
+      const bgID = extractBackgroundTaskID(textOutput)
+
+      if (bgID) {
+        const taskProvider = resolveTaskProvider(config, record.category)
+        record.backgroundTaskID = bgID
+        setTaskStatus(record, "running", `Background task launched with ${bgID}, provider=${taskProvider}`)
+      } else if (textOutput.toLowerCase().includes("failed")) {
+        const failure = classifyFailure(textOutput)
+        const taskProvider = resolveTaskProvider(config, record.category)
+        const shouldFallback =
+          config.features.selfHealing &&
+          isHookEnabled(config, "fallback-engine") &&
+          config.runtimeFallback.enabled &&
+          failure.code !== null &&
+          config.runtimeFallback.retryOnErrors.includes(failure.code) &&
+          record.fallbackAttempts < config.runtimeFallback.maxFallbackAttempts
+
+        if (shouldFallback) {
+          record.fallbackAttempts += 1
+          record.retries += 1
+          record.fallbackReason = failure.reason
+          const nextProvider = getNextProvider(config, taskProvider)
+          const providerNote = nextProvider ? `next provider ${nextProvider}` : "no alternate provider configured"
+          setTaskStatus(
+            record,
+            "retrying",
+            `Fallback attempt ${record.fallbackAttempts}/${config.runtimeFallback.maxFallbackAttempts}, reason=${failure.reason}, ${providerNote}`
+          )
+        } else {
+          setTaskStatus(record, "failed", "Task execution reported failure")
+        }
+      } else {
+        setTaskStatus(record, "completed", "Task execution completed")
+      }
+
+      if (record.status === "completed" || record.status === "failed" || record.status === "stopped") {
+        closeTaskPane(record, config)
+      }
+      processDeferredTmuxQueue(input.sessionID, config)
+      persistSessionTasks(input.sessionID)
+
+      const activityLine = `\n[Subagent activity] ${record.status.toUpperCase()} ${record.agent} \"${record.title}\"`
+      if (isHookEnabled(config, "activity-feed")) {
+        if (typeof output.output === "string") {
+          output.output = `${output.output}${activityLine}`
+        } else {
+          output.output = activityLine.trim()
+        }
+      }
+    },
+    event: async (input) => {
+      if (input.event.type !== "session.deleted") return
+      const props = isRecord(input.event.properties) ? input.event.properties : null
+      const info = props && isRecord(props.info) ? props.info : null
+      const sessionID = info ? asString(info.id) : undefined
+      if (!sessionID) return
+
+      const config = parseConfigFromFile().config
+      const state = getSessionState(sessionID)
+      for (const record of getTasksForSession(sessionID)) {
+        if (record.tmuxPaneID) closeTaskPane(record, config)
+        if (record.status === "running" || record.status === "retrying" || record.status === "queued") {
+          setTaskStatus(record, "stopped", "Parent session deleted")
+        }
+      }
+      state.deferredTmuxQueue = []
+      persistSessionTasks(sessionID)
+    },
+  }
+}
+
+export default WpromoteOrchestrationPlugin