## Seed Desk\: reservations on the active branch Mara wants the agent to help hold fictional packets while she works through a conversation\. Her obstacle is no longer retrieval\. It is stale decisions\: a reservation based on an old availability view must not silently overwrite a newer one\. She chooses **current\-branch reconstruction plus revision\-checked actions**\. This is still not a stock system\. Separate sessions and processes do not coordinate physical inventory\. ### Milestone\: a confirmed human reservation **Starting state\:** the stage\-3 fixture has eight basil packets\, five bean packets and three marigold packets\. Reservations are empty\. Agent actions are disabled\. Files\: - [Stage 3 entry]() - [Reservation domain and reconstruction]() - [Inventory]() - [Package manifest]() - [Tool description]() For a standalone download\, install the matching dependencies in this stage\. This is package\-manager work and may access your registry\. If those custom versions are unavailable\, use the matching installed source workspace instead\. **Terminal shell—dependency installation\, then launch\:** ~~~sh cd "$EXAMPLES/seed-desk/03-reservations" bun install cd "$LAB/work" omp --no-extensions --no-skills -e "$EXAMPLES/seed-desk/03-reservations/index.ts" --session "$LAB/seed-session.jsonl" ~~~ **Human OMP slash commands\:** ~~~text /seeds query /seeds reserve basil-genovese 2 ~~~ Cancel the first confirmation\. Then repeat the reservation command and confirm\. **Expected state after confirmation on a fresh branch\:** ~~~text basil-genovese: 6 available, 2 reserved ~~~ The query also supplies a revision\. Its concrete value comes from your session\, so it will not match a printed workbook token\. #### What changed in the code\? The domain separates\: - the immutable fictional fixture\; - a persisted snapshot containing `version`\, `agentEnabled` and reservation `quantities`\; - a derived revision\; - domain validation in `changeReservation()`\. A successful change appends a custom entry named `seed-desk-state-v1`\. It then reconstructs state\, refreshes the status and emits `workbook:seed-desk:changed`\. The extension does not write a separate inventory file\. #### Why the second revision check matters A confirmation dialog is an `await`\. During that wait\, another action or a session\-tree movement may occur\. **Exact excerpt—post\-dialog check in [stage 3’s entry]()\; read in its surrounding command handler\:** ~~~ts // Re-read after the dialog: another action or tree navigation may have happened. const current = reconstruct(ctx); if (current.revision !== initial.revision) throw new DeskRefusal("stale-revision", "The branch changed during confirmation; try again."); const snapshot: Snapshot = grant ? { version: 1, quantities: current.quantities, agentEnabled: value === "on" } : changeReservation(current, verb, value ?? "", Number(count), initial.revision, "human"); const saved = commit(ctx, snapshot, grant ? `agent-${value}` : verb); ~~~ After validation\, the commit path has no asynchronous gap before `appendEntry()`\. That prevents JavaScript invocations from interleaving inside this small validation\-and\-append segment\. It is not a cross\-process transaction or a durable database lock\. **Observed\:** cancellation appended no state entry\. A confirmation\-race scenario changed state while the dialog was open\; the waiting human reservation was then refused\, leaving bean reservations at zero\. **Exercise\:** reserve two basil packets\, then cancel a request to release one\. **Checkpoint\:** basil remains at two reserved\. Cancellation before commit is not a release\. ### Milestone\: grant the agent a bounded domain capability Mara now wants the agent to make fictional reservations without opening a dialog for every domain decision\. She does not want the tool to grant itself that authority\. **Human OMP slash command\:** ~~~text /seeds agent on ~~~ Confirm the scoped dialog\. The model\-facing interface is now `seed_desk`\. **Model tool arguments—call `seed_desk`\:** ~~~json {"op":"discover"} ~~~ ~~~json {"op":"query"} ~~~ ~~~json {"op":"inspect","id":"basil-genovese"} ~~~ The tool supports\: | Operation | Purpose | | --- | --- | | `discover` | Explain supported operations\, action prerequisites and the current state revision | | `query` | Return valid IDs\, available\/reserved quantities and a revision\; optionally filter by exact family | | `inspect` | Read one exact seed ID | | `act` | Reserve or release a positive integer quantity using the current revision and a human\-granted permission | The structured response includes `ok`\, `scope`\, and\, when available\, `revision`\, `agentEnabled`\, `code` and `data`\. The text response includes the domain outcome and revision\. Do not assume every field in `details`\, including permission status\, is automatically sent to the model\; a host exposing structured details has more information than ordinary text\-only model replay\. #### Ask the agent for the right sequence **Agent request—use in an authorized model session\:** ~~~text Use seed_desk to query current fictional availability. Choose bean-scarlet only if at least one packet is available. Reserve one packet using the exact revision returned by that query. If the operation is refused, explain the refusal and query again before deciding whether another action is appropriate. Do not retry blindly. ~~~ A model session requires your normal provider configuration and may incur charges\. The recorded example checks did not use provider inference\. For readers inspecting the schema\, this is the action shape\: **Illustrative model\-tool argument template—not usable until the revision is replaced with the actual latest returned value\:** ~~~json { "op": "act", "action": "reserve", "id": "bean-scarlet", "packets": 1, "expectedRevision": "COPY_THE_LATEST_RETURNED_REVISION" } ~~~ A successful action returns a new revision\. Reusing the old one is a refusal\, not a second reservation\. #### Refusals are part of the interface | Condition | Domain code | Correct next action | | --- | --- | --- | | No human grant | `agent-disabled` | Ask the human whether to enable the domain capability | | Old revision | `stale-revision` | Query again\; reconsider the intended action | | Invented ID | `invalid-target` | Use an ID from query results | | Zero\, negative or unsafe quantity | `invalid-quantity` | Supply a positive safe integer | | More than available | `insufficient-availability` | Reduce the quantity or choose another item | | Release exceeds this branch’s holding | `insufficient-reservation` | Inspect current reservations | | Incompatible or invalid persisted snapshot | `corrupt-state` | Stop and navigate to a valid earlier branch | | Human mutation without UI | `ui-required` | Use a supported interactive confirmation path | The schema can reject malformed inputs before the domain runs\. The domain also validates action\, quantity and target\. These are complementary checks\. Seed Desk returns ordinary domain refusals as `details.ok: false` with explanatory text\. It does not mark every such refusal as a thrown transport\/tool error\. An SDK caller must inspect `ok`\, not merely whether a promise resolved\. **Observed\:** the recorded checks covered disabled authority\, stale revision\, invalid target\, invalid quantity\, insufficient availability and excess release without appending state\. #### Host approval is a separate gate The mixed read\/write `seed_desk` tool is conservatively declared `approval: "write"` for all operations\. That host approval tier and Mara’s `/seeds agent on` grant are different\: - Host approval controls whether the wrapped tool call may execute under the configured approval policy\. - Seed Desk’s grant controls whether its own `act` operation may mutate this domain state\. - Neither prevents other extension JavaScript or independently permitted tools from acting elsewhere\. Do not weaken a host’s approval configuration merely to make a test pass\. ### Milestone\: reconstruct the branch\, not the whole file Mara tries a different plan from an earlier point in the conversation\. Her first instinct is to scan all saved entries and select the latest snapshot\. That would mix sibling branches\. Instead\, `reconstruct()` walks `ctx.sessionManager.getBranch()`\. Its revision is\: - session ID plus `root`\, before any Seed Desk state entry\; - session ID plus the latest Seed Desk state entry’s ID afterward\. Consequences\: - Ordinary conversation does not stale the domain revision\. - A reservation or permission change does\. - A sibling state snapshot cannot be reused as the current branch’s revision\. - A new session has a distinct identity\. - A branch inherits the reservations and grants in its ancestry\. The domain validates every matching stored snapshot it encounters\. It does not skip a corrupt Seed Desk entry and silently trust a later one\. #### Inspect the journal **Terminal shell—inspect only the lab’s Seed Desk state records\:** ~~~sh grep '"customType":"seed-desk-state-v1"' "$LAB/seed-session.jsonl" ~~~ This is a journal inspection\, not a request to edit the journal while OMP owns it\. Exit and reopen with the same launch command and session path\. Then query again\. **Observed\:** - Real JSONL entries survived reopen\. - The restored reservation was two packets\. - The revision was preserved\. - Rewinding before a reservation showed zero reserved\. - A sibling branch could hold one packet while the original branch retained two\. - A sibling revision token was rejected\. - A fresh session had no carried reservation and agent authority was off\. A plain leaf movement is not the same thing as a newly appended branch record\. The session loader reconstructs its position from journal structure\; do not assume every transient UI navigation choice is independently durable without a subsequent journal change\. Always query after reopen\. #### Revoke deliberately **Human OMP slash command\:** ~~~text /seeds agent off ~~~ This also asks for confirmation and appends a new snapshot\. Unlike Review Desk’s in\-memory revocation later\, **Seed Desk refuses both grant and revoke commands without UI**\. A persisted grant may therefore still permit tool acts after headless reopen\, subject to host approval\. That is the supplied stage’s exact policy\, not a general recommendation for all applications\. ### Persistence and cancellation limits `appendEntry()` stores extension state outside model\-visible conversation\. It returns no persistence receipt\. The current file session manager normally hands completed appends to the OS synchronously once persistence is materialized\, but it does not provide a power\-loss\/fsync guarantee through this extension API\. Storage failures can be latched and surfaced by the host\. The Seed Desk checks did not exercise disk\-failure recovery\. Before commit\, cancellation changes nothing\. After commit\, cancellation cannot undo a reservation\. Query before retrying\. Status notifications and bus events do not start an agent turn\. The optional `renderResult()` is presentation only\; it does not replace the result’s text and structured details\. **Exercise\:** should a real multi\-user seed library use this journal as its stock database\? **Answer\:** no\. It would need a shared authoritative store\, atomic stock operations\, durable request identity and coordination across users and processes\. This stage deliberately teaches fictional branch\-local reservations\. *Source\, snapshot 2026\-08\-29\: linked stage\-3 files\; `packages/coding-agent/src/session/session-manager.ts`\, `ReadonlySessionManager`\, `appendCustomEntry`\, `getBranch`\; `packages/coding-agent/src/tools/approval.ts`\, `resolveApproval`\.*