owlmem 0.6.0 → 0.7.0

package/README.md

@@ -19,11 +19,44 @@ changes is backed up first (`<file>.bak-owlmem-<time>`). It also adds a short "T
 | `--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 |
-| `--uninstall` | remove the OwlMem entries and rules block again |
+| `--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

package/owlmem.mjs

@@ -5,9 +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] [--uninstall]
+//   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
@@ -32,12 +33,13 @@
 // 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, copyFileSync } from "node:fs";
-import { homedir, hostname } from "node:os";
-import { join, dirname } from "node:path";
+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.6.0";
+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();
@@ -200,10 +202,11 @@ export async function deviceFingerprint(spki) {
   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
-async function signHeaders(method, path, mode) {
+// 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(BASE + "/v1/vault/" + path).pathname, mode, ts, nonce].join("\n");
+  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) };
@@ -213,7 +216,7 @@ async function signHeaders(method, path, mode) {
 async function call(method, path, body, mode = "other") {
   let r;
   try {
-    const sh = await signHeaders(method, path, mode).catch(() => ({}));      // can't write the device key: no standing grants, everything else still works
+    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); }
@@ -703,13 +706,15 @@ const LOGIN = {
 };
 
 async function install(args) {
-  const opts = { dryRun: false, yes: false, noRules: false, uninstall: false, only: null };
+  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);
@@ -729,6 +734,7 @@ async function install(args) {
     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; }
@@ -750,9 +756,24 @@ async function install(args) {
       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;
@@ -765,6 +786,415 @@ function nextSteps(items, out) {
   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
@@ -775,7 +1205,9 @@ as <file>.bak-owlmem-<time>. Also adds the OwlMem usage rules to CLAUDE.md / AGE
   --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)
+  --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.`;
 
@@ -785,6 +1217,7 @@ export async function main(argv) {
   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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "owlmem",
-  "version": "0.6.0",
+  "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" },