@phnx-labs/agents-cli 1.22.35 → 1.22.38

package/dist/lib/deeplink/register.d.ts

@@ -0,0 +1,49 @@
+export declare const AGENTS_URL_SCHEME = "agents";
+export declare const MAC_BUNDLE_ID = "dev.agents.urlhandler";
+export interface SchemeStatus {
+    registered: boolean;
+    platform: NodeJS.Platform;
+    /** One human line: where the handler is, or why it is not registered. */
+    detail: string;
+}
+/**
+ * POSIX single-quote a path so a space or metacharacter in it can never break
+ * out of the handler command.
+ */
+export declare function shQuote(p: string): string;
+/**
+ * Resolve how the OS handler should invoke this CLI, as an already-quoted
+ * command prefix (without the `open <url>` suffix).
+ *
+ * A macOS GUI app does NOT inherit the shell PATH, so the handler must use an
+ * absolute path. Prefer the `agents` shim on PATH (directly executable); fall
+ * back to `<node> <entry>` for a bare JS install.
+ */
+export declare function resolveAgentsInvocation(platform?: NodeJS.Platform): string;
+/** The freedesktop `.desktop` entry that claims `x-scheme-handler/agents`. */
+export declare function linuxDesktopEntry(invocation: string): string;
+/**
+ * AppleScript whose `on open location` handler fires when macOS routes an
+ * `agents://` URL to the app. `quoted form of` makes the URL a single safe
+ * shell argument — the URL is never concatenated unquoted.
+ */
+export declare function macAppleScriptSource(invocation: string): string;
+/** PlistBuddy commands that add the `agents` URL type to a compiled app's Info.plist. */
+export declare function macPlistBuddyCommands(plistPath: string): string[][];
+/** `reg add` argv lists that register the scheme under HKCU on Windows. */
+export declare function windowsRegistryCommands(invocation: string): string[][];
+export declare function linuxDesktopPath(home?: string): string;
+export declare function macAppPath(home?: string): string;
+/** Whether the handler artifact exists on disk (a cheap, side-effect-free check). */
+export declare function agentsUrlSchemeStatus(platform?: NodeJS.Platform, home?: string): SchemeStatus;
+export interface RegisterOptions {
+    platform?: NodeJS.Platform;
+    home?: string;
+    /** Skip if already present (used by best-effort callers like setup). */
+    ifMissing?: boolean;
+}
+export declare function registerAgentsUrlScheme(opts?: RegisterOptions): SchemeStatus;
+export declare function unregisterAgentsUrlScheme(opts?: {
+    platform?: NodeJS.Platform;
+    home?: string;
+}): SchemeStatus;

package/dist/lib/deeplink/register.js

@@ -0,0 +1,253 @@
+/**
+ * Register the `agents://` URL scheme with the OS so a click in an artifact
+ * routes to `agents open <url>` (see url.ts + commands/open.ts).
+ *
+ * A browser page cannot spawn a shell; a registered URL scheme is the
+ * OS-sanctioned hand-off. Each platform gets its own handler:
+ *   - Linux:   a `.desktop` entry claiming `x-scheme-handler/agents`, made the
+ *              default via `xdg-mime`.
+ *   - macOS:   a tiny AppleScript app whose `on open location` runs the CLI;
+ *              its Info.plist declares the `agents` scheme, registered with
+ *              LaunchServices via `lsregister`.
+ *   - Windows: `HKCU\Software\Classes\agents` shell-open-command registry keys.
+ *
+ * The content generators below are pure and unit-tested. The `register*` /
+ * `unregister*` / `status*` functions apply them and never throw — they return a
+ * {@link SchemeStatus} so callers (setup, `agents open register`, doctor) can
+ * report without a try/catch.
+ */
+import { execFileSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { getAgentsBinPath } from '../cli-entry.js';
+export const AGENTS_URL_SCHEME = 'agents';
+export const MAC_BUNDLE_ID = 'dev.agents.urlhandler';
+const LINUX_DESKTOP_FILE = 'agents-url-handler.desktop';
+const MAC_APP_NAME = 'AgentsURLHandler.app';
+// ---------------------------------------------------------------------------
+// Invocation resolution — the absolute command the handler runs.
+// ---------------------------------------------------------------------------
+/**
+ * POSIX single-quote a path so a space or metacharacter in it can never break
+ * out of the handler command.
+ */
+export function shQuote(p) {
+    return `'${p.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * Resolve how the OS handler should invoke this CLI, as an already-quoted
+ * command prefix (without the `open <url>` suffix).
+ *
+ * A macOS GUI app does NOT inherit the shell PATH, so the handler must use an
+ * absolute path. Prefer the `agents` shim on PATH (directly executable); fall
+ * back to `<node> <entry>` for a bare JS install.
+ */
+export function resolveAgentsInvocation(platform = os.platform()) {
+    const onPath = whichAgents(platform);
+    if (onPath)
+        return platform === 'win32' ? `"${onPath}"` : shQuote(onPath);
+    const entry = getAgentsBinPath();
+    if (platform === 'win32')
+        return `"${process.execPath}" "${entry}"`;
+    return `${shQuote(process.execPath)} ${shQuote(entry)}`;
+}
+function whichAgents(platform) {
+    try {
+        const cmd = platform === 'win32' ? 'where' : 'which';
+        const out = execFileSync(cmd, ['agents'], { encoding: 'utf8' }).trim();
+        const first = out.split(/\r?\n/)[0]?.trim();
+        return first && fs.existsSync(first) ? first : null;
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Pure content generators (unit-tested).
+// ---------------------------------------------------------------------------
+/** The freedesktop `.desktop` entry that claims `x-scheme-handler/agents`. */
+export function linuxDesktopEntry(invocation) {
+    return [
+        '[Desktop Entry]',
+        'Type=Application',
+        'Name=Agents URL Handler',
+        'Comment=Resume an agents session from an agents:// deep link',
+        `Exec=${invocation} open %u`,
+        'Terminal=false',
+        'NoDisplay=true',
+        'MimeType=x-scheme-handler/agents;',
+        '',
+    ].join('\n');
+}
+/**
+ * AppleScript whose `on open location` handler fires when macOS routes an
+ * `agents://` URL to the app. `quoted form of` makes the URL a single safe
+ * shell argument — the URL is never concatenated unquoted.
+ */
+export function macAppleScriptSource(invocation) {
+    // Escape the (already shell-quoted) invocation for an AppleScript double-quoted
+    // string literal, so a `"` or `\` in the install path cannot break osacompile.
+    const literal = invocation.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+    return [
+        'on open location this_URL',
+        `\tdo shell script "${literal} open " & quoted form of this_URL`,
+        'end open location',
+    ].join('\n');
+}
+/** PlistBuddy commands that add the `agents` URL type to a compiled app's Info.plist. */
+export function macPlistBuddyCommands(plistPath) {
+    const b = ['/usr/libexec/PlistBuddy', '-c'];
+    return [
+        [...b, 'Add :CFBundleIdentifier string ' + MAC_BUNDLE_ID, plistPath],
+        [...b, 'Add :CFBundleURLTypes array', plistPath],
+        [...b, 'Add :CFBundleURLTypes:0 dict', plistPath],
+        [...b, 'Add :CFBundleURLTypes:0:CFBundleURLName string ' + MAC_BUNDLE_ID, plistPath],
+        [...b, 'Add :CFBundleURLTypes:0:CFBundleURLSchemes array', plistPath],
+        [...b, `Add :CFBundleURLTypes:0:CFBundleURLSchemes:0 string ${AGENTS_URL_SCHEME}`, plistPath],
+    ];
+}
+/** `reg add` argv lists that register the scheme under HKCU on Windows. */
+export function windowsRegistryCommands(invocation) {
+    const base = 'HKCU\\Software\\Classes\\agents';
+    return [
+        ['add', base, '/ve', '/d', 'URL:agents Protocol', '/f'],
+        ['add', base, '/v', 'URL Protocol', '/d', '', '/f'],
+        ['add', `${base}\\shell\\open\\command`, '/ve', '/d', `${invocation} open "%1"`, '/f'],
+    ];
+}
+// ---------------------------------------------------------------------------
+// Paths.
+// ---------------------------------------------------------------------------
+export function linuxDesktopPath(home = os.homedir()) {
+    return path.join(home, '.local', 'share', 'applications', LINUX_DESKTOP_FILE);
+}
+export function macAppPath(home = os.homedir()) {
+    return path.join(home, 'Applications', MAC_APP_NAME);
+}
+// ---------------------------------------------------------------------------
+// Status.
+// ---------------------------------------------------------------------------
+/** Whether the handler artifact exists on disk (a cheap, side-effect-free check). */
+export function agentsUrlSchemeStatus(platform = os.platform(), home = os.homedir()) {
+    if (platform === 'linux') {
+        const p = linuxDesktopPath(home);
+        return fs.existsSync(p)
+            ? { registered: true, platform, detail: `handler: ${p}` }
+            : { registered: false, platform, detail: `no handler (${p}) — run: agents open register` };
+    }
+    if (platform === 'darwin') {
+        const p = macAppPath(home);
+        return fs.existsSync(p)
+            ? { registered: true, platform, detail: `handler: ${p}` }
+            : { registered: false, platform, detail: `no handler (${p}) — run: agents open register` };
+    }
+    if (platform === 'win32') {
+        const ok = windowsSchemeRegistered();
+        return ok
+            ? { registered: true, platform, detail: 'handler: HKCU\\Software\\Classes\\agents' }
+            : { registered: false, platform, detail: 'no handler — run: agents open register' };
+    }
+    return { registered: false, platform, detail: `unsupported platform: ${platform}` };
+}
+function windowsSchemeRegistered() {
+    try {
+        execFileSync('reg', ['query', 'HKCU\\Software\\Classes\\agents\\shell\\open\\command'], { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function registerAgentsUrlScheme(opts = {}) {
+    const platform = opts.platform ?? os.platform();
+    const home = opts.home ?? os.homedir();
+    if (opts.ifMissing && agentsUrlSchemeStatus(platform, home).registered) {
+        return agentsUrlSchemeStatus(platform, home);
+    }
+    try {
+        if (platform === 'linux')
+            return registerLinux(home);
+        if (platform === 'darwin')
+            return registerMac(home);
+        if (platform === 'win32')
+            return registerWindows(platform);
+        return { registered: false, platform, detail: `unsupported platform: ${platform}` };
+    }
+    catch (err) {
+        return { registered: false, platform, detail: `registration failed: ${err.message}` };
+    }
+}
+export function unregisterAgentsUrlScheme(opts = {}) {
+    const platform = opts.platform ?? os.platform();
+    const home = opts.home ?? os.homedir();
+    try {
+        if (platform === 'linux') {
+            fs.rmSync(linuxDesktopPath(home), { force: true });
+            run('update-desktop-database', [path.dirname(linuxDesktopPath(home))], true);
+            return { registered: false, platform, detail: 'handler removed' };
+        }
+        if (platform === 'darwin') {
+            fs.rmSync(macAppPath(home), { recursive: true, force: true });
+            return { registered: false, platform, detail: 'handler removed' };
+        }
+        if (platform === 'win32') {
+            run('reg', ['delete', 'HKCU\\Software\\Classes\\agents', '/f'], true);
+            return { registered: false, platform, detail: 'handler removed' };
+        }
+        return { registered: false, platform, detail: `unsupported platform: ${platform}` };
+    }
+    catch (err) {
+        return { registered: agentsUrlSchemeStatus(platform, home).registered, platform, detail: `removal failed: ${err.message}` };
+    }
+}
+function registerLinux(home) {
+    const invocation = resolveAgentsInvocation('linux');
+    const dest = linuxDesktopPath(home);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.writeFileSync(dest, linuxDesktopEntry(invocation), 'utf8');
+    // Make it the default handler for the scheme; best-effort DB refresh.
+    run('xdg-mime', ['default', LINUX_DESKTOP_FILE, 'x-scheme-handler/agents'], true);
+    run('update-desktop-database', [path.dirname(dest)], true);
+    return { registered: true, platform: 'linux', detail: `handler: ${dest}` };
+}
+function registerMac(home) {
+    const invocation = resolveAgentsInvocation('darwin');
+    const app = macAppPath(home);
+    fs.mkdirSync(path.dirname(app), { recursive: true });
+    fs.rmSync(app, { recursive: true, force: true });
+    // Compile the AppleScript into an .app, then inject the URL scheme into its plist.
+    const scriptFile = path.join(os.tmpdir(), `agents-url-handler-${process.pid}.applescript`);
+    fs.writeFileSync(scriptFile, macAppleScriptSource(invocation), 'utf8');
+    try {
+        run('osacompile', ['-o', app, scriptFile], false);
+    }
+    finally {
+        fs.rmSync(scriptFile, { force: true });
+    }
+    const plist = path.join(app, 'Contents', 'Info.plist');
+    // Non-optional: if the URL type is not written, the scheme is never claimed —
+    // registerAgentsUrlScheme must report failure, not a false "registered".
+    for (const cmd of macPlistBuddyCommands(plist))
+        run(cmd[0], cmd.slice(1), false);
+    // Register with LaunchServices so the scheme resolves without a reboot.
+    const lsregister = '/System/Library/Frameworks/CoreServices.framework/Versions/A/Frameworks/LaunchServices.framework/Versions/A/Support/lsregister';
+    run(lsregister, ['-f', app], true);
+    return { registered: true, platform: 'darwin', detail: `handler: ${app}` };
+}
+function registerWindows(platform) {
+    const invocation = resolveAgentsInvocation('win32');
+    for (const args of windowsRegistryCommands(invocation))
+        run('reg', args, false);
+    return { registered: true, platform, detail: 'handler: HKCU\\Software\\Classes\\agents' };
+}
+/** Run a helper command. `optional` swallows failures (best-effort DB refreshes). */
+function run(cmd, args, optional) {
+    try {
+        execFileSync(cmd, args, { stdio: 'ignore' });
+    }
+    catch (err) {
+        if (!optional)
+            throw err;
+    }
+}

package/dist/lib/deeplink/url.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Parse the `agents://` deep-link scheme.
+ *
+ * A rendered artifact (a plan or report) embeds `agents://session/<id>` in its
+ * provenance line. Clicking it hands the URL to the OS, which routes it to the
+ * registered handler (see register.ts) that runs `agents open <url>`. This module
+ * turns that URL into a validated {@link AgentsSessionLink} the resume dispatcher
+ * consumes.
+ *
+ * Parsing is deliberately strict: the session id is the only thing that ever
+ * reaches a child process, and the `open` command passes it as argv (never
+ * interpolated into a shell), so a hostile URL cannot inject a command. Anything
+ * that is not `agents://session/<valid-id>` is rejected with a reason.
+ *
+ * URL shape:
+ *   agents://session/<id>              — resume <id>, owner host resolved from the id
+ *   agents://session/<id>?host=<name>  — the same, with a routing hint
+ */
+export interface AgentsSessionLink {
+    kind: 'session';
+    /** The session id (or short-id/alias) to resume. */
+    id: string;
+    /** Optional owning-host hint; resume self-resolves the owner from the id regardless. */
+    host?: string;
+}
+export interface AgentsUrlError {
+    error: string;
+}
+export declare function isDeepLinkSessionId(raw: string): boolean;
+/**
+ * Parse an `agents://…` URL into a {@link AgentsSessionLink}, or return an
+ * {@link AgentsUrlError} with a human reason. Never throws.
+ */
+export declare function parseAgentsUrl(input: string): AgentsSessionLink | AgentsUrlError;

package/dist/lib/deeplink/url.js

@@ -0,0 +1,78 @@
+/**
+ * Parse the `agents://` deep-link scheme.
+ *
+ * A rendered artifact (a plan or report) embeds `agents://session/<id>` in its
+ * provenance line. Clicking it hands the URL to the OS, which routes it to the
+ * registered handler (see register.ts) that runs `agents open <url>`. This module
+ * turns that URL into a validated {@link AgentsSessionLink} the resume dispatcher
+ * consumes.
+ *
+ * Parsing is deliberately strict: the session id is the only thing that ever
+ * reaches a child process, and the `open` command passes it as argv (never
+ * interpolated into a shell), so a hostile URL cannot inject a command. Anything
+ * that is not `agents://session/<valid-id>` is rejected with a reason.
+ *
+ * URL shape:
+ *   agents://session/<id>              — resume <id>, owner host resolved from the id
+ *   agents://session/<id>?host=<name>  — the same, with a routing hint
+ */
+/**
+ * Session-id shapes accepted from a deep link. Mirrors `looksLikeSessionId`
+ * (lib/session/discover.ts) WITHOUT importing the heavy session module, so the
+ * `open` command stays cold-start cheap: a bare hex short-id/prefix (>=6 chars),
+ * a UUID (optionally `session_`-prefixed), a `ses_<ulid>` (OpenCode), or an
+ * `ag-…-<8hex>` tmux alias. The upper length bound is a sanity cap, not a format
+ * rule.
+ */
+const HEX_ID = /^[0-9a-f-]{6,}$/i;
+const SES_ULID = /^ses_[0-9a-hjkmnp-tv-z]{26}$/i;
+import { AG_TMUX_NAME_RE as AG_ALIAS } from '../session/types.js';
+const HOST_HINT = /^[a-z0-9][a-z0-9._-]{0,63}$/i;
+export function isDeepLinkSessionId(raw) {
+    const id = (raw ?? '').trim();
+    if (!id || id.length > 128)
+        return false;
+    const bare = id.replace(/^session_/i, '');
+    return HEX_ID.test(bare) || SES_ULID.test(id) || AG_ALIAS.test(id);
+}
+/**
+ * Parse an `agents://…` URL into a {@link AgentsSessionLink}, or return an
+ * {@link AgentsUrlError} with a human reason. Never throws.
+ */
+export function parseAgentsUrl(input) {
+    const raw = (input ?? '').trim();
+    if (!raw)
+        return { error: 'empty URL' };
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return { error: `not a URL: ${truncate(raw)}` };
+    }
+    if (url.protocol !== 'agents:') {
+        return { error: `unsupported scheme: ${url.protocol}// (expected agents://)` };
+    }
+    // agents://session/<id> → hostname="session", pathname="/<id>". The authority
+    // is compared case-insensitively because some browsers normalize its casing.
+    const verb = url.hostname.toLowerCase();
+    if (verb !== 'session') {
+        return { error: `unknown agents:// target "${verb || '(none)'}" (expected agents://session/<id>)` };
+    }
+    let id;
+    try {
+        id = decodeURIComponent(url.pathname.replace(/^\/+/, '')).trim();
+    }
+    catch {
+        return { error: 'malformed session id encoding' };
+    }
+    if (!isDeepLinkSessionId(id)) {
+        return { error: `invalid session id: ${truncate(id) || '(none)'}` };
+    }
+    const hostParam = url.searchParams.get('host')?.trim();
+    const host = hostParam && HOST_HINT.test(hostParam) ? hostParam : undefined;
+    return host ? { kind: 'session', id, host } : { kind: 'session', id };
+}
+function truncate(s, max = 60) {
+    return s.length > max ? `${s.slice(0, max)}…` : s;
+}

package/dist/lib/device-config.d.ts

@@ -1,46 +1,84 @@
 /**
- * Device/user config keys — typed read/write over the two-tier agents.yaml store.
+ * Device/user config keys — typed read/write over the central agents.yaml store.
  *
  * One registry (`CONFIG_KEYS`) maps each CLI dotted name to where it lives:
- *   - user scope   → central `~/.agents/agents.yaml` under `config:` (syncs
- *                    fleet-wide via `agents repo push/pull`)
- *   - device scope → `~/.agents/devices/<host>/agents.yaml` under `config:`
- *                    (per-machine; mirrors how `defaultBrowserProfile` is routed)
+ *   - user scope     → central `~/.agents/agents.yaml` under `config:` (syncs
+ *                      fleet-wide via `agents repo push/pull`)
+ *   - device scope   → split by `visibility`, which asks WHO READS IT:
+ *       · `shared`   → central `fleet.devices.<name>.config`, because a PEER
+ *                      reads it (the ssh keys and platform to dial the box,
+ *                      agents.max-concurrent for placement, auto-launch and
+ *                      notes for fleet views). Names and non-secret values only
+ *                      (a secrets-bundle NAME is fine; a credential never is).
+ *       · `machine`  → the owning box's own doc, never the shared file, because
+ *                      nothing off-box reads it (browser.profile,
+ *                      browser.remote-control, scheduler.enabled,
+ *                      daemon.enabled).
  *
- * This machine's keys go through the readMeta/updateMeta funnel (state.ts) so the
- * partition/overlay logic stays the single writer. Another device's doc is
- * read/written in place — the devices/ tree syncs via the DotAgents repo, so
- * editing `devices/mac-mini/agents.yaml` locally is how `configure`/`note`
- * target a peer (`--device`-style).
+ * That split exists because "central for everything" put 13 machines on one
+ * tracked path and they stopped being able to pull. `browser.remote-control` is
+ * also a consent flag — syncing one box's opt-in to the rest was a security bug,
+ * not just churn.
  *
- * `browser.profile` is NOT a `config:` key — it is the existing
- * `Meta.defaultBrowserProfile` field; the registry entry documents the mapping
- * and set/get route to it so there is one source of truth (no duplicate key).
+ * The device registry (`~/.agents/.history/devices/registry.json`) stays the
+ * DISCOVERY cache (address, tailscale snapshot, reachability); the profile
+ * fields config can override (ssh.*, platform, user) are overlaid onto it at
+ * read time by `lib/devices/resolve-profile.ts`.
  *
- * Unset always means today's behavior.
+ * Legacy stores (per-device `devices/<host>/agents.yaml` config and
+ * `.history/devices/auto-launch.json`) are folded into the central block once
+ * by `lib/devices/config-migration.ts`, invoked on the first read/write in a
+ * process — after migration there is ONE read path, no fallback branches.
+ *
+ * Unset always means today's behavior (the documented default).
  */
 /** Which tier of the agents.yaml store a key lives in. */
 export type ConfigScope = 'user' | 'device';
+/**
+ * For a device-scope key: WHO READS IT, which is what decides where it is stored.
+ *
+ * - `shared`  — a PEER reads it, so it must be visible fleet-wide and lives in the
+ *   tracked `fleet.devices.<name>.config`. `ssh.*` and `platform` are the
+ *   load-bearing cases: machine A resolves them to build the ssh target for B
+ *   (`lib/devices/resolve-profile.ts`), so it cannot ask B for them.
+ * - `machine` — only the owning box ever reads it, so it belongs in that box's
+ *   own gitignored doc and must never reach the fleet-shared file. Storing these
+ *   centrally is what makes 13 machines write one tracked path.
+ *
+ * Declaring this is MANDATORY for a device-scope key — the union below makes
+ * omitting it a compile error, mirroring how `META_KEY_SCOPE` (lib/state.ts) uses
+ * an exhaustive `Record<keyof Meta, ...>`. Before this, a new key picked its home
+ * by hand with no signal, which is how operator config drifted into the shared
+ * file twice.
+ */
+export type ConfigVisibility = 'shared' | 'machine';
 /** Value type of a config key — drives validation and `--json` rendering. */
 export type ConfigType = 'string' | 'int' | 'bool' | 'string-list';
-/** One known config key. */
-export interface ConfigKeySpec {
+/** Fields every key carries, regardless of scope. */
+interface ConfigKeySpecBase {
     /** CLI dotted name, e.g. `interactive.host`. */
     name: string;
-    /** camelCase key under the YAML `config:` block. */
+    /** camelCase key under the YAML config block. */
     yamlKey: string;
-    scope: ConfigScope;
     type: ConfigType;
     /** One-line description for help/list output. */
     description: string;
-    /**
-     * When set, the value lives in this top-level Meta field instead of the
-     * `config:` block (only `browser.profile` → `defaultBrowserProfile` today).
-     */
-    field?: 'defaultBrowserProfile';
+    /** The effective value when the key is unset (bool keys; drives the interactive menu's default). */
+    defaultValue?: unknown;
     /** Extra validation beyond the type check; return an error string or null. */
     validate?: (value: unknown) => string | null;
 }
+/**
+ * One known config key. A device-scope key MUST declare its `visibility`; a
+ * user-scope key has none (it is fleet-wide by definition).
+ */
+export type ConfigKeySpec = (ConfigKeySpecBase & {
+    scope: 'user';
+    visibility?: never;
+}) | (ConfigKeySpecBase & {
+    scope: 'device';
+    visibility: ConfigVisibility;
+});
 /** A key with its resolved value and the layer that set it. */
 export interface ConfigEntry {
     spec: ConfigKeySpec;
@@ -49,22 +87,78 @@ export interface ConfigEntry {
     /** Which layer set it; undefined when unset. */
     layer?: ConfigScope;
 }
-/** Options scoping a read/write to a specific device's doc (default: this machine). */
+/** Options scoping a read/write to a specific device (default: this machine). */
 export interface ConfigTarget {
     device?: string;
 }
 export declare const CONFIG_KEYS: readonly ConfigKeySpec[];
 /** Look up a key spec by CLI dotted name, or throw listing the known keys. */
 export declare function configKeySpec(name: string): ConfigKeySpec;
+/**
+ * Fold the legacy per-device config stores into the central block, once per
+ * process. A failure is loud but non-fatal — config reads must keep working,
+ * and the next process retries the fold. Honors AGENTS_SKIP_MIGRATION=1, the
+ * same gate bootstrap's runMigration uses (tests pin it so a fork never folds
+ * the developer's real ~/.agents as a side effect).
+ *
+ * Call this ONLY from a lifecycle entry point (daemon boot, `runMigration`).
+ * It must never hang off a config read or write: `~/.agents/agents.yaml` is a
+ * tracked file shared by every machine in the fleet, so a migration on the read
+ * path means an ordinary `agents config get` can dirty the shared file. That is
+ * what left yosemite-s0 unable to pull — 13 machines each rewriting one tracked
+ * path, on nearly every command.
+ */
+export declare function ensureDeviceConfigMigrated(): void;
+/**
+ * The raw device-scope config block for `device` from the central
+ * `fleet.devices.<name>.config` map ({} when unset). This is the single read
+ * path post-migration — the profile resolver (`lib/devices/resolve-profile.ts`)
+ * goes through here. Deliberately does NOT auto-trigger the migration: it
+ * serves the hot dial/render paths, and the keys it resolves (ssh.*, platform)
+ * are new — they never existed in the legacy stores. Keys with legacy data are
+ * read through the public API below, which triggers the fold.
+ */
+export declare function readDeviceConfigValues(device: string): Record<string, unknown>;
 /** Get one config key's value and the layer that set it. */
 export declare function getConfigValue(name: string, opts?: ConfigTarget): ConfigEntry;
-/** List every known key with its value and the layer that set it. */
+/**
+ * List every known key with its value and the layer that set it.
+ *
+ * Listing a PEER omits its machine-local keys rather than throwing. Their values
+ * live in that box's own doc and are genuinely unknowable from here, but a bulk
+ * listing must not hard-fail because one key in the registry is unreadable —
+ * `agents devices config <peer>` should still show everything it CAN resolve.
+ * Asking for such a key by name still errors, with the `agents ssh` fix named.
+ */
 export declare function listConfig(opts?: ConfigTarget): ConfigEntry[];
+/** List user-scope config keys with their values. Used to show inherited settings
+ * in per-device views without implying those keys are device-local. */
+export declare function listUserConfig(): ConfigEntry[];
+/** Resolve the explicit usage host, falling back to the user's interactive host. */
+export declare function resolveUsagePrimaryHost(): string | null;
 /** Set a config key (validated). Device-scope keys target this machine unless `opts.device` names a peer. */
 export declare function setConfigValue(name: string, value: unknown, opts?: ConfigTarget): void;
 /** Unset a config key — restores default behavior. No-op when already unset. */
 export declare function unsetConfigValue(name: string, opts?: ConfigTarget): void;
-/** True unless this machine's device doc disables the routines scheduler. */
+/** A device's auto-launch flags, as read by the ext's launch ranking. */
+export interface AutoLaunchPreference {
+    enabled?: boolean;
+    preferred?: boolean;
+}
+/** True if the device is enabled for auto-launch. Unset defaults to true. */
+export declare function isAutoLaunchEnabled(name: string): boolean;
+/** Set whether a device is enabled for auto-launch. Setting the default
+ * (enabled) removes the key to keep the block minimal. */
+export declare function setAutoLaunchEnabled(name: string, enabled: boolean): void;
+/** True if the device is preferred for auto-launch ranking. */
+export declare function isAutoLaunchPreferred(name: string): boolean;
+/** Set whether a device is preferred for auto-launch. Setting the default
+ * (not preferred) removes the key to keep the block minimal. */
+export declare function setAutoLaunchPreferred(name: string, preferred: boolean): void;
+/** Every device's auto-launch flags, keyed by device name (set flags only) —
+ * the shape the ext's launch ranking consumes. */
+export declare function loadAutoLaunchPreferences(): Record<string, AutoLaunchPreference>;
+/** True unless this machine's config disables the routines scheduler. */
 export declare function isSchedulerEnabled(): boolean;
 /**
  * Throw when the routines scheduler is disabled on this machine, naming the
@@ -73,7 +167,7 @@ export declare function isSchedulerEnabled(): boolean;
  * scheduler init) refuses with.
  */
 export declare function assertSchedulerEnabled(): void;
-/** True unless this machine's device doc disables the daemon outright (top-level kill switch). */
+/** True unless this machine's config disables the daemon outright (top-level kill switch). */
 export declare function isDaemonEnabled(): boolean;
 /**
  * Throw when the daemon is disabled on this machine, naming the setting and
@@ -84,9 +178,10 @@ export declare function isDaemonEnabled(): boolean;
  */
 export declare function assertDaemonEnabled(): void;
 /**
- * Read the `agents.max-concurrent` cap for each named device from its synced
- * device doc (no SSH). Devices without a cap are omitted — uncapped is the
+ * Read the `agents.max-concurrent` cap for each named device from the central
+ * config block (no SSH). Devices without a cap are omitted — uncapped is the
  * default. Used as an input to host ranking (teams placement, Factory
  * auto-launch), never as a remote probe.
  */
 export declare function readMaxConcurrentCaps(devices: string[]): Record<string, number>;
+export {};