@renzrollon/interlock 1.1.1 → 1.2.0

package/lib/state-home.mjs

@@ -0,0 +1,298 @@
+// The state home — where a run's append-only corpora live.
+//
+// A ship run writes two kinds of file. Its working state (the manifest, the
+// cursor, the briefings, the spill) belongs to the working tree the run operates
+// on. Its corpora (the trajectory, the outcome line, the metrics, the resume
+// card) belong to the project, because `interlock report` reads them across
+// every run the project has ever had.
+//
+// On a main checkout those are the same directory and nothing here matters. On
+// a linked worktree they are not: a Desktop worktree session runs in a checkout
+// that is deleted when the session is archived, so corpora written there are
+// written into a directory with an expiry date, and the report run from the main
+// checkout never sees them. This module names the main checkout instead — read
+// from git's common directory, which is the one fact every linked worktree of a
+// repository shares.
+//
+// Four properties are load-bearing:
+//
+//   1. NEVER THROWS. Every failure — a missing git, a directory that is not a
+//      repository, a hang, output it cannot read — collapses to the root itself
+//      with a reason, which is exactly today's behaviour plus a sentence. The
+//      caller banners `STATE HOME UNRESOLVED: <reason>`; a fallback without a
+//      reason would be a silent degradation, so every fallback carries one.
+//
+//   2. WRITES NOTHING. It reads two paths from git and asks one yes/no question.
+//      `git rev-parse` touches no index and no lock.
+//
+//   3. LANES ARE NOT SESSIONS. Interlock's own lane worktrees are linked
+//      worktrees too, and resolving one to the main checkout would scatter a
+//      lane's state across two trees. They are recognised by path segment, with
+//      no git call — `laneWorktreePath` in `lib/run.mjs` is the one derivation
+//      of that path, and a marker file a lane could lose would misread it as a
+//      session the moment it went missing.
+//
+//   4. REAL PATHS. macOS keeps `/tmp` and `/var` behind symlinks and git reports
+//      real paths, so the root and every path git prints are compared after
+//      `realpath`; a symlinked root and its target resolve alike.
+//
+// An explicit home (`--state-home`, else `INTERLOCK_STATE_HOME`) replaces the
+// home only after the surface is known, because the surface describes the
+// session — where the run actually is — and that stays true whoever chose the
+// home.
+//
+// Shelling out to git from `lib/` follows `lib/drift.mjs` and
+// `lib/run-paths.mjs`: `execFileSync`, stderr discarded, bounded, every failure
+// caught.
+
+import { execFileSync } from 'node:child_process'
+import { realpathSync } from 'node:fs'
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path'
+
+/** What the working root is. Recorded on the manifest, the `run-start` event and the receipt. */
+export const SURFACES = Object.freeze(['main', 'linked-worktree', 'lane-worktree', 'unknown'])
+
+/** The environment variable that pins the state home when no `--state-home` flag is given. */
+export const STATE_HOME_ENV = 'INTERLOCK_STATE_HOME'
+
+/**
+ * The directory Interlock's lane worktrees live under, as path segments.
+ *
+ * Restated from `LANE_WORKTREES_DIR` in `lib/run.mjs` rather than imported:
+ * `lib/run.mjs` imports this module, and the reverse import would be a cycle.
+ * `test/spine/state-home.test.mjs` pins the two together, so the restatement
+ * cannot drift without a red test.
+ */
+export const LANE_WORKTREE_SEGMENTS = Object.freeze(['.claude', 'ship', 'worktrees'])
+
+/** How long one git call may take before the resolver gives up on it. */
+const GIT_TIMEOUT_MS = 10_000
+
+/** The option git older than 2.31 does not know, and may echo back rather than reject. */
+const PATH_FORMAT = '--path-format=absolute'
+
+function defaultExec(file, args, { cwd } = {}) {
+  return execFileSync(file, args, {
+    cwd,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+    timeout: GIT_TIMEOUT_MS
+  })
+}
+
+function nonEmptyString(value) {
+  return typeof value === 'string' && value.trim() !== ''
+}
+
+function messageOf(err) {
+  if (err && typeof err.message === 'string' && err.message) return err.message
+  return String(err)
+}
+
+function isTimeout(err) {
+  return Boolean(err) && (err.code === 'ETIMEDOUT' || err.signal === 'SIGTERM')
+}
+
+function isMissingGit(err) {
+  return Boolean(err) && err.code === 'ENOENT'
+}
+
+/** The first line git wrote to stderr, without its `fatal: ` prefix — present only when an exec captured it. */
+function stderrLine(err) {
+  const raw = err && err.stderr
+  const text = typeof raw === 'string' ? raw : raw && typeof raw.toString === 'function' ? raw.toString() : ''
+  const line = text.split(/\r?\n/).map(l => l.trim()).find(Boolean)
+  return line ? line.replace(/^(fatal|error):\s*/i, '') : null
+}
+
+/**
+ * One sentence for a failed git call. The default exec discards stderr, so the
+ * exit status is usually all there is; 128 is git's fatal exit, and the fatal a
+ * resolver meets is almost always "not a git repository".
+ */
+function describeGitFailure(err, what, root) {
+  if (isMissingGit(err)) return `git could not be run in ${root}: not found on PATH (ENOENT)`
+  if (isTimeout(err)) return `git timed out after ${GIT_TIMEOUT_MS / 1000}s in ${root}`
+  const said = stderrLine(err)
+  const status = err && typeof err.status === 'number' ? err.status : null
+  if (said) return `${what} failed in ${root}: ${said}`
+  if (status === 128) return `${what} failed in ${root} (exit 128): not a git repository, or one git refuses to read`
+  if (status !== null) return `${what} failed in ${root} (exit ${status})`
+  if (err && err.signal) return `${what} in ${root} was stopped by ${err.signal}`
+  return `${what} failed in ${root}: ${messageOf(err)}`
+}
+
+function lines(out) {
+  return String(out ?? '')
+    .split(/\r?\n/)
+    .map(l => l.trim())
+    .filter(Boolean)
+}
+
+/** A path made real when it can be; left as given when it cannot (it may not exist, which is not an error here). */
+function realOrSelf(path, realpath) {
+  try {
+    const real = realpath(path)
+    return nonEmptyString(real) ? real : path
+  } catch {
+    return path
+  }
+}
+
+function hasLaneSegments(path) {
+  const parts = path.split(/[\\/]+/)
+  const [a, b, c] = LANE_WORKTREE_SEGMENTS
+  for (let i = 0; i + 2 < parts.length; i++) {
+    if (parts[i] === a && parts[i + 1] === b && parts[i + 2] === c) return true
+  }
+  return false
+}
+
+/** True when `path` is `root` or anywhere beneath it. */
+function isWithin(path, root) {
+  const rel = relative(root, path)
+  return rel === '' || (!isAbsolute(rel) && rel !== '..' && !rel.startsWith(`..${sep}`))
+}
+
+/**
+ * The state home a user set explicitly, or `null` when they set none.
+ *
+ * The `--state-home` flag wins over `INTERLOCK_STATE_HOME`; an empty or
+ * whitespace-only value, or a flag given without a value, is no setting at all.
+ * A relative value is made absolute against the current directory — the one the
+ * user typed it in.
+ *
+ * @param {{flag?: unknown, env?: Record<string, string|undefined>}} [opts]
+ * @returns {string|null} an absolute path, or null
+ */
+export function explicitStateHome({ flag, env = process.env } = {}) {
+  if (nonEmptyString(flag)) return resolve(process.cwd(), flag)
+  const fromEnv = env && env[STATE_HOME_ENV]
+  if (nonEmptyString(fromEnv)) return resolve(process.cwd(), fromEnv)
+  return null
+}
+
+/**
+ * Where the corpora of a run working in `root` go, and what `root` is.
+ *
+ * In order (design D13): the root is made absolute and real; a root under
+ * Interlock's lane-worktree directory is its own home with no git call; git's
+ * directory and common directory decide main checkout versus linked worktree,
+ * with the linked worktree's home accepted only when a working tree sits beside
+ * the common directory; any failure is the root itself with a reason; and an
+ * explicit home replaces the result last, keeping the surface.
+ *
+ * Never throws and never writes.
+ *
+ * @param {string} root the working root the run operates on; defaults to the current directory
+ * @param {object} [opts]
+ * @param {string|null} [opts.explicit] the `--state-home` value; when absent, `env[STATE_HOME_ENV]` is consulted
+ * @param {Record<string, string|undefined>} [opts.env] where `INTERLOCK_STATE_HOME` is read; defaults to `process.env`
+ * @param {(file: string, args: string[], opts: {cwd: string}) => string} [opts.exec] runs git and returns stdout; throws on failure
+ * @param {(path: string) => string} [opts.realpath] defaults to `fs.realpathSync`
+ * @returns {{home: string, surface: 'main'|'linked-worktree'|'lane-worktree'|'unknown', reason: string|null, resolvedFrom: 'explicit'|'git'|'lane'|'fallback'}}
+ *   `reason` is null unless the surface is `unknown`, and says why when it is —
+ *   including after an explicit home replaced the fallback, because it still
+ *   explains the surface.
+ */
+export function resolveStateHome(root, { explicit, env = process.env, exec = defaultExec, realpath = realpathSync } = {}) {
+  let abs = process.cwd()
+  let resolved
+  try {
+    abs = resolve(nonEmptyString(root) ? root : '.')
+    resolved = resolveFromRoot(abs, { exec, realpath })
+  } catch (err) {
+    // Unreachable by design — every step above catches its own failure — but
+    // the never-throws property is the contract, so it is held here as well.
+    resolved = fallback(abs, `the state home could not be resolved: ${messageOf(err)}`)
+  }
+
+  let pinned = null
+  try {
+    pinned = nonEmptyString(explicit) ? resolve(process.cwd(), explicit) : explicitStateHome({ env })
+  } catch {
+    pinned = null
+  }
+  if (pinned) return { ...resolved, home: realOrSelf(pinned, realpath), resolvedFrom: 'explicit' }
+  return resolved
+}
+
+function fallback(home, reason) {
+  return { home, surface: 'unknown', reason, resolvedFrom: 'fallback' }
+}
+
+function resolveFromRoot(abs, { exec, realpath }) {
+  // 1. Absolute, then real. A root that cannot be made real is not one git can
+  //    be asked about either; say which of the two it is.
+  let root
+  try {
+    root = realpath(abs)
+    if (!nonEmptyString(root)) root = abs
+  } catch (err) {
+    const code = err && err.code
+    if (code === 'ENOENT' || code === 'ENOTDIR') return fallback(abs, `the working root ${abs} does not exist`)
+    return fallback(abs, `the working root ${abs} could not be resolved: ${code || messageOf(err)}`)
+  }
+
+  // 2. One of Interlock's own lane worktrees: its own home, and no git call.
+  if (hasLaneSegments(root) || hasLaneSegments(abs)) {
+    return { home: root, surface: 'lane-worktree', reason: null, resolvedFrom: 'lane' }
+  }
+
+  // 3. Ask git for the two directories. A git before 2.31 does not know
+  //    `--path-format` and either rejects it (retried without) or echoes it back
+  //    as a line of output (dropped); either way the paths may then be relative,
+  //    and mean something only once resolved against the root. A missing git or
+  //    a timeout is not retried — the option cannot be why, and a retry would
+  //    double a ten-second wait for the same answer.
+  let out
+  try {
+    out = exec('git', ['rev-parse', PATH_FORMAT, '--git-dir', '--git-common-dir'], { cwd: root })
+  } catch (first) {
+    if (isMissingGit(first) || isTimeout(first)) {
+      return fallback(root, describeGitFailure(first, 'git rev-parse', root))
+    }
+    try {
+      out = exec('git', ['rev-parse', '--git-dir', '--git-common-dir'], { cwd: root })
+    } catch (retry) {
+      return fallback(root, describeGitFailure(retry, 'git rev-parse', root))
+    }
+  }
+
+  const printed = lines(out)
+  if (printed[0] === PATH_FORMAT) printed.shift()
+  if (printed.length < 2) {
+    return fallback(
+      root,
+      `git rev-parse in ${root} printed ${printed.length} line(s) where a git directory and a common directory were expected`
+    )
+  }
+  const gitDir = realOrSelf(resolve(root, printed[0]), realpath)
+  const commonDir = realOrSelf(resolve(root, printed[1]), realpath)
+
+  if (gitDir === commonDir) {
+    return { home: root, surface: 'main', reason: null, resolvedFrom: 'git' }
+  }
+
+  // A linked worktree. Its main checkout is the common directory's parent — but
+  // only when a working tree actually sits there: a bare repository's common
+  // directory has no checkout beside it, and its parent is just a directory.
+  const candidate = dirname(commonDir)
+  const bare = `the common directory ${commonDir} has no working tree beside it (a bare repository)`
+  let inside
+  try {
+    inside = lines(exec('git', ['-C', candidate, 'rev-parse', '--is-inside-work-tree'], { cwd: root }))[0]
+  } catch (err) {
+    if (isMissingGit(err) || isTimeout(err)) return fallback(root, describeGitFailure(err, 'git rev-parse', candidate))
+    return fallback(root, bare)
+  }
+  if (inside !== 'true') return fallback(root, bare)
+
+  // A main checkout inside the working root would make the root its own
+  // ancestor's home; whatever produced that answer, it is not one to write into.
+  if (isWithin(candidate, root)) {
+    return fallback(root, `the main checkout ${candidate} resolved inside the working root ${root}`)
+  }
+
+  return { home: candidate, surface: 'linked-worktree', reason: null, resolvedFrom: 'git' }
+}

package/lib/verify.mjs

@@ -449,6 +449,43 @@ export function clusterFailures(failures) {
   )
 }
 
+// --- the budget's clock ----------------------------------------------------
+
+/**
+ * How long a checkpoint's planned checks actually ran, from the timings
+ * `interlock verify exec` recorded around each command.
+ *
+ * Every exec of a planned kind is summed, not only the last: a check re-run
+ * after a repair cost that time too. Timings for a kind the plan did not name
+ * are ignored — they are not this checkpoint's checks. A planned kind with no
+ * timing at all is reported in `missing`, and the caller decides what to charge
+ * instead; this function never estimates one.
+ *
+ * @param {Array<{kind: string}>} steps  the plan's steps
+ * @param {Array<{kind: string, durationMs: number}>} timings
+ * @returns {{ms: number, missing: string[]}}
+ */
+export function foldCheckTimings(steps, timings) {
+  const planned = [
+    ...new Set(
+      (Array.isArray(steps) ? steps : [])
+        .map(s => (isObject(s) && typeof s.kind === 'string' ? s.kind : null))
+        .filter(Boolean)
+    )
+  ]
+  const usable = (Array.isArray(timings) ? timings : []).filter(
+    t => isObject(t) && typeof t.kind === 'string' && Number.isFinite(t.durationMs) && t.durationMs >= 0
+  )
+  let ms = 0
+  const missing = []
+  for (const kind of planned) {
+    const mine = usable.filter(t => t.kind === kind)
+    if (!mine.length) missing.push(kind)
+    for (const t of mine) ms += Math.round(t.durationMs)
+  }
+  return { ms, missing }
+}
+
 // --- judging --------------------------------------------------------------
 
 /**

package/lib/waves.mjs

@@ -11,9 +11,10 @@
 //      touches several files. The clamp keeps a task's recorded model at haiku
 //      or sonnet below tier 5, and opus only on a true tier-5 task, so the
 //      model cannot escalate itself. That clamped model is what a single-task
-//      lane dispatches on. A lane of two or more tasks dispatches on opus
-//      (rule 8) without rewriting any task's recorded model. Every clamp is
-//      reported.
+//      lane dispatches on. A lane of two or more tasks dispatches on opus only
+//      when its hardest tier clears `LANE_CAPS.opusMinTier` (or every task
+//      already carries opus, as in solo); otherwise it runs on sonnet. Every
+//      clamp is reported.
 //
 //   2. Fan-out cap. A wave is a set of independent tasks, so the temptation is
 //      to spawn all of them at once. The original implementation did exactly
@@ -75,8 +76,9 @@
 //      becomes one chain lane, packed next-fit under the same per-tier cap. A
 //      batch of two or more lanes is left alone, so work that was going to run
 //      concurrently still does. Fusion never crosses a wave. A chain runs in
-//      the batch order it was fused from, never re-sorted by task id, and it
-//      dispatches on opus because it holds more than one task.
+//      the batch order it was fused from, never re-sorted by task id. Its model
+//      follows `laneModel` — opus only when the hardest tier clears the
+//      published floor, otherwise sonnet.
 //
 // The second half of this file *executes* that plan — as a state machine, not a
 // runner. The orchestration is moving into a dynamic-workflow script, which can
@@ -518,18 +520,53 @@ export function laneLabel(lane) {
   return lane.length === 1 ? lane[0].id : `${lane[0].id}+${lane.length - 1}`
 }
 
+/** Separates a spawn's label from the words its title adds. */
+export const TITLE_SEPARATOR = ' · '
+
+/** The longest title a lane displays under, ellipsis included. */
+const TITLE_MAX = 48
+
 /**
- * The model a lane dispatches on, derived from the lane's shape.
+ * The name a lane is SHOWN under — its label, then the first words of its first
+ * task's description: `1.1+5 · Add the relaunch guard to…`.
  *
- * A lane of two or more tasks is the work agent the planner chose not to split,
- * so it dispatches on opus. A lane of one task dispatches on that task's clamped
- * model — haiku or sonnet, or opus for a tier-5 task or a solo promotion. Nothing
- * here rewrites `task.model`: a narrowed lane of one returns to the task's model.
+ * Display only. Everything that joins on a lane — its briefing file, worktree,
+ * trajectory line, record-batch fold — keys on `laneLabel`, because a key built
+ * from prose would change whenever a task was reworded. It is still a pure
+ * function of the lane, so a replay displays, and cache-hits, the same agent.
+ */
+export function laneTitle(lane) {
+  const label = laneLabel(lane)
+  const first = lane[0] && typeof lane[0].description === 'string' ? lane[0].description : ''
+  const words = first.replace(/[`*_]/g, '').replace(/\s+/g, ' ').trim().split(' ').slice(0, 6).join(' ')
+  const gist = words.replace(/[\s.,;:—-]+$/, '')
+  if (!gist) return label
+  const full = `${label}${TITLE_SEPARATOR}${gist}`
+  return full.length <= TITLE_MAX ? full : `${full.slice(0, TITLE_MAX - 1).trimEnd()}…`
+}
+
+/**
+ * The model a lane dispatches on, derived from the lane's shape and hardest tier.
+ *
+ * A lane of one task dispatches on that task's clamped model — haiku or sonnet,
+ * or opus for a tier-5 task or a solo promotion. A lane of two or more tasks is
+ * the work agent the planner chose not to split: it dispatches on opus when its
+ * hardest tier is at or above `LANE_CAPS.opusMinTier`, or when every task already
+ * carries opus (solo promotion of the whole change). Otherwise it runs on
+ * sonnet — routine multi-task work no longer pays the flagship model by default.
+ * Nothing here rewrites `task.model`: a narrowed lane of one returns to the
+ * task's model.
  */
 export function laneModel(lane) {
-  if (lane.length >= 2) return 'opus'
-  const only = lane[0]
-  return (only && only.model) || 'sonnet'
+  if (!Array.isArray(lane) || lane.length === 0) return 'sonnet'
+  if (lane.length === 1) {
+    const only = lane[0]
+    return (only && only.model) || 'sonnet'
+  }
+  // Solo promotions rewrite every task to opus after the clamp; an all-opus
+  // multi-task lane is that decision (or a pure tier-5 pack), not the floor.
+  if (lane.every(t => t && t.model === 'opus')) return 'opus'
+  return laneTier(lane) >= LANE_CAPS.opusMinTier ? 'opus' : 'sonnet'
 }
 
 /**
@@ -542,8 +579,8 @@ export function laneModel(lane) {
  * Returns `null` (inherit the session default — do not force) for tiers 3–4 by
  * policy and for an untiered lane (`laneTier` → 0) by fallback; the plan's
  * effort report distinguishes the two. Effort is derived from tier alone. The
- * model a lane dispatches on follows the lane's shape, so an opus lane of
- * tier-1 or tier-2 tasks still runs at `low`.
+ * model a lane dispatches on follows shape and the opus floor, so a multi-task
+ * lane of tier-1 or tier-2 tasks runs on sonnet at `low`.
  */
 export function laneEffort(lane) {
   const tier = laneTier(lane)
@@ -1412,7 +1449,7 @@ export function planWaves(input, opts = {}) {
   for (const chain of chains) {
     warnings.push(
       `tasks ${chain.ids.join(', ')} were ${chain.fusedBatches} consecutive single-lane batches in ` +
-        `${laneWhere(chain.group)}; fused into one chain lane run by one opus agent in that order ` +
+        `${laneWhere(chain.group)}; fused into one chain lane run by one ${laneModel(chain.tasks)} agent in that order ` +
         `(tier-${chain.tier} lane cap ${chain.cap})`
     )
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@renzrollon/interlock",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Autonomous spec-driven development orchestration for Claude Code, layered on OpenSpec",
   "type": "module",
   "engines": {
@@ -18,6 +18,7 @@
     "workflows",
     "skills",
     "hooks",
+    "types",
     "agents",
     "shared",
     ".claude-plugin",

package/shared/TEST-PROFILE.md

@@ -5,8 +5,9 @@ Durable, machine-readable record of how a project's tests run. Owned by
 re-sniff `package.json` on every run.
 
 **Path:** `.claude/testing/profile.json`  
-**Human mirror:** idempotent `## Testing` block in `CLAUDE.md` (or `AGENTS.md`
-on Cursor-only projects) between HTML comment markers (see below).
+**Human mirror:** idempotent `## Testing` block in the project's instruction
+file — `CLAUDE.md`, `.claude/CLAUDE.md`, or `AGENTS.md` on Cursor-only
+projects — between HTML comment markers (see below).
 
 Learned gotchas discovered mid-fix go to
 `.claude/memory/failure-modes/<slug>.md` (max 3 per session) — **not** into
@@ -153,9 +154,13 @@ reuse as-is.
 
 ## Human mirror (`## Testing` block)
 
-Write (or replace) content **between** these markers inside `CLAUDE.md`
-(prefer) or `AGENTS.md` (if that is the project's agent doc and `CLAUDE.md`
-is absent):
+Write (or replace) content **between** these markers inside the first of
+these that exists: `CLAUDE.md` at the root, then `.claude/CLAUDE.md`, then
+`AGENTS.md` (if that is the project's agent doc). Create a root `CLAUDE.md`
+only when none of the three exists. A repository that is also a Claude Code
+plugin keeps its instructions in `.claude/CLAUDE.md`, because
+`claude plugin validate --strict` rejects a `CLAUDE.md` at the plugin root; a
+mirror that recreated one there would turn that repository's CI red.
 
 ```markdown
 ## Testing

package/skills/fix-tests/SKILL.md

@@ -34,7 +34,7 @@ Resolve `typecheck.command` and `lint.command` on the same pass, the way `covera
 
 This is the only skill permitted to interview the user about tests. Every later run is zero-question.
 
-Persist the profile and mirror it into the `## Testing` block in `CLAUDE.md` (or `AGENTS.md`), between the managed markers, idempotently.
+Persist the profile and mirror it into the `## Testing` block of the first instruction file that exists — `CLAUDE.md`, then `.claude/CLAUDE.md`, then `AGENTS.md` — between the managed markers, idempotently.
 
 ---
 

package/types/index.d.ts

@@ -0,0 +1,28 @@
+// Interlock's type contract: the session state its hooks module keeps
+// (guard-ship-relaunch-in-process design D2). `.claude-plugin/plugin.json`
+// names this file as `types`; `claude plugin validate` holds every `$.state`
+// key `hooks/mod.mjs` reads or writes to the keys declared here.
+//
+// One key, the launch guard's record, in the shape `lib/launch-rule.mjs`
+// reads and the settings form's file ledger holds: times are ISO strings.
+
+/** One ship launch the runtime accepted, as its result named it. */
+export type Launch = {
+  at: string
+  runId: string | null
+  workflowName: string | null
+  scriptPath: string | null
+}
+
+/** The session's launches and the time of its last human prompt. */
+export type LaunchRecord = {
+  schema: 'interlock.launch-ledger/1'
+  launches: Launch[]
+  lastHumanPromptAt: string | null
+}
+
+declare module 'claude-code' {
+  interface PluginState {
+    interlock: { ledger: LaunchRecord }
+  }
+}