@holmes-lab/holmes-kit 0.23.3 → 0.24.0

package/CHANGELOG.md

@@ -5,6 +5,47 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 <!-- @implements A-SPEC-209 -->
+## [0.24.0] - 2026-09-19
+
+A way for a consumer's defect to reach us, and two rules that existed only in prose.
+
+### Added
+- **`holmes-kit report`** (A-SPEC-675, A-SPEC-676, A-SPEC-679, A-SPEC-680). A consumer project had no channel by which a
+  holmes-kit defect could reach us: the one field defect we knew about arrived because a user pasted
+  a transcript, and it had reproduced for every consumer on every slice. The command writes a
+  **redacted** report to `.ax/reports/<fingerprint>.md` and prints a prefilled GitHub issue link —
+  carrying the title, the repository owner as assignee, and the body — plus a search link for the
+  same fingerprint so a duplicate is visible before filing. `--open` opens it; a headless box, an SSH
+  session or CI simply keeps the printed link. **No token, no API, no automatic submission**: the
+  person presses Submit on GitHub's own page with the body visible and editable, which puts consent
+  where the bytes are. Redaction is an **allowlist**, not a scrubber, because a denylist has been
+  punctured here before; the machine's hostname, username, home directory and replica ids are
+  searched for in the composed body by the pins themselves. A spec id passes by shape and a spec
+  TITLE does not — that is unreleased product intent. Observations take numbers only.
+  What holmes-kit cannot know, it says: no ledger keeps the product's refusal text, so a run without
+  `--message` writes the report, states that no description was given, explains why it cannot be
+  recovered, and exits non-zero rather than handing a maintainer a version string.
+- **A stale graph analysis is visible** (A-SPEC-681). The Stop hook's tracked channel reports source
+  changed with no `maintenance_analyze` standing open. Measured here: the procedure had been skipped
+  for seventeen consecutive commits, and the one run that followed found child-process precedents a
+  name search had missed entirely. Non-blocking, silent in a workspace that never analysed anything,
+  and judged by commit rather than by clock.
+
+### Fixed
+- **The workspace registry no longer fills with dead temp directories** (A-SPEC-677, 678). Measured:
+  603 entries, 458 (76%) pointing at paths that no longer existed and 599 of them temp directories —
+  **three** were real projects. `upgrade` believed the list: it would print 458 skip lines and then
+  run `runInit({force:true})` against 142 abandoned temp directories, writing wiring files into them.
+  A temp target is now never recorded, and recording prunes what has vanished. The pruning is
+  deliberately asymmetric: a vanished temp path is gone by construction, while a vanished normal path
+  may be an unmounted volume, so it is counted and kept — `upgrade` already skips it harmlessly, and
+  deleting it is the one outcome a user cannot undo.
+- **Tests can no longer write into the developer's real registry** (A-SPEC-678). That is how 599 of
+  those entries arrived. Inside jest, `process.env` is a sandbox copy, so setting `HOME` never
+  reaches `setenv` and `os.homedir()` keeps answering the real home — an in-process test cannot
+  isolate a module that calls it directly. `HOLMES_HOME` is the seam; consumers set nothing and
+  behaviour is unchanged for them.
+
 ## [0.23.3] - 2026-09-18
 
 A suite that takes half as long, a build that admits when it is stale, and a CI matrix that stopped

package/README.md

@@ -16,6 +16,8 @@
 
 ### 🛡️ Currently Supported Features (Production Features)
 
+- 📮 **`holmes-kit report` — a defect can reach the maintainers** *(new in 0.24.0)*: until now a consumer's holmes-kit defect had no way back to us; the one we learned about arrived because someone pasted a transcript, and it had been reproducing for every consumer on every slice. The command writes a **redacted** report to `.ax/reports/<fingerprint>.md` and prints a prefilled GitHub issue link — title, assignee, body — plus a search link for the same fingerprint so you can see whether it is already known. `--open` opens it; on a headless box or over SSH the printed link is the whole of it. **No token, no API, nothing sent automatically**: you press Submit on GitHub's own page with the body in front of you and editable. Redaction is an allowlist rather than a scrubber — this project's own remote carries a token before the `@`, its replica ids carry a person's name, and its spec titles are unreleased product intent, so a path, a credential or a machine identifier withholds the field and the report says which. A spec id passes by shape; a spec title does not. And what holmes-kit cannot know, it says: no ledger keeps its own refusal text, so a report with no description states that rather than pretending.
+- 🧭 **A skipped graph analysis is visible** *(new in 0.24.0)*: `AGENTS.md` asks for `maintenance_analyze` before editing source, and nothing checked. Measured on this repository, the step had been skipped for seventeen consecutive commits — and the run that followed named child-process precedents a name search had missed completely, because the question was "who opens a browser" while the answer lived under "who spawns a child". The Stop hook now reports source changed with no analysis standing open: non-blocking, judged by commit rather than by clock, and silent in a workspace that never adopted the habit.
 - 🧱 **A stale build is told, not discovered** *(new in 0.23.3)*: thirty suites in this project load `dist/` while they run, and nothing asserted that it still represented the source — only the release gate compared the build id to HEAD, and only at publish time. A stale build does not go red; it verifies old code and returns green. The Stop hook now reports it on the non-blocking `tracked` channel, judged by the **build id and never by mtime**: measured here, `.build-id` had a newer mtime than every source file while naming a commit nine behind HEAD, with two changed sources missing from `dist` entirely. A workspace that does not build hears nothing, `fresh` says nothing, and the two states that cannot be judged say **that** rather than passing quietly.
 - 📐 **Declarations are read as written** *(new in 0.23.2)*: `Files to Touch` is where a spec declares the files it will touch, and three things read it — fulfilment advisories, the declaration census and the approval impact note. The parser took only the **first word of a list item**, so measured over 678 approved specs here, **88 specs and 172 paths were declared and never read**; 24 of them parsed to zero while naming files plainly. Several paths on one line, an indented continuation, a Korean first word, a prose paragraph — all invisible. They are read now, wherever they sit, and a bare `name.ext` keeps its old position rule so a property access like `module.exports` is still not a file. A declared path that does not exist but is the suffix of exactly one repository file is reported as an abbreviation rather than a defect; two candidates stays an ambiguity and nothing is guessed. Cost, measured across the whole corpus: **zero** new `missing` findings.
 - 📄 **The publish gate reads the docs** *(new in 0.23.2)*: the publish playbook has demanded "bring README and CHANGELOG up to this release" since 0.16.0 and only prose enforced it, so it failed four times — including 0.21.0, 0.22.0 and 0.23.0, which each shipped with a feature list frozen at 0.20.0. The release gate now refuses two things it can decide: a missing CHANGELOG entry for the version being published, and an entry with `### Added` while `README.md` has not changed since the previous release. Replayed over eight releases it refuses exactly the three that were stale and passes the other five. What needs judgement — is the old wording still true? — stays with the person and is **reported**, never faked; a check that could not run says so instead of reading as a pass.

package/dist/.build-id

@@ -1 +1 @@
-970ee6cf-mu6tt9oo
+d23fd983-mu76a9wy

package/dist/holmes/cli/index.js

@@ -234,6 +234,8 @@ const USAGE = `holmes-kit — deterministic ASE governance for a project
                              Setting the key is consent to egress (spec prose, paths, symbol names sent externally).
 
   holmes-kit doctor [flags]    diagnose the install
+  holmes-kit report --message "<what happened>" [--harness <name>]
+                               write a redacted field report and print a prefilled issue link
     --target <dir>             also verify that target's wiring points at this install
     --json                     machine-readable output
 
@@ -347,6 +349,33 @@ async function main(argv) {
             return r.exitCode;
         });
     }
+    // @implements A-SPEC-679 — the surface that calls the report composer. Nothing here reaches the
+    // network: it writes a file and prints links, and a person decides whether to open them.
+    if (cmd === 'report') {
+        const { runReport } = require('./report');
+        const { machineIdentity } = require('../project/field-report');
+        const os3 = require('node:os');
+        const mIdx = argv.indexOf('--message');
+        const message = mIdx >= 0 ? argv[mIdx + 1] : undefined;
+        const reported = runReport({ message, open: argv.includes('--open'), root: process.cwd(), packageRoot: packageRoot(), harness: (() => { const i = argv.indexOf('--harness'); return i >= 0 ? argv[i + 1] : undefined; })() }, {
+            write: (p2, c) => fs.writeFileSync(p2, c),
+            mkdir: (p2) => { fs.mkdirSync(p2, { recursive: true }); },
+            stdout: (t) => process.stdout.write(t),
+            readFile: (p2) => fs.readFileSync(p2, 'utf8'),
+            now: () => new Date(),
+            identity: machineIdentity({ hostname: os3.hostname(), username: os3.userInfo().username, homedir: os3.homedir() }),
+        });
+        // @implements A-SPEC-680 — the flag now does what it says. Failing to open is the NORMAL case on
+        // a headless box and never changes the report's own exit code: the URL is already on stdout.
+        if (argv.includes('--open')) {
+            const { openUrl } = require('./open-url');
+            const { spawn } = require('node:child_process');
+            const opened = openUrl(reported.url, process.platform, (f, a, o) => spawn(f, a, o).unref());
+            process.stdout.write(opened ? '\nopened in your browser — press Submit there.\n'
+                : '\ncould not open a browser here; the link above is the whole of it.\n');
+        }
+        return reported.code;
+    }
     if (cmd === 'doctor') {
         // A nonexistent target read as "healthy but unwired" and both advised remedies then refused it
         // (round-6) — the typo is the diagnosis, so say it.
@@ -1183,7 +1212,18 @@ async function main(argv) {
                             return '';
                         }
                     })();
-                    recordWorkspace(os2.homedir(), { target: opts.target, agents: [...agents], version: pkgVersion, ts: new Date().toISOString() });
+                    // @implements A-SPEC-677 — the recorder prunes what has vanished while it is already here.
+                    // A deletion the user cannot see is a deletion they cannot check, so the count is printed.
+                    // @implements A-SPEC-678 — the seam a test can reach; consumers set nothing and get homedir().
+                    const { holmesHome } = require('../update/workspaces');
+                    recordWorkspace(holmesHome(process.env, os2.homedir()), { target: opts.target, agents: [...agents], version: pkgVersion, ts: new Date().toISOString() }, {
+                        read: (p2) => fs.readFileSync(p2, 'utf8'),
+                        write: (p2, c) => fs.writeFileSync(p2, c),
+                        mkdir: (p2) => { fs.mkdirSync(p2, { recursive: true }); },
+                        exists: (p2) => fs.existsSync(p2),
+                        tmpdir: () => os2.tmpdir(),
+                        onPrune: (n) => process.stdout.write(`  registry: dropped ${n} workspace entr${n === 1 ? 'y' : 'ies'} whose temporary path no longer exists\n`),
+                    });
                 }
                 catch { /* registry failure never fails init */ }
             }

package/dist/holmes/cli/open-url.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Opening a URL in whatever the operating system calls a browser.
+ *
+ * `report --open` used to parse the flag and do nothing: A-SPEC-679 said "opening is left to the
+ * caller" and that caller was never written. A flag accepted and ignored is worse than no flag —
+ * the user believes the browser opened and walks away. This repository has the lesson on file as
+ * "left as an integration point means dead".
+ *
+ * Judgement is separated from doing so all three platforms can be pinned from one machine. Wiring
+ * being present has never been the same thing as wiring that works.
+ *
+ * NO SHELL. The URL carries `&` and `#`, and a shell would split the command at them; it goes in as
+ * a single argument, which is the same discipline `Supervisor.spawnChild` and doctor's spawn checks
+ * already follow here.
+ */
+export interface OpenCommand {
+    file: string;
+    args: string[];
+}
+export type SpawnLike = (file: string, args: string[], opts: Record<string, unknown>) => unknown;
+/** `null` when the platform cannot be judged: not opening is better than guessing a command. */
+export declare function openCommand(platform: string): OpenCommand | null;
+/**
+ * True only when the spawn was actually attempted and did not throw.
+ *
+ * A missing browser is the NORMAL case on a headless box, an SSH session or CI. It costs the user
+ * nothing — the URL is already on stdout — so it returns false rather than throwing, and the
+ * caller's exit code does not change.
+ */
+export declare function openUrl(url: string, platform: string, spawn: SpawnLike): boolean;

package/dist/holmes/cli/open-url.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openCommand = openCommand;
+exports.openUrl = openUrl;
+/** `null` when the platform cannot be judged: not opening is better than guessing a command. */
+function openCommand(platform) {
+    if (typeof platform !== 'string' || platform.trim() === '')
+        return null;
+    if (platform === 'darwin')
+        return { file: 'open', args: [] };
+    // `start` reads its first quoted argument as the WINDOW TITLE, so a URL passed without the empty
+    // title becomes a title and nothing opens.
+    if (platform === 'win32')
+        return { file: 'cmd', args: ['/c', 'start', ''] };
+    return { file: 'xdg-open', args: [] };
+}
+/**
+ * True only when the spawn was actually attempted and did not throw.
+ *
+ * A missing browser is the NORMAL case on a headless box, an SSH session or CI. It costs the user
+ * nothing — the URL is already on stdout — so it returns false rather than throwing, and the
+ * caller's exit code does not change.
+ */
+function openUrl(url, platform, spawn) {
+    if (typeof url !== 'string' || url.trim() === '')
+        return false;
+    const cmd = openCommand(platform);
+    if (!cmd)
+        return false;
+    try {
+        // detached + ignored stdio: the browser outlives this process and never holds the terminal.
+        spawn(cmd.file, [...cmd.args, url], { detached: true, stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/holmes/cli/report.d.ts

@@ -0,0 +1,20 @@
+export interface ReportOptions {
+    message?: string;
+    open?: boolean;
+    root: string;
+    packageRoot: string;
+    harness?: string;
+}
+export interface ReportIo {
+    write(p: string, c: string): void;
+    mkdir(p: string): void;
+    stdout(s: string): void;
+    readFile(p: string): string;
+    now(): Date;
+    /** Strings that identify this machine or person, injected so a pin can search for them. */
+    identity: string[];
+}
+export declare function runReport(o: ReportOptions, io: ReportIo): {
+    code: number;
+    url: string;
+};

package/dist/holmes/cli/report.js

@@ -0,0 +1,115 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runReport = runReport;
+// @implements A-SPEC-679
+/**
+ * `holmes-kit report` — the surface that finally calls the report composer.
+ *
+ * Two measurements decided what this command can honestly claim. No ledger keeps the product's
+ * refusal text: it is returned to the caller and vanishes, so holmes-kit cannot know what went
+ * wrong. And a report assembled from only what IS auto-fillable — version, harness, OS, node, a
+ * spec id out of a ledger — cannot be triaged; a maintainer receives a version string and a
+ * fingerprint.
+ *
+ * So the human's one sentence IS the report, and everything here is context wrapped around it. That
+ * is still worth having: a pasted transcript leaks paths, spec titles and commit messages and can
+ * never be deduplicated, while this carries a redacted context and a fingerprint that recognises
+ * the same defect reported by someone else.
+ *
+ * Nothing here reaches the network. Opening a browser is the caller's act, which keeps this module
+ * pure enough to pin and keeps "going out" a decision a person makes.
+ */
+const path = __importStar(require("node:path"));
+const field_report_1 = require("../project/field-report");
+const field_report_url_1 = require("../project/field-report-url");
+const reported_log_1 = require("./reported-log");
+/** `unknown` rather than an empty string: a blank version reads as a version we know to be blank. */
+const versionOf = (io, packageRoot) => {
+    try {
+        return String(JSON.parse(io.readFile(path.join(packageRoot, 'package.json'))).version ?? 'unknown');
+    }
+    catch {
+        return 'unknown';
+    }
+};
+function runReport(o, io) {
+    const described = typeof o.message === 'string' && o.message.trim() !== '';
+    const report = (0, field_report_1.composeFieldReport)({
+        kit: versionOf(io, o.packageRoot),
+        harness: o.harness ?? 'unknown',
+        os: process.platform,
+        arch: process.arch,
+        node: process.version,
+        ...(described ? { message: o.message.trim() } : {}),
+        identity: io.identity,
+    });
+    let body = (0, field_report_1.fieldReportBody)(report);
+    if (!described) {
+        // Incomplete, not failed. A quiet empty report hands a maintainer a version string and calls it
+        // a bug report; saying so is the difference between a report and a shrug.
+        body += '\n\nno description was given — rerun with `--message "<what happened>"`; holmes-kit cannot'
+            + ' recover what it said to you, because no ledger keeps its refusal text.';
+    }
+    const dir = path.join(o.root, '.ax', 'reports');
+    const file = path.join(dir, `${report.fingerprint}.md`);
+    io.mkdir(dir);
+    io.write(file, `${body}\n`);
+    // @implements A-SPEC-679 — leave the fingerprint of THIS report, so a future briefing can match it.
+    // Best-effort: a log problem must never fail the report it accompanies.
+    try {
+        const logFile = path.join(dir, 'reported.jsonl');
+        let prior = null;
+        try {
+            prior = io.readFile(logFile);
+        }
+        catch {
+            prior = null;
+        }
+        io.write(logFile, (0, reported_log_1.mergeReported)(prior, { fingerprint: report.fingerprint, kit: report.kit, ts: io.now().toISOString() }).lines);
+    }
+    catch { /* the report itself still stands */ }
+    const url = (0, field_report_url_1.issueUrl)(body, { localPath: file, title: (0, field_report_url_1.issueTitle)(report), assignee: field_report_url_1.ISSUE_ASSIGNEE });
+    io.stdout(`report written: ${file}\n`);
+    io.stdout(`\nopen this to file it (you press Submit, and you can edit the body first):\n${url.url}\n`);
+    io.stdout(`\ncheck whether it is already known:\n${(0, field_report_url_1.searchUrl)(report.fingerprint)}\n`);
+    if (url.truncated)
+        io.stdout('\n(the URL body was truncated; the file above holds the whole report)\n');
+    if (!described)
+        io.stdout('\nno description was given — this report says so rather than pretending.\n');
+    // @implements A-SPEC-680 — the URL is returned rather than rebuilt by the caller: two places
+    // composing it would drift, and the caller needs the exact bytes it printed.
+    return { code: described ? 0 : 2, url: url.url };
+}

package/dist/holmes/cli/reported-log.d.ts

@@ -0,0 +1,23 @@
+/**
+ * What this machine has reported — a SET of fingerprints, not a history.
+ *
+ * It exists for a briefing that does not exist yet: "the thing you reported is fixed in 0.24.0".
+ * That can only work if the fingerprint from the MOMENT of reporting is on disk, because a
+ * fingerprint is derived from content and recomputing one later can disagree — redaction may
+ * withhold a different field next time. A line costs nothing now; without it such a briefing would
+ * stay silent about every report made before it shipped.
+ *
+ * A set rather than a log because the question is "what have I reported", not "when". Reporting the
+ * same defect twice adds nothing.
+ *
+ * Local only. Nothing here sends anything anywhere.
+ */
+export interface ReportedEntry {
+    fingerprint: string;
+    kit: string;
+    ts: string;
+}
+export declare function mergeReported(existing: string | null, entry: ReportedEntry): {
+    lines: string;
+    added: boolean;
+};

package/dist/holmes/cli/reported-log.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mergeReported = mergeReported;
+function mergeReported(existing, entry) {
+    const kept = [];
+    const seen = new Set();
+    for (const line of (existing ?? '').split('\n')) {
+        const t = line.trim();
+        if (t === '')
+            continue;
+        try {
+            const row = JSON.parse(t);
+            // A row that cannot name a fingerprint cannot answer the question this file exists for.
+            if (typeof row.fingerprint !== 'string' || row.fingerprint === '')
+                continue;
+            if (seen.has(row.fingerprint))
+                continue;
+            seen.add(row.fingerprint);
+            kept.push({ fingerprint: row.fingerprint, kit: String(row.kit ?? ''), ts: String(row.ts ?? '') });
+        }
+        catch {
+            // A torn line is dropped, never fatal: a broken log must not fail the report it accompanies,
+            // the same best-effort rule the workspace registry states for itself.
+            continue;
+        }
+    }
+    const added = !seen.has(entry.fingerprint);
+    if (added)
+        kept.push(entry);
+    return { lines: `${kept.map((e) => JSON.stringify(e)).join('\n')}\n`, added };
+}

package/dist/holmes/hooks/stop.d.ts

@@ -4,7 +4,9 @@ import type { TestOutcome } from '../review/test-runner';
 import { type KnownDefectJudgement } from '../rtm/known-defects';
 import { type CiVerdict } from '../project/ci-runs';
 import { type DistVerdict } from '../project/dist-freshness';
+import { type AnalysisVerdict } from '../project/analysis-currency';
 export declare function collectKnownDefects(root: string, now: Date): KnownDefectJudgement | undefined;
+export declare function collectAnalysisCurrency(root: string, changedSources: number): AnalysisVerdict | undefined;
 export declare function collectDistFreshness(root: string): DistVerdict | undefined;
 export declare function collectCiVerdicts(root: string, now?: Date): CiVerdict[];
 /**
@@ -45,6 +47,11 @@ export interface StopEvidence {
      * does not build at all; a `no-build-id`/`unknown` verdict when it looked and could not judge.
      */
     dist?: DistVerdict;
+    /**
+     * @implements A-SPEC-681 — whether the graph analysis AGENTS.md asks for was run before this
+     * turn's source edits. Absent when the workspace never analysed anything.
+     */
+    analysis?: AnalysisVerdict;
     /** Provenance-chain verification result (CLI-supplied). A broken chain blocks the stop. */
     provenance?: {
         ok: boolean;

package/dist/holmes/hooks/stop.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MAX_CONSECUTIVE_BLOCKS = void 0;
 exports.collectKnownDefects = collectKnownDefects;
+exports.collectAnalysisCurrency = collectAnalysisCurrency;
 exports.collectDistFreshness = collectDistFreshness;
 exports.collectCiVerdicts = collectCiVerdicts;
 exports.changedAnchoredAspecs = changedAnchoredAspecs;
@@ -85,6 +86,7 @@ const known_defects_1 = require("../rtm/known-defects");
 const test_files_1 = require("../cpg/test-files");
 const ci_runs_1 = require("../project/ci-runs");
 const dist_freshness_1 = require("../project/dist-freshness");
+const analysis_currency_1 = require("../project/analysis-currency");
 // @implements A-SPEC-660 — the I/O half of the known-defect marker: walk the workspace's test files
 // (the same directory rule and test predicate ART-4's anchor scan uses), parse each for markers,
 // judge them against the injected clock. A walk that cannot START is NO SIGNAL (undefined) — never
@@ -132,6 +134,22 @@ function collectKnownDefects(root, now) {
         return undefined;
     }
 }
+// @implements A-SPEC-681 — the I/O half of the analysis line: count the analyses still open against
+// the source files this turn changed. A workspace that never analysed anything did not adopt the
+// discipline and hears nothing; a count that cannot be taken says so rather than passing.
+function collectAnalysisCurrency(root, changedSources) {
+    if (!(0, analysis_currency_1.hasAnalysisDir)(root))
+        return undefined;
+    let openAnalyses = null;
+    try {
+        const { openArtifacts } = require('../mcp/maintenance-evidence');
+        openAnalyses = openArtifacts(path.join(root, '.ax', 'evidence', 'maintenance')).length;
+    }
+    catch {
+        openAnalyses = null;
+    }
+    return (0, analysis_currency_1.analysisCurrency)({ adopted: true, openAnalyses, changedSources });
+}
 // @implements A-SPEC-673 — the I/O half of the build-freshness line: read `dist/.build-id` and ask
 // git how far that commit sits behind HEAD. A workspace that does not build hears nothing; a build
 // that cannot be judged says so rather than passing quietly.
@@ -560,6 +578,7 @@ const TRACK_LABELS = {
     'ART-9': 'known-defect debt',
     'CI': 'matrix',
     'DIST': 'build freshness',
+    'ANALYSIS': 'graph analysis',
 };
 /**
  * One line per ARTICLE, each under its own name.
@@ -641,6 +660,13 @@ function evaluateStop(specs, evidence) {
         if (detail)
             tracked = [...(tracked ?? []), { article: 'DIST', detail }];
     }
+    // @implements A-SPEC-681 — AGENTS.md step 3 asks for a graph analysis before editing source, and
+    // nothing enforced it: seventeen feat/fix commits ran without one. Observed here, never blocked.
+    if (evidence?.analysis) {
+        const detail = (0, analysis_currency_1.analysisStatusLine)(evidence.analysis);
+        if (detail)
+            tracked = [...(tracked ?? []), { article: 'ANALYSIS', detail }];
+    }
     const problems = violations.map((x) => `[${x.article}] ${x.detail}`);
     // @implements A-SPEC-247 — structured list so the caller can ask acknowledgeStop which of these
     // are waiting on an owner. Mirrors `problems` exactly, including the two synthesized below.
@@ -1241,7 +1267,15 @@ if (require.main === module) {
             catch {
                 dist = undefined;
             }
-            let out = evaluateStop(specs, { testCasesByAspec, provenance, executedByAspec, findings, findingsUnreadable, unanchoredChangedSources: unanchored, unrecordedApprovals: unrecorded, rolledBackLedgers: rolledBack, redFirstMode, changedAspecs, outcomesByAspec, ...(knownDefects ? { knownDefects } : {}), ...(ci ? { ci } : {}), ...(dist ? { dist } : {}) });
+            // @implements A-SPEC-681 — the analysis line rides the same non-blocking channel.
+            let analysis;
+            try {
+                analysis = collectAnalysisCurrency(stopProjectRoot(), (unanchored ?? []).length);
+            }
+            catch {
+                analysis = undefined;
+            }
+            let out = evaluateStop(specs, { testCasesByAspec, provenance, executedByAspec, findings, findingsUnreadable, unanchoredChangedSources: unanchored, unrecordedApprovals: unrecorded, rolledBackLedgers: rolledBack, redFirstMode, changedAspecs, outcomesByAspec, ...(knownDefects ? { knownDefects } : {}), ...(ci ? { ci } : {}), ...(dist ? { dist } : {}), ...(analysis ? { analysis } : {}) });
             // @implements A-SPEC-534.4 — track mode records ART-8 findings without blocking: surface them so
             // the operator observes RED-first gaps before an owner promotes the posture to strict.
             // @implements A-SPEC-559.2 — spec-evolution trigger (observe-first, NEVER blocks): a dirty

package/dist/holmes/project/analysis-currency.d.ts

@@ -0,0 +1,22 @@
+export type AnalysisState = 'analysed' | 'missing' | 'not-adopted' | 'unknown';
+export interface AnalysisVerdict {
+    state: AnalysisState;
+    openCount: number | null;
+    changedSources: number;
+}
+export interface AnalysisInput {
+    adopted: boolean;
+    openAnalyses: number | null;
+    changedSources: number;
+}
+/** Adoption is the directory's existence. A project that never analysed anything did not opt in. */
+export declare function hasAnalysisDir(root: string): boolean;
+/**
+ * Judged by COMMIT, never by clock. "An analysis within N hours" is an invented constant that turns
+ * a slow slice into a violation; what matters is whether an analysis stands open for the work that
+ * changed these files, which is exactly what `test_run` closes when it reconciles a persisted
+ * analysis against the files a slice actually touched.
+ */
+export declare function analysisCurrency(input: AnalysisInput): AnalysisVerdict;
+/** Empty when there is nothing to say; the two unjudgeable states say so rather than passing. */
+export declare function analysisStatusLine(v: AnalysisVerdict): string;

package/dist/holmes/project/analysis-currency.js

@@ -0,0 +1,96 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasAnalysisDir = hasAnalysisDir;
+exports.analysisCurrency = analysisCurrency;
+exports.analysisStatusLine = analysisStatusLine;
+// @implements A-SPEC-681
+/**
+ * Whether the graph analysis this project's own instructions require was actually run.
+ *
+ * `AGENTS.md` step 3 asks for `maintenance_analyze({persist:true})` before editing source, and
+ * nothing enforced it: measured 2026-09-19, the last persisted analysis was at 10:52 the previous
+ * day and seventeen feat/fix commits followed it with none. A user had to point at the gap.
+ *
+ * The cost was concrete. Searching for the precedent for spawning a browser, grep returned a CSS
+ * class named 'open', a d3 'start' event and a schema enum; the analysis returned `wiringSpawnCheck`
+ * and `Supervisor.spawnChild`. The question was "who opens a browser" and the answer lived under
+ * "who spawns a child" — a gap lexical search cannot cross and the graph does not notice.
+ *
+ * This OBSERVES. It does not block, and it never runs the tool on the operator's behalf: analysis is
+ * expensive and what to ask is a person's judgement.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+/** Adoption is the directory's existence. A project that never analysed anything did not opt in. */
+function hasAnalysisDir(root) {
+    try {
+        return fs.statSync(path.join(root, '.ax', 'evidence', 'maintenance')).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Judged by COMMIT, never by clock. "An analysis within N hours" is an invented constant that turns
+ * a slow slice into a violation; what matters is whether an analysis stands open for the work that
+ * changed these files, which is exactly what `test_run` closes when it reconciles a persisted
+ * analysis against the files a slice actually touched.
+ */
+function analysisCurrency(input) {
+    const changedSources = typeof input.changedSources === 'number' && Number.isFinite(input.changedSources)
+        ? Math.max(0, input.changedSources) : 0;
+    const open = input.openAnalyses;
+    const base = { openCount: typeof open === 'number' && Number.isFinite(open) ? open : null, changedSources };
+    if (!input.adopted)
+        return { state: 'not-adopted', ...base };
+    // The discipline is about editing source. Nothing changed, nothing to say.
+    if (changedSources === 0)
+        return { state: 'analysed', ...base };
+    if (typeof open !== 'number' || !Number.isFinite(open) || open < 0)
+        return { state: 'unknown', ...base };
+    return { state: open > 0 ? 'analysed' : 'missing', ...base };
+}
+/** Empty when there is nothing to say; the two unjudgeable states say so rather than passing. */
+function analysisStatusLine(v) {
+    if (v.state === 'analysed' || v.state === 'not-adopted')
+        return '';
+    if (v.state === 'unknown') {
+        return 'the persisted analyses could not be counted — whether this change was analysed could not be judged';
+    }
+    const n = v.changedSources;
+    return `${n} source file${n === 1 ? '' : 's'} changed with no analysis standing open — `
+        + 'AGENTS.md step 3 asks for `maintenance_analyze({ persist: true })` first; it finds precedents a name search cannot reach';
+}

package/dist/holmes/project/field-report-url.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The report's way to us: a PREFILLED GitHub issue URL that a person submits on GitHub's own page.
+ *
+ * The alternative — holmes-kit holding a token and posting through the API — was rejected for a
+ * measured reason, not a stylistic one. Consent is the weakest link here: the first field report of
+ * the approval queue counted 1,412 unique requests against 8 decisions, 99.4% undecided. A yes/no
+ * buried in a stream of prompts is not a decision, and a user consents to "report this" without
+ * reading forty lines of body.
+ *
+ * A URL moves the decision to where the bytes are visible. The person sees the whole body in
+ * GitHub's own editor, can change it, and cancelling costs nothing — closing the tab is the entire
+ * undo. Four consequences follow structurally rather than by discipline: no token exists to leak,
+ * nothing can be sent silently, there is no auth/rate-limit/retry surface, and this module cannot
+ * exfiltrate anything because it has no transport at all. It only builds strings.
+ */
+import type { FieldReport } from './field-report';
+export declare const ISSUE_REPO = "holmes-kit/holmes-kit";
+/** Conservative: GitHub accepts more, but a URL that silently fails to open helps nobody. */
+export declare const URL_BUDGET = 8000;
+/**
+ * The repository owner, offered as the default assignee.
+ *
+ * KNOWN LIMIT, stated rather than implied: GitHub honours `assignee=` only when the person filling
+ * the form may assign (write or triage on the repo). A third-party reporter usually cannot, and the
+ * parameter is then dropped silently. It costs nothing either way — it routes when it can and is
+ * discarded when it cannot — but it is not a guarantee, and nobody should plan triage around it.
+ */
+export declare const ISSUE_ASSIGNEE = "sungnamparkkorea-arch";
+export interface UrlOptions {
+    repo?: string;
+    localPath?: string;
+    budget?: number;
+    title?: string;
+    assignee?: string | null;
+}
+/**
+ * The fingerprint rides in the title so a person scanning the issue list recognises a duplicate
+ * without opening anything. The MESSAGE deliberately does not: a title is the most visible place in
+ * the tracker, and `message` is the one allowlisted field whose VALUE can be withheld as unsafe.
+ */
+export declare function issueTitle(r: FieldReport): string;
+export declare function issueUrl(body: string, opts?: UrlOptions): {
+    url: string;
+    truncated: boolean;
+};
+/** Empty in, empty out: a query with no fingerprint lists every issue, which is not a duplicate check. */
+export declare function searchUrl(fingerprint: string, opts?: UrlOptions): string;

package/dist/holmes/project/field-report-url.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ISSUE_ASSIGNEE = exports.URL_BUDGET = exports.ISSUE_REPO = void 0;
+exports.issueTitle = issueTitle;
+exports.issueUrl = issueUrl;
+exports.searchUrl = searchUrl;
+exports.ISSUE_REPO = 'holmes-kit/holmes-kit';
+/** Conservative: GitHub accepts more, but a URL that silently fails to open helps nobody. */
+exports.URL_BUDGET = 8000;
+/**
+ * The repository owner, offered as the default assignee.
+ *
+ * KNOWN LIMIT, stated rather than implied: GitHub honours `assignee=` only when the person filling
+ * the form may assign (write or triage on the repo). A third-party reporter usually cannot, and the
+ * parameter is then dropped silently. It costs nothing either way — it routes when it can and is
+ * discarded when it cannot — but it is not a guarantee, and nobody should plan triage around it.
+ */
+exports.ISSUE_ASSIGNEE = 'sungnamparkkorea-arch';
+/**
+ * The fingerprint rides in the title so a person scanning the issue list recognises a duplicate
+ * without opening anything. The MESSAGE deliberately does not: a title is the most visible place in
+ * the tracker, and `message` is the one allowlisted field whose VALUE can be withheld as unsafe.
+ */
+function issueTitle(r) {
+    const what = r.article || r.tool || 'report';
+    return `holmes-kit ${r.kit}: ${what} (${r.fingerprint.slice(0, 8)})`;
+}
+const NOTE = (localPath) => localPath
+    ? `\n\n— truncated to fit the URL; the full report is at ${localPath}`
+    : '\n\n— truncated to fit the URL; the full report stayed on the reporter\'s machine';
+function issueUrl(body, opts = {}) {
+    const repo = opts.repo ?? exports.ISSUE_REPO;
+    const budget = opts.budget ?? exports.URL_BUDGET;
+    // The title goes in the URL, not just into a helper nobody calls. It was missing here for a
+    // slice: `issueTitle` existed, a pin called it directly, and the product path built `?body=`
+    // alone — so GitHub opened with a blank title. A function pinned in isolation says nothing about
+    // the path that is supposed to feed it.
+    const titlePart = opts.title && opts.title.trim() !== '' ? `title=${encodeURIComponent(opts.title)}&` : '';
+    // Omitted rather than emptied when absent: a fork or an internal mirror must not point at someone
+    // else's account, and `assignee=` with nothing after it is noise in the form.
+    const assigneePart = typeof opts.assignee === 'string' && opts.assignee.trim() !== ''
+        ? `assignee=${encodeURIComponent(opts.assignee.trim())}&` : '';
+    const base = `https://github.com/${repo}/issues/new?${titlePart}${assigneePart}body=`;
+    const build = (text) => base + encodeURIComponent(text);
+    const whole = build(body);
+    if (whole.length <= budget)
+        return { url: whole, truncated: false };
+    // Never a silent cut: the note is part of the body that gets sent, so the reader of the ISSUE — not
+    // just the reporter — learns that something was left out.
+    const note = NOTE(opts.localPath);
+    let keep = body.length;
+    while (keep > 0 && build(body.slice(0, keep) + note).length > budget) {
+        keep = Math.floor(keep * 0.9);
+    }
+    return { url: build(body.slice(0, keep) + note), truncated: true };
+}
+/** Empty in, empty out: a query with no fingerprint lists every issue, which is not a duplicate check. */
+function searchUrl(fingerprint, opts = {}) {
+    if (typeof fingerprint !== 'string' || fingerprint.trim() === '')
+        return '';
+    const repo = opts.repo ?? exports.ISSUE_REPO;
+    return `https://github.com/${repo}/issues?q=${encodeURIComponent(`is:issue ${fingerprint.trim()}`)}`;
+}

package/dist/holmes/project/field-report.d.ts

@@ -0,0 +1,54 @@
+/** The only keys a report may carry. Adding one is an edit here, which the pin makes visible. */
+export declare const FIELD_REPORT_KEYS: readonly ["kit", "harness", "os", "arch", "node", "message", "article", "tool", "specIds", "observations", "fingerprint", "withheld"];
+export interface FieldReportInput {
+    kit: string;
+    harness: string;
+    os: string;
+    arch: string;
+    node: string;
+    message?: string;
+    article?: string;
+    tool?: string;
+    specIds?: string[];
+    observations?: Array<{
+        label: string;
+        value: number;
+    }>;
+    /** Strings that identify this machine or person, injected by the caller so a pin can search for them. */
+    identity?: string[];
+}
+export interface FieldReport {
+    kit: string;
+    harness: string;
+    os: string;
+    arch: string;
+    node: string;
+    message: string;
+    article: string;
+    tool: string;
+    specIds: string[];
+    observations: Array<{
+        label: string;
+        value: number;
+    }>;
+    fingerprint: string;
+    withheld: string[];
+}
+/**
+ * Injected rather than read from `os` here, so a pin can search a composed body for THIS machine's
+ * real values. A module that reads the environment itself can only be tested against fixtures, and
+ * fixtures are exactly what a redaction pin must not trust.
+ *
+ * Tokens shorter than two characters are dropped: a one-character identity would redact every
+ * sentence, which is destruction rather than redaction.
+ */
+export declare function machineIdentity(env: {
+    hostname?: string;
+    username?: string;
+    homedir?: string;
+    replicas?: string[];
+}): string[];
+export declare function isSafeValue(text: string, identity: string[]): boolean;
+export declare function composeFieldReport(input: FieldReportInput): FieldReport;
+/** The bytes a human will read and paste. Anything withheld is named, never dropped in silence. */
+export declare function fieldReportBody(r: FieldReport): string;

package/dist/holmes/project/field-report.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FIELD_REPORT_KEYS = void 0;
+exports.machineIdentity = machineIdentity;
+exports.isSafeValue = isSafeValue;
+exports.composeFieldReport = composeFieldReport;
+exports.fieldReportBody = fieldReportBody;
+// @implements A-SPEC-675
+/**
+ * A field report: what a consumer workspace may tell us about a holmes-kit defect.
+ *
+ * There is no channel today. The one field defect we know about — REQ-671, where the AGENTS.md we
+ * ship told agents to author specs with four tools and none of them can write a section body —
+ * reached us because a user pasted a transcript. It reproduced for every consumer on every slice.
+ *
+ * What may be sent is decided by an ALLOWLIST, never by scrubbing. This repository has already been
+ * punctured by a denylist once (the secret-free path rule, holed by UNC paths), and the hazards here
+ * are measured rather than imagined: its replica ids carry a person's name, its homedir carries the
+ * OS username, and its git remote carries a forty-character token before the `@`. That last one is
+ * why an ALLOWED FIELD can still hold a dangerous VALUE — hence two layers, shape and content.
+ *
+ * It never guesses a cause. This module carries what was OBSERVED and leaves the diagnosis to a
+ * person: in one session here, four instrument failures and three confident wrong conclusions were
+ * caught only by re-measuring, and an issue tracker full of confident auto-diagnoses costs a
+ * maintainer more than an empty one.
+ */
+const advisory_outcomes_1 = require("../rtm/advisory-outcomes");
+/** The only keys a report may carry. Adding one is an edit here, which the pin makes visible. */
+exports.FIELD_REPORT_KEYS = ['kit', 'harness', 'os', 'arch', 'node', 'message',
+    'article', 'tool', 'specIds', 'observations', 'fingerprint', 'withheld'];
+/**
+ * Injected rather than read from `os` here, so a pin can search a composed body for THIS machine's
+ * real values. A module that reads the environment itself can only be tested against fixtures, and
+ * fixtures are exactly what a redaction pin must not trust.
+ *
+ * Tokens shorter than two characters are dropped: a one-character identity would redact every
+ * sentence, which is destruction rather than redaction.
+ */
+function machineIdentity(env) {
+    const raw = [env.hostname, env.username, env.homedir, ...(env.replicas ?? [])];
+    return [...new Set(raw.filter((s) => typeof s === 'string' && s.trim().length >= 2).map((s) => s.trim()))];
+}
+const ABSOLUTE_PATH = /(^|[\s"'`(])(\/(?:Users|home|root|var|opt|private)\/|[A-Za-z]:[\\/])/;
+/** `user@host` with a long opaque user is how this repository's own remote carries its token. */
+const CREDENTIAL = /[A-Za-z0-9_.-]{8,}@[A-Za-z0-9.-]+/;
+function isSafeValue(text, identity) {
+    if (typeof text !== 'string' || text === '')
+        return true;
+    if (ABSOLUTE_PATH.test(text) || CREDENTIAL.test(text))
+        return false;
+    const lower = text.toLowerCase();
+    return !identity.some((id) => id.length >= 2 && lower.includes(id.toLowerCase()));
+}
+/** Ids only. A spec TITLE is unreleased product intent and must not ride in on the id field. */
+const SPEC_ID = /^(?:REQ|H-SPEC|A-SPEC|T-SPEC|C-SPEC)-\d+(?:\.\d+)?$/;
+function composeFieldReport(input) {
+    const identity = input.identity ?? [];
+    const withheld = [];
+    const guard = (name, value) => {
+        const v = value ?? '';
+        if (v === '')
+            return '';
+        if (isSafeValue(v, identity))
+            return v;
+        withheld.push(name);
+        return '';
+    };
+    const message = guard('message', input.message);
+    const article = guard('article', input.article);
+    const tool = guard('tool', input.tool);
+    const specIds = (input.specIds ?? []).filter((s) => typeof s === 'string' && SPEC_ID.test(s));
+    // Numbers only: prose in a measurement's place is how a narrative smuggles itself past the
+    // allowlist, and the reports worth having in this repository were always numbers.
+    const observations = (input.observations ?? []).filter((o) => o && typeof o.label === 'string'
+        && typeof o.value === 'number' && Number.isFinite(o.value) && isSafeValue(o.label, identity));
+    const fingerprint = (0, advisory_outcomes_1.advisoryId)('field-report', article || tool || 'unknown', { kit: input.kit, harness: input.harness, os: input.os, message, article, tool, specIds });
+    return {
+        kit: input.kit, harness: input.harness, os: input.os, arch: input.arch, node: input.node,
+        message, article, tool, specIds, observations, fingerprint, withheld,
+    };
+}
+/** The bytes a human will read and paste. Anything withheld is named, never dropped in silence. */
+function fieldReportBody(r) {
+    const lines = [
+        `holmes-kit ${r.kit} · ${r.harness} · ${r.os}/${r.arch} · node ${r.node}`,
+        '',
+        `fingerprint: ${r.fingerprint}`,
+    ];
+    if (r.article)
+        lines.push(`article: ${r.article}`);
+    if (r.tool)
+        lines.push(`tool: ${r.tool}`);
+    if (r.specIds.length > 0)
+        lines.push(`specs: ${r.specIds.join(', ')}`);
+    if (r.message)
+        lines.push('', 'what holmes-kit said:', '', '> ' + r.message);
+    if (r.observations.length > 0) {
+        lines.push('', 'observed:');
+        for (const o of r.observations)
+            lines.push(`- ${o.label}: ${o.value}`);
+    }
+    if (r.withheld.length > 0) {
+        lines.push('', `withheld (contained a path, a credential or a machine identifier): ${r.withheld.join(', ')}`);
+    }
+    lines.push('', 'This report states what was observed. It does not diagnose a cause.');
+    return lines.join('\n');
+}

package/dist/holmes/update/workspaces.d.ts

@@ -9,6 +9,20 @@ export interface Registry {
     version: 1;
     workspaces: WorkspaceEntry[];
 }
+/**
+ * @implements A-SPEC-678
+ * Where the registry lives — with one seam a test can reach.
+ *
+ * Measured 2026-09-18: inside jest, `process.env` is a plain object copy in the sandbox, so
+ * assigning `HOME` never reaches `setenv` and `os.homedir()` keeps answering the developer's real
+ * home. Plain node follows `$HOME`; jest does not. An in-process test therefore cannot isolate a
+ * module that calls `os.homedir()` directly — which is how 599 of this machine's 603 registry
+ * entries came to be test temp directories.
+ *
+ * jest DOES control `process.env`, so one lookup there is the smallest seam that works. Consumers
+ * set nothing and get `os.homedir()`; an empty value is not a setting.
+ */
+export declare function holmesHome(env: NodeJS.ProcessEnv, fallback: string): string;
 export declare const EMPTY_REGISTRY: Registry;
 /**
  * @implements A-SPEC-543.1
@@ -28,8 +42,45 @@ export declare function mergeWorkspaceEntry(reg: Registry, entry: WorkspaceEntry
  * Thin best-effort recorder: read → merge → write `~/.holmes/workspaces.json`. Every failure is
  * swallowed (returns false) — a registry problem must never fail the init that feeds it.
  */
-export declare function recordWorkspace(home: string, entry: WorkspaceEntry, io?: {
+/**
+ * @implements A-SPEC-677 — the I/O a recorder needs. `exists` and `tmpdir` are injected so a pin can
+ * judge without depending on this machine's real paths.
+ */
+export interface RecordIo {
     read: (p: string) => string;
     write: (p: string, c: string) => void;
     mkdir: (p: string) => void;
-}): boolean;
+    exists?: (p: string) => boolean;
+    tmpdir?: () => string;
+    onPrune?: (dropped: number) => void;
+}
+/**
+ * @implements A-SPEC-677
+ * Whether a target lives under the OS temp root — and therefore is ephemeral by construction.
+ *
+ * macOS spells that root two ways: `os.tmpdir()` answers `/var/folders/...` while a realpath gives
+ * `/private/var/folders/...`. Both appear in this machine's registry, so both are judged. A `/tmp`
+ * literal would have missed all 599 of them.
+ *
+ * An empty root filters NOTHING. When the judgement cannot be made, keeping an entry costs a line
+ * and dropping one the user wanted costs them something they cannot get back.
+ */
+export declare function isTempTarget(target: string, tmpdir: string): boolean;
+/**
+ * @implements A-SPEC-677
+ * Drop what has certainly gone; COUNT what merely cannot be seen.
+ *
+ * The asymmetry is the whole judgement. A vanished temp path is gone by construction — nothing
+ * re-creates a `mkdtemp` directory. A vanished normal path may be an unmounted volume, an external
+ * disk or a network share, and `upgrade` already skips it harmlessly with one line. Deleting it is
+ * the one outcome the user cannot undo, so absence outside the temp root is reported, never acted on.
+ */
+export declare function pruneRegistry(reg: Registry, p: {
+    exists(t: string): boolean;
+    isTemp(t: string): boolean;
+}): {
+    registry: Registry;
+    dropped: number;
+    absent: number;
+};
+export declare function recordWorkspace(home: string, entry: WorkspaceEntry, io?: RecordIo): boolean;

package/dist/holmes/update/workspaces.js

@@ -34,12 +34,33 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EMPTY_REGISTRY = void 0;
+exports.holmesHome = holmesHome;
 exports.readRegistry = readRegistry;
 exports.mergeWorkspaceEntry = mergeWorkspaceEntry;
+exports.isTempTarget = isTempTarget;
+exports.pruneRegistry = pruneRegistry;
 exports.recordWorkspace = recordWorkspace;
 // @implements A-SPEC-543.1
 const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
+/**
+ * @implements A-SPEC-678
+ * Where the registry lives — with one seam a test can reach.
+ *
+ * Measured 2026-09-18: inside jest, `process.env` is a plain object copy in the sandbox, so
+ * assigning `HOME` never reaches `setenv` and `os.homedir()` keeps answering the developer's real
+ * home. Plain node follows `$HOME`; jest does not. An in-process test therefore cannot isolate a
+ * module that calls `os.homedir()` directly — which is how 599 of this machine's 603 registry
+ * entries came to be test temp directories.
+ *
+ * jest DOES control `process.env`, so one lookup there is the smallest seam that works. Consumers
+ * set nothing and get `os.homedir()`; an empty value is not a setting.
+ */
+function holmesHome(env, fallback) {
+    const override = env.HOLMES_HOME;
+    return typeof override === 'string' && override.trim() !== '' ? override : fallback;
+}
 exports.EMPTY_REGISTRY = { version: 1, workspaces: [] };
 /**
  * @implements A-SPEC-543.1
@@ -79,16 +100,59 @@ function mergeWorkspaceEntry(reg, entry) {
     };
 }
 /**
- * @implements A-SPEC-543.1
- * Thin best-effort recorder: read → merge → write `~/.holmes/workspaces.json`. Every failure is
- * swallowed (returns false) — a registry problem must never fail the init that feeds it.
+ * @implements A-SPEC-677
+ * Whether a target lives under the OS temp root — and therefore is ephemeral by construction.
+ *
+ * macOS spells that root two ways: `os.tmpdir()` answers `/var/folders/...` while a realpath gives
+ * `/private/var/folders/...`. Both appear in this machine's registry, so both are judged. A `/tmp`
+ * literal would have missed all 599 of them.
+ *
+ * An empty root filters NOTHING. When the judgement cannot be made, keeping an entry costs a line
+ * and dropping one the user wanted costs them something they cannot get back.
  */
+function isTempTarget(target, tmpdir) {
+    if (typeof target !== 'string' || typeof tmpdir !== 'string' || tmpdir.trim() === '')
+        return false;
+    const roots = new Set([tmpdir, tmpdir.startsWith('/private') ? tmpdir.slice('/private'.length) : `/private${tmpdir}`]);
+    return [...roots].some((r) => r !== '' && (target === r || target.startsWith(r.endsWith('/') ? r : `${r}/`)));
+}
+/**
+ * @implements A-SPEC-677
+ * Drop what has certainly gone; COUNT what merely cannot be seen.
+ *
+ * The asymmetry is the whole judgement. A vanished temp path is gone by construction — nothing
+ * re-creates a `mkdtemp` directory. A vanished normal path may be an unmounted volume, an external
+ * disk or a network share, and `upgrade` already skips it harmlessly with one line. Deleting it is
+ * the one outcome the user cannot undo, so absence outside the temp root is reported, never acted on.
+ */
+function pruneRegistry(reg, p) {
+    let dropped = 0, absent = 0;
+    const workspaces = reg.workspaces.filter((w) => {
+        if (p.exists(w.target))
+            return true;
+        if (p.isTemp(w.target)) {
+            dropped += 1;
+            return false;
+        }
+        absent += 1;
+        return true;
+    });
+    return { registry: { version: 1, workspaces }, dropped, absent };
+}
 function recordWorkspace(home, entry, io = {
     read: (p) => fs.readFileSync(p, 'utf8'),
     write: (p, c) => fs.writeFileSync(p, c),
     mkdir: (p) => { fs.mkdirSync(p, { recursive: true }); },
+    exists: (p) => fs.existsSync(p),
+    tmpdir: () => os.tmpdir(),
 }) {
     try {
+        // @implements A-SPEC-677 — an ephemeral target is not recorded at all. What never enters cannot
+        // pile up, and 599 of this machine's 603 entries entered exactly this way. Returning true is
+        // honest: nothing failed, there was simply nothing worth remembering.
+        const tmpdir = io.tmpdir?.() ?? '';
+        if (isTempTarget(entry.target, tmpdir))
+            return true;
         const dir = path.join(home, '.holmes');
         const file = path.join(dir, 'workspaces.json');
         let raw = null;
@@ -98,9 +162,18 @@ function recordWorkspace(home, entry, io = {
         catch {
             raw = null;
         }
-        const merged = mergeWorkspaceEntry(readRegistry(raw), entry);
+        const exists = io.exists;
+        // @implements A-SPEC-677 — prune while we are already here. Without an `exists` probe there is
+        // no way to tell gone from present, so the registry is merged unpruned rather than guessed at.
+        const base = exists
+            ? pruneRegistry(readRegistry(raw), { exists, isTemp: (t) => isTempTarget(t, tmpdir) })
+            : { registry: readRegistry(raw), dropped: 0, absent: 0 };
+        const merged = mergeWorkspaceEntry(base.registry, entry);
         io.mkdir(dir);
         io.write(file, `${JSON.stringify(merged, null, 2)}\n`);
+        // Never a silent deletion: whoever asked can learn how many entries went.
+        if (base.dropped > 0)
+            io.onPrune?.(base.dropped);
         return true;
     }
     catch {

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "@implements A-SPEC-209",
   "name": "@holmes-lab/holmes-kit",
-  "version": "0.23.3",
+  "version": "0.24.0",
   "description": "Holmes-Kit — deterministic Agentic Software Engineering (ASE) harness with causal traceability (spec chain + D-CPG + RTM + phase guardrail)",
   "main": "dist/holmes/mcp/server.js",
   "types": "dist/holmes/mcp/server.d.ts",