@phnx-labs/agents-cli 1.22.113 → 1.22.115

package/dist/lib/routine-process-cleanup.d.ts

@@ -1,5 +1,5 @@
 import type { RunMeta } from './scheduling/routines.js';
-export interface RoutineProcessCleanupOptions {
+interface RoutineProcessCleanupOptions {
     runsDir?: string;
     alive?: (pid: number) => boolean;
     owns?: (meta: RunMeta) => Promise<boolean> | boolean;
@@ -7,3 +7,4 @@ export interface RoutineProcessCleanupOptions {
 }
 /** Reap process groups whose durable run record is already terminal. */
 export declare function reapTerminalRoutineProcesses(opts?: RoutineProcessCleanupOptions): Promise<number[]>;
+export {};

package/dist/lib/routine-readiness.d.ts

@@ -34,8 +34,6 @@ export declare function fireTimeAuthReadiness(agent: string, version: string): R
 export declare function evaluateActivationReadiness(config: JobConfig, deps?: {
     probeAgent?: (agent: string) => boolean;
 }): RoutineReadinessResult;
-/** One-line human summary of a blocked readiness result, with its repair. */
-export declare function formatReadinessBlocker(result: RoutineReadinessResult): string;
 interface RemoteProjectDefinition {
     name: string;
     root?: string;

package/dist/lib/routine-readiness.js

@@ -93,13 +93,6 @@ export function evaluateActivationReadiness(config, deps = {}) {
             : undefined,
     }, { agent: config.agent, version: pinnedLocally });
 }
-/** One-line human summary of a blocked readiness result, with its repair. */
-export function formatReadinessBlocker(result) {
-    if (result.ready || !result.readiness)
-        return 'ready';
-    const { code, message, repair } = result.readiness;
-    return `${code}: ${message}${repair ? `\n  repair: ${repair}` : ''}`;
-}
 /** Parse the target HOME sentinel and the project catalog returned by one SSH call. */
 export function parseRemoteProjectSnapshot(stdout) {
     const lines = stdout.split(/\r?\n/);

package/dist/lib/routines-project.d.ts

@@ -12,21 +12,19 @@
  * `list` shows them as disabled. `syncProjectRoutines` refreshes materialised
  * copies from their source YAML (also invoked on daemon SIGHUP).
  */
-import { type JobConfig, type JobSource } from './scheduling/routines.js';
+import { type JobConfig } from './scheduling/routines.js';
 /** Expand `~/…` and resolve to an absolute path. */
 export declare function expandProjectPath(p: string): string;
 /** Store paths home-relative when under $HOME so they travel across machines. */
 export declare function displayProjectPath(abs: string): string;
 /** Resolve the project root (parent of `.agents/`) from a cwd, or null. */
 export declare function resolveProjectRoot(cwd?: string): string | null;
-/** Git provenance for a project root (best-effort; never throws). */
-export declare function readProjectGitSource(projectRoot: string): Pick<JobSource, 'repo' | 'branch' | 'commit'>;
 /** List project routine YAML files (name + absolute path). */
 export declare function listProjectRoutineFiles(projectRoot: string): Array<{
     name: string;
     path: string;
 }>;
-export interface SyncProjectResult {
+interface SyncProjectResult {
     projectRoot: string;
     synced: string[];
     skipped: Array<{
@@ -105,3 +103,4 @@ export declare function materialiseProjectRoutine(projectRoot: string, name: str
 } | {
     error: string;
 };
+export {};

package/dist/lib/routines-project.js

@@ -49,7 +49,7 @@ export function resolveProjectRoot(cwd = process.cwd()) {
     return path.dirname(agentsDir);
 }
 /** Git provenance for a project root (best-effort; never throws). */
-export function readProjectGitSource(projectRoot) {
+function readProjectGitSource(projectRoot) {
     const abs = expandProjectPath(projectRoot);
     const out = {};
     try {

package/dist/lib/rules/compile.d.ts

@@ -16,18 +16,8 @@ import { type RulesLayer } from './compose.js';
  */
 export declare const COMPILED_HEADER: string;
 export declare const COMPILED_HEADER_PROJECT: string;
-/** Sidecar manifest recording source file hashes for staleness detection. */
-export interface CompileManifest {
-    compiledAt: string;
-    sources: {
-        path: string;
-        sha256: string;
-        mtime?: number;
-        size?: number;
-    }[];
-}
 /** Result of resolving @-imports in a rules file. */
-export interface ResolveResult {
+interface ResolveResult {
     /** Fully-inlined content. */
     content: string;
     /** Absolute paths of every file read during resolution (including the root). */
@@ -55,26 +45,13 @@ export declare function supportsRulesImports(agentId: AgentId): boolean;
  * nothing to compile.
  */
 export declare function isRulesStale(agentId: AgentId, version: string): boolean;
-/**
- * Resolve the source `rules/AGENTS.md` (with all @-imports expanded) and
- * write the result into the version home, alongside a sidecar manifest that
- * records source file hashes for staleness detection.
- *
- * Agents that natively resolve @-imports are skipped (no-op) — their sync
- * uses the standard copyFileSync path in `syncResourcesToVersion`.
- */
-export declare function compileRulesForAgent(agentId: AgentId, version: string): {
-    compiled: boolean;
-    compiledPath: string;
-    sources: number;
-};
 /**
  * Recompile rules if stale. Safe to call on every agent invocation — the
  * staleness check is fast (sha256 of 8-10 small files, ~10-20ms). Returns
  * true if a recompile happened, false otherwise.
  */
 export declare function ensureRulesFresh(agentId: AgentId, version: string): boolean;
-export interface ProjectCompileResult {
+interface ProjectCompileResult {
     /** True when cwd/AGENTS.md was newly written or rewritten. */
     compiled: boolean;
     /** Absolute path to cwd/AGENTS.md. Empty when no project rules dir was present. */
@@ -110,3 +87,4 @@ export declare function compileRulesForProject(cwd: string, opts?: {
     preset?: string;
     layers?: RulesLayer[];
 }): ProjectCompileResult;
+export {};

package/dist/lib/rules/compile.js

@@ -153,7 +153,7 @@ export function isRulesStale(agentId, version) {
  * Agents that natively resolve @-imports are skipped (no-op) — their sync
  * uses the standard copyFileSync path in `syncResourcesToVersion`.
  */
-export function compileRulesForAgent(agentId, version) {
+function compileRulesForAgent(agentId, version) {
     if (supportsRulesImports(agentId)) {
         return { compiled: false, compiledPath: '', sources: 0 };
     }

package/dist/lib/rules/compose.d.ts

@@ -26,14 +26,7 @@ export interface RulesLayer {
     /** Set when scope is 'extra'; undefined otherwise. */
     alias?: string;
 }
-export interface PresetDef {
-    /** Subrule names (without `.md`), in concatenation order. */
-    subrules: string[];
-}
-export interface RulesYaml {
-    presets?: Record<string, PresetDef>;
-}
-export interface ComposeOptions {
+interface ComposeOptions {
     /** Defaults to `"default"`. */
     preset?: string;
     /** Layers in precedence order, highest first. */
@@ -47,7 +40,7 @@ export interface ComposedSubrule {
     /** Set when the subrule is dir-form (`subrules/<name>/`); the dir itself. */
     subruleDir?: string;
 }
-export interface ComposeResult {
+interface ComposeResult {
     /** Fully concatenated, no @-imports. */
     content: string;
     /** The preset name that was applied. */
@@ -98,3 +91,4 @@ export declare function collectSubruleHooksFromState(opts?: {
     preset?: string;
     cwd?: string;
 }): Record<string, ManifestHook>;
+export {};

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

@@ -7,23 +7,18 @@
  * refreshing rules files across version homes.
  */
 import type { AgentId } from '../types.js';
-export type InstructionsScope = 'user' | 'project';
-export interface InstalledInstructions {
+type InstructionsScope = 'user' | 'project';
+interface InstalledInstructions {
     agentId: AgentId;
     scope: InstructionsScope;
     path: string;
     exists: boolean;
 }
-export interface DiscoveredInstructions {
+interface DiscoveredInstructions {
     agentId: AgentId;
     sourcePath: string;
     filename: string;
 }
-/**
- * Central rules filename constant.
- * All agents map to this file in ~/.agents/rules/, renamed per-agent when synced.
- */
-export declare const CENTRAL_RULES_FILENAME = "AGENTS.md";
 /**
  * Get the canonical central rules filename for an agent's instructionsFile.
  * Central storage uses AGENTS.md, which gets renamed per-agent when syncing:
@@ -36,15 +31,8 @@ export declare function getCentralRulesFileName(agentId: AgentId): string;
 export declare function getInstructionsPath(agentId: AgentId, scope: InstructionsScope, cwd?: string): string;
 export declare function instructionsExists(agentId: AgentId, scope?: InstructionsScope, cwd?: string): boolean;
 export declare function discoverInstructionsFromRepo(repoPath: string): DiscoveredInstructions[];
-export declare function resolveInstructionsSource(repoPath: string, agentId: AgentId): string | null;
 export declare function discoverRuleFilesFromRepo(repoPath: string): string[];
-export declare function installInstructions(sourcePath: string, agentId: AgentId, method?: 'symlink' | 'copy'): {
-    path: string;
-    method: 'symlink' | 'copy';
-    error?: string;
-};
 export declare function uninstallInstructions(agentId: AgentId): boolean;
-export declare function instructionsContentMatches(agentId: AgentId, sourcePath: string, scope?: InstructionsScope, cwd?: string): boolean;
 export declare function listInstalledInstructionsWithScope(agentId: AgentId, cwd?: string, options?: {
     home?: string;
 }): InstalledInstructions[];
@@ -61,3 +49,4 @@ export declare function installInstructionsCentrally(repoPath: string, filesToIn
  * List top-level rules files from user and system dirs (user wins on collision).
  */
 export declare function listCentralRules(): string[];
+export {};

package/dist/lib/rules/rules.js

@@ -15,7 +15,7 @@ import { getEffectiveHome } from '../installations/store.js';
  * Central rules filename constant.
  * All agents map to this file in ~/.agents/rules/, renamed per-agent when synced.
  */
-export const CENTRAL_RULES_FILENAME = 'AGENTS.md';
+const CENTRAL_RULES_FILENAME = 'AGENTS.md';
 const RULES_DOC_FILENAME = 'README.md';
 function isSyncableRuleMarkdown(filename) {
     return filename.endsWith('.md') && filename !== RULES_DOC_FILENAME;
@@ -57,9 +57,6 @@ export function getCentralRulesFileName(agentId) {
     }
     return filename;
 }
-function normalizeContent(content) {
-    return content.replace(/\r\n/g, '\n').trim();
-}
 /**
  * Get the user-scope config dir for an agent (version-aware).
  */
@@ -124,24 +121,6 @@ export function discoverInstructionsFromRepo(repoPath) {
     }
     return instructions;
 }
-export function resolveInstructionsSource(repoPath, agentId) {
-    const agent = AGENTS[agentId];
-    const rulesDir = path.join(repoPath, 'rules');
-    if (!fs.existsSync(rulesDir)) {
-        return null;
-    }
-    const possibleNames = [
-        `${agentId}.md`,
-        agent.instructionsFile,
-    ].filter(name => name !== 'AGENTS.md');
-    for (const filename of possibleNames) {
-        const sourcePath = path.join(rulesDir, filename);
-        if (fs.existsSync(sourcePath)) {
-            return sourcePath;
-        }
-    }
-    return null;
-}
 export function discoverRuleFilesFromRepo(repoPath) {
     const rulesDir = path.join(repoPath, 'rules');
     if (!fs.existsSync(rulesDir)) {
@@ -154,34 +133,6 @@ export function discoverRuleFilesFromRepo(repoPath) {
         return [];
     }
 }
-export function installInstructions(sourcePath, agentId, method = 'copy') {
-    const agent = AGENTS[agentId];
-    const configDir = getUserConfigDir(agentId);
-    const targetPath = path.join(configDir, agent.instructionsFile);
-    if (!fs.existsSync(configDir)) {
-        fs.mkdirSync(configDir, { recursive: true });
-    }
-    if (fs.existsSync(targetPath)) {
-        const stat = fs.lstatSync(targetPath);
-        if (stat.isSymbolicLink()) {
-            fs.unlinkSync(targetPath);
-        }
-        else {
-            fs.unlinkSync(targetPath);
-        }
-    }
-    try {
-        if (method === 'symlink') {
-            fs.symlinkSync(sourcePath, targetPath);
-            return { path: targetPath, method: 'symlink' };
-        }
-        fs.copyFileSync(sourcePath, targetPath);
-        return { path: targetPath, method: 'copy' };
-    }
-    catch (err) {
-        return { path: '', method: 'copy', error: err.message };
-    }
-}
 export function uninstallInstructions(agentId) {
     const agent = AGENTS[agentId];
     const configDir = getUserConfigDir(agentId);
@@ -192,20 +143,6 @@ export function uninstallInstructions(agentId) {
     }
     return false;
 }
-export function instructionsContentMatches(agentId, sourcePath, scope = 'user', cwd = process.cwd()) {
-    const installedPath = getInstructionsPath(agentId, scope, cwd);
-    if (!fs.existsSync(installedPath) || !fs.existsSync(sourcePath)) {
-        return false;
-    }
-    try {
-        const installedContent = fs.readFileSync(installedPath, 'utf-8');
-        const sourceContent = fs.readFileSync(sourcePath, 'utf-8');
-        return normalizeContent(installedContent) === normalizeContent(sourceContent);
-    }
-    catch {
-        return false;
-    }
-}
 export function listInstalledInstructionsWithScope(agentId, cwd = process.cwd(), options) {
     const results = [];
     const agent = AGENTS[agentId];

package/dist/lib/run-defaults.d.ts

@@ -13,7 +13,7 @@
  */
 import type { AgentId, Mode, RunConfig, RunDefaults } from './types.js';
 export declare const VERSION_RE: RegExp;
-export interface ParsedRunDefaultSelector {
+interface ParsedRunDefaultSelector {
     agent: AgentId;
     version: string;
     selector: string;

package/dist/lib/run-notify.d.ts

@@ -1,5 +1,5 @@
 import { type DesktopNotification } from './menubar/notify-desktop.js';
-export interface RunNotifyContext {
+interface RunNotifyContext {
     /** Agent that ran, e.g. `claude`. */
     agent: string;
     /** `--name` slug when the caller named the run; falls back to the agent. */
@@ -29,3 +29,4 @@ export declare function buildRunFinishNotification(ctx: RunNotifyContext, exitCo
  * limit, not a case to paper over.
  */
 export declare function armRunFinishNotification(ctx: RunNotifyContext): void;
+export {};

package/dist/lib/run-trace-sync.d.ts

@@ -15,7 +15,7 @@ export declare function armRunFinishTraceSync(opts?: {
 }): void;
 /**
  * Fire a fire-and-forget `agents traces sync` NOW (not on exit). An important
- * owner-bound ping (`feed post --level important`, `agents notify`,
+ * owner-bound ping (`feed post --level important`, `agents send --to owner`,
  * `send --to owner`) links the caller's `…/console/sessions/<id>` page, and that
  * page only exists once the session's shard has been uploaded — trace sync fires
  * on run exit (PHNX-3628), not when a mid-run ping is posted. This closes that

package/dist/lib/run-trace-sync.js

@@ -84,7 +84,7 @@ export function armRunFinishTraceSync(opts = {}) {
 }
 /**
  * Fire a fire-and-forget `agents traces sync` NOW (not on exit). An important
- * owner-bound ping (`feed post --level important`, `agents notify`,
+ * owner-bound ping (`feed post --level important`, `agents send --to owner`,
  * `send --to owner`) links the caller's `…/console/sessions/<id>` page, and that
  * page only exists once the session's shard has been uploaded — trace sync fires
  * on run exit (PHNX-3628), not when a mid-run ping is posted. This closes that

package/dist/lib/scheduler.d.ts

@@ -8,7 +8,7 @@
 import { Cron } from 'croner';
 import type { JobConfig } from './scheduling/routines.js';
 /** How a fire was triggered, carrying the scheduler's intended UTC slot time. */
-export interface TriggerContext {
+interface TriggerContext {
     /** The ALIGNED cron slot this callback fires for, for the single-fire claim
      *  keyed on (routine, scheduledFor). Derived by {@link fireSlot} — NOT croner's
      *  raw `currentRun()`, which carries wall-clock jitter. */
@@ -48,3 +48,4 @@ export declare class JobScheduler {
         enabled: boolean;
     }>;
 }
+export {};

package/dist/lib/scheduling/routines.d.ts

@@ -7,7 +7,7 @@
  * scheduling.
  */
 import { Cron } from 'croner';
-import { type ResolvedExecutionContext, type ProjectResolution, type PlacementMode, type RoutineKind, type ContextFsProbe } from '../routine-context.js';
+import { type ResolvedExecutionContext, type ProjectResolution, type PlacementMode, type ContextFsProbe } from '../routine-context.js';
 import type { AgentId, RunStrategy } from '../types.js';
 import type { LoopConfig } from '../loop.js';
 import { JobScheduler } from '../scheduler.js';
@@ -18,7 +18,7 @@ export declare function localLatestRun(job: JobConfig): RunMeta | null;
 export declare function listJobsForDisplay(cwd?: string): JobConfig[];
 export declare function buildRoutineListJson(): Record<string, unknown>[];
 /** One routine's live scheduler-status row for `agents routines status --json`. */
-export interface RoutineStatusRow {
+interface RoutineStatusRow {
     name: string;
     /** The single device this routine is pinned to fire on, or null when unpinned. */
     ownerDevice: string | null;
@@ -99,8 +99,6 @@ export type GithubTriggerEvent = 'pull_request' | 'push' | 'issue_comment' | 'wo
 export declare const GITHUB_TRIGGER_EVENTS: readonly GithubTriggerEvent[];
 /** Linear webhook resource types a routine can be triggered by. */
 export type LinearTriggerEvent = 'Issue' | 'IssueLabel' | 'Comment' | 'Project' | 'Cycle';
-/** Canonical set of accepted Linear trigger events — single source for validation. */
-export declare const LINEAR_TRIGGER_EVENTS: readonly LinearTriggerEvent[];
 /**
  * Map a user-facing `--on` alias to a canonical GitHub trigger event.
  * Accepts the canonical names plus friendly shortcuts (e.g. `pr`, `pr_opened`
@@ -380,7 +378,7 @@ export declare function normalizeProjects(projects: string[] | undefined): strin
  * "Cross-project" is `{ kind: 'named', name }` and can never collide with the
  * `operations` / `cross` special buckets that happen to share those titles.
  */
-export type ProjectGroup = {
+type ProjectGroup = {
     kind: 'named';
     name: string;
 } | {
@@ -431,10 +429,6 @@ export declare function projectGroupOrder(group: ProjectGroup): number;
  * - `"Unknown projects"` — when any entry is no longer a defined project (stale).
  */
 export declare function computeProjectGroup(projects: string[] | undefined, knownProjectNames: Set<string>): string;
-/** A real-filesystem {@link ContextFsProbe} for readiness checks on this machine. */
-export declare function realFsProbe(): ContextFsProbe;
-/** Classify a routine by its body kind — governs the execution-context fallback rules. */
-export declare function jobRoutineKind(config: Pick<JobConfig, 'agent' | 'workflow' | 'command'>): RoutineKind;
 /**
  * Resolve a routine's execution context (working directory + structural/fs
  * readiness) by bridging its `project`/`cwd` fields into the pure
@@ -595,7 +589,7 @@ export declare function routineOwnerDevice(config: Pick<JobConfig, 'devices'>):
  */
 export declare function hasAmbiguousDevicePin(config: Pick<JobConfig, 'devices'>): boolean;
 /** One routine whose `devices` names more than one machine, with its resolved owner. */
-export interface AmbiguousDevicePin {
+interface AmbiguousDevicePin {
     name: string;
     devices: string[];
     /** The device that now fires it — the rest are inert. */
@@ -627,7 +621,7 @@ export declare function parseHostStrategy(raw: string | undefined | null): HostS
  */
 export declare function placementRequiresFiringPin(strategy: HostStrategy): boolean;
 /** Human presentation of a device-affinity mismatch for commands and runner. */
-export interface JobEligibilityResult {
+interface JobEligibilityResult {
     /** Full human message, e.g. "Job 'NAME' can only run on: a, b". */
     message: string;
     /** One-line copy-paste suggestion, e.g. "agents routines run NAME --device a". */
@@ -670,7 +664,7 @@ export declare function readJob(name: string, cwd?: string): JobConfig | null;
  * The outcome of reading one routine file: a config, or the reason it is inert.
  * Every `problem` here means the daemon will not run the routine.
  */
-export type RoutineReadResult = {
+type RoutineReadResult = {
     config: JobConfig;
     problem: null;
 } | {
@@ -721,7 +715,7 @@ export declare function validateJob(config: Partial<JobConfig>): string[];
 export declare function validateTrigger(trigger: unknown): string[];
 /** True when a job's endAt has already elapsed. False when endAt is unset or in the future. */
 export declare function isPastEndAt(config: Pick<JobConfig, 'endAt'>, now?: Date): boolean;
-export interface OneShotScheduleParts {
+interface OneShotScheduleParts {
     minute: number;
     hour: number;
     day: number;
@@ -799,7 +793,7 @@ export declare function getLatestRun(jobName: string): RunMeta | null;
  */
 export declare function getLatestCompletedRun(jobName: string): RunMeta | null;
 /** Duration + outcome rollup for a job's run history. */
-export interface RoutineStats {
+interface RoutineStats {
     /** Total run records (any status, including `missed`). */
     count: number;
     failed: number;
@@ -917,13 +911,6 @@ export declare function parseAtTime(atTime: string): {
     schedule: string;
     runOnce: boolean;
 } | null;
-/** Check if an installed job's normalized YAML matches the source file. */
-export declare function jobContentMatches(name: string, sourcePath: string): boolean;
-/** Install a job by reading and validating a YAML source file. */
-export declare function installJobFromSource(sourcePath: string, name: string): {
-    success: boolean;
-    error?: string;
-};
 /** List all job names that have run directories. */
 export declare function listJobsWithRuns(): string[];
 /** Count total runs across all jobs. */
@@ -939,3 +926,4 @@ export declare function pruneRuns(keep: number): {
     deleted: number;
     bytesFreed: number;
 };
+export {};

package/dist/lib/scheduling/routines.js

@@ -220,7 +220,7 @@ export const GITHUB_TRIGGER_EVENTS = [
     'workflow_run',
 ];
 /** Canonical set of accepted Linear trigger events — single source for validation. */
-export const LINEAR_TRIGGER_EVENTS = [
+const LINEAR_TRIGGER_EVENTS = [
     'Issue',
     'IssueLabel',
     'Comment',
@@ -335,7 +335,7 @@ export function computeProjectGroup(projects, knownProjectNames) {
     return projectGroupTitle(computeProjectGroupKind(projects, knownProjectNames));
 }
 /** A real-filesystem {@link ContextFsProbe} for readiness checks on this machine. */
-export function realFsProbe() {
+function realFsProbe() {
     return {
         exists: (p) => fs.existsSync(p),
         isDirectory: (p) => { try {
@@ -354,7 +354,7 @@ export function realFsProbe() {
     };
 }
 /** Classify a routine by its body kind — governs the execution-context fallback rules. */
-export function jobRoutineKind(config) {
+function jobRoutineKind(config) {
     if (config.command)
         return 'command';
     if (config.workflow)
@@ -1725,49 +1725,6 @@ export function parseAtTime(atTime) {
     }
     return null;
 }
-/** Check if an installed job's normalized YAML matches the source file. */
-export function jobContentMatches(name, sourcePath) {
-    const existing = readJob(name);
-    if (!existing)
-        return false;
-    try {
-        const sourceContent = fs.readFileSync(sourcePath, 'utf-8');
-        const sourceJob = yaml.parse(sourceContent);
-        if (!sourceJob)
-            return false;
-        const existingNormalized = yaml.stringify(existing);
-        const fullSource = { ...JOB_DEFAULTS, ...sourceJob, name: sourceJob.name || name };
-        const sourceNormalized = yaml.stringify(fullSource);
-        return existingNormalized === sourceNormalized;
-    }
-    catch {
-        return false;
-    }
-}
-/** Install a job by reading and validating a YAML source file. */
-export function installJobFromSource(sourcePath, name) {
-    try {
-        const content = fs.readFileSync(sourcePath, 'utf-8');
-        const parsed = yaml.parse(content);
-        if (!parsed)
-            return { success: false, error: 'Invalid YAML' };
-        const config = {
-            ...JOB_DEFAULTS,
-            ...parsed,
-            name: parsed.name || name,
-        };
-        const errors = validateJob(config);
-        if (errors.length > 0) {
-            return { success: false, error: errors.join(', ') };
-        }
-        writeJob(config);
-        setJobEnabled(config.name, config.enabled);
-        return { success: true };
-    }
-    catch (err) {
-        return { success: false, error: err.message };
-    }
-}
 /** List all job names that have run directories. */
 export function listJobsWithRuns() {
     const runsDir = getRunsDir();

package/dist/lib/secrets-cli.d.ts

@@ -0,0 +1,11 @@
+export declare const SECRETS_CLI_NAME = "secrets";
+export declare const SECRETS_CLI_PACKAGE = "@phnx-labs/secrets-cli";
+/** Published standalone `agents setup secrets` installs; bump with the protocol. */
+export declare const SECRETS_CLI_VERSION = "0.1.4";
+export declare const SECRETS_CLI_SPEC = "@phnx-labs/secrets-cli@0.1.4";
+export declare const SECRETS_CLI_INSTALL_HINT = "npm i -g @phnx-labs/secrets-cli@0.1.4";
+/**
+ * True when `$SECRETS_BIN` is set or a real `secrets` executable is on PATH
+ * outside agents-cli's shims dir. Does not spawn the binary.
+ */
+export declare function isSecretsPresent(): boolean;

package/dist/lib/secrets-cli.js

@@ -0,0 +1,30 @@
+/**
+ * The standalone `secrets` CLI that agents-cli talks to (PHNX-3989).
+ *
+ * The engine lives in `@phnx-labs/secrets-cli`. This module is the single pin
+ * and presence check shared by the process client (`secrets-client.ts`) and
+ * `agents setup secrets` — it carries no storage. Presence is `findInPath`,
+ * which skips `~/.agents/.cache/shims`: a leftover alias there `exec`s
+ * `agents secrets` and would recurse (agi-cli#3532).
+ *
+ * Keep this file free of `cli-resources` imports: `secrets-client.ts` loads it,
+ * and a cycle through the host-CLI parser would pull yaml/spawn into the
+ * process-client module graph.
+ */
+import { findInPath } from './agent-spec/agents.js';
+export const SECRETS_CLI_NAME = 'secrets';
+export const SECRETS_CLI_PACKAGE = '@phnx-labs/secrets-cli';
+/** Published standalone `agents setup secrets` installs; bump with the protocol. */
+export const SECRETS_CLI_VERSION = '0.1.4';
+export const SECRETS_CLI_SPEC = `${SECRETS_CLI_PACKAGE}@${SECRETS_CLI_VERSION}`;
+export const SECRETS_CLI_INSTALL_HINT = `npm i -g ${SECRETS_CLI_SPEC}`;
+/**
+ * True when `$SECRETS_BIN` is set or a real `secrets` executable is on PATH
+ * outside agents-cli's shims dir. Does not spawn the binary.
+ */
+export function isSecretsPresent() {
+    const explicit = process.env.SECRETS_BIN?.trim();
+    if (explicit)
+        return true;
+    return findInPath(SECRETS_CLI_NAME) !== null;
+}