@visual-z/xeno 0.8.4 → 0.9.1

package/src/runtime/runtime-target.ts

@@ -1,149 +0,0 @@
-/** R8: live capabilities stay with their Session; only observations cross a log boundary. */
-import { randomUUID } from "node:crypto";
-import { hostname } from "node:os";
-import { join, resolve } from "node:path";
-import type { LogEvent, ArtifactRef } from "../core/events.ts";
-import { deriveAcceptance, type AcceptanceState } from "../core/acceptance.ts";
-import { canonicalValue } from "../core/continuation.ts";
-import { isCommandArtifactReceipt, sameArtifactIdentity, type CommandArtifactReceipt } from "../core/command-artifacts.ts";
-import { targetIsReady, type RuntimeTarget, type RuntimeTargetReceipt, type RuntimeInstance } from "../core/runtime-target.ts";
-import { failureDiagnostic, ToolFault, NOT_STARTED, UNKNOWN_EFFECT } from "../core/tool-failure.ts";
-import { commandTimeout } from "../core/command-contract.ts";
-import { executionOutcome } from "../core/outcome.ts";
-import { archiveCommandArtifacts, artifactExclusions, observeArtifactFiles, observeArtifactInputs } from "../store/command-artifacts.ts";
-import { readObservation } from "../store/observations.ts";
-import { targetDirectory, targetProgram, observeRuntimeIdentity } from "../store/runtime-target.ts";
-import { findSession, startSession, pollSession, yieldWait } from "./exec-sessions.ts";
-import { sessionResult, type ToolContext, type ToolResult } from "./tools.ts";
-
-type History = readonly { node: number; events: readonly LogEvent[] }[];
-type LiveTarget = { request: string; contract: string; build: string; instance: RuntimeInstance };
-type Request = { action: "start" | "inspect"; target: string; session_id?: number; yield_time_ms?: number; timeout?: number };
-// Assumed bound for the small build manifest; binaries are observed separately, never read from log JSON.
-const MANIFEST_BYTES = 256 * 1024;
-
-export class RuntimeTargets {
-  private readonly live = new Map<string, LiveTarget>();
-
-  async perform(ctx: ToolContext, history: History, input: Request): Promise<{ result: ToolResult; observation: RuntimeTargetReceipt }> {
-    const events = history.flatMap(part => [...part.events]);
-    const state = deriveAcceptance(undefined, events);
-    const contract = events.find(event => event.id === state?.contract_event);
-    const target = contract?.t === "acceptance_contract" ? contract.contract.targets?.find(item => item.id === input.target) : undefined;
-    if (!state || !target) throw new ToolFault("invalid_input", "target must name a runtime in the current trusted acceptance contract", NOT_STARTED);
-    const archive = ctx.outputStore ?? join(ctx.root, ".xeno", "observations");
-    const receipt: RuntimeTargetReceipt = { kind: "runtime_target", version: 1, target: target.id,
-      request: state.request, contract_event: state.contract_event, state: "unknown", reason: "runtime has not been observed",
-      observed_at: new Date().toISOString(), source: { host: ctx.hostId ?? hostname(), workspace: resolve(ctx.root), cwd: resolve(ctx.root, target.workdir ?? "."), runtime: `bun/${Bun.version}` },
-      ...(target.port === undefined ? {} : { port: target.port }),
-      checks: { build: false, inputs: false, artifacts: false, process: false, image: false, port: target.port === undefined ? null : false } };
-    const raw: ArtifactRef[] = [];
-    let processResult: ToolResult | undefined;
-    let launched = false;
-    try {
-      const build = await this.build(ctx, history, state, target, receipt);
-      const existing = this.live.get(target.id);
-      if (input.action === "start") {
-        if (input.session_id !== undefined) throw Error("start does not accept a session_id; inspect an existing handle instead");
-        if (existing && findSession(existing.instance.session, ctx.execOwner)?.alive()) throw Error(`target already owns session ${existing.instance.session}; inspect or stop that handle before starting another`);
-        if (!build) throw Error(receipt.reason);
-        const cwd = await targetDirectory(ctx.root, target.workdir ?? ".");
-        const entryPath = join(await targetDirectory(ctx.root, "."), target.entry);
-        const program = await targetProgram(target.interpreter ?? entryPath, ctx.signal);
-        if (ctx.signal?.aborted) throw Error("target start cancelled before execution");
-        const argv = [program.path, ...(target.interpreter ? [entryPath] : []), ...(target.args ?? [])];
-        const command = argv.map(arg => `'${arg.replaceAll("'", "'\\''")}'`).join(" ");
-        const source = { ...receipt.source, cwd };
-        const session = await startSession({ argv, command, cwd, tty: false, spoolDir: archive, source,
-          timeoutMs: commandTimeout(input.timeout, ctx.timeoutMs, ctx.maxTimeoutMs), ...(ctx.execOwner ? { owner: ctx.execOwner } : {}) });
-        if ("error" in session) throw Error(session.error);
-        launched = true;
-        const entry = build.outputs.find(output => output.path === target.entry)!.after;
-        if (entry.state !== "observed") throw Error("target entry observation missing");
-        const live: LiveTarget = { request: state.request, contract: state.contract_event, build: receipt.build!.event,
-          instance: { id: randomUUID(), session: session.id, pid: session.pid, source, entry: { path: entryPath, sha256: entry.sha256 }, program } };
-        this.live.set(target.id, live);
-        const taken = await pollSession(session, archive, ctx.maxOutputBytes, yieldWait(input.yield_time_ms ?? 1000).ms, "", ctx.signal);
-        raw.push(taken.stored.ref);
-        processResult = await sessionResult(ctx, session.command, session.timeoutMs, taken);
-      }
-      const live = this.live.get(target.id);
-      if (!live || live.request !== state.request || live.contract !== state.contract_event) throw Error("no live target capability in this Session; historical PID observations are not reattached");
-      receipt.instance = live.instance; receipt.source = live.instance.source;
-      if (input.session_id !== undefined && live.instance.session !== input.session_id) throw Error("requested handle is not this target instance");
-      if (!build || live.build !== receipt.build?.event) { receipt.state = "stale"; throw Error("the running instance is not bound to the current successful build"); }
-      const session = findSession(live.instance.session, ctx.execOwner);
-      if (!session || !session.alive() || session.exit !== null) { receipt.state = "stale"; throw Error("owned runtime exited or its live capability was lost"); }
-      const actual = await observeRuntimeIdentity(session.pid, live.instance.program, target.port, archive, ctx.signal);
-      raw.push(...actual.raw);
-      // Recheck after OS inspection: neither an exec nor a file replacement during a probe can inherit readiness.
-      const current = await targetProgram(target.interpreter ?? live.instance.entry.path, ctx.signal);
-      const currentBuild = await this.build(ctx, history, state, target, receipt);
-      receipt.checks.process = findSession(session.id, ctx.execOwner) === session && session.alive() && session.exit === null;
-      receipt.checks.image = actual.image && canonicalValue(current) === canonicalValue(live.instance.program);
-      receipt.checks.port = actual.port;
-      receipt.reason = !currentBuild ? receipt.reason : !receipt.checks.process ? "owned runtime exited during observation" :
-        !receipt.checks.image ? "runtime executable identity changed or could not be established" : actual.reason;
-      receipt.state = targetIsReady(receipt) ? "ready" : !actual.known ? "unknown" : !currentBuild || !receipt.checks.process ? "stale" : "not_ready";
-    } catch (error) { receipt.reason = error instanceof Error ? error.message : "target observation failed"; }
-    // Cancellation can arrive during a bounded file/OS probe, after the first
-    // poll released its listener. Finish through the same owned process path.
-    if (ctx.signal?.aborted) {
-      const live = this.live.get(target.id);
-      const session = live && live.request === state.request && live.contract === state.contract_event ? findSession(live.instance.session, ctx.execOwner) : undefined;
-      if (session) {
-        const taken = await pollSession(session, archive, ctx.maxOutputBytes, 0, "", ctx.signal);
-        raw.push(taken.stored.ref); processResult = await sessionResult(ctx, session.command, session.timeoutMs, taken);
-      }
-      receipt.state = "unknown"; receipt.checks.process = false; receipt.reason = "target observation cancelled";
-    }
-    receipt.observed_at = new Date().toISOString();
-    try { receipt.manifest = await archiveCommandArtifacts(archive, { observation: receipt, raw }); }
-    catch { receipt.state = "unknown"; receipt.reason = "runtime observation archive unavailable"; }
-    const content = `target ${target.id}: ${receipt.state}; ${receipt.reason}\n` +
-      `build ${receipt.build?.event ?? "none"}; entry ${receipt.instance?.entry.path ?? target.entry}; ` +
-      `session ${receipt.instance?.session ?? "none"}; pid ${receipt.instance?.pid ?? "unknown"}; port ${target.port ?? "not declared"}` +
-      (receipt.manifest ? `\nObservation: history artifact=${receipt.manifest.sha256}` : "") +
-      (receipt.state === "ready" ? "\nAwaiting explicit user acceptance of this instance." : "");
-    const result: ToolResult = { ...processResult, ok: receipt.state === "ready", content: content + (processResult ? `\n${processResult.content}` : ""),
-      // Process exit and target readiness are different operations. Keep the
-      // actual exit in effect/data; only the target owns this tool's outcome.
-      outcome: processResult?.outcome?.reason === "cancelled" || processResult?.outcome?.reason === "timeout" ? processResult.outcome :
-        executionOutcome(ctx.signal?.aborted ? "cancelled" : receipt.state === "ready" ? "tool_completed" : "tool_failed"),
-      ...(processResult?.data ? {} : { data: receipt }),
-      ...(receipt.state === "ready" ? {} : { diagnostic: failureDiagnostic(ctx.signal?.aborted ? "cancelled" : "unknown_effect", receipt.reason, launched ? UNKNOWN_EFFECT : NOT_STARTED) }) };
-    // The original stream reference must still match the process receipt. The
-    // separate target event/manifest preserves the richer runtime observation.
-    return { result, observation: receipt };
-  }
-
-  private async build(ctx: ToolContext, history: History, state: AcceptanceState, target: RuntimeTarget, receipt: RuntimeTargetReceipt): Promise<CommandArtifactReceipt | undefined> {
-    const criterion = state.criteria.find(item => item.id === target.build);
-    const part = history.find(part => part.events.some(event => event.id === criterion?.evidence?.event_id));
-    const event = part?.events.find(event => event.id === criterion?.evidence?.event_id);
-    const build = event?.t === "tool_result" && event.ok && event.effect?.kind === "command" && event.effect.exit === 0 ? event.effect.artifacts : undefined;
-    if (criterion?.status !== "pass" || !isCommandArtifactReceipt(build) || build.state !== "observed" || !build.manifest || !part || !event ||
-      criterion.kind !== "command" || build.command !== criterion.command || build.source.host !== receipt.source.host ||
-      build.source.workspace !== resolve(ctx.root) || canonicalValue(build.plan) !== canonicalValue(target.artifacts)) {
-      receipt.reason = `run the exact build condition ${target.build} with artifacts=${JSON.stringify(target.artifacts)} on this host and workspace`; return undefined;
-    }
-    receipt.build = { node: part.node, event: event.id, manifest: build.manifest };
-    const exclusions = artifactExclusions(ctx.root, target.artifacts, [...(ctx.ownedStatePaths ?? []), ctx.outputStore ?? join(ctx.root, ".xeno", "observations")]);
-    const { manifest, ...original } = build;
-    if (manifest.bytes > MANIFEST_BYTES) throw Error("build manifest exceeds runtime verification budget");
-    const page = await readObservation(ctx.outputStore ?? join(ctx.root, ".xeno", "observations"), manifest.sha256, 0, MANIFEST_BYTES);
-    if (page.next !== null || page.bytes !== manifest.bytes || canonicalValue(JSON.parse(page.text)) !== canonicalValue(original) ||
-      canonicalValue(exclusions) !== canonicalValue(build.inputs.exclusions)) throw Error("build observation scope or archived manifest does not match its original receipt");
-    receipt.checks.build = true;
-    const inputs = await observeArtifactInputs(ctx.root, exclusions, ctx.signal);
-    const files = await observeArtifactFiles(ctx.root, target.artifacts.paths, ctx.signal);
-    receipt.checks.inputs = inputs.sha256 !== null && inputs.sha256 === build.inputs.after;
-    receipt.checks.artifacts = build.outputs.every((output, i) => {
-      const file = files[i];
-      return file?.state === "observed" && output.after.state === "observed" && file.sha256 === output.after.sha256 &&
-        file.bytes === output.after.bytes && sameArtifactIdentity(file.identity, output.after.identity);
-    });
-    if (!receipt.checks.inputs || !receipt.checks.artifacts) { receipt.state = "stale"; receipt.reason = "build inputs or artifact bytes/identity changed; rebuild before launching or accepting"; return undefined; }
-    return build;
-  }
-}

package/src/runtime/secrets.ts

@@ -1,79 +0,0 @@
-/**
- * The session's live view of its secret vault (S.9). Rules and the inverse
- * live in core/secrets.ts; this owns the mutable entries, their durable
- * append, and the walk over an event's fields.
- *
- * One keeper per session tree: a branch shares its parent's, because both
- * write the same log and a placeholder number must mean one value in it.
- */
-import { expandText, isSolicitedSecret, mapStrings, placeholder, redactText, type SecretEntry } from "../core/secrets.ts";
-import type { LogEvent } from "../core/events.ts";
-import { appendVault, readVault } from "../store/secrets.ts";
-
-// Fields whose bytes a provider or the store verifies: rewriting them breaks
-// replay (signed thinking, raw provider blocks) or identity, and none of them
-// carries text a person typed or a tool printed.
-const VERIFIED_FIELDS = new Set(["id", "at", "raw", "wire", "signature", "replay_key", "sha256", "call_id", "user_id", "parent_call_id"]);
-
-export class SecretKeeper {
-  private entries: SecretEntry[] = [];
-  private pending: Promise<void> = Promise.resolve();
-
-  private readonly dir: string;
-  private readonly candidates: readonly { value: string; rule: string }[];
-
-  constructor(dir: string, candidates: readonly { value: string; rule: string }[] = []) {
-    this.dir = dir; this.candidates = candidates;
-  }
-
-  async load(): Promise<void> {
-    const stored = await readVault(this.dir);
-    // Entries this keeper already assigned (none before start) stay; stored ones fill in.
-    for (const entry of stored) if (!this.entries.some(known => known.n === entry.n)) this.entries.push(entry);
-  }
-
-  /**
-   * Returns the event to write and whether this call added vault entries. The
-   * entries are in memory at once -- the next event numbers after them -- and
-   * durable before the returned promise resolves, so no written event ever
-   * holds a placeholder the vault cannot expand.
-   */
-  async redact(event: LogEvent, previousAssistantText: string | undefined): Promise<{ event: LogEvent; added: number }> {
-    const added: SecretEntry[] = [];
-    const redact = (text: string): string => {
-      const result = redactText(text, [...this.entries, ...added], this.candidates);
-      added.push(...result.added);
-      return result.text;
-    };
-    const skip = (key: string) => VERIFIED_FIELDS.has(key);
-    let next: LogEvent;
-    if (event.t === "checkpoint") next = event; // file fingerprints and paths, never projected
-    else if (event.t === "assistant") {
-      // Thinking is replayed under the provider's signature; a changed byte is a rejected request.
-      next = { ...event, blocks: event.blocks.map(block => block.type === "thinking" ? block : mapStrings(block, redact, skip) as typeof block) };
-    } else if (event.t === "user" && isSolicitedSecret(event.text, previousAssistantText)) {
-      // The whole message is the credential, however short: it was asked for.
-      const value = event.text.trim();
-      const entry = this.entries.find(known => known.value === value) ??
-        { n: this.entries.reduce((max, known) => Math.max(max, known.n), 0) + 1, value, rule: "solicited" };
-      if (!this.entries.includes(entry)) added.push(entry);
-      next = { ...mapStrings(event, redact, key => skip(key) || key === "text") as LogEvent & { t: "user" }, text: placeholder(entry.n) };
-    } else next = mapStrings(event, redact, skip) as LogEvent;
-    if (added.length > 0) {
-      this.entries.push(...added);
-      const write = this.pending.then(() => appendVault(this.dir, added));
-      this.pending = write.catch(() => {});
-      await write;
-    }
-    return { event: next, added: added.length };
-  }
-
-  /** Tool input as the tool should run it: placeholders become values. */
-  expand(input: unknown): unknown {
-    return this.entries.length === 0 ? input : mapStrings(input, text => expandText(text, this.entries));
-  }
-}
-
-export const SECRET_GUIDANCE = "Values written as [[xeno-secret-N]] are credentials xeno hid from you. " +
-  "Use the placeholder exactly as written in tool inputs; xeno substitutes the real value when the tool runs " +
-  "and hides it again in the output. Do not ask the user to repeat a hidden value.";

package/src/runtime/self-update.ts

@@ -1,74 +0,0 @@
-/**
- * Run the package manager for an explicit `/update` (docs/tasks/fix-update-installs.md).
- *
- * The argv comes from core's `installArgv`; this module only owns the process.
- * Every competitor runs the install unbounded, and that is exactly what their
- * hang reports are about (claude-code #80147, opencode #10921 `bun add`
- * stuck forever), so the install has a deadline and streams its latest line
- * to the caller as evidence that it is moving.
- */
-import { access, constants } from "node:fs/promises";
-import type { InstallOutcome } from "../core/update-check.ts";
-
-/** A global bun/npm install normally takes seconds; three minutes covers a slow registry. Assumed. */
-export const INSTALL_TIMEOUT_MS = 180_000;
-/** Lines of package-manager output kept for a failure message: enough for an npm error block. */
-const TAIL_LINES = 6;
-
-export interface InstallOptions {
-  readonly signal?: AbortSignal;
-  readonly timeoutMs?: number;
-  /** The package manager's newest non-empty output line. */
-  readonly onLine?: (line: string) => void;
-  /** Refuse before spawning when this directory cannot be written, as pi does. */
-  readonly writableDir?: string;
-}
-
-const ANSI = /\x1b\[[0-9;?]*[A-Za-z]|\x1b\][^\x07]*\x07|\r/g;
-
-export async function runInstall(argv: readonly string[], options: InstallOptions = {}): Promise<InstallOutcome> {
-  if (options.signal?.aborted) return { kind: "cancelled" };
-  if (options.writableDir) {
-    try { await access(options.writableDir, constants.W_OK); }
-    catch { return { kind: "unavailable", reason: `${options.writableDir} is not writable by this user` }; }
-  }
-  // Resolve through PATH like the person's own shell would; a bun-run xeno can always fall back to its own bun.
-  const program = Bun.which(argv[0]!) ?? (argv[0] === "bun" ? process.execPath : null);
-  if (!program) return { kind: "unavailable", reason: `${argv[0]} was not found on PATH` };
-  let child: ReturnType<typeof Bun.spawn<"ignore", "pipe", "pipe">>;
-  try { child = Bun.spawn([program, ...argv.slice(1)], { stdin: "ignore", stdout: "pipe", stderr: "pipe" }); }
-  catch (error) { return { kind: "unavailable", reason: error instanceof Error ? error.message : String(error) }; }
-
-  const output: string[] = [];
-  const read = async (stream: ReadableStream<Uint8Array>) => {
-    const decoder = new TextDecoder();
-    let pending = "";
-    const take = (line: string) => {
-      const clean = line.replace(ANSI, "").trim();
-      if (!clean) return;
-      output.push(clean); if (output.length > TAIL_LINES) output.shift();
-      options.onLine?.(clean);
-    };
-    for await (const chunk of stream) {
-      const lines = (pending + decoder.decode(chunk, { stream: true })).split("\n");
-      pending = lines.pop()!;
-      lines.forEach(take);
-    }
-    take(pending + decoder.decode());
-  };
-
-  let stopped: "timeout" | "cancelled" | undefined;
-  const timeoutMs = options.timeoutMs ?? INSTALL_TIMEOUT_MS;
-  const timer = setTimeout(() => { stopped = "timeout"; child.kill(); }, timeoutMs);
-  const abort = () => { stopped ??= "cancelled"; child.kill(); };
-  options.signal?.addEventListener("abort", abort, { once: true });
-  try {
-    const [code] = await Promise.all([child.exited, read(child.stdout), read(child.stderr)]);
-    if (stopped === "timeout") return { kind: "timeout", ms: timeoutMs, output };
-    if (stopped === "cancelled") return { kind: "cancelled" };
-    return code === 0 ? { kind: "installed" } : { kind: "exit", code, output };
-  } finally {
-    clearTimeout(timer);
-    options.signal?.removeEventListener("abort", abort);
-  }
-}

package/src/runtime/session-control.ts

@@ -1,265 +0,0 @@
-/** Q24: one controller per live Session, shared by the TUI and structured adapters. */
-import { createHash, randomUUID } from "node:crypto";
-import { resolve } from "node:path";
-import { goalView, contextLens, type GoalView, type ContextLens } from "../core/control-view.ts";
-import { DEFAULT_CONTEXT_POLICY } from "../core/context-policy.ts";
-import { userInputData, type UserInput } from "../core/images.ts";
-import type { Phase } from "../core/queue.ts";
-import type { PermissionRequest } from "../core/permissions.ts";
-import type { ExecutionOutcome } from "../core/outcome.ts";
-import type { LogEvent } from "../core/events.ts";
-import { readNodeHistory } from "../store/restore.ts";
-import type { Session, LoopEvent, RequestOptions } from "./loop.ts";
-import type { ApprovalChoice } from "./tools.ts";
-import { validateQuestionReply, type QuestionRequest, type QuestionReply } from "../core/question.ts";
-import type { QuestionSlot } from "./question-tool.ts";
-import { requestExternalEffects } from "./turn-effects.ts";
-import type { ExternalEffect } from "../core/external-effects.ts";
-
-export type ControlNotice = { method: string; params: { threadId: string; streamId: string; sequence: number; turnId?: string; [key: string]: unknown } };
-export type PendingApproval = { id: string; turnId: string; request: PermissionRequest };
-export type ControlSnapshot = {
-  version: "xeno-control/0.1"; threadId: string; streamId: string; sequence: number; node: number;
-  activeTurnId: string | null; goal: GoalView | null; context: ContextLens;
-  workflowMode: "build" | "plan";
-  waiting: "permission" | "question" | "auth" | null; approvals: PendingApproval[]; questions: QuestionRequest[];
-};
-
-export class SessionControl {
-  /** App-owned configuration switches resources at an idle checkpoint; observers cannot mutate it. */
-  configureWorkflow?: (mode: "build" | "plan") => Promise<void>;
-  readonly questionSlot: QuestionSlot;
-  private questionClients = 0;
-  private readonly questionAdapter: NonNullable<QuestionSlot["current"]> = (request, signal) => this.askQuestion(request, signal);
-  private readonly questions = new Map<string, { request: QuestionRequest; resolve(reply: QuestionReply | undefined): void }>();
-  readonly session: Session;
-  readonly threadId: string;
-  readonly streamId = randomUUID();
-  private sequence = 0;
-  private listeners = new Set<(event: ControlNotice) => void>();
-  private active: { id: string; abort: AbortController; queue: UserInput[] } | null = null;
-  private task: Promise<void> | null = null;
-  private approvals = new Map<string, { data: PendingApproval; resolve: (choice: ApprovalChoice) => void }>();
-  private waiting: ControlSnapshot["waiting"] = null;
-  private changing = false;
-  private inputSource: ((phase: Phase) => Promise<UserInput | null>) | undefined;
-  /** What the last finished turn did outside the workspace, as sent with its turn/completed. */
-  lastExternalEffects: readonly ExternalEffect[] = [];
-
-  constructor(session: Session) {
-    this.session = session;
-    this.questionSlot = session.config.tools.questionSlot ?? {};
-    // Same identity rule as provider affinity; no new durable identity store (D8).
-    this.threadId = createHash("sha256").update(resolve(session.config.logDir)).digest("hex");
-    session.subscribeRecords(item => this.emit("item/completed", { item }));
-  }
-  get activeTurnId(): string | null { return this.active?.id ?? null; }
-  get busy(): boolean { return this.changing || this.active !== null || this.session.running; }
-
-  /** One owner excludes turn admission across asynchronous checkpoint/configuration work. */
-  async withIdleChange<T>(operation: () => Promise<T>): Promise<T> {
-    if (this.busy) throw Error("configuration changes require an idle session");
-    this.changing = true;
-    try { const result = await operation(); this.emit("thread/statusChanged"); return result; }
-    finally { this.changing = false; }
-  }
-
-  subscribe(listener: (event: ControlNotice) => void): () => void {
-    this.listeners.add(listener); return () => { this.listeners.delete(listener); };
-  }
-  /** The attached editor owns retractable drafts even when an adapter starts the turn. */
-  attachInput(pull: (phase: Phase) => Promise<UserInput | null>): () => void {
-    if (this.inputSource) throw Error("the session already has an attached input owner");
-    this.inputSource = pull;
-    return () => { if (this.inputSource === pull) this.inputSource = undefined; };
-  }
-  private emit(method: string, data: Record<string, unknown> = {}): void {
-    const event: ControlNotice = { method, params: { ...data, threadId: this.threadId, streamId: this.streamId,
-      sequence: ++this.sequence, ...(this.active ? { turnId: this.active.id } : {}) } };
-    for (const listener of this.listeners) {
-      // Observers are outside the evidence owner: mutations and failures cannot alter execution.
-      try { listener(structuredClone(event)); } catch { /* the transport owns delivery errors */ }
-    }
-  }
-  async snapshot(observe = true): Promise<ControlSnapshot> {
-    if (observe && !this.busy) await this.session.acceptanceState();
-    const node = this.session.state.node;
-    const history = await readNodeHistory(this.session.config.logDir, node, undefined, "context");
-    if (!history.ok) throw Error(history.error);
-    if (node !== this.session.state.node) throw Error("session changed while reading; refresh the snapshot");
-    const s = this.session;
-    // Ancestors are sealed. The live segment must share the cursor's publication
-    // boundary: a disk read can finish between append and in-memory publication.
-    const parts = history.nodes.map(part => part.node === node ? { node, events: structuredClone(s.state.events) } : part);
-    const projectedGoal = goalView(parts, { strict: s.config.strictVerification === true, blind: s.config.blindChecks !== undefined });
-    const goal = this.active && projectedGoal?.state.request.event !== this.active.id ? null : projectedGoal;
-    return { version: "xeno-control/0.1", threadId: this.threadId, streamId: this.streamId, sequence: this.sequence, node,
-      activeTurnId: this.activeTurnId, goal, waiting: this.waiting, workflowMode: s.config.tools.workflowMode ?? "build",
-      approvals: structuredClone([...this.approvals.values()].map(item => item.data)),
-      questions: structuredClone([...this.questions.values()].map(item => item.request)),
-      context: contextLens({ ...s.contextInput(), anchor: s.state.anchor, policy: s.config.contextPolicy ?? DEFAULT_CONTEXT_POLICY,
-        contextWindow: s.provider.config.spec.contextWindow, outputReserve: s.provider.config.maxTokens,
-        ...(s.config.counter ? { counter: s.config.counter } : {}), ...(s.config.boundary ? { boundary: s.config.boundary } : {}) }) };
-  }
-  async items(): Promise<{ node: number; event: LogEvent }[]> {
-    const node = this.session.state.node;
-    const history = await readNodeHistory(this.session.config.logDir, node, undefined, "context");
-    if (!history.ok) throw Error(history.error);
-    if (node !== this.session.state.node) throw Error("session changed while reading; refresh the snapshot");
-    return history.nodes.flatMap(part => (part.node === node ? structuredClone(this.session.state.events) : part.events)
-      .map(event => ({ node: part.node, event })));
-  }
-
-  /** Both local and remote turns pass through this iterator; Session remains the execution owner. */
-  async *send(input: UserInput, signal?: AbortSignal, pull?: (phase: Phase) => Promise<UserInput | null>, options?: RequestOptions): AsyncGenerator<LoopEvent> {
-    if (this.busy) throw Error("a turn is already running");
-    const active = { id: this.session.clock.nextId(), abort: new AbortController(), queue: [] as UserInput[] };
-    this.active = active;
-    this.questionSlot.activeTurn = active.id;
-    const signals = signal ? AbortSignal.any([signal, active.abort.signal]) : active.abort.signal;
-    let outcome: ExecutionOutcome | undefined;
-    try {
-      this.emit("turn/started");
-      const steering = async (phase: Phase): Promise<UserInput | null> => {
-        const external = active.queue.splice(0), local = await (pull ?? this.inputSource)?.(phase);
-        if (local) external.push(local);
-        const data = external.map(value => userInputData(value));
-        const text = data.map(value => value.text).join("\n\n"), images = data.flatMap(value => value.images ?? []);
-        return images.length ? { text, images } : text || null;
-      };
-      for await (const event of this.session.send(input, signals, steering, active.id, options)) {
-        this.emit("turn/event", { event });
-        if (event.kind === "done") outcome = event.outcome;
-        yield event;
-      }
-    } catch (error) {
-      // Raw provider errors may contain credentials. The owner can report a sanitized error separately.
-      this.emit("turn/error", { message: "turn failed; inspect the session outcome" });
-      throw error;
-    } finally {
-      for (const approval of [...this.approvals.values()]) approval.resolve("deny");
-      for (const question of [...this.questions.values()]) question.resolve(undefined);
-      delete this.questionSlot.activeTurn;
-      this.waiting = null;
-      // A thrown provider error also appends an outcome. Clients must be able to discover it.
-      try {
-        if (!outcome) {
-          const state = (await this.snapshot(false)).goal?.state;
-          if (state?.request.event === active.id) outcome = state.execution;
-        }
-      } catch { /* unreadable storage stays unknown, never an invented completion */ }
-      // feat-external-effects-summary: a projection of this request's receipts, never a stored event.
-      let externalEffects: ExternalEffect[] = [];
-      try { externalEffects = requestExternalEffects(this.session); } catch { /* the list is advisory; a read failure shows none */ }
-      this.lastExternalEffects = externalEffects;
-      this.emit("turn/completed", { ...(outcome ? { outcome } : {}), steeringUndelivered: active.queue.length, externalEffects });
-      this.active = null;
-    }
-  }
-  start(input: UserInput): string {
-    if (this.busy) throw Error("a turn is already running");
-    this.task = (async () => { for await (const _event of this.send(input)) { /* notices are the client stream */ } })();
-    void this.task.catch(() => {});
-    return this.active!.id;
-  }
-  async whenIdle(): Promise<void> { await this.task; await this.session.whenIdle(); }
-  private current(turnId: string): NonNullable<SessionControl["active"]> {
-    if (!this.active || this.active.id !== turnId) throw Error("stale or unknown turnId");
-    return this.active;
-  }
-  steer(turnId: string, input: UserInput): void {
-    const turn = this.current(turnId);
-    // Assumed ingress bound, not an execution policy. Keep a client from queuing unbounded work.
-    if (turn.queue.length >= 32) throw Error("steering queue is full");
-    turn.queue.push(structuredClone(input));
-    this.session.wakeProcessWaits();
-    this.emit("turn/steeringQueued", { count: turn.queue.length });
-  }
-  interrupt(turnId: string): void {
-    this.current(turnId).abort.abort();
-    for (const approval of [...this.approvals.values()]) approval.resolve("deny");
-    for (const question of [...this.questions.values()]) question.resolve(undefined);
-    this.session.cancel();
-  }
-  setWaiting(kind: ControlSnapshot["waiting"]): void {
-    this.waiting = this.approvals.size ? "permission" : kind;
-    this.emit("thread/statusChanged", { waiting: this.waiting });
-  }
-  ask(request: PermissionRequest, present?: (id: string, resolve: (choice: ApprovalChoice) => void) => (() => void)): Promise<ApprovalChoice> {
-    if (!this.active) return Promise.resolve("deny");
-    const data = { id: randomUUID(), turnId: this.active.id, request: structuredClone(request) };
-    return new Promise(resolveChoice => {
-      let close: (() => void) | undefined;
-      const resolveOnce = (choice: ApprovalChoice) => {
-        if (!this.approvals.delete(data.id)) return;
-        close?.(); this.waiting = this.approvals.size ? "permission" : null;
-        this.emit("approval/resolved", { approvalId: data.id }); resolveChoice(choice);
-      };
-      this.approvals.set(data.id, { data, resolve: resolveOnce }); this.waiting = "permission";
-      this.emit("approval/request", { approval: data });
-      if (this.approvals.has(data.id)) {
-        try { close = present?.(data.id, resolveOnce); }
-        catch { resolveOnce("deny"); }
-      }
-    });
-  }
-  respond(turnId: string, id: string, choice: ApprovalChoice): void {
-    this.current(turnId);
-    const approval = this.approvals.get(id);
-    if (!approval || approval.data.turnId !== turnId) throw Error("stale or unknown approvalId");
-    approval.resolve(choice);
-  }
-  denyApprovals(): void { for (const approval of [...this.approvals.values()]) approval.resolve("deny"); }
-  attachQuestionClient(): () => void {
-    this.questionClients++;
-    if (!this.questionSlot.current) this.questionSlot.current = this.questionAdapter;
-    let closed = false;
-    return () => {
-      if (closed) return; closed = true;
-      if (--this.questionClients === 0) {
-        if (this.questionSlot.current === this.questionAdapter) delete this.questionSlot.current;
-        for (const question of [...this.questions.values()]) question.resolve(undefined);
-      }
-    };
-  }
-  askQuestion(request: QuestionRequest, signal: AbortSignal, present?: (request: QuestionRequest) => Promise<unknown>): Promise<QuestionReply | undefined> {
-    if (!this.active || request.turn_id !== this.active.id || signal.aborted || !present && this.questionClients === 0) return Promise.resolve(undefined);
-    if (this.questions.has(request.request_id)) return Promise.reject(Error("duplicate question invocation"));
-    return new Promise(resolve => {
-      const finish = (reply: QuestionReply | undefined) => {
-        if (!this.questions.delete(request.request_id)) return;
-        signal.removeEventListener("abort", aborted); this.setWaiting(this.questions.size ? "question" : null);
-        this.emit("question/resolved", { requestId: request.request_id }); resolve(reply);
-      };
-      const aborted = () => finish(undefined);
-      this.questions.set(request.request_id, { request: structuredClone(request), resolve: finish });
-      signal.addEventListener("abort", aborted, { once: true }); this.setWaiting("question");
-      this.emit("question/request", { question: structuredClone(request) });
-      if (present) void present(structuredClone(request)).then(value => {
-        if (value === undefined) finish(undefined); else try { finish(validateQuestionReply(request, value)); } catch { finish(undefined); }
-      }).catch(() => finish(undefined));
-    });
-  }
-  respondQuestion(turnId: string, requestId: string, reply: unknown): void {
-    this.current(turnId); const question = this.questions.get(requestId);
-    if (!question || question.request.turn_id !== turnId) throw Error("stale or unknown question requestId");
-    question.resolve(validateQuestionReply(question.request, reply));
-  }
-  async accept(requestId: string, criterion: string): Promise<void> {
-    if (this.busy) throw Error("acceptance requires an idle session");
-    this.changing = true;
-    try {
-      const state = await this.session.requestState();
-      if (state?.request.event !== requestId) throw Error("stale or unknown requestId");
-      await this.session.acceptCriterion(criterion);
-      this.emit("thread/statusChanged");
-    } finally { this.changing = false; }
-  }
-}
-
-const controls = new WeakMap<Session, SessionControl>();
-export function sessionControl(session: Session): SessionControl {
-  let control = controls.get(session);
-  if (!control) { control = new SessionControl(session); controls.set(session, control); }
-  return control;
-}