@visual-z/xeno 0.1.0

package/src/core/environment.ts

@@ -0,0 +1,29 @@
+/**
+ * Facts about the machine, fixed at session start.
+ *
+ * Without them the model spends its first requests discovering what one
+ * `uname` / `pwd` / `git status` would have told it (Meta-Harness and
+ * LangChain's LocalContext middleware inject the same snapshot for that
+ * reason). They go into the frozen prefix, which a resumed session reads
+ * back from its saved context rather than rebuilding, so a date that has
+ * moved on by the next day does not change the cached prefix.
+ */
+export interface SessionEnvironment {
+  platform: string;
+  shell: string;
+  cwd: string;
+  /** Local calendar date, YYYY-MM-DD. */
+  date: string;
+  git: boolean;
+}
+
+export function environmentSection(env: SessionEnvironment): string {
+  return [
+    "Environment (recorded at session start):",
+    `- Platform: ${env.platform}`,
+    `- Shell: ${env.shell}`,
+    `- Working directory: ${env.cwd}`,
+    `- Date: ${env.date}`,
+    `- Git repository: ${env.git ? "yes" : "no"}`,
+  ].join("\n");
+}

package/src/core/event-validation.ts

@@ -0,0 +1,99 @@
+/** D8/D11: malformed durable data is corruption, never a valid empty event. */
+import type { LogEvent, NodeRef } from "./events.ts";
+import { isExecutionOutcome } from "./outcome.ts";
+import { isJsonValue, isToolDiagnostic } from "./tool-contract.ts";
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+const strings = (value: unknown): boolean => Array.isArray(value) && value.every((v) => typeof v === "string");
+const stringMap = (value: unknown): boolean => isRecord(value) && Object.values(value).every((v) => typeof v === "string");
+const optionalString = (value: unknown): boolean => value === undefined || typeof value === "string";
+const natural = (value: unknown): boolean => Number.isSafeInteger(value) && Number(value) >= 0;
+export function validNodeRef(value: unknown): value is NodeRef {
+  return isRecord(value) && Number.isSafeInteger(value["node"]) && Number(value["node"]) >= 0 &&
+    typeof value["log_ref"] === "string" && typeof value["sha256"] === "string" &&
+    (value["at_event"] === undefined || typeof value["at_event"] === "string");
+}
+
+export function isLogEvent(value: unknown): value is LogEvent {
+  if (!isRecord(value) || typeof value["id"] !== "string" || value["id"].length === 0 || typeof value["at"] !== "string") return false;
+  if (value["outcome"] !== undefined && !isExecutionOutcome(value["outcome"])) return false;
+  if (value["work_id"] !== undefined && !(typeof value["work_id"] === "string" && value["work_id"].trim().length > 0)) return false;
+  const carried = value["carried_from"];
+  if (carried !== undefined && !(isRecord(carried) && natural(carried["node"]) && typeof carried["event"] === "string")) return false;
+  const has = (...keys: string[]): boolean => keys.every((key) => typeof value[key] === "string");
+  switch (value["t"]) {
+    case "user": return has("text");
+    case "guidance": return has("text") && ["continuation", "repetition", "budget", "boundary", "stall", "output_recovery", "completion_review", "churn", "deadline"].includes(String(value["reason"])) && strings(value["sources"]);
+    case "interrupt": return has("user_id");
+    case "assistant": return (value["stop_reason"] === null || optionalString(value["stop_reason"])) && Array.isArray(value["blocks"]) && value["blocks"].every((b: unknown) => {
+      if (!isRecord(b)) return false;
+      if (b["type"] === "text") return typeof b["text"] === "string";
+      if (b["type"] === "thinking") return typeof b["text"] === "string" && "raw" in b;
+      return b["type"] === "tool_use" && typeof b["call_id"] === "string" && typeof b["name"] === "string" && "input" in b;
+    });
+    case "tool_result": {
+      if (value["data"] !== undefined && !isJsonValue(value["data"])) return false;
+      if (value["diagnostic"] !== undefined && !isToolDiagnostic(value["diagnostic"])) return false;
+      if (!has("call_id", "content") || typeof value["ok"] !== "boolean") return false;
+      if (!optionalString(value["content_sha256"])) return false;
+      if (!optionalString(value["observation_sha256"])) return false;
+      const artifact = value["content_ref"];
+      if (artifact !== undefined && !(isRecord(artifact) && typeof artifact["sha256"] === "string" &&
+          typeof artifact["path"] === "string" && natural(artifact["bytes"]))) return false;
+      const effect = value["effect"];
+      if (effect === undefined) return true;
+      if (!isRecord(effect)) return false;
+      if (effect["kind"] === "command") return typeof effect["cmd"] === "string" && Number.isInteger(effect["exit"]) &&
+        optionalString(effect["gate"]) && optionalString(effect["workspace_sha256"]);
+      if (effect["kind"] === "read") return typeof effect["path"] === "string" && typeof effect["sha256"] === "string" &&
+        (effect["ranges"] === undefined || (Array.isArray(effect["ranges"]) && effect["ranges"].every((r: unknown) =>
+          Array.isArray(r) && r.length === 2 && r.every((n) => Number.isSafeInteger(n)) && r[0] >= 1 && r[1] >= r[0])));
+      return effect["kind"] === "edit" && typeof effect["path"] === "string" && typeof effect["sha256_after"] === "string" &&
+        (effect["sha256_before"] === null || typeof effect["sha256_before"] === "string");
+    }
+    case "cut": return has("handoff_ref") && ["trigger", "hard_limit", "model_checkpoint"].includes(String(value["reason"])) &&
+      optionalString(value["retained_from"]) &&
+      (value["next_node"] === undefined || natural(value["next_node"])) && optionalString(value["next_model"]) &&
+      (value["handoff_tokens"] === undefined || (typeof value["handoff_tokens"] === "number" && Number.isFinite(value["handoff_tokens"]) && value["handoff_tokens"] > 0)) &&
+      (value["predecessor"] === null || validNodeRef(value["predecessor"]));
+    case "claim": {
+      const q = value["evidence"];
+      return has("what") && isRecord(q) && (typeof q["gate"] === "string" || typeof q["command"] === "string");
+    }
+    case "decision": return has("chose", "because") && (value["rejected"] === undefined || strings(value["rejected"]));
+    case "pitfall": return has("tried", "failed_because");
+    case "blocked": return has("what", "reason");
+    case "question": return has("text");
+    case "next_action": return has("what", "next_action");
+    case "evidence_link": return has("work", "what", "source") && optionalString(value["resource"]) && optionalString(value["version"]) &&
+      optionalString(value["supersedes"]) && (value["observed_version"] === null || optionalString(value["observed_version"]));
+    case "work_status": return has("work_id", "what") && ["unblock", "reopen", "cancel"].includes(String(value["operation"])) &&
+      optionalString(value["reason"]) && (value["operation"] === "cancel" ||
+        (typeof value["next_action"] === "string" && value["next_action"].trim().length > 0));
+    case "snapshot": return stringMap(value["added"]) && stringMap(value["changed"]) && strings(value["removed"]) &&
+      strings(value["undeclared"]) && strings(value["declared_but_unchanged"]) && optionalString(value["workspace_sha256"]) &&
+      (value["phase"] === undefined || value["phase"] === "turn" || value["phase"] === "idle");
+    case "rewind": return ["both", "files", "context"].includes(String(value["mode"])) && validNodeRef(value["from"]) &&
+      has("prompt") && strings(value["restored"]) && strings(value["removed"]) && strings(value["unrecoverable"]) && strings(value["divergence"]);
+    case "spawn": {
+      const input = value["input"];
+      if (input !== undefined) {
+        if (!isRecord(input) || typeof input["source_event"] !== "string" || !strings(input["tools"]) ||
+            !Number.isSafeInteger(input["max_turns"]) || Number(input["max_turns"]) < 1 || !isRecord(input["workspace"])) return false;
+        const workspace = input["workspace"];
+        if (!(workspace["kind"] === "shared_readonly" || (workspace["kind"] === "git_tree" &&
+            typeof workspace["head"] === "string" && typeof workspace["tree"] === "string"))) return false;
+      }
+      return validNodeRef(value["branch"]) && has("purpose") && (value["workspace"] === undefined ||
+      (isRecord(value["workspace"]) && typeof value["workspace"]["path"] === "string" && typeof value["workspace"]["branch"] === "string"));
+    }
+    case "joined": return validNodeRef(value["branch"]) && has("handoff_ref", "summary") && optionalString(value["model"]) &&
+      (value["tip"] === undefined || validNodeRef(value["tip"]));
+    case "adopt": return validNodeRef(value["branch"]) && (value["next_node"] === undefined || natural(value["next_node"])) &&
+      (value["applied"] === undefined || value["applied"] === true);
+    case "discard": return validNodeRef(value["branch"]) && has("reason");
+    default: return false;
+  }
+}

package/src/core/events.ts

@@ -0,0 +1,486 @@
+/**
+ * Append-only event log types.
+ *
+ * Two hard rules, both load-bearing:
+ *
+ * 1. APPEND REFERENCES, NEVER COPIES (decision D8). A `cut` event stores the id of
+ *    the handoff it produced and a ref to its predecessor segment -- never the
+ *    history it replaces. Codex CLI re-embeds the full `replacement_history` into
+ *    its rollout JSONL on every compaction, which is O(n^2) on disk and has been
+ *    reported to reach 42 GB (openai/codex#41806). The rule exists to make that
+ *    shape unrepresentable.
+ *
+ * 2. HARNESS-DERIVED VS MODEL-ANNOTATED. Harness events are produced from things
+ *    that cannot be wrong: the user typed this, the tool exited with this code.
+ *    Model-annotated events are optional, may be wrong, and always have a
+ *    deterministic fallback. Nothing load-bearing depends on the model's honesty --
+ *    in particular, verification comes from exit codes, never from the model
+ *    saying the tests passed.
+ */
+
+import type { ExecutionOutcome } from "./outcome.ts";
+import type { JsonValue, ToolDiagnostic } from "./tool-contract.ts";
+
+export type EventId = string;
+export type Sha256 = string;
+export type IsoTime = string;
+
+/** Inclusive 1-indexed line range, matching how editors and tools report them. */
+export type LineRange = readonly [start: number, end: number];
+
+/**
+ * A pointer to one node of the session tree.
+ *
+ * A single parent pointer is what makes the log a tree rather than a list --
+ * the linear case is the degenerate tree where every node has exactly one
+ * child. `node` is the ALLOCATION number, not a position in the tree:
+ * structure lives only in parent pointers, the way a commit hash is an
+ * identity and the parent link is the shape.
+ */
+export type NodeRef = {
+  node: number;
+  log_ref: string;
+  sha256: Sha256;
+  /**
+   * Where in the parent this node branched off. Omitted means the parent's
+   * current end.
+   *
+   * An event id rather than a turn index. An index is only stable while
+   * nothing upstream can be inserted, edited or compacted, and while that
+   * holds inside a node today it is a property of the storage rather than of
+   * the pointer. The id already exists, is already unique, and gives one more
+   * thing for free: a pointer at an event that is not there can be detected,
+   * where an out-of-range index can only be range-checked.
+   */
+  at_event?: EventId;
+};
+
+// ---------------------------------------------------------------------------
+// Effects: what a tool call actually did, as classified by the tool registry.
+// ---------------------------------------------------------------------------
+
+/**
+ * `gate` is attached by the harness from configured gate patterns, not guessed
+ * from the command text. A command with no configured gate is still recorded --
+ * it just counts as weaker evidence than a named gate.
+ */
+export type Effect =
+  | { kind: "read"; path: string; sha256: Sha256; ranges?: readonly LineRange[] }
+  | { kind: "edit"; path: string; sha256_before: Sha256 | null; sha256_after: Sha256 }
+  | { kind: "command"; cmd: string; exit: number; gate?: string; workspace_sha256?: Sha256 };
+
+// ---------------------------------------------------------------------------
+// Harness-derived events
+// ---------------------------------------------------------------------------
+
+export interface UserEvent {
+  t: "user";
+  id: EventId;
+  at: IsoTime;
+  text: string;
+}
+
+/** A factual harness notice, appended once rather than rewriting the prompt (N.1). */
+export interface GuidanceEvent {
+  t: "guidance";
+  id: EventId;
+  at: IsoTime;
+  reason: "continuation" | "repetition" | "budget" | "boundary" | "stall" | "output_recovery" | "completion_review" | "churn" | "deadline";
+  text: string;
+  sources: readonly EventId[];
+}
+
+/**
+ * The user cancelled the turn that `user_id` opened.
+ *
+ * A later record, not a flag on that user event: the cancel happened after
+ * the prompt was written, and rewriting a committed event would violate
+ * append-only (D8). Only harness-observable facts are stored -- which prompt
+ * and when -- never the partial assistant text, which was never delivered.
+ * A cancelled generation is not a conversation that happened (same rule as
+ * AGENT_PLAYBOOK "凭证与错误文本": a failed request is not a conversation).
+ */
+export interface InterruptEvent {
+  t: "interrupt";
+  id: EventId;
+  at: IsoTime;
+  /** The user event whose turn was cancelled. */
+  user_id: EventId;
+}
+
+/**
+ * Only the shapes the projection needs to replay a turn.
+ *
+ * A thinking block carries the provider's opaque fields alongside its text.
+ * They must be replayed byte-for-byte: the API rejects blocks whose content
+ * was modified, and a block whose text is empty still has to go back verbatim.
+ * Keeping only the text would drop the signature and fail the next request --
+ * so the raw block is kept under `raw` and replayed untouched, while `text` is
+ * what a UI renders.
+ */
+export type AssistantBlock =
+  | { type: "text"; text: string }
+  | { type: "thinking"; text: string; raw: unknown }
+  /**
+   * `wire` is the provider's own per-call data beyond id, name and arguments
+   * (Gemini's thought signature), replayed verbatim like a thinking block's raw.
+   */
+  | { type: "tool_use"; call_id: string; name: string; input: unknown; wire?: unknown };
+
+export interface AssistantEvent {
+  t: "assistant";
+  id: EventId;
+  at: IsoTime;
+  blocks: readonly AssistantBlock[];
+  /** N.12: provider-observed termination, never a claim of task completion. Legacy logs omit it. */
+  stop_reason?: string | null;
+}
+
+export interface ToolResultEvent {
+  t: "tool_result";
+  id: EventId;
+  at: IsoTime;
+  call_id: string;
+  ok: boolean;
+  /** What the model sees. Large payloads belong on disk, referenced by effect. */
+  content: string;
+  /** Digest of the complete observation, even when it fits inline in the log. */
+  content_sha256?: Sha256;
+  /** O.3: semantic observation digest excludes presentation metadata. */
+  observation_sha256?: Sha256;
+  content_ref?: ArtifactRef;
+  effect?: Effect;
+  /** O.1: actual termination, independent of effect/verification; legacy logs omit it. */
+  outcome?: ExecutionOutcome;
+  /** O.3: machine-readable observations and recovery hints, not additional proof. */
+  data?: JsonValue;
+  diagnostic?: ToolDiagnostic;
+}
+
+export type ArtifactRef = { sha256: Sha256; path: string; bytes: number };
+
+/** Terminates the segment it appears in. Carries refs only -- see rule 1 above. */
+export interface CutEvent {
+  t: "cut";
+  id: EventId;
+  at: IsoTime;
+  handoff_ref: string;
+  predecessor: NodeRef | null;
+  reason: CutReason;
+  /** Durable transition intent; recovery opens this exact successor. */
+  next_node?: number;
+  next_model?: string;
+  /** V2 carried-state budget, fixed in the log for identical replay. */
+  handoff_tokens?: number;
+  /** N.8: first retained event on the effective ancestry; no copied transcript. */
+  retained_from?: EventId;
+}
+
+export type CutReason = "hard_limit" | "trigger" | "model_checkpoint";
+
+// ---------------------------------------------------------------------------
+// Model-annotated events (optional; every consumer has a fallback)
+// ---------------------------------------------------------------------------
+
+/**
+ * How a completion claim points at its proof. Resolved against the log by
+ * deriveHandoff(); a claim whose evidence does not resolve to a zero exit is
+ * surfaced as unverified rather than accepted or silently dropped.
+ */
+export type EvidenceQuery =
+  | { gate: string }
+  | { command: string };
+
+export interface ClaimEvent {
+  t: "claim";
+  id: EventId;
+  at: IsoTime;
+  what: string;
+  work_id?: string;
+  evidence: EvidenceQuery;
+  /** Set when an adopt moved this event from another node. */
+  carried_from?: CarriedFrom;
+}
+
+export interface DecisionEvent {
+  t: "decision";
+  id: EventId;
+  at: IsoTime;
+  chose: string;
+  because: string;
+  rejected?: readonly string[];
+  /** Set when an adopt moved this event from another node. */
+  carried_from?: CarriedFrom;
+}
+
+export interface PitfallEvent {
+  t: "pitfall";
+  id: EventId;
+  at: IsoTime;
+  tried: string;
+  failed_because: string;
+  /** Set when an adopt moved this event from another node. */
+  carried_from?: CarriedFrom;
+}
+
+export interface BlockedEvent {
+  t: "blocked";
+  id: EventId;
+  at: IsoTime;
+  what: string;
+  work_id?: string;
+  reason: string;
+  /** Set when an adopt moved this event from another node. */
+  carried_from?: CarriedFrom;
+}
+
+export interface QuestionEvent {
+  t: "question";
+  id: EventId;
+  at: IsoTime;
+  text: string;
+  /** Set when an adopt moved this event from another node. */
+  carried_from?: CarriedFrom;
+}
+
+/**
+ * What changed in the workspace during one turn, as a delta.
+ *
+ * A delta rather than a full listing: repeating the whole workspace every
+ * turn is the same quadratic growth D8 exists to prevent. The full set at
+ * any node is the deltas along its ancestry replayed in order.
+ *
+ * Recorded from a scan rather than from what the tools reported, because a
+ * shell command can write anywhere and its effect carries only an exit code.
+ * The two are compared, and a change nobody declared is surfaced.
+ */
+export interface SnapshotEvent {
+  t: "snapshot";
+  id: EventId;
+  at: IsoTime;
+  added: Record<string, Sha256>;
+  changed: Record<string, Sha256>;
+  removed: readonly string[];
+  /** Paths that changed with no tool claiming them. */
+  undeclared: readonly string[];
+  /** Paths a tool claimed to edit that did not change. */
+  declared_but_unchanged: readonly string[];
+  workspace_sha256?: Sha256;
+  /** Idle observations must not redefine a completed user exchange. */
+  phase?: "turn" | "idle";
+}
+
+/**
+ * Which halves of a rewind moved.
+ *
+ *   both     the default. The conversation and the workspace go back
+ *            together, so they still agree afterwards.
+ *   files    the workspace goes back, the conversation does not. The model's
+ *            context describes edits that are no longer on disk.
+ *   context  the conversation goes back, the workspace does not. Files exist
+ *            that the model has no memory of writing.
+ */
+export type RewindMode = "both" | "files" | "context";
+
+/**
+ * The workspace and the conversation were moved relative to each other.
+ *
+ * Recorded because the workspace is a projection of the log: a restore is a
+ * change no tool claimed, so without this event the next turn-boundary scan
+ * reports the whole thing as undeclared damage and the handoff inherits it.
+ *
+ * WHETHER IT REPLAYS DEPENDS ON `mode`, and the rule is the same one the
+ * whole log follows: tell the model exactly when, and only when, its picture
+ * would otherwise be wrong.
+ *
+ *   "both" does NOT replay. The context and the disk agree afterwards, and
+ *   saying "you just rewound" would carry the undone work back in another
+ *   form -- the exact thing being undone.
+ *
+ *   "files" and "context" DO replay, naming paths. They leave the two
+ *   disagreeing, and a model planning against the wrong picture is the
+ *   documented failure: with a context-only restore it "starts from bad code
+ *   with no memory of how it got there", which is worse than either state.
+ */
+export interface RewindEvent {
+  t: "rewind";
+  id: EventId;
+  at: IsoTime;
+  mode: RewindMode;
+  /** Where things were moved back to. */
+  from: NodeRef;
+  /** The prompt that opened the exchange moved back to, for a human reader. */
+  prompt: string;
+  restored: readonly string[];
+  removed: readonly string[];
+  /** Target files whose content is no longer in the blob store. */
+  unrecoverable: readonly string[];
+  /**
+   * Paths where the workspace and this conversation no longer agree, with
+   * which side is ahead. Computed from the plan, never described vaguely:
+   * "some files may differ" is not something a model can act on.
+   */
+  divergence: readonly string[];
+}
+
+// --- branch lifecycle ------------------------------------------------------
+
+/**
+ * The parent opened a branch. Carries a reference, never the branch itself.
+ */
+export interface SpawnEvent {
+  t: "spawn";
+  id: EventId;
+  at: IsoTime;
+  branch: NodeRef;
+  /** What the branch is for, in one line. */
+  purpose: string;
+  /** The isolated checkout belongs to this branch, including after restart. */
+  workspace?: { path: string; branch: string };
+  /** O.4: a task input envelope references the original request, never copies history. */
+  input?: {
+    source_event: string;
+    tools: readonly string[];
+    max_turns: number;
+    workspace: { kind: "shared_readonly" } | { kind: "git_tree"; head: string; tree: string };
+  };
+}
+
+/**
+ * A branch finished and handed its state back.
+ *
+ * `handoff_ref` is a path, and `summary` is a line the branch wrote -- the
+ * handoff's contents are never inlined here (D8). The parent reads the file
+ * when it needs the detail.
+ */
+export interface JoinedEvent {
+  t: "joined";
+  id: EventId;
+  at: IsoTime;
+  branch: NodeRef;
+  handoff_ref: string;
+  summary: string;
+  /** A branch can cut before joining; its last node need not be its root. */
+  tip?: NodeRef;
+  model?: string;
+  /** Absence in a legacy join means unknown, never inferred success. */
+  outcome?: ExecutionOutcome;
+}
+
+/** The parent took this branch as the mainline. */
+export interface AdoptEvent {
+  t: "adopt";
+  id: EventId;
+  at: IsoTime;
+  branch: NodeRef;
+  /** Commit intent after all parent tool results; recovery reuses this node. */
+  next_node?: number;
+  applied?: true;
+}
+
+/** The parent rejected this branch. Resolution, not silence (D16). */
+export interface DiscardEvent {
+  t: "discard";
+  id: EventId;
+  at: IsoTime;
+  branch: NodeRef;
+  reason: string;
+}
+
+/**
+ * Where an event was carried from, when an adopt moved it into a new node.
+ *
+ * Adopting a branch would otherwise lose the parent's post-fork annotations --
+ * including the decision that chose the branch, which is the least disposable
+ * record there is. Carrying them is free in context terms because model
+ * annotations never replay as messages; only the derivation sees them.
+ */
+export interface CarriedFrom {
+  node: number;
+  event: EventId;
+}
+
+/**
+ * The one genuinely non-derivable field. "What was I doing" can be reconstructed
+ * from the log; "what should happen next" cannot. When absent, the handoff says
+ * so via continuation_valid rather than inventing one.
+ */
+export interface NextActionEvent {
+  t: "next_action";
+  id: EventId;
+  at: IsoTime;
+  what: string;
+  work_id?: string;
+  next_action: string;
+  /** Set when an adopt moved this event from another node. */
+  carried_from?: CarriedFrom;
+}
+
+/** O.2: lifecycle changes append facts; an old title is not a task identity. */
+export interface WorkStatusEvent {
+  t: "work_status";
+  id: EventId;
+  at: IsoTime;
+  work_id: string;
+  what: string;
+  operation: "unblock" | "reopen" | "cancel";
+  next_action?: string;
+  reason?: string;
+  carried_from?: CarriedFrom;
+}
+
+/** O.6: a model associates an original observation with work; the runtime resolves its source. */
+export interface EvidenceLinkEvent {
+  t: "evidence_link"; id: EventId; at: IsoTime;
+  work: string; what: string; source: EventId;
+  resource?: string; version?: string; supersedes?: EventId;
+  /** Last version observed by the harness when this association was recorded. */
+  observed_version?: string | null;
+  carried_from?: CarriedFrom;
+}
+
+export type LogEvent =
+  | UserEvent
+  | GuidanceEvent
+  | InterruptEvent
+  | AssistantEvent
+  | ToolResultEvent
+  | EvidenceLinkEvent
+  | CutEvent
+  | SnapshotEvent
+  | RewindEvent
+  | SpawnEvent
+  | JoinedEvent
+  | AdoptEvent
+  | DiscardEvent
+  | ClaimEvent
+  | DecisionEvent
+  | PitfallEvent
+  | BlockedEvent
+  | QuestionEvent
+  | NextActionEvent
+  | WorkStatusEvent;
+
+export const HARNESS_EVENTS = [
+  "user", "guidance", "interrupt", "assistant", "tool_result", "cut", "snapshot", "rewind",
+] as const;
+export const MODEL_EVENTS = [
+  "claim", "decision", "pitfall", "blocked", "question", "next_action", "work_status", "evidence_link",
+  "spawn", "joined", "adopt", "discard",
+] as const;
+
+/**
+ * Events an adopt carries into the node it opens.
+ *
+ * Only annotations: harness events are either already in the branch's
+ * ancestry or are parent actions the branch should not inherit.
+ */
+export const CARRYABLE_EVENTS = [
+  "claim", "decision", "pitfall", "blocked", "question", "next_action", "work_status", "evidence_link",
+] as const;
+
+export type CarryableEvent = Extract<LogEvent, { t: (typeof CARRYABLE_EVENTS)[number] }>;
+
+export function isHarnessEvent(e: LogEvent): boolean {
+  return (HARNESS_EVENTS as readonly string[]).includes(e.t);
+}