┌─────────────────────────────┐
                            │         KHAELOR TUI         │
                            │  composer · timeline · bars │
                            └────┬───────────────▲────────┘
                    KernelCommand│               │ coalesced events (~16 ms)
                                 │               │
   ┌─────────────────────────────▼───────────────┴─────────────────────────────┐
   │                              EVENT BUS (typed, in-process)                │
   │        durable events ──► SessionStore (JSONL append, write-ahead)        │
   │        ephemeral deltas ──► TUI coalescer only                            │
   └────────────▲───────────────────▲──────────────────────▲───────────────────┘
                │                   │                      │
        ┌───────┴────────┐  ┌───────┴────────┐   ┌─────────┴─────────┐
        │ Session Engine │  │  Agent Kernel  │   │  Process Manager  │
        │ log·projections│◄─┤  (state-derived│   │ (background procs)│
        │ resume=replay  │  │   loop, ADR-2) │   └─────────▲─────────┘
        └───────▲────────┘  └───┬───┬───┬────┘             │
                │               │   │   │                  │
                │      ┌────────┘   │   └─────────┐        │
                │      ▼            ▼             ▼        │
                │ ┌──────────┐ ┌──────────┐ ┌───────────┐  │
                │ │ Context  │ │  Model   │ │   Tool    │──┘
                │ │ Engine   │ │ Runtime  │ │  Runtime  │──► Permissions
                │ │ (ADR-6/7)│ │ (ADR-10) │ │  (ADR-8)  │    (ADR-9)
                │ └────┬─────┘ └────┬─────┘ └─────┬─────┘
                │      │            │             │
                └──────┤       Anthropic API      ▼
                       ▼        (official SDK) ┌───────────┐
                ┌─────────────┐                │ Workspace │──► files · processes
                │ Repository  │───────────────►│ (ADR-13)  │
                │ Intelligence│                └───────────┘
                └─────────────┘

Layer 0   shared                          (imports nothing)
Layer 1   config · workspace · anthropic · session
Layer 2   permissions · repository · tools · context
Layer 3   agent
Layer 4   tui
Layer 5   cli                             (composition root)

// shared/events.ts — full definitions in EVENT_MODEL.md
export type DurableEvent = /* discriminated union, EVENT_MODEL.md §4 */;
export type EphemeralEvent = /* discriminated union, EVENT_MODEL.md §4 */;
export type KhaelorEvent = DurableEvent | EphemeralEvent;

export interface EventBus {
  publishDurable(e: DurableEventInput): DurableEvent;   // append-then-publish; assigns seq/id/ts
  publishEphemeral(e: EphemeralEvent): void;
  on<T extends KhaelorEvent["type"]>(
    type: T,
    handler: (e: Extract<KhaelorEvent, { type: T }>) => void,
  ): Unsubscribe;
  onAny(handler: (e: KhaelorEvent) => void): Unsubscribe;
}

// shared/commands.ts — the TUI→engine channel
export type KernelCommand =
  | { kind: "submit-message"; text: string; mentions: FileMention[] }
  | { kind: "steer"; text: string }
  | { kind: "interrupt" }
  | { kind: "permission-response"; requestId: string; decision: "once" | "always" | "deny" }
  | { kind: "slash"; command: string; args: string }
  | { kind: "shell"; command: string }          // "!git status" composer shortcut
  | { kind: "quit" };

export type Unsubscribe = () => void;
export type Result<T, E = KhaelorError> = { ok: true; value: T } | { ok: false; error: E };

export interface KhaelorConfig {
  model: string;                       // Anthropic model id — never hard-coded lists (CLAUDE.md §6)
  auxModel: string;                    // cheaper model for compaction summaries (ADR-10)
  thinking: "off" | "adaptive" | "always";
  maxOutputTokens: number;
  permissions: Record<string, PermissionAction>;   // capability → allow|ask|deny
  theme: ThemeConfig;
}
export function loadConfig(argv: ParsedArgs, cwd: string): Promise<ResolvedConfig>;
export function discoverInstructions(cwd: string): Promise<InstructionFile[]>; // ordered, global → nested
export function persistPermissionGrant(scope: "project", rule: PermissionRule): Promise<void>; // ADR-9

export interface Workspace {
  cwd(): string;
  readFile(path: string): Promise<string>;
  writeFile(path: string, content: string): Promise<void>;   // atomic: tmp + rename
  exec(command: Command): Promise<ProcessResult>;
}
export interface Command {
  cmd: string;                       // run via user shell for `bash` tool
  cwd?: string;
  timeoutMs: number;                 // hard ceiling; ADR-8: long commands redirect to `process`
  env?: Record<string, string>;
  signal?: AbortSignal;
}
export interface ProcessResult {
  exitCode: number | null;           // null = killed by timeout/signal
  stdout: string; stderr: string;
  durationMs: number;
  truncated: boolean;
}
export class LocalWorkspace implements Workspace { /* only module touching node:fs/child_process */ }
// Tool-side helpers PARAMETERIZED BY Workspace (never fattening the interface — ADR-13):
export function statFile(ws: Workspace, path: string): Promise<FileStat>;
export function fileExists(ws: Workspace, path: string): Promise<boolean>;

export type Capability =
  | "file.read" | "file.write.project" | "process.execute"
  | "network.access" | "git.modify" | "filesystem.outsideProject";
export type PermissionAction = "allow" | "ask" | "deny";
export interface PermissionRule { capability: Capability; pattern: string; action: PermissionAction; }

export interface PermissionRequest {
  capability: Capability;
  descriptor: string;               // e.g. "bash: npm install", "write: src/agent/kernel.ts"
  toolUseId: string;
  suggestion?: PermissionRule;      // "always allow `git push *`" — omitted when the command
}                                   // contains shell operators (Hermes guard, ADR-9)

export interface PermissionEvaluator {
  evaluate(req: PermissionRequest): PermissionAction;   // last-match-wins over rules + hardline floor
  addGrant(rule: PermissionRule): Promise<void>;        // persists via config (ADR-9)
}

export interface RepositoryIndex {
  fileMap(opts?: { maxEntries?: number }): Promise<RepoFileEntry[]>;   // respects .gitignore/.khaelorignore
  gitStatus(): Promise<GitStatus>;                                     // branch, dirty, untracked
  gitDiff(paths?: string[]): Promise<GitDiff>;
  recordBaseline(when: "session-start" | "pre-first-edit"): Promise<GitBaseline>;  // ADR-15
  attributeChanges(): Promise<{ khaelor: string[]; preExisting: string[] }>;
  search(query: RipgrepQuery): Promise<SearchResult>;                  // bounded, structured
  findFiles(fuzzy: string, limit: number): Promise<RankedFile[]>;      // frecency-ranked
  noteAccess(path: string): void;                                      // feeds frecency + recency
}

export interface ToolDefinition<In> {
  name: ToolName;
  description: string;                       // guidance prose lives here, not in params
  inputSchema: JSONSchema;                   // ≤5 properties
  capability: (input: In, ctx: ToolContext) => Capability;   // drives permission evaluation
  execute: (input: In, ctx: ToolContext) => Promise<ToolResult>;
}
export interface ToolContext {
  workspace: Workspace;
  repo: RepositoryIndex;
  processes: ProcessManager;
  signal: AbortSignal;                       // turn-scoped; aborts in-flight tools (ADR-11)
  emitOutput: (chunk: string) => void;       // → ephemeral ToolOutput events
  budget: OutputBudget;                      // per-result + per-turn caps, spill-to-file (ADR-8)
}
export interface ToolResult {
  modelText: string;               // budgeted head/tail-truncated text with omission markers
  isError: boolean;
  spillFile?: string;              // full output path under ~/.khaelor/spill/, model can read/grep it
  ui: ToolUiMeta;                  // diffStats, matchCount, exitCode… for collapsed rendering
  filesModified?: FileModification[];
}
export interface ToolRegistry {
  definitions(): ToolDefinition<unknown>[];  // data-driven — the ADR-16 seam
  get(name: string): ToolDefinition<unknown> | undefined;
}
export interface ProcessManager {            // model-facing via the `process` tool (ADR-8)
  start(cmd: string, opts: { cwd?: string; name?: string }): ManagedProcess;
  list(): ManagedProcessInfo[];
  read(id: string, opts?: { offset?: number; limit?: number }): ProcessReadResult; // rolling 200K buffer
  write(id: string, input: string): void;
  stop(id: string): Promise<void>;           // process-group kill (mini hygiene, ADR-8)
  stopAll(): Promise<void>;                   // shutdown only — NOT on interrupt (ADR-11)
}

export interface TuiApp {
  start(io: { events: EventBus; dispatch: (c: KernelCommand) => void; config: ResolvedConfig }): Promise<void>;
  stop(): Promise<void>;
}

user types → composer → KernelCommand{submit-message} → cli dispatcher
  → durable UserMessageCreated appended + published
  → kernel loop wakes (it is the sole consumer of "work exists" state)
  → ContextEngine.selectContext(projection) → ModelRequest (byte-stable tiers, ADR-7)
  → ModelClient.stream(request, signal)
       deltas   → ephemeral ModelTextDelta / ModelThinkingDelta / ToolInputDelta → TUI coalescer
       settled  → durable ModelTextBlockCompleted / ModelThinkingBlockCompleted / ToolRequested
       finish   → durable ModelResponseCompleted {usage, stopReason}
  → for each ToolRequested (sequential, block order):
       Tool Runtime: capability → PermissionEvaluator
         ask → durable PermissionRequested → TUI panel → PermissionGranted/Denied
       durable ToolApproved → ToolStarted → execute (ephemeral ToolOutput chunks)
       → durable ToolCompleted | ToolFailed | ToolCancelled (+ FileModified / ProcessStarted …)
  → steering queue drained at the post-tool-batch seam → durable SteeringInjected
  → ContextEngine.onTurnComplete(usage) → maybe durable ContextPruned / ContextCompacted
  → loop re-derives: more tool calls? overflow? stop?
  → on stop with unverified code changes → verification gate (≤2 nudges) → TaskCompleted{evidence}

interface KernelDeps {
  session: SessionHandle;          // projection access + durable publish
  context: ContextEngine;
  model: ModelClient;
  tools: ToolRuntime;              // registry + permission gate + executor
  verifier: VerificationGate;      // ADR-12
  steering: SteeringQueue;         // ADR-11
  bus: EventBus;
}
interface KernelRunState {
  turnSignal: AbortController;     // the cancellation root for this run (ADR-11)
  budget: { iterations: number; verificationAttempts: number };
}

async function runTurn(deps: KernelDeps, run: KernelRunState): Promise<TurnOutcome> {
  while (true) {
    // 1. Re-derive what to do from RECORDED state — never from loop-local flags.
    const state = deps.session.projection();          // in-memory, event-derived (rebuilt from
    const next  = deriveNext(state, run.budget);      // JSONL only on resume — ADR-2 trade-off)

    switch (next.kind) {
      case "inject-steering": {
        // Safe seam: after tool results / before the next model call (ADR-11).
        deps.session.publish(steeringInjected(next.queued, next.seam));
        continue;
      }

      case "compact": {
        // Proactive (token budget) or reactive (overflow error recorded). ADR-6.
        const checkpoint = await deps.context.compress(state, run.turnSignal.signal);
        deps.session.publish(contextCompacted(checkpoint));   // durable; replay-deterministic
        continue;
      }

      case "call-model": {
        const ctx = await deps.context.selectContext(state);   // byte-stable tiers (ADR-7)
        try {
          for await (const ev of deps.model.stream(ctx.request, run.turnSignal.signal)) {
            reduceModelEvent(ev, deps);   // pure reducer: deltas → ephemeral publish;
          }                               // settled blocks / tool_use / usage → durable publish
        } catch (err) {
          const klass = classifyModelError(err);               // typed taxonomy (ADR-10)
          deps.session.publish(modelRequestFailed(klass));
          if (klass.kind === "context-overflow") continue;     // → deriveNext yields "compact"
          if (klass.kind === "cancelled")        continue;     // → deriveNext sees Interrupted
          if (klass.retryable) continue;                       // ModelClient already backed off
          return { kind: "failed", error: klass };             // fatal → TaskFailed recorded by caller
        }
        continue;
      }

      case "execute-tools": {
        // Sequential, block order. The runtime gates permissions, executes, and records
        // ToolApproved/Started/Completed/Failed/Cancelled + FileModified/Process* itself.
        await deps.tools.executeBatch(next.pending, run.turnSignal.signal);
        deps.context.onTurnComplete(deps.session.projection().lastUsage);  // ADR-6 observation
        continue;
      }

      case "verify": {
        // Model stopped; code changed this turn; no fresh verification evidence (ADR-12).
        if (run.budget.verificationAttempts >= 2) return { kind: "done", withheld: next.candidate };
        run.budget.verificationAttempts++;
        deps.session.publish(verificationRequested(next.detectedChecks, next.candidate));
        continue;                                              // nudge is a synthetic message → call-model
      }

      case "interrupted": return { kind: "interrupted" };      // Interrupted event is already durable
      case "done":        return { kind: "done" };
    }
  }
}

function deriveNext(s: SessionProjection, budget: Budget): NextAction {
  if (s.interruptedSinceLastModelCall)             return { kind: "interrupted" };
  if (s.pendingToolCalls.length > 0)               return { kind: "execute-tools", pending: s.pendingToolCalls };
  if (s.queuedSteering.length > 0 && s.atSafeSeam) return { kind: "inject-steering", ... };
  if (s.contextOverflowRecorded || s.tokensUsed > s.compactionThreshold)
                                                   return { kind: "compact" };
  if (s.lastStop === "end_turn") {
    const gate = needsVerification(s);             // code changed this turn ∧ no fresh evidence,
    if (gate.required)                             //   documentation-only changes filtered (ADR-12)
                                                   return { kind: "verify", ...gate };
    return { kind: "done" };
  }
  if (isDoomLoop(s))                               return { kind: "verify-with-user" };  // 3 byte-identical
  if (budget.iterations <= 0)                      return { kind: "done" };              //   consecutive calls → ask
  return { kind: "call-model" };
}

~/.khaelor/
  sessions/<project-hash>/
    <session-id>.jsonl        # append-only durable event log — THE truth
    <session-id>.meta.json    # projection cache (title, usage, cost, updatedAt) — always rebuildable
  spill/                      # oversized tool output (size-capped)
  logs/                       # developer logs (never the TUI)

export interface SessionStore {
  create(meta: NewSessionMeta): Promise<SessionHandle>;
  open(sessionId: string): Promise<SessionHandle>;            // resume = replay (§5.4)
  list(projectHash: string): Promise<SessionMeta[]>;          // reads meta caches; rebuilds stale ones
}
export interface SessionHandle {
  readonly id: string;
  publish(e: DurableEventInput): DurableEvent;    // append (write-ahead) + bus publish; assigns seq
  projection(): SessionProjection;                // in-memory, maintained by the same reducer
  meta(): SessionMeta;
}
export interface SessionMeta {                    // CLAUDE.md §8
  id: string; title: string; project: string;
  createdAt: number; updatedAt: number;
  model: string;
  tokenUsage: UsageTotals;                        // incl. cache read/write — real API numbers only
  cost: number;
  gitBranch: string;
  workingDirectory: string;
}

export interface ContextEngine {
  /** Assemble the model request from the projection. V1: pass-through hook for selection
   *  (no retrieval/topic routing yet — the verb exists so repository intelligence can
   *  plug in without interface change). */
  selectContext(s: SessionProjection): Promise<BuiltContext>;

  /** Summarize-compact. Emits nothing itself — returns the checkpoint the kernel records
   *  as a durable ContextCompacted event. Cuts ONLY at pairing-safe indices. */
  compress(s: SessionProjection, signal: AbortSignal): Promise<CompactionCheckpoint>;

  /** Observation hook: real usage from the last response updates budget accounting. */
  onTurnComplete(usage: ModelUsage): void;

  /** Cheap, deterministic, no-LLM: blank old tool results (protect newest N tokens).
   *  Returns the toolUseIds to prune; kernel records ContextPruned. Runs BEFORE compress. */
  pruneToolResults(s: SessionProjection): PruneDecision;
}
export interface BuiltContext {
  request: ModelRequest;            // system tiers + messages + tools + cache breakpoints
  stats: ContextStats;              // per-section token estimates → /context inspector
}

objective: <the user's current objective, one paragraph>
completed:
  - <finished sub-goal>
current_state: <where the work stands right now>
important_files:
  - path: src/context/engine.ts
    reason: <why it matters to remaining work>
changes:
  - <file-level change made so far>
failed_attempts:
  - <approach tried and abandoned, with why>
decisions:
  - <decision taken and rationale>
running_processes:
  - id: <process id>
    command: npm run dev
    status: running
next_steps:
  - <concrete next action>
raw_evidence:                       # preserved verbatim when summarization would destroy it
  - label: <e.g. failing test output>
    content: |
      <capped raw text>

export interface ModelClient {
  stream(request: ModelRequest, signal: AbortSignal): AsyncIterable<ModelEvent>;
  countTokens?(request: ModelRequest): Promise<number>;      // best-effort budgeting aid
}
export interface ModelRequest {
  model: string;
  system: SystemTier[];                       // stable tiers with cache_control breakpoints
  messages: AnthropicMessage[];               // byte-stable projection (§6.5)
  tools: ToolSchema[];
  maxOutputTokens: number;
  thinking?: ThinkingConfig;
}
export type ModelEvent =
  | { type: "started"; requestId: string }
  | { type: "text-delta"; blockIndex: number; text: string }
  | { type: "thinking-delta"; blockIndex: number; text: string }
  | { type: "block-completed"; blockIndex: number; block: CompletedBlock }  // text | thinking(+signature) | tool_use
  | { type: "finished"; stopReason: StopReason; usage: ModelUsage };
export interface ModelUsage {                 // real API fields ONLY — never estimated (Rule #4)
  inputTokens: number; outputTokens: number;
  cacheReadTokens: number; cacheWriteTokens: number;
}

export type ModelErrorKind =
  | "retryable"          // 429 / 5xx / network — retried inside ModelClient with jittered
                         //   exponential backoff and a retry budget; surfaced only on exhaustion
  | "context-overflow"   // routed to Context Engine (reactive compaction) — NEVER retried blindly
  | "auth"               // fatal; actionable message; never logs the key
  | "invalid-request"    // fatal; a KHAELOR bug — surfaced loudly
  | "cancelled";         // AbortSignal fired — not an error path, folds into Interrupted state
export class ModelError extends Error {
  kind: ModelErrorKind; retryable: boolean; status?: number; requestId?: string;
}

interface CompletionEvidence {
  objective: string;
  changedFiles: string[];
  checks: CheckResult[];            // command, exitCode, summary — real results only
  unresolvedIssues: string[];
}

t0    node boots; cli entry parses argv (no framework, hand-rolled — zero-dep parse)
t1    load config files (2 small JSON reads) + env; NO dotenv autoload; no network
t2    initialize terminal + render the startup shell (header, prompt) — FIRST PAINT
      ── everything below is lazy / background ──
bg    git status + branch (async → fills status bar when ready)
bg    session store init (create/open lazily on first message or /resume)
bg    instruction-file discovery (KHAELOR.md etc.)
lazy  @anthropic-ai/sdk        — imported on first model call
lazy  markdown/highlight/diff  — imported on first render that needs them
lazy  ripgrep spawn            — on first grep/glob/@-mention