@phnx-labs/agents-cli 1.20.71 → 1.20.73

package/dist/lib/pty-client.js

@@ -11,8 +11,10 @@ import { fileURLToPath } from 'url';
 import * as path from 'path';
 import { getSocketPath, getPtyLogPath, isPtyServerRunning } from './pty-server.js';
 import { backgroundSpawnOptions } from './platform/process.js';
+import { BUN_VIRTUAL_ROOT } from './cli-entry.js';
 const CONNECT_TIMEOUT_MS = 5000;
 const RESPONSE_TIMEOUT_MS = 30000;
+const START_TIMEOUT_MS = 5000;
 const IS_WINDOWS = process.platform === 'win32';
 /**
  * Send a request to the PTY server and return the response.
@@ -36,18 +38,44 @@ async function ensureServer() {
     // Find the entry point to spawn the server
     const { bin, args } = getServerSpawnArgs();
     const logPath = getPtyLogPath();
-    const logFd = fs.openSync(logPath, 'a');
-    const child = spawn(bin, args, {
-        stdio: ['ignore', logFd, logFd],
-        ...backgroundSpawnOptions({ fdStdio: true }),
+    let logFd;
+    try {
+        logFd = fs.openSync(logPath, 'a');
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error([
+            'PTY server failed to start before spawning.',
+            `Spawned: ${formatCommand({ bin, args })}`,
+            `Log: ${logPath}`,
+            `Log open error: ${message}`,
+        ].join('\n'));
+    }
+    let child;
+    try {
+        child = spawn(bin, args, {
+            stdio: ['ignore', logFd, logFd],
+            ...backgroundSpawnOptions({ fdStdio: true }),
+        });
+    }
+    finally {
+        fs.closeSync(logFd);
+    }
+    let childExit;
+    let childError;
+    let lastReadinessError;
+    child.once('exit', (code, signal) => {
+        childExit = { code, signal };
+    });
+    child.once('error', (err) => {
+        childError = err;
     });
     child.unref();
-    fs.closeSync(logFd);
     // Wait for the server to become reachable. On Unix the socket file appearing is
     // a cheap readiness signal; on Windows the named pipe is not a filesystem object
     // (fs.existsSync always returns false), so we just attempt the ping directly.
     const socketPath = getSocketPath();
-    const deadline = Date.now() + 5000;
+    const deadline = Date.now() + START_TIMEOUT_MS;
     while (Date.now() < deadline) {
         if (IS_WINDOWS || fs.existsSync(socketPath)) {
             // Verify we can connect
@@ -55,15 +83,50 @@ async function ensureServer() {
                 await sendRequest({ action: 'ping' });
                 return;
             }
-            catch {
-                // Not ready yet
+            catch (err) {
+                lastReadinessError = err instanceof Error ? err : new Error(String(err));
             }
         }
+        if (childError || childExit)
+            break;
         await new Promise(r => setTimeout(r, 100));
     }
-    throw new Error('PTY server failed to start within 5 seconds. Check ~/.agents/.system/helpers/pty/logs.jsonl');
+    throw new Error(buildPtyStartFailureMessage({
+        timeoutMs: START_TIMEOUT_MS,
+        spawn: { bin, args },
+        exit: childExit,
+        spawnError: childError,
+        lastReadinessError,
+        logPath,
+    }));
 }
-function getServerSpawnArgs() {
+export function getServerSpawnArgs(options = {}) {
+    const isStandaloneExecutable = options.isStandaloneExecutable
+        ?? isBunStandaloneExecutable();
+    if (isStandaloneExecutable) {
+        // A Bun `--compile` standalone binary cannot `require()` a native addon, so
+        // running the PTY sidecar AS this binary fails to load node-pty's pty.node
+        // (fatal on macOS; see #315). Prefer a real `node` running the dist/index.js
+        // that ships beside the binary — there node-pty loads from the on-disk
+        // prebuild. We can't do `<binary> dist/index.js` (the standalone misparses a
+        // script arg as a subcommand), so a genuine `node` is required. Fall back to
+        // the binary itself only when no node / no dist is found (a bare standalone
+        // install with no Node — PTY may then be unavailable, but nothing else can
+        // load the addon anyway).
+        const node = (options.resolveNode ?? resolveNodeExecutable)();
+        const exists = options.fileExists ?? fs.existsSync;
+        const execPath = options.execPath ?? process.execPath;
+        if (node) {
+            try {
+                const distIndex = path.join(path.dirname(execPath), '..', 'index.js');
+                if (exists(distIndex)) {
+                    return { bin: node, args: [distIndex, 'pty', '_server'] };
+                }
+            }
+            catch { }
+        }
+        return { bin: process.execPath, args: ['pty', '_server'] };
+    }
     // Prefer the dist/index.js from the same installation as this code.
     // This avoids version mismatch when a globally installed `agents` is older.
     try {
@@ -86,6 +149,69 @@ function getServerSpawnArgs() {
     catch { }
     return { bin: 'agents', args: ['pty', '_server'] };
 }
+export function isBunStandaloneExecutable(moduleUrl = import.meta.url) {
+    return BUN_VIRTUAL_ROOT.test(moduleUrl);
+}
+/**
+ * Locate a real `node` on PATH for running the sidecar's dist/index.js from a
+ * Bun standalone binary (which cannot itself load native addons). Returns
+ * undefined when no node is found — the caller then falls back to the binary.
+ */
+function resolveNodeExecutable() {
+    try {
+        const lookup = IS_WINDOWS ? 'where node' : 'which node';
+        const node = execSync(lookup, { encoding: 'utf-8' }).split(/\r?\n/)[0].trim();
+        if (node && fs.existsSync(node))
+            return node;
+    }
+    catch { }
+    return undefined;
+}
+export function readRecentLogLines(logPath, maxLines = 20) {
+    try {
+        if (!fs.existsSync(logPath))
+            return [];
+        return fs.readFileSync(logPath, 'utf-8')
+            .split(/\r?\n/)
+            .filter(line => line.trim().length > 0)
+            .slice(-maxLines);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return [`Unable to read PTY server log: ${message}`];
+    }
+}
+export function buildPtyStartFailureMessage(details) {
+    const lines = [
+        `PTY server failed to start within ${Math.round(details.timeoutMs / 1000)} seconds.`,
+        `Spawned: ${formatCommand(details.spawn)}`,
+    ];
+    if (details.spawnError) {
+        lines.push(`Spawn error: ${details.spawnError.message}`);
+    }
+    if (details.exit) {
+        const reason = details.exit.signal
+            ? `signal ${details.exit.signal}`
+            : `code ${details.exit.code ?? 'unknown'}`;
+        lines.push(`PTY server process exited with ${reason} before listening.`);
+    }
+    if (details.lastReadinessError) {
+        lines.push(`Last readiness error: ${details.lastReadinessError.message}`);
+    }
+    lines.push(`Log: ${details.logPath}`);
+    const logLines = readRecentLogLines(details.logPath);
+    if (logLines.length > 0) {
+        lines.push('Recent PTY server log:');
+        lines.push(...logLines.map(line => `  ${line}`));
+    }
+    else {
+        lines.push('No PTY server log output was written.');
+    }
+    return lines.join('\n');
+}
+function formatCommand(spawnArgs) {
+    return [spawnArgs.bin, ...spawnArgs.args].map((part) => JSON.stringify(part)).join(' ');
+}
 /**
  * Send a JSON request over the unix socket and return the parsed response.
  */

package/dist/lib/refresh.js

@@ -16,7 +16,7 @@ import { capableAgents } from './capabilities.js';
 import { AGENTS, ALL_AGENT_IDS, getAllCliStates, registerMcpToTargets, agentLabel, } from './agents.js';
 import { readManifest, MANIFEST_FILENAME } from './manifest.js';
 import { getUserAgentsDir } from './state.js';
-import { installVersion, listInstalledVersions, getGlobalDefault, setGlobalDefault, getVersionHomePath, syncResourcesToVersion, getAvailableResources, getActuallySyncedResources, getNewResources, getProjectOnlyResources, hasNewResources, promptNewResourceSelection, promptResourceSelection, resolveConfiguredAgentTargets, } from './versions.js';
+import { installVersion, listInstalledVersions, isVersionIsolated, getGlobalDefault, setGlobalDefault, getVersionHomePath, syncResourcesToVersion, getAvailableResources, getActuallySyncedResources, getNewResources, getProjectOnlyResources, hasNewResources, promptNewResourceSelection, promptResourceSelection, resolveConfiguredAgentTargets, } from './versions.js';
 import { listCliStatus, installCli, describeMethod, describeCheck, selectInstallMethod, } from './cli-resources.js';
 import { ensureShimCurrent, isShimsInPath, addShimsToPath, getPathSetupInstructions, switchConfigSymlink, switchHomeFileSymlinks, } from './shims.js';
 import { parseHookManifest, registerHooksToSettings } from './hooks.js';
@@ -133,13 +133,9 @@ export async function refresh(options = {}) {
             actuallySynced.plugins.length > 0;
         try {
             let selection;
+            let forceFullSync = false;
             if (skipPrompts) {
-                if (!hasAnySynced || hasNewResources(newResources, agentId)) {
-                    selection = {
-                        commands: 'all', skills: 'all', hooks: 'all', memory: 'all',
-                        mcp: 'all', permissions: 'all', subagents: 'all', plugins: 'all',
-                    };
-                }
+                forceFullSync = true;
             }
             else if (!hasAnySynced) {
                 console.log(chalk.yellow(`\n${agentLabel(agentId)}@${defaultVer} has no synced resources.`));
@@ -153,8 +149,11 @@ export async function refresh(options = {}) {
                 if (userSelection)
                     selection = userSelection;
             }
-            if (selection && Object.keys(selection).length > 0) {
-                const syncResult = syncResourcesToVersion(agentId, defaultVer, selection);
+            else {
+                forceFullSync = true;
+            }
+            if (forceFullSync || (selection && Object.keys(selection).length > 0)) {
+                const syncResult = syncResourcesToVersion(agentId, defaultVer, selection, forceFullSync ? { force: true } : undefined);
                 const synced = [];
                 if (syncResult.commands)
                     synced.push('commands');
@@ -231,7 +230,12 @@ export async function refresh(options = {}) {
         }
         const selectedVersions = [];
         for (const agentId of agentsNeedingDefault) {
-            const versions = listInstalledVersions(agentId);
+            // Isolated copies are not default-eligible — `agents use` refuses them and
+            // setting one here would also switch the config symlink, pointing the user's
+            // real ~/.<agent> at an isolated home. Keep them out of the picker entirely.
+            const versions = listInstalledVersions(agentId).filter((v) => !isVersionIsolated(agentId, v));
+            if (versions.length === 0)
+                continue;
             const agent = AGENTS[agentId];
             const shouldSwitch = await select({
                 message: `${agentLabel(agent.id)} has no default version. Set one now?`,

package/dist/lib/resource-profiles.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Top-level resource profiles.
+ *
+ * These are distinct from model-provider run profiles in lib/profiles.ts. A
+ * resource profile is a global mode switch stored in agents.yaml that filters
+ * the resolved DotAgents resource view and secrets bundles.
+ */
+import type { ResourceProfilePreset } from './types.js';
+export type ProfiledResourceKind = 'commands' | 'skills' | 'hooks' | 'subagents' | 'plugins' | 'workflows' | 'permissions' | 'mcp' | 'memory' | 'secrets';
+export type PatternedProfileKind = Exclude<ProfiledResourceKind, 'memory' | 'secrets'>;
+export interface ActiveResourceProfile {
+    name: string;
+    preset: ResourceProfilePreset;
+}
+export declare function validateResourceProfileName(name: string): void;
+export declare function listResourceProfileNames(): string[];
+export declare function getResourceProfilePreset(name: string): ResourceProfilePreset | null;
+export declare function getActiveResourceProfileName(): string | null;
+export declare function getActiveResourceProfile(): ActiveResourceProfile | null;
+export declare function upsertResourceProfilePreset(name: string, preset: ResourceProfilePreset): void;
+export declare function setActiveResourceProfile(name: string | null): void;
+export declare function patternedProfileKinds(): PatternedProfileKind[];
+export declare function activeRulesPreset(): string | null;
+export declare function filterNamesForActiveResourceProfile(kind: ProfiledResourceKind, names: string[], sourceMap?: Map<string, string>): string[];
+export declare function isNameActiveInResourceProfile(kind: ProfiledResourceKind, name: string, source?: string): boolean;
+export declare function assertNameActiveInResourceProfile(kind: ProfiledResourceKind, name: string): void;

package/dist/lib/resource-profiles.js

@@ -0,0 +1,157 @@
+/**
+ * Top-level resource profiles.
+ *
+ * These are distinct from model-provider run profiles in lib/profiles.ts. A
+ * resource profile is a global mode switch stored in agents.yaml that filters
+ * the resolved DotAgents resource view and secrets bundles.
+ */
+import { readMeta, updateMeta } from './state.js';
+import { brandProfileName } from './brand.js';
+const PROFILE_NAME_PATTERN = /^[a-z0-9][a-z0-9-_]{0,48}$/i;
+const PATTERNED_KINDS = [
+    'commands',
+    'skills',
+    'hooks',
+    'subagents',
+    'plugins',
+    'workflows',
+    'permissions',
+    'mcp',
+];
+export function validateResourceProfileName(name) {
+    if (!PROFILE_NAME_PATTERN.test(name)) {
+        throw new Error(`Invalid profile name '${name}'. Use letters, digits, dash, underscore (max 48 chars).`);
+    }
+}
+export function listResourceProfileNames() {
+    return Object.keys(readMeta().profiles?.presets ?? {}).sort((a, b) => a.localeCompare(b));
+}
+export function getResourceProfilePreset(name) {
+    validateResourceProfileName(name);
+    return readMeta().profiles?.presets?.[name] ?? null;
+}
+export function getActiveResourceProfileName() {
+    // A white-label brand pins its own profile; when running under a brand
+    // (AGENTS_BRAND set) that preset wins over the global `profiles.active`, so
+    // every resource filter that keys off the active profile becomes brand-scoped.
+    // See lib/brand.ts.
+    const branded = brandProfileName();
+    if (branded)
+        return branded;
+    return readMeta().profiles?.active ?? null;
+}
+export function getActiveResourceProfile() {
+    const meta = readMeta();
+    const name = getActiveResourceProfileName();
+    if (!name)
+        return null;
+    const preset = meta.profiles?.presets?.[name];
+    return preset ? { name, preset } : null;
+}
+export function upsertResourceProfilePreset(name, preset) {
+    validateResourceProfileName(name);
+    updateMeta((meta) => ({
+        ...meta,
+        profiles: {
+            ...meta.profiles,
+            presets: {
+                ...(meta.profiles?.presets ?? {}),
+                [name]: preset,
+            },
+        },
+    }));
+}
+export function setActiveResourceProfile(name) {
+    if (name) {
+        validateResourceProfileName(name);
+        const preset = getResourceProfilePreset(name);
+        if (!preset)
+            throw new Error(`Profile '${name}' not found.`);
+    }
+    updateMeta((meta) => ({
+        ...meta,
+        profiles: {
+            ...meta.profiles,
+            active: name || undefined,
+        },
+    }));
+}
+export function patternedProfileKinds() {
+    return [...PATTERNED_KINDS];
+}
+function plainPatternMatches(pattern, name) {
+    if (pattern === '*')
+        return true;
+    if (!pattern.includes('*'))
+        return pattern === name;
+    const escaped = pattern
+        .split('*')
+        .map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+        .join('.*');
+    return new RegExp(`^${escaped}$`).test(name);
+}
+function filterByPlainPatterns(names, patterns) {
+    const include = patterns.filter((p) => !p.startsWith('!'));
+    const exclude = patterns.filter((p) => p.startsWith('!')).map((p) => p.slice(1));
+    return names.filter((name) => include.some((p) => plainPatternMatches(p, name)) &&
+        !exclude.some((p) => plainPatternMatches(p, name)));
+}
+function sourcePatternMatches(pattern, name, sourceMap) {
+    const colon = pattern.indexOf(':');
+    if (colon === -1)
+        return false;
+    const source = pattern.slice(0, colon);
+    const rawName = pattern.slice(colon + 1);
+    const actualSource = sourceMap.get(name);
+    if (actualSource !== source)
+        return false;
+    const patternNames = rawName === '*' ? ['*'] : rawName.split(',').map((n) => n.trim()).filter(Boolean);
+    return patternNames.some((patternName) => plainPatternMatches(patternName, name));
+}
+function expandProfilePatterns(names, patterns, sourceMap) {
+    if (sourceMap) {
+        const included = new Set();
+        const excluded = new Set();
+        for (const pattern of patterns) {
+            const negate = pattern.startsWith('!');
+            const raw = negate ? pattern.slice(1) : pattern;
+            const target = negate ? excluded : included;
+            const matches = raw.includes(':')
+                ? names.filter((name) => sourcePatternMatches(raw, name, sourceMap))
+                : names.filter((name) => plainPatternMatches(raw, name));
+            for (const name of matches)
+                target.add(name);
+        }
+        return names.filter((name) => included.has(name) && !excluded.has(name));
+    }
+    return filterByPlainPatterns(names, patterns);
+}
+export function activeRulesPreset() {
+    const preset = getActiveResourceProfile()?.preset;
+    return preset?.rules ?? preset?.rulesPreset ?? null;
+}
+export function filterNamesForActiveResourceProfile(kind, names, sourceMap) {
+    const profile = getActiveResourceProfile();
+    if (!profile)
+        return names;
+    if (kind === 'memory') {
+        const rules = activeRulesPreset();
+        return rules ? names.filter((name) => name === rules) : names;
+    }
+    const patterns = profile.preset[kind];
+    if (!patterns)
+        return names;
+    return expandProfilePatterns(names, patterns, sourceMap);
+}
+export function isNameActiveInResourceProfile(kind, name, source) {
+    const sourceMap = source ? new Map([[name, source]]) : undefined;
+    return filterNamesForActiveResourceProfile(kind, [name], sourceMap).includes(name);
+}
+export function assertNameActiveInResourceProfile(kind, name) {
+    const active = getActiveResourceProfile();
+    if (!active)
+        return;
+    if (isNameActiveInResourceProfile(kind, name))
+        return;
+    throw new Error(`${kind === 'secrets' ? 'Secrets bundle' : 'Resource'} '${name}' is not active in profile '${active.name}'.`);
+}

package/dist/lib/resources/permissions.js

@@ -77,6 +77,12 @@ function getAgentConfigPath(agent, versionHome) {
             return path.join(versionHome, '.kiro', 'settings', 'permissions.yaml');
         case 'openclaw':
             return path.join(versionHome, '.openclaw', 'openclaw.json');
+        case 'copilot':
+            return path.join(versionHome, '.copilot', 'permissions-config.json');
+        case 'forge':
+            return path.join(versionHome, '.forge', 'permissions.yaml');
+        case 'hermes':
+            return path.join(versionHome, '.hermes', 'config.yaml');
         case 'goose':
             return path.join(versionHome, '.config', 'goose', 'permission.yaml');
         default:
@@ -173,7 +179,7 @@ export const PermissionsHandler = {
             merged = mergePermissionSets(merged, r.item);
         }
         // Apply to the agent's config file
-        applyPermissionsToVersion(agent, merged, versionHome, true);
+        applyPermissionsToVersion(agent, merged, versionHome, true, cwd);
     },
     /**
      * Permissions use YAML format.

package/dist/lib/resources/types.d.ts

@@ -5,7 +5,7 @@
  * - Union: All resources from all layers are combined
  * - Override on name conflict: Higher layer wins (project > user > system)
  */
-export type AgentId = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode' | 'openclaw' | 'kiro' | 'goose' | 'antigravity' | 'grok' | 'kimi' | 'droid' | 'hermes' | 'forge';
+export type AgentId = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode' | 'openclaw' | 'copilot' | 'kiro' | 'goose' | 'antigravity' | 'grok' | 'kimi' | 'droid' | 'hermes' | 'forge';
 export type Layer = 'system' | 'user' | 'project';
 export type ResourceKind = 'command' | 'hook' | 'skill' | 'rule' | 'mcp' | 'permission' | 'subagent' | 'workflow' | 'memory';
 /** A resolved resource with its origin layer. */

package/dist/lib/resources.d.ts

@@ -5,7 +5,7 @@
 import type { AgentId } from './types.js';
 import { type SkillParseError } from './skills.js';
 /** Resource kind — matches the subdirectory name under each repo root. */
-export type ResourceKind = 'commands' | 'skills' | 'hooks' | 'rules' | 'mcp' | 'cli' | 'permissions' | 'subagents' | 'profiles' | 'secrets';
+export type ResourceKind = 'commands' | 'skills' | 'hooks' | 'rules' | 'mcp' | 'cli' | 'permissions' | 'subagents' | 'workflows' | 'profiles' | 'secrets';
 /** A resource resolved with its origin. */
 export interface ResolvedResource {
     name: string;

package/dist/lib/resources.js

@@ -14,6 +14,27 @@ import { listMcpServerConfigs } from './mcp.js';
 import { WorkflowsHandler } from './resources/workflows.js';
 import { isCapable } from './capabilities.js';
 import { getProjectAgentsDir, getUserAgentsDir, getSystemAgentsDir, getEnabledExtraRepos, } from './state.js';
+import { isNameActiveInResourceProfile } from './resource-profiles.js';
+function profiledKind(kind) {
+    switch (kind) {
+        case 'commands':
+        case 'skills':
+        case 'hooks':
+        case 'mcp':
+        case 'permissions':
+        case 'subagents':
+        case 'secrets':
+            return kind;
+        case 'rules':
+            return 'memory';
+        default:
+            return null;
+    }
+}
+function resourceIsActive(kind, name, source) {
+    const activeKind = profiledKind(kind);
+    return activeKind ? isNameActiveInResourceProfile(activeKind, name, source) : true;
+}
 /**
  * Resolve a single resource by kind + name using project > user > system precedence.
  * For file-based resources the path ends in `.md`, `.yaml`, or `.yml` as appropriate.
@@ -36,13 +57,19 @@ export function resolveResource(kind, name, cwd) {
         // Try exact name (for directories like skills/subagents)
         const exactPath = path.join(dir, name);
         if (fs.existsSync(exactPath)) {
-            return { name, path: exactPath, source };
+            if (resourceIsActive(kind, name, source)) {
+                return { name, path: exactPath, source };
+            }
+            continue;
         }
         // Try with common file extensions
         for (const ext of ['.md', '.yaml', '.yml']) {
             const withExt = exactPath + ext;
             if (fs.existsSync(withExt)) {
-                return { name, path: withExt, source };
+                if (resourceIsActive(kind, name, source)) {
+                    return { name, path: withExt, source };
+                }
+                continue;
             }
         }
     }
@@ -80,6 +107,8 @@ export function listResources(kind, cwd) {
             const rawName = entry.name.replace(/\.(md|yaml|yml)$/, '');
             if (seen.has(rawName))
                 continue;
+            if (!resourceIsActive(kind, rawName, source))
+                continue;
             seen.add(rawName);
             results.push({
                 name: rawName,
@@ -162,7 +191,7 @@ export function getAgentResources(agentId, options = {}) {
             hooks.push({ name: hook.name, path: hook.path, scope: hook.scope });
         }
     }
-    // Workflows (claude only)
+    // Workflows
     const workflows = [];
     if (isCapable(agentId, 'workflows')) {
         for (const w of WorkflowsHandler.listAll(agentId, cwd)) {

package/dist/lib/routines.d.ts

@@ -41,6 +41,10 @@ export interface GithubJobTrigger {
     repo?: string;
     /** git branch (ref short name) — when set, only payloads for this branch match. */
     branch?: string;
+    /** GitHub webhook action, e.g. `opened`, `synchronize`, or `labeled`. */
+    action?: string;
+    /** Required GitHub label name. For `pull_request.labeled`, this is the added label. */
+    label?: string;
 }
 export interface LinearJobTrigger {
     type: 'linear_event';
@@ -184,6 +188,10 @@ export declare function checkJobDeviceEligibility(config: Pick<JobConfig, 'name'
  * Higher layers shadow lower ones of the same name (first-seen wins): a project
  * routine shadows a user routine, and a user routine shadows a built-in system
  * routine (`~/.agents/.system/routines/`, shipped via gh:phnx-labs/.agents-system).
+ * When a same-name project routine wins for inspection, the user-layer
+ * `devices` allowlist is overlaid only if the project routine does not declare
+ * its own allowlist, so CWD project discovery cannot hide an operational fleet
+ * pin or erase a project-authored one.
  * Project discovery is opt-in via `cwd`; the daemon (which calls `listJobs()`
  * with no argument) sees user + system routines, so a built-in routine fires for
  * every install unless the user overrides or disables it by name.
@@ -191,6 +199,9 @@ export declare function checkJobDeviceEligibility(config: Pick<JobConfig, 'name'
 export declare function listJobs(cwd?: string): JobConfig[];
 /**
  * Read a single job config by name, checking project > user > system.
+ * Same-name project routines keep the user-layer `devices` allowlist only when
+ * the project routine does not declare its own allowlist, for the same reason
+ * as listJobs().
  * Project discovery is opt-in via `cwd`; daemon callers pass no argument and
  * resolve user + system routines (a user routine of the same name shadows a
  * built-in system routine).