@saadnvd1/agent-os 0.3.678 → 0.3.684

package/lib/health/tick.ts

@@ -11,6 +11,7 @@ import { healthConfig, type HealthConfig } from "./config";
 import { runDetectors } from "./detectors";
 import { gatherFacts, liveBackgroundJobs } from "./facts";
 import { envTick, realEnv, type EnvDeps } from "./env/envTick";
+import { spinTick } from "./spin-tick";
 import { addNote } from "./notes";
 import { closeResolvedPieces } from "./pieces";
 import { deliver, deliverClosed, type RouteDeps, realRoute } from "./route";
@@ -43,9 +44,10 @@ export const MAX_WAKES = 2;
 // A wake that never came back (a restart cut it off) is given up on.
 export const WAKE_GIVE_UP_MS = 3 * MIN;
 
-// The checks the tick evaluates: piece-dup is raised where a piece starts.
+// The checks the tick evaluates: piece-dup is raised where a piece starts,
+// bg-spin by the process step (spin-tick.ts).
 export const TICK_CHECKS: readonly CheckId[] = CHECKS.filter(
-  (c) => c !== "piece-dup"
+  (c) => c !== "piece-dup" && c !== "bg-spin"
 );
 
 export interface TickDeps {
@@ -54,6 +56,8 @@ export interface TickDeps {
   watch: WatchDeps;
   route: RouteDeps;
   env: EnvDeps;
+  // Stops background jobs that spin (spin-tick.ts).
+  spin: (now: number) => Promise<void>;
   wake: typeof wake;
 }
 
@@ -63,6 +67,7 @@ export const realTick: TickDeps = {
   watch: { run: runClaude, usagePct: currentUsagePct },
   route: realRoute,
   env: realEnv,
+  spin: spinTick,
   wake,
 };
 
@@ -145,6 +150,9 @@ export function healthTick(
   closeResolvedPieces(now);
   leaveHeartbeat(now, liveBackgroundJobs());
   giveUpStale(now, deps);
+  void deps
+    .spin(now)
+    .catch((error) => console.error("[health] spin check:", error));
   void envTick(now, c, deps.env).catch((error) =>
     console.error("[health] environment failures:", error)
   );

package/lib/health/types.ts

@@ -14,6 +14,7 @@ export const CHECKS = [
   "load-red",
   "queue-held",
   "bg-quiet",
+  "bg-spin",
   "piece-dup",
   "restarts",
   "ci-slow",
@@ -26,6 +27,7 @@ export const AREA_OF: Record<CheckId, Area> = {
   "load-red": "scheduler",
   "queue-held": "scheduler",
   "bg-quiet": "tasks",
+  "bg-spin": "tasks",
   "piece-dup": "pipeline",
   restarts: "pipeline",
   "ci-slow": "pipeline",

package/lib/orchestrator/brief.ts

@@ -164,7 +164,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. ${full ? `The shell and your file writes are unchecked (Saad's decision, 2026-10-18: Orchestrator full access, switched in Settings → Workspaces): \`git push\`, \`gh pr merge\`, commits, \`stash\`, \`clean\`, edits in any project checkout or task worktree, AgentOS's own state, dotfiles, launch agents, .claude, CLAUDE.md, .mcp.json, hooks, \`sqlite3\` writes, \`aos sweep --arm\`, other workspaces' repositories. Use that to fix things directly instead of starting a task for every small job, but still prefer the tools for what they cover (they're scoped to this workspace and logged), and never use the shell to get around a hard line. One warning stays: never stop or restart AgentOS or its tmux; that ends every session it runs, this one included. If AgentOS itself needs a restart, \`ask_saad\`. Reading a secret file is allowed; its value is never printed, logged or sent off the machine. ` : `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. ${full ? `` : `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. ${full ? `You can read and write files anywhere (Read, Grep, Glob, Write, Edit, NotebookEdit); nothing is checked.` : `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. ${full ? `The shell and your file writes are unchecked (Saad's decision, 2026-10-18: Orchestrator full access, switched in Settings → Workspaces): \`git push\`, \`gh pr merge\`, commits, \`stash\`, \`clean\`, edits in any project checkout or task worktree, AgentOS's own state, dotfiles, launch agents, .claude, CLAUDE.md, .mcp.json, hooks, \`sqlite3\` writes, \`aos sweep --arm\`, other workspaces' repositories. Use that to fix things directly instead of starting a task for every small job, but still prefer the tools for what they cover (they're scoped to this workspace and logged), and never use the shell to get around a hard line. One warning stays: never stop or restart AgentOS or its tmux; that ends every session it runs, this one included. If AgentOS itself needs a restart, \`ask_saad\`. Reading a secret file is allowed; its value is never printed, logged or sent off the machine. ` : `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\`, \`pnpm 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. ${full ? `` : `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. ${full ? `You can read and write files anywhere (Read, Grep, Glob, Write, Edit, NotebookEdit); nothing is checked.` : `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/share/pdf.ts

@@ -6,6 +6,7 @@
  */
 
 import fs from "fs";
+import path from "path";
 import type { Browser, LaunchOptions } from "playwright";
 
 const IDLE_MS = 60_000;
@@ -32,13 +33,43 @@ h1,h2,h3,h4{break-after:avoid}
 img{max-width:100%;break-inside:avoid}
 `;
 
+/**
+ * Playwright's headless shell, which `playwright install
+ * chromium-headless-shell` puts beside the full Chromium (same cache folder,
+ * the revision the locked package names). Null when it isn't installed.
+ */
+export function headlessShellPath(chromiumExecutable: string): string | null {
+  // <cache>/chromium-<rev>/<platform>/...: the shell's folder has the same <rev>.
+  const m = /^(.*)[\\/]chromium-(\d+)[\\/]/.exec(chromiumExecutable);
+  if (!m) return null;
+  const folder = path.join(m[1], `chromium_headless_shell-${m[2]}`);
+  let platform: string | undefined;
+  try {
+    platform = fs
+      .readdirSync(folder)
+      .find((d) => d.startsWith("chrome-headless-shell-"));
+  } catch {
+    return null;
+  }
+  if (!platform) return null;
+  const exe = path.join(
+    folder,
+    platform,
+    process.platform === "win32"
+      ? "chrome-headless-shell.exe"
+      : "chrome-headless-shell"
+  );
+  return fs.existsSync(exe) ? exe : null;
+}
+
 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 full = chromium.executablePath();
+  const candidates = [headlessShellPath(full), full, ...CHROME_PATHS];
   const path = candidates.find((p) => p && fs.existsSync(p));
   found = path ? { executablePath: path, headless: true } : null;
   return found;

package/lib/tasks/setup.ts

@@ -20,8 +20,10 @@ const tail = (s: string, n: number) => (s.length > n ? `...${s.slice(-n)}` : s);
 export function setupOutcome(result: SetupResult | Error): TaskSetup {
   if (result instanceof Error)
     return { status: "failed", ms: null, error: redact(result.message) };
-  if (result.success)
-    return { status: "ok", ms: result.durationMs, error: null };
+  if (result.success) {
+    const warning = result.steps.find((s) => s.warning)?.warning;
+    return { status: "ok", ms: result.durationMs, error: warning ?? null };
+  }
   const failed = result.steps.filter((s) => !s.success);
   const last = failed[failed.length - 1];
   const error = last
@@ -31,6 +33,11 @@ export function setupOutcome(result: SetupResult | Error): TaskSetup {
 }
 
 export function setupNote(setup: TaskSetup): string {
+  if (setup.status === "ok" && setup.error)
+    return `
+
+---
+Note from AgentOS: ${setup.error}`;
   if (setup.status !== "failed") return "";
   return `
 

package/lib/worktree-deps/clone.ts

@@ -236,6 +236,16 @@ export async function cloneDeps(opts: {
 // not, and cloning it would hand the worktree missing dependencies. Other
 // package managers have no hidden lockfile to check, so they pass.
 export async function nodeModulesMatchLock(dir: string): Promise<boolean> {
+  // pnpm copies the lockfile it installed from into node_modules/.pnpm.
+  const pnpmLock = await fs.promises
+    .readFile(path.join(dir, "pnpm-lock.yaml"), "utf-8")
+    .catch(() => null);
+  if (pnpmLock !== null) {
+    const installed = await fs.promises
+      .readFile(path.join(dir, "node_modules", ".pnpm", "lock.yaml"), "utf-8")
+      .catch(() => null);
+    return installed === pnpmLock;
+  }
   const read = (file: string) =>
     fs.promises
       .readFile(file, "utf-8")

package/lib/worktree-deps/fastcopy.ts

@@ -22,7 +22,14 @@ export const STORE_ROOT = agentosHome("deps-store");
 
 // Files tools rewrite in place. A hardlink would carry the write back into
 // the store, so these are real copies in every worktree.
-export const MUTABLE_IN_MODULES = [".package-lock.json", ".cache", ".vite"];
+export const MUTABLE_IN_MODULES = [
+  ".package-lock.json",
+  ".modules.yaml",
+  ".pnpm/lock.yaml",
+  ".pnpm-workspace-state-v1.json",
+  ".cache",
+  ".vite",
+];
 
 const probed = new Map<string, boolean>();
 

package/lib/worktree-deps/index.ts

@@ -7,7 +7,7 @@ import { exec } from "child_process";
 import { promisify } from "util";
 import type { SetupResult } from "../env-setup";
 import { NO_FAST_COPY, cloneDeps } from "./clone";
-import { detectPackageManager, setupEnv } from "./install";
+import { detectPackageManager, setupEnv, shellCommand } from "./install";
 
 const execAsync = promisify(exec);
 
@@ -47,8 +47,8 @@ export async function runCommand(
 
 /**
  * Clone the main checkout's node_modules (or exactly agentos.json's `clone`
- * paths), or else install: the lockfile's frozen install first, then a
- * plain one.
+ * paths), or else install: the lockfile's frozen install first, then (for
+ * a project other than AgentOS) a plain one.
  */
 export async function bringDependencies(
   result: SetupResult,
@@ -81,20 +81,15 @@ export async function bringDependencies(
     return;
   }
 
-  let error: string | undefined;
-  for (const command of pm.installs) {
-    const run = await deps.run(command, worktreePath, envVars);
-    result.steps.push({
-      name: `Install dependencies (${pm.name})`,
-      command,
-      success: run.success,
-      output: [clone.reason && `Not cloned: ${clone.reason}`, run.output]
-        .filter(Boolean)
-        .join("\n"),
-      error: run.error,
-    });
-    if (run.success) return;
-    error = run.error;
-  }
-  if (error !== undefined) result.success = false;
+  const run = await deps.run(shellCommand(pm.install), worktreePath, envVars);
+  result.steps.push({
+    name: `Install dependencies (${pm.name})`,
+    command: pm.install,
+    success: run.success,
+    output: [clone.reason && `Not cloned: ${clone.reason}`, run.output]
+      .filter(Boolean)
+      .join("\n"),
+    error: run.error,
+  });
+  if (!run.success) result.success = false;
 }

package/lib/worktree-deps/install.ts

@@ -1,6 +1,8 @@
 /**
  * Installing a worktree's dependencies when they can't be cloned: the
- * lockfile's own frozen install first, then a plain install.
+ * lockfile's own frozen install, and nothing else. A plain install would
+ * resolve ranges to versions newer than the lockfile, so a lockfile that
+ * disagrees with package.json fails setup and the agent is told.
  */
 
 import * as fs from "fs";
@@ -8,8 +10,7 @@ import * as path from "path";
 
 export interface PackageManager {
   name: "bun" | "pnpm" | "yarn" | "npm";
-  // Tried in order until one succeeds: frozen to the lockfile, then plain.
-  installs: string[];
+  install: string;
 }
 
 // Each install includes devDependencies: the agent needs typecheck, tests
@@ -17,44 +18,29 @@ export interface PackageManager {
 const BY_LOCKFILE: Array<{ file: string; pm: PackageManager }> = [
   {
     file: "bun.lock",
-    pm: {
-      name: "bun",
-      installs: ["bun install --frozen-lockfile", "bun install"],
-    },
+    pm: { name: "bun", install: "bun install --frozen-lockfile" },
   },
   {
     file: "bun.lockb",
-    pm: {
-      name: "bun",
-      installs: ["bun install --frozen-lockfile", "bun install"],
-    },
+    pm: { name: "bun", install: "bun install --frozen-lockfile" },
   },
   {
     file: "pnpm-lock.yaml",
     pm: {
       name: "pnpm",
-      installs: [
-        "pnpm install --frozen-lockfile --prod=false",
-        "pnpm install --prod=false",
-      ],
+      install: "pnpm install --frozen-lockfile --prod=false",
     },
   },
   {
     file: "yarn.lock",
     pm: {
       name: "yarn",
-      installs: [
-        "yarn install --frozen-lockfile --production=false",
-        "yarn install --production=false",
-      ],
+      install: "yarn install --frozen-lockfile --production=false",
     },
   },
   {
     file: "package-lock.json",
-    pm: {
-      name: "npm",
-      installs: ["npm ci --include=dev", "npm install --include=dev"],
-    },
+    pm: { name: "npm", install: "npm ci --include=dev" },
   },
 ];
 
@@ -68,11 +54,18 @@ export function detectPackageManager(
   }
   if (fs.existsSync(path.join(projectPath, "package.json"))) {
     // No lockfile, so nothing to be frozen to.
-    return { name: "npm", installs: ["npm install --include=dev"] };
+    return { name: "npm", install: "npm install --include=dev" };
   }
   return null;
 }
 
+// pnpm may exist only as a corepack shim that was never enabled; the shell
+// defines `pnpm` through corepack when the command is missing.
+export function shellCommand(command: string): string {
+  if (!command.startsWith("pnpm ")) return command;
+  return `if ! command -v pnpm >/dev/null 2>&1; then pnpm() { COREPACK_ENABLE_DOWNLOAD_PROMPT=0 corepack pnpm "$@"; }; fi; ${command}`;
+}
+
 // What setup commands run under: the server's environment without the
 // settings that make an install skip devDependencies.
 export function setupEnv(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saadnvd1/agent-os",
-  "version": "0.3.678",
+  "version": "0.3.684",
   "description": "Self-hosted web UI for managing Claude Code sessions",
   "bin": {
     "agent-os": "scripts/agent-os"
@@ -24,29 +24,24 @@
     "tsconfig.json",
     "postcss.config.mjs",
     "tailwind.config.ts",
-    "package-lock.json",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
-    "predev": "node scripts/ensure-native.mjs && node scripts/gen-migrations-index.mjs",
+    "predev": "node scripts/check-native.mjs --rebuild && 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",
     "disk:dry-run": "tsx scripts/disk-dry-run.ts",
     "prebuild": "node scripts/gen-migrations-index.mjs",
     "build": "next build",
-    "prestart": "node scripts/ensure-native.mjs && node scripts/gen-migrations-index.mjs",
+    "prestart": "node scripts/check-native.mjs --rebuild && node scripts/gen-migrations-index.mjs",
     "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",
     "postinstall": "chmod +x node_modules/node-pty/prebuilds/*/spawn-helper 2>/dev/null || true",
     "prepare": "husky",
-    "tauri": "tauri",
-    "tauri:dev": "tauri dev",
-    "tauri:build": "tauri build",
-    "tauri:build:linux": "docker build -t agentos-linux -f src-tauri/Dockerfile.linux src-tauri && docker run --rm -v $(pwd)/src-tauri/target:/app/target agentos-linux",
     "prelint": "node scripts/gen-migrations-index.mjs",
     "lint": "eslint .",
     "format": "prettier --write .",
@@ -71,7 +66,7 @@
   "author": "Saad Naveed",
   "license": "MIT",
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "bugs": {
     "url": "https://github.com/saadnvd1/agent-os/issues"
@@ -155,15 +150,15 @@
     "serwist": "^9.5.7",
     "sonner": "^2.0.7",
     "tailwind-merge": "^3.4.0",
+    "unified": "^11.0.5",
     "valtio": "^2.3.0",
     "ws": "^8.19.0",
     "zod": "^4.6.5"
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4.1.18",
-    "@tauri-apps/api": "^2.12.1",
-    "@tauri-apps/cli": "^2.12.1",
     "@types/better-sqlite3": "^7.6.13",
+    "@types/hast": "^3.0.4",
     "@types/jsdom": "^30.0.0",
     "@types/mdast": "^4.0.4",
     "@types/node": "^20.19.27",
@@ -177,6 +172,7 @@
     "jsdom": "^30.1.2",
     "prettier": "^3.7.4",
     "prettier-plugin-tailwindcss": "^0.7.2",
+    "remark-parse": "^11.0.0",
     "sharp": "^0.35.5",
     "tailwindcss": "^4.1.18",
     "tsx": "^4.23.15",
@@ -184,8 +180,5 @@
     "typescript": "^5.9.3",
     "vitest": "^4.1.11"
   },
-  "overrides": {
-    "dompurify": "^3.4.16",
-    "postcss-selector-parser": "^7.1.6"
-  }
+  "packageManager": "pnpm@11.28.5+sha512.484563d30b4c2ad27cb48aa94ff2b302dbcebc8ff6bf28816c2589886e146ce7f76f354f3bc1a438e6f5e9768c302aa0a6f7add8232903cd4cf81426cbc14d9e"
 }

package/scripts/check-native.mjs

@@ -0,0 +1,86 @@
+// Proves the native modules work in a node_modules tree: open a SQLite
+// database with better-sqlite3 and spawn a pty with node-pty. Used before a
+// deploy swaps an install in, and by predev/prestart.
+//   node scripts/check-native.mjs [node_modules dir]   (default: this checkout's)
+//   --rebuild  on a Node ABI mismatch, run `pnpm rebuild` once and check again
+import { createRequire } from "module";
+import { execFileSync } from "child_process";
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const args = process.argv.slice(2);
+const rebuild = args.includes("--rebuild");
+const modules = path.resolve(
+  args.find((a) => !a.startsWith("--")) ?? path.join(here, "..", "node_modules")
+);
+
+async function sqlite(require) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "aos-native-"));
+  try {
+    const db = require("better-sqlite3")(path.join(dir, "check.db"));
+    db.exec("create table t (v text); insert into t values ('ok')");
+    const row = db.prepare("select v from t").get();
+    db.close();
+    if (row?.v !== "ok") throw new Error("better-sqlite3 read back nothing");
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+function pty(require) {
+  return new Promise((resolve, reject) => {
+    const p = require("node-pty").spawn("/bin/sh", ["-c", "echo pty-ok"], {});
+    let out = "";
+    const timer = setTimeout(() => {
+      p.kill();
+      reject(new Error("node-pty: no exit within 10s"));
+    }, 10_000);
+    p.onData((d) => (out += d));
+    p.onExit(({ exitCode }) => {
+      clearTimeout(timer);
+      if (exitCode === 0 && out.includes("pty-ok")) resolve();
+      else reject(new Error(`node-pty: exit ${exitCode}, output ${out}`));
+    });
+  });
+}
+
+async function failures() {
+  const require = createRequire(path.join(modules, "noop.js"));
+  const found = [];
+  for (const [name, run] of [
+    ["better-sqlite3", sqlite],
+    ["node-pty", pty],
+  ]) {
+    try {
+      await run(require);
+    } catch (err) {
+      found.push({ name, message: String(err?.message ?? err) });
+    }
+  }
+  return found;
+}
+
+let bad = await failures();
+if (
+  bad.length &&
+  rebuild &&
+  bad.some((b) => b.message.includes("NODE_MODULE_VERSION"))
+) {
+  const names = bad.map((b) => b.name);
+  console.log(`Rebuilding ${names.join(", ")} for Node ${process.version}...`);
+  execFileSync("pnpm", ["rebuild", ...names], {
+    cwd: path.dirname(modules),
+    stdio: "inherit",
+  });
+  bad = await failures();
+}
+if (bad.length) {
+  for (const b of bad)
+    console.error(`native check failed: ${b.name}: ${b.message}`);
+  process.exit(1);
+}
+console.log(`native modules ok (${modules})`);
+process.exit(0);

package/scripts/code-health/prepass.ts

@@ -142,11 +142,11 @@ async function prepass(args: string[]) {
   const steps: Record<Collector, () => string | void> = {
     deps: () => {
       const prod = JSON.parse(
-        run("npm", ["audit", "--omit=dev", "--json"], root) || "{}"
+        run("pnpm", ["audit", "--prod", "--json"], root) || "{}"
       );
-      const all = JSON.parse(run("npm", ["audit", "--json"], root) || "{}");
+      const all = JSON.parse(run("pnpm", ["audit", "--json"], root) || "{}");
       const outdated = JSON.parse(
-        run("npm", ["outdated", "--json"], root) || "{}"
+        run("pnpm", ["outdated", "--format", "json"], root) || "{}"
       );
       result.deps = {
         prod: summarizeNpmAudit(prod),

package/scripts/install-deps

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# Install this checkout's dependencies the one way AgentOS does: pnpm, frozen
+# to pnpm-lock.yaml, only the build scripts pnpm-workspace.yaml allows, then a
+# check that the native modules work and the PDF browser. For first installs
+# (setup, `agent-os install`); a running server's updates go through
+# scripts/redeploy, which installs beside the live tree.
+#   scripts/install-deps [--no-browser]
+set -euo pipefail
+cd "$(dirname "$0")/.."
+# shellcheck source=lib/pnpm.sh
+source scripts/lib/pnpm.sh
+
+if [ -s "$HOME/.nvm/nvm.sh" ]; then
+  # shellcheck disable=SC1091
+  source "$HOME/.nvm/nvm.sh" >/dev/null
+  nvm use >/dev/null
+fi
+use_pnpm
+
+# devDependencies are needed to build, even when the shell has NODE_ENV=production.
+unset NODE_ENV npm_config_production npm_config_omit
+pnpm install --frozen-lockfile
+node scripts/check-native.mjs
+[ "${1:-}" = "--no-browser" ] || install_pdf_browser

package/scripts/lib/commands.sh

@@ -43,7 +43,7 @@ cmd_install() {
 
     # Install dependencies
     log_info "Installing dependencies..."
-    npm install --include=dev --legacy-peer-deps
+    scripts/install-deps
 
     # Build for production
     log_info "Building for production..."
@@ -296,7 +296,7 @@ cmd_update() {
         git pull --ff-only
 
         log_info "Installing dependencies..."
-        npm install --include=dev --legacy-peer-deps
+        scripts/install-deps
 
         log_info "Rebuilding..."
         npm run build

package/scripts/lib/deps-swap.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# Install dependencies beside the live ones, prove the native modules work in
+# them, and only then swap them in. A deploy that brings a broken install
+# fails here, and the node_modules the running server reads is never touched.
+# The tree being replaced stays in .deps/prev for one rollback.
+# Sourced by scripts/redeploy; run from the repository root, after use_pnpm.
+# Test hooks: AGENTOS_INSTALL_CMD (default `pnpm install --frozen-lockfile`),
+# AGENTOS_NATIVE_CHECK (default `node scripts/check-native.mjs <dir>`).
+
+DEPS=.deps
+STAGE=$DEPS/stage
+PREV=$DEPS/prev
+STAMP=.agentos-deps
+
+# What an install depends on. A new Node or CPU rebuilds the native modules.
+deps_stamp() {
+  {
+    cat package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc 2>/dev/null
+    node -p 'process.version + process.platform + process.arch'
+  } | shasum -a 256 | cut -d' ' -f1
+}
+
+# 0 and a staged tree to swap in, or 10 when the live install is already
+# right, or 1 with the live tree untouched.
+install_beside() {
+  local stamp
+  stamp=$(deps_stamp)
+  if [ -d node_modules ] && [ "$(cat "node_modules/$STAMP" 2>/dev/null)" = "$stamp" ]; then
+    echo "Dependencies unchanged."
+    # The last build ran on these same dependencies, so a rollback has
+    # nothing to put back.
+    rm -rf "$PREV"
+    return 10
+  fi
+  rm -rf "$STAGE"
+  mkdir -p "$STAGE"
+  cp package.json pnpm-lock.yaml pnpm-workspace.yaml "$STAGE/"
+  [ -f .npmrc ] && cp .npmrc "$STAGE/"
+  # HUSKY=0: the staged copy is not a git checkout.
+  if ! (cd "$STAGE" && HUSKY=0 bash -c "${AGENTOS_INSTALL_CMD:-pnpm install --frozen-lockfile}"); then
+    rm -rf "$STAGE"
+    echo "Install failed; the live node_modules is untouched." >&2
+    return 1
+  fi
+  if ! bash -c "${AGENTOS_NATIVE_CHECK:-node scripts/check-native.mjs \"\$1\"}" _ "$STAGE/node_modules"; then
+    rm -rf "$STAGE"
+    echo "Native modules do not load in the new install; the live node_modules is untouched." >&2
+    return 1
+  fi
+  echo "$stamp" > "$STAGE/node_modules/$STAMP"
+}
+
+swap_deps() {
+  [ -d "$STAGE/node_modules" ] || { echo "no checked install to swap in" >&2; return 1; }
+  rm -rf "$PREV"
+  mkdir -p "$DEPS"
+  [ -d node_modules ] && mv node_modules "$PREV"
+  mv "$STAGE/node_modules" node_modules
+  rm -rf "$STAGE"
+}
+
+# Put the node_modules from before the last swap back (a failed build, or
+# `redeploy --rollback`); the current one is dropped.
+restore_deps() {
+  [ -d "$PREV" ] || return 0
+  rm -rf node_modules
+  mv "$PREV" node_modules
+}