@forwardimpact/basecamp 1.0.0 → 2.2.0

package/src/basecamp.js

@@ -1,14 +1,16 @@
 #!/usr/bin/env node
 
-// Basecamp — CLI and scheduler for personal knowledge bases.
+// Basecamp — CLI and scheduler for autonomous agent teams.
 //
 // Usage:
-//   node basecamp.js                     Run due tasks once and exit
+//   node basecamp.js                     Wake due agents once and exit
 //   node basecamp.js --daemon            Run continuously (poll every 60s)
-//   node basecamp.js --run <task>        Run a specific task immediately
+//   node basecamp.js --wake <agent>      Wake a specific agent immediately
 //   node basecamp.js --init <path>       Initialize a new knowledge base
-//   node basecamp.js --validate          Validate agents and skills exist
-//   node basecamp.js --status            Show task status
+//   node basecamp.js --update [path]     Update KB with latest CLAUDE.md, agents and skills
+//   node basecamp.js --stop              Gracefully stop daemon and children
+//   node basecamp.js --validate          Validate agent definitions exist
+//   node basecamp.js --status            Show agent status
 //   node basecamp.js --help              Show this help
 
 import {
@@ -18,9 +20,11 @@ import {
   mkdirSync,
   unlinkSync,
   chmodSync,
+  readdirSync,
+  statSync,
+  cpSync,
+  copyFileSync,
 } from "node:fs";
-import { execSync } from "node:child_process";
-import { spawn } from "node:child_process";
 import { join, dirname, resolve } from "node:path";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
@@ -31,32 +35,29 @@ const BASECAMP_HOME = join(HOME, ".fit", "basecamp");
 const CONFIG_PATH = join(BASECAMP_HOME, "scheduler.json");
 const STATE_PATH = join(BASECAMP_HOME, "state.json");
 const LOG_DIR = join(BASECAMP_HOME, "logs");
+const CACHE_DIR = join(HOME, ".cache", "fit", "basecamp");
 const __dirname =
   import.meta.dirname || dirname(fileURLToPath(import.meta.url));
 const SHARE_DIR = "/usr/local/share/fit-basecamp";
 const SOCKET_PATH = join(BASECAMP_HOME, "basecamp.sock");
 
-// --- posix_spawn (macOS app bundle only) ------------------------------------
+// --- posix_spawn (TCC-compliant process spawning) ---------------------------
 
-const USE_POSIX_SPAWN = !!process.env.BASECAMP_BUNDLE;
-let posixSpawn;
-if (USE_POSIX_SPAWN) {
-  try {
-    posixSpawn = await import("./posix-spawn.js");
-  } catch (err) {
-    console.error(
-      "Failed to load posix-spawn, falling back to child_process:",
-      err.message,
-    );
-  }
-}
+import * as posixSpawn from "./posix-spawn.js";
 
 let daemonStartedAt = null;
 
+// Maximum time an agent can be "active" before being considered stale (35 min).
+// Matches the 30-minute child_process timeout plus a buffer.
+const MAX_AGENT_RUNTIME_MS = 35 * 60_000;
+
+/** Active child PIDs spawned by posix_spawn (for graceful shutdown). */
+const activeChildren = new Set();
+
 // --- Helpers ----------------------------------------------------------------
 
 function ensureDir(dir) {
-  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  mkdirSync(dir, { recursive: true });
 }
 
 function readJSON(path, fallback) {
@@ -124,12 +125,12 @@ function getBundlePath() {
 }
 
 function loadConfig() {
-  return readJSON(CONFIG_PATH, { tasks: {} });
+  return readJSON(CONFIG_PATH, { agents: {} });
 }
 function loadState() {
   const raw = readJSON(STATE_PATH, null);
-  if (!raw || typeof raw !== "object" || !raw.tasks) {
-    const state = { tasks: {} };
+  if (!raw || typeof raw !== "object" || !raw.agents) {
+    const state = { agents: {} };
     saveState(state);
     return state;
   }
@@ -167,196 +168,197 @@ function cronMatches(expr, d) {
 // --- Scheduling logic -------------------------------------------------------
 
 function floorToMinute(d) {
-  return new Date(
-    d.getFullYear(),
-    d.getMonth(),
-    d.getDate(),
-    d.getHours(),
-    d.getMinutes(),
-  ).getTime();
-}
-
-function shouldRun(task, taskState, now) {
-  if (task.enabled === false) return false;
-  if (taskState.status === "running") return false;
-  const { schedule } = task;
+  const t = d.getTime();
+  return t - (t % 60_000);
+}
+
+function shouldWake(agent, agentState, now) {
+  if (agent.enabled === false) return false;
+  if (agentState.status === "active") return false;
+  const { schedule } = agent;
   if (!schedule) return false;
-  const lastRun = taskState.lastRunAt ? new Date(taskState.lastRunAt) : null;
+  const lastWoke = agentState.lastWokeAt
+    ? new Date(agentState.lastWokeAt)
+    : null;
 
   if (schedule.type === "cron") {
-    if (lastRun && floorToMinute(lastRun) === floorToMinute(now)) return false;
+    if (lastWoke && floorToMinute(lastWoke) === floorToMinute(now))
+      return false;
     return cronMatches(schedule.expression, now);
   }
   if (schedule.type === "interval") {
     const ms = (schedule.minutes || 5) * 60_000;
-    return !lastRun || now.getTime() - lastRun.getTime() >= ms;
+    return !lastWoke || now.getTime() - lastWoke.getTime() >= ms;
   }
   if (schedule.type === "once") {
-    return !taskState.lastRunAt && now >= new Date(schedule.runAt);
+    return !agentState.lastWokeAt && now >= new Date(schedule.runAt);
   }
   return false;
 }
 
-// --- Task execution ---------------------------------------------------------
+// --- Agent execution --------------------------------------------------------
 
-async function runTask(taskName, task, _config, state) {
-  if (!task.kb) {
-    log(`Task ${taskName}: no "kb" specified, skipping.`);
+function failAgent(agentState, error) {
+  Object.assign(agentState, {
+    status: "failed",
+    startedAt: null,
+    lastWokeAt: new Date().toISOString(),
+    lastError: String(error).slice(0, 500),
+  });
+}
+
+async function wakeAgent(agentName, agent, state) {
+  if (!agent.kb) {
+    log(`Agent ${agentName}: no "kb" specified, skipping.`);
     return;
   }
-  const kbPath = expandPath(task.kb);
+  const kbPath = expandPath(agent.kb);
   if (!existsSync(kbPath)) {
-    log(`Task ${taskName}: path "${kbPath}" does not exist, skipping.`);
+    log(`Agent ${agentName}: path "${kbPath}" does not exist, skipping.`);
     return;
   }
 
   const claude = findClaude();
-  const prompt = task.skill
-    ? `Use the skill "${task.skill}" — ${task.prompt || `Run the ${taskName} task.`}`
-    : task.prompt || `Run the ${taskName} task.`;
 
-  log(
-    `Running task: ${taskName} (kb: ${task.kb}${task.agent ? `, agent: ${task.agent}` : ""}${task.skill ? `, skill: ${task.skill}` : ""})`,
-  );
+  log(`Waking agent: ${agentName} (kb: ${agent.kb})`);
 
-  const ts = (state.tasks[taskName] ||= {});
-  ts.status = "running";
-  ts.startedAt = new Date().toISOString();
+  const as = (state.agents[agentName] ||= {});
+  as.status = "active";
+  as.startedAt = new Date().toISOString();
   saveState(state);
 
-  const spawnArgs = ["--print"];
-  if (task.agent) spawnArgs.push("--agent", task.agent);
-  spawnArgs.push("-p", prompt);
-
-  // Use posix_spawn when running inside the app bundle for TCC inheritance.
-  // Fall back to child_process.spawn for dev mode and other platforms.
-  if (posixSpawn) {
-    try {
-      const { pid, stdoutFd, stderrFd } = posixSpawn.spawn(
-        claude,
-        spawnArgs,
-        undefined,
-        kbPath,
-      );
+  const spawnArgs = ["--agent", agentName, "--print", "-p", "Observe and act."];
 
-      // Read stdout and stderr concurrently to avoid pipe deadlocks,
-      // then wait for the child to exit.
-      const [stdout, stderr] = await Promise.all([
-        posixSpawn.readAll(stdoutFd),
-        posixSpawn.readAll(stderrFd),
-      ]);
-      const exitCode = await posixSpawn.waitForExit(pid);
-
-      if (exitCode === 0) {
-        log(`Task ${taskName} completed. Output: ${stdout.slice(0, 200)}...`);
-        Object.assign(ts, {
-          status: "finished",
-          startedAt: null,
-          lastRunAt: new Date().toISOString(),
-          lastError: null,
-          runCount: (ts.runCount || 0) + 1,
-        });
-      } else {
-        const errMsg = stderr || stdout || `Exit code ${exitCode}`;
-        log(`Task ${taskName} failed: ${errMsg.slice(0, 300)}`);
-        Object.assign(ts, {
-          status: "failed",
-          startedAt: null,
-          lastRunAt: new Date().toISOString(),
-          lastError: errMsg.slice(0, 500),
-        });
-      }
-      saveState(state);
-    } catch (err) {
-      log(`Task ${taskName} failed: ${err.message}`);
-      Object.assign(ts, {
-        status: "failed",
-        startedAt: null,
-        lastRunAt: new Date().toISOString(),
-        lastError: err.message.slice(0, 500),
-      });
-      saveState(state);
+  try {
+    const { pid, stdoutFd, stderrFd } = posixSpawn.spawn(
+      claude,
+      spawnArgs,
+      undefined,
+      kbPath,
+    );
+    activeChildren.add(pid);
+
+    // Read stdout and stderr concurrently to avoid pipe deadlocks,
+    // then wait for the child to exit.
+    const [stdout, stderr] = await Promise.all([
+      posixSpawn.readAll(stdoutFd),
+      posixSpawn.readAll(stderrFd),
+    ]);
+    const exitCode = await posixSpawn.waitForExit(pid);
+    activeChildren.delete(pid);
+
+    if (exitCode === 0) {
+      log(`Agent ${agentName} completed. Output: ${stdout.slice(0, 200)}...`);
+      updateAgentState(as, stdout, agentName);
+    } else {
+      const errMsg = stderr || stdout || `Exit code ${exitCode}`;
+      log(`Agent ${agentName} failed: ${errMsg.slice(0, 300)}`);
+      failAgent(as, errMsg);
     }
-    return;
+  } catch (err) {
+    log(`Agent ${agentName} failed: ${err.message}`);
+    failAgent(as, err.message);
   }
+  saveState(state);
+}
 
-  return new Promise((resolve) => {
-    const child = spawn(claude, spawnArgs, {
-      cwd: kbPath,
-      stdio: ["pipe", "pipe", "pipe"],
-      timeout: 30 * 60_000,
-    });
+/**
+ * Parse Decision:/Action: lines from agent output and update state.
+ * Also saves stdout to the state directory as a briefing fallback.
+ * @param {object} agentState
+ * @param {string} stdout
+ * @param {string} agentName
+ */
+function updateAgentState(agentState, stdout, agentName) {
+  const lines = stdout.split("\n");
+  const decisionLine = lines.find((l) => l.startsWith("Decision:"));
+  const actionLine = lines.find((l) => l.startsWith("Action:"));
+
+  Object.assign(agentState, {
+    status: "idle",
+    startedAt: null,
+    lastWokeAt: new Date().toISOString(),
+    lastDecision: decisionLine
+      ? decisionLine.slice(10).trim()
+      : stdout.slice(0, 200),
+    lastAction: actionLine ? actionLine.slice(8).trim() : null,
+    lastError: null,
+    wakeCount: (agentState.wakeCount || 0) + 1,
+  });
 
-    let stdout = "";
-    let stderr = "";
-    child.stdout.on("data", (d) => (stdout += d));
-    child.stderr.on("data", (d) => (stderr += d));
-
-    child.on("close", (code) => {
-      if (code === 0) {
-        log(`Task ${taskName} completed. Output: ${stdout.slice(0, 200)}...`);
-        Object.assign(ts, {
-          status: "finished",
-          startedAt: null,
-          lastRunAt: new Date().toISOString(),
-          lastError: null,
-          runCount: (ts.runCount || 0) + 1,
-        });
-      } else {
-        const errMsg = stderr || stdout || `Exit code ${code}`;
-        log(`Task ${taskName} failed: ${errMsg.slice(0, 300)}`);
-        Object.assign(ts, {
-          status: "failed",
-          startedAt: null,
-          lastRunAt: new Date().toISOString(),
-          lastError: errMsg.slice(0, 500),
-        });
-      }
-      saveState(state);
-      resolve();
-    });
+  // Save output as briefing fallback so View Briefing always has content
+  const stateDir = join(CACHE_DIR, "state");
+  ensureDir(stateDir);
+  const prefix = agentName.replace(/-/g, "_");
+  writeFileSync(join(stateDir, `${prefix}_last_output.md`), stdout);
+}
 
-    child.on("error", (err) => {
-      log(`Task ${taskName} failed: ${err.message}`);
-      Object.assign(ts, {
-        status: "failed",
-        startedAt: null,
-        lastRunAt: new Date().toISOString(),
-        lastError: err.message.slice(0, 500),
-      });
-      saveState(state);
-      resolve();
+/**
+ * Reset agents stuck in "active" state. This happens when the daemon
+ * restarts while agents were running, or when a child process exits
+ * without triggering cleanup (e.g. pipe error, signal).
+ *
+ * @param {object} state
+ * @param {{ reason: string, maxAge?: number }} opts
+ *   reason  — logged and stored in lastError
+ *   maxAge  — if set, only reset agents active longer than this (ms)
+ */
+function resetStaleAgents(state, { reason, maxAge }) {
+  let resetCount = 0;
+  for (const [name, as] of Object.entries(state.agents)) {
+    if (as.status !== "active") continue;
+    if (maxAge && as.startedAt) {
+      const elapsed = Date.now() - new Date(as.startedAt).getTime();
+      if (elapsed < maxAge) continue;
+    }
+    log(`Resetting stale agent: ${name} (${reason})`);
+    Object.assign(as, {
+      status: "interrupted",
+      startedAt: null,
+      lastError: reason,
     });
-  });
+    resetCount++;
+  }
+  if (resetCount > 0) saveState(state);
+  return resetCount;
 }
 
-async function runDueTasks() {
+async function wakeDueAgents() {
   const config = loadConfig(),
     state = loadState(),
     now = new Date();
-  let ranAny = false;
-  for (const [name, task] of Object.entries(config.tasks)) {
-    if (shouldRun(task, state.tasks[name] || {}, now)) {
-      await runTask(name, task, config, state);
-      ranAny = true;
+
+  // Reset agents that have been active longer than the maximum runtime.
+  resetStaleAgents(state, {
+    reason: "Exceeded maximum runtime",
+    maxAge: MAX_AGENT_RUNTIME_MS,
+  });
+
+  let wokeAny = false;
+  for (const [name, agent] of Object.entries(config.agents)) {
+    if (shouldWake(agent, state.agents[name] || {}, now)) {
+      await wakeAgent(name, agent, state);
+      wokeAny = true;
     }
   }
-  if (!ranAny) log("No tasks due.");
+  if (!wokeAny) log("No agents due.");
 }
 
-// --- Next-run computation ---------------------------------------------------
+// --- Next-wake computation --------------------------------------------------
 
-/** @param {object} task @param {object} taskState @param {Date} now */
-function computeNextRunAt(task, taskState, now) {
-  if (task.enabled === false) return null;
-  const { schedule } = task;
+/** @param {object} agent @param {object} agentState @param {Date} now */
+function computeNextWakeAt(agent, agentState, now) {
+  if (agent.enabled === false) return null;
+  const { schedule } = agent;
   if (!schedule) return null;
 
   if (schedule.type === "interval") {
     const ms = (schedule.minutes || 5) * 60_000;
-    const lastRun = taskState.lastRunAt ? new Date(taskState.lastRunAt) : null;
-    if (!lastRun) return now.toISOString();
-    return new Date(lastRun.getTime() + ms).toISOString();
+    const lastWoke = agentState.lastWokeAt
+      ? new Date(agentState.lastWokeAt)
+      : null;
+    if (!lastWoke) return now.toISOString();
+    return new Date(lastWoke.getTime() + ms).toISOString();
   }
 
   if (schedule.type === "cron") {
@@ -372,13 +374,62 @@ function computeNextRunAt(task, taskState, now) {
   }
 
   if (schedule.type === "once") {
-    if (taskState.lastRunAt) return null;
+    if (agentState.lastWokeAt) return null;
     return schedule.runAt;
   }
 
   return null;
 }
 
+// --- Briefing file resolution -----------------------------------------------
+
+/**
+ * Resolve the briefing file for an agent by convention:
+ * 1. Scan ~/.cache/fit/basecamp/state/ for files matching {agent_name}_*.md
+ * 2. Fall back to the KB's knowledge/Briefings/ directory (latest .md file)
+ *
+ * @param {string} agentName
+ * @param {object} agentConfig
+ * @returns {string|null}
+ */
+function resolveBriefingFile(agentName, agentConfig) {
+  // 1. Scan state directory for agent-specific files (latest by mtime)
+  const stateDir = join(CACHE_DIR, "state");
+  if (existsSync(stateDir)) {
+    const prefix = agentName.replace(/-/g, "_") + "_";
+    const matches = readdirSync(stateDir).filter(
+      (f) => f.startsWith(prefix) && f.endsWith(".md"),
+    );
+    if (matches.length > 0) {
+      let latest = join(stateDir, matches[0]);
+      let latestMtime = statSync(latest).mtimeMs;
+      for (let i = 1; i < matches.length; i++) {
+        const p = join(stateDir, matches[i]);
+        const mt = statSync(p).mtimeMs;
+        if (mt > latestMtime) {
+          latest = p;
+          latestMtime = mt;
+        }
+      }
+      return latest;
+    }
+  }
+
+  // 2. Fall back to KB briefings directory (latest by name)
+  if (agentConfig.kb) {
+    const dir = join(expandPath(agentConfig.kb), "knowledge", "Briefings");
+    if (existsSync(dir)) {
+      const files = readdirSync(dir)
+        .filter((f) => f.endsWith(".md"))
+        .sort()
+        .reverse();
+      if (files.length > 0) return join(dir, files[0]);
+    }
+  }
+
+  return null;
+}
+
 // --- Socket server ----------------------------------------------------------
 
 /** @param {import('node:net').Socket} socket @param {object} data */
@@ -392,19 +443,23 @@ function handleStatusRequest(socket) {
   const config = loadConfig();
   const state = loadState();
   const now = new Date();
-  const tasks = {};
-
-  for (const [name, task] of Object.entries(config.tasks)) {
-    const ts = state.tasks[name] || {};
-    tasks[name] = {
-      enabled: task.enabled !== false,
-      status: ts.status || "never-run",
-      lastRunAt: ts.lastRunAt || null,
-      nextRunAt: computeNextRunAt(task, ts, now),
-      runCount: ts.runCount || 0,
-      lastError: ts.lastError || null,
+  const agents = {};
+
+  for (const [name, agent] of Object.entries(config.agents)) {
+    const as = state.agents[name] || {};
+    agents[name] = {
+      enabled: agent.enabled !== false,
+      status: as.status || "never-woken",
+      lastWokeAt: as.lastWokeAt || null,
+      nextWakeAt: computeNextWakeAt(agent, as, now),
+      lastAction: as.lastAction || null,
+      lastDecision: as.lastDecision || null,
+      wakeCount: as.wakeCount || 0,
+      lastError: as.lastError || null,
+      kbPath: agent.kb ? expandPath(agent.kb) : null,
+      briefingFile: resolveBriefingFile(name, agent),
     };
-    if (ts.startedAt) tasks[name].startedAt = ts.startedAt;
+    if (as.startedAt) agents[name].startedAt = as.startedAt;
   }
 
   send(socket, {
@@ -412,7 +467,7 @@ function handleStatusRequest(socket) {
     uptime: daemonStartedAt
       ? Math.floor((Date.now() - daemonStartedAt) / 1000)
       : 0,
-    tasks,
+    agents,
   });
 }
 
@@ -427,23 +482,31 @@ function handleMessage(socket, line) {
 
   if (request.type === "status") return handleStatusRequest(socket);
 
-  if (request.type === "run") {
-    if (!request.task) {
-      send(socket, { type: "error", message: "Missing task name" });
+  if (request.type === "shutdown") {
+    log("Shutdown requested via socket.");
+    send(socket, { type: "ack", command: "shutdown" });
+    socket.end();
+    killActiveChildren();
+    process.exit(0);
+  }
+
+  if (request.type === "wake") {
+    if (!request.agent) {
+      send(socket, { type: "error", message: "Missing agent name" });
       return;
     }
     const config = loadConfig();
-    const task = config.tasks[request.task];
-    if (!task) {
+    const agent = config.agents[request.agent];
+    if (!agent) {
       send(socket, {
         type: "error",
-        message: `Task not found: ${request.task}`,
+        message: `Agent not found: ${request.agent}`,
       });
       return;
     }
-    send(socket, { type: "ack", command: "run", task: request.task });
+    send(socket, { type: "ack", command: "wake", agent: request.agent });
     const state = loadState();
-    runTask(request.task, task, config, state).catch(() => {});
+    wakeAgent(request.agent, agent, state).catch(() => {});
     return;
   }
 
@@ -482,7 +545,11 @@ function startSocketServer() {
   });
 
   const cleanup = () => {
+    killActiveChildren();
     server.close();
+    try {
+      unlinkSync(SOCKET_PATH);
+    } catch {}
     process.exit(0);
   };
   process.on("SIGTERM", cleanup);
@@ -491,17 +558,87 @@ function startSocketServer() {
   return server;
 }
 
+// --- Graceful shutdown -------------------------------------------------------
+
+/**
+ * Send SIGTERM to all tracked child processes (running claude sessions).
+ * Called on daemon shutdown to prevent orphaned processes.
+ */
+function killActiveChildren() {
+  for (const pid of activeChildren) {
+    try {
+      process.kill(pid, "SIGTERM");
+      log(`Sent SIGTERM to child PID ${pid}`);
+    } catch {
+      // Already exited
+    }
+  }
+  activeChildren.clear();
+}
+
+/**
+ * Connect to the daemon socket and request graceful shutdown.
+ * Waits up to 5 seconds for the daemon to exit.
+ * @returns {Promise<boolean>} true if shutdown succeeded
+ */
+async function requestShutdown() {
+  if (!existsSync(SOCKET_PATH)) {
+    console.log("Daemon not running (no socket).");
+    return false;
+  }
+
+  const { createConnection } = await import("node:net");
+  return new Promise((resolve) => {
+    const timeout = setTimeout(() => {
+      console.log("Shutdown timed out.");
+      socket.destroy();
+      resolve(false);
+    }, 5000);
+
+    const socket = createConnection(SOCKET_PATH, () => {
+      socket.write(JSON.stringify({ type: "shutdown" }) + "\n");
+    });
+
+    let buffer = "";
+    socket.on("data", (data) => {
+      buffer += data.toString();
+      if (buffer.includes("\n")) {
+        clearTimeout(timeout);
+        console.log("Daemon stopped.");
+        socket.destroy();
+        resolve(true);
+      }
+    });
+
+    socket.on("error", () => {
+      clearTimeout(timeout);
+      console.log("Daemon not running (connection refused).");
+      resolve(false);
+    });
+
+    socket.on("close", () => {
+      clearTimeout(timeout);
+      resolve(true);
+    });
+  });
+}
+
 // --- Daemon -----------------------------------------------------------------
 
 function daemon() {
   daemonStartedAt = Date.now();
   log("Scheduler daemon started. Polling every 60 seconds.");
   log(`Config: ${CONFIG_PATH}  State: ${STATE_PATH}`);
+
+  // Reset any agents left "active" from a previous daemon session.
+  const state = loadState();
+  resetStaleAgents(state, { reason: "Daemon restarted" });
+
   startSocketServer();
-  runDueTasks().catch((err) => log(`Error: ${err.message}`));
+  wakeDueAgents().catch((err) => log(`Error: ${err.message}`));
   setInterval(async () => {
     try {
-      await runDueTasks();
+      await wakeDueAgents();
     } catch (err) {
       log(`Error: ${err.message}`);
     }
@@ -510,7 +647,11 @@ function daemon() {
 
 // --- Init knowledge base ----------------------------------------------------
 
-function findTemplateDir() {
+/**
+ * Resolve the template directory or exit with an error.
+ * @returns {string}
+ */
+function requireTemplateDir() {
   const bundle = getBundlePath();
   if (bundle) {
     const tpl = join(bundle.resources, "template");
@@ -521,7 +662,91 @@ function findTemplateDir() {
     join(__dirname, "..", "template"),
   ])
     if (existsSync(d)) return d;
-  return null;
+  console.error("Template not found. Reinstall fit-basecamp.");
+  process.exit(1);
+}
+
+/**
+ * Copy bundled files (CLAUDE.md, skills, agents) from template to a KB.
+ * Shared by --init and --update.
+ * @param {string} tpl  Path to the template directory
+ * @param {string} dest Path to the target knowledge base
+ */
+function copyBundledFiles(tpl, dest) {
+  // CLAUDE.md
+  copyFileSync(join(tpl, "CLAUDE.md"), join(dest, "CLAUDE.md"));
+  console.log(`  Updated CLAUDE.md`);
+
+  // Settings — merge template permissions into existing settings
+  mergeSettings(tpl, dest);
+
+  // Skills and agents
+  for (const sub of ["skills", "agents"]) {
+    const src = join(tpl, ".claude", sub);
+    if (!existsSync(src)) continue;
+    cpSync(src, join(dest, ".claude", sub), { recursive: true });
+    const entries = readdirSync(src, { withFileTypes: true }).filter((d) =>
+      sub === "skills" ? d.isDirectory() : d.name.endsWith(".md"),
+    );
+    const names = entries.map((d) =>
+      sub === "agents" ? d.name.replace(".md", "") : d.name,
+    );
+    console.log(`  Updated ${names.length} ${sub}: ${names.join(", ")}`);
+  }
+}
+
+/**
+ * Merge template settings.json into the destination's settings.json.
+ * Adds any missing entries from allow, deny, and additionalDirectories
+ * without removing user customizations.
+ * @param {string} tpl Template directory
+ * @param {string} dest Knowledge base directory
+ */
+function mergeSettings(tpl, dest) {
+  const src = join(tpl, ".claude", "settings.json");
+  if (!existsSync(src)) return;
+
+  const destPath = join(dest, ".claude", "settings.json");
+
+  // No existing settings — copy template directly
+  if (!existsSync(destPath)) {
+    ensureDir(join(dest, ".claude"));
+    copyFileSync(src, destPath);
+    console.log(`  Created settings.json`);
+    return;
+  }
+
+  const template = readJSON(src, {});
+  const existing = readJSON(destPath, {});
+  const tp = template.permissions || {};
+  const ep = (existing.permissions ||= {});
+  let added = 0;
+
+  // Merge array fields
+  for (const key of ["allow", "deny", "additionalDirectories"]) {
+    if (!tp[key]?.length) continue;
+    const set = new Set((ep[key] ||= []));
+    for (const entry of tp[key]) {
+      if (!set.has(entry)) {
+        ep[key].push(entry);
+        set.add(entry);
+        added++;
+      }
+    }
+  }
+
+  // Merge scalar fields
+  if (tp.defaultMode && !ep.defaultMode) {
+    ep.defaultMode = tp.defaultMode;
+    added++;
+  }
+
+  if (added > 0) {
+    writeJSON(destPath, existing);
+    console.log(`  Updated settings.json (${added} new entries)`);
+  } else {
+    console.log(`  Settings up to date`);
+  }
 }
 
 function initKB(targetPath) {
@@ -530,11 +755,7 @@ function initKB(targetPath) {
     console.error(`Knowledge base already exists at ${dest}`);
     process.exit(1);
   }
-  const tpl = findTemplateDir();
-  if (!tpl) {
-    console.error("Template not found. Reinstall fit-basecamp.");
-    process.exit(1);
-  }
+  const tpl = requireTemplateDir();
 
   ensureDir(dest);
   for (const d of [
@@ -542,16 +763,74 @@ function initKB(targetPath) {
     "knowledge/Organizations",
     "knowledge/Projects",
     "knowledge/Topics",
+    "knowledge/Briefings",
   ])
     ensureDir(join(dest, d));
 
-  execSync(`cp -R "${tpl}/." "${dest}/"`);
+  // User-specific files (not overwritten by --update)
+  copyFileSync(join(tpl, "USER.md"), join(dest, "USER.md"));
+
+  // Bundled files (shared with --update)
+  copyBundledFiles(tpl, dest);
 
   console.log(
     `Knowledge base initialized at ${dest}\n\nNext steps:\n  1. Edit ${dest}/USER.md with your name, email, and domain\n  2. cd ${dest} && claude`,
   );
 }
 
+// --- Update knowledge base --------------------------------------------------
+
+/**
+ * Update an existing knowledge base with the latest bundled files.
+ * User data (USER.md, knowledge/) is untouched.
+ * Settings.json is merged — new template entries are added without
+ * removing user customizations.
+ * @param {string} targetPath
+ */
+function updateKB(targetPath) {
+  const dest = expandPath(targetPath);
+  if (!existsSync(join(dest, "CLAUDE.md"))) {
+    console.error(`No knowledge base found at ${dest}`);
+    process.exit(1);
+  }
+  const tpl = requireTemplateDir();
+  copyBundledFiles(tpl, dest);
+  console.log(`\nKnowledge base updated: ${dest}`);
+}
+
+/**
+ * Run --update for an explicit path or every unique KB in the scheduler config.
+ */
+function runUpdate() {
+  if (args[1]) {
+    updateKB(args[1]);
+    return;
+  }
+
+  // Discover unique KB paths from config
+  const config = loadConfig();
+  const kbPaths = [
+    ...new Set(
+      Object.values(config.agents)
+        .filter((a) => a.kb)
+        .map((a) => expandPath(a.kb)),
+    ),
+  ];
+
+  if (kbPaths.length === 0) {
+    console.error(
+      "No knowledge bases configured and no path given.\n" +
+        "Usage: fit-basecamp --update [path]",
+    );
+    process.exit(1);
+  }
+
+  for (const kb of kbPaths) {
+    console.log(`\nUpdating ${kb}...`);
+    updateKB(kb);
+  }
+}
+
 // --- Status -----------------------------------------------------------------
 
 function showStatus() {
@@ -559,23 +838,23 @@ function showStatus() {
     state = loadState();
   console.log("\nBasecamp Scheduler\n==================\n");
 
-  const tasks = Object.entries(config.tasks || {});
-  if (tasks.length === 0) {
-    console.log(`No tasks configured.\n\nEdit ${CONFIG_PATH} to add tasks.`);
+  const agents = Object.entries(config.agents || {});
+  if (agents.length === 0) {
+    console.log(`No agents configured.\n\nEdit ${CONFIG_PATH} to add agents.`);
     return;
   }
 
-  console.log("Tasks:");
-  for (const [name, task] of tasks) {
-    const s = state.tasks[name] || {};
+  console.log("Agents:");
+  for (const [name, agent] of agents) {
+    const s = state.agents[name] || {};
     const kbStatus =
-      task.kb && !existsSync(expandPath(task.kb)) ? " (not found)" : "";
+      agent.kb && !existsSync(expandPath(agent.kb)) ? " (not found)" : "";
     console.log(
-      `  ${task.enabled !== false ? "+" : "-"} ${name}\n` +
-        `    KB: ${task.kb || "(none)"}${kbStatus}  Schedule: ${JSON.stringify(task.schedule)}\n` +
-        `    Status: ${s.status || "never-run"}  Last: ${s.lastRunAt ? new Date(s.lastRunAt).toLocaleString() : "never"}  Runs: ${s.runCount || 0}` +
-        (task.agent ? `\n    Agent: ${task.agent}` : "") +
-        (task.skill ? `\n    Skill: ${task.skill}` : "") +
+      `  ${agent.enabled !== false ? "+" : "-"} ${name}\n` +
+        `    KB: ${agent.kb || "(none)"}${kbStatus}  Schedule: ${JSON.stringify(agent.schedule)}\n` +
+        `    Status: ${s.status || "never-woken"}  Last wake: ${s.lastWokeAt ? new Date(s.lastWokeAt).toLocaleString() : "never"}  Wakes: ${s.wakeCount || 0}` +
+        (s.lastAction ? `\n    Last action: ${s.lastAction}` : "") +
+        (s.lastDecision ? `\n    Last decision: ${s.lastDecision}` : "") +
         (s.lastError ? `\n    Error: ${s.lastError.slice(0, 80)}` : ""),
     );
   }
@@ -593,46 +872,34 @@ function findInLocalOrGlobal(kbPath, subPath) {
 
 function validate() {
   const config = loadConfig();
-  const tasks = Object.entries(config.tasks || {});
-  if (tasks.length === 0) {
-    console.log("No tasks configured. Nothing to validate.");
+  const agents = Object.entries(config.agents || {});
+  if (agents.length === 0) {
+    console.log("No agents configured. Nothing to validate.");
     return;
   }
 
-  console.log("\nValidating tasks...\n");
+  console.log("\nValidating agents...\n");
   let errors = 0;
 
-  for (const [name, task] of tasks) {
-    if (!task.kb) {
+  for (const [name, agent] of agents) {
+    if (!agent.kb) {
       console.log(`  [FAIL] ${name}: no "kb" path specified`);
       errors++;
       continue;
     }
-    const kbPath = expandPath(task.kb);
+    const kbPath = expandPath(agent.kb);
     if (!existsSync(kbPath)) {
       console.log(`  [FAIL] ${name}: path not found: ${kbPath}`);
       errors++;
       continue;
     }
 
-    for (const [kind, sub] of [
-      ["agent", task.agent],
-      ["skill", task.skill],
-    ]) {
-      if (!sub) continue;
-      const relPath =
-        kind === "agent"
-          ? join("agents", sub.endsWith(".md") ? sub : sub + ".md")
-          : join("skills", sub, "SKILL.md");
-      const found = findInLocalOrGlobal(kbPath, relPath);
-      console.log(
-        `  [${found ? "OK" : "FAIL"}]  ${name}: ${kind} "${sub}"${found ? "" : " not found"}`,
-      );
-      if (!found) errors++;
-    }
-
-    if (!task.agent && !task.skill)
-      console.log(`  [OK]   ${name}: no agent or skill to validate`);
+    const agentFile = join("agents", name + ".md");
+    const found = findInLocalOrGlobal(kbPath, agentFile);
+    console.log(
+      `  [${found ? "OK" : "FAIL"}]  ${name}: agent definition${found ? "" : " not found"}`,
+    );
+    if (!found) errors++;
   }
 
   console.log(errors > 0 ? `\n${errors} error(s).` : "\nAll OK.");
@@ -644,15 +911,17 @@ function validate() {
 function showHelp() {
   const bin = "fit-basecamp";
   console.log(`
-Basecamp — Run scheduled Claude tasks across knowledge bases.
+Basecamp — Schedule autonomous agents across knowledge bases.
 
 Usage:
-  ${bin}                     Run due tasks once and exit
+  ${bin}                     Wake due agents once and exit
   ${bin} --daemon            Run continuously (poll every 60s)
-  ${bin} --run <task>        Run a specific task immediately
+  ${bin} --wake <agent>      Wake a specific agent immediately
   ${bin} --init <path>       Initialize a new knowledge base
-  ${bin} --validate          Validate agents and skills exist
-  ${bin} --status            Show task status
+  ${bin} --update [path]     Update KB with latest CLAUDE.md, agents and skills
+  ${bin} --stop              Gracefully stop daemon and all running agents
+  ${bin} --validate          Validate agent definitions exist
+  ${bin} --status            Show agent status
 
 Config:  ~/.fit/basecamp/scheduler.json
 State:   ~/.fit/basecamp/state.json
@@ -666,35 +935,39 @@ const args = process.argv.slice(2);
 const command = args[0];
 ensureDir(BASECAMP_HOME);
 
+function requireArg(usage) {
+  if (!args[1]) {
+    console.error(usage);
+    process.exit(1);
+  }
+  return args[1];
+}
+
 const commands = {
   "--help": showHelp,
   "-h": showHelp,
   "--daemon": daemon,
   "--validate": validate,
-  "--status": showStatus,
-  "--init": () => {
-    if (!args[1]) {
-      console.error("Usage: node basecamp.js --init <path>");
-      process.exit(1);
-    }
-    initKB(args[1]);
+  "--stop": async () => {
+    const stopped = await requestShutdown();
+    if (!stopped) process.exit(1);
   },
-  "--run": async () => {
-    if (!args[1]) {
-      console.error("Usage: node basecamp.js --run <task-name>");
-      process.exit(1);
-    }
+  "--status": showStatus,
+  "--init": () => initKB(requireArg("Usage: fit-basecamp --init <path>")),
+  "--update": runUpdate,
+  "--wake": async () => {
+    const name = requireArg("Usage: fit-basecamp --wake <agent-name>");
     const config = loadConfig(),
       state = loadState(),
-      task = config.tasks[args[1]];
-    if (!task) {
+      agent = config.agents[name];
+    if (!agent) {
       console.error(
-        `Task "${args[1]}" not found. Available: ${Object.keys(config.tasks).join(", ") || "(none)"}`,
+        `Agent "${name}" not found. Available: ${Object.keys(config.agents).join(", ") || "(none)"}`,
       );
       process.exit(1);
     }
-    await runTask(args[1], task, config, state);
+    await wakeAgent(name, agent, state);
   },
 };
 
-await (commands[command] || runDueTasks)();
+await (commands[command] || wakeDueAgents)();