sign-off-axi 0.5.2 → 0.5.3

package/README.md

@@ -7,6 +7,8 @@
 
 <h1 align="center">sign-off</h1>
 
+Guided plans and reports now offer **Simplify this** under each part (and for any words you select inside one paragraph): the same owner explains it in place, with pending and persistent **New** states. New defaults require a filer; older documents still load. [Owner setup and engagement contract](docs/contract.md#report-schema-4-and-plan-schema-3-engagement-v1).
+
 <p align="center"><b>One calm page for every question the programs working for you need answered.</b><br>Agents ask; you answer with one tap on your own machine; the answer is saved for the asker to read. Proof of finished work lands on the same page, so you check it instead of taking anyone's word.</p>
 
 <p align="center"><b>▶ <a href="https://umeranjum17.github.io/sign-off/demo/">Try it live</a></b>: the real board on demo data. No install, nothing leaves your browser. · <a href="https://umeranjum17.github.io/sign-off/">Website</a></p>
@@ -29,7 +31,7 @@ sign-off-axi open                    # 3. start the board and open the printed l
 Then ask your first question, the way an agent would, and answer it on the board:
 
 ```sh
-sign-off-axi raise \
+sign-off-axi raise --ask-ref message-example \
   --title "Keep the weekly digest?" \
   --why "The paid plan renews Monday." \
   --outcome yes="It keeps going out." --outcome no="It stops this week." \
@@ -83,7 +85,7 @@ One line on what the agent runs per kind; the full reference is [docs/question-k
 
 | Kind | The agent runs | You see |
 |---|---|---|
-| Yes or no, pick one | `raise --title ... --recommend ...` | buttons, the recommended one first |
+| Yes or no, pick one | `raise --ask-ref <captain-message-id-or-hold-id> --title ... --recommend ...` | buttons, the recommended one first |
 | Design pick (mocks A/B/C) | `post --type design --mock a=... --mock b=... --link a=<url>` | mocks side by side, an Open live link under each option that has a `--link`, a note on any part |
 | Proof update | `post --type evidence --media shot.png` | the capture, its result, Pass / Fail / Needs work |
 | Proof with a file to install | `post --type evidence --media shot.png --attach app.apk` | the capture, and the file with its size and a Download button (any type, up to 1 GB, `SIGN_OFF_ATTACH_MAX_MB` to change) |
@@ -97,7 +99,9 @@ One line on what the agent runs per kind; the full reference is [docs/question-k
 
 Every item records who filed it. The agent raises with `--filer my-agent`, then blocks on `sign-off-axi wait --filer my-agent`, which returns that filer's answers, each once, and the card shows **Seen by agent**. An agent that 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, and a `notify:` block can send an HTTP POST when a card enters Decide. The worked examples are in [docs/commands.md](docs/commands.md).
 
-sign-off itself calls no model and inherits the calling agent's model routing. The shipped skill is deliberately thin: it tells the agent how to write a good card and defers to `sign-off-axi --help` for every flag, so an installed copy never goes stale.
+For Go deeper on a guided plan or report, an idle **Claude Code** author can opt in to native session resumption: register its actual UUID with `owner --filer <id> --host claude --session <UUID> --cwd <absolute project folder>`, then run a separate `owner --dispatch --timeout 3600` process for the same board. `owner` shows queued delivery failures and distinguishes delivered from owner-read. No Firstmate is needed; other hosts are not supported for this wake path. See the [standalone owner recipe](docs/commands.md#standalone-go-deeper-owner).
+
+Each ordinary sign-off command calls no model; the opt-in dispatcher invokes the installed Claude Code with its normal credentials and optional registered model. The shipped skill is deliberately thin: it tells the agent how to write a good card and defers to `sign-off-axi --help` for every flag, so an installed copy never goes stale.
 
 ## Works alone, or with its siblings
 
@@ -150,7 +154,7 @@ always wins.
 tmp=$(mktemp -d)
 export SIGN_OFF_HOME="$tmp"
 (cd "$tmp" &&
-  sign-off-axi raise \
+  sign-off-axi raise --ask-ref message-example \
   --title "Probe?")
 ```
 

package/dist/cli.js

@@ -11,8 +11,9 @@ import { pipeline } from 'node:stream';
 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 { acknowledgeOwner, checkOwner, deliveries, dispatchOwners, registerOwner } from './owner.js';
 import { AxiError, runAxiCli } from 'axi-sdk-js';
-import { ATTACH_DEFAULT_MB, ATTACH_MAX, ATTACH_NAME, CHAPTERS_MAX, SIGNED_IN, CLEARED, InputError, MEDIA_MAX, NOTE_MAX, REPLY, answersPath, appendAnnotation, asks, appendAnswer, appendDismissed, appendSendBack, appendDesignAnswer, appendMessage, appendRound, awaitsVerdict, appendRead, answerDeeper, askDeeper, deeperPath, guidePart, markDeeperRead, readDeeper, readReads, seenAt, isKey, loadDecisions, markDelivered, markSeen, messagesPath, readAnnotations, readAnswers, readDismissed, readItems, sameDecision, readMessages, readRounds, roundsPath, seenBy, seenPath, sentIds, unreadable as reasonOf, writeItems } from './store.js';
+import { ATTACH_DEFAULT_MB, ATTACH_MAX, ATTACH_NAME, CHAPTERS_MAX, SIGNED_IN, CLEARED, InputError, MEDIA_MAX, NOTE_MAX, REPLY, answersPath, appendAnnotation, asks, appendAnswer, appendDismissed, appendSendBack, appendDesignAnswer, appendMessage, appendRound, awaitsVerdict, lapsed, askEngagement, checkEngagement, markEngagementSeen, appendRead, answerDeeper, askDeeper, deeperPath, guidePart, markDeeperRead, readDeeper, readReads, seenAt, isKey, loadDecisions, markDelivered, markSeen, messagesPath, readAnnotations, readAnswers, readDismissed, readItems, sameDecision, readMessages, readRounds, roundsPath, seenBy, seenPath, sentIds, unreadable as reasonOf, writeItems } from './store.js';
 import { ContractError, KINDS, MEDIA_BYTES, REPORT_INIT, checkMessage, guided, mediaFiles, parseMessage, reportPage } from './contract.js';
 import { faults, isStill } from './evidence-text.js';
 import { deliverVault, errors, readVaultExpiry, sweepVault, takeVaultExpiries, VaultError } from './vault.js';
@@ -29,13 +30,13 @@ 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[22]:
-  (none)=list, raise, post, answers, wait, poll, deeper, open, status, stop, serve, export, init, report, signin, dismiss, restore, refile, doctor, notify, validate, help
+commands[23]:
+  (none)=list, raise, post, answers, wait, poll, deeper, owner, open, status, stop, serve, export, init, report, signin, dismiss, restore, refile, 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:
   sign-off-axi
-  sign-off-axi raise --title "Ship the new sign-in screen this week?" --why "The screen is ready; the release goes out Friday." --outcome yes="It ships Friday." --outcome no="It waits a week." --recommend yes --recommend-reason "Tests pass on every phone." --default no
+  sign-off-axi raise --ask-ref message-example --title "Ship the new sign-in screen this week?" --why "The screen is ready; the release goes out Friday." --outcome yes="It ships Friday." --outcome no="It waits a week." --recommend yes --recommend-reason "Tests pass on every phone." --default no
   sign-off-axi post --type evidence --title "Sign-in screen on a phone" --about "The new screen loads in 1 second." --media shot.png
   sign-off-axi post .sign-off/decisions.json --type design --title "Pick the sign-in layout" --option a=A --option b=B --mock a=mocks/a.html --mock b=mocks/b.html --recommend b
   sign-off-axi post .sign-off/decisions.json --type diagram --title "Is this the sign-in flow?" --view mocks/sign-in/flow.svg
@@ -72,6 +73,9 @@ examples:
        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.
+New Decide questions require --ask-ref <captain-message-id-or-hold-id>, saved as ask_ref (1-256 characters, no whitespace or controls).
+For --kind ask or a feed, put ask_ref in the message, or pass --ask-ref. Existing cards need no new reference.
+Follow-ups belong in the backlog, not the board. Plans, reports, evidence and engagement records are unchanged.
 Every question meets the question standard (docs/contract.md, "Asking a good question"); a question that does not is refused with the field and one fix line:
   --title is one plain question the buttons answer: it ends in "?", has 12 words or fewer, no "Say yes or no:", "Captain hold:" or "Captain:" prefix and no key-like word.
   --why says what it is about and why it needs an answer now (200 characters or fewer).
@@ -90,8 +94,8 @@ Raising the same question again is a no-op that reports its status; a different
 --filer names who asks (your agent session or any id of 1-128 of A-Z a-z 0-9 . _ -), saved on the item so \`wait --filer\` with the same 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.
 examples:
-  sign-off-axi raise --title "Keep the weekly digest?" --why "Open rate held steady; the paid plan ends Monday." --outcome yes="It keeps going out each Monday." --outcome no="It stops after this week." --recommend yes --recommend-reason "Readers still open it." --default yes --silent-by 2026-10-19T09:00Z
-  sign-off-axi raise --title "Which day should the release ship?" --why "Two fixes are still in review." --option a="A: Today" --option b="B: Friday" --option c="C: Next week" --outcome a="Ships now without the fixes." --outcome b="Ships with both fixes." --outcome c="Ships with the redesign too." --recommend b --recommend-reason "Both fixes land by Thursday." --default b --merge release-day
+  sign-off-axi raise --ask-ref message-example --title "Keep the weekly digest?" --why "Open rate held steady; the paid plan ends Monday." --outcome yes="It keeps going out each Monday." --outcome no="It stops after this week." --recommend yes --recommend-reason "Readers still open it." --default yes --silent-by 2026-10-19T09:00Z
+  sign-off-axi raise --ask-ref message-example --title "Which day should the release ship?" --why "Two fixes are still in review." --option a="A: Today" --option b="B: Friday" --option c="C: Next week" --outcome a="Ships now without the fixes." --outcome b="Ships with both fixes." --outcome c="Ships with the redesign too." --recommend b --recommend-reason "Both fixes land by Thursday." --default b --merge release-day
   sign-off-axi raise --from ./decisions.json
 `,
     validate: `usage: sign-off-axi validate <message.json>... [--kind <kind>] [--expect-invalid]
@@ -135,14 +139,16 @@ 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 still needs an answer. Without --filer or SIGN_OFF_FILER, wait takes no filer
+             guided plans and reports keep listening for Go deeper, even after send-back; otherwise NOT_FOUND when none needs an answer.
+             Without --filer or SIGN_OFF_FILER, wait takes no filer and never consumes Go deeper
   --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 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
-  --events   needs --filer (or SIGN_OFF_FILER); one JSON line per new answer and per another-round ask, in the order they were saved (${CONTRACT}#7-answers):
+  --events   needs --filer (or SIGN_OFF_FILER); JSON lines for new answers, another-round asks and Go deeper (each wait returns one batch).
+             Answer and round lines come in the order they were saved (${CONTRACT}#7-answers):
              {"event":"answer","contract":1,"kind","schema","key","title","answer","label","close","at","note"?,"filer"?,"comments"?}
              {"event":"round","contract":1,"kind","schema","key","title","note","at","filer"?,"comments"?}; a board-format item reports as ask schema 1
 A note column appears when any shown answer has a note.
@@ -191,7 +197,8 @@ examples:
        sign-off-axi post [board.json] --type report --title "<the answer>" --about "<why it matters>" --view <page.html> --preview <picture> [--key <key>] [--link <commit or URL>] [--filer <id>]
        sign-off-axi post [board.json] --type signin --service "<name>" --link <sign-in URL> --unlocks "<what it unlocks>" --waits "<who waits>" [--expires <ISO time or 15m>] [--key <key>] [--filer <id>]
        sign-off-axi post [board.json] --type signin --service "<name>" --start '<command as a JSON list>' --unlocks "<what it unlocks>" --waits "<who waits>" [--key <key>] [--filer <id>]
-Posts an item for the user. --type decision (the default) is a yes/no or pick-one question, exactly like raise, with the same question standard and flags (--why, --outcome, --recommend-reason, --silent-by, --merge).
+Posts an item for the user. --type decision (the default) is a yes/no or pick-one question, exactly like raise, with the same question standard and flags (--ask-ref, --why, --outcome, --recommend-reason, --silent-by, --merge).
+A new Decide question requires --ask-ref <captain-message-id-or-hold-id> (ask_ref in a message or feed); follow-ups belong in the backlog, not the board. Existing cards, plans, reports, evidence and engagement records are unchanged.
 --kind posts one contract message (${CONTRACT}), read from a file or from stdin with --from -: it must be that kind and pass every rule,
 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;
@@ -239,7 +246,7 @@ within 20 seconds, shows on the card and Open can try again. It is stopped after
 examples:
   sign-off-axi post --type design --title "Pick the sign-in layout" --option a="A: single column" --option b="B: split screen" --mock a=mocks/a.html --mock b=mocks/b.html --tradeoff "B scans fastest; A is simplest." --recommend b
   sign-off-axi post .sign-off/decisions.json --type design --key sign-in --title "Pick the sign-in layout" --option a=A --option b=B --option c=C --mock a=mocks/sign-in/index.html?variant=a --mock b=mocks/sign-in/index.html?variant=b --mock c=mocks/sign-in/index.html?variant=c --tradeoff "..." --recommend b
-  sign-off-axi post --type decision --title "Keep the weekly digest?" --why "Open rate held steady." --outcome yes="It keeps going out." --outcome no="It stops this week." --recommend yes --recommend-reason "Readers still open it." --default yes
+  sign-off-axi post --type decision --ask-ref message-example --title "Keep the weekly digest?" --why "Open rate held steady." --outcome yes="It keeps going out." --outcome no="It stops this week." --recommend yes --recommend-reason "Readers still open it." --default 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
@@ -308,9 +315,20 @@ examples:
   sign-off-axi init ./my-project --agent opencode
   sign-off-axi init --agent codex,gemini-cli
 `,
+    owner: `usage: sign-off-axi owner [board.json] --filer <id> --host claude --session <UUID> --cwd <absolute folder> [--model <id>]
+       sign-off-axi owner [board.json] --dispatch [--filer <id>] [--timeout <seconds>] [--verbose]
+       sign-off-axi owner [board.json] --ack <request id>
+       sign-off-axi owner [board.json]
+Register the actual author session locally, never in document JSON. Only Claude Code is supported.
+--dispatch retries unfinished Go deeper requests, once by default; --timeout keeps polling for that many seconds.
+--verbose writes the real host result to stderr for local diagnostics.
+The dispatcher uses the normal installed claude and its credentials, argv only, and resumes the exact session.
+Run one dispatcher per board, separately from the idle owner. Leave inaccessible owners queued; inspect delivery errors with owner.
+Delivered means process handoff, not read. The resumed owner must --ack before answering once, without --more.
+Do not run an active wait listener for the same owner alongside the dispatcher. No substitute answers.`,
     deeper: `usage: sign-off-axi deeper [board.json] [--filer <id>] [--all] [--json]
-       sign-off-axi deeper [board.json] --id <id> --text "<answer>" [--more]
-Go deeper is the button on every part of a plan 2 or report 3. The person taps it; wait --filer wakes with the ask, or this command lists the ones nobody finished.
+       sign-off-axi deeper [board.json] --filer <id> --id <id> --text "<answer>" [--more]
+Every part of a plan 3 or report 4 offers Ask a question, Go deeper, Simplify this, Show an example, Why?, and free text. Ask a question needs text and Send; Go deeper, Simplify this, Show an example and Why? send immediately. Free text and follow-ups use custom. Older guided schemas retain Go deeper. Engagement v1 replies require the owning --filer or registered owner session; stale targets are refused. The person taps it; wait --filer wakes with the ask, or this command lists the ones nobody finished.
 Answer in plain words about the part they tapped, a few lines at a time: each --more piece streams into that spot on the board while they watch, and a last call without --more ends it.
   --id     the ask to answer   --text  the answer, or - to read stdin (2000 characters or fewer per piece)
   --more   more pieces follow   --all  also the finished asks
@@ -549,8 +567,8 @@ 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, not dismissed, and something to answer (an item with no options and no reply is only shown). */
-const waits = (d) => asks(d) && !d.dismissed && awaitsVerdict(d.type, d.answer);
+/** Still waiting on the user: not answered, not dismissed, not an expired sign-in, and something to answer (an item with no options and no reply is only shown). */
+const waits = (d) => asks(d) && !lapsed(d) && !d.dismissed && awaitsVerdict(d.type, d.answer);
 /** The items that archive after a day: all of them, except on a board another program feeds, which owns what it shows. */
 const archivable = (file, decisions) => ((x) => (x.readonly === true || x.answers_only === true ? [] : decisions))(readItems(file).extra);
 /** The board's decisions with their latest answer; a missing board file is an empty board.
@@ -659,12 +677,40 @@ function eventLines(file, rows, answers, rounds) {
 function deeperOut(file, asks, on, events) {
     if (events) {
         const kind = kindOf(file), titles = new Map(board(file).map((d) => [d.key, d.title]));
-        return asks.map(({ id, key, part, about, q, at }) => JSON.stringify({ event: 'deeper', ...kind(key), key, title: titles.get(key), id, part, about, ...(q && { q }), at })).join('\n');
+        return asks.map(({ id, key, part, about, q, at, ...rest }) => JSON.stringify({ event: 'deeper', ...kind(key), key, title: titles.get(key), id, part, about, ...(q && { q }), at, ...(rest.version === 1 && rest) })).join('\n');
     }
-    return toon({ board: tilde(file), deeper: asks.map(({ id, key, part, about, q = '', at }) => ({ id, key, part, about, q, at })) }, ['The person tapped Go deeper: answer in plain words, a few lines at a time, as the part they tapped',
+    return toon({ board: tilde(file), deeper: asks.map(({ id, key, part, about, q = '', at, action }) => ({ id, key, part, about, q, at, ...(action && { action }) })) }, ['The person tapped Go deeper: answer in plain words, a few lines at a time, as the part they tapped',
         `Run \`sign-off-axi deeper${on} --id <id> --text "<what you found>" --more\` for each piece, then once more without --more to finish`]);
 }
 /** `deeper`: the Go deeper asks nobody has finished, or with --id and --text one piece of the answer the board streams under the part the person tapped. */
+async function owner(args) {
+    const { file, values } = parse('owner', args, { filer: { type: 'string' }, host: { type: 'string' }, session: { type: 'string' }, cwd: { type: 'string' }, model: { type: 'string' }, dispatch: { type: 'boolean' }, verbose: { type: 'boolean' }, ack: { type: 'string' }, timeout: { type: 'string' } });
+    ready(file, '');
+    if (values.ack !== undefined) {
+        acknowledgeOwner(file, values.ack);
+        markDeeperRead(file, [values.ack]);
+    }
+    else if (values.session !== undefined) {
+        const filer = filerOf(values);
+        if (!filer)
+            throw new InputError('Registration needs --filer');
+        await locked(`${file}.owners.lock`, () => registerOwner(file, filer, { host: values.host, session: values.session, cwd: values.cwd, ...(values.model && { model: values.model }) }));
+    }
+    else if (values.dispatch) {
+        if (values.timeout !== undefined && !/^\d{1,7}$/.test(values.timeout))
+            throw new InputError('--timeout must be whole seconds');
+        const until = Date.now() + Number(values.timeout ?? 0) * 1000;
+        await locked(`${file}.dispatch.lock`, async () => {
+            do {
+                await dispatchOwners(file, process.argv[1], filerOf(values), values.verbose);
+                if (Date.now() >= until)
+                    break;
+                await new Promise(ok => setTimeout(ok, 1000));
+            } while (Date.now() < until);
+        }, 'another owner dispatcher is active', 0);
+    }
+    return JSON.stringify({ delivery: deliveries(file) });
+}
 async function deeper(args) {
     const { file, values, on } = parse('deeper', args, { filer: { type: 'string' }, id: { type: 'string' }, text: { type: 'string' }, more: { type: 'boolean' }, all: { type: 'boolean' }, json: { type: 'boolean' } });
     ready(file, on);
@@ -679,11 +725,23 @@ async function deeper(args) {
         if (!open.length)
             return toon({ board: tilde(file), deeper: '0 open' }, [`Run \`sign-off-axi wait${on}\` to be woken when the person taps Go deeper`]);
         markDeeperRead(file, open.filter((x) => !x.read).map((x) => x.id));
-        return toon({ board: tilde(file), deeper: open.map(({ id, key, part, about, q = '', at, done }) => ({ id, key, part, about, q, at, done: !!done })) }, [`Run \`sign-off-axi deeper${on} --id <id> --text "<answer>"\` to answer one`]);
+        return toon({ board: tilde(file), deeper: open.map(({ id, key, part, about, q = '', at, done, action }) => ({ id, key, part, about, q, at, done: !!done, ...(action && { action }) })) }, [`Run \`sign-off-axi deeper${on} --id <id> --text "<answer>"\` to answer one`]);
     }
     const ask = readDeeper(file).find((x) => x.id === values.id);
     if (!ask)
         throw fail(`no Go deeper ask with id ${values.id}`, 'NOT_FOUND', `Run \`sign-off-axi deeper${on}\` to see the open ones`);
+    checkEngagement(file, ask);
+    if (ask.version === 1 && !process.env.SIGN_OFF_OWNER_SESSION && filer !== ask.filer)
+        throw new InputError('Engagement reply requires its owning --filer');
+    if (filer !== undefined && !board(file).some(d => d.key === ask.key && d.filer === filer))
+        throw new InputError('Request does not belong to this filer');
+    if (process.env.SIGN_OFF_OWNER_SESSION) {
+        checkOwner(file, ask);
+        if (ask.done)
+            return toon({ id: ask.id, answered: 'already done' }, []);
+        if (values.more || deliveries(file)[ask.id]?.state !== 'owner-read')
+            throw new InputError('Owner must acknowledge first and send one final answer without --more');
+    }
     if (ask.done)
         throw fail(`ask ${values.id} is already answered`, 'CONFLICT', 'The person can tap Go deeper again for a follow-up');
     let text = values.text;
@@ -691,7 +749,11 @@ async function deeper(args) {
         text = readFileSync(0, 'utf8');
     if (typeof text !== 'string' || !text.trim() || [...text.trim()].length > 2000)
         throw fail('--text must be the answer, 2000 characters or fewer', 'VALIDATION_ERROR', 'Run `sign-off-axi deeper --help`');
-    answerDeeper(file, ask.id, text.trim(), !!values.more);
+    await locked(`${deeperPath(file)}.lock`, () => {
+        checkEngagement(file, ask);
+        if (!process.env.SIGN_OFF_OWNER_SESSION || !readDeeper(file).find(x => x.id === ask.id)?.done)
+            answerDeeper(file, ask.id, text.trim(), !!values.more);
+    });
     return toon({ id: ask.id, key: ask.key, part: ask.part, answered: values.more ? 'piece sent, more to come' : 'done' }, values.more ? [`Run \`sign-off-axi deeper${on} --id ${ask.id} --text "<next piece>" [--more]\``] : [`Run \`sign-off-axi wait${on}\` for the next answer or ask`]);
 }
 async function wait(args) {
@@ -756,12 +818,12 @@ async function wait(args) {
             if (found.length && values.events)
                 return eventLines(file, found, given, asked.filter((r) => fresh.some((d) => d.key === r.key)));
             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`]);
+                return printAnswers(file, found, waiting, values, [waiting ? `Run \`sign-off-axi wait${on}\` for the next of the ${waiting} waiting` : filer !== undefined && rows.some((d) => d.guided) ? `Run \`sign-off-axi wait${on}\` for the next Go deeper ask` : `Run \`sign-off-axi stop${onBoard}\` to close the board`]);
             }
             // A Go deeper ask on this filer's guided page wakes the wait once, and is marked read when it is handed over.
-            if (values.key === undefined) {
+            if (filer !== undefined) {
                 const asks = await locked(`${deeperPath(file)}.lock`, () => {
-                    const got = readDeeper(file).filter((x) => !x.read && rows.some((d) => d.key === x.key));
+                    const got = readDeeper(file).filter((x) => !x.read && !x.done && (values.key === undefined || x.key === values.key) && rows.some((d) => d.key === x.key));
                     markDeeperRead(file, got.map((x) => x.id));
                     return got;
                 }, 'another wait is still taking Go deeper asks');
@@ -797,7 +859,7 @@ async function wait(args) {
                     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) {
+            if (values.key === undefined && !rows.some((d) => waits({ ...d, dismissed: false }) || (filer !== undefined && d.guided)) && !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();
@@ -898,7 +960,7 @@ function post(args, cmd = 'post') {
     const typed = cmd === 'post' ? { replace: { type: 'boolean' }, kind: { type: 'string' }, type: { type: 'string' }, tradeoff: { type: 'string' }, mock: { type: 'string', multiple: true },
         media: { type: 'string', multiple: true }, attach: { type: 'string', multiple: true }, link: { type: 'string', multiple: true }, view: { type: 'string' }, preview: { type: 'string' }, chapter: { type: 'string', multiple: true },
         ...Object.fromEntries(SIGNIN_FIELDS.map((f) => [f, { type: 'string' }])) } : {};
-    const { file, named, values, on } = parse(cmd, args, { from: { type: 'string' }, filer: { type: 'string' }, ...typed,
+    const { file, named, values, on } = parse(cmd, args, { from: { type: 'string' }, filer: { type: 'string' }, 'ask-ref': { type: 'string' }, ...typed,
         ...Object.fromEntries(RAISE_FIELDS.map((f) => [f, { type: 'string', multiple: MANY.includes(f) }])) });
     const given = [...RAISE_FIELDS, 'type', 'tradeoff', 'mock', 'media', 'attach', 'link', 'view', 'preview', 'chapter', ...SIGNIN_FIELDS].filter((f) => values[f] !== undefined);
     // Only a design takes --link more than once (one per option); any other type keeps its one item link, the last given.
@@ -914,7 +976,7 @@ function post(args, cmd = 'post') {
     if (values.from !== undefined && given.length)
         throw fail(`--from cannot be combined with --${given[0]}`, 'VALIDATION_ERROR', `Put every field in the --from file, or ${cmd} with flags only`);
     if (values.replace)
-        return replace(file, named, on, values.from, filerOf(values));
+        return replace(file, named, on, values.from, filerOf(values), values['ask-ref']);
     const filer = filerOf(values, true);
     const type = values.type ?? 'decision', told = ASK_FLAGS.find((f) => values[f] !== undefined);
     if (told && type !== 'decision')
@@ -1122,7 +1184,7 @@ async function refile(args) {
 }
 /** For a program that feeds the board: the --from file, checked like any post, becomes the whole board, items and top-level fields. Answers stay.
  * With a filer it replaces only that filer's items (and items with no filer it names by key); every other item and top-level field stays. */
-function replace(file, named, on, from, filer) {
+function replace(file, named, on, from, filer, askRef) {
     if (from === undefined)
         throw fail('--replace needs --from <board file>', 'VALIDATION_ERROR', 'sign-off-axi post board.json --from feed.json --replace');
     const source = resolve(from), fed = readItems(source);
@@ -1146,6 +1208,11 @@ function replace(file, named, on, from, filer) {
                 throw fail(`key ${i.key} was answered on ${tilde(file)} and is no longer there`, 'CONFLICT', 'Post it under a new key');
             }
         const current = board(file);
+        if (askRef !== undefined)
+            for (const [i, d] of incoming.entries())
+                if (['decision', 'ask'].includes(feed[i]?.kind ?? feed[i]?.type ?? 'decision') && !current.some((c) => c.key === d.key))
+                    feed[i].ask_ref = askRef;
+        checkAskRefs(incoming, feed, current);
         for (const had of current) {
             const d = incoming.find((x) => x.key === had.key);
             if (filer && d && had.filer && had.filer !== filer)
@@ -1408,6 +1475,8 @@ async function postKind(file, named, on, values, built) {
     if (m.filer !== undefined && values.filer !== undefined && m.filer !== values.filer) {
         throw fail(`${name}: key ${m.key}: filer ${m.filer} is not --filer ${values.filer}`, 'VALIDATION_ERROR', 'Leave "filer" out of the message, or pass the same --filer');
     }
+    if (m.kind === 'ask' && values['ask-ref'] !== undefined)
+        m.ask_ref = values['ask-ref'];
     const filer = m.filer ?? filerOf(values, true), scratch = mkdtempSync(join(tmpdir(), 'sign-off-')), source = join(scratch, basename(name));
     try {
         if (m.kind === 'evidence')
@@ -1504,16 +1573,20 @@ function buildIncoming(values, extra, filer, file) {
         // An item that names its own filer keeps it.
         const source = resolve(values.from), raw = readItems(source).items;
         contractItems(raw, values.from, file);
+        if (values['ask-ref'] !== undefined)
+            for (const item of raw)
+                if ((item.kind ?? item.type ?? 'decision') === 'ask' || (item.type ?? 'decision') === 'decision' && !item.kind)
+                    item.ask_ref = values['ask-ref'];
         const incoming = loadDecisions(source, board);
         recommended(raw, false);
-        return { incoming: incoming.map((d) => ({ filer, ...d })), raw: raw.map((i) => ({ filer, ...i })) };
+        return { incoming: incoming.map((d, i) => ({ filer, ...d, ...(raw[i].ask_ref !== undefined && { ask_ref: raw[i].ask_ref }) })), raw: raw.map((i) => ({ filer, ...i })) };
     }
     const scratch = mkdtempSync(join(tmpdir(), 'sign-off-'));
     const source = join(scratch, 'flags');
     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, proof: values.proof };
+        const told = ask && { why, recommend_reason: values['recommend-reason'], silent_by: values['silent-by'], merges: values.merge, proof: values.proof, ask_ref: values['ask-ref'] };
         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)
@@ -1568,11 +1641,23 @@ function checkMerges(incoming, resulting, current) {
         }
     }
 }
+/** New decision cards need the captain message or hold that prompted them; old cards still re-post. */
+function checkAskRefs(incoming, raw, current) {
+    for (const [i, d] of incoming.entries()) {
+        if (!['decision', 'ask'].includes(raw[i]?.kind ?? raw[i]?.type ?? 'decision') || current.some((c) => c.key === d.key))
+            continue;
+        const ref = raw[i]?.ask_ref;
+        if (typeof ref !== 'string' || !ref.trim() || ref.length > 256 || /[\s\x00-\x1f\x7f]/.test(ref)) {
+            throw fail(`key ${d.key}: a new Decide card needs a captain ask reference`, 'VALIDATION_ERROR', 'Pass --ask-ref <captain-message-id-or-hold-id> (ask_ref in a message or feed). Follow-ups belong in the backlog, not the board');
+        }
+    }
+}
 /** exact: a contract post, where a key takes only the same message again, filer and filed included (contract section 4). */
 function storeIncoming(file, named, on, { incoming, raw }, filer, exact = false) {
     mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
     return locked(`${file}.lock`, () => {
         const current = board(file), items = existsSync(file) ? readItems(file).items : [], saved = readAnswers(file), now = new Date().toISOString();
+        checkAskRefs(incoming, raw, current);
         checkMerges(incoming, [...current.filter((c) => !incoming.some((d) => d.key === c.key)), ...incoming], current);
         // Proof is evidence: a new ask that offers Pass and Fail would sit in Waiting on you as an ask, so it is refused.
         const proof = incoming.find((d) => d.type === 'decision' && !d.kind && !current.some((c) => c.key === d.key) && ['pass', 'fail'].every((v) => d.options.some((o) => o.value === v)));
@@ -1597,7 +1682,7 @@ function storeIncoming(file, named, on, { incoming, raw }, filer, exact = false)
             if (!had && Object.hasOwn(saved, d.key) && !awaitsVerdict(d.type, saved[d.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, dismissed: 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, ask_ref: 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 }), announced: undefined }) !== canon(raw[i]) : same(had) !== same(d);
             if (had && differs())
@@ -1830,7 +1915,7 @@ const skillInstalled = (dir, agent) => [join(dir, AGENTS[agent].dir), AGENTS[age
     .some((skills) => existsSync(join(skills, 'sign-off-axi', 'SKILL.md')));
 const SKILL_ADD = ['-y', 'skills', 'add', 'umeranjum17/sign-off', '--skill', 'sign-off-axi', '-y', '-a'];
 const skillAdd = (agents) => `npx ${[...SKILL_ADD, ...agents].join(' ')}`;
-const GITIGNORE = 'mocks/\nevidence/\n*.answers.jsonl\n*.rounds.jsonl\n*.messages.jsonl\n*.annotations.jsonl\n*.seen.jsonl\n*.dismissed.jsonl\n*.reads.jsonl\n*.deeper.jsonl\n*.board.pid\n*.board.log\nnotify.log\n*.token\n*.export.html\n';
+const GITIGNORE = 'mocks/\nevidence/\n*.answers.jsonl\n*.rounds.jsonl\n*.messages.jsonl\n*.annotations.jsonl\n*.seen.jsonl\n*.dismissed.jsonl\n*.reads.jsonl\n*.deeper.jsonl\n*.owners.json\n*.delivery.jsonl\n*.board.pid\n*.board.log\nnotify.log\n*.token\n*.export.html\n';
 /** The board, port, bind and hosts in <so>/config.yaml (the `key: value` lines init writes). A bad line falls back on its own default
  * (decisions.json, 4410) and `problems` says what is wrong; a file that cannot be read throws. */
 function readSetup(so) {
@@ -2335,7 +2420,7 @@ async function serve(args) {
         rmSync(record(file), { force: true }); });
     for (const sig of ['SIGINT', 'SIGTERM'])
         process.on(sig, () => process.exit(0));
-    return toon({ board: tilde(file), url, pid: process.pid }, [linkHelp(file, url), `Run \`sign-off-axi answers${parsed.on}\` to read their answers`]);
+    return toon({ board: tilde(file), url, pid: process.pid }, [linkHelp(file, url), `Run \`sign-off-axi answers${parsed.on}\` to read their answers`, `Run \`sign-off-axi stop${parsed.on}\` to close the board (no shell kill needed)`]);
 }
 /** Every new comment and queued prompt, each handed over once. */
 async function poll(args) {
@@ -2374,13 +2459,14 @@ async function exportBoard(args) {
     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.
-    const inline = async (url, query) => {
+    const inline = async (url, query, document = false) => {
         const [code, body] = await route({ method: 'GET', url }).catch(() => [404, null]);
         if (code !== 200) {
             missing++;
             return;
         }
-        const { media, type } = body;
+        const { media: bytes, type } = body;
+        const media = document && type === 'text/html' ? Buffer.concat([bytes, pointer]) : bytes;
         // A data: URL keeps a one-page mock's query where the mock page reads it, but also appends it to the page text: a trailing comment hides it.
         files[url] = query && type === 'text/html' ? `data:text/html;charset=utf-8,${q(media.toString())}%3C!--?${query}` : `data:${type};base64,${media.toString('base64')}`;
     };
@@ -2393,7 +2479,7 @@ async function exportBoard(args) {
         }
         // A diagram or an interactive page is the item's own view, inlined the same way.
         if (d.view)
-            await inline(at(d.key, '', d.view));
+            await inline(at(d.key, '', d.view), undefined, true);
         if (d.preview)
             await inline(at(d.key, '', d.preview));
         for (const i of (d.media ?? []).keys())
@@ -2526,6 +2612,7 @@ const state = () => {
         seen_at: Object.fromEntries(Object.values(answers).flatMap((a) => { const t = seenAt(file)(a); return t ? [[a.key, t]] : []; })),
         reads: readReads(file),
         deeper: readDeeper(file),
+        delivery: deliveries(file),
         rounds,
         messages: readMessages(file, warn),
         annotations: readOnly() || answersOnly() ? [] : ((sent) => readAnnotations(file, warn).map((a) => (sent.has(a.id) ? { ...a, sent: true } : a)))(sentIds(file)),
@@ -2670,8 +2757,8 @@ async function route(req) {
             const actual = under(dirname(under(dirname(file), mockFile(mock))), path);
             if (statSync(actual).size > MOCK_BYTES)
                 return [404, { error: 'Mock is unavailable' }];
-            // A design mock page, and a plan's page, get the pointing bridge when served; export inlines the page as written.
-            return [200, { media: readFileSync(actual), type, point: (Boolean(value) || d.type === 'plan') && type === 'text/html' }];
+            // Every HTML view gets the bridge: document readers need its size handshake too.
+            return [200, { media: readFileSync(actual), type, point: type === 'text/html' }];
         }
         catch {
             return [404, { error: 'Mock is unavailable' }];
@@ -2731,7 +2818,7 @@ async function route(req) {
         clearTimeout(timer);
         return [200, state()];
     }
-    if (req.method !== 'POST' || !['/api/answers', '/api/rounds', '/api/messages', '/api/annotations', '/api/dismiss', '/api/signin', '/api/leash', '/api/deeper', '/api/reads'].includes(req.url ?? ''))
+    if (req.method !== 'POST' || !['/api/answers', '/api/rounds', '/api/messages', '/api/annotations', '/api/dismiss', '/api/signin', '/api/leash', '/api/deeper', '/api/reads', '/api/engagement', '/api/engagement/seen'].includes(req.url ?? ''))
         return [404, { error: 'Not found' }];
     if (readOnly())
         return [403, { error: 'This board is read-only' }];
@@ -2824,6 +2911,14 @@ async function route(req) {
         appendDismissed(file, [...new Set(keys)], dismissed);
         return [200, state()];
     }
+    if (req.url === '/api/engagement' || req.url === '/api/engagement/seen') {
+        const input = JSON.parse(body);
+        if (req.url.endsWith('/seen'))
+            markEngagementSeen(file, input.id, input.answerRevision);
+        else
+            askEngagement(file, input);
+        return [200, state()];
+    }
     if (req.url === '/api/reads' || req.url === '/api/deeper') {
         const { key, part, q } = JSON.parse(body) ?? {}, d = loadDecisions(file).find((x) => x.key === key), about = typeof part === 'string' && d ? guidePart(d, part) : undefined;
         if (!about)
@@ -3077,7 +3172,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), deeper: axi('deeper', deeper), signin: axi('signin', signin), dismiss: axi('dismiss', dismiss(false)), restore: axi('restore', dismiss(true)), refile: axi('refile', refile), doctor: axi('doctor', doctor), notify: axi('notify', notify), 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), owner: axi('owner', owner), deeper: axi('deeper', deeper), signin: axi('signin', signin), dismiss: axi('dismiss', dismiss(false)), restore: axi('restore', dismiss(true)), refile: axi('refile', refile), 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;

package/dist/contract.js

@@ -11,15 +11,15 @@ export class ContractError extends Error {
     }
 }
 /** The kinds, with the schema number of each. */
-export const SCHEMAS = { ask: 1, report: 3, evidence: 1, gate: 1, finding: 1, plan: 2, design: 1 };
+export const SCHEMAS = { ask: 1, report: 4, evidence: 1, gate: 1, finding: 1, plan: 3, design: 1 };
 /** Older schemas this sign-off-axi still takes, so a board that holds them loads and re-posts: the page-based report 2 and plan 1. */
-const OLDER = { report: [2], plan: [1] };
+const OLDER = { report: [2, 3], plan: [1, 2] };
 /** The guided schemas: a report 3 and a plan 2 are fields the board draws as one guided page, not a page the agent draws. */
-export const guided = (m) => (m?.kind === 'report' && m.schema === 3) || (m?.kind === 'plan' && m.schema === 2);
+export const guided = (m) => (m?.kind === 'report' && [3, 4].includes(m.schema)) || (m?.kind === 'plan' && [2, 3].includes(m.schema));
 export const KINDS = Object.keys(SCHEMAS);
 const COMMON = ['contract', 'kind', 'schema', 'key', 'title', 'filer', 'link', 'about'];
 const FIELDS = {
-    ask: [...COMMON, 'detail', 'why', 'options', 'recommend_value', 'recommend_reason', 'default_if_silent', 'silent_by', 'close', 'merges', 'proof'],
+    ask: [...COMMON, 'ask_ref', 'detail', 'why', 'options', 'recommend_value', 'recommend_reason', 'default_if_silent', 'silent_by', 'close', 'merges', 'proof'],
     report: [...COMMON, 'filed', 'group', 'decided', 'form', 'video', 'asked_by', 'view', 'preview'],
     evidence: [...COMMON, 'media', 'run'],
     gate: [...COMMON, 'run', 'options', 'recommend_value', 'close'],
@@ -314,6 +314,8 @@ export function checkMessage(m, want, flags = false) {
     if (!Object.hasOwn(m, 'title'))
         throw bad('title', 'is required', 'Add "title": the question, in 160 characters or fewer');
     text('title', m.title, 160, 'the question, in 160 characters or fewer');
+    if (g && m.schema === SCHEMAS[m.kind] && !isKey(m.filer))
+        throw bad('filer', 'is required', 'Set "filer" to the owning agent id');
     if (Object.hasOwn(m, 'filer') && !isKey(m.filer))
         throw bad('filer', 'must be 1-128 of A-Z a-z 0-9 . _ -', 'Set "filer" to your agent session id or tool name, or leave it out');
     if (Object.hasOwn(m, 'link') && !(typeof m.link === 'string' && /^(https?:\/\/[^\s\p{Cc}\p{Cs}]{1,500}|[a-f0-9]{7,40})$/u.test(m.link))) {

package/dist/evidence-text.js

@@ -14,8 +14,11 @@ const SATURATED = 96;
 const BAND_MIN = 0.05;
 const BARS_MIN = 5;
 const BARS_SHARE_MIN = 0.6;
-/** A placeholder is one flat colour over this share of the picture; the real captures measured top out at 75%, the text renders are text. */
+/** A placeholder is one flat colour over this share of the picture, with almost nothing drawn on it. A real screen can be as empty (a chat
+ * with no messages is 90% paper) but its header, message, composer and tab bar draw 7% or more of the picture in other colours; a flat card
+ * with a label or icon draws under 1%. */
 const PLACEHOLDER_MIN = 0.9;
+const PLACEHOLDER_DETAIL_MAX = 0.05;
 /** A picture with no ink at all (a flat colour) is not text, so it passes. */
 const INK_MIN = 0.005;
 /** How close (0-255 RGB distance) a pixel must be to the paper or to the paper-ink line to count as text. */
@@ -85,7 +88,7 @@ function faultsOf(share) {
     return [
         ...(text ? ['text'] : []),
         ...(share.bars >= BARS_MIN && share.barShare >= BARS_SHARE_MIN ? ['colour bars'] : []),
-        ...(!text && share.top >= PLACEHOLDER_MIN ? ['placeholder'] : []),
+        ...(!text && share.top >= PLACEHOLDER_MIN && share.ink + share.off <= PLACEHOLDER_DETAIL_MAX ? ['placeholder'] : []),
     ];
 }
 export function faults(file) {