@byokit/herdr 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+## 0.5.0 (2026-10-01)
+
+- SECURITY: StartAgent and openSignInTab accept a clean launch environment with explicit unsets, verified before launch in idle shells on new or existing panes; credential values stay out of terminal commands, argv and errors, preventing inherited API key (billed per use) variables from overriding subscription sign-in.
+
+## 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.
@@ -9,6 +19,9 @@
 - 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)
 

package/README.md

@@ -192,8 +192,12 @@ if (moved.ok) console.log(moved.session); // new pane to follow
 
 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.
 
@@ -219,7 +223,8 @@ await kit.cli(['integration', 'install', 'codex'], { env: { CODEX_HOME: '/app/ac
 
 `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.
+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.
@@ -307,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
@@ -328,3 +391,10 @@ package, never touches a person's other AI tools. Its tests run against a fake H
 ## License
 
 Apache-2.0. See [LICENSE](LICENSE) and [NOTICE](../../NOTICE).
+
+`startAgent` and `openSignInTab` accept the accounts `launchEnv()` result as `env: launch`.
+The host and Herdr must share a filesystem. New panes and existing idle POSIX shells apply
+the settings and unsets through a private temporary file before launch; only the file path
+is sent to the terminal. Busy panes and unsupported shells fail closed. Legacy record env
+still travels on new-pane placement, and remains refused on existing panes. Credential
+values must never be supplied in agent args.

package/dist/accounts.js

@@ -73,7 +73,7 @@ export function createAccountPanes(ctx) {
         }
     }
     async function perform(target, o, request) {
-        const failed = (code, live = target.paneId) => ({ ok: false, code, message: words(`move.${code}`), live });
+        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);
@@ -107,6 +107,7 @@ export function createAccountPanes(ctx) {
                 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,
@@ -144,8 +145,10 @@ export function createAccountPanes(ctx) {
                         && (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)
+                        && 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())));
@@ -156,8 +159,33 @@ export function createAccountPanes(ctx) {
                 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 {

package/dist/agents.js

@@ -7,6 +7,7 @@ import { accessSync, constants as fsConstants, openSync, readSync, closeSync } f
 import { homedir } from 'node:os';
 import { delimiter, join } from 'node:path';
 import { words } from "./words.js";
+import { prepareLaunchEnv } from "./launch-env.js";
 const PROMPTABLE = ['idle', 'working', 'blocked', 'done'];
 const DEFAULT_TIMEOUT_MS = 60_000;
 // `agent.start` lands while the fresh pane is still at its shell prompt: the server answers
@@ -81,15 +82,19 @@ export function createAgents(ctx) {
         catch (error) {
             const reason = classifyStartFailure(error, { installExpected, stage });
             emit({ phase: 'launchFailed', kind: o.kind, reason, message: launchFailureWords(reason, o.kind) });
+            if (o.env && typeof o.env.env === 'object')
+                throw fail(codeOf(error) === 'env_mismatch' ? 'env_mismatch' : 'start_failed', words('agent.notReady'));
             throw error;
         }
     }
     async function startAgentInner(o, onStartPhase) {
-        if ('pane' in o.place && Object.keys(o.env ?? {}).length > 0) {
+        const launch = o.env && typeof o.env.env === 'object' && Array.isArray(o.env.unset)
+            ? o.env : undefined;
+        if (!launch && 'pane' in o.place && Object.keys(o.env ?? {}).length > 0) {
             throw fail('env_mismatch', 'This pane needs to be opened again to use that sign-in.');
         }
         const timeout = o.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-        const env = o.env === undefined ? {} : { env: o.env };
+        const env = o.env === undefined || launch ? {} : { env: o.env };
         let paneId;
         let created = false;
         if (o.worktree !== undefined) {
@@ -127,6 +132,20 @@ export function createAgents(ctx) {
         }
         if (paneId === undefined)
             throw new Error('herdr: the placement answered no pane id');
+        if (launch) {
+            try {
+                await prepareLaunchEnv(call, paneId, launch, timeout);
+            }
+            catch (error) {
+                if (created) {
+                    try {
+                        await call('pane.close', { pane_id: paneId });
+                    }
+                    catch { /* best effort */ }
+                }
+                throw error;
+            }
+        }
         onStartPhase?.();
         const name = agentName(o);
         const params = { pane_id: paneId, kind: o.kind, name,
@@ -148,6 +167,8 @@ export function createAgents(ctx) {
                     }
                     catch { /* rollback is best-effort */ }
                 }
+                if (launch)
+                    throw fail('start_failed', words('agent.notReady'));
                 throw error;
             }
         }

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, Move, MoveToAccount, MoveToAccountResult, 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, 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;
@@ -79,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();
@@ -457,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/launch-env.d.ts

@@ -0,0 +1,6 @@
+import type { Call } from './agents.ts';
+export type LaunchEnvironment = {
+    env: Record<string, string>;
+    unset: string[];
+};
+export declare function prepareLaunchEnv(call: Call, paneId: string, launch: LaunchEnvironment, timeout: number): Promise<void>;

package/dist/launch-env.js

@@ -0,0 +1,71 @@
+// The pinned agent.start launches through the pane shell. Values stay in a private host file,
+// never terminal text or argv. Only an idle POSIX shell may source it; preparation fails closed.
+import { randomBytes } from 'node:crypto';
+import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+const quote = (v) => `'${v.replaceAll("'", "'\\''")}'`;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export async function prepareLaunchEnv(call, paneId, launch, timeout) {
+    let dir;
+    try {
+        if (!Number.isFinite(timeout) || timeout <= 0)
+            throw new Error();
+        const entries = Object.entries(launch.env);
+        const unset = [...launch.unset];
+        const names = [...entries.map(([key]) => key), ...unset];
+        if (names.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) => Object.hasOwn(launch.env, key)))
+            throw new Error();
+        const deadline = Date.now() + timeout;
+        // Do not send shell input to an agent or another foreground program.
+        for (;;) {
+            const result = await call('pane.process_info', { pane_id: paneId }, Math.max(1, deadline - Date.now()));
+            const info = result?.process_info;
+            if (info?.shell_pid && info.foreground_processes?.length === 1
+                && info.foreground_processes[0]?.pid === info.shell_pid
+                && /^(?:-)?(?:ba|z|da|k)?sh$/.test(info.foreground_processes[0].name))
+                break;
+            if (Date.now() >= deadline)
+                throw new Error();
+            await sleep(Math.min(100, Math.max(1, deadline - Date.now())));
+        }
+        const marker = `BYOKIT_ENV_${randomBytes(16).toString('hex')}`;
+        dir = mkdtempSync(join(tmpdir(), 'byokit-env-'));
+        const file = join(dir, 'prepare.sh');
+        const steps = [
+            'set +x +v',
+            // Remove exports absent from the clean result too: a pane may inherit more than the host.
+            // The pipeline is private; neither values nor variable listings reach the terminal.
+            `for BYOKIT_ENV_KEY in $(/usr/bin/env | /usr/bin/cut -d= -f1); do
+case "$BYOKIT_ENV_KEY" in ''|[!A-Za-z_]*|*[!A-Za-z0-9_]*) continue ;; esac
+case "$BYOKIT_ENV_KEY" in ${entries.length ? entries.map(([key]) => key).join('|') : 'BYOKIT_ENV_KEY'}) ;; *) unset "$BYOKIT_ENV_KEY" 2>/dev/null || return 1 ;; esac
+done`,
+            'unset BYOKIT_ENV_KEY',
+            ...unset.map((key) => `unset ${key}`),
+            ...entries.map(([key, value]) => `export ${key}=${quote(value)}`),
+            ...unset.map((key) => `test "\${${key}+present}" = ''`),
+            ...entries.map(([key, value]) => `test "\${${key}+present}" = present && test "$${key}" = ${quote(value)}`),
+            `printf '%s\\n' ${quote(marker)}`,
+        ];
+        writeFileSync(file, steps.join(' &&\n') + '\n', { mode: 0o600, flag: 'wx' });
+        await call('pane.send_text', { pane_id: paneId, text: `set +x +v; . ${quote(file)}\n` }, Math.max(1, deadline - Date.now()));
+        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()));
+            if (result?.read?.text?.split(/\r?\n/).some((line) => line.trim() === marker))
+                return;
+            if (Date.now() >= deadline)
+                throw new Error();
+            await sleep(Math.min(100, Math.max(1, deadline - Date.now())));
+        }
+    }
+    catch {
+        throw Object.assign(new Error('This pane could not use that sign-in.'), { code: 'env_mismatch' });
+    }
+    finally {
+        if (dir !== undefined)
+            rmSync(dir, { recursive: true, force: true });
+    }
+}

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

@@ -2,6 +2,7 @@
 // request per connection — the server closes after answering; only `events.subscribe` is held open.
 // Ported from muxr `perf/fake-herdr/server.mjs` with the UI plugins, title churn, graphics and perf
 // byte rates removed.
+import { spawnSync } from 'node:child_process';
 import { mkdirSync, unlinkSync } from 'node:fs';
 import { createServer } from 'node:net';
 import { join } from 'node:path';
@@ -235,6 +236,28 @@ export async function startFakeHerdr(options) {
             emitEvent('tab.renamed', { tab_id: tab.tab_id, workspace_id: tab.workspace_id, label: tab.label });
             return { type: 'tab_info', tab: tabView(tab) };
         },
+        'pane.process_info': (p) => {
+            const pane = paneOf(p.pane_id);
+            const busy = live.agents.some((a) => a.pane_id === pane.pane_id);
+            return { process_info: { shell_pid: 1, foreground_processes: [{ pid: busy ? 2 : 1, name: busy ? 'agent' : 'sh' }] } };
+        },
+        'pane.send_text': (p) => {
+            const pane = paneOf(p.pane_id);
+            const text = String(p.text ?? '');
+            // A real offline shell exercises the private launch file, never a real agent CLI.
+            if (!/^set \+x \+v; \. '/.test(text))
+                throw fail('unsupported', 'unsupported fake shell command');
+            const r = spawnSync('/bin/sh', ['-c', text + "printf '\\0'; /usr/bin/env -0"], {
+                env: pane.env ?? { PATH: '/usr/bin:/bin', HOME: dir }, encoding: 'utf8', timeout: 5000,
+            });
+            const [output, ...environment] = r.stdout.split('\0');
+            pane.text.push(output);
+            pane.env = Object.fromEntries(environment.filter(Boolean).map((entry) => {
+                const i = entry.indexOf('=');
+                return [entry.slice(0, i), entry.slice(i + 1)];
+            }));
+            return {};
+        },
         'pane.get': (p) => ({ pane: paneView(paneOf(p.pane_id)) }),
         'pane.close': (p) => {
             const pane = paneOf(p.pane_id);

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

@@ -116,7 +116,10 @@ export type StartAgent = {
         base?: string;
     };
     args?: string[];
-    env?: Record<string, string>;
+    env?: Record<string, string> | {
+        env: Record<string, string>;
+        unset: string[];
+    };
     timeoutMs?: number;
     onEvent?: (e: AgentStartEvent) => void;
     installProbe?: AgentInstallProbe;
@@ -164,6 +167,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.4.0",
+  "version": "0.5.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",
@@ -53,7 +53,7 @@
   },
   "dependencies": {
     "@byokit/link": "0.7.0",
-    "@byokit/relay": "0.5.0",
+    "@byokit/relay": "0.5.1",
     "@byokit/reach": "0.6.0",
     "@byokit/seal": "0.2.0",
     "ws": "8.21.3"