@renzrollon/interlock 1.0.0

package/lib/merge-lanes.mjs

@@ -0,0 +1,148 @@
+// The fold decision for `interlock merge-lanes`.
+//
+// `lib/waves.mjs` makes lanes in a batch path-disjoint over PREDICTED paths —
+// but a prediction is a model's guess, and its own comment says a task that
+// writes a file it never declared is invisible to that check. Running each
+// lane in its own git worktree (workflows/ship.js `isolation:'worktree'`)
+// turns isolation between lanes from a probabilistic property of the
+// predictor into a filesystem fact; this module is the other half — folding
+// those worktrees' ACTUAL writes back into the shared tree, and answering one
+// question: did the batch's lanes really stay disjoint, or did two of them
+// write the same file despite a disjoint prediction?
+//
+// Pure: no fs, no clock, no random — consistent with `adjudicateBatches` /
+// `laneOutcomes` in workflows/ship.js. The caller (`bin/interlock`) does the
+// git plumbing: locating each lane's worktree, diffing it against the shared
+// base commit to build `changedByLane`, and applying a clean fold to the
+// shared tree. This module only decides `clean` | `collision` | `error` from
+// those already-observed facts.
+//
+// Fails closed in one direction: an uncertain fold (a label that cannot be
+// resolved, a lane with no changed-file report) is an `error`, and a real
+// path collision is a `collision` — neither ever resolves itself into a
+// `clean` fold. A silent overwrite here would be the same defect
+// `wave-isolation` exists to prevent, wearing a green check.
+
+import { canonicalizePath } from './risk.mjs'
+
+/**
+ * @typedef {{ label: string }} LaneRef
+ *   The batch's lanes, identified by their stable label (`laneLabel(lane)` in
+ *   workflows/ship.js) — this module never sees the task objects themselves.
+ */
+
+/**
+ * Decide how a completed batch's lane worktrees fold into the shared tree.
+ *
+ * @param {object} input
+ * @param {LaneRef[]} input.lanes the batch's lanes, in dispatch order
+ * @param {Record<string, string[]|null|undefined>} input.changedByLane maps a
+ *   lane label to the files that lane actually changed vs `base` (raw, as git
+ *   reported them — not yet canonicalized). `null`/`undefined`/absent means
+ *   the lane's changed-file set could not be observed (its worktree could not
+ *   be located), which is a fold-time error, not an empty write.
+ * @param {string} [input.base] the shared-tree commit every lane's diff was
+ *   taken against. Carried through for provenance; the decision itself is a
+ *   function of `changedByLane`, which already reflects that diff.
+ * @returns {{
+ *   status: 'clean'|'collision'|'error',
+ *   folds: Array<{ lane: string, files: string[] }>,
+ *   collisions: Array<{ canonicalPath: string, lanes: string[] }>,
+ *   unresolved: Array<{ label: string, reason: string }>
+ * }}
+ */
+export function mergeDecision({ lanes, changedByLane, base } = {}) {
+  void base // provenance only — the decision reads changedByLane, not base itself
+
+  const laneList = Array.isArray(lanes) ? lanes : []
+  const changed = changedByLane && typeof changedByLane === 'object' ? changedByLane : {}
+
+  const empty = { folds: [], collisions: [], unresolved: [] }
+
+  // Labels first: a lane this module cannot name is a lane it cannot fold —
+  // never a filesystem scan for a best guess. Absent, empty, non-string, and
+  // duplicate labels are all named rather than defaulted past.
+  const seen = new Map()
+  const unresolved = []
+  for (const lane of laneList) {
+    const label = lane && typeof lane.label === 'string' ? lane.label.trim() : ''
+    if (!label) {
+      unresolved.push({ label: '', reason: 'lane has no label — cannot locate its worktree' })
+      continue
+    }
+    if (seen.has(label)) {
+      unresolved.push({ label, reason: 'duplicate lane label within this batch' })
+      continue
+    }
+    seen.set(label, lane)
+  }
+  if (unresolved.length) return { status: 'error', ...empty, unresolved }
+
+  // Every named lane needs an observed changed-file set. Missing (rather than
+  // empty) means its worktree could not be located — an empty-write lane is
+  // reported as `files: []` below, never conflated with "unknown".
+  const filesByLabel = new Map()
+  for (const label of seen.keys()) {
+    const files = changed[label]
+    if (!Array.isArray(files)) {
+      unresolved.push({
+        label,
+        reason: 'no changed-file report for this lane — its worktree could not be located'
+      })
+      continue
+    }
+    filesByLabel.set(label, files.filter(f => typeof f === 'string' && f.trim()))
+  }
+  if (unresolved.length) return { status: 'error', ...empty, unresolved }
+
+  // Canonicalize each lane's actual writes for CONTENTION KEYING ONLY — the
+  // reported `files` below stay in the spelling git reported them in, the
+  // same split `canonicalizePath` / `normalizePath` draw in lib/risk.mjs.
+  // A path that fails to canonicalize (should not happen for a git-reported,
+  // repo-relative path) contends with nothing rather than being silently
+  // dropped from the report.
+  const canonicalByLabel = new Map()
+  for (const [label, files] of filesByLabel) {
+    const set = new Set()
+    for (const f of files) {
+      const c = canonicalizePath(f)
+      if (c !== null) set.add(c)
+    }
+    canonicalByLabel.set(label, set)
+  }
+
+  // Pairwise intersection across every lane, over canonical paths — never raw
+  // spellings, so `src/a.ts` and `./src/a.ts` written by two lanes are one
+  // collision, not two near-misses that both look disjoint.
+  const contenders = new Map() // canonicalPath -> Set<label>
+  const labels = [...canonicalByLabel.keys()]
+  for (let i = 0; i < labels.length; i++) {
+    for (let j = i + 1; j < labels.length; j++) {
+      const a = labels[i]
+      const b = labels[j]
+      for (const path of canonicalByLabel.get(a)) {
+        if (canonicalByLabel.get(b).has(path)) {
+          if (!contenders.has(path)) contenders.set(path, new Set())
+          contenders.get(path).add(a).add(b)
+        }
+      }
+    }
+  }
+
+  if (contenders.size) {
+    const collisions = [...contenders.entries()]
+      .map(([canonicalPath, laneSet]) => ({ canonicalPath, lanes: [...laneSet].sort() }))
+      .sort((x, y) => x.canonicalPath.localeCompare(y.canonicalPath))
+    return { status: 'collision', folds: [], collisions, unresolved: [] }
+  }
+
+  // Disjoint, by construction of the check above: apply the union. An
+  // empty-write lane contributes `files: []` and is reported, not dropped —
+  // it ran and touched nothing, which is a fact worth keeping, not a lane to
+  // silently skip.
+  const folds = laneList
+    .filter(lane => typeof lane.label === 'string' && lane.label.trim())
+    .map(lane => ({ lane: lane.label.trim(), files: filesByLabel.get(lane.label.trim()) || [] }))
+
+  return { status: 'clean', folds, collisions: [], unresolved: [] }
+}

package/lib/metrics.mjs

@@ -0,0 +1,99 @@
+// The one impure module in lib/.
+//
+// Everything else in `lib/` is a pure decision — data in, decision out, no fs,
+// no clock, no I/O — precisely so it can be tested without a fixture and called
+// from a runtime that has no filesystem of its own. This module deliberately
+// breaks that rule: it writes a file. It is isolated here so the exception is
+// visible, and so nothing pure ever grows a write path by accident.
+//
+// Two consequences of being the exception:
+//
+// 1. **It never throws.** A metrics write is a side effect of a run, never part
+//    of it. A read-only checkout, a missing `.claude/`, a full disk — each
+//    degrades to a no-op that *reports* itself via the return value. A run must
+//    never fail because bookkeeping failed.
+// 2. **It writes counts, not content.** Per decision §4.7 the payload is a
+//    timestamp, a change name and four integers. No transcripts, no finding
+//    bodies, no prompts, no file paths from the diff. The fields are copied out
+//    by name rather than spread in, so handing this function an entire review
+//    result cannot leak a finding's text into `.claude/metrics/`.
+//
+// Exposed to skills as a `interlock` subcommand.
+
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** Where metrics land, relative to the repo root. */
+export const METRICS_DIR = join('.claude', 'metrics')
+
+/** Bump when the payload shape changes, so old files stay readable. */
+export const REVIEW_METRICS_SCHEMA = 'interlock.review-metrics/1'
+
+/** The only counts that are ever written. */
+const COUNT_KEYS = ['raised', 'dismissed', 'droppedByQuality', 'surviving']
+
+// A change name reaches us from a branch, a directory or a model, so it is
+// untrusted as a path component: `../` or a slash would put the file somewhere
+// other than the metrics directory. Reduce it to a filename-safe slug.
+function slugify(change) {
+  const s = typeof change === 'string' ? change.trim() : ''
+  const safe = s.replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^[-.]+|[-.]+$/g, '')
+  return safe.slice(0, 80) || 'unnamed'
+}
+
+// ISO 8601 with the characters that are awkward in filenames replaced, so the
+// name still sorts chronologically as a string.
+function stampOf(iso) {
+  return iso.replace(/[:.]/g, '-')
+}
+
+function toCount(value) {
+  const n = Number(value)
+  if (!Number.isFinite(n) || n < 0) return 0
+  return Math.trunc(n)
+}
+
+/**
+ * Append a review's counts to `.claude/metrics/`.
+ *
+ * @param {string} root repo root; `.claude/metrics` is created beneath it
+ * @param {{change?: string, counts?: object, now?: Date|string}} [input]
+ *   `counts` is a `resolveReview` result's `counts` (extra keys are ignored);
+ *   `now` is an injection point for deterministic tests
+ * @returns {{written: boolean, path: string|null, reason: string|null}}
+ *   `reason` explains a `written: false` — it is never an exception
+ */
+export function writeReviewMetrics(root, input = {}) {
+  try {
+    if (typeof root !== 'string' || !root.trim()) {
+      return { written: false, path: null, reason: 'no root directory given' }
+    }
+    if (!existsSync(root)) {
+      return { written: false, path: null, reason: `root does not exist: ${root}` }
+    }
+
+    const when = input.now instanceof Date ? input.now : new Date(input.now || Date.now())
+    const iso = Number.isNaN(when.getTime()) ? new Date().toISOString() : when.toISOString()
+
+    const counts = {}
+    for (const k of COUNT_KEYS) counts[k] = toCount(input.counts && input.counts[k])
+
+    // Built key by key: whatever else the caller passed cannot ride along.
+    const payload = {
+      schema: REVIEW_METRICS_SCHEMA,
+      timestamp: iso,
+      change: slugify(input.change),
+      counts
+    }
+
+    const dir = join(root, METRICS_DIR)
+    mkdirSync(dir, { recursive: true })
+    const file = join(dir, `review-${payload.change}-${stampOf(iso)}.json`)
+    writeFileSync(file, JSON.stringify(payload, null, 2) + '\n')
+    return { written: true, path: file, reason: null }
+  } catch (err) {
+    // Deliberately swallowed: see the module header. The caller gets a reason,
+    // never an exception.
+    return { written: false, path: null, reason: (err && err.message) || String(err) }
+  }
+}

package/lib/notify.mjs

@@ -0,0 +1,229 @@
+// The one network call this CLI ever makes: a push to ntfy.sh (or a
+// self-hosted server) so a ship run that stops while nobody is watching can
+// still reach someone.
+//
+// Three properties are load-bearing, and every one of them exists because
+// this module is the CLI's only exception to "no network":
+//
+//   1. PURE TRANSPORT. Nothing here reads a file or the tree. Configuration
+//      is two environment variables and nothing else (design D2) — a typo in
+//      `.claude/settings.local.json` must never masquerade as a push failure,
+//      so there is no settings file this module could misread in the first
+//      place.
+//
+//   2. THE TOPIC NEVER LEAVES. The topic is the only auth ntfy.sh has on a
+//      public server; it is a capability, not a label. `readNotifyConfig`
+//      never echoes it, `sanitizeReason` strips it (and the server URL) from
+//      every failure reason before that reason reaches a summary line, a
+//      receipt event or the trajectory, because a `fetch` failure's own
+//      `cause` can carry the request host and a malformed-URL error can carry
+//      the whole URL.
+//
+//   3. BOUNDED AND NEVER THE REASON A CLOSE HANGS. `postNtfy` awaits `fetch`
+//      under an `AbortController` timing out at `LIMITS.notifyTimeoutMs`, and
+//      every failure mode — a non-2xx status, a network error, the timeout,
+//      invalid configuration — resolves to `{ sent: false, reason }` rather
+//      than throwing. Nothing here changes an exit code; the caller decides
+//      what a failed push means for the run.
+//
+// design D1, D2, D4, D5, D14 (add-harden-unattended-ship-runs).
+
+import { LIMITS } from './limits.mjs'
+
+/** Where the topic is read from. Set by the operator, never by the repo. */
+export const NOTIFY_TOPIC_ENV = 'INTERLOCK_NTFY_TOPIC'
+
+/** Where a self-hosted server is read from. Unset means the public default. */
+export const NOTIFY_URL_ENV = 'INTERLOCK_NTFY_URL'
+
+/** The public ntfy server, used when `NOTIFY_URL_ENV` is unset. */
+export const DEFAULT_NTFY_URL = 'https://ntfy.sh'
+
+function messageOf(err) {
+  return (err && err.message) || String(err)
+}
+
+/** A topic containing whitespace or a slash cannot be a single ntfy path segment. */
+function topicShapeInvalid(topic) {
+  return typeof topic !== 'string' || !topic || /\s/.test(topic) || topic.includes('/')
+}
+
+/** Does `url` parse as an absolute URL `fetch` could target? */
+function urlShapeInvalid(url) {
+  if (typeof url !== 'string' || !url) return true
+  try {
+    // eslint-disable-next-line no-new
+    new URL(url)
+    return false
+  } catch {
+    return true
+  }
+}
+
+/**
+ * Read push configuration from the environment. Never the tree — `INTERLOCK_
+ * NTFY_TOPIC` and `INTERLOCK_NTFY_URL` are the whole of it (design D2).
+ *
+ * @param {object} env  environment to read (injected in tests; `process.env` at call sites)
+ * @returns {{topic: string, url: string} | {topic: null} | {invalid: string}}
+ *   `{ topic: null }` when push is simply unconfigured — not an error, the
+ *   default and by far the common case. `{ invalid: '<VAR>' }` names the
+ *   offending variable and never its value.
+ */
+export function readNotifyConfig(env) {
+  const rawTopic = env && typeof env[NOTIFY_TOPIC_ENV] === 'string' ? env[NOTIFY_TOPIC_ENV].trim() : ''
+  if (!rawTopic) return { topic: null }
+  if (topicShapeInvalid(rawTopic)) return { invalid: NOTIFY_TOPIC_ENV }
+
+  const rawUrl =
+    env && typeof env[NOTIFY_URL_ENV] === 'string' && env[NOTIFY_URL_ENV].trim()
+      ? env[NOTIFY_URL_ENV].trim()
+      : DEFAULT_NTFY_URL
+  if (urlShapeInvalid(rawUrl)) return { invalid: NOTIFY_URL_ENV }
+
+  return { topic: rawTopic, url: rawUrl }
+}
+
+/**
+ * The message for a ship run's terminal close — the summary's own first line
+ * as the title, so the push and the printed line can never disagree, and a
+ * body that names the change and the run id or says plainly that none was
+ * ever minted (design D4).
+ *
+ * @param {object} input
+ * @param {string} input.headline  the summary's first line, verbatim
+ * @param {string} input.change    the change name
+ * @param {string|null} [input.runId]  minted at `adoptPlan`; null before one was
+ * @returns {{title: string, body: string, priority: 'high'|'default'}}
+ */
+export function composeCloseMessage({ headline, change, runId } = {}) {
+  const runLine = runId ? `run: ${runId}` : 'run: none — the run halted before a plan was adopted'
+  return {
+    title: headline,
+    body: `change: ${change}\n${runLine}`,
+    priority: typeof headline === 'string' && headline.startsWith('SHIP HALTED') ? 'high' : 'default'
+  }
+}
+
+/**
+ * The message for `/interlock:spec`'s human checkpoint (design D6) — pushed
+ * the same way a halt is, so a checkpoint reached while nobody is watching
+ * still reaches someone.
+ *
+ * @param {string} change
+ * @returns {{title: string, body: string, priority: 'default'}}
+ */
+export function composeCheckpointMessage(change) {
+  return {
+    title: `SPEC CHECKPOINT — ${change}`,
+    body: `change: ${change}`,
+    priority: 'default'
+  }
+}
+
+/**
+ * Strip anything the message could otherwise carry that identifies the
+ * server or the topic out of a failure reason, before that reason can reach
+ * a summary line, a receipt event or the trajectory. Two more precautions
+ * beyond the exact strings: the URL's bare host, because a network error's
+ * own `cause` often carries only the host and not the scheme, and a hard cap
+ * so one hostile or malformed message cannot blow up a printed report.
+ *
+ * @param {string} reason
+ * @param {{topic?: string, url?: string}} [config]
+ * @returns {string}
+ */
+export function sanitizeReason(reason, { topic, url } = {}) {
+  let text = typeof reason === 'string' ? reason : String(reason)
+  if (topic) text = text.split(topic).join('<topic>')
+  if (url) {
+    text = text.split(url).join('<url>')
+    try {
+      const host = new URL(url).host
+      if (host) text = text.split(host).join('<host>')
+    } catch {
+      // url did not parse; nothing further to strip on its account.
+    }
+  }
+  text = text.replace(/\r?\n+/g, ' ').trim()
+  return text.length > 200 ? text.slice(0, 200) : text
+}
+
+/**
+ * Encode a header value that may carry non-ASCII text.
+ *
+ * This is not defensive tidying, it is the only way the title can travel at
+ * all: EVERY headline this module sends contains an em dash (`SHIP COMPLETE —
+ * <change>`), HTTP header values are ByteStrings, and Node's `fetch` throws
+ * `Cannot convert argument to a ByteString` rather than transmitting one. So
+ * a non-ASCII value is sent as an RFC 2047 base64 encoded-word, which ntfy
+ * documents as the supported encoding for exactly this case (docs.ntfy.sh
+ * §Publish → "ntfy supports UTF-8 in HTTP headers, but not every library or
+ * programming language does", checked 2026-09-07).
+ *
+ * A pure-ASCII value is passed through untouched, so the common `interlock
+ * notify --title` case stays readable on the wire.
+ *
+ * @param {string} value
+ * @returns {string}
+ */
+export function encodeHeaderValue(value) {
+  const text = typeof value === 'string' ? value : String(value ?? '')
+  // eslint-disable-next-line no-control-regex
+  if (/^[\x20-\x7e]*$/.test(text)) return text
+  return `=?UTF-8?B?${Buffer.from(text, 'utf8').toString('base64')}?=`
+}
+
+/**
+ * Post one ntfy message. Never throws: every failure mode — invalid
+ * configuration, a non-2xx status, a network error, the timeout — resolves
+ * to `{ sent: false, reason }`, sanitized, so the caller can always print
+ * something and never has to catch anything.
+ *
+ * @param {object} input
+ * @param {string} input.url
+ * @param {string} input.topic
+ * @param {string} input.title
+ * @param {string} input.body
+ * @param {'high'|'default'} [input.priority]
+ * @param {object} [opts]
+ * @param {typeof fetch} [opts.fetchImpl]  injected for tests; no network in the suite
+ * @param {number} [opts.timeoutMs]  defaults to the published `LIMITS.notifyTimeoutMs`
+ * @returns {Promise<{sent: true} | {sent: false, reason: string}>}
+ */
+export async function postNtfy(
+  { url, topic, title, body, priority } = {},
+  { fetchImpl = globalThis.fetch, timeoutMs = LIMITS.notifyTimeoutMs } = {}
+) {
+  const invalidVar = topicShapeInvalid(topic) ? NOTIFY_TOPIC_ENV : urlShapeInvalid(url) ? NOTIFY_URL_ENV : null
+  if (invalidVar) {
+    return { sent: false, reason: sanitizeReason(`invalid configuration: ${invalidVar}`, { topic, url }) }
+  }
+
+  const target = `${url.replace(/\/+$/, '')}/${topic}`
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), timeoutMs)
+  try {
+    const response = await fetchImpl(target, {
+      method: 'POST',
+      headers: {
+        Title: encodeHeaderValue(title || ''),
+        Priority: priority || 'default'
+      },
+      body: body || '',
+      signal: controller.signal
+    })
+    if (!response || !response.ok) {
+      const status = response ? response.status : 'unknown'
+      return { sent: false, reason: sanitizeReason(`HTTP ${status}`, { topic, url }) }
+    }
+    return { sent: true }
+  } catch (err) {
+    if (err && err.name === 'AbortError') {
+      return { sent: false, reason: sanitizeReason(`timed out after ${timeoutMs}ms`, { topic, url }) }
+    }
+    return { sent: false, reason: sanitizeReason(`network error: ${messageOf(err)}`, { topic, url }) }
+  } finally {
+    clearTimeout(timer)
+  }
+}