owlmem 0.4.1 → 0.7.0

package/README.md

@@ -2,6 +2,63 @@
 
 Command line for [OwlMem](https://owlmem.com) — shared memory and an end-to-end encrypted vault for your AI agents.
 
+## Connect your AI apps
+
+```sh
+npx -y owlmem install
+```
+
+Finds Claude Code, Codex, Cursor, VS Code, Windsurf, Gemini CLI and Claude Desktop on this computer and adds
+OwlMem (`https://mcp.owlmem.com/mcp`) to each one. Config files are merged, not overwritten, and every file it
+changes is backed up first (`<file>.bak-owlmem-<time>`). It also adds a short "Team memory" rules block to
+`~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md` and `~/.gemini/GEMINI.md` (between `<!-- owlmem:start -->` markers).
+
+| Option | |
+|---|---|
+| `--dry-run` | show the plan, change nothing |
+| `--yes` | don't ask (when stdin isn't a terminal — an AI running it — it never asks) |
+| `--only claude-code,cursor` | only these apps (`claude-code`, `codex`, `cursor`, `vscode`, `vscode-insiders`, `windsurf`, `gemini`, `claude-desktop`) |
+| `--no-rules` | leave the instruction files alone |
+| `--wake` / `--no-wake` | turn on auto-wake (below) without asking / don't ask about it |
+| `--uninstall` | remove the OwlMem entries and rules block again, and auto-wake |
+
+Signing in is done by each app (standard MCP OAuth): the first time it uses OwlMem it opens the owlmem.com
+page, where you sign in and click **Allow**. AI agents can read the setup guide at https://mcp.owlmem.com.
+
+## Auto-wake
+
+An AI on your computer normally sees a task only when someone opens it. Auto-wake starts it as soon as it gets one:
+a small background program long-polls OwlMem and runs that AI's command line unattended — Claude Code with
+`claude -p`, Codex with `codex exec` — with the task as the prompt. The AI marks the task done or declined as usual.
+
+```sh
+npx -y owlmem install --wake     # or answer "y" when install asks; --yes alone leaves it off
+npx -y owlmem wake enable        # on its own (options: --boot, --max N, --timeout MIN, --again)
+npx -y owlmem wake status
+npx -y owlmem wake disable       # also done by npx -y owlmem uninstall
+```
+
+- **Pairing.** `wake enable` prints a link: open it, check the code matches, and pick which AI each app on this
+  computer is. Until then nothing starts. The computer is identified by its device key (next to `config.json`).
+- **Runs as you.** A systemd user service (Linux), a LaunchAgent (macOS) or a logon task (Windows) — this user
+  only, no admin rights. `--boot` (Linux) turns on lingering so it runs from boot, not just from login.
+- **One program per computer** for every paired AI. One task at a time per AI, at most 2 at once (`--max`),
+  30 minutes per task (`--timeout`); a task that runs out of time is stopped and marked declined for a person.
+  A task sent to every agent wakes just one.
+- **Working folder.** A line like `cwd: ~/Projects/app` in the task picks the folder. In a Git repository the AI
+  gets its own worktree and branch (`owlmem/task-<id>`), commits there and doesn't merge — the result names the
+  branch. Other folders take one task at a time; with no folder it works in an empty one.
+- **Safety.** The AI uses its own OwlMem connection and the permissions it always has: no `--dangerously-*` flags.
+  Claude Code is only additionally allowed the two OwlMem tools it needs to report back (`kb_task_update`,
+  `kb_inbox`). Anything that needs a person — an approval, a sign-in, a code — it declines, saying what to do.
+  It is told never to put secrets in its result.
+- **Turning it off.** Each AI has an auto-wake switch in the console (AI agents → Agents), where you can also remove
+  the computer. When the computer is removed, the AI is disconnected or the account is gone, the program gets a 401,
+  removes its own autostart entry and exits. The command for each app is in `~/.config/owlmem/wake/wake.json`;
+  logs and worktrees stay in that folder after uninstalling.
+
+## Vault
+
 ```sh
 npx owlmem login            # paste the agent's token from the OwlMem console
 npx owlmem vault unlock     # paste your recovery code, once per machine
@@ -13,6 +70,13 @@ npx owlmem vault import bitwarden_export.json   # also 1Password / KeePass CSV,
 Vault items are encrypted on your machine with a key only you hold; OwlMem stores ciphertext it cannot read.
 Every read or write needs the space owner's approval in the console (passkey, authenticator app or GitHub).
 
+For unattended jobs (scheduled tasks, overnight deploys) the owner can set a **standing grant**: one agent, on one machine,
+may read chosen items or a folder without asking each time, until a set date (90 days at most), optionally only during set hours.
+Run `npx owlmem device` on that machine to register it and print its fingerprint. The program signs every vault request with a
+device key kept next to its config, so the same token on another machine gets nothing. By default a standing grant covers
+`owlmem run` / `vault_run` only (the secret goes into a command); viewing in plain text must be allowed separately.
+Saving, deleting and exporting always need approval.
+
 Let your AI use the vault directly through a local MCP server:
 
 ```sh
@@ -22,3 +86,6 @@ claude mcp add owlmem-vault -- npx -y owlmem mcp
 Tools: `vault_list`, `vault_run` (secrets are injected into the command and masked in its output), `vault_get`, `vault_put`.
 
 Requires Node 18+. No dependencies.
+
+`owlmem vault unlock` opens your browser only when talking to owlmem.com; set `OWLMEM_NO_BROWSER=1` (or `BROWSER=none`)
+to just print the link instead.

package/owlmem.mjs

@@ -5,6 +5,10 @@
 // server only ever sees ciphertext. Your space key comes from the recovery code shown once when the vault
 // was set up in the console; `owlmem vault unlock` stores it on this machine (0600).
 //
+//   owlmem install [--dry-run] [--yes] [--only a,b] [--no-rules] [--wake] [--uninstall]
+//                                        connect Claude Code, Codex, Cursor, VS Code, Windsurf, Gemini CLI and
+//                                        Claude Desktop on this computer to OwlMem (npx -y owlmem install)
+//   owlmem wake enable|disable|status    auto-wake: start the AI on this computer when it gets a task (runs from login)
 //   owlmem login                         save this agent's token (from the console)
 //   owlmem vault unlock                  paste the recovery code once per machine
 //   owlmem vault ls
@@ -15,19 +19,27 @@
 //   owlmem vault export [--format bitwarden-json|keepass-csv|env] > file
 //   owlmem run --env VAR=<name>[:field] [...] -- <command> [args]   run a command with secrets in its environment
 //   owlmem vault keygen                  (setup without a browser) print a new recovery code and its key check
+//   owlmem device                        register this machine and show its fingerprint (for standing grants)
 //   owlmem mcp                           local MCP server for your AI (vault_list, vault_run, vault_get, vault_put)
 //                                        e.g. claude mcp add owlmem-vault -- node ~/owlmem.mjs mcp
 //
 // Reading, writing, deleting and exporting need the space owner's approval in the console; this program waits
 // for it (up to 5 minutes). Secrets go to stdout only; messages go to stderr.
+//
+// Standing grants (for unattended jobs): the owner can let one agent, on one machine, read chosen items without
+// asking each time — until a set date, optionally only during set hours. This program signs every vault request
+// with a device key kept on this machine (device.json next to config.json), and says whether the secret goes into a
+// command (`owlmem run`, vault_run) or is shown (`vault get`, vault_get). A token copied to another machine has no
+// device key there, so standing grants don't apply. Writing, deleting and exporting always need approval.
 
 import { webcrypto as crypto } from "node:crypto";
-import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync } from "node:fs";
-import { homedir } from "node:os";
-import { join, dirname } from "node:path";
-import { spawn } from "node:child_process";
+import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync, copyFileSync, rmSync, statSync, realpathSync, openSync, closeSync, appendFileSync } from "node:fs";
+import { homedir, hostname, userInfo } from "node:os";
+import { join, dirname, basename, relative, isAbsolute } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn, spawnSync } from "node:child_process";
 
-export const VERSION = "0.4.1";
+export const VERSION = "0.7.0";
 const BASE = (process.env.OWLMEM_URL || "https://owlmem.com").replace(/\/$/, "");
 const DIR = process.env.OWLMEM_HOME || join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "owlmem");
 const enc = new TextEncoder(), dec = new TextDecoder();
@@ -169,11 +181,43 @@ function spaceKey(space) {
   return unb64(readFileSync(p, "utf8").trim());
 }
 
+// ── this machine's device key (standing grants are bound to it) ──
+// ECDSA P-256, made on first use, kept next to config.json (0600). The server only ever sees the public key and signatures.
+let DEVICE = null;
+async function device() {
+  if (DEVICE) return DEVICE;
+  const p = join(DIR, "device.json");
+  let d = null;
+  try { d = JSON.parse(readFileSync(p, "utf8")); } catch {}
+  if (!d || !d.pkcs8 || !d.spki) {
+    const kp = await crypto.subtle.generateKey({ name: "ECDSA", namedCurve: "P-256" }, true, ["sign", "verify"]);
+    d = { v: 1, spki: b64url(new Uint8Array(await crypto.subtle.exportKey("spki", kp.publicKey))), pkcs8: b64(new Uint8Array(await crypto.subtle.exportKey("pkcs8", kp.privateKey))), created: new Date().toISOString() };
+    saveFile(p, JSON.stringify(d, null, 2));
+  }
+  const key = await crypto.subtle.importKey("pkcs8", unb64(d.pkcs8), { name: "ECDSA", namedCurve: "P-256" }, false, ["sign"]);
+  return (DEVICE = { spki: d.spki, key });
+}
+export async function deviceFingerprint(spki) {
+  const h = [...new Uint8Array(await crypto.subtle.digest("SHA-256", unb64(spki.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat((4 - spki.length % 4) % 4))))].map((x) => x.toString(16).padStart(2, "0")).join("").slice(0, 16).toUpperCase();
+  return h.match(/.{4}/g).join("-");
+}
+// mode: "run" = the secret goes into a command; "view" = it is shown (stdout / the AI's conversation); "other" = anything else
+// url: the full request URL (only its path is signed)
+async function signHeaders(method, url, mode) {
+  const d = await device();
+  const ts = String(Math.floor(Date.now() / 1000)), nonce = b64url(crypto.getRandomValues(new Uint8Array(18)));
+  const msg = ["owlmem-device-v1", method.toUpperCase(), new URL(url).pathname, mode, ts, nonce].join("\n");
+  const sig = new Uint8Array(await crypto.subtle.sign({ name: "ECDSA", hash: "SHA-256" }, d.key, enc.encode(msg)));
+  return { "X-OwlMem-Device": d.spki, "X-OwlMem-Device-Name": (process.env.OWLMEM_DEVICE_NAME || hostname()).replace(/[^\w .@()-]/g, "").slice(0, 60),
+           "X-OwlMem-Mode": mode, "X-OwlMem-Time": ts, "X-OwlMem-Nonce": nonce, "X-OwlMem-Sig": b64url(sig) };
+}
+
 // ── http ──
-async function call(method, path, body) {
+async function call(method, path, body, mode = "other") {
   let r;
   try {
-    r = await fetch(BASE + "/v1/vault/" + path, { method, headers: { Authorization: "Bearer " + token(), "Content-Type": "application/json", "User-Agent": "owlmem-cli/" + VERSION },
+    const sh = await signHeaders(method, BASE + "/v1/vault/" + path, mode).catch(() => ({}));      // can't write the device key: no standing grants, everything else still works
+    r = await fetch(BASE + "/v1/vault/" + path, { method, headers: { Authorization: "Bearer " + token(), "Content-Type": "application/json", "User-Agent": "owlmem-cli/" + VERSION, ...sh },
                                                   body: body === undefined ? undefined : JSON.stringify(body) });
   } catch (e) { throw new Fail("Can't reach OwlMem (" + BASE + "): " + e.message); }
   const data = await r.json().catch(() => ({}));
@@ -181,10 +225,10 @@ async function call(method, path, body) {
 }
 // Ask, and if the owner has to approve, wait for it (polling every 3 s, up to 5 minutes), then ask again.
 let WAIT_MS = 5 * 60 * 1000;     // 命令行等 5 分钟；MCP 里只等 30 秒，免得 AI 客户端的工具调用超时
-async function approved(method, path, body, kind = "access") {
+async function approved(method, path, body, kind = "access", mode = "other") {
   let extra = "";
   for (let round = 0; round < 3; round++) {
-    const r = await call(method, path + extra, body);
+    const r = await call(method, path + extra, body, mode);
     if (r.status < 400) return r.data;
     if (r.data.error !== "approval_required") throw new Fail(r.data.detail || r.data.error || "HTTP " + r.status);
     const id = r.data.request;
@@ -196,7 +240,7 @@ async function approved(method, path, body, kind = "access") {
       st = (await call("GET", "requests/" + id)).data.status;
       if (st !== "pending") break;
     }
-    if (st === "pending") throw new Fail(`Waiting for approval (request ${id}). Ask the space owner to approve it in the OwlMem console (Vault), then try again.`);
+    if (st === "pending") throw new Fail(`Waiting for approval (request ${id}). Ask the space owner to approve it in the OwlMem console (Vault), then try again. For unattended jobs, ask them for a standing grant for this agent and this machine (run: owlmem device).`);
     if (st !== "approved") throw new Fail(st === "denied" ? "The request was denied." : "The request expired before it was approved.");
     say("Approved.");
     if (kind !== "access") extra = (path.includes("?") ? "&" : "?") + "request=" + encodeURIComponent(id);
@@ -311,6 +355,21 @@ export function guessCSV(text) {
 }
 // <<< vault core
 
+// ── opening a browser ──
+// Only for the real service: OWLMEM_NO_BROWSER=1 or BROWSER=none turns it off, and so does any OWLMEM_URL that isn't owlmem.com
+// (tests and local previews run on 127.0.0.1 — 10-24 a test run kept opening tabs in the owner's browser). The link is always printed.
+export function browserAllowed(env = process.env) {
+  if (env.OWLMEM_NO_BROWSER && env.OWLMEM_NO_BROWSER !== "0") return false;
+  if (String(env.BROWSER || "").toLowerCase() === "none") return false;
+  let host = "";
+  try { const u = new URL(env.OWLMEM_URL || "https://owlmem.com"); if (u.protocol !== "https:") return false; host = u.hostname; } catch { return false; }
+  return host === "owlmem.com" || host.endsWith(".owlmem.com");
+}
+function openBrowser(url) {
+  if (!browserAllowed()) return false;
+  try { spawn(process.platform === "darwin" ? "open" : process.platform === "win32" ? "explorer" : "xdg-open", [url], { stdio: "ignore", detached: true }).on("error", () => {}).unref(); return true; } catch { return false; }
+}
+
 // ── unlock via the console ──
 async function unlockInBrowser(space) {
   const kp = await unlockKeypair();
@@ -318,7 +377,7 @@ async function unlockInBrowser(space) {
   if (r.status >= 400) throw new Fail(r.data.detail || r.data.error);
   const fp = await unlockFingerprint(kp.pubkey);
   say("Open this link, sign in, and approve with your passkey:\n\n  " + r.data.url + "\n\nThe console will show a code — check it matches: " + fp + "\nWaiting (up to 10 minutes)…");
-  try { spawn(process.platform === "darwin" ? "open" : process.platform === "win32" ? "explorer" : "xdg-open", [r.data.url], { stdio: "ignore", detached: true }).on("error", () => {}).unref(); } catch {}
+  openBrowser(r.data.url);
   const wait = Number(process.env.OWLMEM_POLL_MS || 2000), until = Date.now() + 10 * 60 * 1000;
   while (Date.now() < until) {
     await new Promise((res) => setTimeout(res, wait));
@@ -350,9 +409,9 @@ function ask(question, hidden = true) {
 
 // ── commands ──
 function flag(args, name, dflt) { const i = args.indexOf(name); if (i < 0) return dflt; const v = args[i + 1]; args.splice(i, 2); return v; }
-async function fetchItem(name) {
+async function fetchItem(name, mode = "view") {
   const sp = await space(); const raw = spaceKey(sp.space);
-  const it = await approved("GET", itemPath(name));
+  const it = await approved("GET", itemPath(name), undefined, "access", mode);
   return open(raw, sp.space, name, it.nonce, it.ciphertext);
 }
 function pick(body, field) {
@@ -366,7 +425,7 @@ function pick(body, field) {
 const MCP_TOOLS = [
   { name: "vault_list", description: "List the credentials in the team vault (names and descriptions only; no secrets).", inputSchema: { type: "object", properties: {} } },
   { name: "vault_run",
-    description: "PREFERRED way to use a secret: run a shell command with vault items injected as environment variables. The secret values are masked as **** in the output returned to you, so they never enter the conversation. Needs the space owner's approval in the OwlMem console the first time (then 15 min – 2 h).",
+    description: "PREFERRED way to use a secret: run a shell command with vault items injected as environment variables. The secret values are masked as **** in the output returned to you, so they never enter the conversation. Needs the space owner's approval in the OwlMem console the first time (then 15 min – 2 h), unless they set a standing grant for you on this machine — standing grants cover vault_run only (not vault_get) unless the owner also allowed viewing.",
     inputSchema: { type: "object", properties: {
       command: { type: "string", description: "Shell command to run (sh -c)" },
       env: { type: "object", description: 'Map of ENV_VAR to "item" or "item:field", e.g. {"DB_PASSWORD": "prod/db:password"}', additionalProperties: { type: "string" } },
@@ -396,7 +455,7 @@ async function mcpCall(name, a) {
     for (const [k, ref] of Object.entries(a.env || {})) {
       if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(k)) throw new Fail("Bad variable name " + k);
       const [item, field] = String(ref).split(":");
-      const v = pick(await fetchItem(item), field); env[k] = v; if (v && v.length >= 4) secrets.push(v);
+      const v = pick(await fetchItem(item, "run"), field); env[k] = v; if (v && v.length >= 4) secrets.push(v);
     }
     const mask = (t) => secrets.sort((x, y) => y.length - x.length).reduce((acc, v) => acc.split(v).join("****"), t);
     const out = await new Promise((res) => {
@@ -434,10 +493,739 @@ async function mcpServe() {
   await new Promise((res) => process.stdin.on("end", res));
 }
 
+// ── install: connect the AI apps on this machine to OwlMem's MCP server ──
+// The snippets here must say the same as the website (design/owlmem/site.py CODE); tests/test_owlmem_install.py compares them.
+export const MCP_URL = "https://mcp.owlmem.com/mcp";
+export const RULES = `## Team memory (OwlMem)
+- Before starting a task, use kb_search (documents) and kb_recall (facts) for the topic.
+- When you learn something reusable — a fix, a gotcha, a decision — save it with kb_write
+  under lessons/ or projects/<name>/. Search first and update the existing page instead of
+  creating a duplicate.
+- Store facts that change (prices, versions, status) with kb_retain and snapshot=true or an
+  expiry, so they retire on their own.
+- Never put passwords or API keys in documents or memory. Use the OwlMem vault.`;
+const MARK_START = "<!-- owlmem:start -->", MARK_END = "<!-- owlmem:end -->";
+const DOCS = "https://owlmem.com/docs#";
+// What each app's config file gets under its servers key (same shapes as on owlmem.com/docs)
+export const ENTRIES = {
+  cursor: { url: MCP_URL },
+  vscode: { type: "http", url: MCP_URL },
+  windsurf: { serverUrl: MCP_URL },
+  gemini: { httpUrl: MCP_URL },
+  "claude-desktop": { command: "npx", args: ["-y", "mcp-remote", MCP_URL] },
+};
+export const CLAUDE_ADD = ["mcp", "add", "--transport", "http", "--scope", "user", "owlmem", MCP_URL];
+export const CODEX_TOML = `[mcp_servers.owlmem]\nurl = "${MCP_URL}"`;
+
+function onPath(name) {
+  const exts = process.platform === "win32" ? ["", ".cmd", ".exe", ".bat"] : [""];
+  for (const d of (process.env.PATH || "").split(process.platform === "win32" ? ";" : ":")) {
+    if (!d) continue;
+    for (const e of exts) { const p = join(d, name + e); if (existsSync(p)) return p; }
+  }
+  return null;
+}
+function home() { return process.env.HOME || process.env.USERPROFILE || homedir(); }
+function platform() { return process.env.OWLMEM_PLATFORM || process.platform; }     // OWLMEM_PLATFORM: tests only
+function appData() {     // per-user application data folder (VS Code, Claude Desktop)
+  const p = platform(), h = home();
+  if (p === "darwin") return join(h, "Library", "Application Support");
+  if (p === "win32") return process.env.APPDATA || join(h, "AppData", "Roaming");
+  return process.env.XDG_CONFIG_HOME || join(h, ".config");
+}
+const readText = (f) => { try { return readFileSync(f, "utf8"); } catch { return null; } };
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+
+// Client table. detect(): is this app on this machine? Each plan returns {state, ops, note}.
+//   state: "ok" (already set up) | "add" | "update" | "remove" | "absent" (nothing to remove) | "fail"
+//   ops: [{type:"write", file, text} | {type:"run", argv}]
+function jsonClient(id, name, file, key, entry) {
+  return { id, name, file, key, entry, docs: DOCS + ({ windsurf: "others", gemini: "others", "claude-desktop": "claude" }[id] || id) };
+}
+export function clients() {
+  const h = home(), ad = appData();
+  const codexHome = process.env.CODEX_HOME || join(h, ".codex");
+  const list = [
+    { id: "claude-code", name: "Claude Code", docs: DOCS + "claude-code", rules: join(process.env.CLAUDE_CONFIG_DIR || join(h, ".claude"), "CLAUDE.md"),
+      detect: () => !!onPath("claude") },
+    { id: "codex", name: "Codex", docs: DOCS + "codex", file: join(codexHome, "config.toml"), rules: join(codexHome, "AGENTS.md"),
+      detect: () => !!onPath("codex") || existsSync(codexHome) },
+    Object.assign(jsonClient("cursor", "Cursor", join(h, ".cursor", "mcp.json"), "mcpServers", ENTRIES.cursor),
+      { detect: () => existsSync(join(h, ".cursor")) || !!onPath("cursor") }),
+    Object.assign(jsonClient("vscode", "VS Code", join(ad, "Code", "User", "mcp.json"), "servers", ENTRIES.vscode),
+      { detect: () => existsSync(join(ad, "Code", "User")) }),
+    Object.assign(jsonClient("vscode-insiders", "VS Code Insiders", join(ad, "Code - Insiders", "User", "mcp.json"), "servers", ENTRIES.vscode),
+      { detect: () => existsSync(join(ad, "Code - Insiders", "User")), docs: DOCS + "vscode", optional: true }),
+    Object.assign(jsonClient("windsurf", "Windsurf", join(h, ".codeium", "windsurf", "mcp_config.json"), "mcpServers", ENTRIES.windsurf),
+      { detect: () => existsSync(join(h, ".codeium", "windsurf")) }),
+    Object.assign(jsonClient("gemini", "Gemini CLI", join(h, ".gemini", "settings.json"), "mcpServers", ENTRIES.gemini),
+      { detect: () => existsSync(join(h, ".gemini")) || !!onPath("gemini"), rules: join(h, ".gemini", "GEMINI.md") }),
+    Object.assign(jsonClient("claude-desktop", "Claude Desktop", join(ad, "Claude", "claude_desktop_config.json"), "mcpServers", ENTRIES["claude-desktop"]),
+      { detect: () => existsSync(join(ad, "Claude")) }),
+  ];
+  return list;
+}
+export const CLIENT_IDS = ["claude-code", "codex", "cursor", "vscode", "vscode-insiders", "windsurf", "gemini", "claude-desktop"];
+
+function planJSON(c, uninstall) {
+  const text = readText(c.file);
+  let obj = {};
+  if (text !== null && text.trim()) {
+    try { obj = JSON.parse(text); } catch {
+      const hint = /\/\/|\/\*/.test(text) ? "it has comments or isn't plain JSON" : "it isn't valid JSON";
+      return { state: "fail", ops: [], note: `${c.file}: ${hint}, so it was left alone. Add OwlMem by hand: ${c.docs}` };
+    }
+    if (!obj || typeof obj !== "object" || Array.isArray(obj)) return { state: "fail", ops: [], note: `${c.file}: unexpected content, left alone. Add OwlMem by hand: ${c.docs}` };
+  }
+  const servers = obj[c.key] && typeof obj[c.key] === "object" && !Array.isArray(obj[c.key]) ? obj[c.key] : null;
+  const cur = servers ? servers.owlmem : undefined;
+  if (uninstall) {
+    if (cur === undefined) return { state: "absent", ops: [] };
+    const next = { ...obj, [c.key]: { ...servers } }; delete next[c.key].owlmem;
+    return { state: "remove", ops: [{ type: "write", file: c.file, text: JSON.stringify(next, null, 2) + "\n" }] };
+  }
+  if (same(cur, c.entry)) return { state: "ok", ops: [] };
+  const next = { ...obj, [c.key]: { ...(servers || {}), owlmem: c.entry } };
+  return { state: cur === undefined ? "add" : "update", ops: [{ type: "write", file: c.file, text: JSON.stringify(next, null, 2) + "\n" }],
+           note: cur === undefined ? "" : "replaced the existing owlmem entry " + JSON.stringify(cur) };
+}
+
+// Codex: ~/.codex/config.toml. Only the [mcp_servers.owlmem] table (and its sub-tables) is touched; everything else is kept as is.
+export function tomlSplit(text) {
+  const rest = [], section = []; let mine = false;
+  for (const l of text.split("\n")) {
+    if (/^\s*\[\[/.test(l)) mine = false;
+    else { const m = /^\s*\[\s*([^\]]+?)\s*\]\s*(#.*)?$/.exec(l); if (m) { const n = m[1].replace(/["'\s]/g, ""); mine = n === "mcp_servers.owlmem" || n.startsWith("mcp_servers.owlmem."); } }
+    (mine ? section : rest).push(l);
+  }
+  return { rest: rest.join("\n").replace(/\n{3,}/g, "\n\n").replace(/\s+$/, ""), section: section.join("\n").trim(), found: section.length > 0 };
+}
+function planCodex(c, uninstall) {
+  const text = readText(c.file) ?? "";
+  if (/^\s*mcp_servers\s*[.=]|^\s*owlmem\s*=\s*\{/m.test(text))
+    return { state: "fail", ops: [], note: `${c.file} defines MCP servers in a form this installer doesn't edit; left alone. Add OwlMem by hand: ${c.docs}` };
+  const { rest, section, found } = tomlSplit(text);
+  if (uninstall) return found ? { state: "remove", ops: [{ type: "write", file: c.file, text: rest ? rest + "\n" : "" }] } : { state: "absent", ops: [] };
+  const norm = (s) => s.split("\n").map((l) => l.trim()).filter((l) => l && !l.startsWith("#")).join("\n");
+  if (found && norm(section) === norm(CODEX_TOML)) return { state: "ok", ops: [] };
+  return { state: found ? "update" : "add", ops: [{ type: "write", file: c.file, text: (rest ? rest + "\n\n" : "") + CODEX_TOML + "\n" }],
+           note: found ? "replaced the existing [mcp_servers.owlmem] table" : "" };
+}
+
+// Claude Code: through its own command (`claude mcp add … --scope user`); ~/.claude.json tells us what is there already.
+function planClaude(c, uninstall) {
+  let cur;
+  try { cur = (JSON.parse(readText(join(home(), ".claude.json")) || "{}").mcpServers || {}).owlmem; } catch { cur = undefined; }
+  const rm = { type: "run", argv: ["claude", "mcp", "remove", "owlmem", "--scope", "user"], ignoreFail: !uninstall };
+  if (uninstall) return cur === undefined ? { state: "absent", ops: [] } : { state: "remove", ops: [rm] };
+  if (cur && cur.url === MCP_URL && (cur.type === "http" || cur.type === "streamable-http") && !cur.headers) return { state: "ok", ops: [] };
+  return { state: cur === undefined ? "add" : "update", ops: [...(cur === undefined ? [] : [rm]), { type: "run", argv: ["claude", ...CLAUDE_ADD], retryWith: rm }],
+           note: cur === undefined ? "" : "replaced the existing owlmem server " + JSON.stringify(cur) };
+}
+
+export function withRules(text, uninstall) {
+  const t = text ?? "";
+  const re = new RegExp("\\n*" + MARK_START + "[\\s\\S]*?" + MARK_END + "\\n?");
+  if (uninstall) return re.test(t) ? t.replace(re, "\n").replace(/^\n+/, "").replace(/\n{3,}/g, "\n\n") : t;
+  const block = MARK_START + "\n" + RULES + "\n" + MARK_END + "\n";
+  if (re.test(t)) return t.replace(re, (m) => (m.startsWith("\n") ? "\n\n" : "") + block);
+  return t.trim() ? t.replace(/\s*$/, "\n\n") + block : block;
+}
+
+export function plan(opts = {}) {
+  const only = opts.only ? new Set(opts.only) : null;
+  const out = [];
+  for (const c of clients()) {
+    if (only && !only.has(c.id) && !(c.id === "vscode-insiders" && only.has("vscode"))) continue;
+    const r = { id: c.id, name: c.name, docs: c.docs, file: c.file, ops: [], note: "" };
+    if (!c.detect()) { if (!c.optional || only) Object.assign(r, { state: "missing" }); else continue; out.push(r); continue; }
+    Object.assign(r, c.id === "claude-code" ? planClaude(c, opts.uninstall) : c.id === "codex" ? planCodex(c, opts.uninstall) : planJSON(c, opts.uninstall));
+    if (c.rules && !opts.noRules && r.state !== "fail") {
+      const before = readText(c.rules), after = withRules(before, opts.uninstall);
+      if (after !== (before ?? "") && !(opts.uninstall && before === null)) { r.ops.push({ type: "write", file: c.rules, text: after, rules: true }); r.rulesChanged = true; }
+      r.rulesFile = c.rules;
+    }
+    out.push(r);
+  }
+  return out;
+}
+
+function stamp() { const d = new Date(), p = (n) => String(n).padStart(2, "0"); return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`; }
+function runCmd(argv) {
+  const r = spawnSync(argv[0], argv.slice(1), { encoding: "utf8", shell: process.platform === "win32", timeout: 60000 });
+  return { ok: r.status === 0, out: ((r.stderr || "") + (r.stdout || "")).trim() || (r.error ? r.error.message : "") };
+}
+export function apply(items) {
+  const ts = stamp();
+  for (const r of items) {
+    r.backups = [];
+    try {
+      for (const op of r.ops) {
+        if (op.type === "write") {
+          mkdirSync(dirname(op.file), { recursive: true });
+          if (existsSync(op.file)) { const b = op.file + ".bak-owlmem-" + ts; copyFileSync(op.file, b); r.backups.push(b); }
+          writeFileSync(op.file, op.text);
+        } else {
+          let res = runCmd(op.argv);
+          if (!res.ok && op.retryWith && /already exists/i.test(res.out)) { runCmd(op.retryWith.argv); res = runCmd(op.argv); }
+          if (!res.ok && !op.ignoreFail) throw new Error("`" + op.argv.join(" ") + "` failed: " + (res.out.split("\n").slice(-3).join(" ") || "no output"));
+        }
+      }
+    } catch (e) { r.state = "fail"; r.note = (e.message || String(e)) + " — set it up by hand: " + r.docs; }
+  }
+  return items;
+}
+
+const tilde = (f) => { const h = home(); return f && h && f.startsWith(h + (platform() === "win32" ? "\\" : "/")) ? "~" + f.slice(h.length) : f; };
+const SYM = { ok: "✓", add: "✓", update: "↺", remove: "✓", absent: "–", missing: "–", fail: "✗" };
+function describe(r, done, uninstall) {
+  const verb = {
+    ok: "already set up", add: done ? "added" : "will add OwlMem", update: done ? "updated" : "will update the owlmem entry",
+    remove: done ? "removed" : "will remove OwlMem", absent: "not configured", missing: "not installed", fail: "failed",
+  }[r.state];
+  const sym = !done && r.state === "add" ? "+" : !done && r.state === "remove" ? "-" : SYM[r.state];
+  const lines = [`${sym} ${r.name.padEnd(17)} ${verb}${r.state !== "missing" && r.file && r.state !== "fail" ? "  (" + tilde(r.file) + ")" : ""}`];
+  if (r.note) lines.push("    " + r.note);
+  for (const op of r.ops) {
+    if (op.type === "run" && !done) lines.push("    run: " + op.argv.join(" "));
+    if (op.rules) lines.push(`    ${done ? "" : "will "}${uninstall ? (done ? "removed" : "remove") : (done ? "wrote" : "write")} the OwlMem rules block in ${tilde(op.file)}`);
+  }
+  if (done && r.backups?.length) lines.push("    backup: " + r.backups.join(", "));
+  return lines.join("\n");
+}
+
+const LOGIN = {
+  "claude-code": "Claude Code: run /mcp, pick owlmem, choose Authenticate.",
+  codex: "Codex: run `codex mcp login owlmem`.",
+  cursor: "Cursor: Settings → MCP, click \"Needs login\" next to owlmem.",
+  vscode: "VS Code: it asks you to sign in the first time Copilot uses owlmem (or run \"MCP: List Servers\" → owlmem → Start).",
+  "vscode-insiders": "VS Code Insiders: same as VS Code.",
+  windsurf: "Windsurf: open Settings → MCP servers and refresh; sign in when it asks.",
+  gemini: "Gemini CLI: run `/mcp auth owlmem`.",
+  "claude-desktop": "Claude Desktop: restart it; the sign-in page opens on the first start (via mcp-remote).",
+};
+
+async function install(args) {
+  const opts = { dryRun: false, yes: false, noRules: false, uninstall: false, only: null, wake: null };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--dry-run") opts.dryRun = true;
+    else if (a === "--yes" || a === "-y") opts.yes = true;
+    else if (a === "--no-rules") opts.noRules = true;
+    else if (a === "--uninstall") opts.uninstall = true;
+    else if (a === "--wake") opts.wake = true;
+    else if (a === "--no-wake") opts.wake = false;
+    else if (a === "--only" || a.startsWith("--only=")) {
+      const v = a.includes("=") ? a.slice(7) : args[++i];
+      opts.only = String(v || "").split(",").map((s) => s.trim()).filter(Boolean);
+      const bad = opts.only.filter((x) => !CLIENT_IDS.includes(x));
+      if (bad.length || !opts.only.length) throw new Fail(`--only takes a comma-separated list of: ${CLIENT_IDS.join(", ")}`);
+    } else if (a === "--help" || a === "-h") { console.log(INSTALL_HELP); return; }
+    else throw new Fail("Unknown option " + a + "\n\n" + INSTALL_HELP);
+  }
+  const items = plan(opts);
+  const changes = items.filter((r) => r.ops.length);
+  const out = (s = "") => console.log(s);
+  out(opts.uninstall ? "OwlMem uninstall — " + (opts.dryRun ? "dry run, nothing is changed" : "plan") : "OwlMem install — connects the AI apps on this computer to " + MCP_URL + (opts.dryRun ? " (dry run, nothing is changed)" : ""));
+  out();
+  for (const r of items) out(describe(r, false, opts.uninstall));
+  out();
+  if (!changes.length) {
+    out(items.some((r) => r.state === "ok") || opts.uninstall ? "Nothing to change." : "No supported AI apps found. Manual setup for every app: https://owlmem.com/docs");
+    if (!opts.uninstall && items.some((r) => r.state === "ok")) nextSteps(items, out);
+    process.exitCode = items.some((r) => r.state === "fail") ? 1 : 0;
+    if (!opts.dryRun) await installWake(opts, items, out);
+    return;
+  }
+  if (opts.dryRun) { out(`Dry run: ${changes.length} app(s) would change. Run again without --dry-run to apply.`); return; }
+  const tty = process.stdin.isTTY && process.stdout.isTTY;
+  if (tty && !opts.yes) {
+    const ans = (await ask("Apply these changes? [Y/n] ", false)).toLowerCase();
+    if (ans && !ans.startsWith("y")) { out("Nothing changed."); return; }
+  }
+  apply(changes);
+  out();
+  for (const r of changes) out(describe(r, true, opts.uninstall));
+  out();
+  if (opts.uninstall) out("OwlMem was removed from those apps. Backups of every changed file sit next to it (*.bak-owlmem-*).");
+  else {
+    nextSteps(items, out);
+    const codex = items.find((r) => r.id === "codex" && r.state !== "fail" && r.state !== "missing");
+    if (codex && tty && !opts.yes && onPath("codex") && browserAllowed()) {      // codex mcp login opens a browser: same rule as openBrowser
+      const ans = (await ask("Sign Codex in now? This runs `codex mcp login owlmem` and opens your browser. [y/N] ", false)).toLowerCase();
+      if (ans.startsWith("y")) await new Promise((res) => spawn("codex", ["mcp", "login", "owlmem"], { stdio: "inherit", shell: process.platform === "win32" }).on("exit", res).on("error", res));
+    }
+  }
+  await installWake(opts, items, out);
+  if (items.some((r) => r.state === "fail")) process.exitCode = 1;
+}
+
+// `owlmem install` asks once whether to turn on auto-wake (--wake: yes without asking; --yes alone: no). `uninstall` removes it.
+async function installWake(opts, items, out) {
+  try {
+    if (opts.uninstall) { await wakeDisable(true); return; }
+    if (opts.wake === false || loadWake()) return;
+    if (!items.some((r) => (r.id === "claude-code" || r.id === "codex") && ["ok", "add", "update"].includes(r.state))) { if (opts.wake) out("Auto-wake: needs Claude Code or Codex on this computer."); return; }
+    let on = opts.wake === true;
+    if (!on && !opts.yes && process.stdin.isTTY && process.stdout.isTTY)
+      on = (await ask("\nStart your AI automatically when it gets a task (auto-wake, runs in the background)? [y/N] ", false)).toLowerCase().startsWith("y");
+    if (!on) { if (!opts.yes) out("Auto-wake is off. Turn it on any time: npx -y owlmem wake enable"); return; }
+    out(); await wakeEnable([]);
+  } catch (e) { out("Auto-wake: " + (e instanceof Fail ? e.message : e?.message || e)); process.exitCode = 1; }
+}
+
+function nextSteps(items, out) {
+  const live = items.filter((r) => ["ok", "add", "update"].includes(r.state));
+  if (!live.length) return;
+  out("Next: sign in once in each app. The first time an app uses OwlMem it opens the owlmem.com sign-in page —");
+  out("sign in with your email (new accounts get a free space) and click \"Allow\". An AI can't click it for you.");
+  for (const r of live) out("  • " + LOGIN[r.id]);
+  if (live.some((r) => ["cursor", "vscode", "vscode-insiders", "windsurf"].includes(r.id)))
+    out("Cursor, VS Code and Windsurf have no global rules file: add the rules from https://owlmem.com/docs#instructions to your project rules.");
+  if (live.some((r) => r.id === "claude-desktop")) out("Claude Desktop: restart it to load OwlMem. (Or add https://mcp.owlmem.com/mcp under Settings → Connectors instead.)");
+  out("Already-running sessions don't see new MCP servers: start a new session, then ask your AI to run kb_search.");
+}
+
+// ── auto-wake: start the AI on this computer when it gets a task ──
+// One background program per user per computer (`owlmem wake run`, started at login by systemd --user / a LaunchAgent / a
+// logon task) long-polls OwlMem. When an agent paired with this computer gets a task, it runs that agent's command line
+// unattended (`claude -p`, `codex exec`) with the task as the prompt. The woken AI uses its own OwlMem connection (the one
+// `owlmem install` set up), so it acts as itself. It gets no extra permissions: no --dangerously-* flags; anything that
+// needs a person, it declines with what the person has to do.
+// This computer is identified by its device key (device.json); the pairing is approved in the console, where each AI has an
+// auto-wake switch and the computer can be removed. If OwlMem answers 401 (computer removed, AI disconnected, account gone)
+// the program removes its own autostart entry and exits.
+export const WAKE_CLIENTS = {
+  "claude-code": { name: "Claude Code", bin: "claude",
+    // -p runs one prompt and exits; it may only use the two OwlMem tools it needs to report back, beyond what your own settings allow
+    command: ["claude", "-p", "--allowedTools", "mcp__owlmem__kb_task_update,mcp__owlmem__kb_inbox"], prompt: "stdin" },
+  codex: { name: "Codex", bin: "codex", command: ["codex", "exec", "--skip-git-repo-check", "-"], prompt: "stdin" },
+};
+export const WAKE_DEFAULTS = { max_parallel: 2, timeout_min: 30 };
+const WAKE_UNIT = "owlmem-wake.service", WAKE_LABEL = "com.owlmem.wake", WAKE_TASK = "OwlMem Wake", WAKE_RUNKEY = "OwlMemWake";
+const wakeDir = (dir = DIR) => join(dir, "wake");
+const wakeFile = (dir = DIR) => join(wakeDir(dir), "wake.json");
+export function loadWake(dir = DIR) { try { return JSON.parse(readFileSync(wakeFile(dir), "utf8")); } catch { return null; } }
+function saveWake(dir, c) { saveFile(wakeFile(dir), JSON.stringify(c, null, 2) + "\n"); }
+
+// Where the autostart entry goes and what it says. o: {platform, home, dir, node, script, path, uid, user, boot}
+const xml = (s) => String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+const unitq = (s) => '"' + String(s).replace(/%/g, "%%").replace(/\\/g, "\\\\").replace(/"/g, '\\"') + '"';
+export function autostart(o) {
+  const p = o.platform, args = [o.node, o.script, "wake", "run"];
+  if (p === "linux") {
+    const file = join(o.xdg || join(o.home, ".config"), "systemd", "user", WAKE_UNIT);
+    const text = `[Unit]
+Description=OwlMem auto-wake (starts your AI when it gets a task)
+Documentation=https://owlmem.com/docs#wake
+After=network-online.target
+
+[Service]
+Type=simple
+ExecStart=${args.map(unitq).join(" ")}
+Environment=${unitq("OWLMEM_HOME=" + o.dir)}
+Environment=${unitq("PATH=" + o.path)}
+Restart=on-failure
+RestartSec=30
+
+[Install]
+WantedBy=default.target
+`;
+    const sc = (...a) => ["systemctl", "--user", ...a];
+    return { kind: "systemd", file, files: [{ file, text }],
+      start: [{ argv: sc("daemon-reload") }, { argv: sc("enable", "--now", WAKE_UNIT) },
+              ...(o.boot ? [{ argv: ["loginctl", "enable-linger", o.user], ignoreFail: true, note: "boot" }] : [])],
+      stop: [{ argv: sc("disable", "--now", WAKE_UNIT), ignoreFail: true }],
+      selfStop: [{ argv: sc("disable", WAKE_UNIT), ignoreFail: true }],         // from inside the service: don't stop ourselves mid-cleanup
+      after: [{ argv: sc("daemon-reload"), ignoreFail: true }] };
+  }
+  if (p === "darwin") {
+    const file = join(o.home, "Library", "LaunchAgents", WAKE_LABEL + ".plist");
+    const log = join(wakeDir(o.dir), "wake.out.log");
+    const text = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${WAKE_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>${args.map((a) => `<string>${xml(a)}</string>`).join("")}</array>
+  <key>EnvironmentVariables</key>
+  <dict><key>OWLMEM_HOME</key><string>${xml(o.dir)}</string><key>PATH</key><string>${xml(o.path)}</string></dict>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><dict><key>SuccessfulExit</key><false/></dict>
+  <key>ThrottleInterval</key><integer>30</integer>
+  <key>StandardOutPath</key><string>${xml(log)}</string>
+  <key>StandardErrorPath</key><string>${xml(log)}</string>
+</dict>
+</plist>
+`;
+    return { kind: "launchd", file, files: [{ file, text }],
+      start: [{ argv: ["launchctl", "bootstrap", "gui/" + o.uid, file], fallback: { argv: ["launchctl", "load", "-w", file] } }],
+      stop: [{ argv: ["launchctl", "bootout", "gui/" + o.uid + "/" + WAKE_LABEL], ignoreFail: true }],
+      selfStop: [], after: [] };
+  }
+  if (p === "win32") {
+    const vbs = join(wakeDir(o.dir), "owlmem-wake.vbs");
+    const vq = (s) => '""' + String(s).replace(/"/g, '""""') + '""';
+    const text = `' OwlMem auto-wake: runs "owlmem wake run" without a console window (started at logon)\r
+Set sh = CreateObject("WScript.Shell")\r
+sh.Environment("PROCESS")("OWLMEM_HOME") = "${String(o.dir).replace(/"/g, '""')}"\r
+sh.Run "${args.map(vq).join(" ")}", 0, False\r
+`;
+    const tr = `wscript.exe "${vbs}"`;
+    const runKey = "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run";
+    return { kind: "schtasks", file: vbs, files: [{ file: vbs, text }],
+      start: [{ argv: ["schtasks", "/Create", "/TN", WAKE_TASK, "/SC", "ONLOGON", "/TR", tr, "/RL", "LIMITED", "/F"],
+                fallback: { argv: ["reg", "add", runKey, "/v", WAKE_RUNKEY, "/t", "REG_SZ", "/d", tr, "/f"] } },
+              { argv: ["wscript.exe", vbs], ignoreFail: true, detach: true }],
+      stop: [{ argv: ["schtasks", "/End", "/TN", WAKE_TASK], ignoreFail: true }, { argv: ["schtasks", "/Delete", "/TN", WAKE_TASK, "/F"], ignoreFail: true },
+             { argv: ["reg", "delete", runKey, "/v", WAKE_RUNKEY, "/f"], ignoreFail: true }],
+      selfStop: [{ argv: ["schtasks", "/Delete", "/TN", WAKE_TASK, "/F"], ignoreFail: true }, { argv: ["reg", "delete", runKey, "/v", WAKE_RUNKEY, "/f"], ignoreFail: true }],
+      after: [] };
+  }
+  throw new Fail("Auto-wake isn't supported on " + p + ".");
+}
+// The autostart entry outlives this run: under Nix (and similar) process.execPath is a versioned store path that
+// disappears after the next system upgrade, so prefer a stable path that resolves to the same node binary.
+export function stableNode(execPath = process.execPath, candidates = ["/run/current-system/sw/bin/node", join(home(), ".nix-profile", "bin", "node"), "/usr/local/bin/node", "/usr/bin/node", onPath("node")]) {
+  let real; try { real = realpathSync(execPath); } catch { return execPath; }
+  for (const c of candidates) { try { if (c && c !== execPath && realpathSync(c) === real) return c; } catch {} }
+  return execPath;
+}
+function autostartOpts(dir = DIR, extra = {}) {
+  let uid = "", user = "";
+  try { const u = userInfo(); uid = String(u.uid); user = u.username; } catch {}
+  return { platform: platform(), home: home(), xdg: process.env.XDG_CONFIG_HOME, dir, node: stableNode(), script: join(wakeDir(dir), "owlmem.mjs"),
+           path: process.env.PATH || "", uid, user, ...extra };
+}
+// run(argv, op) → {ok, out}; op.detach: start it and don't wait (the Windows launcher)
+function wakeRunCmd(argv, op = {}) {
+  if (!op.detach) return runCmd(argv);
+  try { spawn(argv[0], argv.slice(1), { stdio: "ignore", detached: true }).on("error", () => {}).unref(); return { ok: true, out: "" }; } catch (e) { return { ok: false, out: e.message }; }
+}
+function runOps(ops, run) {
+  const out = [];
+  for (const op of ops) {
+    let r = run(op.argv, op);
+    if (!r.ok && op.fallback) r = run(op.fallback.argv);
+    out.push({ argv: op.argv, ...r });
+    if (!r.ok && !op.ignoreFail) throw new Fail("`" + op.argv.join(" ") + "` failed: " + (r.out || "").split("\n").slice(-2).join(" "));
+  }
+  return out;
+}
+export function installAutostart(o, run = wakeRunCmd) {
+  const a = autostart(o);
+  for (const f of a.files) { mkdirSync(dirname(f.file), { recursive: true }); writeFileSync(f.file, f.text); }
+  return { ...a, ran: runOps(a.start, run) };
+}
+// Remove the autostart entry. self: called by the running program itself (after a 401), so it doesn't stop its own service first.
+export function removeAutostart(o, run = wakeRunCmd, self = false) {
+  const a = autostart(o);
+  const ran = runOps(self ? a.selfStop : a.stop, run);
+  for (const f of a.files) rmSync(f.file, { force: true });
+  ran.push(...runOps(a.after, run));
+  return { ...a, ran };
+}
+// Everything local except the work itself: autostart entry, wake.json, the program copy. Worktrees and logs stay (they hold the AI's work).
+export function wakeUninstall(o, run = wakeRunCmd, self = false) {
+  const r = removeAutostart(o, run, self);
+  for (const f of ["wake.json", "owlmem.mjs", "owlmem-wake.vbs"]) rmSync(join(wakeDir(o.dir), f), { force: true });
+  return r;
+}
+
+// ── a task's working directory ──
+// A task can name one with a line like "cwd: ~/Projects/app" (also dir:, workdir:, 目录：). Git repository → a separate
+// worktree on its own branch (owlmem/task-<id>), so two tasks in one project don't collide; the AI commits there and doesn't merge.
+// Plain directory → one task at a time in it. No directory → an empty folder of its own (OwlMem-only work).
+const DIR_RE = /^[ \t>*-]*(?:cwd|dir|directory|workdir|working directory|目录|工作目录)[ \t]*[:：=][ \t]*`?([^`\r\n]+?)`?[ \t]*$/im;
+export function taskDir(body, h = home()) {
+  const m = DIR_RE.exec(String(body || ""));
+  if (!m) return null;
+  let d = m[1].trim().replace(/^["']|["']$/g, "");
+  if (d === "~" || d.startsWith("~/") || d.startsWith("~\\")) d = join(h, d.slice(2));
+  return isAbsolute(d) ? d : null;
+}
+function gitRun(args) { const r = spawnSync("git", args, { encoding: "utf8", timeout: 60000 }); return { ok: r.status === 0, out: ((r.stdout || "") + (r.stderr || "")).trim() }; }
+export function planWorkdir(task, h = home(), git = gitRun) {
+  const d = taskDir(task.body, h);
+  if (!d) return { kind: "scratch" };
+  let st = null; try { st = statSync(d); } catch {}
+  if (!st || !st.isDirectory()) return { kind: "missing", dir: d };
+  const real = realpathSync(d);
+  const top = git(["-C", real, "rev-parse", "--show-toplevel"]);
+  if (top.ok && top.out) return { kind: "worktree", dir: real, top: realpathSync(top.out.split("\n")[0].trim()) };
+  return { kind: "dir", dir: real, lock: real };
+}
+export function prepareWorkdir(task, plan, dir = DIR, git = gitRun) {
+  if (plan.kind === "missing") throw new Fail("the task's directory doesn't exist on this computer: " + plan.dir);
+  if (plan.kind === "scratch") { const cwd = join(wakeDir(dir), "scratch", "task-" + task.id); mkdirSync(cwd, { recursive: true }); return { cwd }; }
+  if (plan.kind === "dir") return { cwd: plan.dir };
+  const branch = "owlmem/task-" + task.id, wt = join(wakeDir(dir), "worktrees", basename(plan.top) + "-task-" + task.id);
+  if (!existsSync(wt)) {
+    mkdirSync(dirname(wt), { recursive: true });
+    let r = git(["-C", plan.top, "worktree", "add", "-b", branch, wt, "HEAD"]);
+    if (!r.ok && /already exists/i.test(r.out)) r = git(["-C", plan.top, "worktree", "add", wt, branch]);
+    if (!r.ok) throw new Fail("couldn't make a git worktree in " + plan.top + ": " + r.out.split("\n").slice(-1)[0]);
+  }
+  const rel = relative(plan.top, plan.dir);
+  return { cwd: rel ? join(wt, rel) : wt, worktree: wt, branch, repo: plan.top };
+}
+
+export function wakePrompt(task, place, o = {}) {
+  const id = task.id, mins = o.timeout_min || WAKE_DEFAULTS.timeout_min;
+  const where = place.worktree
+    ? `Work in ${place.cwd}. It is a separate git worktree of ${place.repo} on the branch ${place.branch}, made for this task so it doesn't collide with other work. Commit your changes on this branch only. Don't merge, rebase or push other branches, and don't touch ${place.repo} itself. Put the branch name in your result so a person can review and merge it.`
+    : place.scratch ? `There is no project directory for this task: you are in an empty folder (${place.cwd}). Use the OwlMem tools.`
+    : `Work in ${place.cwd}. Other tasks wait until you finish here.`;
+  return `OwlMem auto-wake started you on ${o.machine || "this computer"} to handle one task. Nobody is watching this session and nobody can answer questions.
+
+Task #${id}, for ${task.agent}${task.broadcast ? " (sent to every agent; it is yours once you take it)" : ""}, from ${task.from}:
+Title: ${task.title}
+
+${task.body || "(no details)"}
+
+Rules:
+1. First call kb_task_update with id=${id} and status="doing". If the OwlMem tools aren't available, or OwlMem says the task isn't yours or is already taken, stop there and do nothing else.
+2. ${where}
+3. When you're finished, call kb_task_update with id=${id}, status="done" and note = the result (what you did, where it is).
+4. If you can't do it — including anything that needs a person to approve, sign in, enter a code or confirm — call kb_task_update with id=${id}, status="declined" and note = what a person needs to do. Don't try to get around a permission you don't have.
+5. Never put passwords, tokens, keys or other secrets in the note or in any message.
+6. You have ${mins} minutes. After that this session is stopped and the task is handed to a person.
+`;
+}
+
+// ── running a task ──
+export async function runTask(task, cfg, o = {}) {
+  const dir = o.dir || DIR, cl = (cfg.clients || {})[task.client];
+  if (!cl || !Array.isArray(cl.command) || !cl.command.length) return { outcome: "error", detail: "no command for " + task.client + " on this computer (wake.json)" };
+  let place;
+  try { const plan = o.plan || planWorkdir(task, o.home || home(), o.git); place = prepareWorkdir(task, plan, dir, o.git); if (plan.kind === "scratch") place.scratch = true; }
+  catch (e) { return { outcome: "error", detail: e.message }; }
+  const prompt = wakePrompt(task, place, { machine: cfg.machine, timeout_min: cfg.timeout_min });
+  const argv = [...cl.command, ...(cl.prompt === "arg" ? [prompt] : [])];
+  mkdirSync(join(wakeDir(dir), "logs"), { recursive: true });
+  const logPath = join(wakeDir(dir), "logs", "task-" + task.id + ".log");
+  const fd = openSync(logPath, "a");
+  const win = (o.platform || platform()) === "win32";
+  const ms = o.timeoutMs ?? (cfg.timeout_min || WAKE_DEFAULTS.timeout_min) * 60000;
+  try {
+    return await new Promise((res) => {
+      let ch, timedOut = false, killer = null;
+      try {
+        ch = spawn(argv[0], argv.slice(1), { cwd: place.cwd, stdio: ["pipe", fd, fd], detached: !win, shell: win, windowsHide: true,
+          env: { ...process.env, OWLMEM_NO_BROWSER: "1", OWLMEM_WAKE_TASK: String(task.id) } });
+      } catch (e) { res({ outcome: "error", detail: "couldn't start " + argv[0] + ": " + e.message }); return; }
+      const kill = (sig) => { try { if (win) spawnSync("taskkill", ["/T", "/F", "/PID", String(ch.pid)]); else process.kill(-ch.pid, sig); } catch { try { ch.kill(sig); } catch {} } };
+      const timer = setTimeout(() => { timedOut = true; kill("SIGTERM"); killer = setTimeout(() => kill("SIGKILL"), 10000); }, ms);
+      ch.on("error", (e) => { clearTimeout(timer); clearTimeout(killer); res({ outcome: "error", detail: (e.code === "ENOENT" ? "command not found: " : "couldn't start: ") + argv[0] }); });
+      ch.on("close", (code, sig) => { clearTimeout(timer); clearTimeout(killer); res(timedOut ? { outcome: "timeout", code } : { outcome: "exit", code: code ?? (sig ? 128 : null) }); });
+      ch.stdin.on("error", () => {});
+      ch.stdin.end(cl.prompt === "arg" ? "" : prompt);
+    });
+  } finally { closeSync(fd); }
+}
+
+// One at a time per AI, one at a time per plain directory, at most `max` at once on the computer. start(job) → Promise<result>.
+export class Scheduler {
+  constructor({ max = WAKE_DEFAULTS.max_parallel, start, onDone } = {}) {
+    Object.assign(this, { max, start, onDone, queue: [], running: new Set(), agents: new Set(), locks: new Set() });
+  }
+  add(job) { this.queue.push(job); this.pump(); }
+  pump() {
+    for (let i = 0; i < this.queue.length && this.running.size < this.max;) {
+      const j = this.queue[i];
+      if (this.agents.has(j.agent) || (j.lock && this.locks.has(j.lock))) { i++; continue; }
+      this.queue.splice(i, 1); this.running.add(j); this.agents.add(j.agent); if (j.lock) this.locks.add(j.lock);
+      Promise.resolve().then(() => this.start(j)).catch((e) => ({ outcome: "error", detail: e?.message || String(e) })).then((res) => {
+        this.running.delete(j); this.agents.delete(j.agent); if (j.lock) this.locks.delete(j.lock);
+        try { this.onDone?.(j, res); } catch {}
+        this.pump();
+      });
+    }
+  }
+  busy() { return [...new Set([...this.agents, ...this.queue.map((j) => j.agent)])]; }
+  slots() { return Math.max(0, this.max - this.running.size - this.queue.length); }
+  get size() { return this.running.size + this.queue.length; }
+}
+
+// The long-poll loop. api(sub, body) → {status, data}. Returns "revoked" after cleaning up on a 401.
+export async function wakeLoop(o) {
+  const { cfg, api, sched, log = () => {}, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), once = false, cleanup } = o;
+  let backoff = 0;
+  for (;;) {
+    const t0 = Date.now();
+    let r;
+    try { r = await api("poll", { busy: sched.busy(), slots: sched.slots(), timeout: (cfg.timeout_min || WAKE_DEFAULTS.timeout_min) * 60, wait: 50, version: VERSION }); }
+    catch (e) { r = { status: 0, data: { detail: e?.message || String(e) } }; }
+    if (r.status === 401) {
+      log("OwlMem no longer accepts this computer for auto-wake (" + (r.data?.detail || r.data?.error || "401") + "). Removing auto-wake from this computer.");
+      if (cleanup) cleanup();
+      return "revoked";
+    }
+    if (r.status !== 200) {        // network trouble or a server hiccup: try again, waiting longer each time (up to 5 minutes)
+      backoff = Math.min(300000, backoff ? backoff * 2 : 2000);
+      log("Can't reach OwlMem (" + (r.data?.detail || "HTTP " + r.status) + "); trying again in " + Math.round(backoff / 1000) + " s.");
+      if (once) return "error";
+      await sleep(backoff); continue;
+    }
+    backoff = 0;
+    for (const t of r.data.tasks || []) {
+      const plan = o.plan ? o.plan(t) : planWorkdir(t);
+      log("Task #" + t.id + " for " + t.agent + ": starting " + t.client + (plan.dir ? " in " + plan.dir : "") + ".");
+      sched.add({ id: t.id, agent: t.agent, lock: plan.lock || null, task: t, plan });
+    }
+    if (once) return r.data.status;
+    if (Date.now() - t0 < 1000 && !(r.data.tasks || []).length) await sleep(1000);       // never spin
+  }
+}
+
+function wakeApi() {
+  return async (sub, body) => {
+    const url = BASE + "/v1/wake/" + sub;
+    let r;
+    try {
+      const sh = await signHeaders("POST", url, "other");
+      r = await fetch(url, { method: "POST", headers: { "Content-Type": "application/json", "User-Agent": "owlmem-cli/" + VERSION, ...sh },
+                             body: JSON.stringify(body || {}), signal: AbortSignal.timeout(90000) });
+    } catch (e) { return { status: 0, data: { detail: e.message } }; }
+    return { status: r.status, data: await r.json().catch(() => ({})) };
+  };
+}
+
+function wakeLogger(dir = DIR) {
+  const f = join(wakeDir(dir), "wake.log");
+  return (msg) => {
+    const line = new Date().toISOString() + " " + msg + "\n";
+    try { mkdirSync(wakeDir(dir), { recursive: true }); if (existsSync(f) && statSync(f).size > 1 << 20) copyFileSync(f, f + ".1"), writeFileSync(f, ""); appendFileSync(f, line); } catch {}
+    process.stderr.write(line);
+  };
+}
+
+async function wakeRun() {
+  const cfg = loadWake();
+  if (!cfg) throw new Fail("Auto-wake isn't set up on this computer. Run: npx -y owlmem wake enable");
+  const log = wakeLogger(), api = wakeApi();
+  const report = async (j, res) => {
+    log("Task #" + j.id + ": " + res.outcome + (res.code != null ? " (exit code " + res.code + ")" : "") + (res.detail ? " — " + res.detail : ""));
+    for (let i = 0; i < 5; i++) {
+      const r = await api("report", { id: j.id, outcome: res.outcome, code: res.code ?? null, detail: res.detail || "" });
+      if (r.status === 200 || r.status === 404 || r.status === 401) return;
+      await new Promise((ok) => setTimeout(ok, 5000 * (i + 1)));
+    }
+  };
+  const sched = new Scheduler({ max: cfg.max_parallel || WAKE_DEFAULTS.max_parallel, start: (j) => runTask(j.task, cfg, { plan: j.plan }), onDone: (j, res) => { report(j, res); } });
+  log("OwlMem auto-wake " + VERSION + " running on " + (cfg.machine || hostname()) + ".");
+  const out = await wakeLoop({ cfg, api, sched, log, cleanup: () => { try { wakeUninstall(autostartOpts(), wakeRunCmd, true); } catch (e) { log("cleanup: " + e.message); } } });
+  if (out === "revoked") process.exit(0);
+}
+
+async function wakeEnable(args = []) {
+  const boot = args.includes("--boot"), again = args.includes("--again");
+  const num = (name, lo, hi) => { const i = args.indexOf(name); if (i < 0) return undefined; const n = Number(args[i + 1]); if (!Number.isInteger(n) || n < lo || n > hi) throw new Fail(`${name} takes a whole number from ${lo} to ${hi}.`); return n; };
+  const max = num("--max", 1, 16), timeout = num("--timeout", 1, 240);
+  const old = loadWake() || {};
+  const clients = { ...(old.clients || {}) };
+  for (const [id, c] of Object.entries(WAKE_CLIENTS)) if (!clients[id] && onPath(c.bin)) clients[id] = { command: c.command, prompt: c.prompt };
+  if (!Object.keys(clients).length)
+    throw new Fail("No AI command line found on this computer that auto-wake can start (Claude Code: claude, Codex: codex). Install one, or add its command to " + wakeFile() + " under \"clients\".");
+  const cfg = { v: 1, ...WAKE_DEFAULTS, ...old, machine: process.env.OWLMEM_DEVICE_NAME || hostname(), clients, ...(max ? { max_parallel: max } : {}), ...(timeout ? { timeout_min: timeout } : {}), boot: boot || !!old.boot };
+  // OwlMem knows these app names; a command you add yourself to wake.json goes under "gemini" or "custom"
+  const r = await wakeApi()("pair", { clients: Object.keys(clients).filter((c) => ["claude-code", "codex", "gemini", "custom"].includes(c)), force: again });
+  if (r.status !== 200) throw new Fail("OwlMem didn't accept the pairing: " + (r.data.detail || r.data.error || "HTTP " + r.status));
+  mkdirSync(wakeDir(), { recursive: true });
+  copyFileSync(fileURLToPath(import.meta.url), join(wakeDir(), "owlmem.mjs"));      // the service runs this copy (npx's cache can be cleaned out)
+  if (r.data.status === "pending") cfg.pair_url = r.data.url; else delete cfg.pair_url;
+  saveWake(DIR, cfg);
+  const a = installAutostart(autostartOpts(DIR, { boot: cfg.boot }));
+  say("Auto-wake is installed (" + a.kind + ": " + tilde(a.file) + ").");
+  say("Apps it can start here: " + Object.keys(clients).map((c) => WAKE_CLIENTS[c]?.name || c).join(", ") + ". At most " + cfg.max_parallel + " at once, " + cfg.timeout_min + " minutes per task.");
+  if (r.data.status === "pending") {
+    say("\nApprove this computer in the OwlMem console and pick which AI each app is:\n\n  " + r.data.url + "\n\nCheck that the console shows this code: " + r.data.code + "\nUntil then auto-wake waits and starts nothing.");
+    openBrowser(r.data.url);
+  } else say("This computer is already paired (" + r.data.code + "). Turn auto-wake on or off for each AI in the console (AI agents → Agents).");
+}
+
+function wakeDisable(quiet = false) {
+  const had = !!loadWake();
+  const o = autostartOpts();
+  const present = existsSync(autostart(o).file);
+  if (!had && !present) { if (!quiet) say("Auto-wake isn't set up on this computer."); return false; }
+  const api = wakeApi();
+  return api("bye", {}).catch(() => null).then(() => {
+    wakeUninstall(o);
+    say("Auto-wake removed from this computer (autostart entry and settings). Worktrees and logs it made stay in " + tilde(wakeDir()) + ".");
+    return true;
+  });
+}
+
+async function wakeStatus() {
+  const cfg = loadWake(), a = autostart(autostartOpts());
+  if (!cfg) { say("Auto-wake isn't set up on this computer. Turn it on: npx -y owlmem wake enable"); return; }
+  say("Autostart: " + (existsSync(a.file) ? a.kind + " (" + tilde(a.file) + ")" : "missing"));
+  say("Apps: " + Object.entries(cfg.clients || {}).map(([k, v]) => k + " → " + v.command.join(" ")).join("; "));
+  say("At most " + cfg.max_parallel + " at once, " + cfg.timeout_min + " minutes per task. Log: " + tilde(join(wakeDir(), "wake.log")));
+  const r = await wakeApi()("poll", { wait: 0, slots: 0 });
+  if (r.status === 401) say("OwlMem: this computer isn't paired any more. Pair it again: npx -y owlmem wake enable --again");
+  else if (r.status !== 200) say("OwlMem: can't reach it (" + (r.data.detail || "HTTP " + r.status) + ")");
+  else if (r.data.status === "pending") say("OwlMem: waiting for approval in the console" + (cfg.pair_url ? ": " + cfg.pair_url : "") + " (code " + r.data.code + ")");
+  else say("OwlMem: paired as " + r.data.code + ". " + r.data.agents.map((x) => x.agent + " (" + x.client + (x.wake ? "" : ", switched off") + ")").join(", "));
+}
+
+const WAKE_HELP = `Usage: npx -y owlmem wake <enable|disable|status>
+
+Auto-wake starts the AI on this computer when it gets an OwlMem task (Claude Code with \`claude -p\`, Codex with
+\`codex exec\`), without you opening it. It runs in the background from login, for this user only.
+
+  enable [--boot] [--max N] [--timeout MIN] [--again]
+                 install it and pair this computer (approve in the console). --boot (Linux): run from boot,
+                 not just login. --max: tasks at once (default 2). --timeout: minutes per task (default 30).
+                 --again: pair again (choose the AIs again).
+  disable        remove it from this computer (also done by npx -y owlmem uninstall)
+  status         show what's set up and what OwlMem says
+
+Turn it off for one AI with the switch in the console (AI agents → Agents). Settings, including the command for
+each app ("claude-code", "codex", or your own under "gemini" / "custom"): ~/.config/owlmem/wake/wake.json`;
+
+async function wakeCmd(sub, args) {
+  if (sub === "enable") return wakeEnable(args);
+  if (sub === "disable") return wakeDisable();
+  if (sub === "status") return wakeStatus();
+  if (sub === "run") return wakeRun();
+  console.log(WAKE_HELP);
+  if (sub && sub !== "help" && sub !== "--help") process.exitCode = 2;
+}
+
+const INSTALL_HELP = `Usage: npx -y owlmem install [options]
+
+Connects Claude Code, Codex, Cursor, VS Code, Windsurf, Gemini CLI and Claude Desktop on this computer to
+OwlMem (${MCP_URL}). Config files are merged, never overwritten; each changed file is backed up first
+as <file>.bak-owlmem-<time>. Also adds the OwlMem usage rules to CLAUDE.md / AGENTS.md / GEMINI.md.
+
+  --dry-run          show what would change, change nothing
+  --yes, -y          don't ask (non-interactive runs, e.g. an AI running this, never ask)
+  --only a,b         only these apps: ${CLIENT_IDS.join(", ")}
+  --no-rules         don't touch CLAUDE.md / AGENTS.md / GEMINI.md
+  --uninstall        remove OwlMem entries and the rules block (with backups), and auto-wake
+  --wake             also turn on auto-wake: start your AI when it gets a task (without --wake, --yes leaves it off)
+  --no-wake          don't ask about auto-wake
+
+Signing in happens in each app the first time it uses OwlMem (standard MCP OAuth): you click "Allow" once.`;
+
 export async function main(argv) {
   const [cmd, sub, ...rest] = argv;
   if (cmd === "--version" || cmd === "version") { console.log(VERSION); return; }
+  if (cmd === "install") { await install(argv.slice(1)); return; }
+  if (cmd === "uninstall") { await install(["--uninstall", ...argv.slice(1)]); return; }
   if (cmd === "mcp") { await mcpServe(); return; }
+  if (cmd === "wake") { await wakeCmd(sub, rest); return; }
+  if (cmd === "device") {          // register this machine for standing grants and show its fingerprint
+    const r = await call("POST", "device", {});
+    if (r.status >= 400) throw new Fail(r.data.detail || r.data.error || "HTTP " + r.status);
+    say("This machine: " + (process.env.OWLMEM_DEVICE_NAME || hostname()));
+    console.log(r.data.device);
+    say("Registered for " + r.data.agent + ". In the OwlMem console (Vault → Standing grants) pick the machine with this fingerprint.");
+    return;
+  }
   if (cmd === "login") {
     const t = (process.env.OWLMEM_TOKEN || await ask("Paste this agent's token (om_…, shown as dots), then Enter: ")).replace(/\x1b\[[0-9;]*[~A-Za-z]/g, "").replace(/[^A-Za-z0-9_-]/g, "");
     if (!/^om_[A-Za-z0-9_-]{20,80}$/.test(t)) throw new Fail("That doesn't look like an OwlMem agent token (om_…).");
@@ -455,13 +1243,13 @@ export async function main(argv) {
       if (opts[i] !== "--env") throw new Fail("Unknown option " + opts[i]);
       const m = /^([A-Za-z_][A-Za-z0-9_]*)=([^:]+)(?::(.+))?$/.exec(opts[++i] || "");
       if (!m) throw new Fail("Use --env VAR=item or --env VAR=item:field");
-      env[m[1]] = pick(await fetchItem(m[2]), m[3] || (undefined));
+      env[m[1]] = pick(await fetchItem(m[2], "run"), m[3] || (undefined));
     }
     const child = spawn(command[0], command.slice(1), { stdio: "inherit", env });
     await new Promise((res) => child.on("exit", (code, sig) => { process.exitCode = sig ? 1 : code; res(); }));
     return;
   }
-  if (cmd !== "vault") { say(readFileSync(new URL(import.meta.url), "utf8").split("\n").filter((l) => l.startsWith("//")).slice(0, 26).map((l) => l.slice(3)).join("\n")); process.exitCode = cmd ? 2 : 0; return; }
+  if (cmd !== "vault") { { const ls = readFileSync(new URL(import.meta.url), "utf8").split("\n").slice(1); say(ls.slice(0, ls.findIndex((l) => !l.startsWith("//"))).map((l) => l.slice(3)).join("\n")); } process.exitCode = cmd ? 2 : 0; return; }
   const args = [...rest];
   if (sub === "keygen") {
     const sp = process.env.OWLMEM_SPACE || (await space().catch(() => ({}))).space;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "owlmem",
-  "version": "0.4.1",
-  "description": "OwlMem command line: end-to-end encrypted vault for your AI agents, and a local MCP server.",
+  "version": "0.7.0",
+  "description": "OwlMem command line: connect your AI apps to OwlMem in one command (npx -y owlmem install), an end-to-end encrypted vault for your AI agents, and a local MCP server.",
   "type": "module",
   "bin": { "owlmem": "owlmem.mjs" },
   "files": ["owlmem.mjs", "README.md", "LICENSE"],