@phnx-labs/agents-cli 1.22.14 → 1.22.15

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 1.22.15
+
+- **Separate routine definitions from device activation (#2023).** Enable a routine by listing its name in `~/.agents/devices/<hostname>/agents.yaml`; built-in Watchdog setup and `watchdog on|off` now update that host-owned manifest without rewriting the routine definition. Source: `apps/cli/src/lib/routine-activation.ts`, `apps/cli/src/commands/setup-watchdog.ts`.
+
+- **`agents devices list` no longer shows the "Leased boxes" section by default — it moves behind a new `--all` flag (RUSH-2190).** Loading the section routes through crabbox's bundle auto-detect, which scans the keychain and can raise a macOS Touch ID sheet *after* the device table has printed, hanging non-interactive callers (observed: the `.agents-system` SessionStart topology hook). The default list now renders only registered devices, which are reachable without any secrets; the load/mem/headroom columns are unchanged (the stats probe was already broker-only). `agents devices list --all` restores the section; `--no-stats` remains a hard "instant, no provider calls" opt-out even with `--all`. Source: `apps/cli/src/commands/ssh.ts` (`showLeasedBoxesSection`), `apps/cli/src/commands/ssh.test.ts`.
+
+- **Install: `plugin:` prefix on the unified path (Phase 5 packaging).**
+  `agents install plugin:<spec>` uses the same grammar and trust gate as
+  `agents plugins install` (`name@url`, local path, `--allow-exec-surfaces`).
+  Specialized verbs still work; `agents install` is the one add path for mcp,
+  skill, plugin, and GitHub sources. Source: `apps/cli/src/commands/packages.ts`,
+  `apps/cli/src/lib/registry.ts`.
+
 ## 1.22.14
 
 - **`agents secrets view <bundle> --reveal` now resolves a locked keychain bundle

package/README.md

@@ -396,7 +396,7 @@ agents watchdog --nudge    # actually inject "Continue." into the stalled split
 agents watchdog --watch    # daemon loop: a tick every --interval
 ```
 
-`agents watchdog` detects a stalled session, resolves the *exact* terminal split it lives in (tmux, iTerm, VSCodium, or a raw pty), and injects a nudge -- `Continue.` by default, or set `--text`. It's dry by default; `--nudge` acts on a single tick, and `agents watchdog enable` flips global auto-nudge on so `--watch` injects on its own. Steer a single run with `agents watchdog policy <id> off | keep | handsoff`.
+`agents watchdog` detects a stalled session, resolves the *exact* terminal split it lives in (tmux, iTerm, VSCodium, or a raw pty), and injects a nudge -- `Continue.` by default, or set `--text`. It's dry by default; `--nudge` acts on a single tick, and `agents watchdog on|off` enables or disables the built-in routine on this device. `agents setup watchdog` chooses devices. Steer a single run with `agents watchdog policy <id> off | keep | handsoff`.
 
 A stalled session whose tail shows a hard account limit ("You've hit your weekly limit · resets …") is **rotated in place** instead of nudged: the watchdog gates on the same healthy-account selection `agents run auto` makes (zero healthy → one skip event per cooldown window, terminal untouched), injects the harness's exit sequence, relaunches `agents run auto --interactive --session-id <uuid>` in the *same* tab, then replays the old session's resume once the new TUI is live. Default on; `agents watchdog rotate off` disables it (nudging stays on).
 
@@ -921,11 +921,11 @@ agents routines run daily-digest       # Test it now, ignore the schedule
 agents routines logs daily-digest      # Last execution — status + report (add --full for raw stdout)
 agents routines stats                  # Run count, failed, missed, avg/p50/p95 duration — per job or all
 
-# Routines sync to every device; restrict to an allowlist with --devices
+# Definitions sync to every device; activation is stored per hostname
 agents routines add nightly-drain --schedule "0 3 * * *" --agent claude \
-  --devices yosemite-s0,mac-mini --prompt "Drain the local work queue"
+  --prompt "Drain the local work queue"
 
-agents routines devices nightly-drain --set yosemite-s0,mac-mini  # update allowlist
+agents routines devices nightly-drain --set yosemite-s0,mac-mini  # enable on both hosts
 agents routines list --host yosemite-s0                            # query another device
 
 # Signed webhook trigger: Linear issue labeled "agent" fires a routine

package/dist/commands/cloud.js

@@ -7,8 +7,7 @@ import { resolveProvider, getAllProviders, getDefaultProviderId } from '../lib/c
 import { insertTask, updateTaskStatus, getTaskById, listTasks as listStoredTasks, listActiveTasks } from '../lib/cloud/store.js';
 import { renderStream } from '../lib/cloud/stream.js';
 import { MissingTargetError, MAX_IMAGES_PER_DISPATCH } from '../lib/cloud/types.js';
-import { normalizeTriggerEvent, validateTrigger, writeJob, jobExists, GITHUB_TRIGGER_EVENTS } from '../lib/routines.js';
-import { machineId } from '../lib/machine-id.js';
+import { normalizeTriggerEvent, validateTrigger, writeJob, setJobEnabled, jobExists, GITHUB_TRIGGER_EVENTS } from '../lib/routines.js';
 import { emit } from '../lib/events.js';
 import { shareRuntimeEnv } from '../lib/share/config.js';
 /** Map a supported image file extension to its wire mimeType. Rejects anything else. */
@@ -310,16 +309,15 @@ Examples:
             };
             if (repoValues[0])
                 routine.repo = repoValues[0];
-            // --host with --on: the webhook-fired run places on that machine (the
-            // routine carries the placement, and firing pins to THIS device so a
-            // fleet of receivers can't each dispatch a duplicate).
+            // --host controls where the enabled local receiver dispatches the run.
+            // Device activation remains in this receiver's device manifest.
             if (options.host) {
                 routine.host = options.host;
                 if (options.remoteCwd)
                     routine.remoteCwd = options.remoteCwd;
-                routine.devices = [machineId()];
             }
             writeJob(routine);
+            setJobEnabled(routine.name, true);
             if (json) {
                 console.log(JSON.stringify({ ok: true, registered: routineName, trigger }, null, 2));
             }

package/dist/commands/packages.js

@@ -22,7 +22,7 @@ import { discoverWorkflowsFromRepo, installWorkflowCentrally, } from '../lib/wor
 import { discoverSubagentsFromRepo, installSubagentCentrally, } from '../lib/subagents.js';
 import { discoverPermissionsFromRepo, installPermissionSet, } from '../lib/permissions.js';
 import { listInstalledVersions, resolveConfiguredAgentTargets, syncResourcesToVersion, } from '../lib/versions.js';
-import { isInteractiveTerminal, isPromptCancelled, parseCommaSeparatedList, requireDestructiveArg, requireInteractiveSelection, resolveInstalledAgentTargetsAutoInstalling, } from './utils.js';
+import { formatPath, isInteractiveTerminal, isPromptCancelled, parseCommaSeparatedList, requireDestructiveArg, requireInteractiveSelection, resolveInstalledAgentTargetsAutoInstalling, } from './utils.js';
 import { itemPicker } from '../lib/picker.js';
 import { registerMcpCommandToTargets, discoverMcpConfigsFromRepo, installMcpConfigCentrally, } from '../lib/mcp.js';
 export function buildMcpPackageCommand(pkg) {
@@ -435,37 +435,30 @@ the sha256 in the index and abort on mismatch.
     // ==========================================================================
     program
         .command('install <identifier>')
-        .description('Install a package by registry name (mcp:notion), GitHub URL (gh:user/repo), or skill identifier')
+        .description('Install a package: mcp:, skill:, plugin:, or GitHub (gh:user/repo) — one install path (Phase 5)')
         .option('-a, --agents <list>', 'Targets: claude, codex@0.116.0, or cursor@default')
         .option('--types <list>', 'When source is a repo: comma-separated resource types to install (skills,workflows,commands,hooks,permissions,subagents,mcp)')
         .option('--names <list>', 'When source is a repo: comma-separated resource names within the selected types')
         .option('-y, --yes', 'Auto-install any missing agent versions without prompting')
+        .option('--allow-exec-surfaces', 'With plugin: allow plugins that ship hooks/mcp/bin (same as agents plugins install)')
         .addHelpText('after', `
-Install resolves the package type (MCP server, skill, command, hook) and installs to the specified agents. Packages can come from registries (mcp:, skill:), GitHub (gh:user/repo), or direct URLs.
+Install is the unified add path (Phase 5 packaging). Prefix the identifier:
+
+  mcp:<name>       MCP server from a registry
+  skill:<name>     skill from a registry (or gh: fallback)
+  plugin:<spec>    plugin — same grammar as agents plugins install (name@url or path)
+  gh:user/repo     clone a DotAgents / multi-resource repo and install selected types
 
 Examples:
-  # Install an MCP server from a registry
   agents install mcp:notion --agents claude
-
-  # Install skills and commands from GitHub
+  agents install skill:animator --agents claude,codex
+  agents install plugin:my-plugin@https://github.com/user/my-plugin.git
+  agents install plugin:~/Projects/rush-toolkit
   agents install gh:anthropics/skills --agents codex,claude
-
-  # Install using GitHub shorthand
-  agents install gh:user/repo --agents claude@2.1.112
-
-  # Install only specific resource types from a multi-resource repo
   agents install gh:phnx-labs/.agents-system --types skills,workflows --agents claude@all
 
-  # Install specific resources by name
-  agents install gh:phnx-labs/.agents-system --types skills --names animator,composer --agents claude@all
-
-  # Install to all installed agents (uses defaults or prompts)
-  agents install mcp:postgres
-
-When to use:
-  - After search: 'agents search notion' then 'agents install mcp:notion'
-  - Team setup: 'agents install gh:team/resources' to sync everyone's tooling
-  - Quick MCP add: 'agents install mcp:<name>' when you know the package name
+Specialized verbs still work (agents plugins install, agents skills add) and
+delegate to the same underlying installers.
 `)
         .action(async (identifier, options) => {
         const spinner = ora('Resolving package...').start();
@@ -473,10 +466,85 @@ When to use:
             const resolved = await resolvePackage(identifier);
             if (!resolved) {
                 spinner.fail('Package not found');
-                console.log(chalk.gray('\nTip: Use explicit prefix (mcp:, skill:, gh:) or check the identifier.'));
+                console.log(chalk.gray('\nTip: Use explicit prefix (mcp:, skill:, plugin:, gh:) or check the identifier.'));
                 process.exit(1);
             }
             spinner.succeed(`Found ${resolved.type} package`);
+            if (resolved.type === 'plugin') {
+                spinner.stop();
+                const spec = resolved.pluginSpec ?? resolved.source;
+                console.log(chalk.gray(`Installing plugin from: ${spec}`));
+                const { installPlugin, getPlugin, inspectPluginCapabilities, pluginCapabilityLabels, parseInstallSpec, checkPluginDependencies, hasPluginExecSurfaces, pluginSupportsAgent, syncPluginToVersion, pluginResourceGroups, } = await import('../lib/plugins.js');
+                const { listInstalledVersions, getGlobalDefault, getVersionHomePath, syncResourcesToVersion } = await import('../lib/versions.js');
+                const { agentLabel } = await import('../lib/agents.js');
+                let name;
+                let root;
+                try {
+                    const result = await installPlugin(spec);
+                    name = result.name;
+                    root = result.root;
+                }
+                catch (err) {
+                    console.log(chalk.red(`Install failed: ${err.message}`));
+                    process.exit(1);
+                }
+                const plugin = getPlugin(name);
+                if (!plugin) {
+                    console.log(chalk.red(`Installed but could not load plugin '${name}'`));
+                    process.exit(1);
+                }
+                const capabilities = inspectPluginCapabilities(root);
+                const allowExec = options.allowExecSurfaces === true;
+                if (hasPluginExecSurfaces(capabilities) && !allowExec) {
+                    const source = parseInstallSpec(spec).source;
+                    console.error(chalk.red('Install refused: plugin ships executable surfaces:'));
+                    for (const label of pluginCapabilityLabels(capabilities)) {
+                        console.error(`  ${label}`);
+                    }
+                    console.error(`Re-run with --allow-exec-surfaces if you trust the source: ${source}@HEAD`);
+                    fs.rmSync(root, { recursive: true, force: true });
+                    process.exit(1);
+                }
+                const missingDeps = checkPluginDependencies(plugin.manifest);
+                if (missingDeps.length > 0) {
+                    console.log(chalk.yellow(`Warning: missing dependencies: ${missingDeps.join(', ')}`));
+                    console.log(chalk.gray('Install them with: agents install plugin:<name>@<source>'));
+                }
+                // Same sync loop as `agents plugins install` (default version per harness).
+                console.log();
+                let synced = 0;
+                for (const agentId of capableAgents('plugins')) {
+                    if (!pluginSupportsAgent(plugin, agentId))
+                        continue;
+                    const versions = listInstalledVersions(agentId);
+                    if (versions.length === 0)
+                        continue;
+                    const defaultVer = getGlobalDefault(agentId);
+                    const targetVersions = defaultVer ? [defaultVer] : [versions[versions.length - 1]];
+                    for (const version of targetVersions) {
+                        const didSync = allowExec
+                            ? syncPluginToVersion(plugin, agentId, getVersionHomePath(agentId, version), {
+                                allowExecSurfaces: true,
+                            }).success
+                            : syncResourcesToVersion(agentId, version, { plugins: [name] }).plugins.length > 0;
+                        if (didSync) {
+                            console.log(chalk.green(`  Synced to ${agentLabel(agentId)}@${version}`));
+                            synced++;
+                        }
+                    }
+                }
+                if (synced === 0) {
+                    console.log(chalk.gray('  No supported agent versions installed — run "agents use <agent>@<version>" to sync.'));
+                }
+                console.log(chalk.bold(`\nInstalled ${plugin.name} v${plugin.manifest.version} to ${formatPath(root)}`));
+                const groups = pluginResourceGroups(plugin);
+                if (groups.length > 0) {
+                    for (const g of groups) {
+                        console.log(chalk.gray(`  ${g.label}: ${g.items.slice(0, 8).join(', ')}${g.items.length > 8 ? '…' : ''}`));
+                    }
+                }
+                return;
+            }
             if (resolved.type === 'mcp') {
                 // Install MCP server
                 const entry = resolved.mcpEntry;

package/dist/commands/projects.d.ts

@@ -24,11 +24,8 @@ export declare function formatFleetSkippedNote(skipped: string[]): string;
  *
  * `stderr: 'ignore'` is load-bearing, not tidiness. A checkout with no origin
  * makes git print `error: No such remote 'origin'` on ITS stderr, which is the
- * terminal's — the catch below never sees it. That was invisible while this was
- * called once from `add` inside a real repo, and became noise the moment
- * `import --from-factory` started calling it per row: importing 12 registry
- * rows printed two raw git errors between the progress lines. Absence of a
- * remote is an expected answer here (`undefined`), not something to report.
+ * terminal's — the catch below never sees it. Absence of a remote is an
+ * expected answer here (`undefined`), not something to report.
  */
 export declare function originSlug(cwd: string): string | undefined;
 /** One `projects list` row, pre-render. */

package/dist/commands/projects.js

@@ -20,16 +20,15 @@ import { machineId } from '../lib/machine-id.js';
 import { getActiveSessions } from '../lib/session/active.js';
 import { gatherRemoteActive } from '../lib/session/remote-active.js';
 import { gatherRemoteAgentsJson } from '../lib/remote-agents-json.js';
-import { factoryProjectsPath } from '../lib/auto-dispatch.js';
 import { formatFleetWorkspaces, parseRemoteProbe, probeProjectWorkspaces, workspaceTargetsForDef, workspaceWarnings, } from '../lib/project-probe.js';
-import { listProjectDefs, loadProjectDef, writeProjectDef, removeProjectDef, projectDefPath, isSafeProjectName, } from '../lib/projects.js';
+import { listProjectDefs, loadProjectDef, writeProjectDef, removeProjectDef, projectDefPath, isSafeProjectName, validateProjectDef, } from '../lib/projects.js';
 import { rollupSessionsByProject, withDefaultMachine, isDeadStatus, liveDeadSplit, enrichProjectSignals, formatProjectMembersByHost, formatProjectWarnings, } from '../lib/project-status.js';
 import { fetchLinearProjectCounts } from '../lib/linear-project-counts.js';
 import { listLinearProjects, pickLinearProject } from '../lib/linear-projects.js';
 import { checkRepoSlug } from '../lib/project-doctor.js';
 import { formatFocusAreas, readFocusAreas } from '../lib/project-focus.js';
 import { formatVerdict, scheduleVerdict } from '../lib/project-schedule.js';
-import { buildFactoryImportCandidates, buildLinearImportCandidates, validateImportOpts, } from '../lib/project-import.js';
+import { buildLinearImportCandidates, validateImportOpts, } from '../lib/project-import.js';
 /** Recursion guard: a peer answering a probe fan-out never re-fans-out itself. */
 export const PROJECTS_NO_FANOUT_ENV = 'AGENTS_PROJECTS_LOCAL';
 /** Max peers named in the skipped note before the rest collapse to `+N`. */
@@ -73,11 +72,8 @@ function parseGoalFlag(raw) {
  *
  * `stderr: 'ignore'` is load-bearing, not tidiness. A checkout with no origin
  * makes git print `error: No such remote 'origin'` on ITS stderr, which is the
- * terminal's — the catch below never sees it. That was invisible while this was
- * called once from `add` inside a real repo, and became noise the moment
- * `import --from-factory` started calling it per row: importing 12 registry
- * rows printed two raw git errors between the progress lines. Absence of a
- * remote is an expected answer here (`undefined`), not something to report.
+ * terminal's — the catch below never sees it. Absence of a remote is an
+ * expected answer here (`undefined`), not something to report.
  */
 export function originSlug(cwd) {
     try {
@@ -92,38 +88,6 @@ export function originSlug(cwd) {
         return undefined;
     }
 }
-/**
- * Read the Factory registry off disk and plan its import. Every read failure is
- * fatal and named — an unreadable or malformed registry must not read as "0
- * projects to import".
- */
-function runFactoryImport(existing, opts) {
-    const src = factoryProjectsPath();
-    let rawText;
-    try {
-        rawText = fs.readFileSync(src, 'utf8');
-    }
-    catch {
-        console.error(chalk.red(`No Factory registry at ${src}`));
-        process.exit(1);
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(rawText);
-    }
-    catch {
-        console.error(chalk.red(`Factory registry at ${src} is not valid JSON`));
-        process.exit(1);
-    }
-    const rows = Array.isArray(parsed)
-        ? parsed
-        : Array.isArray(parsed?.projects)
-            ? parsed.projects
-            : [];
-    // The checkout's real `origin` overrides the registry's path-derived slug —
-    // see buildFactoryImportCandidates for why the path guess is not trustworthy.
-    return buildFactoryImportCandidates(rows, existing, opts, (root) => originSlug(expandLocalHome(root)));
-}
 /**
  * List the workspace's Linear projects and plan their import, binding each to a
  * local checkout under the configured projects root when the names match
@@ -442,7 +406,11 @@ export function registerProjectsCommands(program) {
         examples: `
       agents projects import --from-linear  # the projects you actually track
       agents projects add rush --repo phnx-labs/rush --path apps/web
-      agents projects list
+      agents projects list                 # definitions only (no session scan)
+      agents projects list --with-agents   # opt-in local active counts
+      agents projects list --json          # machine-readable defs (Factory uses this)
+      echo '{...}' | agents projects save --json  # create/update one def from stdin
+      agents projects rm rush --json       # machine-readable delete
       agents projects status              # every project, across the whole fleet
       agents projects status rush         # one project (same body as view/show)
       agents projects view rush           # alias of status <name>
@@ -452,31 +420,34 @@ export function registerProjectsCommands(program) {
     `,
         notes: `
       Definitions are hand-editable YAML in ~/.agents/projects/ and sync across
-      machines with 'agents push/pull'.
-
-      'import --from-factory' reads Factory's auto-detected registry, which
-      guesses from checkouts on disk — it imports only 'high' confidence rows by
-      default. Widen with --min-confidence medium or --all, and drop a bad guess
-      with 'agents projects rm <name>'.
+      machines with 'agents push/pull'. Factory reads and writes only through
+      these commands — never ~/.agents/factory/projects.json.
     `,
     });
     // ---- list ----
     projects
         .command('list')
-        .description('List defined projects with their root, repo, and live agent count.')
+        .description('List defined projects (definitions only by default; no session scan).')
         .option('--json', 'Machine-readable output')
+        .option('--with-agents', 'Include local active agent counts (opt-in; never SSH)')
         .action(async (opts) => {
         const defs = listProjectDefs();
+        // Definitions-only by default: zero session scan / SSH. --with-agents is
+        // an explicit opt-in for local active counts only (getActiveSessions is
+        // local; it never fans out).
+        const roll = opts.withAgents
+            ? rollupSessionsByProject(defs, await getActiveSessions())
+            : undefined;
         if (opts.json) {
-            const roll = rollupSessionsByProject(defs, await getActiveSessions());
-            console.log(JSON.stringify(defs.map((d) => ({ ...d, agents: roll.get(d.name)?.agents ?? 0 })), null, 2));
+            console.log(JSON.stringify(opts.withAgents
+                ? defs.map((d) => ({ ...d, agents: roll.get(d.name)?.agents ?? 0 }))
+                : defs, null, 2));
             return;
         }
         if (!defs.length) {
             console.log(chalk.gray('No projects defined. Add one: agents projects add <name>'));
             return;
         }
-        const roll = rollupSessionsByProject(defs, await getActiveSessions());
         const rows = defs.map((d) => ({
             name: d.name,
             path: truncate(d.root ?? d.defaultPath ?? '', LIST_PATH_MAX),
@@ -484,9 +455,9 @@ export function registerProjectsCommands(program) {
         }));
         const w = computeProjectListWidths(rows);
         for (const [i, d] of defs.entries()) {
-            const agents = roll.get(d.name)?.agents ?? 0;
             const row = rows[i];
-            console.log(`  ${chalk.bold(row.name.padEnd(w.name))} ${chalk.dim(row.path.padEnd(w.path))} ${chalk.cyan(row.repo.padEnd(w.repo))} ${agents} agents`);
+            const agentsSuffix = opts.withAgents && roll ? ` ${roll.get(d.name)?.agents ?? 0} agents` : '';
+            console.log(`  ${chalk.bold(row.name.padEnd(w.name))} ${chalk.dim(row.path.padEnd(w.path))} ${chalk.cyan(row.repo.padEnd(w.repo))}${agentsSuffix}`);
         }
     });
     // ---- add ----
@@ -732,11 +703,8 @@ export function registerProjectsCommands(program) {
     // ---- import ----
     projects
         .command('import')
-        .description('Import project definitions from Linear (preferred) or the Factory auto-detection registry.')
-        .option('--from-linear', 'Import the workspace\'s Linear projects (via the `linear` CLI)')
-        .option('--from-factory', 'Import the Factory registry (~/.agents/factory/projects.json)')
-        .option('--min-confidence <level>', '--from-factory only: lowest detection confidence to import — low|medium|high (default: high)')
-        .option('--all', '--from-factory only: import every row regardless of confidence')
+        .description('Import project definitions from Linear (via the `linear` CLI).')
+        .option('--from-linear', 'Import the workspace\'s Linear projects')
         .option('--force', 'Overwrite existing definitions')
         .action((raw) => {
         let opts;
@@ -748,7 +716,7 @@ export function registerProjectsCommands(program) {
             process.exit(1);
         }
         const existing = new Map(listProjectDefs().map((d) => [d.name, d]));
-        const result = opts.source === 'linear' ? runLinearImport(existing, opts) : runFactoryImport(existing, opts);
+        const result = runLinearImport(existing, opts);
         for (const def of result.defs)
             writeProjectDef(def);
         const n = result.defs.length;
@@ -756,9 +724,6 @@ export function registerProjectsCommands(program) {
         console.log(chalk.green(`Imported ${n} project${n === 1 ? '' : 's'}${s ? chalk.gray(` (${s} skipped)`) : ''}`));
         for (const skip of result.skipped)
             console.log(chalk.gray(`  skip ${skip.name}: ${skip.reason}`));
-        if (opts.source === 'factory' && s > 0 && opts.minConfidence === 'high') {
-            console.log(chalk.gray('  (widen with --min-confidence medium or --all)'));
-        }
     });
     // ---- set ----
     projects
@@ -883,17 +848,79 @@ export function registerProjectsCommands(program) {
         writeProjectDef(def);
         console.log(chalk.green(`${def.name} → Linear project "${p.name}" (${p.id})${p.url ? ` ${p.url}` : ''}`));
     });
+    // ---- save ----
+    projects
+        .command('save')
+        .description('Create or update one project from a complete ProjectDef JSON object on stdin.')
+        .option('--json', 'Required: read ProjectDef JSON from stdin; print the saved definition as JSON')
+        .action(async (opts) => {
+        if (!opts.json) {
+            console.error(chalk.red('projects save requires --json (pipe one complete ProjectDef JSON object on stdin).'));
+            process.exit(1);
+        }
+        const chunks = [];
+        for await (const c of process.stdin)
+            chunks.push(c);
+        const raw = Buffer.concat(chunks).toString('utf8').trim();
+        if (!raw) {
+            console.error(chalk.red('projects save --json: empty stdin (expected one ProjectDef JSON object).'));
+            process.exit(1);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (e) {
+            console.error(chalk.red(`projects save --json: invalid JSON: ${e instanceof Error ? e.message : String(e)}`));
+            process.exit(1);
+        }
+        let def;
+        try {
+            def = validateProjectDef(parsed);
+        }
+        catch (e) {
+            console.error(chalk.red(e instanceof Error ? e.message : String(e)));
+            process.exit(1);
+        }
+        writeProjectDef(def);
+        const saved = loadProjectDef(def.name);
+        if (!saved) {
+            console.error(chalk.red(`projects save: wrote "${def.name}" but could not reload it`));
+            process.exit(1);
+        }
+        console.log(JSON.stringify(saved, null, 2));
+    });
     // ---- rm ----
     projects
         .command('rm <name>')
         .alias('remove')
         .description('Delete a project definition. Never touches the repo.')
-        .action((name) => {
+        .option('--json', 'Machine-readable success / error')
+        .action((name, opts) => {
+        if (!isSafeProjectName(name)) {
+            if (opts.json) {
+                console.log(JSON.stringify({ ok: false, name, error: `Invalid project name: "${name}"` }));
+            }
+            else {
+                console.error(chalk.red(`Invalid project name: "${name}"`));
+            }
+            process.exit(1);
+        }
         if (removeProjectDef(name)) {
-            console.log(chalk.green(`Removed project "${name}"`));
+            if (opts.json) {
+                console.log(JSON.stringify({ ok: true, name, removed: true }));
+            }
+            else {
+                console.log(chalk.green(`Removed project "${name}"`));
+            }
         }
         else {
-            console.error(chalk.red(`No project named "${name}".`));
+            if (opts.json) {
+                console.log(JSON.stringify({ ok: false, name, error: `No project named "${name}"` }));
+            }
+            else {
+                console.error(chalk.red(`No project named "${name}".`));
+            }
             process.exit(1);
         }
     });