thurview 0.8.1 → 0.8.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thurview",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "description": "Guided, evidence-anchored reviews of agent-written code. A coding agent authors the review; you read, ask, comment and decide in the browser.",
   "license": "MIT",
   "type": "module",

package/skills/thurview/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: thurview
-description: Author and publish a thurview document - a guided, evidence-anchored explanation the reader opens in the browser, annotates, asks questions about, and approves or sends back. Two kinds: a review of a branch, pull request or commit range, and a code explainer of a whole codebase or one subsystem at a pinned commit. Use when the user asks to review a branch or PR, to explain or walk through a change, "review my branch against main", to explain how a codebase or subsystem works or where its design problems might be, or invokes /thurview. Not for a pass/fail bug hunt.
+description: Author and publish a thurview document - a guided, evidence-anchored explanation the reader opens in the browser, annotates, asks questions about, and approves or sends back. Two kinds — a review of a branch, pull request or commit range, and a code explainer of a whole codebase or one subsystem at a pinned commit. Use when the user asks to review a branch or PR, to explain or walk through a change, "review my branch against main", to explain how a codebase or subsystem works or where its design problems might be, or invokes /thurview. Not for a pass/fail bug hunt.
 user-invocable: true
 argument-hint: "[<pr-number|pr-url> | --base <ref> --head <ref> | explain [<path>]]"
 ---
@@ -249,7 +249,9 @@ Tell the user, in a few lines and nothing more:
 - which theme source you used: the user's request, the project's design
   system (name the files), or the default skin
 - when the review has no map, why not, in one clause
-- that you are now waiting for their questions and their decision
+- that you are now waiting for their questions and their decision, and that
+  a question asked after you stop waiting is queued rather than lost - the
+  page tells them which of the two it is
 
 The page explains its own controls; do not describe them.
 
@@ -265,9 +267,16 @@ nothing: keep `--timeout` under that limit and run `wait` again on `timeout`.
 When the tool can run a command in the background and wake you when it exits,
 run `wait` that way, so the user has the terminal back while they read.
 
+While `wait` runs the reader's page says an agent is listening, and says the
+opposite within seconds of it returning. Do not loop it to look present: a
+question asked with nobody waiting is queued, not lost, and `thurview`
+reports it as `needsAgent` the next time you run any command in the
+worktree.
+
 `wait.reason` says what happened, with the threads that need you:
 
-- `question`: an "Ask now" thread. Answer each thread in `threads` with
+- `question`: a thread the reader sent to you. Answer each thread in
+  `threads` with
   `thurview threads reply <threadId> --review <id> --body "<answer>"`. Do
   not change the document for a question. Wait again.
 - `awaiting-agent-updates`: the reader submitted with "Request changes".

package/skills/thurview/references/lifecycle.md

@@ -27,7 +27,7 @@ warns when the branch moved past them.
 | `accepted`               | Terminal. Cannot be republished.                         |
 | `closed`                 | Terminal. Ended without approval. Cannot be republished. |
 
-"Ask now" does not change the status. "Submit review" with "Request changes"
+Asking the agent a question does not change the status. "Submit review" with "Request changes"
 sets `awaiting-agent-updates`; with "Approve" sets `accepted`; with "Close"
 sets `closed`.
 
@@ -36,21 +36,62 @@ Dismissal is separate: the reader removes the review from the active list and
 
 ## Threads
 
-Two kinds, chosen by the reader when creating one:
+Two kinds, chosen by the reader when creating one. In the browser these are
+the two buttons on the comment box, one click each:
 
-- `ask` mode (a question): delivered at once. `wait` returns `question`.
-  Answer with `threads reply`. It stays open until the reader resolves it;
-  open questions never block a republish.
-- `review` mode (a comment): held as pending until the reader submits. Then
-  `wait` returns `awaiting-agent-updates` with the submitted threads.
+- `ask` mode (a question, "Send to the agent"): submitted on creation and
+  delivered at once. `wait` returns `question`. Answer with `threads reply`.
+  Open questions never block a republish.
+- `review` mode (a comment, "Add to the review"): held as pending until the
+  reader submits. Then `wait` returns `awaiting-agent-updates` with the
+  submitted threads.
 
 Targets: a document block (with an optional quoted selection), a file line
 on the base or head side, a map node, or the whole review.
 
+### Status, `submitted` and `needsAgent`
+
+Two flags and one derived predicate decide whether a thread reaches you.
+`needsAgent` is the whole queue: `wait` reports it, `threads list --open`
+counts it, and a thread outside it will not be delivered to anyone.
+
+```text
+needsAgent = status is open  AND  submitted  AND  the last message is the reader's
+```
+
+| Transition                     | status               | submitted     |
+| ------------------------------ | -------------------- | ------------- |
+| reader creates an `ask` thread | `open`               | `true`        |
+| reader creates a `review` one  | `open`               | `false`       |
+| reader submits the review      | unchanged            | `true` (all)  |
+| **reader writes in a thread**  | **forced to `open`** | `true` if ask |
+| agent replies                  | unchanged            | unchanged     |
+| `threads resolve` / Resolve    | `resolved`           | unchanged     |
+| Reopen                         | `open`               | unchanged     |
+
+A message from the reader always reopens the thread. It has to: a reply that
+left the thread resolved would sit at `needsAgent: false`, invisible to
+`wait` and to `threads list --open`, and the reader would be writing to
+nobody while the page still offered them a Reply button. Publishing a new
+revision never touches a thread's status.
+
 `publish` after the first revision requires zero open submitted comment
 threads. Resolve a thread only when its requested change is present. Do not
 rewrite or merge threads.
 
+### Presence: what the reader is told
+
+While `thurview wait` runs it writes a heartbeat to
+`${THURVIEW_HOME:-~/.thurview}/agents/<reviewId>.json`, and the browser reads
+it back as one of two sentences: an agent is listening now, or nothing is
+listening and what you send is queued until one checks in. Nothing else
+writes it, so presence is never inferred and never faked. A heartbeat older
+than 15 seconds is a dead `wait`, not an agent.
+
+That is why a question asked while you are away is not lost and does not need
+you to sit in `wait`: it is queued, `thurview` reports it as `needsAgent` the
+next time you run any command in the worktree, and you answer it then.
+
 ```sh
 thurview threads list --review <id> [--open]
 thurview threads get <threadId> --review <id>
@@ -64,6 +105,7 @@ thurview threads resolve <threadId> --review <id>
 ${THURVIEW_HOME:-~/.thurview}/
 ├── THURVIEW.md              user guidance (optional)
 ├── server.json              running server, if any
+├── agents/<id>.json         heartbeat of a running `wait`, removed when it ends
 └── reviews/<id>/
     ├── review.md            you edit
     ├── data.yaml            you edit
@@ -90,3 +132,8 @@ again.
 
 `thurview threads get <id>` truncates bodies over 1500 characters; pass
 `--full` when the hint says so.
+
+While `wait` runs, the reader's page says an agent is listening; when it
+returns, the page says the opposite within seconds. Do not leave `wait`
+running to look present when you are not going to answer, and do not loop it
+to keep a queue drained: the queue survives you, and the reader is told so.