@visual-z/xeno 0.8.3 → 0.9.0

package/src/core/permissions.ts

@@ -1,410 +0,0 @@
-/**
- * Pure permission rules: which tools the model may see, and whether a
- * call is allow / ask / deny.
- *
- * Approval is the last look at what is about to run, not a boundary.
- * Path tools are already confined to the workspace root; host commands
- * are not, which is why shell entry points default to ask.
- *
- * This module must stay free of I/O, clocks, and randomness. The CLI
- * compiles flags and session memory into a rule list; this file only
- * matches them. There is no command-danger heuristic: a screen that
- * misses `find . -delete` is worse than none, because it implies
- * someone is checking.
- */
-
-export type PermissionAction = "allow" | "ask" | "deny";
-
-export interface PermissionRequest {
-  readonly tool: string;
-  /** Exact command string for bash; omitted for tools that have none. */
-  readonly command?: string;
-  /** Normalized workspace-relative or external absolute file resources. */
-  readonly paths?: readonly string[];
-}
-
-export interface PermissionRule {
-  readonly action: PermissionAction;
-  /** Absent matches every tool. */
-  readonly tool?: string;
-  /** Absent matches every command. When set, matches only this exact string. */
-  readonly command?: string;
-  /** Literal argv prefix, matched only for a single command without expansion. */
-  readonly commandPrefix?: readonly string[];
-  readonly path?: string;
-  /** Portable path glob: *, ?, and **; no brace or character-class expansion. */
-  readonly pathGlob?: string;
-}
-
-/**
- * Who contributed the tool. `builtin` is the only producer today.
- * `extension` is in the union so `--no-builtin-tools` can keep a
- * non-builtin tool without a later schema change across layers.
- */
-export type ToolSource = "builtin" | "extension";
-
-/** Task capabilities are frozen once at session creation (O.7); not permissions. */
-export const TOOL_PROFILES = {
-  // worktree joined the measured ten (2026-10-11, feat-worktree-tool): without
-  // it a model needing isolation had no checkout it was allowed to edit.
-  coding: ["read", "grep", "find", "write", "edit", "environment", "exec_command", "write_stdin", "history", "note", "worktree"],
-  foundation: ["read", "grep", "find", "write", "edit", "environment", "exec_command", "write_stdin", "history", "note", "worktree", "question", "apply_patch", "diff", "webfetch", "websearch", "format", "lsp"],
-  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. */
-  readonly exclude?: readonly string[];
-  /** `--no-tools`: start from nothing. Ignored when `only` is set. */
-  readonly none?: boolean;
-  /**
-   * `--no-builtin-tools`. Drops `source === "builtin"` (and untagged tools,
-   * which are builtin). Ignored when `only` is set: an explicit `--tools`
-   * names a specific tool and is a stronger statement than "not that category".
-   */
-  readonly noBuiltin?: boolean;
-}
-
-/**
- * The flag a no-tty refusal names so a pipeline can choose explicitly.
- *
- * Session memory is not this flag: session memory dies with the process.
- * A persisted "always allow" would fire months later when nobody is watching.
- */
-export const ALLOW_TOOLS_FLAG = "--allow-tools";
-
-/**
- * Product default. Shell entry points ask because their effects are not
- * confined to the workspace root; path tools keep their own confinement.
- */
-export function defaultRules(): readonly PermissionRule[] {
-  return [
-    // Templates are ordinary source; actual environment values deserve the
-    // same last look as commands. Indirect readers also check read resources.
-    { action: "allow", tool: "read", pathGlob: "**/.env.example" },
-    { action: "ask", tool: "read", pathGlob: "**/.env" },
-    { action: "ask", tool: "read", pathGlob: "**/.env.*" },
-    { action: "ask", tool: "bash" },
-    // 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" },
-  ];
-}
-
-/**
- * CLI opt-ins compiled to one process-scoped rule list. YOLO permits every
- * tool; capability admission and path confinement still apply (D13).
- * Neither this flag nor remembered approvals become a persisted policy.
- */
-export function rulesWithAllowTools(
-  allowTools: readonly string[],
-  options: { readonly yolo?: boolean } = {},
-): PermissionRule[] {
-  if (options.yolo === true) return [{ action: "allow" }];
-  return [
-    ...allowTools.map((tool) => ({ action: "allow" as const, tool })),
-    ...defaultRules(),
-  ];
-}
-
-export function ruleMatches(rule: PermissionRule, request: PermissionRequest): boolean {
-  if (rule.tool !== undefined && rule.tool !== request.tool) return false;
-  if (rule.command !== undefined && rule.command !== request.command) return false;
-  if (rule.commandPrefix !== undefined) {
-    const words = request.command === undefined ? null : literalCommandWords(request.command);
-    if (!words || rule.commandPrefix.length === 0 || rule.commandPrefix.some((word, i) => words[i] !== word)) return false;
-  }
-  if (rule.path !== undefined && !request.paths?.some(path => normalizePermissionPath(path) === normalizePermissionPath(rule.path!))) return false;
-  if (rule.pathGlob !== undefined && !request.paths?.some(path => permissionPathMatches(rule.pathGlob!, path))) return false;
-  return true;
-}
-
-/**
- * First matching rule wins. An empty list allows: the tool tests pass no
- * rules because they are testing the tool, not the gate. The CLI always
- * supplies the current process's compiled policy.
- */
-export function decide(
-  rules: readonly PermissionRule[],
-  request: PermissionRequest,
-): PermissionAction {
-  // A multi-file call needs every resource admitted. A broad allow for its
-  // first path must not conceal a denial on a later file (D13 / R13).
-  if (request.paths && request.paths.length > 1) {
-    const actions = request.paths.map(path => decide(rules, { ...request, paths: [path] }));
-    return actions.includes("deny") ? "deny" : actions.includes("ask") ? "ask" : "allow";
-  }
-  for (const rule of rules) {
-    if (ruleMatches(rule, request)) return rule.action;
-  }
-  return "allow";
-}
-
-/** Configured denial is a ceiling; in-memory approval can only resolve asks. */
-export function decideWithSessionRules(
-  configured: readonly PermissionRule[], remembered: readonly PermissionRule[], request: PermissionRequest,
-): PermissionAction {
-  if (decide(configured, request) === "deny") return "deny";
-  return decide([...remembered, ...configured], request);
-}
-
-/**
- * Where a gate outcome came from, for the durable approval record
- * (feat-approval-events). `auto` is an allow by a rule with no selector --
- * what `--yolo` compiles to -- so "no approval was required" is derived from
- * the rule list itself rather than from a side flag. `none` means no rule
- * matched and the empty-list default allowed: no policy was consulted.
- */
-export type DecisionSource = "session_rule" | "config" | "auto" | "none";
-export interface DecisionExplanation {
-  readonly action: PermissionAction;
-  readonly source: DecisionSource;
-  readonly rule?: PermissionRule;
-}
-
-/** Mirrors decide() exactly, but keeps the index of the rule that produced the action. */
-function explainList(rules: readonly PermissionRule[], request: PermissionRequest): { action: PermissionAction; index?: number } {
-  if (request.paths && request.paths.length > 1) {
-    const each = request.paths.map(path => explainList(rules, { ...request, paths: [path] }));
-    const actions = each.map(item => item.action);
-    const action: PermissionAction = actions.includes("deny") ? "deny" : actions.includes("ask") ? "ask" : "allow";
-    return each.find(item => item.action === action)!;
-  }
-  const index = rules.findIndex(rule => ruleMatches(rule, request));
-  return index < 0 ? { action: "allow" } : { action: rules[index]!.action, index };
-}
-
-/** decideWithSessionRules plus the rule that decided; the action is always identical (property-tested). */
-export function explainDecision(
-  configured: readonly PermissionRule[], remembered: readonly PermissionRule[], request: PermissionRequest,
-): DecisionExplanation {
-  const ceiling = explainList(configured, request);
-  if (ceiling.action === "deny") return { action: "deny", source: "config", rule: configured[ceiling.index!]! };
-  const combined = [...remembered, ...configured];
-  const found = explainList(combined, request);
-  if (found.index === undefined) return { action: found.action, source: "none" };
-  const rule = combined[found.index]!;
-  const unconditional = rule.tool === undefined && rule.command === undefined && rule.commandPrefix === undefined &&
-    rule.path === undefined && rule.pathGlob === undefined;
-  return { action: found.action, rule,
-    source: found.index < remembered.length ? "session_rule" : unconditional && rule.action === "allow" ? "auto" : "config" };
-}
-
-/**
- * A call needs a decision when the product default would not silently allow
- * it, or when the effective policy did not. Calls outside both -- confined
- * reads and edits under the default -- had nobody's judgement to record.
- */
-export function approvalNeeded(request: PermissionRequest, effective: PermissionAction): boolean {
-  return effective !== "allow" || decide(defaultRules(), request) !== "allow";
-}
-
-/** Stable one-line rule text for the log and the export; field order is fixed. */
-export function describeRule(rule: PermissionRule): string {
-  return [rule.action, rule.tool ?? "*",
-    ...(rule.command !== undefined ? [`command=${JSON.stringify(rule.command)}`] : []),
-    ...(rule.commandPrefix !== undefined ? [`commandPrefix=${JSON.stringify(rule.commandPrefix.join(" "))}`] : []),
-    ...(rule.path !== undefined ? [`path=${JSON.stringify(rule.path)}`] : []),
-    ...(rule.pathGlob !== undefined ? [`pathGlob=${JSON.stringify(rule.pathGlob)}`] : [])].join(" ");
-}
-
-/** Lexical normalization is pure; the store adds canonical symlink resources. */
-export function normalizePermissionPath(path: string): string {
-  const absolute = path.startsWith("/");
-  const parts: string[] = [];
-  for (const part of path.split("/")) {
-    if (!part || part === ".") continue;
-    if (part === ".." && parts.length > 0 && parts.at(-1) !== "..") parts.pop();
-    else if (part === ".." && absolute) continue;
-    else parts.push(part);
-  }
-  return (absolute ? "/" : "") + parts.join("/") || ".";
-}
-
-/** Dynamic programming avoids exponential regexp backtracking on model input. */
-export function permissionPathMatches(pattern: string, path: string): boolean {
-  const glob = normalizePermissionPath(pattern), value = normalizePermissionPath(path);
-  let row = Array<boolean>(value.length + 1).fill(false); row[0] = true;
-  for (let i = 0; i < glob.length; i++) {
-    const char = glob[i]!;
-    const next = Array<boolean>(value.length + 1).fill(false);
-    if (char === "*") {
-      const deep = glob[i + 1] === "*";
-      if (deep) i++;
-      // **/ also matches zero directories, as in **/.env at the root.
-      const directories = deep && glob[i + 1] === "/";
-      if (directories) i++;
-      next[0] = row[0]!;
-      for (let j = 1; j <= value.length; j++) {
-        next[j] = row[j]! || ((deep || value[j - 1] !== "/") && next[j - 1]!);
-        if (directories && value[j - 1] !== "/") next[j] = row[j]!;
-      }
-      // A globstar followed by slash may consume complete directories only.
-      if (directories) {
-        let reachable = row[0]!;
-        for (let j = 1; j <= value.length; j++) {
-          reachable = reachable || row[j]!;
-          next[j] = row[j]! || (value[j - 1] === "/" && reachable);
-        }
-      }
-    } else {
-      for (let j = 1; j <= value.length; j++) next[j] = row[j - 1]! &&
-        (char === "?" ? value[j - 1] !== "/" : char === value[j - 1]);
-    }
-    row = next;
-  }
-  return row[value.length]!;
-}
-
-/**
- * This is a prefix matcher, never a command-danger classifier. Unknown shell
- * syntax fails to match and therefore retains the full-command ask (D13).
- */
-export function literalCommandWords(command: string): string[] | null {
-  const words: string[] = [];
-  let word = "", started = false, quote: "'" | '"' | null = null;
-  for (let i = 0; i < command.length; i++) {
-    const char = command[i]!;
-    if (char === "\n" || char === "\r" || char === "\0") return null;
-    if (quote === "'") {
-      if (char === "'") quote = null; else word += char;
-      continue;
-    }
-    if (char === "\\") {
-      const escaped = command[++i];
-      if (escaped === undefined || escaped === "\n" || escaped === "\r") return null;
-      // Bash double quotes retain backslash before ordinary characters.
-      word += quote === '"' && !['$', '`', '"', "\\"].includes(escaped) ? `\\${escaped}` : escaped;
-      started = true; continue;
-    }
-    if (quote === '"') {
-      if (char === '"') quote = null;
-      else if (char === "$" || char === "`") return null;
-      else word += char;
-      continue;
-    }
-    if (char === "'" || char === '"') { quote = char; started = true; continue; }
-    if (char === " " || char === "\t") { if (started) words.push(word); word = ""; started = false; continue; }
-    if (";|&<>($`*?[]{}~#".includes(char)) return null;
-    word += char; started = true;
-  }
-  if (quote !== null) return null;
-  if (started) words.push(word);
-  return words.length ? words : null;
-}
-
-/** Unknown config keys are errors: a typo must not silently weaken a policy. */
-export function parsePermissionRule(value: unknown): PermissionRule {
-  if (!value || typeof value !== "object" || Array.isArray(value)) throw Error("permission rule must be an object");
-  const rule = value as Record<string, unknown>;
-  if (Object.keys(rule).some(key => !["action", "tool", "command", "commandPrefix", "path", "pathGlob"].includes(key))) throw Error("unknown permission rule field");
-  if (!["allow", "ask", "deny"].includes(String(rule["action"]))) throw Error("permission rule action must be allow, ask or deny");
-  for (const key of ["tool", "command", "path", "pathGlob"]) {
-    if (rule[key] !== undefined && (typeof rule[key] !== "string" || !String(rule[key]).trim() || String(rule[key]).includes("\0"))) throw Error(`permission ${key} must be a nonempty string`);
-  }
-  if (rule["path"] !== undefined && rule["pathGlob"] !== undefined) throw Error("permission path and pathGlob are mutually exclusive");
-  if (typeof rule["pathGlob"] === "string" && /[\[\]{}]/.test(rule["pathGlob"])) throw Error("permission pathGlob supports only *, ? and **");
-  const prefix = rule["commandPrefix"];
-  if (prefix !== undefined && (!Array.isArray(prefix) || prefix.length === 0 || prefix.some(word => typeof word !== "string" || !word || /[\r\n\0]/.test(word)))) throw Error("permission commandPrefix must contain literal argv tokens");
-  if (prefix !== undefined && rule["command"] !== undefined) throw Error("permission command and commandPrefix are mutually exclusive");
-  return structuredClone(value) as PermissionRule;
-}
-
-/**
- * Comma-separated flag values. Empty tokens are dropped so `--tools a,,b`
- * does not invent a blank name.
- */
-export function parseToolList(raw: string): string[] {
-  return raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
-}
-
-/**
- * Names the model will see. An excluded tool has to vanish here -- leaving
- * it in the schema and failing at call time teaches the model to retry
- * the same call and burn tokens.
- *
- * `--tools` is a strict allowlist. `--no-tools` starts from nothing, then
- * `--tools` can add names back (pi's combination). `--exclude-tools` is
- * applied last.
- */
-export function selectToolNames(
-  available: readonly string[],
-  selection: ToolSelection,
-): string[] {
-  let names: string[];
-  if (selection.only !== undefined) {
-    const allow = new Set(selection.only);
-    names = available.filter((n) => allow.has(n));
-  } else if (selection.none === true) {
-    names = [];
-  } else {
-    names = [...available];
-  }
-  if (selection.exclude !== undefined) {
-    const ex = new Set(selection.exclude);
-    names = names.filter((n) => !ex.has(n));
-  }
-  return names;
-}
-
-export function selectTools<T extends { name: string; source?: ToolSource }>(
-  tools: readonly T[],
-  selection: ToolSelection,
-): 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
-  // no-op until every schema is recut.
-  if (selection.noBuiltin === true && selection.only === undefined) {
-    selected = selected.filter((t) => (t.source ?? "builtin") !== "builtin");
-  }
-  return selected;
-}
-
-export function permissionRequest(name: string, input: unknown): PermissionRequest {
-  if (typeof input !== "object" || input === null) {
-    return { tool: name };
-  }
-  const fields = input as { readonly [k: string]: unknown };
-  const command = ["bash", "exec_command", "environment"].includes(name) ? fields[name === "exec_command" ? "cmd" : "command"] : undefined;
-  const paths = typeof fields["path"] === "string" ? [fields["path"]]
-    : Array.isArray(fields["paths"]) && fields["paths"].every(path => typeof path === "string") ? fields["paths"] as string[] : undefined;
-  return { tool: name, ...(typeof command === "string" ? { command } : {}),
-    ...(paths ? { paths: paths.map(normalizePermissionPath) } : {}) };
-}
-
-/**
- * Why this ask became a deny: nobody could be asked. Names the flag that
- * would have allowed the call without asking, so a CI author can choose.
- */
-export function askWithoutTtyMessage(request: PermissionRequest): string {
-  return (
-    `refused: ${request.tool} requires approval and there is no tty to ask. ` +
-    `Pass ${ALLOW_TOOLS_FLAG} ${request.tool} to allow it without asking.`
-  );
-}
-
-export function deniedMessage(request: PermissionRequest): string {
-  return `refused: ${request.tool} was denied`;
-}

package/src/core/process-receipt.ts

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

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

@@ -1,40 +0,0 @@
-/** 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 };
-/** S.1: what a finished turn's ledger says, in one line; the status itself stays "done". */
-const FINISHED: Readonly<Record<string, string>> = {
-  verified: "Goal verified against its contract",
-  checked: "Turn finished; changes passed a fresh check",
-  unchecked: "Turn finished; changes not checked",
-  needs_work: "Turn finished; declared checks incomplete",
-  not_applicable: "Turn finished",
-};
-
-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") return { state: "blocked", kind: "question", msg: "Goal awaits user review" };
-  if (input.outcome?.reason === "model_end") return { state: "done", msg: FINISHED[input.goal ?? "not_applicable"] ?? FINISHED["not_applicable"]! };
-  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\\";
-}