@cohortapp/agent-sdk 2.3.0

package/bin/maestro.mjs

@@ -0,0 +1,3516 @@
+#!/usr/bin/env node
+/**
+ * Maestro CLI — Create and manage autonomous AI agent deployments.
+ *
+ * Usage:
+ *   npx @cohortapp/agent-sdk create <dirname>   # Scaffold a new agent repo
+ *   npx @cohortapp/agent-sdk upgrade            # Update framework files in current agent repo
+ *   npx @cohortapp/agent-sdk doctor             # Verify installation and configuration
+ */
+
+import { resolve, join, dirname, relative, sep, basename } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import {
+  mkdirSync,
+  cpSync,
+  copyFileSync,
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  readdirSync,
+  statSync,
+  lstatSync,
+  openSync,
+  readSync,
+  closeSync,
+} from "node:fs";
+import { execFileSync, spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import { checkOwnershipSet } from "../lib/fs-ownership.mjs";
+import { resolveArchetype, migrateLegacyArchetype } from "../lib/archetype.mjs";
+import { runAudit, applyFixes, buildAttestation } from "../lib/security/audit-engine.mjs";
+import { selectProvider } from "../lib/secrets/providers.mjs";
+import { syncSecrets, rotateSecret, makeBroker, auditLogPath } from "../lib/secrets/broker.mjs";
+import { applyBrandEnvCompat } from "../lib/env-compat.mjs";
+
+// Fleet back-compat FIRST: bridge NEOLITH_* ⇄ COHORT_* env names before any
+// env-first resolution below — installed hosts still export the legacy names.
+applyBrandEnvCompat();
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const MAESTRO_ROOT = resolve(__dirname, "..");
+const SCAFFOLD_DIR = join(MAESTRO_ROOT, "scaffold");
+const FRAMEWORK_FEATURES_PATH = join(MAESTRO_ROOT, "framework-features.json");
+
+// Plist architecture marker — must match the value emitted by
+// scripts/local-triggers/generate-plists.sh. Used by doctor + upgrade
+// migration to distinguish cadence-bus plists from the legacy
+// spawn-per-tick pattern (which invoked run-trigger.sh directly).
+const PLIST_ARCH_MARKER = "maestro-plist-arch: cadence-bus";
+const LEGACY_PLIST_INDICATOR = "run-trigger.sh";
+
+// ---------------------------------------------------------------------------
+// Colours
+// ---------------------------------------------------------------------------
+
+const C = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  red: "\x1b[31m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+  cyan: "\x1b[36m",
+};
+
+const log = (msg) => console.log(`${C.blue}[maestro]${C.reset} ${msg}`);
+const ok = (msg) => console.log(`${C.green}  ✓${C.reset} ${msg}`);
+const warn = (msg) => console.log(`${C.yellow}  ⚠${C.reset} ${msg}`);
+const fail = (msg) => console.error(`${C.red}  ✗${C.reset} ${msg}`);
+
+// ---------------------------------------------------------------------------
+// CREATE — scaffold a new agent repo
+// ---------------------------------------------------------------------------
+
+function create(targetName) {
+  if (!targetName) {
+    fail("Usage: maestro create <agent-directory-name>");
+    fail("Example: maestro create acme-ai");
+    process.exit(1);
+  }
+
+  const targetDir = resolve(process.cwd(), targetName);
+
+  if (existsSync(targetDir)) {
+    fail(`Directory already exists: ${targetDir}`);
+    process.exit(1);
+  }
+
+  console.log();
+  log(`Creating agent: ${targetName}`);
+  mkdirSync(targetDir, { recursive: true });
+
+  // ── Step 1: Copy framework files ────────────────────────────────────────
+
+  log("Copying framework files...");
+
+  const frameworkDirs = [
+    "scripts",
+    "agents",
+    "workflows",
+    "policies",
+    "teams",
+    "docs",
+    "public",
+    "plugins",
+    "schedules",
+    "desktop-control",
+    "ingest",
+    "mcp",
+    "services",
+    // lib/ holds shared framework primitives — singleton lock, cadence bus,
+    // action executor, tool definitions — that scripts/ imports via relative
+    // paths. Must travel with each agent repo so the relative imports work
+    // without depending on a checkout of @cohortapp/agent-sdk on the same host.
+    "lib",
+  ];
+
+  for (const dir of frameworkDirs) {
+    const src = join(MAESTRO_ROOT, dir);
+    if (existsSync(src)) {
+      cpSync(src, join(targetDir, dir), { recursive: true });
+      ok(dir);
+    }
+  }
+
+  // ── Step 2: Copy scaffold templates ─────────────────────────────────────
+
+  log("Copying agent templates...");
+
+  if (existsSync(SCAFFOLD_DIR)) {
+    cpSync(SCAFFOLD_DIR, targetDir, { recursive: true });
+    ok("scaffold templates");
+  }
+
+  // Copy .claude/ directory
+  const claudeDir = join(MAESTRO_ROOT, ".claude");
+  if (existsSync(claudeDir)) {
+    cpSync(claudeDir, join(targetDir, ".claude"), { recursive: true });
+    ok(".claude/ (settings, commands)");
+  }
+
+  // ── Step 3: Create agent-specific directories ───────────────────────────
+
+  log("Creating agent directories...");
+
+  const agentDirs = [
+    "config",
+    "knowledge/decisions",
+    "knowledge/decisions/archive",
+    "knowledge/entities",
+    "knowledge/memory",
+    "knowledge/sources",
+    "knowledge/syntheses",
+    "memory/interactions",
+    "memory/profiles/users",
+    "memory/profiles/channels",
+    "memory/precedents",
+    "memory/precedents/market-signals",
+    "memory/indexes",
+    "memory/templates",
+    "state/inbox/slack",
+    "state/inbox/gmail",
+    "state/inbox/calendar",
+    "state/inbox/sms",
+    "state/inbox/whatsapp",
+    "state/inbox/internal",
+    "state/inbox/attachments",
+    "state/inbox/processed",
+    "state/queues",
+    "state/dashboards",
+    "state/polling",
+    "state/locks/outbound",
+    "state/triggers/priority",
+    "state/handoffs",
+    "state/huddle",
+    "state/indexes",
+    "state/rag",
+    "state/sessions",
+    "state/slack-responded",
+    "state/slack-thread-tracker",
+    "state/tmp",
+    "state/cadence-bus",
+    "state/cadence-bus/inbox",
+    "state/cadence-bus/claimed",
+    "state/cadence-bus/processed",
+    "state/cadence-bus/failed",
+    "state/cadence-bus/dlq",
+    // 1.12.0 — channel bus + voice + WhatsApp (Baileys) state dirs.
+    // Pre-created at scaffold time so daemon startups don't race with
+    // first-run mkdir calls. Each feature's init wizard re-creates these
+    // idempotently as a safety net.
+    "state/channels",
+    "state/voice",
+    "state/whatsapp/auth",
+    "state/whatsapp/audio",
+    "state/whatsapp/outbound",
+    "outputs/briefs",
+    "outputs/drafts",
+    "outputs/memos",
+    "outputs/research",
+    "outputs/tasks",
+    "outputs/sessions",
+    "logs/polling",
+    "logs/workflows",
+    "logs/sessions",
+    "logs/audit",
+    "logs/security",
+    "logs/evolution",
+    "logs/huddle",
+    "logs/daemon",
+    "logs/cadence-bus",
+    "logs/infra",
+    "logs/monitor",
+    "logs/phone",
+    "logs/sms",
+    "logs/whatsapp",
+    "logs/email",
+    // 1.12.0
+    "logs/channels",
+    "logs/voice",
+    "logs/voice/sessions",
+    "self-optimization/scenarios",
+    "tests",
+  ];
+
+  for (const dir of agentDirs) {
+    mkdirSync(join(targetDir, dir), { recursive: true });
+  }
+  ok(`${agentDirs.length} agent directories`);
+
+  // ── Step 3b: Generate template files ───────────────────────────────────
+  // These are empty-but-structured templates that define the operational
+  // schema for queues, dashboards, knowledge, and config. Without them,
+  // workflows and triggers have nothing to read/write.
+
+  log("Generating operational templates...");
+
+  // Queue templates — 16 operational queues
+  const queueTemplates = {
+    "action-stack": "Active action items requiring attention or follow-through",
+    "decision-queue": "Key decisions awaiting principal input or closure",
+    "follow-ups": "Commitments to external parties with due dates",
+    "awaiting-reply": "Messages sent that are awaiting responses",
+    "awaiting-approval": "Items pending principal or stakeholder approval",
+    "blocked-initiatives": "Strategic initiatives blocked by dependencies",
+    "high-risk-items": "Items with elevated risk requiring close monitoring",
+    "upcoming-deadlines": "Time-sensitive items with approaching deadlines",
+    "relationship-health": "Relationship maintenance and engagement tracking",
+    "hiring-critical-path": "Critical hiring actions and pipeline blockers",
+    "platform-blockers": "Technical and platform issues blocking delivery",
+    "capital-watchpoints": "Financial and fundraising items requiring attention",
+    "legal-obligations": "Regulatory submissions and legal compliance deadlines",
+    "narrative-opportunities": "Strategic narrative and thought leadership opportunities",
+    "tech-debt": "Technical debt with strategic impact",
+    "improvement-backlog": "Self-improvement and operational enhancement candidates",
+  };
+
+  for (const [name, desc] of Object.entries(queueTemplates)) {
+    const content = `queue_name: ${name}\ndescription: ${desc}\nitems: []\n`;
+    writeFileSync(join(targetDir, `state/queues/${name}.yaml`), content);
+  }
+  ok(`${Object.keys(queueTemplates).length} queue templates`);
+
+  // Dashboard templates — 10 operational dashboards
+  const dashboardTemplates = {
+    "executive-summary": {
+      description: "Primary situational awareness — read at every session start",
+      fields: "generated: null\nsummary:\n  total_open_items: 0\n  critical_items: 0\n  overdue_items: 0\n  sla_breaches: 0\n  items_resolved_today: 0\n  items_created_today: 0\nqueue_health: {}\ntop_priorities: []\ntop_blockers: []\n",
+    },
+    "daemon-health": {
+      description: "System health metrics for the daemon and triggers",
+      fields: "status: initialising\nlast_check: null\ntrigger_health: {}\npoller_health: {}\n",
+    },
+    "strategy-scorecard": {
+      description: "Progress on strategic priorities and quarterly OKRs",
+      fields: "generated: null\npriorities: []\ninitiatives: []\n",
+    },
+    "risk-register": {
+      description: "Enterprise risk register with severity and mitigation",
+      fields: "generated: null\nrisks: []\n",
+    },
+    "engineering-health": {
+      description: "Per-repo engineering activity, PRs, delivery confidence",
+      fields: "generated: null\nrepositories: []\ndelivery_confidence: null\n",
+    },
+    "org-health": {
+      description: "Hiring pipeline, capability gaps, structural risks",
+      fields: "generated: null\nhiring_pipeline: {}\ncapability_gaps: []\n",
+    },
+    "leadership-accountability": {
+      description: "Per-leader commitment follow-through tracking",
+      fields: "generated: null\nleaders: []\n",
+    },
+    "relationship-pipeline": {
+      description: "Strategic relationships with stage and warmth tracking",
+      fields: "generated: null\nrelationships: []\n",
+    },
+    "capital-readiness": {
+      description: "Runway, fundraising readiness, investor pipeline",
+      fields: "generated: null\nrunway_months: null\nreadiness_score: null\npipeline: []\n",
+    },
+    "system-health": {
+      description: "Self-governance metrics — evolution, coverage, queue health",
+      fields: "generated: null\nevolution_changes: 0\nknowledge_coverage: null\ntrigger_reliability: null\n",
+    },
+  };
+
+  for (const [name, { description, fields }] of Object.entries(dashboardTemplates)) {
+    const content = `# ${name.replace(/-/g, " ").replace(/\b\w/g, c => c.toUpperCase())} Dashboard\n# ${description}\n\n${fields}`;
+    writeFileSync(join(targetDir, `state/dashboards/${name}.yaml`), content);
+  }
+  ok(`${Object.keys(dashboardTemplates).length} dashboard templates`);
+
+  // Config templates — operational config files
+  log("Generating config templates...");
+
+  const configTemplates = {
+    "environment.yaml": `# Environment Configuration
+# All environment-specific values — actual secrets are in .env
+# Agent identity is defined in config/agent.ts
+
+system:
+  name: maestro
+  version: 1.0.0
+  operator_persona: "UNCONFIGURED"
+  operator_role: "UNCONFIGURED"
+  company: ""
+  ceo: ""
+  timezone: UTC
+
+machine:
+  type: mac-mini
+  os: macOS
+  hostname: \${HOSTNAME}
+  purpose: Autonomous agent operations node
+
+paths:
+  agent_home: ~/${targetName}
+  logs: ~/${targetName}/logs
+  outputs: ~/${targetName}/outputs
+`,
+    "contacts.yaml": `# Key Contacts
+# Communication classifications and relationship context
+# Updated by: init-maestro wizard, agent interactions
+
+contacts: []
+
+# Classification levels:
+# - internal: team members, direct reports
+# - external-trusted: partners, advisors, board members
+# - external-standard: vendors, candidates, general contacts
+# - regulatory: regulators, legal counterparties
+`,
+    "priorities.yaml": `# Active Strategic Priorities
+# Updated by: weekly-priorities workflow, principal directive
+# Read by: morning-brief, backlog-executor, strategy-scorecard
+
+priorities: []
+
+# Priority format:
+# - id: P1
+#   title: Priority title
+#   status: active | paused | completed
+#   owner: principal | agent
+#   milestones: []
+#   deadline: null
+`,
+    "sla-defaults.yaml": `# SLA Defaults — response time expectations by item type
+# Used by: inbox-processor, meeting-action-capture, midday-sweep
+
+sla_defaults:
+  principal_request: 4
+  leadership_request: 24
+  external_partner: 48
+  regulatory: 24
+  candidate: 24
+  board_member: 12
+  investor: 24
+  general: 72
+
+thresholds:
+  at_risk_percent: 75
+  breach_percent: 100
+
+drift_thresholds:
+  critical_priority: 7
+  medium_priority: 14
+  low_priority: 30
+`,
+    "brand-assets.yaml": `# Brand Assets Configuration
+# Official brand assets, design system, and usage rules
+# Assets directory: public/assets/
+
+asset_inventory:
+  icon_dark: public/assets/icon-dark.svg
+  icon_light: public/assets/icon-light.svg
+  logo_dark: public/assets/logo-dark.svg
+  logo_light: public/assets/logo-light.svg
+
+usage_rules:
+  dark_variants: "Use on light/white backgrounds"
+  light_variants: "Use on dark backgrounds"
+  full_logo: "Cover pages, document headers, title slides"
+  icon_only: "Footers, watermarks, compact placements"
+  never: "stretch, rotate, recolour, or modify the assets"
+`,
+    "repo-registry.yaml": `# Source Repository Registry
+# Cross-repository map for codebase awareness
+# Updated by: init-maestro wizard
+
+repositories: []
+
+# Format:
+# - name: repo-name
+#   path: ~/repo-name
+#   purpose: What this repo contains
+#   domains: [domain1, domain2]
+`,
+    "slack-channels.yaml": `# Slack Channel Configuration
+# Which channels the agent monitors and their purpose
+# Updated by: init-maestro wizard
+
+channels: []
+
+# Format:
+# - id: C0XXXXX
+#   name: channel-name
+#   purpose: What this channel is for
+#   monitor: true | false
+#   respond: true | false
+`,
+    "tooling-map.yaml": `# Tooling Map
+# Maps responsibilities to available tools and scripts
+# Generated by: init-maestro sub-agent 8
+
+tools: []
+`,
+    "validation-rules.yaml": `# Outbound Correspondence Validation Rules
+# Used by: scripts/validate-outbound.py
+# Purpose: Pre-send gate to prevent factual inaccuracies and protocol violations
+
+relationship_claims:
+  enabled: true
+  severity: block
+  patterns: []
+
+ai_disclosure:
+  enabled: true
+  severity: block
+  blocked_phrases:
+    - "I am an AI"
+    - "as an AI"
+    - "I'm an artificial intelligence"
+    - "language model"
+
+tone_violations:
+  enabled: true
+  severity: warn
+  rules: []
+`,
+    "mcp-integrations.yaml": `# MCP Server Integration Configuration
+# Which MCP services this agent connects to
+# Updated by: init-maestro wizard
+
+integrations:
+  slack: { enabled: false, notes: "Configure via .env" }
+  gmail: { enabled: false, notes: "Configure via .env" }
+  calendar: { enabled: false, notes: "Configure via .env" }
+`,
+    "mcp-servers.json": `{}`,
+    "caller-id-map.yaml": `# Caller ID Map
+# Maps phone numbers to known contacts for SMS/voice identification
+# Updated by: agent interactions
+
+contacts: {}
+`,
+    "hiring.yaml": `# Hiring Configuration
+# Pipeline settings, screening rules, and template references
+# Updated by: init-maestro wizard (for executive-operator / operations-leader archetypes)
+
+enabled: false
+roles: []
+screening:
+  auto_advance_threshold: 75
+  auto_reject_threshold: 40
+  review_band: [40, 75]
+`,
+  };
+
+  for (const [filename, content] of Object.entries(configTemplates)) {
+    const dest = join(targetDir, `config/${filename}`);
+    if (!existsSync(dest)) {
+      writeFileSync(dest, content);
+    }
+  }
+  ok(`${Object.keys(configTemplates).length} config templates`);
+
+  // Knowledge templates — schemas and empty indexes
+  log("Generating knowledge templates...");
+
+  const knowledgeTemplates = {
+    "decisions/decision-schema.yaml": `# Decision Record Schema
+# Format: DEC-YYYY-MM-DD-NNN
+# See docs for full schema documentation
+
+schema:
+  version: "1.0"
+  fields:
+    id: { type: string, format: "DEC-YYYY-MM-DD-NNN", required: true }
+    date: { type: date, format: "YYYY-MM-DD", required: true }
+    title: { type: string, required: true }
+    domain: { type: string, required: true }
+    decision_maker: { type: string, required: true }
+    decision_text: { type: string, required: true }
+    context: { type: string, required: true }
+    rationale: { type: string, required: true }
+    status: { type: string, enum: [active, superseded, reversed, completed], default: active }
+`,
+    "decisions/index.yaml": `# Decision Index
+# Auto-maintained by decision-log agent
+
+decisions: []
+`,
+    "entities/entity-map.yaml": `# Entity Map
+# All contacts, companies, regulators, advisors
+# De-duplication rules and relationship mapping
+
+entities: []
+`,
+    "entities/org-chart.md": `# Organisation Chart
+
+*Configure via /init-maestro*
+`,
+    "sources/source-registry.yaml": `# Authoritative Source Registry
+# Central registry of all information sources
+
+sources: {}
+`,
+    "sources/blocker-playbooks.yaml": `# Blocker Resolution Playbooks
+# Common blocker patterns and resolution strategies
+
+playbooks: []
+`,
+    "syntheses/strategy-state.yaml": `# Living Strategy State
+# Evolves weekly with strategic position, assumptions, risks, signals
+
+last_updated: null
+strategic_position: ""
+key_assumptions: []
+active_risks: []
+market_signals: []
+`,
+    "syntheses/README.md": `# Knowledge Syntheses
+
+Strategic syntheses generated by domain agents. Updated weekly.
+`,
+    "memory/executive-memory.yaml": `# Executive Memory
+# Institutional memory for strategic context
+
+entries: []
+`,
+  };
+
+  for (const [path, content] of Object.entries(knowledgeTemplates)) {
+    writeFileSync(join(targetDir, `knowledge/${path}`), content);
+  }
+  ok(`${Object.keys(knowledgeTemplates).length} knowledge templates`);
+
+  // Self-optimization templates
+  const selfOptTemplates = {
+    "program.md": `# Self-Optimization Program
+
+This agent evolves its own operating setup through structured experimentation.
+Changes are classified by risk: low (auto-apply), medium (apply + notify), high (escalate).
+`,
+    "experiment-log.yaml": `# Experiment Log
+experiments: []
+`,
+    "failure-patterns.yaml": `# Failure Patterns
+# Recurring failure modes and mitigations
+patterns: []
+`,
+    "metric-snapshots.yaml": `# Metric Snapshots
+# Periodic captures of operational metrics
+snapshots: []
+`,
+    "scoring-rubrics.yaml": `# Scoring Rubrics
+# Evaluation criteria for self-assessment
+rubrics: []
+`,
+  };
+
+  for (const [filename, content] of Object.entries(selfOptTemplates)) {
+    writeFileSync(join(targetDir, `self-optimization/${filename}`), content);
+  }
+  ok(`${Object.keys(selfOptTemplates).length} self-optimization templates`);
+
+  // .gitkeep files for empty directories that git would otherwise ignore
+  const gitkeepDirs = [
+    "state/handoffs", "state/huddle", "state/indexes", "state/rag",
+    "state/sessions", "state/slack-responded", "state/slack-thread-tracker",
+    "state/tmp", "state/inbox/attachments", "state/inbox/processed",
+    "state/inbox/whatsapp", "memory/precedents/market-signals",
+    "knowledge/decisions/archive", "tests",
+    "logs/infra", "logs/monitor", "logs/phone", "logs/sms",
+    "logs/whatsapp", "logs/email", "self-optimization/scenarios",
+  ];
+
+  for (const dir of gitkeepDirs) {
+    const keepFile = join(targetDir, dir, ".gitkeep");
+    if (!existsSync(keepFile)) {
+      writeFileSync(keepFile, "");
+    }
+  }
+  ok(".gitkeep files for empty directories");
+
+  // ── Step 4: Generate package.json ───────────────────────────────────────
+
+  log("Generating package.json...");
+
+  const agentPackage = {
+    name: targetName,
+    version: "1.0.0",
+    description: "Maestro AI agent — configure with: maestro setup",
+    type: "module",
+    private: true,
+    scripts: {
+      "init-agent": "./scripts/setup/init-agent.sh",
+      "configure-macos": "sudo ./scripts/setup/configure-macos.sh",
+      "configure-macos:check": "./scripts/setup/configure-macos.sh --check",
+      daemon: "node scripts/daemon/maestro-daemon.mjs",
+      "cadence:enqueue": "node scripts/cadence/enqueue-cadence-tick.mjs",
+      "cadence:consume": "node scripts/daemon/cadence-consumer.mjs",
+      "cadence:status": "node scripts/cadence/cadence-status.mjs",
+      healthcheck: "./scripts/healthcheck.sh",
+      "emergency-stop": "./scripts/emergency-stop.sh",
+      resume: "./scripts/resume-operations.sh",
+      "pdf:memo": "node scripts/pdf-generation/build-document.mjs --template memo",
+      "pdf:board-pack": "node scripts/pdf-generation/build-document.mjs --template board-pack",
+      "pdf:letter": "node scripts/pdf-generation/build-document.mjs --template corporate-letter",
+      "pdf:investor": "node scripts/pdf-generation/build-document.mjs --template investor-letter",
+      "gen:illustration": "node scripts/media-generation/generate-assets.mjs --illustration",
+      "gen:video": "node scripts/media-generation/generate-assets.mjs --video",
+      "gen:all-missing": "node scripts/media-generation/generate-assets.mjs --all-missing",
+      "gen:list": "node scripts/media-generation/generate-assets.mjs --list",
+      "slack:events": "node scripts/slack-events-server.mjs",
+      "slack:events:start": "./scripts/slack-events-ctl.sh start",
+      "slack:events:stop": "./scripts/slack-events-ctl.sh stop",
+      "slack:events:status": "./scripts/slack-events-ctl.sh status",
+      upgrade: "npx @cohortapp/agent-sdk upgrade",
+      init: "npx @cohortapp/agent-sdk init",
+      doctor: "npx @cohortapp/agent-sdk doctor",
+    },
+    dependencies: {
+      "@google/genai": "^1.42.0",
+      dotenv: "^16.4.5",
+      execa: "^9.6.1",
+      imapflow: "^1.2.18",
+      mailparser: "^3.9.6",
+      openai: "^6.33.0",
+    },
+    devDependencies: {
+      sharp: "^0.34.5",
+      tsx: "^4.20.6",
+    },
+  };
+
+  writeFileSync(
+    join(targetDir, "package.json"),
+    JSON.stringify(agentPackage, null, 2) + "\n"
+  );
+  ok("package.json");
+
+  // ── Step 5: Copy .env.example and .gitignore ────────────────────────────
+
+  for (const file of [".env.example", ".gitignore"]) {
+    const src = join(MAESTRO_ROOT, file);
+    if (existsSync(src)) {
+      cpSync(src, join(targetDir, file));
+      ok(file);
+    }
+  }
+
+  // ── Step 6: Initialize git ──────────────────────────────────────────────
+
+  log("Initializing git repository...");
+  try {
+    execFileSync("git", ["init"], { cwd: targetDir, stdio: "pipe" });
+    ok("git init");
+  } catch {
+    warn("git init failed — initialize manually");
+  }
+
+  // ── Step 7: Install dependencies ────────────────────────────────────────
+
+  log("Installing dependencies...");
+  try {
+    execFileSync("npm", ["install"], { cwd: targetDir, stdio: "pipe" });
+    ok("npm install");
+  } catch {
+    warn("npm install failed — run manually: cd " + targetDir + " && npm install");
+  }
+
+  // ── Done ────────────────────────────────────────────────────────────────
+
+  console.log();
+  console.log("╔══════════════════════════════════════════════════════════════╗");
+  console.log("║  Agent created successfully!                                ║");
+  console.log("╠══════════════════════════════════════════════════════════════╣");
+  console.log("║                                                              ║");
+  console.log("║  Next steps:                                                 ║");
+  console.log(`║  1. cd ${targetName.padEnd(51)}║`);
+  console.log('║  2. maestro setup                                            ║');
+  console.log("║                                                              ║");
+  console.log("║  The wizard handles everything: identity, company context,   ║");
+  console.log("║  model/provider, channels, the operating model, and          ║");
+  console.log("║  self-verification.                                          ║");
+  console.log("║                                                              ║");
+  console.log("╚══════════════════════════════════════════════════════════════╝");
+  console.log();
+}
+
+// ---------------------------------------------------------------------------
+// UPGRADE — update framework files in current agent repo (smart merge)
+// ---------------------------------------------------------------------------
+//
+// Upgrade philosophy: by default, never silently overwrite a file the user has
+// modified locally. Detection uses git as the source of truth:
+//
+//   • untracked or has-uncommitted-changes in agent repo ⇒ "locally modified"
+//   • tracked and clean against HEAD ⇒ "vendored, safe to overwrite"
+//
+// For every framework file we'd otherwise overwrite, we classify into:
+//
+//   added     — file doesn't exist in agent repo → copy
+//   updated   — file exists, agent's copy matches HEAD (no local edits) → overwrite
+//   same      — file exists, content already byte-identical to upstream → skip
+//   preserved — file exists with local edits → keep agent's copy, write the
+//               upstream version to .maestro/incoming/<path> for manual review
+//               (unless --force-overwrite is passed)
+//
+// Flags:
+//   --dry-run            preview only; no files written
+//   --force-overwrite    overwrite even locally-modified files (with backup)
+//   --no-incoming        skip writing .maestro/incoming/ shadows
+//   --verbose            list every file's classification
+
+// Paths that get upgraded. Each entry is { path, mode } where mode is:
+//   "smart"  — per-file classification described above
+//   "merge"  — add new files only; never overwrite existing (used for agents/)
+const UPGRADE_PATHS = [
+  { path: "scripts", mode: "smart" },
+  { path: "policies", mode: "smart" },
+  { path: "docs", mode: "smart" },
+  { path: "public/assets", mode: "smart" },
+  { path: "workflows", mode: "smart" },
+  { path: "schedules", mode: "smart" },
+  { path: "desktop-control", mode: "smart" },
+  { path: "ingest", mode: "smart" },
+  { path: "mcp", mode: "smart" },
+  { path: ".claude/commands", mode: "smart" },
+  { path: "plugins/maestro-skills", mode: "smart" },
+  { path: "teams", mode: "smart" },
+  { path: "agents", mode: "merge" },
+  // Framework primitives — colocated with scripts/ so relative imports
+  // (e.g. ../../lib/cadence-bus.mjs from scripts/cadence/*) resolve in
+  // every agent repo without needing @cohortapp/agent-sdk in node_modules.
+  { path: "lib", mode: "smart" },
+];
+
+function sha256File(p) {
+  return createHash("sha256").update(readFileSync(p)).digest("hex");
+}
+
+function walkFiles(root) {
+  const out = [];
+  if (!existsSync(root)) return out;
+  const stack = [root];
+  while (stack.length) {
+    const dir = stack.pop();
+    for (const name of readdirSync(dir)) {
+      const full = join(dir, name);
+      // Use lstat first so we can detect (and skip) symlinks — particularly
+      // broken ones, which are common in shared scaffolds.
+      let lst;
+      try { lst = lstatSync(full); }
+      catch { continue; }
+      if (lst.isSymbolicLink()) {
+        // Skip symlinks entirely — agents shouldn't inherit links into paths
+        // that may not exist on the target machine.
+        continue;
+      }
+      if (lst.isDirectory()) stack.push(full);
+      else if (lst.isFile()) out.push(full);
+    }
+  }
+  return out;
+}
+
+// .maestroignore — gitignore-style allowlist of paths the upgrade must NOT
+// touch. Supports comments (#), directory prefixes (trailing /), exact paths,
+// simple globs (* matches a single path segment, ** matches recursively), and
+// negation (! prefix to un-ignore). Match order is top-to-bottom; last match
+// wins, like .gitignore.
+function loadMaestroignore(cwd) {
+  const file = join(cwd, ".maestroignore");
+  if (!existsSync(file)) return null;
+  const patterns = [];
+  for (const raw of readFileSync(file, "utf-8").split(/\r?\n/)) {
+    const stripped = raw.replace(/^\s+|\s+$/g, "");
+    if (!stripped || stripped.startsWith("#")) continue;
+    const negate = stripped.startsWith("!");
+    const pat = negate ? stripped.slice(1).trim() : stripped;
+    if (!pat) continue;
+    patterns.push({ pat, negate });
+  }
+  return patterns.length ? patterns : null;
+}
+
+function patternToRegex(pat) {
+  // Helper: convert a glob-aware pattern to its regex source.
+  // ** must be substituted before single * so we don't double-rewrite it.
+  // * is intentionally outside the regex-escape char class so the
+  // glob substitution can find unescaped `*` characters afterward.
+  const globToRe = (p) =>
+    p.replace(/[.+^${}()|[\]\\]/g, "\\$&")
+      .replace(/\*\*/g, "<DBL>")
+      .replace(/\*/g, "[^/]*")
+      .replace(/<DBL>/g, ".*");
+
+  // Directory prefix: `scripts/daemon/` or `agents/role-*/` match
+  // anything under that path (recursive).
+  if (pat.endsWith("/")) {
+    return new RegExp("^" + globToRe(pat));
+  }
+  // Single-line glob: must match in full (no trailing slash).
+  if (pat.includes("*")) {
+    return new RegExp("^" + globToRe(pat) + "$");
+  }
+  // Exact: also matches anything underneath (gitignore semantics — a
+  // pattern without trailing slash still protects a directory if it
+  // resolves to one).
+  const escaped = pat.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  return new RegExp("^" + escaped + "(/|$)");
+}
+
+function matchesIgnore(repoRel, patterns) {
+  if (!patterns) return false;
+  let ignored = false;
+  for (const { pat, negate } of patterns) {
+    if (patternToRegex(pat).test(repoRel)) {
+      ignored = !negate;
+    }
+  }
+  return ignored;
+}
+
+function isGitRepo(cwd) {
+  try {
+    execFileSync("git", ["rev-parse", "--is-inside-work-tree"], { cwd, stdio: "pipe" });
+    return true;
+  } catch { return false; }
+}
+
+// Build a Set of repo-relative paths that are dirty (modified, added, untracked).
+// Single git invocation is much faster than per-file checks.
+function dirtyPathSet(cwd) {
+  const set = new Set();
+  try {
+    const out = execFileSync(
+      "git",
+      ["status", "--porcelain=v1", "-z", "--untracked-files=all"],
+      { cwd, encoding: "utf-8" }
+    );
+    // -z separates records with NUL; each record is "XY path" (no quoting).
+    // For renames (R/C) the format is "R  newpath\0oldpath\0" — we only care
+    // about destination, but for safety we treat both as dirty.
+    for (const rec of out.split("\0")) {
+      if (!rec) continue;
+      const status = rec.slice(0, 2);
+      const path = rec.slice(3);
+      // Anything in porcelain output is non-clean by definition.
+      if (status !== "  ") set.add(path);
+    }
+  } catch {
+    // Not a git repo or git failed — caller will fall back to caution mode.
+  }
+  return set;
+}
+
+// ---------------------------------------------------------------------------
+// Cadence-bus migration (called from upgrade)
+// ---------------------------------------------------------------------------
+//
+// As of maestro 1.8 scheduled cadence ticks no longer spawn a fresh Claude
+// Code session per tick. launchd plists now invoke a lightweight Node
+// enqueue script that drops a JSON event onto state/cadence-bus/; the
+// persistent maestro-daemon.mjs consumes the bus.
+//
+// This migration runs idempotently on every upgrade:
+//   1. Detect generated plists at scripts/local-triggers/plists/ that still
+//      reference run-trigger.sh (the legacy per-tick spawn path).
+//   2. Back them up to .maestro/backup/plists/<utc-timestamp>/.
+//   3. Regenerate plists via scripts/local-triggers/generate-plists.sh so
+//      the on-disk files match the cadence-bus architecture.
+//   4. Surface installed plists at ~/Library/LaunchAgents/ that still match
+//      the legacy pattern, with exact launchctl unload/load commands the
+//      operator can run.
+//
+// Returns a summary object the caller uses to print user-visible output.
+
+function plistRefersToLegacy(path) {
+  try {
+    const body = readFileSync(path, "utf-8");
+    return body.includes(LEGACY_PLIST_INDICATOR);
+  } catch {
+    return false;
+  }
+}
+
+function plistMatchesArch(path) {
+  try {
+    const body = readFileSync(path, "utf-8");
+    return body.includes(PLIST_ARCH_MARKER);
+  } catch {
+    return false;
+  }
+}
+
+function listPlists(dir) {
+  if (!existsSync(dir)) return [];
+  try {
+    return readdirSync(dir).filter((n) => n.endsWith(".plist")).map((n) => join(dir, n));
+  } catch {
+    return [];
+  }
+}
+
+function migrateCadenceBus(cwd, flags) {
+  const summary = {
+    generated_legacy: [],
+    generated_modern: [],
+    installed_legacy: [],
+    backed_up: [],
+    regenerated: false,
+    skipped_regen_reason: null,
+    bus_dir: null,
+    notes: [],
+  };
+
+  // Bootstrap the cadence-bus directory tree even when nothing else is
+  // moving — needed for fresh installs that upgrade through this path.
+  const busBase = join(cwd, "state", "cadence-bus");
+  summary.bus_dir = busBase;
+  for (const d of ["inbox", "claimed", "processed", "failed", "dlq"]) {
+    const full = join(busBase, d);
+    if (!existsSync(full) && !flags.dryRun) {
+      mkdirSync(full, { recursive: true });
+    }
+  }
+  const versionFile = join(busBase, "VERSION");
+  if (!existsSync(versionFile) && !flags.dryRun) {
+    writeFileSync(versionFile, "1\n");
+  }
+
+  // Inspect generated plists.
+  const generatedDir = join(cwd, "scripts/local-triggers/plists");
+  const generated = listPlists(generatedDir);
+  for (const p of generated) {
+    const rel = relative(cwd, p);
+    if (plistRefersToLegacy(p)) summary.generated_legacy.push(rel);
+    else if (plistMatchesArch(p)) summary.generated_modern.push(rel);
+  }
+
+  // Inspect installed plists.
+  const installedDir = join(process.env.HOME || "/", "Library/LaunchAgents");
+  for (const p of listPlists(installedDir)) {
+    const name = basename(p);
+    // Only consider plists owned by Maestro — labels start with ai.maestro.
+    // (or legacy ai.adaptic. for agents installed before the rename).
+    if (!name.startsWith("ai.maestro.") && !name.startsWith("ai.adaptic.")) continue;
+    if (plistRefersToLegacy(p)) summary.installed_legacy.push(p);
+  }
+
+  // Back up any legacy generated plists.
+  if (summary.generated_legacy.length > 0) {
+    const ts = new Date().toISOString().replace(/[:.]/g, "-");
+    const backupDir = join(cwd, ".maestro/backup/plists", ts);
+    if (!flags.dryRun) {
+      mkdirSync(backupDir, { recursive: true });
+      for (const rel of summary.generated_legacy) {
+        const src = join(cwd, rel);
+        const dst = join(backupDir, basename(src));
+        try {
+          copyFileSync(src, dst);
+          summary.backed_up.push(relative(cwd, dst));
+        } catch (err) {
+          summary.notes.push(`backup failed for ${rel}: ${err.message}`);
+        }
+      }
+    } else {
+      // Dry-run: still report what would be backed up.
+      summary.notes.push(`would back up ${summary.generated_legacy.length} legacy plist(s) to .maestro/backup/plists/${ts}/`);
+    }
+
+    // Regenerate via the bundled script. Soft failure — operator can rerun.
+    const generator = join(cwd, "scripts/local-triggers/generate-plists.sh");
+    if (existsSync(generator)) {
+      if (!flags.dryRun) {
+        try {
+          execFileSync("/bin/bash", [generator], { cwd, stdio: "pipe" });
+          summary.regenerated = true;
+        } catch (err) {
+          summary.skipped_regen_reason = `generate-plists.sh failed: ${err.message.split("\n")[0]}`;
+        }
+      } else {
+        summary.notes.push("dry-run: would regenerate plists via scripts/local-triggers/generate-plists.sh");
+      }
+    } else {
+      summary.skipped_regen_reason = "scripts/local-triggers/generate-plists.sh missing";
+    }
+  }
+
+  return summary;
+}
+
+function printCadenceBusSummary(summary, flags) {
+  console.log();
+  console.log(`${C.bold}Cadence bus migration${C.reset}${flags.dryRun ? " (dry run)" : ""}`);
+  if (summary.generated_legacy.length === 0 && summary.installed_legacy.length === 0) {
+    ok("Already on cadence-bus architecture (no legacy plists found).");
+    if (summary.generated_modern.length > 0) {
+      ok(`${summary.generated_modern.length} generated plist(s) carry the cadence-bus marker.`);
+    }
+    return;
+  }
+  if (summary.generated_legacy.length > 0) {
+    warn(`${summary.generated_legacy.length} generated plist(s) still call run-trigger.sh directly:`);
+    for (const p of summary.generated_legacy.slice(0, 8)) console.log(`    ${p}`);
+    if (summary.generated_legacy.length > 8) {
+      console.log(`    … and ${summary.generated_legacy.length - 8} more`);
+    }
+  }
+  if (summary.backed_up.length > 0) {
+    ok(`Backed up ${summary.backed_up.length} legacy plist(s) under ${dirname(summary.backed_up[0])}`);
+  }
+  if (summary.regenerated) {
+    ok("Regenerated plists with the cadence-bus architecture.");
+  } else if (summary.skipped_regen_reason) {
+    warn(`Skipped plist regeneration: ${summary.skipped_regen_reason}`);
+    warn("Run manually: ./scripts/local-triggers/generate-plists.sh");
+  }
+
+  if (summary.installed_legacy.length > 0) {
+    console.log();
+    warn(`${summary.installed_legacy.length} installed launchd plist(s) at ~/Library/LaunchAgents/ still use the legacy spawn-per-tick pattern.`);
+    warn("Reload them so launchctl picks up the cadence-bus versions:");
+    for (const p of summary.installed_legacy.slice(0, 8)) {
+      const label = basename(p, ".plist");
+      console.log(`    launchctl unload "${p}" && launchctl load "${p}"`);
+      // Cosmetic alias for label clarity.
+      void label;
+    }
+    if (summary.installed_legacy.length > 8) {
+      console.log(`    … and ${summary.installed_legacy.length - 8} more`);
+    }
+  }
+
+  for (const note of summary.notes) console.log(`    note: ${note}`);
+}
+
+function parseUpgradeFlags(args) {
+  const flags = {
+    dryRun: false,
+    forceOverwrite: false,
+    noIncoming: false,
+    verbose: 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 === "--verbose" || a === "-v") flags.verbose = true;
+    else if (a === "--help" || a === "-h") return null;
+    else { fail(`Unknown flag: ${a}`); process.exit(1); }
+  }
+  return flags;
+}
+
+async function upgrade(args = []) {
+  const flags = parseUpgradeFlags(args);
+  if (flags === null) {
+    console.log(`
+Usage: maestro upgrade [flags]
+
+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
+  --verbose, -v          Print classification for every file
+  --help, -h             Show this help
+
+Per-file behaviour:
+  added     — new upstream file → copy
+  updated   — existed, byte-equal to your committed copy → safe overwrite
+  same      — existed and already byte-identical to upstream → skip
+  ignored   — matches a pattern in .maestroignore → never touched (any state)
+  preserved — has uncommitted local edits → keep yours, upstream lands at
+              .maestro/incoming/<path> for manual diff
+  mergeKept — under agents/ → never overwrite (custom agents preserved)
+  forced    — overwritten by --force-overwrite; backup at .maestro/backup/<path>
+
+.maestroignore format (gitignore-style, top-down, last match wins):
+  scripts/slack-send.sh          exact file
+  scripts/daemon/                directory and everything beneath
+  scripts/send-email-*.py        single-segment glob
+  workflows/**                   recursive glob
+  !workflows/quarterly/          un-ignore (force overwrite)
+`);
+    return;
+  }
+
+  const cwd = process.cwd();
+
+  // config/agent.json is the single source of truth (config/agent.ts is the
+  // derived wrapper). Accept either as the agent-repo signal — but agent.json is
+  // primary; a CLAUDE.md alone (framework checkout) still qualifies for upgrade.
+  if (!existsSync(join(cwd, "config/agent.json")) && !existsSync(join(cwd, "config/agent.ts")) && !existsSync(join(cwd, "CLAUDE.md"))) {
+    fail("Not a Maestro agent directory (config/agent.json not found)");
+    process.exit(1);
+  }
+
+  const inGit = isGitRepo(cwd);
+  if (!inGit) {
+    warn("Not in a git repo — cannot detect local modifications.");
+    warn("All existing files will be treated as locally modified and preserved.");
+    warn("Use --force-overwrite to override.");
+  }
+
+  const dirty = inGit ? dirtyPathSet(cwd) : null;
+  const ignorePatterns = loadMaestroignore(cwd);
+  if (ignorePatterns) {
+    log(`.maestroignore loaded (${ignorePatterns.length} pattern${ignorePatterns.length === 1 ? "" : "s"})`);
+  }
+
+  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 preservedFiles = [];
+  const ignoredFiles = [];
+
+  for (const { path: relRoot, mode } of UPGRADE_PATHS) {
+    const srcRoot = join(MAESTRO_ROOT, relRoot);
+    const dstRoot = join(cwd, relRoot);
+    if (!existsSync(srcRoot)) continue;
+
+    const srcFiles = walkFiles(srcRoot);
+    for (const srcFile of srcFiles) {
+      const relFromRoot = relative(srcRoot, srcFile);
+      const dstFile = join(dstRoot, relFromRoot);
+      const repoRel = relative(cwd, dstFile).split(sep).join("/");
+
+      const isIgnored = matchesIgnore(repoRel, ignorePatterns);
+
+      // Case 0: .maestroignore match — never touch, regardless of state.
+      // Checked BEFORE existsSync so that protected new-files-from-upstream
+      // are never silently introduced into the agent repo either.
+      if (isIgnored) {
+        counts.ignored++;
+        ignoredFiles.push(repoRel);
+        if (flags.verbose) console.log(`  · ${repoRel} (ignored via .maestroignore)`);
+        continue;
+      }
+
+      // Case 1: new file (doesn't exist in agent) — always copy.
+      if (!existsSync(dstFile)) {
+        if (!flags.dryRun) {
+          mkdirSync(dirname(dstFile), { recursive: true });
+          copyFileSync(srcFile, dstFile);
+        }
+        counts.added++;
+        if (flags.verbose) ok(`+ ${repoRel}`);
+        continue;
+      }
+
+      // Case 2: byte-identical — nothing to do.
+      const srcHash = sha256File(srcFile);
+      const dstHash = sha256File(dstFile);
+      if (srcHash === dstHash) {
+        counts.same++;
+        if (flags.verbose) console.log(`  = ${repoRel}`);
+        continue;
+      }
+
+      // Case 3: merge-mode never overwrites existing files.
+      if (mode === "merge") {
+        counts.mergeKept++;
+        if (flags.verbose) console.log(`  ~ ${repoRel} (merge-mode, kept)`);
+        continue;
+      }
+
+      // Case 4: locally modified? Determine via git dirty set.
+      const locallyModified = inGit ? dirty.has(repoRel) : true;
+
+      if (locallyModified && !flags.forceOverwrite) {
+        counts.preserved++;
+        preservedFiles.push(repoRel);
+        if (!flags.dryRun && !flags.noIncoming) {
+          const shadow = join(cwd, ".maestro", "incoming", repoRel);
+          mkdirSync(dirname(shadow), { recursive: true });
+          copyFileSync(srcFile, shadow);
+        }
+        if (flags.verbose) console.log(`  ~ ${repoRel} (local edits, preserved)`);
+        continue;
+      }
+
+      // Case 5: overwrite (clean tracked file, or --force).
+      if (locallyModified && flags.forceOverwrite) {
+        // Back up the about-to-be-clobbered file.
+        if (!flags.dryRun) {
+          const backup = join(cwd, ".maestro", "backup", repoRel);
+          mkdirSync(dirname(backup), { recursive: true });
+          copyFileSync(dstFile, backup);
+        }
+        counts.forced++;
+        if (flags.verbose) warn(`! ${repoRel} (forced; backup written)`);
+      } else {
+        counts.updated++;
+        if (flags.verbose) console.log(`  > ${repoRel}`);
+      }
+      if (!flags.dryRun) {
+        mkdirSync(dirname(dstFile), { recursive: true });
+        copyFileSync(srcFile, dstFile);
+      }
+    }
+  }
+
+  // Ensure standard runtime directories exist.
+  const ensureDirs = [
+    "state/handoffs", "state/huddle", "state/indexes", "state/rag",
+    "state/sessions", "state/slack-responded", "state/slack-thread-tracker",
+    "state/tmp", "state/inbox/whatsapp", "state/inbox/attachments",
+    "state/inbox/processed", "memory/precedents/market-signals",
+    "knowledge/decisions/archive", "self-optimization/scenarios", "tests",
+    "logs/infra", "logs/monitor", "logs/phone", "logs/sms",
+    "logs/whatsapp", "logs/email",
+    // Cadence bus (architecture introduced in maestro 1.8). Idempotent.
+    "state/cadence-bus", "state/cadence-bus/inbox", "state/cadence-bus/claimed",
+    "state/cadence-bus/processed", "state/cadence-bus/failed", "state/cadence-bus/dlq",
+    "logs/cadence-bus",
+    // Org/secrets/diagnostics/scheduling/hook spine (maestro 1.18+). Runtime
+    // dirs for lib/{secrets,diagnostics,scheduling,hooks,org}; all fail-open if
+    // absent, but pre-creating them avoids first-write races. Idempotent.
+    "state/secrets", "state/scheduling", "state/scheduling/jobs",
+    "logs/diagnostics", "logs/diagnostics/counters", "logs/traces",
+    "logs/events", "logs/audit/hooks",
+  ];
+  let newDirs = 0;
+  for (const dir of ensureDirs) {
+    const dirPath = join(cwd, dir);
+    if (!existsSync(dirPath)) {
+      if (!flags.dryRun) mkdirSync(dirPath, { recursive: true });
+      newDirs++;
+    }
+  }
+
+  // ── Scaffold config templates (add-only) ────────────────────────────────
+  // scaffold/config/* are disabled-by-default templates a new agent gets at
+  // `create` time (cpSync flattens scaffold/ over the repo root). UPGRADE_PATHS
+  // deliberately does NOT include config/ (it is operator-owned, never smart-
+  // merged), so existing agents would otherwise never receive NEW config
+  // templates introduced by a framework rev — e.g. org.yaml / secrets.yaml /
+  // alerts.yaml shipped with the org/secrets/diagnostics systems. Copy any
+  // scaffold/config file that the agent does NOT already have. We NEVER
+  // overwrite an existing config (operator-owned, may be customised or enabled);
+  // .maestroignore and --dry-run are honoured. The `.example` companions land
+  // too so the agent has the documented full form alongside the live default.
+  const scaffoldConfigDir = join(SCAFFOLD_DIR, "config");
+  let newConfigs = 0;
+  if (existsSync(scaffoldConfigDir)) {
+    for (const name of readdirSync(scaffoldConfigDir)) {
+      const src = join(scaffoldConfigDir, name);
+      let st;
+      try { st = lstatSync(src); } catch { continue; }
+      if (!st.isFile()) continue; // configs are flat files
+      const dst = join(cwd, "config", name);
+      const repoRel = relative(cwd, dst).split(sep).join("/");
+      if (matchesIgnore(repoRel, ignorePatterns)) {
+        counts.ignored++;
+        ignoredFiles.push(repoRel);
+        if (flags.verbose) console.log(`  · ${repoRel} (ignored via .maestroignore)`);
+        continue;
+      }
+      if (existsSync(dst)) {
+        // Operator owns config/ — never clobber an existing template.
+        if (flags.verbose) console.log(`  ~ ${repoRel} (config exists, kept)`);
+        continue;
+      }
+      if (!flags.dryRun) {
+        mkdirSync(dirname(dst), { recursive: true });
+        copyFileSync(src, dst);
+      }
+      counts.added++;
+      newConfigs++;
+      if (flags.verbose) ok(`+ ${repoRel}`);
+    }
+  }
+
+  // ── SoT self-heal: kill the agent.ts/agent.json split-brain ─────────────
+  // The single source of truth is config/agent.json with config/agent.ts as a
+  // thin re-export wrapper. Legacy repos carry a standalone literal agent.ts
+  // (and may lack agent.json). Auto-migrate so they self-heal on upgrade.
+  if (!flags.dryRun) {
+    try {
+      const tsPath = join(cwd, "config/agent.ts");
+      const jsonPath = join(cwd, "config/agent.json");
+      const tsSrc = existsSync(tsPath) ? readFileSync(tsPath, "utf-8") : "";
+      const tsIsWrapper = /import\s+\w+\s+from\s+['"]\.\/agent\.json['"]/.test(tsSrc);
+      const tsIsStandalone = existsSync(tsPath) && /export\s+const\s+agent\s*(?::[^=]+)?=\s*\{/.test(tsSrc) && !tsIsWrapper;
+
+      if (!existsSync(jsonPath) && tsIsStandalone) {
+        // No SoT yet — run the full migration (extracts agent.json + writes wrapper).
+        try {
+          execFileSync("node", [join(MAESTRO_ROOT, "scripts/setup/migrate-agent-to-sot.mjs")], {
+            cwd, env: { ...process.env, AGENT_DIR: cwd, AGENT_ROOT: cwd, MAESTRO_ROOT }, stdio: "pipe",
+          });
+          ok("migrated config/agent.ts → config/agent.json + thin wrapper (SoT self-heal)");
+        } catch (e) {
+          warn(`SoT migration could not run automatically: ${e && e.message ? e.message : e}`);
+          warn("  Run manually: npx tsx scripts/setup/migrate-agent-to-sot.mjs");
+        }
+      } else if (existsSync(jsonPath) && tsIsStandalone) {
+        // SoT exists but the .ts is still a standalone literal — just re-wrap it.
+        const { ensureSotWrapper } = await import(join(MAESTRO_ROOT, "lib", "setup", "sot.mjs"));
+        const r = ensureSotWrapper(cwd);
+        if (r.wrote) ok("rewrote config/agent.ts as the SoT wrapper (re-exports agent.json)");
+      }
+    } catch (e) {
+      warn(`SoT self-heal skipped: ${e && e.message ? e.message : e}`);
+    }
+  }
+
+  // Cadence-bus migration: detect legacy spawn-per-tick plists and rewrite
+  // them so launchd enqueues cadence events instead of spawning Claude.
+  const cadenceMigration = migrateCadenceBus(cwd, flags);
+
+  // Regenerate derived config from config/agent.json (the SOT).
+  // Soft failures — older agents that haven't migrated to the SOT layout
+  // yet don't have agent.json and that's fine.
+  if (!flags.dryRun && existsSync(join(cwd, "config", "agent.json"))) {
+    // config/agent.env — env-var file consumed by shell scripts.
+    try {
+      execFileSync(
+        "node",
+        [join(MAESTRO_ROOT, "scripts/setup/generate-agent-env.mjs")],
+        { cwd, env: { ...process.env, AGENT_DIR: cwd }, stdio: "pipe" }
+      );
+      ok("regenerated config/agent.env");
+    } catch (e) {
+      warn(`could not regenerate config/agent.env: ${e.message}`);
+    }
+    // config/environment.yaml — operational config consumed by workflows.
+    // Replaces the previously-static hardcoded identity fields.
+    try {
+      execFileSync(
+        "node",
+        [join(MAESTRO_ROOT, "scripts/setup/render-environment-yaml.mjs")],
+        { cwd, env: { ...process.env, AGENT_DIR: cwd }, stdio: "pipe" }
+      );
+      ok("regenerated config/environment.yaml");
+    } catch (e) {
+      warn(`could not regenerate config/environment.yaml: ${e.message}`);
+    }
+  }
+
+  // Summary
+  console.log();
+  console.log(`${C.bold}Upgrade summary${C.reset}${flags.dryRun ? " (dry run, nothing written)" : ""}`);
+  if (counts.added)     ok(`${counts.added} added (new files)`);
+  if (counts.updated)   ok(`${counts.updated} updated (vendored, no local edits)`);
+  if (counts.same)      console.log(`  = ${counts.same} already up-to-date`);
+  if (counts.ignored)   console.log(`  · ${counts.ignored} ignored (.maestroignore protected)`);
+  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 (newDirs)          ok(`${newDirs} new directories created`);
+
+  if (preservedFiles.length && !flags.noIncoming && !flags.dryRun) {
+    console.log();
+    log("Upstream versions of your locally-modified files saved to .maestro/incoming/");
+    log("Review with:  diff <path> .maestro/incoming/<path>");
+    for (const p of preservedFiles.slice(0, 5)) console.log(`    ${p}`);
+    if (preservedFiles.length > 5) console.log(`    … and ${preservedFiles.length - 5} more`);
+  }
+
+  // Surface the cadence-bus migration summary AFTER the file-by-file
+  // upgrade summary so the operator sees both layers of change.
+  printCadenceBusSummary(cadenceMigration, flags);
+
+  // Reconcile framework features — run auto-init steps, queue manual ones.
+  if (!flags.dryRun && existsSync(FRAMEWORK_FEATURES_PATH)) {
+    try {
+      const { loadRegistry, reconcileFeatures } = await import("../lib/feature-init.mjs");
+      const registry = loadRegistry(FRAMEWORK_FEATURES_PATH);
+      console.log();
+      log("Reconciling framework features...");
+      const result = reconcileFeatures({
+        maestroRoot: MAESTRO_ROOT,
+        agentRoot: cwd,
+        registry,
+        runAuto: true,
+        logger: (entry) => {
+          if (entry.stage === "completed") ok(`init: ${entry.feature}`);
+          else if (entry.stage === "failed") warn(`init failed: ${entry.feature} — ${entry.message}`);
+          else if (entry.stage === "pending") console.log(`  ~ pending: ${entry.feature} (run \`maestro init ${entry.feature} --apply\`)`);
+        },
+      });
+      if (result.pending.length) {
+        warn(`${result.pending.length} feature(s) still pending — run: maestro init`);
+      } else if (result.ranAuto.length) {
+        ok(`${result.ranAuto.length} feature(s) initialised this run`);
+      } else {
+        ok("All framework features up to date");
+      }
+    } catch (e) {
+      warn(`feature reconciliation skipped: ${e.message}`);
+    }
+  }
+
+  console.log();
+  log("Agent-specific paths (config/, CLAUDE.md, knowledge/, memory/, state/, outputs/, logs/, .env) were NOT touched.");
+}
+
+// ---------------------------------------------------------------------------
+// DOCTOR — cost-telemetry tripwire (pure predicate, unit-tested)
+// ---------------------------------------------------------------------------
+//
+// Observability audit F2: the daily-budget governor sums estimated_usd across
+// today's cost ledger rows. If callers spawn sessions but record $0 (the
+// historic --input-tokens 0 --output-tokens 0 bug), the ledger fills with rows
+// whose estimated_usd is 0, the spend band is permanently 0%, and the budget
+// cap silently can never trip. Doctor surfaces that "blind" state in RED.
+//
+// The ledger lives at <agentRoot>/state/cost-tracking/<UTC-YYYY-MM-DD>.jsonl
+// and is written by scripts/cost/track-claude-usage.mjs (record subcommand).
+// Each row carries estimated_usd (the tracker computes it from token counts).
+//
+// evaluateCostTripwire is a pure function so the red/green decision is testable
+// in isolation from disk + the doctor's side-effecting ok/warn/fail output.
+
+/**
+ * Sum estimated_usd and count rows from already-parsed ledger rows.
+ * Tolerant of missing/NaN estimated_usd (treated as 0) and ignores non-objects.
+ * @param {Array<object>} rows
+ * @returns {{ rowCount: number, totalUsd: number }}
+ */
+function summariseLedgerRows(rows) {
+  let rowCount = 0;
+  let totalUsd = 0;
+  for (const row of rows || []) {
+    if (!row || typeof row !== "object") continue;
+    rowCount++;
+    const usd = Number(row.estimated_usd);
+    if (Number.isFinite(usd)) totalUsd += usd;
+  }
+  return { rowCount, totalUsd: +totalUsd.toFixed(6) };
+}
+
+/**
+ * Decide the cost-telemetry posture from today's ledger rows and a count of
+ * sessions known to have run today (rows themselves OR a daemon heartbeat that
+ * proves activity). The contract the spec pins down:
+ *
+ *   RED   — sessions ran today (rows exist OR heartbeat active) but summed
+ *           estimated_usd === 0 → "spend telemetry is blind".
+ *   GREEN — no sessions ran (nothing to measure) OR spend > 0.
+ *
+ * @param {{ rows?: Array<object>, sessionCount?: number }} input
+ *   rows         — parsed ledger rows for today (may be empty)
+ *   sessionCount — sessions evidenced today from outside the ledger (e.g. a
+ *                  fresh daemon heartbeat). Activity = (rows.length>0) || (sessionCount>0).
+ * @returns {{ red: boolean, status: "red"|"green", reason: string, rowCount: number, totalUsd: number, sessionCount: number }}
+ */
+function evaluateCostTripwire({ rows = [], sessionCount = 0 } = {}) {
+  const { rowCount, totalUsd } = summariseLedgerRows(rows);
+  const sessions = Math.max(0, Number(sessionCount) || 0);
+  const hadActivity = rowCount > 0 || sessions > 0;
+
+  if (!hadActivity) {
+    return {
+      red: false,
+      status: "green",
+      reason: "no sessions ran today — nothing to measure",
+      rowCount,
+      totalUsd,
+      sessionCount: sessions,
+    };
+  }
+  if (totalUsd > 0) {
+    return {
+      red: false,
+      status: "green",
+      reason: `spend telemetry live ($${totalUsd} across ${rowCount} ledger row(s))`,
+      rowCount,
+      totalUsd,
+      sessionCount: sessions,
+    };
+  }
+  return {
+    red: true,
+    status: "red",
+    reason: `spend telemetry is blind — ${hadActivity ? "sessions ran today" : ""} but ledger sums $0 (${rowCount} row(s)${sessions ? `, heartbeat-active` : ""}). Callers are recording 0 tokens; budget governor can never trip on spend.`,
+    rowCount,
+    totalUsd,
+    sessionCount: sessions,
+  };
+}
+
+/**
+ * Staleness ladder for the router's data files (pricing cache & catalog cost
+ * provenance, and the policy overlay): a freshly-fetched figure is GREEN; a
+ * `fetched`/`issued_at` date older than 7 days is WARN; older than 30 days is
+ * FAIL. Volatile-priced rows whose provenance is stale are the dangerous case
+ * (a promo expiry silently busting a budget), so a stale catalog with any
+ * volatile row escalates straight to FAIL at 30 d. Pure + testable; the doctor
+ * maps the verdict onto ok/warn/fail.
+ *
+ * @param {{ fetched?: string|null, now?: number, hasVolatile?: boolean, label?: string }} input
+ *   fetched     — ISO date (YYYY-MM-DD or full ISO) the data was last refreshed
+ *   now         — epoch ms (injectable for tests; default Date.now)
+ *   hasVolatile — true if any priced row is volatile (escalates the FAIL case)
+ * @returns {{ status: "green"|"warn"|"fail", ageDays: number|null, reason: string }}
+ */
+function evaluateStaleness({ fetched, now = Date.now(), hasVolatile = false, label = "data" } = {}) {
+  if (!fetched) {
+    return { status: "warn", ageDays: null, reason: `${label} has no fetch date — provenance unknown` };
+  }
+  const t = new Date(fetched).getTime();
+  if (!Number.isFinite(t)) {
+    return { status: "warn", ageDays: null, reason: `${label} fetch date "${fetched}" is unparseable` };
+  }
+  const ageDays = Math.floor((now - t) / 86_400_000);
+  if (ageDays >= 30) {
+    return {
+      status: "fail",
+      ageDays,
+      reason: `${label} is ${ageDays}d old (>30d)${hasVolatile ? " and prices volatile — a promo expiry may be silently busting the budget" : ""}`,
+    };
+  }
+  if (ageDays >= 7) {
+    return { status: "warn", ageDays, reason: `${label} is ${ageDays}d old (>7d) — refresh the pricing cache` };
+  }
+  return { status: "green", ageDays, reason: `${label} fresh (${ageDays}d old)` };
+}
+
+// ---------------------------------------------------------------------------
+// ROUTER — `maestro router why <item>` / `maestro router validate`
+// ---------------------------------------------------------------------------
+
+const ROUTER_HELP = `
+${C.bold}maestro router${C.reset} — inspect the v2 model router.
+
+Usage:
+  maestro router why <request-json|task_class>   Resolve a RouteRequest and print
+                                                 the decision: chain, chosen,
+                                                 explain, tried[], audit.
+  maestro router validate                         Strict-validate config/model-routing.yaml
+                                                 against the catalog (+ overlay).
+
+Examples:
+  maestro router why '{"task_class":"classify.inbox","data_class":"public"}'
+  maestro router why session.responder
+  maestro router validate
+`;
+
+/**
+ * Load the v2 routing config + bundled catalog for the current agent repo.
+ * Returns { config, catalog } or null with an explanation logged.
+ */
+async function loadRouterContext(cwd) {
+  const routerLib = join(MAESTRO_ROOT, "lib", "model-router.mjs");
+  const catalogLib = join(MAESTRO_ROOT, "lib", "model-router", "catalog.mjs");
+  if (!existsSync(routerLib) || !existsSync(catalogLib)) {
+    fail("model-router library not reachable — run `npm run upgrade` in this agent");
+    return null;
+  }
+  const { loadRoutingConfig } = await import(`file://${routerLib}`);
+  const { loadCatalog } = await import(`file://${catalogLib}`);
+  let config = null;
+  try {
+    config = loadRoutingConfig(cwd);
+  } catch (err) {
+    fail(`config/model-routing.yaml failed to load: ${err.message}`);
+    return null;
+  }
+  const catalog = loadCatalog(cwd, {});
+  return { config, catalog, routerLib };
+}
+
+async function routerCmd(args = []) {
+  const sub = args[0];
+  if (!sub || sub === "--help" || sub === "-h") {
+    console.log(ROUTER_HELP);
+    return;
+  }
+  const cwd = process.cwd();
+  const ctx = await loadRouterContext(cwd);
+  if (!ctx) {
+    process.exitCode = 1;
+    return;
+  }
+  const { config, catalog, routerLib } = ctx;
+
+  if (sub === "validate") {
+    const { validateRoutingConfig } = await import(`file://${routerLib}`);
+    if (!config) {
+      warn("No config/model-routing.yaml present — router is inert (Anthropic-only).");
+      return;
+    }
+    if (config.schema_version !== 2) {
+      ok("config/model-routing.yaml is a v1 config (legacy resolver path; not v2-validated).");
+      return;
+    }
+    const { errors, warnings } = validateRoutingConfig(config, { catalog, env: process.env });
+    for (const w of warnings) warn(`${w.where}: ${w.warning}`);
+    for (const e of errors) fail(`${e.where}: ${e.error}`);
+    if (errors.length === 0) ok(`config/model-routing.yaml valid (${warnings.length} warning(s)).`);
+    process.exitCode = errors.length ? 1 : 0;
+    return;
+  }
+
+  if (sub === "why") {
+    const { resolveChain } = await import(`file://${routerLib}`);
+    const raw = args.slice(1).join(" ").trim();
+    if (!raw) {
+      fail('usage: maestro router why <request-json|task_class>');
+      process.exitCode = 1;
+      return;
+    }
+    let request;
+    if (raw.startsWith("{")) {
+      try {
+        request = JSON.parse(raw);
+      } catch (err) {
+        fail(`could not parse request JSON: ${err.message}`);
+        process.exitCode = 1;
+        return;
+      }
+    } else {
+      // Bare token → treat as a task_class.
+      request = { task_class: raw };
+    }
+    const decision = resolveChain(request, { agentRoot: cwd, config, catalog, env: process.env });
+    printRouteDecision(decision);
+    return;
+  }
+
+  fail(`Unknown router subcommand: ${sub}`);
+  console.log(ROUTER_HELP);
+  process.exitCode = 1;
+}
+
+/** Pretty-print a RouteDecision for `maestro router why`. */
+function printRouteDecision(d) {
+  if (!d) {
+    fail("resolveChain returned nothing");
+    return;
+  }
+  console.log();
+  console.log(`${C.bold}decision${C.reset}  ${d.decision_id}`);
+  if (d.chosen) {
+    console.log(`${C.bold}chosen${C.reset}    ${C.green}${d.chosen.provider}/${d.chosen.model}${C.reset}  harness=${d.chosen.harness} transport=${d.chosen.transport} wire=${d.chosen.wire}`);
+  } else {
+    console.log(`${C.bold}chosen${C.reset}    ${C.red}<no route>${C.reset}`);
+  }
+  console.log(`${C.bold}explain${C.reset}   ${d.explain}`);
+  console.log(`${C.bold}lane${C.reset}      ${d.lane}   cache_ttl=${d.cache_ttl}   estCostUSD=${d.estCostUSD}`);
+  console.log(`${C.bold}chain${C.reset}     ${(d.chain || []).map((c) => `${c.ref}(${c.harness}/${c.transport})`).join(" → ") || "(empty)"}`);
+  if (d.tried && d.tried.length) {
+    console.log(`${C.bold}tried${C.reset}`);
+    for (const t of d.tried) console.log(`            ${C.yellow}✗${C.reset} ${t.ref} — ${t.reason}`);
+  }
+  if (Object.keys(d.envForSpawn || {}).length) {
+    console.log(`${C.bold}envForSpawn${C.reset}`);
+    for (const [k, v] of Object.entries(d.envForSpawn)) {
+      const shown = /TOKEN|KEY/.test(k) && v ? "***" : v;
+      console.log(`            ${k}=${shown}`);
+    }
+  }
+  console.log(`${C.bold}spawnArgs${C.reset} model=${d.spawnArgs.modelFlag} maxTurns=${d.spawnArgs.maxTurns} bare=${d.spawnArgs.bare}`);
+  console.log(`${C.bold}audit${C.reset}     rule=${d.audit.rule} fallback=${d.audit.fallback_reason || "—"} config=${d.audit.config_source || "—"} overlay=${d.audit.overlay_version || "—"}`);
+  console.log();
+}
+
+// ---------------------------------------------------------------------------
+// DOCTOR — verify installation
+// ---------------------------------------------------------------------------
+
+async function doctor() {
+  const cwd = process.cwd();
+  console.log();
+  log("Running Maestro diagnostics...");
+  console.log();
+
+  let issues = 0;
+
+  // ── Framework files ─────────────────────────────────────────────────────
+  // config/agent.json is the single source of truth; config/agent.ts is the
+  // derived thin wrapper (checked separately below as a secondary signal).
+  const essentialFiles = [
+    "config/agent.json", "CLAUDE.md", ".claude/settings.json",
+    ".claude/commands/init-maestro.md", "package.json",
+    "scripts/setup/init-agent.sh", "scripts/healthcheck.sh",
+    "config/environment.yaml", "config/contacts.yaml",
+    "config/priorities.yaml", "config/sla-defaults.yaml",
+    "scripts/daemon/maestro-daemon.mjs",
+    "scripts/local-triggers/generate-plists.sh",
+    "state/dashboards/executive-summary.yaml",
+    "state/queues/action-stack.yaml",
+    "knowledge/decisions/decision-schema.yaml",
+    // Cadence-bus architecture (maestro 1.8+)
+    "lib/cadence-bus.mjs",
+    "scripts/cadence/enqueue-cadence-tick.mjs",
+    "scripts/cadence/launchd-cadence-wrapper.sh",
+    "scripts/cadence/cadence-status.mjs",
+    "scripts/daemon/cadence-consumer.mjs",
+    "scripts/daemon/cadence-handlers.mjs",
+  ];
+
+  for (const file of essentialFiles) {
+    if (existsSync(join(cwd, file))) ok(file);
+    else { fail(`Missing: ${file}`); issues++; }
+  }
+
+  // ── config/agent.ts is the derived SoT wrapper (secondary signal) ───────
+  // A standalone literal .ts (legacy split-brain) is a WARN, fixed by `upgrade`.
+  {
+    const tsPath = join(cwd, "config/agent.ts");
+    if (existsSync(tsPath) && existsSync(join(cwd, "config/agent.json"))) {
+      const src = readFileSync(tsPath, "utf-8");
+      if (/import\s+\w+\s+from\s+['"]\.\/agent\.json['"]/.test(src)) ok("config/agent.ts is the SoT wrapper (re-exports agent.json)");
+      else { warn("config/agent.ts is a standalone literal (legacy split-brain) — run: npx @cohortapp/agent-sdk upgrade"); issues++; }
+    }
+  }
+
+  // ── Archetype profile (function × altitude) ─────────────────────────────
+  // Resolve the agent's operating model from the framework archetype library.
+  // A freshly-created framework checkout has no config/agent.json; skip there.
+  try {
+    const agentJsonPath = join(cwd, "config/agent.json");
+    if (existsSync(agentJsonPath)) {
+      const cfg = JSON.parse(readFileSync(agentJsonPath, "utf-8"));
+      const sel = cfg.function && cfg.altitude
+        ? { function: cfg.function, altitude: cfg.altitude }
+        : migrateLegacyArchetype(cfg.archetype);
+      if (!sel) {
+        warn("config/agent.json has no { function, altitude } archetype — run maestro setup");
+        issues++;
+      } else {
+        const profile = await resolveArchetype(sel);
+        ok(`Archetype resolves: ${profile.label} (${profile.function} × ${profile.altitude})`);
+      }
+    }
+  } catch (err) {
+    fail(`Archetype profile invalid: ${err && err.message ? err.message : err}`);
+    issues++;
+  }
+
+  // ── Operating model: completeness gate (shared with `maestro setup`) ─────
+  // The single source of truth for "fully set up" lives in
+  // lib/setup/completeness.mjs so setup and doctor never drift. A freshly-created
+  // framework checkout (no config/agent.json) is tolerated — skip the gate there.
+  if (existsSync(join(cwd, "config/agent.json"))) {
+    try {
+      const { assertComplete } = await import(join(MAESTRO_ROOT, "lib", "setup", "completeness.mjs"));
+      const res = await assertComplete(cwd);
+      if (res.ok) {
+        ok("Operating model complete (charter, priorities, backlog≥5, roster, cadences, policies — placeholder-free)");
+      } else {
+        // Identity gaps are reported by the archetype check above; surface the
+        // operating-model artifacts here with their remedy.
+        for (const m of res.missing) {
+          if (m.artifact.startsWith("identity") || m.artifact === "config/agent.json") continue;
+          warn(`Operating model: ${m.artifact} — ${m.reason}`);
+          issues++;
+        }
+        warn("  Finish setup:  maestro setup   (resumes from the checkpoint)");
+      }
+    } catch (err) {
+      warn(`Operating-model gate skipped: ${err && err.message ? err.message : err}`);
+    }
+  }
+
+  // ── Cadence bus state directories ───────────────────────────────────────
+  const busDirs = [
+    "state/cadence-bus",
+    "state/cadence-bus/inbox",
+    "state/cadence-bus/claimed",
+    "state/cadence-bus/processed",
+    "state/cadence-bus/failed",
+    "state/cadence-bus/dlq",
+    "logs/cadence-bus",
+  ];
+  for (const d of busDirs) {
+    if (existsSync(join(cwd, d))) ok(d);
+    else { warn(`Missing: ${d} — run: npx @cohortapp/agent-sdk upgrade`); issues++; }
+  }
+
+  // ── Launchd plist architecture ──────────────────────────────────────────
+  const plistDir = join(cwd, "scripts/local-triggers/plists");
+  if (existsSync(plistDir)) {
+    const plists = readdirSync(plistDir).filter((n) => n.endsWith(".plist"));
+    let legacy = 0;
+    let modern = 0;
+    for (const name of plists) {
+      const body = readFileSync(join(plistDir, name), "utf-8");
+      if (body.includes(LEGACY_PLIST_INDICATOR)) legacy++;
+      else if (body.includes(PLIST_ARCH_MARKER)) modern++;
+    }
+    if (plists.length === 0) {
+      warn("scripts/local-triggers/plists/ is empty — run: scripts/local-triggers/generate-plists.sh");
+      issues++;
+    } else if (legacy > 0) {
+      // Legacy plists are a migration warning rather than a fatal — the
+      // operator can fix them with `maestro upgrade`. Use warn() so the
+      // message lands on stdout where scripted callers will see it.
+      warn(`${legacy} plist(s) still call run-trigger.sh directly (legacy spawn-per-tick).`);
+      warn(`  Fix:  npx @cohortapp/agent-sdk upgrade   (will back up + regenerate)`);
+      issues++;
+    } else {
+      ok(`${modern}/${plists.length} plist(s) use the cadence-bus architecture`);
+    }
+
+    // Spot-check installed plists at ~/Library/LaunchAgents/.
+    const installedDir = join(process.env.HOME || "/", "Library/LaunchAgents");
+    if (existsSync(installedDir)) {
+      let installedLegacy = 0;
+      for (const name of readdirSync(installedDir)) {
+        if (!name.startsWith("ai.maestro.") && !name.startsWith("ai.adaptic.")) continue;
+        if (!name.endsWith(".plist")) continue;
+        const body = readFileSync(join(installedDir, name), "utf-8");
+        if (body.includes(LEGACY_PLIST_INDICATOR)) installedLegacy++;
+      }
+      if (installedLegacy > 0) {
+        warn(`${installedLegacy} installed launchd plist(s) still use the legacy pattern.`);
+        warn("  Fix:  npx @cohortapp/agent-sdk upgrade   then follow the printed launchctl commands.");
+        issues++;
+      } else {
+        ok("Installed launchd plists (ai.maestro.*/legacy ai.adaptic.*) are on cadence-bus or absent");
+      }
+    }
+  } else {
+    warn("scripts/local-triggers/plists/ does not exist yet — run scripts/setup/init-agent.sh");
+  }
+
+  // ── Cadence consumer heartbeat ──────────────────────────────────────────
+  try {
+    // Read via the bundled lib so we don't reinvent path resolution.
+    const mod = readFileSync(join(cwd, "state/cadence-bus/health.json"), "utf-8");
+    const health = JSON.parse(mod);
+    const ageMs = Date.now() - new Date(health.ts).getTime();
+    if (ageMs < 60_000) ok(`Cadence consumer heartbeat fresh (${Math.round(ageMs / 1000)}s)`);
+    else if (ageMs < 5 * 60_000) warn(`Cadence consumer heartbeat stale (${Math.round(ageMs / 1000)}s) — daemon may be slow.`);
+    else {
+      warn(`Cadence consumer heartbeat very stale (${Math.round(ageMs / 1000)}s) — start the daemon: npm run daemon`);
+      issues++;
+    }
+  } catch {
+    warn("No cadence consumer heartbeat yet — start the daemon: npm run daemon");
+  }
+
+  // ── Manual tick smoke test ──────────────────────────────────────────────
+  // Enqueue a heartbeat tick if cadence files are in place. The bus
+  // accepts the event even when the consumer isn't running; the file lands
+  // on disk and is recoverable. This proves the producer side end-to-end.
+  const enqueueScript = join(cwd, "scripts/cadence/enqueue-cadence-tick.mjs");
+  if (existsSync(enqueueScript)) {
+    const result = spawnSync(process.execPath, [
+      enqueueScript, "cadence-bus-heartbeat",
+      "--source=daemon", "--metadata=note=doctor-smoke", "--quiet",
+    ], { cwd, encoding: "utf-8", env: { ...process.env, AGENT_ROOT: cwd } });
+    if (result.status === 0) ok("Cadence enqueue smoke test passed");
+    else {
+      fail(`Cadence enqueue smoke test failed (exit ${result.status}): ${(result.stderr || "").trim()}`);
+      issues++;
+    }
+  }
+
+  // ── WS4: recovery + resource governance ─────────────────────────────────
+  // The kill switch is HUMAN-ONLY now; the watchdog self-heals (soft→hard→
+  // restart→graceful-reboot) and never writes .emergency-stop on OOM. Surface
+  // the live governance posture so an operator can see throttle/breaker/budget
+  // state and the reboot wiring at a glance.
+  {
+    // .emergency-stop present → the agent is intentionally stopped by a human.
+    if (existsSync(join(cwd, ".emergency-stop"))) {
+      let reason = "";
+      try { reason = readFileSync(join(cwd, ".emergency-stop"), "utf-8").trim().split("\n")[0]; } catch { /* */ }
+      fail(`.emergency-stop present${reason ? ` ("${reason}")` : ""} — human-only kill switch is set; agent will not run. Clear with: scripts/resume-operations.sh`);
+      issues++;
+    } else {
+      ok(".emergency-stop absent (agent not human-halted)");
+    }
+
+    // Watchdog heartbeat freshness (<90s).
+    try {
+      const hbRaw = readFileSync(join(cwd, "state/heartbeat"), "utf-8").trim();
+      const hbAgeMs = Date.now() - new Date(hbRaw).getTime();
+      if (Number.isFinite(hbAgeMs) && hbAgeMs < 90_000) ok(`Memory watchdog heartbeat fresh (${Math.round(hbAgeMs / 1000)}s)`);
+      else { warn(`Memory watchdog heartbeat stale (${Math.round(hbAgeMs / 1000)}s) — check ai.maestro.*-memory-watchdog`); issues++; }
+    } catch {
+      warn("No memory watchdog heartbeat (state/heartbeat) — is the watchdog plist loaded?");
+    }
+
+    // Soft-throttle ceiling (state/throttle.json) — WARN while unexpired.
+    try {
+      const { readThrottle, dynamicMax, defaultDeps } = await import(join(MAESTRO_ROOT, "lib", "resource-governor.mjs"));
+      const thr = readThrottle({ agentRoot: cwd });
+      if (thr.ceiling !== Infinity) {
+        warn(`Resource governor throttled: ceiling=${thr.ceiling}${thr.reason ? ` (${thr.reason})` : ""} — watchdog SOFT/HARD tier active; auto-clears on TTL`);
+      } else {
+        ok("No active soft-throttle (state/throttle.json clear/expired)");
+      }
+      // Computed dynamicMax vs RAM (sizing sanity).
+      try {
+        const deps = defaultDeps({ agentRoot: cwd });
+        const dMax = dynamicMax(deps);
+        ok(`Governor dynamicMax=${dMax} (RAM ${Math.round(deps.totalmem / (1024 * 1024 * 1024))}GB, ${deps.cpus} cpus)`);
+      } catch { /* os read best-effort */ }
+    } catch (err) {
+      warn(`Resource governor check skipped: ${err && err.message ? err.message : err}`);
+    }
+
+    // Shared 429 breaker — WARN if open.
+    try {
+      const { checkRateLimit } = await import(join(MAESTRO_ROOT, "lib", "rate-guard.mjs"));
+      const rb = checkRateLimit(process.env.MAESTRO_RATE_PROVIDER || "anthropic", { agentRoot: cwd });
+      if (!rb.allowed) {
+        const mins = Math.max(0, Math.round((rb.retryAt - Date.now()) / 60_000));
+        warn(`429 rate breaker OPEN — spawns gated for ~${mins}m (state/rate-limits/)`); issues++;
+      } else {
+        ok("429 rate breaker closed (spawns allowed)");
+      }
+    } catch { /* breaker read best-effort */ }
+
+    // Today's budget band.
+    try {
+      const { dailyStatus } = await import(join(MAESTRO_ROOT, "lib", "budget-guard.mjs"));
+      const b = dailyStatus({ agentRoot: cwd });
+      if (b.essentialOnly) { warn(`Daily budget cap reached ($${b.spentUSD}/$${b.capUSD}) — essential-only (inbox replies continue; backlog+cadence deferred)`); issues++; }
+      else if (b.band >= 75) { warn(`Daily budget at ${b.band}% ($${b.spentUSD}/$${b.capUSD})`); }
+      else ok(`Daily budget band ${b.band}% ($${b.spentUSD}/$${b.capUSD})`);
+    } catch { /* ledger read best-effort */ }
+
+    // Cost-telemetry tripwire (observability F2). Read today's cost ledger and
+    // cross-check against evidence that sessions actually ran (ledger rows OR a
+    // fresh cadence-consumer heartbeat). If sessions ran but summed
+    // estimated_usd is $0, spend telemetry is blind and the budget governor
+    // can never trip — RED. No sessions, or spend>0 → GREEN.
+    try {
+      const ledgerDate = new Date().toISOString().slice(0, 10);
+      const ledgerPath = join(cwd, "state/cost-tracking", `${ledgerDate}.jsonl`);
+      const rows = [];
+      if (existsSync(ledgerPath)) {
+        const body = readFileSync(ledgerPath, "utf-8");
+        for (const line of body.split("\n")) {
+          if (!line.trim()) continue;
+          try { rows.push(JSON.parse(line)); } catch { /* skip malformed row */ }
+        }
+      }
+      // Heartbeat as out-of-ledger session evidence: a fresh consumer heartbeat
+      // (<5m) means the daemon is live and spawning, so $0 spend is suspicious
+      // even before the first ledger row lands.
+      let heartbeatActive = 0;
+      try {
+        const health = JSON.parse(readFileSync(join(cwd, "state/cadence-bus/health.json"), "utf-8"));
+        const ageMs = Date.now() - new Date(health.ts).getTime();
+        if (Number.isFinite(ageMs) && ageMs >= 0 && ageMs < 5 * 60_000) heartbeatActive = 1;
+      } catch { /* no heartbeat — rely on ledger rows alone */ }
+
+      const tripwire = evaluateCostTripwire({ rows, sessionCount: heartbeatActive });
+      if (tripwire.red) {
+        fail(`Cost telemetry BLIND — ${tripwire.reason}`);
+        fail(`  Fix: callers must pass real --input-tokens/--output-tokens to scripts/cost/track-claude-usage.mjs (lift usage from the claude --output-format json envelope).`);
+        issues++;
+      } else if (tripwire.rowCount === 0 && heartbeatActive === 0) {
+        ok("Cost telemetry: no sessions recorded today (nothing to measure)");
+      } else {
+        ok(`Cost telemetry live ($${tripwire.totalUsd} across ${tripwire.rowCount} ledger row(s) today)`);
+      }
+    } catch { /* cost ledger read best-effort */ }
+
+    // Resume-pending markers stuck at the strike cap.
+    try {
+      const rpDir = join(cwd, "state/sessions/resume-pending");
+      if (existsSync(rpDir)) {
+        let stuck = 0, total = 0;
+        for (const f of readdirSync(rpDir)) {
+          if (!f.endsWith(".json")) continue;
+          total++;
+          try {
+            const m = JSON.parse(readFileSync(join(rpDir, f), "utf-8"));
+            if ((m.recoveryAttempts || 0) >= 3) stuck++;
+          } catch { /* skip */ }
+        }
+        if (stuck > 0) { warn(`${stuck}/${total} resume-pending marker(s) hit the 3-strike cap — items were marked blocked; review state/queues/`); issues++; }
+        else if (total > 0) ok(`${total} in-flight resume marker(s), none stuck`);
+        else ok("No in-flight resume markers");
+      }
+    } catch { /* */ }
+
+    // pmset autorestart — the box must power back on after an outage.
+    try {
+      const ps = spawnSync("pmset", ["-g"], { encoding: "utf-8" });
+      if (ps.status === 0) {
+        const m = (ps.stdout || "").match(/\bautorestart\s+(\d)/);
+        if (m && m[1] === "1") ok("pmset autorestart=1 (box reboots after power loss)");
+        else { warn("pmset autorestart is not 1 — set: sudo pmset -a autorestart 1 (so the agent recovers from power loss)"); issues++; }
+      }
+    } catch { /* pmset unavailable (non-mac / sandbox) — skip */ }
+  }
+
+  // ── .env ────────────────────────────────────────────────────────────────
+  if (existsSync(join(cwd, ".env"))) {
+    // .env permission hygiene (setup-onboarding W4): every credential — Slack,
+    // Gmail, Twilio, Anthropic — lives here in plaintext. It must be chmod 600
+    // (owner-only); a group/world-readable .env on a shared or stolen Mac mini
+    // leaks the principal's full credential set. The framework never chmods it
+    // for the operator — surface the exact fix instead. POSIX-only (mode bits).
+    if (typeof process.getuid === "function") {
+      try {
+        const mode = statSync(join(cwd, ".env")).mode & 0o777;
+        if ((mode & 0o077) !== 0) {
+          fail(`.env is mode ${mode.toString(8).padStart(3, "0")} — group/world can read plaintext secrets.`);
+          fail(`  Fix:  chmod 600 .env`);
+          issues++;
+        } else {
+          ok(".env permissions are owner-only (chmod 600)");
+        }
+      } catch { /* stat failed — skip */ }
+    }
+    const env = readFileSync(join(cwd, ".env"), "utf-8");
+    const check = (key, required) => {
+      const re = new RegExp(`^${key}=.+`, "m");
+      if (re.test(env)) ok(`${key} configured`);
+      else if (required) { warn(`${key} not set`); issues++; }
+      else warn(`${key} not set (optional)`);
+    };
+    check("ANTHROPIC_API_KEY", true);
+    check("SLACK_USER_TOKEN", false);
+    check("GMAIL_APP_PASSWORD", false);
+
+    // Auth validity: if ANTHROPIC_API_KEY is set, ping the API to
+    // verify it works. An invalid key in .env will silently be sent
+    // to every `claude --print` sub-session and cause cascading 401s
+    // (exactly the ravi-ai inbox-processor runaway). Better to catch
+    // it here. Skips the check if the user opted out via
+    // MAESTRO_PREFER_SUBSCRIPTION_AUTH=1 (subscription wins).
+    const keyMatch = env.match(/^ANTHROPIC_API_KEY=(.+)$/m);
+    const preferSubsMatch = env.match(/^MAESTRO_PREFER_SUBSCRIPTION_AUTH=(.+)$/m);
+    const preferSubs = preferSubsMatch && /^1|true|yes$/i.test(preferSubsMatch[1].trim());
+    if (keyMatch && !preferSubs) {
+      const key = keyMatch[1].trim().replace(/^"|"$/g, "");
+      try {
+        const result = spawnSync("curl", [
+          "-s", "-o", "/dev/null", "-w", "%{http_code}",
+          "-X", "POST",
+          "-H", `x-api-key: ${key}`,
+          "-H", "anthropic-version: 2023-06-01",
+          "-H", "content-type: application/json",
+          "--max-time", "8",
+          "https://api.anthropic.com/v1/messages",
+          "-d", JSON.stringify({ model: "claude-haiku-4-5", max_tokens: 5, messages: [{ role: "user", content: "ping" }] }),
+        ], { encoding: "utf-8" });
+        const code = (result.stdout || "").trim();
+        if (code === "200") ok("ANTHROPIC_API_KEY validated against api.anthropic.com");
+        else if (code === "401") {
+          warn(`ANTHROPIC_API_KEY is INVALID (HTTP 401 from api.anthropic.com).`);
+          warn(`  This will cause every sub-session spawn to fail. Either:`);
+          warn(`    1. Replace the key in .env with a valid one, OR`);
+          warn(`    2. Set MAESTRO_PREFER_SUBSCRIPTION_AUTH=1 in .env to use Claude Code subscription auth.`);
+          issues++;
+        } else if (code) warn(`ANTHROPIC_API_KEY check returned HTTP ${code} (expected 200)`);
+        else warn(`ANTHROPIC_API_KEY check skipped (no network / curl missing)`);
+      } catch { warn("ANTHROPIC_API_KEY check failed (curl error)"); }
+    } else if (preferSubs) {
+      ok("MAESTRO_PREFER_SUBSCRIPTION_AUTH=1 — using Claude Code subscription (Keychain OAuth)");
+    }
+
+    // ── Slack Socket Mode ────────────────────────────────────────────────
+    // When SLACK_APP_LEVEL_TOKEN is set, verify the launchd job is loaded
+    // and the listener has connected recently. The check is fully optional:
+    // the framework still works with the legacy 60s poller if the operator
+    // hasn't enabled Socket Mode yet.
+    const socketTokenMatch = env.match(/^SLACK_APP_LEVEL_TOKEN=(.+)$/m);
+    const socketToken = socketTokenMatch ? socketTokenMatch[1].trim().replace(/^["']|["']$/g, "") : "";
+    if (socketToken && socketToken.startsWith("xapp-")) {
+      ok("SLACK_APP_LEVEL_TOKEN configured (Socket Mode candidate)");
+
+      // Resolve the agent's first name the same way generate-plists.sh does
+      // so the label matches whatever is installed in ~/Library/LaunchAgents/.
+      let firstName = "";
+      try {
+        const aj = JSON.parse(readFileSync(join(cwd, "config/agent.json"), "utf-8"));
+        if (aj.firstName) firstName = String(aj.firstName).toLowerCase();
+      } catch { /* fall back */ }
+      if (!firstName) firstName = cwd.split("/").pop().replace(/-ai$/, "").toLowerCase();
+      // Is the plist installed at ~/Library/LaunchAgents/? Prefer the current
+      // ai.maestro.* namespace; fall back to legacy ai.adaptic.* for agents
+      // installed before the rename.
+      const installedDir = join(process.env.HOME || "/", "Library/LaunchAgents");
+      const socketCandidates = [`ai.maestro.${firstName}-slack-socket`, `ai.adaptic.${firstName}-slack-socket`];
+      const socketLabel = socketCandidates.find((l) => existsSync(join(installedDir, `${l}.plist`))) || socketCandidates[0];
+      const installedPath = join(installedDir, `${socketLabel}.plist`);
+      if (existsSync(installedPath)) {
+        // Is it actually loaded? launchctl list returns 0 when the label exists.
+        const listRes = spawnSync("launchctl", ["list", socketLabel], { encoding: "utf-8" });
+        if (listRes.status === 0) ok(`launchd job loaded: ${socketLabel}`);
+        else {
+          warn(`Plist installed but launchd job not loaded: ${socketLabel}`);
+          warn(`  Fix: launchctl load ${installedPath}`);
+          issues++;
+        }
+      } else {
+        warn(`SLACK_APP_LEVEL_TOKEN set but ${installedPath} missing.`);
+        warn("  Run: node scripts/setup/init-slack-socket-mode.mjs");
+        issues++;
+      }
+
+      // Did the listener log a `hello` envelope recently? The log lives at
+      // logs/polling/<today>-slack-socket.jsonl — scan the last few lines
+      // for a fresh "hello" or "inbox-item-written" entry.
+      const today = new Date().toISOString().slice(0, 10);
+      const yesterday = new Date(Date.now() - 86400000).toISOString().slice(0, 10);
+      let foundRecent = false;
+      let latestTs = null;
+      for (const day of [today, yesterday]) {
+        const logPath = join(cwd, "logs/polling", `${day}-slack-socket.jsonl`);
+        if (!existsSync(logPath)) continue;
+        // Read the tail (last 50KB) to avoid loading huge files.
+        try {
+          const stat = statSync(logPath);
+          const buf = Buffer.alloc(Math.min(stat.size, 50_000));
+          const fd = openSync(logPath, "r");
+          try {
+            const start = Math.max(0, stat.size - buf.length);
+            readSync(fd, buf, 0, buf.length, start);
+          } finally { closeSync(fd); }
+          const tail = buf.toString("utf-8");
+          for (const line of tail.split("\n").reverse()) {
+            if (!line) continue;
+            try {
+              const entry = JSON.parse(line);
+              if (entry.message === "hello — connected to Slack Socket Mode" ||
+                  entry.message === "inbox-item-written" ||
+                  entry.message === "starting Socket Mode listener") {
+                latestTs = entry.ts;
+                const ageMs = Date.now() - new Date(entry.ts).getTime();
+                if (ageMs >= 0 && ageMs < 60 * 60_000) foundRecent = true;
+                break;
+              }
+            } catch { /* malformed line — skip */ }
+          }
+          if (latestTs) break;
+        } catch { /* unreadable log — skip */ }
+      }
+      if (foundRecent) {
+        const ageMin = Math.round((Date.now() - new Date(latestTs).getTime()) / 60_000);
+        ok(`Socket Mode listener was active ${ageMin}m ago`);
+      } else if (latestTs) {
+        const ageMin = Math.round((Date.now() - new Date(latestTs).getTime()) / 60_000);
+        warn(`Socket Mode last connect ${ageMin}m ago — may be stalled`);
+        issues++;
+      } else {
+        warn("Socket Mode listener has not produced a connect log yet.");
+        warn("  Check: tail -f logs/polling/$(date +%Y-%m-%d)-slack-socket.jsonl");
+        issues++;
+      }
+    }
+  } else {
+    fail(".env file not found — copy from .env.example");
+    issues++;
+  }
+
+  // ── Dependencies ────────────────────────────────────────────────────────
+  if (existsSync(join(cwd, "node_modules"))) ok("node_modules installed");
+  else { fail("node_modules not found — run: npm install"); issues++; }
+
+  try {
+    execFileSync("which", ["claude"], { stdio: "pipe" });
+    ok("Claude CLI installed");
+  } catch {
+    fail("Claude CLI not found — install: npm install -g @anthropic-ai/claude-code");
+    issues++;
+  }
+
+  try {
+    execFileSync("which", ["jq"], { stdio: "pipe" });
+    ok("jq installed");
+  } catch {
+    warn("jq not found — install: brew install jq (used by various shell helpers)");
+  }
+
+  // ── Emergency-stop wiring ───────────────────────────────────────────────
+  const stopScript = join(cwd, "scripts/emergency-stop.sh");
+  if (existsSync(stopScript)) {
+    const body = readFileSync(stopScript, "utf-8");
+    if (body.includes("$AGENT_DIR/schedules") || body.includes("$SOPHIE_AI_DIR/schedules")) {
+      warn("scripts/emergency-stop.sh still looks in $REPO/schedules/ (legacy path bug). Run: maestro upgrade");
+      issues++;
+    } else if (!body.includes("Library/LaunchAgents")) {
+      warn("scripts/emergency-stop.sh doesn't reference ~/Library/LaunchAgents/ — kill-switch may be ineffective.");
+      issues++;
+    } else {
+      ok("scripts/emergency-stop.sh present (uses ~/Library/LaunchAgents/)");
+    }
+  } else { warn("scripts/emergency-stop.sh missing — kill-switch unavailable"); issues++; }
+
+  // ── Feature-init state ──────────────────────────────────────────────────
+  const featureState = join(cwd, ".maestro/features.json");
+  if (existsSync(featureState)) {
+    try {
+      const s = JSON.parse(readFileSync(featureState, "utf-8"));
+      const pending = (s.pending || []).length;
+      const initialised = Object.keys(s.initialized || {}).length;
+      if (pending > 0) {
+        warn(`${pending} framework feature(s) pending init — run: maestro init`);
+        issues++;
+      } else {
+        ok(`${initialised} framework feature(s) initialised`);
+      }
+    } catch {
+      warn(".maestro/features.json is malformed — run: maestro upgrade");
+      issues++;
+    }
+  } else {
+    warn(".maestro/features.json not found — run: maestro upgrade");
+    issues++;
+  }
+
+  // ── Workflow / agent / skill cross-references ──────────────────────────
+  // Scan workflows/ for `agent:` and `skill:` references and verify each
+  // exists. Catches the "morning-brief references agent: foo that doesn't
+  // exist" class of integration drift.
+  const workflowsDir = join(cwd, "workflows");
+  const agentsDir = join(cwd, "agents");
+  const skillsDir = join(cwd, "plugins/maestro-skills/skills");
+  if (existsSync(workflowsDir)) {
+    const missingAgents = new Set();
+    const missingSkills = new Set();
+    const walkYaml = (dir) => {
+      for (const name of readdirSync(dir)) {
+        const full = join(dir, name);
+        const st = statSync(full);
+        if (st.isDirectory()) walkYaml(full);
+        else if (st.isFile() && /\.ya?ml$/.test(name)) {
+          const body = readFileSync(full, "utf-8");
+          for (const m of body.matchAll(/^\s+agent:\s*([\w-]+)\b/gm)) {
+            const a = m[1];
+            if (a === "agent-self" || a === "agent_self") continue;
+            if (!existsSync(join(agentsDir, a))) missingAgents.add(a);
+          }
+          for (const m of body.matchAll(/^\s+skill:\s*([\w-]+)\b/gm)) {
+            const s = m[1];
+            if (!existsSync(join(skillsDir, `${s}.md`))) missingSkills.add(s);
+          }
+        }
+      }
+    };
+    try { walkYaml(workflowsDir); }
+    catch (err) { warn(`workflow scan failed: ${err.message}`); }
+    if (missingAgents.size === 0 && missingSkills.size === 0) {
+      ok("All workflow agent/skill references resolved");
+    } else {
+      if (missingAgents.size) { warn(`Workflows reference ${missingAgents.size} missing agent(s): ${[...missingAgents].slice(0,5).join(", ")}${missingAgents.size > 5 ? "…" : ""}`); issues++; }
+      if (missingSkills.size) { warn(`Workflows reference ${missingSkills.size} missing skill(s): ${[...missingSkills].slice(0,5).join(", ")}${missingSkills.size > 5 ? "…" : ""}`); issues++; }
+    }
+  }
+
+  // ── state/ + logs/ ownership & permission hygiene (audit M3) ─────────────
+  // The framework runs as the unprivileged user. If state/ or logs/ were
+  // created/chown'd root (e.g. an installer step run under sudo) the daemon's
+  // writes fail silently; a 0777 chmod "fix" then leaves private state
+  // world-writable. Verify ownership + perms here and tell the operator the
+  // exact command to run. We never chown/chmod automatically.
+  if (typeof process.getuid === "function") {
+    const ownershipPaths = [
+      "state", "logs",
+      "state/queues", "state/dashboards",
+      "state/cadence-bus",
+      "state/cadence-bus/inbox", "state/cadence-bus/claimed",
+      "state/cadence-bus/processed", "state/cadence-bus/failed",
+      "state/cadence-bus/dlq",
+      "logs/cadence-bus",
+    ];
+    const entries = ownershipPaths.map((rel) => {
+      const full = join(cwd, rel);
+      try {
+        const st = statSync(full);
+        return { path: rel, mode: st.mode, uid: st.uid, exists: true };
+      } catch {
+        return { path: rel, exists: false };
+      }
+    });
+    const ownership = checkOwnershipSet(entries, { runtimeUid: process.getuid() });
+    if (ownership.ok) {
+      ok("state/ and logs/ owned by runtime uid, not group/world-writable");
+    } else {
+      for (const v of ownership.violations) {
+        fail(`${v.path}: ${v.reasons.join("; ")}`);
+      }
+      fail(`  Fix:  ${ownership.fixCommand}`);
+      issues += ownership.violations.length;
+    }
+  }
+
+  // ── Cadence-bus DLQ depth ───────────────────────────────────────────────
+  const dlqDir = join(cwd, "state/cadence-bus/dlq");
+  if (existsSync(dlqDir)) {
+    const dlqFiles = readdirSync(dlqDir).filter((n) => n.endsWith(".json"));
+    if (dlqFiles.length === 0) ok("Cadence-bus DLQ is empty");
+    else if (dlqFiles.length < 5) warn(`Cadence-bus DLQ: ${dlqFiles.length} event(s). Review: state/cadence-bus/dlq/`);
+    else {
+      fail(`Cadence-bus DLQ: ${dlqFiles.length} event(s) — investigate before clearing.`);
+      issues++;
+    }
+  }
+
+  // ── Backup configured + fresh (DR-config, gaps-enterprise-ops G16) ──────
+  // RED when backup is unconfigured: at fleet scale a machine with no DR target
+  // is a silent data-loss risk. Previously doctor exited 0 on a missing backup
+  // target; now it FAILs so the gap surfaces. GREEN only when a target is
+  // configured AND a recent (<25h) successful run is recorded.
+  const backupCfg = join(cwd, ".maestro/backup-config.yaml");
+  if (existsSync(backupCfg)) {
+    const cfg = readFileSync(backupCfg, "utf-8");
+    if (/enabled:\s*true/.test(cfg)) {
+      const lastBackup = join(cwd, ".maestro/last-backup.json");
+      if (existsSync(lastBackup)) {
+        try {
+          const lb = JSON.parse(readFileSync(lastBackup, "utf-8"));
+          const age = Date.now() - new Date(lb.completed_at).getTime();
+          if (age < 25 * 60 * 60 * 1000) ok(`Backup configured + fresh: last run ${Math.round(age / 3600000)}h ago (${lb.provider}://${lb.bucket})`);
+          else { warn(`Last backup ${Math.round(age / 3600000)}h ago — investigate scripts/maintenance/backup-to-cloud.sh`); issues++; }
+        } catch { warn("last-backup.json is malformed"); }
+      } else {
+        warn("Backup enabled but no successful run yet — schedule scripts/maintenance/backup-to-cloud.sh");
+        issues++;
+      }
+    } else {
+      fail("Backup target present but disabled (.maestro/backup-config.yaml: enabled is not true).");
+      console.log("        fix: set enabled: true and schedule scripts/maintenance/backup-to-cloud.sh");
+      issues++;
+    }
+  } else {
+    fail("No backup target configured — fleet machines need a DR backup (.maestro/backup-config.yaml missing).");
+    console.log("        fix: create .maestro/backup-config.yaml (enabled: true, provider, bucket) and schedule scripts/maintenance/backup-to-cloud.sh");
+    issues++;
+  }
+
+  // ── Cross-agent registry ────────────────────────────────────────────────
+  const knownAgents = join(cwd, "config/known-agents.json");
+  if (existsSync(knownAgents)) {
+    try {
+      const reg = JSON.parse(readFileSync(knownAgents, "utf-8"));
+      const count = Array.isArray(reg.agents) ? reg.agents.length : 0;
+      if (count > 0) ok(`Cross-agent registry: ${count} peer agent(s)`);
+      else warn("config/known-agents.json present but empty — peer-agent detection won't work");
+    } catch {
+      warn("config/known-agents.json is malformed");
+      issues++;
+    }
+  } else {
+    warn("config/known-agents.json missing — run: maestro init known-agents-registry --apply");
+    issues++;
+  }
+
+  // ── Model router (1.12.0+) ─────────────────────────────────────────────
+  // Disabled-but-present is the normal "ready to opt in" state. Active is
+  // verified by loading the config and checking each backend's auth env var.
+  const routerActive = join(cwd, "config/model-routing.yaml");
+  const routerDisabled = join(cwd, "config/model-routing.yaml.disabled");
+  if (existsSync(routerActive)) {
+    try {
+      // Use the framework's loader so we get the same parser as the daemon.
+      const routerPath = process.env.HOME
+        ? join(process.env.HOME, "maestro/lib/model-router.mjs")
+        : null;
+      if (routerPath && existsSync(routerPath)) {
+        const { loadRoutingConfig } = await import(`file://${routerPath}`);
+        const cfg = loadRoutingConfig(cwd);
+        if (!cfg) {
+          warn("config/model-routing.yaml present but loader returned null — check syntax");
+          issues++;
+        } else if (cfg.schema_version === 2) {
+          // ── Policy v2 path: strict-validate + staleness ladder ──────────
+          ok(`Model router active (policy v2, ${Object.keys(cfg.aliases || {}).length} alias(es))`);
+          try {
+            const { validateRoutingConfig } = await import(`file://${routerPath}`);
+            const catalogLib = join(process.env.HOME, "maestro/lib/model-router/catalog.mjs");
+            const { loadCatalog } = await import(`file://${catalogLib}`);
+            const catalog = loadCatalog(cwd, {});
+            const { errors, warnings } = validateRoutingConfig(cfg, { catalog, env: process.env });
+            for (const w of warnings) warn(`  router config: ${w.where} — ${w.warning}`);
+            for (const e of errors) { fail(`  router config: ${e.where} — ${e.error}`); issues++; }
+            if (errors.length === 0) ok("  config strict-validation: passed");
+
+            // Staleness ladder: catalog cost provenance + pricing cache.
+            // WARN @7d, FAIL @30d (graft #18). Volatile rows escalate the FAIL.
+            const models = catalog.models || [];
+            let oldest = null;
+            let anyVolatile = false;
+            for (const r of models) {
+              const p = r.cost_provenance || {};
+              if (p.volatile) anyVolatile = true;
+              if (p.fetched && (oldest == null || p.fetched < oldest)) oldest = p.fetched;
+            }
+            const catStale = evaluateStaleness({ fetched: oldest, hasVolatile: anyVolatile, label: "catalog cost provenance" });
+            if (catStale.status === "fail") { fail(`  ${catStale.reason}`); issues++; }
+            else if (catStale.status === "warn") { warn(`  ${catStale.reason}`); issues++; }
+            else ok(`  ${catStale.reason}`);
+
+            // Pricing cache freshness (cost fields refresh out of band).
+            const priceCachePath = join(cwd, "state/model-router/pricing-cache.json");
+            if (existsSync(priceCachePath)) {
+              let fetched = null;
+              try {
+                const pc = JSON.parse(readFileSync(priceCachePath, "utf-8"));
+                const entries = pc.models && typeof pc.models === "object" ? pc.models : pc;
+                for (const v of Object.values(entries)) {
+                  const f = v && v.provenance && v.provenance.fetched;
+                  if (f && (fetched == null || f < fetched)) fetched = f;
+                }
+                if (!fetched && pc.fetched) fetched = pc.fetched;
+              } catch { /* */ }
+              const pcStale = evaluateStaleness({ fetched, hasVolatile: anyVolatile, label: "pricing cache" });
+              if (pcStale.status === "fail") { fail(`  ${pcStale.reason}`); issues++; }
+              else if (pcStale.status === "warn") { warn(`  ${pcStale.reason}`); issues++; }
+              else ok(`  ${pcStale.reason}`);
+            } else {
+              ok("  pricing cache absent — using bundled catalog prices (provenance above governs)");
+            }
+          } catch (verr) {
+            warn(`  router v2 checks skipped: ${verr.message}`);
+          }
+        } else {
+          const names = Object.keys(cfg.backends);
+          ok(`Model router active (${names.length} backend${names.length === 1 ? "" : "s"}: ${names.join(", ")})`);
+          // Verify auth env for each backend that needs one. We check .env
+          // on disk (not process.env) because doctor doesn't load dotenv;
+          // the daemon does that at spawn time, so a key present in .env is
+          // effectively configured even if process.env doesn't show it.
+          let envBody = "";
+          try { envBody = readFileSync(join(cwd, ".env"), "utf-8"); } catch { /* */ }
+          for (const [name, b] of Object.entries(cfg.backends)) {
+            if (!b.auth_env) continue;
+            const re = new RegExp(`^${b.auth_env}=.+`, "m");
+            const hasInEnvFile = re.test(envBody);
+            const hasInProcEnv = !!process.env[b.auth_env];
+            if (!hasInEnvFile && !hasInProcEnv) {
+              warn(`Model router backend "${name}" needs ${b.auth_env} — not set in .env or process env`);
+              issues++;
+            } else {
+              ok(`  ${name}: ${b.auth_env} configured`);
+            }
+          }
+        }
+      } else {
+        warn("model-router config present but lib/model-router.mjs not reachable — `npm run upgrade` in agent");
+      }
+    } catch (err) {
+      fail(`Model router config failed to load: ${err.message}`);
+      issues++;
+    }
+  } else if (existsSync(routerDisabled)) {
+    ok("Model router available (config/model-routing.yaml.disabled — rename to activate)");
+  }
+
+  // ── Voice realtime (1.12.0+) ───────────────────────────────────────────
+  const voiceActive = join(cwd, "config/voice.yaml");
+  const voiceDisabled = join(cwd, "config/voice.yaml.disabled");
+  if (existsSync(voiceActive)) {
+    ok("Voice channel active (config/voice.yaml)");
+    if (existsSync(join(cwd, ".env"))) {
+      const env = readFileSync(join(cwd, ".env"), "utf-8");
+      if (/^OPENAI_API_KEY=.+/m.test(env)) ok("  OPENAI_API_KEY configured");
+      else { warn("  OPENAI_API_KEY missing — voice channel will not connect"); issues++; }
+      if (/^TWILIO_ACCOUNT_SID=.+/m.test(env) && /^TWILIO_AUTH_TOKEN=.+/m.test(env)) ok("  Twilio credentials configured");
+      else warn("  Twilio creds missing (only required for SIP inbound mode)");
+    }
+    if (!existsSync(join(cwd, "logs/voice/sessions"))) warn("  logs/voice/sessions/ missing — run: maestro init voice-realtime --apply");
+  } else if (existsSync(voiceDisabled)) {
+    ok("Voice channel available (config/voice.yaml.disabled — rename to activate)");
+  }
+
+  // ── Channel bus (1.12.0+) ──────────────────────────────────────────────
+  const channelStateDir = join(cwd, "state/channels");
+  if (existsSync(channelStateDir)) ok("Channel bus state dir present (state/channels/)");
+  else warn("state/channels/ missing — run: maestro init channel-bus --apply");
+
+  // ── WhatsApp transport (1.12.0+) ───────────────────────────────────────
+  const waActive = join(cwd, "config/whatsapp.yaml");
+  const waDisabled = join(cwd, "config/whatsapp.yaml.disabled");
+  if (existsSync(waActive)) {
+    try {
+      const body = readFileSync(waActive, "utf-8");
+      const isBaileys = /^transport:\s*baileys\b/m.test(body);
+      const isTwilio = /^transport:\s*twilio\b/m.test(body);
+      if (isBaileys) {
+        ok("WhatsApp channel active (transport: baileys)");
+        const pkgA = join(cwd, "node_modules/baileys/package.json");
+        const pkgB = join(cwd, "node_modules/@whiskeysockets/baileys/package.json");
+        if (existsSync(pkgA) || existsSync(pkgB)) ok("  baileys npm package installed");
+        else { warn("  baileys not installed — run: npm i baileys"); issues++; }
+        const authDir = join(cwd, "state/whatsapp/auth");
+        if (!existsSync(authDir)) { warn("  state/whatsapp/auth/ missing — run: maestro init whatsapp-baileys --apply"); issues++; }
+      } else if (isTwilio) {
+        ok("WhatsApp channel active (transport: twilio)");
+        if (existsSync(join(cwd, ".env"))) {
+          const env = readFileSync(join(cwd, ".env"), "utf-8");
+          if (/^TWILIO_ACCOUNT_SID=.+/m.test(env)) ok("  TWILIO_ACCOUNT_SID configured");
+          else { warn("  TWILIO_ACCOUNT_SID missing"); issues++; }
+        }
+      } else {
+        warn("config/whatsapp.yaml present but transport is neither 'twilio' nor 'baileys'");
+        issues++;
+      }
+    } catch (err) {
+      warn(`config/whatsapp.yaml unreadable: ${err.message}`);
+      issues++;
+    }
+  } else if (existsSync(waDisabled)) {
+    ok("WhatsApp channel available (config/whatsapp.yaml.disabled — rename to activate)");
+  }
+
+  // ── Collective memory & org mesh ─────────────────────────────────────────
+  if (existsSync(join(cwd, "scripts/collective/hook-runner.mjs"))) {
+    const pointer = join(homedir(), ".claude", "maestro-agent.json");
+    const globalSettings = join(homedir(), ".claude", "settings.json");
+    let wired = false;
+    if (existsSync(globalSettings)) {
+      try {
+        const gs = JSON.parse(readFileSync(globalSettings, "utf-8"));
+        const cmds = Object.values(gs.hooks || {}).flat().flatMap((g) => (g && g.hooks ? g.hooks : [])).map((h) => h && h.command).filter(Boolean);
+        wired = cmds.some((c) => c.includes("scripts/collective/hook-runner.mjs"));
+      } catch { /* */ }
+    }
+    if (wired && existsSync(pointer)) {
+      ok("Collective memory wired into global Claude config (~/.claude)");
+    } else {
+      warn("Collective memory not wired into global Claude config.");
+      warn("  Fix:  npx @cohortapp/agent-sdk global-setup");
+      issues++;
+    }
+  }
+
+  // ── New framework systems (maestro 1.18+) ───────────────────────────────
+  // One-line presence check per system. The lib/* modules are delivered by
+  // `maestro upgrade` (UPGRADE_PATHS includes lib/); a missing module means an
+  // upgrade is overdue (WARN, not FAIL — these systems are additive + fail-open).
+  // The configs are disabled-by-default templates, so "available" is the healthy
+  // resting state until the operator opts in.
+  {
+    const libPresent = (rel) => existsSync(join(cwd, rel));
+    const needsUpgrade = (rel, label) => {
+      if (libPresent(rel)) return true;
+      warn(`${label} module missing (${rel}) — run: npx @cohortapp/agent-sdk upgrade`);
+      issues++;
+      return false;
+    };
+
+    // Org / Cohort plane — REAL connectivity probes (2.0 §5), not presence
+    // checks: enrollment resolution, directory reachability + latency, the
+    // x-org-protocol drift header, the messaging.channels pairing gate, and
+    // the workspace-mailbox probe when config/orgmail.yaml exists. `fail`
+    // counts toward the issues total; `warn` lines are advisory (protocol
+    // drift / servers predating the phase-1 header).
+    if (needsUpgrade("lib/org/client.mjs", "Org client")) {
+      try {
+        const { checkOrgConnectivity } = await import("../lib/org/doctor.mjs");
+        for (const r of await checkOrgConnectivity({ agentRoot: cwd })) {
+          if (r.level === "ok") ok(r.msg);
+          else if (r.level === "warn") warn(r.msg);
+          else { fail(r.msg); issues++; }
+        }
+      } catch (err) {
+        warn(`Org connectivity probes unavailable: ${err && err.message ? err.message : err}`);
+      }
+    }
+
+    // Secret lifecycle (local sealed store by default; broker optional).
+    if (needsUpgrade("lib/secrets/broker.mjs", "Secrets broker")) {
+      if (existsSync(join(cwd, "config/secrets.yaml"))) ok("Secret lifecycle configured (config/secrets.yaml — `maestro secrets list`)");
+      else ok("Secret lifecycle available (config/secrets.yaml absent — `maestro upgrade` ships the template)");
+    }
+
+    // Diagnostics / observability spine.
+    needsUpgrade("lib/diagnostics/trace.mjs", "Diagnostics trace");
+    if (libPresent("lib/diagnostics/counters.mjs")) ok("Diagnostics spine present (trace/events/counters)");
+
+    // Behavioral alerting (thresholds + webhook sink).
+    if (existsSync(join(cwd, "config/alerts.yaml"))) ok("Alerting configured (config/alerts.yaml)");
+    else warn("config/alerts.yaml absent — run: npx @cohortapp/agent-sdk upgrade");
+
+    // Hook bus, dynamic scheduling, send-gate — additive lib spine.
+    needsUpgrade("lib/hooks/bus.mjs", "Hook bus");
+    if (libPresent("lib/scheduling/dynamic-jobs.mjs")) ok("Dynamic scheduling present (lib/scheduling/)");
+    needsUpgrade("lib/comms/send-gate.mjs", "Send-gate");
+  }
+
+  console.log();
+  if (issues === 0) ok("All checks passed.");
+  else warn(`${issues} issue(s) found.`);
+  process.exitCode = issues === 0 ? 0 : 1;
+}
+
+// ---------------------------------------------------------------------------
+// SETUP — the deterministic, resumable, self-verifying wizard (WS1)
+// ---------------------------------------------------------------------------
+
+const SETUP_HELP = `
+${C.bold}maestro setup${C.reset} — configure this agent (deterministic, resumable, self-verifying).
+
+Usage:
+  maestro setup [section] [flags]
+
+Sections (run in order): identity company model comms tools operating-model enrich verify
+
+Flags:
+  --resume               Resume from the checkpoint (default when one exists)
+  --from <id>            Start at section <id> and continue
+  --only <id,id,...>     Run only these sections (forced, even if complete)
+  --status               Print each section's detect() status and exit
+  --headless             Never prompt; use --answers / env / defaults
+  --answers <file.json>  Pre-supplied answers for headless / scripted runs
+  --no-enrich            Skip LLM enrichment (leave deterministic skeletons)
+  --dry-run              Print what would run; write nothing
+  --verbose              Print generator output as sections apply
+  --help, -h             Show this help
+
+Run from inside an agent repo (one with config/agent.json). After
+\`maestro create <dir>\`, do: cd <dir> && maestro setup
+`;
+
+/**
+ * `maestro pair <code>` — open a pre-auth pairing handshake with the org.
+ *
+ * The operator (or an org admin acting on the agent's behalf) picks a `code`,
+ * runs this to POST pairing.request (UNAUTHENTICATED — the agent has no key
+ * yet), and shares the code with an org admin who approves it via
+ * pairing.approve. The device keypair is materialised on first use and its
+ * public key rides in the handshake. Enablement of the knowledge plane still
+ * waits on the admin issuing a Bearer key (paste it into config/org.yaml or
+ * re-run `maestro setup --only org`). Complements the admin-API-key lane; it
+ * does not replace it.
+ */
+async function pairCmd(args = []) {
+  if (args.includes("--help") || args.includes("-h")) {
+    log("Usage: maestro pair <code>");
+    log("  Opens a pre-auth pairing handshake; an org admin approves it (pairing.approve).");
+    log("  Resolves the Cohort base from COHORT_BASE or config/org.yaml.");
+    return;
+  }
+  const cwd = process.cwd();
+  const isAgentRepo = existsSync(join(cwd, "config/agent.json")) || existsSync(join(cwd, "config/agent.ts"));
+  if (!isAgentRepo) {
+    warn("Not a Maestro agent directory (no config/agent.json here).");
+    log("Run this from an agent repo (create one with `maestro create <dirname>`).");
+    process.exitCode = 1;
+    return;
+  }
+
+  let orgMod, clientMod;
+  try {
+    orgMod = await import(pathToFileURL(join(MAESTRO_ROOT, "lib", "setup", "sections", "org.mjs")).href);
+    clientMod = await import(pathToFileURL(join(MAESTRO_ROOT, "lib", "org", "client.mjs")).href);
+  } catch (err) {
+    fail(`could not load the org client: ${err && err.message ? err.message : err}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const cfg = await orgMod.readOrgConfig(cwd);
+  const c = clientMod.configFromAgent(cfg);
+  const base = (process.env.COHORT_BASE || c.base || "").trim();
+  const code = (args.find((a) => a && !a.startsWith("-")) || process.env.COHORT_PAIRING_CODE || "").trim();
+
+  if (!base) {
+    fail("no Cohort base URL — set COHORT_BASE or run `maestro setup --only org` first.");
+    process.exitCode = 1;
+    return;
+  }
+  if (!code || code.length < 4) {
+    fail("usage: maestro pair <code>   (4+ chars; share it with your org admin to approve).");
+    process.exitCode = 1;
+    return;
+  }
+
+  log(`Requesting pairing with ${base} …`);
+  const res = await orgMod.requestPairing(cwd, { base, code, orgId: c.orgId });
+  if (res.ok) {
+    ok(`Pairing requested — code ${res.code}, agent ${res.agentId}, status ${res.status}.`);
+    log("Ask an org admin to approve it (pairing.approve), then set org.cohort.token to the issued key");
+    log("(or re-run `maestro setup --only org`). config/org.yaml records the outstanding handshake.");
+  } else {
+    fail(`Pairing failed: ${res.error}`);
+    process.exitCode = 1;
+  }
+}
+
+async function setupCmd(args = []) {
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log(SETUP_HELP);
+    return;
+  }
+  const cwd = process.cwd();
+  const isAgentRepo = existsSync(join(cwd, "config/agent.json")) || existsSync(join(cwd, "config/agent.ts"));
+  const wantStatus = args.includes("--status");
+
+  if (!isAgentRepo) {
+    // Graceful, non-throwing message (the done-bar requires --help / --status to
+    // run cleanly in a non-agent dir).
+    warn("Not a Maestro agent directory (no config/agent.json here).");
+    log("Create one first:  npx @cohortapp/agent-sdk create <dirname>");
+    log("Then:              cd <dirname> && maestro setup");
+    if (!wantStatus) process.exitCode = 1;
+    return;
+  }
+
+  let runner;
+  try {
+    runner = await import(join(MAESTRO_ROOT, "lib", "setup", "runner.mjs"));
+  } catch (err) {
+    fail(`could not load the setup runner: ${err && err.message ? err.message : err}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  try {
+    const parsed = runner.parseFlags(args);
+    const res = await runner.runSetup({
+      agentRoot: cwd,
+      maestroRoot: MAESTRO_ROOT,
+      flags: parsed.flags,
+      section: parsed.section,
+    });
+    if (res && res.status) return; // --status already printed
+    console.log();
+    const gateGreen = res && res.verify && res.verify.complete && res.verify.complete.ok;
+    if (res && res.ok && gateGreen) {
+      ok("Setup complete — full operating model + a green completeness gate.");
+    } else if (res && res.ok) {
+      // No hard failures (identity/archetype/Claude all OK), but the completeness
+      // gate isn't fully green — usually un-enriched prose slots (e.g. --no-enrich).
+      ok("Setup ran — identity, model, and the operating model are in place.");
+      warn("Some company-specific slots are still skeletons (run without --no-enrich to fill them).");
+      warn("Re-run any time:  maestro setup   (resumes from the checkpoint)");
+    } else {
+      warn("Setup finished with hard failures — see the capability summary above.");
+      warn("Re-run after fixing:  maestro setup   (resumes from the checkpoint)");
+      process.exitCode = 1;
+    }
+  } catch (err) {
+    fail(`setup failed: ${err && err.message ? err.message : err}`);
+    process.exitCode = 1;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// INIT — run pending feature-init steps
+// ---------------------------------------------------------------------------
+
+async function initCmd(args) {
+  const cwd = process.cwd();
+  const help = args.includes("--help") || args.includes("-h");
+  const apply = args.includes("--apply") || args.includes("-y") || args.includes("--yes");
+  const featureArg = args.find((a) => !a.startsWith("-"));
+
+  if (help) {
+    console.log(`
+Usage: maestro init [feature-name] [--apply]
+
+Reconciles this agent's .maestro/features.json against the framework
+feature registry (framework-features.json shipped with @cohortapp/agent-sdk).
+Auto-runnable features are executed directly; features requiring user
+input are listed and can be opted into individually with their name as
+the first argument.
+
+  maestro init                    list pending features (dry-run)
+  maestro init --apply            run every auto-runnable pending step
+  maestro init <feature> --apply  run only the named feature's init step
+  maestro init --help             this help
+
+After init, run \`maestro doctor\` to confirm everything is in place.
+`);
+    return;
+  }
+
+  const { loadRegistry, loadAgentState, reconcileFeatures, listPending, markInitialised, diffFeatures } = await import("../lib/feature-init.mjs");
+  let registry;
+  try { registry = loadRegistry(FRAMEWORK_FEATURES_PATH); }
+  catch (err) { fail(err.message); process.exit(1); }
+
+  if (featureArg) {
+    // Targeted init — run just one feature's command.
+    const def = registry.features?.[featureArg];
+    if (!def) { fail(`unknown feature: ${featureArg}`); process.exit(1); }
+    log(`Running init for ${featureArg}: ${def.init?.description || ""}`);
+    if (!apply) { warn("dry-run — pass --apply to actually run."); return; }
+    const r = await runFeatureInit({ name: featureArg, def, cwd });
+    if (r.ok) {
+      markInitialised(cwd, featureArg, def.version);
+      ok(`initialised: ${featureArg} v${def.version}`);
+    } else {
+      fail(`init failed: ${r.error}`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  // Reconcile + list pending.
+  const state = loadAgentState(cwd);
+  const diff = diffFeatures(registry, state);
+  if (diff.length === 0 && (state.pending || []).length === 0) {
+    ok("All framework features are initialised.");
+    return;
+  }
+
+  // Show what's pending before doing anything.
+  if (!apply) {
+    log(`${diff.length} feature(s) need initialisation:`);
+    for (const item of diff) {
+      const auto = item.definition.init?.auto;
+      console.log(`  ${auto ? "•" : "?"} ${item.definition.title || item.name} (v${item.version}) — ${auto ? "auto" : "needs --apply"}`);
+      if (item.definition.init?.description) console.log(`      ${item.definition.init.description}`);
+    }
+    console.log();
+    log("Run `maestro init --apply` to execute every auto-runnable step.");
+    return;
+  }
+
+  // --apply: run auto features now.
+  log("Running auto-init steps...");
+  const result = reconcileFeatures({
+    maestroRoot: MAESTRO_ROOT,
+    agentRoot: cwd,
+    registry,
+    runAuto: true,
+    logger: (entry) => {
+      const sym = entry.stage === "completed" ? `${C.green}✓${C.reset}` : entry.stage === "failed" ? `${C.red}✗${C.reset}` : entry.stage === "pending" ? `${C.yellow}~${C.reset}` : `${C.cyan}…${C.reset}`;
+      console.log(`  ${sym} ${entry.feature}${entry.message ? ` — ${entry.message}` : ""}`);
+    },
+  });
+
+  console.log();
+  if (result.ranAuto.length) ok(`${result.ranAuto.length} feature(s) initialised: ${result.ranAuto.join(", ")}`);
+  if (result.pending.length) warn(`${result.pending.length} feature(s) still pending (need manual decision): ${result.pending.join(", ")}`);
+  if (result.failed.length) {
+    fail(`${result.failed.length} feature(s) failed during init:`);
+    for (const f of result.failed) console.log(`    ✗ ${f.name}: ${f.error}`);
+    process.exit(1);
+  }
+  if (result.pending.length) {
+    console.log();
+    const pendingList = listPending(cwd);
+    for (const p of pendingList) {
+      console.log(`    To initialise ${p.feature}: maestro init ${p.feature} --apply`);
+    }
+  }
+}
+
+async function runFeatureInit({ name, def, cwd }) {
+  const { execFileSync } = await import("node:child_process");
+  const cmd = def.init?.command;
+  if (!cmd || cmd === "true") return { ok: true };
+  const parts = cmd.split(/\s+/);
+  try {
+    if (parts[0] === "node" && parts[1]) {
+      const script = join(cwd, parts[1]);
+      const fallback = join(MAESTRO_ROOT, parts[1]);
+      const scriptPath = existsSync(script) ? script : (existsSync(fallback) ? fallback : null);
+      if (!scriptPath) return { ok: false, error: `script not found: ${parts[1]}` };
+      execFileSync(process.execPath, [scriptPath, ...parts.slice(2)], {
+        cwd,
+        env: { ...process.env, AGENT_ROOT: cwd, AGENT_DIR: cwd, MAESTRO_ROOT },
+        stdio: "inherit",
+      });
+      return { ok: true };
+    }
+    execFileSync("/bin/bash", ["-lc", cmd], {
+      cwd,
+      env: { ...process.env, AGENT_ROOT: cwd, AGENT_DIR: cwd, MAESTRO_ROOT },
+      stdio: "inherit",
+    });
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// MAIN
+// ---------------------------------------------------------------------------
+
+/** Timestamp suffix for config backups. */
+function tsStamp() {
+  return new Date().toISOString().replace(/[:.]/g, "-");
+}
+
+/** Does `dir` look like a collective-capable agent repo? */
+function isAgentRepo(dir) {
+  return existsSync(join(dir, "config", "agent.json")) &&
+    existsSync(join(dir, "scripts", "collective", "hook-runner.mjs"));
+}
+
+/** Scan the home dir (depth 1) for collective-capable agent repos. */
+function discoverAgentRepos(home) {
+  const out = [];
+  let entries;
+  try { entries = readdirSync(home, { withFileTypes: true }); } catch { return out; }
+  for (const e of entries) {
+    if (!e.isDirectory() || e.name.startsWith(".")) continue;
+    const dir = join(home, e.name);
+    if (isAgentRepo(dir)) out.push(dir);
+  }
+  return out;
+}
+
+/**
+ * Resolve the agent repo global-setup should wire. Order: explicit path arg →
+ * cwd → resolveAgentRoot (env/walk/pointer) → unique home-dir scan. Returns the
+ * path, or null if none / ambiguous (caller reports).
+ */
+async function resolveSetupRepo(args) {
+  const argPath = args.find((a) => !a.startsWith("-"));
+  if (argPath) { const p = resolve(argPath); return isAgentRepo(p) ? p : null; }
+  if (existsSync(join(process.cwd(), "scripts/collective/hook-runner.mjs"))) return process.cwd();
+  try {
+    const { resolveAgentRoot } = await import("../lib/collective/config.mjs");
+    const r = resolveAgentRoot(process.cwd());
+    if (r && isAgentRepo(r)) return r;
+  } catch { /* */ }
+  const found = discoverAgentRepos(homedir());
+  if (found.length === 1) return found[0];
+  if (found.length > 1) { fail(`Multiple agent repos found: ${found.join(", ")}. Pass one: maestro global-setup <repo>`); return null; }
+  return null;
+}
+
+/**
+ * global-setup — wire the Collective Memory & Org Mesh layer into the GLOBAL
+ * Claude Code config (~/.claude) so EVERY session on this machine contributes to
+ * and recalls from this agent's long-term memory, and is aware of concurrent
+ * sessions. Idempotent + additive (never clobbers existing hooks/plugins/config;
+ * backs up settings.json before writing). Run by init-agent.sh, by `wundr
+ * install` (which defers to maestro), and standalone. See
+ * docs/architecture/collective-memory-and-org-mesh.md.
+ */
+async function globalSetup(args = []) {
+  const dryRun = args.includes("--dry-run") || args.includes("-n");
+  console.log();
+  log("Wiring collective memory into the global Claude Code config...");
+  const cwd = await resolveSetupRepo(args);
+  if (!cwd) {
+    fail("Could not locate a Maestro agent repo to wire.");
+    fail("Run from your agent repo, pass it explicitly (`maestro global-setup <repo>`),");
+    fail("or run `npx @cohortapp/agent-sdk upgrade` in the agent repo first.");
+    process.exit(1);
+  }
+  log(`Agent repo: ${cwd}`);
+  const gc = await import("../lib/collective/global-config.mjs");
+  const claudeDir = join(homedir(), ".claude");
+  const settingsPath = join(claudeDir, "settings.json");
+  const claudeMdPath = join(claudeDir, "CLAUDE.md");
+  const pointerFile = join(claudeDir, "maestro-agent.json");
+  if (!dryRun) mkdirSync(claudeDir, { recursive: true });
+
+  let agentName = "";
+  try {
+    const aj = JSON.parse(readFileSync(join(cwd, "config/agent.json"), "utf-8"));
+    agentName = aj.firstName || aj.fullName || "";
+  } catch { /* unconfigured is fine */ }
+
+  // 1) settings.json hooks (deep-merged, idempotent, backed up before write).
+  let settings = {};
+  if (existsSync(settingsPath)) {
+    try { settings = JSON.parse(readFileSync(settingsPath, "utf-8")); } catch { settings = {}; }
+  }
+  const { hooks, added } = gc.mergeCollectiveHooks(settings.hooks || {}, cwd, process.execPath);
+  if (added.length > 0) {
+    settings.hooks = hooks;
+    if (!dryRun) {
+      if (existsSync(settingsPath)) {
+        try { copyFileSync(settingsPath, `${settingsPath}.backup.${tsStamp()}`); } catch { /* */ }
+      }
+      writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+    }
+    ok(`${dryRun ? "[dry-run] " : ""}global hooks added: ${added.join(", ")}`);
+  } else {
+    ok("global hooks already present (no change)");
+  }
+
+  // 2) global CLAUDE.md directive (only our delimited block is touched).
+  let mdContent = "";
+  if (existsSync(claudeMdPath)) { try { mdContent = readFileSync(claudeMdPath, "utf-8"); } catch { /* */ } }
+  const md = gc.upsertClaudeMdBlock(mdContent, gc.buildCollectiveClaudeMd(cwd));
+  if (md.changed) {
+    if (!dryRun) writeFileSync(claudeMdPath, md.content);
+    ok(`${dryRun ? "[dry-run] " : ""}global CLAUDE.md collective block written`);
+  } else {
+    ok("global CLAUDE.md collective block up to date");
+  }
+
+  // 3) machine pointer (locates the agent for sessions in any repo).
+  if (!dryRun) writeFileSync(pointerFile, JSON.stringify(gc.buildPointer(cwd, agentName), null, 2));
+  ok(`${dryRun ? "[dry-run] " : ""}machine pointer → ${pointerFile}`);
+
+  console.log();
+  if (dryRun) {
+    log("Dry run complete — no files written.");
+  } else {
+    log("Collective memory wired. New Claude Code sessions on this machine now");
+    log("contribute to + recall from this agent, and see concurrent sessions.");
+    if (added.length > 0) log("Restart running interactive sessions to pick up the new hooks.");
+  }
+}
+
+// ---------------------------------------------------------------------------
+// AUDIT — registry-driven security-posture audit + attestation (G15)
+// ---------------------------------------------------------------------------
+//
+// `maestro audit` runs lib/security/audit-engine.mjs against the current agent
+// repo and prints a one-line-per-check summary (or JSON). It exits non-zero on
+// any unsuppressed failure, so it's CI-usable. `--fix` applies the safe,
+// declared auto-fixes first, then re-audits. `--attest` (implied by --json)
+// emits the hash-locked conformance artifact the org server aggregates.
+
+async function auditCmd(args = []) {
+  const flags = { json: false, fix: false };
+  for (const a of args) {
+    if (a === "--json") flags.json = true;
+    else if (a === "--fix") flags.fix = true;
+    else if (a === "--help" || a === "-h") {
+      console.log(`
+Usage: maestro audit [--json] [--fix]
+
+Runs the registry-driven security-posture audit (lib/security/audit-engine.mjs)
+against this agent repo. Exits non-zero on any unsuppressed failure.
+
+Flags:
+  --json   Emit machine-readable JSON (results + hash-locked attestation)
+  --fix    Apply safe auto-fixes (e.g. chmod 600 .env, remove tracked .pyc),
+           then re-audit. Non-fixable findings are left for you to resolve.
+
+Suppressions: config/audit-suppressions.yaml — a list of { id, reason, until }.
+A suppression silences one check id, requires a reason, and expires at 'until'.
+`.trim());
+      return;
+    } else { fail(`Unknown flag: ${a}`); process.exit(1); }
+  }
+
+  const cwd = process.cwd();
+  if (!existsSync(join(cwd, "config/agent.json")) && !existsSync(join(cwd, "config/agent.ts")) && !existsSync(join(cwd, "CLAUDE.md"))) {
+    if (flags.json) { console.log(JSON.stringify({ ok: false, error: "not a Maestro agent directory" })); }
+    else { fail("Not a Maestro agent directory (config/agent.json not found)"); }
+    process.exit(1);
+  }
+
+  let audit;
+  let fixed = [];
+  if (flags.fix) {
+    const res = await applyFixes(cwd);
+    fixed = res.fixed;
+    audit = res.audit;
+  } else {
+    audit = await runAudit(cwd);
+  }
+  const attestation = buildAttestation(audit, cwd);
+
+  if (flags.json) {
+    console.log(JSON.stringify({ ok: audit.ok, summary: audit.summary, results: audit.results, suppressed: audit.suppressed, fixed, attestation }, null, 2));
+    process.exit(audit.ok ? 0 : 1);
+  }
+
+  console.log();
+  console.log(`${C.bold}Security posture audit${C.reset}`);
+  if (fixed.length) ok(`applied ${fixed.length} safe fix(es): ${fixed.join(", ")}`);
+  for (const r of audit.results) {
+    if (r.ok) { ok(`[${r.severity}] ${r.id} — ${r.detail}`); continue; }
+    if (r.suppressed) {
+      warn(`[${r.severity}] ${r.id} — SUPPRESSED (${r.suppressionReason}${r.suppressionUntil ? `, until ${r.suppressionUntil}` : ""})`);
+      continue;
+    }
+    fail(`[${r.severity}] ${r.id} — ${r.detail}`);
+    if (r.fix) console.log(`        fix: ${r.fix}${r.fixable ? "  (or: maestro audit --fix)" : ""}`);
+  }
+  console.log();
+  const s = audit.summary;
+  console.log(`=== ${s.passed}/${s.total} checks passed${s.suppressed ? `, ${s.suppressed} suppressed` : ""}${s.failed ? `, ${s.failed} FAILED` : ""} ===`);
+  console.log(`attestation: ${attestation.hash.slice(0, 16)}…  (archetype: ${attestation.identity.function || "?"}/${attestation.identity.altitude || "?"})`);
+  if (audit.ok) ok("Posture conformant — no unsuppressed failures.");
+  else fail(`Posture has ${s.failed} unsuppressed failure(s)${s.worstSeverity ? ` (worst: ${s.worstSeverity})` : ""}.`);
+  process.exit(audit.ok ? 0 : 1);
+}
+
+// ---------------------------------------------------------------------------
+// SECRETS — secret lifecycle (gaps-enterprise-ops G12)
+// ---------------------------------------------------------------------------
+//
+// `maestro secrets sync`          Pull org secrets from the broker into the
+//                                 local encrypted store (cached, offline).
+// `maestro secrets list`          Print secret NAMES only (never values).
+// `maestro secrets rotate --name X`  Rotate X; the new value is read from stdin
+//                                 so it never lands in shell history / argv.
+//
+// Config lives in config/secrets.yaml. The broker fetch is the runtime global
+// (real network) here — tests exercise lib/secrets directly with an injected
+// fetch, never through this command.
+
+const SECRETS_HELP = `
+Usage: maestro secrets <list|sync|rotate> [flags]
+
+  list                     Print secret names in the local store (names only)
+  sync [--name X ...]      Pull org secrets from the broker into the local store
+                           (no --name → pull every name the broker lists)
+  rotate --name X          Rotate secret X; the new value is read from stdin
+
+Config: config/secrets.yaml  (provider: file|env|keychain, broker: { base_url, token_env })
+Audit:  logs/audit/secrets.jsonl  (names only — values are never logged)
+`.trim();
+
+/** Load + parse config/secrets.yaml (YAML or JSON), or null when absent. */
+async function loadSecretsConfig(cwd) {
+  const path = join(cwd, "config/secrets.yaml");
+  if (!existsSync(path)) return null;
+  const text = readFileSync(path, "utf-8");
+  try {
+    const y = await import("js-yaml");
+    return y.load(text) || null;
+  } catch {
+    // js-yaml unavailable — accept a JSON config as a graceful fallback.
+    try { return JSON.parse(text); } catch { return null; }
+  }
+}
+
+/** Read a value from stdin (for `rotate`, so secrets never touch argv). */
+function readStdin() {
+  try {
+    // 1 MiB cap is plenty for a secret; read the whole fd 0.
+    const buf = readFileSync(0, "utf-8");
+    return buf.replace(/\r?\n$/, "");
+  } catch {
+    return "";
+  }
+}
+
+async function secretsCmd(args = []) {
+  const sub = args[0];
+  if (!sub || sub === "--help" || sub === "-h") {
+    console.log(SECRETS_HELP);
+    return;
+  }
+  const cwd = process.cwd();
+  if (!existsSync(join(cwd, "config/agent.json")) && !existsSync(join(cwd, "config/agent.ts")) && !existsSync(join(cwd, "CLAUDE.md"))) {
+    fail("Not a Maestro agent directory (config/agent.json not found)");
+    process.exit(1);
+  }
+
+  // Parse --name (repeatable) for sync/rotate.
+  const names = [];
+  for (let i = 1; i < args.length; i++) {
+    if (args[i] === "--name" || args[i] === "-n") { names.push(args[++i]); }
+  }
+
+  const cfg = await loadSecretsConfig(cwd);
+
+  if (sub === "list") {
+    const provider = selectProvider(cfg, { agentRoot: cwd, env: process.env });
+    const list = await provider.list();
+    if (list.length === 0) {
+      log(`No secrets in the local store (provider: ${provider.name}).`);
+      return;
+    }
+    log(`Secrets in the local store (provider: ${provider.name}) — names only:`);
+    for (const n of list) console.log(`  ${n}`);
+    return;
+  }
+
+  if (sub === "sync") {
+    const broker = makeBroker(cfg, { fetch: globalThis.fetch });
+    if (!broker) {
+      fail("No broker configured — set config/secrets.yaml: broker.base_url + token_env.");
+      process.exitCode = 1;
+      return;
+    }
+    let toPull = names.filter(Boolean);
+    if (toPull.length === 0) {
+      // No explicit names → pull everything the broker advertises.
+      toPull = await broker.list();
+      if (toPull.length === 0) {
+        warn("Broker returned no secret names to sync.");
+        return;
+      }
+    }
+    let res;
+    try {
+      res = await syncSecrets({ cfg, agentRoot: cwd, env: process.env, fetch: globalThis.fetch, names: toPull });
+    } catch (err) {
+      fail(`secrets sync failed: ${err.message}`);
+      process.exitCode = 1;
+      return;
+    }
+    if (res.synced.length) ok(`Synced ${res.synced.length} secret(s): ${res.synced.join(", ")}`);
+    if (res.missing.length) warn(`Broker had no value for: ${res.missing.join(", ")}`);
+    for (const f of res.failed) fail(`Failed to store ${f.name}: ${f.error}`);
+    process.exitCode = res.failed.length ? 1 : 0;
+    return;
+  }
+
+  if (sub === "rotate") {
+    const name = names.filter(Boolean)[0];
+    if (!name) {
+      fail("usage: maestro secrets rotate --name <SECRET_NAME>  (new value on stdin)");
+      process.exitCode = 1;
+      return;
+    }
+    const value = readStdin();
+    if (!value) {
+      fail("No value on stdin. Pipe the new value: echo -n 'newval' | maestro secrets rotate --name X");
+      process.exitCode = 1;
+      return;
+    }
+    try {
+      const res = await rotateSecret(name, value, { cfg, agentRoot: cwd, env: process.env, fetch: globalThis.fetch });
+      ok(`Rotated "${res.name}" on ${res.provider}${res.mirrored ? " (mirrored locally)" : ""}.`);
+      log(`Audit: ${relative(cwd, auditLogPath(cwd))} (names only)`);
+    } catch (err) {
+      fail(`Rotation failed: ${err.message}`);
+      process.exitCode = 1;
+      return;
+    }
+    return;
+  }
+
+  fail(`Unknown secrets subcommand: ${sub}`);
+  console.log(SECRETS_HELP);
+  process.exitCode = 1;
+}
+
+// ---------------------------------------------------------------------------
+// SYNC — re-pull this agent's record from Cohort and update config/agent.json
+// ---------------------------------------------------------------------------
+//
+// The seamless-UPDATE path that mirrors the Cohort-driven setup pull: when
+// COHORT_API_KEY + COHORT_ORG_ID (optionally COHORT_AGENT_ID) are present it
+// re-pulls the MemberProfileDTO, maps it to the config/agent.json subset, merges
+// it (never clobbering a locally-customised value unless --force), regenerates
+// the derived artefacts, and prints a diff of what changed. Fail-open + idempotent.
+
+const SYNC_HELP = `
+Usage: maestro sync [flags]
+
+Re-pull this agent's record from Cohort (the org single source of truth) and
+update config/agent.json. Requires COHORT_API_KEY + COHORT_ORG_ID in the env
+(optionally COHORT_AGENT_ID to select a specific member; otherwise whoami).
+
+Flags:
+  --force      Overwrite locally-customised values too (default: protect them)
+  --dry-run    Show the diff without writing config/agent.json
+  --help, -h   Show this help
+`;
+
+function parseSyncFlags(args) {
+  const flags = { force: false, dryRun: false };
+  for (const a of args) {
+    if (a === "--force") flags.force = true;
+    else if (a === "--dry-run" || a === "-n") flags.dryRun = true;
+    else if (a === "--help" || a === "-h") return null;
+    else { fail(`Unknown sync flag: ${a}`); process.exit(1); }
+  }
+  return flags;
+}
+
+/** Render one diff row's value compactly for the CLI report. */
+function fmtSyncVal(v) {
+  if (v === undefined) return "(unset)";
+  if (Array.isArray(v)) return `[${v.length} item${v.length === 1 ? "" : "s"}]`;
+  if (v && typeof v === "object") return JSON.stringify(v);
+  const s = String(v);
+  return s.length > 60 ? `${s.slice(0, 57)}…` : s;
+}
+
+async function syncCmd(args = []) {
+  const flags = parseSyncFlags(args);
+  if (flags === null) { console.log(SYNC_HELP); return; }
+  const cwd = process.cwd();
+
+  if (!existsSync(join(cwd, "config/agent.json")) && !existsSync(join(cwd, "config/agent.ts"))) {
+    fail("Not a Maestro agent directory (config/agent.json not found)");
+    process.exit(1);
+  }
+
+  const { cohortPullEnv, pullAndPlan } = await import(join(MAESTRO_ROOT, "lib", "setup", "enroll-from-cohort.mjs"));
+  const { fetchSelfProfile } = await import(join(MAESTRO_ROOT, "lib", "org", "client.mjs"));
+
+  const e = cohortPullEnv();
+  if (!e.enabled) {
+    fail("Cohort pull not configured — set COHORT_API_KEY and COHORT_ORG_ID.");
+    process.exit(1);
+  }
+
+  // Test seam (sandbox/offline): MAESTRO_SYNC_FETCH_SELF_PROFILE points at an ESM
+  // module default-exporting a fetchSelfProfile-shaped fn, so the sync path can be
+  // exercised end-to-end without a network round-trip. Never used in production.
+  let fetchSelf = fetchSelfProfile;
+  if (process.env.MAESTRO_SYNC_FETCH_SELF_PROFILE) {
+    try {
+      const mod = await import(pathToFileURL(process.env.MAESTRO_SYNC_FETCH_SELF_PROFILE).href);
+      if (typeof (mod.default || mod.fetchSelfProfile) === "function") fetchSelf = mod.default || mod.fetchSelfProfile;
+    } catch { /* fall back to the real client */ }
+  }
+
+  log(`Re-pulling profile from Cohort (${e.agentId ? `member ${e.agentId}` : "whoami"})…`);
+  const plan = await pullAndPlan({ agentRoot: cwd, force: flags.force, fetchSelfProfileImpl: fetchSelf });
+  if (!plan.pulled) {
+    warn(`No profile pulled (${plan.reason || "unknown"}). config/agent.json unchanged.`);
+    return;
+  }
+
+  if (!plan.changes.length) {
+    ok("Already in sync with Cohort — no changes.");
+    return;
+  }
+
+  console.log();
+  console.log(`${C.bold}Changes from Cohort${flags.dryRun ? " (dry run)" : ""}:${C.reset}`);
+  for (const ch of plan.changes) {
+    console.log(`  ${ch.path}: ${C.yellow}${fmtSyncVal(ch.from)}${C.reset} → ${C.green}${fmtSyncVal(ch.to)}${C.reset}`);
+  }
+  console.log();
+
+  if (flags.dryRun) {
+    log("Dry run — config/agent.json not modified. Re-run without --dry-run to apply.");
+    return;
+  }
+
+  const { mergeAgentJson, ensureSotWrapper } = await import(join(MAESTRO_ROOT, "lib", "setup", "sot.mjs"));
+  mergeAgentJson(cwd, plan.patch);
+  ok(`Updated config/agent.json (${plan.changes.length} field${plan.changes.length === 1 ? "" : "s"}).`);
+
+  // Regenerate the derived artefacts so the archetype/wrapper/env reflect the pull.
+  try {
+    const { runGenerator } = await import(join(MAESTRO_ROOT, "lib", "setup", "run-generator.mjs"));
+    runGenerator("init-archetype.mjs", cwd, { maestroRoot: MAESTRO_ROOT });
+    ensureSotWrapper(cwd);
+    runGenerator("generate-agent-env.mjs", cwd, { maestroRoot: MAESTRO_ROOT });
+    ok("Regenerated archetype, agent.ts wrapper, and agent.env.");
+  } catch (err) {
+    warn(`Derived-artefact regeneration skipped: ${err && err.message ? err.message : err}`);
+  }
+
+  // Refresh the authoritative org context cache (config/org-context.json) so the
+  // agent's situational awareness tracks the org. Fail-open + non-blocking.
+  try {
+    const { bootstrapOrgContextInto } = await import(join(MAESTRO_ROOT, "lib", "setup", "sections", "org.mjs"));
+    const res = await bootstrapOrgContextInto(cwd, {});
+    if (res && res.path) ok("Refreshed config/org-context.json from Cohort.");
+  } catch { /* fail-open — local model stands */ }
+}
+
+// ---------------------------------------------------------------------------
+// WHO-OWNS — situational awareness over the cached org context
+// ---------------------------------------------------------------------------
+//
+// The runtime consumer of lib/org/awareness.mjs: deterministic, ZERO-LLM answers
+// drawn from config/org-context.json (the Cohort bootstrap cache) — "who owns
+// this scope?", "who do I escalate to?", "who reports to me?", "which adopted
+// decisions touch this topic?". Fail-open: an un-enrolled agent (no cache) prints
+// a clear hint instead of erroring.
+
+/**
+ * Render the awareness answers for the current agent to stdout.
+ * @param {string[]} args - [scope?] plus flags (--escalate, --reports, --decisions, --json)
+ */
+async function whoOwnsCmd(args = []) {
+  const cwd = process.cwd();
+  const flags = new Set(args.filter((a) => a.startsWith("--")));
+  const positional = args.filter((a) => !a.startsWith("--"));
+  const scope = positional.join(" ").trim();
+  const asJson = flags.has("--json");
+
+  const { loadOrgContext } = await import(join(MAESTRO_ROOT, "lib", "org", "bootstrap-context.mjs"));
+  const ctx = loadOrgContext(cwd);
+  if (!ctx) {
+    if (asJson) { console.log(JSON.stringify({ error: "no-org-context" })); return; }
+    warn("No cached org context (config/org-context.json). Enroll + sync first:");
+    warn("  maestro setup --only org   # then   maestro sync");
+    return;
+  }
+
+  const aw = await import(join(MAESTRO_ROOT, "lib", "org", "awareness.mjs"));
+  const wantEscalate = flags.has("--escalate");
+  const wantReports = flags.has("--reports");
+  const wantDecisions = flags.has("--decisions");
+  const wantOwner = !!scope || (!wantEscalate && !wantReports && !wantDecisions);
+
+  const result = {};
+  if (wantOwner && scope) result.owner = aw.ownerOf(ctx, scope);
+  if (wantEscalate || (!scope && !wantReports && !wantDecisions)) result.escalateTo = aw.escalateTo(ctx);
+  if (wantReports) result.reports = aw.whoReportsToMe(ctx, ctx.profile && ctx.profile.slug);
+  if (wantDecisions) result.decisions = aw.relevantDecisions(ctx, scope);
+
+  if (asJson) { console.log(JSON.stringify(result, null, 2)); return; }
+
+  console.log();
+  if (scope && "owner" in result) {
+    const o = result.owner;
+    if (o) log(`Owner of "${scope}": ${C.bold}${o.owner.displayName || o.owner.slug}${C.reset} (${o.role || "assigned"}) — stream ${o.stream.name || o.stream.code || "?"}`);
+    else warn(`No accountable owner found for "${scope}" in the org strategy.`);
+  }
+  if ("escalateTo" in result) {
+    const e = result.escalateTo;
+    if (e) log(`Escalate to: ${e.manager ? (e.manager.displayName || e.manager.slug) : "(no manager)"}${e.escalationPath ? ` — ${e.escalationPath}` : ""}`);
+    else warn("No escalation target recorded in the org context.");
+  }
+  if (wantReports) {
+    const rs = result.reports || [];
+    if (rs.length) { log(`Reports (${rs.length}):`); for (const r of rs) ok(`${r.displayName || r.slug}${r.style ? ` [${r.style}]` : ""}`); }
+    else warn("No direct reports recorded in the org context.");
+  }
+  if (wantDecisions) {
+    const ds = result.decisions || [];
+    if (ds.length) { log(`Adopted decisions${scope ? ` touching "${scope}"` : ""} (${ds.length}):`); for (const d of ds.slice(0, 12)) ok(d.title || d.summary || d.id || "(untitled)"); }
+    else warn(`No adopted decisions${scope ? ` touching "${scope}"` : ""}.`);
+  }
+}
+
+// Pure, side-effect-free helpers exported for unit tests (bin/maestro.test.mjs).
+// They carry no I/O so importing this module to test them is safe; the CLI
+// dispatch below only runs when the file is the process entrypoint.
+export { evaluateCostTripwire, summariseLedgerRows, evaluateStaleness, parseSyncFlags, fmtSyncVal };
+
+async function main() {
+const [, , command, ...args] = process.argv;
+
+switch (command) {
+  case "create": create(args[0]); break;
+  case "setup": await setupCmd(args); break;
+  case "pair": await pairCmd(args); break;
+  case "sync": await syncCmd(args); break;
+  case "upgrade": await upgrade(args); break;
+  case "global-setup": await globalSetup(args); break;
+  case "doctor": await doctor(); break;
+  case "audit": await auditCmd(args); break;
+  case "router": await routerCmd(args); break;
+  case "secrets": await secretsCmd(args); break;
+  case "who-owns": case "who": await whoOwnsCmd(args); break;
+  case "init":
+  case "update-init":
+  case "init-update":
+    await initCmd(args); break;
+  case "--help": case "-h": case undefined:
+    console.log(`
+Maestro — Autonomous AI Agent Operating System
+
+Usage:
+  npx @cohortapp/agent-sdk create <dirname>           Create a new agent repo
+  npx @cohortapp/agent-sdk setup [section] [flags]    Configure this agent (deterministic, resumable wizard)
+  npx @cohortapp/agent-sdk pair <code>                Open a pre-auth pairing handshake (org admin approves it)
+  npx @cohortapp/agent-sdk sync [--force] [--dry-run] Re-pull this agent's record from Cohort into config/agent.json
+  npx @cohortapp/agent-sdk upgrade [--dry-run]        Update framework files
+  npx @cohortapp/agent-sdk init [feature] [--apply]   Run pending feature-init steps
+  npx @cohortapp/agent-sdk global-setup [--dry-run]   Wire collective memory into ~/.claude (machine-wide)
+  npx @cohortapp/agent-sdk doctor                     Verify installation
+  npx @cohortapp/agent-sdk audit [--json] [--fix]     Security-posture audit + hash-locked attestation
+  npx @cohortapp/agent-sdk router why <item>          Explain a routing decision (chain + tried + explain)
+  npx @cohortapp/agent-sdk router validate            Strict-validate config/model-routing.yaml
+  npx @cohortapp/agent-sdk secrets list               List local secret names (names only)
+  npx @cohortapp/agent-sdk secrets sync [--name X]    Pull org secrets from the broker into the local store
+  npx @cohortapp/agent-sdk secrets rotate --name X    Rotate a secret (new value read from stdin)
+  npx @cohortapp/agent-sdk who-owns <scope>           Who owns a scope / escalate-to / reports (org context, zero-LLM)
+
+Upgrade 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
+  --verbose, -v          List classification for every file
+
+Init flags:
+  (no args)              List pending features (dry-run)
+  --apply, -y            Run every auto-runnable pending step
+  <feature> --apply      Run only the named feature's init step
+
+Workflow:
+  1. npx @cohortapp/agent-sdk create my-agent
+  2. cd my-agent
+  3. maestro setup
+
+Upgrade workflow (existing agents):
+  1. npm update @cohortapp/agent-sdk
+  2. npm run upgrade        (runs maestro upgrade + auto-init)
+  3. maestro init           (run any deferred init steps)
+`);
+    break;
+  default:
+    fail(`Unknown command: ${command}`);
+    process.exit(1);
+}
+}
+
+// Dispatch only when invoked as the CLI entrypoint — importing for tests must
+// not run any command (process.argv would be the test runner's argv).
+if (import.meta.url === `file://${process.argv[1]}`) {
+  await main();
+}