@visual-z/xeno 0.8.4 → 0.9.0

package/src/runtime/control-client.ts

@@ -1,149 +0,0 @@
-/** Typed local control client; requests are never retried after a delivery error. */
-import { CONTROL_SCHEMA, parseControlRequest } from "../core/control-protocol.ts";
-import type { ContextLens, LensFocus } from "../core/control-view.ts";
-import type { LogEvent } from "../core/events.ts";
-import type { QuestionReply } from "../core/question.ts";
-import type { SessionList } from "../store/sessions.ts";
-import type { ControlNotice, ControlSnapshot } from "./session-control.ts";
-
-export interface ControlApi {
-  "thread/read": { params: { threadId: string }; result: ControlSnapshot };
-  "thread/list": { params: Record<string, never>; result: SessionList & { live: string[] } };
-  "thread/new": { params: { name?: string }; result: ControlSnapshot };
-  "thread/resume": { params: { session: string }; result: ControlSnapshot };
-  "thread/fork": { params: { threadId: string; name?: string }; result: ControlSnapshot };
-  "thread/close": { params: { threadId: string }; result: { closed: boolean } };
-  "thread/mode": { params: { threadId: string; mode: "build" | "plan" }; result: ControlSnapshot };
-  "turn/start": { params: { threadId: string; input: string }; result: { turnId: string } };
-  "turn/steer": { params: { threadId: string; turnId: string; input: string }; result: { queued: boolean } };
-  "turn/interrupt": { params: { threadId: string; turnId: string }; result: { interruptRequested: boolean } };
-  "approval/respond": { params: { threadId: string; turnId: string; approvalId: string; choice: "once" | "command" | "tool" | "deny" }; result: { accepted: boolean } };
-  "question/respond": { params: { threadId: string; turnId: string; requestId: string; reply: string }; result: { accepted: boolean } };
-  "acceptance/accept": { params: { threadId: string; requestId: string; criterionId: string }; result: { accepted: boolean } };
-  "context/read": { params: { threadId: string; focus: LensFocus; offset?: number; limit?: number }; result: {
-    node: number; streamId: string; sequence: number; focus: LensFocus; total: number; entries: readonly unknown[]; nextOffset: number | null;
-    components: ContextLens["components"]; used: ContextLens["used"]; countKind: ContextLens["countKind"] } };
-  "item/list": { params: { threadId: string; after?: { node: number; event: string }; limit?: number }; result: {
-    items: { node: number; id: string; type: LogEvent["t"] }[]; nextCursor: { node: number; event: string } | null } };
-  "item/read": { params: { threadId: string; node: number; event: string }; result: { node: number; event: LogEvent } };
-  "thread/subscribe": { params: { threadId: string; after?: { streamId: string; sequence: number } }; result: { snapshot: ControlSnapshot; resyncRequired: boolean } };
-}
-function record(value: unknown): value is Record<string, unknown> { return !!value && typeof value === "object" && !Array.isArray(value); }
-function identity(value: unknown): value is string { return typeof value === "string" && value.length > 0 && value.length <= 128; }
-function count(value: unknown): value is number { return typeof value === "number" && Number.isSafeInteger(value) && value >= 0; }
-function snapshot(value: unknown): boolean {
-  return record(value) && value["version"] === CONTROL_SCHEMA.protocol && identity(value["threadId"]) && identity(value["streamId"]) && count(value["sequence"])
-    && count(value["node"]) && (value["activeTurnId"] === null || identity(value["activeTurnId"])) && (value["goal"] === null || record(value["goal"]))
-    && [null, "permission", "question", "auth"].includes(value["waiting"] as null) && Array.isArray(value["approvals"]) && Array.isArray(value["questions"]) && record(value["context"]);
-}
-function result(method: keyof ControlApi, value: unknown): boolean {
-  if (["thread/read", "thread/new", "thread/resume", "thread/fork", "thread/mode"].includes(method)) return snapshot(value);
-  if (!record(value)) return false;
-  switch (method) {
-    case "thread/list": return Array.isArray(value["sessions"]) && count(value["truncated"]) && Array.isArray(value["live"]) && value["live"].every(identity);
-    case "thread/close": return typeof value["closed"] === "boolean";
-    case "turn/start": return identity(value["turnId"]);
-    case "turn/steer": return typeof value["queued"] === "boolean";
-    case "turn/interrupt": return typeof value["interruptRequested"] === "boolean";
-    case "approval/respond": case "question/respond": case "acceptance/accept": return typeof value["accepted"] === "boolean";
-    case "thread/subscribe": return snapshot(value["snapshot"]) && typeof value["resyncRequired"] === "boolean";
-    case "context/read": return count(value["node"]) && identity(value["streamId"]) && count(value["sequence"]) && ["messages", "omitted", "history"].includes(String(value["focus"]))
-      && count(value["total"]) && Array.isArray(value["entries"]) && (value["nextOffset"] === null || count(value["nextOffset"])) && record(value["components"])
-      && typeof value["used"] === "number" && typeof value["countKind"] === "string";
-    case "item/list": return Array.isArray(value["items"]) && value["items"].every(item => record(item) && count(item["node"]) && identity(item["id"]) && typeof item["type"] === "string")
-      && (value["nextCursor"] === null || record(value["nextCursor"]) && count(value["nextCursor"]["node"]) && identity(value["nextCursor"]["event"]));
-    case "item/read": return count(value["node"]) && record(value["event"]) && identity(value["event"]["id"]) && typeof value["event"]["t"] === "string";
-    default: return false;
-  }
-}
-export class ControlClient {
-  private readonly write: (line: string) => void;
-  private readonly closeTransport: (() => void) | undefined;
-  private next = 1;
-  private buffer = "";
-  private closed = false;
-  private ready = false;
-  private initializing = false;
-  private readonly pending = new Map<number, { resolve(value: unknown): void; reject(error: Error): void; timer: ReturnType<typeof setTimeout> }>();
-  private readonly listeners = new Set<(notice: ControlNotice) => void>();
-  constructor(write: (line: string) => void, options: { close?: () => void } = {}) { this.write = write; this.closeTransport = options.close; }
-  onNotice(listener: (notice: ControlNotice) => void, threadId?: string): () => void {
-    const actual = threadId ? (notice: ControlNotice) => { if (notice.params.threadId === threadId) listener(notice); } : listener;
-    this.listeners.add(actual); return () => { this.listeners.delete(actual); };
-  }
-  async initialize(name: string, version: string): Promise<{ threadId: string; streamId: string }> {
-    if (this.ready || this.initializing) throw Error("control client already initialized or initializing");
-    this.initializing = true;
-    try {
-      const value = await this.raw("initialize", { clientInfo: { name, version } });
-      if (!record(value) || value["protocol"] !== CONTROL_SCHEMA.protocol || !identity(value["threadId"]) || !identity(value["streamId"])) {
-        this.close("unsupported or invalid control initialize result"); throw Error("unsupported or invalid control initialize result");
-      }
-      try { this.write(JSON.stringify({ method: "initialized", params: {} }) + "\n"); }
-      catch { this.close("control handshake delivery failed"); throw Error("control handshake delivery failed"); }
-      this.ready = true; return { threadId: value["threadId"], streamId: value["streamId"] };
-    } finally { this.initializing = false; }
-  }
-  request<M extends keyof ControlApi>(method: M, params: ControlApi[M]["params"]): Promise<ControlApi[M]["result"]> {
-    if (!this.ready) return Promise.reject(Error("initialize the control client before making requests"));
-    return this.raw(method, params).then(value => {
-      if (!result(method, value)) { this.close("invalid typed control result"); throw Error("invalid typed control result"); }
-      return value as ControlApi[M]["result"];
-    });
-  }
-  respondQuestion(threadId: string, turnId: string, requestId: string, reply: QuestionReply): Promise<{ accepted: boolean }> {
-    return this.request("question/respond", { threadId, turnId, requestId, reply: JSON.stringify(reply) });
-  }
-  raw(method: string, params: Record<string, unknown>, timeoutMs = 30_000): Promise<unknown> {
-    if (this.closed) return Promise.reject(Error("control client is closed"));
-    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 300_000) return Promise.reject(Error("control timeout must be 1..300000 ms"));
-    if (this.pending.size >= CONTROL_SCHEMA.limits.queuedRequests) return Promise.reject(Error("client request limit reached"));
-    const id = this.next++, line = JSON.stringify({ id, method, params }) + "\n";
-    try { parseControlRequest({ id, method, params }); } catch { return Promise.reject(Error("invalid control request parameters")); }
-    if (Buffer.byteLength(line) > CONTROL_SCHEMA.limits.frameBytes) return Promise.reject(Error("request exceeds frame limit"));
-    return new Promise((resolve, reject) => {
-      const timer = setTimeout(() => { this.pending.delete(id); reject(Error("request timed out; effect is unknown, inspect before retrying")); }, timeoutMs);
-      this.pending.set(id, { resolve, reject, timer });
-      try { this.write(line); } catch { clearTimeout(timer); this.pending.delete(id); reject(Error("control delivery failed; effects are unknown, inspect before retrying")); }
-    });
-  }
-  feed(text: string): void {
-    if (this.closed) return;
-    this.buffer += text;
-    for (;;) {
-      const at = this.buffer.indexOf("\n");
-      if (at < 0) { if (Buffer.byteLength(this.buffer) > CONTROL_SCHEMA.limits.frameBytes) this.close("oversized control frame"); return; }
-      const line = this.buffer.slice(0, at); this.buffer = this.buffer.slice(at + 1);
-      if (Buffer.byteLength(line) > CONTROL_SCHEMA.limits.frameBytes) { this.close("oversized control frame"); return; }
-      if (!line.trim()) continue;
-      let data: unknown;
-      try { data = JSON.parse(line); } catch { this.close("invalid control JSON"); return; }
-      if (!record(data)) { this.close("invalid control envelope"); return; }
-      if (Object.hasOwn(data, "id")) {
-        const id = data["id"], error = data["error"];
-        if (!(id === null || typeof id === "number" && Number.isSafeInteger(id) && id >= 1) || Object.keys(data).some(key => !["id", "result", "error"].includes(key))
-          || Object.hasOwn(data, "result") === Object.hasOwn(data, "error")
-          || Object.hasOwn(data, "error") && (!record(error) || !Number.isSafeInteger(error["code"]) || typeof error["message"] !== "string" || Object.keys(error).some(key => !["code", "message"].includes(key)))) {
-          this.close("invalid control response envelope"); return;
-        }
-        if (id === null) { this.close("control server rejected the connection frame"); return; }
-        const pending = this.pending.get(id); if (!pending) continue;
-        this.pending.delete(id); clearTimeout(pending.timer);
-        if (record(error)) pending.reject(Error(`Control request rejected (${String(error["code"])}): ${String(error["message"]).slice(0, 512)}`)); else pending.resolve(data["result"]);
-      } else {
-        const params = data["params"], method = data["method"];
-        if (Object.keys(data).some(key => !["method", "params"].includes(key)) || typeof method !== "string" || !CONTROL_SCHEMA.notifications.some(name => name === method)
-          || !record(params) || !identity(params["threadId"]) || !identity(params["streamId"]) || !count(params["sequence"]) || params["sequence"] === 0
-          || params["turnId"] !== undefined && !identity(params["turnId"])) { this.close("invalid control notification envelope"); return; }
-        for (const listener of this.listeners) try { listener(structuredClone(data) as ControlNotice); } catch { /* observers do not own transport */ }
-      }
-    }
-  }
-  close(reason = "control transport closed; unresolved effects are unknown"): void {
-    if (this.closed) return;
-    this.closed = true; this.ready = false; this.buffer = "";
-    for (const item of this.pending.values()) { clearTimeout(item.timer); item.reject(Error(reason)); }
-    this.pending.clear(); this.listeners.clear();
-    try { this.closeTransport?.(); } catch { /* transport failures cannot reopen this client or replay requests */ }
-  }
-}

package/src/runtime/control-connection.ts

@@ -1,139 +0,0 @@
-/** Connection lifecycle is transient; durable state belongs exclusively to Session's log (Q24). */
-import { CONTROL_SCHEMA, parseControlRequest, ControlProtocolError, type RpcId } from "../core/control-protocol.ts";
-import { selectLens, type LensFocus } from "../core/control-view.ts";
-import { assertNever } from "../core/exhaustive.ts";
-import type { SessionControl } from "./session-control.ts";
-import type { ApprovalChoice } from "./tools.ts";
-import type { SessionHub } from "./session-hub.ts";
-
-export type RpcOutput = { id: RpcId | null; result?: unknown; error?: { code: number; message: string } } | { method: string; params: unknown };
-
-export class ControlConnection {
-  private readonly control: () => SessionControl;
-  private readonly write: (output: RpcOutput) => void;
-  private initialized = false;
-  private ready = false;
-  private subscribed = false;
-  private closed = false;
-  private attached: SessionControl | undefined;
-  private stop: (() => void) | undefined;
-  private readonly denyOnClose: boolean;
-  private readonly hub: SessionHub | undefined;
-  private readonly subscriptions = new Map<SessionControl, () => void>();
-  private readonly questionClients = new Map<SessionControl, () => void>();
-
-  constructor(control: () => SessionControl, write: (output: RpcOutput) => void, options: { denyOnClose?: boolean; hub?: SessionHub } = {}) {
-    this.control = control; this.write = write; this.denyOnClose = options.denyOnClose ?? false;
-    this.hub = options.hub;
-  }
-  private attach(): SessionControl {
-    const control = this.control();
-    if (this.attached !== control) {
-      this.stop?.(); this.attached = control;
-      this.stop = control.subscribe(notice => { if (!this.closed && this.ready && this.subscribed) this.write(notice); });
-    }
-    return control;
-  }
-  async receive(value: unknown): Promise<void> {
-    if (this.closed) return;
-    let id: RpcId | null = null;
-    try {
-      if (typeof value === "object" && value !== null && "id" in value &&
-        (typeof value.id === "string" && value.id.length <= 128 || typeof value.id === "number" && Number.isSafeInteger(value.id))) id = value.id;
-      const request = parseControlRequest(value), params = request.params;
-      let control = this.attach();
-      if (request.method === "initialize") {
-        if (this.initialized) throw new ControlProtocolError(-32000, "already initialized");
-        this.initialized = true;
-        this.write({ id, result: { protocol: CONTROL_SCHEMA.protocol, experimental: true, threadId: control.threadId, streamId: control.streamId,
-          capabilities: { turns: true, steering: true, approvals: true, questions: true, contextLens: true, snapshotResync: true, durableEventReplay: "item/list", adaptiveExecution: false } } });
-        return;
-      }
-      if (!this.initialized) throw new ControlProtocolError(-32000, "not initialized");
-      if (request.method === "initialized") { if (this.ready) throw new ControlProtocolError(-32000, "already ready"); this.ready = true; return; }
-      if (!this.ready) throw new ControlProtocolError(-32000, "send initialized before using the session");
-      if (request.method === "thread/list") {
-        if (!this.hub) throw Error("multi-session methods require app-server");
-        this.write({ id, result: await this.hub.list() }); return;
-      }
-      if (request.method === "thread/new" || request.method === "thread/resume") {
-        if (!this.hub) throw Error("multi-session methods require app-server");
-        const opened = await this.hub.open(request.method === "thread/new" ? "new" : "resume", params);
-        this.write({ id, result: await opened.snapshot() }); return;
-      }
-      if (this.hub && typeof params["threadId"] === "string") control = this.hub.get(params["threadId"]);
-      if (params["threadId"] !== control.threadId) throw new ControlProtocolError(-32000, "stale or unknown threadId; initialize a new connection after changing sessions");
-      let result: unknown;
-      switch (request.method) {
-        case "thread/fork": {
-          if (!this.hub) throw Error("multi-session methods require app-server");
-          result = await (await this.hub.open("fork", { ...params, session: control.session.config.logDir })).snapshot(); break;
-        }
-        case "thread/close": {
-          if (!this.hub) throw Error("multi-session methods require app-server");
-          await this.hub.close(control.threadId); this.subscriptions.get(control)?.(); this.subscriptions.delete(control);
-          this.questionClients.get(control)?.(); this.questionClients.delete(control);
-          result = { closed: true }; break;
-        }
-        case "thread/mode": {
-          if (!control.configureWorkflow) throw Error("workflow changes are unavailable for this session");
-          await control.configureWorkflow(params["mode"] as "build" | "plan"); result = await control.snapshot(); break;
-        }
-        case "thread/read": result = await control.snapshot(); break;
-        case "thread/subscribe": {
-          if (!this.questionClients.has(control)) this.questionClients.set(control, control.attachQuestionClient());
-          if (this.hub) {
-            if (!this.subscriptions.has(control)) this.subscriptions.set(control, control.subscribe(notice => { if (!this.closed) this.write(notice); }));
-          } else this.subscribed = true;
-          const snapshot = await control.snapshot();
-          const after = params["after"] as { streamId: string; sequence: number } | undefined;
-          result = { snapshot, resyncRequired: after !== undefined && (after.streamId !== snapshot.streamId || after.sequence !== snapshot.sequence) };
-          break;
-        }
-        case "turn/start": result = { turnId: control.start(String(params["input"])) }; break;
-        case "turn/steer": control.steer(String(params["turnId"]), String(params["input"])); result = { queued: true }; break;
-        case "turn/interrupt": control.interrupt(String(params["turnId"])); result = { interruptRequested: true }; break;
-        case "approval/respond": control.respond(String(params["turnId"]), String(params["approvalId"]), params["choice"] as ApprovalChoice); result = { accepted: true }; break;
-        case "question/respond": control.respondQuestion(String(params["turnId"]), String(params["requestId"]), JSON.parse(String(params["reply"]))); result = { accepted: true }; break;
-        case "acceptance/accept": await control.accept(String(params["requestId"]), String(params["criterionId"])); result = { accepted: true }; break;
-        case "context/read": {
-          const snapshot = await control.snapshot(false), all = selectLens(snapshot.context, params["focus"] as LensFocus);
-          const offset = Number(params["offset"] ?? 0), limit = Number(params["limit"] ?? 50);
-          result = { node: snapshot.node, streamId: snapshot.streamId, sequence: snapshot.sequence, focus: params["focus"], total: all.length,
-            entries: all.slice(offset, offset + limit), nextOffset: offset + limit < all.length ? offset + limit : null,
-            components: snapshot.context.components, used: snapshot.context.used, countKind: snapshot.context.countKind };
-          break;
-        }
-        case "item/list": {
-          const all = await control.items(), after = params["after"] as { node: number; event: string } | undefined;
-          const index = after ? all.findIndex(item => item.node === after.node && item.event.id === after.event) : -1;
-          if (after && index < 0) throw Error("cursor is not on the current path; refresh the snapshot");
-          const entries = all.slice(index + 1, index + 1 + Number(params["limit"] ?? 50));
-          const last = entries.at(-1);
-          result = { items: entries.map(item => ({ node: item.node, id: item.event.id, type: item.event.t })),
-            nextCursor: last && index + 1 + entries.length < all.length ? { node: last.node, event: last.event.id } : null };
-          break;
-        }
-        case "item/read": {
-          const item = (await control.items()).find(item => item.node === params["node"] && item.event.id === params["event"]);
-          if (!item) throw Error("item is not on the current path");
-          result = item; break;
-        }
-        default: assertNever(request.method, "control request");
-      }
-      if (!this.closed) this.write({ id, result });
-    } catch (error) {
-      if (!this.closed) this.write({ id, error: { code: error instanceof ControlProtocolError ? error.code : -32000,
-        message: error instanceof Error ? error.message.slice(0, 512) : "control request failed" } });
-    }
-  }
-  close(): void {
-    this.closed = true; this.stop?.();
-    for (const stop of this.subscriptions.values()) stop(); this.subscriptions.clear();
-    for (const stop of this.questionClients.values()) stop(); this.questionClients.clear();
-    if (this.denyOnClose && this.attached) {
-      this.attached.denyApprovals();
-      if (this.attached.activeTurnId) this.attached.interrupt(this.attached.activeTurnId);
-    }
-  }
-}

package/src/runtime/counter-check.ts

@@ -1,74 +0,0 @@
-/**
- * Counter-checks: the discriminating rung of the evidence ladder (S.1).
- *
- * A check that passed is run once more against the workspace with this
- * request's changes undone. If it still passes, it did not test the change --
- * unless it is a guard, which must still pass there (S.7). That is the harness
- * applying to the agent the rule verify-red applies to every card: "a test
- * that cannot fail proves nothing". This module only runs the checks and
- * reports their exit codes; what an exit code means for a criterion of a
- * given role is decided in core (`counterVerdict`).
- *
- * Three rules keep the verdict honest:
- * - Only commands that already ran and passed in this request are re-run --
- *   checks the user accepted -- and only in a disposable clone.
- * - The clone must be reverted exactly: after undoing the request's changes
- *   its source fingerprint must equal the baseline recorded when the request
- *   began. The undo comes from a snapshot taken at the start when there is
- *   one, else from the journal; a change neither recorded (a shell command
- *   writing files without a checkpoint, with no snapshot) cannot be undone,
- *   so nothing runs and the result is unavailable rather than a guess.
- * - The real workspace is never written.
- */
-import { join, relative } from "node:path";
-import { changedPaths, planFileTransition, type CheckpointEvent, type FileChanges } from "../core/checkpoints.ts";
-import type { LogEvent } from "../core/events.ts";
-import { applyFileChanges } from "../store/file-checkpoints.ts";
-import { observeCommand } from "../store/command.ts";
-import { observeWorkspace } from "../store/workspace-observation.ts";
-import { cloneWorkspace } from "../store/workspace-clone.ts";
-
-export type CounterCheckInput = {
-  root: string; blobs: string; ownedPaths: readonly string[];
-  /** The request's events, in order. */
-  events: readonly LogEvent[];
-  /**
-   * The exact transition back to the request's starting state, when the
-   * caller took a snapshot at the start (fix-counter-check-own-baseline). It
-   * covers changes a shell command made. Absent: the request's journaled
-   * file changes are undone instead.
-   */
-  revert?: FileChanges;
-  checks: readonly { id: string; command: string; guard?: true }[];
-  timeoutMs: number; maxOutputBytes: number; outputStore: string; signal?: AbortSignal;
-};
-export type CounterCheckResult = { id: string; command: string; guard?: true } & ({ exit: number } | { reason: string });
-
-export async function counterCheck(input: CounterCheckInput): Promise<CounterCheckResult[]> {
-  const unavailable = (reason: string): CounterCheckResult[] => input.checks.map(check => ({ ...check, reason }));
-  if (input.checks.length === 0) return [];
-  const baseline = input.events.findLast(event => event.t === "workspace_observation" && event.baseline === true);
-  if (baseline?.t !== "workspace_observation" || baseline.fingerprint === undefined) return unavailable("no workspace baseline was recorded when this request began");
-  const applied = input.events.filter((event): event is CheckpointEvent => event.t === "checkpoint" && event.phase === "applied");
-  // Undoing every applied change of this request and replaying none is the journal's revert.
-  const revert = input.revert ?? planFileTransition(applied, []);
-  if (changedPaths(revert).length === 0) return unavailable("this request recorded no file changes to undo");
-  const clone = await cloneWorkspace(input.root, input.signal);
-  if (!clone.ok) return unavailable(clone.reason);
-  try {
-    try { await applyFileChanges(clone.path, input.blobs, revert, input.signal); }
-    catch (error) { return unavailable(`the recorded changes could not be undone: ${error instanceof Error ? error.message : String(error)}`); }
-    const owned = input.ownedPaths.map(path => { const rel = relative(input.root, path); return rel.startsWith("..") ? path : join(clone.path, rel); });
-    const observed = await observeWorkspace(clone.path, input.signal, owned);
-    if (!observed.ok) return unavailable(`the reverted copy could not be observed: ${observed.reason}`);
-    if (observed.fingerprint !== baseline.fingerprint) return unavailable(input.revert ? "the request's starting state could not be rebuilt exactly"
-      : "some changes were made outside tracked edits, so the request's starting state could not be rebuilt");
-    const results: CounterCheckResult[] = [];
-    for (const check of input.checks) {
-      const captured = await observeCommand({ command: check.command, cwd: clone.path, outputStore: input.outputStore,
-        maxOutputBytes: input.maxOutputBytes, timeoutMs: input.timeoutMs, ...(input.signal ? { signal: input.signal } : {}) });
-      results.push(captured.stopped ? { ...check, reason: `the check did not finish in the reverted copy (${captured.stopped})` } : { ...check, exit: captured.exit });
-    }
-    return results;
-  } finally { await clone.dispose(); }
-}

package/src/runtime/environment-tools.ts

@@ -1,60 +0,0 @@
-/** R6: observe through the same shell and process owner; never infer versions from the host PATH. */
-import { createHash } from "node:crypto";
-import { hostname } from "node:os";
-import { join, resolve } from "node:path";
-import { ENVIRONMENT_OUTPUT_BYTES, ENVIRONMENT_PARSE_BYTES, ENVIRONMENT_TIMEOUT_MS, ENVIRONMENT_TTL_MS,
-  environmentCapability, parseEnvironmentFrame, type EnvironmentProbe, type EnvironmentReceipt, type EnvironmentSource } from "../core/environment.ts";
-import { executionOutcome } from "../core/outcome.ts";
-import { canonicalValue } from "../core/continuation.ts";
-import { failureDiagnostic } from "../core/tool-failure.ts";
-import { observeCommand } from "../store/command.ts";
-import type { ToolContext, ToolResult } from "./tools.ts";
-
-const hash = (text: string) => createHash("sha256").update(text).digest("hex");
-/** Hash only resolution-related inherited inputs; never expose the full environment or its credentials. */
-export function environmentSource(ctx: Pick<ToolContext, "root" | "hostId">, cwd: string): EnvironmentSource {
-  const keys = ["PATH", "HOME", "SHELL", "LANG", "BASH_ENV", "PYTHONHOME", "PYTHONPATH", "PYENV_VERSION", "VIRTUAL_ENV", "CONDA_PREFIX", "NVM_BIN"];
-  return { host: ctx.hostId ?? hostname(), workspace: resolve(ctx.root), cwd: resolve(cwd),
-    runtime: `bun/${Bun.version};${process.platform}/${process.arch};${process.execPath}`,
-    inherited_sha256: hash(canonicalValue(Object.fromEntries(keys.map(key => [key, process.env[key] ?? null])))) };
-}
-
-export async function observeEnvironment(ctx: ToolContext, cwd: string, program: string, probe: EnvironmentProbe, command: string): Promise<ToolResult> {
-  const budget = new AbortController();
-  const signal = ctx.signal ? AbortSignal.any([ctx.signal, budget.signal]) : budget.signal;
-  let outputBytes = 0;
-  const source = environmentSource(ctx, cwd);
-  const captured = await observeCommand({ command, cwd, cleanupOnExit: true, outputLimitBytes: ENVIRONMENT_OUTPUT_BYTES,
-    outputStore: ctx.outputStore ?? join(ctx.root, ".xeno", "observations"),
-    maxOutputBytes: ENVIRONMENT_PARSE_BYTES, timeoutMs: Math.min(ENVIRONMENT_TIMEOUT_MS, ctx.timeoutMs, ctx.maxTimeoutMs ?? Infinity), signal,
-    onOutput: chunk => {
-      outputBytes += chunk.byteLength;
-      if (outputBytes > ENVIRONMENT_OUTPUT_BYTES) budget.abort();
-      ctx.onOutput?.(chunk);
-    },
-  });
-  const outputLimited = budget.signal.aborted;
-  const parseLimited = captured.ref.bytes > ENVIRONMENT_PARSE_BYTES;
-  const frame = parseEnvironmentFrame(new TextDecoder().decode(captured.head), program, probe);
-  const capability = captured.cleanup ? { state: "unknown" as const, reported_version: null, reason: captured.cleanup.message } : environmentCapability(frame, captured.exit, { complete: captured.capture === "complete",
-    ...(captured.stopped ? { stopped: captured.stopped } : {}),
-    ...(outputLimited ? { limited: "output" } : parseLimited ? { limited: "parse" } : {}) });
-  const observedAt = Date.now();
-  const receipt: EnvironmentReceipt = { kind: "environment", version: 1, query: { program, probe }, source,
-    observed_at: observedAt, expires_at: observedAt + ENVIRONMENT_TTL_MS, ...capability,
-    shell: frame ? { executable: frame.shell, version: frame.shell_version, cwd: frame.cwd, path_sha256: hash(frame.path) } : null,
-    resolution: frame ? { kind: frame.kind, executable: frame.executable } : null,
-    evidence: { output: captured.ref, exit: captured.exit, complete: captured.capture === "complete" } };
-  const status = outputLimited ? "tool_failed" : captured.stopped ?? (capability.state === "observed" ? "tool_completed" : "tool_failed");
-  const code = outputLimited ? "execution_failed" : captured.stopped ?? (capability.state === "missing" ? "environment_missing" : "execution_failed");
-  const text = JSON.stringify(receipt);
-  const bytes = new TextEncoder().encode(text);
-  // Raw output is the primary artifact. Structured data is separately preserved by the Session broker.
-  const content = bytes.length <= ctx.maxOutputBytes ? text :
-    `environment ${receipt.state}; exit ${captured.exit}; full receipt in data; original output: ${captured.ref.sha256}`;
-  return { ok: capability.state === "observed", content, content_ref: captured.ref, data: receipt,
-    ...(captured.cleanup ? { warnings: [captured.cleanup] } : {}),
-    observation_sha256: hash(canonicalValue({ query: receipt.query, source, ...capability, shell: receipt.shell, resolution: receipt.resolution, evidence: receipt.evidence })),
-    effect: { kind: "command", cmd: command, exit: captured.exit }, outcome: executionOutcome(status),
-    ...(capability.state === "observed" ? {} : { diagnostic: failureDiagnostic(code, capability.reason ?? "capability unconfirmed", { execution: "started", effects: "possible" }) }) };
-}

package/src/runtime/evidence-notes.ts

@@ -1,35 +0,0 @@
-/** O.6: resolve model associations against original observations in the active ancestry. */
-import type { EvidenceLinkEvent } from "../core/events.ts";
-import type { Handoff } from "../core/handoff.ts";
-import { historyEntries } from "../core/history-query.ts";
-import { observedVersion, resourceKey } from "../core/evidence-links.ts";
-import { scopedWorkId } from "../core/work-state.ts";
-import { readNodeHistory } from "../store/restore.ts";
-import { failureDiagnostic, NOT_STARTED, READ_ATTEMPTED } from "../core/tool-failure.ts";
-import type { ToolResult } from "./tools.ts";
-
-export async function resolveEvidenceNote(logDir: string, node: number, namespace: string, current: Handoff, event: EvidenceLinkEvent): Promise<{ event?: EvidenceLinkEvent; result: ToolResult }> {
-  const work = scopedWorkId(namespace, event.work, current.state.work_items ?? []);
-  const fail = (message: string, attempted = false) => ({ result: { ok: false, content: message, data: { recorded: false },
-    diagnostic: failureDiagnostic(attempted ? "execution_failed" : "invalid_input", message, attempted ? READ_ATTEMPTED : NOT_STARTED) } });
-  if (!current.state.work_items?.some(item => item.id === work)) return fail("pin requires an existing work item");
-  const history = await readNodeHistory(logDir, node);
-  if (!history.ok) return fail(history.error, true);
-  const entries = historyEntries(history.nodes);
-  const source = entries.find(entry => entry.event === event.source && entry.kind === "tool_result");
-  if (!source) return fail("pin source must be an original tool observation in the active ancestry");
-  const resource = event.resource === undefined ? source.resources?.[0] : resourceKey(event.resource);
-  if (resource !== undefined && !source.resources?.includes(resource)) return fail("pin resource must match the original observation");
-  if (event.supersedes && (event.supersedes === event.source || !current.evidence_links?.some(link =>
-    link.work === work && link.event === event.supersedes && link.superseded_by === undefined))) return fail("supersedes must name an active pinned source for this work item");
-  const events = history.nodes.flatMap(part => [...part.events]);
-  const observed = events.find(item => item.id === event.source);
-  const effect = observed?.t === "tool_result" ? observed.effect : undefined;
-  const version = effect && "path" in effect ? effect.kind === "read" ? effect.sha256 : effect.sha256_after : undefined;
-  const latest = resource === undefined ? undefined : observedVersion(events, resource);
-  const resolved: EvidenceLinkEvent = { ...event, work,
-    ...(resource !== undefined ? { resource } : {}), ...(version !== undefined ? { version } : {}),
-    ...(latest !== undefined ? { observed_version: latest } : {}) };
-  return { event: resolved, result: { ok: true, content: JSON.stringify({ recorded: true, work_id: work, source_event: source.event, source_node: source.node,
-    resource: resource ?? null, instruction: "This links observed evidence; completion still requires verification." }) } };
-}