@lovinka/vitrinka 1.15.1 → 1.17.0

package/CHANGELOG.md

@@ -3,6 +3,38 @@
 `vitrinka update` prints the sections newer than your previous version after
 updating — keep entries short and user-facing.
 
+## 1.17.0 — 2026-07-20
+
+### Added
+- `get_questions` MCP tool — durable post-send retrieval of a board's answered
+  decisions (options, notes, ⌖ refs). Choices ride the work wire exactly once,
+  so a send with no listening session used to look unrecoverable; now any
+  session can re-read the full answer record at any time.
+- `scrape_board` digest now carries a compact `questions[]`
+  (`{id, prompt, answer?, note?, staged?}`) — one call reads the decision
+  state alongside cards/flow/sections; section scopes keep only their own.
+- `vitrinka watch` keepalive: while a human actually has the board open, the
+  leased watch emits a quiet `· keepalive` heartbeat (default every 3000 s,
+  `--keepalive 0` off) so the listening session's prompt cache stays warm and
+  the next annotation lands cheap. An abandoned board costs nothing.
+
+## 1.16.0 — 2026-07-19
+
+### Added
+- Listener takeover is automatic on the same machine — arming `vitrinka watch`
+  for a scope another of YOUR sessions already holds displaces the older
+  listener (its in-flight items go back to the queue) instead of failing with
+  a 409 and a manual handoff. The displaced watch prints one stand-down line
+  and exits cleanly. Live leases on a *different* machine still refuse the
+  claim; `--takeover` still steals expired leases only.
+
+### Fixed
+- `vitrinka watch` and the background daemon no longer swallow answered
+  brainstorm choices — a pure choice batch used to be drained by the notifier
+  and marked delivered while the listening session never woke. Notifier lanes
+  now peek without consuming, and watch announces each answer as a
+  `№<id> [choice]` line; the acting lane keeps exactly-once delivery.
+
 ## 1.15.1 — 2026-07-18
 
 ### Added

package/dist/cli.js

@@ -3415,13 +3415,14 @@ export const COMMANDS = [
     },
     {
         name: 'watch', summary: 'Monitor the work queue (listen v2); auto-scopes to repo+branch, leases the scope (one listener each), one line per new item',
-        usage: '[--board <slug>|--project <p> --branch <b>|--all] [--takeover] [--quiet-grace <sec>] [--once] [--base <url>]',
+        usage: '[--board <slug>|--project <p> --branch <b>|--all] [--takeover] [--quiet-grace <sec>] [--keepalive <sec>] [--once] [--base <url>]',
         flags: [{ f: '--board', arg: '<slug>', d: 'lease one board (else the repo project+branch is inferred)' },
             { f: '--project', arg: '<p>', d: 'override the inferred project scope' },
             { f: '--branch', arg: '<b>', d: 'override the inferred branch scope (with --project)' },
             { f: '--all', d: 'firehose: observe every board (leases a conflict-free scope, claims nothing)' },
             { f: '--takeover', d: 'steal an EXPIRED lease (a dead session); never steals a live one' },
             { f: '--quiet-grace', arg: '<sec>', d: 'drain poll interval (default 5)' },
+            { f: '--keepalive', arg: '<sec>', d: 'cache keep-alive wake interval while a viewer has a scope board open (default 3000, 0 = off)' },
             { f: '--once', d: 'single deterministic poll (exit 0 = work, 3 = idle)' }, BASE_FLAG],
         dynamic: 'boards',
         examples: ['vitrinka watch', 'vitrinka watch --board payout-flow', 'vitrinka watch --takeover'],
@@ -4282,6 +4283,47 @@ export function computeAnnouncements(prev, currentQueue) {
     }
     return { lines, nextMap };
 }
+// choiceLine renders the single stdout line for one answered question:
+//   №<id> [choice] <board>: <question> → <option>[ · <note>] (≤120 chars tail)
+export function choiceLine(c) {
+    const board = c.board || '?';
+    let tail = `${String(c.question ?? '').replace(/\s+/g, ' ').trim()} → ${String(c.option ?? '').replace(/\s+/g, ' ').trim()}`;
+    if (c.note)
+        tail += ` · ${String(c.note).replace(/\s+/g, ' ').trim()}`;
+    if (tail.length > 120)
+        tail = tail.slice(0, 120) + '…';
+    return `№${c.id} [choice] ${board}: ${tail}`;
+}
+// computeChoiceAnnouncements is the choice twin of computeAnnouncements (PURE).
+// A choice is "new" when its id wasn't announced or its answer/note changed
+// (re-answer + re-dispatch re-arms delivered and must re-announce). A drained
+// choice drops off the wait wire and thus out of nextMap.
+export function computeChoiceAnnouncements(prev, choices) {
+    const nextMap = {};
+    const lines = [];
+    for (const c of choices) {
+        if (c == null || c.id === undefined || c.id === null)
+            continue;
+        const key = String(c.id);
+        const before = prev[key];
+        if (!before || before.option !== c.option || before.note !== c.note) {
+            lines.push(choiceLine(c));
+        }
+        nextMap[key] = { option: c.option, note: c.note };
+    }
+    return { lines, nextMap };
+}
+// shouldKeepalive is the presence-gated cache keep-alive decision (PURE —
+// unit-tested). A listening Claude Code session's prompt cache expires after a
+// TTL of idle; a wake just before expiry re-reads the cache (~10% of input
+// price) instead of paying a full-price cache re-write on the next annotation.
+// That gamble only pays while an annotation is plausibly imminent, so the wake
+// fires ONLY when the server reports a human actually has a scope board open
+// (viewerPresent on the idle wait response). Every stdout line wakes the
+// session, so any emitted line resets the clock.
+export function shouldKeepalive(nowMs, lastWakeMs, keepaliveSec, viewerPresent) {
+    return keepaliveSec > 0 && viewerPresent && nowMs - lastWakeMs >= keepaliveSec * 1000;
+}
 const watchEmit = (line) => { process.stdout.write(line + '\n'); };
 const watchSleep = (ms) => new Promise((r) => setTimeout(r, ms));
 function watchBaseUrl(args) {
@@ -4337,6 +4379,8 @@ async function watchFetchJson(url, timeoutMs) {
 async function watchCmd(args) {
     const base = watchBaseUrl(args);
     const graceSec = numArg(args['quiet-grace'], 5, '--quiet-grace');
+    // --keepalive 0 disables the heartbeat (numArg itself rejects non-positives).
+    const keepaliveSec = strArg(args.keepalive) === '0' ? 0 : numArg(args.keepalive, 3000, '--keepalive');
     const once = args.once === true;
     // Repo context for scope inference (main worktree basename = project; current
     // branch). '.' cwd is where the session runs (the app repo).
@@ -4352,7 +4396,7 @@ async function watchCmd(args) {
     // --once: a single deterministic probe (tests). Lease-free (no session), so it
     // never claims scope. Returns exit 0 with announcements, else 3 (idle).
     if (once) {
-        const waitUrl = `${base}/api/v1/work/wait?${new URLSearchParams({ timeout: '2', ...sq })}`;
+        const waitUrl = `${base}/api/v1/work/wait?${new URLSearchParams({ timeout: '2', peek: '1', ...sq })}`;
         let waited;
         try {
             waited = await watchFetchJson(waitUrl, 12_000);
@@ -4361,19 +4405,24 @@ async function watchCmd(args) {
             console.error(`watch --once: vitrinka unreachable: ${e instanceof Error ? e.message : e}`);
             process.exit(3);
         }
-        if (!waited || waited.idle || !Array.isArray(waited.work) || waited.work.length === 0) {
+        const onceChoices = Array.isArray(waited?.choices) ? waited.choices : [];
+        const hasWork = Array.isArray(waited?.work) && waited.work.length > 0;
+        if (!waited || waited.idle || (!hasWork && onceChoices.length === 0)) {
             process.exit(3);
         }
-        let list;
-        try {
-            list = await watchFetchJson(listUrl(), 30_000);
-        }
-        catch (e) {
-            console.error(`watch --once: list failed: ${e instanceof Error ? e.message : e}`);
-            process.exit(3);
+        const lines = computeChoiceAnnouncements({}, onceChoices).lines;
+        if (hasWork) {
+            let list;
+            try {
+                list = await watchFetchJson(listUrl(), 30_000);
+            }
+            catch (e) {
+                console.error(`watch --once: list failed: ${e instanceof Error ? e.message : e}`);
+                process.exit(3);
+            }
+            const items = Array.isArray(list?.work) ? list.work : [];
+            lines.push(...computeAnnouncements({}, items).lines);
         }
-        const items = Array.isArray(list?.work) ? list.work : [];
-        const { lines } = computeAnnouncements({}, items);
         for (const l of lines)
             watchEmit(l);
         process.exit(lines.length > 0 ? 0 : 3);
@@ -4385,7 +4434,9 @@ async function watchCmd(args) {
     const session = `${hostname()}:${process.pid}`;
     const takeover = args.takeover === true;
     const leasedWaitUrl = (secs) => {
-        const q = new URLSearchParams({ timeout: String(secs), session, ...sq });
+        // peek=1: the watch is a NOTIFIER — the server must leave choices pending
+        // for the acting session's MCP wait_for_work drain (which has no peek).
+        const q = new URLSearchParams({ timeout: String(secs), peek: '1', session, ...sq });
         if (actor)
             q.set('actor', actor);
         if (takeover)
@@ -4415,12 +4466,17 @@ async function watchCmd(args) {
     process.on('SIGINT', () => { void shutdown(0); });
     process.on('SIGTERM', () => { void shutdown(0); });
     let announced = {};
+    let announcedChoices = {};
     let downSince = null;
     let degradedAt = null;
     let backoff = 1000;
+    // Keep-alive clock: the session was active when it armed the monitor, and
+    // every stdout line re-wakes it — so any emit resets the clock.
+    let lastWakeMs = Date.now();
+    const emit = (line) => { watchEmit(line); lastWakeMs = Date.now(); };
     const noteSuccess = () => {
         if (degradedAt !== null)
-            watchEmit('✓ vitrinka reachable again');
+            emit('✓ vitrinka reachable again');
         downSince = null;
         degradedAt = null;
         backoff = 1000;
@@ -4431,7 +4487,7 @@ async function watchCmd(args) {
             downSince = now;
         const downMs = now - downSince;
         if (downMs >= 120_000 && (degradedAt === null || now - degradedAt >= 600_000)) {
-            watchEmit(`⚠ vitrinka unreachable for ${Math.round(downMs / 1000)}s — listener degraded`);
+            emit(`⚠ vitrinka unreachable for ${Math.round(downMs / 1000)}s — listener degraded`);
             degradedAt = now;
         }
         const wait = backoff;
@@ -4451,11 +4507,12 @@ async function watchCmd(args) {
             continue;
         }
         if (resp.status === 409) {
-            // Scope already held by another session. Live → cannot steal; expired →
-            // retry with --takeover. Either way surface it and exit (the skill reads
-            // exit 2 as "another session owns this scope").
+            // Scope held by an unstealable lease: a LIVE listener on ANOTHER machine
+            // (same-machine live leases are displaced automatically — newest wins),
+            // or an expired lease without --takeover. Surface it and exit (the skill
+            // reads exit 2 as "another session owns this scope").
             const h = resp.body?.holder ?? {};
-            const live = resp.body?.live ? 'live' : 'expired';
+            const live = resp.body?.live ? 'live, another machine' : 'expired';
             const scopeStr = h.scopeKind === 'project' ? `${h.scope}/${h.branch}` : (h.scope || h.scopeKind || scope.label);
             const since = h.lastSeen ? ` (since ${h.lastSeen})` : '';
             watchEmit(`⚠ listener already active (${live}): ${h.actor || '?'}@${h.session || '?'} on ${scopeStr}${since}`);
@@ -4467,12 +4524,44 @@ async function watchCmd(args) {
             await noteFailure();
             continue;
         }
+        if (resp.body?.revoked) {
+            // Newest-wins takeover: another session on this machine armed a listener
+            // for our scope. Stand down — one notice, clean exit, and NEVER re-claim
+            // (the takeover is the operator's routing decision).
+            const t = resp.body.takenBy ?? {};
+            watchEmit(`⚠ listener for ${scope.label} taken over by ${t.actor || '?'}@${t.session || '?'} — standing down`);
+            process.exit(0);
+        }
         noteSuccess();
         if (typeof resp.body?.listener === 'number')
             leaseId = resp.body.listener;
         const waited = resp.body;
-        if (!waited || waited.idle || !Array.isArray(waited.work) || waited.work.length === 0) {
+        const waitedWork = Array.isArray(waited?.work) ? waited.work : [];
+        const waitedChoices = Array.isArray(waited?.choices) ? waited.choices : [];
+        if (!waited || waited.idle || (waitedWork.length === 0 && waitedChoices.length === 0)) {
+            announced = {};
+            announcedChoices = {};
+            // Presence-gated cache keep-alive: the idle response says whether a
+            // human has a scope board open; if so and the session has been idle
+            // ~one cache TTL, one heartbeat line wakes it to refresh the cache.
+            // The skill treats the line as a no-op wake (do nothing, end turn).
+            if (shouldKeepalive(Date.now(), lastWakeMs, keepaliveSec, waited?.viewerPresent === true)) {
+                emit(`· keepalive ${scope.label}`);
+            }
+            continue;
+        }
+        // Choices announce straight from the wait body — with peek they stay
+        // pending on the wire (invisible to the plain work list), so this response
+        // is their only sighting until the acting session drains them.
+        {
+            const { lines, nextMap } = computeChoiceAnnouncements(announcedChoices, waitedChoices);
+            announcedChoices = nextMap;
+            for (const l of lines)
+                emit(l);
+        }
+        if (waitedWork.length === 0) {
             announced = {};
+            await watchSleep(graceSec * 1000);
             continue;
         }
         // Queue non-empty → diff the full open list and announce new items. The next
@@ -4483,7 +4572,7 @@ async function watchCmd(args) {
             const { lines, nextMap } = computeAnnouncements(announced, items);
             announced = nextMap;
             for (const l of lines)
-                watchEmit(l);
+                emit(l);
         }
         catch {
             await noteFailure();