taskchef 6.1.3 → 7.1.0

package/docs/firstmate-taskchef-comparison.md

@@ -0,0 +1,279 @@
+# FirstMate and TaskChef: architecture and fit
+
+> **Research, not contract.** This document compares two version-scoped
+> implementations. It does not define TaskChef behavior; the normative source
+> is the [TaskChef specification](spec.md). Recheck the linked sources before relying on these
+> conclusions after the access date.
+
+For TaskChef installation and everyday use, start with the
+[README](../README.md). For its current implementation flow, see
+[TaskChef workflows](workflows.md).
+
+## Scope and sources
+
+**Access date:** 2026-08-25
+
+**TaskChef scope:** the TaskChef 7 contract in this repository revision.
+Current behavior was verified against the [specification](spec.md),
+[workflows](workflows.md), packaged skills,
+[MCP implementation](https://github.com/favoyang/taskchef/blob/main/src/mcp.js),
+[workspace implementation](https://github.com/favoyang/taskchef/blob/main/src/workspace.js),
+CLI, dashboard, and tests.
+
+**FirstMate scope:**
+[`kunchenguid/firstmate`](https://github.com/kunchenguid/firstmate) at commit
+[`038d0f7`](https://github.com/kunchenguid/firstmate/tree/038d0f7ec6ba7238a151722931434dcf06ff37c4),
+the tip of its official `main` branch when accessed. Repository history already
+identified Kunchenguid's project as the intended FirstMate; no competing local
+reference pointed to another project.
+
+Primary FirstMate sources:
+
+- [README](https://github.com/kunchenguid/firstmate/blob/038d0f7ec6ba7238a151722931434dcf06ff37c4/README.md)
+  for product goals, installation, features, and supported harnesses;
+- [AGENTS.md](https://github.com/kunchenguid/firstmate/blob/038d0f7ec6ba7238a151722931434dcf06ff37c4/AGENTS.md)
+  for the coordinator's operating contract, authority, delegation, supervision,
+  and delivery rules;
+- [Architecture](https://github.com/kunchenguid/firstmate/blob/038d0f7ec6ba7238a151722931434dcf06ff37c4/docs/architecture.md)
+  for watcher, session backend, worktree, state, and recovery mechanics;
+- [Configuration](https://github.com/kunchenguid/firstmate/blob/038d0f7ec6ba7238a151722931434dcf06ff37c4/docs/configuration.md)
+  for operational-home state, project modes, profiles, and extension settings;
+- [Codex App boundary](https://github.com/kunchenguid/firstmate/blob/038d0f7ec6ba7238a151722931434dcf06ff37c4/docs/codex-app-backend.md)
+  for the current limit that Codex desktop is not a selectable FirstMate runtime
+  backend;
+- [Vision](https://github.com/kunchenguid/firstmate/blob/038d0f7ec6ba7238a151722931434dcf06ff37c4/VISION.md)
+  for the intended single-liaison, durable-fleet experience.
+
+Unless labeled **Inference** or **Recommendation**, statements below are facts
+supported by those version-scoped sources or the TaskChef 7 codebase.
+
+## Executive comparison
+
+**Fact:** TaskChef is a Codex-native dispatch and task-index layer. It routes a
+request to visible Codex tasks, returns immediately, and lets the user work with
+each executor directly. It stores one latest task snapshot and offers read-only
+reports and a local dashboard.
+
+**Fact:** FirstMate is an agent distribution for running a supervised crew. The
+user talks to one primary coordinator, which dispatches workers into isolated
+worktrees and visible session backends, watches meaningful state, escalates
+decisions, follows configured delivery modes, and reconciles durable fleet state
+after restart.
+
+**Inference:** The products overlap at intake, project routing, parallel task
+creation, and observability. Their central responsibility boundary differs:
+TaskChef hands control to native Codex tasks; FirstMate retains coordination
+responsibility until an outcome is landed, transferred, or safely preserved.
+
+## Architecture at a glance
+
+| Dimension | TaskChef 7 | FirstMate at `038d0f7` |
+| --- | --- | --- |
+| Primary goal | Put multi-project work into the right visible Codex task and make it findable later. | Let one person direct a supervised crew across projects through one liaison. |
+| Product form | Codex plugin: three skills, local MCP server, data CLI, and loopback dashboard. | Cloneable agent distribution: instructions, internal skills, scripts, policies, and private on-disk state. |
+| Runtime | Native Codex desktop tasks are the executors and live source of truth. | Harness-driven workers in tmux by default, with documented alternative session backends; Codex can be a harness, but Codex desktop is not a runtime backend. |
+| Coordinator lifetime | Dispatcher returns immediately and does not supervise. | First mate remains active and uses watcher/guard mechanisms to supervise meaningful events. |
+| Project isolation | Delegates to the configured Codex project; isolation follows native Codex/project behavior. | Ship and scout workers require separate Treehouse- or backend-managed worktrees. |
+| Durable state | `taskchef.json` plus latest snapshots in `tasks.jsonl`. | Backlog, briefs, reports, task metadata, status-event logs, decisions, endpoint records, and configuration under an operational home. |
+
+## Goals and user experience
+
+### TaskChef
+
+**Fact:** The user submits work in the dispatcher or explicitly invokes
+`$taskchef-delegate` elsewhere. TaskChef creates independently openable Codex
+tasks and returns links. The user opens those tasks for questions, approvals,
+follow-ups, and delivery.
+
+**Strength:** This preserves the familiar Codex task model and makes delegation
+transparent. There is little new runtime or policy to learn.
+
+**Limitation:** Several active executors still mean several conversations. A
+dispatcher report reduces search cost but does not own supervision or recovery.
+
+### FirstMate
+
+**Fact:** The user talks to the first mate as the single liaison. Crewmates do
+project work; the first mate reads projects, supervises the fleet, reconciles
+direct user intervention, brings forward decisions, and reports outcomes.
+
+**Strength:** The user can look away while one coordinator retains context and
+responsibility across a larger fleet.
+
+**Limitation:** The experience requires more local tooling, state, policy, and
+operational machinery than a simple dispatcher. The coordinator's summaries
+also insert an interpretation layer between user and worker.
+
+## Task identity and persistence
+
+### TaskChef
+
+**Fact:** `prepare_dispatch` allocates a TaskChef UUID and exact first-line
+marker. `record_task` persists the marked instruction before native task
+creation. The executor then reads its own `CODEX_THREAD_ID` and calls
+`link_task`; the dispatcher neither searches recent tasks nor repairs identity.
+The task record keeps one immutable intent/project snapshot plus the latest
+identity and semantic result fields.
+
+**Fact:** Schema 4 linking accepts one atomic null-to-canonical-Codex-UUIDv7
+transition. Exact retries are idempotent, conflicts fail, and link interruption
+remains visibly pending. Follow-up semantic results require a newer exact
+native turn ID.
+
+### FirstMate
+
+**Fact:** FirstMate assigns a task identity used across backlog entries, briefs,
+worker endpoint metadata, worktrees, status events, reports, and delivery
+artifacts. Durable disk records plus live backend state allow session-start and
+watcher reconciliation.
+
+**Inference:** TaskChef's identity model is narrower and easier to audit because
+it binds one record to one native executor. FirstMate's richer identity graph is
+necessary for supervision and recovery, but creates more reconciliation paths
+and invariants.
+
+## Delegation and concurrency
+
+### TaskChef
+
+**Fact:** The delegation skill splits only independently useful outcomes,
+routes each to exactly one configured project, records before one native
+creation call, and returns immediately. Multiple dispatchers and executors may
+share the workspace; locking and atomic JSONL replacement serialize mutations.
+
+**Fact:** TaskChef itself does not allocate worktrees, choose worker models,
+schedule dependencies, retry failed execution, or enforce a repository delivery
+mode. Those belong to Codex and each target project's instructions.
+
+### FirstMate
+
+**Fact:** FirstMate distinguishes ship work from scout investigation, prepares
+durable task material, selects a configured harness/profile, and spawns workers
+in isolated worktrees. Independent work may run concurrently; dependencies and
+unsafe shared state can hold work back.
+
+**Fact:** Supported runtime backends and harness adapters are explicit
+extension surfaces. The reference path uses tmux, while other documented
+backends have different verification or experimental status.
+
+## Status and results
+
+### TaskChef
+
+**Fact:** Persisted statuses are `working`, `needs_input`, `completed`, and
+`failed`. Executors report
+`working` at turn start and a semantic state before ending. Schema 5 preserves
+the last concise semantic result separately while a newer turn is working.
+`needs_input` is reserved for a real semantic decision, not a native approval
+prompt.
+
+**Fact:** The report skill treats cached results as evidence, takes one recent
+Codex metadata snapshot, and performs targeted exact-thread reads only for
+selected anomalies or freshness checks. It never polls or writes inferred
+state.
+
+### FirstMate
+
+**Fact:** FirstMate combines durable task/backlog state, append-only status
+events, live backend evidence, validation/delivery artifacts, and watcher wake
+records. Its supervision path distinguishes historical event logs from current
+worker state and escalates meaningful decisions, failures, stalls, and delivery
+milestones.
+
+**Inference:** TaskChef optimizes for a small truthful cache and bounded reads;
+FirstMate optimizes for continuity and active coordination. Neither data model
+can be substituted for the other without changing product responsibility.
+
+## UI and observability
+
+### TaskChef
+
+**Fact:** The loopback dashboard watches `tasks.jsonl`, streams stable validated
+snapshots, filters and orders tasks, shows notifications and details, and opens
+a task directly in Codex when its stored thread ID has a supported UUID shape.
+This navigation check does not prove schema 4 or 5 self-link provenance. The
+dashboard does not refresh native task state, submit replies, or show
+transcripts or token usage.
+
+**Fact:** The user can also ask for a live TaskChef report or inspect the data
+CLI. Executor work remains visible in normal Codex desktop tasks.
+
+### FirstMate
+
+**Fact:** Workers run in visible session backends that the user can inspect or
+intervene in, while the first mate remains the primary interface. Fleet views,
+durable status/decision records, and watcher-driven wakes provide the
+coordinator's operational observability.
+
+**Fact:** FirstMate currently documents Codex desktop as an integration
+boundary, not a selectable worker backend. Codex CLI can participate through a
+harness adapter.
+
+## Integrations and extension model
+
+| Area | TaskChef | FirstMate |
+| --- | --- | --- |
+| Codex | Built around native Codex projects, tasks, thread reads, and desktop deep links. | Codex is one verified harness; desktop tasks are not its worker runtime. |
+| GitHub | Configured repository URLs aid routing; delivery remains the executor project's concern. | GitHub CLI, PR state, and configured delivery modes are part of supervised shipping workflows. |
+| Skills | Three plugin skills with narrow bootstrap, delegate, and report responsibilities. | Internal firstmate-only skills plus standalone public skills; AGENTS.md routes conditional procedures. |
+| MCP | Four primary local TaskChef tools plus one deprecated compatibility alias own deterministic identity and state writes. | FirstMate describes itself as an agent distribution rather than an MCP product; deterministic behavior lives largely in scripts. |
+| Runtime extensions | Extend plugin skills/MCP/CLI/dashboard or compose native Codex capabilities. | Add or verify harness adapters, session backends, dispatch profiles, operational scripts, and optional integrations. |
+
+## Trust and security boundaries
+
+### TaskChef
+
+**Fact:** The MCP server is local and does not receive transport-authenticated
+Codex caller identity. Executor thread and turn IDs are cooperative assertions.
+Validation prevents accidental parent/provisional identity capture, duplicate
+identity use, stale-turn replacement, and malformed record mutation; it does
+not resist a deliberately forged local MCP caller.
+
+**Fact:** The dashboard binds to loopback, has no browser authentication, and
+uses Host/Origin checks for open-in-Codex actions. It must not be exposed
+through a proxy or tunnel. Workspace mutation uses one lock and atomic writes.
+
+### FirstMate
+
+**Fact:** The first mate is normally read-only over project clones; crewmates
+make project changes in isolated worktrees. Merge, destructive action, and
+standing autonomy are governed by explicit captain authority and per-project
+delivery modes. Scripts validate task endpoints, homes, worktrees, and state
+before sensitive lifecycle actions.
+
+**Inference:** TaskChef has a smaller local attack and failure surface but
+delegates repository safety to Codex and project policy. FirstMate explicitly
+owns more delivery and process safety, which improves centralized control while
+expanding the trusted script, state, backend, and credential surface.
+
+## Strengths, limitations, and best fit
+
+| Product | Strongest when | Less suitable when |
+| --- | --- | --- |
+| TaskChef | You already use Codex desktop; want one multi-project inbox; prefer direct executor conversations; value a small inspectable history; want minimal runtime machinery. | You want one liaison to supervise, recover, coordinate decisions, enforce delivery modes, or return only consolidated outcomes. |
+| FirstMate | You want one coordinator to run many visible workers; need isolated worktrees, durable fleet recovery, proactive supervision, and consistent delivery policy across projects. | You want native Codex desktop tasks as the core UI; prefer minimal setup and state; or want to interact directly with every executor without a coordinator layer. |
+
+## Recommendations
+
+**Recommendation:** Choose TaskChef when the problem is routing and task
+findability. Choose FirstMate when the problem is sustained supervisory
+attention and delivery coordination.
+
+**Recommendation:** Do not casually nest the systems. A FirstMate coordinator
+behind every TaskChef executor, or TaskChef dispatch inside every FirstMate
+worker, adds identity, authority, and recovery boundaries without a clear owner.
+If composition is necessary, define exactly one supervisory layer and treat the
+other as a leaf runtime or intake adapter.
+
+**Recommendation:** TaskChef can borrow outcome-oriented reporting ideas
+without becoming a supervisory runtime. Useful candidates are clearer
+completion summaries and an explicit user-approved result-to-follow-up handoff.
+They should preserve native Codex task ownership, bounded reads, and the absence
+of background supervision.
+
+**Inference:** Reproducing FirstMate's restart-proof crew management inside
+TaskChef would not be a small feature. It would require new durable state,
+worker liveness contracts, worktree ownership, decision queues, delivery
+authority, retry/recovery policy, and a continuously supervised runtime. That
+would change TaskChef's product category and should be evaluated as a separate
+architecture rather than an incremental dashboard enhancement.

package/docs/spec.md

@@ -0,0 +1,265 @@
+# TaskChef specification
+
+This is TaskChef's normative agent-facing contract. **MUST**, **MUST NOT**,
+**SHOULD**, and **MAY** are requirements in the RFC 2119 sense. The
+[README](../README.md) owns user setup and operation; [workflows](workflows.md)
+owns implementation walkthroughs; the [FirstMate comparison](firstmate-taskchef-comparison.md)
+is dated research, not contract.
+
+## Terminology
+
+| Term | Definition |
+| --- | --- |
+| **TaskChef** | The plugin, skills, MCP server, CLI, dashboard, and current workspace formats defined here. |
+| **Dispatcher workspace** | The per-user local data project selected by `--workspace`, then `TASKCHEF_WORKSPACE`, then `~/.agents/taskchef`. |
+| **Dispatcher** | The Codex task that accepts a request, routes it, records it, creates executors, and returns without supervising them. |
+| **Configured project** | One routing target in `taskchef.json`, identified by canonical local path and described by `name`, optional `description`, `isGitRepository`, and `githubRepos`. |
+| **Routing** | Selecting exactly one configured project and exactly one matching native Codex project for an outcome. |
+| **Delegated task** | One independently useful outcome represented by one TaskChef task UUID and snapshot. |
+| **Executor** | The native Codex task created to own and perform one delegated task. |
+| **Task record** | One complete JSON object in `tasks.jsonl`; it contains immutable intent/project fields and mutable identity/result fields. |
+| **Marker** | The exact first instruction line `<!-- taskchef_id=<lowercase full UUID> -->`, followed by a blank line. |
+| **Record-before-create** | Persisting a link-pending task before asking Codex to create its executor. |
+| **Self-linking** | The executor's one-way registration of its own canonical Codex UUIDv7 from `CODEX_THREAD_ID`. |
+| **Link-pending** | A working task whose `threadId` is null and `updatedBy` is `dispatcher`. |
+| **Current execution state** | The latest reported executor turn and its `working`, `needs_input`, `completed`, or `failed` status. |
+| **Last semantic result** | The most recent `completed`, `needs_input`, or `failed` outcome, preserved separately while a newer turn is working. |
+| **Current turn ID** | The canonical Codex UUIDv7 returned by an exact native read of the linked executor for the turn being reported. |
+| **Dashboard** | The loopback, read-only UI derived from validated workspace snapshots and bounded native actions. |
+| **Skill** | One packaged agent procedure: `taskchef-bootstrap`, `taskchef-delegate`, or `taskchef-report`. |
+
+## Components and ownership
+
+- `taskchef-bootstrap` MUST own initialization, project configuration, and
+  diagnostics. It MUST NOT dispatch or report unless separately requested.
+- `taskchef-delegate` MUST own routing and record-before-create delegation.
+  It MUST return after creation and MUST NOT poll, supervise, or infer identity.
+- `taskchef-report` MUST own on-demand reporting. It MUST NOT poll or persist
+  inferred state.
+- The MCP server MUST expose four primary lifecycle tools plus the deprecated
+  `report_result` compatibility alias specified below.
+- The CLI MAY administer and inspect the workspace, but MUST NOT provide a
+  second agent lifecycle protocol.
+- The dashboard MUST be read-only with respect to dispatcher files.
+- `docs/spec.md` is the single normative behavior source. Other documents
+  MUST link here rather than redefine the contract.
+
+## Workspace contract
+
+TaskChef MUST manage only `AGENTS.md`, `taskchef.json`, and `tasks.jsonl`
+inside the dispatcher workspace. It MUST preserve unrelated paths.
+
+`taskchef.json` MUST have schema version 2 and exactly:
+
+```json
+{
+  "schemaVersion": 2,
+  "projects": []
+}
+```
+
+Each project MUST contain `name`, normalized absolute `path`, boolean
+`isGitRepository`, and array `githubRepos`; `description` is optional.
+Names and paths MUST be unique. Git projects MUST be exact Git roots.
+Repository URLs MUST canonicalize to `https://github.com/<owner>/<repository>`
+and be case-insensitively deduplicated.
+
+`tasks.jsonl` MUST contain zero or more newline-terminated schema-4 or schema-5
+records, one per line. Schema 4 is read compatibility for the previously
+released format; every new record and state mutation MUST write schema 5.
+Other schemas or unsupported fields MUST be rejected without conversion.
+Reads and writes MUST reject symlinked managed files. Mutations
+MUST hold the shared workspace lock and replace state atomically; read-only
+operations MUST NOT require write permission.
+
+## Task schema
+
+Every record MUST contain exactly these fields:
+
+| Field | Contract |
+| --- | --- |
+| `schemaVersion` | Integer `5`; schema-4 records remain readable until their next mutation. |
+| `id` | Unique safe TaskChef ID; delegation uses a lowercase full UUID. |
+| `project` | Immutable configured-project snapshot. |
+| `title` | Non-empty display title. |
+| `instruction` | Non-empty executor instruction; link-pending records MUST contain the exact marker for `id`. |
+| `threadId` | Null while link-pending; after self-link, canonical Codex UUIDv7. Low-level current-schema direct records may hold another durable non-provisional ID but are outside the MCP delegation journey. |
+| `createdAt` | ISO 8601 creation timestamp. |
+| `status` | `working`, `needs_input`, `completed`, or `failed`. |
+| `summary` | Null while working; otherwise the current semantic state's non-empty summary of at most 2,000 characters. |
+| `turnId` | Null before turn reporting; otherwise the current reported turn. Linked MCP journeys use a canonical Codex UUIDv7. |
+| `updatedAt` | ISO 8601 timestamp not earlier than `createdAt` or the prior `updatedAt`; clock rollback cannot backdate a transition. |
+| `updatedBy` | `dispatcher` or `mcp`. |
+| `lastResult` | Null before a semantic result; otherwise `{status, summary, turnId, updatedAt}` preserving the latest semantic result. |
+
+Task IDs and non-null thread identities MUST be unique. The immutable intent
+fields MUST NOT change after recording.
+
+## Required lifecycle
+
+1. The dispatcher MUST call `prepare_dispatch` once per outcome.
+2. It MUST choose exactly one configured project and exact native-project path.
+3. It MUST build the instruction from the returned marker, a blank line, the
+   packaged executor contract paragraphs, and the user's outcome.
+4. It MUST call `record_task` with `threadId: null` before native creation.
+5. It MUST create exactly one native Codex executor and return immediately.
+6. The executor MUST read its own `CODEX_THREAD_ID` and call `link_task`
+   before substantive work. It MUST NOT use parent/session identity or guess.
+7. After initial linking, the executor MUST exactly read its linked task and
+   call `report_state` with that turn ID, `working`, and no summary before work.
+8. Before ending, it MUST call `report_state` for the same working turn with a
+   semantic status and concise summary.
+9. A follow-up MUST report `working` with its new current turn ID before work.
+   It MUST NOT reuse a prior turn.
+
+If native creation fails after recording, the dispatcher MUST call
+`report_state` with `failed`, null thread/turn IDs, and a bounded summary.
+A link failure MUST remain visible and retryable; the executor MUST report it
+visibly and MUST NOT continue substantive work.
+
+`needs_input` MUST mean a semantic user decision or missing fact. A native
+approval prompt MUST remain live Codex state and MUST NOT be stored as
+`needs_input`.
+
+## MCP interface
+
+All tools resolve the workspace internally. Callers MUST NOT supply a workspace
+path. Success returns both one text content item and the stated structured
+object. Validation, marker, identity, uniqueness, freshness, or filesystem
+failures are surfaced as tool errors and MUST NOT partially mutate the log.
+
+### `prepare_dispatch`
+
+**Caller:** dispatcher. **Mutation:** none.
+
+**Input:** empty object.
+
+**Structured output:**
+
+```text
+{ preparation: {
+  schemaVersion: 1,
+  workspace: string,
+  taskId: string,
+  preparedAt: string,
+  marker: string,
+  projectCount: number,
+  projects: Project[]
+} }
+```
+
+The tool generates a fresh task UUID and exact marker and returns current
+routing targets. An invocation is not idempotent: each successful call creates
+new preparation values, though it writes no state.
+
+**Annotations:** `readOnlyHint: true`, `destructiveHint: false`,
+`openWorldHint: false`.
+
+### `record_task`
+
+**Caller:** dispatcher. **Mutation:** atomically appends one task.
+
+**Input:**
+
+| Field | Type and rule |
+| --- | --- |
+| `id` | Non-empty string; MUST equal the instruction marker. |
+| `project` | Non-empty configured project path. |
+| `title` | Non-empty string. |
+| `instruction` | Non-empty string beginning with the exact marker and blank line. |
+| `threadId` | Literal null. |
+
+**Structured output:** `{ task: Task }`.
+
+The returned task has schema 5, `working`, null summary/turn/thread/lastResult,
+`updatedBy: dispatcher`, and equal creation/update timestamps. Duplicate IDs,
+unknown projects, malformed markers, and invalid input fail. Repeating a
+successful call is not idempotent; it fails as a duplicate.
+
+**Annotations:** `readOnlyHint: false`, `destructiveHint: false`,
+`openWorldHint: false`.
+
+### `link_task`
+
+**Caller:** executor. **Mutation:** one atomic identity transition.
+
+**Input:** `{ taskId: non-empty string, threadId: non-empty string }`.
+The workspace layer requires `threadId` to be a canonical Codex UUIDv7.
+
+**Structured output:** `{ task: Task }`.
+
+The eligible record MUST be link-pending, working, dispatcher-written, and have
+the exact marker. The thread ID MUST be unused. Success sets `threadId`,
+refreshes `updatedAt`, and sets `updatedBy: mcp`. An exact successful retry
+is idempotent. A different identity, terminal record, reused identity, missing
+marker, or ineligible state fails.
+
+**Annotations:** `readOnlyHint: false`, `destructiveHint: false`,
+`openWorldHint: false`.
+
+### `report_state`
+
+**Caller:** executor, or dispatcher only for native creation failure.
+**Mutation:** replaces the current state atomically and preserves `lastResult`.
+
+**Input:**
+
+| Field | Type and rule |
+| --- | --- |
+| `taskId` | Non-empty string. |
+| `threadId` | Matching non-empty ID for a linked task; null only for creation failure. |
+| `turnId` | Current canonical Codex UUIDv7 for a linked MCP journey; null only for creation failure. Maximum 256 characters at the MCP boundary. |
+| `status` | `working`, `needs_input`, `completed`, or `failed`. |
+| `summary` | Omitted or null for `working`; required non-empty string of at most 2,000 characters otherwise. |
+
+**Structured output:** `{ task: Task }`.
+
+For a linked self-linking journey, `working` MUST identify a turn newer than
+the current turn and last semantic result. A semantic state MUST match the
+current working turn. Repeating an identical state is idempotent; conflicting
+or older state fails. A null-identity record accepts only a fresh executor
+creation `failed` state with both IDs null. Success sets the current state and
+preserves the semantic state in `lastResult`; starting newer work does not erase
+that result.
+
+**Annotations:** `readOnlyHint: false`, `destructiveHint: true`,
+`openWorldHint: false`.
+
+### `report_result` (deprecated)
+
+`report_result` retains the prior semantic-only input shape and statuses as a
+temporary compatibility alias. It implicitly accepts a fresh supplied turn and
+stores its semantic result, including for supported schema-4 records and
+low-level opaque direct records. It does not accept `working`. New executor
+instructions MUST use `report_state`. Successful mutation upgrades schema 4 to
+schema 5; unsupported schemas remain rejected.
+
+## Reporting and dashboard
+
+A semantic result is cached evidence, not permanent live truth. Reports SHOULD
+use one bounded native metadata snapshot. Active or approval-waiting native
+state overrides cache. An inactive task does not prove completion. Focused
+reports MAY read a selected task once when metadata is newer or evidence is
+uncertain. Reports MUST NOT poll or classify assistant prose.
+
+The dashboard MUST bind only to loopback, validate the current workspace
+snapshot, and avoid sessions or shared client state. Direct thread navigation
+MUST require a canonical Codex UUIDv7. Otherwise it MAY open the revalidated
+configured project. Project paths from task history MUST be matched against
+current configuration before use.
+
+## Concurrency and trust
+
+All task and configuration writers MUST share one workspace lock. Duplicate ID,
+duplicate thread, link, and result freshness checks MUST occur while holding
+that lock. Atomic replacement MUST preserve valid unrelated records.
+
+TaskChef is designed for a local, single-user boundary. Executor self-linking is
+a cooperative assertion, not transport-authenticated proof. Task instructions,
+stored project snapshots, and dashboard requests are untrusted input.
+Implementations MUST validate exact shapes, canonical paths, safe IDs, markers,
+loopback origin, and current configuration before acting.
+
+TaskChef MUST NOT use lifecycle hooks, schedules, polling, recent-thread search,
+transcript search, title matching, hidden reasoning, or token usage to discover
+identity or infer semantic results.