diff --git a/packages/plugins/README.md b/packages/plugins/README.md index 5c85e306d..bdb0d1e95 100644 --- a/packages/plugins/README.md +++ b/packages/plugins/README.md @@ -367,6 +367,87 @@ 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, after pi's lookup label, starts with "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 +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, 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 + shape; +- `missing`: `inspect` says `found: false`. + +Only `found: true` with `fit: "pass"` reads as `fit` or `changed`. The watch +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, and only when both +records have a version: a timeout or a throw knows none, and is not a new +binary. So unknown 2.0, a timeout, then unknown 2.1, all with no digest, +gives no transition for the version; W1 keeps no last known version. + +The redaction applies to the stored surfaces too, so a surface is for +display and comparison, not for fit rules: with USER set to `model`, the +stored `help` reads `--` where claude printed `--model`. A fit rule +(slice W2's flag check, for one) runs inside the module on the text the +binary printed and puts its answer in `fit`, `failed` and `line`. + ## 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..3628cfae7 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,61 @@ 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. 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, 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" }; + 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(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 } }; + } 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..f7d62c708 100644 --- a/packages/plugins/harness/pi/index.mjs +++ b/packages/plugins/harness/pi/index.mjs @@ -55,6 +55,28 @@ 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 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 = {} } = {}) { + 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: {} }; + // Read after pi-fit's "pi (