@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/hosts/tasks.d.ts

@@ -1,43 +1,15 @@
-/**
- * Local record of dispatched host tasks.
- *
- * Each dispatch writes a `<id>.json` sidecar next to its `<id>.log` (and the
- * remote's `<id>.exit`) under ~/.agents/.cache/hosts/, so `agents devices ps` / `agents logs`
- * can list runs and follow output across CLI invocations. (Folding these into
- * the cloud SQLite store so `agents cloud ps` sees them is a fast-follow — it
- * needs care around the cloud status-refresh path.)
- */
 export type HostTaskStatus = 'running' | 'completed' | 'failed' | 'unknown';
 export interface HostTask {
     id: string;
     host: string;
     target: string;
-    /** OpenSSH private-key path retained for follow/reconcile/stop calls. */
     identityFile?: string;
     remoteShell?: 'posix' | 'powershell';
     agent: string;
     prompt: string;
     pid?: number;
-    /**
-     * The durable `agents run --name <slug>` handle for this dispatch, if given.
-     * Chosen at launch and agent-agnostic (unlike sessionId), so `agents devices
-     * ps` / `agents logs <name>` and the dispatch tip can reference the run by a stable name
-     * even for agents that never expose a session id up front. Absent when the
-     * run was launched without `--name`.
-     */
     name?: string;
-    /**
-     * The remote run's agent session id, so `agents sessions`/resume-by-id can map
-     * a discovered session back to the host it lives on. Two sources: for Claude
-     * (the only agent that accepts `--session-id`) it's the id we FORCED at
-     * dispatch; for every other agent it's the id the remote COINED, captured from
-     * the run's stdout sentinel (`--emit-session-id`, see session-marker.ts) once
-     * the follow returns and stamped on the record via `captureRemoteSessionId`.
-     * Absent only until that capture lands — e.g. an unfollowed (`--no-follow`)
-     * non-Claude run whose id the reconcile path fills in later.
-     */
     sessionId?: string;
-    /** Remote paths (under the host's ~/.agents/.cache/hosts/). */
     remoteLog: string;
     remoteExit: string;
     status: HostTaskStatus;
@@ -46,38 +18,12 @@ export interface HostTask {
     finishedAt?: string;
 }
 export declare function hostsCacheDir(): string;
-/** Local path we mirror a task's remote log into while following. */
 export declare function localLogPath(id: string): string;
 export declare function saveTask(task: HostTask): void;
 export declare function loadTask(id: string): HostTask | null;
 export declare function updateTask(id: string, patch: Partial<HostTask>): HostTask | null;
-/**
- * The record patch for a run that has finished with `code`. The single authority
- * for the exit-code → status mapping, so the dispatch, reconcile, and log-follow
- * paths can never disagree. A genuine remote exit code is never -1 (that sentinel
- * means "follow window closed while the run continues"), so callers must resolve
- * -1 as still-running and never pass it here.
- */
 export declare function terminalPatch(code: number): Partial<HostTask>;
 export declare function listTasks(): HostTask[];
-/**
- * Find the host task that launched a given agent session id, so a resume-by-id
- * can re-dispatch to the host the session actually lives on. Newest task wins
- * (listTasks is createdAt-desc) — a session id should be unique, but a re-run
- * with the same forced id resolves to the most recent dispatch.
- */
 export declare function findTaskBySessionId(sessionId: string): HostTask | null;
-/**
- * Find the newest host task launched with `--name <name>`, so `agents logs
- * <name>` / `agents devices ps` and resolve-by-handle can address a run by its durable name.
- * Case-insensitive; newest wins (listTasks is createdAt-desc) when a name was
- * reused across dispatches.
- */
 export declare function findTaskByName(name: string): HostTask | null;
-/**
- * Resolve a host-task reference the way `agents devices ps`, `agents logs`, and `agents devices stop` do: a raw
- * dispatch id first, then a `--name` handle, then the remote agent/session id.
- * Shared so any other caller resolving "does this ref name a detached --device
- * dispatch?" (e.g. `agents message`) uses the identical three-way lookup.
- */
 export declare function resolveTaskRef(ref: string): HostTask | null;

package/dist/lib/hosts/tasks.js

@@ -1,12 +1,3 @@
-/**
- * Local record of dispatched host tasks.
- *
- * Each dispatch writes a `<id>.json` sidecar next to its `<id>.log` (and the
- * remote's `<id>.exit`) under ~/.agents/.cache/hosts/, so `agents devices ps` / `agents logs`
- * can list runs and follow output across CLI invocations. (Folding these into
- * the cloud SQLite store so `agents cloud ps` sees them is a fast-follow — it
- * needs care around the cloud status-refresh path.)
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import { getCacheDir } from '../state.js';
@@ -16,7 +7,6 @@ export function hostsCacheDir() {
 function taskFile(id) {
     return path.join(hostsCacheDir(), `${id}.json`);
 }
-/** Local path we mirror a task's remote log into while following. */
 export function localLogPath(id) {
     return path.join(hostsCacheDir(), `${id}.log`);
 }
@@ -40,13 +30,6 @@ export function updateTask(id, patch) {
     saveTask(next);
     return next;
 }
-/**
- * The record patch for a run that has finished with `code`. The single authority
- * for the exit-code → status mapping, so the dispatch, reconcile, and log-follow
- * paths can never disagree. A genuine remote exit code is never -1 (that sentinel
- * means "follow window closed while the run continues"), so callers must resolve
- * -1 as still-running and never pass it here.
- */
 export function terminalPatch(code) {
     return {
         status: code === 0 ? 'completed' : 'failed',
@@ -70,12 +53,6 @@ export function listTasks() {
     }
     return tasks.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
 }
-/**
- * Find the host task that launched a given agent session id, so a resume-by-id
- * can re-dispatch to the host the session actually lives on. Newest task wins
- * (listTasks is createdAt-desc) — a session id should be unique, but a re-run
- * with the same forced id resolves to the most recent dispatch.
- */
 export function findTaskBySessionId(sessionId) {
     if (!sessionId)
         return null;
@@ -85,12 +62,6 @@ export function findTaskBySessionId(sessionId) {
     }
     return null;
 }
-/**
- * Find the newest host task launched with `--name <name>`, so `agents logs
- * <name>` / `agents devices ps` and resolve-by-handle can address a run by its durable name.
- * Case-insensitive; newest wins (listTasks is createdAt-desc) when a name was
- * reused across dispatches.
- */
 export function findTaskByName(name) {
     if (!name)
         return null;
@@ -101,12 +72,6 @@ export function findTaskByName(name) {
     }
     return null;
 }
-/**
- * Resolve a host-task reference the way `agents devices ps`, `agents logs`, and `agents devices stop` do: a raw
- * dispatch id first, then a `--name` handle, then the remote agent/session id.
- * Shared so any other caller resolving "does this ref name a detached --device
- * dispatch?" (e.g. `agents message`) uses the identical three-way lookup.
- */
 export function resolveTaskRef(ref) {
     return loadTask(ref) ?? findTaskByName(ref) ?? findTaskBySessionId(ref);
 }

package/dist/lib/hosts/types.d.ts

@@ -1,70 +1,31 @@
-/**
- * Agent-host provider contract.
- *
- * A `HostProvider` answers "what are my hosts, and how do I reach them?" — the
- * pluggable directory/metadata/reachability layer. Shipped providers: `local`
- * (ssh-config ∪ inline registry) and `devices` (the Tailscale fleet from
- * `agents devices`); `rush`/`crabbox` remain additive fast-follows behind this
- * same contract. Capability-gated so partial providers are first-class
- * (mirrors the cloud provider registry).
- */
 import type { HostEntry } from '../types.js';
 export type HostProviderId = 'local' | 'devices';
 export type HostStatus = 'online' | 'offline' | 'unknown';
-/** A host as seen at runtime: its persisted entry plus name/provider/status. */
 export interface Host extends HostEntry {
     name: string;
     provider: HostProviderId;
-    /** True when the host has an explicit overlay/inline entry in the registry. */
     enrolled?: boolean;
     status?: HostStatus;
-    /**
-     * False when the host is listed for honesty but can't carry a `--device` run
-     * (today: password-auth devices — offload rides BatchMode=yes ssh). Absent
-     * means dispatchable. Cap routing and target pickers filter on this.
-     */
     dispatchable?: boolean;
 }
-/**
- * Thrown when a device resolves but can't be used as an offload target because
- * it authenticates with a password. The offload path runs over `sshExec`, whose
- * `SSH_OPTS` force `BatchMode=yes` (no password prompts), so only key / ssh-config
- * auth can carry a `--device` run. Named so the top-level catch prints the message
- * cleanly instead of a stack trace. (Lives here, not registry.ts, so providers
- * can throw it without a circular import; registry.ts re-exports it.)
- */
 export declare class DeviceOffloadUnsupportedError extends Error {
     constructor(name: string);
 }
 export interface HostProviderCapabilities {
-    /** Can list/track hosts. */
     directory: boolean;
-    /** Can add/remove hosts. */
     mutate: boolean;
-    /** Reports online/offline without an explicit probe. */
     presence: boolean;
-    /** Can dispatch a command without an SSH address (its own relay). */
     relay: boolean;
-    /** Can provision new hosts. */
     lease: boolean;
 }
 export interface HostProvider {
     id: HostProviderId;
     capabilities(): HostProviderCapabilities;
-    /** Every host this provider knows about. */
     list(): Promise<Host[]>;
-    /** Resolve one host by name, or null if unknown to this provider. */
     resolve(name: string): Promise<Host | null>;
-    /** Persist a host (mutate-capable providers only). */
     register?(spec: Host): Promise<Host>;
-    /** Remove a host (mutate-capable providers only). */
     remove?(name: string): Promise<void>;
-    /** Presence without an explicit probe (presence-capable providers only). */
     presence?(name: string): Promise<HostStatus>;
 }
-/**
- * The ssh target string for a host: the bare name for ssh-config hosts (ssh
- * resolves HostName/User/Port/Identity), else `user@address` (or `address`).
- */
 export declare function sshTargetFor(host: Host): string;
 export declare function hostIdentityArgs(host: Host): string[];

package/dist/lib/hosts/types.js

@@ -1,21 +1,3 @@
-/**
- * Agent-host provider contract.
- *
- * A `HostProvider` answers "what are my hosts, and how do I reach them?" — the
- * pluggable directory/metadata/reachability layer. Shipped providers: `local`
- * (ssh-config ∪ inline registry) and `devices` (the Tailscale fleet from
- * `agents devices`); `rush`/`crabbox` remain additive fast-follows behind this
- * same contract. Capability-gated so partial providers are first-class
- * (mirrors the cloud provider registry).
- */
-/**
- * Thrown when a device resolves but can't be used as an offload target because
- * it authenticates with a password. The offload path runs over `sshExec`, whose
- * `SSH_OPTS` force `BatchMode=yes` (no password prompts), so only key / ssh-config
- * auth can carry a `--device` run. Named so the top-level catch prints the message
- * cleanly instead of a stack trace. (Lives here, not registry.ts, so providers
- * can throw it without a circular import; registry.ts re-exports it.)
- */
 export class DeviceOffloadUnsupportedError extends Error {
     constructor(name) {
         super(`Device "${name}" uses password auth, which --device offload can't use yet ` +
@@ -24,10 +6,6 @@ export class DeviceOffloadUnsupportedError extends Error {
         this.name = 'DeviceOffloadUnsupportedError';
     }
 }
-/**
- * The ssh target string for a host: the bare name for ssh-config hosts (ssh
- * resolves HostName/User/Port/Identity), else `user@address` (or `address`).
- */
 export function sshTargetFor(host) {
     if (host.source === 'ssh-config')
         return host.name;

package/dist/lib/humans.d.ts

@@ -1,33 +1,12 @@
 import type { HumansConfig, HumanOwner } from './types.js';
-/**
- * Read and parse humans.yaml. Returns null when the file does not exist or
- * is not a valid v1 config — never throws.
- */
 export declare function readHumans(): HumansConfig | null;
-/**
- * Write a HumansConfig to ~/.agents/humans.yaml. Creates the file with the
- * canonical header. Overwrites any existing content.
- */
 export declare function writeHumans(config: HumansConfig): void;
-/**
- * Return the effective owner notification destination from humans.yaml.
- * The owner's normal-severity policy selects the channel; when no normal
- * policy is declared, the first addressable channel is the default.
- */
 export declare function getOwnerNotifyFromHumans(): {
     channel: string;
     to: string;
 } | null;
-/**
- * Return every addressable owner destination selected by the normal-severity
- * policy, in policy order. A config without a policy keeps the historical
- * single-channel behavior by selecting the first addressable channel.
- */
 export declare function getOwnerNotifyDestinationsFromHumans(): Array<{
     channel: string;
     to: string;
 }>;
-/**
- * Read the owner block from humans.yaml. Returns null if missing.
- */
 export declare function getOwnerFromHumans(): HumanOwner | null;

package/dist/lib/humans.js

@@ -1,12 +1,3 @@
-/**
- * humans.yaml — owner identity, channels, and notification policy.
- *
- * Canonical file: ~/.agents/humans.yaml
- * Schema version: 1
- *
- * This module is the single read/write seam for humans.yaml. All channel/
- * notify consumers should read owner config from here.
- */
 import * as fs from 'fs';
 import * as yaml from 'yaml';
 import { getHumansFilePath } from './state.js';
@@ -14,10 +5,6 @@ const HUMANS_VERSION = 1;
 const HUMANS_HEADER = `# humans.yaml — owner identity and notification channels
 # Managed by agents-cli. See: agents humans --help
 `;
-/**
- * Read and parse humans.yaml. Returns null when the file does not exist or
- * is not a valid v1 config — never throws.
- */
 export function readHumans() {
     const filePath = getHumansFilePath();
     if (!fs.existsSync(filePath))
@@ -36,28 +23,14 @@ export function readHumans() {
         return null;
     }
 }
-/**
- * Write a HumansConfig to ~/.agents/humans.yaml. Creates the file with the
- * canonical header. Overwrites any existing content.
- */
 export function writeHumans(config) {
     const filePath = getHumansFilePath();
     const body = yaml.stringify(config, { lineWidth: 120 });
     fs.writeFileSync(filePath, HUMANS_HEADER + body, { encoding: 'utf-8', mode: 0o600 });
 }
-/**
- * Return the effective owner notification destination from humans.yaml.
- * The owner's normal-severity policy selects the channel; when no normal
- * policy is declared, the first addressable channel is the default.
- */
 export function getOwnerNotifyFromHumans() {
     return getOwnerNotifyDestinationsFromHumans()[0] ?? null;
 }
-/**
- * Return every addressable owner destination selected by the normal-severity
- * policy, in policy order. A config without a policy keeps the historical
- * single-channel behavior by selecting the first addressable channel.
- */
 export function getOwnerNotifyDestinationsFromHumans() {
     const owner = readHumans()?.owner;
     const channels = owner?.channels ?? [];
@@ -86,9 +59,6 @@ export function getOwnerNotifyDestinationsFromHumans() {
         return [migrated];
     return [];
 }
-/**
- * Read the owner block from humans.yaml. Returns null if missing.
- */
 export function getOwnerFromHumans() {
     return readHumans()?.owner ?? null;
 }

package/dist/lib/identity/client.d.ts

@@ -1,60 +1,26 @@
-/**
- * The ONE place agents-cli talks to its account backend (Phoenix ID).
- *
- * Why a seam at all: the removed Prix-coupled layer (RUSH-2581) had no single
- * entry point — the backend URL was hardcoded in five files and the session
- * token was re-read from `~/.rush/user.yaml` by seven separate functions, so
- * re-pointing identity meant editing a dozen call sites and rewriting error
- * strings scattered through the tree. This module is the correction: one base
- * URL, one token reader, one HTTP funnel, one error type. Commands import from
- * here and nothing else.
- *
- * The shape mirrors the seams this repo already proved elsewhere —
- * the bounded secrets process client (`lib/secrets-client.ts`) and
- * `CloudProvider` (`lib/cloud/types.ts`) — so a second identity backend, if
- * one is ever needed, is a swap here rather than a sweep across commands.
- */
-/**
- * Where the account backend lives. Config, never a literal at a call site.
- *
- * The default is Phoenix ID's branded custom domain. The legacy workers.dev
- * hostname remains live for already-released clients, but new clients and
- * managed Workers must share this canonical base so token verification cannot
- * drift across the release boundary.
- */
 export declare const DEFAULT_PHOENIX_ID_BASE = "https://id.byphoenix.com";
 export declare const PHOENIX_ID_BASE: string;
-/** Our own session file. agents-cli never reads another product's credentials. */
 export declare function sessionFilePath(): string;
 export interface PhoenixSession {
     access_token: string;
     email?: string;
     userId?: string;
-    /**
-     * Hosted OAuth profile image (https URL), when Phoenix ID exposes one. Wins
-     * over the email-Gravatar fallback in share attribution. Optional forever —
-     * a missing value just means the Gravatar/initials fallback.
-     */
     avatarUrl?: string;
-    /** Unix ms; absent means the server did not scope the token's lifetime. */
+    name?: string;
     expires_at?: number;
 }
 export declare function readSession(): PhoenixSession | null;
 export declare function writeSession(session: PhoenixSession): void;
 export declare function clearSession(): void;
-/** An error carrying the server's status and message, so callers can branch on it. */
 export declare class PhoenixApiError extends Error {
     readonly status: number;
     constructor(message: string, status: number);
 }
 interface RequestOptions {
     body?: unknown;
-    /** Send the stored session token. Default true; the device-flow start does not. */
     auth?: boolean;
-    /** Use this token instead of the stored one (mid-login, before the write). */
     token?: string;
     timeoutMs?: number;
 }
-/** The single HTTP funnel. Every request to the account backend goes through here. */
 export declare function phoenixRequest<T>(method: 'GET' | 'POST' | 'PATCH' | 'DELETE', route: string, opts?: RequestOptions): Promise<T>;
 export {};

package/dist/lib/identity/client.js

@@ -1,33 +1,9 @@
-/**
- * The ONE place agents-cli talks to its account backend (Phoenix ID).
- *
- * Why a seam at all: the removed Prix-coupled layer (RUSH-2581) had no single
- * entry point — the backend URL was hardcoded in five files and the session
- * token was re-read from `~/.rush/user.yaml` by seven separate functions, so
- * re-pointing identity meant editing a dozen call sites and rewriting error
- * strings scattered through the tree. This module is the correction: one base
- * URL, one token reader, one HTTP funnel, one error type. Commands import from
- * here and nothing else.
- *
- * The shape mirrors the seams this repo already proved elsewhere —
- * the bounded secrets process client (`lib/secrets-client.ts`) and
- * `CloudProvider` (`lib/cloud/types.ts`) — so a second identity backend, if
- * one is ever needed, is a swap here rather than a sweep across commands.
- */
 import * as fs from 'fs';
 import * as path from 'path';
+import { atomicWriteFileSync } from '../fs-atomic.js';
 import { getRuntimeStateDir } from '../state.js';
-/**
- * Where the account backend lives. Config, never a literal at a call site.
- *
- * The default is Phoenix ID's branded custom domain. The legacy workers.dev
- * hostname remains live for already-released clients, but new clients and
- * managed Workers must share this canonical base so token verification cannot
- * drift across the release boundary.
- */
 export const DEFAULT_PHOENIX_ID_BASE = 'https://id.byphoenix.com';
 export const PHOENIX_ID_BASE = process.env.PHOENIX_ID_BASE ?? DEFAULT_PHOENIX_ID_BASE;
-/** Our own session file. agents-cli never reads another product's credentials. */
 export function sessionFilePath() {
     return path.join(getRuntimeStateDir(), 'phoenix-session.json');
 }
@@ -44,17 +20,16 @@ export function readSession() {
 export function writeSession(session) {
     const file = sessionFilePath();
     fs.mkdirSync(path.dirname(file), { recursive: true });
-    fs.writeFileSync(file, JSON.stringify(session, null, 2), { mode: 0o600 });
+    atomicWriteFileSync(file, JSON.stringify(session, null, 2), { encoding: 'utf-8', mode: 0o600 });
+    fs.chmodSync(file, 0o600);
 }
 export function clearSession() {
     try {
         fs.rmSync(sessionFilePath(), { force: true });
     }
     catch {
-        // Already gone: logging out twice is not an error.
     }
 }
-/** An error carrying the server's status and message, so callers can branch on it. */
 export class PhoenixApiError extends Error {
     status;
     constructor(message, status) {
@@ -63,7 +38,6 @@ export class PhoenixApiError extends Error {
         this.name = 'PhoenixApiError';
     }
 }
-/** The single HTTP funnel. Every request to the account backend goes through here. */
 export async function phoenixRequest(method, route, opts = {}) {
     const headers = { 'Content-Type': 'application/json' };
     if (opts.auth !== false) {

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

@@ -1,7 +1,3 @@
-/**
- * Phoenix ID — the typed surface commands use. Every route the account backend
- * exposes is a function here; no command builds a URL or reads a token itself.
- */
 import { type PhoenixSession } from './client.js';
 export { PHOENIX_ID_BASE, PhoenixApiError, clearSession, readSession, sessionFilePath, writeSession, type PhoenixSession, } from './client.js';
 export interface DeviceAuthorization {
@@ -16,24 +12,18 @@ export interface WhoAmI {
     userId: string;
     email: string;
     valid: true;
-    /** Hosted OAuth profile image, when Phoenix ID stores one for this user. */
     avatar_url?: string;
+    name?: string;
 }
-/**
- * RFC 8628 poll outcomes. `pending` and `slow_down` are normal states of a
- * login in progress, not failures — the server signals them through the error
- * body, and this is where that wire detail stops.
- */
 export type DevicePoll = {
     status: 'authorized';
     access_token: string;
     user: {
         email: string;
         id: string;
-        /** Hosted OAuth profile image, when the provider exposed one to Phoenix ID. */
         avatar_url?: string;
-        /** Google-style alias some providers use for the same field. */
         picture?: string;
+        name?: string;
     };
 } | {
     status: 'pending';
@@ -47,18 +37,7 @@ export type DevicePoll = {
 export declare function startDeviceAuthorization(): Promise<DeviceAuthorization>;
 export declare function pollDeviceToken(deviceCode: string): Promise<DevicePoll>;
 export declare function fetchWhoAmI(token?: string): Promise<WhoAmI>;
-/**
- * Keep the session's hosted avatar current (PHNX-3547): merge the `avatar_url`
- * Phoenix ID reports on `/api/v1/auth/me` into the persisted session, so the
- * actor env and share attribution can stamp the profile image instead of only
- * a Gravatar hash. Pass `known` when the caller already fetched `/auth/me`
- * (whoami) — then a changed picture is written too. Without it, a session that
- * already carries a picture is left alone rather than spending a network round
- * trip to re-check it (the share publish path). A no-op when signed out or when
- * the server exposes none; network/server failures are swallowed (the Gravatar
- * fallback covers attribution either way).
- */
-export declare function refreshSessionAvatar(known?: WhoAmI): Promise<void>;
+export declare function refreshSessionProfile(known?: WhoAmI): Promise<void>;
 export interface SpaceSummary {
     id: string;
     slug: string;
@@ -124,10 +103,7 @@ export interface Subscription {
     [key: string]: unknown;
 }
 export declare const fetchSubscription: (agent?: string) => Promise<Subscription>;
-/** `Design Team` → `design-team`; the slug a space gets when the user gives only a name. */
 export declare function slugify(name: string): string;
-/** Resolve a space by id, slug, or name from a list the caller already fetched. */
 export declare function resolveSpaceFromList(spaces: SpaceSummary[], ref?: string): SpaceSummary | null;
-/** Resolve a member by email or user id from a list the caller already fetched. */
 export declare function resolveMemberFromList(members: SpaceMember[], ref: string): SpaceMember | null;
 export type { PhoenixSession as Session };

package/dist/lib/identity/index.js

@@ -1,7 +1,3 @@
-/**
- * Phoenix ID — the typed surface commands use. Every route the account backend
- * exposes is a function here; no command builds a URL or reads a token itself.
- */
 import { phoenixRequest, PhoenixApiError, readSession, writeSession } from './client.js';
 export { PHOENIX_ID_BASE, PhoenixApiError, clearSession, readSession, sessionFilePath, writeSession, } from './client.js';
 export function startDeviceAuthorization() {
@@ -23,7 +19,6 @@ export async function pollDeviceToken(deviceCode) {
     catch (err) {
         if (!(err instanceof PhoenixApiError))
             throw err;
-        // The server encodes poll state in the error body (RFC 8628 §3.5).
         if (err.message.includes('authorization_pending'))
             return { status: 'pending' };
         if (err.message.includes('slow_down'))
@@ -38,18 +33,7 @@ export async function pollDeviceToken(deviceCode) {
 export function fetchWhoAmI(token) {
     return phoenixRequest('GET', '/api/v1/auth/me', { token });
 }
-/**
- * Keep the session's hosted avatar current (PHNX-3547): merge the `avatar_url`
- * Phoenix ID reports on `/api/v1/auth/me` into the persisted session, so the
- * actor env and share attribution can stamp the profile image instead of only
- * a Gravatar hash. Pass `known` when the caller already fetched `/auth/me`
- * (whoami) — then a changed picture is written too. Without it, a session that
- * already carries a picture is left alone rather than spending a network round
- * trip to re-check it (the share publish path). A no-op when signed out or when
- * the server exposes none; network/server failures are swallowed (the Gravatar
- * fallback covers attribution either way).
- */
-export async function refreshSessionAvatar(known) {
+export async function refreshSessionProfile(known) {
     const session = readSession();
     if (!session)
         return;
@@ -57,13 +41,17 @@ export async function refreshSessionAvatar(known) {
         return;
     try {
         const me = known ?? (await fetchWhoAmI());
+        const current = readSession();
+        if (!current || current.access_token !== session.access_token || current.userId !== session.userId)
+            return;
         const hosted = me.avatar_url?.trim();
-        if (hosted && /^https:\/\//i.test(hosted) && hosted !== session.avatarUrl) {
-            writeSession({ ...session, avatarUrl: hosted });
+        const avatarUrl = hosted && /^https:\/\//i.test(hosted) ? hosted : current.avatarUrl;
+        const name = me.name?.trim() || current.name;
+        if (avatarUrl !== current.avatarUrl || name !== current.name) {
+            writeSession({ ...current, ...(avatarUrl ? { avatarUrl } : {}), ...(name ? { name } : {}) });
         }
     }
     catch {
-        // Offline or server without the field — the Gravatar fallback covers it.
     }
 }
 export const listSpaces = () => phoenixRequest('GET', '/api/v1/spaces');
@@ -81,8 +69,6 @@ export const updateSpaceMemberRole = (id, userId, role) => phoenixRequest('PATCH
 export const removeSpaceMember = (id, userId) => phoenixRequest('DELETE', `/api/v1/spaces/${encodeURIComponent(id)}/members/${encodeURIComponent(userId)}`);
 export const deleteSpace = (id) => phoenixRequest('DELETE', `/api/v1/spaces/${encodeURIComponent(id)}`);
 export const fetchSubscription = (agent = 'agents-cli') => phoenixRequest('GET', `/api/v1/billing/subscription?agent=${encodeURIComponent(agent)}`);
-// ─── Helpers shared by the commands ──────────────────────────────────────────
-/** `Design Team` → `design-team`; the slug a space gets when the user gives only a name. */
 export function slugify(name) {
     return name
         .trim()
@@ -91,7 +77,6 @@ export function slugify(name) {
         .replace(/^-+|-+$/g, '')
         .slice(0, 63);
 }
-/** Resolve a space by id, slug, or name from a list the caller already fetched. */
 export function resolveSpaceFromList(spaces, ref) {
     if (!ref)
         return spaces.length === 1 ? spaces[0] : null;
@@ -101,7 +86,6 @@ export function resolveSpaceFromList(spaces, ref) {
         spaces.find((s) => s.name.toLowerCase() === needle) ??
         null);
 }
-/** Resolve a member by email or user id from a list the caller already fetched. */
 export function resolveMemberFromList(members, ref) {
     const needle = ref.trim().toLowerCase();
     return (members.find((m) => m.user_id === ref) ??