@phnx-labs/agents-cli 1.22.38 → 1.22.40

package/dist/lib/{migrate.js → installations/migrate.js}

@@ -8,19 +8,24 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import * as yaml from 'yaml';
-import { stringifyDoc } from './yaml-io.js';
+import { stringifyDoc } from '../yaml-io.js';
 import { execSync } from 'child_process';
-import { atomicWriteFileSync } from './fs-atomic.js';
-import { machineId } from './machine-id.js';
-import { AGENTS, agentConfigDirName, findInPath } from './agents.js';
-import { createLink } from './platform/index.js';
-import { foldLegacySystemRepo, copyDirSkipExisting } from './migrate-fold.js';
-export { foldLegacySystemRepo } from './migrate-fold.js';
-import { migrateLegacyRoutineActivation, listJobs, validateJob } from './routines.js';
-import { setConfigValue } from './device-config.js';
-import { enabledRoutineNames, replaceEnabledRoutines } from './routine-activation.js';
-import { evaluateActivationReadiness } from './routine-readiness.js';
-import { migrateDeviceConfigToCentral } from './devices/config-migration.js';
+import { atomicWriteFileSync } from '../fs-atomic.js';
+import { machineId } from '../machine-id.js';
+import { AGENTS, agentConfigDirName, findInPath } from '../agents.js';
+import { createLink } from '../platform/index.js';
+import { foldLegacySystemRepo, copyDirSkipExisting } from '../migrate-fold.js';
+export { foldLegacySystemRepo } from '../migrate-fold.js';
+import { migrateLegacyRoutineActivation, listJobs, validateJob } from '../scheduling/routines.js';
+import { setConfigValue } from '../device-config.js';
+import { enabledRoutineNames, replaceEnabledRoutines } from '../routine-activation.js';
+import { evaluateActivationReadiness } from '../routine-readiness.js';
+import { migrateDeviceConfigStores } from '../devices/config-migration.js';
+// Two constants only, never the read/write API — migrations still operate on raw
+// YAML so they never take the meta lock or prime the meta cache mid-migration.
+import { DEFAULT_BROWSER_PROFILE_NAME } from '../browser/profiles.js';
+import { META_HEADER as DEVICE_META_HEADER } from '../state.js';
+import { COMPILED_HEADER_PROJECT } from '../rules/compile.js';
 const HOME = process.env.HOME ?? os.homedir();
 const USER_DIR = path.join(HOME, '.agents');
 /** Canonical system-repo location (post-fold). */
@@ -640,11 +645,28 @@ function migratePermissionSetsToPresets() {
  * switching is owned by `agents use`, not the migrator.
  */
 function repairAgentConfigSymlinks() {
-    // Version pins live in the per-device file post-split (~/.agents/devices/<machine>/
-    // agents.yaml); central agents.yaml may still carry them mid-transition. Read
-    // device first (authoritative), then central, first-seen-agent wins.
+    // Version pins live in the machine-local pins JSON (~/.agents/.history/
+    // devices/pins-<machine>.json); the tracked device doc and central
+    // agents.yaml may still carry them mid-transition. Read pins first
+    // (authoritative), then the legacy locations, first-seen-agent wins.
     const defaults = [];
-    const collectPins = (file) => {
+    const seen = new Set();
+    const collectJsonPins = (file) => {
+        let pins;
+        try {
+            pins = JSON.parse(fs.readFileSync(file, 'utf-8'));
+        }
+        catch {
+            return;
+        }
+        for (const [agent, version] of Object.entries(pins?.agents ?? {})) {
+            if (!seen.has(agent)) {
+                seen.add(agent);
+                defaults.push({ agent, version });
+            }
+        }
+    };
+    const collectYamlPins = (file) => {
         let text;
         try {
             text = fs.readFileSync(file, 'utf-8');
@@ -657,12 +679,15 @@ function repairAgentConfigSymlinks() {
             return;
         for (const line of block[1].split('\n')) {
             const m = line.match(/^\s+([a-z][a-z0-9_-]*):\s*([^\s#]+)/);
-            if (m && !defaults.some((d) => d.agent === m[1]))
+            if (m && !seen.has(m[1])) {
+                seen.add(m[1]);
                 defaults.push({ agent: m[1], version: m[2] });
+            }
         }
     };
-    collectPins(path.join(USER_DIR, 'devices', machineId(), 'agents.yaml'));
-    collectPins(path.join(USER_DIR, 'agents.yaml'));
+    collectJsonPins(path.join(USER_DIR, '.history', 'devices', `pins-${machineId()}.json`));
+    collectYamlPins(path.join(USER_DIR, 'devices', machineId(), 'agents.yaml'));
+    collectYamlPins(path.join(USER_DIR, 'agents.yaml'));
     if (defaults.length === 0)
         return;
     let repaired = 0;
@@ -1127,7 +1152,7 @@ async function mergeSqliteDb(src, dest) {
     // every user table. Dynamic import keeps the sqlite shim off the hot path
     // for CLI starts that don't actually need a merge.
     try {
-        const sqliteMod = (await import('./sqlite.js'));
+        const sqliteMod = (await import('../sqlite.js'));
         const Database = sqliteMod.default;
         const db = new Database(dest);
         try {
@@ -1624,8 +1649,8 @@ function migrateVersionResourcesToPatterns() {
 /**
  * Split the machine-local fields out of the committed central agents.yaml so it
  * becomes portable and syncs cleanly (no more skip-worktree band-aid):
- *   agents:   -> ~/.agents/devices/<machineId>/agents.yaml  (committed, per-device)
- *   versions: -> ~/.agents/.history/version-resources.json   (gitignored, machine-local)
+ *   agents:   -> ~/.agents/.history/devices/pins-<machineId>.json  (untracked, machine-local)
+ *   versions: -> ~/.agents/.history/version-resources.json         (gitignored, machine-local)
  * Then clear any externally-set skip-worktree bit. Idempotent: no-op once central
  * carries neither field. Operates on raw YAML (never through state.ts).
  */
@@ -1647,18 +1672,16 @@ function migrateSplitDeviceLocalMeta() {
     // Only rewrite central when it actually carries machine-local fields — a
     // machine whose agents.yaml is already portable-only is left untouched.
     if (hasLocal) {
-        // agents: -> per-device file (merge, existing device entries win).
+        // agents: -> machine-local pins JSON (merge, existing pins win).
         if (agents && Object.keys(agents).length > 0) {
-            const devicePath = path.join(USER_DIR, 'devices', machineId(), 'agents.yaml');
+            const pinsPath = path.join(USER_DIR, '.history', 'devices', `pins-${machineId()}.json`);
             let existing = {};
             try {
-                const dm = yaml.parse(fs.readFileSync(devicePath, 'utf-8'));
-                if (dm?.agents)
-                    existing = dm.agents;
+                existing = JSON.parse(fs.readFileSync(pinsPath, 'utf-8')) || {};
             }
             catch { /* absent */ }
-            fs.mkdirSync(path.dirname(devicePath), { recursive: true });
-            atomicWriteFileSync(devicePath, HEADER + yaml.stringify({ agents: { ...agents, ...existing } }));
+            fs.mkdirSync(path.dirname(pinsPath), { recursive: true });
+            atomicWriteFileSync(pinsPath, JSON.stringify({ ...existing, agents: { ...agents, ...existing.agents } }, null, 2) + '\n');
         }
         // versions: -> machine-local history JSON (merge, existing wins).
         if (versions && Object.keys(versions).length > 0) {
@@ -1672,7 +1695,7 @@ function migrateSplitDeviceLocalMeta() {
             atomicWriteFileSync(vrPath, JSON.stringify({ ...versions, ...existing }, null, 2) + '\n');
         }
         // Strip machine-local fields from central and rewrite (portable only) — after
-        // the device/history writes above, so a crash never loses data.
+        // the pins/history writes above, so a crash never loses data.
         delete meta.agents;
         delete meta.versions;
         atomicWriteFileSync(metaFile, HEADER + yaml.stringify(meta));
@@ -1685,8 +1708,105 @@ function migrateSplitDeviceLocalMeta() {
     }
     catch { /* not a git repo / bit not set */ }
     if (hasLocal) {
-        console.error('Split agents.yaml: agents: -> devices/, versions: -> .history/version-resources.json');
+        console.error('Split agents.yaml: agents: -> .history/devices/pins-*.json, versions: -> .history/version-resources.json');
+    }
+}
+/**
+ * Move the auto-detected `default` browser profile OUT of the committed central
+ * agents.yaml and into this machine's per-device file.
+ *
+ * `browser` is a CENTRAL key because named profiles a user creates are real fleet
+ * config, but the ONE `default` entry inside it is machine-local: its `binary` is
+ * an OS-specific path and its endpoint is a locally-chosen free port.
+ * `createProfile`/`updateProfile` already route that entry to `deviceBrowser`
+ * (`isMachineLocalProfile`, browser/profiles.ts) — but nothing ever removed the
+ * copy older versions had already written into the shared file, and
+ * `serializeCentral` cannot: it deletes whole KEYS that are device-scoped, and
+ * `browser` is not one.
+ *
+ * So the entry sat in the committed file and every box rewrote it with its own
+ * browser. Measured 2026-08-13, all three boxes on 1.22.38 (which HAS the writer
+ * fix) with an empty `deviceBrowser` and a machine-specific `default` in central:
+ *
+ *   zion         browser: chrome    binary: /Applications/Google Chrome.app/...
+ *   yosemite-s1  browser: brave     binary: /opt/brave.com/brave/brave
+ *   mark-1       (same shape)
+ *
+ * `agents repos pull user` refuses when an incoming change touches a locally
+ * modified path, so agents.yaml being permanently dirty wedged the fleet config
+ * sync outright — those boxes sat 5, 8 and 79 commits behind. (RUSH-2161)
+ *
+ * Idempotent: no-op once central carries no `default` entry. The device file is
+ * written FIRST so a crash between the two writes can never lose the profile,
+ * and an entry already in the device file wins (this machine's live value is
+ * newer than the stale central copy by construction).
+ *
+ * Central is edited through a `yaml.Document` rather than re-stringified, so the
+ * hand-written comments in the committed agents.yaml survive — a plain
+ * `yaml.stringify` would drop every one of them and rewrite the whole file,
+ * which is the same churn this migration exists to stop (see `serializeCentral`).
+ */
+export function migrateMachineLocalBrowserProfileOutOfCentral(userDir = USER_DIR, machine = machineId()) {
+    const metaFile = path.join(userDir, 'agents.yaml');
+    if (!fs.existsSync(metaFile))
+        return;
+    let doc;
+    try {
+        doc = yaml.parseDocument(fs.readFileSync(metaFile, 'utf-8'));
+    }
+    catch {
+        return;
     }
+    if (doc.errors.length > 0)
+        return;
+    const central = doc.toJSON() ?? {};
+    const browser = central.browser;
+    if (!browser || typeof browser !== 'object' || Array.isArray(browser))
+        return;
+    const entry = browser[DEFAULT_BROWSER_PROFILE_NAME];
+    if (entry === undefined)
+        return;
+    // Device file first — a crash before central is rewritten leaves a harmless
+    // duplicate, while the reverse order would drop the profile entirely.
+    const devicePath = path.join(userDir, 'devices', machine, 'agents.yaml');
+    let deviceDoc = {};
+    try {
+        deviceDoc = yaml.parse(fs.readFileSync(devicePath, 'utf-8')) || {};
+    }
+    catch { /* absent — first write */ }
+    const deviceBrowser = (deviceDoc.browser && typeof deviceDoc.browser === 'object' && !Array.isArray(deviceDoc.browser))
+        ? deviceDoc.browser
+        : {};
+    if (deviceBrowser[DEFAULT_BROWSER_PROFILE_NAME] === undefined) {
+        deviceBrowser[DEFAULT_BROWSER_PROFILE_NAME] = entry;
+        deviceDoc.browser = deviceBrowser;
+        fs.mkdirSync(path.dirname(devicePath), { recursive: true });
+        atomicWriteFileSync(devicePath, DEVICE_META_HEADER + yaml.stringify(deviceDoc));
+    }
+    // Then strip it from the synced file, dropping `browser:` entirely when the
+    // machine-local entry was its only member.
+    doc.deleteIn(['browser', DEFAULT_BROWSER_PROFILE_NAME]);
+    if (Object.keys(browser).length === 1) {
+        const itemsOf = () => (doc.contents?.items) ?? [];
+        const idx = itemsOf().findIndex((pair) => pair.key?.value === 'browser');
+        const orphaned = idx >= 0 ? itemsOf()[idx]?.key?.commentBefore ?? undefined : undefined;
+        doc.delete('browser');
+        if (orphaned) {
+            // Deleting shifted the following pair down into `idx`.
+            const next = itemsOf()[idx]?.key;
+            if (next)
+                next.commentBefore = next.commentBefore ? `${orphaned}\n${next.commentBefore}` : orphaned;
+            else
+                doc.commentBefore = orphaned;
+        }
+    }
+    // Everything cleared -> header only, never a bare `{}`. stringifyDoc emits a
+    // FLOW empty map for an empty root, and a later parseDocument inherits that
+    // flow and renders the whole rewritten file inline. serializeCentral guards
+    // the identical case (state.ts, `isEmpty ? META_HEADER : stringifyDoc(doc)`).
+    const remaining = Object.keys(doc.toJSON() ?? {}).length;
+    atomicWriteFileSync(metaFile, remaining === 0 ? DEVICE_META_HEADER : stringifyDoc(doc));
+    console.error(`Migrated agents.yaml: browser '${DEFAULT_BROWSER_PROFILE_NAME}' profile -> devices/${machine}/agents.yaml`);
 }
 /**
  * Rename the legacy `extras-extras/` plugin-marketplace dir to `agents-extras/`
@@ -2260,6 +2380,88 @@ export function migrateKimiSubagentsToMarkdown(versionsDir) {
         console.error(`Removed ${removed} pre-markdown Kimi subagent file(s); run 'agents sync kimi' to write the new format`);
     }
 }
+/**
+ * Remove the compiled "project" ruleset the compiler used to write into $HOME
+ * (RUSH-2725). `compileRulesForProject` treated any cwd with `.agents/rules`
+ * as a project — and the user layer at ~/.agents satisfies that test — so it
+ * wrote ~/AGENTS.md plus per-agent symlinks, and every session under $HOME
+ * then loaded the entire ruleset twice (global memory + "project" memory).
+ * The compiler now refuses reserved roots; this removes the artifact already
+ * on disk. Only files we provably own are touched: an AGENTS.md carrying the
+ * compiled-project header, symlinks pointing at it, and copy-fallback files
+ * (symlink-less filesystems) carrying the same header.
+ */
+export function removeHomeCompiledProjectRules(homeDir = HOME) {
+    const agentsPath = path.join(homeDir, 'AGENTS.md');
+    let agentsLstat;
+    try {
+        agentsLstat = fs.lstatSync(agentsPath);
+    }
+    catch {
+        return;
+    }
+    if (!agentsLstat.isFile())
+        return;
+    let content = '';
+    try {
+        content = fs.readFileSync(agentsPath, 'utf8');
+    }
+    catch {
+        return;
+    }
+    if (!content.startsWith(COMPILED_HEADER_PROJECT))
+        return;
+    const seen = new Set(['AGENTS.md']);
+    for (const agent of Object.values(AGENTS)) {
+        const fname = agent.instructionsFile;
+        if (seen.has(fname) || fname.includes('/') || fname.includes('\\'))
+            continue;
+        seen.add(fname);
+        const linkPath = path.join(homeDir, fname);
+        let lstat;
+        try {
+            lstat = fs.lstatSync(linkPath);
+        }
+        catch {
+            continue;
+        }
+        if (lstat.isSymbolicLink()) {
+            let target = '';
+            try {
+                target = fs.readlinkSync(linkPath);
+            }
+            catch {
+                continue;
+            }
+            if (target === 'AGENTS.md') {
+                try {
+                    fs.unlinkSync(linkPath);
+                }
+                catch { /* next run retries */ }
+            }
+        }
+        else if (lstat.isFile()) {
+            // Symlink-less filesystems got a copy of AGENTS.md instead — same header.
+            let copy = '';
+            try {
+                copy = fs.readFileSync(linkPath, 'utf8');
+            }
+            catch {
+                continue;
+            }
+            if (copy.startsWith(COMPILED_HEADER_PROJECT)) {
+                try {
+                    fs.unlinkSync(linkPath);
+                }
+                catch { /* next run retries */ }
+            }
+        }
+    }
+    try {
+        fs.unlinkSync(agentsPath);
+    }
+    catch { /* next run retries */ }
+}
 /** Run all idempotent migrations. Safe to call multiple times. */
 export async function runMigration() {
     // MUST run first: every other migrator reads SYSTEM_DIR (the new path).
@@ -2299,13 +2501,20 @@ export async function runMigration() {
     // agents.yaml. After migrateVersionResourcesToPatterns so versions: is already
     // in pattern form when it moves to the history file.
     migrateSplitDeviceLocalMeta();
-    // Fold per-device operator config (device-doc config:/defaultBrowserProfile
-    // and .history/devices/auto-launch.json) into the central
-    // fleet.devices.<name>.config block. After migrateSplitDeviceLocalMeta so the
-    // device docs are in their canonical location. Also invoked on daemon boot
-    // and on the first device-config read/write in a process, so sentinel'd
-    // installs (which skip this whole run) still converge.
-    migrateDeviceConfigToCentral();
+    // Same split, one level deeper: `browser` stays central (named profiles are
+    // fleet config) but its auto-detected `default` entry is machine-local and was
+    // left behind in the synced file, keeping every box dirty. After
+    // migrateSplitDeviceLocalMeta so the device file is already in its canonical
+    // location before this merges an entry into it.
+    migrateMachineLocalBrowserProfileOutOfCentral();
+    // Converge the device-config/pins stores: fold the central
+    // fleet.devices.<name>.config block + legacy auto-launch.json into the
+    // per-device docs' config:, and extract pins from tracked docs into the
+    // untracked pins JSON. After migrateSplitDeviceLocalMeta so the pins file is
+    // in its canonical location. Also invoked on daemon boot and on the first
+    // device-config read/write in a process, so sentinel'd installs (which skip
+    // this whole run) still converge.
+    migrateDeviceConfigStores();
     // Bucket moves: collapse runtime state into ~/.agents/.history and ~/.agents/.cache.
     migrateRuntimeToHistory();
     migrateLegacySessionMarkersToBookmarks();
@@ -2343,6 +2552,10 @@ export async function runMigration() {
     // Fold the legacy watchdog enable sentinel into `watchdog.enabled` config so a
     // user who opted in under the old build stays opted in after upgrading.
     migrateWatchdogSentinelToConfig();
+    // Delete the compiled "project" ruleset older builds wrote into $HOME — the
+    // duplicate-injection artifact of RUSH-2725. The compiler no longer writes
+    // it; this cleans up what is already on every machine.
+    removeHomeCompiledProjectRules();
     // Deactivate any routine whose execution context no longer resolves ready, so
     // an anchor-less agent/workflow routine cannot keep firing-and-failing after the
     // fold (RUSH-2290). Runs AFTER the tick/watchdog routines are added so those
@@ -2354,4 +2567,18 @@ export async function runMigration() {
     // infinite-exec-loop). Also runs after the bucket moves so it scans the
     // canonical HISTORY_DIR/versions tree.
     repairSelfReferentialBinShims();
+    // Version-skew one-shot (RUSH-2435): retrofit the current pane-died hook
+    // onto any managed tmux session an older binary left with a stale one. Runs
+    // at upgrade time in addition to the daemon-startup call (daemon.ts) so a
+    // machine that upgrades without immediately restarting its daemon still
+    // repairs on the next `agents` invocation. Idempotent/non-destructive.
+    try {
+        const { reconcileSessionHooks } = await import('../tmux/session.js');
+        const { isTmuxInstalled } = await import('../tmux/binary.js');
+        if (isTmuxInstalled())
+            await reconcileSessionHooks();
+    }
+    catch {
+        // best-effort — a migration must never fail because tmux wasn't reachable
+    }
 }

package/dist/lib/installations/resolve.js

@@ -1,5 +1,5 @@
 import { AGENTS } from '../agents.js';
-import { getGlobalDefault } from '../versions.js';
+import { getGlobalDefault } from './versions.js';
 import { listInstallations } from './store.js';
 /**
  * Addressing a frozen installation.

package/dist/lib/installations/strategies.js

@@ -6,7 +6,7 @@ import * as path from 'path';
 import { AGENTS, findInPath, isSelfUpdatingAgent } from '../agents.js';
 import { VERSION_RE } from '../agent-spec/primitives.js';
 import { importInstallScriptBinary } from '../import.js';
-import { getBinaryPath, getLatestNpmVersion, getOldestNpmVersion, getLiveVersion, getVersionHomePath, invalidateLiveVersionCache, isGlobalBinaryAgent, } from '../versions.js';
+import { getBinaryPath, getLatestNpmVersion, getOldestNpmVersion, getLiveVersion, getVersionHomePath, invalidateLiveVersionCache, isGlobalBinaryAgent, } from './versions.js';
 import { installationDir } from './store.js';
 const execAsync = promisify(exec);
 const execFileAsync = promisify(execFile);

package/dist/lib/installations/update.js

@@ -1,7 +1,7 @@
 import * as fs from 'fs';
 import { AGENTS, isAgentHardDeprecated, hardDeprecationError } from '../agents.js';
-import { emit } from '../events.js';
-import { getBinaryPath, invalidateInstalledVersionsCache, invalidateLiveVersionCache, verifyBinaryLaunches, } from '../versions.js';
+import { emit } from '../feed/events.js';
+import { getBinaryPath, invalidateInstalledVersionsCache, invalidateLiveVersionCache, verifyBinaryLaunches, } from './versions.js';
 import { assertValidRelease, selectUpdateStrategy, } from './strategies.js';
 import { listInstallations, recordRelease } from './store.js';
 /**

package/dist/lib/{versions.d.ts → installations/versions.d.ts}

@@ -1,6 +1,6 @@
-import type { AgentId } from './types.js';
-import { compareVersions } from './agent-spec/primitives.js';
-import { type PrunableKind } from './staleness/prune.js';
+import type { AgentId } from '../types.js';
+import { compareVersions } from '../agent-spec/primitives.js';
+import { type PrunableKind } from '../staleness/prune.js';
 /**
  * Resource selection for syncing to a version.
  * Each field can be:
@@ -519,6 +519,15 @@ export interface SyncResult {
      * repo-scope reconcile that ran the prune pass; empty otherwise.
      */
     pruned: Record<PrunableKind, string[]>;
+    /**
+     * Resources this sync refused to write, as user-facing sentences (RUSH-2677).
+     *
+     * An empty `mcp`/`subagents`/… list means "nothing to write"; it cannot also
+     * mean "declined and here is why", which is how a harness with no config
+     * writer reported a clean sync while writing nothing. The rendering command
+     * MUST surface these — a decline nobody prints is the silent no-op again.
+     */
+    declined: string[];
 }
 /**
  * Enumerate the DotAgent repo names that resources can be scoped to:

package/dist/lib/{versions.js → installations/versions.js}

@@ -21,36 +21,36 @@ 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, 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';
-import { activeRulesPreset, filterNamesForActiveResourceProfile } from './resource-profiles.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';
+import { activeRulesPreset, filterNamesForActiveResourceProfile } from '../resource-profiles.js';
 // VERSION_RE + compareVersions are owned by the agent-spec engine primitives
 // (single source of truth). Re-exported below so existing importers of
 // `compareVersions` from './versions.js' keep working.
-import { VERSION_RE, compareVersions } from './agent-spec/primitives.js';
-import { AGENTS, agentConfigDirName, getAccountEmail, resolveAgentName, formatAgentError, findInPath, isSelfUpdatingAgent, isAgentHardDeprecated, hardDeprecationError } from './agents.js';
-import { discoverPermissionGroups, getActivePermissionPresetName, readPermissionPresetRecipe, PERMISSION_PRESET_ENV_VAR } from './permissions.js';
-import { parseMcpConfigForScan, isProjectMcpTrusted } from './mcp.js';
-import { createVersionedAlias, removeVersionedAlias, getConfigSymlinkVersion, ensureClaudeInsideSymlink, assertIsolationBoundary, } from './shims.js';
-import { importInstallScriptBinary } from './import.js';
-import { createInstallation } from './installations/store.js';
-import { INSTALLATION_RECORD_FILE } from './installations/types.js';
-import { IS_WINDOWS, composeWin32CommandLine } from './platform/index.js';
-import { listInstalledSubagents } from './subagents.js';
-import { listInstalledWorkflows } from './workflows.js';
-import { parseHookManifest, registerHooksToSettings, selectHookManifest, pruneVersionHomeHookEntriesFromSettings } from './hooks.js';
-import { supports, explainSkip } from './capabilities.js';
-import { discoverPlugins, syncPluginToVersion, pluginSupportsAgent, cleanOrphanedPluginSkills, marketplaceSpecForName } from './plugins.js';
-import { loadManifest, saveManifest, buildManifest as buildSyncManifest, isStale } from './staleness/index.js';
-import { pruneRemovedResources } from './staleness/prune.js';
-import { emit } from './events.js';
-import { safeJoin } from './paths.js';
-import { readSkillSourceCommandMarker, shouldAlsoInstallCommandAsSkill, shouldInstallCommandAsSkill, } from './command-skills.js';
-import { getWriter, getDetector } from './staleness/registry.js';
-import { syncMemoryToVersionHome } from './memory.js';
-import { listPluginSkillNames, resolveCommandSource, resolveSkillSource } from './staleness/writers/sources.js';
-import { syncProjectResourcesToAgent } from './project-resources.js';
+import { VERSION_RE, compareVersions } from '../agent-spec/primitives.js';
+import { AGENTS, agentConfigDirName, getAccountEmail, resolveAgentName, formatAgentError, findInPath, isSelfUpdatingAgent, isAgentHardDeprecated, hardDeprecationError } from '../agents.js';
+import { discoverPermissionGroups, getActivePermissionPresetName, readPermissionPresetRecipe, PERMISSION_PRESET_ENV_VAR } from '../permissions.js';
+import { parseMcpConfigForScan, isProjectMcpTrusted } from '../mcp.js';
+import { createVersionedAlias, removeVersionedAlias, getConfigSymlinkVersion, ensureClaudeInsideSymlink, assertIsolationBoundary, } from '../shims.js';
+import { importInstallScriptBinary } from '../import.js';
+import { createInstallation } from './store.js';
+import { INSTALLATION_RECORD_FILE } from './types.js';
+import { IS_WINDOWS, composeWin32CommandLine } from '../platform/index.js';
+import { listInstalledSubagents } from '../subagents.js';
+import { listInstalledWorkflows } from '../workflows.js';
+import { parseHookManifest, registerHooksToSettings, selectHookManifest, pruneVersionHomeHookEntriesFromSettings, installSessionTrackerHookSync, installSessionTrackerHook } from '../hooks.js';
+import { supports, explainSkip } from '../capabilities.js';
+import { discoverPlugins, syncPluginToVersion, pluginSupportsAgent, cleanOrphanedPluginSkills, marketplaceSpecForName } from '../plugins/plugins.js';
+import { loadManifest, saveManifest, buildManifest as buildSyncManifest, isStale } from '../staleness/index.js';
+import { pruneRemovedResources } from '../staleness/prune.js';
+import { emit } from '../feed/events.js';
+import { safeJoin } from '../paths.js';
+import { readSkillSourceCommandMarker, shouldAlsoInstallCommandAsSkill, shouldInstallCommandAsSkill, } from '../command-skills.js';
+import { getWriter, getDetector } from '../staleness/registry.js';
+import { syncMemoryToVersionHome } from '../memory.js';
+import { listPluginSkillNames, resolveCommandSource, resolveSkillSource } from '../staleness/writers/sources.js';
+import { syncProjectResourcesToAgent } from '../project-resources.js';
 /** Promisified exec for running shell commands. */
 const execAsync = promisify(exec);
 const execFileAsync = promisify(execFile);
@@ -1638,6 +1638,10 @@ export async function installVersion(agent, version, onProgress, opts) {
         // here on; the release it carries is recorded separately so `agents update`
         // can move the release without invalidating any reference to the label.
         createInstallation(agent, installedVersion, installedVersion);
+        const trackerInstall = await installSessionTrackerHook(agent, installedVersion);
+        if (!trackerInstall.installed && trackerInstall.error) {
+            console.warn(`agents: SessionStart hook not installed for ${agent}@${installedVersion}: ${trackerInstall.error}`);
+        }
         // The self-updating binary just changed on disk — drop the cached
         // `--version` so `agents view` reflects the freshly-installed release.
         invalidateLiveVersionCache(agent);
@@ -1797,6 +1801,10 @@ export async function installVersion(agent, version, onProgress, opts) {
     }
     // Freeze this installation's identity (see the installScript branch above).
     createInstallation(agent, healthyVersion, healthyVersion);
+    const trackerInstall = await installSessionTrackerHook(agent, healthyVersion);
+    if (!trackerInstall.installed && trackerInstall.error) {
+        console.warn(`agents: SessionStart hook not installed for ${agent}@${healthyVersion}: ${trackerInstall.error}`);
+    }
     emit('version.install', { agent, version: healthyVersion });
     return { success: true, installedVersion: healthyVersion };
 }
@@ -1924,7 +1932,7 @@ async function reconcileGlobalBinaryVersions(agent) {
         const staleDir = getVersionDir(agent, version);
         const trashPath = softDeleteVersionDir(agent, version);
         if (trashPath) {
-            const { updateSessionFilePaths } = await import('./session/db.js');
+            const { updateSessionFilePaths } = await import('../session/db.js');
             updateSessionFilePaths(staleDir, trashPath);
             foldedAny = true;
         }
@@ -1962,7 +1970,7 @@ export async function reconcileStaleLatestDir(agent, installedVersion) {
     // harness can't statically transform, so it must stay out of the eager graph.
     const trashPath = softDeleteVersionDir(agent, 'latest');
     if (trashPath) {
-        const { updateSessionFilePaths } = await import('./session/db.js');
+        const { updateSessionFilePaths } = await import('../session/db.js');
         updateSessionFilePaths(staleLatestDir, trashPath);
     }
     return 'trashed';
@@ -2711,7 +2719,7 @@ export function mergeRepoScopedSelections(repos, cwd = process.cwd()) {
  */
 export function syncResourcesToVersion(agent, version, selection, options = {}) {
     if (isAgentHardDeprecated(agent)) {
-        return { commands: false, skills: false, hooks: false, memory: [], permissions: false, mcp: [], subagents: [], plugins: [], workflows: [], projectSkipped: [], pruned: { commands: [], skills: [] } };
+        return { commands: false, skills: false, hooks: false, memory: [], permissions: false, mcp: [], subagents: [], plugins: [], workflows: [], projectSkipped: [], pruned: { commands: [], skills: [] }, declined: [] };
     }
     const agentConfig = AGENTS[agent];
     const versionHome = getVersionHomePath(agent, version);
@@ -2722,7 +2730,7 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
     // care about the ORIGINAL intent: a caller passing no selection means
     // "full sync; persist the staleness manifest after."
     const userPassedSelection = selection !== undefined;
-    const result = { commands: false, skills: false, hooks: false, memory: [], permissions: false, mcp: [], subagents: [], plugins: [], workflows: [], projectSkipped: [], pruned: { commands: [], skills: [] } };
+    const result = { commands: false, skills: false, hooks: false, memory: [], permissions: false, mcp: [], subagents: [], plugins: [], workflows: [], projectSkipped: [], pruned: { commands: [], skills: [] }, declined: [] };
     const cwd = options.cwd || process.cwd();
     const projectAgentsDir = options.projectDir || getProjectAgentsDir(cwd);
     const userAgentsDir = getUserAgentsDir();
@@ -2734,6 +2742,16 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
     if (projectAgentsDir) {
         result.projectSkipped = syncProjectResourcesToAgent(agent, version, projectAgentsDir).skipped;
     }
+    // Install the shared SessionStart state-writer hook for every hook-capable
+    // harness. This must run even when the rest of the sync is skipped by the
+    // staleness guard, because the hook is registered in the harness's native
+    // config (not in the version-home resource tree the manifest tracks).
+    if (supports(agent, 'hooks', version).ok) {
+        const trackerResult = installSessionTrackerHookSync(agent, version);
+        if (!trackerResult.installed && trackerResult.error) {
+            console.warn(`agents: SessionStart hook not installed for ${agent}@${version}: ${trackerResult.error}`);
+        }
+    }
     // Fast guard BEFORE getAvailableResources / pattern expansion /
     // ensureVersionResourcePatterns. Guard needs only loadManifest + isStale
     // (~6 ms); the work that used to sit ahead of it was ~12.5 ms of the 21.5 ms
@@ -3104,6 +3122,8 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
     if (mcpToSync.length > 0 && mcpWriter) {
         const r = mcpWriter.write({ version, versionHome, selection: mcpToSync, cwd });
         result.mcp = r.synced;
+        if (r.errors?.length)
+            result.declined.push(...r.errors.map((e) => `mcp: ${e}`));
         // mcp patterns already written via ensureVersionResourcePatterns above.
     }
     // Sync subagents — dispatch through WRITERS.subagents. listInstalledSubagents

package/dist/lib/isolation-boundary-report.js

@@ -1,6 +1,6 @@
 import chalk from 'chalk';
 import { IsolationBoundaryError } from './shims.js';
-import { listInstalledVersions } from './versions.js';
+import { listInstalledVersions } from './installations/versions.js';
 /**
  * Turn an {@link IsolationBoundaryError} into guidance. The boundary is enforced by a
  * throw so it cannot be forgotten; this is what keeps that from surfacing as a stack

package/dist/lib/linear-projects.d.ts

@@ -60,3 +60,31 @@ export declare function pickLinearProject(query: string, projects: LinearProject
  * the user down a wrong "no matches" path.
  */
 export declare function listLinearProjects(): LinearProjectLite[];
+/**
+ * The `linear` block a def should carry after binding it to `project`.
+ *
+ * Pure so the write rule is testable without a `linear` CLI or a filesystem —
+ * `agents projects link` is the only caller and does nothing else to the field.
+ *
+ * Two rules, both learned from real drift:
+ *
+ * - `name` is REFRESHED, never merely preserved. It used to be written by
+ *   spreading `prior`, so a project renamed on the board kept its old label in
+ *   the YAML forever — and that label is what the status card, the AGI EXT
+ *   Fleet panel (`linearProjectName`), and agents naming the work all read.
+ * - `url` is dropped when the projectId CHANGES and the incoming row has none.
+ *   Carrying it over would leave a def pointing at the previous project's page
+ *   beside the new project's name, and the status card prefers `url` over the
+ *   id — so the one field a reader clicks would go to the wrong project.
+ *   Re-linking the SAME id keeps a previously stored url, since the CLI's list
+ *   row omitting `url` says nothing about whether the project has one.
+ */
+export declare function nextLinearLink(prior: {
+    projectId?: string;
+    url?: string;
+    name?: string;
+} | undefined, project: LinearProjectLite): {
+    projectId: string;
+    url?: string;
+    name: string;
+};