@phnx-labs/agents-cli 1.22.8 → 1.22.10

package/CHANGELOG.md

@@ -1,5 +1,65 @@
 # Changelog
 
+## 1.22.10
+
+- **Plugins package workflows (Phase 5 packaging slice).** A plugin’s `workflows/<name>/WORKFLOW.md` is discovered and resolved by `agents run <name>` with precedence project > user > plugin > extra > system — no separate install into `~/.agents/workflows/` required. Plugin inventory / resource groups list `workflows`. Source: `apps/cli/src/lib/workflows.ts`, `apps/cli/src/lib/plugins.ts`, `apps/cli/src/lib/resources/workflows.ts`.
+
+- **`scripts/release.sh` routes the home-base publish hop via `agents ssh`.** Plain `ssh mac-mini` fails host-key checks on headless Linux workers; `agents ssh` uses the devices registry and brokered credentials. Falls back to plain ssh only when `agents` is not on PATH. Source: `apps/cli/scripts/release.sh`.
+
+- **Touch ID is now raised in exactly one place — `agents secrets unlock`.** `agents secrets list`, `agents run <agent>`, `secrets get`/`export`/`view`, and every background read resolve from the secrets broker / durable session / no-ACL layer and never raise a biometric sheet; a locked keychain bundle fails with an actionable "run `agents secrets unlock <bundle>`" hint instead of prompting. The `AGENTS_SECRETS_NO_PROMPT` environment override and the "a human at a TTY, so prompting is fine" heuristic are deleted — the prompt decision is structural, not an ambient env var. The macOS keychain `list`/`list-synced` enumeration queries now pass `kSecUseAuthenticationUISkip` (enumeration itself was evaluating the biometry ACL, so `agents secrets list` prompted and silently dropped keychain bundles when the sheet was cancelled), and the one-time hash-rekey + metadata-ACL heal run only inside the single `unlock` sheet so nothing on the run/list path can storm. Source: `apps/cli/src/lib/secrets/keychain-helper.swift`, `apps/cli/src/lib/secrets/index.ts`, `apps/cli/src/lib/secrets/bundles.ts`, `apps/cli/src/lib/secrets/headless.ts`, `apps/cli/src/commands/secrets.ts`.
+- **The Factory VS Code extension (`swarm-ext`) no longer decrypts secrets or shells raw `ssh`.** Device health, reachability, and sync route every remote command through `agents ssh <host>` (broker-owned credentials, no prompt); the extension's own secret-resolution path (`resolveSecret`/`discoverSecretsReadCmd`/`extractCredentials`) is removed, so rendering the devices list never raises Touch ID. Source: `apps/factory/src/vscode/deviceHealth.vscode.ts`, `apps/factory/src/vscode/settings.vscode.ts`, `apps/factory/src/vscode/extension.ts`.
+
+## 1.22.9
+
+- **`agents ssh auto` and `agents teams add --device auto` no longer reject with "Unknown device 'auto'" (RUSH-2185).** The `auto` affinity sentinel was a `run`-only preprocessing step (`applyDeviceAutoToOptions` in `smart-launch.ts`, wired only from `agents run`'s exec path) — every other `--host`/`--device` caller went straight to the shared resolver, which had no idea what `auto` meant and reported it as an unregistered device. `matchHost` (the one core every `--host`/`--device` caller shares) now resolves `auto` directly via the same `resolveDeviceAffinity` engine `run` uses, so `agents ssh`, `agents teams add`, and anything else routed through `matchHost`/`resolveHost` (including the generic `--host`/`--device` passthrough) pick a device the same way. `agents teams add --device auto` landing on the local machine now just runs the teammate locally, matching `run`'s "null pick = local" outcome; `agents ssh auto` refuses a local pick with a clear message instead of self-SSHing, since `agents ssh` exists to dial OUT to a remote box. Source: `apps/cli/src/lib/hosts/registry.ts`, `apps/cli/src/lib/devices/resolve-target.ts`, `apps/cli/src/commands/ssh.ts`, `apps/cli/src/commands/teams.ts`, `apps/cli/docs/00-concepts.md`, `apps/cli/docs/hosts.md`, `apps/cli/docs/teams.md`.
+
+- **`agents harness edit` gains `--auth-provider`, `--fallback-model`, and `--from-secrets`; `add`/`fork` gain an interactive wizard and `--from-secrets`.** `edit` (already shipped with `--model`/`--base-url`/`--version`/`--description`) now also repoints auth at a different keychain-backed provider, sets or clears (`--fallback-model ""`) the same-host fallback model retried on a rate limit, and — like `add`/`fork` — accepts `--from-secrets <bundle>[:<key>]` to copy a value out of an existing `agents secrets` bundle into the harness's own keychain item once, instead of retyping a key already stored elsewhere (the item it writes to, `agents-cli.<provider>.token`, is never gated behind the biometry-required prefixes, so later reads stay silent). `agents harness add`/`fork` now accept `[name]`/`[source] [name]` as optional positionals — run either with insufficient flags in an interactive terminal and a picker (fork from a native host or existing harness → a built-in preset or "build custom" → the harness's name, pre-filled with the preset's own name → how to get the key) replaces the old hard error; flags remain fully supported for scripts, and a non-interactive shell still gets the original error. Source: `apps/cli/src/commands/harness.ts`, `apps/cli/src/commands/profiles.ts`, `apps/cli/docs/profiles.md`.
+
+- **`agents run --lease` is reuse-first against the crabbox profile pool, with a
+  `--fresh` opt-out.** A bare `--lease` used to always lease a brand-new box, so
+  bursts of runs (e.g. resumed sessions) stacked up idle `keep=true` boxes at
+  full monthly cost. Now, before warming a new box, the run looks for a warm box
+  carrying the same `profile` label the warmup would use (read from the repo's
+  `.crabbox.yaml`, matching `scripts/sandbox.sh`'s `pick_ready_box`) and the same
+  network mode — a tailnet box is never handed to a public run or vice versa —
+  and reuses the first one `crabbox status` reports SSH-ready, keeping it after
+  the run. A not-ready pool box is skipped, never stopped. `--fresh` forces the
+  old behavior (brand-new box, torn down after the run); `--box <slug>` is
+  unchanged. Source: `apps/cli/src/lib/crabbox/lease.ts`,
+  `apps/cli/src/lib/crabbox/cli.ts`, `apps/cli/src/lib/crabbox/config.ts`,
+  `apps/cli/src/commands/exec.ts`.
+
+- **The menu bar now notices and reports when the scheduler dies — instead of
+  staying silent forever.** The only proactive "routines overdue / scheduler
+  down" signal was `notifyOverdue` (`src/lib/overdue.ts`), fired from inside
+  `runDaemon()` — so it could never fire while the daemon itself was down, the
+  exact outage it exists to report. `MenubarHelper` is a separate launchd
+  KeepAlive service that stays alive when the daemon dies, so its 10s tick now
+  polls daemon liveness independently of the dropdown ever being opened; once
+  it has been continuously unreachable for ~30s (debounced past a routine
+  restart blip), it fires one native notification ("Scheduler stopped —
+  routines won't run") through its own `NSUserNotificationCenter` delivery —
+  no daemon, no CLI spawn required — and lights the always-visible menu-bar
+  badge (`⏻`) until the scheduler comes back. Source:
+  `apps/cli/menubar/Sources/MenubarHelper/StatusItemController.swift`.
+
+- **Observe umbrella aliases: `inbox`, `timeline`, `roster` (Phase 3 surface consolidation).**
+  Thin doors onto existing readers (no store merge): `agents inbox` ≡ `feed`,
+  `agents timeline` ≡ `feed --filter updates`, `agents roster` ≡ `sessions --active`.
+  Root help gains an Observe section; `agents audit` stays the tamper-evident run
+  log (not an events alias). Source: `apps/cli/src/lib/observe-aliases.ts`,
+  `apps/cli/src/commands/feed.ts`, `apps/cli/src/commands/sessions.ts`.
+
+- **Daemon usage refresh is a fixed 5-minute per-host schedule, concurrency-safe, and Touch-ID-free.**
+  Each machine's daemon still owns its own usage cache (no fleet-wide store). Account live
+  fetches are now scheduled every **5 minutes** (was adaptive 90s–15m), with a 60s wake to
+  notice due accounts after backoff ends. Cache writes use a file lock + atomic rename so a
+  concurrent `agents view` background refresh cannot tear or drop rows. The daemon path
+  loads Claude credentials with **`fileOnly`** (setup-token / no-ACL cache / `.credentials.json`
+  only) and never opens the ACL-bound macOS keychain item, so a background tick cannot pop
+  Touch ID. Refresh still skips a provider under 429 backoff and still never rotates
+  single-use Claude refresh tokens.
+
 ## 1.22.8
 
 - **`agents browser` now gates cross-machine drives behind per-device consent.** `agents browser <cmd> --host <device>` already routes a browser command to another fleet machine over SSH and drives its browser — but nothing asked that machine's permission, so any box you could SSH to, you could drive. A new device-local `browser.remote-control` setting (off by default, never synced) fixes that: a fleet-remote `browser --host <this-machine> start` is refused with an actionable message until the owner runs `agents browser remote-control on` here. Local starts (no `--host`) are never gated. The fleet passthrough marks every `--host` dispatch with `AGENTS_FLEET_REMOTE` so the far side can tell a cross-machine drive from a local one. New command: `agents browser remote-control [on|off]` (no arg prints status; `--json` supported). Source: `apps/cli/src/lib/browser/remote-control.ts`, `apps/cli/src/commands/browser.ts`, `apps/cli/src/lib/hosts/passthrough.ts`, `apps/cli/src/lib/device-config.ts`, `apps/cli/docs/browser.md`.
@@ -983,6 +1043,8 @@
 
 ## 1.20.92
 
+- **`agents sessions render <id...>` produces shareable, redacted Markdown instead of raw harness JSONL.** Claude, Codex, Kimi, Grok, Cursor, and Droid transcripts flow through the existing normalized `SessionEvent[]` parsers, then render with the same session-browser preview at the top, ordered user/assistant turns, fenced shell commands, JSON tool arguments, and explicitly truncated tool results. Redaction remains on by default through the canonical redactor, now also masking Unix/macOS/Windows home-directory identities and live secret values; `--no-redact` is local-only. Reasoning defaults to omitted and can be folded or included explicitly. One or several selected sessions can be written to a mode-`0600` Markdown file, and `--json` exposes the rendered documents for machine callers. The repo session skill and transcript-sharing guidance now require rendering `.md` before creating a confidential gist. Source: `apps/cli/src/commands/sessions-render.ts`, `apps/cli/src/lib/session/render.ts`, `apps/cli/src/lib/redact.ts`, `.agents/skills/sessions/SKILL.md`.
+
 - **`agents sessions` rows show creation time as well as last activity (RUSH-2107).**
   The trailing time cell used to carry one unlabeled "X ago" — last activity — so a
   row could not say when the session began or how long it had been alive. It now
@@ -2855,10 +2917,8 @@
   `agentOnly` guard; and `isHeadlessSecretsContext` recognized the `headless` and
   `teams` runtimes but not `terminal`, which is what an interactive run sets. Agent
   launches now resolve broker-only and a locked bundle fails fast naming
-  `agents secrets unlock <bundle>`; `AGENTS_SECRETS_NO_PROMPT=1` is no longer needed
-  as a workaround. `agents secrets get/export/exec` typed in a **plain shell** still
-  prompts — it carries no `AGENTS_RUNTIME`, so the guard does not apply. Run beneath
-  an agent it refuses, because there the agent is the caller. This narrows the
+  `agents secrets unlock <bundle>`. Direct read commands use the same broker-only
+  path even from a plain shell; only an explicit unlock may authenticate. This narrows the
   agent-triggered approval added in RUSH-2032, which is unreleased.
 
 - **`release.sh` now borrows the npm token from a primary device when the local box

package/README.md

@@ -255,6 +255,9 @@ agents sessions --project my-app
 # Read a full conversation
 agents sessions a1b2c3d4 --markdown
 
+# Render a shareable, redacted Markdown transcript with the session preview on top
+agents sessions render a1b2c3d4 -o session.md
+
 # Just the last 3 turns, user messages only
 agents sessions a1b2c3d4 --last 3 --include user
 
@@ -323,6 +326,8 @@ Each live session resolves to `working`, `waiting_input` (with why -- a question
 
 Landing on a session cold? `agents sessions <id>` prints a catch-up digest: an inferred title, files changed grouped by directory (created / modified / deleted), a histogram of which tools did the work (including parsed Bash commands -- `git`, `npm`, `ffmpeg`, `ssh`, and so on), and the last test verdict -- the signals to reload a task in seconds.
 
+Sharing a session uses `agents sessions render <id> -o session.md`, not the raw harness JSONL. The document starts with that same preview, then presents user and assistant turns, fenced commands, structured tool arguments, and bounded tool output. Credential-shaped values and local home paths are redacted by default; `--no-redact` is for local-only inspection.
+
 ### Resume anywhere — and stay resumed
 
 Pick up any past conversation and drop it back into a terminal:

package/dist/commands/browser.js

@@ -5,7 +5,7 @@ import { updateMeta } from '../lib/state.js';
 import { resolveActor } from '../lib/actor.js';
 import { loginsForProfile, profilesLoggedInto, serviceForUrl, loginsWithAccountsForProfile, accountsForProfile, credKeysForService, AUTH_SIGNATURES, } from '../lib/browser/login-detection.js';
 import { parseSecretRef } from '../lib/browser/secret-ref.js';
-import { readAndResolveBundleEnv, isHeadlessSecretsContext, bundleExists, readBundle, describeBundle } from '../lib/secrets/bundles.js';
+import { readAndResolveBundleEnv, bundleExists, readBundle, describeBundle } from '../lib/secrets/bundles.js';
 import { findBrowserPath, getPortOccupant, isLauncherScript } from '../lib/browser/chrome.js';
 import { listProfileCacheDirs, removeProfileCache, listAllProfileSnapshots, } from '../lib/browser/runtime-state.js';
 import { DEFAULT_VIEWPORT } from '../lib/browser/devices.js';
@@ -1481,7 +1481,7 @@ function registerTaskCommands(browser) {
                 process.exit(1);
             }
             try {
-                const { env } = readAndResolveBundleEnv(parsed.bundle, { caller: 'browser type', keys: [parsed.key], keyMode: 'storage', agentOnly: isHeadlessSecretsContext() });
+                const { env } = readAndResolveBundleEnv(parsed.bundle, { caller: 'browser type', keys: [parsed.key], keyMode: 'storage', agentOnly: true });
                 if (!(parsed.key in env)) {
                     console.error(`Key "${parsed.key}" not in bundle "${parsed.bundle}".`);
                     process.exit(1);

package/dist/commands/exec.js

@@ -560,9 +560,10 @@ export function registerRunCommand(program) {
         .option('--no-follow', 'With --host, dispatch detached and return immediately (track via `agents hosts ps/logs`).')
         .option('--any', 'With --host <cap> (a capability tag), pick any matching host instead of erroring when several match.')
         .option('--copy-creds', 'With --host, copy the picked runtime credentials (and Claude OAuth token) to the host, then shred them after the run. Opt-in per run.')
-        .option('--lease [backend]', 'Invent a disposable cloud box for this run and tear it down after (via crabbox). Optional backend selects the cloud (hetzner/aws/do). Same as --where lease[:backend]. Unlike --host, no machine is registered.')
+        .option('--lease [backend]', "Run on a cloud box (via crabbox) and tear it down after — reuses a warm box from the repo's profile pool when one is ready (--fresh forces a new box). Optional backend selects the cloud (hetzner/aws/do). Same as --where lease[:backend]. Unlike --host, no machine is registered.")
         .option('--box <slug>', 'Reuse an existing warm crabbox box for this run instead of provisioning a disposable --lease box.')
         .option('--keep-box', 'With --lease, keep the box after the run instead of stopping it.')
+        .option('--fresh', "With --lease, always provision a brand-new box (skip the warm profile-pool reuse) and tear it down after the run.")
         .option('--reuse', 'With --lease, reuse the most-recently-used warm box if one exists (else provision fresh). The scriptable form of the interactive reuse picker.')
         .option('--bare', 'With --lease, skip copying your local ~/.agents setup (skills/hooks/commands/MCP) onto the box.')
         .option('--tailscale', 'Lease the box onto your tailnet (reachable only over Tailscale) rather than a public IP.')
@@ -621,6 +622,14 @@ export function registerRunCommand(program) {
       # Inject a keychain-backed secrets bundle
       agents run claude "deploy the worker" --secrets prod --mode edit
 
+      # Run on a cloud box — reuses a warm box from the repo's profile pool when
+      # one is ready (kept after the run), else leases a fresh box, torn down after
+      agents run claude "fix the failing tests" --lease
+
+      # Force a brand-new box (destroyed after), or target a warm box by slug
+      agents run claude "fix the failing tests" --lease --fresh
+      agents run claude "fix the failing tests" --box warm-one
+
       # Pass arbitrary native flags to the underlying CLI via -- separator
       agents run kimi -- --plan --some-kimi-option value
       agents run claude "fix the bug" -- --custom-flag
@@ -824,6 +833,14 @@ export function registerRunCommand(program) {
                 console.error(chalk.red('Pass either --lease to provision a disposable box, or --box <slug> to reuse a warm box — not both.'));
                 process.exit(1);
             }
+            if (options.fresh && options.box) {
+                console.error(chalk.red('--fresh forces a brand-new box; it cannot be combined with --box <slug> (which reuses one).'));
+                process.exit(1);
+            }
+            if (options.fresh && options.reuse) {
+                console.error(chalk.red('--fresh forces a brand-new box; it cannot be combined with --reuse.'));
+                process.exit(1);
+            }
             const backend = typeof options.lease === 'string' ? options.lease : undefined;
             // crabbox syncs this directory to the box via `git ls-files`; outside a
             // git repo that fails with "build sync file list: exit status 128" — but
@@ -848,12 +865,21 @@ export function registerRunCommand(program) {
             // ── F3 reuse (RUSH-1922) + F5 net-mode (RUSH-1924) ───────────────────
             // Resolve which box this run targets and how it is networked BEFORE any
             // provisioning. `--box` is an explicit reuse; otherwise, on an
-            // interactive tty, offer the warm boxes as a reuse picker (headless /
-            // --json never blocks — it provisions fresh unless --reuse/--box).
+            // interactive tty, offer the warm boxes as a reuse picker. Headless runs
+            // never block: leaseAndRun itself is reuse-first against the profile
+            // pool (a ready pool box is reused; none ready → warm a fresh one).
+            // `--fresh` opts out of every reuse path.
             const leaseSecretsBundle = process.env.AGENTS_LEASE_SECRETS_BUNDLE;
             const nowSecs = Math.floor(Date.now() / 1000);
             let reuseSlug = options.box;
-            if (options.lease && !reuseSlug) {
+            // The profile this run's pool/box carries: the repo's .crabbox.yaml
+            // `profile:` when declared (what crabbox warmup would label a fresh box
+            // with), else crabbox's default. Passing it to leaseAndRun makes the
+            // pool-reuse match interchangeable with a fresh warmup.
+            const repoRoot = gitToplevel(leaseCwd);
+            const { readCrabboxRepoProfile } = await import('../lib/crabbox/config.js');
+            const poolProfile = repoRoot ? readCrabboxRepoProfile(repoRoot) : undefined;
+            if (options.lease && !reuseSlug && !options.fresh) {
                 const { crabboxList } = await import('../lib/crabbox/cli.js');
                 const { reusableBoxes, formatBoxRow } = await import('./lease.js');
                 let warm = [];
@@ -861,9 +887,8 @@ export function registerRunCommand(program) {
                     warm = reusableBoxes(crabboxList({ secretsBundle: leaseSecretsBundle }), nowSecs);
                 }
                 catch {
-                    warm = []; // crabbox unavailable / no creds → just provision fresh
+                    warm = []; // crabbox unavailable / no creds → the pool check in leaseAndRun decides
                 }
-                const repoRoot = gitToplevel(leaseCwd);
                 const alwaysFresh = repoRoot ? isAlwaysFreshRepo(readAlwaysFreshRepos(), repoRoot) : false;
                 if (warm.length > 0 && !alwaysFresh) {
                     if (options.reuse) {
@@ -896,7 +921,8 @@ export function registerRunCommand(program) {
                             console.error(chalk.yellow('Selection cancelled — provisioning a fresh box.'));
                         }
                     }
-                    // Headless with no --reuse falls through here → provision fresh.
+                    // Headless with no --reuse falls through here → leaseAndRun's
+                    // profile-pool check decides (reuse a ready pool box, else warm fresh).
                 }
                 else if (options.reuse && warm.length > 0) {
                     // --reuse still honors a warm box even when the picker is suppressed.
@@ -1015,12 +1041,16 @@ export function registerRunCommand(program) {
                         : `${runtime} credentials`;
             const boxLifecycle = reuseSlug
                 ? `Reusing crabbox box ${reuseSlug}`
-                : `Leasing a ${backend ?? 'hetzner'} box${netMode === 'tailscale' ? ' on your tailnet' : ''}`;
+                : options.fresh
+                    ? `Leasing a fresh ${backend ?? 'hetzner'} box${netMode === 'tailscale' ? ' on your tailnet' : ''}`
+                    : `Leasing a ${backend ?? 'hetzner'} box${netMode === 'tailscale' ? ' on your tailnet' : ''} (a ready box from the '${poolProfile ?? 'default'}' pool is reused when one exists)`;
             const boxAfterRun = reuseSlug
                 ? 'the box is kept after the run'
                 : options.keepBox
                     ? 'the box is kept after the run'
-                    : 'the box is destroyed after the run';
+                    : options.fresh
+                        ? 'the box is destroyed after the run'
+                        : 'a fresh box is destroyed after the run; a reused pool box is kept';
             console.error(chalk.gray(`${boxLifecycle} · shipping ${whatShips}${credentialRuntimes.length > 0 && leaseEmail ? ` (${leaseEmail})` : ''}; ${boxAfterRun}.`));
             // Read the Claude OAuth token from the local Keychain (silent) so it can be
             // written to ~/.claude/.credentials.json on the box — otherwise Claude boots
@@ -1100,6 +1130,8 @@ export function registerRunCommand(program) {
                     secretsBundle: leaseSecretsBundle,
                     keep: options.keepBox,
                     reuseBox: reuseSlug,
+                    fresh: options.fresh,
+                    profile: poolProfile,
                     copySetup,
                     netMode,
                     onData: (chunk) => router.push(chunk),

package/dist/commands/feed.js

@@ -222,7 +222,7 @@ export function sessionHintsFromActive(sessions) {
 export function registerFeedCommand(program) {
     const feed = program
         .command('feed')
-        .description('Open blocks (needs you) + agent status posts (feed post)')
+        .description('Operator inbox + agent status posts (aliases: inbox = needs-you; timeline = --filter updates)')
         .option('--json', 'Output as JSON (each block stamped with its outcome + ask class)')
         .option('--filter <view>', 'What to show: needs (default) · updates · all', 'needs')
         .option('--flat', 'List one block per agent instead of grouping by outcome')
@@ -572,6 +572,43 @@ docs/06-observability.md.
             renderOutcomeGroup(g, self);
         await renderTrailingActivity();
     });
+    // Observe-umbrella aliases (Phase 3): intentional second names, not deprecations.
+    // Re-parse into `feed` so flags/help stay single-sourced. See lib/observe-aliases.ts.
+    registerFeedObserveAliases(program);
+}
+/**
+ * `inbox` / `timeline` → feed. Loaded with the feed module so lazy COMMAND_LOADERS
+ * for those names also get the real `feed` command registered for re-parse.
+ */
+function registerFeedObserveAliases(program) {
+    const reparse = async (alias) => {
+        const { expandObserveAlias } = await import('../lib/observe-aliases.js');
+        const rest = process.argv.slice(3);
+        const expanded = expandObserveAlias(alias, rest);
+        if (!expanded) {
+            console.error(chalk.red(`Unknown observe alias: ${alias}`));
+            process.exit(1);
+        }
+        if (process.stderr.isTTY)
+            process.stderr.write(chalk.gray(`${expanded.note}\n`));
+        await program.parseAsync(['node', 'agents', ...expanded.argv]);
+    };
+    program
+        .command('inbox')
+        .description('Needs-you inbox (alias of `agents feed`). Open blocks waiting on you.')
+        .allowUnknownOption()
+        .allowExcessArguments()
+        .action(async () => {
+        await reparse('inbox');
+    });
+    program
+        .command('timeline')
+        .description('Agent progress stream (alias of `agents feed --filter updates`). What agents posted recently.')
+        .allowUnknownOption()
+        .allowExcessArguments()
+        .action(async () => {
+        await reparse('timeline');
+    });
 }
 /**
  * Mirror a written post to the configured sinks (`feed.broadcast` in

package/dist/commands/harness.d.ts

@@ -11,7 +11,8 @@
  * native harness registry. The `agents profiles` tree stays unchanged.
  */
 import type { Command } from 'commander';
-import { type Profile } from '../lib/profiles.js';
+import { type AddProfileOptions } from './profiles.js';
+import { type Profile, type ForkProfileOptions } 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
@@ -25,9 +26,25 @@ export interface ForkOptions {
     authProvider?: string;
     version?: string;
     description?: string;
+    /** `<bundle>` or `<bundle>:<key>` — see {@link applyFromSecrets} in ./profiles.js. */
+    fromSecrets?: string;
     keyStdin?: boolean;
     force?: boolean;
 }
+/** Options accepted by `agents harness edit`. */
+export interface EditOptions {
+    model?: string;
+    baseUrl?: string;
+    authProvider?: string;
+    /** Empty string ('') unpins the host CLI version. */
+    version?: string;
+    description?: string;
+    /** Empty string ('') clears the fallback model. */
+    fallbackModel?: string;
+    /** `<bundle>` or `<bundle>:<key>` — see {@link applyFromSecrets} in ./profiles.js. */
+    fromSecrets?: string;
+    keyStdin?: boolean;
+}
 /**
  * Build the new harness for `agents harness fork <source> <name>`.
  *
@@ -37,4 +54,26 @@ export interface ForkOptions {
  * copy a model from.
  */
 export declare function buildFork(source: string, name: string, opts: ForkOptions): Profile;
+/** Map `agents harness edit` flags onto {@link ForkProfileOptions} — the same
+ * override shape `editProfile`/`forkProfile` apply. `--version ''` (unpin) is
+ * handled by the caller ({@link buildEdit}), not here: `forkProfile`'s own
+ * ternary treats an empty string as "no override" and would otherwise inherit
+ * the source's version instead of clearing it. */
+export declare function buildEditOverrides(opts: EditOptions): ForkProfileOptions;
+/** True when at least one recognized edit flag was given. */
+export declare function hasEditFlags(opts: EditOptions): boolean;
+/**
+ * Build the edited harness for `agents harness edit <name>` — the profile-shape
+ * transform only; the caller applies `--from-secrets`/`--auth-provider` (async
+ * keychain side effects) and persists with `writeProfile`. Mirrors
+ * {@link buildFork}'s split between a pure builder and the action's IO.
+ */
+export declare function buildEdit(name: string, opts: EditOptions): Profile;
+/** True when `agents harness fork` was given too little to proceed without the wizard. */
+export declare function forkNeedsWizard(source: string | undefined, name: string | undefined, opts: ForkOptions): boolean;
+/** True when `agents harness add` was given too little to proceed without the wizard.
+ * Mirrors {@link addProfile}'s own error condition in ./profiles.js so a bare
+ * `agents harness add <preset-name>` (no flags) still resolves via the preset
+ * fallback instead of being routed into the wizard. */
+export declare function addNeedsWizard(name: string | undefined, opts: AddProfileOptions): boolean;
 export declare function registerHarnessCommands(program: Command): void;