@cohortapp/agent-sdk 2.5.0 → 2.6.0

package/scripts/record-receipt.sh

@@ -0,0 +1,63 @@
+#!/bin/bash
+# record-receipt.sh — witness a successful outbound send for answer-assurance.
+#
+# WHY THIS EXISTS
+#
+# A spawned session is a separate `claude` process, and it is REQUIRED to reply
+# through these CLI lanes (prompt-builder mandates them; the org MCP send tools
+# are hard-blocked by a pre-tool hook). So when a session answers a human, the
+# daemon that spawned it learns nothing — it sees an exit code and nothing else.
+# That is why exit 0 was treated as proof of a reply, and why a 241-second
+# session whose own final text was "Nothing was sent." was marked handled
+# forever.
+#
+# A receipt is the evidence that crosses the process boundary. Without one on
+# every lane the daemon's assurance goes the other way and apologises — "I
+# didn't get a reply out to you" — to people who were answered fine.
+#
+# Attribution (which obligation, which session) rides in on the env the
+# dispatcher stamps on the child: MAESTRO_OBLIGATION_KEY / MAESTRO_SESSION_ID.
+#
+# Usage: record-receipt.sh <service> <channel> <via> [chars]
+# Always exits 0. Bookkeeping must never break a send.
+set +e
+
+SERVICE="$1"
+CHANNEL="$2"
+VIA="${3:-cli}"
+CHARS="${4:-0}"
+
+[ -n "$SERVICE" ] && [ -n "$CHANNEL" ] || exit 0
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+# Two different roots, deliberately kept apart.
+#   CODE_DIR  — where this checkout's lib/ lives. Always derivable from $0, so
+#               resolution never depends on the caller's env being right.
+#   AGENT_REPO_DIR — where STATE is written. That is the agent's root, and the
+#               receipt must land in the same tree the daemon sweeps.
+# Collapsing the two (the obvious "just use AGENT_DIR for both") silently writes
+# no receipt whenever an agent's root is not also a maestro checkout — and a
+# receipt that silently does not happen is the exact failure this file prevents.
+CODE_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+AGENT_REPO_DIR="${AGENT_DIR:-$CODE_DIR}"
+
+RECEIPTS=""
+for CAND in \
+  "$CODE_DIR/lib/comms/receipts.mjs" \
+  "$AGENT_REPO_DIR/lib/comms/receipts.mjs" \
+  "$AGENT_REPO_DIR/node_modules/@cohortapp/agent-sdk/lib/comms/receipts.mjs"
+do
+  if [ -f "$CAND" ]; then RECEIPTS="$CAND"; break; fi
+done
+[ -n "$RECEIPTS" ] || exit 0
+
+NODE_BIN="${MAESTRO_NODE_BIN:-/opt/homebrew/bin/node}"
+command -v "$NODE_BIN" >/dev/null 2>&1 || NODE_BIN="node"
+command -v "$NODE_BIN" >/dev/null 2>&1 || exit 0
+
+AGENT_DIR="$AGENT_REPO_DIR" "$NODE_BIN" "$RECEIPTS" record \
+  --service "$SERVICE" --channel "$CHANNEL" --kind session --via "$VIA" \
+  --chars "$CHARS" --agent-root "$AGENT_REPO_DIR" >/dev/null 2>&1
+
+exit 0

package/scripts/restore-from-backup.sh

@@ -177,11 +177,17 @@ if [ "$DRY_RUN" -eq 0 ] && [ -d "$UNPACK" ]; then
 fi
 
 # ---------------------------------------------------------------------------
-# 3. Restore config/, state/, logs/ — idempotent (back up existing first)
+# 3. Restore the durable trees — idempotent (back up existing first)
+#
+# This list MIRRORS lib/backup/policy.mjs DEFAULT_INCLUDE. It used to be just
+# config/state/logs, which meant the backup archived more than the restore put
+# back: knowledge/, memory/, outputs/ and the .maestro/ markers rode along in
+# every tarball and were silently left in the scratch dir on the way home.
+# Absent trees are skipped, so a legacy archive still restores exactly as before.
 # ---------------------------------------------------------------------------
 
-step "Step 3/5: restore config/, state/, logs/ into $AGENT_DIR"
-for dir in config state logs; do
+step "Step 3/5: restore the durable trees into $AGENT_DIR"
+for dir in config state knowledge memory outputs logs .maestro; do
     SRC="$UNPACK/$dir"
     DEST="$AGENT_DIR/$dir"
     if [ "$DRY_RUN" -eq 1 ]; then
@@ -204,6 +210,11 @@ for dir in config state logs; do
 done
 
 # Lock down secret-bearing files if they came back in the archive.
+#
+# Archives produced since 2026-08 CANNOT contain .env — lib/backup/policy.mjs
+# denies it in code and the runner verifies the finished tarball. This branch
+# stays for legacy archives (and for a .env the operator restored by hand),
+# because an over-permissive .env is worth catching whatever put it there.
 if [ "$DRY_RUN" -eq 1 ]; then
     note "DRY-RUN: would chmod 600 $AGENT_DIR/.env if present"
 elif [ -f "$AGENT_DIR/.env" ]; then

package/scripts/restore-from-backup.test.mjs

@@ -71,14 +71,17 @@ test("--dry-run lists every restore step and the manual follow-ups", () => {
     // The five numbered steps are all present.
     assert.match(out, /Step 1\/5: validate \+ decrypt/);
     assert.match(out, /Step 2\/5: unpack/);
-    assert.match(out, /Step 3\/5: restore config\/, state\/, logs\//);
+    assert.match(out, /Step 3\/5: restore the durable trees/);
     assert.match(out, /Step 4\/5: re-establish org-server \(Cohort\) identity/);
     assert.match(out, /Step 5\/5: remaining MANUAL steps/);
 
-    // Each of the three dirs is named in the plan.
-    assert.match(out, /would restore config\//);
-    assert.match(out, /would restore state\//);
-    assert.match(out, /would restore logs\//);
+    // Every tree the DEFAULT backup include set archives must also be a tree
+    // the restore puts back — otherwise the archive carries data the recovery
+    // silently leaves in the scratch dir. (lib/backup/policy.mjs
+    // DEFAULT_INCLUDE, plus logs/ which an operator may add explicitly.)
+    for (const dir of ["config", "state", "knowledge", "memory", "outputs", "logs", "\\.maestro"]) {
+      assert.match(out, new RegExp(`would restore ${dir}/`), `restore plan omits ${dir}/`);
+    }
 
     // The irreducibly-manual follow-ups: secret recovery + cohort re-pair.
     assert.match(out, /maestro secrets sync/);

package/scripts/send-email-threaded.py

@@ -29,6 +29,45 @@ from email.mime.base import MIMEBase
 from email import encoders
 from email.utils import formatdate
 
+
+def _record_receipt(service, channel, via, chars=0, kind="session"):
+    """Witness a successful send for the daemon's answer-assurance ledger.
+
+    Shells out to lib/comms/receipts.mjs because that module owns the on-disk
+    format and this script cannot import it. Entirely best-effort and silent on
+    every failure: a send must never be broken by its own bookkeeping.
+    """
+    try:
+        import subprocess
+        # Two roots, kept apart: code_dir is where lib/ lives (always derivable
+        # from __file__), agent_dir is where state is written. Collapsing them
+        # writes no receipt whenever an agent root is not also a checkout.
+        code_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+        agent_dir = os.environ.get("AGENT_DIR") or code_dir
+        mod = None
+        for cand in (os.path.join(code_dir, "lib", "comms", "receipts.mjs"),
+                     os.path.join(agent_dir, "lib", "comms", "receipts.mjs"),
+                     os.path.join(agent_dir, "node_modules", "@cohortapp",
+                                  "agent-sdk", "lib", "comms", "receipts.mjs")):
+            if os.path.exists(cand):
+                mod = cand
+                break
+        if not mod or not channel:
+            return
+        node = os.environ.get("MAESTRO_NODE_BIN") or "/opt/homebrew/bin/node"
+        if not os.path.exists(node):
+            node = "node"
+        subprocess.run(
+            [node, mod, "record", "--service", service, "--channel", str(channel),
+             "--kind", kind, "--via", via, "--chars", str(chars),
+             "--agent-root", agent_dir],
+            timeout=10, check=False,
+            stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+            env={**os.environ, "AGENT_DIR": agent_dir})
+    except Exception:
+        pass
+
+
 # LLM-based dedup (Layer 1) — replaces old subject+recipient lock per CEO directive ib-20260406-001
 try:
     sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
@@ -369,6 +408,14 @@ def send_email(to, subject, body, reply_subject=None, attachments=None, cc=None,
         except Exception:
             pass
 
+    # Post-send: delivery receipt. This script is the mandated Gmail reply lane
+    # for a spawned session, and a session is a separate process — unless the
+    # send is witnessed here the daemon cannot tell an answered ask from a
+    # session that exited 0 in silence, and it apologises to people who were
+    # already answered. Attribution rides in on the dispatcher's env.
+    _record_receipt(service="gmail", channel=to, via="send-email-threaded.py",
+                    chars=len(body or ""))
+
 if __name__ == '__main__':
     if len(sys.argv) < 4 and '--help' not in sys.argv and '-h' not in sys.argv:
         print("Usage: send-email-threaded.py <to> <subject> <body> [--reply-to-subject 'original subject'] [--attachment file]")

package/scripts/send-sms.sh

@@ -162,6 +162,10 @@ if [ "$HTTP_CODE" = "201" ] || [ "$HTTP_CODE" = "200" ]; then
     PREVIEW=$(printf '%s' "$BODY" | head -c 200)
     "$SCRIPT_DIR/outbound-dedup.sh" confirm sms "$DEDUP_KEY" "To:$TO SID:$MESSAGE_SID $PREVIEW" 2>/dev/null || true
   fi
+  # Witness the send for answer-assurance (see scripts/record-receipt.sh).
+  if [ -x "$SCRIPT_DIR/record-receipt.sh" ]; then
+    AGENT_DIR="$AGENT_REPO_DIR" "$SCRIPT_DIR/record-receipt.sh" sms "$TO" send-sms.sh "${#BODY}" || true
+  fi
   echo "SMS sent successfully"
   echo "  To: $TO"
   echo "  From: $FROM_NUMBER"

package/scripts/send-whatsapp.sh

@@ -268,6 +268,10 @@ if [ "$HTTP_CODE" = "201" ] || [ "$HTTP_CODE" = "200" ]; then
     PREVIEW=$(printf '%s' "${BODY:-template:$TEMPLATE}" | head -c 200)
     "$SCRIPT_DIR/outbound-dedup.sh" confirm whatsapp "$DEDUP_KEY" "To:$TO SID:$MESSAGE_SID $PREVIEW" 2>/dev/null || true
   fi
+  # Witness the send for answer-assurance (see scripts/record-receipt.sh).
+  if [ -x "$SCRIPT_DIR/record-receipt.sh" ]; then
+    AGENT_DIR="$AGENT_REPO_DIR" "$SCRIPT_DIR/record-receipt.sh" whatsapp "$TO" send-whatsapp.sh "${#BODY}" || true
+  fi
   echo "WhatsApp message sent successfully (${MODE} mode)"
   echo "  To: $TO"
   echo "  From: $FROM_NUMBER (whatsapp:${FROM_NUMBER})"

package/scripts/setup/init-backup.mjs

@@ -1,13 +1,23 @@
 #!/usr/bin/env node
 /**
- * init-backup.mjs — Off-machine state backup wizard.
+ * init-backup.mjs — give this agent a DR posture, non-interactively.
  *
- * Configures `.maestro/backup-config.yaml` with bucket details and seeds
- * a daily launchd plist that runs scripts/maintenance/backup-to-cloud.sh.
- * Requires interactive input — does NOT auto-run.
+ * DECISION (delegated authority, 2026-08-12): this step is now AUTO-RUNNABLE
+ * and writes an ENABLED config. It used to be an interactive wizard that wrote
+ * `enabled: false` and demanded a bucket + cloud credentials, which meant every
+ * agent was born failing `maestro doctor` on a check nobody could clear on the
+ * spot — so the check became noise and the fleet's real DR posture stayed at
+ * zero. The default it writes now needs no credentials, no bucket and no
+ * network: nightly LOCAL restore points in
+ * ~/Library/Application Support/Maestro/backups/<prefix>/, outside the agent
+ * repo. The off-machine tier stays opt-in and doctor WARNs (not FAILs) until
+ * it is set — see lib/backup/policy.mjs for the full reasoning and for the
+ * hard deny-list that keeps .env and .cohort-key.json out of every archive.
+ *
+ * Idempotent: an existing config is left exactly as the operator left it.
  */
-import { existsSync, writeFileSync, mkdirSync } from "node:fs";
-import { join, resolve, dirname } from "node:path";
+import { existsSync, writeFileSync, mkdirSync, readFileSync } from "node:fs";
+import { join, resolve, dirname, basename } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -16,39 +26,84 @@ const AGENT_DIR = process.env.AGENT_ROOT || process.env.AGENT_DIR || resolve(__d
 const ok = (m) => process.stdout.write(`[init-backup]  ✓ ${m}\n`);
 const warn = (m) => process.stdout.write(`[init-backup]  ⚠ ${m}\n`);
 
+/** Same resolution ladder as the runner: agent lib → installed SDK → checkout. */
+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(process.env.MAESTRO_ROOT || resolve(__dirname, "..", ".."), "lib", "backup", "policy.mjs"),
+    resolve(__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");
+}
+
+/** Archive prefix: the repoSlug from config/agent.json, else the directory name. */
+function derivePrefix() {
+  try {
+    const p = join(AGENT_DIR, "config", "agent.json");
+    if (existsSync(p)) {
+      const doc = JSON.parse(readFileSync(p, "utf-8"));
+      const candidate = doc.repoSlug || doc.agentId || doc.firstName;
+      if (candidate) return String(candidate);
+    }
+  } catch {
+    /* fall through to the directory name */
+  }
+  return basename(AGENT_DIR);
+}
+
+const policy = await loadPolicy();
+
 mkdirSync(join(AGENT_DIR, ".maestro"), { recursive: true });
-const cfg = join(AGENT_DIR, ".maestro/backup-config.yaml");
-if (existsSync(cfg)) {
-  ok("backup-config.yaml already present");
+const cfgPath = join(AGENT_DIR, ".maestro/backup-config.yaml");
+
+if (existsSync(cfgPath)) {
+  const plan = policy.resolveBackupPlan({ agentRoot: AGENT_DIR });
+  if (!plan.readable) {
+    warn(`${cfgPath} exists but is unparseable YAML — leaving it alone. Fix it or delete it and re-run.`);
+    process.exit(1);
+  }
+  ok(`backup-config.yaml already present (tier: ${plan.tier})`);
+  if (plan.tier === "local") {
+    warn("Local restore points only — nothing survives losing this machine. Set offsite.provider + offsite.bucket to close that gap.");
+  }
   process.exit(0);
 }
 
-writeFileSync(cfg, `# Off-machine state backup configuration
-# Fill in the bucket details, then run:
-#   maestro init backup-replication --apply
-#
-# Backups cover (configurable below):
-#   - state/   (queues, dashboards, inboxes — minus state/tmp/)
-#   - knowledge/
-#   - outputs/
-#   - logs/ (rotated archives only — current-day logs excluded)
-#   - config/agent.json (identity SOT)
-
-enabled: false
-provider: gcs            # gcs | s3 | rsync
-bucket: ""               # e.g. northwind-maestro-backups
-prefix: agent-name-here  # e.g. ravi-ai (typically the repoSlug)
-schedule: "0 3 * * *"    # daily 03:00 local (overrides via launchd plist)
-include:
-  - state
-  - knowledge
-  - outputs
-  - logs
-  - config/agent.json
-exclude:
-  - state/tmp
-  - state/rag/index/*.bin
-retention_days: 30
-`);
-ok(`wrote ${cfg}`);
-warn("Backup is configured but NOT enabled. Edit .maestro/backup-config.yaml + set enabled: true, then re-run init.");
+const prefix = policy.sanitisePrefix(derivePrefix());
+writeFileSync(cfgPath, policy.defaultConfigYaml({ prefix }));
+ok(`wrote ${cfgPath} (prefix: ${prefix})`);
+
+const plan = policy.resolveBackupPlan({ agentRoot: AGENT_DIR });
+ok(`Tier 1 ON — nightly local restore points at ${plan.local.dir} (retention ${plan.local.retentionDays}d)`);
+ok(`Archived: ${plan.include.join(", ")}`);
+ok("NEVER archived: .env, .cohort-key.json, private keys, .claude/.credentials.json, node_modules, .git, state/tmp, RAG index");
+
+// Take the FIRST backup right now rather than waiting for 03:10.
+//
+// Without this the agent is still born failing doctor ("enabled but has NEVER
+// completed a run — there is no restore point") for up to 24 hours, which is
+// the exact shape of the problem this whole change exists to remove. Running it
+// here also proves the pipeline end-to-end at setup time, when a human is
+// watching, instead of at 3am when nobody is. Cheap on a fresh agent, and a
+// failure is REPORTED but never fatal — a broken first backup must not take the
+// rest of `maestro init` down with it.
+if (!process.argv.includes("--no-run")) {
+  const { spawnSync } = await import("node:child_process");
+  const runner = existsSync(join(AGENT_DIR, "scripts/maintenance/backup-run.mjs"))
+    ? join(AGENT_DIR, "scripts/maintenance/backup-run.mjs")
+    : resolve(__dirname, "..", "maintenance", "backup-run.mjs");
+  const r = spawnSync(process.execPath, [runner, "--agent-dir", AGENT_DIR], {
+    encoding: "utf-8",
+    timeout: 10 * 60 * 1000,
+  });
+  if (r.status === 0) {
+    ok("first restore point taken — this agent is recoverable as of right now");
+  } else {
+    warn(`the first backup did NOT succeed (exit ${r.status ?? "?"}): ${(r.stderr || r.stdout || "").trim().split("\n").slice(-3).join(" / ")}`);
+    warn("Run `node scripts/maintenance/backup-run.mjs` and fix it — until it passes, this agent has no restore point.");
+  }
+}
+
+warn("Tier 2 (off-machine) is NOT configured — a dead Mac mini still loses everything. Set offsite.provider (gcs|s3|rsync) + offsite.bucket in .maestro/backup-config.yaml.");

package/scripts/slack-send.sh

@@ -285,3 +285,15 @@ if [ "$STATUS" = "OK" ] && [ -n "$RESPONDING_TO" ] && [ -n "$DEDUP_ACQUIRED" ];
   "$SCRIPT_DIR/slack-responded.sh" confirm "$CHANNEL" "$RESPONDING_TO" "$PREVIEW" 2>/dev/null || true
   DEDUP_CONFIRMED="1"
 fi
+
+# ── Delivery receipt ────────────────────────────────────────────────
+# This script IS the Slack reply lane for a spawned session (prompt-builder
+# mandates it; the MCP send tools are hard-blocked by a pre-tool hook). A session
+# is a separate process, so unless the send is witnessed here the daemon cannot
+# tell "the session answered" from "the session exited 0 saying nothing" — and
+# its answer-assurance then apologises to a human who was already answered.
+# Attribution (obligation key / session id) rides in on the dispatcher's env.
+# Best-effort and always non-fatal: bookkeeping must never break a send.
+if [ "$STATUS" = "OK" ] && [ -x "$SCRIPT_DIR/record-receipt.sh" ]; then
+  AGENT_DIR="$AGENT_REPO_DIR" "$SCRIPT_DIR/record-receipt.sh" slack "$CHANNEL" slack-send.sh "${#MESSAGE}" || true
+fi