@a5c-ai/babysitter-opencode 5.0.1-staging.d73033a7 → 5.0.1-staging.daf8e165bc4a

package/bin/install.cjs

@@ -1,146 +1,4 @@
 #!/usr/bin/env node
 'use strict';
 
-/**
- * Babysitter OpenCode Plugin Installer
- *
- * Copies the babysitter plugin bundle into the OpenCode plugins directory:
- *   <workspace>/.opencode/plugins/babysitter/
- *
- * Registers hooks in OpenCode config, creates the index.js entry point
- * for plugin discovery, and bootstraps the global process library.
- *
- * Usage:
- *   node install.cjs                     # Install into cwd workspace
- *   node install.cjs --workspace /path   # Install into specified workspace
- *   node install.cjs --global            # Global install (user home)
- *   node install.cjs --accomplish        # Install only to Accomplish AI data dir
- */
-
-const path = require('path');
-const {
-  copyPluginBundle,
-  ensureGlobalProcessLibrary,
-  ensureMarketplaceEntry,
-  getAccomplishOpenCodeHome,
-  getHomeMarketplacePath,
-  getHomePluginRoot,
-  getOpenCodeHome,
-  installAccomplishSurface,
-  installOpenCodeSurface,
-  isAccomplishInstalled,
-  writeIndexJs,
-} = require('./install-shared.cjs');
-
-const PACKAGE_ROOT = path.resolve(__dirname, '..');
-
-function parseArgs(argv) {
-  let workspace = process.env.OPENCODE_WORKSPACE || process.cwd();
-  let accomplish = false;
-  for (let i = 2; i < argv.length; i += 1) {
-    const arg = argv[i];
-    if (arg === '--workspace') {
-      const next = argv[i + 1];
-      workspace = next && !next.startsWith('-') ? path.resolve(argv[++i]) : process.cwd();
-      continue;
-    }
-    if (arg === '--global') {
-      workspace = null;
-      continue;
-    }
-    if (arg === '--accomplish') {
-      accomplish = true;
-      continue;
-    }
-    throw new Error(`unknown argument: ${arg}`);
-  }
-  return { workspace, accomplish };
-}
-
-function installStandardOpenCode(workspace) {
-  const openCodeHome = getOpenCodeHome(workspace);
-  const pluginRoot = getHomePluginRoot(workspace);
-  const marketplacePath = getHomeMarketplacePath(workspace);
-
-  console.log(`[babysitter] Installing OpenCode plugin to ${pluginRoot}`);
-
-  // 1. Copy plugin bundle
-  copyPluginBundle(PACKAGE_ROOT, pluginRoot);
-  console.log('[babysitter]   Copied plugin bundle');
-
-  // 2. Write index.js entry point for OpenCode plugin discovery
-  writeIndexJs(pluginRoot);
-  console.log('[babysitter]   Created index.js entry point');
-
-  // 3. Register in marketplace
-  ensureMarketplaceEntry(marketplacePath, pluginRoot);
-  console.log(`[babysitter]   Marketplace: ${marketplacePath}`);
-
-  // 4. Install OpenCode surfaces (skills, hooks config)
-  installOpenCodeSurface(PACKAGE_ROOT, openCodeHome);
-  console.log('[babysitter]   Installed hooks and skills');
-
-  // 5. Bootstrap global process library
-  try {
-    const active = ensureGlobalProcessLibrary(PACKAGE_ROOT);
-    console.log(`[babysitter]   Process library: ${active.binding?.dir || '(default)'}`);
-    if (active.defaultSpec?.cloneDir) {
-      console.log(`[babysitter]   Process library clone: ${active.defaultSpec.cloneDir}`);
-    }
-    console.log(`[babysitter]   Process library state: ${active.stateFile}`);
-  } catch (err) {
-    console.warn(`[babysitter]   Warning: Could not bootstrap process library: ${err.message}`);
-    console.warn('[babysitter]   Run "babysitter process-library:clone" manually if needed.');
-  }
-}
-
-function installToAccomplish() {
-  const accomplishHome = getAccomplishOpenCodeHome();
-  console.log(`[babysitter] Installing plugin to Accomplish AI: ${accomplishHome}`);
-
-  installAccomplishSurface(PACKAGE_ROOT, accomplishHome);
-
-  console.log('[babysitter]   Copied plugin bundle to Accomplish');
-  console.log('[babysitter]   Created index.js entry point for Accomplish');
-  console.log('[babysitter]   Installed hooks and skills for Accomplish');
-  console.log('[babysitter] Accomplish AI installation complete.');
-  console.log('[babysitter] Restart Accomplish to pick up the installed plugin.');
-}
-
-function main() {
-  const { workspace, accomplish } = parseArgs(process.argv);
-
-  try {
-    // If --accomplish is used without --global/--workspace, install only to Accomplish
-    if (accomplish && workspace !== null) {
-      installToAccomplish();
-      return;
-    }
-
-    // Standard OpenCode install
-    installStandardOpenCode(workspace);
-
-    // Auto-detect Accomplish and install there too (unless --accomplish was explicit)
-    if (!accomplish) {
-      try {
-        if (isAccomplishInstalled()) {
-          console.log('[babysitter] Detected Accomplish AI installation.');
-          installToAccomplish();
-        }
-      } catch (err) {
-        console.warn(`[babysitter]   Warning: Accomplish AI detection failed: ${err.message}`);
-      }
-    } else {
-      // --accomplish combined with --global: install to both
-      installToAccomplish();
-    }
-
-    console.log('[babysitter] Installation complete!');
-    console.log('[babysitter] Restart OpenCode to pick up the installed plugin.');
-  } catch (err) {
-    console.error(`[babysitter] Failed to install plugin: ${err.message}`);
-    process.exitCode = 1;
-  }
-}
-
-main();
+require('./install.js');

package/bin/install.js

@@ -1,110 +1,30 @@
 #!/usr/bin/env node
-/**
- * Babysitter OpenCode Plugin Installer
- *
- * Copies plugin files into the OpenCode plugins directory:
- *   .opencode/plugins/babysitter/
- *
- * OpenCode discovers plugins as JS/TS modules in .opencode/plugins/.
- * This installer creates the necessary directory structure and copies
- * hook scripts, skills, and an index.js entry point.
- */
+'use strict';
 
-"use strict";
+const path = require('path');
+const shared = require('./install-shared');
 
-const fs = require("fs");
-const path = require("path");
-
-const PLUGIN_ROOT = path.resolve(__dirname, "..");
-const WORKSPACE = process.env.OPENCODE_WORKSPACE || process.cwd();
-const TARGET_DIR = path.join(WORKSPACE, ".opencode", "plugins", "babysitter");
-
-function copyRecursive(src, dest) {
-  const stat = fs.statSync(src);
-  if (stat.isDirectory()) {
-    fs.mkdirSync(dest, { recursive: true });
-    for (const entry of fs.readdirSync(src)) {
-      copyRecursive(path.join(src, entry), path.join(dest, entry));
-    }
-  } else {
-    fs.mkdirSync(path.dirname(dest), { recursive: true });
-    fs.copyFileSync(src, dest);
-  }
-}
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
 
 function main() {
-  console.log(`Installing babysitter plugin for OpenCode...`);
-  console.log(`  Source: ${PLUGIN_ROOT}`);
-  console.log(`  Target: ${TARGET_DIR}`);
+  const pluginRoot = shared.getHomePluginRoot();
+  const marketplacePath = shared.getHomeMarketplacePath();
 
-  // Create target directory
-  fs.mkdirSync(TARGET_DIR, { recursive: true });
+  console.log(`[${shared.PLUGIN_NAME}] Installing plugin to ${pluginRoot}`);
 
-  // Copy hooks
-  const hooksDir = path.join(PLUGIN_ROOT, "hooks");
-  if (fs.existsSync(hooksDir)) {
-    copyRecursive(hooksDir, path.join(TARGET_DIR, "hooks"));
-    console.log("  Copied hooks/");
-  }
-
-  // Copy skills
-  const skillsDir = path.join(PLUGIN_ROOT, "skills");
-  if (fs.existsSync(skillsDir)) {
-    copyRecursive(skillsDir, path.join(TARGET_DIR, "skills"));
-    console.log("  Copied skills/");
-  }
-
-  // Copy commands
-  const commandsDir = path.join(PLUGIN_ROOT, "commands");
-  if (fs.existsSync(commandsDir)) {
-    copyRecursive(commandsDir, path.join(TARGET_DIR, "commands"));
-    console.log("  Copied commands/");
-  }
-
-  // Copy plugin.json and versions.json
-  for (const file of ["plugin.json", "versions.json"]) {
-    const src = path.join(PLUGIN_ROOT, file);
-    if (fs.existsSync(src)) {
-      fs.copyFileSync(src, path.join(TARGET_DIR, file));
-      console.log(`  Copied ${file}`);
+  try {
+    shared.copyPluginBundle(PACKAGE_ROOT, pluginRoot);
+    shared.ensureMarketplaceEntry(marketplacePath, pluginRoot);
+    if (typeof shared.harnessInstall === 'function') {
+      shared.harnessInstall(PACKAGE_ROOT, pluginRoot);
     }
+    shared.runPostInstall && shared.runPostInstall(pluginRoot);
+    console.log(`[${shared.PLUGIN_NAME}] Installation complete!`);
+    console.log(`[${shared.PLUGIN_NAME}] Restart your IDE/CLI to pick up the plugin.`);
+  } catch (err) {
+    console.error(`[${shared.PLUGIN_NAME}] Failed to install: ${err.message}`);
+    process.exitCode = 1;
   }
-
-  // Create index.js entry point for OpenCode plugin discovery
-  const indexContent = `#!/usr/bin/env node
-/**
- * Babysitter plugin entry point for OpenCode.
- *
- * OpenCode discovers plugins by looking for JS/TS modules in
- * .opencode/plugins/. This file registers the babysitter hooks
- * with the OpenCode plugin system.
- */
-
-"use strict";
-
-const path = require("path");
-
-const PLUGIN_DIR = __dirname;
-
-module.exports = {
-  name: "babysitter",
-  version: require(path.join(PLUGIN_DIR, "plugin.json")).version,
-
-  hooks: {
-    "session.created": require(path.join(PLUGIN_DIR, "hooks", "session-created.js")),
-    "session.idle": require(path.join(PLUGIN_DIR, "hooks", "session-idle.js")),
-    "shell.env": require(path.join(PLUGIN_DIR, "hooks", "shell-env.js")),
-    "tool.execute.before": require(path.join(PLUGIN_DIR, "hooks", "tool-execute-before.js")),
-    "tool.execute.after": require(path.join(PLUGIN_DIR, "hooks", "tool-execute-after.js")),
-  },
-};
-`;
-
-  fs.writeFileSync(path.join(TARGET_DIR, "index.js"), indexContent);
-  console.log("  Created index.js");
-
-  console.log(`\nBabysitter plugin installed to ${TARGET_DIR}`);
-  console.log("Restart OpenCode to activate the plugin.");
 }
 
 main();

package/bin/uninstall.cjs

@@ -1,90 +1,4 @@
 #!/usr/bin/env node
 'use strict';
 
-/**
- * Babysitter OpenCode Plugin Uninstaller
- *
- * Removes the babysitter plugin from the OpenCode plugins directory
- * and cleans up hooks config and marketplace entries.
- *
- * Usage:
- *   node uninstall.cjs                     # Uninstall from cwd workspace
- *   node uninstall.cjs --workspace /path   # Uninstall from specified workspace
- *   node uninstall.cjs --global            # Global uninstall
- */
-
-const fs = require('fs');
-const path = require('path');
-const {
-  getHomeMarketplacePath,
-  getHomePluginRoot,
-  getOpenCodeHome,
-  removeManagedHooks,
-  removeMarketplaceEntry,
-} = require('./install-shared.cjs');
-
-function parseArgs(argv) {
-  let workspace = process.env.OPENCODE_WORKSPACE || process.cwd();
-  for (let i = 2; i < argv.length; i += 1) {
-    const arg = argv[i];
-    if (arg === '--workspace') {
-      const next = argv[i + 1];
-      workspace = next && !next.startsWith('-') ? path.resolve(argv[++i]) : process.cwd();
-      continue;
-    }
-    if (arg === '--global') {
-      workspace = null;
-      continue;
-    }
-    throw new Error(`unknown argument: ${arg}`);
-  }
-  return { workspace };
-}
-
-function main() {
-  const { workspace } = parseArgs(process.argv);
-  const openCodeHome = getOpenCodeHome(workspace);
-  const pluginRoot = getHomePluginRoot(workspace);
-  const marketplacePath = getHomeMarketplacePath(workspace);
-  let removedPlugin = false;
-
-  console.log(`[babysitter] Uninstalling OpenCode plugin from ${pluginRoot}`);
-
-  // 1. Remove plugin directory
-  if (fs.existsSync(pluginRoot)) {
-    try {
-      fs.rmSync(pluginRoot, { recursive: true, force: true });
-      console.log(`[babysitter]   Removed ${pluginRoot}`);
-      removedPlugin = true;
-    } catch (err) {
-      console.warn(`[babysitter]   Warning: Could not remove plugin directory: ${err.message}`);
-    }
-  }
-
-  // 2. Remove marketplace entry
-  removeMarketplaceEntry(marketplacePath);
-  console.log('[babysitter]   Cleaned marketplace entry');
-
-  // 3. Remove managed hooks from OpenCode config
-  removeManagedHooks(openCodeHome);
-  console.log('[babysitter]   Cleaned hooks config');
-
-  // 4. Clean up empty parent directories
-  const pluginsDir = path.dirname(pluginRoot);
-  try {
-    const remaining = fs.readdirSync(pluginsDir);
-    if (remaining.length === 0) {
-      fs.rmdirSync(pluginsDir);
-      console.log('[babysitter]   Removed empty plugins/ directory');
-    }
-  } catch { /* best-effort */ }
-
-  if (!removedPlugin) {
-    console.log('[babysitter] Plugin directory not found; config and hooks cleaned if present.');
-    return;
-  }
-
-  console.log('[babysitter] Uninstallation complete. Restart OpenCode to finish removal.');
-}
-
-main();
+require('./uninstall.js');

package/bin/uninstall.js

@@ -1,46 +1,24 @@
 #!/usr/bin/env node
-/**
- * Babysitter OpenCode Plugin Uninstaller
- *
- * Removes the babysitter plugin from the OpenCode plugins directory.
- */
+'use strict';
 
-"use strict";
-
-const fs = require("fs");
-const path = require("path");
-
-const WORKSPACE = process.env.OPENCODE_WORKSPACE || process.cwd();
-const TARGET_DIR = path.join(WORKSPACE, ".opencode", "plugins", "babysitter");
-
-function removeRecursive(dir) {
-  if (!fs.existsSync(dir)) return;
-  fs.rmSync(dir, { recursive: true, force: true });
-}
+const fs = require('fs');
+const shared = require('./install-shared');
 
 function main() {
-  console.log(`Uninstalling babysitter plugin from OpenCode...`);
-  console.log(`  Target: ${TARGET_DIR}`);
+  const pluginRoot = shared.getHomePluginRoot();
 
-  if (!fs.existsSync(TARGET_DIR)) {
-    console.log("  Plugin not installed -- nothing to remove.");
+  if (!fs.existsSync(pluginRoot)) {
+    console.log(`[${shared.PLUGIN_NAME}] Plugin not installed at ${pluginRoot}`);
     return;
   }
 
-  removeRecursive(TARGET_DIR);
-  console.log("  Removed babysitter plugin directory.");
-
-  // Clean up empty parent directories
-  const pluginsDir = path.join(WORKSPACE, ".opencode", "plugins");
   try {
-    const remaining = fs.readdirSync(pluginsDir);
-    if (remaining.length === 0) {
-      fs.rmdirSync(pluginsDir);
-      console.log("  Removed empty .opencode/plugins/ directory.");
-    }
-  } catch { /* best-effort */ }
-
-  console.log("\nBabysitter plugin uninstalled. Restart OpenCode to complete removal.");
+    fs.rmSync(pluginRoot, { recursive: true, force: true });
+    console.log(`[${shared.PLUGIN_NAME}] Uninstalled from ${pluginRoot}`);
+  } catch (err) {
+    console.error(`[${shared.PLUGIN_NAME}] Failed to uninstall: ${err.message}`);
+    process.exitCode = 1;
+  }
 }
 
 main();

package/commands/blueprints.md

@@ -0,0 +1,64 @@
+---
+description: manage Babysitter blueprints. Use this command to list installed blueprints, browse marketplaces, install, update, uninstall, configure, or create a new blueprint.
+argument-hint: Blueprint action and options.
+---
+
+This command installs and manages Babysitter blueprints. A blueprint is a version-managed package of contextual instructions or deterministic Babysitter processes, not a conventional software plugin.
+
+If the command is run without arguments, list installed blueprints with their name, version, marketplace, installation date, and last update date. Also list configured marketplaces and show how to add the default marketplace when none exist.
+
+Blueprints can be installed at two scopes:
+
+- **global** (`--global`): stored under `~/.a5c/`, available for all projects
+- **project** (`--project`): stored under `<projectDir>/.a5c/`, project-specific
+
+## Marketplace Management
+
+Marketplaces are git repositories containing a `marketplace.json` manifest and blueprint package directories. The SDK clones new marketplaces to `.a5c/blueprints/marketplaces/` for the selected scope and reads legacy `.a5c/marketplaces/` clones for compatibility.
+
+### Add a marketplace
+
+```bash
+babysitter blueprint:add-marketplace --marketplace-url <url> [--marketplace-path <relative-path>] [--marketplace-branch <ref>] [--force] --global|--project [--json]
+```
+
+### Update a marketplace
+
+```bash
+babysitter blueprint:update-marketplace --marketplace-name <name> [--marketplace-branch <ref>] --global|--project [--json]
+```
+
+### List blueprints in a marketplace
+
+```bash
+babysitter blueprint:list-plugins --marketplace-name <name> --global|--project [--json]
+```
+
+## Blueprint Lifecycle
+
+For `blueprint:install`, `blueprint:update`, `blueprint:configure`, and `blueprint:list-plugins`, the `--marketplace-name` flag is auto-detected when only one marketplace is cloned for the selected scope.
+
+```bash
+babysitter blueprint:install --plugin-name <name> [--marketplace-name <mp>] --global|--project [--json]
+babysitter blueprint:update --plugin-name <name> --marketplace-name <mp> --global|--project [--json]
+babysitter blueprint:configure --plugin-name <name> --marketplace-name <mp> --global|--project [--json]
+babysitter blueprint:uninstall --plugin-name <name> --marketplace-name <mp> --global|--project [--json]
+```
+
+The `--plugin-name` flag is preserved for CLI compatibility with existing marketplace manifests. User-facing docs should call the installable a blueprint.
+
+## Registry Management
+
+```bash
+babysitter blueprint:list-installed --global|--project [--json]
+babysitter blueprint:update-registry --plugin-name <name> --plugin-version <ver> --marketplace-name <mp> --global|--project [--json]
+babysitter blueprint:remove-from-registry --plugin-name <name> --global|--project [--json]
+```
+
+## Deprecated Aliases
+
+The old `plugin:*` commands remain available as deprecated aliases for one release. Prefer `blueprint:*` in new docs, skills, and process instructions.
+
+## Agent Plugins Are Separate
+
+Do not rename or reinterpret agent harness plugins while handling blueprints. `CLAUDE_PLUGIN_ROOT`, `PI_PLUGIN_ROOT`, `.claude/plugins/`, hooks-mux, extension-mux, and agent plugin manifests stay plugin-specific.

package/commands/call.md

@@ -1,7 +1,11 @@
----
-description: Orchestrate a babysitter run. use this command to start babysitting a complex workflow.
-argument-hint: Specific instructions for the run.
-allowed-tools: Read, Grep, Write, Task, Bash, Edit, Grep, Glob, WebFetch, WebSearch, Search, AskUserQuestion, TodoWrite, TodoRead, Skill, BashOutput, KillShell, MultiEdit, LS
----
-
-Invoke the babysitter:babysit skill (using the Skill tool) and follow its instructions (SKILL.md).
+---
+description: Orchestrate a babysitter run. use this command to start babysitting a complex workflow.
+argument-hint: Specific instructions for the run.
+allowed-tools: Read, Grep, Write, Task, Bash, Edit, Grep, Glob, WebFetch, WebSearch, Search, AskUserQuestion, TodoWrite, TodoRead, Skill, BashOutput, KillShell, MultiEdit, LS
+---
+
+Invoke the babysitter:babysit skill (using the Skill tool) and follow its instructions (SKILL.md). Then continue executing the returned instructions in this same turn. Do not stop after the Skill tool returns; carry the requested run through to completion proof.
+
+User arguments for this command:
+
+$ARGUMENTS

package/commands/check-forbidden-markers.md

@@ -0,0 +1,68 @@
+---
+description: Pre-deploy gate that scans built JS chunks for forbidden substring markers (saga-era / obsolete code paths) listed in a project-local forbidden-markers.txt
+argument-hint: "[--markers-file <path>] [--chunks-dir <path>] [--json] Optional overrides; defaults are project-relative."
+allowed-tools: Read, Grep, Write, Task, Bash, Edit, Grep, Glob, WebFetch, WebSearch, Search, AskUserQuestion, TodoWrite, TodoRead, Skill, BashOutput, KillShell, MultiEdit, LS
+---
+
+Invoke the babysitter:babysit skill (using the Skill tool) and follow its instructions (SKILL.md). Compose the gate from the shared helper at `library/processes/shared/forbidden-markers-scanner.js` (issue #477).
+
+## What this gate does
+
+Reads a list of literal substring markers from `scripts/forbidden-markers.txt` (blank lines and `#`-prefixed comments stripped) and greps every `.js` chunk under `.vercel/output/static/_next/static/chunks/` (Next.js / Vercel default; configurable) for any occurrence. Reports structured hits per `(marker, chunk)` pair with occurrence counts. Designed to chain between `vercel build --prod` and `vercel deploy --prod`.
+
+Use this gate when a refactor or restart-from-baseline replaced load-bearing code paths and you need a structural guarantee the obsolete symbols never re-ship. Burned-in evidence: cookbook VI-9 / VI-12 near-miss revivals during the 2026-05 iOS-Safari saga; the prototype lives at `cookbook/scripts/check-no-forbidden.mjs` and shipped two upstream contributions before being generalized as this gate.
+
+## When to use
+
+- **Pre-deploy.** Insert after build, before deploy. Block the deploy when `ok: false`.
+- **Post-restart.** After a baseline rollback + step-by-step re-add, snapshot the saga-era markers in `forbidden-markers.txt` and let CI hold the line.
+- **Post-refactor.** When old helper / handler / module names must not coexist with the new ones in the same bundle.
+
+## Expected config locations
+
+- `scripts/forbidden-markers.txt` — one marker per line, `#` for comments. The list is the contract; the gate is mechanical. Commit this file to source control.
+- `.vercel/output/static/_next/static/chunks/` — default scan target. Override for non-Vercel frameworks via the `--chunks-dir` flag or the `chunksDir` task input.
+
+A missing markers file is a no-op (`ok: true`, `reason: 'missing-markers-file'`) — misconfiguration is never a deploy block. A missing chunks directory is likewise a no-op (`reason: 'missing-chunks-dir'`) so the gate is safe to chain into `check:all` before the build runs.
+
+## Exit semantics
+
+| Reason                  | `ok`   | Deploy decision                |
+|-------------------------|--------|--------------------------------|
+| `missing-markers-file`  | true   | Pass (no gate active)          |
+| `missing-chunks-dir`    | true   | Pass (run before build)        |
+| `empty-markers`         | true   | Pass (list is empty)           |
+| `no-chunks`             | true   | Pass (nothing to scan)         |
+| `clean`                 | true   | Pass — proceed to deploy       |
+| `hits`                  | false  | **BLOCK** — surface hits, ask for triage |
+
+For each hit, the gate emits `{ marker, chunk, count }` so the operator sees the exact marker string, the absolute chunk path, and the number of occurrences in that chunk. Multiple hits across chunks for the same marker are reported separately.
+
+## Programmatic surface
+
+```js
+import { scanForbiddenMarkers, checkForbiddenMarkersTask } from '@a5c-ai/babysitter-library/processes/shared';
+
+// Direct call:
+const result = await scanForbiddenMarkers({
+  markersFile: 'scripts/forbidden-markers.txt',
+  chunksDir:   '.vercel/output/static/_next/static/chunks',
+});
+if (!result.ok) {
+  // result.hits: Array<{ marker, chunk, count }>
+  // result.reason === 'hits'
+  process.exit(1);
+}
+
+// Or dispatched as a babysitter task:
+const gate = await ctx.task(checkForbiddenMarkersTask, {
+  projectDir: '.',
+  // markersFile / chunksDir are inferred from projectDir if omitted
+});
+```
+
+## Reference
+
+- Issue: https://github.com/a5c-ai/babysitter/issues/477
+- Helper module: `library/processes/shared/forbidden-markers-scanner.js`
+- Origin (cookbook prototype): `cookbook/scripts/check-no-forbidden.mjs` (81 lines)

package/commands/cleanup.md

@@ -6,15 +6,43 @@ allowed-tools: Read, Grep, Write, Task, Bash, Edit, Grep, Glob, WebFetch, WebSea
 
 Invoke the babysitter:babysit skill (using the Skill tool) and follow its instructions (SKILL.md).
 
-Create and run a cleanup process using the process at `skills\babysit\process\cradle\cleanup-runs.js/processes/cleanup-runs.js`.
+Resolve the active process library with:
+
+```bash
+babysitter process-library:active --json
+```
+
+Read `binding.dir` from that JSON and create/run the cleanup process from `cradle/cleanup-runs.js#process` relative to that active library root. Do not use plugin-cache-relative cradle paths.
 
 Implementation notes (for the process):
 - Parse arguments for `--dry-run` flag (if present, set dryRun: true in inputs) and `--keep-days N` (default: 7)
-- The process scans .a5c/runs/ for completed/failed runs, aggregates insights, writes summaries, then removes old data
-- Always show the user what will be removed before removing (in interactive mode via breakpoints)
-- In non-interactive mode (yolo), proceed with cleanup using defaults
-- The insights file goes to docs/run-history-insights.md
-- Only remove terminal runs (completed/failed) older than the keep-days threshold
-- Never remove active/in-progress runs
-- Remove orphaned process files not referenced by remaining runs
-- After cleanup, show remaining run count and disk usage
+
+CRITICAL: The cleanup MUST follow this exact phase order. Do NOT delete any run before Phase 2 completes.
+
+Phase 1 — Scan:
+- Scan .a5c/runs/ for all runs
+- Classify each as terminal (completed/failed) or active (in-progress/created)
+- Identify terminal runs older than the keep-days threshold as removal candidates
+- Never mark active/in-progress runs for removal
+- Count and report: total runs, terminal, active, removal candidates, disk usage
+
+Phase 2 — Aggregate insights (BEFORE any deletion):
+- For EVERY removal candidate, read its run.json and journal/ events
+- Extract: processId, prompt, status, event count, created date, task summaries
+- Group by process type and extract patterns (retry counts, convergence behavior, failure modes)
+- Append a new dated section to docs/run-history-insights.md with:
+  - Summary statistics (runs removed, disk freed, runs retained)
+  - Run categories with counts and descriptions
+  - Key patterns observed (multi-batch convergence, retry behavior, etc.)
+  - What worked well / what didn't from the run data
+- This file MUST be written and verified before proceeding to Phase 3
+
+Phase 3 — Confirm removal:
+- In interactive mode, show the user what will be removed via a breakpoint
+- In non-interactive mode (yolo), proceed with defaults
+- In dry-run mode, stop here and show what would be removed
+
+Phase 4 — Remove:
+- Delete the terminal runs older than keep-days threshold
+- Identify and remove orphaned process files not referenced by remaining runs
+- Show remaining run count and disk usage after cleanup