@visual-z/xeno 0.2.1 → 0.4.0

package/src/core/model-picker.ts

@@ -0,0 +1,64 @@
+/**
+ * `/model` list order. Pure: the catalog, readiness and recency go in,
+ * rows come out.
+ *
+ * The catalog holds thousands of entries across hundreds of providers; a
+ * picker that lists them all is the "every time I pick a model it's hard"
+ * report. The rule is OpenCode's (dialog-model.tsx): only models whose
+ * provider can actually authenticate, Recent first (bounded), then one
+ * group per provider, in catalog order. The current model is always shown, even when its
+ * credential stopped resolving, so the user can see why they are stuck.
+ */
+export interface PickerModel {
+  readonly key: string;
+  readonly provider: string;
+  readonly providerName: string;
+  readonly id: string;
+  readonly name: string;
+  readonly ready: boolean;
+}
+
+export interface PickerRow {
+  readonly key: string;
+  readonly section: "recent" | "provider";
+  /** Group heading: "Recent" or the provider's display name. */
+  readonly group: string;
+  readonly model: PickerModel;
+  readonly current: boolean;
+}
+
+/** Five recent models: one screen of a 10-row list stays for the provider groups. Assumed. */
+export const RECENT_LIMIT = 5;
+
+export function pickerRows(models: readonly PickerModel[], opts: { readonly current: string; readonly recent: readonly string[]; readonly limit?: number }): PickerRow[] {
+  const visible = models.filter(model => model.ready || model.key === opts.current);
+  const byKey = new Map(visible.map(model => [model.key, model]));
+  const rows: PickerRow[] = [];
+  const used = new Set<string>();
+  for (const key of opts.recent) {
+    if (rows.length >= (opts.limit ?? RECENT_LIMIT)) break;
+    const model = byKey.get(key);
+    if (!model || used.has(key)) continue;
+    used.add(key);
+    rows.push({ key, section: "recent", group: "Recent", model, current: key === opts.current });
+  }
+  const groups = new Map<string, PickerModel[]>();
+  for (const model of visible) {
+    if (used.has(model.key)) continue;
+    used.add(model.key);
+    const list = groups.get(model.provider) ?? [];
+    list.push(model);
+    groups.set(model.provider, list);
+  }
+  // Catalog order is curated (flagship models first), so it is kept for
+  // both the groups and the models inside them instead of re-sorting.
+  for (const [, list] of groups) {
+    for (const model of list) rows.push({ key: model.key, section: "provider", group: model.providerName, model, current: model.key === opts.current });
+  }
+  return rows;
+}
+
+/** Most recent first, deduplicated, bounded. Recording is a pure update of the stored list. */
+export function recordRecent(recent: readonly string[], key: string, limit = 10): string[] {
+  return [key, ...recent.filter(entry => entry !== key)].slice(0, limit);
+}

package/src/core/native-eval.ts

@@ -0,0 +1,25 @@
+/** Q.20: native subscription measurements are standard API price equivalents, never invoices. */
+import { measuredCharge, requestReservation, type BenchmarkPrice, type BenchmarkUsage } from "./benchmark.ts";
+
+// Verified Luna short-context tier. Bound wire bytes conservatively before dispatch;
+// crossing this tier needs a new protocol, not silent use of the cheaper price.
+export const NATIVE_EVAL_INPUT_LIMIT = 272000;
+export function nativeUsage(response: unknown): BenchmarkUsage | null {
+  if (!response || typeof response !== "object") return null;
+  const raw = (response as Record<string, unknown>)["usage"];
+  if (!raw || typeof raw !== "object") return null;
+  const u = raw as Record<string, unknown>, details = u["input_tokens_details"] as Record<string, unknown> | undefined;
+  const input = u["input_tokens"], output = u["output_tokens"], cached = details?.["cached_tokens"] ?? 0, created = details?.["cache_write_tokens"] ?? 0;
+  if (![input, output, cached, created].every(n => typeof n === "number" && Number.isSafeInteger(n) && n >= 0) ||
+      Number(input) <= 0 || Number(output) <= 0 || Number(input) > NATIVE_EVAL_INPUT_LIMIT || Number(cached) + Number(created) > Number(input)) return null;
+  return { input_tokens: Number(input) - Number(cached) - Number(created), output_tokens: Number(output),
+    cache_read_input_tokens: Number(cached), cache_creation_input_tokens: Number(created) };
+}
+export function nativeReservation(bytes: number, modelMaxOutput: number, price: BenchmarkPrice): number {
+  if (bytes + 4096 > NATIVE_EVAL_INPUT_LIMIT || price.cacheWrite === undefined) throw Error("native eval price tier or cache-write rate is not covered");
+  return requestReservation(bytes, modelMaxOutput, { ...price, input: Math.max(price.input, price.cacheWrite) });
+}
+export function nativeMeasured(response: unknown, price: BenchmarkPrice): number | null {
+  const usage = nativeUsage(response);
+  return usage && price.cacheWrite !== undefined ? measuredCharge(usage, price) : null;
+}

package/src/core/note-guidance.ts

@@ -0,0 +1,34 @@
+/** Q.22: recovery advice must use the same evidence rules as the handoff. */
+import type { LogEvent } from "./events.ts";
+import { resolveEvidence, type EvidenceResolution } from "./evidence.ts";
+import type { ToolDiagnostic } from "./tool-contract.ts";
+import { failureDiagnostic, NOT_STARTED } from "./tool-failure.ts";
+
+type Claim = Extract<LogEvent, { t: "claim" }>;
+
+/** Only unknown work may suggest the existing unscoped completion path. */
+export function unknownWorkClaimDiagnostic(events: readonly LogEvent[], claim: Claim): ToolDiagnostic {
+  const proof = resolveEvidence(events, claim.evidence);
+  const message = `unknown work_id ${claim.work_id}; no work item was created or completed`;
+  const diagnostic = failureDiagnostic("invalid_input", message, NOT_STARTED);
+  if (!proof.ok) return { ...diagnostic,
+    next: "For tracked work, record next before doing and verifying it. For a one-off task, omit work_id from done after an actual successful verification. A done note is optional." };
+  return { ...diagnostic,
+    next: "A current successful verification already exists. For this one-off completion, omit work_id; do not create next after verification or rerun the command just to record a note.",
+    recover: { tool: "note", input: { kind: "done", what: claim.what, proof: proof.evidence.command } } };
+}
+
+/** A persisted claim is a known state change, even when its proof is insufficient. */
+export function unverifiedNoteDiagnostic(reason: Extract<EvidenceResolution, { ok: false }>, event: string, openedAt?: string): ToolDiagnostic {
+  const cause = reason.reason === "nonzero_exit" ? `the matching command exited ${reason.exit}`
+    : reason.reason === "stale_workspace" ? "the verification no longer matches the observed workspace"
+    : openedAt ? `no matching verification was observed after work activation ${openedAt} in this segment`
+    : "no matching verification was observed in this segment";
+  const message = `Claim ${event} was recorded but remains unverified: ${cause}.`;
+  return { ...failureDiagnostic("execution_failed", message, { execution: "started", effects: "possible" }),
+    next: "The claim is already recorded; do not replay it unchanged. " + (reason.reason === "nonzero_exit"
+      ? "Inspect the command's original output, fix the cause and verify again before claiming completion."
+      : reason.reason === "stale_workspace" ? "Verify the current workspace before claiming completion."
+      : openedAt ? "Run the verifier for this work activation before claiming completion; reopening never reuses an older verification."
+      : "Cite an actual successful command from this segment, or run the required verification first.") };
+}

package/src/core/oauth-fields.ts

@@ -0,0 +1,44 @@
+/** Validated wire data only; the runtime owns HTTP, time, polling and persistence. */
+export interface OAuthTokens { access: string; refresh: string; expiresIn: number }
+export interface DeviceAuthorization {
+  deviceCode: string;
+  userCode: string;
+  verificationUri: string;
+  verificationUriComplete?: string;
+  expiresIn: number;
+  interval?: number;
+}
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+}
+function positive(value: unknown): value is number { return typeof value === "number" && Number.isFinite(value) && value > 0; }
+function token(value: unknown): value is string { return typeof value === "string" && value.length > 0 && !/[\s\x00-\x1f\x7f]/.test(value); }
+
+/** Refresh rotation is optional; omission preserves the existing refresh capability. */
+export function parseOAuthTokens(value: unknown, previousRefresh?: string): OAuthTokens | undefined {
+  const data = record(value);
+  const access = data?.["access_token"], refresh = data?.["refresh_token"] ?? previousRefresh, expiresIn = data?.["expires_in"];
+  if (!token(access) || !token(refresh) || !positive(expiresIn)) return undefined;
+  return { access, refresh, expiresIn };
+}
+
+export function trustedOAuthUrl(value: unknown, origins: readonly string[]): value is string {
+  if (typeof value !== "string" || /[\x00-\x20\x7f]/.test(value)) return false;
+  try {
+    const url = new URL(value);
+    return url.protocol === "https:" && !url.username && !url.password && origins.includes(url.origin);
+  } catch { return false; }
+}
+
+/** Never open an issuer-supplied arbitrary origin or print its control characters. */
+export function parseDeviceAuthorization(value: unknown, origins: readonly string[]): DeviceAuthorization | undefined {
+  const data = record(value);
+  const deviceCode = data?.["device_code"], userCode = data?.["user_code"], verificationUri = data?.["verification_uri"];
+  const complete = data?.["verification_uri_complete"], expiresIn = data?.["expires_in"], interval = data?.["interval"];
+  if (!token(deviceCode) || typeof userCode !== "string" || !/^[A-Za-z0-9-]+$/.test(userCode)
+    || !trustedOAuthUrl(verificationUri, origins) || !positive(expiresIn)
+    || (complete !== undefined && !trustedOAuthUrl(complete, origins)) || (interval !== undefined && !positive(interval))) return undefined;
+  return { deviceCode, userCode, verificationUri, expiresIn,
+    ...(typeof complete === "string" ? { verificationUriComplete: complete } : {}), ...(typeof interval === "number" ? { interval } : {}) };
+}

package/src/core/observation-view.ts

@@ -7,6 +7,30 @@
  * failing build or test run prints last: the error and the summary. Codex
  * keeps half of each end (`utils/string/src/truncate.rs`); so does this.
  */
+import type { ArtifactRef } from "./events.ts";
+
+export interface BytePreview {
+  unit: "utf8_bytes";
+  complete: boolean;
+  visible: readonly (readonly [number, number])[];
+  next_offset: number | null;
+}
+const object = (value: unknown): value is Record<string, unknown> => value !== null && typeof value === "object" && !Array.isArray(value);
+const natural = (value: unknown): value is number => typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+export function isObservationArtifact(value: unknown): value is ArtifactRef {
+  return object(value) && typeof value["sha256"] === "string" && /^[a-f0-9]{64}$/.test(value["sha256"]) && typeof value["path"] === "string" && natural(value["bytes"]);
+}
+/** The same coverage invariant serves file reads and search projections. */
+export function isBytePreview(value: unknown, total: number): value is BytePreview {
+  if (!object(value) || value["unit"] !== "utf8_bytes" || typeof value["complete"] !== "boolean" || !Array.isArray(value["visible"])) return false;
+  let last = 0, prefix = 0;
+  for (const range of value["visible"]) {
+    if (!Array.isArray(range) || range.length !== 2 || !natural(range[0]) || !natural(range[1]) || range[0] < last || range[1] <= range[0] || range[1] > total) return false;
+    if (prefix === range[0]) prefix = range[1];
+    last = range[1];
+  }
+  return value["complete"] === (prefix === total) && value["next_offset"] === (value["complete"] ? null : prefix);
+}
 
 /** A UTF-8 continuation byte: cutting before one would split a character. */
 const continuation = (byte: number | undefined) => byte !== undefined && (byte & 0xc0) === 0x80;
@@ -29,20 +53,36 @@ export function headTailView(
   limit: number,
   marker: (omitted: number, offset: number) => string,
 ): string {
+  // Legacy command callers require the recovery locator even below its minimum display budget.
+  return headTailSelection(head, tail, total, limit, marker, true).text;
+}
+
+/** Half-open byte ranges in the original observation, excluding presentation markers. */
+export function headTailSelection(
+  head: Uint8Array, tail: Uint8Array, total: number, limit: number,
+  marker: (omitted: number, offset: number) => string, allowOversizeMarker = false,
+): { text: string; visible: [number, number][] } {
   const decoder = new TextDecoder();
-  if (total <= limit && head.length >= total) return decoder.decode(head.subarray(0, total));
+  if (total <= limit && head.length >= total) return { text: decoder.decode(head.subarray(0, total)), visible: total ? [[0, total]] : [] };
   // Digits of the real numbers never exceed digits of `total`, so this bounds
   // the marker before the cut points that decide its numbers are known.
   const reserve = new TextEncoder().encode(marker(total, total)).length;
+  if (reserve > limit && !allowOversizeMarker) {
+    const bytes = new TextEncoder().encode(marker(total, 0));
+    let end = Math.max(0, Math.min(Math.floor(limit), bytes.length));
+    while (end > 0 && continuation(bytes[end])) end--;
+    return { text: decoder.decode(bytes.subarray(0, end)), visible: [] };
+  }
   const budget = Math.max(0, limit - reserve);
   let headEnd = Math.min(Math.floor(budget / 2), head.length);
   while (headEnd > 0 && continuation(head[headEnd])) headEnd--;
   let tailStart = tail.length - Math.min(budget - headEnd, tail.length);
   while (tailStart < tail.length && continuation(tail[tailStart])) tailStart++;
   const kept = tail.length - tailStart;
-  return decoder.decode(head.subarray(0, headEnd)) +
+  return { text: decoder.decode(head.subarray(0, headEnd)) +
     marker(total - headEnd - kept, headEnd) +
-    decoder.decode(tail.subarray(tailStart));
+    decoder.decode(tail.subarray(tailStart)),
+    visible: [...(headEnd ? [[0, headEnd] as [number, number]] : []), ...(kept ? [[total - kept, total] as [number, number]] : [])] };
 }
 
 /** Signals a shell reports as 128+n; the common ones a model can act on. */
@@ -69,17 +109,18 @@ export function commandHeader(input: {
   timeoutMs: number;
   /** What the model asked for, when that differs from what was applied. */
   requestedMs?: number;
+  managed?: boolean;
 }): string {
   const parts = [`exit ${input.exit}`, `${(input.wallMs / 1000).toFixed(1)}s`];
   if (input.stopped === "timeout") {
     const requested = input.requestedMs !== undefined && input.requestedMs !== input.timeoutMs
       ? ` (requested ${seconds(input.requestedMs)}, capped)` : "";
-    // Say what to do differently: the same command with the same timeout
-    // will time out the same way.
-    parts.push(`timed out after ${seconds(input.timeoutMs)}${requested}; process group terminated; ` +
-      "rerun with a larger timeout, or start long-lived work in the background with output redirected to a file and poll it");
+    // A deadline requests cleanup, but cannot by itself prove absence of
+    // partial side effects or successful cleanup (R3 / R10).
+    parts.push(`timed out after ${seconds(input.timeoutMs)}${requested}; process group cleanup requested; ` +
+      "inspect partial effects and cleanup before deciding on a new invocation or a larger timeout");
   } else if (input.stopped === "cancelled") {
-    parts.push("cancelled; process group terminated");
+    parts.push("cancelled; process group cleanup requested");
   } else if (input.exit > 128 && SIGNALS[input.exit - 128] !== undefined) {
     parts.push(`128+${input.exit - 128}: likely terminated by ${SIGNALS[input.exit - 128]}`);
   }

package/src/core/permissions.ts

@@ -36,7 +36,22 @@ export interface PermissionRule {
  */
 export type ToolSource = "builtin" | "extension";
 
+/** Task capabilities are frozen once at session creation (O.7); not permissions. */
+export const TOOL_PROFILES = {
+  coding: ["read", "grep", "find", "write", "edit", "environment", "exec_command", "write_stdin", "history", "note"],
+  readonly: ["read", "grep", "find", "history", "note"],
+  research: ["read", "grep", "find", "history", "note", "branch", "resolve"],
+  data: ["read", "grep", "find", "history", "note", "query"],
+  full: null,
+} as const;
+export type ToolProfile = keyof typeof TOOL_PROFILES;
+export function isToolProfile(value: string): value is ToolProfile {
+  return Object.hasOwn(TOOL_PROFILES, value);
+}
+
 export interface ToolSelection {
+  /** Applies only to builtin defaults; explicit only and extension capabilities win. */
+  readonly profile?: ToolProfile;
   /** `--tools`: a strict allowlist. */
   readonly only?: readonly string[];
   /** `--exclude-tools`: removed after the allowlist (or the full set) is built. */
@@ -69,6 +84,8 @@ export function defaultRules(): readonly PermissionRule[] {
     // Same reach as bash. write_stdin needs no rule of its own: it can only
     // address a session exec_command already started, under this approval.
     { action: "ask", tool: "exec_command" },
+    { action: "ask", tool: "environment" },
+    { action: "ask", tool: "target" },
     { action: "allow" },
   ];
 }
@@ -147,6 +164,11 @@ export function selectTools<T extends { name: string; source?: ToolSource }>(
 ): T[] {
   const names = new Set(selectToolNames(tools.map((t) => t.name), selection));
   let selected = tools.filter((t) => names.has(t.name));
+  const profile = selection.profile === undefined ? null : TOOL_PROFILES[selection.profile];
+  if (profile !== null && selection.only === undefined) {
+    const defaults = new Set<string>(profile);
+    selected = selected.filter(t => t.source === "extension" || defaults.has(t.name));
+  }
   // `--tools` already named specific tools, so the category filter does
   // not get a second veto. Untagged tools are builtin: that is today's
   // only producer, and treating absence as "keep" would make the flag a
@@ -158,10 +180,10 @@ export function selectTools<T extends { name: string; source?: ToolSource }>(
 }
 
 export function permissionRequest(name: string, input: unknown): PermissionRequest {
-  if ((name !== "bash" && name !== "exec_command") || typeof input !== "object" || input === null) {
+  if (!["bash", "exec_command", "environment"].includes(name) || typeof input !== "object" || input === null) {
     return { tool: name };
   }
-  const command = (input as { readonly [k: string]: unknown })[name === "bash" ? "command" : "cmd"];
+  const command = (input as { readonly [k: string]: unknown })[name === "exec_command" ? "cmd" : "command"];
   if (typeof command !== "string") return { tool: name };
   return { tool: name, command };
 }

package/src/core/process-receipt.ts

@@ -0,0 +1,105 @@
+/** R7 / D8 / D11: an observed process and a live control capability are distinct facts. */
+import type { ArtifactRef, LogEvent } from "./events.ts";
+import { isObservationArtifact } from "./observation-view.ts";
+import { isCommandArtifactReceipt, type CommandArtifactReceipt } from "./command-artifacts.ts";
+
+export type ProcessSource = { host: string; workspace: string; cwd: string; runtime: string };
+export type ProcessReceipt = {
+  kind: "process";
+  version: 1;
+  session_id: number;
+  state: "running" | "exited" | "cancelled" | "timeout" | "unknown";
+  capability: "live" | "closed" | "lost" | "expired" | "unknown";
+  /** Legacy running/exit fields keep their meaning; null explicitly means no observation. */
+  running: boolean | null;
+  exit: number | null;
+  source: ProcessSource | null;
+  output?: ArtifactRef;
+  full_output?: ArtifactRef;
+  /** Half-open raw stream byte offsets covered by output, not preview character positions. */
+  cursor?: { unit: "bytes"; start: number; end: number };
+  replayed: boolean;
+  /** Complete means stream EOF was observed; full_output always means all captured bytes. */
+  capture?: "complete" | "partial";
+  /** Same one-shot command observation, not a new scan at each poll. */
+  artifacts?: CommandArtifactReceipt;
+  origin?: { node: number; event: string };
+};
+
+const object = (value: unknown): value is Record<string, unknown> => value !== null && typeof value === "object" && !Array.isArray(value);
+const natural = (value: unknown): value is number => typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+export function isProcessReceipt(value: unknown): value is ProcessReceipt {
+  if (!object(value) || value["kind"] !== "process" || value["version"] !== 1 || !natural(value["session_id"]) || value["session_id"] < 1 ||
+    !["running", "exited", "cancelled", "timeout", "unknown"].includes(String(value["state"])) ||
+    !["live", "closed", "lost", "expired", "unknown"].includes(String(value["capability"])) || typeof value["replayed"] !== "boolean") return false;
+  if (value["state"] === "running") {
+    if (value["running"] !== true || value["exit"] !== null || !["live", "lost"].includes(String(value["capability"]))) return false;
+  } else if (value["state"] === "unknown") {
+    if (value["running"] !== null || value["exit"] !== null || value["capability"] !== "unknown") return false;
+  } else if (value["running"] !== false || !Number.isInteger(value["exit"]) || !["closed", "expired"].includes(String(value["capability"]))) return false;
+  const source = value["source"];
+  if (["lost", "expired"].includes(String(value["capability"])) && value["replayed"] !== true) return false;
+  if (value["capture"] !== undefined && !["complete", "partial"].includes(String(value["capture"]))) return false;
+  const artifacts = value["artifacts"];
+  if (artifacts !== undefined && (!isCommandArtifactReceipt(artifacts) || artifacts.exit !== value["exit"] ||
+    value["state"] === "unknown" || !object(value["source"]) || !["host", "workspace", "cwd", "runtime"].every(key =>
+      (artifacts.source as Record<string, string>)[key] === (value["source"] as Record<string, unknown>)[key]))) return false;
+  if (source !== null && (!object(source) || !["host", "workspace", "cwd", "runtime"].every(key => typeof source[key] === "string" && source[key] !== ""))) return false;
+  for (const name of ["output", "full_output"]) if (value[name] !== undefined && !isObservationArtifact(value[name])) return false;
+  const cursor = value["cursor"];
+  if (cursor !== undefined && (!object(cursor) || cursor["unit"] !== "bytes" || !natural(cursor["start"]) || !natural(cursor["end"]) ||
+    cursor["end"] < cursor["start"] || !isObservationArtifact(value["output"]) || value["output"].bytes !== cursor["end"] - cursor["start"])) return false;
+  if (isObservationArtifact(value["full_output"]) && object(cursor) && typeof cursor["end"] === "number" && value["full_output"].bytes !== cursor["end"]) return false;
+  const origin = value["origin"];
+  return origin === undefined || object(origin) && natural(origin["node"]) && typeof origin["event"] === "string" && origin["event"] !== "";
+}
+
+export function processReceipt(input: { session: number; source: ProcessSource; exit: number | null; stopped?: "cancelled" | "timeout";
+  output: ArtifactRef; fullOutput?: ArtifactRef; start: number; end: number; capture?: "complete" | "partial"; replayed?: boolean; artifacts?: CommandArtifactReceipt }): ProcessReceipt {
+  const state = input.exit === null ? "running" : input.stopped ?? "exited";
+  return { kind: "process", version: 1, session_id: input.session, source: input.source, state,
+    capability: input.exit === null ? "live" : "closed", running: input.exit === null, exit: input.exit,
+    output: input.output, ...(input.fullOutput ? { full_output: input.fullOutput } : {}),
+    cursor: { unit: "bytes", start: input.start, end: input.end }, replayed: input.replayed === true,
+    ...(input.artifacts ? { artifacts: input.artifacts } : {}),
+    ...(input.capture ? { capture: input.capture } : {}) };
+}
+
+/** Missing live state never turns a historical running observation into a fabricated exit. */
+export function recoverProcessReceipt(receipt: ProcessReceipt, origin: { node: number; event: string }): ProcessReceipt {
+  return { ...receipt, capability: receipt.state === "running" ? "lost" : receipt.state === "unknown" ? "unknown" : "expired", replayed: true, origin };
+}
+
+/** Original results, not a bounded handoff or replayed receipt, own the observation time and evidence. */
+export function latestProcessReceipt(nodes: readonly { node: number; events: readonly LogEvent[] }[], session: number):
+  { receipt: ProcessReceipt; origin: { node: number; event: string } } | undefined {
+  for (let n = nodes.length - 1; n >= 0; n--) {
+    const part = nodes[n]!;
+    for (let i = part.events.length - 1; i >= 0; i--) {
+      const event = part.events[i]!, origin = { node: part.node, event: event.id };
+      if (event.t === "process_exit" && event.session === session) return { origin, receipt: event.receipt ?? {
+        kind: "process", version: 1, session_id: session, state: "exited", capability: "closed", source: null,
+        running: false, exit: event.exit, output: event.output, replayed: false,
+      } };
+      if (event.t !== "tool_result" || !object(event.data) || event.data["session_id"] !== session) continue;
+      if (isProcessReceipt(event.data)) {
+        if (!event.data.replayed) return { receipt: event.data, origin };
+        continue;
+      }
+      const data = event.data;
+      if (typeof data["running"] !== "boolean" || data["running"] === false && !Number.isInteger(data["exit"])) continue;
+      return { origin, receipt: { kind: "process", version: 1, session_id: session, source: null,
+        state: data["running"] ? "running" : "exited", capability: data["running"] ? "live" : "closed",
+        running: data["running"], exit: data["running"] ? null : data["exit"] as number,
+        ...(event.content_ref ? { output: event.content_ref } : {}), replayed: false } };
+    }
+  }
+  return undefined;
+}
+
+/** Disposable cache bounds are supplied by runtime; pruning never changes the durable receipts. */
+export function retainProcessReceipts<T extends { endedAt: number }>(entries: readonly T[], now: number, maxAgeMs: number, maxCount: number): T[] {
+  if (!Number.isFinite(now) || !Number.isFinite(maxAgeMs) || maxAgeMs < 0 || !Number.isSafeInteger(maxCount) || maxCount < 0) throw new Error("invalid receipt retention policy");
+  return entries.filter(entry => entry.endedAt <= now && now - entry.endedAt < maxAgeMs)
+    .sort((a, b) => b.endedAt - a.endedAt).slice(0, maxCount);
+}

package/src/core/process-state.ts

@@ -0,0 +1,37 @@
+/** O.14: observed process facts and present capabilities are different projections. */
+import type { ArtifactRef, LogEvent } from "./events.ts";
+import type { BranchRecord } from "./handoff.ts";
+import { isProcessReceipt } from "./process-receipt.ts";
+
+export type ProcessObservation = {
+  session: number; node: number; event: string; observed: "running" | "exited";
+  command?: string; exit?: number; output?: ArtifactRef;
+}
+export function deriveProcesses(prev: readonly ProcessObservation[], events: readonly LogEvent[], node: number): ProcessObservation[] {
+  const state = new Map(prev.map(item => [item.session, item]));
+  const commands = new Map<string, string>();
+  for (const event of events) {
+    if (event.t === "tool_invocation" && event.name === "exec_command" && typeof event.input === "object" && event.input !== null &&
+      !Array.isArray(event.input) && "cmd" in event.input && typeof event.input["cmd"] === "string") commands.set(event.call_id, event.input["cmd"]);
+    if (event.t === "assistant") for (const call of event.blocks) {
+      if (call.type === "tool_use" && call.name === "exec_command" && typeof call.input === "object" && call.input !== null && "cmd" in call.input && typeof call.input.cmd === "string") commands.set(call.call_id, call.input.cmd);
+    }
+    if (event.t === "process_exit") state.set(event.session, { session: event.session, node, event: event.id, observed: "exited", command: event.command, exit: event.exit, output: event.output });
+    if (event.t !== "tool_result" || !event.data || typeof event.data !== "object" || Array.isArray(event.data)) continue;
+    const data = event.data as { readonly [key: string]: unknown };
+    if (isProcessReceipt(data) && data.replayed) continue;
+    if (typeof data["session_id"] !== "number" || !Number.isSafeInteger(data["session_id"]) || data["session_id"] < 1 || typeof data["running"] !== "boolean") continue;
+    if (data["running"] === false && !Number.isInteger(data["exit"])) continue;
+    const before = state.get(data["session_id"]);
+    const command = event.effect?.kind === "command" ? event.effect.cmd : commands.get(event.call_id) ?? before?.command;
+    state.set(data["session_id"], { session: data["session_id"], node, event: event.id, observed: data["running"] ? "running" : "exited",
+      ...(command ? { command } : {}), ...(typeof data["exit"] === "number" ? { exit: data["exit"] } : {}), ...(event.content_ref ? { output: event.content_ref } : {}) });
+  }
+  return [...state.values()].sort((a, b) => a.session - b.session);
+}
+export function processStatus(item: ProcessObservation, handle: "running" | "ended_unobserved" | undefined): "running" | "ended_unobserved" | "unknown" | "exited" {
+  return item.observed === "exited" ? "exited" : handle ?? "unknown";
+}
+export function branchStatus(item: BranchRecord, handle: "running" | "ready" | undefined): "running" | "ready" | "unknown" | "joined" | "resolved" {
+  return item.resolution !== null ? "resolved" : item.handoff_ref ? "joined" : handle ?? "unknown";
+}

package/src/core/program-status.ts

@@ -0,0 +1,31 @@
+/** OSC 7501 revision 0.2: program state, never a model's claim of goal completion (Q24/D11). */
+import type { ExecutionOutcome } from "./outcome.ts";
+
+export type ProgramStatus = { state: "idle" | "working" | "done" | "blocked" | "error" | "clear";
+  kind?: "permission" | "question" | "auth"; msg?: string };
+export function programStatus(input: { running: boolean; waiting?: "permission" | "question" | "auth" | null;
+  outcome?: ExecutionOutcome; goal?: string }): ProgramStatus {
+  if (input.waiting) return { state: "blocked", kind: input.waiting, msg: input.waiting === "auth" ? "Sign in to continue" : input.waiting === "permission" ? "Tool approval required" : "User input required" };
+  if (input.running) return { state: "working", msg: "Agent is working" };
+  if (input.outcome?.status === "cancelled") return { state: "idle", msg: "Turn cancelled" };
+  if (input.outcome?.status === "failed") return { state: "error", msg: "Turn failed; inspect the session" };
+  if (input.outcome?.status === "stopped") return { state: "blocked", kind: "question", msg: "Turn stopped; review evidence before continuing" };
+  if (input.goal === "awaiting_human" || input.goal === "blocked") return { state: "blocked", kind: "question", msg: "Goal awaits user review" };
+  if (input.outcome?.reason === "model_end") return { state: "done", msg: input.goal === "verified" ? "Goal verified against its contract" : "Turn finished; goal verification incomplete" };
+  return { state: "idle", msg: "Ready for a request" };
+}
+export const PROGRAM_STATUS_QUERY = "\x1b]7501;?\x1b\\";
+export function programStatusReply(sequence: string): boolean { return /^\x1b\]7501;\?[^\x00-\x1f\x7f]*(?:\x07|\x1b\\)$/.test(sequence); }
+
+export function encodeProgramStatus(status: ProgramStatus, id: string): string {
+  if (id.length > 128 || id.split("/").length > 8 || !id.split("/").every(part => /^[A-Za-z0-9_.+-]{1,32}$/.test(part))) throw Error("invalid program status id");
+  let message = "", size = 0;
+  // Protocol's decoded UTF-8 cap. Remove controls before encoding; never split a code point.
+  for (const point of (status.msg ?? "").replace(/[\x00-\x1f\x7f-\x9f\p{Cf}]/gu, " ")) {
+    const bytes = new TextEncoder().encode(point); if (size + bytes.length > 2048) break;
+    message += point; size += bytes.length;
+  }
+  const encoded = btoa(Array.from(new TextEncoder().encode(message), byte => String.fromCharCode(byte)).join(""));
+  return `\x1b]7501;state=${status.state}:app=xeno:id=${id}` +
+    (status.state === "blocked" && status.kind ? `:kind=${status.kind}` : "") + (message ? `:msg=${encoded}` : "") + "\x1b\\";
+}