@skitterbyte/skitterspec 21.0.0 → 22.0.0

package/assets/review/page.html

@@ -168,25 +168,58 @@ input:focus-visible,
   font-size: .85rem;
   font-weight: 600;
 }
-.tree { padding: 0 .6rem .7rem; font-size: .82rem; }
-.tree ul { list-style: none; margin: 0; padding-left: .8rem; }
-.tree > ul { padding-left: 0; }
-.tree .dir { color: var(--muted); display: block; padding: .1rem 0; }
+/* The tree scrolls SIDEWAYS; names never wrap. A wrapped name turned every
+   long path into three ragged lines, which is what made the sidebar hard to
+   scan. Indentation is per-row padding rather than nested <ul> padding — see
+   renderTree, which explains why the sticky column below depends on it. */
+.tree { padding: 0 0 .7rem; font-size: .82rem; overflow-x: auto; }
+.tree ul { list-style: none; margin: 0; padding: 0; }
+/* max-content makes the list as wide as its widest row, and min-width keeps it
+   filling the sidebar when everything fits. Together they give every row the
+   same width, which is what `.ct` needs. */
+.tree > ul { width: max-content; min-width: 100%; }
+.tree .dir { color: var(--muted); display: block; padding: .1rem .6rem; white-space: nowrap; }
 .tree-file {
   display: flex;
   gap: .4rem;
   width: 100%;
   text-align: left;
-  background: none;
+  /* A COLOUR, not `none`: `.ct` inherits it to mask the name scrolling under
+     it, and inherit re-resolves on hover so the pinned counts follow the row. */
+  background: var(--panel);
   border: 0;
   border-radius: 6px;
-  padding: .15rem .3rem;
+  /* NO horizontal padding, deliberately. A sticky box is clamped by its
+     containing block — this row's content box — so a .6rem side padding gave
+     `.ct` two different resting places: flush to the scrollport while pinned,
+     and .6rem inside it once scrolled to the end, which reads as the counts
+     sliding as you reach the right. The gutters live on `.nm` and `.ct`
+     instead, where they move with the element rather than fencing it in. */
+  padding: .15rem 0;
   color: inherit;
   font-size: .82rem;
 }
 .tree-file:hover { background: var(--panel-2); color: inherit; }
-.tree-file .nm { overflow-wrap: anywhere; }
-.tree-file .ct { margin-left: auto; white-space: nowrap; font-family: ui-monospace, monospace; font-size: .75rem; }
+.tree-file .nm { white-space: nowrap; }
+/* Pinned to the right edge of the tree's scrollport, so the change counts stay
+   readable however far the names are scrolled. Sticky can only pin within its
+   own row, which is why every row spans the full scroll width above. */
+.tree-file .ct {
+  margin-left: auto;
+  position: sticky;
+  right: 0;
+  background: inherit;
+  /* The right gutter is PADDING on the pinned element, not a `right` offset.
+     An offset would hold the box away from the edge and let names scroll
+     visibly through the gap beside it; padding keeps the masking background
+     running to the scrollport edge with the text inset. */
+  padding-left: .55rem;
+  padding-right: .6rem;
+  box-shadow: -8px 0 8px -8px rgba(0, 0, 0, .45);
+  white-space: nowrap;
+  font-family: ui-monospace, monospace;
+  font-size: .75rem;
+}
 .tree-file.is-noise .nm { color: var(--muted); }
 
 .file {
@@ -382,6 +415,28 @@ tr.note-row td {
   border-radius: 10px;
   background: var(--panel);
 }
+/* WHERE THIS REVIEW LIVES, and whether it is also running. It sits ABOVE the
+   verdicts because the question it answers — do I want to look at this running
+   before I conclude? — comes before the conclusion, not after it. Visually its
+   own strip, because it is not a verdict: pressing one of these changes what is
+   running (or which surfaces are permitted) and hands the reader straight back
+   to the same page with the same options. */
+.surfaces {
+  margin: 1.2rem 0 0;
+  padding: .55rem .7rem;
+  border: 1px solid var(--line);
+  border-radius: 10px;
+  background: var(--panel);
+}
+.surfaces[hidden] { display: none; }
+.surfaces-title { display: block; font-size: .8rem; color: var(--muted); margin: 0 0 .35rem; }
+.surface-row { display: flex; flex-wrap: wrap; align-items: center; gap: .5rem; margin: .3rem 0; }
+.surface-label { font-size: .8rem; font-weight: 600; min-width: 4.5rem; }
+.surface-state { font-size: .8rem; color: var(--muted); }
+.surface-note { font-size: .78rem; color: var(--muted); }
+/* The command, for a page with no transport. Same treatment as the verdict
+   command list: plain text a single tap selects whole, never an input. */
+.surface-cmd { font-size: .78rem; user-select: all; }
 .verdict-end { margin: 1.2rem 0 0; }
 .verdict-title { font-size: .8rem; color: var(--muted); }
 .verdict-count { font-size: .8rem; color: var(--muted); }
@@ -393,6 +448,13 @@ tr.note-row td {
 /* A button the render did not ask for is GONE, not dimmed — a disabled control
    invites a reader to work out how to enable it, and there is nothing to do. */
 .verdict button[hidden] { display: none; }
+/* AND THE BAR ITSELF. `display: flex` beats the browser's `[hidden]`, so the
+   whole bar stayed on screen on a `file://` page — offering four buttons that
+   POST to a server that is not there, directly above the command list that
+   exists because they cannot. The guard in `assets-review` only read the
+   template for a `hidden` attribute, and this element is hidden at runtime, so
+   it never saw it; the guard reads the script now too. */
+.verdict[hidden] { display: none; }
 /* A blocked control is dashed as well as dimmed, so the block survives a
    greyscale screen — and the reason rides in the label, never in a tooltip
    nobody hovers on a phone. */
@@ -448,7 +510,10 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
 .decided-what { margin: 0 0 .35rem; font-size: 1.05rem; font-weight: 650; line-height: 1.4; }
 .decided-note { margin: 0 0 .8rem; color: var(--muted); font-size: .88rem; line-height: 1.5; max-width: 62ch; }
 .decided-note:last-child { margin-bottom: 0; }
-.decided-toggle { font-size: .78rem; }
+/* SPACE ABOVE IT. The toggle sits under whatever the panel ended on — a
+   sentence, or the command callout — and butted straight against the callout's
+   border it read as part of it rather than as the way back to the diff. */
+.decided-toggle { font-size: .78rem; margin-top: .8rem; }
 
 /* WHY THE CHANGE EXISTS — the PR description this page never had. It is prose
    to be read rather than data to be scanned, so it gets a measure, air, and a
@@ -506,6 +571,17 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
 .context-more > summary:hover { color: var(--accent); border-color: var(--accent); }
 .context-more[open] > summary { margin-bottom: .6rem; }
 .context li.done { color: var(--muted); }
+/* The ticket rides ON the title line rather than under it — it is the other
+   name for this work, not a fact about it. Sized down and tinted so the title
+   still reads as the title. */
+.ticket {
+  font-size: .62em; font-weight: 600; vertical-align: middle;
+  font-family: var(--mono, ui-monospace, monospace);
+  color: var(--accent); text-decoration: none;
+  padding: .12em .45em; border: 1px solid var(--line); border-radius: 999px;
+  white-space: nowrap;
+}
+a.ticket:hover { border-color: var(--accent); }
 .context-more > summary { cursor: pointer; color: var(--muted); font-size: .85rem; margin-top: .6rem; }
 .copy-hint { font-size: .8rem; color: var(--muted); margin: .4rem 0 0; }
 .sent-cmd { display: flex; gap: .4rem; align-items: stretch; margin: .4rem 0 0; }
@@ -518,8 +594,100 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
   flex: 1; min-width: 0; font-family: var(--mono, ui-monospace, monospace);
   font-size: .85rem; padding: .35rem .5rem; color: var(--fg);
   background: var(--bg); border: 1px solid var(--line); border-radius: 4px;
+  /* One tap takes the whole command — the gesture that still works on a page
+     served over plain http, where the clipboard API is withheld. */
+  user-select: all; -webkit-user-select: all;
+  overflow-x: auto; white-space: pre; line-height: 1.6;
 }
 .sent-cmd-copy { white-space: nowrap; }
+/* ONE GRID FOR THE WHOLE LIST, so the command column starts at the same x on
+   every row. A per-row layout cannot do that: each row would size its own label
+   column to its own label, and `Commit` and `Commit & Continue` are not the
+   same width. The label column is `max-content` — the longest label decides,
+   which is a fact about the labels rather than a rem value someone has to
+   remember to update when one changes. */
+.cmd-list { display: grid; grid-template-columns: max-content minmax(0, 1fr) max-content; margin: .6rem 0 0; }
+.cmd-list[hidden] { display: none; }
+.cmd-lead { grid-column: 1 / -1; font-size: .85rem; color: var(--muted); margin: 0 0 .5rem; }
+/* ONE LINE: label, command, Copy. It was three lines deep — the label on its
+   own row above the command — which spent a screenful on four rows that fit on
+   four lines. */
+.cmd-row {
+  display: grid;
+  grid-column: 1 / -1;
+  /* FALLBACK FIRST, then subgrid. A browser without subgrid drops the second
+     declaration and keeps this one, which still gives one line per row — just
+     each sized to itself. Without a fallback the row would fall back to a
+     single auto column and stack, which is worse than the misalignment. */
+  grid-template-columns: max-content minmax(0, 1fr) max-content;
+  grid-template-columns: subgrid;
+  gap: .5rem; align-items: center;
+  padding: .4rem .5rem; margin-bottom: .35rem;
+  background: var(--panel); border: 1px solid var(--line); border-radius: 6px;
+}
+.cmd-row[hidden] { display: none; }
+.cmd-label { font-weight: 600; font-size: .85rem; white-space: nowrap; }
+/* A TINTED EDGE, NOT A TINTED BOX. Four filled rows read as four warnings —
+   the colour shouted where it only needed to identify. The left border and the
+   label carry it now, which is enough to recognise the choice by and quiet
+   enough to read past. No new tokens: `v-commit` and `v-changes` above borrow
+   exactly this pair. */
+.cmd-row[data-verdict="commit"],
+.cmd-row[data-verdict="commit-start"],
+.cmd-row[data-verdict="commit-continue"],
+.cmd-row[data-verdict="continue"] { border-left: 3px solid var(--good-fg); }
+.cmd-row[data-verdict="commit"] .cmd-label,
+.cmd-row[data-verdict="commit-start"] .cmd-label,
+.cmd-row[data-verdict="commit-continue"] .cmd-label,
+.cmd-row[data-verdict="continue"] .cmd-label { color: var(--good-fg); }
+.cmd-row[data-verdict="changes"] { border-left: 3px solid var(--flag-fg); }
+.cmd-row[data-verdict="changes"] .cmd-label { color: var(--flag-fg); }
+/* Discuss keeps the neutral panel, exactly as its button does — it is the
+   ending that decides nothing, and colouring it would say otherwise. */
+.cmd-text {
+  /* No `flex` — the list's grid column sizes this now. min-width:0 still
+     earns its place: it is what lets a long command scroll inside its own box
+     instead of widening the column and pushing Copy off the row. */
+  min-width: 0; font-family: var(--mono, ui-monospace, monospace);
+  font-size: .85rem; padding: .3rem .45rem; color: var(--fg);
+  background: var(--bg); border: 1px solid var(--line); border-radius: 4px;
+  /* One tap takes the whole command — see `.sent-cmd-text`. */
+  user-select: all; -webkit-user-select: all;
+  overflow-x: auto; white-space: pre; line-height: 1.6;
+}
+.cmd-copy { white-space: nowrap; }
+/* AN ACTION, NOT A NOTE. The command reached the reader as a grey line under a
+   bar that had just closed, and it read as a footnote to something finished —
+   so it is now a filled callout inside the decided panel, which is the block a
+   re-opened page shows first. It reuses the add palette rather than minting a
+   green of its own: those three tokens are already defined on bare `:root` and
+   redefined in both theme blocks, which is the property `assets-review` guards. */
+.sent-cmd.act {
+  flex-wrap: wrap; align-items: center; margin-top: .7rem;
+  padding: .55rem .6rem; border-radius: 6px;
+  background: var(--add-bg); border: 1px solid var(--add-mark); color: var(--add-fg);
+}
+.sent-cmd-lead { flex-basis: 100%; font-size: .85rem; font-weight: 600; color: var(--add-fg); }
+/* A FAILED SEND, IN THE PALETTE OF A FAILURE. The same callout the waiting-pass
+   case uses, in the delete colours rather than the add ones — `--del-bg` /
+   `--del-fg` / `--del-mark` are already defined on bare `:root` and redefined in
+   both theme blocks, which is the property `assets-review` guards. No new token
+   is minted for this. */
+.sent-cmd.act.fail {
+  background: var(--del-bg); border-color: var(--del-mark); color: var(--del-fg);
+}
+.sent-cmd.act.fail .sent-cmd-lead { color: var(--del-fg); }
+/* THE OUTCOME THE READER MUST ACT ON, AS LOUD AS THE ONE THEY NEED NOT.
+   A failed send used to be a small grey line in the footer, under a verdict bar
+   that had just closed — quieter than the success it was not. It gets the panel
+   the decided page gets, at the top of the column, in the delete palette. What
+   it does NOT get is `is-decided`: nothing was delivered, so the diff stays and
+   the verdict buttons stay live for a second try. */
+.decided.failed {
+  border-left-color: var(--del-mark);
+  background: var(--panel);
+}
+.decided.failed .decided-what { color: var(--del-mark); }
 /* The claim code is read aloud or copied, so it is set apart from the sentence
    around it rather than buried in it. */
 .copy-hint { user-select: text; }
@@ -548,12 +716,44 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
          engine from the spec's own files — nothing here passed through the
          model, so it is free however large the diff. Absent entirely for a spec
          whose overview cannot be read: the page worked without it before. -->
+    <!-- A SEND THAT DID NOT LAND. Same shape as the panel below, delete palette,
+         and deliberately NOT the same section: this one leaves the page
+         undecided, because nothing was delivered and the reader still has a
+         verdict to give. It names which failure happened, since a server that
+         has moved and a pass the engine refused send the reader to different
+         places. -->
+    <section class="decided failed" id="send-failed" hidden>
+      <p class="decided-what" id="send-failed-what"></p>
+      <p class="decided-note" id="send-failed-note"></p>
+      <p class="sent-cmd act fail" id="send-failed-cmd" hidden>
+        <span class="sent-cmd-lead" id="send-failed-lead"></span>
+        <code class="sent-cmd-text" id="send-failed-text"></code>
+        <button type="button" class="sent-cmd-copy" id="send-failed-copy" hidden>Copy</button>
+      </p>
+    </section>
     <!-- WHAT YOU DECIDED, once the pass has actually been handed over. It sits
          above everything because on a re-open it is the only thing you need:
          the review is over, and this says how it ended. -->
     <section class="decided" id="decided" hidden>
       <p class="decided-what" id="decided-what"></p>
       <p class="decided-note" id="decided-note"></p>
+      <!-- THE ONE THING LEFT TO DO, and it lives HERE rather than under the
+           verdict bar because that is where it was being missed: a grey line
+           below a bar that had just closed, in the type size of a footnote,
+           saying the same words whether it mattered or not. It is shown only
+           where the page has ESTABLISHED that the pass is still sitting there,
+           so when it appears it is always an instruction. -->
+      <p class="sent-cmd act" id="sent-cmd" hidden>
+        <span class="sent-cmd-lead" id="sent-cmd-lead"></span>
+        <!-- PLAIN TEXT, NOT AN INPUT. A readonly field still looks like
+             something to type into, and on a phone tapping it raises the
+             keyboard for a value nobody can change. It is a command to read and
+             copy, so it is marked up as one — `user-select: all` makes a single
+             tap take the whole thing, which is the gesture that works where no
+             clipboard API does. -->
+        <code class="sent-cmd-text" id="sent-cmd-text"></code>
+        <button type="button" class="sent-cmd-copy" id="sent-cmd-copy" hidden>Copy</button>
+      </p>
       <button type="button" class="decided-toggle" id="decided-toggle">Show the diff anyway</button>
     </section>
     <section class="context reviewable" id="context" hidden>
@@ -565,6 +765,13 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
     </section>
     <div id="review-block" class="reviewable">__REVIEW_BLOCK__</div>
     <div id="files" class="reviewable"></div>
+    <!-- THE SURFACES STRIP. Built by the script from `data.surfaces`, and
+         absent entirely when the render carried none — a `--docs` page has no
+         branch to put live, so it gets no strip and no explanation of why. -->
+    <section class="surfaces reviewable" id="surfaces" hidden>
+      <span class="surfaces-title">Where this runs</span>
+      <div id="surface-rows"></div>
+    </section>
     <!-- THE VERDICT SITS AT THE END, where reading finishes. It began in the
          header and the first person to use it could not find it: you read a
          350-line diff downward, and the control asking for your conclusion was
@@ -582,16 +789,30 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
              read it, carry on. It is not the removed `none` verdict — that
              recorded itself and did nothing, while this one resumes the run. -->
         <button id="verdict-continue" class="v-continue" type="button" hidden>→ Continue</button>
+        <!-- THE AUTHORING VERDICT, hidden unless the render asked for it. A spec
+             that has just been written has no phase in flight to continue, so
+             "Commit & Continue" is the wrong verb for it: this one commits the
+             spec and puts it IN FLIGHT, which is the `commit && /spec-start`
+             that was typed by hand until now. -->
+        <button id="verdict-commit-start" class="v-commit" type="button" hidden>&#10003; Commit &amp; Start</button>
         <button id="verdict-changes" class="v-changes" type="button">↺ Request changes</button>
         <button id="verdict-discuss" type="button">… Discuss first</button>
         <span class="verdict-count" id="verdict-count" aria-live="polite"></span>
       </div>
+      <!-- WHERE THE BUTTONS CANNOT DELIVER, the commands stand in their place.
+           A `file://` page has no server to POST to and no store to write to,
+           so a verdict button there only ever built a blob for the reader to
+           paste — a wall of JSON standing in for one word. Each row is named
+           with the BUTTON'S own label, because that is the word the reader
+           chose everywhere else; `commit-continue` is the wire spelling, and
+           nobody should have to learn a second vocabulary to recognise their
+           own decision. Built by the script, so there is exactly one list of
+           verdicts and it is the one the bar already uses. -->
+      <div class="cmd-list" id="cmd-list" hidden>
+        <p class="cmd-lead" id="cmd-lead"></p>
+      </div>
       <p class="verdict-log" id="verdict-log" hidden></p>
       <p class="copy-hint" id="copy-hint" hidden></p>
-      <p class="sent-cmd" id="sent-cmd" hidden>
-        <input class="sent-cmd-text" id="sent-cmd-text" readonly aria-label="Command to run">
-        <button type="button" class="sent-cmd-copy" id="sent-cmd-copy" hidden>Copy</button>
-      </p>
       <textarea class="copy-out" id="copy-out" readonly hidden aria-label="Review blob to copy"></textarea>
       <p class="drawn-by" id="drawn-by"></p>
     </footer>
@@ -1089,28 +1310,56 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
     d.scrollIntoView({ block: 'start' })
   }
 
+  // ONE FLAT LIST, indented by per-row padding rather than by nesting <ul>s.
+  //
+  // That is not a tidy-up: the change counts are `position: sticky; right: 0`,
+  // and a sticky box can only pin within its own row. Nested <ul>s make each
+  // level narrower than its parent, so a deep row ends before the scrollport's
+  // right edge and its counts slide away the moment you scroll sideways. Flat
+  // rows all share the widest row's width, so every one of them has something
+  // to pin to.
+  //
+  // Depth goes on as an inline style because it is data, not a class: the tree
+  // is however deep the diff happens to be, and a rule per level would be a
+  // guess at the maximum.
+  function indent(node, depth, base) {
+    // Rounded, because 3 * 0.8 is 2.4000000000000004 in binary floating point
+    // and that lands verbatim in the attribute. CSS copes; a person reading the
+    // page source does not, and neither does a test asserting the value.
+    var rem = Math.round((base + depth * 0.8) * 100) / 100
+    node.setAttribute('style', 'padding-left:' + rem + 'rem')
+    return node
+  }
+
   function renderTree(node) {
     var ul = el('ul')
-    Object.keys(node.dirs).sort().forEach(function (name) {
-      var li = el('li')
-      li.appendChild(el('span', 'dir', name + '/'))
-      li.appendChild(renderTree(node.dirs[name]))
-      ul.appendChild(li)
-    })
-    node.files.sort(function (a, b) { return a.name.localeCompare(b.name) }).forEach(function (entry) {
-      var li = el('li')
-      var b = el('button', 'tree-file' + (entry.file.noise ? ' is-noise' : ''))
-      b.type = 'button'
-      b.appendChild(el('span', 'nm', entry.name))
-      var ct = el('span', 'ct')
-      ct.appendChild(el('span', 'a', '+' + entry.file.additions))
-      ct.appendChild(document.createTextNode(' '))
-      ct.appendChild(el('span', 'd', '-' + entry.file.deletions))
-      b.appendChild(ct)
-      b.addEventListener('click', function () { reveal(entry.file) })
-      li.appendChild(b)
-      ul.appendChild(li)
-    })
+    ;(function walk(n, depth) {
+      Object.keys(n.dirs).sort().forEach(function (name) {
+        var li = el('li')
+        li.appendChild(indent(el('span', 'dir', name + '/'), depth, 0.6))
+        ul.appendChild(li)
+        // The subtree goes in AFTER its own label and before this level's
+        // files, which is the order the nested form produced.
+        walk(n.dirs[name], depth + 1)
+      })
+      n.files.sort(function (a, b) { return a.name.localeCompare(b.name) }).forEach(function (entry) {
+        var li = el('li')
+        var b = el('button', 'tree-file' + (entry.file.noise ? ' is-noise' : ''))
+        b.type = 'button'
+        // The same .6rem base as a dir label, so a file sits level with the
+        // directory it is in. It is on the name rather than the row because the
+        // row must reach the scrollport edge — see `.tree-file` padding.
+        b.appendChild(indent(el('span', 'nm', entry.name), depth, 0.6))
+        var ct = el('span', 'ct')
+        ct.appendChild(el('span', 'a', '+' + entry.file.additions))
+        ct.appendChild(document.createTextNode(' '))
+        ct.appendChild(el('span', 'd', '-' + entry.file.deletions))
+        b.appendChild(ct)
+        b.addEventListener('click', function () { reveal(entry.file) })
+        li.appendChild(b)
+        ul.appendChild(li)
+      })
+    })(node, 0)
     return ul
   }
 
@@ -1228,6 +1477,7 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
   var verdictBtns = {
     commit: document.getElementById('verdict-commit'),
     'commit-continue': document.getElementById('verdict-commit-continue'),
+    'commit-start': document.getElementById('verdict-commit-start'),
     continue: document.getElementById('verdict-continue'),
     changes: document.getElementById('verdict-changes'),
     discuss: document.getElementById('verdict-discuss'),
@@ -1235,7 +1485,7 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
   // The committing pair, named once. A fifth verdict that commits is added
   // here, and the shared block below follows for free — the same reason the
   // engine keeps a `COMMITTING` list rather than a second condition.
-  var COMMITTERS = ['commit', 'commit-continue']
+  var COMMITTERS = ['commit', 'commit-continue', 'commit-start']
 
   /*
    * WHICH BUTTONS THIS PAGE OFFERS, and it comes from the render rather than
@@ -1250,7 +1500,15 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
    * changes.
    */
   var MIDRUN = data.buttons === 'midrun'
-  var OFFERED = MIDRUN ? ['continue', 'changes', 'discuss'] : ['commit', 'commit-continue', 'changes', 'discuss']
+  // ONE TABLE, keyed by the set the engine named. A chain of ternaries is how a
+  // third set becomes a fourth condition somebody forgets to add a button to.
+  var OFFERS = {
+    midrun: ['continue', 'changes', 'discuss'],
+    authoring: ['commit-start', 'commit', 'changes', 'discuss'],
+    refresh: ['commit', 'changes', 'discuss'],
+    committing: ['commit', 'commit-continue', 'changes', 'discuss'],
+  }
+  var OFFERED = OFFERS[data.buttons] || OFFERS.committing
   Object.keys(verdictBtns).forEach(function (key) {
     verdictBtns[key].hidden = OFFERED.indexOf(key) === -1
   })
@@ -1263,6 +1521,7 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
   var LABELS = {
     commit: '✓ Commit',
     'commit-continue': '✓ Commit & Continue',
+    'commit-start': '✓ Commit & Start',
     continue: '→ Continue',
     changes: '↺ Request changes',
     discuss: '… Discuss first',
@@ -1272,11 +1531,15 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
     // Says what it will NOT do: a reader must not press this expecting the
     // spec to be finished and landed.
     'commit-continue': 'Commit what you just read, then build the next phase — nothing is landed',
+    // Says what it WILL do, because this is the one verdict that provisions:
+    // a worktree appears and phase 1 starts.
+    'commit-start': 'Commit this spec, then put it in flight and build phase 1',
     // Says what it will NOT do, for the same reason: nothing is committed by
     // this, so the work it resumes is still uncommitted afterwards.
     continue: 'You have read it — carry on with the run; nothing is committed',
   }
 
+  var verdictEl = document.getElementById('verdict')
   var verdictCount = document.getElementById('verdict-count')
   var verdictLog = document.getElementById('verdict-log')
   var copyOut = document.getElementById('copy-out')
@@ -1289,6 +1552,14 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
   var sentCmd = document.getElementById('sent-cmd')
   var sentCmdText = document.getElementById('sent-cmd-text')
   var sentCmdCopy = document.getElementById('sent-cmd-copy')
+  var sentCmdLead = document.getElementById('sent-cmd-lead')
+  var failBox = document.getElementById('send-failed')
+  var failWhat = document.getElementById('send-failed-what')
+  var failNote = document.getElementById('send-failed-note')
+  var failCmd = document.getElementById('send-failed-cmd')
+  var failLead = document.getElementById('send-failed-lead')
+  var failText = document.getElementById('send-failed-text')
+  var failCopy = document.getElementById('send-failed-copy')
 
   function pending() {
     var b = buildBlob()
@@ -1320,6 +1591,10 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
     // the two committing buttons unconditionally, so without this it would undo
     // the ending every time anything redrew.
     if (decided) return drawDecided()
+    // Which shape this page offers is re-answered here rather than at load: a
+    // reader who ticks an accept half-way through has changed what their pass
+    // contains, and a command line cannot carry the new contents.
+    drawCmdList()
     var n = pending()
     var open = openNotes()
     verdictCount.textContent = n
@@ -1391,6 +1666,9 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
       'Sent to Claude' + (when ? ' on ' + when : '') + ' — this review is ' + said + '. ' +
       'Nothing here reaches Claude any more, so the verdict buttons are closed.'
     wrapEl.className = wrapEl.className.replace(/\s*\bis-decided\b/g, '') + ' is-decided'
+    // The commands go with the bar. A decided page offers no way to decide
+    // again, whichever shape it was offering.
+    if (cmdList) cmdList.hidden = true
     // EVERY button, not only the committing pair: `refresh` re-enables those two
     // by design, and a decided page must beat it.
     Object.keys(verdictBtns).forEach(function (key) {
@@ -1404,29 +1682,54 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
     // sentence again in smaller type, so it goes.
     verdictLog.hidden = true
 
+    // WHAT THE PAGE ESTABLISHED, replayed — never re-derived. `picked` is the
+    // answer the poll got, and a re-opened tab has no way to ask again for a
+    // pass that is long gone, so it says what it said before rather than
+    // quietly changing its mind a day later.
+    copyHint.hidden = true
+    copyOut.hidden = true
+    if (decided.picked === true) {
+      // NOTHING TO RUN, and so nothing offered. This is the whole point of
+      // asking: the command used to appear here on every single ending, which
+      // taught the reader it was decoration.
+      sentCmd.hidden = true
+      decidedNote.textContent += ' Claude picked this up — there is nothing to run.'
+      return
+    }
     // THE HAND-OFF SURVIVES THE ENDING — but only where there is something
     // worth carrying. A code is six digits to transcribe, and the box and its
     // Copy button exist for exactly that. A bare `/spec-reviewed` is a word the
     // reader is about to type into the terminal they are already sitting in;
     // dressing it as a copyable artefact makes the ending look unfinished.
     if (decided.cmd && /\s/.test(decided.cmd)) {
-      copyHint.hidden = false
-      copyHint.textContent = 'Sent. Run this where Claude is:'
+      decidedNote.textContent += ' It is still waiting to be picked up.'
       showCommand(decided.cmd)
       return
     }
-    copyHint.hidden = true
     sentCmd.hidden = true
-    copyOut.hidden = true
     if (decided.cmd) {
       decidedNote.textContent +=
         ' If Claude was not already waiting, run ' + decided.cmd + ' where it is.'
     }
   }
 
-  /** Record a verdict that was actually delivered, and end the page on it. */
-  function markDecided(verdict, cmd) {
-    decided = { verdict: verdict, at: new Date().toISOString(), cmd: cmd || null }
+  /**
+   * Record a verdict that was actually delivered, and end the page on it.
+   *
+   * `picked` is three-valued and the third value is the useful one: `true` the
+   * engine confirmed somebody claimed this pass, `false` it confirmed nobody
+   * has, and `null` NOTHING COULD BE ESTABLISHED — an older daemon with no
+   * lookup, a poll that never came back, a page that stopped asking. Only
+   * `true` takes the command away, so every way of not knowing leaves it on
+   * screen (`.claude/rules/negative-checks.md` rule 4).
+   */
+  function markDecided(verdict, cmd, picked) {
+    decided = {
+      verdict: verdict,
+      at: new Date().toISOString(),
+      cmd: cmd || null,
+      picked: picked === undefined ? null : picked,
+    }
     save()
     drawDecided()
   }
@@ -1447,6 +1750,7 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
     approve: 'committed',
     commit: 'committed',
     'commit-continue': 'committed, then carried on',
+    'commit-start': 'committed, then put in flight',
     continue: 'read it and carried on',
     changes: 'changes requested',
     discuss: 'discussed',
@@ -1482,29 +1786,122 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
    * here, not an edge one. A Copy button that does nothing when tapped is worse
    * than text that was always text, so the button only exists where it can work.
    */
+  /**
+   * Put the whole command in the reader's selection. Returns whether it worked.
+   *
+   * REPORTED, NOT ASSUMED. It replaces `input.select()`, which the box no longer
+   * has anything to call — and the honest thing to do when a browser withholds
+   * `getSelection` is to stop claiming the text is selected, rather than say so
+   * and leave someone hunting for a highlight that is not there.
+   */
+  function selectCommand() {
+    return selectNode(sentCmdText)
+  }
+
+  /**
+   * Put a node's whole text in the reader's selection. Returns whether it took.
+   */
+  function selectNode(node) {
+    try {
+      var range = document.createRange()
+      range.selectNodeContents(node)
+      var sel = window.getSelection && window.getSelection()
+      if (!sel) return false
+      sel.removeAllRanges()
+      sel.addRange(range)
+      return true
+    } catch (e) {
+      return false
+    }
+  }
+
+  /**
+   * Can this browser copy AT ALL — by either route?
+   *
+   * WHAT THIS GOT WRONG, and why the button kept vanishing where it was needed
+   * most: `navigator.clipboard` is **secure-context only**, so it is absent on
+   * every `http://<lan-ip>:7777` page — which is exactly the page someone reads
+   * on a phone. Asking only about that API therefore hid the Copy button in the
+   * one case the button exists for, and left a phone reader long-pressing to
+   * select text on a page that could have copied for them all along.
+   *
+   * `document.execCommand('copy')` is deprecated and universally implemented,
+   * and it works in a non-secure context inside a user gesture. So there are
+   * two routes, and the rule below is unchanged: offer the button only where
+   * one of them exists.
+   */
+  function canCopy() {
+    return Boolean(
+      (navigator.clipboard && navigator.clipboard.writeText) ||
+        (document.execCommand && window.getSelection),
+    )
+  }
+
+  /**
+   * Copy `text`, by whichever route this browser has. Resolves on success and
+   * rejects otherwise, so every caller reports the same three outcomes.
+   *
+   * `node` is what gets left selected when copying fails — the reader can then
+   * do it by hand, which is the behaviour this button replaced rather than
+   * removed.
+   */
+  function copyText(text, node) {
+    if (navigator.clipboard && navigator.clipboard.writeText) {
+      return navigator.clipboard.writeText(text)
+    }
+    return new Promise(function (resolve, reject) {
+      // The selection IS the mechanism here, not a consolation: execCommand
+      // copies what is selected. So it is made first and deliberately left in
+      // place — a failed copy then lands the reader exactly where the old
+      // no-clipboard path did.
+      if (!selectNode(node)) return reject(new Error('no selection'))
+      var ok = false
+      try {
+        ok = document.execCommand('copy')
+      } catch (e) {
+        ok = false
+      }
+      return ok ? resolve() : reject(new Error('execCommand refused'))
+    })
+  }
+
   function showCommand(cmd) {
     sentCmd.hidden = false
-    sentCmdText.value = cmd
-    var canCopy = Boolean(navigator.clipboard && navigator.clipboard.writeText)
-    sentCmdCopy.hidden = !canCopy
-    if (canCopy) return
-    // Selected, and SAID to be selected: a reader who sees nothing happen has
-    // no way to tell a page that did nothing from one that already did the work.
-    sentCmdText.focus()
-    sentCmdText.select()
-    copyHint.textContent = copyHint.textContent + ' (selected — copy it)'
+    sentCmdText.textContent = cmd
+    var copyable = canCopy()
+    sentCmdCopy.hidden = !copyable
+    sentCmdCopy.textContent = 'Copy'
+    // SET HERE, NOT LEFT TO THE MARKUP. The lead says two different things and
+    // the box is shown more than once in a page's life, so a line that was only
+    // ever correct on first render would go stale the moment either changed.
+    if (copyable) {
+      sentCmdLead.textContent = 'Run this where Claude is:'
+      // NOT SELECTED when there is a button. Pre-selecting made the line look
+      // like a focused input, which is what it was mistaken for — and it is the
+      // long-press-to-select gesture the button is here to spare a phone reader.
+      return
+    }
+    // Selected where that is possible, and SAID to be selected: a reader who
+    // sees nothing happen has no way to tell a page that did nothing from one
+    // that already did the work. The lead carries it now that the box lives in
+    // the decided panel — `copy-hint` is down in the footer with the verdict
+    // bar, and appending to it put the sentence half a page from the thing it
+    // describes.
+    sentCmdLead.textContent = selectCommand()
+      ? 'Run this where Claude is (selected — copy it):'
+      : 'Run this where Claude is — copy it:'
   }
 
   if (sentCmdCopy) {
     sentCmdCopy.addEventListener('click', function () {
-      navigator.clipboard.writeText(sentCmdText.value).then(function () {
+      copyText(sentCmdText.textContent, sentCmdText).then(function () {
         sentCmdCopy.textContent = 'Copied'
       }, function () {
         // The capability was there and the write still failed. Fall back to the
-        // same selection the no-clipboard path uses rather than saying nothing.
-        sentCmdText.focus()
-        sentCmdText.select()
-        sentCmdCopy.textContent = 'Copy failed — selected'
+        // same selection the no-clipboard path uses rather than saying nothing —
+        // and if even that is unavailable, say THAT, because a button reading
+        // "selected" over nothing highlighted is worse than an honest failure.
+        sentCmdCopy.textContent = selectCommand() ? 'Copy failed — selected' : 'Copy failed'
       })
     })
   }
@@ -1533,16 +1930,64 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
       into.appendChild(h)
     }
 
+    /**
+     * THE PHASE COMES FIRST, and the spec's Problem is folded away behind it.
+     *
+     * The open part of this header used to be `Why` — the overview's Problem,
+     * which is about the whole spec. A reader opening a page for phase 3 got
+     * the same paragraph they had already read at phase 1, and had to expand
+     * `More` to reach the only thing that told them what THIS review covers.
+     * The question a review page answers is "what am I looking at", so the
+     * phase answers it, and the background it sits in is one tap away.
+     *
+     * The TASK LIST is open too, deliberately. It is the cheapest statement of
+     * what is and is not in this diff — which matters most half-way through a
+     * phase, where a `/spec-diff` shows three ticked boxes and four empty ones
+     * and the empty ones are the reason the diff looks unfinished.
+     */
+    if (ctx.phase) {
+      head(why, 'Phase ' + ctx.phase.n + (ctx.phase.title ? ' — ' + ctx.phase.title : ''))
+      if (ctx.phase.goal) {
+        var g = document.createElement('p')
+        g.textContent = ctx.phase.goal
+        why.appendChild(g)
+      }
+      if (ctx.phase.tasks && ctx.phase.tasks.length) {
+        var ul = document.createElement('ul')
+        ul.className = 'tasks'
+        ctx.phase.tasks.forEach(function (task) {
+          var li = document.createElement('li')
+          // Done is dimmed rather than struck through: every task is ticked by
+          // the time a phase renders, and a whole list struck through reads as
+          // cancelled work.
+          li.className = task.done ? 'done' : ''
+          li.textContent = (task.done ? '✅ ' : '⬜ ') + task.text
+          ul.appendChild(li)
+        })
+        why.appendChild(ul)
+      }
+    }
+
     if (ctx.problem) {
-      // FIRST PARAGRAPH OPEN, the remainder folded. A phone shows perhaps six
-      // lines before the file list is pushed off-screen, and pushing it off is
-      // the thing this header was built to avoid.
+      // FOLDED, ALL OF IT. With the phase open above, the spec's Problem is
+      // background rather than the answer — and on a phone every line of it is
+      // a line of the file list pushed off-screen, which is the thing this
+      // header was built to avoid. Where there is NO phase (a branch-wide diff,
+      // a spec with no live phase) the first paragraph stays open, because then
+      // it is the only thing the header can say.
       var paras = String(ctx.problem).split(/\n\s*\n/)
-      head(why, 'Why')
-      var lead = document.createElement('p')
-      lead.textContent = paras[0].replace(/\s+/g, ' ').trim()
-      why.appendChild(lead)
-      for (var i = 1; i < paras.length; i++) {
+      var from = 0
+      if (!ctx.phase) {
+        head(why, 'Why')
+        var lead = document.createElement('p')
+        lead.textContent = paras[0].replace(/\s+/g, ' ').trim()
+        why.appendChild(lead)
+        from = 1
+      } else if (paras.length) {
+        head(rest, 'Why')
+        drewRest = true
+      }
+      for (var i = from; i < paras.length; i++) {
         var p = document.createElement('p')
         p.textContent = paras[i].replace(/\s+/g, ' ').trim()
         rest.appendChild(p)
@@ -1579,29 +2024,6 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
       }
     }
 
-    if (ctx.phase) {
-      head(rest, 'Phase ' + ctx.phase.n + (ctx.phase.title ? ' — ' + ctx.phase.title : ''))
-      drewRest = true
-      if (ctx.phase.goal) {
-        var g = document.createElement('p')
-        g.textContent = ctx.phase.goal
-        rest.appendChild(g)
-      }
-      if (ctx.phase.tasks && ctx.phase.tasks.length) {
-        var ul = document.createElement('ul')
-        ctx.phase.tasks.forEach(function (t) {
-          var li = document.createElement('li')
-          // Done is dimmed rather than struck through: every task is ticked by
-          // the time a phase renders, and a whole list struck through reads as
-          // cancelled work.
-          li.className = t.done ? 'done' : ''
-          li.textContent = (t.done ? '✅ ' : '⬜ ') + t.text
-          ul.appendChild(li)
-        })
-        rest.appendChild(ul)
-      }
-    }
-
     document.getElementById('context').hidden = false
     more.hidden = !drewRest
   }
@@ -1615,6 +2037,91 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
     copyHint.textContent = why
   }
 
+  /**
+   * Put the whole recovery command in the failure callout, with its Copy control.
+   *
+   * THE SAME CONTROL THE `file://` PAGE ALREADY USES — `/spec-reviewed <verdict>`
+   * — so there is one command row rather than a second kind. It reaches the
+   * agent regardless of any server, which is the only reason a recovery can be
+   * offered from a failed send at all.
+   *
+   * `canCopy` decides whether there is a button, exactly as `showCommand` does:
+   * a control that does nothing on tap reads as a broken page, and one that is
+   * missing where it would have worked reads as a page that never offered it.
+   */
+  function showFailCommand(cmd) {
+    failCmd.hidden = false
+    failText.textContent = cmd
+    var copyable = canCopy()
+    failCopy.hidden = !copyable
+    failCopy.textContent = 'Copy'
+    failLead.textContent = copyable
+      ? 'Your verdict is not lost — run this where Claude is:'
+      : selectNode(failText)
+        ? 'Your verdict is not lost — run this where Claude is (selected — copy it):'
+        : 'Your verdict is not lost — run this where Claude is — copy it:'
+  }
+
+  if (failCopy) {
+    failCopy.addEventListener('click', function () {
+      copyText(failText.textContent, failText).then(function () {
+        failCopy.textContent = 'Copied'
+      }, function () {
+        failCopy.textContent = selectNode(failText) ? 'Copy failed — selected' : 'Copy failed'
+      })
+    })
+  }
+
+  /** Take the failure panel down — a fresh attempt, or one that landed. */
+  function clearSendFailure() {
+    failBox.hidden = true
+    failCmd.hidden = true
+    failWhat.textContent = ''
+    failNote.textContent = ''
+  }
+
+  /**
+   * Say that a send did not land, as loudly as a send that did.
+   *
+   * THE ONE OUTCOME THE READER MUST ACT ON used to be reported more quietly than
+   * the one they need do nothing about: a small grey line in the footer, under a
+   * verdict bar that had just closed. It gets the panel at the top of the column
+   * now, in the delete palette.
+   *
+   * IT DOES NOT DECIDE THE PAGE. Nothing was delivered, so the diff stays and
+   * the verdict buttons stay live — a page that closed its controls over a
+   * failed send would strand the reader with no way to try again.
+   *
+   * A pass carrying MARKS still goes to the clipboard, because a command line
+   * cannot carry notes and a failed send must not become the moment they are
+   * silently dropped.
+   */
+  function sendFailed(json, verdict, what, note) {
+    copyHint.hidden = true
+    copyHint.textContent = ''
+    failBox.hidden = false
+    failWhat.textContent = what
+    if (pending() > 0) {
+      failCmd.hidden = true
+      failNote.textContent =
+        note +
+        ' You have marked things up, and a command line cannot carry notes — the whole pass is ' +
+        'below. Copy it and paste it to Claude.'
+      copyOut.hidden = false
+      copyOut.value = json
+      copyOut.focus()
+      copyOut.select()
+    } else {
+      failNote.textContent = note
+      showFailCommand('/spec-reviewed ' + verdict)
+    }
+    // WHERE THE READER IS LOOKING. The verdict bar is at the foot of the page
+    // and this panel is at the head of it, so a failure announced without this
+    // is a failure announced off-screen — which is the shape of the bug being
+    // fixed, one scroll position removed.
+    if (failBox.scrollIntoView) failBox.scrollIntoView()
+  }
+
   // One action per decision: the verdict button IS the copy button, so the blob
   // can never carry a verdict other than the one just pressed.
   /**
@@ -1625,6 +2132,7 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
    * much you wrote.
    */
   function post(json, verdict) {
+    clearSendFailure()
     copyHint.hidden = false
     copyHint.textContent = 'Sending…'
     fetch(location.pathname, {
@@ -1634,11 +2142,45 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
     }).then(function (res) {
       return res.text().then(function (text) {
         if (!res.ok) {
-          // A pass the server REFUSED must never read as sent. Its message
-          // names the entry that was wrong, so it is shown rather than summarised.
-          copyHint.textContent = 'Not sent — ' + (text || res.status)
+          // A pass the server REFUSED must never read as sent — and WHICH
+          // refusal decides where the reader goes next, so the two are named
+          // separately rather than collapsed into one "not sent".
+          if (res.status === 404) {
+            // THE PORT MOVED, or another repo's daemon holds this one. The token
+            // in this URL means nothing there, so re-opening the page from the
+            // session that produced it is the fix — the link is stale, the pass
+            // is fine.
+            sendFailed(
+              json,
+              verdict,
+              'Not sent — this page\'s server is gone.',
+              'Nothing is answering at this address any more: the review server moved to another ' +
+                'port, or a different repo holds this one. Re-open the page from the Claude Code ' +
+                'session that produced it and the buttons below will send.',
+            )
+          } else if (res.status === 422) {
+            // THE ENGINE READ IT AND SAID NO. Its message names the entry that
+            // was wrong, so it is relayed verbatim — paraphrasing is how a
+            // reader ends up hunting for a problem the tool had already named.
+            // AND NO "re-open": the page is fine, and re-opening would only be
+            // refused again.
+            sendFailed(
+              json,
+              verdict,
+              'Not sent — the engine refused this pass.',
+              text || 'It answered ' + res.status + ' without saying why.',
+            )
+          } else {
+            sendFailed(
+              json,
+              verdict,
+              'Not sent — the server answered ' + res.status + '.',
+              text || 'It gave no reason.',
+            )
+          }
           return
         }
+        clearSendFailure()
         var code = ''
         try { code = JSON.parse(text).code } catch (e) {}
         // NAME THE COMMAND. Not "claim it with 418207", which instructs a
@@ -1648,25 +2190,194 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
         // stays, as the thing to CHECK: it is the one part of a waiting pass
         // that tells yours apart from anyone else's.
         if (code) {
-          copyHint.textContent = 'Sent. Run this where Claude is:'
-          showCommand('/spec-reviewed ' + code)
-          markDecided(verdict, '/spec-reviewed ' + code)
+          // SENT, AND NOW ASK WHAT BECAME OF IT. The page used to name the
+          // command here unconditionally — the same sentence whether a session
+          // was waiting to claim the pass or nothing was — because it had no
+          // way to find out. It has one now.
+          markDecided(verdict, '/spec-reviewed ' + code, null)
+          watchPass(code, verdict)
         } else {
           // NO CODE, NO COMMAND. A `/spec-reviewed` with nothing after it still
           // works — it picks up the single waiting pass — but the page cannot
           // claim the server named THIS one, so it does not put words in its
           // mouth. Bare is what the reader is told, because bare is what is true.
           copyHint.textContent = 'Sent — run /spec-reviewed to pick it up.'
-          markDecided(verdict)
+          markDecided(verdict, null, null)
         }
       })
     }, function () {
-      // The server was there when the page was served and is not now. Falling
-      // back to the clipboard keeps the pass recoverable rather than lost.
-      showFallback(json, 'Could not reach the server. Copy this, then paste it to Claude.')
+      // THE REQUEST NEVER ARRIVED — the network, or a server that has stopped.
+      // Distinct from both refusals above: there is no status and no message,
+      // because nothing answered. Re-opening may fix it and the command
+      // certainly will, so both are offered.
+      sendFailed(
+        json,
+        verdict,
+        'Not sent — could not reach the server.',
+        'The request did not arrive: the server has stopped, or this device cannot reach it. ' +
+          'Re-open the page from the session that produced it to try again.',
+      )
     })
   }
 
+  /* ==========================================================================
+   * The command list — a verdict bar for a page that cannot deliver one
+   *
+   * A `file://` page has no server and no store, so its buttons never sent
+   * anything: they built a JSON blob and put it on the clipboard to paste. That
+   * is still the only way a pass carrying MARKS can travel, and it stays. What
+   * changes is the common case — a reader who ticked nothing and wrote nothing,
+   * whose whole pass is one word — where a command they run in the terminal
+   * beside them beats a wall of text every time.
+   *
+   * WHICH SHAPE IS LIVE IS DECIDED BY WHAT THE PASS CARRIES, and it is
+   * re-decided on every mark. Tick one accept and the rows stand down, because
+   * a command line cannot carry someone's notes and dropping them silently
+   * would be worse than asking for the paste. Clear it again and they return.
+   * ======================================================================== */
+
+  // Only a `file://` page. A served page posts; a published one writes to its
+  // store. Both can deliver, so both keep their buttons — decided from what the
+  // page IS, exactly as `send` decides.
+  var NO_TRANSPORT = location.protocol === 'file:' && !isArtifact()
+  var cmdList = document.getElementById('cmd-list')
+  var cmdLead = document.getElementById('cmd-lead')
+  var cmdRows = {}
+
+  function buildCmdRows() {
+    if (!NO_TRANSPORT || !cmdList) return
+    // WHERE, not just what. "Run one of these where it is" assumed the reader
+    // knew which terminal counts, and there is usually more than one open. The
+    // answer is specific and worth saying: the session that produced this page
+    // is the one holding the review.
+    cmdLead.textContent =
+      'This page has no way to reach Claude. Copy one of these and paste it into the ' +
+      'Claude Code session that produced this review — that is the one waiting for your verdict.'
+    // THE SAME LIST THE BAR USES. `OFFERED` already answers which verdicts this
+    // render offers — a mid-run page lists Continue and never the committing
+    // pair — so deriving the rows from it is what keeps the two from drifting.
+    OFFERED.forEach(function (verdict) {
+      var row = el('div', 'cmd-row')
+      row.setAttribute('data-verdict', verdict)
+      var label = el('span', 'cmd-label', LABELS[verdict])
+      var cmd = el('code', 'cmd-text', '/spec-reviewed ' + verdict)
+      row.appendChild(label)
+      row.appendChild(cmd)
+      // NEVER A BUTTON THAT CANNOT COPY — the same rule `showCommand` follows,
+      // through the same `canCopy`. A control that does nothing on tap reads as
+      // a broken page; a control that is MISSING where it would have worked
+      // reads as a page that never offered it, which is the failure this shares
+      // its capability check to avoid.
+      if (canCopy()) {
+        var copy = el('button', 'cmd-copy', 'Copy')
+        copy.setAttribute('type', 'button')
+        copy.addEventListener('click', function () {
+          copyText(cmd.textContent, cmd).then(function () {
+            // COPIED IS DECIDED. The reader has the command; what happens next
+            // happens in their terminal, and the page has nothing left to do
+            // but say what they chose — with the command repeated, because a
+            // copy can fail silently and an hour later this box is the only
+            // record of it.
+            markDecided(verdict, cmd.textContent, false)
+          }, function () {
+            copy.textContent = selectNode(cmd) ? 'Copy failed — selected' : 'Copy failed'
+          })
+        })
+        row.appendChild(copy)
+      }
+      cmdList.appendChild(row)
+      cmdRows[verdict] = row
+    })
+  }
+
+  /**
+   * Decide, now, which of the two shapes this page is offering.
+   *
+   * Called from `refresh`, so it re-answers on every mark rather than once at
+   * load: the reader who ticks an accept half-way through has changed what
+   * their pass contains, and the page has to change with them.
+   */
+  function drawCmdList() {
+    if (!NO_TRANSPORT || !cmdList) return
+    var marked = pending() > 0
+    cmdList.hidden = marked
+    Object.keys(cmdRows).forEach(function (k) { cmdRows[k].hidden = marked })
+    // The bar comes back to carry what a command cannot, and SAYS SO. A reader
+    // whose notes had been dropped would not find out until the review came
+    // back without them.
+    verdictEl.hidden = !marked
+    if (marked) {
+      copyHint.hidden = false
+      copyHint.textContent =
+        'You have marked something up, and a command line cannot carry notes — ' +
+        'use a verdict button below and paste what it copies.'
+    } else if (copyHint.textContent.indexOf('cannot carry notes') !== -1) {
+      copyHint.hidden = true
+      copyHint.textContent = ''
+    }
+  }
+
+  // How long to keep asking, and how often. A claim is a file-watch waking a
+  // session that is already sitting there, so the answer normally arrives in
+  // well under a second; these are sized for the case where it does not.
+  var PASS_POLL_MS = 900
+  var PASS_POLL_ROUNDS = 8
+
+  /**
+   * Ask the engine what became of the pass we just sent, and end on the answer.
+   *
+   * THE PAGE STOPPED GUESSING. It used to hand over `/spec-reviewed <code>` on
+   * every successful POST, because it could not tell an auto-claimed pass from
+   * one nobody was listening for — so the reader was told to run a command they
+   * almost never needed, in the same words used when running it was the only
+   * thing that would save their review. Both sentences are now earned.
+   *
+   * ONE ANSWER TAKES THE COMMAND AWAY, and it is the positive one: `claimed`,
+   * which the engine reads off a decision log that NAMES this code. Everything
+   * else — `waiting`, `unknown`, a server that never replied, a body that did
+   * not parse, an older daemon with no lookup, the rounds running out — leaves
+   * the command exactly where it is. A command nobody needed to run costs a
+   * glance; a pass nobody claims costs the review.
+   *
+   * WHAT WOULD FOOL A LOOSER VERSION: treating a failed poll as "probably fine".
+   * The failures that make a poll fail are the same ones that make a claim fail
+   * — the machine sleeping, the daemon restarting, the network going — so the
+   * moment this is least able to see is the moment its answer matters most.
+   */
+  function watchPass(code, verdict) {
+    var rounds = 0
+    // `?pass=` on the page's own path, so the serve token in the URL guards
+    // this exactly as it guards everything else and there is no second address.
+    var url = location.pathname + '?pass=' + encodeURIComponent(code)
+
+    function stop(picked) {
+      markDecided(verdict, '/spec-reviewed ' + code, picked)
+    }
+
+    function ask() {
+      rounds++
+      fetch(url, { method: 'GET', headers: { accept: 'application/json' } }).then(function (res) {
+        if (!res || !res.ok) return again()
+        return res.text().then(function (text) {
+          var state = null
+          try { state = JSON.parse(text).state } catch (e) {}
+          if (state === 'claimed') return stop(true)
+          return again()
+        })
+      }, again)
+    }
+
+    function again() {
+      // Out of rounds is a CANNOT-TELL, not a no. Nobody is obliged to claim a
+      // pass inside seven seconds, and a page that concluded "abandoned" would
+      // be inventing an answer out of its own impatience.
+      if (rounds >= PASS_POLL_ROUNDS) return stop(false)
+      window.setTimeout(ask, PASS_POLL_MS)
+    }
+
+    ask()
+  }
+
   /**
    * Is this page running as a published Artifact?
    *
@@ -1714,7 +2425,11 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
           // the one thing that is true and actionable.
           copyHint.textContent = 'Sent. Run this where Claude is:'
           showCommand('/spec-reviewed')
-          markDecided(verdict, '/spec-reviewed')
+          // A PUBLISHED PAGE CANNOT ASK. The pass went into the artifact's own
+          // store, which the engine only reads when someone tells it to, so
+          // nothing here could ever come back `true` — and the command is the
+          // whole ending rather than a fallback within it.
+          markDecided(verdict, '/spec-reviewed', null)
         })
     }).then(null, function (err) {
       if (landed) return
@@ -1762,6 +2477,181 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
     })
   }
 
+  /**
+   * The surfaces strip: where this review lives, and whether it is also running.
+   *
+   * AN ACTION IS NOT A VERDICT, and the whole strip exists to make that visible.
+   * A verdict is the reader's conclusion, consumed once. These change what is
+   * RUNNING (or which tiers are permitted) and hand the reader straight back to
+   * the same page with the same options — so pressing one must not close the
+   * page into its decided state, and must not clear a gate.
+   *
+   * ENABLE-ONLY for the tiers. Turning `network` off from a page reached over
+   * the network kills the page doing the turning, and the reader gains nothing
+   * they could not get by typing the command — so the engine's `tierAction`
+   * never offers a disable and this renders whatever it is given.
+   */
+  var ACTION_LABEL = {
+    'live-on': '▶ Put it live',
+    'allow-network': '▶ Allow network',
+    'allow-remote': '▶ Allow remote',
+  }
+  var ACTION_CMD = {
+    'live-on': '/spec-live',
+    'allow-network': 'skitterspec spec-env review allow network',
+    'allow-remote': '/spec-remote-review',
+  }
+  var SURFACE_LABEL = { live: 'live', network: 'network', remote: 'remote' }
+
+  function surfaceStateText(row) {
+    if (row.kind === 'live') {
+      if (row.state === 'on') return row.url ? 'on — running at ' + row.url : 'on'
+      if (row.state === 'held') return row.reason || 'held by another spec'
+      return 'off'
+    }
+    if (row.state === 'on') return row.url ? 'on — ' + row.url : 'on'
+    return row.state === 'off' ? 'off' : 'unavailable'
+  }
+
+  function buildSurfaces() {
+    var section = document.getElementById('surfaces')
+    var host = document.getElementById('surface-rows')
+    // ABSENT, NOT EMPTY. A render that carried no surfaces gets no strip and no
+    // line explaining the absence — a `--docs` page has no branch to put live,
+    // and that is a healthy page rather than a deprived one.
+    if (!section || !host || !data.surfaces || !data.surfaces.length) return
+    section.hidden = false
+    data.surfaces.forEach(function (row) {
+      var div = document.createElement('div')
+      div.className = 'surface-row'
+      var label = document.createElement('span')
+      label.className = 'surface-label'
+      label.textContent = SURFACE_LABEL[row.kind === 'live' ? 'live' : row.tier] || ''
+      div.appendChild(label)
+      var state = document.createElement('span')
+      state.className = 'surface-state'
+      state.textContent = surfaceStateText(row)
+      div.appendChild(state)
+      if (row.action) {
+        if (NO_TRANSPORT) {
+          // No server and no store, so a button here would build an instruction
+          // with nowhere to go. The command is the honest control — exactly the
+          // trade the verdict bar already makes on a `file://` page.
+          var cmd = document.createElement('code')
+          cmd.className = 'surface-cmd'
+          cmd.textContent = ACTION_CMD[row.action] || ''
+          div.appendChild(cmd)
+        } else {
+          var btn = document.createElement('button')
+          btn.type = 'button'
+          btn.textContent = ACTION_LABEL[row.action] || row.action
+          btn.setAttribute('data-action', row.action)
+          btn.addEventListener('click', function () {
+            if (btn.disabled) return
+            sendAction(row.action, btn)
+          })
+          div.appendChild(btn)
+        }
+      }
+      // THE COMMAND FOR A DIRECTION THE PAGE DOES NOT OFFER. A live spec shows
+      // no press — handing the instance back to `main` is a workspace decision,
+      // not this review's — so the line names `/spec-live main` instead, and the
+      // reader is never left knowing what they want and not what to type.
+      if (row.command && !row.action) {
+        var cmdOnly = document.createElement('code')
+        cmdOnly.className = 'surface-cmd'
+        cmdOnly.textContent = row.command
+        div.appendChild(cmdOnly)
+      }
+      if (row.note) {
+        var note = document.createElement('span')
+        note.className = 'surface-note'
+        note.textContent = row.note
+        div.appendChild(note)
+      }
+      host.appendChild(div)
+    })
+  }
+
+  /**
+   * Send an action, and leave the page exactly as live as it was.
+   *
+   * IT CARRIES NO MARKS. An action blob is an instruction, not a review pass —
+   * so the accepts and comments stay on the page and travel with the verdict
+   * the reader eventually chooses. Sending them here would merge them early and
+   * then send them again, which is one reader's review counted twice.
+   *
+   * AND IT NEVER CALLS `markDecided`. The reader still owes a verdict; closing
+   * the page over an action would be the record-and-do-nothing ending this
+   * whole contract is against.
+   */
+  function sendAction(action, btn) {
+    var blob = {
+      version: 1,
+      spec: data.spec,
+      generatedAt: data.generatedAt,
+      accepted: [],
+      unaccepted: [],
+      comments: [],
+      action: action,
+    }
+    btn.disabled = true
+    var was = btn.textContent
+    btn.textContent = 'Sending…'
+    fetch(location.pathname, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(blob),
+    }).then(function (res) {
+      if (!res || !res.ok) {
+        btn.disabled = false
+        btn.textContent = was
+        return
+      }
+      return res.text().then(function (text) {
+        var code = null
+        try { code = JSON.parse(text).code } catch (e) {}
+        btn.textContent = 'Sent'
+        // RELOAD WHEN IT HAS BEEN ACTED ON, not on a timer. The agent re-renders
+        // after the action, so the page the reader wants is the next one — and
+        // `?pass=` already answers whether this exact code was claimed. Running
+        // out of rounds leaves the page alone rather than reloading on a guess.
+        if (code) watchAction(code, btn)
+      })
+    }, function () {
+      btn.disabled = false
+      btn.textContent = was
+    })
+  }
+
+  function watchAction(code, btn) {
+    var rounds = 0
+    var url = location.pathname + '?pass=' + encodeURIComponent(code)
+    function ask() {
+      rounds++
+      fetch(url, { method: 'GET', headers: { accept: 'application/json' } }).then(function (res) {
+        if (!res || !res.ok) return again()
+        return res.text().then(function (text) {
+          var state = null
+          try { state = JSON.parse(text).state } catch (e) {}
+          if (state === 'claimed') return window.location.reload()
+          return again()
+        })
+      }, again)
+    }
+    function again() {
+      // CANNOT TELL, so change nothing. Nobody is obliged to act on an action
+      // inside a few seconds, and a page that reloaded out of impatience would
+      // throw away marks the reader had not sent yet.
+      if (rounds >= PASS_POLL_ROUNDS) {
+        btn.textContent = 'Sent — reload when it is done'
+        return
+      }
+      window.setTimeout(ask, PASS_POLL_MS)
+    }
+    ask()
+  }
+
   Object.keys(verdictBtns).forEach(function (verdict) {
     verdictBtns[verdict].addEventListener('click', function () {
       // A disabled or hidden button does not fire in a browser; the guard is
@@ -1788,6 +2678,8 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
   }
 
   restore()
+  buildCmdRows()
+  buildSurfaces()
   drawContext()
   drawLog()
   drawDecided()
@@ -1813,7 +2705,54 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
   })
 
   // --- header --------------------------------------------------------------
-  document.getElementById('title').textContent = data.title
+  var titleEl = document.getElementById('title')
+  titleEl.textContent = data.title
+  /**
+   * The tracker ticket, beside the title and linked where there is a url.
+   *
+   * `href` IS SET ONLY FROM A URL THE ENGINE ALREADY VETTED as http(s) — see
+   * `readTicket`. The value originates in a spec file someone edits, and this
+   * page is served over the network, so a `javascript:` url in an href would be
+   * script execution. An id with no usable url still renders; it just does not
+   * become a link, which is the harmless half of the pair.
+   */
+  ;(function () {
+    var tk = data.context && data.context.ticket
+    if (!tk || !tk.id) return
+    var node
+    if (tk.url) {
+      node = document.createElement('a')
+      node.setAttribute('href', tk.url)
+      node.setAttribute('target', '_blank')
+      node.setAttribute('rel', 'noopener noreferrer')
+    } else {
+      node = document.createElement('span')
+    }
+    node.className = 'ticket'
+    node.textContent = tk.id
+    titleEl.appendChild(document.createTextNode(' '))
+    titleEl.appendChild(node)
+  })()
+
+  /**
+   * An ISO timestamp is a machine's format. The header showed
+   * `2026-09-16T13:53:58.370Z` to a person deciding whether a page was stale,
+   * which is the one question it is there to answer and the hardest way to ask
+   * it. Rendered in the READER's locale and zone, because that is the clock
+   * they are comparing against; the raw value stays as the `title` so nothing
+   * precise is lost, and it survives a browser that throws on either call.
+   */
+  function whenRendered(iso) {
+    try {
+      var d = new Date(iso)
+      if (isNaN(d.getTime())) return iso
+      return d.toLocaleString(undefined, {
+        day: 'numeric', month: 'short', year: 'numeric', hour: '2-digit', minute: '2-digit',
+      })
+    } catch (e) {
+      return iso
+    }
+  }
   var t = data.totals
   var sub = document.getElementById('sub')
   function part(text, cls) { sub.appendChild(el('span', cls, text)) }
@@ -1822,7 +2761,9 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
   sep()
   part(data.mode === 'branch'
     ? 'everything since ' + data.base + (data.fellBack ? ' (working tree clean)' : '')
-    : 'uncommitted work')
+    : data.mode === 'docs'
+      ? "the spec's own documents"
+      : 'uncommitted work')
   sep()
   part(t.files + ' file' + (t.files === 1 ? '' : 's'))
   sep()
@@ -1830,7 +2771,9 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
   part(' ')
   part('-' + t.deletions, 'd')
   sep()
-  part(data.generatedAt)
+  var when = el('span', null, whenRendered(data.generatedAt))
+  when.setAttribute('title', data.generatedAt)
+  sub.appendChild(when)
 })()
 </script>
 </body>