@skitterbyte/skitterspec 17.0.0 → 19.0.0

package/src/env/building.js

@@ -0,0 +1,143 @@
+'use strict'
+
+/**
+ * The primary-checkout leak guard.
+ *
+ * A phase can be built in a worktree from a session standing somewhere else —
+ * every write an absolute path, every command `cd`-prefixed. That works;
+ * `spec-env review` already reads a worktree exactly that way. What it cannot do
+ * is *prove* it worked: one relative path and the edit lands in the primary
+ * checkout, on the base branch, silently.
+ *
+ * So record what the primary checkout looked like before the build
+ * (`--record-primary`) and compare after it (`--assert-primary-clean`).
+ *
+ * The baseline is the whole point. `negative-checks.md` rule 1 asks for a
+ * positive signal rather than an absence, and "these were the dirty paths at a
+ * known moment" is one; a bare "the primary must be clean" check would accuse
+ * anyone who left an unrelated edit open in another window. Rule 4 supplies the
+ * third state: when the baseline is missing, or is for another spec, the check
+ * cannot tell — and cannot-tell reports and exits 0 rather than accusing.
+ */
+
+const path = require('node:path')
+
+// The state dir sits beside the registry file, e.g. `.spec-env` — the same
+// convention `dev.js` uses for logs and pids.
+function stateDir(config) {
+  return path.posix.dirname(config.registry) || '.spec-env'
+}
+
+/** Where the baseline lives. Gitignored with the rest of `.spec-env/`. */
+function baselinePath(dir, config) {
+  return path.join(dir, stateDir(config), 'building.json')
+}
+
+/**
+ * Merge one or more newline-separated git path listings into a sorted, deduped
+ * array. Blank lines are dropped; nothing is parsed out of the line.
+ *
+ * DELIBERATELY NOT `git status --porcelain`, for two reasons, both found by
+ * running this against a real worktree:
+ *
+ *   1. Porcelain puts the path behind two fixed status columns and a space, and
+ *      the repo's `gitReader` TRIMS its stdout — so the first line loses its
+ *      leading space and a fixed `slice(3)` eats the first character of the
+ *      first path. A guard that renames the file it is accusing you of is worse
+ *      than no guard.
+ *   2. Porcelain reports stat-dirty entries: a file whose mtime moved but whose
+ *      content is identical to HEAD. One was observed here, reported as ` M`
+ *      with an empty `git diff`. Accusing someone of leaking a file they never
+ *      changed is exactly the false accusation `negative-checks.md` exists to
+ *      prevent.
+ *
+ * `git diff --name-only HEAD` compares CONTENT, and
+ * `git ls-files --others --exclude-standard` lists genuinely new files. Between
+ * them they answer "what did this tree gain?" without a column to miscount.
+ */
+function mergePaths(...listings) {
+  const out = new Set()
+  for (const listing of listings) {
+    for (const line of String(listing || '').split('\n')) {
+      const p = line.replace(/\r$/, '').trim()
+      if (p !== '') out.add(p)
+    }
+  }
+  return [...out].sort()
+}
+
+/** Are these two paths the same tree? */
+function sameTree(a, b) {
+  return path.resolve(a) === path.resolve(b)
+}
+
+/** The record written by `--record-primary`. Pure. */
+function buildBaseline({ spec, worktreePath, primary, paths }) {
+  return { spec, worktreePath, primary, paths: [...paths].sort() }
+}
+
+/**
+ * Compare a recorded baseline against the primary checkout's current state.
+ *
+ * Three verdicts, never two (`negative-checks.md` rule 4):
+ *   - `clean`   — nothing new appeared; say nothing and exit 0.
+ *   - `leaked`  — these paths appeared since; name them and exit non-zero.
+ *   - `unknown` — the check cannot tell; say why and exit 0.
+ *
+ * Pure: every input is supplied, nothing is read from disk or git.
+ *
+ * WHAT WOULD FOOL THIS CHECK, deliberately unhandled:
+ *   - Work the build COMMITTED in the primary checkout. A commit empties the
+ *     porcelain, so a leak that was tidied away looks identical to no leak. The
+ *     guard is aimed at the actual failure mode — writes going astray mid-build,
+ *     while nothing has been committed yet — and runs before the phase commit
+ *     for that reason.
+ *   - A write to a GITIGNORED path in the primary (`.spec-env/` itself, build
+ *     output, `node_modules`). `git status` cannot see it, by design, and the
+ *     baseline file lives in exactly such a path so that recording it is not
+ *     itself a change the next comparison trips over.
+ *   - A path dirty at record time and then edited FURTHER by the build. It is in
+ *     the baseline, so it stays silent. That is the deliberate trade: silence
+ *     there costs a missed edit to a file someone was already working on, and
+ *     the opposite default accuses every healthy concurrent edit.
+ */
+function compare(baseline, currentPaths, { spec, worktreePath, primary }) {
+  if (sameTree(primary, worktreePath)) {
+    return {
+      verdict: 'unknown',
+      paths: [],
+      reason: 'the worktree IS the primary checkout — there is no second tree to leak into',
+    }
+  }
+  if (!baseline) {
+    return { verdict: 'unknown', paths: [], reason: 'no baseline recorded' }
+  }
+  if (baseline.spec !== spec) {
+    return {
+      verdict: 'unknown',
+      paths: [],
+      reason: `the baseline was recorded for ${baseline.spec}, not ${spec}`,
+    }
+  }
+  if (!sameTree(baseline.worktreePath, worktreePath)) {
+    return {
+      verdict: 'unknown',
+      paths: [],
+      reason: 'the baseline records a different worktree for this spec',
+    }
+  }
+  const before = new Set(baseline.paths || [])
+  const appeared = [...currentPaths].filter((p) => !before.has(p)).sort()
+  return appeared.length === 0
+    ? { verdict: 'clean', paths: [], reason: null }
+    : { verdict: 'leaked', paths: appeared, reason: null }
+}
+
+module.exports = {
+  stateDir,
+  baselinePath,
+  mergePaths,
+  sameTree,
+  buildBaseline,
+  compare,
+}

package/src/env/classify.js

@@ -0,0 +1,91 @@
+'use strict'
+
+/**
+ * Which uncommitted paths belong to ONE spec?
+ *
+ * `/spec-start` refuses a dirty tree because moving another spec's unfinished
+ * work is not ours to do. But the commonest dirty tree there is — the spec you
+ * just authored and are now starting — is not another spec's work at all, and
+ * refusing it costs a round trip through `/commit` on every single start.
+ *
+ * The distinction this module draws is deliberately NOT "does the dirt look
+ * important?" (a judgement, and the gate rightly refuses to make one) but
+ * membership in an exactly-known set: the spec's own folder, plus whatever the
+ * project declares in `spec.companionPaths`. Everything else is foreign, and one
+ * foreign path disqualifies the whole tree.
+ */
+
+const path = require('node:path')
+const { BUCKETS, expandTokens, readFrontmatterField } = require('./resolve.js')
+
+// git reports repo-relative, forward-slashed paths; an untracked directory comes
+// back with a trailing slash. Normalise both away so comparisons are exact.
+function normalize(p) {
+  return String(p || '')
+    .trim()
+    .replace(/\\/g, '/')
+    .replace(/\/+$/, '')
+}
+
+/**
+ * Expand a `companionPaths` pattern for this spec, or return null when it cannot
+ * be expanded.
+ *
+ * A PATTERN THAT REFERENCES `{identifier}` WHEN NO IDENTIFIER RESOLVES MATCHES
+ * NOTHING, deliberately. Two ordinary situations produce a spec with no id — a
+ * project that never set `branch.identifierField`, and a spec deliberately kept
+ * local, never pushed to a tracker — and in both the file the pattern describes
+ * either does not exist or belongs to some OTHER spec. Expanding `{identifier}`
+ * to a placeholder, or dropping the token, would widen the owned set to a path
+ * this spec has no claim on and sweep another spec's snapshot into its commit.
+ * Being wrong this way costs a refusal the operator can fix with `/commit`; the
+ * other way costs them a file they never staged.
+ */
+function expandCompanion(pattern, spec, config) {
+  const tokens = { slug: spec.slug }
+  if (/\{identifier\}/.test(pattern)) {
+    const field = config && config.branch && config.branch.identifierField
+    const identifier = readFrontmatterField(spec.path, field)
+    if (!identifier) return null
+    tokens.identifier = identifier
+  }
+  return normalize(expandTokens(pattern, tokens))
+}
+
+/**
+ * Split `dirtyPaths` into the ones that belong to `spec` and the ones that do
+ * not. Repo-relative paths in, repo-relative paths out; nothing is read from git
+ * and nothing is written.
+ *
+ * Owned:
+ *   - anything inside `specs/<bucket>/<folder>/` for ANY bucket. Every bucket is
+ *     checked rather than the spec's current one because starting a spec MOVES it
+ *     (backlog → in-progress), so a tree mid-move is dirty in two buckets at once
+ *     and both halves are the same spec's.
+ *   - each expandable `spec.companionPaths` entry.
+ *
+ * @returns {{owned: string[], foreign: string[]}}
+ */
+function classifyDirtyTree(spec, dirtyPaths, config) {
+  const owned = []
+  const foreign = []
+  if (!spec) return { owned, foreign: (dirtyPaths || []).map(normalize).filter(Boolean) }
+
+  const folders = BUCKETS.map((bucket) => `specs/${bucket}/${spec.folder}`)
+  const companions = new Set()
+  for (const pattern of (config && config.spec && config.spec.companionPaths) || []) {
+    const expanded = expandCompanion(pattern, spec, config)
+    if (expanded) companions.add(expanded)
+  }
+
+  for (const raw of dirtyPaths || []) {
+    const p = normalize(raw)
+    if (!p) continue
+    const inFolder = folders.some((f) => p === f || p.startsWith(`${f}/`))
+    if (inFolder || companions.has(p)) owned.push(p)
+    else foreign.push(p)
+  }
+  return { owned, foreign }
+}
+
+module.exports = { classifyDirtyTree, expandCompanion }

package/src/env/config.js

@@ -27,9 +27,11 @@
  *     dev:      [ { name, command, portVar, health?, frontPort? } ],  // host dev
  *               // servers started on the spec's port block (empty = none)
  *     proxy:    { enabled, host },  // bundled front-door proxy (spec-env connect)
- *     open:     { command },   // optional, editor/terminal-agnostic opener
  *     registry: ".spec-env/registry.json",
  *     branch:   { pattern, identifierField },  // git branch naming (provider-neutral)
+ *     spec:     { companionPaths: [ "path", ... ] },  // paths that belong to a
+ *               // spec alongside its own folder (provider-neutral; {slug} and
+ *               // {identifier} expand); empty = the spec folder only
  *     baseBranch: "",          // "" = auto-detect (origin/HEAD → main → master)
  *     guards:   { refuseTeardownIfDirty, refuseTeardownIfUnpushed },
  *     teardown: { deleteRemoteBranch },
@@ -83,22 +85,48 @@ const DEFAULT_CONFIG = Object.freeze({
   // Front-door proxy (`spec-env connect`): a bundled Node reverse proxy that
   // exposes one connected spec's frontPort processes on the canonical ports.
   proxy: Object.freeze({ enabled: true, host: '127.0.0.1' }),
-  open: Object.freeze({ command: '' }),
   registry: '.spec-env/registry.json',
   // Git branch naming, provider-neutral. `pattern` expands {type}/{slug} and,
   // when a tracker provider is linked, {identifier}; `identifierField` names the
   // 00-overview.md frontmatter field a provider writes the ticket id into (empty
   // = no identifier, so patterns referencing {identifier} fall back to type/slug).
   branch: Object.freeze({ pattern: '{type}/{slug}', identifierField: '' }),
+  // Paths that belong to a spec ALONGSIDE its own `specs/<bucket>/<name>/` folder
+  // — a tracker provider's per-spec snapshot, for instance. Provider-neutral by
+  // design: the base engine must not know that any particular tracker exists, so
+  // the project declares the shape and `{slug}` / `{identifier}` expand exactly as
+  // they do in `branch.pattern` ({identifier} via `branch.identifierField`).
+  // Default: none, so a spec owns only its own folder.
+  spec: Object.freeze({ companionPaths: Object.freeze([]) }),
   // Integration base branch. Empty = auto-detect (origin/HEAD → main → master).
   baseBranch: '',
   guards: Object.freeze({ refuseTeardownIfDirty: true, refuseTeardownIfUnpushed: true }),
   // Teardown cleanup beyond this machine. `deleteRemoteBranch` decides what
-  // `spec-env down` does about the branch `/spec-start` pushed: "prompt" (default)
+  // `spec-env down` does about a branch the USER published by hand — nothing
+  // publishes one at provisioning, so there is often no remote ref at all and
+  // the plan then says nothing: "prompt" (default)
   // plans the delete in its own confirm-first section for the skill to ask about,
   // "never" omits it, "always" folds it into the run-blind command list. Only ever
   // planned for a LANDED branch — see teardown.js.
   teardown: Object.freeze({ deleteRemoteBranch: 'prompt' }),
+
+  // `reader` decides how a diff's location is worded, and — via
+  // `serveOnRemote` — whether the engine stands the local server up so a remote
+  // reader gets a link that opens. It never decides to PUBLISH: publishing
+  // leaves a page this tooling cannot remove, so it stays an explicit ask.
+  // `detect` sniffs; `local`/`remote` are the operator's own answer and are
+  // believed without sniffing, because they know where they are reading and no
+  // signal can outrank that.
+  // `commitWith` names the skill a COMMITTING verdict hands off to. `/commit`
+  // ships with skittership, a different package — so it may not be installed,
+  // and skitterspec must never vendor a copy of it.
+  //
+  // There is no off switch, and that is deliberate: `"none"` existed and was
+  // removed, because it produced the one thing a review page must not have —
+  // a verdict that records itself and does nothing. A review is the guard in
+  // front of an action; recording an approval for SOMEONE ELSE to act on is a
+  // different mechanism, not a value of this key.
+  review: Object.freeze({ reader: 'detect', servePort: 7777, serveOnRemote: true, commitWith: '/commit' }),
   // Live overlay (`spec-env live`). `migrations` is a list of globs marking
   // migration files; a branch that changes any of them is treated as stateful and
   // `live take` refuses it (code-only v1). Default: none (nothing is stateful).
@@ -125,12 +153,13 @@ function defaults() {
     setup: [],
     dev: [],
     proxy: { ...DEFAULT_CONFIG.proxy },
-    open: { ...DEFAULT_CONFIG.open },
     registry: DEFAULT_CONFIG.registry,
     branch: { ...DEFAULT_CONFIG.branch },
+    spec: { companionPaths: [] },
     baseBranch: DEFAULT_CONFIG.baseBranch,
     guards: { ...DEFAULT_CONFIG.guards },
     teardown: { ...DEFAULT_CONFIG.teardown },
+    review: { ...DEFAULT_CONFIG.review },
     live: { migrations: [] },
     hotfix: { ...DEFAULT_CONFIG.hotfix, targets: [] },
   }
@@ -258,11 +287,6 @@ function mergeConfig(base, parsed) {
     assign(base.proxy, parsed.proxy, 'host', 'string')
   }
 
-  if (isObject(parsed.open)) {
-    // command may be intentionally empty (no auto-open)
-    assign(base.open, parsed.open, 'command', 'string?')
-  }
-
   if (isObject(parsed.branch)) {
     assign(base.branch, parsed.branch, 'pattern', 'string')
     assign(base.branch, parsed.branch, 'identifierField', 'string')
@@ -296,6 +320,30 @@ function mergeConfig(base, parsed) {
     }
   }
 
+  // An unrecognised reader falls through to `detect`, which is the state that
+  // claims least: it can answer "unknown", and unknown is wired to today's
+  // behaviour. A typo must never become a confident `local`, because a confident
+  // `local` is exactly the dead `file://` link this key exists to prevent.
+  if (isObject(parsed.review)) {
+    const reader = parsed.review.reader
+    if (reader === 'local' || reader === 'remote' || reader === 'detect') {
+      base.review.reader = reader
+    }
+    assign(base.review, parsed.review, 'servePort', 'number')
+    // Opting OUT is the only thing this key can do — a non-boolean leaves the
+    // default in place rather than being read as a refusal, so a typo cannot
+    // quietly restore the dead `file://` link on a remote reader.
+    assign(base.review, parsed.review, 'serveOnRemote', 'boolean')
+    // An empty string leaves `/commit` standing, like every other string key
+    // here. There is nothing it could mean instead: the hand-off has no off
+    // switch, so a blank value is a typo rather than an instruction.
+    assign(base.review, parsed.review, 'commitWith', 'string')
+  }
+
+  if (isObject(parsed.spec) && Array.isArray(parsed.spec.companionPaths)) {
+    base.spec.companionPaths = normalizeFileList(parsed.spec.companionPaths)
+  }
+
   if (isObject(parsed.live) && Array.isArray(parsed.live.migrations)) {
     base.live.migrations = normalizeFileList(parsed.live.migrations)
   }

package/src/env/provision.js

@@ -5,14 +5,15 @@
  *
  * Given a resolved spec and its allocated slot, `planUp` returns the exact
  * side-effecting commands the `/spec-env` skill runs (`git worktree add`,
- * `docker compose up`), the rendered `.env` contents, and the expanded opener —
- * but performs no side effects itself. The caller (the CLI) reads/allocates the
+ * `docker compose up`) and the rendered `.env` contents — but performs no side
+ * effects itself. The caller (the CLI) reads/allocates the
  * registry and passes the slot; this stays deterministic and unit-testable with
  * no live git/docker.
  */
 
+const { classifyDirtyTree } = require('./classify.js')
 const { portOffset } = require('./registry.js')
-const { renderEnvFile, expandOpenCommand } = require('./render.js')
+const { renderEnvFile } = require('./render.js')
 const { expandTokens } = require('./resolve.js')
 
 /**
@@ -71,6 +72,164 @@ function seedCommandFor(file, mode) {
   )
 }
 
+
+// Cap a path list in a message: enough to recognise, not a wall of text.
+function listPaths(paths) {
+  const shown = paths.slice(0, 5).join(', ')
+  return paths.length > 5 ? `${shown}, and ${paths.length - 5} more` : shown
+}
+
+/**
+ * Decide what an uncommitted tree means for a provisioning run: commit it, refuse
+ * it, or ignore it.
+ *
+ * `/spec-start` refuses a dirty tree so another spec's unfinished work is never
+ * moved without its author asking. But the commonest dirty tree of all is the
+ * spec you just wrote and are now starting, and refusing THAT costs a round trip
+ * through `/commit` on every start. So the question asked here is not "does this
+ * dirt look important?" — a judgement the gate rightly declines to make — but
+ * membership in an exactly-known set (see `classify.js`). One foreign path
+ * disqualifies the whole tree.
+ *
+ * WHAT WOULD FOOL THIS: `ctx.dirtyPaths` being absent. That is not "the tree is
+ * clean" — it is "nobody looked", which happens on every legacy caller and
+ * whenever git itself could not be read. Either way it is never permission to
+ * commit: with no classification there is no owned set, so no commit is planned.
+ *
+ * Whether it also REFUSES depends on `carriesChanges`, and the asymmetry is the
+ * two modes' actual risk, not an inconsistency:
+ *
+ *   - checkout mode (`carriesChanges`) — `git switch -c` silently carries
+ *     uncommitted work onto the new branch. Unable to see the tree means unable
+ *     to rule that out, so it refuses, exactly as it did before this gate existed.
+ *   - worktree mode — `git worktree add` carries nothing, and forks from a commit
+ *     regardless. Refusing here would fire on a healthy repo whose git we merely
+ *     could not read, which is a cost paid by someone who did nothing wrong. So
+ *     it plans no commit and provisions as before.
+ *
+ * `specOnFork` is the other half, and a POSITIVE signal rather than an absence:
+ * the worktree forks from a specific commit, so a spec absent from it produces a
+ * branch missing the very spec it is for. A clean tree cannot detect that — the
+ * spec may be committed, just somewhere else. `null` means the caller could not
+ * tell (an unreadable git, or a hotfix, which forks from a tag predating its own
+ * spec), and routes to carrying on, never to refusing.
+ *
+ * FOREIGN DIRT IS THE SAME ASYMMETRY, for the same reason. Another spec's
+ * uncommitted work refuses in checkout mode, where `git switch -c` would carry
+ * it onto the new branch, and does not in worktree mode, where nothing carries
+ * anywhere. Refusing there fired on the commonest tree this workflow produces —
+ * author spec B while spec A is still uncommitted, then start B — and prevented
+ * nothing, since the only write to the primary checkout is a pathspec-limited
+ * commit of this spec's own paths. It is reported instead, on `foreign`.
+ *
+ * ctx: { dirtyPaths?, clean?, specOnFork?, specFoundOn?, forkRef?, specUntracked? }
+ * @returns {{blocked: boolean, reason: string|null, commands: string[],
+ *            owned: string[], foreign: string[]}}
+ */
+function planSpecCommit(spec, ctx, config, { carriesChanges = false } = {}) {
+  const ok = { blocked: false, reason: null, commands: [], owned: [], verb: null, foreign: [] }
+  const c = ctx || {}
+
+  if (!Array.isArray(c.dirtyPaths)) {
+    // Nobody looked: never commit, and refuse only where switching could carry
+    // work we cannot see (see the asymmetry above).
+    if (carriesChanges && c.clean === false) {
+      return {
+        blocked: true,
+        reason:
+          'the primary checkout has uncommitted changes — commit or stash them first' +
+          (carriesChanges ? ' (switching would carry them onto the new branch)' : ''),
+        commands: [],
+        owned: [],
+        verb: null,
+      }
+    }
+    return ok
+  }
+
+  const { owned, foreign } = classifyDirtyTree(spec, c.dirtyPaths, config)
+
+  // FOREIGN DIRT REFUSES ONLY WHERE IT CAN REACH THE BRANCH, which is checkout
+  // mode and nowhere else. `git switch -c` carries the working tree onto the new
+  // branch, silently, so there it is someone else's work being moved without
+  // them asking. `git worktree add` carries nothing and forks from a commit, so
+  // in worktree mode the same tree is simply none of this run's business.
+  //
+  // WHAT WOULD MAKE THIS UNSAFE AGAIN: an unbounded commit. The only thing this
+  // run does to the primary checkout is the spec commit below, and it is safe to
+  // leave a colleague's files sitting beside it only because that commit is
+  // pathspec-limited on BOTH halves (`git add --`, `git commit … --`) and so
+  // cannot reach a path it does not own — not even one another session has
+  // already staged into the shared index. Drop the `--` and this stops being a
+  // false guard and starts being a missing one.
+  if (foreign.length && carriesChanges) {
+    return {
+      blocked: true,
+      reason:
+        `the primary checkout has uncommitted changes that are not ${spec.folder}'s — ` +
+        'commit or stash them first (switching would carry them onto the new branch)' +
+        `: ${listPaths(foreign)}`,
+      commands: [],
+      owned: [],
+      verb: null,
+      foreign,
+    }
+  }
+
+  if (owned.length) {
+    // `add` or `update`? Asked of git (`ctx.specUntracked`, from `git ls-files`)
+    // rather than inferred from the shape of the status output. The inference —
+    // "a bare directory entry means the folder is wholly untracked" — was wrong in
+    // the ordinary case of the FIRST spec in a bucket, where git reports the
+    // bucket as the untracked directory instead. The old inference stays as a
+    // fallback for callers that pass no fact; unknown yields `update`, which is
+    // never a false claim.
+    const isNew =
+      typeof c.specUntracked === 'boolean'
+        ? c.specUntracked
+        : owned.includes(`specs/${spec.bucket}/${spec.folder}`)
+    const verb = isNew ? 'add' : 'update'
+    // BOTH HALVES ARE PATHSPEC-LIMITED, and they answer different failures.
+    // `add` is what makes a path git has never seen committable at all — every
+    // brand-new spec folder is untracked. The `--` on the COMMIT is what bounds
+    // what lands: a checkout has one `.git/index` and every session standing in
+    // it shares that index, so a bare `git commit` takes whatever another
+    // session has already staged, however exactly this one named its own paths.
+    // Dropping the `--` would leave the naming above as decoration.
+    const paths = owned.map((p) => `"${p}"`).join(' ')
+    return {
+      blocked: false,
+      reason: null,
+      owned,
+      verb,
+      foreign,
+      commands: [
+        `git add -- ${paths}`,
+        `git commit -m "chore(spec): ${verb} ${spec.folder}" -- ${paths}`,
+      ],
+    }
+  }
+
+  // Tree is clean. The spec must already be in the base branch's tree, or the
+  // worktree forks without it.
+  // Nothing of this spec's is uncommitted, but somebody else's may be — say so
+  // rather than returning the bare `ok`, or the caller has no way to report what
+  // it left alone.
+  if (foreign.length && c.specOnFork !== false) return { ...ok, foreign }
+
+  if (c.specOnFork === false) {
+    return {
+      blocked: true,
+      reason:
+        `${spec.folder} is not committed in ${c.forkRef || 'the fork point'}` +
+        (c.specFoundOn ? ` — it is on ${c.specFoundOn}` : '') +
+        ' — the worktree would fork without the spec it is for',
+      commands: [],
+    }
+  }
+  return ok
+}
+
 /**
  * Plan a provisioning run.
  *
@@ -80,10 +239,10 @@ function seedCommandFor(file, mode) {
  *                       existed in the registry (re-run → attach, don't clobber).
  * @param {object} config normalised env config.
  * @returns {object} { worktreePath, branch, projectName, slot, portOffset,
- *                     envContents, openCommand, commands, seedCommands,
+ *                     envContents, commands, seedCommands,
  *                     setupCommands, attached }
  */
-function planUp(spec, alloc, config) {
+function planUp(spec, alloc, config, ctx) {
   const { slot, attached } = alloc
 
   // Per-spec escalation: bring Docker up only when this spec's Stack is `docker`,
@@ -107,7 +266,6 @@ function planUp(spec, alloc, config) {
     portOffset: offset === null ? '' : String(offset),
   }
 
-  const openCommand = expandOpenCommand(config.open.command, tokens)
 
   // File seeding runs *in the worktree* after `git worktree add`, before the
   // setup commands (which may depend on the seeded .env). Each entry becomes an
@@ -143,17 +301,31 @@ function planUp(spec, alloc, config) {
     commands.push(`docker compose --project-name ${spec.projectName} up -d`)
   }
 
+  // The tree gate. A worktree forks from the base branch's tree, so an
+  // uncommitted spec would produce a branch missing the spec it is for — this is
+  // where that gets committed, or refused. Worktree mode had NO clean gate before
+  // this: `git worktree add` does not carry uncommitted changes anywhere, so the
+  // failure surfaced three steps later as a live-overlay refusal naming the wrong
+  // stage. An absent `ctx` means no caller looked, and changes nothing.
+  const gate = planSpecCommit(spec, ctx, config)
+
   return {
+    blocked: gate.blocked,
+    reason: gate.reason,
+    specCommit: gate.owned && gate.owned.length ? { paths: gate.owned, verb: gate.verb } : null,
+    // What this run deliberately did not touch. Carried out rather than dropped
+    // because "provisioned, and left four of your files alone" is a different
+    // report from "provisioned", and the caller cannot reconstruct it.
+    untouched: gate.foreign || [],
     worktreePath: spec.worktreePath,
     branch: spec.branch,
     projectName: spec.projectName,
     slot: wantsDocker ? slot : null,
     portOffset: offset,
     envContents,
-    openCommand,
-    commands,
-    seedCommands,
-    setupCommands,
+    commands: gate.blocked ? [] : [...gate.commands, ...commands],
+    seedCommands: gate.blocked ? [] : seedCommands,
+    setupCommands: gate.blocked ? [] : setupCommands,
     attached,
   }
 }
@@ -174,8 +346,7 @@ function planUp(spec, alloc, config) {
  *    about someone else's unfinished spec. Being on THIS spec's branch is not a
  *    refusal — it is the re-run, and the answer is "already attached".
  *
- * There is no bootstrap and no opener: the primary checkout already has its
- * dependencies, and no new session is being opened.
+ * There is no bootstrap: the primary checkout already has its dependencies.
  */
 function planCheckoutUp(spec, ctx, config) {
   const base = ctx.base || (config && config.baseBranch) || 'main'
@@ -196,12 +367,10 @@ function planCheckoutUp(spec, ctx, config) {
   if (ctx.current && ctx.current === spec.branch) {
     return { ...result, attached: true }
   }
-  if (!ctx.clean) {
-    return block(
-      'the primary checkout has uncommitted changes — commit or stash them first ' +
-        '(switching would carry them onto the new branch)',
-    )
-  }
+  // Same gate as worktree mode, but `git switch -c` genuinely CARRIES uncommitted
+  // work onto the new branch, so the refusal keeps saying so.
+  const gate = planSpecCommit(spec, ctx, config, { carriesChanges: true })
+  if (gate.blocked) return block(gate.reason)
   if (!ctx.onBase) {
     return block(
       `the primary checkout is on ${ctx.current || '(detached)'}, not ${base} — ` +
@@ -209,10 +378,14 @@ function planCheckoutUp(spec, ctx, config) {
     )
   }
 
+  if (gate.owned && gate.owned.length) {
+    result.specCommit = { paths: gate.owned, verb: gate.verb }
+  }
+  result.commands.push(...gate.commands)
   result.commands.push(
     ctx.branchExists ? `git switch ${spec.branch}` : `git switch -c ${spec.branch}`,
   )
   return result
 }
 
-module.exports = { planUp, planCheckoutUp, seedCommandFor, worktreeCd }
+module.exports = { planUp, planCheckoutUp, planSpecCommit, seedCommandFor, worktreeCd }

package/src/env/proxy.js

@@ -141,7 +141,40 @@ async function waitListening(
   return false
 }
 
-module.exports = { renderRoutes, createRouteServer, startProxy, portsInUse, waitListening }
+
+/**
+ * Ask whether `port` is free on EVERY host it will need, one host at a time.
+ *
+ * SEQUENTIAL IS THE WHOLE POINT, and it is not a style choice. The probe works
+ * by binding, so two probes of the same port running concurrently contend with
+ * each other — and on Linux a wildcard bind and a loopback bind of one port are
+ * mutually exclusive, so the pair reports a completely free port as busy. The
+ * review server then refused to start on every Linux machine, which is to say
+ * on CI, while every macOS run stayed green because BSD lets the two coexist.
+ *
+ * Probing one host at a time asks the question that was always intended — is
+ * anything ELSE holding this port — instead of racing the caller against
+ * itself. Verified on node:24-alpine: parallel reports busy on a free port,
+ * sequential does not; both still refuse a real squatter on either address.
+ *
+ * `probe` is injectable so the concurrency can be asserted without sockets.
+ */
+async function portsInUseOn(port, hosts, probe = portsInUse) {
+  const busy = []
+  for (const host of [...new Set(hosts)]) {
+    busy.push(...(await probe([port], host)))
+  }
+  return [...new Set(busy)]
+}
+
+module.exports = {
+  renderRoutes,
+  createRouteServer,
+  startProxy,
+  portsInUse,
+  portsInUseOn,
+  waitListening,
+}
 
 // Entry point: run as a detached process by the CLI. Reads its routes from a
 // file so a re-`connect` just rewrites the file and restarts this (tiny) process.