@cohortapp/agent-sdk 2.6.0 → 2.6.1

package/bin/maestro.mjs

@@ -21,6 +21,7 @@ import {
   readdirSync,
   statSync,
   lstatSync,
+  unlinkSync,
   openSync,
   readSync,
   closeSync,
@@ -767,6 +768,23 @@ const UPGRADE_PATHS = [
   { path: "archetypes", mode: "smart" },
 ];
 
+// Directories that sit under a "smart" upgrade root but hold MACHINE-GENERATED
+// artifacts rather than framework files — launchd plists rendered per-machine
+// from config/agent.json. Upstream ships no copy of them by design, so to the
+// prune pass they look exactly like orphans: tracked, clean, and absent from
+// the SDK. Git cannot tell the difference, because there is no difference to
+// see — the intent lives in the directory, not the file state. Deleting them
+// would destroy this machine's schedule (and would race the cadence-bus
+// migration, which backs these same plists up and regenerates them).
+const PRUNE_EXCLUDE_PREFIXES = [
+  "scripts/local-triggers/plists/",
+  "scripts/poller-launchd/",
+];
+
+function isPruneExcluded(repoRel) {
+  return PRUNE_EXCLUDE_PREFIXES.some((p) => repoRel.startsWith(p));
+}
+
 function sha256File(p) {
   return createHash("sha256").update(readFileSync(p)).digest("hex");
 }
@@ -1074,11 +1092,13 @@ function parseUpgradeFlags(args) {
     forceOverwrite: false,
     noIncoming: false,
     verbose: false,
+    noPrune: false,
   };
   for (const a of args) {
     if (a === "--dry-run" || a === "-n") flags.dryRun = true;
     else if (a === "--force-overwrite" || a === "--force") flags.forceOverwrite = true;
     else if (a === "--no-incoming") flags.noIncoming = true;
+    else if (a === "--no-prune") flags.noPrune = true;
     else if (a === "--verbose" || a === "-v") flags.verbose = true;
     else if (a === "--help" || a === "-h") return null;
     else { fail(`Unknown flag: ${a}`); process.exit(1); }
@@ -1096,6 +1116,7 @@ Flags:
   --dry-run, -n          Preview changes without writing
   --force-overwrite      Overwrite even locally-modified files (backs them up)
   --no-incoming          Don't write .maestro/incoming/ shadows for preserved files
+  --no-prune             Keep framework files that upstream has deleted
   --verbose, -v          Print classification for every file
   --help, -h             Show this help
 
@@ -1108,6 +1129,9 @@ Per-file behaviour:
               .maestro/incoming/<path> for manual diff
   mergeKept — under agents/ → never overwrite (custom agents preserved)
   forced    — overwritten by --force-overwrite; backup at .maestro/backup/<path>
+  pruned    — deleted upstream and pristine here → removed; backup at
+              .maestro/backup/<path>. Only ever applies to files git reports as
+              tracked-and-clean, so your own files are never at risk.
 
 .maestroignore format (gitignore-style, top-down, last match wins):
   scripts/slack-send.sh          exact file
@@ -1145,9 +1169,11 @@ Per-file behaviour:
   const banner = flags.dryRun ? "DRY RUN — " : "";
   log(`${banner}Upgrading framework files from @cohortapp/agent-sdk...`);
 
-  const counts = { added: 0, updated: 0, same: 0, ignored: 0, preserved: 0, mergeKept: 0, forced: 0 };
+  const counts = { added: 0, updated: 0, same: 0, ignored: 0, preserved: 0, mergeKept: 0, forced: 0, pruned: 0, pruneKept: 0 };
   const preservedFiles = [];
   const ignoredFiles = [];
+  const prunedFiles = [];
+  const pruneKeptFiles = [];
 
   for (const { path: relRoot, mode } of UPGRADE_PATHS) {
     const srcRoot = join(MAESTRO_ROOT, relRoot);
@@ -1235,6 +1261,86 @@ Per-file behaviour:
     }
   }
 
+  // ── Prune: framework files this agent still holds but upstream deleted ─────
+  //
+  // The copy loop above is one-directional: it adds and overwrites, but never
+  // removes. So every file the SDK has ever shipped stays resident on an agent
+  // machine forever. That is not merely untidy — an orphan is a *stale module*
+  // that keeps importing symbols its collaborators no longer export, so it
+  // fails permanently and drags the agent's own test suite red. (Found in the
+  // field: scripts/daemon/responder.test.mjs survived the transport refactor
+  // and kept importing a deleted `loadConversationHistory`.)
+  //
+  // Prune asks the converse of the copy loop's question — "does the agent hold
+  // a file upstream deleted?" — and reuses the identical safety rules:
+  //
+  //   * .maestroignore still wins; an ignored path is never touched.
+  //   * "merge" roots (agents/) are skipped wholesale — files there are
+  //     *supposed* to exist only locally; that is the mode's entire purpose.
+  //   * Only files git reports as tracked-and-clean are removed. dirtyPathSet()
+  //     is built with --untracked-files=all, so a path absent from it is
+  //     provably a pristine framework file the operator never touched.
+  //     Anything else — edited, untracked, operator-authored — is kept and
+  //     reported, never deleted.
+  //   * Outside a git repo we cannot prove any of the above, so prune does
+  //     nothing at all rather than guess.
+  //
+  // Removals are backed up under .maestro/backup/ exactly like a forced
+  // overwrite, so a prune is always reversible.
+  if (flags.noPrune) {
+    log("Prune skipped (--no-prune): upstream-deleted files left in place.");
+  } else if (!inGit) {
+    warn("Prune skipped: not a git repo, so pristine framework files can't be told from yours.");
+  } else {
+    for (const { path: relRoot, mode } of UPGRADE_PATHS) {
+      // merge-mode roots hold deliberately-local files — nothing to reconcile.
+      if (mode === "merge") continue;
+      const srcRoot = join(MAESTRO_ROOT, relRoot);
+      const dstRoot = join(cwd, relRoot);
+      // If upstream dropped the whole root, treat it as out of scope rather
+      // than deleting an entire directory tree on the agent's machine.
+      if (!existsSync(srcRoot) || !existsSync(dstRoot)) continue;
+
+      for (const dstFile of walkFiles(dstRoot)) {
+        const relFromRoot = relative(dstRoot, dstFile);
+        if (existsSync(join(srcRoot, relFromRoot))) continue; // still shipped
+
+        const repoRel = relative(cwd, dstFile).split(sep).join("/");
+
+        // Machine-generated, not framework-shipped — see PRUNE_EXCLUDE_PREFIXES.
+        if (isPruneExcluded(repoRel)) {
+          if (flags.verbose) console.log(`  · ${repoRel} (machine-generated, never pruned)`);
+          continue;
+        }
+
+        if (matchesIgnore(repoRel, ignorePatterns)) {
+          counts.ignored++;
+          ignoredFiles.push(repoRel);
+          if (flags.verbose) console.log(`  · ${repoRel} (orphan, ignored via .maestroignore)`);
+          continue;
+        }
+
+        // Dirty covers edited AND untracked — either way it isn't ours to delete.
+        if (dirty.has(repoRel)) {
+          counts.pruneKept++;
+          pruneKeptFiles.push(repoRel);
+          if (flags.verbose) console.log(`  ~ ${repoRel} (deleted upstream, but yours — kept)`);
+          continue;
+        }
+
+        if (!flags.dryRun) {
+          const backup = join(cwd, ".maestro", "backup", repoRel);
+          mkdirSync(dirname(backup), { recursive: true });
+          copyFileSync(dstFile, backup);
+          unlinkSync(dstFile);
+        }
+        counts.pruned++;
+        prunedFiles.push(repoRel);
+        if (flags.verbose) warn(`- ${repoRel} (deleted upstream; backup written)`);
+      }
+    }
+  }
+
   // Ensure standard runtime directories exist.
   const ensureDirs = [
     "state/handoffs", "state/huddle", "state/indexes", "state/rag",
@@ -1383,8 +1489,21 @@ Per-file behaviour:
   if (counts.mergeKept) console.log(`  ~ ${counts.mergeKept} merge-mode kept (agents/ custom files preserved)`);
   if (counts.preserved) warn(`${counts.preserved} preserved (local edits — kept your version)`);
   if (counts.forced)    warn(`${counts.forced} force-overwritten (backups in .maestro/backup/)`);
+  if (counts.pruned)    ok(`${counts.pruned} pruned (deleted upstream; backups in .maestro/backup/)`);
+  if (counts.pruneKept) warn(`${counts.pruneKept} deleted upstream but kept (yours — edited or untracked)`);
   if (newDirs)          ok(`${newDirs} new directories created`);
 
+  if (prunedFiles.length && flags.verbose === false) {
+    for (const p of prunedFiles.slice(0, 5)) console.log(`    - ${p}`);
+    if (prunedFiles.length > 5) console.log(`    … and ${prunedFiles.length - 5} more`);
+  }
+  if (pruneKeptFiles.length) {
+    console.log();
+    log("These are gone from the framework but still present here — delete if you no longer want them:");
+    for (const p of pruneKeptFiles.slice(0, 5)) console.log(`    ${p}`);
+    if (pruneKeptFiles.length > 5) console.log(`    … and ${pruneKeptFiles.length - 5} more`);
+  }
+
   if (preservedFiles.length && !flags.noIncoming && !flags.dryRun) {
     console.log();
     log("Upstream versions of your locally-modified files saved to .maestro/incoming/");

package/bin/maestro.test.mjs

@@ -1140,3 +1140,185 @@ test("doctor surfaces the new framework systems (org / secrets / diagnostics)",
     await rmRoot(shim);
   }
 });
+
+// ---------------------------------------------------------------------------
+// upgrade — prune (framework files deleted upstream)
+//
+// The copy loop only ever adds and overwrites, so before this every file the
+// SDK had ever shipped stayed resident on an agent machine forever. Orphaned
+// *modules* keep importing symbols their collaborators no longer export, so
+// they fail permanently and drag the agent's own suite red — found in the
+// field on Isla's machine, where a stale scripts/daemon/responder.test.mjs
+// survived the transport refactor still importing a deleted export.
+//
+// Prune's contract is narrow on purpose: it removes a file only when git
+// proves it is tracked-and-clean, i.e. pristine framework material the
+// operator never touched. Everything else is kept and reported.
+// ---------------------------------------------------------------------------
+
+/**
+ * Agent repo carrying `orphans` — paths upstream does not ship. Written before
+ * the commit so git sees them as tracked and clean (prune's precondition).
+ */
+async function makeAgentWithOrphans(orphans) {
+  const root = await tmpRoot("maestro-orphan");
+  mkdirSync(join(root, "config"), { recursive: true });
+  writeFileSync(join(root, "CLAUDE.md"), "# agent\n");
+  writeFileSync(join(root, "config/agent.ts"), "export const AGENT = { firstName: 'orphan' };\n");
+  writeFileSync(join(root, "package.json"), '{"name":"orphan-agent","version":"1.0.0"}\n');
+  for (const [rel, body] of Object.entries(orphans)) {
+    mkdirSync(dirname(join(root, rel)), { recursive: true });
+    writeFileSync(join(root, rel), body);
+  }
+  execFileSync("git", ["init", "-q"], { cwd: root });
+  execFileSync("git", ["add", "-A"], { cwd: root });
+  execFileSync(
+    "git",
+    ["-c", "user.email=test@test", "-c", "user.name=test", "commit", "-q", "-m", "init"],
+    { cwd: root },
+  );
+  return root;
+}
+
+const ORPHAN = "lib/zz-deleted-upstream-fixture.mjs";
+
+test("upgrade prunes a pristine framework file deleted upstream, with a backup", async () => {
+  const root = await makeAgentWithOrphans({ [ORPHAN]: "export const gone = 1;\n" });
+  try {
+    const r = runCli(["upgrade"], root);
+    assert.equal(r.status, 0, r.stderr);
+    assert.ok(!existsSync(join(root, ORPHAN)), "orphan should have been pruned");
+    assert.ok(
+      existsSync(join(root, ".maestro/backup", ORPHAN)),
+      "prune must be reversible — a backup is required",
+    );
+    assert.equal(
+      readFileSync(join(root, ".maestro/backup", ORPHAN), "utf-8"),
+      "export const gone = 1;\n",
+      "backup must hold the original bytes",
+    );
+  } finally {
+    await fsp.rm(root, { recursive: true, force: true });
+  }
+});
+
+test("upgrade never prunes a file the operator edited", async () => {
+  const root = await makeAgentWithOrphans({ [ORPHAN]: "export const gone = 1;\n" });
+  try {
+    writeFileSync(join(root, ORPHAN), "export const gone = 2; // my change\n");
+    const r = runCli(["upgrade"], root);
+    assert.equal(r.status, 0, r.stderr);
+    assert.ok(existsSync(join(root, ORPHAN)), "an edited orphan is the operator's, not ours to delete");
+    assert.match(
+      readFileSync(join(root, ORPHAN), "utf-8"),
+      /my change/,
+      "the operator's bytes must survive verbatim",
+    );
+    assert.match(r.stdout, /kept/i, "the kept orphan must be reported, not silently left");
+  } finally {
+    await fsp.rm(root, { recursive: true, force: true });
+  }
+});
+
+test("upgrade never prunes an untracked file", async () => {
+  const root = await makeAgentWithOrphans({});
+  try {
+    // Written after the commit → untracked → indistinguishable from operator work.
+    mkdirSync(join(root, "lib"), { recursive: true });
+    writeFileSync(join(root, ORPHAN), "export const mine = 1;\n");
+    const r = runCli(["upgrade"], root);
+    assert.equal(r.status, 0, r.stderr);
+    assert.ok(existsSync(join(root, ORPHAN)), "untracked files are never prune candidates");
+  } finally {
+    await fsp.rm(root, { recursive: true, force: true });
+  }
+});
+
+test("upgrade --no-prune leaves upstream-deleted files in place", async () => {
+  const root = await makeAgentWithOrphans({ [ORPHAN]: "export const gone = 1;\n" });
+  try {
+    const r = runCli(["upgrade", "--no-prune"], root);
+    assert.equal(r.status, 0, r.stderr);
+    assert.ok(existsSync(join(root, ORPHAN)), "--no-prune must suppress removal entirely");
+  } finally {
+    await fsp.rm(root, { recursive: true, force: true });
+  }
+});
+
+test("upgrade --dry-run reports a prune without performing it", async () => {
+  const root = await makeAgentWithOrphans({ [ORPHAN]: "export const gone = 1;\n" });
+  try {
+    const r = runCli(["upgrade", "--dry-run"], root);
+    assert.equal(r.status, 0, r.stderr);
+    assert.ok(existsSync(join(root, ORPHAN)), "dry run must not delete");
+    assert.ok(!existsSync(join(root, ".maestro/backup", ORPHAN)), "dry run must not write backups");
+    assert.match(r.stdout, /prune/i, "dry run must still tell the operator what it would remove");
+  } finally {
+    await fsp.rm(root, { recursive: true, force: true });
+  }
+});
+
+test("upgrade honours .maestroignore over prune", async () => {
+  const root = await makeAgentWithOrphans({
+    [ORPHAN]: "export const gone = 1;\n",
+    ".maestroignore": `${ORPHAN}\n`,
+  });
+  try {
+    const r = runCli(["upgrade"], root);
+    assert.equal(r.status, 0, r.stderr);
+    assert.ok(existsSync(join(root, ORPHAN)), ".maestroignore must win over prune, as it does over overwrite");
+  } finally {
+    await fsp.rm(root, { recursive: true, force: true });
+  }
+});
+
+test("upgrade prune leaves files that upstream still ships", async () => {
+  const root = await makeAgentWithOrphans({});
+  try {
+    const r = runCli(["upgrade"], root);
+    assert.equal(r.status, 0, r.stderr);
+    // A file the SDK genuinely ships must survive — the guard against a prune
+    // that mistakes "present upstream" for "absent" and empties the repo.
+    assert.ok(
+      existsSync(join(root, "lib/identity/persona.mjs")),
+      "currently-shipped framework files must never be pruned",
+    );
+    assert.ok(existsSync(join(root, "scripts/daemon/responder.mjs")));
+  } finally {
+    await fsp.rm(root, { recursive: true, force: true });
+  }
+});
+
+test("upgrade prune never touches merge-mode agents/", async () => {
+  const custom = "agents/my-private-agent.md";
+  const root = await makeAgentWithOrphans({ [custom]: "# mine\n" });
+  try {
+    const r = runCli(["upgrade"], root);
+    assert.equal(r.status, 0, r.stderr);
+    assert.ok(
+      existsSync(join(root, custom)),
+      "agents/ is merge-mode: local-only files there are the point, not orphans",
+    );
+  } finally {
+    await fsp.rm(root, { recursive: true, force: true });
+  }
+});
+
+test("upgrade prune never removes machine-generated launchd plists", async () => {
+  // A committed plist is tracked, clean, and absent upstream — it satisfies
+  // every safety check prune has, yet it is this machine's schedule, not
+  // framework material. Regression: an early prune deleted the very plist the
+  // cadence-bus migration was about to back up and regenerate.
+  const plist = "scripts/local-triggers/plists/ai.adaptic.some-trigger.plist";
+  const root = await makeAgentWithOrphans({ [plist]: "<?xml version=\"1.0\"?><plist/>" });
+  try {
+    const r = runCli(["upgrade"], root);
+    assert.equal(r.status, 0, r.stderr);
+    assert.ok(
+      existsSync(join(root, plist)),
+      "generated plists are machine config; prune must leave them alone",
+    );
+  } finally {
+    await fsp.rm(root, { recursive: true, force: true });
+  }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cohortapp/agent-sdk",
-  "version": "2.6.0",
+  "version": "2.6.1",
   "description": "Cohort Agent SDK \u2014 autonomous AI colleague runtime. Deploy senior AI colleagues on dedicated Mac minis, wired to the Cohort operating surface.",
   "type": "module",
   "bin": {

package/scripts/daemon/classifier.test.mjs

@@ -25,21 +25,30 @@
 
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { createRequire } from "node:module";
+import { readFileSync } from "node:fs";
 
 import * as classifier from "./classifier.mjs";
 
 // ── 1. Imports cleanly with no openai package present ───────────────────────
 
-test("classifier.mjs imports cleanly with no openai package installed", () => {
+test("classifier.mjs imports cleanly and does not depend on openai", () => {
   // The module-level import above already succeeded (this file loaded), which
-  // is the load-bearing assertion. Double-check openai is genuinely absent so
-  // this test fails loudly if someone reintroduces the hard dependency.
-  const require = createRequire(import.meta.url);
-  assert.throws(
-    () => require.resolve("openai"),
-    /Cannot find module 'openai'|Cannot find package 'openai'/,
-    "openai must NOT be resolvable — the classifier must not depend on it"
+  // is the load-bearing assertion.
+  //
+  // The invariant is about THIS MODULE's source, not the ambient node_modules
+  // tree. An earlier version asserted `require.resolve("openai")` throws, but
+  // that is a proxy that only holds inside the SDK's own checkout: every agent
+  // repo that pulls openai in transitively made this fail while the real
+  // invariant stayed true. A guard that goes red on every downstream machine
+  // just teaches operators to ignore red suites, so assert on the source.
+  const src = readFileSync(new URL("./classifier.mjs", import.meta.url), "utf-8");
+  const importsOpenai = /(?:^|\n)\s*import[^\n]*["']openai["']/.test(src)
+    || /\bimport\(\s*["']openai["']\s*\)/.test(src)
+    || /\brequire\(\s*["']openai["']\s*\)/.test(src);
+  assert.equal(
+    importsOpenai,
+    false,
+    "classifier.mjs must not import openai — a hard dependency here broke the whole module on agents that lack it"
   );
   assert.equal(typeof classifier.classifyItem, "function", "classifyItem is exported");
 });