From b156727c0021f7fb0a629d3f87e599779e4f6e5d Mon Sep 17 00:00:00 2001 From: Jason Woltje Date: Fri, 20 Nov 2026 03:54:47 -0600 Subject: [PATCH 1/3] feat(plugins): harness watch W1: watchHarnesses() makes one pass over every harness the loader gives, with no name list, and calls the optional inspect({ env, scratch, signal }) or falls back to version() with fit unknown; it sets each record's state (fit, changed, red, unknown, missing) from the answer and the last record, gives a transition only when the state or the digest changes, and writes nothing; only found plus fit pass reads as fit, a fail is red only when definite, and a throw, a timeout or an answer outside the contract is unknown; source must be a lookup step's name, and every text field has the scratch directory, the home directory, env values and PATH entries replaced by names; pi's inspect reuses preflight's fit check and its cache (a "can't be checked" failure is unknown); claude-code's inspect gives the version, the sha256 and a --help surface from a scratch HOME, fit unknown; README documents the contract (#1873, lane harness-watch-w1) --- packages/plugins/README.md | 59 ++++ .../plugins/harness/claude-code/index.mjs | 56 +++- packages/plugins/harness/pi/index.mjs | 18 ++ packages/plugins/src/harness-watch.mjs | 170 ++++++++++++ packages/plugins/tests/harness-watch.test.mjs | 262 ++++++++++++++++++ 5 files changed, 563 insertions(+), 2 deletions(-) create mode 100644 packages/plugins/src/harness-watch.mjs create mode 100644 packages/plugins/tests/harness-watch.test.mjs diff --git a/packages/plugins/README.md b/packages/plugins/README.md index 5c85e306d..d4a3ab5dd 100644 --- a/packages/plugins/README.md +++ b/packages/plugins/README.md @@ -367,6 +367,65 @@ the kind's whole setting, so it names every harness that stays on: { "revision": "", "plugins": { "harness": ["pi", "claude-code"] } } ``` +### Harness watch and `inspect` (#1873, slice W1) + +Jason's ruling (2026-11-19): no pins on any harness, a periodic check +instead. `src/harness-watch.mjs` is the function that check calls. +`watchHarnesses({ last, env, scratch, dataRoot, timeoutMs })` makes one +pass over every harness `loadInstalled('harness', { dataRoot })` gives, +tree or installed. It holds no name list, so a harness added later is +watched at once. It writes nothing: it takes the records the last pass +returned and gives back `{ records, transitions, refused, gone }`. + +`inspect({ env, scratch, signal })` is an optional harness export, outside +`kinds.mjs`. It returns a promise of: + +| Field | Meaning | +|---|---| +| `found` | `true` when the binary sessions run was found, `false` when not | +| `source` | the lookup step that won, such as `MOSAIC_PI_BIN`, `PATH` or `repo`; never a path | +| `version` | the binary's version label, or null | +| `digest` | a sha256 hex digest of what runs, or null | +| `fit` | `"pass"`, `"fail"` or `"unknown"`: the module's own fit check | +| `definite` | for a `"fail"`, true when the check decided; a failure that could not tell is false | +| `failed` | rule ids the check names, when it names any | +| `line` | one plain line for the owner; it names a variable or a lookup step, never a path | +| `surfaces` | name to text, such as `help` | + +`env` is the environment of the process sessions launch from. `scratch` is +a directory the module may use for a scratch HOME; it removes what it makes +there. `signal` aborts when the watch stops waiting. `pi` returns its fit +check (`packages/harness/src/pi-fit.mjs`), called exactly as `preflight` +calls it, so the two share one cache and one running check. Its digest is +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. + +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; +- `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 + shape; +- `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. + ## Transcript usage source (row 124) `usage-source/transcript` now ships interface 1's `readTurn({harness, root})`. diff --git a/packages/plugins/harness/claude-code/index.mjs b/packages/plugins/harness/claude-code/index.mjs index 984d6a280..9f82533cf 100644 --- a/packages/plugins/harness/claude-code/index.mjs +++ b/packages/plugins/harness/claude-code/index.mjs @@ -4,8 +4,9 @@ // both stay in packages/harness (a module can't change that boundary). The launcher, the bundle // and the usage reader call these on the host; the runner gets the answers as data in // session.json. packages/plugins/README.md lists the interface. -import { spawnSync } from "node:child_process"; -import { accessSync, constants, realpathSync, statSync } from "node:fs"; +import { spawn, spawnSync } from "node:child_process"; +import { createHash } from "node:crypto"; +import { accessSync, constants, createReadStream, mkdtempSync, realpathSync, rmSync, statSync } from "node:fs"; import { delimiter, dirname, isAbsolute, join } from "node:path"; import { fileURLToPath } from "node:url"; import { claudeBuiltins, MCP_PREFIX } from "../../../harness/src/gate.mjs"; @@ -89,6 +90,57 @@ export function version({ env }) { return r.status === 0 ? r.stdout.trim().split("\n")[0] || null : null; } +// #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. +const CAPTURE_TIMEOUT = 10000; +const CAPTURE_MAX = 1024 * 1024; +export async function inspect({ env = {}, scratch = null, signal } = {}) { + const bin = binary(env); + 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)); + 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 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 } }; + } finally { + rmSync(home, { recursive: true, force: true }); + } +} + +function sha256(file) { + return new Promise((resolve, reject) => { + const h = createHash("sha256"); + createReadStream(file).on("error", reject).on("data", (c) => h.update(c)).on("end", () => resolve(h.digest("hex"))); + }); +} + +// stdout of bin args when it exits 0 within CAPTURE_TIMEOUT and prints at most CAPTURE_MAX, else null. +function capture(bin, args, runEnv, signal) { + return new Promise((resolve) => { + let child; + try { child = spawn(bin, args, { env: runEnv, cwd: runEnv.HOME, stdio: ["ignore", "pipe", "ignore"] }); } catch { resolve(null); return; } + const out = []; + let size = 0, done = false; + const finish = (v) => { if (done) return; done = true; clearTimeout(timer); signal?.removeEventListener?.("abort", kill); resolve(v); }; + const kill = () => { try { child.kill("SIGKILL"); } catch {} finish(null); }; + const timer = setTimeout(kill, CAPTURE_TIMEOUT); + signal?.addEventListener?.("abort", kill, { once: true }); + if (signal?.aborted) kill(); + child.stdout.on("data", (c) => { size += c.length; if (size > CAPTURE_MAX) kill(); else out.push(c); }); + child.on("error", () => finish(null)); + child.on("close", (status) => finish(status === 0 ? Buffer.concat(out).toString("utf8") : null)); + }); +} + // Its launches spend the business's launch.account (row 126). export const countsAccount = () => true; diff --git a/packages/plugins/harness/pi/index.mjs b/packages/plugins/harness/pi/index.mjs index 8ffc361be..fbf417297 100644 --- a/packages/plugins/harness/pi/index.mjs +++ b/packages/plugins/harness/pi/index.mjs @@ -55,6 +55,24 @@ export async function version({ env = {} } = {}) { return printedVersion(locate(env).bin); } +// #1873 harness watch W1: what the watch records for the pi binary sessions run. It calls the fit +// 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, +// 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 = {} } = {}) { + const at = locate(env); + if (!at.bin) return { found: false, source: env.MOSAIC_PI_BIN ? "MOSAIC_PI_BIN" : null, version: null, digest: null, fit: "unknown", definite: false, failed: [], line: at.problem, surfaces: {} }; + 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); + return { found: true, source, version: await printedVersion(at.bin), digest: null, fit: undecided ? "unknown" : "fail", definite: !undecided, failed: [], line: fit.message, surfaces: {} }; +} + // #1873 S3: runs the fit check, or shares the one running, and throws its refusal line when the // binary fails it. A host that calls env() without preflight (Triage) awaits this first. export async function ready({ env = process.env } = {}) { diff --git a/packages/plugins/src/harness-watch.mjs b/packages/plugins/src/harness-watch.mjs new file mode 100644 index 000000000..2fea75c99 --- /dev/null +++ b/packages/plugins/src/harness-watch.mjs @@ -0,0 +1,170 @@ +// #1873 harness watch, slice W1 (reports/harness-watch-design.md sections 1 and 5): one pass over +// every harness the loader gives, tree or installed. No name list: a harness added later is +// watched at once. For each module it calls the optional inspect({ env, scratch, signal }), or +// falls back to version({ env }) with fit "unknown". It compares the answer with the last record +// the caller passes in and returns the new records and the transitions. It writes nothing: no +// 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 +// 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 +// missing inspect says the binary is not found +// Only fit === "pass" with found === true reads as fit or changed. Nothing else can. +// +// 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. +import { realpathSync } from "node:fs"; +import { homedir } from "node:os"; +import { isAbsolute } from "node:path"; +import { loadInstalled } from "./loader.mjs"; + +export const STATES = Object.freeze(["fit", "changed", "red", "unknown", "missing"]); +const FITS = new Set(["pass", "fail", "unknown"]); +// An inspect that takes longer than this gives unknown. pi's fit check runs many sandboxed starts. +export const INSPECT_TIMEOUT_MS = 300000; +const SOURCE = /^[A-Za-z][A-Za-z0-9_]{0,63}$/; +const RULE = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,63}$/; +const SURFACE = /^[a-z][a-z0-9-]{0,31}$/; +const DIGEST = /^[a-f0-9]{64}$/; +const LABEL_MAX = 128; +const LINE_MAX = 500; +const SURFACE_MAX = 256 * 1024; +const SURFACES_MAX = 16; +// An env value shorter than this is too common a word to mean anything ("1", "true", "C"). +const VALUE_MIN = 6; +const CONTROL = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f\u2028\u2029]/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, +// refused, gone }: one record per harness the loader gives, a transition for each harness whose +// state or digest is not the last record's (or that has no last record), the loader's refusals +// as it reports them, and the names of last records whose harness the loader no longer gives. +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 redact = redactor(env, scratch); + 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; + 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 }); + } + const seen = new Set(records.map((r) => r.harness)); + return { records, transitions, refused, gone: [...before.keys()].filter((n) => !seen.has(n)).sort() }; +} + +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. +async function ask(module, { env, scratch, timeoutMs }) { + const via = typeof module.inspect === "function" ? "inspect" : "version"; + const stop = new AbortController(); + let timer = null; + 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 }) }; + } catch { + // The error's text can name a host path, so the record keeps none of it. + return { via, error: "threw" }; + } + })(); + try { + return await Promise.race([asked, late]); + } finally { + clearTimeout(timer); + } +} + +// The contract's fields from an answer, each checked and redacted. Anything else is dropped. +function clean({ via, answer, version, error }, redact) { + 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` }; + if (via === "version") { + const label = text(version, LABEL_MAX, 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 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)); + } + } + return { + ...base, + found, + source: typeof answer.source === "string" && SOURCE.test(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) : [], + line: text(answer.line, LINE_MAX, redact), + surfaces, + }; +} + +// The state for a cleaned answer and the last record. +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; + 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 }; +} + +// One printable line, cut to max, redacted; or null. +function text(v, max, redact) { + if (typeof v !== "string") return null; + const line = redact(v.split("\n")[0].replace(CONTROL, " ").trim()).slice(0, max); + return line || null; +} + +// 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. +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, ""); + try { add(realpathSync(scratch), ""); } catch {} + } + 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(/\/+$/, ""), ""); + } + } + try { add(homedir(), ""); } catch {} + 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; + }; +} diff --git a/packages/plugins/tests/harness-watch.test.mjs b/packages/plugins/tests/harness-watch.test.mjs new file mode 100644 index 000000000..92aa1a4f9 --- /dev/null +++ b/packages/plugins/tests/harness-watch.test.mjs @@ -0,0 +1,262 @@ +// #1873 harness watch, slice W1 (reports/harness-watch-design.md sections 1 and 5): one pass over +// every harness the loader gives, an optional inspect per module or the version fallback, a +// state from the answer and the last record, and transitions only on a state or digest change. +// No record holds a host path or an env value. +import test from "node:test"; +import assert from "node:assert/strict"; +import { createReadStream, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync, symlinkSync, watch, writeFileSync } from "node:fs"; +import { createHash } from "node:crypto"; +import { tmpdir } from "node:os"; +import { join, resolve } from "node:path"; +import { fileURLToPath, pathToFileURL } from "node:url"; +import { tree } from "./helpers.mjs"; +import { KINDS } from "../src/kinds.mjs"; +import { piStandIn } from "../../harness/tests/pi-stand-in.mjs"; +import { sandboxProblem } from "../../seat/src/sandbox.mjs"; +import * as pi from "../harness/pi/index.mjs"; +import * as claude from "../harness/claude-code/index.mjs"; + +const REPO = resolve(fileURLToPath(new URL("../../../", import.meta.url))); +const WATCH_SRC = join(REPO, "packages", "plugins", "src", "harness-watch.mjs"); +const PI_NAME = "@earendil-works/pi-coding-agent"; +const NO_BWRAP = sandboxProblem() ? { skip: "no working bwrap here" } : {}; +const DIGEST_A = "a".repeat(64); +const DIGEST_B = "b".repeat(64); + +function scratch(t) { + const root = mkdtempSync(join(tmpdir(), "mosaic-watch-")); + t.after(() => rmSync(root, { recursive: true, force: true })); + return root; +} + +// 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"; +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 }) { + const a = JSON.parse(readFileSync(env.WATCH_ANSWER, "utf8"))[${JSON.stringify(name)}]; + if (a === "throw") throw new Error("inspect failed at " + env.WATCH_SECRET); + if (a === "hang") return new Promise(() => {}); + return a; +}` : ""} +`; + +// A scratch plugin tree whose harness directory holds only the named stand-ins, and its watch. +async function watchTree(t, harnesses) { + const tr = tree(t); + for (const [name, opts] of Object.entries(harnesses)) tr.write("harness", name, standIn(name, opts)); + const { watchHarnesses } = await import(pathToFileURL(join(tr.pkg, "src", "harness-watch.mjs")).href); + const dir = scratch(t); + const file = join(dir, "answer.json"); + const pass = async (answers, { last = [], env = {}, timeoutMs = 2000 } = {}) => { + writeFileSync(file, JSON.stringify(answers)); + return watchHarnesses({ last, env: { WATCH_ANSWER: file, ...env }, scratch: dir, timeoutMs }); + }; + return { pass, dir }; +} + +const ok = (digest, extra = {}) => ({ found: true, source: "PATH", version: "1.0.0", digest, fit: "pass", definite: true, failed: [], line: "passed", surfaces: {}, ...extra }); +const byName = (out) => Object.fromEntries(out.records.map((r) => [r.harness, r])); + +test("W1 discovery: every harness the loader gives is watched, with no name list in the watch", async (t) => { + // Names made for this run, so nothing in the watch could have listed them. + const names = [`w${process.pid}-one`, `w${process.pid}-two`, `w${process.pid}-three`].sort(); + const { pass } = await watchTree(t, { [names[0]]: {}, [names[1]]: { inspect: false }, [names[2]]: {} }); + const out = await pass({ [names[0]]: ok(DIGEST_A), [names[2]]: ok(DIGEST_B) }, { env: { WATCH_VERSION: "3.1.4" } }); + assert.deepEqual(out.records.map((r) => r.harness).sort(), names); + assert.deepEqual(out.refused, []); + const r = byName(out); + assert.equal(r[names[0]].via, "inspect"); + assert.equal(r[names[1]].via, "version"); + assert.equal(r[names[2]].digest, DIGEST_B); + // The watch's source names no harness: no quoted name and no bare word for a shipped one. + const src = readFileSync(WATCH_SRC, "utf8").replace(/^\s*\/\/.*$/gm, ""); + assert.doesNotMatch(src, /["'`](?:pi|claude|claude-code|codex)["'`]/); + assert.doesNotMatch(src, /\b(?:claude|codex)\b|\bpi\b/i); +}); + +test("W1 the version fallback: a harness with no inspect is watched through version() and is unknown", async (t) => { + const { pass } = await watchTree(t, { plain: { inspect: false } }); + let rec = byName(await pass({}, { env: { WATCH_VERSION: "2.0.0" } })).plain; + assert.deepEqual([rec.state, rec.via, rec.version, rec.fit, rec.found, rec.digest], ["unknown", "version", "2.0.0", "unknown", null, null]); + rec = byName(await pass({}, {})).plain; + assert.deepEqual([rec.state, rec.version], ["unknown", null]); + rec = byName(await pass({}, { env: { WATCH_VERSION: "throw", WATCH_SECRET: "/srv/hidden-value" } })).plain; + assert.deepEqual([rec.state, rec.line], ["unknown", "version failed"]); +}); + +test("W1 each state from a pair of records: same digest, new digest, fail, undecided, throw, timeout, not found", async (t) => { + const { pass } = await watchTree(t, { h: {} }); + const first = await pass({ h: ok(DIGEST_A) }); + const prior = first.records; + assert.equal(byName(first).h.state, "fit"); + const cases = [ + ["same digest, fit pass", ok(DIGEST_A), "fit"], + ["new digest, fit pass", ok(DIGEST_B), "changed"], + ["fit fail, definite", ok(DIGEST_B, { fit: "fail", definite: true, failed: ["C5"], line: "lacks --no-mcp" }), "red"], + ["fit fail, not definite", ok(DIGEST_B, { fit: "fail", definite: false }), "unknown"], + ["fit unknown", ok(DIGEST_B, { fit: "unknown" }), "unknown"], + ["inspect throws", "throw", "unknown"], + ["inspect times out", "hang", "unknown"], + ["binary not found", { found: false, source: null, version: null, digest: null, fit: "unknown", definite: false, failed: [], line: "no binary", surfaces: {} }, "missing"], + // Answers that are not the contract's never read as fit. + ["fit spelled otherwise", ok(DIGEST_A, { fit: "PASS" }), "unknown"], + ["found not a boolean", ok(DIGEST_A, { found: "yes" }), "unknown"], + ["no answer", null, "unknown"], + ["a pass with found false", ok(DIGEST_A, { found: false }), "missing"], + ]; + for (const [what, answer, state] of cases) { + const out = await pass({ h: answer }, { last: prior, timeoutMs: 300 }); + assert.equal(byName(out).h.state, state, what); + } + const red = byName(await pass({ h: ok(DIGEST_B, { fit: "fail", definite: true, failed: ["C5", "bad id with spaces"], line: "lacks --no-mcp" }) }, { last: prior })).h; + assert.deepEqual([red.failed, red.line, red.definite], [["C5"], "lacks --no-mcp", true]); + const late = byName(await pass({ h: "hang" }, { last: prior, timeoutMs: 300 })).h; + assert.equal(late.line, "inspect did not answer in time"); +}); + +test("W1 a transition is reported only when the state or the digest changes", async (t) => { + const { pass } = await watchTree(t, { h: {}, k: {} }); + const one = await pass({ h: ok(DIGEST_A), k: ok(DIGEST_A) }); + assert.deepEqual(one.transitions.map((x) => [x.harness, x.from, x.to.state]), [["h", null, "fit"], ["k", null, "fit"]]); + // Same answers: no transition, and changedAt stays the first pass's. + const two = await pass({ h: ok(DIGEST_A), k: ok(DIGEST_A, { version: "1.0.1", line: "another line" }) }, { last: one.records }); + assert.deepEqual(two.transitions, []); + assert.equal(byName(two).h.changedAt, byName(one).h.changedAt); + // A state change is a transition, with or without a new digest. + const three = await pass({ h: ok(DIGEST_B), k: ok(DIGEST_A, { fit: "fail", definite: true }) }, { last: two.records }); + assert.deepEqual(three.transitions.map((x) => [x.harness, x.from.state, x.to.state, x.from.digest, x.to.digest]), + [["h", "fit", "changed", DIGEST_A, DIGEST_B], ["k", "fit", "red", DIGEST_A, DIGEST_A]]); + const four = await pass({ h: ok(DIGEST_B, { fit: "unknown" }), k: ok(DIGEST_A, { fit: "fail", definite: true }) }, { last: three.records }); + // A new digest with the state unchanged (unknown to unknown) is a transition too. + const five = await pass({ h: ok(DIGEST_A, { fit: "unknown" }), k: ok(DIGEST_A, { fit: "fail", definite: true }) }, { last: four.records }); + assert.deepEqual(five.transitions.map((x) => [x.harness, x.from.state, x.to.state]), [["h", "unknown", "unknown"]]); + // A harness the loader no longer gives is named in gone, and has no record. + const six = await pass({ h: ok(DIGEST_A) }, { last: [...five.records, { harness: "removed", state: "fit", digest: DIGEST_A }] }); + assert.deepEqual(six.gone, ["removed"]); +}); + +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"; + const env = { WATCH_SECRET: secret, HOME: join(dir, "home"), MOSAIC_FIXTURE_BIN: "/opt/fixture/bin/tool", PATH: "/opt/fixture-tools/bin:/usr/bin:/bin" }; + const answer = ok(DIGEST_A, { + source: dir, version: `9.9 at ${dir}/bin`, + line: `found at ${env.MOSAIC_FIXTURE_BIN} in ${secret}, home ${env.HOME}, ${realpathSync(dir)}`, + surfaces: { help: `usage: ${dir}/tool\nsee /opt/fixture-tools/bin/tool and ${tmpdir()}`, "Bad Name": dir }, + }); + const out = await pass({ h: answer }, { env }); + const text = JSON.stringify(out); + for (const p of [dir, realpathSync(dir), secret, env.MOSAIC_FIXTURE_BIN, "/opt/fixture-tools/bin", env.HOME, tmpdir()]) assert.ok(!text.includes(p), p); + const rec = byName(out).h; + assert.equal(rec.source, null, "a source that is a path is dropped"); + assert.deepEqual(Object.keys(rec.surfaces), ["help"]); + assert.match(rec.line, //); + assert.match(rec.surfaces.help, /\/tool/); +}); + +test("W1 real pi from node_modules gives a version, a digest and fit pass", NO_BWRAP, async (t) => { + const dir = scratch(t); + const env = { PATH: "/usr/bin:/bin" }; + const r = await pi.inspect({ env, scratch: dir }); + const pkg = JSON.parse(readFileSync(join(REPO, "node_modules", PI_NAME, "package.json"), "utf8")); + assert.equal(r.fit, "pass", r.line); + assert.deepEqual([r.found, r.source, r.version, r.definite], [true, "repo", pkg.version, true]); + assert.match(r.digest, /^[a-f0-9]{64}$/); + const { watchHarnesses } = await import(pathToFileURL(WATCH_SRC).href); + const out = await watchHarnesses({ env, scratch: dir }); + const rec = out.records.find((x) => x.via === "inspect" && x.source === "repo"); + assert.deepEqual([rec.state, rec.digest, rec.version], ["fit", r.digest, pkg.version]); + const text = JSON.stringify(out); + for (const p of [dir, REPO, realpathSync(join(REPO, "node_modules"))]) assert.ok(!text.includes(p), p); +}); + +// A stand-in pi package named by MOSAIC_PI_BIN, as pi-fit.test.mjs makes one. +function piPackage(t, knobs) { + const root = scratch(t); + const pkg = join(root, "prefix", "lib", "node_modules", PI_NAME); + mkdirSync(join(pkg, "dist", "bundle"), { recursive: true }); + writeFileSync(join(pkg, "package.json"), JSON.stringify({ name: PI_NAME, version: "2.0.0", bin: { pi: "dist/bundle/cli.js" } })); + writeFileSync(join(pkg, "dist", "bundle", "cli.js"), piStandIn({ version: "2.0.0", ...knobs }), { mode: 0o755 }); + mkdirSync(join(root, "prefix", "bin")); + symlinkSync(`../lib/node_modules/${PI_NAME}/dist/bundle/cli.js`, join(root, "prefix", "bin", "pi")); + return { root, env: { MOSAIC_PI_BIN: join(root, "prefix", "bin", "pi"), PATH: "/usr/bin:/bin" } }; +} + +test("W1 pi inspect shares preflight's fit check: a binary that passed is not checked again", NO_BWRAP, async (t) => { + const s = piPackage(t, {}); + // A fit check makes its scratch directories in TMPDIR. Control: preflight's check is seen making + // them. Then inspect, on the binary that passed, must make none. + const made = []; + const watcher = watch(tmpdir(), (_, name) => { if (String(name).startsWith("mosaic-pi-fit-")) made.push(name); }); + t.after(() => watcher.close()); + const settle = () => new Promise((done) => setTimeout(done, 200)); + assert.equal(await pi.preflight({ env: { ...s.env, ZAI_API_KEY: "fixture-zai" } }), null); + await settle(); + assert.ok(made.length > 0, "the watcher sees a fit check run"); + made.length = 0; + const r = await pi.inspect({ env: s.env }); + await settle(); + assert.deepEqual(made, []); + assert.deepEqual([r.fit, r.source, r.version], ["pass", "MOSAIC_PI_BIN", "2.0.0"]); + assert.ok(!JSON.stringify(r).includes(s.root)); +}); + +test("W1 pi inspect: a definite failure is fail, one that can't be checked is unknown, no binary is not found", NO_BWRAP, async (t) => { + const lacking = piPackage(t, { dropFlags: ["--no-skills"] }); + let r = await pi.inspect({ env: lacking.env }); + assert.deepEqual([r.found, r.fit, r.definite, r.digest, r.version, r.line], [true, "fail", true, null, "2.0.0", "pi 2.0.0 (MOSAIC_PI_BIN) lacks --no-skills"]); + const flood = piPackage(t, { flood: true }); + r = await pi.inspect({ env: flood.env }); + assert.deepEqual([r.fit, r.definite], ["unknown", false], r.line); + assert.match(r.line, /can't be checked/); + r = await pi.inspect({ env: { MOSAIC_PI_BIN: "relative/pi", PATH: "/usr/bin:/bin" } }); + assert.deepEqual([r.found, r.source, r.line], [false, "MOSAIC_PI_BIN", "MOSAIC_PI_BIN isn't an executable file at an absolute path"]); +}); + +const sha256 = (file) => new Promise((done, fail) => { + const h = createHash("sha256"); + createReadStream(file).on("error", fail).on("data", (c) => h.update(c)).on("end", () => done(h.digest("hex"))); +}); + +const CLAUDE = process.env.MOSAIC_CLAUDE_BIN; +test("W1 the real claude binary named by MOSAIC_CLAUDE_BIN gives a version, a sha256 and its help", CLAUDE ? {} : { skip: "MOSAIC_CLAUDE_BIN is not set" }, async (t) => { + const dir = scratch(t); + const env = { MOSAIC_CLAUDE_BIN: CLAUDE, PATH: "/usr/bin:/bin" }; + const r = await claude.inspect({ env, scratch: dir }); + assert.deepEqual([r.found, r.source, r.fit, r.definite], [true, "MOSAIC_CLAUDE_BIN", "unknown", false]); + assert.match(r.version, /\d+\.\d+\.\d+/); + assert.equal(r.digest, await sha256(realpathSync(CLAUDE))); + assert.match(r.surfaces.help, /--version/); + const { watchHarnesses } = await import(pathToFileURL(WATCH_SRC).href); + const out = await watchHarnesses({ env, scratch: dir }); + const rec = out.records.find((x) => x.source === "MOSAIC_CLAUDE_BIN"); + assert.deepEqual([rec.state, rec.digest, rec.version], ["unknown", r.digest, r.version]); + assert.ok(!JSON.stringify(out).includes(CLAUDE)); + // The scratch HOME it ran in is gone. + assert.deepEqual(readdirNames(dir), []); +}); + +test("W1 claude-code inspect: no binary is not found, naming the variable; no scratch runs nothing", async (t) => { + let r = await claude.inspect({ env: { MOSAIC_CLAUDE_BIN: "relative/claude" }, scratch: scratch(t) }); + 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]); + 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 }); + r = await claude.inspect({ env: { PATH: join(dir, "bin") } }); + assert.deepEqual([r.found, r.source, r.version, r.surfaces], [true, "PATH", null, {}]); + assert.equal(r.digest, await sha256(join(dir, "bin", "claude"))); + assert.deepEqual(readdirNames(join(dir, "bin")), ["claude"], "nothing ran without scratch"); +}); + +function readdirNames(dir) { + return readdirSync(dir).sort(); +} -- 2.54.0 From af8c2f97773eb26b0081dc623ec670e6c71da846 Mon Sep 17 00:00:00 2001 From: Jason Woltje Date: Fri, 20 Nov 2026 04:12:24 -0600 Subject: [PATCH 2/3] 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 () and any absolute path left (), 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) --- packages/plugins/README.md | 38 +++-- .../plugins/harness/claude-code/index.mjs | 14 +- packages/plugins/harness/pi/index.mjs | 10 +- packages/plugins/src/harness-watch.mjs | 138 ++++++++++++---- packages/plugins/tests/harness-watch.test.mjs | 154 +++++++++++++++++- 5 files changed, 300 insertions(+), 54 deletions(-) diff --git a/packages/plugins/README.md b/packages/plugins/README.md index d4a3ab5dd..27d6a357c 100644 --- a/packages/plugins/README.md +++ b/packages/plugins/README.md @@ -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 ``, then any other absolute path +of two segments or more with ``. 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) diff --git a/packages/plugins/harness/claude-code/index.mjs b/packages/plugins/harness/claude-code/index.mjs index 9f82533cf..3628cfae7 100644 --- a/packages/plugins/harness/claude-code/index.mjs +++ b/packages/plugins/harness/claude-code/index.mjs @@ -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 } }; diff --git a/packages/plugins/harness/pi/index.mjs b/packages/plugins/harness/pi/index.mjs index fbf417297..f7d62c708 100644 --- a/packages/plugins/harness/pi/index.mjs +++ b/packages/plugins/harness/pi/index.mjs @@ -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 (