Skip to content

docs: add plan 2 for the daemon core with the fake harness - #18

Merged
misaon merged 3 commits into
mainfrom
worktree-plan-2-daemon-core
Oct 1, 2026
Merged

misaon merged 3 commits into
mainfrom
worktree-plan-2-daemon-core

Conversation

@misaon

@misaon misaon commented Oct 1, 2026 •

Copy link
Copy Markdown
Owner

What

The implementation plan for sub-project 1, plan 2: the workbox daemon with the fake harness. Eighteen tasks (Task 9 is split into 9a and 9b): protocol event catalogue, entities, commands and frames, state machine, projections and project config (Tasks 1–3); core domain, ports, in-memory store and shared store suite, recommendation policy and slugs, session runtime, Workbox service (4–7); store-sqlite (8); the process package, host sandbox and git worktrees (9a–9b); harness-fake with JSON scenarios (10); server token authority and blobs, HTTP routes and dispatcher, WebSocket protocol (11–13); CLI composition root and serve, daemon client with status/stop/default command, project and session commands with an end-to-end fake-harness run (14–16); decision records and developer experience (17).

This PR is documentation only and is meant to be reviewed before any implementation starts. Merging it is the approval; the implementation then runs task by task with the subagent-driven flow used for plan 1, in a fresh worktree, and lands as its own pull request(s).

The draft went through two independent review rounds (opus) and two revision rounds before this version: 2 Critical, 15 Important and 58 Minor findings were fixed; every finding and its resolution is listed in the notes kept outside the repository, and the reviewers verified the lint claims against the repository's own Oxlint, bun:sqlite behaviour on Bun 1.4.2, and git 2.54 worktree behaviour.

Decisions that deviate from the spec text (please confirm or object)

The plan has a "Decisions and spec deviations" table (21 rows). The ones that need your word:

  1. Storage access: bun:sqlite directly with embedded, versioned SQL migrations instead of Drizzle ORM 0.45. Drizzle 1.0 is still in release candidates, its migrator reads a folder from disk that a compiled binary does not have, and the log needs an FTS5 virtual table and projections an ORM does not model. FTS5 is verified: SQLite 3.54.0 on macOS creates and queries fts5 tables, and Bun's static SQLite for Linux and Windows is compiled with SQLITE_ENABLE_FTS5. Recorded as an ADR 0003 amendment in Task 17.
  2. daemon.json stores the bearer token itself (owner-only file, mode 0600) rather than its hash: later workbox invocations must authenticate to the daemon, and the file permissions are the boundary. The browser receives the bearer once from POST /api/auth/exchange, as the spec says; it never appears in a URL or a log.
  3. New package packages/process (tag process) for the command runner that plan 1c put into apps/cli, because sandbox-host needs it now and the Claude adapter will need it in plan 4. The alternative is to move it twice.
  4. ANTHROPIC_API_KEY is not in the default env.passthrough; a project opts in. The README documents it.
  5. Queued prompts live in memory in plan 2: discarded on interrupt and stop, started after turn.failed, lost on a daemon crash. Persisting them would need a turn.queued event the spec does not have.
  6. A fixed employee name pool (Alice, Bob, Eva, Jan) closes spec open question 5 for slice 1; a locale-aware pool would need the user's locale inside core.
  7. Two lint relaxations through nested overrides with ADR 0005 ledger rows: test-suite limits lifted for src/testing/** in core and sandbox-host, and ignoreInferredTypes in server.
  8. Worktree cleanup: session.archive removes the worktree (after stopping the harness); stop and a failed preparation keep it.
  9. Error reporting: failures reject with WorkboxError instead of typed result objects; creating → idle fires when the adapter's start() resolves; prepare() returns a PreparedWorkspace.
  10. POST /api/command and project.list/session.list commands extend spec 7.2 so the CLI has a transport; GET /api/summary serves workbox status. Recorded in the new ADR 0012.

Review guide

  • Global Constraints and Review Focus at the top are what every task's reviewer will hold the implementation to.
  • Task 1 fixes the event payload field names for every later plan; that table deserves the closest read.
  • Task 6 (session runtime) and Task 13 (WebSocket backfill) carry the concurrency rules; Tasks 14–15 describe the start/attach/stop lifecycle. Say if you want a different port strategy or browser-opening behaviour.

Checklist

  • The PR title is a Conventional Commit (it becomes the squash commit message)
  • Tests cover the change and pnpm check is green locally (docs only; docs/superpowers/** is excluded from the linters by design)
  • Commits are signed off (git commit -s)
  • Docs, i18n messages (en and cs) and ADRs are updated where the change needs it (ADR work is scheduled inside the plan)

misaon added 3 commits October 1, 2026 17:27
Signed-off-by: Ondřej Misák <email@ondrejmisak.cz>
Two opus reviews and three revision rounds. The server now receives the event
feed and partial snapshots, list commands and routes exist for the CLI, the
bearer design is consistent across tasks, the session lifecycle covers creating,
resume, shutdown and restart, the sandbox handles remote-only bases, Windows
shells and unique branch names, the WebSocket protocol defines backpressure and
ordering, idempotency keys are unique per event, and every snippet matches the
repository's lint rules. Task 9 is split into 9a (process package) and 9b (host
sandbox provider).

Signed-off-by: Ondřej Misák <email@ondrejmisak.cz>
@misaon
misaon merged commit a4a16af into main Oct 1, 2026
13 checks passed
@misaon
misaon deleted the worktree-plan-2-daemon-core branch October 1, 2026 19:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant