sign-off-axi 0.4.6 → 0.4.8

package/README.md

@@ -172,6 +172,8 @@ the new page on a phone." \
 
 *Proof of a fix, with two captures. Pass, Fail, or Needs work.*
 
+Evidence lists passed proof only: an update whose linked run passed. A plain update like this links no run, so it waits in **Waiting on you** instead, as does a failed or unchecked run, each with its honest result and its verdicts and Dismiss, so the agent still gets an answer. Passed updates are grouped by the project named in the run's proof line, `verify-<project>: ...` (trimmed, compared without case); a proof line with no such prefix goes under **Other**.
+
 ### Explainer video, with chapters
 
 ```sh
@@ -354,7 +356,8 @@ cannot block can be woken instead: an `on_answer:` line in the
 `config.yaml` beside the board names a command the board runs for every
 answer. A `notify:` block in that config can send an HTTP POST when a card
 enters Waiting on you, with its bearer token read from a named environment
-variable. The full reference, with the worked example, is in
+variable, or, with `receiver: muxr`, from the muxr host's `notify-token`
+file; `sign-off-axi notify test` sends a test notice. The full reference, with the worked example, is in
 [docs/commands.md](docs/commands.md).
 
 Every command takes `--help` and prints compact output with next-step hints.

package/dist/cli.js

@@ -5,14 +5,15 @@ import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
 import { spawn, spawnSync } from 'node:child_process';
 import { accessSync, closeSync, constants, existsSync, lstatSync, mkdirSync, mkdtempSync, openSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, watch, writeFileSync } from 'node:fs';
 import { lookup } from 'node:dns/promises';
-import { homedir, tmpdir, userInfo } from 'node:os';
+import { availableParallelism, homedir, tmpdir, userInfo } from 'node:os';
+import { Worker } from 'node:worker_threads';
 import { basename, delimiter, dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { parseArgs } from 'node:util';
 import { encode } from '@toon-format/toon';
 import { AxiError, runAxiCli } from 'axi-sdk-js';
 import { CHAPTERS_MAX, SIGNED_IN, CLEARED, InputError, MEDIA_MAX, NOTE_MAX, REPLY, answersPath, appendAnnotation, appendAnswer, appendDismissed, appendSendBack, appendDesignAnswer, appendMessage, appendRound, awaitsVerdict, isKey, loadDecisions, markDelivered, markSeen, messagesPath, readAnnotations, readAnswers, readDismissed, readItems, readMessages, readRounds, roundsPath, seenBy, seenPath, sentIds, unreadable as reasonOf, writeItems } from './store.js';
 import { ContractError, KINDS, MEDIA_BYTES, REPORT_INIT, checkMessage, mediaFiles, parseMessage, reportPage } from './contract.js';
-import { faults } from './evidence-text.js';
+import { faults, isStill } from './evidence-text.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';
@@ -27,8 +28,8 @@ const AGENTS = {
     'gemini-cli': { bin: 'gemini', dir: '.agents/skills', home: join(homedir(), '.gemini', 'skills') },
 };
 const TOP_HELP = `usage: sign-off-axi [command] [board.json] [flags]
-commands[17]:
-  (none)=list, raise, post, answers, wait, poll, open, status, stop, serve, export, init, report, signin, doctor, validate, help
+commands[18]:
+  (none)=list, raise, post, answers, wait, poll, open, status, stop, serve, export, init, report, signin, doctor, notify, validate, help
 board: the nearest .sign-off/ board (the walk's bounds and SIGN_OFF_HOME: README, "Test runs never touch your board"), else ~/.sign-off/decisions.json; a board file given always wins
 flags: --full and --json on list, answers and wait, --events on wait, --json on status, --filer on post, raise and wait, --help on every command, -v/--version
 examples:
@@ -61,7 +62,7 @@ examples:
   sign-off-axi
   sign-off-axi list ./decisions.json --full
 `,
-    raise: `usage: sign-off-axi raise [board.json] --title "<question>" [--key <key>] [--about <text>] [--detail <text>] --why <text> [--option <value>=<label>]... --outcome <value>=<text>... --recommend <value> --recommend-reason <text> --default <value> [--silent-by <ISO time>] [--merge <key>]... [--close done|release] [--filer <id>]
+    raise: `usage: sign-off-axi raise [board.json] --title "<question>" [--key <key>] [--about <text>] [--detail <text>] --why <text> [--option <value>=<label>]... --outcome <value>=<text>... --recommend <value> --recommend-reason <text> --default <value> [--silent-by <ISO time>] [--merge <key>]... [--proof <key>] [--close done|release] [--filer <id>]
        sign-off-axi raise [board.json] --from <decisions.json> [--filer <id>]
 Adds questions to the board: yes/no, or 2 to 6 choices with one --option each. --key defaults to a slug of the title.
 raise is the alias for post --type decision: same flags, same output.
@@ -75,6 +76,7 @@ Every question meets the question standard (docs/contract.md, "Asking a good que
   yes and no are labelled Yes and No; a question never takes Done, OK or Not now buttons.
 One decision is one card: look at the open cards first. --merge <key> (up to 10) names other cards on the board that ask the same thing and offer every option of this one:
 they are hidden while this one waits, and its answer closes them too, with the same value and a note naming this key. A merged card merges nothing itself, a card is named by one ask until that ask is answered, and an answered or dismissed card cannot be merged.
+--proof <key> names an evidence update already on the board that this ask rests on: Decide shows its capture and result at the top.
 The user answers with one tap and can undo it for a few seconds.
 --from adds every decision in a decisions file: ${FORMAT}
 Raising the same question again is a no-op that reports its status; a different question under a used key is refused.
@@ -285,6 +287,19 @@ It opens from disk with no server and makes no network request. --out defaults t
 examples:
   sign-off-axi export
   sign-off-axi export ./decisions.json --out ~/board-12-oct.html
+`,
+    notify: `usage: sign-off-axi notify [check|test] [dir]
+Device notifications are off until the config.yaml beside the board has a notify: block. For the muxr receiver it is:
+  notify:
+    receiver: muxr
+    link_base: https://my-machine.my-tailnet.ts.net:4410/   (https or a tailnet address, so the link opens on the iPad)
+    url: http://127.0.0.1:8793/v1/notify                    (optional: this is the default)
+The token is read at send time from the file <MUXR_HOME>/notify-token (default ~/.muxr/notify-token), never kept in the config.
+check (the default): says whether notifications are off, misconfigured, waiting on the token file, or ready. It sends nothing.
+test: sends one real "sign-off test" notice now and says plainly what happened (sent, no token file, token refused, receiver not running).
+examples:
+  sign-off-axi notify
+  sign-off-axi notify test
 `,
     doctor: `usage: sign-off-axi doctor [dir]
 Checks the repo setup init wrote: node version, config, board file, answer files, a lock a crashed command left behind, gitignore lines, folders, whether the dashboard port is free,
@@ -322,12 +337,14 @@ function fits(title, key) {
         throw fail(`${key ? `key ${key}: ` : ''}title is ${n} characters, over ${TITLE_MAX}`, 'VALIDATION_ERROR', `Shorten the title to ${TITLE_MAX} characters and put the rest in about`);
 }
 /** The question standard's flags: a decision's why, each option's outcome, the reason for the recommendation, when silence decides, the cards it merges. */
-const ASK_FLAGS = ['why', 'outcome', 'recommend-reason', 'silent-by', 'merge'];
+const ASK_FLAGS = ['why', 'outcome', 'recommend-reason', 'silent-by', 'merge', 'proof'];
 const MANY = ['option', 'outcome', 'merge'];
 /** Board types that are contract kinds: a decision (the default type) is an ask. */
 const CONTRACT_TYPES = ['decision', 'ask', 'evidence', 'report', 'plan', 'design'];
-/** The stored item as the message it came from: the board's own `filed` stamp is not part of a message that names none. */
-const asSent = ({ filed: _filed, ...rest }) => rest;
+/** The stored item as the message it came from: the board's own `filed` stamp is not part of a message that names none, and the notice record (`announced`) is the board's too. */
+const asSent = ({ filed: _filed, announced: _announced, ...rest }) => rest;
+/** A report names its own `filed` time, so only the notice record goes. */
+const asReport = ({ announced: _announced, ...rest }) => rest;
 /** Items of a --from file that carry contract or kind are contract messages: each is checked against its kind's rules before anything is stored.
  * A new item of a contract kind must carry them (contract section 2). A --replace feed replaces the stored item, so an item under an existing key
  * that changed is checked again; an unchanged item, a board-format one and every item outside a --replace feed are not checked again. */
@@ -349,7 +366,7 @@ function contractItems(items, from, file, replace = false) {
         // item, a board-format one and every item outside a --replace feed are not checked again.
         const asMessage = (x) => {
             if (m?.kind !== 'evidence')
-                return m?.kind === 'report' ? x : asSent(x);
+                return m?.kind === 'report' ? asReport(x) : asSent(x);
             const { type: _type, number: _number, media, evidence: run, ...message } = asSent(x);
             return { ...message, ...(media !== undefined && { media: Array.isArray(media) ? media.map((r) => r?.path) : media }), ...(run && { run }) };
         };
@@ -919,7 +936,7 @@ function postSignin(file, named, on, values, filer) {
         let status = same ? (done ? 'already done' : 'already waiting') : had ? 'new link' : 'posted';
         if (!same) {
             fits(d.title, d.key);
-            const next = { ...item, filed: new Date().toISOString().replace(/\.\d+Z$/, 'Z') };
+            const next = { ...item, ...(had?.announced && { announced: had.announced }), filed: new Date().toISOString().replace(/\.\d+Z$/, 'Z') };
             if (had)
                 items[at] = next;
             else
@@ -990,7 +1007,9 @@ function replace(file, named, on, from, filer) {
             }
         }
         const old = existsSync(file) ? readItems(file) : undefined;
-        let items = feed, extra = fed.extra, resulting = incoming;
+        // The notice record belongs to the card key, so a feed that rewrites a card keeps it: the receiver was told once.
+        const told = new Map((old?.items ?? []).filter((i) => i?.key && i.announced).map((i) => [i.key, i.announced]));
+        let items = feed.map((i) => (told.has(i?.key) ? { ...i, announced: told.get(i.key) } : i)), extra = fed.extra, resulting = incoming;
         if (filer) {
             // The feed's items first: the board shows the file's last item first, so the other filers' items keep showing on top.
             const fedKeys = new Set(feed.map((i) => i.key));
@@ -1067,7 +1086,7 @@ function postMedia(file, named, on, values, type, filer, message) {
         return path;
     });
     // A still that is not a picture of the product (text, colour bars or a placeholder) is measured before anything is copied.
-    const [unfit] = explainer ? [] : sources.flatMap((src) => /\.(png|jpe?g|webp)$/i.test(src) ? faults(src).map((f) => ({ src, f })) : []);
+    const [unfit] = explainer ? [] : sources.flatMap((src) => isStill(src) ? faults(src).map((f) => ({ src, f })) : []);
     if (unfit)
         throw fail(UNFIT[unfit.f](tilde(unfit.src)), 'VALIDATION_ERROR', 'Post a real capture of the running product instead: a screenshot or recording of the screen the user sees');
     mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
@@ -1077,8 +1096,8 @@ function postMedia(file, named, on, values, type, filer, message) {
         const current = board(file), store = join(dirname(file), 'evidence'), taken = current.map((d) => Number(/^update-(\d+)$/.exec(d.key)?.[1] ?? 0));
         const own = message ? message.key : explainer && (values.key ?? slug(values.title)), had = message && own && items.find((x) => x?.key === own);
         if (had) {
-            // The stored item, read back as the message it came from: its run, and each media file by hash.
-            const asMessage = ({ type: _t, number: _n, filed: _f, evidence: run, media: kept, ...rest }) => canon({ ...rest, run, media: kept?.map((x) => x.sha256) });
+            // The stored item, read back as the message it came from: its run, and each media file by hash. The notice record is the board's, not the message's.
+            const asMessage = ({ type: _t, number: _n, filed: _f, announced: _a, evidence: run, media: kept, ...rest }) => canon({ ...rest, run, media: kept?.map((x) => x.sha256) });
             if (asMessage(had) !== canon({ ...message, media: sources.length ? sources.map((src) => sha256(readFileSync(src))) : undefined })) {
                 throw fail(`key ${own} already holds a different message on ${tilde(file)}`, 'CONFLICT', 'Post it under a new key');
             }
@@ -1299,7 +1318,7 @@ function buildIncoming(values, extra, filer, file) {
     try {
         const { title, key = slug(title), about, detail, why, recommend: recommend_value, default: default_if_silent, close } = values;
         const ask = !Object.hasOwn(extra, 'type'), options = ask ? outcomesOf(values) : optionsOf(values);
-        const told = ask && { why, recommend_reason: values['recommend-reason'], silent_by: values['silent-by'], merges: values.merge };
+        const told = ask && { why, recommend_reason: values['recommend-reason'], silent_by: values['silent-by'], merges: values.merge, proof: values.proof };
         writeFileSync(source, JSON.stringify({ schema: 2, items: [{ key, title, about, detail, ...told, options, recommend_value, default_if_silent, close, ...extra, filer }] }));
         const incoming = loadDecisions(source, board), raw = readItems(source).items;
         if (!ask)
@@ -1325,6 +1344,9 @@ const canon = (v) => JSON.stringify(v, (_, x) => (x && typeof x === 'object' &&
 /** A merge names cards on the board that take this card's answer: each is on the board, offers every option of this card, and merges nothing itself.
  * A card is named by one ask until that ask is answered, dismissed or not. A merge new to the board also names a card still open. */
 function checkMerges(incoming, resulting, current) {
+    for (const d of incoming)
+        if (d.proof && resulting.find((x) => x.key === d.proof)?.type !== 'evidence')
+            throw fail(`key ${d.key} rests on ${d.proof}, which is not an evidence update on the board`, 'VALIDATION_ERROR', `Post the evidence update first, or leave out --proof`);
     const byKey = new Map(resulting.map((d) => [d.key, d])), before = new Map(current.map((c) => [c.key, c]));
     const closed = (key) => !!(before.get(key)?.answer || before.get(key)?.dismissed);
     const holder = (key, self) => resulting.find((x) => x.key !== self && !before.get(x.key)?.answer && x.merges?.includes(key));
@@ -1372,7 +1394,7 @@ function storeIncoming(file, named, on, { incoming, raw }, filer, exact = false)
             // 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, 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);
+            const differs = () => exact ? canon({ ...items.find((x) => x?.key === d.key), ...(raw[i].filed === undefined && { filed: undefined }), announced: undefined }) !== canon(raw[i]) : same(had) !== same(d);
             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.
@@ -1612,11 +1634,11 @@ function readSetup(so) {
     readFileSync(join(so, 'config.yaml'), 'utf8').split(/\r?\n/).forEach((l, n) => {
         // The notify block's indented lines keep their # , and } characters: only a # after a space starts a comment.
         if (inNotify && (!l.trim() || /^\s/.test(l))) {
-            const text = l.replace(/(^|\s+)#.*$/, '').trim(), field = text.match(/^(url|token_env|link_base)\s*:\s*(.+)$/);
+            const text = l.replace(/(^|\s+)#.*$/, '').trim(), field = text.match(/^(url|token_env|link_base|receiver)\s*:\s*(.+)$/);
             if (field)
                 notify[field[1]] = field[2].replace(/^(['"])(.*)\1$/, '$2');
             else if (text)
-                problems.push(`line ${n + 1} is not one "url", "token_env" or "link_base" line under notify`);
+                problems.push(`line ${n + 1} is not one "receiver", "url", "token_env" or "link_base" line under notify`);
             return;
         }
         inNotify = false;
@@ -1656,15 +1678,36 @@ function readSetup(so) {
     catch {
         return undefined;
     } };
+    const muxr = notify.receiver?.toLowerCase() === 'muxr';
+    if (notifyBlock && notify.receiver && !muxr)
+        problems.push('notify receiver must be muxr, or leave the receiver line out');
+    if (muxr)
+        notify.url ??= MUXR_URL;
     const sendTo = parsed(notify.url), base = parsed(notify.link_base);
     const usable = !!sendTo && !!base && (sendTo.protocol === 'https:' || (sendTo.protocol === 'http:' && (loopback(sendTo.hostname.replace(/^\[|\]$/g, '')) || sendTo.hostname === 'localhost')))
         && ['http:', 'https:'].includes(base.protocol) && (notify.token_env === undefined || /^[A-Za-z_]\w*$/.test(notify.token_env));
     if (notifyBlock && !usable)
         problems.push('notify needs url (https://, or http:// on this machine) and link_base (http:// or https://) lines, and token_env must name an environment variable');
+    // A phone or iPad opens the link, so a muxr notice's link is https or a tailnet address: 127.0.0.1 or a LAN name would be dead there.
+    const reachable = !!base && (base.protocol === 'https:' || /\.ts\.net$/i.test(base.hostname) || (isIP(base.hostname) === 4 && /^100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\./.test(base.hostname)));
+    if (notifyBlock && usable && muxr && !reachable)
+        problems.push('notify link_base must be https:// or a tailnet address (a .ts.net name or 100.x address) so the link opens on the iPad');
     return { board: join(so, goodBoard ? config.board : 'decisions.json'), port: goodPort ? Number(port) : 4410, bind, hosts, onAnswer, goodBoard, problems,
-        notify: notifyBlock && usable ? { url: notify.url, token_env: notify.token_env, link_base: notify.link_base } : undefined };
+        notify: notifyBlock && usable && (!muxr || reachable) ? { url: notify.url, token_env: notify.token_env, link_base: notify.link_base, muxr } : undefined };
 }
-const NOTIFY_SENDER = `void (async()=>{const delays=[2000,10000,60000];for(let i=0;i<4;i++){try{if((await fetch(process.env.SIGN_OFF_NOTIFY_URL,{method:'POST',headers:{'content-type':'application/json',...(process.env.SIGN_OFF_NOTIFY_TOKEN&&{authorization:'Bearer '+process.env.SIGN_OFF_NOTIFY_TOKEN})},body:process.env.SIGN_OFF_NOTIFY_BODY,signal:AbortSignal.timeout(10000)})).ok)return}catch{}if(i<3)await new Promise(r=>setTimeout(r,delays[i]))}require('node:fs').appendFileSync(process.env.SIGN_OFF_NOTIFY_LOG,new Date().toISOString()+' notification send failed for card '+process.env.SIGN_OFF_NOTIFY_ID+'\\n')})();`;
+const MUXR_URL = 'http://127.0.0.1:8793/v1/notify';
+/** The muxr receiver's token file, read at send time and never stored: <MUXR_HOME>/notify-token, MUXR_HOME defaulting to ~/.muxr. */
+const muxrTokenFile = () => join(process.env.MUXR_HOME || join(homedir(), '.muxr'), 'notify-token');
+/** Why a notice cannot be sent yet, in plain words; undefined when its token is there. */
+const tokenMissing = (n) => n.muxr
+    ? (() => { try {
+        return readFileSync(muxrTokenFile(), 'utf8').trim() ? undefined : `${tilde(muxrTokenFile())} is empty`;
+    }
+    catch {
+        return `${tilde(muxrTokenFile())} is not there yet (the muxr host writes it when it updates)`;
+    } })()
+    : n.token_env && !process.env[n.token_env] ? `${n.token_env} is not set` : undefined;
+const NOTIFY_SENDER = `void (async()=>{const delays=[2000,10000,60000],f=process.env.SIGN_OFF_NOTIFY_TOKEN_FILE;for(let i=0;i<4;i++){try{const t=f?require('node:fs').readFileSync(f,'utf8').trim():process.env.SIGN_OFF_NOTIFY_TOKEN;if((await fetch(process.env.SIGN_OFF_NOTIFY_URL,{method:'POST',headers:{'content-type':'application/json',...(t&&{authorization:'Bearer '+t})},body:process.env.SIGN_OFF_NOTIFY_BODY,signal:AbortSignal.timeout(10000)})).ok)return}catch{}if(i<3)await new Promise(r=>setTimeout(r,delays[i]))}require('node:fs').appendFileSync(process.env.SIGN_OFF_NOTIFY_LOG,new Date().toISOString()+' notification send failed for card '+process.env.SIGN_OFF_NOTIFY_ID+'\\n')})();`;
 /** The cards waiting on the user before a write: a card waiting after the write but not before it has entered Waiting on you. */
 function waitingKeys(file) {
     try {
@@ -1674,24 +1717,39 @@ function waitingKeys(file) {
         return undefined;
     }
 }
-/** Announces each card that entered Waiting on you with a write. The card is already stored, so nothing here fails the command. */
+/** Announces each card that entered Waiting on you with a write. The card is already stored, so nothing here fails the command.
+ * A card is announced once: the card keeps the record, so one that leaves Waiting and comes back (a new sign-in link) stays quiet,
+ * the same silent return an Undo gets. */
 function notifyEntered(file, named, before) {
     try {
         const so = dirname(named), notify = before ? readSetup(so).notify : undefined;
-        if (!before || !notify || (notify.token_env && !process.env[notify.token_env]))
+        if (!before || !notify || tokenMissing(notify))
+            return;
+        const { items } = readItems(file), fresh = board(file, () => { }).filter((d) => waits(d) && !before.has(d.key) && !items.some((i) => i?.key === d.key && i.announced));
+        if (!fresh.length)
             return;
-        for (const d of board(file, () => { }).filter((d) => waits(d) && !before.has(d.key)))
+        const at = new Date().toISOString().replace(/\.\d+Z$/, 'Z');
+        for (const i of items)
+            if (fresh.some((d) => d.key === i?.key))
+                i.announced = at;
+        writeItems(file, items);
+        for (const d of fresh)
             sendNotice(so, notify, d);
     }
     catch { }
 }
+/** The JSON one card sends: sign-off's own shape, or muxr's {title (1-80 chars), body, url, id}. */
+function noticeBody(notify, d) {
+    const kind = d.kind ?? { decision: 'ask', explainer: d.options.length ? 'ask' : 'report' }[d.type] ?? d.type;
+    const text = [...(d.about ?? d.detail ?? d.why ?? d.title).replace(/[\r\n]+/g, ' ')].slice(0, 200).join(''), url = `${notify.link_base.replace(/\/$/, '')}#waiting/${encodeURIComponent(d.key)}`;
+    if (notify.muxr)
+        return { title: [...d.title].slice(0, 80).join('') || d.key, body: text, url, id: d.key };
+    return { v: 1, source: 'sign-off', id: d.key, kind: ['ask', 'plan', 'design', 'evidence', 'report'].includes(kind) ? kind : 'ask',
+        title: [...d.title].slice(0, 120).join(''), text, url, at: d.filed ?? new Date().toISOString() };
+}
 function sendNotice(so, notify, d) {
     const token = notify.token_env ? process.env[notify.token_env] : undefined;
-    const kind = d.kind ?? { decision: 'ask', explainer: d.options.length ? 'ask' : 'report' }[d.type] ?? d.type;
-    const body = JSON.stringify({ v: 1, source: 'sign-off', id: d.key, kind: ['ask', 'plan', 'design', 'evidence', 'report'].includes(kind) ? kind : 'ask',
-        title: [...d.title].slice(0, 120).join(''), text: [...(d.about ?? d.detail ?? d.why ?? d.title).replace(/[\r\n]+/g, ' ')].slice(0, 200).join(''),
-        url: `${notify.link_base.replace(/\/$/, '')}#waiting/${encodeURIComponent(d.key)}`, at: d.filed ?? new Date().toISOString() });
-    const child = spawn(process.execPath, ['-e', NOTIFY_SENDER], { detached: true, stdio: 'ignore', env: { ...process.env, SIGN_OFF_NOTIFY_URL: notify.url, SIGN_OFF_NOTIFY_BODY: body, SIGN_OFF_NOTIFY_TOKEN: token ?? '', SIGN_OFF_NOTIFY_ID: d.key, SIGN_OFF_NOTIFY_LOG: join(so, 'notify.log') } });
+    const child = spawn(process.execPath, ['-e', NOTIFY_SENDER], { detached: true, stdio: 'ignore', env: { ...process.env, SIGN_OFF_NOTIFY_URL: notify.url, SIGN_OFF_NOTIFY_BODY: JSON.stringify(noticeBody(notify, d)), SIGN_OFF_NOTIFY_TOKEN: notify.muxr ? '' : token ?? '', SIGN_OFF_NOTIFY_TOKEN_FILE: notify.muxr ? muxrTokenFile() : '', SIGN_OFF_NOTIFY_ID: d.key, SIGN_OFF_NOTIFY_LOG: join(so, 'notify.log') } });
     child.on('error', () => warn(`notification sender could not start for card ${d.key}`));
     child.unref();
 }
@@ -1707,7 +1765,7 @@ function init(args) {
     }
     catch { }
     const files = [
-        [join(so, 'config.yaml'), `# sign-off repo setup. board: path under .sign-off/, port: dashboard port, agent: auto or the coding agents to install the skill for.\n# bind: 127.0.0.1 keeps the dashboard on this machine; a private address such as its VPN address lets a phone open it.\n# hosts: (optional) private DNS names that lead to that address, such as its mesh VPN name, commas between them.\n# on_answer: (optional) a command run for each answer, with the answer as one JSON line on its stdin; no shell, so | > && do nothing: on_answer: node hook.mjs\nboard: decisions.json\nport: 4410\nbind: 127.0.0.1\nagent: ${agent}\n`],
+        [join(so, 'config.yaml'), `# sign-off repo setup. board: path under .sign-off/, port: dashboard port, agent: auto or the coding agents to install the skill for.\n# bind: 127.0.0.1 keeps the dashboard on this machine; a private address such as its VPN address lets a phone open it.\n# hosts: (optional) private DNS names that lead to that address, such as its mesh VPN name, commas between them.\n# on_answer: (optional) a command run for each answer, with the answer as one JSON line on its stdin; no shell, so | > && do nothing: on_answer: node hook.mjs\n# name: (optional) your name, shown on the board. leash: how much agents may do without asking: ask, matters (the default) or act; the board's Leash control sets it.\nboard: decisions.json\nport: 4410\nbind: 127.0.0.1\nagent: ${agent}\n`],
         [board, `{"schema": 2, "items": []}\n`],
         [join(so, '.gitignore'), GITIGNORE],
     ];
@@ -1779,6 +1837,43 @@ function report(args) {
             : `Run \`sign-off-axi post <board.json> --type report --title "<the answer>" --about "<why it matters>" --view <path>/index.html --preview <path>/preview.svg\`, both paths from the board file's folder, which must hold this folder`,
     ]);
 }
+/** `notify check|test`: whether device notifications can work from this setup, and one real test notice. Never prints the token. */
+async function notify(args) {
+    const mode = ['check', 'test'].includes(args[0]) ? args.shift() : 'check';
+    const { dir: folder, given } = repoDir('notify', args), dir = given ? folder : setupFolderHere() ?? folder, so = join(dir, '.sign-off');
+    let setup;
+    try {
+        setup = readSetup(so);
+    }
+    catch {
+        throw fail(`no readable config.yaml in ${tilde(so)}`, 'NOT_FOUND', `Run \`sign-off-axi init ${shellPath(dir)}\``);
+    }
+    const config = shellPath(join(so, 'config.yaml'));
+    if (setup.problems.some((p) => p.startsWith('notify')))
+        throw fail(`the notify: block in ${tilde(join(so, 'config.yaml'))} cannot be used: ${setup.problems.filter((p) => p.startsWith('notify')).join('; ')}`, 'VALIDATION_ERROR', `Edit ${config}, then run \`sign-off-axi notify\` again`);
+    const n = setup.notify;
+    if (!n)
+        return toon({ notifications: 'off' }, [`Ask the user once whether they want device notifications; if yes, add \`notify:\`, \`  receiver: muxr\` and \`  link_base: <the board's https or tailnet address>\` lines to ${config}`]);
+    const why = tokenMissing(n);
+    if (why)
+        throw fail(`notifications are on but cannot send: ${why}`, 'NOT_FOUND', n.muxr ? 'Update the muxr host so it writes its notify-token file, then run `sign-off-axi notify test`' : `Export ${n.token_env} with the receiver's token`);
+    if (mode === 'check')
+        return toon({ notifications: 'on', receiver: n.muxr ? 'muxr' : 'webhook', url: n.url, link_base: n.link_base, token: n.muxr ? tilde(muxrTokenFile()) : `$${n.token_env ?? '(none)'}` }, ['Run `sign-off-axi notify test` to send one real test notice']);
+    const probe = { key: 'sign-off-test', title: 'sign-off test', about: 'Device notifications from sign-off work.', type: 'decision', options: [] };
+    let status;
+    try {
+        const token = n.muxr ? readFileSync(muxrTokenFile(), 'utf8').trim() : n.token_env ? process.env[n.token_env] : undefined;
+        status = (await fetch(n.url, { method: 'POST', headers: { 'content-type': 'application/json', ...(token && { authorization: `Bearer ${token}` }) }, body: JSON.stringify(noticeBody(n, probe)), signal: AbortSignal.timeout(10000) })).status;
+    }
+    catch {
+        throw fail(`nothing answered at ${n.url}`, 'NOT_FOUND', n.muxr ? 'Start the muxr host on this machine, then run `sign-off-axi notify test` again' : 'Check the url: line, then run `sign-off-axi notify test` again');
+    }
+    if ([401, 403].includes(status))
+        throw fail(`the receiver refused the token (HTTP ${status})`, 'VALIDATION_ERROR', n.muxr ? `Check that ${tilde(muxrTokenFile())} holds the token the muxr host expects` : `Check ${n.token_env}`);
+    if (status >= 300)
+        throw fail(`the receiver answered HTTP ${status}, so the test notice was not accepted`, 'VALIDATION_ERROR', 'Check the receiver is the notification endpoint');
+    return toon({ notifications: 'on', test: 'sent', http: status }, ['Check the device for the "sign-off test" notice']);
+}
 async function doctor(args) {
     const { dir: folder, given } = repoDir('doctor', args), dir = given ? folder : setupFolderHere() ?? folder, so = join(dir, '.sign-off'), rerun = `sign-off-axi init ${shellPath(dir)}`;
     const checks = [];
@@ -1846,8 +1941,9 @@ async function doctor(args) {
                     check('config', `board ${basename(board)}, port ${port}`);
                 else
                     check('config', `${basename(config)}: ${setup.problems.join('; ')}`, `Edit ${shellPath(config)} to hold "board: <name>.json", "port: <0-65535>" and "bind: <127.0.0.1 or a private address>" lines, such as board: decisions.json, port: 4410 and bind: 127.0.0.1, and hosts: only DNS names${setup.goodBoard ? '' : `, or delete it and run \`${rerun}\``}`);
-                if (setup.notify?.token_env && !process.env[setup.notify.token_env])
-                    check('notify', `${setup.notify.token_env} is not set, so no notice is sent`, `Export ${setup.notify.token_env} with the receiver's token`);
+                const why = setup.notify && tokenMissing(setup.notify);
+                if (setup.notify && why)
+                    check('notify', `${why}, so no notice is sent`, setup.notify.muxr ? 'Update the muxr host so it writes its notify-token file, then run `sign-off-axi notify test`' : `Export ${setup.notify.token_env} with the receiver's token`);
                 // A hosts: name is only of use when it leads to the bind address.
                 const astray = [];
                 for (const h of setup.hosts) {
@@ -1972,11 +2068,12 @@ async function doctor(args) {
         throw fail(`${bad.length} of ${checks.length} checks need a fix in ${tilde(dir)}`, 'NOT_FOUND', ...bad.map((c) => `${c.name}: ${c.ok}. ${c.fix}`));
     return toon({ dir: tilde(dir), checks: checks.map(({ name, ok }) => ({ name, ok })) }, [`Run \`sign-off-axi open ${shellPath(board)}\` to show the board to the user`]);
 }
-let file = '', evidenceRoot = '', bind = '127.0.0.1', hosts = [], onAnswer = [];
+let file = '', config = '', evidenceRoot = '', bind = '127.0.0.1', hosts = [], onAnswer = [];
 async function serve(args) {
     const parsed = parse('serve', args, BOARD_FLAGS), port = boardPort(parsed.named, parsed.values.port);
     ready(parsed.file, parsed.on, parsed.values['evidence-root']);
     bind = bindOf(parsed.named, parsed.values.bind);
+    config = join(dirname(parsed.named), 'config.yaml');
     ({ hosts = [], onAnswer = [] } = setupOf(parsed.named) ?? {});
     let warned = false;
     const sweep = async (phase) => {
@@ -1994,6 +2091,7 @@ async function serve(args) {
             tokenOf(parsed.file, true);
         await sweep('startup');
         [file, evidenceRoot] = [parsed.file, parsed.values['evidence-root'] ? resolve(parsed.values['evidence-root']) : ''];
+        guardReady = warmGuard();
         await new Promise((ok, no) => server.once('error', no).listen(port, bind, ok)).catch((e) => {
             throw fail(e.code === 'EADDRINUSE' ? `port ${port} is in use; pass --port` : e.code === 'EADDRNOTAVAIL' ? `${bind} is not an address of this machine; pass another --bind` : e.message, 'SERVE_FAILED', 'Run `sign-off-axi --help` for the flags, then start it again');
         });
@@ -2048,6 +2146,9 @@ async function exportBoard(args) {
     const parsed = parse('export', args, { out: { type: 'string' }, 'evidence-root': { type: 'string' } });
     ready(parsed.file, parsed.on, parsed.values['evidence-root']);
     [file, evidenceRoot] = [parsed.file, parsed.values['evidence-root'] ? resolve(parsed.values['evidence-root']) : ''];
+    config = join(dirname(parsed.named), 'config.yaml');
+    guardReady = warmGuard();
+    await guardReady;
     const { file: _, messages: _messages, annotations: _annotations, ...frozen } = state(), files = {}, q = encodeURIComponent;
     let missing = 0;
     // The same URLs the page asks the server for, read through the same hash and path checks.
@@ -2094,19 +2195,92 @@ const sha256 = (bytes) => createHash('sha256').update(bytes).digest('hex');
 /** A card whose picture is a colour-bar test card or a placeholder is not shown: a card posted before the guard can hold one. Read by the
  * stored hash, so each picture is measured once. */
 const unfitMedia = new Map();
-const fakeEvidence = (d) => d.type === 'evidence' && (d.media ?? []).some((m) => {
-    if (!unfitMedia.has(m.sha256)) {
-        let found;
+const fakeEvidence = (d) => d.type === 'evidence' && (d.media ?? []).some((m) => isStill(m.path) && unfitMedia.get(m.sha256) === true);
+/** Every still on the board, once, so a request never walks the media: the board's files are hash-checked and immutable. */
+const stillJobs = () => {
+    const jobs = [], seen = new Set();
+    for (const d of loadDecisions(file)) {
+        if (d.type !== 'evidence')
+            continue;
+        for (const m of d.media ?? []) {
+            if (!isStill(m.path) || seen.has(m.sha256) || unfitMedia.has(m.sha256))
+                continue;
+            seen.add(m.sha256);
+            try {
+                jobs.push({ path: under(dirname(file), m.path), sha256: m.sha256 });
+            }
+            catch { /* an absent file has no faults */ }
+        }
+    }
+    return jobs;
+};
+/** Measures the board's stills in parallel and off the request path. A fresh board is therefore ready before it is asked for cards: the
+ * page and media answer at once, and the guard's pass never blocks them. One follow-up pass takes whatever a lost worker never reported. */
+let guardReady = Promise.resolve();
+/** A board read waits this long for the warm pass, so a still that is slow or stuck never holds the cards. */
+const GUARD_WAIT = 500;
+/** A worker still measuring after this is stuck in a convert that outlived its own timeout: it is stopped and its stills stay unmeasured. */
+const WORKER_WAIT = 35_000;
+const warmGuard = () => new Promise((done) => {
+    const pass = (retry) => {
+        let jobs;
         try {
-            found = faults(under(dirname(file), m.path)).some((f) => f !== 'text');
+            jobs = stillJobs();
         }
         catch {
-            return false;
+            return done();
+        }
+        if (!jobs.length)
+            return done();
+        const workers = Math.max(1, Math.min(8, availableParallelism(), jobs.length));
+        let left = workers;
+        const ended = () => {
+            if (--left)
+                return;
+            if (retry)
+                pass(false);
+            else
+                done();
+        };
+        for (let i = 0; i < workers; i++) {
+            let worker;
+            try {
+                worker = new Worker(new URL('./stills-worker.js', import.meta.url), { workerData: jobs.filter((_, j) => j % workers === i) });
+            }
+            catch {
+                ended();
+                continue;
+            }
+            let stop;
+            const arm = () => {
+                clearTimeout(stop);
+                stop = setTimeout(() => { void worker.terminate(); }, WORKER_WAIT);
+                stop.unref();
+            };
+            arm();
+            worker.on('message', ([sha, unfit]) => { unfitMedia.set(sha, unfit); arm(); });
+            worker.once('error', () => clearTimeout(stop));
+            worker.once('exit', () => { clearTimeout(stop); ended(); });
         }
-        unfitMedia.set(m.sha256, found);
-    }
-    return unfitMedia.get(m.sha256);
+    };
+    pass(true);
 });
+/** How much agents may do without asking, from the leash: line of config.yaml: ask (wait on every ask), matters (take the default at the
+ * silent-by time, the default) or act (take the recommended pick now and report it). With the name: line it is the page's only setting. */
+const LEASHES = ['ask', 'matters', 'act'];
+const configLine = (text, key) => new RegExp(`^[ \\t]*${key}[ \\t]*:([^#\\n]*)`, 'm').exec(text)?.[1].trim() || undefined;
+/** The user's name and leash; none for a board with no config.yaml beside it. */
+function profile() {
+    let text;
+    try {
+        text = readFileSync(config, 'utf8');
+    }
+    catch {
+        return {};
+    }
+    const leash = configLine(text, 'leash') ?? '';
+    return { name: configLine(text, 'name')?.slice(0, 40), leash: LEASHES.includes(leash) ? leash : 'matters' };
+}
 const state = () => {
     reap();
     // The page marks sent comments in annotations, so answers and rounds go without theirs: a read-only board or an export carries none.
@@ -2121,6 +2295,7 @@ const state = () => {
             ...(d.mocks && { mocks: d.mocks.map((m) => ({ ...m, hash: mockHash(m.path) })) }) })),
         readonly: readOnly(),
         answers_only: answersOnly(),
+        ...profile(),
         answers,
         seen: Object.values(answers).filter(taken).map((a) => a.key),
         rounds,
@@ -2292,9 +2467,12 @@ async function route(req) {
     if (req.method === 'GET' && req.url === '/api/board')
         return [200, { file, pid: process.pid }];
     if (req.method === 'GET' && req.url === '/api/decisions') {
+        let timer;
+        await Promise.race([guardReady, new Promise((ok) => { timer = setTimeout(ok, GUARD_WAIT); })]);
+        clearTimeout(timer);
         return [200, state()];
     }
-    if (req.method !== 'POST' || !['/api/answers', '/api/rounds', '/api/messages', '/api/annotations', '/api/dismiss', '/api/signin'].includes(req.url ?? ''))
+    if (req.method !== 'POST' || !['/api/answers', '/api/rounds', '/api/messages', '/api/annotations', '/api/dismiss', '/api/signin', '/api/leash'].includes(req.url ?? ''))
         return [404, { error: 'Not found' }];
     if (readOnly())
         return [403, { error: 'This board is read-only' }];
@@ -2362,6 +2540,21 @@ async function route(req) {
             return board(file).find((x) => x.key === key)?.answer ? [200, { state: state() }] : [502, { error: e.message, state: state() }];
         }
     }
+    if (req.url === '/api/leash') {
+        const { leash } = JSON.parse(body) ?? {};
+        if (!LEASHES.includes(leash))
+            return [400, { error: `Send a leash of ${LEASHES.join(', ')}` }];
+        let text;
+        try {
+            text = readFileSync(config, 'utf8');
+        }
+        catch {
+            return [409, { error: 'This board has no config.yaml to keep the leash in; run sign-off-axi init' }];
+        }
+        const line = /^[ \t]*leash[ \t]*:.*$/m;
+        writeFileSync(config, line.test(text) ? text.replace(line, `leash: ${leash}`) : `${text.replace(/\n?$/, '\n')}leash: ${leash}\n`);
+        return [200, state()];
+    }
     if (req.url === '/api/dismiss') {
         const { keys, dismissed } = JSON.parse(body) ?? {};
         if (!Array.isArray(keys) || !keys.length || keys.length > 200 || typeof dismissed !== 'boolean')
@@ -2369,8 +2562,6 @@ async function route(req) {
         const have = new Map(board(file).map((x) => [x.key, x]));
         if (!keys.every((k) => isKey(k) && have.has(k)))
             return [404, { error: 'This item is no longer in the file' }];
-        if (dismissed && keys.some((k) => have.get(k)?.type === 'plan' && !have.get(k)?.answer))
-            return [400, { error: 'A plan waits until it is sent back, so it cannot be dismissed' }];
         appendDismissed(file, [...new Set(keys)], dismissed);
         return [200, state()];
     }
@@ -2597,7 +2788,7 @@ await runAxiCli({
     topLevelHelp: TOP_HELP,
     getCommandHelp: (cmd) => HELP[cmd],
     home: axi('list', list),
-    commands: { list: axi('list', list), raise: axi('raise', (args) => post(args, 'raise')), post: axi('post', post), answers: axi('answers', answers), wait: axi('wait', wait), poll: axi('poll', poll), open: axi('open', open), status: axi('status', status), stop: axi('stop', stop), serve: axi('serve', serve), export: axi('export', exportBoard), init: axi('init', init), report: axi('report', report), signin: axi('signin', signin), doctor: axi('doctor', doctor), validate, help: ([name, ...rest]) => {
+    commands: { list: axi('list', list), raise: axi('raise', (args) => post(args, 'raise')), post: axi('post', post), answers: axi('answers', answers), wait: axi('wait', wait), poll: axi('poll', poll), open: axi('open', open), status: axi('status', status), stop: axi('stop', stop), serve: axi('serve', serve), export: axi('export', exportBoard), init: axi('init', init), report: axi('report', report), signin: axi('signin', signin), doctor: axi('doctor', doctor), notify: axi('notify', notify), validate, help: ([name, ...rest]) => {
             if (rest.length || (name && !HELP[name]))
                 throw fail(`unknown command or argument: ${[name, ...rest].join(' ')}`, 'VALIDATION_ERROR', 'Run `sign-off-axi --help` to see the commands');
             return name ? HELP[name] : TOP_HELP;