@phnx-labs/agents-cli 1.22.119 → 1.22.121

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

@@ -1,23 +1,3 @@
-/**
- * Commands writer.
- *
- * Two physical formats, selected per-(agent, version) at write time. Most
- * agents receive one format; dual-write registry targets receive both:
- *
- *  - command-as-skill — fires when `shouldInstallCommandAsSkill(agent, version)`
- *    is true. Used for Codex >= 0.117.0 (commands capability ends, skills
- *    capability remains) and agents with skills but no native command-file dir
- *    such as Kimi. Cursor also receives this format in addition to its IDE
- *    command file. Writes `{agentDir}/skills/<name>/SKILL.md` with the
- *    `agents_command` marker; the agent picks it up as a slash-command equivalent.
- *
- *  - native command file — `{agentDir}/<commandsSubdir>/<name>.md` (or .toml
- *    when the agent's format is toml). Standard path for Claude, Codex
- *    < 0.117.0, Cursor, OpenCode, Copilot, Amp, Roo, Antigravity.
- *
- * Source resolution is `resolveCommandSource` (user → system → extras —
- * project layer intentionally excluded).
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import { AGENTS, MANAGED_AGENT_IDS, agentConfigDirName } from '../../agents.js';
@@ -39,8 +19,6 @@ function buildCommandsWriter(agent) {
             const commandsAsSkills = shouldInstallCommandAsSkill(agent, version);
             const commandsAlsoAsSkills = shouldAlsoInstallCommandAsSkill(agent, version);
             const supportsCommands = supports(agent, 'commands', version).ok;
-            // Version-gated agents (e.g. goose skills >= 1.25.0) are registered but
-            // may be called at a version too old for both paths — skip gracefully.
             if (!commandsAsSkills && !supportsCommands) {
                 return { synced: [] };
             }
@@ -60,8 +38,6 @@ function buildCommandsWriter(agent) {
                     continue;
                 if (commandsAsSkills || commandsAlsoAsSkills) {
                     const installed = installCommandSkillToVersion(agentDir, cmd, srcFile, skillRoots);
-                    // installed.skipped means a real skill source already owns this name,
-                    // which is a deliberate no-op, not a failure — the native file is still written.
                     if (!installed.success)
                         continue;
                     if (!installed.skipped) {
@@ -69,8 +45,6 @@ function buildCommandsWriter(agent) {
                     }
                 }
                 if (supportsCommands && agent === 'goose') {
-                    // Goose: recipe YAML + config.yaml slash_commands entry, not a file copy.
-                    // No artifact path recorded — the recipe layout lives in goose-commands.ts.
                     const installed = installGooseCommandToVersion(versionHome, cmd, srcFile);
                     if (!installed.success)
                         continue;
@@ -95,8 +69,6 @@ function buildCommandsWriter(agent) {
             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}`);
@@ -106,17 +78,12 @@ function buildCommandsWriter(agent) {
                         removed = true;
                     }
                 }
-                catch { /* already gone / inaccessible */ }
+                catch { }
             }
-            // 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;
@@ -125,26 +92,12 @@ function buildCommandsWriter(agent) {
         },
     };
 }
-// Built lazily on first access — see lazy-map.ts for the cycle rationale.
-//
-// Registration covers two cases:
-//   - native commands (claude, codex < 0.117.0, grok, etc.) — `commands` cap
-//   - commands-as-skills (kimi, codex >= 0.117.0)
-//   - dual-write commands plus command-skills (cursor)
-//
-// Agents that have skills but use a NATIVE non-file slash-command system
-// (openclaw → Gateway-based commands) are NOT registered. They declare
-// `nativeCommandRuntime: true` to opt out — their own runtime resolves slash
-// commands, so there's nothing to write and nothing to convert.
 export const commandsWriters = lazyAgentMap(() => {
     const m = {};
     for (const id of MANAGED_AGENT_IDS) {
         const cfg = AGENTS[id];
         if (cfg.capabilities.commands === false && (!cfg.skillsDir || cfg.skillsDir === ''))
             continue;
-        // Skills-capable agent with no native command-file dir: convert commands to
-        // skills by default (kimi, …). Opt out only agents with their own
-        // slash-command runtime (openclaw).
         if (cfg.capabilities.commands === false && (!cfg.commandsSubdir || cfg.commandsSubdir === '')) {
             if (cfg.nativeCommandRuntime)
                 continue;

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

@@ -1,9 +1,3 @@
-/**
- * Hooks writer — copies trusted hook sources into `{agentDir}/hooks/`.
- * Caller filters by `supports(agent, 'hooks', version)` before invoking.
- * Orphan sweep (delete hooks in version-home that aren't in `availableNames`)
- * stays in the orchestrator since it depends on the broader available set.
- */
 import * as fs from 'fs';
 import { agentConfigDirName } from '../../agents.js';
 import * as path from 'path';
@@ -23,7 +17,6 @@ function removePath(target) {
         }
     }
     catch {
-        /* already gone */
     }
 }
 function copyDir(src, dest) {
@@ -86,22 +79,12 @@ function buildHooksWriter(agent) {
                     paths.push(destFile);
                 }
             }
-            // Native hook registration in settings.json/hooks.json. Grok is included
-            // so subrule-bundled guards (absolute paths outside the central hooks/
-            // copy set) get registered into ~/.grok/hooks/hooks.json via
-            // registerHooksForGrok — file copy alone only sees top-level available.hooks
-            // names (RUSH-1353). Copilot/Goose load managed *.json under their
-            // hooks dirs the same way.
             if (agent === 'claude' || agent === 'codex' || agent === 'antigravity' || agent === 'kimi' || agent === 'droid' || agent === 'copilot' || agent === 'goose' || agent === 'cursor' || agent === 'grok' || agent === 'hermes' || agent === 'muse') {
                 registerHooksToSettings(agent, versionHome);
             }
             return { synced, paths };
         },
         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 {
@@ -110,7 +93,7 @@ function buildHooksWriter(agent) {
                     return { removed: true };
                 }
             }
-            catch { /* already gone / inaccessible */ }
+            catch { }
             return { removed: false };
         },
     };

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

@@ -1,16 +1,4 @@
-/**
- * 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';
 export declare const ALL_RESOURCE_KINDS: readonly ResourceKind[];
-/** Map kind -> capability name on AgentConfig.capabilities. */
 export declare function kindToCapability(kind: ResourceKind): CapabilityName;

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

@@ -9,7 +9,6 @@ export const ALL_RESOURCE_KINDS = [
     'plugins',
     'workflows',
 ];
-/** Map kind -> capability name on AgentConfig.capabilities. */
 export function kindToCapability(kind) {
     return kind === 'permissions' ? 'allowlist' : kind;
 }

package/dist/lib/staleness/writers/lazy-map.d.ts

@@ -1,13 +1,2 @@
-/**
- * Lazy-built per-agent map.
- *
- * The writer/detector modules form a circular dependency with agents.ts:
- * agents.ts → versions.ts → staleness/registry.ts → writers/<kind>.ts →
- * (capableAgents/AGENTS via capabilities or agents directly). If a writer
- * module iterates AGENTS at module top-level it fires before the AGENTS
- * const is initialized through the cycle. Wrapping the per-agent map in a
- * lazily-evaluated Proxy defers every read until call time, by which point
- * the cycle has resolved.
- */
 import type { AgentId } from '../../types.js';
 export declare function lazyAgentMap<T>(build: () => Partial<Record<AgentId, T>>): Partial<Record<AgentId, T>>;

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

@@ -1,10 +1,3 @@
-/**
- * MCP writer — thin dispatcher into `installMcpServers` from `lib/mcp.ts`.
- *
- * The per-agent format handling (Claude CLI, Codex TOML, Cursor JSON, etc.)
- * lives in lib/mcp.ts; we keep it there to avoid the import cycle with
- * `versions.ts`. The writer simply hands the selection to that function.
- */
 import * as fs from 'fs';
 import { capableAgents } from '../../capabilities.js';
 import { installMcpServers } from '../../mcp.js';
@@ -16,12 +9,6 @@ function buildMcpWriter(agent) {
         agent,
         write({ version, versionHome, selection, cwd }) {
             const r = installMcpServers(agent, version, versionHome, selection, { cwd });
-            // Forward r.errors: dropping them is what let a harness with no config
-            // writer report a clean sync while writing nothing (RUSH-2677).
-            // All applied servers land in the one canonical config file — that file
-            // is the artifact whose deletion must read as stale (#2398). Recorded
-            // only when it verifiably exists after the write, so an agent whose CLI
-            // wrote elsewhere can never produce a perpetually-stale manifest.
             const configPath = getMcpConfigPathForHome(agent, versionHome);
             const paths = r.applied.length > 0 && fs.existsSync(configPath) ? [configPath] : [];
             return { synced: r.applied, paths, ...(r.errors.length ? { errors: r.errors } : {}) };

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

@@ -8,10 +8,6 @@ function buildPluginsWriter(agent) {
         write({ version, versionHome, selection }) {
             const all = discoverPlugins();
             const map = new Map(all.map(p => [p.name, p]));
-            // Clean orphan plugin-skills from plugins that no longer exist. Pass the
-            // discovered plugins (not just names) so a stale install under one
-            // marketplace is trashed even when another marketplace still ships that
-            // name — the PHNX-2618 shadow `code` plugin.
             cleanOrphanedPluginSkills(agent, versionHome, all);
             const synced = [];
             for (const name of selection) {

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

@@ -1,6 +1,5 @@
 import type { ResourceWriter } from './types.js';
 export interface RulesSelection {
-    /** Preset name to compose. Empty string falls through to `"default"` in the composer. */
     preset: string;
 }
 export declare const rulesWriters: Partial<Record<"claude" | "codex" | "cursor" | "opencode" | "openclaw" | "copilot" | "amp" | "goose" | "antigravity" | "grok" | "kimi" | "droid" | "hermes" | "muse" | "warp", ResourceWriter<RulesSelection>>>;

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

@@ -1,15 +1,3 @@
-/**
- * Rules writer — composes one instruction file per supported agent.
- *
- * Single-target per agent (RulesCapability is `{ file: string } | false`).
- * The composer in `lib/rules/compose.ts` handles all four layers
- * (project > user > extras > system). We never write the project layer into
- * the version home — it's resolved at agents-run time into the workspace
- * AGENTS.md by `compileRulesForProject`.
- *
- * Selection shape: `{ preset: string }`. Use `getActiveRulesPreset(agent,
- * version)` to derive the preset when the caller has no override.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import { AGENTS, agentConfigDirName } from '../../agents.js';
@@ -28,20 +16,14 @@ function buildRulesWriter(agent) {
             const targetName = cap.file;
             const composed = composeRulesFromState({ preset: selection.preset || undefined });
             const agentDir = path.join(versionHome, agentConfigDirName(agent));
-            // `cap.file` is a trusted constant from AGENTS table; openclaw ships a
-            // nested path (`workspace/AGENTS.md`) so we use path.join rather than
-            // safeJoin (which rejects path separators in `name`).
             const destFile = path.join(agentDir, targetName);
             fs.mkdirSync(path.dirname(destFile), { recursive: true });
-            // Remove any pre-existing symlink before writing — a stale symlink
-            // could point at a deleted source and writeFileSync would chase it
-            // to nothing.
             try {
                 const st = fs.lstatSync(destFile);
                 if (st.isSymbolicLink() || st.isFile())
                     fs.unlinkSync(destFile);
             }
-            catch { /* destination did not exist */ }
+            catch { }
             fs.writeFileSync(destFile, composed.content);
             return { synced: [targetName], paths: [destFile] };
         },

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

@@ -1,9 +1,3 @@
-/**
- * Skills writer — copies each selected skill directory into
- * `{agentDir}/skills/<name>/`. Agents flagged `nativeAgentsSkillsDir` (Gemini)
- * read directly from `~/.agents/skills/` and have no writer registered; the
- * sync orchestrator clears their version-home skills dir.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import { AGENTS, agentConfigDirName } from '../../agents.js';
@@ -39,7 +33,7 @@ function removePath(p) {
         else if (st.isDirectory())
             fs.rmSync(p, { recursive: true, force: true });
     }
-    catch { /* already gone */ }
+    catch { }
 }
 function buildSkillsWriter(agent) {
     return {
@@ -53,7 +47,7 @@ function buildSkillsWriter(agent) {
                     removePath(skillsTarget);
                 }
             }
-            catch { /* does not exist yet */ }
+            catch { }
             fs.mkdirSync(skillsTarget, { recursive: true });
             const synced = [];
             const paths = [];
@@ -71,9 +65,6 @@ function buildSkillsWriter(agent) {
         },
         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 };
             }
@@ -84,7 +75,7 @@ function buildSkillsWriter(agent) {
                     return { removed: true };
                 }
             }
-            catch { /* already gone / inaccessible */ }
+            catch { }
             return { removed: false };
         },
     };
@@ -92,8 +83,6 @@ function buildSkillsWriter(agent) {
 export const skillsWriters = lazyAgentMap(() => {
     const m = {};
     for (const agent of capableAgents('skills')) {
-        // Agents that natively read ~/.agents/skills/ don't get a version-home
-        // write — the orchestrator clears the dir for them.
         if (AGENTS[agent].nativeAgentsSkillsDir)
             continue;
         m[agent] = buildSkillsWriter(agent);

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

@@ -1,27 +1,16 @@
 import type { AgentId } from '../../types.js';
-/** Every `plugins/<plugin>/skills` dir across trusted source bases, filtered to an optional plugin/agent scope. */
 export declare function pluginSkillDirs(options?: {
     agent?: AgentId;
     plugins?: Set<string>;
 }): string[];
-/** Find the trusted source for a command markdown by name. */
 export declare function resolveCommandSource(name: string): string | null;
-/** Find the trusted source directory for a skill by name. */
 export declare function resolveSkillSource(name: string, options?: {
     agent?: AgentId;
     plugins?: Set<string>;
 }): string | null;
-/** List trusted plugin-bundled skill names, filtered to an optional plugin/agent scope. */
 export declare function listPluginSkillNames(options?: {
     agent?: AgentId;
     plugins?: Set<string>;
 }): string[];
-/**
- * Find the trusted source for a hook by name.
- * - File basename (`04-session-identity.sh`) or relative path
- *   (`session-starts/04-session-identity.sh`) → script file
- * - Directory basename (`tests`) → directory bundle (fixtures-only etc.)
- */
 export declare function resolveHookSource(name: string): string | null;
-/** All trusted command-skill source roots, used to dedup name collisions for commands-as-skills writes. */
 export declare function trustedSkillRoots(): string[];

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

@@ -1,18 +1,8 @@
-/**
- * Shared layer-source resolution for writers.
- *
- * Layer precedence matches getResourceBases() in versions.ts. Project layer
- * is intentionally EXCLUDED for commands/skills/hooks/subagents/permissions
- * — those bodies become agent context, and a cloned public repo could ship
- * one that coerces the agent on the next launch. Trusted layers only:
- * user → system → extras.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import { getUserAgentsDir, getAgentsDir, getEnabledExtraRepos, getCommandsDir, getSkillsDir, getHooksDir } from '../../state.js';
 import { isSafeSegmentName, safeJoin } from '../../paths.js';
 import { AGENTS } from '../../agents.js';
-/** Trusted source bases for content-like kinds. Project layer excluded. */
 function trustedSourceBases() {
     return [
         { dir: getUserAgentsDir() },
@@ -55,11 +45,8 @@ function pluginSupportsAgent(manifest, agent) {
         return true;
     return !manifest.agents || manifest.agents.length === 0 || manifest.agents.includes(agent);
 }
-/** Every `plugins/<plugin>/skills` dir across trusted source bases, filtered to an optional plugin/agent scope. */
 export function pluginSkillDirs(options = {}) {
     const dirs = [];
-    // A harness that loads plugin skills natively gets no flattened copy and no
-    // plugin credit for a top-level skills/<name>: that copy is an orphan there.
     if (options.agent && AGENTS[options.agent]?.nativePluginSkills)
         return dirs;
     for (const base of trustedSourceBases()) {
@@ -85,7 +72,6 @@ export function pluginSkillDirs(options = {}) {
     }
     return dirs;
 }
-/** Find the trusted source for a command markdown by name. */
 export function resolveCommandSource(name) {
     const candidates = [
         safeJoin(path.join(getUserAgentsDir(), 'commands'), `${name}.md`),
@@ -94,7 +80,6 @@ export function resolveCommandSource(name) {
     ];
     return candidates.find(isLiveFile) ?? null;
 }
-/** Find the trusted source directory for a skill by name. */
 export function resolveSkillSource(name, options = {}) {
     const candidates = [
         safeJoin(path.join(getUserAgentsDir(), 'skills'), name),
@@ -104,7 +89,6 @@ export function resolveSkillSource(name, options = {}) {
     ];
     return candidates.find(isLiveDir) ?? null;
 }
-/** List trusted plugin-bundled skill names, filtered to an optional plugin/agent scope. */
 export function listPluginSkillNames(options = {}) {
     const names = new Set();
     for (const skillsDir of pluginSkillDirs(options)) {
@@ -125,10 +109,6 @@ export function listPluginSkillNames(options = {}) {
     }
     return Array.from(names);
 }
-/**
- * Subdirectories under hooks/ that are never group dirs.
- * Must stay in lockstep with HOOK_GROUP_SKIP_DIRS in hooks.ts.
- */
 const HOOK_GROUP_SKIP_DIRS = new Set(['node_modules', '.git', '.cache']);
 const HOOK_SCRIPT_EXTS = new Set([
     '.sh', '.bash', '.zsh', '.py', '.js', '.ts', '.mjs', '.cjs', '.rb', '.pl', '.ps1', '.cmd', '.bat',
@@ -168,7 +148,6 @@ function findNestedHookFile(hooksRoot, basename) {
         const groupDir = path.join(hooksRoot, name);
         if (!isLiveDir(groupDir))
             continue;
-        // Only group dirs (those with scripts) contribute nested scripts.
         if (!dirHasTopLevelScripts(groupDir))
             continue;
         const candidate = path.join(groupDir, basename);
@@ -177,12 +156,6 @@ function findNestedHookFile(hooksRoot, basename) {
     }
     return null;
 }
-/**
- * Find the trusted source for a hook by name.
- * - File basename (`04-session-identity.sh`) or relative path
- *   (`session-starts/04-session-identity.sh`) → script file
- * - Directory basename (`tests`) → directory bundle (fixtures-only etc.)
- */
 export function resolveHookSource(name) {
     const roots = [
         path.join(getUserAgentsDir(), 'hooks'),
@@ -191,8 +164,6 @@ export function resolveHookSource(name) {
     ];
     const base = path.basename(name);
     for (const hooksRoot of roots) {
-        // Exact relative path (top-level or group/name) — multi-segment needs
-        // path.join + containment, not safeJoin (single-segment only).
         if (name.includes('/') || name.includes('\\')) {
             const candidate = path.resolve(hooksRoot, name);
             const rootResolved = path.resolve(hooksRoot);
@@ -204,14 +175,12 @@ export function resolveHookSource(name) {
         else if (isSafeSegmentName(name)) {
             try {
                 const top = safeJoin(hooksRoot, name);
-                // File script first; then directory bundle (e.g. tests/ fixtures).
                 if (isLiveFile(top))
                     return top;
                 if (isLiveDir(top) && !dirHasTopLevelScripts(top))
                     return top;
             }
             catch {
-                /* invalid segment */
             }
         }
         const nested = findNestedHookFile(hooksRoot, base);
@@ -220,7 +189,6 @@ export function resolveHookSource(name) {
     }
     return null;
 }
-/** All trusted command-skill source roots, used to dedup name collisions for commands-as-skills writes. */
 export function trustedSkillRoots() {
     return [
         path.join(getUserAgentsDir(), 'skills'),

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

@@ -1,12 +1,3 @@
-/**
- * Subagents writer. Every agent's on-disk layout (target dir, file/dir shape,
- * 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
- * defense as commands/skills/hooks).
- */
 import * as fs from 'fs';
 import { capableAgents } from '../../capabilities.js';
 import { listInstalledSubagents } from '../../subagents.js';
@@ -29,25 +20,18 @@ function buildSubagentsWriter(agent) {
             for (const name of selection) {
                 const sub = map.get(name);
                 if (!sub) {
-                    // Requested but not discoverable as an installed central subagent —
-                    // e.g. its AGENT.md failed to parse. Say so instead of silently
-                    // dropping it, which read as an unactionable doctor "hold" (PHNX-3187).
                     errors.push(`subagent '${name}': no parseable AGENT.md in ~/.agents/subagents`);
                     continue;
                 }
                 try {
                     target.write(dir, sub);
                     synced.push(sub.name);
-                    // The registry owns the layout — record the artifact paths this
-                    // write occupies so a later deletion reads as stale (#2398).
                     for (const entry of target.occupied(dir, sub.name)) {
                         if (fs.existsSync(entry.path))
                             paths.push(entry.path);
                     }
                 }
                 catch (e) {
-                    // A genuine fs/transform failure must surface with its reason, not
-                    // vanish behind a bare `catch` (RUSH-2677 / PHNX-3187).
                     errors.push(`subagent '${sub.name}': ${e.message}`);
                 }
             }

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

@@ -1,86 +1,28 @@
-/**
- * Per-(kind, agent) writer contract.
- *
- * The aggregator in `syncResourcesToVersion` (versions.ts) selects names per
- * kind, then dispatches into a writer from `../registry.ts`. The writer owns
- * everything kind-specific: the agent's storage format, the layered source
- * search, the conversion/copy step. Writers MUST be reached only after a
- * `supports(agent, kind, version).ok === true` precheck — they throw when
- * called on a (kind, agent) pair that the capability matrix says is false.
- *
- * The shape is intentionally narrow. Writers don't accept ambient state; the
- * caller passes the names already resolved against availability. Selection is
- * a string[] for most kinds, a PermissionsSelection object for permissions,
- * and a RulesSelection object for rules — see kind-specific writer modules.
- */
 import type { AgentId } from '../../types.js';
 import type { ResourceKind } from './kinds.js';
 export interface WriteArgs<Sel> {
-    /** Agent version (e.g. "1.2.3") — passed for version-gated capability checks and side files. */
     version: string;
-    /** Absolute path to the version's home dir, i.e. `~/.agents/.history/versions/<agent>/<version>/home`. */
     versionHome: string;
-    /** Kind-specific selection payload. */
     selection: Sel;
-    /** Current working directory — used by writers that consult project-layer state. */
     cwd: string;
 }
 export interface WriteResult {
-    /** Names actually written. Empty array = write produced nothing (not an error). */
     synced: string[];
-    /**
-     * Absolute on-disk paths of the artifacts this write materialized (a file or
-     * a dir root per resource, per the agent's layout). Recorded into the sync
-     * manifest as `writtenTargets` so `isStale` can flag a deleted artifact as
-     * stale with one existsSync per path (#2398) — no content reads, keeping the
-     * fast-guard budget (RUSH-2320). Optional: a writer whose artifact path is
-     * not cheaply known (goose recipe YAML, plugins) may omit entries; absence
-     * means "not verified", never a false stale.
-     */
     paths?: string[];
-    /**
-     * Per-item failures the writer could not complete, as user-facing sentences.
-     *
-     * `synced: []` alone cannot distinguish "nothing to do" from "refused to
-     * write and said why", which is how an unwritable harness reported success
-     * for its whole life (RUSH-2677). A writer that declines MUST say so here.
-     */
     errors?: 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/staleness/writers/workflows.js

@@ -18,7 +18,7 @@ function buildWorkflowsWriter(agent) {
                     if (r.success)
                         synced.push(name);
                 }
-                catch { /* per-item failure: skip */ }
+                catch { }
             }
             return { synced };
         },

package/dist/lib/standalone-tools.d.ts

@@ -0,0 +1,24 @@
+export declare const STANDALONE_TOOLS: readonly ["sessions", "browser", "secrets", "computer", "term"];
+export type StandaloneTool = typeof STANDALONE_TOOLS[number];
+export interface StandaloneToolPin {
+    tool: StandaloneTool;
+    pkg: string;
+    floor: string;
+}
+export declare const STANDALONE_TOOL_PINS: Readonly<Record<StandaloneTool, StandaloneToolPin>>;
+export declare function pinnedSpec(tool: StandaloneTool): string;
+export interface ToolPinRow {
+    tool: StandaloneTool;
+    pkg: string;
+    floor: string;
+    installed: string | null;
+    state: 'ok' | 'missing' | 'outdated' | 'installed' | 'upgraded' | 'failed';
+    error?: string;
+}
+export declare function meetsFloor(installed: string | null, floor: string): boolean;
+export declare function readToolPins(tools?: readonly StandaloneTool[]): Promise<ToolPinRow[]>;
+export declare function ensureToolPins(opts?: {
+    tools?: readonly StandaloneTool[];
+    dryRun?: boolean;
+    logToStderr?: boolean;
+}): Promise<ToolPinRow[]>;