mango-cms 0.3.34 → 0.3.36

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 }

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

@@ -0,0 +1,227 @@
+// config.js
+//
+// Centralized env reading + validation for the orchestrator. The OAuth token is
+// never read from git — it lives in /root/.vibe-orchestrator.env on the droplet
+// (chmod 600) and is sourced into the process env before launch (see README).
+
+import path from 'node:path'
+import fs from 'node:fs'
+import os from 'node:os'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+
+function envInt(name, fallback) {
+  const v = process.env[name]
+  if (v == null || v === '') return fallback
+  const n = Number.parseInt(v, 10)
+  return Number.isFinite(n) ? n : fallback
+}
+
+const config = {
+  // HTTP/SSE listen port for the orchestrator service.
+  port: envInt('VIBE_ORCH_PORT', 7130),
+
+  // Root under which each <site> is a clone, e.g. /root/Staging/<site>.
+  stagingRoot: process.env.VIBE_STAGING_ROOT || '/root/Staging',
+
+  // Whitelist of site slugs the orchestrator is allowed to operate on. Empty =>
+  // any directory directly under stagingRoot is permitted (still path-guarded).
+  allowedSites: (process.env.VIBE_ALLOWED_SITES || 'generations-vibe')
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean),
+
+  // claude CLI binary (v2.1.157 installed at /usr/local/bin/claude on droplet).
+  claudeBin: process.env.VIBE_CLAUDE_BIN || 'claude',
+
+  // Per-session cumulative token cap. 0 = unlimited. Raised from 200k → 2M
+  // (HAP-1096): a real vibe session reads files + viewport screenshots (images are
+  // token-heavy) and 200k was tripping mid-demo. Cost is still tracked + billed per
+  // turn, so this is a runaway-safety rail, not a budget — tune via VIBE_TOKEN_CAP.
+  tokenCap: envInt('VIBE_TOKEN_CAP', 2_000_000),
+
+  // Headless permission mode. Deliberately NOT bypassPermissions: this droplet is
+  // shared (it hosts ~40 other production sites) and the orchestrator runs as root,
+  // so blanket-allowing Bash would let an errant run `rm -rf` a sibling tenant — a
+  // blast radius the HAP-1124 path guard does NOT cover (it only matches Edit/Write,
+  // not Bash). acceptEdits keeps that destructive/network Bash gated while still
+  // auto-accepting file edits on the throwaway clone. The HAP-1096 web-fetch +
+  // screenshot-read failures are fixed surgically instead via `allowedTools` +
+  // `toolExtraDirs` below — read-only capabilities with no shared-droplet risk.
+  permissionMode: process.env.VIBE_PERMISSION_MODE || 'acceptEdits',
+
+  // Tools pre-approved for headless runs (no interactive approver exists, so
+  // otherwise-gated tools are auto-DENIED). WebFetch/WebSearch are read-only network
+  // reads with no filesystem/destructive risk — enabling them lets the owner say
+  // "use our real logo + brand blue from generations.org" and have it work (HAP-1096,
+  // where WebFetch showed "isn't permitted here"). Space/comma separated override.
+  allowedTools: (process.env.VIBE_ALLOWED_TOOLS || 'WebFetch WebSearch')
+    .split(/[\s,]+/)
+    .map((s) => s.trim())
+    .filter(Boolean),
+
+  // Extra directories the run's tools may access (--add-dir). The viewport
+  // screenshot and any pasted/uploaded attachments are persisted OUTSIDE the cwd
+  // (os.tmpdir()/vibe-orchestrator, so they never land in the editable clone); under
+  // acceptEdits the agent otherwise can't Read them — that is the HAP-1096 "screenshot
+  // file gated behind approval" failure. Allowing this one temp dir restores the read.
+  toolExtraDirs: (
+    process.env.VIBE_TOOL_EXTRA_DIRS
+    || path.join(os.tmpdir(), 'vibe-orchestrator')
+  )
+    .split(/[\s,]+/)
+    .map((s) => s.trim())
+    .filter(Boolean),
+
+  // Optional model override (e.g. claude-opus-4-8). Empty => CLI default.
+  model: process.env.VIBE_MODEL || '',
+
+  // The OAuth token. An EXPLICIT token is optional: when empty, live runs use
+  // the claude CLI's own auto-refreshing login credentials instead (the Phase-1
+  // decision — "Claude Code CLI not API key"). Never required for the server to
+  // boot — scaffold/stream-parse/session work runs token-free.
+  oauthToken: process.env.CLAUDE_CODE_OAUTH_TOKEN || '',
+
+  // Path to the claude CLI's auto-refreshing login credentials. When present,
+  // live runs work without an explicit oauthToken. Override only in tests.
+  claudeCredentialsPath:
+    process.env.VIBE_CLAUDE_CREDENTIALS
+    || path.join(os.homedir(), '.claude', '.credentials.json'),
+
+  // Wall-clock ceiling for a single claude invocation (ms). 0 = no timeout.
+  runTimeoutMs: envInt('VIBE_RUN_TIMEOUT_MS', 10 * 60 * 1000),
+
+  // ---- Publish (staging → prod via the existing pipeline; HAP-1103) ----
+
+  // Master switch for the publish endpoints. The actual `git push` is also
+  // gated by an explicit per-call confirm; this is the operator-level kill switch.
+  publishEnabled: String(process.env.VIBE_PUBLISH_ENABLED ?? 'true').toLowerCase() !== 'false',
+
+  // Remote the publish push targets (push to its tracked branch → ssh-deploy).
+  publishRemote: process.env.VIBE_PUBLISH_REMOTE || 'origin',
+
+  // Deploy branch each workspace branch merges INTO on publish. ssh-deploy only
+  // triggers on a push to this branch (`.github/workflows/ssh-deploy.yml` →
+  // update.sh on prod), so a per-branch workspace must merge here to reach prod.
+  // When a workspace is already on this branch, publish pushes it directly.
+  publishBranch: process.env.VIBE_PUBLISH_BRANCH || 'main',
+
+  // Env-specific file that must NEVER be pushed. The staging overlay materializes
+  // the staging block into it; publish restores it (`git checkout`) before commit.
+  settingsPath: process.env.VIBE_SETTINGS_PATH || 'mango/config/settings.json',
+
+  // ---- Self-protection: path guard + rollback (HAP-1124) ----
+
+  // Server-side denylist enforcement. When true, every live run is launched with
+  // a PreToolUse hook (scripts/path-guard-hook.mjs) that blocks edits to the Vibe
+  // system itself (drawer, orchestrator, staging spine, settings, deploy/CI). This
+  // is enforced regardless of the prompt. Disable only for tests/debugging.
+  pathGuardEnabled: String(process.env.VIBE_PATH_GUARD ?? 'true').toLowerCase() !== 'false',
+
+  // Absolute path to the PreToolUse hook script. Lives in the orchestrator tree
+  // (itself protected), never inside the editable site clone.
+  pathGuardHook:
+    process.env.VIBE_PATH_GUARD_HOOK
+    || path.resolve(__dirname, '..', 'scripts', 'path-guard-hook.mjs'),
+
+  // Auto-commit every applied vibe edit to the staging clone's git history and
+  // keep a known-good baseline tag, so there is always a way back (revert last /
+  // reset to baseline). Disable only for tests that drive a fake runner.
+  autoCommitEnabled: String(process.env.VIBE_AUTO_COMMIT ?? 'true').toLowerCase() !== 'false',
+
+  // Annotated tag marking the known-good baseline a "reset to baseline" returns to.
+  baselineTag: process.env.VIBE_BASELINE_TAG || 'vibe-baseline',
+
+  // ---- Owner auth (HAP-1109) ----
+
+  // HMAC secret shared ONLY between Mango (which mints owner tokens from an
+  // authenticated admin session) and this orchestrator (which verifies them).
+  // Lives in /root/.vibe-orchestrator.env on the droplet (chmod 600), never in
+  // git. UNSET ⇒ the orchestrator fails CLOSED: every gated endpoint returns 503
+  // until it is configured. This is the real per-owner gate that replaces the old
+  // optional shared secret.
+  tokenSecret: process.env.VIBE_ORCH_TOKEN_SECRET || '',
+
+  // Roles that count as a site owner (any match grants access).
+  ownerRoles: (process.env.VIBE_OWNER_ROLES || 'admin')
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean),
+
+  // ---- Cost tracking (HAP-1123) ----
+
+  // Client-facing markup on the RAW API cost, as a percentage (board request on
+  // HAP-1123). 100 ⇒ a 100% markup ⇒ the client is shown/billed 2× the raw cost.
+  // The raw CLI cost stays the persisted source of truth; the markup is applied
+  // only at display + rollup time so the rate can change without rewriting history.
+  markupPct: envInt('VIBE_COST_MARKUP_PCT', 100),
+
+  // Mango ingest endpoint that mirrors each per-turn cost record into the
+  // `vibeCosts` collection (queryable in the CMS for invoicing). UNSET ⇒ the
+  // mirror is a no-op and the orchestrator's local NDJSON log is the only store
+  // (the rollup endpoint reads from it either way). Authenticated with the shared
+  // VIBE_ORCH_TOKEN_SECRET as a bearer; intended to point at localhost Mango.
+  costMirrorUrl: process.env.VIBE_COST_MIRROR_URL || '',
+
+  // ---- CORS (HAP-1121) ----
+
+  // Browser origins allowed to call the orchestrator cross-origin. The ⌘K drawer
+  // is served from the SITE origin (e.g. https://staging-vibe.generations.org)
+  // and calls the orchestrator on the -api origin, so the browser issues a CORS
+  // preflight. Without an allow-list + preflight handling every call surfaces as
+  // "Failed to fetch". Empty list ⇒ reflect any origin (dev only). Prod + staging
+  // site origins are the defaults.
+  allowedOrigins: (
+    process.env.VIBE_ALLOWED_ORIGINS
+    || 'https://staging-vibe.generations.org,https://vibe.generations.org,http://localhost:7121'
+  )
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean),
+
+  // ---- Idle session reaping (HAP-1110) ----
+
+  // How long a session may sit idle (no prompts, no keepalive touches, no open
+  // readers) before it is reaped so the next prompt starts a fresh conversation.
+  // A running run or an open SSE reader always keeps it warm. 0 = never reap.
+  sessionIdleMs: envInt('VIBE_SESSION_IDLE_MS', 30 * 60 * 1000),
+
+  // How often the reaper sweeps. Kept well below sessionIdleMs.
+  reaperIntervalMs: envInt('VIBE_REAPER_INTERVAL_MS', 60 * 1000),
+}
+
+/** Resolve + validate a site slug to an absolute, in-root working directory. */
+function resolveSiteDir(site) {
+  if (!site || typeof site !== 'string' || !/^[a-zA-Z0-9._-]+$/.test(site)) {
+    throw new Error(`invalid site slug: ${JSON.stringify(site)}`)
+  }
+  if (config.allowedSites.length && !config.allowedSites.includes(site)) {
+    throw new Error(`site not in allowlist: ${site}`)
+  }
+  const dir = path.resolve(config.stagingRoot, site)
+  // Guard against traversal escaping the staging root.
+  if (dir !== path.join(config.stagingRoot, site)) {
+    throw new Error(`resolved path escapes staging root: ${site}`)
+  }
+  return dir
+}
+
+/** True when the claude CLI's auto-refreshing login credentials are present. */
+function hasCliCredentials() {
+  try {
+    return fs.existsSync(config.claudeCredentialsPath)
+  } catch {
+    return false
+  }
+}
+
+/**
+ * True when a live claude run is possible: either an explicit OAuth token is
+ * configured, OR the claude CLI has its own login credentials to fall back on.
+ */
+function canRunLive() {
+  return !!config.oauthToken || hasCliCredentials()
+}
+
+export { config, resolveSiteDir, canRunLive, hasCliCredentials }

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

@@ -0,0 +1,64 @@
+// costMirror.js
+//
+// Best-effort mirror of a per-turn cost record into the Mango `vibeCosts`
+// collection (HAP-1123). The orchestrator's NDJSON log (costStore) is the durable
+// system of record; this mirror makes the same record queryable in the CMS so the
+// board can invoice from it. A mango outage NEVER loses data — the local log
+// already has every record and the orchestrator rollup endpoint reads from it.
+//
+// Transport: a plain POST to the Mango ingest endpoint on localhost, authenticated
+// with the shared VIBE_ORCH_TOKEN_SECRET as a bearer. Disabled (no-op) unless
+// VIBE_COST_MIRROR_URL is configured, so it is fail-safe by default.
+
+import http from 'node:http'
+import https from 'node:https'
+import { config } from './config.js'
+
+/**
+ * POST one normalized cost record to the Mango ingest endpoint. Resolves to
+ * `{ ok }`; never rejects (callers treat it as fire-and-forget). No-op when the
+ * mirror URL or shared secret is unset.
+ *
+ * @param {object} entry              normalized cost record (from costStore)
+ * @param {object} [opts]
+ * @param {string} [opts.url]         override the mirror URL (tests)
+ * @param {string} [opts.secret]      override the bearer secret (tests)
+ * @param {function} [opts.requestFn] injectable transport (tests)
+ */
+function mirrorCost(entry, opts = {}) {
+  const url = opts.url || config.costMirrorUrl
+  const secret = opts.secret || config.tokenSecret
+  if (!url || !secret || !entry) return Promise.resolve({ ok: false, skipped: true })
+
+  return new Promise((resolve) => {
+    let target
+    try { target = new URL(url) } catch { return resolve({ ok: false, error: 'bad mirror url' }) }
+    const lib = target.protocol === 'https:' ? https : http
+    const requestFn = opts.requestFn || lib.request
+    const body = JSON.stringify(entry)
+    const req = requestFn(
+      {
+        hostname: target.hostname,
+        port: target.port,
+        path: target.pathname + target.search,
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json',
+          'content-length': Buffer.byteLength(body),
+          authorization: `Bearer ${secret}`,
+        },
+        timeout: 5000,
+      },
+      (res) => {
+        res.resume() // drain
+        resolve({ ok: res.statusCode >= 200 && res.statusCode < 300, status: res.statusCode })
+      },
+    )
+    req.on('error', () => resolve({ ok: false }))
+    req.on('timeout', () => { req.destroy(); resolve({ ok: false, error: 'timeout' }) })
+    req.write(body)
+    req.end()
+  })
+}
+
+export { mirrorCost }