@phnx-labs/agents-cli 1.22.38 → 1.22.40

package/dist/lib/fleet/manifest.js

@@ -34,10 +34,16 @@ function validateDefaults(v, where) {
     if (o.sync !== undefined && !isStringArray(o.sync)) {
         throw new Error(`fleet: ${where}.sync must be a list of scope names (e.g. [user]).`);
     }
+    if (o.config !== undefined && (typeof o.config !== 'object' || o.config === null || Array.isArray(o.config))) {
+        throw new Error(`fleet: ${where}.config must be a mapping of config keys to values.`);
+    }
     return {
         agents: o.agents,
         sync: o.sync,
         login: validateLogin(o.login, where),
+        // `config:` is operator config (`agents devices config`); inert to the
+        // reconcile engine but part of the manifest shape.
+        config: o.config,
     };
 }
 /** Validate a raw `fleet:` object (already YAML-parsed) into a typed manifest. */
@@ -58,17 +64,10 @@ export function parseFleetManifest(raw) {
         const map = {};
         for (const [name, ov] of Object.entries(o.devices)) {
             // An empty entry (`device: {}`) inherits defaults — represent as {}.
-            const merged = ov == null ? {} : validateDefaults(ov, `devices.${name}`);
-            // `config:` is the operator-config block (`agents devices config`) —
-            // inert to the reconcile engine but part of the manifest shape.
-            const cfg = ov != null ? ov.config : undefined;
-            if (cfg !== undefined) {
-                if (typeof cfg !== 'object' || cfg === null || Array.isArray(cfg)) {
-                    throw new Error(`fleet: devices.${name}.config must be a mapping of config keys to values.`);
-                }
-                merged.config = cfg;
-            }
-            map[name] = merged;
+            // (A per-device `config:` here is the LEGACY #2458 store — parsed through
+            // so reads stay lossless, folded into the per-device doc by the config
+            // migration, never written by current code.)
+            map[name] = ov == null ? {} : validateDefaults(ov, `devices.${name}`);
         }
         devices = map;
     }
@@ -76,6 +75,19 @@ export function parseFleetManifest(raw) {
         throw new Error(`fleet: devices must be the string 'all' or a mapping of device -> overrides (got ${JSON.stringify(o.devices)}).`);
     }
     const manifest = { defaults, devices };
+    if (o.discovery !== undefined) {
+        if (typeof o.discovery !== 'object' || o.discovery === null || Array.isArray(o.discovery)) {
+            throw new Error('fleet: discovery must be a mapping of device name to approved or ignored.');
+        }
+        const discovery = {};
+        for (const [name, status] of Object.entries(o.discovery)) {
+            if (status !== 'approved' && status !== 'ignored') {
+                throw new Error(`fleet: discovery.${name} must be approved or ignored.`);
+            }
+            discovery[name] = status;
+        }
+        manifest.discovery = discovery;
+    }
     // Additive, backward-compatible extras (captured by `agents fleet capture`).
     if (o.secrets !== undefined) {
         if (typeof o.secrets !== 'object' || o.secrets === null || Array.isArray(o.secrets)) {

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

@@ -27,6 +27,14 @@ export interface FleetDefaults {
     sync?: string[];
     /** Login propagation strategy. Default `'sync'`. */
     login?: FleetLoginMode;
+    /**
+     * Fleet-wide config defaults (`agents devices config --fleet <key> <value>`)
+     * — the middle layer of the device-config store: built-in default <
+     * `fleet.defaults.config` < per-device `devices/<name>/agents.yaml`
+     * `config:`. Inert to the reconcile engine (apply never pushes it; it takes
+     * effect through the config read path). Names and non-secret values only.
+     */
+    config?: Record<string, unknown>;
 }
 /** Per-device override; any omitted field inherits from `defaults`. */
 export interface FleetDeviceOverride {
@@ -34,12 +42,10 @@ export interface FleetDeviceOverride {
     sync?: string[];
     login?: FleetLoginMode;
     /**
-     * Operator config for this device, written by `agents devices config <name>`
-     * — the device-scope keys of the `lib/device-config.ts` registry (maxAgents,
-     * schedulerEnabled, ssh*, autoLaunch*, notes, …). This is the ONE store for
-     * per-device settings: central, synced, and backed up with agents.yaml.
-     * LEAK-FREE like the rest of the manifest — names and non-secret values only
-     * (a secrets-bundle NAME is fine; a credential value never is).
+     * LEGACY home of per-device operator config (#2458); the current store is the
+     * per-device doc `devices/<name>/agents.yaml` `config:` block. Existing
+     * values are folded into the device doc by lib/devices/config-migration.ts
+     * and stripped here — current code never writes this field.
      */
     config?: Record<string, unknown>;
 }
@@ -68,6 +74,12 @@ export interface FleetManifest {
     };
     /** Routine NAMES that should be active on the fleet (files sync via the repo). */
     routines?: string[];
+    /**
+     * Portable user decisions for Tailscale discovery. A name maps to `approved`
+     * or `ignored`; absence means pending. Connection metadata remains in each
+     * machine's local device registry and is never committed.
+     */
+    discovery?: Record<string, 'approved' | 'ignored'>;
 }
 /**
  * A device's desired state after merging defaults with its override and
@@ -118,7 +130,7 @@ export interface DeviceProbe {
     note?: string;
 }
 /** One planned action against a device, in a single reconcile dimension. */
-export type FleetActionKind = 'install-cli' | 'upgrade-cli' | 'add-agent' | 'sync-config' | 'push-login' | 'needs-login'
+export type FleetActionKind = 'install-cli' | 'upgrade-cli' | 'add-agent' | 'sync-config' | 'needs-login'
 /** Push a declared secrets bundle to the device over SSH. Opt-in only
  * (`--provision-secrets`) and gated on a pinned host key, because this moves
  * credential VALUES to another machine (RUSH-1968). */

package/dist/lib/fleet-cache.d.ts

@@ -12,7 +12,7 @@
  * `runFleetStatusPublish` for the fleet-status mirror); this module is the read
  * side only.
  */
-import { type UsageSnapshot } from './usage.js';
+import { type UsageSnapshot } from './accounting/usage.js';
 import { type FleetStatusRow } from './fleet-status.js';
 /**
  * The fleet-status union the daemon publishes (own row) and the fleet-status

package/dist/lib/fleet-cache.js

@@ -12,7 +12,7 @@
  * `runFleetStatusPublish` for the fleet-status mirror); this module is the read
  * side only.
  */
-import { readClaudeUsageCache } from './usage.js';
+import { readClaudeUsageCache } from './accounting/usage.js';
 import { readHeadroomEntry } from './usage-refresh.js';
 import { readFleetStatus as readFleetStatusMirror } from './fleet-status.js';
 /**

package/dist/lib/format.d.ts

@@ -50,6 +50,25 @@ export declare function truncate(s: string, max: number): string;
 export declare function relTime(iso: string): string;
 /** Format a millisecond duration as "45s", "3m", "2h 5m", "1d 3h". */
 export declare function humanDuration(ms: number): string;
+/**
+ * Human-readable byte size. Previously copy-pasted into five files
+ * (`commands/prune.ts`, `commands/share.ts`, `commands/inspect.ts`,
+ * `commands/sessions.ts`, `lib/browser/sessions-list.ts`) — this is the
+ * canonical home.
+ */
+export declare function formatBytes(n: number): string;
+/**
+ * True when an error came from the user cancelling a prompt (Ctrl+C).
+ *
+ * Lives here rather than in `commands/utils.ts` so `lib/` callers
+ * (`drift-sync.ts`, `refresh.ts`) don't have to import upward out of `lib/`
+ * into the command layer. `commands/utils.ts` re-exports it.
+ */
+export declare function isPromptCancelled(err: unknown): boolean;
+/** True when stdin/stdout are attached to a real terminal. */
+export declare function isInteractiveTerminal(): boolean;
+/** Parse a comma-separated CLI list, trimming whitespace and dropping empties. */
+export declare function parseCommaSeparatedList(value: string | undefined): string[];
 /**
  * Visible column width of `s`, ignoring ANSI SGR color codes (e.g. chalk
  * wrappers). Matches the full CSI sequence including the `\x1b` escape.

package/dist/lib/format.js

@@ -9,7 +9,7 @@
  */
 import chalk from 'chalk';
 import { readSync } from 'node:fs';
-import { emitFriction } from './events.js';
+import { emitFriction } from './feed/events.js';
 /**
  * Render a fatal error to the right stream. Pure — no I/O, no `process.exit` — so
  * the human-vs-agent split is unit-testable. A `--json` caller gets
@@ -97,6 +97,49 @@ export function humanDuration(ms) {
     const hh = h % 24;
     return hh ? `${d}d ${hh}h` : `${d}d`;
 }
+/**
+ * Human-readable byte size. Previously copy-pasted into five files
+ * (`commands/prune.ts`, `commands/share.ts`, `commands/inspect.ts`,
+ * `commands/sessions.ts`, `lib/browser/sessions-list.ts`) — this is the
+ * canonical home.
+ */
+export function formatBytes(n) {
+    if (n < 1024)
+        return `${n} B`;
+    const units = ['KB', 'MB', 'GB', 'TB'];
+    let size = n / 1024;
+    let unit = 0;
+    while (size >= 1024 && unit < units.length - 1) {
+        size /= 1024;
+        unit++;
+    }
+    return `${size < 10 ? size.toFixed(1) : Math.round(size)} ${units[unit]}`;
+}
+/**
+ * True when an error came from the user cancelling a prompt (Ctrl+C).
+ *
+ * Lives here rather than in `commands/utils.ts` so `lib/` callers
+ * (`drift-sync.ts`, `refresh.ts`) don't have to import upward out of `lib/`
+ * into the command layer. `commands/utils.ts` re-exports it.
+ */
+export function isPromptCancelled(err) {
+    return err instanceof Error && (err.name === 'ExitPromptError' ||
+        err.message.includes('force closed') ||
+        err.message.includes('User force closed'));
+}
+/** True when stdin/stdout are attached to a real terminal. */
+export function isInteractiveTerminal() {
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+/** Parse a comma-separated CLI list, trimming whitespace and dropping empties. */
+export function parseCommaSeparatedList(value) {
+    if (!value)
+        return [];
+    return value
+        .split(',')
+        .map((item) => item.trim())
+        .filter(Boolean);
+}
 /**
  * Visible column width of `s`, ignoring ANSI SGR color codes (e.g. chalk
  * wrappers). Matches the full CSI sequence including the `\x1b` escape.

package/dist/lib/friction-heuristics.d.ts

@@ -6,7 +6,7 @@
  * yet. This is a starting point: one detector for the most actionable pattern,
  * an agent stuck retrying the SAME denied action instead of adapting.
  */
-import type { EventRecord } from './events.js';
+import type { EventRecord } from './feed/events.js';
 export interface RepeatedGuardBlockFinding {
     /** Session id the repeated blocks happened in, or 'unknown' when the
      *  friction event carried no session (e.g. a guard fired outside any

package/dist/lib/git.d.ts

@@ -207,6 +207,10 @@ export declare function isGitRepo(dir: string): boolean;
  * Shells out to `git rev-parse --show-toplevel`, so it resolves correctly from
  * any subdirectory and for linked worktrees (unlike the root-only, synchronous
  * {@link isGitRepo} above). Throws if `dir` is not inside a git repository.
+ *
+ * Git prints POSIX separators even on Windows (`C:/Users/...`); we fold them to
+ * the native separator so the result is a real filesystem path that compares
+ * equal to one built with `path.*`. On POSIX this is a no-op.
  */
 export declare function getGitRoot(dir: string): Promise<string>;
 /**
@@ -216,6 +220,10 @@ export declare function getGitRoot(dir: string): Promise<string>;
  * worktree: `--show-toplevel` there returns the worktree's own path, but the
  * common git dir (`--git-common-dir`) always points at the primary repo's
  * `.git`, whose parent is the main checkout. Throws if `dir` is not in a repo.
+ *
+ * Git prints POSIX separators even on Windows (`C:/Users/...`); we fold them to
+ * the native separator so the result is a real filesystem path that compares
+ * equal to one built with `path.*`. On POSIX this is a no-op.
  */
 export declare function getMainRepoRoot(dir: string): Promise<string>;
 /**
@@ -281,7 +289,22 @@ export declare function displayHomePath(dir: string): string;
  *   3. Genuinely diverged (local commits not on tracking) → `rebase` onto the
  *      tracking ref (same outcome as {@link syncRepoGit}, without a second pull).
  */
-export declare function pullRepo(dir: string): Promise<{
+export interface PullRepoOptions {
+    /**
+     * `'default-branch-fast-forward'` — strict mode for `projects pull`:
+     *   - Blocks immediately if the tree is dirty (no remote read needed).
+     *   - Fetches origin, resolves the remote default branch, and refuses if the
+     *     current branch is not the remote default.
+     *   - Refuses if HEAD is ahead of the upstream (local commits not on remote).
+     *   - Fast-forwards only (`merge --ff-only`). NEVER rebases.
+     *   - NEVER installs git hook symlinks (read-only model path).
+     *
+     * `'preserve-local'` (default) — the existing behavior: tolerates dirty trees
+     * when the incoming diff does not collide, and rebases a diverged branch.
+     */
+    mode?: 'preserve-local' | 'default-branch-fast-forward';
+}
+export declare function pullRepo(dir: string, options?: PullRepoOptions): Promise<{
     success: boolean;
     commit: string;
     error?: string;

package/dist/lib/git.js

@@ -10,7 +10,7 @@ import { execFileSync } from 'node:child_process';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import { IS_WINDOWS, isWindowsAbsolutePath } from './platform/index.js';
+import { IS_WINDOWS, isWindowsAbsolutePath, toNativePath } from './platform/index.js';
 import { getPackageLocalPath } from './state.js';
 import { DEFAULT_SYSTEM_REPO, systemRepoSlug } from './types.js';
 /**
@@ -658,10 +658,14 @@ export function isGitRepo(dir) {
  * Shells out to `git rev-parse --show-toplevel`, so it resolves correctly from
  * any subdirectory and for linked worktrees (unlike the root-only, synchronous
  * {@link isGitRepo} above). Throws if `dir` is not inside a git repository.
+ *
+ * Git prints POSIX separators even on Windows (`C:/Users/...`); we fold them to
+ * the native separator so the result is a real filesystem path that compares
+ * equal to one built with `path.*`. On POSIX this is a no-op.
  */
 export async function getGitRoot(dir) {
     const root = await simpleGit(dir).revparse(['--show-toplevel']);
-    return root.trim();
+    return toNativePath(root.trim());
 }
 /**
  * Return the absolute path to the **main** working-tree root for `dir`.
@@ -670,10 +674,14 @@ export async function getGitRoot(dir) {
  * worktree: `--show-toplevel` there returns the worktree's own path, but the
  * common git dir (`--git-common-dir`) always points at the primary repo's
  * `.git`, whose parent is the main checkout. Throws if `dir` is not in a repo.
+ *
+ * Git prints POSIX separators even on Windows (`C:/Users/...`); we fold them to
+ * the native separator so the result is a real filesystem path that compares
+ * equal to one built with `path.*`. On POSIX this is a no-op.
  */
 export async function getMainRepoRoot(dir) {
     const common = await simpleGit(dir).raw(['rev-parse', '--path-format=absolute', '--git-common-dir']);
-    return path.dirname(common.trim());
+    return toNativePath(path.dirname(common.trim()));
 }
 /**
  * Initialize a git repo in an existing directory.
@@ -863,23 +871,8 @@ export function displayHomePath(dir) {
     const rel = dir.startsWith(home) ? '~' + dir.slice(home.length) : dir;
     return rel.replace(/\\/g, '/');
 }
-/**
- * Pull changes in an existing repo.
- * A dirty working tree no longer refuses outright: a fast-forward that touches
- * no uncommitted path still runs (see `dirtyTreeRefusal`). It refuses when the
- * branch has local commits to rebase, or when an incoming path is also dirty.
- *
- * Strategy (RUSH-2282):
- *   1. Fetch, then compare HEAD to the resolved tracking ref.
- *   2. Clean behind-only (HEAD is an ancestor of tracking) → `merge --ff-only`
- *      against the tracking ref. Never re-enter `git pull` after a bare fetch —
- *      multi-entry FETCH_HEAD (concurrent fetch, multi-branch remote) makes
- *      `git pull --rebase` die with "Cannot rebase onto multiple branches" even
- *      when the checkout is a pure fast-forward.
- *   3. Genuinely diverged (local commits not on tracking) → `rebase` onto the
- *      tracking ref (same outcome as {@link syncRepoGit}, without a second pull).
- */
-export async function pullRepo(dir) {
+export async function pullRepo(dir, options = {}) {
+    const strict = options.mode === 'default-branch-fast-forward';
     try {
         const git = simpleGit(dir);
         // A rebase left in progress by an earlier run must be reported as itself.
@@ -916,14 +909,24 @@ export async function pullRepo(dir) {
             };
         }
         const status = await git.status();
+        // Strict mode (projects pull): refuse a dirty tree immediately — no fetch
+        // needed to know the answer, and the caller must not risk touching staged
+        // or modified files with an incoming fast-forward.
+        const isDirty = !status.isClean();
+        if (strict && isDirty) {
+            return {
+                success: false,
+                commit: '',
+                error: `Blocked: dirty working tree. Commit or discard local changes before pulling.\n\n  cd ${displayHomePath(dir)} && git status`,
+            };
+        }
         // A dirty tree is not decided here: whether a fast-forward is safe depends
         // on what is actually incoming, and that needs a fetched upstream ref. The
         // gate therefore sits just before the integrate step below. The exception is
         // a repo with no remote at all — there is nothing to fast-forward from, so
         // the dirt is the whole answer and the resolution below would only fail
         // with a less useful message.
-        const isDirty = !status.isClean();
-        if (isDirty && (await git.getRemotes()).length === 0) {
+        if (!strict && isDirty && (await git.getRemotes()).length === 0) {
             return {
                 success: false,
                 commit: '',
@@ -931,13 +934,13 @@ export async function pullRepo(dir) {
             };
         }
         const branch = status.current || 'main';
-        // Resolve the upstream ref to fast-forward against. Prefer the local
-        // branch's tracking config; otherwise ask origin for its default branch.
+        // Resolve the upstream ref to fast-forward against.
+        // Strict mode: always fetch origin and resolve its default branch — then
+        // verify the current branch IS the remote default (refuse otherwise).
+        // Preserve-local mode: prefer the local branch's tracking config; only
+        // fetch when no tracking is set.
         let tracking = status.tracking;
-        if (!tracking) {
-            // No tracking config: fetch origin so its HEAD is known, then ask which
-            // branch it points at. This path only ever concerns origin — a branch with
-            // no upstream has no other remote to consult.
+        if (strict || !tracking) {
             try {
                 await git.fetch('origin');
                 await git.raw(['remote', 'set-head', 'origin', '--auto']);
@@ -948,6 +951,19 @@ export async function pullRepo(dir) {
                 tracking = `origin/${branch}`;
             }
         }
+        // Strict: the checkout must be on the remote default branch — never pull a
+        // feature branch across the fleet unattended.
+        if (strict) {
+            const sep = tracking.indexOf('/');
+            const expectedBranch = sep > 0 ? tracking.slice(sep + 1) : tracking;
+            if (branch !== expectedBranch) {
+                return {
+                    success: false,
+                    commit: '',
+                    error: `Blocked: HEAD is on "${branch}" but origin defaults to "${expectedBranch}". Switch to "${expectedBranch}" before pulling.`,
+                };
+            }
+        }
         // Split the remote-tracking ref (<remote>/<branch>) so callers/logs can name
         // the remote. Branch names may contain slashes, so split on the FIRST
         // separator only. The integrate step below uses `tracking` directly (not a
@@ -983,15 +999,32 @@ export async function pullRepo(dir) {
         // around that call would always report "can ff" (RUSH-2282).
         const aheadCount = parseInt((await git.raw(['rev-list', '--count', `${tracking}..HEAD`])).trim(), 10);
         const behindCount = parseInt((await git.raw(['rev-list', '--count', `HEAD..${tracking}`])).trim(), 10);
-        const canFastForward = Number.isFinite(aheadCount) &&
-            Number.isFinite(behindCount) &&
-            aheadCount === 0 &&
-            behindCount > 0;
-        // Dirty tree: same rule `syncRepoGit` applies, from the same function — a
-        // fast-forward that touches nothing the author is holding may proceed; a
-        // rebase or a colliding path may not. Refusing on any dirt at all is what
-        // used to strand merged changes on every box that had an unrelated edit.
-        if (isDirty) {
+        // Both counts are the ONLY inputs to the fast-forward decision, so a count
+        // we cannot read is a refusal, not a reason to guess. Fail here rather than
+        // downstream: an unreadable count used to fall through to the rebase arm in
+        // preserve-local mode, and to a "HEAD diverged" message in strict mode that
+        // named the wrong cause.
+        if (!Number.isFinite(aheadCount) || !Number.isFinite(behindCount)) {
+            return {
+                success: false,
+                commit: '',
+                error: `Could not read how far HEAD is from ${tracking} — 'git rev-list --count' returned no usable count. Check the checkout, then pull again:\n\n  cd ${displayHomePath(dir)} && git status`,
+            };
+        }
+        const canFastForward = aheadCount === 0 && behindCount > 0;
+        // Strict: block if HEAD has local commits not on the remote — fast-forward
+        // requires the local tip to be an ancestor of the remote tip.
+        if (strict && aheadCount > 0) {
+            return {
+                success: false,
+                commit: '',
+                error: `Blocked: HEAD is ${aheadCount} commit${aheadCount === 1 ? '' : 's'} ahead of ${tracking}. Push or discard local commits before pulling.`,
+            };
+        }
+        // Dirty tree (preserve-local only): same rule `syncRepoGit` applies —
+        // a fast-forward that touches nothing the author is holding may proceed; a
+        // rebase or a colliding path may not. Strict mode already refused above.
+        if (!strict && isDirty) {
             const refusal = await dirtyTreeRefusal(git, status, tracking);
             if (refusal) {
                 return {
@@ -1010,6 +1043,14 @@ export async function pullRepo(dir) {
                 // Diverged (or local-only commits). Rebase onto the tracking tip —
                 // same outcome as `git pull --rebase <remote> <branch>` without
                 // re-fetching or consulting FETCH_HEAD.
+                //
+                // PRESERVE-LOCAL ONLY — strict mode can never reach this arm, so the
+                // fleet pull never rewrites history. Strict has already returned for
+                // every case that leaves `canFastForward` false: an identical local and
+                // remote ref, `aheadCount > 0` (which is also what "diverged" means),
+                // and a count that would not parse. That leaves `aheadCount === 0` with
+                // a differing ref, i.e. `behindCount > 0` — a fast-forward. Keep those
+                // three returns above intact if you change this.
                 await git.raw(['rebase', tracking]);
             }
         }
@@ -1028,7 +1069,10 @@ export async function pullRepo(dir) {
                 error: `${verb} onto ${tracking} failed — the pull was rolled back, nothing changed.\n\nResolve the divergence, then pull again:\n\n  cd ${displayHomePath(dir)} && git log --oneline HEAD...${tracking}\n\n${err.message}`,
             };
         }
-        installGithooksSymlinks(dir);
+        // Strict mode never installs git hook symlinks — the command is a read-model
+        // operation (update pointers only; never reconfigure the checkout).
+        if (!strict)
+            installGithooksSymlinks(dir);
         const log = await git.log({ maxCount: 1 });
         return {
             success: true,

package/dist/lib/heal.js

@@ -23,10 +23,10 @@
  * `agents prune cleanup`, so a heal pass can never lose work.
  */
 import { ALL_AGENT_IDS } from './agents.js';
-import { syncResourcesToVersion, listInstalledVersions, isVersionIsolated, getVersionHomePath, getActuallySyncedResources, compareVersions, } from './versions.js';
+import { syncResourcesToVersion, listInstalledVersions, isVersionIsolated, getVersionHomePath, getActuallySyncedResources, compareVersions, } from './installations/versions.js';
 import { diffVersionResources, } from './doctor-diff.js';
-import { discoverPlugins, updatePlugin, readPluginSourceInfo, getUpstreamManifestVersion, } from './plugins.js';
-import { repairPluginManifestFile } from './plugin-marketplace.js';
+import { discoverPlugins, updatePlugin, readPluginSourceInfo, getUpstreamManifestVersion, } from './plugins/plugins.js';
+import { repairPluginManifestFile } from './plugins/plugin-marketplace.js';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';

package/dist/lib/hooks.d.ts

@@ -386,3 +386,21 @@ export declare function registerHooksToSettings(agentId: AgentId, versionHome: s
  * entries removed.
  */
 export declare function pruneVersionHomeHookEntriesFromSettings(settingsPath: string, agent: AgentId, removedVersion: string): number;
+export interface InstallSessionTrackerHookResult {
+    installed: boolean;
+    error?: string;
+}
+/**
+ * Install the shared SessionStart state-writer hook (`packages/session-tracker`)
+ * into the harness's native config. Gated by `supports(agent, 'hooks', version)`;
+ * unsupported agents return `installed: false` with a reason instead of throwing.
+ *
+ * This is the bridge that makes bare `claude` / `codex` / `kimi` launches write
+ * `~/.agents/.cache/terminals/sessions/<pid>.json`, not just `agents run` launches.
+ */
+export declare function installSessionTrackerHook(agent: AgentId, version?: string, home?: string): Promise<InstallSessionTrackerHookResult>;
+/**
+ * Synchronous variant for callers that cannot be made async (e.g.
+ * `syncResourcesToVersion`). Best-effort: failures are returned, not thrown.
+ */
+export declare function installSessionTrackerHookSync(agent: AgentId, version?: string, home?: string): InstallSessionTrackerHookResult;

package/dist/lib/hooks.js

@@ -13,6 +13,9 @@ import * as os from 'os';
 import * as path from 'path';
 import * as yaml from 'yaml';
 import * as TOML from 'smol-toml';
+import { execFile, execFileSync } from 'child_process';
+import { promisify } from 'util';
+import { fileURLToPath } from 'url';
 import { AGENTS, agentConfigDirName, isAgentHardDeprecated } from './agents.js';
 import { supports, explainSkip, capableAgents } from './capabilities.js';
 import { getHooksDir as getSystemHooksDir, getUserHooksDir, getUserAgentsDir, getSystemAgentsDir, getProjectAgentsDir, getTrashHooksDir, getEnabledExtraRepos, getResolvedRulesDir, getUserRulesDir, getPerfDir } from './state.js';
@@ -264,7 +267,7 @@ function collapseVersionHookEntries(entries, activeVersionHome) {
         return true;
     });
 }
-import { getEffectiveHome, getGlobalDefault, getVersionHomePath, isVersionIsolated, listInstalledVersions, resolveVersion, } from './versions.js';
+import { getEffectiveHome, getGlobalDefault, getVersionHomePath, isVersionIsolated, listInstalledVersions, resolveVersion, } from './installations/versions.js';
 import { generateHookShim, getHookShimPath, isValidHookShimName, parseCacheConfig, removeHookShim } from './hooks/cache.js';
 import { getHookShimsDir } from './state.js';
 function hookContentHash(scriptPath) {
@@ -3244,3 +3247,112 @@ function registerHooksForHermes(versionHome, manifest, resolveScript, managedPre
     }
     return { registered, errors };
 }
+const execFileAsync = promisify(execFile);
+function resolveSessionTrackerRoot() {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    // Built/installed layout: dist/lib/ -> dist/session-tracker
+    const built = path.resolve(here, '..', 'session-tracker');
+    if (fs.existsSync(path.join(built, 'dist', 'hook.sh'))) {
+        return built;
+    }
+    // Source layout: apps/cli/src/lib/ -> repo root -> packages/session-tracker
+    const source = path.resolve(here, '..', '..', '..', '..', 'packages', 'session-tracker');
+    if (fs.existsSync(path.join(source, 'src', 'hook.sh'))) {
+        return source;
+    }
+    return null;
+}
+function resolveTsxLoader(trackerRoot) {
+    const loader = path.join(trackerRoot, 'node_modules', 'tsx', 'dist', 'cli.mjs');
+    if (fs.existsSync(loader))
+        return loader;
+    return null;
+}
+function buildInstallHookInvocation(trackerRoot, agent) {
+    const distScript = path.join(trackerRoot, 'dist', 'install-hook.js');
+    if (fs.existsSync(distScript)) {
+        return { command: process.execPath, args: [distScript, agent] };
+    }
+    const loader = resolveTsxLoader(trackerRoot);
+    if (!loader)
+        return null;
+    return {
+        command: process.execPath,
+        args: [loader, path.join(trackerRoot, 'src', 'install-hook.ts'), agent],
+    };
+}
+/**
+ * Install the shared SessionStart state-writer hook (`packages/session-tracker`)
+ * into the harness's native config. Gated by `supports(agent, 'hooks', version)`;
+ * unsupported agents return `installed: false` with a reason instead of throwing.
+ *
+ * This is the bridge that makes bare `claude` / `codex` / `kimi` launches write
+ * `~/.agents/.cache/terminals/sessions/<pid>.json`, not just `agents run` launches.
+ */
+export async function installSessionTrackerHook(agent, version, home) {
+    const gate = supports(agent, 'hooks', version);
+    if (!gate.ok) {
+        return { installed: false, error: explainSkip(agent, 'hooks', gate, version) };
+    }
+    const trackerRoot = resolveSessionTrackerRoot();
+    if (!trackerRoot) {
+        return { installed: false, error: 'session-tracker package not found' };
+    }
+    const invocation = buildInstallHookInvocation(trackerRoot, agent);
+    if (!invocation) {
+        return { installed: false, error: 'session-tracker not built and tsx is unavailable' };
+    }
+    try {
+        await execFileAsync(invocation.command, invocation.args, {
+            env: { ...process.env, HOME: home ?? process.env.HOME },
+            encoding: 'utf8',
+        });
+        return { installed: true };
+    }
+    catch (err) {
+        return { installed: false, error: installFailureMessage(err) };
+    }
+}
+/**
+ * The child reports its refusal reason on stdout (its HOOK_SUPPORT table), not
+ * stderr — and a Buffer-typed empty stderr is truthy, so a bare `err.stderr ??
+ * err.message` surfaced an empty string. Prefer the first NON-EMPTY stream.
+ */
+function installFailureMessage(err) {
+    const e = err;
+    for (const stream of [e.stderr, e.stdout]) {
+        const text = stream == null ? '' : String(stream).trim();
+        if (text.length > 0)
+            return text;
+    }
+    return e.message;
+}
+/**
+ * Synchronous variant for callers that cannot be made async (e.g.
+ * `syncResourcesToVersion`). Best-effort: failures are returned, not thrown.
+ */
+export function installSessionTrackerHookSync(agent, version, home) {
+    const gate = supports(agent, 'hooks', version);
+    if (!gate.ok) {
+        return { installed: false, error: explainSkip(agent, 'hooks', gate, version) };
+    }
+    const trackerRoot = resolveSessionTrackerRoot();
+    if (!trackerRoot) {
+        return { installed: false, error: 'session-tracker package not found' };
+    }
+    const invocation = buildInstallHookInvocation(trackerRoot, agent);
+    if (!invocation) {
+        return { installed: false, error: 'session-tracker not built and tsx is unavailable' };
+    }
+    try {
+        execFileSync(invocation.command, invocation.args, {
+            env: { ...process.env, HOME: home ?? process.env.HOME },
+            stdio: ['ignore', 'pipe', 'pipe'],
+            encoding: 'utf8',
+        });
+        return { installed: true };
+    }
+    catch (err) {
+        return { installed: false, error: installFailureMessage(err) };
+    }
+}