trekoon 0.4.1 → 0.4.3

package/README.md

@@ -90,8 +90,8 @@ What the agent does during execution:
    calls `task done`
 6. `task done` returns which downstream tasks just became unblocked, so the
    orchestrator knows what to dispatch next
-7. After all tasks complete: code review, tests, manual verification, then marks
-   the epic `done`
+7. After all tasks complete: review agent or review skill for non-trivial
+   changes, tests, manual verification, then marks the epic `done`
 
 The orchestrator uses `task done` responses to drive the whole loop. No polling,
 no guessing. When a task finishes, Trekoon tells you exactly what's ready next.
@@ -110,13 +110,15 @@ agents don't know how to use Trekoon properly.
 ```bash
 trekoon skills install          # repo-local (.agents/skills/trekoon/)
 trekoon skills install -g       # global (~/.agents/skills/trekoon)
+trekoon skills install --link --editor codex    # editor link (.codex/skills/trekoon)
 trekoon update                  # refresh all installed skills
 ```
 
-The skill bundles three reference documents that agents load on demand:
+The skill bundles reference documents that agents load on demand:
 
 | Agent needs to... | Skill reads | What it covers |
 | --- | --- | --- |
+| Coordinate across harnesses | `reference/harness-primitives.md` | Universal subagent, question, local task display, review, and evidence-recording guidance |
 | Plan a feature | `reference/planning.md` | Decomposition, writing standard, dependency modeling, validation |
 | Execute an epic | `reference/execution.md` | Graph building, lane grouping, sub-agent dispatch, verification (universal) |
 | Execute with Agent Teams | `reference/execution-with-team.md` | TeamCreate/SendMessage, parallel Claude Code instances in tmux |
@@ -145,6 +147,16 @@ Execute only:
 /trekoon <epic-id> execute
 ```
 
+When you execute an epic, use subagents by default for any meaningful work that
+can run independently. Keep small or tightly coupled tasks in the parent agent.
+Use the main context for orchestration, dependency decisions, user
+communication, and final synthesis while Trekoon remains the durable source of
+truth.
+
+If a harness has a higher-priority rule requiring explicit permission before
+subagents, surface that immediately instead of silently doing broad work
+yourself.
+
 Plan and execute end to end:
 
 ```
@@ -154,9 +166,11 @@ dependency order until the epic is complete
 
 ## Agent Teams
 
-For larger epics, Trekoon supports Claude Code Agent Teams. Instead of
-sequential sub-agents, you get real parallel Claude Code instances coordinated
-through `TeamCreate` and `SendMessage`, each running in its own tmux pane.
+For larger epics, use the current harness's native subagent mechanism for
+meaningful work that can run independently. Claude Code Agent Teams are one
+runtime-specific option: instead of sequential sub-agents, you get real parallel
+Claude Code instances coordinated through `TeamCreate` and `SendMessage`, each
+running in its own tmux pane.
 
 Requires Claude Code env variable `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=true`.
 
@@ -191,7 +205,9 @@ trekoon board update    # refresh assets only
 ```
 
 Binds to `127.0.0.1` only with a per-session token. Gives you an epics
-overview, kanban workspace per epic, task detail modals, and search.
+overview, kanban workspace per epic, task detail modals, and search. The board
+client subscribes to `/api/snapshot/stream` (SSE), so mutations from another
+shell, worktree, or browser tab show up live without a manual refresh.
 
 ## Commands
 
@@ -199,15 +215,20 @@ overview, kanban workspace per epic, task detail modals, and search.
 | --- | --- |
 | Set up a repo | `trekoon init` |
 | Open the local board | `trekoon board open` |
-| Plan work | `trekoon epic create ...`, `trekoon epic expand ...` |
+| Plan work | `trekoon --toon epic create ...`, `trekoon --toon epic expand ...` |
 | Create tasks in bulk | `trekoon task create-many ...` |
 | Add dependencies | `trekoon dep add-many ...` |
 | Start an agent session | `trekoon session --epic <id>` |
 | Get next-action suggestions | `trekoon suggest --epic <id>` |
 | Check epic progress | `trekoon epic progress <id>` |
 | Export epic to Markdown | `trekoon epic export <id>` |
+| Claim a task atomically | `trekoon task claim <id> --owner <owner>` |
+| Claim a subtask atomically | `trekoon subtask claim <id> --owner <owner>` |
 | Mark a task done | `trekoon task done <id>` |
 | Sync across worktrees | `trekoon sync pull --from main` |
+| Back up the DB before migrations | `trekoon migrate backup` |
+| Reveal full board token | `trekoon board open --reveal-token` |
+| Run experimental daemon | `trekoon serve` (experimental) |
 | Get help | `trekoon [command] -h` |
 
 Every command supports `--toon`, `--json`, `--compact` for structured output.

package/docs/ai-agents.md

@@ -14,22 +14,39 @@ agent to:
 - append progress and blocker notes instead of rewriting descriptions
 - preview scoped replace before `--apply`
 - treat `.trekoon` as shared repo-scoped state
+- use harness-local todo/task tools as a live progress display while keeping
+  Trekoon as the durable source of truth
+- use subagents by default for meaningful work that can run independently when
+  the harness exposes them
+- keep small or tightly coupled tasks in the parent agent so the main context
+  stays available for orchestration and decisions
 
 The skill ships with reference guides so the agent can handle the full
 plan-to-completion workflow from one install:
 
 ```
 .agents/skills/trekoon/
-  SKILL.md                      <- command reference, status machine, agent loop
+  SKILL.md                      <- command router and operating contract
   reference/
+    harness-primitives.md       <- universal agent/task/question/review primitives
     planning.md                 <- decomposition, writing standard, validation
     execution.md                <- graph building, lane dispatch, verification
     execution-with-team.md      <- Agent Teams pattern (Claude Code only)
 ```
 
-The agent loads the relevant reference on demand: `planning.md` when asked to
-plan, `execution.md` when asked to execute, `execution-with-team.md` when Agent
-Teams are available.
+The command shape determines what the agent loads:
+
+| User command | Required references |
+| --- | --- |
+| `/trekoon plan <goal>` | `harness-primitives.md`, then `planning.md` |
+| `/trekoon <id>` | `SKILL.md` only, unless deeper analysis is needed |
+| `/trekoon <id> analyze` | `SKILL.md` plus targeted Trekoon reads |
+| `/trekoon <id> execute` | `harness-primitives.md`, then `execution.md` |
+| `/trekoon <id> team execute` | `harness-primitives.md`, then `execution-with-team.md` |
+
+`harness-primitives.md` is loaded before planning or execution because those
+modes may need structured questions, local progress displays, subagent
+delegation, review agents, and runtime-specific orchestration.
 
 ## Install the skill
 
@@ -42,6 +59,7 @@ Create a project-local editor link when your agent environment supports it:
 ```bash
 trekoon skills install --link --editor opencode
 trekoon skills install --link --editor claude
+trekoon skills install --link --editor codex
 trekoon skills install --link --editor pi
 trekoon skills install --link --editor opencode --to ./.custom-editor/skills
 trekoon skills update
@@ -52,6 +70,7 @@ Path behavior:
 - Canonical install: `.agents/skills/trekoon/SKILL.md`
 - OpenCode link: `.opencode/skills/trekoon`
 - Claude link: `.claude/skills/trekoon`
+- Codex link: `.codex/skills/trekoon`
 - Pi link: `.pi/skills/trekoon`
 - `--to <path>` changes only the editor link root
 - `--allow-outside-repo` is for intentional external links
@@ -89,10 +108,25 @@ Typical flow:
 4. Execute the plan (reads `reference/execution.md` internally)
 5. Update progress, blockers, and completion state as you go
 
+> **Experimental — not for routine agent use:** `trekoon serve` and the
+> `--daemon` flag are experimental. Use the default one-shot CLI path for
+> any production or automated agent workflow until daemon mode stabilizes.
+
 ## Default execution loop
 
 The core loop: **session, work, task done, repeat**.
 
+When you execute an epic, use subagents by default for any meaningful work that
+can run independently. Keep small or tightly coupled tasks in the parent agent.
+Build the Trekoon execution graph, group ready tasks into lanes, keep a local
+todo/task display for the user, and synthesize the results. Use the parent
+context for dependency decisions and finishing the epic.
+
+Some harnesses have higher-priority rules that require explicit user permission
+before spawning subagents. When that happens, say so immediately after
+discovering independent lanes and ask for permission before broad execution. Do
+not silently default to single-agent execution.
+
 Start with a single orientation call, optionally scoped to an epic:
 
 ```bash
@@ -113,14 +147,24 @@ If the session shows you're behind, pull tracker events before claiming work:
 trekoon --toon sync pull --from main
 ```
 
-Claim work, assign ownership, then finish or report a block:
+Claim work atomically using SQL compare-and-swap (recommended for parallel
+agents), then finish or report a block:
 
 ```bash
-trekoon --toon task update <task-id> --status in_progress --owner "agent-1"
+trekoon --toon task claim <task-id> --owner "agent-1"
 trekoon --toon task done <task-id>
 trekoon --toon task update <task-id> --append "Blocked by <reason>" --status blocked
 ```
 
+`task claim` is the safe primitive for parallel agents. Two concurrent calls on
+the same task return exactly one `claimed: true`. Check `data.claimed` before
+proceeding — if false, another agent won the race.
+
+```bash
+# Fallback: non-atomic claim (single-agent or sequential workflows only)
+trekoon --toon task update <task-id> --status in_progress --owner "agent-1"
+```
+
 Use `task done` when the task is actually finished. It marks the task complete,
 auto-transitions through `in_progress` if needed, reports newly unblocked
 downstream tasks, warns about incomplete subtasks, and returns the next ready
@@ -179,6 +223,20 @@ notes, mark it done, and repeat until there are no ready tasks or you hit a
 blocker.
 ```
 
+### Execute with subagents where useful
+
+```text
+/trekoon <epic-id> execute -- use subagents by default for meaningful work that
+can run independently, keep Trekoon as the source of truth, and use local task
+tools to show live progress.
+```
+
+Short form for harnesses that require explicit delegation wording:
+
+```text
+/trekoon <epic-id> execute with subagents
+```
+
 ### Plan and execute end to end
 
 ```text
@@ -201,6 +259,7 @@ Use the narrowest command that answers the question:
 | One task with subtasks | `trekoon --toon task show <task-id> --all` |
 | One epic tree | `trekoon --toon epic show <epic-id> --all` |
 | Export epic to Markdown | `trekoon --toon epic export <epic-id>` |
+| Snapshot the DB before manual recovery | `trekoon --toon migrate backup [--retain <n>]` |
 | Repeated text in one scope | `trekoon --toon epic|task|subtask search ...` |
 
 For repeated text changes, use the safe replace loop:

package/docs/commands.md

@@ -12,20 +12,21 @@ the quickest way to get started, read [Quickstart](quickstart.md) first.
 - `trekoon epic <create|expand|list|show|search|replace|update|delete|progress>`
 - `trekoon session [--epic <epic-id>]`
 - `trekoon suggest [--epic <epic-id>]`
-- `trekoon task <create|create-many|list|show|ready|next|done|search|replace|update|delete>`
-- `trekoon subtask <create|create-many|list|search|replace|update|delete>`
+- `trekoon task <create|create-many|list|show|ready|next|done|search|replace|update|delete|claim>`
+- `trekoon subtask <create|create-many|list|search|replace|update|delete|claim>`
 - `trekoon dep <add|add-many|remove|list|reverse>`
 - `trekoon events prune [--dry-run] [--archive] [--retention-days <n>]`
-- `trekoon migrate <status|rollback> [--to-version <n>]`
+- `trekoon migrate <status|rollback|backup> [--to-version <n>] [--retain <n>]`
 - `trekoon sync status [--from <branch>]`
 - `trekoon sync pull --from <branch>`
 - `trekoon sync resolve <conflict-id> --use ours|theirs [--dry-run]`
 - `trekoon sync resolve --all --use ours|theirs [--entity <id>] [--field <name>] [--dry-run]`
 - `trekoon sync conflicts <list|show> [--mode pending|all]`
-- `trekoon skills install [--link --editor opencode|claude|pi] [--to <path>] [--allow-outside-repo]`
-- `trekoon skills install -g|--global [--editor opencode|claude|pi]`
+- `trekoon skills install [--link --editor opencode|claude|codex|pi] [--to <path>] [--allow-outside-repo]`
+- `trekoon skills install -g|--global [--editor opencode|claude|codex|pi]`
 - `trekoon skills update`
 - `trekoon wipe --yes`
+- `trekoon serve` (experimental)
 
 ## Global options
 
@@ -33,6 +34,7 @@ the quickest way to get started, read [Quickstart](quickstart.md) first.
 - `--toon` — TOON-encoded output (preferred for agent loops)
 - `--compact` — strips contract metadata from TOON/JSON envelopes
 - `--compat <mode>` — explicit machine compatibility behavior
+- `--daemon` — (experimental) route the call through a running `trekoon serve` daemon over a Unix socket; transparently falls back to the in-process CLI when no daemon is reachable. Equivalent to `TREKOON_DAEMON=1`.
 - `--help` — root and command help
 - `--version` — CLI version
 
@@ -73,6 +75,7 @@ Board API endpoints (all require token authentication):
 | Method | Endpoint | Purpose |
 | --- | --- | --- |
 | `GET` | `/api/snapshot` | Full board state (epics, tasks, subtasks, deps, counts) |
+| `GET` | `/api/snapshot/stream` | Server-sent events stream of `snapshot` and `snapshotDelta` events for live updates |
 | `PATCH` | `/api/epics/{id}` | Update epic title, description, or status |
 | `PATCH` | `/api/tasks/{id}` | Update task title, description, status, or owner |
 | `PATCH` | `/api/subtasks/{id}` | Update subtask title, description, status, or owner |
@@ -81,6 +84,19 @@ Board API endpoints (all require token authentication):
 | `POST` | `/api/dependencies` | Add dependency edge (sourceId, dependsOnId) |
 | `DELETE` | `/api/dependencies?sourceId=...&dependsOnId=...` | Remove dependency |
 
+**Note:** the SSE auth token rides as a `?token=` query parameter on
+`/api/snapshot/stream` (EventSource cannot set custom headers), so it may
+appear in reverse-proxy access logs; treat access logs as sensitive if the
+board is exposed beyond localhost.
+
+Board mutations from any source — board UI, CLI in another shell, or another
+worktree — propagate to every connected client through the SSE stream. The CLI
+side is driven by a WAL-watcher that diffs the snapshot when
+`.trekoon/trekoon.db-wal` changes; in-process mutations publish deltas
+directly. PATCH endpoints accept `If-Match: <updatedAt-ms>` for optimistic
+concurrency: a stale value returns `409` with `currentUpdatedAt`. Missing
+`If-Match` is allowed for back-compat.
+
 Board commands don't accept command-specific options yet. For tests and local
 development, `TREKOON_BOARD_ASSET_ROOT` overrides the bundled asset source.
 
@@ -183,6 +199,41 @@ trekoon subtask update <subtask-id> --owner "agent-2"
 
 Also accepted on `PATCH /api/tasks/{id}` and `PATCH /api/subtasks/{id}`.
 
+## Task claim
+
+```bash
+trekoon task claim <task-id> --owner <owner>
+trekoon subtask claim <subtask-id> --owner <owner>
+```
+
+Atomically claim a task (or subtask) using a SQL compare-and-swap. Sets
+`status=in_progress` and `owner=<owner>` only when:
+
+- The task is in `todo` or `blocked` status, **and**
+- The `owner` column is `NULL` or already equal to `<owner>` (re-entrant claim)
+
+Two concurrent `task claim` calls racing on the same task return exactly one
+`claimed: true`. The loser gets `claimed: false` with `currentOwner` and
+`currentStatus` reflecting the winner's write.
+
+`--owner` is required.
+
+Response envelope:
+
+```text
+ok: true
+command: task.claim | subtask.claim
+data:
+  claimed: true | false
+  currentOwner: <owner> | null
+  currentStatus: in_progress | todo | blocked | done
+  task | subtask: { ...full record... }   # present only when claimed=true
+```
+
+When `claimed` is false, `task`/`subtask` is absent. `currentOwner` tells you
+who holds the lock. `currentStatus` tells you why the claim failed (already
+`done`, or `in_progress` by another owner).
+
 ## Task done
 
 `trekoon task done <task-id>` marks a task complete and returns the next ready
@@ -289,6 +340,99 @@ trekoon --toon sync conflicts show <conflict-id>
 `list` defaults to `--mode pending`. Use `--mode all` to include resolved
 conflicts.
 
+## Migrate commands
+
+### `migrate status`
+
+```bash
+trekoon --toon migrate status
+```
+
+Reports `currentVersion`, `latestVersion`, and pending migration count.
+
+### `migrate rollback`
+
+```bash
+trekoon --toon migrate rollback [--to-version <n>]
+```
+
+Rolls back schema migrations one version (default) or down to `--to-version`.
+Migrations 0004, 0005, and 0006 are irreversible (ALTER TABLE plus dependency
+data cleanup). Rolling back below those versions errors with code
+`migration_down_unsupported`. Take a backup first; restore by copying the
+backup over `.trekoon/trekoon.db`.
+
+### `migrate backup`
+
+```bash
+trekoon --toon migrate backup
+trekoon --toon migrate backup --retain 5
+```
+
+Snapshots `.trekoon/trekoon.db` to a timestamped sibling file
+(`trekoon.db.backup-<ISO8601>`) using SQLite `VACUUM INTO`. The source database
+is opened read-only, so a backup never mutates live state. Returns
+`backupPath`, `bytes`, `migrationVersion`, and `latestVersion` for machine
+consumers. Backups stay inside `.trekoon/` and are gitignored along with the
+rest of the directory.
+
+`--retain <n>` keeps the last `n` timestamped backups; older siblings are
+pruned in the same call. Default is `10`. Backups created within the same
+millisecond produce a deterministic collision error that names the existing
+file so operators can identify it.
+
+To restore from a backup: stop any process holding the DB, then copy the
+backup file over `.trekoon/trekoon.db`.
+
+## Daemon (experimental)
+
+`trekoon serve` runs Trekoon as a long-lived process listening
+on a Unix-domain socket inside `<storage-root>/.trekoon/daemon.sock`. The
+daemon holds the SQLite connection in memory, so subsequent invocations skip
+Bun startup, module load, migration probes, and database open.
+
+Status: **experimental**. Not on by default. The default one-shot CLI behavior
+is unchanged whether or not the daemon is running.
+
+Activate the client with one of:
+
+```bash
+TREKOON_DAEMON=1 trekoon session
+trekoon --daemon session
+```
+
+If no daemon is reachable, the client transparently falls back to the in-process
+one-shot path. Calls run against the daemon return envelopes equivalent to the
+in-process call modulo:
+
+- The per-request `requestId` and `persistedAt` fields.
+- Environment variables. The client's `process.env` is **not** forwarded over
+  the socket; the daemon process uses the environment captured at `trekoon
+  serve` startup. If a command's behavior depends on an env var (e.g. an
+  override flag), set it before launching the daemon — not on the client side.
+
+The daemon request contract is `{argv, cwd}` only — there is no per-call env
+channel. This narrows the secret-leak surface area and keeps the equivalence
+claim crisp.
+
+Security:
+
+- Socket file mode `0o600`; parent `.trekoon/` directory forced to `0o700`.
+- The umask is tightened to `0o077` around `server.listen()` so the socket
+  inode is created with restrictive perms (no TOCTOU window before chmod).
+- Daemon error envelopes return a sanitized message only — no stack trace,
+  which would otherwise leak filesystem paths or secret-bearing error text.
+  Stacks are still routed to the daemon's local `console.error` for operator
+  debugging.
+- Client env is not transmitted over the socket (see equivalence note above).
+- Stale sockets from prior crashes are unlinked at startup.
+- On `Ctrl-C` / `SIGTERM` the socket is unlinked and the cached database
+  connection is closed.
+
+Performance (see `bench/daemon-session.ts`): daemon median < 10 ms,
+cold one-shot median > 50 ms — roughly a 5–10× latency reduction for
+repeated calls by reusing the held-open SQLite connection.
+
 ## Related docs
 
 - [Quickstart](quickstart.md)

package/docs/machine-contracts.md

@@ -254,6 +254,12 @@ data:
 Transition details are in `data`, not `error.details`. `error` only has `code`
 and `message`.
 
+**Allowed bypass:** `task done` performs an atomic single-transaction direct
+write to `done` from any non-`done` status (`todo`, `blocked`, `in_progress`),
+emitting one `task.updated` event — there is no intermediate `in_progress`
+event when starting from `todo`/`blocked`. This is the only sanctioned
+bypass of the status-machine checker.
+
 ## Epic progress
 
 ```bash
@@ -328,6 +334,69 @@ data:
     pendingConflicts
 ```
 
+## Task claim
+
+```bash
+trekoon --toon task claim <task-id> --owner <owner>
+trekoon --toon subtask claim <subtask-id> --owner <owner>
+```
+
+Atomically claims a task or subtask using SQL compare-and-swap. The single
+UPDATE predicate ensures exactly one concurrent caller gets `claimed: true`.
+
+Success (claimed):
+
+```text
+ok: true
+command: task.claim | subtask.claim
+data:
+  claimed: true
+  currentOwner: <owner>
+  currentStatus: in_progress
+  task | subtask: { ...full record... }
+```
+
+Not claimed (another owner holds it, or status is done/in_progress by others):
+
+```text
+ok: true
+command: task.claim | subtask.claim
+data:
+  claimed: false
+  currentOwner: <string> | null
+  currentStatus: in_progress | done | todo | blocked
+```
+
+Note: `claimed: false` is a successful response (`ok: true`). The command
+reports the current state, not an error condition. Check `data.claimed` to
+distinguish the two cases.
+
+Dependency gating on claim (cr-expert hardening): when the task or subtask is
+in `blocked` or `todo` and has unresolved dependencies, the claim atomically
+fails with `code: dependency_blocked` rather than flipping the row into
+`in_progress`. This mirrors `task done` semantics so neither
+forward-progress transition (`todo|blocked → in_progress` via claim,
+`* → done` via `task done`) can bypass dependency resolution.
+
+```text
+ok: false
+command: task.claim | subtask.claim
+error:
+  code: dependency_blocked
+  message: "task cannot transition to in_progress while dependencies are unresolved"
+data:
+  unresolvedDependencyCount: <number>
+  unresolvedDependencyIds: [<id>, ...]
+  unresolvedDependencies: [{ id, kind, status }, ...]
+```
+
+The only intentional direct-status-write exception in the codebase remains
+`MutationService.markTaskDoneAtomically`, which bypasses
+`validateStatusTransition` for the `* → done` flip but still goes through
+`assertNoUnresolvedDependenciesForStatusTransition` before issuing the UPDATE.
+No other call site is permitted to write `status` directly without going
+through the public transition checker.
+
 ## Owner field in updates
 
 Task and subtask update payloads include `owner`:
@@ -538,6 +607,60 @@ error:
   message: "Pending conflicts changed before batch resolution could be applied."
 ```
 
+## Error code registry
+
+All machine-visible error codes emitted by Trekoon. Every `error.code` value in
+any `ok: false` response will be one of the following strings.
+
+| Code | Description |
+|---|---|
+| `already_done` | Entity is already in `done` status; transition is a no-op. |
+| `already_resolved` | Conflict was resolved by another process before this write. |
+| `ambiguous_legacy_state` | Legacy worktree state is ambiguous and cannot be automatically resolved. |
+| `backpressure` | SSE snapshot stream disconnected a slow client whose queued bytes exceeded the hard limit. |
+| `backup_already_exists` | A backup file already exists at the target path; overwrite was not requested. |
+| `backup_database_missing` | Source database file not found when attempting to create a backup. |
+| `backup_failed` | Backup operation failed (I/O or copy error). |
+| `cancelled` | Operation was cancelled by the user (e.g. confirmation prompt rejected). |
+| `confirmation_required` | Human-mode operation requires explicit confirmation before proceeding. |
+| `conflict_set_changed` | Batch conflict set changed between preview and confirmed write. |
+| `daemon_start_failed` | Daemon failed to start (socket bind error or already running). |
+| `database_busy` | SQLite database is locked; retry after a short wait. |
+| `dependency_blocked` | Cascade update blocked because one or more descendants have unresolved dependencies. |
+| `disallowed_field` | Sync resolve attempted to write a field that is not on the allow-list. |
+| `events_failed` | Event log query or export failed. |
+| `install_failed` | Skill installation failed (file copy or permission error). |
+| `internal_error` | Unexpected internal error; inspect server logs for details. |
+| `invalid_args` | Required positional arguments are missing or malformed. |
+| `invalid_dependency` | Dependency edge is invalid (self-loop, wrong entity type, or duplicate). |
+| `invalid_input` | One or more option values failed validation. |
+| `invalid_path` | File path is invalid for the requested operation (e.g. path is a directory). |
+| `invalid_source` | Source entity for a dependency or sync operation does not exist or is of wrong kind. |
+| `invalid_state` | Entity or system is in a state that does not permit the requested operation. |
+| `invalid_subcommand` | Unrecognised subcommand for this command group. |
+| `legacy_import_failed` | Import from a legacy (pre-`.trekoon`) data directory failed. |
+| `migrate_failed` | Database schema migration failed. |
+| `migration_down_unsupported` | Down-migrations are not supported; only forward migrations are allowed. |
+| `missing_asset` | Expected bundled asset (skill file, template) was not found. |
+| `no_matching_conflicts` | `sync resolve --all` filters matched zero pending conflicts. |
+| `not_found` | Requested entity (epic, task, subtask, dependency) does not exist. |
+| `orphaned_external_node` | Dependency graph contains a node that belongs to a different epic. |
+| `outside_repo_target` | Skill install target path is outside the repository root. |
+| `permission_denied` | File-system permission denied for the requested path. |
+| `precondition_failed` | `If-Match` precondition header did not match the entity's current `updatedAt`. |
+| `row_not_found` | Sync resolve target row no longer exists in the database. |
+| `status_transition_invalid` | Requested status transition is not permitted by the status machine. |
+| `stream_unavailable` | SSE snapshot stream is not available (board not initialised or shutting down). |
+| `sync_failed` | Sync pull or push operation failed. |
+| `tracked_ignored_mismatch` | Worktree is tracked by Trekoon but its path is in `.gitignore`, or vice-versa. |
+| `unauthorized` | Request lacks valid authentication credentials. |
+| `unhandled_command` | Command matched a known group but no case handled the subcommand. |
+| `unknown_command` | Top-level command token is not recognised. |
+| `unknown_option` | An option flag passed to the command is not recognised. |
+| `unsupported_entity_kind` | Sync resolve encountered an entity kind that the writer does not handle. |
+| `update_failed` | Skill update failed (download, copy, or permission error). |
+| `wrong_entity_type` | Operation requires a specific entity kind but a different kind was supplied. |
+
 ## Related docs
 
 - [Quickstart](quickstart.md)

package/docs/quickstart.md

@@ -69,7 +69,7 @@ if you just need to refresh the runtime assets without opening the browser.
 ## Create work
 
 ```bash
-trekoon epic create --title "Agent backlog stabilization" --description "Track stabilization work" --status todo
+trekoon --toon epic create --title "Agent backlog stabilization" --description "Track stabilization work" --status todo
 trekoon task create --title "Implement sync status" --description "Add status reporting" --epic <epic-id> --status todo
 trekoon subtask create --task <task-id> --title "Add cursor model" --status todo
 ```
@@ -88,7 +88,7 @@ trekoon task list --all --view compact
 If you already know the full epic tree, create everything in one call:
 
 ```bash
-trekoon epic create \
+trekoon --toon epic create \
   --title "Batch command rollout" \
   --description "Ship one-shot planning workflows" \
   --task "task-a|First task|First description|todo" \
@@ -118,7 +118,7 @@ For larger updates, use batch commands instead of looping:
 | Multiple tasks under one epic | `trekoon task create-many --epic <epic-id> --task ...` |
 | Multiple subtasks under one task | `trekoon subtask create-many <task-id> --subtask ...` |
 | Multiple dependency edges | `trekoon dep add-many --dep ...` |
-| Expand an existing epic | `trekoon epic expand <epic-id> ...` |
+| Expand an existing epic | `trekoon --toon epic expand <epic-id> ...` |
 
 These validate the whole batch before applying, so a bad input fails the entire
 operation instead of leaving partial state.
@@ -148,6 +148,58 @@ a file extension means "write this file"; no extension means "put the default-
 named file in this directory". Use `--overwrite` to resave after the plan state
 changes.
 
+## Claim work atomically
+
+When multiple agents or lanes work in parallel, use `claim` to avoid races:
+
+```bash
+trekoon task claim <task-id> --owner <owner>
+trekoon subtask claim <subtask-id> --owner <owner>
+```
+
+Both commands use a SQL compare-and-swap: the claim succeeds only when the item
+is `todo` or `blocked` and the owner is `NULL` or already set to `<owner>`.
+The response includes `claimed` (true/false), `currentOwner`, `currentStatus`,
+and the full entity record on success. Two concurrent claims return exactly one
+`claimed=true`.
+
+## Database backup and migration
+
+Before any manual migration recovery, snapshot the database:
+
+```bash
+trekoon migrate backup
+trekoon migrate backup --retain 5   # keep last 5 backups (default 10)
+```
+
+This writes a timestamped copy of `.trekoon/trekoon.db` next to the live file.
+To check the current schema version or roll back:
+
+```bash
+trekoon migrate status
+trekoon migrate rollback              # one version back
+trekoon migrate rollback --to-version 1
+```
+
+## Daemon mode (experimental)
+
+> **Not for routine agent use.** `trekoon serve` and `--daemon` are
+> experimental; use the default one-shot CLI path in automated workflows.
+
+`trekoon serve` starts a foreground daemon on a Unix-domain socket inside
+`.trekoon`. Subsequent calls skip Bun startup, module load, and database
+open — per `bench/daemon-session.ts`: daemon median < 10 ms vs. cold
+one-shot median > 50 ms:
+
+```bash
+trekoon serve                         # start the daemon (foreground)
+trekoon --daemon session              # route a call through the daemon
+TREKOON_DAEMON=1 trekoon session      # same, via environment variable
+```
+
+If the socket is missing or unreachable the client falls back silently to the
+normal one-shot path. The socket is 0o600 and `.trekoon` is forced to 0o700.
+
 ## Check progress
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trekoon",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "AI-first task tracking that lives in your repo. You describe what to build, your agent plans it as a dependency graph, then executes it task by task",
   "keywords": [
     "ai",