@byokit/herdr 0.7.2 → 0.8.0

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/index.d.ts

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

package/dist/index.js

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

package/dist/kit.d.ts

@@ -81,6 +81,9 @@ export declare class HerdrKit {
             timeoutMs: number;
         };
     }): Promise<PromptReceipt>;
+    waitPromptable(target: AgentRef, o: {
+        timeoutMs: number;
+    }): Promise<void>;
     runTurn<T = unknown>(target: AgentRef, o: AgentTurnOptions<T>): Promise<AgentTurnEnd<T>>;
     onTurnEnd(fn: (end: AgentTurnEnd) => void): () => void;
     sendKeys(target: AgentRef, keys: string[]): Promise<void>;

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,
@@ -462,6 +463,7 @@ export class HerdrKit {
         return () => { this.startListeners.delete(fn); };
     }
     prompt(target, text, o) { return this.agents.prompt(target, text, o); }
+    waitPromptable(target, o) { return this.agents.waitPromptable(target, o); }
     runTurn(target, o) { return this.turns.runTurn(target, o); }
     onTurnEnd(fn) { return this.turns.onTurnEnd(fn); }
     sendKeys(target, keys) { return this.agents.sendKeys(target, keys); }

package/dist/link.d.ts

@@ -1,5 +1,5 @@
 import { type IncomingMessage, type ServerResponse } from 'node:http';
-import { type Grant, type Host, type HostOptions } from '@byokit/link';
+import { type Grant, type Host, type HostOptions } from '@byokit/pair';
 import { type ServeIngress, type Via } from '@byokit/discover';
 import type { RelayClient } from '@byokit/relay';
 import type { HerdrKit } from './kit.ts';

package/dist/link.js

@@ -1,4 +1,4 @@
-// Host-side link adapter: the hd.* ops over @byokit/link, and the serve() wiring (duplicated per kit by design,
+// Host-side link adapter: the hd.* ops over @byokit/pair, and the serve() wiring (duplicated per kit by design,
 // D3) — built in H7 (docs/runtime-kits.md 7.1-7.3).
 //
 // Permission shape: `allow` lets every request through and `handle`/`stream` refuse with the `link.notAllowed`
@@ -6,7 +6,7 @@
 // generic `view-only`/`not-allowed` words instead).
 import { createServer } from 'node:http';
 import { WebSocketServer } from 'ws';
-import { PublicLinkError, } from '@byokit/link';
+import { PublicLinkError, } from '@byokit/pair';
 import { reach } from '@byokit/discover';
 import { stateWords, words } from "./words.js";
 import { decodeB64Url, sealNotice } from "./notices.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`);
@@ -390,6 +494,36 @@ export function herdrContract(make, options) {
             await kit.closeWorkspace(w2);
         });
     });
+    test('contract: waitPromptable waits through a launch-pending agent and resolves', async () => {
+        await bench(async ({ kit, fake }) => {
+            if (!fake)
+                return;
+            const paneId = 'w1:p2';
+            const agent = fake.world.agents.find((row) => row.pane_id === paneId);
+            assert.ok(agent, 'the fake seeds w1:p2');
+            agent.launch_pending = true;
+            await kit.start();
+            // A still-pending launch is not promptable: the deadline rejects agent-not-ready.
+            await assert.rejects(kit.waitPromptable({ paneId }, { timeoutMs: 120 }), (e) => e.code === 'agent-not-ready', 'a launch that stays pending rejects with agent-not-ready');
+            // Flip the fake ready: the next read clears launch_pending and the wait resolves.
+            const waiting = kit.waitPromptable({ paneId }, { timeoutMs: 2000 });
+            agent.launch_pending = false;
+            await waiting;
+            assert.equal(agentStatusOf(kit.snapshot(), paneId).status, 'idle');
+        });
+    });
+    test('contract: waitPromptable rejects pane-unavailable when the pane closes mid-wait', async () => {
+        await bench(async ({ kit, fake }) => {
+            if (!fake)
+                return;
+            const paneId = 'w1:p2';
+            fake.world.agents.find((row) => row.pane_id === paneId).launch_pending = true;
+            await kit.start();
+            const waiting = kit.waitPromptable({ paneId }, { timeoutMs: 2000 });
+            await kit.closePane(paneId);
+            await assert.rejects(waiting, (e) => e.code === 'pane-unavailable', 'a pane closed while waiting rejects pane-unavailable instead of hanging');
+        });
+    });
     test('contract: the cli answers --version and the terminal echoes', async () => {
         await bench(async ({ kit }) => {
             await kit.start();

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');