@skitterbyte/skitterspec 21.0.0 → 22.1.0

package/src/env/hooks.js

@@ -39,6 +39,41 @@ const HOOK_SCRIPT_RE = /[.]claude[/\\]hooks[/\\]review-gate(?:[.][A-Za-z0-9]+)?(
 const HOOK_TIMEOUT = 10
 const MATCHER = 'Bash'
 
+/**
+ * Every hook this package registers, as data.
+ *
+ * ONE LIST, so a second hook cannot arrive as a second copy of the merge logic
+ * below — which is where every property this file has earned would have to be
+ * re-derived and one of them forgotten. Each entry supplies only what differs:
+ * the script's stem, the tools it matches, and its timeout.
+ *
+ * The `re` for each is built from its stem with the same boundary lookahead the
+ * review gate's has, so `main-guard-extra.js` — somebody else's hook — is not
+ * silently rewritten as ours.
+ */
+function hookStemRe(stem) {
+  const name = stem.split('/').pop()
+  return new RegExp(`[.]claude[/\\\\]hooks[/\\\\]${name}(?:[.][A-Za-z0-9]+)?(?![\\w.-])`)
+}
+
+const HOOKS = [
+  {
+    key: 'review-gate',
+    stem: HOOK_STEM,
+    matcher: MATCHER,
+    timeout: HOOK_TIMEOUT,
+  },
+  {
+    // Refuses an Edit/Write in the primary checkout while it is on the base
+    // branch. A different matcher from the review gate's, because it guards a
+    // different moment: the first write, before any work exists.
+    key: 'main-guard',
+    stem: '.claude/hooks/main-guard',
+    matcher: 'Edit|Write|NotebookEdit|MultiEdit',
+    timeout: HOOK_TIMEOUT,
+  },
+].map((h) => ({ ...h, script: `${h.stem}.cjs`, re: hookStemRe(h.stem) }))
+
 function isObject(value) {
   return value !== null && typeof value === 'object' && !Array.isArray(value)
 }
@@ -52,10 +87,14 @@ function writeSettings(file, settings) {
   fs.writeFileSync(file, JSON.stringify(settings, null, 2) + '\n')
 }
 
-function hookEntry() {
+function commandFor(script) {
+  return `node "\${CLAUDE_PROJECT_DIR}/${script}"`
+}
+
+function hookEntry(hook = HOOKS[0]) {
   return {
-    matcher: MATCHER,
-    hooks: [{ type: 'command', command: HOOK_COMMAND, timeout: HOOK_TIMEOUT }],
+    matcher: hook.matcher,
+    hooks: [{ type: 'command', command: commandFor(hook.script), timeout: hook.timeout }],
   }
 }
 
@@ -67,34 +106,72 @@ function hookEntry() {
  * 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) {
-  return registeredHooks(preToolUse).length > 0
+function alreadyRegistered(preToolUse, hook = HOOKS[0]) {
+  return registeredHooks(preToolUse, hook).length > 0
 }
 
 // Every hook object under `PreToolUse` whose command names our script, whatever
 // extension it names it under. Pure.
-function registeredHooks(preToolUse) {
+function registeredHooks(preToolUse, hook = HOOKS[0]) {
   if (!Array.isArray(preToolUse)) return []
   const out = []
   for (const group of preToolUse) {
     if (!isObject(group) || !Array.isArray(group.hooks)) continue
     for (const h of group.hooks) {
-      if (isObject(h) && typeof h.command === 'string' && HOOK_SCRIPT_RE.test(h.command)) out.push(h)
+      if (isObject(h) && typeof h.command === 'string' && hook.re.test(h.command)) out.push(h)
     }
   }
   return out
 }
 
 /**
- * Ensure the review-gate hook is registered in `dir`'s project settings.
- * Idempotent and non-destructive. Returns `{ changed, reason }`:
+ * Ensure ONE hook is registered in an already-parsed settings object.
+ * Mutates `parsed` in place when it migrates a stale path; returns
+ * `{ changed, reason }` with the same vocabulary as the wrapper below.
+ *
+ * Split out so a second hook could be added without a second copy of this
+ * logic — which is where every property this file has earned (preserve unknown
+ * keys, match on the script PATH, migrate in place, stay idempotent) would have
+ * had to be re-derived, and one of them forgotten.
+ */
+function ensureOneHook(parsed, hook) {
+  const hooks = isObject(parsed.hooks) ? parsed.hooks : {}
+  const preToolUse = Array.isArray(hooks.PreToolUse) ? hooks.PreToolUse : []
+
+  // Registered already — but possibly under a path that no longer exists, since
+  // the script's extension changed. Rewrite the path IN PLACE rather than
+  // replacing the command: an operator who wrapped our hook, added a flag or
+  // changed the interpreter has registered it their way, and the thing that
+  // moved is the file, not their command. Adding a fresh entry beside theirs
+  // would run the gate twice and read as a bug in the gate; leaving the old one
+  // alone would aim the harness at a file this same upgrade retires.
+  const registered = registeredHooks(preToolUse, hook)
+  if (registered.length) {
+    const stale = registered.filter((h) => !h.command.includes(hook.script))
+    if (!stale.length) return { changed: false, reason: 'present' }
+    for (const h of stale) h.command = h.command.replace(hook.re, hook.script)
+    return { changed: true, reason: 'migrated' }
+  }
+
+  parsed.hooks = { ...hooks, PreToolUse: [...preToolUse, hookEntry(hook)] }
+  return { changed: true, reason: 'added' }
+}
+
+/**
+ * Ensure every hook this package ships 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
  *   - `migrated`  — registered under a retired path; the path was rewritten
  *   - `present`   — already registered (no write)
  *   - `malformed` — the file exists but is not parseable JSON (left untouched)
+ *
+ * WITH SEVERAL HOOKS THE REASON IS THE STRONGEST ONE that applied, in the order
+ * added > migrated > present. A run that added one hook and found the other
+ * already there did change the file, and reporting `present` for it would tell
+ * an operator nothing happened when something did.
  */
-function ensureReviewGateHook(dir) {
+function ensureHooks(dir) {
   const file = settingsPath(dir)
 
   let raw
@@ -102,7 +179,7 @@ function ensureReviewGateHook(dir) {
     raw = fs.readFileSync(file, 'utf-8')
   } catch (error) {
     if (error.code === 'ENOENT') {
-      writeSettings(file, { hooks: { PreToolUse: [hookEntry()] } })
+      writeSettings(file, { hooks: { PreToolUse: HOOKS.map((h) => hookEntry(h)) } })
       return { changed: true, reason: 'created' }
     }
     throw error
@@ -118,38 +195,30 @@ function ensureReviewGateHook(dir) {
   }
   if (!isObject(parsed)) return { changed: false, reason: 'malformed' }
 
-  const hooks = isObject(parsed.hooks) ? parsed.hooks : {}
-  const preToolUse = Array.isArray(hooks.PreToolUse) ? hooks.PreToolUse : []
+  const reasons = HOOKS.map((h) => ensureOneHook(parsed, h))
+  const changed = reasons.some((r) => r.changed)
+  if (changed) writeSettings(file, parsed)
 
-  // Registered already — but possibly under a path that no longer exists, since
-  // the script's extension changed. Rewrite the path IN PLACE rather than
-  // replacing the command: an operator who wrapped our hook, added a flag or
-  // changed the interpreter has registered it their way, and the thing that
-  // moved is the file, not their command. Adding a fresh entry beside theirs
-  // would run the gate twice and read as a bug in the gate; leaving the old one
-  // alone would aim the harness at a file this same upgrade retires.
-  const registered = registeredHooks(preToolUse)
-  if (registered.length) {
-    const stale = registered.filter((h) => !h.command.includes(HOOK_SCRIPT))
-    if (!stale.length) return { changed: false, reason: 'present' }
-    for (const h of stale) h.command = h.command.replace(HOOK_SCRIPT_RE, HOOK_SCRIPT)
-    writeSettings(file, parsed)
-    return { changed: true, reason: 'migrated' }
+  for (const rank of ['added', 'migrated', 'present']) {
+    if (reasons.some((r) => r.reason === rank)) return { changed, reason: rank }
   }
-
-  writeSettings(file, {
-    ...parsed,
-    hooks: { ...hooks, PreToolUse: [...preToolUse, hookEntry()] },
-  })
-  return { changed: true, reason: 'added' }
+  return { changed, reason: 'present' }
 }
 
+// The name this shipped under when there was one hook. Kept as an alias rather
+// than renamed away, because it is what an installed `init.js` from an older
+// version calls — and a rename that breaks an upgrade path is not a rename, it
+// is a removal.
+const ensureReviewGateHook = ensureHooks
+
 module.exports = {
+  ensureHooks,
   ensureReviewGateHook,
   alreadyRegistered,
   registeredHooks,
   hookEntry,
   settingsPath,
+  HOOKS,
   HOOK_STEM,
   HOOK_SCRIPT,
   HOOK_SCRIPT_RE,

package/src/env/live.js

@@ -85,6 +85,98 @@ function summarizeReceipt(receipt) {
   )
 }
 
+// --- is this spec live? ---------------------------------------------------
+
+/**
+ * Whether a spec is currently live, in a form a page can carry. Pure.
+ *
+ * FOUR STATES, NOT TWO, and the fourth is what keeps this quiet in a healthy
+ * repo. `on` and `off` are the two a reader acts on; `held` is another spec
+ * holding the workbench, which is a refusal with a named way out; and
+ * `unavailable` is **cannot tell** — routed to silence rather than to a warning
+ * (`.claude/rules/negative-checks.md` rule 4). A project with no isolation and a
+ * spec with no worktree both land there, and both are perfectly healthy.
+ *
+ * THE BRANCH IS THE AUTHORITY, NOT THE RECEIPT, exactly as this file's header
+ * says: the receipt is metadata for `live status` and crash recovery. So an
+ * unreadable or absent receipt costs the *holder's name* and nothing else — the
+ * state still comes from which branch the primary checkout is on. Deriving the
+ * state from the receipt instead would report `off` for a checkout plainly
+ * sitting on a feature branch, which is the one answer that would let something
+ * act.
+ *
+ * WHAT WOULD FOOL THIS: `onBase` and `primaryBranch` are read from the primary
+ * checkout by the caller. A caller that passes a *worktree's* git reader would
+ * describe the worktree's HEAD and call it the workbench — so `ctx` is built by
+ * `assertPrimaryOnMain` against the repo root and nowhere else.
+ *
+ * ctx: { isolated, onBase, primaryBranch, receipt, worktreeExists, url }
+ * @returns {{state:'on'|'off'|'held'|'unavailable', holder:string|null, url:string|null, reason:string|null}}
+ */
+function liveStateFor(spec, ctx) {
+  const c = ctx || {}
+  const unavailable = (reason) => ({ state: 'unavailable', holder: null, url: null, reason })
+
+  if (!spec || !spec.branch) return unavailable('no spec to ask about')
+  if (c.isolated === false) return unavailable('isolation is not configured')
+
+  // Not on base — something holds the workbench. Which something is the only
+  // question left, and the branch answers it without the receipt.
+  if (c.onBase === false) {
+    const branch = c.primaryBranch || null
+    if (branch && branch === spec.branch) {
+      return { state: 'on', holder: null, url: c.url || null, reason: null }
+    }
+    const holder = c.receipt && c.receipt.spec ? String(c.receipt.spec) : null
+    const on = branch || '(detached)'
+    return {
+      state: 'held',
+      holder,
+      url: null,
+      // Every way out, because this is the only explanation the reader gets —
+      // the same reasoning `planTake`'s guard 1 records for its own refusal.
+      reason: holder
+        ? `${holder} holds the workbench (branch ${on})`
+        : `the workbench is on ${on} — no receipt; switched by hand?`,
+    }
+  }
+
+  // `onBase` is deliberately three-valued: anything but a definite `true` here
+  // is a checkout we could not read, and that is not evidence the spec is off.
+  if (c.onBase !== true) return unavailable('could not read the primary checkout')
+  if (!c.worktreeExists) return unavailable('no worktree to put live')
+
+  return { state: 'off', holder: null, url: null, reason: null }
+}
+
+/**
+ * The one line the render prints for a live state, or null for `unavailable`.
+ * Pure.
+ *
+ * NULL IS THE POINT. `unavailable` prints nothing at all — not a dash, not an
+ * explanation — because every input that produces it is a healthy repo that
+ * simply has no live surface, and a line about one is an accusation.
+ */
+function liveStateLine(live) {
+  if (!live || live.state === 'unavailable') return null
+  const label = '  live:'.padEnd(11)
+  // IT NAMES THE COMMAND, not the capability. This line read
+  // `off — the page can put it live`, which told the reader a page somewhere
+  // could do it and left them to find the verb — and the verb is the thing they
+  // actually need when they are in a terminal rather than on the page. It is
+  // `/spec-live` rather than `spec-env live take` because that command is what a
+  // person types: it is user-only by its own marking, and the model cannot run
+  // it either way.
+  if (live.state === 'on') {
+    return (
+      `${label}on${live.url ? ` — running at ${live.url}` : ''}` +
+      '; /spec-live main to restore main'
+    )
+  }
+  if (live.state === 'held') return `${label}held — ${live.reason}`
+  return `${label}off — /spec-live to put it live`
+}
+
 // --- stateful detection (glob matching) -----------------------------------
 
 // Translate a restricted glob into an anchored RegExp: `**` matches across path
@@ -164,7 +256,27 @@ function planTake(spec, config, ctx) {
     branch,
     worktreePath: spec.worktreePath,
   }
-  const block = (reason) => ({ ...result, blocked: true, reason })
+  /**
+   * A refusal, and — only where one exists — the way out of it.
+   *
+   * AN OFFER IS DECLARED HERE OR NOWHERE. A caller that raises a picker from a
+   * refusal is reading this field, never re-deciding from the reason text: the
+   * one boundary that matters is that work which is not the operator's must
+   * never be offered up (a workbench another spec holds is theirs to free), and
+   * a rule in prose is not what should be holding that line.
+   *
+   * ABSENT STAYS ABSENT. A refusal with no way out carries no `offer` key at
+   * all, so every existing consumer sees exactly the shape it saw before.
+   *
+   * @param {string} reason   what is wrong, unchanged
+   * @param {object} [offer]  { kind: 'satisfy'|'bypass', label, command }
+   */
+  const block = (reason, offer) => ({
+    ...result,
+    blocked: true,
+    reason,
+    ...(offer ? { offer } : {}),
+  })
 
   // 1. The lock: the primary checkout must be on base (free). Off-base → a spec
   //    (or you) already holds the live instance.
@@ -201,6 +313,15 @@ function planTake(spec, config, ctx) {
     return block(
       `${spec.folder}'s worktree has uncommitted changes — commit or stash them in ` +
         `${spec.worktreePath} first (the rebase cannot run over them)`,
+      // SATISFYING THE GUARD, not stepping past it. Committing the phase is the
+      // precondition `live take` is asking for, so doing it weakens nothing and
+      // needs no record — which is what separates this from a `bypass`.
+      //
+      // Offered for the WORKTREE's tree and never for the primary checkout's
+      // (check 2 above): that one holds whatever the operator happens to have
+      // open, not this spec's phase work, and committing it under this spec's
+      // ticket is the mis-stamping `commit-trailers.md` exists to prevent.
+      { kind: 'satisfy', label: 'Commit first, then go live', command: '/commit' },
     )
   }
   // 4. A hotfix is built on an old release tag; checking its branch out under the
@@ -378,4 +499,6 @@ module.exports = {
   planTake,
   planRelease,
   planAbort,
+  liveStateFor,
+  liveStateLine,
 }

package/src/env/mainguard.js

@@ -0,0 +1,240 @@
+'use strict'
+
+/**
+ * The main guard — is this write about to land on the base branch?
+ *
+ * `main` is where work **lands**, not where it happens. Two routes reach it
+ * otherwise, and both cost someone else something: a dirty base branch that
+ * every in-flight spec has to replay over and no release can be cut through,
+ * and — worse — work that renders no review page at all, because nothing in
+ * this workflow renders one for the primary checkout.
+ *
+ * Both routes now have somewhere to go: `/spec` authors in its own `--docs`
+ * worktree, and `/no-spec` gives mechanical work a branch of its own. So the
+ * guard is a push toward a path that exists rather than a refusal with no exit.
+ *
+ * THE ACCUSATION IS POSITIVE, AND ALL FOUR PARTS MUST HOLD. It is
+ * `.claude/rules/negative-checks.md` rule 1 applied to a check that stops
+ * someone working: isolation is configured, the guard is not switched off, this
+ * directory IS the primary checkout, and HEAD IS the base branch. Anything the
+ * engine cannot establish — no repo, no config, an unresolvable base, a
+ * worktree, an unreadable allow file — allows the write and says nothing.
+ * Being wrong the permissive way costs one unguarded edit on a rule the skills
+ * also carry; being wrong the other way costs someone their work with no idea
+ * why.
+ */
+
+const fs = require('node:fs')
+const path = require('node:path')
+
+const { assertPrimaryOnMain, resolvePrimaryCheckout } = require('./resolve.js')
+
+// Where the allow lives. Gitignored, machine-local and beside the registry —
+// this is one person's decision about one session, never the project's policy.
+const ALLOW_FILE = 'main-allow.json'
+
+function allowPath(rootDir, config) {
+  return path.resolve(rootDir, path.dirname(config.registry), ALLOW_FILE)
+}
+
+/**
+ * Read the recorded allow. Pure but for the read.
+ *
+ * MISSING AND MALFORMED BOTH READ AS "NO ALLOW", which is the *strict* answer
+ * here rather than the lenient one — and that is the right way round only
+ * because the strict answer is also the safe one. An unreadable allow file
+ * makes the guard fire, and firing costs a refusal naming two exits; silently
+ * treating it as permission would let a stale file switch the guard off
+ * forever.
+ */
+function readAllow(rootDir, config) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(allowPath(rootDir, config), 'utf-8'))
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null
+    return parsed
+  } catch {
+    return null
+  }
+}
+
+function writeAllow(rootDir, config, value) {
+  const file = allowPath(rootDir, config)
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  fs.writeFileSync(file, JSON.stringify(value, null, 2) + '\n')
+}
+
+function clearAllow(rootDir, config) {
+  try {
+    fs.unlinkSync(allowPath(rootDir, config))
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Does `allow` permit a write from `sessionId`? Pure.
+ *
+ * TWO KINDS, AND THEY MUST NOT LOOK ALIKE. A **session** allow names the
+ * session that asked for it, so it lapses the moment that conversation ends —
+ * which is what "temporary" has to mean for something nobody will remember to
+ * switch back. A **repo** allow is the degraded form for a harness that exposes
+ * no session id; it outlives the session and is cleared only by hand, so
+ * `mainGuardStatus` says which kind is in force rather than reporting a bare
+ * "allowed".
+ *
+ * A session allow with no session id to compare against does NOT apply. The
+ * alternative — treating "cannot tell whose session this is" as a match — would
+ * turn every session allow into a repo one the moment a caller forgot to pass
+ * the id.
+ */
+function allowApplies(allow, sessionId) {
+  if (!allow) return false
+  if (allow.scope === 'repo') return true
+  if (allow.scope === 'session') return Boolean(sessionId) && allow.session === sessionId
+  return false
+}
+
+/**
+ * Should a write in `dir` be refused? Pure — every fact arrives in `ctx`.
+ *
+ * ctx: { configured, enabled, isPrimary, onBase, allow, sessionId }
+ *
+ * Returns `{ refuse, reason }`. `reason` is for the operator and names both
+ * exits; `refuse: false` always carries a null reason, because a guard that
+ * explains why it is NOT firing is the narration this codebase bans.
+ *
+ * WHAT WOULD FOOL THIS: nothing here inspects the *file* being written. A write
+ * to `specs/`, to `.claude/`, to a scratch file — all refused alike, and that is
+ * the decision rather than an oversight. An allowlist was considered and is
+ * empty by construction: with `/spec` authoring into its own worktree and
+ * `/no-spec` catching ad-hoc work, no legitimate writer to the base branch is
+ * left. `/spec-init` is the apparent exception and is not one — it bootstraps a
+ * repo that has no `env.config.json` yet, so `configured` is false and the
+ * guard never reaches this function.
+ */
+function judgeMainWrite(ctx) {
+  const { configured, enabled, isPrimary, onBase, allow, sessionId } = ctx || {}
+
+  // Every one of these is a CANNOT-TELL or a NOT-APPLICABLE, and each routes to
+  // the harmless branch on its own rather than through a combined condition —
+  // so a later reader can delete one without silently widening the others.
+  if (!configured) return { refuse: false, reason: null }
+  if (enabled === false) return { refuse: false, reason: null }
+  if (!isPrimary) return { refuse: false, reason: null }
+  if (!onBase) return { refuse: false, reason: null }
+  if (allowApplies(allow, sessionId)) return { refuse: false, reason: null }
+
+  return {
+    refuse: true,
+    reason:
+      'the primary checkout is on the base branch, and the base branch is a landing zone — ' +
+      'work lands there, it does not happen there.\n\n' +
+      'Move the work instead of writing here:\n' +
+      '  /no-spec <name>      a one-off with no spec — its own branch, worktree and review page\n' +
+      '  /spec-start <name>   a spec that is ready to be built\n' +
+      '  /spec                a change that wants grilling first\n\n' +
+      'If this really does belong on the base branch, the USER types /allow-main — ' +
+      'it is theirs to run, not yours.',
+  }
+}
+
+/**
+ * Gather the facts and judge. The only IO in the module's hot path.
+ *
+ * `git` is an injected reader, as everywhere in this package: the caller owns
+ * the child-process boundary, which is what keeps `judgeMainWrite` testable
+ * without one.
+ */
+function checkMainWrite(dir, config, git, opts = {}) {
+  // `present` from `loadEnvConfig` — the caller has it and this module must not
+  // re-read the file to find out. A defaults-only config is indistinguishable
+  // from a configured one that happens to match the defaults, so asking the
+  // config object would answer the wrong question.
+  const configured = opts.present === true
+  const enabled = !(config && config.guards && config.guards.mainIsLandingZone === false)
+
+  // IS THIS THE PRIMARY CHECKOUT? A worktree is somebody's spec branch and none
+  // of this guard's business, so the question is asked positively rather than by
+  // looking for the absence of a worktree marker.
+  let isPrimary = false
+  let primary = null
+  try {
+    primary = resolvePrimaryCheckout(dir, git)
+    isPrimary = Boolean(primary) && path.resolve(primary) === path.resolve(dir)
+  } catch {
+    // Not a git repo, or git unreadable. Cannot tell → allow.
+    return { refuse: false, reason: null, branch: null, baseBranch: null }
+  }
+
+  let onBase = false
+  let branch = null
+  let baseBranch = null
+  try {
+    const state = assertPrimaryOnMain(config, git)
+    onBase = state.onBase
+    branch = state.branch
+    baseBranch = state.baseBranch
+  } catch {
+    return { refuse: false, reason: null, branch: null, baseBranch: null }
+  }
+
+  const root = isPrimary ? dir : primary || dir
+  const verdict = judgeMainWrite({
+    configured,
+    enabled,
+    isPrimary,
+    onBase,
+    allow: readAllow(root, config),
+    sessionId: opts.sessionId || null,
+  })
+  return { ...verdict, branch, baseBranch }
+}
+
+/**
+ * Record an allow. `sessionId` present → a session allow; absent → a repo one.
+ * Returns what was written, so the caller can report which kind it is.
+ */
+function recordAllow(rootDir, config, { sessionId = null, reason = null, at = null } = {}) {
+  const value = sessionId
+    ? { scope: 'session', session: sessionId, reason, at }
+    : { scope: 'repo', reason, at }
+  writeAllow(rootDir, config, value)
+  return value
+}
+
+/**
+ * What is in force, as data. Four states, and the caller reports all four —
+ * `off` (the project switched the guard off), `unconfigured`, `allowed` (with
+ * its scope and reason), or `guarded`.
+ */
+function mainGuardStatus(rootDir, config, opts = {}) {
+  if (opts.present !== true) return { state: 'unconfigured' }
+  if (config && config.guards && config.guards.mainIsLandingZone === false) {
+    return { state: 'off' }
+  }
+  const allow = readAllow(rootDir, config)
+  if (allowApplies(allow, opts.sessionId || null)) {
+    return { state: 'allowed', scope: allow.scope, reason: allow.reason || null, at: allow.at || null }
+  }
+  // A session allow belonging to ANOTHER session is reported rather than hidden:
+  // the operator asked for one somewhere, and a bare "guarded" would send them
+  // hunting for why their /allow-main did nothing.
+  if (allow && allow.scope === 'session') {
+    return { state: 'guarded', otherSession: true }
+  }
+  return { state: 'guarded' }
+}
+
+module.exports = {
+  ALLOW_FILE,
+  allowPath,
+  readAllow,
+  writeAllow,
+  clearAllow,
+  allowApplies,
+  judgeMainWrite,
+  checkMainWrite,
+  recordAllow,
+  mainGuardStatus,
+}