@descent-vtt/spec-harness 0.19.0 → 0.21.0

package/dist/siblings.js

@@ -15,7 +15,9 @@
 import { execFile } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { parseBriefList, SiblingOutputError } from './briefs.js';
+import { inputsOf, parseBriefList, SiblingOutputError } from './briefs.js';
+import { hasher, isFile, keepAnswer, keptAnswer, readsAsListed } from './fs.js';
+import { ANSWER_MS, stoppedAtLimit, timeFor, WORK_MS } from './git.js';
 import { checkVersion } from './versions.js';
 /**
  * Where a sibling is, or why it cannot be run. It is looked for in `root`'s
@@ -51,6 +53,10 @@ export function locate(name, root, config, installs = []) {
 }
 /** The `version` a package.json declares, or `undefined` when there is no such file or it is not JSON. */
 export function declaredVersion(file) {
+    // Only a file is read: a named pipe under the name was read without end,
+    // and before any sibling ran (ADR-0002).
+    if (!isFile(file))
+        return undefined;
     // A manifest that holds null throws on the read, and any other value that
     // is not an object has no version, so the catch answers for both. Falling
     // out of it answers undefined as well, and a Buffer parses as its text:
@@ -68,39 +74,107 @@ export function declaredVersion(file) {
  *
  * Never through a shell: an argument is a path or a brief id, and a shell
  * would read it as syntax. `node` as a command's first word is this Node, so
- * `["node", "path/to/bin.js"]` works on every host; a Windows `.cmd` shim such
- * as `npx` cannot be started without a shell, and the error says to name the
- * script instead.
+ * `["node", "path/to/bin.js"]` works on every host. A program that cannot be
+ * started is answered on every host in one way, code -1 and a line that says
+ * to name the tool's script: one not found, a script named without `node`,
+ * a Windows `.cmd` shim such as `npx`, which cannot be started without a
+ * shell, a directory or a file the account may not run.
+ *
+ * A sibling that does not answer within `limit` is stopped, and rejected as
+ * a `SiblingError` that names it: what it was asked waits on it, the hook
+ * before a write among them, which then holds the write (ADR-0002).
  */
-export function runSibling(command, args, root, timeoutMs = 600_000) {
+export function runSibling(name, command, args, root, limit = WORK_MS) {
     const [first, ...rest] = command;
     const program = first === 'node' ? process.execPath : first;
-    return new Promise((resolve) => {
-        execFile(program, [...rest, ...args], {
-            cwd: root,
-            maxBuffer: 256 * 1024 * 1024,
-            encoding: 'utf8',
-            // Keeps a console window from opening on Windows; the sweep runs on
-            // Linux, where the mutant is equivalent.
-            windowsHide: true,
-            timeout: timeoutMs,
-            shell: false,
-            env: { ...process.env, NO_COLOR: '1', FORCE_COLOR: '0' },
-        }, (error, stdout, stderr) => {
-            const failure = error;
-            if (failure !== null && failure.code === 'ENOENT') {
-                resolve({
-                    code: -1,
-                    stdout: '',
-                    stderr: `cannot start "${first}": name the tool's script, such as ["node", "node_modules/@descent-vtt/<tool>/bin/<tool>.js"]`,
-                });
-                return;
-            }
-            const code = failure === null ? 0 : typeof failure.code === 'number' ? failure.code : -1;
-            resolve({ code, stdout, stderr });
-        });
+    const { ms, said } = timeFor(limit);
+    if (ms === 0)
+        return Promise.reject(new SiblingError(`${name} was not started: ${said} had passed`));
+    const unstarted = {
+        code: -1,
+        stdout: '',
+        stderr: `cannot start "${first}": name the tool's script, such as ["node", "node_modules/@descent-vtt/<tool>/bin/<tool>.js"]`,
+    };
+    return new Promise((resolve, reject) => {
+        try {
+            execFile(program, [...rest, ...args], {
+                cwd: root,
+                maxBuffer: 256 * 1024 * 1024,
+                encoding: 'utf8',
+                // Keeps a console window from opening on Windows; the sweep runs on
+                // Linux, where the mutant is equivalent.
+                windowsHide: true,
+                timeout: ms,
+                shell: false,
+                env: { ...process.env, NO_COLOR: '1', FORCE_COLOR: '0' },
+            }, (error, stdout, stderr) => {
+                if (stoppedAtLimit(error)) {
+                    reject(new SiblingError(`${name} did not answer within ${said}, and was stopped`));
+                    return;
+                }
+                const failure = error;
+                // Of what reaches here, only the error of a process that was never
+                // made names the system call that failed, `spawn` and the program:
+                // ENOENT, and on Linux and macOS EACCES for a directory or a file
+                // that may not be run. One that ran has its exit code, and one
+                // stopped at its limit was answered above.
+                if (failure !== null && typeof failure.syscall === 'string') {
+                    resolve(unstarted);
+                    return;
+                }
+                const code = failure === null ? 0 : typeof failure.code === 'number' ? failure.code : -1;
+                resolve({ code, stdout, stderr });
+            });
+        }
+        catch {
+            // Some programs are refused before a process is made, and Node throws
+            // that rather than pass it to the callback: on Windows a script, as
+            // EFTYPE, and a `.cmd` or `.bat`, as EINVAL; on every host a NUL in a
+            // word of the command. The options are this function's own, so what
+            // execFile throws is a command it could not start.
+            resolve(unstarted);
+        }
     });
 }
+/**
+ * Where and under what a session's answer of spec-brief's is kept, or
+ * `null` where none is. A command `tools` names is started every time:
+ * which version it runs cannot be told without starting it.
+ */
+async function keeperOf(kept, root, sibling) {
+    // A command with no version is kept nothing by the test of the version an
+    // answer names, too: the mutant without this one reads, for every write, a
+    // kept answer there is none of, and is equivalent.
+    if (sibling.version === null)
+        return null;
+    const hash = await hasher();
+    const key = answerKey(root, kept.session, sibling.command, sibling.version);
+    return { commonDir: kept.commonDir, key, name: `${hash(key)}.json`, version: sibling.version, hash };
+}
+/**
+ * The briefs a kept answer gives, or `null` where it is not to be given:
+ * nothing kept, or what was kept is not a list document that names what it
+ * was read from in the version installed, or anything it names reads
+ * otherwise.
+ */
+async function givenAgain(stdout, version, root, hash) {
+    // JSON.parse reads null as null, which names no inputs, and a null read
+    // past the test of none below throws, which answers null: the two tests
+    // are the compiler's, and their mutants equivalent.
+    if (stdout === null)
+        return null;
+    try {
+        const document = JSON.parse(stdout);
+        const inputs = inputsOf(document);
+        if (inputs === null || inputs.tool !== version || !(await readsAsListed(root, inputs, hash)))
+            return null;
+        return parseBriefList(document);
+    }
+    catch {
+        // What another program wrote there is no answer of spec-brief's.
+        return null;
+    }
+}
 export class SiblingError extends Error {
     constructor(message) {
         super(message);
@@ -116,24 +190,56 @@ function parseJson(name, run) {
         throw new SiblingError(`${name} exited ${run.code} without JSON${said ? `: ${said}` : ''}`);
     }
 }
+/** The command line spec-brief is asked for the briefs with. */
+const LIST = ['list', '--archived', '--format', 'json', '--no-color'];
+/**
+ * The variables beyond git's own that an answer of spec-brief's can turn on
+ * and its list does not name: which git and which Node run, where git finds
+ * the person's configuration and ignore files, and how Node runs a script.
+ * Every variable whose name begins `GIT_` is read with them.
+ */
+const ANSWER_VARIABLES = ['PATH', 'HOME', 'USERPROFILE', 'HOMEDRIVE', 'HOMEPATH', 'XDG_CONFIG_HOME', 'NODE_OPTIONS', 'NODE_PATH'];
+/**
+ * What a kept answer is the answer to: the work tree, the session, the
+ * spec-brief that answered, by its command, its version and the Node it ran
+ * on, the command line, and the variables above, as spec-brief is started
+ * with them (runSibling). An answer is given again only for the same.
+ */
+export function answerKey(root, session, command, version, env = process.env) {
+    const variables = Object.keys(env)
+        .filter((name) => /^GIT_/i.test(name) || ANSWER_VARIABLES.includes(name.toUpperCase()))
+        // One case for each name, whichever: the mutant that folds to the other is equivalent.
+        .map((name) => [name.toUpperCase(), env[name]])
+        .sort();
+    return JSON.stringify({ root, session, command, version, node: process.version, args: LIST, variables });
+}
 /** The siblings of the work tree at `root`, looked for in its install and then in each of `installs` (locate). */
 export function createSiblings(root, config, installs = []) {
-    const found = (name) => {
-        const sibling = locate(name, root, config, installs);
-        if (sibling.kind !== 'found')
-            throw new SiblingError(sibling.reason);
-        return sibling.command;
-    };
+    return siblingsOf(root, config, installs, null);
+}
+function siblingsOf(root, config, installs, kept) {
     return {
         root,
         locate: (name) => locate(name, root, config, installs),
-        async briefs() {
-            const run = await runSibling(found('spec-brief'), ['list', '--archived', '--format', 'json', '--no-color'], root);
+        async briefs(limit = ANSWER_MS) {
+            const sibling = locate('spec-brief', root, config, installs);
+            if (sibling.kind !== 'found')
+                throw new SiblingError(sibling.reason);
+            const keeper = kept === null ? null : await keeperOf(kept, root, sibling);
+            if (keeper !== null) {
+                const again = await givenAgain(await keptAnswer(keeper.commonDir, keeper.name, keeper.key), keeper.version, root, keeper.hash);
+                if (again !== null)
+                    return again;
+            }
+            const run = await runSibling('spec-brief', sibling.command, LIST, root, limit);
             if (run.code === 2) {
                 throw new SiblingError(`spec-brief could not list the briefs: ${run.stderr.trim().split('\n')[0] || 'exit 2'}`);
             }
+            let document;
+            let rows;
             try {
-                return parseBriefList(parseJson('spec-brief', run));
+                document = parseJson('spec-brief', run);
+                rows = parseBriefList(document);
             }
             catch (error) {
                 // parseJson throws a SiblingError, which this would copy, and
@@ -143,12 +249,19 @@ export function createSiblings(root, config, installs = []) {
                     throw new SiblingError(error.message);
                 throw error;
             }
+            // Kept only where spec-brief said all was well and named what it read,
+            // in the version that answered: any other answer is read once.
+            if (keeper !== null && run.code === 0 && inputsOf(document)?.tool === keeper.version) {
+                await keepAnswer(keeper.commonDir, keeper.name, keeper.key, run.stdout);
+            }
+            return rows;
         },
+        keeping: (commonDir, session) => siblingsOf(root, config, installs, { commonDir, session }),
         async json(name, args) {
             const sibling = locate(name, root, config, installs);
             if (sibling.kind !== 'found')
                 return { absent: sibling.reason };
-            const run = await runSibling(sibling.command, args, root);
+            const run = await runSibling(name, sibling.command, args, root);
             return { code: run.code, document: parseJson(name, run), stderr: run.stderr };
         },
     };

package/dist/siblings.js.map

@@ -1 +1 @@
-{"version":3,"file":"siblings.js","sourceRoot":"","sources":["../src/siblings.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The edge where the harness meets spec-brief, spec-graph and spec-guard.\n *\n * Through their command lines and their versioned JSON, never by importing\n * their packages: each is released, pinned and dropped on its own, and none\n * becomes a dependency of this one (spec-core ADR-0005, ADR-0002 here).\n *\n * A sibling is found as the repository installed it -\n * `node_modules/@descent-vtt/<name>/bin/<name>.js`, run with this Node - or\n * as `.spec-harness.json` names it. One that is not there is `absent`, and\n * what needed it says so; nothing it would have checked is reported clean.\n * One installed below this release's minimum is `outdated`, and is reported\n * the same way rather than run (versions.ts).\n */\n\nimport { execFile } from 'node:child_process';\nimport { existsSync, readFileSync } from 'node:fs';\nimport { join } from 'node:path';\n\nimport { parseBriefList, SiblingOutputError } from './briefs.js';\nimport type { HarnessConfig, SiblingName } from './config.js';\nimport type { BriefRow } from './types.js';\nimport { checkVersion } from './versions.js';\n\nexport interface SiblingRun {\n  readonly code: number;\n  readonly stdout: string;\n  readonly stderr: string;\n}\n\nexport type Sibling =\n  /**\n   * `version` is `null` for a command `.spec-harness.json` names, whose\n   * version is not checked. `elsewhere` is the directory whose install it\n   * is, where that is not the work tree's own.\n   */\n  | { readonly kind: 'found'; readonly command: readonly string[]; readonly version: string | null; readonly elsewhere?: string }\n  | { readonly kind: 'absent'; readonly reason: string }\n  /** Installed, at a version below the minimum or one that cannot be read, which is `null`. */\n  | { readonly kind: 'outdated'; readonly reason: string; readonly version: string | null; readonly elsewhere?: string };\n\n/**\n * Where a sibling is, or why it cannot be run. It is looked for in `root`'s\n * install, then in each of `installs` in turn, and the first that has it\n * decides, at this release's floor: a work tree with an install of its own\n * runs it, outdated or not, and one with none is checked with the\n * project's, as git's hook and Claude Code's are where a linked worktree has\n * none (ADR-0005).\n */\n// A name a mutant puts on the default list is a directory relative to where\n// the run is, which holds no install: equivalent, here and below.\nexport function locate(name: SiblingName, root: string, config: HarnessConfig, installs: readonly string[] = []): Sibling {\n  // A command the configuration names is run as named: which package it runs,\n  // and so which version, is the configuration's to say.\n  const configured = config.tools[name];\n  if (configured !== null) return { kind: 'found', command: configured, version: null };\n  for (const place of [root, ...installs]) {\n    const directory = join(place, 'node_modules', '@descent-vtt', name);\n    const bin = join(directory, 'bin', `${name}.js`);\n    if (!existsSync(bin)) continue;\n    const check = checkVersion(name, declaredVersion(join(directory, 'package.json')));\n    const where = place === root ? {} : { elsewhere: place };\n    if (!check.ok) return { kind: 'outdated', reason: check.reason, version: check.version, ...where };\n    return { kind: 'found', command: [process.execPath, bin], version: check.version, ...where };\n  }\n  return {\n    kind: 'absent',\n    reason: `${name} is not installed here: npm install --save-dev @descent-vtt/${name}, or name its command under \"tools\" in .spec-harness.json`,\n  };\n}\n\n/** The `version` a package.json declares, or `undefined` when there is no such file or it is not JSON. */\nexport function declaredVersion(file: string): unknown {\n  // A manifest that holds null throws on the read, and any other value that\n  // is not an object has no version, so the catch answers for both. Falling\n  // out of it answers undefined as well, and a Buffer parses as its text:\n  // the empty catch and the encoding are equivalent to their mutants.\n  try {\n    const manifest: { version?: unknown } = JSON.parse(readFileSync(file, 'utf8'));\n    return manifest.version;\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * Runs a sibling with arguments, in the repository root.\n *\n * Never through a shell: an argument is a path or a brief id, and a shell\n * would read it as syntax. `node` as a command's first word is this Node, so\n * `[\"node\", \"path/to/bin.js\"]` works on every host; a Windows `.cmd` shim such\n * as `npx` cannot be started without a shell, and the error says to name the\n * script instead.\n */\nexport function runSibling(command: readonly string[], args: readonly string[], root: string, timeoutMs = 600_000): Promise<SiblingRun> {\n  const [first, ...rest] = command;\n  const program = first === 'node' ? process.execPath : (first as string);\n  return new Promise((resolve) => {\n    execFile(\n      program,\n      [...rest, ...args],\n      {\n        cwd: root,\n        maxBuffer: 256 * 1024 * 1024,\n        encoding: 'utf8',\n        // Keeps a console window from opening on Windows; the sweep runs on\n        // Linux, where the mutant is equivalent.\n        windowsHide: true,\n        timeout: timeoutMs,\n        shell: false,\n        env: { ...process.env, NO_COLOR: '1', FORCE_COLOR: '0' },\n      },\n      (error, stdout, stderr) => {\n        const failure = error as (Error & { code?: unknown }) | null;\n        if (failure !== null && failure.code === 'ENOENT') {\n          resolve({\n            code: -1,\n            stdout: '',\n            stderr: `cannot start \"${first}\": name the tool's script, such as [\"node\", \"node_modules/@descent-vtt/<tool>/bin/<tool>.js\"]`,\n          });\n          return;\n        }\n        const code = failure === null ? 0 : typeof failure.code === 'number' ? failure.code : -1;\n        resolve({ code, stdout, stderr });\n      },\n    );\n  });\n}\n\nexport class SiblingError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'SiblingError';\n  }\n}\n\nfunction parseJson(name: string, run: SiblingRun): unknown {\n  try {\n    return JSON.parse(run.stdout);\n  } catch {\n    const said = (run.stderr.trim() || run.stdout.trim()).split('\\n').slice(0, 3).join(' ');\n    throw new SiblingError(`${name} exited ${run.code} without JSON${said ? `: ${said}` : ''}`);\n  }\n}\n\nexport interface Siblings {\n  readonly root: string;\n  locate(name: SiblingName): Sibling;\n  /** Every brief, live and archived. Exit 2 from spec-brief is an error here too. */\n  briefs(): Promise<BriefRow[]>;\n  /** A sibling's JSON output for a command line, with its exit code and what it said on stderr; `absent` says why it cannot be run, missing or outdated. */\n  json(name: SiblingName, args: readonly string[]): Promise<{ readonly code: number; readonly document: unknown; readonly stderr: string } | { readonly absent: string }>;\n}\n\n/** The siblings of the work tree at `root`, looked for in its install and then in each of `installs` (locate). */\nexport function createSiblings(root: string, config: HarnessConfig, installs: readonly string[] = []): Siblings {\n  const found = (name: SiblingName): readonly string[] => {\n    const sibling = locate(name, root, config, installs);\n    if (sibling.kind !== 'found') throw new SiblingError(sibling.reason);\n    return sibling.command;\n  };\n  return {\n    root,\n    locate: (name) => locate(name, root, config, installs),\n    async briefs() {\n      const run = await runSibling(found('spec-brief'), ['list', '--archived', '--format', 'json', '--no-color'], root);\n      if (run.code === 2) {\n        throw new SiblingError(`spec-brief could not list the briefs: ${run.stderr.trim().split('\\n')[0] || 'exit 2'}`);\n      }\n      try {\n        return parseBriefList(parseJson('spec-brief', run));\n      } catch (error) {\n        // parseJson throws a SiblingError, which this would copy, and\n        // parseBriefList nothing but its own: the check is equivalent to its\n        // mutant, and keeps any other error the stack trace it needs.\n        if (error instanceof SiblingOutputError) throw new SiblingError(error.message);\n        throw error;\n      }\n    },\n    async json(name, args) {\n      const sibling = locate(name, root, config, installs);\n      if (sibling.kind !== 'found') return { absent: sibling.reason };\n      const run = await runSibling(sibling.command, args, root);\n      return { code: run.code, document: parseJson(name, run), stderr: run.stderr };\n    },\n  };\n}\n"]}
+{"version":3,"file":"siblings.js","sourceRoot":"","sources":["../src/siblings.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The edge where the harness meets spec-brief, spec-graph and spec-guard.\n *\n * Through their command lines and their versioned JSON, never by importing\n * their packages: each is released, pinned and dropped on its own, and none\n * becomes a dependency of this one (spec-core ADR-0005, ADR-0002 here).\n *\n * A sibling is found as the repository installed it -\n * `node_modules/@descent-vtt/<name>/bin/<name>.js`, run with this Node - or\n * as `.spec-harness.json` names it. One that is not there is `absent`, and\n * what needed it says so; nothing it would have checked is reported clean.\n * One installed below this release's minimum is `outdated`, and is reported\n * the same way rather than run (versions.ts).\n */\n\nimport { execFile } from 'node:child_process';\nimport { existsSync, readFileSync } from 'node:fs';\nimport { join } from 'node:path';\n\nimport { inputsOf, parseBriefList, SiblingOutputError } from './briefs.js';\nimport type { HarnessConfig, SiblingName } from './config.js';\nimport { hasher, isFile, keepAnswer, keptAnswer, readsAsListed, type Hash } from './fs.js';\nimport { ANSWER_MS, stoppedAtLimit, timeFor, WORK_MS } from './git.js';\nimport type { BriefRow } from './types.js';\nimport { checkVersion } from './versions.js';\n\nexport interface SiblingRun {\n  readonly code: number;\n  readonly stdout: string;\n  readonly stderr: string;\n}\n\nexport type Sibling =\n  /**\n   * `version` is `null` for a command `.spec-harness.json` names, whose\n   * version is not checked. `elsewhere` is the directory whose install it\n   * is, where that is not the work tree's own.\n   */\n  | { readonly kind: 'found'; readonly command: readonly string[]; readonly version: string | null; readonly elsewhere?: string }\n  | { readonly kind: 'absent'; readonly reason: string }\n  /** Installed, at a version below the minimum or one that cannot be read, which is `null`. */\n  | { readonly kind: 'outdated'; readonly reason: string; readonly version: string | null; readonly elsewhere?: string };\n\n/**\n * Where a sibling is, or why it cannot be run. It is looked for in `root`'s\n * install, then in each of `installs` in turn, and the first that has it\n * decides, at this release's floor: a work tree with an install of its own\n * runs it, outdated or not, and one with none is checked with the\n * project's, as git's hook and Claude Code's are where a linked worktree has\n * none (ADR-0005).\n */\n// A name a mutant puts on the default list is a directory relative to where\n// the run is, which holds no install: equivalent, here and below.\nexport function locate(name: SiblingName, root: string, config: HarnessConfig, installs: readonly string[] = []): Sibling {\n  // A command the configuration names is run as named: which package it runs,\n  // and so which version, is the configuration's to say.\n  const configured = config.tools[name];\n  if (configured !== null) return { kind: 'found', command: configured, version: null };\n  for (const place of [root, ...installs]) {\n    const directory = join(place, 'node_modules', '@descent-vtt', name);\n    const bin = join(directory, 'bin', `${name}.js`);\n    if (!existsSync(bin)) continue;\n    const check = checkVersion(name, declaredVersion(join(directory, 'package.json')));\n    const where = place === root ? {} : { elsewhere: place };\n    if (!check.ok) return { kind: 'outdated', reason: check.reason, version: check.version, ...where };\n    return { kind: 'found', command: [process.execPath, bin], version: check.version, ...where };\n  }\n  return {\n    kind: 'absent',\n    reason: `${name} is not installed here: npm install --save-dev @descent-vtt/${name}, or name its command under \"tools\" in .spec-harness.json`,\n  };\n}\n\n/** The `version` a package.json declares, or `undefined` when there is no such file or it is not JSON. */\nexport function declaredVersion(file: string): unknown {\n  // Only a file is read: a named pipe under the name was read without end,\n  // and before any sibling ran (ADR-0002).\n  if (!isFile(file)) return undefined;\n  // A manifest that holds null throws on the read, and any other value that\n  // is not an object has no version, so the catch answers for both. Falling\n  // out of it answers undefined as well, and a Buffer parses as its text:\n  // the empty catch and the encoding are equivalent to their mutants.\n  try {\n    const manifest: { version?: unknown } = JSON.parse(readFileSync(file, 'utf8'));\n    return manifest.version;\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * Runs a sibling with arguments, in the repository root.\n *\n * Never through a shell: an argument is a path or a brief id, and a shell\n * would read it as syntax. `node` as a command's first word is this Node, so\n * `[\"node\", \"path/to/bin.js\"]` works on every host. A program that cannot be\n * started is answered on every host in one way, code -1 and a line that says\n * to name the tool's script: one not found, a script named without `node`,\n * a Windows `.cmd` shim such as `npx`, which cannot be started without a\n * shell, a directory or a file the account may not run.\n *\n * A sibling that does not answer within `limit` is stopped, and rejected as\n * a `SiblingError` that names it: what it was asked waits on it, the hook\n * before a write among them, which then holds the write (ADR-0002).\n */\nexport function runSibling(name: string, command: readonly string[], args: readonly string[], root: string, limit = WORK_MS): Promise<SiblingRun> {\n  const [first, ...rest] = command;\n  const program = first === 'node' ? process.execPath : (first as string);\n  const { ms, said } = timeFor(limit);\n  if (ms === 0) return Promise.reject(new SiblingError(`${name} was not started: ${said} had passed`));\n  const unstarted: SiblingRun = {\n    code: -1,\n    stdout: '',\n    stderr: `cannot start \"${first}\": name the tool's script, such as [\"node\", \"node_modules/@descent-vtt/<tool>/bin/<tool>.js\"]`,\n  };\n  return new Promise((resolve, reject) => {\n    try {\n      execFile(\n        program,\n        [...rest, ...args],\n        {\n          cwd: root,\n          maxBuffer: 256 * 1024 * 1024,\n          encoding: 'utf8',\n          // Keeps a console window from opening on Windows; the sweep runs on\n          // Linux, where the mutant is equivalent.\n          windowsHide: true,\n          timeout: ms,\n          shell: false,\n          env: { ...process.env, NO_COLOR: '1', FORCE_COLOR: '0' },\n        },\n        (error, stdout, stderr) => {\n          if (stoppedAtLimit(error)) {\n            reject(new SiblingError(`${name} did not answer within ${said}, and was stopped`));\n            return;\n          }\n          const failure = error as (Error & { code?: unknown; syscall?: unknown }) | null;\n          // Of what reaches here, only the error of a process that was never\n          // made names the system call that failed, `spawn` and the program:\n          // ENOENT, and on Linux and macOS EACCES for a directory or a file\n          // that may not be run. One that ran has its exit code, and one\n          // stopped at its limit was answered above.\n          if (failure !== null && typeof failure.syscall === 'string') {\n            resolve(unstarted);\n            return;\n          }\n          const code = failure === null ? 0 : typeof failure.code === 'number' ? failure.code : -1;\n          resolve({ code, stdout, stderr });\n        },\n      );\n    } catch {\n      // Some programs are refused before a process is made, and Node throws\n      // that rather than pass it to the callback: on Windows a script, as\n      // EFTYPE, and a `.cmd` or `.bat`, as EINVAL; on every host a NUL in a\n      // word of the command. The options are this function's own, so what\n      // execFile throws is a command it could not start.\n      resolve(unstarted);\n    }\n  });\n}\n\n/**\n * Where and under what a session's answer of spec-brief's is kept, or\n * `null` where none is. A command `tools` names is started every time:\n * which version it runs cannot be told without starting it.\n */\nasync function keeperOf(kept: Kept, root: string, sibling: Extract<Sibling, { kind: 'found' }>): Promise<{ readonly commonDir: string; readonly key: string; readonly name: string; readonly version: string; readonly hash: Hash } | null> {\n  // A command with no version is kept nothing by the test of the version an\n  // answer names, too: the mutant without this one reads, for every write, a\n  // kept answer there is none of, and is equivalent.\n  if (sibling.version === null) return null;\n  const hash = await hasher();\n  const key = answerKey(root, kept.session, sibling.command, sibling.version);\n  return { commonDir: kept.commonDir, key, name: `${hash(key)}.json`, version: sibling.version, hash };\n}\n\n/**\n * The briefs a kept answer gives, or `null` where it is not to be given:\n * nothing kept, or what was kept is not a list document that names what it\n * was read from in the version installed, or anything it names reads\n * otherwise.\n */\nasync function givenAgain(stdout: string | null, version: string, root: string, hash: Hash): Promise<BriefRow[] | null> {\n  // JSON.parse reads null as null, which names no inputs, and a null read\n  // past the test of none below throws, which answers null: the two tests\n  // are the compiler's, and their mutants equivalent.\n  if (stdout === null) return null;\n  try {\n    const document: unknown = JSON.parse(stdout);\n    const inputs = inputsOf(document);\n    if (inputs === null || inputs.tool !== version || !(await readsAsListed(root, inputs, hash))) return null;\n    return parseBriefList(document);\n  } catch {\n    // What another program wrote there is no answer of spec-brief's.\n    return null;\n  }\n}\n\nexport class SiblingError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'SiblingError';\n  }\n}\n\nfunction parseJson(name: string, run: SiblingRun): unknown {\n  try {\n    return JSON.parse(run.stdout);\n  } catch {\n    const said = (run.stderr.trim() || run.stdout.trim()).split('\\n').slice(0, 3).join(' ');\n    throw new SiblingError(`${name} exited ${run.code} without JSON${said ? `: ${said}` : ''}`);\n  }\n}\n\nexport interface Siblings {\n  readonly root: string;\n  locate(name: SiblingName): Sibling;\n  /**\n   * Every brief, live and archived. Exit 2 from spec-brief is an error here\n   * too, and so is a spec-brief that does not answer within `limit`, the\n   * time a question is given unless a caller gives another.\n   */\n  briefs(limit?: number): Promise<BriefRow[]>;\n  /**\n   * The same siblings, with spec-brief's list of the briefs kept for a\n   * session under the common directory and given again to that session's\n   * runs where every input it lists reads as listed (ADR-0002).\n   */\n  keeping(commonDir: string, session: string): Siblings;\n  /** A sibling's JSON output for a command line, with its exit code and what it said on stderr; `absent` says why it cannot be run, missing or outdated. */\n  json(name: SiblingName, args: readonly string[]): Promise<{ readonly code: number; readonly document: unknown; readonly stderr: string } | { readonly absent: string }>;\n}\n\n/** The command line spec-brief is asked for the briefs with. */\nconst LIST: readonly string[] = ['list', '--archived', '--format', 'json', '--no-color'];\n\n/**\n * The variables beyond git's own that an answer of spec-brief's can turn on\n * and its list does not name: which git and which Node run, where git finds\n * the person's configuration and ignore files, and how Node runs a script.\n * Every variable whose name begins `GIT_` is read with them.\n */\nconst ANSWER_VARIABLES: readonly string[] = ['PATH', 'HOME', 'USERPROFILE', 'HOMEDRIVE', 'HOMEPATH', 'XDG_CONFIG_HOME', 'NODE_OPTIONS', 'NODE_PATH'];\n\n/**\n * What a kept answer is the answer to: the work tree, the session, the\n * spec-brief that answered, by its command, its version and the Node it ran\n * on, the command line, and the variables above, as spec-brief is started\n * with them (runSibling). An answer is given again only for the same.\n */\nexport function answerKey(root: string, session: string, command: readonly string[], version: string, env: Readonly<Record<string, string | undefined>> = process.env): string {\n  const variables = Object.keys(env)\n    .filter((name) => /^GIT_/i.test(name) || ANSWER_VARIABLES.includes(name.toUpperCase()))\n    // One case for each name, whichever: the mutant that folds to the other is equivalent.\n    .map((name) => [name.toUpperCase(), env[name]])\n    .sort();\n  return JSON.stringify({ root, session, command, version, node: process.version, args: LIST, variables });\n}\n\n/** The siblings of the work tree at `root`, looked for in its install and then in each of `installs` (locate). */\nexport function createSiblings(root: string, config: HarnessConfig, installs: readonly string[] = []): Siblings {\n  return siblingsOf(root, config, installs, null);\n}\n\n/** Where a session's answers are kept, and which session's they are. */\ninterface Kept {\n  readonly commonDir: string;\n  readonly session: string;\n}\n\nfunction siblingsOf(root: string, config: HarnessConfig, installs: readonly string[], kept: Kept | null): Siblings {\n  return {\n    root,\n    locate: (name) => locate(name, root, config, installs),\n    async briefs(limit = ANSWER_MS) {\n      const sibling = locate('spec-brief', root, config, installs);\n      if (sibling.kind !== 'found') throw new SiblingError(sibling.reason);\n      const keeper = kept === null ? null : await keeperOf(kept, root, sibling);\n      if (keeper !== null) {\n        const again = await givenAgain(await keptAnswer(keeper.commonDir, keeper.name, keeper.key), keeper.version, root, keeper.hash);\n        if (again !== null) return again;\n      }\n      const run = await runSibling('spec-brief', sibling.command, LIST, root, limit);\n      if (run.code === 2) {\n        throw new SiblingError(`spec-brief could not list the briefs: ${run.stderr.trim().split('\\n')[0] || 'exit 2'}`);\n      }\n      let document: unknown;\n      let rows: BriefRow[];\n      try {\n        document = parseJson('spec-brief', run);\n        rows = parseBriefList(document);\n      } catch (error) {\n        // parseJson throws a SiblingError, which this would copy, and\n        // parseBriefList nothing but its own: the check is equivalent to its\n        // mutant, and keeps any other error the stack trace it needs.\n        if (error instanceof SiblingOutputError) throw new SiblingError(error.message);\n        throw error;\n      }\n      // Kept only where spec-brief said all was well and named what it read,\n      // in the version that answered: any other answer is read once.\n      if (keeper !== null && run.code === 0 && inputsOf(document)?.tool === keeper.version) {\n        await keepAnswer(keeper.commonDir, keeper.name, keeper.key, run.stdout);\n      }\n      return rows;\n    },\n    keeping: (commonDir, session) => siblingsOf(root, config, installs, { commonDir, session }),\n    async json(name, args) {\n      const sibling = locate(name, root, config, installs);\n      if (sibling.kind !== 'found') return { absent: sibling.reason };\n      const run = await runSibling(name, sibling.command, args, root);\n      return { code: run.code, document: parseJson(name, run), stderr: run.stderr };\n    },\n  };\n}\n"]}

package/dist/usage.d.ts

@@ -30,6 +30,9 @@ export interface CommandLine {
     readonly recommend: string | undefined;
     readonly show: string | undefined;
     readonly id: string | undefined;
+    /** Whether the line asks for the help, or for the version, which every command answers in place of running. */
+    readonly help: boolean;
+    readonly version: boolean;
 }
 /** Whether a value names nothing: empty, or only space. */
 export declare function isBlank(value: string): boolean;
@@ -77,6 +80,17 @@ declare const VALUED: {
         readonly says: "names no probe; give it a probe's id, or leave it out to run every probe";
     };
 };
+/**
+ * A resolved path with its drive letter in one case. On Windows a drive
+ * letter names its volume in either case, `D:\` and `d:\` alike (Microsoft's
+ * Naming Files, Paths, and Namespaces, Naming Conventions, read 2026-10-19),
+ * where Node's `resolve` keeps the case it was written in (spec-core
+ * ADR-0005, amended 2026-10-19). The rest of the path is left as it is: NTFS
+ * can be made to tell names apart by case, so whether two names are one
+ * directory is the disk's to say. A path resolved elsewhere starts with `/`,
+ * and has no drive letter to fold.
+ */
+export declare function foldDrive(path: string): string;
 /**
  * The first option that takes one value and was given two that read as two,
  * named with both as they were written; `null` where none was. The parser
@@ -203,7 +217,7 @@ declare const SHAPE: {
             readonly most: 0;
             readonly takes: "no argument";
         };
-        readonly options: readonly ["root", "format", "write", "git-hook"];
+        readonly options: readonly ["root", "format", "write", "git-hook", "block-on-failure"];
     };
     readonly mcp: {
         readonly limit: {
@@ -230,7 +244,7 @@ export type Command = keyof typeof SHAPE;
  * every release, which this one cannot rewrite, and exit 2 from it holds
  * every write of a session, the write that would fix the line among them.
  * A line the parser cannot read is asked the same, and the hook says it
- * with exit 1 (cli.ts).
+ * to the person with exit 0 (cli.ts).
  */
 export declare function isClaudeHook(command: string | undefined, argument: string | undefined): boolean;
 /** The words for a `--root` that is a file, or is not there, wherever it is said. */
@@ -244,7 +258,7 @@ export interface LineFault {
  * What Claude Code's hook does with its own line, as far as the line decides
  * it: it guards, in the root the line gives it where it gives one and under
  * the brief it names where it names one; or the guard is off, for a fault
- * the hook says with exit 1 and holds no write for; or every write is held,
+ * the hook says with exit 0 and holds no write for; or every write is held,
  * exit 2, for a brief the line names that is not one (ADR-0005). The hook
  * reads its line through the functions below, and `doctor` reads a line it
  * finds in Claude Code's settings through the same ones, so what it says of
@@ -284,9 +298,9 @@ export interface GuardOff {
     readonly state: 'off';
     readonly fault: LineFault;
     /**
-     * Set where the hook says nothing of the fault and exits 0, so that no
-     * run of it fails: a root outside any work tree, or in a work tree that
-     * does not hold the project. Every other fault it says, with exit 1.
+     * Set where the hook says nothing of the fault: a root outside any work
+     * tree, or in a work tree that does not hold the project. Every other
+     * fault it says, to the person, and every one with exit 0.
      */
     readonly silent?: true;
     /**
@@ -326,6 +340,25 @@ export declare function unreadHookLine(said: string): GuardOff;
  * someone had configured was off.
  */
 export declare function readHookLine(root: string | undefined, cwd: string, isDirectory: (path: string) => boolean): Guards | GuardOff;
+/**
+ * What `--help` or `--version` on the hook's line stands beside that the
+ * hook would say as it runs, in the words for a line it cannot read; `null`
+ * where the line asks for neither, or stands beside nothing the line itself
+ * shows to be wrong. Every command answers either before it runs, so the
+ * hook printed the help over a root that is not a directory, exit 0, and
+ * said nothing of it (ADR-0005). A fault only git or spec-brief can tell
+ * stays unsaid: neither is asked before an answer that runs nothing.
+ */
+export declare function answerBeside(line: Pick<CommandLine, 'help' | 'version' | 'root'>, cwd: string, isDirectory: (path: string) => boolean): string | null;
+/**
+ * A line of the hook's that asks for the help or the version, which the hook
+ * prints, exit 0, in place of reading its question: no write is checked
+ * under it, and Claude Code, by its hooks reference, writes what a hook
+ * that exits 0 prints to its debug log, so nothing says the guard is off
+ * (ADR-0005). The hook says nothing of it, since a person who asks the hook
+ * for its help at a terminal is answered the same way.
+ */
+export declare function answeringHookLine(asked: 'help' | 'version'): GuardOff;
 /**
  * A line whose root is a directory outside any git work tree. The hook
  * reads that as a session outside one, where it has nothing to guard: it
@@ -367,7 +400,9 @@ export declare function holderHookLine(line: Guards, tree: OtherTree, path: stri
  * every write under one that names no brief, which only spec-brief can tell.
  * A line with two values for an option that takes one is a line the hook
  * cannot read, whichever option it is, read from `cwd` as the hook reads it
- * from where it is started (cli.ts).
+ * from where it is started (cli.ts). So is one with the help or the version
+ * beside a root that is not a directory; and with either beside nothing it
+ * can see is wrong, the line checks no write, whatever else it holds.
  */
 export declare function claudeHookLine(words: readonly string[], parse: (argv: readonly string[]) => CommandLine, cwd: string, isDirectory: (path: string) => boolean): HookLine | null;
 /**

package/dist/usage.js

@@ -44,19 +44,33 @@ const VALUED = literal({
     show: { of: every('show'), says: 'names no escalation; give it an id, as spec-harness escalate --list prints them' },
     id: { of: every('id'), says: "names no probe; give it a probe's id, or leave it out to run every probe" },
 });
+/**
+ * A resolved path with its drive letter in one case. On Windows a drive
+ * letter names its volume in either case, `D:\` and `d:\` alike (Microsoft's
+ * Naming Files, Paths, and Namespaces, Naming Conventions, read 2026-10-19),
+ * where Node's `resolve` keeps the case it was written in (spec-core
+ * ADR-0005, amended 2026-10-19). The rest of the path is left as it is: NTFS
+ * can be made to tell names apart by case, so whether two names are one
+ * directory is the disk's to say. A path resolved elsewhere starts with `/`,
+ * and has no drive letter to fold.
+ */
+export function foldDrive(path) {
+    return /^[a-z]:/.test(path) ? `${path[0].toUpperCase()}${path.slice(1)}` : path;
+}
 /**
  * Whether two values of an option that takes one ask for one thing, as the
  * option reads them: a brief by its id as spec-brief's names are matched,
  * space around it dropped and `12` the brief `012` (ADR-0004); a root by the
  * directory it names from `cwd`, the one an empty root names on the hook's
- * line among them; any other as it is written, since each is read so, a
- * format, a probe's position, an id or text.
+ * line among them, with a drive letter in either case; any other as it is
+ * written, since each is read so, a format, a probe's position, an id or
+ * text.
  */
 function asksOne(option, first, other, cwd) {
     if (option === 'brief')
         return sameId(first.trim(), other.trim());
     if (option === 'root')
-        return resolve(cwd, first) === resolve(cwd, other);
+        return foldDrive(resolve(cwd, first)) === foldDrive(resolve(cwd, other));
     return first === other;
 }
 /**
@@ -125,7 +139,7 @@ const SHAPE = literal({
     audit: { options: ['brief', 'base', 'root', 'format', 'strict'], ...ONE_BRIEF },
     probe: { options: ['brief', 'base', 'root', 'format', 'id', 'at'], ...ONE_BRIEF },
     premises: { options: ['brief', 'root', 'format', 'strict'], ...NO_ARGUMENT },
-    init: { options: ['root', 'format', 'write', 'git-hook'], ...NO_ARGUMENT },
+    init: { options: ['root', 'format', 'write', 'git-hook', 'block-on-failure'], ...NO_ARGUMENT },
     mcp: { options: ['root'], ...NO_ARGUMENT },
     // A diagnosis says what is wrong with what it was given, where a command
     // that acts on it stops: a brief or a base that names nothing is a line of
@@ -151,7 +165,7 @@ function listed(options) {
  * every release, which this one cannot rewrite, and exit 2 from it holds
  * every write of a session, the write that would fix the line among them.
  * A line the parser cannot read is asked the same, and the hook says it
- * with exit 1 (cli.ts).
+ * to the person with exit 0 (cli.ts).
  */
 export function isClaudeHook(command, argument) {
     return command === 'hook' && argument === 'claude';
@@ -199,6 +213,42 @@ export function readHookLine(root, cwd, isDirectory) {
     }
     return { state: 'guards', root: given };
 }
+/**
+ * What `--help` or `--version` on the hook's line stands beside that the
+ * hook would say as it runs, in the words for a line it cannot read; `null`
+ * where the line asks for neither, or stands beside nothing the line itself
+ * shows to be wrong. Every command answers either before it runs, so the
+ * hook printed the help over a root that is not a directory, exit 0, and
+ * said nothing of it (ADR-0005). A fault only git or spec-brief can tell
+ * stays unsaid: neither is asked before an answer that runs nothing.
+ */
+export function answerBeside(line, cwd, isDirectory) {
+    if (!line.help && !line.version)
+        return null;
+    const read = readHookLine(line.root, cwd, isDirectory);
+    if (read.state === 'guards')
+        return null;
+    const asked = line.help ? 'help' : 'version';
+    return `--${asked} is given beside a fault, ${read.fault.wrong}, and the ${asked} would be printed in its place`;
+}
+/**
+ * A line of the hook's that asks for the help or the version, which the hook
+ * prints, exit 0, in place of reading its question: no write is checked
+ * under it, and Claude Code, by its hooks reference, writes what a hook
+ * that exits 0 prints to its debug log, so nothing says the guard is off
+ * (ADR-0005). The hook says nothing of it, since a person who asks the hook
+ * for its help at a terminal is answered the same way.
+ */
+export function answeringHookLine(asked) {
+    return {
+        state: 'off',
+        silent: true,
+        fault: {
+            wrong: `the line asks for the ${asked}, which the hook prints, exit 0, in place of checking the write`,
+            mend: 'take that option off the line, where init writes "hook claude" and nothing after it',
+        },
+    };
+}
 /**
  * A line whose root is a directory outside any git work tree. The hook
  * reads that as a session outside one, where it has nothing to guard: it
@@ -261,7 +311,9 @@ export function holderHookLine(line, tree, path) {
  * every write under one that names no brief, which only spec-brief can tell.
  * A line with two values for an option that takes one is a line the hook
  * cannot read, whichever option it is, read from `cwd` as the hook reads it
- * from where it is started (cli.ts).
+ * from where it is started (cli.ts). So is one with the help or the version
+ * beside a root that is not a directory; and with either beside nothing it
+ * can see is wrong, the line checks no write, whatever else it holds.
  */
 export function claudeHookLine(words, parse, cwd, isDirectory) {
     let line;
@@ -277,6 +329,13 @@ export function claudeHookLine(words, parse, cwd, isDirectory) {
     const twice = twoValues(line, cwd);
     if (twice !== null)
         return unreadHookLine(twice);
+    const beside = answerBeside(line, cwd, isDirectory);
+    if (beside !== null)
+        return unreadHookLine(beside);
+    if (line.help)
+        return answeringHookLine('help');
+    if (line.version)
+        return answeringHookLine('version');
     const read = readHookLine(line.root, cwd, isDirectory);
     return read.state === 'guards' && line.brief !== undefined && !isBlank(line.brief) ? { ...read, brief: line.brief } : read;
 }