@henryz2004/agency 1.0.0

package/scripts/animsheet.mjs

@@ -0,0 +1,60 @@
+// animsheet.mjs — a film-strip of every character & pet ANIMATION to
+// docs/animations.png: one row per animation, columns = consecutive frames left
+// to right (read a row like a flip-book). Static poses only — to watch them move,
+// run `npm start` and open /lab.html. Some rows jump to a specific frame window so
+// a given idle fidget (which fires on a seed-staggered cadence) is guaranteed to
+// show; the console prints the row legend.
+//
+//   node scripts/animsheet.mjs
+import { writeFileSync } from 'node:fs';
+import { Ctx, encodePNG, upscale, selfCheckPNG } from './_pixpng.mjs';
+import { drawPerson, drawWalker, drawCat, drawDog } from '../public/sprites.js';
+
+selfCheckPNG();
+
+// idle fidgets fire when (frame + seed*37) % 116 < 22, cycling kind 0→1→2 each
+// period. seed 0 → window starts at frame 0 (kind 0), 116 (kind 1), 232 (kind 2).
+const clips = [
+  { name: 'seated · typing',     kind: 'person', seed: 7, act: 'working',                f: (i) => i },
+  { name: 'seated · sip coffee', kind: 'person', seed: 0, act: 'idle',                   f: (i) => i * 3 },
+  { name: 'seated · stretch',    kind: 'person', seed: 0, act: 'idle',                   f: (i) => 116 + i * 3 },
+  { name: 'seated · lean back',  kind: 'person', seed: 0, act: 'idle',                   f: (i) => 232 + i * 3 },
+  { name: 'seated · wave (done)',kind: 'person', seed: 3, act: 'idle', unread: true,     f: (i) => i },
+  { name: 'walk cycle',          kind: 'walker', seed: 5, walking: true,                 f: (i) => i },
+  { name: 'idle · check phone',  kind: 'walker', seed: 0, walking: false,                f: (i) => i * 3 },
+  { name: 'idle · stretch',      kind: 'walker', seed: 0, walking: false,                f: (i) => 116 + i * 3 },
+  { name: 'cat · walk',          kind: 'cat',    mode: 'walk',                           f: (i) => i * 2 },
+  { name: 'cat · groom',         kind: 'cat',    mode: 'sit',                            f: (i) => i },
+  { name: 'cat · sleep',         kind: 'cat',    mode: 'sleep',                          f: (i) => i * 2 },
+  { name: 'cat · petted',        kind: 'cat',    mode: 'pet',                            f: (i) => i },
+  { name: 'dog · pant/look',     kind: 'dog',    mode: 'idle',                           f: (i) => 6 + i },
+  { name: 'dog · yawn',          kind: 'dog',    mode: 'yawn',                           f: (i) => 99 + i },
+  { name: 'dog · petted',        kind: 'dog',    mode: 'pet',                            f: (i) => i },
+];
+
+const FR = 8, CW = 30, CH = 46, M = 12, SCALE = 5, BG = '#1b1e26';
+const W = M * 2 + FR * CW, H = M * 2 + clips.length * CH;
+const ctx = new Ctx(W, H, BG);
+
+function render(clip, cx, top, bottom, frame) {
+  if (clip.kind === 'person') drawPerson(ctx, cx, top + 9, { seed: clip.seed, activity: clip.act, frame, unread: !!clip.unread });
+  else if (clip.kind === 'walker') drawWalker(ctx, cx, bottom - 5, { seed: clip.seed, frame, walking: clip.walking });
+  else if (clip.kind === 'cat') {
+    const o = clip.mode === 'sleep' ? { sleeping: true } : clip.mode === 'pet' ? { petted: true } : clip.mode === 'walk' ? { walking: true } : {};
+    drawCat(ctx, cx - 6, bottom - 5, frame, 1, o);
+  } else drawDog(ctx, cx - 9, bottom - 5, { frame, petted: clip.mode === 'pet' });
+}
+
+clips.forEach((clip, r) => {
+  const top = M + r * CH, bottom = top + CH;
+  // pets live on the warm office floor and the cat is near-black — give the pet
+  // rows a floor band so they read (workers stay on dark so their torsos fade out).
+  if (clip.kind === 'cat' || clip.kind === 'dog') { ctx.fillStyle = '#a8814e'; ctx.fillRect(M, top, W - M * 2, CH); }
+  for (let i = 0; i < FR; i++) render(clip, M + i * CW + CW / 2, top, bottom, clip.f(i));
+  if (r) { ctx.fillStyle = 'rgba(255,255,255,0.07)'; ctx.fillRect(M, top, W - M * 2, 1); } // row divider
+});
+
+const out = new URL('../docs/animations.png', import.meta.url);
+writeFileSync(out, encodePNG(W * SCALE, H * SCALE, upscale(ctx.buf, W, H, SCALE)));
+console.log(`wrote ${out.pathname} — ${W * SCALE}×${H * SCALE}px, ${clips.length} animations × ${FR} frames`);
+clips.forEach((c, r) => console.log(`  row ${r + 1}: ${c.name}`));

package/scripts/charsheet.mjs

@@ -0,0 +1,61 @@
+// charsheet.mjs — render a contact sheet of every procedural character variation
+// to docs/characters.png. Zero deps: the renderers only use fillStyle+fillRect,
+// so scripts/_pixpng.mjs runs them headlessly and dumps a PNG (stdlib zlib).
+// Re-run after tweaking palettes / hair styles / clothing in public/sprites.js.
+//
+//   node scripts/charsheet.mjs
+import { writeFileSync } from 'node:fs';
+import { Ctx, encodePNG, upscale, selfCheckPNG } from './_pixpng.mjs';
+import { drawWalker, personLook, SKINS, HAIRS, SHIRTS, HAIR_STYLES, TOPS } from '../public/sprites.js';
+
+selfCheckPNG(); // throws if the shim/encoder is broken — fail before writing a bad file
+
+// ---- the sheet: three stacked sections, each a centred grid of walkers -------
+const CELL_W = 28, CELL_H = 50, SCALE = 4, BG = '#1b1e26';
+const clean = (l) => ({ ...l, glasses: false, beard: false });
+
+// Section 1 — hair styles (cols, each its own palette) × face accessory (rows).
+const hairCols = [];
+for (let c = 0; c < HAIR_STYLES; c++) { const b = clean(personLook(c * 7919 + 13)); b.hairStyle = c; b.top = 0; hairCols.push(b); }
+const faceRows = [(l) => l, (l) => ({ ...l, glasses: true }), (l) => ({ ...l, beard: true }), (l) => ({ ...l, glasses: true, beard: true })];
+const sec1 = faceRows.map((f) => hairCols.map((b) => f(b)));
+
+// Section 2 — clothing styles (cols) × colorways (rows): each row is one person
+// wearing every `top`, rows differ in palette so colors vary too.
+const sec2 = [111, 222, 333, 444].map((seed) => {
+  const b = clean(personLook(seed));
+  return Array.from({ length: TOPS }, (_, t) => ({ ...b, top: t }));
+});
+
+// Section 3 — palette sweeps: every skin tone, hair color, shirt color.
+const base = clean(personLook(42)); base.top = 0;
+const sec3 = [
+  SKINS.map((skin) => ({ ...base, skin, hairStyle: 0 })),
+  HAIRS.map((hair) => ({ ...base, hair, hairStyle: 0 })),
+  SHIRTS.map((shirt) => ({ ...base, shirt, hairStyle: 2 })),
+];
+
+const sections = [sec1, sec2, sec3];
+const M = 16, GAP = 22;
+const secW = (s) => Math.max(...s.map((r) => r.length)) * CELL_W;
+const W = M * 2 + Math.max(...sections.map(secW));
+const H = M * 2 + sections.reduce((n, s) => n + s.length * CELL_H, 0) + GAP * (sections.length - 1);
+const ctx = new Ctx(W, H, BG);
+
+const place = (look, gridX, col, gridY, row) =>
+  drawWalker(ctx, gridX + col * CELL_W + CELL_W / 2, gridY + row * CELL_H + CELL_H - 6, { look, frame: 0, walking: false });
+
+let y = M;
+sections.forEach((sec, si) => {
+  const gx = M + Math.round((W - M * 2 - secW(sec)) / 2);
+  sec.forEach((looks, r) => looks.forEach((l, c) => place(l, gx, c, y, r)));
+  y += sec.length * CELL_H;
+  if (si < sections.length - 1) { ctx.fillStyle = 'rgba(255,255,255,0.10)'; ctx.fillRect(M, Math.round(y + GAP / 2), W - M * 2, 1); y += GAP; }
+});
+
+// ---- encode + write ---------------------------------------------------------
+const out = new URL('../docs/characters.png', import.meta.url);
+const big = upscale(ctx.buf, W, H, SCALE);
+writeFileSync(out, encodePNG(W * SCALE, H * SCALE, big));
+const count = sections.reduce((n, s) => n + s.reduce((m, r) => m + r.length, 0), 0);
+console.log(`wrote ${out.pathname} — ${W * SCALE}×${H * SCALE}px, ${count} characters`);

package/scripts/install-hook.mjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+// install-hook.mjs — idempotently merge Agency's global Stop hook into
+// ~/.claude/settings.json so paused Claude Code agents can be answered from the
+// dashboard (Control Phase-1).
+//
+// THE HOOK: a Stop hook of type "http" pointed at Agency's /api/hook/stop. When
+// an agent stops, Claude Code POSTs the hook and BLOCKS until we respond; Agency
+// holds that connection open until you reply (or a soft deadline), then resumes
+// or stops the agent. The hook FAILS OPEN: if Agency isn't running (connection
+// refused) or times out, the agent just stops normally — so installing this is
+// safe even when the dashboard is closed.
+//
+// This is USER OPT-IN. The merge mirrors judge's installer (idempotent: it
+// won't add a second Agency entry if one already exists, and it preserves any
+// other hooks you have). It writes ONLY ~/.claude/settings.json (your hook
+// config) — never the session/usage data Agency reads.
+//
+// Usage:
+//   node scripts/install-hook.mjs            # install/merge
+//   node scripts/install-hook.mjs --uninstall  # remove only Agency's entry
+//   node scripts/install-hook.mjs --print      # show the entry, write nothing
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+const PORT = process.env.PORT ? Number(process.env.PORT) : 4313;
+const HOST = process.env.HOST || '127.0.0.1';
+const HOOK_URL = `http://${HOST}:${PORT}/api/hook/stop`;
+const HOOK_TIMEOUT = 120; // seconds — must exceed Agency's ~110s soft deadline
+
+const SETTINGS = path.join(os.homedir(), '.claude', 'settings.json');
+
+// The hook entry we install. We tag it by its URL path so we can find/replace
+// our own entry on re-runs without disturbing anyone else's Stop hooks.
+const AGENCY_SIG = '/api/hook/stop';
+function agencyEntry() {
+  return { hooks: [{ type: 'http', url: HOOK_URL, timeout: HOOK_TIMEOUT }] };
+}
+
+// Does this Stop-hook entry belong to Agency? (matches any port/host install.)
+function isAgencyEntry(entry) {
+  return (
+    entry &&
+    Array.isArray(entry.hooks) &&
+    entry.hooks.some((h) => h && h.type === 'http' && typeof h.url === 'string' && h.url.includes(AGENCY_SIG))
+  );
+}
+
+function loadSettings(file) {
+  if (!fs.existsSync(file)) return {};
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch (err) {
+    console.error(`Can't read ${file}: ${err.message} — aborting.`);
+    process.exit(1);
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      console.error(`${file} is not a JSON object — fix it manually, aborting.`);
+      process.exit(1);
+    }
+    return parsed;
+  } catch {
+    console.error(`${file} is invalid JSON — fix it manually, aborting.`);
+    process.exit(1);
+  }
+}
+
+function install() {
+  const cfg = loadSettings(SETTINGS);
+  cfg.hooks = cfg.hooks && typeof cfg.hooks === 'object' && !Array.isArray(cfg.hooks) ? cfg.hooks : {};
+  const cur = cfg.hooks.Stop;
+  if (cur !== undefined && !Array.isArray(cur)) {
+    console.error(`${SETTINGS}: hooks.Stop is not an array — fix it manually, aborting.`);
+    process.exit(1);
+  }
+  cfg.hooks.Stop = Array.isArray(cur) ? cur : [];
+
+  if (cfg.hooks.Stop.some(isAgencyEntry)) {
+    console.log(`Agency Stop hook already wired in ${SETTINGS} (nothing to do).`);
+    return;
+  }
+  cfg.hooks.Stop.push(agencyEntry());
+  fs.mkdirSync(path.dirname(SETTINGS), { recursive: true });
+  fs.writeFileSync(SETTINGS, JSON.stringify(cfg, null, 2) + '\n');
+  console.log(`Wired Agency Stop hook into ${SETTINGS} → ${HOOK_URL}`);
+  console.log('Run `npm start`, then run `claude` anywhere — when an agent stops,');
+  console.log('answer it from the dashboard (it fails open if Agency is closed).');
+}
+
+function uninstall() {
+  if (!fs.existsSync(SETTINGS)) {
+    console.log(`No settings at ${SETTINGS} — nothing to remove.`);
+    return;
+  }
+  const cfg = loadSettings(SETTINGS);
+  if (!cfg.hooks || typeof cfg.hooks !== 'object' || !Array.isArray(cfg.hooks.Stop)) {
+    console.log(`No Agency Stop hook in ${SETTINGS}.`);
+    return;
+  }
+  const before = cfg.hooks.Stop.length;
+  cfg.hooks.Stop = cfg.hooks.Stop.filter((e) => !isAgencyEntry(e));
+  const removed = before - cfg.hooks.Stop.length;
+  if (cfg.hooks.Stop.length === 0) delete cfg.hooks.Stop;
+  if (cfg.hooks && Object.keys(cfg.hooks).length === 0) delete cfg.hooks;
+  fs.writeFileSync(SETTINGS, JSON.stringify(cfg, null, 2) + '\n');
+  console.log(removed ? `Removed Agency Stop hook from ${SETTINGS}.` : `No Agency Stop hook in ${SETTINGS}.`);
+}
+
+const arg = process.argv[2];
+if (arg === '--print') {
+  console.log(JSON.stringify({ hooks: { Stop: [agencyEntry()] } }, null, 2));
+} else if (arg === '--uninstall' || arg === '-u') {
+  uninstall();
+} else {
+  install();
+}

package/server.js

@@ -0,0 +1,370 @@
+#!/usr/bin/env node
+// server.js — zero-dependency HTTP server for Agency.
+// Serves the static frontend and a single /api/state endpoint that fuses live
+// running sessions with historical usage stats and stable agent identities.
+
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { getUsage } from './lib/usage.js';
+import { getLive } from './lib/live.js';
+import { identityFor, overrideFor, setOverride } from './lib/roster.js';
+import { getTranscript } from './lib/transcript.js';
+import * as control from './lib/control.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PUBLIC = path.join(__dirname, 'public');
+const PORT = process.env.PORT ? Number(process.env.PORT) : 4313;
+const HOST = process.env.HOST || '127.0.0.1';
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.ico': 'image/x-icon',
+  '.mp3': 'audio/mpeg',
+};
+
+function buildState() {
+  const usage = getUsage();
+  const live = getLive();
+
+  // Which sessions are paused on a Stop hook, waiting for a reply (Control
+  // Phase-1). Folded onto matching live agents as awaitingReply / pendingSince
+  // so the frontend HUD + render.js "needs you" indicator can read it. The
+  // agent shape is otherwise unchanged.
+  const waiting = control.list();
+
+  // Attach a stable identity to each live agent. In-process teammates keep
+  // their team-config label + subagent_type as name/title (the roster still
+  // supplies a stable avatar palette + hire date), so "cc-internals" reads as
+  // itself rather than a roster-minted persona.
+  const agents = live.agents.map((a) => {
+    const ident = identityFor(a.sessionId, a.model, a.startedAt);
+    const w = a.sessionId ? waiting[a.sessionId] : null;
+    const ctrl = w ? { awaitingReply: true, pendingSince: w.since } : null;
+    // User overrides (rename / hide), persisted per sessionId. A custom name
+    // wins over the minted persona AND the teammate label; `hidden` is carried
+    // on EVERY agent (default false) so consumers never see undefined.
+    const ov = overrideFor(a.sessionId);
+    if (a.role === 'teammate') {
+      return {
+        ...a,
+        ...ident,
+        ...ctrl,
+        name: ov.name || a.teammateName || ident.name,
+        title: a.teammateType || ident.title,
+        hidden: ov.hidden,
+      };
+    }
+    return { ...a, ...ident, ...ctrl, name: ov.name || ident.name, hidden: ov.hidden };
+  });
+
+  return {
+    generatedAt: Date.now(),
+    live: { agents, teams: live.teams, now: live.now },
+    usage,
+  };
+}
+
+function sendJSON(res, code, obj) {
+  const body = JSON.stringify(obj);
+  res.writeHead(code, {
+    'Content-Type': 'application/json; charset=utf-8',
+    'Cache-Control': 'no-store',
+  });
+  res.end(body);
+}
+
+function serveStatic(req, res) {
+  let urlPath = decodeURIComponent(req.url.split('?')[0]);
+  if (urlPath === '/') urlPath = '/index.html';
+  const filePath = path.normalize(path.join(PUBLIC, urlPath));
+  if (filePath !== PUBLIC && !filePath.startsWith(PUBLIC + path.sep)) {
+    res.writeHead(403);
+    res.end('forbidden');
+    return;
+  }
+  fs.readFile(filePath, (err, data) => {
+    if (err) {
+      res.writeHead(404);
+      res.end('not found');
+      return;
+    }
+    const ext = path.extname(filePath);
+    res.writeHead(200, { 'Content-Type': MIME[ext] || 'application/octet-stream' });
+    res.end(data);
+  });
+}
+
+// Open a new Terminal window running `claude --resume <id>` in the agent's cwd.
+// macOS-only (osascript → Terminal.app). ponytail: Terminal.app is hardcoded;
+// swap the AppleScript target if you live in iTerm. sessionId is charset-checked
+// by the caller and cwd is single-quoted, then both layers are escaped for the
+// AppleScript string so a weird path can't break out of it.
+function openResumeTerminal(sessionId, cwd, kind, cb) {
+  // A running BACKGROUND agent can't be `--resume`d (the CLI refuses — it's
+  // already live); you attach to it via the agent manager. Interactive sessions
+  // resume directly. ponytail: `claude agents` is a picker (no per-id attach in
+  // this CLI); --cwd scopes it to this project so the agent is easy to find.
+  const bg = kind === 'background' || kind === 'bg';
+  const inner = bg ? `claude agents --cwd ${shellQuote(cwd)}` : `claude --resume ${sessionId}`;
+  const shellCmd = `cd ${shellQuote(cwd)} && ${inner}`;
+  const appleScript = `tell application "Terminal"\nactivate\ndo script "${appleEscape(shellCmd)}"\nend tell`;
+  execFile('osascript', ['-e', appleScript], (err) => cb(err));
+}
+const shellQuote = (s) => `'${String(s).replace(/'/g, `'\\''`)}'`;
+const appleEscape = (s) => String(s).replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+
+const server = http.createServer((req, res) => {
+  try {
+    const q = req.url.indexOf('?');
+    const pathname = q === -1 ? req.url : req.url.slice(0, q);
+    const query = q === -1 ? '' : req.url.slice(q + 1);
+    if (pathname === '/api/state') {
+      sendJSON(res, 200, buildState());
+      return;
+    }
+    // Read-only peek at the tail of a session's transcript (for the chat panel).
+    if (pathname === '/api/transcript') {
+      const params = new URLSearchParams(query);
+      const sessionId = params.get('sessionId');
+      const cwd = params.get('cwd');
+      if (!sessionId || !cwd) {
+        sendJSON(res, 400, { error: 'sessionId and cwd are required' });
+        return;
+      }
+      sendJSON(res, 200, getTranscript(sessionId, cwd));
+      return;
+    }
+    // ACTION endpoint (the one place Agency acts instead of viewing): open a
+    // terminal running `claude --resume <id>` in the agent's cwd. User-authorized;
+    // it spawns osascript→Terminal but never writes the ~/.claude data sources.
+    if (pathname === '/api/resume' && req.method === 'POST') {
+      let body = '';
+      req.on('data', (c) => {
+        body += c;
+        if (body.length > 4096) req.destroy(); // cap — these payloads are tiny
+      });
+      req.on('end', () => {
+        // This async handler fires after the top-level try/catch has returned, so
+        // guard it too — a throw here would otherwise crash the process (the app's
+        // fail-soft charter: a bad request must never take down the server).
+        try {
+          let sessionId, cwd, kind;
+          try {
+            ({ sessionId, cwd, kind } = JSON.parse(body || '{}'));
+          } catch {
+            return sendJSON(res, 400, { error: 'bad json' });
+          }
+          // Validate HARD before building any command: sessionId to a safe charset,
+          // cwd to an existing absolute path. (cwd is still shell-quoted below.)
+          if (!sessionId || !/^[A-Za-z0-9._-]+$/.test(sessionId)) {
+            return sendJSON(res, 400, { error: 'invalid sessionId' });
+          }
+          if (!cwd || typeof cwd !== 'string' || !path.isAbsolute(cwd) || !fs.existsSync(cwd)) {
+            return sendJSON(res, 400, { error: 'invalid cwd' });
+          }
+          openResumeTerminal(sessionId, cwd, kind, (err) =>
+            err ? sendJSON(res, 500, { error: String(err.message || err) }) : sendJSON(res, 200, { ok: true })
+          );
+        } catch (err) {
+          sendJSON(res, 500, { error: String(err && err.message ? err.message : err) });
+        }
+      });
+      return;
+    }
+    // CONTROL endpoint — the Stop-hook landing pad. A Claude Code Stop hook of
+    // type "http" POSTs here and BLOCKS the agent until we respond; it FAILS
+    // OPEN (timeout / refused / non-2xx → agent just stops). We register the
+    // paused session and HOLD this response open: it's resolved either by
+    // /api/reply (→ decision:"block" JSON, resuming the agent with the user's
+    // instruction) or by the soft deadline (→ empty 200, agent stops normally,
+    // under the 120s hook timeout). Authorized control surface, like
+    // /api/resume — never writes the ~/.claude data sources.
+    if (pathname === '/api/hook/stop' && req.method === 'POST') {
+      let body = '';
+      req.on('data', (c) => {
+        body += c;
+        if (body.length > 64 * 1024) req.destroy(); // cap — hook payloads are small
+      });
+      req.on('end', () => {
+        // Fires after the top-level try/catch returns, so guard it too — a
+        // throw here would crash the process (fail-soft charter: a bad hook
+        // payload must never take down the server / /api/state).
+        try {
+          let info = {};
+          try {
+            info = JSON.parse(body || '{}') || {};
+          } catch {
+            // Malformed payload: fail open — let the agent stop normally.
+            return sendJSON(res, 200, {});
+          }
+          const sessionId = info.session_id;
+          // No usable session id: nothing to register against, fail open.
+          if (!sessionId || typeof sessionId !== 'string' || !/^[A-Za-z0-9._-]+$/.test(sessionId)) {
+            return sendJSON(res, 200, {});
+          }
+          let settled = false;
+          // settle(text): text → resume with the user's instruction; null →
+          // empty 200 so the agent stops. Idempotent (timeout vs reply vs close
+          // race) and returns true only if it actually wrote to a live socket,
+          // so control.resolve can tell a delivered reply from a dropped one.
+          const settle = (text) => {
+            if (settled) return false;
+            settled = true;
+            try {
+              if (typeof text === 'string') {
+                sendJSON(res, 200, {
+                  decision: 'block',
+                  reason: text,
+                  hookSpecificOutput: { hookEventName: 'Stop', additionalContext: text },
+                });
+              } else {
+                sendJSON(res, 200, {});
+              }
+              return true;
+            } catch {
+              return false; // connection already gone
+            }
+          };
+          // If the client hangs up while we hold (agent killed, hook timed out
+          // on its side), mark this hold settled AND drop the registry entry
+          // (entry-scoped, so a superseding hold survives) — otherwise the agent
+          // would keep showing awaitingReply and a late /api/reply would falsely
+          // report success on a dead socket.
+          res.on('close', () => {
+            settled = true;
+            control.cancel(sessionId, settle);
+          });
+          control.register(sessionId, {
+            cwd: info.cwd,
+            transcriptPath: info.transcript_path,
+            settle,
+          });
+        } catch (err) {
+          // Last-ditch: fail open so the agent stops rather than hanging.
+          try {
+            sendJSON(res, 200, {});
+          } catch {
+            /* ignore */
+          }
+        }
+      });
+      return;
+    }
+    // CONTROL endpoint — deliver the user's typed reply to a paused agent.
+    // { sessionId, text }: resolves the matching held /api/hook/stop request
+    // (→ resumes the agent with `text`). 404 if no agent is pending for that id.
+    if (pathname === '/api/reply' && req.method === 'POST') {
+      let body = '';
+      req.on('data', (c) => {
+        body += c;
+        if (body.length > 16 * 1024) req.destroy(); // cap — text is capped to ~8KB below
+      });
+      req.on('end', () => {
+        try {
+          let sessionId, text;
+          try {
+            ({ sessionId, text } = JSON.parse(body || '{}'));
+          } catch {
+            return sendJSON(res, 400, { error: 'bad json' });
+          }
+          if (!sessionId || typeof sessionId !== 'string' || !/^[A-Za-z0-9._-]+$/.test(sessionId)) {
+            return sendJSON(res, 400, { error: 'invalid sessionId' });
+          }
+          if (typeof text !== 'string' || !text.trim()) {
+            return sendJSON(res, 400, { error: 'text is required' });
+          }
+          const reply = text.slice(0, 8 * 1024); // cap the instruction length
+          const delivered = control.resolve(sessionId, reply);
+          if (delivered) sendJSON(res, 200, { ok: true });
+          else sendJSON(res, 404, { error: 'no agent waiting for this session' });
+        } catch (err) {
+          sendJSON(res, 500, { error: String(err && err.message ? err.message : err) });
+        }
+      });
+      return;
+    }
+    // OVERRIDE endpoint — persist a per-session rename / hide. Authorized like
+    // the other POSTs; it writes only data/roster.json (a regenerable cache),
+    // never the ~/.claude data sources. Body { sessionId, name?, hidden? }:
+    // name '' or null clears the rename; hidden is a boolean toggle. Only the
+    // keys present in the body are applied, so a hide-toggle won't wipe a rename.
+    if (pathname === '/api/agent-override' && req.method === 'POST') {
+      let body = '';
+      req.on('data', (c) => {
+        body += c;
+        if (body.length > 4096) req.destroy(); // cap — these payloads are tiny
+      });
+      req.on('end', () => {
+        // Fires after the top-level try/catch returns, so guard it too — a throw
+        // here would crash the process (fail-soft charter: a bad request must
+        // never take down the server / /api/state).
+        try {
+          let info;
+          try {
+            info = JSON.parse(body || '{}');
+          } catch {
+            return sendJSON(res, 400, { error: 'bad json' });
+          }
+          const { sessionId, name, hidden } = info || {};
+          if (!sessionId || typeof sessionId !== 'string' || !/^[A-Za-z0-9._-]+$/.test(sessionId)) {
+            return sendJSON(res, 400, { error: 'invalid sessionId' }); // match /api/reply's charset guard
+          }
+          // Pass through only the keys actually present so a hide-toggle doesn't
+          // wipe the name and vice-versa. roster.setOverride trims + length-caps
+          // + strips control chars from the name; it is never eval'd or exec'd.
+          const patch = {};
+          if (Object.prototype.hasOwnProperty.call(info, 'name')) patch.name = name;
+          if (Object.prototype.hasOwnProperty.call(info, 'hidden')) {
+            if (typeof hidden !== 'boolean') {
+              return sendJSON(res, 400, { error: 'hidden must be a boolean' });
+            }
+            patch.hidden = hidden;
+          }
+          const override = setOverride(sessionId, patch);
+          sendJSON(res, 200, { ok: true, override });
+        } catch (err) {
+          sendJSON(res, 500, { ok: false, error: String(err && err.message ? err.message : err) });
+        }
+      });
+      return;
+    }
+    serveStatic(req, res);
+  } catch (err) {
+    sendJSON(res, 500, { error: String(err && err.message ? err.message : err) });
+  }
+});
+
+// Open the dashboard in the default browser on launch (the `npx` UX). Best
+// effort + fail-silent; skip with AGENCY_NO_OPEN=1 (dev / headless / remote).
+function openBrowser(url) {
+  if (process.env.AGENCY_NO_OPEN) return;
+  const [cmd, args] =
+    process.platform === 'darwin' ? ['open', [url]]
+    : process.platform === 'win32' ? ['cmd', ['/c', 'start', '', url]]
+    : ['xdg-open', [url]];
+  try {
+    execFile(cmd, args, () => {});
+  } catch {
+    /* no browser opener available — the printed URL still works */
+  }
+}
+
+server.listen(PORT, HOST, () => {
+  // Warm the usage cache so the first request is fast.
+  try {
+    getUsage();
+  } catch {
+    /* ignore */
+  }
+  console.log(`\n  🏢  Agency is open for business.`);
+  console.log(`      → http://${HOST}:${PORT}\n`);
+  openBrowser(`http://${HOST}:${PORT}`);
+});