v0.1.9 — mobile companion + stability

CodeTrellis 0.1.9 — the mobile-companion + stability release.

A big release. Two headline themes: (1) the desktop backend is
dramatically more reliable — the WASM-database memory-out-of-bounds
crash class is gone, and existing DBs auto-heal schema drift on
startup; (2) a full iOS / Android companion app, paired in
seconds and giving you the desktop's plan workspace, channels,
terminal, and dependency graph on the phone.

The companion app is not in the App Store yet — it's going through
certification. If you'd like early TestFlight / APK access, reach
out via the issues tab on this repo or email — see "Mobile companion
early access" below.

Highlights

• No more "memory access out of bounds" crashes. The desktop now
  uses a native SQLite (better-sqlite3) with WAL persistence instead
  of sql.js's WASM-in-memory engine. No memory ceiling, much faster,
  zero per-mutation full-DB exports.
• Schema reconciler. Existing databases now self-heal on startup:
  any column declared in the schema but missing from your live DB
  (e.g. tasks.file_spec, tasks.symbol_specs) is added
  automatically. No more "no such column" crashes on upgrade.
• Mobile companion app (TestFlight / APK). Pair in one QR scan,
  drive the desktop from your phone — plans, channels, terminals,
  graph, system docs. Real-time WebRTC + Bonjour discovery, no cloud.
• Three new MCP tools for the mobile companion so any connected
  agent can drive the phone too: mobile_navigate,
  mobile_screenshot, mobile_present.

Backend stability

sql.js (WASM) → better-sqlite3 (native)

The previous engine held the whole database in a fixed Emscripten
WASM heap and re-exported the entire ~35 MB DB to disk after every
mutation (~85 sites + a 30-second autosave). Past tens of MB the
WASM heap faulted with RuntimeError: memory access out of bounds,
which wedged every database endpoint until the app was restarted.

The new engine is native sql, disk-backed in WAL mode, persists in
place — no full-DB export churn, no memory ceiling. A thin
sql.js-compatible shim (run / exec / export / close) means
all ~290 existing call sites keep working unchanged. Your existing
~/.codetrellis/data.db is opened as-is; no data migration.

Schema reconciler

Every time the app starts, the reconciler parses the declared
CREATE TABLE blocks and compares them to PRAGMA table_info on
the live DB. Any column the declaration adds that the live DB is
missing gets ALTER TABLE … ADD COLUMN-ed in automatically.

This is the safety net for the "added a column to CREATE TABLE
but forgot the matching ALTER" class of bug that bit
tasks.file_spec in v0.1.8 (which broke get_plan_summary,
post_channel_event, and the inspector's "load source").

It's additive only — never drops or renames. Non-additive changes
(NOT NULL with backfill, renames, indexes, data backfills) still go
through the lazy migration block.

Look for [DB] Schema reconciler added N column(s): … in the logs
on first boot of 0.1.9.

Frontend crash guards

• sessions.filter is not a function no longer wedges the UI when
  the sessions blob comes back malformed.
• The graph no longer throws nodes is not iterable when opening a
  plan whose project directory has been moved or deleted.

Boot reliability

• The active project is now restored on every boot — the desktop
  no longer reports "No project scanned" after a restart, even if
  the renderer hasn't issued a fresh scan yet.

Mobile companion app

An iOS / Android companion that pairs with the desktop in seconds
and gives you full real-time access to your plans, channels,
terminals, and dependency graph from anywhere on your network.

Built with Expo + React Native. Real-time desktop ⇄ phone via
WebRTC over Bonjour mDNS discovery (so it Just Works on your local
network with no cloud, no signalling server). No data leaves your
LAN.

Mobile companion — early access

We're getting the app through Apple's TestFlight and Google's
internal-testing pipelines before public release. If you want
early access to the mobile companion now, open an issue on this
repo titled "Mobile early access" or email the address in the
desktop app's About panel with your platform (iOS / Android) and
TestFlight email / Google account.

The desktop app at v0.1.9 already speaks the mobile pairing
protocol — you can pair it the moment your test build is in your
hands.

Pairing & connection

• One-scan QR pairing (Bluetooth-style flow): open Settings →
  Devices on the desktop, scan the on-screen QR on the phone, done.
• mDNS / Bonjour discovery — the desktop advertises as
  <your-mac>.local; the phone finds it without typing IPs.
• Auto-connect on launch — the phone reconnects to the last
  reachable desktop the moment it opens.
• Reconnect on app foreground — coming back to the phone after
  a lock auto-restores the link via the AppState listener.
• Conservative liveness heartbeat — no false-positive
  reconnects when the network briefly stutters.
• Dead-peer reaping — zombie WebRTC connections (phones that
  walked out of range) are reaped server-side so the Devices list
  stays honest.

Mobile features (parity rollout)

The mobile companion now covers plans, channels, terminal, graph,
and admin — broadly at parity with the desktop's plan workspace.

Plans tab

• Defaults to "all projects" — every plan across every CodeTrellis
  project on the desktop, not just the active one.
• Browse, open, and create plans from the phone.
• Drill into plan info, status, item tree, deviations.
• Per-plan discussion channels — full channel rail on mobile
  (stuck / need-decision / need-context / handing-off / steer /
  weigh-in), with message threading and resolution.

Plan authoring on mobile

• Edit bodies and titles, post comments, set fields (status,
  assignee, blocked reason).
• Create / delete items, add / remove item refs.
• @-mention to address comments and channel posts to specific
  people / agents.
• Editable titles + markdown for deviations and channel messages.
• Body editor: Write / Preview toggle, writing-friendly font
  stack.

Markdown rendering

• Notion-style reading view for plan bodies.
• Inline [[item]] / [[file]] / [[symbol]] / [[attachment]]
  chips render natively in the phone's markdown view — tap to
  navigate.

Terminal panel on mobile

• Real terminal via xterm.js running inside a WebView, streamed
  over WebRTC from the desktop's PTY.
• Fit-resize so the terminal correctly tracks the phone's portrait
  / landscape size.
• xterm.js is bundled offline — no CDN dependency, full air-gap.
• Kill terminals from the phone.

Graph on mobile

• Interactive streamed dependency graph (live updates from the
  desktop's view).
• Graph depth toggle — package / file / symbol detail levels.
• Base mode for diff comparison against a pinned commit.
• Git gutter showing changed files inline.
• Graph source preview — tap a node, see the source for that
  file / symbol without leaving the graph.

System docs, settings, projects, templates on mobile

• Browse and read system docs (.codetrellis/docs/).
• Mirror desktop settings — identity, MCP port, plan defaults.
• Browse and open projects (with a Cancel button on the modal so
  you can back out cleanly).
• Plan templates + import-from-disk.

Handoff / mentions / presence

• Handoff card UX on the phone when an agent posts a
  handing-off event.
• @-mentions you receive ping the phone.
• Presence indicators: see which other actors (humans, agents) are
  on a plan with you.

New MCP tools (drive the phone from any agent)

The desktop now exposes three new MCP tools that operate on the
paired phone, not the desktop:

• mobile_navigate(target, plan_uid?) — switch the phone's
  view: plans / channels / terminal / graph / system-docs / etc.
• mobile_screenshot(panel?) — capture what the user is
  looking at on the phone (replies are chunked so screenshots of
  long pages no longer time out).
• mobile_present(text, …) — post a narration card to the
  phone's Presence Pane (same surface as the desktop's, mirrored).

These compose with the rest of the MCP API — any connected agent
(Claude Code, Codex, Cursor, custom) can drive both the desktop
and the phone in lockstep.

Build & packaging

• Cross-platform builds from macOS now work end-to-end with
  Rosetta installed. The afterPack hook (scripts/adhoc-sign.js)
  now checks the target platform (context.electronPlatformName)
  rather than the host, so cross-arch Windows / Linux builds from
  an Apple Silicon Mac no longer try to xattr a .app that
  doesn't exist.
• werift WebRTC native deps are unpacked from app.asar so
  the nested node_modules resolution Just Works in packaged
  builds (no more MODULE_NOT_FOUND from the WebRTC stack).
• asar packing disabled where it broke werift's nested
  module loader.
• better-sqlite3 (native .node binary) is externalised in
  electron.vite.config so the build doesn't try to bundle it.
• xterm.js bundled offline for the mobile WebView terminal —
  no runtime CDN.

Downloads

• macOS (Apple Silicon) — CodeTrellis-0.1.9-arm64.dmg
• macOS (Intel) — CodeTrellis-0.1.9-x64.dmg
• Windows installer (NSIS) — CodeTrellis-Setup-0.1.9.exe
• Windows portable — CodeTrellis-Portable-0.1.9.exe
• Linux AppImage (x64) — CodeTrellis-0.1.9.AppImage

First-launch notes

Builds are not yet code-signed, so the OS will warn you the first
time. This is expected — bypass it once and the warning won't
repeat.

• macOS: right-click → Open → Open. Or System Settings →
  Privacy & Security → "Open Anyway". If quarantine sticks,
  xattr -cr /Applications/CodeTrellis.app.
• Windows: SmartScreen → "More info" → "Run anyway".
• Linux AppImage: chmod +x then ./CodeTrellis-0.1.9.AppImage.

Upgrading from v0.1.8

• Install the new binary over the top. Your existing
  ~/.codetrellis/data.db is opened in place by better-sqlite3 —
  no data migration. The schema reconciler will log any columns
  it backfills.
• Plans, items, channel events, system docs, snapshots — all
  preserved.
• Pairing keys / device list — preserved.

Mobile companion early access — how to get on the list

1. Open an issue on this repo titled "Mobile early access", or
   email the address shown in the desktop app's About panel.
2. Tell us: iOS or Android, your TestFlight email (iOS) or
   Google account email (Android), and a sentence on what you'd
   use it for (we use this to triage the rollout, not to gatekeep).
3. We'll add you to the test cohort as soon as your slot opens up.

The desktop at v0.1.9 already speaks the mobile pairing protocol —
the moment your build lands, pair via Settings → Devices and
you're streaming.

---

Full changelog (since v0.1.8)

Backend stability

• 2e924c2 fix(backend): migrate DB from sql.js (WASM) to better-sqlite3 (native)
• 4942d4a fix(backend): sql.js OOB self-heal + restore active project on boot
• fbeed79 feat(db): schema reconciler — auto-heal additive column drift
• f1c3524 fix(frontend): guard sessions array — unrecoverable "sessions.filter is not a function" crash
• 0bc718a fix(graph): stop "nodes is not iterable" crash when opening a plan whose project dir is missing

Mobile companion — connection & pairing

• ef013e8 fix: reap dead WebRTC peers (zombie companion connections)
• ca847a0 feat(mobile): real auto-reconnect + connection liveness heartbeat
• b9e4333 feat(mobile): auto-connect on launch to the last reachable desktop
• 43b684f fix(mobile): make liveness heartbeat conservative — no false-positive reconnects
• 01cbfbc feat(mobile): reconnect on app foreground (AppState)

Mobile companion — terminal & graph

• 556ec41 feat(mobile): real terminal via xterm.js (WebView) + streaming + fit-resize
• ff891e3 build(mobile): bundle xterm.js offline; drop dead ANSI parser
• aecd21c feat(mobile): browse/open projects from the phone + interactive streamed graph
• 9814d82 mobile: graph depth (file nodes + base mode + git gutter), handoff, mentions, presence

Mobile companion — plans, channels, authoring

• 18c48f0 feat(mobile): M8 — surface full plan info + per-plan discussion channels
• 3150c0f fix(mobile): Plans tab defaults to all projects (show every plan)
• 8e6c4df feat(mobile): Notion-style markdown reading + desktop↔mobile gap analysis
• f448eb1 feat(mobile): render inline [[item/file/symbol/attach]] chips in bodies
• 2b24fdb feat(mobile): P1 lightweight authoring — edit bodies, post comments, set fields
• 86447aa feat(mobile): finish authoring — create items, assignee/blocked edits, @-mention
• 0485bfb feat(mobile): editable titles + markdown for deviations & channel messages
• e8a44bd mobile: plan create/delete, item ref add/remove, terminal kill, graph source preview
• 3cdf21f polish(mobile): nicer body editor — Write/Preview toggle, writing-friendly font

Mobile companion — system docs, templates, settings, projects

• 75b42af mobile: settings, system docs, plan templates/import, project management
• 2a07db4 fix(mobile): add Cancel button to the Open Project browser modal

Mobile companion — MCP & screenshots

• 88453bb feat(mcp): drive the mobile companion — mobile_navigate / mobile_screenshot / mobile_present
• 512a449 fix(mobile): chunk mobile_screenshot reply — fixes the screenshot timeout

Internal / merges / docs

• 42555a7 Merge branch 'm8-plans-and-channels': mobile companion parity + zombie-peer fix
• 64cb72d Merge origin/main: bring in adhoc-sign target-platform build fix (cb79e2e)
• 777268c docs: parity matrix — P2 polish closed (graph depth, handoff, mentions, presence)
• d73332f docs: parity matrix — P3 admin tail closed (settings, sysdocs, templates, projects)
• d0b3faf docs: update mobile parity matrix — P0/P1 + high-value P2 closed

---

Built from lionroseway/codetrellis @ fbeed79.