whose-turn 1.0.0-alpha.5 → 1.0.0-alpha.7

package/lib/api.mjs

@@ -11,6 +11,7 @@ import { composeIssue, DEFAULT_COMPOSER } from './compose.mjs';
 import { readSize, saveSize, checkMode, spawnOpener } from './window.mjs';
 import { frameHandOff } from './handoff.mjs';
 import { noUpdates } from './update.mjs';
+import { LINE_BREAK } from './secrets.mjs';
 
 const send = (response, code, body, contentType = 'application/json', cacheControl = 'no-store') => {
   const data = Buffer.isBuffer(body) ? body : Buffer.from(contentType === 'application/json' ? JSON.stringify(body) : body);
@@ -47,7 +48,6 @@ const assertLocal = (request, port) => {
 
 const WINDOW_PAGES = ['/', '/report', '/sheet'];
 
-/** What a browser sees when a window page is opened under another host name: where to go, instead of the API's JSON refusal. */
 const wrongAddressPage = (port) => {
   const address = `http://127.0.0.1:${port}/`;
   return `<!doctype html><meta charset="utf-8"><meta name="color-scheme" content="light dark"><title>Whose Turn</title><p style="font: 15px system-ui; margin: 40px">The window opens only at the local address: <a href="${address}">${address}</a></p>`;
@@ -66,6 +66,15 @@ const marksProblem = (body) => {
   if ('base' in body && !(Number.isFinite(body.base) && body.base <= Date.now() + CLOCK_SKEW_MS)) {
     return 'base must be a number of milliseconds, not in the future';
   }
+  if (body.notes !== undefined) {
+    if (!body.notes || typeof body.notes !== 'object' || Array.isArray(body.notes)) {
+      return 'notes must map row ids to a line of text';
+    }
+    const wrongNote = Object.entries(body.notes).find(([, value]) => typeof value !== 'string' || value.length > 200);
+    if (wrongNote) {
+      return `notes.${wrongNote[0]} must be text of at most 200 characters`;
+    }
+  }
   if (body.handled === undefined) {
     return '';
   }
@@ -100,7 +109,7 @@ const aggregateSummary = (workspaces) => {
 
 const OPEN_COOLDOWN_MS = 5000;
 
-export const startApi = async ({ port, appDir, registry, requestPoll, saveConfig, secrets, inbox, http, reports, dataDir, opener = spawnOpener(appDir), updater = noUpdates() }) => {
+export const startApi = async ({ port, appDir, registry, requestPoll, saveConfig, secrets, inbox, http, reports, dataDir, opener = spawnOpener(appDir), updater = noUpdates(), changelog = null }) => {
   const windowFile = createStatic(join(appDir, 'dist'));
   const feedbackCache = {};
   const pick = (id) => {
@@ -164,6 +173,12 @@ export const startApi = async ({ port, appDir, registry, requestPoll, saveConfig
       const tables = Object.fromEntries(registry.workspaces.map((workspace) => [workspace.id, workspace.rulesTable]));
       return send(response, 200, { workspaces: registry.rawWorkspaces, problems: registry.problems, connectors: connectorCatalogue(), fields: WORKSPACE_FIELDS, facts: FACTS, tables, table_warnings: normaliseWorkspaces(registry.rawWorkspaces).warnings, config_file: registry.configFile });
     }
+    if (url.pathname === '/api/changelog') {
+      if (!changelog) {
+        throw new ApiError('CHANGELOG_UNAVAILABLE');
+      }
+      return send(response, 200, changelog);
+    }
     if (url.pathname === '/api/inbox') {
       return send(response, 200, { items: inbox.pending(url.searchParams.get('consumer') || '') });
     }
@@ -267,6 +282,11 @@ export const startApi = async ({ port, appDir, registry, requestPoll, saveConfig
     const service = String(body.service || '').trim();
     const account = String(body.account || '').trim();
     const value = String(body.value || '').trim();
+    for (const [field, text] of Object.entries({ service, account, value })) {
+      if (LINE_BREAK.test(text)) {
+        throw new ApiError('INVALID_ARGUMENT', { detail: `${field} must not contain a line break` });
+      }
+    }
     if (!/^[\w.-]{1,80}$/.test(service) || !account || !value) {
       throw new ApiError('INVALID_ARGUMENT', { detail: 'service, account and value are required' });
     }

package/lib/changelog.mjs

@@ -0,0 +1,74 @@
+/** Parses CHANGELOG.md (Keep a Changelog) into versions, newest first as written, and reads it next to server.mjs. */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const VERSION_HEADING = /^##\s+\[([^\]]+)\](?:\s+-\s+(\S.*?))?\s*$/;
+const SECTION_HEADING = /^###\s+(\S.*?)\s*$/;
+const ISSUE_ID = String.raw`[A-Z][A-Z0-9]+-\d+`;
+const TRAILING_IDS = new RegExp(String.raw`(?<=[.!?])\s+${ISSUE_ID}(?:,\s*${ISSUE_ID})*\.?$`);
+const BRACKETED_IDS = new RegExp(String.raw`\s*\((?:${ISSUE_ID})(?:,\s*${ISSUE_ID})*\)`, 'g');
+
+/** An entry as a user reads it: the internal tracker ids at its end or in brackets are dropped. */
+export const withoutIds = (entry) => entry.replace(BRACKETED_IDS, '').replace(TRAILING_IDS, '').trim();
+
+/** [{version, date, sections: [{kind, items: [markdown]}]}]; a malformed `##` heading ends the version above it and its body is dropped. */
+export const parseChangelog = (text) => {
+  const versions = [];
+  let version = null;
+  let section = null;
+  let item = null;
+  const closeItem = () => {
+    if (item !== null && section) {
+      section.items.push(withoutIds(item.trim()));
+    }
+    item = null;
+  };
+  for (const line of String(text).split(/\r?\n/)) {
+    if (line.startsWith('## ') || line === '##') {
+      closeItem();
+      const heading = line.match(VERSION_HEADING);
+      version = heading ? { version: heading[1], date: heading[2] || '', sections: [] } : null;
+      section = null;
+      if (version) {
+        versions.push(version);
+      }
+      continue;
+    }
+    if (!version) {
+      continue;
+    }
+    const kind = line.match(SECTION_HEADING);
+    if (kind) {
+      closeItem();
+      section = { kind: kind[1], items: [] };
+      version.sections.push(section);
+      continue;
+    }
+    if (!section) {
+      continue;
+    }
+    if (line.startsWith('- ')) {
+      closeItem();
+      item = line.slice(2);
+    } else if (item !== null && /^\s+\S/.test(line)) {
+      item += '\n' + line.trim();
+    } else {
+      closeItem();
+    }
+  }
+  closeItem();
+  versions.forEach((entry) => {
+    entry.sections = entry.sections.filter((one) => one.items.length);
+  });
+  return versions;
+};
+
+/** The reply of GET /api/changelog: the released versions only, or null when the file cannot be read. */
+export const loadChangelog = (appDir, current) => {
+  try {
+    const versions = parseChangelog(readFileSync(join(appDir, 'CHANGELOG.md'), 'utf8'));
+    return { current, versions: versions.filter((entry) => entry.version !== 'Unreleased') };
+  } catch {
+    return null;
+  }
+};

package/lib/config.mjs

@@ -146,7 +146,6 @@ const normaliseLinks = (links) => (Array.isArray(links) ? links : []).map((entry
 
 const isStringList = (value) => Array.isArray(value) && value.every((item) => typeof item === 'string');
 
-/** A problem tied to one field of the saved list, as the settings form shows it under that field. */
 const violation = (field, description) => ({ field, description });
 
 const fieldProblems = (workspace, id, index) => {

package/lib/errors.mjs

@@ -16,6 +16,7 @@ const REASONS = {
   OPEN_TOO_SOON: { code: 429, status: 'RESOURCE_EXHAUSTED', message: 'The window was just opened; wait a few seconds before opening it again.' },
   UPDATE_IN_PROGRESS: { code: 409, status: 'ABORTED', message: 'An update is already installing; the server restarts when it is done.' },
   UPDATE_UNAVAILABLE: { code: 412, status: 'FAILED_PRECONDITION', message: 'There is no update to apply: the server runs from a checkout or already runs the latest version.' },
+  CHANGELOG_UNAVAILABLE: { code: 404, status: 'NOT_FOUND', message: 'This install has no readable CHANGELOG.md.' },
   FORBIDDEN_ORIGIN: { code: 403, status: 'PERMISSION_DENIED', message: 'Only the local window may call this API.' },
   INTERNAL: { code: 500, status: 'INTERNAL', message: 'The local server failed on this request; the details are in its log.' },
 };

package/lib/facts.mjs

@@ -6,32 +6,33 @@ export const shortDate = (iso) => new Date(iso).toLocaleDateString('en-US', { mo
 const CATEGORY_GROUPS = { new: 'todo', indeterminate: 'in_progress', done: 'done' };
 const CHAIN_GROUPS = ['backlog', 'passed', 'code_review', 'qa', 'on_hold'];
 
-/** Every fact a table row may test or quote: its type, the closed values when there are any, and where it comes from. */
+/** The closed fact dictionary a table row may test or quote, each with its plain words.
+ * Rules: docs/mechanisms/rules-table.md, Facts. */
 export const FACTS = {
-  connector: { type: 'string', from: 'the connector entry id the ticket came from' },
-  'ticket.key': { type: 'string', from: 'tracker connectors (jira, linear)' },
-  'ticket.status': { type: 'string', values: 'status groups', from: 'the ticket status matched against rules.statuses; else todo, in_progress or done from the status category' },
-  'ticket.status_name': { type: 'string', from: 'the status as the tracker names it' },
-  'ticket.assignee': { type: 'string', from: '"me" when the ticket is on you, else the assignee name' },
-  'ticket.done': { type: 'boolean', from: 'the status category is done' },
-  'ticket.started': { type: 'boolean', from: 'the status category is in progress' },
-  'ticket.hold_reason': { type: 'string', from: 'the comment that explains an on_hold status; missing when none does' },
-  'pr.open': { type: 'boolean', from: 'github: the ticket has an open PR; false when it has none' },
-  'pr.merged': { type: 'boolean', from: 'github: the ticket PR is merged; false when it has none' },
-  'pr.number': { type: 'number', from: 'github' },
-  'pr.checks': { type: 'string', values: ['passing', 'failing', 'running', 'none'], from: 'github' },
-  'pr.review': { type: 'string', values: ['approved', 'changes_requested', 'none'], from: 'github' },
-  'pr.base': { type: 'string', from: 'github: the branch the PR goes into' },
-  'pr.unanswered': { type: 'boolean', from: 'github: a human commented after your last comment and it is not an approval' },
-  'pr.commenter': { type: 'string', from: 'github: the author of that last comment' },
-  'comment.mentions_me': { type: 'boolean', from: 'tracker comments: an unanswered @-mention of you on the ticket' },
-  'comment.is_question': { type: 'boolean', from: 'the newest unanswered mention reads as a question' },
-  'comment.author': { type: 'string', from: 'the author of the newest unanswered mention' },
-  unanswered_count: { type: 'number', from: 'how many @-mentions of you on the ticket are unanswered' },
-  'run.failed': { type: 'boolean', from: 'github: the latest completed run of a workflow on the default branch failed; missing on tickets' },
-  'run.workflow': { type: 'string', from: 'github: the name of that workflow' },
-  'run.branch': { type: 'string', from: 'github: the branch it ran on, the default branch' },
-  'run.mine': { type: 'boolean', from: 'github: you pushed the commit or started the run' },
+  connector: { type: 'string', name: 'the source', from: 'the connector entry id the ticket came from' },
+  'ticket.key': { type: 'string', name: 'the ticket key', from: 'tracker connectors (jira, linear)' },
+  'ticket.status': { type: 'string', name: 'the ticket status', values: 'status groups', from: 'the ticket status matched against rules.statuses; else todo, in_progress or done from the status category' },
+  'ticket.status_name': { type: 'string', name: 'the status', from: 'the status as the tracker names it' },
+  'ticket.assignee': { type: 'string', name: 'the assignee', from: '"me" when the ticket is on you, else the assignee name' },
+  'ticket.done': { type: 'boolean', says: ['the ticket is done', 'the ticket is not done'], from: 'the status category is done' },
+  'ticket.started': { type: 'boolean', says: ['the ticket is started', 'the ticket is not started'], from: 'the status category is in progress' },
+  'ticket.hold_reason': { type: 'string', name: 'the hold reason', from: 'the comment that explains an on_hold status; missing when none does' },
+  'pr.open': { type: 'boolean', says: ['the PR is open', 'no PR is open'], from: 'github: the ticket has an open PR; false when it has none' },
+  'pr.merged': { type: 'boolean', says: ['the PR is merged', 'the PR is not merged'], from: 'github: the ticket PR is merged; false when it has none' },
+  'pr.number': { type: 'number', name: 'the PR number', from: 'github' },
+  'pr.checks': { type: 'string', name: 'the PR checks', values: ['passing', 'failing', 'running', 'none'], from: 'github' },
+  'pr.review': { type: 'string', name: 'the PR review', values: ['approved', 'changes_requested', 'none'], from: 'github' },
+  'pr.base': { type: 'string', name: 'the target branch', from: 'github: the branch the PR goes into' },
+  'pr.unanswered': { type: 'boolean', says: ['a comment on the PR waits for your answer', 'no comment on the PR waits for your answer'], from: 'github: a human commented after your last comment and it is not an approval' },
+  'pr.commenter': { type: 'string', name: 'the commenter', from: 'github: the author of that last comment' },
+  'comment.mentions_me': { type: 'boolean', says: ['you are mentioned and have not answered', 'no mention of you waits for an answer'], from: 'tracker comments: an unanswered @-mention of you on the ticket' },
+  'comment.is_question': { type: 'boolean', says: ['the mention is a question', 'the mention is not a question'], from: 'the newest unanswered mention reads as a question' },
+  'comment.author': { type: 'string', name: 'the author', from: 'the author of the newest unanswered mention' },
+  unanswered_count: { type: 'number', name: 'the number of mentions of you', from: 'how many @-mentions of you on the ticket are unanswered' },
+  'run.failed': { type: 'boolean', says: ['a workflow run failed', 'no workflow run failed'], from: 'github: the latest completed run of a workflow on the default branch failed; missing on tickets' },
+  'run.workflow': { type: 'string', name: 'the workflow', from: 'github: the name of that workflow' },
+  'run.branch': { type: 'string', name: 'the branch', from: 'github: the branch it ran on, the default branch' },
+  'run.mine': { type: 'boolean', says: ['the run is yours', 'the run is not yours'], from: 'github: you pushed the commit or started the run' },
 };
 
 /** The order status words are tried in: the chain's groups first, then any extra group in rules.statuses. */

package/lib/notify.mjs

@@ -26,7 +26,14 @@ const COMMANDS = {
   ],
 };
 
-const launch = (file, args, env) => execFile(file, args, { env: { ...process.env, ...env } }, () => {});
+/** True under a test runner (node:test passes NODE_TEST_CONTEXT to child processes, Vitest sets VITEST) or when WHOSE_TURN_NOTIFY=off. */
+export const muted = (env = process.env) => Boolean(env.NODE_TEST_CONTEXT || env.VITEST) || env.WHOSE_TURN_NOTIFY === 'off';
+
+const launch = (file, args, env) => {
+  if (!muted()) {
+    execFile(file, args, { env: { ...process.env, ...env } }, () => {});
+  }
+};
 
 export const notify = (title, body, { platform = process.platform, run = launch } = {}) => {
   const build = COMMANDS[platform];

package/lib/rules.mjs

@@ -19,8 +19,7 @@ export const compileRules = (rules) => {
   };
 };
 
-/** The user's own name reads as "you". */
-const youOr = (name, myName) => (myName && name === myName ? 'you' : name);
+export const youOr = (name, myName) => (myName && name === myName ? 'you' : name);
 
 const BLANK_ROW = {
   group: 'you', whose: 'You', done: false, started: false, rank: 3, why: '', hold_url: '', hold_full: '', status_since: '', status_group: '',
@@ -177,9 +176,12 @@ export const turnRows = ({ tickets = [], prs = [], comments = [], asks = [], run
   return rows;
 };
 
+/** The feed id of a ticket event the monitor itself recorded. */
+export const eventId = (event) => `event:${event.key}:${event.at}:${event.kind}`;
+
 const feedItem = (fields) => ({ who: '', text: '', body: '', key: '', title: '', ...fields });
 
-export const feedRows = ({ activity = [], events = [], tickets = [], comments = [], asks = [] }, { me = {}, rules, historyDays = 14 }) => {
+export const feedRows = ({ activity = [], events = [], tickets = [], comments = [], asks = [], notes = [] }, { me = {}, rules, historyDays = 14 }) => {
   const cutoff = daysAgoIso(historyDays);
   const recentComments = comments.filter((comment) => comment.at >= cutoff);
   const rows = [
@@ -193,7 +195,8 @@ export const feedRows = ({ activity = [], events = [], tickets = [], comments =
         text: oneline(comment.body), body: comment.body, url: comment.url,
       });
     }),
-    ...events.map((event) => feedItem({ id: `event:${event.key}:${event.at}:${event.kind}`, at: event.at, source: event.source, ref: event.key, key: event.key, kind: event.kind, text: event.text, url: event.url })),
+    ...events.map((event) => feedItem({ id: eventId(event), at: event.at, source: event.source, ref: event.key, key: event.key, kind: event.kind, text: event.text, url: event.url })),
+    ...notes.map((note) => feedItem({ id: note.id, at: note.at, source: note.source, ref: note.key, key: note.key, kind: 'note', who: 'you', text: note.text, body: note.text, url: note.url })),
   ];
   const timesByKey = groupBy([...events, ...recentComments], (item) => item.key);
   for (const ticket of tickets) {

package/lib/secrets.mjs

@@ -7,6 +7,8 @@ import { fileURLToPath } from 'node:url';
 const CREDENTIAL_SCRIPT = fileURLToPath(new URL('./platform/credential.ps1', import.meta.url));
 const POWERSHELL = ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-File', CREDENTIAL_SCRIPT];
 
+export const LINE_BREAK = /[\r\n]/;
+
 const quote = (text) => `"${text.replace(/[\\"]/g, '\\$&')}"`;
 
 const STORES = {
@@ -61,6 +63,11 @@ export const createSecrets = (dataDir, { platform = process.platform, run = exec
       return (stdout || '').trim() || (await fromFile(dataDir, service, account));
     },
     set: async (service, account, value) => {
+      for (const [field, text] of Object.entries({ service, account, value })) {
+        if (LINE_BREAK.test(text)) {
+          throw new Error(`The secret ${field} must not contain a line break.`);
+        }
+      }
       if (store && (await attempt(store.set(service, account, value))) !== null) {
         return;
       }

package/lib/store.mjs

@@ -1,4 +1,4 @@
-/** One workspace's files on disk: state.json (last poll per source), marks.json (seen, handled, notified, health alerts already announced), todos.json and cache.json (connector caches that are data). */
+/** One workspace's files on disk: state.json (last poll per source), marks.json (seen, handled with its info, notified, health alerts already announced), todos.json and cache.json (connector caches that are data). */
 import { mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
 import { join, resolve, sep } from 'node:path';
 import { DAY } from './text.mjs';
@@ -31,7 +31,7 @@ export const openStore = (dataDir, workspaceId) => {
   mkdirSync(dir, { recursive: true });
   const files = { state: join(dir, 'state.json'), marks: join(dir, 'marks.json'), todos: join(dir, 'todos.json'), cache: join(dir, 'cache.json') };
   const state = { version: 0, errors: {}, polled_at: '', fails: {}, sources: {}, events: [], ...readJson(files.state, {}) };
-  const marks = { seen: [], base: null, handled: {}, notified: [], notified_seeded: false, health_alerted: [], ...readJson(files.marks, {}) };
+  const marks = { seen: [], base: null, handled: {}, info: {}, notified: [], notified_seeded: false, health_alerted: [], ...readJson(files.marks, {}) };
   if (!marks.base) {
     marks.base = Date.now() - 3 * DAY;
   }

package/lib/trace.mjs

@@ -0,0 +1,45 @@
+/** The trace a row leaves in Handled when its turn passes to someone else: one phrase and the feed event behind it. */
+import { eventId, youOr } from './rules.mjs';
+import { DAY, oneline } from './text.mjs';
+
+const lastName = (text) => String(text).split(' → ').pop().trim();
+
+/** Ticket rows that were on you before a poll and are on someone else after it. */
+export const passedRows = (before, after) => {
+  const later = new Map(after.map((row) => [row.row_id, row]));
+  return before
+    .filter((row) => row.group === 'you' && row.row_id === row.key && later.get(row.row_id)?.group === 'others')
+    .map((row) => ({ before: row, after: later.get(row.row_id) }));
+};
+
+const mergedNow = ({ before, after }) => before.pr_state !== 'MERGED' && after.pr_state === 'MERGED';
+
+/** The newest comment on the ticket from the day before the move, as `{author, text}`, or null. */
+const commentBefore = (feed, key, at) => {
+  const found = feed.find((item) => item.kind === 'comment' && item.key === key && Date.parse(at) - Date.parse(item.at) < DAY);
+  return found ? { author: found.who, text: oneline(found.body || found.text, 4000) } : null;
+};
+
+/** `{outcome, event, detail}` built from what moved the row, or null when no event explains it. `events` are this poll's ticket events, `feed` is newest first, `me` is your name per source. */
+export const traceOf = (pair, events, feed, me = {}) => {
+  const own = events.filter((event) => event.key === pair.after.key && event.source === pair.after.source);
+  const reassigned = own.find((event) => event.kind === 'reassigned');
+  const status = own.find((event) => event.kind === 'status');
+  const merge = mergedNow(pair) && feed.find((item) => item.kind === 'merged' && item.key === pair.after.key);
+  if (merge) {
+    return { outcome: 'Merged', event: merge.id, detail: { summary: 'Pull request merged' } };
+  }
+  if (reassigned) {
+    const names = reassigned.text.split(' → ');
+    const name = names.at(-1).trim();
+    const base = name ? `Passed to ${name}` : 'Passed on';
+    const comment = commentBefore(feed, pair.after.key, reassigned.at);
+    const head = status ? `${base} · ${lastName(status.text)}` : base;
+    return {
+      outcome: comment ? `${head} · ${comment.text}` : head,
+      event: eventId(reassigned),
+      detail: { what: head, assignee: names.map((name) => youOr(name.trim(), me[pair.after.source])).join(' → '), ...(status ? { status: status.text } : {}), ...(comment ? { comment } : {}) },
+    };
+  }
+  return status ? { outcome: `Moved to ${lastName(status.text)}`, event: eventId(status), detail: { status: status.text } } : null;
+};

package/lib/workspace.mjs

@@ -1,7 +1,8 @@
 /** One workspace: polls its connector entries, stores each result by source, merges them by kind, evaluates the rules once per version and notifies. */
 import { openStore } from './store.mjs';
 import { compileRules, turnRows, feedRows, myMoves, isHandled, withHandled, turnCounts, ticketEvents } from './rules.mjs';
-import { makeKeyFinder, nowIso, daysAgoIso, unionCapped, DAY } from './text.mjs';
+import { makeKeyFinder, nowIso, oneline, daysAgoIso, unionCapped, DAY } from './text.mjs';
+import { passedRows, traceOf } from './trace.mjs';
 import { buildHandOff, snapshotOf, renderHandOff, frameHandOff } from './handoff.mjs';
 import { notify as desktopNotify } from './notify.mjs';
 import { DEFAULT_LIMITS, nextFails, assess, transition } from './health.mjs';
@@ -44,6 +45,7 @@ export const createWorkspace = (definition, { dataDir, historyDays, http, secret
   const listeners = new Set();
   let digest = '';
   let derived = null;
+  let marksVersion = 0;
   let freshAt = '';
   const startedAt = nowIso();
 
@@ -55,17 +57,34 @@ export const createWorkspace = (definition, { dataDir, historyDays, http, secret
     return base ? `${base}${key}` : '';
   };
 
+  const noteEvents = () => Object.entries(store.marks.info)
+    .filter(([rowId, detail]) => detail.note && store.marks.handled[rowId])
+    .map(([rowId, detail]) => ({ id: `note:${rowId}:${store.marks.handled[rowId]}`, at: store.marks.handled[rowId], source: detail.source, key: detail.key, text: detail.note, url: detail.url }));
+
   const rows = () => {
     const day = nowIso().slice(0, 10);
-    if (!derived || derived.version !== store.state.version || derived.day !== day) {
+    if (!derived || derived.version !== store.state.version || derived.day !== day || derived.marksVersion !== marksVersion) {
       const sources = merged();
-      const state = { ...sources, events: store.state.events };
+      const state = { ...sources, events: store.state.events, notes: noteEvents() };
       const context = { me: me(), rules, historyDays, ticketUrl };
-      derived = { version: store.state.version, day, turn: turnRows(sources, context), feed: feedRows(state, context) };
+      derived = { version: store.state.version, marksVersion, day, turn: turnRows(sources, context), feed: feedRows(state, context) };
     }
     return derived;
   };
 
+  /** Saves the marks and, when what rows() derives from them (a note on a handled row) may have moved, drops the derived rows. */
+  const marksChanged = (derivedMoved = true) => {
+    if (derivedMoved) {
+      marksVersion += 1;
+    }
+    store.saveMarks();
+  };
+
+  const unmark = (rowId) => {
+    delete store.marks.handled[rowId];
+    delete store.marks.info[rowId];
+  };
+
   const emit = () => {
     const message = { ws: definition.id, version: store.state.version, polled_at: store.state.polled_at, open_moves: myMoves(rows().turn, store.marks).length };
     for (const listener of listeners) {
@@ -143,6 +162,7 @@ export const createWorkspace = (definition, { dataDir, historyDays, http, secret
     const state = store.state;
     const errors = {};
     const ticketsBefore = merged().tickets;
+    const turnBefore = rows().turn;
     definition.connectors.forEach((entry, index) => {
       const outcome = outcomes[index];
       Object.assign(errors, outcome.errors);
@@ -155,9 +175,8 @@ export const createWorkspace = (definition, { dataDir, historyDays, http, secret
         delete state.sources[id];
       }
     }
-    if (ticketsBefore.length) {
-      state.events = [...ticketEvents(ticketsBefore, merged().tickets), ...state.events].slice(0, 500);
-    }
+    const fresh = ticketsBefore.length ? ticketEvents(ticketsBefore, merged().tickets) : [];
+    state.events = [...fresh, ...state.events].slice(0, 500);
     state.errors = errors;
     state.polled_at = nowIso();
     if (outcomes.some((outcome) => outcome.data)) {
@@ -171,6 +190,7 @@ export const createWorkspace = (definition, { dataDir, historyDays, http, secret
       digest = next;
       state.version += 1;
       store.saveState();
+      recordTrace(turnBefore, fresh);
       if (outcomes.some((outcome) => outcome.data)) {
         notifyNewMoves();
         store.marks.notified_seeded = true;
@@ -187,6 +207,36 @@ export const createWorkspace = (definition, { dataDir, historyDays, http, secret
     return { errors, rateLimited: outcomes.some((outcome) => outcome.rateLimited) };
   };
 
+  const rowRef = (row) => ({ key: row.key, source: row.source, url: row.ticket_url || row.url });
+
+  /** Adds the auto Handled mark to rows whose turn passed on in this poll and drops it from rows whose turn came back. */
+  const recordTrace = (turnBefore, fresh) => {
+    const { turn, feed } = rows();
+    const { handled, info } = store.marks;
+    let changed = false;
+    let notesMoved = false;
+    for (const pair of passedRows(turnBefore, turn)) {
+      const trace = traceOf(pair, fresh, feed, me());
+      if (trace) {
+        const rowId = pair.after.row_id;
+        notesMoved ||= Boolean(info[rowId]?.note);
+        handled[rowId] = [handled[rowId] || '', nowIso(), pair.after.activity_at || ''].sort().pop();
+        info[rowId] = { ...info[rowId], ...rowRef(pair.after), auto: true, outcome: trace.outcome, event: trace.event, detail: trace.detail };
+        changed = true;
+      }
+    }
+    for (const [rowId, detail] of Object.entries(info)) {
+      if (detail.auto && turn.some((row) => row.row_id === rowId && row.group === 'you')) {
+        notesMoved ||= Boolean(detail.note);
+        unmark(rowId);
+        changed = true;
+      }
+    }
+    if (changed) {
+      marksChanged(notesMoved);
+    }
+  };
+
   const quickLinks = () => mergeLinks(definition.links || [], definition.connectors.flatMap((entry) => (CONNECTORS[entry.type]?.links ? CONNECTORS[entry.type].links(entry) : [])));
 
   const expireHandled = () => {
@@ -194,12 +244,12 @@ export const createWorkspace = (definition, { dataDir, historyDays, http, secret
     let changed = false;
     for (const [rowId, at] of Object.entries(store.marks.handled)) {
       if (new Date(at).getTime() < limit) {
-        delete store.marks.handled[rowId];
+        unmark(rowId);
         changed = true;
       }
     }
     if (changed) {
-      store.saveMarks();
+      marksChanged();
     }
   };
 
@@ -244,6 +294,16 @@ export const createWorkspace = (definition, { dataDir, historyDays, http, secret
     return { ...identity(), moves: myMoves(rows().turn, store.marks), new_events: unread, todos: todosWithLinks().filter((todo) => !todo.done), polled_at: store.state.polled_at, errors: store.state.errors, health: health() };
   };
 
+  const noteOn = (rowId, text) => {
+    const line = oneline(text || '', 200);
+    const row = rows().turn.find((candidate) => candidate.row_id === rowId);
+    if (!store.marks.handled[rowId] || (!line && !store.marks.info[rowId]?.note)) {
+      return;
+    }
+    const { note, ...rest } = { ...(row ? rowRef(row) : {}), ...store.marks.info[rowId] };
+    store.marks.info[rowId] = line ? { ...rest, note: line } : rest;
+  };
+
   const updateMarks = (body) => {
     const marks = store.marks;
     if (body.seen) {
@@ -258,12 +318,15 @@ export const createWorkspace = (definition, { dataDir, historyDays, http, secret
     }
     for (const [rowId, value] of Object.entries(body.handled || {})) {
       if (value === null) {
-        delete marks.handled[rowId];
+        unmark(rowId);
       } else {
         marks.handled[rowId] = value;
       }
     }
-    store.saveMarks();
+    for (const [rowId, text] of Object.entries(body.notes || {})) {
+      noteOn(rowId, text);
+    }
+    marksChanged(Object.keys(body.handled || {}).length + Object.keys(body.notes || {}).length > 0);
     emit();
     return marked();
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "whose-turn",
-  "version": "1.0.0-alpha.5",
+  "version": "1.0.0-alpha.7",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -37,13 +37,15 @@
     "lint:style": "stylelint \"web/src/**/*.{vue,css}\"",
     "format": "prettier --write web/src",
     "check": "npm run typecheck && npm run lint && npm run lint:style && npm test && npm run test:web",
-    "test:web": "vitest run"
+    "test:web": "vitest run",
+    "mutation": "stryker run"
   },
   "bin": {
     "whose-turn": "server.mjs"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
+    "@stryker-mutator/core": "^10.1.1",
     "@testing-library/dom": "10.4.2",
     "@testing-library/vue": "8.1.0",
     "@types/node": "22.19.19",
@@ -66,5 +68,12 @@
     "vue": "^3.5.0",
     "vue-eslint-parser": "10.4.1",
     "vue-tsc": "3.3.13"
+  },
+  "overrides": {
+    "qs": "^6.16.1",
+    "fast-uri": "^3.1.9",
+    "zod": "^4.6.7",
+    "minimatch": "^11.0.4",
+    "glob": "^14.0.3"
   }
 }

package/server.mjs

@@ -13,6 +13,7 @@ import { openInbox } from './lib/inbox.mjs';
 import { openReports } from './lib/feedback.mjs';
 import { startApi } from './lib/api.mjs';
 import { notify } from './lib/notify.mjs';
+import { loadChangelog } from './lib/changelog.mjs';
 import { createUpdater, restartServer, runsInstalled } from './lib/update.mjs';
 
 const appDir = dirname(fileURLToPath(import.meta.url));
@@ -71,7 +72,7 @@ const saveConfig = async (rawWorkspaces) => {
 };
 
 try {
-  server = await startApi({ port: first.port, appDir, registry, requestPoll, saveConfig, secrets, inbox, http, reports, dataDir: first.dataDir, updater });
+  server = await startApi({ port: first.port, appDir, registry, requestPoll, saveConfig, secrets, inbox, http, reports, dataDir: first.dataDir, updater, changelog: loadChangelog(appDir, version) });
 } catch (error) {
   console.error(error.message);
   process.exit(1);