@skitterbyte/skitterspec 18.0.0 → 20.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/commitcmd.js

@@ -0,0 +1,108 @@
+'use strict'
+
+/**
+ * Is this shell command a `git commit`?
+ *
+ * Asked by the review-gate hook, which is handed the command line a tool is
+ * about to run and has to decide whether the gate is even relevant. It lives
+ * here rather than inside the hook script for one reason: **a check that blocks
+ * a commit is an accusation** (`.claude/rules/negative-checks.md`), and an
+ * accusation that cannot be unit-tested will be wrong in ways nobody finds. The
+ * hook is a stdin shim over `spec-env review gate --check --for-command`; this
+ * is the part with the judgement in it.
+ *
+ * It answers TRUE only on a positive reading — a `git` invocation whose first
+ * non-option argument is `commit`. Everything it cannot parse confidently reads
+ * FALSE, because the cost of the two mistakes is not symmetric: a false
+ * negative lets one commit through a gate the skills also enforce, while a
+ * false positive blocks a command that has nothing to do with reviewing and
+ * leaves the operator with no idea why.
+ */
+
+// Shell metacharacters that end one command and begin another. `|` covers `||`
+// too, and `&` covers `&&`; over-splitting is harmless here because each
+// fragment is judged on its own.
+const SEPARATORS = /[;&|\n]+/
+
+/**
+ * Remove every quoted span. Pure.
+ *
+ * THE POINT IS WHAT THIS PREVENTS, twice over. `echo "deploy && git commit"`
+ * must not read as a commit — splitting a raw string on `&&` would manufacture
+ * a fragment out of someone's prose. And `git commit -m "fix the git log"`
+ * must still read as one: emptying the quotes leaves the real argv intact,
+ * because a verb is never inside quotes.
+ *
+ * An UNTERMINATED quote empties the rest of the line, so a half-written command
+ * reads as nothing rather than as something — the cannot-tell case going to the
+ * harmless branch, again.
+ */
+function stripQuoted(command) {
+  let out = ''
+  let quote = null
+  for (let i = 0; i < command.length; i++) {
+    const c = command[i]
+    if (quote) {
+      if (c === '\\' && quote === '"') {
+        i++
+        continue
+      }
+      if (c === quote) quote = null
+      continue
+    }
+    if (c === '"' || c === "'") {
+      quote = c
+      continue
+    }
+    out += c
+  }
+  return out
+}
+
+// git's own options, before the subcommand. Those taking a separate value have
+// to be skipped WITH their value, or `git -C /tmp commit` reads its verb as the
+// path. The `=` forms carry their value already.
+const GIT_OPTS_WITH_VALUE = new Set(['-C', '-c', '--git-dir', '--work-tree', '--namespace', '--exec-path'])
+
+/**
+ * Does this one fragment invoke `git commit`? Pure.
+ *
+ * `env`, `sudo`, `time` and the like are NOT unwrapped: a wrapper is not the
+ * common case and guessing at one is how a false positive gets built. The
+ * binary may be a path (`/usr/bin/git`), because that is ordinary.
+ */
+function fragmentCommits(fragment) {
+  const tokens = fragment.trim().split(/\s+/).filter(Boolean)
+  const at = tokens.findIndex((t) => t === 'git' || /(^|\/)git$/.test(t))
+  if (at === -1) return false
+
+  for (let i = at + 1; i < tokens.length; i++) {
+    const t = tokens[i]
+    if (GIT_OPTS_WITH_VALUE.has(t)) {
+      i++
+      continue
+    }
+    if (t.startsWith('-')) continue
+    // The first non-option token is the subcommand, whatever it is. Only one
+    // word is a commit.
+    return t === 'commit'
+  }
+  return false
+}
+
+/**
+ * Does this command line run `git commit` anywhere in it? Pure.
+ *
+ * WHAT WOULD FOOL THIS, named here so the next reader does not have to
+ * rediscover it: a commit hidden inside a quoted script (`sh -c 'git commit'`),
+ * behind an alias, or built by string interpolation reads as FALSE. All three
+ * are deliberate — they are the unknown case, and the unknown case does not
+ * accuse. The gate is still enforced by `/spec-next`, which does not depend on
+ * reading anybody's shell.
+ */
+function isGitCommit(command) {
+  if (typeof command !== 'string' || !command.trim()) return false
+  return stripQuoted(command).split(SEPARATORS).some(fragmentCommits)
+}
+
+module.exports = { isGitCommit, stripQuoted, fragmentCommits }

package/src/env/config.js

@@ -27,7 +27,6 @@
  *     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
@@ -86,7 +85,6 @@ 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
@@ -104,11 +102,43 @@ const DEFAULT_CONFIG = Object.freeze({
   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.
+  //
+  // `required` decides whether a phase that ended owes a verdict before its
+  // work can be committed or the next phase built. It defaults TRUE: the push
+  // toward reading the diff is the point, and a project that would rather not
+  // be pushed says so once. It is the only key anything reads to decide
+  // whether the gate refuses, so turning it off turns off the hook with it.
+  review: Object.freeze({
+    reader: 'detect',
+    servePort: 7777,
+    serveOnRemote: true,
+    commitWith: '/commit',
+    required: true,
+  }),
   // 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).
@@ -135,13 +165,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: [] },
   }
@@ -269,11 +299,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')
@@ -307,6 +332,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')
+    // Same shape as `serveOnRemote`, and for a sharper reason: a non-boolean
+    // leaves the gate ON. Turning off a check that refuses must be something
+    // someone WROTE, never something a typo achieved on their behalf.
+    assign(base.review, parsed.review, 'required', 'boolean')
+  }
+
   if (isObject(parsed.spec) && Array.isArray(parsed.spec.companionPaths)) {
     base.spec.companionPaths = normalizeFileList(parsed.spec.companionPaths)
   }

package/src/env/hooks.js

@@ -0,0 +1,117 @@
+'use strict'
+
+/**
+ * Register the review-gate hook in the project's Claude Code settings.
+ *
+ * `.claude/settings.json` rather than `settings.local.json`, and the difference
+ * is the point: the trusted-worktree entry is an absolute path and therefore
+ * one machine's business, while this is the project's policy — a phase that
+ * ended owes a verdict — and it should reach everyone who clones the repo. The
+ * command is written with `${CLAUDE_PROJECT_DIR}` so it stays true wherever the
+ * checkout lives, worktrees included.
+ *
+ * Conservative in the same way `trust.js` is: every existing key is preserved,
+ * a file it cannot parse is left exactly as it is, and re-running changes
+ * nothing once the entry is there. Callers own the reporting.
+ */
+
+const fs = require('node:fs')
+const path = require('node:path')
+
+const HOOK_SCRIPT = '.claude/hooks/review-gate.js'
+const HOOK_COMMAND = `node "\${CLAUDE_PROJECT_DIR}/${HOOK_SCRIPT}"`
+// Seconds. The engine call behind this is one git-free read of a small JSON
+// file, so anything approaching this is a wedge rather than slow work — and a
+// hook that times out fails OPEN, which is the answer we want for a wedge.
+const HOOK_TIMEOUT = 10
+const MATCHER = 'Bash'
+
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function settingsPath(dir) {
+  return path.join(dir, '.claude', 'settings.json')
+}
+
+function writeSettings(file, settings) {
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  fs.writeFileSync(file, JSON.stringify(settings, null, 2) + '\n')
+}
+
+function hookEntry() {
+  return {
+    matcher: MATCHER,
+    hooks: [{ type: 'command', command: HOOK_COMMAND, timeout: HOOK_TIMEOUT }],
+  }
+}
+
+/**
+ * Is our hook already registered under `PreToolUse`? Pure.
+ *
+ * Matched on the SCRIPT PATH, not on the whole command string. An operator who
+ * added a timeout, wrapped the invocation, or changed the interpreter has
+ * registered our hook their way — re-adding a second copy beside theirs would
+ * run it twice and look like a bug in the gate.
+ */
+function alreadyRegistered(preToolUse) {
+  if (!Array.isArray(preToolUse)) return false
+  return preToolUse.some(
+    (group) =>
+      isObject(group) &&
+      Array.isArray(group.hooks) &&
+      group.hooks.some((h) => isObject(h) && typeof h.command === 'string' && h.command.includes(HOOK_SCRIPT)),
+  )
+}
+
+/**
+ * Ensure the review-gate hook is registered in `dir`'s project settings.
+ * Idempotent and non-destructive. Returns `{ changed, reason }`:
+ *   - `created`   — no settings file; one was written
+ *   - `added`     — merged into an existing file
+ *   - `present`   — already registered (no write)
+ *   - `malformed` — the file exists but is not parseable JSON (left untouched)
+ */
+function ensureReviewGateHook(dir) {
+  const file = settingsPath(dir)
+
+  let raw
+  try {
+    raw = fs.readFileSync(file, 'utf-8')
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      writeSettings(file, { hooks: { PreToolUse: [hookEntry()] } })
+      return { changed: true, reason: 'created' }
+    }
+    throw error
+  }
+
+  let parsed
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    // Never rewrite a settings file we could not read. It is the operator's
+    // config and everything else in it would be lost.
+    return { changed: false, reason: 'malformed' }
+  }
+  if (!isObject(parsed)) return { changed: false, reason: 'malformed' }
+
+  const hooks = isObject(parsed.hooks) ? parsed.hooks : {}
+  const preToolUse = Array.isArray(hooks.PreToolUse) ? hooks.PreToolUse : []
+  if (alreadyRegistered(preToolUse)) return { changed: false, reason: 'present' }
+
+  writeSettings(file, {
+    ...parsed,
+    hooks: { ...hooks, PreToolUse: [...preToolUse, hookEntry()] },
+  })
+  return { changed: true, reason: 'added' }
+}
+
+module.exports = {
+  ensureReviewGateHook,
+  alreadyRegistered,
+  hookEntry,
+  settingsPath,
+  HOOK_SCRIPT,
+  HOOK_COMMAND,
+}

package/src/env/provision.js

@@ -5,15 +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')
 
 /**
@@ -114,11 +114,20 @@ function listPaths(paths) {
  * 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[]}}
+ * @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 }
+  const ok = { blocked: false, reason: null, commands: [], owned: [], verb: null, foreign: [] }
   const c = ctx || {}
 
   if (!Array.isArray(c.dirtyPaths)) {
@@ -140,15 +149,30 @@ function planSpecCommit(spec, ctx, config, { carriesChanges = false } = {}) {
 
   const { owned, foreign } = classifyDirtyTree(spec, c.dirtyPaths, config)
 
-  if (foreign.length) {
+  // 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' +
-        (carriesChanges ? ' (switching would carry them onto the new branch)' : '') +
+        'commit or stash them first (switching would carry them onto the new branch)' +
         `: ${listPaths(foreign)}`,
       commands: [],
+      owned: [],
+      verb: null,
+      foreign,
     }
   }
 
@@ -165,20 +189,34 @@ function planSpecCommit(spec, ctx, config, { carriesChanges = false } = {}) {
         ? 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 ${owned.map((p) => `"${p}"`).join(' ')}`,
-        `git commit -m "chore(spec): ${verb} ${spec.folder}"`,
+        `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,
@@ -201,7 +239,7 @@ function planSpecCommit(spec, ctx, config, { carriesChanges = false } = {}) {
  *                       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, ctx) {
@@ -228,7 +266,6 @@ function planUp(spec, alloc, config, ctx) {
     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
@@ -276,13 +313,16 @@ function planUp(spec, alloc, config, ctx) {
     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: gate.blocked ? [] : [...gate.commands, ...commands],
     seedCommands: gate.blocked ? [] : seedCommands,
     setupCommands: gate.blocked ? [] : setupCommands,
@@ -306,8 +346,7 @@ function planUp(spec, alloc, config, ctx) {
  *    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'