@byokit/herdr 0.7.3 → 0.8.1

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 ## Unreleased
 
+## 0.8.1 (2026-10-12)
+
+- Dependency update: pins @byokit/discover 0.8.1.
+- FIX: (from @byokit/discover 0.8.1) `browse()` and `scan()` accept resolved services whose `fullName` carries the service type without a trailing dot (`host._type._tcp`, as Android's react-native-zeroconf delivers) or with a trailing `.local` domain suffix, case-insensitive, instead of only the `host.local._type._tcp.` shape. Android phones now discover computers over mDNS instead of always scanning empty.
+
+## 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.

package/README.md

@@ -205,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
@@ -286,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';
@@ -456,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.js

@@ -9,7 +9,7 @@ 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;
@@ -62,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 {
@@ -130,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 }),
@@ -143,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;
@@ -171,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;
             }
         }
@@ -188,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;
@@ -385,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 {
@@ -396,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.
@@ -414,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

@@ -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>;

package/dist/device.js

@@ -219,6 +219,13 @@ export function herdrDevice(link) {
         close: async (o) => {
             await link.request('hd.close', o);
         },
+        rename: async (o) => {
+            await link.request('hd.rename', o);
+        },
+        focus: async (o) => {
+            await link.request('hd.focus', o);
+        },
+        layout: (o) => link.request('hd.layout', o),
         events: () => streamFrames(link, 'hd.events', {}),
         subscribe: (subs, on, onError) => subscription(link.stream('hd.subscribe', { subs }), on, onError),
         registerNotices: async (seed) => {

package/dist/kit.js

@@ -136,7 +136,8 @@ export class HerdrKit {
     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.accountPanes = createAccountPanes({ call: this.callAny, startAgent: (o) => this.startAgent(o),
+            agentStatus: (kinds, options) => this.agentStatus(kinds, options) });
         this.agents = createAgents({ call: this.callAny, snapshot: () => this.snapshot(),
             reread: (paneId) => this.reread(paneId),
             launchEnv: () => o.mode === 'own' ? this.supervisor.env() : undefined,

package/dist/link.js

@@ -15,6 +15,9 @@ const VIEW_OPS = new Set(['hd.state', 'hd.tree', 'hd.kinds', 'hd.read', 'hd.bloc
 const deny = () => {
     throw new PublicLinkError(words('link.notAllowed'));
 };
+// A refused widening close is the kit's plain sentence for the device, not a bare failure (6.4, 6.9).
+const WIDEN_CODES = new Set(['pane-close-would-widen', 'tab-close-would-widen', 'workspace-close-would-widen']);
+const widenError = (e) => WIDEN_CODES.has(e?.code ?? '') ? new PublicLinkError(words('close.wouldWiden')) : undefined;
 const findPane = (snap, paneId) => {
     for (const w of snap.workspaces) {
         for (const t of w.tabs) {
@@ -132,6 +135,14 @@ export function herdrLink(kit, o) {
                     if (!wid || !kit.snapshot().workspaces.some((w) => w.id === wid && inScope(scope, w.id)))
                         deny();
                 }
+                if (typeof place.workspace === 'string' && place.workspace !== 'new') {
+                    // A label placement lands its tab in the matching workspace: every match must already
+                    // be in scope, or the device would reach a workspace its grant never named. No match
+                    // creates, which stays creatable like a 'new' workspace.
+                    const label = place.workspace;
+                    if (kit.snapshot().workspaces.some((w) => w.label === label && !inScope(scope, w.id)))
+                        deny();
+                }
                 return kit.startAgent(args);
             }
             case 'hd.prompt': {
@@ -237,21 +248,144 @@ export function herdrLink(kit, o) {
                     const where = findPane(snap, paneId);
                     if (!where || !inScope(scope, where.workspaceId))
                         deny();
-                    await kit.closePane(paneId);
+                    try {
+                        await kit.closePane(paneId);
+                    }
+                    catch (e) {
+                        throw widenError(e) ?? e;
+                    }
                     return null;
                 }
                 if (tabId !== undefined) {
                     const owner = snap.workspaces.find((w) => w.tabs.some((t) => t.id === tabId));
                     if (!owner || !inScope(scope, owner.id))
                         deny();
-                    await kit.closeTab(tabId);
+                    try {
+                        await kit.closeTab(tabId);
+                    }
+                    catch (e) {
+                        throw widenError(e) ?? e;
+                    }
                     return null;
                 }
                 if (!snap.workspaces.some((w) => w.id === workspaceId && inScope(scope, w.id)))
                     deny();
-                await kit.closeWorkspace(workspaceId);
+                try {
+                    await kit.closeWorkspace(workspaceId);
+                }
+                catch (e) {
+                    throw widenError(e) ?? e;
+                }
                 return null;
             }
+            // The typed edit ops copy hd.close's shape (7.1): exactly one target, control only, and the
+            // target's owning workspace checked against scope before any Herdr call is made (a tab through
+            // its workspace, a workspace through itself). Out of scope — or unknown — is link.notAllowed.
+            case 'hd.rename': {
+                if (grant.role !== 'control')
+                    deny();
+                const snap = kit.snapshot();
+                const paneId = asString(args.pane);
+                const tabId = asString(args.tab);
+                const workspaceId = asString(args.workspace);
+                const label = asString(args.label);
+                const picked = [paneId, tabId, workspaceId].filter((v) => v !== undefined);
+                if (picked.length !== 1)
+                    throw new Error('herdr: hd.rename picks exactly one of pane, tab or workspace');
+                if (label === undefined || label.length === 0)
+                    throw new Error('herdr: hd.rename needs a label');
+                if (paneId !== undefined) {
+                    const where = findPane(snap, paneId);
+                    if (!where || !inScope(scope, where.workspaceId))
+                        deny();
+                    await kit.call('pane.rename', { pane_id: paneId, label });
+                    return null;
+                }
+                if (tabId !== undefined) {
+                    const owner = snap.workspaces.find((w) => w.tabs.some((t) => t.id === tabId));
+                    if (!owner || !inScope(scope, owner.id))
+                        deny();
+                    await kit.call('tab.rename', { tab_id: tabId, label });
+                    return null;
+                }
+                if (!snap.workspaces.some((w) => w.id === workspaceId && inScope(scope, w.id)))
+                    deny();
+                await kit.call('workspace.rename', { workspace_id: workspaceId, label });
+                return null;
+            }
+            case 'hd.focus': {
+                if (grant.role !== 'control')
+                    deny();
+                const snap = kit.snapshot();
+                const paneId = asString(args.pane);
+                const tabId = asString(args.tab);
+                const workspaceId = asString(args.workspace);
+                const picked = [paneId, tabId, workspaceId].filter((v) => v !== undefined);
+                if (picked.length !== 1)
+                    throw new Error('herdr: hd.focus picks exactly one of pane, tab or workspace');
+                if (paneId !== undefined) {
+                    const where = findPane(snap, paneId);
+                    if (!where || !inScope(scope, where.workspaceId))
+                        deny();
+                    await kit.call('pane.focus', { pane_id: paneId });
+                    return null;
+                }
+                if (tabId !== undefined) {
+                    const owner = snap.workspaces.find((w) => w.tabs.some((t) => t.id === tabId));
+                    if (!owner || !inScope(scope, owner.id))
+                        deny();
+                    await kit.call('tab.focus', { tab_id: tabId });
+                    return null;
+                }
+                if (!snap.workspaces.some((w) => w.id === workspaceId && inScope(scope, w.id)))
+                    deny();
+                await kit.call('workspace.focus', { workspace_id: workspaceId });
+                return null;
+            }
+            case 'hd.layout': {
+                if (grant.role !== 'control')
+                    deny();
+                const root = args.root;
+                if (typeof root !== 'object' || root === null || Array.isArray(root)) {
+                    throw new Error('herdr: hd.layout needs a root');
+                }
+                const snap = kit.snapshot();
+                const tabId = asString(args.tabId);
+                const workspaceId = asString(args.workspaceId);
+                // The layout picks exactly one tab or workspace, in scope, before any call.
+                if ([tabId, workspaceId].filter((v) => v !== undefined).length !== 1) {
+                    throw new Error('herdr: hd.layout picks exactly one of tabId or workspaceId');
+                }
+                if (tabId !== undefined) {
+                    const owner = snap.workspaces.find((w) => w.tabs.some((t) => t.id === tabId));
+                    if (!owner || !inScope(scope, owner.id))
+                        deny();
+                }
+                else if (!snap.workspaces.some((w) => w.id === workspaceId && inScope(scope, w.id)))
+                    deny();
+                // Every named pane leaf must be known and in scope before any call; an unnamed leaf is a new pane.
+                const pending = [root];
+                while (pending.length > 0) {
+                    const node = asRecord(pending.pop());
+                    if (typeof node.pane_id === 'string') {
+                        const where = findPane(snap, node.pane_id);
+                        if (!where || !inScope(scope, where.workspaceId))
+                            deny();
+                    }
+                    if (node.first !== undefined)
+                        pending.push(node.first);
+                    if (node.second !== undefined)
+                        pending.push(node.second);
+                }
+                const tabLabel = asString(args.tabLabel);
+                return kit.call('layout.apply', {
+                    root: root,
+                    ...(args.focus === true ? { focus: true } : {}),
+                    ...(tabId !== undefined ? { tab_id: tabId } : {}),
+                    ...(workspaceId !== undefined ? { workspace_id: workspaceId } : {}),
+                    ...(tabLabel !== undefined ? { tab_label: tabLabel } : {}),
+                });
+            }
             case 'hd.notices.register': {
                 if (grant.role !== 'control')
                     deny();

package/dist/muse.d.ts

@@ -4,6 +4,8 @@ export declare function museNative(launcher: string): {
     native: string;
     version: string;
 } | undefined;
+/** A mise-style auto-install launcher is a shell script that goes through mise. Shared with agents.ts. */
+export declare function isMiseLauncher(head: string): boolean;
 export type MuseReadiness = {
     state: 'unknown' | 'missing' | 'launcher-only' | 'installed';
     signedIn: 'unknown';

package/dist/muse.js

@@ -56,6 +56,12 @@ export function museNative(launcher) {
         return;
     }
 }
+/** A mise-style auto-install launcher is a shell script that goes through mise. Shared with agents.ts. */
+export function isMiseLauncher(head) {
+    const shebang = head.split('\n', 1)[0] ?? '';
+    return /^#!\s*(?:\S*\/)?(?:env\s+)?(?:sh|bash|zsh|dash|ksh|ash)(?:\s|$)/.test(shebang)
+        && head.includes('mise');
+}
 /** Only the supplied effective pane PATH is probed, never the controller's personal directories. */
 export function museReadiness(env) {
     if (env?.PATH === undefined)
@@ -70,7 +76,7 @@ export function museReadiness(env) {
             accessSync(bin, constants.X_OK);
             const selected = museNative(bin);
             const head = launcherHead(bin);
-            const launcherOnly = head.startsWith('#!') && (head.includes('mise') || (!selected && head.includes('MUSE_CHANNEL')));
+            const launcherOnly = isMiseLauncher(head) || (!selected && head.includes('MUSE_CHANNEL'));
             return { state: launcherOnly ? 'launcher-only' : 'installed', signedIn: 'unknown', bin,
                 ...(selected ? { version: selected.version } : {}) };
         }

package/dist/notices.js

@@ -1,6 +1,8 @@
 // Sealed blocked-approval notices: the relay reads only a generic title, the phone opens the sealed body with its
-// own key (docs/runtime-kits.md 7.3). Portable: no Node import anywhere in it — `./device` re-exports `openNotice`.
-import { boxKeyPairFromSeed, openBoxFromSeed, sealBox } from '@byokit/seal';
+// own key (docs/runtime-kits.md 7.3). The envelope comes from `@byokit/seal`'s generic notice API, so one opener
+// serves every kit; this file keeps the blocked-agent shape check and the box-key text. Portable: no Node import
+// anywhere in it — `./device` re-exports `openNotice`.
+import { boxKeyPairFromSeed, openNotice as sealOpenNotice, sealNotice as sealSealNotice } from '@byokit/seal';
 const ABC = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
 /** Base64url without padding, hand-rolled so this file stays portable (no Buffer, no atob). */
 export function encodeB64Url(bytes) {
@@ -57,28 +59,20 @@ export function sealNotice(b, boxPublicKey) {
     }
     if (!isBlockedAgent(b))
         throw new Error('herdr: cannot seal that notice');
-    return { v: 1, sealed: encodeB64Url(sealBox(new TextEncoder().encode(JSON.stringify(b)), boxPublicKey)) };
+    return sealSealNotice(b, boxPublicKey);
 }
 /** Open a notice envelope with the device's 32-byte seed; null when it is not ours or not a notice. */
 export function openNotice(data, seed) {
-    if (typeof data !== 'object' || data === null || data.v !== 1 || typeof data.sealed !== 'string')
-        return null;
     if (!(seed instanceof Uint8Array) || seed.length !== 32)
         return null;
-    const bundle = decodeB64Url(data.sealed);
-    if (bundle === null)
-        return null;
-    const bytes = openBoxFromSeed(bundle, seed);
-    if (bytes === null)
-        return null;
-    let parsed;
+    const { secretKey } = boxKeyPairFromSeed(seed);
     try {
-        parsed = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+        const parsed = sealOpenNotice(data, secretKey);
+        return isBlockedAgent(parsed) ? parsed : null;
     }
-    catch {
-        return null;
+    finally {
+        secretKey.fill(0);
     }
-    return isBlockedAgent(parsed) ? parsed : null;
 }
 /** The box public key a device registers for a seed (the host seals to this). */
 export function boxPublicKeyB64(seed) {

package/dist/testing/contract.js

@@ -53,6 +53,15 @@ export function herdrContract(make, options) {
         }
         return { status, panes };
     }
+    function ownerOf(snapshot, paneId) {
+        for (const workspace of snapshot.workspaces) {
+            for (const tab of workspace.tabs) {
+                if (tab.panes.some((pane) => pane.id === paneId))
+                    return { workspace, tab };
+            }
+        }
+        return undefined;
+    }
     test('contract: start reaches ready and ping speaks the pinned protocol', async () => {
         await bench(async ({ kit }) => {
             await kit.start();
@@ -279,10 +288,93 @@ export function herdrContract(make, options) {
             }
             assert.equal(pane.paneId, 'w1:p1', 'the pane placement uses the pane as given');
             assert.equal(typeof ws.name, 'string');
+            // `created` tells a workspace-making placement from one landing in an existing workspace.
+            assert.equal(ws.created, true, 'a new workspace reports created');
+            assert.equal(tree.created, true, 'a worktree checkout reports created');
+            assert.equal(tab.created, false, 'a new tab reports reuse');
+            assert.equal(split.created, false, 'a split reports reuse');
+            assert.equal(pane.created, false, 'a caller-owned pane reports reuse');
             const workspaces = (await kit.call('workspace.list', {}));
             assert.ok(workspaces.workspaces?.some((workspace) => workspace.worktree?.is_linked_worktree === true), 'the worktree placement registers a linked checkout');
         });
     });
+    test('contract: startAgent with a workspace label reuses the matching workspace', async () => {
+        await bench(async ({ kit }) => {
+            await kit.start();
+            const before = kit.snapshot().workspaces.length;
+            const made = (await kit.call('workspace.create', { cwd: '/tmp/h6-label', label: 'byokit-reuse' }));
+            const wid = made.workspace?.workspace_id;
+            assert.equal(typeof wid, 'string');
+            await until(() => kit.snapshot().workspaces.find((w) => w.id === wid), (w) => w !== undefined);
+            const first = await kit.startAgent({ kind: 'pi', cwd: '/tmp/h6', place: { workspace: 'byokit-reuse', label: 'agent-tab' } });
+            assert.equal(first.created, false, 'landing in an existing workspace reports reuse');
+            assert.match(first.paneId, /^w\d+:p\d+$/);
+            const tree = await until(() => {
+                const snap = kit.snapshot();
+                const owner = ownerOf(snap, first.paneId);
+                return owner !== undefined && snap.workspaces.length === before + 1 ? { snap, owner } : undefined;
+            }, () => true);
+            assert.equal(tree.owner.workspace.id, wid, 'the agent lands in the workspace with that label');
+            assert.equal(tree.owner.tab.label, 'agent-tab', 'the tab label rides the reuse');
+            const second = await kit.startAgent({ kind: 'pi', cwd: '/tmp/h6', place: { workspace: 'byokit-reuse' } });
+            assert.equal(second.created, false);
+            assert.notEqual(second.paneId, first.paneId, 'the second start gets its own tab pane');
+            const again = await until(() => {
+                const snap = kit.snapshot();
+                return ownerOf(snap, second.paneId) !== undefined && snap.workspaces.length === before + 1 ? snap : undefined;
+            }, () => true);
+            assert.equal(again.workspaces.length, before + 1, 'reuse adds a tab, never a workspace');
+        });
+    });
+    test('contract: startAgent with an unknown workspace label creates it', async () => {
+        await bench(async ({ kit }) => {
+            await kit.start();
+            const before = kit.snapshot().workspaces.length;
+            const ref = await kit.startAgent({ kind: 'pi', cwd: '/tmp/h6', place: { workspace: 'byokit-fresh' } });
+            assert.equal(ref.created, true, 'no match creates the workspace');
+            assert.match(ref.paneId, /^w\d+:p\d+$/);
+            const snap = await until(() => {
+                const s = kit.snapshot();
+                const owner = ownerOf(s, ref.paneId);
+                return owner !== undefined && owner.workspace.label === 'byokit-fresh' && s.workspaces.length === before + 1
+                    ? s : undefined;
+            }, () => true);
+            assert.equal(snap.workspaces.length, before + 1);
+        });
+    });
+    test('contract: a failed start into a reused workspace keeps the workspace', async () => {
+        await bench(async ({ kit, fake }) => {
+            if (!fake)
+                return;
+            await kit.start();
+            const made = (await kit.call('workspace.create', { cwd: '/tmp/h6-label', label: 'byokit-keep' }));
+            const wid = made.workspace?.workspace_id;
+            assert.equal(typeof wid, 'string');
+            await until(() => kit.snapshot().workspaces.find((w) => w.id === wid), (w) => w !== undefined);
+            const panesBefore = agentStatusOf(kit.snapshot(), 'none').panes;
+            fake.agentStartFaults.push({ code: 'agent_failed', message: 'boom' });
+            await assert.rejects(kit.startAgent({ kind: 'pi', cwd: '/tmp/h6', place: { workspace: 'byokit-keep' } }), /boom/);
+            await until(() => agentStatusOf(kit.snapshot(), 'none').panes, (n) => n === panesBefore);
+            assert.ok(kit.snapshot().workspaces.some((w) => w.id === wid && w.label === 'byokit-keep'), 'the reused workspace is never closed by a failed start');
+        });
+    });
+    test('contract: two workspaces with one label refuse as ambiguous and pick nothing', async () => {
+        await bench(async ({ kit }) => {
+            await kit.start();
+            await kit.call('workspace.create', { cwd: '/tmp/h6-label', label: 'byokit-dup' });
+            await kit.call('workspace.create', { cwd: '/tmp/h6-label', label: 'byokit-dup' });
+            const settled = await until(() => {
+                const snap = kit.snapshot();
+                return snap.workspaces.filter((w) => w.label === 'byokit-dup').length === 2 ? snap : undefined;
+            }, () => true);
+            const workspacesBefore = settled.workspaces.length;
+            const panesBefore = agentStatusOf(settled, 'none').panes;
+            await assert.rejects(kit.startAgent({ kind: 'pi', cwd: '/tmp/h6', place: { workspace: 'byokit-dup' } }), (e) => e.code === 'workspace-ambiguous', 'two matching labels refuse with the named ambiguous error');
+            assert.equal(kit.snapshot().workspaces.filter((w) => w.label === 'byokit-dup').length, 2);
+            assert.equal(kit.snapshot().workspaces.length, workspacesBefore, 'the refusal creates no workspace');
+            assert.equal(agentStatusOf(kit.snapshot(), 'none').panes, panesBefore, 'the refusal creates no pane');
+        });
+    });
     test('contract: a started agent joins snapshot() and its status stays current there', async () => {
         await bench(async ({ kit }) => {
             await kit.start();
@@ -374,14 +466,26 @@ export function herdrContract(make, options) {
         await bench(async ({ kit }) => {
             await kit.start();
             // A fresh workspace holds exactly one tab with exactly one pane: the widening cases.
-            const made = (await kit.call('workspace.create', { cwd: '/tmp/h6-other' }));
+            const made = (await kit.call('workspace.create', { cwd: '/tmp/h6-other', label: 'other' }));
             const w2 = made.workspace?.workspace_id;
             assert.equal(typeof w2, 'string');
-            await assert.rejects(kit.closePane(`${w2}:p1`), (e) => e.code === 'pane-close-would-widen', 'closing the last pane would close the tab');
-            await assert.rejects(kit.closeTab(`${w2}:t1`), (e) => e.code === 'tab-close-would-widen', 'closing the only tab would close the workspace');
+            // A refusal carries the wider target (scope, id, label) the app would close instead (6.4).
+            const widen = async (work) => {
+                try {
+                    await work;
+                }
+                catch (e) {
+                    const { scope, id, label, code } = e;
+                    return { scope, id, label, code };
+                }
+                assert.fail('expected a would-widen refusal');
+            };
+            assert.deepEqual(await widen(kit.closePane(`${w2}:p1`)), { scope: 'tab', id: `${w2}:t1`, label: 'main', code: 'pane-close-would-widen' }, 'closing the last pane widens to its tab');
+            assert.deepEqual(await widen(kit.closeTab(`${w2}:t1`)), { scope: 'workspace', id: w2, label: 'other', code: 'tab-close-would-widen' }, 'closing the only tab widens to its workspace');
             // worktree.create links a checkout into w1's group: the root now widens on close.
+            const w1Label = kit.snapshot().workspaces.find((w) => w.id === 'w1')?.label;
             await kit.startAgent({ kind: 'pi', cwd: '/tmp/h6', place: { workspace: 'new' }, worktree: { branch: 'h6' } });
-            await assert.rejects(kit.closeWorkspace('w1'), (e) => e.code === 'workspace-close-would-widen', 'closing a worktree group parent would close the group');
+            assert.deepEqual(await widen(kit.closeWorkspace('w1')), { scope: 'workspace', id: 'w1', label: w1Label, code: 'workspace-close-would-widen' }, 'closing a worktree group parent widens to the group, named by its root');
             // The exact closes still go through.
             await kit.call('pane.split', { target_pane_id: `${w2}:p1`, direction: 'right' });
             await kit.closePane(`${w2}:p1`);

package/dist/testing/fake-herdr/server.js

@@ -8,7 +8,7 @@ import { createServer } from 'node:net';
 import { join } from 'node:path';
 import { HERDR_PROTOCOL, HERDR_VERSION } from "../../constants.js";
 import { writeBinShim } from "./bin.js";
-import { agentRecord, createWorld, paneScroll, relayoutTab } from "./world.js";
+import { COLS, ROWS, agentRecord, createWorld, paneScroll, relayoutTab } from "./world.js";
 const PROMPT_SETTLE_MS = 50; // 6.8: the agent settles 50 ms after a prompt
 const WAIT_POLL_MS = 5;
 // The subscription kinds that need a `pane_id` filter and ride their own socket each
@@ -18,6 +18,27 @@ const WAIT_POLL_MS = 5;
 // batch with another kind.
 const FILTERED = new Set(['pane_agent_status_changed', 'pane_output_matched', 'pane_scroll_changed']);
 const AGENT_NAME = /^[a-z][a-z0-9_-]{0,31}$/;
+// Position every pane leaf of a layout tree inside the tab's area: a split divides its rect at its
+// ratio, a pane leaf lands where the recursion left it. Leaves in tree order, so `focus` can pick
+// the first one.
+function layoutLeaves(node, rect, out) {
+    if (node.type === 'split' && node.first !== undefined && node.second !== undefined) {
+        const ratio = typeof node.ratio === 'number' ? Math.min(1, Math.max(0, node.ratio)) : 0.5;
+        if (node.direction === 'down') {
+            const top = Math.max(1, Math.round(rect.height * ratio));
+            layoutLeaves(node.first, { x: rect.x, y: rect.y, width: rect.width, height: top }, out);
+            layoutLeaves(node.second, { x: rect.x, y: rect.y + top, width: rect.width, height: Math.max(1, rect.height - top) }, out);
+        }
+        else {
+            const left = Math.max(1, Math.round(rect.width * ratio));
+            layoutLeaves(node.first, { x: rect.x, y: rect.y, width: left, height: rect.height }, out);
+            layoutLeaves(node.second, { x: rect.x + left, y: rect.y, width: Math.max(1, rect.width - left), height: rect.height }, out);
+        }
+        return;
+    }
+    if (typeof node.pane_id === 'string')
+        out.push({ paneId: node.pane_id, rect });
+}
 export async function startFakeHerdr(options) {
     const dir = options.dir;
     if (typeof dir !== 'string' || dir.length === 0)
@@ -335,6 +356,45 @@ export async function startFakeHerdr(options) {
             return { zoom: { changed, zoomed: live.zoomed } };
         },
         'pane.layout': (p) => ({ layout: tabLayout(paneOf(p.pane_id).tab_id) }),
+        'layout.apply': (p) => {
+            const root = p.root;
+            if (typeof root !== 'object' || root === null || Array.isArray(root)) {
+                throw fail('invalid_layout', 'a root layout is required');
+            }
+            // The target tab: an explicit tab_id, else the workspace's first tab (the pinned server needs one).
+            let tab;
+            if (typeof p.tab_id === 'string') {
+                tab = live.tabs.find((row) => row.tab_id === p.tab_id);
+                if (tab === undefined)
+                    throw fail('tab_not_found', 'tab not found');
+            }
+            else if (typeof p.workspace_id === 'string') {
+                if (!live.workspaces.some((row) => row.workspace_id === p.workspace_id)) {
+                    throw fail('workspace_not_found', 'workspace not found');
+                }
+                tab = live.tabs.find((row) => row.workspace_id === p.workspace_id);
+                if (tab === undefined)
+                    throw fail('tab_not_found', 'tab not found');
+            }
+            else {
+                throw fail('invalid_target', 'layout.apply needs a tab_id or workspace_id');
+            }
+            // Every leaf must be a pane of the target tab; the layout repositions exactly those panes.
+            const leaves = [];
+            layoutLeaves(root, { x: 0, y: 0, width: COLS, height: ROWS }, leaves);
+            for (const leaf of leaves) {
+                const pane = live.panes.find((row) => row.pane_id === leaf.paneId);
+                if (pane === undefined || pane.tab_id !== tab.tab_id) {
+                    throw fail('pane_not_found', `pane not found in tab: ${leaf.paneId}`);
+                }
+                pane.rect = leaf.rect;
+            }
+            if (p.focus === true && leaves[0] !== undefined)
+                focusPane(leaves[0].paneId);
+            const layout = tabLayout(tab.tab_id);
+            emitEvent('layout.updated', { layout });
+            return { type: 'layout_apply', layout: { ...layout, root } };
+        },
         'agent.start': (p) => {
             const fault = agentStartFaults.shift();
             if (fault !== undefined)

package/dist/turn-files.d.ts

@@ -1,4 +1,4 @@
 import type { AgentTurnEnd, AgentTurnFiles } from './types.ts';
 export declare function positiveLimit(value: number | undefined, fallback: number): number;
-export declare function scanFiles(root: string, policy: AgentTurnFiles | undefined, resultName: string, active: () => void): Promise<Map<string, string>>;
+export declare function scanFiles(root: string, policy: AgentTurnFiles | false | undefined, resultName: string, active: () => void): Promise<Map<string, string>>;
 export declare function changedFiles(before: Map<string, string>, after: Map<string, string>): AgentTurnEnd['changedFiles'];

package/dist/turn-files.js

@@ -11,8 +11,13 @@ export function positiveLimit(value, fallback) {
 // A baseline of the actual tree, independent of Git status and mtime granularity. Never traverse
 // symlinks or read special files; a changing/unreadable tree fails rather than claiming a full diff.
 export async function scanFiles(root, policy, resultName, active) {
+    // files:false skips the scan entirely: no walk, so a large tree (e.g. node_modules) cannot fail the turn.
+    if (policy === false)
+        return new Map();
     const maxFiles = positiveLimit(policy?.maxFiles, 10000);
     const maxBytes = positiveLimit(policy?.maxBytes, 128 * 1024 * 1024);
+    // Read once: narrowing on the parameter does not persist into the walk closure below.
+    const exclude = policy?.exclude;
     let entries = 0;
     let bytes = 0;
     const found = new Map();
@@ -27,7 +32,7 @@ export async function scanFiles(root, policy, resultName, active) {
             active();
             const path = join(dir, name);
             const rel = relative(root, path).split(sep).join('/');
-            if (name === '.git' || rel === resultName || policy?.exclude?.(rel))
+            if (name === '.git' || rel === resultName || exclude?.(rel))
                 continue;
             if (++entries > maxFiles)
                 throw new Error('turn: file limit');

package/dist/turns.js

@@ -73,9 +73,11 @@ export function createTurns(kit) {
         if (!isAbsolute(o.cwd))
             throw fail('turn-cwd');
         const timeoutMs = positiveLimit(o.timeoutMs, 300000);
-        // Fail invalid configuration before delivering a prompt.
-        positiveLimit(o.files?.maxFiles, 10000);
-        positiveLimit(o.files?.maxBytes, 128 * 1024 * 1024);
+        // Fail invalid configuration before delivering a prompt (no scan means no file limits to check).
+        if (o.files !== false) {
+            positiveLimit(o.files?.maxFiles, 10000);
+            positiveLimit(o.files?.maxBytes, 128 * 1024 * 1024);
+        }
         if (o.result)
             positiveLimit(o.result.maxBytes, 1024 * 1024);
         const schema = o.result ? JSON.stringify(o.result.schema) : undefined;
@@ -125,7 +127,7 @@ export function createTurns(kit) {
             const endSignal = new Promise((resolve) => { resolveEnd = resolve; });
             const watch = kit.subscribe([{ type: 'pane.agent_status_changed', pane_id: target.paneId }], (e) => {
                 if (!armed) {
-                    if (e.agent_status !== 'idle')
+                    if (e.agent_status !== 'idle' && e.agent_status !== 'done')
                         abort('turn-busy');
                     return;
                 }
@@ -153,7 +155,7 @@ export function createTurns(kit) {
                 throw fail('turn-watch-lost');
             const beforeAgent = await gate(kit.call('agent.get', { target: target.paneId }));
             const agent = beforeAgent.agent;
-            if (agent.agent_status !== 'idle' || agent.launch_pending === true)
+            if ((agent.agent_status !== 'idle' && agent.agent_status !== 'done') || agent.launch_pending === true)
                 throw fail('turn-not-idle');
             if (target.name && agent.name !== target.name)
                 throw fail('turn-unavailable');

package/dist/types.d.ts

@@ -98,6 +98,7 @@ export type AgentStartEvent = {
 export type AgentRef = {
     paneId: string;
     name?: string;
+    created?: boolean;
 };
 export type StartAgent = {
     kind: string;
@@ -106,6 +107,9 @@ export type StartAgent = {
     place: {
         workspace: 'new';
         label?: string;
+    } | {
+        workspace: string;
+        label?: string;
     } | {
         tab: 'new';
         workspaceId: string;
@@ -155,6 +159,7 @@ export type MoveToAccount = {
     provider: string;
     folder: string;
     env?: Record<string, string>;
+    name?: string;
     direction?: 'right' | 'down';
     timeoutMs?: number;
     whenBusy?: BusyHandoff;
@@ -164,7 +169,7 @@ export type MoveToAccountResult = {
     session: string;
 } | {
     ok: false;
-    code: 'too_early' | 'busy' | 'unsupported' | 'env_mismatch' | 'close_failed' | 'start_failed' | 'blocked' | 'changed' | 'interrupt_unsupported';
+    code: 'too_early' | 'busy' | 'unsupported' | 'env_mismatch' | 'close_failed' | 'start_failed' | 'blocked' | 'changed' | 'interrupt_unsupported' | 'signed_out';
     message: string;
     live?: string;
 };
@@ -209,7 +214,8 @@ export type AgentTurnOptions<T = unknown> = {
     cwd: string;
     timeoutMs?: number;
     signal?: AbortSignal;
-    files?: AgentTurnFiles;
+    /** Pass false to skip the file scan entirely (changedFiles is then always empty). */
+    files?: AgentTurnFiles | false;
     result?: AgentTurnResultPolicy<T>;
     onEnd?: (end: AgentTurnEnd<T>) => void;
 };

package/dist/words.json

@@ -20,6 +20,7 @@
     "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.",
+    "move.signed_out": "Sign in to {name} first.",
     "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.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/herdr",
-  "version": "0.7.3",
+  "version": "0.8.1",
   "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/pair.",
   "license": "Apache-2.0",
   "type": "module",
@@ -52,9 +52,9 @@
     "prepack": "tsc -b && node ../../scripts/fix-words-dts.cjs"
   },
   "dependencies": {
-    "@byokit/pair": "0.9.0",
-    "@byokit/relay": "0.6.0",
-    "@byokit/discover": "0.7.0",
+    "@byokit/pair": "0.10.0",
+    "@byokit/relay": "0.6.1",
+    "@byokit/discover": "0.8.1",
     "@byokit/seal": "0.3.0",
     "ws": "8.22.0"
   },