@skitterbyte/skitterspec-linear 4.0.0 → 6.0.0

package/src/env/config.js

@@ -28,7 +28,12 @@
  *     registry: ".spec-env/registry.json",
  *     branch:   { pattern, identifierField },  // git branch naming (provider-neutral)
  *     baseBranch: "",          // "" = auto-detect (origin/HEAD → main → master)
- *     guards:   { refuseTeardownIfDirty, refuseTeardownIfUnpushed }
+ *     guards:   { refuseTeardownIfDirty, refuseTeardownIfUnpushed },
+ *     live:     { migrations: [ "glob", ... ] }  // migration globs → `live take`
+ *               // refuses a branch that changes them (code-only v1)
+ *     hotfix:   { bump, cherryPickMain, targets }  // `hotfix land`: patch-bump the
+ *               // deploy tag, also cherry-pick onto the base branch (main), and
+ *               // onto any extra base tags in `targets` (test/demo lines)
  *   }
  */
 
@@ -74,6 +79,16 @@ const DEFAULT_CONFIG = Object.freeze({
   // Integration base branch. Empty = auto-detect (origin/HEAD → main → master).
   baseBranch: '',
   guards: Object.freeze({ refuseTeardownIfDirty: true, refuseTeardownIfUnpushed: 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).
+  live: Object.freeze({ migrations: Object.freeze([]) }),
+  // Hotfix landing (`spec-env hotfix land`). `bump` is the version-bump strategy
+  // for the new deploy tag (only "patch" today). `cherryPickMain` also cherry-picks
+  // the fix onto the base branch for the next release (default true). `targets` is
+  // an optional default list of extra base tags to also patch (test/demo lines);
+  // `--also <tag>` on the command adds more at run time. Default: patch, main, none.
+  hotfix: Object.freeze({ bump: 'patch', cherryPickMain: true, targets: Object.freeze([]) }),
 })
 
 function isObject(value) {
@@ -94,6 +109,8 @@ function defaults() {
     branch: { ...DEFAULT_CONFIG.branch },
     baseBranch: DEFAULT_CONFIG.baseBranch,
     guards: { ...DEFAULT_CONFIG.guards },
+    live: { migrations: [] },
+    hotfix: { ...DEFAULT_CONFIG.hotfix, targets: [] },
   }
 }
 
@@ -237,6 +254,18 @@ function mergeConfig(base, parsed) {
     assign(base.guards, parsed.guards, 'refuseTeardownIfUnpushed', 'boolean')
   }
 
+  if (isObject(parsed.live) && Array.isArray(parsed.live.migrations)) {
+    base.live.migrations = normalizeFileList(parsed.live.migrations)
+  }
+
+  if (isObject(parsed.hotfix)) {
+    assign(base.hotfix, parsed.hotfix, 'bump', 'string')
+    assign(base.hotfix, parsed.hotfix, 'cherryPickMain', 'boolean')
+    if (Array.isArray(parsed.hotfix.targets)) {
+      base.hotfix.targets = normalizeFileList(parsed.hotfix.targets)
+    }
+  }
+
   return base
 }
 

package/src/env/hotfix.js

@@ -0,0 +1,133 @@
+'use strict'
+
+/**
+ * Pure landing planner for `spec-env hotfix land`.
+ *
+ * A hotfix is built on an old release tag (its `Base version`), so it can't be
+ * fast-forwarded onto `main` like an ordinary spec (that's `integrate.js`).
+ * Instead `planHotfixLand` emits the exact side-effect-free, **never-pushing**
+ * commands to:
+ *   1. tag the hotfix branch head with the patch-bumped base tag (the prod deploy
+ *      tag — the branch head already is baseRef + the fix);
+ *   2. for each extra target tag, cherry-pick the fix onto a throwaway worktree at
+ *      that tag and re-tag it with its own patch bump (test/demo release lines);
+ *   3. cherry-pick the fix onto the base branch (main) for the next release.
+ *
+ * It performs no side effects — the caller (the CLI) probes git for `dirty` /
+ * `aheadOfBase` / `existingTags` / `mainRepoPath` and supplies them, keeping this
+ * deterministic and unit-testable with no live git. Conflict handling lives in the
+ * skill (run a cherry-pick, abort on non-zero exit, hand back), mirroring
+ * `integrate.js` — the planner never reasons about conflicts.
+ */
+
+const path = require('node:path')
+
+/**
+ * Parse a semver-ish tag and return it with its PATCH bumped by one. Preserves any
+ * non-digit prefix (e.g. `v` → `v33.16.5`) and drops any pre-release/build suffix
+ * (`-rc1`, `+build`). Throws on a tag with no `MAJOR.MINOR.PATCH` core.
+ */
+function bumpPatch(tag) {
+  const m = /^(\D*)(\d+)\.(\d+)\.(\d+)(?:.*)$/.exec(String(tag || '').trim())
+  if (!m) {
+    throw new Error(
+      `hotfix: cannot bump a patch version from tag "${tag}" — need <prefix>MAJOR.MINOR.PATCH`,
+    )
+  }
+  const [, prefix, major, minor, patch] = m
+  return `${prefix}${major}.${minor}.${Number(patch) + 1}`
+}
+
+// A filesystem/branch-safe slug derived from a tag (`v30.2.1` → `v30-2-1`).
+function tagSlug(tag) {
+  return String(tag)
+    .replace(/[^a-zA-Z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+}
+
+/**
+ * @param {object} spec  resolved hotfix spec: { slug, branch, worktreePath, baseRef, ... }
+ * @param {object} config normalised env config (reads `config.hotfix`).
+ * @param {object} ctx   { worktreeState:{dirty}, aheadOfBase, fixRange, mainRepoPath,
+ *                          base, extraTargets: string[], existingTags: string[] }
+ * @returns {object} { blocked, noop, reason, commands, prodTag, targets, branch, base }
+ */
+function planHotfixLand(spec, config, ctx) {
+  const c = ctx || {}
+  const branch = spec.branch
+  const baseRef = spec.baseRef
+  const hotfixCfg = (config && config.hotfix) || { cherryPickMain: true, targets: [] }
+  const result = {
+    blocked: false,
+    noop: false,
+    reason: null,
+    commands: [],
+    prodTag: null,
+    targets: [],
+    branch,
+    base: c.base,
+  }
+  const block = (reason) => ({ ...result, blocked: true, reason })
+
+  // A hotfix must carry the tag it forked from — everything below bumps from it.
+  if (!baseRef) {
+    return block('spec has no Base version — not a hotfix, or the header is missing')
+  }
+  // The completion edits (status flip, git mv) must be committed before landing.
+  if (c.worktreeState && c.worktreeState.dirty) {
+    return block('worktree has uncommitted changes — commit the completion first')
+  }
+  // Nothing on the branch beyond the base tag → nothing to land.
+  if (!c.aheadOfBase) {
+    return { ...result, noop: true, reason: `no commits on ${branch} beyond ${baseRef} — nothing to land` }
+  }
+
+  // Track tags we'd create so we never plan a collision (with an existing tag, or
+  // between the prod tag and a target tag).
+  const taken = new Set(c.existingTags || [])
+  const fixRange = c.fixRange
+  const commands = []
+  const targets = []
+
+  // 1. Prod line: tag the hotfix branch head (already baseRef + fix). No push.
+  const prodTag = bumpPatch(baseRef)
+  if (taken.has(prodTag)) {
+    return block(`tag ${prodTag} already exists — bump the base version or delete the stale tag`)
+  }
+  taken.add(prodTag)
+  commands.push(`git -C ${spec.worktreePath} tag ${prodTag}`)
+  targets.push({ kind: 'prod', base: baseRef, tag: prodTag })
+
+  // 2. Extra targets: cherry-pick the fix onto a throwaway worktree at each tag,
+  //    re-tag with its own patch bump, then remove the worktree + temp branch (the
+  //    commits survive under the new tag, so `-D` is safe for the throwaway branch).
+  const wtRoot = path.dirname(spec.worktreePath)
+  for (const t of c.extraTargets || []) {
+    const tag = bumpPatch(t)
+    if (taken.has(tag)) {
+      return block(`tag ${tag} (for target ${t}) already exists — resolve it before landing`)
+    }
+    taken.add(tag)
+    const slug = `${spec.slug}-onto-${tagSlug(t)}`
+    const tmpBranch = `hotfix/${slug}`
+    const tmpPath = path.join(wtRoot, slug)
+    commands.push(
+      `git worktree add ${tmpPath} -b ${tmpBranch} ${t}`,
+      `git -C ${tmpPath} cherry-pick ${fixRange}`,
+      `git -C ${tmpPath} tag ${tag}`,
+      `git worktree remove ${tmpPath}`,
+      `git branch -D ${tmpBranch}`,
+    )
+    targets.push({ kind: 'extra', base: t, tag, worktreePath: tmpPath })
+  }
+
+  // 3. Cherry-pick the fix onto the base branch (main) for the next release.
+  if (hotfixCfg.cherryPickMain !== false) {
+    commands.push(`git -C ${c.mainRepoPath} cherry-pick ${fixRange}`)
+    targets.push({ kind: 'main', base: c.base })
+  }
+
+  return { ...result, commands, prodTag, targets, fixRange }
+}
+
+module.exports = { bumpPatch, tagSlug, planHotfixLand }

package/src/env/live.js

@@ -0,0 +1,357 @@
+'use strict'
+
+/**
+ * Live-overlay receipt — the advisory record of which spec currently holds the
+ * primary checkout for live testing.
+ *
+ * The *authority* on "who's live" is the branch checked out in the primary
+ * checkout (see `assertPrimaryOnMain` in resolve.js): on the base branch → free;
+ * on a feature branch → that spec is in control. This receipt is only metadata —
+ * it powers `live status` and crash recovery (`live abort` reads `baseMainCommit`
+ * from here to restore the primary checkout). It lives beside the slot registry
+ * at the primary checkout root (`.spec-env/live.json`, gitignored).
+ *
+ * `receiptPath`/`renderReceipt`/`summarizeReceipt` are pure; `read`/`write`/`clear`
+ * are the thin IO seam the CLI drives, mirroring env/registry.js. No `Date.now()`
+ * — the caller passes `heldSince`.
+ */
+
+const fs = require('node:fs')
+const path = require('node:path')
+
+const REQUIRED = ['spec', 'branch', 'holder', 'heldSince', 'baseMainCommit']
+
+// Absolute path to the receipt — a sibling of the configured registry file, so it
+// follows wherever `.spec-env` is configured (default `.spec-env/live.json`).
+function receiptPath(rootDir, config) {
+  return path.resolve(rootDir, path.dirname(config.registry), 'live.json')
+}
+
+// Normalize receipt fields into the persisted shape. Pure; throws on a missing
+// field so a half-formed receipt is never written.
+function renderReceipt(fields) {
+  for (const key of REQUIRED) {
+    if (!fields || !fields[key]) throw new Error(`live receipt: missing ${key}`)
+  }
+  const receipt = {}
+  for (const key of REQUIRED) receipt[key] = String(fields[key])
+  return receipt
+}
+
+// Read the receipt. Missing file → null (no one is live). Malformed JSON → Error.
+function readReceipt(rootDir, config) {
+  const file = receiptPath(rootDir, config)
+  let raw
+  try {
+    raw = fs.readFileSync(file, 'utf-8')
+  } catch (error) {
+    if (error.code === 'ENOENT') return null
+    throw error
+  }
+  try {
+    return JSON.parse(raw)
+  } catch (error) {
+    throw new Error(
+      `Invalid live receipt ${path.dirname(config.registry)}/live.json: ${error.message}`,
+    )
+  }
+}
+
+// Persist the receipt, creating its parent dir as needed. Returns the written shape.
+function writeReceipt(rootDir, config, fields) {
+  const receipt = renderReceipt(fields)
+  const file = receiptPath(rootDir, config)
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  fs.writeFileSync(file, JSON.stringify(receipt, null, 2) + '\n')
+  return receipt
+}
+
+// Remove the receipt. Idempotent: clearing an absent receipt is a clean no-op.
+function clearReceipt(rootDir, config) {
+  const file = receiptPath(rootDir, config)
+  try {
+    fs.unlinkSync(file)
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error
+  }
+}
+
+// A one-line human summary of a receipt (or the "free" state when null). Pure.
+function summarizeReceipt(receipt) {
+  if (!receipt) return 'free — no spec is live'
+  return (
+    `${receipt.spec} (branch ${receipt.branch}) — ` +
+    `held by ${receipt.holder} since ${receipt.heldSince}`
+  )
+}
+
+// --- stateful detection (glob matching) -----------------------------------
+
+// Translate a restricted glob into an anchored RegExp: `**` matches across path
+// separators (with an optional trailing `/`), `*` matches within a segment, `?`
+// a single non-separator char. Enough for migration-path globs, no dependency.
+function globToRegExp(glob) {
+  let re = ''
+  for (let i = 0; i < glob.length; i++) {
+    const ch = glob[i]
+    if (ch === '*') {
+      if (glob[i + 1] === '*') {
+        re += '.*'
+        i++
+        if (glob[i + 1] === '/') i++ // consume the `/` in `**/`
+      } else {
+        re += '[^/]*'
+      }
+    } else if (ch === '?') {
+      re += '[^/]'
+    } else if ('.+^${}()|[]\\/'.includes(ch)) {
+      re += '\\' + ch
+    } else {
+      re += ch
+    }
+  }
+  return new RegExp('^' + re + '$')
+}
+
+// True when any file path matches any of the migration globs. Empty patterns or
+// no files → false (nothing configured / nothing changed).
+function migrationsHit(files, patterns) {
+  if (!Array.isArray(files) || !files.length) return false
+  if (!Array.isArray(patterns) || !patterns.length) return false
+  const res = patterns.map(globToRegExp)
+  return files.some((f) => res.some((r) => r.test(f)))
+}
+
+// --- take planner ---------------------------------------------------------
+
+/**
+ * Pure planner for `spec-env live take`. Validates the preconditions for putting
+ * a spec live on the running instance by branch-switch, and returns either a
+ * structured refusal or the ordered git steps + the receipt to write. All git /
+ * port state is probed by the CLI and passed in `ctx`, keeping this deterministic
+ * and unit-testable with no live git.
+ *
+ * ctx:
+ *   primary        { onBase, branch, baseBranch } — the guard result for the primary checkout
+ *   primaryPath    absolute path of the primary checkout (the checkout target)
+ *   clean          boolean — primary checkout working tree is clean
+ *   worktreeExists boolean — the spec's worktree is on disk
+ *   base           resolved base branch name (rebase target)
+ *   baseMainCommit primary HEAD before the switch (receipt / crash recovery)
+ *   serverUp       true | false | null — null = no canonical ports declared → no gate
+ *   canonicalPorts number[] — declared canonical (frontPort) ports, for messages
+ *   migrationsHit  boolean — the branch diff touches configured migration globs
+ *   depsChanged    boolean — the branch diff touches a lockfile/manifest (→ warn)
+ *   holder,heldSince receipt provenance (injected by the CLI; no Date.now here)
+ *
+ * @returns {object} { blocked, reason, commands, warnings, receipt, base, branch, worktreePath }
+ */
+function planTake(spec, config, ctx) {
+  const c = ctx || {}
+  const branch = spec.branch
+  const base = c.base
+  const result = {
+    blocked: false,
+    reason: null,
+    commands: [],
+    warnings: [],
+    receipt: null,
+    base,
+    branch,
+    worktreePath: spec.worktreePath,
+  }
+  const block = (reason) => ({ ...result, blocked: true, reason })
+
+  // 1. The lock: the primary checkout must be on base (free). Off-base → a spec
+  //    (or you) already holds the live instance.
+  if (!c.primary || !c.primary.onBase) {
+    const on = c.primary && c.primary.branch ? c.primary.branch : '(detached)'
+    return block(
+      `primary checkout is on ${on}, not ${base} — a spec already holds the live ` +
+        'instance; release it with `/spec-live main` first',
+    )
+  }
+  // 2. Never switch a dirty tree — the checkout is reset back to base on release.
+  if (!c.clean) {
+    return block('primary checkout has uncommitted changes — commit or stash them first')
+  }
+  // 3. Need a worktree holding the branch to detach and hand over.
+  if (!c.worktreeExists) {
+    return block(`${spec.folder} has no worktree — run \`/spec-go ${spec.folder}\` first`)
+  }
+  // 4. A hotfix is built on an old release tag; checking its branch out under the
+  //    running dev server risks schema/DB drift breaking the shared instance.
+  //    Always refuse, regardless of Stack — test it in isolation via /spec-connect.
+  if (spec.type === 'hotfix') {
+    return block(
+      `${spec.folder} is a hotfix (built on an old release tag) — live overlay ` +
+        'could break the running instance; use `/spec-connect` to test it in isolation',
+    )
+  }
+  // 5. v1 is code-only: refuse a stateful spec (Stack: worktree + docker)…
+  if (spec.stack === 'docker') {
+    return block(
+      `${spec.folder} is stateful (Stack: worktree + docker) — live overlay is ` +
+        'code-only; use `/spec-connect` for a Docker-backed spec',
+    )
+  }
+  // 6. …and refuse a branch that changes migrations (would mutate the shared DB).
+  if (c.migrationsHit) {
+    return block(
+      `${spec.folder}'s branch changes migrations — live overlay is code-only; ` +
+        'use `/spec-connect`',
+    )
+  }
+  // 7. Verify-only: a dev server must be listening to hot-reload the switch.
+  if (c.serverUp === false) {
+    return block(
+      `no dev server listening on canonical port(s) ${(c.canonicalPorts || []).join(', ')} — ` +
+        'start your dev server (or `skitterspec spec-env dev up`) first',
+    )
+  }
+
+  const warnings = []
+  if (c.depsChanged) {
+    warnings.push('dependencies changed on this branch — restart your dev server after the switch')
+  }
+  if (c.serverUp === null) {
+    warnings.push('no canonical dev ports configured — nothing to hot-reload; switching anyway')
+  }
+
+  return {
+    ...result,
+    commands: [
+      `git -C ${spec.worktreePath} rebase ${base}`,
+      `git -C ${spec.worktreePath} switch --detach`,
+      `git -C ${c.primaryPath} checkout ${branch}`,
+    ],
+    warnings,
+    receipt: {
+      spec: spec.folder,
+      branch,
+      holder: c.holder,
+      heldSince: c.heldSince,
+      baseMainCommit: c.baseMainCommit,
+    },
+  }
+}
+
+// --- release planner ------------------------------------------------------
+
+/**
+ * Pure planner for `spec-env live release` — hand the running instance back to
+ * base and re-isolate the spec's branch into its worktree (the graceful exit of
+ * an unfinished session). All git state is probed by the CLI and passed in.
+ *
+ * In the branch-switch model `take` never moves the base ref, so release is just
+ * `checkout base` (frees the branch) then re-attach it to the worktree — no reset.
+ *
+ * ctx: { primary:{onBase,branch}, primaryPath, base, clean, worktreeExists }
+ * @returns {object} { blocked, noop, reason, commands, clears, base, branch, worktreePath }
+ */
+function planRelease(spec, config, ctx) {
+  const c = ctx || {}
+  const branch = spec.branch
+  const base = c.base
+  const result = {
+    blocked: false,
+    noop: false,
+    reason: null,
+    commands: [],
+    clears: false,
+    base,
+    branch,
+    worktreePath: spec.worktreePath,
+  }
+
+  // Nothing live — the primary checkout is already on base.
+  if (c.primary && c.primary.onBase) {
+    return { ...result, noop: true, reason: `nothing is live — the primary checkout is on ${base}` }
+  }
+  // A different spec holds the instance.
+  if (c.primary && c.primary.branch !== branch) {
+    return {
+      ...result,
+      blocked: true,
+      reason: `the live spec is ${c.primary.branch}, not ${branch} — release that one`,
+    }
+  }
+  // Fixes made while live must be committed to the branch first (never discarded).
+  if (!c.clean) {
+    return {
+      ...result,
+      blocked: true,
+      reason: `primary checkout has uncommitted changes — commit your fixes to ${branch} first`,
+    }
+  }
+
+  const commands = [`git -C ${c.primaryPath} checkout ${base}`]
+  if (c.worktreeExists) commands.push(`git -C ${spec.worktreePath} switch ${branch}`)
+  return { ...result, commands, clears: true }
+}
+
+// --- abort planner --------------------------------------------------------
+
+/**
+ * Pure planner for `spec-env live abort` — crash recovery. Works from the receipt
+ * (not a resolved spec), so it recovers even when the spec folder can't be found.
+ * Conservative: it refuses to discard uncommitted work, and won't force anything
+ * without a receipt to tell it what "live" was.
+ *
+ * Like release, recovery is `checkout base` + re-isolate — no `reset --hard`:
+ * branch-switch never moved base, and resetting to the receipt's recorded commit
+ * would discard any legitimate advance of base. `baseMainCommit` stays a record.
+ *
+ * ctx: { receipt, primary:{onBase,branch}, primaryPath, base, clean, worktreeExists, worktreePath }
+ * @returns {object} { blocked, noop, reason, commands, clears, base, branch }
+ */
+function planAbort(config, ctx) {
+  const c = ctx || {}
+  const base = c.base
+  const result = { blocked: false, noop: false, reason: null, commands: [], clears: false, base, branch: null }
+
+  if (!c.receipt) {
+    if (c.primary && c.primary.onBase) {
+      return { ...result, noop: true, reason: `nothing is live — the primary checkout is on ${base}` }
+    }
+    const on = c.primary && c.primary.branch ? c.primary.branch : '(detached)'
+    return {
+      ...result,
+      blocked: true,
+      reason:
+        `no live receipt, but the primary checkout is on ${on} — no recorded base ` +
+        `to restore; check out ${base} manually once you're sure it's safe`,
+    }
+  }
+
+  // Receipt present. Never discard uncommitted work — surface it instead.
+  if (!c.clean) {
+    return {
+      ...result,
+      blocked: true,
+      reason:
+        'the primary checkout has uncommitted changes that abort would discard — ' +
+        'commit or stash them (or resolve manually) first',
+    }
+  }
+
+  const branch = c.receipt.branch
+  const commands = []
+  if (!(c.primary && c.primary.onBase)) commands.push(`git -C ${c.primaryPath} checkout ${base}`)
+  if (c.worktreeExists) commands.push(`git -C ${c.worktreePath} switch ${branch}`)
+  return { ...result, commands, clears: true, branch }
+}
+
+module.exports = {
+  receiptPath,
+  renderReceipt,
+  readReceipt,
+  writeReceipt,
+  clearReceipt,
+  summarizeReceipt,
+  globToRegExp,
+  migrationsHit,
+  planTake,
+  planRelease,
+  planAbort,
+}

package/src/env/provision.js

@@ -94,10 +94,14 @@ function planUp(spec, alloc, config) {
 
   const commands = []
   // Fresh branch → -b; attach an existing branch/slot → plain form (never clobber).
+  // A hotfix forks its fresh branch from a release tag (`spec.baseRef`, e.g.
+  // `v33.16.4`) instead of base HEAD — so the fix is built on the exact commit
+  // line prod runs. Attaching an existing branch ignores baseRef (already forked).
+  const forkPoint = !attached && spec.baseRef ? ` ${spec.baseRef}` : ''
   commands.push(
     attached
       ? `git worktree add ${spec.worktreePath} ${spec.branch}`
-      : `git worktree add ${spec.worktreePath} -b ${spec.branch}`,
+      : `git worktree add ${spec.worktreePath} -b ${spec.branch}${forkPoint}`,
   )
   if (wantsDocker) {
     commands.push(`docker compose --project-name ${spec.projectName} up -d`)

package/src/env/prune.js

@@ -0,0 +1,119 @@
+'use strict'
+
+/**
+ * Pure planner for `spec-env prune` — the orphaned-test-DB reaper.
+ *
+ * Per-spec isolation gives each Docker-escalated spec its own compose stack
+ * namespaced by `{repoSlug}_{slug}`; the DB storage is a Docker named volume
+ * (`{repoSlug}_{slug}_<volname>`). Those volumes only ever get dropped by an
+ * explicit single-spec `spec-env down`, so they leak whenever that path is
+ * skipped (declined/guard-aborted teardown, manual `git worktree remove`,
+ * `--keep-volumes`). This planner reconciles the live namespace volumes against
+ * the specs that are still live and returns the `docker volume rm` commands for
+ * the orphans.
+ *
+ * **Liveness = an existing worktree, NOT the slot registry.** The registry is
+ * exactly what goes stale (a declined teardown leaves both the slot and the
+ * volume behind), so the caller derives `liveSlugs` from real worktrees and the
+ * registry is only reconciled afterwards. See the spec Decisions.
+ *
+ * We never parse a slug out of an orphan. Instead we build a protected-prefix
+ * set from the live slugs (`{repoSlug}_{slug}_`) and keep any volume matching
+ * one — everything else in the `{repoSlug}_` namespace is an orphan. The
+ * trailing `_` makes the slug match exact: slugs are kebab-case (`[a-z0-9-]`)
+ * and `_` is the compose project/volume separator, so `add` never protects
+ * `add-widget`.
+ *
+ * Side-effect free and deterministic: no `Date.now()` — the caller supplies
+ * `now` (and per-volume `createdAt`) when age-gating.
+ */
+
+const { splitPrefix } = require('./resolve.js')
+
+/**
+ * @param {Array<string|{name:string,createdAt?:number|null}>} volumes
+ *   live Docker volume names (or objects carrying `createdAt` epoch-ms for age
+ *   gating). Plain strings are treated as unknown-age.
+ * @param {Iterable<string>} liveSlugs  slugs of specs that still have a worktree.
+ * @param {object} opts { repoSlug, olderThanDays?, now? }
+ *   `repoSlug` (required) is the namespace prefix. `olderThanDays` (optional)
+ *   keeps only orphans strictly older than the cutoff; when set, `now`
+ *   (epoch-ms) is required and volumes of unknown age are conservatively kept.
+ * @returns {{ orphans: Array<{name:string,createdAt:number|null}>, commands: string[] }}
+ */
+function planPrune(volumes, liveSlugs, opts = {}) {
+  const { repoSlug, olderThanDays = null, now = null } = opts
+  if (!repoSlug) throw new Error('planPrune: opts.repoSlug is required')
+
+  const namespace = `${repoSlug}_`
+  const live = liveSlugs instanceof Set ? liveSlugs : new Set(liveSlugs || [])
+  const protectedPrefixes = [...live].map((slug) => `${repoSlug}_${slug}_`)
+
+  let orphans = (volumes || [])
+    .map((v) => (typeof v === 'string' ? { name: v, createdAt: null } : v))
+    .filter((v) => {
+      const name = v && v.name
+      if (!name || !name.startsWith(namespace)) return false
+      return !protectedPrefixes.some((p) => name.startsWith(p))
+    })
+    .map((v) => ({ name: v.name, createdAt: v.createdAt == null ? null : v.createdAt }))
+
+  if (olderThanDays != null) {
+    if (now == null) throw new Error('planPrune: olderThanDays requires opts.now')
+    const cutoff = now - olderThanDays * 24 * 60 * 60 * 1000
+    // Unknown age (createdAt == null) is kept — never drop what we can't date.
+    orphans = orphans.filter((v) => v.createdAt != null && v.createdAt <= cutoff)
+  }
+
+  const commands = orphans.map((v) => `docker volume rm ${v.name}`)
+  return { orphans, commands }
+}
+
+/**
+ * Derive the set of live spec slugs from the specs that still have a git
+ * worktree. The **worktree is the liveness signal** (see module header): the
+ * registry is not consulted here. Pure — the caller supplies the spec list and
+ * the set of live worktree paths (both gathered via IO).
+ *
+ * @param {Array<{slug:string, worktreePath:string}>} specs
+ * @param {Set<string>|Iterable<string>} liveWorktreePaths  absolute paths.
+ * @returns {Set<string>} slugs whose worktree currently exists.
+ */
+function liveSlugsForSpecs(specs, liveWorktreePaths) {
+  const live = liveWorktreePaths instanceof Set ? liveWorktreePaths : new Set(liveWorktreePaths || [])
+  const slugs = new Set()
+  for (const spec of specs || []) {
+    if (spec && spec.worktreePath && live.has(spec.worktreePath)) slugs.add(spec.slug)
+  }
+  return slugs
+}
+
+/**
+ * Reconcile the slot registry against the volumes we're about to reap. A stale
+ * slot is one whose spec's DB volume is an orphan — freeing it converges the
+ * registry back to what actually exists (the registry is keyed by spec *folder*,
+ * so we split each folder's prefix to get its slug and match it to a reaped
+ * volume by the same `{repoSlug}_{slug}_` prefix used for orphan detection).
+ * Pure: returns a new registry object plus the folders freed; never mutates.
+ *
+ * @param {{slots: Object<string,number>}} registry
+ * @param {Array<{name:string}>} orphans  the volumes planPrune decided to reap.
+ * @param {string} repoSlug
+ * @returns {{ registry: {slots: Object<string,number>}, freed: string[] }}
+ */
+function reconcileRegistry(registry, orphans, repoSlug) {
+  const slots = { ...((registry && registry.slots) || {}) }
+  const reaped = (orphans || []).map((o) => o.name)
+  const freed = []
+  for (const folder of Object.keys(slots)) {
+    const { slug } = splitPrefix(folder)
+    const prefix = `${repoSlug}_${slug}_`
+    if (reaped.some((name) => name.startsWith(prefix))) {
+      delete slots[folder]
+      freed.push(folder)
+    }
+  }
+  return { registry: { slots }, freed }
+}
+
+module.exports = { planPrune, liveSlugsForSpecs, reconcileRegistry }