@byokit/herdr 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## 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.
@@ -9,6 +15,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

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/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/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

@@ -164,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.4.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,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"