@opengsd/gsd-core 1.10.0 → 1.12.0

package/gsd-core/bin/lib/runtime-identity.cjs

@@ -0,0 +1,234 @@
+"use strict";
+/**
+ * Runtime identity — prove which package's `gsd-tools` actually executed (#3146).
+ *
+ * The predecessor package `get-shit-done-cc` publishes a colliding `gsd-tools`
+ * bin (verified 2026-08-24 against 1.42.3: `bin.gsd-tools -> bin/gsd-sdk.js`),
+ * and exposes verbs of the same name with different semantics. #3129 is the
+ * worked example: `phases.clear` archives here and **deletes** there, and the
+ * output is success-shaped either way, so 43 phase directories went missing
+ * with no warning.
+ *
+ * That collision is now prevented in the resolver rather than detected here:
+ * the launcher's PATH branch resolves `gsd_run`, which only this package
+ * publishes and which self-locates to its sibling shim, so a foreign binary is
+ * unreachable from PATH. The path-based branches — a project-local install, a
+ * runtime config directory — have no such structural guarantee: they trust
+ * their configured location. #3841 closes that remaining route by making the
+ * launcher preamble PROBE the resolved tool once, before any verb runs, and
+ * warn when it cannot prove it is this package. This module backs both the
+ * `runtime-identity` verb the preamble calls and the vocabulary that gate
+ * reports in (`IDENTITY_STATUS`).
+ *
+ * The rollout is warn-then-fail (the #3146 maintainer ruling): the preamble
+ * prints one actionable line and proceeds. It cannot hard-fail yet because
+ * `no_identity_verb` does not distinguish a foreign package from an
+ * `@opengsd/gsd-core` older than the verb — and during rollout the old-version
+ * case is the common one, so a hard failure would stop working installs.
+ *
+ * Parsing is deliberately STRICT. The whole value of the check is telling "us"
+ * from "not us"; a lenient parse that accepts the predecessor's usage text as
+ * close-enough would reproduce the exact silent success #3129 already produced.
+ * Liberality is spent on visibility instead — distinct reason codes, each
+ * naming what actually happened.
+ *
+ * The classifier and the shell preamble are held in agreement by a
+ * cross-surface parity test (#3841): both read stdout only and must reach the
+ * same verdict for the same payload, or the preamble's warning and this
+ * module's diagnostic would silently diverge on the same input.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IDENTITY_RAW_PREFIX = exports.IDENTITY_STATUS = exports.EXPECTED_PACKAGE_NAME = void 0;
+exports.classifyIdentityProbe = classifyIdentityProbe;
+exports.statusForVerdict = statusForVerdict;
+exports.buildIdentityPayload = buildIdentityPayload;
+exports.explainVerdict = explainVerdict;
+exports.cmdRuntimeIdentity = cmdRuntimeIdentity;
+const package_identity_cjs_1 = require("./package-identity.cjs");
+const capability_loader_cjs_1 = require("./capability-loader.cjs");
+/** The package name a legitimate GSD runtime reports. Baked at build time (#498). */
+exports.EXPECTED_PACKAGE_NAME = package_identity_cjs_1.packageName;
+/**
+ * The two-valued status the launcher preamble exports as `GSD_IDENTITY_STATUS`
+ * (#3841). Frozen so it is a VALUE a test can assert on: CONTRIBUTING forbids
+ * proving the gate fired by matching its human-readable warning prose.
+ *
+ * Two values, not five: the shell has no use for the distinction between
+ * `no_identity_verb` and `unparseable` — it either holds proof or it does not.
+ * The five-way {@link IdentityReason} stays the diagnostic vocabulary;
+ * {@link statusForVerdict} is the only bridge between them.
+ */
+exports.IDENTITY_STATUS = Object.freeze({
+    OK: 'ok',
+    UNVERIFIED: 'unverified',
+});
+/**
+ * The exact byte prefix the preamble anchors its `case` pattern to.
+ *
+ * ANCHORED, never a substring search. `JSON.stringify` emits keys in insertion
+ * order and `buildIdentityPayload` inserts `packageName` first, so a genuine
+ * `--raw` payload always STARTS with this. An unanchored match would verify the
+ * decoy `{"packageName":"get-shit-done-cc","note":"@opengsd/gsd-core"}`, which
+ * is exactly the shape a colliding package could publish.
+ *
+ * The preamble anchors at BOTH ends: its `case` pattern is this prefix, then
+ * anything, then a literal `}`, so a truncated payload fails too. That is safe
+ * for any future additive field — a JSON object's own closing brace is always
+ * the last character, whatever the last value's type. It also pairs the literal
+ * `{` for the raw-text brace guards the preamble is inlined into (#3841); the
+ * pairing is a consequence of the stronger check, not the reason for it.
+ */
+exports.IDENTITY_RAW_PREFIX = `{"packageName":"${exports.EXPECTED_PACKAGE_NAME}"`;
+/** Cap on echoed probe output so a warning can never dump a whole usage screen. */
+const EVIDENCE_MAX_CHARS = 200;
+function excerpt(text) {
+    const flat = text.replace(/\s+/g, ' ').trim();
+    return flat.length > EVIDENCE_MAX_CHARS ? `${flat.slice(0, EVIDENCE_MAX_CHARS)}…` : flat;
+}
+/**
+ * `stdout` as a plain JSON object, or `null` when it is not one.
+ *
+ * `JSON.parse` accepts `0`, `"str"`, `[]`, `null` and `true`; arrays and `null`
+ * are also `object` to `typeof`. All are rejected here so no downstream
+ * truthiness check can mistake `[]` for a verified identity.
+ */
+function parseIdentityRecord(stdout) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        return null;
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+        return null;
+    return parsed;
+}
+/**
+ * Pure classifier: probe result -> verdict. Total — never throws, for any input.
+ *
+ * Non-object JSON (`0`, `"str"`, `[]`, `null`, `true`) is `unparseable`, not
+ * `ok` and not a crash: `JSON.parse` accepts all of them, so a naive truthiness
+ * check would let `[]` through as a verified identity.
+ */
+function classifyIdentityProbe(probe, expected = exports.EXPECTED_PACKAGE_NAME) {
+    if (probe.spawnFailed || probe.timedOut) {
+        return {
+            reason: 'probe_failed',
+            expected,
+            detail: probe.timedOut ? 'identity probe timed out' : 'identity probe could not be spawned',
+        };
+    }
+    // PARSE BEFORE CONSULTING THE EXIT CODE (#3841).
+    //
+    // The exit-code rule below is right for its stated reason -- the predecessor
+    // prints a usage screen and exits 1, and that is "something else answered",
+    // not a parse problem -- but it used to run FIRST, so it also caught a tool
+    // that had already proved its identity and merely exited non-zero afterwards.
+    // The shell preamble this module speaks for reads stdout ONLY (its command
+    // substitution discards the status), so the two surfaces disagreed on exactly
+    // that input: shell `ok`, classifier `no_identity_verb`. Measured against the
+    // real snippet, not inferred. Since this classifier is the engine for the
+    // announced hard-fail phase, such an install would have flipped from verified
+    // to refused at rollout, in the phase where that stops the run.
+    //
+    // The predecessor defence is unaffected: a usage screen yields no usable
+    // payload, so it still falls through to the exit-code branch below.
+    const record = parseIdentityRecord(probe.stdout);
+    if (record !== null) {
+        const actual = record.packageName;
+        if (typeof actual === 'string' && actual.length > 0) {
+            // Unknown keys are ignored so a future payload addition cannot fail an
+            // older check. The shell anchor is deliberately open in the middle for the
+            // same reason, and the parity suite pins both halves of that (case P10).
+            const version = typeof record.version === 'string' ? record.version : undefined;
+            if (actual !== expected)
+                return { reason: 'identity_mismatch', expected, actual, version };
+            // ANCHOR PARITY (#3841). The shell preamble cannot parse JSON: it matches
+            // a `case` pattern anchored at the START of stdout, so a payload only
+            // verifies there when it begins at the first byte and serializes
+            // `packageName` first. A purely structural parse would accept
+            // `{"note":"x","packageName":"<us>"}` and a leading-whitespace payload
+            // that the shell rejects -- a FAIL-OPEN disagreement between the two
+            // surfaces.
+            //
+            // Reproduce those two properties SEMANTICALLY rather than byte-matching
+            // IDENTITY_RAW_PREFIX. The prefix describes the `--raw` wire format, but
+            // this classifier is also handed the DEFAULT pretty serialization
+            // (`runtime-identity` with no `--raw`, which is two-space indented) --
+            // byte-matching the compact prefix rejected that, which the remote matrix
+            // caught. `startsWith('{')` and a first-key check hold for both.
+            const firstKey = Object.keys(record)[0];
+            if (!probe.stdout.startsWith('{') || firstKey !== 'packageName') {
+                return {
+                    reason: 'unparseable',
+                    expected,
+                    detail: 'payload names this package but is not in the anchored wire shape',
+                };
+            }
+            return { reason: 'ok', expected, actual, version };
+        }
+    }
+    // Nothing was proved. NOW the exit status is the discriminator: a non-zero
+    // exit means a binary that does not implement this verb answered.
+    if (probe.exitCode !== 0) {
+        return {
+            reason: 'no_identity_verb',
+            expected,
+            detail: `exit ${String(probe.exitCode)}: ${excerpt(probe.stdout)}`,
+        };
+    }
+    return {
+        reason: 'unparseable',
+        expected,
+        detail: record === null ? excerpt(probe.stdout) : 'payload has no usable packageName',
+    };
+}
+/**
+ * Collapse a five-way verdict onto the two-valued shell status.
+ *
+ * Total by construction: anything that is not `ok` is `unverified`. A future
+ * sixth reason code therefore fails CLOSED here rather than silently verifying.
+ */
+function statusForVerdict(verdict) {
+    return verdict.reason === 'ok' ? exports.IDENTITY_STATUS.OK : exports.IDENTITY_STATUS.UNVERIFIED;
+}
+/**
+ * Build this runtime's identity payload.
+ *
+ * Version is REPORTED but not asserted in the warn phase, so a dev tree
+ * reporting readHostVersion()'s fail-closed `0.0.0` still verifies. Carrying it
+ * now means the hard-fail phase can gate on compatibility without a payload
+ * change (and therefore without a second round of Hyrum's-Law exposure).
+ */
+function buildIdentityPayload(deps = {}) {
+    const readVersion = deps.readVersion ?? (() => (0, capability_loader_cjs_1.readHostVersion)());
+    const readName = deps.readPackageName ?? (() => exports.EXPECTED_PACKAGE_NAME);
+    return { packageName: readName(), version: readVersion() };
+}
+/** Render a verdict as the one-line actionable warning the preamble prints. */
+function explainVerdict(verdict, resolvedPath) {
+    const head = `WARNING: "${resolvedPath}" did not report a ${verdict.expected} identity.`;
+    const why = {
+        ok: 'identity verified',
+        identity_mismatch: `it reported "${verdict.actual ?? '(unknown)'}" instead`,
+        no_identity_verb: 'it does not implement the runtime-identity verb — either a different package, or a gsd-core predating the verb',
+        unparseable: 'its response could not be parsed as an identity payload',
+        probe_failed: 'the identity probe could not be run',
+    };
+    const tail = 'A workflow shipped by this package may be running against a different tool. ' +
+        'See docs/how-to/diagnose-a-foreign-gsd-tools.md';
+    const evidence = verdict.detail ? ` (${verdict.detail})` : '';
+    return `${head} Reason: ${why[verdict.reason]}${evidence}. ${tail}`;
+}
+/**
+ * CLI arm for `gsd-tools runtime-identity`.
+ *
+ * Kept on the CJS fast path for the same reason as `current-timestamp`: it is a
+ * pure local read, and the launcher preamble spawns it once per workflow run,
+ * so SDK bridge startup would be a per-run tax on every workflow.
+ */
+function cmdRuntimeIdentity(raw = false, deps = {}) {
+    const payload = buildIdentityPayload(deps);
+    process.stdout.write(`${JSON.stringify(payload, null, raw ? 0 : 2)}\n`);
+}

package/gsd-core/bin/lib/runtime-name-policy.cjs

@@ -193,7 +193,9 @@ exports.NO_LOCAL_CONFIG_DIR_SENTINEL = '(no-local-config-dir)';
  * Pure runtime-identity projection. Relocated from `bin/install.js` per
  * ADR-1508 (epic #1507, #1510 Phase 1) so the Runtime Artifact Conversion
  * Module's rewrite engine can consume it without importing the installer.
- * `bin/install.js` re-exports this same function for back-compat.
+ * Consumers import it from here. `bin/install.js` used to re-export it for
+ * back-compat; that re-export was retired in #2876, once an audit found the
+ * compatibility spine had no production consumer at all.
  */
 function getDirName(runtime) {
     if (!runtime)

package/gsd-core/bin/lib/runtime-slash.cjs

@@ -29,6 +29,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.formatGsdSlash = formatGsdSlash;
+exports.readInstallRuntimeMarker = readInstallRuntimeMarker;
+exports._setInstallRuntimeMarkerForTests = _setInstallRuntimeMarkerForTests;
+exports._resetInstallRuntimeMarkerCacheForTests = _resetInstallRuntimeMarkerCacheForTests;
+exports.resolveExplicitRuntime = resolveExplicitRuntime;
 exports.resolveRuntime = resolveRuntime;
 exports.formatGsdSlashFor = formatGsdSlashFor;
 const node_fs_1 = __importDefault(require("node:fs"));
@@ -74,20 +78,74 @@ function formatGsdSlash(commandName, runtime) {
     }
     return `/gsd-${token}${tail}`;
 }
+// ─── #3897 rung 2: the per-install `.gsd-runtime` marker, promoted from ──────
+// model-resolver.cts (#2297) to this module — the canonical owner of runtime
+// identity (resolveRuntime, formatGsdSlash). `bin/install.js` writes
+// `<install>/gsd-core/.gsd-runtime` beside VERSION for every runtime install
+// (#2297). This module compiles to `gsd-core/bin/lib/runtime-slash.cjs`
+// (ADR-457) — the SAME directory `model-resolver.cjs` compiles to — so the
+// `__dirname`-relative path below is unchanged from the promoted original.
+//
+// Cache + test-seam shape, byte-for-behaviour preserved from
+// model-resolver.cts:65-77 (N5): module-level `let`, `try/catch -> null`,
+// `_setInstallRuntimeMarkerForTests` / `_resetInstallRuntimeMarkerCacheForTests`.
+// `model-resolver.cts` now imports this implementation instead of holding its
+// own copy; the two `hooks/*.js` marker readers delegate here too (through
+// `ensureRuntimeBuild()`, per `scripts/lint-hooks-runtime-build-seam.cjs`).
+let _installMarkerCache;
 /**
- * Resolve the effective runtime for a project directory.
+ * Read the per-install runtime marker, cached for the process lifetime.
+ * Never throws (N4) — an absent/unreadable marker (dev/source tree, an
+ * install predating #2297, EACCES, hostile content, ...) is "no signal",
+ * never a resolution failure; a throw here would break a session in
+ * `gsd-agent-isolation-guard.js`, which is worse than resolving the wrong
+ * runtime.
+ *
+ * The raw marker string is returned as-is (trimmed) — callers MUST route it
+ * through `resolveRuntimeNameFromCandidates` before trusting it (N1); this
+ * function itself does not normalize so its cached value matches exactly
+ * what #2297's tests already assert about the underlying file read.
+ */
+function readInstallRuntimeMarker() {
+    if (_installMarkerCache !== undefined)
+        return _installMarkerCache;
+    try {
+        const markerPath = node_path_1.default.join(__dirname, '..', '..', '.gsd-runtime');
+        const raw = node_fs_1.default.readFileSync(markerPath, 'utf8').trim();
+        _installMarkerCache = raw || null;
+    }
+    catch {
+        // No marker: dev/source tree, or an install predating #2297. Fall through
+        // to the 'claude' default (keeps tier aliases — never worse than the bug).
+        _installMarkerCache = null;
+    }
+    return _installMarkerCache;
+}
+// Test seams for the install-marker rung (the dev/source tree has no marker,
+// so the file read always bottoms out at 'claude' — these let tests exercise
+// the third precedence rung and reset the module-level cache between cases).
+function _setInstallRuntimeMarkerForTests(value) {
+    _installMarkerCache = value;
+}
+function _resetInstallRuntimeMarkerCacheForTests() {
+    _installMarkerCache = undefined;
+}
+/**
+ * Resolve the explicit runtime for a project directory, from the two
+ * explicit sources only — no default is applied.
  *
- *   process.env.GSD_RUNTIME  >  config.runtime  >  'claude'
+ *   env.GSD_RUNTIME  >  config.runtime  >  null
  *
- * Mirrors the precedence already used by profile-output.cjs and the rest of
- * the runtime resolution chain. Returns a lowercased string so downstream
- * comparisons can be case-blind.
+ * Returns null when neither explicit source is set, so a caller can
+ * distinguish "config said claude" from "nothing was set" (needed by
+ * #3245's host-detection rung, which must only run when this returns null).
  *
  * @param projectDir - path to the project directory, or null/undefined
- * @returns the resolved runtime name
+ * @param env - environment variables to read GSD_RUNTIME from; defaults to process.env
+ * @returns the resolved runtime name, or null if neither source is set
  */
-function resolveRuntime(projectDir) {
-    const envRuntime = (0, runtime_name_policy_cjs_1.resolveRuntimeNameFromCandidates)(process.env['GSD_RUNTIME']);
+function resolveExplicitRuntime(projectDir, env = process.env) {
+    const envRuntime = (0, runtime_name_policy_cjs_1.resolveRuntimeNameFromCandidates)(env['GSD_RUNTIME']);
     if (envRuntime)
         return envRuntime;
     if (projectDir) {
@@ -113,6 +171,36 @@ function resolveRuntime(projectDir) {
             // runtime output formatting.
         }
     }
+    return null;
+}
+/**
+ * Resolve the effective runtime for a project directory.
+ *
+ *   process.env.GSD_RUNTIME  >  config.runtime  >  install marker  >  'claude'
+ *
+ * Mirrors the precedence already used by profile-output.cjs and the rest of
+ * the runtime resolution chain. Returns a lowercased string so downstream
+ * comparisons can be case-blind.
+ *
+ * #3897 rung 2: the per-install `.gsd-runtime` marker is the THIRD rung,
+ * between the two explicit sources and the 'claude' default — matching
+ * model-resolver.cts's own description of it as "the third precedence rung"
+ * before this reader was promoted here. The marker's raw contents are never
+ * trusted verbatim (N1): they are routed through the SAME
+ * `resolveRuntimeNameFromCandidates` normalization the env rung uses, so an
+ * unknown or hostile marker value degrades exactly like an unknown
+ * GSD_RUNTIME value would.
+ *
+ * @param projectDir - path to the project directory, or null/undefined
+ * @returns the resolved runtime name
+ */
+function resolveRuntime(projectDir) {
+    const explicit = resolveExplicitRuntime(projectDir);
+    if (explicit)
+        return explicit;
+    const markerRuntime = (0, runtime_name_policy_cjs_1.resolveRuntimeNameFromCandidates)(readInstallRuntimeMarker());
+    if (markerRuntime)
+        return markerRuntime;
     return 'claude';
 }
 /**

package/gsd-core/bin/lib/security.cjs

@@ -29,6 +29,7 @@ exports.requireSafePath = requireSafePath;
 exports.scanForInjection = scanForInjection;
 exports.sanitizeForPrompt = sanitizeForPrompt;
 exports.sanitizeForDisplay = sanitizeForDisplay;
+exports.sanitizeLabel = sanitizeLabel;
 exports.validateShellArg = validateShellArg;
 exports.safeJsonParse = safeJsonParse;
 exports.validatePhaseNumber = validatePhaseNumber;
@@ -73,13 +74,52 @@ function validatePath(filePath, baseDir, opts = {}) {
         resolvedPath = node_fs_1.default.realpathSync(resolvedPath);
     }
     catch {
-        const parentDir = node_path_1.default.dirname(resolvedPath);
+        // realpathSync failed — either resolvedPath doesn't exist at all, or it's
+        // a dangling symlink (the link itself exists but its target doesn't).
+        // lstat (unlike stat/realpath) stats the link itself and does NOT follow
+        // it, so it succeeds for a dangling symlink and throws ENOENT for a
+        // genuinely absent path. That's the discriminator: without it, a dangling
+        // symlink to a non-existent OUTSIDE path would fall through to the
+        // parent-resolution fallback below and be re-accepted as an in-project
+        // path, while a symlink to an EXISTING outside path is correctly
+        // rejected via the realpathSync success branch above — a state
+        // difference an attacker can use as an existence oracle for arbitrary
+        // absolute paths.
         try {
-            const realParent = node_fs_1.default.realpathSync(parentDir);
-            resolvedPath = node_path_1.default.join(realParent, node_path_1.default.basename(resolvedPath));
+            if (node_fs_1.default.lstatSync(resolvedPath).isSymbolicLink()) {
+                return { safe: false, resolved: '', error: 'Path is an unresolvable symbolic link' };
+            }
         }
         catch {
-            // Parent doesn't exist either — keep the resolved path as-is
+            // lstat also threw — resolvedPath (and its would-be link) genuinely
+            // doesn't exist. Fall through to ancestor resolution below.
+        }
+        // Walk up to the nearest ancestor that exists and realpath THAT, then
+        // re-append the remaining (not-yet-created) segments. This canonicalizes
+        // resolvedPath the same way resolvedBase was canonicalized above,
+        // regardless of how many leading directories are missing — a single
+        // parent-only check would leave resolvedPath un-canonicalized whenever
+        // the parent is also missing, which breaks the startsWith comparison
+        // below on any non-canonical cwd (e.g. macOS /var/... vs
+        // /private/var/...).
+        let ancestor = node_path_1.default.dirname(resolvedPath);
+        const remainder = [node_path_1.default.basename(resolvedPath)];
+        for (;;) {
+            try {
+                const realAncestor = node_fs_1.default.realpathSync(ancestor);
+                resolvedPath = node_path_1.default.join(realAncestor, ...remainder);
+                break;
+            }
+            catch {
+                const parent = node_path_1.default.dirname(ancestor);
+                if (parent === ancestor) {
+                    // Reached filesystem root without finding an existing ancestor —
+                    // keep resolvedPath as-is.
+                    break;
+                }
+                remainder.unshift(node_path_1.default.basename(ancestor));
+                ancestor = parent;
+            }
         }
     }
     const normalizedBase = resolvedBase + node_path_1.default.sep;
@@ -193,7 +233,7 @@ exports.INJECTION_PATTERNS = [
     /override\s+(system|previous)\s+(prompt|instructions)/i,
     // Role/identity manipulation
     /you\s+are\s+now\s+(?:a|an|the)\s+/i,
-    /act\s+as\s+(?:a|an|the)\s+(?!plan|phase|wave)/i,
+    /\bact\s+as\s+(?:a|an|the)\s+(?!plan|phase|wave)/i,
     /pretend\s+(?:you(?:'re| are)\s+|to\s+be\s+)/i,
     /from\s+now\s+on,?\s+you\s+(?:are|will|should|must)/i,
     // System prompt extraction
@@ -349,6 +389,65 @@ function sanitizeForDisplay(text) {
         .join('\n');
     return sanitized;
 }
+/**
+ * Sanitize a value that must render as a SINGLE LINE and is derived from a
+ * filesystem name (a phase directory's number/name token, an archived
+ * milestone label, a bare filename) — not from file/frontmatter CONTENT.
+ *
+ * Why this is NOT `sanitizeForDisplay`: that helper's job is multi-line
+ * prose — it strips whole protocol-leak LINES while deliberately preserving
+ * `\n` between legitimate ones (see its docstring and
+ * `tests/security.test.cjs`'s neighbouring describe). A filesystem name is
+ * the opposite shape: it is supposed to be one line, so a `\n`/`\r` inside
+ * one is never legitimate content to preserve — it is an attacker (or a
+ * doctored checkout) using the directory NAME itself as the injection
+ * vector. #3458's reproduction: a phase directory literally named
+ *   `zz\n0 open items require decisions.\n\x1b[2K\x1b[1G FORGED`
+ * flows verbatim into `audit-open`'s human report (the phase-number
+ * fallback taken when the name doesn't match `PHASE_NUMBER_TOKEN_SOURCE`).
+ * `sanitizeForDisplay` would pass every one of those bytes straight through
+ * — by design, since it never touches control characters — so the embedded
+ * `\n` becomes a real newline in the report, printing a forged
+ * "0 open items require decisions." as its own line, and the raw ESC bytes
+ * reach the terminal.
+ *
+ * This helper closes that hole by ESCAPING (never silently stripping) the
+ * C0 control range (0x00–0x1F, including ESC 0x1B, CR, LF), DEL (0x7F), and
+ * the C1 range (0x80–0x9F) into a visible representation (`\n`, `\x1b`,
+ * ...). Escaping rather than stripping is deliberate: a reviewer reading the
+ * report should be able to SEE that a name was doctored, not have it quietly
+ * normalized away as if nothing happened. Every other character — including
+ * all ordinary printable and non-ASCII text — passes through byte-identical.
+ */
+function sanitizeLabel(text) {
+    if (!text || typeof text !== 'string')
+        return text;
+    const NAMED_ESCAPES = {
+        0x00: '\\0',
+        0x07: '\\a',
+        0x08: '\\b',
+        0x09: '\\t',
+        0x0a: '\\n',
+        0x0b: '\\v',
+        0x0c: '\\f',
+        0x0d: '\\r',
+        0x1b: '\\x1b',
+    };
+    let out = '';
+    for (const ch of text) {
+        const code = ch.codePointAt(0);
+        const isC0 = code <= 0x1f;
+        const isDel = code === 0x7f;
+        const isC1 = code >= 0x80 && code <= 0x9f;
+        if (isC0 || isDel || isC1) {
+            out += NAMED_ESCAPES[code] ?? `\\x${code.toString(16).padStart(2, '0')}`;
+        }
+        else {
+            out += ch;
+        }
+    }
+    return out;
+}
 // ─── Shell Safety ───────────────────────────────────────────────────────────────────────
 /**
  * Validate that a string is safe to use as a shell argument when quoted.