chamba 0.1.0 → 0.3.0

package/dist/cli.js

@@ -1,97 +1,106 @@
 #!/usr/bin/env node
 
 // packages/cli/src/index.ts
-import { pathToFileURL as pathToFileURL2 } from "node:url";
+import { realpathSync as realpathSync2 } from "node:fs";
+import { fileURLToPath as fileURLToPath6 } from "node:url";
 
 // packages/server/src/index.ts
 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";
@@ -134,6 +143,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()
@@ -166,7 +178,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(),
@@ -192,7 +205,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
@@ -224,6 +240,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
@@ -234,36 +254,176 @@ var wsServerMessageSchema = z9.discriminatedUnion("t", [
 import { createNodeWebSocket } from "@hono/node-ws";
 import { Hono } from "hono";
 
+// packages/server/src/inject.ts
+import { existsSync } from "node:fs";
+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;
+}
+
 // packages/server/src/render.ts
 import { marked } from "marked";
 
+// packages/server/src/static.ts
+import { existsSync as existsSync2 } from "node:fs";
+import path2 from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+function resolveWebDist() {
+  const here = path2.dirname(fileURLToPath2(import.meta.url));
+  const dev = path2.resolve(here, "../../web/dist");
+  const packaged = path2.resolve(here, "../web");
+  return [dev, packaged].find((dir) => existsSync2(path2.join(dir, "index.html"))) ?? dev;
+}
+
+// packages/server/src/app.ts
+var MAX_UPLOAD_BYTES = 25 * 1024 * 1024;
+
+// packages/server/src/lifecycle.ts
+import { open, readFile as readFile2, rm } from "node:fs/promises";
+
 // packages/server/src/sessions/paths.ts
-import path from "node:path";
-function resolveHome() {
-  const override = process.env.CHAMBA_DIR;
-  return override && override.length > 0 ? path.resolve(override) : path.join(process.cwd(), ".chamba");
+import { existsSync as existsSync3, realpathSync } from "node:fs";
+import { appendFile, mkdir, readFile } from "node:fs/promises";
+import path3 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 = path3.resolve(ctx.cwd);
+  while (true) {
+    if (existsSync3(path3.join(cursor, ".chamba"))) return canonicalize(path3.join(cursor, ".chamba"));
+    if (!root) break;
+    if (cursor === root) break;
+    const parent = path3.dirname(cursor);
+    if (parent === cursor) break;
+    cursor = parent;
+  }
+  return null;
+}
+function plannedHome(ctx = defaultContext()) {
+  const root = gitRoot(ctx.cwd) ?? path3.resolve(ctx.cwd);
+  return canonicalize(path3.join(root, ".chamba"));
+}
+function gitRoot(cwd) {
+  let cursor = path3.resolve(cwd);
+  while (true) {
+    if (existsSync3(path3.join(cursor, ".git"))) return cursor;
+    const parent = path3.dirname(cursor);
+    if (parent === cursor) return null;
+    cursor = parent;
+  }
+}
+function enclosingChamba(cwd) {
+  const parts = path3.resolve(cwd).split(path3.sep);
+  const index = parts.lastIndexOf(".chamba");
+  if (index < 0) return null;
+  return parts.slice(0, index + 1).join(path3.sep) || path3.sep;
+}
+function canonicalize(p) {
+  const resolved = path3.resolve(p);
+  let existing = resolved;
+  const tail = [];
+  while (!existsSync3(existing)) {
+    tail.unshift(path3.basename(existing));
+    const parent = path3.dirname(existing);
+    if (parent === existing) return resolved;
+    existing = parent;
+  }
+  return path3.join(realpathSync(existing), ...tail);
 }
 function sessionsDir(home) {
-  return path.join(home, "sessions");
+  return path3.join(home, "sessions");
 }
 function sessionDir(home, id) {
-  return path.join(sessionsDir(home), id);
+  return path3.join(sessionsDir(home), id);
 }
 function metaPath(home, id) {
-  return path.join(sessionDir(home, id), "meta.json");
+  return path3.join(sessionDir(home, id), "meta.json");
+}
+function pidfilePath(home) {
+  return path3.join(home, "server.json");
 }
 function agentStatePath(home) {
-  return path.join(home, "agent-state.json");
+  return path3.join(home, "agent-state.json");
+}
+async function ensureChambaHome(home) {
+  await mkdir(sessionsDir(home), { recursive: true });
+  await ensureGitignored(home);
+}
+async function ensureGitignored(home) {
+  if (path3.basename(home) !== ".chamba") return;
+  const gitignore = path3.join(path3.dirname(home), ".gitignore");
+  const entry = ".chamba/";
+  try {
+    let content = "";
+    try {
+      content = await readFile(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
+function readServerInfo(home) {
+  return readPidfile(pidfilePath(home));
+}
+async function readPidfile(file) {
+  try {
+    const raw = await readFile2(file, "utf8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.pid === "number" && typeof parsed.port === "number") return parsed;
+    return null;
+  } catch {
+    return null;
+  }
 }
 
 // packages/server/src/port.ts
 var DEFAULT_PORT = 4319;
-function resolvePort(argv = process.argv.slice(2)) {
+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 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++) {
@@ -275,38 +435,38 @@ 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;
 }
 
 // packages/server/src/version.ts
-import { existsSync, readFileSync } from "node:fs";
-import path2 from "node:path";
-import { fileURLToPath } from "node:url";
+import { existsSync as existsSync4, readFileSync } from "node:fs";
+import path4 from "node:path";
+import { fileURLToPath as fileURLToPath3 } from "node:url";
 function chambaVersion() {
-  let dir = path2.dirname(fileURLToPath(import.meta.url));
+  let dir = path4.dirname(fileURLToPath3(import.meta.url));
   for (; ; ) {
-    const manifest = path2.join(dir, "package.json");
-    if (existsSync(manifest)) {
+    const manifest = path4.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 = path2.dirname(dir);
+    const parent = path4.dirname(dir);
     if (parent === dir) return "0.0.0-dev";
     dir = parent;
   }
 }
 
 // packages/server/src/sessions/meta.ts
-import { readdir, readFile, rename, writeFile } from "node:fs/promises";
+import { readdir, readFile as readFile3, rename, rm as rm2, writeFile } from "node:fs/promises";
 async function readMeta(home, id) {
   try {
-    const raw = await readFile(metaPath(home, id), "utf8");
+    const raw = await readFile3(metaPath(home, id), "utf8");
     return sessionMetaSchema.parse(JSON.parse(raw));
   } catch (err) {
     if (err.code === "ENOENT") return null;
@@ -354,8 +514,8 @@ function parseArgs(argv) {
 }
 
 // packages/cli/src/client.ts
-import { readFile as readFile2 } from "node:fs/promises";
-import path3 from "node:path";
+import { readFile as readFile4 } from "node:fs/promises";
+import path5 from "node:path";
 var ChannelError = class extends Error {
   constructor(status2, message) {
     super(message);
@@ -449,9 +609,9 @@ var Client = class {
    * bytes into the session directory rather than smuggling them through JSON.
    */
   async uploadAttachment(id, filePath) {
-    const bytes = await readFile2(filePath);
+    const bytes = await readFile4(filePath);
     const form = new FormData();
-    form.append("file", new Blob([bytes]), path3.basename(filePath));
+    form.append("file", new Blob([bytes]), path5.basename(filePath));
     const res = await this.json(
       `/api/sessions/${encodeURIComponent(id)}/attachments`,
       { method: "POST", body: form, timeoutMs: 3e4 },
@@ -494,17 +654,17 @@ var Client = class {
     );
     return res.session;
   }
-  async json(path9, options, schema) {
-    const res = await this.fetch(path9, options);
+  async json(path12, options, schema) {
+    const res = await this.fetch(path12, options);
     if (!res.ok) throw await toError(res);
     return schema.parse(await res.json());
   }
-  async fetch(path9, options) {
+  async fetch(path12, options) {
     const { method = "GET", body, timeoutMs } = options;
     const controller = timeoutMs !== void 0 ? new AbortController() : void 0;
     const timer = controller && timeoutMs !== void 0 ? setTimeout(() => controller.abort(), timeoutMs) : void 0;
     try {
-      return await fetch(new URL(path9, this.baseUrl), {
+      return await fetch(new URL(path12, this.baseUrl), {
         method,
         signal: controller?.signal,
         ...bodyInit(body)
@@ -530,7 +690,7 @@ async function toError(res) {
 }
 
 // packages/cli/src/output.ts
-import path4 from "node:path";
+import path6 from "node:path";
 import { z as z10 } from "zod";
 function out(message) {
   process.stdout.write(`${message}
@@ -554,8 +714,25 @@ function eventAttachments(event) {
   const parsed = z10.array(attachmentSchema).safeParse(event.payload.attachments);
   return parsed.success ? parsed.data : [];
 }
+function formatSystemEvent(event) {
+  const parsed = systemPayloadSchema.safeParse(event.payload);
+  if (!parsed.success) return `\xB7 ${eventText(event)}`;
+  const { reason, to, kind } = parsed.data;
+  switch (reason) {
+    case "user-moved-away":
+      return to ? `\xB7 You moved to another session (${to})` : "\xB7 The user moved away";
+    case "session-ended":
+      return "\xB7 Session ended";
+    case "session-created":
+      return "\xB7 Session created";
+    case "kind-chosen":
+      return kind ? `\xB7 Session set to ${kind}` : "\xB7 Session kind chosen";
+    default:
+      return `\xB7 ${reason}`;
+  }
+}
 function formatEvent(event) {
-  if (event.source === "system") return `\xB7 ${eventText(event)}`;
+  if (event.source === "system") return formatSystemEvent(event);
   const who = event.source === "user" ? "you" : "agent";
   const text = eventText(event);
   return text ? `${who}: ${text}` : `${who}:`;
@@ -582,7 +759,7 @@ function formatAnnotationBatch(event, home) {
       lines.push(`     component: ${target.component.name}${at}`);
     }
     if (item.screenshot) {
-      const abs = path4.join(sessionDir(home, event.sessionId), item.screenshot.relPath);
+      const abs = path6.join(sessionDir(home, event.sessionId), item.screenshot.relPath);
       lines.push(`     [shot] ${item.screenshot.name} -> ${abs}`);
     }
   });
@@ -614,7 +791,7 @@ function formatArtifact(event, home) {
   );
   if (!parsed.success) return formatEvent(event);
   const ref = parsed.data;
-  const abs = path4.join(sessionDir(home, event.sessionId), ref.relPath);
+  const abs = path6.join(sessionDir(home, event.sessionId), ref.relPath);
   return `agent [artifact ${ref.kind} "${ref.name}"] -> ${abs}`;
 }
 function printEvents(events, home) {
@@ -637,7 +814,7 @@ function printEvents(events, home) {
     }
     out(formatEvent(event));
     for (const att of eventAttachments(event)) {
-      out(`  [file] ${att.name} -> ${path4.join(sessionDir(home, event.sessionId), att.relPath)}`);
+      out(`  [file] ${att.name} -> ${path6.join(sessionDir(home, event.sessionId), att.relPath)}`);
     }
   }
 }
@@ -645,15 +822,16 @@ function formatSession(meta, presence, current) {
   const marker = current ? "*" : " ";
   const title = meta.title ? ` "${meta.title}"` : "";
   const live = presence ? ` ${presence}` : "";
-  return `${marker} ${meta.id}  ${meta.status}${live}  ${meta.kind}${title}`;
+  return `${marker} ${meta.id}  ${meta.status}${live}  ${meta.kind ?? "unset"}${title}`;
 }
 
 // packages/cli/src/commands/artifact.ts
-import { readFile as readFile4 } from "node:fs/promises";
+import { readFile as readFile6 } from "node:fs/promises";
 
 // packages/cli/src/state.ts
-import { mkdir, readFile as readFile3, rename as rename2, writeFile as writeFile2 } from "node:fs/promises";
-import path5 from "node:path";
+import { randomUUID } from "node:crypto";
+import { mkdir as mkdir2, readFile as readFile5, rename as rename2, rm as rm3, writeFile as writeFile2 } from "node:fs/promises";
+import path7 from "node:path";
 import { z as z11 } from "zod";
 var agentStateSchema = z11.object({
   currentSessionId: z11.string().optional(),
@@ -661,7 +839,7 @@ var agentStateSchema = z11.object({
 });
 async function readState(home = resolveHome()) {
   try {
-    const raw = await readFile3(agentStatePath(home), "utf8");
+    const raw = await readFile5(agentStatePath(home), "utf8");
     return agentStateSchema.parse(JSON.parse(raw));
   } catch {
     return { cursors: {} };
@@ -669,11 +847,16 @@ async function readState(home = resolveHome()) {
 }
 async function writeState(state, home = resolveHome()) {
   const file = agentStatePath(home);
-  await mkdir(path5.dirname(file), { recursive: true });
-  const tmp = `${file}.tmp`;
-  await writeFile2(tmp, `${JSON.stringify(state, null, 2)}
+  await mkdir2(path7.dirname(file), { recursive: true });
+  const tmp = `${file}.${randomUUID()}.tmp`;
+  try {
+    await writeFile2(tmp, `${JSON.stringify(state, null, 2)}
 `, "utf8");
-  await rename2(tmp, file);
+    await rename2(tmp, file);
+  } catch (err) {
+    await rm3(tmp, { force: true }).catch(() => void 0);
+    throw err;
+  }
 }
 function cursorFor(state, id) {
   return state.cursors[id] ?? 0;
@@ -690,7 +873,11 @@ var UsageError = class extends Error {
   }
 };
 async function resolveSessionId(ctx) {
-  if (ctx.flags.session) return ctx.flags.session;
+  const flag = ctx.flags.session;
+  if (flag === "true" || flag === "") {
+    throw new UsageError("`--session` needs a session id, e.g. --session <id>");
+  }
+  if (flag) return flag;
   const state = await readState(ctx.home);
   if (state.currentSessionId) return state.currentSessionId;
   throw new UsageError("no current session - run `chamba open` or pass --session <id>");
@@ -715,7 +902,7 @@ async function artifact(ctx) {
   if (!file || file === "true") throw new UsageError("chamba artifact needs --file <path>");
   let content;
   try {
-    content = await readFile4(file, "utf8");
+    content = await readFile6(file, "utf8");
   } catch (err) {
     throw new UsageError(`could not read ${file}: ${err.message}`);
   }
@@ -733,8 +920,8 @@ async function artifact(ctx) {
 }
 
 // packages/cli/src/commands/ask.ts
-import { randomUUID } from "node:crypto";
-import { readFile as readFile5 } from "node:fs/promises";
+import { randomUUID as randomUUID2 } from "node:crypto";
+import { readFile as readFile7 } from "node:fs/promises";
 async function ask(ctx) {
   const source = await readCardSource(ctx);
   let parsed;
@@ -744,7 +931,7 @@ async function ask(ctx) {
     throw new UsageError(`--json is not valid JSON: ${err.message}`);
   }
   if (parsed && typeof parsed === "object" && !Array.isArray(parsed) && !("cardId" in parsed)) {
-    parsed.cardId = randomUUID();
+    parsed.cardId = randomUUID2();
   }
   const result = postQuestionCardReqSchema.safeParse(parsed);
   if (!result.success) {
@@ -762,7 +949,7 @@ async function readCardSource(ctx) {
   const file = ctx.positionals[0];
   if (file) {
     try {
-      return await readFile5(file, "utf8");
+      return await readFile7(file, "utf8");
     } catch (err) {
       throw new UsageError(`could not read card file ${file}: ${err.message}`);
     }
@@ -774,7 +961,8 @@ async function readCardSource(ctx) {
 
 // packages/cli/src/commands/attach.ts
 async function attach(ctx) {
-  const id = ctx.positionals[0] ?? ctx.flags.session;
+  const flagId = ctx.flags.session === "true" ? void 0 : ctx.flags.session || void 0;
+  const id = ctx.positionals[0] ?? flagId;
   if (!id) throw new UsageError("usage: chamba attach <session-id>");
   const tail = intFlag(ctx.flags.tail, 20);
   const digest = await ctx.client.attach(id, tail);
@@ -819,8 +1007,8 @@ async function end(ctx) {
 }
 
 // packages/cli/src/commands/export.ts
-import { copyFile, mkdir as mkdir2, readFile as readFile6, writeFile as writeFile3 } from "node:fs/promises";
-import path6 from "node:path";
+import { copyFile, mkdir as mkdir3, readFile as readFile8, rm as rm4, writeFile as writeFile3 } from "node:fs/promises";
+import path8 from "node:path";
 async function exportCmd(ctx) {
   const dest = ctx.positionals[0];
   if (!dest) throw new UsageError("usage: chamba export <dest> [--session <id>]");
@@ -829,12 +1017,12 @@ async function exportCmd(ctx) {
   const summary = await assemblePackage({
     events,
     sessionDir: sessionDir(ctx.home, id),
-    dest: path6.resolve(dest)
+    dest: path8.resolve(dest)
   });
   note(
-    `exported ${id} -> ${path6.resolve(dest)} (spec.md${summary.hasDraft ? "" : " placeholder"}, ${summary.assets.length} asset${summary.assets.length === 1 ? "" : "s"}, ${summary.decisions} decision${summary.decisions === 1 ? "" : "s"})`
+    `exported ${id} -> ${path8.resolve(dest)} (spec.md${summary.hasDraft ? "" : " placeholder"}, ${summary.assets.length} asset${summary.assets.length === 1 ? "" : "s"}, ${summary.decisions} decision${summary.decisions === 1 ? "" : "s"})`
   );
-  out(path6.resolve(dest));
+  out(path8.resolve(dest));
   return 0;
 }
 async function assemblePackage(input) {
@@ -855,32 +1043,33 @@ async function assemblePackage(input) {
       if (parsed.success) decisions.push(parsed.data);
     }
   }
-  await mkdir2(input.dest, { recursive: true });
-  const assetsDir = path6.join(input.dest, "assets");
+  await mkdir3(input.dest, { recursive: true });
+  const assetsDir = path8.join(input.dest, "assets");
+  await rm4(assetsDir, { recursive: true, force: true });
   const draftBody = canonicalDraft ? await readArtifact(input.sessionDir, canonicalDraft) : void 0;
   await writeFile3(
-    path6.join(input.dest, "spec.md"),
+    path8.join(input.dest, "spec.md"),
     draftBody ?? "# Spec\n\n_No draft was authored in this session._\n",
     "utf8"
   );
   const assets = [];
   for (const ref of artifacts.values()) {
     if (ref === canonicalDraft) continue;
-    const src = path6.join(input.sessionDir, ref.relPath);
-    const base = path6.basename(ref.relPath);
+    const src = path8.join(input.sessionDir, ref.relPath);
+    const base = path8.basename(ref.relPath);
     try {
-      await mkdir2(assetsDir, { recursive: true });
-      await copyFile(src, path6.join(assetsDir, base));
+      await mkdir3(assetsDir, { recursive: true });
+      await copyFile(src, path8.join(assetsDir, base));
       assets.push(base);
     } catch {
     }
   }
-  await writeFile3(path6.join(input.dest, "decisions.md"), renderDecisions(decisions), "utf8");
+  await writeFile3(path8.join(input.dest, "decisions.md"), renderDecisions(decisions), "utf8");
   return { hasDraft: Boolean(draftBody), assets, decisions: decisions.length };
 }
 async function readArtifact(dir, ref) {
   try {
-    return await readFile6(path6.join(dir, ref.relPath), "utf8");
+    return await readFile8(path8.join(dir, ref.relPath), "utf8");
   } catch {
     return void 0;
   }
@@ -908,22 +1097,31 @@ var USAGE = `chamba - a browser companion for your terminal agent
 
 Usage:
   chamba                     list sessions and show which is current
+  chamba init [dir]          create the .chamba workspace (at the git root, or
+             [--here]        <dir>, or the current dir with --here); prints its
+                             location and per-project port
   chamba open [--kind K]     start a session (K: everyday | spec), print its URL
-             [--title T]
-  chamba poll [--wait ms]    block for the next human/system events; a batch may
-                             include "user moved away" (hand off with attach) or
-                             "session ended" (stop polling, resume terminal work)
+             [--title T]     (creates the workspace at the repo root if none yet)
+  chamba poll                wait for the next human/system events, blocking across
+             [--wait ms]     quiet windows on its own until a batch arrives (it may
+             [--for ms]      include "user moved away" -> attach, or "session ended"
+             [--once]        -> stop). After a quiet stretch (--for, default 4m) it
+                             prints a heartbeat and exits 0 - just re-run. --once does
+                             one bounded check instead (scripts/tests); --wait is the
+                             per-request window (max 30s)
   chamba reply <text>        send a line from the agent into the session
              [--file a,b]    attach files by path (comma-separated); --image is
              [--image a,b]   an alias. text is optional when files are attached
   chamba attach <id>         load a session's recent tail and make it current
              [--tail N]
   chamba end                 end the current session
+  chamba stop                stop this project's server (it otherwise self-stops
+                             after an idle spell); the next open starts a fresh one
 
 Spec sessions (open with --kind spec):
   chamba ask --json '{...}'  post a question card (question + 2-6 options with
              | <file.json>   descriptions, optional "recommended"); a cardId is
-                             minted for you. The answer returns as a message
+                             created for you. The answer returns as a message
   chamba decision            record a decision: --status confirmed|assumed
              --status S        --summary "..." [--detail "..."]
              --summary T
@@ -941,45 +1139,133 @@ Spec sessions (open with --kind spec):
 
 Global:
   --session <id>             act on a specific session instead of the current one
-  --port <n>                 server port (default: CHAMBA_PORT or 4319)`;
+  --port <n>                 server port (default: CHAMBA_PORT, else a per-project
+                             port derived from the workspace location)`;
 function help(_ctx) {
   note(USAGE);
   return Promise.resolve(0);
 }
 
+// packages/cli/src/commands/init.ts
+import path9 from "node:path";
+async function init(ctx) {
+  const target = resolveTarget(ctx);
+  const existing = findExistingHome({ cwd: target, env: {} });
+  if (existing && !ctx.flags.here) {
+    report("chamba workspace already exists", existing);
+    return 0;
+  }
+  if (existing && ctx.flags.here) {
+    note(`note: shadowing an existing workspace at ${existing}`);
+  }
+  await ensureChambaHome(path9.join(target, ".chamba"));
+  const home = findExistingHome({ cwd: target, env: {} }) ?? path9.join(target, ".chamba");
+  report("created chamba workspace", home);
+  if (path9.basename(home) !== ".chamba") {
+    note("warning: home is not a .chamba directory, so it will not be auto-gitignored");
+  }
+  return 0;
+}
+function resolveTarget(ctx) {
+  const explicit = ctx.positionals[0];
+  if (explicit) return path9.resolve(explicit);
+  const root = gitRoot(process.cwd());
+  if (root) return root;
+  if (ctx.flags.here) return path9.resolve(process.cwd());
+  throw new UsageError(
+    "no .git found here - pass a directory (`chamba init <dir>`) or `chamba init --here` to choose where .chamba lives"
+  );
+}
+function report(headline, home) {
+  note(headline);
+  note(`home: ${home}  port: ${derivePort(home)}`);
+  note("each project gets its own server on its own port; other projects are unaffected");
+}
+
 // packages/cli/src/launch.ts
-import { spawn } from "node:child_process";
-import { existsSync as existsSync2 } from "node:fs";
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync as existsSync5 } from "node:fs";
 import { createRequire } from "node:module";
-import path7 from "node:path";
-import { fileURLToPath as fileURLToPath2, pathToFileURL } from "node:url";
+import path10 from "node:path";
+import { fileURLToPath as fileURLToPath4, pathToFileURL } from "node:url";
 var require2 = createRequire(import.meta.url);
-async function ensureServer(client) {
-  if (await client.isUp()) return { spawned: false };
-  spawnServer();
-  await waitUntilUp(client);
+async function ensureServer(client, target) {
+  if (await client.isUp()) {
+    await verifyHome(client, target);
+    return { spawned: false };
+  }
+  ensureDevBuilds();
+  spawnServer(target);
+  await waitUntilUp(client, target);
   return { spawned: true };
 }
-function spawnServer() {
+async function verifyHome(client, target) {
+  const health = await client.health();
+  if (health.home === target.home) return;
+  if (health.home === void 0) {
+    throw new Error(
+      `a chamba server already owns port ${target.port} but predates workspace isolation - stop that process and retry`
+    );
+  }
+  throw new Error(
+    `port ${target.port} is serving a different chamba workspace (${health.home}); run from that project, or set --port / CHAMBA_PORT to run a separate server`
+  );
+}
+function spawnServer(target) {
   const child = spawn(process.execPath, serverLaunchArgs(), {
     detached: true,
     stdio: "ignore",
-    env: process.env
+    env: { ...process.env, CHAMBA_DIR: target.home, CHAMBA_PORT: String(target.port) }
   });
   child.unref();
 }
 function serverLaunchArgs() {
-  const here = path7.dirname(fileURLToPath2(import.meta.url));
-  const packagedServer = path7.join(here, "server.js");
-  if (existsSync2(packagedServer)) return [packagedServer];
+  const here = path10.dirname(fileURLToPath4(import.meta.url));
+  const packagedServer = path10.join(here, "server.js");
+  if (existsSync5(packagedServer)) return [packagedServer];
   const serverBin = require2.resolve("@chamba/server/bin");
   const tsxLoader = pathToFileURL(require2.resolve("tsx")).href;
   return ["--import", tsxLoader, serverBin];
 }
-async function waitUntilUp(client, timeoutMs = 1e4) {
+function ensureDevBuilds() {
+  const here = path10.dirname(fileURLToPath4(import.meta.url));
+  if (existsSync5(path10.join(here, "server.js"))) return;
+  const repoRoot = path10.resolve(path10.dirname(require2.resolve("@chamba/server/bin")), "../../..");
+  const deps = [
+    { label: "web UI", filter: "@chamba/web", dist: resolveWebDist(), marker: "index.html" },
+    {
+      label: "annotation client",
+      filter: "@chamba/inject",
+      dist: resolveInjectDist(),
+      marker: "annotate.js"
+    }
+  ];
+  for (const dep of deps) {
+    if (existsSync5(path10.join(dep.dist, dep.marker))) continue;
+    note(`building chamba ${dep.label} (first run in this environment)...`);
+    const result = spawnSync("pnpm", ["--filter", dep.filter, "build"], {
+      cwd: repoRoot,
+      encoding: "utf8"
+    });
+    if (result.error || result.status !== 0) {
+      const detail = `${result.stderr ?? ""}${result.stdout ?? ""}`.trim();
+      throw new Error(
+        `could not build ${dep.filter} (needed to serve the ${dep.label})${detail ? `:
+${detail}` : ""}`
+      );
+    }
+  }
+}
+async function waitUntilUp(client, target, timeoutMs = 1e4) {
   const deadline = Date.now() + timeoutMs;
   while (Date.now() < deadline) {
-    if (await client.isUp()) return;
+    if (await client.isUp()) {
+      const health = await client.health();
+      if (health.home === target.home) return;
+      throw new Error(
+        `port ${target.port} was taken by a different chamba workspace (${health.home ?? "unknown"})`
+      );
+    }
     await delay(150);
   }
   throw new Error("server did not become healthy in time");
@@ -989,9 +1275,19 @@ function delay(ms) {
 }
 
 // packages/cli/src/commands/open.ts
-async function open(ctx) {
-  const { spawned } = await ensureServer(ctx.client);
-  if (spawned) note("started chamba server");
+async function open2(ctx) {
+  if (!ctx.workspaceExists) {
+    if (!gitRoot(process.cwd())) {
+      throw new UsageError(
+        "no chamba workspace, and no .git here to anchor one - run `chamba init <dir>` or `chamba init --here` to choose where .chamba lives"
+      );
+    }
+    await ensureChambaHome(ctx.home);
+    note(`created chamba workspace at ${ctx.home}`);
+  }
+  note(`home: ${ctx.home}  port: ${ctx.port}`);
+  const { spawned } = await ensureServer(ctx.client, { home: ctx.home, port: ctx.port });
+  if (spawned) note(`started chamba server on :${ctx.port}`);
   const req = {
     ...ctx.flags.kind ? { kind: parseKind(ctx.flags.kind) } : {},
     ...ctx.flags.title ? { title: ctx.flags.title } : {}
@@ -1002,7 +1298,17 @@ async function open(ctx) {
   const state = await readState(ctx.home);
   await writeState(withSession(state, id, digest.cursor), ctx.home);
   out(`http://localhost:${ctx.port}/?s=${id}`);
+  note("  in a container? if this link is unreachable from your host:");
+  note(
+    `  - the server bound ${resolveBindHost([])}; set CHAMBA_HOST=0.0.0.0 so the host can reach it`
+  );
+  note(`  - forward port ${ctx.port} to the host (1:1); pin it with CHAMBA_PORT to keep it stable`);
   note(`session ${id} - open the URL, then run \`chamba poll\` to wait for messages`);
+  if (!ctx.flags.kind) {
+    note(
+      "  no --kind given: the human picks spec or everyday in the browser; your next poll reports it as `\xB7 Session set to ...`"
+    );
+  }
   return 0;
 }
 function parseKind(value) {
@@ -1012,9 +1318,45 @@ function parseKind(value) {
 }
 
 // packages/cli/src/commands/poll.ts
-async function poll(ctx) {
+var DEFAULT_WAIT_MS = 25e3;
+var MAX_WAIT_MS = 3e4;
+var DEFAULT_FOLLOW_MS = 4 * 6e4;
+var BACKOFF_START_MS = 500;
+var BACKOFF_MAX_MS = 5e3;
+var IDLE_GUARD_MS = 1e3;
+var realClock = {
+  now: () => Date.now(),
+  sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+};
+async function poll(ctx, clock = realClock) {
   const id = await resolveSessionId(ctx);
-  const wait = Math.min(intFlag(ctx.flags.wait, 25e3), 3e4);
+  const wait = Math.min(intFlag(ctx.flags.wait, DEFAULT_WAIT_MS), MAX_WAIT_MS);
+  if (ctx.flags.once !== void 0) return pollOnce(ctx, id, wait);
+  const followMs = intFlag(ctx.flags.for, DEFAULT_FOLLOW_MS);
+  return follow(
+    {
+      now: clock.now,
+      sleep: clock.sleep,
+      cursor: async () => cursorFor(await readState(ctx.home), id),
+      poll: (since) => ctx.client.poll(id, since, wait),
+      deliver: async (res) => {
+        printEvents(res.events, ctx.home);
+        await writeState(withSession(await readState(ctx.home), id, res.cursor), ctx.home);
+      },
+      onError: (err, giveUp) => note(pollErrorMessage(err, giveUp)),
+      onHeartbeat: () => note("still listening - re-run chamba poll to keep waiting"),
+      onEnded: () => note("session has ended - nothing more to wait for"),
+      isFatal
+    },
+    // The park floor never drops below the guard sleep, so a small (or zero) `--wait`
+    // - which makes the server answer empty at once - cannot spin the loop hot.
+    {
+      deadline: clock.now() + followMs,
+      parkFloorMs: Math.max(IDLE_GUARD_MS, Math.floor(wait / 2))
+    }
+  );
+}
+async function pollOnce(ctx, id, wait) {
   const state = await readState(ctx.home);
   const since = cursorFor(state, id);
   const res = await ctx.client.poll(id, since, wait);
@@ -1026,8 +1368,53 @@ async function poll(ctx) {
   await writeState(withSession(state, id, res.cursor), ctx.home);
   return 0;
 }
+async function follow(io, cfg) {
+  let backoff = BACKOFF_START_MS;
+  while (true) {
+    const since = await io.cursor();
+    const start = io.now();
+    let res;
+    try {
+      res = await io.poll(since);
+    } catch (err) {
+      const giveUp = io.isFatal(err) || io.now() >= cfg.deadline;
+      io.onError(err, giveUp);
+      if (giveUp) return 1;
+      await io.sleep(backoff);
+      backoff = Math.min(backoff * 2, BACKOFF_MAX_MS);
+      continue;
+    }
+    backoff = BACKOFF_START_MS;
+    if (res.events.length > 0) {
+      await io.deliver(res);
+      return 0;
+    }
+    if (res.ended) {
+      io.onEnded?.();
+      return 0;
+    }
+    if (io.now() >= cfg.deadline) {
+      io.onHeartbeat();
+      return 0;
+    }
+    if (io.now() - start < cfg.parkFloorMs) await io.sleep(IDLE_GUARD_MS);
+  }
+}
+function isFatal(err) {
+  if (err instanceof ChannelError) return err.status === 404;
+  if (err instanceof SyntaxError) return true;
+  return err instanceof Error && err.name === "ZodError";
+}
+function pollErrorMessage(err, giveUp) {
+  if (err instanceof ChannelError && err.status === 404) {
+    return "session not found - it may have been removed";
+  }
+  const detail = err instanceof Error ? err.message : String(err);
+  return giveUp ? `poll failed: ${detail}` : `poll failed, retrying: ${detail}`;
+}
 
 // packages/cli/src/commands/reply.ts
+import { stat } from "node:fs/promises";
 async function reply(ctx) {
   const text = ctx.positionals.join(" ").trim();
   const files = filePaths(ctx.flags);
@@ -1035,6 +1422,15 @@ async function reply(ctx) {
     throw new UsageError("usage: chamba reply <text> [--file a,b] [--image a,b]");
   }
   const id = await resolveSessionId(ctx);
+  for (const file of files) {
+    try {
+      const info = await stat(file);
+      if (!info.isFile()) throw new UsageError(`not a file: ${file}`);
+    } catch (err) {
+      if (err instanceof UsageError) throw err;
+      throw new UsageError(`file not found: ${file}`);
+    }
+  }
   const attachmentIds = [];
   for (const file of files) {
     const attachment = await ctx.client.uploadAttachment(id, file);
@@ -1053,10 +1449,10 @@ function filePaths(flags) {
 }
 
 // packages/cli/src/commands/skill.ts
-import { cpSync, existsSync as existsSync3 } from "node:fs";
+import { cpSync, existsSync as existsSync6, rmSync } from "node:fs";
 import { homedir } from "node:os";
-import path8 from "node:path";
-import { fileURLToPath as fileURLToPath3 } from "node:url";
+import path11 from "node:path";
+import { fileURLToPath as fileURLToPath5 } from "node:url";
 async function skill(ctx) {
   if (ctx.positionals[0] !== "install") {
     throw new UsageError("usage: chamba skill install [--global]");
@@ -1067,28 +1463,36 @@ async function skill(ctx) {
     return 1;
   }
   const base = ctx.flags.global ? homedir() : process.cwd();
-  const target = path8.join(base, ".claude", "skills", "chamba");
+  const target = path11.join(base, ".claude", "skills", "chamba");
+  rmSync(target, { recursive: true, force: true });
   cpSync(source, target, { recursive: true });
   note(`installed the chamba skill to ${target}`);
   note("reload your agent's skills, then use /chamba");
   return 0;
 }
 function resolveSkillSource() {
-  const here = path8.dirname(fileURLToPath3(import.meta.url));
+  const here = path11.dirname(fileURLToPath5(import.meta.url));
   const candidates = [
-    path8.resolve(here, "../skill"),
+    path11.resolve(here, "../skill"),
     // packaged: dist/cli.js -> <pkg>/skill
-    path8.resolve(here, "../../../../skill")
+    path11.resolve(here, "../../../../skill")
     // dev: packages/cli/src/commands -> <repo>/skill
   ];
-  return candidates.find((dir) => existsSync3(path8.join(dir, "SKILL.md"))) ?? null;
+  return candidates.find((dir) => existsSync6(path11.join(dir, "SKILL.md"))) ?? null;
 }
 
 // packages/cli/src/commands/status.ts
 async function status(ctx) {
+  if (!ctx.workspaceExists) {
+    note(
+      "no chamba workspace here - run `chamba open` to start one (creates .chamba at the repo root), or `chamba init` to choose where"
+    );
+    return 0;
+  }
   const state = await readState(ctx.home);
-  const up = await ctx.client.isUp();
+  const up = await serverOwnsHome(ctx);
   const rows = up ? await rowsFromServer(ctx) : await rowsFromDisk(ctx);
+  note(`home: ${ctx.home}`);
   if (rows.length === 0) {
     note("no sessions yet - run `chamba open` to start one");
     return 0;
@@ -1099,6 +1503,14 @@ async function status(ctx) {
   }
   return 0;
 }
+async function serverOwnsHome(ctx) {
+  if (!await ctx.client.isUp()) return false;
+  try {
+    return (await ctx.client.health()).home === ctx.home;
+  } catch {
+    return false;
+  }
+}
 async function rowsFromServer(ctx) {
   const summaries = await ctx.client.list();
   return summaries.map((s) => ({ meta: s.meta, presence: s.presence }));
@@ -1109,14 +1521,61 @@ async function rowsFromDisk(ctx) {
   return metas.filter((meta) => meta !== null).sort((a, b) => b.updatedAt.localeCompare(a.updatedAt)).map((meta) => ({ meta }));
 }
 
+// packages/cli/src/commands/stop.ts
+async function stop(ctx) {
+  const info = await readServerInfo(ctx.home);
+  if (!info) {
+    note("no chamba server running here");
+    return 0;
+  }
+  const client = new Client(`http://127.0.0.1:${info.port}/`);
+  if (!await ownsHome(client, ctx.home)) {
+    note("no chamba server running here");
+    return 0;
+  }
+  try {
+    process.kill(info.pid, "SIGTERM");
+  } catch {
+    note("no chamba server running here");
+    return 0;
+  }
+  if (await waitUntilDown(client)) {
+    note(`stopped chamba server on :${info.port}`);
+    return 0;
+  }
+  note(`sent stop to the chamba server (pid ${info.pid}) but it did not exit in time`);
+  return 1;
+}
+async function ownsHome(client, home) {
+  if (!await client.isUp()) return false;
+  try {
+    return (await client.health()).home === home;
+  } catch {
+    return false;
+  }
+}
+async function waitUntilDown(client, timeoutMs = 5e3) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!await client.isUp()) return true;
+    await delay2(150);
+  }
+  return false;
+}
+function delay2(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
 // packages/cli/src/commands/index.ts
 var COMMANDS = {
-  open,
+  init,
+  open: open2,
   poll,
   reply,
   end,
   attach,
   status,
+  stop,
   // Spec sessions: structured interview + live artifacts + export.
   ask,
   decision,
@@ -1137,21 +1596,40 @@ function runCommand(name, ctx) {
 }
 
 // packages/cli/src/index.ts
+var REQUIRES_WORKSPACE = /* @__PURE__ */ new Set([
+  "poll",
+  "reply",
+  "end",
+  "attach",
+  "ask",
+  "decision",
+  "artifact",
+  "export"
+]);
 async function main(argv = process.argv.slice(2)) {
-  const port = resolvePort(argv);
   const { positionals, flags } = parseArgs(argv);
   if (flags.version && positionals.length === 0) {
     out(chambaVersion());
     return 0;
   }
   const command = positionals[0] ?? (flags.help ? "help" : "status");
+  const existing = findExistingHome();
+  const home = existing ?? plannedHome();
+  const port = resolvePort(argv, home);
   const ctx = {
     client: new Client(`http://127.0.0.1:${port}/`),
-    home: resolveHome(),
+    home,
     port,
     flags,
-    positionals: positionals.slice(1)
+    positionals: positionals.slice(1),
+    workspaceExists: existing !== null
   };
+  if (!ctx.workspaceExists && REQUIRES_WORKSPACE.has(command)) {
+    note(
+      "no chamba workspace here - run `chamba open` to start one (creates .chamba at the repo root), or `chamba init` to choose where"
+    );
+    return 2;
+  }
   try {
     return await runCommand(command, ctx);
   } catch (err) {
@@ -1167,16 +1645,39 @@ function reportError(err) {
     note(`error: ${err.message}`);
     return 1;
   }
-  const cause = err.cause;
-  if (cause?.code === "ECONNREFUSED") {
+  if (errorCode(err) === "ECONNREFUSED") {
     note("cannot reach the chamba server - run `chamba open` first");
     return 1;
   }
   note(`error: ${err.message}`);
   return 1;
 }
-var invokedDirectly = process.argv[1] !== void 0 && pathToFileURL2(process.argv[1]).href === import.meta.url;
-if (invokedDirectly) {
+function errorCode(err) {
+  const seen = /* @__PURE__ */ new Set();
+  const queue = [err];
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (!current || typeof current !== "object" || seen.has(current)) continue;
+    seen.add(current);
+    const code = current.code;
+    if (typeof code === "string") return code;
+    const cause = current.cause;
+    if (cause) queue.push(cause);
+    const errors = current.errors;
+    if (Array.isArray(errors)) queue.push(...errors);
+  }
+  return void 0;
+}
+function invokedAsEntry() {
+  const entry = process.argv[1];
+  if (entry === void 0) return false;
+  try {
+    return realpathSync2(entry) === realpathSync2(fileURLToPath6(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+if (invokedAsEntry()) {
   main().then(
     (code) => process.exit(code),
     (err) => {