@leftoff/cli 0.9.17-beta.9 → 0.9.18-beta.1

package/ui/session-catchup.js

@@ -6,6 +6,8 @@
 // The recap's lines come from the transcript, so they go in as text afterwards
 // ([data-scu], fillSessionCatchup), never as markup.
 import { copyButtonHtml, fillCopy } from './copy-msg.js' // 0.9.11: Copy on Claude's messages
+import { mdInline } from './changelog-md.js'
+const SCU_MD = /^(goal|next|b-\d+)$/
 
 export function catchupButtonHtml(s, { esc, icon = () => '', busy = false } = {}) {
   if (!s || s.agent || String(s.id || '').startsWith('agent:')) return ''
@@ -107,7 +109,9 @@ export function fillSessionCatchup(root, ui) {
   if (!root || !root.querySelectorAll) return 0
   const t = sessionCatchupTexts(ui)
   let n = 0
-  for (const el of root.querySelectorAll('[data-scu]')) { el.textContent = t[el.getAttribute('data-scu')] || ''; n++ }
+  // 0.9.19: the recap's own words (goal, lines, Next) render `code` and **bold**: mdInline escapes
+  // everything first, so a line is still never markup of its own; the rest stays plain text
+  for (const el of root.querySelectorAll('[data-scu]')) { const k = el.getAttribute('data-scu'), v = t[k] || ''; if (SCU_MD.test(k)) el.innerHTML = mdInline(v, { links: false }); else el.textContent = v; n++ }
   const by = root.querySelector('[data-scu="by"]')
   if (by && !by.textContent) by.hidden = true
   const cb = root.querySelector('.scu .msg-copy') // 0.9.11: Copy's words, as an attribute

package/ui/start.js

@@ -51,8 +51,36 @@ export function startPick(data, ui = {}) {
   const where = ui.where === 'worktree' && !(repo && repo.git === false) ? 'worktree' : 'repo'
   // Permissions: what you picked, else what this board last used for that Mac (kept on the Mac you're connected to), else Ask me
   const mode = START_MODES.some((x) => x.v === ui.mode) ? ui.mode : m && START_MODES.some((x) => x.v === m.lastMode) ? m.lastMode : 'default'
-  return { m, repo, where, mode, project, also, dropped, missing }
-}
+  // 0.9.17 Claude Code or Codex: what you picked (when that Mac has both), else what it used last, else the one it has
+  const ag = m && m.agents ? m.agents : null
+  const agent = !ag ? 'claude' : ag.choice && (ui.agent === 'claude' || ui.agent === 'codex') ? ui.agent : ag.last || (ag.claude ? 'claude' : ag.codex ? 'codex' : 'claude')
+  // 1.0 Mode: what you picked (when it's possible for that agent there), else what that Mac used last for the agent, else how Start ran it before
+  const rs = m && m.runs ? m.runs : null
+  const okRun = (r) => !!(rs && rs.options && rs.options[agent] && rs.options[agent][r] && rs.options[agent][r].ok)
+  const dflt = agent === 'codex' ? 'board' : 'headless'
+  const lastRun = rs && rs.last ? rs.last[agent] : null
+  const run = !rs ? dflt : START_RUNS.some((x) => x.v === ui.run) && okRun(ui.run) ? ui.run : okRun(lastRun) ? lastRun : okRun(dflt) ? dflt : (START_RUNS.find((x) => okRun(x.v)) || { v: dflt }).v
+  return { m, repo, where, mode, project, also, dropped, missing, agent, agents: ag, run, runs: rs }
+}
+// 1.0 where the agent runs (src/start-run.js)
+export const START_RUNS = Object.freeze([
+  { v: 'headless', label: 'Headless', sub: 'chat in Live, from any device', glyph: '◇' },
+  { v: 'board', label: 'Board terminal', sub: 'a terminal here and on your phone', glyph: '▭' },
+  { v: 'app', label: 'My terminal app', sub: 'Ghostty, iTerm or Terminal', glyph: '▣' },
+])
+export function startRunIntro(agent, run) {
+  const AG = agent === 'codex' ? 'Codex' : 'Claude Code'
+  if (run === 'board') return 'Leftoff starts ' + AG + ' in a terminal it keeps on the Mac you pick. It shows in the board and on your phone, and it keeps running when you close the tab.'
+  if (run === 'app') return 'Leftoff starts ' + AG + ' in a terminal it keeps on the Mac you pick, and opens it in your terminal app. Closing that window doesn’t stop it: Open in Terminal (or leftoff attach) brings it back.'
+  return 'Leftoff starts ' + AG + ' on the Mac you pick, with no terminal. It shows on every board right away: talk to it in Live, and approve its edits and commands in Needs you, from any device.'
+}
+export const AGENT_NAMES = Object.freeze({ claude: 'Claude Code', codex: 'Codex' })
+// 0.9.17 the Permissions cards in Codex's words (src/codex-start.js CODEX_MODES_TEXT)
+export const CODEX_MODE_SUBS = Object.freeze({
+  default: { sub: 'Codex’s own settings', text: 'Codex runs with your own Codex settings: it asks before anything its sandbox doesn’t allow. You answer in its terminal.' },
+  acceptEdits: { sub: 'edits in the folder, asks for the rest', text: 'Codex may edit files and run commands inside the folder (its workspace-write sandbox); anything outside it asks first, in its terminal.' },
+  auto: { sub: 'no asks, sandboxed to the folder', text: 'Codex never stops to ask: commands run inside the folder’s sandbox, and anything the sandbox blocks fails back to Codex instead of asking you.' },
+})
 export const ADD_DIRS_MAX = 8 // src/claude-headless.js
 
 // The body New session posts (src/session-start.js): a project start carries
@@ -60,6 +88,8 @@ export const ADD_DIRS_MAX = 8 // src/claude-headless.js
 // added (0.9.16) carries just those folders.
 export function startBody(pick, prompt, { draft = null, atts = [] } = {}) {
   const b = { machine: pick.m.machine, cwd: pick.repo.path, prompt, where: pick.where, mode: pick.mode }
+  if (pick.agents) b.agent = pick.agent // 0.9.17 (a Mac that didn't say which it has gets none: Claude Code, as before)
+  if (pick.runs) b.run = pick.run // 1.0 (an older Mac gets none: the way it always started)
   if (pick.project) Object.assign(b, { project: pick.project.id, addDirs: pick.also.map((r) => r.path) })
   else if (pick.also && pick.also.length) b.addDirs = pick.also.map((r) => r.path) // 0.9.16 + Add another repo
   const ids = (atts || []).filter((a) => a && a.id && a.status === 'done').map((a) => a.id) // 0.9.13
@@ -127,6 +157,17 @@ export function modePillHtml(s, { esc, seen = null }) {
   return ' <span class="mode-pill m-' + esc(m) + '" data-tip="' + esc('Permissions: ' + modeLabel(m) + (h.state === 'running' ? '' : ' (when it runs again)')) + '">' + esc(modeLabel(m)) + '</span>'
 }
 
+// 1.0 A session in one of Leftoff's terminals: where it runs, by shape and
+// words. ▣ a terminal app is attached; ◌ running · detached (nobody looking;
+// it keeps running, Go or Open in Terminal brings it back); nothing otherwise.
+export function termPillHtml(s, { esc }) {
+  const t = s && s.terminal
+  if (!t || t.kind !== 'leftoff' || !t.termId || s.endedAt) return ''
+  if (t.apps > 0) return ' <span class="term-pill t-app" data-tip="' + esc('Open in a terminal app (leftoff attach). Closing that window leaves it running.') + '"><span aria-hidden="true">▣</span> in a terminal app</span>'
+  if (t.detached) return ' <span class="term-pill t-detached" data-tip="' + esc('Its terminal is running with no window on it. Go shows it here; Open in Terminal attaches a window. Only Stop or Exit ends it.') + '"><span aria-hidden="true">◌</span> running · detached</span>'
+  return ''
+}
+
 // Is a path inside one of a Mac's approved folders (its real paths)?
 export function underApproved(p, approved) {
   const x = String(p || '')
@@ -160,8 +201,8 @@ const ago = (iso, now) => {
   return Math.round(s / 86400) + 'd ago'
 }
 
-function opt({ k, v, label, sub = '', on = false, disabled = false, esc }) {
-  return '<button type="button" class="start-opt" role="radio" aria-checked="' + on + '" data-action="start-pick" data-k="' + esc(k) + '" data-v="' + esc(v) + '"' + (disabled ? ' disabled' : '') + '>' +
+function opt({ k, v, label, sub = '', on = false, disabled = false, tip = '', esc }) {
+  return '<button type="button" class="start-opt" role="radio" aria-checked="' + on + '" data-action="start-pick" data-k="' + esc(k) + '" data-v="' + esc(v) + '"' + (disabled ? ' disabled' : '') + (tip ? ' data-tip="' + esc(tip) + '"' : '') + '>' +
     '<span class="start-opt-main">' + label + '</span>' + (sub ? '<span class="start-opt-sub">' + sub + '</span>' : '') + '</button>'
 }
 
@@ -169,6 +210,7 @@ function opt({ k, v, label, sub = '', on = false, disabled = false, esc }) {
 export function startAskLine(ask, { clock = (x) => x } = {}) {
   if (!ask) return null
   if (ask.state === 'pending') return { tone: 'wait', text: 'Waiting for a yes on ' + ask.machine + ' (until ' + clock(ask.expiresAt) + '). It shows on that Mac’s board and as a notification.' + (ask.firstTime ? ' A first time in a folder asks there, unless it’s inside a folder approved there.' : '') }
+  if (ask.state === 'starting' && ask.agent === 'codex') return { tone: 'wait', text: 'Codex is running in a terminal on ' + ask.machine + '. Its session opens here as soon as Codex writes it (after its first message).' }
   if (ask.state === 'starting') return { tone: 'wait', text: 'Starting on ' + ask.machine + '…' }
   if (ask.state === 'declined') return { tone: 'bad', text: 'Declined on ' + ask.machine + '.' }
   if (ask.state === 'expired') return { tone: 'bad', text: 'Nobody confirmed it on ' + ask.machine + ' in time.' }
@@ -179,8 +221,10 @@ export function startAskLine(ask, { clock = (x) => x } = {}) {
 export function startPageHtml(data, ui = {}, { esc, icon, emoji = () => '', local = true, now = Date.now(), clock = (x) => x, draft = '', busy = false, atts = null, chipHtml = null, mayProject = true } = {}) {
   const pick = startPick(data, ui)
   const rule = startRule(data, pick, { local })
+  const codex = pick.agent === 'codex'
+  const AG = AGENT_NAMES[pick.agent] || 'Claude Code'
   let h = '<a class="back" href="#/">← All sessions</a>' +
-    '<div class="pagehead"><div><h1>New session</h1><div class="sub">Leftoff starts Claude Code on the Mac you pick. It shows on every board right away: talk to it in Live, approve its edits and commands in Needs you.</div></div></div>'
+    '<div class="pagehead"><div><h1>New session</h1><div class="sub">' + esc(startRunIntro(pick.agent, pick.run)) + '</div></div></div>'
   h += '<div class="start" data-start>'
   // Mac
   const ms = (data && data.machines) || []
@@ -188,6 +232,20 @@ export function startPageHtml(data, ui = {}, { esc, icon, emoji = () => '', loca
     ms.map((x) => opt({ k: 'machine', v: x.machine, on: !!pick.m && x.machine === pick.m.machine, disabled: !x.online, esc,
       label: esc((emoji(x.machine) ? emoji(x.machine) + ' ' : '') + x.machine), sub: esc(x.here ? (local ? 'this Mac' : 'the Mac you’re connected to') : x.online ? 'online' : 'offline') })).join('') +
     '</div></section>'
+  // Agent (0.9.17): only when that Mac has both
+  if (pick.agents && pick.agents.choice) {
+    h += '<section class="start-sec start-agent"><h2 class="start-h">Agent</h2><div class="start-opts" role="radiogroup" aria-label="Agent">' +
+      opt({ k: 'agent', v: 'claude', on: !codex, esc, label: 'Claude Code', sub: 'Anthropic' }) +
+      opt({ k: 'agent', v: 'codex', on: codex, esc, label: 'Codex', sub: 'OpenAI' }) +
+      '</div></section>'
+  }
+  // Mode (1.0): headless, the board's terminal, or your terminal app; the ones that Mac can't do say why
+  if (pick.runs && pick.runs.options) {
+    const o = pick.runs.options[pick.agent] || {}
+    h += '<section class="start-sec start-run"><h2 class="start-h">Mode</h2><div class="start-opts" role="radiogroup" aria-label="Mode">' +
+      START_RUNS.map((x) => { const can = o[x.v] || { ok: true }; return opt({ k: 'run', v: x.v, on: x.v === pick.run, disabled: !can.ok, tip: can.ok ? '' : can.why || '', esc, label: '<span class="run-glyph" aria-hidden="true">' + x.glyph + '</span> ' + esc(x.label), sub: esc(can.ok ? x.sub : 'not on this Mac') }) }).join('') +
+      '</div></section>'
+  }
   // Project (0.9.12): only when there are projects
   const projects = (pick.m && pick.m.projects) || []
   if (projects.length) {
@@ -228,17 +286,17 @@ export function startPageHtml(data, ui = {}, { esc, icon, emoji = () => '', loca
   // Where
   h += '<section class="start-sec"><h2 class="start-h">Where</h2><div class="start-opts start-where" role="radiogroup" aria-label="Where">' +
     opt({ k: 'where', v: 'repo', on: pick.where === 'repo', esc, label: 'In the repo', sub: 'on its current branch' }) +
-    opt({ k: 'where', v: 'worktree', on: pick.where === 'worktree', esc, label: 'New worktree', sub: pick.repo && pick.repo.git === false ? 'needs a git repo' : 'its own branch and folder', disabled: !!(pick.repo && pick.repo.git === false) }) +
+    opt({ k: 'where', v: 'worktree', on: pick.where === 'worktree', esc, label: 'New worktree', sub: pick.repo && pick.repo.git === false ? 'needs a git repo' : codex ? 'Codex’s own worktree' : 'its own branch and folder', disabled: !!(pick.repo && pick.repo.git === false) }) +
     '</div></section>'
   // Permissions (0.9.9)
   const mo = START_MODES.find((x) => x.v === pick.mode) || START_MODES[0]
-  const moreText = mo.text + ' ' + TERMINAL_MODE_HINT // behind the (?): the cards' own lines say enough
+  const moreText = codex ? (CODEX_MODE_SUBS[mo.v] || CODEX_MODE_SUBS.default).text : mo.text + ' ' + TERMINAL_MODE_HINT // behind the (?): the cards' own lines say enough
   h += '<section class="start-sec"><h2 class="start-h start-h-help">Permissions' + helpQHtml({ id: 'start-mode-help', label: 'About Permissions', text: moreText, open: !!ui.helpOpen }, { esc }) + '</h2><div class="start-opts start-mode" role="radiogroup" aria-label="Permissions">' +
-    START_MODES.map((x) => opt({ k: 'mode', v: x.v, on: x.v === mo.v, esc, label: esc(x.label), sub: esc(x.sub) })).join('') +
+    START_MODES.map((x) => opt({ k: 'mode', v: x.v, on: x.v === mo.v, esc, label: esc(x.label), sub: esc(codex ? CODEX_MODE_SUBS[x.v].sub : x.sub) })).join('') +
     '</div>' + helpMoreHtml({ id: 'start-mode-help', text: moreText, open: !!ui.helpOpen, cls: 'start-hint start-mode-hint' }, { esc }) + '</section>'
   // First message
   h += '<section class="start-sec"><h2 class="start-h" id="start-msg-h">First message</h2><div class="start-box">' +
-    composerBoxHtml({ submit: 'start', sendAction: 'start-send', draftKey: 'start', draft, ...(Array.isArray(atts) ? { attach: true, atts, chipHtml, sid: START_SID } : {}), may: rule.ok && !ui.ask, busy, placeholder: 'What should Claude do?', label: 'First message', inputClass: 'start-text', keys: 'Enter Meta+Enter Control+Enter' }) +
+    composerBoxHtml({ submit: 'start', sendAction: 'start-send', draftKey: 'start', draft, ...(Array.isArray(atts) && !codex ? { attach: true, atts, chipHtml, sid: START_SID } : {}), may: rule.ok && !(ui.ask && ui.ask.state !== 'starting'), busy, placeholder: codex ? 'What should Codex do? (or leave it empty)' : 'What should Claude do?', label: 'First message', inputClass: 'start-text', keys: 'Enter Meta+Enter Control+Enter' }) +
     '</div><p class="start-rule' + (rule.ok ? '' : ' bad') + '" role="status">' + esc(rule.text) + '</p>'
   const line = startAskLine(ui.ask, { clock })
   if (line) h += '<div class="start-ask ' + line.tone + '" role="status">' + esc(line.text) + (ui.ask && ['declined', 'expired', 'failed'].includes(ui.ask.state) ? ' <button type="button" class="btn" data-action="start-again">Try again</button>' : '') + '</div>'
@@ -458,20 +516,37 @@ export function headlessBarHtml(s, { esc, icon, may = true, busy = null, local =
   if (!h) return ''
   const from = s.startedFrom && s.startedFrom.device ? ' from ' + s.startedFrom.device : ''
   const where = s.machine ? ' on ' + s.machine : ''
+  const agent = h.agent === 'codex' || s.codingAgent === 'codex' ? 'Codex' : 'Claude Code'
+  // 1.0 the same conversation in a terminal: Leftoff's own (a terminal app attaches to it on the Mac itself)
+  const cont = may && h.state !== 'stopping' && h.state !== 'resuming' ? continueButtonHtml(s, 'board', { esc }) : ''
   let text, btn = ''
-  if (h.state === 'running') { text = 'Running' + where + ', started' + from + ' by Leftoff' + (h.awake ? ' · keeping it awake' : ''); if (may) btn = '<button type="button" class="btn" data-action="headless-stop" data-id="' + esc(s.id) + '">' + icon('square') + 'Stop</button>' }
+  if (h.state === 'running') { text = 'Running' + where + ', started' + from + ' by Leftoff' + (h.awake ? ' · keeping it awake' : ''); if (may) btn = cont + '<button type="button" class="btn" data-action="headless-stop" data-id="' + esc(s.id) + '">' + icon('square') + 'Stop</button>' }
   else if (h.state === 'stopping') text = 'Stopping' + where + '…'
-  else if (h.state === 'resuming') text = 'Starting Claude Code' + where + '…' // 0.9.9: Resume on its way
+  else if (h.state === 'resuming') text = 'Starting ' + agent + where + '…' // 0.9.9: Resume on its way
   else {
     // 0.9.13: Paused (its process went: a restart, an exit) is still open; a message resumes it, as does Stopped
     text = (h.error ? 'Claude Code stopped' + where : h.state === 'paused' ? 'Paused' + where + (h.pausedWhy && h.pausedWhy !== 'restart' ? '' : ' (Leftoff restarted)') : 'Stopped' + where) + (from ? ', started' + from : '') + ' · a message picks it up'
-    if (may) btn = '<button type="button" class="btn primary" data-action="headless-run" data-id="' + esc(s.id) + '">' + icon('play') + 'Resume here</button>'
+    if (may) btn = cont + '<button type="button" class="btn primary" data-action="headless-run" data-id="' + esc(s.id) + '">' + icon('play') + 'Resume here</button>'
   }
   return '<div class="headless-bar ' + esc(h.state) + '" data-sid="' + esc(s.id) + '"><span class="grow">' + icon('play') + esc(text) + '</span>' + btn + '</div>' +
     (h.error && h.state !== 'running' ? '<pre class="headless-err" data-headless-err="' + esc(s.id) + '"></pre>' : '') +
     (h.state !== 'stopping' && h.state !== 'resuming' ? headlessModeHtml(s, { esc, may, busy, local, helpOpen }) : '')
 }
 
+// 1.0 Continue in terminal / Continue headless: one button, the same conversation the other way
+export function continueButtonHtml(s, run, { esc }) {
+  const label = run === 'headless' ? 'Continue headless' : 'Continue in terminal'
+  const tip = run === 'headless' ? 'Ends it in the terminal, then picks the same conversation up headless (Live). Only when it’s idle.' : 'Ends the headless process, then picks the same conversation up in a terminal of Leftoff’s. Only when it’s idle.'
+  return '<button type="button" class="btn run-continue" data-action="run-continue" data-run="' + esc(run) + '" data-id="' + esc(s.id) + '" data-tip="' + esc(tip) + '"><span class="run-glyph" aria-hidden="true">' + (run === 'headless' ? '◇' : '▭') + '</span>' + esc(label) + '</button>'
+}
+// The same for a session in Leftoff's own terminal (not headless): where it runs, and the way to headless
+export function termBarHtml(s, { esc, may = true } = {}) {
+  const t = s && s.terminal
+  if (!s || s.headless || s.endedAt || !t || t.kind !== 'leftoff' || !t.termId) return ''
+  const where = t.apps > 0 ? 'In a terminal app' : t.detached ? 'Running · detached' : 'In Leftoff’s terminal'
+  return '<div class="headless-bar term-bar" data-sid="' + esc(s.id) + '"><span class="grow"><span class="run-glyph" aria-hidden="true">' + (t.apps > 0 ? '▣' : t.detached ? '◌' : '▭') + '</span>' + esc(where + (s.machine ? ' on ' + s.machine : '')) + '</span>' + (may ? continueButtonHtml(s, 'headless', { esc }) : '') + '</div>'
+}
+
 // The session page's Permissions switch for a session Leftoff runs: the same
 // three as New session. Running, it switches Claude Code mid-session; stopped,
 // it's the mode Resume starts it in.

package/ui/walk-lines.js

@@ -0,0 +1,119 @@
+// 2026-10-30 (walkthrough round 3) Line references for "Ask about this change":
+// click a line number in a walkthrough's diff to pick it, shift-click or drag
+// for a range, Cmd/Ctrl-click to add another range (another file, another
+// step). On a phone: tap to pick, tap another line of the same snippet to
+// stretch it, tap in another snippet to add one. The picks show as chips over
+// the ask box; asking puts each ref and its exact lines into the chat box.
+//
+// A pick is a run of rows of ONE drawn patch (a step's snippet, a file in the
+// Files view), by row index into diff-view.js's parsePatch rows, so it means
+// the same lines in the unified and the split view. Pure: no DOM here.
+import { parsePatch } from './diff-view.js'
+
+const rowsCache = new Map()
+// patch -> parsePatch(patch).rows (kept a little while: the same patch is asked for often)
+export function rowsOf(patch) {
+  const k = String(patch == null ? '' : patch)
+  let r = rowsCache.get(k)
+  if (!r) { r = parsePatch(k).rows; rowsCache.set(k, r); if (rowsCache.size > 300) rowsCache.delete(rowsCache.keys().next().value) }
+  return r
+}
+const isLine = (r) => r && (r.k === 'add' || r.k === 'del' || r.k === 'ctx')
+
+// The numbers a run of rows covers: the new side when any row has a new number
+// (what the file reads now), else the old side (only removed lines).
+export function rangeInfo(rows, a, b) {
+  const lo = Math.min(a, b), hi = Math.max(a, b)
+  const ls = (rows || []).slice(lo, hi + 1).filter(isLine)
+  if (!ls.length) return null
+  const ns = ls.filter((r) => r.n != null).map((r) => r.n)
+  const side = ns.length ? 'new' : 'old'
+  const xs = side === 'new' ? ns : ls.map((r) => r.o).filter((x) => x != null)
+  return { side, from: Math.min(...xs), to: Math.max(...xs), lines: ls.length }
+}
+// "src/x.js:12–18", "repo · src/x.js:40", "src/x.js:7–9 (old)" for removed lines only.
+// label: the path as a person reads it (semdiff.js pathLabel)
+export function refLabel(label, info) {
+  if (!info) return String(label || '')
+  return String(label || '') + ':' + (info.from === info.to ? info.from : info.from + '–' + info.to) + (info.side === 'old' ? ' (old)' : '')
+}
+// The exact lines, the way the walkthrough's model reads them: "+ 13 │ text",
+// "- o12 │ text" (removed, its old number), "  14 │ text" (unchanged).
+export function refLinesText(rows, a, b, { max = 80 } = {}) {
+  const lo = Math.min(a, b), hi = Math.max(a, b)
+  const ls = (rows || []).slice(lo, hi + 1).filter(isLine)
+  const out = ls.slice(0, max).map((r) => (r.k === 'add' ? '+ ' + r.n : r.k === 'del' ? '- o' + r.o : '  ' + r.n) + ' │ ' + r.t)
+  if (ls.length > max) out.push('  … ' + (ls.length - max) + ' more lines')
+  return out.join('\n')
+}
+
+// ---------------------------------------------------------------- picking
+// A pick: { k (which drawn patch), file, step, x (where it started), a, b }.
+// ev: { shift, add (Cmd/Ctrl), touch } -> the new list (never the same array).
+const inside = (p, ri) => ri >= p.a && ri <= p.b
+export function mergePicks(list) {
+  const out = []
+  for (const p of list) {
+    const q = out.find((o) => o.k === p.k && p.a <= o.b + 1 && p.b >= o.a - 1)
+    if (q) { q.a = Math.min(q.a, p.a); q.b = Math.max(q.b, p.b) } else out.push({ ...p })
+  }
+  return out
+}
+export function pickLine(list, at, ev = {}) {
+  const cur = (list || []).map((p) => ({ ...p }))
+  const one = { k: at.k, file: at.file, step: at.step || null, x: at.ri, a: at.ri, b: at.ri }
+  const lastOf = () => { for (let i = cur.length - 1; i >= 0; i--) if (cur[i].k === at.k) return i; return -1 }
+  if (ev.shift) {
+    const i = lastOf()
+    if (i < 0) return mergePicks([...cur, one])
+    const p = cur[i]; p.a = Math.min(p.x, at.ri); p.b = Math.max(p.x, at.ri)
+    return mergePicks(cur)
+  }
+  if (ev.add) {
+    const i = cur.findIndex((p) => p.k === at.k && inside(p, at.ri))
+    if (i >= 0) { cur.splice(i, 1); return cur }
+    return mergePicks([...cur, one])
+  }
+  if (ev.touch) {
+    const i = cur.findIndex((p) => p.k === at.k && inside(p, at.ri))
+    if (i >= 0) { cur.splice(i, 1); return cur } // a tap on a picked line lets it go
+    const j = lastOf()
+    if (j >= 0 && j === cur.length - 1) { const p = cur[j]; p.a = Math.min(p.x, at.ri); p.b = Math.max(p.x, at.ri); return mergePicks(cur) } // a second tap stretches it
+    return mergePicks([...cur, one])
+  }
+  if (cur.length === 1 && cur[0].k === at.k && cur[0].a === at.ri && cur[0].b === at.ri) return []
+  return [one]
+}
+// dragging: the pick at index i stretched from where it started to ri
+export function dragTo(list, i, ri) {
+  const cur = (list || []).map((p) => ({ ...p }))
+  const p = cur[i]
+  if (!p) return cur
+  p.a = Math.min(p.x, ri); p.b = Math.max(p.x, ri)
+  return cur
+}
+
+// ---------------------------------------------------------------- asking
+// picks + how to read each one -> [{ label, text, step }] ; read(p) -> { rows, label, stepTitle }
+export function describePicks(list, read) {
+  const out = []
+  for (const p of list || []) {
+    const r = read(p)
+    if (!r || !r.rows) continue
+    const info = rangeInfo(r.rows, p.a, p.b)
+    if (!info) continue
+    out.push({ label: refLabel(r.label, info), text: refLinesText(r.rows, p.a, p.b), stepTitle: r.stepTitle || '', info })
+  }
+  return out
+}
+// The words that go into the chat box: each ref with its lines in a diff
+// fence, then the question. refs: describePicks' answer.
+export function refsPrompt(refs, question) {
+  const q = String(question || '').trim()
+  if (!refs || !refs.length) return q
+  const blocks = refs.map((r) => {
+    const fence = /```/.test(r.text) ? '~~~~' : '```'
+    return '`' + r.label + '`' + (r.stepTitle ? ' (' + r.stepTitle + ')' : '') + ':\n' + fence + 'diff\n' + r.text + '\n' + fence
+  })
+  return (refs.length === 1 ? 'About these lines:' : 'About these ' + refs.length + ' places:') + '\n\n' + blocks.join('\n\n') + (q ? '\n\n' + q : '')
+}

package/ui/walk-md.js

@@ -0,0 +1,40 @@
+// 0.9.19 (Joel: "Should we rendering md in the walk through? (and when
+// downloaded)"): a walkthrough's words are Markdown the model wrote, so they
+// render the way the board renders Claude's replies: the same renderer
+// (ui/handoffs.js renderDoc, ui/changelog-md.js mdInline), which escapes
+// everything first (raw HTML shows as text and never runs) and makes a link
+// only for https (new tab, rel=noopener). Titles are inline only (code, bold,
+// italic; no links, since a title sits in buttons and tips); a step's why gets
+// paragraphs, lists and fenced code too. The export uses the same HTML with no
+// copy buttons (it has no script). Copy as Markdown stays the raw text.
+import { mdInline } from './changelog-md.js'
+import { renderDoc } from './handoffs.js'
+import { codeCopyButton } from './code-copy.js'
+
+// a title: inline only
+export function walkInline(s) { return mdInline(String(s == null ? '' : s), { links: false, em: true }) }
+// a callout or the summary: inline, with https links
+export function walkInlineLinks(s) { return mdInline(String(s == null ? '' : s), { links: true, em: true }) }
+// The export links out to nothing (one offline file): a link there is its words,
+// with the address after them in brackets when the words aren't the address.
+export function unlink(html) {
+  return String(html).replace(/<a href="([^"]*)"(?: target="_blank" rel="noopener")?>([\s\S]*?)<\/a>/g, (_, href, inner) =>
+    inner.replace(/<[^>]+>/g, '') === href || inner.replace(/<[^>]+>/g, '') === href.replace(/&amp;/g, '&') ? '<span class="u">' + inner + '</span>' : inner + ' <span class="u">(' + href + ')</span>')
+}
+// a step's why: blocks (paragraphs, lists, fenced code), no file links
+export function walkBlock(s, { exported = false } = {}) {
+  const h = renderDoc(String(s == null ? '' : s), { files: false })
+  return exported ? unlink(h.split(codeCopyButton()).join('')) : h
+}
+// the export's inline words: rendered, nothing linked
+export function walkInlineExport(s) { return unlink(walkInlineLinks(s)) }
+// the same words as plain text, for a data-tip, an aria-label or the deck's "now" line
+export function mdPlain(s) {
+  return String(s == null ? '' : s)
+    .replace(/`([^`]+)`/g, '$1')
+    .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1')
+    .replace(/\*\*(.+?)\*\*/g, '$1')
+    .replace(/~~(.+?)~~/g, '$1')
+    .replace(/(^|[^\w*])\*([^*\s][^*]*?)\*(?![\w*])/g, '$1$2')
+    .replace(/(^|[^\w])_([^_\s][^_]*?)_(?!\w)/g, '$1$2')
+}

package/ui/walk-pop.js

@@ -15,20 +15,39 @@ export function sizeWords(z) {
   if (z.files === 0) return { kind: 'none', text: 'No changes yet' }
   return { kind: 'some', text: plural(z.files, 'file') + ' · +' + n0(z.add) + ' −' + n0(z.del) }
 }
-export function sizeLineHtml(z, { esc, icon }) {
+export function sizeLineHtml(z, { esc, icon, reviewed = null }) {
   const w = sizeWords(z)
   if (!w) return ''
-  return w.kind === 'none'
+  return (w.kind === 'none'
     ? '<span class="fs-wt-meta none">' + icon('circle-dashed') + esc(w.text) + '</span>'
-    : '<span class="fs-wt-meta">' + esc(w.text) + '</span>'
+    : '<span class="fs-wt-meta">' + esc(w.text) + '</span>') + walkBadgeHtml(walkProgress(z, reviewed), { esc, icon })
+}
+// 2026-10-30 (asked: "if you've gone through a walk through, should we have a way of denoting that
+// in the right sidebar where that button is?"): the walkthrough you last opened for this scope
+// (change-size's walk: { fp, steps, changed }) and how many of its steps you marked reviewed ->
+// null (never opened, or nothing marked yet) | { kind: 'part' | 'done', text, tip }
+export function walkProgress(z, reviewed) {
+  const wk = z && z.walk
+  const n = wk && Number(wk.steps)
+  const r = Math.max(0, Math.min(n || 0, Number(reviewed) || 0))
+  if (!n || !r) return null
+  const ch = wk.changed > 0 ? wk.changed + (wk.changed === 1 ? ' file' : ' files') + ' changed since' : ''
+  const done = r >= n
+  const text = (done ? 'Reviewed' : r + ' of ' + n + ' reviewed') + (ch ? ' · ' + ch : '')
+  const tip = (done ? 'You marked every step of this walkthrough reviewed' : 'You marked ' + r + ' of its ' + n + ' steps reviewed') + (ch ? '; ' + ch + ' it was written' : '')
+  return { kind: done ? 'done' : 'part', text, tip }
+}
+export function walkBadgeHtml(p, { esc, icon }) {
+  if (!p) return ''
+  return '<span class="fs-wt-rv fs-wt-rv-' + p.kind + '" data-tip="' + esc(p.tip) + '">' + (p.kind === 'done' ? icon('check') : '<i class="wt-chg-g" aria-hidden="true"></i>') + '<span>' + esc(p.text) + '</span></span>'
 }
 
 // the button (and, on touch, its (i)); data-pop names the popover it explains itself with
-export function walkButtonHtml(s, { esc, icon, on = false, size = null }) {
+export function walkButtonHtml(s, { esc, icon, on = false, size = null, reviewed = null }) {
   const id = esc(s.id)
   return '<span class="fs-wt-wrap">' +
     '<button type="button" class="btn fs-wt' + (on ? ' on' : '') + (sizeWords(size) && sizeWords(size).kind === 'none' ? ' none' : '') + '" data-action="' + (on ? 'wt-close' : 'wt-open') + '" data-id="' + id + '" aria-pressed="' + on + '" data-pop="wt">' +
-      icon('git-compare') + '<span class="fs-wt-l"><span class="fs-wt-v">Walk me through it</span><span class="fs-wt-size" data-id="' + id + '">' + sizeLineHtml(size, { esc, icon }) + '</span></span></button>' +
+      icon('git-compare') + '<span class="fs-wt-l"><span class="fs-wt-v">Walk me through it</span><span class="fs-wt-size" data-id="' + id + '">' + sizeLineHtml(size, { esc, icon, reviewed }) + '</span></span></button>' +
     '<button type="button" class="fs-pop-i" data-pop-open="wt" data-id="' + id + '" aria-label="What Walk me through it does" aria-expanded="false">' + icon('info') + '</button>' +
   '</span>'
 }

package/ui/walk-spots.js

@@ -0,0 +1,89 @@
+// 2026-10-30 (walkthrough round 3) "Next spot to really look at": the button in
+// the walkthrough's toolbar (and the n key) jumps to the next place that
+// deserves a real look, across steps, in reading order: the lines a callout
+// flags, the spots the model named (src/semdiff.js validateSpots), and, when
+// it named none, this file's heuristic: each Core snippet, plus risky-looking
+// changes anywhere (removed logic, auth and permissions, config and
+// migrations, error handling). Supporting snippets only when nothing else is
+// left. Each spot carries a short reason, shown as a tag at the line. Pure.
+import { parsePatch } from './diff-view.js'
+
+export const SPOT_WORDS = { look: 'Look closely', assumption: 'Assumption', untested: 'Untested' }
+const AUTH_WORDS = ['auth', 'permission', 'role', 'admin', 'token', 'secret', 'password', 'passwd', 'csrf', 'session', 'login', 'logout', 'acl', 'grant', 'privilege', 'sudo', 'jwt', 'oauth', 'cookie', 'signature', 'verify']
+// a word on its own or the start of a camelCase part ("isAdmin", "checkPermission", "AUTH_KEY")
+const AUTH = new RegExp('(?:(?<![A-Za-z])(?:' + AUTH_WORDS.join('|') + ')|(?<![A-Za-z])(?:' + AUTH_WORDS.map((x) => x.toUpperCase()).join('|') + ')|(?<=[a-z])(?:' + AUTH_WORDS.map((x) => x[0].toUpperCase() + x.slice(1)).join('|') + ')|(?<![A-Za-z])(?:' + AUTH_WORDS.map((x) => x[0].toUpperCase() + x.slice(1)).join('|') + '))')
+const ERR = /\b(catch|throw|throws|raise|except|finally|reject|rescue|panic|recover|try)\b|\.catch\(|\berr(or)?s?\b/i
+const MIGRATION = /(^|\/)(migrations?|migrate|db\/schema)(\/|\.)|\.sql$/i
+const CONFIG = /(^|\/)(config|settings|\.github\/workflows)(\/|\.|$)|\.(ya?ml|toml|ini|conf)$|(^|\/)(Dockerfile|package\.json|\.env\.example|wrangler\.toml|tsconfig\.json)$/i
+const COMMENT = /^\s*(\/\/|#|\*|\/\*|--|;)/
+
+const isLine = (r) => r.k === 'add' || r.k === 'del' || r.k === 'ctx'
+const sideOf = (r) => (r.k === 'del' ? 'old' : 'new')
+const numOf = (r) => (r.k === 'del' ? r.o : r.n)
+
+// One snippet (a patch, its file) -> { why, side, line, risk } or null when nothing in it changed.
+export function snippetRisk(patch, file) {
+  const rows = parsePatch(patch).rows
+  const ch = rows.filter((r) => r.k === 'add' || r.k === 'del')
+  if (!ch.length) return null
+  const at = (r, why, risk = true) => ({ why, side: sideOf(r), line: numOf(r), risk })
+  const first = ch.find((r) => r.k === 'add') || ch[0] // what the file reads now, when there's any
+  if (MIGRATION.test(String(file || ''))) return at(first, 'Migration')
+  // removed logic: a run of 3+ removed code lines with (almost) nothing added in its place
+  for (let i = 0; i < rows.length; i++) {
+    if (rows[i].k !== 'del') continue
+    let j = i, dels = 0, adds = 0
+    while (j < rows.length && (rows[j].k === 'del' || rows[j].k === 'add')) { if (rows[j].k === 'del' && rows[j].t.trim() && !COMMENT.test(rows[j].t)) dels++; if (rows[j].k === 'add' && rows[j].t.trim()) adds++; j++ }
+    if (dels >= 3 && adds * 2 < dels) return at(rows[i], 'Removed logic')
+    i = j - 1
+  }
+  const code = ch.filter((r) => r.t.trim() && !COMMENT.test(r.t))
+  const a = code.find((r) => AUTH.test(r.t))
+  if (a) return at(a, 'Auth / permissions')
+  const e = code.find((r) => ERR.test(r.t))
+  if (e) return at(e, 'Error handling')
+  if (CONFIG.test(String(file || ''))) return at(first, 'Config')
+  return at(first, 'Core change', false)
+}
+
+// data (a walkthrough) + its steps in reading order -> the spots, in order:
+// [{ step, snip, hunk, file, side, line, why, kind }] (kind: callout | model | risk | core | sup)
+export function spotsFor(data, order) {
+  const steps = order || (data && data.steps) || []
+  const model = data && Array.isArray(data.spots) ? data.spots : []
+  const main = [], sup = []
+  for (const st of steps) {
+    const core = st.tag === 'Core'
+    const snips = st.snippets || []
+    snips.forEach((sn, i) => {
+      const here = []
+      const lineIn = (side, line) => parsePatch(sn.patch).rows.some((r) => isLine(r) && (side === 'old' ? r.o : r.n) === line)
+      for (const c of st.callouts || []) if (c.hunk === sn.hunk && lineIn(c.side, c.line)) here.push({ side: c.side, line: c.line, why: SPOT_WORDS[c.kind] || SPOT_WORDS.look, kind: 'callout' })
+      for (const m of model) if (m.step === st.id && m.hunk === sn.hunk && lineIn(m.side, m.line) && !here.some((x) => x.side === m.side && x.line === m.line)) here.push({ side: m.side, line: m.line, why: m.why || 'Worth a look', kind: 'model' })
+      if (!here.length && !model.length) {
+        const r = snippetRisk(sn.patch, sn.file)
+        if (r && (r.risk || core)) here.push({ side: r.side, line: r.line, why: r.why, kind: r.risk ? 'risk' : 'core' })
+        else if (r) sup.push({ step: st.id, snip: i, hunk: sn.hunk, file: sn.file, side: r.side, line: r.line, why: 'Supporting', kind: 'sup' })
+      } else if (!here.length && core) {
+        // the model named spots, just none here: a Core snippet still gets one
+        const r = snippetRisk(sn.patch, sn.file)
+        if (r) here.push({ side: r.side, line: r.line, why: r.risk ? r.why : 'Core change', kind: r.risk ? 'risk' : 'core' })
+      }
+      here.sort((x, y) => x.line - y.line)
+      for (const x of here) main.push({ step: st.id, snip: i, hunk: sn.hunk, file: sn.file, ...x })
+    })
+  }
+  return main.length ? main : sup
+}
+
+// The spot after (dir 1) or before (-1) index cur, wrapping; -1 when there are none.
+export function nextSpotIndex(n, cur, dir = 1) {
+  if (!n) return -1
+  if (cur == null || cur < 0) return dir > 0 ? 0 : n - 1
+  return ((cur + dir) % n + n) % n
+}
+// "2 of 7 spots" once you've started, "7 spots" before
+export function spotCountWords(n, cur) {
+  if (!n) return 'No spots'
+  return (cur != null && cur >= 0 ? (cur + 1) + ' of ' + n : String(n)) + (n === 1 ? ' spot' : ' spots')
+}