@phnx-labs/agents-cli 1.22.43 → 1.22.44

package/dist/lib/hosts/registry.js

@@ -24,7 +24,7 @@ import { normalizeHost } from '../machine-id.js';
 import { readMeta } from '../state.js';
 import { isSshConfigHost } from './ssh-config.js';
 import { resolveRemoteOsSync } from './remote-os.js';
-import { loadDevices, isControlDevice } from '../devices/registry.js';
+import { loadDevices } from '../devices/registry.js';
 import { resolveDeviceProfile } from '../devices/resolve-profile.js';
 import { isDeviceAuto, resolveDeviceAffinity } from '../smart-launch.js';
 import { localMachineId } from '../session/origin-machine.js';
@@ -148,7 +148,7 @@ function literalHost(token, host, user) {
  * all resolve the same way regardless of which subcommand called.
  *
  * Non-throwing: returns null on an injection-guard failure or an unresolved bare
- * token. Device-only refusals (control device, password auth) are NOT applied
+ * token. The device-only refusal (password auth) is NOT applied
  * here — that is the dispatch wrapper's job ({@link resolveHost}), so the fan-out
  * and `agents ssh` paths, which handle those cases differently, aren't forced
  * into a dispatch verdict.
@@ -240,8 +240,7 @@ export async function listAllHosts() {
  * caller consumes (`run --device`, the generic passthrough, teams placement, the
  * cloud host provider, doctor, funnel, remote secrets). Grammar and merge come
  * from {@link matchHost}; on top, this layer applies the device-only dispatch
- * refusals so they hold even when an inline overlay shadows the device:
- *   - a control device (a paired iPhone) can never be a dispatch target;
+ * refusal so it holds even when an inline overlay shadows the device:
  *   - a password-auth device throws the typed {@link DeviceOffloadUnsupportedError}
  *     (offload rides `BatchMode=yes` ssh, which can't answer a prompt);
  *   - an addressless device has nothing to dial.
@@ -254,9 +253,6 @@ export async function resolveHost(name) {
     if (!host)
         return null;
     if (host.device) {
-        if (isControlDevice(host.device)) {
-            throw new Error(`Device "${host.device.name}" is a control device (a cockpit), not an executor — it can't run agents. Dispatch to a worker device instead.`);
-        }
         if (host.device.auth.method === 'password') {
             throw new DeviceOffloadUnsupportedError(host.device.name);
         }

package/dist/lib/installations/versions.js

@@ -2491,6 +2491,10 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
     const commandsAlsoAsSkills = shouldAlsoInstallCommandAsSkill(agent, version);
     const commandsInstallAsSkills = commandsAsSkills || commandsAlsoAsSkills;
     let writtenCommands = [];
+    // Artifact paths the writers report (WriteResult.paths), persisted to the
+    // manifest as `writtenTargets` after a full sync so isStale can flag a
+    // deleted artifact as stale (#2398).
+    const writtenTargets = [];
     if (commandsToSync.length > 0 && commandsWriter) {
         // Agents that replace native command files with skills (codex >= 0.117.0,
         // kimi) must have their legacy command dir removed, or files written by an
@@ -2503,6 +2507,8 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
         }
         const r = commandsWriter.write({ version, versionHome, selection: commandsToSync, cwd });
         writtenCommands = r.synced;
+        if (r.paths)
+            writtenTargets.push(...r.paths);
         result.commands = r.synced.length > 0;
     }
     // Orphan-sweep stale top-level command files from previous syncs under a
@@ -2510,8 +2516,9 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
     // not pass an explicit `selection`. Callers that pass explicit selections
     // are using the incremental/additive API (sync exactly these; leave others
     // alone), so the sweep would be a contract violation there. The
-    // cross-project leak always comes from the no-selection shim auto-sync at
-    // launch.
+    // cross-project leak comes from no-selection full syncs run under different
+    // cwds (`agents sync` / `agents refresh`; the shim's `agents sync --launch`
+    // skips version-home reconciliation and never reaches this path).
     if (!userPassedSelection && commandsWriter && !shouldInstallCommandAsSkill(agent, version)) {
         const commandsTargetSweep = path.join(agentDir, agentConfig.commandsSubdir);
         if (fs.existsSync(commandsTargetSweep)) {
@@ -2570,6 +2577,8 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
     else if (skillsWriter) {
         if (skillsToSync.length > 0) {
             const r = skillsWriter.write({ version, versionHome, selection: skillsToSync, cwd });
+            if (r.paths)
+                writtenTargets.push(...r.paths);
             result.skills = r.synced.length > 0;
         }
         // Orphan-sweep stale skill directories from previous syncs under a
@@ -2625,6 +2634,8 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
                         }
                     }
                 }
+                if (r.paths)
+                    writtenTargets.push(...r.paths);
                 result.hooks = r.synced.length > 0;
                 hookManifest = selectHookManifest(parseHookManifest(), hooksToSync);
             }
@@ -2651,6 +2662,8 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
                 : null;
             const preset = overridePreset || activeRulesPreset() || getActiveRulesPreset(agent, version);
             const r = rulesWriter.write({ version, versionHome, selection: { preset }, cwd });
+            if (r.paths)
+                writtenTargets.push(...r.paths);
             result.memory.push(...r.synced);
             // rulesPreset is tracked separately via setActiveRulesPreset.
         }
@@ -2728,6 +2741,8 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
     const mcpToSync = mcpToSyncAll.filter(n => !untrustedProjectMcpNames.has(n));
     if (mcpToSync.length > 0 && mcpWriter) {
         const r = mcpWriter.write({ version, versionHome, selection: mcpToSync, cwd });
+        if (r.paths)
+            writtenTargets.push(...r.paths);
         result.mcp = r.synced;
         if (r.errors?.length)
             result.declined.push(...r.errors.map((e) => `mcp: ${e}`));
@@ -2749,6 +2764,8 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
     }
     if (subagentsToSync.length > 0 && subagentsWriter) {
         const r = subagentsWriter.write({ version, versionHome, selection: subagentsToSync, cwd });
+        if (r.paths)
+            writtenTargets.push(...r.paths);
         result.subagents.push(...r.synced);
         // Orphan-sweep for Claude only — see comment on commands/skills sweep
         // for the no-selection guard. OpenClaw stores subagents as siblings of
@@ -2855,6 +2872,8 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
         const previous = loadManifest(agent, version);
         const manifest = buildSyncManifest(agent, version, cwd, previous);
         manifest.writtenCommands = writtenCommands;
+        // Deduped + sorted so repeated full syncs write byte-identical manifests.
+        manifest.writtenTargets = Array.from(new Set(writtenTargets)).sort();
         saveManifest(agent, version, manifest);
     }
     return result;

package/dist/lib/menubar/MenubarHelper.app/Contents/Info.plist

@@ -7,11 +7,7 @@
     <key>CFBundleIdentifier</key>
     <string>com.phnx-labs.agents-menubar</string>
     <key>CFBundleName</key>
-    <string>AGI Menu</string>
-    <key>CFBundleDisplayName</key>
-    <string>AGI Menu</string>
-    <key>CFBundleIconFile</key>
-    <string>AppIcon</string>
+    <string>Agents Menu Bar</string>
     <key>CFBundlePackageType</key>
     <string>APPL</string>
     <key>CFBundleShortVersionString</key>

package/dist/lib/menubar/MenubarHelper.app/Contents/_CodeSignature/CodeResources

@@ -3,22 +3,9 @@
 <plist version="1.0">
 <dict>
 	<key>files</key>
-	<dict>
-		<key>Resources/AppIcon.icns</key>
-		<data>
-		jOjZVimcFRHoP2VPzgn8uM8mjkA=
-		</data>
-	</dict>
+	<dict/>
 	<key>files2</key>
-	<dict>
-		<key>Resources/AppIcon.icns</key>
-		<dict>
-			<key>hash2</key>
-			<data>
-			GFvSLeNYJ3ASxW3OzcuiB4aID0gZUBkpozmWZkbTFNw=
-			</data>
-		</dict>
-	</dict>
+	<dict/>
 	<key>rules</key>
 	<dict>
 		<key>^Resources/</key>

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

@@ -75,6 +75,33 @@ export declare function generateServicePlist(execPath: string): string;
 export declare function restartMenubarLaunchAgent(uid: number, plist: string, exec?: (cmd: string, args: readonly string[], opts: {
     stdio: ['ignore', 'ignore', 'ignore'];
 }) => Buffer): void;
+/**
+ * Force a running helper off the binary that was just swapped underneath it.
+ *
+ * `installMenubarLaunchAgentOnUpgrade()` calls this after a heal actually
+ * replaces the on-disk bundle (a version bump or the ad-hoc -> Developer ID
+ * transition — see `menubarHealReplacedBundle`). `restartMenubarLaunchAgent`
+ * (run moments earlier via `installAndStartService`) already attempts
+ * bootout+bootstrap+kickstart, but that targets the GUI launchd domain and
+ * fails silently — `launchctl kickstart -k gui/<uid>/<label>` prints "Could not
+ * find service ... in domain for user gui" — from a shell with no Aqua session,
+ * which is the ordinary case for `agents` invoked from a terminal/tmux/ssh
+ * session rather than literally the login item (verified live). When that
+ * happens the plist and on-disk bundle are current but the LIVE process is
+ * still the old binary, so it requests Accessibility under the OLD code
+ * identity and the grant never sticks.
+ *
+ * `kickstart -k` (force-restart, unlike the bare kickstart already tried) is
+ * attempted first since it is the clean launchd-native path when it works. If
+ * launchd has no record of the service in this context either, fall back to
+ * ending the specific pid(s) already confirmed to be running the installed
+ * bundle (`ownProcesses`, resolved by the caller via `liveMenubarProcesses`) —
+ * never a broad pkill. The launchd plist has `KeepAlive=true`, so the ended
+ * process is relaunched from the swapped binary within seconds.
+ */
+export declare function restartMenubarHelperAfterSwap(uid: number, ownProcesses: readonly MenubarProcess[], exec?: (cmd: string, args: readonly string[], opts: {
+    stdio: ['ignore', 'ignore', 'ignore'];
+}) => Buffer, kill?: (pid: number) => void): void;
 /**
  * Install + start the menu-bar helper as a launchd user service (idempotent).
  * Clears the sticky opt-out, installs the .app, writes the plist, and
@@ -97,6 +124,23 @@ export declare function isMenubarStale(opts: {
     currentVersion: string;
     execExists: boolean;
 }): boolean;
+/**
+ * Pure decision (no I/O): did THIS heal actually replace bundle content a live
+ * process could be running stale, as opposed to a plist-only repoint?
+ *
+ * `stale` (version bump or missing exec) and `needsDevIdHeal` (ad-hoc ->
+ * Developer ID) both mean the shipped `.app` differs from what is already
+ * installed — the exact condition under which a running helper can be left on
+ * an old code identity after `enableMenubarService` swaps the bundle. A
+ * repoint-only heal (`menubarSetupNeedsRepoint()` alone, same version, same
+ * signing identity) does NOT count: RUSH-3005 already owns the churn from
+ * mixed-Node-interpreter repoints, and restarting the helper on every one of
+ * those would double that churn rather than fix this bug.
+ */
+export declare function menubarHealReplacedBundle(opts: {
+    stale: boolean;
+    needsDevIdHeal: boolean;
+}): boolean;
 /**
  * Pure re-point decision (no I/O): the plist's baked interpreter/entry no longer
  * match the install that is now running `agents`. This catches DUAL-INSTALL skew
@@ -110,6 +154,7 @@ export declare function isMenubarStale(opts: {
 export declare function menubarPlistNeedsRepoint(opts: {
     plistEntry: string | null;
     plistNode: string | null;
+    plistNodeExists: boolean;
     activeEntry: string | null;
     activeNode: string | null;
 }): boolean;
@@ -185,6 +230,31 @@ export declare function mayInstallMenubarHelper(opts: {
  * throws into startup.
  */
 export declare function installMenubarLaunchAgentOnUpgrade(): void;
+/**
+ * Pure decision (no I/O): run the one-time `tccutil reset Accessibility` only
+ * on a real ad-hoc -> Developer ID transition, and only once ever. A machine
+ * that was always Developer ID never accumulated a dead TCC row under an
+ * ad-hoc identity, so resetting there would just force a needless re-prompt;
+ * a machine that already migrated must not be reset again on every heal.
+ */
+export declare function shouldMigrateMenubarTcc(opts: {
+    needsDevIdHeal: boolean;
+    alreadyMigrated: boolean;
+}): boolean;
+/**
+ * Reset the stale Accessibility grant TCC recorded against the pre-migration
+ * ad-hoc identity, then stamp the marker so this never runs again on this
+ * machine. Targets `SERVICE_LABEL_BASE` — the bundle's actual
+ * `CFBundleIdentifier`/codesign `--identifier` (menubar/scripts/build.sh) that
+ * TCC keys grants to — not the namespaced `serviceLabel()`, which exists only
+ * to keep launchd job labels apart under a redirected HOME (RUSH-2639) and is
+ * never the app's real identity. Best-effort: a missing/failing `tccutil`
+ * (older macOS, a sandboxed test HOME) must never block the heal that just
+ * fixed the signing identity itself.
+ */
+export declare function resetMenubarAccessibilityTcc(exec?: (cmd: string, args: readonly string[], opts: {
+    stdio: ['ignore', 'ignore', 'ignore'];
+}) => Buffer): void;
 /** One step of `agents menubar setup`, and how it came out. */
 export interface SetupStep {
     /** What was configured. */
@@ -272,3 +342,42 @@ export interface MenubarStatus {
     disabledByUser: boolean;
 }
 export declare function getMenubarStatus(): MenubarStatus;
+/** Read-only diagnostic for `agents menubar doctor` — probes, never mutates. */
+export interface MenubarDoctorReport {
+    platform: string;
+    installPath: string | null;
+    installedVersion: string | null;
+    currentVersion: string;
+    versionMatches: boolean;
+    /** `unknown` on non-darwin or when nothing is installed to inspect. */
+    signingIdentity: 'developer-id' | 'ad-hoc' | 'unknown';
+    running: boolean;
+    /** A live helper pid started before the installed bundle's on-disk mtime —
+     *  it is running the binary that has since been swapped underneath it. */
+    staleRunningProcess: PidStaleness[];
+    /** Grant likely needs to be re-made: an ad-hoc identity breaks on every
+     *  update, or a live process is confirmed to predate the current bundle. */
+    accessibilityHintNeeded: boolean;
+}
+/** One live pid checked against the bundle's on-disk mtime. */
+export interface PidStaleness {
+    pid: number;
+    stale: boolean;
+}
+/**
+ * Pure comparison (no I/O) behind the stale-process check: a helper pid that
+ * started before the bundle on disk was last written is still running the
+ * PREVIOUS binary — the exact condition `restartMenubarHelperAfterSwap` exists
+ * to fix. Millisecond epoch timestamps in, so the truth table is unit-testable
+ * without a live process or filesystem.
+ */
+export declare function isMenubarProcessStaleAgainstBundle(pidStartedAtMs: number, bundleMtimeMs: number): boolean;
+/**
+ * `agents menubar doctor` — everything a human needs to tell "why did
+ * Accessibility ask again" apart from "the helper is genuinely broken":
+ * install path, version skew, whether the signing identity is update-stable,
+ * and whether a live process predates the bundle it's supposed to be running.
+ * Read-only: no install, no restart, no TCC reset — `agents menubar setup`
+ * remains the command that fixes what this reports.
+ */
+export declare function buildMenubarDoctorReport(): MenubarDoctorReport;

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

@@ -353,6 +353,45 @@ export function restartMenubarLaunchAgent(uid, plist, exec = execFileSync) {
     }
     catch { /* best effort */ }
 }
+/**
+ * Force a running helper off the binary that was just swapped underneath it.
+ *
+ * `installMenubarLaunchAgentOnUpgrade()` calls this after a heal actually
+ * replaces the on-disk bundle (a version bump or the ad-hoc -> Developer ID
+ * transition — see `menubarHealReplacedBundle`). `restartMenubarLaunchAgent`
+ * (run moments earlier via `installAndStartService`) already attempts
+ * bootout+bootstrap+kickstart, but that targets the GUI launchd domain and
+ * fails silently — `launchctl kickstart -k gui/<uid>/<label>` prints "Could not
+ * find service ... in domain for user gui" — from a shell with no Aqua session,
+ * which is the ordinary case for `agents` invoked from a terminal/tmux/ssh
+ * session rather than literally the login item (verified live). When that
+ * happens the plist and on-disk bundle are current but the LIVE process is
+ * still the old binary, so it requests Accessibility under the OLD code
+ * identity and the grant never sticks.
+ *
+ * `kickstart -k` (force-restart, unlike the bare kickstart already tried) is
+ * attempted first since it is the clean launchd-native path when it works. If
+ * launchd has no record of the service in this context either, fall back to
+ * ending the specific pid(s) already confirmed to be running the installed
+ * bundle (`ownProcesses`, resolved by the caller via `liveMenubarProcesses`) —
+ * never a broad pkill. The launchd plist has `KeepAlive=true`, so the ended
+ * process is relaunched from the swapped binary within seconds.
+ */
+export function restartMenubarHelperAfterSwap(uid, ownProcesses, exec = execFileSync, kill = endProcess) {
+    const reg = serviceManagerRegistrationAllowed();
+    if (!reg.allowed)
+        return;
+    const target = `gui/${uid}/${serviceLabel()}`;
+    const opts = { stdio: ['ignore', 'ignore', 'ignore'] };
+    try {
+        exec('launchctl', ['kickstart', '-k', target], opts);
+        return;
+    }
+    catch {
+        for (const p of ownProcesses)
+            kill(p.pid);
+    }
+}
 /**
  * Install + start the menu-bar helper as a launchd user service (idempotent).
  * Clears the sticky opt-out, installs the .app, writes the plist, and
@@ -425,6 +464,22 @@ function menubarSetupStale() {
         execExists: fs.existsSync(installedExecutablePath()),
     });
 }
+/**
+ * Pure decision (no I/O): did THIS heal actually replace bundle content a live
+ * process could be running stale, as opposed to a plist-only repoint?
+ *
+ * `stale` (version bump or missing exec) and `needsDevIdHeal` (ad-hoc ->
+ * Developer ID) both mean the shipped `.app` differs from what is already
+ * installed — the exact condition under which a running helper can be left on
+ * an old code identity after `enableMenubarService` swaps the bundle. A
+ * repoint-only heal (`menubarSetupNeedsRepoint()` alone, same version, same
+ * signing identity) does NOT count: RUSH-3005 already owns the churn from
+ * mixed-Node-interpreter repoints, and restarting the helper on every one of
+ * those would double that churn rather than fix this bug.
+ */
+export function menubarHealReplacedBundle(opts) {
+    return opts.stale || opts.needsDevIdHeal;
+}
 /**
  * Pure re-point decision (no I/O): the plist's baked interpreter/entry no longer
  * match the install that is now running `agents`. This catches DUAL-INSTALL skew
@@ -440,7 +495,12 @@ export function menubarPlistNeedsRepoint(opts) {
         return false; // can't resolve the running install — don't churn
     if (opts.plistEntry !== opts.activeEntry)
         return true;
-    if (opts.activeNode && opts.plistNode !== opts.activeNode)
+    // The entry path owns the helper. The same installed CLI may be invoked through
+    // several compatible Node interpreters (nvm, Homebrew, a parent process's
+    // process.execPath). Re-pointing merely because those valid interpreter paths
+    // differ makes every invocation replace and relaunch the shared helper. Keep the
+    // recorded interpreter until it disappears; then repoint to the active one.
+    if (opts.activeNode && (!opts.plistNode || !opts.plistNodeExists))
         return true;
     return false;
 }
@@ -457,9 +517,11 @@ function readPlistEnvValue(key) {
 }
 /** True when the installed plist points at a different install than the active one. */
 function menubarSetupNeedsRepoint() {
+    const plistNode = readPlistEnvValue('AGENTS_NODE');
     return menubarPlistNeedsRepoint({
         plistEntry: readPlistEnvValue('AGENTS_ENTRY'),
-        plistNode: readPlistEnvValue('AGENTS_NODE'),
+        plistNode,
+        plistNodeExists: Boolean(plistNode) && fs.existsSync(plistNode),
         activeEntry: resolveCliEntry(),
         activeNode: process.execPath,
     });
@@ -650,7 +712,8 @@ export function installMenubarLaunchAgentOnUpgrade() {
         // installed copy is still ad-hoc while the shipped source is Developer ID
         // (older heal path; Accessibility re-prompts until the identity is restored).
         const needsDevIdHeal = installedNeedsDevIdHeal();
-        if (!(menubarSetupStale() || menubarSetupNeedsRepoint() || needsDevIdHeal))
+        const stale = menubarSetupStale();
+        if (!(stale || menubarSetupNeedsRepoint() || needsDevIdHeal))
             return;
         // ...but a copy that does not own the helper only gets to act on that drift
         // once per cooldown. Without the gate every coexisting install recopies the
@@ -661,8 +724,22 @@ export function installMenubarLaunchAgentOnUpgrade() {
         // false without installing when the bundle fails the Gatekeeper check, and
         // stamping first would spend the shared cooldown on a no-op — locking every
         // non-owner out for another hour while nothing had been fixed.
-        if (enableMenubarService({ clearOptOut: false }))
+        if (enableMenubarService({ clearOptOut: false })) {
             stampMenubarHeal();
+            // One-time: the ad-hoc -> Developer ID transition leaves a dead TCC row
+            // under the old identity (tccutil on zion reset it 11 times across
+            // machines that made this jump) — clear it so the fresh grant sticks.
+            if (shouldMigrateMenubarTcc({ needsDevIdHeal, alreadyMigrated: menubarTccAlreadyMigrated() })) {
+                resetMenubarAccessibilityTcc();
+            }
+            // Only a REAL content swap (version bump or the Dev-ID transition) can
+            // leave a running process on stale code — a plist-only repoint (handled
+            // above by menubarSetupNeedsRepoint alone) is RUSH-3005's churn to own,
+            // not this heal's to restart on top of.
+            if (menubarHealReplacedBundle({ stale, needsDevIdHeal })) {
+                restartMenubarHelperAfterSwap(process.getuid?.() ?? 0, liveMenubarProcesses().own);
+            }
+        }
     }
     catch {
         /* never block startup on the menu bar */
@@ -677,6 +754,46 @@ function installedNeedsDevIdHeal() {
         return false;
     return hasDeveloperIdSignature(src);
 }
+/** Marker written once the one-time ad-hoc -> Developer ID TCC migration has
+ *  run on this machine, next to the version/heal stamps. */
+function tccMigrationMarkerPath() {
+    return path.join(installDir(), '.menubar-tcc-migrated');
+}
+function menubarTccAlreadyMigrated() {
+    return fs.existsSync(tccMigrationMarkerPath());
+}
+/**
+ * Pure decision (no I/O): run the one-time `tccutil reset Accessibility` only
+ * on a real ad-hoc -> Developer ID transition, and only once ever. A machine
+ * that was always Developer ID never accumulated a dead TCC row under an
+ * ad-hoc identity, so resetting there would just force a needless re-prompt;
+ * a machine that already migrated must not be reset again on every heal.
+ */
+export function shouldMigrateMenubarTcc(opts) {
+    return opts.needsDevIdHeal && !opts.alreadyMigrated;
+}
+/**
+ * Reset the stale Accessibility grant TCC recorded against the pre-migration
+ * ad-hoc identity, then stamp the marker so this never runs again on this
+ * machine. Targets `SERVICE_LABEL_BASE` — the bundle's actual
+ * `CFBundleIdentifier`/codesign `--identifier` (menubar/scripts/build.sh) that
+ * TCC keys grants to — not the namespaced `serviceLabel()`, which exists only
+ * to keep launchd job labels apart under a redirected HOME (RUSH-2639) and is
+ * never the app's real identity. Best-effort: a missing/failing `tccutil`
+ * (older macOS, a sandboxed test HOME) must never block the heal that just
+ * fixed the signing identity itself.
+ */
+export function resetMenubarAccessibilityTcc(exec = execFileSync) {
+    try {
+        exec('tccutil', ['reset', 'Accessibility', SERVICE_LABEL_BASE], { stdio: ['ignore', 'ignore', 'ignore'] });
+    }
+    catch { /* best effort — a missing/failing tccutil must not block the heal */ }
+    try {
+        fs.mkdirSync(installDir(), { recursive: true });
+        fs.writeFileSync(tccMigrationMarkerPath(), new Date().toISOString());
+    }
+    catch { /* best effort */ }
+}
 /**
  * Decide which live helper processes must be ended so exactly one status item
  * survives. Pure so the choice is unit-testable without a live menu bar.
@@ -867,3 +984,81 @@ export function getMenubarStatus() {
         disabledByUser: menubarDisabledByUser(),
     };
 }
+/**
+ * Pure comparison (no I/O) behind the stale-process check: a helper pid that
+ * started before the bundle on disk was last written is still running the
+ * PREVIOUS binary — the exact condition `restartMenubarHelperAfterSwap` exists
+ * to fix. Millisecond epoch timestamps in, so the truth table is unit-testable
+ * without a live process or filesystem.
+ */
+export function isMenubarProcessStaleAgainstBundle(pidStartedAtMs, bundleMtimeMs) {
+    return pidStartedAtMs < bundleMtimeMs;
+}
+/** Wall-clock start time of a live pid via `ps`, or null if it can't be read. */
+function pidStartTimeMs(pid) {
+    const r = spawnSync('ps', ['-o', 'lstart=', '-p', String(pid)], {
+        stdio: ['ignore', 'pipe', 'ignore'],
+        encoding: 'utf-8',
+    });
+    if (r.status !== 0)
+        return null;
+    const raw = (r.stdout || '').trim();
+    if (!raw)
+        return null;
+    const t = new Date(raw).getTime();
+    return Number.isNaN(t) ? null : t;
+}
+/**
+ * `agents menubar doctor` — everything a human needs to tell "why did
+ * Accessibility ask again" apart from "the helper is genuinely broken":
+ * install path, version skew, whether the signing identity is update-stable,
+ * and whether a live process predates the bundle it's supposed to be running.
+ * Read-only: no install, no restart, no TCC reset — `agents menubar setup`
+ * remains the command that fixes what this reports.
+ */
+export function buildMenubarDoctorReport() {
+    if (!onDarwin()) {
+        return {
+            platform: process.platform,
+            installPath: null,
+            installedVersion: null,
+            currentVersion: getCliVersion(),
+            versionMatches: false,
+            signingIdentity: 'unknown',
+            running: false,
+            staleRunningProcess: [],
+            accessibilityHintNeeded: false,
+        };
+    }
+    const status = getMenubarStatus();
+    const appPath = status.installedApp;
+    const signingIdentity = appPath
+        ? (hasDeveloperIdSignature(appPath) ? 'developer-id' : 'ad-hoc')
+        : 'unknown';
+    let staleRunningProcess = [];
+    if (appPath && status.instances.length > 0) {
+        try {
+            const bundleMtimeMs = fs.statSync(installedExecutablePath()).mtimeMs;
+            staleRunningProcess = status.instances
+                .map((p) => {
+                const startedAt = pidStartTimeMs(p.pid);
+                return startedAt === null
+                    ? null
+                    : { pid: p.pid, stale: isMenubarProcessStaleAgainstBundle(startedAt, bundleMtimeMs) };
+            })
+                .filter((p) => p !== null);
+        }
+        catch { /* exec vanished mid-check — report no staleness rather than throw */ }
+    }
+    return {
+        platform: process.platform,
+        installPath: appPath,
+        installedVersion: status.installedVersion,
+        currentVersion: status.currentVersion,
+        versionMatches: status.installedVersion === status.currentVersion,
+        signingIdentity,
+        running: status.running,
+        staleRunningProcess,
+        accessibilityHintNeeded: signingIdentity === 'ad-hoc' || staleRunningProcess.some((p) => p.stale),
+    };
+}

package/dist/lib/prix-account.d.ts

@@ -1,6 +1,7 @@
 /**
  * Client for the Rush account layer (`api.prix.dev`) — backs `agents auth` and
- * `agents org`. `agents org` maps to `/api/v1/spaces`, not `/api/v1/orgs`: spaces
+ * `agents auth space` (canonical) / `agents org` (deprecated alias). `agents auth space`
+ * maps to `/api/v1/spaces`, not `/api/v1/orgs`: spaces
  * already carry the free-tier caps (1 owned space, 3 members) and can exist
  * standalone with no parent organization, matching a "just want a team" CLI flow
  * better than the heavier enterprise-tenancy `orgs` routes (domain, SSO). See

package/dist/lib/prix-account.js

@@ -1,6 +1,7 @@
 /**
  * Client for the Rush account layer (`api.prix.dev`) — backs `agents auth` and
- * `agents org`. `agents org` maps to `/api/v1/spaces`, not `/api/v1/orgs`: spaces
+ * `agents auth space` (canonical) / `agents org` (deprecated alias). `agents auth space`
+ * maps to `/api/v1/spaces`, not `/api/v1/orgs`: spaces
  * already carry the free-tier caps (1 owned space, 3 members) and can exist
  * standalone with no parent organization, matching a "just want a team" CLI flow
  * better than the heavier enterprise-tenancy `orgs` routes (domain, SSO). See

package/dist/lib/remote-agents-json.js

@@ -12,7 +12,7 @@ import chalk from 'chalk';
 import { SSH_OPTS, controlOpts, assertValidSshTarget, shellQuote, REMOTE_STDOUT_MAX_BYTES, RemoteUtf8Accumulator, } from './ssh-exec.js';
 import { deviceIdentityArgs, sshTargetFor } from './devices/connect.js';
 import { resolveExplicitTargets } from './devices/resolve-target.js';
-import { loadDevices, isControlDevice, isDialableDevice } from './devices/registry.js';
+import { loadDevices, isDialableDevice } from './devices/registry.js';
 import { remoteShellFor, buildWindowsAgentsCommand, stripClixml } from './hosts/remote-cmd.js';
 import { machineId, normalizeHost } from './machine-id.js';
 const REMOTE_TIMEOUT_MS = 12_000;
@@ -117,12 +117,6 @@ export async function gatherRemoteAgentsJson(options, deps = {}) {
                 continue;
             if (normalizeHost(device.name) === self)
                 continue;
-            // Control-only devices (a phone/tablet cockpit) drive the fleet but never
-            // run agents — never dial them, whatever their platform reads as. Keyed on
-            // role, not platform, so this holds even for a control device that carries
-            // a real OS value (mirrors the skip in session/remote-list.ts).
-            if (isControlDevice(device))
-                continue;
             if (!['windows', 'linux', 'macos'].includes(device.platform))
                 continue;
             try {

package/dist/lib/routines-placement.d.ts

@@ -29,7 +29,7 @@ export type PlacementTarget = {
  * `config.devices` is the *firing* allowlist only (which daemon may fire the
  * job). It is intentionally NOT used as an execution pool filter — otherwise
  * the double-fire pin (`devices: [self]`) would collapse fleet placement to
- * always-local. Control / offline / no-address devices are never chosen.
+ * always-local. Offline / no-address devices are never chosen.
  */
 export declare function pickFleetDevice(_config?: Pick<JobConfig, 'devices'>, platform?: DevicePlatform): string | null;
 /**

package/dist/lib/routines-placement.js

@@ -23,7 +23,7 @@ import { planFleetTargets } from './devices/fleet.js';
  * `config.devices` is the *firing* allowlist only (which daemon may fire the
  * job). It is intentionally NOT used as an execution pool filter — otherwise
  * the double-fire pin (`devices: [self]`) would collapse fleet placement to
- * always-local. Control / offline / no-address devices are never chosen.
+ * always-local. Offline / no-address devices are never chosen.
  */
 export function pickFleetDevice(_config, platform) {
     let reg;

package/dist/lib/secrets/Agents CLI.app/Contents/Info.plist

@@ -8,8 +8,6 @@
   <string>Agents CLI</string>
   <key>CFBundleDisplayName</key>
   <string>Agents CLI</string>
-  <key>CFBundleIconFile</key>
-  <string>AppIcon</string>
   <key>CFBundleExecutable</key>
   <string>Agents CLI</string>
   <key>CFBundlePackageType</key>