@saadnvd1/agent-os 0.3.653 → 0.3.657

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/shell-guard.ts

@@ -1,7 +1,7 @@
 import fs from "fs";
 import os from "os";
 import path from "path";
-import { isSecretPath } from "../secret-paths";
+import { isOrchestratorSecretPath as isSecretPath } from "../secret-paths";
 import { TOOL_NAMES } from "./tool-names";
 import { parseShell, UNKNOWN, type SimpleCommand } from "./shell-parse";
 
@@ -26,6 +26,9 @@ export interface ShellContext {
   writeRefusal: (p: string) => Promise<string | null>;
   // Whether this file is AgentOS's database or other state of its own.
   isAgentOsState: (p: string) => Promise<boolean>;
+  // Whether this path is under ~/.agent-os/audits, where reports go and
+  // nothing may be made executable.
+  inAudits?: (p: string) => Promise<boolean>;
   // AgentOS's server and the tmux servers it runs sessions in.
   protectedPids: () => Promise<Set<number>>;
 }
@@ -319,6 +322,8 @@ const GIT_WRITES = new Set([
   "mv",
 ]);
 
+const READ_ONLY_STASH = new Set(["list", "show"]);
+
 async function gitRefusal(
   args: string[],
   ctx: ShellContext,
@@ -348,10 +353,13 @@ async function gitRefusal(
   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} would change ${dir}. ${why}` : null;
+  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;
 }
 
 // Commands whose every non-option argument is a file they change, and
@@ -372,6 +380,16 @@ const WRITES_ALL = new Set([
 ]);
 const WRITES_LAST = new Set(["cp", "ln", "install", "rsync", "ditto"]);
 
+// Whether this chmod mode adds an execute bit (or might: copying another
+// class's bits, or a mode it can't read).
+export function addsExecute(mode: string): boolean {
+  if (/^[0-7]{1,4}$/.test(mode)) return [...mode.slice(-3)].some((d) => +d & 1);
+  return mode.split(",").some((c) => {
+    const m = /^[ugoa]*([-+=])([rwxXst]*|[ugo])$/.exec(c);
+    return !m || (m[1] !== "-" && /[xXugo]/.test(m[2]));
+  });
+}
+
 function writtenFiles(inv: Invocation): string[] {
   const { name, args } = inv;
   const files = [...inv.cmd.writes];
@@ -550,6 +568,15 @@ export async function shellRefusal(
         if (has(cwd) && !f.startsWith("/")) continue;
         const r = await ctx.writeRefusal(path.resolve(cwd, f));
         if (r) return `Refused: ${inv.name} would write ${f}. ${r}`;
+        if (
+          inv.name === "chmod" &&
+          ctx.inAudits &&
+          (await ctx.inAudits(path.resolve(cwd, f))) &&
+          addsExecute(
+            inv.args.find((a) => !/^(-[RHLPfvhc]+|--.*)$/.test(a)) ?? ""
+          )
+        )
+          return `Refused: chmod would make ${f} executable. ~/.agent-os/audits holds reports, not programs.`;
       }
     }
   }

package/lib/orchestrator/write-guard.ts

@@ -18,7 +18,7 @@ import os from "os";
 import path from "path";
 import { db, type Session } from "../db";
 import { git, GitError } from "../git-exec";
-import { isSecretPath } from "../secret-paths";
+import { isOrchestratorSecretPath as isSecretPath } from "../secret-paths";
 import { WORKTREES_DIR } from "../worktrees";
 import { orchestratorDir } from "./home";
 import { LIMITS_FILE } from "./usage";
@@ -49,6 +49,11 @@ export interface WriteBounds {
   // Its own quick changes' worktrees (quick.ts): the one place in a
   // project it may write, everything else in `repos` still refused.
   quick?: string[];
+  // Its own Claude Code auto-memory folder (~/.claude/projects/<mangled
+  // cwd>/memory), as named, and the one `audits` folder in `state`: the only
+  // two places in a protected area it may write.
+  memory?: string[];
+  audits?: string;
 }
 
 // Wherever they are, files that configure what an agent, git or a
@@ -124,6 +129,21 @@ const within = (p: string, root: string) => {
   return a === b || a.startsWith(b === "/" ? b : b + "/");
 };
 
+// How Claude Code names a project's folder under ~/.claude/projects.
+export const mangleCwd = (cwd: string) => cwd.replace(/[^a-zA-Z0-9]/g, "-");
+
+// A folder that must sit exactly where its name says under `parent` (no
+// link in it or between leading elsewhere). Returns the roots a write may go
+// under, or none.
+async function plainRoot(dir: string, parent: string): Promise<string[]> {
+  const byName = path.join(
+    await physicalPath(parent),
+    path.relative(parent, dir)
+  );
+  const real = await physicalPath(dir);
+  return key(real) === key(byName) ? [byName, path.resolve(dir)] : [];
+}
+
 const expandHome = (p: string) => p.replace(/^~(?=$|\/)/, os.homedir());
 
 // Why a write to this path is refused, or null when it may go ahead. For a
@@ -145,6 +165,8 @@ export async function writeRefusal(
   let home: string[];
   let runs: string[];
   let quick: string[][];
+  let memory: string[];
+  let audits: string[];
   try {
     // Where it lands as written, and with `..` taken by name first, as a
     // tool that normalises the path before opening it would; and where it
@@ -168,6 +190,14 @@ export async function writeRefusal(
     ownDir = await both(bounds.ownDir);
     home = await both(bounds.home);
     quick = await Promise.all((bounds.quick ?? []).map(both));
+    memory = (
+      await Promise.all(
+        (bounds.memory ?? []).map((m) =>
+          plainRoot(m, path.join(bounds.home, ".claude", "projects"))
+        )
+      )
+    ).flat();
+    audits = bounds.audits ? await plainRoot(bounds.audits, bounds.state) : [];
   } catch (e) {
     return `Couldn't resolve ${filePath}: ${(e as Error).message}.`;
   }
@@ -178,27 +208,40 @@ export async function writeRefusal(
     const ownQuick = quick.find((q) => q.some((d) => within(target, d)));
     const holdsQuick = (r: string) =>
       !!ownQuick && ownQuick.some((d) => within(d, r));
-    const repo = repos.find((r) => within(target, r) && !holdsQuick(r));
+    const inAudits = audits.find((d) => within(target, d));
+    const holdsAudits = (r: string) =>
+      !!inAudits && within(inAudits, r) && !within(r, inAudits);
+    const repo = repos.find(
+      (r) => within(target, r) && !holdsQuick(r) && !holdsAudits(r)
+    );
     if (repo)
-      return `${filePath} is inside ${repo}, a project repository, task worktree or AgentOS itself. Change code there through a task (start_task), or for a small edit, in a quick change's worktree (quick_change), so its PR goes through the merge gates.`;
+      return `${key(filePath) === key(repo) ? repo : `${filePath} is inside ${repo}`} is a project repository, task worktree or AgentOS itself. Change code there through a task (start_task), or for a small edit, in a quick change's worktree (quick_change), so its PR goes through the merge gates.`;
     if (ownQuick && !shell && GIT_LAYOUT_FILE.test(target))
       return `${filePath} is part of a git repository's layout (HEAD, .git/, .gitattributes); git config can run programs, so orchestrators never write those.`;
     if (AGENTOS_TEMP.test(target))
       return `${filePath} is in a checkout AgentOS is reviewing or rebasing; orchestrators never write there.`;
     // Its folder, or a quick worktree (which sits in ~/.agent-os/worktrees):
     // AgentOS's state and the home's dot-folders hold it, but it's its own.
-    const own = ownDir.some((d) => within(target, d)) || !!ownQuick;
+    const own =
+      ownDir.some((d) => within(target, d)) || !!ownQuick || !!inAudits;
     if (state.some((d) => within(target, d)) && !own)
       return `${filePath} is in AgentOS's own state (${bounds.state}); you may write only in your folder, ${bounds.ownDir}.`;
     if (shell) continue;
     if (isSecretPath(target) || isSecretPath(filePath))
       return `${filePath} holds or guards secrets; orchestrators never write those.`;
     const runsIn = runs.find((r) => within(target, r));
+    // In its memory folder or audits, the rest of the path is what counts:
+    // the `.claude` and `.agent-os` above it are why it's allowed.
+    const inMemory = memory.find((d) => within(target, d));
+    const sub = inMemory ?? inAudits;
+    const rest = sub ? target.slice(sub.length) : null;
     if (
-      RUNS_CODE.test(target) ||
-      RUNS_CODE.test(filePath) ||
+      (rest === null
+        ? RUNS_CODE.test(target) || RUNS_CODE.test(filePath)
+        : RUNS_CODE.test(rest)) ||
       runsIn ||
       (!own &&
+        !inMemory &&
         home.some(
           (h) =>
             within(target, h) &&
@@ -235,8 +278,9 @@ export async function orchestratorWriteBounds(
     .all() as { dir: string }[];
   const dbPath = agentOsDbPath();
   const repos = projects.map((p) => expandHome(p.dir)).filter((d) => d !== "");
+  const cwd = expandHome(session.working_directory);
   return {
-    cwd: expandHome(session.working_directory),
+    cwd,
     home: os.homedir(),
     runs: [
       path.join(os.homedir(), "Library"),
@@ -248,6 +292,10 @@ export async function orchestratorWriteBounds(
       ...(process.env.PATH ?? "").split(":").filter((d) => d.startsWith("/")),
     ],
     ownDir: orchestratorDir(session.workspace_id ?? ""),
+    memory: [...new Set([cwd, await physicalPath(cwd)])].map((c) =>
+      path.join(os.homedir(), ".claude", "projects", mangleCwd(c), "memory")
+    ),
+    audits: path.join(os.homedir(), ".agent-os", "audits"),
     quick: quickWorktrees(session.id),
     state: path.join(os.homedir(), ".agent-os"),
     repos: [...repos, WORKTREES_DIR, process.cwd(), path.dirname(dbPath)],
@@ -344,6 +392,12 @@ async function commandRefusal(
       const state = await physicalPath(bounds.state);
       return within(real, state) && !within(real, own);
     },
+    inAudits: async (p) => {
+      const roots = bounds.audits
+        ? await plainRoot(bounds.audits, bounds.state)
+        : [];
+      return roots.some((r) => within(p, r));
+    },
     protectedPids,
   });
 }

package/lib/secret-paths.ts

@@ -7,3 +7,15 @@ export const SECRET_PATH =
   /(^|\/)\.env(\.[^/]*)?$|(^|\/)[^/]*(secret|credential|tokenvault|keychain)[^/]*(\/|$)|\.(pem|key|p12|pfx)$|(^|\/)(id_(rsa|dsa|ecdsa|ed25519)|\.npmrc|\.netrc|\.pgpass)$|(^|\/)\.(ssh|aws|azure|gnupg|kube|docker)(\/|$)|(^|\/)\.config\/(gh|gcloud|op)(\/|$)/i;
 
 export const isSecretPath = (p: string): boolean => SECRET_PATH.test(p);
+
+// What an orchestrator treats as secret: the same, except the committed
+// templates, matched on the whole file name (`.env.example.bak` is still an
+// env file) and only when no folder above them is a secret one.
+const ENV_TEMPLATES = new Set([".env.example", ".env.sample", ".env.template"]);
+
+export const isOrchestratorSecretPath = (p: string): boolean => {
+  if (!isSecretPath(p)) return false;
+  const i = p.lastIndexOf("/");
+  if (!ENV_TEMPLATES.has(p.slice(i + 1))) return true;
+  return i >= 0 && isSecretPath(`${p.slice(0, i)}/x`);
+};

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/lib/simulator/brief.ts

@@ -12,7 +12,7 @@ export function simulatorBrief(
     return "- The iOS simulator tools are not available on this machine; skip simulator checks and say so in the PR.";
   return [
     "- iOS simulator (optional; it never gates a PR or a build, and a failure is reported, not a blocker): `aos sim open` makes your own simulator and installs this worktree's build (run it with run_in_background, a cold build takes minutes; `aos sim status` shows where it is).",
-    '  Drive and check state with `aos sim snapshot -i` (accessibility tree with @refs, text, cheap), `aos sim click @e3`, `aos sim fill @e5 "text"`, `aos sim logs --last 2m`. Refs are only valid from the latest snapshot.',
+    '  Drive and check state with `aos sim snapshot -i` (accessibility tree with @refs, text, cheap), `aos sim click @e3`, `aos sim fill @e5 "text"`, `aos sim logs --last 2m`. Refs are only valid from the latest snapshot. Never click or type through Python (Quartz) or cliclick; `aos sim` is the only path and needs neither.',
     "  Every image you read stays in your context for every later turn, so screenshot only the final changed screens, and prefer `aos sim screenshot --region @e3` (one element from the latest snapshot) for a single row or banner. It prints two paths: read the `read:` one (reduced to 800px); attach the `full-size` file to the PR.",
     "  Screenshots are written outside the worktree: don't put them in commits or the PR body unless they belong there. `aos sim close` when you're done; it is closed for you when the task ends.",
   ].join("\n");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saadnvd1/agent-os",
-  "version": "0.3.653",
+  "version": "0.3.657",
   "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) => {