@visual-z/xeno 0.2.1 → 0.3.0

package/src/runtime/trial-control.ts

@@ -0,0 +1,45 @@
+/** Q.14: an explicit signal owner records the first interruption independent of exception paths. */
+import type { TrialInterruption, TrialLifecycle } from "../core/trial-lifecycle.ts";
+
+/** A bad deadline must not strand the gateway acquired immediately before its clock starts. */
+export async function openTrialControl(timeoutMs:number,caller:AbortSignal|undefined,disposeOnFailure:()=>Promise<void>):Promise<TrialControl> {
+  try {return new TrialControl(timeoutMs,caller);}
+  catch(error){await disposeOnFailure();throw error;}
+}
+
+export class TrialControl {
+  private readonly controller=new AbortController();
+  readonly signal=this.controller.signal;
+  private readonly deadline:AbortSignal;
+  private readonly caller:AbortSignal|undefined;
+  private phase:TrialInterruption["phase"]="initialization";
+  private requests=0;
+  private interrupted:TrialInterruption|null=null;
+  private active=true;
+  private readonly onDeadline=()=>this.stop("deadline");
+  private readonly onCaller=()=>this.stop("caller");
+  constructor(timeoutMs:number,caller?:AbortSignal) {
+    this.deadline=AbortSignal.timeout(timeoutMs);this.caller=caller;
+    this.deadline.addEventListener("abort",this.onDeadline,{once:true});
+    caller?.addEventListener("abort",this.onCaller,{once:true});
+    // An already-cancelled caller precedes the newly-created local deadline.
+    if(caller?.aborted)this.onCaller();else if(this.deadline.aborted)this.onDeadline();
+  }
+  private stop(source:TrialInterruption["source"]):void {
+    if(!this.active||this.interrupted)return;
+    this.interrupted={source,phase:this.phase,backendRequests:this.requests};
+    this.controller.abort();
+  }
+  enterExecution():void {this.phase="execution";}
+  beginBackend():void {
+    if(!this.active||this.signal.aborted)throw Error("trial no longer accepts backend requests");
+    this.requests++;
+  }
+  finishWork():void {
+    this.active=false;
+    this.deadline.removeEventListener("abort",this.onDeadline);this.caller?.removeEventListener("abort",this.onCaller);
+  }
+  observe(cleanup:TrialLifecycle["cleanup"]):TrialLifecycle {
+    return {version:1,backendRequests:this.requests,interruption:this.interrupted?{...this.interrupted}:null,cleanup};
+  }
+}

package/src/runtime/update-check.ts

@@ -0,0 +1,47 @@
+/**
+ * Ask the npm registry for the newest published xeno (docs/tasks/feat-update-check.md).
+ *
+ * One small GET (the dist-tags document is about 20 bytes) with a 3-second
+ * timeout, falling back to the package's `latest` document. It carries
+ * Bun's default User-Agent and nothing that identifies the person: the
+ * registry sees an IP address, the time and the package name. Failure of
+ * any kind is "no answer"; it never reaches the screen as an error.
+ */
+import { distTagsUrl } from "../core/update-check.ts";
+
+/** How long to wait for the registry. Codex and pi wait longer; startup never waits on it anyway. Assumed. */
+export const UPDATE_TIMEOUT_MS = 3000;
+
+type Fetch = (input: string, init?: RequestInit) => Promise<Response>;
+
+export interface LatestVersionOptions {
+  /**
+   * Ends the request early. The interactive app aborts it on close: an open
+   * socket keeps the process alive, so quitting would otherwise wait out the
+   * timeout (feat-update-check DoD 3).
+   */
+  readonly signal?: AbortSignal;
+  readonly fetcher?: Fetch;
+  readonly timeoutMs?: number;
+}
+
+export async function fetchLatestVersion(registry: string | undefined, options: LatestVersionOptions = {}): Promise<string | null> {
+  const fetcher = options.fetcher ?? ((input, init) => fetch(input, init));
+  const timeout = AbortSignal.timeout(options.timeoutMs ?? UPDATE_TIMEOUT_MS);
+  const signal = options.signal ? AbortSignal.any([options.signal, timeout]) : timeout;
+  const tags = distTagsUrl(registry);
+  const attempts: [string, (body: Record<string, unknown>) => unknown][] = [
+    [tags, body => body["latest"]],
+    // Mirrors that do not serve dist-tags still serve the package's latest document.
+    [tags.replace(/\/-\/package\/([^/]+)\/dist-tags$/, "/$1/latest"), body => body["version"]],
+  ];
+  for (const [url, pick] of attempts) {
+    try {
+      const response = await fetcher(url, { signal, headers: { accept: "application/json" } });
+      if (!response.ok) continue;
+      const value = pick(await response.json() as Record<string, unknown>);
+      if (typeof value === "string" && value.length <= 64) return value;
+    } catch { if (signal.aborted) return null; }
+  }
+  return null;
+}

package/src/runtime/window-trial.ts

@@ -111,7 +111,8 @@ export async function runWindowTrial(options: {
       row.lastEvent = events.at(-1)?.id ?? null;
       row.fullPageRead = events.some(event => event.t === "tool_result" && event.ok && event.effect?.kind === "read" &&
         event.effect.path === page.path && event.effect.sha256 === sha(page.body) && event.effect.ranges?.some(range => range[0] === 1 && range[1] === page.body.split("\n").length) &&
-        event.content_ref === undefined && event.content.includes(page.body.split("\n").at(-1)!));
+        // Archival is independent of truncation. Verify what the model actually received, including the middle.
+        event.content.includes(page.body.split("\n").map((line, index) => `${index + 1}\t${line}`).join("\n")));
       for (const prior of options.fixture.pages.slice(0, stage + 1)) {
         const content = await readFile(join(workspace, prior.path), "utf8").catch(() => null);
         row.inputs[prior.path] = content === null ? null : sha(content);

package/src/runtime/working-notes.ts

@@ -2,14 +2,28 @@
 import type { LogEvent } from "../core/events.ts";
 import { deriveHandoff } from "../core/derive.ts";
 import { scopedWorkId, workChangeError } from "../core/work-state.ts";
+import { resolveEvidence, type EvidenceResolution } from "../core/evidence.ts";
+import { unknownWorkClaimDiagnostic, unverifiedNoteDiagnostic } from "../core/note-guidance.ts";
+import { failureDiagnostic, NOT_STARTED } from "../core/tool-failure.ts";
+import type { ToolDiagnostic } from "../core/tool-contract.ts";
 import { replayContext } from "../store/replay.ts";
 import { digestNode, nodePath } from "../store/log.ts";
 import { resolveEvidenceNote } from "./evidence-notes.ts";
 import type { ToolResult } from "./tools.ts";
 
+function rejected(message: string, diagnostic = failureDiagnostic("invalid_input", message, NOT_STARTED)): { out: ToolResult } {
+  return { out: { ok: false, content: message, data: { recorded: false }, diagnostic } };
+}
+function claimResult(annotation: Extract<LogEvent, { t: "claim" }>, proof: EvidenceResolution, openedAt?: string): ToolResult {
+  const diagnostic: ToolDiagnostic | undefined = proof.ok ? undefined : unverifiedNoteDiagnostic(proof, annotation.id, openedAt);
+  return { ok: proof.ok, content: JSON.stringify({ recorded: true, claim_event: annotation.id,
+    verification: proof.ok ? "verified" : "unverified", ...(proof.ok ? { evidence: proof.evidence } : { reason: proof.reason }) }),
+    ...(diagnostic ? { diagnostic } : {}) };
+}
+
 export async function prepareWorkingNote(logDir: string, node: number, namespace: string, annotation: LogEvent | undefined, out: ToolResult): Promise<{ out: ToolResult; annotation?: LogEvent }> {
   if (!annotation) return { out };
-  if (annotation.t !== "evidence_link" && !("work_id" in annotation && annotation.work_id !== undefined)) return { out, annotation };
+  if (annotation.t !== "claim" && annotation.t !== "evidence_link" && !("work_id" in annotation && annotation.work_id !== undefined)) return { out, annotation };
   const replayed = await replayContext(logDir, node);
   const input = { prev: replayed.fullHandoff, events: replayed.events, depth: replayed.depth,
     self: { node, log_ref: nodePath(logDir, node), sha256: await digestNode(logDir, node) } };
@@ -18,13 +32,29 @@ export async function prepareWorkingNote(logDir: string, node: number, namespace
     const resolved = await resolveEvidenceNote(logDir, node, namespace, current, annotation);
     return { out: resolved.result, ...(resolved.event ? { annotation: resolved.event } : {}) };
   }
+  if (annotation.t === "claim" && annotation.work_id === undefined) {
+    return { annotation, out: claimResult(annotation, resolveEvidence(input.events, annotation.evidence)) };
+  }
   if (!("work_id" in annotation) || annotation.work_id === undefined) throw new Error("missing identified work annotation");
   const workId = scopedWorkId(namespace, annotation.work_id, current.state.work_items ?? []);
   annotation = { ...annotation, work_id: workId };
+  const owned = current.state.work_items?.find(item => item.id === workId);
+  if (owned?.owner && owned.owner !== namespace) return rejected(`work ${workId} is owned by ${owned.owner}`);
+  if ((annotation.t === "next_action" || annotation.t === "work_dependencies") && annotation.depends_on !== undefined) annotation = {
+    ...annotation, depends_on: annotation.depends_on.map(id => scopedWorkId(namespace, id, current.state.work_items ?? [])),
+  };
+  if ((annotation.t === "decision" || annotation.t === "pitfall") && !current.state.work_items?.some(item => item.id === workId)) {
+    return rejected(`unknown work_id ${workId}; record a next note first`);
+  }
+  if (!owned && annotation.t === "claim") {
+    const diagnostic = unknownWorkClaimDiagnostic(input.events, annotation);
+    return rejected(diagnostic.message, diagnostic);
+  }
   const error = workChangeError(current.state.work_items ?? [], annotation);
-  if (error) return { out: { ok: false, content: error } };
+  if (error) return rejected(error);
   const proposed = deriveHandoff({ ...input, events: [...input.events, annotation] });
   const item = proposed.state.work_items?.find(item => item.id === workId);
-  return { annotation, out: { ok: annotation.t !== "claim" || item?.verification === "verified",
+  const claim = annotation.t === "claim" ? claimResult(annotation, resolveEvidence(input.events, annotation.evidence, owned?.opened_at), owned?.opened_at) : undefined;
+  return { annotation, out: { ...claim, ok: annotation.t !== "claim" || item?.verification === "verified",
     content: JSON.stringify({ recorded: true, work_item: item }) } };
 }

package/src/runtime/workspace-lifecycle.ts

@@ -0,0 +1,97 @@
+/** P.3: execution owns checkpoints; session opening owns no filesystem baseline. */
+import { randomUUID } from "node:crypto";
+import type { CheckpointEvent, FileVersion, WorkspaceObservationEvent } from "../core/checkpoints.ts";
+import { sameVersion } from "../core/checkpoints.ts";
+import { blobAddress } from "../store/blobs.ts";
+import { archiveEdit, replaceFile, readEditableFile } from "../store/file-checkpoints.ts";
+import { GitCheckpoints, type GitCheckpoint } from "../store/git-checkpoints.ts";
+import { observeWorkspace } from "../store/workspace-observation.ts";
+import type { ToolResult } from "./tools.ts";
+import type { JsonValue } from "../core/tool-contract.ts";
+
+type Record = Omit<CheckpointEvent, "id" | "at"> | Omit<WorkspaceObservationEvent, "id" | "at">;
+interface CommandCheckpoint { operation: string; snapshot?: GitCheckpoint; unavailable?: string; }
+export class WorkspaceLifecycle {
+  readonly root: string;
+  readonly blobs: string;
+  readonly shellCheckpoints: boolean;
+  private readonly record: (event: Record) => Promise<void>;
+  private readonly ownedPaths: readonly string[];
+  private readonly git: GitCheckpoints;
+  private readonly pending = new Map<number, CommandCheckpoint>();
+  private fingerprint: string | undefined;
+  constructor(root: string, blobs: string, shellCheckpoints: boolean, record: (event: Record) => Promise<void>, checkpointStorage = blobs, ownedPaths: readonly string[] = []) {
+    this.root = root; this.blobs = blobs; this.shellCheckpoints = shellCheckpoints; this.record = record;
+    this.ownedPaths = ownedPaths;
+    this.git = new GitCheckpoints(root, checkpointStorage, ownedPaths);
+  }
+  private interfere(): void {
+    for (const checkpoint of this.pending.values()) checkpoint.unavailable = "overlapping mutations prevent attributing a command checkpoint";
+  }
+  async edit(path: string, before: { bytes: Uint8Array | null; version: FileVersion }, after: Uint8Array, signal?: AbortSignal): Promise<void> {
+    this.interfere();
+    await archiveEdit(this.blobs, before.bytes, after);
+    const operation = randomUUID();
+    const next = { sha256: blobAddress(after), mode: before.version?.mode ?? (0o666 & ~process.umask()) };
+    const changes = { [path]: { before: before.version, after: next } };
+    await this.record({ t: "checkpoint", operation, source: "edit", phase: "prepared", changes });
+    try {
+      await replaceFile(this.root, path, before.version, after, next.mode, signal);
+      const actual = (await readEditableFile(this.root, path)).version;
+      if (!sameVersion(actual, next)) throw new Error(`file changed concurrently after editing: ${path}`);
+      await this.record({ t: "checkpoint", operation, source: "edit", phase: "applied", changes });
+    } catch (error) {
+      await this.record({ t: "checkpoint", operation, source: "edit", phase: "unavailable", changes,
+        reason: "edit did not establish the expected file version; inspect before retrying" });
+      throw error;
+    }
+  }
+  async command(name: string, input: unknown, execute: () => Promise<ToolResult>, signal?: AbortSignal): Promise<ToolResult> {
+    const args = input as { session_id?: number };
+    let checkpoint: CommandCheckpoint | undefined;
+    if (name === "write_stdin") checkpoint = args.session_id === undefined ? undefined : this.pending.get(args.session_id);
+    else {
+      this.interfere();
+      if (this.shellCheckpoints) {
+        checkpoint = { operation: randomUUID() };
+        try {
+          if (this.pending.size) throw new Error("another command is still running");
+          checkpoint.snapshot = await this.git.capture(signal);
+          await this.record({ t: "checkpoint", operation: checkpoint.operation, source: "git", phase: "prepared", changes: {}, tree: checkpoint.snapshot.tree });
+        } catch (error) { checkpoint.unavailable = error instanceof Error ? error.message : "Git checkpoint unavailable"; }
+      }
+    }
+    const result = await execute();
+    if (!checkpoint) return result;
+    const data = (result.data && typeof result.data === "object" && !Array.isArray(result.data) ? result.data : {}) as { readonly [key: string]: JsonValue };
+    const session = data["session_id"];
+    if (data["running"] === true && typeof session === "number") {
+      this.pending.set(session, checkpoint);
+      return { ...result, data: { ...data, checkpoint: "pending" } };
+    }
+    if (typeof args.session_id === "number") this.pending.delete(args.session_id);
+    try {
+      if (checkpoint.unavailable || !checkpoint.snapshot) throw new Error(checkpoint.unavailable ?? "missing command baseline");
+      const snapshot = await this.git.capture(signal);
+      const changes = await this.git.changes(checkpoint.snapshot, snapshot, this.blobs, signal);
+      await this.record({ t: "checkpoint", operation: checkpoint.operation, source: "git", phase: "applied", changes, tree: snapshot.tree });
+      return { ...result, data: { ...data, checkpoint: "captured" } };
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : "Git checkpoint unavailable";
+      await this.record({ t: "checkpoint", operation: checkpoint.operation, source: "git", phase: "unavailable", changes: {}, reason });
+      return { ...result, content: `${result.content}\nFile recovery unavailable: ${reason}. The command result is unchanged.`, data: { ...data, checkpoint: "unavailable" } };
+    }
+  }
+  async abandonCommands(): Promise<void> {
+    for (const checkpoint of this.pending.values()) await this.record({ t: "checkpoint", operation: checkpoint.operation,
+      source: "git", phase: "unavailable", changes: {}, reason: "process ended without an observed checkpoint boundary" });
+    this.pending.clear();
+  }
+  async observe(previous?: string, signal?: AbortSignal): Promise<void> {
+    const observation = await observeWorkspace(this.root, signal, this.ownedPaths);
+    const fingerprint = observation.ok ? observation.fingerprint : undefined;
+    await this.record({ t: "workspace_observation", scope: "source-v1", changed: !observation.ok || (previous ?? this.fingerprint) !== undefined && fingerprint !== (previous ?? this.fingerprint),
+      ...(observation.ok ? { fingerprint: observation.fingerprint } : { reason: observation.reason }) });
+    this.fingerprint = fingerprint;
+  }
+}

package/src/store/acceptance.ts

@@ -0,0 +1,15 @@
+/** Explicit files or trusted project declarations; never infer natural-language criteria. */
+import { join, resolve } from "node:path";
+import { parseAcceptanceContract, type AcceptanceContract } from "../core/acceptance.ts";
+import { blobAddress } from "./blobs.ts";
+
+export async function loadAcceptanceContract(workspace: string, trusted: boolean, explicit?: string): Promise<AcceptanceContract | undefined> {
+  if (!explicit && !trusted) return undefined;
+  const path = explicit ? resolve(workspace, explicit) : join(workspace, ".xeno", "acceptance.json");
+  const file = Bun.file(path);
+  if (!await file.exists()) { if (explicit) throw new Error(`missing acceptance file: ${path}`); return undefined; }
+  if (file.size > 64000) throw new Error("acceptance file exceeds 64 KiB");
+  const text = await file.text();
+  const contract = parseAcceptanceContract(JSON.parse(text));
+  return { ...contract, scope: contract.scope ?? (explicit ? "request" : "changes"), source: { path, sha256: blobAddress(text) } };
+}

package/src/store/checkpoint-history.ts

@@ -0,0 +1,43 @@
+/** File ancestry is independent of model-context ancestry (P.3). */
+import { readNodeHistory, type RestoreTarget } from "./restore.ts";
+import { planFileTransition, type CheckpointEvent, type FileVersion, type FileChanges } from "../core/checkpoints.ts";
+
+export async function checkpointHistory(dir: string, target: RestoreTarget, visited = new Set<string>()): Promise<CheckpointEvent[]> {
+  const position = typeof target === "number" ? { node: target } : target;
+  const key = `${position.node}:${position.atEvent ?? "end"}`;
+  if (visited.has(key) || visited.size >= 256) throw new Error("cyclic or excessively deep file history");
+  const next = new Set(visited).add(key);
+  const history = await readNodeHistory(dir, position.node);
+  if (!history.ok) throw new Error(history.error);
+  let checkpoints: CheckpointEvent[] = [];
+  const legacy = new Map<string, FileVersion>();
+  for (const node of history.nodes) {
+    let events = node.events;
+    if (node.node === position.node && position.atEvent !== undefined) {
+      const at = events.findIndex(event => event.id === position.atEvent);
+      if (at < 0) throw new Error(`NO_SUCH_EVENT: ${position.atEvent}`);
+      events = events.slice(0, at + 1);
+    }
+    for (const event of events) {
+      if (event.t === "rewind" && event.files_from) {
+        checkpoints = await checkpointHistory(dir, { node: event.files_from.node,
+          ...(event.files_from.at_event ? { atEvent: event.files_from.at_event } : {}) }, next);
+      } else if (event.t === "checkpoint") checkpoints.push(event);
+      else if (event.t === "snapshot") {
+        // Interpret historical full snapshots without rewriting them or scanning today's disk.
+        const changes: FileChanges = Object.create(null) as FileChanges;
+        for (const [path, sha256] of Object.entries({ ...event.added, ...event.changed })) {
+          changes[path] = { before: legacy.get(path) ?? null, after: { sha256, mode: 0o644 } };
+          legacy.set(path, changes[path]!.after);
+        }
+        for (const path of event.removed) { changes[path] = { before: legacy.get(path) ?? null, after: null }; legacy.delete(path); }
+        checkpoints.push({ t: "checkpoint", id: event.id, at: event.at, operation: event.id, source: "git", phase: "applied", changes });
+      }
+    }
+  }
+  return checkpoints;
+}
+
+export async function planCheckpointRestore(dir: string, current: RestoreTarget, target: RestoreTarget): Promise<FileChanges> {
+  return planFileTransition(await checkpointHistory(dir, current), await checkpointHistory(dir, target));
+}

package/src/store/command-artifacts.ts

@@ -0,0 +1,96 @@
+/** R8: bounded observations over file descriptors; binaries themselves are not copied into the log. */
+import { constants } from "node:fs";
+import { lstat, open, realpath } from "node:fs/promises";
+import { resolve, join, relative, sep } from "node:path";
+import { createHash } from "node:crypto";
+import { MAX_COMMAND_ARTIFACT_BYTES, COMMAND_ARTIFACT_SCOPE, sameArtifactIdentity, validArtifactPath,
+  type ArtifactFile, type ArtifactFileIdentity, type CommandArtifactPlan } from "../core/command-artifacts.ts";
+import { archiveObservation } from "./observations.ts";
+import { observeWorkspace, SOURCE_IGNORE } from "./workspace-observation.ts";
+import { blobAddress } from "./blobs.ts";
+
+// Assumed per-phase bounds, not performance measurements; exhaustion yields unknown.
+const OBSERVATION_MS = 10_000;
+const CHUNK_BYTES = 1024 * 1024;
+type IdentityStat = { dev: bigint; ino: bigint; mtimeNs: bigint; ctimeNs: bigint; mode: bigint };
+const identity = (info: IdentityStat): ArtifactFileIdentity => ({ device: String(info.dev), inode: String(info.ino),
+  mtime_ns: String(info.mtimeNs), ctime_ns: String(info.ctimeNs), mode: Number(info.mode) & 0o777 });
+
+/** Both walks reject symlink components. This is a local observation, not an OS sandbox against hostile concurrent renames. */
+async function ordinaryPath(root: string, path: string): Promise<string> {
+  let current = root;
+  const parts = path.split("/");
+  for (let i = 0; i < parts.length; i++) {
+    current = join(current, parts[i]!);
+    const info = await lstat(current);
+    if (info.isSymbolicLink() || (i === parts.length - 1 ? !info.isFile() : !info.isDirectory())) throw Object.assign(new Error("not an ordinary confined file"), { code: "EUNSAFE" });
+  }
+  if (await realpath(current) !== current) throw Object.assign(new Error("file path changed or follows a symlink"), { code: "EUNSAFE" });
+  return current;
+}
+
+export function artifactExclusions(root: string, plan: CommandArtifactPlan, ownedPaths: readonly string[] = []): string[] {
+  const owned = ownedPaths.map(path => relative(resolve(root), resolve(path)))
+    .filter(path => path && path !== ".." && !path.startsWith(`..${sep}`) && !path.startsWith(sep) && !path.split(sep).some(part => SOURCE_IGNORE.includes(part)));
+  return [...new Set([...plan.output_roots, ...owned])].sort();
+}
+export async function observeArtifactInputs(root: string, exclusions: readonly string[], signal?: AbortSignal): Promise<{ sha256: string | null; reason?: string }> {
+  const bounded = AbortSignal.any([AbortSignal.timeout(OBSERVATION_MS), ...(signal ? [signal] : [])]);
+  const result = await observeWorkspace(root, bounded, exclusions.map(path => resolve(root, path)));
+  // A digest binds the declared finite scope as well as its bytes; it is never source-v1 evidence.
+  return result.ok && !bounded.aborted ? { sha256: blobAddress(JSON.stringify([COMMAND_ARTIFACT_SCOPE, SOURCE_IGNORE, exclusions, result.fingerprint])) }
+    : { sha256: null, reason: result.ok ? "input observation cancelled or timed out" : result.reason };
+}
+
+export async function observeArtifactFiles(root: string, paths: readonly string[], signal?: AbortSignal): Promise<ArtifactFile[]> {
+  const bounded = AbortSignal.any([AbortSignal.timeout(OBSERVATION_MS), ...(signal ? [signal] : [])]);
+  let remaining = MAX_COMMAND_ARTIFACT_BYTES;
+  const results: ArtifactFile[] = [];
+  let base: string;
+  try { base = await realpath(root); } catch { return paths.map(() => ({ state: "unknown", reason: "workspace unavailable" })); }
+  for (const path of paths) {
+    if (!validArtifactPath(path)) { results.push({ state: "unsafe", reason: "invalid workspace artifact path" }); continue; }
+    if (bounded.aborted) { results.push({ state: "unknown", reason: "artifact observation cancelled or timed out" }); continue; }
+    try {
+      const absolute = await ordinaryPath(base, path);
+      // O_NONBLOCK prevents a concurrent FIFO replacement from hanging before fstat rejects it.
+      const file = await open(absolute, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+      try {
+        const before = await file.stat({ bigint: true });
+        if (!before.isFile()) { results.push({ state: "unsafe", reason: "opened object is not an ordinary file" }); continue; }
+        if (before.size > BigInt(remaining)) { results.push({ state: "unknown", reason: "artifact byte budget exceeded" }); continue; }
+        const limit = Number(before.size), buffer = Buffer.alloc(Math.min(CHUNK_BYTES, Math.max(1, limit + 1))), hash = createHash("sha256");
+        let bytes = 0, failed = false;
+        for (;;) {
+          if (bounded.aborted) { results.push({ state: "unknown", reason: "artifact observation cancelled or timed out" }); failed = true; break; }
+          const read = await file.read(buffer, 0, Math.min(buffer.length, limit + 1 - bytes), bytes);
+          bytes += read.bytesRead;
+          remaining -= read.bytesRead;
+          if (bytes > limit) { results.push({ state: "changed", reason: "file grew during observation" }); failed = true; break; }
+          if (read.bytesRead === 0) break;
+          hash.update(buffer.subarray(0, read.bytesRead));
+        }
+        if (failed) continue;
+        const after = await file.stat({ bigint: true });
+        await ordinaryPath(base, path);
+        const named = await lstat(absolute, { bigint: true });
+        if (bytes !== Number(before.size) || after.size !== before.size || named.size !== before.size ||
+          !sameArtifactIdentity(identity(before), identity(after)) || !sameArtifactIdentity(identity(after), identity(named))) {
+          results.push({ state: "changed", reason: "file contents or identity changed during observation" }); continue;
+        }
+        results.push({ state: "observed", sha256: hash.digest("hex"), bytes, identity: identity(after) });
+      } finally { await file.close(); }
+    } catch (error) {
+      const code = (error as { code?: string }).code;
+      results.push(code === "ENOENT" || code === "ENOTDIR" ? { state: "missing", reason: "artifact path was not found" }
+        : code === "EUNSAFE" || code === "ELOOP" ? { state: "unsafe", reason: "artifact path is not an ordinary confined file" }
+        : { state: "unknown", reason: "artifact file could not be observed" });
+    }
+  }
+  return results;
+}
+
+export async function archiveCommandArtifacts(outputStore: string, observation: unknown) {
+  async function* bytes() { yield new TextEncoder().encode(JSON.stringify(observation)); }
+  return (await archiveObservation(outputStore, bytes(), 0)).ref;
+}

package/src/store/command.ts

@@ -1,49 +1,60 @@
 /** O.1: own the process group, preserve partial observations, and drain before returning. */
 import { captureCommandObservation } from "./observations.ts";
+import { commandArgv, commandEnvironment, COMMAND_TERMINATION_GRACE_MS } from "../core/command-contract.ts";
+import { ToolFault, NOT_STARTED, failureDiagnostic } from "../core/tool-failure.ts";
 
-/** Operational grace, not a measured optimum: do not let ignored SIGTERM defeat cancellation. */
-const TERMINATION_GRACE_MS = 200;
-
-/**
- * Variables that make a command behave as if no one is at the keyboard.
- *
- * There never is: a pager waits on a tty that does not exist, colour codes
- * spend budget on escape bytes, and a git credential prompt or an apt
- * question hangs the command until the timeout. Codex sets the same core set
- * for its exec sessions (`unified_exec/process_manager.rs`). LANG is filled in
- * only when absent -- a user's own locale is not ours to override.
- */
-export function commandEnvironment(base: Readonly<Record<string, string | undefined>>): Record<string, string> {
-  const env: Record<string, string> = {};
-  for (const [key, value] of Object.entries(base)) if (value !== undefined) env[key] = value;
-  Object.assign(env, {
-    TERM: "dumb", PAGER: "cat", GIT_PAGER: "cat", NO_COLOR: "1",
-    GIT_TERMINAL_PROMPT: "0", DEBIAN_FRONTEND: "noninteractive",
-  });
-  if (env["LANG"] === undefined || env["LANG"] === "") env["LANG"] = "C.UTF-8";
-  return env;
-}
-
-export async function observeCommand(input: {
-  command: string;
+interface CommandCaptureInput {
   cwd: string;
   outputStore: string;
   maxOutputBytes: number;
   timeoutMs: number;
   signal?: AbortSignal;
   onOutput?: (chunk: Uint8Array) => void;
-}) {
+  /** Bounded probes never transfer background children to the caller. */
+  cleanupOnExit?: boolean;
+  /** Stop capture after the crossing chunk; command cancellation still owns process cleanup. */
+  outputLimitBytes?: number;
+}
+
+export async function observeCommand(input: CommandCaptureInput & { command: string }) {
   if (input.signal?.aborted) {
     const empty = () => new ReadableStream<Uint8Array>({ start: controller => controller.close() });
     const captured = await captureCommandObservation(input.outputStore, empty(), empty(), Promise.resolve(130), input.maxOutputBytes);
-    return { ...captured, wallMs: 0, stopped: "cancelled" as const };
+    return { ...captured, wallMs: 0, stopped: "cancelled" as const, cleanup: undefined };
   }
+  return executeCaptured(input, commandArgv(input.command), false);
+}
+
+/** Native host API: argv is never interpreted by a shell and each pipe is recoverable. */
+export async function observeArgvCommand(input: CommandCaptureInput & { argv: readonly string[] }) {
+  if (!Array.isArray(input.argv) || input.argv.length === 0 || !input.argv[0] ||
+    input.argv.some(value => typeof value !== "string" || value.includes("\0"))) {
+    throw new ToolFault("invalid_input", "native argv must contain a program and literal string arguments without NUL", NOT_STARTED);
+  }
+  if (input.signal?.aborted) throw new ToolFault("cancelled", "native command was cancelled before it started", NOT_STARTED);
+  const captured = await executeCaptured(input, [...input.argv], true);
+  if (captured.channels.length !== 2) throw new Error("missing native stdout/stderr artifacts");
+  return { ...captured, stdout: captured.channels[0]!, stderr: captured.channels[1]! };
+}
+
+async function executeCaptured(input: CommandCaptureInput, argv: string[], native: boolean) {
   const started = performance.now();
-  const proc = Bun.spawn(["bash", "-o", "pipefail", "-lc", input.command], {
-    cwd: input.cwd, stdout: "pipe", stderr: "pipe", detached: true, env: commandEnvironment(process.env),
-  });
+  const proc = (() => {
+    try { return Bun.spawn(argv, {
+      cwd: input.cwd, stdin: "ignore", stdout: "pipe", stderr: "pipe", detached: true,
+      // Preserve the trusted native API's inherited environment; shell tools
+      // retain their explicit noninteractive policy and login-shell startup.
+      env: native ? process.env : commandEnvironment(process.env),
+    }); } catch (error) {
+      const os = (error as { code?: string }).code;
+      throw new ToolFault(os === "ENOENT" || os === "ENOTDIR" ? "environment_missing" : os === "EACCES" || os === "EPERM" ? "permission_denied" : "execution_failed", String(error), NOT_STARTED);
+    }
+  })();
   let stopped: "cancelled" | "timeout" | undefined;
   let escalation: ReturnType<typeof setTimeout> | undefined;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let exited = false, cleaned = false;
+  let cleanupError: unknown;
   const kill = (signal: "SIGTERM" | "SIGKILL") => {
     try {
       // POSIX detached children lead their own group; never signal the caller's group.
@@ -53,22 +64,39 @@ export async function observeCommand(input: {
       if ((error as { code?: string }).code !== "ESRCH") throw error;
     }
   };
+  const cleanup = () => {
+    if (cleaned) return;
+    cleaned = true;
+    try { kill("SIGKILL"); } catch (error) { cleanupError = error; }
+  };
   const stop = (reason: "cancelled" | "timeout") => {
-    if (stopped !== undefined) return;
+    if (exited || stopped !== undefined) return;
     stopped = reason;
     kill("SIGTERM");
-    escalation = setTimeout(() => kill("SIGKILL"), TERMINATION_GRACE_MS);
+    escalation = setTimeout(cleanup, COMMAND_TERMINATION_GRACE_MS);
   };
+  const exit = proc.exited.then(code => {
+    exited = true;
+    clearTimeout(timer); clearTimeout(escalation);
+    // Clean once at the observed exit, never after slow archival when a PID
+    // might have been reused. Legacy successful bash background starts remain.
+    if (native || input.cleanupOnExit || stopped !== undefined) cleanup();
+    return code;
+  });
   const abort = () => stop("cancelled");
   input.signal?.addEventListener("abort", abort, { once: true });
-  const timer = setTimeout(() => stop("timeout"), input.timeoutMs);
+  timer = setTimeout(() => stop("timeout"), input.timeoutMs);
   if (input.signal?.aborted) abort();
   try {
     const captured = await captureCommandObservation(input.outputStore, proc.stdout, proc.stderr,
-      proc.exited, input.maxOutputBytes, input.onOutput);
-    return { ...captured, wallMs: performance.now() - started, ...(stopped ? { stopped } : {}) };
+      exit, input.maxOutputBytes, input.onOutput, native, input.outputLimitBytes);
+    // Parent exit and archived output remain facts even if group cleanup
+    // cannot be confirmed. This is execution uncertainty, not user denial.
+    const cleanupDiagnostic = cleanupError === undefined ? undefined : failureDiagnostic("unknown_effect",
+      `process-group cleanup was not confirmed: ${String(cleanupError)}`, { execution: "started", effects: "possible" });
+    return { ...captured, wallMs: performance.now() - started, ...(stopped ? { stopped } : {}), cleanup: cleanupDiagnostic };
   } catch (error) {
-    kill("SIGKILL");
+    cleanup();
     await proc.exited;
     throw error;
   } finally {
@@ -76,6 +104,6 @@ export async function observeCommand(input: {
     clearTimeout(escalation);
     input.signal?.removeEventListener("abort", abort);
     // A descendant can close stdio yet ignore SIGTERM; completing capture is not proof it stopped.
-    if (stopped !== undefined) kill("SIGKILL");
+    if (stopped !== undefined) cleanup();
   }
 }