@ghostlygawd/hangar 0.2.0

package/lib/transcripts.js

@@ -0,0 +1,266 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import chokidar from 'chokidar'
+import { projectsDirFor, mungeCwd } from './paths.js'
+import { detectLimit } from './limits.js'
+
+const ACTIVE_MS = 90_000
+const IDLE_MS = 30 * 60_000
+const RECENT_PARSE_MS = 48 * 3_600_000
+const FEED_CAP = 1000
+
+/**
+ * Watches Claude Code transcript JSONL files across all profile homes and
+ * keeps an in-memory view of every session. Pure file reads — observing a
+ * session costs zero tokens by construction.
+ */
+export class TranscriptWatcher {
+  /**
+   * @param {() => Array<{name: string, home: string}>} getProfiles
+   * @param {(event: object) => void} emit
+   * @param {(profile: string, hit: {kind: string, resetsAt?: string}) => void} onLimit
+   */
+  constructor(getProfiles, emit, onLimit) {
+    this.getProfiles = getProfiles
+    this.emit = emit
+    this.onLimit = onLimit
+    this.sessions = new Map() // sessionId → session view
+    this.offsets = new Map() // file → byte offset already parsed
+    this.fileProfile = new Map() // file → profile name
+    this.watcher = null
+  }
+
+  start() {
+    const roots = []
+    for (const p of this.getProfiles()) {
+      const dir = projectsDirFor(p.home)
+      if (fs.existsSync(dir)) roots.push({ dir, profile: p.name })
+    }
+    const paths = roots.map((r) => r.dir)
+    this.roots = roots
+    if (paths.length === 0) return
+    this.watcher = chokidar.watch(paths, {
+      ignoreInitial: false,
+      depth: 2,
+      awaitWriteFinish: { stabilityThreshold: 150, pollInterval: 50 },
+    })
+    this.watcher.on('add', (f) => this.#onFile(f, true))
+    this.watcher.on('change', (f) => this.#onFile(f, false))
+  }
+
+  stop() {
+    this.watcher?.close()
+  }
+
+  #profileFor(file) {
+    if (this.fileProfile.has(file)) return this.fileProfile.get(file)
+    const hit = this.roots.find((r) => file.toLowerCase().startsWith(r.dir.toLowerCase()))
+    const name = hit ? hit.profile : 'default'
+    this.fileProfile.set(file, name)
+    return name
+  }
+
+  #onFile(file, isAdd) {
+    if (!file.endsWith('.jsonl')) return
+    let st
+    try { st = fs.statSync(file) } catch { return }
+    // History older than the recent window parses lazily (on demand), not at startup.
+    if (isAdd && Date.now() - st.mtimeMs > RECENT_PARSE_MS) {
+      this.#registerLazy(file, st)
+      return
+    }
+    this.#consume(file)
+  }
+
+  #registerLazy(file, st) {
+    const sessionId = path.basename(file, '.jsonl')
+    if (this.sessions.has(sessionId)) return
+    this.sessions.set(sessionId, this.#blankSession(sessionId, file, st.mtimeMs, { lazy: true }))
+  }
+
+  /** Parse any unread bytes of a transcript file. */
+  #consume(file) {
+    let fd
+    try { fd = fs.openSync(file, 'r') } catch { return }
+    try {
+      const size = fs.fstatSync(fd).size
+      const from = this.offsets.get(file) ?? 0
+      if (size <= from) return
+      const buf = Buffer.alloc(size - from)
+      fs.readSync(fd, buf, 0, buf.length, from)
+      const text = buf.toString('utf8')
+      const lastNl = text.lastIndexOf('\n')
+      if (lastNl === -1) return // torn single line — wait for more
+      this.offsets.set(file, from + Buffer.byteLength(text.slice(0, lastNl + 1)))
+      for (const line of text.slice(0, lastNl).split('\n')) {
+        if (line.trim()) this.#line(file, line)
+      }
+    } finally {
+      fs.closeSync(fd)
+    }
+  }
+
+  /** Force-parse a lazy session's full history (used when the UI opens it). */
+  hydrate(sessionId) {
+    const s = this.sessions.get(sessionId)
+    if (!s || !s.lazy) return
+    s.lazy = false
+    this.#consume(s.file)
+  }
+
+  #blankSession(sessionId, file, mtimeMs, extra = {}) {
+    return {
+      id: sessionId,
+      file,
+      profile: this.#profileFor(file),
+      cwd: null,
+      gitBranch: null,
+      firstTs: null,
+      lastTs: mtimeMs ? new Date(mtimeMs).toISOString() : null,
+      entries: [],
+      usage: { input: 0, output: 0, cacheRead: 0, cacheCreation: 0 },
+      lastContext: null,
+      model: null,
+      ...extra,
+    }
+  }
+
+  #line(file, line) {
+    let obj
+    try { obj = JSON.parse(line) } catch { return }
+
+    const limit = detectLimit(obj)
+    if (limit) this.onLimit(this.#profileFor(file), limit)
+
+    const sessionId = obj.sessionId || path.basename(file, '.jsonl')
+    let s = this.sessions.get(sessionId)
+    if (!s) {
+      s = this.#blankSession(sessionId, file, null)
+      this.sessions.set(sessionId, s)
+    }
+
+    if (obj.cwd && !s.cwd) s.cwd = obj.cwd
+    if (obj.gitBranch) s.gitBranch = obj.gitBranch
+    if (obj.timestamp) {
+      if (!s.firstTs) s.firstTs = obj.timestamp
+      s.lastTs = obj.timestamp
+    }
+    if (obj.isSidechain) return // subagent side-channels stay out of the main feed
+
+    const entry = toEntry(obj)
+    if (!entry) return
+    entry.ts = obj.timestamp || new Date().toISOString()
+
+    if (entry.usage) {
+      s.usage.input += entry.usage.input_tokens || 0
+      s.usage.output += entry.usage.output_tokens || 0
+      s.usage.cacheRead += entry.usage.cache_read_input_tokens || 0
+      s.usage.cacheCreation += entry.usage.cache_creation_input_tokens || 0
+      s.lastContext =
+        (entry.usage.input_tokens || 0) +
+        (entry.usage.cache_read_input_tokens || 0) +
+        (entry.usage.cache_creation_input_tokens || 0)
+      delete entry.usage
+    }
+    if (entry.model) s.model = entry.model
+
+    s.entries.push(entry)
+    if (s.entries.length > FEED_CAP) s.entries.splice(0, s.entries.length - FEED_CAP)
+    this.emit({ type: 'message', sessionId, profile: s.profile, cwd: s.cwd, entry })
+  }
+
+  /** Lightweight session summaries for the board/activity views. */
+  list() {
+    const now = Date.now()
+    return [...this.sessions.values()].map((s) => ({
+      id: s.id,
+      profile: s.profile,
+      cwd: s.cwd,
+      gitBranch: s.gitBranch,
+      firstTs: s.firstTs,
+      lastTs: s.lastTs,
+      state: stateOf(s.lastTs, now),
+      usage: s.usage,
+      lastContext: s.lastContext,
+      model: s.model,
+      entryCount: s.entries.length,
+      lazy: !!s.lazy,
+      lastEntry: s.entries[s.entries.length - 1] ?? null,
+    }))
+  }
+
+  feed(sessionId, from = 0) {
+    this.hydrate(sessionId)
+    const s = this.sessions.get(sessionId)
+    if (!s) return null
+    return {
+      id: s.id,
+      profile: s.profile,
+      cwd: s.cwd,
+      state: stateOf(s.lastTs, Date.now()),
+      usage: s.usage,
+      lastContext: s.lastContext,
+      model: s.model,
+      total: s.entries.length,
+      entries: s.entries.slice(Math.max(0, from)),
+    }
+  }
+}
+
+function stateOf(lastTs, now) {
+  if (!lastTs) return 'ended'
+  const age = now - Date.parse(lastTs)
+  if (age < ACTIVE_MS) return 'active'
+  if (age < IDLE_MS) return 'idle'
+  return 'ended'
+}
+
+/** Map one transcript object to a feed entry, or null for non-display lines. */
+function toEntry(obj) {
+  if (obj.type === 'user' && obj.message?.role === 'user') {
+    const c = obj.message.content
+    if (typeof c === 'string') {
+      if (c.startsWith('<local-command') || c.startsWith('<command-name>')) return null
+      return { kind: 'user', text: clip(c, 2000) }
+    }
+    if (Array.isArray(c)) {
+      const results = c.filter((b) => b.type === 'tool_result')
+      if (results.length) return { kind: 'tool_result', count: results.length }
+      const text = c.filter((b) => b.type === 'text').map((b) => b.text).join('\n')
+      return text ? { kind: 'user', text: clip(text, 2000) } : null
+    }
+    return null
+  }
+
+  if (obj.type === 'assistant' && obj.message) {
+    const blocks = Array.isArray(obj.message.content) ? obj.message.content : []
+    const text = blocks.filter((b) => b.type === 'text').map((b) => b.text).join('\n')
+    const tools = blocks
+      .filter((b) => b.type === 'tool_use')
+      .map((b) => ({ name: b.name, hint: toolHint(b.name, b.input) }))
+    if (!text && tools.length === 0) return null
+    return {
+      kind: 'assistant',
+      text: clip(text, 2000),
+      tools,
+      usage: obj.message.usage,
+      model: obj.message.model,
+    }
+  }
+
+  return null
+}
+
+function toolHint(name, input) {
+  if (!input || typeof input !== 'object') return ''
+  const v =
+    input.file_path || input.path || input.command || input.pattern ||
+    input.query || input.url || input.description || input.prompt || ''
+  return clip(String(v).split('\n')[0], 120)
+}
+
+function clip(s, n) {
+  return s.length > n ? `${s.slice(0, n)}…` : s
+}
+
+export { mungeCwd }

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@ghostlygawd/hangar",
+  "version": "0.2.0",
+  "description": "A free, open-source cockpit for parallel Claude Code on Windows — isolated worktree spaces, real interactive sessions, multi-account, zero-token observability.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "bin": {
+    "hangar": "bin/hangar.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "server/",
+    "web/dist/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "start": "node bin/hangar.js",
+    "test": "vitest run",
+    "web:dev": "npm --prefix web run dev",
+    "web:build": "npm --prefix web run build",
+    "prepublishOnly": "npm run web:build"
+  },
+  "dependencies": {
+    "@fastify/static": "^8.0.0",
+    "chokidar": "^4.0.0",
+    "fastify": "^5.0.0",
+    "qrcode-terminal": "^0.12.0",
+    "systeminformation": "^5.23.0"
+  },
+  "devDependencies": {
+    "vitest": "^3.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GhostlyGawd/hangar.git"
+  },
+  "homepage": "https://ghostlygawd.github.io/hangar",
+  "bugs": {
+    "url": "https://github.com/GhostlyGawd/hangar/issues"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "worktree",
+    "parallel",
+    "agents",
+    "windows",
+    "cockpit"
+  ]
+}

package/server/bus.js

@@ -0,0 +1,60 @@
+/** Tiny SSE fan-out. Subscribers are raw HTTP responses. */
+export class Bus {
+  constructor() {
+    this.clients = new Set()
+    this.heartbeats = new Map()
+  }
+
+  publish(event) {
+    const frame = `data: ${JSON.stringify(event)}\n\n`
+    for (const res of this.clients) this.#write(res, frame)
+  }
+
+  /** Write to one client; a dead/broken socket is dropped, never thrown — one
+   *  stale tab must not starve every other client of events. */
+  #write(res, frame) {
+    if (res.writableEnded || res.destroyed) { this.#drop(res); return }
+    try {
+      res.write(frame)
+    } catch {
+      this.#drop(res)
+    }
+  }
+
+  #drop(res) {
+    const hb = this.heartbeats.get(res)
+    if (hb) { clearInterval(hb); this.heartbeats.delete(res) }
+    this.clients.delete(res)
+    try { res.destroy() } catch { /* best effort */ }
+  }
+
+  /** Attach a fastify reply as an SSE stream. */
+  attach(reply) {
+    // hand the response lifecycle to us — without this Fastify 5 also tries to
+    // send its own reply on the already-written socket (FST_ERR_REP_ALREADY_SENT).
+    reply.hijack()
+    const res = reply.raw
+    res.writeHead(200, {
+      'content-type': 'text/event-stream',
+      'cache-control': 'no-cache',
+      connection: 'keep-alive',
+      'x-accel-buffering': 'no',
+    })
+    res.write(': hangar\n\n')
+    this.clients.add(res)
+    const heartbeat = setInterval(() => this.#write(res, ': hb\n\n'), 15000)
+    this.heartbeats.set(res, heartbeat)
+    res.on('close', () => this.#drop(res))
+  }
+
+  /** Clear heartbeats and end every stream so the server can shut down cleanly. */
+  close() {
+    for (const res of this.clients) {
+      const hb = this.heartbeats.get(res)
+      if (hb) clearInterval(hb)
+      try { res.end() } catch { /* best effort */ }
+    }
+    this.heartbeats.clear()
+    this.clients.clear()
+  }
+}

package/server/gate.js

@@ -0,0 +1,50 @@
+import crypto from 'node:crypto'
+
+function timingSafeTokenEqual(candidate, expected) {
+  if (typeof candidate !== 'string') return false
+  const a = Buffer.from(candidate)
+  const b = Buffer.from(expected)
+  if (a.length !== b.length) return false
+  return crypto.timingSafeEqual(a, b)
+}
+
+function cookieValue(header, name) {
+  if (!header) return undefined
+  for (const part of header.split(';')) {
+    const eq = part.indexOf('=')
+    if (eq === -1) continue
+    if (part.slice(0, eq).trim() === name) return decodeURIComponent(part.slice(eq + 1).trim())
+  }
+  return undefined
+}
+
+/**
+ * Token gate. Off when no token is configured (localhost-only use).
+ * When on: EVERYTHING is gated except /api/health — the API, the live SSE
+ * stream, AND the dashboard shell + assets. Auth comes from ?token=,
+ * Authorization: Bearer, or a session cookie; the compare is timing-safe.
+ *
+ * The cookie is what lets a phone work: it opens the tunnel link once with
+ * ?token=…, which we validate and echo back as an HttpOnly cookie, so the
+ * follow-up asset/document requests (which carry no query) still pass.
+ */
+export function registerGate(app, getToken) {
+  app.addHook('preHandler', async (request, reply) => {
+    const expected = getToken()
+    if (!expected) return
+    const route = request.routeOptions?.url ?? request.url
+    if (route === '/api/health') return
+    const query = request.query ?? {}
+    const auth = request.headers.authorization
+    const fromRequest = query.token ?? (auth?.startsWith('Bearer ') ? auth.slice(7) : undefined)
+    const cookie = cookieValue(request.headers.cookie, 'hangar_token')
+    const candidate = fromRequest ?? cookie
+    if (!timingSafeTokenEqual(candidate, expected)) {
+      return reply.code(401).send({ error: 'unauthorized' })
+    }
+    // establish a session so subsequent no-query asset/document loads pass
+    if (fromRequest !== undefined && cookie !== expected) {
+      reply.header('set-cookie', `hangar_token=${encodeURIComponent(expected)}; Path=/; HttpOnly; SameSite=Strict`)
+    }
+  })
+}

package/server/index.js

@@ -0,0 +1,67 @@
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { createRequire } from 'node:module'
+import Fastify from 'fastify'
+import fastifyStatic from '@fastify/static'
+import { JsonStore } from '../lib/store.js'
+import { CONFIG_FILE, REPOS_FILE, PARKED_FILE, DEFAULT_CONFIG } from '../lib/paths.js'
+import { listProfiles } from '../lib/profiles.js'
+import { TranscriptWatcher } from '../lib/transcripts.js'
+import { SystemMonitor } from '../lib/sysinfo.js'
+import { Bus } from './bus.js'
+import { registerGate } from './gate.js'
+import { registerRoutes } from './routes.js'
+
+const here = path.dirname(fileURLToPath(import.meta.url))
+const require = createRequire(import.meta.url)
+const { version } = require('../package.json')
+
+export async function startServer(overrides = {}) {
+  const config = new JsonStore(CONFIG_FILE, DEFAULT_CONFIG)
+  const repos = new JsonStore(REPOS_FILE, { repos: [] })
+  const parked = new JsonStore(PARKED_FILE, {})
+
+  const bind = overrides.bind ?? config.data.bind
+  const port = overrides.port ?? config.data.port
+  const LOOPBACK = new Set(['127.0.0.1', 'localhost', '::1'])
+  const lanExposed = !LOOPBACK.has(bind)
+  if (lanExposed && !config.data.token && !overrides.token) {
+    throw new Error('Refusing to bind beyond localhost without a token. Set one: hangar config token <value>')
+  }
+
+  const bus = new Bus()
+
+  const transcripts = new TranscriptWatcher(
+    () => listProfiles(),
+    (event) => bus.publish(event),
+    (profile, hit) => {
+      const existing = parked.data[profile]
+      if (existing && existing.reason === hit.kind) return
+      parked.update((d) => {
+        d[profile] = { profile, limitedAt: new Date().toISOString(), reason: hit.kind, resetAt: hit.resetsAt }
+      })
+      bus.publish({ type: 'parked', parked: parked.data })
+    },
+  )
+  transcripts.start()
+
+  const sysmon = new SystemMonitor((event) => bus.publish(event), () => bus.clients.size > 0)
+  sysmon.start()
+
+  const app = Fastify({ logger: false })
+  registerGate(app, () => overrides.token ?? config.data.token)
+  registerRoutes(app, { repos, parked, config, transcripts, sysmon, bus, version })
+
+  app.register(fastifyStatic, {
+    root: path.join(here, '..', 'web', 'dist'),
+    prefix: '/',
+  })
+  app.setNotFoundHandler((req, reply) => {
+    // SPA fallback for client-side routes; API misses stay JSON 404s
+    if (req.raw.url?.startsWith('/api/')) return reply.code(404).send({ error: 'not found' })
+    return reply.sendFile('index.html')
+  })
+
+  await app.listen({ port, host: bind })
+  return { app, port, bind, config, stop: async () => { transcripts.stop(); sysmon.stop(); bus.close(); await app.close() } }
+}

package/server/routes.js

@@ -0,0 +1,166 @@
+import crypto from 'node:crypto'
+import { isRepoRoot, currentBranch } from '../lib/git.js'
+import { listSpaces, createSpace, deleteSpace, spacePath } from '../lib/spaces.js'
+import { listProfiles, addProfile, removeProfile } from '../lib/profiles.js'
+import { launchSession, liveness } from '../lib/launch.js'
+
+export function registerRoutes(app, ctx) {
+  const { repos, parked, config, transcripts, sysmon } = ctx
+
+  app.get('/api/health', async () => ({ ok: true, name: 'hangar', version: ctx.version }))
+
+  // ----- full snapshot the UI boots from -----
+  app.get('/api/state', async () => {
+    const out = await Promise.all(repos.data.repos.map(async (r) => {
+      const [spaces, branch] = await Promise.all([
+        listSpaces(r.path).catch(() => []),
+        currentBranch(r.path).catch(() => null),
+      ])
+      return { ...r, branch, spaces }
+    }))
+    return {
+      repos: out,
+      profiles: listProfiles().map(({ home, ...p }) => ({ ...p })),
+      parked: parked.data,
+      sessions: attachSessions(transcripts.list(), repos.data.repos),
+      windows: liveness(),
+      config: { port: config.data.port, bind: config.data.bind, tokenSet: !!config.data.token },
+    }
+  })
+
+  // ----- repos -----
+  app.post('/api/repos', async (req, reply) => {
+    // store canonical Windows form so cwd-prefix joins are reliable
+    const p = String(req.body?.path ?? '').trim().replace(/\//g, '\\').replace(/\\+$/, '')
+    if (!p) return reply.code(400).send({ error: 'path is required' })
+    if (!(await isRepoRoot(p))) {
+      return reply.code(400).send({ error: `"${p}" is not the top level of a git repository.` })
+    }
+    const existing = repos.data.repos.find((r) => samePath(r.path, p))
+    if (existing) return existing
+    const entry = { id: crypto.randomUUID().slice(0, 8), name: p.replace(/[\\/]+$/, '').split(/[\\/]/).pop(), path: p, addedAt: new Date().toISOString() }
+    repos.update((d) => d.repos.push(entry))
+    return entry
+  })
+
+  app.delete('/api/repos/:id', async (req, reply) => {
+    const before = repos.data.repos.length
+    repos.update((d) => { d.repos = d.repos.filter((r) => r.id !== req.params.id) })
+    if (repos.data.repos.length === before) return reply.code(404).send({ error: 'unknown repo' })
+    return { ok: true }
+  })
+
+  // ----- spaces -----
+  app.post('/api/repos/:id/spaces', async (req, reply) => {
+    const repo = repos.data.repos.find((r) => r.id === req.params.id)
+    if (!repo) return reply.code(404).send({ error: 'unknown repo' })
+    const res = await createSpace(repo.path, String(req.body?.name ?? ''))
+    if (!res.ok) return reply.code(res.status).send({ error: res.error })
+    ctx.bus.publish({ type: 'spaces' })
+    return res
+  })
+
+  app.delete('/api/repos/:id/spaces/:name', async (req, reply) => {
+    const repo = repos.data.repos.find((r) => r.id === req.params.id)
+    if (!repo) return reply.code(404).send({ error: 'unknown repo' })
+    const res = await deleteSpace(repo.path, req.params.name, {
+      force: req.query?.force === '1',
+      confirm: req.query?.confirm ?? '',
+    })
+    if (!res.ok) return reply.code(res.status).send({ error: res.error })
+    ctx.bus.publish({ type: 'spaces' })
+    return res
+  })
+
+  // ----- launch (real interactive windows only) -----
+  app.post('/api/launch', async (req, reply) => {
+    const { repoId, space, profile = 'default', prompt = '' } = req.body ?? {}
+    const repo = repos.data.repos.find((r) => r.id === repoId)
+    if (!repo) return reply.code(404).send({ error: 'unknown repo' })
+    const cwd = space ? spacePath(repo.path, String(space)) : repo.path
+    const known = listProfiles().some((p) => p.name === profile)
+    if (!known) return reply.code(400).send({ error: `unknown profile "${profile}"` })
+    const res = await launchSession({ cwd, profile, prompt: String(prompt ?? '') })
+    if (!res.ok) return reply.code(500).send({ error: res.error })
+    ctx.bus.publish({ type: 'windows' })
+    return res
+  })
+
+  // ----- sessions -----
+  app.get('/api/sessions', async () => attachSessions(transcripts.list(), repos.data.repos))
+
+  app.get('/api/sessions/:id', async (req, reply) => {
+    const from = Number(req.query?.from ?? 0)
+    const feed = transcripts.feed(req.params.id, Number.isFinite(from) ? from : 0)
+    if (!feed) return reply.code(404).send({ error: 'unknown session' })
+    return feed
+  })
+
+  // ----- profiles -----
+  app.get('/api/profiles', async () => ({
+    profiles: listProfiles().map(({ home, ...p }) => p),
+    parked: parked.data,
+  }))
+
+  app.post('/api/profiles', async (req, reply) => {
+    const res = addProfile(String(req.body?.name ?? ''), req.body?.displayName)
+    if (!res.ok) return reply.code(res.status).send({ error: res.error })
+    return res
+  })
+
+  app.delete('/api/profiles/:name', async (req, reply) => {
+    const res = removeProfile(req.params.name)
+    if (!res.ok) return reply.code(res.status).send({ error: res.error })
+    return res
+  })
+
+  app.post('/api/parked/clear', async (req) => {
+    const name = String(req.body?.profile ?? '')
+    parked.update((d) => { delete d[name] })
+    ctx.bus.publish({ type: 'parked', parked: parked.data })
+    return { ok: true }
+  })
+
+  // ----- system -----
+  app.get('/api/system', async () => sysmon.snapshot())
+
+  // ----- config -----
+  app.put('/api/config', async (req) => {
+    const allowed = ['port', 'bind', 'token', 'defaultProfile']
+    config.update((d) => {
+      for (const k of allowed) {
+        if (k in (req.body ?? {})) d[k] = req.body[k]
+      }
+    })
+    return { ok: true, restartNeeded: ['port', 'bind'].some((k) => k in (req.body ?? {})) }
+  })
+
+  // ----- live events -----
+  app.get('/api/events', (req, reply) => {
+    ctx.bus.attach(reply)
+  })
+}
+
+/** Join sessions to tracked repos/spaces by cwd prefix (slash-direction agnostic). */
+function attachSessions(sessions, repoList) {
+  const norm = (p) => p.replace(/\//g, '\\').replace(/\\+$/, '').toLowerCase()
+  return sessions
+    .map((s) => {
+      if (!s.cwd) return { ...s, repoId: null, space: null }
+      const cwd = norm(s.cwd)
+      const repo = repoList.find((r) => {
+        const rp = norm(r.path)
+        return cwd === rp || cwd.startsWith(rp + '\\')
+      })
+      if (!repo) return null // sessions outside tracked repos stay out of the cockpit
+      const rest = cwd.slice(norm(repo.path).length).replace(/^\\/, '')
+      const m = rest.match(/^\.hangar-spaces\\([^\\]+)/)
+      return { ...s, repoId: repo.id, repoName: repo.name, space: m ? m[1] : null }
+    })
+    .filter(Boolean)
+}
+
+function samePath(a, b) {
+  const n = (x) => x.replace(/\//g, '\\').replace(/\\+$/, '').toLowerCase()
+  return n(a) === n(b)
+}