@phnx-labs/agents-cli 1.20.50 → 1.20.51

package/dist/lib/shims.js

@@ -214,7 +214,14 @@ async function promptConflictStrategy(conflictInfos) {
 // v25 — dispatcher self-recovery: if the baked AGENTS_BIN is gone (a removed/moved
 //        dev build that generated the shim), resolve `agents` on PATH instead of
 //        exiting 127, so a stale/vanished dev build can't brick every launch.
-export const SHIM_SCHEMA_VERSION = 25;
+// v26 — grok resolves its binary from the versioned home's .grok/downloads first
+//        ($VERSION_DIR/home/.grok/downloads, where the binary lands when the
+//        installer runs with GROK_HOME set or grok self-updates under the shim),
+//        then falls back to the global ~/.grok/downloads for pre-fix installs.
+//        The old dispatcher checked only the global dir, so a pinned grok that
+//        installed into the versioned home fell through to the "not installed"
+//        error.
+export const SHIM_SCHEMA_VERSION = 26;
 /** Internal marker string used to embed the schema version in shim scripts. */
 const SHIM_VERSION_MARKER = 'agents-shim-version:';
 function shellQuote(value) {
@@ -468,11 +475,14 @@ fi
 
 VERSION_DIR="$AGENTS_USER_DIR/.history/versions/$AGENT/$VERSION"
 
-# Grok special case: binary lives in ~/.grok/downloads/, not node_modules.
-# We still use the agents-cli version dir purely for GROK_HOME isolation.
+# Grok special case: binary lives in the versioned home's .grok/downloads (or,
+# for pre-fix installs, the global ~/.grok/downloads), not node_modules. We
+# still use the agents-cli version dir purely for GROK_HOME isolation.
 if [ "$AGENT" = "grok" ]; then
-  # Try to find a matching binary for the pinned version in the global grok downloads dir.
-  GROK_DOWNLOADS="$HOME/.grok/downloads"
+  # Check the versioned home first — this is where the binary lands when the
+  # installer runs with GROK_HOME set (i.e. via the shim or a correct
+  # \`agents add grok\`), or when grok self-updates from within the shim.
+  GROK_DOWNLOADS="$VERSION_DIR/home/.grok/downloads"
   if [ -d "$GROK_DOWNLOADS" ]; then
     # Prefer a binary whose filename contains the exact version
     BINARY=$(ls "$GROK_DOWNLOADS"/grok-* 2>/dev/null | grep -i "$VERSION" | head -1)
@@ -481,6 +491,17 @@ if [ "$AGENT" = "grok" ]; then
       BINARY=$(ls "$GROK_DOWNLOADS"/grok-* 2>/dev/null | head -1)
     fi
   fi
+  # Fall back to the global grok home (binary installed without GROK_HOME set,
+  # e.g. an earlier \`agents add grok@latest\` before this resolution fix).
+  if [ -z "$BINARY" ] || [ ! -x "$BINARY" ]; then
+    GROK_DOWNLOADS="$HOME/.grok/downloads"
+    if [ -d "$GROK_DOWNLOADS" ]; then
+      BINARY=$(ls "$GROK_DOWNLOADS"/grok-* 2>/dev/null | grep -i "$VERSION" | head -1)
+      if [ -z "$BINARY" ]; then
+        BINARY=$(ls "$GROK_DOWNLOADS"/grok-* 2>/dev/null | head -1)
+      fi
+    fi
+  fi
   if [ -z "$BINARY" ] || [ ! -x "$BINARY" ]; then
     # Last resort: the adopted native launcher (recorded absolute path) if we
     # adopted grok, else whatever is on PATH. Prefer the adopted record — after
@@ -744,8 +765,14 @@ export function removeShim(agent) {
  *        editor opens the script and the agent never launches. The `.cmd` is
  *        now the only Windows artifact and carries this alias marker so
  *        staleness checks read it directly.
+ *  v13 — grok aliases resolve the binary from the versioned home's
+ *        .grok/downloads first, then fall back to the global ~/.grok/downloads.
+ *        The old template checked only the global dir, so a `grok@<version>`
+ *        alias failed with "not installed" whenever the binary was staged into
+ *        the versioned home (installer run with GROK_HOME set, or grok
+ *        self-update under the shim).
  */
-export const VERSIONED_ALIAS_SCHEMA_VERSION = 12;
+export const VERSIONED_ALIAS_SCHEMA_VERSION = 13;
 /** Internal marker string used to embed the schema version in versioned alias scripts. */
 const VERSIONED_ALIAS_VERSION_MARKER = 'agents-versioned-alias-version:';
 // The version string is interpolated into a generated bash script and into
@@ -822,13 +849,22 @@ export KIMI_CODE_HOME="$HOME/.agents/.history/versions/${agent}/${version}/home/
     // "agents __shim" which resolves via getBinaryPath() instead.
     const versionDir = `$HOME/.agents/.history/versions/${agent}/${version}`;
     const binaryResolution = agent === 'grok'
-        ? `# Grok ships its native binary in ~/.grok/downloads, not node_modules.
-GROK_DOWNLOADS="$HOME/.grok/downloads"
+        ? `# Grok ships its native binary in the versioned home's .grok/downloads (or,
+# for pre-fix installs, the global ~/.grok/downloads), not node_modules.
+GROK_DOWNLOADS="${versionDir}/home/.grok/downloads"
 BINARY=""
 if [ -d "$GROK_DOWNLOADS" ]; then
   BINARY=$(ls "$GROK_DOWNLOADS"/grok-* 2>/dev/null | grep -i "${version}" | head -1)
   [ -n "$BINARY" ] || BINARY=$(ls "$GROK_DOWNLOADS"/grok-* 2>/dev/null | head -1)
 fi
+# Fall back to the global grok home (binary installed without GROK_HOME set).
+if [ -z "$BINARY" ] || [ ! -x "$BINARY" ]; then
+  GROK_GLOBAL_DOWNLOADS="$HOME/.grok/downloads"
+  if [ -d "$GROK_GLOBAL_DOWNLOADS" ]; then
+    BINARY=$(ls "$GROK_GLOBAL_DOWNLOADS"/grok-* 2>/dev/null | grep -i "${version}" | head -1)
+    [ -n "$BINARY" ] || BINARY=$(ls "$GROK_GLOBAL_DOWNLOADS"/grok-* 2>/dev/null | head -1)
+  fi
+fi
 # Refuse a PATH match under our own shims dir — it resolves to this alias's
 # sibling dispatcher shim (shims dir is ahead of ~/.local/bin on PATH) and
 # re-execs forever. Fall through to the clean "not installed" error instead.

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

@@ -50,10 +50,41 @@ export declare const REMOTE_TASK_NAME = "AgentsComputerHelper";
 /** Basename of the cross-published exe under native/computer-win/dist. */
 export declare const WIN_HELPER_EXE = "computer-helper-win.exe";
 /**
- * Locate the cross-published Windows daemon exe. Only the local build output is
- * a candidate — `scripts/build-win.sh` writes it to packages/.../dist/.
+ * Locate a locally built Windows daemon exe — a repo-checkout build output from
+ * `scripts/build-win.sh`, or one bundled next to the package. Local paths are
+ * only the first candidate; npm-installed CLIs have neither and fall through to
+ * the release-asset download (`ensureWinHelperExe`).
  */
 export declare function resolveWinHelperExe(): string | null;
+/** GitHub repo whose `v<version>` releases carry the exe as an asset. */
+export declare const WIN_HELPER_RELEASE_REPO = "phnx-labs/agents-cli";
+/** Cache dir for downloaded helper exes, one subdir per release tag. */
+export declare function winHelperCacheDir(version: string): string;
+/** Release-asset URLs for the exe + its checksum at one exact `v<version>` tag. */
+export declare function winHelperAssetUrls(version: string): {
+    exe: string;
+    sha256: string;
+};
+/**
+ * Parse the published `.sha256` asset — `sha256sum` format (`<hex>  <name>`) or
+ * a bare hex digest. Throws on anything that does not lead with 64 hex chars.
+ */
+export declare function parseSha256Asset(text: string): string;
+/** Stream a file through sha256 — the exe is ~157MB, never read it whole. */
+export declare function sha256File(file: string): Promise<string>;
+/**
+ * Download the exe release asset for this CLI version, verify its sha256
+ * against the published `.sha256` asset, and cache it under the agents cache
+ * dir. Only the exact `v<version>` tag is consulted — a missing asset is a
+ * hard error naming that tag, never a silent fallback to another release.
+ */
+export declare function downloadWinHelperExe(version: string): Promise<string>;
+/**
+ * Resolve the helper exe for `setup --host`: local build outputs first (repo
+ * checkout / bundled), then the checksum-verified release-asset download for
+ * the running CLI version. Throws with the tag it checked when neither exists.
+ */
+export declare function ensureWinHelperExe(version?: string): Promise<string>;
 /** Persisted per-device tunnel state so verbs can reconnect after `start --host`. */
 export interface RemoteTunnelState {
     device: string;

package/dist/lib/ssh-tunnel.js

@@ -21,7 +21,9 @@ import * as net from 'net';
 import * as fs from 'fs';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
-import { randomBytes } from 'crypto';
+import { randomBytes, createHash } from 'crypto';
+import { Readable } from 'stream';
+import { pipeline } from 'stream/promises';
 import { sshExec, SSH_OPTS } from './ssh-exec.js';
 import { backgroundSpawnOptions } from './platform/process.js';
 import { encodePowerShell } from './browser/drivers/ssh.js';
@@ -29,6 +31,7 @@ import { getDevice } from './devices/registry.js';
 import { sshTargetFor } from './devices/connect.js';
 import { hostNameFor } from './devices/ssh-config.js';
 import { getCacheDir } from './state.js';
+import { getCliVersion } from './version.js';
 import { openComputerClient, resolveTcpEndpoint } from './computer-rpc.js';
 /** Build the ssh argv (after the `ssh` program name) for an `-L` tunnel. Pure.
  *
@@ -89,8 +92,10 @@ export const REMOTE_TASK_NAME = 'AgentsComputerHelper';
 /** Basename of the cross-published exe under native/computer-win/dist. */
 export const WIN_HELPER_EXE = 'computer-helper-win.exe';
 /**
- * Locate the cross-published Windows daemon exe. Only the local build output is
- * a candidate — `scripts/build-win.sh` writes it to packages/.../dist/.
+ * Locate a locally built Windows daemon exe — a repo-checkout build output from
+ * `scripts/build-win.sh`, or one bundled next to the package. Local paths are
+ * only the first candidate; npm-installed CLIs have neither and fall through to
+ * the release-asset download (`ensureWinHelperExe`).
  */
 export function resolveWinHelperExe() {
     const here = path.dirname(fileURLToPath(import.meta.url));
@@ -106,6 +111,89 @@ export function resolveWinHelperExe() {
     }
     return null;
 }
+/** GitHub repo whose `v<version>` releases carry the exe as an asset. */
+export const WIN_HELPER_RELEASE_REPO = 'phnx-labs/agents-cli';
+/** Cache dir for downloaded helper exes, one subdir per release tag. */
+export function winHelperCacheDir(version) {
+    return path.join(getCacheDir(), 'computer', 'win-helper', `v${version}`);
+}
+/** Release-asset URLs for the exe + its checksum at one exact `v<version>` tag. */
+export function winHelperAssetUrls(version) {
+    const base = `https://github.com/${WIN_HELPER_RELEASE_REPO}/releases/download/v${version}`;
+    return { exe: `${base}/${WIN_HELPER_EXE}`, sha256: `${base}/${WIN_HELPER_EXE}.sha256` };
+}
+/**
+ * Parse the published `.sha256` asset — `sha256sum` format (`<hex>  <name>`) or
+ * a bare hex digest. Throws on anything that does not lead with 64 hex chars.
+ */
+export function parseSha256Asset(text) {
+    const m = text.trim().match(/^([A-Fa-f0-9]{64})(\s|$)/);
+    if (!m)
+        throw new Error(`malformed .sha256 release asset: ${JSON.stringify(text.slice(0, 80))}`);
+    return m[1].toLowerCase();
+}
+/** Stream a file through sha256 — the exe is ~157MB, never read it whole. */
+export function sha256File(file) {
+    return new Promise((resolve, reject) => {
+        const hash = createHash('sha256');
+        fs.createReadStream(file)
+            .on('error', reject)
+            .on('data', (d) => hash.update(d))
+            .on('end', () => resolve(hash.digest('hex')));
+    });
+}
+/**
+ * Download the exe release asset for this CLI version, verify its sha256
+ * against the published `.sha256` asset, and cache it under the agents cache
+ * dir. Only the exact `v<version>` tag is consulted — a missing asset is a
+ * hard error naming that tag, never a silent fallback to another release.
+ */
+export async function downloadWinHelperExe(version) {
+    const cached = path.join(winHelperCacheDir(version), WIN_HELPER_EXE);
+    if (fs.existsSync(cached))
+        return cached;
+    const tag = `v${version}`;
+    const { exe: exeUrl, sha256: shaUrl } = winHelperAssetUrls(version);
+    const missing = (status, url) => new Error(`no ${WIN_HELPER_EXE} release asset for tag ${tag} (HTTP ${status} on ${url}). ` +
+        `The Windows helper ships as a GitHub release asset per tagged CLI version; ` +
+        `from a repo checkout you can build it locally instead: bash scripts/build-win.sh`);
+    // Checksum first: it is tiny and 404s fast when the tag has no assets.
+    const shaRes = await fetch(shaUrl, { signal: AbortSignal.timeout(30_000) });
+    if (!shaRes.ok)
+        throw missing(shaRes.status, shaUrl);
+    const expected = parseSha256Asset(await shaRes.text());
+    console.error(`Downloading ${WIN_HELPER_EXE} ${tag} from GitHub releases (~160 MB)...`);
+    const exeRes = await fetch(exeUrl, { signal: AbortSignal.timeout(15 * 60_000) });
+    if (!exeRes.ok || !exeRes.body)
+        throw missing(exeRes.status, exeUrl);
+    fs.mkdirSync(path.dirname(cached), { recursive: true });
+    // Stream to a partial file and rename only after the checksum passes, so an
+    // interrupted download can never be picked up as a valid cache hit.
+    const partial = `${cached}.download`;
+    try {
+        await pipeline(Readable.fromWeb(exeRes.body), fs.createWriteStream(partial));
+        const actual = await sha256File(partial);
+        if (actual !== expected) {
+            throw new Error(`sha256 mismatch for ${exeUrl}: expected ${expected}, got ${actual}`);
+        }
+        fs.renameSync(partial, cached);
+    }
+    finally {
+        fs.rmSync(partial, { force: true });
+    }
+    return cached;
+}
+/**
+ * Resolve the helper exe for `setup --host`: local build outputs first (repo
+ * checkout / bundled), then the checksum-verified release-asset download for
+ * the running CLI version. Throws with the tag it checked when neither exists.
+ */
+export async function ensureWinHelperExe(version = getCliVersion()) {
+    const local = resolveWinHelperExe();
+    if (local)
+        return local;
+    return downloadWinHelperExe(version);
+}
 function remoteStateDir() {
     return path.join(getCacheDir(), 'computer', 'remote');
 }
@@ -249,10 +337,9 @@ function copyFileOverScp(target, remotePath, filePath, timeoutMs = 600_000) {
  */
 export async function setupRemoteHelper(name) {
     const { target } = await resolveRemoteDevice(name);
-    const exe = resolveWinHelperExe();
-    if (!exe) {
-        throw new Error(`Windows helper exe not built. Run: bash scripts/build-win.sh`);
-    }
+    // Local build output, else the checksum-verified GitHub release asset for
+    // this CLI version. Throws naming the tag it checked when neither exists.
+    const exe = await ensureWinHelperExe();
     const prep = sshExec(target, encodePowerShell(buildPushScript()), { timeoutMs: 60_000 });
     if (prep.code !== 0) {
         throw new Error(`preparing helper exe path on '${name}' failed (exit ${prep.code ?? 'null'}): ${prep.stderr.trim() || prep.stdout.trim()}`);

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

@@ -53,4 +53,3 @@ export interface SyncManifest {
     workflows?: Record<string, DirEntry>;
     plugins?: Record<string, PluginEntry>;
 }
-export type ResourceType = 'commands' | 'skills' | 'hooks' | 'mcp' | 'rules' | 'subagents' | 'workflows' | 'plugins' | 'permissions';

package/dist/lib/types.d.ts

@@ -128,6 +128,19 @@ export interface AgentConfig {
     capabilities: {
         hooks: Capability;
         mcp: Capability;
+        /**
+         * Whether `mcp add --transport http` is supported. Only true for agents
+         * whose CLI accepts an HTTP-transport MCP server registration; false for
+         * agents that only accept stdio (registerMcp skips HTTP registration with
+         * a clear reason).
+         */
+        mcpHttp: Capability;
+        /**
+         * Whether HTTP-MCP registration accepts `--header` args. Independent of
+         * `mcpHttp`: only Claude's CLI takes headers today; Codex/Gemini accept
+         * HTTP MCP but reject header args.
+         */
+        mcpHeaders: Capability;
         allowlist: Capability;
         skills: Capability;
         commands: Capability;
@@ -164,7 +177,7 @@ export type RulesCapability = false | {
     file: string;
 };
 /** Names of every gateable capability on AgentConfig. */
-export type CapabilityName = 'hooks' | 'mcp' | 'allowlist' | 'skills' | 'commands' | 'plugins' | 'subagents' | 'rules' | 'workflows';
+export type CapabilityName = 'hooks' | 'mcp' | 'mcpHttp' | 'mcpHeaders' | 'allowlist' | 'skills' | 'commands' | 'plugins' | 'subagents' | 'rules' | 'workflows';
 /**
  * Permission modes controlling agent autonomy.
  *   plan  read-only investigation; no writes, no shell side-effects

package/dist/lib/versions.d.ts

@@ -379,32 +379,6 @@ export interface SyncResult {
     plugins: string[];
     workflows: string[];
 }
-/** Diff between central ~/.agents/ resources and what is synced to a version home. */
-export interface ResourceDiff {
-    commands: {
-        added: string[];
-        dangling: string[];
-    };
-    skills: {
-        added: string[];
-        dangling: string[];
-    };
-    hooks: {
-        added: string[];
-        dangling: string[];
-    };
-    memory: {
-        added: string[];
-        dangling: string[];
-    };
-    totalAdded: number;
-    totalDangling: number;
-}
-/**
- * Get the diff between central resources (~/.agents/) and what's synced to a version.
- * Uses filesystem state - no tracking needed.
- */
-export declare function getResourceDiff(agent: AgentId, version: string): ResourceDiff;
 /**
  * Enumerate the DotAgent repo names that resources can be scoped to:
  * the fixed `project` / `user` / `system` layers plus every enabled extra

package/dist/lib/versions.js

@@ -21,7 +21,7 @@ import { exec, execFile } from 'child_process';
 import { promisify } from 'util';
 import chalk from 'chalk';
 import { checkbox, select } from '@inquirer/prompts';
-import { getVersionsDir, ensureAgentsDir, readMeta, writeMeta, getCommandsDir, getSkillsDir, getHooksDir, getResolvedRulesDir, getUserRulesDir, getVersionResources, ensureVersionResourcePatterns, getProjectAgentsDir, getPromptcutsPath, getUserPromptcutsPath, getEnabledExtraRepos, getAgentsDir, getUserAgentsDir, getTrashVersionsDir, getActiveRulesPreset, getHomeDir } from './state.js';
+import { getVersionsDir, ensureAgentsDir, readMeta, writeMeta, getSkillsDir, getResolvedRulesDir, getUserRulesDir, getVersionResources, ensureVersionResourcePatterns, getProjectAgentsDir, getPromptcutsPath, getUserPromptcutsPath, getEnabledExtraRepos, getAgentsDir, getUserAgentsDir, getTrashVersionsDir, getActiveRulesPreset, getHomeDir } from './state.js';
 import { defaultPatterns, expandPatterns } from './resource-patterns.js';
 import { listResources } from './resources.js';
 // VERSION_RE + compareVersions are owned by the agent-spec engine primitives
@@ -40,7 +40,7 @@ import { discoverPlugins } from './plugins.js';
 import { loadManifest, saveManifest, buildManifest as buildSyncManifest, isStale } from './staleness/index.js';
 import { emit } from './events.js';
 import { safeJoin } from './paths.js';
-import { listCommandSkillsInVersion, readSkillSourceCommandMarker, shouldInstallCommandAsSkill } from './command-skills.js';
+import { readSkillSourceCommandMarker, shouldInstallCommandAsSkill } from './command-skills.js';
 import { getWriter, getDetector } from './staleness/registry.js';
 /** Promisified exec for running shell commands. */
 const execAsync = promisify(exec);
@@ -1826,149 +1826,6 @@ async function getCliVersionFromPath(agent) {
         return null;
     }
 }
-/**
- * Get the diff between central resources (~/.agents/) and what's synced to a version.
- * Uses filesystem state - no tracking needed.
- */
-export function getResourceDiff(agent, version) {
-    const agentConfig = AGENTS[agent];
-    const versionHome = getVersionHomePath(agent, version);
-    const agentDir = path.join(versionHome, agentConfigDirName(agent));
-    const diff = {
-        commands: { added: [], dangling: [] },
-        skills: { added: [], dangling: [] },
-        hooks: { added: [], dangling: [] },
-        memory: { added: [], dangling: [] },
-        totalAdded: 0,
-        totalDangling: 0,
-    };
-    // Helper to check symlink status
-    const getSymlinkStatus = (linkPath) => {
-        try {
-            const stat = fs.lstatSync(linkPath);
-            if (!stat.isSymbolicLink())
-                return 'none';
-            // Check if target exists
-            try {
-                fs.statSync(linkPath);
-                return 'valid';
-            }
-            catch {
-                return 'dangling';
-            }
-        }
-        catch {
-            return 'none';
-        }
-    };
-    // Commands: check directory symlink (or individual files for Gemini / generated skills for newer Codex)
-    const centralCommands = getCommandsDir();
-    const commandsTarget = path.join(agentDir, agentConfig.commandsSubdir);
-    if (shouldInstallCommandAsSkill(agent, version)) {
-        const centralFiles = fs.existsSync(centralCommands)
-            ? fs.readdirSync(centralCommands).filter(f => f.endsWith('.md'))
-            : [];
-        const centralNames = new Set(centralFiles.map(f => f.replace('.md', '')));
-        const versionNames = new Set(listCommandSkillsInVersion(agentDir));
-        for (const file of centralFiles) {
-            const name = file.replace('.md', '');
-            if (!versionNames.has(name)) {
-                diff.commands.added.push(file);
-            }
-        }
-        for (const name of versionNames) {
-            if (!centralNames.has(name)) {
-                diff.commands.dangling.push(`${name}.md`);
-            }
-        }
-    }
-    else if (agentConfig.format === 'toml') {
-        // Gemini: compare .md files in central vs .toml files in version
-        if (fs.existsSync(centralCommands)) {
-            const centralFiles = fs.readdirSync(centralCommands).filter(f => f.endsWith('.md'));
-            const versionFiles = fs.existsSync(commandsTarget)
-                ? fs.readdirSync(commandsTarget).filter(f => f.endsWith('.toml'))
-                : [];
-            const versionNames = new Set(versionFiles.map(f => f.replace('.toml', '')));
-            for (const file of centralFiles) {
-                const name = file.replace('.md', '');
-                if (!versionNames.has(name)) {
-                    diff.commands.added.push(file);
-                }
-            }
-            // Check for dangling (toml exists but no md source)
-            const centralNames = new Set(centralFiles.map(f => f.replace('.md', '')));
-            for (const file of versionFiles) {
-                const name = file.replace('.toml', '');
-                if (!centralNames.has(name)) {
-                    diff.commands.dangling.push(file);
-                }
-            }
-        }
-    }
-    else {
-        // Other agents: check directory symlink
-        const status = getSymlinkStatus(commandsTarget);
-        if (status === 'none' && fs.existsSync(centralCommands)) {
-            const files = fs.readdirSync(centralCommands).filter(f => f.endsWith('.md'));
-            diff.commands.added = files;
-        }
-        else if (status === 'dangling') {
-            diff.commands.dangling = ['commands/'];
-        }
-    }
-    // Skills: check directory symlink (skip if agent natively reads ~/.agents/skills/)
-    if (!agentConfig.nativeAgentsSkillsDir) {
-        const centralSkills = getSkillsDir();
-        const skillsTarget = path.join(agentDir, 'skills');
-        const skillsStatus = getSymlinkStatus(skillsTarget);
-        if (skillsStatus === 'none' && fs.existsSync(centralSkills)) {
-            const dirs = fs.readdirSync(centralSkills).filter(f => {
-                const stat = fs.statSync(path.join(centralSkills, f));
-                return stat.isDirectory() && !f.startsWith('.');
-            });
-            diff.skills.added = dirs;
-        }
-        else if (skillsStatus === 'dangling') {
-            diff.skills.dangling = ['skills/'];
-        }
-    }
-    // Hooks: check directory symlink (if agent supports hooks)
-    if (agentConfig.supportsHooks) {
-        const centralHooks = getHooksDir();
-        const hooksTarget = path.join(agentDir, 'hooks');
-        const hooksStatus = getSymlinkStatus(hooksTarget);
-        if (hooksStatus === 'none' && fs.existsSync(centralHooks)) {
-            const files = fs.readdirSync(centralHooks).filter(f => !f.startsWith('.'));
-            diff.hooks.added = files;
-        }
-        else if (hooksStatus === 'dangling') {
-            diff.hooks.dangling = ['hooks/'];
-        }
-    }
-    // Rules: check individual file symlinks
-    const systemRulesDir = getResolvedRulesDir();
-    if (fs.existsSync(systemRulesDir)) {
-        const ruleFiles = fs.readdirSync(systemRulesDir).filter(f => f.endsWith('.md') && f !== RULES_DOC_FILENAME);
-        for (const file of ruleFiles) {
-            const targetName = file === 'AGENTS.md' ? agentConfig.instructionsFile : file;
-            const targetPath = path.join(agentDir, targetName);
-            const status = getSymlinkStatus(targetPath);
-            if (status === 'none') {
-                diff.memory.added.push(file);
-            }
-            else if (status === 'dangling') {
-                diff.memory.dangling.push(targetName);
-            }
-        }
-    }
-    // Calculate totals
-    diff.totalAdded = diff.commands.added.length + diff.skills.added.length +
-        diff.hooks.added.length + diff.memory.added.length;
-    diff.totalDangling = diff.commands.dangling.length + diff.skills.dangling.length +
-        diff.hooks.dangling.length + diff.memory.dangling.length;
-    return diff;
-}
 /**
  * Enumerate the DotAgent repo names that resources can be scoped to:
  * the fixed `project` / `user` / `system` layers plus every enabled extra

package/dist/lib/warn-unpushed.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Whether a just-finished run should be checked for stranded work: only
+ * writable modes can leave commits (plan is read-only), and only non-interactive
+ * runs need the warning (an interactive user sees their own shell). Centralizes
+ * the gate so every exit path in the run command applies it identically.
+ */
+export declare function shouldWarnUnpushed(mode: string, interactive: boolean): boolean;
+export interface UnpushedState {
+    /** cwd is inside a git work tree. */
+    isRepo: boolean;
+    /** current branch, or null when detached / not a repo. */
+    branch: string | null;
+    /** the branch has an upstream tracking ref configured. */
+    hasUpstream: boolean;
+    /** commits reachable from HEAD but not from any remote-tracking ref. */
+    unpushed: {
+        sha: string;
+        subject: string;
+    }[];
+}
+/**
+ * Inspect `cwd` for commits on the current branch that have not reached any
+ * remote. Uses `git log --not --remotes` so it is correct even when the branch
+ * has no upstream set: commits already present on some `origin/*` ref are NOT
+ * reported (no false positive), and a never-pushed branch reports all its
+ * commits. Returns an inert result — never throws — for a non-repo cwd, a
+ * detached HEAD, or a repo with no remotes (nothing to push to).
+ */
+export declare function getUnpushedState(cwd: string): Promise<UnpushedState>;
+/**
+ * Render the warning for an unpushed state, or null when there is nothing to
+ * warn about. Split out from the printer so it is directly testable.
+ */
+export declare function formatUnpushedWarning(state: UnpushedState, cwd: string): string | null;
+/**
+ * If the just-finished run left committed-but-unpushed work in `cwd`, print a
+ * loud stderr warning with the exact push / PR commands. Non-fatal by contract:
+ * any failure is swallowed so it can never break a run's exit path.
+ */
+export declare function warnUnpushedWork(cwd: string): Promise<void>;