@phnx-labs/agents-cli 1.20.0 → 1.20.4

package/dist/lib/plugin-marketplace.js

@@ -40,6 +40,16 @@ function settingsPath(agent, versionHome) {
 /**
  * Copy plugin source into marketplace install dir.
  * Source of truth remains ~/.agents/plugins/<name>/ — this is a per-version snapshot.
+ *
+ * Symlinks pointing OUTSIDE the plugin source root are dropped. They show up
+ * when plugin authors (legitimately) link prompt-side references to sibling
+ * codebases — e.g. the rush plugin's `app -> ../../../rush/app` for @app/...
+ * autocomplete in user prompts. Faithfully copying those symlinks pollutes
+ * the marketplace with gigabytes of node_modules / .next / brand-asset video
+ * that the consumer (Claude Code, OpenClaw) then walks during plugin
+ * discovery — which is the documented cause of multi-minute startup hangs.
+ *
+ * Internal symlinks (target stays inside the plugin root) are preserved.
  */
 export function copyPluginToMarketplace(plugin, agent, versionHome) {
     const dest = pluginInstallDir(plugin, agent, versionHome);
@@ -47,7 +57,43 @@ export function copyPluginToMarketplace(plugin, agent, versionHome) {
     if (fs.existsSync(dest)) {
         fs.rmSync(dest, { recursive: true, force: true });
     }
-    fs.cpSync(plugin.root, dest, { recursive: true, dereference: false });
+    const sourceRealRoot = (() => {
+        try {
+            return fs.realpathSync(plugin.root);
+        }
+        catch {
+            return plugin.root;
+        }
+    })();
+    const skipped = [];
+    fs.cpSync(plugin.root, dest, {
+        recursive: true,
+        dereference: false,
+        filter: (src) => {
+            try {
+                const stat = fs.lstatSync(src);
+                if (!stat.isSymbolicLink())
+                    return true;
+                const target = fs.realpathSync(src);
+                if (target === sourceRealRoot || target.startsWith(sourceRealRoot + path.sep)) {
+                    return true;
+                }
+                skipped.push(path.relative(plugin.root, src) || path.basename(src));
+                return false;
+            }
+            catch {
+                // Dangling symlink or stat failure — drop it; it can't be useful in
+                // the marketplace and would error the consumer's walk anyway.
+                skipped.push(path.relative(plugin.root, src) || path.basename(src));
+                return false;
+            }
+        },
+    });
+    if (skipped.length > 0) {
+        process.stderr.write(`agents-cli: plugin '${plugin.name}' has ${skipped.length} symlink(s) ` +
+            `pointing outside its source root; not copied to marketplace ` +
+            `(would bloat consumer startup): ${skipped.join(', ')}\n`);
+    }
     return dest;
 }
 /**

package/dist/lib/plugins.js

@@ -28,6 +28,20 @@ export const PLUGIN_EXEC_SURFACE_LABELS = {
     hasSettings: 'settings.json',
     hasPermissions: 'permissions/',
 };
+function isPluginRootEntry(pluginsDir, entry) {
+    if (entry.name.startsWith('.'))
+        return false;
+    if (entry.isDirectory())
+        return true;
+    if (!entry.isSymbolicLink())
+        return false;
+    try {
+        return fs.statSync(path.join(pluginsDir, entry.name)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Discover all plugins in ~/.agents/plugins/.
  * A valid plugin has a .claude-plugin/plugin.json manifest.
@@ -40,7 +54,7 @@ export function discoverPlugins() {
     const plugins = [];
     const entries = fs.readdirSync(pluginsDir, { withFileTypes: true });
     for (const entry of entries) {
-        if (!entry.isDirectory() || entry.name.startsWith('.'))
+        if (!isPluginRootEntry(pluginsDir, entry))
             continue;
         const pluginRoot = path.join(pluginsDir, entry.name);
         const manifest = loadPluginManifest(pluginRoot);

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

@@ -5,6 +5,20 @@
  * name so users can `agents profiles add kimi` without manual configuration.
  */
 import type { AgentId } from './types.js';
+export interface PresetVar {
+    /** Env var name to set in the resulting profile. */
+    envVar: string;
+    /** User-facing prompt text. */
+    prompt: string;
+    /** True for secrets — wizard will mask input and store in keychain. */
+    secret?: boolean;
+    /** Default value (shown in prompt). */
+    default?: string;
+    /** Optional regex pattern — input validated against it. */
+    pattern?: string;
+    /** Optional hint text shown beside the prompt. */
+    hint?: string;
+}
 /** A pre-configured profile template for a model provider. */
 export interface Preset {
     name: string;
@@ -12,10 +26,22 @@ export interface Preset {
     provider: string;
     host: AgentId;
     env: Record<string, string>;
+    vars?: PresetVar[];
     authEnvVar: string;
+    /** True if the provider can function without a keychain token (e.g. Bedrock with SSO). */
+    authOptional?: boolean;
     signupUrl?: string;
+    docPath?: string;
 }
 export declare const PRESETS: Preset[];
+export interface ResolvedPresetEnv {
+    /** Env vars from preset.env — always set, no user input. */
+    static: Record<string, string>;
+    /** Vars the wizard needs to prompt for. */
+    prompts: PresetVar[];
+}
+/** Split a preset into static env vars and prompts needed from the user. */
+export declare function expandPreset(p: Preset): ResolvedPresetEnv;
 /** Look up a preset by name (case-sensitive). */
 export declare function getPreset(name: string): Preset | undefined;
 /** Return a copy of all available presets. */

package/dist/lib/profiles-presets.js

@@ -91,41 +91,220 @@ export const PRESETS = [
     // ----- xAI Grok Build CLI (native host) -----
     {
         name: 'grok-fast',
-        description: 'xAI Grok Build CLI — fast tier. Native grok host, no OpenRouter wrapper.',
+        description: 'xAI Grok Build CLI — fast tier. Optimized for speed and low-latency coding tasks.',
         provider: 'xai',
         host: 'grok',
         authEnvVar: 'XAI_API_KEY',
         signupUrl: 'https://console.x.ai',
         env: {
-            // TODO: confirm model id (docs.x.ai/build/models, May 2026)
-            GROK_MODEL: 'grok-build-fast',
+            GROK_MODEL: 'grok-build-0.1',
         },
     },
     {
         name: 'grok-heavy',
-        description: 'xAI Grok Build CLI — heavy tier (SuperGrok). Native grok host.',
+        description: 'xAI Grok Build CLI — flagship tier (Grok 4.3). Best for complex reasoning and large context windows.',
         provider: 'xai',
         host: 'grok',
         authEnvVar: 'XAI_API_KEY',
         signupUrl: 'https://console.x.ai',
         env: {
-            // TODO: confirm model id (docs.x.ai/build/models, May 2026)
-            GROK_MODEL: 'grok-build',
+            GROK_MODEL: 'grok-4.3',
         },
     },
     // ----- Google Antigravity CLI (native host) -----
     {
         name: 'agy',
-        description: 'Google Antigravity CLI default. Auth via Google OAuth or ANTIGRAVITY_API_KEY.',
+        description: 'Google Antigravity CLI default (gemini-3.5-flash). Optimized for speed and large context.',
         provider: 'google',
         host: 'antigravity',
         authEnvVar: 'ANTIGRAVITY_API_KEY',
         signupUrl: 'https://antigravity.google',
         env: {
-        // TODO: confirm model id — antigravity defaults are managed by the CLI itself
+        // Antigravity defaults to gemini-3.5-flash as of June 2026
         },
     },
+    // ----- Direct Providers -----
+    {
+        name: 'anthropic',
+        description: 'Anthropic direct API — standard Claude Code experience with your own API key.',
+        provider: 'anthropic',
+        host: 'claude',
+        authEnvVar: 'ANTHROPIC_API_KEY',
+        signupUrl: 'https://console.anthropic.com',
+        env: {
+            ANTHROPIC_MODEL: 'claude-3-5-sonnet-latest',
+            ANTHROPIC_SMALL_FAST_MODEL: 'claude-3-5-haiku-latest',
+        },
+    },
+    // ----- Gateway / enterprise / self-hosted -----
+    {
+        name: 'proxy',
+        description: 'Generic local proxy / gateway — points at a local router (CCR, LiteLLM) or internal corporate inference endpoint.',
+        provider: 'proxy',
+        host: 'claude',
+        authEnvVar: 'ANTHROPIC_AUTH_TOKEN',
+        authOptional: true,
+        env: {
+            API_TIMEOUT_MS: '600000',
+        },
+        vars: [
+            {
+                envVar: 'ANTHROPIC_BASE_URL',
+                prompt: 'Gateway base URL',
+                default: 'http://127.0.0.1:3456',
+            },
+            {
+                envVar: 'ANTHROPIC_MODEL',
+                prompt: 'Model ID',
+                default: 'claude-3-5-sonnet-latest',
+            },
+        ],
+    },
+    {
+        name: 'truefoundry',
+        description: 'TrueFoundry AI Gateway routing to Anthropic-compatible backends (often Bedrock). Strips experimental headers + disables prompt caching to satisfy Bedrock validation.',
+        provider: 'truefoundry',
+        host: 'claude',
+        authEnvVar: 'ANTHROPIC_AUTH_TOKEN',
+        signupUrl: 'https://www.truefoundry.com',
+        docPath: 'truefoundry',
+        env: {
+            CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS: '1',
+            CLAUDE_CODE_ATTRIBUTION_HEADER: '0',
+            DISABLE_PROMPT_CACHING: '1',
+            API_TIMEOUT_MS: '600000',
+            CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY: '1',
+        },
+        vars: [
+            {
+                envVar: 'ANTHROPIC_BASE_URL',
+                prompt: 'TrueFoundry gateway base URL',
+                hint: 'e.g. https://<tenant>.truefoundry.cloud/api/llm',
+            },
+            {
+                envVar: 'ANTHROPIC_MODEL',
+                prompt: 'Model ID',
+                hint: 'provider-account/model-id',
+            },
+        ],
+    },
+    {
+        name: 'bedrock',
+        description: 'AWS Bedrock — Claude Code native Bedrock mode. Uses the standard AWS SDK credential chain (SSO, IAM roles, env). Set AWS_BEARER_TOKEN_BEDROCK only if your gateway requires a static token.',
+        provider: 'bedrock',
+        host: 'claude',
+        authEnvVar: 'AWS_BEARER_TOKEN_BEDROCK',
+        authOptional: true,
+        signupUrl: 'https://aws.amazon.com/bedrock/',
+        env: {
+            CLAUDE_CODE_USE_BEDROCK: '1',
+            DISABLE_PROMPT_CACHING: '1',
+        },
+        vars: [
+            {
+                envVar: 'AWS_REGION',
+                prompt: 'AWS region',
+                default: 'us-east-1',
+            },
+        ],
+    },
+    {
+        name: 'vertex',
+        description: 'Google Vertex AI — Claude Code native Vertex mode.',
+        provider: 'vertex',
+        host: 'claude',
+        authEnvVar: 'GOOGLE_APPLICATION_CREDENTIALS',
+        signupUrl: 'https://cloud.google.com/vertex-ai',
+        env: {
+            CLAUDE_CODE_USE_VERTEX: '1',
+        },
+        vars: [
+            {
+                envVar: 'CLOUD_ML_REGION',
+                prompt: 'Vertex region',
+                default: 'us-east5',
+            },
+            {
+                envVar: 'ANTHROPIC_VERTEX_PROJECT_ID',
+                prompt: 'GCP project ID',
+            },
+        ],
+    },
+    {
+        name: 'foundry',
+        description: 'Microsoft Azure AI Foundry — Anthropic models hosted on Azure. Distinct from TrueFoundry.',
+        provider: 'foundry',
+        host: 'claude',
+        authEnvVar: 'ANTHROPIC_FOUNDRY_API_KEY',
+        signupUrl: 'https://ai.azure.com',
+        env: {
+            CLAUDE_CODE_USE_FOUNDRY: '1',
+        },
+        vars: [
+            {
+                envVar: 'ANTHROPIC_FOUNDRY_BASE_URL',
+                prompt: 'Azure AI Foundry base URL',
+                hint: '<resource>.services.ai.azure.com/anthropic',
+            },
+        ],
+    },
+    {
+        name: 'litellm',
+        description: 'LiteLLM proxy in Anthropic-compatible mode.',
+        provider: 'litellm',
+        host: 'claude',
+        authEnvVar: 'ANTHROPIC_AUTH_TOKEN',
+        env: {
+            API_TIMEOUT_MS: '600000',
+        },
+        vars: [
+            { envVar: 'ANTHROPIC_BASE_URL', prompt: 'LiteLLM base URL' },
+            { envVar: 'ANTHROPIC_MODEL', prompt: 'Model ID' },
+        ],
+    },
+    {
+        name: 'vllm',
+        description: 'Self-hosted vLLM with native Anthropic-compatible endpoint.',
+        provider: 'vllm',
+        host: 'claude',
+        authEnvVar: 'ANTHROPIC_AUTH_TOKEN',
+        env: {
+            API_TIMEOUT_MS: '600000',
+        },
+        vars: [
+            {
+                envVar: 'ANTHROPIC_BASE_URL',
+                prompt: 'vLLM base URL',
+                default: 'http://127.0.0.1:8000',
+            },
+            { envVar: 'ANTHROPIC_MODEL', prompt: 'Model ID' },
+        ],
+    },
+    {
+        name: 'ollama',
+        description: 'Local Ollama via Codex CLI (OpenAI-compatible). Codex host because Anthropic translation through CCR/LiteLLM drops tool_use.',
+        provider: 'ollama',
+        host: 'codex',
+        authEnvVar: 'OPENAI_API_KEY',
+        env: {},
+        vars: [
+            {
+                envVar: 'OPENAI_BASE_URL',
+                prompt: 'Ollama base URL',
+                default: 'http://127.0.0.1:11434/v1',
+            },
+            {
+                envVar: 'OPENAI_MODEL',
+                prompt: 'Model ID',
+                default: 'qwen3-coder:30b',
+            },
+        ],
+    },
 ];
+/** Split a preset into static env vars and prompts needed from the user. */
+export function expandPreset(p) {
+    return { static: { ...p.env }, prompts: p.vars ?? [] };
+}
 /** Look up a preset by name (case-sensitive). */
 export function getPreset(name) {
     return PRESETS.find((p) => p.name === name);

package/dist/lib/profiles.d.ts

@@ -23,8 +23,24 @@ export interface Profile {
     preset?: string;
     provider?: string;
 }
+/**
+ * Stable, machine-readable summary used by `agents view` and `--json`.
+ * `agent` is the underlying harness (claude/codex/...) so consumers can
+ * group profiles under installed agents without reparsing host strings.
+ */
+export interface ProfileSummary {
+    name: string;
+    agent: AgentId;
+    host: string;
+    provider: string;
+    model: string;
+    auth: string;
+    path: string;
+}
 /** Get the directory where profile YAML files are stored. */
 export declare function getProfilesDir(): string;
+/** Return the on-disk YAML path for a profile name. */
+export declare function getProfilePath(name: string): string;
 /** Validate a profile name against the allowed pattern. Throws on invalid input. */
 export declare function validateProfileName(name: string): void;
 /** Check whether a profile YAML file exists on disk. */
@@ -37,6 +53,24 @@ export declare function writeProfile(profile: Profile): void;
 export declare function deleteProfile(name: string): boolean;
 /** List all valid profiles, sorted by name. Malformed files are silently skipped. */
 export declare function listProfiles(): Profile[];
+/** Format the host harness and optional pinned version for display. */
+export declare function profileHostLabel(profile: Profile): string;
+/** Return the configured provider name, deriving it from the shared keychain item when needed. */
+export declare function profileProviderLabel(profile: Profile): string;
+/** Return the configured model env value for display. */
+export declare function profileModelLabel(profile: Profile): string;
+/**
+ * Build a non-secret auth identity/status label for list surfaces.
+ *
+ * - Inline JWT in env: decode locally and show email / preferred_username / sub.
+ * - Inline opaque token in env: masked prefix/suffix (user explicitly stored it
+ *   in the YAML, so they accept the leak in their own output).
+ * - Keychain-backed auth: provider + "stored" or "missing" (non-prompting).
+ * - No auth at all: provider only.
+ */
+export declare function profileAuthLabel(profile: Profile): string;
+/** Build a stable, machine-readable summary for list and view surfaces. */
+export declare function profileSummary(profile: Profile): ProfileSummary;
 /**
  * Build a profile from a preset. The keychain item is shared across all
  * profiles that point at the same provider, so adding kimi + deepseek prompts

package/dist/lib/profiles.js

@@ -9,7 +9,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
 import { getUserAgentsDir } from './state.js';
-import { getKeychainToken, keychainItemName } from './secrets/profiles.js';
+import { getKeychainToken, hasKeychainToken, keychainItemName } from './secrets/profiles.js';
 import { getPreset } from './profiles-presets.js';
 const PROFILE_NAME_PATTERN = /^[a-z0-9][a-z0-9-_]{0,48}$/i;
 /** Get the directory where profile YAML files are stored. */
@@ -19,6 +19,11 @@ export function getProfilesDir() {
 function profilePath(name) {
     return path.join(getProfilesDir(), `${name}.yml`);
 }
+/** Return the on-disk YAML path for a profile name. */
+export function getProfilePath(name) {
+    validateProfileName(name);
+    return profilePath(name);
+}
 /** Validate a profile name against the allowed pattern. Throws on invalid input. */
 export function validateProfileName(name) {
     if (!PROFILE_NAME_PATTERN.test(name)) {
@@ -89,6 +94,112 @@ export function listProfiles() {
     }
     return profiles.sort((a, b) => a.name.localeCompare(b.name));
 }
+/** Format the host harness and optional pinned version for display. */
+export function profileHostLabel(profile) {
+    return profile.host.version ? `${profile.host.agent}@${profile.host.version}` : profile.host.agent;
+}
+/** Return the configured provider name, deriving it from the shared keychain item when needed. */
+export function profileProviderLabel(profile) {
+    return profile.provider || profile.auth?.keychainItem?.split('.')[1] || '-';
+}
+const MODEL_ENV_KEYS = [
+    'ANTHROPIC_MODEL',
+    'ANTHROPIC_SMALL_FAST_MODEL',
+    'OPENAI_MODEL',
+    'GEMINI_MODEL',
+    'GROK_MODEL',
+];
+/** Return the configured model env value for display. */
+export function profileModelLabel(profile) {
+    for (const key of MODEL_ENV_KEYS) {
+        const value = profile.env[key];
+        if (value)
+            return value;
+    }
+    for (const [key, value] of Object.entries(profile.env)) {
+        if ((key === 'MODEL' || key.endsWith('_MODEL')) && value)
+            return value;
+    }
+    return '-';
+}
+function decodeJwtPayload(token) {
+    const parts = token.split('.');
+    if (parts.length < 2)
+        return null;
+    try {
+        const normalized = parts[1].replace(/-/g, '+').replace(/_/g, '/');
+        const padded = normalized.padEnd(Math.ceil(normalized.length / 4) * 4, '=');
+        const decoded = Buffer.from(padded, 'base64').toString('utf-8');
+        const parsed = JSON.parse(decoded);
+        return parsed && typeof parsed === 'object' ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function maskToken(token) {
+    if (token.length <= 12)
+        return `${token.slice(0, 3)}...${token.slice(-2)}`;
+    return `${token.slice(0, 6)}...${token.slice(-4)}`;
+}
+const INLINE_AUTH_KEYS = [
+    'ANTHROPIC_AUTH_TOKEN',
+    'ANTHROPIC_API_KEY',
+    'OPENAI_API_KEY',
+    'GEMINI_API_KEY',
+    'GOOGLE_API_KEY',
+    'XAI_API_KEY',
+];
+function inlineAuthToken(profile) {
+    if (profile.auth?.envVar && profile.env[profile.auth.envVar]) {
+        return profile.env[profile.auth.envVar];
+    }
+    for (const key of INLINE_AUTH_KEYS) {
+        const value = profile.env[key];
+        if (value)
+            return value;
+    }
+    return undefined;
+}
+/**
+ * Build a non-secret auth identity/status label for list surfaces.
+ *
+ * - Inline JWT in env: decode locally and show email / preferred_username / sub.
+ * - Inline opaque token in env: masked prefix/suffix (user explicitly stored it
+ *   in the YAML, so they accept the leak in their own output).
+ * - Keychain-backed auth: provider + "stored" or "missing" (non-prompting).
+ * - No auth at all: provider only.
+ */
+export function profileAuthLabel(profile) {
+    const provider = profileProviderLabel(profile);
+    const token = inlineAuthToken(profile);
+    if (token) {
+        const payload = decodeJwtPayload(token);
+        const identity = payload?.email ||
+            payload?.preferred_username ||
+            payload?.username ||
+            payload?.sub;
+        if (typeof identity === 'string')
+            return `${provider} ${identity}`;
+        return `${provider} ${maskToken(token)}`;
+    }
+    if (profile.auth) {
+        return `${provider} ${hasKeychainToken(profile.auth.keychainItem) ? 'stored' : 'missing'}`;
+    }
+    return provider;
+}
+/** Build a stable, machine-readable summary for list and view surfaces. */
+export function profileSummary(profile) {
+    return {
+        name: profile.name,
+        agent: profile.host.agent,
+        host: profileHostLabel(profile),
+        provider: profileProviderLabel(profile),
+        model: profileModelLabel(profile),
+        auth: profileAuthLabel(profile),
+        path: getProfilePath(profile.name),
+    };
+}
 /**
  * Build a profile from a preset. The keychain item is shared across all
  * profiles that point at the same provider, so adding kimi + deepseek prompts

package/dist/lib/pty-server.js

@@ -192,7 +192,33 @@ export async function runPtyServer() {
     }
     const sessions = new Map();
     const socketPath = getSocketPath();
-    // Remove stale socket
+    const pidPath = getPtyPidPath();
+    // Race resolution must happen BEFORE touching the socket file. Two clients
+    // racing ensureServer() in pty-client.ts can both observe
+    // isPtyServerRunning()=false and spawn parallel servers; without the
+    // O_EXCL claim below, the second spawn would unlink the first's socket
+    // inode and overwrite its PID file, orphaning the first server with its
+    // kernel socket binding intact but unreachable via the filesystem.
+    if (isPtyServerRunning()) {
+        log('INFO', 'PTY server already running; duplicate spawn exits cleanly');
+        process.exit(0);
+    }
+    try {
+        fs.writeFileSync(pidPath, String(process.pid), { flag: 'wx', encoding: 'utf-8' });
+    }
+    catch (err) {
+        if (err && err.code === 'EEXIST') {
+            log('INFO', 'PID slot claimed by a concurrent server; exiting cleanly');
+            process.exit(0);
+        }
+        throw err;
+    }
+    // We own the PID slot; ensure it's released on any exit path, not just SIGTERM/SIGINT.
+    process.on('exit', () => { try {
+        fs.unlinkSync(pidPath);
+    }
+    catch { } });
+    // Remove stale socket from a prior crashed server. Safe now that we hold the PID slot.
     if (fs.existsSync(socketPath)) {
         try {
             fs.unlinkSync(socketPath);
@@ -510,8 +536,6 @@ export async function runPtyServer() {
     // assumption, not a nice-to-have. If we can't lock it down, refuse to
     // start so the caller learns immediately.
     fs.chmodSync(socketPath, 0o600);
-    // Write PID
-    fs.writeFileSync(getPtyPidPath(), String(process.pid), 'utf-8');
     log('INFO', `PTY server started (PID: ${process.pid}, socket: ${socketPath})`);
     // Shutdown handler
     function shutdown() {

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

@@ -20,16 +20,28 @@ export declare function humanizeCron(expr: string, _tz?: string): string;
  * - further out      → 'Jun 15, 9:00 AM'
  */
 export declare function humanizeNextRun(date: Date | null, now: Date, tz?: string): string;
+/**
+ * Maximum display length for a repo cell. Display strings longer than this
+ * are truncated with an ellipsis so column alignment is preserved.
+ * Consumers that render the column should use this constant as the column width.
+ */
+export declare const REPO_DISPLAY_MAX = 24;
 /**
  * Parse a repo string into a display label and an optional hyperlink target.
  *
  * Rules:
- *   - undefined / empty          → display '-', href null
- *   - 'owner/name' (one slash)   → display 'owner/name', href 'https://github.com/owner/name/pulls'
- *   - 'https://...' or 'http://…' → display hostname+path, href the URL verbatim
- *   - anything else              → display raw string, href null
+ *   - null / undefined / empty / non-string → display '-', href null
+ *   - 'owner/name' (one slash)              → display 'owner/name', href 'https://github.com/owner/name/pulls'
+ *   - 'https://...' or 'http://...'         → display hostname+path, href the URL verbatim
+ *   - anything else                         → display raw string, href null
+ *
+ * The display string is truncated to REPO_DISPLAY_MAX characters (with a
+ * trailing '…') when it would otherwise exceed the column width. The href
+ * is always the full untruncated URL so hyperlinks remain functional.
+ *
+ * NEVER throws — mirrors the contract of humanizeCron.
  */
-export declare function formatRepoLink(repo: string | undefined): {
+export declare function formatRepoLink(repo: unknown): {
     display: string;
     href: string | null;
 };