gsd-pi 2.27.0 → 2.28.0-dev.4009980

package/dist/loader.js

@@ -2,37 +2,33 @@
 // GSD Startup Loader
 // Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
 import { fileURLToPath } from 'url';
-import { dirname, resolve, join, delimiter } from 'path';
-import { existsSync, readFileSync, readdirSync, mkdirSync, symlinkSync, cpSync } from 'fs';
+import { dirname, resolve, join, relative, delimiter } from 'path';
+import { existsSync, readFileSync, mkdirSync, symlinkSync, cpSync } from 'fs';
 // Fast-path: handle --version/-v and --help/-h before importing any heavy
 // dependencies. This avoids loading the entire pi-coding-agent barrel import
 // (~1s) just to print a version string.
 const gsdRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const args = process.argv.slice(2);
 const firstArg = args[0];
+// Read package.json once — reused for version, banner, and GSD_VERSION below
+let gsdVersion = '0.0.0';
+try {
+    const pkg = JSON.parse(readFileSync(join(gsdRoot, 'package.json'), 'utf-8'));
+    gsdVersion = pkg.version || '0.0.0';
+}
+catch { /* ignore */ }
 if (firstArg === '--version' || firstArg === '-v') {
-    try {
-        const pkg = JSON.parse(readFileSync(join(gsdRoot, 'package.json'), 'utf-8'));
-        process.stdout.write((pkg.version || '0.0.0') + '\n');
-    }
-    catch {
-        process.stdout.write('0.0.0\n');
-    }
+    process.stdout.write(gsdVersion + '\n');
     process.exit(0);
 }
 if (firstArg === '--help' || firstArg === '-h') {
-    let version = '0.0.0';
-    try {
-        const pkg = JSON.parse(readFileSync(join(gsdRoot, 'package.json'), 'utf-8'));
-        version = pkg.version || version;
-    }
-    catch { /* ignore */ }
     const { printHelp } = await import('./help-text.js');
-    printHelp(version);
+    printHelp(gsdVersion);
     process.exit(0);
 }
 import { agentDir, appRoot } from './app-paths.js';
 import { serializeBundledExtensionPaths } from './bundled-extension-paths.js';
+import { discoverExtensionEntryPaths } from './extension-discovery.js';
 import { renderLogo } from './logo.js';
 // pkg/ is a shim directory: contains gsd's piConfig (package.json) and pi's
 // theme assets (dist/modes/interactive/theme/) without a src/ directory.
@@ -52,15 +48,9 @@ if (!existsSync(appRoot)) {
     const dim = '\x1b[2m';
     const reset = '\x1b[0m';
     const colorCyan = (s) => `${cyan}${s}${reset}`;
-    let version = '';
-    try {
-        const pkgJson = JSON.parse(readFileSync(resolve(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf-8'));
-        version = pkgJson.version ?? '';
-    }
-    catch { /* ignore */ }
     process.stderr.write(renderLogo(colorCyan) +
         '\n' +
-        `  Get Shit Done ${dim}v${version}${reset}\n` +
+        `  Get Shit Done ${dim}v${gsdVersion}${reset}\n` +
         `  ${green}Welcome.${reset} Setting up your environment...\n\n`);
 }
 // GSD_CODING_AGENT_DIR — tells pi's getAgentDir() to return ~/.gsd/agent/ instead of ~/.gsd/agent/
@@ -79,13 +69,7 @@ process.env.NODE_PATH = [gsdNodeModules, process.env.NODE_PATH]
 const { Module } = await import('module');
 Module._initPaths?.();
 // GSD_VERSION — expose package version so extensions can display it
-try {
-    const gsdPkg = JSON.parse(readFileSync(join(gsdRoot, 'package.json'), 'utf-8'));
-    process.env.GSD_VERSION = gsdPkg.version || '0.0.0';
-}
-catch {
-    process.env.GSD_VERSION = '0.0.0';
-}
+process.env.GSD_VERSION = gsdVersion;
 // GSD_BIN_PATH — absolute path to this loader (dist/loader.js), used by patched subagent
 // to spawn gsd instead of pi when dispatching workflow tasks
 process.env.GSD_BIN_PATH = process.argv[1];
@@ -97,37 +81,12 @@ const srcRes = join(gsdRoot, 'src', 'resources');
 const resourcesDir = existsSync(distRes) ? distRes : srcRes;
 process.env.GSD_WORKFLOW_PATH = join(resourcesDir, 'GSD-WORKFLOW.md');
 // GSD_BUNDLED_EXTENSION_PATHS — dynamically discovered bundled extension entry points.
-// Scans the bundled resources directory to find all extensions, then maps paths to
-// agentDir (~/.gsd/agent/extensions/) where initResources() will sync them.
-//
-// Discovery rules (mirroring resource-loader.ts discoverExtensionEntryPaths):
-//   - Top-level .ts/.js files → extension entry point
-//   - Directories with index.ts or index.js → extension entry point
-//   - Directories without either (e.g. shared/, remote-questions/) → skipped
-//
-// Previously this was a hardcoded list that required manual updates whenever
-// extensions were added or removed — causing merge conflicts in forks and
-// falling out of sync with what buildResourceLoader() discovers at runtime.
+// Uses the shared discoverExtensionEntryPaths() to scan the bundled resources
+// directory, then remaps discovered paths to agentDir (~/.gsd/agent/extensions/)
+// where initResources() will sync them.
 const bundledExtDir = join(resourcesDir, 'extensions');
 const agentExtDir = join(agentDir, 'extensions');
-const discoveredExtensionPaths = [];
-if (existsSync(bundledExtDir)) {
-    for (const entry of readdirSync(bundledExtDir, { withFileTypes: true })) {
-        if (entry.isFile() && (entry.name.endsWith('.ts') || entry.name.endsWith('.js'))) {
-            discoveredExtensionPaths.push(join(agentExtDir, entry.name));
-        }
-        else if (entry.isDirectory()) {
-            const srcIndex = existsSync(join(bundledExtDir, entry.name, 'index.ts'))
-                ? 'index.ts'
-                : existsSync(join(bundledExtDir, entry.name, 'index.js'))
-                    ? 'index.js'
-                    : null;
-            if (srcIndex) {
-                discoveredExtensionPaths.push(join(agentExtDir, entry.name, srcIndex));
-            }
-        }
-    }
-}
+const discoveredExtensionPaths = discoverExtensionEntryPaths(bundledExtDir).map((entryPath) => join(agentExtDir, relative(bundledExtDir, entryPath)));
 process.env.GSD_BUNDLED_EXTENSION_PATHS = serializeBundledExtensionPaths(discoveredExtensionPaths);
 // Respect HTTP_PROXY / HTTPS_PROXY / NO_PROXY env vars for all outbound requests.
 // pi-coding-agent's cli.ts sets this, but GSD bypasses that entry point — so we

package/dist/onboarding.js

@@ -9,7 +9,7 @@
  *
  * All steps are skippable. All errors are recoverable. Never crashes boot.
  */
-import { exec } from 'node:child_process';
+import { execFile } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { renderLogo } from './logo.js';
@@ -92,12 +92,13 @@ async function loadPico() {
 // ─── Utilities ────────────────────────────────────────────────────────────────
 /** Open a URL in the system browser (best-effort, non-blocking) */
 function openBrowser(url) {
-    const cmd = process.platform === 'darwin' ? 'open' :
-        process.platform === 'win32' ? 'start' :
-            'xdg-open';
-    exec(`${cmd} "${url}"`, () => {
-        // Ignore errors — user can manually open the URL
-    });
+    if (process.platform === 'win32') {
+        execFile('cmd', ['/c', 'start', '', url], () => { });
+    }
+    else {
+        const cmd = process.platform === 'darwin' ? 'open' : 'xdg-open';
+        execFile(cmd, [url], () => { });
+    }
 }
 /** Check if an error is a clack cancel signal */
 function isCancelError(p, err) {

package/dist/remote-questions-config.js

@@ -8,10 +8,15 @@
  * JS to uncompiled .ts fail at runtime (#592).
  */
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
-import { dirname } from "node:path";
-import { getGlobalGSDPreferencesPath } from "./resources/extensions/gsd/preferences.js";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+// Inlined from preferences.ts to avoid crossing the compiled/uncompiled
+// boundary — this file is compiled by tsc, but preferences.ts is loaded
+// via jiti at runtime. Importing it as .js fails because no .js exists
+// in dist/. See #592, #1110.
+const GLOBAL_PREFERENCES_PATH = join(homedir(), ".gsd", "preferences.md");
 export function saveRemoteQuestionsConfig(channel, channelId) {
-    const prefsPath = getGlobalGSDPreferencesPath();
+    const prefsPath = GLOBAL_PREFERENCES_PATH;
     const block = [
         "remote_questions:",
         `  channel: ${channel}`,

package/dist/resource-loader.d.ts

@@ -1,5 +1,5 @@
 import { DefaultResourceLoader } from '@gsd/pi-coding-agent';
-export declare function discoverExtensionEntryPaths(extensionsDir: string): string[];
+export { discoverExtensionEntryPaths } from './extension-discovery.js';
 export declare function readManagedResourceVersion(agentDir: string): string | null;
 export declare function getNewerManagedResourceVersion(agentDir: string, currentVersion: string): string | null;
 /**
@@ -18,9 +18,4 @@ export declare function getNewerManagedResourceVersion(agentDir: string, current
  * Inspectable: `ls ~/.gsd/agent/extensions/`
  */
 export declare function initResources(agentDir: string): void;
-/**
- * Constructs a DefaultResourceLoader that loads extensions from both
- * ~/.gsd/agent/extensions/ (GSD's default) and ~/.pi/agent/extensions/ (pi's default).
- * This allows users to use extensions from either location.
- */
 export declare function buildResourceLoader(agentDir: string): DefaultResourceLoader;

package/dist/resource-loader.js

@@ -4,6 +4,7 @@ import { chmodSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rm
 import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { compareSemver } from './update-check.js';
+import { discoverExtensionEntryPaths } from './extension-discovery.js';
 // Resolve resources directory — prefer dist/resources/ (stable, set at build time)
 // over src/resources/ (live working tree, changes with git branch).
 //
@@ -18,56 +19,7 @@ const srcResources = join(packageRoot, 'src', 'resources');
 const resourcesDir = existsSync(distResources) ? distResources : srcResources;
 const bundledExtensionsDir = join(resourcesDir, 'extensions');
 const resourceVersionManifestName = 'managed-resources.json';
-function isExtensionFile(name) {
-    return name.endsWith('.ts') || name.endsWith('.js');
-}
-function resolveExtensionEntries(dir) {
-    const packageJsonPath = join(dir, 'package.json');
-    if (existsSync(packageJsonPath)) {
-        try {
-            const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
-            const declared = pkg?.pi?.extensions;
-            if (Array.isArray(declared)) {
-                const resolved = declared
-                    .filter((entry) => typeof entry === 'string')
-                    .map((entry) => resolve(dir, entry))
-                    .filter((entry) => existsSync(entry));
-                if (resolved.length > 0) {
-                    return resolved;
-                }
-            }
-        }
-        catch {
-            // Ignore malformed manifests and fall back to index.ts/index.js discovery.
-        }
-    }
-    const indexTs = join(dir, 'index.ts');
-    if (existsSync(indexTs)) {
-        return [indexTs];
-    }
-    const indexJs = join(dir, 'index.js');
-    if (existsSync(indexJs)) {
-        return [indexJs];
-    }
-    return [];
-}
-export function discoverExtensionEntryPaths(extensionsDir) {
-    if (!existsSync(extensionsDir)) {
-        return [];
-    }
-    const discovered = [];
-    for (const entry of readdirSync(extensionsDir, { withFileTypes: true })) {
-        const entryPath = join(extensionsDir, entry.name);
-        if ((entry.isFile() || entry.isSymbolicLink()) && isExtensionFile(entry.name)) {
-            discovered.push(entryPath);
-            continue;
-        }
-        if (entry.isDirectory() || entry.isSymbolicLink()) {
-            discovered.push(...resolveExtensionEntries(entryPath));
-        }
-    }
-    return discovered;
-}
+export { discoverExtensionEntryPaths } from './extension-discovery.js';
 function getExtensionKey(entryPath, extensionsDir) {
     const relPath = relative(extensionsDir, entryPath);
     return relPath.split(/[\\/]/)[0];
@@ -76,12 +28,16 @@ function getManagedResourceManifestPath(agentDir) {
     return join(agentDir, resourceVersionManifestName);
 }
 function getBundledGsdVersion() {
+    // Prefer GSD_VERSION env var (set once by loader.ts) to avoid re-reading package.json
+    if (process.env.GSD_VERSION && process.env.GSD_VERSION !== '0.0.0') {
+        return process.env.GSD_VERSION;
+    }
     try {
         const pkg = JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf-8'));
         return typeof pkg?.version === 'string' ? pkg.version : '0.0.0';
     }
     catch {
-        return process.env.GSD_VERSION || '0.0.0';
+        return '0.0.0';
     }
 }
 function writeManagedResourceManifest(agentDir) {
@@ -136,6 +92,29 @@ function makeTreeWritable(dirPath) {
         }
     }
 }
+/**
+ * Syncs a single bundled resource directory into the agent directory.
+ *
+ * 1. Makes the destination writable (handles Nix store read-only copies).
+ * 2. Removes destination subdirs that exist in source to clear stale files,
+ *    while preserving user-created directories.
+ * 3. Copies source into destination.
+ * 4. Makes the result writable for the next upgrade cycle.
+ */
+function syncResourceDir(srcDir, destDir) {
+    makeTreeWritable(destDir);
+    if (existsSync(srcDir)) {
+        for (const entry of readdirSync(srcDir, { withFileTypes: true })) {
+            if (entry.isDirectory()) {
+                const target = join(destDir, entry.name);
+                if (existsSync(target))
+                    rmSync(target, { recursive: true, force: true });
+            }
+        }
+        cpSync(srcDir, destDir, { recursive: true, force: true });
+        makeTreeWritable(destDir);
+    }
+}
 /**
  * Syncs all bundled resources to agentDir (~/.gsd/agent/) on every launch.
  *
@@ -153,50 +132,19 @@ function makeTreeWritable(dirPath) {
  */
 export function initResources(agentDir) {
     mkdirSync(agentDir, { recursive: true });
-    // Sync extensions — clean bundled subdirs first to remove stale leftover files,
-    // then overwrite so updates land on next launch. Only bundled subdirs are removed;
-    // user-created extension directories are preserved.
-    const destExtensions = join(agentDir, 'extensions');
-    makeTreeWritable(destExtensions);
-    for (const entry of readdirSync(bundledExtensionsDir, { withFileTypes: true })) {
-        if (entry.isDirectory()) {
-            const target = join(destExtensions, entry.name);
-            if (existsSync(target))
-                rmSync(target, { recursive: true, force: true });
-        }
-    }
-    cpSync(bundledExtensionsDir, destExtensions, { recursive: true, force: true });
-    makeTreeWritable(destExtensions);
-    // Sync agents
-    const destAgents = join(agentDir, 'agents');
-    const srcAgents = join(resourcesDir, 'agents');
-    if (existsSync(srcAgents)) {
-        makeTreeWritable(destAgents);
-        for (const entry of readdirSync(srcAgents, { withFileTypes: true })) {
-            if (entry.isDirectory()) {
-                const target = join(destAgents, entry.name);
-                if (existsSync(target))
-                    rmSync(target, { recursive: true, force: true });
-            }
-        }
-        cpSync(srcAgents, destAgents, { recursive: true, force: true });
-        makeTreeWritable(destAgents);
-    }
-    // Sync skills
-    const destSkills = join(agentDir, 'skills');
-    const srcSkills = join(resourcesDir, 'skills');
-    if (existsSync(srcSkills)) {
-        makeTreeWritable(destSkills);
-        for (const entry of readdirSync(srcSkills, { withFileTypes: true })) {
-            if (entry.isDirectory()) {
-                const target = join(destSkills, entry.name);
-                if (existsSync(target))
-                    rmSync(target, { recursive: true, force: true });
-            }
-        }
-        cpSync(srcSkills, destSkills, { recursive: true, force: true });
-        makeTreeWritable(destSkills);
+    // Skip the full copy when the synced version already matches the running version.
+    // This avoids ~800ms of synchronous rmSync + cpSync on every startup.
+    const currentVersion = getBundledGsdVersion();
+    const managedVersion = readManagedResourceVersion(agentDir);
+    if (managedVersion && managedVersion === currentVersion) {
+        return;
     }
+    syncResourceDir(bundledExtensionsDir, join(agentDir, 'extensions'));
+    syncResourceDir(join(resourcesDir, 'agents'), join(agentDir, 'agents'));
+    syncResourceDir(join(resourcesDir, 'skills'), join(agentDir, 'skills'));
+    // Ensure all newly copied files are owner-writable so the next run can
+    // overwrite them (covers extensions, agents, and skills in one walk).
+    makeTreeWritable(agentDir);
     writeManagedResourceManifest(agentDir);
 }
 /**
@@ -204,10 +152,19 @@ export function initResources(agentDir) {
  * ~/.gsd/agent/extensions/ (GSD's default) and ~/.pi/agent/extensions/ (pi's default).
  * This allows users to use extensions from either location.
  */
+// Cache bundled extension keys at module load — avoids re-scanning the extensions
+// directory in buildResourceLoader() (already scanned by loader.ts for env var).
+let _bundledExtensionKeys = null;
+function getBundledExtensionKeys() {
+    if (!_bundledExtensionKeys) {
+        _bundledExtensionKeys = new Set(discoverExtensionEntryPaths(bundledExtensionsDir).map((entryPath) => getExtensionKey(entryPath, bundledExtensionsDir)));
+    }
+    return _bundledExtensionKeys;
+}
 export function buildResourceLoader(agentDir) {
     const piAgentDir = join(homedir(), '.pi', 'agent');
     const piExtensionsDir = join(piAgentDir, 'extensions');
-    const bundledKeys = new Set(discoverExtensionEntryPaths(bundledExtensionsDir).map((entryPath) => getExtensionKey(entryPath, bundledExtensionsDir)));
+    const bundledKeys = getBundledExtensionKeys();
     const piExtensionPaths = discoverExtensionEntryPaths(piExtensionsDir).filter((entryPath) => !bundledKeys.has(getExtensionKey(entryPath, piExtensionsDir)));
     return new DefaultResourceLoader({
         agentDir,

package/dist/resources/extensions/ask-user-questions.ts

@@ -10,6 +10,7 @@
  */
 
 import type { ExtensionAPI } from "@gsd/pi-coding-agent";
+import { sanitizeError } from "./shared/sanitize.js";
 import { Text } from "@gsd/pi-tui";
 import { Type } from "@sinclair/typebox";
 import {
@@ -17,7 +18,7 @@ import {
 	type Question,
 	type QuestionOption,
 	type RoundResult,
-} from "./shared/interview-ui.js";
+} from "./shared/mod.js";
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
@@ -80,7 +81,7 @@ function errorResult(
 	questions: Question[] = [],
 ): { content: { type: "text"; text: string }[]; details: AskUserQuestionsDetails } {
 	return {
-		content: [{ type: "text", text: message }],
+		content: [{ type: "text", text: sanitizeError(message) }],
 		details: { questions, response: null, cancelled: true },
 	};
 }

package/dist/resources/extensions/bg-shell/bg-shell-command.ts

@@ -0,0 +1,219 @@
+/**
+ * /bg slash command registration — interactive process manager overlay and CLI subcommands.
+ */
+
+import type { ExtensionAPI } from "@gsd/pi-coding-agent";
+import { Key } from "@gsd/pi-tui";
+import { shortcutDesc } from "../shared/terminal.js";
+
+import {
+	processes,
+	killProcess,
+	getGroupStatus,
+	cleanupAll,
+} from "./process-manager.js";
+import {
+	generateDigest,
+	getOutput,
+	formatDigestText,
+} from "./output-formatter.js";
+import { formatUptime } from "./utilities.js";
+import { BgManagerOverlay } from "./overlay.js";
+
+import type { BgShellSharedState } from "./index.js";
+
+export function registerBgShellCommand(pi: ExtensionAPI, state: BgShellSharedState): void {
+	pi.registerCommand("bg", {
+		description: "Manage background processes: /bg [list|output|kill|killall|groups] [id]",
+
+		getArgumentCompletions: (prefix: string) => {
+			const subcommands = ["list", "output", "kill", "killall", "groups", "digest"];
+			const parts = prefix.trim().split(/\s+/);
+
+			if (parts.length <= 1) {
+				return subcommands
+					.filter(cmd => cmd.startsWith(parts[0] ?? ""))
+					.map(cmd => ({ value: cmd, label: cmd }));
+			}
+
+			if (parts[0] === "output" || parts[0] === "kill" || parts[0] === "digest") {
+				const idPrefix = parts[1] ?? "";
+				return Array.from(processes.values())
+					.filter(p => p.id.startsWith(idPrefix))
+					.map(p => ({
+						value: `${parts[0]} ${p.id}`,
+						label: `${p.id} — ${p.label}`,
+					}));
+			}
+
+			return [];
+		},
+
+		handler: async (args, ctx) => {
+			const parts = args.trim().split(/\s+/);
+			const sub = parts[0] || "list";
+
+			if (sub === "list" || sub === "") {
+				if (processes.size === 0) {
+					ctx.ui.notify("No background processes.", "info");
+					return;
+				}
+
+				if (!ctx.hasUI) {
+					const lines = Array.from(processes.values()).map(p => {
+						const statusIcon = p.alive
+							? (p.status === "ready" ? "✓" : p.status === "error" ? "✗" : "⋯")
+							: "○";
+						const uptime = formatUptime(Date.now() - p.startedAt);
+						const portInfo = p.ports.length > 0 ? ` :${p.ports.join(",")}` : "";
+						return `${p.id}  ${statusIcon} ${p.status}  ${uptime}  ${p.label}  [${p.processType}]${portInfo}`;
+					});
+					ctx.ui.notify(lines.join("\n"), "info");
+					return;
+				}
+
+				await ctx.ui.custom<void>(
+					(tui, theme, _kb, done) => {
+						return new BgManagerOverlay(tui, theme, () => {
+							done();
+							state.refreshWidget();
+						});
+					},
+					{
+						overlay: true,
+						overlayOptions: {
+							width: "60%",
+							minWidth: 50,
+							maxHeight: "70%",
+							anchor: "center",
+						},
+					},
+				);
+				return;
+			}
+
+			if (sub === "output" || sub === "digest") {
+				const id = parts[1];
+				if (!id) {
+					ctx.ui.notify(`Usage: /bg ${sub} <id>`, "error");
+					return;
+				}
+				const bg = processes.get(id);
+				if (!bg) {
+					ctx.ui.notify(`No process with id '${id}'`, "error");
+					return;
+				}
+
+				if (!ctx.hasUI) {
+					if (sub === "digest") {
+						const digest = generateDigest(bg);
+						ctx.ui.notify(formatDigestText(bg, digest), "info");
+					} else {
+						const output = getOutput(bg, { stream: "both", tail: 50 });
+						ctx.ui.notify(output || "(no output)", "info");
+					}
+					return;
+				}
+
+				await ctx.ui.custom<void>(
+					(tui, theme, _kb, done) => {
+						const overlay = new BgManagerOverlay(tui, theme, () => {
+							done();
+							state.refreshWidget();
+						});
+						const procs = Array.from(processes.values());
+						const idx = procs.findIndex(p => p.id === id);
+						if (idx >= 0) overlay.selectAndView(idx);
+						return overlay;
+					},
+					{
+						overlay: true,
+						overlayOptions: {
+							width: "60%",
+							minWidth: 50,
+							maxHeight: "70%",
+							anchor: "center",
+						},
+					},
+				);
+				return;
+			}
+
+			if (sub === "kill") {
+				const id = parts[1];
+				if (!id) {
+					ctx.ui.notify("Usage: /bg kill <id>", "error");
+					return;
+				}
+				const bg = processes.get(id);
+				if (!bg) {
+					ctx.ui.notify(`No process with id '${id}'`, "error");
+					return;
+				}
+				killProcess(id, "SIGTERM");
+				await new Promise(r => setTimeout(r, 300));
+				if (bg.alive) {
+					killProcess(id, "SIGKILL");
+					await new Promise(r => setTimeout(r, 200));
+				}
+				if (!bg.alive) processes.delete(id);
+				ctx.ui.notify(`Killed process ${id} (${bg.label})`, "info");
+				return;
+			}
+
+			if (sub === "killall") {
+				const count = processes.size;
+				cleanupAll();
+				ctx.ui.notify(`Killed ${count} background process(es)`, "info");
+				return;
+			}
+
+			if (sub === "groups") {
+				const groups = new Set<string>();
+				for (const p of processes.values()) {
+					if (p.group) groups.add(p.group);
+				}
+				if (groups.size === 0) {
+					ctx.ui.notify("No process groups defined.", "info");
+					return;
+				}
+				const lines = Array.from(groups).map(g => {
+					const gs = getGroupStatus(g);
+					const icon = gs.healthy ? "✓" : "✗";
+					const procs = gs.processes.map(p => `${p.id}(${p.status})`).join(", ");
+					return `${icon} ${g}: ${procs}`;
+				});
+				ctx.ui.notify(lines.join("\n"), "info");
+				return;
+			}
+
+			ctx.ui.notify("Usage: /bg [list|output|digest|kill|killall|groups] [id]", "info");
+		},
+	});
+
+	// ── Ctrl+Alt+B shortcut ──────────────────────────────────────────────
+
+	pi.registerShortcut(Key.ctrlAlt("b"), {
+		description: shortcutDesc("Open background process manager", "/bg"),
+		handler: async (ctx) => {
+			state.latestCtx = ctx;
+			await ctx.ui.custom<void>(
+				(tui, theme, _kb, done) => {
+					return new BgManagerOverlay(tui, theme, () => {
+						done();
+						state.refreshWidget();
+					});
+				},
+				{
+					overlay: true,
+					overlayOptions: {
+						width: "60%",
+						minWidth: 50,
+						maxHeight: "70%",
+						anchor: "center",
+					},
+				},
+			);
+		},
+	});
+}