fix(plugins): harness-watch-w1 review: a record carries lastDigest, the latest digest it knew, so a new binary after an unknown, red, missing, timeout or throw reads changed, and when neither record has a digest the version stands in, so red 2.0 to red 2.1 is a transition; the inspect answer is copied inside the try to own data fields only, so a getter, a Proxy or an inherited field is a failed inspect (unknown) and not a failed pass; redaction also covers realpaths, trailing slashes, the user name as a word (<user>) and any absolute path left (<path>), and the loader's refusal messages; a source or rule id equal to an env value is dropped; pi's "can't be checked" match reads only after its lookup label; claude-code skips relative PATH entries and hashes and runs the same resolved file; README updated (#1873, lane harness-watch-w1)

This commit is contained in:
jason.woltje committed 2026-11-20 04:12:24 -06:00
1 parent b156727c00
commit af8c2f9777
5 files changed
+300 -54

No files matched your search

+25 -13
View File
@@ -401,15 +401,19 @@ that check's digest of the binary's files; a failed check gives none. A
failure whose line says "can't be checked" is `fit: "unknown"`.
`claude-code` returns the sha256 of the binary's real file and the first
line of `--version`, and captures `--help` as the `help` surface, both run
with only PATH and a scratch HOME. Its fit stays `"unknown"` until slice W2
adds the claude fit rule.
from that same real file with only PATH and a scratch HOME. Its lookup for
the watch skips a relative PATH entry, as pi's does. Its fit stays
`"unknown"` until slice W2 adds the claude fit rule (and runs these
captures with no network).
A module with no `inspect` is watched through `version({ env })`, with fit
`"unknown"`. A record's `state` is:
- `fit`: found, the fit check passed, same digest as the last record (or no
last digest);
- `changed`: found, the fit check passed, a new digest;
- `fit`: found, the fit check passed, the last known digest (or none known);
- `changed`: found, the fit check passed, a digest that is not the last known
one. The last known digest is the latest any earlier record saw, kept in
each record's `lastDigest` across unknown, red and missing records, so a
new binary first seen through a timeout still reads `changed`;
- `red`: found, and the fit check failed with `definite: true`;
- `unknown`: anything else, including no `inspect`, an `inspect` that throws
or runs past `timeoutMs` (default 300 s), and an answer that isn't this
@@ -417,14 +421,22 @@ A module with no `inspect` is watched through `version({ env })`, with fit
- `missing`: `inspect` says `found: false`.
Only `found: true` with `fit: "pass"` reads as `fit` or `changed`. The watch
checks each field's shape and drops what doesn't fit (a `source` that isn't
a plain name, a digest that isn't 64 hex characters). In every text field it
replaces the scratch directory, the home directory, every env value of six
characters or more and every PATH entry with a name for it. A record also
carries `via` (`inspect` or `version`), `checkedAt` and `changedAt`. A
transition (`{ harness, at, from, to, failed, line }`, with `from` null on
a first sight) is given only when the state or the digest is not the last
record's.
copies the answer's own data fields only: a field that is a getter, or an
answer that throws when read (a Proxy), is a failed `inspect`, and an
inherited field is not read. It checks each field's shape and drops what
doesn't fit (a `source` that isn't a plain name, a digest that isn't 64 hex
characters, a `source` or rule id that is an env value). In every text
field it replaces the scratch directory, the home directory, every env value
of six characters or more and every PATH entry, each also as its real path
and without a trailing slash, with a name for it, the user name (USER,
LOGNAME, the process's account) with `<user>`, then any other absolute path
of two segments or more with `<path>`. The loader's refusals in `refused`
get the same treatment. A record also carries `via` (`inspect` or
`version`), `lastDigest`, `checkedAt` and `changedAt`. A transition
(`{ harness, at, from, to, failed, line }`, with `from` null on a first
sight) is given only when the state or the binary is not the last record's.
The digest names the binary; when neither record has one (pi gives none for
a failed check), the version label stands in for it.
## Transcript usage source (row 124)
@@ -93,21 +93,25 @@ export function version({ env }) {
// #1873 harness watch W1: what the watch records for the binary sessions run: the lookup step that
// found it (MOSAIC_CLAUDE_BIN or PATH, never a path), the sha256 of its real file, the first line
// of --version and the whole --help as a surface. Both run with an empty environment but PATH and
// a fresh HOME under scratch, which is removed after. Without scratch they don't run. Fit stays
// "unknown": the claude fit rule (every flag the adapter passes is in --help) is slice W2.
// a fresh HOME under scratch, which is removed after. Without scratch they don't run. The real path
// is resolved once, then hashed and run, so the digest and the captures are of one file; a relative
// PATH entry is skipped, as pi's lookup skips it. Fit stays "unknown": the claude fit rule (every
// flag the adapter passes is in --help) is slice W2, with the no-network wrapper for these runs.
const CAPTURE_TIMEOUT = 10000;
const CAPTURE_MAX = 1024 * 1024;
export async function inspect({ env = {}, scratch = null, signal } = {}) {
const bin = binary(env);
const bin = binary({ ...env, PATH: (env.PATH ?? "").split(delimiter).filter((dir) => isAbsolute(dir)).join(delimiter) });
const source = env.MOSAIC_CLAUDE_BIN ? "MOSAIC_CLAUDE_BIN" : bin ? "PATH" : null;
const base = { source, fit: "unknown", definite: false, failed: [], surfaces: {} };
if (!bin) return { ...base, found: false, version: null, digest: null, line: env.MOSAIC_CLAUDE_BIN ? "MOSAIC_CLAUDE_BIN isn't an executable file at an absolute path" : "no claude on PATH" };
const digest = await sha256(realpathSync(bin));
let real;
try { real = realpathSync(bin); } catch { return { ...base, found: false, version: null, digest: null, line: `the claude from ${source} can't be resolved` }; }
const digest = await sha256(real);
if (typeof scratch !== "string" || !isAbsolute(scratch)) return { ...base, found: true, version: null, digest, line: "no scratch directory, so --version and --help were not run; fit not checked" };
const home = mkdtempSync(join(scratch, "claude-home-"));
try {
const runEnv = { PATH: "/usr/bin:/bin", HOME: home };
const [v, help] = [await capture(bin, ["--version"], runEnv, signal), await capture(bin, ["--help"], runEnv, signal)];
const [v, help] = [await capture(real, ["--version"], runEnv, signal), await capture(real, ["--help"], runEnv, signal)];
const line = v?.split("\n")[0].trim() ?? "";
const version = line && line.length <= 128 ? line : null;
return { ...base, found: true, version, digest, line: help === null ? "--help gave no answer; fit not checked" : "fit not checked", surfaces: help === null ? {} : { help } };
+7 -3
View File
@@ -59,8 +59,8 @@ export async function version({ env = {} } = {}) {
// check exactly as preflight does (same found binary, same levels, this process's environment), so
// it shares preflight's cache and its running check: a binary that passed is not checked again.
// digest is the fit check's digest of the binary's files; a check that fails gives none, since
// pi-fit.mjs exports no digest of its own. A failure whose line says "can't be checked" could not
// decide, so its fit is "unknown"; any other failure is definite. source names the lookup step,
// pi-fit.mjs exports no digest of its own. A failure whose reason starts "can't be checked" could
// not decide, so its fit is "unknown"; any other failure is definite. source names the lookup step,
// never a path. scratch is not used: the fit check makes its own scratch directories.
const SOURCES = Object.freeze({ MOSAIC_PI_BIN: "MOSAIC_PI_BIN", "the pi on PATH": "PATH", "the repository's pi": "repo" });
export async function inspect({ env = {} } = {}) {
@@ -69,7 +69,11 @@ export async function inspect({ env = {} } = {}) {
const source = SOURCES[at.label] ?? null;
const fit = await piFit(at, { levels: LEVELS });
if (fit.ok) return { found: true, source, version: fit.version ?? null, digest: fit.digest, fit: "pass", definite: true, failed: [], line: `pi${fit.version ? ` ${fit.version}` : ""} (${at.label}) passed the fit check`, surfaces: {} };
const undecided = /can't be checked/.test(fit.message);
// Read after pi-fit's "pi <version> (<label>) " prefix, so a version label cannot decide it. A line
// without that prefix keeps the whole-line match: an unknown line must not read as definite.
const mark = `(${at.label}) `;
const cut = fit.message.indexOf(mark);
const undecided = cut === -1 ? /can't be checked/.test(fit.message) : fit.message.slice(cut + mark.length).startsWith("can't be checked");
return { found: true, source, version: await printedVersion(at.bin), digest: null, fit: undecided ? "unknown" : "fail", definite: !undecided, failed: [], line: fit.message, surfaces: {} };
}
+110 -28
View File
@@ -6,9 +6,11 @@
// state file, no log, no timer. The caller (W2's host timer) keeps the records.
//
// A record's state:
// fit found, the module's fit check passed, and the digest is the last record's (or there
// is no last digest to compare with)
// changed found, the fit check passed, and the digest differs from the last record's
// fit found, the module's fit check passed, and the digest is the last known one (or there
// is no known digest to compare with)
// changed found, the fit check passed, and the digest differs from the last known one: the
// latest digest any earlier record saw, kept in lastDigest across unknown, red and
// missing records, so a new binary first seen through a timeout still reads changed
// red found, and the fit check failed with a definite answer
// unknown anything else: the check could not decide, the module has no inspect, inspect threw,
// timed out or gave an answer that isn't the contract's
@@ -17,9 +19,10 @@
//
// No record field holds a host path or an env value: source must be a lookup step's name
// (MOSAIC_PI_BIN, PATH, repo), never a path, and every text field has the scratch directory,
// the home directory, each env value and each PATH entry replaced by a name for it.
// the home directory, each env value and each PATH entry (and their real paths) replaced by a
// name for it, then every other absolute path replaced by <path>.
import { realpathSync } from "node:fs";
import { homedir } from "node:os";
import { homedir, userInfo } from "node:os";
import { isAbsolute } from "node:path";
import { loadInstalled } from "./loader.mjs";
@@ -39,6 +42,10 @@ const SURFACES_MAX = 16;
const VALUE_MIN = 6;
const CONTROL = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f\u2028\u2029]/g;
// An absolute path of two segments or more that no name replaced. Not one that follows a word,
// a colon, a slash, a dot, a dash, a tilde or a name's closing ">" (URLs, ~/x, <home>/x, a/b/c).
const LOOSE_PATH = /(?<![\w:/.~>-])\/[^\s/'"`<>()[\]{},;]+(?:\/[^\s'"`<>()[\]{},;]*)+/g;
// One pass. last: the records a previous pass returned (an array; others are ignored). env: the
// environment of the process sessions launch from, which the modules look up their binary in.
// scratch: a directory the modules may use for a scratch HOME. Returns { records, transitions,
@@ -48,16 +55,20 @@ const CONTROL = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f\u2028\u2029]/g;
export async function watchHarnesses({ last = [], env = process.env, scratch = null, dataRoot = null, timeoutMs = INSPECT_TIMEOUT_MS, now = () => new Date() } = {}) {
const before = new Map();
for (const r of Array.isArray(last) ? last : []) if (r && typeof r.harness === "string") before.set(r.harness, r);
const { modules, refused } = await loadInstalled("harness", { dataRoot });
const loaded = await loadInstalled("harness", { dataRoot });
const redact = redactor(env, scratch);
// The loader's refusals name the module's directory, a host path, so their text is redacted too.
const refused = loaded.refused.map((r) => ({ ...r, message: typeof r.message === "string" ? redact(r.message) : null }));
const modules = loaded.modules;
const records = [];
const transitions = [];
for (const { name, module } of modules) {
const answer = await ask(module, { env, scratch, timeoutMs });
const at = now().toISOString();
const prior = before.get(name) ?? null;
const record = { harness: name, ...settle(clean(answer, redact), prior), checkedAt: at };
const moved = !prior || prior.state !== record.state || (prior.digest ?? null) !== record.digest;
const record = { harness: name, ...settle(clean(answer, redact, env), prior), checkedAt: at };
record.lastDigest = record.digest ?? known(prior);
const moved = !prior || prior.state !== record.state || !sameBinary(prior, record);
record.changedAt = moved ? at : (typeof prior.changedAt === "string" ? prior.changedAt : at);
records.push(record);
if (moved) transitions.push({ harness: name, at, from: prior ? brief(prior) : null, to: brief(record), failed: record.failed, line: record.line });
@@ -66,6 +77,16 @@ export async function watchHarnesses({ last = [], env = process.env, scratch = n
return { records, transitions, refused, gone: [...before.keys()].filter((n) => !seen.has(n)).sort() };
}
// The latest digest the last record knew: its own, or the one it carried forward.
const known = (prior) => [prior?.digest, prior?.lastDigest].find((d) => typeof d === "string" && DIGEST.test(d)) ?? null;
// Whether two records are of the same binary. The digest decides; when neither record has one
// (pi gives none for a failed check), the version label stands in for it.
function sameBinary(prior, record) {
const was = typeof prior.digest === "string" ? prior.digest : null;
if (was !== null || record.digest !== null) return was === record.digest;
return (typeof prior.version === "string" ? prior.version : null) === record.version;
}
const brief = (r) => ({ state: STATES.includes(r.state) ? r.state : "unknown", version: typeof r.version === "string" ? r.version : null, digest: typeof r.digest === "string" ? r.digest : null });
// The module's answer, or { error } when it threw or ran past timeoutMs. via says which export.
@@ -76,8 +97,11 @@ async function ask(module, { env, scratch, timeoutMs }) {
const late = new Promise((resolve) => { timer = setTimeout(() => { stop.abort(); resolve({ via, error: "timeout" }); }, timeoutMs); });
const asked = (async () => {
try {
if (via === "inspect") return { via, answer: await module.inspect({ env, scratch, signal: stop.signal }) };
return { via, version: await module.version({ env }) };
// The answer is copied here, inside the try, to plain own data: a getter, a Proxy or an
// inherited field that throws or lies is a failed inspect, not a failed pass.
if (via === "inspect") return { via, answer: plain(await module.inspect({ env, scratch, signal: stop.signal })) };
const version = await module.version({ env });
return { via, version: typeof version === "string" ? version : null };
} catch {
// The error's text can name a host path, so the record keeps none of it.
return { via, error: "threw" };
@@ -90,8 +114,45 @@ async function ask(module, { env, scratch, timeoutMs }) {
}
}
// The contract's fields from an answer, each checked and redacted. Anything else is dropped.
function clean({ via, answer, version, error }, redact) {
// The contract's fields of an answer as own data properties, copied to a plain object whose
// values are strings, booleans, null, an array of strings or a map of strings. A getter is not
// called (a field that is one makes the answer a failed inspect), an inherited field is not read,
// and failed and surfaces are cut before they are read.
const FIELDS = ["found", "source", "version", "digest", "fit", "definite", "line"];
function plain(answer) {
if (!answer || typeof answer !== "object") return null;
const own = (o, k) => {
const d = Object.getOwnPropertyDescriptor(o, k);
if (d && !("value" in d)) throw new Error("an accessor field");
return d ? d.value : undefined;
};
const out = {};
for (const k of FIELDS) {
const v = own(answer, k);
if (typeof v === "string" || typeof v === "boolean") out[k] = v;
}
const failed = own(answer, "failed");
if (Array.isArray(failed)) {
out.failed = [];
for (let i = 0; i < Math.min(failed.length, 32); i++) {
const id = own(failed, String(i));
if (typeof id === "string") out.failed.push(id);
}
}
const surfaces = own(answer, "surfaces");
if (surfaces && typeof surfaces === "object" && !Array.isArray(surfaces)) {
out.surfaces = {};
for (const k of Object.keys(surfaces).slice(0, SURFACES_MAX)) {
const v = own(surfaces, k);
if (typeof v === "string") out.surfaces[k] = v.slice(0, SURFACE_MAX);
}
}
return out;
}
// The contract's fields from an answer, each checked and redacted. Anything else is dropped. A
// source or rule id that is an env value is dropped too: they are not text, so not redacted.
function clean({ via, answer, version, error }, redact, env) {
const base = { via, found: null, source: null, version: null, digest: null, fit: "unknown", definite: false, failed: [], line: null, surfaces: {} };
if (error === "timeout") return { ...base, line: `${via} did not answer in time` };
if (error) return { ...base, line: `${via} failed` };
@@ -100,25 +161,24 @@ function clean({ via, answer, version, error }, redact) {
return { ...base, version: label, line: label ? "no inspect; fit not checked" : "no inspect, and version gave no answer" };
}
if (!answer || typeof answer !== "object") return { ...base, line: "inspect gave no answer" };
const values = envValues(env);
const found = answer.found === true ? true : answer.found === false ? false : null;
const fit = FITS.has(answer.fit) ? answer.fit : "unknown";
const surfaces = {};
if (answer.surfaces && typeof answer.surfaces === "object") {
for (const [k, v] of Object.entries(answer.surfaces).slice(0, SURFACES_MAX)) {
if (SURFACE.test(k) && typeof v === "string") surfaces[k] = redact(v.slice(0, SURFACE_MAX));
}
for (const [k, v] of Object.entries(answer.surfaces)) if (SURFACE.test(k)) surfaces[k] = redact(v);
}
return {
...base,
found,
source: typeof answer.source === "string" && SOURCE.test(answer.source) ? answer.source : null,
source: typeof answer.source === "string" && SOURCE.test(answer.source) && !values.has(answer.source) ? answer.source : null,
version: text(answer.version, LABEL_MAX, redact),
digest: typeof answer.digest === "string" && DIGEST.test(answer.digest) ? answer.digest : null,
fit,
// A pass is an answer, so it is definite. A failure is definite only when the module says so
// (otherwise the check could not decide), and an unknown never is.
definite: fit === "pass" || (fit === "fail" && answer.definite === true),
failed: Array.isArray(answer.failed) ? [...new Set(answer.failed.filter((id) => typeof id === "string" && RULE.test(id)))].slice(0, 32) : [],
failed: Array.isArray(answer.failed) ? [...new Set(answer.failed.filter((id) => RULE.test(id) && !values.has(id)))] : [],
line: text(answer.line, LINE_MAX, redact),
surfaces,
};
@@ -129,7 +189,7 @@ function settle(r, prior) {
let state = "unknown";
if (r.via === "inspect" && r.found === false) state = "missing";
else if (r.via === "inspect" && r.found === true && r.fit === "pass") {
const was = prior && typeof prior.digest === "string" ? prior.digest : null;
const was = known(prior);
state = was !== null && r.digest !== null && was !== r.digest ? "changed" : "fit";
} else if (r.via === "inspect" && r.found === true && r.fit === "fail" && r.definite) state = "red";
return { state, ...r };
@@ -142,29 +202,51 @@ function text(v, max, redact) {
return line || null;
}
// Every nonempty string value in env and in this process's environment.
function envValues(env) {
const out = new Set();
for (const source of [env ?? {}, process.env]) for (const v of Object.values(source)) if (typeof v === "string" && v) out.add(v);
return out;
}
const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
// Replaces every host path and env value a record could pick up with a name for it: the scratch
// directory (and its real path), the home directory, each env value of VALUE_MIN characters or
// more from env and this process's own environment, and each absolute PATH entry. Longest first,
// so a path inside another is not left half replaced.
// directory, the home directory, each env value of VALUE_MIN characters or more from env and this
// process's own environment, and each absolute PATH entry, each also as its real path and without
// a trailing slash. Longest first, so a path inside another is not left half replaced. The user
// name (this process's account, USER and LOGNAME), short as it may be, is replaced as a whole
// word. Last, any absolute path left is <path>.
function redactor(env, scratch) {
const pairs = new Map();
const add = (value, name) => { if (typeof value === "string" && value.length >= VALUE_MIN && !pairs.has(value)) pairs.set(value, name); };
if (typeof scratch === "string" && scratch) {
add(scratch, "<scratch>");
try { add(realpathSync(scratch), "<scratch>"); } catch {}
}
const put = (value, name) => { if (value.length >= VALUE_MIN && !pairs.has(value)) pairs.set(value, name); };
const add = (value, name) => {
if (typeof value !== "string") return;
put(value, name);
if (!value.startsWith("/")) return;
const bare = value.replace(/\/+$/, "");
if (bare) put(bare, name);
try { put(realpathSync(bare || "/"), name); } catch {}
};
if (typeof scratch === "string" && scratch) add(scratch, "<scratch>");
for (const source of [env ?? {}, process.env]) {
for (const [k, v] of Object.entries(source)) {
if (typeof v !== "string") continue;
add(v, `<${k}>`);
if (k === "PATH") for (const dir of v.split(":")) if (isAbsolute(dir) && dir !== "/") add(dir.replace(/\/+$/, ""), "<PATH entry>");
if (k === "PATH") for (const dir of v.split(":")) if (isAbsolute(dir) && dir !== "/") add(dir, "<PATH entry>");
}
}
try { add(homedir(), "<home>"); } catch {}
const users = new Set();
try { users.add(userInfo().username); } catch {}
for (const source of [env ?? {}, process.env]) for (const k of ["USER", "LOGNAME"]) if (typeof source[k] === "string") users.add(source[k]);
const words = [...users].filter((u) => typeof u === "string" && u.length >= 2 && /^[A-Za-z0-9._-]+$/.test(u));
const word = words.length ? new RegExp(`(?<![A-Za-z0-9_])(?:${words.sort((a, b) => b.length - a.length).map(escape).join("|")})(?![A-Za-z0-9_])`, "g") : null;
const order = [...pairs.keys()].sort((a, b) => b.length - a.length);
return (s) => {
let out = s;
for (const value of order) if (out.includes(value)) out = out.split(value).join(pairs.get(value));
return out;
if (word) out = out.replace(word, "<user>");
return out.replace(LOOSE_PATH, "<path>");
};
}
+149 -5
View File
@@ -31,18 +31,27 @@ function scratch(t) {
// A stand-in harness module: every export the kind needs, a version() that answers
// env.WATCH_VERSION, and (with inspect) an inspect() that answers its own entry of the JSON file
// env.WATCH_ANSWER names, read at each call: "throw" throws, "hang" never answers.
const standIn = (name, { inspect = true } = {}) => `import { readFileSync } from "node:fs";
// env.WATCH_ANSWER names, read at each call: "throw" throws, "hang" never answers, "hang-signal"
// never answers but writes <answer file>.aborted when its signal aborts, and the rest build an
// answer JSON cannot carry (a throwing getter, a Proxy, inherited fields, a huge sparse array).
const standIn = (name, { inspect = true } = {}) => `import { readFileSync, writeFileSync } from "node:fs";
export const interfaceVersion = ${KINDS.harness.interfaceVersion};
${KINDS.harness.exports.filter((e) => e !== "version").map((e) => `export function ${e}() { return null; }`).join("\n")}
export async function version({ env }) {
if (env.WATCH_VERSION === "throw") throw new Error("version failed at " + env.WATCH_SECRET);
return env.WATCH_VERSION ?? null;
}
${inspect ? `export async function inspect({ env }) {
${inspect ? `export async function inspect({ env, signal }) {
const a = JSON.parse(readFileSync(env.WATCH_ANSWER, "utf8"))[${JSON.stringify(name)}];
if (a === "throw") throw new Error("inspect failed at " + env.WATCH_SECRET);
const boom = () => { throw new Error("inspect failed at " + env.WATCH_SECRET); };
if (a === "throw") boom();
if (a === "hang") return new Promise(() => {});
if (a === "hang-signal") return new Promise(() => { signal.addEventListener("abort", () => writeFileSync(env.WATCH_ANSWER + ".aborted", "1")); });
if (a === "getter") return { found: true, fit: "pass", definite: true, get digest() { return boom(); } };
if (a === "proxy") return new Proxy({}, { get: boom, getOwnPropertyDescriptor: boom, ownKeys: boom });
if (a === "surfaces-proxy") return { found: true, fit: "pass", definite: true, digest: "${DIGEST_A}", surfaces: new Proxy({}, { ownKeys: boom }) };
if (a === "inherited") return Object.create({ found: true, fit: "pass", definite: true, digest: "${DIGEST_A}" });
if (a === "sparse") { const failed = []; failed.length = 2 ** 32 - 1; failed[0] = "C1"; return { found: true, fit: "fail", definite: true, failed, line: "sparse" }; }
return a;
}` : ""}
`;
@@ -58,7 +67,7 @@ async function watchTree(t, harnesses) {
writeFileSync(file, JSON.stringify(answers));
return watchHarnesses({ last, env: { WATCH_ANSWER: file, ...env }, scratch: dir, timeoutMs });
};
return { pass, dir };
return { pass, dir, tr, file };
}
const ok = (digest, extra = {}) => ({ found: true, source: "PATH", version: "1.0.0", digest, fit: "pass", definite: true, failed: [], line: "passed", surfaces: {}, ...extra });
@@ -142,6 +151,96 @@ test("W1 a transition is reported only when the state or the digest changes", as
assert.deepEqual(six.gone, ["removed"]);
});
test("W1 a new binary first seen through an unknown, red or missing record still reads changed", async (t) => {
const { pass } = await watchTree(t, { h: {} });
const none = { found: true, source: "PATH", version: "2.0.0", digest: null, fit: "unknown", definite: false, failed: [], line: "timed out", surfaces: {} };
for (const [what, between] of [["unknown", none], ["red", { ...none, fit: "fail", definite: true }], ["missing", { ...none, found: false }], ["timeout", "hang"], ["throw", "throw"]]) {
const one = await pass({ h: ok(DIGEST_A) });
const two = await pass({ h: between }, { last: one.records, timeoutMs: 200 });
assert.equal(byName(two).h.lastDigest, DIGEST_A, what);
const three = await pass({ h: ok(DIGEST_B) }, { last: two.records });
assert.equal(byName(three).h.state, "changed", what);
const four = await pass({ h: ok(DIGEST_B) }, { last: three.records });
assert.equal(byName(four).h.state, "fit", what);
}
// With no digest on either record, a new version label is a new binary: red 2.0 to red 2.1 is a
// transition, red 2.1 again is not.
const red = (version, line) => ({ ...none, version, line, fit: "fail", definite: true });
const a = await pass({ h: red("2.0.0", "lacks --no-skills") });
const b = await pass({ h: red("2.1.0", "lacks --no-mcp") }, { last: a.records });
assert.deepEqual(b.transitions.map((x) => [x.from.version, x.to.version, x.line]), [["2.0.0", "2.1.0", "lacks --no-mcp"]]);
const c = await pass({ h: red("2.1.0", "lacks --no-mcp") }, { last: b.records });
assert.deepEqual(c.transitions, []);
});
test("W1 an answer that throws when read, a Proxy or inherited fields is unknown, and the other harnesses still get records", async (t) => {
const { pass, file } = await watchTree(t, { bad: {}, good: {} });
for (const shape of ["getter", "proxy", "surfaces-proxy"]) {
const out = await pass({ bad: shape, good: ok(DIGEST_A) }, { env: { WATCH_SECRET: "/srv/fixture-secret-place" } });
const r = byName(out);
assert.deepEqual([r.bad.state, r.bad.line, r.good.state], ["unknown", "inspect failed", "fit"], shape);
assert.ok(!JSON.stringify(out).includes("fixture-secret"), shape);
}
// An inherited fit is not the module's answer.
assert.equal(byName(await pass({ bad: "inherited", good: ok(DIGEST_A) })).bad.state, "unknown");
// A huge sparse failed list is cut before it is read, so the pass ends at once.
const began = Date.now();
const sparse = byName(await pass({ bad: "sparse", good: ok(DIGEST_A) })).bad;
assert.deepEqual([sparse.state, sparse.failed], ["red", ["C1"]]);
assert.ok(Date.now() - began < 2000);
// On a timeout the watch aborts the signal it passed.
const late = byName(await pass({ bad: "hang-signal", good: ok(DIGEST_A) }, { timeoutMs: 200 })).bad;
await new Promise((done) => setTimeout(done, 50));
assert.equal(late.state, "unknown");
assert.equal(readFileSync(file + ".aborted", "utf8"), "1");
});
test("W1 fields are checked: a digest that is a path is dropped, version and line keep one printable line", async (t) => {
const { pass, dir } = await watchTree(t, { h: {} });
const r = byName(await pass({ h: ok(dir, { version: "1.0\u0007beta\nsecond line", line: "first\r\nsecond", surfaces: { help: "a\nb" } }) })).h;
assert.deepEqual([r.digest, r.version, r.line, r.surfaces.help], [null, "1.0 beta", "first", "a\nb"]);
});
test("W1 redaction covers real paths, trailing slashes, the user name, rule ids, sources, loose paths and the loader's refusals", async (t) => {
const { pass, dir, tr } = await watchTree(t, { h: {} });
mkdirSync(join(dir, "real", "home"), { recursive: true });
mkdirSync(join(dir, "real", "bin"), { recursive: true });
symlinkSync(join(dir, "real", "home"), join(dir, "linkhome"));
symlinkSync(join(dir, "real", "bin"), join(dir, "linkbin"));
const realHome = realpathSync(join(dir, "linkhome"));
const realBin = realpathSync(join(dir, "linkbin"));
// A symlinked scratch: the answer names its real path.
const linkScratch = join(dir, "linkscratch");
symlinkSync(dir, linkScratch);
const env = { HOME: join(dir, "linkhome") + "/", PATH: `${join(dir, "linkbin")}:/usr/bin:/bin`, USER: "jq", WATCH_TOKEN: "sk-AbCdEf123456", WATCH_NAME: "fixturesource" };
// Each rule on its own line, with what the line must read after. scratch: the one passed.
const lines = {
scratch: [`in ${dir}/x`, "in <scratch>/x", linkScratch],
home: [`home ${realHome}`, "home <HOME>", dir],
slash: [`home ${join(dir, "linkhome")}`, "home <HOME>", dir],
bin: [`bin ${realBin}/claude`, "bin <PATH entry>/claude", dir],
user: ["built by jq on host", "built by <user> on host", dir],
loose: ["at /opt/notinenv/bin/tool and /etc/passwd", "at <path> and <path>", dir],
kept: ["see https://example.com/a/b, ~/x/y and /model", "see https://example.com/a/b, ~/x/y and /model", dir],
};
const { watchHarnesses } = await import(pathToFileURL(join(tr.pkg, "src", "harness-watch.mjs")).href);
for (const [what, [line, want, at]] of Object.entries(lines)) {
const file = join(dir, `answer-${what}.json`);
writeFileSync(file, JSON.stringify({ h: ok(DIGEST_A, { line }) }));
const out = await watchHarnesses({ env: { ...env, WATCH_ANSWER: file }, scratch: at });
assert.equal(byName(out).h.line, want, what);
}
const rec = byName(await pass({ h: ok(DIGEST_A, { source: "fixturesource", failed: ["sk-AbCdEf123456", "C5"], line: `in ${realpathSync(dir)}` }) }, { env })).h;
assert.deepEqual([rec.source, rec.failed], [null, ["C5"]]);
assert.equal(rec.line, "in <scratch>");
// The loader's refusal of a harness directory with no index.mjs names its path; the watch's copy doesn't.
mkdirSync(join(tr.pkg, "harness", "noindex"));
const out = await pass({ h: ok(DIGEST_A) });
const refusal = out.refused.find((r) => r.name === "noindex");
assert.ok(refusal && typeof refusal.message === "string", JSON.stringify(out.refused));
assert.ok(!refusal.message.includes(tr.pkg), refusal.message);
});
test("W1 no record holds a path under the scratch directory, the home directory or an env value", async (t) => {
const { pass, dir } = await watchTree(t, { h: {} });
const secret = "/srv/fixture-secret-place";
@@ -248,6 +347,18 @@ test("W1 claude-code inspect: no binary is not found, naming the variable; no sc
assert.deepEqual([r.found, r.source, r.line], [false, "MOSAIC_CLAUDE_BIN", "MOSAIC_CLAUDE_BIN isn't an executable file at an absolute path"]);
r = await claude.inspect({ env: { PATH: scratch(t) }, scratch: scratch(t) });
assert.deepEqual([r.found, r.source], [false, null]);
// A relative PATH entry is skipped, as pi's lookup skips it, though "bin" from this cwd holds a claude.
const rel = scratch(t);
mkdirSync(join(rel, "bin"));
writeFileSync(join(rel, "bin", "claude"), "#!/bin/sh\necho 1.0.0\n", { mode: 0o755 });
const cwd = process.cwd();
process.chdir(rel);
try {
r = await claude.inspect({ env: { PATH: "bin" }, scratch: scratch(t) });
} finally {
process.chdir(cwd);
}
assert.deepEqual([r.found, r.source], [false, null]);
const dir = scratch(t);
mkdirSync(join(dir, "bin"));
writeFileSync(join(dir, "bin", "claude"), "#!/bin/sh\necho ran >> \"$0.log\"\necho 1.2.3\n", { mode: 0o755 });
@@ -257,6 +368,39 @@ test("W1 claude-code inspect: no binary is not found, naming the variable; no sc
assert.deepEqual(readdirNames(join(dir, "bin")), ["claude"], "nothing ran without scratch");
});
test("W1 claude-code inspect runs --version and --help with PATH and a scratch HOME only, then removes it", async (t) => {
const dir = scratch(t);
const work = scratch(t);
mkdirSync(join(dir, "bin"));
const bin = join(dir, "bin", "claude");
writeFileSync(bin, "#!/bin/sh\nenv > \"$0.env$1\"\n[ \"$1\" = --version ] && echo '1.2.3 (stand-in)'\n[ \"$1\" = --help ] && echo 'usage: claude --version'\nexit 0\n", { mode: 0o755 });
const r = await claude.inspect({ env: { MOSAIC_CLAUDE_BIN: bin, PATH: "/usr/bin:/bin", FIXTURE_TOKEN: "fixture-token-value" }, scratch: work });
assert.deepEqual([r.found, r.source, r.version, r.surfaces.help], [true, "MOSAIC_CLAUDE_BIN", "1.2.3 (stand-in)", "usage: claude --version\n"]);
for (const arg of ["--version", "--help"]) {
const vars = Object.fromEntries(readFileSync(`${bin}.env${arg}`, "utf8").trim().split("\n").map((l) => [l.slice(0, l.indexOf("=")), l.slice(l.indexOf("=") + 1)]));
assert.deepEqual(Object.keys(vars).filter((k) => !["PWD", "SHLVL", "_", "OLDPWD"].includes(k)).sort(), ["HOME", "PATH"], arg);
assert.equal(vars.PATH, "/usr/bin:/bin");
assert.ok(vars.HOME.startsWith(join(realpathSync(work), "claude-home-")), arg);
}
assert.deepEqual(readdirNames(work), [], "the scratch HOME is removed");
});
test("W1 claude-code inspect: an aborted signal kills the capture it is running", async (t) => {
const dir = scratch(t);
mkdirSync(join(dir, "bin"));
const bin = join(dir, "bin", "claude");
writeFileSync(bin, "#!/bin/sh\necho $$ > \"$0.pid$1\"\nexec sleep 30\n", { mode: 0o755 });
const stop = new AbortController();
setTimeout(() => stop.abort(), 300);
const began = Date.now();
const r = await claude.inspect({ env: { MOSAIC_CLAUDE_BIN: bin }, scratch: scratch(t), signal: stop.signal });
assert.ok(Date.now() - began < 5000);
assert.deepEqual([r.found, r.version, r.surfaces], [true, null, {}]);
const pid = Number(readFileSync(`${bin}.pid--version`, "utf8"));
await new Promise((done) => setTimeout(done, 200));
assert.throws(() => process.kill(pid, 0), { code: "ESRCH" });
});
function readdirNames(dir) {
return readdirSync(dir).sort();
}