@phnx-labs/agents-cli 1.22.38 → 1.22.40

package/dist/lib/state.d.ts

@@ -47,6 +47,16 @@ export declare function getUserAgentsDir(): string;
  * @deprecated Use getUserAgentsDir() directly.
  */
 export declare function getOptionalUserAgentsDir(): string | null;
+/**
+ * True when `agentsPath` is a reserved `.agents` root that must never be
+ * treated as a project layer: the user repo (~/.agents), the system repo
+ * (~/.agents/.system), or a git checkout of either canonical DotAgents repo.
+ * `getProjectAgentsDir` skips these while walking up; direct-cwd callers
+ * (`compileRulesForProject`) consult the same predicate so `$HOME` — whose
+ * `.agents/rules` is the user layer itself — can never compile as a
+ * "project" (RUSH-2725).
+ */
+export declare function isReservedAgentsDir(agentsPath: string): boolean;
 /** Walk up from startPath to find a project-scoped .agents/ directory (skipping both roots). */
 export declare function getProjectAgentsDir(startPath?: string): string | null;
 /** Return all .agents/ directories in scope: project, user, then system. */
@@ -250,8 +260,15 @@ export declare function getTeamsRegistryPath(): string;
 export declare function getDevicesRegistryPath(): string;
 /** Path to the device ignore-list — tailscale node names the user dismissed, so auto-discovery never re-suggests them. Per-machine, same dir as the registry. */
 export declare function getDevicesIgnoredPath(): string;
-/** Path to the LEGACY device auto-launch preference file — which registered devices are eligible/preferred for the ext's auto-host selection. Superseded by the central `fleet.devices.<name>.config` block; only lib/devices/config-migration.ts still reads it (to fold + remove it). */
+/** Path to the LEGACY device auto-launch preference file — which registered devices are eligible/preferred for the ext's auto-host selection. Superseded by the per-device doc `config:` block; only lib/devices/config-migration.ts still reads it (to fold + remove it). */
 export declare function getDevicesAutoLaunchPath(): string;
+/** Path to THIS machine's agent pins — the `agents:` global defaults and
+ * `isolatedAgents:` pointers. Each pin names a version installed on THIS
+ * machine, so it is machine-local runtime state and lives beside the device
+ * registry under `.history/devices/` (untracked) — NOT in the tracked
+ * per-device doc, where auto-written pins caused commit churn on every
+ * `agents use` / install. Read at call time like the other devices-dir paths. */
+export declare function getDevicePinsPath(): string;
 /** Dir of "pending device" sentinels (~/.agents/.cache/state/devices-pending/) — one empty-ish file per newly-discovered, not-yet-approved tailnet node. Written by the daemon probe, read by the menu-bar helper (mirrors the attention sentinel dir). */
 export declare function getDevicesPendingDir(): string;
 /** Path to cloud dispatch cache (~/.agents/.cache/cloud/). */
@@ -373,6 +390,7 @@ export declare function getDeviceMetaPath(): string;
  * Gitignored (under .history/) and regenerable; never synced.
  */
 export declare function getVersionResourcesPath(): string;
+export declare function withMetaLock<T>(fn: () => T): T;
 /**
  * Read and cache ~/.agents/agents.yaml, migrating from legacy locations if needed.
  *

package/dist/lib/state.js

@@ -267,14 +267,27 @@ function isUserOrSystemRepoCheckout(agentsPath) {
         return false;
     return canonicalDotAgentsRepoSlugs().has(origin);
 }
+/**
+ * True when `agentsPath` is a reserved `.agents` root that must never be
+ * treated as a project layer: the user repo (~/.agents), the system repo
+ * (~/.agents/.system), or a git checkout of either canonical DotAgents repo.
+ * `getProjectAgentsDir` skips these while walking up; direct-cwd callers
+ * (`compileRulesForProject`) consult the same predicate so `$HOME` — whose
+ * `.agents/rules` is the user layer itself — can never compile as a
+ * "project" (RUSH-2725).
+ */
+export function isReservedAgentsDir(agentsPath) {
+    return isSamePath(agentsPath, SYSTEM_AGENTS_DIR)
+        || isSamePath(agentsPath, USER_AGENTS_DIR)
+        || isUserOrSystemRepoCheckout(agentsPath);
+}
 /** Walk up from startPath to find a project-scoped .agents/ directory (skipping both roots). */
 export function getProjectAgentsDir(startPath = process.cwd()) {
     let dir = path.resolve(startPath);
     while (true) {
         const agentsPath = path.join(dir, '.agents');
         if (fs.existsSync(agentsPath) && fs.statSync(agentsPath).isDirectory()) {
-            if (!isSamePath(agentsPath, SYSTEM_AGENTS_DIR) && !isSamePath(agentsPath, USER_AGENTS_DIR)
-                && !isUserOrSystemRepoCheckout(agentsPath)) {
+            if (!isReservedAgentsDir(agentsPath)) {
                 return agentsPath;
             }
         }
@@ -564,8 +577,15 @@ function getDevicesDir() {
 export function getDevicesRegistryPath() { return path.join(getDevicesDir(), 'registry.json'); }
 /** Path to the device ignore-list — tailscale node names the user dismissed, so auto-discovery never re-suggests them. Per-machine, same dir as the registry. */
 export function getDevicesIgnoredPath() { return path.join(getDevicesDir(), 'ignored.json'); }
-/** Path to the LEGACY device auto-launch preference file — which registered devices are eligible/preferred for the ext's auto-host selection. Superseded by the central `fleet.devices.<name>.config` block; only lib/devices/config-migration.ts still reads it (to fold + remove it). */
+/** Path to the LEGACY device auto-launch preference file — which registered devices are eligible/preferred for the ext's auto-host selection. Superseded by the per-device doc `config:` block; only lib/devices/config-migration.ts still reads it (to fold + remove it). */
 export function getDevicesAutoLaunchPath() { return path.join(getDevicesDir(), 'auto-launch.json'); }
+/** Path to THIS machine's agent pins — the `agents:` global defaults and
+ * `isolatedAgents:` pointers. Each pin names a version installed on THIS
+ * machine, so it is machine-local runtime state and lives beside the device
+ * registry under `.history/devices/` (untracked) — NOT in the tracked
+ * per-device doc, where auto-written pins caused commit churn on every
+ * `agents use` / install. Read at call time like the other devices-dir paths. */
+export function getDevicePinsPath() { return path.join(getDevicesDir(), `pins-${machineId()}.json`); }
 /** Dir of "pending device" sentinels (~/.agents/.cache/state/devices-pending/) — one empty-ish file per newly-discovered, not-yet-approved tailnet node. Written by the daemon probe, read by the menu-bar helper (mirrors the attention sentinel dir). */
 export function getDevicesPendingDir() { return path.join(getRuntimeStateDir(), 'devices-pending'); }
 /** Path to cloud dispatch cache (~/.agents/.cache/cloud/). */
@@ -779,6 +799,7 @@ function currentMetaStamp() {
     return safeMtimeMs(META_FILE)
         + '|' + safeMtimeMs(SYSTEM_META_FILE)
         + '|' + safeMtimeMs(getDeviceMetaPath())
+        + '|' + safeMtimeMs(getDevicePinsPath())
         + '|' + safeMtimeMs(getVersionResourcesPath());
 }
 /** Memoize a parsed Meta against the current file mtimes. */
@@ -786,7 +807,7 @@ function rememberMeta(meta) {
     metaCache = { stamp: currentMetaStamp(), meta };
     return meta;
 }
-function withMetaLock(fn) {
+export function withMetaLock(fn) {
     ensureAgentsDir();
     if (metaLockDepth > 0) {
         metaLockDepth++;
@@ -821,12 +842,15 @@ function writeIfChanged(filePath, content) {
     atomicWriteFileSync(filePath, content);
 }
 /**
- * Partition the in-memory Meta across three files by sync-domain:
+ * Partition the in-memory Meta across four files by sync-domain:
  *   - central  `~/.agents/agents.yaml`             — portable, everything else
- *              (including the user-scope `config:` block and the per-device
- *              operator config under `fleet.devices.<name>.config`)
- *   - device   `~/.agents/devices/<machine>/agents.yaml` — `agents:` pins +
- *              `routines:` (all per-machine)
+ *              (including the user-scope `config:` block and the fleet-wide
+ *              config defaults under `fleet.defaults.config`)
+ *   - device   `~/.agents/devices/<machine>/agents.yaml` — TRACKED operator doc:
+ *              `routines:` + `config:` (per-device operator settings) + machine-local
+ *              `browser:` / `projectRoot` (never synced)
+ *   - pins     `~/.agents/.history/devices/pins-<host>.json` — `agents:` +
+ *              `isolatedAgents:` (machine-local runtime, untracked)
  *   - history  `~/.agents/.history/version-resources.json` — `versions:` (machine-local)
  * All callers funnel through writeMeta → here, so nothing else changes. Empty
  * `agents:` / `versions:` are not written (no empty committed files).
@@ -952,48 +976,83 @@ function writeMetaUnlocked(meta) {
     const { agents, isolatedAgents, versions, deviceRoutines, deviceConfig, deviceBrowser, projectRoot, ...central } = meta;
     // Write the machine-local files FIRST, then strip central — so a crash mid-write
     // never removes pins/versions from central before they're persisted elsewhere.
-    const devicePath = getDeviceMetaPath();
     const hasAgents = !!agents && Object.keys(agents).length > 0;
     // The isolated pointer names a version installed on THIS machine, exactly like a
-    // global pin, so it belongs beside `agents:` in the device file rather than in the
+    // global pin, so it belongs beside `agents` in the pins file rather than in the
     // central doc that syncs — otherwise another machine inherits a pointer to a copy
     // it does not have.
     const hasIsolatedAgents = !!isolatedAgents && Object.keys(isolatedAgents).length > 0;
-    const hasDeviceRoutines = Array.isArray(deviceRoutines);
-    // Machine-visibility operator config. Lives here rather than in the synced
-    // central file because nothing off-box reads it — and because
-    // browser.remote-control is a consent flag that must not propagate on pull.
+    // Pins (`agents:` defaults + `isolatedAgents:`) are machine-local runtime
+    // state — they live in the untracked .history pins JSON, never in the tracked
+    // per-device doc (auto-written pins there caused commit churn on every
+    // `agents use` / install).
+    const pinsPath = getDevicePinsPath();
+    if (hasAgents || hasIsolatedAgents) {
+        const pins = {};
+        if (hasAgents)
+            pins.agents = agents;
+        if (hasIsolatedAgents)
+            pins.isolatedAgents = isolatedAgents;
+        fs.mkdirSync(path.dirname(pinsPath), { recursive: true });
+        writeIfChanged(pinsPath, JSON.stringify(pins, null, 2) + '\n');
+    }
+    else if (fs.existsSync(pinsPath)) {
+        // Every pin was cleared. Persist the emptied file instead of skipping the
+        // write — otherwise the stale pins file survives and overlayMachineLocal
+        // re-applies the removed pin on the next read.
+        writeIfChanged(pinsPath, '{}\n');
+    }
+    // The tracked per-device doc carries operator-owned fields: `routines:`
+    // (device-local activation) from here, `config:` from lib/device-config.ts,
+    // and machine-local browser defaults / projectRoot (never fleet policy).
+    // Merge over the existing doc so a `config:` block written outside this path
+    // is never clobbered. Pins are stripped defensively — they belong to the pins
+    // file now (the migration strips them too; a hand-edited doc converges on the
+    // next write).
+    const devicePath = getDeviceMetaPath();
+    let doc = {};
+    if (fs.existsSync(devicePath)) {
+        try {
+            const parsed = yaml.parse(fs.readFileSync(devicePath, 'utf-8'));
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                doc = parsed;
+            }
+        }
+        catch { /* preserve the existing tolerance for malformed legacy device YAML */ }
+    }
+    delete doc.agents;
+    delete doc.isolatedAgents;
+    if (Array.isArray(deviceRoutines))
+        doc.routines = deviceRoutines;
+    else
+        delete doc.routines;
     const hasDeviceConfig = !!deviceConfig && Object.keys(deviceConfig).length > 0;
+    if (hasDeviceConfig)
+        doc.config = deviceConfig;
+    else
+        delete doc.config;
     const hasDeviceBrowser = !!deviceBrowser && Object.keys(deviceBrowser).length > 0;
-    // An inferred local filesystem path — machine state, never fleet policy.
+    if (hasDeviceBrowser)
+        doc.browser = deviceBrowser;
+    else
+        delete doc.browser;
     const hasProjectRoot = typeof projectRoot === 'string' && projectRoot.length > 0;
-    if (hasAgents || hasIsolatedAgents || hasDeviceRoutines || hasDeviceConfig || hasDeviceBrowser || hasProjectRoot) {
-        // Device-local doc carries `agents:` pins and `routines:` — per-machine and
-        // must never land in central agents.yaml (which syncs). Operator config
-        // used to ride this doc under `config:`; it now lives centrally under
-        // `fleet.devices.<name>.config` (see lib/device-config.ts).
-        const deviceDoc = {};
-        if (hasAgents)
-            deviceDoc.agents = agents;
-        if (hasIsolatedAgents)
-            deviceDoc.isolatedAgents = isolatedAgents;
-        if (hasDeviceRoutines)
-            deviceDoc.routines = deviceRoutines;
-        if (hasDeviceConfig)
-            deviceDoc.config = deviceConfig;
-        if (hasDeviceBrowser)
-            deviceDoc.browser = deviceBrowser;
-        if (hasProjectRoot)
-            deviceDoc.projectRoot = projectRoot;
+    if (hasProjectRoot)
+        doc.projectRoot = projectRoot;
+    else
+        delete doc.projectRoot;
+    if (Object.keys(doc).length > 0) {
         fs.mkdirSync(path.dirname(devicePath), { recursive: true });
-        writeIfChanged(devicePath, META_HEADER + yaml.stringify(deviceDoc));
+        writeIfChanged(devicePath, META_HEADER + yaml.stringify(doc));
     }
     else if (fs.existsSync(devicePath)) {
-        // Every device-local value was cleared. Persist the emptied doc instead of
-        // skipping the write — otherwise the stale device file survives and
-        // overlayMachineLocal re-applies the removed pin/default on the next read,
-        // leaving a dangling value (e.g. a default pointing at a deleted profile).
-        writeIfChanged(devicePath, META_HEADER + yaml.stringify({ agents: {} }));
+        // Nothing operator-owned remains — remove the doc rather than leaving an
+        // empty tracked file behind.
+        fs.rmSync(devicePath, { force: true });
+        try {
+            fs.rmdirSync(path.dirname(devicePath));
+        }
+        catch { /* not empty — other files live in the device dir */ }
     }
     if (versions && Object.keys(versions).length > 0) {
         const vrPath = getVersionResourcesPath();
@@ -1005,20 +1064,27 @@ function writeMetaUnlocked(meta) {
 }
 /**
  * Overlay this machine's local state onto a central-portable Meta:
- *   - `agents:` and `isolatedAgents:` from the device file (device wins; the union
+ *   - `agents:` and `isolatedAgents:` from the pins file (device wins; the union
  *     both preserves the one-level merge and self-heals a pre-migration central that
  *     still has pins)
- *   - `routines:` from the device file into `deviceRoutines` (device-local
- *     routine activation)
+ *   - `routines:` / machine-local `browser:` / `projectRoot` from the tracked device
+ *     doc (device-local; the doc's `config:` block is read by lib/device-config.ts,
+ *     not overlaid here)
  *   - `versions:` from the history JSON (wholesale replace; falls back to
  *     whatever central carried when the history file doesn't exist yet)
- *
- * (Device operator config is NOT overlaid here: it lives centrally under
- * `fleet.devices.<name>.config` — see lib/device-config.ts. The legacy
- * `config:`/`defaultBrowserProfile:` keys in a device doc are folded into the
- * central block by lib/devices/config-migration.ts.)
  */
 function overlayMachineLocal(meta) {
+    const pinsPath = getDevicePinsPath();
+    if (fs.existsSync(pinsPath)) {
+        try {
+            const pins = JSON.parse(fs.readFileSync(pinsPath, 'utf-8'));
+            if (pins?.agents)
+                meta.agents = { ...meta.agents, ...pins.agents };
+            if (pins?.isolatedAgents)
+                meta.isolatedAgents = { ...meta.isolatedAgents, ...pins.isolatedAgents };
+        }
+        catch { /* ignore malformed pins file */ }
+    }
     const devicePath = getDeviceMetaPath();
     if (fs.existsSync(devicePath)) {
         let dm = null;
@@ -1027,10 +1093,13 @@ function overlayMachineLocal(meta) {
         }
         catch { /* preserve the existing tolerance for malformed legacy device YAML */ }
         if (dm) {
+            // Pre-migration pins may still live in the tracked doc — honor them until
+            // migrateDeviceConfigStores strips them. Pins-file values already applied
+            // above win on key conflict.
             if (dm?.agents)
-                meta.agents = { ...meta.agents, ...dm.agents };
+                meta.agents = { ...dm.agents, ...meta.agents };
             if (dm?.isolatedAgents)
-                meta.isolatedAgents = { ...meta.isolatedAgents, ...dm.isolatedAgents };
+                meta.isolatedAgents = { ...dm.isolatedAgents, ...meta.isolatedAgents };
             if (typeof dm?.projectRoot === 'string')
                 meta.projectRoot = dm.projectRoot;
             if (dm?.browser && typeof dm.browser === 'object' && !Array.isArray(dm.browser)) {
@@ -1039,7 +1108,7 @@ function overlayMachineLocal(meta) {
             if (dm?.config && typeof dm.config === 'object' && !Array.isArray(dm.config)) {
                 meta.deviceConfig = { ...meta.deviceConfig, ...dm.config };
             }
-            if (dm && Object.prototype.hasOwnProperty.call(dm, 'routines')) {
+            if (Object.prototype.hasOwnProperty.call(dm, 'routines')) {
                 if (!Array.isArray(dm.routines) || dm.routines.some((name) => typeof name !== 'string')) {
                     throw new Error(`Device config corrupted at ${devicePath}: routines must be a string list.`);
                 }

package/dist/lib/subagents.js

@@ -11,7 +11,7 @@ import * as path from 'path';
 import * as yaml from 'yaml';
 import { capableAgents } from './capabilities.js';
 import { getSubagentsDir, getUserSubagentsDir, getTrashSubagentsDir } from './state.js';
-import { listInstalledVersions, getVersionHomePath } from './versions.js';
+import { listInstalledVersions, getVersionHomePath } from './installations/versions.js';
 import { safeJoin } from './paths.js';
 import { subagentTarget, writeSubagentToHome, listInstalledSubagentNames, listInstalledSubagentsRich, removeSubagentFromHome, trashSubagentFromHome, copyDirWithRename, } from './subagents-registry.js';
 /**

package/dist/lib/sync-status.js

@@ -21,7 +21,7 @@
 import simpleGit from 'simple-git';
 import { ALL_AGENT_IDS } from './agents.js';
 import { diffVersionResources, } from './doctor-diff.js';
-import { listInstalledVersions, getGlobalDefault } from './versions.js';
+import { listInstalledVersions, getGlobalDefault } from './installations/versions.js';
 import { loadManifest } from './staleness/index.js';
 import { getSystemAgentsDir } from './state.js';
 import { isGitRepo } from './git.js';

package/dist/lib/sync-umbrella.d.ts

@@ -12,7 +12,7 @@
  *   repos    -> git pull of ~/.agents + enabled ~/.agents-* extras (pullRepo)
  *   secrets  -> listRemoteBundles + pullBundle (needs a passphrase; skipped
  *               cleanly when none is available — tokenized non-interactive auth
- *               arrives with `agents login`, #366/#367)
+ *               arrives with `agents secrets vault unlock`, #366/#367)
  *   reconcile-> refresh({ skipPrompts }) — re-materialize resources into homes
  */
 /** The umbrella flags off `agents sync`. */
@@ -59,6 +59,11 @@ export interface UmbrellaResult {
         skipped: boolean;
     };
     reconciled: boolean;
+    /**
+     * Resources the reconcile stage refused to write, as user-facing sentences.
+     * Empty when nothing was declined — never conflated with "nothing to do".
+     */
+    declined: string[];
 }
 export interface RunUmbrellaArgs {
     flags: UmbrellaFlags;

package/dist/lib/sync-umbrella.js

@@ -12,7 +12,7 @@
  *   repos    -> git pull of ~/.agents + enabled ~/.agents-* extras (pullRepo)
  *   secrets  -> listRemoteBundles + pullBundle (needs a passphrase; skipped
  *               cleanly when none is available — tokenized non-interactive auth
- *               arrives with `agents login`, #366/#367)
+ *               arrives with `agents secrets vault unlock`, #366/#367)
  *   reconcile-> refresh({ skipPrompts }) — re-materialize resources into homes
  */
 import { pullRepo } from './git.js';
@@ -55,7 +55,7 @@ export function planUmbrellaStages(f) {
 export async function runUmbrellaSync(args) {
     const { flags, log, yes, passphrase, quiet = false } = args;
     const plan = planUmbrellaStages(flags);
-    const result = { plan, reconciled: false };
+    const result = { plan, reconciled: false, declined: [] };
     if (plan.fetchRepos) {
         const dirs = [
             { alias: 'user', dir: getUserAgentsDir() },
@@ -74,13 +74,17 @@ export async function runUmbrellaSync(args) {
             }
         }
         result.repos = { pulled, errors };
+        if (!errors.some((error) => error.startsWith('user:'))) {
+            const { reconcileDeviceDiscoveryPolicies } = await import('./devices/discovery-policy.js');
+            await reconcileDeviceDiscoveryPolicies();
+        }
     }
     if (plan.fetchSecrets) {
         if (!passphrase) {
             result.secrets = {
                 pulled: 0,
                 skipped: true,
-                reason: `no passphrase — set ${SYNC_PASSPHRASE_ENV} or run \`agents login\` (#366)`,
+                reason: `no passphrase — set ${SYNC_PASSPHRASE_ENV} or run \`agents secrets vault unlock\` (#366)`,
                 errors: [],
             };
             log(`secrets: skipped (no passphrase — set ${SYNC_PASSPHRASE_ENV})`);
@@ -109,8 +113,9 @@ export async function runUmbrellaSync(args) {
     }
     if (plan.reconcile) {
         const { refresh } = await import('./refresh.js');
-        await refresh({ skipPrompts: yes, quiet });
+        const refreshed = await refresh({ skipPrompts: yes, quiet });
         result.reconciled = true;
+        result.declined = refreshed.declined;
         // Keep already-registered devices' reachability current, and surface newly
         // appeared tailnet nodes as "pending" for the menu-bar Register/Ignore gate
         // rather than silently adding them (refresh mode). Soft: a machine without

package/dist/lib/teams/agents.js

@@ -8,7 +8,7 @@
  * multiple permission modes (plan, edit, full).
  */
 import { spawn, execSync } from 'child_process';
-import { getAgentsInvocation } from '../daemon.js';
+import { getAgentsInvocation } from '../daemon/daemon.js';
 import * as fs from 'fs/promises';
 import * as fsSync from 'fs';
 import * as path from 'path';
@@ -20,7 +20,7 @@ import { normalizeEvents } from './parsers.js';
 import { debug } from './debug.js';
 import { getAgentsDir as getSystemAgentsDir, getShimsDir } from '../state.js';
 import { AGENTS, getAccountInfo } from '../agents.js';
-import { resolveVersion, isVersionInstalled, verifyInstalledBinaryLaunches } from '../versions.js';
+import { resolveVersion, isVersionInstalled, verifyInstalledBinaryLaunches } from '../installations/versions.js';
 import { sanitizeProcessEnv } from '../secrets/bundles.js';
 import { resolveActor, actorEnv } from '../actor.js';
 import { recordRunName } from '../session/run-names.js';

package/dist/lib/teams/registry.js

@@ -13,7 +13,7 @@ import * as path from 'path';
 import { randomBytes } from 'crypto';
 import lockfile from 'proper-lockfile';
 import { getTeamsRegistryPath } from '../state.js';
-import { emit } from '../events.js';
+import { emit } from '../feed/events.js';
 async function registryPath() {
     return getTeamsRegistryPath();
 }

package/dist/lib/terminal/backends/vscodium-agent.js

@@ -7,7 +7,7 @@
  * the editor CLI's `--open-url` flag. The extension opens an editor-tab terminal
  * in `cwd`, runs `command`, and its shell-adoption promotes a resume command
  * (e.g. `claude --resume <id>`) to the matching agent chip. Driving the editor
- * CLI (not macOS `open`) means this works over `--host` SSH and on Linux, needs
+ * CLI (not macOS `open`) means this works over `--device` SSH and on Linux, needs
  * no OS URL-scheme handler registration, and sends the command into an
  * already-interactive login shell — so no `zsh -ilc` wrap (the other backends'
  * wrapper) is applied here.

package/dist/lib/terminal/engine.js

@@ -19,7 +19,7 @@ export function specForRequest(req) {
 export async function openSurface(req, opts = {}) {
     try {
         // Both can throw: specForRequest on an unknown backend, runSpec when the
-        // SSH transport rejects an invalid --host target. Keep them inside the
+        // SSH transport rejects an invalid --device target. Keep them inside the
         // catch so a bad request degrades to a per-surface failure, never a throw.
         const spec = specForRequest(req);
         const res = await runSpec(spec, req.host, opts.resolveHost);

package/dist/lib/terminal/index.d.ts

@@ -16,3 +16,7 @@ export { specForRequest, buildRequests, openSurface, openSurfaces, type OpenOpti
 export { runLocal, runRemote, runSpec, remoteCommand, type HostResolver, type RunResult } from './transport.js';
 export { injectIntoTerminal, tmuxSendKeysArgv, tmuxInjectSpecs, itermInjectScript, ghosttyInjectScript, appleScriptInjectSpec, vscodiumInjectUri, vscodiumInjectSpec, type InjectTarget, type InjectBackend, type InjectOptions, type InjectResult, } from './inject.js';
 export { resolveInjectTarget, resolveInjectTargetForSession, type InjectResolution, type InjectRail, type ResolveOptions, } from './resolve.js';
+export { iLoginShell } from './shell.js';
+export { shellQuote } from './quote.js';
+export { parseTerminalFlag, stripTerminalFlag, buildRunCommand, openRunInTerminal, toHostSamples, TERMINAL_FLAG_BACKENDS } from './run-surface.js';
+export type { OpenRunSurfaceParams, OpenRunSurfaceResult } from './run-surface.js';

package/dist/lib/terminal/index.js

@@ -7,3 +7,6 @@ export { specForRequest, buildRequests, openSurface, openSurfaces, } from './eng
 export { runLocal, runRemote, runSpec, remoteCommand } from './transport.js';
 export { injectIntoTerminal, tmuxSendKeysArgv, tmuxInjectSpecs, itermInjectScript, ghosttyInjectScript, appleScriptInjectSpec, vscodiumInjectUri, vscodiumInjectSpec, } from './inject.js';
 export { resolveInjectTarget, resolveInjectTargetForSession, } from './resolve.js';
+export { iLoginShell } from './shell.js';
+export { shellQuote } from './quote.js';
+export { parseTerminalFlag, stripTerminalFlag, buildRunCommand, openRunInTerminal, toHostSamples, TERMINAL_FLAG_BACKENDS } from './run-surface.js';

package/dist/lib/terminal/inject.d.ts

@@ -12,7 +12,7 @@
  * It mirrors the engine's shape exactly: pure per-backend spec builders (like
  * `tmuxTabArgv` / `itermTabScript`) produce a `LaunchSpec` (argv), and the same
  * `runSpec` transport runs it — so injection inherits the engine's local/remote
- * (`--host` over SSH) execution for free. A `LaunchSpec` never opens anything;
+ * (`--device` over SSH) execution for free. A `LaunchSpec` never opens anything;
  * building one is side-effect-free and unit-testable without a display.
  *
  * Backends (each addresses the EXACT split, not the frontmost surface):
@@ -27,7 +27,7 @@
  *             into the swarmify `swarm-ext` extension's `/inject` verb, targeting
  *             a live-terminals.json terminal by id. Focus-independent, exact
  *             terminal, and (like the launch backend, src/lib/terminal/backends/
- *             vscodium-agent.ts) works over `--host` SSH and on Linux.
+ *             vscodium-agent.ts) works over `--device` SSH and on Linux.
  *   - ghostty (macOS) → COARSE only: Ghostty has no scripting dictionary, so
  *             there is no per-split addressing — this raises a window and types
  *             via System Events keystrokes, stealing focus. The resolver refuses

package/dist/lib/terminal/inject.js

@@ -12,7 +12,7 @@
  * It mirrors the engine's shape exactly: pure per-backend spec builders (like
  * `tmuxTabArgv` / `itermTabScript`) produce a `LaunchSpec` (argv), and the same
  * `runSpec` transport runs it — so injection inherits the engine's local/remote
- * (`--host` over SSH) execution for free. A `LaunchSpec` never opens anything;
+ * (`--device` over SSH) execution for free. A `LaunchSpec` never opens anything;
  * building one is side-effect-free and unit-testable without a display.
  *
  * Backends (each addresses the EXACT split, not the frontmost surface):
@@ -27,7 +27,7 @@
  *             into the swarmify `swarm-ext` extension's `/inject` verb, targeting
  *             a live-terminals.json terminal by id. Focus-independent, exact
  *             terminal, and (like the launch backend, src/lib/terminal/backends/
- *             vscodium-agent.ts) works over `--host` SSH and on Linux.
+ *             vscodium-agent.ts) works over `--device` SSH and on Linux.
  *   - ghostty (macOS) → COARSE only: Ghostty has no scripting dictionary, so
  *             there is no per-split addressing — this raises a window and types
  *             via System Events keystrokes, stealing focus. The resolver refuses

package/dist/lib/terminal/transport.js

@@ -5,7 +5,7 @@
  * are short-lived commands that create the surface and return, so waiting gives
  * a real success/failure. Remote: serialize the argv into one shell string and
  * hand it to `sshExec` — the same hardened SSH primitive `agents sessions
- * --host` and the browser driver use (target-injection guard, POSIX quoting,
+ * --device` and the browser driver use (target-injection guard, POSIX quoting,
  * connection multiplexing).
  */
 import { spawn } from 'child_process';

package/dist/lib/tmux/index.d.ts

@@ -5,4 +5,4 @@
  */
 export { findTmuxBinary, isTmuxInstalled, getTmuxVersion, isTmuxVersionSupported, MIN_TMUX_VERSION, assertTmuxAvailable, TmuxUnavailableError, TmuxCommandError, runTmux, attachTmux, } from './binary.js';
 export { getDefaultSocketPath, getSessionMetaPath, ensureTmuxDir, } from './paths.js';
-export { assertValidSessionName, slugifyName, hasSession, createSession, killSession, killAll, listSessions, splitPane, sendKeys, capturePane, readSessionMeta, TmuxSessionError, type SessionMeta, type CreateSessionOptions, type ListedSession, type SplitOptions, type SendOptions, type CaptureOptions, } from './session.js';
+export { assertValidSessionName, slugifyName, hasSession, createSession, killSession, killAll, listSessions, splitPane, sendKeys, capturePane, readSessionMeta, TmuxSessionError, reconcileSessionHooks, ensureSessionHookRepaired, type SessionMeta, type CreateSessionOptions, type ListedSession, type SplitOptions, type SendOptions, type CaptureOptions, } from './session.js';

package/dist/lib/tmux/index.js

@@ -5,4 +5,4 @@
  */
 export { findTmuxBinary, isTmuxInstalled, getTmuxVersion, isTmuxVersionSupported, MIN_TMUX_VERSION, assertTmuxAvailable, TmuxUnavailableError, TmuxCommandError, runTmux, attachTmux, } from './binary.js';
 export { getDefaultSocketPath, getSessionMetaPath, ensureTmuxDir, } from './paths.js';
-export { assertValidSessionName, slugifyName, hasSession, createSession, killSession, killAll, listSessions, splitPane, sendKeys, capturePane, readSessionMeta, TmuxSessionError, } from './session.js';
+export { assertValidSessionName, slugifyName, hasSession, createSession, killSession, killAll, listSessions, splitPane, sendKeys, capturePane, readSessionMeta, TmuxSessionError, reconcileSessionHooks, ensureSessionHookRepaired, } from './session.js';

package/dist/lib/tmux/session.d.ts

@@ -188,7 +188,7 @@ export declare function paneExitStatus(pane: string, socket?: string): Promise<P
  * Best-effort — returns false when tmux rejects the hook so callers do not
  * stamp a schema marker and daemon reconciliation can retry later.
  */
-export declare function setSessionHook(name: string, hook: string, command: string, socket?: string): Promise<boolean>;
+export declare function setSessionHook(name: string, hook: string, command: string, socket?: string, timeoutMs?: number): Promise<boolean>;
 /**
  * Schema version of the `pane-died` hook installed on managed `agents run`
  * sessions. Bump whenever the hook's SHAPE changes so the daemon reconcile
@@ -231,7 +231,7 @@ export declare const AGENT_HOOK_SCHEMA = 5;
  */
 export declare function agentPaneDiedHook(sessionName: string, agentPane: string): string;
 /** Stamp a session's hook-schema marker to the current version. */
-export declare function markSessionHookSchema(name: string, socket?: string): Promise<void>;
+export declare function markSessionHookSchema(name: string, socket?: string, timeoutMs?: number): Promise<void>;
 /**
  * The outcome of {@link prepareSessionForResume}. `attach` carries the pane it
  * positively resolved so the caller can read that pane's exit status back after
@@ -261,15 +261,30 @@ export declare function prepareSessionForResume(name: string, socket?: string):
  * exited a split — self-heals in place, without waiting for those agents to exit
  * or for the server to be recycled.
  *
- * The daemon calls this on a light interval. The per-session `@ag_hook_schema`
- * marker makes steady-state a cheap no-op: a session already at the current
- * schema is skipped. Only run-wrapped sessions (`ag-` prefix) are touched — an
+ * NOT a daemon poll — the 5-minute `tmux-reconcile` routine that used to call this
+ * was deleted (RUSH-2495). It survives as the version-skew ONE-SHOT: the daemon
+ * calls it once at startup (`runDaemon` in `../daemon.js`) and once from the
+ * upgrade-time migration (`runMigration` in `../migrate.js`), so a session a
+ * pre-fix binary left with a stale hook still self-heals without a live poller.
+ * `ensureSessionHookRepaired` covers the steady-state gap between those two
+ * points by repairing a single session right before it's attached to. The
+ * per-session `@ag_hook_schema` marker makes both paths a cheap no-op once a
+ * session is current. Only run-wrapped sessions (`ag-` prefix) are touched — an
  * externally-created session on the socket keeps whatever hook it set.
  */
 export declare function reconcileSessionHooks(socket?: string): Promise<{
     scanned: number;
     reconciled: number;
 }>;
+/**
+ * Repair a single managed session's `pane-died` hook right before it is
+ * attached to, so a legacy session left by a pre-fix binary self-heals on the
+ * next touch instead of waiting for the next daemon-startup/upgrade one-shot
+ * (RUSH-2435). Only `ag-`-prefixed (run-wrapped) sessions are touched; a no-op
+ * for anything else. Best-effort — never throws, so a repair failure can never
+ * block the attach it is protecting.
+ */
+export declare function ensureSessionHookRepaired(name: string, socket?: string): Promise<void>;
 /**
  * List live sessions on the socket. Reconciles meta JSONs against tmux's view:
  *  - tmux session with no meta → returned without `meta` (external session)
@@ -277,6 +292,7 @@ export declare function reconcileSessionHooks(socket?: string): Promise<{
  */
 export declare function listSessions(opts?: {
     socket?: string;
+    timeoutMs?: number;
 }): Promise<ListedSession[]>;
 export interface SplitOptions {
     name: string;