@byokit/herdr 0.5.0 → 0.7.1

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 ## Unreleased
 
+## 0.7.1 (2026-10-07)
+
+- Dependency update: pins @byokit/relay 0.5.3.
+- Dependency update: pins @byokit/link 0.7.1.
+
+- `move` and `moveToAccount` no longer type env prep into the new pane: the split placement env is verified silently through `pane.get` (set vars exact, unset vars absent, fail closed), so no `unset` lines, echo probes or account folder values stay in the scrollback after a move.
+- The replacement agent keeps the conversation's name: it starts unique while the source is still live, then takes the source's session name through `agent.rename` once the source pane closes (best-effort; a refused rename never fails the move). New panes no longer show `move-<hex>` names.
+- The quickstart now says what to read next (the kit spec's decisions and work packages, then the two ways in
+  and agent readiness). Docs only; no typed surface changed.
+- The `relay` option takes anything with `RelayClient`'s `notify`, so a host can hand the kit a relay it opens after `Host.open` (the client needs the open host). A `RelayClient` still fits; behaviour is unchanged.
+- Unreleased source dependency metadata: pin @byokit/seal 0.3.0 and @byokit/relay 0.5.2; this package's existing version is not republished. Previously published consumer metadata remains unchanged.
+- `startAgent` with a record `env` that sets `HOME` now also places the pane's XDG config, data, state and cache directories under that home (unless set), so a sign-in inside the pane stays in the task-owned home instead of the server's.
+
+## 0.7.0 (2026-10-02)
+
+- Includes the Muse installation, managed-kind discovery and isolated readiness FIX/SECURITY changes recorded in the unpublished 0.6.0 preparation below; none add native login qualification.
+
+FIX: Re-read source quiescence, conversation, terminal and published sequence immediately before closing on every account move; roll back replacements on change and verify surviving conversations after uncertain cleanup. Published Herdr has no atomic conditional close.
+FIX: Add explicit confirmed, bounded `whenBusy: { busy: 'wait', confirmed, waitMs }` account handoff: move when this step finishes, never interrupt. Preserve default busy refusal, refuse missing sequence/stale identity, stop on blocked approvals, and return typed `interrupt_unsupported` without keys or lifecycle calls. Native working-step qualification remains separate from offline protocol fixtures.
+
+## 0.6.0 (2026-10-02)
+
+- SECURITY: Explicit Muse installation uses private staged HOME/XDG/temp paths, a clean environment, bounded HTTPS downloads and owned-process cancellation; it never imports personal credentials, edits shell profiles, or starts automatic login or updates.
+- FIX: Missing Muse on the effective private launch PATH now reports not installed and refuses before pane placement or start instead of showing a fake installation and waiting for the startup timeout. The explicit official installer returns verified local release paths for launch; account/catalog readiness remains unknown.
+
+FIX: Discover every pinned agent kind and use its actual account-folder and resume support for sign-in tabs and managed moves. Kinds without a folder override remain one sign-in per computer user, tab only. New move support is fixture-tested, not native-qualified.
+
+SECURITY: Readiness no longer probes default CLI logins. Pass `agentStatus(kinds, { folders: { [kind]: appManagedFolder }, env? })` to select an app-owned account; absent or invalid folders return unknown without running a CLI. Status commands receive a clean env with HOME/XDG/platform directories confined to that folder. Direct `runStatusCommand` calls without an explicit HOME return no answer. Injected status runners now receive the resolved executable path and explicit env (not an inherited default login).
+
 ## 0.5.0 (2026-10-01)
 
 - SECURITY: StartAgent and openSignInTab accept a clean launch environment with explicit unsets, verified before launch in idle shells on new or existing panes; credential values stay out of terminal commands, argv and errors, preventing inherited API key (billed per use) variables from overriding subscription sign-in.

package/README.md

@@ -145,6 +145,10 @@ for (const q of await hd.blocked()) {
 The [herdr-kit example](../../examples/herdr-kit) is the full version: pairing with a QR code and typed code, a
 persistent grant store, and the phone page above.
 
+Read next: [docs/runtime-kits.md](../../docs/runtime-kits.md) §11 for the decisions and the work packages this
+kit does not have yet, and [Two ways in](#two-ways-in) plus
+[Agent readiness](#agent-readiness) for the parts a new app picks first.
+
 ## API at a glance
 
 | Export | What it does |
@@ -154,7 +158,7 @@ persistent grant store, and the phone page above.
 | `HERDR_VERSION`, `HERDR_PROTOCOL` | The pinned Herdr release (`0.9.1`) and the protocol the kit speaks (`22`) |
 | `words`, `agentWords`, `stateWords`, `WORDS` | Plain sentences for agent statuses and kit states |
 | `herdrLink` (`@byokit/herdr/link`) | The host side of the `hd.*` link ops, spread into `Host.open`; scopes each grant to its workspaces and can push sealed approval notices through a relay |
-| `serve` (`@byokit/herdr/link`) | Finds the address with `@byokit/reach` and serves the link (and an optional page) on one port |
+| `serve` (`@byokit/herdr/link`) | Finds the address with `@byokit/discover` and serves the link (and an optional page) on one port |
 | `herdrDevice` (`@byokit/herdr/device`) | The phone and browser side: typed calls over a `DeviceLink` (`tree`, `startAgent`, `prompt`, `read`, `blocked`, `answer`, `events`, `terminal`, notices); no Node import |
 | `openNotice` (`@byokit/herdr/device`) | Opens a sealed approval notice with the device's own seed |
 | `startFakeHerdr`, `writeBinShim`, `herdrContract` (`@byokit/herdr/testing`) | The kit's stand-in Herdr, a bin shim that runs it, and the contract suite the kit passes |
@@ -190,15 +194,39 @@ const moved = await kit.moveToAccount({ paneId: 'w1:p2' }, {
 if (moved.ok) console.log(moved.session); // new pane to follow
 ```
 
-A move accepts Claude for Claude folders and Codex for Codex folders. Pi ignores these folder variables and is refused. It verifies the new shell's effective
+A move accepts mapped managed kinds, including Claude (`CLAUDE_CONFIG_DIR`), Codex (`CODEX_HOME`) and Pi
+(`PI_CODING_AGENT_DIR`, `--session <id|absolute path>`). Hosts own cross-account history sharing.
+It verifies the new shell's effective
 account folder, resumes the conversation there, waits for a ready session, then closes the old pane. A failed
 start preserves the original. A failed source close rolls back the new pane only after fresh reads verify
 both conversations' identities. A lost close acknowledgment can mean the original already closed: the kit
 preserves the replacement when the source is absent, replaced or unreachable and returns `close_failed`.
 After uncertain source close or cleanup, `live` names a freshly verified surviving conversation; it is omitted
 when neither conversation can be verified. Check the remaining panes before retrying. Independent changes
-can still happen after verification; the server has no conditional close transaction. Failures return a plain `message`. Wait until a conversation is idle or done before
-moving it. `StartAgent.env` applies to newly created placements; existing shells cannot receive a new env.
+can still happen after verification; the server has no conditional close transaction. Immediately before close,
+the source must still be idle/done with the same conversation, terminal and published `state_change_seq` as
+before splitting. Otherwise the replacement is closed and `changed` returned; `live` is freshly verified.
+This guard applies to idle moves too. It is a bounded observation, not atomic or a new security guarantee.
+Failures return a plain `message`. By default, working or blocked conversations return `busy`.
+
+Both move APIs optionally accept:
+```ts
+import type { BusyHandoff } from '@byokit/herdr';
+const whenBusy: BusyHandoff = {
+  busy: 'wait',
+  confirmed: { session: 'published-conversation-id', terminalId: 'published-terminal-id' },
+  waitMs: 300_000,
+}; // Pass whenBusy to either move API after the person confirms these current values.
+```
+Label this **Move when this step finishes**. Confirmation must match the current published session and terminal;
+wait requires a published sequence and finite positive `waitMs` ≤ 300000. Working sources wait for idle/done/blocked
+and are re-read before staging. Timeout returns `busy`, approval returns `blocked`, stale identity returns `changed`,
+and missing sequence or invalid bounds returns `unsupported`. The person may stop the step themselves in the pane.
+`busy: 'interrupt'` (confirmed session/terminal/seq) returns `interrupt_unsupported`, never keys or lifecycle calls.
+Offline fixtures do not qualify real working-step handoff or native Pi moves. `StartAgent.env` applies to newly created placements; existing shells cannot receive a new env.
+A record env with `HOME` gives the pane a task-owned home: unless the env sets them, `XDG_CONFIG_HOME`,
+`XDG_DATA_HOME`, `XDG_STATE_HOME` and `XDG_CACHE_HOME` move under it too, so a sign-in inside the pane stays
+there. Other server variables still reach the pane; pass `{ env, unset }` for a fully replaced environment.
 Tokens stay on the device and are never logged. Each provider's own terms apply to how you use your plan.
 
 For managed-folder stores that supply resume arguments and credential shedding, use `move`:
@@ -242,15 +270,17 @@ Helpers cover the common paths (start an agent, deliver a prompt with a receipt,
 
 `kit.agentStatus(kinds)` reports, per kind, whether the agent's CLI is installed and whether
 it is signed in — the onboarding agents-and-pickers check. It needs no Herdr connection: it
-probes the local machine. Install detection reuses `installedAgentKinds` over the host PATH plus
+probes the explicit path or, for own-mode kits, the managed launch PATH. Adopt-mode inventory
+uses the local machine; it is not evidence of an existing pane's environment. That inventory uses the host PATH plus
 the extra install dirs a service PATH omits (`extraPathDirs`: `~/.local/bin`, the mise shims,
 `~/.npm-global/bin`, Homebrew and the system dirs — the set muxr probed before this kit did).
 Sign-in comes only from each CLI's own documented non-secret status command, with a 10 s timeout;
 a kind whose CLI has none, or whose command gives no answer, reads `unknown`. Credential files
 are never opened, read or statted — only the signed-in boolean is kept. Install detection tells a
 real runnable binary apart from an auto-install launcher: a mise-style shim on PATH, or nothing
-on PATH at all, reads `installState: 'installs-on-first-start'` with `installed: false` — Herdr
-fetches the agent on first start — instead of a missing-install error. That covers `pi`, which
+on PATH at all, retains the legacy `installState: 'installs-on-first-start'` with `installed: false`.
+**Muse is different:** no executable, an auto-install shim, or an official launcher without its selected native release,
+reads `installState: 'missing'`. Stock Herdr does not install an absent Muse command. That covers `pi`, which
 Herdr installs via mise: a missing or shimmed `pi` reads `installed: false` with `installs on
 first start`, while a real `pi` binary reads `installed: true`.
 
@@ -287,12 +317,71 @@ sniff's file-head reader (tests use fakes); `{ run }` injects the command runner
 `{ timeoutMs }` bounds each probe. `signInHint` rides kinds the kit knows how to check whenever they
 are not signed in; `installHint` always rides along.
 
+## Explicit private Muse installation
+
+`installMuse` is an additive Node helper. Calling it authorizes the official published installer,
+not sign-in or a model request. Show the source (`MUSE_INSTALL_URL`), destination and affected
+files before offering that action. No hidden download happens on import or `startAgent`.
+
+```ts
+import { HerdrKit, installMuse, museReadiness } from '@byokit/herdr';
+
+const installed = await installMuse({
+  home: '/app-owned/private/muse',
+  path: ['/usr/bin', '/bin'], // clean host-selected tools; no inherited environment
+  // installDir: '/app-owned/private/muse/tools', signal, timeoutMs: 180_000
+});
+if (installed.ok) {
+  const { env, version } = installed.receipt;
+  console.log(museReadiness(env), version); // installation only, signedIn stays unknown
+  const kit = new HerdrKit({ mode: 'adopt', bin: '/app-owned/tools/herdr',
+    socketPath: '/app-owned/herdr.sock' }); // the app's already running stock Herdr
+  await kit.start();
+  // Existing env-replacement/rollback guards still apply. Use this complete environment
+  // rather than shell rc files, including for an existing pane you explicitly prepare.
+  await kit.startAgent({ kind: 'muse', cwd: '/app-owned/project',
+    place: { tab: 'new', workspaceId: 'project' }, env: { env, unset: [] } });
+} else {
+  console.log(installed.code, installed.message); // e.g. protected_download, cancelled
+}
+```
+
+Only absolute app-managed private homes/targets are allowed. The destination must be inside
+that home; symlink/escape/default-home/system targets are refused. Bash/curl are required on
+the explicit tool PATH. The unmodified official HTTPS installer runs in a fresh staging
+HOME/XDG/temp, with `MUSE_INSTALL_DIR`, `MUSE_NO_MODIFY_PATH=1`, `MUSE_LOGIN=0`, no inherited
+URL/auth/profile overrides and a bounded curl policy. No credentials are copied or read from
+the caller's existing home. HTTPS-only redirects (at most three), per-download 60 s/512 MiB,
+a total deadline (default 180 s, maximum 300 s) and owned-process-group cancellation are enforced.
+No shell profile or persistent PATH is modified.
+
+Success requires both the executable launcher and selected executable `muse-bin-<version>`;
+the receipt records the native release version, SHA-256 hashes, actual paths and launch env.
+A working installation is reused without updates. A failed/cancelled new install leaves no
+partial target; an existing incomplete target is preserved/refused (choose a fresh directory).
+The returned environment disables automatic updates and login. Hosts own these private paths
+and must avoid concurrent writers; filesystem validation is not an OS sandbox for publisher code.
+Linux/macOS x64/arm64 are supported; Windows returns `unsupported_platform`.
+
+Known-missing Muse refuses with `agent_not_installed` / `launchFailed.reason: 'not-installed'`
+**before placement/start**. Preflight uses the explicit per-call environment, otherwise the
+kit-owned launch environment for a new pane. Controller-global inventory/probe overrides
+never prove readiness on a known private launch PATH. An unobserved existing/adopted pane
+environment remains unknown (`museReadiness()`), not installed. Exact typed RPC pass-through
+is unchanged; direct stock `agent.start` has upstream behavior.
+
+Installation adds no folder/resume/native-move capability: Muse remains tab-only metadata.
+It does not prove sign-in, account catalog or model readiness. The official public model name
+is `muse-spark-1.3-contributor`; the installed account's own catalog still requires separate
+owner qualification. No provider/model fallback is performed. Previously inspected published
+kit versions 0.3.0 and 0.5.0 lack this helper/fix; this source change is not a published-version claim.
+
 ## Agent start lifecycle
 
 `startAgent` keeps its typed shape and rejection, and additionally reports the launch as events
 so an app shows `Installing…` instead of a blank start: `installing` (with the progress words)
 before a start that needs an install, `ready` with the fresh ref, and `launchFailed` with a typed
-`reason` (`placement-failed` | `pane-busy` | `install-failed` | `start-rejected`) plus plain words.
+`reason` (`placement-failed` | `pane-busy` | `install-failed` | `start-rejected` | `not-installed`) plus plain words.
 Subscribe per call with `onEvent`, or app-wide with `kit.onStartAgent` — no polling either way.
 
 ```ts

package/dist/accounts.js

@@ -1,7 +1,9 @@
 // Account-specific CLI panes (D11/6.6). No credentials are read or copied. Moves follow
 // the decided start-then-close order; only fake transports exercise this in tests.
 import { randomBytes } from 'node:crypto';
+import { isAbsolute } from 'node:path';
 import { words } from "./words.js";
+import { accountKind } from "./kinds.js";
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 export function createAccountPanes(ctx) {
     const moving = new Set();
@@ -15,55 +17,58 @@ export function createAccountPanes(ctx) {
             return false;
         }
     }
-    // A shell rc can override placement env. Verify what the shell actually resolves, rather
-    // than pane.get's launch env. The variable name is fixed by the provider, never caller text.
-    async function checkEnv(paneId, variable, folder, timeout, absent = false) {
-        const marker = `BYOKIT_ACCOUNT_${randomBytes(8).toString('hex')}`;
-        const deadline = Date.now() + timeout;
-        const expansion = absent ? '${' + variable + '+x}' : '$' + variable;
-        try {
-            await call('pane.send_text', { pane_id: paneId, text: `echo ${marker}="${expansion}"\n` }, timeout);
-            for (;;) {
-                const result = await call('pane.read', { pane_id: paneId, source: 'recent_unwrapped', lines: 40,
-                    format: 'text', strip_ansi: true }, Math.max(1, deadline - Date.now()));
-                const readings = String(result?.read?.text ?? '').split('\n').map((line) => line.trim())
-                    .filter((line) => line.startsWith(`${marker}=`)).map((line) => line.slice(marker.length + 1));
-                if (readings.length > 0)
-                    return readings.includes(folder);
-                if (Date.now() >= deadline)
-                    return false;
-                await sleep(Math.min(100, Math.max(1, deadline - Date.now())));
-            }
-        }
-        catch {
-            return false;
-        }
-    }
-    // agent.start has no env/unset/command field in the pinned protocol. Clear credentials in
-    // the shell that launches it, then verify absence (never echo credential values).
-    async function prepareEnv(paneId, set, unset, variable, timeout) {
+    // Env verification types nothing into the pane: every prep keystroke (unset lines,
+    // echo probes) stays in the new pane's scrollback where users see it after a move. The
+    // placement env rides `pane.split`, applied by the server before the shell is shown,
+    // so `pane.get` proves the new shell's launch env: every set var exact, every unset
+    // var absent. Fail closed: the split call cannot express removals, so a leaked
+    // credential in the launch env refuses the move instead of running on it.
+    // Limitation: a shell rc overriding placement env after launch is not visible here;
+    // no pinned RPC reads shell-effective env without typing into the pane.
+    async function verifyPaneEnv(paneId, set, unset, timeout) {
         const entries = Object.entries(set);
         if ([...entries.map(([key]) => key), ...unset].some((key) => !/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
             || entries.some(([, value]) => typeof value !== 'string' || /[\r\n\0]/.test(value))
             || unset.some((key) => key in set))
             return false;
         try {
-            if (unset.length > 0)
-                await call('pane.send_text', { pane_id: paneId, text: `unset ${unset.join(' ')}\n` }, timeout);
-            if (!await checkEnv(paneId, variable, set[variable], timeout))
+            const pane = (await call('pane.get', { pane_id: paneId }, timeout))?.pane;
+            const env = pane?.env;
+            if (!pane || typeof env !== 'object' || env === null || Array.isArray(env))
                 return false;
-            for (const key of unset)
-                if (!await checkEnv(paneId, key, '', timeout, true))
-                    return false;
-            return true;
+            if (unset.some((key) => Object.hasOwn(env, key)))
+                return false;
+            return entries.every(([key, value]) => env[key] === value);
         }
         catch {
             return false;
         }
     }
+    // The replacement keeps the conversation's user-visible name. The server rejects
+    // duplicate agent names, so it starts unique while the source is still live, then
+    // takes the source's name once that pane is closed. A failed rename keeps the
+    // unique start name and never fails the move.
+    function moveNames(sourceName, kind) {
+        const clean = (value) => {
+            const slug = String(value ?? '').toLowerCase().replace(/[^a-z0-9_-]+/g, '-')
+                .replace(/^[-_0-9]+/, '').slice(0, 32);
+            return /^[a-z][a-z0-9_-]{0,31}$/.test(slug) ? slug : undefined;
+        };
+        const want = clean(sourceName) ?? clean(kind) ?? 'agent';
+        return { start: `${want.slice(0, 25)}-${randomBytes(3).toString('hex')}`, want };
+    }
     async function openSignInTab(o) {
-        const { workspaceId, label, ...start } = o;
+        const { workspaceId, label, folder, ...start } = o;
         try {
+            if (folder !== undefined) {
+                const variable = accountKind(start.kind)?.folderVar;
+                if (!variable || !folder || /[\r\n\0]/.test(folder))
+                    throw new Error('unsupported folder');
+                const launch = start.env;
+                start.env = launch && typeof launch.env === 'object' && Array.isArray(launch.unset)
+                    ? { env: { ...launch.env, [variable]: folder }, unset: launch.unset }
+                    : { ...launch, [variable]: folder };
+            }
             return await ctx.startAgent({ ...start, place: { tab: 'new', workspaceId,
                     ...(label === undefined ? {} : { label }) } });
         }
@@ -85,19 +90,69 @@ export function createAccountPanes(ctx) {
             catch {
                 return failed('too_early');
             }
-            const session = agent?.agent_session;
+            const handoff = o.whenBusy;
+            const optedIn = handoff?.busy === 'wait' || handoff?.busy === 'interrupt';
+            let session = agent?.agent_session;
             if (!agent || agent.launch_pending === true || !session || typeof session.value !== 'string'
                 || session.value.length === 0)
                 return failed('too_early');
-            if (!['idle', 'done'].includes(agent.agent_status))
+            if (agent.agent_status === 'blocked')
+                return failed(optedIn ? 'blocked' : 'busy');
+            if (!['idle', 'done'].includes(agent.agent_status) && !(optedIn && agent.agent_status === 'working'))
                 return failed('busy');
+            if (optedIn) {
+                if (!handoff.confirmed || handoff.confirmed.session !== session.value
+                    || handoff.confirmed.terminalId !== agent.terminal_id)
+                    return failed('changed');
+                if (typeof agent.terminal_id !== 'string' || agent.terminal_id.length === 0)
+                    return failed('unsupported');
+                if (handoff.busy === 'interrupt') {
+                    if (handoff.confirmed.seq !== agent.state_change_seq)
+                        return failed('changed');
+                    return failed('interrupt_unsupported');
+                }
+                if (!Number.isFinite(handoff.waitMs) || handoff.waitMs <= 0 || handoff.waitMs > 300_000
+                    || !Number.isSafeInteger(agent.state_change_seq) || agent.state_change_seq < 0)
+                    return failed('unsupported');
+                if (agent.agent_status === 'working') {
+                    try {
+                        await call('agent.wait', { target: target.paneId, until: ['idle', 'done', 'blocked'],
+                            timeout_ms: handoff.waitMs }, handoff.waitMs + 5000);
+                    }
+                    catch {
+                        return failed('busy');
+                    }
+                    let current;
+                    try {
+                        current = (await call('agent.get', { target: target.paneId }))?.agent;
+                    }
+                    catch {
+                        return failed('changed', null);
+                    }
+                    if (!current || current.launch_pending === true || current.agent !== agent.agent
+                        || current.terminal_id !== agent.terminal_id || current.agent_session?.agent !== session.agent
+                        || current.agent_session?.kind !== session.kind || current.agent_session?.value !== session.value)
+                        return failed('changed', null);
+                    if (current.agent_status === 'blocked')
+                        return failed('blocked');
+                    if (!['idle', 'done'].includes(current.agent_status))
+                        return failed('busy');
+                    if (!Number.isSafeInteger(current.state_change_seq) || current.state_change_seq < 0)
+                        return failed('unsupported');
+                    agent = current;
+                    session = current.agent_session;
+                }
+            }
             const kind = agent.agent;
-            if (!['claude', 'codex'].includes(o.provider) || kind !== o.provider
-                || (request !== undefined && request.kind !== kind)
-                || session.agent !== kind || session.kind !== 'id')
+            const metadata = accountKind(o.provider);
+            if (!metadata?.folderVar || !metadata.resume || kind !== metadata.kind
+                || (request !== undefined && accountKind(request.kind)?.kind !== kind)
+                || session.agent !== kind || !metadata.sessionKinds.includes(session.kind))
+                return failed('unsupported');
+            if (/[\x00-\x1f\x7f]/.test(session.value) || session.value.length > (session.kind === 'path' ? 4096 : 512)
+                || (session.kind === 'path' && !isAbsolute(session.value)))
                 return failed('unsupported');
-            const args = request?.args ?? (kind === 'claude' && session.kind === 'id' ? ['--resume', session.value]
-                : kind === 'codex' && session.kind === 'id' ? ['resume', session.value] : undefined);
+            const args = request?.args ?? metadata.resumeArgs?.map((arg) => arg.replace('{session}', () => session.value));
             if (args === undefined || !Array.isArray(args) || args.length === 0 || args.some((a) => typeof a !== 'string' || /[\r\n\0]/.test(a)))
                 return failed('unsupported');
             if (!o.folder || /[\r\n\0]/.test(o.folder))
@@ -105,7 +160,7 @@ export function createAccountPanes(ctx) {
             const timeout = o.timeoutMs ?? 60_000;
             if (!Number.isFinite(timeout) || timeout <= 0)
                 return failed('start_failed');
-            const variable = o.provider === 'claude' ? 'CLAUDE_CONFIG_DIR' : 'CODEX_HOME';
+            const variable = metadata.folderVar;
             let paneId;
             let replacement;
             try {
@@ -127,16 +182,17 @@ export function createAccountPanes(ctx) {
             catch {
                 return rollback('start_failed');
             }
-            if (request !== undefined && !await prepareEnv(paneId, request.set, request.unset ?? [], variable, timeout)) {
-                return rollback('env_mismatch');
+            if (request !== undefined) {
+                if (!await verifyPaneEnv(paneId, request.set, request.unset ?? [], timeout))
+                    return rollback('env_mismatch');
             }
-            if (request === undefined && !await checkEnv(paneId, variable, o.folder, timeout)) {
+            else if (!await verifyPaneEnv(paneId, { ...o.env, [variable]: o.folder }, [], timeout)) {
                 return rollback('env_mismatch');
             }
+            const names = moveNames(agent?.name, kind);
             try {
-                // Unique names avoid colliding with the still-live source agent.
                 await ctx.startAgent({ kind, cwd: agent.foreground_cwd ?? agent.cwd ?? '.',
-                    name: `move-${randomBytes(8).toString('hex')}`, place: { pane: paneId }, args, timeoutMs: timeout });
+                    name: names.start, place: { pane: paneId }, args, timeoutMs: timeout });
                 await call('agent.wait', { target: paneId, until: ['idle', 'done'], timeout_ms: timeout }, timeout + 5000);
                 const deadline = Date.now() + timeout;
                 for (;;) {
@@ -158,25 +214,43 @@ export function createAccountPanes(ctx) {
                 const cleaned = await close(paneId);
                 return failed('start_failed', cleaned ? target.paneId : paneId);
             }
+            // Compare identity, not revision: status changes can legitimately bump revision.
+            const survives = async (id, expected) => {
+                try {
+                    const current = (await call('agent.get', { target: id }, timeout))?.agent;
+                    return !!current && current.agent === expected.agent && current.launch_pending !== true
+                        && ['idle', 'working', 'blocked', 'done'].includes(current.agent_status)
+                        && current.agent_session?.agent === expected.agent_session?.agent
+                        && current.agent_session?.kind === expected.agent_session?.kind
+                        && current.agent_session?.value === expected.agent_session?.value
+                        && (expected.terminal_id === undefined || current.terminal_id === expected.terminal_id)
+                        && (expected.name === undefined || current.name === expected.name);
+                }
+                catch {
+                    return false;
+                } // unavailable is not proof of survival
+            };
+            let current;
+            try {
+                current = (await call('agent.get', { target: target.paneId }, timeout))?.agent;
+            }
+            catch {
+                current = {};
+            }
+            if (!current || current.launch_pending === true || !['idle', 'done'].includes(current.agent_status)
+                || current.agent_status !== agent.agent_status || current.agent !== agent.agent || current.terminal_id !== agent.terminal_id
+                || current.agent_session?.agent !== session.agent || current.agent_session?.kind !== session.kind
+                || current.agent_session?.value !== session.value
+                || (agent.state_change_seq !== undefined && current.state_change_seq !== agent.state_change_seq)) {
+                await close(paneId);
+                const live = await survives(paneId, replacement) ? paneId
+                    : await survives(target.paneId, agent) ? target.paneId : null;
+                return failed('changed', live);
+            }
+            // Published Herdr has no conditional close: the final observation is not atomic.
             if (!await close(target.paneId)) {
                 // A lost ACK can mean the close already applied. Never destroy the ready
                 // replacement unless a fresh read proves the original conversation survived.
-                // Compare identity, not revision: status changes can legitimately bump revision.
-                const survives = async (id, expected) => {
-                    try {
-                        const current = (await call('agent.get', { target: id }, timeout))?.agent;
-                        return !!current && current.agent === expected.agent && current.launch_pending !== true
-                            && ['idle', 'working', 'blocked', 'done'].includes(current.agent_status)
-                            && current.agent_session?.agent === expected.agent_session?.agent
-                            && current.agent_session?.kind === expected.agent_session?.kind
-                            && current.agent_session?.value === expected.agent_session?.value
-                            && (expected.terminal_id === undefined || current.terminal_id === expected.terminal_id)
-                            && (expected.name === undefined || current.name === expected.name);
-                    }
-                    catch {
-                        return false;
-                    } // unavailable is not proof of survival
-                };
                 const replacementAlive = await survives(paneId, replacement);
                 const sourceAlive = await survives(target.paneId, agent);
                 if (sourceAlive && replacementAlive)
@@ -188,6 +262,15 @@ export function createAccountPanes(ctx) {
                 return failed('close_failed', live);
             }
             // The source is closed: a notification failure cannot undo a successful move.
+            // Take the conversation's name now that it is free; the unique start name stays
+            // when the rename is refused, and a rename failure never undoes the move.
+            if (names.want !== names.start) {
+                try {
+                    await call('agent.rename', { target: paneId, name: names.want }, timeout);
+                    replacement.name = names.want;
+                }
+                catch { /* the unique start name stays; the move already succeeded */ }
+            }
             try {
                 request?.onReplaced?.(paneId);
             }
@@ -199,10 +282,10 @@ export function createAccountPanes(ctx) {
         }
     }
     async function move(o) {
-        const variable = o.kind === 'claude' ? 'CLAUDE_CONFIG_DIR' : 'CODEX_HOME';
+        const variable = accountKind(o.kind)?.folderVar;
         const result = await perform({ paneId: o.paneId }, {
-            provider: o.kind === 'claude' ? 'claude' : 'codex', folder: o.set[variable] ?? '',
-            env: o.set, timeoutMs: o.timeoutMs,
+            provider: o.kind, folder: variable === undefined ? '' : o.set[variable] ?? '',
+            env: o.set, timeoutMs: o.timeoutMs, whenBusy: o.whenBusy,
         }, o);
         return result.ok ? { ok: true, paneId: result.session } : result;
     }

package/dist/agents.d.ts

@@ -6,6 +6,7 @@ export declare function createAgents(ctx: {
     snapshot(): HerdrSnapshot;
     reread(paneId: string): Promise<void>;
     emitStart?(e: AgentStartEvent): void;
+    launchEnv?(): Record<string, string> | undefined;
 }): Pick<HerdrKit, 'startAgent' | 'prompt' | 'sendKeys' | 'wait' | 'read' | 'agentKinds' | 'installedAgentKinds' | 'agentStatus'>;
 export declare function resolveAgentBinary(kind: string, o: {
     path: string[];
@@ -29,6 +30,7 @@ export declare function agentProbePath(path?: string[], home?: string): string[]
 export declare function runStatusCommand(command: string, args: string[], o?: {
     stdin?: string;
     timeoutMs?: number;
+    env?: Record<string, string>;
 }): Promise<{
     stdout: string;
 } | undefined>;