@phnx-labs/agents-cli 1.22.35 → 1.22.37

package/dist/lib/smart-launch.js

@@ -11,6 +11,7 @@ import { loadDevicesSync } from './devices/registry.js';
 import { normalizeHost } from './machine-id.js';
 import { probePoolSignals } from './teams/placement-probe.js';
 import { pickBestDevice } from './teams/scheduler.js';
+import { getAccountInfo } from './agents.js';
 /** Peakiness of usage weights; >1 amplifies the most-used option. */
 export const DEFAULT_AFFINITY_ALPHA = 1.3;
 /**
@@ -64,38 +65,73 @@ export function listOnlineDeviceNames(localName = localMachineId()) {
     }
     return [...names];
 }
+export function formatNoHealthyDeviceError(pool, signals, agent) {
+    const excluded = pool.map((key) => {
+        const signal = signals.get(key);
+        const reason = signal?.reachable !== true
+            ? 'unreachable'
+            : signal.headroom === 'loaded'
+                ? 'overloaded'
+                : signal.installed !== true || signal.signedIn !== true
+                    ? 'no ready harness account'
+                    : 'ineligible';
+        return `${key} (${reason})`;
+    }).join(', ');
+    const target = agent ? `can run ${agent}` : "for 'run auto'";
+    return `agents: no healthy device ${target} — excluded: ${excluded}; earliest window resets unknown`;
+}
 /**
  * Pick the least-loaded healthy device that can run `agent` when the harness is
- * known. `run auto` omits the agent and ranks the same live health/load signals
- * without an installed-harness filter. The local machine participates in the
- * same probe; a fully unusable fleet degrades to local instead of stranding a run.
+ * known. `run auto` omits the agent and treats any ready account on the device
+ * as eligible. The local machine participates in the
+ * same probe and must pass the same eligibility checks. An empty eligible pool
+ * fails loud; automatic placement never silently becomes a local launch.
  */
 export async function resolveDeviceAuto(agent, opts = {}) {
     const local = normalizeHost(opts.localMachine ?? localMachineId());
     const pool = [...new Set((opts.eligibleHosts ?? listOnlineDeviceNames(local)).map(normalizeHost))];
     if (!pool.includes(local))
         pool.push(local);
-    try {
-        const signals = await (opts.probe ?? probePoolSignals)(pool, agent);
-        const picked = pickBestDevice(pool, [], { signals, agentLabel: agent });
-        return {
-            host: picked === local ? null : picked,
-            pickedDeviceKey: picked,
-            candidates: pool.map((key) => ({
-                key,
-                loadPercent: signals.get(key)?.loadPercent,
-                installed: signals.get(key)?.installed,
-                signedIn: signals.get(key)?.signedIn,
-            })),
-        };
+    const signals = await (opts.probe ?? probePoolSignals)(pool, agent);
+    if (!agent && !opts.probe) {
+        const { collectFleetHarnesses } = await import('../commands/ssh.js');
+        const inventory = await collectFleetHarnesses({ devices: pool });
+        const byHost = new Map(inventory.map((result) => [normalizeHost(result.host), result]));
+        for (const key of pool) {
+            const result = byHost.get(key);
+            const accountEligible = !!result && !result.error && !result.skipped && result.rows.some((row) => row.ready);
+            const current = signals.get(key);
+            if (current)
+                signals.set(key, { ...current, installed: accountEligible, signedIn: accountEligible });
+        }
     }
-    catch {
-        return {
-            host: null,
-            pickedDeviceKey: local,
-            candidates: [{ key: local }],
-        };
+    if (agent && !opts.probe && signals.has(local)) {
+        const info = await getAccountInfo(agent).catch(() => null);
+        const eligible = !!info?.signedIn && info.usageStatus !== 'rate_limited' && info.usageStatus !== 'out_of_credits';
+        signals.set(local, { ...signals.get(local), signedIn: eligible });
     }
+    const eligiblePool = pool.filter((key) => {
+        const signal = signals.get(key);
+        if (signal?.reachable !== true || signal.headroom === 'loaded')
+            return false;
+        if (!agent)
+            return opts.probe ? true : signal.installed === true && signal.signedIn === true;
+        return signal.installed === true && signal.signedIn === true;
+    });
+    if (eligiblePool.length === 0) {
+        throw new Error(formatNoHealthyDeviceError(pool, signals, agent));
+    }
+    const picked = pickBestDevice(eligiblePool, [], { signals, agentLabel: agent });
+    return {
+        host: picked === local ? null : picked,
+        pickedDeviceKey: picked,
+        candidates: pool.map((key) => ({
+            key,
+            loadPercent: signals.get(key)?.loadPercent,
+            installed: signals.get(key)?.installed,
+            signedIn: signals.get(key)?.signedIn,
+        })),
+    };
 }
 /**
  * Resolve host for `--device auto`. Does NOT pick harness or accounts.
@@ -152,8 +188,8 @@ export function isDeviceAuto(value) {
 const HOST_SLOTS = ['host', 'device', 'on', 'computer'];
 /**
  * Apply `--device auto` / `--host auto` (and deprecated `--smart`) onto run options.
- * Mutates `options` in place. On affinity failure, clears auto slots (local) and
- * returns `skipped` — never throws; callers must not hard-exit.
+ * Mutates `options` in place. Placement failures propagate without rewriting
+ * `auto`, so callers fail loud instead of silently launching locally.
  */
 export async function applyDeviceAutoToOptions(options, deps = {}) {
     let deprecationSmart = false;
@@ -167,42 +203,27 @@ export async function applyDeviceAutoToOptions(options, deps = {}) {
     if (!hasAuto) {
         return { attempted: false, deprecationSmart };
     }
-    try {
-        const resolve = deps.resolve ?? (() => resolveDeviceAuto(deps.agent));
-        const plan = await resolve();
-        const concrete = plan.host; // null = local
-        for (const k of HOST_SLOTS) {
-            if (isDeviceAuto(options[k])) {
-                options[k] = concrete ?? undefined;
-            }
+    const resolve = deps.resolve ?? (() => resolveDeviceAuto(deps.agent));
+    const plan = await resolve();
+    const concrete = plan.host; // null = local
+    for (const k of HOST_SLOTS) {
+        if (isDeviceAuto(options[k])) {
+            options[k] = concrete ?? undefined;
         }
-        const accountPickerRequested = deps.accountPickerRequested ?? false;
-        if (!accountPickerRequested && !options.strategy && !options.balanced) {
-            options.balanced = true;
-        }
-        const hostLabel = concrete ?? 'local';
-        const deviceHint = plan.candidates
-            .slice(0, 4)
-            .map((c) => `${c.key}:${c.loadPercent === undefined ? '?' : `${Math.round(c.loadPercent)}%`}`)
-            .join(', ');
-        const acctNote = accountPickerRequested ? 'accounts=picker' : 'accounts=balanced';
-        return {
-            attempted: true,
-            deprecationSmart,
-            banner: { hostLabel, deviceHint, acctNote },
-        };
     }
-    catch (err) {
-        // Graceful degrade: clear auto slots so the run continues locally.
-        for (const k of HOST_SLOTS) {
-            if (isDeviceAuto(options[k])) {
-                options[k] = undefined;
-            }
-        }
-        return {
-            attempted: true,
-            deprecationSmart,
-            skipped: err.message,
-        };
+    const accountPickerRequested = deps.accountPickerRequested ?? false;
+    if (!accountPickerRequested && !options.strategy && !options.balanced) {
+        options.balanced = true;
     }
+    const hostLabel = concrete ?? 'local';
+    const deviceHint = plan.candidates
+        .slice(0, 4)
+        .map((c) => `${c.key}:${c.loadPercent === undefined ? '?' : `${Math.round(c.loadPercent)}%`}`)
+        .join(', ');
+    const acctNote = accountPickerRequested ? 'accounts=picker' : 'accounts=balanced';
+    return {
+        attempted: true,
+        deprecationSmart,
+        banner: { hostLabel, deviceHint, acctNote },
+    };
 }

package/dist/lib/ssh-exec.d.ts

@@ -2,7 +2,7 @@
  * Shared SSH exec primitive — the single hardened choke point for running a
  * command on a remote host over the system `ssh`.
  *
- * `agents hosts` dispatch and the browser driver both go through here so the
+ * `agents run --host` dispatch and the browser driver both go through here so the
  * connection hardening (`BatchMode`, `accept-new`, `ConnectTimeout`) and the
  * target-injection guard live in exactly one place. Target validation is the
  * canonical definition; `commands/secrets.ts` re-exports it.

package/dist/lib/ssh-exec.js

@@ -2,7 +2,7 @@
  * Shared SSH exec primitive — the single hardened choke point for running a
  * command on a remote host over the system `ssh`.
  *
- * `agents hosts` dispatch and the browser driver both go through here so the
+ * `agents run --host` dispatch and the browser driver both go through here so the
  * connection hardening (`BatchMode`, `accept-new`, `ConnectTimeout`) and the
  * target-injection guard live in exactly one place. Target validation is the
  * canonical definition; `commands/secrets.ts` re-exports it.

package/dist/lib/staleness/prune.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Manifest-bounded prune (RUSH-2438).
+ *
+ * `agents sync` was additive-only: it installed/updated resources present in
+ * source but never removed a resource that had been DELETED from source, so a
+ * removed command/skill/hook lingered in every installed version home forever
+ * (and stayed live in the `/` menu). Bare `agents sync <agent>` full syncs did
+ * sweep orphans, but the repo-scoped forms the reconcile path actually uses —
+ * `agents sync <agent>@all system`, `agents sync <agent> system --force` — pass
+ * a selection, which turned the orphan sweeps off. This closes that gap.
+ *
+ * The prune set is computed by name, bounded by the sync manifest:
+ *
+ *     prune = (names the last sync recorded as installed)
+ *           − (names still present in source across ALL layers)
+ *           ∩ (names currently materialized in the version home)
+ *
+ * Each clause is a safety guarantee:
+ *   - The manifest bound means only agents-installed resources are ever
+ *     candidates — a file the user hand-authored into the version home was
+ *     never recorded, so it is never touched.
+ *   - Diffing against ALL layers (not just the scoped one) means a resource
+ *     still provided by any other layer — e.g. a same-named user command that
+ *     shadows a removed system command — stays: it is still "in source".
+ *   - Requiring the name to be materialized skips work for anything already
+ *     gone and never errors on a missing path.
+ *
+ * When there is NO manifest we cannot know what a prior sync installed, so we
+ * FAIL LOUD by pruning nothing and reporting it — never a "delete everything
+ * not in source" guess. The manifest is written by the next full sync, so the
+ * baseline heals itself.
+ *
+ * Deletion itself is delegated to each writer's `remove()` (the inverse of
+ * `write()`), so per-harness layout knowledge — native file vs command-skill
+ * dir vs goose recipe — lives in one place and can't drift.
+ */
+import type { AgentId } from '../types.js';
+import type { SyncManifest } from './types.js';
+/**
+ * Kinds prune reconciles. Restricted to the name-keyed file/dir resources whose
+ * writer implements `remove()`. Deliberately excluded, each with a reason:
+ *   - hooks — a version-home hook script is coupled to a settings.json /
+ *     hooks.json REGISTRATION. Pruning the last hook to zero would delete the
+ *     script but must also GC its registration in the same pass, and that lands
+ *     in `src/lib/hooks.ts` — a Windows-portable-path surface the CI windows leg
+ *     gates on. Split to RUSH-2456 so this PR stays Linux-only-green; hook FILES
+ *     are still reconciled by the in-write orphan sweep (versions.ts, gated on
+ *     `hooksToSync > 0`).
+ *   - rules / permissions — synced as a wholesale rewrite (one composed file /
+ *     the full allowlist), so a removed rule or group already drops out.
+ *   - plugins — carry their own reconciliation via `cleanOrphanedPluginSkills`.
+ *   - mcp — registered through each agent's CLI/config, a separate removal path.
+ *   - subagents / workflows — no clean per-name inverse yet (multi-agent index
+ *     finalize; native workflow trees); tracked for a follow-up.
+ */
+export declare const PRUNABLE_KINDS: readonly ["commands", "skills"];
+export type PrunableKind = typeof PRUNABLE_KINDS[number];
+export interface PruneInput {
+    agent: AgentId;
+    version: string;
+    versionHome: string;
+    cwd: string;
+    /**
+     * The sync manifest loaded BEFORE this sync ran — the record of what the last
+     * sync installed. `null` means no prior full sync established a baseline.
+     */
+    previousManifest: SyncManifest | null;
+    /**
+     * Current source resource names across ALL layers (project/user/system/extras),
+     * per prunable kind. A name present here is still "in source" and never pruned.
+     */
+    sourceNames: Record<PrunableKind, ReadonlyArray<string>>;
+}
+export interface PruneOutcome {
+    /** Names actually removed from the version home, per kind. */
+    pruned: Record<PrunableKind, string[]>;
+    /**
+     * True when prune ran with no manifest and therefore deleted nothing — the
+     * fail-loud baseline case. Callers surface this so a skipped reconcile is
+     * never mistaken for "nothing to prune".
+     */
+    skippedNoManifest: boolean;
+}
+/**
+ * Remove resources that a prior sync installed and that are now gone from
+ * source, from one agent@version home. Deletes nothing when no manifest exists.
+ */
+export declare function pruneRemovedResources(input: PruneInput): PruneOutcome;

package/dist/lib/staleness/prune.js

@@ -0,0 +1,69 @@
+import { getWriter, getDetector } from './registry.js';
+/**
+ * Kinds prune reconciles. Restricted to the name-keyed file/dir resources whose
+ * writer implements `remove()`. Deliberately excluded, each with a reason:
+ *   - hooks — a version-home hook script is coupled to a settings.json /
+ *     hooks.json REGISTRATION. Pruning the last hook to zero would delete the
+ *     script but must also GC its registration in the same pass, and that lands
+ *     in `src/lib/hooks.ts` — a Windows-portable-path surface the CI windows leg
+ *     gates on. Split to RUSH-2456 so this PR stays Linux-only-green; hook FILES
+ *     are still reconciled by the in-write orphan sweep (versions.ts, gated on
+ *     `hooksToSync > 0`).
+ *   - rules / permissions — synced as a wholesale rewrite (one composed file /
+ *     the full allowlist), so a removed rule or group already drops out.
+ *   - plugins — carry their own reconciliation via `cleanOrphanedPluginSkills`.
+ *   - mcp — registered through each agent's CLI/config, a separate removal path.
+ *   - subagents / workflows — no clean per-name inverse yet (multi-agent index
+ *     finalize; native workflow trees); tracked for a follow-up.
+ */
+export const PRUNABLE_KINDS = ['commands', 'skills'];
+/** Names the manifest recorded as installed for a kind (source-name keyed). */
+function manifestNames(manifest, kind) {
+    switch (kind) {
+        case 'commands': {
+            // Object keys are the source command names; writtenCommands carries any
+            // extra names the writer actually emitted (dual-write / command-skill).
+            const names = new Set(Object.keys(manifest.commands ?? {}));
+            for (const c of manifest.writtenCommands ?? [])
+                names.add(c);
+            return [...names];
+        }
+        case 'skills': return Object.keys(manifest.skills ?? {});
+    }
+}
+function emptyPruned() {
+    return { commands: [], skills: [] };
+}
+/**
+ * Remove resources that a prior sync installed and that are now gone from
+ * source, from one agent@version home. Deletes nothing when no manifest exists.
+ */
+export function pruneRemovedResources(input) {
+    const { agent, version, versionHome, cwd, previousManifest, sourceNames } = input;
+    if (!previousManifest) {
+        return { pruned: emptyPruned(), skippedNoManifest: true };
+    }
+    const pruned = emptyPruned();
+    for (const kind of PRUNABLE_KINDS) {
+        const writer = getWriter(kind, agent);
+        const detector = getDetector(kind, agent);
+        // No writer.remove (unsupported kind/agent) or no detector: nothing to do.
+        if (!writer?.remove || !detector)
+            continue;
+        const installed = manifestNames(previousManifest, kind);
+        if (installed.length === 0)
+            continue;
+        const stillInSource = new Set(sourceNames[kind]);
+        const materialized = new Set(detector.list({ version, versionHome, cwd }));
+        for (const name of installed) {
+            if (stillInSource.has(name))
+                continue; // still provided by some layer
+            if (!materialized.has(name))
+                continue; // already gone from the home
+            const result = writer.remove({ version, versionHome, name, cwd });
+            if (result.removed)
+                pruned[kind].push(name);
+        }
+    }
+    return { pruned, skippedNoManifest: false };
+}

package/dist/lib/staleness/registry.d.ts

@@ -5,7 +5,7 @@ import type { ResourceDetector } from './detectors/types.js';
 import type { RulesSelection } from './writers/rules.js';
 export type { ResourceKind } from './writers/kinds.js';
 export { kindToCapability, ALL_RESOURCE_KINDS } from './writers/kinds.js';
-export type { ResourceWriter, WriteArgs, WriteResult } from './writers/types.js';
+export type { ResourceWriter, WriteArgs, WriteResult, RemoveArgs, RemoveResult } from './writers/types.js';
 export type { ResourceDetector, DetectArgs } from './detectors/types.js';
 export type { RulesSelection } from './writers/rules.js';
 /** Per-kind selection payload. Most kinds are string[]; rules is special. */

package/dist/lib/staleness/writers/commands.js

@@ -25,8 +25,8 @@ import { supports } from '../../capabilities.js';
 import { safeJoin } from '../../paths.js';
 import { markdownToToml } from '../../convert.js';
 import { commandAppliesTo, parseCommandMetadata } from '../../commands.js';
-import { installCommandSkillToVersion, shouldAlsoInstallCommandAsSkill, shouldInstallCommandAsSkill, } from '../../command-skills.js';
-import { installGooseCommandToVersion } from '../../goose-commands.js';
+import { installCommandSkillToVersion, listCommandSkillsInVersion, removeCommandSkillFromVersion, shouldAlsoInstallCommandAsSkill, shouldInstallCommandAsSkill, } from '../../command-skills.js';
+import { installGooseCommandToVersion, listGooseCommandsInVersion, removeGooseCommandFromVersion, } from '../../goose-commands.js';
 import { resolveCommandSource, trustedSkillRoots } from './sources.js';
 import { lazyAgentMap } from './lazy-map.js';
 function buildCommandsWriter(agent) {
@@ -82,6 +82,38 @@ function buildCommandsWriter(agent) {
             }
             return { synced };
         },
+        remove({ versionHome, name }) {
+            const agentConfig = AGENTS[agent];
+            const agentDir = path.join(versionHome, agentConfigDirName(agent));
+            let removed = false;
+            // Native command file (Claude, Codex <0.117, Grok, Cursor, …). The
+            // extension follows the agent's format, mirroring the write path above.
+            if (agentConfig.commandsSubdir) {
+                const ext = agentConfig.format === 'toml' ? '.toml' : '.md';
+                const nativeFile = safeJoin(path.join(agentDir, agentConfig.commandsSubdir), `${name}${ext}`);
+                try {
+                    if (fs.existsSync(nativeFile) && fs.lstatSync(nativeFile).isFile()) {
+                        fs.unlinkSync(nativeFile);
+                        removed = true;
+                    }
+                }
+                catch { /* already gone / inaccessible */ }
+            }
+            // Command-as-skill dir (Codex >=0.117, Kimi; Cursor dual-write). Gated on
+            // it currently being a command-skill, and removeCommandSkillFromVersion
+            // re-checks the `agents_command` marker before deleting — so a real skill
+            // of the same name is never destroyed by a command prune.
+            if (listCommandSkillsInVersion(agentDir).includes(name)) {
+                if (removeCommandSkillFromVersion(agentDir, name).success)
+                    removed = true;
+            }
+            // Goose recipe YAML + its slash_commands registry entry.
+            if (agent === 'goose' && listGooseCommandsInVersion(versionHome).includes(name)) {
+                if (removeGooseCommandFromVersion(versionHome, name).success)
+                    removed = true;
+            }
+            return { removed };
+        },
     };
 }
 // Built lazily on first access — see lazy-map.ts for the cycle rationale.

package/dist/lib/staleness/writers/hooks.js

@@ -95,6 +95,22 @@ function buildHooksWriter(agent) {
             }
             return { synced };
         },
+        remove({ versionHome, name }) {
+            // Delete the copied hook artifact from `{agentDir}/hooks/<name>`. Native
+            // settings.json/hooks.json registration is regenerated by the write path
+            // that runs alongside this prune (registerHooksToSettings above reads the
+            // remaining source manifest), so a removed hook drops out of both.
+            const agentDir = path.join(versionHome, agentConfigDirName(agent));
+            const hookTarget = safeJoin(path.join(agentDir, 'hooks'), name);
+            try {
+                if (fs.existsSync(hookTarget)) {
+                    removePath(hookTarget);
+                    return { removed: true };
+                }
+            }
+            catch { /* already gone / inaccessible */ }
+            return { removed: false };
+        },
     };
 }
 export const hooksWriters = lazyAgentMap(() => {

package/dist/lib/staleness/writers/kinds.d.ts

@@ -2,6 +2,12 @@
  * Canonical list of resource kinds dispatched through the writer/detector
  * registry. Each name is the capability name on AgentConfig — except
  * "permissions", which maps to the legacy capability name "allowlist".
+ *
+ * NOTE: "rules" in this registry is the WRITER key for what ResourceSelection
+ * calls "memory". The --rule/--rules CLI flag therefore maps to the "memory"
+ * key in ResourceSelection, not to a key called "rules". The memory file is
+ * composed from all layers (not a per-repo artifact), so it is always set to
+ * 'all' rather than filtered by individual names.
  */
 import type { CapabilityName } from '../../types.js';
 export type ResourceKind = 'commands' | 'skills' | 'hooks' | 'rules' | 'mcp' | 'permissions' | 'subagents' | 'plugins' | 'workflows';

package/dist/lib/staleness/writers/skills.js

@@ -9,6 +9,7 @@ import * as path from 'path';
 import { AGENTS, agentConfigDirName } from '../../agents.js';
 import { capableAgents } from '../../capabilities.js';
 import { safeJoin } from '../../paths.js';
+import { listCommandSkillsInVersion } from '../../command-skills.js';
 import { resolveSkillSource } from './sources.js';
 import { lazyAgentMap } from './lazy-map.js';
 const SKILL_COPY_IGNORE = new Set(['.DS_Store', '.git', '.gitignore', '.venv', '__pycache__', 'node_modules']);
@@ -66,6 +67,24 @@ function buildSkillsWriter(agent) {
             }
             return { synced };
         },
+        remove({ versionHome, name }) {
+            const agentDir = path.join(versionHome, agentConfigDirName(agent));
+            // A command-installed-as-skill lives in the same skills/ dir but is owned
+            // by the commands writer's prune — never delete it from here, or a
+            // still-live converted command would vanish under a skill prune.
+            if (listCommandSkillsInVersion(agentDir).includes(name)) {
+                return { removed: false };
+            }
+            const destDir = safeJoin(path.join(agentDir, 'skills'), name);
+            try {
+                if (fs.existsSync(destDir) && fs.lstatSync(destDir).isDirectory()) {
+                    removePath(destDir);
+                    return { removed: true };
+                }
+            }
+            catch { /* already gone / inaccessible */ }
+            return { removed: false };
+        },
     };
 }
 export const skillsWriters = lazyAgentMap(() => {

package/dist/lib/staleness/writers/subagents.d.ts

@@ -1,8 +1,7 @@
 /**
  * Subagents writer. Every agent's on-disk layout (target dir, file/dir shape,
- * transform, and any post-sync finalize such as Kimi's parent index) is
- * declared once in the subagent registry; this writer is generic and iterates
- * the registry instead of a per-agent `else if` chain.
+ * transform) is declared once in the subagent registry; this writer is generic
+ * and iterates the registry instead of a per-agent `else if` chain.
  *
  * Source-side discovery is `listInstalledSubagents` from lib/subagents.ts —
  * it reads user + system layers only (project layer excluded for the same

package/dist/lib/staleness/writers/subagents.js

@@ -24,10 +24,6 @@ function buildSubagentsWriter(agent) {
                 }
                 catch { /* per-item sync failure: skip */ }
             }
-            // Optional cross-item pass (e.g. Kimi's `_agents-cli.yaml` parent index).
-            if (target.finalize && synced.length > 0) {
-                target.finalize(dir, synced.map((name) => map.get(name)));
-            }
             return { synced };
         },
     };

package/dist/lib/staleness/writers/types.d.ts

@@ -29,8 +29,40 @@ export interface WriteResult {
     /** Names actually written. Empty array = write produced nothing (not an error). */
     synced: string[];
 }
+/**
+ * Inverse of a write: locate and delete the materialized artifact for one
+ * resource `name` from a version home. Used only by the manifest-bounded prune
+ * pass (RUSH-2438), which supplies names it has already proven were
+ * agents-installed and are gone from source — the writer just owns the layout
+ * knowledge (native file vs command-skill dir vs recipe) so prune never
+ * re-derives it.
+ */
+export interface RemoveArgs {
+    /** Agent version (e.g. "1.2.3"). */
+    version: string;
+    /** Absolute path to the version's home dir. */
+    versionHome: string;
+    /** Resource name to remove (no extension). */
+    name: string;
+    /** Current working directory — used by writers that consult project-layer state. */
+    cwd: string;
+}
+export interface RemoveResult {
+    /** True when an artifact owned by this writer was found and deleted. */
+    removed: boolean;
+}
 export interface ResourceWriter<Sel = string[]> {
     readonly kind: ResourceKind;
     readonly agent: AgentId;
     write(args: WriteArgs<Sel>): WriteResult;
+    /**
+     * Optional inverse of `write` for the prune pass. Only the name-keyed
+     * file/dir kinds implement it (commands, skills, hooks); kinds whose sync is
+     * a wholesale rewrite (rules, permissions) or that carry their own
+     * reconciliation (plugins via cleanOrphanedPluginSkills) leave it undefined.
+     * Absence is not a silent skip: `pruneRemovedResources` only iterates
+     * `PRUNABLE_KINDS`, and a registry completeness test asserts every writer for
+     * those kinds implements `remove`.
+     */
+    remove?(args: RemoveArgs): RemoveResult;
 }

package/dist/lib/startup/command-registry.d.ts

@@ -37,20 +37,19 @@ export declare const loadCli: ModuleLoader;
 export declare const loadSubagents: ModuleLoader;
 export declare const loadPlugins: ModuleLoader;
 export declare const loadWorkflows: ModuleLoader;
-export declare const loadWorktree: ModuleLoader;
 export declare const loadVersions: ModuleLoader;
 export declare const loadUpdate: ModuleLoader;
 export declare const loadImport: ModuleLoader;
-export declare const loadExport: ModuleLoader;
 export declare const loadPackages: ModuleLoader;
 export declare const loadRoutines: ModuleLoader;
 export declare const loadMonitors: ModuleLoader;
 export declare const loadProjects: ModuleLoader;
 export declare const loadRun: ModuleLoader;
 export declare const loadResume: ModuleLoader;
+export declare const loadOpen: ModuleLoader;
 export declare const loadReconnect: ModuleLoader;
 export declare const loadFork: ModuleLoader;
-export declare const loadDefaults: ModuleLoader;
+export declare const loadConfig: ModuleLoader;
 export declare const loadSet: ModuleLoader;
 export declare const loadModels: ModuleLoader;
 export declare const loadModes: ModuleLoader;
@@ -65,12 +64,9 @@ export declare const loadProfiles: ModuleLoader;
 export declare const loadHarness: ModuleLoader;
 export declare const loadSecrets: ModuleLoader;
 export declare const loadLogin: ModuleLoader;
-export declare const loadWallet: ModuleLoader;
-export declare const loadHelper: ModuleLoader;
 export declare const loadMenubar: ModuleLoader;
 export declare const loadBeta: ModuleLoader;
 export declare const loadSync: ModuleLoader;
-export declare const loadLock: ModuleLoader;
 export declare const loadRefreshRules: ModuleLoader;
 export declare const loadFactory: ModuleLoader;
 export declare const loadUsage: ModuleLoader;
@@ -88,19 +84,16 @@ export declare const loadTmux: ModuleLoader;
 export declare const loadWatchdog: ModuleLoader;
 export declare const loadBrowser: ModuleLoader;
 export declare const loadComputer: ModuleLoader;
-export declare const loadHosts: ModuleLoader;
-export declare const loadLease: ModuleLoader;
 export declare const loadLogs: ModuleLoader;
 export declare const loadEvents: ModuleLoader;
 export declare const loadSsh: ModuleLoader;
-export declare const loadPull: ModuleLoader;
-export declare const loadPush: ModuleLoader;
 export declare const loadRepo: ModuleLoader;
 export declare const loadSetup: ModuleLoader;
 export declare const loadUninstall: ModuleLoader;
 export declare const loadUpgrade: ModuleLoader;
 export declare const loadSessions: ModuleLoader;
 export declare const loadTeams: ModuleLoader;
+export declare const loadTickets: ModuleLoader;
 export declare const loadCloud: ModuleLoader;
 export declare const loadMessage: ModuleLoader;
 export declare const loadSend: ModuleLoader;
@@ -109,11 +102,11 @@ export declare const loadMailboxes: ModuleLoader;
 export declare const loadServe: ModuleLoader;
 export declare const loadShare: ModuleLoader;
 export declare const loadAudit: ModuleLoader;
-export declare const loadWebhook: ModuleLoader;
-export declare const loadFunnel: ModuleLoader;
+export declare const loadWebhooks: ModuleLoader;
 export declare const loadHumans: ModuleLoader;
 export declare const loadAccounts: ModuleLoader;
 export declare const loadDaemon: ModuleLoader;
+export declare const loadCp: ModuleLoader;
 /**
  * Commands whose modules pull in the SQLite-backed session/cloud stack. They are
  * registered AFTER `applyGlobalHelpConventions` (mirroring main's order: help
@@ -150,6 +143,7 @@ export declare const COMMAND_LOADERS: Record<string, ModuleLoader[]>;
  * registered command tree so a new command can never drift out of it.
  */
 export declare const KNOWN_TOP_LEVEL_COMMANDS: ReadonlySet<string>;
+export declare const RETIRED_TOP_LEVEL_COMMANDS: ReadonlySet<string>;
 /** Whether `name` is a top-level command this CLI registers. See {@link KNOWN_TOP_LEVEL_COMMANDS}. */
 export declare function isKnownTopLevelCommand(name: string): boolean;
 /**