@phnx-labs/agents-cli 1.20.35 → 1.20.36

package/dist/lib/mcp.js

@@ -34,6 +34,18 @@ export function parseMcpServerConfig(filePath) {
     }
     return validateMcpYamlConfig(parsed);
 }
+/**
+ * Validate an MCP server name. Rejects names that could be misinterpreted as
+ * command-line options or that contain characters unsafe for argv/identifier use.
+ */
+export function validateMcpServerName(name) {
+    if (name.startsWith('-')) {
+        throw new Error(`Invalid MCP server name '${name}': names cannot start with '-'`);
+    }
+    if (/[\s\0-\x1f\x7f]/.test(name)) {
+        throw new Error(`Invalid MCP server name '${name}': names cannot contain whitespace or control characters`);
+    }
+}
 function validateMcpYamlConfig(parsed) {
     if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
         return null;
@@ -41,6 +53,7 @@ function validateMcpYamlConfig(parsed) {
     const config = parsed;
     if (typeof config.name !== 'string' || config.name.length === 0)
         return null;
+    validateMcpServerName(config.name);
     if (config.transport !== 'stdio' && config.transport !== 'http')
         return null;
     const result = {
@@ -205,12 +218,12 @@ function installMcpViaClaude(binaryPath, server, versionHome) {
                 envArgs.push('--env', `${key}=${value}`);
             }
         }
-        // claude mcp add --scope user --transport stdio <name> [--env K=V]... -- <cmd> [args...]
+        // claude mcp add --scope user --transport stdio [--env K=V]... -- <name> <cmd> [args...]
         const args = [
             'mcp', 'add', '--scope', 'user', '--transport', 'stdio',
-            server.name,
             ...envArgs,
             '--',
+            server.name,
             server.config.command,
             ...(server.config.args || [])
         ];
@@ -222,8 +235,8 @@ function installMcpViaClaude(binaryPath, server, versionHome) {
         });
     }
     else {
-        // claude mcp add --scope user --transport http <name> <url>
-        execFileSync(binaryPath, ['mcp', 'add', '--scope', 'user', '--transport', 'http', server.name, server.config.url], {
+        // claude mcp add --scope user --transport http -- <name> <url>
+        execFileSync(binaryPath, ['mcp', 'add', '--scope', 'user', '--transport', 'http', '--', server.name, server.config.url], {
             stdio: 'pipe',
             timeout: 30000,
             env: execEnv,
@@ -237,10 +250,11 @@ function installMcpViaClaude(binaryPath, server, versionHome) {
  */
 function installMcpViaCodex(binaryPath, server, versionHome) {
     if (server.config.transport === 'stdio') {
-        // codex mcp add <name> -- <cmd> [args...]
+        // codex mcp add -- <name> <cmd> [args...]
         const args = [
-            'mcp', 'add', server.name,
+            'mcp', 'add',
             '--',
+            server.name,
             server.config.command,
             ...(server.config.args || [])
         ];
@@ -272,11 +286,12 @@ export async function registerMcpCommandToTargets(targets, name, commandSpec, sc
 }
 function registerMcpCommand(agentId, name, commandSpec, scope, transport, options = {}) {
     try {
+        validateMcpServerName(name);
         const bin = options.binary || AGENTS[agentId].cliCommand;
         const commandArgs = [commandSpec.command, ...commandSpec.args];
         const args = agentId === 'claude'
-            ? ['mcp', 'add', '--transport', transport, '--scope', scope, name, '--', ...commandArgs]
-            : ['mcp', 'add', name, '--', ...commandArgs];
+            ? ['mcp', 'add', '--transport', transport, '--scope', scope, '--', name, ...commandArgs]
+            : ['mcp', 'add', '--', name, ...commandArgs];
         const env = options.home ? { ...process.env, HOME: options.home } : process.env;
         execFileSync(bin, args, { stdio: 'pipe', timeout: 30000, env, shell: needsWindowsShell(bin) });
         return { success: true };
@@ -508,6 +523,7 @@ export function installMcpServers(agentId, version, versionHome, mcpNames, optio
  * Write an MCP server config to ~/.agents/mcp/.
  */
 export function writeMcpServerConfig(config) {
+    validateMcpServerName(config.name);
     const mcpDir = getUserMcpDir();
     fs.mkdirSync(mcpDir, { recursive: true });
     const fileName = `${config.name.toLowerCase().replace(/[^a-z0-9]/g, '-')}.yaml`;

package/dist/lib/migrate.d.ts

@@ -25,6 +25,25 @@
  * LEGACY_SYSTEM_DIR" without duplicating data.
  */
 export declare function foldLegacySystemRepo(): void;
+/**
+ * Migrate a legacy single-repo agents.yaml into ~/.agents/agents.yaml.
+ *
+ * The post-fold system dir (~/.agents/.system) is a pull-only mirror of the
+ * npm-shipped defaults. Its agents.yaml is a TRACKED file that readMeta() reads
+ * in place as the defaults base (see SYSTEM_META_FILE in state.ts). Deleting or
+ * moving a tracked file out of the mirror dirties its working tree, which
+ * permanently wedges `agents setup`, `agents sync`, and background auto-pull
+ * ("Working tree has uncommitted changes.") because the mirror sync refuses a
+ * dirty tree. So when agents.yaml is tracked there, treat the mirror as strictly
+ * read-only and leave the file alone.
+ *
+ * Only an UNTRACKED agents.yaml is residue from the pre-split single-repo layout
+ * (or a legacy ~/.agents-system fold) and is safe to move/drop.
+ *
+ * Params default to the real on-disk locations; they are injectable so tests can
+ * drive a fixture tree without touching the user's ~/.agents.
+ */
+export declare function migrateAgentsYaml(systemDir?: string, userDir?: string): void;
 /**
  * Repair self-referential agent binary symlinks.
  *

package/dist/lib/migrate.js

@@ -8,6 +8,9 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import * as yaml from 'yaml';
+import { execSync } from 'child_process';
+import { atomicWriteFileSync } from './fs-atomic.js';
+import { machineId } from './machine-id.js';
 import { AGENTS, agentConfigDirName, findInPath } from './agents.js';
 import { createLink } from './platform/index.js';
 const HOME = process.env.HOME ?? os.homedir();
@@ -79,21 +82,46 @@ export function foldLegacySystemRepo() {
     }
     catch { /* best-effort */ }
 }
+/** True when `relPath` is a file tracked by a git repo rooted at `repoDir`. */
+function isTrackedInGitRepo(repoDir, relPath) {
+    try {
+        execSync(`git ls-files --error-unmatch -- ${relPath}`, { cwd: repoDir, stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        // Not a git repo, or the file is untracked — either way, not tracked.
+        return false;
+    }
+}
 /**
- * Move ~/.agents-system/agents.yaml -> ~/.agents/agents.yaml.
- * No-op if user file already exists or system file absent.
- * (This is also handled inline in state.ts readMeta, but is exposed here
- *  for explicit migration calls from postinstall / CLI entry points.)
+ * Migrate a legacy single-repo agents.yaml into ~/.agents/agents.yaml.
+ *
+ * The post-fold system dir (~/.agents/.system) is a pull-only mirror of the
+ * npm-shipped defaults. Its agents.yaml is a TRACKED file that readMeta() reads
+ * in place as the defaults base (see SYSTEM_META_FILE in state.ts). Deleting or
+ * moving a tracked file out of the mirror dirties its working tree, which
+ * permanently wedges `agents setup`, `agents sync`, and background auto-pull
+ * ("Working tree has uncommitted changes.") because the mirror sync refuses a
+ * dirty tree. So when agents.yaml is tracked there, treat the mirror as strictly
+ * read-only and leave the file alone.
+ *
+ * Only an UNTRACKED agents.yaml is residue from the pre-split single-repo layout
+ * (or a legacy ~/.agents-system fold) and is safe to move/drop.
+ *
+ * Params default to the real on-disk locations; they are injectable so tests can
+ * drive a fixture tree without touching the user's ~/.agents.
  */
-function migrateAgentsYaml() {
-    const src = path.join(SYSTEM_DIR, 'agents.yaml');
-    const dest = path.join(USER_DIR, 'agents.yaml');
+export function migrateAgentsYaml(systemDir = SYSTEM_DIR, userDir = USER_DIR) {
+    const src = path.join(systemDir, 'agents.yaml');
+    const dest = path.join(userDir, 'agents.yaml');
     if (!fs.existsSync(src))
         return;
+    // Tracked in the system mirror → npm-shipped defaults; never mutate. readMeta()
+    // already surfaces it in place, so no user-dir copy is needed either.
+    if (isTrackedInGitRepo(systemDir, 'agents.yaml'))
+        return;
     if (fs.existsSync(dest)) {
-        // User copy is authoritative — drop the stale system leftover. The system
-        // repo (npm-shipped) does not track agents.yaml; any copy here is residue
-        // from the pre-split layout.
+        // User copy is authoritative — drop the untracked stale system leftover.
         try {
             fs.unlinkSync(src);
         }
@@ -101,7 +129,7 @@ function migrateAgentsYaml() {
         return;
     }
     try {
-        fs.mkdirSync(USER_DIR, { recursive: true, mode: 0o700 });
+        fs.mkdirSync(userDir, { recursive: true, mode: 0o700 });
         fs.renameSync(src, dest);
         console.error('Migrated agents.yaml to ~/.agents/');
     }
@@ -656,22 +684,31 @@ function migratePermissionSetsToPresets() {
  * switching is owned by `agents use`, not the migrator.
  */
 function repairAgentConfigSymlinks() {
-    let yaml;
-    try {
-        yaml = fs.readFileSync(path.join(USER_DIR, 'agents.yaml'), 'utf-8');
-    }
-    catch {
-        return;
-    }
-    const agentsBlock = yaml.match(/^agents:\s*\n((?:  [^\n]*\n)+)/m);
-    if (!agentsBlock)
-        return;
+    // Version pins live in the per-device file post-split (~/.agents/devices/<machine>/
+    // agents.yaml); central agents.yaml may still carry them mid-transition. Read
+    // device first (authoritative), then central, first-seen-agent wins.
     const defaults = [];
-    for (const line of agentsBlock[1].split('\n')) {
-        const m = line.match(/^\s+([a-z][a-z0-9_-]*):\s*([^\s#]+)/);
-        if (m)
-            defaults.push({ agent: m[1], version: m[2] });
-    }
+    const collectPins = (file) => {
+        let text;
+        try {
+            text = fs.readFileSync(file, 'utf-8');
+        }
+        catch {
+            return;
+        }
+        const block = text.match(/^agents:\s*\n((?:  [^\n]*\n)+)/m);
+        if (!block)
+            return;
+        for (const line of block[1].split('\n')) {
+            const m = line.match(/^\s+([a-z][a-z0-9_-]*):\s*([^\s#]+)/);
+            if (m && !defaults.some((d) => d.agent === m[1]))
+                defaults.push({ agent: m[1], version: m[2] });
+        }
+    };
+    collectPins(path.join(USER_DIR, 'devices', machineId(), 'agents.yaml'));
+    collectPins(path.join(USER_DIR, 'agents.yaml'));
+    if (defaults.length === 0)
+        return;
     let repaired = 0;
     for (const { agent, version } of defaults) {
         const configDirName = agent in AGENTS ? agentConfigDirName(agent) : `.${agent}`;
@@ -1625,6 +1662,73 @@ function migrateVersionResourcesToPatterns() {
         console.error('Migrated agents.yaml versions: entries to pattern format');
     }
 }
+/**
+ * Split the machine-local fields out of the committed central agents.yaml so it
+ * becomes portable and syncs cleanly (no more skip-worktree band-aid):
+ *   agents:   -> ~/.agents/devices/<machineId>/agents.yaml  (committed, per-device)
+ *   versions: -> ~/.agents/.history/version-resources.json   (gitignored, machine-local)
+ * Then clear any externally-set skip-worktree bit. Idempotent: no-op once central
+ * carries neither field. Operates on raw YAML (never through state.ts).
+ */
+function migrateSplitDeviceLocalMeta() {
+    const metaFile = path.join(USER_DIR, 'agents.yaml');
+    if (!fs.existsSync(metaFile))
+        return;
+    let meta;
+    try {
+        meta = yaml.parse(fs.readFileSync(metaFile, 'utf-8')) || {};
+    }
+    catch {
+        return;
+    }
+    const agents = meta.agents;
+    const versions = meta.versions;
+    const hasLocal = (!!agents && Object.keys(agents).length > 0) || (!!versions && Object.keys(versions).length > 0);
+    const HEADER = '# agents-cli metadata\n# Auto-generated - do not edit manually\n# https://github.com/phnx-labs/agents-cli\n\n';
+    // Only rewrite central when it actually carries machine-local fields — a
+    // machine whose agents.yaml is already portable-only is left untouched.
+    if (hasLocal) {
+        // agents: -> per-device file (merge, existing device entries win).
+        if (agents && Object.keys(agents).length > 0) {
+            const devicePath = path.join(USER_DIR, 'devices', machineId(), 'agents.yaml');
+            let existing = {};
+            try {
+                const dm = yaml.parse(fs.readFileSync(devicePath, 'utf-8'));
+                if (dm?.agents)
+                    existing = dm.agents;
+            }
+            catch { /* absent */ }
+            fs.mkdirSync(path.dirname(devicePath), { recursive: true });
+            atomicWriteFileSync(devicePath, HEADER + yaml.stringify({ agents: { ...agents, ...existing } }));
+        }
+        // versions: -> machine-local history JSON (merge, existing wins).
+        if (versions && Object.keys(versions).length > 0) {
+            const vrPath = path.join(USER_DIR, '.history', 'version-resources.json');
+            let existing = {};
+            try {
+                existing = JSON.parse(fs.readFileSync(vrPath, 'utf-8')) || {};
+            }
+            catch { /* absent */ }
+            fs.mkdirSync(path.dirname(vrPath), { recursive: true });
+            atomicWriteFileSync(vrPath, JSON.stringify({ ...versions, ...existing }, null, 2) + '\n');
+        }
+        // Strip machine-local fields from central and rewrite (portable only) — after
+        // the device/history writes above, so a crash never loses data.
+        delete meta.agents;
+        delete meta.versions;
+        atomicWriteFileSync(metaFile, HEADER + yaml.stringify(meta));
+    }
+    // Always clear any skip-worktree bit (idempotent, best-effort) so agents.yaml
+    // syncs cleanly on every machine — even one that had nothing to split. Runs
+    // after any rewrite so the tracked content already matches the split shape.
+    try {
+        execSync('git update-index --no-skip-worktree agents.yaml', { cwd: USER_DIR, stdio: 'ignore' });
+    }
+    catch { /* not a git repo / bit not set */ }
+    if (hasLocal) {
+        console.error('Split agents.yaml: agents: -> devices/, versions: -> .history/version-resources.json');
+    }
+}
 /**
  * Rename the legacy `extras-extras/` plugin-marketplace dir to `agents-extras/`
  * inside every installed agent version-home, and rewrite cross-references in
@@ -1805,6 +1909,10 @@ export async function runMigration() {
     foldUserHooksYamlIntoAgentsYaml();
     foldBrowserProfilesIntoAgentsYaml();
     migrateVersionResourcesToPatterns();
+    // Split machine-local fields (agents:/versions:) out of the committed central
+    // agents.yaml. After migrateVersionResourcesToPatterns so versions: is already
+    // in pattern form when it moves to the history file.
+    migrateSplitDeviceLocalMeta();
     // Bucket moves: collapse runtime state into ~/.agents/.history and ~/.agents/.cache.
     migrateRuntimeToHistory();
     migrateRuntimeToCache();

package/dist/lib/overdue.js

@@ -44,6 +44,9 @@ export function detectOverdueJobs(now = new Date()) {
     for (const job of listJobs()) {
         if (!job.enabled || job.runOnce)
             continue;
+        // Trigger-only jobs (no cron schedule) never have an expected fire time.
+        if (!job.schedule)
+            continue;
         let expected = null;
         try {
             const cronOptions = { paused: true };

package/dist/lib/picker.d.ts

@@ -8,6 +8,8 @@
 /** Configuration for the interactive picker prompt. */
 export interface PickerConfig<T> {
     message: string;
+    /** Optional dim hint line rendered directly under the header (above the rows). */
+    subtitle?: string;
     items: T[];
     filter: (query: string) => T[];
     labelFor: (item: T, query: string) => string;

package/dist/lib/picker.js

@@ -174,7 +174,10 @@ export function itemPicker(config) {
         const help = previewOpen
             ? chalk.gray(`↑↓ navigate · space: close preview · ⏎ ${enter} · esc: cancel`)
             : chalk.gray(`↑↓ navigate${hasPreview ? ' · space: preview' : ''} · ⏎ ${enter} · esc: cancel`);
-        const parts = [header, page];
+        const parts = [header];
+        if (cfg.subtitle)
+            parts.push(cfg.subtitle);
+        parts.push(page);
         if (results.length === 0) {
             parts.push(chalk.gray(`  ${cfg.emptyMessage ?? 'No matches.'}`));
         }

package/dist/lib/platform/exec.d.ts

@@ -17,3 +17,49 @@ export declare function needsWindowsShell(binary: string, platform?: NodeJS.Plat
  * shell would actually run, matching `which` semantics on POSIX.
  */
 export declare function findExecutable(name: string, platform?: NodeJS.Platform): string | null;
+/**
+ * Absolute path of the POSIX shell for `sh -c <command string>` composition.
+ * `/bin/sh` on POSIX; on Windows there is no /bin/sh, so resolve Git's
+ * `sh.exe`/`bash.exe` from PATH (present wherever Git for Windows is — dev
+ * boxes and the GitHub windows runners alike). Falls back to the bare name so
+ * a missing shell surfaces as a clear spawn ENOENT on `sh` rather than a
+ * misleading one on `/bin/sh`.
+ */
+export declare function posixShellPath(platform?: NodeJS.Platform): string;
+/**
+ * Quote one argument for a Windows `cmd.exe` command line, as built by Node's
+ * `spawn(..., { shell: true })` on win32 (the `.cmd` agent shims, `agents secrets
+ * exec`, ...). cmd.exe does NO quoting of its own, so an unquoted arg with a space
+ * is split into several args, and a cmd metacharacter (`&|<>()^`) would be
+ * interpreted by the shell. We wrap any arg with whitespace, a quote, or a
+ * metacharacter in double quotes and escape embedded quotes / trailing
+ * backslashes per the CommandLineToArgvW rules, so the *child's* argv parse
+ * reconstructs the original argument.
+ *
+ * CAVEAT: cmd.exe expands `%VAR%` (always) and `!VAR!` (under delayed expansion)
+ * BEFORE argv parsing, and double-quoting does NOT suppress `%`/`!` (the
+ * "BatBadBut" / CVE-2024-1874 class). We deliberately do not escape `%`/`!`:
+ * the callers here run a command whose `%`/`!`-bearing tokens are the caller's
+ * own (an agent prompt against the caller's shell, a bundle the caller owns), so
+ * caller-controlled `%`/`!` is not a privilege boundary. If that ever changes
+ * (composing an untrusted command line), route through a shell that disables
+ * expansion rather than relying on this quoter. An empty arg becomes `""`.
+ */
+export declare function quoteWin32ExecArg(arg: string): string;
+/**
+ * Compose a DEP0190-safe Windows shell command line from a command and its args.
+ *
+ * Node's `spawn(cmd, args, { shell: true })` on win32 concatenates `cmd` and
+ * every element of `args` into a single cmd.exe line WITHOUT escaping — that is
+ * both Node's DEP0190 deprecation (a future hard error) and a real injection
+ * surface, since user-controlled text (an agent prompt, a secrets-exec command)
+ * flows through `args`. Passing the fully-composed line as the SOLE `command`
+ * with an EMPTY args array sidesteps both: we quote every token with
+ * `quoteWin32ExecArg` so the child's CommandLineToArgvW parse reconstructs the
+ * exact original argv, and Node has no args array left to concatenate.
+ *
+ * Callers spawn the result as `spawn(line, [], { shell: true })`. A simple arg
+ * (no whitespace/quote/metachar) is passed through untouched, so the composed
+ * line is byte-identical to the old unquoted join for the common case.
+ */
+export declare function composeWin32CommandLine(command: string, args: string[]): string;

package/dist/lib/platform/exec.js

@@ -39,3 +39,77 @@ export function findExecutable(name, platform = process.platform) {
         return null;
     }
 }
+/**
+ * Absolute path of the POSIX shell for `sh -c <command string>` composition.
+ * `/bin/sh` on POSIX; on Windows there is no /bin/sh, so resolve Git's
+ * `sh.exe`/`bash.exe` from PATH (present wherever Git for Windows is — dev
+ * boxes and the GitHub windows runners alike). Falls back to the bare name so
+ * a missing shell surfaces as a clear spawn ENOENT on `sh` rather than a
+ * misleading one on `/bin/sh`.
+ */
+export function posixShellPath(platform = process.platform) {
+    if (platform !== 'win32')
+        return '/bin/sh';
+    return findExecutable('sh', platform) ?? findExecutable('bash', platform) ?? 'sh';
+}
+/**
+ * Quote one argument for a Windows `cmd.exe` command line, as built by Node's
+ * `spawn(..., { shell: true })` on win32 (the `.cmd` agent shims, `agents secrets
+ * exec`, ...). cmd.exe does NO quoting of its own, so an unquoted arg with a space
+ * is split into several args, and a cmd metacharacter (`&|<>()^`) would be
+ * interpreted by the shell. We wrap any arg with whitespace, a quote, or a
+ * metacharacter in double quotes and escape embedded quotes / trailing
+ * backslashes per the CommandLineToArgvW rules, so the *child's* argv parse
+ * reconstructs the original argument.
+ *
+ * CAVEAT: cmd.exe expands `%VAR%` (always) and `!VAR!` (under delayed expansion)
+ * BEFORE argv parsing, and double-quoting does NOT suppress `%`/`!` (the
+ * "BatBadBut" / CVE-2024-1874 class). We deliberately do not escape `%`/`!`:
+ * the callers here run a command whose `%`/`!`-bearing tokens are the caller's
+ * own (an agent prompt against the caller's shell, a bundle the caller owns), so
+ * caller-controlled `%`/`!` is not a privilege boundary. If that ever changes
+ * (composing an untrusted command line), route through a shell that disables
+ * expansion rather than relying on this quoter. An empty arg becomes `""`.
+ */
+export function quoteWin32ExecArg(arg) {
+    if (arg.length > 0 && !/[\s"&|<>()^]/.test(arg))
+        return arg;
+    let result = '"';
+    let backslashes = 0;
+    for (const ch of arg) {
+        if (ch === '\\') {
+            backslashes += 1;
+            continue;
+        }
+        if (ch === '"') {
+            // Double the run of backslashes, then escape this quote.
+            result += '\\'.repeat(backslashes * 2 + 1) + '"';
+            backslashes = 0;
+            continue;
+        }
+        result += '\\'.repeat(backslashes) + ch;
+        backslashes = 0;
+    }
+    // Trailing backslashes precede the closing quote → must be doubled.
+    result += '\\'.repeat(backslashes * 2) + '"';
+    return result;
+}
+/**
+ * Compose a DEP0190-safe Windows shell command line from a command and its args.
+ *
+ * Node's `spawn(cmd, args, { shell: true })` on win32 concatenates `cmd` and
+ * every element of `args` into a single cmd.exe line WITHOUT escaping — that is
+ * both Node's DEP0190 deprecation (a future hard error) and a real injection
+ * surface, since user-controlled text (an agent prompt, a secrets-exec command)
+ * flows through `args`. Passing the fully-composed line as the SOLE `command`
+ * with an EMPTY args array sidesteps both: we quote every token with
+ * `quoteWin32ExecArg` so the child's CommandLineToArgvW parse reconstructs the
+ * exact original argv, and Node has no args array left to concatenate.
+ *
+ * Callers spawn the result as `spawn(line, [], { shell: true })`. A simple arg
+ * (no whitespace/quote/metachar) is passed through untouched, so the composed
+ * line is byte-identical to the old unquoted join for the common case.
+ */
+export function composeWin32CommandLine(command, args) {
+    return [command, ...args].map(quoteWin32ExecArg).join(' ');
+}

package/dist/lib/platform/process.d.ts

@@ -9,6 +9,37 @@
  * process counts as success.
  */
 export declare function killTree(pid: number): void;
+/**
+ * Spawn options for a long-lived background child (daemon, detached worker,
+ * sidecar server, fire-and-forget job).
+ *
+ * POSIX: `detached: true` — the child leads its own process group, so it
+ * survives the parent and group kills (`kill(-pid)`) still reach it.
+ *
+ * Windows: the child must not share the launcher's console (a console-close
+ * event when the launcher exits would tear it down, #556) and must not flash
+ * a window. How to get there depends on the child's stdio:
+ *
+ * - All stdio non-inherited ('ignore'/'pipe'): `windowsHide: true`, NOT
+ *   detached. CREATE_NO_WINDOW gives the child its own hidden console that
+ *   every console-subsystem descendant (powershell, git, a .cmd shim's cmd.exe
+ *   wrapper) inherits — no window anywhere down the tree. `detached` would
+ *   defeat it: DETACHED_PROCESS makes CreateProcess ignore CREATE_NO_WINDOW.
+ *
+ * - Any stdio slot redirected to an fd (log files — `fdStdio: true`): libuv
+ *   skips CREATE_NO_WINDOW whenever a stdio fd is inherited, so windowsHide
+ *   cannot engage and a non-detached child would share the launcher's console
+ *   and die with it. Keep DETACHED_PROCESS: the child runs console-less and
+ *   windowless; its console-tool spawns stay invisible because the leaf call
+ *   sites pass their own `windowsHide` with piped stdio.
+ */
+export declare function backgroundSpawnOptions(opts?: {
+    fdStdio?: boolean;
+    platform?: NodeJS.Platform;
+}): {
+    detached: boolean;
+    windowsHide: boolean;
+};
 /**
  * Is a process with this PID currently alive?
  *

package/dist/lib/platform/process.js

@@ -17,7 +17,7 @@ export function killTree(pid) {
         return;
     if (process.platform === 'win32') {
         try {
-            execFileSync('taskkill', ['/F', '/T', '/PID', String(pid)], { stdio: 'ignore' });
+            execFileSync('taskkill', ['/F', '/T', '/PID', String(pid)], { stdio: 'ignore', windowsHide: true });
         }
         catch { /* already gone, or no such pid */ }
     }
@@ -28,6 +28,39 @@ export function killTree(pid) {
         catch { /* already gone */ }
     }
 }
+/**
+ * Spawn options for a long-lived background child (daemon, detached worker,
+ * sidecar server, fire-and-forget job).
+ *
+ * POSIX: `detached: true` — the child leads its own process group, so it
+ * survives the parent and group kills (`kill(-pid)`) still reach it.
+ *
+ * Windows: the child must not share the launcher's console (a console-close
+ * event when the launcher exits would tear it down, #556) and must not flash
+ * a window. How to get there depends on the child's stdio:
+ *
+ * - All stdio non-inherited ('ignore'/'pipe'): `windowsHide: true`, NOT
+ *   detached. CREATE_NO_WINDOW gives the child its own hidden console that
+ *   every console-subsystem descendant (powershell, git, a .cmd shim's cmd.exe
+ *   wrapper) inherits — no window anywhere down the tree. `detached` would
+ *   defeat it: DETACHED_PROCESS makes CreateProcess ignore CREATE_NO_WINDOW.
+ *
+ * - Any stdio slot redirected to an fd (log files — `fdStdio: true`): libuv
+ *   skips CREATE_NO_WINDOW whenever a stdio fd is inherited, so windowsHide
+ *   cannot engage and a non-detached child would share the launcher's console
+ *   and die with it. Keep DETACHED_PROCESS: the child runs console-less and
+ *   windowless; its console-tool spawns stay invisible because the leaf call
+ *   sites pass their own `windowsHide` with piped stdio.
+ */
+export function backgroundSpawnOptions(opts = {}) {
+    const platform = opts.platform ?? process.platform;
+    if (platform === 'win32') {
+        return opts.fdStdio
+            ? { detached: true, windowsHide: true }
+            : { detached: false, windowsHide: true };
+    }
+    return { detached: true, windowsHide: false };
+}
 /**
  * Is a process with this PID currently alive?
  *

package/dist/lib/platform/winpath.js

@@ -107,6 +107,7 @@ function runPowerShell(script, extraEnv) {
         encoding: 'utf-8',
         env: extraEnv ? { ...process.env, ...extraEnv } : process.env,
         stdio: ['ignore', 'pipe', 'pipe'],
+        windowsHide: true,
     });
 }
 /** Parse the read script's stdout into the original value kind and RAW value. */
@@ -163,6 +164,7 @@ export function getEffectiveExecutionPolicy() {
         const out = execFileSync('powershell', ['-NoProfile', '-NonInteractive', '-Command', 'Get-ExecutionPolicy'], {
             encoding: 'utf-8',
             stdio: ['ignore', 'pipe', 'pipe'],
+            windowsHide: true,
         }).trim();
         return out || null;
     }

package/dist/lib/plugins.js

@@ -172,16 +172,26 @@ export function loadPluginManifest(pluginRoot) {
     }
 }
 export function validatePluginName(name) {
-    return name.length > 0
-        && !/[/\\]/.test(name)
-        && !name.includes('..')
-        && !name.includes('\0');
+    if (!name || name.length === 0 || name === '.' || name === '..') {
+        return false;
+    }
+    const normalized = path.normalize(name);
+    if (normalized === '.' || normalized === '' || normalized === '..') {
+        return false;
+    }
+    if (/[/\\]/.test(name) || name.includes('\0')) {
+        return false;
+    }
+    if (path.basename(normalized) !== name) {
+        return false;
+    }
+    return true;
 }
 export function assertPluginTargetContained(targetRoot, pluginsDir) {
     const resolvedPluginsDir = path.resolve(pluginsDir);
     const resolvedTargetRoot = path.resolve(targetRoot);
-    if (resolvedTargetRoot !== resolvedPluginsDir
-        && !resolvedTargetRoot.startsWith(`${resolvedPluginsDir}${path.sep}`)) {
+    if (resolvedTargetRoot === resolvedPluginsDir
+        || !resolvedTargetRoot.startsWith(`${resolvedPluginsDir}${path.sep}`)) {
         throw new Error(`Plugin install target escapes plugins directory: ${targetRoot}`);
     }
 }