sign-off-axi 0.3.2 → 0.3.3

package/README.md

@@ -131,7 +131,7 @@ sign-off-axi post --type explainer --title "<question>" --media <video> [--about
 sign-off-axi init [dir] [--agent auto|<name>]   write the repo setup under <dir>/.sign-off/ (config, board, mocks/ and evidence/ folders)
                                                 and install the skill for each chosen coding agent (auto: each one on PATH)
 sign-off-axi doctor [dir]                       check that setup and each agent's skill; every failure names its fix
-sign-off-axi validate <message.json>... [--kind <kind>] [--expect-invalid]   check ask, report and evidence messages against the contract (docs/contract.md) without posting
+sign-off-axi validate <message.json>... [--kind <kind>] [--expect-invalid]   check ask, report, evidence, gate and finding messages against the contract (docs/contract.md) without posting
 sign-off-axi open  [--port 4410] [--bind <address>] [--evidence-root <dir>]   start the board in the background; prints its URL and pid
 sign-off-axi status                             is the board open started for this file running? its URL and pid
 sign-off-axi stop                               stop that board
@@ -145,12 +145,12 @@ sign-off-axi export [--out <file.html>]          write a frozen read-only copy o
 
 - The board is the one you name right after the command (`sign-off-axi answers ./decisions.json`). With none, it is the nearest `.sign-off/` board that `init` set up, found by the walk described in [Test runs never touch your board](#test-runs-never-touch-your-board); otherwise the default board there (`~/.sign-off/decisions.json`, or under `SIGN_OFF_HOME`). Answers are saved next to it.
 - Next-step commands in the output name paths under the working folder relative to it, and say `npx -y sign-off-axi` when sign-off-axi runs through `npx`.
-- `post --type design` asks for a pick between up to 6 mock options, each with an optional `--mock <value>=<path>` file (`.html`, `.svg`, `.png`, `.jpg`, `.jpeg`, `.webp`) shown as a tall phone frame above its button (the recommended one first; on a phone the frames swipe sideways, the next one peeking in, and a tap opens one full size), plus a `--tradeoff` line and a `--recommend` badge. Mock paths are relative to the board file's folder and never escape it. One `.html` page can hold every variant: `--mock a=mocks/<key>/index.html?variant=a` loads the page with `?variant=a`. An `.html` mock or view loads the css, scripts, images and fonts beside it by relative name (`style.css`, `img/dot.png`), from its own folder only, never anything above it. The board adds a small pointing script to each `.html` mock: once the board turns it on for that frame, a tap on a part of the mock is kept from the mock and named back to the board as a path to that element, its tag and its words; it passes only text and gives the mock no reach into the board. With **Comment on the mocks** on, a tap opens a comment on that element: one per element, listed under the mocks with Edit and Delete, kept on the board and shown, until it is sent, only on the exact mock file it was made on. The comments go to the agent with the next answer on that card (a pick, Other answer or **Another round**, which may then have no note), each with its element, in `wait` and `answers` (`comments`); once sent they are listed as sent and can no longer change. An option with no mock, or whose file is gone, says "No mock for this option". `post --type decision` (the default) is exactly `raise`, and `raise` stays as its alias.
+- `post --type design` asks for a pick between up to 6 mock options, each with an optional `--mock <value>=<path>` file (`.html`, `.svg`, `.png`, `.jpg`, `.jpeg`, `.webp`) shown as a tall phone frame above its button (the recommended one first; on a phone the frames swipe sideways, the next one peeking in, and a tap opens one full size), plus a `--tradeoff` line and a `--recommend` badge. Mock paths are relative to the board file's folder and never escape it. One `.html` page can hold every variant: `--mock a=mocks/<key>/index.html?variant=a` loads the page with `?variant=a`. An `.html` mock or view loads the css, scripts, images and fonts beside it by relative name (`style.css`, `img/dot.png`), from its own folder only, never anything above it. The board adds a small pointing script to each `.html` mock: once the board turns it on for that frame, a tap on a part of the mock is kept from the mock and named back to the board as a path to that element, its tag and its words; it passes only text and gives the mock no reach into the board. With **Comment on the mocks** on, a tap opens a comment on that element: one per element, listed under the mocks with Edit and Delete (words typed but not yet saved stay with their element while the page is open, so tapping another element and back keeps them; a reload drops them), kept on the board and shown, until it is sent, only on the exact mock file it was made on. The comments go to the agent with the next answer on that card (a pick, Other answer or **Another round**, which may then have no note), each with its element, in `wait` and `answers` (`comments`); once sent they are listed as sent and can no longer change. An option with no mock, or whose file is gone, says "No mock for this option". `post --type decision` (the default) is exactly `raise`, and `raise` stays as its alias.
 - `post --type evidence` posts the next numbered update (`update-1`, `update-2`, ...) with 1 to 12 screenshots or recordings (`.png`, `.jpg`, `.jpeg`, `.webp`, `.mp4`, `.webm`, up to 50 MB each), a short note and an optional commit or PR link. The files are copied into `evidence/<number>/` next to the board, so the board is the store: no hosted service. The page shows the updates newest first; each file is served only while its size and SHA-256 still match what was posted, and recordings play inline on a phone. The person gives a verdict, **Pass**, **Fail** or **Needs work**, with an optional note, read back with `answers` or `wait --key update-<number>`.
 - `post --type diagram` and `post --type interactive` show a question with a picture: `--view <path>` names one board-relative file, an image (`.svg`, `.png`, `.jpg`, `.jpeg`, `.webp`) drawn at card width for a diagram, or one self-contained `.html` page that runs in a sandboxed frame for interactive. Every mock and view is served under a Content-Security-Policy with no `fetch`, no remote files and no access to the dashboard or its tab. They answer like a decision.
 - `post --type explainer` shows a question with a narrated video the agent made itself (stills plus speech from a free local engine such as piper or espeak-ng, joined with ffmpeg; the skill has the recipe). `--media` names one `.mp4` or `.webm`, copied into `evidence/<number>/` and served hash-checked like evidence media; it plays on the card with its own controls, at phone width too. `--about` is a short summary and each `--chapter m:ss=<title>` is a button that plays the video from there. sign-off itself never makes the video: it calls no speech engine, no ffmpeg and no network service.
 - The person can also tap **Another round** inside **Other answer** (with the typed note), which wakes a waiting agent the same way an answer does; the agent reads it back in `answers --json` under `rounds`, with any comments on mock elements it carried.
-- **Dismiss** (the × on an item in a list, **Dismiss** under Needs you first and beside **Skip for now** in Triage, or **Clear all done** on Answered) hides items from the board, Today included; **Undo** in the toast brings them back, and so does **Restore** under **Dismissed (N)** at the end of Needs you first and Triage. The agent is not told, so an ask it waits on keeps waiting. The storage is in [docs/file-formats.md](docs/file-formats.md).
+- **Dismiss** (the × on an item in a list, **Dismiss** under Needs you first and beside **Skip for now** in Triage, or **Clear all done** on Answered) hides items from the board, Today included; **Undo** in the toast brings them back, and so does **Restore** under **Dismissed (N)** at the end of Needs you first and Triage. `list` counts a dismissed item as neither waiting nor answered, as the board does (`list --full` says `dismissed` for an unanswered one and still its answer for an answered one), and `answers` does not count it as waiting; the agent is not told, so an ask it waits on keeps waiting, and `answers` still returns a dismissed answer. The storage is in [docs/file-formats.md](docs/file-formats.md).
 - The person can comment on any item (**Send as a comment**, also inside **Other answer**: each card has that one place to type) and queue a free-text prompt for the agent (**Ask the agent**). `poll` blocks until one arrives and prints every new one once (`--json` prints `{"messages":[{"id","kind","key"?,"text","at"}]}`); the page then shows it as read by the agent. Typed notes that are not sent yet stay in the browser across reloads; everything sent is saved next to the board and survives a restart.
 - The board runs on your own machine only: no hosted service, no recurring cost. It listens on `127.0.0.1` unless `--bind <address>` (or `bind:` in the `config.yaml` that `init` writes) names one private address of this machine, such as its VPN address, so a phone or tablet on your own network can open it. A `hosts:` line in that config names private DNS names that lead to the bind address, such as its mesh VPN name (commas between them), so the board also opens by name; `doctor` checks each one resolves to the bind address. All interfaces and public addresses are refused. Beyond `127.0.0.1` the board makes an access token once (`decisions.token`, mode 600, next to the board), `open` prints it in the link, and every request without it is refused; the link sets a cookie, so the page and its media work after the first load. Delete the token file to shut old links out at once, then `stop` and `open` for a new one.
 - `export` writes one self-contained HTML file (`decisions.export.html` by default): every item, answer, note and another-round request with its local mocks and media inlined; comments and queued prompts are left out. `--out` must end in `.html`, so a wrong path never overwrites the board. It opens from disk with no server, is read-only, and makes no network request. A mock page is inlined on its own, so the css and images beside it show only on the running board.
@@ -159,10 +159,10 @@ sign-off-axi export [--out <file.html>]          write a frozen read-only copy o
 - Raising a question that is already on the board is a no-op that reports its status, so an agent can re-run it safely. `--key` defaults to a slug of the title.
 - Each raised or posted item records when it was filed (`filed`), so Triage shows `Waiting since 09:15` and the Waiting on you tile `Oldest 09:15`; `post --replace` keeps an item's first time.
 - `open` is a no-op when the same board is already open on the same address, and fails with `CONFLICT` when it runs on another one. `--evidence-root` is the folder holding `.done-done/`, for decisions that link run evidence.
-- `--filer <id>` on `post` and `raise` saves who filed the item (an agent session id or any 1-128 of `A-Z a-z 0-9 . _ -`; `SIGN_OFF_FILER` sets it for every command, and a post with neither saves `CLAUDE_CODE_SESSION_ID` when it is set). `wait --filer <id>` then returns only answers to that filer's items it has not taken yet, marks each taken (`decisions.seen.jsonl`) and the card shows **Seen by agent**; it fails with `NOT_FOUND` when none of that filer's items is answered or waiting. The page never shows the filer id.
+- `--filer <id>` on `post` and `raise` saves who filed the item (an agent session id or any 1-128 of `A-Z a-z 0-9 . _ -`; `SIGN_OFF_FILER` sets it for every command, and a post with neither saves `CLAUDE_CODE_SESSION_ID` when it is set). `wait --filer <id>` then returns only answers to that filer's items it has not taken yet, marks each taken (`decisions.seen.jsonl`) and the card shows **Seen by agent**; it fails with `NOT_FOUND` when none of that filer's items still needs an answer. The page never shows the filer id.
 - `on_answer: <command> [args]` in the `config.yaml` beside the board runs that command for every saved answer, read when the board starts. It runs with no shell, in the board's folder, and gets the answer as one JSON line on stdin (`{"key","answer","label","close","at","note"?,"title"?,"filer"?,"comments"?}`, where `comments`, present when the answer carried comments on mock elements, lists each as `id`, `mock`, `hash`, `ref`, `tag`, `words` and `text`); the answer is never put into its arguments, so a typed note cannot inject a command. A failure is logged and never blocks the answer. With no shell, `|`, `>` and `&&` are passed as plain arguments, so put a pipeline in a script and name the script; a relative path such as `./hook.sh` is found from the board's folder. `doctor` checks that the command can run.
 - `post --from <file> --replace --filer <id>` lets several programs feed one board: it replaces only that filer's items (and items with no filer that the file names by key), keeps every other item, the board's other top-level fields and all answers, and an empty items list removes that filer's items.
-- `wait` replaces a polling loop. With `--key` it returns at once if that decision is already answered, and waits for a key that is not raised yet; without it, it waits for the next answer to any decision still waiting and fails with `NOT_FOUND` when nothing is. It wakes on each save, gives up after `--timeout` seconds (600, ten minutes, by default) with code `TIMEOUT` and exit 1, and takes `--full` and `--json` like `answers`. Ctrl-C stops it without changing anything.
+- `wait` replaces a polling loop. With `--key` it returns at once if that decision is already answered, and waits for a key that is not raised yet; without it, it waits for the next answer to any decision that still needs an answer and fails with `NOT_FOUND` when nothing needs one. It wakes on each save, gives up after `--timeout` seconds (600, ten minutes, by default) with code `TIMEOUT` and exit 1, and takes `--full` and `--json` like `answers`. Ctrl-C stops it without changing anything.
 - `open` records the board's pid, port and address next to the board file (`decisions.board.pid`). `status` and `stop` read it and only act on a pid that really serves that board, so no one has to guess a pid to kill. `open` on a board already served by `serve` records that server, so `stop` can close it too.
 
 ```

package/dist/cli.js

@@ -12,7 +12,7 @@ import { encode } from '@toon-format/toon';
 import { AxiError, runAxiCli } from 'axi-sdk-js';
 import { CHAPTERS_MAX, CLEARED, InputError, MEDIA_MAX, NOTE_MAX, REPLY, answersPath, appendAnnotation, appendAnswer, appendDismissed, appendMessage, appendRound, isKey, loadDecisions, markDelivered, markSeen, messagesPath, readAnnotations, readAnswers, readDismissed, readItems, readMessages, readRounds, roundsPath, seenBy, seenPath, sentIds, writeItems } from './store.js';
 import { ContractError, KINDS, MEDIA_BYTES, checkMessage, mediaFiles, parseMessage } from './contract.js';
-import { sweepVault } from './vault.js';
+import { deliverVault, errors, readVaultExpiry, sweepVault, takeVaultExpiries, VaultError } from './vault.js';
 const FORMAT = 'https://github.com/umeranjum17/sign-off/blob/main/docs/file-formats.md';
 const CONTRACT = 'https://github.com/umeranjum17/sign-off/blob/main/docs/contract.md';
 /** Coding agents init installs the skill for: the `npx skills add -a` name, the command that shows it is installed,
@@ -74,8 +74,10 @@ examples:
 `,
     validate: `usage: sign-off-axi validate <message.json>... [--kind <kind>] [--expect-invalid]
 Checks message files against the communication contract without posting them: ${CONTRACT}
-A message is one JSON object with "contract": 1, its "kind" and its "schema". This build checks kinds ask, report and evidence, schema 1 each.
+A message is one JSON object with "contract": 1, its "kind" and its "schema". This build checks kinds ask, report, evidence, gate and finding, schema 1 each.
 An evidence message's media paths read from the message file's folder: each file must be there, inside it, and 50 MB or less.
+A gate names its done-done run (run_id and commit) and offers 2 or 3 of approve (Approve), skip (Skip the judge) and fix (Fix first).
+A finding gives a repeated cause, its counts, record ids (never record text) and a proposed change, and offers apply (Apply) and skip (Skip).
 Post one with \`sign-off-axi post --kind <kind> --from <message.json>\`, or --from - to read stdin.
 A board file given to raise --from or post --from may hold such messages as items: each is checked the same way before it is stored, and a report shows under Reports with no answer.
 In such a file a new item of a contract kind (a decision, the default, an ask or a report) must carry contract, kind and schema; new evidence is posted with post --kind evidence, one at a time.
@@ -90,6 +92,8 @@ examples:
   sign-off-axi validate --kind ask messages/*.json
   sign-off-axi validate --kind report report.json
   sign-off-axi validate --kind evidence proof/evidence.json
+  sign-off-axi validate --kind gate gate.json
+  sign-off-axi validate --kind finding finding.json
   sign-off-axi validate --expect-invalid node_modules/sign-off-axi/fixtures/contract/*/invalid-*.json
 `,
     answers: `usage: sign-off-axi answers [board.json] [--key <key>] [--full] [--json]
@@ -106,10 +110,10 @@ examples:
 Blocks until the user answers, then prints the answer the way answers does. Use it instead of a polling loop.
   --filer    only the items posted with this --filer (or SIGN_OFF_FILER): returns every answer to them this filer has not taken yet,
              even one saved before wait started, and marks it taken, so the board shows "Seen by agent" on that card;
-             NOT_FOUND when none of them is answered or waiting. Without --filer or SIGN_OFF_FILER, wait takes no filer
+             NOT_FOUND when none of them still needs an answer. Without --filer or SIGN_OFF_FILER, wait takes no filer
   --key      wait for that decision; an answer saved before wait starts returns at once
              and a key not raised yet is waited for too
-             without --key, wait for the next answer to any decision still waiting; NOT_FOUND when nothing is
+             without --key, wait for the next answer to any decision that still needs an answer; NOT_FOUND when nothing needs one
   --timeout  seconds to wait, 600 (10 minutes) by default; then exits 1 with code TIMEOUT
   --full     adds the button label, close and title
   --json     {"<key>":{"answer","label","close","at","note"?}} for the new answers; note only when the user wrote one
@@ -160,6 +164,8 @@ Posts an item for the user. --type decision (the default) is a yes/no or pick-on
 else it is refused with one fix line and nothing is written. A key already on the board takes only the same message again; anything else exits 2.
 --kind evidence copies its media, read from the message file's folder (the current folder for stdin), into evidence/<number>/ like --type evidence;
 a "run" is shown as the update's proof record. With no key it posts the next update-<number>.
+--kind gate holds a done-done run for the user: it waits like an ask; run done-done respond --action <the picked value>.
+--kind finding asks the user to apply or skip a retro's proposed change: it waits like an ask.
 Listing --option needs --recommend <value>, on every type: the option you would pick, shown first and marked. --from --replace feeds are not held to it.
 --filer names who posts (your agent session or any id of 1-128 of A-Z a-z 0-9 . _ -), saved on the item; then \`wait --filer <id>\` gets the answer.
 SIGN_OFF_FILER sets it for every command; with neither, the Claude Code session id is saved when there is one.
@@ -185,6 +191,8 @@ examples:
   sign-off-axi post --type decision --title "Keep the weekly digest?" --recommend yes
   sign-off-axi post --kind ask --from ask.json --filer agent-41
   sign-off-axi post --kind evidence --from proof/evidence.json --filer done-done
+  sign-off-axi post --kind gate --from gate.json --filer done-done
+  sign-off-axi post --kind finding --from finding.json --filer learn-from-mistakes
   sign-off-axi post .sign-off/decisions.json --type interactive --title "Does the sign-in flow feel right?" --view mocks/sign-in/demo.html --option yes=Yes --option no="Needs work" --recommend yes
   sign-off-axi post --type evidence --title "Sign-in screen on a phone" --about "The new screen loads in 1 second." --media phone.png --media flow.mp4 --link https://github.com/acme/app/pull/12
   sign-off-axi post --type explainer --title "Is the new sign-in clear?" --about "The new sign-in has 2 steps." --media explainer.mp4 --chapter 0:00=Start --chapter 0:12="Step 2"
@@ -362,17 +370,19 @@ function filerOf(values, session = false) {
 }
 const waitFor = (on, filer, key) => (filer ? `Run \`sign-off-axi wait${on} --filer ${filer}\` to block until the user answers`
     : `Run \`sign-off-axi wait${on}${key ? ` --key ${key}` : ''}\` to block until the user answers`);
-/** Still waiting on the user: not answered, and something to answer (an item with no options and no reply is only shown). */
-const waits = (d) => !d.answer && (d.options.length > 0 || !!d.reply);
-/** The board's decisions with their latest answer; a missing board file is an empty board. */
+/** Still waiting on the user: not answered, not dismissed, and something to answer (an item with no options and no reply is only shown). */
+const waits = (d) => !d.dismissed && !d.answer && (d.options.length > 0 || !!d.reply);
+/** The board's decisions with their latest answer; a missing board file is an empty board.
+ *  A dismissal hides an item from the board and is not waiting here either, checked against the same dismissed log the board reads. */
 function board(file, say = warn) {
     if (!existsSync(file))
         return [];
     const decisions = loadDecisions(file), answers = readAnswers(file, say);
+    const hidden = new Set(readDismissed(file, answers, readRounds(file), say));
     for (const key of Object.keys(answers))
         if (!decisions.some((d) => d.key === key))
             say(`left out the answer for ${key}: that question is no longer in ${basename(file)}`);
-    return decisions.map((d) => ({ ...d, answer: Object.hasOwn(answers, d.key) ? answers[d.key] : undefined }));
+    return decisions.map((d) => ({ ...d, answer: Object.hasOwn(answers, d.key) ? answers[d.key] : undefined, dismissed: hidden.has(d.key) }));
 }
 function ready(file, on, root) {
     if (!existsSync(file))
@@ -383,9 +393,9 @@ function ready(file, on, root) {
 }
 function list(args) {
     const { file, values, on } = parse('list', args, TIERS);
-    const rows = board(file), waiting = rows.filter(waits), answered = rows.filter((d) => d.answer).length;
+    const rows = board(file), waiting = rows.filter(waits), answered = rows.filter((d) => d.answer && !d.dismissed).length;
     if (values.json)
-        return JSON.stringify({ board: file, decisions: rows });
+        return JSON.stringify({ board: file, decisions: rows.map(({ dismissed, ...d }) => (dismissed ? { ...d, dismissed } : d)) });
     const help = [
         ...(waiting.length ? [`Run \`sign-off-axi open${on}\` to show the board to the user`] : []),
         ...(answered ? [`Run \`sign-off-axi answers${on}\` to read the ${answered} saved answers`] : []),
@@ -393,7 +403,7 @@ function list(args) {
     ];
     const where = tilde(file) + (existsSync(file) ? '' : ' (no file yet; raise creates it)');
     if (values.full) {
-        return toon({ board: where, decisions: rows.map((d) => ({ key: d.key, status: d.answer?.answer ?? 'waiting', title: d.title, about: d.about ?? '', detail: d.detail ?? '',
+        return toon({ board: where, decisions: rows.map((d) => ({ key: d.key, status: d.answer?.answer ?? (d.dismissed ? 'dismissed' : 'waiting'), title: d.title, about: d.about ?? '', detail: d.detail ?? '',
                 recommend: d.recommend_value ?? '', default_if_silent: d.default_if_silent ?? '', close: d.close })) }, help);
     }
     return toon({
@@ -433,10 +443,13 @@ function answers(args) {
     return printAnswers(file, rows, waiting, values, waiting ? [`Run \`sign-off-axi open${on}\` so the user can answer the ${waiting} waiting`, `Run \`sign-off-axi wait${on}${key}\` to block until they answer`] : []);
 }
 async function wait(args) {
-    const { file, values, on: onBoard } = parse('wait', args, { ...TIERS, filer: { type: 'string' }, key: { type: 'string' }, timeout: { type: 'string', default: '600' } });
+    const { file, values, on: onBoard } = parse('wait', args, { ...TIERS, filer: { type: 'string' }, key: { type: 'string' }, timeout: { type: 'string', default: '600' }, into: { type: 'string' } });
     if (!/^\d{1,7}$/.test(values.timeout))
         throw fail('--timeout must be whole seconds, 0 or more', 'VALIDATION_ERROR', `Run \`sign-off-axi wait --help\``);
     const filer = filerOf(values), on = onBoard + (filer ? ` --filer ${filer}` : '');
+    // Vault Give delivery: its own loop, before any board read, so no ordinary wait changes. Undocumented while the vault is OFF.
+    if (values.into !== undefined)
+        return waitInto(file, values, onBoard);
     if (values.key === undefined)
         ready(file, onBoard);
     const seconds = Number(values.timeout), deadline = Date.now() + seconds * 1000, key = values.key === undefined ? '' : ` --key ${values.key}`;
@@ -448,7 +461,7 @@ async function wait(args) {
     for (const r of readRounds(file))
         seenRounds.set(r.key, (seenRounds.get(r.key) ?? 0) + 1);
     // A save wakes the loop at once; the 1 second timer is the fallback where file events are unavailable.
-    let wake = () => { }, watcher;
+    let wake = () => { }, watcher, vaultWarned = false;
     const name = basename(answersPath(file));
     try {
         try {
@@ -477,7 +490,36 @@ async function wait(args) {
             if (found.length) {
                 return printAnswers(file, found, waiting, values, [waiting ? `Run \`sign-off-axi wait${on}\` for the next of the ${waiting} waiting` : `Run \`sign-off-axi stop${onBoard}\` to close the board`]);
             }
-            if (values.key === undefined && !waiting) {
+            // Private vault expiries and refusals reach a filer wait only once its ordinary answers are out; each is taken once.
+            let live = 0, unknown = false;
+            if (filer !== undefined && values.key === undefined) {
+                const vault = await takeVaultExpiries(file, filer).catch(() => undefined);
+                unknown = !vault;
+                if ((!vault || !vault.clean) && !vaultWarned) {
+                    vaultWarned = true;
+                    warn('Vault expiry status unavailable; ordinary answers still arrive.');
+                }
+                if (vault?.events.length)
+                    return vaultEvent(file, vault.events, values);
+                live = vault?.live ?? 0;
+            }
+            // A keyed filer wait reads its own item's expiry or refusal, unless one of its board rows already holds the key.
+            if (filer !== undefined && values.key !== undefined && isKey(values.key) && !rows.some((d) => d.key === values.key)) {
+                let event;
+                try {
+                    event = await readVaultExpiry(file, values.key, filer, true);
+                }
+                catch (e) {
+                    if (e?.code !== 'READER_MISMATCH' && !vaultWarned) {
+                        vaultWarned = true;
+                        warn('Vault expiry status unavailable; ordinary answers still arrive.');
+                    }
+                }
+                if (event)
+                    return vaultEvent(file, [{ key: values.key, at: event.at, status: event.status }], values);
+            }
+            // A dismissed ask is hidden from the board, not withdrawn: it is not counted as waiting, but the agent still waits on it.
+            if (values.key === undefined && !rows.some((d) => waits({ ...d, dismissed: false })) && !live && !unknown) {
                 throw fail(`nothing${filer ? ` posted by ${filer}` : ''} is waiting on ${tilde(file)}`, 'NOT_FOUND', `Run \`sign-off-axi answers${onBoard}\` to read the saved answers`, `Run \`sign-off-axi raise${on} --title "<question>"\` to ask a new one`);
             }
             const left = deadline - Date.now();
@@ -496,6 +538,55 @@ async function wait(args) {
         watcher?.close();
     }
 }
+/** Metadata only: a fixed sentence, never a value, URL, path or filer. Failures exit 1; a delivery exits 0 with a label.
+ * One poll takes one kind, so all events share a status. */
+const VAULT_EVENTS = {
+    expired: { sentence: errors.EXPIRED, code: 'EXPIRED' },
+    refused: { sentence: errors.REFUSED, code: 'REFUSED' },
+    'delivery-uncertain': { sentence: errors.DELIVERY_UNCERTAIN, code: 'DELIVERY_UNCERTAIN' },
+    delivered: { sentence: 'Saved to the approved destination file.' },
+};
+function vaultEvent(file, events, values) {
+    const status = events[0].status, { sentence, code } = VAULT_EVENTS[status], at = (ms) => new Date(ms).toISOString().slice(0, 19) + 'Z';
+    if (code)
+        process.exitCode = 1;
+    if (values.json)
+        return JSON.stringify(Object.fromEntries(events.map((e) => [e.key, { answer: status, label: sentence, close: 'done', at: at(e.at) }])));
+    return toon({ board: tilde(file), [status]: events.map((e) => ({ key: e.key, at: at(e.at) })), ...(code ? { error: sentence, code } : { label: sentence }) }, code ? ['Ask for a fresh item under a new key'] : []);
+}
+// Only these leave the item deliverable later; every other vault code is final for this wait.
+const INTO_RETRY = ['BUSY', 'NOT_FOUND', 'VAULT_KEY_UNAVAILABLE'];
+const INTO_HELP = { DESTINATION_DENIED: 'Fix the destination folder locally, then run the same wait again', DESTINATION_EXISTS: 'Fix the destination folder locally, then run the same wait again',
+    READER_MISMATCH: 'Check --key, --filer and --into against the item', VALIDATION_ERROR: 'Check --key, --filer and --into against the item' };
+/** `wait --into`: delivers one Give once into its bound file, polling while it is pending. The destination is never printed. */
+async function waitInto(file, values, onBoard) {
+    const { key, filer, into } = values, seconds = Number(values.timeout), deadline = Date.now() + seconds * 1000;
+    // An explicit --filer: an inherited SIGN_OFF_FILER must not route a secret write.
+    if (key === undefined || filer === undefined)
+        throw fail('wait --into needs --key and --filer', 'VALIDATION_ERROR', 'Pass the Give item\'s --key and your own --filer');
+    let warned = false;
+    for (;;) {
+        let done;
+        try {
+            done = await deliverVault(file, key, filer, into);
+        }
+        catch (e) {
+            const code = e instanceof VaultError ? e.code : 'BUSY';
+            if (!INTO_RETRY.includes(code))
+                throw fail(errors[code], code, INTO_HELP[code] ?? 'Ask for a fresh item under a new key');
+            if (code !== 'NOT_FOUND' && !warned) {
+                warned = true;
+                warn('Vault delivery status unavailable; still waiting.');
+            }
+        }
+        if (done)
+            return vaultEvent(file, [done], values);
+        const left = deadline - Date.now();
+        if (left <= 0)
+            throw fail(`no vault item with key ${key} was ready to deliver within ${seconds}s`, 'TIMEOUT', `Run \`sign-off-axi wait${onBoard} --key ${key} --filer ${filer} --into <file> --timeout ${seconds}\` to keep waiting`);
+        await new Promise((ok) => setTimeout(ok, Math.min(1000, left)));
+    }
+}
 const slug = (title) => title.toLowerCase().replace(/[^a-z0-9]+/g, '-').slice(0, 64).replace(/^-+|-+$/g, '') || 'decision';
 /** Runs fn while holding an exclusive lock file that names its pid, so two agents raising at once never drop a decision,
  * and a lock a crash left behind can be told apart from one in use. */
@@ -608,7 +699,13 @@ function replace(file, on, from, filer) {
                 fits(i?.title, i?.key);
         const feed = fed.items.map((i) => ({ filed: first.get(i?.key)?.filed ?? now, ...i, ...(filer && { filer }) }));
         // An answer belongs to its question: an answered key may not come back asking something else.
-        const question = (d) => JSON.stringify([d.title, [...d.options].sort((a, b) => a.value.localeCompare(b.value)), !!d.reply]);
+        const question = (d) => JSON.stringify([d.title, [...d.options].sort((a, b) => a.value.localeCompare(b.value)), !!d.reply, d.run, d.finding]);
+        // A gate's answer is the action for its run, and a finding's the verdict on its proposal, so a dropped answered one cannot come back.
+        const saved = readAnswers(file);
+        for (const i of fed.items)
+            if ((i?.kind === 'gate' || i?.kind === 'finding') && !first.has(i?.key) && Object.hasOwn(saved, i?.key)) {
+                throw fail(`key ${i.key} was answered on ${tilde(file)} and is no longer there`, 'CONFLICT', 'Post it under a new key');
+            }
         for (const had of board(file)) {
             const d = incoming.find((x) => x.key === had.key);
             if (filer && d && had.filer && had.filer !== filer)
@@ -881,26 +978,28 @@ function storeIncoming(file, on, { incoming, raw }, filer, exact = false) {
         const current = board(file), items = existsSync(file) ? readItems(file).items : [], saved = readAnswers(file), now = new Date().toISOString();
         const raised = incoming.map((d, i) => {
             const had = current.find((c) => c.key === d.key);
+            // A contract message refused for its key exits 2 like any other refusal (contract section 4); raise --title keeps exit 1.
+            const contract = exact || raw[i]?.contract !== undefined || raw[i]?.kind !== undefined;
+            const refuse = (why) => {
+                if (contract)
+                    process.once('exit', () => { process.exitCode = 2; });
+                return fail(`key ${d.key} ${why}`, 'CONFLICT', contract ? 'Post it under a new key' : 'Raise it under a new --key');
+            };
             // An answer outlives its item: a new question under that key would inherit it.
             if (!had && Object.hasOwn(saved, d.key))
-                throw fail(`key ${d.key} already has a saved answer on ${tilde(file)} from an item no longer there`, 'CONFLICT', 'Raise it under a new --key');
+                throw refuse(`already has a saved answer on ${tilde(file)} from an item no longer there`);
             // The same question from another filer, or at another time, is the same question: it keeps its first filer and time.
-            const same = (x) => JSON.stringify({ ...x, answer: undefined, filer: undefined, filed: undefined, options: [...x.options].sort((a, b) => a.value.localeCompare(b.value)) });
+            const same = (x) => JSON.stringify({ ...x, answer: undefined, dismissed: undefined, filer: undefined, filed: undefined, options: [...x.options].sort((a, b) => a.value.localeCompare(b.value)) });
             // A message that names no filed time matches the one the board stamped.
             const differs = () => exact ? canon({ ...items.find((x) => x?.key === d.key), ...(raw[i].filed === undefined && { filed: undefined }) }) !== canon(raw[i]) : same(had) !== same(d);
-            if (had && differs()) {
-                // A contract message refused for its key exits 2 like any other refusal (contract section 4); raise --title keeps exit 1.
-                const contract = exact || raw[i]?.contract !== undefined || raw[i]?.kind !== undefined;
-                if (contract)
-                    process.once('exit', () => { process.exitCode = 2; });
-                throw fail(`key ${d.key} already holds a different ${contract ? 'message' : 'question'} on ${tilde(file)}`, 'CONFLICT', contract ? 'Post it under a new key' : 'Raise it under a new --key');
-            }
+            if (had && differs())
+                throw refuse(`already holds a different ${contract ? 'message' : 'question'} on ${tilde(file)}`);
             // Each new item records when it was raised, unless it names its own time.
             if (!had) {
                 fits(d.title, d.key);
                 items.push({ filed: now, ...raw[i] });
             }
-            return { key: d.key, status: !had ? 'raised' : had.answer ? `already answered ${had.answer.answer}` : waits(had) ? 'already waiting' : 'already posted', title: d.title };
+            return { key: d.key, status: !had ? 'raised' : had.answer ? `already answered ${had.answer.answer}` : waits({ ...had, dismissed: false }) ? 'already waiting' : 'already posted', title: d.title };
         });
         if (raised.some((r) => r.status === 'raised'))
             writeItems(file, items);

package/dist/contract.js

@@ -10,17 +10,24 @@ export class ContractError extends Error {
         this.help = help;
     }
 }
-export const KINDS = ['ask', 'report', 'evidence', 'gate', 'finding'];
-/** The kinds this build checks, with the schema number of each. */
-export const SCHEMAS = { ask: 1, report: 1, evidence: 1 };
+/** The kinds, with the schema number of each. */
+export const SCHEMAS = { ask: 1, report: 1, evidence: 1, gate: 1, finding: 1 };
+export const KINDS = Object.keys(SCHEMAS);
 const COMMON = ['contract', 'kind', 'schema', 'key', 'title', 'filer', 'link', 'about'];
 const FIELDS = {
     ask: [...COMMON, 'detail', 'options', 'recommend_value', 'default_if_silent', 'close'],
     report: [...COMMON, 'filed', 'group', 'decided'],
     evidence: [...COMMON, 'media', 'run'],
+    gate: [...COMMON, 'run', 'options', 'recommend_value', 'close'],
+    finding: [...COMMON, 'cause', 'incidents', 'days', 'evidence_ids', 'change_kind', 'proposal', 'options', 'recommend_value'],
 };
 /** A done-done run: its id, full commit and the four Checks lines. */
 const RUN = ['run_id', 'commit', 'outcome', 'repro', 'proof', 'evidence'];
+/** The fixed options of a kind, each with its one label: a gate's are the actions of done-done respond --action. */
+const ACTIONS = {
+    gate: { approve: 'Approve', skip: 'Skip the judge', fix: 'Fix first' },
+    finding: { apply: 'Apply', skip: 'Skip' },
+};
 export const MEDIA_BYTES = 50_000_000;
 /** Parses one message; a field written twice in any object refuses it, since plain JSON.parse keeps the last one quietly. */
 export function parseMessage(bytes) {
@@ -92,6 +99,24 @@ export function checkMessage(m, want) {
         if ([...v].length > max)
             throw bad(field, `is ${[...v].length} characters, over ${max}`, `Shorten "${name}" to ${max} characters`);
     };
+    /** A done-done run block with exactly these fields: an id, a full commit, and on evidence the four Checks lines. */
+    const checkRun = (fields) => {
+        const r = m.run;
+        if (!r || typeof r !== 'object' || Array.isArray(r))
+            throw bad('run', 'must be an object', `Set "run" to {${fields.map(show).join(', ')}}`);
+        const odd = Object.keys(r).find((f) => !fields.includes(f));
+        if (odd !== undefined)
+            throw bad(`run.${escaped(odd) || '""'}`, 'is not a field of run', `Remove ${show(odd)}; run has only ${fields.join(', ')}`);
+        const missing = fields.find((f) => !Object.hasOwn(r, f));
+        if (missing)
+            throw bad(`run.${missing}`, 'is required', `Add "${missing}" to "run"`);
+        if (!isKey(r.run_id))
+            throw bad('run.run_id', 'must be 1-128 of A-Z a-z 0-9 . _ -', 'Set "run_id" to the done-done run id');
+        if (!(typeof r.commit === 'string' && /^[a-f0-9]{40}$/.test(r.commit)))
+            throw bad('run.commit', 'must be a full 40-character lowercase commit', 'Set "commit" to the full hash, such as the output of git rev-parse HEAD');
+        for (const f of fields.slice(2))
+            text(`run.${f}`, r[f], 1000, `the run's ${f} Checks line, in 1000 characters or fewer`);
+    };
     need('contract');
     if (m.contract !== 1)
         throw bad('contract', `must be 1, not ${show(m.contract)}`, whole(m.contract) ? 'Upgrade sign-off-axi: this one knows contract 1' : 'Set "contract": 1');
@@ -100,8 +125,6 @@ export function checkMessage(m, want) {
         throw bad('kind', `must be one of ${KINDS.join(', ')}, not ${show(m.kind)}`, `Set "kind" to one of ${KINDS.join(', ')}`);
     if (want !== undefined && m.kind !== want)
         throw bad('kind', `is ${m.kind}, not --kind ${want}`, `Pass --kind ${m.kind}, or name the ${want} message file`);
-    if (!SCHEMAS[m.kind])
-        throw bad('kind', `${m.kind} is not checked by this sign-off-axi yet`, `Upgrade sign-off-axi to a version that checks ${m.kind}`);
     need('schema');
     if (!whole(m.schema))
         throw bad('schema', `must be a whole number, not ${show(m.schema)}`, `Set "schema": ${SCHEMAS[m.kind]}`);
@@ -123,7 +146,7 @@ export function checkMessage(m, want) {
         throw bad('link', 'must be an http(s) link with no spaces or control characters, or a 7-40 character commit hash', 'Set "link" to a URL such as "https://example.com/pr/4" or a commit hash, or leave it out');
     }
     if (m.kind !== 'ask') {
-        const what = m.kind === 'report' ? 'what happened' : 'what this shows';
+        const what = { report: 'what happened', gate: 'why the run is held', finding: 'the counts, with no record text' }[m.kind] ?? 'what this shows';
         if (!Object.hasOwn(m, 'about'))
             throw bad('about', 'is required', `Add "about": ${what}, in 500 characters or fewer`);
         text('about', m.about, 500, `${what}, in 500 characters or fewer`);
@@ -142,23 +165,8 @@ export function checkMessage(m, want) {
                     throw bad(`media[${n}]`, `${show(p)} must end in .png, .jpg, .jpeg, .webp, .mp4 or .webm`, 'Post a screenshot or recording in one of those formats');
             });
         }
-        if (Object.hasOwn(m, 'run')) {
-            const r = m.run;
-            if (!r || typeof r !== 'object' || Array.isArray(r))
-                throw bad('run', 'must be an object', `Set "run" to {${RUN.map(show).join(', ')}}`);
-            const odd = Object.keys(r).find((f) => !RUN.includes(f));
-            if (odd !== undefined)
-                throw bad(`run.${escaped(odd) || '""'}`, 'is not a field of run', `Remove ${show(odd)}; run has only ${RUN.join(', ')}`);
-            const missing = RUN.find((f) => !Object.hasOwn(r, f));
-            if (missing)
-                throw bad(`run.${missing}`, 'is required', `Add "${missing}" to "run"`);
-            if (!isKey(r.run_id))
-                throw bad('run.run_id', 'must be 1-128 of A-Z a-z 0-9 . _ -', 'Set "run_id" to the done-done run id');
-            if (!(typeof r.commit === 'string' && /^[a-f0-9]{40}$/.test(r.commit)))
-                throw bad('run.commit', 'must be a full 40-character lowercase commit', 'Set "commit" to the full hash, such as the output of git rev-parse HEAD');
-            for (const f of RUN.slice(2))
-                text(`run.${f}`, r[f], 1000, `the run's ${f} Checks line, in 1000 characters or fewer`);
-        }
+        if (Object.hasOwn(m, 'run'))
+            checkRun(RUN);
         return { kind: m.kind, schema: m.schema };
     }
     if (m.kind === 'report') {
@@ -177,10 +185,12 @@ export function checkMessage(m, want) {
         text('about', m.about, 500, 'a short note, or leave it out');
     if (Object.hasOwn(m, 'detail'))
         text('detail', m.detail, 1000, 'the longer note, or leave it out');
-    const options = m.options;
-    if (!Array.isArray(options) || options.length < 2 || options.length > 6) {
-        throw bad('options', Object.hasOwn(m, 'options') ? 'must list 2 to 6 options' : 'is required', 'Set "options" to 2-6 objects such as {"value":"yes","label":"Yes"}');
-    }
+    // A gate offers 2 or 3 of done-done's actions and a finding both of apply and skip, in any order, each with its own label.
+    const options = m.options, actions = ACTIONS[m.kind], max = actions ? Object.keys(actions).length : 6;
+    const named = actions && Object.entries(actions).map(([value, label]) => show({ value, label })).join(', ');
+    const listed = !actions ? 'Set "options" to 2-6 objects such as {"value":"yes","label":"Yes"}' : max === 3 ? `Set "options" to 2 or 3 of ${named}` : `Set "options" to ${named}`;
+    if (!Array.isArray(options) || options.length < 2 || options.length > max)
+        throw bad('options', Object.hasOwn(m, 'options') ? `must list ${{ 2: '2', 3: '2 or 3' }[max] ?? '2 to 6'} options` : 'is required', listed);
     options.forEach((o, n) => {
         const field = `options[${n}]`;
         if (!o || typeof o !== 'object' || Array.isArray(o))
@@ -194,6 +204,9 @@ export function checkMessage(m, want) {
             throw bad(`${field}.value`, `repeats ${o.value}`, 'Give every option its own value');
         text(`${field}.label`, o.label, 80, 'the button text, in 80 characters or fewer');
     });
+    const odd = actions && options.find((o) => !Object.hasOwn(actions, o.value) || actions[o.value] !== o.label);
+    if (odd)
+        throw bad('options', `${show(odd)} is not a ${m.kind} action: ${Object.keys(actions).join(', ')}, each with its label`, listed);
     const values = options.map((o) => o.value), pick = `the option you would pick: one of ${values.join(', ')}`;
     if (!Object.hasOwn(m, 'recommend_value'))
         throw bad('recommend_value', 'is required', `Add "recommend_value": ${show(values[0])}, ${pick}`);
@@ -204,6 +217,35 @@ export function checkMessage(m, want) {
     }
     if (Object.hasOwn(m, 'close') && m.close !== 'done' && m.close !== 'release')
         throw bad('close', 'must be done or release', 'Set "close" to "done" or "release", or leave it out');
+    // A gate's run is its own rule (section 5), so it comes after the field rules of section 4.
+    if (m.kind === 'gate') {
+        if (!Object.hasOwn(m, 'run'))
+            throw bad('run', 'is required', 'Add "run": {"run_id": "<done-done run id>", "commit": "<full commit>"}, the run held for approval');
+        checkRun(RUN.slice(0, 2));
+    }
+    // A finding names its records by id only; the validator cannot see record text, so keeping it out is the producer's job.
+    if (m.kind === 'finding') {
+        const must = (f, ok, rule, help) => {
+            if (!Object.hasOwn(m, f))
+                throw bad(f, 'is required', help);
+            if (!ok(m[f]))
+                throw bad(f, rule, help);
+        };
+        must('cause', (v) => typeof v === 'string' && /^[a-z0-9-]{1,64}$/.test(v), 'must be 1-64 of a-z 0-9 -', 'Set "cause" to the repeated cause, such as "missing-env"');
+        for (const f of ['incidents', 'days'])
+            must(f, whole, 'must be a whole number, 0 or more', `Set "${f}" to a count, such as 4`);
+        must('evidence_ids', (v) => Array.isArray(v) && v.length <= 50, 'must list 0 to 50 record ids', 'Set "evidence_ids" to the ids of the records, such as ["rec-7f3a"], never their text');
+        m.evidence_ids.forEach((id, n) => {
+            if (!isKey(id))
+                throw bad(`evidence_ids[${n}]`, 'must be 1-128 of A-Z a-z 0-9 . _ -', 'Name each record by its id, never its text');
+            if (m.evidence_ids.indexOf(id) < n)
+                throw bad(`evidence_ids[${n}]`, `repeats ${id}`, 'List each record id once');
+        });
+        must('change_kind', (v) => ['doc', 'rule', 'code'].includes(v), 'must be doc, rule or code', 'Set "change_kind" to "doc", "rule" or "code"');
+        if (!Object.hasOwn(m, 'proposal'))
+            throw bad('proposal', 'is required', 'Add "proposal": the change, in 500 characters or fewer');
+        text('proposal', m.proposal, 500, 'the change, in 500 characters or fewer');
+    }
     return { kind: m.kind, schema: m.schema };
 }
 /** An evidence message's media files, from `base`, the message file's folder: each a file of 50,000,000 bytes or fewer whose real path,

package/dist/store.js

@@ -165,6 +165,10 @@ export function loadDecisions(path, board) {
             ...(d.steps && { steps: d.steps.map(({ title, marks }) => ({ title, ...(marks?.length && { marks }) })) }),
             ...(stored && d.media && { media: d.media.map(({ path, sha256, bytes }) => ({ path, sha256, bytes })) }),
             ...(d.type === 'evidence' && { number: d.number }),
+            // A gate's run is part of its question: the same key with another run is a different question.
+            ...(d.kind === 'gate' && d.run && { run: { run_id: d.run.run_id, commit: d.run.commit } }),
+            // So is a finding's proposal, with the counts and records behind it.
+            ...(d.kind === 'finding' && { finding: { cause: d.cause, incidents: d.incidents, days: d.days, evidence_ids: d.evidence_ids, change_kind: d.change_kind, proposal: d.proposal } }),
             ...(d.type === 'explainer' && d.chapters && { chapters: d.chapters.map(({ at, title }) => ({ at, title })) }),
         };
     });

package/dist/vault.js

@@ -1,10 +1,10 @@
-// Vault remains OFF. The server imports only expiry housekeeping, never payload access.
-import { closeSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+// Vault remains OFF. The server imports only expiry functions; `wait --into` reaches payload only through deliverVault.
+import { closeSync, existsSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, isAbsolute, join, parse, resolve } from 'node:path';
 import { homedir } from 'node:os';
-import { createCipheriv, createHash, randomBytes } from 'node:crypto';
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from 'node:crypto';
 import { isKey } from './store.js';
-const errors = {
+export const errors = {
     VALIDATION_ERROR: 'Vault input is invalid: check mode, expiry, provider and destination.',
     EXPIRED: 'Vault item expired; request a fresh item.',
     VAULT_KEY_UNAVAILABLE: 'Vault key is unavailable; encrypted payload cannot be read.',
@@ -13,6 +13,10 @@ const errors = {
     TIMEOUT: 'Vault expiry wait timed out; retry status later.',
     READER_MISMATCH: 'This item belongs to a different filer or destination.',
     REFUSED: 'User refused this vault item; no value was delivered.',
+    DESTINATION_DENIED: 'Destination is outside an approved private config root or has unsafe permissions.',
+    DESTINATION_EXISTS: 'Destination exists; nothing was overwritten.',
+    ALREADY_READ: 'Vault item was already delivered; value is unavailable.',
+    DELIVERY_UNCERTAIN: 'Delivery interrupted; do not retry this item. Check destination locally, then request a fresh item if needed.',
 };
 export class VaultError extends Error {
     code;
@@ -35,6 +39,17 @@ function boardFile(board) {
         bad('NOT_FOUND');
     }
 }
+// Never used: callers stay silent with no permission walk, lock or state creation.
+const unused = (file) => {
+    try {
+        return !lstatSync(join(stateHome(), 'sign-off', 'vault'), { throwIfNoEntry: false }) || !lstatSync(join(dirname(file), '.sign-off-vault-id'), { throwIfNoEntry: false });
+    }
+    catch (e) {
+        if (e?.code === 'ENOENT' || e?.code === 'ENOTDIR')
+            return true;
+        throw e;
+    }
+};
 function boardId(file, create) {
     const side = join(dirname(file), '.sign-off-vault-id');
     if (!lstatSync(side, { throwIfNoEntry: false })) {
@@ -48,10 +63,12 @@ function boardId(file, create) {
         bad('VALIDATION_ERROR');
     return id;
 }
+// Absolute and free of raw '.' or '..' segments, which resolve() would otherwise hide.
+const plain = (p) => isAbsolute(p) && !p.split('/').some((s) => s === '.' || s === '..');
 function metadata(m) {
     if (!m || typeof m.board !== 'string' || !VAULT_ID.test(m.board) || !isKey(m.key) || !isKey(m.filer) || !['give', 'receive'].includes(m.mode)
         || !Number.isSafeInteger(m.expires) || m.expires <= 0
-        || (m.mode === 'give' ? typeof m.destination !== 'string' || !isAbsolute(m.destination) : m.destination !== undefined))
+        || (m.mode === 'give' ? typeof m.destination !== 'string' || !plain(m.destination) : m.destination !== undefined))
         bad('VALIDATION_ERROR');
     return { board: m.board, key: m.key, mode: m.mode, filer: m.filer, expires: m.expires,
         ...(m.destination !== undefined && { destination: resolve(m.destination) }) };
@@ -61,8 +78,9 @@ function privateFile(path) {
     if (!s.isFile() || s.nlink !== 1 || s.uid !== process.getuid?.() || (s.mode & 0o777) !== 0o600 || s.size > 32_768)
         bad('VAULT_KEY_UNAVAILABLE');
 }
+const stateHome = () => process.env.XDG_STATE_HOME || join(homedir(), '.local', 'state');
 function root(create = true) {
-    const state = process.env.XDG_STATE_HOME || join(homedir(), '.local', 'state');
+    const state = stateHome();
     if (!isAbsolute(state) || !process.getuid)
         bad('VAULT_KEY_UNAVAILABLE');
     const owner = join(state, 'sign-off'), vault = join(owner, 'vault');
@@ -87,6 +105,45 @@ function root(create = true) {
     }
     return vault;
 }
+const within = (child, parent) => child === parent || child.startsWith(parent.replace(/\/$/, '') + '/');
+function gitFree(path) {
+    let p = parse(path).root;
+    for (const part of path.slice(p.length).split('/')) {
+        p = join(p, part);
+        if (existsSync(join(p, '.git')))
+            return false;
+    }
+    return true;
+}
+// Owner-only list of approved destination directories: one canonical absolute path per line, `#` comments. Any bad line denies all.
+// ponytail: exact-directory approvals, so a destination must be a direct child; ancestors get only the .git walk.
+function approvedDirs(file, dir) {
+    const list = join(process.env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'sign-off', 'vault-destinations');
+    if (!isAbsolute(list))
+        bad('DESTINATION_DENIED');
+    let text;
+    try {
+        privateFile(list);
+        text = readFileSync(list, 'utf8');
+    }
+    catch {
+        bad('DESTINATION_DENIED');
+    }
+    const vaultDir = realpathSync(dir), home = realpathSync(homedir()), boardDir = dirname(file);
+    return text.split('\n').map((l) => l.trim()).filter((l) => l && !l.startsWith('#')).map((line) => {
+        const s = lstatSync(line, { throwIfNoEntry: false });
+        if (!plain(line) || !s?.isDirectory() || realpathSync(line) !== line || s.uid !== process.getuid?.() || (s.mode & 0o777) !== 0o700
+            || !gitFree(line) || within(home, line) || [vaultDir, boardDir].some((o) => within(o, line) || within(line, o)))
+            bad('DESTINATION_DENIED');
+        return line;
+    });
+}
+function checkDestination(dest, file, dir) {
+    if (!approvedDirs(file, dir).includes(dirname(dest)))
+        bad('DESTINATION_DENIED');
+    if (lstatSync(dest, { throwIfNoEntry: false }))
+        bad('DESTINATION_EXISTS'); // any entry, including a dangling symlink
+}
 function syncDir(path) {
     const fd = openSync(path, 'r');
     try {
@@ -145,12 +202,32 @@ function seal(dir, meta, value) {
         key.fill(0);
     }
 }
-async function lockedVault(dir, fn) {
+function unseal(key, meta, s) {
+    const d = createDecipheriv('aes-256-gcm', key, Buffer.from(s.nonce, 'base64'));
+    d.setAAD(aad(meta));
+    d.setAuthTag(Buffer.from(s.tag, 'base64'));
+    return Buffer.concat([d.update(Buffer.from(s.data, 'base64')), d.final()]);
+}
+// A stop signal with no listener ends the process at once, even inside the locked section, and the lock it leaves fails closed for good.
+// So a listener takes each stop signal the process has none for: it runs only between turns of the event loop, after a section has
+// removed its lock, and raises the signal again with no listener, so the process still ends by it. It stays on once added, since
+// Node drops a signal that came just before its listener was removed.
+const STOPS = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+function raise(signal) {
+    for (const s of STOPS)
+        process.off(s, raise);
+    if (!process.listenerCount(signal))
+        process.kill(process.pid, signal);
+}
+async function lockedVault(dir, fn, attempts = 50) {
+    for (const s of STOPS)
+        if (!process.listenerCount(s))
+            process.on(s, raise);
     let lock;
     try {
         const candidate = join(dir, 'lock');
         // ponytail: one global lock; split by board only if custody throughput requires it. Stale locks fail closed.
-        for (let tries = 0;; tries++) {
+        for (let tries = 1;; tries++) {
             try {
                 const fd = openSync(candidate, 'wx', 0o600);
                 closeSync(fd);
@@ -158,7 +235,7 @@ async function lockedVault(dir, fn) {
                 break;
             }
             catch (e) {
-                if (e.code !== 'EEXIST' || tries === 49)
+                if (e.code !== 'EEXIST' || tries === attempts)
                     bad('BUSY');
             }
             await new Promise((ok) => setTimeout(ok, 20));
@@ -195,11 +272,18 @@ function readRecord(path) {
         bad('VALIDATION_ERROR');
     }
     if (!record || record.schema !== 1 || !VAULT_ID.test(record.meta.board)
-        || JSON.stringify(metadata(record.meta)) !== JSON.stringify(record.meta) || !['pending', 'ready', 'refused', 'expired'].includes(record.status)
+        || JSON.stringify(metadata(record.meta)) !== JSON.stringify(record.meta) || !['pending', 'ready', 'refused', 'expired', 'claimed', 'delivered'].includes(record.status)
         || path !== join(dirname(path), `${digest(record.meta.board, record.meta.key)}.json`))
         bad('VALIDATION_ERROR');
     return record;
 }
+// A refusal is admitted only while the item is live (`operate` expires first), so only an expiry is bound to the deadline.
+function expiryEvent(id, record) {
+    const status = (record.status === 'claimed' ? 'delivery-uncertain' : record.status);
+    if (!Number.isSafeInteger(record.at) || record.at <= 0 || (status === 'expired' && record.at < record.meta.expires) || record.at > 8.64e15 || Object.hasOwn(record, 'sealed'))
+        bad('VALIDATION_ERROR');
+    return { schema: 1, id: `${digest(id, record.meta.key)}:${status}`, status, at: record.at };
+}
 function expire(path, record) {
     if (['pending', 'ready'].includes(record.status) && record.meta.expires <= Date.now()) {
         record = { schema: 1, meta: record.meta, status: 'expired', at: Date.now() };
@@ -258,30 +342,112 @@ export async function sweepVault(board) {
         return false;
     }
 }
-/** Private, replayable expiry observation; never a payload or public answer consumer. */
-export async function readVaultExpiry(board, key, filer) {
+/** Replayable expiry observation; never a payload consumer. The public keyed wait (`publicWait`) also expires its own item on access,
+ * gets a refusal, delivery or uncertain delivery as an event and tries the lock once; the private observer reports only expiry. */
+export async function readVaultExpiry(board, key, filer, publicWait = false) {
     if (!isKey(key) || !isKey(filer))
         bad('VALIDATION_ERROR');
     try {
-        const { file, dir } = custody(board, false);
+        // Never used: silent before any custody or permission walk.
+        const file = boardFile(board);
+        if (unused(file))
+            return;
+        const { dir } = custody(board, false);
         if (!dir)
             return;
         return await lockedVault(dir, () => {
             if (!lstatSync(join(dirname(file), '.sign-off-vault-id'), { throwIfNoEntry: false }))
                 return;
-            const { id, record } = boundRecord(file, dir, key, false);
+            const { id, path, record } = boundRecord(file, dir, key, false);
             if (!record)
                 return;
             if (record.meta.filer !== filer)
                 bad('READER_MISMATCH');
-            if (record.status === 'refused')
+            if (record.status === 'refused' && !publicWait)
                 bad('REFUSED');
-            if (record.status !== 'expired')
-                return;
-            if (!Number.isSafeInteger(record.at) || record.at <= 0 || record.at < record.meta.expires || Object.hasOwn(record, 'sealed'))
-                bad('VALIDATION_ERROR');
-            return { schema: 1, id: `${digest(id, key)}:expired`, status: 'expired', at: record.at };
-        });
+            const current = publicWait ? expire(path, record) : record;
+            const terminal = publicWait ? ['expired', 'refused', 'claimed', 'delivered'] : ['expired', 'refused'];
+            return terminal.includes(current.status) ? expiryEvent(id, current) : undefined;
+        }, publicWait ? 1 : 50);
+    }
+    catch (e) {
+        throw e instanceof VaultError ? e : new VaultError('BUSY');
+    }
+}
+/** For an ordinary filer wait: expires this filer's elapsed items in the board's folder, then takes each untaken terminal event once.
+ * A private `.<kind>.taken` marker per event dedupes filer waits; markers are durable before any event is returned.
+ * One kind per poll (expired, refused, delivery-uncertain, delivered), so one output never mixes two codes and a failure is never
+ * hidden behind a delivery's exit 0. */
+export async function takeVaultExpiries(board, filer) {
+    if (!isKey(filer))
+        bad('VALIDATION_ERROR');
+    const none = { events: [], live: 0, clean: true };
+    try {
+        // Never used: silent, with no permission walk, lock or state creation.
+        const file = boardFile(board);
+        if (unused(file))
+            return none;
+        const { dir } = custody(board, false);
+        if (!dir)
+            return none;
+        // One try: an ordinary wait never queues behind custody; BUSY means unknown this poll.
+        return await lockedVault(dir, () => {
+            const id = boardId(file, false), found = [], made = [];
+            let live = 0, clean = true;
+            for (const name of readdirSync(dir).filter((n) => n.endsWith('.json')).sort()) {
+                try {
+                    const path = join(dir, name), record = readRecord(path);
+                    if (record.meta.board !== id || record.meta.filer !== filer)
+                        continue;
+                    const r = expire(path, record);
+                    if (r.status === 'pending' || r.status === 'ready')
+                        live++;
+                    else
+                        found.push({ path, key: r.meta.key, event: expiryEvent(id, r) });
+                }
+                catch {
+                    clean = false;
+                }
+            }
+            try {
+                const take = (kind) => found.filter(({ path, event }) => {
+                    if (event.status !== kind)
+                        return false;
+                    const marker = path.replace(/\.json$/, `.${kind}.taken`);
+                    let fd;
+                    try {
+                        fd = openSync(marker, 'wx', 0o600);
+                    }
+                    catch (e) {
+                        if (e.code !== 'EEXIST')
+                            throw e;
+                        privateFile(marker);
+                        return false;
+                    }
+                    made.push(marker);
+                    try {
+                        writeFileSync(fd, event.id);
+                        fsyncSync(fd);
+                    }
+                    finally {
+                        closeSync(fd);
+                    }
+                    return true;
+                });
+                let fresh = [];
+                for (const kind of ['expired', 'refused', 'delivery-uncertain', 'delivered'])
+                    if (!fresh.length)
+                        fresh = take(kind);
+                if (made.length)
+                    syncDir(dir);
+                return { events: fresh.map(({ key, event }) => ({ key, at: event.at, status: event.status })), live, clean };
+            }
+            catch (e) {
+                for (const m of made)
+                    rmSync(m, { force: true });
+                throw e;
+            }
+        }, 1);
     }
     catch (e) {
         throw e instanceof VaultError ? e : new VaultError('BUSY');
@@ -310,6 +476,10 @@ const active = (r) => {
         bad('REFUSED');
     if (r.status === 'expired')
         bad('EXPIRED');
+    if (r.status === 'delivered')
+        bad('ALREADY_READ');
+    if (r.status === 'claimed')
+        bad('DELIVERY_UNCERTAIN');
     return r;
 };
 export async function createVault(input, value) {
@@ -325,6 +495,8 @@ export async function createVault(input, value) {
             bad('VALIDATION_ERROR'); // Terminal keys are tombstones, never reusable.
         if (meta.expires <= Date.now())
             bad('EXPIRED');
+        if (meta.destination !== undefined)
+            checkDestination(meta.destination, boardFile(input.board), dir);
         if (!value)
             master(dir);
         const record = { schema: 1, meta, status: value ? 'ready' : 'pending', at: Date.now(), ...(value && { sealed: seal(dir, meta, value) }) };
@@ -352,3 +524,64 @@ export async function refuseVault(board, key) {
         return summary(record);
     });
 }
+/** Give delivery for the bound filer and destination. Pending, or a never-used vault (nothing is created), returns undefined so the
+ * caller keeps waiting. Any failure after the claim leaves the record `claimed`, which is terminal (DELIVERY_UNCERTAIN) and never
+ * decrypts again. */
+export async function deliverVault(board, key, filer, into, afterClaim) {
+    if (!isKey(key) || !isKey(filer) || typeof into !== 'string' || !plain(into))
+        bad('VALIDATION_ERROR');
+    try {
+        if (unused(boardFile(board)))
+            return undefined;
+    }
+    catch (e) {
+        throw e instanceof VaultError ? e : new VaultError('BUSY');
+    }
+    return operate(board, key, false, (dir, path, old) => {
+        if (old && old.meta.filer !== filer)
+            bad('READER_MISMATCH');
+        const r = active(old);
+        if (r.meta.mode !== 'give' || resolve(into) !== r.meta.destination)
+            bad(r.meta.mode === 'give' ? 'READER_MISMATCH' : 'VALIDATION_ERROR');
+        if (r.status === 'pending')
+            return undefined;
+        const dest = r.meta.destination;
+        checkDestination(dest, boardFile(board), dir); // pre-claim: the payload stays ready on any denial
+        const secret = master(dir);
+        // Commit point: the ciphertext leaves disk here, so no later process can decrypt it.
+        publish(path, JSON.stringify({ schema: 1, meta: r.meta, status: 'claimed', at: Date.now() }));
+        let made;
+        try {
+            afterClaim?.();
+            const value = unseal(secret, r.meta, r.sealed);
+            const fd = openSync(dest, 'wx', 0o600);
+            try {
+                const st = fstatSync(fd);
+                made = { dev: st.dev, ino: st.ino };
+                writeFileSync(fd, value);
+                fsyncSync(fd);
+            }
+            finally {
+                closeSync(fd);
+                value.fill(0);
+            }
+            syncDir(dirname(dest));
+            const done = { schema: 1, meta: r.meta, status: 'delivered', at: Date.now() };
+            publish(path, JSON.stringify(done));
+            return { key: r.meta.key, at: done.at, status: 'delivered' };
+        }
+        catch {
+            // Remove only a file this call created; a lost wx race is someone else's file and stays.
+            try {
+                const s = lstatSync(dest);
+                if (made && s.dev === made.dev && s.ino === made.ino)
+                    rmSync(dest);
+            }
+            catch { /* best effort */ }
+            bad('DELIVERY_UNCERTAIN');
+        }
+        finally {
+            secret.fill(0);
+        }
+    });
+}

package/fixtures/contract/README.md

@@ -9,7 +9,7 @@ fixtures/contract/<kind>.v<schema>/valid-<name>.json
 fixtures/contract/<kind>.v<schema>/invalid-<field>-<rule>.json
 ```
 
-- `<kind>` is `ask`, `report`, `evidence`, `gate` or `finding`, and `<schema>` its schema number, such as `ask.v1/`. A version ships a folder for every kind it validates. This version ships `ask.v1/`, `report.v1/` and `evidence.v1/`.
+- `<kind>` is `ask`, `report`, `evidence`, `gate` or `finding`, and `<schema>` its schema number, such as `ask.v1/`. A version ships a folder for every kind it validates. This version ships `ask.v1/`, `report.v1/`, `evidence.v1/`, `gate.v1/` and `finding.v1/`. This is the one list of shipped folders; other docs point here.
 - Each file holds one message. An evidence fixture that names `media` ships those files next to it.
 - Each kind has at least 2 valid files and 3 invalid ones: one with a required field missing, one over a limit, and one with an unknown field.
 - An invalid file breaks exactly one rule. Its name gives the field and the rule, such as `invalid-title-too-long.json`, and sign-off's own tests check that the refusal names that field.

package/fixtures/contract/finding.v1/invalid-cause-missing.json

@@ -0,0 +1 @@
+{"contract":1,"kind":"finding","schema":1,"key":"lfm-missing-env","title":"Repeated cause: missing env var in CI","filer":"learn-from-mistakes","about":"4 incidents over 3 days in 2 sources.","incidents":4,"days":3,"evidence_ids":["rec-7f3a","rec-91be"],"change_kind":"doc","proposal":"Add the env var to the CI setup page.","options":[{"value":"apply","label":"Apply"},{"value":"skip","label":"Skip"}],"recommend_value":"apply"}

package/fixtures/contract/finding.v1/invalid-change_kind-unknown.json

@@ -0,0 +1 @@
+{"contract":1,"kind":"finding","schema":1,"key":"lfm-missing-env","title":"Repeated cause: missing env var in CI","filer":"learn-from-mistakes","about":"4 incidents over 3 days in 2 sources.","cause":"missing-env","incidents":4,"days":3,"evidence_ids":["rec-7f3a","rec-91be"],"change_kind":"process","proposal":"Add the env var to the CI setup page.","options":[{"value":"apply","label":"Apply"},{"value":"skip","label":"Skip"}],"recommend_value":"apply"}

package/fixtures/contract/finding.v1/invalid-evidence_ids-repeated.json

@@ -0,0 +1 @@
+{"contract":1,"kind":"finding","schema":1,"key":"lfm-missing-env","title":"Repeated cause: missing env var in CI","filer":"learn-from-mistakes","about":"4 incidents over 3 days in 2 sources.","cause":"missing-env","incidents":4,"days":3,"evidence_ids":["rec-7f3a","rec-7f3a"],"change_kind":"doc","proposal":"Add the env var to the CI setup page.","options":[{"value":"apply","label":"Apply"},{"value":"skip","label":"Skip"}],"recommend_value":"apply"}

package/fixtures/contract/finding.v1/invalid-options-label-changed.json

@@ -0,0 +1 @@
+{"contract":1,"kind":"finding","schema":1,"key":"lfm-missing-env","title":"Repeated cause: missing env var in CI","filer":"learn-from-mistakes","about":"4 incidents over 3 days in 2 sources.","cause":"missing-env","incidents":4,"days":3,"evidence_ids":["rec-7f3a","rec-91be"],"change_kind":"doc","proposal":"Add the env var to the CI setup page.","options":[{"value":"apply","label":"Apply"},{"value":"skip","label":"Leave it"}],"recommend_value":"apply"}

package/fixtures/contract/finding.v1/invalid-proposal-too-long.json

@@ -0,0 +1 @@
+{"contract":1,"kind":"finding","schema":1,"key":"lfm-missing-env","title":"Repeated cause: missing env var in CI","filer":"learn-from-mistakes","about":"4 incidents over 3 days in 2 sources.","cause":"missing-env","incidents":4,"days":3,"evidence_ids":["rec-7f3a","rec-91be"],"change_kind":"doc","proposal":"Add the env var to the CI setup page. Add the env var to the CI setup page. Add the env var to the CI setup page. Add the env var to the CI setup page. Add the env var to the CI setup page. Add the env var to the CI setup page. Add the env var to the CI setup page. Add the env var to the CI setup page. Add the env var to the CI setup page. Add the env var to the CI setup page. Add the env var to the CI setup page. Add the env var to the CI setup page. Add the env var to the CI setup page. Add the env var to the CI setup page. ","options":[{"value":"apply","label":"Apply"},{"value":"skip","label":"Skip"}],"recommend_value":"apply"}

package/fixtures/contract/finding.v1/invalid-record_text-unknown.json

@@ -0,0 +1 @@
+{"contract":1,"kind":"finding","schema":1,"key":"lfm-missing-env","title":"Repeated cause: missing env var in CI","filer":"learn-from-mistakes","about":"4 incidents over 3 days in 2 sources.","cause":"missing-env","incidents":4,"days":3,"evidence_ids":["rec-7f3a","rec-91be"],"change_kind":"doc","proposal":"Add the env var to the CI setup page.","options":[{"value":"apply","label":"Apply"},{"value":"skip","label":"Skip"}],"recommend_value":"apply","record_text":"CI failed: API_TOKEN is not set"}

package/fixtures/contract/finding.v1/valid-apply.json

@@ -0,0 +1 @@
+{"contract":1,"kind":"finding","schema":1,"key":"lfm-missing-env","title":"Repeated cause: missing env var in CI","filer":"learn-from-mistakes","about":"4 incidents over 3 days in 2 sources.","cause":"missing-env","incidents":4,"days":3,"evidence_ids":["rec-7f3a","rec-91be"],"change_kind":"doc","proposal":"Add the env var to the CI setup page.","options":[{"value":"apply","label":"Apply"},{"value":"skip","label":"Skip"}],"recommend_value":"apply"}

package/fixtures/contract/finding.v1/valid-skip-no-records.json

@@ -0,0 +1 @@
+{"contract":1,"kind":"finding","schema":1,"key":"lfm-flaky-wait","title":"Repeated cause: a test waits on a fixed sleep","about":"2 incidents in 1 day in Umer's runs.","cause":"fixed-sleep","incidents":2,"days":1,"evidence_ids":[],"change_kind":"code","proposal":"Wait for the page to be ready instead of sleeping.","options":[{"value":"skip","label":"Skip"},{"value":"apply","label":"Apply"}],"recommend_value":"skip"}

package/fixtures/contract/gate.v1/invalid-default_if_silent-unknown.json

@@ -0,0 +1 @@
+{"contract":1,"kind":"gate","schema":1,"key":"dd-gate-c4","title":"Move the sign-in run on past its judge?","about":"The judge could not tell the screens apart.","run":{"run_id":"20261011T120000Z-a1b2c3d4","commit":"0123456789abcdef0123456789abcdef01234567"},"options":[{"value":"approve","label":"Approve"},{"value":"fix","label":"Fix first"}],"recommend_value":"fix","default_if_silent":"fix"}

package/fixtures/contract/gate.v1/invalid-options-label-changed.json

@@ -0,0 +1 @@
+{"contract":1,"kind":"gate","schema":1,"key":"dd-gate-c3","title":"Move the sign-in run on past its judge?","about":"The judge could not tell the screens apart.","run":{"run_id":"20261011T120000Z-a1b2c3d4","commit":"0123456789abcdef0123456789abcdef01234567"},"options":[{"value":"approve","label":"Ship it"},{"value":"fix","label":"Fix first"}],"recommend_value":"fix"}

package/fixtures/contract/gate.v1/invalid-options-too-few.json

@@ -0,0 +1 @@
+{"contract":1,"kind":"gate","schema":1,"key":"dd-gate-c2","title":"Move the sign-in run on past its judge?","about":"The judge could not tell the screens apart.","run":{"run_id":"20261011T120000Z-a1b2c3d4","commit":"0123456789abcdef0123456789abcdef01234567"},"options":[{"value":"approve","label":"Approve"}],"recommend_value":"approve"}

package/fixtures/contract/gate.v1/invalid-run-missing.json

@@ -0,0 +1 @@
+{"contract":1,"kind":"gate","schema":1,"key":"dd-gate-c1","title":"Move the sign-in run on past its judge?","about":"The judge could not tell the screens apart.","options":[{"value":"approve","label":"Approve"},{"value":"fix","label":"Fix first"}],"recommend_value":"fix"}

package/fixtures/contract/gate.v1/invalid-run-outcome-unknown.json

@@ -0,0 +1 @@
+{"contract":1,"kind":"gate","schema":1,"key":"dd-gate-c5","title":"Move the sign-in run on past its judge?","about":"The judge could not tell the screens apart.","run":{"run_id":"20261011T120000Z-a1b2c3d4","commit":"0123456789abcdef0123456789abcdef01234567","outcome":"Umer can see it."},"options":[{"value":"approve","label":"Approve"},{"value":"fix","label":"Fix first"}],"recommend_value":"fix"}

package/fixtures/contract/gate.v1/valid-three-actions.json

@@ -0,0 +1 @@
+{"contract":1,"kind":"gate","schema":1,"key":"dd-gate-a1b2c3d4","title":"Move the sign-in run on past its judge?","filer":"done-done","about":"The judge could not tell the screens apart.","run":{"run_id":"20261011T120000Z-a1b2c3d4","commit":"0123456789abcdef0123456789abcdef01234567"},"options":[{"value":"approve","label":"Approve"},{"value":"skip","label":"Skip the judge"},{"value":"fix","label":"Fix first"}],"recommend_value":"fix","close":"done"}

package/fixtures/contract/gate.v1/valid-two-actions.json

@@ -0,0 +1 @@
+{"contract":1,"kind":"gate","schema":1,"key":"dd-gate-b5c6d7e8","title":"Approve the checkout run for Umer?","about":"Umer's checkout run passed every step but the judge.","run":{"run_id":"20261011T120000Z-a1b2c3d4","commit":"0123456789abcdef0123456789abcdef01234567"},"options":[{"value":"fix","label":"Fix first"},{"value":"approve","label":"Approve"}],"recommend_value":"approve"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sign-off-axi",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "One review board for evidence, quick yes/no decisions and retro changes.",
   "type": "module",
   "bin": { "sign-off-axi": "dist/cli.js" },

package/web/index.html

@@ -38,13 +38,15 @@
   .tiles { display: grid; grid-template-columns: 1fr 1fr; gap: 0.75rem; }
   .card, .tile { background: var(--surface); border: 1px solid var(--line); border-radius: 1rem; box-shadow: var(--shadow); }
   .card { padding: 1rem; }
-  .tile { position: relative; display: grid; grid-template-columns: auto minmax(0, 1fr) auto; align-content: start; gap: 0.25rem 0.5rem; padding: 0.625rem 0.875rem; color: var(--text); text-decoration: none; }
+  .tile { position: relative; display: grid; grid-template-columns: auto auto minmax(0, 1fr); align-content: start; gap: 0.25rem 0.5rem; padding: 0.625rem 0.875rem; color: var(--text); text-decoration: none; }
   .tile::after { content: "›" / ""; position: absolute; top: 0.5rem; right: 0.875rem; color: var(--muted); font-size: 1.5rem; line-height: 1.2; }
   .tile .name { grid-column: 1 / -1; font-size: 0.875rem; font-weight: 600; color: var(--muted); line-height: 1.3; }
   .tile .detail { grid-column: 1 / -1; }
-  .tile .n { grid-column: 1 / 3; font-size: 2.125rem; font-weight: 700; line-height: 1.15; font-variant-numeric: tabular-nums; }
+  .tile .n { grid-column: 1 / 3; font-size: 2.125rem; font-weight: 700; line-height: 1.15; font-variant-numeric: tabular-nums; white-space: nowrap; }
   .tile .detail { font-size: 0.8125rem; color: var(--muted); display: -webkit-box; -webkit-line-clamp: 1; -webkit-box-orient: vertical; overflow: hidden; }
-  .vis { align-self: center; display: flex; align-items: center; gap: 0.25rem; }
+  /* The marks give way to the count: one line at the right, and a mark with no room left wraps out of sight. */
+  .vis { align-self: center; display: flex; flex-wrap: wrap; justify-content: flex-end; align-items: center; gap: 0.25rem; height: 2.25rem; overflow: hidden; }
+  .vis::before { content: ""; height: 100%; }
   .vis img { width: 1.5rem; height: 2.25rem; object-fit: cover; object-position: top; border: 1px solid var(--line); border-radius: 0.25rem; }
   .mark { width: 0.875rem; height: 0.875rem; border-radius: 50%; border: 2px solid var(--area); }
   /* Waiting shows one clock and Answered up to three checks, drawn in the area's colour. */
@@ -123,15 +125,16 @@
   .foot .meta { margin: 0 auto 0 0; }
   .foot a { color: var(--accent); font-weight: 600; text-decoration: none; }
   .foot button { border-color: transparent; border-radius: 999px; background: var(--sunk); font-weight: 600; }
-  .day { position: relative; height: 4.5rem; border-bottom: 1px solid var(--border); }
+  /* Tall enough for the tallest column, six dots under its count, so no count reaches the caption above. */
+  .day { position: relative; height: 6.5rem; border-bottom: 1px solid var(--border); }
   .col { position: absolute; bottom: 0.25rem; display: flex; flex-direction: column-reverse; align-items: center; gap: 0.1875rem; transform: translateX(-50%);
-    font-size: 0.8125rem; font-weight: 700; line-height: 1.2; }
+    font-size: 0.8125rem; font-weight: 700; line-height: 1.2; overflow-wrap: normal; }
   .dot { width: 0.625rem; height: 0.625rem; border-radius: 50%; background: var(--c-answered); }
   .hours { display: flex; justify-content: space-between; color: var(--muted); font-size: 0.8125rem; font-variant-numeric: tabular-nums; }
   .events { list-style: none; margin: 0.75rem 0 0; padding: 0; display: grid; gap: 0.25rem; font-size: 0.9375rem; }
   .events time, .sec-head .meta { font-weight: 700; font-variant-numeric: tabular-nums; margin-right: 0.5rem; }
   .sec-head { display: flex; align-items: baseline; justify-content: space-between; gap: 1rem; }
-  .sec-head h2 { margin: 0; } .sec-head:has(+ .in-evidence) { margin: 1rem 0 0.375rem; }
+  .sec-head h2 { margin: 0; overflow-wrap: normal; } /* A long count beside a section name wraps itself, never the name mid-word. */ .sec-head:has(+ .in-evidence) { margin: 1rem 0 0.375rem; }
   .rows { list-style: none; margin: 0; padding: 0 1rem; }
   .rows > li + li { border-top: 1px solid var(--line); }
   .compact { display: flex; align-items: center; gap: 0.75rem; padding: 0.75rem 0; color: var(--text); text-decoration: none; }
@@ -394,7 +397,7 @@
     const drop = clearIfSaved(d.key, drafts.get(d.key));
     call('/api/answers', {
       method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ key: d.key, answer: o.value, note }),
-    }, () => { editing.delete(d.key); if (!typed) drop(); }).then(() => offerUndo(d, before)).then(() => typed && call('/api/messages', {
+    }, () => { forget(d.key); if (!typed) drop(); }).then(() => offerUndo(d, before)).then(() => typed && call('/api/messages', {
       method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ kind: 'comment', key: d.key, text: typed }),
     }, drop)).catch((e) => {
       shown(err).textContent = `Couldn't save: ${e.message}`;
@@ -566,7 +569,7 @@
       const drop = clearIfSaved(d.key, drafts.get(d.key));
       call('/api/rounds', {
         method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ key: d.key, note }),
-      }, () => { editing.delete(d.key); drop(); }).catch((e) => {
+      }, () => { forget(d.key); drop(); }).catch((e) => {
         shown(err).textContent = `Couldn't ask: ${e.message}`;
         roundBtn.disabled = false;
       });
@@ -672,6 +675,10 @@
 
   /** Comments on mock elements: the open editor per item, then the unsent list, then the sent ones. An unsent comment shows only on the mock file it was made on. */
   const editing = new Map(), talks = () => !state.readonly && !state.answers_only && !FROZEN;
+  // Words typed for an element and not saved yet, kept in page memory (not across a reload) so tapping another element or another Edit loses nothing.
+  const unsaved = new Map(), spot = (key, a) => `${key}~${a.mock}~${a.ref}`;
+  // Sent with an answer or round: the card's editor closes and its unsaved words go.
+  const forget = (key) => { editing.delete(key); for (const k of unsaved.keys()) if (k.startsWith(`${key}~`)) unsaved.delete(k); };
   const redraw = (d) => document.querySelectorAll('.ann').forEach((n) => n.dataset.ann === d.key && n.replaceWith(annotations(d)));
   function annotations(d) {
     const hash = new Map((d.mocks ?? []).map((m) => [m.value, m.hash])), open = editing.get(d.key);
@@ -704,10 +711,18 @@
     let form = '';
     if (open && pages.length) {
       const box = el('textarea', { id: `ann-text-${d.key}`, rows: 2, maxlength: 500, dir: 'auto' }), save = el('button', {}, 'Save comment'), cancel = el('button', { class: 'quick' }, 'Cancel');
-      box.value = open.text ?? mine.find((a) => !a.sent && a.mock === open.mock && a.ref === open.ref)?.text ?? '';
-      box.oninput = () => (open.text = box.value);
-      save.onclick = () => post(save, { id: open.id, key: d.key, mock: open.mock, ref: open.ref, tag: open.tag, words: open.words, text: box.value, hash: open.hash }, () => editing.delete(d.key));
-      cancel.onclick = () => { editing.delete(d.key); redraw(d); };
+      const at = spot(d.key, open);
+      box.value = unsaved.get(at) ?? mine.find((a) => !a.sent && a.mock === open.mock && a.ref === open.ref)?.text ?? '';
+      box.oninput = () => unsaved.set(at, box.value);
+      // Saved, only this editor closes: one opened while the save was on its way stays open with its words.
+      save.onclick = () => {
+        const text = box.value;
+        post(save, { id: open.id, key: d.key, mock: open.mock, ref: open.ref, tag: open.tag, words: open.words, text, hash: open.hash }, () => {
+          if (unsaved.get(at) === text) unsaved.delete(at);
+          if (editing.get(d.key) === open) editing.delete(d.key);
+        });
+      };
+      cancel.onclick = () => { unsaved.delete(at); editing.delete(d.key); redraw(d); };
       form = el('div', {}, el('label', { for: box.id }, `Comment on ${what(open)}`), box, el('div', { class: 'actions' }, save, cancel));
     }
     const row = (a, ...buttons) => el('li', {}, el('div', {}, el('p', { class: 'meta' }, what(a)), el('p', { class: 'saved-note', dir: 'auto' }, a.text)), ...buttons);
@@ -716,7 +731,7 @@
     const rows = mine.filter((a) => !a.sent).map((a) => {
       const edit = el('button', { class: 'quick', 'aria-label': `Edit comment, ${what(a)}` }, 'Edit'), del = el('button', { class: 'quick', 'aria-label': `Delete comment, ${what(a)}` }, 'Delete');
       edit.onclick = () => { editing.set(d.key, { ...a }); redraw(d); };
-      del.onclick = () => post(del, { id: a.id, deleted: true }, () => { if (editing.get(d.key)?.mock === a.mock && editing.get(d.key)?.ref === a.ref) editing.delete(d.key); });
+      del.onclick = () => post(del, { id: a.id, deleted: true }, () => { unsaved.delete(spot(d.key, a)); if (editing.get(d.key)?.mock === a.mock && editing.get(d.key)?.ref === a.ref) editing.delete(d.key); });
       return row(a, el('span', { class: 'actions' }, edit, del));
     });
     return el('div', { class: 'ann', 'data-ann': d.key }, pages.length ? el('div', { class: 'actions' }, toggle) : '',
@@ -759,21 +774,23 @@
       el('span', { class: 'n' }, String(items.length)), el('span', { class: 'vis', 'aria-hidden': 'true' }, ...marks), el('span', { class: 'detail', dir: 'auto' }, detail));
   }
 
-  /** The day so far: a mark per answer on a line of hours, and the list of them. Only answers have a place on it; an item's `filed` time is not shown here. */
+  /** The day so far: a mark per answer on a line of hours, and the list of them. Only answers have a place on it; an item's `filed` time is not shown here.
+   *  Each column carries its own count, so the columns add up to the day's total in the caption; columns sit at least a tenth of the line apart, so two counts never touch. */
   function today(answered) {
-    const day = new Date().toDateString(), done = answered.map((d) => ({ d, t: new Date(state.answers[d.key].at) }))
-      .filter((e) => e.t.toDateString() === day).sort((x, y) => x.t - y.t);
+    // `answered` arrives newest first with ties in the Answered list's order, so the list keeps that order as given; the chart sorts a copy by time.
+    const day = new Date().toDateString(), fresh = answered.map((d) => ({ d, t: new Date(state.answers[d.key].at) }))
+      .filter((e) => e.t.toDateString() === day), done = [...fresh].sort((x, y) => x.t - y.t);
     const head = (range) => el('div', { class: 'sec-head' }, el('h2', {}, 'Today'), range ? el('span', { class: 'meta' }, range) : '');
     if (!done.length) return el('section', { class: 'card today' }, head(), el('p', { class: 'meta' }, 'Nothing answered today yet.'));
     const h0 = done[0].t.getHours(), step = Math.ceil((done.at(-1).t.getHours() + 1 - h0) / 4), h1 = h0 + step * Math.ceil((done.at(-1).t.getHours() + 1 - h0) / step);
     const x = (t) => ((t.getHours() + t.getMinutes() / 60 - h0) / (h1 - h0)) * 100, cols = new Map();
-    for (const e of done) { const k = Math.round(x(e.t) / 4) * 4; cols.set(k, [...(cols.get(k) ?? []), e]); }
+    for (const e of done) { const k = Math.round(x(e.t) / 10) * 10; cols.set(k, [...(cols.get(k) ?? []), e]); }
     const hours = Array.from({ length: (h1 - h0) / step + 1 }, (_, i) => `${(h0 + i * step) % 24}:00`), SHOWN = 8;
     return el('section', { class: 'card today' }, head(`${done.length} answered, ${hours[0]} to ${hours.at(-1)}`),
       el('div', { class: 'day', 'aria-hidden': 'true' }, ...[...cols].map(([k, es]) => el('span', { class: 'col', style: `left: ${k}%` },
-        ...es.slice(0, 6).map(() => el('span', { class: 'dot' })), es.length > 1 ? String(es.length) : ''))),
+        ...es.slice(0, 6).map(() => el('span', { class: 'dot' })), String(es.length)))),
       el('div', { class: 'hours', 'aria-hidden': 'true' }, ...hours.map((h) => el('span', {}, h))),
-      el('ol', { class: 'events' }, ...done.slice(-SHOWN).map((e) => el('li', { dir: 'auto' }, el('time', {}, hhmm(e.t)), `${title(e.d)} · ${state.answers[e.d.key].label}`))),
+      el('ol', { class: 'events' }, ...fresh.slice(0, SHOWN).map((e) => el('li', { dir: 'auto' }, el('time', {}, hhmm(e.t)), `${title(e.d)} · ${state.answers[e.d.key].label}`))),
       done.length > SHOWN ? el('p', { class: 'meta' }, `and ${done.length - SHOWN} earlier`) : '');
   }
 
@@ -967,6 +984,12 @@
     pointing.set(frame.dataset.mock, on);
     aim(frame);
   }
+  // While pointing is on, a tap never opens the mock full size, even one that reaches the board instead of the frame:
+  // one on the frame's edge, one the browser sends there until it has drawn the frame taking taps, or one before a frame drawn anew is ready.
+  addEventListener('click', (e) => {
+    const frame = e.target.closest?.('.shot')?.querySelector('iframe[data-mock]');
+    if (frame && talks() && pointing.get(frame.dataset.mock) === true) e.preventDefault();
+  });
   addEventListener('message', (e) => {
     const frame = mockFrame(e.source), msg = e.data;
     if (!frame || !msg) return;