@byokit/herdr 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## Unreleased
 
+## 0.4.1 (2026-10-01)
+
+- Dependency update: pins @byokit/relay 0.5.1.
+
+- FIX: Preserve the ready replacement after a lost source-close acknowledgment unless fresh reads verify the original conversation survived; report only a verified recovery conversation, or omit `live` when verification is unavailable.
+
+## 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.
+- Track a subscription agent's turn with `runTurn` and `onTurnEnd`: acknowledged Herdr status
+  events, optional JSON validated by the app's schema validator, and changed files from bounded
+  before/after snapshots of the app-owned working directory. No additional API billing path.
+
 ## 0.3.0 (2026-10-01)
 
 - Dependency update: pins @byokit/reach 0.5.0.
@@ -24,6 +41,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,47 @@ 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
+start preserves the original. A failed source close rolls back the new pane only after fresh reads verify
+both conversations' identities. A lost close acknowledgment can mean the original already closed: the kit
+preserves the replacement when the source is absent, replaced or unreachable and returns `close_failed`.
+After uncertain source close or cleanup, `live` names a freshly verified surviving conversation; it is omitted
+when neither conversation can be verified. Check the remaining panes before retrying. Independent changes
+can still happen after verification; the server has no conditional close transaction. Failures return a plain `message`. Wait until a conversation is idle or done before
 moving it. `StartAgent.env` applies to newly created placements; existing shells cannot receive a new env.
 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 once after an acknowledged source close and cannot undo the move.
+An ambiguous close returns failure without a replacement notification, even if the source has disappeared.
+`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.
@@ -277,6 +312,64 @@ off();
 `start()` is non-fatal: if Herdr is down it rejects (state `failed`, e.g. `failed/socket`) and may be called again
 afterwards, so the host comes up while Herdr is down by retrying `start()` in a backoff loop.
 
+## Turn results
+
+`runTurn` prompts an existing subscription agent and resolves after Herdr reports that it worked
+and returned to `idle` or `done`. Subscribe app-wide with `onTurnEnd`, or use the call's `onEnd`.
+An initial idle or a blocked approval does not finish the turn; keep using `onBlocked`/`answer`.
+No provider API or additional billing path is involved.
+
+```ts
+import { HerdrKit } from '@byokit/herdr';
+
+const kit = new HerdrKit({ mode: 'adopt', bin: 'herdr', socketPath: '/tmp/herdr.sock' });
+await kit.start();
+const target = await kit.startAgent({ kind: 'codex', cwd: '/app/worktree', place: { workspace: 'new' } });
+const off = kit.onTurnEnd((end) => console.log(end.changedFiles));
+const end = await kit.runTurn(target, {
+  prompt: 'Implement the requested change, then report whether the build passed.',
+  cwd: '/app/worktree',
+  timeoutMs: 10 * 60_000,
+  files: { exclude: (path) => path === 'node_modules' || path === 'dist' },
+  result: {
+    schema: { type: 'object', required: ['buildPassed'], additionalProperties: false,
+      properties: { buildPassed: { type: 'boolean' } } },
+    // For larger schemas, call the app's existing JSON Schema validator here.
+    validate: (value: unknown): value is { buildPassed: boolean } =>
+      typeof value === 'object' && value !== null && 'buildPassed' in value &&
+      typeof value.buildPassed === 'boolean' && Object.keys(value).length === 1,
+  },
+});
+if (end.result.state === 'valid') console.log(end.result.value.buildPassed);
+off();
+```
+
+The kit asks the agent to write `{ turnId, result }` to a fresh JSON file in that folder before
+finishing. It checks the id, parses and validates the bounded file, and removes it. The result
+is `not-requested` without a policy, `missing` if the agent did not write it, `invalid` with a
+reason if it could not be accepted, or `valid` with a typed value. Unchecked payloads are never
+returned or logged; the transient result file is excluded from `changedFiles`. Default result
+limit: 1 MiB (`result.maxBytes`). The agent must follow these instructions; Herdr has no native
+schema-enforced response API. Task success is a separate app decision.
+
+`changedFiles` lists sorted relative paths with `added`, `modified` or `deleted`, including
+untracked files and changes to already-dirty files. Snapshots compare content, modes and symlink
+targets, do not traverse symlinks, always exclude `.git`, and ignore special files. Files changed
+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.
+
+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
+absolute `cwd` must match Herdr's reported working directory. Timeout, watch loss, pane closure or
+replacement, `kit.stop()` and an aborted `signal` reject without a completion event. Monitoring
+cancellation does not interrupt the agent; it may still finish or write its result file later.
+Herdr's working-to-idle/done detection is the end signal, not proof of semantic success. The kit
+does not guess completion from elapsed silence or a prompt receipt.
+
+This helper runs on the host. Apps own branches, review/apply/rollback and authorized forwarding
+of results to devices; it adds no link permission or device operation.
+
 ## Status
 
 Pinned to Herdr v0.9.1. The schema snapshot (`schema/herdr-api-0.9.1.json`, protocol 22) generates the typed surface

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,8 +72,8 @@ export function createAccountPanes(ctx) {
             throw Object.assign(new Error(words('agent.notReady')), { code: 'sign_in_failed' });
         }
     }
-    async function moveToAccount(target, o) {
-        const failed = (code, live = target.paneId) => ({ ok: false, code, message: words(`move.${code}`), live });
+    async function perform(target, o, request) {
+        const failed = (code, live = target.paneId) => ({ ok: false, code, message: words(`move.${code}`), ...(live === null ? {} : { live }) });
         if (moving.has(target.paneId))
             return failed('busy');
         moving.add(target.paneId);
@@ -69,21 +92,22 @@ 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';
             let paneId;
+            let replacement;
             try {
                 const split = await call('pane.split', { target_pane_id: target.paneId,
                     direction: o.direction ?? 'right', focus: false,
@@ -96,35 +120,91 @@ 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) {
+                        replacement = ready;
+                        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);
                 return failed('start_failed', cleaned ? target.paneId : paneId);
             }
             if (!await close(target.paneId)) {
-                const cleaned = await close(paneId);
-                return failed('close_failed', cleaned ? target.paneId : paneId);
+                // A lost ACK can mean the close already applied. Never destroy the ready
+                // replacement unless a fresh read proves the original conversation survived.
+                // Compare identity, not revision: status changes can legitimately bump revision.
+                const survives = async (id, expected) => {
+                    try {
+                        const current = (await call('agent.get', { target: id }, timeout))?.agent;
+                        return !!current && current.agent === expected.agent && current.launch_pending !== true
+                            && ['idle', 'working', 'blocked', 'done'].includes(current.agent_status)
+                            && current.agent_session?.agent === expected.agent_session?.agent
+                            && current.agent_session?.kind === expected.agent_session?.kind
+                            && current.agent_session?.value === expected.agent_session?.value
+                            && (expected.terminal_id === undefined || current.terminal_id === expected.terminal_id)
+                            && (expected.name === undefined || current.name === expected.name);
+                    }
+                    catch {
+                        return false;
+                    } // unavailable is not proof of survival
+                };
+                const replacementAlive = await survives(paneId, replacement);
+                const sourceAlive = await survives(target.paneId, agent);
+                if (sourceAlive && replacementAlive)
+                    await close(paneId);
+                // Re-read after cleanup too: its ACK can also be lost, or another actor can
+                // replace a pane. `live` is optional precisely when neither can be verified.
+                const live = await survives(paneId, replacement) ? paneId
+                    : await survives(target.paneId, agent) ? target.paneId : null;
+                return failed('close_failed', live);
+            }
+            // 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, AgentTurnEnd, AgentTurnOptions, AgentTurnFiles, AgentTurnResult, AgentTurnResultPolicy, } from './types.ts';

package/dist/kit.d.ts

@@ -1,4 +1,5 @@
-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';
+import type { AgentTurnEnd, AgentTurnOptions } from './types.ts';
 export declare class HerdrKit {
     private readonly supervisor;
     private transport?;
@@ -18,6 +19,7 @@ export declare class HerdrKit {
     private readonly agents;
     private readonly startListeners;
     private readonly blockedList;
+    private readonly turns;
     constructor(o: HerdrKitOptions);
     get state(): HerdrState;
     private publish;
@@ -39,6 +41,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 +71,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?: {
@@ -77,6 +81,8 @@ export declare class HerdrKit {
             timeoutMs: number;
         };
     }): Promise<PromptReceipt>;
+    runTurn<T = unknown>(target: AgentRef, o: AgentTurnOptions<T>): Promise<AgentTurnEnd<T>>;
+    onTurnEnd(fn: (end: AgentTurnEnd) => void): () => void;
     sendKeys(target: AgentRef, keys: string[]): Promise<void>;
     wait(target: AgentRef, o: {
         until?: AgentStatus[];

package/dist/kit.js

@@ -6,6 +6,7 @@ import { openTerminal } from "./terminal.js";
 import { protocolBounds } from "./constants.js";
 import { closePane, closeTab, closeWorkspace } from "./close.js";
 import { Supervisor } from "./supervise.js";
+import { createTurns } from "./turns.js";
 const kinds = ['pane.agent_detected', 'pane.created', 'pane.closed', 'pane.moved', 'pane.exited', 'pane.updated',
     'workspace.created', 'workspace.closed', 'workspace.renamed', 'workspace.updated', 'tab.created', 'tab.closed', 'tab.renamed'];
 const empty = () => ({ connected: false, workspaces: [] });
@@ -131,6 +132,7 @@ export class HerdrKit {
     agents;
     startListeners = new Set();
     blockedList;
+    turns;
     constructor(o) {
         this.o = o;
         this.supervisor = new Supervisor(o, (s) => { this.current = s; o.onState?.(s); });
@@ -143,6 +145,7 @@ export class HerdrKit {
                 }
                 catch { /* a listener never breaks a start */ } } });
         this.blockedList = new Blocked({ call: this.callAny });
+        this.turns = createTurns(this);
     }
     get state() { return this.current; }
     publish() { for (const fn of this.listeners)
@@ -396,6 +399,7 @@ export class HerdrKit {
         }
     }
     async stop() {
+        this.turns.stop();
         ++this.generation;
         this.statusReadyResolve?.();
         this.statusReadyPromise = Promise.resolve();
@@ -427,7 +431,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 +451,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
@@ -456,6 +461,8 @@ export class HerdrKit {
         return () => { this.startListeners.delete(fn); };
     }
     prompt(target, text, o) { return this.agents.prompt(target, text, 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); }
     wait(target, o) { return this.agents.wait(target, o); }
     read(paneId, o) { return this.agents.read(paneId, o); }

package/dist/turn-files.d.ts

@@ -0,0 +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 changedFiles(before: Map<string, string>, after: Map<string, string>): AgentTurnEnd['changedFiles'];

package/dist/turn-files.js

@@ -0,0 +1,88 @@
+import { createHash } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, open, readdir, readlink, realpath } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
+export function positiveLimit(value, fallback) {
+    const n = value ?? fallback;
+    if (!Number.isSafeInteger(n) || n <= 0)
+        throw new Error('turn: invalid limit');
+    return n;
+}
+// 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) {
+    const maxFiles = positiveLimit(policy?.maxFiles, 10000);
+    const maxBytes = positiveLimit(policy?.maxBytes, 128 * 1024 * 1024);
+    let entries = 0;
+    let bytes = 0;
+    const found = new Map();
+    async function walk(dir) {
+        active();
+        // Catch a directory being swapped for an out-of-tree symlink during a scan.
+        const canonical = await realpath(dir);
+        const within = relative(root, canonical);
+        if (canonical !== dir || within === '..' || within.startsWith(`..${sep}`))
+            throw new Error('turn: directory escaped');
+        for (const name of await readdir(dir)) {
+            active();
+            const path = join(dir, name);
+            const rel = relative(root, path).split(sep).join('/');
+            if (name === '.git' || rel === resultName || policy?.exclude?.(rel))
+                continue;
+            if (++entries > maxFiles)
+                throw new Error('turn: file limit');
+            const info = await lstat(path);
+            if (info.isSymbolicLink()) {
+                found.set(rel, `link:${await readlink(path)}`);
+            }
+            else if (info.isDirectory()) {
+                await walk(path);
+            }
+            else if (info.isFile()) {
+                const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+                try {
+                    const before = await file.stat();
+                    if (!before.isFile() || before.ino !== info.ino || before.dev !== info.dev)
+                        throw new Error('turn: file changed');
+                    const digest = createHash('sha256');
+                    const buffer = Buffer.alloc(64 * 1024);
+                    let total = 0;
+                    for (;;) {
+                        active();
+                        const { bytesRead } = await file.read(buffer, 0, buffer.length, null);
+                        bytes += bytesRead;
+                        total += bytesRead;
+                        if (bytes > maxBytes)
+                            throw new Error('turn: byte limit');
+                        if (bytesRead === 0)
+                            break;
+                        digest.update(buffer.subarray(0, bytesRead));
+                    }
+                    const after = await file.stat();
+                    if (before.size !== total || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) {
+                        throw new Error('turn: file changed');
+                    }
+                    found.set(rel, `${before.mode}:${digest.digest('hex')}`);
+                }
+                finally {
+                    await file.close();
+                }
+            }
+        }
+    }
+    await walk(root);
+    active();
+    return found;
+}
+export function changedFiles(before, after) {
+    const changes = [];
+    for (const path of [...new Set([...before.keys(), ...after.keys()])].sort()) {
+        if (!before.has(path))
+            changes.push({ path, change: 'added' });
+        else if (!after.has(path))
+            changes.push({ path, change: 'deleted' });
+        else if (before.get(path) !== after.get(path))
+            changes.push({ path, change: 'modified' });
+    }
+    return changes;
+}

package/dist/turns.d.ts

@@ -0,0 +1,7 @@
+import type { HerdrKit } from './kit.ts';
+import type { AgentRef, AgentTurnEnd, AgentTurnOptions } from './types.ts';
+export declare function createTurns(kit: HerdrKit): {
+    runTurn: <T>(target: AgentRef, o: AgentTurnOptions<T>) => Promise<AgentTurnEnd<T>>;
+    onTurnEnd(fn: (end: AgentTurnEnd) => void): () => void;
+    stop(): void;
+};

package/dist/turns.js

@@ -0,0 +1,225 @@
+import { randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { open, realpath, unlink } from 'node:fs/promises';
+import { isAbsolute, join, relative, sep } from 'node:path';
+import { changedFiles, positiveLimit, scanFiles } from "./turn-files.js";
+import { words } from "./words.js";
+const fail = (code) => Object.assign(new Error(words('turn.failed')), { code });
+const contains = (parent, child) => {
+    const rel = relative(parent, child);
+    return rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+};
+async function readResult(path, id, policy) {
+    const maxBytes = positiveLimit(policy.maxBytes, 1024 * 1024);
+    let file;
+    try {
+        file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return { state: 'missing' };
+        return { state: 'invalid', reason: 'unsafe-file' };
+    }
+    try {
+        const info = await file.stat();
+        if (!info.isFile())
+            return { state: 'invalid', reason: 'unsafe-file' };
+        if (info.size > maxBytes)
+            return { state: 'invalid', reason: 'too-large' };
+        const buffer = Buffer.alloc(Math.min(info.size + 1, maxBytes + 1));
+        let size = 0;
+        while (size < buffer.length) {
+            const { bytesRead } = await file.read(buffer, size, buffer.length - size, null);
+            if (!bytesRead)
+                break;
+            size += bytesRead;
+        }
+        if (size > maxBytes)
+            return { state: 'invalid', reason: 'too-large' };
+        const after = await file.stat();
+        if (size !== info.size || after.mtimeMs !== info.mtimeMs || after.ctimeMs !== info.ctimeMs) {
+            return { state: 'invalid', reason: 'format' };
+        }
+        let payload;
+        try {
+            payload = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(buffer.subarray(0, size)));
+        }
+        catch {
+            return { state: 'invalid', reason: 'format' };
+        }
+        if (typeof payload !== 'object' || payload === null || Array.isArray(payload) ||
+            !('turnId' in payload) || payload.turnId !== id || !('result' in payload)) {
+            return { state: 'invalid', reason: 'format' };
+        }
+        try {
+            if (policy.validate(payload.result))
+                return { state: 'valid', value: payload.result };
+        }
+        catch { /* Validator diagnostics may contain private data; never log them. */ }
+        return { state: 'invalid', reason: 'schema' };
+    }
+    finally {
+        await file.close();
+    }
+}
+export function createTurns(kit) {
+    const panes = new Set();
+    const roots = new Set();
+    const pending = new Set();
+    const listeners = new Set();
+    async function runTurn(target, o) {
+        if (panes.has(target.paneId))
+            throw fail('turn-busy');
+        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);
+        if (o.result)
+            positiveLimit(o.result.maxBytes, 1024 * 1024);
+        const schema = o.result ? JSON.stringify(o.result.schema) : undefined;
+        const id = randomUUID();
+        const resultName = `.byokit-turn-${id}.json`;
+        let root;
+        let ownsRoot = false;
+        let failure;
+        let rejectFailure;
+        const failed = new Promise((_, reject) => { rejectFailure = reject; });
+        void failed.catch(() => { });
+        const abort = (code) => {
+            if (failure)
+                return;
+            failure = fail(code);
+            rejectFailure(failure);
+        };
+        const active = () => { if (failure)
+            throw failure; };
+        const gate = (promise) => Promise.race([promise, failed]);
+        const cancelled = () => abort('turn-cancelled');
+        const stopped = () => abort('turn-unavailable');
+        panes.add(target.paneId);
+        pending.add(stopped);
+        const timer = setTimeout(() => abort('turn-timeout'), timeoutMs);
+        o.signal?.addEventListener('abort', cancelled, { once: true });
+        if (o.signal?.aborted)
+            cancelled();
+        let stopWatch;
+        let offEvent;
+        let offChange;
+        try {
+            active();
+            root = await gate(realpath(o.cwd));
+            if ([...roots].some((held) => contains(held, root) || contains(root, held)))
+                throw fail('turn-busy');
+            roots.add(root);
+            ownsRoot = true;
+            if (!kit.snapshot().connected)
+                throw fail('turn-watch-lost');
+            offChange = kit.onChange((tree) => { if (!tree.connected)
+                abort('turn-watch-lost'); });
+            let armed = false;
+            let working = false;
+            let ended = false;
+            let resolveEnd;
+            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')
+                        abort('turn-busy');
+                    return;
+                }
+                if (ended) {
+                    if (e.agent_status !== 'idle' && e.agent_status !== 'done')
+                        abort('turn-busy');
+                    return;
+                }
+                if (e.agent_status === 'working')
+                    working = true;
+                else if (working && (e.agent_status === 'idle' || e.agent_status === 'done')) {
+                    ended = true;
+                    resolveEnd(e.agent_status);
+                }
+            }, () => abort('turn-watch-lost'));
+            stopWatch = watch;
+            watch.onDisconnect(() => abort('turn-watch-lost'));
+            offEvent = kit.onEvent((e) => {
+                const kind = e.type.replace(/_/g, '.');
+                if (e.pane_id === target.paneId && ['pane.closed', 'pane.exited', 'pane.moved', 'pane.agent.detected'].includes(kind)) {
+                    abort('turn-unavailable');
+                }
+            });
+            if (!await gate(watch.ready))
+                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)
+                throw fail('turn-not-idle');
+            if (target.name && agent.name !== target.name)
+                throw fail('turn-unavailable');
+            const cwd = agent.foreground_cwd ?? agent.cwd;
+            if (typeof cwd !== 'string' || await gate(realpath(cwd)) !== root)
+                throw fail('turn-cwd');
+            const before = await gate(scanFiles(root, o.files, resultName, active));
+            const prompt = o.result ? `${o.prompt}\n\nBefore finishing, write a UTF-8 JSON file at ${JSON.stringify(join(root, resultName))}. ` +
+                `The file must contain {"turnId":${JSON.stringify(id)},"result":<your result>}. ` +
+                `The result must satisfy this JSON Schema: ${schema}. Write the file completely before returning to idle.` : o.prompt;
+            active();
+            armed = true;
+            const receipt = await gate(kit.prompt(target, prompt));
+            const status = await gate(endSignal);
+            // Recheck the occupant/directory before reading an agent-created file.
+            const afterAgent = (await gate(kit.call('agent.get', { target: target.paneId }))).agent;
+            if (afterAgent.terminal_id !== receipt.terminalId || afterAgent.name !== agent.name ||
+                afterAgent.agent !== agent.agent || !['idle', 'done'].includes(afterAgent.agent_status) ||
+                await gate(realpath(afterAgent.foreground_cwd ?? afterAgent.cwd ?? '')) !== root)
+                throw fail('turn-unavailable');
+            const result = o.result
+                ? await gate(readResult(join(root, resultName), id, o.result)) : { state: 'not-requested' };
+            const after = await gate(scanFiles(root, o.files, resultName, active));
+            active();
+            const end = { id, target: { ...target }, receipt, status, changedFiles: changedFiles(before, after), result };
+            // App callbacks cannot turn a completed turn into a failed call, and never see unchecked bytes.
+            for (const fn of [...listeners])
+                try {
+                    fn(end);
+                }
+                catch { /* host listener */ }
+            try {
+                o.onEnd?.(end);
+            }
+            catch { /* per-turn listener */ }
+            return end;
+        }
+        catch (error) {
+            if (failure)
+                throw failure;
+            const code = error?.code;
+            if (code?.startsWith('turn-'))
+                throw error;
+            throw fail('turn-failed');
+        }
+        finally {
+            clearTimeout(timer);
+            o.signal?.removeEventListener('abort', cancelled);
+            stopWatch?.();
+            offEvent?.();
+            offChange?.();
+            pending.delete(stopped);
+            panes.delete(target.paneId);
+            if (ownsRoot && root) {
+                // Unlink only the kit's unique output path; never recursively delete a directory or follow a link.
+                if (o.result && await realpath(root).catch(() => undefined) === root) {
+                    await unlink(join(root, resultName)).catch(() => { });
+                }
+                roots.delete(root);
+            }
+        }
+    }
+    return {
+        runTurn,
+        onTurnEnd(fn) { listeners.add(fn); return () => { listeners.delete(fn); }; },
+        stop() { for (const cancel of [...pending])
+            cancel(); },
+    };
+}

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;
@@ -148,6 +164,47 @@ export type PromptReceipt = {
     status: AgentStatus;
     agentSession?: AgentSessionRef;
 };
+export type AgentTurnFiles = {
+    /** Relative paths, including directories. Returning true prunes the entry. `.git` is always excluded. */
+    exclude?: (relativePath: string) => boolean;
+    maxFiles?: number;
+    maxBytes?: number;
+};
+export type AgentTurnResultPolicy<T> = {
+    schema: Record<string, unknown>;
+    /** Use the app's JSON Schema validator; false or a throw rejects the payload. */
+    validate: (value: unknown) => value is T;
+    maxBytes?: number;
+};
+export type AgentTurnOptions<T = unknown> = {
+    prompt: string;
+    cwd: string;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    files?: AgentTurnFiles;
+    result?: AgentTurnResultPolicy<T>;
+    onEnd?: (end: AgentTurnEnd<T>) => void;
+};
+export type AgentTurnResult<T = unknown> = {
+    state: 'not-requested' | 'missing';
+} | {
+    state: 'invalid';
+    reason: 'format' | 'schema' | 'too-large' | 'unsafe-file';
+} | {
+    state: 'valid';
+    value: T;
+};
+export type AgentTurnEnd<T = unknown> = {
+    id: string;
+    target: AgentRef;
+    receipt: PromptReceipt;
+    status: 'idle' | 'done';
+    changedFiles: {
+        path: string;
+        change: 'added' | 'modified' | 'deleted';
+    }[];
+    result: AgentTurnResult<T>;
+};
 export type BlockedAgent = {
     paneId: string;
     workspaceId: string;

package/dist/words.json

@@ -23,6 +23,7 @@
     "move.busy": "Wait for this conversation to finish before moving it.",
     "move.unsupported": "This conversation cannot move between these accounts.",
     "move.env_mismatch": "The new pane did not receive that sign-in. Try again.",
-    "move.close_failed": "The old pane could not close. The move was undone where possible.",
-    "move.start_failed": "The new account could not take over. Try again."
+    "move.close_failed": "The move could not be confirmed. Check the remaining panes before trying again.",
+    "move.start_failed": "The new account could not take over. Try again.",
+    "turn.failed": "This turn could not be confirmed. Check the helper before trying again."
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/herdr",
-  "version": "0.3.0",
+  "version": "0.4.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/link.",
   "license": "Apache-2.0",
   "type": "module",
@@ -53,8 +53,8 @@
   },
   "dependencies": {
     "@byokit/link": "0.7.0",
-    "@byokit/relay": "0.5.0",
-    "@byokit/reach": "0.5.0",
+    "@byokit/relay": "0.5.1",
+    "@byokit/reach": "0.6.0",
     "@byokit/seal": "0.2.0",
     "ws": "8.21.3"
   },