Repository navigation
docs: add plan 2 for the daemon core with the fake harness - #18
Merged
Merged
Conversation
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
The implementation plan for sub-project 1, plan 2: the
workboxdaemon 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);coredomain, ports, in-memory store and shared store suite, recommendation policy and slugs, session runtime,Workboxservice (4–7);store-sqlite(8); theprocesspackage, host sandbox and git worktrees (9a–9b);harness-fakewith JSON scenarios (10);servertoken authority and blobs, HTTP routes and dispatcher, WebSocket protocol (11–13); CLI composition root andserve, daemon client withstatus/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:sqlitebehaviour 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:
bun:sqlitedirectly 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 queriesfts5tables, and Bun's static SQLite for Linux and Windows is compiled withSQLITE_ENABLE_FTS5. Recorded as an ADR 0003 amendment in Task 17.daemon.jsonstores the bearer token itself (owner-only file, mode 0600) rather than its hash: laterworkboxinvocations must authenticate to the daemon, and the file permissions are the boundary. The browser receives the bearer once fromPOST /api/auth/exchange, as the spec says; it never appears in a URL or a log.packages/process(tagprocess) for the command runner that plan 1c put intoapps/cli, becausesandbox-hostneeds it now and the Claude adapter will need it in plan 4. The alternative is to move it twice.ANTHROPIC_API_KEYis not in the defaultenv.passthrough; a project opts in. The README documents it.interruptandstop, started afterturn.failed, lost on a daemon crash. Persisting them would need aturn.queuedevent the spec does not have.Alice,Bob,Eva,Jan) closes spec open question 5 for slice 1; a locale-aware pool would need the user's locale insidecore.src/testing/**incoreandsandbox-host, andignoreInferredTypesinserver.session.archiveremoves the worktree (after stopping the harness);stopand a failed preparation keep it.WorkboxErrorinstead of typed result objects;creating → idlefires when the adapter'sstart()resolves;prepare()returns aPreparedWorkspace.POST /api/commandandproject.list/session.listcommands extend spec 7.2 so the CLI has a transport;GET /api/summaryservesworkbox status. Recorded in the new ADR 0012.Review guide
Checklist
pnpm checkis green locally (docs only;docs/superpowers/**is excluded from the linters by design)git commit -s)