@visual-z/xeno 0.2.0 → 0.3.0

package/src/core/version.ts

@@ -0,0 +1,55 @@
+/**
+ * Semantic version comparison (semver.org §11), without a dependency. Pure.
+ *
+ * Used to decide whether a published version is newer than the running one
+ * (docs/tasks/feat-update-check.md). Anything that does not parse is not a
+ * version, and an unparseable version never produces an update notice.
+ */
+
+export interface Version {
+  readonly major: number;
+  readonly minor: number;
+  readonly patch: number;
+  /** Dot-separated pre-release identifiers; empty for a release. */
+  readonly prerelease: readonly (number | string)[];
+}
+
+const PATTERN = /^v?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+
+export function parseVersion(text: string): Version | null {
+  const match = PATTERN.exec(text.trim());
+  if (!match) return null;
+  const numbers = [match[1], match[2], match[3]].map(Number);
+  if (numbers.some(n => !Number.isSafeInteger(n))) return null;
+  const prerelease = match[4] ? match[4].split(".").map(part => /^\d+$/.test(part) ? Number(part) : part) : [];
+  return { major: numbers[0]!, minor: numbers[1]!, patch: numbers[2]!, prerelease };
+}
+
+/** -1, 0 or 1, by §11: numbers, then a release outranks its pre-releases, then identifiers left to right. Build metadata is ignored. */
+export function compareVersions(a: Version, b: Version): -1 | 0 | 1 {
+  for (const key of ["major", "minor", "patch"] as const) if (a[key] !== b[key]) return a[key] < b[key] ? -1 : 1;
+  const x = a.prerelease, y = b.prerelease;
+  if (!x.length || !y.length) return x.length === y.length ? 0 : x.length ? -1 : 1;
+  for (let i = 0; i < Math.min(x.length, y.length); i++) {
+    const p = x[i]!, q = y[i]!;
+    if (p === q) continue;
+    if (typeof p === "number" && typeof q === "number") return p < q ? -1 : 1;
+    // Numeric identifiers have lower precedence than alphanumeric ones.
+    if (typeof p === "number") return -1;
+    if (typeof q === "number") return 1;
+    return p < q ? -1 : 1;
+  }
+  return x.length === y.length ? 0 : x.length < y.length ? -1 : 1;
+}
+
+/**
+ * Whether `latest` should be offered to someone running `current`. Never a
+ * downgrade, never something unparseable, and a release is not nudged
+ * towards a pre-release (a pre-release user may move to the next release).
+ */
+export function isUpgrade(latest: string, current: string): boolean {
+  const next = parseVersion(latest), now = parseVersion(current);
+  if (!next || !now) return false;
+  if (next.prerelease.length && !now.prerelease.length) return false;
+  return compareVersions(next, now) > 0;
+}

package/src/core/work-state.ts

@@ -15,8 +15,35 @@ export type WorkItem = {
   evidence?: Evidence;
   /** Reopening keeps provenance without carrying a second copy of old proof. */
   previous_evidence?: string;
+  depends_on?: readonly string[];
+  owner?: string;
+  owner_event?: string;
 };
 
+export type WorkReadiness = { ready: boolean; reason: "ready" | "waiting" | "blocked" | "closed" | "owned" | "missing"; waiting_for: string[] };
+export function workReadiness(items: readonly WorkItem[], id: string, actor?: string): WorkReadiness {
+  const item = items.find(work => work.id === id);
+  if (!item) return { ready: false, reason: "missing", waiting_for: [id] };
+  if (item.status === "completed" || item.status === "cancelled") return { ready: false, reason: "closed", waiting_for: [] };
+  const waiting = (item.depends_on ?? []).filter(dep => items.find(work => work.id === dep)?.status !== "completed");
+  const reason = item.status === "blocked" ? "blocked" : waiting.length ? "waiting" : item.owner && item.owner !== actor ? "owned" : "ready";
+  return { ready: reason === "ready", reason, waiting_for: [...waiting] };
+}
+
+function dependencyError(items: readonly WorkItem[], id: string, dependencies: readonly string[]): string | null {
+  if (new Set(dependencies).size !== dependencies.length) return "duplicate work dependencies";
+  if (dependencies.includes(id)) return "work dependency cycle: self dependency";
+  if (dependencies.some(dep => !items.some(item => item.id === dep))) return "unknown work dependency";
+  const seen = new Set<string>(), pending = [...dependencies];
+  while (pending.length) {
+    const dep = pending.pop()!;
+    if (dep === id) return "work dependency cycle";
+    if (seen.has(dep)) continue;
+    seen.add(dep); pending.push(...items.find(item => item.id === dep)?.depends_on ?? []);
+  }
+  return null;
+}
+
 /** O.2: sibling sessions may choose the same local label without aliasing work. */
 export function scopedWorkId(namespace: string, requested: string, items: readonly WorkItem[]): string {
   return items.some(item => item.id === requested) || requested.startsWith(`${namespace}:`)
@@ -26,6 +53,18 @@ export function scopedWorkId(namespace: string, requested: string, items: readon
 export function workChangeError(items: readonly WorkItem[], event: LogEvent): string | null {
   if (!("work_id" in event) || event.work_id === undefined) return null;
   const item = items.find(item => item.id === event.work_id);
+  if ((event.t === "next_action" || event.t === "work_dependencies") && event.depends_on !== undefined) {
+    const error = dependencyError(items, event.work_id, event.depends_on);
+    if (error) return error;
+  }
+  if (event.t === "work_dependencies" && !item) return `unknown work_id ${event.work_id}`;
+  if (event.t === "work_owner") {
+    if (!item) return `unknown work_id ${event.work_id}`;
+    if (event.operation === "release") return item.owner === event.owner ? null : "only the recorded owner can release work";
+    const ready = workReadiness(items, item.id, event.owner);
+    return ready.ready ? null : `work ${item.id} is ${ready.reason}; cannot claim it`;
+  }
+  if (event.t === "claim" && item && (item.depends_on ?? []).some(dep => items.find(work => work.id === dep)?.status !== "completed")) return "work dependencies are not completed";
   if (event.t === "work_status") {
     // D15 carries post-fork instructions, not their whole history. A harness-
     // authenticated transition may seed intent in the adopted branch, never proof.
@@ -51,13 +90,19 @@ export function deriveWorkItems(previous: readonly WorkItem[], events: readonly
   const items = new Map(previous.map(item => [item.id, { ...item }]));
   for (let index = 0; index < events.length; index++) {
     const event = events[index]!;
-    if (!("work_id" in event) || event.work_id === undefined || workChangeError([...items.values()], event)) continue;
+    if ((event.t !== "next_action" && event.t !== "blocked" && event.t !== "work_status" && event.t !== "claim" && event.t !== "work_dependencies" && event.t !== "work_owner") ||
+        event.work_id === undefined || workChangeError([...items.values()], event)) continue;
     const old = items.get(event.work_id);
-    const item: WorkItem = old ? { ...old, what: event.what, updated_at: event.id } : {
+    const item: WorkItem = old ? { ...old, what: event.t === "work_owner" || event.t === "work_dependencies" ? old.what : event.what, updated_at: event.id } : {
       id: event.work_id, what: event.what, status: "active", verification: "not_run",
       opened_at: event.id, updated_at: event.id,
     };
-    if (event.t === "next_action") item.next_action = event.next_action;
+    if (event.t === "next_action") { item.next_action = event.next_action; if (event.depends_on !== undefined) item.depends_on = [...event.depends_on]; }
+    else if (event.t === "work_dependencies") item.depends_on = [...event.depends_on];
+    else if (event.t === "work_owner") {
+      if (event.operation === "claim") { item.owner = event.owner; item.owner_event = event.id; }
+      else { delete item.owner; delete item.owner_event; }
+    }
     else if (event.t === "blocked") {
       item.status = "blocked";
       item.reason = event.reason;
@@ -89,6 +134,7 @@ export function deriveWorkItems(previous: readonly WorkItem[], events: readonly
       } else { item.verification = "unverified"; item.reason = resolved.reason; }
     }
     items.set(item.id, item);
+    if (item.status === "completed" || item.status === "cancelled") { delete item.owner; delete item.owner_event; }
   }
   return [...items.values()].map(item => {
     if (!item.evidence) return item;

package/src/core/working-set.ts

@@ -0,0 +1,91 @@
+/** O.10: prioritize explicit intent and references without changing D20 arrays. */
+import type { Handoff } from "./handoff.ts";
+import type { NodeRef } from "./events.ts";
+import { workReadiness, type WorkItem, type WorkReadiness } from "./work-state.ts";
+import { emitYaml } from "./yaml.ts";
+import { estimateTokens } from "./tokens.ts";
+import { RECOVERY_SECTIONS, recoverySources, type RecoveryNodes, type RecoveryRanges, type RecoveryReference } from "./recovery-sources.ts";
+import { recoveryInstructions } from "./prompt-policy.ts";
+
+export type WorkingSet = {
+  version: 1 | 2; source: NodeRef;
+  work: (Pick<WorkItem, "id" | "what" | "status" | "next_action" | "reason" | "depends_on" | "owner"> & { readiness?: WorkReadiness })[];
+  references: ({ node?: number; event: string; kind: string; work?: string } & Partial<Omit<RecoveryReference, "node" | "event" | "kind" | "work">>)[];
+  omitted: { work: number; references: number };
+  recovery_sections?: RecoveryRanges;
+  recovery: string;
+};
+
+export function workingSet(full: Handoff, budget: number): WorkingSet | null {
+  if (!full.predecessor) return null;
+  const items = (full.state.work_items ?? []).filter(item => item.status === "blocked" || item.status === "active")
+    .toSorted((a, b) => Number(b.status === "blocked") - Number(a.status === "blocked") || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  const active = new Set(items.map(item => item.id));
+  const references: WorkingSet["references"] = [
+    ...(full.evidence_links ?? []).filter(link => active.has(link.work) && !link.superseded_by)
+      .map(link => ({ event: link.event, kind: "evidence", work: link.work })),
+    ...full.decisions.filter(item => item.work_id && active.has(item.work_id) && item.source)
+      .map(item => ({ node: item.source!.node, event: item.source!.event_id, kind: "decision", work: item.work_id! })),
+    ...full.pitfalls.filter(item => item.work_id && active.has(item.work_id) && item.source)
+      .map(item => ({ node: item.source!.node, event: item.source!.event_id, kind: "pitfall", work: item.work_id! })),
+    ...(full.progress_evidence ?? []).toReversed().map(item => ({ node: item.source.node, event: item.source.event_id, kind: item.kind })),
+  ];
+  const view: WorkingSet = { version: 1, source: full.predecessor, work: [], references: [],
+    omitted: { work: items.length, references: references.length }, recovery: "history(work_id=ID), history(event=ID), or history(node=source.node, section=...)" };
+  const fits = () => budget === Infinity || estimateTokens.count([], emitYaml(view)) <= budget;
+  if (!fits()) return null;
+  for (const item of items) {
+    const { id, what, status, next_action, reason, depends_on, owner } = item;
+    view.work.push({ id, what, status, ...(next_action ? { next_action } : {}), ...(reason ? { reason } : {}),
+      ...(depends_on ? { depends_on, readiness: workReadiness(full.state.work_items ?? [], id) } : {}), ...(owner ? { owner } : {}) });
+    view.omitted.work--;
+    if (!fits()) { view.work.pop(); view.omitted.work++; }
+  }
+  for (const reference of references) {
+    view.references.push(reference); view.omitted.references--;
+    if (!fits()) { view.references.pop(); view.omitted.references++; }
+  }
+  return view;
+}
+
+/** R9: a new projection version keeps the original v1 ordering byte-stable. */
+export function recoveryWorkingSet(full: Handoff, nodes: RecoveryNodes, budget: number, tools?: readonly string[]): WorkingSet | null {
+  const legacy = workingSet(full, Infinity);
+  if (!legacy) return null;
+  const sources = recoverySources(nodes);
+  const view: WorkingSet = { version: 2, source: legacy.source, work: [], references: [],
+    omitted: { work: legacy.work.length, references: legacy.references.length + RECOVERY_SECTIONS.reduce((sum, section) => sum + sources[section].length, 0) },
+    recovery_sections: Object.fromEntries(RECOVERY_SECTIONS.map(section => [section, { total: sources[section].length, omitted: sources[section].length }])) as RecoveryRanges,
+    recovery: tools === undefined ? "Read original user messages before continuing: history(node=source.node,recovery=users,offset=0). Other pages: failures, environment, next_actions; event=ID reads one original. Abandoned messages are cancelled; annotations are not user instructions. Observations are historical: recheck resource, host and current permissions before acting. history(work_id=ID) recovers work." : recoveryInstructions(tools) };
+  const fits = () => estimateTokens.count([], emitYaml(view)) <= budget;
+  if (!fits()) return null;
+  const queues = RECOVERY_SECTIONS.map(section => ({ section, items: [...sources[section]], at: 0 }));
+  // The latest and first live user messages anchor correction and initial scope;
+  // remaining user sources are newest first. Cancelled turns stay pageable.
+  const live = sources.users.filter(ref => !ref.abandoned), first = live.at(-1);
+  queues[0]!.items = [...live.slice(0, 1), ...(first && first !== live[0] ? [first] : []),
+    ...live.slice(1, -1), ...sources.users.filter(ref => ref.abandoned)];
+  const takeReference = (reference: WorkingSet["references"][number], section?: keyof RecoveryRanges) => {
+    view.references.push(reference); view.omitted.references--;
+    if (section) view.recovery_sections![section].omitted--;
+    if (!fits()) {
+      view.references.pop(); view.omitted.references++;
+      if (section) view.recovery_sections![section].omitted++;
+    }
+  };
+  // One source per role precedes work prose; round-robin growth thereafter
+  // prevents a long task list or repeated failures starving other categories.
+  for (const queue of queues) { const reference = queue.items[queue.at++]; if (reference) takeReference(reference, queue.section); }
+  let at = 0;
+  while (at < legacy.work.length || at < legacy.references.length || queues.some(queue => queue.at < queue.items.length)) {
+    const work = legacy.work[at];
+    if (work) {
+      view.work.push(work); view.omitted.work--;
+      if (!fits()) { view.work.pop(); view.omitted.work++; }
+    }
+    for (const queue of queues) { const reference = queue.items[queue.at++]; if (reference) takeReference(reference, queue.section); }
+    const reference = legacy.references[at++];
+    if (reference) takeReference(reference);
+  }
+  return view;
+}

package/src/runtime/auth.ts

@@ -304,8 +304,8 @@ export function envLabel(provider: string): string {
  */
 export function describeMissingCredential(provider: string): string {
   return (
-    `no credential for ${provider}. Either export ${envLabel(provider)}, ` +
-    `or run /login ${provider} to store one in ~/.xeno/auth.json`
+    `no credential for ${provider}. Run /login ${provider} to add a key, ` +
+    `or export ${envLabel(provider)}`
   );
 }
 

package/src/runtime/branch-jobs.ts

@@ -0,0 +1,36 @@
+/** O.14: volatile ownership, never a replacement for the durable branch log. */
+export class BranchJobs<T> {
+  private readonly jobs = new Map<number, { controller: AbortController; done: Promise<void>; value?: T; error?: string; detach(): void; ready: boolean }>();
+
+  get active(): number { return [...this.jobs.values()].filter(job => !job.ready).length; }
+  state(node: number): "running" | "ready" | undefined {
+    const job = this.jobs.get(node); return job ? job.ready ? "ready" : "running" : undefined;
+  }
+  nodes(): number[] { return [...this.jobs.keys()]; }
+  start(node: number, controller: AbortController, run: () => Promise<T>, detach: () => void): void {
+    if (this.jobs.has(node)) throw new Error("branch already owned");
+    const job: { controller: AbortController; done: Promise<void>; value?: T; error?: string; detach(): void; ready: boolean } = {
+      controller, ready: false, detach, done: Promise.resolve(),
+    };
+    this.jobs.set(node, job);
+    job.done = run().then(value => { job.value = value; }, () => { job.error = "branch finalization failed; inspect its original log"; })
+      .finally(() => { job.ready = true; job.detach(); });
+  }
+  cancel(node?: number): void {
+    for (const [id, job] of this.jobs) if (node === undefined || node === id) job.controller.abort();
+  }
+  async drain(node?: number): Promise<void> { await Promise.all([...this.jobs].filter(([id]) => node === undefined || node === id).map(([, job]) => job.done)); }
+  async wait(node: number, ms: number): Promise<{ value?: T; error?: string; running: boolean } | undefined> {
+    const job = this.jobs.get(node); if (!job) return undefined;
+    if (!Number.isFinite(ms) || ms < 0 || ms > 60_000) throw new RangeError("wait_ms must be between 0 and 60000");
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    try {
+      if (!job.ready && ms > 0) await Promise.race([job.done, new Promise<void>(resolve => { timer = setTimeout(resolve, ms); })]);
+    } finally { clearTimeout(timer); }
+    return { ...(job.value !== undefined ? { value: job.value } : {}), ...(job.error ? { error: job.error } : {}), running: !job.ready };
+  }
+  forget(node: number): void {
+    if (this.state(node) === "running") throw new Error("cannot forget a running branch");
+    this.jobs.delete(node);
+  }
+}

package/src/runtime/clipboard.ts

@@ -1,6 +1,17 @@
-/** Pi's files → image → text precedence, with native-helper and OS-command fallbacks (MIT, 02eed88). */
+/**
+ * Pi's files → image → text precedence (MIT, 02eed88) over the platform's own
+ * clipboard commands. The optional native helper went with the vendored TUI
+ * (D20); a caller may still inject one.
+ */
 import { fileURLToPath } from "node:url";
-import { getNativeClipboard, type NativeClipboard } from "../vendor/pi-tui/native-platform.ts";
+
+export interface NativeClipboard {
+  setText?(text: string): Promise<void>;
+  getText?(): Promise<string | null | undefined>;
+  getImage?(): Promise<Uint8Array | null | undefined>;
+  getFilePaths?(): Promise<string[] | null | undefined>;
+}
+function getNativeClipboard(): NativeClipboard | null { return null; }
 import { runClipboardCommand } from "../vendor/pi-rich/clipboard-command.ts";
 
 export type ClipboardContent = { files: string[] } | { image: Uint8Array } | { text: string } | null;
@@ -104,9 +115,9 @@ export async function readClipboard(options: ClipboardOptions = {}): Promise<Cli
       return bytes.length ? { text: bytes.toString("utf8") } : null;
     }
   }
-  const image = await native?.getImage();
+  const image = await native?.getImage?.();
   if (image?.length) return { image };
-  const text = await native?.getText();
+  const text = await native?.getText?.();
   if (text !== undefined) return text ? { text } : null;
   const fallback = env["TERMUX_VERSION"] ? await run("termux-clipboard-get", []) : platform === "darwin" ? await run("pbpaste", []) : undefined;
   if (fallback === undefined) throw new Error("Clipboard unavailable for this terminal session");

package/src/runtime/command-artifacts.ts

@@ -0,0 +1,64 @@
+/** R8: one owner observes an admitted command once, including after a managed call yields. */
+import { hostname } from "node:os";
+import { resolve, join } from "node:path";
+import { artifactChange, commandArtifactState, parseCommandArtifactPlan, COMMAND_ARTIFACT_SCOPE, type CommandArtifactReceipt } from "../core/command-artifacts.ts";
+import { observeArtifactInputs, observeArtifactFiles, artifactExclusions, archiveCommandArtifacts } from "../store/command-artifacts.ts";
+import type { ToolContext } from "./tools.ts";
+
+export type ArtifactCommandEnd = { exit: number; stopped?: "cancelled" | "timeout"; capture?: "complete" | "partial"; cleanup?: unknown };
+export type CommandArtifactObserver = {
+  pending: CommandArtifactReceipt;
+  finish(end: ArtifactCommandEnd): Promise<CommandArtifactReceipt>;
+};
+
+/** Syntactic validation precedes admission; no preflight disk probing is smuggled through a denied tool. */
+export function prepareArtifactArguments(input: unknown): unknown {
+  if (input === null || typeof input !== "object" || Array.isArray(input) || !("artifacts" in input)) return input;
+  return { ...input, artifacts: parseCommandArtifactPlan(input.artifacts) };
+}
+
+export async function beginCommandArtifacts(ctx: Pick<ToolContext, "root" | "hostId" | "ownedStatePaths" | "outputStore" | "signal">,
+  command: string, cwd: string, requested: unknown): Promise<CommandArtifactObserver | undefined> {
+  if (requested === undefined) return undefined;
+  const plan = parseCommandArtifactPlan(requested), exclusions = artifactExclusions(ctx.root, plan,
+    [...(ctx.ownedStatePaths ?? []), ctx.outputStore ?? join(ctx.root, ".xeno", "observations")]);
+  const beforeInputs = await observeArtifactInputs(ctx.root, exclusions, ctx.signal);
+  const before = await observeArtifactFiles(ctx.root, plan.paths, ctx.signal);
+  const pending: CommandArtifactReceipt = {
+    kind: "command_artifacts", version: 1, state: "pending", plan,
+    source: { host: ctx.hostId ?? hostname(), workspace: resolve(ctx.root), cwd: resolve(cwd), runtime: `bun/${Bun.version}` },
+    command, exit: null, started_at: new Date().toISOString(), observed_at: null,
+    inputs: { scope: COMMAND_ARTIFACT_SCOPE, exclusions, before: beforeInputs.sha256, after: null },
+    outputs: [], reasons: beforeInputs.reason ? [beforeInputs.reason] : [],
+  };
+  let completed: Promise<CommandArtifactReceipt> | undefined;
+  return { pending, finish(end) {
+    completed ??= (async () => {
+      // Observation failures retain the actual exit. Never retry a post-exit read against later files.
+      const reasons = [...pending.reasons];
+      if (end.exit !== 0) reasons.push("command exited unsuccessfully");
+      if (end.stopped) reasons.push(`command ${end.stopped}`);
+      if (end.capture === "partial") reasons.push("command output capture is partial");
+      if (end.cleanup) reasons.push("command cleanup is unconfirmed");
+      const after = await observeArtifactFiles(ctx.root, plan.paths, ctx.signal);
+      const afterInputs = await observeArtifactInputs(ctx.root, exclusions, ctx.signal);
+      if (afterInputs.reason) reasons.push(afterInputs.reason);
+      const receipt: CommandArtifactReceipt = { ...pending, exit: end.exit, observed_at: new Date().toISOString(),
+        inputs: { ...pending.inputs, after: afterInputs.sha256 },
+        outputs: plan.paths.map((path, i) => ({ path, before: before[i]!, after: after[i]!, change: artifactChange(before[i]!, after[i]!) })), reasons };
+      receipt.state = commandArtifactState(receipt);
+      try { receipt.manifest = await archiveCommandArtifacts(ctx.outputStore ?? join(ctx.root, ".xeno", "observations"), receipt); }
+      catch { receipt.reasons.push("artifact observation archive unavailable"); receipt.state = commandArtifactState(receipt); }
+      return receipt;
+    })();
+    return completed;
+  } };
+}
+
+export function commandArtifactSummary(receipt: CommandArtifactReceipt | undefined): string {
+  if (!receipt) return "";
+  const changes = ["created", "modified", "unchanged", "unknown"].map(change => `${change}=${receipt.outputs.filter(output => output.change === change).length}`).join(", ");
+  return `\n[artifacts ${receipt.state}; ${changes}; reasons=${receipt.reasons.length}; ` +
+    (receipt.manifest ? `history artifact=${receipt.manifest.sha256}; ` : "") +
+    "command association only, not build causality or runtime acceptance]";
+}

package/src/runtime/environment-tools.ts

@@ -0,0 +1,60 @@
+/** 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

@@ -5,14 +5,16 @@ 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) => ({ result: { ok: false, content: message } });
+  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);
+  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");