fix(cli,plugins,harness): harness-watch-w2 review: pi-fit's two whole-result tests carry digest and undecided, and pi-binary's copy links packages/plugins/src (P2-1, P2-2); the claude fit rule counts a flag only from an option line read up to its description, so a flag a description only mentions is a miss (P2-3); on a cache miss preflight asks the bus host's watch for a pass at once (new src/watch-request.mjs: a stat pass now, a full pass on a changed key, one tick after a running pass, none after stop), and stays synchronous, so the launch that missed and launches before the first pass ends still go ahead (P2-4, the rest named in the README); the watch redacts word:/path, file:// and ~/ forms (P3-5); each claude capture kills its process group when it ends too and runs nothing on an aborted signal, the unobservable key-equal guard is dropped, pi inspect takes its check as an option, the host backstop leaves kept and source alone, and tests now fail without the group kill, the stop grace, the verdict cap, the early abort, the backstop's data root, home and process env needles and pi's undecided read (P3-6) (#1873, lane harness-watch-w2)

This commit is contained in:
jason.woltje committed 2026-11-20 07:29:22 -06:00
1 parent 7afe892e94
commit f2463ab36d
11 files changed
+330 -47

No files matched your search

+23 -4
View File
@@ -9,6 +9,10 @@
// halted/invalid while processing is halted or invalid (processingStatus), no pass at all; the
// first tick after it clears runs a full pass
//
// A harness module may ask for a stat pass now (packages/plugins/src/watch-request.mjs; claude-code's
// preflight asks when it has no verdict for its binary): it runs at once, or right after the pass
// running, and runs a full pass only when the key changed, as a tick does.
//
// One pass at a time: a tick that comes while a pass runs does nothing. A pass that throws is
// logged, with no path in the line, and the timer goes on; its key is not kept, so the next tick
// runs a full pass again. stop() clears the timer, aborts the pass running (the watch aborts the
@@ -31,6 +35,7 @@ import { join } from "node:path";
import { loadInstalled } from "../../plugins/src/loader.mjs";
import { watchHarnesses } from "../../plugins/src/harness-watch.mjs";
import { statKey } from "../../plugins/src/stat-key.mjs";
import { onWatchRequest } from "../../plugins/src/watch-request.mjs";
import { processingStatus } from "../../processing-control/src/state.mjs";
export const STAT_MS = 5 * 60 * 1000;
@@ -81,12 +86,14 @@ export function startHarnessWatch({
dayMs = DAY_MS,
timeoutMs = undefined,
scratchRoot = () => tmpdir(),
requests = onWatchRequest,
} = {}) {
if (typeof dataRoot !== "string" || !dataRoot) throw new TypeError("startHarnessWatch needs the organization's dataRoot");
const control = new AbortController();
let stopped = false;
let running = null;
let held = false;
let again = false;
let needFull = true;
let lastKey = null;
let lastFull = null;
@@ -123,11 +130,22 @@ export function startHarnessWatch({
if (stopped || running) return;
running = pass()
.catch((e) => { if (!stopped) log(`harness watch: a pass failed (${failure(e)}); the timer goes on`); })
.finally(() => { running = null; });
.finally(() => {
running = null;
if (again && !stopped) { again = false; tick(); }
});
}
// A request runs a tick now, or once right after the pass running.
function request() {
if (stopped) return;
if (running) again = true;
else tick();
}
const timer = clock.setInterval(tick, statMs);
timer?.unref?.();
const unlisten = typeof requests === "function" ? requests(request) : null;
tick();
return Object.freeze({
@@ -136,6 +154,7 @@ export function startHarnessWatch({
if (!stopped) {
stopped = true;
clock.clearInterval(timer);
if (typeof unlisten === "function") unlisten();
control.abort();
}
await (running ?? Promise.resolve());
@@ -183,9 +202,9 @@ function store(dataRoot, result, { env, scratch, at }) {
// Whether a value holds a path the host knows (the scratch directory, the home directory, the data
// root) or an env value of VALUE_MIN characters or more, the host's or the launch env's, in any of
// its strings. Names the watch sets itself are not text and are skipped: a harness or module name
// (an env value may name the harness), a state, a fit, a via, a time or a digest.
const NOT_TEXT = new Set(["harness", "gone", "name", "code", "state", "fit", "via", "at", "checkedAt", "changedAt", "digest", "lastDigest"]);
function leakChecker({ env, scratch, dataRoot }) {
// (an env value may name the harness), a lookup step, a state, a fit, a via, a time or a digest.
const NOT_TEXT = new Set(["harness", "gone", "name", "kept", "source", "code", "state", "fit", "via", "at", "checkedAt", "changedAt", "digest", "lastDigest"]);
export function leakChecker({ env, scratch, dataRoot }) {
const needles = new Set();
const add = (v) => { if (typeof v === "string" && v.length >= VALUE_MIN) needles.add(v); };
for (const p of [scratch, dataRoot, homedir()]) add(p);
+106 -2
View File
@@ -3,14 +3,16 @@
// with stand-in harnesses, and one through startHost.
import test from "node:test";
import assert from "node:assert/strict";
import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, utimesSync, writeFileSync } from "node:fs";
import { homedir, tmpdir } from "node:os";
import { join } from "node:path";
import { DAY_MS, STAT_MS, startHarnessWatch, watchFile, watchLog } from "../src/harness-watch-host.mjs";
import { DAY_MS, STAT_MS, leakChecker, startHarnessWatch, watchFile, watchLog } from "../src/harness-watch-host.mjs";
import { bootConfig, loadSystem } from "../src/config.mjs";
import { startHost } from "../src/host.mjs";
import { makeDeployment } from "../../discord/tests/helpers.mjs";
import { fixture, tmp } from "./helpers.mjs";
import { requestWatch } from "../../plugins/src/watch-request.mjs";
import * as claude from "../../plugins/harness/claude-code/index.mjs";
function scratch(t) {
const root = mkdtempSync(join(tmpdir(), "mosaic-hw-"));
@@ -302,6 +304,108 @@ test("W2 host watch through the real watch: stand-in harnesses that print a scra
assert.equal(JSON.parse(readFileSync(watchFile(dataRoot), "utf8")).harnesses.find((r) => r.source === "MOSAIC_CLAUDE_BIN").version, "1.0.1");
});
// Review P3-6: each needle of the backstop on its own: the data root, the home directory (with HOME
// unset, so no env value covers it) and a value only the host process's env holds.
test("W2 host watch: the backstop knows the data root, the home directory and the host's own env values", () => {
const leaks = leakChecker({ env: {}, scratch: "/fixture-scratch-x", dataRoot: "/fixture-data-root/org" });
assert.equal(leaks({ line: "at /fixture-data-root/org/state" }), true);
assert.equal(leaks({ line: "at /fixture-scratch-x/home" }), true);
assert.equal(leaks({ line: "nothing here" }), false);
assert.equal(leaks({ harness: "/fixture-data-root/org" }), false, "a name field is not text");
const saved = process.env.HOME;
process.env.FIXTURE_HW_ONLY = "fixture-process-only-77";
try {
delete process.env.HOME;
const home = homedir();
const bare = leakChecker({ env: {}, scratch: "/fixture-scratch-x", dataRoot: "/fixture-data-root/org" });
assert.equal(bare({ version: `1.0 ${home}` }), true, "the home directory");
assert.equal(bare({ line: "token fixture-process-only-77" }), true, "a value of the host process's env");
} finally {
process.env.HOME = saved;
delete process.env.FIXTURE_HW_ONLY;
}
});
// Review P3-5: a file: URL, a host:/path and a ~/ path a binary prints are paths too, and reach
// neither file.
test("W2 host watch through the real watch: a file: URL, a host:/path and a ~/ path in a version reach neither file", async (t) => {
const root = scratch(t);
const dataRoot = join(root, "org");
mkdirSync(dataRoot);
const bin = join(root, "bin", "claude");
mkdirSync(join(root, "bin"));
writeFileSync(bin, `#!/bin/sh\ncase "$1" in\n--version) echo "1.0 file:///opt/fixture-tree/bin/claude host:/srv/fixture-a/b ~/.local/share/fixture/claude";;\n--help) echo "usage";;\n*) exit 3;;\nesac\n`, { mode: 0o755 });
const env = { MOSAIC_CLAUDE_BIN: bin, MOSAIC_PI_BIN: join(root, "no-pi"), PATH: "/usr/bin:/bin", HOME: join(root, "home") };
const h = startHarnessWatch({ dataRoot, env, clock: fakeClock(), log: () => {}, processing: () => ({ halted: false }), scratchRoot: () => root });
t.after(() => h.stop());
await h.settled();
const json = readFileSync(watchFile(dataRoot), "utf8");
const jsonl = readFileSync(watchLog(dataRoot), "utf8");
assert.equal(JSON.parse(json).harnesses.find((r) => r.source === "MOSAIC_CLAUDE_BIN").version, "1.0 <path> host:<path> <path>");
for (const text of [json, jsonl]) for (const needle of ["fixture-tree", "/srv/", "fixture-a", "~/", "/fixture/claude"]) assert.ok(!text.includes(needle), `no ${needle} in a state file`);
});
// Review P2-4: a module asks for a stat pass now (claude-code's preflight, with no verdict). It runs
// at once, or once after the pass running, and a full pass only when the key changed.
test("W2 host watch: a request runs a stat pass now, a full pass only on a changed key, once after a running pass, none after stop", async (t) => {
let release = null;
let hold = false;
const stub = stubWatch(() => (hold ? new Promise((done) => { release = () => done({ records: [record()], transitions: [], refused: [], gone: [] }); }) : { records: [record()], transitions: [], refused: [], gone: [] }));
const s = start(t, { stub });
await s.handle.settled();
assert.deepEqual([stub.calls.length, s.keyCalls.length], [1, 1]);
requestWatch();
await s.handle.settled();
assert.deepEqual([stub.calls.length, s.keyCalls.length], [1, 2], "a request with the same key runs a stat pass and no full pass");
s.setKey("k2");
requestWatch();
await s.handle.settled();
assert.equal(stub.calls.length, 2, "a request after the key changed runs a full pass");
// Requests while a pass runs: one more stat pass right after it, however many came.
hold = true;
s.setKey("k3");
requestWatch();
await new Promise((done) => setImmediate(done));
assert.equal(stub.calls.length, 3);
hold = false;
s.setKey("k4");
requestWatch();
requestWatch();
assert.equal(s.keyCalls.length, 4, "no stat pass while a pass runs");
release();
await new Promise((done) => setTimeout(done, 20));
await s.handle.settled();
assert.deepEqual([stub.calls.length, s.keyCalls.length], [4, 5], "one stat pass after it, which saw k4 and ran a full pass");
await s.handle.stop();
requestWatch();
await s.handle.settled();
assert.deepEqual([stub.calls.length, s.keyCalls.length], [4, 5], "after stop a request does nothing");
});
// Review P2-4, through the real watch: a red claude touched after its check has a new stat key, so
// preflight has no verdict for a moment; it asks the watch, whose pass checks it again, and preflight
// refuses again within that pass, not at the next tick.
test("W2 host watch through the real watch: preflight's request re-checks a red claude touched after its check", async (t) => {
const root = scratch(t);
const dataRoot = join(root, "org");
mkdirSync(dataRoot);
const bin = join(root, "bin", "claude");
mkdirSync(join(root, "bin"));
writeFileSync(bin, `#!/bin/sh\ncase "$1" in\n--version) echo "1.0.0";;\n--help) echo "usage: claude [--version]";;\n*) exit 3;;\nesac\n`, { mode: 0o755 });
const env = { MOSAIC_CLAUDE_BIN: bin, MOSAIC_PI_BIN: join(root, "no-pi"), PATH: "/usr/bin:/bin", HOME: join(root, "home") };
const launch = { ...env, ANTHROPIC_API_KEY: "fixture-api-key" };
const clock = fakeClock();
const h = startHarnessWatch({ dataRoot, env, clock, log: () => {}, processing: () => ({ halted: false }), scratchRoot: () => root });
t.after(() => h.stop());
await h.settled();
assert.equal(claude.preflight({ env: launch })?.code, "harness-feature-missing");
chmodSync(bin, 0o700);
utimesSync(bin, new Date(), new Date(Date.now() + 60000));
assert.equal(claude.preflight({ env: launch }), null, "no verdict for the new stat key: this launch is not held");
await h.settled();
assert.equal(claude.preflight({ env: launch })?.code, "harness-feature-missing", "the requested pass checked it again, with no tick");
});
test("W2 startHost with harnessWatch starts the watch in the host, and close stops it", async (t) => {
const root = tmp(t);
const f = fixture(root);
+10 -3
View File
@@ -543,14 +543,21 @@ test("pi-unpin S3 re-check 7: env() refuses while the fit check is still running
assert.equal(pi.env({ policy: { tools: ["read"] }, tools: [], session, env: s.env }).PI_OFFLINE, "1");
});
// #1873 W2: a check that could not run is a failure with the digest of the files it would have run
// and undecided: true, beside its message.
function assertUndecided(r, message) {
assert.deepEqual(r, { ok: false, message, digest: r.digest, undecided: true });
assert.match(r.digest, /^[0-9a-f]{64}$/);
}
test("pi-unpin S3: a check that cannot run refuses", SKIP, async t => {
const s = standIn(t, {});
const r = await piFit(locate(s.env), { levels: LEVELS, bwrap: join(s.root, "no-bwrap") });
assert.deepEqual(r, { ok: false, message: "pi (MOSAIC_PI_BIN) can't be checked: the sandbox (bwrap) is missing" });
assertUndecided(r, "pi (MOSAIC_PI_BIN) can't be checked: the sandbox (bwrap) is missing");
// A sandbox that fails says so without its own error text, which can name a host path.
const broken = join(s.root, "broken-bwrap");
writeFileSync(broken, `#!/bin/sh\necho "bwrap: Can't find source path ${s.root}/x" >&2\nexit 1\n`, { mode: 0o755 });
assert.deepEqual(await piFit(locate(s.env), { levels: LEVELS, bwrap: broken }), { ok: false, message: "pi (MOSAIC_PI_BIN) can't be checked: the sandbox (bwrap) failed" });
assertUndecided(await piFit(locate(s.env), { levels: LEVELS, bwrap: broken }), "pi (MOSAIC_PI_BIN) can't be checked: the sandbox (bwrap) failed");
// An unreadable package is refused before anything runs.
const found = locate(s.env);
rmSync(join(s.root, "prefix", "lib", "node_modules", NAME, "package.json"));
@@ -742,7 +749,7 @@ test("pi-unpin S3 re-check 10: a failed probe names the tool that failed, and on
assert.deepEqual(r.outer, { used: false, why });
}
assert.deepEqual((await fitWith({})).outer, { used: true });
assert.deepEqual(await fitWith({ unshare: refusing, bwrap: broken }), { ok: false, message: "pi (MOSAIC_PI_BIN) can't be checked: the sandbox (bwrap) failed" });
assertUndecided(await fitWith({ unshare: refusing, bwrap: broken }), "pi (MOSAIC_PI_BIN) can't be checked: the sandbox (bwrap) failed");
});
// R10-P2-1: without unshare's outer layer, a bwrap killed in its setup leaves its child waiting for
+30 -10
View File
@@ -396,7 +396,8 @@ returned and gives back `{ records, transitions, refused, gone }`.
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
calls it, so the two share one cache and one running check (a test may pass
its own check as `check`). Its digest is
that check's digest of the binary's files, on a pass and (W2) on a failure
too. W2: a failed check carries `undecided`, true when the check could not
tell and false when the binary definitely failed. `inspect` reads that
@@ -407,17 +408,22 @@ watch waits on them; a check `preflight` also waits on keeps running.
`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.
the watch skips a relative PATH entry, as pi's does. Each capture runs in its
own process group: a stop, a timeout or the capture's end kills the whole
group, so nothing the binary left in the background outlives it, and a signal
already aborted runs nothing.
W2, the claude fit rule: every flag the claude adapter passes appears in
`--help`, and `--version` answers. The flags come from the adapter itself:
`inspect` runs `adapters/claude/adapter.sh` twice against a recorder that
writes its argv (a first turn, which passes `--session-id`, then a second,
which passes `--resume`), so the module holds no list of them. The rule
reads the text the binary printed: every flag token anywhere in it counts,
in an option line or a description, and `--x[-y]` counts as both `--x` and
`--x-y` (claude 2.1.322 names `--system-prompt-file` only as
`--system-prompt[-file]`). A missing flag is `fit: "fail"`, definite, with
reads the text the binary printed. A flag counts only from an option line
(one to four spaces, then `-`), read up to the description; a flag a
description only mentions does not count. `--x[-y]` anywhere in the text
gives `--x-y` when `--x` has its own option line (claude 2.1.322 names
`--system-prompt-file` only as `--system-prompt[-file]` in the `--bare`
description, beside a `--system-prompt` option line). A missing flag is `fit: "fail"`, definite, with
the flag as the rule id; so is `--version` or `--help` exiting non-zero
(rule id `--version` or `--help`). A capture that timed out, was stopped,
could not start or printed too much, or an adapter run that failed, is
@@ -429,7 +435,13 @@ memory by the stat key (`src/stat-key.mjs`) of the binary's real file and
the adapter; `preflight` reads it and refuses `harness-feature-missing` on a
fail. A replaced binary or adapter has another key, so an old verdict no
longer applies. With no verdict, or an undecided one, `preflight` does not
refuse in W2.
refuse in W2. With no verdict it asks for a watch pass at once
(`src/watch-request.mjs`); in the bus host that runs a stat pass now, and a
full pass when the key changed, so a binary or adapter touched after its
check is checked again within one pass. `preflight` stays synchronous and
does not wait for that pass: the launch that missed, any launch before the
first full pass at host start ends, and any launch while the pass runs go
ahead. With no listener (no bus host) the request does nothing.
`watchKey({ env })` is a second optional export: a string the bus host's
timer compares every five minutes (W2). It changes when anything the module
@@ -462,7 +474,9 @@ 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`
of two segments or more with `<path>`, including one after a `word:` (as in
`host:/srv/a`), a `file://` URL and a `~/` or `~name/` 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
@@ -495,7 +509,10 @@ that key changed or a day has gone by. While processing is halted or
invalid it runs nothing; the first tick after resume runs a full pass. A
tick while a pass runs does nothing. A pass that throws is logged with no
path and the timer goes on; its key is not kept, so the next tick tries
again. Stopping the host clears the timer and aborts the pass running.
again. Stopping the host clears the timer and aborts the pass running. A
request from `src/watch-request.mjs` (preflight's, on a miss) runs a tick at
once; a request while a pass runs runs one tick after it, and a request
after stop does nothing.
The host is the one writer of two files under `<org dataRoot>/state/`:
@@ -506,7 +523,10 @@ The host is the one writer of two files under `<org dataRoot>/state/`:
Before either is written, every string in them is checked again for the
scratch directory, the home directory, the data root and any env value of
six characters or more; a hit writes nothing and logs the pass as failed.
six characters or more, from the launch environment and the host's own; a
hit writes nothing and logs the pass as failed. Name, code, state, digest
and time fields (`harness`, `gone`, `name`, `kept`, `source`, `code`,
`state`, `fit`, `via`, the digests and the times) are not checked as text.
## Transcript usage source (row 124)
+33 -17
View File
@@ -13,6 +13,7 @@ import { claudeBuiltins, MCP_PREFIX } from "../../../harness/src/gate.mjs";
import { hasSessionCredential, SESSION_CREDENTIALS } from "../../../seat/src/session.mjs";
import { UNSHARE } from "../../../seat/src/sandbox.mjs";
import { statKey } from "../../src/stat-key.mjs";
import { requestWatch } from "../../src/watch-request.mjs";
export const interfaceVersion = 1;
@@ -73,8 +74,12 @@ export function preflight({ env, proxy = null }) {
}
// #1873 harness watch W2: the fit verdict the last check of this very file gave (inspect below),
// found by the stat key of its real file and the adapter's. Only a definite failure refuses. No
// verdict, or a check that could not tell, does not refuse in this slice.
// verdict, or a check that could not tell, does not refuse in this slice. With no verdict, the
// bus host's watch is asked for a stat pass now (src/watch-request.mjs), so a binary replaced,
// touched or moved since the last check is checked within one pass, not at the next tick; this
// launch is not held for it.
const verdict = verdictFor(bin);
if (!verdict) requestWatch();
if (verdict?.fit === "fail") {
return { code: "harness-feature-missing", message: `the claude from ${env.MOSAIC_CLAUDE_BIN ? "MOSAIC_CLAUDE_BIN" : "PATH"} failed the fit check: ${verdict.why}` };
}
@@ -111,9 +116,11 @@ export function version({ env }) {
// come from the adapter itself: adapter.sh runs twice against a stand-in claude that writes its
// argv (once fresh, which passes --session-id, and once with a session id kept, which passes
// --resume), so there is no second list of them here. --help is read on the text the binary
// printed, not on the redacted copy the watch stores: every flag token in it counts, in an option
// line or in a description, and --x[-y] counts as --x and --x-y (claude 2.1.322 names
// --system-prompt-file only as --system-prompt[-file]). A flag missing from it, or --version or
// printed, not on the redacted copy the watch stores. A flag counts only from an option line (one
// to four spaces, then -), where it is named before the description: a flag a description only
// mentions does not count. --x[-y] anywhere in the text gives --x-y when --x has its own option
// line (claude 2.1.322 names --system-prompt-file only as --system-prompt[-file] in the --bare
// description, beside a --system-prompt option line). A flag missing from it, or --version or
// --help exiting non-zero, is fit "fail", definite, with the flag as the rule id. A capture that
// timed out, was stopped, could not start or printed too much, or an adapter run that failed, is
// "unknown": the check could not tell. The captures run with no network: unshare -r -n when it
@@ -142,8 +149,9 @@ export async function inspect({ env = {}, scratch = null, signal, unshare = UNSH
const first = v.why === null ? v.out.split("\n")[0].trim() : "";
const version = first && first.length <= 128 ? first : null;
const verdict = judge({ v, first, help, flags });
// Kept only when it is definite and the binary and the adapter did not change during the check.
if (verdict.definite && key && key === verdictKey(real)) remember(key, { fit: verdict.fit, failed: verdict.failed, why: verdict.why });
// Kept when it is definite, by the key taken before the check: if the binary or the adapter
// changed during it, preflight looks up the new key and does not find this one.
if (verdict.definite && key) remember(key, { fit: verdict.fit, failed: verdict.failed, why: verdict.why });
const line = fence.argv ? verdict.why : `${verdict.why}; run with the network on: ${fence.why}`;
return { ...base, found: true, version, digest, fit: verdict.fit, definite: verdict.definite, failed: verdict.failed, line, surfaces: help.why === null ? { help: help.out } : {} };
} finally {
@@ -170,17 +178,21 @@ function judge({ v, first, help, flags }) {
const failMessage = (failed) => (failed.length === 1 && (failed[0] === "--version" || failed[0] === "--help") ? `${failed[0]} gave no answer` : `--help lacks ${failed.join(" ")}`);
// Every flag token in the help text: a - or -- then a letter, not inside a word. --x[-y] gives
// --x and --x-y.
const HELP_TOKEN = /(?<![A-Za-z0-9_-])--?[A-Za-z][A-Za-z0-9-]*(?:\[[A-Za-z0-9-]+\])?/g;
// The flags --help names in its option lines: a line that starts with one to four spaces then -,
// read up to the first run of two spaces (the option and its aliases, before the description).
// Then --x[-y] anywhere in the text gives --x-y when --x is one of them.
const OPTION_LINE = /^ {1,4}-/;
const HEAD_FLAG = /(?:^|[\s,])(--?[A-Za-z][A-Za-z0-9-]*)(?=$|[\s,=<[])/g;
const BRACKET = /(?<![A-Za-z0-9_-])(--?[A-Za-z][A-Za-z0-9-]*)\[(-[A-Za-z0-9-]+)\]/g;
export function helpFlags(text) {
const all = String(text ?? "");
const out = new Set();
for (const [token] of String(text ?? "").matchAll(HELP_TOKEN)) {
const open = token.indexOf("[");
if (open < 0) { out.add(token); continue; }
out.add(token.slice(0, open));
out.add(token.slice(0, open) + token.slice(open + 1, -1));
for (const line of all.split("\n")) {
if (!OPTION_LINE.test(line)) continue;
const head = line.trim().split(/\s{2,}/)[0];
for (const m of head.matchAll(HEAD_FLAG)) out.add(m[1]);
}
for (const m of all.matchAll(BRACKET)) if (out.has(m[1])) out.add(m[1] + m[2]);
return out;
}
@@ -257,9 +269,11 @@ function sha256(file) {
// Runs argv in its own process group and returns { out, why }: why is null when it exited 0 within
// CAPTURE_TIMEOUT and printed at most CAPTURE_MAX, else "exit" (it exited non-zero: an answer),
// "timed out", "was stopped", "could not start" or "printed too much" (no answer). A timeout, a
// stop or too much output kills the whole group.
// stop or too much output kills the whole group, and so does its end: nothing it left in the
// background outlives the capture. An already aborted signal starts nothing.
function capture(argv, runEnv, signal, cwd = runEnv.HOME) {
return new Promise((resolve) => {
if (signal?.aborted) { resolve({ out: "", why: "was stopped" }); return; }
let child;
try { child = spawn(argv[0], argv.slice(1), { env: runEnv, cwd, stdio: ["ignore", "pipe", "ignore"], detached: true }); } catch { resolve({ out: "", why: "could not start" }); return; }
const out = [];
@@ -272,10 +286,12 @@ function capture(argv, runEnv, signal, cwd = runEnv.HOME) {
const stopped = () => kill("was stopped");
const timer = setTimeout(() => kill("timed out"), CAPTURE_TIMEOUT);
signal?.addEventListener?.("abort", stopped, { once: true });
if (signal?.aborted) stopped();
child.stdout.on("data", (c) => { size += c.length; if (size > CAPTURE_MAX) kill("printed too much"); else out.push(c); });
child.on("error", () => finish("could not start"));
child.on("close", (status) => finish(status === 0 ? null : "exit"));
child.on("close", (status) => {
try { process.kill(-child.pid, "SIGKILL"); } catch {}
finish(status === 0 ? null : "exit");
});
});
}
+3 -2
View File
@@ -66,11 +66,12 @@ export async function version({ env = {} } = {}) {
// the lookup step, never a path. scratch is not used: the fit check makes its own scratch directories.
// signal goes to the fit check (W2): when the watch stops, a check only it waits on is stopped.
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 = {}, signal = null } = {}) {
// check: the fit check to run, piFit unless a test gives a stand-in for it.
export async function inspect({ env = {}, signal = null, check = piFit } = {}) {
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, signal });
const fit = await check(at, { levels: LEVELS, signal });
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 = fit.undecided !== false;
return { found: true, source, version: await printedVersion(at.bin, { signal }), digest: typeof fit.digest === "string" ? fit.digest : null, fit: undecided ? "unknown" : "fail", definite: !undecided, failed: [], line: fit.message, surfaces: {} };
+6 -3
View File
@@ -44,8 +44,11 @@ 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;
// a slash, a dot, a dash, a tilde or a name's closing ">" (https://x/y, ~/x, <home>/x, a/b/c); one
// after a colon is a path (host:/srv/a/b). W2 review P3-5: a file: URL and a ~/ path are paths too.
const LOOSE_PATH = /(?<![\w/.~>-])\/[^\s/'"`<>()[\]{},;]+(?:\/[^\s'"`<>()[\]{},;]*)+/g;
const FILE_URL = /(?<![A-Za-z0-9_])file:\/\/[^\s'"`<>()[\]{},;]*/gi;
const TILDE_PATH = /(?<![\w/.~-])~[A-Za-z0-9._-]*\/[^\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.
@@ -269,6 +272,6 @@ function redactor(env, scratch) {
let out = s;
for (const value of order) if (out.includes(value)) out = out.split(value).join(pairs.get(value));
if (word) out = out.replace(word, "<user>");
return out.replace(LOOSE_PATH, "<path>");
return out.replace(FILE_URL, "<path>").replace(TILDE_PATH, "<path>").replace(LOOSE_PATH, "<path>");
};
}
+20
View File
@@ -0,0 +1,20 @@
// #1873 harness watch W2: a harness module asks the bus host's watch for a stat pass now, instead
// of at the next five-minute tick. claude-code's preflight asks when it has no verdict for the
// binary it found (a binary or adapter replaced, touched or moved since the last check, or a host
// that just started). The host's watch (packages/cli/src/harness-watch-host.mjs) listens in the
// same process; with no listener (a Console, a test, a launch outside a bus host) the request does
// nothing. A request carries nothing: the watch compares its own stat key and runs a full pass
// only when it changed, so a flood of requests costs one stat pass each and no extra full pass.
const listeners = new Set();
// Calls fn on each request until the returned function is called.
export function onWatchRequest(fn) {
listeners.add(fn);
return () => { listeners.delete(fn); };
}
export function requestWatch() {
for (const fn of [...listeners]) {
try { fn(); } catch {}
}
}
@@ -34,13 +34,16 @@ function scratch(t) {
// The help a claude that has every flag the adapter passes would print (a test fixture; the module
// itself reads the flags from adapter.sh). --system-prompt-file shows only as --system-prompt[-file],
// as on claude 2.1.322.
// as on claude 2.1.322. Descriptions also mention flags (--settings, --mcp-config, --model), as
// claude's do; only the option lines count.
const HELP_LINES = [
"Usage: claude [options] [command] [prompt]", "", "Options:",
" -p, --print Print response and exit",
" --output-format <format> text, json or stream-json",
" --verbose Verbose output",
" --include-partial-messages Partial message chunks",
" --include-partial-messages Partial message chunks",
" --bare Minimal mode: no --settings files, no --mcp-config servers,",
" --settings and --model still apply",
" --system-prompt <prompt> System prompt; also --system-prompt[-file]",
" --model <model> Model",
" --effort <level> Effort",
@@ -57,7 +60,8 @@ const HELP_LINES = [
" -v, --version Version",
" -h, --help Help",
];
const help = ({ drop = [], extra = [] } = {}) => [...HELP_LINES.filter((l) => !drop.some((d) => new RegExp(`(^|[ ,])${d}([ ,<\\[]|$)`).test(l))), ...extra].join("\n");
// drop removes the option line that names a flag (its head, not a mention in a description).
const help = ({ drop = [], extra = [] } = {}) => [...HELP_LINES.filter((l) => !drop.some((d) => new RegExp(`^ (?:-[A-Za-z], )?${d}(?=[ ,<\\[]|$)`).test(l))), ...extra].join("\n");
// A stand-in claude: --version prints version (or exits versionExit), --help prints text (or exits
// helpExit, or sleeps with helpHang), anything else exits 3. With nsFile it writes the network
@@ -116,7 +120,19 @@ test("W2 claude-code: --resume, which only a later turn passes, is checked too,
const prose = help({ drop: ["--system-prompt"], extra: [" --append-system-prompt <prompt> Append; see --system-prompt-files"] });
const s = await claude.inspect({ env: { MOSAIC_CLAUDE_BIN: standIn(join(dir, "b"), { helpText: prose }) }, scratch: scratch(t) });
assert.deepEqual([s.fit, s.failed], ["fail", ["--system-prompt-file"]], "a longer token or a token inside a word is not the flag");
assert.deepEqual([...claude.helpFlags("use -p/--print or --system-prompt[-file]; non-interactive")].sort(), ["--print", "--system-prompt", "--system-prompt-file", "-p"]);
// Only option lines count; --x[-y] in prose gives --x-y only beside an --x option line.
assert.deepEqual([...claude.helpFlags("use -p/--print or --system-prompt[-file]; non-interactive")], []);
assert.deepEqual([...claude.helpFlags(" -c, --continue Continue\n --system-prompt <p> Prompt\n see --system-prompt[-file], --zz[-q]\n --settings in prose")].sort(), ["--continue", "--system-prompt", "--system-prompt-file", "-c"]);
});
// Review P2-3: a flag a description mentions is not an option. A claude whose help lost the
// --settings and --mcp-config option lines, though other descriptions still name both, is red.
test("W2 claude-code: a flag only a description mentions does not count", async (t) => {
const text = help({ drop: ["--settings", "--mcp-config"] });
assert.match(text, /--settings/);
assert.match(text, /--mcp-config/);
const r = await claude.inspect({ env: { MOSAIC_CLAUDE_BIN: standIn(scratch(t), { helpText: text }) }, scratch: scratch(t) });
assert.deepEqual([r.fit, r.definite, [...r.failed].sort()], ["fail", true, ["--mcp-config", "--settings"]], r.line);
});
test("W2 claude-code: the flags come from adapter.sh, not a list in the module", async (t) => {
@@ -248,7 +264,8 @@ test("W2 an undecided pi check is unknown from its undecided field; pi's inspect
// A scratch plugin tree of stand-in harnesses: each inspect writes <MARKS>/<name> when it is
// asked, then answers its entry of the JSON file WATCH_ANSWER names; "hang-signal" waits for its
// signal and writes <MARKS>/<name>.aborted when it aborts.
// signal and writes <MARKS>/<name>.aborted when it aborts; "slow-stop" ends 300 ms after its signal
// aborts and writes <MARKS>/<name>.ended then.
const marker = (name) => `import { readFileSync, writeFileSync } from "node:fs";
export const interfaceVersion = ${KINDS.harness.interfaceVersion};
${KINDS.harness.exports.map((e) => `export function ${e}() { return null; }`).join("\n")}
@@ -256,6 +273,7 @@ export async function inspect({ env, signal }) {
writeFileSync(env.MARKS + "/${name}", "1");
const a = JSON.parse(readFileSync(env.WATCH_ANSWER, "utf8"))[${JSON.stringify(name)}];
if (a === "hang-signal") return new Promise(() => { signal.addEventListener("abort", () => writeFileSync(env.MARKS + "/${name}.aborted", "1")); });
if (a === "slow-stop") return new Promise((done) => { signal.addEventListener("abort", () => setTimeout(() => { writeFileSync(env.MARKS + "/${name}.ended", "1"); done({ found: true }); }, 300)); });
return a;
}
`;
@@ -293,3 +311,73 @@ test("W2 the watch keeps flag rule ids and still drops ones that are not names",
assert.deepEqual(out.records[0].failed, ["--strict-mcp-config", "-p", "C1"]);
assert.equal(out.records[0].state, "red");
});
// Review P3-6: a stop waits for the inspect it aborted to end (up to the grace), so what it started
// is gone when the watch returns.
test("W2 a stopped watch returns after the inspect it aborted has ended", async (t) => {
const w = await markerTree(t, ["slow"]);
writeFileSync(w.env.WATCH_ANSWER, JSON.stringify({ slow: "slow-stop" }));
const stop = new AbortController();
setTimeout(() => stop.abort(), 100);
const out = await w.watchHarnesses({ env: w.env, scratch: w.dir, signal: stop.signal, timeoutMs: 60000 });
assert.equal(out.stopped, true);
assert.ok(existsSync(join(w.env.MARKS, "slow.ended")), "the watch waited for the inspect to end");
});
const alive = (pid) => { try { process.kill(pid, 0); return true; } catch { return false; } };
const until = async (fn, ms = 3000) => { const end = Date.now() + ms; while (!fn() && Date.now() < end) await new Promise((r) => setTimeout(r, 25)); return fn(); };
// Review P3-6: a capture's whole process group goes, on a stop and when it ends: a stand-in that
// leaves a child in the background leaves nothing.
test("W2 claude-code: a capture stops what the binary left in the background, on a stop and when it ends", async (t) => {
const dir = scratch(t);
const bin = join(dir, "claude");
const left = join(dir, "left"), held = join(dir, "held");
writeFileSync(bin, [
"#!/bin/sh", 'case "$1" in',
`--version) sleep 30 >/dev/null 2>&1 & echo $! > '${left}'; echo '9.9.9';;`,
`--help) sleep 30 >/dev/null 2>&1 & echo $! > '${held}'; wait;;`,
"*) exit 3;;", "esac", "",
].join("\n"), { mode: 0o755 });
const stop = new AbortController();
const r = claude.inspect({ env: { MOSAIC_CLAUDE_BIN: bin }, scratch: scratch(t), signal: stop.signal });
assert.ok(await until(() => existsSync(held)), "--help started");
stop.abort();
const out = await r;
assert.match(out.line, /--help was stopped/);
const pids = [left, held].map((f) => Number(readFileSync(f, "utf8").trim()));
for (const pid of pids) assert.ok(await until(() => !alive(pid)), `process ${pid} left by a capture is gone`);
});
// Review P3-6: an already aborted signal starts nothing and decides nothing.
test("W2 claude-code: an inspect with an already aborted signal runs nothing and is unknown", async (t) => {
const dir = scratch(t);
const nsFile = join(dir, "ran");
const r = await claude.inspect({ env: { MOSAIC_CLAUDE_BIN: standIn(join(dir, "bin"), { nsFile }) }, scratch: scratch(t), signal: AbortSignal.abort() });
assert.deepEqual([r.fit, r.definite], ["unknown", false], r.line);
assert.equal(existsSync(nsFile), false, "the binary was not run");
});
// Review P3-6: at most 16 verdicts are kept; the oldest goes first.
test("W2 claude-code: preflight's verdicts are capped, oldest first", async (t) => {
const dir = scratch(t);
const bins = [];
for (let i = 0; i < 17; i++) bins.push(standIn(join(dir, `b${i}`), { helpText: help({ drop: ["--restricted"] }) }));
for (const bin of bins) assert.equal((await claude.inspect({ env: { MOSAIC_CLAUDE_BIN: bin }, scratch: scratch(t) })).fit, "fail");
const refused = (bin) => claude.preflight({ env: { MOSAIC_CLAUDE_BIN: bin, ...CREDENTIAL } })?.code ?? null;
assert.equal(refused(bins[0]), null, "the first verdict was dropped");
for (const bin of bins.slice(1)) assert.equal(refused(bin), "harness-feature-missing");
});
// Review P3-6: pi's inspect decides from undecided alone, whatever the message says.
test("W2 pi's inspect reads undecided, not the message", async (t) => {
const stand = piPackage(t, {});
const digest = "b".repeat(64);
const run = (fit) => pi.inspect({ env: stand.env, check: async () => fit });
let r = await run({ ok: false, message: "pi (MOSAIC_PI_BIN) can't be checked: words", digest, undecided: false });
assert.deepEqual([r.fit, r.definite, r.digest], ["fail", true, digest]);
r = await run({ ok: false, message: "pi (MOSAIC_PI_BIN) lacks --no-skills", digest, undecided: true });
assert.deepEqual([r.fit, r.definite], ["unknown", false]);
r = await run({ ok: false, message: "pi (MOSAIC_PI_BIN) lacks --no-skills" });
assert.deepEqual([r.fit, r.definite, r.digest], ["unknown", false, null], "a check that gives no undecided field is undecided");
});
@@ -229,7 +229,10 @@ test("W1 redaction covers real paths, trailing slashes, the user name, rule ids,
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],
// W2 review P3-5: a ~/ path, a file: URL and a path after a colon are paths now; a URL with a
// host and a one-segment path stay.
kept: ["see https://example.com/a/b, ~/x/y and /model", "see https://example.com/a/b, <path> and /model", dir],
forms: ["file:///opt/fixture/bin host:/srv/fixture/b ~me/.local/x", "<path> host:<path> <path>", dir],
};
const { watchHarnesses } = await import(pathToFileURL(join(tr.pkg, "src", "harness-watch.mjs")).href);
for (const [what, [line, want, at]] of Object.entries(lines)) {
@@ -39,6 +39,8 @@ async function copyRepo(t, script, version) {
mkdirSync(mod, { recursive: true });
for (const f of readdirSync(MODULE)) if (f.endsWith(".mjs")) copyFileSync(join(MODULE, f), join(mod, f));
for (const p of readdirSync(join(REPO, "packages"))) if (p !== "plugins") symlinkSync(join(REPO, "packages", p), join(root, "packages", p));
// The module imports packages/plugins/src (the stat key), so that links to the real tree too.
symlinkSync(join(REPO, "packages", "plugins", "src"), join(root, "packages", "plugins", "src"));
standIn(join(root, "node_modules"), script, version);
mkdirSync(join(root, "node_modules", ".bin"));
symlinkSync(`../${NAME}/dist/bundle/cli.js`, join(root, "node_modules", ".bin", "pi"));