@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/accounts/slots.d.ts

@@ -2,39 +2,14 @@ import type { AgentId, DeviceAccountSlot, Meta } from '../types.js';
 export type { DeviceAccountSlot };
 export declare function slotDir(harness: AgentId, accountId: string): string;
 export declare function readSlots(meta: Pick<Meta, 'deviceAccounts'>): Record<string, DeviceAccountSlot>;
-/**
- * Remove slot records from THIS box's device doc (`deviceAccounts.slots`).
- * Symmetric with {@link recordSlot}. The slot DIRECTORY is not touched — a
- * caller that also wants the on-disk home gone removes it separately; a stale
- * worker slot keeps its dir because `.claude/projects` holds transcripts
- * (PHNX-4116). A no-op for an empty list or an id with no record.
- */
 export declare function dropSlots(accountIds: readonly string[]): void;
 export declare function recordSlot(accountId: string, slot: DeviceAccountSlot): void;
 export interface SlotProjection {
     accountId: string;
-    /** Account name as registered (`agents accounts list`). */
     name: string;
     slotDir: string;
-    /** The version home the slot was projected from. */
     from: string;
-    /** `<kind>/<name>` artifacts removed because the source no longer has them. */
     pruned: string[];
 }
-/**
- * Re-project settings and resources into every account slot this device holds
- * for `harness`, from the harness's default version home. `ensureSlot` does
- * this once at `agents accounts add`; every reconcile calls this so a slot
- * never lags the version home it was cloned from (PHNX-3940). Credentials are
- * never touched: `carryForwardSettings` and the resource writers exclude them.
- * A slot whose directory is gone is skipped, not recreated.
- */
 export declare function projectAccountSlots(harness: AgentId): SlotProjection[];
-/**
- * Create the HOME-shaped slot dir and project settings/resources from the
- * managed install. Does not copy credentials (carryForwardSettings excludes
- * them; resource writers write skills/hooks/commands, never OAuth files).
- * Does not persist the slot record — call {@link recordSlot} after identity
- * is captured.
- */
 export declare function ensureSlot(harness: AgentId, accountId: string): DeviceAccountSlot;

package/dist/lib/accounts/slots.js

@@ -1,16 +1,3 @@
-/**
- * Per-device account slots (PHNX-3940).
- *
- * An account is a credential slot, not an installation. The binary lives in
- * the one managed harness install; each account gets a HOME-shaped dir under
- * `~/.agents/.history/accounts/<harness>/<accountId>/` with no binary in it.
- * Native OAuth files stay in this dir on the device that minted them and are
- * never copied. Settings and resources are projected through the same writers
- * version homes use (`carryForwardSettings`, `getWriter`) — credentials are
- * excluded by those writers.
- *
- * Slot records live in the device doc (`deviceAccounts.slots`), never central.
- */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { AGENTS, agentConfigDirName } from '../agents.js';
@@ -35,13 +22,6 @@ export function slotDir(harness, accountId) {
 export function readSlots(meta) {
     return { ...(meta.deviceAccounts?.slots ?? {}) };
 }
-/**
- * Remove slot records from THIS box's device doc (`deviceAccounts.slots`).
- * Symmetric with {@link recordSlot}. The slot DIRECTORY is not touched — a
- * caller that also wants the on-disk home gone removes it separately; a stale
- * worker slot keeps its dir because `.claude/projects` holds transcripts
- * (PHNX-4116). A no-op for an empty list or an id with no record.
- */
 export function dropSlots(accountIds) {
     if (accountIds.length === 0)
         return;
@@ -82,11 +62,6 @@ function projectResources(harness, version, destHome, fromHome) {
         if (!writer)
             continue;
         if (kind === 'rules') {
-            // Symlink to the version home's rules instead of composing a duplicate.
-            // Harnesses whose shim pins a separate config dir (e.g. CLAUDE_CONFIG_DIR
-            // → account slot) cause the harness to load rules from both the version
-            // home (~/.claude/) and the slot, doubling ~5 K tokens per session.
-            // A symlink gives both paths the same inode so the harness can dedup.
             const cap = AGENTS[harness].capabilities.rules;
             if (typeof cap !== 'object')
                 continue;
@@ -102,7 +77,7 @@ function projectResources(harness, version, destHome, fromHome) {
                 if (st.isSymbolicLink() || st.isFile())
                     fs.unlinkSync(destFile);
             }
-            catch { /* did not exist */ }
+            catch { }
             try {
                 createLink(srcFile, destFile);
             }
@@ -126,11 +101,6 @@ function projectResources(harness, version, destHome, fromHome) {
         }
     }
 }
-/**
- * Remove slot artifacts whose source name is gone. Only the name-keyed kinds
- * that implement `remove` (commands, skills, hooks) are pruned; wholesale kinds
- * (rules, permissions) are rewritten by the projection itself.
- */
 function pruneSlotResources(harness, version, slotHome, fromHome) {
     const cwd = process.cwd();
     const pruned = [];
@@ -151,14 +121,6 @@ function pruneSlotResources(harness, version, slotHome, fromHome) {
     }
     return pruned;
 }
-/**
- * Re-project settings and resources into every account slot this device holds
- * for `harness`, from the harness's default version home. `ensureSlot` does
- * this once at `agents accounts add`; every reconcile calls this so a slot
- * never lags the version home it was cloned from (PHNX-3940). Credentials are
- * never touched: `carryForwardSettings` and the resource writers exclude them.
- * A slot whose directory is gone is skipped, not recreated.
- */
 export function projectAccountSlots(harness) {
     const version = sourceVersion(harness);
     if (!version)
@@ -173,9 +135,6 @@ export function projectAccountSlots(harness) {
     for (const account of Object.values(native)) {
         if (account.agent !== harness)
             continue;
-        // The slot record is device-local and written after identity capture; a
-        // slot dir minted by an earlier build, or an add that stopped short of
-        // recording, is still the HOME an account run uses — project it too.
         const dir = slots[account.id]?.slotDir ?? slotDir(harness, account.id);
         if (!fs.existsSync(path.join(dir, agentConfigDirName(harness))))
             continue;
@@ -186,13 +145,6 @@ export function projectAccountSlots(harness) {
     }
     return projected;
 }
-/**
- * Create the HOME-shaped slot dir and project settings/resources from the
- * managed install. Does not copy credentials (carryForwardSettings excludes
- * them; resource writers write skills/hooks/commands, never OAuth files).
- * Does not persist the slot record — call {@link recordSlot} after identity
- * is captured.
- */
 export function ensureSlot(harness, accountId) {
     harnessAuth(harness);
     const dir = slotDir(harness, accountId);

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

@@ -1,14 +1,3 @@
-/**
- * Agent Client Protocol (ACP) client wrapper for agents-cli.
- *
- * Spawns an ACP-capable agent CLI as a stdio subprocess and drives it through
- * initialize -> newSession -> prompt, streaming `session/update` notifications
- * back to the caller as async iterables.
- *
- * Also implements the Client interface (fs read/write, terminal exec) so the
- * agent can request filesystem and shell operations through us. `--mode plan`
- * rejects all write/terminal requests; `edit`/`full` allow them.
- */
 import { type SessionNotification } from '@zed-industries/agent-client-protocol';
 import type { AgentId } from '../types.js';
 import { type ExecMode } from '../exec.js';
@@ -17,16 +6,11 @@ interface AcpRunOptions {
     prompt: string;
     cwd: string;
     mode: ExecMode;
-    /** Optional: callback invoked for every session/update notification. */
     onUpdate?: (n: SessionNotification) => void;
 }
 interface AcpRunResult {
     stopReason: string;
     sessionId: string;
 }
-/**
- * Runs a single prompt turn against an ACP-capable agent and streams updates
- * to `onUpdate`. Resolves when the turn completes (StopReason is returned).
- */
 export declare function runAcp(opts: AcpRunOptions): Promise<AcpRunResult>;
 export {};

package/dist/lib/acp/client.js

@@ -1,14 +1,3 @@
-/**
- * Agent Client Protocol (ACP) client wrapper for agents-cli.
- *
- * Spawns an ACP-capable agent CLI as a stdio subprocess and drives it through
- * initialize -> newSession -> prompt, streaming `session/update` notifications
- * back to the caller as async iterables.
- *
- * Also implements the Client interface (fs read/write, terminal exec) so the
- * agent can request filesystem and shell operations through us. `--mode plan`
- * rejects all write/terminal requests; `edit`/`full` allow them.
- */
 import { spawn } from 'child_process';
 import { Readable, Writable } from 'stream';
 import { promises as fs } from 'fs';
@@ -17,25 +6,11 @@ import { ClientSideConnection, ndJsonStream, } from '@zed-industries/agent-clien
 import { getAcpSpec, supportsAcp } from './harnesses.js';
 import { buildExecEnv } from '../exec.js';
 const PROTOCOL_VERSION = 1;
-/**
- * Runs a single prompt turn against an ACP-capable agent and streams updates
- * to `onUpdate`. Resolves when the turn completes (StopReason is returned).
- */
 export async function runAcp(opts) {
     if (!supportsAcp(opts.agent)) {
         throw new Error(`Agent '${opts.agent}' does not support ACP. Use direct exec instead.`);
     }
     const spec = getAcpSpec(opts.agent);
-    // Build the harness's exec env the SAME way `agents run` does, instead of
-    // handing it a raw process.env. buildExecEnv is what injects the per-account
-    // `CLAUDE_CODE_OAUTH_TOKEN` on a worker device (gated by device role: a
-    // headed/personal box still defers to its native login). Without this, an ACP
-    // launch inherited no setup-token and fell through to the version home's
-    // copied native `.credentials.json` — which expires in ~15h and 401s once its
-    // refresh chain dies, exactly the "logged out on a worker" report (PHNX-3681).
-    // A verified precedence test shows the env token wins over a present
-    // `.credentials.json`, so injecting here is sufficient — the stale file no
-    // longer decides the session.
     const child = spawn(spec.command, spec.args, {
         cwd: opts.cwd,
         stdio: ['pipe', 'pipe', 'inherit'],
@@ -93,10 +68,6 @@ function buildClient(opts) {
             return {};
         },
         async requestPermission(params) {
-            // `skip` (formerly `full`) and `auto` blanket-approve; in `auto` the
-            // upstream model has its own classifier so we just say "allow once" and
-            // let it decide. `edit` says allow_once. `plan` should never reach here
-            // (canWrite gates writes earlier), but if it does we cancel.
             const skipAll = mode === 'skip';
             const optionId = skipAll
                 ? (params.options.find(o => o.kind === 'allow_always')?.optionId

package/dist/lib/acp/harnesses.d.ts

@@ -1,26 +1,11 @@
-/**
- * Per-harness spawn configuration for Agent Client Protocol (ACP) mode.
- *
- * Each entry describes how to launch a coding agent CLI as an ACP server
- * (stdio JSON-RPC). Unsupported harnesses (amp, goose-stdio) are omitted;
- * callers should fall back to the legacy direct-exec path for those.
- *
- * Sources: https://agentclientprotocol.com/get-started/agents + vendor docs.
- */
 import type { AgentId } from '../types.js';
 interface AcpHarnessSpec {
-    /** Command + args to spawn the agent in ACP server mode. */
     command: string;
     args: string[];
-    /** Human-hint for `teams doctor` when the spawn fails. */
     installHint: string;
-    /** Confidence: "verified" = tested in this repo, "documented" = per vendor docs. */
     confidence: 'verified' | 'documented';
-    /** Source URL for the invocation. */
     source: string;
 }
-/** Returns the ACP spawn spec for an agent, or undefined if the harness does not speak ACP. */
 export declare function getAcpSpec(agent: AgentId): AcpHarnessSpec | undefined;
-/** True if the harness is known to support ACP (directly or via adapter). */
 export declare function supportsAcp(agent: AgentId): boolean;
 export {};

package/dist/lib/acp/harnesses.js

@@ -1,12 +1,3 @@
-/**
- * Per-harness spawn configuration for Agent Client Protocol (ACP) mode.
- *
- * Each entry describes how to launch a coding agent CLI as an ACP server
- * (stdio JSON-RPC). Unsupported harnesses (amp, goose-stdio) are omitted;
- * callers should fall back to the legacy direct-exec path for those.
- *
- * Sources: https://agentclientprotocol.com/get-started/agents + vendor docs.
- */
 const ACP_HARNESSES = {
     claude: {
         command: 'npx',
@@ -50,17 +41,10 @@ const ACP_HARNESSES = {
         confidence: 'documented',
         source: 'https://docs.x.ai/build/cli/headless-scripting',
     },
-    // antigravity: no documented ACP support (May 2026).
-    // goose: ACP over HTTP via `goosed`, not a clean stdio subcommand.
-    // copilot: excluded for now (not installed in the reference environment,
-    //                no local verification possible).
-    // amp: not on the ACP agents list.
 };
-/** Returns the ACP spawn spec for an agent, or undefined if the harness does not speak ACP. */
 export function getAcpSpec(agent) {
     return ACP_HARNESSES[agent];
 }
-/** True if the harness is known to support ACP (directly or via adapter). */
 export function supportsAcp(agent) {
     return ACP_HARNESSES[agent] !== undefined;
 }

package/dist/lib/acp/run.d.ts

@@ -1,10 +1,3 @@
-/**
- * Headless ACP runner.
- *
- * Glue between the `agents run <agent> "prompt" --acp` command and the ACP
- * client. Emits either a human-readable stream of agent messages or newline-
- * delimited JSON events, depending on `--json`.
- */
 import type { AgentId } from '../types.js';
 import type { ExecMode } from '../exec.js';
 interface HeadlessAcpOptions {
@@ -14,6 +7,5 @@ interface HeadlessAcpOptions {
     mode: ExecMode;
     json: boolean;
 }
-/** Runs a prompt turn over ACP, streaming output to stdout per `json` mode. */
 export declare function runAcpHeadless(opts: HeadlessAcpOptions): Promise<number>;
 export {};

package/dist/lib/acp/run.js

@@ -1,12 +1,4 @@
-/**
- * Headless ACP runner.
- *
- * Glue between the `agents run <agent> "prompt" --acp` command and the ACP
- * client. Emits either a human-readable stream of agent messages or newline-
- * delimited JSON events, depending on `--json`.
- */
 import { runAcp } from './client.js';
-/** Runs a prompt turn over ACP, streaming output to stdout per `json` mode. */
 export async function runAcpHeadless(opts) {
     const onUpdate = opts.json ? emitJsonLine : emitTextChunk;
     const result = await runAcp({

package/dist/lib/actor.d.ts

@@ -2,99 +2,29 @@ import { type PhoenixSession } from './identity/client.js';
 import type { ActorConfig } from './types.js';
 export type ActorKind = 'human' | 'agent';
 export interface ResolvedActor {
-    /**
-     * Stable id for the responsible entity: the tailnet login (usually an email)
-     * for a resolved human, or `UNRESOLVED@<host>` when it can't be determined.
-     */
     id: string;
     kind: ActorKind;
-    /** Human-readable name, for git author + display. */
     name?: string;
-    /** Email, for git author + as a durable key. */
     email?: string;
-    /** GitHub handle, when the actors map records one. */
     github?: string;
-    /**
-     * Phoenix (work) identity id for this human, when the actors map records one.
-     * Bridges a personal tailnet login (e.g. a personal gmail) to the stable
-     * internal work identity, so attribution survives whichever email a person
-     * happens to be signed into tailscale with.
-     */
     phoenixId?: string;
-    /**
-     * The human's hosted profile picture (https URL) from the Phoenix ID session
-     * signed in on this device, attached only when that session belongs to the
-     * same email as the resolved actor. Rides the env as `AGENTS_ACTOR_AVATAR` so
-     * tools the agent runs (artifacts, shares) can show the person, not initials.
-     */
     avatarUrl?: string;
 }
-/** Result of `tailscale whois --json <ip>` we care about. */
 interface WhoisIdentity {
     login?: string;
     displayName?: string;
 }
-/**
- * Map a resolved tailnet identity (+ the actors map) to a ResolvedActor. Pure --
- * the impure whois/config reads happen in computeActor -- so the enrich/override
- * path is fully testable. No login (local, or an unnameable peer) yields the
- * honest `UNRESOLVED@<host>`; a login without a config entry still credits git
- * from the tailnet DisplayName + login email.
- */
 export declare function actorFromIdentity(who: WhoisIdentity | undefined, host: string, actors: Record<string, ActorConfig>): ResolvedActor;
-/**
- * The Phoenix ID profile picture for a resolved human, when the session signed
- * in on this device is that same person (matched on email, case-insensitive).
- * A shared box signed in as someone else must not lend its picture to whoever
- * SSH-ed in, so a mismatch yields nothing. Pure: the session is injected.
- */
+export declare function httpsUrl(value: string | undefined): string | undefined;
 export declare function actorAvatar(actor: ResolvedActor, session: PhoenixSession | null): string | undefined;
-/**
- * Injectable tailscale resolvers, so tests can drive the SSH-whois and
- * local-self branches deterministically without a real tailscale on the box
- * (a dev machine that *is* on the tailnet would otherwise make the local path
- * non-deterministic). Production callers use the defaults.
- */
 interface ActorResolvers {
     whois: (ip: string) => WhoisIdentity | undefined;
     self: () => WhoisIdentity | undefined;
-    /** The Phoenix ID session on this device (a local file read, no network). */
     session: () => PhoenixSession | null;
 }
-/**
- * Compute the actor for a given environment. The only impurity is the tailscale
- * shell-out (injectable via `resolvers`), so tests drive every branch explicitly.
- *
- * Resolution order: an inherited env actor wins; otherwise an SSH run whois-es
- * its client IP; a local run (no SSH) credits the device's own tailnet owner;
- * and anything unresolvable degrades to `UNRESOLVED@<host>`. Note the self
- * fallback fires ONLY for a truly local run — an SSH run whose whois fails must
- * NOT be credited to the box owner (that would misattribute a remote human to
- * whoever owns the machine).
- */
 export declare function computeActor(env?: NodeJS.ProcessEnv, resolvers?: ActorResolvers): ResolvedActor;
-/**
- * Resolve the actor for the current process, cached for the process lifetime
- * (the SSH `whois` shell-out runs at most once).
- */
 export declare function resolveActor(): ResolvedActor;
-/**
- * Test-only: pin the tailscale resolvers `resolveActor()` uses, so a test that
- * exercises the cached production entrypoint (e.g. `withActorEnv()`) is isolated
- * from whether the box running it is on the tailnet. `computeActor` already takes
- * injected resolvers for its unit tests; this extends the same seam to the cached
- * path. Pass `undefined` to restore the real tailscale resolvers. Resets the
- * cache so the next `resolveActor()` recomputes under the new resolvers.
- */
 export declare function setActorResolvers(resolvers: ActorResolvers | undefined): void;
-/** Clear the per-process cache. For tests, and for env changes within a run. */
 export declare function resetActorCache(): void;
-/**
- * The env an actor propagates to child processes. Always carries the actor id +
- * kind (so children inherit and don't re-resolve). For a resolved human with a
- * real name and email, it also carries `GIT_AUTHOR_*` / `GIT_COMMITTER_*` so the
- * agent's own commits are credited to the person, not the shared account. An
- * unresolved actor sets no git identity -- git keeps its ambient config.
- */
 export declare function actorEnv(actor: ResolvedActor): Record<string, string>;
 export {};

package/dist/lib/actor.js

@@ -1,41 +1,9 @@
-/**
- * Actor provenance -- who initiated a run.
- *
- * One shared account means every session, commit, and event otherwise shows up
- * as the same person. `resolveActor()` answers "which human is behind this run"
- * by looking at how the process was reached:
- *
- *   - Over SSH (the shared-fleet case): `tailscale whois` the SSH client IP to
- *     the connecting tailnet identity -- a real name + login email.
- *   - Locally (non-SSH): the run belongs to whoever owns this device on the
- *     tailnet, so we read that owner from `tailscale status` (`.Self.UserID` ->
- *     `.User[]`). Only if tailscale can't name the device owner either do we fall
- *     back to the honest `UNRESOLVED@<host>` with no personal git identity claimed.
- *   - Inherited: a child spawn trusts the `AGENTS_ACTOR*` env its parent
- *     stamped rather than re-resolving, so the whole spawn tree shares one actor.
- *
- * The resolved actor rides the child-process env (`actorEnv()`, merged into
- * `buildExecEnv`). When the actor is a resolved human, that env also carries
- * `GIT_AUTHOR_*` / `GIT_COMMITTER_*`, so the agent's own `git commit` is credited
- * to the person instead of the shared account.
- *
- * The optional `actors:` map in agents.yaml enriches or overrides a resolved
- * identity (pin a work email, add a github handle, mark an entry as an agent).
- */
 import { spawnSync } from 'child_process';
 import { machineId } from './machine-id.js';
 import { parseSshConnection } from './session/provenance.js';
 import { readSession } from './identity/client.js';
 import { readMeta } from './state.js';
-/** Hard cap on the whois shell-out — it runs on the spawn hot path. */
 const WHOIS_TIMEOUT_MS = 2000;
-/**
- * Resolve the tailnet identity behind an IP via `tailscale whois`. Returns
- * undefined when tailscale is absent, the peer is unknown, the call fails, or it
- * exceeds WHOIS_TIMEOUT_MS -- every one of those falls back to an unresolved
- * actor, never an error and never a hang (a wedged tailscaled is timed out, not
- * waited on, since this sits in buildExecEnv on every agent spawn).
- */
 function tailscaleWhois(ip) {
     try {
         const res = spawnSync('tailscale', ['whois', '--json', ip], {
@@ -43,8 +11,6 @@ function tailscaleWhois(ip) {
             windowsHide: true,
             timeout: WHOIS_TIMEOUT_MS,
         });
-        // A timeout leaves status null (child killed by SIGTERM) -- the status guard
-        // below treats it as an unresolved actor, same as any other failure.
         if (res.status !== 0 || !res.stdout)
             return undefined;
         const data = JSON.parse(res.stdout);
@@ -57,15 +23,6 @@ function tailscaleWhois(ip) {
         return undefined;
     }
 }
-/**
- * Resolve this device's own tailnet owner via `tailscale status --json`:
- * `.Self.UserID` indexes into the `.User` map for the owner's login + display
- * name. Used for a LOCAL run, where there is no SSH client to whois — the run
- * belongs to whoever owns the box on the tailnet. Same graceful-undefined +
- * timeout discipline as `tailscaleWhois`: tailscale absent, a wedged daemon, a
- * tagged (owner-less) device, or a parse failure all yield undefined, never an
- * error and never a hang on the spawn hot path.
- */
 function tailscaleSelf() {
     try {
         const res = spawnSync('tailscale', ['status', '--json'], {
@@ -79,7 +36,6 @@ function tailscaleSelf() {
         const uid = data.Self?.UserID;
         if (uid == null)
             return undefined;
-        // The User map is keyed by the UserID rendered as a string.
         const u = data.User?.[String(uid)];
         if (!u?.LoginName)
             return undefined;
@@ -89,7 +45,6 @@ function tailscaleSelf() {
         return undefined;
     }
 }
-/** Read the actors map from config, tolerant of a missing/unreadable config. */
 function readActors() {
     try {
         return readMeta().actors ?? {};
@@ -98,10 +53,6 @@ function readActors() {
         return {};
     }
 }
-/**
- * Find the actors-map entry for a resolved tailnet login. Matches on an entry's
- * explicit `login`, its map key, or its `email` (all case-insensitive).
- */
 function findActorConfig(login, actors) {
     const needle = login.toLowerCase();
     for (const [key, cfg] of Object.entries(actors)) {
@@ -111,13 +62,6 @@ function findActorConfig(login, actors) {
     }
     return undefined;
 }
-/**
- * Map a resolved tailnet identity (+ the actors map) to a ResolvedActor. Pure --
- * the impure whois/config reads happen in computeActor -- so the enrich/override
- * path is fully testable. No login (local, or an unnameable peer) yields the
- * honest `UNRESOLVED@<host>`; a login without a config entry still credits git
- * from the tailnet DisplayName + login email.
- */
 export function actorFromIdentity(who, host, actors) {
     const login = who?.login;
     if (!login) {
@@ -134,7 +78,6 @@ export function actorFromIdentity(who, host, actors) {
         phoenixId: cfg?.phoenixId,
     };
 }
-/** Reconstruct an actor an ancestor process already resolved into the env. */
 function inheritedActor(env) {
     const id = env.AGENTS_ACTOR;
     if (!id)
@@ -149,17 +92,10 @@ function inheritedActor(env) {
         avatarUrl: httpsUrl(env.AGENTS_ACTOR_AVATAR),
     };
 }
-/** An avatar is only ever an https URL; anything else is not an avatar. */
-function httpsUrl(value) {
+export function httpsUrl(value) {
     const trimmed = value?.trim();
     return trimmed && /^https:\/\/\S+$/i.test(trimmed) ? trimmed : undefined;
 }
-/**
- * The Phoenix ID profile picture for a resolved human, when the session signed
- * in on this device is that same person (matched on email, case-insensitive).
- * A shared box signed in as someone else must not lend its picture to whoever
- * SSH-ed in, so a mismatch yields nothing. Pure: the session is injected.
- */
 export function actorAvatar(actor, session) {
     if (actor.kind !== 'human' || !actor.email || !session?.email)
         return undefined;
@@ -168,17 +104,6 @@ export function actorAvatar(actor, session) {
     return httpsUrl(session.avatarUrl);
 }
 const defaultResolvers = { whois: tailscaleWhois, self: tailscaleSelf, session: readSession };
-/**
- * Compute the actor for a given environment. The only impurity is the tailscale
- * shell-out (injectable via `resolvers`), so tests drive every branch explicitly.
- *
- * Resolution order: an inherited env actor wins; otherwise an SSH run whois-es
- * its client IP; a local run (no SSH) credits the device's own tailnet owner;
- * and anything unresolvable degrades to `UNRESOLVED@<host>`. Note the self
- * fallback fires ONLY for a truly local run — an SSH run whose whois fails must
- * NOT be credited to the box owner (that would misattribute a remote human to
- * whoever owns the machine).
- */
 export function computeActor(env = process.env, resolvers = defaultResolvers) {
     const inherited = inheritedActor(env);
     if (inherited)
@@ -186,9 +111,6 @@ export function computeActor(env = process.env, resolvers = defaultResolvers) {
     const sshRaw = env.SSH_CONNECTION;
     const ssh = sshRaw ? parseSshConnection(sshRaw) : undefined;
     let who = ssh?.clientIp ? resolvers.whois(ssh.clientIp) : undefined;
-    // Self-credit only for a genuinely LOCAL run (no SSH_CONNECTION at all). An
-    // SSH session whose connection is unparseable or unresolvable stays
-    // UNRESOLVED rather than being misattributed to the box's owner.
     if (!who && !sshRaw)
         who = resolvers.self();
     const actor = actorFromIdentity(who, machineId(), readActors());
@@ -197,38 +119,18 @@ export function computeActor(env = process.env, resolvers = defaultResolvers) {
 }
 let cached;
 let resolverOverride;
-/**
- * Resolve the actor for the current process, cached for the process lifetime
- * (the SSH `whois` shell-out runs at most once).
- */
 export function resolveActor() {
     if (!cached)
         cached = computeActor(process.env, resolverOverride ?? defaultResolvers);
     return cached;
 }
-/**
- * Test-only: pin the tailscale resolvers `resolveActor()` uses, so a test that
- * exercises the cached production entrypoint (e.g. `withActorEnv()`) is isolated
- * from whether the box running it is on the tailnet. `computeActor` already takes
- * injected resolvers for its unit tests; this extends the same seam to the cached
- * path. Pass `undefined` to restore the real tailscale resolvers. Resets the
- * cache so the next `resolveActor()` recomputes under the new resolvers.
- */
 export function setActorResolvers(resolvers) {
     resolverOverride = resolvers;
     cached = undefined;
 }
-/** Clear the per-process cache. For tests, and for env changes within a run. */
 export function resetActorCache() {
     cached = undefined;
 }
-/**
- * The env an actor propagates to child processes. Always carries the actor id +
- * kind (so children inherit and don't re-resolve). For a resolved human with a
- * real name and email, it also carries `GIT_AUTHOR_*` / `GIT_COMMITTER_*` so the
- * agent's own commits are credited to the person, not the shared account. An
- * unresolved actor sets no git identity -- git keeps its ambient config.
- */
 export function actorEnv(actor) {
     const env = {
         AGENTS_ACTOR: actor.id,