chamba 0.0.1 → 0.2.0

package/dist/server.js

@@ -0,0 +1,1919 @@
+// packages/server/src/index.ts
+import { serve as honoServe } from "@hono/node-server";
+
+// packages/shared/src/annotations.ts
+import { z as z3 } from "zod";
+
+// packages/shared/src/messages.ts
+import { z as z2 } from "zod";
+
+// packages/shared/src/session.ts
+import { z } from "zod";
+var sessionKindSchema = z.enum(["everyday", "spec"]);
+var sessionStatusSchema = z.enum(["active", "ended"]);
+var sessionMetaSchema = z.object({
+  id: z.string().min(1),
+  kind: sessionKindSchema.optional(),
+  title: z.string().optional(),
+  status: sessionStatusSchema,
+  createdAt: z.string().datetime(),
+  updatedAt: z.string().datetime()
+});
+
+// packages/shared/src/messages.ts
+var attachmentSchema = z2.object({
+  id: z2.string().min(1),
+  name: z2.string().min(1),
+  relPath: z2.string().min(1),
+  contentType: z2.string().min(1),
+  size: z2.number().int().nonnegative()
+});
+var messagePayloadSchema = z2.object({
+  text: z2.string().min(1).optional(),
+  attachments: z2.array(attachmentSchema).optional()
+}).refine((p) => (p.text?.length ?? 0) > 0 || (p.attachments?.length ?? 0) > 0, {
+  message: "a message needs text or at least one attachment"
+});
+var systemReasonSchema = z2.enum([
+  "session-created",
+  "user-moved-away",
+  "session-ended",
+  "kind-chosen"
+]);
+var systemPayloadSchema = z2.object({
+  reason: systemReasonSchema,
+  to: z2.string().min(1).optional(),
+  kind: sessionKindSchema.optional()
+});
+
+// packages/shared/src/annotations.ts
+var ANNOTATION_BATCH = "annotation-batch";
+var annotationSourceSchema = z3.object({
+  file: z3.string().min(1),
+  line: z3.number().int().positive().optional(),
+  column: z3.number().int().positive().optional()
+});
+var annotationComponentSchema = z3.object({
+  name: z3.string().min(1),
+  source: annotationSourceSchema.optional()
+});
+var annotationTargetSchema = z3.object({
+  selector: z3.string().min(1),
+  pageUrl: z3.string().min(1),
+  viewport: z3.object({
+    width: z3.number().int().positive(),
+    height: z3.number().int().positive()
+  }),
+  label: z3.string().optional(),
+  component: annotationComponentSchema.optional()
+});
+var annotationItemSchema = z3.object({
+  note: z3.string().min(1).optional(),
+  target: annotationTargetSchema,
+  screenshot: attachmentSchema.optional()
+});
+var annotationBatchPayloadSchema = z3.object({
+  items: z3.array(annotationItemSchema).min(1)
+});
+
+// packages/shared/src/api.ts
+import { z as z7 } from "zod";
+
+// packages/shared/src/events.ts
+import { z as z4 } from "zod";
+var eventSourceSchema = z4.enum(["user", "agent", "system"]);
+var eventEnvelopeSchema = z4.object({
+  id: z4.string().uuid(),
+  seq: z4.number().int().nonnegative(),
+  sessionId: z4.string().min(1),
+  ts: z4.string().datetime(),
+  type: z4.string().min(1),
+  source: eventSourceSchema,
+  payload: z4.unknown()
+});
+
+// packages/shared/src/presence.ts
+import { z as z5 } from "zod";
+var presenceSchema = z5.enum(["listening", "working", "away"]);
+
+// packages/shared/src/spec.ts
+import { z as z6 } from "zod";
+var QUESTION_CARD = "question-card";
+var DECISION = "decision";
+var ARTIFACT = "artifact";
+var questionOptionSchema = z6.object({
+  label: z6.string().min(1),
+  description: z6.string().min(1),
+  recommended: z6.boolean().optional()
+});
+var questionCardPayloadSchema = z6.object({
+  cardId: z6.string().uuid(),
+  question: z6.string().min(1),
+  options: z6.array(questionOptionSchema).min(2).max(6),
+  /** Optional custom wording for the stop-anytime affordance. */
+  stopHint: z6.string().min(1).optional()
+});
+var decisionStatusSchema = z6.enum(["confirmed", "assumed"]);
+var decisionPayloadSchema = z6.object({
+  summary: z6.string().min(1),
+  status: decisionStatusSchema,
+  detail: z6.string().min(1).optional()
+});
+var artifactKindSchema = z6.enum(["draft", "mock", "diagram"]);
+var artifactRefSchema = z6.object({
+  kind: artifactKindSchema,
+  name: z6.string().min(1),
+  relPath: z6.string().min(1),
+  contentType: z6.string().min(1),
+  size: z6.number().int().nonnegative()
+});
+var artifactPayloadSchema = z6.object({
+  artifact: artifactRefSchema
+});
+
+// packages/shared/src/api.ts
+var cursorSchema = z7.number().int().nonnegative();
+var createSessionReqSchema = z7.object({
+  kind: sessionKindSchema.optional(),
+  title: z7.string().min(1).optional()
+});
+var setSessionKindReqSchema = z7.object({
+  kind: sessionKindSchema
+});
+var messageBodySchema = z7.object({
+  text: z7.string().min(1).optional(),
+  attachmentIds: z7.array(z7.string().min(1)).optional()
+}).refine((r) => (r.text?.length ?? 0) > 0 || (r.attachmentIds?.length ?? 0) > 0, {
+  message: "a message needs text or at least one attachment"
+});
+var postMessageReqSchema = messageBodySchema;
+var replyReqSchema = messageBodySchema;
+var annotationItemReqSchema = z7.object({
+  note: z7.string().min(1).optional(),
+  target: annotationTargetSchema,
+  screenshotAttachmentId: z7.string().min(1).optional()
+});
+var postAnnotationsReqSchema = z7.object({
+  items: z7.array(annotationItemReqSchema).min(1)
+});
+var moveAwayReqSchema = z7.object({
+  to: z7.string().min(1).optional()
+});
+var postQuestionCardReqSchema = questionCardPayloadSchema;
+var postDecisionReqSchema = decisionPayloadSchema;
+var postArtifactReqSchema = z7.object({
+  kind: artifactKindSchema,
+  name: z7.string().min(1),
+  content: z7.string().min(1)
+});
+var attachmentResSchema = z7.object({
+  attachment: attachmentSchema
+});
+var eventResSchema = z7.object({
+  event: eventEnvelopeSchema
+});
+var pollResSchema = z7.object({
+  events: z7.array(eventEnvelopeSchema),
+  cursor: cursorSchema,
+  ended: z7.boolean().optional()
+});
+var fetchMoreSchema = z7.object({
+  hasMore: z7.boolean(),
+  earliestLoadedSeq: cursorSchema,
+  hint: z7.string()
+});
+var attachDigestSchema = z7.object({
+  meta: sessionMetaSchema,
+  presence: presenceSchema,
+  tail: z7.array(eventEnvelopeSchema),
+  cursor: cursorSchema,
+  fetchMore: fetchMoreSchema
+});
+var sessionSummarySchema = z7.object({
+  meta: sessionMetaSchema,
+  presence: presenceSchema
+});
+var listResSchema = z7.object({
+  sessions: z7.array(sessionSummarySchema)
+});
+var sessionResSchema = z7.object({
+  session: sessionSummarySchema
+});
+var healthResSchema = z7.object({
+  ok: z7.boolean(),
+  sessions: cursorSchema,
+  home: z7.string().min(1).optional(),
+  port: z7.number().int().positive().optional(),
+  version: z7.string().min(1).optional()
+});
+
+// packages/shared/src/issues.ts
+import { z as z8 } from "zod";
+var issueTypeSchema = z8.enum(["bug", "feature"]);
+var postIssueReqSchema = z8.object({
+  type: issueTypeSchema,
+  text: z8.string().min(1),
+  screenshotAttachmentIds: z8.array(z8.string().min(1)).optional()
+});
+var issueResSchema = z8.object({
+  id: z8.string().min(1),
+  path: z8.string().min(1)
+});
+
+// packages/shared/src/ws.ts
+import { z as z9 } from "zod";
+var wsServerMessageSchema = z9.discriminatedUnion("t", [
+  z9.object({
+    t: z9.literal("hello"),
+    meta: sessionMetaSchema,
+    presence: presenceSchema
+  }),
+  z9.object({
+    t: z9.literal("append"),
+    event: eventEnvelopeSchema
+  }),
+  z9.object({
+    t: z9.literal("presence"),
+    state: presenceSchema
+  }),
+  z9.object({
+    t: z9.literal("kind"),
+    meta: sessionMetaSchema
+  }),
+  z9.object({
+    t: z9.literal("ended"),
+    meta: sessionMetaSchema
+  })
+]);
+
+// packages/server/src/app.ts
+import { createNodeWebSocket } from "@hono/node-ws";
+import { Hono } from "hono";
+
+// packages/server/src/inject.ts
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+function resolveInjectDist() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const dev = path.resolve(here, "../../inject/dist");
+  const packaged = path.resolve(here, "../inject");
+  return [dev, packaged].find((dir) => existsSync(path.join(dir, "annotate.js"))) ?? dev;
+}
+function createInjectHandler(injectDist) {
+  const file = path.join(injectDist, "annotate.js");
+  return async (c) => {
+    let bytes;
+    try {
+      const raw = await readFile(file);
+      bytes = new Uint8Array(raw.byteLength);
+      bytes.set(raw);
+    } catch {
+      return c.text("annotation client not built - run `pnpm --filter @chamba/inject build`", 404);
+    }
+    return c.body(bytes, 200, {
+      "content-type": "text/javascript; charset=utf-8",
+      "cache-control": "no-cache",
+      "access-control-allow-origin": "*"
+    });
+  };
+}
+
+// packages/server/src/render.ts
+import { marked } from "marked";
+var INJECT_TAG = '<script src="/inject/annotate.js"></script>';
+async function renderArtifactHtml(file, content) {
+  const lower = file.toLowerCase();
+  if (lower.endsWith(".html") || lower.endsWith(".htm")) {
+    return injectInto(content);
+  }
+  if (lower.endsWith(".md") || lower.endsWith(".markdown")) {
+    const body = await marked.parse(content, { async: false });
+    return draftDocument(body);
+  }
+  return draftDocument(`<pre>${escapeHtml(content)}</pre>`);
+}
+function injectInto(html) {
+  const idx = html.toLowerCase().lastIndexOf("</body>");
+  if (idx === -1) return `${html}
+${INJECT_TAG}`;
+  return `${html.slice(0, idx)}${INJECT_TAG}
+${html.slice(idx)}`;
+}
+function draftDocument(body) {
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<style>
+  :root { color-scheme: light dark; }
+  body {
+    margin: 0 auto; max-width: 46rem; padding: 2.5rem 1.5rem;
+    font: 16px/1.65 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+    color: #1a1a1a; background: #fff;
+  }
+  @media (prefers-color-scheme: dark) { body { color: #e6e6e6; background: #0d0d0d; } }
+  h1, h2, h3 { line-height: 1.25; margin-top: 1.8em; }
+  h1 { font-size: 1.8rem; } h2 { font-size: 1.4rem; } h3 { font-size: 1.15rem; }
+  code { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 0.9em; }
+  pre { background: rgba(127,127,127,0.12); padding: 1rem; border-radius: 8px; overflow-x: auto; }
+  pre code { background: none; padding: 0; }
+  :not(pre) > code { background: rgba(127,127,127,0.14); padding: 0.15em 0.35em; border-radius: 4px; }
+  blockquote { margin: 1em 0; padding-left: 1em; border-left: 3px solid rgba(127,127,127,0.35); color: inherit; opacity: 0.85; }
+  table { border-collapse: collapse; } th, td { border: 1px solid rgba(127,127,127,0.3); padding: 0.4em 0.7em; }
+  a { color: #2563eb; } @media (prefers-color-scheme: dark) { a { color: #60a5fa; } }
+</style>
+</head>
+<body>
+${body}
+${INJECT_TAG}
+</body>
+</html>`;
+}
+function escapeHtml(text) {
+  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+// packages/server/src/static.ts
+import { existsSync as existsSync2 } from "node:fs";
+import { readFile as readFile2 } from "node:fs/promises";
+import path3 from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+
+// packages/server/src/mime.ts
+import path2 from "node:path";
+var CONTENT_TYPES = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".ico": "image/x-icon",
+  ".woff2": "font/woff2",
+  ".map": "application/json; charset=utf-8",
+  ".pdf": "application/pdf",
+  ".txt": "text/plain; charset=utf-8",
+  ".md": "text/markdown; charset=utf-8"
+};
+function contentTypeFor(filePath) {
+  return CONTENT_TYPES[path2.extname(filePath).toLowerCase()] ?? "application/octet-stream";
+}
+
+// packages/server/src/static.ts
+function resolveWebDist() {
+  const here = path3.dirname(fileURLToPath2(import.meta.url));
+  const dev = path3.resolve(here, "../../web/dist");
+  const packaged = path3.resolve(here, "../web");
+  return [dev, packaged].find((dir) => existsSync2(path3.join(dir, "index.html"))) ?? dev;
+}
+function createStaticHandler(webDist) {
+  return async (c) => {
+    let pathname;
+    try {
+      pathname = decodeURIComponent(new URL(c.req.url).pathname);
+    } catch {
+      return c.json({ error: "not found" }, 404);
+    }
+    if (pathname.startsWith("/api") || pathname.startsWith("/ws")) {
+      return c.json({ error: "not found" }, 404);
+    }
+    const relative = pathname === "/" ? "index.html" : pathname.replace(/^\/+/, "");
+    const filePath = path3.resolve(webDist, relative);
+    if (filePath !== webDist && !filePath.startsWith(webDist + path3.sep)) {
+      return c.json({ error: "not found" }, 404);
+    }
+    const direct = await readFileOrNull(filePath);
+    if (direct) {
+      return c.body(direct, 200, { "content-type": contentTypeFor(filePath) });
+    }
+    const indexHtml = await readFileOrNull(path3.join(webDist, "index.html"));
+    if (indexHtml) {
+      return c.body(indexHtml, 200, { "content-type": "text/html; charset=utf-8" });
+    }
+    return c.text("web build not found - run `pnpm --filter @chamba/web build`", 404);
+  };
+}
+async function readFileOrNull(filePath) {
+  try {
+    const raw = await readFile2(filePath);
+    const bytes = new Uint8Array(raw.byteLength);
+    bytes.set(raw);
+    return bytes;
+  } catch {
+    return null;
+  }
+}
+
+// packages/server/src/app.ts
+var INLINE_SAFE_TYPES = /* @__PURE__ */ new Set([
+  "image/png",
+  "image/jpeg",
+  "image/gif",
+  "image/webp",
+  "image/x-icon"
+]);
+var MAX_UPLOAD_BYTES = 25 * 1024 * 1024;
+function createApp(ctx) {
+  const app = new Hono();
+  const { injectWebSocket, upgradeWebSocket } = createNodeWebSocket({ app });
+  ctx.presence.onChange((id, state) => ctx.hub.broadcast(id, { t: "presence", state }));
+  const summaryOf = (meta) => ({
+    meta,
+    presence: ctx.presence.get(meta.id)
+  });
+  app.get("/api/health", async (c) => {
+    const all = await ctx.sessions.list();
+    const active = all.filter((meta) => meta.status === "active").length;
+    return c.json({
+      ok: true,
+      sessions: active,
+      home: ctx.home,
+      port: ctx.port,
+      version: ctx.version
+    });
+  });
+  app.post("/api/sessions", async (c) => {
+    const parsed = createSessionReqSchema.safeParse(await readJson(c));
+    if (!parsed.success) return badRequest(c, parsed.error.issues);
+    const meta = await ctx.sessions.create(parsed.data);
+    return c.json({ session: summaryOf(meta) }, 201);
+  });
+  app.get("/api/sessions", async (c) => {
+    const all = await ctx.sessions.list();
+    return c.json({ sessions: all.map(summaryOf) });
+  });
+  app.get("/api/sessions/:id", async (c) => {
+    const meta = await ctx.sessions.getMeta(c.req.param("id"));
+    if (!meta) return notFound(c);
+    return c.json({ session: summaryOf(meta) });
+  });
+  app.post("/api/sessions/:id/messages", async (c) => {
+    const id = c.req.param("id");
+    const meta = await ctx.sessions.getMeta(id);
+    if (!meta) return notFound(c);
+    if (meta.status === "ended") return c.json({ error: "session ended" }, 409);
+    const parsed = postMessageReqSchema.safeParse(await readJson(c));
+    if (!parsed.success) return badRequest(c, parsed.error.issues);
+    const attachments = await resolveAttachments(ctx, id, parsed.data.attachmentIds);
+    if (attachments === null) return c.json({ error: "unknown attachment" }, 400);
+    const event = await ctx.sessions.postMessage(id, { text: parsed.data.text, attachments });
+    return c.json({ event }, 201);
+  });
+  app.post("/api/sessions/:id/reply", async (c) => {
+    const id = c.req.param("id");
+    const meta = await ctx.sessions.getMeta(id);
+    if (!meta) return notFound(c);
+    if (meta.status === "ended") return c.json({ error: "session ended" }, 409);
+    const parsed = replyReqSchema.safeParse(await readJson(c));
+    if (!parsed.success) return badRequest(c, parsed.error.issues);
+    const attachments = await resolveAttachments(ctx, id, parsed.data.attachmentIds);
+    if (attachments === null) return c.json({ error: "unknown attachment" }, 400);
+    const event = await ctx.sessions.reply(id, { text: parsed.data.text, attachments });
+    ctx.presence.beat(id);
+    return c.json({ event }, 201);
+  });
+  app.post("/api/sessions/:id/attachments", async (c) => {
+    const id = c.req.param("id");
+    const meta = await ctx.sessions.getMeta(id);
+    if (!meta) return notFound(c);
+    if (meta.status === "ended") return c.json({ error: "session ended" }, 409);
+    const declaredLength = Number(c.req.header("content-length"));
+    if (Number.isFinite(declaredLength) && declaredLength > MAX_UPLOAD_BYTES) {
+      return c.json({ error: "file too large" }, 413);
+    }
+    const body = await c.req.parseBody();
+    const file = body.file;
+    if (!(file instanceof File)) return c.json({ error: "expected a `file` field" }, 400);
+    if (file.size > MAX_UPLOAD_BYTES) return c.json({ error: "file too large" }, 413);
+    const bytes = new Uint8Array(await file.arrayBuffer());
+    if (bytes.byteLength === 0) return c.json({ error: "empty file" }, 400);
+    const attachment = await ctx.sessions.saveAttachment(id, file.name || "file", bytes);
+    return c.json({ attachment }, 201);
+  });
+  app.get("/api/sessions/:id/attachments/:attId", async (c) => {
+    const file = await ctx.sessions.readAttachment(c.req.param("id"), c.req.param("attId"));
+    if (!file) return notFound(c);
+    const headers = {
+      "content-type": file.contentType,
+      "x-content-type-options": "nosniff"
+    };
+    const baseType = file.contentType.split(";")[0]?.trim().toLowerCase() ?? "";
+    if (!INLINE_SAFE_TYPES.has(baseType)) headers["content-disposition"] = "attachment";
+    return c.body(file.bytes, 200, headers);
+  });
+  app.post("/api/sessions/:id/annotations", async (c) => {
+    const id = c.req.param("id");
+    const meta = await ctx.sessions.getMeta(id);
+    if (!meta) return notFound(c);
+    if (meta.status === "ended") return c.json({ error: "session ended" }, 409);
+    const parsed = postAnnotationsReqSchema.safeParse(await readJson(c));
+    if (!parsed.success) return badRequest(c, parsed.error.issues);
+    const items = await resolveAnnotationItems(ctx, id, parsed.data.items);
+    if (items === null) return c.json({ error: "unknown attachment" }, 400);
+    const event = await ctx.sessions.postAnnotations(id, items);
+    return c.json({ event }, 201);
+  });
+  app.post("/api/sessions/:id/cards", async (c) => {
+    const guard = await requireSpecActive(ctx, c);
+    if (guard.res) return guard.res;
+    const parsed = postQuestionCardReqSchema.safeParse(await readJson(c));
+    if (!parsed.success) return badRequest(c, parsed.error.issues);
+    const event = await ctx.sessions.postQuestionCard(guard.id, parsed.data);
+    ctx.presence.beat(guard.id);
+    return c.json({ event }, 201);
+  });
+  app.post("/api/sessions/:id/decisions", async (c) => {
+    const guard = await requireSpecActive(ctx, c);
+    if (guard.res) return guard.res;
+    const parsed = postDecisionReqSchema.safeParse(await readJson(c));
+    if (!parsed.success) return badRequest(c, parsed.error.issues);
+    const event = await ctx.sessions.postDecision(guard.id, parsed.data);
+    ctx.presence.beat(guard.id);
+    return c.json({ event }, 201);
+  });
+  app.post("/api/sessions/:id/artifacts", async (c) => {
+    const guard = await requireSpecActive(ctx, c);
+    if (guard.res) return guard.res;
+    const parsed = postArtifactReqSchema.safeParse(await readJson(c));
+    if (!parsed.success) return badRequest(c, parsed.error.issues);
+    const ref = await ctx.sessions.saveArtifact(
+      guard.id,
+      parsed.data.kind,
+      parsed.data.name,
+      parsed.data.content
+    );
+    const event = await ctx.sessions.postArtifact(guard.id, ref);
+    ctx.presence.beat(guard.id);
+    return c.json({ event }, 201);
+  });
+  app.post("/api/sessions/:id/issues", async (c) => {
+    const id = c.req.param("id");
+    const meta = await ctx.sessions.getMeta(id);
+    if (!meta) return notFound(c);
+    const parsed = postIssueReqSchema.safeParse(await readJson(c));
+    if (!parsed.success) return badRequest(c, parsed.error.issues);
+    const saved = await ctx.sessions.saveIssue(meta, parsed.data);
+    if (!saved) return c.json({ error: "unknown attachment" }, 400);
+    return c.json(saved, 201);
+  });
+  app.post("/api/sessions/:id/move-away", async (c) => {
+    const id = c.req.param("id");
+    const meta = await ctx.sessions.getMeta(id);
+    if (!meta) return notFound(c);
+    if (meta.status === "ended") return c.json({ error: "session ended" }, 409);
+    const parsed = moveAwayReqSchema.safeParse(await readJson(c));
+    if (!parsed.success) return badRequest(c, parsed.error.issues);
+    const event = await ctx.sessions.moveAway(id, parsed.data.to);
+    return c.json({ event }, 201);
+  });
+  app.get("/api/sessions/:id/poll", async (c) => {
+    const id = c.req.param("id");
+    const meta = await ctx.sessions.getMeta(id);
+    if (!meta) return notFound(c);
+    const since = parseNonNeg(c.req.query("since"), 0);
+    const wait = meta.status === "ended" ? 0 : clamp(parseNonNeg(c.req.query("wait"), 25e3), 0, 3e4);
+    ctx.presence.enter(id);
+    let delivered = false;
+    try {
+      const res = await ctx.sessions.poll(id, since, wait, c.req.raw.signal);
+      delivered = res.events.length > 0;
+      return c.json({ ...res, ended: meta.status === "ended" });
+    } finally {
+      ctx.presence.leave(id, c.req.raw.signal.aborted, delivered);
+    }
+  });
+  app.get("/api/sessions/:id/events", async (c) => {
+    const id = c.req.param("id");
+    const meta = await ctx.sessions.getMeta(id);
+    if (!meta) return notFound(c);
+    const since = parseNonNeg(c.req.query("since"), 0);
+    const limitRaw = c.req.query("limit");
+    const limit = limitRaw === void 0 ? void 0 : parseNonNeg(limitRaw, 0);
+    return c.json(await ctx.sessions.events(id, since, limit));
+  });
+  app.get("/api/sessions/:id/attach", async (c) => {
+    const id = c.req.param("id");
+    const tail = clamp(parseNonNeg(c.req.query("tail"), 20), 0, 500);
+    const digest = await ctx.sessions.attach(id, tail, ctx.presence.get(id));
+    if (!digest) return notFound(c);
+    return c.json(digest);
+  });
+  app.post("/api/sessions/:id/kind", async (c) => {
+    const id = c.req.param("id");
+    const parsed = setSessionKindReqSchema.safeParse(await readJson(c));
+    if (!parsed.success) return badRequest(c, parsed.error.issues);
+    const result = await ctx.sessions.setKind(id, parsed.data.kind);
+    if (!result.ok) {
+      if (result.reason === "unknown") return notFound(c);
+      const message = result.reason === "ended" ? "session ended" : "kind already set";
+      return c.json({ error: message }, 409);
+    }
+    ctx.hub.broadcast(id, { t: "kind", meta: result.meta });
+    return c.json({ session: summaryOf(result.meta) });
+  });
+  app.post("/api/sessions/:id/end", async (c) => {
+    const id = c.req.param("id");
+    const meta = await ctx.sessions.end(id);
+    if (!meta) return notFound(c);
+    ctx.hub.broadcast(id, { t: "ended", meta });
+    return c.json({ session: summaryOf(meta) });
+  });
+  app.get(
+    "/ws",
+    upgradeWebSocket((c) => {
+      const id = new URL(c.req.url).searchParams.get("s") ?? "";
+      return {
+        onOpen: (_evt, ws) => {
+          openSocket(ctx, id, ws).catch(() => ws.close(1011, "internal error"));
+        },
+        onClose: (_evt, ws) => {
+          ctx.hub.remove(id, ws);
+        }
+      };
+    })
+  );
+  app.get("/api/sessions/:id/artifacts/:name", async (c) => {
+    const id = c.req.param("id");
+    const meta = await ctx.sessions.getMeta(id);
+    if (!meta) return notFound(c);
+    const name = c.req.param("name");
+    const artifact = await ctx.sessions.readArtifact(id, name);
+    if (!artifact) return notFound(c);
+    const raw = c.req.query("raw");
+    if (raw === "1" || raw === "true") {
+      const type = name.toLowerCase().endsWith(".html") ? "text/html; charset=utf-8" : "text/plain; charset=utf-8";
+      return c.body(artifact.content, 200, { "content-type": type, "cache-control": "no-cache" });
+    }
+    const html = await renderArtifactHtml(artifact.file, artifact.content);
+    return c.body(html, 200, {
+      "content-type": "text/html; charset=utf-8",
+      "cache-control": "no-cache"
+    });
+  });
+  app.get("/inject/annotate.js", createInjectHandler(ctx.injectDist));
+  app.get("*", createStaticHandler(ctx.webDist));
+  return { app, injectWebSocket };
+}
+async function openSocket(ctx, id, ws) {
+  const meta = await ctx.sessions.getMeta(id);
+  if (!meta) {
+    ws.close(1008, "unknown session");
+    return;
+  }
+  const first = ctx.hub.add(id, ws);
+  if (first) {
+    const log = await ctx.sessions.logFor(id);
+    const unsubscribe = log.subscribe((event) => ctx.hub.broadcast(id, { t: "append", event }));
+    ctx.hub.setForwarder(id, unsubscribe);
+  }
+  const hello = { t: "hello", meta, presence: ctx.presence.get(id) };
+  ws.send(JSON.stringify(hello));
+}
+async function resolveAttachments(ctx, id, ids) {
+  if (!ids || ids.length === 0) return [];
+  const refs = [];
+  for (const attId of ids) {
+    const ref = await ctx.sessions.resolveAttachment(id, attId);
+    if (!ref) return null;
+    refs.push(ref);
+  }
+  return refs;
+}
+async function resolveAnnotationItems(ctx, id, items) {
+  const resolved = [];
+  for (const item of items) {
+    let screenshot;
+    if (item.screenshotAttachmentId) {
+      const ref = await ctx.sessions.resolveAttachment(id, item.screenshotAttachmentId);
+      if (!ref) return null;
+      screenshot = ref;
+    }
+    resolved.push({
+      ...item.note ? { note: item.note } : {},
+      target: item.target,
+      ...screenshot ? { screenshot } : {}
+    });
+  }
+  return resolved;
+}
+async function requireSpecActive(ctx, c) {
+  const id = c.req.param("id") ?? "";
+  const meta = await ctx.sessions.getMeta(id);
+  if (!meta) return { id, res: notFound(c) };
+  if (meta.status === "ended") return { id, res: c.json({ error: "session ended" }, 409) };
+  if (meta.kind !== "spec") return { id, res: c.json({ error: "not a spec session" }, 400) };
+  return { id, res: null };
+}
+async function readJson(c) {
+  try {
+    return await c.req.json();
+  } catch {
+    return {};
+  }
+}
+function notFound(c) {
+  return c.json({ error: "unknown session" }, 404);
+}
+function badRequest(c, issues) {
+  return c.json({ error: "invalid request", issues }, 400);
+}
+function parseNonNeg(value, fallback) {
+  if (value === void 0) return fallback;
+  const n = Number(value);
+  return Number.isFinite(n) && n >= 0 ? Math.floor(n) : fallback;
+}
+function clamp(n, min, max) {
+  return Math.min(max, Math.max(min, n));
+}
+
+// packages/server/src/lifecycle.ts
+import { unlinkSync } from "node:fs";
+import { open, readFile as readFile4, rm } from "node:fs/promises";
+
+// packages/server/src/sessions/paths.ts
+import { existsSync as existsSync3, realpathSync } from "node:fs";
+import { appendFile, mkdir, readFile as readFile3 } from "node:fs/promises";
+import path4 from "node:path";
+function defaultContext() {
+  return { cwd: process.cwd(), env: process.env };
+}
+function resolveHome(ctx = defaultContext()) {
+  return findExistingHome(ctx) ?? plannedHome(ctx);
+}
+function findExistingHome(ctx = defaultContext()) {
+  const dir = ctx.env.CHAMBA_DIR;
+  if (dir && dir.length > 0) return canonicalize(dir);
+  const inside = enclosingChamba(ctx.cwd);
+  if (inside) return canonicalize(inside);
+  const root = gitRoot(ctx.cwd);
+  let cursor = path4.resolve(ctx.cwd);
+  while (true) {
+    if (existsSync3(path4.join(cursor, ".chamba"))) return canonicalize(path4.join(cursor, ".chamba"));
+    if (!root) break;
+    if (cursor === root) break;
+    const parent = path4.dirname(cursor);
+    if (parent === cursor) break;
+    cursor = parent;
+  }
+  return null;
+}
+function plannedHome(ctx = defaultContext()) {
+  const root = gitRoot(ctx.cwd) ?? path4.resolve(ctx.cwd);
+  return canonicalize(path4.join(root, ".chamba"));
+}
+function gitRoot(cwd) {
+  let cursor = path4.resolve(cwd);
+  while (true) {
+    if (existsSync3(path4.join(cursor, ".git"))) return cursor;
+    const parent = path4.dirname(cursor);
+    if (parent === cursor) return null;
+    cursor = parent;
+  }
+}
+function enclosingChamba(cwd) {
+  const parts = path4.resolve(cwd).split(path4.sep);
+  const index = parts.lastIndexOf(".chamba");
+  if (index < 0) return null;
+  return parts.slice(0, index + 1).join(path4.sep) || path4.sep;
+}
+function canonicalize(p) {
+  const resolved = path4.resolve(p);
+  let existing = resolved;
+  const tail = [];
+  while (!existsSync3(existing)) {
+    tail.unshift(path4.basename(existing));
+    const parent = path4.dirname(existing);
+    if (parent === existing) return resolved;
+    existing = parent;
+  }
+  return path4.join(realpathSync(existing), ...tail);
+}
+function sessionsDir(home) {
+  return path4.join(home, "sessions");
+}
+function sessionDir(home, id) {
+  return path4.join(sessionsDir(home), id);
+}
+function logPath(home, id) {
+  return path4.join(sessionDir(home, id), "log.ndjson");
+}
+function attachmentsDir(home, id) {
+  return path4.join(sessionDir(home, id), "attachments");
+}
+function artifactsDir(home, id) {
+  return path4.join(sessionDir(home, id), "artifacts");
+}
+function issuesDir(home) {
+  return path4.join(home, "issues");
+}
+function issueDir(home, id) {
+  return path4.join(issuesDir(home), id);
+}
+function metaPath(home, id) {
+  return path4.join(sessionDir(home, id), "meta.json");
+}
+function pidfilePath(home) {
+  return path4.join(home, "server.json");
+}
+async function ensureChambaHome(home) {
+  await mkdir(sessionsDir(home), { recursive: true });
+  await ensureGitignored(home);
+}
+async function ensureGitignored(home) {
+  if (path4.basename(home) !== ".chamba") return;
+  const gitignore = path4.join(path4.dirname(home), ".gitignore");
+  const entry = ".chamba/";
+  try {
+    let content = "";
+    try {
+      content = await readFile3(gitignore, "utf8");
+    } catch (err) {
+      if (err.code !== "ENOENT") return;
+    }
+    const already = content.split(/\r?\n/).some((line) => {
+      const trimmed = line.trim();
+      return trimmed === entry || trimmed === ".chamba";
+    });
+    if (already) return;
+    const prefix = content.length > 0 && !content.endsWith("\n") ? "\n" : "";
+    await appendFile(gitignore, `${prefix}${entry}
+`, "utf8");
+  } catch {
+  }
+}
+
+// packages/server/src/lifecycle.ts
+var ServerConflictError = class extends Error {
+  constructor(existing) {
+    super(`chamba server already running (pid ${existing.pid}, port ${existing.port})`);
+    this.existing = existing;
+    this.name = "ServerConflictError";
+  }
+};
+async function acquirePidfile(home, port) {
+  const file = pidfilePath(home);
+  const info = { pid: process.pid, port, startedAt: (/* @__PURE__ */ new Date()).toISOString() };
+  for (let attempt = 0; attempt < 3; attempt++) {
+    try {
+      const handle = await open(file, "wx");
+      await handle.writeFile(`${JSON.stringify(info, null, 2)}
+`);
+      await handle.close();
+      return makeHandle(file, info.pid);
+    } catch (err) {
+      if (err.code !== "EEXIST") throw err;
+      const existing = await readPidfile(file);
+      if (existing && existing.pid !== process.pid && await isServerLive(existing)) {
+        throw new ServerConflictError(existing);
+      }
+      await rm(file, { force: true });
+    }
+  }
+  throw new Error("could not acquire chamba pidfile");
+}
+function makeHandle(file, ownerPid) {
+  let released = false;
+  const releaseSync = () => {
+    if (released) return;
+    released = true;
+    try {
+      unlinkSync(file);
+    } catch {
+    }
+  };
+  process.once("exit", releaseSync);
+  return {
+    release: async () => {
+      if (released) return;
+      released = true;
+      try {
+        const current = await readPidfile(file);
+        if (!current || current.pid === ownerPid) await rm(file, { force: true });
+      } catch {
+      }
+    }
+  };
+}
+async function readPidfile(file) {
+  try {
+    const raw = await readFile4(file, "utf8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.pid === "number" && typeof parsed.port === "number") return parsed;
+    return null;
+  } catch {
+    return null;
+  }
+}
+function isPidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === "EPERM";
+  }
+}
+async function isServerLive(info) {
+  if (!isPidAlive(info.pid)) return false;
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 500);
+    const res = await fetch(`http://127.0.0.1:${info.port}/api/health`, {
+      signal: controller.signal
+    });
+    clearTimeout(timer);
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+function startIdleWatchdog(opts) {
+  if (opts.idleMs <= 0) return () => void 0;
+  const interval = opts.intervalMs ?? Math.min(opts.idleMs, 5e3);
+  let idleSince = Date.now();
+  const timer = setInterval(() => {
+    if (opts.isBusy()) {
+      idleSince = Date.now();
+      return;
+    }
+    if (Date.now() - idleSince >= opts.idleMs) opts.onIdle();
+  }, interval);
+  timer.unref?.();
+  return () => clearInterval(timer);
+}
+
+// packages/server/src/port.ts
+var DEFAULT_PORT = 4319;
+var DEFAULT_BIND_HOST = "127.0.0.1";
+function resolveBindHost(argv = process.argv.slice(2)) {
+  const flag = readFlag(argv, "--host");
+  if (flag !== void 0 && flag.length > 0) return flag;
+  const env = process.env.CHAMBA_HOST;
+  if (env !== void 0 && env.length > 0) return env;
+  return DEFAULT_BIND_HOST;
+}
+function resolvePort(argv = process.argv.slice(2), home) {
+  const flag = readFlag(argv, "--port");
+  if (flag !== void 0) return parsePort(flag, "--port");
+  const env = process.env.CHAMBA_PORT;
+  if (env !== void 0 && env.length > 0) return parsePort(env, "CHAMBA_PORT");
+  return home !== void 0 ? derivePort(home) : DEFAULT_PORT;
+}
+function derivePort(home) {
+  let hash = 2166136261;
+  for (let i = 0; i < home.length; i++) {
+    hash ^= home.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return DEFAULT_PORT + Math.abs(hash) % 512;
+}
+function readFlag(argv, name) {
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === name) return argv[i + 1];
+    if (arg?.startsWith(`${name}=`)) return arg.slice(name.length + 1);
+  }
+  return void 0;
+}
+function parsePort(value, source) {
+  const port = Number(value);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error(`invalid ${source}: ${value}`);
+  }
+  return port;
+}
+
+// packages/server/src/presence.ts
+var PresenceTracker = class {
+  /**
+   * `idleAwayMs` is how long presence stays `listening` after a normal poll
+   * return - long enough to bridge real work gaps. `dropAwayMs` is the shorter
+   * window used when a poll's client disconnected, so a killed or crashed agent
+   * surfaces quickly. Both are unrelated to `ServeOptions.idleMs`, which is the
+   * server's own self-shutdown window.
+   */
+  constructor(idleAwayMs = 30 * 6e4, dropAwayMs = 1e4) {
+    this.idleAwayMs = idleAwayMs;
+    this.dropAwayMs = dropAwayMs;
+  }
+  active = /* @__PURE__ */ new Map();
+  lastSeen = /* @__PURE__ */ new Map();
+  state = /* @__PURE__ */ new Map();
+  timers = /* @__PURE__ */ new Map();
+  listeners = /* @__PURE__ */ new Set();
+  get(id) {
+    return this.state.get(id) ?? "away";
+  }
+  /** A poll has parked: the agent is definitely present. */
+  enter(id) {
+    this.active.set(id, (this.active.get(id) ?? 0) + 1);
+    this.lastSeen.set(id, Date.now());
+    this.clearTimer(id);
+    this.set(id, "listening");
+  }
+  /**
+   * A poll returned or timed out: still present through the away window. `dropped`
+   * marks a client disconnect (the agent's process died or was killed mid-poll),
+   * which uses the short window; a normal return uses the long one. `delivered`
+   * marks a clean return that carried input - the agent took the human's message
+   * and left to work - so with no poll left parked the state flips to `working`,
+   * with the long window as the backstop if the agent never comes back.
+   */
+  leave(id, dropped = false, delivered = false) {
+    const remaining = Math.max(0, (this.active.get(id) ?? 1) - 1);
+    this.active.set(id, remaining);
+    this.lastSeen.set(id, Date.now());
+    if (remaining > 0) return;
+    if (delivered && !dropped) this.set(id, "working");
+    this.scheduleAway(id, dropped ? this.dropAwayMs : this.idleAwayMs);
+  }
+  /** Any other sign of life (e.g. a reply) keeps the agent listening. */
+  beat(id) {
+    this.lastSeen.set(id, Date.now());
+    this.set(id, "listening");
+    if ((this.active.get(id) ?? 0) === 0) this.scheduleAway(id, this.idleAwayMs);
+  }
+  /** True while any session has a parked poll - used to hold off idle shutdown. */
+  hasActivePolls() {
+    for (const count of this.active.values()) {
+      if (count > 0) return true;
+    }
+    return false;
+  }
+  onChange(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  scheduleAway(id, delayMs) {
+    this.clearTimer(id);
+    const timer = setTimeout(() => {
+      this.timers.delete(id);
+      if ((this.active.get(id) ?? 0) === 0) this.set(id, "away");
+    }, delayMs);
+    timer.unref?.();
+    this.timers.set(id, timer);
+  }
+  clearTimer(id) {
+    const timer = this.timers.get(id);
+    if (timer) {
+      clearTimeout(timer);
+      this.timers.delete(id);
+    }
+  }
+  set(id, next) {
+    if (this.state.get(id) === next) return;
+    this.state.set(id, next);
+    for (const listener of [...this.listeners]) listener(id, next);
+  }
+};
+
+// packages/server/src/sessions/index.ts
+import { randomBytes, randomUUID as randomUUID3 } from "node:crypto";
+import { mkdir as mkdir3, readdir as readdir2, readFile as readFile7, stat, writeFile as writeFile2 } from "node:fs/promises";
+import path7 from "node:path";
+
+// packages/server/src/version.ts
+import { existsSync as existsSync4, readFileSync } from "node:fs";
+import path5 from "node:path";
+import { fileURLToPath as fileURLToPath3 } from "node:url";
+function chambaVersion() {
+  let dir = path5.dirname(fileURLToPath3(import.meta.url));
+  for (; ; ) {
+    const manifest = path5.join(dir, "package.json");
+    if (existsSync4(manifest)) {
+      try {
+        const { version } = JSON.parse(readFileSync(manifest, "utf8"));
+        if (typeof version === "string" && version) return version;
+      } catch {
+      }
+    }
+    const parent = path5.dirname(dir);
+    if (parent === dir) return "0.0.0-dev";
+    dir = parent;
+  }
+}
+
+// packages/server/src/issues.ts
+function buildIssueRecord(input) {
+  return {
+    id: input.id,
+    type: input.type,
+    text: input.text,
+    filedAt: input.filedAt,
+    chambaVersion: chambaVersion(),
+    session: {
+      id: input.meta.id,
+      kind: input.meta.kind ?? "unset",
+      status: input.meta.status,
+      ...input.meta.title ? { title: input.meta.title } : {}
+    },
+    env: {
+      node: process.version,
+      platform: process.platform,
+      arch: process.arch,
+      cwd: process.cwd()
+    },
+    screenshots: input.screenshots,
+    recentEvents: input.tail.map(summarizeEvent)
+  };
+}
+function renderIssueMarkdown(record) {
+  const lines = [
+    `# ${record.type === "bug" ? "Bug" : "Feature request"}`,
+    "",
+    record.text,
+    "",
+    "## Context",
+    "",
+    `- chamba version: ${record.chambaVersion}`,
+    `- session: ${record.session.id} (${record.session.kind}, ${record.session.status})`,
+    ...record.session.title ? [`- session title: ${record.session.title}`] : [],
+    `- environment: node ${record.env.node} on ${record.env.platform}/${record.env.arch}`,
+    `- cwd: ${record.env.cwd}`,
+    `- filed: ${record.filedAt}`
+  ];
+  if (record.screenshots.length > 0) {
+    lines.push("", "### Screenshots", "");
+    for (const name of record.screenshots) lines.push(`- ${name}`);
+  }
+  if (record.recentEvents.length > 0) {
+    lines.push("", "### Recent session events", "");
+    for (const event of record.recentEvents) {
+      const text = event.text ? `: ${event.text}` : "";
+      lines.push(`- [${event.seq}] ${event.ts} ${event.source}/${event.type}${text}`);
+    }
+  }
+  return `${lines.join("\n")}
+`;
+}
+function summarizeEvent(event) {
+  return {
+    seq: event.seq,
+    ts: event.ts,
+    source: event.source,
+    type: event.type,
+    ...eventText(event) ? { text: truncate(eventText(event), 200) } : {}
+  };
+}
+function eventText(event) {
+  const payload = event.payload;
+  if (payload && typeof payload === "object") {
+    const record = payload;
+    if (typeof record.text === "string") return record.text;
+    if (typeof record.reason === "string") return record.reason;
+  }
+  return "";
+}
+function truncate(text, max) {
+  const oneLine = text.replace(/\s+/g, " ").trim();
+  return oneLine.length > max ? `${oneLine.slice(0, max - 1)}\u2026` : oneLine;
+}
+
+// packages/server/src/sessions/log.ts
+import { randomUUID } from "node:crypto";
+import { mkdir as mkdir2, open as open2, readFile as readFile5, truncate as truncate2 } from "node:fs/promises";
+import path6 from "node:path";
+var SessionLog = class {
+  constructor(id, file) {
+    this.id = id;
+    this.file = file;
+  }
+  events = [];
+  handle = null;
+  loaded = false;
+  loading = null;
+  mutex = Promise.resolve();
+  listeners = /* @__PURE__ */ new Set();
+  /** Replay the ndjson file into memory and open the append handle. Idempotent. */
+  async load() {
+    if (this.loaded) return;
+    if (this.loading) return this.loading;
+    this.loading = this.replay();
+    try {
+      await this.loading;
+    } finally {
+      this.loading = null;
+    }
+  }
+  async replay() {
+    await mkdir2(path6.dirname(this.file), { recursive: true });
+    this.events = [];
+    let content = "";
+    try {
+      content = await readFile5(this.file, "utf8");
+    } catch (err) {
+      if (err.code !== "ENOENT") throw err;
+    }
+    const lines = content.split("\n");
+    let validBytes = 0;
+    let truncateTo = null;
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i] ?? "";
+      const hasSeparator = i < lines.length - 1;
+      const byteLen = Buffer.byteLength(line, "utf8") + (hasSeparator ? 1 : 0);
+      if (line.trim().length === 0) {
+        validBytes += byteLen;
+        continue;
+      }
+      try {
+        this.events.push(eventEnvelopeSchema.parse(JSON.parse(line)));
+        validBytes += byteLen;
+      } catch (err) {
+        const isLastContentLine = lines.slice(i + 1).every((rest) => rest.trim().length === 0);
+        if (isLastContentLine && !hasSeparator) {
+          truncateTo = validBytes;
+          break;
+        }
+        throw err;
+      }
+    }
+    if (truncateTo !== null) await truncate2(this.file, truncateTo);
+    this.handle = await open2(this.file, "a");
+    this.loaded = true;
+  }
+  /** Total events == next seq to be assigned == the "caught up" cursor. */
+  get nextSeq() {
+    return this.events.length;
+  }
+  /** Every event with `seq >= since`, in order. Pure read from memory. */
+  readSince(since) {
+    if (since <= 0) return this.events.slice();
+    return this.events.slice(since);
+  }
+  /** The last `n` events (for the catch-up digest). */
+  tail(n) {
+    if (n <= 0) return [];
+    return this.events.slice(Math.max(0, this.events.length - n));
+  }
+  /** True if a qualifying (non-agent) event exists at or beyond `since`. */
+  hasIncoming(since) {
+    for (let i = Math.max(0, since); i < this.events.length; i++) {
+      const event = this.events[i];
+      if (event && event.source !== "agent") return true;
+    }
+    return false;
+  }
+  /**
+   * Append one event durably. Serialized so seq assignment and the write can
+   * never interleave; resolves only after `fsync`. Listeners (WS broadcast,
+   * presence, parked polls) fire synchronously right after the in-memory push,
+   * with no `await` in between - so a poller that just read `events` and is about
+   * to register cannot miss the wakeup.
+   */
+  async append(input) {
+    await this.load();
+    const run = this.mutex.then(async () => {
+      const handle = this.handle;
+      if (!handle) throw new Error("session log not open");
+      const event = {
+        id: randomUUID(),
+        seq: this.events.length,
+        sessionId: this.id,
+        ts: (/* @__PURE__ */ new Date()).toISOString(),
+        type: input.type,
+        source: input.source,
+        payload: input.payload
+      };
+      await handle.write(`${JSON.stringify(event)}
+`);
+      await handle.sync();
+      this.events.push(event);
+      this.emit(event);
+      return event;
+    });
+    this.mutex = run.catch(() => void 0);
+    return run;
+  }
+  /** Subscribe to every future append (WS/presence). Returns an unsubscribe. */
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  /**
+   * Resolve on the next append or when `timeoutMs`/`signal` fires. Registration
+   * is synchronous (in the Promise executor), so callers can qualify-check then
+   * await this with no yield between - no lost wakeup.
+   */
+  waitForAppend(timeoutMs, signal) {
+    return new Promise((resolve) => {
+      const finish = () => {
+        clearTimeout(timer);
+        this.listeners.delete(onAppend);
+        signal?.removeEventListener("abort", finish);
+        resolve();
+      };
+      const onAppend = () => finish();
+      const timer = setTimeout(finish, timeoutMs);
+      this.listeners.add(onAppend);
+      if (signal) {
+        if (signal.aborted) {
+          finish();
+          return;
+        }
+        signal.addEventListener("abort", finish, { once: true });
+      }
+    });
+  }
+  emit(event) {
+    for (const listener of [...this.listeners]) listener(event);
+  }
+  async close() {
+    const handle = this.handle;
+    this.handle = null;
+    this.loaded = false;
+    await handle?.close();
+  }
+};
+
+// packages/server/src/sessions/meta.ts
+import { randomUUID as randomUUID2 } from "node:crypto";
+import { readdir, readFile as readFile6, rename, rm as rm2, writeFile } from "node:fs/promises";
+async function readMeta(home, id) {
+  try {
+    const raw = await readFile6(metaPath(home, id), "utf8");
+    return sessionMetaSchema.parse(JSON.parse(raw));
+  } catch (err) {
+    if (err.code === "ENOENT") return null;
+    throw err;
+  }
+}
+async function writeMeta(home, meta) {
+  const target = metaPath(home, meta.id);
+  const tmp = `${target}.${randomUUID2()}.tmp`;
+  try {
+    await writeFile(tmp, `${JSON.stringify(meta, null, 2)}
+`, "utf8");
+    await rename(tmp, target);
+  } catch (err) {
+    await rm2(tmp, { force: true }).catch(() => void 0);
+    throw err;
+  }
+}
+async function listSessionIds(home) {
+  try {
+    const entries = await readdir(sessionsDir(home), { withFileTypes: true });
+    return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+  } catch (err) {
+    if (err.code === "ENOENT") return [];
+    throw err;
+  }
+}
+
+// packages/server/src/sessions/index.ts
+var Sessions = class {
+  constructor(home) {
+    this.home = home;
+  }
+  logs = /* @__PURE__ */ new Map();
+  metaCache = /* @__PURE__ */ new Map();
+  metaLocks = /* @__PURE__ */ new Map();
+  /**
+   * Serialize a meta read-modify-write for one session. Without this, a message's
+   * `touch` can read `active` from cache, then write it back on top of an `end`
+   * that landed in between - leaving `meta.json` `active` while the log holds a
+   * `session-ended` event. Chaining every read+write per session makes the last
+   * writer see the previous one's result, so status can never regress.
+   */
+  withMetaLock(id, fn) {
+    const prev = this.metaLocks.get(id) ?? Promise.resolve();
+    const run = prev.then(fn, fn);
+    this.metaLocks.set(
+      id,
+      run.then(
+        () => void 0,
+        () => void 0
+      )
+    );
+    return run;
+  }
+  async init() {
+    await ensureChambaHome(this.home);
+  }
+  async create(req) {
+    await ensureChambaHome(this.home);
+    const id = await this.generateId();
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const meta = {
+      id,
+      ...req.kind ? { kind: req.kind } : {},
+      ...req.title ? { title: req.title } : {},
+      status: "active",
+      createdAt: now,
+      updatedAt: now
+    };
+    await this.logFor(id);
+    await writeMeta(this.home, meta);
+    this.metaCache.set(id, meta);
+    await this.append(id, {
+      type: "system",
+      source: "system",
+      payload: { reason: "session-created" }
+    });
+    return await this.getMeta(id) ?? meta;
+  }
+  async getMeta(id) {
+    const cached = this.metaCache.get(id);
+    if (cached) return cached;
+    const meta = await readMeta(this.home, id);
+    if (meta) this.metaCache.set(id, meta);
+    return meta;
+  }
+  async list() {
+    const ids = await listSessionIds(this.home);
+    const metas = await Promise.all(ids.map((id) => this.getMeta(id)));
+    return metas.filter((meta) => meta !== null).sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+  }
+  /** Get (or lazily create + replay) the in-memory log for a session. */
+  async logFor(id) {
+    let log = this.logs.get(id);
+    if (!log) {
+      log = new SessionLog(id, logPath(this.home, id));
+      this.logs.set(id, log);
+    }
+    await log.load();
+    return log;
+  }
+  /** Durable append; also bumps the session's `updatedAt`. */
+  async append(id, input) {
+    const log = await this.logFor(id);
+    const event = await log.append(input);
+    await this.touch(id);
+    return event;
+  }
+  postMessage(id, body) {
+    return this.append(id, { type: "message", source: "user", payload: messagePayload(body) });
+  }
+  reply(id, body) {
+    return this.append(id, { type: "message", source: "agent", payload: messagePayload(body) });
+  }
+  /** Append a batch of element comments as one `annotation-batch` event (source
+   * `user`, so the agent's poll delivers it like any incoming line). */
+  postAnnotations(id, items) {
+    return this.append(id, { type: ANNOTATION_BATCH, source: "user", payload: { items } });
+  }
+  /** A structured interview question, rendered as a card in the conversation. The
+   * agent authors these, so the source is `agent` (like a reply); the user's
+   * answer comes back as a normal `message`. */
+  postQuestionCard(id, payload) {
+    return this.append(id, { type: QUESTION_CARD, source: "agent", payload });
+  }
+  /** A decision-log entry (confirmed-by-user vs. assumed-by-agent). Agent-sourced. */
+  postDecision(id, payload) {
+    return this.append(id, { type: DECISION, source: "agent", payload });
+  }
+  /** Announce an authored/revised artifact. The bytes were written by
+   * `saveArtifact`; this records the reference as an event so the surface tab and
+   * the thread learn about the revision. Agent-sourced. */
+  postArtifact(id, artifact) {
+    return this.append(id, { type: ARTIFACT, source: "agent", payload: { artifact } });
+  }
+  /** Record that the user activated another session, so the agent's poll on this
+   * one learns where to hand off (attach the target, digest, keep attending). */
+  moveAway(id, to) {
+    return this.append(id, {
+      type: "system",
+      source: "system",
+      payload: { reason: "user-moved-away", ...to ? { to } : {} }
+    });
+  }
+  /**
+   * Persist an uploaded file into the session's attachments directory and return
+   * its durable reference. The stored name embeds a generated id and the sanitized
+   * original (`<attId>__<name>`), so the file is self-describing on disk and
+   * resolvable later without a sidecar; the recorded path stays session-relative.
+   */
+  async saveAttachment(id, name, bytes) {
+    const dir = attachmentsDir(this.home, id);
+    await mkdir3(dir, { recursive: true });
+    const attId = randomUUID3();
+    const safeName = sanitizeName(name);
+    const stored = `${attId}__${safeName}`;
+    await writeFile2(path7.join(dir, stored), bytes);
+    return {
+      id: attId,
+      name: safeName,
+      relPath: `attachments/${stored}`,
+      contentType: contentTypeFor(safeName),
+      size: bytes.byteLength
+    };
+  }
+  /** Rebuild an attachment reference from disk by its id (null if absent). */
+  async resolveAttachment(id, attId) {
+    const stored = await this.storedAttachment(id, attId);
+    if (!stored) return null;
+    const info = await stat(path7.join(attachmentsDir(this.home, id), stored));
+    return {
+      id: attId,
+      name: stored.slice(attId.length + 2),
+      relPath: `attachments/${stored}`,
+      contentType: contentTypeFor(stored),
+      size: info.size
+    };
+  }
+  /** Read an attachment's bytes and content type for serving (null if absent).
+   * The bytes are copied into a plain `ArrayBuffer`-backed view so the response
+   * layer can stream them directly (a `Buffer` widens to `ArrayBufferLike`). */
+  async readAttachment(id, attId) {
+    const stored = await this.storedAttachment(id, attId);
+    if (!stored) return null;
+    const raw = await readFile7(path7.join(attachmentsDir(this.home, id), stored));
+    const bytes = new Uint8Array(new ArrayBuffer(raw.byteLength));
+    bytes.set(raw);
+    return { bytes, contentType: contentTypeFor(stored) };
+  }
+  /**
+   * Persist an artifact's source text under the session's `artifacts/` directory
+   * and return its durable reference. Re-posting the same (kind, name) overwrites
+   * the file - the latest content is what the surface tab and export use, while
+   * the event log preserves that a revision happened. The stored filename embeds
+   * the kind and a kind-specific extension (`draft-*.md`, `mock-*.html`,
+   * `diagram-*.mmd`), so a file is self-describing and the serve route can infer
+   * how to render it without a sidecar.
+   */
+  async saveArtifact(id, kind, name, content) {
+    const dir = artifactsDir(this.home, id);
+    await mkdir3(dir, { recursive: true });
+    const ext = ARTIFACT_EXT[kind];
+    const base = sanitizeName(name).replace(/\.(md|markdown|html?|mmd|mermaid)$/i, "");
+    const stored = `${kind}-${base || "spec"}${ext}`;
+    const bytes = Buffer.from(content, "utf8");
+    await writeFile2(path7.join(dir, stored), bytes);
+    return {
+      kind,
+      name,
+      relPath: `artifacts/${stored}`,
+      contentType: ARTIFACT_CONTENT_TYPE[kind],
+      size: bytes.byteLength
+    };
+  }
+  /** Read a stored artifact by its on-disk filename (basename of a ref's
+   * `relPath`), or null. The session id and the name are both guarded to flat safe
+   * tokens so the serve route cannot be walked out of the artifacts directory. */
+  async readArtifact(id, file) {
+    if (!isSafeId(id)) return null;
+    if (!/^[A-Za-z0-9._-]+$/.test(file) || file.includes("..")) return null;
+    try {
+      const content = await readFile7(path7.join(artifactsDir(this.home, id), file), "utf8");
+      return { content, file };
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * File an offline issue report under `.chamba/issues/<id>/`. Referenced
+   * screenshots are copied in as self-contained files, then `report.md` and
+   * `context.json` capture the report plus auto-collected context (chamba
+   * version, the session, a tail of recent events, basic env). Returns the new
+   * id and the absolute directory, or `null` if a referenced screenshot id is
+   * unknown for this session. Deliberately never appends to the log - an issue is
+   * an on-disk artifact, not a conversation event.
+   */
+  async saveIssue(meta, req) {
+    const resolved = [];
+    for (const attId of req.screenshotAttachmentIds ?? []) {
+      const ref = await this.resolveAttachment(meta.id, attId);
+      const file = await this.readAttachment(meta.id, attId);
+      if (!ref || !file) return null;
+      const ext = path7.extname(ref.name) || extFromContentType(file.contentType);
+      resolved.push({ name: `screenshot-${resolved.length + 1}${ext}`, bytes: file.bytes });
+    }
+    const id = await this.generateId();
+    const dir = issueDir(this.home, id);
+    await mkdir3(dir, { recursive: true });
+    for (const shot of resolved) await writeFile2(path7.join(dir, shot.name), shot.bytes);
+    const tail = (await this.logFor(meta.id)).tail(ISSUE_TAIL);
+    const record = buildIssueRecord({
+      id,
+      type: req.type,
+      text: req.text,
+      filedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      meta,
+      tail,
+      screenshots: resolved.map((shot) => shot.name)
+    });
+    await writeFile2(path7.join(dir, "report.md"), renderIssueMarkdown(record), "utf8");
+    await writeFile2(path7.join(dir, "context.json"), `${JSON.stringify(record, null, 2)}
+`, "utf8");
+    return { id, path: dir };
+  }
+  /** The on-disk filename for an attachment id, or null. The id is a uuid (no
+   * `__`), so the `<attId>__` prefix uniquely identifies one stored file. The
+   * session id is guarded too: the attachment-serve route reaches here without the
+   * `getMeta` check the other routes use, so an unsafe id must fail closed here. */
+  async storedAttachment(id, attId) {
+    if (!isSafeId(id)) return null;
+    if (!/^[0-9a-f-]+$/i.test(attId)) return null;
+    let entries;
+    try {
+      entries = await readdir2(attachmentsDir(this.home, id));
+    } catch {
+      return null;
+    }
+    return entries.find((entry) => entry.startsWith(`${attId}__`)) ?? null;
+  }
+  /**
+   * The agent long-poll: return every incoming (non-agent) event at or beyond
+   * `since`, parking until one arrives or the wait elapses. The sync
+   * qualify-check and waiter registration have no `await` between them, so an
+   * append concurrent with a poll can never be missed.
+   */
+  async poll(id, since, waitMs, signal) {
+    const log = await this.logFor(id);
+    const deadline = Date.now() + waitMs;
+    while (true) {
+      if (log.hasIncoming(since)) {
+        const events = log.readSince(since).filter((event) => event.source !== "agent");
+        return { events, cursor: log.nextSeq };
+      }
+      const remaining = deadline - Date.now();
+      if (remaining <= 0 || signal?.aborted) return { events: [], cursor: log.nextSeq };
+      await log.waitForAppend(remaining, signal);
+    }
+  }
+  /** Non-blocking history read (all sources), optionally capped. */
+  async events(id, since, limit) {
+    const log = await this.logFor(id);
+    const all = log.readSince(since);
+    const events = limit && limit > 0 ? all.slice(0, limit) : all;
+    return { events, cursor: log.nextSeq };
+  }
+  /** The catch-up digest: metadata, a recent tail, the poll cursor, how to get more. */
+  async attach(id, tailN, presence) {
+    const meta = await this.getMeta(id);
+    if (!meta) return null;
+    const log = await this.logFor(id);
+    const tail = log.tail(tailN);
+    const earliest = tail.length > 0 ? tail[0]?.seq ?? 0 : log.nextSeq;
+    return {
+      meta,
+      presence,
+      tail,
+      cursor: log.nextSeq,
+      fetchMore: {
+        hasMore: earliest > 0,
+        earliestLoadedSeq: earliest,
+        hint: earliest > 0 ? `chamba events --since 0 (older history before seq ${earliest})` : "none"
+      }
+    };
+  }
+  /** End a session: append the lifecycle marker, flip status to `ended`. */
+  async end(id) {
+    const meta = await this.getMeta(id);
+    if (!meta) return null;
+    if (meta.status === "ended") return meta;
+    await this.append(id, {
+      type: "system",
+      source: "system",
+      payload: { reason: "session-ended" }
+    });
+    return this.withMetaLock(id, async () => {
+      const current = await this.getMeta(id) ?? meta;
+      const ended = {
+        ...current,
+        status: "ended",
+        updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      await writeMeta(this.home, ended);
+      this.metaCache.set(id, ended);
+      return ended;
+    });
+  }
+  /**
+   * Set the kind of an undecided session - the human's choice in the browser.
+   * Allowed once: a session that is unknown, ended, or already has a kind is
+   * refused. Appends a `kind-chosen` marker so the agent's poll learns the choice,
+   * then locks the kind into meta. Keeps the property that a decided session's
+   * kind never changes (an everyday session never grows spec events).
+   */
+  async setKind(id, kind) {
+    const meta = await this.getMeta(id);
+    if (!meta) return { ok: false, reason: "unknown" };
+    if (meta.status === "ended") return { ok: false, reason: "ended" };
+    if (meta.kind) return { ok: false, reason: "already-set" };
+    await this.append(id, {
+      type: "system",
+      source: "system",
+      payload: { reason: "kind-chosen", kind }
+    });
+    return this.withMetaLock(id, async () => {
+      const current = await this.getMeta(id) ?? meta;
+      const decided = { ...current, kind, updatedAt: (/* @__PURE__ */ new Date()).toISOString() };
+      await writeMeta(this.home, decided);
+      this.metaCache.set(id, decided);
+      return { ok: true, meta: decided };
+    });
+  }
+  touch(id) {
+    return this.withMetaLock(id, async () => {
+      const meta = await this.getMeta(id);
+      if (!meta) return;
+      const updated = { ...meta, updatedAt: (/* @__PURE__ */ new Date()).toISOString() };
+      await writeMeta(this.home, updated);
+      this.metaCache.set(id, updated);
+    });
+  }
+  async generateId() {
+    for (let attempt = 0; attempt < 5; attempt++) {
+      const id = `${Date.now().toString(36)}${randomBytes(3).toString("hex")}`;
+      if (await readMeta(this.home, id) === null) return id;
+    }
+    return randomUUID3();
+  }
+};
+function isSafeId(id) {
+  return /^[A-Za-z0-9_-]+$/.test(id);
+}
+var ISSUE_TAIL = 20;
+function extFromContentType(contentType) {
+  const type = contentType.split(";")[0]?.trim().toLowerCase();
+  switch (type) {
+    case "image/png":
+      return ".png";
+    case "image/jpeg":
+      return ".jpg";
+    case "image/gif":
+      return ".gif";
+    case "image/webp":
+      return ".webp";
+    case "image/svg+xml":
+      return ".svg";
+    default:
+      return ".bin";
+  }
+}
+var ARTIFACT_EXT = {
+  draft: ".md",
+  mock: ".html",
+  diagram: ".mmd"
+};
+var ARTIFACT_CONTENT_TYPE = {
+  draft: "text/markdown; charset=utf-8",
+  mock: "text/html; charset=utf-8",
+  diagram: "text/plain; charset=utf-8"
+};
+function messagePayload(body) {
+  return {
+    ...body.text ? { text: body.text } : {},
+    ...body.attachments && body.attachments.length > 0 ? { attachments: body.attachments } : {}
+  };
+}
+function sanitizeName(name) {
+  const base = name.split(/[\\/]/).pop() ?? name;
+  const cleaned = base.replace(/[^A-Za-z0-9._-]/g, "_").replace(/^\.+/, "");
+  return cleaned.length > 0 ? cleaned.slice(0, 120) : "file";
+}
+
+// packages/server/src/ws.ts
+var WsHub = class {
+  rooms = /* @__PURE__ */ new Map();
+  forwarders = /* @__PURE__ */ new Map();
+  /** Add a socket to a room; returns true if it is the room's first socket. */
+  add(id, ws) {
+    let room = this.rooms.get(id);
+    if (!room) {
+      room = /* @__PURE__ */ new Set();
+      this.rooms.set(id, room);
+    }
+    room.add(ws);
+    return room.size === 1;
+  }
+  remove(id, ws) {
+    const room = this.rooms.get(id);
+    if (!room) return;
+    room.delete(ws);
+    if (room.size === 0) {
+      this.rooms.delete(id);
+      const unsubscribe = this.forwarders.get(id);
+      if (unsubscribe) {
+        unsubscribe();
+        this.forwarders.delete(id);
+      }
+    }
+  }
+  setForwarder(id, unsubscribe) {
+    this.forwarders.set(id, unsubscribe);
+  }
+  broadcast(id, message) {
+    const room = this.rooms.get(id);
+    if (!room) return;
+    const data = JSON.stringify(message);
+    for (const ws of [...room]) {
+      try {
+        ws.send(data);
+      } catch {
+      }
+    }
+  }
+  hasClients() {
+    return this.rooms.size > 0;
+  }
+};
+
+// packages/server/src/index.ts
+var DEFAULT_IDLE_MS = 5 * 6e4;
+async function serve(options = {}) {
+  const home = options.home ?? resolveHome();
+  const port = options.port ?? resolvePort(process.argv.slice(2), home);
+  const host = options.host ?? resolveBindHost();
+  const webDist = options.webDist ?? resolveWebDist();
+  const injectDist = options.injectDist ?? resolveInjectDist();
+  const sessions = new Sessions(home);
+  await sessions.init();
+  const presence = new PresenceTracker();
+  const hub = new WsHub();
+  const { app, injectWebSocket } = createApp({
+    sessions,
+    presence,
+    hub,
+    webDist,
+    injectDist,
+    home,
+    port,
+    version: chambaVersion()
+  });
+  const pid = await acquirePidfile(home, port);
+  const server = honoServe({ fetch: app.fetch, hostname: host, port });
+  injectWebSocket(server);
+  try {
+    await waitListening(server);
+  } catch (err) {
+    await pid.release();
+    throw err;
+  }
+  let closing = false;
+  let stopWatchdog = () => void 0;
+  const close = async () => {
+    if (closing) return;
+    closing = true;
+    stopWatchdog();
+    await closeServer(server);
+    await pid.release();
+  };
+  stopWatchdog = startIdleWatchdog({
+    idleMs: options.idleMs ?? parseIdleMs(process.env.CHAMBA_IDLE_MS) ?? DEFAULT_IDLE_MS,
+    isBusy: () => hub.hasClients() || presence.hasActivePolls(),
+    // `close()` drains in-flight connections (a POST is neither a WS client nor a
+    // parked poll, so `isBusy` does not count it) and releases the pidfile; the
+    // explicit exit then guarantees the detached process actually goes away rather
+    // than lingering on some stray handle.
+    onIdle: () => void close().then(() => process.exit(0))
+  });
+  return { port, url: `http://localhost:${port}/`, home, sessions, close };
+}
+function parseIdleMs(value) {
+  if (value === void 0 || value.length === 0) return null;
+  const n = Number(value);
+  return Number.isFinite(n) && n >= 0 ? Math.floor(n) : null;
+}
+function waitListening(server) {
+  return new Promise((resolve, reject) => {
+    const cleanup = () => {
+      server.off("listening", onListening);
+      server.off("error", onError);
+    };
+    const onListening = () => {
+      cleanup();
+      resolve();
+    };
+    const onError = (err) => {
+      cleanup();
+      reject(err);
+    };
+    server.once("listening", onListening);
+    server.once("error", onError);
+  });
+}
+function closeServer(server) {
+  return new Promise((resolve) => server.close(() => resolve()));
+}
+
+// packages/server/src/bin.ts
+async function main() {
+  try {
+    const running = await serve();
+    process.stdout.write(`chamba server listening on ${running.url}
+`);
+    const shutdown = () => {
+      void running.close().then(() => process.exit(0));
+    };
+    process.once("SIGINT", shutdown);
+    process.once("SIGTERM", shutdown);
+  } catch (err) {
+    if (err instanceof ServerConflictError) {
+      process.stdout.write(`${err.message}
+`);
+      process.exit(0);
+    }
+    process.stderr.write(`chamba server failed: ${err.message}
+`);
+    process.exit(1);
+  }
+}
+void main();