Genie

A rebuild of Genie. An agent is a session. A session is not a terminal.

Build specification: .ai/plans/genie-2-spec-from-scratch.md in the tynn.ai envelope.

The rule this repository exists for

No agent process is ever attached to a pty — for any reason, including "an unused one". AgentEngine has one member and no 'pty', so the state is unrepresentable rather than merely avoided. The only TUI path is Take Over, which opens a terminal in its own window with Genie's MCP available; Genie does not start, manage, restart or revive it.

Layers

PROVIDER     @particle-academy/prism-acp       ClaudeDriver, CodexDriver — spawn, speak ACP
DURABILITY   @particle-academy/prism-harness   Thread + FileSessionStore ONLY (not AgentRuntime)
SURFACE      genie2                            renders the session model; never parses bytes

prism-harness's AgentRuntime assumes Prism is the agent (LlmClient = (req) => Promise<res>) and has zero knowledge of ACP. Genie's agent is an external CLI owning its own thread over a streaming protocol, so only the durability half applies — confirmed as the intended seam by that package's author.

Commands

npm test              # 406 unit tests, ~2s
npm run typecheck     # tsc; the no-pty rule lives in the type system, so this is a gate
npm run build         # renderer (vite) + main (ESM) + preload (CJS — a sandboxed preload
                      # supports only CommonJS; an ESM one loads as nothing)
npm run verify        # typecheck + test + build

Verification that is not a unit test

bash scripts/verify-linux.sh   # the whole gate on real Linux, in a container, ~40s
bash scripts/smoke-linux.sh    # OPEN THE APP: a real window under Xvfb, driven over CDP
npm run verify:live            # a real claude session: start, reply, persist, stop, process scan
npm run verify:flow            # real frames -> ledger rows -> the row a person reads

smoke-linux.sh is the one that matters. The build this replaces shipped four releases on green unit suites and every one was broken the moment somebody opened it, because nobody ever opened it. It runs on every push too, as a CI job called a real window, and uploads screenshots — looking at them has found five defects no test caught, including a Dashboard with no empty state and an entire application rendering in one font.

verify:live and verify:flow need the provider binary and spend real subscription tokens, so they are deliberately not part of npm test. Run them before anything is tagged.

Nothing GUI runs on the owner's desktop

Not a browser, not Electron, not a dev server. Every check above either runs headless in a --rm container or on CI. That is a standing rule of this workspace, not a preference.

Where things are

src/core/      every DECISION, as pure functions — tested without a DOM
src/main/      Electron main: registry, sessions, store, paths, upgrade
src/renderer/  React surfaces; they render and decide nothing
scripts/       verification that needs a machine rather than a test runner
docs/          the decisions the spec left to the builder, and why

The split is load-bearing: a decision taken inside a component is a decision nobody checks, and that is where the previous build kept most of them.

State

.ai/plans/genie-2-build-status.md in the envelope says what is built, what is verified, how it was verified, and what is not. That separation is the point — four releases shipped on "the tests pass".