chamba 0.1.0 → 0.2.0

package/dist/server.js

@@ -2,91 +2,99 @@
 import { serve as honoServe } from "@hono/node-server";
 
 // packages/shared/src/annotations.ts
-import { z as z2 } from "zod";
+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 attachmentSchema = z.object({
+var sessionKindSchema = z.enum(["everyday", "spec"]);
+var sessionStatusSchema = z.enum(["active", "ended"]);
+var sessionMetaSchema = z.object({
   id: z.string().min(1),
-  name: z.string().min(1),
-  relPath: z.string().min(1),
-  contentType: z.string().min(1),
-  size: z.number().int().nonnegative()
+  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 = z.object({
-  text: z.string().min(1).optional(),
-  attachments: z.array(attachmentSchema).optional()
+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 = z.enum(["session-created", "user-moved-away", "session-ended"]);
-var systemPayloadSchema = z.object({
+var systemReasonSchema = z2.enum([
+  "session-created",
+  "user-moved-away",
+  "session-ended",
+  "kind-chosen"
+]);
+var systemPayloadSchema = z2.object({
   reason: systemReasonSchema,
-  to: z.string().min(1).optional()
+  to: z2.string().min(1).optional(),
+  kind: sessionKindSchema.optional()
 });
 
 // packages/shared/src/annotations.ts
 var ANNOTATION_BATCH = "annotation-batch";
-var annotationSourceSchema = z2.object({
-  file: z2.string().min(1),
-  line: z2.number().int().positive().optional(),
-  column: z2.number().int().positive().optional()
+var annotationSourceSchema = z3.object({
+  file: z3.string().min(1),
+  line: z3.number().int().positive().optional(),
+  column: z3.number().int().positive().optional()
 });
-var annotationComponentSchema = z2.object({
-  name: z2.string().min(1),
+var annotationComponentSchema = z3.object({
+  name: z3.string().min(1),
   source: annotationSourceSchema.optional()
 });
-var annotationTargetSchema = z2.object({
-  selector: z2.string().min(1),
-  pageUrl: z2.string().min(1),
-  viewport: z2.object({
-    width: z2.number().int().positive(),
-    height: z2.number().int().positive()
+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: z2.string().optional(),
+  label: z3.string().optional(),
   component: annotationComponentSchema.optional()
 });
-var annotationItemSchema = z2.object({
-  note: z2.string().min(1).optional(),
+var annotationItemSchema = z3.object({
+  note: z3.string().min(1).optional(),
   target: annotationTargetSchema,
   screenshot: attachmentSchema.optional()
 });
-var annotationBatchPayloadSchema = z2.object({
-  items: z2.array(annotationItemSchema).min(1)
+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 z3 } from "zod";
-var eventSourceSchema = z3.enum(["user", "agent", "system"]);
-var eventEnvelopeSchema = z3.object({
-  id: z3.string().uuid(),
-  seq: z3.number().int().nonnegative(),
-  sessionId: z3.string().min(1),
-  ts: z3.string().datetime(),
-  type: z3.string().min(1),
+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: z3.unknown()
+  payload: z4.unknown()
 });
 
 // packages/shared/src/presence.ts
-import { z as z4 } from "zod";
-var presenceSchema = z4.enum(["listening", "away"]);
-
-// packages/shared/src/session.ts
 import { z as z5 } from "zod";
-var sessionKindSchema = z5.enum(["everyday", "spec"]);
-var sessionStatusSchema = z5.enum(["active", "ended"]);
-var sessionMetaSchema = z5.object({
-  id: z5.string().min(1),
-  kind: sessionKindSchema,
-  title: z5.string().optional(),
-  status: sessionStatusSchema,
-  createdAt: z5.string().datetime(),
-  updatedAt: z5.string().datetime()
-});
+var presenceSchema = z5.enum(["listening", "working", "away"]);
 
 // packages/shared/src/spec.ts
 import { z as z6 } from "zod";
@@ -129,6 +137,9 @@ 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()
@@ -163,7 +174,8 @@ var eventResSchema = z7.object({
 });
 var pollResSchema = z7.object({
   events: z7.array(eventEnvelopeSchema),
-  cursor: cursorSchema
+  cursor: cursorSchema,
+  ended: z7.boolean().optional()
 });
 var fetchMoreSchema = z7.object({
   hasMore: z7.boolean(),
@@ -189,7 +201,10 @@ var sessionResSchema = z7.object({
 });
 var healthResSchema = z7.object({
   ok: z7.boolean(),
-  sessions: cursorSchema
+  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
@@ -221,6 +236,10 @@ var wsServerMessageSchema = z9.discriminatedUnion("t", [
     t: z9.literal("presence"),
     state: presenceSchema
   }),
+  z9.object({
+    t: z9.literal("kind"),
+    meta: sessionMetaSchema
+  }),
   z9.object({
     t: z9.literal("ended"),
     meta: sessionMetaSchema
@@ -357,7 +376,12 @@ function resolveWebDist() {
 }
 function createStaticHandler(webDist) {
   return async (c) => {
-    const pathname = decodeURIComponent(new URL(c.req.url).pathname);
+    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);
     }
@@ -389,6 +413,14 @@ async function readFileOrNull(filePath) {
 }
 
 // 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 });
@@ -400,7 +432,13 @@ function createApp(ctx) {
   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 });
+    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));
@@ -447,9 +485,14 @@ function createApp(ctx) {
     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);
@@ -458,7 +501,13 @@ function createApp(ctx) {
   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);
-    return c.body(file.bytes, 200, { "content-type": file.contentType });
+    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");
@@ -532,11 +581,13 @@ function createApp(ctx) {
     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);
-      return c.json(res);
+      delivered = res.events.length > 0;
+      return c.json({ ...res, ended: meta.status === "ended" });
     } finally {
-      ctx.presence.leave(id);
+      ctx.presence.leave(id, c.req.raw.signal.aborted, delivered);
     }
   });
   app.get("/api/sessions/:id/events", async (c) => {
@@ -555,6 +606,19 @@ function createApp(ctx) {
     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);
@@ -568,7 +632,7 @@ function createApp(ctx) {
       const id = new URL(c.req.url).searchParams.get("s") ?? "";
       return {
         onOpen: (_evt, ws) => {
-          void openSocket(ctx, id, ws);
+          openSocket(ctx, id, ws).catch(() => ws.close(1011, "internal error"));
         },
         onClose: (_evt, ws) => {
           ctx.hub.remove(id, ws);
@@ -675,11 +739,62 @@ 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 resolveHome() {
-  const override = process.env.CHAMBA_DIR;
-  return override && override.length > 0 ? path4.resolve(override) : path4.join(process.cwd(), ".chamba");
+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");
@@ -844,12 +959,20 @@ function resolveBindHost(argv = process.argv.slice(2)) {
   if (env !== void 0 && env.length > 0) return env;
   return DEFAULT_BIND_HOST;
 }
-function resolvePort(argv = process.argv.slice(2)) {
+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 DEFAULT_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++) {
@@ -861,7 +984,7 @@ function readFlag(argv, name) {
 }
 function parsePort(value, source) {
   const port = Number(value);
-  if (!Number.isInteger(port) || port < 0 || port > 65535) {
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
     throw new Error(`invalid ${source}: ${value}`);
   }
   return port;
@@ -869,8 +992,16 @@ function parsePort(value, source) {
 
 // packages/server/src/presence.ts
 var PresenceTracker = class {
-  constructor(graceMs = 9e3) {
-    this.graceMs = graceMs;
+  /**
+   * `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();
@@ -887,18 +1018,27 @@ var PresenceTracker = class {
     this.clearTimer(id);
     this.set(id, "listening");
   }
-  /** A poll returned or timed out: still present through the grace window. */
-  leave(id) {
+  /**
+   * 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) this.scheduleAway(id);
+    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);
+    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() {
@@ -911,12 +1051,12 @@ var PresenceTracker = class {
     this.listeners.add(listener);
     return () => this.listeners.delete(listener);
   }
-  scheduleAway(id) {
+  scheduleAway(id, delayMs) {
     this.clearTimer(id);
     const timer = setTimeout(() => {
       this.timers.delete(id);
       if ((this.active.get(id) ?? 0) === 0) this.set(id, "away");
-    }, this.graceMs);
+    }, delayMs);
     timer.unref?.();
     this.timers.set(id, timer);
   }
@@ -935,19 +1075,19 @@ var PresenceTracker = class {
 };
 
 // packages/server/src/sessions/index.ts
-import { randomBytes, randomUUID as randomUUID2 } from "node:crypto";
+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 existsSync3, readFileSync } from "node:fs";
+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 (existsSync3(manifest)) {
+    if (existsSync4(manifest)) {
       try {
         const { version } = JSON.parse(readFileSync(manifest, "utf8"));
         if (typeof version === "string" && version) return version;
@@ -970,7 +1110,7 @@ function buildIssueRecord(input) {
     chambaVersion: chambaVersion(),
     session: {
       id: input.meta.id,
-      kind: input.meta.kind,
+      kind: input.meta.kind ?? "unset",
       status: input.meta.status,
       ...input.meta.title ? { title: input.meta.title } : {}
     },
@@ -1038,7 +1178,7 @@ function truncate(text, max) {
 
 // packages/server/src/sessions/log.ts
 import { randomUUID } from "node:crypto";
-import { mkdir as mkdir2, open as open2, readFile as readFile5 } from "node:fs/promises";
+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) {
@@ -1064,17 +1204,37 @@ var SessionLog = class {
   }
   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;
     }
-    for (const line of content.split("\n")) {
-      const trimmed = line.trim();
-      if (trimmed.length === 0) continue;
-      this.events.push(eventEnvelopeSchema.parse(JSON.parse(trimmed)));
+    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;
   }
@@ -1173,7 +1333,8 @@ var SessionLog = class {
 };
 
 // packages/server/src/sessions/meta.ts
-import { readdir, readFile as readFile6, rename, writeFile } from "node:fs/promises";
+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");
@@ -1185,10 +1346,15 @@ async function readMeta(home, id) {
 }
 async function writeMeta(home, meta) {
   const target = metaPath(home, meta.id);
-  const tmp = `${target}.tmp`;
-  await writeFile(tmp, `${JSON.stringify(meta, null, 2)}
+  const tmp = `${target}.${randomUUID2()}.tmp`;
+  try {
+    await writeFile(tmp, `${JSON.stringify(meta, null, 2)}
 `, "utf8");
-  await rename(tmp, target);
+    await rename(tmp, target);
+  } catch (err) {
+    await rm2(tmp, { force: true }).catch(() => void 0);
+    throw err;
+  }
 }
 async function listSessionIds(home) {
   try {
@@ -1207,16 +1373,36 @@ var Sessions = class {
   }
   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.mintId();
+    const id = await this.generateId();
     const now = (/* @__PURE__ */ new Date()).toISOString();
     const meta = {
       id,
-      kind: req.kind ?? "everyday",
+      ...req.kind ? { kind: req.kind } : {},
       ...req.title ? { title: req.title } : {},
       status: "active",
       createdAt: now,
@@ -1299,14 +1485,14 @@ var Sessions = class {
   }
   /**
    * Persist an uploaded file into the session's attachments directory and return
-   * its durable reference. The stored name embeds a minted id and the sanitized
+   * 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 = randomUUID2();
+    const attId = randomUUID3();
     const safeName = sanitizeName(name);
     const stored = `${attId}__${safeName}`;
     await writeFile2(path7.join(dir, stored), bytes);
@@ -1368,9 +1554,10 @@ var Sessions = class {
     };
   }
   /** Read a stored artifact by its on-disk filename (basename of a ref's
-   * `relPath`), or null. The name is guarded to a flat safe filename so the serve
-   * route cannot be walked out of the artifacts directory. */
+   * `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");
@@ -1397,7 +1584,7 @@ var Sessions = class {
       const ext = path7.extname(ref.name) || extFromContentType(file.contentType);
       resolved.push({ name: `screenshot-${resolved.length + 1}${ext}`, bytes: file.bytes });
     }
-    const id = await this.mintId();
+    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);
@@ -1417,8 +1604,11 @@ var Sessions = class {
     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. */
+   * `__`), 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 {
@@ -1483,27 +1673,63 @@ var Sessions = class {
       source: "system",
       payload: { reason: "session-ended" }
     });
-    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;
+    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;
+    });
   }
-  async touch(id) {
+  /**
+   * 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;
-    const updated = { ...meta, updatedAt: (/* @__PURE__ */ new Date()).toISOString() };
-    await writeMeta(this.home, updated);
-    this.metaCache.set(id, updated);
+    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 mintId() {
+  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 randomUUID2();
+    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();
@@ -1594,7 +1820,7 @@ var WsHub = class {
 var DEFAULT_IDLE_MS = 5 * 6e4;
 async function serve(options = {}) {
   const home = options.home ?? resolveHome();
-  const port = options.port ?? resolvePort();
+  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();
@@ -1602,7 +1828,16 @@ async function serve(options = {}) {
   await sessions.init();
   const presence = new PresenceTracker();
   const hub = new WsHub();
-  const { app, injectWebSocket } = createApp({ sessions, presence, hub, webDist, injectDist });
+  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);
@@ -1622,12 +1857,21 @@ async function serve(options = {}) {
     await pid.release();
   };
   stopWatchdog = startIdleWatchdog({
-    idleMs: options.idleMs ?? DEFAULT_IDLE_MS,
+    idleMs: options.idleMs ?? parseIdleMs(process.env.CHAMBA_IDLE_MS) ?? DEFAULT_IDLE_MS,
     isBusy: () => hub.hasClients() || presence.hasActivePolls(),
-    onIdle: () => void close()
+    // `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 = () => {