@cohortapp/agent-sdk 2.5.1 → 2.6.0

package/scripts/local-triggers/generate-plists.test.mjs

@@ -107,7 +107,7 @@ function listPlists(agentRoot) {
 // Tests
 // ---------------------------------------------------------------------------
 
-test("generator emits 22 standard plists with the agent's first name", async () => {
+test("generator emits 23 standard plists with the agent's first name", async () => {
   // Standard inventory (cadence-bus v1 + slack-socket-mode v1), with NO
   // config/.cadence-plists.tsv present (no archetype cadences):
   //   daemon, poll-relay, slack-socket (3 infra), PLUS one trigger plist per
@@ -119,7 +119,8 @@ test("generator emits 22 standard plists with the agent's first name", async ()
   //   org-cost-sync, monitoring-alerts, dynamic-jobs (5), PLUS the SP10
   //   messaging-inbound cadence (1), PLUS the 2026-07 Directory & Design
   //   stewards directory-hygiene + brand-steward (2), PLUS the D3 self-directed
-  //   loop goal-steward (1). = 3 infra + 19 trigger = 22 total.
+  //   loop goal-steward (1), PLUS the 2026-08 DR cadence nightly-backup (1).
+  //   = 3 infra + 20 trigger = 23 total.
   // org-pulse used to be declared standard but was OMITTED by the old hardcoded
   // list (it never got a plist); deriving from the SoT fixes that drift.
   // The former weekly-* cadences are still ARCHETYPE-DRIVEN (function × altitude),
@@ -129,9 +130,11 @@ test("generator emits 22 standard plists with the agent's first name", async ()
     const r = runGenerator(root);
     assert.equal(r.status, 0, r.stderr);
     const plists = listPlists(root);
-    assert.equal(plists.length, 22, `expected 22 standard plists; got ${plists.join(",")}`);
+    assert.equal(plists.length, 23, `expected 23 standard plists; got ${plists.join(",")}`);
     assert.ok(plists.includes("ai.maestro.alice-messaging-inbound.plist"),
       "messaging-inbound (SP10 standard cadence) must get a SoT-derived plist");
+    assert.ok(plists.includes("ai.maestro.alice-nightly-backup.plist"),
+      "nightly-backup (the DR cadence) must be scheduled, not left to a human to remember");
     for (const id of ["directory-hygiene", "brand-steward"]) {
       assert.ok(plists.includes(`ai.maestro.alice-${id}.plist`),
         `Directory/Design steward "${id}" must get a SoT-derived plist; got ${plists.join(",")}`);
@@ -200,7 +203,7 @@ test("archetype cadences from config/.cadence-plists.tsv emit extra trigger plis
     const r = runGenerator(root);
     assert.equal(r.status, 0, r.stderr);
     const plists = listPlists(root);
-    assert.equal(plists.length, 24, `expected 22 standard + 2 archetype; got ${plists.join(",")}`);
+    assert.equal(plists.length, 25, `expected 23 standard + 2 archetype; got ${plists.join(",")}`);
     const dir = join(root, "scripts/local-triggers/plists");
     const eng = readFileSync(join(dir, "ai.maestro.erin-engineering-health.plist"), "utf-8");
     assert.match(eng, /<key>Weekday<\/key>\s*<integer>3<\/integer>/); // base64 schedule decoded

package/scripts/maintenance/backup-run.mjs

@@ -0,0 +1,415 @@
+#!/usr/bin/env node
+/**
+ * backup-run.mjs — the nightly DR job.
+ *
+ * Replaces the brains of scripts/maintenance/backup-to-cloud.sh (which is now a
+ * thin wrapper so any already-installed plist keeps working). The shell driver
+ * parsed YAML with awk, had no deny-list, and — the part that mattered —
+ * `exit 0`'d silently when unconfigured, which is how a fleet ran for months
+ * with zero agents backed up and nothing red anywhere.
+ *
+ * What it does, in order:
+ *   1. Resolve the plan (lib/backup/policy.mjs — the single source of truth
+ *      shared with doctor and the nightly-backup cadence).
+ *   2. REFUSE to run if the plan is unusable, loudly, with a non-zero exit.
+ *      Never a silent success.
+ *   3. tar.gz the include paths with the hard credential deny-list applied as
+ *      --exclude patterns (belt) on top of the plan's already-filtered include
+ *      list (braces).
+ *   4. VERIFY the archive does not contain a denied path before it goes
+ *      anywhere. A backup that ships `.env` to a bucket is a credential leak
+ *      that looks exactly like a successful backup, so the check happens on the
+ *      real archive listing, not on the intent.
+ *   5. Place it in the local restore-point directory (Tier 1), prune to
+ *      retention, then push offsite (Tier 2) when configured.
+ *   6. Stamp .maestro/last-backup.json — the marker doctor and
+ *      lib/diagnostics/backup-freshness.mjs read.
+ *
+ * Exit codes: 0 success (including "offsite skipped because unconfigured" —
+ * that is a WARN state doctor owns, not a job failure), 1 refused/failed.
+ *
+ * Usage:
+ *   node scripts/maintenance/backup-run.mjs [--dry-run] [--agent-dir <path>]
+ */
+
+import { execFileSync } from "node:child_process";
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+  appendFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const argv = process.argv.slice(2);
+const DRY_RUN = argv.includes("--dry-run");
+const agentDirArg = (() => {
+  const i = argv.indexOf("--agent-dir");
+  return i >= 0 ? argv[i + 1] : null;
+})();
+
+const AGENT_DIR = resolve(
+  agentDirArg || process.env.AGENT_ROOT || process.env.AGENT_DIR || join(__dirname, "..", "..")
+);
+
+const LOG_DIR = join(AGENT_DIR, "logs", "maintenance");
+const LOG_FILE = join(LOG_DIR, "backup.log");
+
+function log(level, msg) {
+  const line = `[${new Date().toISOString()}] [${level}] ${msg}`;
+  process.stdout.write(`${line}\n`);
+  try {
+    mkdirSync(LOG_DIR, { recursive: true });
+    appendFileSync(LOG_FILE, `${line}\n`);
+  } catch {
+    /* logging must never be the thing that fails the backup */
+  }
+}
+
+/**
+ * Resolve lib/backup/policy.mjs from the agent's own lib/ first (an agent repo
+ * carries its own framework copy), then the installed SDK, then this checkout —
+ * the same resolution ladder generate-plists.sh uses.
+ */
+async function loadPolicy() {
+  const candidates = [
+    join(AGENT_DIR, "lib", "backup", "policy.mjs"),
+    join(AGENT_DIR, "node_modules", "@cohortapp", "agent-sdk", "lib", "backup", "policy.mjs"),
+    join(__dirname, "..", "..", "lib", "backup", "policy.mjs"),
+  ];
+  for (const c of candidates) {
+    if (existsSync(c)) return import(`file://${c}`);
+  }
+  throw new Error(`lib/backup/policy.mjs not found (looked in: ${candidates.join(", ")})`);
+}
+
+async function main() {
+  const policy = await loadPolicy();
+  const plan = policy.resolveBackupPlan({ agentRoot: AGENT_DIR });
+
+  // ── Refuse loudly rather than exit 0 silently ────────────────────────────
+  if (!plan.present) {
+    log("error", "REFUSING: no .maestro/backup-config.yaml. Fix: maestro init backup-replication --apply");
+    process.exit(1);
+  }
+  if (!plan.readable) {
+    log("error", "REFUSING: .maestro/backup-config.yaml is unparseable YAML.");
+    process.exit(1);
+  }
+  if (!plan.enabled) {
+    log("error", "REFUSING: backup-config.yaml has enabled != true — this machine has no restore points.");
+    process.exit(1);
+  }
+  for (const v of plan.violations) {
+    log("warn", `include path DROPPED by the credential deny-list: ${v.path} (matched ${v.pattern})`);
+  }
+  if (!plan.include.length) {
+    log("error", "REFUSING: every include path was rejected — the archive would be empty.");
+    process.exit(1);
+  }
+
+  // Only archive what actually exists; a missing optional tree (outputs/ on a
+  // fresh agent) must not fail the whole run.
+  const present = plan.include.filter((p) => existsSync(join(AGENT_DIR, p)));
+  const absent = plan.include.filter((p) => !present.includes(p));
+  if (absent.length) log("info", `skipping absent include path(s): ${absent.join(", ")}`);
+  if (!present.length) {
+    log("error", "REFUSING: none of the configured include paths exist on disk.");
+    process.exit(1);
+  }
+
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-").replace(/Z$/, "Z");
+  const archiveName = `${plan.prefix}-${stamp}.tar.gz`;
+  // Tier 1 off + Tier 2 on is a legitimate (if unusual) posture: stage in the
+  // OS temp dir, never inside the agent repo. An archive that lives in the tree
+  // it protects is not a backup, and it would also end up inside the NEXT one.
+  const localDir = plan.local.enabled ? plan.local.dir : join(tmpdir(), "maestro-backup-staging");
+  const archivePath = join(localDir, archiveName);
+
+  log("info", `plan: tier=${plan.tier} include=[${present.join(", ")}] → ${archivePath}`);
+  if (DRY_RUN) {
+    log("info", "--dry-run: stopping before tar.");
+    return;
+  }
+
+  mkdirSync(localDir, { recursive: true });
+
+  // ── 2b. CONTENT deny-list ───────────────────────────────────────────────
+  // The path deny-list cannot see a credential stored INSIDE an included file,
+  // and that is not hypothetical: state/setup/progress.json carried this agent's
+  // live COHORT_API_KEY in plaintext while the archive listing verified clean.
+  // Scan the real bytes on disk and turn every hit into a tar --exclude, so the
+  // secret never enters the tarball in the first place.
+  //
+  // A hit DROPS THE FILE; it does not fail the run. A false positive must cost
+  // one file in a restore point, never the machine's whole DR posture.
+  const contentScan = policy.scanIncludesForSecrets(plan, AGENT_DIR);
+  const contentExcludes = [];
+  for (const leak of contentScan.leaks) {
+    contentExcludes.push(`--exclude=${leak.path}`);
+    log("warn", `file DROPPED by the CONTENT deny-list: ${leak.path} (matched ${leak.patterns.join(", ")}) — a credential inside an archived file is the same leak as archiving .env`);
+  }
+  for (const big of contentScan.oversize) {
+    log("warn", `NOT content-scanned (over the size limit): ${big} — it is still archived; the path deny-list is its only cover`);
+  }
+  for (const e of contentScan.errors.slice(0, 10)) log("warn", `content scan could not read ${e}`);
+  if (contentScan.truncated) {
+    log("error", "REFUSING: the content scan hit its file budget before finishing — an unscanned tree may contain credentials.");
+    process.exit(1);
+  }
+  log("info", `content scan: ${contentScan.scanned} file(s) read, ${contentScan.leaks.length} dropped, ${contentScan.skippedBinary} binary skipped`);
+
+  // ── 3. build the archive ────────────────────────────────────────────────
+  const excludeArgs = [...policy.tarExcludeArgs(plan), ...contentExcludes];
+  try {
+    execFileSync("tar", [...excludeArgs, "-czf", archivePath, "-C", AGENT_DIR, ...present], {
+      stdio: ["ignore", "pipe", "pipe"],
+      maxBuffer: 32 * 1024 * 1024,
+    });
+  } catch (err) {
+    log("error", `tar failed: ${err && err.message}`);
+    try { rmSync(archivePath, { force: true }); } catch { /* best effort */ }
+    process.exit(1);
+  }
+
+  // ── 4. verify no denied path made it in ─────────────────────────────────
+  // This is the check that turns the deny-list from an intention into a
+  // guarantee. It reads the REAL archive listing: a symlink, a nested copy, or
+  // a tar flag that behaved differently than expected all surface here.
+  let listing = "";
+  try {
+    listing = execFileSync("tar", ["-tzf", archivePath], {
+      encoding: "utf-8",
+      maxBuffer: 128 * 1024 * 1024,
+    });
+  } catch (err) {
+    log("error", `could not list the archive to verify it: ${err && err.message}`);
+    rmSync(archivePath, { force: true });
+    process.exit(1);
+  }
+  const leaked = [];
+  const contentDenied = new Set(contentScan.leaks.map((l) => l.path));
+  for (const entry of listing.split("\n")) {
+    const rel = entry.trim().replace(/^\.\//, "");
+    if (!rel || rel.endsWith("/")) continue;
+    const hit = policy.denyMatch(rel);
+    if (hit) leaked.push(`${rel} (${hit})`);
+    // A file the content scan flagged must not be in the listing. If tar kept it
+    // anyway (an --exclude that did not match the stored path form), that is
+    // exactly the silent leak this whole check exists to catch.
+    else if (contentDenied.has(rel)) leaked.push(`${rel} (content deny-list — the --exclude did not take)`);
+    if (leaked.length >= 10) break;
+  }
+  if (leaked.length) {
+    rmSync(archivePath, { force: true });
+    log("error", `REFUSING to keep an archive containing denied paths — DELETED it. Offenders: ${leaked.join("; ")}`);
+    process.exit(1);
+  }
+
+  const size = statSync(archivePath).size;
+  // Say exactly what was verified. "verified clean" over a path-only check is the
+  // false assurance that let a live API key ship.
+  log(
+    "info",
+    `archive verified: ${archiveName} (${size} bytes, ${listing.split("\n").length - 1} entries) — ` +
+    `no denied PATHS, and ${contentScan.leaks.length} content-flagged file(s) confirmed absent ` +
+    `(${contentScan.scanned} file(s) content-scanned, ${contentScan.oversize.length} too large to scan)`
+  );
+
+  // ── 5a. prune local restore points ──────────────────────────────────────
+  let pruned = 0;
+  if (plan.local.enabled) {
+    const cutoff = Date.now() - plan.local.retentionDays * 86_400_000;
+    for (const name of safeReaddir(localDir)) {
+      if (!name.startsWith(`${plan.prefix}-`) || !name.endsWith(".tar.gz")) continue;
+      const full = join(localDir, name);
+      if (full === archivePath) continue;
+      try {
+        if (statSync(full).mtimeMs < cutoff) {
+          rmSync(full, { force: true });
+          pruned++;
+        }
+      } catch { /* a file that vanished under us is already pruned */ }
+    }
+    if (pruned) log("info", `pruned ${pruned} local restore point(s) older than ${plan.local.retentionDays}d`);
+  }
+
+  // ── 5b. offsite ─────────────────────────────────────────────────────────
+  let offsiteOk = false;
+  let offsiteDetail = "not configured";
+  if (plan.offsite.configured) {
+    const key = `${plan.prefix}/${archiveName}`;
+    try {
+      if (plan.offsite.provider === "gcs") {
+        requireBinary("gsutil", "install the gcloud SDK, or switch offsite.provider");
+        execFileSync("gsutil", ["cp", archivePath, `gs://${stripScheme(plan.offsite.bucket)}/${key}`], { stdio: "pipe" });
+      } else if (plan.offsite.provider === "s3") {
+        requireBinary("aws", "install the AWS CLI, or switch offsite.provider");
+        execFileSync("aws", ["s3", "cp", archivePath, `s3://${stripScheme(plan.offsite.bucket)}/${key}`], { stdio: "pipe" });
+      } else if (plan.offsite.provider === "rsync") {
+        requireBinary("rsync", "install rsync, or switch offsite.provider");
+        execFileSync("rsync", ["-az", archivePath, `${plan.offsite.bucket.replace(/\/+$/, "")}/${plan.prefix}/`], { stdio: "pipe" });
+      }
+      offsiteOk = true;
+      offsiteDetail = `${plan.offsite.provider}://${plan.offsite.bucket}/${key}`;
+      log("info", `offsite copy complete → ${offsiteDetail}`);
+    } catch (err) {
+      // A failed offsite push does NOT discard the local restore point — we are
+      // strictly better off than before. But it is never silent: the marker
+      // records the failure and doctor reads the marker.
+      offsiteDetail = `FAILED: ${err && err.message}`;
+      log("error", `offsite copy failed (local restore point kept): ${err && err.message}`);
+    }
+  } else {
+    log("warn", "offsite is NOT configured — these restore points do not survive losing this machine. Set offsite.provider + offsite.bucket in .maestro/backup-config.yaml.");
+  }
+
+  // ── 5c. prune OFFSITE to retention ──────────────────────────────────────
+  // `offsite.retention_days` was parsed into the plan, shipped in the default
+  // config beside a comment describing Tier 2 as working, and consumed by
+  // NOTHING: the only pruning was local, on `local.retentionDays`. An operator
+  // who set `retention_days: 30` got a bucket that grew forever and was never
+  // told. Prune with the same CLI that uploaded, over our OWN key prefix only.
+  let offsitePruned = 0;
+  let offsitePruneDetail = "not attempted";
+  if (offsiteOk) {
+    try {
+      offsitePruned = pruneOffsite(plan, log);
+      offsitePruneDetail = `${offsitePruned} archive(s) older than ${plan.offsite.retentionDays}d removed`;
+    } catch (err) {
+      // Never fatal: the restore points exist, which is the point of the job.
+      offsitePruneDetail = `FAILED: ${err && err.message}`;
+      log("error", `offsite retention prune failed (the upload succeeded; old archives remain): ${err && err.message}`);
+    }
+  }
+
+  // Staging dir (Tier 1 off) is not a restore point — clear it once pushed.
+  if (!plan.local.enabled && offsiteOk) {
+    try { rmSync(archivePath, { force: true }); } catch { /* best effort */ }
+  }
+
+  // ── 6. stamp the marker doctor reads ────────────────────────────────────
+  const marker = {
+    completed_at: new Date().toISOString(),
+    tier: offsiteOk ? "offsite" : "local",
+    provider: offsiteOk ? plan.offsite.provider : "local",
+    bucket: offsiteOk ? plan.offsite.bucket : localDir,
+    prefix: plan.prefix,
+    archive: archiveName,
+    size_bytes: size,
+    include: present,
+    local_dir: localDir,
+    local_pruned: pruned,
+    offsite: offsiteDetail,
+    offsite_retention_days: plan.offsite.configured ? plan.offsite.retentionDays : null,
+    offsite_pruned: offsitePruneDetail,
+    denied_include_paths: plan.violations,
+    // The CONTENT deny-list's findings, on the record. A leak that is dropped
+    // silently teaches nobody; the operator needs to know a credential was
+    // sitting in an archived file and rotate it.
+    denied_content_paths: contentScan.leaks,
+    content_scanned_files: contentScan.scanned,
+    content_unscanned_oversize: contentScan.oversize,
+  };
+  writeFileSync(join(AGENT_DIR, ".maestro", "last-backup.json"), `${JSON.stringify(marker, null, 2)}\n`);
+  log("info", `backup complete (tier=${marker.tier}).`);
+}
+
+function safeReaddir(dir) {
+  try {
+    return readdirSync(dir);
+  } catch {
+    return [];
+  }
+}
+
+function stripScheme(bucket) {
+  return String(bucket).replace(/^(gs|s3):\/\//, "").replace(/\/+$/, "");
+}
+
+/**
+ * Delete offsite archives older than `offsite.retentionDays`.
+ *
+ * Scoped THREE ways so this can never delete something that is not ours:
+ *   - only under `<bucket>/<prefix>/`
+ *   - only names matching `<prefix>-<ISO stamp>.tar.gz`
+ *   - only stamps older than the retention window (parsed from the NAME, not
+ *     from remote metadata, so a re-upload cannot resurrect an object)
+ *
+ * rsync targets are deliberately NOT pruned: doing so means running a remote
+ * `find -delete` over ssh against a path from a config file, which is a much
+ * bigger gun than a bucket delete. The operator is TOLD rather than left to
+ * assume — the honest half of "fail-open is fine, silent is not".
+ *
+ * @returns {number} objects removed
+ */
+function pruneOffsite(plan, log) {
+  const days = plan.offsite.retentionDays;
+  if (!Number.isFinite(days) || days <= 0) return 0;
+  const cutoff = Date.now() - days * 86_400_000;
+  const prefix = plan.prefix;
+  const bucket = stripScheme(plan.offsite.bucket);
+  const nameRe = new RegExp(`^${prefix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}-(.+)\\.tar\\.gz$`);
+
+  const ageOf = (name) => {
+    const m = nameRe.exec(name);
+    if (!m) return null;
+    // `2026-08-12T08-26-30-411Z` → restore the ISO punctuation.
+    const iso = m[1].replace(/T(\d{2})-(\d{2})-(\d{2})-(\d{3})Z$/, "T$1:$2:$3.$4Z");
+    const t = Date.parse(iso);
+    return Number.isFinite(t) ? t : null;
+  };
+
+  if (plan.offsite.provider === "rsync") {
+    log(
+      "warn",
+      `offsite.retention_days: ${days} is NOT enforced for the rsync provider — maestro will not run a remote ` +
+      "delete over ssh against a path from a config file. Age out archives on the receiving host (a cron " +
+      "`find <path> -name '*.tar.gz' -mtime +N -delete`), or switch offsite.provider to gcs/s3."
+    );
+    return 0;
+  }
+
+  const list = plan.offsite.provider === "gcs"
+    ? execFileSync("gsutil", ["ls", `gs://${bucket}/${prefix}/`], { encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] })
+    : execFileSync("aws", ["s3", "ls", `s3://${bucket}/${prefix}/`], { encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] });
+
+  let removed = 0;
+  for (const raw of list.split("\n")) {
+    const line = raw.trim();
+    if (!line) continue;
+    const name = line.split(/[\s/]+/).pop();
+    if (!name || !name.endsWith(".tar.gz")) continue;
+    const t = ageOf(name);
+    if (t === null || t >= cutoff) continue;
+    const key = `${prefix}/${name}`;
+    if (plan.offsite.provider === "gcs") {
+      execFileSync("gsutil", ["rm", `gs://${bucket}/${key}`], { stdio: "pipe" });
+    } else {
+      execFileSync("aws", ["s3", "rm", `s3://${bucket}/${key}`], { stdio: "pipe" });
+    }
+    removed += 1;
+  }
+  if (removed) log("info", `offsite prune: removed ${removed} archive(s) older than ${days}d from ${plan.offsite.provider}://${bucket}/${prefix}/`);
+  return removed;
+}
+
+function requireBinary(bin, hint) {
+  try {
+    execFileSync("/usr/bin/which", [bin], { stdio: "ignore" });
+  } catch {
+    throw new Error(`${bin} not found in PATH — ${hint}`);
+  }
+}
+
+main().catch((err) => {
+  log("error", `unhandled: ${err && err.stack ? err.stack : err}`);
+  process.exit(1);
+});

package/scripts/maintenance/backup-to-cloud.sh

@@ -1,124 +1,24 @@
 #!/bin/bash
-# backup-to-cloud.sh — Off-machine state backup driver.
+# backup-to-cloud.sh — COMPATIBILITY WRAPPER.
 #
-# Reads .maestro/backup-config.yaml and pushes the configured paths to GCS
-# or S3 (or rsyncs to a remote host). Designed to be invoked daily via a
-# launchd plist. Idempotent; safe to re-run.
+# The backup driver moved to scripts/maintenance/backup-run.mjs. This shell
+# entrypoint stays because installed launchd plists and the runbook reference
+# it by name; it now just execs the Node runner.
 #
-# If .maestro/backup-config.yaml is missing or `enabled: false`, exits 0
-# silently. Errors during upload are logged to logs/maintenance/backup.log
-# and surface in `maestro doctor`.
+# Why the move: this script parsed YAML with awk, had no credential deny-list,
+# required a cloud bucket before it would do anything, and — the part that
+# actually cost us — `exit 0`'d SILENTLY when unconfigured. A fleet can run for
+# months with zero agents backed up and nothing red anywhere. backup-run.mjs
+# refuses loudly with a non-zero exit instead, and writes local restore points
+# with no credentials at all so the default posture is "something", not "nothing".
+#
+# See lib/backup/policy.mjs for the posture (what/where/never) and
+# docs/runbooks/backup-restore.md for the restore path.
 
 set -e
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-AGENT_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
-CFG="$AGENT_DIR/.maestro/backup-config.yaml"
-LOG_DIR="$AGENT_DIR/logs/maintenance"
-LOG="$LOG_DIR/backup.log"
-mkdir -p "$LOG_DIR"
-
-log() { echo "[$(date -u +"%Y-%m-%dT%H:%M:%SZ")] $1" | tee -a "$LOG"; }
-
-if [ ! -f "$CFG" ]; then
-    log "backup-config.yaml not found — backup not configured. Run: maestro init backup-replication --apply"
-    exit 0
-fi
-
-# Tiny YAML reader (only the fields we need).
-get() {
-    awk -v k="$1" '
-      $1 == k":" { sub(/^[^:]+:[[:space:]]*/, "", $0); gsub(/^"|"$/, "", $0); print; exit }
-    ' "$CFG"
-}
-
-ENABLED=$(get enabled)
-if [ "$ENABLED" != "true" ]; then
-    log "Backup not enabled (.maestro/backup-config.yaml: enabled: false). Skipping."
-    exit 0
-fi
-
-PROVIDER=$(get provider)
-BUCKET=$(get bucket)
-PREFIX=$(get prefix)
-RETENTION=$(get retention_days)
-[ -z "$RETENTION" ] && RETENTION=30
-
-if [ -z "$BUCKET" ] || [ -z "$PROVIDER" ] || [ -z "$PREFIX" ]; then
-    log "ERROR: backup-config.yaml missing required fields (provider / bucket / prefix)."
-    exit 1
-fi
-
-DATE=$(date -u +"%Y-%m-%d")
-log "Starting backup → $PROVIDER://$BUCKET/$PREFIX/$DATE/"
-
-# Default include paths if the YAML doesn't override them.
-INCLUDE_DEFAULT=(state knowledge outputs config/agent.json)
-INCLUDE_PATHS=()
-in_include=0
-while IFS= read -r line; do
-    if echo "$line" | grep -qE "^include:"; then in_include=1; continue; fi
-    if [ "$in_include" = "1" ]; then
-        if echo "$line" | grep -qE "^[a-z]"; then in_include=0; continue; fi
-        path=$(echo "$line" | sed 's/^[[:space:]]*-[[:space:]]*//' | sed 's/[[:space:]]*$//')
-        [ -n "$path" ] && INCLUDE_PATHS+=("$path")
-    fi
-done < "$CFG"
-[ ${#INCLUDE_PATHS[@]} -eq 0 ] && INCLUDE_PATHS=("${INCLUDE_DEFAULT[@]}")
-
-# Build the archive
-TMP_DIR=$(mktemp -d)
-trap "rm -rf $TMP_DIR" EXIT
-TARBALL="$TMP_DIR/$PREFIX-$DATE.tar.gz"
-
-log "Packaging: ${INCLUDE_PATHS[*]}"
-tar --exclude="state/tmp" --exclude="state/rag/index" --exclude=".DS_Store" \
-    -czf "$TARBALL" -C "$AGENT_DIR" "${INCLUDE_PATHS[@]}" 2>>"$LOG" || {
-    log "ERROR: tar failed"
-    exit 1
-}
-SIZE=$(stat -f%z "$TARBALL")
-log "Packaged: $TARBALL ($SIZE bytes)"
-
-# Upload — choose provider.
-case "$PROVIDER" in
-    gcs)
-        if ! command -v gsutil >/dev/null 2>&1; then
-            log "ERROR: gsutil not found in PATH. Install gcloud SDK or change provider."
-            exit 1
-        fi
-        gsutil cp "$TARBALL" "gs://$BUCKET/$PREFIX/$DATE/$(basename "$TARBALL")" >>"$LOG" 2>&1
-        ;;
-    s3)
-        if ! command -v aws >/dev/null 2>&1; then
-            log "ERROR: aws CLI not found in PATH. Install awscli or change provider."
-            exit 1
-        fi
-        aws s3 cp "$TARBALL" "s3://$BUCKET/$PREFIX/$DATE/$(basename "$TARBALL")" >>"$LOG" 2>&1
-        ;;
-    rsync)
-        # bucket field carries the rsync target (user@host:/path)
-        rsync -avz "$TARBALL" "$BUCKET/$PREFIX/$DATE/" >>"$LOG" 2>&1
-        ;;
-    *)
-        log "ERROR: unknown provider '$PROVIDER'"
-        exit 1
-        ;;
-esac
-
-log "Upload complete: $PROVIDER://$BUCKET/$PREFIX/$DATE/"
-
-# Update .maestro/last-backup.json so doctor can verify freshness.
-mkdir -p "$AGENT_DIR/.maestro"
-cat > "$AGENT_DIR/.maestro/last-backup.json" <<JSON
-{
-  "completed_at": "$(date -u +"%Y-%m-%dT%H:%M:%SZ")",
-  "provider": "$PROVIDER",
-  "bucket": "$BUCKET",
-  "prefix": "$PREFIX",
-  "size_bytes": $SIZE,
-  "tarball": "$(basename "$TARBALL")"
-}
-JSON
+AGENT_DIR="${AGENT_ROOT:-${AGENT_DIR:-$(cd "$SCRIPT_DIR/../.." && pwd)}}"
 
-log "Backup complete."
+NODE_BIN="$(command -v node || echo /opt/homebrew/bin/node)"
+exec "$NODE_BIN" "$SCRIPT_DIR/backup-run.mjs" --agent-dir "$AGENT_DIR" "$@"

package/scripts/org/send-orgmail.mjs

@@ -214,6 +214,22 @@ async function main() {
 
   const status = frame.result?.status;
   if (status === "queued" || status === "deduped") {
+    // Witness the send for the daemon's answer-assurance ledger. This CLI is the
+    // sanctioned orgmail lane for a spawned session, and a session is a separate
+    // process: without a receipt the daemon reads a delivered reply as silence
+    // and apologises to a human who already has their answer. Attribution rides
+    // in on the dispatcher's env. Best-effort — never fails the send.
+    try {
+      const { recordOutbound } = await import("../../lib/comms/receipts.mjs");
+      recordOutbound({
+        service: "orgmail",
+        channel: frame.result.threadId || flags.thread || flags.to[0],
+        kind: "session",
+        via: "send-orgmail.mjs",
+        chars: String(text).length,
+        agentRoot: cfg.agentRoot,
+      });
+    } catch { /* bookkeeping must never break a send */ }
     console.log(`send-orgmail: ${status} — messageId ${frame.result.messageId} threadId ${frame.result.threadId}`);
     process.exit(0);
   }