@cohortapp/agent-sdk 2.5.1 → 2.6.1

package/bin/maestro.test.mjs

@@ -358,60 +358,123 @@ test("setup --status in an agent dir lists section detect() statuses", async ()
 // doctor cost-telemetry tripwire — pure predicate (observability F2)
 // ---------------------------------------------------------------------------
 
-test("summariseLedgerRows sums estimated_usd and counts rows; tolerates junk", () => {
+/** A measured session row in the shape the tracker now writes. */
+function measuredRow(over = {}) {
+  return {
+    ts: new Date().toISOString(), cadence: "inbox", source: "dispatcher",
+    model: "sonnet", input_tokens: 16, output_tokens: 5000,
+    cache_read_input_tokens: 553181, measurement: "measured",
+    estimated_usd: 0.241, total_cost_usd: 0.533412, ...over,
+  };
+}
+/** A session that ran but whose usage could not be read. */
+function unmeasuredRow(over = {}) {
+  return {
+    ts: new Date().toISOString(), cadence: "inbox", source: "dispatcher",
+    model: "sonnet", input_tokens: null, output_tokens: null,
+    measurement: "unknown", unmeasured_reason: "no-usage-field",
+    estimated_usd: null, total_cost_usd: null, ...over,
+  };
+}
+/** A message send: no model ran, so $0 is a fact rather than a gap. */
+function nonLlmRow(over = {}) {
+  return {
+    ts: new Date().toISOString(), source: "messaging", task_class: "messaging.send",
+    model: null, input_tokens: 0, output_tokens: 0, estimated_usd: 0, ...over,
+  };
+}
+
+test("summariseLedgerRows bills the authoritative cost, not the cache-blind estimate", () => {
+  const s = summariseLedgerRows([measuredRow(), measuredRow({ total_cost_usd: 1 })]);
+  assert.equal(s.rowCount, 2);
+  assert.equal(s.totalUsd, 1.533412, "total_cost_usd wins over estimated_usd");
+});
+
+test("summariseLedgerRows counts sessions, not attribution rows; tolerates junk", () => {
   const s = summariseLedgerRows([
-    { estimated_usd: 0.5 },
-    { estimated_usd: 1.25 },
-    { estimated_usd: "0.25" }, // numeric string coerced
-    { estimated_usd: NaN },    // ignored as 0
-    {},                        // counts as a row, $0
-    null,                      // skipped entirely
-    "garbage",                 // skipped entirely
+    measuredRow(), unmeasuredRow(), nonLlmRow(), null, "garbage",
   ]);
-  assert.equal(s.rowCount, 5, "only object rows count");
-  assert.equal(s.totalUsd, 2, "0.5 + 1.25 + 0.25 = 2.00");
+  assert.equal(s.rowCount, 2, "1 measured + 1 unmeasured; the send is not a session");
+  assert.equal(s.measured, 1);
+  assert.equal(s.unmeasured, 1);
+  assert.equal(s.nonLlmRows, 1);
 });
 
 test("summariseLedgerRows on empty input is zeroed", () => {
-  assert.deepEqual(summariseLedgerRows([]), { rowCount: 0, totalUsd: 0 });
-  assert.deepEqual(summariseLedgerRows(undefined), { rowCount: 0, totalUsd: 0 });
+  assert.equal(summariseLedgerRows([]).rowCount, 0);
+  assert.equal(summariseLedgerRows([]).totalUsd, 0);
+  assert.equal(summariseLedgerRows(undefined).rowCount, 0);
 });
 
-test("evaluateCostTripwire: rows exist but spend is $0 → RED (telemetry blind)", () => {
+test("evaluateCostTripwire: unmeasured rows → RED (the 0-vs-unknown distinction)", () => {
+  // The defect doctor exists to catch: a session ran and nobody priced it.
+  const t = evaluateCostTripwire({ rows: [measuredRow(), unmeasuredRow()], sessionCount: 2 });
+  assert.equal(t.red, true);
+  assert.equal(t.unmeasured, 1);
+  assert.match(t.reason, /NO token counts/);
+  assert.match(t.fix, /unmeasured_reason/);
+});
+
+test("evaluateCostTripwire: a genuine zero-token session is NOT unmeasured", () => {
+  // A model ran and emitted nothing. That is a measurement; it must stay GREEN
+  // as long as the day bills above $0 — otherwise doctor cries wolf.
   const t = evaluateCostTripwire({
-    rows: [{ estimated_usd: 0 }, { estimated_usd: 0 }, { estimated_usd: 0 }],
-    sessionCount: 0,
+    rows: [measuredRow(), measuredRow({ input_tokens: 40, output_tokens: 0, total_cost_usd: 0 })],
+    sessionCount: 2,
   });
+  assert.equal(t.red, false);
+  assert.equal(t.unmeasured, 0);
+});
+
+test("evaluateCostTripwire: sessions logged but no ledger rows → RED (unrecorded)", () => {
+  const t = evaluateCostTripwire({ rows: [], sessionCount: 3 });
   assert.equal(t.red, true);
-  assert.equal(t.status, "red");
-  assert.equal(t.rowCount, 3);
-  assert.equal(t.totalUsd, 0);
-  assert.match(t.reason, /blind/i);
+  assert.equal(t.unrecorded, 3);
+  assert.match(t.reason, /only 0 dispatcher row\(s\) reached the cost ledger/);
 });
 
-test("evaluateCostTripwire: no rows but heartbeat-active session → RED", () => {
-  // Daemon is live (heartbeat) but the ledger is empty → still blind.
-  const t = evaluateCostTripwire({ rows: [], sessionCount: 1 });
+test("evaluateCostTripwire: rows from ANOTHER writer do not mask an unrecorded dispatcher", () => {
+  // The population bug this replaced. `sessionCount` comes from the dispatcher's
+  // own session log; `rowCount` counted rows from every writer. With the
+  // responder now writing rows too, a dispatcher that had stopped recording
+  // entirely read as unrecorded:0 / GREEN — 35 real sessions unpriced, and the
+  // one detector meant to catch exactly that said nothing.
+  const responderRows = Array.from({ length: 40 }, () => measuredRow({ source: "responder" }));
+  const t = evaluateCostTripwire({ rows: responderRows, sessionCount: 35 });
+  assert.equal(t.red, true, "35 dispatcher sessions with 0 dispatcher rows is RED");
+  assert.equal(t.unrecorded, 35);
+  assert.equal(t.sourceRowCount, 0);
+  assert.match(t.reason, /dispatcher logged 35/);
+});
+
+test("evaluateCostTripwire: measured rows billing $0 → RED (pricing broken)", () => {
+  const t = evaluateCostTripwire({
+    rows: [measuredRow({ total_cost_usd: 0, estimated_usd: 0 })],
+    sessionCount: 1,
+  });
   assert.equal(t.red, true);
-  assert.equal(t.status, "red");
-  assert.match(t.reason, /blind/i);
+  assert.match(t.reason, /bill to \$0/);
+  assert.match(t.fix, /--cache-read-tokens/);
 });
 
 test("evaluateCostTripwire: no sessions and no rows → GREEN (nothing to measure)", () => {
   const t = evaluateCostTripwire({ rows: [], sessionCount: 0 });
   assert.equal(t.red, false);
-  assert.equal(t.status, "green");
   assert.match(t.reason, /nothing to measure/i);
 });
 
-test("evaluateCostTripwire: spend > 0 → GREEN even with sessions", () => {
-  const t = evaluateCostTripwire({
-    rows: [{ estimated_usd: 0 }, { estimated_usd: 0.42 }],
-    sessionCount: 1,
-  });
+test("evaluateCostTripwire: attribution-only day is quiet, not blind", () => {
+  // Regression guard for the false alarm this replaced: 41 message-send rows on
+  // 2026-08-11 would have armed the old tripwire all by themselves.
+  const t = evaluateCostTripwire({ rows: [nonLlmRow(), nonLlmRow()], sessionCount: 0 });
   assert.equal(t.red, false);
-  assert.equal(t.status, "green");
-  assert.equal(t.totalUsd, 0.42);
+  assert.match(t.reason, /nothing to measure/i);
+});
+
+test("evaluateCostTripwire: spend > 0 with every session measured → GREEN", () => {
+  const t = evaluateCostTripwire({ rows: [measuredRow()], sessionCount: 1 });
+  assert.equal(t.red, false);
+  assert.equal(t.totalUsd, 0.533412);
   assert.match(t.reason, /live/i);
 });
 
@@ -442,19 +505,19 @@ async function makeBareAgent() {
 
 function utcDate() { return new Date().toISOString().slice(0, 10); }
 
-test("doctor RED when today's ledger has rows but $0 spend", async () => {
+test("doctor RED when a session ran with no token counts recorded", async () => {
   const root = await makeBareAgent();
   try {
     mkdirSync(join(root, "state/cost-tracking"), { recursive: true });
     const ledger = join(root, "state/cost-tracking", `${utcDate()}.jsonl`);
     writeFileSync(ledger,
-      JSON.stringify({ ts: new Date().toISOString(), cadence: "inbox-processor", model: "sonnet", input_tokens: 0, output_tokens: 0, estimated_usd: 0 }) + "\n" +
-      JSON.stringify({ ts: new Date().toISOString(), cadence: "backlog-executor", model: "opus", input_tokens: 0, output_tokens: 0, estimated_usd: 0 }) + "\n"
+      JSON.stringify(unmeasuredRow({ unmeasured_reason: "no-usage-field" })) + "\n" +
+      JSON.stringify(unmeasuredRow({ cadence: "backlog", unmeasured_reason: "empty-stdout" })) + "\n"
     );
     const r = runCli(["doctor"], root);
     const out = (r.stdout || "") + (r.stderr || "");
     assert.match(out, /Cost telemetry BLIND/);
-    assert.match(out, /track-claude-usage\.mjs/);
+    assert.match(out, /NO token counts/);
   } finally { await rmRoot(root); }
 });
 
@@ -463,12 +526,10 @@ test("doctor GREEN when today's ledger records real spend", async () => {
   try {
     mkdirSync(join(root, "state/cost-tracking"), { recursive: true });
     const ledger = join(root, "state/cost-tracking", `${utcDate()}.jsonl`);
-    writeFileSync(ledger,
-      JSON.stringify({ ts: new Date().toISOString(), cadence: "inbox-processor", model: "sonnet", input_tokens: 1500, output_tokens: 320, estimated_usd: 0.0093 }) + "\n"
-    );
+    writeFileSync(ledger, JSON.stringify(measuredRow()) + "\n");
     const r = runCli(["doctor"], root);
     const out = (r.stdout || "") + (r.stderr || "");
-    assert.match(out, /Cost telemetry live/);
+    assert.match(out, /Cost telemetry: spend telemetry live/);
     assert.ok(!out.includes("Cost telemetry BLIND"), "must not flag blind when spend>0");
   } finally { await rmRoot(root); }
 });
@@ -478,7 +539,23 @@ test("doctor GREEN (nothing to measure) when no ledger exists today", async () =
   try {
     const r = runCli(["doctor"], root);
     const out = (r.stdout || "") + (r.stderr || "");
-    assert.match(out, /no sessions recorded today/);
+    assert.match(out, /nothing to measure/);
+  } finally { await rmRoot(root); }
+});
+
+test("doctor does NOT cry wolf on an empty ledger while the daemon is live", async () => {
+  // The regression this replaced: doctor keyed "sessions ran" off a fresh
+  // heartbeat, so every UTC day went RED between midnight and the first session
+  // and printed a fix that had already shipped.
+  const root = await makeBareAgent();
+  try {
+    mkdirSync(join(root, "state/cadence-bus"), { recursive: true });
+    writeFileSync(join(root, "state/cadence-bus/health.json"),
+      JSON.stringify({ ts: new Date().toISOString() }));
+    const r = runCli(["doctor"], root);
+    const out = (r.stdout || "") + (r.stderr || "");
+    assert.ok(!out.includes("Cost telemetry BLIND"), "a live daemon with no sessions yet is not blind");
+    assert.match(out, /nothing to measure/);
   } finally { await rmRoot(root); }
 });
 
@@ -860,30 +937,80 @@ test("secrets sync without a configured broker exits 1", async () => {
 // doctor — backup-config DR check (gaps-enterprise-ops G16)
 // ---------------------------------------------------------------------------
 
-test("doctor RED when no backup target is configured", async () => {
+test("doctor RED when there is no DR posture at all, and names the one command that fixes it", async () => {
   const root = await makeBareAgent();
   try {
     const r = runCli(["doctor"], root);
     const out = (r.stdout || "") + (r.stderr || "");
-    assert.match(out, /No backup target configured/);
+    assert.match(out, /No DR posture at all/);
     assert.match(out, /backup-config\.yaml/);
+    assert.match(out, /maestro init backup-replication --apply/);
     // doctor exits 1 whenever any issue is found; the missing backup is one.
     assert.equal(r.status, 1, out);
   } finally { await rmRoot(root); }
 });
 
-test("doctor GREEN for backup when configured + a fresh successful run is recorded", async () => {
+test("doctor RED when backup is enabled but has never actually run", async () => {
+  const root = await makeBareAgent();
+  try {
+    mkdirSync(join(root, ".maestro"), { recursive: true });
+    writeFileSync(join(root, ".maestro/backup-config.yaml"), "enabled: true\nprefix: t\n");
+    const r = runCli(["doctor"], root);
+    const out = (r.stdout || "") + (r.stderr || "");
+    assert.match(out, /NEVER completed a run/);
+    assert.match(out, /backup-run\.mjs/);
+  } finally { await rmRoot(root); }
+});
+
+test("doctor WARNS (not GREEN) when restore points are fresh but local-only", async () => {
+  const root = await makeBareAgent();
+  try {
+    mkdirSync(join(root, ".maestro"), { recursive: true });
+    writeFileSync(join(root, ".maestro/backup-config.yaml"), "enabled: true\nprefix: t\nlocal:\n  enabled: true\n");
+    writeFileSync(join(root, ".maestro/last-backup.json"), JSON.stringify({
+      completed_at: new Date().toISOString(), tier: "local", provider: "local",
+    }));
+    const r = runCli(["doctor"], root);
+    const out = (r.stdout || "") + (r.stderr || "");
+    assert.match(out, /LOCAL-ONLY/);
+    assert.match(out, /offsite\.provider/);
+    assert.ok(!out.includes("No DR posture at all"), "must not claim the config is missing");
+  } finally { await rmRoot(root); }
+});
+
+test("doctor GREEN for backup only when it is fresh AND off-machine", async () => {
   const root = await makeBareAgent();
   try {
     mkdirSync(join(root, ".maestro"), { recursive: true });
-    writeFileSync(join(root, ".maestro/backup-config.yaml"), "enabled: true\nprovider: s3\nbucket: agent-backups\n");
+    writeFileSync(
+      join(root, ".maestro/backup-config.yaml"),
+      "enabled: true\nprefix: t\noffsite:\n  provider: s3\n  bucket: agent-backups\n"
+    );
     writeFileSync(join(root, ".maestro/last-backup.json"), JSON.stringify({
-      completed_at: new Date().toISOString(), provider: "s3", bucket: "agent-backups",
+      completed_at: new Date().toISOString(), tier: "offsite", provider: "s3", bucket: "agent-backups",
     }));
     const r = runCli(["doctor"], root);
     const out = (r.stdout || "") + (r.stderr || "");
-    assert.match(out, /Backup configured \+ fresh/);
-    assert.ok(!out.includes("No backup target configured"), "must not flag missing backup when fresh");
+    assert.match(out, /Backup fresh \+ off-machine/);
+    assert.ok(!out.includes("No DR posture at all"), "must not flag missing backup when fresh");
+    assert.ok(!out.includes("LOCAL-ONLY"), "offsite is configured");
+  } finally { await rmRoot(root); }
+});
+
+test("doctor reports an include path that the credential deny-list drops", async () => {
+  const root = await makeBareAgent();
+  try {
+    mkdirSync(join(root, ".maestro"), { recursive: true });
+    writeFileSync(
+      join(root, ".maestro/backup-config.yaml"),
+      "enabled: true\nprefix: t\ninclude:\n  - state\n  - .env\n"
+    );
+    writeFileSync(join(root, ".maestro/last-backup.json"), JSON.stringify({
+      completed_at: new Date().toISOString(), tier: "local",
+    }));
+    const r = runCli(["doctor"], root);
+    const out = (r.stdout || "") + (r.stderr || "");
+    assert.match(out, /DROPPED by the credential deny-list/);
   } finally { await rmRoot(root); }
 });
 
@@ -1013,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/docs/runbooks/backup-restore.md

@@ -12,27 +12,47 @@ This complements `docs/runbooks/mac-mini-bootstrap.md` (fresh provisioning) and
 compromised machine, do NOT restore onto the same hardware — rebuild on a clean
 box.
 
-## What is backed up, and the honest gaps
-
-Off-machine backup is driven by `scripts/maintenance/backup-to-cloud.sh`, reading
-`.maestro/backup-config.yaml`, run daily via launchd. Configure it with
-`maestro init backup-replication --apply` (`scripts/setup/init-backup.mjs`).
-
-Know these caveats before you rely on it:
-
-- **Backup is opt-in and silent when off.** If `.maestro/backup-config.yaml` is
-  missing or `enabled: false`, the script exits 0 and does nothing. An agent with
-  no backup configured looks identical to a healthy one in casual inspection —
-  check explicitly (below).
-- **Coverage historically excluded `logs/` and the audit records.** Confirm your
-  config's include paths cover `state/`, `logs/`, and `.maestro/`. If `logs/` is
-  excluded, a dead machine loses that agent's local compliance history — the
-  org-server export (next section) is your compensating control.
-- **`retention_days` may not be enforced** by older builds; do not assume old
-  archives are pruned.
-- **Archives may be unencrypted** unless you enabled client-side encryption.
-  Treat the backup bucket as sensitive, restrict access, and prefer an encrypted
-  bucket and encrypted archives.
+## The posture: two tiers
+
+Since 2026-08 the DR posture is **restore points first, offsite second**, driven
+by `scripts/maintenance/backup-run.mjs` (the `nightly-backup` cadence, 03:10
+local) reading `.maestro/backup-config.yaml`. `scripts/maintenance/backup-to-cloud.sh`
+is now a thin compatibility wrapper around the same runner.
+
+| Tier | Default | Where | Survives |
+|---|---|---|---|
+| 1 — local restore points | **ON**, zero credentials | `~/Library/Application Support/Maestro/backups/<prefix>/`, **outside** the agent repo | corrupted queue, bad state write, botched checkout, `rm -rf` of the repo |
+| 2 — offsite copy | opt-in (`offsite.provider` + `offsite.bucket`) | gcs / s3 / rsync | machine loss, disk death, fire |
+
+`maestro init backup-replication --apply` writes the Tier-1 default, and it is
+`auto: true` — so a **new agent is born with a DR posture instead of a red
+doctor line**. Tier 2 stays a deliberate act (it needs a bucket and credentials);
+`maestro doctor` WARNs until it is set, naming the residual risk in words.
+
+**Archived by default:** `state/`, `knowledge/`, `memory/`, `outputs/`,
+`config/`, `.maestro/`. `logs/` is deliberately excluded — largest tree, least
+value, and the authoritative audit trail is already the org event ledger (next
+section). Add it explicitly to `include:` if you want it.
+
+**NEVER archived, enforced in code and not overridable from the config**
+(`lib/backup/policy.mjs` → `DENY_PATTERNS`): `.env`, `.env.*`,
+`.cohort-key.json`, `.claude/.credentials.json`, `*.pem` / `*.key` / SSH keys,
+`node_modules`, `.git`, `state/tmp`, the RAG index, sqlite WAL/SHM files.
+`.env` carries `COHORT_API_KEY` (which authenticates as this member) and
+`.cohort-key.json` is the device identity — a backup that shipped either to a
+bucket would be a credential-exfiltration channel that looks *exactly* like a
+successful backup. The deny-list is applied three times: it drops offending
+`include:` entries at plan time (reporting them), it becomes `tar --exclude`
+arguments, and the runner **lists the finished archive and deletes it** if a
+denied path got in anyway. A restore re-pairs for a fresh token; it never
+restores a dead identity.
+
+Remaining honest gaps:
+
+- **Archives are unencrypted at rest** unless you point Tier 2 at an encrypted
+  bucket. Treat the backup destination as sensitive and restrict access.
+- **Tier 1 alone is not DR.** A local restore point on a dead disk is nothing.
+  Doctor says so explicitly; do not read the absence of a red line as safety.
 
 The org server is your fleet-as-DR layer for the audit record: every
 side-effecting action is a hash-chained `org_events` row at Cohort, exportable
@@ -46,18 +66,26 @@ non-repudiable record.
 ```bash
 cd ~/<agent>-ai
 
-# 1. Is backup configured and enabled?
-test -f .maestro/backup-config.yaml && grep -E '^enabled:' .maestro/backup-config.yaml
+# 1. Is backup configured and enabled, and at which tier?
+test -f .maestro/backup-config.yaml && grep -E '^enabled:|provider:|bucket:' .maestro/backup-config.yaml
 
-# 2. Did the last run succeed, and when?
+# 2. Did the last run succeed, when, and to where?
+cat .maestro/last-backup.json
 tail -n 20 logs/maintenance/backup.log
 
-# 3. Does the configured destination actually have today's archive?
-#    (provider-specific; e.g. for GCS:)
-#    gcloud storage ls "gs://<bucket>/<prefix>/$(date -u +%F)/"
+# 3. Do the local restore points actually exist?
+ls -lh ~/Library/Application\ Support/Maestro/backups/*/
 
-# 4. doctor surfaces backup freshness in the governance posture.
+# 4. Does the offsite destination have the archive? (provider-specific)
+#    gcloud storage ls "gs://<bucket>/<prefix>/"
+
+# 5. doctor's verdict — fail (no restore point) vs warn (local-only / stale)
+#    vs ok (fresh AND off-machine).
 maestro doctor
+
+# 6. Force a run now, without waiting for 03:10.
+node scripts/maintenance/backup-run.mjs
+node scripts/maintenance/backup-run.mjs --dry-run   # print the plan only
 ```
 
 If `maestro doctor` does not flag a missing/stale backup red, do not assume the
@@ -163,8 +191,10 @@ A rebuilt machine with no backup is the next dead machine.
 ```bash
 cd ~/<agent>-ai
 maestro init backup-replication --apply   # if .maestro/backup-config.yaml absent
-# confirm include paths cover state/, logs/, .maestro/; confirm encryption on.
-maestro doctor                            # backup freshness should clear within a day
+# Restore the OFFSITE block from the dead machine's config (Tier 1 is on by
+# default; Tier 2 is the one that saves you next time).
+node scripts/maintenance/backup-run.mjs   # don't wait for 03:10 — prove it works now
+maestro doctor                            # expect "Backup fresh + off-machine"
 ```
 
 ---
@@ -195,9 +225,11 @@ tested restore.
 
 | Need | Command |
 |---|---|
-| Is backup on? | `grep -E '^enabled:' .maestro/backup-config.yaml` |
-| Last backup status | `tail logs/maintenance/backup.log` |
-| Configure backup | `maestro init backup-replication --apply` |
+| Is backup on, and at which tier? | `grep -E '^enabled:\|provider:\|bucket:' .maestro/backup-config.yaml` |
+| Last backup status | `cat .maestro/last-backup.json` / `tail logs/maintenance/backup.log` |
+| Configure backup (Tier 1 default) | `maestro init backup-replication --apply` |
+| Run a backup now | `node scripts/maintenance/backup-run.mjs` |
+| Add the offsite tier | set `offsite.provider` + `offsite.bucket` in `.maestro/backup-config.yaml` |
 | Governance posture incl. backup freshness | `maestro doctor` |
 | Re-mint agent identity | `cohort pair approve <agentId> --scopes <...>` |
 | Recover audit history | `cohort export-audit --format ocsf` |

package/framework-features.json

@@ -94,13 +94,13 @@
       }
     },
     "backup-replication": {
-      "version": "1",
+      "version": "2",
       "since": "1.9.0",
-      "title": "Off-machine state backup",
+      "title": "Disaster-recovery backup (local restore points + optional offsite)",
       "init": {
-        "auto": false,
+        "auto": true,
         "command": "node scripts/setup/init-backup.mjs",
-        "description": "Configure off-machine backup of state/, knowledge/, outputs/, and rotated logs to GCS or S3. Requires bucket name + credentials. Doctor flags if last successful backup is >24h old once configured."
+        "description": "Write .maestro/backup-config.yaml with the default DR posture so a new agent is not born failing doctor. TIER 1 (on, zero credentials): nightly tar.gz of state/, knowledge/, memory/, outputs/, config/ and .maestro/ into ~/Library/Application Support/Maestro/backups/<prefix>/ — outside the agent repo — via the nightly-backup cadence at 03:10, 14-day retention. TIER 2 (opt-in): set offsite.provider (gcs|s3|rsync) + offsite.bucket to get a copy off the machine; doctor WARNS until you do, because Tier 1 alone does not survive losing the box. NEVER archived, enforced in code (lib/backup/policy.mjs DENY_PATTERNS), not overridable from the config: .env, .cohort-key.json, private keys, .claude/.credentials.json, node_modules, .git, state/tmp, the RAG index."
       }
     },
     "slack-socket-mode": {