@leftoff/cli 0.9.6 → 0.9.7

package/docs/SECURITY.md

@@ -94,6 +94,8 @@ A relayed request is replayed against the Mac's own board from inside the daemon
 
 When your hosted board is open on a Mac that runs Leftoff, the page sends the same sealed requests straight to that Mac's daemon at `http://127.0.0.1:7429/v1/relay/direct` instead of to the relay. Nothing new is trusted: the daemon opens them with the same per-device key (and the same replay and time checks), runs them the same way (a remote device, the rules above), and seals the answer. The page only switches after the daemon says it's on your account and a sealed round trip through it works, so another Leftoff on that port (someone else's account) can't serve your board: it can't open the request or forge the answer. The door is loopback only, never through a proxy, off when Use from anywhere is off, and answers CORS for exactly one origin, `https://<your name>.leftoff.dev` (with Chrome's Private Network Access header); any other page gets a 403 it can't read. If the direct path fails, the request goes through the relay once more and the board stays on the relay until a later check finds the direct path again.
 
+Since 0.9.7 the page also tries `https://leftoff.localhost/v1/relay/direct` (Leftoff's own Caddy from `leftoff setup`, bound to loopback; it rewrites Host, drops X-Forwarded-*, and passes the page's Origin through), since Safari won't let an https page call plain `http://127.0.0.1`. A request that came in through this door came from a browser on this Mac, from your own board's origin, sealed with a paired key, so it may also do the one thing only this Mac's own browser may do: **Restore** (`POST /v1/restore`, which opens Ghostty tabs here). The daemon marks such requests with a second in-memory secret that only the door sets; a sealed request can't carry it, and every other endpoint treats a direct request exactly like the relay (a paired remote device). Through the relay, from a phone or another Mac, Restore stays off.
+
 ### Logging
 
 The Worker never logs request or response bodies (it can't read them anyway) and stores only what's listed above, in your Durable Object. `wrangler.toml` turns Workers observability (request logs) off. Cloudflare's edge keeps its usual metadata for any site (IP, hostname, path such as `/_relay/api`, status), under its own policies.

package/mod/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "leftoff",
-  "version": "0.9.6",
+  "version": "0.9.7",
   "description": "Leftoff (formerly Checkpoints): WTF was I working on? Tracks every Claude Code session on this machine, writes a 3-line checkpoint when one goes quiet, and adds /cp (checkpoint now), /cp-name and a /leftoff pane. Talks to the local Leftoff daemon on 127.0.0.1:7429 and falls back to writing markdown in ~/checkpoints.",
   "author": {
     "name": "Joel"

package/mod/hooks/register.js

@@ -28,7 +28,7 @@ const END_TIMEOUT_MS = 1000
 const MODEL_TIMEOUT_MS = 20000
 
 // Module state. $.state is not used: the pane redraws with $.ui.invalidate.
-const MOD_VERSION = '0.9.6' // keep in step with .claude-plugin/plugin.json
+const MOD_VERSION = '0.9.7' // keep in step with .claude-plugin/plugin.json
 
 const st = {
   internal: false,
@@ -103,6 +103,7 @@ async function api($, method, path, body, timeoutMs) {
 // Every event goes through here: post, or spool a unique file (fs.write isn't atomic).
 async function sendOrSpool($, type, data, timeoutMs) {
   if (st.internal || !st.sessionId) return null
+  try { await ensureSetup($) } catch {} // a setup that failed leaves the fallback below to name the spool file's folder
   const ev = { v: 1, type, sessionId: st.sessionId, at: nowIso(), capture: 'mod', machine: st.machine, data: data || {} }
   st.record = applyEvent(st.record || { id: st.sessionId, turns: 0, turnsSinceCheckpoint: 0, backgroundTasks: 0 }, ev)
   const r = await api($, 'POST', '/v1/events', { events: [ev] }, timeoutMs)
@@ -115,7 +116,17 @@ async function sendOrSpool($, type, data, timeoutMs) {
     return j
   }
   try {
-    await $.fs.write(st.root + '/.spool/' + st.machine + '/' + st.sessionId + '/' + Date.now() + '-' + rand() + '.json', JSON.stringify({ events: [ev] }) + '\n')
+    // An absolute root even when setup never came: without one the concat
+    // makes st.root null a relative "null/.spool" beside the session's cwd.
+    let root = st.root
+    if (!root) {
+      const home = (await $.env.get('HOME')) || (await $.env.get('USERPROFILE')) || ''
+      if (home) root = home.replace(/[\\/]+$/, '') + '/checkpoints' // never a bare "/checkpoints"
+    }
+    // Only an absolute folder; otherwise skip the file but still keep the registry below.
+    if (root && /^([A-Za-z]:[\\/]|\/)/.test(String(root))) {
+      await $.fs.write(String(root) + '/.spool/' + (st.machine || 'unknown') + '/' + st.sessionId + '/' + Date.now() + '-' + rand() + '.json', JSON.stringify({ events: [ev] }) + '\n')
+    }
   } catch {}
   try {
     await $.store.set('session:' + st.sessionId, {
@@ -160,6 +171,20 @@ async function loadSetup($) {
   st.machine = resolveMachine({ env: await $.env.get('CHECKPOINTS_MACHINE'), hostname, cfg: st.cfg })
 }
 
+// loadSetup runs once per process and every sender awaits the same attempt:
+// a hook that fires before session.start (classic.SessionStart on a cold
+// boot, the old null/.spool race) waits for these values instead of reading
+// st at its initial state.
+let setupPromise = null
+function ensureSetup($) {
+  if (!setupPromise) {
+    const p = loadSetup($)
+    setupPromise = p
+    p.catch(() => { if (setupPromise === p) setupPromise = null }) // a failed setup tries again on the next event
+  }
+  return setupPromise
+}
+
 async function readRepo($, cwd) {
   let repo = null
   try {
@@ -931,7 +956,7 @@ export function register(on, options) {
   on('session.start', async ($, e, next) => {
     try {
       if (await isInternal($)) { st.internal = true; return next(e) }
-      await loadSetup($)
+      try { await ensureSetup($) } catch {} // the same attempt an early hook may have started; a failure still says hello
       st.sessionId = await $.session.id()
       const cwd = await $.session.cwd()
       const repo = await readRepo($, cwd)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leftoff/cli",
-  "version": "0.9.6",
+  "version": "0.9.7",
   "description": "Leftoff: WTF was I working on? Tracks every Claude Code session, writes a 3-line checkpoint when one goes quiet, and gives you a daily digest and a board, on your Mac and (optionally) your phone.",
   "keywords": [
     "claude",

package/ui/app.css

@@ -35,6 +35,12 @@
   --toast-shadow: 0 10px 30px rgba(0,0,0,.4);
   --chevron: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='12' viewBox='0 0 12 12'%3E%3Cpath d='M2.5 4.5 6 8l3.5-3.5' fill='none' stroke='%238b93a7' stroke-width='1.6' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/svg%3E");
   --radius: 14px;
+  --btn-bg: #1d2433;
+  --btn-hover: #252d40;
+  --btn-active: #161b26;
+  --btn-line: #3a4560;
+  --btn-line-hover: #56637f;
+  --btn-shadow: none;
   --mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
 }
 /* Light: a paper-white page with cool-gray structure, not an inverted dark.
@@ -75,6 +81,12 @@
   --card-shadow: 0 1px 2px rgba(22,26,36,.04), 0 2px 8px rgba(22,26,36,.04);
   --toast-shadow: 0 10px 30px rgba(22,26,36,.16);
   --chevron: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='12' viewBox='0 0 12 12'%3E%3Cpath d='M2.5 4.5 6 8l3.5-3.5' fill='none' stroke='%235b6478' stroke-width='1.6' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/svg%3E");
+  --btn-bg: #ffffff;
+  --btn-hover: #f4f6fa;
+  --btn-active: #e9ecf2;
+  --btn-line: #c7cedb;
+  --btn-line-hover: #9aa3b5;
+  --btn-shadow: 0 1px 1px rgba(22,26,36,.06);
 }
 * { box-sizing: border-box; }
 html, body { margin: 0; background: var(--bg); color: var(--text); font: 14px/1.5 -apple-system, BlinkMacSystemFont, "Inter", "Segoe UI", Roboto, Helvetica, Arial, sans-serif; -webkit-font-smoothing: antialiased; }
@@ -147,11 +159,18 @@ h2 .count { color: var(--faint); font-weight: 500; }
 .nocp { color: var(--faint); font-size: 13px; font-style: italic; padding: 4px 0; }
 
 .actions-row { display: flex; gap: 6px; flex-wrap: wrap; margin-top: auto; padding-top: 2px; }
-.btn { background: var(--bg2); border: 1px solid var(--line); border-radius: 8px; padding: 5px 10px; font-size: 12.5px; color: var(--muted); cursor: pointer; display: inline-flex; align-items: center; gap: 6px; }
-.btn:hover { color: var(--text); border-color: var(--line-strong); }
+/* 0.9.7: a secondary button reads as a button on any surface (page, card, the
+   tinted banners): solid text, its own fill and a visible edge. Only a real
+   disabled state (disabled or aria-disabled) is dimmed, flat and dashed. */
+.btn { background: var(--btn-bg); border: 1px solid var(--btn-line); border-radius: 8px; padding: 5px 10px; font-size: 12.5px; font-weight: 500; color: var(--text2); cursor: pointer; display: inline-flex; align-items: center; gap: 6px; box-shadow: var(--btn-shadow); transition: background-color .12s, border-color .12s, color .12s; }
+.btn:hover { background: var(--btn-hover); border-color: var(--btn-line-hover); color: var(--text); }
+.btn:active { background: var(--btn-active); box-shadow: none; }
+.btn:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
 .btn.primary { background: var(--accent); border-color: var(--accent); color: var(--on-accent); font-weight: 600; }
 .btn.primary:hover { filter: brightness(1.08); color: var(--on-accent); }
-.btn:disabled { opacity: .55; cursor: progress; }
+.btn.primary:active { filter: brightness(.94); }
+.btn:disabled, .btn[aria-disabled="true"], .btn:disabled:hover, .btn[aria-disabled="true"]:hover, .btn:disabled:active, .btn[aria-disabled="true"]:active { opacity: .5; cursor: not-allowed; box-shadow: none; filter: none; border-style: dashed; background: var(--btn-bg); border-color: var(--btn-line-hover); color: var(--muted); }
+@media (prefers-reduced-motion: reduce) { .btn { transition: none; } }
 
 .empty { border: 1px dashed var(--line); border-radius: var(--radius); padding: 38px; text-align: center; color: var(--muted); }
 .empty code { background: var(--bg2); padding: 2px 6px; border-radius: 6px; }
@@ -488,7 +507,6 @@ h2 .count { color: var(--faint); font-weight: 500; }
 .btn.allow:hover { filter: brightness(1.08); }
 .btn.deny { color: var(--red); border-color: color-mix(in srgb, var(--red) 40%, var(--line)); }
 .btn.deny:hover { background: var(--tint-red); }
-.btn[disabled] { opacity: .5; cursor: not-allowed; }
 .deny-form { display: flex; gap: 6px; flex-wrap: wrap; }
 .deny-form[hidden] { display: none; }
 .deny-form input, .need .qother, .reply-text { flex: 1 1 220px; min-width: 0; background: var(--field); border: 1px solid var(--line); border-radius: 8px; color: var(--text); padding: 7px 9px; font: inherit; font-size: 13px; }
@@ -635,7 +653,8 @@ html { background: var(--bg); }
 .banner.restore .rs-m { color: var(--muted); font-size: 12px; overflow-wrap: anywhere; }
 .banner.restore .rs-m.err { color: var(--red); }
 .banner.restore .rs-actions { display: flex; flex-wrap: wrap; gap: 8px; align-items: center; }
-.banner.restore .rs-note { color: var(--muted); font-size: 12px; }
+.banner.restore .rs-note { color: var(--text2); font-size: 12.5px; flex: 1 1 280px; min-width: 0; }
+@media (pointer: coarse), (max-width: 600px) { .banner.restore .rs-actions .btn { min-height: 44px; } }
 .banner .rs-cmds { margin: 8px 0 0; padding: 8px 10px; background: var(--bg2); border: 1px solid var(--line); border-radius: 8px; font: 12px/1.5 var(--mono); white-space: pre-wrap; overflow-wrap: anywhere; color: var(--text2); }
 .banner.restore .rs-result { margin: 10px 0 0; }
 
@@ -1931,3 +1950,68 @@ mark.tx, .co-snip mark, .tx-snip mark, .tx-msg-text mark { background: var(--tx-
   .board-search .set-search input, .board-search input { height: 44px; }
   .tx-board-link { min-height: 44px; }
 }
+
+/* ------------------------------------------------ first-run setup wizard (0.9.7, ui/wizard.js) */
+.wz { max-width: 860px; margin: 8px auto 40px; }
+.wz .sr-only { position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0 0 0 0); white-space: nowrap; }
+.wz-top { display: flex; align-items: flex-start; justify-content: space-between; gap: 12px; margin-bottom: 14px; }
+.wz-h1 { font-size: 22px; line-height: 1.25; margin: 0; font-weight: 700; color: var(--text); }
+.wz-count { color: var(--muted); font-size: 13px; margin-top: 2px; }
+.wz-bar { list-style: none; margin: 0 0 14px; padding: 0; display: flex; gap: 6px; overflow-x: auto; scrollbar-width: none; }
+.wz-bar::-webkit-scrollbar { display: none; }
+.wz-bar li { flex: 1 0 auto; }
+.wz-bar button { width: 100%; display: flex; align-items: center; gap: 8px; padding: 8px 10px; border-radius: 10px; border: 1px solid var(--line); background: var(--card); color: var(--muted); font: inherit; font-size: 13px; cursor: pointer; white-space: nowrap; min-height: 40px; }
+.wz-bar button:hover { border-color: var(--line-strong); color: var(--text); }
+.wz-num { flex: none; width: 22px; height: 22px; border-radius: 50%; display: inline-flex; align-items: center; justify-content: center; font-size: 12px; font-weight: 700; background: var(--bg2); color: var(--muted); border: 1px solid var(--line); }
+.wz-bar li.done .wz-num { background: var(--tint-green); color: var(--green); border-color: color-mix(in srgb, var(--green) 45%, var(--line)); }
+.wz-bar li.on button { border-color: var(--accent); color: var(--text); background: var(--tint-accent); }
+.wz-bar li.on .wz-num { background: var(--accent); color: var(--on-accent); border-color: var(--accent); }
+.wz-card { background: var(--card); border: 1px solid var(--line); border-radius: var(--radius); box-shadow: var(--card-shadow); padding: 18px; outline: none; }
+.wz-card:focus-visible { box-shadow: 0 0 0 2px var(--focus); }
+.wz .wz-step { margin: 0 0 12px; }
+.wz-status { display: flex; gap: 12px; align-items: flex-start; }
+.wz-mark { flex: none; width: 24px; height: 24px; border-radius: 50%; display: inline-flex; align-items: center; justify-content: center; font-weight: 700; font-size: 13px; background: var(--tint-gray); color: var(--muted); }
+.wz-status.s-done .wz-mark, .wz-sumlist .wz-done .wz-mark { background: var(--tint-green); color: var(--green); }
+.wz-status.s-todo .wz-mark, .wz-sumlist .wz-todo .wz-mark { background: var(--tint-yellow); color: var(--yellow); }
+.wz-title { font-size: 16px; font-weight: 600; color: var(--text); line-height: 1.35; }
+.wz-detail { color: var(--text2); margin-top: 3px; }
+.wz-p { color: var(--text2); margin: 12px 0 0; }
+.wz-p a, .wz-detail a { color: var(--accent); }
+.wz-hint { color: var(--muted); font-size: 12.5px; }
+.wz-list { list-style: none; padding: 0; margin: 12px 0 0; display: flex; flex-direction: column; gap: 6px; }
+.wz-list li { display: flex; align-items: center; gap: 8px; color: var(--text2); flex-wrap: wrap; }
+.wz-dot { width: 8px; height: 8px; border-radius: 50%; background: var(--gray); flex: none; }
+.wz-dot.up { background: var(--green); } .wz-dot.down { background: var(--red); }
+.wz-chip { font-size: 11.5px; font-weight: 600; padding: 1px 8px; border-radius: 999px; background: var(--tint-gray); color: var(--muted); }
+.wz-chip.on { background: var(--tint-green); color: var(--green); }
+.wz-actions { display: flex; align-items: center; gap: 10px; margin-top: 14px; flex-wrap: wrap; }
+.wz-result { margin-top: 12px; padding: 10px 12px; border-radius: 10px; border: 1px solid var(--line); background: var(--bg2); display: flex; flex-direction: column; gap: 4px; color: var(--text2); }
+.wz-result.ok { border-color: color-mix(in srgb, var(--green) 40%, var(--line)); }
+.wz-result.bad { border-color: color-mix(in srgb, var(--red) 45%, var(--line)); color: var(--text); }
+.wz-fix { margin-top: 14px; padding: 10px 12px; border-radius: 10px; background: var(--bg2); border: 1px solid var(--line); }
+.wz-fix-what { font-size: 13px; color: var(--text2); margin-bottom: 6px; }
+.wz-cmdrow { display: flex; align-items: center; gap: 8px; }
+.wz-cmd { flex: 1; min-width: 0; overflow-wrap: anywhere; color: var(--text); font-size: 13px; }
+.wz-sumlist { list-style: none; padding: 0; margin: 0; display: flex; flex-direction: column; gap: 8px; }
+.wz-sumlist li { display: flex; gap: 10px; align-items: flex-start; color: var(--text2); border: 0; padding: 0; }
+.wz-sumlist b { color: var(--text); margin-right: 4px; }
+.wz-h3 { font-size: 15px; margin: 18px 0 0; color: var(--text); }
+.wz-allset { font-weight: 600; color: var(--green); }
+.wz-nav { display: flex; justify-content: space-between; align-items: center; gap: 10px; margin-top: 14px; }
+.wz-nav-r { display: flex; gap: 8px; }
+.wz .btn { font-size: 14px; padding: 8px 14px; min-height: 38px; }
+.wz-remote { margin-top: 10px; }
+@media (pointer: coarse), (max-width: 600px) {
+  .wz .btn, .wz-bar button { min-height: 44px; }
+  .wz-copy { min-width: 64px; justify-content: center; }
+}
+@media (max-width: 600px) {
+  .wz { margin-top: 0; }
+  .wz-card { padding: 14px; }
+  .wz-bar li { flex: none; }
+  .wz-bar .wz-lbl { display: none; }
+  .wz-bar li.on .wz-lbl { display: inline; }
+  .wz-cmdrow { flex-direction: column; align-items: flex-start; }
+  .wz-cmd { width: 100%; }
+  .wz-nav .btn { padding: 8px 16px; }
+}

package/ui/app.js

@@ -4,6 +4,7 @@ import { goWithFeedback, goState, GIVE_UP_MS } from './go.js'
 import { icon } from './icons.js'
 import { selectHtml, comboHtml, closeMenu, openActionMenu, closeActionMenu, actionMenuKey, openNameSheet } from './picker.js'
 import { SETTINGS, settingsKeyFor } from './settings-nav.js'
+import { mountWizard, shouldAutoOpen } from './wizard.js'
 import { changedKeys } from './settings-dirty.js'
 import { looksMd, stripMd, plainCp } from './cp-text.js'
 import { beginWriting, settleWriting, reconcileWriting, dismissWriting, isWriting, writingText, WRITING_SYNC_MS, FRESH_MS } from './writing.js'
@@ -12,7 +13,8 @@ import { needsItems, needsStrip, needPanel, agentNeedPanel, httpsOnly, agentRepl
 import { SUMMARY_EXAMPLES, LENGTH_CHOICES } from './summary-examples.js'
 import { mdInline, renderSection } from './changelog-md.js'
 import { cardPrsHtml, sessionPrsSection, prsPageHtml, prsBodyHtml, prRowHtml, prRows, readPrFilter, prsHash } from './prs.js'
-import { wantsSetupBanner, setupCandidate, localLeftoffAnswers, thisOneSuffix } from './viewer.js'
+import { wantsSetupBanner, setupCandidate, localLeftoffAnswers, thisOneSuffix, isPhoneUa } from './viewer.js'
+import { restoreAccess, hintHtml, restoreWhen } from './restore-gate.js'
 import { defaultEmoji, PICKER_SET, isEmoji } from './machines.js'
 import { todosSection, sessionTodosSection, cardHandoffChips, sessionFilesSection, docViewerBody, docDownloadHref, docMenuItems, docFileName, renderDoc } from './handoffs.js'
 const $app = document.getElementById('app')
@@ -205,7 +207,7 @@ function banners() {
     const items = inc.slice(0, 2).flatMap((e) => e.sections.flatMap((s) => s.items.map((it) => ({ v: e.version, t: it })))).slice(0, 4)
     out += '<div class="banner info update" role="status"><div class="grow"><b>Leftoff ' + (u.remoteVersion ? 'v' + esc(u.remoteVersion) : esc(u.remoteSha || 'update')) + ' is available</b> · you have v' + esc(h.version) +
       (items.length ? '<ul class="incoming">' + items.map((x) => '<li>' + mdInline(firstSentence(x.t)) + '</li>').join('') + '</ul>' : '') + '</div>' +
-      '<code class="cmd">leftoff upgrade</code><button type="button" class="btn" data-action="copy-cmd" data-cmd="leftoff upgrade">Copy</button></div>'
+      '<code class="cmd">' + esc(u.upgradeCommand || 'leftoff upgrade') + '</code><button type="button" class="btn" data-action="copy-cmd" data-cmd="' + esc(u.upgradeCommand || 'leftoff upgrade') + '">Copy</button></div>'
   }
   out += syncBanners(h)
   const mod = h.mod
@@ -310,7 +312,7 @@ function staleNote(machine) {
 function updateLine() {
   const h = state.health || {}
   const u = h.update || {}
-  if (u.available) return 'v' + esc(u.remoteVersion || '?') + ' is available: run <code>leftoff upgrade</code>.'
+  if (u.available) return 'v' + esc(u.remoteVersion || '?') + ' is available: run <code>' + esc(u.upgradeCommand || 'leftoff upgrade') + '</code>.'
   if (u.error) return 'Last check couldn’t reach the repo (' + esc(u.error) + ').'
   if (u.checkedAt) return 'Up to date (v' + esc(h.version) + '), checked ' + esc(ago(u.checkedAt)) + '.'
   return 'Not checked yet.'
@@ -1033,26 +1035,32 @@ function emptyFold(list) {
     '<div class="grid">' + list.map(card).join('') + '</div></details>'
 }
 
-// Restore (v0.4.7): the sessions that were open before this machine restarted,
+// Restore (v0.4.7): the sessions that were open before this machine restarted
+// (0.9.7: or when the terminal quit),
 // with a checkbox each; Restore opens each in a new Ghostty tab, resumed by id.
 // Opening tabs runs on the Mac, so (like Go) only its own browser may press it.
 const restoreUi = { open: false, off: new Set(), result: null }
 function restoreDismissKey(r) { return 'lo.restore.dismissed:' + (r.restartAt || '') }
 function restorePicked() { const r = state.restore; return r ? r.sessions.filter((s) => !restoreUi.off.has(s.id)) : [] }
+// 0.9.7: this Mac's own board, or the hosted board open on it (the direct path)
+function restoreGate() {
+  const lr = window.leftoffRelay, r = state.restore || {}
+  return restoreAccess({ local: state.viewerLocal !== false, hosted: !!lr, route: lr ? lr.route : null, routeMac: lr ? lr.mac : null, machine: r.machine || null,
+    phone: isPhoneUa(navigator.userAgent, { maxTouchPoints: navigator.maxTouchPoints || 0 }) })
+}
 function restoreBanner() {
   const r = state.restore
   if (!r || !r.sessions || !r.sessions.length) return restoreUi.result ? restoreResult() : ''
   try { if (localStorage.getItem(restoreDismissKey(r)) === '1' && !restoreUi.open) return '' } catch {}
   const n = r.sessions.length
-  const what = r.restartKind === 'boot' ? (r.ghostty ? 'your Mac' : 'this machine') + ' restarted' : 'Leftoff restarted'
   const when = r.restartAt ? ' (' + clock(r.restartAt) + ')' : ''
-  const head = '<b>' + n + ' session' + (n === 1 ? ' was' : 's were') + ' open before ' + what + '</b>' + esc(when)
+  const head = '<b>' + n + ' session' + (n === 1 ? ' was' : 's were') + ' open ' + esc(restoreWhen(r)) + '</b>' + esc(when)
   if (!restoreUi.open) {
     return '<div class="banner info restore" id="restoreBanner" role="status"><span class="grow">' + head + '. Put them back, each in its own Ghostty tab.</span>' +
       '<button type="button" class="btn primary" data-action="restore-open">' + icon('rotate-ccw') + 'Restore…</button>' +
       '<button type="button" class="btn x" data-action="restore-dismiss" aria-label="Not now" title="Not now">✕</button></div>'
   }
-  const local = state.viewerLocal !== false
+  const gate = restoreGate()
   const picked = restorePicked().length
   const rows = r.sessions.map((s) => '<label class="rs-row"><input type="checkbox" name="rs" value="' + esc(s.id) + '"' + (restoreUi.off.has(s.id) ? '' : ' checked') + '>' +
     '<span class="rs-main"><span class="rs-t">' + esc(s.title || '(untitled)') + '</span><span class="rs-m">' + esc([s.repoLabel, s.branch, s.modelLabel, s.lastAliveAt ? 'last seen ' + ago(s.lastAliveAt) : null, 'cp:' + (s.shortId || s.id.slice(0, 8))].filter(Boolean).join(' · ')) + '</span>' + (s.blocked ? '<span class="rs-m err">' + esc(s.error) + '</span>' : '') + '</span></label>').join('')
@@ -1060,13 +1068,15 @@ function restoreBanner() {
     '<button type="button" class="btn x" data-action="restore-close" aria-label="Close" title="Close">✕</button></div>' +
     '<div class="rs-list">' + rows + '</div>' +
     '<div class="rs-actions">' +
-    (local ? '<button type="button" class="btn primary" data-action="restore-go" id="restoreGo"' + (picked ? '' : ' disabled') + '>' + icon('rotate-ccw') + 'Restore ' + picked + '</button>'
-      : '<button type="button" class="btn primary" disabled title="Restore opens Ghostty tabs on the Mac running Leftoff, so it only works from that Mac’s own browser (localhost)">Restore ' + picked + '</button>') +
+    '<button type="button" class="btn primary" data-action="restore-go" id="restoreGo" data-how="' + (gate.how || 'off') + '"' + (gate.ok && picked ? '' : ' aria-disabled="true"') +
+      (gate.ok ? '' : ' aria-describedby="restoreHint" title="' + esc(gate.hint.replace(/`/g, '')) + '"') + '>' + icon('rotate-ccw') + 'Restore ' + picked + '</button>' +
     '<button type="button" class="btn" data-action="restore-all">' + (picked === r.sessions.length ? 'Select none' : 'Select all') + '</button>' +
     '<button type="button" class="btn" data-action="restore-copy">Copy commands</button>' +
-    (local ? '' : '<span class="rs-note">This opens tabs on the Mac, so only its own browser can do it (or run <code>leftoff restore</code> there).</span>') +
+    (gate.ok ? '' : '<span class="rs-note" id="restoreHint">' + hintHtml(gate.hint, esc) + '</span>') +
     '</div>' + (restoreUi.result ? restoreResult() : '') + '</div>'
 }
+// 0.9.7: the hosted board found (or lost) this Mac's direct path: Restore follows it
+if (typeof window !== 'undefined') window.addEventListener('leftoff-route', () => { const el = restoreUi.open && document.getElementById('restoreBanner'); if (el) el.outerHTML = restoreBanner() })
 function restoreResult() {
   const x = restoreUi.result
   if (!x) return ''
@@ -2407,6 +2417,7 @@ async function viewSettings() {
     updates: '<div class="section">About</div>' +
       '<label>Version</label><div class="aboutline"><span class="chip mono">v' + esc(h.version || '') + '</span><a href="#/whats-new">What’s new</a><a href="' + NPM_URL + '" target="_blank" rel="noopener">npm ↗</a></div>' +
       '<div class="hint">' + updateLine() + ' <button type="button" class="linkish" data-action="check-updates">Check now</button></div>' +
+      '<label>Setup</label><div class="aboutline"><a href="#/setup">Run setup again</a></div>' +
       advanced('updates', '<label for="f-updates">Check daily</label><label class="check"><input id="f-updates" type="checkbox"' + (!(c.updates && c.updates.check === false) ? ' checked' : '') + '><span>Look for a new version daily. Nothing installs on its own.</span></label>' +
         '<label>Machine</label><div><span class="chip machine">⌂ ' + esc(c.machineResolved) + '</span></div>' +
         '<label>Folder</label><div><a class="chip mono" href="file://' + esc(c.folder) + '">' + esc(c.folder) + '</a></div>'),
@@ -3148,6 +3159,7 @@ async function render() {
     else if (r.name === 'whats-new') await viewWhatsNew()
     else if (r.name === 'docs' && r.arg) await viewDocPage(r.arg)
     else if (r.name === 'search') await viewSearch(r.q || '')
+    else if (r.name === 'setup') await viewSetup()
     else await viewBoard()
   } catch (e) {
     if (e.code === 'login_required') return showLogin()
@@ -3155,6 +3167,18 @@ async function render() {
   }
 }
 
+// First-run setup wizard (0.9.7, ui/wizard.js). Live updates don't redraw it:
+// it keeps its own step and fetches its own state.
+async function viewSetup() {
+  if ($app.querySelector('.wz')) return
+  await mountWizard($app, { api, esc, onDone: () => { location.hash = '#/' } })
+}
+// Opens #/setup by itself once, on a Mac's own board, when the board opens plain (no deep link).
+async function firstRunSetup() {
+  if (location.hash.replace(/^#\/?/, '')) return
+  try { const s = await api('GET', '/v1/setup'); if (shouldAutoOpen(s, (state.route || {}).name) && !location.hash.replace(/^#\/?/, '')) location.replace('#/setup') } catch {}
+}
+
 // A remote browser (Tailscale) that hasn't signed in yet: the iPhone
 // home-screen app always lands here first (it has its own cookie jar), so the
 // typed code is the main way in; the QR link is the other.
@@ -3709,7 +3733,9 @@ document.addEventListener('click', async (ev) => {
     if (action === 'restore-copy') { const p = restorePicked(); if (!p.length) { toast('Pick at least one'); return } await copy(p.map((x) => x.command).join('\n')); return }
     if (action === 'restore-go') {
       const ids = restorePicked().map((x) => x.id)
-      if (!ids.length) return
+      if (!ids.length) { toast('Pick at least one'); return }
+      const gate = restoreGate()
+      if (!gate.ok) { toast(gate.hint.replace(/`/g, ''), 6000); return }
       btn.disabled = true; btn.textContent = 'Opening ' + ids.length + '…'
       const r = await api('POST', '/v1/restore', { ids }, { timeoutMs: 60000 })
       restoreUi.result = r.how === 'print' || r.failed ? r : null
@@ -4338,7 +4364,7 @@ let pending = null
 const busy = () => !!document.querySelector('.doc-viewer:not([hidden]), .lo-menu, .title input, .repomore[open], .need .deny-form:not([hidden])') || !!(document.activeElement && document.activeElement.closest && document.activeElement.closest('.addform') && document.activeElement.value) || !!(document.activeElement && document.activeElement.closest && document.activeElement.closest('.need') && /^(INPUT|TEXTAREA)$/.test(document.activeElement.tagName))
 // Settings isn't redrawn by live updates: it would wipe what you're editing,
 // and the QR code you're scanning (v0.4.6). Its sections fetch their own state.
-function soon() { if (pending) return; pending = setTimeout(() => { pending = null; if (!busy() && !(state.route && state.route.name === 'settings') && !(state.route && state.route.name === 'catchup' && cuUi.open)) render(); refreshHealth() }, 800) }
+function soon() { if (pending) return; pending = setTimeout(() => { pending = null; if (!busy() && !(state.route && ['settings', 'setup'].includes(state.route.name)) && !(state.route && state.route.name === 'catchup' && cuUi.open)) render(); refreshHealth() }, 800) }
 let stream = null
 function connect() {
   if (stream) { try { stream.close() } catch {} }
@@ -4388,7 +4414,7 @@ document.addEventListener('change', async (ev) => {
     if (ev.target.checked) restoreUi.off.delete(ev.target.value); else restoreUi.off.add(ev.target.value)
     const n = restorePicked().length
     const go = document.getElementById('restoreGo')
-    if (go) { go.disabled = !n; go.innerHTML = icon('rotate-ccw') + 'Restore ' + n }
+    if (go) { if (n && restoreGate().ok) go.removeAttribute('aria-disabled'); else go.setAttribute('aria-disabled', 'true'); go.innerHTML = icon('rotate-ccw') + 'Restore ' + n }
     const all = document.querySelector('[data-action="restore-all"]')
     if (all) all.textContent = n === (state.restore ? state.restore.sessions.length : 0) ? 'Select none' : 'Select all'
     return
@@ -4455,7 +4481,7 @@ document.addEventListener('pointerdown', (ev) => {
   if (m && !m.contains(ev.target)) m.open = false
 })
 api('GET', '/v1/config').then((c) => (state.cfg = c)).catch(() => {})
-refreshHealth().then(render)
+refreshHealth().then(render).then(firstRunSetup)
 connect()
 
 // The home-screen app's service worker (v0.4.6): it only serves an offline page

package/ui/direct.js

@@ -1,6 +1,7 @@
 // 0.9.3: "direct when on the same Mac". The hosted board (<user>.leftoff.dev)
 // open on a Mac that runs Leftoff asks that Mac's own daemon over
-// http://127.0.0.1:7429 instead of through the relay; the address bar stays.
+// http://127.0.0.1:7429 (0.9.7: or https://leftoff.localhost) instead of
+// through the relay; the address bar stays.
 //
 // The request is the very envelope the relay would carry (ui/relay-crypto.js),
 // posted to /v1/relay/direct (src/direct.js) instead of /_relay/api. So going
@@ -21,7 +22,13 @@ import { LOCAL_PORT, isPhoneUa } from './viewer.js'
 export const DIRECT_PATH = '/v1/relay/direct'
 export const PROBE_EVERY_MS = 60000
 export const FOCUS_GAP_MS = 10000
+// 0.9.7: Leftoff's own https://leftoff.localhost (`leftoff setup`, Caddy in
+// front of 127.0.0.1:7429) is asked too: an https page may always call an
+// https address, where Safari refuses plain http://127.0.0.1. Both go to the
+// same daemon; the first that proves itself is used.
+export const HTTPS_LOCAL = 'https://leftoff.localhost'
 export function directUrl(port = LOCAL_PORT) { return 'http://127.0.0.1:' + port + DIRECT_PATH }
+export function directUrls(port = LOCAL_PORT) { return [HTTPS_LOCAL + DIRECT_PATH, directUrl(port)] }
 
 export class DirectError extends Error { constructor(code, message) { super(message || code); this.code = code } }
 
@@ -37,14 +44,18 @@ export function directMatch(info, { user, picked } = {}) {
 export function aborted(signal) { return !!(signal && signal.aborted) }
 
 export class DirectRoute {
-  constructor({ user, port = LOCAL_PORT, fetchImpl, now = () => Date.now(), ua = '', maxTouchPoints = 0, every = PROBE_EVERY_MS, focusGap = FOCUS_GAP_MS } = {}) {
+  constructor({ user, port = LOCAL_PORT, urls = null, fetchImpl, now = () => Date.now(), ua = '', maxTouchPoints = 0, every = PROBE_EVERY_MS, focusGap = FOCUS_GAP_MS } = {}) {
     this.user = user; this.port = port; this.fetchImpl = fetchImpl; this.now = now
+    this.urls = urls && urls.length ? urls.slice() : directUrls(port)
+    this.base = null // the address that answered last (one of urls)
     // a phone or tablet never runs Leftoff: don't ask (and don't trip a permission prompt)
     this.never = isPhoneUa(ua, { maxTouchPoints })
     this.every = every; this.focusGap = focusGap
     this.on = false; this.machine = null; this.checkedAt = 0; this.inflight = null; this.lastError = null; this.latencyMs = null
   }
-  get url() { return directUrl(this.port) }
+  get url() { return this.base || this.urls[this.urls.length - 1] }
+  // 'https' (https://leftoff.localhost) or 'http' (127.0.0.1), once one answered
+  get via() { return this.base ? (this.base.startsWith('https:') ? 'https' : 'http') : null }
 
   // -> the machine (direct confirmed, not yet switched on) or null. Never throws.
   probe({ picked = null, verify = null, timeoutMs = 1500 } = {}) {
@@ -53,15 +64,20 @@ export class DirectRoute {
     this.inflight = (async () => {
       this.checkedAt = this.now()
       const t0 = this.now()
-      let info
-      try {
-        const r = await this.fetchImpl(this.url, { mode: 'cors', credentials: 'omit', cache: 'no-store', signal: timeoutSignal(timeoutMs) })
-        if (r.status !== 200) return null
-        info = await r.json()
-      } catch { return null }
-      const m = directMatch(info, { user: this.user, picked })
-      if (!m) return null
-      if (verify) { let ok = false; try { ok = await verify(m) } catch { ok = false } if (!ok) return null }
+      // every address at once; the first that is this account's Leftoff wins
+      const ask = async (url) => {
+        const r = await this.fetchImpl(url, { mode: 'cors', credentials: 'omit', cache: 'no-store', signal: timeoutSignal(timeoutMs) })
+        if (r.status !== 200) throw new DirectError('http_' + r.status)
+        const m = directMatch(await r.json(), { user: this.user, picked })
+        if (!m) throw new DirectError('not_ours')
+        return { url, m }
+      }
+      let hit
+      try { hit = await firstOf(this.urls.map(ask)) } catch { return null }
+      const prev = this.base
+      this.base = hit.url
+      const m = hit.m
+      if (verify) { let ok = false; try { ok = await verify(m) } catch { ok = false } if (!ok) { this.base = prev; return null } }
       this.latencyMs = Math.max(0, Math.round(this.now() - t0))
       return m
     })().finally(() => { this.inflight = null })
@@ -108,6 +124,15 @@ export function toResponse(out) {
   return new Response(nullBody ? null : out.b, { status: out.s, headers: out.h })
 }
 
+// Promise.any, for browsers and runtimes without it.
+function firstOf(ps) {
+  return new Promise((resolve, reject) => {
+    let left = ps.length
+    if (!left) return reject(new DirectError('none'))
+    for (const p of ps) Promise.resolve(p).then(resolve, () => { if (--left === 0) reject(new DirectError('none')) })
+  })
+}
+
 function timeoutSignal(ms) {
   if (typeof AbortSignal !== 'undefined' && AbortSignal.timeout) return AbortSignal.timeout(ms)
   const c = new AbortController(); setTimeout(() => c.abort(), ms); return c.signal

package/ui/restore-gate.js

@@ -0,0 +1,40 @@
+// 0.9.7: may this board press Restore, and if not, what would make it work.
+// Restore opens Ghostty tabs on the Mac the restore card belongs to, so the
+// board must be on that Mac: its own browser on localhost, or your hosted
+// board (<user>.leftoff.dev) open on it and talking to it over the direct path
+// (ui/direct.js: http://127.0.0.1:7429 or https://leftoff.localhost). The
+// daemon checks the same thing again (src/direct.js DIRECT_LOCAL); this only
+// decides how the button looks and what the hint says. Plain logic, no DOM.
+//
+//   local     the page is that Mac's own board (viewer.local)
+//   hosted    the page is the hosted board (window.leftoffRelay)
+//   route     'direct' | 'relay' (leftoffRelay.route), routeMac: the Mac it is on
+//   machine   the Mac the restore card belongs to
+//   phone     a phone or tablet (never runs Leftoff)
+// -> { ok, how: 'local' | 'direct' | null, hint: text with `commands` or null }
+export function restoreAccess({ local = false, hosted = false, route = null, routeMac = null, machine = null, phone = false } = {}) {
+  if (local && !hosted) return { ok: true, how: 'local', hint: null }
+  if (hosted && !phone && route === 'direct' && machine && routeMac === machine) return { ok: true, how: 'direct', hint: null }
+  const m = machine || 'the Mac'
+  if (phone) return { ok: false, how: null, hint: 'Restore opens Ghostty tabs on ' + m + ', so it can’t run from a phone yet. On ' + m + ', run `leftoff restore`.' }
+  if (hosted) {
+    return { ok: false, how: null, hint: 'Restore opens Ghostty tabs on ' + m + '. Open this board on ' + m + ', or run `leftoff restore` there. Already on ' + m + '? Run `leftoff setup` and turn on https://leftoff.localhost so this page can reach it.' }
+  }
+  return { ok: false, how: null, hint: 'Restore opens Ghostty tabs on ' + m + ', so it works from ' + m + '’s own browser. Or run `leftoff restore` there.' }
+}
+
+// The hint as HTML: escaped, `commands` in <code>.
+export function hintHtml(hint, esc) {
+  return String(hint || '').split('`').map((part, i) => (i % 2 ? '<code>' + esc(part) + '</code>' : esc(part))).join('')
+}
+
+// 0.9.7: when the restore card's sessions were open, from GET /v1/restore:
+// restartKind 'quit' (the terminal quit while the Mac stayed up; restartTerminal
+// names it when known), 'boot' or 'daemon'. short: the CLI's one-liners.
+//   -> "when Ghostty quit" | "before your Mac restarted" | "before Leftoff restarted"
+export function restoreWhen(r = {}, { short = false } = {}) {
+  if (r.restartKind === 'quit') return 'when ' + (r.restartTerminal || 'the terminal') + ' quit'
+  if (short) return 'before the restart'
+  if (r.restartKind === 'boot') return 'before ' + (r.ghostty === false ? 'this machine' : 'your Mac') + ' restarted'
+  return 'before Leftoff restarted'
+}