@descent-vtt/spec-harness 0.18.0 → 0.20.0

package/dist/cli.js

@@ -18,14 +18,15 @@
  * line and exit 2, as every error does.
  */
 import { SiblingOutputError } from './briefs.js';
-import { ConfigError, SIBLINGS } from './config.js';
-import { isDirectory } from './fs.js';
-import { GitError, show, stagedChanges } from './git.js';
-import { claudeResponse, gitResponse, parseClaudeHook } from './hooks.js';
-import { SiblingError } from './siblings.js';
-import { emptyValue, heldHookLine, isBlank, isClaudeHook, readHookLine, refusal, unreadHookLine } from './usage.js';
+import { CONFIG_FILE, ConfigError, SIBLINGS, SPEC_BRIEF_CONFIGS } from './config.js';
+import { dirname, join, resolve } from 'node:path';
+import { gitDirectories, isDirectory, keepCall, loadConfig, mainWorkTree, outsideEvery, StateError, takeCall, writesOnly } from './fs.js';
+import { changedPaths, GitError, show, stagedChanges } from './git.js';
+import { afterResponse, callFile, callRecord, claudeResponse, gitResponse, keptCall, mendResponse, NONE, parseClaudeHook, SESSION_START, sessionOf, sessionResponse, TURN_END, turnResponse, warningResponse, warningsKept, warningsOf } from './hooks.js';
+import { declaredVersion, SiblingError } from './siblings.js';
+import { answerBeside, emptyValue, heldHookLine, isBlank, isClaudeHook, readHookLine, refusal, twoValues, unreadHookLine } from './usage.js';
 import { CLAUDE_CODE_MINIMUM, MINIMUM_VERSIONS } from './versions.js';
-import { activeBrief, answerOf, describeActive, EXIT_ERROR, EXIT_FAILED, EXIT_OK, json, openWorkspace, parseOptions, UsageError, version, } from './workspace.js';
+import { activeBrief, answerOf, describeActive, EXIT_ERROR, EXIT_FAILED, EXIT_OK, json, MAIN_INSTALL, mayBeElsewhere, openFound, openWorkspace, otherTree, parseOptions, UsageError, version, writesBy, } from './workspace.js';
 export { EXIT_ERROR, EXIT_FAILED, EXIT_OK, UsageError, version } from './workspace.js';
 export const HELP = `spec-harness - context, guards, audits and rulings for rounds of agent work
 
@@ -36,7 +37,10 @@ Commands:
   context [brief]     What an agent needs to start a round: the brief, its scope,
                       rulings, dependencies, the rules in force, the cited documents.
   guard <path...>     May the round write these paths? Exit 1 if one is refused.
-  hook claude         Answer a Claude Code PreToolUse or PostToolUse hook (stdin).
+  hook claude         Answer a Claude Code PreToolUse, PostToolUse, SessionStart or Stop
+                      hook (stdin). At session start it says what would hold every
+                      write; at a turn's end, with "turnReport" on, what the work tree
+                      holds that the brief protects or that is outside its scope.
   hook git            Answer git's pre-commit hook for the staged files.
   escalate            Ask a person to rule: --path <file> (repeatable) --reason <why>
                       [--option "<label>: <cost>"]... [--recommend <text>].
@@ -53,17 +57,21 @@ Commands:
   premises            Do the live briefs' premises still hold? For CI: exit 1 when one
                       is stale, or, with --strict, when spec-guard cannot read one.
   init                Configure the spec-* tools to agree. Prints the plan; --write
-                      applies it; --git-hook adds a pre-commit hook.
+                      applies it; --git-hook adds a pre-commit hook; --block-on-failure
+                      has Claude Code 2.1.295 or later hold a write when the hook cannot
+                      start or runs past its timeout.
   mcp                 Serve start_round, check_path, request_escalation, audit_round,
                       list_rounds and the workflow prompts over MCP on stdio.
   doctor              Which siblings are installed, at which versions, which brief is
                       named, how Claude Code runs the guard, and git's hook. Exit 1
                       when a sibling is older than this release needs, the guard is
                       installed twice, its hook's line turns it off or holds every
-                      write, disableAllHooks or an array for a matcher switches it
-                      off, the plugin that is turned on is not on this machine and
-                      nothing else guards, Claude Code is too old to run its hooks,
-                      or git stops every commit at what stands for its hook.
+                      write, the branch names a brief spec-brief does not list or
+                      has archived, disableAllHooks or an array for a matcher
+                      switches it off, the plugin that is turned on is not on this
+                      machine and nothing else guards, Claude Code is too old to
+                      run its hooks, or git stops every commit at what stands for
+                      its hook.
 
 Options:
   --brief <id>        The brief the round works on. Otherwise SPEC_BRIEF, then the branch.
@@ -76,14 +84,19 @@ Options:
   --format <fmt>      pretty or json; audit and premises also gitlab, sarif or github.
                       For every command but hook and mcp.
   --strict            Warnings fail the run. For guard, audit, premises and doctor.
-  --help, --version
+  --block-on-failure  onFailure "block" on init's entries but the one as a turn ends. For init.
+  --help, --version   One of the two: both on one line are refused.
 
 An option a command does not read, an argument it does not take, an option or an
-argument given an empty value, and a brief given both as the argument and as --brief
-are refused, exit 2, not read as if they were not there. doctor says an empty --brief
-or --base in its report. hook claude reads its line as every release has, and says a
-line it cannot read, and a --root that is not a directory, with exit 1: it refuses
-nothing for either.
+argument given an empty value, a brief given both as the argument and as --brief,
+and an option that takes one value given two that name two things are refused, exit 2,
+not read as if they were not there, and so with --help or --version on the line. The
+same value twice, as --root . --root ./, is read once, and on Windows a drive letter in
+either case. doctor says an empty --brief or --base in its report. hook claude reads its
+line as every release has, and says a line it cannot read, two values for one option or
+--help beside a --root that is not a directory among them, a --root that is not a
+directory, and a question it cannot read, as a warning to the person with exit 0: it
+refuses nothing for any of them.
 
 Exit codes: 0 clean, 1 refused or found something, 2 the answer cannot be trusted.
 `;
@@ -93,13 +106,41 @@ Exit codes: 0 clean, 1 refused or found something, 2 the answer cannot be truste
  * to a file no brief protects reads none.
  */
 const reader = async () => (await import('./reader.js')).createReader();
-async function decisionsFor(workspace, options, io, given, cwd) {
-    const active = await activeBrief(workspace, options, io.env);
-    const { brief, note, problem } = describeActive(active);
+/**
+ * The work tree with spec-brief's answers kept for a session of Claude
+ * Code's, and given again to it where all they were read from reads the
+ * same (ADR-0002); as it is where no session is named.
+ */
+function keptFor(workspace, session) {
+    return session === null ? workspace : { ...workspace, siblings: workspace.siblings.keeping(workspace.commonDir, session) };
+}
+async function decisionsFor(workspace, options, io, given, cwd, session = null) {
+    // A path outside every work tree of the repository is decided as one
+    // outside it, whichever brief is named and whatever is wrong with the
+    // name: the problem held every write, a file outside the repository
+    // among them, where no brief decides one (ADR-0005). So no brief is asked
+    // about for such a write, and spec-brief is not run for it.
+    const outside = outsideEvery(given, workspace.root, workspace.commonDir, cwd);
+    const active = outside ? null : await activeBrief(keptFor(workspace, session), options, io.env);
+    const { brief, note, problem } = active === null ? { brief: null, note: undefined, problem: null } : describeActive(active);
     if (problem !== null)
         return { problem };
     const { checkPaths } = await import('./round.js');
-    return { decisions: await checkPaths(workspace, brief, note, given, cwd, reader, options.base) };
+    return { decisions: await checkPaths(workspace, brief, note, given, cwd, reader, options.base), brief };
+}
+/**
+ * Whether a decision is of a file the answer after the write is made from:
+ * the configuration, spec-brief's, the brief, or a file beside it in the
+ * briefs' directory, which spec-brief reads too. A call that writes one is
+ * decided again after the write, so that what the write changed is read
+ * (ADR-0002).
+ */
+function decidesAnswers(decision, brief) {
+    if (decision.path === CONFIG_FILE || SPEC_BRIEF_CONFIGS.includes(decision.path))
+        return true;
+    if (brief === null)
+        return false;
+    return decision.path === brief.file || decision.path.startsWith(`${dirname(brief.file)}/`);
 }
 const SYMBOL = { allow: 'ok     ', warn: 'warning', ask: 'ask    ', deny: 'refused' };
 async function guardCommand(options, io) {
@@ -139,10 +180,12 @@ async function readStdin(io) {
     return Buffer.concat(chunks).toString('utf8');
 }
 /**
- * The write Claude Code asks the hook about, or the exit code that answers
- * already: 1 for a question that cannot be read, 0 for a tool that writes
- * no file. Asked before anything on the hook's own line is, so that a line
- * that is wrong is said where there is a write it leaves unchecked.
+ * The write Claude Code asks the hook about, or the session that starts, or
+ * the exit code that answers already, 0: for a question that cannot be read,
+ * said to the person, and for a tool that writes no file. Asked before
+ * anything on the hook's own line is, so that a line that is wrong is said
+ * where there is a write it leaves unchecked, or a session whose every write
+ * it leaves so.
  */
 async function writeAsked(io) {
     let question;
@@ -152,27 +195,138 @@ async function writeAsked(io) {
     catch (error) {
         // A question that could not be read is one the hook cannot see, as one
         // it cannot parse is, below: it has no event to hold a write by.
-        io.stderr.write(`spec-harness: the hook input could not be read: ${error.message}\n`);
-        return EXIT_FAILED;
+        return answer(io, warningResponse(`the hook input could not be read: ${error.message}, so nothing it asks about is checked`));
     }
     const request = parseClaudeHook(question);
-    if ('error' in request) {
-        // A hook that cannot read its question refuses nothing it cannot see,
-        // but says so where the person reads it: a non-blocking error.
-        io.stderr.write(`spec-harness: ${request.error}\n`);
-        return EXIT_FAILED;
-    }
-    return request.paths.length === 0 ? EXIT_OK : request;
+    // A hook that cannot read its question refuses nothing it cannot see, and
+    // says so where the person reads it.
+    if ('error' in request)
+        return answer(io, warningResponse(`${request.error}, so nothing it asks about is checked`));
+    return request.paths.length === 0 && request.event !== SESSION_START && request.event !== TURN_END ? EXIT_OK : request;
 }
 /**
  * What is wrong with the hook's own line, said and nothing refused for it:
- * one line, since Claude Code shows the first line of the stderr of a hook
- * that exits 1 and goes on with the write, where exit 2 would hold every
- * write of the session, the one that mends the line among them (ADR-0005).
+ * one line, shown to the person, and exit 0, where exit 2 would hold every
+ * write of the session, the one that mends the line among them. Exit 1 said
+ * it as well, and is what Claude Code counts as a hook that failed, which
+ * `onFailure: "block"` holds the write for (ADR-0005).
+ */
+function guardOff(io, { wrong, mend }, event) {
+    if (event === SESSION_START)
+        return answer(io, sessionResponse(`${wrong}, so the guard is off and no write of this session is checked; ${mend}`));
+    if (event === TURN_END)
+        return answer(io, turnResponse(`spec-harness: ${wrong}, so the guard is off and no write of this session is checked; ${mend}`));
+    return answer(io, warningResponse(`${wrong}, so the guard is off and this write is not checked; ${mend}`));
+}
+function answer(io, response) {
+    io.stdout.write(response.stdout);
+    return response.exitCode;
+}
+/**
+ * The answer to a write a configuration that does not load holds no more,
+ * or `null` for every other write, which is held as before (ADR-0005). Every
+ * write was held. A write outside every work tree of the repository is
+ * decided as such a write is, after the write as before it: nothing of the
+ * repository's decides it. And before a write to the configuration file
+ * itself, and to nothing else, the line says why every other write is held,
+ * so that a session can mend a typo in it. `cwd` is what a relative path
+ * is read from.
+ */
+function mending(error, request, cwd, env) {
+    // Every configuration the hook loads is read from a file, so `file` is
+    // never `null` here, and the test of it is the compiler's: its mutant is
+    // equivalent.
+    if (!(error instanceof ConfigError) || error.file === null)
+        return null;
+    // The work trees are named by the files git keeps, where git would name
+    // the same ones; a repository whose configuration or environment moves a
+    // work tree elsewhere is not known to leave the path outside. The file
+    // was loaded from the top git named, where a `.git` stands, so the files
+    // name a work tree, and the test of `null` is the compiler's.
+    const found = gitDirectories(dirname(error.file), env);
+    if (found !== null && found.exact && outsideEvery(request.paths, found.top, found.common, cwd))
+        return NONE;
+    if (request.event !== 'PreToolUse' || !writesOnly(request.paths, error.file, cwd))
+        return null;
+    return mendResponse(`${error.message}, so every other write is held until it loads; this write, to ${error.file} itself, is not checked`);
+}
+/**
+ * What would hold every write of the session that starts, said once as it
+ * starts and no write waits on it (ADR-0005): a configuration that does not
+ * load, a brief named that spec-brief does not list or has archived, and
+ * spec-brief itself, where a brief is named, missing, too old or unable to
+ * list the briefs. Each in the words a write would be held with, and
+ * `doctor` says, and with what mends it. `null` where nothing does. The
+ * check never ends the session's start: whatever it meets is said.
+ */
+async function sessionProblem(options, io, root, cwd, session) {
+    const held = 'so every write of this session is held until it is mended';
+    try {
+        const named = await openWorkspace({ ...options, root }, io);
+        // A session in another work tree of the project has its writes decided
+        // there, and so is the check (ADR-0005).
+        const found = cwd === null ? null : await otherTree(named, cwd);
+        const workspace = found === null ? named : await openFound(found, io, () => [named.root]);
+        const { problem } = describeActive(await activeBrief(keptFor(workspace, session), options, io.env));
+        return problem === null ? null : `${heldHookLine(problem).wrong}, ${held}: fix the brief or the branch before writing; spec-harness doctor says more`;
+    }
+    catch (error) {
+        // A session in no work tree has nothing to guard, as a write there has
+        // not. Anything else that stops the check stops a write's as well, which
+        // is then held as one the hook cannot check: a configuration that does
+        // not load, a spec-brief that is missing, too old or cannot list the
+        // briefs, and whatever a defect throws.
+        if (error instanceof UsageError)
+            return null;
+        // But a write to the configuration file itself, which mends it, where
+        // the file is one a write may reach under its name alone (ADR-0005). The
+        // configuration is read from a file here as before a write, so the test
+        // of `file` is the compiler's, and its mutant is equivalent.
+        const mendable = error instanceof ConfigError && error.file !== null && writesOnly([error.file], error.file, root);
+        return `${error.message}, ${held}${mendable ? `, but for a write to ${error.file} itself, which is not checked` : ''}; spec-harness doctor says more`;
+    }
+}
+/** The most paths a report names one by one: past it, how many more there are. */
+const REPORTED = 20;
+/**
+ * What the work tree holds at the end of a turn that the brief protects or
+ * that is outside its scope, one line a path in the words a write of it is
+ * given; or `null` where there is nothing to say: `turnReport` is off, no
+ * brief is named, nothing changed is either, or the session is in no work
+ * tree (ADR-0005). The work tree is the one a write of the session is
+ * decided in. One start of git reads what changed, and nothing is asked of
+ * the base, so no ruling is read: a protected file a signed ruling allows
+ * is said as protected, and the audit reads the ruling. A configuration
+ * that does not load is said by every write and as the session starts, and
+ * here holds the report back without a word.
  */
-function guardOff(io, { wrong, mend }) {
-    io.stderr.write(`spec-harness: ${wrong}, so the guard is off and this write is not checked; ${mend}\n`);
-    return EXIT_FAILED;
+async function turnReport(options, io, root, cwd) {
+    try {
+        const named = await openWorkspace({ ...options, root }, io);
+        const found = cwd === null ? null : await otherTree(named, cwd);
+        const workspace = found === null ? named : await openFound(found, io, () => [named.root]);
+        if (!workspace.config.turnReport)
+            return null;
+        const { brief, problem } = describeActive(await activeBrief(workspace, options, io.env));
+        if (problem !== null)
+            return `spec-harness: ${heldHookLine(problem).wrong}, so what the work tree holds is not reported, and every write is held; spec-harness doctor says more`;
+        if (brief === null)
+            return null;
+        const [changed, { decide }] = await Promise.all([changedPaths(workspace.root), import('./guard.js')]);
+        const outOfScope = workspace.config.outOfScope;
+        const said = changed.map((path) => decide({ path, given: path, brief, rulings: [], outOfScope })).filter((decision) => decision.verdict !== 'allow');
+        if (said.length === 0)
+            return null;
+        const lines = said.slice(0, REPORTED).map((decision) => `- ${decision.message}. Next: ${decision.hint}.`);
+        const more = said.length > REPORTED ? [`- and ${said.length - REPORTED} more: spec-harness guard <path> says each`] : [];
+        const paths = said.length === 1 ? `a path that brief ${brief.id} protects or that is outside its scope` : `${said.length} paths that brief ${brief.id} protects or that are outside its scope`;
+        return [`spec-harness: as this turn ended, the work tree held changes to ${paths}:`, ...lines, ...more].join('\n');
+    }
+    catch (error) {
+        if (error instanceof UsageError || error instanceof ConfigError)
+            return null;
+        return `spec-harness: ${error.message}, so what the work tree holds is not reported`;
+    }
 }
 /**
  * Claude Code's hook on a line the parser refused: an option no command has,
@@ -185,7 +339,53 @@ async function unreadLine(said, io) {
     const request = await writeAsked(io);
     if (typeof request === 'number')
         return request;
-    return guardOff(io, unreadHookLine(said).fault);
+    return guardOff(io, unreadHookLine(said).fault, request.event);
+}
+/**
+ * The answer after a write, where it can be given with no process started,
+ * or `null` where it is to be decided as before (ADR-0002, ADR-0003).
+ *
+ * The git directory is the one the files at the hook's root name. What the
+ * run before the write kept for this call, if anything, is taken away as it
+ * is read, and answered from where it is this call's: the same release,
+ * session, call, tool, paths, directories, line and variables. And where
+ * nothing is kept, a run after a write says nothing but a warning outside
+ * the scope, which only `outOfScope: "warn"` decides: under `ask` or
+ * `deny` there is nothing to say, where the configuration read is the one
+ * git would have the hook read, of the work tree the session is in.
+ */
+async function answeredAfter(root, record, cwd, paths, io) {
+    const found = gitDirectories(root, io.env);
+    if (found === null)
+        return null;
+    if (record !== null) {
+        const kept = await takeCall(found.common, callFile(record));
+        // warningsKept reads no text as no record as well: the test is there for
+        // the type, and its mutant is equivalent.
+        const warnings = kept === null ? null : warningsKept(kept, record);
+        if (warnings !== null)
+            return afterResponse(warnings);
+    }
+    // A path in another work tree than the one this configuration is read
+    // from may be decided by another's, which may warn.
+    if (!found.exact || (cwd !== null && mayBeElsewhere(cwd, found.top)) || paths.some((path) => mayBeElsewhere(resolve(cwd ?? io.cwd, path), found.top)))
+        return null;
+    try {
+        return (await loadConfig(found.top)).config.outOfScope === 'warn' ? null : afterResponse([]);
+    }
+    catch {
+        // A configuration that does not load is said as it was, by the run.
+        return null;
+    }
+}
+/**
+ * The answer before a write the hook could not check: one line, and exit 2,
+ * which holds the write. Claude Code shows the line to Claude as the
+ * reason.
+ */
+function cannotCheck(io, error) {
+    io.stderr.write(`spec-harness: cannot check this write: ${error.message}\n`);
+    return EXIT_ERROR;
 }
 async function hookCommand(options, io) {
     const kind = options.positionals[0];
@@ -197,41 +397,90 @@ async function hookCommand(options, io) {
         // reads the line where it finds it in a settings file (usage.ts).
         const line = readHookLine(options.root, io.cwd, isDirectory);
         if (line.state === 'off')
-            return guardOff(io, line.fault);
+            return guardOff(io, line.fault, request.event);
         const cwd = request.cwd ?? io.cwd;
+        const root = line.root ?? io.env['CLAUDE_PROJECT_DIR'] ?? cwd;
+        const session = sessionOf(request);
+        if (request.event === SESSION_START)
+            return answer(io, sessionResponse(await sessionProblem(options, io, root, request.cwd, session)));
+        if (request.event === TURN_END)
+            return answer(io, turnResponse(await turnReport(options, io, root, request.cwd)));
+        const record = callRecord(request, { root: line.root, brief: options.brief, base: options.base }, io.cwd, io.env, version());
+        if (request.event === 'PostToolUse') {
+            const answered = await answeredAfter(root, record, request.cwd, request.paths, io);
+            if (answered !== null) {
+                io.stdout.write(answered.stdout);
+                return answered.exitCode;
+            }
+        }
         let workspace;
         try {
-            workspace = await openWorkspace({ ...options, root: line.root ?? io.env['CLAUDE_PROJECT_DIR'] ?? cwd }, io);
+            workspace = await openWorkspace({ ...options, root }, io);
         }
         catch (error) {
             if (error instanceof UsageError)
                 return EXIT_OK;
+            const mended = mending(error, request, cwd, io.env);
+            if (mended !== null)
+                return answer(io, mended);
+            // git asked where the work tree is and did not answer within its time
+            // limit: before a write that is a write the hook could not check, said
+            // as one (ADR-0002).
+            if (error instanceof GitError && request.event === 'PreToolUse')
+                return cannotCheck(io, error);
             throw error;
         }
         try {
-            const decided = await decisionsFor(workspace, options, io, request.paths, cwd);
-            if ('problem' in decided) {
-                // Exit 2 blocks the tool call, and its stderr reaches the model. Where
-                // the name stands on the hook's own line, what is wrong with it is
-                // `doctor`'s to say as well, in the same words (usage.ts).
-                io.stderr.write(`spec-harness: ${heldHookLine(decided.problem).wrong}. Fix the brief or the branch before writing.\n`);
-                return EXIT_ERROR;
+            // The answer reads a decision by its verdict, which a mutant's text
+            // put first on this list has none of: that mutant is equivalent.
+            const decisions = [];
+            // Whether the run after the write may answer from what this one keeps:
+            // not where a decision refuses, nor where the write is to what the
+            // answer is made from, in any work tree that decides it.
+            let keeps = true;
+            for (const part of await writesBy(workspace, request.cwd, request.paths, io)) {
+                const decided = await decisionsFor(part.workspace, options, io, part.paths, cwd, session);
+                if ('problem' in decided) {
+                    // Exit 2 blocks the tool call, and its stderr reaches the model. Where
+                    // the name stands on the hook's own line, what is wrong with it is
+                    // `doctor`'s to say as well, in the same words (usage.ts).
+                    io.stderr.write(`spec-harness: ${heldHookLine(decided.problem).wrong}. Fix the brief or the branch before writing.\n`);
+                    return EXIT_ERROR;
+                }
+                // A line of the answer for each path, by the work tree that decided it.
+                decisions.push(...decided.decisions);
+                if (decided.decisions.some((decision) => decision.verdict === 'deny' || decidesAnswers(decision, decided.brief)))
+                    keeps = false;
             }
-            const response = claudeResponse(request.event, decided.decisions);
+            const response = claudeResponse(request.event, decisions);
             io.stdout.write(response.stdout);
+            // What the run after the write will say, kept for it where the call
+            // goes ahead: a refused call has none. It changes nothing of the
+            // answer, which is made before it is kept.
+            if (request.event === 'PreToolUse' && record !== null && keeps) {
+                await keepCall(workspace.commonDir, callFile(record), keptCall(record, warningsOf(decisions)));
+            }
             return response.exitCode;
         }
         catch (error) {
             if (request.event !== 'PreToolUse')
                 throw error;
+            // The configuration of another work tree the write is decided in,
+            // which does not load, lets a write to itself through as the
+            // project's does.
+            const mended = mending(error, request, cwd, io.env);
+            if (mended !== null)
+                return answer(io, mended);
             // A round is named and its briefs cannot be read: the guard cannot
             // tell a protected file from any other, so the write waits.
-            io.stderr.write(`spec-harness: cannot check this write: ${error.message}\n`);
-            return EXIT_ERROR;
+            return cannotCheck(io, error);
         }
     }
     if (kind === 'git') {
-        const workspace = await openWorkspace(options, io);
+        // git starts its hook at the top of the work tree it commits in, a
+        // linked worktree's own, whose install may be none: it is then checked
+        // with the main work tree's (ADR-0005).
+        const workspace = await openWorkspace(options, io, MAIN_INSTALL);
         const staged = await stagedChanges(workspace.root);
         const paths = staged.flatMap((change) => (change.from === undefined ? [change.path] : [change.from, change.path]));
         if (paths.length === 0)
@@ -262,6 +511,15 @@ async function baseAndSigners({ resolveBase }, workspace, flag, signersFile) {
     const signersText = base.kind === 'resolved' ? await show(base.sha, signersFile, workspace.root) : null;
     return { base, signersText };
 }
+/**
+ * The release of spec-harness installed in a work tree, where the hook's
+ * line, init's and the plugin's, names its script under the project's
+ * `node_modules`; `null` where none is, or its manifest gives no version.
+ */
+function harnessRelease(root) {
+    const version = declaredVersion(join(root, 'node_modules', '@descent-vtt', 'spec-harness', 'package.json'));
+    return typeof version === 'string' ? version : null;
+}
 /**
  * How Claude Code is wired to the guard, and the release of the one on
  * `PATH`, which waits on the wiring: only a Claude Code that runs the guard
@@ -279,21 +537,25 @@ async function doctorCommand(options, io) {
     // What doctor alone runs of them, loaded before anything is asked: the
     // five things below are asked at once, and none waits on a module.
     const [configure, round, setup, signing] = await Promise.all([import('./configure.js'), import('./round.js'), import('./setup.js'), import('./signers.js')]);
-    const { describeBase, describeClaudeCode, describeClaudeRelease, describeGitHook, describeHooksOff, describePlugin, describePresence, describeSignerKeys, describeSignerProblem, describeSigners, guardSwitchedOff, wiringState } = configure;
+    const { describeBase, describeClaudeCode, describeClaudeRelease, describeGitHook, describeHooksOff, describeInstalls, describePlugin, describePresence, describeSignerKeys, describeSignerProblem, describeSigners, guardSwitchedOff, guardWired, NO_SESSION_START, wiringState } = configure;
     const { diagnoseBrief, specBriefPlugin } = round;
     const { gitHook } = setup;
     const { notFido2, readAllowedSigners } = signing;
-    const workspace = await openWorkspace(options, io);
+    // The siblings as git's hook finds them in this work tree: its own
+    // install, and in a linked worktree with none the main work tree's.
+    const workspace = await openWorkspace(options, io, MAIN_INSTALL);
     const rows = SIBLINGS.map((name) => {
         const sibling = workspace.siblings.locate(name);
         const row = { tool: name, state: sibling.kind, minimum: MINIMUM_VERSIONS[name] };
         if (sibling.kind === 'absent')
-            return { ...row, version: null, detail: sibling.reason };
+            return { ...row, version: null, elsewhere: null, detail: sibling.reason };
+        const elsewhere = sibling.elsewhere ?? null;
+        const whose = elsewhere === null ? '' : `, the install of ${elsewhere}: this work tree has none of its own`;
         if (sibling.kind === 'outdated')
-            return { ...row, version: sibling.version, detail: sibling.reason };
+            return { ...row, version: sibling.version, elsewhere, detail: `${sibling.reason}${whose}` };
         const command = sibling.command.join(' ');
-        const detail = sibling.version === null ? `${command} (named in .spec-harness.json; its version is not checked)` : `${command} (${sibling.version})`;
-        return { ...row, version: sibling.version, detail };
+        const detail = sibling.version === null ? `${command} (named in .spec-harness.json; its version is not checked)` : `${command} (${sibling.version}${whose})`;
+        return { ...row, version: sibling.version, elsewhere, detail };
     });
     const signersFile = workspace.config.rulings.allowedSigners;
     // Five things that wait on the work tree and on nothing of one another,
@@ -336,7 +598,15 @@ async function doctorCommand(options, io) {
     // this machine, or cannot be told to be, and disableAllHooks, which
     // switches off whatever hooks there are.
     const switchedOff = guardSwitchedOff(wiring);
-    const wiringNotes = [describePresence(wiring), wiring.hooksOff === null ? null : describeHooksOff(wiring.hooksOff, switchedOff)].filter((note) => note !== null);
+    // And whether the hook is started as a session starts, where settings hold
+    // the guard: a note, failing nothing, and `sessionStart` in the document.
+    const atStart = wiring.hooks.length > 0 && !wiring.sessionStart ? NO_SESSION_START : null;
+    // And, in a linked worktree where something wires the guard, the release
+    // the hook's line runs where it is not this work tree's own: a note. In
+    // the main work tree both are read from one install, and are one.
+    const main = mainWorkTree(workspace.commonDir);
+    const installs = guardWired(wiring) && main !== null ? describeInstalls(main, harnessRelease(main), harnessRelease(workspace.root)) : null;
+    const wiringNotes = [describePresence(wiring), wiring.hooksOff === null ? null : describeHooksOff(wiring.hooksOff, switchedOff), installs].filter((note) => note !== null);
     // How the hook runs the harness is a note: one that goes through npx guards
     // as well as one that does not, and fails nothing, --strict or not.
     const { hook, note: hookNote } = answerOf(hookAsked);
@@ -384,6 +654,7 @@ async function doctorCommand(options, io) {
             ...more(wiringNotes),
             ...more(lineNotes),
             ...more(release === null ? [] : [describeClaudeRelease(release)]),
+            ...more(atStart === null ? [] : [atStart]),
             `git     ${describeGitHook(hook)}`,
             ...more(hookNote === null ? [] : [hookNote]),
             '',
@@ -396,21 +667,28 @@ async function doctorCommand(options, io) {
     // a choice; with none installed, the harness can check nothing. A double
     // install is a problem too, where no Claude Code wiring at all is a choice,
     // and so are a hook whose own line turns the guard off or holds every
-    // write, guard hooks that disableAllHooks switches off, a plugin that is
-    // turned on and is not on this machine where no hook of init's stands in
-    // for it, a Claude Code too old to run the hooks, and something at the
-    // path of git's pre-commit hook that git cannot run and stops every
-    // commit at. A release that cannot be told is not fine either, nor a
-    // line whose reading cannot be, nor a plugin that cannot be told to be on
-    // this machine: --strict fails the three.
+    // write, a branch that names a brief no round can work under, which holds
+    // every write as well (ADR-0004), guard hooks that disableAllHooks
+    // switches off, a plugin that is turned on and is not on this machine
+    // where no hook of init's stands in for it, a Claude Code too old to run
+    // the hooks, and something at the path of git's pre-commit hook that git
+    // cannot run and stops every commit at. A release that cannot be told is
+    // not fine either, nor a line whose reading cannot be, nor a plugin that
+    // cannot be told to be on this machine, nor a hook git runs that cannot be
+    // read, which stops every commit as a script and runs as a program, nor a
+    // place git runs its hooks from that git cannot name: --strict fails the
+    // five.
     const outdated = rows.some((row) => row.state === 'outdated');
     const usable = rows.some((row) => row.state === 'found');
     const off = wiring.lines.some((line) => line.state === 'off' || line.state === 'held');
     const missing = wiring.presence?.state === 'absent' && wiring.hooks.length === 0;
     const tooOld = release?.state === 'outdated';
     const stopped = hook.state === 'stops';
-    const untold = options.strict && (release?.state === 'unknown' || wiring.lines.some((line) => line.state === 'unknown') || wiring.presence?.state === 'unknown');
-    return outdated || !usable || claude === 'both' || off || switchedOff || missing || tooOld || stopped || untold ? EXIT_FAILED : EXIT_OK;
+    // Only an unreadable hook has `runs`, so the test of its state is the
+    // compiler's, and its mutant is equivalent.
+    const untold = options.strict &&
+        (release?.state === 'unknown' || wiring.lines.some((line) => line.state === 'unknown') || wiring.presence?.state === 'unknown' || (hook.state === 'unreadable' && hook.runs) || hook.state === 'unknown');
+    return outdated || !usable || claude === 'both' || off || named.branch || switchedOff || missing || tooOld || stopped || untold ? EXIT_FAILED : EXIT_OK;
 }
 /* ---------------------------------------------------------------- dispatch */
 /**
@@ -452,16 +730,20 @@ async function dispatch(argv, io) {
         io.stderr.write(`spec-harness: ${refused.message}\n`);
         return EXIT_ERROR;
     }
-    if (options.version) {
-        io.stdout.write(`${version()}\n`);
-        return EXIT_OK;
-    }
-    if (options.help || options.command === undefined) {
-        io.stdout.write(HELP);
-        return options.help ? EXIT_OK : EXIT_ERROR;
+    // Two values for an option that takes one: the parser kept the last, and
+    // which was meant cannot be told from the line, so it is refused as a line
+    // the parser cannot read is, and Claude Code's hook says it of its own.
+    const twice = twoValues(options, io.cwd);
+    if (twice !== null) {
+        if (isClaudeHook(options.command, options.positionals[0]))
+            return unreadLine(twice, io);
+        io.stderr.write(`spec-harness: ${twice}; give it one\n`);
+        return EXIT_ERROR;
     }
-    const command = COMMANDS.get(options.command);
-    if (command === undefined) {
+    // A line that is wrong is refused before --help or --version answers: an
+    // answer beside it said nothing of what was wrong, exit 0, as an option no
+    // command has never was (spec-core ADR-0005).
+    if (options.command !== undefined && !COMMANDS.has(options.command)) {
         io.stderr.write(`spec-harness: unknown command "${options.command}"; see spec-harness --help\n`);
         return EXIT_ERROR;
     }
@@ -471,7 +753,22 @@ async function dispatch(argv, io) {
         io.stderr.write(`spec-harness: ${refused}\n`);
         return EXIT_ERROR;
     }
-    return command(options, io);
+    // Claude Code's hook is exempt from every refusal above, and said a root
+    // that is not a directory only as it ran, which the help or the version
+    // answered in place of: printed beside one, either is a line it cannot
+    // read, said where there is a write it leaves unchecked (ADR-0005).
+    const beside = isClaudeHook(options.command, options.positionals[0]) ? answerBeside(options, io.cwd, isDirectory) : null;
+    if (beside !== null)
+        return unreadLine(beside, io);
+    if (options.version) {
+        io.stdout.write(`${version()}\n`);
+        return EXIT_OK;
+    }
+    if (options.help || options.command === undefined) {
+        io.stdout.write(HELP);
+        return options.help ? EXIT_OK : EXIT_ERROR;
+    }
+    return COMMANDS.get(options.command)(options, io);
 }
 /**
  * Runs the command line and resolves to the exit code, for an error nothing
@@ -506,12 +803,15 @@ export async function run(argv, io) {
     catch (error) {
         // A sibling's document of a shape the harness does not read is a sibling
         // that printed something it cannot read (answers.ts): exit 2. A git
-        // command that failed is what git said, and no line of the harness's.
+        // command that failed is what git said, and no line of the harness's;
+        // and a path under git's directory where the harness keeps its state,
+        // which holds something else, is said in a line of its own (fs.ts).
         if (error instanceof UsageError ||
             error instanceof ConfigError ||
             error instanceof SiblingError ||
             error instanceof SiblingOutputError ||
-            error instanceof GitError) {
+            error instanceof GitError ||
+            error instanceof StateError) {
             io.stderr.write(`spec-harness: ${error.message}\n`);
             return EXIT_ERROR;
         }