@renzrollon/interlock 1.1.1 → 1.2.1

package/lib/prompts/verify.mjs

@@ -29,6 +29,27 @@ function retryPreamble(fixAttempt, fixAttemptsRemaining, errors) {
   )
 }
 
+// Shell-quoted, because a planned command is one argument to the wrapper and
+// routinely holds spaces, `&&` or a pipe. The same rule `workflows/ship.js`
+// quotes a relay's argv with.
+const quote = a => (/[^\w@%+=:,./-]/.test(String(a)) ? `'${String(a).replace(/'/g, `'\\''`)}'` : String(a))
+
+/**
+ * One planned step as the line the agent runs: the command, verbatim, inside
+ * `interlock verify exec`, which passes its output and exit code through and
+ * records how long it took. The inter-wave budget is charged from that record —
+ * the CLI's own clock around the command — rather than from the relay and agent
+ * time between the step's dispatch and its judgement.
+ *
+ * The line is the shell command and nothing else. The briefing says to run each
+ * line exactly as written, so a `kind:` label in front of it would be run too —
+ * and fail. The kind is already on the line, as `--kind`.
+ */
+function execLine(s) {
+  const cwd = typeof s.cwd === 'string' && s.cwd.trim() && s.cwd.trim() !== '.' ? ` --cwd ${quote(s.cwd.trim())}` : ''
+  return `  interlock verify exec --kind ${quote(s.kind)}${cwd} --command ${quote(s.command)}`
+}
+
 /**
  * @param {object} input
  * @param {string} input.change
@@ -51,7 +72,7 @@ export function assembleVerifyPrompt({
   fixAttemptsRemaining,
   errors
 }) {
-  const planned = (Array.isArray(steps) ? steps : []).map(s => `  ${s.kind}: ${s.command}`).join('\n')
+  const planned = (Array.isArray(steps) ? steps : []).map(execLine).join('\n')
   // A run id the CLI already knows is stated; otherwise the agent is told where
   // to read it, rather than being left to invent one and spill into nowhere.
   const spillRunId = runId
@@ -66,6 +87,8 @@ export function assembleVerifyPrompt({
     `Run these verification steps for change "${change}" and report what happened.\n\n` +
     retry +
     planned +
+    `\n\nRun each line above exactly as written, as one shell command: \`interlock verify exec\` runs the command unchanged — its ` +
+    `output and exit code are the command's own — and records how long the check took.` +
     // The repair clause is the one sentence a retry must not inherit: "do not
     // repair on a first failure" is exactly wrong on the second attempt, which
     // exists to repair.

package/lib/receipt.mjs

@@ -103,8 +103,14 @@ export function tailFromManifest(manifest) {
  *   degradations?: string[],
  *   planFingerprint?: string,
  *   leftoverTaskIds?: string[],
- *   host?: {id?: string, billing?: string, hooks?: boolean, usage?: boolean}
- * }} input
+ *   host?: {id?: string, billing?: string, hooks?: boolean, usage?: boolean,
+ *     cacheAccounting?: boolean|'hook'},
+ *   lanesStoppedByHost?: number, schemaResultsMissing?: number,
+ *   toolsDeniedInLanes?: number, modelSubstitutions?: number,
+ *   permissionPrompts?: number, autoModeDenials?: number,
+ *   surface?: string, stateHome?: string
+ * }} input the six counts are passed only when the run observed agents at all
+ *   (a host record or a sidecar); leaving one out records it as unobserved
  */
 export function buildReceipt(input) {
   const source = input || {}
@@ -143,6 +149,12 @@ export function buildReceipt(input) {
   // outcome corpus's comparisons are only meaningful if the run said so itself.
   const host = source.host && typeof source.host === 'object' ? source.host : null
 
+  // A count the run measured, zero included, or `undefined`. Never a default:
+  // a run that saw no host record and no sidecar observed no agent, and a zero
+  // here would file it beside a run that watched every lane and found nothing.
+  const measured = value => (typeof value === 'number' && Number.isFinite(value) ? value : undefined)
+  const named = value => (typeof value === 'string' && value.length > 0 ? value : undefined)
+
   return {
     type: 'run-receipt',
     change: source.change,
@@ -155,7 +167,12 @@ export function buildReceipt(input) {
           // Recorded per run so a reader can PARTITION the corpus rather than
           // average across it: cache figures exist on some hosts and not others,
           // and that asymmetry is stated rather than engineered away.
-          cacheAccounting: host.cacheAccounting
+          cacheAccounting: host.cacheAccounting,
+          // The effort capability the host declared (flag, negotiated or
+          // unsupported), so a reader can tell a run whose effort was applied
+          // from one where it could not be. `null` when the manifest predates
+          // the capability, never the assumed `flag`.
+          effort: host.effort ?? null
         }
       : undefined,
     waves: (Array.isArray(summary.waves) ? summary.waves : []).map(wave => ({
@@ -230,7 +247,21 @@ export function buildReceipt(input) {
           (paths
             ? 'the executed plan could not be read back at close'
             : 'the run did not reach its close, so the executed plan was never read'),
-    degradations: source.degradations
+    degradations: source.degradations,
+    // What the run observed about its agents (design D8), copied by name. The
+    // close counts them off the host records and the sidecar; this only
+    // carries what it was handed, so the banners and the counts cannot come
+    // apart through a second derivation here.
+    lanesStoppedByHost: measured(source.lanesStoppedByHost),
+    schemaResultsMissing: measured(source.schemaResultsMissing),
+    toolsDeniedInLanes: measured(source.toolsDeniedInLanes),
+    modelSubstitutions: measured(source.modelSubstitutions),
+    permissionPrompts: measured(source.permissionPrompts),
+    autoModeDenials: measured(source.autoModeDenials),
+    // Where the run ran and where its corpora went (design D14), as `run start`
+    // recorded them — never re-resolved at close, so one run names one home.
+    surface: named(source.surface),
+    stateHome: named(source.stateHome)
   }
 }
 
@@ -278,6 +309,17 @@ export function degradationLines({ banners = [], closing = null, hostBanners = [
   return [...new Set(out)]
 }
 
+// Whether two absolute paths name the same directory for the purpose of the
+// `state home:` row. Import-free like the rest of this module, so it compares
+// text: trailing separators are ignored and nothing touches the filesystem. A
+// home recorded through a symlink and a cwd reached through its real path read
+// as different, which prints a row naming a real path — never a lost one.
+function samePath(a, b) {
+  if (typeof a !== 'string' || typeof b !== 'string') return false
+  const trim = p => (p.length > 1 ? p.replace(/[\\/]+$/, '') || p.slice(0, 1) : p)
+  return trim(a) === trim(b)
+}
+
 /**
  * The summary's first line, exactly as `formatRunSummary` prints it.
  *
@@ -302,10 +344,10 @@ export function summaryHeadline({ change, halted, leftoverTaskIds } = {}) {
  * Silence is the failure mode it exists to remove: a summary with no banner
  * section is indistinguishable from a run that degraded and hid it.
  *
- * `runId`, `root`, `projectSlug`, `push`, `unarchived` and `resumeCard` all
- * default so this stays callable exactly as it was before design D7/D8/D9 and
- * the halt resume card added them — the receipt module stays import-free either
- * way.
+ * `runId`, `root`, `projectSlug`, `stateHome`, `push`, `unarchived` and
+ * `resumeCard` all default so this stays callable exactly as it was before
+ * design D7/D8/D9, the halt resume card and the state home added them — the
+ * receipt module stays import-free either way.
  */
 export function formatRunSummary({
   change,
@@ -316,6 +358,7 @@ export function formatRunSummary({
   runId = undefined,
   root = undefined,
   projectSlug = undefined,
+  stateHome = undefined,
   push = null,
   unarchived = null,
   resumeCard = null
@@ -390,6 +433,14 @@ export function formatRunSummary({
   )
   if (projectSlug !== undefined && projectSlug !== null) lines.push(`  project: ${projectSlug}`)
   if (root !== undefined && root !== null) lines.push(`  cwd: ${root}`)
+  // Where the run's trajectory, outcome line, metrics and resume card went
+  // (design D14), directly under the directory the close ran in, and only when
+  // the two differ: a main-checkout run's summary stays byte-identical, and a
+  // linked-worktree run tells its reader that its records are not in the tree
+  // they are looking at.
+  if (typeof stateHome === 'string' && stateHome.length > 0 && !samePath(stateHome, root)) {
+    lines.push(`  state home: ${stateHome}`)
+  }
 
   // The push outcome (design D5): a row only when a push was actually
   // attempted — an unconfigured relay is an optional feature left off, not a

package/lib/report-html.mjs

@@ -28,10 +28,11 @@
 // through the `html` tagged template below, which escapes unless a fragment is
 // explicitly marked `raw`. There is no second interpolation path.
 
-// The one thing this renderer imports: the wording of an absence it shares with
-// the text surface. Two surfaces describing the same absence in different words
-// is how a reader comes to believe they are looking at two different facts.
-import { NO_EVAL_RESULT } from './report.mjs'
+// The only things this renderer imports: wording it shares with the text
+// surface — an absence, and the surface partition's bucket labels. Two surfaces
+// describing the same fact in different words is how a reader comes to believe
+// they are looking at two different facts.
+import { NO_EVAL_RESULT, SURFACE_BUCKETS } from './report.mjs'
 
 const ESCAPES = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }
 
@@ -195,10 +196,79 @@ function evalHistoryCorpus(e) {
   )
 }
 
+/**
+ * Trajectories in the home repository's other worktrees: counted, never read.
+ *
+ * A scan that could not be made renders as a word at full weight with its
+ * reason, never as a zero — a count nobody took is not a count of nothing.
+ */
+function unreadWorktrees(u) {
+  if (!u) return ''
+  const counted = u.runs !== null && u.runs !== undefined && u.worktrees !== null && u.worktrees !== undefined
+  const count = counted
+    ? raw(html`<span class="num">${u.runs}</span> file(s) across <span class="num">${u.worktrees}</span> worktree(s), not read`)
+    : raw('<span class="word">NOT COUNTED</span>')
+
+  const notes = []
+  if (!counted) notes.push(`could not be counted: ${u.reason || 'no reason was given'}`)
+
+  return (
+    html`<div class="corpus"><div class="corpus-head"><h3>Trajectories in other linked worktrees</h3>
+      <div class="corpus-count">${count}</div></div>
+      <p class="reason">Counted by file name from the repository's worktree list. None was opened, and no
+      figure on this page includes them.</p>` +
+    (notes.length ? html`<ul class="named">${raw(notes.map(n => html`<li>${n}</li>`).join(''))}</ul>` : '') +
+    (u.unscannable && u.unscannable.length
+      ? html`<div class="named-head">Worktrees not counted, named rather than skipped</div><ul class="named">` +
+        raw(u.unscannable.map(w => html`<li><span class="file">${w.worktree}</span> — ${w.reason}</li>`).join('')) +
+        '</ul>'
+      : '') +
+    '</div>'
+  )
+}
+
+/** The partition of the scanned runs by the surface each `run-start` recorded. Every bucket, zeros included. */
+function surfacePartition(surfaces, scanned) {
+  if (!surfaces) return ''
+  return (
+    html`<div class="named-head">Surface each run-start recorded — over ${scanned} scanned</div>` +
+    html`<dl class="facets surfaces">${raw(
+      SURFACE_BUCKETS.map(b => html`<div><dt>${b.label}</dt><dd class="num">${surfaces[b.key] ?? 0}</dd></div>`).join('')
+    )}</dl>`
+  )
+}
+
+/**
+ * Said only when the home is not simply the one git named: an unresolved home,
+ * or a surface the resolver could not establish. Never left to the header row.
+ */
+function stateHomeNotice(h) {
+  if (!h) return ''
+  if (h.resolvedFrom === 'fallback') {
+    return html`<p class="reason">STATE HOME UNRESOLVED: ${h.reason || 'no reason was given'} — every corpus was read from the root.</p>`
+  }
+  if (h.reason) return html`<p class="reason">Surface unknown: ${h.reason}</p>`
+  return ''
+}
+
+const RESOLVED_FROM_WORDS = Object.freeze({
+  explicit: 'explicit — --state-home or INTERLOCK_STATE_HOME',
+  git: 'git',
+  lane: 'lane worktree path',
+  fallback: 'unresolved — the root'
+})
+
 function coverageSection(coverage) {
   const { trajectories: t, outcomes: o, metrics: m } = coverage
 
   const trajectoryNotes = []
+  if (t.interruptedNotesWithoutTrajectory) {
+    const n = t.interruptedNotesWithoutTrajectory
+    trajectoryNotes.push(`${n} interrupted-run note${n === 1 ? '' : 's'} name${n === 1 ? 's' : ''} no scanned trajectory`)
+  }
+  for (const u of t.interruptedNotesUnreadable || []) {
+    trajectoryNotes.push(`interrupted-run note unreadable: ${u.file} — ${u.reason}`)
+  }
   if (t.truncated) trajectoryNotes.push(`scan capped — ${t.notScanned} not read`)
   if (t.filteredOut) trajectoryNotes.push(`${t.filteredOut} outside the filter`)
   if (t.skippedLines) trajectoryNotes.push(`${t.skippedLines} torn line(s) skipped`)
@@ -215,9 +285,15 @@ function coverageSection(coverage) {
       ${proportionMark(t.scanned, t.total)}
       <dl class="facets">
         <div><dt>with run-start</dt><dd class="num">${t.withRunStart}</dd></div>
-        <div><dt>with terminal</dt><dd class="num">${t.withTerminal}</dd><dd class="aside">run-complete or run-halt</dd></div>
-        <div><dt>with receipt</dt><dd class="num">${t.withReceipt}</dd><dd class="aside">every receipt-derived indicator rests on this</dd></div>
+        <div><dt>with terminal</dt><dd class="num">${t.withTerminal}</dd><dd class="aside">run-complete or run-halt</dd></div>` +
+    (t.withoutTerminal
+      ? html`<div><dt>without terminal</dt><dd class="num">${t.withoutTerminal.total}</dd><dd class="aside">of ${t.scanned} scanned</dd></div>
+        <div><dt>interrupted</dt><dd class="num">${t.withoutTerminal.interrupted}</dd><dd class="aside">a SessionEnd note names the run</dd></div>
+        <div><dt>unexplained</dt><dd class="num">${t.withoutTerminal.unexplained}</dd><dd class="aside">no note names the run</dd></div>`
+      : '') +
+    html`<div><dt>with receipt</dt><dd class="num">${t.withReceipt}</dd><dd class="aside">every receipt-derived indicator rests on this</dd></div>
       </dl>` +
+    surfacePartition(coverage.surfaces, t.scanned) +
     (trajectoryNotes.length
       ? html`<ul class="named">${raw(trajectoryNotes.map(n => html`<li>${n}</li>`).join(''))}</ul>`
       : '') +
@@ -227,6 +303,8 @@ function coverageSection(coverage) {
         '</ul>'
       : '') +
     '</div>' +
+    // --- trajectories the home's repository holds elsewhere, counted not read
+    unreadWorktrees(coverage.unreadInLinkedWorktrees) +
     // --- outcomes
     html`<div class="corpus"><div class="corpus-head"><h3>Outcome records</h3>
       <div class="corpus-count">${o.exists ? raw(html`<span class="num">${o.records}</span> record(s)`) : raw('<span class="word">ABSENT</span>')}</div></div>` +
@@ -576,6 +654,7 @@ export function renderReportHtml(report) {
   const filterBits = []
   if (filter.since) filterBits.push(`since ${filter.since}`)
   if (filter.change) filterBits.push(`change ${filter.change}`)
+  const home = r.stateHome && typeof r.stateHome === 'object' ? r.stateHome : null
 
   const body = r.coverage
     ? coverageSection(r.coverage) + (r.indicators ? indicatorsSection(r.indicators) : '')
@@ -596,6 +675,9 @@ export function renderReportHtml(report) {
   <div><div class="kicker">Interlock · instrument readout</div><h1>Interlock Report</h1></div>
   <div class="meta">
     <span class="k">ROOT</span><span>${r.root || '.'}</span>
+    <span class="k">STATE HOME</span><span>${home && home.home ? home.home : 'unstated'}</span>
+    <span class="k">SURFACE</span><span>${home && home.surface ? home.surface : 'unstated'}</span>
+    <span class="k">HOME FROM</span><span>${home ? RESOLVED_FROM_WORDS[home.resolvedFrom] || home.resolvedFrom || 'unstated' : 'unstated'}</span>
     <span class="k">SCHEMA</span><span>${r.schema || 'unknown'}</span>
     <span class="k">SCAN CAP</span><span>${filter.maxRuns === undefined ? 'unstated' : filter.maxRuns} run(s)</span>
     <span class="k">FILTER</span><span>${filterBits.length ? filterBits.join(', ') : 'none'}</span>
@@ -613,6 +695,7 @@ export function renderReportHtml(report) {
     <div><span></span><span>Both are findings, recorded at the same standing as a measured value.</span></div>
   </div>
 </div>
+${raw(stateHomeNotice(home))}
 ${raw(body)}
 <div class="foot"><span>${r.note || 'reports only'}</span><span>Exit status is always 0.</span></div>
 </main></body></html>