@naswerks/engineering-loop 0.6.0 → 0.7.1

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
     {
       "name": "naswerks",
       "description": "The engineering loop: docs-* knowledge loop, spec-* execution loop, and init for a fresh repository.",
-      "version": "0.6.0",
+      "version": "0.7.1",
       "source": "./"
     }
   ]

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "naswerks",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "The engineering loop: a knowledge loop (docs-*) and an execution loop (spec-*) for repositories driven by hosted agent sessions, plus init to make a repository ready for both.",
   "author": { "name": "naswerks" },
   "license": "MIT",

package/CHANGELOG.md

@@ -5,6 +5,65 @@ version is the one in `package.json` and `.claude-plugin/plugin.json`, which mus
 
 ## [Unreleased]
 
+## [0.7.1] - 2026-10-04
+
+### Changed
+
+- `spec-coordinator` learns the control plane's verbs of 2026-10-04: `seat_spawn` defaults its host to the one
+  carrying the coordinator's own session and takes `model` and `effort` overrides; `accept_plan` and `accept`
+  take `answeringActId`, so one act rules and closes a question — and an act that names no question closes
+  none; the coordinator reads for itself what the owner used to check (`seat_timeline`, `needs_you`, argless
+  `seat_usage`, `seat_parks` with a charge's `seatId` or `all: true`, the roster's host and `re-raises`); it
+  commits its tracker itself, after each reap and never in a seat's commit call; and, hosted, `finish` is its
+  last call — the pipeline moves to `reviewing` and the PR's merge closes it.
+
+### Upgrading from 0.7.0
+
+Take the release (`claude plugin marketplace update engineering-loop`, then
+`claude plugin update naswerks@engineering-loop --scope <scope>`, and a new session). A patch: no loop text
+changed, nothing is restamped, and a hand-cranked repository's coordinator acts as before — every change but
+the tracker's commit discipline is the hosted plane's. A control plane older than 2026-10-04 refuses the new
+arguments and verbs by name.
+
+## [0.7.0] - 2026-10-01
+
+### Changed
+
+- **The hosted plane runs the hand-cranked ceremony: one file, two voices, a poke each way.** A seat writes
+  its `plan.md` and `tldr.md` with its own tools and posts each by `path` the first time — the control plane
+  reads the file from the seat's runner (periscope 1.4.0's `workspace_read`) — then with nothing. The
+  coordinator appends its ruling to the seat's `tldr.md` under its coordinator-voice heading and calls
+  `accept_plan`, `accept` or `callout` with a one-line summary; the control plane mirrors the file before it
+  records the act, and the seat is pointed at the section added. The act still decides. A runner older than
+  periscope 1.4.0 keeps the old form: the seat posts `content`, and the verb carries the coordinator's words.
+  `spec-seat`, `spec-coordinator` and `engineering-loop.md` § The blackboard say so.
+- `spec-coordinator`: `seat_acts` is the coordinator's census (its mint carries `acts:read`, and
+  `spec-retro` says so too); `read_blackboard` returns a window of a file or only the sections new since a
+  revision; `accept` carries the commit call, and an acceptance written into the seat's file binds to that
+  revision.
+- `spec-seat`: a search is data only as a quoted literal given to a read-only search tool, with no `$`, no
+  backtick, no interpreter and no `xargs` in the pipeline. On a periscope 1.4.0 runner the native reads
+  reach outside the workspace, credential material excepted; on an older one a file outside it is read with
+  a shell command.
+
+### Added
+
+- **`## [seat·…] ABOUT TO PARK`, the seat's third anchor:** the next call waits on a human, and here it is —
+  the verbatim command and what it waits on, posted before the call runs. Non-staling, like `HOLDING`.
+- Both skills: a control-plane verb that fails with a transport error (`ECONNRESET`) is called once more,
+  then disclosed; a refusal has a name and a dropped connection does not.
+
+### Upgrading from 0.6
+
+1. Take the release: `claude plugin marketplace update engineering-loop`, then
+   `claude plugin update naswerks@engineering-loop --scope <scope>`, and a new session.
+2. Re-copy the loop text of `references/engineering-loop.md` into `docs/_meta/engineering-loop.md` — § The
+   blackboard changed — keeping your repository-owned sections. Then `init refresh` restamps both copies; it
+   never touches loop text.
+3. A control plane that reads the seat anchors treats `## [seat·…] ABOUT TO PARK` as it treats
+   `## [seat·…] HOLDING` — a post-acceptance append that does not stale the acceptance. Until it does, the
+   append stales one.
+
 ## [0.6.0] - 2026-09-29
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naswerks/engineering-loop",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "The engineering loop as a Claude Code plugin: a knowledge loop (docs-*), an execution loop (spec-*), and init for a fresh repository. The package root is the plugin root.",
   "license": "MIT",
   "type": "module",

package/references/docs-workflow.md

@@ -1,4 +1,4 @@
-<!-- naswerks-loop: version=0.6.0 -->
+<!-- naswerks-loop: version=0.7.1 -->
 # Docs Workflow
 
 > How knowledge flows through `docs/`: the loop, the folder rules, the templates, and the `docs-*` skills.

package/references/engineering-loop.md

@@ -1,4 +1,4 @@
-<!-- naswerks-loop: version=0.6.0 -->
+<!-- naswerks-loop: version=0.7.1 -->
 # The Engineering Loop — flow, seats, skills, and the ceremony
 
 > The quick intro to how work gets built with this loop: the two loops (`docs-*` knowledge, `spec-*`
@@ -253,26 +253,31 @@ repo files, staged at close-out; the coordinator appends rulings with its own fi
 human's relay is a one-line nudge each way).
 
 <!-- control-plane-specific -->
-**Hosted — there is no folder tree the controller can read.** A seat **carries its bytes** to
-`post_plan` / `post_tldr` (verbs under `acts:write`, so a witness ticket structurally cannot post), and
-everything identifying is **server-derived** — pipeline and seat from the verified ticket, and **the rev**
-(newest + 1). *A rev nobody can misstate cannot regress by accident.* The append-only guard is what
-survives the transport: the ladder only climbs, a shorter file is refused, and the same rev with
-different bytes is refused — so the mirror **cannot be clobbered or rewound by a caller that lies, even
-though it can be fed.**
-
-**The coordinator's voice is NOT in the seat's file on the hosted plane.** A coordinator answers with
-`callout` (its sixth drive verb, machine-written, the only downward path), which persists on its own
-artifact lane and closes the question in the **acts ledger**. So **the file says whether a question was
-ASKED; the ledger says whether it was ANSWERED**, and a seat typing a coordinator-voice heading into its
-own TLDR closes nothing. `callout` **refuses when the charge has no live session** — a coordinator must
+**Hosted — the same files, read by the controller.** A seat edits its two files with its own tools and
+**pokes**: `post_plan` / `post_tldr` with the file's `path` inside its workspace the first time, then with
+nothing — the control plane reads the file from the seat's runner and mirrors it (verbs under `acts:write`,
+so a witness ticket structurally cannot post). A runner older than periscope 1.4.0 cannot be read; there the
+seat carries its bytes as `content`. Everything identifying is **server-derived** — pipeline and seat from
+the verified ticket, and **the rev** (newest + 1). *A rev nobody can misstate cannot regress by accident.*
+The append-only guard is what survives the transport: the ladder only climbs, a revision that drops a section
+is refused, and the same rev with different bytes is refused — so the mirror **cannot be clobbered or rewound
+by a caller that lies, even though it can be fed.**
+
+**The coordinator's voice is in the seat's file in both modes.** The coordinator appends its ruling to the
+seat's `tldr.md` under its coordinator-voice heading, then calls its verb (`accept_plan` · `accept` ·
+`callout`) with a one-line summary: the control plane mirrors the file as a revision in the coordinator's
+voice BEFORE it records the act, and the seat is pointed at the section added. **The file says what was
+said; the ledger says what was decided** — a question closes only on the coordinator's act, so a seat typing
+a coordinator-voice heading into its own TLDR closes nothing, and a revision in the coordinator's voice never
+counts as the seat asking. `callout` **refuses when the charge has no live session** — a coordinator must
 `seat_spawn` before it can rule — and reports **"RULING RECORDED, NOT DELIVERED"** in those words if the
-transport drops it.
+transport drops it. Where the coordinator cannot write the seat's file (a runner older than 1.4.0, a seat in
+its own workspace), the verb carries the words, as before.
 
-The coordinator-voice block (machinery-written hosted; the hand-cranked coordinator writes it —
-hand-cranked there is no rev counter, so the heading is `## COORDINATOR RULING (plan — {verdict})`; the
-stable grep prefix `## COORDINATOR RULING` is the contract in both modes, and an older board's
-`## PARENT RULING` is read as the same heading):
+The coordinator-voice block (the coordinator writes it in both modes; hand-cranked there is no rev counter,
+so the heading is `## COORDINATOR RULING (plan — {verdict})`; the stable grep prefix
+`## COORDINATOR RULING` is the contract in both modes, and an older board's `## PARENT RULING` is read as
+the same heading):
 
 ```
 ## COORDINATOR RULING (plan rev N — {accept | accept-with-riders | blocking-precondition})
@@ -286,19 +291,21 @@ Go build. Fold the riders in — no re-approval round-trip.
 
 Callouts and nudges append as `## COORDINATOR NOTE` (actor-suffixed when known, e.g. `(operator)`).
 
-**The seat's own two anchors:**
+**The seat's own three anchors:**
 
 ```
 ## [seat·{slug} · run {id}] CLOSE-OUT RECEIPT     <- after the push
 ## [seat·{slug} · run {id}] HOLDING              <- "I have pushed and I am waiting"
+## [seat·{slug} · run {id}] ABOUT TO PARK        <- "the next call waits on a human, and here it is"
 ```
 
-**A question heading, a HOLDING and a close-out receipt are ALL non-staling** — the gates bind an
-acceptance to the accepted CONTENT, not to the revision number, so appending your own *state* leaves it
-intact. Only **new content** stales. A seat that has pushed and is waiting is otherwise indistinguishable
+**A question heading, a HOLDING, an ABOUT TO PARK and a close-out receipt are ALL non-staling** — the gates
+bind an acceptance to the accepted CONTENT, not to the revision number, so appending your own *state* leaves
+it intact. Only **new content** stales. A seat that has pushed and is waiting is otherwise indistinguishable
 from a seat that has done nothing, and a coordinator reading a wake led by its own acceptance concludes
-there is nothing to rule — the HOLDING anchor is what prevents that. The token is the literal `seat·`
-whatever seat you are — it is a protocol anchor, not a description of you.
+there is nothing to rule — the HOLDING anchor is what prevents that, and ABOUT TO PARK does the same for a
+seat the gate is holding. The token is the literal `seat·` whatever seat you are — it is a protocol anchor,
+not a description of you.
 
 ### Questions ride the same blackboard
 

package/skills/spec-coordinator/SKILL.md

@@ -73,36 +73,56 @@ the tracker exists and cut Prompt #1. **Step 0 still applies.**
 ## Your hands
 
 **`read_blackboard` first, always** — argless it is your DAY-ONE SWEEP and your roster: every seat you
-decide for, its state, and its newest tldr rev. With a seat id it returns that seat's artifacts.
-Hand-cranked, your tools are normal file tools on the blackboard files plus the human relay.
+decide for, its state, and its newest tldr rev. With a seat id it returns that seat's tldr (or
+`kind: plan`): whole, a window of it (`offset`), or only the sections new since a revision (`sinceRev`) —
+read what changed, not the whole conversation again. In a shared workspace the seat's `tldr.md` is also a
+file you read with your own tools. Hand-cranked, your tools are normal file tools on the blackboard files
+plus the human relay.
 
 <!-- control-plane-specific -->
 **The five that reach a seat, and what each one actually is:**
 
 | Verb | What it does | The part that bites |
 |---|---|---|
-| `seat_spawn` | Opens a DECLARED sibling's session | **It can never CREATE a seat** — the topology is the create door's, decided by a human — and you may only drive seats you `supervises`/`reviews` |
-| `accept_plan` | The verdict act: `accept` · `accept-with-riders` · `blocking-precondition`, **and NOTHING ELSE carries a go** — and an accepting verdict DELIVERS ITSELF: the seat's live session receives a one-line pointer to the ruling (the body is a `ruling` artifact on your act, on its board) | Pass the workspace HEAD you observed (a backticked sha is fine); an accepting verdict whose seat planned against a different tree is REFUSED, naming both shas. READ THE REPLY'S `delivery:` LINE — `NOT DELIVERED` means the seat is idle and only a `callout` reaches it |
-| `accept` | The rev-bound FINAL receipt | It binds to the seat's CURRENT tldr revision, so if the seat posts again your acceptance no longer covers what it publishes. **Re-accept — it is idempotent and cheap.** This receipt is what the push bar reads; prose is not a receipt |
+| `seat_spawn` | Opens a DECLARED sibling's session | **It can never CREATE a seat** — the topology is the create door's, decided by a human — and you may only drive seats you `supervises`/`reviews`. With no `hostId` it opens on the host carrying your own session; `model` and `effort` override the seat's own for this session, judged against what the runner offers |
+| `accept_plan` | The verdict act: `accept` · `accept-with-riders` · `blocking-precondition`, **and NOTHING ELSE carries a go** — and it DELIVERS ITSELF: the seat's live session receives a one-line pointer to the ruling, for an accepting verdict and for any verdict that filed a ruling in the seat's file | Write the ruling into the seat's `tldr.md` FIRST (`## COORDINATOR RULING (plan rev N — {verdict})`), then call with a one-line `ruling`: the file is mirrored before your act and the pointer names your section. Pass the workspace HEAD you observed (a backticked sha is fine); an accepting verdict whose seat planned against a different tree is REFUSED, naming both shas. READ THE REPLY'S `delivery:` and `file:` LINES — `NOT DELIVERED` means the seat is idle and only a `callout` reaches it. When the verdict also answers the seat's question, pass `answeringActId` — one act rules and closes it |
+| `accept` | The rev-bound FINAL receipt — and it TELLS the seat, so it carries your commit call | Put the next instruction (commit, push, close-out) in `ruling`, or write it under `## COORDINATOR ACCEPT` in the seat's `tldr.md` first — the receipt then binds to that mirrored revision. It binds to the seat's CURRENT tldr revision, so if the seat posts NEW CONTENT again your acceptance no longer covers what it publishes. **Re-accept — it is idempotent and cheap.** This receipt is what the push bar reads; prose is not a receipt. `answeringActId` closes the question it answers, as on `accept_plan` |
 | `complete` | The reap, and it is HONEST | It re-reads the seat and reports ok only after the terminal state is OBSERVED |
-| `callout` | **THE ONLY WAY YOU REACH A CHARGE** (besides the pointer an accepting `accept_plan` sends) | A charge that posted and ended its turn cannot resume any other way — without this verb it waits for a human. Your ruling must carry a DETERMINATE NEXT ACTION it can execute without inference. KEEP IT TO A LINE: over 600 chars the body is stored as a `ruling` artifact on the board and the seat receives a POINTER — the seat reads the body once, from the board, never twice |
+| `callout` | **THE ONLY WAY YOU REACH A CHARGE** (besides the pointers `accept_plan` and `accept` send) | A charge that posted and ended its turn cannot resume any other way — without this verb it waits for a human. Your ruling must carry a DETERMINATE NEXT ACTION it can execute without inference. **Write it into the seat's `tldr.md` first and pass a one-line `ruling`:** the file is mirrored before your act and the seat is pointed at your section. Without a file, KEEP IT TO A LINE: over 600 chars the body is stored as a `ruling` artifact on the board and the seat receives a POINTER — the seat reads the body once, never twice |
 
-**A QUESTION IS CLOSED BY AN ACT, NOT BY A FILE.** Answer a charge's question with a `callout` carrying
-that post's act id as `answeringActId` — **that act IS the answer**, and it is the only thing that stops
-the re-raise. A `callout` without one steers and closes nothing, and **nothing you write into a file
+**A QUESTION IS CLOSED BY AN ACT, NOT BY A FILE.** Answer a charge's question with a `callout` — or an
+`accept_plan` / `accept` that rules at the same time — carrying that post's act id as `answeringActId`:
+**that act IS the answer**, and it is the only thing that stops the re-raise. An act without one steers or
+rules and closes nothing — a forgotten id costs one re-raise — and **nothing you write into a file
 closes anything**: the latch reads the ledger, so a ruling you never sent is a question still open no
 matter what any blackboard says.
 
-**`seat_acts` IS NOT YOURS, and that is deliberate.** Your mint is `seat:read` · `pipeline:read` ·
-`drive:write` — the coordinator kind was the last one without `acts:read`, and granting it would have
-made that scope universal. **So do not plan a day-one argless act sweep you cannot run**; your sweep is
-`read_blackboard`, and any count you publish names the lane that produced it. The retro seat DOES carry
-`acts:read` — the sweep is its instrument, not yours.
+**THE COORDINATOR'S APPEND, HOSTED.** In a shared workspace a seat that posts its `tldr.md` by `path` shares
+the file with you: append your ruling with your own file tools under a coordinator-voice heading, then call
+the verb. The control plane reads the file, mirrors it as the next revision in YOUR voice before it records
+your act, and points the seat at the section you added; the reply's `file:` line says what was mirrored. A
+seat that posts bytes (a runner older than periscope 1.4.0) or works in its own workspace keeps the old form:
+the verb carries your words. **The act still decides** — a section closes nothing on its own.
+
+**`seat_acts` IS YOUR CENSUS.** Your mint carries `acts:read`: take counts, human touches and receipts from
+the ledger, never from a seat's report about itself, and name the lane any count you publish came from.
+Beside it, read for yourself what the owner used to check for you: `seat_timeline` (a seat's two lanes —
+*the reap ended the process* is the runner's `ended` row, cause `stop_requested`, after your reap act),
+`needs_you` (the owner's Needs-you tab, Active and History), argless `seat_usage` (every seat's spend and
+the pipeline's total), `seat_parks` with a charge's `seatId` or `all: true` (its parks, and the rows that
+ADMITTED a push), and the argless roster's host and `re-raises` per seat.
 
 **WAKES:** you are woken when a charge posts its plan or its tldr, and a one-line pointer rides the wake —
-read the board and answer on first receipt rather than spending a round-trip.
+the revision and the sections it added. Read what is new (`read_blackboard` with `sinceRev`, or the file) and
+answer on first receipt rather than spending a round-trip.
 
-**THE TRACKER IS YOURS ALONE.** Advance it at every seat boundary; never reconstruct it at the close.
+**A verb that fails with a transport error** (`ECONNRESET`, a socket closed under the call) is the transport,
+not a refusal: call it once more, and journal it if it fails again. A refusal has a name; a dropped
+connection does not.
+
+**THE TRACKER IS YOURS ALONE.** Advance it at every seat boundary and **commit it yourself — after each
+reap, before the next spawn — never in a seat's commit call**, so it is never frozen between an acceptance
+and a seat's close-out. Never reconstruct it at the close.
 
 ## The loop (per seat)
 
@@ -329,6 +349,12 @@ read the board and answer on first receipt rather than spending a round-trip.
       is not reversible by the seat that does it, and a check the human runs afterwards confirms the damage
       instead of preventing it. **A live-check row is confirmation; this is prevention.** Never hold the
       run waiting for a human to verify this first — you have the list, so you are the gate.
+   8. **Hosted, `finish` is your last call** — once every other seat, P included, is reaped. Pass the PR's
+      URL: it records the pipeline done with evidence it reads from the ledger, moves it to `reviewing`,
+      closes your own session and ends your process, and the PR's merge closes the pipeline. **Nothing you
+      send after it is admitted** — commit your tracker and report first. It refuses, recording nothing,
+      while any seat is still live or when none shipped. Hand-cranked there is no `finish`; the human closes
+      the effort.
 
 **The human hand-tests.** Live verification is the human's role, not a seat's claim — when a slice
 ships something clickable, tell the human concretely what to drive (the 2-3 highest-value clicks), and
@@ -342,10 +368,9 @@ so read them as run-time obligations, not close-out ones:
 
 - **Your zero-touch / ceremony claims must cite an ARGLESS sweep**, never a verb list you picked
   yourself. **Check on day one that the sweep is runnable at your run's scale — and that it is runnable
-  BY SOMEONE.** Hosted, your ticket carries no `acts:read`, so the argless act sweep is not yours; your
-  day-one check is whether the retro seat, a witness or an operator can produce it. If none can, that is
-  a day-one escalation, not a close-out discovery — a verb-filtered audit can only confirm what you
-  suspected.
+  BY SOMEONE.** Hosted, `seat_acts` is that sweep and your ticket carries it; hand-cranked, check that the
+  retro seat, a witness or an operator can produce it. If none can, that is a day-one escalation, not a
+  close-out discovery — a verb-filtered audit can only confirm what you suspected.
 - **A rev-bound acceptance goes stale on a post-acceptance append of NEW CONTENT — from either actor.**
   The receipt covers the tldr rev + HEAD it was written against; a later content post invalidates it and
   the cheap repair is an **argless re-accept sent WITH the retry order in the same act**. A re-accept with
@@ -541,8 +566,9 @@ still open, however good the prose; the seat is still holding and the re-raise i
 **The blackboard append.** Hand-cranked, the seat's `plan.md` and `tldr.md` are live FILES at
 `docs/research/{topic}/sessions/{spec-slug}/` — read the TLDR there with normal file tools instead of
 asking for a paste (`read-full-plan` = read `plan.md`, a pull, never force-fed). Deliver every ruling by
-**APPENDING it verbatim to the seat's `tldr.md`**, right under the questions it answers. Hosted, your
-verbs ARE the appends and the machinery writes them for you.
+**APPENDING it verbatim to the seat's `tldr.md`**, right under the questions it answers. Hosted, the same
+append, then the verb: the control plane mirrors the file before your act and points the seat at the
+section (§ Your hands, the coordinator's append).
 
 **Anchor grammar (canonical — the witness greps these):** rulings land under
 `## COORDINATOR RULING (plan — {verdict})` hand-cranked, `## COORDINATOR RULING (plan rev N — {verdict})`

package/skills/spec-retro/SKILL.md

@@ -45,12 +45,10 @@ human and exception rows included. **Start every audit with it: "what happened t
 not ask about."** A verb-filtered read can only confirm suspicions, never surface surprises — a run can
 certify itself "zero-touch" while `approved_by_human` rows sit one unqueried verb away.
 
-**Who holds the instrument, on the hosted plane:** a `retro` seat's ticket carries `acts:read`, so
-`seat_acts` argless IS your sweep. A `coordinator` ticket deliberately does **not** carry it — its mint is
-`seat:read` · `pipeline:read` · `drive:write` — so a coordinator writing this retro from its own seat
-reads `read_blackboard` (argless = the roster) and takes the act sweep from the retro seat, the
-effort's witness, or a credentialed operator. **Say which instrument produced every count in this
-document** — a number whose lane you cannot name is testimony, not an audit.
+**Who holds the instrument, on the hosted plane:** a `retro` seat's ticket and a `coordinator` ticket both
+carry `acts:read`, so `seat_acts` argless IS your sweep whichever of the two writes this retro. **Say which
+instrument produced every count in this document** — a number whose lane you cannot name is testimony, not
+an audit.
 
 **If the argless sweep is not runnable at your run's scale, that is a day-one escalation, not a
 close-out discovery.** A few thousand rows can exceed the lane's page budget; you cannot retroactively

package/skills/spec-seat/SKILL.md

@@ -98,16 +98,26 @@ that is your scope — do not widen it on the theory that more reading is safer.
 `plan.md` (the full plan document) and `tldr.md` (the chat: your PLAN TLDR, any mid-build updates, the
 FINAL TLDR — **append, never overwrite**) are FILES, not just chat text.
 
+**ONE CEREMONY IN BOTH MODES: you write your file, then you poke; your coordinator appends its ruling to the
+SAME file, then pokes you. Nobody pastes a document into a message.**
+
 - **Hand-cranked:** create them under `docs/research/{topic}/sessions/{slug}/` at plan time and end your
   turn announcing the path. The coordinator reads `tldr.md` with normal file tools and APPENDS its ruling
   under `## COORDINATOR RULING`, so read the answer in your own file and proceed. The full plan is PULL — it is
   read only on a read-full-plan verdict; never paste it into chat. (If your harness has a plan-approval
   mode that forbids writes: give the chat summary, get the human's approve, THEN post and stop.)
-- **Hosted (a seat inside a pipeline):** the same two files are yours to edit with normal file tools, then
-  call **`post_plan` / `post_tldr` with the file's whole text as `content`** — the control plane runs on
-  another machine and cannot read your file. It records a revision and wakes your coordinator with ONE
-  LINE naming the act and the rev; the coordinator reads your file from the board; nothing you wrote is
-  pasted into its context (the pointer protocol).
+- **Hosted (a seat inside a pipeline):** the same two files are yours to edit with normal file tools. **Write,
+  then poke:** the first time, call `post_tldr` with `path` — the file's path inside your workspace, relative
+  to its root — and the control plane reads the file from your runner; after that, call `post_tldr` with
+  NOTHING and it reads the same path again (`post_plan` the same way). It records a revision and wakes your
+  coordinator with ONE LINE naming the rev and the sections you added. **Your coordinator's ruling arrives
+  IN YOUR FILE** — it appends under its coordinator-voice heading, and you are poked with one line naming
+  the section (*"Your tldr.md rev 5 adds `## COORDINATOR RULING (plan rev 1 — accept)`"*). Read it with
+  your own file tools; it is never pasted to you.
+  **If the post answers `host-lacks-workspace-read`** (a runner older than periscope 1.4.0) **or asks for
+  `content`** (a control plane that predates reading files), it cannot read your workspace: pass the whole
+  file as `content` instead, and read rulings from your board (`seat_content(kind: "ruling")`) as well as
+  your file.
   **THE FILE IS THE RECORD AND THE ROW MIRRORS IT** — one artifact row per rev carrying the whole file
   verbatim, so the two voices stay interleaved because nothing splits them. The control plane refuses
   `blackboard-rev-regressed` · `blackboard-shrank` · `blackboard-rev-content-mismatch` at the door: **an
@@ -194,9 +204,10 @@ question tool — the relay cannot copy it.
 **An unanswered question re-raises to your coordinator on a cooldown** until a ruling lands. Asking costs
 the pipeline a round-trip and nothing else.
 
-**WHAT ACTUALLY CLOSES A QUESTION.** On the hosted plane **nothing you write into a FILE closes anything.**
-The latch reads the ACTS LEDGER: a ruling closes your question only when it is delivered as a `callout`
-carrying your post's act id as `answeringActId`. A `callout` without one steers you and closes nothing.
+**WHAT ACTUALLY CLOSES A QUESTION.** On the hosted plane **nothing written into a FILE closes anything** —
+not yours, and not your coordinator's section in it. The latch reads the ACTS LEDGER: a ruling closes your
+question only when the coordinator's act carries your post's act id as `answeringActId`. The words arrive in
+your file; the act is what decides. A `callout` without one steers you and closes nothing.
 **The reason is a security property, not tidiness:** `tldr.md` is written BY YOU, so a file-side close
 predicate is a string the audited party can type — a seat could write `## COORDINATOR RULING` into its own file
 and switch off the very re-raise that exists to stop it waiting forever. The question is therefore split
@@ -250,6 +261,9 @@ Ask what the park is protecting:
   the platform's turn, not your failure; routing around it hides the defect the park is surfacing.
 - **A park on a boundary command** (push to the base branch, force-push, branch delete — or a command
   whose *text* merely tripped the scanner) — **never re-request; reshape the command.**
+  **A search is data only in one shape:** a quoted literal pattern given to a read-only search tool (`rg`,
+  `grep`, `git grep`, `Select-String`, `findstr`), with no `$`, no backtick, no interpreter and no `xargs`
+  in the pipeline. Any other command carrying boundary words parks — search for the symbol, not the verb.
   **THE SCANNER MATCHES TEXT, NOT PARSED VERBS, AND THIS IS THE MOST-PAID FENCE IN THE CEREMONY.** It
   fires on read-only commands a careful seat runs to PROVE its work: an `echo` label reading
   `=== remote tip ===` on a `git status`/`git log` block, or `git branch -r --contains <sha>` — a branch
@@ -266,6 +280,16 @@ Ask what the park is protecting:
 The test: is the park **blocking your work** (re-request + disclose), **guarding the boundary** (reshape),
 or **a wall** (reshape or escalate — never a click)?
 
+**BEFORE A CALL YOU KNOW WILL PARK, SAY SO.** When your work needs a boundary command — a lane that tests the
+park, a push your coordinator called for from a state the push bar cannot see — append
+
+```
+## [seat·{slug} · run {id}] ABOUT TO PARK
+```
+
+with the verbatim command and what it waits on, post, then run it. A seat held by the gate without saying so
+looks idle to everyone watching. Like `HOLDING`, it is a state report, and it does not stale your acceptance.
+
 **EVERY park is DISCLOSED in your next TLDR — including one you resolved yourself in seconds:** the
 verbatim command AND the verbatim park text. A self-resolved park looks like nothing happened and leaves
 the coordinator no signal, so the gate's false-park rate is only ever knowable from the seat that paid it.
@@ -379,7 +403,9 @@ doorbell with no follow-through**; if you receive one bare, retry anyway and say
   parks where the same three commands, sent one at a time, flow unattended. Keep the word "push" out of
   echo text — the deny layer matches text, not parsed verbs.
 - Prefer native read/glob/grep tools for reads; a shell read flows with its row like any other
-  non-boundary call.
+  non-boundary call. On a periscope 1.4.0 runner they reach anything outside your workspace except
+  credential material; on an older runner Read is jailed to your workspace, so read a file outside it —
+  the runner's installed package, say — with a shell command.
 - **Codegen only through the command `patterns/codegen.md` § Running codegen names** (when the repo has
   one) — never hand-write a generated folder.
 - **Never improvise a qualifying path in.** If a push parks and the remedy you can think of is touching a
@@ -449,9 +475,10 @@ ANCHOR, not a description of you.** A descriptive tail after the marker IS
 blessed (`… CLOSE-OUT RECEIPT — addendum: the six staged, tree clean`) — an end-anchored pattern on the
 one heading seats are told to write would be a trap that fires on ordinary prose.
 
-**Any post-accept append that is NOT one of these four — close-out receipt, HOLDING, a question heading, or
-your coordinator's own voice — needs the argless re-accept.** The bar is content, not revision: it asks *is
-what you are publishing still what I approved?*, and a state report is not a change of work.
+**Any post-accept append that is NOT one of these five — close-out receipt, HOLDING, ABOUT TO PARK, a
+question heading, or your coordinator's own voice — needs the argless re-accept.** The bar is content, not
+revision: it asks *is what you are publishing still what I approved?*, and a state report is not a change of
+work.
 
 **FILE YOUR SESSION ARTIFACTS:** copy your final `plan.md` and `tldr.md` into
 `docs/research/{topic}/sessions/{slug}/`. **Two files — that is the whole filing step.** Questions ride the
@@ -524,5 +551,8 @@ plane. The publish receipt is written at your turn's STOP and is structurally un
   with a clean rerun builds trust, an undisclosed one destroys it.
 - **A rule recalled from context needs re-reading at the source before it is used to refuse work.** A
   rule already corrected on disk is the commonest thing a seat blocks itself on.
+- **A control-plane verb that fails with a transport error** (`ECONNRESET`, a socket closed under the call)
+  is the transport, not a refusal: call it once more. If it fails again, say so in your next TLDR and carry
+  on with work that does not need it. A refusal has a name; a dropped connection does not.
 - Your job skill is next: `spec-build` (build/fixit) · `spec-review` (the outside look) ·
   `docs-process` (compile the living docs). Counterpart: `spec-coordinator` (the seat that arms you).