@phnx-labs/agents-cli 1.22.7 → 1.22.8

package/dist/lib/browser/remote-control.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Consent gate for driving THIS machine's browser from another fleet machine.
+ *
+ * `browser --host <device>` routes a browser command to `<device>` over SSH (the
+ * fleet passthrough) and runs `agents browser ...` there. Every such remote
+ * invocation carries the {@link FLEET_REMOTE_ENV} marker, set once at the fleet
+ * dispatch site (`maybeRunOnHost`). A machine only accepts being driven when its
+ * owner has opted in via `agents browser remote-control on` (the device-scope
+ * `browser.remote-control` config key, never synced).
+ *
+ * Local invocations (no marker) are never gated — this only governs cross-machine
+ * drives. Read-only queries are not gated here; the gate sits at the drive entry
+ * point (`browser start`), the one command that opens/attaches a browser.
+ */
+/** Env marker set on every remote `agents` invocation by `buildRemoteAgentsInvocation`. */
+export declare const FLEET_REMOTE_ENV = "AGENTS_FLEET_REMOTE";
+/** True when this process was dispatched to this machine by a fleet `--host` run. */
+export declare function isFleetRemoteInvocation(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Whether this machine allows other fleet machines to drive its browser. Reads
+ * the device-scope `browser.remote-control` config key. Unset = off (deny).
+ */
+export declare function remoteControlEnabled(): boolean;
+/**
+ * Guard the browser-drive entry point. A fleet-remote invocation may only drive
+ * this machine's browser when the owner opted in; otherwise throw a clear,
+ * actionable error. A local invocation is never gated.
+ *
+ * `env` and `enabled` are injectable so the decision is unit-testable without a
+ * real remote hop or a real config store.
+ */
+export declare function assertRemoteControlAllowed(opts?: {
+    env?: NodeJS.ProcessEnv;
+    enabled?: boolean;
+}): void;

package/dist/lib/browser/remote-control.js

@@ -0,0 +1,48 @@
+/**
+ * Consent gate for driving THIS machine's browser from another fleet machine.
+ *
+ * `browser --host <device>` routes a browser command to `<device>` over SSH (the
+ * fleet passthrough) and runs `agents browser ...` there. Every such remote
+ * invocation carries the {@link FLEET_REMOTE_ENV} marker, set once at the fleet
+ * dispatch site (`maybeRunOnHost`). A machine only accepts being driven when its
+ * owner has opted in via `agents browser remote-control on` (the device-scope
+ * `browser.remote-control` config key, never synced).
+ *
+ * Local invocations (no marker) are never gated — this only governs cross-machine
+ * drives. Read-only queries are not gated here; the gate sits at the drive entry
+ * point (`browser start`), the one command that opens/attaches a browser.
+ */
+import { getConfigValue } from '../device-config.js';
+/** Env marker set on every remote `agents` invocation by `buildRemoteAgentsInvocation`. */
+export const FLEET_REMOTE_ENV = 'AGENTS_FLEET_REMOTE';
+/** True when this process was dispatched to this machine by a fleet `--host` run. */
+export function isFleetRemoteInvocation(env = process.env) {
+    return env[FLEET_REMOTE_ENV] === '1';
+}
+/**
+ * Whether this machine allows other fleet machines to drive its browser. Reads
+ * the device-scope `browser.remote-control` config key. Unset = off (deny).
+ */
+export function remoteControlEnabled() {
+    return getConfigValue('browser.remote-control').value === true;
+}
+/**
+ * Guard the browser-drive entry point. A fleet-remote invocation may only drive
+ * this machine's browser when the owner opted in; otherwise throw a clear,
+ * actionable error. A local invocation is never gated.
+ *
+ * `env` and `enabled` are injectable so the decision is unit-testable without a
+ * real remote hop or a real config store.
+ */
+export function assertRemoteControlAllowed(opts) {
+    const env = opts?.env ?? process.env;
+    if (!isFleetRemoteInvocation(env))
+        return;
+    const enabled = opts?.enabled ?? remoteControlEnabled();
+    if (enabled)
+        return;
+    const who = env.AGENTS_ACTOR_HOST || env.AGENTS_ACTOR || 'A fleet machine';
+    throw new Error(`${who} tried to drive this machine's browser over \`browser --host\`, but remote ` +
+        `browser control is off here. To allow it, run on THIS machine:\n` +
+        `  agents browser remote-control on`);
+}

package/dist/lib/browser/service.d.ts

@@ -50,6 +50,22 @@ export interface HealInfo {
     role: string;
     name: string;
 }
+/**
+ * Resolve the identity stamped on a task at start: WHO (`owner`) and WHICH run
+ * (`launchId`). The forwarded values come from the caller's own CLI process and
+ * are authoritative — the browser daemon is shared and long-lived, so resolving
+ * the actor daemon-side (the RUSH-2020 bug) mis-attributes every task to the
+ * daemon's owner. `resolveLocalActor` is consulted ONLY when no actor was
+ * forwarded (a CLI that predates the field, mid-rollout) — never to override a
+ * forwarded one.
+ */
+export declare function resolveTaskIdentity(forwarded: {
+    actor?: string;
+    launchId?: string;
+}, resolveLocalActor: () => string): {
+    owner: string;
+    launchId?: string;
+};
 export declare class BrowserService {
     private static readonly SOURCE_PREFIX;
     private connections;
@@ -64,6 +80,9 @@ export declare class BrowserService {
         url?: string;
         endpointName?: string;
         skipDomainSkill?: boolean;
+        /** Caller identity, forwarded from the CLI (see IPCRequest.actor/launchId). */
+        actor?: string;
+        launchId?: string;
     }): Promise<{
         task: string;
         name: string;

package/dist/lib/browser/service.js

@@ -222,6 +222,21 @@ async function isConnHealthy(conn, timeoutMs = 1000) {
         return false;
     }
 }
+/**
+ * Resolve the identity stamped on a task at start: WHO (`owner`) and WHICH run
+ * (`launchId`). The forwarded values come from the caller's own CLI process and
+ * are authoritative — the browser daemon is shared and long-lived, so resolving
+ * the actor daemon-side (the RUSH-2020 bug) mis-attributes every task to the
+ * daemon's owner. `resolveLocalActor` is consulted ONLY when no actor was
+ * forwarded (a CLI that predates the field, mid-rollout) — never to override a
+ * forwarded one.
+ */
+export function resolveTaskIdentity(forwarded, resolveLocalActor) {
+    return {
+        owner: forwarded.actor ?? resolveLocalActor(),
+        launchId: forwarded.launchId,
+    };
+}
 export class BrowserService {
     static SOURCE_PREFIX = {
         'rush-app': 'rush-app-',
@@ -332,7 +347,10 @@ export class BrowserService {
             currentTabId: undefined,
             createdAt: Date.now(),
             pid: conn.pid,
-            owner: resolveActor().id, // who launched this browser task (RUSH-2020)
+            // Identity is forwarded from the caller (see resolveTaskIdentity): WHO
+            // (owner) and WHICH run (launchId). Resolving daemon-side would attribute
+            // every task to the shared daemon's actor (the RUSH-2020 bug).
+            ...resolveTaskIdentity({ actor: opts.actor, launchId: opts.launchId }, () => resolveActor().id),
         };
         // For Electron, get the existing window as the tab
         if (conn.electron) {

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

@@ -79,10 +79,20 @@ export interface Task {
     createdAt: number;
     pid: number;
     /**
-     * Resolved actor id (`resolveActor().id`) stamped at task start — who launched
-     * this browser task. Optional: tasks persisted before RUSH-2020 carry none.
+     * Resolved actor id (`resolveActor().id`) stamped at task start — WHO launched
+     * this browser task (a person/agent identity, stable across runs). Forwarded
+     * from the caller over IPC — the daemon is shared, so it cannot resolve the
+     * caller's actor itself. Optional: tasks persisted before RUSH-2020 carry none.
      */
     owner?: string;
+    /**
+     * The caller's per-run launch id (`$AGENT_LAUNCH_ID`, minted by exec.ts for
+     * every harness) stamped at task start — WHICH run created this task. Distinct
+     * from `owner`: two runs by the same actor get different launchIds, which is
+     * the scope the current-task default and `status --mine` filter on. Forwarded
+     * from the caller over IPC. Optional: tasks from before this shipped carry none.
+     */
+    launchId?: string;
     /**
      * Per-tab snapshot of the last ref listing captured for that tab
      * (shortId -> {descriptors, opts}). Persisted to tasks.json so a later
@@ -184,6 +194,8 @@ export interface IPCRequest {
     until?: string;
     appLevel?: string;
     skipDomainSkill?: boolean;
+    actor?: string;
+    launchId?: string;
 }
 /** Subset of IPCResponse describing a recording start result. */
 export interface RecordStartFields {

package/dist/lib/device-config.js

@@ -67,6 +67,14 @@ export const CONFIG_KEYS = [
         type: 'bool',
         description: 'Whether the routines scheduler (daemon) may fire on this device.',
     },
+    {
+        name: 'browser.remote-control',
+        yamlKey: 'browserRemoteControl',
+        scope: 'device',
+        type: 'bool',
+        description: "Whether other fleet machines may drive THIS device's browser over `browser --host <this-device>`. " +
+            'Default off — a fleet-remote drive is refused until the owner runs `agents browser remote-control on`.',
+    },
     {
         name: 'notes',
         yamlKey: 'notes',

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

@@ -16,7 +16,7 @@
  * table or, when `--host`/`--device` is present, exits with a clear
  * "not supported" message — never commander's raw `unknown option`.
  */
-import { type DeviceRegistry } from '../devices/registry.js';
+import { type DeviceProfile, type DeviceRegistry } from '../devices/registry.js';
 import { runLocalCommand, runOnDevice } from '../devices/fleet.js';
 /** Per-command remote behaviour. Absence from this map = not host-routable here. */
 interface RemoteSpec {
@@ -36,6 +36,15 @@ export interface FleetPassthroughOptions {
     /** Override this machine's id (tests). Defaults to `machineId()`. */
     self?: string;
 }
+/**
+ * Prefix a fan-out remote command so the far side sees AGENTS_FLEET_REMOTE=1 —
+ * the same marker the single-target dispatch sets via env. `wrapRemoteCommand`
+ * joins the argv with spaces (POSIX) or base64-encodes it for PowerShell, so a
+ * shell-appropriate leading token rides through both: `env VAR=1 …` on POSIX,
+ * `$env:VAR='1'; …` on PowerShell. Only remote (non-self) targets get it; the
+ * self target runs locally and must stay ungated.
+ */
+export declare function markFleetRemote(cmd: string[], device: DeviceProfile): string[];
 /** Run `agents <command> …` across every registered device and render the roster. */
 export declare function runFleetPassthrough(command: string, allArgs: string[], spec: RemoteSpec, opts?: FleetPassthroughOptions): Promise<boolean>;
 /**

package/dist/lib/hosts/passthrough.js

@@ -319,6 +319,19 @@ function renderFleetRoster(command, forwarded, results, self) {
         console.log(chalk.gray(summaryParts.join(' · ')));
     }
 }
+/**
+ * Prefix a fan-out remote command so the far side sees AGENTS_FLEET_REMOTE=1 —
+ * the same marker the single-target dispatch sets via env. `wrapRemoteCommand`
+ * joins the argv with spaces (POSIX) or base64-encodes it for PowerShell, so a
+ * shell-appropriate leading token rides through both: `env VAR=1 …` on POSIX,
+ * `$env:VAR='1'; …` on PowerShell. Only remote (non-self) targets get it; the
+ * self target runs locally and must stay ungated.
+ */
+export function markFleetRemote(cmd, device) {
+    return device.shell === 'powershell'
+        ? [`$env:AGENTS_FLEET_REMOTE='1';`, ...cmd]
+        : ['env', 'AGENTS_FLEET_REMOTE=1', ...cmd];
+}
 /** Run `agents <command> …` across every registered device and render the roster. */
 export async function runFleetPassthrough(command, allArgs, spec, opts = {}) {
     const self = opts.self ?? machineId();
@@ -335,7 +348,12 @@ export async function runFleetPassthrough(command, allArgs, spec, opts = {}) {
     const results = await fanOutDevices(targets, async (target) => {
         const cmd = ['agents', ...forwarded];
         const isSelf = target.device.name.toLowerCase() === self.toLowerCase() || isSelfHost(target.device.name);
-        const res = isSelf ? localRunner(cmd) : runner(target.device, cmd);
+        // Only `browser` consults the fleet-remote marker (its consent gate), and
+        // the fan-out has no separate env channel — the marker must ride the argv.
+        // So scope the env-prefix to a REMOTE browser drive: every other command's
+        // remote argv stays byte-identical, and the self target is never gated.
+        const remoteCmd = !isSelf && command === 'browser' ? markFleetRemote(cmd, target.device) : cmd;
+        const res = isSelf ? localRunner(cmd) : runner(target.device, remoteCmd);
         if (res.code !== 0) {
             const detail = (res.stderr || res.stdout || 'unreachable').trim().slice(0, 200);
             throw new Error(detail || 'unreachable');
@@ -500,7 +518,10 @@ export async function maybeRunOnHost(command, allArgs, opts) {
     // UNDER the doctor PATH so that PATH still wins — without this the remote
     // re-resolves the actor from THIS box's SSH_CONNECTION and mis-credits it
     // (RUSH-2028). Flows to both POSIX (export) and Windows ($env:) dialects.
-    const env = withActorEnv(doctorPath);
+    // AGENTS_FLEET_REMOTE marks this as a fleet-dispatched `--host` run so the far
+    // side can gate consent-sensitive actions — the browser consent gate
+    // (lib/browser/remote-control.ts) reads it to allow/deny a cross-machine drive.
+    const env = withActorEnv({ ...doctorPath, AGENTS_FLEET_REMOTE: '1' });
     const remoteCmd = buildRemoteAgentsInvocation(forwarded, remoteCwd, remoteOs, env);
     const code = sshStream(target, remoteCmd, { tty: interactive, multiplex: true });
     if (code === 255) {

package/dist/lib/hosts/remote-cmd.js

@@ -105,6 +105,7 @@ export const RUN_OPTION_FORWARDING = {
     disableTmux: 'local-only',
     host: 'local-only',
     device: 'local-only',
+    where: 'local-only', // expands into host/lease before dispatch; never re-forwarded
     on: 'local-only',
     computer: 'local-only',
     any: 'local-only',

package/dist/lib/placement.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Placement — one model for "where does the body run?"
+ *
+ * The CLI grew several doors that all mean execution target:
+ *   run --host / --device / --lease / --box
+ *   routines --placement / --run-on / hostStrategy
+ *   monitors --run-on (body) vs --device (owner — NOT placement)
+ *   teams --device (teammate pin)
+ *   cloud run --provider host
+ *
+ * This module is the shared vocabulary. Old flags remain; --where is a
+ * thin alias on `agents run` that expands into them. Docs and help teach
+ * the matrix; stores stay separate (device registry, lease boxes, cloud).
+ *
+ * Owner (who may fire / evaluate) is NOT placement — see monitors.
+ */
+/** Where a job body executes. */
+export type PlacementKind = 'local' | 'device' | 'fleet' | 'cloud' | 'lease';
+/**
+ * Canonical placement object.
+ *
+ *   kind: local  — this machine
+ *   kind: device — named box or affinity pick (target: name | "auto")
+ *   kind: fleet  — pick one online device at fire time (routines)
+ *   kind: cloud  — vendor cloud dispatch
+ *   kind: lease  — disposable crabbox (target: optional backend)
+ */
+export interface Placement {
+    kind: PlacementKind;
+    /** Device/host name, "auto", lease backend, or undefined. */
+    target?: string;
+    /** Flag or path that produced this (errors / diagnostics). */
+    source: string;
+}
+/** Run-flag bag the placement parser understands. */
+export interface RunPlacementFlags {
+    where?: string;
+    host?: string;
+    device?: string;
+    on?: string;
+    computer?: string;
+    lease?: string | boolean;
+    box?: string;
+}
+export declare class PlacementError extends Error {
+    constructor(message: string);
+}
+/**
+ * Parse a `--where` / placement spec string.
+ *
+ * Accepted forms:
+ *   local
+ *   device[:name] | host[:name]   (bare name → device:<name>)
+ *   device:auto | auto | host:auto
+ *   fleet
+ *   cloud
+ *   lease[:backend]
+ */
+export declare function parseWhereSpec(raw: string, source?: string): Placement;
+/** First non-empty host-family flag value (host / device / on / computer). */
+export declare function hostFamilyTarget(flags: RunPlacementFlags): string | undefined;
+/**
+ * Resolve placement from run flags. `--where` wins only when no other
+ * placement flag is set; mixing is a PlacementError.
+ */
+export declare function placementFromRunFlags(flags: RunPlacementFlags): Placement;
+/**
+ * Expand a resolved placement into the concrete run option fields the
+ * existing dispatch paths already understand. Pure — does not mutate input.
+ *
+ * `cloud` and `fleet` are not valid for a bare `agents run` (use `cloud run`
+ * / routines); they throw so callers fail loud.
+ */
+export declare function expandPlacementToRunFlags(placement: Placement): Pick<RunPlacementFlags, 'host' | 'device' | 'lease' | 'box'>;
+/** Map routines hostStrategy (+ optional host) onto the shared Placement. */
+export declare function placementFromHostStrategy(strategy: 'local' | 'host' | 'fleet' | 'cloud', host?: string): Placement;
+/** One-line human form for logs / help. */
+export declare function formatPlacement(p: Placement): string;
+/**
+ * Short matrix for help footers and docs. Keep in sync with 00-concepts.md.
+ */
+export declare const PLACEMENT_MATRIX: string;

package/dist/lib/placement.js

@@ -0,0 +1,188 @@
+/**
+ * Placement — one model for "where does the body run?"
+ *
+ * The CLI grew several doors that all mean execution target:
+ *   run --host / --device / --lease / --box
+ *   routines --placement / --run-on / hostStrategy
+ *   monitors --run-on (body) vs --device (owner — NOT placement)
+ *   teams --device (teammate pin)
+ *   cloud run --provider host
+ *
+ * This module is the shared vocabulary. Old flags remain; --where is a
+ * thin alias on `agents run` that expands into them. Docs and help teach
+ * the matrix; stores stay separate (device registry, lease boxes, cloud).
+ *
+ * Owner (who may fire / evaluate) is NOT placement — see monitors.
+ */
+export class PlacementError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PlacementError';
+    }
+}
+const KINDS = new Set(['local', 'device', 'fleet', 'cloud', 'lease', 'host']);
+/**
+ * Parse a `--where` / placement spec string.
+ *
+ * Accepted forms:
+ *   local
+ *   device[:name] | host[:name]   (bare name → device:<name>)
+ *   device:auto | auto | host:auto
+ *   fleet
+ *   cloud
+ *   lease[:backend]
+ */
+export function parseWhereSpec(raw, source = '--where') {
+    const spec = raw.trim();
+    if (!spec) {
+        throw new PlacementError(`${source} requires a value (local | device:<name> | auto | lease | cloud | fleet)`);
+    }
+    const lower = spec.toLowerCase();
+    if (lower === 'local')
+        return { kind: 'local', source };
+    if (lower === 'auto')
+        return { kind: 'device', target: 'auto', source };
+    if (lower === 'fleet')
+        return { kind: 'fleet', source };
+    if (lower === 'cloud')
+        return { kind: 'cloud', source };
+    if (lower === 'lease')
+        return { kind: 'lease', source };
+    const colon = spec.indexOf(':');
+    if (colon === -1) {
+        // Bare token that is not a reserved kind → device target.
+        if (KINDS.has(lower)) {
+            // "device" / "host" alone means device with no pin (invalid for run).
+            throw new PlacementError(`${source} ${spec}: name a target (device:<name>, device:auto) or use local|lease|cloud|fleet`);
+        }
+        return { kind: 'device', target: spec, source };
+    }
+    const head = spec.slice(0, colon).toLowerCase();
+    const tail = spec.slice(colon + 1).trim();
+    if (!tail) {
+        throw new PlacementError(`${source} ${spec}: missing target after ':'`);
+    }
+    if (head === 'device' || head === 'host') {
+        return { kind: 'device', target: tail, source };
+    }
+    if (head === 'lease') {
+        return { kind: 'lease', target: tail, source };
+    }
+    if (head === 'cloud') {
+        return { kind: 'cloud', target: tail, source };
+    }
+    if (head === 'fleet') {
+        return { kind: 'fleet', target: tail, source };
+    }
+    throw new PlacementError(`${source} ${spec}: unknown kind '${head}' (use local | device:<name> | auto | lease[:backend] | cloud | fleet)`);
+}
+/** First non-empty host-family flag value (host / device / on / computer). */
+export function hostFamilyTarget(flags) {
+    for (const v of [flags.host, flags.device, flags.on, flags.computer]) {
+        if (v)
+            return v;
+    }
+    return undefined;
+}
+/**
+ * Resolve placement from run flags. `--where` wins only when no other
+ * placement flag is set; mixing is a PlacementError.
+ */
+export function placementFromRunFlags(flags) {
+    const where = flags.where?.trim();
+    const hostT = hostFamilyTarget(flags);
+    const hasLease = flags.lease !== undefined && flags.lease !== false;
+    const hasBox = !!flags.box;
+    const placementFlags = [];
+    if (where)
+        placementFlags.push('--where');
+    if (hostT)
+        placementFlags.push('--host/--device');
+    if (hasLease)
+        placementFlags.push('--lease');
+    if (hasBox)
+        placementFlags.push('--box');
+    if (placementFlags.length > 1) {
+        throw new PlacementError(`Conflicting placement flags: ${placementFlags.join(' + ')}. ` +
+            `Use one door — prefer --where (device:<name> | auto | lease | local).`);
+    }
+    if (where)
+        return parseWhereSpec(where, '--where');
+    if (hasBox)
+        return { kind: 'lease', target: flags.box, source: '--box' };
+    if (hasLease) {
+        const backend = typeof flags.lease === 'string' ? flags.lease : undefined;
+        return { kind: 'lease', target: backend, source: '--lease' };
+    }
+    if (hostT)
+        return { kind: 'device', target: hostT, source: '--host/--device' };
+    return { kind: 'local', source: 'default' };
+}
+/**
+ * Expand a resolved placement into the concrete run option fields the
+ * existing dispatch paths already understand. Pure — does not mutate input.
+ *
+ * `cloud` and `fleet` are not valid for a bare `agents run` (use `cloud run`
+ * / routines); they throw so callers fail loud.
+ */
+export function expandPlacementToRunFlags(placement) {
+    switch (placement.kind) {
+        case 'local':
+            return {};
+        case 'device':
+            if (!placement.target) {
+                throw new PlacementError(`${placement.source}: device placement needs a target (name or auto)`);
+            }
+            // Canonical host flag; --device is an alias of the same path.
+            return { host: placement.target };
+        case 'lease':
+            // --box reuses a warm slug; --where lease[:backend] / --lease provisions.
+            if (placement.source === '--box')
+                return { box: placement.target };
+            return placement.target ? { lease: placement.target } : { lease: true };
+        case 'fleet':
+            throw new PlacementError(`fleet placement is for routines (agents routines add … --placement fleet), not agents run. ` +
+                `Use --where device:auto for an affinity pick, or --where device:<name>.`);
+        case 'cloud':
+            throw new PlacementError(`cloud placement is agents cloud run (vendor cloud), not agents run. ` +
+                `For a disposable box use --where lease; for your fleet use --where device:<name>.`);
+    }
+}
+/** Map routines hostStrategy (+ optional host) onto the shared Placement. */
+export function placementFromHostStrategy(strategy, host) {
+    switch (strategy) {
+        case 'local':
+            return { kind: 'local', source: 'hostStrategy:local' };
+        case 'host':
+            return { kind: 'device', target: host, source: 'hostStrategy:host' };
+        case 'fleet':
+            return { kind: 'fleet', source: 'hostStrategy:fleet' };
+        case 'cloud':
+            return { kind: 'cloud', source: 'hostStrategy:cloud' };
+    }
+}
+/** One-line human form for logs / help. */
+export function formatPlacement(p) {
+    if (p.kind === 'local')
+        return 'local';
+    if (p.target)
+        return `${p.kind}:${p.target}`;
+    return p.kind;
+}
+/**
+ * Short matrix for help footers and docs. Keep in sync with 00-concepts.md.
+ */
+export const PLACEMENT_MATRIX = `
+  Intent                         Flag / path
+  ─────────────────────────────  ──────────────────────────────────────────
+  This machine                   (default)  or  --where local
+  Named fleet box                --where device:<name>   (= --host / --device)
+  Affinity pick (14d usage)      --where auto            (= --device auto)
+  Disposable cloud box           --where lease           (= --lease)
+  Reuse warm crabbox             --box <slug>
+  Routines: body on one box      --run-on <name> / --placement host
+  Routines: pick any online      --placement fleet
+  Vendor cloud task              agents cloud run …
+  Monitors: who evaluates        --device <owner>   (NOT body placement)
+  Monitors: where action runs    --run-on <host>
+`.trim();

package/dist/lib/profiles.d.ts

@@ -31,9 +31,10 @@ export interface Profile {
     preset?: string;
     provider?: string;
     /**
-     * Human-facing label for the harness — what `agents view` prints as the
-     * agent-type header, the same slot `AGENTS[id].name` fills for a native
-     * harness. Defaults to the profile name when unset.
+     * Stored for backward-compatible YAML parsing only — no longer read for
+     * display. `profileLabel()` always derives the display name from `name` via
+     * the vendor/brand table. Old YAML files that carry this key still parse
+     * correctly; it is simply ignored.
      */
     label?: string;
     /**
@@ -71,7 +72,7 @@ export interface Profile {
  */
 export interface ProfileSummary {
     name: string;
-    /** Human-facing header label — `label` when set, else the profile name. */
+    /** Human-facing header label — always derived from `name` via the vendor/brand table. */
     label: string;
     agent: AgentId;
     host: string;
@@ -125,8 +126,12 @@ export declare function profileModelEnvKey(profile: Profile): string | null;
  */
 export declare function profileAuthLabel(profile: Profile): string;
 /**
- * Header label for the harness — the slot `AGENTS[id].name` fills for a native
- * harness, so `agents view` can print custom and native harnesses the same way.
+ * Header label for the harness — derived from `profile.name` by splitting on
+ * `[-_]` and mapping each token through the vendor/brand table. Never reads
+ * the stored `label` field; old YAML files with a `label:` key are unaffected.
+ *
+ * Examples: `deepseek-flash` → `'DeepSeek Flash'`, `spark` → `'Spark'`,
+ * `deepseek_chat_v3` → `'DeepSeek Chat V3'`.
  */
 export declare function profileLabel(profile: Profile): string;
 /** Build a stable, machine-readable summary for list and view surfaces. */
@@ -153,8 +158,6 @@ export interface HostModelOptions {
     /** Env var the host reads its auth token from; pair with `provider` to attach keychain auth. */
     authEnvVar?: string;
     description?: string;
-    /** Human-facing header label; defaults to the harness name. */
-    label?: string;
 }
 /**
  * Build a custom-harness profile from a host CLI + model in one shot, without a
@@ -176,7 +179,6 @@ export interface ForkProfileOptions {
     authEnvVar?: string;
     /** Re-pin (or unpin, with an empty string) the host CLI version. */
     version?: string;
-    label?: string;
     description?: string;
 }
 /**
@@ -185,6 +187,26 @@ export interface ForkProfileOptions {
  * diverge from here and deleting the source never affects the fork.
  */
 export declare function forkProfile(source: Profile, name: string, opts?: ForkProfileOptions): Profile;
+/**
+ * Edit an existing profile in-place, applying overrides without changing its
+ * name or lineage. Reuses {@link forkProfile}'s validation and override logic
+ * (model swap, base-URL validation, auth repoint), then restores the original
+ * `forkedFrom` so an edit never self-references the profile.
+ *
+ * Note: this returns the updated `Profile` object but does NOT write it to
+ * disk — callers should follow up with `writeProfile(result)` if persistence
+ * is needed.
+ */
+export declare function editProfile(source: Profile, opts?: ForkProfileOptions): Profile;
+/**
+ * Rename a profile on disk, then rewrite `forkedFrom` in every other profile
+ * that pointed at the old name so lineage display never goes stale.
+ *
+ * Throws if `oldName` does not exist or `newName` already exists. There is no
+ * `--force` / overwrite path — a collision is a hard error directing the user
+ * to remove the target first.
+ */
+export declare function renameProfile(oldName: string, newName: string): void;
 /**
  * Resolve a profile into the env block that should be injected into the
  * spawned agent process. Reads the token from keychain at exec time so the