@byokit/herdr 0.4.1 → 0.7.0

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ## Unreleased
 
+## 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.
+
 ## 0.4.1 (2026-10-01)
 
 - Dependency update: pins @byokit/relay 0.5.1.

package/README.md

@@ -190,15 +190,36 @@ 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.
 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 +263,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 +310,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
@@ -391,3 +473,10 @@ package, never touches a person's other AI tools. Its tests run against a fake H
 ## License
 
 Apache-2.0. See [LICENSE](LICENSE) and [NOTICE](../../NOTICE).
+
+`startAgent` and `openSignInTab` accept the accounts `launchEnv()` result as `env: launch`.
+The host and Herdr must share a filesystem. New panes and existing idle POSIX shells apply
+the settings and unsets through a private temporary file before launch; only the file path
+is sent to the terminal. Busy panes and unsupported shells fail closed. Legacy record env
+still travels on new-pane placement, and remains refused on existing panes. Credential
+values must never be supplied in agent args.

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();
@@ -62,8 +64,17 @@ export function createAccountPanes(ctx) {
         }
     }
     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 +96,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 +166,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 {
@@ -158,25 +219,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)
@@ -199,10 +278,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>;

package/dist/agents.js

@@ -3,10 +3,13 @@
 // 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, openSync, readSync, closeSync } from 'node:fs';
+import { accessSync, constants as fsConstants, openSync, readSync, closeSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { delimiter, join } from 'node:path';
+import { delimiter, isAbsolute, join } from 'node:path';
 import { words } from "./words.js";
+import { accountKind } from "./kinds.js";
+import { prepareLaunchEnv } from "./launch-env.js";
+import { museNative, MUSE_INSTALL_URL } from "./muse.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
@@ -61,19 +64,37 @@ export function createAgents(ctx) {
             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 {
+            if (o.kind === 'muse') {
+                const replacement = o.env && typeof o.env.env === 'object' && Array.isArray(o.env.unset)
+                    ? o.env : undefined;
+                const existingPane = 'pane' in o.place && o.worktree === undefined;
+                // An ordinary env overlay cannot replace an existing shell's environment.
+                if (existingPane && !replacement && Object.keys(o.env ?? {}).length > 0) {
+                    throw fail('env_mismatch', 'This pane needs to be opened again to use that sign-in.');
+                }
+                const effective = replacement?.env ?? (existingPane ? undefined
+                    : { ...ctx.launchEnv?.(), ...o.env });
+                // No controller/global extras and no probe override when the effective PATH is known.
+                // Existing unobserved panes remain unknown; the exact RPC pass-through remains available.
+                const path = effective?.PATH?.split(delimiter).filter(isAbsolute);
+                const probe = path === undefined ? (existingPane ? undefined : o.installProbe) : { path };
+                if (probe && agentInstallState('muse', probe).state === 'missing') {
+                    throw fail('agent_not_installed', words('agent.notInstalled'));
+                }
+            }
+            else {
+                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 }) });
             const ref = await startAgentInner(o, () => { stage = 'start'; });
             emit({ phase: 'ready', kind: o.kind, ref });
             return ref;
@@ -81,15 +102,21 @@ export function createAgents(ctx) {
         catch (error) {
             const reason = classifyStartFailure(error, { installExpected, stage });
             emit({ phase: 'launchFailed', kind: o.kind, reason, message: launchFailureWords(reason, o.kind) });
+            if (codeOf(error) === 'agent_not_installed')
+                throw error;
+            if (o.env && typeof o.env.env === 'object')
+                throw fail(codeOf(error) === 'env_mismatch' ? 'env_mismatch' : 'start_failed', words('agent.notReady'));
             throw error;
         }
     }
     async function startAgentInner(o, onStartPhase) {
-        if ('pane' in o.place && Object.keys(o.env ?? {}).length > 0) {
+        const launch = o.env && typeof o.env.env === 'object' && Array.isArray(o.env.unset)
+            ? o.env : undefined;
+        if (!launch && '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 };
+        const env = o.env === undefined || launch ? {} : { env: o.env };
         let paneId;
         let created = false;
         if (o.worktree !== undefined) {
@@ -127,6 +154,20 @@ export function createAgents(ctx) {
         }
         if (paneId === undefined)
             throw new Error('herdr: the placement answered no pane id');
+        if (launch) {
+            try {
+                await prepareLaunchEnv(call, paneId, launch, timeout);
+            }
+            catch (error) {
+                if (created) {
+                    try {
+                        await call('pane.close', { pane_id: paneId });
+                    }
+                    catch { /* best effort */ }
+                }
+                throw error;
+            }
+        }
         onStartPhase?.();
         const name = agentName(o);
         const params = { pane_id: paneId, kind: o.kind, name,
@@ -148,6 +189,8 @@ export function createAgents(ctx) {
                     }
                     catch { /* rollback is best-effort */ }
                 }
+                if (launch)
+                    throw fail('start_failed', words('agent.notReady'));
                 throw error;
             }
         }
@@ -226,7 +269,7 @@ export function createAgents(ctx) {
         return kinds.filter((kind) => resolveAgentBinary(kind, o).path !== undefined);
     }
     async function agentStatus(kinds, o) {
-        const path = o?.path ?? agentProbePath();
+        const path = o?.path ?? ctx.launchEnv?.()?.PATH?.split(delimiter) ?? agentProbePath();
         const run = o?.run ?? runStatusCommand;
         const timeoutMs = o?.timeoutMs ?? STATUS_TIMEOUT_MS;
         const probe = { path, ...(o?.aliases === undefined ? {} : { aliases: o.aliases }),
@@ -234,18 +277,27 @@ export function createAgents(ctx) {
         return Promise.all(kinds.map(async (kind) => {
             const install = agentInstallState(kind, probe);
             const binary = o?.aliases?.[kind]?.[0] ?? kind;
-            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).
+            const installHint = kind === 'muse' ? `Install Muse explicitly from ${MUSE_INSTALL_URL} into the private launch environment.`
+                : kind === 'pi' ? PI_INSTALL_HINT : `Install the ${binary} command, then check again.`;
+            // Muse missing/launcher-only stays missing; legacy kinds retain their shim readiness.
+            // Install state never proves account or catalog readiness.
             if (install.state !== 'installed')
                 return { kind, installed: false, installState: install.state, signedIn: 'unknown', installHint };
             const statusProbe = STATUS_PROBES[kind];
-            if (statusProbe === undefined)
+            const variable = accountKind(kind)?.folderVar;
+            const folder = o?.folders?.[kind];
+            if (statusProbe === undefined || variable === undefined || !folder || !isAbsolute(folder) || /[\r\n\0]/.test(folder))
                 return { kind, installed: true, installState: 'installed', signedIn: 'unknown', installHint };
             let answer;
+            // A folder override alone is not isolation: the CLI can fall back to HOME,
+            // XDG or platform stores. Supply a clean env and confine every home to this account.
+            const env = { ...o?.env, PATH: path.join(delimiter), HOME: folder, USERPROFILE: folder,
+                XDG_CONFIG_HOME: join(folder, '.config'), XDG_STATE_HOME: join(folder, '.local', 'state'),
+                XDG_DATA_HOME: join(folder, '.local', 'share'), XDG_CACHE_HOME: join(folder, '.cache'),
+                APPDATA: join(folder, 'AppData', 'Roaming'), LOCALAPPDATA: join(folder, 'AppData', 'Local'),
+                [variable]: folder };
             try {
-                answer = await run(statusProbe.command, statusProbe.args, { ...(statusProbe.stdin === undefined ? {} : { stdin: statusProbe.stdin }), timeoutMs });
+                answer = await run(install.path, statusProbe.args, { ...(statusProbe.stdin === undefined ? {} : { stdin: statusProbe.stdin }), timeoutMs, env });
             }
             catch {
                 answer = undefined;
@@ -308,14 +360,27 @@ export function isAutoInstallShim(file, readFile = readHead) {
     }
     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.
+// Muse has no absent-CLI auto-installer in stock Herdr. Its official launcher needs the
+// selected native release too. Other kinds retain their legacy shim classification.
 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' };
+        return { kind, state: kind === 'muse' ? 'missing' : 'installs-on-first-start' };
+    if (kind === 'muse') {
+        try {
+            if (!statSync(found.path).isFile())
+                return { kind, state: 'missing', path: found.path };
+        }
+        catch {
+            return { kind, state: 'missing', path: found.path };
+        }
+        const head = (o?.readFile ?? readHead)(found.path);
+        if (head?.startsWith('#!') && (head.includes('mise') || (head.includes('MUSE_CHANNEL') && !museNative(found.path)))) {
+            return { kind, state: 'missing', path: found.path };
+        }
+        return { kind, state: 'installed', path: found.path };
+    }
     const shim = isAutoInstallShim(found.path, o?.readFile);
     return shim ? { kind, state: 'installs-on-first-start', path: found.path }
         : { kind, state: 'installed', path: found.path };
@@ -325,6 +390,8 @@ export function agentInstallState(kind, o) {
 // finished, a placement that made no pane, or any other rejected start.
 export function classifyStartFailure(error, o) {
     const code = codeOf(error);
+    if (code === 'agent_not_installed')
+        return 'not-installed';
     if (code !== undefined && START_RETRYABLE.has(code))
         return 'pane-busy';
     if (o?.stage === 'placement')
@@ -334,6 +401,8 @@ export function classifyStartFailure(error, o) {
     return 'start-rejected';
 }
 function launchFailureWords(reason, kind) {
+    if (reason === 'not-installed')
+        return words('agent.notInstalled');
     if (reason === 'pane-busy')
         return words('agent.notReady');
     if (reason === 'install-failed')
@@ -375,7 +444,7 @@ const STATUS_PROBES = {
             }
             if (!isRecord(status))
                 return 'unknown';
-            return status.loggedIn === true ? 'yes' : 'no';
+            return status.loggedIn === true ? 'yes' : status.loggedIn === false ? 'no' : 'unknown';
         } },
     // Codex exposes sign-in only over its app-server protocol, so the probe pipes a pipelined
     // `initialize` + `account/read` round (same method muxr's planIdentity uses) and reads the
@@ -392,7 +461,10 @@ const STATUS_PROBES = {
                     continue;
                 }
                 if (isRecord(message) && message.id === 2) {
-                    return isRecord(message.result) && isRecord(message.result.account) ? 'yes' : 'no';
+                    if (!isRecord(message.result))
+                        return 'unknown';
+                    return isRecord(message.result.account) ? 'yes'
+                        : message.result.account === null || !Object.hasOwn(message.result, 'account') ? 'no' : 'unknown';
                 }
             }
             return 'unknown';
@@ -401,8 +473,12 @@ const STATUS_PROBES = {
 // Default runner: one bounded spawn per probe, stdin piped when the protocol needs it (codex).
 // Failures (missing binary, timeout, non-empty stderr, empty stdout) read as no answer — never throw.
 export async function runStatusCommand(command, args, o) {
+    // Public direct calls without an explicit isolated HOME are not allowed to read a login.
+    if (!o?.env?.HOME || !isAbsolute(o.env.HOME) || /[\r\n\0]/.test(o.env.HOME))
+        return undefined;
     return new Promise((resolve) => {
         let done = false;
+        let timer;
         const finish = (value) => {
             if (done)
                 return;
@@ -412,14 +488,14 @@ export async function runStatusCommand(command, args, o) {
         };
         let child;
         try {
-            child = spawn(command, args, { stdio: ['pipe', 'pipe', 'ignore'], timeout: o?.timeoutMs ?? STATUS_TIMEOUT_MS });
+            child = spawn(command, args, { env: o.env, stdio: ['pipe', 'pipe', 'ignore'], timeout: o.timeoutMs ?? STATUS_TIMEOUT_MS });
         }
         catch {
             finish(undefined);
             return;
         }
         let out = '';
-        const timer = setTimeout(() => { child.kill('SIGKILL'); finish(undefined); }, (o?.timeoutMs ?? STATUS_TIMEOUT_MS) + 500);
+        timer = setTimeout(() => { child.kill('SIGKILL'); finish(undefined); }, (o?.timeoutMs ?? STATUS_TIMEOUT_MS) + 500);
         child.on('error', () => finish(undefined));
         const stdout = child.stdout;
         const stdin = child.stdin;