hitloop 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ClickerMonkey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,219 @@
-# Temporary Holding Version
+# hitl — Human In The Loop
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**hitl** is where an AI agent and its human meet. The agent **asks** you questions, **shows** you things, asks you to
+**review** its work, and waits at a **gate** for your OK. You answer, review, mark up pictures and browse the project's
+files, on your phone or your computer. Everything you say lands in one feed the agent reads a little at a time.
+
+The npm package is **`hitloop`**; once installed (`npm i -g hitloop`) the command is `hitl`.
+
+```sh
+npx hitloop init     # once per project: the .hitl folder, the MCP server for Claude Code, a note in CLAUDE.md
+npx hitloop          # the page, for every project, with links for your phone
+```
+
+**Site: https://clickermonkey.github.io/hitl/** (the commands, and a Claude skill to copy or download).
+
+| | | | |
+|:-:|:-:|:-:|:-:|
+| ![The inbox: an approval waiting, a review, questions](docs/screens/phone-inbox.jpg) | ![A review: a line comment and the agent's reply](docs/screens/phone-review.jpg) | ![Before and after: a slider over two screenshots](docs/screens/phone-compare.jpg) | ![An approval: Refuse, Not yet, Approve](docs/screens/phone-approve.jpg) |
+| **Inbox** | **Review** | **Before / after** | **Approve** |
+
+"Human in the loop" means a person stays part of what an automated system does: it checks with them, they decide,
+and it carries on. hitl gives that person somewhere to do it, instead of a chat scrolling past.
+
+It grew from two smaller tools, and does everything both did:
+
+- [questionme](https://github.com/ClickerMonkey/questionme): an agent's questions, answered on your phone.
+- [folderview](https://github.com/ClickerMonkey/folderview): browse, search and comment on any folder, with git.
+
+## What you can do
+
+| | |
+|---|---|
+| **Inbox** | Everything waiting on you across every project, most urgent first: approvals (an agent is waiting), blocking questions, reviews, things to look at. What's done folds away. |
+| **Answer questions** | Dozens at a time, with recommendations, why each one matters, and pictures, diffs and mockups to decide from. Take the recommendations and change the few you disagree with. Text answers grow and wrap as you type. |
+| **Review** | Each thing the agent shows you gets **Looks good**, **Needs changes** or **No**. Comment on a line (tap its number; tap another for a range), on selected text, or on an **area of a picture** you draw around. Attach photos. Finish with **Approve** or **Request changes**. |
+| **One at a time** | Swipe through a review: right for looks good, left for needs changes. Good for thirty screenshots. |
+| **Before and after** | Pictures with a slider (or side by side); code and text as after, before, and the changes between them. |
+| **Approve** | An agent asks "Deploy 2.4.0 to production?" and waits. You get a notification, read what it will do, and tap **Approve** or **Refuse**. |
+| **Browse the files** | Everything folderview does: highlighted code, rendered markdown with Mermaid and math, images, CSV, JSON, notebooks, git status, diffs and history, search, downloads. Big files and big folders open quickly. |
+| **Notes for the agent** | Write on any file, line or picture area, or about anything, with photos from your phone. The agent picks them up and resolves each with a reply. |
+| **Decisions** | Everything you answered, approved or gave a verdict on, searchable. Agents check it before asking again. |
+| **Who's asking** | Each request says which agent session or branch made it. |
+| **Notifications** | Your phone buzzes when an agent asks, shows or waits (ntfy or a webhook). Approvals go out at once. |
+
+It works on phones (sections along the bottom, big touch targets, the page scrolls), tablets and desktops (the file
+tree, the folder and the file side by side).
+
+## For agents
+
+`npx hitloop init` adds the MCP server to Claude Code (`claude mcp add --scope user hitl -- npx -y hitloop@latest mcp`) and
+a short section to the project's `CLAUDE.md` (or `AGENTS.md`) on when to use it.
+
+### MCP tools
+
+| Tool | |
+|---|---|
+| `news` | Everything the human said since you last read, across every question set, review and note, one line each. Start here. |
+| `wait` | Block until the human says something (`any`), finishes (`done`), answers everything (`all`), or answers the blocking questions. Up to 15 minutes; for longer, run `npx hitloop wait` in the background. |
+| `show` | Put files, code, text, diffs, pictures, diagrams, mockups or links in front of the human. `mode: "review"` asks a verdict per item; `"show"` is just to look. Each call makes its own review. |
+| `approve` | Ask yes or no before doing something, and wait for it. Returns APPROVED, REFUSED or "not yet" with their note. |
+| `add_questions` | Questions in a set (questionme's format): options, a recommendation, why it matters, follow-ups that open on an answer. |
+| `get_feedback`, `get_answers`, `notes` | One review's feedback, one set's answers, the notes. |
+| `ack`, `resolve`, `reply` | Mark answers and verdicts as dealt with, resolve comments and notes saying what you did, write back. |
+| `decisions` | What the human decided before. |
+| `status`, `get_link` | What's open; the links to send. |
+| `update_item`, `remove_items`, `update_review`, `update_question`, `remove_questions`, `update_set`, `update_section`, `show_set` | Change things. |
+
+### The CLI does the same
+
+```sh
+npx hitloop news                                  # what's new (marks it read; --peek doesn't)
+npx hitloop wait --any                            # exit once the human says something, printing it
+npx hitloop wait --done <review>                  # exit once they've finished a review (or answered an approval)
+npx hitloop show src/login.ts screens/*.png --title "Login, round 2"     # a review of files
+git diff | npx hitloop show - --title "The change"                      # stdin: a diff, code or text
+npx hitloop approve "Deploy 2.4.0?" --details "Restarts the API" --timeout 30m && ./deploy.sh
+npx hitloop ask <set> --file questions.json       # questions (or write .hitl/questions/<set>.json)
+npx hitloop feedback <review>    npx hitloop answers <set> --new    npx hitloop notes --open
+npx hitloop ack <set|review> <id…> --note "Done in src/x.ts"
+npx hitloop resolve [<review>] <id…> --note "Fixed: …"
+npx hitloop reply <review> c12 "Because the API bills per call."
+npx hitloop decisions auth                        # what was decided about auth
+npx hitloop status                                # every request, with counts
+```
+
+`hitl approve` exits 0 when approved, 1 when refused (or changes are asked for), 2 when there's no answer yet, so a
+script can stop at a real yes or no.
+
+`npx hitloop --help` lists every command and option; a mistyped option is refused rather than ignored.
+
+### Claude Code hooks (optional)
+
+Off unless you turn them on, per project (`hitl hooks on`, `hitl hooks on --stop`, or Settings on the page):
+
+- **News**: whenever you send Claude a message, it's told if you've said something in hitl it hasn't read.
+- **Stop**: Claude can't finish while an approval or a blocking question is waiting, or while there's news it
+  hasn't read. (It only holds Claude once, so it can't loop.)
+
+## Where things live
+
+```
+<project>/.hitl/
+  questions/<id>.json     question sets                        the agent writes
+  reviews/<id>.json       reviews, showings and approvals      the agent writes
+  answers/<id>.json, .md  what you said about each one         hitl writes
+  notes/notes.json, NOTES.md, images/, photos/                 hitl writes
+  media/                  pictures passed as data, snapshots of shown files, marked-up pictures, photos
+  config.json             optional: exclude, hide, showSecrets, maxFileMb, git, watch for this project
+```
+
+Every request is its own file, and a new review always gets a fresh id, so one agent's request never replaces
+another's. Every write is locked and atomic, so the page, the MCP server and the CLI can all write at once.
+Formats: `npx hitloop schema questions`, `npx hitloop schema reviews` (or `schema/` in the package).
+
+`npx hitloop import` brings in a project's `.questionme/` (questions and answers) and `.review/` (folderview's comments,
+as notes).
+
+### A review
+
+```json
+{
+  "title": "Login screen, round 2",
+  "intro": "I moved the button and fixed the spacing. **The error text** is the part I'm least sure of.",
+  "mode": "review",
+  "from": "Claude · branch login-v2",
+  "items": [
+    { "file": "src/login.tsx", "note": "The form", "ask": "Is the error text clear?" },
+    { "file": "src/api.ts", "against": "main", "title": "What changed in the API" },
+    { "image": "screens/login.png", "before": "screens/login-old.png" },
+    { "code": "{ \"retries\": 3 }", "before": "{}", "lang": "json", "name": "config.json" },
+    { "diff": "--- a/x\n+++ b/x\n@@ …" },
+    { "md": "## Left out\n- Password reset" },
+    { "mermaid": "flowchart LR\n A --> B" },
+    { "html": "<button>Sign in</button>", "height": 120 },
+    { "link": "https://example.com/preview" }
+  ]
+}
+```
+
+A `file` item keeps a copy of the file as it was shown; if it changes later, the page says so and shows what changed.
+
+## One server for every project
+
+`npx hitloop` starts one shared server (the hub) on port 4199 for every project you've used it in, so your phone needs
+one bookmark. The MCP server starts it in the background when an agent needs a link.
+
+```sh
+npx hitloop                       # the hub (adds this folder); prints the links
+npx hitloop url [review|set]      # the links (starts the hub if needed)
+npx hitloop stop                  # stop the hub
+npx hitloop projects              # what it serves;  --forget <folder> to drop one
+npx hitloop --solo [folder]       # just this folder, on its own server
+```
+
+| Option | Environment | Default | |
+|---|---|---|---|
+| `-p, --port <n>` | `HITL_PORT` | `4199` | The port to try first; the next free one is used. |
+| `-H, --host <addr>` | `HITL_HOST` | `0.0.0.0` | Where to listen. The default lets your phone reach it. |
+| `--base <path>` | `HITL_BASE` | `/` | Serve under a URL path (behind a proxy). |
+| `--local` | | | Only this computer (`127.0.0.1`), no token. |
+| `--token <t>` | `HITL_TOKEN` | made once | Open a link with `?token=…` once on each device; it's kept as a cookie. |
+| `--no-token` | | | Anyone on your network can open it. |
+| `--allow-host <h>` | | | Accept this host name too (a tunnel's). |
+| `-x, --exclude <globs>` | | | Never show, serve, search or zip these. Also `.hitlignore` in a project. |
+| `--hide <names>`, `--show-secrets`, `--max-file-mb <n>`, `--no-git`, `--no-watch`, `--author <name>` | | | File browsing, as in folderview. |
+| `-o, --open` | | | Open it in your browser. |
+| `--read-only` | | | Look, don't answer. |
+
+Settings can also go in `~/.config/hitl/config.json` (`port`, `host`, `base`, `token`, `allowHosts`, `notify`,
+`exclude`, `hide`, `showSecrets`, `maxFileMb`, `git`, `watch`). `HITL_HOME` moves that folder.
+
+The links include every address your phone might use: your Wi-Fi or LAN address, and a Tailscale address if you have
+one. Add the page to your phone's home screen and it opens like an app.
+
+## Notifications on your phone
+
+```sh
+npx hitloop notify ntfy             # makes a private ntfy topic, saves it, and sends a test
+npx hitloop notify webhook <url>    # or POST JSON anywhere: Pushover, Discord, Home Assistant, …
+npx hitloop notify link http://100.100.4.74:4199   # where the tap should open
+npx hitloop notify test | off
+```
+
+Install the [ntfy app](https://ntfy.sh) and subscribe to the topic it prints. Questions and reviews are batched (one
+notification once the agent has been quiet for 20 seconds); approvals go out within a couple of seconds, at high
+priority. Notifications say what's waiting, never your answers.
+
+## Safety
+
+- **A token by default**: the server listens on your network so your phone can reach it, so every request needs the
+  token (in the link once, then a cookie). `--local` listens on this computer only.
+- **Project files** are served only from inside the project, never `.git` or secret-looking files (`.env`, `*.key`,
+  `*.pem`, `id_rsa`), never through a link that points outside, and never excluded ones.
+- **What an agent writes is untrusted**: markdown is sanitised, HTML runs in a sandbox with no scripts, SVGs and files
+  are served so they can't run script, diagrams are drawn as images.
+- **DNS rebinding** is refused (unknown host names), and so are writes from other sites.
+- **It writes only** in `.hitl/` and its own config folder; `init` also writes `CLAUDE.md`, and the hooks
+  `.claude/settings.json`.
+
+## Development
+
+```sh
+npm install
+npm test                                    # builds, then runs the tests
+node scripts/demo.mjs .demo/trailhead       # a demo project with everything in it
+HITL_HOME=.demo/home node dist/cli.js --solo .demo/trailhead --local
+node scripts/shots.mjs http://localhost:4199/ .demo/shots   # phone and desktop screenshots of every page
+```
+
+- **The server** is TypeScript in `src/`, no runtime dependencies, Node 20 or newer.
+- **The page** is plain JavaScript in `client/`, bundled by esbuild; Shiki's grammars, Mermaid and the math renderer
+  load only when needed.
+
+Releasing: bump the version in `package.json`, commit, push to main. The Release workflow publishes a version that
+isn't on npm yet (trusted publishing), tags it and makes a GitHub release.
+
+## License
+
+MIT

package/dist/agent.js

@@ -0,0 +1,318 @@
+// What an agent reads: one feed of everything the human said since it last read (answers, verdicts, comments, notes),
+// compact so hundreds of answers don't flood its context; waiting until the human has said something; and the
+// decision log. Shared by the MCP tools and the CLI.
+import path from 'node:path';
+import { Questions, StoreError } from './q/store.js';
+import { readAnswers, summaryLine as questionsLine } from './q/agent.js';
+import { allQuestions, answerText, isDone } from './q/model.js';
+import { Reviews } from './r/store.js';
+import { VERDICT_TEXT, isStale, summarise, verdictText, whereText } from './r/model.js';
+import { Notes } from './fs/notes.js';
+export function openProject(root) {
+    const r = path.resolve(root);
+    return { root: r, questions: new Questions(r), reviews: new Reviews(r), notes: new Notes(path.join(r, '.hitl', 'notes'), r) };
+}
+// ── reviews ──
+export function reviewLine(s) {
+    const bits = [];
+    if (s.mode === 'approve')
+        bits.push(s.overall ? (s.overall === 'ok' ? 'APPROVED' : s.overall === 'no' ? 'REFUSED' : 'changes asked for') : 'waiting for a yes or no');
+    else {
+        if (s.mode === 'review')
+            bits.push(`${s.reviewed} of ${s.items} items reviewed`);
+        else
+            bits.push(`${s.items} item${s.items === 1 ? '' : 's'} shown`);
+        if (s.ok)
+            bits.push(`${s.ok} good`);
+        if (s.changes)
+            bits.push(`${s.changes} need changes`);
+        if (s.no)
+            bits.push(`${s.no} no`);
+        if (s.open)
+            bits.push(`${s.open} open comment${s.open === 1 ? '' : 's'}`);
+        if (s.overall)
+            bits.push(`overall: ${VERDICT_TEXT[s.overall]}`);
+    }
+    if (s.stale)
+        bits.push(`${s.stale} verdict${s.stale === 1 ? '' : 's'} on an earlier version`);
+    if (s.unread)
+        bits.push(`${s.unread} new`);
+    if (s.status === 'closed')
+        bits.push('closed');
+    if (s.errors)
+        bits.push(`${s.errors} error${s.errors === 1 ? '' : 's'} in the file`);
+    return `${s.id} (${s.mode}, "${s.title}"${s.from ? `, from ${s.from}` : ''}): ${bits.join(', ')}`;
+}
+export const REVIEW_FILTERS = ['new', 'all', 'open'];
+/** The human's feedback on a review, as text and data. "new" marks it read unless peek. */
+export function readFeedback(reviews, id, opts = {}) {
+    const l = reviews.load(id);
+    if (!l)
+        throw new StoreError(`No review "${id}"${reviews.ids().length ? ` (there are: ${reviews.ids().join(', ')})` : ''}`);
+    const fb = reviews.feedback(id);
+    const r = l.review;
+    const filter = opts.filter ?? 'new';
+    const since = filter === 'new' ? fb.readSeq : -1;
+    const s = summarise(r, fb, l.errors.length);
+    const lines = [reviewLine(s)];
+    if (fb.overall && fb.overall.seq > since)
+        lines.push(`- OVERALL: ${verdictText(r, fb.overall.verdict).toUpperCase()}${fb.overall.note ? ` — "${fb.overall.note}"` : ''}`);
+    const label = (iid) => {
+        const it = r.items.find((i) => i.id === iid);
+        return iid === '' ? '(the whole review)' : it ? `${iid} (${it.title})` : `${iid} (removed)`;
+    };
+    for (const it of r.items) {
+        const v = fb.items[it.id];
+        if (v && v.seq > since)
+            lines.push(`- ${label(it.id)}: ${VERDICT_TEXT[v.verdict]}${v.note ? ` — "${v.note}"` : ''}${isStale(it, v) ? ' (given to an earlier version)' : ''}${v.ack && filter !== 'new' ? ` [done: ${v.ack.note}]` : ''}`);
+    }
+    const show = (c) => {
+        const fresh = c.seq > since || c.replies.some((x) => x.seq > since && x.from === 'owner');
+        if (filter === 'open')
+            return c.status === 'open' && c.from === 'owner';
+        return fresh;
+    };
+    for (const c of fb.comments.filter(show)) {
+        const w = whereText(c);
+        lines.push(`- comment ${c.id} on ${label(c.item)}${w ? `, ${w}` : ''}${c.status === 'resolved' ? ' [resolved]' : ''}: "${c.body}"`);
+        if (c.quote)
+            lines.push(`  about: ${JSON.stringify(c.quote.length > 300 ? c.quote.slice(0, 297) + '…' : c.quote)}`);
+        if (c.marked)
+            lines.push(`  marked-up picture: ${c.marked}`);
+        for (const p of c.photos ?? [])
+            lines.push(`  photo: ${p}`);
+        for (const x of c.replies)
+            if (filter !== 'new' || (x.seq > since && x.from === 'owner'))
+                lines.push(`  ${x.from === 'owner' ? 'human' : 'you'}: "${x.body}"`);
+    }
+    if (lines.length === 1)
+        lines.push(filter === 'new' ? 'Nothing new since you last read.' : filter === 'open' ? 'No open comments.' : 'No feedback yet.');
+    if (filter === 'new' && !opts.peek && fb.seq > fb.readSeq)
+        reviews.markRead(id, fb.seq);
+    return { text: lines.join('\n'), data: { summary: s, feedback: fb } };
+}
+// ── notes ──
+export function readNotes(notes, opts = {}) {
+    const { seq, readSeq } = notes.marks();
+    const filter = opts.filter ?? 'new';
+    const list = notes.all().filter((c) => {
+        if (filter === 'open')
+            return c.status === 'open';
+        if (filter === 'all')
+            return true;
+        return (c.author !== 'agent' && (c.seq ?? 0) > readSeq) || (c.replies ?? []).some((r) => r.from !== 'agent' && (r.seq ?? 0) > readSeq);
+    });
+    const lines = [];
+    for (const c of list) {
+        const where = !c.path ? 'a note' : c.line ? `${c.path}:${c.line}${c.endLine ? '-' + c.endLine : ''}` : c.area ? `${c.path} (marked area ${c.area.w}×${c.area.h} at ${c.area.x},${c.area.y})` : c.path;
+        lines.push(`- note ${c.id} on ${where}${c.status === 'resolved' ? ' [resolved]' : ''}: "${c.body}"`);
+        if (c.quote)
+            lines.push(`  lines: ${JSON.stringify(c.quote.length > 300 ? c.quote.slice(0, 297) + '…' : c.quote)}`);
+        if (c.image)
+            lines.push(`  marked-up picture: .hitl/notes/${c.image}`);
+        for (const p of c.photos ?? [])
+            lines.push(`  photo: .hitl/notes/${p}`);
+        for (const r of c.replies ?? [])
+            if (filter !== 'new' || ((r.seq ?? 0) > readSeq && r.from !== 'agent' && r.author !== 'agent'))
+                lines.push(`  ${r.from === 'agent' || r.author === 'agent' ? 'you' : 'human'}: "${r.body}"`);
+    }
+    if (filter === 'new' && !opts.peek && seq > readSeq)
+        notes.markRead(seq);
+    return { text: lines.join('\n'), count: list.length };
+}
+/** How much is new for the agent, per kind (cheap: nothing is marked read). */
+export function newsCounts(p) {
+    let questions = 0, reviews = 0;
+    for (const s of p.questions.summaries())
+        questions += s.unread + s.unreadMessages;
+    for (const s of p.reviews.summaries())
+        reviews += s.unread;
+    const notes = p.notes.unread();
+    return { questions, reviews, notes, total: questions + reviews + notes };
+}
+/** Everything the human said since the agent last read, across every question set, review and note. */
+export function news(p, opts = {}) {
+    const counts = newsCounts(p);
+    const out = [];
+    const want = (id) => !opts.ids?.length || opts.ids.includes(id);
+    for (const s of p.reviews.summaries()) {
+        if (!s.unread || !want(s.id))
+            continue;
+        out.push(`## Review ${readFeedback(p.reviews, s.id, { filter: 'new', peek: opts.peek }).text}`, '');
+    }
+    for (const s of p.questions.summaries()) {
+        if (!(s.unread + s.unreadMessages) || !want(s.id))
+            continue;
+        out.push(`## Questions ${readAnswers(p.questions, s.id, { filter: 'new', peek: opts.peek }).text}`, '');
+    }
+    if (counts.notes && want('notes')) {
+        const n = readNotes(p.notes, { filter: 'new', peek: opts.peek });
+        if (n.count)
+            out.push(`## Notes from the human (${n.count}; resolve each with a reply saying what you did)`, n.text, '');
+    }
+    if (!out.length)
+        out.push('Nothing new from the human since you last read.');
+    return { text: out.join('\n').trimEnd(), counts };
+}
+/** What's open, briefly: for `hitl status` and the MCP list tool. */
+export function overviewText(p) {
+    const lines = [];
+    const reviews = p.reviews.summaries();
+    const sets = p.questions.summaries();
+    const notes = p.notes.all();
+    if (reviews.length)
+        lines.push('Reviews:', ...reviews.map((s) => '- ' + reviewLine(s)));
+    if (sets.length)
+        lines.push('Question sets:', ...sets.map((s) => '- ' + questionsLine(s)));
+    const open = notes.filter((c) => c.status === 'open').length;
+    if (notes.length)
+        lines.push(`Notes from the human: ${open} open of ${notes.length}${p.notes.unread() ? `, ${p.notes.unread()} new` : ''}`);
+    if (!lines.length)
+        lines.push(`Nothing in ${p.root} yet: no questions, reviews or notes.`);
+    const c = newsCounts(p);
+    if (c.total)
+        lines.push('', `New since you last read: ${c.total} (npx hitloop news, or the news tool).`);
+    return lines.join('\n');
+}
+// ── waiting ──
+export const WAITS = ['any', 'done', 'all', 'blocking'];
+function met(p, w) {
+    const until = w.until ?? 'any';
+    const ids = w.ids?.length ? w.ids : undefined;
+    const stamp = [];
+    if (until === 'any') {
+        let n = 0;
+        for (const s of p.reviews.summaries())
+            if (!ids || ids.includes(s.id))
+                n += s.unread;
+        for (const s of p.questions.summaries())
+            if (!ids || ids.includes(s.id))
+                n += s.unread + s.unreadMessages;
+        if (!ids || ids.includes('notes'))
+            n += p.notes.unread();
+        return { ok: n > 0, stamp: String(n) + ':' + seqs(p, ids) };
+    }
+    const targets = ids ?? [...p.reviews.ids().filter((id) => p.reviews.summary(id)?.status === 'open'), ...p.questions.ids()];
+    if (!targets.length)
+        throw new StoreError('Nothing to wait for: name a review or question set');
+    let ok = true;
+    for (const id of targets) {
+        if (p.reviews.has(id)) {
+            const s = p.reviews.summary(id);
+            if (!s)
+                continue;
+            stamp.push(p.reviews.feedback(id).seq);
+            if (until === 'done' || until === 'blocking')
+                ok &&= s.done;
+            else
+                ok &&= s.done || (s.mode !== 'approve' && s.reviewed >= s.items && s.items > 0);
+        }
+        else if (p.questions.has(id)) {
+            const s = p.questions.summary(id);
+            if (!s)
+                continue;
+            stamp.push(p.questions.answers(id).seq);
+            if (until === 'blocking')
+                ok &&= s.blocking === 0;
+            else
+                ok &&= s.toAnswer === 0;
+        }
+        else
+            throw new StoreError(`No review or question set "${id}"`);
+    }
+    return { ok, stamp: stamp.join(',') };
+}
+function seqs(p, ids) {
+    const out = [];
+    for (const id of p.reviews.ids())
+        if (!ids || ids.includes(id))
+            out.push(p.reviews.feedback(id).seq);
+    for (const id of p.questions.ids())
+        if (!ids || ids.includes(id))
+            out.push(p.questions.answers(id).seq);
+    out.push(p.notes.marks().seq);
+    return out.join(',');
+}
+/** Wait until the condition holds (and the human has paused). Resolves true, or false on timeout or abort. */
+export async function waitFor(p, w) {
+    const started = Date.now();
+    const poll = w.pollMs ?? 1000;
+    let metAt = 0;
+    let lastStamp = '';
+    for (;;) {
+        if (w.signal?.aborted)
+            return false;
+        const m = met(p, w);
+        if (m.ok) {
+            if (!w.settleMs)
+                return true;
+            if (m.stamp !== lastStamp) {
+                lastStamp = m.stamp;
+                metAt = Date.now();
+            }
+            else if (Date.now() - metAt >= w.settleMs)
+                return true;
+        }
+        else
+            lastStamp = '';
+        if (w.timeoutMs && Date.now() - started >= w.timeoutMs)
+            return false;
+        await new Promise((r) => setTimeout(r, poll));
+    }
+}
+/** What the human decided: every answer, verdict and approval, newest first. q narrows it (words, all must match). */
+export function decisions(p, opts = {}) {
+    const out = [];
+    for (const id of p.questions.ids()) {
+        const l = p.questions.load(id);
+        if (!l)
+            continue;
+        const af = p.questions.answers(id);
+        for (const q of allQuestions(l.set)) {
+            const a = af.answers[q.id];
+            if (!a || !isDone(a) || a.status === 'skipped')
+                continue;
+            out.push({ at: a.at, kind: 'answer', request: id, requestTitle: l.set.title, id: q.id, subject: q.question, decision: answerText(q, a), ...(a.note ? { note: a.note } : {}) });
+        }
+    }
+    for (const id of p.reviews.ids()) {
+        const l = p.reviews.load(id);
+        if (!l)
+            continue;
+        const fb = p.reviews.feedback(id);
+        const r = l.review;
+        if (fb.overall)
+            out.push({ at: fb.overall.at, kind: r.mode === 'approve' ? 'approval' : 'overall', request: id, requestTitle: r.title, id: '', subject: r.title, decision: verdictText(r, fb.overall.verdict), ...(fb.overall.note ? { note: fb.overall.note } : {}), ...(r.from ? { from: r.from } : {}) });
+        for (const it of r.items) {
+            const v = fb.items[it.id];
+            if (v)
+                out.push({ at: v.at, kind: 'verdict', request: id, requestTitle: r.title, id: it.id, subject: it.title, decision: VERDICT_TEXT[v.verdict], ...(v.note ? { note: v.note } : {}), ...(r.from ? { from: r.from } : {}) });
+        }
+    }
+    out.sort((a, b) => b.at.localeCompare(a.at));
+    const words = (opts.q ?? '').toLowerCase().split(/\s+/).filter(Boolean);
+    const hits = words.length ? out.filter((d) => words.every((w) => `${d.requestTitle} ${d.subject} ${d.decision} ${d.note ?? ''} ${d.request} ${d.id}`.toLowerCase().includes(w))) : out;
+    return { decisions: hits.slice(0, Math.max(1, Math.min(2000, opts.limit ?? 200))), total: hits.length };
+}
+export function decisionsText(p, opts = {}) {
+    const { decisions: list, total } = decisions(p, opts);
+    if (!list.length)
+        return opts.q ? `No decisions match "${opts.q}".` : 'No decisions yet.';
+    const lines = [`${total} decision${total === 1 ? '' : 's'}${opts.q ? ` matching "${opts.q}"` : ''}${total > list.length ? ` (the newest ${list.length})` : ''}:`];
+    for (const d of list)
+        lines.push(`- ${d.at.slice(0, 10)} ${d.request}${d.id ? '/' + d.id : ''} — ${short(d.subject)}: ${d.decision}${d.note ? ` ("${d.note}")` : ''}`);
+    return lines.join('\n');
+}
+const short = (s) => {
+    const t = s.replace(/\s+/g, ' ').trim();
+    return t.length > 90 ? t.slice(0, 87) + '…' : t;
+};
+export function parseDuration(s, fallback) {
+    if (s === undefined || s === '')
+        return fallback;
+    const m = /^(\d+(?:\.\d+)?)\s*(ms|s|m|h)?$/.exec(s.trim());
+    if (!m)
+        throw new StoreError(`Not a duration: "${s}" (like 90s, 10m, 2h)`);
+    const n = Number(m[1]);
+    return Math.round(n * ({ ms: 1, s: 1000, m: 60_000, h: 3_600_000 }[m[2] ?? 's'] ?? 1000));
+}