@phnx-labs/agents-cli 1.20.89 → 1.20.90

package/CHANGELOG.md

@@ -1,5 +1,245 @@
 # Changelog
 
+## 1.20.90
+
+- **`agents sessions --active` now shows one row per agent, not one per directory.**
+  A live tmux agent pane whose durable identity records were missing (the common case
+  once meta/pid-registry entries age out) was dropped, then re-surfaced by the ps-scan
+  under the newest transcript in its cwd — so many distinct sessions collapsed onto one
+  stranger's id with an inflated `×N` badge, and `agents sessions focus <id>` could not
+  find them. The scanner now recovers the session id straight from the `ag-<agent>-<shortid>`
+  tmux pane name (resolved to the full UUID via the short-id index in one batched query),
+  and refuses to borrow a co-located sibling's transcript when no id is known — so every
+  live session surfaces as its own row and is focus-able again. Also adds a `runTmux`
+  timeout so a wedged tmux server can't hang the scan. Source: `apps/cli/src/lib/session/active.ts`.
+
+- **`agents view` now shows live usage bars for Antigravity.** The `agy` account
+  row renders one bar per model quota bucket (`3.1P: ███░░ 42% (1d)` style),
+  sourced from the same Google Code Assist `:retrieveUserQuota` endpoint `agy`
+  itself talks to. Auth reuses the stored `agy` OAuth credential (macOS Keychain
+  item `gemini`/`antigravity`, Linux Secret Service, or the
+  `~/.gemini/antigravity-cli/antigravity-oauth-token` file fallback), refreshing
+  the access token in memory when expired — safe from a read path because
+  Google's refresh tokens are non-rotating, and never written back to the
+  keychain. Each per-model bucket also flows into the throttle badge, run
+  rotation eligibility, and `agents view --json` (whose usage windows now carry
+  a `label` so same-keyed per-model bars are distinguishable). Source:
+  `apps/cli/src/lib/usage.ts`, `apps/cli/src/lib/agents.ts`,
+  `apps/cli/src/commands/view.ts`.
+
+- **A custom harness is now its own agent type in `agents view`.** A harness created
+  with `agents harness add` (or `agents profiles add`) used to render as an indented
+  `profile` row under whichever host CLI executes it. It now gets its own block beside
+  Claude and Codex — a bold name header, then one row carrying the pinned model, the
+  account/auth state, and `via <host> <version>` naming the native harness underneath.
+  That matches how it is already launched: `agents run <name>` treats a custom harness
+  exactly like a native agent id. A harness whose host CLI has no install is flagged
+  `(host <id> not installed)` rather than listed as runnable, and the separate
+  "Profile-only Agents" section is gone — those harnesses now render in the main list
+  like every other one. Source: `apps/cli/src/commands/view.ts`.
+- **`agents view <harness>` describes a custom harness** — host, model, provider, auth,
+  fork lineage, YAML path — instead of failing with "unknown agent";
+  `agents view <harness> --json` emits its summary. Source:
+  `apps/cli/src/commands/harness.ts` (`renderHarnessDetail`).
+- **New `agents harness fork <source> <name>`.** One verb over both starting points:
+  fork a native harness (`agents harness fork opencode deepseek --model
+  deepseek/deepseek-v4-flash-0731 --auth-provider openrouter`) or copy a custom one you
+  already tuned and change only what you name (`agents harness fork deepseek
+  deepseek-chat --model deepseek/deepseek-chat-v3`). Forking a custom harness is a full
+  copy — env, endpoint, auth binding, `fallback_model`, host version pin — so the two
+  diverge and deleting the source never affects the fork; forking a native harness
+  requires `--model` because there is no model to inherit. Flags: `--model`,
+  `--base-url`, `--auth-provider`, `--version`, `--label`, `--description`,
+  `--key-stdin`, `--force`. Source: `apps/cli/src/lib/profiles.ts` (`forkProfile`).
+- **Profile YAML gains optional `label:` and `forkedFrom:`.** `label` sets the name
+  `agents view` prints for the harness (defaults to the file name); `forkedFrom` records
+  the parent as display-only lineage. Existing profiles keep working untouched. Source:
+  `apps/cli/src/lib/profiles.ts`.
+- **Breaking (`--json`):** in `agents view <agent> --json`, the per-agent `profiles` key
+  is now `harnesses`, and each entry carries new `label`, `hostVersion`, `description`,
+  and `forkedFrom` fields alongside the existing ones. Source:
+  `apps/cli/src/commands/view.ts` (`ViewJsonAgent`).
+
+- **Menu bar ACTIVE: project accordion + session detail submenu.** Projects are
+  collapsed by default as a status strip (`▶ agents-cli  ●8 ◐1  zion`); click
+  `▶`/`▼` to fold agents open under the project (idle-row caps removed — collapse
+  is the wall protection). Focusing an agent opens a side submenu with linkable
+  detail (work title URL, cwd, Linear ticket, GitHub PR, duration, copy session
+  id) from the warm `sessions --active` cache. Accordion reopen rebuilds from
+  cache only (no teams walk / no CLI schedule). Local/remote uses the same host
+  normalize as CLI `machineId()` so local rows are not mislabeled remote. Source:
+  `apps/cli/menubar/Sources/MenubarHelper/StatusItemController.swift`,
+  `LocalState.swift`, `Models.swift`.
+
+- **An offloaded editor tab no longer displays another session's id.** A Factory
+  tab launched with `agents run --host <device>` has no local agent process, but
+  the extension still resolved its "live" session id by reading the SessionStart
+  hook's `~/.agents/.cache/state/sessions/<pid>.json` for the local pid tree —
+  the pid of the ssh client. Those files are keyed by pid alone and are only
+  pruned when the pid is dead, so once the OS recycled a pid the tab adopted
+  whatever session had last held it: one remote tab showed the id and version of
+  an unrelated synthetic run from 20 days earlier while `/status` inside it
+  reported the truth. An offloaded tab now takes its identity from the device
+  instead of local disk, and a local tab rejects any state record whose
+  SessionStart timestamp predates the tab itself.
+- **`AGENT_TERMINAL_ID` now rides the SSH hop.** `agents run --host` forwarded
+  actor provenance but not the launching tab's terminal id, so the remote pid
+  registry recorded no terminal — leaving `agents sessions --active --host
+  <device>` unable to answer "which session is this tab running?" once the agent
+  moved on (a `/clear`, or an exit and rerun in the same tab).
+- **`agents sessions --active --json` now carries `terminalId`.** The pid registry
+  has always recorded it; the emitted row dropped it, so no consumer could join a
+  live session back to the editor tab that launched it.
+
+- **Balanced routing no longer launches into an account it only *thinks* has
+  headroom.** Account usage is cached per machine under stale-while-revalidate:
+  a snapshot up to 24h old was served instantly, and the background refresh that
+  should have corrected it lands after the pick is already made. On a box whose
+  refresh is failing that state is permanent — measured on `yosemite-s1`, every
+  Claude snapshot sat 26 hours to 2.7 days old, so balanced read
+  `muqsit@getrush.ai` as 48% used and launched into it while the account was at
+  its weekly cap; the session answered "You've hit your weekly limit" on its
+  first turn. Routing now caps how stale a snapshot may be when it is about to
+  decide (5 minutes), blocking on one bounded, parallel live read past that — and
+  no read at all inside the existing 2-minute fresh window, which back-to-back
+  launches hit. Display paths (`agents view`) keep the full 24h window and stay
+  off the network.
+- **A pick made on unconfirmed data says so.** When no account on the machine
+  could be refreshed, routing still launches — a broken refresh must not make a
+  box unusable — but the banner now reads `… (2 of 5 healthy, usage unverified —
+  no account could be refreshed)` instead of presenting a guess as a fact. An
+  account with a verified snapshot always wins over one with a stale snapshot,
+  even when the stale number looks emptier. This applies to `--strategy
+  available` as well as `balanced` — both route on the same cache, and
+  `available`'s headroom sort was inverted by a stale number in exactly the same
+  way. An explicit version preference is an instruction, not a ranking signal, so
+  it still wins.
+- **The mid-run failover chain is unchanged.** Declining to *pick* an account on
+  unconfirmed data and declining to *fail over to* it after the primary already
+  hit a 429 are different risks — by then the alternative is not launching at
+  all. Every eligible account stays in the failover chain; only the initial pick
+  prefers verified ones.
+
+- **`agents routines list` no longer reports another device's routine as failed.** Run
+  records are written into the runs dir of whichever machine fired the routine and carry
+  no device attribution, but the listing resolved Last Status from any local record and
+  rendered it even on rows for routines pinned elsewhere. A routine re-pinned to another
+  device therefore kept reporting the old machine's leftover records forever — on zion,
+  `security-sweep`, `review-open-prs` and `hetzner-lease-gc` all read `failed` from late
+  July while `yosemite-s0`/`s1`, the devices that actually fire them, had completed them
+  that morning. The macOS menu bar reads this JSON, so it painted a column of red `exit 1`
+  rows for routines that were green. Last Status is now scoped to the device that owns the
+  run: a routine this device does not fire shows `-`, and `--json` returns `null` for
+  `lastStatus`, `exitCode`, `failureReason`, `lastRunStartedAt` and `lastRunCompletedAt`
+  (`runsHere: false` already says why). A routine pinned to several devices renders one row
+  per device but carries a status only on its **This machine** row. Read a peer's status
+  with `agents routines list --device <name>`; the local history is untouched and still
+  readable via `agents routines runs <name>`. Source: `apps/cli/src/commands/routines.ts`
+  (`localLatestRun`, `groupRoutineJobsByDevice`), `apps/cli/docs/03-routines.md`.
+
+- **`agents watchdog` now tracks per-session presence (RUSH-2007 Layer C).** Each
+  tick reconciles a per-session presence record — `{location, device, transport,
+  lastSeen, status}` at `~/.agents/.cache/state/watchdog/presence.json` — from the
+  tick's active scan, deriving `connected` / `disconnected` by diffing consecutive
+  ticks. A session that was tracked but is now absent (its SSH link dropped or the
+  peer went unreachable) flips to `disconnected`, and the flip is surfaced in
+  `agents watchdog --json` under `presence.transitions` — an interactive drop as a
+  `reconnect-nudge` candidate, a headless remote as `keep-alive`. Folded into the
+  existing tick (no revived daemon, no extra SSH fan-out); additive and does not
+  change the tick's nudge decisions. Source:
+  `apps/cli/src/lib/session/presence.ts`, `apps/cli/src/lib/watchdog/runner.ts`.
+
+- **`agents setup secrets --policy hold` no longer fails, and `agents secrets
+  status` stops naming the retired `daily` policy.** The 1.20.79 `daily` → `hold`
+  rename swept the help, docs, and the `secrets list` POLICY column, but two
+  surfaces were never migrated. The worse one was functional: the onboarding
+  wizard carried its own copy of the policy vocabulary, so
+  `agents setup secrets --policy hold` — the canonical name every other secrets
+  command prints — exited with `Invalid --policy 'hold'. Use daily, always, or
+  never.`, and its interactive prompt still offered `daily` as the default
+  choice. It now shares `parsePolicyOpt` with `agents secrets policy`, so the two
+  commands can't disagree about what a policy is called; `daily`/`session` stay
+  accepted as aliases and the wizard's default is unchanged (the hold tier). The
+  second was cosmetic: `agents secrets status` printed "a daily bundle prompts
+  once…" and "the next read of each daily bundle…" — the one command a user runs
+  to answer *why did it prompt again*, naming a policy its sibling commands no
+  longer emit. Both lines now say `hold` and are pure values pinned by tests, so
+  the vocabulary can't drift again. Source:
+  `apps/cli/src/commands/setup-secrets.ts`, `apps/cli/src/commands/secrets.ts`.
+
+- **Favorite sessions from the browser.** `*` stars the highlighted session in
+  `agents sessions` and `f` filters the list to the starred ones; outside a TTY,
+  `agents sessions favorite <id>` (`--remove` / `--list` / `--json`) and
+  `agents sessions --favorites` do the same. Stars live in
+  `~/.agents/.history/favorites.json` keyed by session id, so they survive a reindex
+  of the session cache. They are per-machine — session sync carries transcripts, not
+  this file. Source:
+  `apps/cli/src/lib/session/favorites.ts`, `apps/cli/src/commands/sessions-favorite.ts`.
+- **Detect sessions that lost their host — two new statuses, `crashed` and `orphaned`.**
+  A session whose editor window or connection went down hard used to just VANISH from
+  `agents sessions --active` (its dead-pid registry entry was filtered out), and one
+  still running in tmux with nobody attached reported a plain `idle`. Both now say so:
+  `✗ crashed` when the host window stopped republishing and the agent died with it,
+  `◍ orphan` when the agent is alive with zero clients attached. Derived from tmux's
+  `#{session_attached}` and the IDE window's registry heartbeat — never from a
+  deliberate `agents sessions detach`, and never over a session that is still working.
+  Source: `apps/cli/src/lib/session/host-link.ts`, `apps/cli/src/lib/session/active.ts`.
+- **`agents sessions --active --favorites` now actually filters.** The flag was wired
+  into the interactive browser only, so every path that skips it — `--json`,
+  `--waiting`, a pipe, a multi-host scope, an SSH-fanout peer — silently returned the
+  whole fleet. Source: `apps/cli/src/commands/sessions.ts`.
+- **`agents sessions --active --waiting` no longer counts a dead session.** `activity`
+  is not rewritten when a session dies, so one that crashed mid-question reported "needs
+  your input" forever — what it needs is a relaunch. Source:
+  `apps/cli/src/commands/sessions.ts`.
+
+- **Resolve historical sessions safely across the fleet (#1757).** `agents sessions --resolve <full-id|prefix|keywords> --json` uses a versioned safe peer protocol, returns only resolver metadata, reports every full-ID candidate on ambiguity, treats synced copies as one match, and exits 2 without deciding when a peer fails, returns malformed output, or runs an older CLI. Source: `apps/cli/src/commands/sessions.ts`.
+
+- **A rate-limited usage endpoint is now backed off instead of hammered.** The
+  daemon warms auth-health every 3 minutes and probes *every installed version
+  home* in one parallel batch, so a machine with five Claude accounts sent five
+  concurrent requests to `api.anthropic.com/api/oauth/usage` every three minutes
+  — roughly 100/hour — before the usage refresh added its own. Nothing read
+  `Retry-After`. Measured on `yosemite-s1`: the endpoint answered
+  `429 rate_limit_error` with `retry-after: 2678` (about 45 minutes) for every
+  account while the credentials themselves read healthy, and the next tick fired
+  three minutes later, deep inside the penalty window, re-arming it. The box
+  never recovered, every usage read failed, and its cache froze — the
+  permanently-stale state balanced routing was already having to defend against.
+- **A 429 now records its deadline and every read honours it.** Usage fetches and
+  health probes for that provider short-circuit until the window passes — no
+  request, no renewed penalty — and report
+  `Claude rate-limited this machine — not retrying for 45 minutes.` The state is
+  on disk, because the callers are separate processes: the long-lived daemon and
+  every one-shot `agents view` / `agents run` — one empty file per penalty under
+  `~/.agents/.cache/usage-backoff/`, named `<agent>.<deadline>`, so two
+  processes recording the same provider at once cannot displace each other and a
+  read takes the furthest deadline. A server delay is capped at an hour, and a
+  missing or unparseable `Retry-After` still backs off.
+
+- **A usage read that fails now says so, instead of returning a silent null.**
+  Four branches in every networked usage fetch — Claude, Kimi, Droid and
+  Cursor — returned `{ snapshot: null, error: null }`: no readable credential, a
+  locally-expired one, a rejected request, and a request that threw (timeout,
+  DNS/TLS, an unparseable payload). The caller could not tell any of them apart
+  from a healthy read, so it fell
+  back to whatever the stale-while-revalidate cache held and drew those bars as
+  fact. Measured on `yosemite-s1`: every Claude account's stored access token had
+  expired (one of them eleven days earlier), so no read could succeed, and
+  `agents view claude --refresh` printed a full, healthy-looking table twice
+  while writing nothing to the cache. A usage read never refreshes a token
+  (RUSH-1822), so an expired credential does not heal on its own — the account
+  stays unreadable until that agent actually runs. A rate-limited endpoint (429)
+  now reads differently from a rejected credential (401), because re-authing
+  fixes one and not the other.
+- **`agents view` marks bars the live read could not confirm.** A row whose
+  snapshot came from the cache after a failed live read renders the reading plus
+  `unverified`, rather than looking identical to a confirmed one. The number
+  still shows — it is the last thing we saw — but it no longer reads as current.
+- **`agents view --refresh` reports what it could not refresh.** It now lists
+  each account it failed to reach and why, instead of rendering a table that
+  looks fully refreshed regardless.
+
 ## 1.20.89
 
 - **Webhook handler layer for one-off agent/workflow/command/routine triggers.**

package/README.md

@@ -265,6 +265,8 @@ On a terminal, `agents sessions --active` (and a bare `agents sessions`) open th
 |---|---|---|
 | `s` | search text | `--query` / positional |
 | `r` | running only | `--active` |
+| `f` | favorites only | `--favorites` |
+| `*` | star / unstar the highlighted session | `agents sessions favorite <id>` |
 | `c` | team sessions | `--teams` |
 | `a` | agent (cycles) | `-a` |
 | `d` | device (cycles) | `--device` |
@@ -274,6 +276,10 @@ On a terminal, `agents sessions --active` (and a bare `agents sessions`) open th
 | `⏎` | resume / attach | `resume` / `focus` |
 | `y` | copy the equivalent command | `--print-cmd` |
 
+**Star the sessions you keep coming back to.** `*` marks the highlighted row (a `★` shows in the listing), `f` narrows to the starred ones, and `agents sessions favorite <id>` / `--favorites` do the same outside a TTY. Stars live in `~/.agents/.history/favorites.json` keyed by session id, so they survive a reindex of the session cache. They're per-machine — session sync carries transcripts, not this file.
+
+**A session that lost its host says so.** When an editor window or an SSH connection goes down hard, the agent it owned used to simply disappear from `--active`; when an agent outlived its window in tmux, it reported a plain `idle`. Both now carry their own status: `✗ crashed` (the host went down and took the agent with it) and `◍ orphan` (still alive, but no client is attached — nothing is showing it). Read from tmux's attached-client count and the editor window's registry heartbeat, so a deliberate `agents sessions detach` is never mistaken for one, and a session that is still *working* headlessly is left alone.
+
 Filters **stack** (they AND together), the active set shows in the header, and the highlighted row **previews below by default** (`tab` hides it) — prompt, activity, last response, plus a links line where the worked-on ticket and the PR the session opened are **clickable** (OSC 8 hyperlinks: the ticket jumps to Linear, the `PR#` to GitHub, in terminals that support them). The Linear workspace is resolved from `LINEAR_WORKSPACE` or the linear-cli config, so tickets stay plain text when it's unknown. Because every hotkey has a flag, the view you build by hand is a real command: press `y` (or run `--print-cmd`) to get the exact `ag sessions …` line — explore interactively, hand the line to an agent. Piped output, `--json`, or `--no-interactive` keep the plain listing for scripts. Peek without opening the pager with `agents sessions <id> --preview`.
 
 | before — preview hidden | after — preview open + clickable links |

package/dist/commands/exec.js

@@ -59,7 +59,13 @@ function formatRotationBanner(result, verb = 'balanced') {
     const { picked, healthy, excluded } = result;
     const label = picked.email ? `${picked.email} · ${picked.agent}@${picked.version}` : `${picked.agent}@${picked.version}`;
     const ratio = `${healthy.length} of ${healthy.length + excluded.length} healthy`;
-    return `[agents] ${verb} picked ${label} (${ratio})`;
+    // Say it when the pick was a guess. A machine whose usage refresh is failing
+    // reports old percentages with total confidence, so a silent banner reads
+    // identical whether the router knew the account had headroom or merely hoped
+    // so — and the operator only finds out when the agent answers "you've hit
+    // your weekly limit".
+    const caveat = result.usageUnverified ? ', usage unverified — no account could be refreshed' : '';
+    return `[agents] ${verb} picked ${label} (${ratio}${caveat})`;
 }
 /**
  * Whether `cwd` is inside a git work tree.

package/dist/commands/harness.d.ts

@@ -11,4 +11,31 @@
  * native harness registry. The `agents profiles` tree stays unchanged.
  */
 import type { Command } from 'commander';
+import { type Profile } from '../lib/profiles.js';
+/**
+ * Print one custom harness. Shared by `agents harness view <name>` and by
+ * `agents view <name>` — a custom harness resolves as an agent type there, so
+ * both entry points must describe it identically.
+ */
+export declare function renderHarnessDetail(name: string): void;
+/** Options accepted by `agents harness fork`. */
+export interface ForkOptions {
+    model?: string;
+    baseUrl?: string;
+    authProvider?: string;
+    version?: string;
+    label?: string;
+    description?: string;
+    keyStdin?: boolean;
+    force?: boolean;
+}
+/**
+ * Build the new harness for `agents harness fork <source> <name>`.
+ *
+ * Two sources, one verb: an existing custom harness is copied and overridden;
+ * a native agent id is turned into a harness pinned to `--model` on that host.
+ * Forking a native harness therefore requires `--model` — there is nothing to
+ * copy a model from.
+ */
+export declare function buildFork(source: string, name: string, opts: ForkOptions): Profile;
 export declare function registerHarnessCommands(program: Command): void;

package/dist/commands/harness.js

@@ -11,15 +11,82 @@
  * native harness registry. The `agents profiles` tree stays unchanged.
  */
 import chalk from 'chalk';
-import { addProfile } from './profiles.js';
-import { listProfiles, readProfile, deleteProfile, profileHostLabel, profileProviderLabel, profileModelLabel, profileAuthLabel, getProfilePath, } from '../lib/profiles.js';
+import { addProfile, ensureProviderToken } from './profiles.js';
+import { listProfiles, readProfile, writeProfile, deleteProfile, profileExists, profileHostLabel, profileProviderLabel, profileModelLabel, profileAuthLabel, profileLabel, forkProfile, profileFromHostModel, authEnvKeyForHost, getProfilePath, validateProfileName, } from '../lib/profiles.js';
 import { listPresets } from '../lib/profiles-presets.js';
-import { AGENTS, ALL_AGENT_IDS } from '../lib/agents.js';
+import { AGENTS, ALL_AGENT_IDS, resolveAgentName } from '../lib/agents.js';
 /** Short capability summary for a native harness — its supported run modes. */
 function nativeModes(id) {
     const modes = AGENTS[id]?.capabilities?.modes ?? [];
     return modes.length ? modes.join('/') : '-';
 }
+/**
+ * Print one custom harness. Shared by `agents harness view <name>` and by
+ * `agents view <name>` — a custom harness resolves as an agent type there, so
+ * both entry points must describe it identically.
+ */
+export function renderHarnessDetail(name) {
+    const p = readProfile(name);
+    console.log(chalk.bold(profileLabel(p)) + chalk.gray('  (custom harness)'));
+    if (p.description)
+        console.log(chalk.gray(p.description));
+    console.log('');
+    console.log(`Host:     ${profileHostLabel(p)}`);
+    console.log(`Model:    ${profileModelLabel(p)}`);
+    if (p.fallback_model)
+        console.log(`Fallback: ${p.fallback_model}`);
+    console.log(`Provider: ${profileProviderLabel(p)}`);
+    console.log(`Auth:     ${profileAuthLabel(p)}`);
+    if (p.forkedFrom)
+        console.log(`Forked:   from ${p.forkedFrom}`);
+    console.log(chalk.gray(getProfilePath(p.name)));
+    console.log('');
+    console.log(chalk.gray(`Run: agents run ${p.name} "hello"`));
+}
+/**
+ * Build the new harness for `agents harness fork <source> <name>`.
+ *
+ * Two sources, one verb: an existing custom harness is copied and overridden;
+ * a native agent id is turned into a harness pinned to `--model` on that host.
+ * Forking a native harness therefore requires `--model` — there is nothing to
+ * copy a model from.
+ */
+export function buildFork(source, name, opts) {
+    if (profileExists(source)) {
+        return forkProfile(readProfile(source), name, {
+            model: opts.model,
+            baseUrl: opts.baseUrl,
+            provider: opts.authProvider,
+            version: opts.version,
+            label: opts.label,
+            description: opts.description,
+        });
+    }
+    const host = resolveAgentName(source);
+    if (!host) {
+        throw new Error(`No harness or agent named '${source}'.\n` +
+            `Fork from a custom harness (agents harness list) or a native one: ${ALL_AGENT_IDS.join(', ')}.`);
+    }
+    if (!opts.model) {
+        throw new Error(`--model <id> is required when forking the native '${host}' harness (there is no model to inherit).`);
+    }
+    return profileFromHostModel(name, host, opts.model, {
+        version: opts.version,
+        baseUrl: opts.baseUrl,
+        provider: opts.authProvider,
+        authEnvVar: opts.authProvider ? authEnvKeyForHostOrThrow(host) : undefined,
+        label: opts.label,
+        description: opts.description ?? `Forked from ${host}: ${opts.model}`,
+    });
+}
+/** Auth env var for a host, as a hard error when the host declares none. */
+function authEnvKeyForHostOrThrow(host) {
+    const key = authEnvKeyForHost(host);
+    if (!key) {
+        throw new Error(`--auth-provider is set but host '${host}' has no known auth env var; it manages its own login.`);
+    }
+    return key;
+}
 export function registerHarnessCommands(program) {
     const cmd = program
         .command('harness')
@@ -30,11 +97,18 @@ A custom harness pins a host CLI (opencode, claude, codex, grok, antigravity, ..
 model and gives it a name. 'agents run <name>' then behaves like a native agent
 type, and 'agents repo push user' syncs it to every device.
 
+A custom harness is its own agent type in 'agents view' — its own block beside Claude
+and Codex, not a row indented under the host CLI that executes it.
+
 Examples:
   # Meta Muse Spark 1.1 through OpenCode, called 'spark'
   agents harness add spark --host opencode --model meta/muse-spark-1.1
   agents run spark "refactor api/handlers/checkout.py"
 
+  # Fork a native harness, or copy one of your own and swap the model
+  agents harness fork opencode deepseek --model deepseek/deepseek-v4-flash-0731 --auth-provider openrouter
+  agents harness fork deepseek deepseek-chat --model deepseek/deepseek-chat-v3
+
   # Per-run model override still wins
   agents run spark --model opencode/big-pickle "quick pass"
 
@@ -66,6 +140,48 @@ Examples:
             process.exit(1);
         }
     });
+    cmd
+        .command('fork <source> <name>')
+        .description('Fork a native harness (claude, opencode, ...) or an existing custom one into a new named harness.')
+        .option('--model <id>', 'Model to pin on the fork (required when forking a native harness)')
+        .option('--base-url <url>', 'Custom endpoint base URL (claude/codex hosts)')
+        .option('--auth-provider <provider>', 'Attach a keychain-backed API key under this provider')
+        .option('--version <version>', 'Pin the host CLI version (e.g., 1.16.0)')
+        .option('--label <text>', 'Human-facing name shown by `agents view` (defaults to <name>)')
+        .option('--description <text>', 'One-line description')
+        .option('--key-stdin', 'Read the API key from stdin instead of prompting (for scripts/CI)')
+        .option('--force', 'Overwrite an existing harness with the same name')
+        .addHelpText('after', `
+Examples:
+  # Fork OpenCode into a harness pinned to a DeepSeek model on OpenRouter
+  agents harness fork opencode deepseek --model deepseek/deepseek-v4-flash-0731 --auth-provider openrouter
+
+  # Fork Claude Code onto a private gateway
+  agents harness fork claude corp --model gpt-x --base-url https://gw.corp/v1 --auth-provider corp
+
+  # Copy an existing harness and swap only the model
+  agents harness fork deepseek deepseek-chat --model deepseek/deepseek-chat-v3
+`)
+        .action(async (source, name, opts) => {
+        try {
+            validateProfileName(name);
+            if (profileExists(name) && !opts.force) {
+                throw new Error(`Harness '${name}' already exists. Use --force to overwrite.`);
+            }
+            // Build first so a bad source/flag combination fails before prompting
+            // for a key the user would then have stored for nothing.
+            const forked = buildFork(source, name, opts);
+            if (opts.authProvider)
+                await ensureProviderToken(opts.authProvider, undefined, opts.keyStdin);
+            writeProfile(forked);
+            console.log(chalk.green(`Harness '${name}' forked from ${source}.`));
+            console.log(chalk.gray(`Try: agents run ${name} "hello"`));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
     cmd
         .command('list')
         .alias('ls')
@@ -114,16 +230,7 @@ Examples:
         .description('Show one custom harness (host, model, provider, auth, path).')
         .action((name) => {
         try {
-            const p = readProfile(name);
-            console.log(chalk.bold(p.name));
-            if (p.description)
-                console.log(chalk.gray(p.description));
-            console.log('');
-            console.log(`Host:     ${profileHostLabel(p)}`);
-            console.log(`Model:    ${profileModelLabel(p)}`);
-            console.log(`Provider: ${profileProviderLabel(p)}`);
-            console.log(`Auth:     ${profileAuthLabel(p)}`);
-            console.log(chalk.gray(getProfilePath(p.name)));
+            renderHarnessDetail(name);
         }
         catch (err) {
             console.error(chalk.red(err.message));

package/dist/commands/profiles.d.ts

@@ -15,6 +15,9 @@ import { type Preset } from '../lib/profiles-presets.js';
  * without mocking @inquirer/prompts.
  */
 export declare function buildProfileFromCollection(name: string, preset: Preset, collected: Record<string, string>, version?: string): Profile;
+/** Read all available data from stdin synchronously, trimmed. */
+/** Ensure a provider API key exists in keychain, prompting or reading stdin if missing. */
+export declare function ensureProviderToken(provider: string, signupUrl?: string, fromStdin?: boolean): Promise<void>;
 /** Options accepted by {@link addProfile} — shared by `agents profiles add` and `agents harness add`. */
 export interface AddProfileOptions {
     preset?: string;

package/dist/commands/profiles.js

@@ -47,7 +47,7 @@ async function promptForSecret(message) {
 }
 /** Read all available data from stdin synchronously, trimmed. */
 /** Ensure a provider API key exists in keychain, prompting or reading stdin if missing. */
-async function ensureProviderToken(provider, signupUrl, fromStdin) {
+export async function ensureProviderToken(provider, signupUrl, fromStdin) {
     const item = keychainItemName(provider);
     if (hasKeychainToken(item)) {
         return;

package/dist/commands/routines.d.ts

@@ -14,10 +14,29 @@ import type { DeviceRegistry } from '../lib/devices/registry.js';
  * callers drop it straight into a status line.
  */
 export declare function formatRunDuration(startedAt: string, completedAt: string | null): string;
+/**
+ * The last run THIS device can speak for.
+ *
+ * A run record is written by whichever daemon fired the routine, into that
+ * machine's own runs dir — records carry no device attribution, so a record
+ * found here only ever describes this device's history. When a routine is
+ * pinned away from this machine (`devices:` excludes it) any local record is a
+ * leftover from before the pin, and reporting it as the routine's status paints
+ * another device's healthy routine red. Report nothing instead; the local
+ * history stays readable via `agents routines runs <name>`, and the owning
+ * device's status via `agents routines list --device <name>`.
+ */
+export declare function localLatestRun(job: JobConfig): RunMeta | null;
 export interface RoutineListGroup {
     key: string;
     title: string;
     jobs: JobConfig[];
+    /**
+     * Whether this device's run records describe the group. False for a
+     * `Device: <peer>` group — the rows are the same routine seen from a machine
+     * that does not fire it there, so Last Status is not ours to report.
+     */
+    local: boolean;
 }
 export declare function groupRoutineJobsByDevice(jobs: JobConfig[], registry: DeviceRegistry, self?: string): RoutineListGroup[];
 export declare function buildRunsJson(runs: RunMeta[]): Record<string, unknown>[];

package/dist/commands/routines.js

@@ -138,6 +138,21 @@ function deviceLabel(job, width) {
         : raw;
     return { raw, display, dim: full.length === 0 || !jobRunsOnThisDevice(job) };
 }
+/**
+ * The last run THIS device can speak for.
+ *
+ * A run record is written by whichever daemon fired the routine, into that
+ * machine's own runs dir — records carry no device attribution, so a record
+ * found here only ever describes this device's history. When a routine is
+ * pinned away from this machine (`devices:` excludes it) any local record is a
+ * leftover from before the pin, and reporting it as the routine's status paints
+ * another device's healthy routine red. Report nothing instead; the local
+ * history stays readable via `agents routines runs <name>`, and the owning
+ * device's status via `agents routines list --device <name>`.
+ */
+export function localLatestRun(job) {
+    return jobRunsOnThisDevice(job) ? getLatestRun(job.name) : null;
+}
 export function groupRoutineJobsByDevice(jobs, registry, self = machineId()) {
     const groups = new Map();
     const add = (key, title, job) => {
@@ -146,7 +161,9 @@ export function groupRoutineJobsByDevice(jobs, registry, self = machineId()) {
             existing.jobs.push(job);
             return;
         }
-        groups.set(key, { key, title, jobs: [job] });
+        // `device:` is the only group that describes a machine other than this one,
+        // so it is the only one whose rows this device cannot report a status for.
+        groups.set(key, { key, title, jobs: [job], local: !key.startsWith('device:') });
     };
     for (const job of jobs) {
         const strategy = resolveHostStrategy(job);
@@ -193,7 +210,7 @@ export function groupRoutineJobsByDevice(jobs, registry, self = machineId()) {
     };
     return [...groups.values()].sort((a, b) => order(a) - order(b) || a.title.localeCompare(b.title));
 }
-function renderRoutineRows({ jobs, scheduler, overdueSet, link, now }) {
+function renderRoutineRows({ jobs, scheduler, overdueSet, link, now, local = true }) {
     const NAME_W = 24;
     const AGENT_W = 10;
     const REPO_W = REPO_DISPLAY_MAX;
@@ -207,7 +224,7 @@ function renderRoutineRows({ jobs, scheduler, overdueSet, link, now }) {
     for (const job of jobs) {
         const nextStr = nextRunLabel(job, scheduler, now);
         const schedStr = scheduleLabel(job);
-        const latestRun = getLatestRun(job.name);
+        const latestRun = local ? localLatestRun(job) : null;
         const lastStatus = latestRun?.status || '-';
         const sourceRepo = job.source?.repo ?? job.repo;
         const sourceLabel = sourceRepo
@@ -509,7 +526,7 @@ export function registerRoutinesCommands(program) {
         if (options.json) {
             const nowJson = new Date();
             const payload = jobs.map((job) => {
-                const latestRun = getLatestRun(job.name);
+                const latestRun = localLatestRun(job);
                 return {
                     name: job.name,
                     agent: job.agent ?? null,
@@ -562,9 +579,14 @@ export function registerRoutinesCommands(program) {
             catch (err) {
                 console.error(chalk.yellow(`Could not read device registry: ${err.message}`));
             }
-            for (const group of groupRoutineJobsByDevice(jobs, registry)) {
+            const groups = groupRoutineJobsByDevice(jobs, registry);
+            for (const group of groups) {
                 console.log(chalk.bold(`\n${group.title}`));
-                renderRoutineRows({ jobs: group.jobs, scheduler, overdueSet, link, now });
+                renderRoutineRows({ jobs: group.jobs, scheduler, overdueSet, link, now, local: group.local });
+            }
+            if (groups.some((group) => !group.local)) {
+                console.log();
+                console.log(chalk.gray('  Last Status is per-device: rows under another device show "-" — read it there with: agents routines list --device <name>'));
             }
         }
         if (overdueSet.size > 0) {

package/dist/commands/secrets.d.ts

@@ -80,10 +80,19 @@ export declare function exportBundleToFile(env: Record<string, string>, filePath
  */
 export declare function importBundleFromFile(filePath: string, passphrase: string): Record<string, string>;
 /** The POLICY column for `secrets list`: the prompt policy, plus a concise
- * state hint. `daily` shows `held Nh` when the secrets-agent is currently
+ * state hint. `hold` shows `held Nh` when the secrets-agent is currently
  * caching the bundle; `always` and `never` show whether they prompt. `held`
  * maps bundle name → expiry epoch-ms (from agentStatus()). */
 export declare function renderPolicyCol(b: SecretsBundle, held?: Map<string, number>): string;
+/** The hold-window line at the top of `secrets status`. Names the `hold` policy
+ * the window belongs to — the rename in #1604 left this surface still saying
+ * "daily", the one name the CLI no longer accepts in its own help. Pure so the
+ * vocabulary is pinned by a test rather than re-drifting on the next rename. */
+export declare function renderHoldSummary(holdStr: string, configured: boolean): string;
+/** The empty-broker line under the hold summary. Named here, beside
+ * `renderHoldSummary`, for the same reason: it is the second line the rename
+ * left saying `daily`, and a test pins both. */
+export declare const NO_BUNDLES_HELD_LINE = "No bundles held. The next read of each hold-policy bundle will prompt once, then hold.";
 /** Human-readable hold window for `secrets status`. Sub-hour values render in
  * minutes (so a near-floor `holdMs` never shows a confusing "0 hours"), whole
  * hours up to 2 days, whole days beyond. Pure — unit-tested. */