@sjawhar/pi-envoy 9.7.1 → 10.1.0

package/dist/skills/dispatch/SKILL.md

@@ -213,11 +213,11 @@ field, and choosing your next issue are in [Working an issue](skill://dispatch/r
 ## Asking
 
 Two kinds of question reach a human. A decision about the design a document records is a decision
-block in that document ([Decision blocks](#decision-blocks)), whatever phase the work is in and
-whether or not the document was approved: a block in an approved document makes the approval
-stale, which is right. A Legion phase worker sends such a decision to its architect, which writes
-the block (`skill://legion-worker`). A to-do or permission only a human can give, or a decision
-with no document to live in, is a `dispatch ask`. The gates below apply to both.
+block in that document ([Decision blocks](#decision-blocks)), at every phase, approved or not: a
+block in an approved document leaves the approval stale until the answer, which carries it
+forward when it is the whole change (below). A Legion phase worker sends it to its architect,
+which writes the block (`skill://legion-worker`). A to-do or permission only a human can give, or
+a decision with no document to live in, is a `dispatch ask`. The gates below apply to both.
 
 ### Before you ask
 
@@ -368,33 +368,33 @@ See [Following](#following) for why you receive what happens to asks you open an
 ## Approval of a spec
 
 Approval is a property of a document, not a question you phrase: a human approves a specific
-version, the way a pull-request review approves a commit, and any later version makes that
-approval stale. A later version also moves an open request to that version and leaves it waiting
-on you until you request again, which hands the same request back to the human. Answering a
-decision block writes a new version, so request approval only when all three hold: every decision
-block is settled, which means answered or waived as the next paragraph
-says; the human has agreed to every point in the spec; and the current version has not been
-approved. A Legion root spec under an armed design gate always goes to approval once all three
-hold (`skill://legion-architect`).
+version, the way a pull-request review approves a commit, and a later version leaves that approval
+stale, unless the human's own answer to a decision block is the whole change since the version
+they approved; then Dispatch records an `approved` review in their name at that version and emits
+`artifact.approved`, so request nothing. When the answer changes text outside its block, rewrite
+that text, run the fresh reader below on it and request again. A later version also moves an open
+request with it, waiting on you until you request again. Request only when all three hold: every
+decision block is settled (answered or waived, below); the human has agreed to every point in the
+spec; and the current version has not been approved. A Legion root spec under an armed design gate
+always goes to approval once all three hold (`skill://legion-architect`).
 
 Before calling `dispatch request-approval`, have a fresh read-only reader check the current spec
-against the code and the human's words, then resolve every finding. A Legion architect uses its
-`plan-gap-analyst`; another session uses the read-only reader its host supplies.
-
-When all three hold, request it in the pass that finishes the spec: a design waiting with nothing in
-the human's Inbox waits on nobody. When a human asks for approval while a block is open, do not
-request it and do not hold it silently: name each open block and ask them to answer it or waive
-it. For a waiver, close the block with `dispatch resolve-ask --kind resolved` (their words as
-`--reason`), then write their decision into the text in their words and request.
-`dispatch request-approval` refuses while any block is open.
+against the code and the human's words, then resolve every finding. A Legion architect uses
+`plan-gap-analyst`, another session the read-only reader its host supplies. When all three hold,
+request in the pass that finishes the spec: a design waiting with nothing in the human's Inbox
+waits on nobody. When a human asks for approval while a block is open, neither request it nor hold
+it silently: name each open block and ask them to answer or waive it. For a waiver, close it with
+`dispatch resolve-ask --kind resolved` (their words as `--reason`), write their decision into the
+text in their words and request. `dispatch request-approval` refuses while any block is open.
 
 An approval request carries nothing new: a point the human has not agreed to gets its own decision
 block first, with your recommendation, or, when it is a choice you can make yourself
 ([Before you ask](#before-you-ask), gate 1) and the human will not want a say in it, comes out of
 the spec and is made where the work happens; an inference you cannot defend in a decision block
 comes out of the spec. `--summary` says in one to three sentences what the human is approving and
-nothing else: no commentary on itself or on the conversation, and no open question. The Inbox
-shows it after "Approve spec.md (version N)?". Never write "Approve" options into an ordinary
+nothing else: no commentary on itself or on the conversation, and no open question; after an
+earlier approval, one sentence naming what changed since it, since the card shows that approval
+and its `Show diff` control carries the detail. Never write "Approve" options into an ordinary
 `dispatch ask`; only humans approve. The call, its result and its answer:
 [Approval requests](skill://dispatch/references/documents.md#approval-requests).
 

package/dist/skills/dispatch/references/api.md

@@ -6,9 +6,22 @@ commands do not cover.
 ## Agent authentication
 
 Use a personal Dispatch token: a human mints it in Dispatch **Settings → Agent tokens** and supplies
-it to the agent through `dispatch.token` in `~/.config/opencode/envoy.json` or `DISPATCH_TOKEN`.
-The server records the minting human as the owner of that session's writes. `DISPATCH_AGENT_TOKEN`
-is the shared devbox fallback; do not configure it for an individual agent.
+it to the agent through `DISPATCH_TOKEN` or `dispatch.token` in the `envoy.json` the agent's
+session reads. Under an Oh My Pi profile other than `default`, a Claude Code `CLAUDE_CONFIG_DIR` or
+an OpenCode `OPENCODE_CONFIG_DIR`, that is the `envoy.json` in the session's own directory; any
+other session reads the file `ENVOY_CONFIG_FILE` names when it is set, else
+`~/.config/legion/envoy.json` (under `$XDG_CONFIG_HOME` when set). The plugin hands the path it
+chose to the session's commands in `ENVOY_CONFIG_FILE` beside `DISPATCH_HOST`, and the `dispatch`
+command reads the file `ENVOY_CONFIG_FILE` names whenever `DISPATCH_HOST` is set, else its host
+plugin's rule; in a Claude Code Bash that lacks both, as a subagent's can,
+`CLAUDE_CODE_CHILD_SESSION=1` makes the host `claude`, so the command reads `CLAUDE_CONFIG_DIR`'s
+file. A `dispatch.token` written `!<command>` is a command whose output is the token. A checkout's
+`.envoy/envoy.json` may set `dispatch.serverUrl` only with the `dispatch.token` beside it, and
+`dispatch.token` only with its own `dispatch.serverUrl` beside it; an `envoy` section there is not
+read. The file's token goes only to its own `dispatch.serverUrl`: a
+`DISPATCH_URL` naming another server needs `DISPATCH_TOKEN` or `DISPATCH_TOKEN_FILE`. The server
+records the minting human as the owner of that session's writes.
+`DISPATCH_AGENT_TOKEN` is the shared devbox fallback; do not configure it for an individual agent.
 
 The deployed Dispatch server's browser origin is configured separately with
 `DISPATCH_SERVER_URL` in the deployment `compose/.env`. Do not change an

package/dist/skills/dispatch/references/documents.md

@@ -226,7 +226,27 @@ nothing, and a different `--summary` is refused, since it would rewrite the card
 reading. The answer reaches you as `artifact.approved` or `artifact.changes_requested` with the
 pinned `version` and closes the request, so the next call opens a new one; `changes_requested`
 carries the reason, which is your next piece of work. Those reads show the document's approval
-state; `stale` means it was approved and then edited.
+state; `stale` means it was approved and changed since, other than as the next paragraph says.
+
+A human's own answer to a decision block in a document they approved can carry the approval to
+the version it writes. Dispatch compares that version with the version they approved, every
+decision block cut out of both; when the text outside the blocks is the same and every block added or
+answered since has their answer, it records an `approved` review in their name pinned to the new version and
+emits `artifact.approved`, in the transaction that writes the version, and answers an approval
+request open on the document `Approve` in their name. The answer was the whole change since the
+version they approved, so request nothing: `dispatch doc-read` shows `Approval: approved vN` at
+the new version. An edit inside the block before the answer does not stop this. A change
+outside the blocks, whoever wrote it (an upload or a typed edit included), a block added since the
+approval that the human has not answered (open or waived), a block the approved version held that
+someone else answered or that was waived since, a decided block whose question or options were
+changed (its answer decided the question it was given on), a removed block, a request for changes
+newer than the approval, or a document they never approved leaves the approval stale, and the next
+request shows them the diff: a request on a document a human approved earlier carries
+`approved` (`{version, at, by}`) in `ask.approval`, and its Inbox card puts
+`Approved at version N on <date> by <who>.` and a `Show diff` control under the question, which
+shows what changed between the two versions with every decision block cut out. So that request's
+`--summary` is one sentence naming what changed since that approval, and repeats nothing the diff
+shows.
 
 ## A document that is reloading
 

package/dist/skills/dispatch/references/issues.md

@@ -107,7 +107,11 @@ Link the pull request that delivers the issue with `--external-link` when you op
 renders its state and checks from that link, and `dispatch read` lists it under `External links:`.
 The command is authenticated with the same bearer as every
 other `dispatch` command: a Legion pane reads it from the `DISPATCH_TOKEN_FILE` path the daemon sets on
-the pane; an OMP session outside Legion reads `dispatch.token` from `~/.config/opencode/envoy.json`.
+the pane; any other session's `dispatch` command reads `dispatch.token` from the `envoy.json` its
+host's plugin read, which the plugin hands it in `ENVOY_CONFIG_FILE`. By that plugin's rule, that
+is an OMP session's profile directory under an omp profile other than `default`, a Claude Code
+session's `CLAUDE_CONFIG_DIR` (its subagents' too) or an OpenCode session's `OPENCODE_CONFIG_DIR`,
+else the file `ENVOY_CONFIG_FILE` names, else `~/.config/legion/envoy.json`.
 
 A write to an issue still in `triage` answers once with `… is still in triage …`; move the status
 when work has started.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/pi-envoy",
-  "version": "9.7.1",
+  "version": "10.1.0",
   "license": "Apache-2.0",
   "type": "module",
   "omp": {