@byokit/herdr 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+## 0.4.0 (2026-10-01)
+
+- Dependency update: pins @byokit/reach 0.6.0.
+
+- Add `move` with caller resume args, credential shedding, staging/replacement hooks and `MoveResult.paneId`.
+- Add per-call `cli` env overlays for managed folder hook installation.
+- Report surviving replacement panes when environment verification rollback fails; refuse folder moves for agents that ignore the folder variables.
+
 ## 0.3.0 (2026-10-01)
 
 - Dependency update: pins @byokit/reach 0.5.0.
@@ -24,6 +32,7 @@
   launcher such as a mise shim: shimmed or absent reads `installs-on-first-start`, sharing the
   one probe path with `installedAgentKinds` (`resolveAgentBinary`, `isAutoInstallShim`).
 
+
 ## 0.2.0 (2026-09-30)
 
 - `HerdrKit.agentStatus(kinds)` (B5): per-kind onboarding readiness — installed plus CLI

package/README.md

@@ -149,7 +149,7 @@ persistent grant store, and the phone page above.
 
 | Export | What it does |
 |---|---|
-| `HerdrKit` (`@byokit/herdr`) | The host-side kit, in `adopt` or `own` mode: `start`/`stop`, `state`, `snapshot`/`onChange`, `startAgent`, `openSignInTab`, `moveToAccount`, `onStartAgent`, `prompt`, `sendKeys`, `wait`, `read`, `blocked`/`onBlocked`/`answer`, `closePane`/`closeTab`/`closeWorkspace`, `agentKinds`, `installedAgentKinds`, `agentStatus`, `agentInstallState`, `terminal`, `onEvent`, `statusWatchReady`, and the pass-throughs `call`, `subscribe` and `cli` |
+| `HerdrKit` (`@byokit/herdr`) | The host-side kit, in `adopt` or `own` mode: `start`/`stop`, `state`, `snapshot`/`onChange`, `startAgent`, `openSignInTab`, `move`, `moveToAccount`, `onStartAgent`, `prompt`, `sendKeys`, `wait`, `read`, `blocked`/`onBlocked`/`answer`, `closePane`/`closeTab`/`closeWorkspace`, `agentKinds`, `installedAgentKinds`, `agentStatus`, `agentInstallState`, `terminal`, `onEvent`, `statusWatchReady`, and the pass-throughs `call`, `subscribe` and `cli` |
 | `agentStatus`, `agentInstallState`, `agentProbePath`, `extraPathDirs`, `runStatusCommand`, `isAutoInstallShim`, `resolveAgentBinary` (`@byokit/herdr`) | Onboarding readiness: per-kind install + CLI sign-in without a Herdr connection (see below) |
 | `HERDR_VERSION`, `HERDR_PROTOCOL` | The pinned Herdr release (`0.9.1`) and the protocol the kit speaks (`22`) |
 | `words`, `agentWords`, `stateWords`, `WORDS` | Plain sentences for agent statuses and kit states |
@@ -176,9 +176,10 @@ The host supplies account folders and shares conversation history as needed. The
 credentials. To connect an account, open its CLI in a new tab and let the person complete the CLI's own login:
 
 ```ts
-import type { HerdrKit } from '@byokit/herdr';
+import { HerdrKit } from '@byokit/herdr';
+const kit = new HerdrKit({ mode: 'adopt', bin: '/app/bin/herdr', socketPath: '/app/herdr.sock' });
+await kit.start();
 
-declare const kit: HerdrKit; // the host's started kit
 const signIn = await kit.openSignInTab({
   workspaceId: 'w1', kind: 'codex', cwd: '/home/me/project', env: { CODEX_HOME: '/app/accounts/work' },
 });
@@ -189,13 +190,42 @@ const moved = await kit.moveToAccount({ paneId: 'w1:p2' }, {
 if (moved.ok) console.log(moved.session); // new pane to follow
 ```
 
-A move accepts Claude/Pi for Claude folders and Codex/Pi for Codex folders. It verifies the new shell's effective
+A move accepts Claude for Claude folders and Codex for Codex folders. Pi ignores these folder variables and is refused. It verifies the new shell's effective
 account folder, resumes the conversation there, waits for a ready session, then closes the old pane. A failed
 start preserves the original; a failed source close rolls back the new pane. Failures return a plain `message`
 and a `live` pane id for recovery, including when cleanup fails. Wait until a conversation is idle or done before
 moving it. `StartAgent.env` applies to newly created placements; existing shells cannot receive a new env.
 Tokens stay on the device and are never logged. Each provider's own terms apply to how you use your plan.
 
+For managed-folder stores that supply resume arguments and credential shedding, use `move`:
+
+```ts
+import { HerdrKit } from '@byokit/herdr';
+const kit = new HerdrKit({ mode: 'adopt', bin: '/app/bin/herdr', socketPath: '/app/herdr.sock' });
+await kit.start();
+
+const conversationId = 'published-conversation-id';
+const staged = new Set<string>();
+let activePane = 'w1:p2';
+const moved = await kit.move({
+  paneId: 'w1:p2', kind: 'codex', args: ['resume', conversationId],
+  set: { CODEX_HOME: '/app/accounts/work' }, unset: ['OPENAI_API_KEY', 'CODEX_API_KEY'],
+  onStaged(paneId) { staged.add(paneId); },
+  onReplaced(paneId) { staged.delete(paneId); activePane = paneId; },
+});
+if (moved.ok) console.log(moved.paneId);
+await kit.cli(['integration', 'install', 'codex'], { env: { CODEX_HOME: '/app/accounts/work' } });
+```
+
+`MoveResult` names the new pane as `paneId`; `moveToAccount` retains its `session` result as
+`MoveToAccountResult`. Both share the same per-source lock. Staging runs before verification/start; a staging
+exception rolls back. Replacement notification runs after closing the source and cannot undo the move.
+`move` clears `unset` in the new shell, verifies the account folder and unset names' absence, and requires an interactive
+agent publishing a conversation before closing the source. The pinned start API has no command-prefix/env
+field, so this uses shell `unset` rather than `env -u`; shells that cannot clear a variable fail closed.
+Only folder paths belong in `set`, never tokens. `cli` env overlays the kit's explicit env for one call;
+it inherits no process variables. The default move step timeout is 60 seconds.
+
 ## Two ways in
 
 - `adopt` talks to the socket path the app passes: the person's own Herdr, nothing spawned, nothing written.

package/dist/accounts.d.ts

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

package/dist/accounts.js

@@ -17,11 +17,12 @@ export function createAccountPanes(ctx) {
     }
     // A shell rc can override placement env. Verify what the shell actually resolves, rather
     // than pane.get's launch env. The variable name is fixed by the provider, never caller text.
-    async function checkEnv(paneId, variable, folder, timeout) {
+    async function checkEnv(paneId, variable, folder, timeout, absent = false) {
         const marker = `BYOKIT_ACCOUNT_${randomBytes(8).toString('hex')}`;
         const deadline = Date.now() + timeout;
+        const expansion = absent ? '${' + variable + '+x}' : '$' + variable;
         try {
-            await call('pane.send_text', { pane_id: paneId, text: `echo ${marker}="$${variable}"\n` }, timeout);
+            await call('pane.send_text', { pane_id: paneId, text: `echo ${marker}="${expansion}"\n` }, timeout);
             for (;;) {
                 const result = await call('pane.read', { pane_id: paneId, source: 'recent_unwrapped', lines: 40,
                     format: 'text', strip_ansi: true }, Math.max(1, deadline - Date.now()));
@@ -38,6 +39,28 @@ export function createAccountPanes(ctx) {
             return false;
         }
     }
+    // agent.start has no env/unset/command field in the pinned protocol. Clear credentials in
+    // the shell that launches it, then verify absence (never echo credential values).
+    async function prepareEnv(paneId, set, unset, variable, timeout) {
+        const entries = Object.entries(set);
+        if ([...entries.map(([key]) => key), ...unset].some((key) => !/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
+            || entries.some(([, value]) => typeof value !== 'string' || /[\r\n\0]/.test(value))
+            || unset.some((key) => key in set))
+            return false;
+        try {
+            if (unset.length > 0)
+                await call('pane.send_text', { pane_id: paneId, text: `unset ${unset.join(' ')}\n` }, timeout);
+            if (!await checkEnv(paneId, variable, set[variable], timeout))
+                return false;
+            for (const key of unset)
+                if (!await checkEnv(paneId, key, '', timeout, true))
+                    return false;
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
     async function openSignInTab(o) {
         const { workspaceId, label, ...start } = o;
         try {
@@ -49,7 +72,7 @@ export function createAccountPanes(ctx) {
             throw Object.assign(new Error(words('agent.notReady')), { code: 'sign_in_failed' });
         }
     }
-    async function moveToAccount(target, o) {
+    async function perform(target, o, request) {
         const failed = (code, live = target.paneId) => ({ ok: false, code, message: words(`move.${code}`), live });
         if (moving.has(target.paneId))
             return failed('busy');
@@ -69,17 +92,17 @@ export function createAccountPanes(ctx) {
             if (!['idle', 'done'].includes(agent.agent_status))
                 return failed('busy');
             const kind = agent.agent;
-            if (!['claude', 'codex'].includes(o.provider) || ![o.provider, 'pi'].includes(kind)
-                || session.agent !== kind)
+            if (!['claude', 'codex'].includes(o.provider) || kind !== o.provider
+                || (request !== undefined && request.kind !== kind)
+                || session.agent !== kind || session.kind !== 'id')
                 return failed('unsupported');
-            const args = kind === 'pi' && session.kind === 'path' ? ['--session', session.value]
-                : kind === 'claude' && session.kind === 'id' ? ['--resume', session.value]
-                    : kind === 'codex' && session.kind === 'id' ? ['resume', session.value] : undefined;
-            if (args === undefined)
+            const args = request?.args ?? (kind === 'claude' && session.kind === 'id' ? ['--resume', session.value]
+                : kind === 'codex' && session.kind === 'id' ? ['resume', session.value] : undefined);
+            if (args === undefined || !Array.isArray(args) || args.length === 0 || args.some((a) => typeof a !== 'string' || /[\r\n\0]/.test(a)))
                 return failed('unsupported');
             if (!o.folder || /[\r\n\0]/.test(o.folder))
                 return failed('env_mismatch');
-            const timeout = o.timeoutMs ?? 15_000;
+            const timeout = o.timeoutMs ?? 60_000;
             if (!Number.isFinite(timeout) || timeout <= 0)
                 return failed('start_failed');
             const variable = o.provider === 'claude' ? 'CLAUDE_CONFIG_DIR' : 'CODEX_HOME';
@@ -96,21 +119,37 @@ export function createAccountPanes(ctx) {
             catch {
                 return failed('start_failed');
             }
-            if (!await checkEnv(paneId, variable, o.folder, timeout)) {
-                await close(paneId);
-                return failed('env_mismatch');
+            const rollback = async (code) => failed(code, await close(paneId) ? target.paneId : paneId);
+            try {
+                request?.onStaged?.(paneId);
+            }
+            catch {
+                return rollback('start_failed');
+            }
+            if (request !== undefined && !await prepareEnv(paneId, request.set, request.unset ?? [], variable, timeout)) {
+                return rollback('env_mismatch');
+            }
+            if (request === undefined && !await checkEnv(paneId, variable, o.folder, timeout)) {
+                return rollback('env_mismatch');
             }
             try {
                 // Unique names avoid colliding with the still-live source agent.
                 await ctx.startAgent({ kind, cwd: agent.foreground_cwd ?? agent.cwd ?? '.',
                     name: `move-${randomBytes(8).toString('hex')}`, place: { pane: paneId }, args, timeoutMs: timeout });
                 await call('agent.wait', { target: paneId, until: ['idle', 'done'], timeout_ms: timeout }, timeout + 5000);
-                const ready = (await call('agent.get', { target: paneId }))?.agent;
-                if (!ready || ready.launch_pending === true || !['idle', 'done'].includes(ready.agent_status)
-                    || ready.agent !== kind || ready.agent_session?.agent !== kind
-                    || ready.agent_session?.kind !== session.kind || typeof ready.agent_session?.value !== 'string'
-                    || ready.agent_session.value.length === 0)
-                    throw new Error('not ready');
+                const deadline = Date.now() + timeout;
+                for (;;) {
+                    const ready = (await call('agent.get', { target: paneId }, Math.max(1, deadline - Date.now())))?.agent;
+                    if (ready && ready.launch_pending !== true && ['idle', 'done'].includes(ready.agent_status)
+                        && (request === undefined || ready.interactive_ready === true)
+                        && ready.agent === kind && ready.agent_session?.agent === kind
+                        && ready.agent_session?.kind === session.kind && typeof ready.agent_session?.value === 'string'
+                        && ready.agent_session.value.length > 0)
+                        break;
+                    if (Date.now() >= deadline)
+                        throw new Error('not ready');
+                    await sleep(Math.min(100, Math.max(1, deadline - Date.now())));
+                }
             }
             catch {
                 const cleaned = await close(paneId);
@@ -120,11 +159,24 @@ export function createAccountPanes(ctx) {
                 const cleaned = await close(paneId);
                 return failed('close_failed', cleaned ? target.paneId : paneId);
             }
+            // The source is closed: a notification failure cannot undo a successful move.
+            try {
+                request?.onReplaced?.(paneId);
+            }
+            catch { /* notification only */ }
             return { ok: true, session: paneId };
         }
         finally {
             moving.delete(target.paneId);
         }
     }
-    return { openSignInTab, moveToAccount };
+    async function move(o) {
+        const variable = o.kind === 'claude' ? 'CLAUDE_CONFIG_DIR' : 'CODEX_HOME';
+        const result = await perform({ paneId: o.paneId }, {
+            provider: o.kind === 'claude' ? 'claude' : 'codex', folder: o.set[variable] ?? '',
+            env: o.set, timeoutMs: o.timeoutMs,
+        }, o);
+        return result.ok ? { ok: true, paneId: result.session } : result;
+    }
+    return { openSignInTab, move, moveToAccount: (target, o) => perform(target, o) };
 }

package/dist/index.d.ts

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

package/dist/kit.d.ts

@@ -1,4 +1,4 @@
-import type { AgentReadiness, AgentStartEvent, AgentStatusOptions, AgentRef, AgentStatus, BlockedAgent, HerdrEvent, HerdrEventName, HerdrEventOf, HerdrKitOptions, HerdrMethod, HerdrParams, HerdrResult, HerdrSnapshot, HerdrState, HerdrSubscription, HerdrSubscribeStop, PromptReceipt, StartAgent, TerminalSession, MoveToAccount, MoveResult, OpenSignInTab } from './types.ts';
+import type { AgentReadiness, AgentStartEvent, AgentStatusOptions, AgentRef, AgentStatus, BlockedAgent, HerdrEvent, HerdrEventName, HerdrEventOf, HerdrKitOptions, HerdrMethod, HerdrParams, HerdrResult, HerdrSnapshot, HerdrState, HerdrSubscription, HerdrSubscribeStop, PromptReceipt, StartAgent, TerminalSession, Move, MoveToAccount, MoveToAccountResult, MoveResult, OpenSignInTab } from './types.ts';
 export declare class HerdrKit {
     private readonly supervisor;
     private transport?;
@@ -39,6 +39,7 @@ export declare class HerdrKit {
     subscribe<E extends HerdrEventName>(subs: HerdrSubscription<E>[], on: (e: HerdrEventOf<E>) => void, onError?: (code: string, message: string) => void): HerdrSubscribeStop;
     cli(args: string[], o?: {
         timeoutMs?: number;
+        env?: Record<string, string>;
     }): Promise<{
         stdout: string;
         stderr: string;
@@ -68,7 +69,8 @@ export declare class HerdrKit {
      */
     statusWatchReady(): Promise<void>;
     openSignInTab(o: OpenSignInTab): Promise<AgentRef>;
-    moveToAccount(target: AgentRef, o: MoveToAccount): Promise<MoveResult>;
+    move(o: Move): Promise<MoveResult>;
+    moveToAccount(target: AgentRef, o: MoveToAccount): Promise<MoveToAccountResult>;
     startAgent(o: StartAgent): Promise<AgentRef>;
     onStartAgent(fn: (e: AgentStartEvent) => void): () => void;
     prompt(target: AgentRef, text: string, o?: {

package/dist/kit.js

@@ -427,7 +427,7 @@ export class HerdrKit {
             throw new Error('herdr: not connected');
         return this.transport.subscribe(subs, on, onError ?? (() => { }));
     }
-    cli(args, o) { return runCli(this.o.bin, this.supervisor.env(), args, o?.timeoutMs); }
+    cli(args, o) { return runCli(this.o.bin, { ...this.supervisor.env(), ...o?.env }, args, o?.timeoutMs); }
     terminal(paneId, o) { return openTerminal(this.o.bin, this.supervisor.env(), paneId, o); }
     snapshot() { return structuredClone(this.tree); }
     onChange(fn) { this.listeners.add(fn); return () => { this.listeners.delete(fn); }; }
@@ -447,6 +447,7 @@ export class HerdrKit {
      */
     statusWatchReady() { return this.statusReadyPromise; }
     openSignInTab(o) { return this.accountPanes.openSignInTab(o); }
+    move(o) { return this.accountPanes.move(o); }
     moveToAccount(target, o) { return this.accountPanes.moveToAccount(target, o); }
     startAgent(o) { return this.agents.startAgent(o); }
     // App-wide start lifecycle without polling: every startAgent's installing/ready/launchFailed

package/dist/types.d.ts

@@ -132,7 +132,7 @@ export type MoveToAccount = {
     direction?: 'right' | 'down';
     timeoutMs?: number;
 };
-export type MoveResult = {
+export type MoveToAccountResult = {
     ok: true;
     session: string;
 } | {
@@ -141,6 +141,22 @@ export type MoveResult = {
     message: string;
     live?: string;
 };
+export type Move = {
+    paneId: string;
+    kind: string;
+    args: string[];
+    set: Record<string, string>;
+    unset?: string[];
+    onStaged?(newPaneId: string): void;
+    onReplaced?(newPaneId: string): void;
+    timeoutMs?: number;
+};
+export type MoveResult = {
+    ok: true;
+    paneId: string;
+} | Extract<MoveToAccountResult, {
+    ok: false;
+}>;
 export type PromptReceipt = {
     paneId: string;
     terminalId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/herdr",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Drive the Herdr on this computer — workspaces, tabs, panes, agents and blocked-approval answers — from an app, or hand it to a phone over @byokit/link.",
   "license": "Apache-2.0",
   "type": "module",
@@ -54,7 +54,7 @@
   "dependencies": {
     "@byokit/link": "0.7.0",
     "@byokit/relay": "0.5.0",
-    "@byokit/reach": "0.5.0",
+    "@byokit/reach": "0.6.0",
     "@byokit/seal": "0.2.0",
     "ws": "8.21.3"
   },