gnosys 5.9.2 → 5.9.4

package/dist/cli.js

@@ -72,48 +72,21 @@ const pkgPath = path.resolve(__dirname, "..", "package.json");
 const pkg = JSON.parse(await fs.readFile(pkgPath, "utf-8"));
 const program = new Command();
 /**
- * v5.4.3 upgrade nudge — runs once per CLI invocation. If the installed
- * version differs from the last-seen one stored in central DB meta, print
- * a one-line stderr nudge so the user knows to run `gnosys upgrade`.
- *
- * Why stderr: doesn't pollute stdout consumers (agents parsing JSON, scripts
- * piping the output). Visible to humans, invisible to most parsers.
- *
- * Why central DB meta: survives across CLI invocations and works whether
- * gnosys is installed globally, locally, or via npx. Single source of truth
- * for "what was the last version this user saw."
- *
- * Skipped when:
- *   - GNOSYS_SKIP_UPGRADE_NUDGE=1
- *   - Running `gnosys upgrade` itself (would be redundant)
- *   - Central DB unavailable (graceful — never blocks the actual command)
+ * Phase F: True if the CLI process is running inside a test harness.
+ * Any code path that would otherwise OPEN the central DB (which
+ * implicitly creates ~/.gnosys/gnosys.db) MUST short-circuit on this.
  */
-function maybePrintUpgradeNudge() {
-    if (process.env.GNOSYS_SKIP_UPGRADE_NUDGE === "1")
-        return;
-    // Avoid printing the nudge when the user is already running upgrade.
-    if (process.argv[2] === "upgrade")
-        return;
-    try {
-        const db = GnosysDB.openLocal();
-        if (!db.isAvailable() || !db.isMigrated()) {
-            db.close();
-            return;
-        }
-        const seen = db.getMeta("last_seen_version");
-        const current = pkg.version;
-        if (seen !== current) {
-            const prefix = seen ? `upgraded to v${current} (from v${seen})` : `installed v${current}`;
-            process.stderr.write(`gnosys: ${prefix}. Run 'gnosys upgrade' to sync registered projects.\n`);
-            db.setMeta("last_seen_version", current);
-        }
-        db.close();
-    }
-    catch {
-        // Never block actual commands — silently skip on any error.
-    }
+function isTestEnv() {
+    return (process.env.VITEST === "true" ||
+        process.env.NODE_ENV === "test" ||
+        process.env.CI === "true");
 }
-maybePrintUpgradeNudge();
+// v5.9.3 Phase H: `maybePrintUpgradeNudge` (cli.ts:92-118 in v5.9.2) was
+// the second of two upgrade-nag mechanisms — both fired on every CLI
+// invocation and both opened the central DB. It is now deleted; the
+// post-install block at the BOTTOM of this file is the single source of
+// truth, runs on stderr only, and is downgrade-aware (`reverted`/
+// `upgraded`).
 /**
  * v5.6.0 back-compat shim: rewrite `gnosys export --to <dir>` →
  * `gnosys export vault --to <dir>` before commander parses argv. The v5.6.0
@@ -193,6 +166,10 @@ Run 'gnosys <command> --help' for command-specific help.
     // "you just installed a newer gnosys but haven't run sync-projects yet"
     // case, which produced a misleading "Run: npm install -g gnosys"
     // banner on every command.
+    //
+    // v5.9.3 (Phase F): skip in tests so we don't auto-create the central DB.
+    if (isTestEnv())
+        return;
     try {
         const centralDb = GnosysDB.openCentral();
         if (centralDb.isAvailable()) {
@@ -1669,6 +1646,27 @@ program
     catch {
         cliConfig = (await import("./lib/config.js")).DEFAULT_CONFIG;
     }
+    // v5.9.3 Phase G: fail-fast on missing API key BEFORE any TUI render.
+    // Done here so we exit before ink + react + the chat renderer pull in
+    // 100+ ms of dependencies. Provider for the chat task may be the
+    // default provider OR an explicit chat override in taskModels.chat.
+    {
+        const { resolveTaskModel: resolveTask } = await import("./lib/config.js");
+        const chatTask = resolveTask(cliConfig, "chat");
+        const provider = opts.provider ?? chatTask.provider;
+        if (provider !== "ollama" && provider !== "lmstudio") {
+            const { getApiKeyForProvider } = await import("./lib/setup.js");
+            const key = await getApiKeyForProvider(provider);
+            if (!key) {
+                const { Status } = await import("./lib/setup/ui/status.js");
+                const envVar = `${provider.toUpperCase()}_API_KEY`;
+                process.stderr.write(`${Status("fail", `no API key for ${provider} (the configured chat provider)`)}\n`);
+                process.stderr.write(`   fix:  gnosys setup           pick a provider with a key, or add one\n`);
+                process.stderr.write(`         export ${envVar}=...\n`);
+                process.exit(1);
+            }
+        }
+    }
     await chat.startChat({
         config: cliConfig,
         resume: opts.resume,
@@ -2871,7 +2869,8 @@ const configCmd = program
 configCmd
     .command("show")
     .description("Show current LLM configuration")
-    .action(async () => {
+    .option("--json", "Dump the raw effective config as JSON")
+    .action(async (opts) => {
     const resolver = await getResolver();
     const stores = resolver.getStores();
     if (stores.length === 0) {
@@ -2879,6 +2878,12 @@ configCmd
         process.exit(1);
     }
     const cfg = await loadConfig(stores[0].path);
+    if (opts.json) {
+        // v5.9.3 (design §12): --json keeps the old machine-readable
+        // dump for scripts. Default output is the human-friendly view.
+        process.stdout.write(`${JSON.stringify(cfg, null, 2)}\n`);
+        return;
+    }
     console.log("System of Cognition (SOC) — LLM Configuration:");
     console.log(`  Default provider: ${cfg.llm.defaultProvider}`);
     console.log("");
@@ -2904,27 +2909,47 @@ configCmd
     .command("set <key> <value> [extra...]")
     .description("Set a config value. Keys: provider, model, ollama-url, groq-model, openai-model, lmstudio-url, task <task> <provider> <model>")
     .action(async (key, value, extra) => {
+    // v5.9.3 Screen 13 — schema-validate the top-level key against the
+    // known set BEFORE any work, render a `did you mean X?` hint on
+    // typo. The diff + store-source label fire after the switch.
+    const { suggestConfigKey, classifyStore, KNOWN_CONFIG_KEYS } = await import("./lib/setup/configSetRender.js");
+    const { Header } = await import("./lib/setup/ui/header.js");
+    const { printStatus } = await import("./lib/setup/ui/status.js");
+    const { printDiff } = await import("./lib/setup/ui/diff.js");
+    if (!KNOWN_CONFIG_KEYS.includes(key)) {
+        const suggestion = suggestConfigKey(key);
+        const meta = suggestion ? `did you mean \`${suggestion}\` ?` : undefined;
+        printStatus("fail", `unknown config key   ${key}`, meta);
+        process.exit(1);
+    }
     const resolver = await getResolver();
     const writeTarget = resolver.getWriteTarget();
     if (!writeTarget) {
-        console.error("No writable store found.");
+        printStatus("fail", "no writable store found");
         process.exit(1);
     }
     const storePath = writeTarget.store.getStorePath();
     const cfg = await loadConfig(storePath);
     const validProviders = ALL_PROVIDERS.join(", ");
+    const homeDir = process.env.HOME || process.env.USERPROFILE || "/";
+    const storeLabel = classifyStore(storePath, homeDir);
+    // Each branch populates this row so the trailing Diff print picks up
+    // a single before/after summary. Recall has three sub-fields and
+    // sets the row inside its own switch.
+    let diffRow = null;
     switch (key) {
         case "provider":
             if (!ALL_PROVIDERS.includes(value)) {
-                console.error(`Invalid provider: "${value}". Supported: ${validProviders}`);
+                printStatus("fail", `invalid provider \`${value}\``, `supported: ${validProviders}`);
                 process.exit(1);
             }
+            diffRow = { label: "provider", from: cfg.llm.defaultProvider, to: value };
             cfg.llm.defaultProvider = value;
-            console.log(`Default provider set to: ${value}`);
             break;
         case "model": {
             // Set model for current default provider
             const p = cfg.llm.defaultProvider;
+            const fromModel = providerModel(cfg, p) ?? "(unset)";
             if (p === "anthropic")
                 cfg.llm.anthropic.model = value;
             else if (p === "ollama")
@@ -2945,7 +2970,7 @@ configCmd
                 else
                     cfg.llm.custom.model = value;
             }
-            console.log(`Model set to: ${value} (for ${p})`);
+            diffRow = { label: `${p}.model`, from: fromModel, to: value };
             break;
         }
         case "task": {
@@ -2954,83 +2979,87 @@ configCmd
             const taskProvider = extra[0];
             const taskModel = extra[1];
             if (!taskName || !taskProvider || !taskModel) {
-                console.error("Usage: gnosys config set task <structuring|synthesis> <provider> <model>");
+                printStatus("fail", "usage", "gnosys config set task <structuring|synthesis> <provider> <model>");
                 process.exit(1);
             }
             if (taskName !== "structuring" && taskName !== "synthesis") {
-                console.error(`Invalid task: "${taskName}". Valid: structuring, synthesis`);
+                printStatus("fail", `invalid task \`${taskName}\``, "valid: structuring, synthesis");
                 process.exit(1);
             }
             if (!ALL_PROVIDERS.includes(taskProvider)) {
-                console.error(`Invalid provider: "${taskProvider}". Supported: ${validProviders}`);
+                printStatus("fail", `invalid provider \`${taskProvider}\``, `supported: ${validProviders}`);
                 process.exit(1);
             }
             if (!cfg.taskModels)
                 cfg.taskModels = {};
-            cfg.taskModels[taskName] = { provider: taskProvider, model: taskModel };
-            console.log(`Task "${taskName}" routed to: ${taskProvider}/${taskModel}`);
+            const taskMap = cfg.taskModels;
+            const prev = taskMap[taskName];
+            const fromStr = prev ? `${prev.provider}/${prev.model}` : "(unset)";
+            taskMap[taskName] = { provider: taskProvider, model: taskModel };
+            diffRow = { label: `task.${taskName}`, from: fromStr, to: `${taskProvider}/${taskModel}` };
             break;
         }
         case "ollama-url":
+            diffRow = { label: "ollama.baseUrl", from: cfg.llm.ollama.baseUrl ?? "(unset)", to: value };
             cfg.llm.ollama.baseUrl = value;
-            console.log(`Ollama base URL set to: ${value}`);
             break;
         case "ollama-model":
+            diffRow = { label: "ollama.model", from: cfg.llm.ollama.model ?? "(unset)", to: value };
             cfg.llm.ollama.model = value;
-            console.log(`Ollama model set to: ${value}`);
             break;
         case "anthropic-model":
+            diffRow = { label: "anthropic.model", from: cfg.llm.anthropic.model ?? "(unset)", to: value };
             cfg.llm.anthropic.model = value;
-            console.log(`Anthropic model set to: ${value}`);
             break;
         case "groq-model":
+            diffRow = { label: "groq.model", from: cfg.llm.groq.model ?? "(unset)", to: value };
             cfg.llm.groq.model = value;
-            console.log(`Groq model set to: ${value}`);
             break;
         case "openai-model":
+            diffRow = { label: "openai.model", from: cfg.llm.openai.model ?? "(unset)", to: value };
             cfg.llm.openai.model = value;
-            console.log(`OpenAI model set to: ${value}`);
             break;
         case "openai-url":
+            diffRow = { label: "openai.baseUrl", from: cfg.llm.openai.baseUrl ?? "(unset)", to: value };
             cfg.llm.openai.baseUrl = value;
-            console.log(`OpenAI base URL set to: ${value}`);
             break;
         case "lmstudio-url":
+            diffRow = { label: "lmstudio.baseUrl", from: cfg.llm.lmstudio.baseUrl ?? "(unset)", to: value };
             cfg.llm.lmstudio.baseUrl = value;
-            console.log(`LM Studio base URL set to: ${value}`);
             break;
         case "lmstudio-model":
+            diffRow = { label: "lmstudio.model", from: cfg.llm.lmstudio.model ?? "(unset)", to: value };
             cfg.llm.lmstudio.model = value;
-            console.log(`LM Studio model set to: ${value}`);
             break;
         case "xai-model":
+            diffRow = { label: "xai.model", from: cfg.llm.xai.model ?? "(unset)", to: value };
             cfg.llm.xai.model = value;
-            console.log(`xAI model set to: ${value}`);
             break;
         case "mistral-model":
+            diffRow = { label: "mistral.model", from: cfg.llm.mistral.model ?? "(unset)", to: value };
             cfg.llm.mistral.model = value;
-            console.log(`Mistral model set to: ${value}`);
             break;
         case "custom-url":
+            diffRow = { label: "custom.baseUrl", from: cfg.llm.custom?.baseUrl ?? "(unset)", to: value };
             if (!cfg.llm.custom)
                 cfg.llm.custom = { model: "", baseUrl: value };
             else
                 cfg.llm.custom.baseUrl = value;
-            console.log(`Custom provider base URL set to: ${value}`);
             break;
         case "custom-model":
+            diffRow = { label: "custom.model", from: cfg.llm.custom?.model ?? "(unset)", to: value };
             if (!cfg.llm.custom)
                 cfg.llm.custom = { model: value, baseUrl: "" };
             else
                 cfg.llm.custom.model = value;
-            console.log(`Custom provider model set to: ${value}`);
             break;
         case "custom-key":
+            // Sensitive — don't echo the key in the diff, just mark as redacted.
+            diffRow = { label: "custom.apiKey", from: cfg.llm.custom?.apiKey ? "(set)" : "(unset)", to: "(set)" };
             if (!cfg.llm.custom)
                 cfg.llm.custom = { model: "", baseUrl: "", apiKey: value };
             else
                 cfg.llm.custom.apiKey = value;
-            console.log(`Custom provider API key set.`);
             break;
         case "recall": {
             // gnosys config set recall <field> <value>
@@ -3038,7 +3067,7 @@ configCmd
             const recallField = value;
             const recallValue = extra[0];
             if (!recallField || !recallValue) {
-                console.error("Usage: gnosys config set recall <aggressive|maxMemories|minRelevance> <value>");
+                printStatus("fail", "usage", "gnosys config set recall <aggressive|maxMemories|minRelevance> <value>");
                 process.exit(1);
             }
             if (!cfg.recall)
@@ -3046,49 +3075,88 @@ configCmd
             switch (recallField) {
                 case "aggressive":
                     if (recallValue !== "true" && recallValue !== "false") {
-                        console.error(`Invalid value: "${recallValue}". Use "true" or "false".`);
+                        printStatus("fail", `invalid value \`${recallValue}\``, "use `true` or `false`");
                         process.exit(1);
                     }
+                    diffRow = { label: "recall.aggressive", from: String(cfg.recall.aggressive), to: recallValue };
                     cfg.recall.aggressive = recallValue === "true";
-                    console.log(`Recall aggressive mode: ${cfg.recall.aggressive ? "enabled" : "disabled"}`);
                     break;
                 case "maxMemories": {
                     const n = parseInt(recallValue, 10);
                     if (isNaN(n) || n < 1 || n > 20) {
-                        console.error("maxMemories must be between 1 and 20");
+                        printStatus("fail", "maxMemories must be between 1 and 20");
                         process.exit(1);
                     }
+                    diffRow = { label: "recall.maxMemories", from: String(cfg.recall.maxMemories), to: String(n) };
                     cfg.recall.maxMemories = n;
-                    console.log(`Recall maxMemories set to: ${n}`);
                     break;
                 }
                 case "minRelevance": {
                     const f = parseFloat(recallValue);
                     if (isNaN(f) || f < 0 || f > 1) {
-                        console.error("minRelevance must be between 0 and 1");
+                        printStatus("fail", "minRelevance must be between 0 and 1");
                         process.exit(1);
                     }
+                    diffRow = { label: "recall.minRelevance", from: String(cfg.recall.minRelevance), to: String(f) };
                     cfg.recall.minRelevance = f;
-                    console.log(`Recall minRelevance set to: ${f}`);
                     break;
                 }
                 default:
-                    console.error(`Unknown recall field: "${recallField}". Valid: aggressive, maxMemories, minRelevance`);
+                    printStatus("fail", `unknown recall field \`${recallField}\``, "valid: aggressive, maxMemories, minRelevance");
                     process.exit(1);
             }
             break;
         }
-        default:
-            console.error(`Unknown config key: "${key}". Valid: provider, model, task, ollama-url, ollama-model, anthropic-model, groq-model, openai-model, openai-url, lmstudio-url, lmstudio-model, recall`);
-            process.exit(1);
     }
     await writeConfig(storePath, cfg);
-    console.log("Configuration saved to gnosys.json");
+    // v5.9.3 Screen 13 — print Header + Diff + ✓ saved with store label.
+    console.log("");
+    console.log(Header(["gnosys", "config", "set"]));
+    console.log("");
+    if (diffRow) {
+        // Append store source to the `to` column so the diff line says
+        // both the new value and where it landed (project vs global).
+        printDiff([{ ...diffRow, to: `${diffRow.to}    (${storeLabel})` }]);
+    }
+    printStatus("ok", `saved · ${path.join(storePath, "gnosys.json")}`, `(${storeLabel})`);
 });
+/** Resolve the current `.model` field for the active LLM provider. */
+function providerModel(cfg, p) {
+    switch (p) {
+        case "anthropic": return cfg.llm.anthropic.model;
+        case "ollama": return cfg.llm.ollama.model;
+        case "groq": return cfg.llm.groq.model;
+        case "openai": return cfg.llm.openai.model;
+        case "lmstudio": return cfg.llm.lmstudio.model;
+        case "xai": return cfg.llm.xai.model;
+        case "mistral": return cfg.llm.mistral.model;
+        case "custom": return cfg.llm.custom?.model;
+    }
+}
 configCmd
     .command("init")
-    .description("Generate a default gnosys.json with LLM settings")
-    .action(async () => {
+    .description("Generate a blank gnosys.json template (deprecated — prefer `gnosys setup`)")
+    .option("--force", "Skip the deprecation warning and write the template")
+    .action(async (opts) => {
+    // v5.9.3 (design handoff §14, deci-050): `config init` is being
+    // folded into `gnosys setup`. Without --force we print a warning
+    // pointing to `gnosys setup` and exit. With --force we write the
+    // (now-blank-provider) template anyway for muscle-memory use.
+    if (!opts.force) {
+        const { Header } = await import("./lib/setup/ui/header.js");
+        const { Status } = await import("./lib/setup/ui/status.js");
+        const { Footer } = await import("./lib/setup/ui/footer.js");
+        console.log("");
+        console.log(Header(["gnosys", "config", "init"], { version: `v${pkg.version}` }));
+        console.log("");
+        console.log(Status("warn", "writing a blank template means the next run of `gnosys setup`"));
+        console.log(Status("warn", "will walk you through the same choices anyway"));
+        console.log("");
+        console.log("   try   gnosys setup        interactive walkthrough (recommended)");
+        console.log("");
+        console.log(Footer("re-run with --force to write the template anyway"));
+        process.exit(0);
+    }
     const resolver = await getResolver();
     const writeTarget = resolver.getWriteTarget();
     if (!writeTarget) {
@@ -3224,7 +3292,12 @@ program
 // `syncProjectsAction`, called from the new `setup sync-projects` command.
 async function syncProjectsAction(opts) {
     const currentVersion = pkg.version;
-    console.log(`Gnosys v${currentVersion} — upgrading registered projects...\n`);
+    // v5.9.3 Screen 10 — Header + leading spinner + hierarchical sections.
+    const { renderSyncHeader, renderUpgradedSection, renderSkippedSection, renderFailedSection, renderMachinesSection, renderDivider, renderDoneLine, renderDashboardSummary, } = await import("./lib/setup/syncProjectsRender.js");
+    const { Spinner } = await import("./lib/setup/ui/spinner.js");
+    console.log("");
+    console.log(renderSyncHeader(currentVersion));
+    console.log("");
     // 1. Read registered projects from file registry AND central DB
     const home = process.env.HOME || process.env.USERPROFILE || "/tmp";
     const registryPath = path.join(home, ".config", "gnosys", "projects.json");
@@ -3235,13 +3308,18 @@ async function syncProjectsAction(opts) {
     catch {
         // No file registry yet
     }
-    // Also check central DB for projects not in the file registry
+    // Also check central DB for projects not in the file registry. Also
+    // capture project titles so the Screen 10 row labels can use the
+    // human-readable name where available.
     let dbProjects = [];
+    const titleByDir = new Map();
     try {
         const centralDb = GnosysDB.openCentral();
         if (centralDb.isAvailable()) {
             const allProjects = centralDb.getAllProjects();
             dbProjects = allProjects.map((p) => p.working_directory);
+            for (const p of allProjects)
+                titleByDir.set(p.working_directory, p.name);
             centralDb.close();
         }
     }
@@ -3259,9 +3337,13 @@ async function syncProjectsAction(opts) {
         }
     }
     if (projects.length === 0) {
-        console.log("No registered projects found. Run 'gnosys init' in each project first.");
+        console.log(" no registered projects found");
+        console.log(" run `gnosys init` in each project first");
         return;
     }
+    // Lead-in spinner: shows we're churning through the registry. Resolves
+    // to ✓ summary after the iteration loop completes (or fail on hard error).
+    const syncSpinner = Spinner(`syncing ${projects.length} registered projects…`);
     // Sync the merged list back to file registry
     try {
         await fs.mkdir(path.dirname(registryPath), { recursive: true });
@@ -3325,6 +3407,9 @@ async function syncProjectsAction(opts) {
             failed.push(`${projectDir} (${err.message})`);
         }
     }
+    // Stop the lead-in spinner now that the iteration is done. Resolved
+    // before any per-section output so the cursor is on a fresh line.
+    syncSpinner.ok(`synced ${projects.length} registered projects`, `${upgraded.length} upgraded · ${skipped.length} skipped · ${failed.length} failed`);
     // 3. Update global agent rules
     try {
         let centralDb = null;
@@ -3340,11 +3425,13 @@ async function syncProjectsAction(opts) {
             const { syncToTarget } = await import("./lib/rulesGen.js");
             await syncToTarget(centralDb, process.cwd(), "global", null);
             centralDb.close();
-            console.log(`  ✓ Global agent rules updated (~/.claude/CLAUDE.md)`);
+            const { printStatus } = await import("./lib/setup/ui/status.js");
+            printStatus("ok", "global agent rules updated", "~/.claude/CLAUDE.md");
         }
     }
     catch {
-        console.log(`  ⚠ Could not update global agent rules`);
+        const { printStatus } = await import("./lib/setup/ui/status.js");
+        printStatus("warn", "could not update global agent rules");
     }
     // 4. Stamp the central DB with current version and machine info
     try {
@@ -3370,25 +3457,36 @@ async function syncProjectsAction(opts) {
     catch {
         // non-critical
     }
-    // 5. Report
+    // 5. Report — v5.9.3 Screen 10 hierarchical layout. Section helpers
+    // turn the raw path arrays into ProjectRow lists (title + fullPath)
+    // and emit dividers between groups.
+    function rowFor(p) {
+        const title = titleByDir.get(p) ?? titleByDir.get(path.resolve(p)) ?? path.basename(p);
+        return { title, fullPath: p };
+    }
+    const upgradedRows = upgraded.map(rowFor);
+    const skippedRows = skipped.map(rowFor);
+    const failedRows = failed.map((f) => {
+        // failed entries are "<path> (<err>)" — extract path for the title.
+        const match = f.match(/^(.+?)\s\((.+)\)$/);
+        const projectPath = match ? match[1] : f;
+        return { title: titleByDir.get(projectPath) ?? path.basename(projectPath), fullPath: f };
+    });
     console.log("");
-    if (upgraded.length > 0) {
-        console.log(`Upgraded (${upgraded.length}):`);
-        for (const p of upgraded)
-            console.log(`  ✓ ${path.basename(p)} — ${p}`);
-    }
-    if (skipped.length > 0) {
-        console.log(`\nSkipped — no .gnosys directory (${skipped.length}):`);
-        for (const p of skipped)
-            console.log(`  ○ ${path.basename(p)} — ${p}  (run 'gnosys init' in this directory)`);
-    }
-    if (failed.length > 0) {
-        console.log(`\nFailed (${failed.length}):`);
-        for (const f of failed)
-            console.log(`  ✗ ${f}`);
-    }
-    console.log(`\nDone. Central DB stamped with v${currentVersion}.`);
-    // Show machine status from shared DB
+    for (const line of renderUpgradedSection(upgradedRows))
+        console.log(line);
+    if (upgradedRows.length > 0 && (skippedRows.length > 0 || failedRows.length > 0)) {
+        console.log("");
+    }
+    for (const line of renderSkippedSection(skippedRows))
+        console.log(line);
+    if (failedRows.length > 0) {
+        console.log("");
+        for (const line of renderFailedSection(failedRows))
+            console.log(line);
+    }
+    // Connected-machines callout (separate divider per design spec).
+    let machineLines = [];
     try {
         const centralDb = GnosysDB.openCentral();
         if (centralDb.isAvailable()) {
@@ -3396,18 +3494,14 @@ async function syncProjectsAction(opts) {
             if (raw) {
                 const machines = JSON.parse(raw);
                 const entries = Object.entries(machines);
-                if (entries.length > 1) {
-                    console.log(`\nConnected machines:`);
-                    for (const [host, info] of entries) {
-                        const isCurrent = host === os.hostname();
-                        const status = info.version === currentVersion ? "✓" : `⚠ v${info.version}`;
-                        console.log(`  ${status} ${host}${isCurrent ? " (this machine)" : ""} — last seen ${info.lastSeen.split("T")[0]}`);
-                    }
-                    const behind = entries.filter(([, info]) => info.version !== currentVersion);
-                    if (behind.length > 0) {
-                        console.log(`\n  ${behind.length} machine(s) need upgrading. Run 'npm install -g gnosys && gnosys upgrade' on each.`);
-                    }
-                }
+                const currentHost = os.hostname();
+                const machineRows = entries.map(([host, info]) => ({
+                    hostname: host,
+                    version: info.version,
+                    lastSeen: info.lastSeen,
+                    isCurrent: host === currentHost,
+                }));
+                machineLines = renderMachinesSection(machineRows, currentVersion);
             }
             centralDb.close();
         }
@@ -3415,9 +3509,36 @@ async function syncProjectsAction(opts) {
     catch {
         // non-critical
     }
-    if (skipped.length > 0) {
-        console.log(`\nNote: ${skipped.length} project(s) skipped — no .gnosys directory found.`);
-        console.log(`Run 'gnosys init' in each directory to set them up, or remove them from the registry.`);
+    if (machineLines.length > 0) {
+        console.log("");
+        console.log(renderDivider());
+        console.log("");
+        for (const line of machineLines)
+            console.log(line);
+    }
+    console.log("");
+    console.log(renderDivider());
+    console.log("");
+    console.log(renderDoneLine(currentVersion));
+    if (skippedRows.length > 0) {
+        // v5.9.3 Phase H: offer one-keystroke cleanup. Stays interactive
+        // by default; users on a TTY get the prompt, non-TTY runs silently
+        // (sync-projects is sometimes invoked from CI).
+        console.log("");
+        if (process.stdout.isTTY) {
+            try {
+                const { cleanupRegistry } = await import("./lib/cleanup.js");
+                await cleanupRegistry({ interactive: true });
+            }
+            catch (err) {
+                const { printStatus } = await import("./lib/setup/ui/status.js");
+                printStatus("warn", "cleanup skipped", err instanceof Error ? err.message : String(err));
+            }
+        }
+        else {
+            const { printStatus } = await import("./lib/setup/ui/status.js");
+            printStatus("progress", "tip", "run `gnosys cleanup` to remove stale entries");
+        }
     }
     // 6. Regenerate portfolio dashboard
     if (!opts.skipDashboard) {
@@ -3432,13 +3553,16 @@ async function syncProjectsAction(opts) {
                 await fs.writeFile(dashboardPath, generatePortfolioHtml(report, dashboardPath), "utf-8");
                 await fs.writeFile(dashboardMdPath, formatPortfolioMarkdown(report), "utf-8");
                 centralDb.close();
-                console.log(`\nPortfolio dashboard regenerated:`);
-                console.log(`  HTML: ${dashboardPath}`);
-                console.log(`  MD:   ${dashboardMdPath}`);
+                console.log("");
+                for (const line of renderDashboardSummary(dashboardPath, dashboardMdPath)) {
+                    console.log(line);
+                }
             }
         }
         catch {
-            console.log(`\n  Could not regenerate portfolio dashboard`);
+            const { printStatus } = await import("./lib/setup/ui/status.js");
+            console.log("");
+            printStatus("warn", "could not regenerate portfolio dashboard");
         }
     }
 }
@@ -3449,6 +3573,25 @@ setupCmd
     .description("Re-initialize all registered projects after upgrading gnosys: refresh agent rules, project registry, central DB stamp, and portfolio dashboard.")
     .option("--skip-dashboard", "Skip regenerating the portfolio dashboard")
     .action(syncProjectsAction);
+// `gnosys cleanup` — prune dead/temp entries from the project registry.
+// Standalone top-level command per Phase H. Also reusable from inside
+// `setup sync-projects` when the skipped list is non-empty (see
+// road-015).
+program
+    .command("cleanup")
+    .description("Remove dead and temp-dir entries from the project registry")
+    .option("--yes", "Non-interactive, remove without prompting")
+    .option("--dry-run", "Show what would be removed without writing")
+    .action(async (opts) => {
+    const { cleanupRegistry } = await import("./lib/cleanup.js");
+    const result = await cleanupRegistry({
+        interactive: !opts.yes && !opts.dryRun,
+        yes: opts.yes,
+    });
+    if (opts.yes || opts.dryRun) {
+        console.log(JSON.stringify(result, null, 2));
+    }
+});
 // `gnosys upgrade` — upgrade the gnosys CLI/MCP itself, then prompt the
 // user to run sync-projects. Writes ~/.gnosys/last-upgrade-at so running
 // MCP servers exit cleanly and the host respawns them against the new
@@ -6265,36 +6408,57 @@ webCmd
 // you" which is a separate concern handled by the preAction warning.
 // Also avoids re-nudging once per command for the same version-pair by
 // honoring a per-session env-var sentinel.
-try {
-    const centralDb = GnosysDB.openCentral();
-    if (centralDb.isAvailable()) {
-        const lastVersion = centralDb.getMeta("app_version");
-        const currentVersion = pkg.version;
-        const isUpgradeCmd = process.argv.slice(2).some(a => a === "upgrade");
-        const isSetupSyncCmd = process.argv.slice(2).join(" ").includes("setup sync-projects");
-        // CRITICAL: `serve` writes JSON-RPC to stdout for MCP transport. Any
-        // console.log during boot corrupts the protocol and the host (Grok, Codex,
-        // etc.) sees the server as [unavailable]. Suppress the nag in serve mode.
-        const isServeCmd = process.argv.slice(2).some(a => a === "serve");
-        const newer = lastVersion && compareSemver(currentVersion, lastVersion) > 0;
-        if (newer && !isUpgradeCmd && !isSetupSyncCmd && !isServeCmd) {
-            console.log("");
-            console.log(`  Gnosys updated: v${lastVersion} → v${currentVersion}`);
-            console.log("");
-            console.log("  Run now to refresh the central DB stamp and registered projects:");
-            console.log("    gnosys setup sync-projects");
-            console.log("");
-            console.log("  Then restart MCP servers:");
-            console.log("    Cursor:      Cmd+Shift+P > MCP: Restart All Servers");
-            console.log("    Claude Code: /mcp > restart gnosys (or start new session)");
-            console.log("    Codex:       start new session");
-            console.log("");
+//
+// v5.9.3 Phase H consolidation lives BELOW this block; Phase F guards us
+// from touching the DB at all in tests.
+if (!isTestEnv()) {
+    try {
+        const centralDb = GnosysDB.openCentral();
+        if (centralDb.isAvailable()) {
+            const lastVersion = centralDb.getMeta("app_version");
+            const currentVersion = pkg.version;
+            const isUpgradeCmd = process.argv.slice(2).some(a => a === "upgrade");
+            const isSetupSyncCmd = process.argv.slice(2).join(" ").includes("setup sync-projects");
+            // CRITICAL: `serve` writes JSON-RPC to stdout for MCP transport. Any
+            // console.log during boot corrupts the protocol and the host (Grok, Codex,
+            // etc.) sees the server as [unavailable]. Suppress the nag in serve mode.
+            const isServeCmd = process.argv.slice(2).some(a => a === "serve");
+            // v5.9.3 Phase H: fire on any mismatch (upgrade OR downgrade).
+            const mismatch = lastVersion !== null && lastVersion !== undefined &&
+                compareSemver(currentVersion, lastVersion) !== 0;
+            if (mismatch && !isUpgradeCmd && !isSetupSyncCmd && !isServeCmd) {
+                // v5.9.3 Phase H: emit on STDERR (was stdout). Safer invariant per
+                // deci-045 — stdout is reserved for command output.
+                const isMajorOrMinor = (() => {
+                    if (!lastVersion)
+                        return false;
+                    const oldParts = lastVersion.split(".").map(Number);
+                    const newParts = currentVersion.split(".").map(Number);
+                    return (oldParts[0] ?? 0) !== (newParts[0] ?? 0) || (oldParts[1] ?? 0) !== (newParts[1] ?? 0);
+                })();
+                const direction = compareSemver(currentVersion, lastVersion ?? "0.0.0") > 0 ? "upgraded" : "reverted";
+                process.stderr.write("\n");
+                process.stderr.write(` ⬢ gnosys ${direction} · v${lastVersion} → v${currentVersion}\n`);
+                process.stderr.write("\n");
+                if (direction === "upgraded") {
+                    process.stderr.write("   sync registered projects        gnosys upgrade\n");
+                    if (isMajorOrMinor) {
+                        process.stderr.write("   restart mcp                     cursor → MCP: restart all servers\n");
+                        process.stderr.write("                                   claude code → /mcp → restart gnosys\n");
+                        process.stderr.write("                                   codex → start new session\n");
+                    }
+                }
+                else {
+                    process.stderr.write("   if this was unintentional, run  gnosys upgrade\n");
+                }
+                process.stderr.write("\n");
+            }
+            centralDb.close();
         }
-        centralDb.close();
     }
-}
-catch {
-    // non-critical — don't block CLI startup
+    catch {
+        // non-critical — don't block CLI startup
+    }
 }
 program.parse();
 //# sourceMappingURL=cli.js.map