@saadnvd1/agent-os 0.3.654 → 0.3.658

package/lib/health/env/types.ts

@@ -0,0 +1,73 @@
+// What the environment-failure detector knows and shows. Plain data, no I/O.
+
+export interface EnvClass {
+  id: string;
+  label: string;
+  // shell: only shell tools' output; guard: any tool's refused call.
+  scope: "shell" | "guard";
+  // Any of these, tested per line.
+  match: RegExp[];
+  // Also has to hold, tested on the whole output.
+  requires?: RegExp;
+  // Vetoes: a command or output that shows it isn't this machine's fault.
+  except?: { command?: RegExp; output?: RegExp };
+  // Sent once to a session that hit it; null means record and escalate only.
+  fix: string | null;
+}
+
+export interface EnvHit {
+  class: string;
+  line: string;
+  command: string;
+}
+
+export interface EnvFailureRow {
+  id: number;
+  session_id: string;
+  class: string;
+  project_id: string | null;
+  workspace_id: string | null;
+  command: string | null;
+  line: string | null;
+  last_item_id: string | null;
+  hits: number;
+  first_at: number;
+  last_at: number;
+  nudged_at: number | null;
+  nudge_skipped: string | null;
+  alerted: string | null;
+  alerted_at: number | null;
+}
+
+export interface EnvClassView {
+  id: string;
+  label: string;
+  fix: string | null;
+  fixOverridden: boolean;
+  sessions7: number;
+  sessions30: number;
+  projects: {
+    id: string | null;
+    name: string;
+    sessions7: number;
+    sessions30: number;
+  }[];
+}
+
+export interface EnvSummary {
+  now: number;
+  classes: EnvClassView[];
+}
+
+export interface EnvSessionView {
+  sessionId: string;
+  name: string;
+  project: string | null;
+  command: string | null;
+  line: string | null;
+  hits: number;
+  firstAt: number;
+  lastAt: number;
+  // "sent", or why not.
+  fix: string;
+}

package/lib/health/tick.ts

@@ -10,6 +10,7 @@ import { leaveHeartbeat } from "./boots";
 import { healthConfig, type HealthConfig } from "./config";
 import { runDetectors } from "./detectors";
 import { gatherFacts, liveBackgroundJobs } from "./facts";
+import { envTick, realEnv, type EnvDeps } from "./env/envTick";
 import { addNote } from "./notes";
 import { closeResolvedPieces } from "./pieces";
 import { deliver, deliverClosed, type RouteDeps, realRoute } from "./route";
@@ -52,6 +53,7 @@ export interface TickDeps {
   facts: (now: number, c: HealthConfig) => HealthFacts;
   watch: WatchDeps;
   route: RouteDeps;
+  env: EnvDeps;
   wake: typeof wake;
 }
 
@@ -60,6 +62,7 @@ export const realTick: TickDeps = {
   facts: gatherFacts,
   watch: { run: runClaude, usagePct: currentUsagePct },
   route: realRoute,
+  env: realEnv,
   wake,
 };
 
@@ -137,6 +140,9 @@ export function healthTick(
   closeResolvedPieces(now);
   leaveHeartbeat(now, liveBackgroundJobs());
   giveUpStale(now, deps);
+  void envTick(now, c, deps.env).catch((error) =>
+    console.error("[health] environment failures:", error)
+  );
 
   const running: Promise<void>[] = [];
   for (const row of openAnomalies()) {

package/lib/orchestrator/brief.ts

@@ -160,7 +160,7 @@ Acting:
 
 The MCP servers this workspace allows (Settings → Workspaces) are yours to use through their own tools, for reading and for additive, reversible changes. Anything outbound through them (sending a message, an email, a post) is a hard line: park it with \`ask_saad\`.
 
-Act through these tools, not the shell: they're scoped to this workspace and braked. The shell runs anything without asking (Saad chose this on 2026-10-11), so use it to read and investigate yourself: \`gh pr list\`, \`gh run view --log-failed\`, \`gh api\` GETs, \`curl\`, \`sqlite3 -readonly\`, git in any repository, a skill's scripts, pipes and chains. Never use it to get around the tools. A deny list refuses, naming the tool to use instead: merging, closing or retargeting a PR (\`${TOOL_NAMES.sign_off}\`, \`${TOOL_NAMES.arm}\`, \`${TOOL_NAMES.land}\`, \`${TOOL_NAMES.drop}\`), \`git push\` (\`${TOOL_NAMES.quick_pr}\`), writing in a project repository or task worktree other than your own quick changes (\`${TOOL_NAMES.start_task}\`, \`${TOOL_NAMES.quick_change}\`), writing AgentOS's state (sqlite3 without \`-readonly\`, or files in ~/.agent-os outside your folder), stopping or restarting AgentOS or its tmux, and reading secret files (env files, keys, ~/.ssh, ~/.aws). Tokenvault is available through \`tv\`: use a token inside the command that needs it (e.g. \`FOO="\$(tv get <project> <desc>)" cmd\`), never print, echo or log a value, and never send one off the machine except to the service it's for. The list catches honest mistakes, not a determined bypass: a script or \`python -c\` could do any of these unseen, and doing so would break Saad's trust in every gate. \`aos notify "<text>"\` pushes a message to Saad's phone. Use it for what he'd want to see now and asked for: the morning report, a real milestone (a stack landed, a blocker only he can clear). Never for routine status: one a minute at most, and he reads the rest here. You can read files anywhere (Read, Grep, Glob), and write them (Write, Edit, NotebookEdit) anywhere except: a project repository or task worktree other than your own open quick changes' worktrees (start a task, or a quick change for a small edit, so the change goes through CI, review and scope), AgentOS's own state in ~/.agent-os outside your folder, secret files (.env, keys, ~/.ssh, ~/.aws, tokenvault and the like), and files that make something run: dotfiles and dot-folders at the top of your home (shell, git, Claude and tool config), ~/Library and /Library's launch agents, git's core.hooksPath folders, the folders on PATH, and any .git, .claude, .mcp.json, CLAUDE.md or AGENTS.md, which would hand you a shell or run code around the gates. Each write is checked before it runs, on the path with symlinks and \`..\` resolved; a refused one says why.
+Act through these tools, not the shell: they're scoped to this workspace and braked. The shell runs anything without asking (Saad chose this on 2026-10-11), so use it to read and investigate yourself: \`gh pr list\`, \`gh run view --log-failed\`, \`gh api\` GETs, \`curl\`, \`sqlite3 -readonly\`, git in any repository, a skill's scripts, pipes and chains. Never use it to get around the tools. A deny list refuses, naming the tool to use instead: merging, closing or retargeting a PR (\`${TOOL_NAMES.sign_off}\`, \`${TOOL_NAMES.arm}\`, \`${TOOL_NAMES.land}\`, \`${TOOL_NAMES.drop}\`), \`git push\` (\`${TOOL_NAMES.quick_pr}\`), writing in a project repository or task worktree other than your own quick changes, except in a project checkout of your own workspace, where you may update and move the branch: \`git pull\` in any form, \`merge\`, \`reset\` (even \`--hard\`), \`checkout\`, \`switch\` and \`rebase\` (also as \`git -C <path>\`), then \`bundle install\`, \`npm install\` or \`bin/rails db:prepare\`. Commits, \`stash\`, \`clean\`, \`restore\` and file edits there still go through tasks and quick changes, and other workspaces' repositories, task worktrees and AgentOS's own live checkout (autodeploy deploys it) are refused for all of it are refused (\`${TOOL_NAMES.start_task}\`, \`${TOOL_NAMES.quick_change}\`), writing AgentOS's state (sqlite3 without \`-readonly\`, or files in ~/.agent-os outside your folder), stopping or restarting AgentOS or its tmux, and reading secret files (env files, keys, ~/.ssh, ~/.aws). Tokenvault is available through \`tv\`: use a token inside the command that needs it (e.g. \`FOO="\$(tv get <project> <desc>)" cmd\`), never print, echo or log a value, and never send one off the machine except to the service it's for. The list catches honest mistakes, not a determined bypass: a script or \`python -c\` could do any of these unseen, and doing so would break Saad's trust in every gate. \`aos notify "<text>"\` pushes a message to Saad's phone. Use it for what he'd want to see now and asked for: the morning report, a real milestone (a stack landed, a blocker only he can clear). Never for routine status: one a minute at most, and he reads the rest here. You can read files anywhere (Read, Grep, Glob), and write them (Write, Edit, NotebookEdit) anywhere except: a project repository or task worktree other than your own open quick changes' worktrees (start a task, or a quick change for a small edit, so the change goes through CI, review and scope), AgentOS's own state in ~/.agent-os outside your folder, secret files (.env, keys, ~/.ssh, ~/.aws, tokenvault and the like), and files that make something run: dotfiles and dot-folders at the top of your home (shell, git, Claude and tool config), ~/Library and /Library's launch agents, git's core.hooksPath folders, the folders on PATH, and any .git, .claude, .mcp.json, CLAUDE.md or AGENTS.md, which would hand you a shell or run code around the gates. Each write is checked before it runs, on the path with symlinks and \`..\` resolved; a refused one says why.
 
 ## Untrusted text
 

package/lib/orchestrator/shell-guard.ts

@@ -29,6 +29,10 @@ export interface ShellContext {
   // Whether this path is under ~/.agent-os/audits, where reports go and
   // nothing may be made executable.
   inAudits?: (p: string) => Promise<boolean>;
+  // What a folder is for fast-forwarding: a project checkout of this
+  // workspace ("own"), the checkout AgentOS's live server and autodeploy run
+  // from ("live"), or anything else.
+  checkoutKind?: (dir: string) => Promise<"own" | "live" | "other">;
   // AgentOS's server and the tmux servers it runs sessions in.
   protectedPids: () => Promise<Set<number>>;
 }
@@ -324,22 +328,40 @@ const GIT_WRITES = new Set([
 
 const READ_ONLY_STASH = new Set(["list", "show"]);
 
+// What an orchestrator may do to a project checkout of its own workspace:
+// bring it up to date and move its branch (Saad, 2026-10-18). Commits, stash,
+// clean and file edits still go through tasks and quick changes.
+const CHECKOUT_UPDATES = new Set([
+  "pull",
+  "merge",
+  "reset",
+  "checkout",
+  "switch",
+  "rebase",
+]);
+
 async function gitRefusal(
-  args: string[],
+  inv: Invocation,
   ctx: ShellContext,
   cwd: string
 ): Promise<string | null> {
+  const args = inv.args;
+  // Every repository the command names: the folder after each -C, and each
+  // git dir and work tree, by option or environment.
+  const named = new Set<string>();
   let dir = cwd;
   let i = 0;
   for (; i < args.length; i++) {
     const a = args[i];
     if (a === "-C" || a === "--git-dir" || a === "--work-tree") {
-      dir = path.resolve(dir, args[++i] ?? "");
+      const to = path.resolve(dir, args[++i] ?? "");
+      if (a === "-C") dir = to;
+      named.add(to);
       continue;
     }
     const eq = /^--(git-dir|work-tree)=(.*)$/.exec(a);
     if (eq) {
-      dir = path.resolve(dir, eq[2]);
+      named.add(path.resolve(dir, eq[2]));
       continue;
     }
     if (a === "-c" || a === "--namespace" || a === "--exec-path") {
@@ -349,17 +371,28 @@ async function gitRefusal(
     if (a.startsWith("-")) continue;
     break;
   }
+  named.add(dir);
+  for (const w of inv.cmd.words) {
+    const env = /^GIT_(?:DIR|WORK_TREE)=(.*)$/.exec(w);
+    if (env) named.add(path.resolve(cwd, env[1]));
+  }
   const sub = args[i];
   if (sub === "push")
     return `Refused: ${T.quick_pr} pushes a quick change's branch and opens its PR, and tasks push their own; nothing pushes from the orchestrator's shell.`;
   if (!GIT_WRITES.has(sub)) return null;
   if (sub === "stash" && READ_ONLY_STASH.has(args[i + 1])) return null;
-  if (has(dir))
-    return `Refused: git ${sub} in a folder only the shell knows (${show(dir)}); name the folder.`;
-  const why = await ctx.writeRefusal(dir);
-  return why
-    ? `Refused: git ${sub} in ${dir}. Orchestrators don't change project checkouts (autodeploy runs from them). To see current code: \`git -C ${dir} fetch\` then \`git -C ${dir} show origin/main:<path>\` or \`git -C ${dir} log origin/main\`.`
-    : null;
+  for (const d of named) {
+    if (has(d))
+      return `Refused: git ${sub} in a folder only the shell knows (${show(d)}); name the folder.`;
+    if (!(await ctx.writeRefusal(d))) continue;
+    const kind = (await ctx.checkoutKind?.(d)) ?? "other";
+    const updates = CHECKOUT_UPDATES.has(sub);
+    if (kind === "live" && updates)
+      return `Refused: git ${sub} in ${d}. This is the checkout AgentOS's live server runs from; autodeploy deploys it (restart gap and health check), and changing it here would swap the code under the running server. For a manual deploy use scripts/redeploy.`;
+    if (kind === "own" && updates) continue;
+    return `Refused: git ${sub} in ${d}. Orchestrators don't change project checkouts except to update them: in a project checkout of your own workspace you may \`git pull\` (any form), \`merge\`, \`reset\`, \`checkout\`, \`switch\` and \`rebase\`. Commits, \`stash\`, \`clean\`, \`restore\` and file edits go through ${T.start_task} or ${T.quick_change}; other workspaces' repositories, task worktrees and AgentOS's live checkout are never changed from here. To see current code: \`git -C ${d} fetch\` then \`git -C ${d} show origin/main:<path>\` or \`git -C ${d} log origin/main\`.`;
+  }
+  return null;
 }
 
 // Commands whose every non-option argument is a file they change, and
@@ -557,7 +590,7 @@ export async function shellRefusal(
         (inv.name === "gh" ? ghRefusal(inv.args) : null) ??
         (inv.name === "curl" ? curlRefusal(inv.args) : null) ??
         (inv.name === "aos" ? aosRefusal(inv.args) : null) ??
-        (inv.name === "git" ? await gitRefusal(inv.args, ctx, cwd) : null) ??
+        (inv.name === "git" ? await gitRefusal(inv, ctx, cwd) : null) ??
         (inv.name === "sqlite3"
           ? await sqliteRefusal(inv, ctx, cwd, command)
           : null) ??

package/lib/orchestrator/write-guard.ts

@@ -24,6 +24,7 @@ import { orchestratorDir } from "./home";
 import { LIMITS_FILE } from "./usage";
 import { quickWorktrees } from "./quick-store";
 import { shellRefusal } from "./shell-guard";
+import { liveCheckout } from "../dev-instance/liveServer";
 
 // The tools that write a file, and the argument naming it.
 export const WRITE_TOOLS: Record<string, string> = {
@@ -398,10 +399,61 @@ async function commandRefusal(
         : [];
       return roots.some((r) => within(p, r));
     },
+    checkoutKind: (dir) => checkoutKind(session, dir),
     protectedPids,
   });
 }
 
+// Whether a folder is a project checkout of the session's own workspace
+// (where it may update and move the branch), a checkout AgentOS's live
+// server or autodeploy runs from (never), or neither. The live ones are the
+// server's folder, the one live-server.json recorded (known even while the
+// server restarts), and any main checkout holding scripts/autodeploy, since
+// that script deploys the folder it sits in (a task worktree has a .git
+// file, not a folder).
+export async function checkoutKind(
+  session: Session,
+  dir: string
+): Promise<"own" | "live" | "other"> {
+  const real = await physicalPath(dir);
+  const roots = async (paths: (string | undefined)[]) =>
+    Promise.all(
+      paths
+        .filter((p): p is string => !!p)
+        .flatMap((p) => [path.resolve(p), p])
+        .map((p) => physicalPath(p))
+    );
+  const live = await roots([process.cwd(), liveCheckout() ?? undefined]);
+  if (live.some((r) => within(real, r)) || deploysFrom(real)) return "live";
+  if (!session.workspace_id) return "other";
+  const own = db
+    .prepare(
+      `SELECT working_directory AS dir FROM projects
+        WHERE workspace_id = ? AND is_uncategorized = 0 AND host_id = 'local'
+       UNION SELECT r.path FROM project_repositories r
+         JOIN projects p ON p.id = r.project_id
+        WHERE p.workspace_id = ? AND p.host_id = 'local'`
+    )
+    .all(session.workspace_id, session.workspace_id) as { dir: string }[];
+  const mine = await roots(own.map((p) => expandHome(p.dir)).filter(Boolean));
+  return mine.some((r) => within(real, r)) ? "own" : "other";
+}
+
+function deploysFrom(real: string): boolean {
+  for (let at = real; ; at = path.dirname(at)) {
+    try {
+      if (
+        fs.statSync(path.join(at, "scripts", "autodeploy")).isFile() &&
+        fs.statSync(path.join(at, ".git")).isDirectory()
+      )
+        return true;
+    } catch {
+      // Not here; look higher.
+    }
+    if (path.dirname(at) === at) return false;
+  }
+}
+
 // AgentOS's server (whatever listens on its port), the tmux servers its
 // sessions run in, and this worker. A lookup that fails refuses the kill.
 async function protectedPids(): Promise<Set<number>> {

package/lib/security/demo.ts

@@ -66,6 +66,7 @@ export const STATIC_SIBLINGS = [
   "me",
   "items",
   "network",
+  "pdf",
   "preview",
   "queue",
   "status",

package/lib/share/pdf.ts

@@ -0,0 +1,116 @@
+/**
+ * The share page as a PDF, printed by headless Chromium from the exact HTML
+ * the preview shows. One browser is launched lazily, reused, and closed after
+ * a quiet spell. Nothing on the page can reach the network: only the inlined
+ * markup is rendered.
+ */
+
+import fs from "fs";
+import type { Browser, LaunchOptions } from "playwright";
+
+const IDLE_MS = 60_000;
+const RENDER_MS = 30_000;
+
+const CHROME_PATHS = [
+  "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+  "/usr/bin/google-chrome",
+  "/usr/bin/google-chrome-stable",
+  "/usr/bin/chromium",
+  "/usr/bin/chromium-browser",
+];
+
+/** Print-only rules, added here so the HTML download stays as it was. */
+const PRINT_CSS = `
+@page{margin:16mm 14mm}
+html,body{background:#fff!important}
+.wrap{max-width:none;padding:0}
+*{-webkit-print-color-adjust:exact;print-color-adjust:exact}
+pre code,pre,details.tool pre{white-space:pre-wrap!important;word-break:break-word!important;overflow-wrap:anywhere;overflow:visible;max-height:none}
+table{display:table;width:100%;table-layout:auto;overflow-wrap:anywhere}
+pre,table,tr,.plan,.error,details.tool{break-inside:avoid-page}
+h1,h2,h3,h4{break-after:avoid}
+img{max-width:100%;break-inside:avoid}
+`;
+
+let found: LaunchOptions | null | undefined;
+
+/** How to launch a browser on this machine, or null when there is none. */
+export async function findBrowser(): Promise<LaunchOptions | null> {
+  if (found !== undefined) return found;
+  const { chromium } = await import("playwright");
+  const candidates = [chromium.executablePath(), ...CHROME_PATHS];
+  const path = candidates.find((p) => p && fs.existsSync(p));
+  found = path ? { executablePath: path, headless: true } : null;
+  return found;
+}
+
+export const pdfAvailable = async () => (await findBrowser()) !== null;
+
+/** Test hook: forget the cached lookup and any open browser. */
+export async function resetPdfBrowser() {
+  found = undefined;
+  await closeBrowser();
+}
+
+let browser: Promise<Browser> | null = null;
+let idle: NodeJS.Timeout | null = null;
+
+async function closeBrowser() {
+  if (idle) clearTimeout(idle);
+  idle = null;
+  const b = browser;
+  browser = null;
+  if (b) await (await b).close().catch(() => {});
+}
+
+async function getBrowser(): Promise<Browser> {
+  const opts = await findBrowser();
+  if (!opts) throw new Error("No browser to print with on this machine.");
+  if (!browser) {
+    const { chromium } = await import("playwright");
+    const launched = chromium.launch(opts);
+    browser = launched;
+    launched.then(
+      (b) =>
+        b.on("disconnected", () => browser === launched && (browser = null)),
+      () => {
+        if (browser === launched) browser = null;
+      }
+    );
+  }
+  return browser;
+}
+
+const withPrint = (html: string) =>
+  html.includes("</head>")
+    ? html.replace("</head>", () => `<style>${PRINT_CSS}</style></head>`)
+    : `<style>${PRINT_CSS}</style>${html}`;
+
+/** The page printed to an A4 PDF. */
+export async function renderPdf(html: string): Promise<Buffer> {
+  const b = await getBrowser();
+  if (idle) clearTimeout(idle);
+  const ctx = await b.newContext({
+    javaScriptEnabled: false,
+    colorScheme: "light",
+  });
+  try {
+    await ctx.setOffline(true);
+    const page = await ctx.newPage();
+    page.setDefaultTimeout(RENDER_MS);
+    await page.emulateMedia({ media: "print", colorScheme: "light" });
+    // "load" waits for images and fonts; scripts are off, so nothing runs after.
+    await page.setContent(withPrint(html), { waitUntil: "load" });
+    return Buffer.from(
+      await page.pdf({
+        format: "A4",
+        printBackground: true,
+        preferCSSPageSize: true,
+      })
+    );
+  } finally {
+    await ctx.close().catch(() => {});
+    idle = setTimeout(() => void closeBrowser(), IDLE_MS);
+    idle.unref();
+  }
+}

package/lib/share/view.ts

@@ -22,6 +22,9 @@ export interface PreviewItem {
   excerpt: string;
 }
 
+/** Download formats a server can make; the client lists what it is told. */
+export type ShareFormat = "pdf" | "html" | "md";
+
 export interface SharePreview {
   html: string;
   markdown: string;
@@ -33,6 +36,8 @@ export interface SharePreview {
   hits: Record<"secret" | "path" | "ip" | "host" | "email", number>;
   tooBig: boolean;
   connectLinked: boolean;
+  /** Best first. pdf only when this machine has a browser to print with. */
+  formats: ShareFormat[];
 }
 
 export interface SharedLinkRow {
@@ -103,7 +108,10 @@ export function formatBytes(n: number): string {
 }
 
 /** A file name for a download: the title, plain, with .html (or `ext`). */
-export function fileName(title: string, ext: "html" | "md" = "html"): string {
+export function fileName(
+  title: string,
+  ext: "html" | "md" | "pdf" = "html"
+): string {
   const slug = title
     .toLowerCase()
     .replace(/[^a-z0-9]+/g, "-")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saadnvd1/agent-os",
-  "version": "0.3.654",
+  "version": "0.3.658",
   "description": "Self-hosted web UI for managing Claude Code sessions",
   "bin": {
     "agent-os": "scripts/agent-os"
@@ -31,10 +31,12 @@
   "scripts": {
     "predev": "node scripts/ensure-native.mjs && node scripts/gen-migrations-index.mjs",
     "dev": "AGENTOS_DEV=1 tsx server.ts",
+    "dev:task": "tsx scripts/dev-task.ts",
+    "dev:stop": "tsx scripts/dev-stop.ts",
     "prebuild": "node scripts/gen-migrations-index.mjs",
     "build": "next build",
     "prestart": "node scripts/ensure-native.mjs && node scripts/gen-migrations-index.mjs",
-    "start": "NODE_ENV=production tsx server.ts",
+    "start": "NODE_ENV=production AGENTOS_SERVER=live node --import tsx server.ts",
     "pretypecheck": "node scripts/gen-migrations-index.mjs",
     "typecheck": "tsc --noEmit",
     "setup": "bash scripts/setup.sh",
@@ -141,6 +143,7 @@
     "next": "^16.3.8",
     "next-themes": "^0.4.6",
     "node-pty": "^1.2.0-beta.6",
+    "playwright": "^1.63.0",
     "qrcode": "^1.5.4",
     "react": "^19.2.1",
     "react-dom": "^19.2.1",
@@ -171,7 +174,6 @@
     "eslint-config-next": "^16.3.8",
     "husky": "^9.1.7",
     "jsdom": "^30.1.2",
-    "playwright": "^1.63.0",
     "prettier": "^3.7.4",
     "prettier-plugin-tailwindcss": "^0.7.2",
     "sharp": "^0.35.5",

package/scripts/dev-stop.ts

@@ -0,0 +1,7 @@
+import fs from "fs";
+import { stopDevServer } from "@/lib/dev-instance";
+
+stopDevServer(fs.realpathSync(process.cwd())).then((r) => {
+  console.log(r.message);
+  process.exit(r.ok ? 0 : 1);
+});

package/scripts/dev-task.ts

@@ -0,0 +1,16 @@
+import fs from "fs";
+import { startDevServer } from "@/lib/dev-instance";
+
+const i = process.argv.indexOf("--port");
+const requested = i === -1 ? undefined : Number(process.argv[i + 1]);
+
+startDevServer({ worktree: fs.realpathSync(process.cwd()), requested })
+  .then((r) =>
+    console.log(
+      `Dev server ${r.reused ? "already running" : "started"}: pid ${r.pid} on http://localhost:${r.port} (log ${r.log}). Stop it with npm run dev:stop.`
+    )
+  )
+  .catch((e: Error) => {
+    console.error(e.message);
+    process.exit(1);
+  });

package/scripts/screenshots/demo.ts

@@ -11,7 +11,7 @@
  */
 import fs from "fs";
 import path from "path";
-import { execFileSync, spawn } from "child_process";
+import { spawnServer } from "@/lib/dev-instance";
 import { PORT, REPO, demoEnv } from "./config";
 import { seed, teardownTmux } from "./seed";
 import { startPeer } from "./peer";
@@ -35,13 +35,9 @@ async function main() {
       process.env[k] ? [[k, process.env[k]!]] : []
     )
   );
-  // server.ts imports the generated migrations index.
-  execFileSync(process.execPath, ["scripts/gen-migrations-index.mjs"], {
-    cwd: REPO,
-  });
-  const tsx = path.join(REPO, "node_modules", "tsx", "dist", "cli.mjs");
-  const server = spawn(process.execPath, [tsx, "server.ts"], {
-    cwd: REPO,
+  const server = spawnServer({
+    repo: REPO,
+    port: PORT,
     env: demoEnv({
       AGENTOS_BIND: "127.0.0.1",
       ...passed,

package/scripts/screenshots/run.ts

@@ -8,7 +8,8 @@
  */
 import fs from "fs";
 import path from "path";
-import { execFileSync, spawn, type ChildProcess } from "child_process";
+import { type ChildProcess } from "child_process";
+import { spawnServer } from "@/lib/dev-instance";
 import { BASE_URL, PORT, REPO, ROOT, demoEnv } from "./config";
 import { seed, teardownTmux } from "./seed";
 import { shoot } from "./shoot";
@@ -38,14 +39,10 @@ async function waitForServer(server: ChildProcess): Promise<void> {
 
 function startServer(): ChildProcess {
   const log = fs.openSync(path.join(ROOT, "server.log"), "w");
-  // server.ts imports the generated migrations index.
-  execFileSync(process.execPath, ["scripts/gen-migrations-index.mjs"], {
-    cwd: REPO,
-  });
-  const tsx = path.join(REPO, "node_modules", "tsx", "dist", "cli.mjs");
   // Loopback only: the demo never listens on another network.
-  return spawn(process.execPath, [tsx, "server.ts"], {
-    cwd: REPO,
+  return spawnServer({
+    repo: REPO,
+    port: PORT,
     // No watchers: the seeded orchestrator and tasks must sit still, never
     // start an agent.
     env: demoEnv({

package/server.ts

@@ -78,6 +78,11 @@ import { failInterruptedSetups } from "./lib/sessions/worktree-setup";
 import { sweepOrphanTmux } from "./lib/tmux/orphans";
 import { releaseInterruptedClaims } from "./lib/orchestrator/ask-approvals";
 import { resumeReviews } from "./lib/orchestrator/review";
+import {
+  isLiveServer,
+  readLiveRecord,
+  writeLiveRecord,
+} from "./lib/dev-instance";
 import { claimAgentosEnv } from "./lib/agents/self-env";
 import { wslNotes, wslVersion } from "./lib/wsl";
 import { getAllProjects } from "./lib/projects";
@@ -89,6 +94,19 @@ const hostname = "127.0.0.1";
 
 // Support: npm run dev -- -p 3012
 const port = serverPort();
+const live = isLiveServer();
+// A distinct title keeps `pkill -f server.ts` and `pkill tsx` off the
+// production server; an AgentOS in a worktree can't take its port.
+process.title = live ? "agentos-server" : "agentos-dev";
+if (!live) {
+  const rec = readLiveRecord();
+  if (rec && rec.port === port && rec.pid !== process.pid) {
+    console.error(
+      `Refusing to start: port ${port} is the live AgentOS server (pid ${rec.pid}). Use npm run dev:task.`
+    );
+    process.exit(1);
+  }
+}
 claimAgentosEnv(port);
 // Demo mode: seeded data, nothing that runs code (lib/security/demo).
 const demo = demoMode();
@@ -302,6 +320,13 @@ app.prepare().then(async () => {
     });
     server.listen(port, address, () => {
       console.log(`> Agent-OS ready on http://${address}:${port}`);
+      if (live)
+        writeLiveRecord({
+          pid: process.pid,
+          port,
+          cwd: process.cwd(),
+          startedAt: Date.now(),
+        });
     });
   };
   const stopListening = (address: string) => {