@byokit/herdr 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 ## Unreleased
 
+## 0.4.0 (2026-10-01)
+
+- Dependency update: pins @byokit/reach 0.6.0.
+
+- Add `move` with caller resume args, credential shedding, staging/replacement hooks and `MoveResult.paneId`.
+- Add per-call `cli` env overlays for managed folder hook installation.
+- Report surviving replacement panes when environment verification rollback fails; refuse folder moves for agents that ignore the folder variables.
+
+## 0.3.0 (2026-10-01)
+
+- Dependency update: pins @byokit/reach 0.5.0.
+- Dependency update: pins @byokit/relay 0.5.0.
+- Dependency update: pins @byokit/link 0.7.0.
+
+- `PromptReceipt.agentSession` optionally identifies the conversation from the prompt response without an extra read.
+
+- FIX: Refuse non-empty `StartAgent.env` on existing panes instead of silently using the old subscription.
+- Move a conversation to another subscription account with `moveToAccount`: verify the target shell folder,
+  resume and wait before closing the original pane, and roll back the new pane on failure.
+- Open each CLI’s own sign-in in an account-specific tab with `openSignInTab` and the host’s explicit env.
+
+- `HerdrKit.startAgent` lifecycle events: `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 —
+  subscribable per call (`StartAgent.onEvent`) or app-wide (`kit.onStartAgent`), no polling.
+  The shape and rejection are unchanged. Install detection (`agentInstallState`, also on
+  `agentStatus` as `installState`) tells a real runnable binary apart from an auto-install
+  launcher such as a mise shim: shimmed or absent reads `installs-on-first-start`, sharing the
+  one probe path with `installedAgentKinds` (`resolveAgentBinary`, `isAutoInstallShim`).
+
+
 ## 0.2.0 (2026-09-30)
 
 - `HerdrKit.agentStatus(kinds)` (B5): per-kind onboarding readiness — installed plus CLI

package/README.md

@@ -149,8 +149,8 @@ persistent grant store, and the phone page above.
 
 | Export | What it does |
 |---|---|
-| `HerdrKit` (`@byokit/herdr`) | The host-side kit, in `adopt` or `own` mode: `start`/`stop`, `state`, `snapshot`/`onChange`, `startAgent`, `prompt`, `sendKeys`, `wait`, `read`, `blocked`/`onBlocked`/`answer`, `closePane`/`closeTab`/`closeWorkspace`, `agentKinds`, `installedAgentKinds`, `agentStatus`, `terminal`, `onEvent`, `statusWatchReady`, and the pass-throughs `call`, `subscribe` and `cli` |
-| `agentStatus`, `agentProbePath`, `extraPathDirs`, `runStatusCommand` (`@byokit/herdr`) | Onboarding readiness: per-kind install + CLI sign-in without a Herdr connection (see below) |
+| `HerdrKit` (`@byokit/herdr`) | The host-side kit, in `adopt` or `own` mode: `start`/`stop`, `state`, `snapshot`/`onChange`, `startAgent`, `openSignInTab`, `move`, `moveToAccount`, `onStartAgent`, `prompt`, `sendKeys`, `wait`, `read`, `blocked`/`onBlocked`/`answer`, `closePane`/`closeTab`/`closeWorkspace`, `agentKinds`, `installedAgentKinds`, `agentStatus`, `agentInstallState`, `terminal`, `onEvent`, `statusWatchReady`, and the pass-throughs `call`, `subscribe` and `cli` |
+| `agentStatus`, `agentInstallState`, `agentProbePath`, `extraPathDirs`, `runStatusCommand`, `isAutoInstallShim`, `resolveAgentBinary` (`@byokit/herdr`) | Onboarding readiness: per-kind install + CLI sign-in without a Herdr connection (see below) |
 | `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 |
@@ -160,9 +160,72 @@ persistent grant store, and the phone page above.
 | `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 |
 | `ensureHerdr`, `fetchHerdr`, `HERDR_ASSETS` (`@byokit/herdr/binary`) | Opt-in pinned fetch: the v0.9.1 asset for the current platform into an app-owned dir, sha256-verified, executable, returned as the absolute `own`-mode `bin`; refused (nothing left) on a hash mismatch or unsupported platform |
 
+`PromptReceipt` contains `paneId`, `terminalId`, `revision`, and `status`. Its optional
+`agentSession` (`{ source, agent, kind, value }`) identifies the conversation that received
+this prompt, taken directly from the `agent.prompt` response without another read.
+`kind` distinguishes a session id from a session path; `value` is that id or path.
+Herdr exposes no separate generation counter. When Herdr omits the session (or returns
+null), `agentSession` is absent; callers can fall back to their existing checks.
+
 Types (`HerdrKitOptions`, `HerdrState`, `StartAgent`, `PromptReceipt`, `BlockedAgent`, `HerdrSnapshot`,
 `HerdrMethod`/`HerdrParams`/`HerdrResult`, `HerdrEventName`/`HerdrEventOf`, ...) come from the main entry.
 
+## Account-specific sign-ins and moves
+
+The host supplies account folders and shares conversation history as needed. The kit never reads or copies
+credentials. To connect an account, open its CLI in a new tab and let the person complete the CLI's own login:
+
+```ts
+import { HerdrKit } from '@byokit/herdr';
+const kit = new HerdrKit({ mode: 'adopt', bin: '/app/bin/herdr', socketPath: '/app/herdr.sock' });
+await kit.start();
+
+const signIn = await kit.openSignInTab({
+  workspaceId: 'w1', kind: 'codex', cwd: '/home/me/project', env: { CODEX_HOME: '/app/accounts/work' },
+});
+// Attach terminal(signIn.paneId, …) for the CLI's own sign-in screen.
+const moved = await kit.moveToAccount({ paneId: 'w1:p2' }, {
+  provider: 'codex', folder: '/app/accounts/work',
+});
+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
+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. Failures return a plain `message`
+and a `live` pane id for recovery, including when cleanup fails. 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.
+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`:
+
+```ts
+import { HerdrKit } from '@byokit/herdr';
+const kit = new HerdrKit({ mode: 'adopt', bin: '/app/bin/herdr', socketPath: '/app/herdr.sock' });
+await kit.start();
+
+const conversationId = 'published-conversation-id';
+const staged = new Set<string>();
+let activePane = 'w1:p2';
+const moved = await kit.move({
+  paneId: 'w1:p2', kind: 'codex', args: ['resume', conversationId],
+  set: { CODEX_HOME: '/app/accounts/work' }, unset: ['OPENAI_API_KEY', 'CODEX_API_KEY'],
+  onStaged(paneId) { staged.add(paneId); },
+  onReplaced(paneId) { staged.delete(paneId); activePane = paneId; },
+});
+if (moved.ok) console.log(moved.paneId);
+await kit.cli(['integration', 'install', 'codex'], { env: { CODEX_HOME: '/app/accounts/work' } });
+```
+
+`MoveResult` names the new pane as `paneId`; `moveToAccount` retains its `session` result as
+`MoveToAccountResult`. Both share the same per-source lock. Staging runs before verification/start; a staging
+exception rolls back. Replacement notification runs after closing the source and cannot undo the move.
+`move` clears `unset` in the new shell, verifies the account folder and unset names' absence, and requires an interactive
+agent publishing a conversation before closing the source. The pinned start API has no command-prefix/env
+field, so this uses shell `unset` rather than `env -u`; shells that cannot clear a variable fail closed.
+Only folder paths belong in `set`, never tokens. `cli` env overlays the kit's explicit env for one call;
+it inherits no process variables. The default move step timeout is 60 seconds.
+
 ## Two ways in
 
 - `adopt` talks to the socket path the app passes: the person's own Herdr, nothing spawned, nothing written.
@@ -179,9 +242,12 @@ the extra install dirs a service PATH omits (`extraPathDirs`: `~/.local/bin`, th
 `~/.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. Herdr auto-installs Pi
-via mise on first start, so `pi` always reads `installed: false` with `installs on first start`
-rather than a missing-install error.
+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
+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`.
 
 ```ts
 import { HerdrKit } from '@byokit/herdr';
@@ -193,10 +259,11 @@ console.log(await kit.agentStatus(['pi', 'claude', 'codex']));
 
 ```text
 [
-  { kind: 'pi', installed: false, signedIn: 'unknown', installHint: 'installs on first start' },
-  { kind: 'claude', installed: true, signedIn: 'yes',
+  { kind: 'pi', installed: false, installState: 'installs-on-first-start', signedIn: 'unknown',
+    installHint: 'installs on first start' },
+  { kind: 'claude', installed: true, installState: 'installed', signedIn: 'yes',
     installHint: 'Install the claude command, then check again.' },
-  { kind: 'codex', installed: true, signedIn: 'no',
+  { kind: 'codex', installed: true, installState: 'installed', signedIn: 'no',
     installHint: 'Install the codex command, then check again.',
     signInHint: 'On this computer run `codex`, sign in, then come back.' },
 ]
@@ -206,13 +273,35 @@ console.log(await kit.agentStatus(['pi', 'claude', 'codex']));
 |---|---|---|
 | `claude` | `claude auth status` (JSON `loggedIn`) | The CLI's own documented status; a signed-out CLI still prints its JSON, so only an empty answer reads `unknown`. |
 | `codex` | `codex app-server` with a pipelined `initialize` + `account/read` round | Codex exposes sign-in only over its app-server protocol; a record `account` in the second answer means signed in. |
-| `pi` | none (Herdr installs it via mise) | No probe: always `installed: false`, `installs on first start`. |
+| `pi` | none (Herdr installs it via mise) | Missing or shimmed: `installed: false`, `installs on first start`. A real binary reads `installed: true`. |
 | any other kind | none | No documented non-secret status command, so `unknown` until the kit covers it. |
 
-Options: `{ path, aliases }` as in `installedAgentKinds`; `{ run }` injects the command runner
+Options: `{ path, aliases }` as in `installedAgentKinds`; `{ readFile }` overrides the shim
+sniff's file-head reader (tests use fakes); `{ run }` injects the command runner
 (`(command, args, { stdin, timeoutMs }) => Promise<{ stdout } | undefined>`, so tests use fakes);
 `{ timeoutMs }` bounds each probe. `signInHint` rides kinds the kit knows how to check whenever they
 are not signed in; `installHint` always rides along.
+
+## 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.
+Subscribe per call with `onEvent`, or app-wide with `kit.onStartAgent` — no polling either way.
+
+```ts
+import { HerdrKit } from '@byokit/herdr';
+
+const kit = new HerdrKit({ mode: 'adopt', bin: 'herdr', socketPath: '/tmp/herdr.sock' });
+const off = kit.onStartAgent((e) => {
+  if (e.phase === 'installing') console.log(e.message);       // Installing pi…
+  if (e.phase === 'launchFailed') console.log(e.reason, e.message);
+});
+await kit.startAgent({ kind: 'pi', cwd: '/home/me/project', place: { workspace: 'new' },
+  onEvent: (e) => { if (e.phase === 'ready') console.log(e.ref.paneId); } });
+off();
+```
 `call` and `subscribe` are typed pass-throughs to the complete socket API, and `cli()` reaches the full CLI.
 
 `start()` is non-fatal: if Herdr is down it rejects (state `failed`, e.g. `failed/socket`) and may be called again

package/dist/accounts.d.ts

@@ -0,0 +1,10 @@
+import type { Call } from './agents.ts';
+import type { AgentRef, Move, MoveResult, MoveToAccount, MoveToAccountResult, OpenSignInTab, StartAgent } from './types.ts';
+export declare function createAccountPanes(ctx: {
+    call: Call;
+    startAgent(o: StartAgent): Promise<AgentRef>;
+}): {
+    openSignInTab: (o: OpenSignInTab) => Promise<AgentRef>;
+    move: (o: Move) => Promise<MoveResult>;
+    moveToAccount: (target: AgentRef, o: MoveToAccount) => Promise<MoveToAccountResult>;
+};

package/dist/accounts.js

@@ -0,0 +1,182 @@
+// 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 { words } from "./words.js";
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export function createAccountPanes(ctx) {
+    const moving = new Set();
+    const call = ctx.call;
+    async function close(paneId) {
+        try {
+            await call('pane.close', { pane_id: paneId });
+            return true;
+        }
+        catch {
+            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) {
+        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))
+                return false;
+            for (const key of unset)
+                if (!await checkEnv(paneId, key, '', timeout, true))
+                    return false;
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async function openSignInTab(o) {
+        const { workspaceId, label, ...start } = o;
+        try {
+            return await ctx.startAgent({ ...start, place: { tab: 'new', workspaceId,
+                    ...(label === undefined ? {} : { label }) } });
+        }
+        catch {
+            // A runtime error can contain account env. Never relay it to the sign-in screen.
+            throw Object.assign(new Error(words('agent.notReady')), { code: 'sign_in_failed' });
+        }
+    }
+    async function perform(target, o, request) {
+        const failed = (code, live = target.paneId) => ({ ok: false, code, message: words(`move.${code}`), live });
+        if (moving.has(target.paneId))
+            return failed('busy');
+        moving.add(target.paneId);
+        try {
+            let agent;
+            try {
+                agent = (await call('agent.get', { target: target.paneId }))?.agent;
+            }
+            catch {
+                return failed('too_early');
+            }
+            const 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))
+                return failed('busy');
+            const kind = agent.agent;
+            if (!['claude', 'codex'].includes(o.provider) || kind !== o.provider
+                || (request !== undefined && request.kind !== kind)
+                || session.agent !== kind || session.kind !== 'id')
+                return failed('unsupported');
+            const args = request?.args ?? (kind === 'claude' && session.kind === 'id' ? ['--resume', session.value]
+                : kind === 'codex' && session.kind === 'id' ? ['resume', session.value] : undefined);
+            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))
+                return failed('env_mismatch');
+            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';
+            let paneId;
+            try {
+                const split = await call('pane.split', { target_pane_id: target.paneId,
+                    direction: o.direction ?? 'right', focus: false,
+                    ...(typeof (agent.foreground_cwd ?? agent.cwd) === 'string' ? { cwd: agent.foreground_cwd ?? agent.cwd } : {}),
+                    env: { ...o.env, [variable]: o.folder } }, timeout);
+                if (typeof split?.pane?.pane_id !== 'string')
+                    return failed('start_failed');
+                paneId = split.pane.pane_id;
+            }
+            catch {
+                return failed('start_failed');
+            }
+            const rollback = async (code) => failed(code, await close(paneId) ? target.paneId : paneId);
+            try {
+                request?.onStaged?.(paneId);
+            }
+            catch {
+                return rollback('start_failed');
+            }
+            if (request !== undefined && !await prepareEnv(paneId, request.set, request.unset ?? [], variable, timeout)) {
+                return rollback('env_mismatch');
+            }
+            if (request === undefined && !await checkEnv(paneId, variable, o.folder, timeout)) {
+                return rollback('env_mismatch');
+            }
+            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 });
+                await call('agent.wait', { target: paneId, until: ['idle', 'done'], timeout_ms: timeout }, timeout + 5000);
+                const deadline = Date.now() + timeout;
+                for (;;) {
+                    const ready = (await call('agent.get', { target: paneId }, Math.max(1, deadline - Date.now())))?.agent;
+                    if (ready && ready.launch_pending !== true && ['idle', 'done'].includes(ready.agent_status)
+                        && (request === undefined || ready.interactive_ready === true)
+                        && ready.agent === kind && ready.agent_session?.agent === kind
+                        && ready.agent_session?.kind === session.kind && typeof ready.agent_session?.value === 'string'
+                        && ready.agent_session.value.length > 0)
+                        break;
+                    if (Date.now() >= deadline)
+                        throw new Error('not ready');
+                    await sleep(Math.min(100, Math.max(1, deadline - Date.now())));
+                }
+            }
+            catch {
+                const cleaned = await close(paneId);
+                return failed('start_failed', cleaned ? target.paneId : paneId);
+            }
+            if (!await close(target.paneId)) {
+                const cleaned = await close(paneId);
+                return failed('close_failed', cleaned ? target.paneId : paneId);
+            }
+            // The source is closed: a notification failure cannot undo a successful move.
+            try {
+                request?.onReplaced?.(paneId);
+            }
+            catch { /* notification only */ }
+            return { ok: true, session: paneId };
+        }
+        finally {
+            moving.delete(target.paneId);
+        }
+    }
+    async function move(o) {
+        const variable = o.kind === 'claude' ? 'CLAUDE_CONFIG_DIR' : 'CODEX_HOME';
+        const result = await perform({ paneId: o.paneId }, {
+            provider: o.kind === 'claude' ? 'claude' : 'codex', folder: o.set[variable] ?? '',
+            env: o.set, timeoutMs: o.timeoutMs,
+        }, o);
+        return result.ok ? { ok: true, paneId: result.session } : result;
+    }
+    return { openSignInTab, move, moveToAccount: (target, o) => perform(target, o) };
+}

package/dist/agents.d.ts

@@ -1,11 +1,29 @@
 import type { HerdrKit } from './kit.ts';
-import type { HerdrSnapshot } from './types.ts';
+import type { AgentInstallProbe, AgentInstallState, AgentLaunchFailureReason, AgentStartEvent, HerdrSnapshot } from './types.ts';
 export type Call = (method: string, params: Record<string, unknown>, timeoutMs?: number) => Promise<unknown>;
 export declare function createAgents(ctx: {
     call: Call;
     snapshot(): HerdrSnapshot;
     reread(paneId: string): Promise<void>;
+    emitStart?(e: AgentStartEvent): void;
 }): Pick<HerdrKit, 'startAgent' | 'prompt' | 'sendKeys' | 'wait' | 'read' | 'agentKinds' | 'installedAgentKinds' | 'agentStatus'>;
+export declare function resolveAgentBinary(kind: string, o: {
+    path: string[];
+    aliases?: Record<string, string[]>;
+}): {
+    binary: string;
+    path?: string;
+};
+export declare function isAutoInstallShim(file: string, readFile?: (file: string) => string | undefined): boolean;
+export declare function agentInstallState(kind: string, o?: AgentInstallProbe): {
+    kind: string;
+    state: AgentInstallState;
+    path?: string;
+};
+export declare function classifyStartFailure(error: unknown, o?: {
+    installExpected?: boolean;
+    stage?: 'placement' | 'start';
+}): AgentLaunchFailureReason;
 export declare function extraPathDirs(home?: string): string[];
 export declare function agentProbePath(path?: string[], home?: string): string[];
 export declare function runStatusCommand(command: string, args: string[], o?: {

package/dist/agents.js

@@ -3,9 +3,10 @@
 // disagree the schema wins. `pane.split` takes `target_pane_id` (muxr agrees), and `agent.start`
 // has no `env` param — a start's env belongs to the placement create/split call (src/generated/methods.ts).
 import { spawn } from 'node:child_process';
-import { accessSync, constants as fsConstants } from 'node:fs';
+import { accessSync, constants as fsConstants, openSync, readSync, closeSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { delimiter, join } from 'node:path';
+import { words } from "./words.js";
 const PROMPTABLE = ['idle', 'working', 'blocked', 'done'];
 const DEFAULT_TIMEOUT_MS = 60_000;
 // `agent.start` lands while the fresh pane is still at its shell prompt: the server answers
@@ -43,10 +44,50 @@ function rootPaneOf(result) {
 }
 export function createAgents(ctx) {
     const call = ctx.call;
+    const emitStart = (e) => {
+        try {
+            ctx.emitStart?.(e);
+        }
+        catch { /* a listener never breaks a start */ }
+    };
     // Every placement takes its pane id from the server's answer, never a prediction (6.4).
     // Placements that make a pane (every path but `pane`) roll it back with `pane.close` when the
     // start fails, so a failed start leaves no extra pane behind.
     async function startAgent(o) {
+        const emit = (e) => {
+            try {
+                o.onEvent?.(e);
+            }
+            catch { /* a listener never breaks a start */ }
+            emitStart(e);
+        };
+        // Install pre-check: a shim or nothing on PATH means Herdr installs on first start, so the
+        // app hears `installing` before the long start instead of watching a blank pane.
+        let installExpected = false;
+        try {
+            installExpected = agentInstallState(o.kind, o.installProbe).state === 'installs-on-first-start';
+        }
+        catch {
+            installExpected = false;
+        }
+        if (installExpected)
+            emit({ phase: 'installing', kind: o.kind, message: words('agent.installing', { agent: o.kind }) });
+        let stage = 'placement';
+        try {
+            const ref = await startAgentInner(o, () => { stage = 'start'; });
+            emit({ phase: 'ready', kind: o.kind, ref });
+            return ref;
+        }
+        catch (error) {
+            const reason = classifyStartFailure(error, { installExpected, stage });
+            emit({ phase: 'launchFailed', kind: o.kind, reason, message: launchFailureWords(reason, o.kind) });
+            throw error;
+        }
+    }
+    async function startAgentInner(o, onStartPhase) {
+        if ('pane' in o.place && Object.keys(o.env ?? {}).length > 0) {
+            throw fail('env_mismatch', 'This pane needs to be opened again to use that sign-in.');
+        }
         const timeout = o.timeoutMs ?? DEFAULT_TIMEOUT_MS;
         const env = o.env === undefined ? {} : { env: o.env };
         let paneId;
@@ -86,6 +127,7 @@ export function createAgents(ctx) {
         }
         if (paneId === undefined)
             throw new Error('herdr: the placement answered no pane id');
+        onStartPhase?.();
         const name = agentName(o);
         const params = { pane_id: paneId, kind: o.kind, name,
             ...(o.args === undefined ? {} : { args: o.args }), timeout_ms: timeout };
@@ -152,7 +194,12 @@ export function createAgents(ctx) {
             || a.pane_id !== target.paneId) {
             throw new Error('Herdr did not queue the prompt.');
         }
-        return { paneId: a.pane_id, terminalId: a.terminal_id, revision: a.revision, status: a.agent_status };
+        const session = a.agent_session;
+        const agentSession = isObj(session) && typeof session.source === 'string'
+            && typeof session.agent === 'string' && typeof session.kind === 'string' && typeof session.value === 'string'
+            ? { source: session.source, agent: session.agent, kind: session.kind, value: session.value } : undefined;
+        return { paneId: a.pane_id, terminalId: a.terminal_id, revision: a.revision, status: a.agent_status,
+            ...(agentSession === undefined ? {} : { agentSession }) };
     }
     async function wait(target, o) {
         const made = await call('agent.wait', { target: target.paneId,
@@ -176,58 +223,123 @@ export function createAgents(ctx) {
         return manifests.map((m) => (typeof m?.agent === 'string' ? m.agent : '')).filter((kind) => kind !== '');
     }
     function installedAgentKinds(kinds, o) {
-        const installed = [];
-        for (const kind of kinds) {
-            const names = [kind, ...(o.aliases?.[kind] ?? [])];
-            if (names.some((name) => o.path.some((dir) => {
-                try {
-                    accessSync(join(dir, name), fsConstants.X_OK);
-                    return true;
-                }
-                catch {
-                    return false;
-                }
-            })))
-                installed.push(kind);
-        }
-        return installed;
-    }
-    // B5: the extra install dirs muxr's `executableOnPath` probes past PATH (a GUI daemon's
-    // inherited PATH omits them), moved into the kit so the host probe is trusted.
-    function installedSet(kinds, o) {
-        return new Set(installedAgentKinds(kinds.filter((k) => k !== 'pi'), o));
+        return kinds.filter((kind) => resolveAgentBinary(kind, o).path !== undefined);
     }
     async function agentStatus(kinds, o) {
         const path = o?.path ?? agentProbePath();
         const run = o?.run ?? runStatusCommand;
         const timeoutMs = o?.timeoutMs ?? STATUS_TIMEOUT_MS;
-        const installed = installedSet(kinds, { path, ...(o?.aliases === undefined ? {} : { aliases: o.aliases }) });
+        const probe = { path, ...(o?.aliases === undefined ? {} : { aliases: o.aliases }),
+            ...(o?.readFile === undefined ? {} : { readFile: o.readFile }) };
         return Promise.all(kinds.map(async (kind) => {
-            // Herdr auto-installs Pi via mise on first start, so PATH presence is not the signal:
-            // Pi always reads not-installed with the readiness words instead of a missing-install error.
-            if (kind === 'pi')
-                return { kind, installed: false, signedIn: 'unknown', installHint: PI_INSTALL_HINT };
+            const install = agentInstallState(kind, probe);
             const binary = o?.aliases?.[kind]?.[0] ?? kind;
-            const installHint = `Install the ${binary} command, then check again.`;
-            if (!installed.has(kind))
-                return { kind, installed: false, signedIn: 'unknown', installHint };
-            const probe = STATUS_PROBES[kind];
-            if (probe === undefined)
-                return { kind, installed: true, signedIn: 'unknown', installHint };
+            const installHint = kind === 'pi' ? PI_INSTALL_HINT : `Install the ${binary} command, then check again.`;
+            // A shim or nothing on PATH means Herdr installs on first start: not installed, with the
+            // readiness words instead of a missing-install error (pi included — a real pi binary is
+            // the only case that reads installed).
+            if (install.state !== 'installed')
+                return { kind, installed: false, installState: install.state, signedIn: 'unknown', installHint };
+            const statusProbe = STATUS_PROBES[kind];
+            if (statusProbe === undefined)
+                return { kind, installed: true, installState: 'installed', signedIn: 'unknown', installHint };
             let answer;
             try {
-                answer = await run(probe.command, probe.args, { ...(probe.stdin === undefined ? {} : { stdin: probe.stdin }), timeoutMs });
+                answer = await run(statusProbe.command, statusProbe.args, { ...(statusProbe.stdin === undefined ? {} : { stdin: statusProbe.stdin }), timeoutMs });
             }
             catch {
                 answer = undefined;
             }
-            const signedIn = answer === undefined ? 'unknown' : probe.parse(answer.stdout);
-            return { kind, installed: true, signedIn, installHint,
+            const signedIn = answer === undefined ? 'unknown' : statusProbe.parse(answer.stdout);
+            return { kind, installed: true, installState: 'installed', signedIn, installHint,
                 ...(signedIn === 'yes' ? {} : { signInHint: SIGNIN_HINTS[kind] ?? `Sign in to ${kind} on this computer, then check again.` }) };
         }));
     }
     return { startAgent, prompt, sendKeys, wait, read, agentKinds, installedAgentKinds, agentStatus };
 }
+// One source of truth for install detection (B5's probe plus the shim layer below): the first
+// executable file named for the kind across the probe path, with its absolute path.
+export function resolveAgentBinary(kind, o) {
+    const names = [kind, ...(o.aliases?.[kind] ?? [])];
+    for (const name of names) {
+        for (const dir of o.path) {
+            if (dir === '')
+                continue;
+            const file = join(dir, name);
+            try {
+                accessSync(file, fsConstants.X_OK);
+                return { binary: name, path: file };
+            }
+            catch { /* keep looking */ }
+        }
+    }
+    return { binary: o.aliases?.[kind]?.[0] ?? kind };
+}
+// Bounded head read for the shim sniff: the first 2 KiB as text, undefined when unreadable.
+function readHead(file) {
+    let fd;
+    try {
+        fd = openSync(file, 'r');
+        const buf = Buffer.alloc(2048);
+        const n = readSync(fd, buf, 0, buf.length, 0);
+        return buf.subarray(0, n).toString('utf8');
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (fd !== undefined)
+            try {
+                closeSync(fd);
+            }
+            catch { /* already gone */ }
+    }
+}
+// A mise-style auto-install launcher reads as a shell script that execs through mise — the
+// found "binary" runs, but the first run installs the agent instead. Real binaries (ELF,
+// Mach-O) never match: the shebang gate keeps a stray "mise" substring ("promise", …) out.
+export function isAutoInstallShim(file, readFile = readHead) {
+    let head;
+    try {
+        head = readFile(file);
+    }
+    catch {
+        return false;
+    }
+    return head !== undefined && head.startsWith('#!') && head.includes('mise');
+}
+// Per-kind install readiness sharing the B5 probe path: `installed` for a real runnable binary,
+// `installs-on-first-start` for an auto-install launcher/shim or nothing on PATH (Herdr fetches
+// the agent on first start). `missing` stays for callers that probe kinds Herdr never installs.
+export function agentInstallState(kind, o) {
+    const path = o?.path ?? agentProbePath();
+    const found = resolveAgentBinary(kind, { path, ...(o?.aliases === undefined ? {} : { aliases: o.aliases }) });
+    if (found.path === undefined)
+        return { kind, state: 'installs-on-first-start' };
+    const shim = isAutoInstallShim(found.path, o?.readFile);
+    return shim ? { kind, state: 'installs-on-first-start', path: found.path }
+        : { kind, state: 'installed', path: found.path };
+}
+// Typed launch failure for the `launchFailed` event. The rejection itself is unchanged — this
+// only classifies it: a busy pane that outlasted the retry budget, an install that never
+// finished, a placement that made no pane, or any other rejected start.
+export function classifyStartFailure(error, o) {
+    const code = codeOf(error);
+    if (code !== undefined && START_RETRYABLE.has(code))
+        return 'pane-busy';
+    if (o?.stage === 'placement')
+        return 'placement-failed';
+    if (o?.installExpected === true)
+        return 'install-failed';
+    return 'start-rejected';
+}
+function launchFailureWords(reason, kind) {
+    if (reason === 'pane-busy')
+        return words('agent.notReady');
+    if (reason === 'install-failed')
+        return words('agent.installFailed', { agent: kind });
+    return words('agent.launchFailed');
+}
 // Extra install dirs muxr's `executableOnPath`
 // (`apps/host/src/agent/infrastructure/herdrSessionSource.ts`) probes past PATH: user-install
 // dirs a service or GUI daemon's inherited PATH omits — mise shims (Herdr installs Pi through

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { HERDR_VERSION, HERDR_PROTOCOL } from './constants.ts';
 export { HerdrKit } from './kit.ts';
 export { agentWords, stateWords, words, WORDS, type WordKey } from './words.ts';
-export { agentProbePath, extraPathDirs, runStatusCommand } from './agents.ts';
-export type { AgentCliSignIn, AgentReadiness, AgentStatusOptions, AgentStatusRunner, AgentRef, AgentStatus, BlockedAgent, HerdrEvent, HerdrEventName, HerdrEventOf, HerdrKitOptions, HerdrMethod, HerdrMethods, HerdrParams, HerdrProtocolRange, HerdrResult, HerdrSnapshot, HerdrState, HerdrSubscription, HerdrSubscribeStop, HerdrTransport, PromptReceipt, StartAgent, TerminalSession, } from './types.ts';
+export { agentProbePath, extraPathDirs, runStatusCommand, agentInstallState, isAutoInstallShim, resolveAgentBinary, classifyStartFailure } from './agents.ts';
+export type { AgentCliSignIn, AgentInstallProbe, AgentInstallState, AgentLaunchFailureReason, AgentReadiness, AgentStartEvent, AgentStatusOptions, AgentStatusRunner, AgentRef, AgentStatus, BlockedAgent, HerdrEvent, HerdrEventName, HerdrEventOf, HerdrKitOptions, HerdrMethod, HerdrMethods, HerdrParams, HerdrProtocolRange, HerdrResult, HerdrSnapshot, HerdrState, HerdrSubscription, HerdrSubscribeStop, HerdrTransport, Move, MoveToAccount, MoveToAccountResult, MoveResult, OpenSignInTab, PromptReceipt, StartAgent, TerminalSession, } from './types.ts';

package/dist/index.js

@@ -3,4 +3,4 @@
 export { HERDR_VERSION, HERDR_PROTOCOL } from "./constants.js";
 export { HerdrKit } from "./kit.js";
 export { agentWords, stateWords, words, WORDS } from "./words.js";
-export { agentProbePath, extraPathDirs, runStatusCommand } from "./agents.js";
+export { agentProbePath, extraPathDirs, runStatusCommand, agentInstallState, isAutoInstallShim, resolveAgentBinary, classifyStartFailure } from "./agents.js";

package/dist/kit.d.ts

@@ -1,4 +1,4 @@
-import type { AgentReadiness, AgentStatusOptions, AgentRef, AgentStatus, BlockedAgent, HerdrEvent, HerdrEventName, HerdrEventOf, HerdrKitOptions, HerdrMethod, HerdrParams, HerdrResult, HerdrSnapshot, HerdrState, HerdrSubscription, HerdrSubscribeStop, PromptReceipt, StartAgent, TerminalSession } from './types.ts';
+import type { AgentReadiness, AgentStartEvent, AgentStatusOptions, AgentRef, AgentStatus, BlockedAgent, HerdrEvent, HerdrEventName, HerdrEventOf, HerdrKitOptions, HerdrMethod, HerdrParams, HerdrResult, HerdrSnapshot, HerdrState, HerdrSubscription, HerdrSubscribeStop, PromptReceipt, StartAgent, TerminalSession, Move, MoveToAccount, MoveToAccountResult, MoveResult, OpenSignInTab } from './types.ts';
 export declare class HerdrKit {
     private readonly supervisor;
     private transport?;
@@ -14,7 +14,9 @@ export declare class HerdrKit {
     private statusEpoch;
     private readonly o;
     private readonly callAny;
+    private readonly accountPanes;
     private readonly agents;
+    private readonly startListeners;
     private readonly blockedList;
     constructor(o: HerdrKitOptions);
     get state(): HerdrState;
@@ -37,6 +39,7 @@ export declare class HerdrKit {
     subscribe<E extends HerdrEventName>(subs: HerdrSubscription<E>[], on: (e: HerdrEventOf<E>) => void, onError?: (code: string, message: string) => void): HerdrSubscribeStop;
     cli(args: string[], o?: {
         timeoutMs?: number;
+        env?: Record<string, string>;
     }): Promise<{
         stdout: string;
         stderr: string;
@@ -65,7 +68,11 @@ export declare class HerdrKit {
      * status events instead of opening a second watch.
      */
     statusWatchReady(): Promise<void>;
+    openSignInTab(o: OpenSignInTab): Promise<AgentRef>;
+    move(o: Move): Promise<MoveResult>;
+    moveToAccount(target: AgentRef, o: MoveToAccount): Promise<MoveToAccountResult>;
     startAgent(o: StartAgent): Promise<AgentRef>;
+    onStartAgent(fn: (e: AgentStartEvent) => void): () => void;
     prompt(target: AgentRef, text: string, o?: {
         wait?: {
             until?: AgentStatus[];

package/dist/kit.js

@@ -1,3 +1,4 @@
+import { createAccountPanes } from "./accounts.js";
 import { createAgents } from "./agents.js";
 import { Blocked } from "./approvals.js";
 import { runCli } from "./cli.js";
@@ -126,13 +127,21 @@ export class HerdrKit {
     // a snapshot read wins over the read (see bootstrap)
     o;
     callAny = (method, params, timeoutMs) => this.call(method, params, timeoutMs === undefined ? undefined : { timeoutMs });
+    accountPanes;
     agents;
+    startListeners = new Set();
     blockedList;
     constructor(o) {
         this.o = o;
         this.supervisor = new Supervisor(o, (s) => { this.current = s; o.onState?.(s); });
+        this.accountPanes = createAccountPanes({ call: this.callAny, startAgent: (o) => this.startAgent(o) });
         this.agents = createAgents({ call: this.callAny, snapshot: () => this.snapshot(),
-            reread: (paneId) => this.reread(paneId) });
+            reread: (paneId) => this.reread(paneId),
+            emitStart: (e) => { for (const fn of [...this.startListeners])
+                try {
+                    fn(e);
+                }
+                catch { /* a listener never breaks a start */ } } });
         this.blockedList = new Blocked({ call: this.callAny });
     }
     get state() { return this.current; }
@@ -418,7 +427,7 @@ export class HerdrKit {
             throw new Error('herdr: not connected');
         return this.transport.subscribe(subs, on, onError ?? (() => { }));
     }
-    cli(args, o) { return runCli(this.o.bin, this.supervisor.env(), args, o?.timeoutMs); }
+    cli(args, o) { return runCli(this.o.bin, { ...this.supervisor.env(), ...o?.env }, args, o?.timeoutMs); }
     terminal(paneId, o) { return openTerminal(this.o.bin, this.supervisor.env(), paneId, o); }
     snapshot() { return structuredClone(this.tree); }
     onChange(fn) { this.listeners.add(fn); return () => { this.listeners.delete(fn); }; }
@@ -437,7 +446,16 @@ export class HerdrKit {
      * status events instead of opening a second watch.
      */
     statusWatchReady() { return this.statusReadyPromise; }
+    openSignInTab(o) { return this.accountPanes.openSignInTab(o); }
+    move(o) { return this.accountPanes.move(o); }
+    moveToAccount(target, o) { return this.accountPanes.moveToAccount(target, o); }
     startAgent(o) { return this.agents.startAgent(o); }
+    // App-wide start lifecycle without polling: every startAgent's installing/ready/launchFailed
+    // lands here as well as on that call's own `onEvent`. Returns the unsubscribe function.
+    onStartAgent(fn) {
+        this.startListeners.add(fn);
+        return () => { this.startListeners.delete(fn); };
+    }
     prompt(target, text, o) { return this.agents.prompt(target, text, o); }
     sendKeys(target, keys) { return this.agents.sendKeys(target, keys); }
     wait(target, o) { return this.agents.wait(target, o); }

package/dist/types.d.ts

@@ -48,9 +48,16 @@ export type { HerdrMethods, HerdrMethod, HerdrParams, HerdrResult } from './gene
 export type { HerdrEvents, HerdrEventName, HerdrEventOf, HerdrSubscription } from './generated/events.ts';
 export type AgentStatus = 'idle' | 'working' | 'blocked' | 'done' | 'unknown';
 export type AgentCliSignIn = 'yes' | 'no' | 'unknown';
+export type AgentInstallState = 'installed' | 'installs-on-first-start' | 'missing';
+export type AgentInstallProbe = {
+    path?: string[];
+    aliases?: Record<string, string[]>;
+    readFile?: (file: string) => string | undefined;
+};
 export type AgentReadiness = {
     kind: string;
     installed: boolean;
+    installState: AgentInstallState;
     signedIn: AgentCliSignIn;
     installHint: string;
     signInHint?: string;
@@ -64,9 +71,25 @@ export type AgentStatusRunner = (command: string, args: string[], o?: {
 export type AgentStatusOptions = {
     path?: string[];
     aliases?: Record<string, string[]>;
+    readFile?: (file: string) => string | undefined;
     run?: AgentStatusRunner;
     timeoutMs?: number;
 };
+export type AgentLaunchFailureReason = 'placement-failed' | 'pane-busy' | 'install-failed' | 'start-rejected';
+export type AgentStartEvent = {
+    phase: 'installing';
+    kind: string;
+    message: string;
+} | {
+    phase: 'ready';
+    kind: string;
+    ref: AgentRef;
+} | {
+    phase: 'launchFailed';
+    kind: string;
+    reason: AgentLaunchFailureReason;
+    message: string;
+};
 export type AgentRef = {
     paneId: string;
     name?: string;
@@ -95,12 +118,51 @@ export type StartAgent = {
     args?: string[];
     env?: Record<string, string>;
     timeoutMs?: number;
+    onEvent?: (e: AgentStartEvent) => void;
+    installProbe?: AgentInstallProbe;
+};
+export type OpenSignInTab = Omit<StartAgent, 'place' | 'worktree'> & {
+    workspaceId: string;
+    label?: string;
 };
+export type MoveToAccount = {
+    provider: 'claude' | 'codex';
+    folder: string;
+    env?: Record<string, string>;
+    direction?: 'right' | 'down';
+    timeoutMs?: number;
+};
+export type MoveToAccountResult = {
+    ok: true;
+    session: string;
+} | {
+    ok: false;
+    code: 'too_early' | 'busy' | 'unsupported' | 'env_mismatch' | 'close_failed' | 'start_failed';
+    message: string;
+    live?: string;
+};
+export type Move = {
+    paneId: string;
+    kind: string;
+    args: string[];
+    set: Record<string, string>;
+    unset?: string[];
+    onStaged?(newPaneId: string): void;
+    onReplaced?(newPaneId: string): void;
+    timeoutMs?: number;
+};
+export type MoveResult = {
+    ok: true;
+    paneId: string;
+} | Extract<MoveToAccountResult, {
+    ok: false;
+}>;
 export type PromptReceipt = {
     paneId: string;
     terminalId: string;
     revision: number;
     status: AgentStatus;
+    agentSession?: AgentSessionRef;
 };
 export type BlockedAgent = {
     paneId: string;

package/dist/words.json

@@ -13,7 +13,16 @@
     "agent.unknown": "Running.",
     "agent.signIn": "Sign in inside {agent}: follow its own steps on the screen.",
     "agent.notReady": "This helper isn't ready yet. Try again in a moment.",
+    "agent.installing": "Installing {agent}…",
+    "agent.installFailed": "Installing {agent} didn't finish. Try again in a moment.",
+    "agent.launchFailed": "That helper couldn't start. Try again in a moment.",
     "approval.stale": "That question already changed. Look again before answering.",
     "close.wouldWiden": "Closing this would close more than you picked. Close the bigger one instead.",
-    "link.notAllowed": "This device can't do that. Ask the person at the computer."
+    "link.notAllowed": "This device can't do that. Ask the person at the computer.",
+    "move.too_early": "This conversation has not started yet. Try again in a moment.",
+    "move.busy": "Wait for this conversation to finish before moving it.",
+    "move.unsupported": "This conversation cannot move between these accounts.",
+    "move.env_mismatch": "The new pane did not receive that sign-in. Try again.",
+    "move.close_failed": "The old pane could not close. The move was undone where possible.",
+    "move.start_failed": "The new account could not take over. Try again."
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/herdr",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Drive the Herdr on this computer — workspaces, tabs, panes, agents and blocked-approval answers — from an app, or hand it to a phone over @byokit/link.",
   "license": "Apache-2.0",
   "type": "module",
@@ -52,9 +52,9 @@
     "prepack": "tsc -b && node ../../scripts/fix-words-dts.cjs"
   },
   "dependencies": {
-    "@byokit/link": "0.6.0",
-    "@byokit/relay": "0.4.2",
-    "@byokit/reach": "0.4.0",
+    "@byokit/link": "0.7.0",
+    "@byokit/relay": "0.5.0",
+    "@byokit/reach": "0.6.0",
     "@byokit/seal": "0.2.0",
     "ws": "8.21.3"
   },