mango-cms 0.3.33 → 0.3.35

package/lib/vibe-orchestrator/server.js

@@ -0,0 +1,344 @@
+// server.js
+//
+// Orchestrator HTTP entrypoint. Dependency-free (node:http). Exposes:
+//
+//   GET  /health           -> { ok, canRunLive, config summary }
+//   GET  /sessions         -> [ { site, sessionId, cumulativeTokens, status } ]
+//   POST /prompt           -> SSE stream of progress events  body: { site, prompt, pageContext?, attachments? }
+//   POST /abort            -> { ok }                          body: { site }
+//   POST /reset            -> { ok }                          body: { site }
+//   POST /publish          -> { ... }                         body: { site, confirm }
+//
+// Owner auth (HAP-1109): every endpoint except `GET /health` requires a real
+// per-owner token in `Authorization: Bearer <token>`. The token is minted by
+// Mango from an authenticated admin session and verified here against the shared
+// VIBE_ORCH_TOKEN_SECRET (see src/ownerToken.js). Without that secret the server
+// fails CLOSED — gated endpoints return 503, never open access. Client-side role
+// flags are never trusted. The Claude OAuth token is never exposed by any
+// endpoint. Intended to listen on localhost only and be fronted by the staging
+// nginx vhost (see README).
+
+import http from 'node:http'
+import { SessionManager } from './src/sessionManager.js'
+import { config, canRunLive } from './src/config.js'
+import { verifyOwnerToken } from './src/ownerToken.js'
+import * as publisher from './src/publisher.js'
+import * as recovery from './src/recovery.js'
+import { readCosts, rollup } from './src/costStore.js'
+
+const manager = new SessionManager()
+
+/** Extract the bearer token from the Authorization header. */
+function bearer(req) {
+  const h = req.headers['authorization'] || ''
+  const m = /^Bearer\s+(.+)$/i.exec(h.trim())
+  return m ? m[1].trim() : ''
+}
+
+/**
+ * Resolve owner auth for a request. Returns the verifyOwnerToken result:
+ * { ok:true, payload } or { ok:false, reason, status }. Fails closed when no
+ * token secret is configured (status 503).
+ */
+function requireOwner(req) {
+  return verifyOwnerToken(bearer(req), {
+    secret: config.tokenSecret,
+    ownerRoles: config.ownerRoles,
+  })
+}
+
+function sendJson(res, status, body) {
+  const data = JSON.stringify(body)
+  res.writeHead(status, { 'content-type': 'application/json' })
+  res.end(data)
+}
+
+/**
+ * Apply CORS headers for an allowed browser origin (HAP-1121). The ⌘K drawer is
+ * served from the site origin (e.g. https://staging-vibe.generations.org) and
+ * calls this orchestrator on the -api origin cross-origin. Without an allow-list
+ * + preflight handling the browser blocks every call and the drawer shows
+ * "Failed to fetch" (a transport failure with no HTTP status). Headers are set
+ * with setHeader so they merge into later writeHead() calls (JSON + SSE alike).
+ * Returns true when the request Origin is allowed.
+ */
+function applyCors(req, res) {
+  const origin = req.headers['origin']
+  if (!origin) return false
+  const list = config.allowedOrigins
+  const allowed = list.length === 0 || list.includes(origin)
+  if (!allowed) return false
+  res.setHeader('Access-Control-Allow-Origin', origin)
+  res.setHeader('Vary', 'Origin')
+  res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS')
+  res.setHeader('Access-Control-Allow-Headers', 'authorization, content-type')
+  res.setHeader('Access-Control-Max-Age', '86400')
+  return true
+}
+
+/**
+ * Resolve a { from, to } ms window from query params (HAP-1123). Each of `from`
+ * and `to` may be epoch-ms or an ISO date (YYYY-MM-DD). With neither present we
+ * default to the current calendar month-to-date so a bare `/costs/rollup` answers
+ * "this month's spend". An ISO date with no time is treated as UTC midnight.
+ */
+function parseRange(params) {
+  const parse = (v) => {
+    if (!v) return undefined
+    if (/^\d+$/.test(v)) return Number.parseInt(v, 10)
+    const t = Date.parse(v)
+    return Number.isNaN(t) ? undefined : t
+  }
+  let from = parse(params.get('from'))
+  let to = parse(params.get('to'))
+  if (from === undefined && to === undefined) {
+    const now = new Date()
+    from = Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1)
+  }
+  return { from, to }
+}
+
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    let raw = ''
+    req.on('data', (c) => {
+      raw += c
+      // 80MB ceiling: prompt bodies may carry a base64 viewport screenshot
+      // (HAP-1111) plus up to 5 user attachments of ≤10MB each (HAP-1126). The
+      // per-file size/mime/count guard runs again server-side in attachments.js;
+      // this is just the gross transport cap.
+      if (raw.length > 80_000_000) reject(new Error('body too large'))
+    })
+    req.on('end', () => {
+      if (!raw) return resolve({})
+      try { resolve(JSON.parse(raw)) } catch { reject(new Error('invalid JSON body')) }
+    })
+    req.on('error', reject)
+  })
+}
+
+function startSse(res, { onPing } = {}) {
+  res.writeHead(200, {
+    'content-type': 'text/event-stream',
+    'cache-control': 'no-cache',
+    connection: 'keep-alive',
+    'x-accel-buffering': 'no', // disable nginx proxy buffering
+  })
+  const write = (event, data) => {
+    res.write(`event: ${event}\n`)
+    res.write(`data: ${JSON.stringify(data)}\n\n`)
+  }
+  // keepalive comment ping so idle proxies don't drop the connection. The ping
+  // also counts as session activity (HAP-1110) so an actively-read but idle
+  // session is kept warm rather than reaped mid-read.
+  const ping = setInterval(() => {
+    res.write(': ping\n\n')
+    onPing?.()
+  }, 15000)
+  if (ping.unref) ping.unref()
+  return { write, close: () => clearInterval(ping) }
+}
+
+async function handlePrompt(req, res) {
+  let body
+  try { body = await readBody(req) } catch (e) { return sendJson(res, 400, { error: e.message }) }
+  const { site, prompt, pageContext, attachments } = body
+
+  let handle
+  try {
+    handle = manager.submit(site, prompt, { pageContext, attachments })
+  } catch (e) {
+    return sendJson(res, 400, { error: e.message })
+  }
+
+  // Track this connection as an active reader and keep the session warm on ping.
+  manager.addReader(site)
+  const sse = startSse(res, { onPing: () => manager.touch(site) })
+  sse.write('accepted', { site })
+
+  handle.emitter.on('event', (ev) => sse.write('progress', ev))
+  handle.emitter.on('error', (err) => sse.write('error', { message: err.message }))
+  handle.emitter.on('end', (summary) => {
+    sse.write('end', summary)
+    sse.close()
+    manager.removeReader(site)
+    res.end()
+  })
+
+  // If the client disconnects, abort the run to free the slot.
+  req.on('close', () => {
+    if (!res.writableEnded) {
+      handle.abort()
+      manager.removeReader(site)
+    }
+    sse.close()
+  })
+}
+
+const server = http.createServer(async (req, res) => {
+  const url = new URL(req.url, 'http://localhost')
+  const route = `${req.method} ${url.pathname}`
+
+  // CORS (HAP-1121): set allow-origin headers for an allowed browser origin and
+  // answer the preflight BEFORE the auth gate. Browsers never send the
+  // Authorization header on an OPTIONS preflight, so gating it on auth returned
+  // 401 and the whole cross-origin call failed in-browser as "Failed to fetch".
+  applyCors(req, res)
+  if (req.method === 'OPTIONS') {
+    res.writeHead(204)
+    return res.end()
+  }
+
+  // `GET /health` is the only unauthenticated route: a minimal liveness probe
+  // for ops/nginx that leaks no config. Everything else requires an owner token.
+  if (route === 'GET /health') {
+    return sendJson(res, 200, { ok: true, ownerAuth: !!config.tokenSecret })
+  }
+
+  // Real per-owner gate. 401 = no/invalid token, 403 = valid but not an owner,
+  // 503 = server not configured for owner auth (fails closed).
+  const auth = requireOwner(req)
+  if (!auth.ok) return sendJson(res, auth.status || 401, { error: auth.reason || 'unauthorized' })
+  req.owner = auth.payload
+
+  try {
+    switch (route) {
+      case 'GET /health/details':
+        return sendJson(res, 200, {
+          ok: true,
+          canRunLive: canRunLive(),
+          stagingRoot: config.stagingRoot,
+          allowedSites: config.allowedSites,
+          tokenCap: config.tokenCap,
+          permissionMode: config.permissionMode,
+          publishEnabled: config.publishEnabled,
+          publishRemote: config.publishRemote,
+          settingsPath: config.settingsPath,
+        })
+
+      case 'GET /sessions':
+        return sendJson(res, 200, { sessions: manager.list() })
+
+      // ---- Cost tracking (HAP-1123) ----
+      // GET /costs         — raw per-turn records in a window (for export/audit)
+      // GET /costs/rollup  — summed totals (by day/session/model) to invoice from
+      // Both default to the current calendar month when no range is given, and
+      // accept ?from / ?to as epoch-ms or YYYY-MM-DD, plus an optional ?site.
+      case 'GET /costs': {
+        const range = parseRange(url.searchParams)
+        const site = url.searchParams.get('site') || undefined
+        return sendJson(res, 200, { ...range, site: site || null, records: readCosts({ ...range, site }) })
+      }
+
+      case 'GET /costs/rollup': {
+        const range = parseRange(url.searchParams)
+        const site = url.searchParams.get('site') || undefined
+        return sendJson(res, 200, rollup({ ...range, site }))
+      }
+
+      case 'POST /prompt':
+        return await handlePrompt(req, res)
+
+      case 'GET /publish/diff': {
+        const site = url.searchParams.get('site') || config.allowedSites[0]
+        try {
+          const d = await publisher.diff(site)
+          return sendJson(res, 200, d)
+        } catch (e) {
+          return sendJson(res, e.statusCode || 400, { error: e.message })
+        }
+      }
+
+      case 'POST /publish': {
+        let body
+        try { body = await readBody(req) } catch (e) { return sendJson(res, 400, { error: e.message }) }
+        const { site, message, confirm } = body
+        try {
+          const result = await publisher.publish(site || config.allowedSites[0], { message, confirm })
+          return sendJson(res, 200, result)
+        } catch (e) {
+          // 409 ⇒ merge conflict publishing the branch into the deploy branch;
+          // surface the conflicting files so the owner can resolve them.
+          return sendJson(res, e.statusCode || 500, {
+            error: e.message,
+            steps: e.steps,
+            conflicts: e.conflicts,
+            deployBranch: e.deployBranch,
+          })
+        }
+      }
+
+      // ---- Recovery / rollback (HAP-1124) ----
+      // GET  /recovery/status        — baseline + recent vibe commits + what's available
+      // POST /recovery/revert-last   — undo the most recent vibe edit (git revert)
+      // POST /recovery/reset-baseline— hard-reset to the known-good baseline (confirm:true)
+      // A recovery path usable without an engineer; also wrapped by scripts/vibe-recover.sh.
+      case 'GET /recovery/status': {
+        const site = url.searchParams.get('site') || config.allowedSites[0]
+        try {
+          return sendJson(res, 200, await recovery.status(site))
+        } catch (e) {
+          return sendJson(res, e.statusCode || 400, { error: e.message })
+        }
+      }
+
+      case 'POST /recovery/revert-last': {
+        const { site } = await readBody(req)
+        const target = site || config.allowedSites[0]
+        if (manager.get(target)?.status === 'running') {
+          return sendJson(res, 409, { error: 'cannot recover while a run is in progress' })
+        }
+        try {
+          return sendJson(res, 200, await recovery.revertLast(target))
+        } catch (e) {
+          return sendJson(res, e.statusCode || 400, { error: e.message })
+        }
+      }
+
+      case 'POST /recovery/reset-baseline': {
+        const { site, confirm } = await readBody(req)
+        const target = site || config.allowedSites[0]
+        if (confirm !== true) {
+          return sendJson(res, 400, { error: 'reset to baseline requires explicit confirm:true' })
+        }
+        if (manager.get(target)?.status === 'running') {
+          return sendJson(res, 409, { error: 'cannot recover while a run is in progress' })
+        }
+        try {
+          return sendJson(res, 200, await recovery.resetToBaseline(target))
+        } catch (e) {
+          return sendJson(res, e.statusCode || 400, { error: e.message })
+        }
+      }
+
+      case 'POST /abort': {
+        const { site } = await readBody(req)
+        manager.abort(site)
+        return sendJson(res, 200, { ok: true })
+      }
+
+      case 'POST /reset': {
+        const { site } = await readBody(req)
+        try { manager.reset(site) } catch (e) { return sendJson(res, 409, { error: e.message }) }
+        return sendJson(res, 200, { ok: true })
+      }
+
+      default:
+        return sendJson(res, 404, { error: 'not found' })
+    }
+  } catch (e) {
+    if (!res.headersSent) sendJson(res, 500, { error: e.message })
+  }
+})
+
+// Listen on loopback only; nginx terminates TLS and proxies.
+server.listen(config.port, '127.0.0.1', () => {
+  // eslint-disable-next-line no-console
+  console.log(`[vibe-orchestrator] listening on 127.0.0.1:${config.port} (live=${canRunLive()}, ownerAuth=${!!config.tokenSecret})`)
+  if (!config.tokenSecret) {
+    // eslint-disable-next-line no-console
+    console.warn('[vibe-orchestrator] WARNING: VIBE_ORCH_TOKEN_SECRET is unset — owner auth is NOT configured; all gated endpoints will return 503 (fail closed).')
+  }
+})
+
+export { server }

package/lib/vibe-orchestrator/src/attachments.js

@@ -0,0 +1,98 @@
+// attachments.js
+//
+// Persist client-uploaded chat attachments (images + PDFs) to temp files the
+// agent can Read — Claude Code natively reads images AND PDFs. Generalizes
+// screenshot.js: each file arrives as a base64 data URL and is written to the OS
+// temp dir, NEVER into the staging repo, so nothing is ever committed or
+// published. Each turn we first clear the site's previous attachments so temp
+// growth stays bounded (the screenshot reuses one fixed file; attachments are a
+// variable-length set, so we sweep the whole `<site>-att-*` prefix). Best-effort
+// — never throws. A server-side size + mime + count guard runs here too so we
+// don't trust the client (HAP-1126).
+
+import { writeFileSync, mkdirSync, readdirSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+const DIR = join(tmpdir(), 'vibe-orchestrator')
+
+// Allowed upload types → file extension. Mirrors the client allow-list. The
+// extension is taken from the data URL's own mime (what the bytes actually are),
+// not the caller-supplied name, exactly like screenshot.js.
+const MIME_EXT = {
+  'image/png': 'png',
+  'image/jpeg': 'jpg',
+  'image/webp': 'webp',
+  'image/gif': 'gif',
+  'application/pdf': 'pdf',
+}
+
+const MAX_FILES = 5
+const MAX_BYTES = 10 * 1024 * 1024 // 10MB per file, decoded (server-side guard)
+
+const DATA_URL = /^data:([a-z0-9.+-]+\/[a-z0-9.+-]+);base64,([A-Za-z0-9+/=\s]+)$/i
+
+function safeSite(site) {
+  return String(site || 'site').replace(/[^a-z0-9_-]/gi, '_')
+}
+
+/** Remove any previously-persisted attachments for a site (best-effort). */
+function clearAttachments(site) {
+  const prefix = `${safeSite(site)}-att-`
+  try {
+    for (const f of readdirSync(DIR)) {
+      if (f.startsWith(prefix)) {
+        try { rmSync(join(DIR, f)) } catch { /* already gone */ }
+      }
+    }
+  } catch { /* dir missing — nothing to clear */ }
+}
+
+/**
+ * Persist a list of `{ name, mime, dataUrl }` attachments to disk. Returns an
+ * array of `{ name, path, mime }` for the files that were saved. Invalid entries
+ * (disallowed mime, malformed data URL, empty, or oversize) are skipped, and the
+ * count is capped at MAX_FILES. Passing an array (even empty) clears the site's
+ * previous attachments first, so each turn starts clean. Best-effort — never
+ * throws.
+ *
+ * @param {string} site
+ * @param {Array<{name?:string, mime?:string, dataUrl?:string}>} attachments
+ * @returns {Array<{name:string, path:string, mime:string}>}
+ */
+function persistAttachments(site, attachments) {
+  if (!Array.isArray(attachments)) return []
+  // Per-turn clean: drop the previous turn's files so temp never grows unbounded.
+  clearAttachments(site)
+  if (!attachments.length) return []
+
+  const saved = []
+  try { mkdirSync(DIR, { recursive: true }) } catch { return saved }
+  const safe = safeSite(site)
+  let n = 0
+  for (const att of attachments) {
+    if (n >= MAX_FILES) break
+    if (!att || typeof att !== 'object') continue
+    const dataUrl = typeof att.dataUrl === 'string' ? att.dataUrl.trim() : ''
+    const m = DATA_URL.exec(dataUrl)
+    if (!m) continue
+    const mime = m[1].toLowerCase()
+    const ext = MIME_EXT[mime]
+    if (!ext) continue // disallowed type — skip silently (client already warned)
+    let buf
+    try { buf = Buffer.from(m[2].replace(/\s+/g, ''), 'base64') } catch { continue }
+    if (!buf.length || buf.length > MAX_BYTES) continue // empty or oversize — skip
+    n += 1
+    const path = join(DIR, `${safe}-att-${n}.${ext}`)
+    const name = typeof att.name === 'string' && att.name.trim()
+      ? att.name.trim().slice(0, 200)
+      : `attachment-${n}.${ext}`
+    try {
+      writeFileSync(path, buf)
+      saved.push({ name, path, mime })
+    } catch { /* write failed — skip this one */ }
+  }
+  return saved
+}
+
+export { persistAttachments, clearAttachments, MIME_EXT, MAX_FILES, MAX_BYTES }

package/lib/vibe-orchestrator/src/claudeRunner.js

@@ -0,0 +1,233 @@
+// claudeRunner.js
+//
+// Spawns Claude Code headless and turns its stream-json output into a live
+// EventEmitter of normalized progress events.
+//
+//   claude -p "<prompt>" --output-format stream-json --verbose \
+//          --permission-mode <mode> [--resume <sessionId>] [--model <m>]
+//
+// cwd is scoped to the resolved staging site dir; the OAuth token is passed via
+// the child env only (never on argv, never logged). The token meter watches
+// usage as it streams and the run is aborted if the per-session cap trips.
+
+import { spawn } from 'node:child_process'
+import { EventEmitter } from 'node:events'
+import { StreamParser, KINDS } from './streamParser.js'
+import { TokenMeter } from './tokenMeter.js'
+import { applyMarkup } from './costStore.js'
+
+/**
+ * Build the inline `--settings` JSON that installs the PreToolUse path-guard hook
+ * (HAP-1124). Enforced server-side for every run: the hook blocks edits to the
+ * Vibe system regardless of the prompt. Returns '' when no hook is configured.
+ * @param {string} [pathGuardHook] absolute path to the hook script
+ * @returns {string}
+ */
+function buildSettings(pathGuardHook) {
+  if (!pathGuardHook) return ''
+  // The `command` is run via shell by the CLI, so quote the path. spawn passes
+  // the whole JSON as one argv element, so the JSON itself needs no extra quoting.
+  return JSON.stringify({
+    hooks: {
+      PreToolUse: [
+        {
+          matcher: 'Edit|Write|MultiEdit|NotebookEdit',
+          hooks: [{ type: 'command', command: `node '${pathGuardHook}'` }],
+        },
+      ],
+    },
+  })
+}
+
+/**
+ * Build the claude argv for a run.
+ * @returns {string[]}
+ */
+function buildArgs({ prompt, permissionMode, model, resumeSessionId, pathGuardHook, allowedTools = [], addDirs = [] }) {
+  const args = ['-p', prompt, '--output-format', 'stream-json', '--verbose']
+  if (permissionMode) args.push('--permission-mode', permissionMode)
+  if (model) args.push('--model', model)
+  if (resumeSessionId) args.push('--resume', resumeSessionId)
+  // Pre-approve read-only web tools (WebFetch/WebSearch) so they aren't auto-denied
+  // in headless, and grant read access to out-of-cwd dirs (the persisted screenshot
+  // + attachments). Both are <tool...>/<dir...> variadic flags (HAP-1096).
+  if (allowedTools.length) args.push('--allowedTools', ...allowedTools)
+  if (addDirs.length) args.push('--add-dir', ...addDirs)
+  const settings = buildSettings(pathGuardHook)
+  if (settings) args.push('--settings', settings)
+  return args
+}
+
+/**
+ * Build the child env for a run.
+ *
+ * The claude CLI authenticates one of two ways: an explicit
+ * `CLAUDE_CODE_OAUTH_TOKEN`, or its own auto-refreshing login credentials at
+ * `~/.claude/.credentials.json`. HAP-1116's outage was a *stale/expired* token
+ * (`401 authentication_failed`); the stopgap was to blank the token so the CLI
+ * falls back to the login credentials. Relying on the CLI treating an empty
+ * string as "no token" is brittle, so when no token is supplied we strip the
+ * var entirely rather than passing `''`. This makes the login-credentials path
+ * (the Phase-1 decision — "Claude Code CLI not API key") explicit and durable.
+ *
+ * @param {string} oauthToken
+ * @returns {NodeJS.ProcessEnv}
+ */
+function buildEnv(oauthToken) {
+  const env = { ...process.env }
+  if (oauthToken) {
+    env.CLAUDE_CODE_OAUTH_TOKEN = oauthToken
+  } else {
+    delete env.CLAUDE_CODE_OAUTH_TOKEN
+  }
+  return env
+}
+
+/**
+ * Run a single headless prompt.
+ *
+ * @param {Object} opts
+ * @param {string} opts.prompt
+ * @param {string} opts.cwd              - absolute staging site dir
+ * @param {string} opts.oauthToken
+ * @param {string} [opts.claudeBin]
+ * @param {string} [opts.permissionMode]
+ * @param {string} [opts.model]
+ * @param {string} [opts.resumeSessionId]
+ * @param {number} [opts.tokenCap]
+ * @param {number} [opts.timeoutMs]
+ * @param {function} [opts.spawnFn]      - injectable for tests (defaults to child_process.spawn)
+ * @returns {{ emitter: EventEmitter, abort: () => void, done: Promise<object> }}
+ *
+ * Emitter events: 'event' (ProgressEvent), 'error' (Error), 'end' (summary).
+ */
+function runPrompt(opts) {
+  const {
+    prompt,
+    cwd,
+    oauthToken,
+    claudeBin = 'claude',
+    permissionMode = 'acceptEdits',
+    model = '',
+    resumeSessionId = null,
+    tokenCap = 0,
+    timeoutMs = 0,
+    markupPct = 0,   // client-facing markup % stamped onto the result event (HAP-1123)
+    pathGuardHook = '',
+    allowedTools = [],  // tools pre-approved for headless (e.g. WebFetch/WebSearch) — HAP-1096
+    addDirs = [],       // extra readable dirs (screenshot + attachments tmp) — HAP-1096
+    spawnFn = spawn,
+  } = opts
+
+  const emitter = new EventEmitter()
+  const parser = new StreamParser()
+  const meter = new TokenMeter(tokenCap)
+
+  let sessionId = resumeSessionId || null
+  let runModel = model || null   // resolved from the CLI's session_start init
+  let lastCostUsd = null         // this turn's total_cost_usd (CLI source of truth)
+  let capTripped = false
+  let settled = false
+  let stderrTail = ''
+
+  const args = buildArgs({ prompt, permissionMode, model, resumeSessionId, pathGuardHook, allowedTools, addDirs })
+  const child = spawnFn(claudeBin, args, {
+    cwd,
+    env: buildEnv(oauthToken),
+    stdio: ['ignore', 'pipe', 'pipe'],
+  })
+
+  let timer = null
+  if (timeoutMs > 0) {
+    timer = setTimeout(() => {
+      emitter.emit('event', { kind: 'aborted', reason: 'timeout', timeoutMs })
+      kill()
+    }, timeoutMs)
+    if (timer.unref) timer.unref()
+  }
+
+  const done = new Promise((resolve) => {
+    const finish = (summary) => {
+      if (settled) return
+      settled = true
+      if (timer) clearTimeout(timer)
+      emitter.emit('end', summary)
+      resolve(summary)
+    }
+
+    function handleEvents(events) {
+      for (const ev of events) {
+        if (ev.kind === KINDS.SESSION_START && ev.sessionId) sessionId = ev.sessionId
+        if (ev.kind === KINDS.SESSION_START && ev.model) runModel = ev.model
+        if (ev.kind === KINDS.RESULT && ev.sessionId) sessionId = ev.sessionId
+        // Only assistant turns add to the meter. The final `result` message
+        // repeats a usage summary — recording it would double-count, so we just
+        // stamp the running snapshot onto it.
+        if (ev.usage && ev.kind !== KINDS.RESULT) meter.record(ev.usage)
+        if (ev.usage || ev.kind === KINDS.RESULT) ev.tokens = meter.snapshot()
+        // HAP-1123: the `result` message carries the CLI's authoritative
+        // total_cost_usd for this turn. Stamp the resolved model onto it (the
+        // result message itself omits model) so the drawer can show "$cost ·
+        // model" inline, and remember the cost for the run summary.
+        if (ev.kind === KINDS.RESULT) {
+          ev.model = runModel
+          if (typeof ev.costUsd === 'number') {
+            lastCostUsd = ev.costUsd
+            // Client-facing number (raw cost + markup) so the drawer shows what the
+            // client is billed without needing to know the markup rate itself.
+            ev.costMarkupPct = markupPct
+            ev.billedUsd = applyMarkup(ev.costUsd, markupPct)
+          }
+        }
+        emitter.emit('event', ev)
+        if (!capTripped && meter.exceeded) {
+          capTripped = true
+          emitter.emit('event', {
+            kind: 'aborted',
+            reason: 'token_cap',
+            tokens: meter.snapshot(),
+          })
+          kill()
+        }
+      }
+    }
+
+    child.stdout.on('data', (chunk) => handleEvents(parser.push(chunk)))
+    child.stderr.on('data', (chunk) => {
+      stderrTail = (stderrTail + chunk.toString()).slice(-4000)
+    })
+
+    child.on('error', (err) => {
+      emitter.emit('error', err)
+      finish({ ok: false, error: err.message, sessionId, model: runModel, costUsd: lastCostUsd, tokens: meter.snapshot() })
+    })
+
+    child.on('close', (code, signal) => {
+      handleEvents(parser.flush())
+      const ok = !capTripped && code === 0
+      finish({
+        ok,
+        code,
+        signal,
+        aborted: capTripped,
+        sessionId,
+        model: runModel,
+        costUsd: lastCostUsd,
+        tokens: meter.snapshot(),
+        stderr: ok ? undefined : stderrTail.trim() || undefined,
+      })
+    })
+  })
+
+  function kill() {
+    if (!child.killed) {
+      child.kill('SIGTERM')
+      // Hard-stop if it ignores SIGTERM.
+      setTimeout(() => { if (!child.killed) child.kill('SIGKILL') }, 3000).unref?.()
+    }
+  }
+
+  return { emitter, abort: kill, done, getSessionId: () => sessionId }
+}
+
+export { runPrompt, buildArgs, buildEnv, buildSettings }