@juzser/blacksmith 0.1.0

package/factory/orchestrator/dist/runtime.js

@@ -0,0 +1,86 @@
+import { SmithError } from './errors.js';
+export class UnsupportedRuntimeError extends SmithError {
+}
+/**
+ * The Node major the repo is pinned to. Kept in lockstep with `.nvmrc` and
+ * the root package.json `engines` field — `runtime.test.ts` asserts all three
+ * agree, so this constant cannot drift away from the pin silently.
+ */
+export const MIN_NODE_MAJOR = 22;
+/**
+ * The N-API version the native dependencies are built against.
+ * `better-sqlite3` ships one prebuilt binary per platform, compiled for
+ * N-API 10 (Node 22+). Node 20 is N-API 9: the binding still *loads*, and
+ * then the process dies at `new Database()` with SIGSEGV — no ABI error, no
+ * message, both streams empty. That silence is why this guard exists (D-47).
+ */
+export const MIN_NAPI = 10;
+export function currentRuntime() {
+    return { version: process.version, napi: process.versions.napi };
+}
+export function nodeMajor(version) {
+    // Tolerates a bare major so the same parser reads `.nvmrc` ("22") and
+    // `process.version` ("v22.23.1") — one definition of "the pinned major".
+    const match = /^v?(\d+)(?:\.|$)/.exec(version.trim());
+    if (match === null)
+        return null;
+    const major = Number(match[1]);
+    return Number.isFinite(major) ? major : null;
+}
+const REMEDY = 'Run `nvm use` (the repo pins the major in .nvmrc) or install Node ' +
+    `${MIN_NODE_MAJOR}+, then reinstall dependencies.`;
+const WHY = 'The prebuilt better-sqlite3 native binding is built for N-API ' +
+    `${MIN_NAPI}; on an older runtime it loads and then segfaults at the first ` +
+    'database open, so you get a crash with empty output instead of an error.';
+/**
+ * Decide whether this runtime can actually run the orchestrator. Unknown is
+ * treated as unsupported: the failure mode being guarded against is a silent
+ * crash, so guessing in favour of "probably fine" reintroduces exactly the
+ * bug (D-47).
+ */
+export function checkRuntime(info = currentRuntime()) {
+    const major = nodeMajor(info.version);
+    if (major === null) {
+        return {
+            supported: false,
+            reason: `Could not parse a Node major version out of "${info.version}", so this runtime ` +
+                `cannot be verified against the required Node >=${MIN_NODE_MAJOR}. ${WHY} ${REMEDY}`,
+        };
+    }
+    if (major < MIN_NODE_MAJOR) {
+        const napi = info.napi === undefined ? 'unknown' : info.napi;
+        return {
+            supported: false,
+            reason: `Node ${info.version} (N-API ${napi}) is too old: black-smith requires Node ` +
+                `>=${MIN_NODE_MAJOR} (N-API >=${MIN_NAPI}). ${WHY} ${REMEDY}`,
+        };
+    }
+    if (info.napi === undefined) {
+        return {
+            supported: false,
+            reason: `Node ${info.version} reports no N-API version, so the native bindings cannot be ` +
+                `matched against the required N-API >=${MIN_NAPI}. ${WHY} ${REMEDY}`,
+        };
+    }
+    const napi = Number(info.napi);
+    if (!Number.isFinite(napi) || napi < MIN_NAPI) {
+        return {
+            supported: false,
+            reason: `Node ${info.version} provides N-API ${info.napi}, below the required N-API ` +
+                `>=${MIN_NAPI}. ${WHY} ${REMEDY}`,
+        };
+    }
+    return { supported: true, reason: null };
+}
+/** `checkRuntime`, but fatal — for the CLI entrypoint. */
+export function assertRuntimeSupported(info = currentRuntime()) {
+    const result = checkRuntime(info);
+    if (result.supported)
+        return;
+    throw new UnsupportedRuntimeError('unsupported-runtime', result.reason ?? 'unsupported runtime', {
+        version: info.version,
+        napi: info.napi ?? null,
+        minNodeMajor: MIN_NODE_MAJOR,
+        minNapi: MIN_NAPI,
+    });
+}

package/factory/orchestrator/dist/sameMistakeKpi.js

@@ -0,0 +1,243 @@
+import { canEscalate, isFileScoped } from './severity.js';
+export function lessonReach(lessons) {
+    const categories = new Set();
+    let escalating = 0;
+    let withoutCategory = 0;
+    let nonFileScoped = 0;
+    for (const lesson of lessons) {
+        if (canEscalate(lesson)) {
+            escalating += 1;
+            categories.add(lesson.category);
+            continue;
+        }
+        // Both reasons are recorded for an entry that has both, because each is a
+        // different edit to make the entry live.
+        if (lesson.category === '')
+            withoutCategory += 1;
+        if (!isFileScoped(lesson))
+            nonFileScoped += 1;
+    }
+    return {
+        total: lessons.length,
+        escalating,
+        withoutCategory,
+        nonFileScoped,
+        categoriesCovered: [...categories].sort(),
+    };
+}
+function emptyDay() {
+    return {
+        intakes: 0,
+        emptyIntakes: 0,
+        decisions: 0,
+        sameMistake: 0,
+        quorumSameMistake: 0,
+        uninstrumentedDecisions: 0,
+    };
+}
+function decide(windows, provenRises, reach, holes) {
+    // Order matters, and it is the asymmetry in code. A repeat the log already
+    // recorded proves the instrument fired, so a rise between measured windows
+    // survives any hole elsewhere in the record rather than being downgraded to
+    // "we cannot tell" by an unrelated unknown. Only when nothing has risen does
+    // the quality of the instrument decide between "on target" and "unreadable".
+    //
+    // "Elsewhere" is the load-bearing word, and it used to be unchecked: a rise
+    // has two operands, and a hole in the earlier one is not elsewhere. Only a
+    // rise the baseline could have contradicted is a fact about the work (D-174).
+    if (provenRises.length > 0)
+        return 'off-target';
+    if (reach.escalating === 0)
+        return 'unverifiable';
+    if (holes)
+        return 'unverifiable';
+    if (windows.length === 0)
+        return 'unverifiable';
+    if (windows.length === 1)
+        return 'insufficient-history';
+    return 'on-target';
+}
+function pct(rate) {
+    return `${(rate * 100).toFixed(1)}%`;
+}
+function describe(report) {
+    const head = `${report.totalSameMistake} same-mistake of ${report.totalDecisions} decision(s) across ` +
+        `${report.windows.length} measured window(s)` +
+        (report.windows.length > 0
+            ? ` — ${report.windows.map((w) => `${w.day} ${pct(w.rate)}`).join(', ')}.`
+            : '.');
+    const holes = [];
+    if (report.reach.escalating === 0) {
+        holes.push(`none of the ${report.reach.total} compiled lesson(s) can escalate anything ` +
+            `(${report.reach.withoutCategory} name no finding_category, ` +
+            `${report.reach.nonFileScoped} are not file-scoped), so a zero here is a property ` +
+            `of the corpus, not of the work`);
+    }
+    if (report.intakesWithoutInstrumentRecord > 0) {
+        holes.push(`${report.intakesWithoutInstrumentRecord} intake(s) record no lessons_escalating count, ` +
+            `so the log does not say whether the gate held any lesson at all`);
+    }
+    if (report.blindIntakes > 0) {
+        holes.push(`${report.blindIntakes} intake(s) ran with no escalating lesson loaded and could not ` +
+            `have found a repeat`);
+    }
+    if (report.unprovenRises.length > 0) {
+        holes.push(`the rate rose on ${report.unprovenRises.join(', ')} from a window whose decisions came ` +
+            `from a gate that could not have recorded a repeat, so the rise measures the corpus ` +
+            `rather than the work`);
+    }
+    if (report.traceDisagreements.length > 0) {
+        holes.push(`the quorum trace saw a same mistake the severity trace did not on ` +
+            `${report.traceDisagreements.join(', ')}`);
+    }
+    if (report.silentDays.length > 0) {
+        holes.push(`${report.silentDays.length} day(s) recorded intakes but no decision ` +
+            `(${report.silentDays.join(', ')}) and are excluded rather than counted as 0%`);
+    }
+    const holeText = holes.length > 0 ? ` Holes: ${holes.join('; ')}.` : '';
+    switch (report.status) {
+        case 'off-target':
+            return (`${head} The rate rose between measured windows, against §9.7's monotonically ` +
+                `decreasing target. The window it rose from recorded every decision under a gate ` +
+                `equipped to escalate, so this stands whatever else the record is missing.${holeText}`);
+        case 'insufficient-history':
+            return (`${head} One measured window is a reading, not a trend; §9.7's target is about ` +
+                `direction and needs a second.${holeText}`);
+        case 'unverifiable':
+            return report.unprovenRises.length > 0
+                ? `${head} The rate rose, but not from a window that could have read anything else: ` +
+                    `the baseline's zeros belong to the corpus, not to the work.${holeText}`
+                : `${head} Nothing here shows the rate rising, but neither can it show the rate ` +
+                    `falling: the number could not have been other than what it is.${holeText}`;
+        default:
+            return (`${head} Non-increasing across every measured window, against a corpus that can ` +
+                `escalate ${report.reach.escalating} lesson(s) in ` +
+                `${report.reach.categoriesCovered.join(', ')}.`);
+    }
+}
+/**
+ * The same-mistake rate read as §9.7's KPI: is it going down, and is the number
+ * one that could have gone up.
+ *
+ * Read-only over the log. Fails the report on anything but `on-target` — an
+ * unreadable instrument is not a clean one, for the same reason
+ * dispatchAudit.ts emits a synthetic check for an empty pair set.
+ */
+export function checkSameMistakeKpi(events, lessons, options) {
+    const reach = lessonReach(lessons);
+    const byDay = new Map();
+    const dayFor = (day) => {
+        let acc = byDay.get(day);
+        if (acc === undefined) {
+            acc = emptyDay();
+            byDay.set(day, acc);
+        }
+        return acc;
+    };
+    let intakesWithoutInstrumentRecord = 0;
+    let blindIntakes = 0;
+    for (const { record } of events) {
+        const day = record.ts.slice(0, 10);
+        if (record.event_type === 'quorum-decision') {
+            if (record.payload.trigger_reason === 'same-mistake')
+                dayFor(day).quorumSameMistake += 1;
+            continue;
+        }
+        if (record.event_type !== 'severity-decisions')
+            continue;
+        const payload = record.payload;
+        const acc = dayFor(day);
+        acc.intakes += 1;
+        const loaded = payload.lessons_escalating;
+        if (typeof loaded !== 'number')
+            intakesWithoutInstrumentRecord += 1;
+        else if (loaded === 0)
+            blindIntakes += 1;
+        const decisions = payload.decisions ?? [];
+        if (decisions.length === 0)
+            acc.emptyIntakes += 1;
+        let fired = false;
+        for (const decision of decisions) {
+            acc.decisions += 1;
+            if (decision.same_mistake) {
+                acc.sameMistake += 1;
+                fired = true;
+            }
+        }
+        // What this intake's decisions are worth as a baseline. A recorded repeat
+        // is its own attestation — `same_mistake: true` cannot be written by a gate
+        // holding nothing to escalate against — so an intake that fired needs no
+        // separate count, which is why an event predating `lessons_escalating` can
+        // still anchor a rise. An intake that did not fire needs the count, and
+        // without it its zeros are the corpus's zeros, not the work's.
+        const shownEquipped = fired || (typeof loaded === 'number' && loaded > 0);
+        if (!shownEquipped)
+            acc.uninstrumentedDecisions += decisions.length;
+    }
+    const days = [...byDay.entries()].sort(([a], [b]) => a.localeCompare(b));
+    const windows = days
+        .filter(([, acc]) => acc.decisions > 0)
+        .map(([day, acc]) => ({
+        day,
+        intakes: acc.intakes,
+        emptyIntakes: acc.emptyIntakes,
+        decisions: acc.decisions,
+        sameMistake: acc.sameMistake,
+        rate: acc.sameMistake / acc.decisions,
+        quorumSameMistake: acc.quorumSameMistake,
+        uninstrumentedDecisions: acc.uninstrumentedDecisions,
+    }));
+    // A day with intakes but no decision at all. Not a rate of zero — there is no
+    // denominator to divide by, and inventing one is the whole bug.
+    const silentDays = days
+        .filter(([, acc]) => acc.decisions === 0 && acc.intakes > 0)
+        .map(([day]) => day);
+    // The quorum trace is written by a different code path (gate.ts:487) and only
+    // when an external provider is enabled, so it is normally silent. What it can
+    // never be is *more* clean than the severity trace: a same-mistake quorum on
+    // a day the decisions call clean means one of the two traces is wrong.
+    const traceDisagreements = days
+        .filter(([, acc]) => acc.quorumSameMistake > acc.sameMistake)
+        .map(([day]) => day);
+    // Split every rise by whether the window it rose FROM could have read
+    // anything but low. A baseline holding decisions no gate was equipped to
+    // escalate is one of the three zeros in this file's header, and a difference
+    // taken against it measures the corpus rather than the factory's conduct —
+    // the substitution `reach` already refuses for the level, refused here for
+    // the trend.
+    const provenRises = [];
+    const unprovenRises = [];
+    for (let i = 1; i < windows.length; i += 1) {
+        const window = windows[i];
+        const previous = windows[i - 1];
+        if (window.rate <= previous.rate)
+            continue;
+        if (previous.uninstrumentedDecisions === 0)
+            provenRises.push(window.day);
+        else
+            unprovenRises.push(window.day);
+    }
+    const monotonic = provenRises.length === 0 && unprovenRises.length === 0;
+    const totalDecisions = windows.reduce((sum, w) => sum + w.decisions, 0);
+    const totalSameMistake = windows.reduce((sum, w) => sum + w.sameMistake, 0);
+    const holes = intakesWithoutInstrumentRecord > 0 ||
+        blindIntakes > 0 ||
+        unprovenRises.length > 0 ||
+        traceDisagreements.length > 0;
+    const partial = {
+        sessionId: options.sessionId,
+        reach,
+        windows,
+        silentDays,
+        totalDecisions,
+        totalSameMistake,
+        intakesWithoutInstrumentRecord,
+        blindIntakes,
+        traceDisagreements,
+        monotonic,
+        provenRises,
+        unprovenRises,
+        status: decide(windows, provenRises, reach, holes),
+    };
+    return { ...partial, detail: describe(partial), ok: partial.status === 'on-target' };
+}

package/factory/orchestrator/dist/sandbox.js

@@ -0,0 +1,165 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { SmithError } from './errors.js';
+import { SANDBOX_LEASE_DIR } from './paths.js';
+import { sandboxRoles } from './policy.js';
+/**
+ * The judge sandbox: what turns "judges are read-only" from a sentence an
+ * agent reads into a rule the machine applies while the judge is running.
+ *
+ * Before this module the guarantee was `immutability.ts` — fingerprint the
+ * worktree, run the judge, compare after. That check is real and it stays
+ * (see `checkWorktreeImmutable`), but it is a *detector*, not a guard: by the
+ * time it fires the write has happened, the judge's verdict is already
+ * untrustworthy, and the task has to go round again. Worse, it can only see
+ * what git can see — a judge that curls an endpoint, installs a package, or
+ * writes outside the worktree leaves no fingerprint at all, and the six judge
+ * roles hold `Bash` in fact even though they are read-only in prose
+ * (agent-interviews.md N-10).
+ *
+ * A lease closes that gap at the only moment where refusing is free: before
+ * the command runs. The orchestrator opens one against the worktree it is
+ * about to hand a judge; `smith policy hook` resolves the lease from the
+ * PreToolUse payload's `cwd` and, while one is open, evaluates the judge
+ * rules in guardrails.yml on top of the six that always apply. Closing the
+ * lease is the orchestrator's move, not the judge's — `judge-sandbox-escape`
+ * exists precisely because `smith sandbox close` is itself a Bash command.
+ *
+ * Why a file rather than an environment variable: the hook does not run in
+ * the judge's process, or even necessarily on the same side of a subagent
+ * boundary. `cwd` is the one thing the PreToolUse payload is guaranteed to
+ * carry that identifies *where* the command will run, and a worktree path is
+ * what a judge dispatch is scoped to. So the lease is keyed by worktree and
+ * kept in the main clone, which is also the answer to "could the judge just
+ * delete it": that path is outside its worktree, and reaching it is a write
+ * the same rule set denies.
+ *
+ * What this deliberately is NOT: a container, a seccomp filter, or a
+ * read-only mount. Those are the real thing and this is not them — a judge
+ * that never issues a Bash tool call cannot be watched here at all, and a
+ * sufficiently creative command line will get past a matcher, exactly as
+ * documented for the six branch/deploy rules. This raises the floor from
+ * "detected afterwards" to "refused up front" on every path a judge actually
+ * has, and `checkWorktreeImmutable` still runs behind it. Both are stated
+ * plainly in docs/standards/guardrails.md rather than sold as a sandbox.
+ */
+export class SandboxError extends SmithError {
+}
+/**
+ * One file per lease, named by a hash of the worktree path.
+ *
+ * Per-file rather than one shared JSON document because judges for different
+ * tasks run at the same time by design: two waves in flight means two opens
+ * and two closes racing, and a read-modify-write of a shared file loses one
+ * of them. A hash rather than the path itself because a worktree path is not
+ * a legal filename on any platform this runs on.
+ */
+export function leasePathFor(worktreeDir, dir = SANDBOX_LEASE_DIR) {
+    const key = createHash('sha256').update(path.resolve(worktreeDir)).digest('hex').slice(0, 32);
+    return path.join(dir, `${key}.json`);
+}
+function assertLease(value, file) {
+    const lease = value;
+    if (lease === null ||
+        typeof lease !== 'object' ||
+        typeof lease.worktreeDir !== 'string' ||
+        typeof lease.role !== 'string' ||
+        typeof lease.taskId !== 'string' ||
+        typeof lease.sessionId !== 'string' ||
+        typeof lease.openedAt !== 'string') {
+        throw new SandboxError('sandbox.invalid-lease', `${file} is not a sandbox lease ({ worktreeDir, role, taskId, sessionId, openedAt }).`, { file });
+    }
+    return lease;
+}
+/**
+ * Open a lease over `worktreeDir`.
+ *
+ * Refuses when one is already open, and that refusal is the point rather than
+ * bookkeeping tidiness: two judges sharing a worktree means the second one's
+ * writes are attributed to the first one's lease and neither verdict can be
+ * trusted. The orchestrator's answer is a second worktree, not a second
+ * judge in the same tree.
+ *
+ * Refuses an unknown `role` for a related reason. The role is not a label on
+ * the lease, it *selects* which rule set policy.ts applies — the judge rules
+ * or a role write scope — so a typo used to be a silent downgrade to whatever
+ * the fallback happened to be. Guessing is not an option here and neither is
+ * a warning: the lease is written once and read by a hook that has no way to
+ * ask what was meant.
+ */
+export function openSandbox(input, dir = SANDBOX_LEASE_DIR) {
+    const roles = sandboxRoles();
+    if (!roles.includes(input.role)) {
+        throw new SandboxError('sandbox.unknown-role', `"${input.role}" is not a role guardrails.yml has rules for. Open the lease as one of: ${roles.join(', ')}.`, { role: input.role, roles });
+    }
+    const worktreeDir = path.resolve(input.worktreeDir);
+    const file = leasePathFor(worktreeDir, dir);
+    const existing = readSandbox(worktreeDir, dir);
+    if (existing) {
+        throw new SandboxError('sandbox.already-open', `A ${existing.role} sandbox is already open on ${worktreeDir} (task ${existing.taskId}, since ${existing.openedAt}). Close it, or give this judge its own worktree.`, { worktreeDir, role: existing.role, taskId: existing.taskId });
+    }
+    const lease = {
+        worktreeDir,
+        role: input.role,
+        taskId: input.taskId,
+        sessionId: input.sessionId,
+        openedAt: input.openedAt,
+    };
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(file, `${JSON.stringify(lease, null, 2)}\n`, 'utf8');
+    return lease;
+}
+/** The lease on exactly this worktree, or null. Does not walk up — see `activeSandboxFor`. */
+export function readSandbox(worktreeDir, dir = SANDBOX_LEASE_DIR) {
+    const file = leasePathFor(worktreeDir, dir);
+    if (!existsSync(file))
+        return null;
+    return assertLease(JSON.parse(readFileSync(file, 'utf8')), file);
+}
+/** Close the lease on `worktreeDir`. Returns false when there was none — closing twice is not an error. */
+export function closeSandbox(worktreeDir, dir = SANDBOX_LEASE_DIR) {
+    const file = leasePathFor(worktreeDir, dir);
+    if (!existsSync(file))
+        return false;
+    rmSync(file);
+    return true;
+}
+/** Every open lease, for `smith sandbox status` and for the resolver below. */
+export function listSandboxes(dir = SANDBOX_LEASE_DIR) {
+    if (!existsSync(dir))
+        return [];
+    const leases = [];
+    for (const name of readdirSync(dir).sort()) {
+        if (!name.endsWith('.json'))
+            continue;
+        const file = path.join(dir, name);
+        leases.push(assertLease(JSON.parse(readFileSync(file, 'utf8')), file));
+    }
+    return leases;
+}
+/**
+ * The lease covering a command about to run in `cwd`, or null.
+ *
+ * Matches on containment, not equality: a judge running `pnpm -C ui test`
+ * from `<worktree>/ui` is inside the same sandbox as one standing at the
+ * root, and a rule that only fired at the exact worktree path would be a
+ * `cd` away from being off. When leases nest (they should not, but a
+ * worktree inside a worktree is not forbidden by anything) the longest
+ * matching path wins, which is the innermost and therefore the most specific
+ * claim on the command.
+ */
+export function activeSandboxFor(cwd, dir = SANDBOX_LEASE_DIR) {
+    const here = path.resolve(cwd);
+    let best = null;
+    for (const lease of listSandboxes(dir)) {
+        const relative = path.relative(lease.worktreeDir, here);
+        const contained = relative === '' ||
+            (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+        if (!contained)
+            continue;
+        if (best === null || lease.worktreeDir.length > best.worktreeDir.length)
+            best = lease;
+    }
+    return best;
+}