Appendix A: Glossary

Definitions of the load-bearing terms in kiki's reference. When a term is used in multiple places, this is the canonical definition.

Concepts

• Thread — the kiki atom. A stable sqlite thread_id representing a themed sequence of jj revisions. While active, its live head is the managed workspace's current @, persisted as thread_head_commit_id. Bookmark name, workspace path, tmux session, and agent harness session are mutable projections of that identity.
• Thread head — the exact commit at the managed workspace's current @, persisted after observed workspace operations. It is the live synchronization source for follows. It is not inferred from the thread bookmark. Creating a follows edge refreshes the parent from a pinned jj operation view rather than trusting a possibly lagging cached head.
• Owned stack — in v1, the provable single-parent chain after the follows edge's exact synchronized base through the thread head. Merge commits, multiple candidate roots, or foreign topology are not guessed through; they produce TopologyDiverged and require a human choice.
• Bookmark — jj's term for a named pointer to a revision. In kiki, the bookmark is a human-facing checkpoint, reopen handle, and branch pushed to a remote. Kiki checkpoints it explicitly at lifecycle and publication boundaries; it does not pretend jj moves it whenever @ gains a child. Canonical identity stays with thread_id, and live state stays with the thread head.
• Follows — a directed parent-thread link enabling live cascade.
• Ambient coordinator — kiki's posture: it observes and reacts to jj/tmux/gh state without gatekeeping the underlying tools.
• Thread lifecycle states — Creating | Active | CreateFailed | ClosePreflight | CloseCommit | CloseFailed | Closed | ProjectionDiverged | DestroyCommit | DestroyFailed | Destroyed. Creation, close, reopen, and the later destroy surface are durable sagas. ProjectionDiverged means a mutable projection such as the bookmark, jj workspace record, path, or tmux session no longer matches recorded state and cannot be repaired unambiguously. The former missing-directory-only Orphaned case is ProjectionDiverged { reason: WorkspaceDirectoryMissing }. Closed is a soft archive retaining the checkpoint bookmark and revisions. Destroyed tombstones kiki's thread identity; jj revisions remain unless a separately approved --abandon-revisions plan named an exact safe chain.

Scope tiers

• Acceptance slice — what v1 must ship to be accepted. The canonical enumeration lives in Orientation and nowhere else; chapters describe behavior and link to the ledger for when it ships.
• v1.x polish — post-acceptance work that deepens v1 but must not block the acceptance slice unless explicitly promoted. Enumerated in the same Orientation ledger.

Cascade

• Cascade reconciliation — the follows-aware process that classifies a parent change, waits for the affected managed agent's safe boundary, makes the workspace reflect the desired jj state, injects context, and acknowledges delivery. The reconciliation is either NativeRewrite or ParentAdvance.
• NativeRewrite — jj has already evolved a descendant's commits in repository state because an ancestor was rewritten. The intent pins the exact old-base → evolved-base transition, not the descendant's volatile working-copy commit. Kiki does not rebase the descendant again; at a safe boundary it verifies the current descendant still contains the evolved base and normally materializes it with jj workspace update-stale.
• ParentAdvance — a parent's persisted thread head gained a new exact commit that is not already an ancestor of the following child. Kiki explicitly rebases the child's provably linear owned stack onto that exact commit at a safe boundary, then materializes the result.
• Materialization — updating a workspace's on-disk files to the working-copy commit already recorded for that workspace in jj repository state. Repository evolution and workspace materialization are separate events.
• Pause-propagate-resume — the protocol that interrupts a child agent at the next safe boundary, reconciles and materializes the desired state, injects a context message, and resumes the agent.
• Core invariant — kiki does not materialize evolved state or perform an explicit follows rebase in a managed workspace while that workspace's managed agent is mid-edit, and it does not resume from a working tree that may hide unsnapshotted edits. Direct human jj operations are an explicit escape hatch and may materialize a stale workspace earlier.
• Soft pause / Hard escalation — soft = inject context through the exclusive PreToolUse boundary using a SoftBatch proof. Hard = pause or terminate the old incarnation and resume or start a replacement through proof-carrying RestartStartup; an untracked prepended message is not delivery evidence.
• WorkspaceProbe — a non-materializing check run immediately before reconciliation. It returns a filesystem fingerprint and classifies the workspace as FreshClean, FreshDirty, StaleClean, StaleDirty, or Unknown; a backend that cannot prove cleanliness returns Unknown, which is handled like dirty state before any mutation.
• WorkspaceRecovery — the hard-paused recovery path for a stale workspace with unsnapshotted or indeterminate edits. It runs outside the source workspace, invokes jj's stale-workspace recovery, enumerates divergent successors, and verifies which result retains the edits before anything resumes.
• sync_intent — the sole durable record of one ordered cascade reconciliation. It owns kind, base transition, normalized trigger operations, result ids, state (Detected | Reconciling | Materialized | Delivered | Acknowledged | RecoveryRequired | TopologyDiverged | Superseded), recovery details, byte-stable payload and anchor, one exact SoftBatch or RestartStartup delivery proof, and the durable delivery-attempt history with its exhaustion state. UI and delivery queries derive progress from these rows rather than shadow counters, and retry bounds are evaluated against them rather than in-memory counts a restart would forget.
• Embedded cascade outbox — the payload, anchor, transcript id, and delivery timestamps stored on a materialized sync_intent. It pins what the agent sees across crash and retry boundaries without creating a second protocol authority. See the embedded-outbox design note.
• SoftBatch delivery proof — intent-embedded state preventing a dispatched tool batch from treating a second concurrent PreToolUse as acknowledgement. The first admitted call binds Block before reconciliation may mutate files, and every call in that batch is blocked. PostToolBatch records exact completion; only a later model turn may acknowledge and clear the proof. For Claude Code the batch is the parallel tool batch; for Codex's proven-serial dispatch it is a single tool call whose blocked completion is reported by the harness's next turn-scoped hook event, since a denied call never runs, fires no post-tool event, and the emitting hook's own RPC dies with the hook.
• RestartStartup delivery proof — hard-restart mode binding a pending payload to a replacement incarnation and one-use startup_delivery_id. The payload is mandatory startup input; an acceptance handshake marks delivery, and only the resulting first model turn causally echoing that id may acknowledge it.

Transcript

• Thread transcript — kiki's locally stored record of human-authored, agent-authored, and kiki-authored conversational text events per thread, bound to jj change-ids. Rows live in ~/.config/kiki/repos/<repo_id>/state.db, are never pushed, and do not enter the source repo; an explicitly consented catch-up may still send selected text to the configured model provider. Rows distinguish author (human|agent|kk) from direction (inbound_to_agent|outbound_from_agent|local_record) so kiki-authored context is not misattributed to the agent.
• Local-storage / no-publication rule — transcript rows are stored under ~/.config/kiki/ and do not feed externally published artifacts (kk publish PR drafting, auto-describe, auto-rename). Sending transcript-derived catch-up or MCP output to a hosted harness is a separate provider-egress boundary and requires remembered consent for the exact thread, provider, purpose, and disclosure version.
• synthesized=TRUE — flag on a transcript row indicating it is kiki-composed content the agent received (cascade injections, reopen catch-up, hard-escalation framing). The flag is what lets kk reopen catch-up exclude prior catch-ups from its source query, breaking the recursion that would otherwise compound on every reopen.
• anchor_unknown=TRUE — flag on a backfilled transcript row whose timestamp predates the available op_history and cannot be reliably anchored to a (change_id, commit_id, op_id). Anchor-aware queries skip these rows by default; --recent and FTS5 search include them. See transcript anchoring.
• TranscriptAdapter — the v1.x capture-side trait abstracting per-harness session-record discovery, tailing, projection to (author, direction, text, dedup_key), and offset reporting. Its first implementations read Claude Code session JSONL and Codex rollout JSONL.

Agent and harness

• Harness — an agent runtime kiki spawns and coordinates with (Claude Code and Codex in v1; others deferred). Exposes a Harness factory trait + RunningAgent instance trait.
• Runtime agent incarnation — one kiki-managed harness process, identified by a kiki UUID separately from the harness's resumable conversation/session id. Delivery acknowledgement belongs to the incarnation, so restarting with the same harness session cannot falsely acknowledge output seen only by the prior process.
• Capabilities — typed struct returned by a Harness describing what it proves: soft_pause, session_resume, structured_tool_hooks, parallel_batch_boundary, exclusive_pre_tool_use, restart_startup_delivery, mcp_client, and quiescence_detection. The cascade orchestrator branches on behavioral proofs, not on the settings mechanism used to obtain them.
• Agent display states — the four-value human-facing projection (idle, working, finished, blocked) of AgentStatus plus turn-completion and attention signals, defined in Harness adapter. Display-only; the orchestrator branches on AgentStatus, never on these.
• PreToolUse / PostToolBatch hooks — kiki's protocol entry points, which each adapter maps onto its harness's hook events; kiki exclusively owns the pre-tool boundary in every managed v1 process incarnation. The first admitted call fixes the whole batch's pass/block decision before mutation; a blocked batch emits the saved payload for every call once prepared. PostToolBatch marks only that exact SoftBatch complete, and a later model turn performs acknowledgement. Claude Code's PostToolUse event is not part of the protocol, and Codex's cannot be: a denied call never executes and fires no post-tool event, so a proven-serial Codex adapter reports its single-call batch complete through the next turn-scoped hook event, which cannot arrive before the blocked call resolved. RestartStartup uses its tagged startup-input proof instead.
• Delivery receipt — the Codex adapter's authoritative consumption evidence: the harness session record's persisted result for a blocked tool_use_id, which must match the saved payload byte-identically before acknowledgement. MarkDelivered proves only that the hook wrote stdout; the receipt proves the model received the payload rather than a timeout-substituted or launcher-generic result. A contrary receipt redelivers on the arriving batch at most once per intent — a repeat fails over to RestartStartup, which does not ride the hook output; an unreadable one defers or fails closed into RestartStartup.
• ContextMessage — { kind: MessageKind, text: String, structured: Option<JSON> } — the byte-stable cascade communication embedded in a materialized intent for delivery to the thread's agent.

Auth

• Bootstrap Admin credential — daemon bootstrap authority stored at ~/.config/kiki/admin-cred (mode 0600). It is not automatically presented by every CLI invocation and is not itself evidence of human presence.
• Human approval — a short-lived, one-use capability bound to one requesting credential, method, target, argument digest, and daemon-rendered plan. It is issued only after an enrolled foreground ApprovalPresenter confirms a persisted challenge. Kiki atomically claims it into one durable operation journal before external effects; crashes may resume only that exact plan, never reuse it for another action.
• ThreadScoped<T> credential — bound to one thread. Stored at ~/.config/kiki/repos/<repo_id>/credentials/<thread_id> (mode 0600). Read by kk-hook, contextual kk, and later same-thread readers. Launch-scoped harness settings — Claude Code's generated settings file or Codex's generated CODEX_HOME — reference it by absolute path; Claude Code's ownership-tracked fallback merges only .claude/settings.local.json. Kiki never writes tracked .claude/settings.json or anything under <workspace>/.codex/.
• Repo-summary read scope — the small expansion of ThreadScoped<T> allowing a sidebar process to subscribe to read-only one-line summaries of sibling threads in the same repo. Same-repo only, read-only, summaries only (no diffs, no transcripts). The single cross-thread read a ThreadScoped<T> credential can perform.
• Projection divergence — an observed mismatch between a thread row and a mutable external projection: missing jj workspace record, mismatched path, missing or moved bookmark, or missing tmux session. Kiki repairs only provably unambiguous cases automatically; otherwise kk repair presents explicit outcomes.

State

• Operation-history cache — normalized op_history nodes, op_history_parents DAG edges, per-view op_workspace_heads, and the op_watch_frontier, populated by live watching and restart catch-up. The workspace dimension is load-bearing because jj's op log is repo-shared but @ is workspace-local; no singular parent or cursor may flatten incomparable operations. Transcript backfill consults this cache and leaves ambiguous anchors unknown.
• pending_kkd_prepends — TTL-bounded sidecar table the JSONL projector consults to recognize kiki-composed --resume prepended messages and capture them as synthesized=TRUE.

UI

• Overlay TUI — the interactive kk UI invoked from inside tmux via prefix+k (or by running bare kk inside a registered repo). Two-pane: left sidebar with Stack and Activity sections, right content pane (transcript / diff / PR comments). Carries the full action set (spawn, publish, close, interrupt) gated by daemon-issued foreground approval cards for consequential verbs. Dismissed with q / esc.
• Persistent sidebar pane — opt-in left tmux pane (default 32 cols) running a long-running kk sidebar --thread <id> ratatui process. Renders the same Stack + Activity sections as the overlay sidebar, restricted to navigation-only keybindings.
• Shell pane — opt-out tmux pane (default on) running the user's $SHELL at the thread's workspace cwd, laid out alongside the agent pane in the same tmux window (default position: below; configurable to the right). The pane kiki manages — singular — so direct jj / gh / test invocations live alongside the agent without leaving the thread. Spawned at thread birth, re-ensured idempotently at kk switch / kk reopen, not auto-respawned after a user-initiated kill in the same continuous attach. Transparent to kkd after spawn — kkd does not track its state or processes. Additional panes the user splits into the session via native tmux are not "shell panes" in kiki's vocabulary; they are just tmux panes and kiki ignores them.
• Stack-aware collapse — kk log's default topology rule: the current thread plus its full follows-ancestor chain renders revision-by-revision; siblings, descendants-not-on-the-current-line, and unrelated threads collapse to one-line summaries; trunk renders as its own root.
• LogRenderer / StatusRenderer — pure-function rendering modules in kiki-core. LogRenderer produces the stack-aware revision view; StatusRenderer produces the kk-shaped header used by kk status and reused by the sidebar via --no-jj. Single source of truth across CLI, overlay TUI, and persistent sidebar pane.

v2 / future

• Causal chain — UUID stamped on each MCP-driven post, used to detect cycles, depth excess, and branch fan-out in inter-thread messaging. See Roadmap.