@holmes-lab/holmes-kit 0.23.2 → 0.24.0

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/semantic/credentials.js

@@ -37,6 +37,8 @@ exports.resolveSemanticKey = resolveSemanticKey;
 exports.storeSemanticKey = storeSemanticKey;
 exports.removeSemanticKey = removeSemanticKey;
 // @implements A-SPEC-592
+// @implements A-SPEC-549.4 — declared by that spec's Files to Touch and carries no Hangul; note that
+// the guard's own SOURCES list does not cover this file (reported, not fixed here).
 // @implements A-SPEC-477
 /**
  * The cloud tier's credential: WHERE the consent lives, and in what order it is looked up.

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.2",
+  "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",
@@ -62,7 +62,8 @@
     "testTimeout": 30000,
     "setupFilesAfterEnv": [
       "<rootDir>/src/holmes/test-support/jest-timeouts-setup.ts"
-    ]
+    ],
+    "maxWorkers": "50%"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",