@cohortapp/agent-sdk 2.3.2 → 2.4.0

package/scripts/setup/generate-plan.mjs

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+/**
+ * generate-plan.mjs — compile the agent's PLAN and emit its schedule.
+ *
+ * `(mandate cache ⊕ capability manifest ⊕ archetype profile ⊕ org context)`
+ *   → obligations
+ *   → config/plan.yaml + config/cadences.yaml + config/.cadence-registry.json
+ *     + config/.cadence-plists.tsv + state/plan/compile.lock
+ *   → scripts/local-triggers/generate-plists.sh   (REAL launchd jobs)
+ *
+ * This is the standalone door to the same code the `mandate` setup section runs,
+ * so `maestro upgrade` and a cron refresh can recompile a plan without the
+ * wizard. Pure + deterministic: identical inputs re-emit byte-identical files,
+ * so a no-op run churns no plists.
+ *
+ * Flags:
+ *   --derive        (re)derive a PROPOSED mandate before compiling
+ *   --no-plists     write the TSV but do not run generate-plists.sh
+ *   --enforcement=observe-only|active
+ *   --print         print the obligation table and exit without writing
+ *
+ * @module scripts/setup/generate-plan
+ */
+
+"use strict";
+
+import { 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", "plan", "compile.mjs"))
+    ? process.env.MAESTRO_ROOT
+    : resolve(here, "..", "..");
+const AGENT_ROOT = process.env.AGENT_ROOT || process.cwd();
+
+const load = (rel) => import(pathToFileURL(join(MAESTRO_ROOT, rel)).href);
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const wantDerive = argv.includes("--derive");
+  const printOnly = argv.includes("--print");
+  const enforcement = (argv.find((a) => a.startsWith("--enforcement=")) || "").split("=")[1] || "observe-only";
+
+  const section = await load("lib/setup/sections/mandate.mjs");
+  const cache = await load("lib/mandate/cache.mjs");
+  const compile = await load("lib/plan/compile.mjs");
+
+  const inputs = await section.loadCompilerInputs({ agentRoot: AGENT_ROOT, maestroRoot: MAESTRO_ROOT });
+  for (const d of inputs.degradations) console.warn(`[generate-plan] ${d.kind}: ${d.reason}`);
+
+  let record = cache.readCache(AGENT_ROOT);
+  if (wantDerive || !record) {
+    const res = await section.resolveMandate({ agentRoot: AGENT_ROOT, inputs }, { logImpl: (m) => console.warn(m) });
+    record = res.record;
+    if (res.derived) {
+      const c = res.derived.counts;
+      console.log(`[generate-plan] derived ${c.proposed} PROPOSED objectives (${c.withMethodSensor} with a method sensor). None are adopted — adopt in Cohort to activate.`);
+    }
+  }
+
+  if (printOnly) {
+    const plan = compile.compilePlan({
+      mandate: record.body || {}, mandateVersion: record.version || 0,
+      manifest: inputs.manifest || { entries: [] }, profile: inputs.profile, orgContext: inputs.orgContext,
+      standardCadences: inputs.standardCadences, archetypeCadences: inputs.archetypeCadences,
+    });
+    for (const ob of plan.obligations) {
+      const when = ob.schedule ? (ob.schedule.interval != null ? `every ${ob.schedule.interval}s` : JSON.stringify(ob.schedule.calendar)) : (ob.trigger ? `on ${ob.trigger.topic}.${ob.trigger.kind || "*"}` : "-");
+      console.log(`  ${ob.kind.padEnd(9)} ${ob.key.padEnd(40)} ${String(when).padEnd(34)} uses=[${(ob.uses || []).join(",")}]`);
+    }
+    console.log(`[generate-plan] ${plan.counts.total} obligations · obligationsHash ${plan.obligationsHash.slice(0, 16)} (dry run — nothing written)`);
+    return 0;
+  }
+
+  const { ok, plan, emit } = await section.compileAndEmit({
+    agentRoot: AGENT_ROOT, maestroRoot: MAESTRO_ROOT, inputs, record, enforcement,
+  }, { skipPlists: argv.includes("--no-plists") });
+
+  if (!ok) {
+    console.error("[generate-plan] plan FAILED validation — nothing written:");
+    for (const e of emit.errors.slice(0, 20)) console.error(`  - ${e}`);
+    return 1;
+  }
+
+  console.log(`[generate-plan] ${plan.counts.total} obligations (${plan.counts.SCHEDULE} SCHEDULE · ${plan.counts.OUTCOME} OUTCOME · ${plan.counts.REACT} REACT)`);
+  console.log(`[generate-plan]   from ${plan.counts.adoptedObjectives} adopted / ${plan.counts.proposedObjectives} proposed objectives · obligationsHash ${plan.obligationsHash.slice(0, 16)}`);
+  console.log(`[generate-plan]   wrote ${emit.files.length} files; ${emit.tsv.length} archetype/mandate plist entries`);
+  for (const d of plan.drift) console.warn(`[generate-plan] drift ${d.kind}${d.key ? ` (${d.key})` : ""}: ${JSON.stringify(d.detail)}`);
+
+  if (!argv.includes("--no-plists")) {
+    const gen = await load("lib/setup/run-generator.mjs");
+    const plistGen = join(AGENT_ROOT, "scripts", "local-triggers", "generate-plists.sh");
+    if (existsSync(plistGen)) {
+      const pr = gen.runScriptAbs(plistGen, AGENT_ROOT, { bash: true, maestroRoot: MAESTRO_ROOT });
+      if (!pr.ok) console.warn(`[generate-plan] generate-plists.sh did not complete: ${(pr.stderr || "").trim().slice(0, 300)}`);
+      else console.log("[generate-plan]   launchd plists regenerated");
+    } else {
+      console.warn("[generate-plan] no scripts/local-triggers/generate-plists.sh — TSV written, launchd jobs not emitted");
+    }
+  }
+  return 0;
+}
+
+main()
+  .then((c) => process.exit(c))
+  .catch((e) => { console.error(`[generate-plan] FAILED: ${e && e.message ? e.message : e}`); process.exit(1); });

package/scripts/setup/init-capability-manifest.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * init-capability-manifest.mjs — build/refresh config/capability-manifest.json.
+ *
+ * The standalone entry point for the capability inventory, so an EXISTING agent
+ * picks the feature up via `maestro upgrade` (framework-features.json →
+ * `capability-manifest`, auto:true) without re-running the whole wizard. Same
+ * code path as the `inventory` setup section — one implementation, two doors.
+ *
+ * Idempotent: re-running with nothing changed rewrites the same manifest with a
+ * new `generatedAt` and the SAME `checksum`, so downstream compilers can tell
+ * "nothing moved".
+ *
+ * Flags:
+ *   --repair     register the skill marketplaces + enable the plugins (default)
+ *   --no-repair  probe only; never write outside config/
+ *   --quiet
+ *
+ * Execution contract mirrors the other generators: cwd = agent repo, with
+ * MAESTRO_ROOT / AGENT_ROOT in env.
+ *
+ * @module scripts/setup/init-capability-manifest
+ */
+
+"use strict";
+
+import { 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", "capability", "inventory.mjs"))
+    ? process.env.MAESTRO_ROOT
+    : resolve(here, "..", "..");
+const AGENT_ROOT = process.env.AGENT_ROOT || process.cwd();
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const repair = !argv.includes("--no-repair");
+  const quiet = argv.includes("--quiet");
+
+  const inv = await import(pathToFileURL(join(MAESTRO_ROOT, "lib", "capability", "inventory.mjs")).href);
+  const sot = await import(pathToFileURL(join(MAESTRO_ROOT, "lib", "setup", "sot.mjs")).href);
+
+  let archetype = null;
+  try {
+    const cfg = sot.readAgentJson(AGENT_ROOT) || {};
+    if (cfg.function && cfg.altitude) archetype = { function: cfg.function, altitude: cfg.altitude };
+  } catch { /* identity section owns this gap; the inventory records it as a degradation */ }
+
+  const manifest = await inv.buildInventory(
+    { agentRoot: AGENT_ROOT, maestroRoot: MAESTRO_ROOT, archetype, repair },
+    { logImpl: quiet ? () => {} : (m) => console.warn(m) },
+  );
+  const path = inv.writeManifest(AGENT_ROOT, manifest);
+
+  const c = manifest.counts || {};
+  console.log(`[capability-manifest] ${manifest.entries.length} capabilities · ${c.reachable} reachable · ${c.unreachable} unreachable`);
+  console.log(`[capability-manifest]   builtin ${c.builtin} · skill ${c.skill} · mcp ${c.mcp} · org ${c.org}`);
+  console.log(`[capability-manifest]   checksum ${manifest.checksum.slice(0, 16)} → ${path}`);
+  if ((manifest.degradations || []).length) {
+    console.log(`[capability-manifest]   ${manifest.degradations.length} degradation(s) — unreachable capabilities may not back any obligation.`);
+  }
+  return 0;
+}
+
+main()
+  .then((c) => process.exit(c))
+  .catch((e) => { console.error(`[capability-manifest] FAILED: ${e && e.message ? e.message : e}`); process.exit(1); });

package/scripts/setup/init-skill-marketplace.mjs

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+/**
+ * init-skill-marketplace.mjs — make the agent's SKILL files actually invocable.
+ *
+ * Rung 1 of the execution ladder ("repeatable procedure, 2-10 calls, a skill
+ * exists in the manifest with reachable:true") was a LIE: maestro ships dozens of
+ * skill markdown files under `plugins/<id>/skills/`, but Claude Code only loads a
+ * skill when its plugin is (a) declared by a `.claude-plugin/marketplace.json`
+ * and (b) listed in `~/.claude/settings.json` `enabledPlugins`. Neither was ever
+ * written, so every one of those files was an orphan — present on disk, dead at
+ * runtime, and silently so.
+ *
+ * This is the standalone repair door, so an EXISTING agent picks it up through
+ * `maestro upgrade` (framework-features.json → `skill-marketplace`, auto:true)
+ * without re-running the wizard. It shares ONE implementation with the
+ * `inventory` setup section — `lib/capability/probe.probeSkillPlugin({repair})`
+ * — rather than growing a second registration mechanism beside it.
+ *
+ * Idempotent: an already-registered, already-enabled plugin is left untouched and
+ * reported as such. Fail-open but NEVER silent — a plugin that cannot be repaired
+ * is printed with its reason and leaves its skills `reachable:false`, which the
+ * plan compiler then refuses to cite.
+ *
+ * Flags:
+ *   --dry-run   report what WOULD be registered; write nothing
+ *   --quiet
+ *
+ * Execution contract mirrors the other generators: cwd = agent repo, with
+ * MAESTRO_ROOT / AGENT_ROOT in env.
+ *
+ * @module scripts/setup/init-skill-marketplace
+ */
+
+"use strict";
+
+import { existsSync, readdirSync } 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", "capability", "probe.mjs"))
+    ? process.env.MAESTRO_ROOT
+    : resolve(here, "..", "..");
+const AGENT_ROOT = process.env.AGENT_ROOT || process.cwd();
+
+/**
+ * Every plugin directory that carries at least one skill file, across the agent
+ * repo and the framework repo. Pure + injectable so the test does not need a
+ * real plugin tree.
+ * @param {{roots:string[]}} o
+ * @param {{existsSync?:Function, readdirSync?:Function}} [deps]
+ * @returns {Array<{pluginId:string, pluginDir:string, skills:string[]}>}
+ */
+export function findSkillPlugins(o = {}, deps = {}) {
+  const ex = deps.existsSync || existsSync;
+  const rdd = deps.readdirSync || readdirSync;
+  const out = [];
+  const seen = new Set();
+
+  for (const root of (o.roots || []).filter(Boolean)) {
+    const pluginsDir = join(root, "plugins");
+    if (!ex(pluginsDir)) continue;
+    let ids = [];
+    try {
+      ids = rdd(pluginsDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name).sort();
+    } catch {
+      continue; // the inventory records the unreadable-dir degradation
+    }
+    for (const pluginId of ids) {
+      if (seen.has(pluginId)) continue;
+      const pluginDir = join(pluginsDir, pluginId);
+      const skillsDir = join(pluginDir, "skills");
+      if (!ex(skillsDir)) continue;
+      let skills = [];
+      try { skills = rdd(skillsDir).filter((f) => String(f).endsWith(".md")).sort(); } catch { skills = []; }
+      if (!skills.length) continue;
+      seen.add(pluginId);
+      out.push({ pluginId, pluginDir, skills });
+    }
+  }
+  return out;
+}
+
+/**
+ * Register + enable every skill plugin found. Returns a per-plugin report.
+ * @param {object} o - { agentRoot, maestroRoot, dryRun? }
+ * @param {object} [deps] - { probeSkillPlugin, existsSync, readdirSync, ... }
+ * @returns {Promise<{plugins:Array, repaired:string[], failed:Array, skillCount:number}>}
+ */
+export async function registerMarketplaces(o = {}, deps = {}) {
+  const probeSkillPlugin = deps.probeSkillPlugin
+    || (await import(pathToFileURL(join(o.maestroRoot || MAESTRO_ROOT, "lib", "capability", "probe.mjs")).href)).probeSkillPlugin;
+
+  const found = findSkillPlugins({ roots: [o.agentRoot, o.maestroRoot] }, deps);
+  const plugins = [];
+  const repaired = [];
+  const failed = [];
+  let skillCount = 0;
+
+  for (const p of found) {
+    skillCount += p.skills.length;
+    const verdict = probeSkillPlugin({ pluginDir: p.pluginDir, pluginId: p.pluginId, repair: !o.dryRun }, deps);
+    const row = {
+      pluginId: p.pluginId,
+      skills: p.skills.length,
+      ok: !!verdict.ok,
+      detail: verdict.detail || null,
+      degraded: verdict.degraded || null,
+      repaired: Array.isArray(verdict.repaired) ? verdict.repaired : [],
+    };
+    plugins.push(row);
+    for (const r of row.repaired) repaired.push(`${p.pluginId}: ${r}`);
+    if (!row.ok) failed.push(row);
+  }
+
+  return { plugins, repaired, failed, skillCount };
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const dryRun = argv.includes("--dry-run");
+  const quiet = argv.includes("--quiet");
+  const log = quiet ? () => {} : (m) => console.log(m);
+
+  const res = await registerMarketplaces({ agentRoot: AGENT_ROOT, maestroRoot: MAESTRO_ROOT, dryRun });
+
+  if (!res.plugins.length) {
+    console.log("[skill-marketplace] no plugin directories carry skill files — nothing to register");
+    return 0;
+  }
+
+  const reachable = res.plugins.filter((p) => p.ok);
+  log(`[skill-marketplace] ${reachable.length}/${res.plugins.length} skill plugins registered + enabled (${res.skillCount} skill files)${dryRun ? "  [DRY RUN — nothing written]" : ""}`);
+  for (const p of res.plugins) {
+    log(`[skill-marketplace]   ${p.ok ? "ok  " : "FAIL"} ${p.pluginId.padEnd(20)} ${p.skills} skill(s)${p.ok ? "" : ` — ${p.degraded}: ${p.detail}`}`);
+  }
+  for (const r of res.repaired) log(`[skill-marketplace]   repaired: ${r}`);
+
+  if (res.failed.length) {
+    // Loud, but not fatal: an un-registerable plugin leaves its skills
+    // reachable:false, and the plan compiler already refuses to cite those.
+    console.warn(`[skill-marketplace] ${res.failed.length} plugin(s) could not be registered — their skills stay unreachable and may not back any obligation.`);
+  }
+  return 0;
+}
+
+// Only run when invoked directly (so the test can import the helpers).
+if (process.argv[1] && resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url))) {
+  main()
+    .then((c) => process.exit(c))
+    .catch((e) => { console.error(`[skill-marketplace] FAILED: ${e && e.message ? e.message : e}`); process.exit(1); });
+}
+
+export default { findSkillPlugins, registerMarketplaces };

package/scripts/setup/init-skill-marketplace.test.mjs

@@ -0,0 +1,193 @@
+/**
+ * init-skill-marketplace.test.mjs — rung 1 of the execution ladder.
+ * Run: node --test scripts/setup/init-skill-marketplace.test.mjs
+ *
+ * The regression under guard: skill markdown files shipped under
+ * `plugins/<id>/skills/*.md` are DEAD at runtime unless their plugin is declared
+ * by a `.claude-plugin/marketplace.json` and enabled in `~/.claude/settings.json`.
+ * They were neither, and nothing said so. These tests use an injected
+ * `probeSkillPlugin` and an injected fs so no real plugin dir or operator
+ * settings file is ever touched.
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { findSkillPlugins, registerMarketplaces } from "./init-skill-marketplace.mjs";
+
+/** An injected fs describing a plugin tree, without creating one. */
+function fakeFs(tree) {
+  return {
+    existsSync: (p) => Object.prototype.hasOwnProperty.call(tree, String(p)),
+    readdirSync: (p, opts) => {
+      const v = tree[String(p)];
+      if (!Array.isArray(v)) throw new Error(`ENOTDIR ${p}`);
+      if (opts && opts.withFileTypes) return v.map((n) => ({ name: n, isDirectory: () => !String(n).endsWith(".md") }));
+      return v;
+    },
+  };
+}
+
+test("findSkillPlugins discovers plugins across BOTH the agent repo and the framework", () => {
+  const deps = fakeFs({
+    "/agent/plugins": ["agent-skills"],
+    "/agent/plugins/agent-skills": ["skills"],
+    "/agent/plugins/agent-skills/skills": ["morning-brief.md", "outreach.md"],
+    "/fw/plugins": ["maestro-skills"],
+    "/fw/plugins/maestro-skills": ["skills"],
+    "/fw/plugins/maestro-skills/skills": ["triage.md"],
+  });
+  const found = findSkillPlugins({ roots: ["/agent", "/fw"] }, deps);
+  assert.deepEqual(found.map((p) => p.pluginId), ["agent-skills", "maestro-skills"]);
+  assert.deepEqual(found[0].skills, ["morning-brief.md", "outreach.md"]);
+  assert.equal(found[1].skills.length, 1);
+});
+
+test("findSkillPlugins ignores plugin dirs that carry no skill files", () => {
+  const deps = fakeFs({
+    "/agent/plugins": ["hooks-only", "agent-skills"],
+    "/agent/plugins/hooks-only": ["hooks"],
+    "/agent/plugins/agent-skills": ["skills"],
+    "/agent/plugins/agent-skills/skills": ["a.md"],
+  });
+  const found = findSkillPlugins({ roots: ["/agent"] }, deps);
+  assert.deepEqual(found.map((p) => p.pluginId), ["agent-skills"]);
+});
+
+test("findSkillPlugins: the agent repo wins a plugin-id collision, and no root is required", () => {
+  const deps = fakeFs({
+    "/agent/plugins": ["agent-skills"],
+    "/agent/plugins/agent-skills": ["skills"],
+    "/agent/plugins/agent-skills/skills": ["local.md"],
+    "/fw/plugins": ["agent-skills"],
+    "/fw/plugins/agent-skills": ["skills"],
+    "/fw/plugins/agent-skills/skills": ["framework.md", "another.md"],
+  });
+  const found = findSkillPlugins({ roots: ["/agent", "/fw"] }, deps);
+  assert.equal(found.length, 1, "the id is de-duplicated");
+  assert.deepEqual(found[0].skills, ["local.md"], "the agent's own copy wins");
+  // A missing plugins dir is a no-op, not a throw.
+  assert.deepEqual(findSkillPlugins({ roots: ["/nothing/here"] }, deps), []);
+  assert.deepEqual(findSkillPlugins({}, deps), []);
+});
+
+test("registerMarketplaces repairs every plugin and reports what it wrote", async () => {
+  const calls = [];
+  const deps = {
+    ...fakeFs({
+      "/agent/plugins": ["agent-skills"],
+      "/agent/plugins/agent-skills": ["skills"],
+      "/agent/plugins/agent-skills/skills": ["a.md", "b.md"],
+    }),
+    probeSkillPlugin: (o) => {
+      calls.push(o);
+      return { ok: true, detail: "marketplace+enabledPlugins", repaired: ["wrote .claude-plugin/marketplace.json", "enabled in settings.json"] };
+    },
+  };
+  const res = await registerMarketplaces({ agentRoot: "/agent", maestroRoot: "/fw" }, deps);
+
+  assert.equal(calls.length, 1);
+  assert.equal(calls[0].repair, true, "a non-dry run repairs");
+  assert.equal(calls[0].pluginId, "agent-skills");
+  assert.equal(res.skillCount, 2);
+  assert.equal(res.failed.length, 0);
+  assert.deepEqual(res.repaired, [
+    "agent-skills: wrote .claude-plugin/marketplace.json",
+    "agent-skills: enabled in settings.json",
+  ]);
+});
+
+test("--dry-run probes but never repairs", async () => {
+  const calls = [];
+  const deps = {
+    ...fakeFs({
+      "/agent/plugins": ["agent-skills"],
+      "/agent/plugins/agent-skills": ["skills"],
+      "/agent/plugins/agent-skills/skills": ["a.md"],
+    }),
+    probeSkillPlugin: (o) => { calls.push(o); return { ok: false, degraded: "marketplace-missing", detail: "no manifest", repaired: [] }; },
+  };
+  const res = await registerMarketplaces({ agentRoot: "/agent", maestroRoot: "/fw", dryRun: true }, deps);
+  assert.equal(calls[0].repair, false, "dry run must not write");
+  assert.equal(res.repaired.length, 0);
+});
+
+test("a plugin that cannot be repaired is reported LOUDLY, never swallowed", async () => {
+  const deps = {
+    ...fakeFs({
+      "/agent/plugins": ["good", "broken"],
+      "/agent/plugins/good": ["skills"],
+      "/agent/plugins/good/skills": ["a.md"],
+      "/agent/plugins/broken": ["skills"],
+      "/agent/plugins/broken/skills": ["b.md", "c.md"],
+    }),
+    probeSkillPlugin: (o) => (o.pluginId === "broken"
+      ? { ok: false, degraded: "marketplace-unwritable", detail: "EACCES", repaired: [] }
+      : { ok: true, detail: "ok", repaired: [] }),
+  };
+  const res = await registerMarketplaces({ agentRoot: "/agent", maestroRoot: "/fw" }, deps);
+
+  assert.equal(res.failed.length, 1);
+  assert.equal(res.failed[0].pluginId, "broken");
+  assert.equal(res.failed[0].degraded, "marketplace-unwritable");
+  assert.equal(res.failed[0].detail, "EACCES");
+  // Its skills stay unreachable, which is what the plan compiler then refuses to cite.
+  assert.equal(res.plugins.find((p) => p.pluginId === "broken").ok, false);
+  assert.equal(res.plugins.find((p) => p.pluginId === "good").ok, true);
+});
+
+test("idempotent: a second run over an already-registered plugin writes nothing new", async () => {
+  let registered = false;
+  const deps = {
+    ...fakeFs({
+      "/agent/plugins": ["agent-skills"],
+      "/agent/plugins/agent-skills": ["skills"],
+      "/agent/plugins/agent-skills/skills": ["a.md"],
+    }),
+    probeSkillPlugin: () => {
+      const repaired = registered ? [] : ["wrote marketplace.json"];
+      registered = true;
+      return { ok: true, detail: "ok", repaired };
+    },
+  };
+  const first = await registerMarketplaces({ agentRoot: "/agent" }, deps);
+  const second = await registerMarketplaces({ agentRoot: "/agent" }, deps);
+  assert.equal(first.repaired.length, 1);
+  assert.equal(second.repaired.length, 0, "no churn on a no-op re-run");
+  assert.deepEqual(first.plugins.map((p) => p.pluginId), second.plugins.map((p) => p.pluginId));
+});
+
+test("the REAL probe writes a valid marketplace manifest into a scratch plugin dir", async () => {
+  // One end-to-end pass against the actual probe, in a tmp tree, to prove the
+  // injected contract above matches the real implementation's shape.
+  const root = mkdtempSync(join(tmpdir(), "maestro-skillmkt-"));
+  const home = mkdtempSync(join(tmpdir(), "maestro-skillhome-"));
+  mkdirSync(join(root, "plugins", "agent-skills", "skills"), { recursive: true });
+  writeFileSync(join(root, "plugins", "agent-skills", "skills", "morning-brief.md"), "# morning-brief\n");
+
+  const { probeSkillPlugin } = await import("../../lib/capability/probe.mjs");
+  const res = await registerMarketplaces(
+    { agentRoot: root, maestroRoot: root },
+    { probeSkillPlugin: (o, d) => probeSkillPlugin(o, { ...d, homeDir: home }) },
+  );
+
+  assert.equal(res.plugins.length, 1);
+  assert.equal(res.skillCount, 1);
+  const manifestPath = join(root, "plugins", "agent-skills", ".claude-plugin", "marketplace.json");
+  assert.ok(existsSync(manifestPath), "the marketplace manifest was written");
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+  assert.equal(manifest.name, "agent-skills");
+  assert.ok(Array.isArray(manifest.plugins) && manifest.plugins.length === 1);
+});
+
+test("the feature is registered in framework-features.json so `maestro upgrade` picks it up", async () => {
+  const features = JSON.parse(readFileSync(new URL("../../framework-features.json", import.meta.url), "utf-8"));
+  const f = (features.features || features)["skill-marketplace"];
+  assert.ok(f, "skill-marketplace feature entry exists");
+  assert.equal(f.init.auto, true, "it is an auto migration (idempotent, ~instant)");
+  assert.match(f.init.command, /init-skill-marketplace\.mjs/);
+});