constella 0.1.0

package/bin/constella.mjs

@@ -0,0 +1,329 @@
+#!/usr/bin/env node
+/**
+ * Constella launcher — installs/boots the local-first runtime, the way `claude` and `codex` do:
+ * everything lives under the user-home runtime root (override with CONSTELLA_HOME).
+ *
+ *   npx constella --onboarding     # force the first-time setup wizard
+ *   npx constella --start          # local mode (auto-login, 127.0.0.1)
+ *   npx constella --auth           # real email + password (127.0.0.1)
+ *   npx constella --vps            # server over Tailscale, in Docker (0.0.0.0)
+ *   npx constella --portable [--path <drive>]   # run from a USB drive (0.0.0.0)
+ *   npx constella update [--check] # detect/apply a new version
+ *
+ * The launch flag picks the run mode (the UI never picks it in a public build). Network modes
+ * (auth/vps/portable) generate + persist a real BETTER_AUTH_SECRET so boot never uses a public key.
+ */
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { mkdirSync, existsSync, readFileSync, writeFileSync, chmodSync, readdirSync } from "node:fs";
+import { spawnSync, spawn, execFileSync } from "node:child_process";
+import { createInterface } from "node:readline";
+import { randomBytes } from "node:crypto";
+import { fileURLToPath } from "node:url";
+
+// Find a dependency's install dir by walking the node_modules chain up from the constella package —
+// so it works whether the dep is nested under constella OR hoisted to the install root (the flat
+// `npm i` layout) OR symlinked (the dev pnpm tree). `require.resolve` is NOT used: a package's
+// `exports` map can hide deep subpaths (drizzle-kit hides ./bin.cjs), which broke a clean `npm i`.
+function pkgDir(pkg) {
+  let dir = PKG_ROOT;
+  for (;;) {
+    const cand = join(dir, "node_modules", pkg);
+    if (existsSync(join(cand, "package.json"))) return cand;
+    const parent = dirname(dir);
+    if (parent === dir) return null; // hit the filesystem root
+    dir = parent;
+  }
+}
+// Resolve a dependency's CLI entry to an absolute JS path so we can run it with `node` directly —
+// no `shell: true`, no bare-name PATH lookup (a hijacked `npx`/`next`/`drizzle-kit` can't shadow it).
+// Reads the REAL `bin` field from the package's package.json (robust to `exports` + hoisting).
+function resolveBin(pkg, binName) {
+  const d = pkgDir(pkg);
+  if (!d) return null;
+  try {
+    const b = JSON.parse(readFileSync(join(d, "package.json"), "utf8")).bin;
+    const rel = typeof b === "string" ? b : (b?.[binName] ?? b?.[pkg]);
+    return rel ? join(d, rel) : null;
+  } catch { return null; }
+}
+
+/** Free bytes on the volume holding `p` (dependency-free; df / Get-PSDrive). 0 if the probe fails. */
+function freeBytes(p) {
+  try {
+    if (process.platform === "win32") {
+      const d = (p[0] || "C").toUpperCase();
+      const drive = /^[A-Z]$/.test(d) ? d : "C";
+      const out = execFileSync("powershell", ["-NoProfile", "-Command", `(Get-PSDrive ${drive}).Free`], { timeout: 6000 }).toString().trim();
+      return Number(out.replace(/[^\d]/g, "")) || 0;
+    }
+    const out = execFileSync("df", ["-k", p], { timeout: 5000 }).toString().trim();
+    const parts = (out.split("\n").pop() || "").split(/\s+/);
+    return (Number(parts[3]) || 0) * 1024;
+  } catch { return 0; }
+}
+
+/** Enumerate mounted REMOVABLE (USB) drives → [{ mount, label, freeBytes }]. Dependency-free, per-OS. */
+function detectRemovableDrives() {
+  try {
+    if (process.platform === "win32") {
+      const ps = `Get-CimInstance Win32_Volume -Filter "DriveType=2" | Where-Object { $_.DriveLetter } | ForEach-Object { "$($_.DriveLetter)|$($_.Label)|$($_.FreeSpace)" }`;
+      const out = execFileSync("powershell", ["-NoProfile", "-Command", ps], { timeout: 8000 }).toString().trim();
+      return out.split(/\r?\n/).filter(Boolean).map((l) => {
+        const [letter, label, free] = l.split("|");
+        const mount = letter.endsWith(":") ? letter + "\\" : letter + ":\\";
+        return { mount, label: label || "USB", freeBytes: Number(free) || 0 };
+      });
+    }
+    if (process.platform === "darwin") {
+      return readdirSync("/Volumes").map((n) => join("/Volumes", n)).filter((v) => {
+        try { const info = execFileSync("diskutil", ["info", v], { timeout: 5000 }).toString(); return /(Removable Media:\s*(Removable|Yes))|(Protocol:\s*USB)/i.test(info) && !/Internal:\s*Yes/i.test(info); }
+        catch { return false; }
+      }).map((v) => ({ mount: v, label: v.split("/").pop() || "USB", freeBytes: freeBytes(v) }));
+    }
+    // linux: lsblk RM=1 (removable) + a mountpoint
+    const out = execFileSync("lsblk", ["-rpno", "NAME,RM,MOUNTPOINT,LABEL"], { timeout: 6000 }).toString().trim();
+    return out.split(/\r?\n/).map((l) => l.split(/\s+/)).filter((p) => p[1] === "1" && p[2]).map((p) => ({ mount: p[2], label: p[3] || "USB", freeBytes: freeBytes(p[2]) }));
+  } catch { return []; }
+}
+
+/** Portable + no --path: detect USB drives and let the user pick one → returns the chosen .constella root. */
+async function pickUsbHome() {
+  const drives = detectRemovableDrives();
+  if (!drives.length) { console.error("✖ Portable mode: no removable USB drive detected. Insert a pen-drive (or pass --path <drive>)."); process.exit(1); }
+  let chosen;
+  if (drives.length === 1) {
+    chosen = drives[0];
+    console.log(`• Using the only USB drive: ${chosen.label} (${chosen.mount}, ${(chosen.freeBytes / 1e9).toFixed(1)} GB free)`);
+  } else {
+    console.log("Detected USB drives:");
+    drives.forEach((d, i) => console.log(`  [${i + 1}] ${d.label}  ${d.mount}  ·  ${(d.freeBytes / 1e9).toFixed(1)} GB free`));
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const ans = await new Promise((res) => rl.question(`Choose a drive [1-${drives.length}]: `, res));
+    rl.close();
+    chosen = drives[parseInt(ans, 10) - 1] ?? drives[0];
+  }
+  return join(chosen.mount, ".constella");
+}
+
+const PKG = "constella";
+const args = process.argv.slice(2);
+const has = (f) => args.includes(f);
+const flag = (f) => { const i = args.indexOf(f); return i >= 0 ? args[i + 1] : undefined; };
+const cmd = args.find((a) => !a.startsWith("-")) ?? "start";
+
+// ---- resolve run mode (explicit flag wins → --bind back-compat → start) ----
+const modeFlags = ["start", "auth", "vps", "portable"].filter((m) => has(`--${m}`));
+if (modeFlags.length > 1) console.warn(`• multiple mode flags given; using --${modeFlags[0]}`);
+const bind = flag("--bind");
+const runMode = modeFlags[0]
+  ?? (bind === "tailnet" ? "vps" : bind === "portable" ? "portable" : bind === "local" ? "start" : undefined)
+  ?? "start";
+
+// ---- `constella update` — detect + apply a new version (runs outside the server) ----
+function localVersion() {
+  try { return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version ?? "0.0.0"; }
+  catch { return "0.0.0"; }
+}
+async function latestVersion() {
+  try {
+    const ac = new AbortController(); const t = setTimeout(() => ac.abort(), 4000);
+    const r = await fetch(`https://registry.npmjs.org/${PKG}/latest`, { signal: ac.signal });
+    clearTimeout(t);
+    return r.ok ? ((await r.json()).version ?? null) : null;
+  } catch { return null; }
+}
+if (cmd === "update") {
+  const current = localVersion();
+  const latest = await latestVersion();
+  console.log(`Constella ${current}${latest ? ` · latest ${latest}` : " · (npm registry unavailable)"}`);
+  if (has("--check")) process.exit(0);
+  if (!latest) { console.log("Couldn't reach the npm registry — try again later."); process.exit(0); }
+  if (latest === current) { console.log("✓ Already up to date."); process.exit(0); }
+  const fromSource = existsSync(join(process.cwd(), ".git")) && existsSync(join(process.cwd(), "src"));
+  if (fromSource) { console.log("Running from source — update with: git pull && pnpm install && pnpm build"); process.exit(0); }
+  console.log(`Updating ${current} → ${latest} …`);
+  // A global install genuinely needs the user's `npm` from PATH, but drop the shell: pass the
+  // platform binary name directly (npm.cmd on Windows) so there's no shell interpretation.
+  const npmCmd = process.platform === "win32" ? "npm.cmd" : "npm";
+  const r = spawnSync(npmCmd, ["install", "-g", `${PKG}@latest`], { stdio: "inherit" });
+  console.log(r.status === 0 ? "✓ Updated. Restart Constella to load the new version." : "✖ Update failed — retry with elevated permissions.");
+  process.exit(r.status === 0 ? 0 : 1);
+}
+
+// ---- runtime root: explicit (CONSTELLA_HOME / --path) wins; portable with no path → pick a USB drive ----
+const explicitHome = process.env.CONSTELLA_HOME ?? flag("--path");
+let HOME = explicitHome ?? join(homedir(), ".constella");
+if (runMode === "portable" && !explicitHome) HOME = await pickUsbHome();
+mkdirSync(join(HOME, "organizations"), { recursive: true });
+process.env.CONSTELLA_HOME = HOME;
+
+// The installed package's OWN root — where the compiled `.next`, the `drizzle/` migrations and the
+// configs live. When Constella runs as an npm package these are NOT in the user's CWD, so `next` and
+// `drizzle-kit` must run from here (CWD = the launch dir, which has none of them).
+const PKG_ROOT = fileURLToPath(new URL("../", import.meta.url));
+// Absolute JS entries for the tools we boot — run with `node`, never via a shell or a bare PATH name.
+const NEXT_BIN = resolveBin("next", "next");
+const DRIZZLE_BIN = resolveBin("drizzle-kit", "drizzle-kit");
+// Pin the DB to an ABSOLUTE path under the runtime root so `drizzle-kit migrate` (run from PKG_ROOT)
+// and the app (which else defaults it to <launch dir>/.constella) open the SAME database file.
+if (!process.env.DATABASE_URL) process.env.DATABASE_URL = "file:" + join(HOME, "constella.db");
+// The bundled `skills/` library + other package assets live under the PACKAGE root, NOT the launch
+// dir. Export it so the server can find them when installed (the loader falls back to launchDir for
+// the dev tree). Without this, an installed run found zero library skills.
+process.env.CONSTELLA_PKG_ROOT = PKG_ROOT;
+
+const host = flag("--host") ?? (runMode === "vps" || runMode === "portable" ? "0.0.0.0" : "127.0.0.1");
+const port = flag("--port") ?? process.env.PORT ?? "3000";
+process.env.CONSTELLA_RUN_MODE = runMode;
+process.env.CONSTELLA_PUBLIC = "1"; // a CLI launch IS the public runtime → the UI mode picker is hidden
+process.env.CONSTELLA_VERSION = localVersion(); // reliable installed version for the in-app Update check
+if (has("--onboarding") || cmd === "onboard" || cmd === "onboarding") process.env.CONSTELLA_FORCE_ONBOARDING = "1";
+
+// ---- secrets persisted under the runtime root (network modes need a real signing key) ----
+const ENV_FILE = join(HOME, ".env");
+function readEnvFile() {
+  const out = {};
+  if (!existsSync(ENV_FILE)) return out;
+  for (const line of readFileSync(ENV_FILE, "utf8").split(/\r?\n/)) {
+    const m = /^([A-Z0-9_]+)=(.*)$/.exec(line.trim());
+    if (m) out[m[1]] = m[2];
+  }
+  return out;
+}
+function ensureSecret(vars, name, gen) {
+  if (process.env[name]) { vars[name] = process.env[name]; return false; }     // env wins
+  if (vars[name] && !/^(changeme|placeholder)?$/i.test(vars[name])) { process.env[name] = vars[name]; return false; } // reuse persisted
+  vars[name] = gen(); process.env[name] = vars[name]; return true;             // generate once
+}
+// EVERY mode persists a real BETTER_AUTH_SECRET, vault key and worker secret under the runtime root.
+// `next start` runs under NODE_ENV=production, where better-auth THROWS on its default secret — so even
+// local `start` mode needs a real one (the vault needs CONSTELLA_VAULT_KEY to encrypt provider keys,
+// and the worker fails CLOSED without CONSTELLA_WORKER_SECRET). Persisted (not ephemeral) so login
+// sessions + the encrypted vault survive a restart. The server + worker inherit this process.env.
+{
+  const vars = readEnvFile();
+  let changed = false;
+  changed = ensureSecret(vars, "BETTER_AUTH_SECRET", () => randomBytes(32).toString("base64url")) || changed;
+  changed = ensureSecret(vars, "CONSTELLA_VAULT_KEY", () => randomBytes(32).toString("base64")) || changed;
+  changed = ensureSecret(vars, "CONSTELLA_WORKER_SECRET", () => randomBytes(24).toString("base64url")) || changed;
+  if (changed) {
+    writeFileSync(ENV_FILE, Object.entries(vars).map(([k, v]) => `${k}=${v}`).join("\n") + "\n", { mode: 0o600 });
+    try { chmodSync(ENV_FILE, 0o600); } catch { /* best-effort on Windows */ }
+  }
+  console.log(`• Secrets ready (stored in ${ENV_FILE}, never printed).`);
+}
+
+// Portable: validate the drive BEFORE installing/booting (minimum 32 GB free; no upper recommendation).
+if (runMode === "portable") {
+  const free = freeBytes(HOME);
+  const gb = Math.round((free / 1e9) * 10) / 10;
+  if (free && free < 32e9) { console.error(`✖ Portable needs at least 32 GB free — only ${gb} GB on ${HOME}. Use a bigger drive.`); process.exit(1); }
+  else if (free) console.log(`• ${gb} GB free on the drive — good (32 GB minimum; more headroom only helps if you carry local models).`);
+}
+
+console.log(`Constella runtime root : ${HOME}`);
+console.log(`Mode                   : ${runMode}  ·  ${host}:${port}`);
+
+// ---- DB schema: apply the shipped migrations to the (fresh) DB. The compiled distribution ships
+// generated SQL migrations in drizzle/, so a brand-new end-user database is built WITHOUT any source
+// schema file. `migrate` is idempotent — already-applied migrations are skipped. ----
+const dbExisted = existsSync(join(HOME, "constella.db"));
+if (!DRIZZLE_BIN) {
+  console.error("✖ drizzle-kit not found in the install — cannot apply the database schema. Reinstall the package.");
+  process.exit(1);
+}
+const schema = spawnSync(process.execPath, [DRIZZLE_BIN, "migrate", "--config", join(PKG_ROOT, "drizzle.config.mjs")], { stdio: "inherit", cwd: PKG_ROOT });
+if (schema.status !== 0) {
+  // A fresh DB that fails to migrate has NO tables → the app would 500 on every request. Fail loud
+  // instead of "continuing". An already-built DB tolerates a no-op/failed re-run.
+  if (!dbExisted) { console.error("✖ Database schema migration failed on a fresh database — aborting (the app needs its tables)."); process.exit(1); }
+  console.warn("• schema migrate skipped/failed on an existing DB — continuing");
+}
+
+// ---- build-on-first-run (fallback only) ----
+// The published package ships a prebuilt .next under PKG_ROOT, so this is skipped. It only triggers
+// when running from a source tree without a build, where the toolchain is present.
+let built = existsSync(join(PKG_ROOT, ".next", "BUILD_ID"));
+if (!built) {
+  console.log("• No build found — building (first run, one-time)…");
+  spawnSync(process.execPath, [NEXT_BIN, "build"], { stdio: "inherit", cwd: PKG_ROOT });
+  built = existsSync(join(PKG_ROOT, ".next", "BUILD_ID"));
+  if (!built) {
+    // Every `bin/constella.mjs` launch is a public/production run (CONSTELLA_PUBLIC=1). Never
+    // silently downgrade to the unhardened `next dev` server — fail closed unless a developer
+    // explicitly opts in with CONSTELLA_DEV=1 (a source tree without a build).
+    if (process.env.CONSTELLA_DEV !== "1") {
+      console.error("✖ No production build and the build failed. Install a built package or run `pnpm build`. Refusing to start a dev server in a public/network mode.");
+      process.exit(1);
+    }
+    console.warn("• build failed — falling back to the dev server (CONSTELLA_DEV=1).");
+  }
+}
+
+// ---- boot: the web server + the 24/7 worker, each SUPERVISED so a crash doesn't take the whole
+// system down. A "24/7" runtime must survive a transient web/worker crash (e.g. an agent run exhausts
+// memory and the OS kills next start) — the supervisor auto-restarts the dead child instead of exiting.
+// A rolling-window cap stops a genuine crash-loop from spinning forever. (Mirrors scripts/start-all.mjs
+// for the dual-process shape, plus restart.) ----
+if (!NEXT_BIN) { console.error("✖ next not found in the install — cannot start the web server. Reinstall the package."); process.exit(1); }
+
+let shuttingDown = false;
+let webChild = null;
+let workerChild = null;
+function shutdown(code) {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  for (const c of [webChild, workerChild]) { try { c?.kill(); } catch { /* already gone */ } }
+  process.exit(code);
+}
+process.on("SIGINT", () => shutdown(0));
+process.on("SIGTERM", () => shutdown(0));
+
+// Crash-loop guard: at most MAX_RESTARTS within WINDOW_MS per child, else give up (real, repeated
+// crash → don't mask it forever). Opt-in heap bump for the web via CONSTELLA_WEB_HEAP_MB.
+const MAX_RESTARTS = 5, WINDOW_MS = 60_000;
+const HEAP_MB = Number(process.env.CONSTELLA_WEB_HEAP_MB) || 0; // 0 = Node default (a JS-heap OOM prints FATAL; a silent kill is usually OS-level)
+
+/** Spawn a supervised child; on an unexpected exit, auto-restart (bounded) instead of shutting down. */
+function supervise(name, makeChild, onExitInfo) {
+  const restarts = [];
+  const launch = () => {
+    const child = makeChild();
+    child.on("error", (e) => console.error(`[${name}] failed to start:`, e.message));
+    child.on("exit", (code) => {
+      if (shuttingDown) return;
+      const now = Date.now();
+      while (restarts.length && now - restarts[0] > WINDOW_MS) restarts.shift();
+      if (restarts.length >= MAX_RESTARTS) {
+        console.error(`✖ [${name}] exited (${code}) and crashed ${restarts.length}x within ${WINDOW_MS / 1000}s — giving up.${onExitInfo ? " " + onExitInfo : ""}`);
+        return shutdown(code ?? 1);
+      }
+      restarts.push(now);
+      console.warn(`• [${name}] exited (${code}) — auto-restarting in 2s (${restarts.length}/${MAX_RESTARTS} within ${WINDOW_MS / 1000}s).`);
+      setTimeout(() => { if (!shuttingDown) launch(); }, 2000);
+    });
+    return child;
+  };
+  return launch();
+}
+
+const start = built ? [NEXT_BIN, "start", "-H", host, "-p", port] : [NEXT_BIN, "dev", "-H", host, "-p", port];
+const nodeArgs = HEAP_MB > 0 ? [`--max-old-space-size=${HEAP_MB}`] : [];
+console.log(`• Starting: next ${start.slice(1).join(" ")}  (from ${PKG_ROOT}${HEAP_MB ? `, heap ${HEAP_MB}MB` : ""})  +  worker`);
+webChild = supervise("web",
+  () => (webChild = spawn(process.execPath, [...nodeArgs, ...start], { stdio: "inherit", cwd: PKG_ROOT })),
+  "Likely OS-level OOM (agent runs exhausting RAM) or a native crash — cap concurrent agents, or raise CONSTELLA_WEB_HEAP_MB if it's a JS-heap OOM.");
+
+// The worker connects back to the server over localhost (127.0.0.1, even when the server binds
+// 0.0.0.0 for vps/portable) and self-retries until it answers. It survives a web restart on its own
+// (its tick just fails until the web is back), so a web crash restarts ONLY the web — the worker stays.
+const workerPath = fileURLToPath(new URL("./worker.mjs", import.meta.url));
+setTimeout(() => {
+  if (shuttingDown) return;
+  workerChild = supervise("worker",
+    () => (workerChild = spawn(process.execPath, [workerPath], {
+      stdio: "inherit",
+      env: { ...process.env, CONSTELLA_BASE_URL: process.env.CONSTELLA_BASE_URL ?? `http://127.0.0.1:${port}` },
+    })));
+}, 1500);

package/bin/guard-hook.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+/**
+ * Claude Code PreToolUse hook — destructive-command guard.
+ *
+ * Injected (when cmdGuard is on — default) into the agent's clean CLAUDE_CONFIG_DIR by
+ * src/server/adapters/cli.ts. Before any Bash run it checks the command against a small deny-list of
+ * clearly-catastrophic operations and BLOCKS them (exit 2 + a reason the model reads) so an agent can't
+ * wipe the machine, force-push to a remote, or brick a disk. It is intentionally NARROW — only
+ * unambiguously destructive patterns — and fails OPEN on anything else, so it never hard-stalls a legit
+ * run. Self-contained (node built-ins only); makes no network calls.
+ */
+import { readFileSync, appendFileSync, mkdirSync } from "node:fs";
+
+let ev = {};
+try { ev = JSON.parse(readFileSync(0, "utf8")); } catch { process.exit(0); }
+if (ev.tool_name !== "Bash") process.exit(0);
+const cmd = String((ev.tool_input && ev.tool_input.command) || "");
+if (!cmd.trim()) process.exit(0);
+
+// [pattern, human reason]. Conservative: only catastrophic, low-false-positive shapes.
+const DENY = [
+  [/\brm\s+-[a-z]*r[a-z]*f[a-z]*\s+(?:-[a-z]+\s+)*(?:\/|~|\$HOME|\/\*|\.\.?)(?:\s|\/|$)/i, "recursive force-delete of a root / home / cwd path"],
+  [/\brm\s+-[a-z]*f[a-z]*r[a-z]*\s+(?:-[a-z]+\s+)*(?:\/|~|\$HOME|\/\*|\.\.?)(?:\s|\/|$)/i, "recursive force-delete of a root / home / cwd path"],
+  [/\bgit\s+push\b[^\n]*\s(?:--force\b|-f\b|--force-with-lease\b)/i, "force-push to a git remote"],
+  [/\bgit\s+reset\s+--hard\b[^\n]*\borigin\//i, "hard reset onto a remote ref"],
+  [/:\s*\(\s*\)\s*\{\s*:\s*\|\s*:\s*&?\s*\}\s*;\s*:/, "fork bomb"],
+  [/\bmkfs(?:\.\w+)?\b/i, "filesystem format (mkfs)"],
+  [/\bdd\b[^\n]*\bof=\/dev\//i, "raw write to a device (dd of=/dev/…)"],
+  [/>\s*\/dev\/(?:sd|nvme|hd|disk|mapper)\w*/i, "redirect over a raw disk device"],
+  [/\bchmod\s+-[a-z]*R[a-z]*\s+0?00\b/i, "recursive chmod 000"],
+  [/\b(?:shutdown|reboot|halt|poweroff)\b/i, "power / shutdown command"],
+  [/\b(?:curl|wget)\b[^\n|]*\|\s*(?:sudo\s+)?(?:sh|bash|zsh)\b/i, "pipe a downloaded script straight into a shell"],
+];
+
+for (const [re, why] of DENY) {
+  if (re.test(cmd)) {
+    // Bridge the denial to the server Inbox: append it to a workspace log the runner reads + clears
+    // after the task. RAG indexes only .md, so this .jsonl never pollutes retrieval. Best-effort.
+    try { mkdirSync(".claude", { recursive: true }); appendFileSync(".claude/guard-denials.jsonl", JSON.stringify({ at: new Date().toISOString(), why, cmd: cmd.slice(0, 300) }) + "\n"); } catch { /* ignore */ }
+    process.stderr.write(`🛑 Blocked by Constella's safety guard (${why}). Do NOT run destructive system commands. Stay inside the project workspace; if you genuinely need this, stop and ask the operator instead of forcing it.\n`);
+    process.exit(2); // block; Claude Code feeds stderr back to the model
+  }
+}
+process.exit(0);

package/bin/lock-hook.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+/**
+ * Claude Code PreToolUse hook — per-file lock for safe PARALLEL agents.
+ *
+ * Injected (only when CONSTELLA_AGENT_LOCK_HOOK=1) into the agent's clean CLAUDE_CONFIG_DIR by
+ * src/server/adapters/cli.ts. Before any Write/Edit/MultiEdit/NotebookEdit it asks the Constella
+ * web server (loopback, worker-secret) to lock that file for this task/agent. If another agent holds
+ * the file, it BLOCKS the tool (exit 2 + a reason the model reads) so the agent edits something else.
+ *
+ * Fails OPEN on anything unexpected (no context, network glitch, non-edit tool) — a hook problem must
+ * never hard-stall a run.
+ */
+import { readFileSync } from "node:fs";
+
+let ev = {};
+try { ev = JSON.parse(readFileSync(0, "utf8")); } catch { process.exit(0); }
+
+const EDIT_TOOLS = new Set(["Write", "Edit", "MultiEdit", "NotebookEdit"]);
+if (!EDIT_TOOLS.has(ev.tool_name)) process.exit(0);
+
+const input = ev.tool_input || {};
+const file = input.file_path || input.notebook_path || "";
+if (!file) process.exit(0);
+
+const base = process.env.CONSTELLA_BASE_URL;
+const secret = process.env.CONSTELLA_WORKER_SECRET;
+const orgId = process.env.CONSTELLA_ORG_ID;
+if (!base || !secret || !orgId) process.exit(0); // not enough context → allow
+
+try {
+  const res = await fetch(base.replace(/\/$/, "") + "/api/locks/acquire", {
+    method: "POST",
+    headers: { "content-type": "application/json", "x-worker-secret": secret },
+    body: JSON.stringify({
+      orgId, path: file,
+      taskId: process.env.CONSTELLA_TASK_ID || "",
+      agentId: process.env.CONSTELLA_AGENT_ID || "",
+      agentHandle: process.env.CONSTELLA_AGENT_HANDLE || "",
+    }),
+    signal: AbortSignal.timeout(4000),
+  });
+  if (res.status === 423) {
+    const j = await res.json().catch(() => ({}));
+    const who = j && j.heldBy && j.heldBy.handle ? "@" + j.heldBy.handle : "another agent";
+    process.stderr.write(`🔒 ${file} is being edited by ${who} right now — do NOT edit it. Work on a DIFFERENT file, or complete the other parts of your task and return to this file later.\n`);
+    process.exit(2); // block; Claude Code feeds stderr back to the model
+  }
+} catch { /* network/timeout → fail open (allow the edit) */ }
+process.exit(0);

package/bin/worker.mjs

@@ -0,0 +1,142 @@
+// Headless 24/7 runner + workspace file-watcher. Runs independent of any browser, alongside the web
+// server. Self-contained: imports only node built-ins + chokidar and talks to the running server over
+// HTTP — so it ships in the compiled distribution with no `src/` source. Started by:
+//   - bin/constella.mjs (the published CLI launch), and
+//   - scripts/start-all.mjs (dev `pnpm start`).
+import { homedir } from "node:os";
+import { join, relative, sep, isAbsolute, resolve } from "node:path";
+import { setMaxListeners } from "node:events";
+import chokidar from "chokidar";
+
+// Raise Node's default 10-listener ceiling: undici registers a per-request "terminated" listener on
+// its shared internal `[Fetch]` controller, so the tick + telegram + sync fetches trip a benign
+// MaxListenersExceededWarning under load. Bounded (not 0) so a real leak still surfaces.
+setMaxListeners(64);
+
+const BASE = process.env.CONSTELLA_BASE_URL ?? "http://localhost:3000";
+const SECRET = process.env.CONSTELLA_WORKER_SECRET ?? "";
+const INTERVAL = Number(process.env.CONSTELLA_WORKER_INTERVAL_MS ?? 60_000);
+// Anchor a relative CONSTELLA_HOME to the launch dir (INIT_CWD), exactly like the app's
+// resolveRuntimePath — otherwise the worker watches a different tree than the app reads/writes.
+const _rawHome = process.env.CONSTELLA_HOME;
+const HOME = _rawHome
+  ? (isAbsolute(_rawHome) ? _rawHome : resolve(process.env.INIT_CWD || process.cwd(), _rawHome))
+  : join(homedir(), ".constella");
+const ORGS = join(HOME, "organizations");
+
+// SSRF / secret-exfil guard: the worker attaches the privileged x-worker-secret to every call, so it
+// must only ever talk to the local server. Whoever controls the env (systemd unit, Docker env, shell)
+// could otherwise point CONSTELLA_BASE_URL at an attacker host and harvest the secret. The launcher
+// always sets BASE=http://127.0.0.1:<port> (loopback even in vps/portable), so loopback-only breaks
+// nothing legitimate; a genuine remote worker must opt in explicitly.
+const ALLOW_REMOTE = process.env.CONSTELLA_ALLOW_REMOTE_WORKER_BASE_URL === "1";
+let baseHost = "";
+try { baseHost = new URL(BASE).hostname; }
+catch { console.error("✖ Invalid CONSTELLA_BASE_URL:", BASE); process.exit(1); }
+const isLoopback = ["localhost", "127.0.0.1", "::1", "[::1]"].includes(baseHost);
+if (!isLoopback && !ALLOW_REMOTE) {
+  console.error(`✖ Refusing to send the worker secret to a non-loopback host (${baseHost}). Set CONSTELLA_ALLOW_REMOTE_WORKER_BASE_URL=1 to override.`);
+  process.exit(1);
+}
+if (!isLoopback && ALLOW_REMOTE && new URL(BASE).protocol !== "https:") {
+  console.warn(`• CONSTELLA_BASE_URL is a remote http:// host (${baseHost}) — the worker secret will travel in cleartext. Use https://.`);
+}
+const headers = (SECRET && (isLoopback || ALLOW_REMOTE)) ? { "x-worker-secret": SECRET } : {};
+
+/* ---- 24/7 tick ---- */
+async function tick() {
+  try {
+    const res = await fetch(BASE + "/api/cron/tick", { method: "POST", headers });
+    const body = await res.json().catch(() => ({}));
+    console.log(new Date().toISOString(), "tick", res.status, JSON.stringify(body).slice(0, 200));
+  } catch (e) {
+    console.error(new Date().toISOString(), "tick failed:", e?.message ?? e);
+  }
+}
+
+/* ---- file-watcher: disk -> DB index ---- */
+// Only these prefixes are indexed (skills/agents/docs/PO/reports as Markdown).
+const INDEXED = /^(\.claude\/skills\/.+\.md|\.claude\/agents\/[^/]+\/(Agent|skills)\.md|DOCS\/.+\.md|PO\/.+\.md|Reports\/.+\.md)$/;
+
+function parse(abs) {
+  const r = relative(ORGS, abs);                 // <orgId>/workspace/<rel...>
+  if (r.startsWith("..")) return null;
+  const parts = r.split(sep);
+  if (parts.length < 3 || parts[1] !== "workspace") return null;
+  const orgId = parts[0];
+  const rel = parts.slice(2).join("/");
+  if (!INDEXED.test(rel)) return null;
+  return { orgId, rel };
+}
+
+const pending = new Map();
+async function syncFile(orgId, rel, event) {
+  try {
+    const res = await fetch(BASE + "/api/sync/file", {
+      method: "POST",
+      headers: { ...headers, "content-type": "application/json" },
+      body: JSON.stringify({ orgId, rel, event }),
+    });
+    console.log(new Date().toISOString(), "sync", event, rel, res.status);
+  } catch (e) {
+    console.error(new Date().toISOString(), "sync failed:", e?.message ?? e);
+  }
+}
+function schedule(abs, event) {
+  const hit = parse(abs);
+  if (!hit) return;
+  const key = hit.orgId + "::" + hit.rel;
+  clearTimeout(pending.get(key));
+  pending.set(key, setTimeout(() => { pending.delete(key); syncFile(hit.orgId, hit.rel, event); }, 400));
+}
+
+function startWatcher() {
+  const watcher = chokidar.watch(ORGS, {
+    ignoreInitial: true,
+    ignored: /(^|[/\\])(\.git|node_modules)([/\\]|$)/,
+    awaitWriteFinish: { stabilityThreshold: 300, pollInterval: 100 },
+  });
+  watcher
+    .on("add", (p) => schedule(p, "add"))
+    .on("change", (p) => schedule(p, "change"))
+    .on("unlink", (p) => schedule(p, "unlink"))
+    .on("ready", () => console.log("watching", ORGS))
+    .on("error", (e) => console.error("watcher error:", e?.message ?? e));
+}
+
+/* ---- Telegram bot poll (long-poll loop; getUpdates waits ~25s server-side) ---- */
+async function telegramLoop() {
+  for (;;) {
+    try {
+      const res = await fetch(BASE + "/api/telegram/poll", { method: "POST", headers });
+      if (res.status === 401) { await new Promise((r) => setTimeout(r, 30_000)); continue; } // not configured/secret
+      const body = await res.json().catch(() => ({}));
+      if (body?.updates) console.log(new Date().toISOString(), "telegram", body.updates, "update(s)");
+    } catch (e) {
+      console.error(new Date().toISOString(), "telegram poll failed:", e?.message ?? e);
+      await new Promise((r) => setTimeout(r, 5_000));
+    }
+    await new Promise((r) => setTimeout(r, 1_000)); // brief gap between long-polls
+  }
+}
+
+/* ---- wait for the web server before the first tick ---- */
+// The launcher starts us a beat after `next start`, but Next can still be warming up — firing the
+// first tick into a not-yet-listening server printed an alarming "fetch failed". Probe quietly until
+// the server answers (any HTTP status = up), THEN start ticking. Bounded so we never hang forever.
+async function waitForServer() {
+  for (let i = 0; i < 90; i++) {
+    try { await fetch(BASE, { method: "GET" }); return true; } // any response means it's listening
+    catch { await new Promise((r) => setTimeout(r, 1000)); }
+  }
+  return false; // give up after ~90s — tick()'s own error handling takes over
+}
+
+console.log(`Constella worker → tick ${BASE}/api/cron/tick every ${INTERVAL}ms; telegram poll; watching ${ORGS}`);
+startWatcher();
+(async () => {
+  await waitForServer();
+  tick();
+  setInterval(tick, INTERVAL);
+  telegramLoop();
+})();

package/docs/assets/arch-orbit.svg

@@ -0,0 +1,56 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 620" width="640" height="620" role="img" aria-label="Constella control plane and its orbiting agent constellation">
+  <defs>
+    <radialGradient id="sky" cx="50%" cy="42%" r="75%">
+      <stop offset="0%" stop-color="#140e33"/>
+      <stop offset="100%" stop-color="#050416"/>
+    </radialGradient>
+    <linearGradient id="hub" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#a78bfa"/>
+      <stop offset="0.5" stop-color="#22d3ee"/>
+      <stop offset="1" stop-color="#e879f9"/>
+    </linearGradient>
+    <filter id="gl" x="-60%" y="-60%" width="220%" height="220%">
+      <feGaussianBlur stdDeviation="3.5" result="b"/><feMerge><feMergeNode in="b"/><feMergeNode in="SourceGraphic"/></feMerge>
+    </filter>
+  </defs>
+  <rect width="640" height="620" fill="url(#sky)"/>
+
+  <!-- orbit rings -->
+  <g fill="none" stroke="#3b3168" stroke-width="1.2" opacity="0.8">
+    <circle cx="320" cy="320" r="120" stroke-dasharray="4 8"><animateTransform attributeName="transform" type="rotate" from="0 320 320" to="360 320 320" dur="40s" repeatCount="indefinite"/></circle>
+    <circle cx="320" cy="320" r="245" stroke-dasharray="3 10"><animateTransform attributeName="transform" type="rotate" from="360 320 320" to="0 320 320" dur="70s" repeatCount="indefinite"/></circle>
+  </g>
+
+  <!-- spokes -->
+  <g stroke="#22d3ee" stroke-width="0.7" opacity="0.18">
+    <line x1="320" y1="320" x2="320" y2="200"/><line x1="320" y1="320" x2="216" y2="380"/><line x1="320" y1="320" x2="424" y2="380"/>
+    <line x1="320" y1="320" x2="320" y2="75"/><line x1="320" y1="320" x2="129" y2="167"/><line x1="320" y1="320" x2="81" y2="375"/>
+    <line x1="320" y1="320" x2="214" y2="541"/><line x1="320" y1="320" x2="426" y2="541"/><line x1="320" y1="320" x2="559" y2="375"/><line x1="320" y1="320" x2="511" y2="167"/>
+  </g>
+
+  <!-- central control plane -->
+  <g filter="url(#gl)">
+    <polygon points="320,288 352,320 320,352 288,320" fill="url(#hub)"/>
+  </g>
+  <text x="320" y="378" text-anchor="middle" font-family="'Segoe UI',Arial,sans-serif" font-size="14" font-weight="700" fill="#e2e8f0">CONSTELLA</text>
+  <text x="320" y="394" text-anchor="middle" font-family="'Segoe UI',Arial,sans-serif" font-size="9" fill="#64748b" letter-spacing="2">CONTROL PLANE</text>
+
+  <!-- agent nodes -->
+  <g font-family="'Segoe UI',Arial,sans-serif" font-size="11" fill="#cbd5e1" text-anchor="middle">
+    <g><circle cx="320" cy="200" r="6.5" fill="#e879f9" filter="url(#gl)"/><text x="320" y="184">Ada · CEO</text></g>
+    <g><circle cx="216" cy="380" r="6" fill="#e879f9"/><text x="196" y="398">Linus · CTO</text></g>
+    <g><circle cx="424" cy="380" r="6" fill="#22d3ee"/><text x="448" y="398">Donald · PO</text></g>
+    <g><circle cx="320" cy="75" r="6" fill="#22d3ee"/><text x="320" y="60">Margaret · Backend</text></g>
+    <g><circle cx="129" cy="167" r="6" fill="#22d3ee"/><text x="129" y="152">Grace · Frontend</text></g>
+    <g><circle cx="81" cy="375" r="6" fill="#22d3ee"/><text x="78" y="359">Edsger · QA</text></g>
+    <g><circle cx="214" cy="541" r="6" fill="#22d3ee"/><text x="214" y="562">Werner · DevOps</text></g>
+    <g><circle cx="426" cy="541" r="6" fill="#a78bfa"/><text x="426" y="562">Barbara · Docs</text></g>
+    <g><circle cx="559" cy="375" r="6.5" fill="#e879f9" filter="url(#gl)"/><text x="559" y="359">Whitfield · CyberSec</text></g>
+    <g><circle cx="511" cy="167" r="6" fill="#a78bfa"/><text x="511" y="152">Vannevar · Knowledge</text></g>
+  </g>
+
+  <!-- travelling photon on the inner orbit -->
+  <circle r="3.5" fill="#ffffff" filter="url(#gl)">
+    <animateMotion dur="9s" repeatCount="indefinite" path="M 320 200 A 120 120 0 1 1 320 440 A 120 120 0 1 1 320 200"/>
+  </circle>
+</svg>