@forwardimpact/basecamp 2.0.0 → 2.3.0

package/config/scheduler.json

@@ -19,6 +19,11 @@
       "kb": "~/Documents/Personal",
       "schedule": { "type": "cron", "expression": "0 7,18 * * *" },
       "enabled": true
+    },
+    "recruiter": {
+      "kb": "~/Documents/Personal",
+      "schedule": { "type": "interval", "minutes": 30 },
+      "enabled": true
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/basecamp",
-  "version": "2.0.0",
+  "version": "2.3.0",
   "description": "Claude Code-native personal knowledge system with autonomous agents",
   "license": "Apache-2.0",
   "repository": {

package/src/basecamp.js

@@ -7,6 +7,8 @@
 //   node basecamp.js --daemon            Run continuously (poll every 60s)
 //   node basecamp.js --wake <agent>      Wake a specific agent immediately
 //   node basecamp.js --init <path>       Initialize a new knowledge base
+//   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
@@ -20,8 +22,9 @@ import {
   chmodSync,
   readdirSync,
   statSync,
+  cpSync,
+  copyFileSync,
 } from "node:fs";
-import { execSync } from "node:child_process";
 import { join, dirname, resolve } from "node:path";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
@@ -48,10 +51,13 @@ let daemonStartedAt = null;
 // 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) {
@@ -162,13 +168,8 @@ function cronMatches(expr, d) {
 // --- Scheduling logic -------------------------------------------------------
 
 function floorToMinute(d) {
-  return new Date(
-    d.getFullYear(),
-    d.getMonth(),
-    d.getDate(),
-    d.getHours(),
-    d.getMinutes(),
-  ).getTime();
+  const t = d.getTime();
+  return t - (t % 60_000);
 }
 
 function shouldWake(agent, agentState, now) {
@@ -197,7 +198,16 @@ function shouldWake(agent, agentState, now) {
 
 // --- Agent execution --------------------------------------------------------
 
-async function wakeAgent(agentName, agent, _config, state) {
+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;
@@ -226,6 +236,7 @@ async function wakeAgent(agentName, agent, _config, state) {
       undefined,
       kbPath,
     );
+    activeChildren.add(pid);
 
     // Read stdout and stderr concurrently to avoid pipe deadlocks,
     // then wait for the child to exit.
@@ -234,6 +245,7 @@ async function wakeAgent(agentName, agent, _config, state) {
       posixSpawn.readAll(stderrFd),
     ]);
     const exitCode = await posixSpawn.waitForExit(pid);
+    activeChildren.delete(pid);
 
     if (exitCode === 0) {
       log(`Agent ${agentName} completed. Output: ${stdout.slice(0, 200)}...`);
@@ -241,24 +253,13 @@ async function wakeAgent(agentName, agent, _config, state) {
     } else {
       const errMsg = stderr || stdout || `Exit code ${exitCode}`;
       log(`Agent ${agentName} failed: ${errMsg.slice(0, 300)}`);
-      Object.assign(as, {
-        status: "failed",
-        startedAt: null,
-        lastWokeAt: new Date().toISOString(),
-        lastError: errMsg.slice(0, 500),
-      });
+      failAgent(as, errMsg);
     }
-    saveState(state);
   } catch (err) {
     log(`Agent ${agentName} failed: ${err.message}`);
-    Object.assign(as, {
-      status: "failed",
-      startedAt: null,
-      lastWokeAt: new Date().toISOString(),
-      lastError: err.message.slice(0, 500),
-    });
-    saveState(state);
+    failAgent(as, err.message);
   }
+  saveState(state);
 }
 
 /**
@@ -336,7 +337,7 @@ async function wakeDueAgents() {
   let wokeAny = false;
   for (const [name, agent] of Object.entries(config.agents)) {
     if (shouldWake(agent, state.agents[name] || {}, now)) {
-      await wakeAgent(name, agent, config, state);
+      await wakeAgent(name, agent, state);
       wokeAny = true;
     }
   }
@@ -392,25 +393,31 @@ function computeNextWakeAt(agent, agentState, now) {
  * @returns {string|null}
  */
 function resolveBriefingFile(agentName, agentConfig) {
-  // 1. Scan state directory for agent-specific files
+  // 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 === 1) return join(stateDir, matches[0]);
-    if (matches.length > 1) {
-      return matches
-        .map((f) => join(stateDir, f))
-        .sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs)[0];
+    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
+  // 2. Fall back to KB briefings directory (latest by name)
   if (agentConfig.kb) {
-    const kbPath = expandPath(agentConfig.kb);
-    const dir = join(kbPath, "knowledge", "Briefings");
+    const dir = join(expandPath(agentConfig.kb), "knowledge", "Briefings");
     if (existsSync(dir)) {
       const files = readdirSync(dir)
         .filter((f) => f.endsWith(".md"))
@@ -475,6 +482,14 @@ function handleMessage(socket, line) {
 
   if (request.type === "status") return handleStatusRequest(socket);
 
+  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" });
@@ -491,7 +506,7 @@ function handleMessage(socket, line) {
     }
     send(socket, { type: "ack", command: "wake", agent: request.agent });
     const state = loadState();
-    wakeAgent(request.agent, agent, config, state).catch(() => {});
+    wakeAgent(request.agent, agent, state).catch(() => {});
     return;
   }
 
@@ -530,7 +545,11 @@ function startSocketServer() {
   });
 
   const cleanup = () => {
+    killActiveChildren();
     server.close();
+    try {
+      unlinkSync(SOCKET_PATH);
+    } catch {}
     process.exit(0);
   };
   process.on("SIGTERM", cleanup);
@@ -539,6 +558,71 @@ 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() {
@@ -563,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");
@@ -574,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) {
@@ -583,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 [
@@ -599,13 +767,70 @@ function initKB(targetPath) {
   ])
     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() {
@@ -693,6 +918,8 @@ Usage:
   ${bin} --daemon            Run continuously (poll every 60s)
   ${bin} --wake <agent>      Wake a specific agent immediately
   ${bin} --init <path>       Initialize a new knowledge base
+  ${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
 
@@ -708,34 +935,38 @@ 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);
   },
+  "--status": showStatus,
+  "--init": () => initKB(requireArg("Usage: fit-basecamp --init <path>")),
+  "--update": runUpdate,
   "--wake": async () => {
-    if (!args[1]) {
-      console.error("Usage: node basecamp.js --wake <agent-name>");
-      process.exit(1);
-    }
+    const name = requireArg("Usage: fit-basecamp --wake <agent-name>");
     const config = loadConfig(),
       state = loadState(),
-      agent = config.agents[args[1]];
+      agent = config.agents[name];
     if (!agent) {
       console.error(
-        `Agent "${args[1]}" not found. Available: ${Object.keys(config.agents).join(", ") || "(none)"}`,
+        `Agent "${name}" not found. Available: ${Object.keys(config.agents).join(", ") || "(none)"}`,
       );
       process.exit(1);
     }
-    await wakeAgent(args[1], agent, config, state);
+    await wakeAgent(name, agent, state);
   },
 };
 

package/template/.claude/agents/chief-of-staff.md

@@ -6,6 +6,8 @@ description: >
   key moments (morning, evening) by the Basecamp scheduler.
 model: sonnet
 permissionMode: bypassPermissions
+skills:
+  - weekly-update
 ---
 
 You are the chief of staff — the user's executive assistant. You create daily
@@ -18,10 +20,12 @@ Read the state files from other agents:
 
 1. **Postman:** `~/.cache/fit/basecamp/state/postman_triage.md`
    - Urgent emails, items needing reply, threads awaiting response
-2. **Concierge:** `~/.cache/fit/basecamp/state/concierge_outlook.md`
+2. **Concierge:** `~/.cache/fit/basecamp/state/concierge_triage.md`
    - Today's meetings, prep status, unprocessed transcripts
-3. **Librarian:** `~/.cache/fit/basecamp/state/librarian_digest.md`
+3. **Librarian:** `~/.cache/fit/basecamp/state/librarian_triage.md`
    - Pending processing, graph size
+4. **Recruiter:** `~/.cache/fit/basecamp/state/recruiter_triage.md`
+   - Candidate pipeline, new assessments, interview scheduling
 
 Also read directly:
 

package/template/.claude/agents/concierge.md

@@ -36,11 +36,10 @@ Assess the current state:
    - Check each session's `_memo.md` against
      `~/.cache/fit/basecamp/state/graph_processed`
 
-Write the calendar outlook to
-`~/.cache/fit/basecamp/state/concierge_outlook.md`:
+Write triage results to `~/.cache/fit/basecamp/state/concierge_triage.md`:
 
 ```
-# Calendar Outlook — {YYYY-MM-DD HH:MM}
+# Calendar Triage — {YYYY-MM-DD HH:MM}
 
 ## Next Meeting
 **{title}** at {time} with {attendees}

package/template/.claude/agents/librarian.md

@@ -9,6 +9,7 @@ permissionMode: bypassPermissions
 skills:
   - extract-entities
   - organize-files
+  - manage-tasks
 ---
 
 You are the librarian — the user's knowledge curator. Each time you are woken,
@@ -20,20 +21,17 @@ Assess what needs processing:
 
 1.  Check for unprocessed synced files (mail and calendar data):
 
-        python3 scripts/state.py check
-
-    (Run from the extract-entities skill directory:
-    `.claude/skills/extract-entities/`)
+        node .claude/skills/extract-entities/scripts/state.mjs check
 
 2.  Count existing knowledge graph entities:
 
     ls knowledge/People/ knowledge/Organizations/ knowledge/Projects/
     knowledge/Topics/ 2>/dev/null | wc -l
 
-Write your digest to `~/.cache/fit/basecamp/state/librarian_digest.md`:
+Write triage results to `~/.cache/fit/basecamp/state/librarian_triage.md`:
 
 ```
-# Knowledge Digest — {YYYY-MM-DD HH:MM}
+# Knowledge Triage — {YYYY-MM-DD HH:MM}
 
 ## Pending Processing
 - {count} unprocessed synced files