@phnx-labs/agents-cli 1.22.113 → 1.22.115

package/dist/lib/installations/migrate.js

@@ -1871,7 +1871,7 @@ export function migrateRoutineRemoteCwdToCwd(routinesDir) {
  * `resume`) makes it ready. Never materializes a device manifest that does not
  * yet exist, and never touches command routines (they run in the target home).
  */
-export function pauseUnreadyEnabledRoutines() {
+function pauseUnreadyEnabledRoutines() {
     const enabled = enabledRoutineNames();
     if (enabled === null)
         return; // no manifest yet — nothing activated to pause

package/dist/lib/installations/shims.d.ts

@@ -358,7 +358,7 @@ export declare function listShimFileNames(): string[];
 /**
  * Prune a stale, orphaned shim: one that is NOT a managed agent shim and NOT a user
  * alias, whose baked `AGENTS_BIN` points at an install that no longer exists. These
- * are `exec "$AGENTS_BIN" <cmd>` command shims (browser/sessions/pty/teams) that
+ * are `exec "$AGENTS_BIN" <cmd>` command shims (browser/teams) that
  * `scripts/postinstall.js` writes for the LIVE install; one baked at a removed
  * install either dies with `exit 127` or shadows the real package bin on PATH.
  * Only removed when the baked target is gone, so a working shim is never touched —

package/dist/lib/installations/shims.js

@@ -2197,11 +2197,11 @@ export function listShimFileNames() {
  * `computer` bin of its own: a machine that installed an older CLI has a real
  * shim on PATH under the name the standalone engine now owns.
  */
-const LEGACY_SHIMS_ALWAYS_PRUNED = new Set(['secrets', 'sessions', 'computer']);
+const LEGACY_SHIMS_ALWAYS_PRUNED = new Set(['secrets', 'sessions', 'computer', 'pty']);
 /**
  * Prune a stale, orphaned shim: one that is NOT a managed agent shim and NOT a user
  * alias, whose baked `AGENTS_BIN` points at an install that no longer exists. These
- * are `exec "$AGENTS_BIN" <cmd>` command shims (browser/sessions/pty/teams) that
+ * are `exec "$AGENTS_BIN" <cmd>` command shims (browser/teams) that
  * `scripts/postinstall.js` writes for the LIVE install; one baked at a removed
  * install either dies with `exit 127` or shadows the real package bin on PATH.
  * Only removed when the baked target is gone, so a working shim is never touched —

package/dist/lib/installations/update-runtime.js

@@ -299,7 +299,7 @@ async function runAutoUpdatePassUntilCancelled(opts, cancelled) {
             // (`ensureShimCurrent`/`ensureVersionedAliasCurrent`). Deliberately
             // NEVER `adoptShadowingLauncher`: that seizes a launcher this pass does
             // not own (a user's own PATH entry, or another install's), and is an
-            // operator-triggered `doctor --fix` action, not something an unattended
+            // operator-triggered `agents sync` action, not something an unattended
             // background pass may do on its own. Real-pass-only, same reason as the
             // migration above — a `--check` preview must not touch PATH or a
             // config-dir symlink.

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

@@ -42,7 +42,7 @@ export declare const LINEAR_CACHE_TTL_MS: number;
  */
 export declare function resolveLinearApiKey(): string | null;
 /** What a lookup found, and how much to trust it. */
-export interface CacheHit<T> {
+interface CacheHit<T> {
     value: T;
     /** Age in ms. Past the TTL the value is still returned, flagged stale. */
     ageMs: number;
@@ -68,3 +68,4 @@ export declare function parseRateLimitReset(header: string | null, nowMs: number
  * `resetAtMs` comes from {@link parseRateLimitReset}; without it, back off one TTL.
  */
 export declare function noteRateLimited(resetAtMs: number | undefined, nowMs: number): void;
+export {};

package/dist/lib/linux-userns.d.ts

@@ -13,7 +13,7 @@ export interface UsernsStatus {
     reason?: string;
 }
 /** The raw signals the pure interpreter reasons over. */
-export interface UsernsInputs {
+interface UsernsInputs {
     platform: NodeJS.Platform;
     /**
      * Contents of {@link APPARMOR_USERNS_SYSCTL_PATH} trimmed, or null when the
@@ -54,5 +54,4 @@ export declare function probeUnshare(): 'ok' | 'denied' | 'no-tool';
  * short-circuits to `ok` without spawning anything.
  */
 export declare function probeUnprivilegedUserns(platform?: NodeJS.Platform): UsernsStatus;
-/** Test-only: drop the process cache so a test can re-probe. */
-export declare function resetUsernsCacheForTests(): void;
+export {};

package/dist/lib/linux-userns.js

@@ -110,7 +110,3 @@ export function probeUnprivilegedUserns(platform = process.platform) {
     });
     return cached;
 }
-/** Test-only: drop the process cache so a test can re-probe. */
-export function resetUsernsCacheForTests() {
-    cached = null;
-}

package/dist/lib/loop.d.ts

@@ -40,7 +40,7 @@ export interface LoopSignal {
 /** Why the loop stopped. Mirrors the teams supervisor exit reasons. */
 export type LoopStoppedBy = 'condition-met' | 'budget' | 'stalled' | 'max' | 'signal' | 'error';
 /** Result of a loop run. */
-export interface LoopResult {
+interface LoopResult {
     /** Iterations actually executed. */
     iterations: number;
     stoppedBy: LoopStoppedBy;
@@ -152,3 +152,4 @@ export declare function defaultRunIteration(options: ExecOptions): Promise<Itera
  *   - `error`         — an iteration threw or exited non-zero.
  */
 export declare function runLoop(execOptions: ExecOptions, loop: LoopConfig, ctx: LoopContext, deps?: LoopDeps): Promise<LoopResult>;
+export {};

package/dist/lib/mailbox-gc.d.ts

@@ -6,7 +6,7 @@ export interface GcResult {
     consumedPruned: number;
     blocksRemoved: number;
 }
-export interface GcOptions {
+interface GcOptions {
     root?: string;
     /** Feed store root. Defaults to getFeedDir(). */
     feedRoot?: string;
@@ -20,3 +20,4 @@ export interface GcOptions {
  * mailbox. For live boxes, drop expired messages and prune old consumed files.
  */
 export declare function gcMailbox(activeBoxIds: Set<string>, options?: GcOptions): GcResult;
+export {};

package/dist/lib/mailbox-target.d.ts

@@ -6,7 +6,7 @@
  */
 import type { ActiveSession } from './session/active.js';
 import type { HostTask } from './hosts/tasks.js';
-export type MessageResolution = {
+type MessageResolution = {
     kind: 'cloud';
     id: string;
 } | {
@@ -61,3 +61,4 @@ export type HostTaskRoute = {
  * latter.
  */
 export declare function decideHostTaskRoute(task: HostTask | null, target: string): HostTaskRoute;
+export {};

package/dist/lib/mailbox.d.ts

@@ -2,12 +2,6 @@
 export declare const DEFAULT_TTL_SECONDS: number;
 /** Env var that overrides {@link DEFAULT_TTL_SECONDS} with a duration like "24h" or "3600". */
 export declare const MAILBOX_TTL_ENV = "AGENTS_MAILBOX_TTL";
-/**
- * Resolve the default mailbox TTL in seconds. Honors `AGENTS_MAILBOX_TTL`
- * (parsed by {@link parseDuration}); falls back to 24h. A malformed env value
- * fails loud instead of silently disabling expiry.
- */
-export declare function resolveDefaultTtlSeconds(): number;
 /** A single mailbox message. `text` may embed `host:/path` clip tokens. */
 export interface MailboxMessage {
     /** Unique, time-sortable id. Also the on-disk filename stem. */

package/dist/lib/mailbox.js

@@ -30,7 +30,7 @@ export const MAILBOX_TTL_ENV = 'AGENTS_MAILBOX_TTL';
  * (parsed by {@link parseDuration}); falls back to 24h. A malformed env value
  * fails loud instead of silently disabling expiry.
  */
-export function resolveDefaultTtlSeconds() {
+function resolveDefaultTtlSeconds() {
     const raw = process.env[MAILBOX_TTL_ENV];
     if (raw == null || raw === '')
         return DEFAULT_TTL_SECONDS;

package/dist/lib/manifest.d.ts

@@ -1,20 +1,6 @@
 import type { Manifest } from './types.js';
 /** Canonical filename for the manifest in any agents repo or project root. */
 export declare const MANIFEST_FILENAME = "agents.yaml";
-/** Parse a YAML string into a typed Manifest object. */
-export declare function parseManifest(content: string): Manifest;
-/**
- * Serialize a Manifest to YAML WITHOUT destroying hand-written comments.
- *
- * Plain `yaml.stringify(manifest)` drops every comment, so `agents mcp add`
- * (and every other writeManifest caller) used to clobber annotations in
- * agents.yaml. Matching `serializeCentral` in state.ts: when existing file
- * text is provided, parse it into a `yaml.Document` (comments + key order
- * preserved) and edit only keys that actually changed. Untouched keys and
- * their comments stay byte-stable. Falls back to plain stringify when there
- * is no existing document yet.
- */
-export declare function serializeManifest(manifest: Manifest, existingContent?: string | null): string;
 /** Read and parse agents.yaml from a directory. Returns null if the file does not exist. */
 export declare function readManifest(repoPath: string): Manifest | null;
 /** Write a Manifest object to agents.yaml in the given directory. */

package/dist/lib/manifest.js

@@ -14,7 +14,7 @@ export const MANIFEST_FILENAME = 'agents.yaml';
 // Per-path re-entrancy depth so withManifestLock is safe against recursive calls.
 const manifestLockDepth = new Map();
 /** Parse a YAML string into a typed Manifest object. */
-export function parseManifest(content) {
+function parseManifest(content) {
     return yaml.parse(content);
 }
 /**
@@ -28,7 +28,7 @@ export function parseManifest(content) {
  * their comments stay byte-stable. Falls back to plain stringify when there
  * is no existing document yet.
  */
-export function serializeManifest(manifest, existingContent) {
+function serializeManifest(manifest, existingContent) {
     const entries = Object.entries(manifest).filter(([, v]) => v !== undefined);
     const isEmpty = entries.length === 0;
     if (existingContent == null || existingContent.trim() === '') {

package/dist/lib/mcp-registry.d.ts

@@ -19,7 +19,7 @@ export type McpFormat =
 /** `{ schema_version, mcp_servers: { "<name>": {transport, ..., enabled} } }` */
  | 'muse-json';
 /** The complete MCP contract for one agent. */
-export interface McpTarget {
+interface McpTarget {
     /** MCP config file under a HOME root (a version home, or the real HOME). */
     home(home: string): string;
     /** Project-scoped MCP config file for a repo at `cwd`. */
@@ -60,3 +60,4 @@ export declare function mcpTarget(agent: AgentId): McpTarget | undefined;
  * MCP-capable, or a hard-deprecated id), or it has one with `format: null`.
  */
 export declare function mcpWriteUnsupportedReason(agent: AgentId): string | null;
+export {};

package/dist/lib/mcp.js

@@ -380,25 +380,31 @@ function installMcpViaClaude(binaryPath, server, versionHome) {
  * Uses: codex mcp add <name> -- <cmd> [args...]
  */
 function installMcpViaCodex(binaryPath, server, versionHome) {
-    if (server.config.transport === 'stdio') {
+    let args;
+    if (server.config.transport === 'http') {
+        if (!server.config.url)
+            throw new Error(`HTTP MCP '${server.name}' has no url`);
+        // codex mcp add <name> --url <url>
+        args = ['mcp', 'add', server.name, '--url', server.config.url];
+    }
+    else {
         // codex mcp add -- <name> <cmd> [args...]
-        const args = [
+        args = [
             'mcp', 'add',
             '--',
             server.name,
             server.config.command,
             ...(server.config.args || [])
         ];
-        // RUSH-1752: user-controlled MCP command/args must not reach cmd.exe unquoted.
-        const spec = execFileShellSpec(binaryPath, args);
-        execFileSync(spec.command, spec.args, {
-            stdio: 'pipe',
-            timeout: 30000,
-            env: { ...process.env, HOME: versionHome },
-            shell: spec.shell,
-        });
     }
-    // Note: Codex may not support HTTP MCPs
+    // RUSH-1752: user-controlled MCP command/args must not reach cmd.exe unquoted.
+    const spec = execFileShellSpec(binaryPath, args);
+    execFileSync(spec.command, spec.args, {
+        stdio: 'pipe',
+        timeout: 30000,
+        env: { ...process.env, HOME: versionHome },
+        shell: spec.shell,
+    });
 }
 export async function registerMcpCommandToTargets(targets, name, commandSpec, scope = 'user', transport = 'stdio') {
     const results = [];

package/dist/lib/memory.d.ts

@@ -12,7 +12,7 @@
  * target dir (see memoryTargetDir).
  */
 import type { AgentId } from './types.js';
-export interface MemoryFact {
+interface MemoryFact {
     /** Filename without .md (slug). */
     name: string;
     /** Absolute path to the fact file. */
@@ -22,20 +22,10 @@ export interface MemoryFact {
     /** First non-empty line of the body (for list display). */
     summary: string;
 }
-export interface MemoryLayerDir {
-    layer: 'project' | 'user' | 'system';
-    dir: string;
-}
 /** User-layer memory root (~/.agents/memory/). */
 export declare function getUserMemoryDir(): string;
-/** System-layer memory root (~/.agents/.system/memory/). */
-export declare function getSystemMemoryDir(): string;
-/** Project-layer memory root when a project agents dir exists. */
-export declare function getProjectMemoryDir(cwd?: string): string | null;
 /** Ensure the user memory dir exists (creates MEMORY.md index if missing). */
 export declare function ensureUserMemoryDir(): string;
-/** Layer dirs highest-priority first. */
-export declare function getMemoryLayerDirs(cwd?: string): MemoryLayerDir[];
 /** List memory facts with project > user > system override on name. */
 export declare function listMemoryFacts(cwd?: string): MemoryFact[];
 /** Read one fact by name (winning layer). */
@@ -44,8 +34,6 @@ export declare function readMemoryFact(name: string, cwd?: string): MemoryFact |
 export declare function addMemoryFact(name: string, body: string): string;
 /** Remove a fact from the user layer. Returns true if a file was deleted. */
 export declare function removeMemoryFact(name: string): boolean;
-/** Rebuild MEMORY.md index from sibling fact files in a single layer dir. */
-export declare function rebuildMemoryIndex(dir: string): void;
 /**
  * Per-agent target directory (relative to version home) for synced memory.
  * Claude/Codex/OpenClaw/Grok get native-ish paths; others get a generic memory/.
@@ -79,3 +67,4 @@ export declare function getClaudeProjectMemoryDir(cwd: string): string;
  * being replaced by the symlink.
  */
 export declare function syncClaudeProjectMemoryDir(versionHome: string, cwd?: string): void;
+export {};

package/dist/lib/memory.js

@@ -22,11 +22,11 @@ export function getUserMemoryDir() {
     return path.join(getUserAgentsDir(), 'memory');
 }
 /** System-layer memory root (~/.agents/.system/memory/). */
-export function getSystemMemoryDir() {
+function getSystemMemoryDir() {
     return path.join(getSystemAgentsDir(), 'memory');
 }
 /** Project-layer memory root when a project agents dir exists. */
-export function getProjectMemoryDir(cwd = process.cwd()) {
+function getProjectMemoryDir(cwd = process.cwd()) {
     const project = getProjectAgentsDir(cwd);
     return project ? path.join(project, 'memory') : null;
 }
@@ -69,7 +69,7 @@ function summarize(content) {
     return '(empty)';
 }
 /** Layer dirs highest-priority first. */
-export function getMemoryLayerDirs(cwd = process.cwd()) {
+function getMemoryLayerDirs(cwd = process.cwd()) {
     const out = [];
     const project = getProjectMemoryDir(cwd);
     if (project && fs.existsSync(project))
@@ -157,7 +157,7 @@ export function removeMemoryFact(name) {
     return true;
 }
 /** Rebuild MEMORY.md index from sibling fact files in a single layer dir. */
-export function rebuildMemoryIndex(dir) {
+function rebuildMemoryIndex(dir) {
     let facts = [];
     try {
         facts = fs.readdirSync(dir).filter(isFactFile).sort();

package/dist/lib/menubar/download-menubar.d.ts

@@ -38,8 +38,6 @@ export declare function menubarHelperAssetUrls(version: string): {
 };
 /** Cache dir for the downloaded menu-bar helper, one subdir per release tag. */
 export declare function menubarHelperCacheDir(version: string): string;
-/** Verify a menu-bar helper `.app`: codesign + Team + DR pin + notarization. */
-export declare function verifyMenubarHelper(appPath: string): void;
 /**
  * Download the menu-bar helper release asset for `version`, verify sha256 +
  * signature + DR pin, and return the path to the extracted `MenubarHelper.app`

package/dist/lib/menubar/download-menubar.js

@@ -20,7 +20,7 @@
  * before the bundle is ever installed. This matches the release-time gate in
  * `scripts/verify-menubar-helper.sh`.
  */
-import { EXPECTED_TEAM_ID, downloadHelperApp, helperAssetUrls, helperCacheDir, verifyHelperApp, } from '../helper-download.js';
+import { EXPECTED_TEAM_ID, downloadHelperApp, helperAssetUrls, helperCacheDir } from '../helper-download.js';
 /** The zipped `.app` release asset name. */
 export const MENUBAR_HELPER_ASSET = 'MenubarHelper.app.zip';
 /** The bundle directory name once extracted. */
@@ -50,10 +50,6 @@ export function menubarHelperAssetUrls(version) {
 export function menubarHelperCacheDir(version) {
     return helperCacheDir(MENUBAR_HELPER_SPEC, version);
 }
-/** Verify a menu-bar helper `.app`: codesign + Team + DR pin + notarization. */
-export function verifyMenubarHelper(appPath) {
-    verifyHelperApp(appPath, MENUBAR_HELPER_SPEC);
-}
 /**
  * Download the menu-bar helper release asset for `version`, verify sha256 +
  * signature + DR pin, and return the path to the extracted `MenubarHelper.app`

package/dist/lib/menubar/install-menubar.d.ts

@@ -45,7 +45,7 @@ export declare function serviceLabel(): string;
  */
 /** Version label for a bundle that has none of its own (a local dev build). */
 export declare const LOCAL_BUILD_LABEL = "local";
-export type MenubarStamp = {
+type MenubarStamp = {
     source: 'release';
     helperVersion: string;
 } | {
@@ -64,10 +64,6 @@ export type MenubarStamp = {
  * package, or a dev checkout without a built bundle).
  */
 export declare function resolveInstalledMenubarExecutable(): string | null;
-/** True if the user explicitly disabled the menu bar (don't auto-enable on upgrade). */
-export declare function menubarDisabledByUser(): boolean;
-/** True if the launchd plist for the menu-bar service is installed. */
-export declare function menubarServiceInstalled(): boolean;
 /** Where a downloaded copy of the floor release sits once fetched and verified. */
 export declare function cachedFloorBundlePath(): string;
 /**
@@ -76,14 +72,6 @@ export declare function cachedFloorBundlePath(): string;
  * The startup self-heal installs from here, network-free.
  */
 export declare function cachedReleaseBundlePath(): string;
-/**
- * The release version an explicit install should fetch: the newest published
- * build, but never below what this Mac already runs — a release deleted after
- * it was installed must not roll the helper back through `setup`/`enable`.
- */
-export declare function menubarVersionToInstall(opts?: {
-    force?: boolean;
-}): Promise<string>;
 /** True when the bundle carries a signature the kernel will accept at launch. */
 export declare function codesignVerifies(appPath: string): boolean;
 /**
@@ -526,7 +514,7 @@ export declare function isMenubarProcessStaleAgainstBundle(pidStartedAtMs: numbe
  */
 export declare function buildMenubarDoctorReport(): MenubarDoctorReport;
 /** Outcome of one auto-update pass (`updateMenubarHelperIfNewer`). */
-export interface MenubarUpdateResult {
+interface MenubarUpdateResult {
     outcome: 'updated' | 'current' | 'skipped' | 'failed';
     installed: string | null;
     available: string;
@@ -567,3 +555,4 @@ export declare function updateMenubarHelperIfNewer(opts?: {
     dryRun?: boolean;
     force?: boolean;
 }): Promise<MenubarUpdateResult>;
+export {};

package/dist/lib/menubar/install-menubar.js

@@ -155,11 +155,11 @@ function disabledSentinelPath() {
     return path.join(getRuntimeStateDir(), 'menubar.disabled');
 }
 /** True if the user explicitly disabled the menu bar (don't auto-enable on upgrade). */
-export function menubarDisabledByUser() {
+function menubarDisabledByUser() {
     return fs.existsSync(disabledSentinelPath());
 }
 /** True if the launchd plist for the menu-bar service is installed. */
-export function menubarServiceInstalled() {
+function menubarServiceInstalled() {
     return onDarwin() && fs.existsSync(servicePlistPath());
 }
 /**
@@ -238,7 +238,7 @@ export function cachedReleaseBundlePath() {
  * build, but never below what this Mac already runs — a release deleted after
  * it was installed must not roll the helper back through `setup`/`enable`.
  */
-export async function menubarVersionToInstall(opts = {}) {
+async function menubarVersionToInstall(opts = {}) {
     const resolved = await resolveMenubarVersion({ force: opts.force });
     const installed = readInstalledMenubarStamp();
     if (installed?.source === 'release' && compareVersions(installed.helperVersion, resolved) > 0)

package/dist/lib/menubar/migrate-prefs.d.ts

@@ -0,0 +1,53 @@
+/**
+ * One-time, CLI-owned migration of AGI Menu preferences from the macOS
+ * UserDefaults domain `com.phnx-labs.agents-menubar` into the registered
+ * `menubar.menu.*` config keys (PHNX-3999).
+ *
+ * Why here: before the preferences became `agents config` keys, the stable menu
+ * bar stored them in its own UserDefaults. A user upgrading must keep those
+ * settings, but the CLI is now the single source of truth and syncs fleet-wide,
+ * so the values are lifted into config ONCE and then owned there.
+ *
+ * The rules (from the integration contract) are all fail-safe:
+ *   - macOS only. On any other platform this is a no-op (Linux derives canonical
+ *     config only).
+ *   - The PRODUCTION domain only — never the dev bundle
+ *     `com.phnx-labs.agents-menubar.dev` (we simply never read it).
+ *   - Import only KNOWN keys ({@link MENUBAR_MENU_PROPERTIES}) that are still
+ *     UNSET in config — an already-set (synced) value is never overridden.
+ *   - One-shot, gated by a sentinel, so a later `agents config unset` cannot
+ *     resurrect the legacy value on the next run.
+ *
+ * The stable app stores each preference under its FULL `menubar.menu.*` key name
+ * (the Swift MenuPreferences local-cache key), so the migration matches on the
+ * full name. If a key is stored under a different name, it simply is not matched
+ * and the migration stays a safe no-op for it. The read uses `defaults export
+ * <domain> -` piped through `plutil` (NOT `defaults read <domain> -json`, which
+ * treats `-json` as a key and errors).
+ */
+/**
+ * Pure plan step: which UserDefaults entries should be imported. The stable app
+ * stores each preference under its FULL `menubar.menu.*` key name (the Swift
+ * MenuPreferences local-cache key), so we match on the full name — only known
+ * keys that are present in `userDefaults` AND currently unset in config
+ * (`isUnset`) are imported, so an already-set value is preserved. Values are
+ * returned raw; the caller coerces + validates them against each key's spec.
+ */
+export declare function planMenubarPrefMigration(userDefaults: Record<string, unknown>, isUnset: (fullName: string) => boolean): Array<{
+    name: string;
+    value: unknown;
+}>;
+/**
+ * Coerce a raw UserDefaults value to the type its config key expects. The
+ * `plutil` scalar output is text, but a bool can arrive as
+ * 0/1 or "true"/"false" and an int as a numeric string, so normalize before
+ * validation. Returns undefined for a value that cannot be coerced (skipped,
+ * never forced).
+ */
+export declare function coerceMenubarPrefValue(name: string, raw: unknown): unknown;
+/**
+ * Run the one-shot migration. macOS only, gated by the sentinel, best-effort:
+ * any failure is swallowed (a migration must never break the snapshot read that
+ * calls it) and a failed read remains eligible for a later retry.
+ */
+export declare function migrateMenubarPreferencesFromUserDefaults(): void;

package/dist/lib/menubar/migrate-prefs.js

@@ -0,0 +1,168 @@
+/**
+ * One-time, CLI-owned migration of AGI Menu preferences from the macOS
+ * UserDefaults domain `com.phnx-labs.agents-menubar` into the registered
+ * `menubar.menu.*` config keys (PHNX-3999).
+ *
+ * Why here: before the preferences became `agents config` keys, the stable menu
+ * bar stored them in its own UserDefaults. A user upgrading must keep those
+ * settings, but the CLI is now the single source of truth and syncs fleet-wide,
+ * so the values are lifted into config ONCE and then owned there.
+ *
+ * The rules (from the integration contract) are all fail-safe:
+ *   - macOS only. On any other platform this is a no-op (Linux derives canonical
+ *     config only).
+ *   - The PRODUCTION domain only — never the dev bundle
+ *     `com.phnx-labs.agents-menubar.dev` (we simply never read it).
+ *   - Import only KNOWN keys ({@link MENUBAR_MENU_PROPERTIES}) that are still
+ *     UNSET in config — an already-set (synced) value is never overridden.
+ *   - One-shot, gated by a sentinel, so a later `agents config unset` cannot
+ *     resurrect the legacy value on the next run.
+ *
+ * The stable app stores each preference under its FULL `menubar.menu.*` key name
+ * (the Swift MenuPreferences local-cache key), so the migration matches on the
+ * full name. If a key is stored under a different name, it simply is not matched
+ * and the migration stays a safe no-op for it. The read uses `defaults export
+ * <domain> -` piped through `plutil` (NOT `defaults read <domain> -json`, which
+ * treats `-json` as a key and errors).
+ */
+import { execFileSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import { assertValidValue, configKeySpec, getConfigValue, setConfigValue } from '../device-config.js';
+import { getRuntimeStateDir } from '../state.js';
+import { MENUBAR_MENU_PROPERTIES } from '../config-keys.js';
+/** The production menu-bar UserDefaults domain (NOT the `.dev` bundle). */
+const USER_DEFAULTS_DOMAIN = 'com.phnx-labs.agents-menubar';
+/** Sentinel marking the one-shot done; its presence blocks every later run. */
+function sentinelPath() {
+    return path.join(getRuntimeStateDir(), 'menubar-prefs-migrated');
+}
+/**
+ * Pure plan step: which UserDefaults entries should be imported. The stable app
+ * stores each preference under its FULL `menubar.menu.*` key name (the Swift
+ * MenuPreferences local-cache key), so we match on the full name — only known
+ * keys that are present in `userDefaults` AND currently unset in config
+ * (`isUnset`) are imported, so an already-set value is preserved. Values are
+ * returned raw; the caller coerces + validates them against each key's spec.
+ */
+export function planMenubarPrefMigration(userDefaults, isUnset) {
+    const plan = [];
+    for (const prop of MENUBAR_MENU_PROPERTIES) {
+        const name = `menubar.menu.${prop}`;
+        if (!(name in userDefaults))
+            continue;
+        if (!isUnset(name))
+            continue;
+        plan.push({ name, value: userDefaults[name] });
+    }
+    return plan;
+}
+/**
+ * Coerce a raw UserDefaults value to the type its config key expects. The
+ * `plutil` scalar output is text, but a bool can arrive as
+ * 0/1 or "true"/"false" and an int as a numeric string, so normalize before
+ * validation. Returns undefined for a value that cannot be coerced (skipped,
+ * never forced).
+ */
+export function coerceMenubarPrefValue(name, raw) {
+    const type = configKeySpec(name).type;
+    if (type === 'bool') {
+        if (typeof raw === 'boolean')
+            return raw;
+        if (raw === 1 || raw === '1' || raw === 'true' || raw === 'YES')
+            return true;
+        if (raw === 0 || raw === '0' || raw === 'false' || raw === 'NO')
+            return false;
+        return undefined;
+    }
+    if (type === 'int') {
+        if (typeof raw === 'number' && Number.isInteger(raw))
+            return raw;
+        if (typeof raw === 'string' && /^\d+$/.test(raw.trim()))
+            return Number.parseInt(raw.trim(), 10);
+        return undefined;
+    }
+    return typeof raw === 'string' ? raw : undefined;
+}
+/**
+ * Read known scalar preferences from the production domain.
+ *
+ * `defaults read <domain> -json` does NOT exist — `defaults read` treats `-json`
+ * as a KEY name and errors. The correct read is `defaults export <domain> -`,
+ * which writes the domain's plist to stdout (an EMPTY plist, exit 0, when the
+ * domain is absent — a legitimate "nothing to migrate"), read one known scalar key at a time with `plutil -extract … raw`. Other
+ * defaults may contain dates or data that cannot be represented as JSON.
+ *
+ * Returns `{ ok }` so the caller can tell a genuine read/convert FAILURE (do not
+ * write the sentinel — retry next run) from an ABSENT domain (ok, empty values —
+ * mark done). A failure never fabricates an empty map.
+ */
+function readUserDefaultsDomain() {
+    try {
+        const plist = execFileSync('defaults', ['export', USER_DEFAULTS_DOMAIN, '-'], {
+            encoding: 'utf8', timeout: 5_000,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        const values = {};
+        for (const property of MENUBAR_MENU_PROPERTIES) {
+            const key = `menubar.menu.${property}`;
+            try {
+                values[key] = execFileSync('plutil', ['-extract', key.replaceAll('.', '\\.'), 'raw', '-o', '-', '-'], {
+                    input: plist, encoding: 'utf8', timeout: 5_000, stdio: ['pipe', 'pipe', 'ignore'],
+                }).trimEnd();
+            }
+            catch {
+                // Missing or non-scalar legacy keys are outside the preference contract.
+            }
+        }
+        return { ok: true, values };
+    }
+    catch {
+        // `defaults`/`plutil` missing, a non-zero exit, or malformed output — a real
+        // failure. Do NOT claim an empty domain; the caller must retry.
+        return { ok: false, values: {} };
+    }
+}
+/**
+ * Run the one-shot migration. macOS only, gated by the sentinel, best-effort:
+ * any failure is swallowed (a migration must never break the snapshot read that
+ * calls it) and a failed read remains eligible for a later retry.
+ */
+export function migrateMenubarPreferencesFromUserDefaults() {
+    if (process.platform !== 'darwin')
+        return;
+    const sentinel = sentinelPath();
+    if (fs.existsSync(sentinel))
+        return;
+    const { ok, values } = readUserDefaultsDomain();
+    // A genuine read/convert failure must NOT mark the migration done — retry on a
+    // later run rather than silently skipping the user's real settings forever. An
+    // ABSENT domain reads ok with empty values and legitimately marks done.
+    if (!ok)
+        return;
+    try {
+        const plan = planMenubarPrefMigration(values, (name) => getConfigValue(name).value === undefined);
+        for (const { name, value } of plan) {
+            const coerced = coerceMenubarPrefValue(name, value);
+            if (coerced === undefined)
+                continue; // unrepresentable — skip, never force
+            try {
+                assertValidValue(configKeySpec(name), coerced);
+            }
+            catch {
+                continue;
+            }
+            setConfigValue(name, coerced);
+        }
+    }
+    catch {
+        return;
+    }
+    try {
+        fs.mkdirSync(path.dirname(sentinel), { recursive: true });
+        fs.writeFileSync(sentinel, new Date().toISOString() + '\n');
+    }
+    catch {
+        /* if we cannot mark it, a later run retries — still safe (idempotent) */
+    }
+}