@cohortapp/agent-sdk 2.3.0

package/scripts/setup/init-agent.test.mjs

@@ -0,0 +1,151 @@
+// init-agent.test.mjs — supply-chain hygiene of scripts/setup/init-agent.sh
+//
+// Item 0.11 (audit setup-onboarding W1/W2, policies-prompts F-15). Covers the
+// global ~/.claude/settings.json handling: it must DEEP-MERGE maestro's
+// additions into any pre-existing settings (preserving the operator's keys)
+// rather than overwrite, and it must never install an allow-all permissions
+// block or wire unpinned third-party (ruflo@latest) hooks.
+//
+// The deep-merge logic is embedded in init-agent.sh as the MAESTRO_MERGE_NODE
+// program (between the BEGIN/END marker comments). We extract that *exact*
+// program and exercise it via a subprocess — no duplicated logic — so the test
+// pins what the script actually ships.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync, writeFileSync, mkdtempSync, rmSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { join, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SCRIPT = join(__dirname, "init-agent.sh");
+const scriptSrc = readFileSync(SCRIPT, "utf8");
+
+// --- extract the embedded merge program (single source of truth) -----------
+function extractMergeProgram() {
+  // MAESTRO_MERGE_NODE='<program>' — single-quoted bash heredoc-style literal.
+  const m = scriptSrc.match(/MAESTRO_MERGE_NODE='([\s\S]*?)'\n# --- END maestro settings deep-merge ---/);
+  assert.ok(m, "MAESTRO_MERGE_NODE program not found in init-agent.sh");
+  return m[1];
+}
+
+function makeTmp() {
+  const dir = mkdtempSync(join(tmpdir(), "init-agent-test-"));
+  return dir;
+}
+
+// Run the extracted node merge program: existing settings JSON (or null for a
+// missing file) + additions JSON on stdin -> returns the merged object.
+function runMerge(existing, additions) {
+  const dir = makeTmp();
+  try {
+    const progPath = join(dir, "merge.cjs");
+    const inPath = join(dir, "settings.json");
+    const outPath = join(dir, "out.json");
+    writeFileSync(progPath, extractMergeProgram());
+    if (existing !== null) {
+      writeFileSync(inPath, typeof existing === "string" ? existing : JSON.stringify(existing));
+    }
+    execFileSync(process.execPath, [progPath, inPath, outPath], {
+      input: JSON.stringify(additions),
+    });
+    return JSON.parse(readFileSync(outPath, "utf8"));
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+// The real additions block the script feeds in (subset that matters here).
+const MAESTRO_ADDITIONS = {
+  $schema: "https://json.schemastore.org/claude-code-settings.json",
+  enabledPlugins: { "claude-mem": true, "context7@claude-plugins-official": true },
+  effortLevel: "high",
+};
+
+test("deep-merge preserves a pre-existing user key", () => {
+  const existing = {
+    myCustomKey: "keep-me",
+    enabledPlugins: { "user-only-plugin": true },
+  };
+  const merged = runMerge(existing, MAESTRO_ADDITIONS);
+
+  // User's top-level key survives.
+  assert.equal(merged.myCustomKey, "keep-me");
+  // User's plugin survives AND maestro's additions land alongside it (object merge).
+  assert.equal(merged.enabledPlugins["user-only-plugin"], true);
+  assert.equal(merged.enabledPlugins["claude-mem"], true);
+  assert.equal(merged.enabledPlugins["context7@claude-plugins-official"], true);
+  // Maestro scalar additions land when the user had nothing there.
+  assert.equal(merged.effortLevel, "high");
+});
+
+test("existing scalar value wins over maestro addition (no clobber)", () => {
+  const existing = { effortLevel: "low", $schema: "user-schema" };
+  const merged = runMerge(existing, MAESTRO_ADDITIONS);
+  assert.equal(merged.effortLevel, "low", "user's effortLevel must not be overwritten");
+  assert.equal(merged.$schema, "user-schema", "user's $schema must not be overwritten");
+});
+
+test("merge never emits an allow-all permissions block", () => {
+  const merged = runMerge({ someKey: 1 }, MAESTRO_ADDITIONS);
+  // No permissions block introduced by maestro at all.
+  assert.equal(merged.permissions, undefined);
+  const dumped = JSON.stringify(merged);
+  assert.ok(!dumped.includes("Bash(*)"), "must not contain Bash(*) allow-all");
+  assert.ok(!dumped.includes("Write(*)"), "must not contain Write(*) allow-all");
+  assert.ok(!dumped.includes("skipDangerousModePermissionPrompt"), "must not skip dangerous-mode prompt");
+});
+
+test("a pre-existing user permissions block is preserved untouched", () => {
+  const existing = {
+    permissions: { allow: ["Read(/safe/*)"], deny: ["Bash(rm -rf /)"] },
+  };
+  const merged = runMerge(existing, MAESTRO_ADDITIONS);
+  assert.deepEqual(merged.permissions.allow, ["Read(/safe/*)"]);
+  assert.deepEqual(merged.permissions.deny, ["Bash(rm -rf /)"]);
+});
+
+test("merge handles a missing settings file (fresh machine)", () => {
+  const merged = runMerge(null, MAESTRO_ADDITIONS);
+  assert.equal(merged.effortLevel, "high");
+  assert.equal(merged.enabledPlugins["claude-mem"], true);
+  assert.equal(merged.permissions, undefined);
+});
+
+test("merge handles invalid/corrupt existing JSON by starting fresh", () => {
+  const merged = runMerge("{ not valid json", MAESTRO_ADDITIONS);
+  assert.equal(merged.effortLevel, "high");
+  assert.equal(merged.permissions, undefined);
+});
+
+// --- static guards on the script source ------------------------------------
+
+test("init-agent.sh no longer wires unpinned ruflo@latest hooks", () => {
+  assert.ok(!/ruflo@latest/.test(scriptSrc), "ruflo@latest must be removed (supply-chain RCE)");
+  assert.ok(!/\bruflo\b/.test(scriptSrc), "no ruflo references should remain");
+});
+
+test("init-agent.sh additions contain no allow-all permissions or dangerous-skip", () => {
+  const m = scriptSrc.match(/MAESTRO_SETTINGS_ADDITIONS='([\s\S]*?)'\n/);
+  assert.ok(m, "MAESTRO_SETTINGS_ADDITIONS block not found");
+  const additions = JSON.parse(m[1]);
+  assert.equal(additions.permissions, undefined, "additions must not ship a permissions block");
+  assert.equal(additions.skipDangerousModePermissionPrompt, undefined,
+    "additions must not skip the dangerous-mode prompt");
+  assert.ok(!m[1].includes("Bash(*)"), "additions must not contain Bash(*) allow-all");
+});
+
+test("init-agent.sh chmods the .env to 600", () => {
+  assert.ok(/chmod 600 "\$ENV_FILE"/.test(scriptSrc),
+    "the agent .env must be chmod 600 after writing (no world-readable credentials)");
+});
+
+test("init-agent.sh deep-merges rather than cat>-overwriting settings.json", () => {
+  // The old destructive `cat > "$CLAUDE_SETTINGS"` heredoc must be gone.
+  assert.ok(!/cat > "\$CLAUDE_SETTINGS"/.test(scriptSrc),
+    "settings.json must be deep-merged, not overwritten via cat >");
+  assert.ok(scriptSrc.includes("node -e \"$MAESTRO_MERGE_NODE\""),
+    "the merge must run via the embedded node program");
+});

package/scripts/setup/init-archetype.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+/**
+ * init-archetype.mjs — agent-side init for the function × altitude archetype library.
+ *
+ * Run by `maestro upgrade` (auto:true) and the init wizard. Ensures the agent's
+ * config/agent.json carries a valid { function, altitude } pair, migrating a
+ * legacy single-axis `archetype` value (the six legacy archetypes ARE the six
+ * functions, so they map to { function: <same>, altitude: c-suite }). Resolves +
+ * validates the operating profile via the framework's archetypes/ library; fails
+ * closed if invalid. Idempotent — a no-op once normalised.
+ *
+ * Execution contract (see lib/feature-init.mjs runInitCommand): invoked with
+ * cwd = agent repo, env AGENT_ROOT / MAESTRO_ROOT set; the script itself may be
+ * the framework copy. We therefore load the resolver from MAESTRO_ROOT when set.
+ *
+ * @module scripts/setup/init-archetype
+ */
+
+"use strict";
+
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const MAESTRO_ROOT =
+  process.env.MAESTRO_ROOT && existsSync(join(process.env.MAESTRO_ROOT, "lib", "archetype.mjs"))
+    ? process.env.MAESTRO_ROOT
+    : resolve(here, "..", "..");
+const AGENT_ROOT = process.env.AGENT_ROOT || process.cwd();
+
+async function main() {
+  const arch = await import(pathToFileURL(join(MAESTRO_ROOT, "lib", "archetype.mjs")).href);
+  const { resolveArchetype, migrateLegacyArchetype, deriveLegacyArchetype, listFunctions, listAltitudes } = arch;
+
+  const cfgPath = join(AGENT_ROOT, "config", "agent.json");
+  if (!existsSync(cfgPath)) {
+    console.log(`[init-archetype] no config/agent.json at ${cfgPath} — skipping (run from an agent repo).`);
+    return 0;
+  }
+  const cfg = JSON.parse(readFileSync(cfgPath, "utf-8"));
+
+  let sel = null;
+  if (cfg.function && cfg.altitude) {
+    sel = { function: cfg.function, altitude: cfg.altitude };
+  } else if (cfg.archetype) {
+    sel = migrateLegacyArchetype(cfg.archetype);
+    if (sel) console.log(`[init-archetype] migrated legacy archetype "${cfg.archetype}" → ${sel.function} × ${sel.altitude}`);
+  }
+  if (!sel) {
+    console.error("[init-archetype] config/agent.json has no { function, altitude } and no legacy archetype.");
+    console.error(`  Set "function" to one of [${listFunctions().join(", ")}] and "altitude" to one of [${listAltitudes().join(", ")}].`);
+    return 1;
+  }
+
+  const profile = await resolveArchetype(sel); // throws if the resolved profile is invalid
+
+  if (cfg.function !== sel.function || cfg.altitude !== sel.altitude || cfg.archetype !== deriveLegacyArchetype(sel)) {
+    cfg.function = sel.function;
+    cfg.altitude = sel.altitude;
+    cfg.archetype = deriveLegacyArchetype(sel);
+    writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + "\n", "utf-8");
+    console.log("[init-archetype] normalised config/agent.json (function / altitude / archetype).");
+  }
+  console.log(`[init-archetype] OK — ${profile.label} (${profile.function} × ${profile.altitude})`);
+  return 0;
+}
+
+main()
+  .then((code) => process.exit(code))
+  .catch((err) => {
+    console.error(`[init-archetype] FAILED: ${err && err.message ? err.message : err}`);
+    process.exit(1);
+  });

package/scripts/setup/init-backup.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+/**
+ * init-backup.mjs — Off-machine state backup wizard.
+ *
+ * Configures `.maestro/backup-config.yaml` with bucket details and seeds
+ * a daily launchd plist that runs scripts/maintenance/backup-to-cloud.sh.
+ * Requires interactive input — does NOT auto-run.
+ */
+import { existsSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const AGENT_DIR = process.env.AGENT_ROOT || process.env.AGENT_DIR || resolve(__dirname, "..", "..");
+
+const ok = (m) => process.stdout.write(`[init-backup]  ✓ ${m}\n`);
+const warn = (m) => process.stdout.write(`[init-backup]  ⚠ ${m}\n`);
+
+mkdirSync(join(AGENT_DIR, ".maestro"), { recursive: true });
+const cfg = join(AGENT_DIR, ".maestro/backup-config.yaml");
+if (existsSync(cfg)) {
+  ok("backup-config.yaml already present");
+  process.exit(0);
+}
+
+writeFileSync(cfg, `# Off-machine state backup configuration
+# Fill in the bucket details, then run:
+#   maestro init backup-replication --apply
+#
+# Backups cover (configurable below):
+#   - state/   (queues, dashboards, inboxes — minus state/tmp/)
+#   - knowledge/
+#   - outputs/
+#   - logs/ (rotated archives only — current-day logs excluded)
+#   - config/agent.json (identity SOT)
+
+enabled: false
+provider: gcs            # gcs | s3 | rsync
+bucket: ""               # e.g. northwind-maestro-backups
+prefix: agent-name-here  # e.g. ravi-ai (typically the repoSlug)
+schedule: "0 3 * * *"    # daily 03:00 local (overrides via launchd plist)
+include:
+  - state
+  - knowledge
+  - outputs
+  - logs
+  - config/agent.json
+exclude:
+  - state/tmp
+  - state/rag/index/*.bin
+retention_days: 30
+`);
+ok(`wrote ${cfg}`);
+warn("Backup is configured but NOT enabled. Edit .maestro/backup-config.yaml + set enabled: true, then re-run init.");

package/scripts/setup/init-cadence-bus.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+/**
+ * init-cadence-bus.mjs — Idempotent init step for the cadence-bus feature.
+ *
+ * Called by `maestro init` / `maestro upgrade` (via the feature-init
+ * tracker). Safe to run repeatedly. Verifies state/cadence-bus/{inbox,
+ * claimed,processed,failed,dlq} exist + logs/cadence-bus/ exists +
+ * generated launchd plists are on the cadence-bus arch.
+ */
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const AGENT_DIR = process.env.AGENT_ROOT || process.env.AGENT_DIR || resolve(__dirname, "..", "..");
+
+const ok = (m) => process.stdout.write(`[init-cadence-bus]  ✓ ${m}\n`);
+const warn = (m) => process.stdout.write(`[init-cadence-bus]  ⚠ ${m}\n`);
+
+// Directory tree (mirror of cadence-bus.mjs's bootstrap).
+for (const d of [
+  "state/cadence-bus/inbox",
+  "state/cadence-bus/claimed",
+  "state/cadence-bus/processed",
+  "state/cadence-bus/failed",
+  "state/cadence-bus/dlq",
+  "logs/cadence-bus",
+]) {
+  const full = join(AGENT_DIR, d);
+  if (!existsSync(full)) {
+    mkdirSync(full, { recursive: true });
+    ok(`created ${d}`);
+  }
+}
+
+// Version marker file.
+const versionFile = join(AGENT_DIR, "state/cadence-bus/VERSION");
+if (!existsSync(versionFile)) {
+  writeFileSync(versionFile, "1\n");
+  ok("seeded state/cadence-bus/VERSION");
+}
+
+// Plist arch verification — flag (don't fix here, that's upgrade's job).
+const plistDir = join(AGENT_DIR, "scripts/local-triggers/plists");
+if (existsSync(plistDir)) {
+  let legacy = 0;
+  for (const name of readdirSync(plistDir)) {
+    if (!name.endsWith(".plist")) continue;
+    const body = readFileSync(join(plistDir, name), "utf-8");
+    if (body.includes("run-trigger.sh")) legacy++;
+  }
+  if (legacy > 0) {
+    warn(`${legacy} generated plist(s) still use the legacy spawn-per-tick pattern.`);
+    warn("  Run: npx @cohortapp/agent-sdk upgrade  (will back up + regenerate)");
+  } else {
+    ok("plist arch verified");
+  }
+}
+
+ok("done");

package/scripts/setup/init-channel-bus.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+/**
+ * init-channel-bus.mjs — Idempotent init for the channel-bus feature.
+ *
+ * Creates state/channels/ for any per-channel state, and verifies that
+ * lib/channels/ is present in the framework install. No-op if either
+ * already exist. The actual channel registration happens at daemon
+ * startup in scripts/daemon/maestro-daemon.mjs (which the framework
+ * upgrade will patch); this wizard only sets up the supporting
+ * filesystem layout.
+ */
+
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync, mkdirSync } from "node:fs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const AGENT_DIR = process.env.AGENT_ROOT || process.env.AGENT_DIR || resolve(__dirname, "..", "..");
+const MAESTRO_ROOT = process.env.MAESTRO_ROOT || resolve(__dirname, "..", "..");
+
+const ok = (m) => process.stdout.write(`[init-channel-bus]  ✓ ${m}\n`);
+const warn = (m) => process.stdout.write(`[init-channel-bus]  ⚠ ${m}\n`);
+const info = (m) => process.stdout.write(`[init-channel-bus]  · ${m}\n`);
+
+// Sanity: lib/channels/ must exist in the framework install.
+const channelsLib = join(MAESTRO_ROOT, "lib/channels/channel.mjs");
+if (!existsSync(channelsLib)) {
+  warn(`lib/channels/ not present in framework at ${MAESTRO_ROOT}`);
+  warn("Run `npm run upgrade` (maestro >= 1.12.0) and retry.");
+  process.exit(1);
+}
+
+for (const d of [
+  "state/channels",
+  "logs/channels",
+]) {
+  const full = join(AGENT_DIR, d);
+  if (!existsSync(full)) {
+    mkdirSync(full, { recursive: true });
+    ok(`created ${d}`);
+  }
+}
+
+info("channel bus ready. Channels register themselves at daemon startup —");
+info("see lib/channels/index.mjs and scripts/daemon/channel-bus.mjs.");
+ok("done");

package/scripts/setup/init-cost-tracking.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+/**
+ * init-cost-tracking.mjs — Set up local cost tracking ledger + dashboard.
+ *
+ * State:
+ *   state/cost-tracking/<date>.jsonl    — per-day token ledger
+ *   state/dashboards/cost-summary.yaml  — rollup
+ *
+ * The actual tracker is scripts/cost/track-claude-usage.mjs (shipped by the
+ * framework) which is wired into the cadence-consumer's session-spawn path.
+ */
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const AGENT_DIR = process.env.AGENT_ROOT || process.env.AGENT_DIR || resolve(__dirname, "..", "..");
+
+const ok = (m) => process.stdout.write(`[init-cost-tracking]  ✓ ${m}\n`);
+
+for (const d of ["state/cost-tracking", "state/dashboards"]) {
+  const full = join(AGENT_DIR, d);
+  if (!existsSync(full)) {
+    mkdirSync(full, { recursive: true });
+    ok(`created ${d}`);
+  }
+}
+
+const summary = join(AGENT_DIR, "state/dashboards/cost-summary.yaml");
+if (!existsSync(summary)) {
+  writeFileSync(summary, `# Cost summary — auto-regenerated by scripts/cost/track-claude-usage.mjs
+generated: null
+window_days: 7
+totals:
+  sessions: 0
+  input_tokens: 0
+  output_tokens: 0
+  estimated_usd: 0
+by_model: {}
+by_cadence: {}
+`);
+  ok("seeded cost-summary.yaml");
+}
+
+ok("done");

package/scripts/setup/init-decision-capture.mjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+/**
+ * init-decision-capture.mjs — Wire decision-capture automation.
+ *
+ * Ensures knowledge/decisions/{decision-schema,index}.yaml exist and
+ * creates scripts/decisions/capture-decision.mjs locally (the helper
+ * that the agent invokes when recording a decision).
+ */
+import { existsSync, mkdirSync, writeFileSync, copyFileSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const AGENT_DIR = process.env.AGENT_ROOT || process.env.AGENT_DIR || resolve(__dirname, "..", "..");
+const MAESTRO_ROOT = process.env.MAESTRO_ROOT || resolve(__dirname, "..", "..");
+
+const ok = (m) => process.stdout.write(`[init-decision-capture]  ✓ ${m}\n`);
+
+for (const d of ["knowledge/decisions", "knowledge/decisions/archive", "scripts/decisions"]) {
+  const full = join(AGENT_DIR, d);
+  if (!existsSync(full)) {
+    mkdirSync(full, { recursive: true });
+    ok(`created ${d}`);
+  }
+}
+
+// Copy the framework's capture-decision helper if present.
+const src = join(MAESTRO_ROOT, "scripts/decisions/capture-decision.mjs");
+const dst = join(AGENT_DIR, "scripts/decisions/capture-decision.mjs");
+if (existsSync(src) && !existsSync(dst)) {
+  copyFileSync(src, dst);
+  ok(`copied capture-decision.mjs`);
+}
+
+// Seed index.yaml + schema if missing.
+const schemaPath = join(AGENT_DIR, "knowledge/decisions/decision-schema.yaml");
+if (!existsSync(schemaPath)) {
+  writeFileSync(schemaPath, `# Decision Record Schema (Maestro decision-capture v1)
+# Each decision is a YAML doc named DEC-YYYY-MM-DD-NNN.yaml under knowledge/decisions/.
+
+schema:
+  version: "1"
+  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 }
+    alternatives:     { type: array,  required: false }
+    stakeholders:     { type: array,  required: false }
+    expires_at:       { type: date,   required: false }
+    status:           { type: string, enum: [active, superseded, reversed, completed], default: active }
+`);
+  ok("seeded decision-schema.yaml");
+}
+
+const indexPath = join(AGENT_DIR, "knowledge/decisions/index.yaml");
+if (!existsSync(indexPath)) {
+  writeFileSync(indexPath, "# Decision Index — auto-maintained by capture-decision.mjs\ndecisions: []\n");
+  ok("seeded decision index");
+}
+
+ok("done");

package/scripts/setup/init-known-agents.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+/**
+ * init-known-agents.mjs — Scaffold config/known-agents.json
+ *
+ * The Northwind agent roster is shipped as a starter; agents that have
+ * already populated their own known-agents.json keep theirs (this init
+ * step is idempotent and never overwrites).
+ *
+ * classifier.mjs reads this file at runtime to detect peer @mentions in
+ * Slack/Gmail so an agent doesn't respond to messages routed at another
+ * agent.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const AGENT_DIR = process.env.AGENT_ROOT || process.env.AGENT_DIR || resolve(__dirname, "..", "..");
+
+const ok = (m) => process.stdout.write(`[init-known-agents]  ✓ ${m}\n`);
+
+const TARGET = join(AGENT_DIR, "config", "known-agents.json");
+const MAESTRO_ROOT = process.env.MAESTRO_ROOT || resolve(__dirname, "..", "..");
+const SCAFFOLD = join(MAESTRO_ROOT, "scaffold", "config", "known-agents.json");
+
+mkdirSync(dirname(TARGET), { recursive: true });
+
+if (existsSync(TARGET)) {
+  // Already present — verify shape and exit. We don't merge upstream
+  // additions into existing files to avoid surprising the operator.
+  try {
+    const current = JSON.parse(readFileSync(TARGET, "utf-8"));
+    const count = Array.isArray(current.agents) ? current.agents.length : 0;
+    ok(`already present (${count} agents)`);
+    process.exit(0);
+  } catch (err) {
+    process.stderr.write(`[init-known-agents] existing file is invalid JSON: ${err.message}\n`);
+    process.exit(1);
+  }
+}
+
+// Copy from scaffold (the framework's canonical roster); fall back to a
+// minimal stub if the scaffold is missing.
+let payload;
+if (existsSync(SCAFFOLD)) {
+  payload = readFileSync(SCAFFOLD, "utf-8");
+  ok(`copied from ${SCAFFOLD}`);
+} else {
+  payload = JSON.stringify({
+    schema_version: "1",
+    agents: [],
+  }, null, 2) + "\n";
+  ok("scaffold not found — wrote empty roster");
+}
+
+writeFileSync(TARGET, payload);
+ok(`wrote ${TARGET}`);

package/scripts/setup/init-learning.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * init-learning.mjs — provision the self-learning loop (WS3) into an agent repo.
+ *
+ * Idempotent + auto-runnable (no TTY): used by `maestro upgrade` to roll WS3 into
+ * agents that predate it, and mirrors what lib/setup/sections/learning.mjs does
+ * for fresh installs. Seeds:
+ *   - config/learning.yaml          (copied from scaffold; never clobbers an
+ *                                    existing operator-customised file)
+ *   - state/learning/counters.json  (zero state for the nudge counters)
+ *   - state/learning/               (holds counters + the sessions.db FTS5 store)
+ *
+ * The actual skill-authoring runs out-of-band in the Stop-hook reflect worker;
+ * the global hook is wired by `maestro global-setup`, not here.
+ *
+ * @module scripts/setup/init-learning
+ */
+
+import { existsSync, mkdirSync, writeFileSync, copyFileSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const MAESTRO_ROOT =
+  process.env.MAESTRO_ROOT && existsSync(join(process.env.MAESTRO_ROOT, "scaffold"))
+    ? process.env.MAESTRO_ROOT
+    : resolve(__dirname, "..", "..");
+const AGENT_DIR = process.env.AGENT_ROOT || process.env.AGENT_DIR || resolve(__dirname, "..", "..");
+
+const ok = (m) => process.stdout.write(`[init-learning]  ✓ ${m}\n`);
+
+async function main() {
+  mkdirSync(join(AGENT_DIR, "state", "learning"), { recursive: true });
+  mkdirSync(join(AGENT_DIR, "config"), { recursive: true });
+
+  // 1. config/learning.yaml — from scaffold, never overwrite an existing file.
+  const cfgDst = join(AGENT_DIR, "config", "learning.yaml");
+  if (!existsSync(cfgDst)) {
+    const scaffold = join(MAESTRO_ROOT, "scaffold", "config", "learning.yaml");
+    if (existsSync(scaffold)) { copyFileSync(scaffold, cfgDst); ok("wrote config/learning.yaml (from scaffold)"); }
+    else {
+      writeFileSync(cfgDst, "# config/learning.yaml — Self-Learning Loop (WS3)\nenabled: true\nminTurns: 4\nreviewModel: sonnet\n");
+      ok("wrote config/learning.yaml (stub)");
+    }
+  }
+
+  // 2. state/learning/counters.json — zero state.
+  const countersDst = join(AGENT_DIR, "state", "learning", "counters.json");
+  if (!existsSync(countersDst)) {
+    try {
+      const { emptyCounters } = await import(resolve(MAESTRO_ROOT, "lib", "learning", "counters.mjs"));
+      writeFileSync(countersDst, JSON.stringify(emptyCounters(), null, 2) + "\n");
+    } catch {
+      writeFileSync(countersDst, JSON.stringify({ tool_uses_since_skill: 0, sessions_since_skill: 0, last_skill_at: null, last_reflect_at: null }, null, 2) + "\n");
+    }
+    ok("seeded state/learning/counters.json");
+  }
+
+  // 3. Best-effort: warm the transcript search index from existing session logs.
+  try {
+    const { ingestAll } = await import(resolve(MAESTRO_ROOT, "lib", "learning", "session-index.mjs"));
+    const r = await ingestAll({ agentRoot: AGENT_DIR });
+    if (r.files) ok(`indexed ${r.added} session transcript(s) into state/learning/sessions.db`);
+  } catch { /* on-demand store; non-fatal */ }
+
+  ok("done");
+  return 0;
+}
+
+main().then((c) => process.exit(c || 0)).catch((e) => { process.stderr.write(`[init-learning] ${e && e.message ? e.message : e}\n`); process.exit(1); });

package/scripts/setup/init-memory-executive.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+/**
+ * init-memory-executive.mjs — Create memory/executive/ + memory/workstreams/
+ * Referenced by agents/ceo-briefing/agent.md and several skill prompts.
+ *
+ * Seeds priorities.md and open-loops.md so morning-brief / evening-wrap
+ * don't fail on a missing file.
+ */
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const AGENT_DIR = process.env.AGENT_ROOT || process.env.AGENT_DIR || resolve(__dirname, "..", "..");
+
+const ok = (m) => process.stdout.write(`[init-memory-executive]  ✓ ${m}\n`);
+
+const DIRS = [
+  "memory/executive",
+  "memory/workstreams",
+];
+
+for (const d of DIRS) {
+  const full = join(AGENT_DIR, d);
+  if (!existsSync(full)) {
+    mkdirSync(full, { recursive: true });
+    ok(`created ${d}`);
+  }
+}
+
+const seeds = {
+  "memory/executive/priorities.md": "# Executive Priorities\n\nCurrent strategic priorities maintained by the agent. Updated weekly.\n\n_Populate via /init-maestro or by the weekly-priorities cadence._\n",
+  "memory/executive/open-loops.md": "# Open Loops\n\nOutstanding commitments awaiting closure. Updated by inbox-processor and evening-wrap cadences.\n\n_Format: each loop has owner, deadline, blocker, last-touched._\n",
+  "memory/workstreams/README.md": "# Workstreams\n\nOne markdown file per active workstream. Updated by the relevant cadence (weekly-execution, weekly-engineering-health, etc.) to reflect current status, blockers, and next milestones.\n",
+};
+
+for (const [path, body] of Object.entries(seeds)) {
+  const full = join(AGENT_DIR, path);
+  if (!existsSync(full)) {
+    writeFileSync(full, body);
+    ok(`seeded ${path}`);
+  }
+}
+
+ok("done");