@byokit/herdr 0.7.2 → 0.8.0

package/CHANGELOG.md

@@ -2,6 +2,45 @@
 
 ## Unreleased
 
+## 0.8.0 (2026-10-12)
+
+- Dependency update: pins @byokit/discover 0.8.0.
+- Dependency update: pins @byokit/relay 0.6.1.
+- Dependency update: pins @byokit/pair 0.10.0.
+
+- FIX: A Node script (or any non-shell interpreter) whose path contains `mise` is now a real installed binary, so `agentStatus` runs its sign-in check instead of skipping it as an auto-install shim; only a shell launcher that mentions mise still reads `installs-on-first-start`.
+- `startAgent` accepts a workspace label as `place.workspace`: the agent lands in the one workspace with that label (new tab, `created: false`) or in a workspace created with that label (`created: true`). Two workspaces with the label refuse with `workspace-ambiguous` and create nothing, and a failed start rolls back only what the kit made (the fresh pane, or the fresh workspace), never a reused workspace. `AgentRef` carries the new `created` flag.
+- New control link ops `hd.rename { pane | tab | workspace, label }`, `hd.focus { pane | tab | workspace }` and
+  `hd.layout { root, focus?, tabId?, tabLabel?, workspaceId? }`, with device `rename()`, `focus()` and
+  `layout()`. Each copies `hd.close`'s scope rule: the one pane, tab (through its owning workspace) or
+  workspace it names must be in `scopeOf(grant)`, or the device hears the `link.notAllowed` sentence and no
+  Herdr call is made; a `view` grant is refused. They map only to the typed `pane.rename`/`tab.rename`/
+  `workspace.rename`, `pane.focus`/`tab.focus`/`workspace.focus` and `layout.apply` calls, never through
+  `hd.call`. The fake Herdr now answers `layout.apply` and emits `layout.updated`.
+- `sealNotice`/`openNotice` (and the portable `./device` re-export) now delegate to `@byokit/seal`'s generic
+  `sealNotice`/`openNotice` instead of sealing and opening the box here: the device seed becomes the box secret
+  through `boxKeyPairFromSeed`, and the opened value is still shape-checked as a `BlockedAgent`. The wire format is
+  unchanged, so a notice sealed by an earlier kit still opens, and `seal.openNotice` opens a herdr notice. The
+  hand-rolled base64url helpers stay only for the box-key registration text (`boxPublicKeyB64`, link.ts's
+  `decodeB64Url`), because seal exports no base64url.
+- FIX: A refused widening close now tells the app which scope it would widen to: `closePane`/`closeTab`/`closeWorkspace` still throw `pane-close-would-widen`/`tab-close-would-widen`/`workspace-close-would-widen`, but each also carries the wider target as `{ scope: 'tab' | 'workspace', id, label }` (a pane's tab, a tab's workspace, a worktree group named by its root), so the UI can offer the bigger close instead. `hd.close` over a link maps all three codes to a `PublicLinkError` with the `close.wouldWiden` words, so a device hears plain words instead of a bare failure.
+- FIX: `moveToAccount` refuses signed-out managed targets before waiting or creating a pane, preserving the source; generic `move` remains caller-gated and unknown readiness still proceeds.
+- FIX: Muse readiness routes its mise check through the shared shell-launcher predicate, so a non-shell binary whose interpreter path contains `mise` reads installed instead of launcher-only; genuine mise shell shims still read launcher-only.
+- FIX: `runTurn` accepts an agent that is already `done` when the turn starts, treating it like `idle` at turn start; previously the call was refused with `turn-not-idle`/`turn-busy`.
+- FIX: `runTurn` accepts `files: false` to skip the file scan entirely (`changedFiles` is then always empty), so a turn rooted in a folder with more than 10000 entries no longer fails with `turn: file limit`.
+
+## 0.7.3 (2026-10-11)
+
+- Dependency update: pins @byokit/discover 0.7.0.
+
+- `@byokit/herdr` exports `isPromptable(agent)`, the single readiness gate `prompt` already used, and adds
+  `kit.waitPromptable(target, { timeoutMs })`: it waits until a just-started agent can take a prompt instead of the
+  host polling `prompt` and catching `agent-not-ready`. It resolves once the kit's snapshot is promptable, rejects
+  `agent-not-ready` at the deadline, and rejects `pane-unavailable` when the pane closes mid-wait.
+- The README's rename note and examples now point at `@byokit/pair` (the phone hand-off host) and the
+  example screenshots were re-captured from today's herdr-kit phone page. Docs only; no typed surface changed.
+- Dependency update: depend on `@byokit/pair` 0.9.0 instead of its deprecated `@byokit/link` shim.
+
 ## 0.7.2 (2026-10-09)
 
 - Dependency update: pins @byokit/relay 0.6.0.

package/README.md

@@ -8,13 +8,16 @@
 
 <p align="center"><strong>Drive the Herdr already on this computer from an app, or from a phone.</strong><br/>
 Workspaces, tabs, panes, coding agents and blocked-approval answers, from a Node app or handed to a phone over
-<a href="../link"><code>@byokit/link</code></a>. Each agent inside Herdr keeps its own subscription login; the kit
+<a href="../pair"><code>@byokit/pair</code></a>. Each agent inside Herdr keeps its own subscription login; the kit
 never sees a credential.</p>
 
+<p align="center"><sub>This kit depends on <a href="../pair"><code>@byokit/pair</code></a>, and its examples
+import from there.</sub></p>
+
 <p align="center">
-  <img src="https://raw.githubusercontent.com/umeranjum17/byokit/main/examples/herdr-kit/docs/3-agent.png" width="240" alt="Phone page titled Agents, Connected to Kitchen computer and Connected to Herdr: two pi agents marked Ready for you, and under Talk to it the agent's screen reading '> Add a --json flag to export', 'Read src/cli/export.ts', 'Edited src/cli/export.ts +18 -3' and 'export --json now prints JSON.' above a Message box, a Send button and Sent." />
-  <img src="https://raw.githubusercontent.com/umeranjum17/byokit/main/examples/herdr-kit/docs/4-question.png" width="240" alt="Phone page with Questions for you at the top: pi, Waiting for your answer., the question 'Allow this? (y/n)' and buttons Enter, y, n and Esc; below, the second pi agent marked Waiting for your answer." />
-  <img src="https://raw.githubusercontent.com/umeranjum17/byokit/main/examples/herdr-kit/docs/5-answered.png" width="240" alt="Phone page after the answer: no Questions for you section, both pi agents marked Ready for you, and the agent's screen ending in 'Allow this? (y/n)', 'y' and 'npm test: 42 passing'" />
+  <img src="https://raw.githubusercontent.com/umeranjum17/byokit/main/examples/herdr-kit/docs/3-agent.png" width="240" alt="Phone page titled Agents, Connected to Kitchen computer - same Wi-Fi.: two Pi agents marked Ready for you, and under Talk to it the agent's screen reading '> Add a --json flag to export', 'Read src/cli/export.ts', 'Edited src/cli/export.ts +18 -3' and 'export --json now prints JSON.' above a Message box, a Send button and Waiting for the reply below." />
+  <img src="https://raw.githubusercontent.com/umeranjum17/byokit/main/examples/herdr-kit/docs/4-question.png" width="240" alt="Phone page with Questions for you at the top: Pi, Waiting for your answer., the question 'Allow this? (y/n)' and buttons Allow, Deny and Skip; below, the second Pi agent marked Waiting for your answer." />
+  <img src="https://raw.githubusercontent.com/umeranjum17/byokit/main/examples/herdr-kit/docs/5-answered.png" width="240" alt="Phone page after the answer: no Questions for you section, both Pi agents marked Ready for you, and the agent's screen ending in 'Allow this? (y/n)', 'y' and 'npm test: 42 passing'" />
 </p>
 <p align="center"><sub>The <a href="../../examples/herdr-kit">herdr-kit example</a>'s phone page: an agent at work, its
 question, answered. Captured by the example's e2e in a phone-sized headless Chromium, against the kit's stand-in
@@ -90,7 +93,7 @@ Waiting for your answer. | Allow this? (y/n)
 idle
 ```
 
-To hand Herdr to a phone, spread `herdrLink` into a `@byokit/link` host and serve it; the phone calls the same
+To hand Herdr to a phone, spread `herdrLink` into a `@byokit/pair` host and serve it; the phone calls the same
 things through `herdrDevice`:
 
 ```ts
@@ -106,8 +109,8 @@ const own = new HerdrKit({ mode: 'own', bin, stateDir: './.state' });
 ```ts
 import { HerdrKit } from '@byokit/herdr';
 import { herdrLink, serve } from '@byokit/herdr/link';
-import { Host, type Grant } from '@byokit/link';
-import { hostKeyFile } from '@byokit/link/node';
+import { Host, type Grant } from '@byokit/pair';
+import { hostKeyFile } from '@byokit/pair/node';
 
 const kit = new HerdrKit({ mode: 'own', bin: '/usr/local/bin/herdr', stateDir: './.state' });
 const grants: Grant[] = [];
@@ -128,7 +131,7 @@ kit.start().catch(() => {});        // non-fatal: retry later while Herdr is dow
 ```
 
 ```ts
-import type { DeviceLink } from '@byokit/link';
+import type { DeviceLink } from '@byokit/pair';
 import { agentWords, herdrDevice } from '@byokit/herdr/device';
 
 declare const link: DeviceLink;     // from pairing (pairWithCode / pairWithOffer)
@@ -153,8 +156,8 @@ kit does not have yet, and [Two ways in](#two-ways-in) plus
 
 | Export | What it does |
 |---|---|
-| `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) |
+| `HerdrKit` (`@byokit/herdr`) | The host-side kit, in `adopt` or `own` mode: `start`/`stop`, `state`, `snapshot`/`onChange`, `startAgent`, `openSignInTab`, `move`, `moveToAccount`, `onStartAgent`, `prompt`, `waitPromptable`, `sendKeys`, `wait`, `read`, `blocked`/`onBlocked`/`answer`, `closePane`/`closeTab`/`closeWorkspace`, `agentKinds`, `installedAgentKinds`, `agentStatus`, `agentInstallState`, `terminal`, `onEvent`, `statusWatchReady`, and the pass-throughs `call`, `subscribe` and `cli` |
+| `isPromptable`, `agentStatus`, `agentInstallState`, `agentProbePath`, `extraPathDirs`, `runStatusCommand`, `isAutoInstallShim`, `resolveAgentBinary` (`@byokit/herdr`) | `isPromptable(agent)` is the readiness rule `prompt` and `waitPromptable` share; the rest is 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 |
@@ -174,6 +177,12 @@ 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.
 
+A just-started agent is not promptable until its launch settles. Instead of polling `prompt` and catching
+`agent-not-ready`, wait once: `await kit.waitPromptable(agent, { timeoutMs: 30_000 })` resolves the moment the
+kit's snapshot is promptable — the same gate (`isPromptable`: not `launch_pending` and status idle/working/blocked/done)
+`prompt` itself uses. At the deadline it rejects with code `agent-not-ready`; a pane that closes while waiting rejects
+with code `pane-unavailable`, so the wait never hangs.
+
 ## Account-specific sign-ins and moves
 
 The host supplies account folders and shares conversation history as needed. The kit never reads or copies
@@ -196,6 +205,7 @@ if (moved.ok) console.log(moved.session); // new pane to follow
 
 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.
+`moveToAccount` checks the target managed folder once with `agentStatus`, after immediate refusals and before waiting or splitting. A signed-out target returns `signed_out` and “Sign in to {name} first.” (`name` defaults to “this account”), with `live` naming the unchanged source and no new pane. Unknown readiness proceeds (including Pi); generic `move` has no check, so Accounts hosts call `cliAccounts.launch` and pass its `set`/`unset` only on success. The check is not a lock: a later sign-out still starts only in the selected folder, with existing `start_failed` rollback and no default-login retry.
 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
@@ -277,12 +287,17 @@ the extra install dirs a service PATH omits (`extraPathDirs`: `~/.local/bin`, th
 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, retains the legacy `installState: 'installs-on-first-start'` with `installed: false`.
+real runnable binary apart from an auto-install launcher: a shell script (a `sh`, `bash`, `zsh`,
+`dash`, `ksh` or `ash` shebang) whose text mentions mise, or nothing on PATH at all, retains the
+legacy `installState: 'installs-on-first-start'` with `installed: false`. A binary whose interpreter
+merely lives under mise (for example a Node script) reads `installed`.
 **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`.
+first start`, while a real `pi` binary reads `installed: true`. The `museReadiness()` probe's
+`launcher-only` state is a separate check, not this shell-shebang rule: it flags any `#!` file whose
+head contains `mise`, so a Node script under mise reads `launcher-only` there but `installed` on the
+agent path.
 
 ```ts
 import { HerdrKit } from '@byokit/herdr';
@@ -447,6 +462,7 @@ targets, do not traverse symlinks, always exclude `.git`, and ignore special fil
 and restored during the turn do not appear. Use `files.exclude` to prune generated or sensitive
 folders. Each scan defaults to 10000 entries and 128 MiB of regular-file content; set
 `files.maxFiles`/`maxBytes` to change these limits. An incomplete scan rejects the call.
+Pass `files: false` to skip the scan entirely (`changedFiles` is then always empty).
 
 Reserve the pane and folder exclusively while the turn runs. Overlapping calls in one kit are
 refused, but changes by other apps or processes cannot be attributed to this agent. The supplied

package/dist/accounts.d.ts

@@ -1,8 +1,9 @@
 import type { Call } from './agents.ts';
-import type { AgentRef, Move, MoveResult, MoveToAccount, MoveToAccountResult, OpenSignInTab, StartAgent } from './types.ts';
+import type { AgentReadiness, AgentStatusOptions, AgentRef, Move, MoveResult, MoveToAccount, MoveToAccountResult, OpenSignInTab, StartAgent } from './types.ts';
 export declare function createAccountPanes(ctx: {
     call: Call;
     startAgent(o: StartAgent): Promise<AgentRef>;
+    agentStatus(kinds: readonly string[], o?: AgentStatusOptions): Promise<AgentReadiness[]>;
 }): {
     openSignInTab: (o: OpenSignInTab) => Promise<AgentRef>;
     move: (o: Move) => Promise<MoveResult>;

package/dist/accounts.js

@@ -78,7 +78,7 @@ export function createAccountPanes(ctx) {
         }
     }
     async function perform(target, o, request) {
-        const failed = (code, live = target.paneId) => ({ ok: false, code, message: words(`move.${code}`), ...(live === null ? {} : { live }) });
+        const failed = (code, live = target.paneId) => ({ ok: false, code, message: words(`move.${code}`, { name: o.name ?? 'this account' }), ...(live === null ? {} : { live }) });
         if (moving.has(target.paneId))
             return failed('busy');
         moving.add(target.paneId);
@@ -114,34 +114,6 @@ export function createAccountPanes(ctx) {
                 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;
             const metadata = accountKind(o.provider);
@@ -161,6 +133,39 @@ export function createAccountPanes(ctx) {
             if (!Number.isFinite(timeout) || timeout <= 0)
                 return failed('start_failed');
             const variable = metadata.folderVar;
+            if (request === undefined) {
+                const [status] = await ctx.agentStatus([kind], { folders: { [kind]: o.folder }, env: o.env });
+                if (status?.signedIn === 'no')
+                    return failed('signed_out');
+            }
+            if (handoff?.busy === 'wait' && 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;
+            }
             let paneId;
             let replacement;
             try {

package/dist/agents.d.ts

@@ -1,13 +1,14 @@
 import type { HerdrKit } from './kit.ts';
-import type { AgentInstallProbe, AgentInstallState, AgentLaunchFailureReason, AgentStartEvent, HerdrSnapshot } from './types.ts';
+import type { AgentInstallProbe, AgentInstallState, AgentLaunchFailureReason, AgentStartEvent, HerdrSnapshot, HerdrSnapshotAgent } from './types.ts';
 export type Call = (method: string, params: Record<string, unknown>, timeoutMs?: number) => Promise<unknown>;
+export declare function isPromptable(agent: HerdrSnapshotAgent | undefined): boolean;
 export declare function createAgents(ctx: {
     call: Call;
     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'>;
+}): Pick<HerdrKit, 'startAgent' | 'prompt' | 'waitPromptable' | 'sendKeys' | 'wait' | 'read' | 'agentKinds' | 'installedAgentKinds' | 'agentStatus'>;
 export declare function resolveAgentBinary(kind: string, o: {
     path: string[];
     aliases?: Record<string, string[]>;

package/dist/agents.js

@@ -9,9 +9,10 @@ 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";
+import { museNative, MUSE_INSTALL_URL, isMiseLauncher } from "./muse.js";
 const PROMPTABLE = ['idle', 'working', 'blocked', 'done'];
 const DEFAULT_TIMEOUT_MS = 60_000;
+const WAIT_PROMPTABLE_POLL_MS = 50;
 // `agent.start` lands while the fresh pane is still at its shell prompt: the server answers
 // `agent_pane_busy`/`agent_pane_unavailable` until the pane is ready. The kit retries those for a
 // bounded 5 s, then rolls the pane it created back with `pane.close` like any other start failure.
@@ -36,6 +37,12 @@ function agentOf(snapshot, paneId) {
             }
     return undefined;
 }
+// The one readiness gate (6.4): an agent record is promptable when it exists, is not mid-launch and
+// its status is one Herdr accepts a prompt in. `prompt` refuses with `agent-not-ready` and
+// `waitPromptable` waits, both through this single rule.
+export function isPromptable(agent) {
+    return agent !== undefined && agent.launchPending !== true && PROMPTABLE.includes(agent.status);
+}
 // `agent.start` requires a name matching /^[a-z][a-z0-9_-]{0,31}$/; derive one from the kind when absent.
 function agentName(o) {
     const slug = (o.name ?? o.kind).toLowerCase().replace(/[^a-z0-9_-]+/g, '-').replace(/^[-_0-9]+/, '').slice(0, 32);
@@ -55,7 +62,9 @@ export function createAgents(ctx) {
     };
     // 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.
+    // start fails, so a failed start leaves no extra pane behind. A label placement that created
+    // its workspace rolls the workspace back with `workspace.close` instead, so no empty workspace
+    // survives either; a reused workspace is never closed.
     async function startAgent(o) {
         const emit = (e) => {
             try {
@@ -123,7 +132,24 @@ export function createAgents(ctx) {
                 XDG_STATE_HOME: join(home, '.local', 'state'), XDG_CACHE_HOME: join(home, '.cache'), ...o.env
             } };
         let paneId;
-        let created = false;
+        let createdPane = false; // a pane this start made: roll it back on failure
+        let createdWorkspace; // a workspace this start made: roll it back instead
+        let workspaceCreated = false; // reported as `created`: a workspace was made
+        async function rollback() {
+            if (createdWorkspace !== undefined) {
+                try {
+                    await call('workspace.close', { workspace_id: createdWorkspace });
+                    return;
+                }
+                catch { /* fall through to the pane when the workspace close misses */ }
+            }
+            if (createdPane && paneId !== undefined) {
+                try {
+                    await call('pane.close', { pane_id: paneId });
+                }
+                catch { /* rollback is best-effort */ }
+            }
+        }
         if (o.worktree !== undefined) {
             const made = await call('worktree.create', { cwd: o.cwd, focus: false, ...env,
                 ...(o.worktree.branch === undefined ? {} : { branch: o.worktree.branch }),
@@ -136,23 +162,50 @@ export function createAgents(ctx) {
             paneId = rootPaneOf(made) ?? rootPaneOf(await call('tab.create', {
                 workspace_id: made?.workspace?.workspace_id, cwd: checkout, focus: false, ...env,
             }));
-            created = true;
+            createdPane = true;
+            workspaceCreated = true;
+        }
+        else if ('workspace' in o.place && o.place.workspace !== 'new') {
+            // A workspace label (6.4): reuse the one workspace with this label, or create it.
+            // The lookup is a fresh `workspace.list`, never the kit's tree, so a workspace made
+            // moments ago is found. Two matches refuse with `workspace-ambiguous` and pick nothing.
+            const label = o.place.workspace;
+            const listed = await call('workspace.list', {});
+            const workspaces = Array.isArray(listed?.workspaces) ? listed.workspaces : [];
+            const matches = workspaces.filter((w) => isObj(w) && w.label === label);
+            if (matches.length > 1)
+                throw fail('workspace-ambiguous', `More than one workspace is named "${label}". Rename one, then try again.`);
+            if (matches.length === 1) {
+                paneId = rootPaneOf(await call('tab.create', { workspace_id: matches[0].workspace_id, cwd: o.cwd,
+                    ...(o.place.label === undefined ? {} : { label: o.place.label }), focus: false, ...env }));
+                createdPane = true;
+            }
+            else {
+                const made = await call('workspace.create', { cwd: o.cwd, label, focus: false, ...env });
+                paneId = rootPaneOf(made);
+                createdPane = true;
+                workspaceCreated = true;
+                if (isObj(made?.workspace) && typeof made.workspace.workspace_id === 'string') {
+                    createdWorkspace = made.workspace.workspace_id;
+                }
+            }
         }
         else if ('workspace' in o.place) {
             paneId = rootPaneOf(await call('workspace.create', { cwd: o.cwd,
                 ...(o.place.label === undefined ? {} : { label: o.place.label }), focus: false, ...env }));
-            created = true;
+            createdPane = true;
+            workspaceCreated = true;
         }
         else if ('tab' in o.place) {
             paneId = rootPaneOf(await call('tab.create', { workspace_id: o.place.workspaceId, cwd: o.cwd,
                 ...(o.place.label === undefined ? {} : { label: o.place.label }), focus: false, ...env }));
-            created = true;
+            createdPane = true;
         }
         else if ('split' in o.place) {
             const made = await call('pane.split', { target_pane_id: o.place.split,
                 direction: o.place.direction, focus: false, ...env });
             paneId = typeof made?.pane?.pane_id === 'string' ? made.pane.pane_id : undefined;
-            created = true;
+            createdPane = true;
         }
         else {
             paneId = o.place.pane;
@@ -164,12 +217,7 @@ export function createAgents(ctx) {
                 await prepareLaunchEnv(call, paneId, launch, timeout);
             }
             catch (error) {
-                if (created) {
-                    try {
-                        await call('pane.close', { pane_id: paneId });
-                    }
-                    catch { /* best effort */ }
-                }
+                await rollback();
                 throw error;
             }
         }
@@ -181,19 +229,14 @@ export function createAgents(ctx) {
         for (;;) {
             try {
                 await call('agent.start', params, timeout + 5000);
-                return { paneId, name };
+                return { paneId, name, created: workspaceCreated };
             }
             catch (error) {
                 if (START_RETRYABLE.has(codeOf(error) ?? '') && Date.now() < deadline) {
                     await sleep(START_RETRY_DELAY_MS);
                     continue;
                 }
-                if (created) {
-                    try {
-                        await call('pane.close', { pane_id: paneId });
-                    }
-                    catch { /* rollback is best-effort */ }
-                }
+                await rollback();
                 if (launch)
                     throw fail('start_failed', words('agent.notReady'));
                 throw error;
@@ -205,10 +248,7 @@ export function createAgents(ctx) {
         // rides reads only, so a snapshot taken mid-launch goes stale. `interactive_ready` is not gated:
         // Herdr sets it only for agents its own `agent.start` settled, and its `agent.prompt` accepts the
         // rest. A refusal never sends `agent.prompt`.
-        const ready = () => {
-            const agent = agentOf(ctx.snapshot(), target.paneId);
-            return agent !== undefined && agent.launchPending !== true && PROMPTABLE.includes(agent.status);
-        };
+        const ready = () => isPromptable(agentOf(ctx.snapshot(), target.paneId));
         if (!ready()) {
             await ctx.reread(target.paneId);
             if (!ready())
@@ -249,6 +289,35 @@ export function createAgents(ctx) {
         return { paneId: a.pane_id, terminalId: a.terminal_id, revision: a.revision, status: a.agent_status,
             ...(agentSession === undefined ? {} : { agentSession }) };
     }
+    // Wait until a just-started agent can take a prompt, instead of the host polling `prompt` and
+    // catching `agent-not-ready`. Resolves on the kit's own snapshot once `isPromptable` holds; the
+    // snapshot is re-read each pass because `launch_pending` rides `agent.get` reads only. A pane that
+    // closed while waiting rejects `pane-unavailable` (confirmed by an `agent_not_found` read); the
+    // deadline rejects `agent-not-ready`. Either way the wait never hangs.
+    async function waitPromptable(target, o) {
+        const deadline = Date.now() + o.timeoutMs;
+        const agent = () => agentOf(ctx.snapshot(), target.paneId);
+        for (;;) {
+            if (isPromptable(agent()))
+                return;
+            if (agent() === undefined) {
+                try {
+                    await call('agent.get', { target: target.paneId });
+                }
+                catch (error) {
+                    if (codeOf(error) === 'agent_not_found')
+                        throw fail('pane-unavailable', 'That pane is no longer available.');
+                    throw error;
+                }
+            }
+            if (Date.now() >= deadline)
+                throw fail('agent-not-ready', 'That agent is not ready for a prompt yet.');
+            await ctx.reread(target.paneId);
+            if (isPromptable(agent()))
+                return;
+            await sleep(WAIT_PROMPTABLE_POLL_MS);
+        }
+    }
     async function wait(target, o) {
         const made = await call('agent.wait', { target: target.paneId,
             ...(o.until === undefined ? {} : { until: o.until }), timeout_ms: o.timeoutMs });
@@ -312,7 +381,7 @@ export function createAgents(ctx) {
                 ...(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 };
+    return { startAgent, prompt, waitPromptable, 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.
@@ -352,9 +421,8 @@ function readHead(file) {
             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.
+// A mise-style auto-install launcher is a shell script that goes through mise — the found
+// "binary" runs, but the first run installs the agent instead (see isMiseLauncher in muse.ts).
 export function isAutoInstallShim(file, readFile = readHead) {
     let head;
     try {
@@ -363,7 +431,7 @@ export function isAutoInstallShim(file, readFile = readHead) {
     catch {
         return false;
     }
-    return head !== undefined && head.startsWith('#!') && head.includes('mise');
+    return head !== undefined && isMiseLauncher(head);
 }
 // 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.
@@ -381,7 +449,7 @@ export function agentInstallState(kind, o) {
             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)))) {
+        if (head !== undefined && (isMiseLauncher(head) || (head.startsWith('#!') && head.includes('MUSE_CHANNEL') && !museNative(found.path)))) {
             return { kind, state: 'missing', path: found.path };
         }
         return { kind, state: 'installed', path: found.path };

package/dist/close.js

@@ -4,7 +4,7 @@ const codeOf = (error) => {
         return code;
     return /herdr: ([a-z0-9_]+):/i.exec(error instanceof Error ? error.message : String(error))?.[1];
 };
-const fail = (code, message) => Object.assign(new Error(message), { code });
+const fail = (code, message, wider) => Object.assign(new Error(message), { code }, wider ?? {});
 const unavailable = (kind) => fail(`${kind}-unavailable`, `That ${kind} is no longer available.`);
 const count = (value) => (typeof value === 'number' && Number.isFinite(value) ? value : 0);
 export async function closePane(call, paneId) {
@@ -21,17 +21,20 @@ export async function closePane(call, paneId) {
     if (typeof tabId !== 'string')
         throw unavailable('pane');
     let paneCount = 0;
+    let tabLabel;
     try {
         const made = (await call('tab.get', { tab_id: tabId }));
         paneCount = count(made?.tab?.pane_count);
+        tabLabel = typeof made?.tab?.label === 'string' ? made.tab.label : undefined;
     }
     catch (error) {
         if (codeOf(error) === 'tab_not_found')
             throw unavailable('pane');
         throw error;
     }
-    if (paneCount <= 1)
-        throw fail('pane-close-would-widen', 'Closing this pane would close its tab; close the tab instead.');
+    if (paneCount <= 1) {
+        throw fail('pane-close-would-widen', 'Closing this pane would close its tab; close the tab instead.', { scope: 'tab', id: tabId, label: tabLabel ?? '' });
+    }
     await call('pane.close', { pane_id: paneId });
 }
 export async function closeTab(call, tabId) {
@@ -48,24 +51,29 @@ export async function closeTab(call, tabId) {
     if (typeof workspaceId !== 'string')
         throw unavailable('tab');
     let tabCount = 0;
+    let workspaceLabel;
     try {
         const made = (await call('workspace.get', { workspace_id: workspaceId }));
         tabCount = count(made?.workspace?.tab_count);
+        workspaceLabel = typeof made?.workspace?.label === 'string' ? made.workspace.label : undefined;
     }
     catch (error) {
         if (codeOf(error) === 'workspace_not_found')
             throw unavailable('tab');
         throw error;
     }
-    if (tabCount <= 1)
-        throw fail('tab-close-would-widen', 'Closing this tab would close its workspace; close the workspace instead.');
+    if (tabCount <= 1) {
+        throw fail('tab-close-would-widen', 'Closing this tab would close its workspace; close the workspace instead.', { scope: 'workspace', id: workspaceId, label: workspaceLabel ?? '' });
+    }
     await call('tab.close', { tab_id: tabId });
 }
 export async function closeWorkspace(call, workspaceId) {
     let worktree;
+    let workspaceLabel;
     try {
         const made = (await call('workspace.get', { workspace_id: workspaceId }));
         worktree = made?.workspace?.worktree;
+        workspaceLabel = typeof made?.workspace?.label === 'string' ? made.workspace.label : undefined;
     }
     catch (error) {
         if (codeOf(error) === 'workspace_not_found')
@@ -78,7 +86,8 @@ export async function closeWorkspace(call, workspaceId) {
         const group = (Array.isArray(made?.workspaces) ? made.workspaces : [])
             .filter((w) => w?.worktree?.repo_key === worktree.repo_key).length;
         if (group >= 2) {
-            throw fail('workspace-close-would-widen', 'Closing this workspace would close its worktree group; close the linked checkouts instead.');
+            // The group is anchored at this root, so the wider target is named by that root workspace.
+            throw fail('workspace-close-would-widen', 'Closing this workspace would close its worktree group; close the linked checkouts instead.', { scope: 'workspace', id: workspaceId, label: workspaceLabel ?? '' });
         }
     }
     await call('workspace.close', { workspace_id: workspaceId });

package/dist/constants.js

@@ -1,7 +1,7 @@
 // The pinned Herdr release (docs/runtime-kits.md D5) and the protocol this kit speaks.
 export const HERDR_VERSION = '0.9.1';
 // From the v0.9.1 schema snapshot (schema/herdr-api-0.9.1.json, docs/runtime-kits.md 6.7);
-// regenerated by scripts/gen-types.ts and pinned by test/generated.test.ts.
+// regenerated by scripts/gen-types.ts.
 export const HERDR_PROTOCOL = 22;
 // Effective accepted server protocols for K11: each undeclared bound means exactly the pin.
 export function protocolBounds(range) {

package/dist/device.d.ts

@@ -1,4 +1,4 @@
-import type { DeviceLink } from '@byokit/link';
+import type { DeviceLink } from '@byokit/pair';
 import type { AgentRef, AgentStatus, BlockedAgent, HerdrEventName, HerdrEventOf, HerdrMethod, HerdrParams, HerdrResult, HerdrSnapshot, HerdrState, HerdrSubscription, PromptReceipt, StartAgent } from './types.ts';
 export type { HerdrEventName, HerdrEventOf, HerdrEvents, HerdrMethod, HerdrMethods, HerdrParams, HerdrResult, HerdrSubscription, } from './types.ts';
 /** One `hd.events` frame (7.2); `raw` carries a line that was not JSON. */
@@ -53,6 +53,24 @@ export declare function herdrDevice(link: DeviceLink): {
         tab?: string;
         workspace?: string;
     }): Promise<void>;
+    rename(o: {
+        pane?: string;
+        tab?: string;
+        workspace?: string;
+        label: string;
+    }): Promise<void>;
+    focus(o: {
+        pane?: string;
+        tab?: string;
+        workspace?: string;
+    }): Promise<void>;
+    layout(o: {
+        root: HerdrParams<'layout.apply'>['root'];
+        focus?: boolean;
+        tabId?: string;
+        tabLabel?: string;
+        workspaceId?: string;
+    }): Promise<HerdrResult<'layout.apply'>>;
     events(): AsyncIterable<HerdrLinkEvent>;
     subscribe<E extends HerdrEventName>(subs: HerdrSubscription<E>[], on: (e: HerdrEventOf<E>) => void, onError?: (message: string) => void): () => void;
     registerNotices(seed: Uint8Array): Promise<void>;