@cohortapp/agent-sdk 2.6.1 → 2.6.2

package/bin/maestro.mjs

@@ -785,6 +785,43 @@ function isPruneExcluded(repoRel) {
   return PRUNE_EXCLUDE_PREFIXES.some((p) => repoRel.startsWith(p));
 }
 
+// Record of what the framework actually delivered to THIS machine, written at
+// the end of every non-dry upgrade. Per-machine state, hence .maestro/.
+//
+// Prune needs to answer "did the framework once ship this file?", and git
+// cannot answer it. A tracked-and-clean file absent from upstream is EITHER a
+// framework file deleted upstream OR a file the operator wrote and committed
+// themselves — the two are byte-for-byte indistinguishable in git status.
+// Getting that wrong destroys operator work: the first cut of this pass
+// proposed deleting an agent's pre-commit secret-scan hook (protecting a live
+// org credential) and its hand-authored workflows, purely because the SDK had
+// never shipped them.
+//
+// So provenance is recorded explicitly. Prune considers a file only if the
+// PREVIOUS manifest lists it — proof this machine received it from the SDK.
+// A machine with no manifest yet prunes nothing and starts clean from the next
+// upgrade; that is the safe direction to fail.
+const SHIPPED_MANIFEST_REL = ".maestro/shipped-manifest.json";
+
+function loadShippedManifest(cwd) {
+  try {
+    const raw = JSON.parse(readFileSync(join(cwd, SHIPPED_MANIFEST_REL), "utf-8"));
+    if (Array.isArray(raw?.files)) return new Set(raw.files);
+  } catch {
+    // Absent or unreadable — caller treats this as "provenance unknown".
+  }
+  return null;
+}
+
+function writeShippedManifest(cwd, files) {
+  const dst = join(cwd, SHIPPED_MANIFEST_REL);
+  mkdirSync(dirname(dst), { recursive: true });
+  writeFileSync(
+    dst,
+    JSON.stringify({ version: 1, files: [...files].sort() }, null, 2) + "\n",
+  );
+}
+
 function sha256File(p) {
   return createHash("sha256").update(readFileSync(p)).digest("hex");
 }
@@ -1174,6 +1211,8 @@ Per-file behaviour:
   const ignoredFiles = [];
   const prunedFiles = [];
   const pruneKeptFiles = [];
+  // What upstream ships right now — becomes this machine's provenance record.
+  const shippedNow = new Set();
 
   for (const { path: relRoot, mode } of UPGRADE_PATHS) {
     const srcRoot = join(MAESTRO_ROOT, relRoot);
@@ -1185,6 +1224,9 @@ Per-file behaviour:
       const relFromRoot = relative(srcRoot, srcFile);
       const dstFile = join(dstRoot, relFromRoot);
       const repoRel = relative(cwd, dstFile).split(sep).join("/");
+      // Recorded regardless of what we then decide to do with the file: the
+      // manifest answers "does the framework ship this?", not "did we write it?"
+      shippedNow.add(repoRel);
 
       const isIgnored = matchesIgnore(repoRel, ignorePatterns);
 
@@ -1287,10 +1329,15 @@ Per-file behaviour:
   //
   // Removals are backed up under .maestro/backup/ exactly like a forced
   // overwrite, so a prune is always reversible.
+  const priorManifest = loadShippedManifest(cwd);
+
   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 if (!priorManifest) {
+    log("Prune skipped: no shipped-manifest yet, so framework files can't be told from your own.");
+    log(`Recording one now (${SHIPPED_MANIFEST_REL}); prune takes effect from the next upgrade.`);
   } else {
     for (const { path: relRoot, mode } of UPGRADE_PATHS) {
       // merge-mode roots hold deliberately-local files — nothing to reconcile.
@@ -1313,6 +1360,15 @@ Per-file behaviour:
           continue;
         }
 
+        // Provenance gate: unless a previous upgrade recorded delivering this
+        // file, it is the operator's until proven otherwise. See the note on
+        // SHIPPED_MANIFEST_REL — this is what stops prune eating hand-authored
+        // scripts, workflows and policies that merely sit under a smart root.
+        if (!priorManifest.has(repoRel)) {
+          if (flags.verbose) console.log(`  · ${repoRel} (never shipped by the framework — yours)`);
+          continue;
+        }
+
         if (matchesIgnore(repoRel, ignorePatterns)) {
           counts.ignored++;
           ignoredFiles.push(repoRel);
@@ -1341,6 +1397,18 @@ Per-file behaviour:
     }
   }
 
+  // Record provenance for the next run. Written even when nothing was pruned —
+  // it is what makes the FOLLOWING upgrade able to prune safely. Never written
+  // on a dry run, so --dry-run stays genuinely side-effect-free.
+  if (!flags.dryRun) {
+    try {
+      writeShippedManifest(cwd, shippedNow);
+    } catch (err) {
+      // Non-fatal: a missing manifest costs pruning, not correctness.
+      warn(`Could not write ${SHIPPED_MANIFEST_REL}: ${err.message}`);
+    }
+  }
+
   // Ensure standard runtime directories exist.
   const ensureDirs = [
     "state/handoffs", "state/huddle", "state/indexes", "state/rag",

package/bin/maestro.test.mjs

@@ -1160,7 +1160,7 @@ test("doctor surfaces the new framework systems (org / secrets / diagnostics)",
  * 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) {
+async function makeAgentWithOrphans(orphans, opts = {}) {
   const root = await tmpRoot("maestro-orphan");
   mkdirSync(join(root, "config"), { recursive: true });
   writeFileSync(join(root, "CLAUDE.md"), "# agent\n");
@@ -1170,6 +1170,17 @@ async function makeAgentWithOrphans(orphans) {
     mkdirSync(dirname(join(root, rel)), { recursive: true });
     writeFileSync(join(root, rel), body);
   }
+  // Provenance: prune only touches files a PREVIOUS upgrade recorded shipping.
+  // Without this the orphans are indistinguishable from operator-authored work
+  // and prune correctly refuses to act — so every prune test must seed it.
+  if (opts.seedManifest !== false) {
+    mkdirSync(join(root, ".maestro"), { recursive: true });
+    writeFileSync(
+      join(root, ".maestro/shipped-manifest.json"),
+      JSON.stringify({ version: 1, files: Object.keys(orphans).sort() }, null, 2) + "\n",
+    );
+  }
+
   execFileSync("git", ["init", "-q"], { cwd: root });
   execFileSync("git", ["add", "-A"], { cwd: root });
   execFileSync(
@@ -1322,3 +1333,72 @@ test("upgrade prune never removes machine-generated launchd plists", async () =>
     await fsp.rm(root, { recursive: true, force: true });
   }
 });
+
+test("upgrade prune spares operator-authored files the framework never shipped", async () => {
+  // The hazard that forced the provenance manifest. scripts/ is a smart root,
+  // so an operator's own committed script there is tracked, clean and absent
+  // upstream — every signal git can offer says "orphan". On a real agent
+  // machine this set included the pre-commit hook guarding a live org
+  // credential. Provenance, not cleanliness, is what makes prune safe.
+  const mine = "scripts/pre-commit-secret-scan.sh";
+  const root = await makeAgentWithOrphans({
+    [mine]: "#!/bin/sh\nexit 0\n",
+    [ORPHAN]: "export const gone = 1;\n",
+  });
+  try {
+    // Manifest records ONLY the framework file — the operator's script was
+    // never delivered by the SDK, so it must not be a prune candidate.
+    writeFileSync(
+      join(root, ".maestro/shipped-manifest.json"),
+      JSON.stringify({ version: 1, files: [ORPHAN] }, null, 2) + "\n",
+    );
+    execFileSync("git", ["add", "-A"], { cwd: root });
+    execFileSync(
+      "git",
+      ["-c", "user.email=test@test", "-c", "user.name=test", "commit", "-q", "-m", "manifest"],
+      { cwd: root },
+    );
+
+    const r = runCli(["upgrade"], root);
+    assert.equal(r.status, 0, r.stderr);
+    assert.ok(existsSync(join(root, mine)), "a file the framework never shipped is the operator's");
+    assert.ok(!existsSync(join(root, ORPHAN)), "the genuinely-shipped orphan should still prune");
+  } finally {
+    await fsp.rm(root, { recursive: true, force: true });
+  }
+});
+
+test("upgrade prunes nothing on a machine with no shipped-manifest, then records one", async () => {
+  const root = await makeAgentWithOrphans({ [ORPHAN]: "export const gone = 1;\n" }, { seedManifest: false });
+  try {
+    const first = runCli(["upgrade"], root);
+    assert.equal(first.status, 0, first.stderr);
+    assert.ok(
+      existsSync(join(root, ORPHAN)),
+      "with no provenance record, prune must do nothing rather than guess",
+    );
+    assert.ok(
+      existsSync(join(root, ".maestro/shipped-manifest.json")),
+      "the first run must record provenance so the next one can prune",
+    );
+    const manifest = JSON.parse(readFileSync(join(root, ".maestro/shipped-manifest.json"), "utf-8"));
+    assert.ok(manifest.files.includes("scripts/daemon/responder.mjs"), "manifest lists shipped files");
+    assert.ok(!manifest.files.includes(ORPHAN), "manifest must not list what upstream doesn't ship");
+  } finally {
+    await fsp.rm(root, { recursive: true, force: true });
+  }
+});
+
+test("upgrade --dry-run writes no shipped-manifest", async () => {
+  const root = await makeAgentWithOrphans({}, { seedManifest: false });
+  try {
+    const r = runCli(["upgrade", "--dry-run"], root);
+    assert.equal(r.status, 0, r.stderr);
+    assert.ok(
+      !existsSync(join(root, ".maestro/shipped-manifest.json")),
+      "--dry-run must stay side-effect-free, including provenance",
+    );
+  } finally {
+    await fsp.rm(root, { recursive: true, force: true });
+  }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cohortapp/agent-sdk",
-  "version": "2.6.1",
+  "version": "2.6.2",
   "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": {