@tokenfactory/acc-runner 0.42.0 → 0.44.0

package/dist/machine-capabilities/redact.js

@@ -0,0 +1,160 @@
+/**
+ * AX-H1 (MACHINE-CAPABILITIES): the LAST THING that runs on the host before a
+ * capability snapshot leaves it.
+ *
+ * AUTH_APPROVAL_BRIEF.md §7.1 / the MLSA plan: no credential ever transits ACC —
+ * presence and identity only. That is enforced in three independent places, and
+ * this is the first of them:
+ *
+ *   1. HERE — `sanitizeSnapshot` REBUILDS every record from the closed field set
+ *      in types.ts and masks every free-text field, so nothing the probe happened
+ *      to capture can ride along. A rebuild rather than a filter: a field nobody
+ *      whitelisted is absent from the output by construction, not removed by a
+ *      rule somebody has to remember to write.
+ *   2. `acc._normalize_machine_capability_{tools,engines}` (migration 0310 §6)
+ *      does the same rebuild server-side, so a rogue or stale runner build cannot
+ *      widen the record.
+ *   3. Two CHECK constraints on `acc.machine_capabilities` reject anything SHAPED
+ *      like a credential at rest, so material that somehow reached a whitelisted
+ *      field is unstorable rather than merely unwritten.
+ *
+ * `looksLikeCredential` is the shared shape test behind (1) and (3) — the
+ * patterns are mirrored in `acc.machine_capability_material_free(jsonb)` and the
+ * unit suite asserts the two agree case by case. It is a SHAPE test, not entropy
+ * analysis: it cannot prove a string is not a secret, which is exactly why it is
+ * the backstop and the rebuild is the boundary.
+ *
+ * PURE by construction — no I/O, no clock — so every rule is unit-testable.
+ */
+import { maskGitCredentials } from "../git-auth/probe.js";
+import { HOST_TOOLS, } from "./types.js";
+/**
+ * Credential SHAPES a developer machine actually holds, plus the two generic
+ * carriers. Mirrors the regexes in `acc.machine_capability_material_free`
+ * (0310 §2); `tests/unit/t1785160000000035-machine-capabilities.test.ts` asserts
+ * the mirror by running the same vectors through both spellings.
+ */
+export const CREDENTIAL_SHAPES = [
+    // GitHub personal / OAuth / app / refresh tokens, and fine-grained PATs.
+    /gh[posru]_[A-Za-z0-9]{16,}/,
+    /github_pat_[A-Za-z0-9_]{20,}/,
+    // Anthropic, OpenAI-family, Google AI keys.
+    /sk-ant-[A-Za-z0-9_-]{16,}/,
+    /sk-[A-Za-z0-9]{32,}/,
+    /AIza[0-9A-Za-z_-]{30,}/,
+    // Slack bot/user/app tokens (an MCP or notifier credential).
+    /xox[baprse]-[A-Za-z0-9-]{10,}/,
+    // A JWT (a Supabase service-role key, an ACC-signed runner token).
+    /eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\./,
+    // A PEM private key block (a GitHub App key).
+    /-----BEGIN [A-Z ]*PRIVATE KEY-----/,
+    // userinfo in a URL: scheme://user:token@host — how a PAT leaks out of a git
+    // remote. maskGitCredentials rewrites this to scheme://***@host, which has no
+    // colon before the '@' and therefore does not match.
+    /:\/\/[^/\s"]+:[^/\s"@]+@/,
+];
+/** True when `value` contains anything shaped like a credential. */
+export function looksLikeCredential(value) {
+    if (!value)
+        return false;
+    return CREDENTIAL_SHAPES.some((re) => re.test(value));
+}
+/**
+ * Mask + bound one free-text field. Applies `maskGitCredentials` first (the
+ * GIT-AUTH-ALERT masker, so URL userinfo and bare gh tokens are rewritten rather
+ * than dropped), then DROPS the value entirely if a credential shape survived —
+ * an unmaskable value is not worth a field. Length-bounded so a whitelisted
+ * field cannot become the smuggling channel.
+ */
+export function safeText(value, maxLength) {
+    if (value === null || value === undefined)
+        return null;
+    const masked = maskGitCredentials(String(value)).trim();
+    if (!masked)
+        return null;
+    if (looksLikeCredential(masked))
+        return null;
+    return masked.slice(0, maxLength);
+}
+/** `safeText` for a field that must be a string: an unusable value becomes "". */
+function safeDetail(value, maxLength = 300) {
+    return safeText(value, maxLength) ?? "";
+}
+/**
+ * Bound, dedupe and sort gh scope labels. Sorted so two snapshots of the same
+ * machine compare equal regardless of the order gh printed them, which is what
+ * makes the "did anything change?" fingerprint in report.ts stable. A label that
+ * looks like a credential is dropped rather than masked — a scope label is a
+ * short well-known word, so an unmaskable one is not a scope.
+ */
+export function safeScopes(scopes) {
+    if (!Array.isArray(scopes))
+        return [];
+    const out = new Set();
+    for (const raw of scopes) {
+        if (typeof raw !== "string")
+            continue;
+        const label = raw.trim();
+        if (!label || looksLikeCredential(label))
+            continue;
+        out.add(label.slice(0, 60));
+        if (out.size >= 32)
+            break;
+    }
+    return [...out].sort();
+}
+/** Rebuild one tool row from the closed field set. */
+export function sanitizeTool(tool) {
+    return {
+        tool: tool.tool,
+        present: tool.present === true,
+        version: safeText(tool.version, 60),
+        authenticated: tool.authenticated === true,
+        identity: safeText(tool.identity, 200),
+        host: safeText(tool.host, 120),
+        scopes: safeScopes(tool.scopes),
+        detail: safeDetail(tool.detail),
+    };
+}
+/** Rebuild one engine row from the closed field set. */
+export function sanitizeEngine(engine) {
+    return {
+        engine_id: (engine.engine_id ?? "").trim().slice(0, 60),
+        present: engine.present === true,
+        version: safeText(engine.version, 60),
+        logged_in: engine.logged_in === true,
+        channel: engine.channel,
+        account_email: safeText(engine.account_email, 200),
+        plan_hint: engine.plan_hint,
+        synthetic_account: safeDetail(engine.synthetic_account, 260),
+        detail: safeDetail(engine.detail),
+    };
+}
+/**
+ * Rebuild a whole snapshot. The ONLY function the reporter is allowed to send
+ * the output of — `recordMachineCapabilities` calls it unconditionally, even on a
+ * snapshot this package built itself, because the point is that no future probe
+ * can add a field that bypasses it.
+ *
+ * Rows for tools outside `HOST_TOOLS` and engines with a blank id are dropped:
+ * the server-side whitelist would drop them anyway, and sending them would make
+ * the local snapshot disagree with the recorded one.
+ */
+export function sanitizeSnapshot(snapshot) {
+    const known = new Set(HOST_TOOLS);
+    return {
+        machine: safeDetail(snapshot.machine, 200) || "unknown-host",
+        platform: safeDetail(snapshot.platform, 40) || "unknown",
+        arch: safeDetail(snapshot.arch, 40) || "unknown",
+        runner_version: safeDetail(snapshot.runner_version, 60),
+        tools: (snapshot.tools ?? [])
+            .filter((t) => known.has(t?.tool))
+            .slice(0, 16)
+            .map(sanitizeTool),
+        engines: (snapshot.engines ?? [])
+            .filter((e) => typeof e?.engine_id === "string" && e.engine_id.trim().length > 0)
+            .slice(0, 32)
+            .map(sanitizeEngine),
+    };
+}
+//# sourceMappingURL=redact.js.map

package/dist/machine-capabilities/redact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.js","sourceRoot":"","sources":["../../src/machine-capabilities/redact.ts"],"names":[],"mappings":"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"}

package/dist/machine-capabilities/report.d.ts

@@ -0,0 +1,107 @@
+import type { MachineCapabilityReport, MachineCapabilitySnapshot } from "./types.js";
+/** Minimum gap between host probes on the shared AS-1 cadence. */
+export declare const DEFAULT_PROBE_MIN_INTERVAL_MS: number;
+/** Minimum gap between re-recording an UNCHANGED snapshot (liveness refresh). */
+export declare const DEFAULT_REFRESH_MIN_INTERVAL_MS: number;
+/** The RPC surface the reporter needs — a supabase-js client satisfies it. */
+export interface MachineCapabilityTransport {
+    rpc(fn: string, args: Record<string, unknown>): PromiseLike<{
+        data?: unknown;
+        error?: {
+            message: string;
+        } | null;
+    }>;
+}
+/**
+ * A stable content fingerprint of a snapshot. Deliberately excludes nothing:
+ * every field that reaches the server is in it, so "unchanged" means the recorded
+ * row would be byte-identical. Sorted keys, so JSON key order cannot make an
+ * unchanged machine look changed.
+ */
+export declare function snapshotFingerprint(snapshot: MachineCapabilitySnapshot): string;
+export interface MachineCapabilityReporterDeps {
+    /** Probe the host. Should not throw; a throw is caught and logged. */
+    probe: () => Promise<MachineCapabilitySnapshot>;
+    /** The RPC transport. Omit to make the reporter probe-only (tests / dry runs). */
+    transport?: MachineCapabilityTransport | null;
+    /** The runner id to attribute the report to, when this process is a runner. */
+    runnerId?: string | null;
+    /** Min gap between host probes. Default 15 min. */
+    probeMinIntervalMs?: number;
+    /** Min gap between re-recording an unchanged snapshot. Default 6 h. */
+    refreshMinIntervalMs?: number;
+    /** Clock (test seam). Default Date.now. */
+    now?: () => number;
+    /** Best-effort log sink. */
+    onLog?: (line: string) => void;
+}
+/** What one cadence tick did, so a caller (and a test) can assert the gates. */
+export type MachineCapabilityTickOutcome = {
+    action: "skipped";
+    reason: "throttled";
+} | {
+    action: "probed";
+    recorded: boolean;
+    changed: boolean;
+    /** Why the write happened (or didn't): changed | liveness-refresh | unchanged | no-transport. */
+    reason: string;
+    /** Why the PROBE happened: first-probe | account-changed | interval-elapsed. */
+    probeReason: string;
+} | {
+    action: "failed";
+    reason: string;
+};
+/**
+ * Drives the capability probe on somebody else's cadence. Holds only the last
+ * fingerprint + two timestamps, so it is cheap to keep for the process lifetime
+ * and has no timer of its own — which is what makes "there is exactly one probe
+ * loop on this host" structurally true rather than a claim in a comment.
+ */
+export declare class MachineCapabilityReporter {
+    private readonly deps;
+    private readonly probeMinIntervalMs;
+    private readonly refreshMinIntervalMs;
+    private readonly now;
+    private lastProbeAt;
+    private lastRecordAt;
+    private lastFingerprint;
+    private lastAccountKey;
+    private seq;
+    /** Serial chain so two triggers never probe concurrently or record out of order. */
+    private tail;
+    constructor(deps: MachineCapabilityReporterDeps);
+    /** The last recorded fingerprint (null before the first successful probe). */
+    fingerprint(): string | null;
+    /** Resolve once every queued tick has settled (test seam). */
+    settle(): Promise<void>;
+    /**
+     * Note one AS-1 cadence tick. `accountKey` is the AS-1 `synthetic_account` of
+     * the identity that tick resolved: when it moves, the engine rows are stale by
+     * definition and the throttle is bypassed.
+     *
+     * Returns the outcome and never rejects — a capability report is
+     * best-effort telemetry and must never be able to fail a cadence tick.
+     */
+    onProbeTick(args: {
+        trigger: string;
+        accountKey?: string | null;
+    }): Promise<MachineCapabilityTickOutcome>;
+    private shouldProbe;
+    private tick;
+}
+/**
+ * Send one report to `acc.record_machine_capabilities`. Returns false (and logs)
+ * on any failure rather than throwing: a pre-0310 server 404s this RPC, and an
+ * operator on an older deploy must not have their runner wedged by a telemetry
+ * write — the same non-fatal contract `set_runner_capabilities` uses in watch.ts.
+ *
+ * The snapshot is sanitized ONE more time on the way out. That is not paranoia
+ * theatre: this function is exported and callable with an arbitrary snapshot, and
+ * the invariant it has to hold is "nothing that leaves this process carries
+ * credential material", not "nothing that leaves this class does".
+ */
+export declare function recordMachineCapabilities(transport: MachineCapabilityTransport, report: MachineCapabilityReport, opts?: {
+    runnerId?: string | null;
+    onLog?: (line: string) => void;
+}): Promise<boolean>;
+//# sourceMappingURL=report.d.ts.map

package/dist/machine-capabilities/report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../src/machine-capabilities/report.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EAAE,uBAAuB,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAErF,kEAAkE;AAClE,eAAO,MAAM,6BAA6B,QAAc,CAAC;AACzD,iFAAiF;AACjF,eAAO,MAAM,+BAA+B,QAAkB,CAAC;AAE/D,8EAA8E;AAC9E,MAAM,WAAW,0BAA0B;IACzC,GAAG,CACD,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,WAAW,CAAC;QAAE,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE;YAAE,OAAO,EAAE,MAAM,CAAA;SAAE,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;CACxE;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,yBAAyB,GAAG,MAAM,CAQ/E;AAED,MAAM,WAAW,6BAA6B;IAC5C,sEAAsE;IACtE,KAAK,EAAE,MAAM,OAAO,CAAC,yBAAyB,CAAC,CAAC;IAChD,kFAAkF;IAClF,SAAS,CAAC,EAAE,0BAA0B,GAAG,IAAI,CAAC;IAC9C,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,mDAAmD;IACnD,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,uEAAuE;IACvE,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,2CAA2C;IAC3C,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,4BAA4B;IAC5B,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAED,gFAAgF;AAChF,MAAM,MAAM,4BAA4B,GACpC;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,WAAW,CAAA;CAAE,GAC1C;IACE,MAAM,EAAE,QAAQ,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,iGAAiG;IACjG,MAAM,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,WAAW,EAAE,MAAM,CAAC;CACrB,GACD;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzC;;;;;GAKG;AACH,qBAAa,yBAAyB;IAaxB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAZjC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;IAC5C,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAS;IAC9C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IAEnC,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,eAAe,CAAuB;IAC9C,OAAO,CAAC,cAAc,CAAuB;IAC7C,OAAO,CAAC,GAAG,CAAK;IAChB,oFAAoF;IACpF,OAAO,CAAC,IAAI,CAAoC;gBAEnB,IAAI,EAAE,6BAA6B;IAShE,8EAA8E;IAC9E,WAAW,IAAI,MAAM,GAAG,IAAI;IAI5B,8DAA8D;IACxD,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAI7B;;;;;;;OAOG;IACH,WAAW,CAAC,IAAI,EAAE;QAChB,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KAC5B,GAAG,OAAO,CAAC,4BAA4B,CAAC;IAUzC,OAAO,CAAC,WAAW;YAUL,IAAI;CA4EnB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,yBAAyB,CAC7C,SAAS,EAAE,0BAA0B,EACrC,MAAM,EAAE,uBAAuB,EAC/B,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CAAO,GACtE,OAAO,CAAC,OAAO,CAAC,CA+BlB"}

package/dist/machine-capabilities/report.js

@@ -0,0 +1,211 @@
+/**
+ * AX-H1 (MACHINE-CAPABILITIES): the reporter — decide WHETHER to probe on this
+ * AS-1 cadence tick, and record the result.
+ *
+ * WHY A GATE AND NOT JUST "PROBE EVERY TICK". AX-H1 rides the AS-1 cadence
+ * (account-probe.ts) rather than adding a loop of its own, and that cadence ticks
+ * every ~60s while the runner is capacity-paused. An account probe is a config
+ * read; a capability probe shells out to gh, git and every engine — four to six
+ * subprocesses. Firing that every minute forever would make a cheap loop
+ * expensive and would rewrite an unchanged row all day.
+ *
+ * So the gate has three rules, in priority order:
+ *
+ *   1. FIRST TICK always probes. A machine that never reports is a machine ACC
+ *      cannot describe, which is the whole gap.
+ *   2. AN ACCOUNT CHANGE always probes. A login swap is precisely when the engine
+ *      rows went stale, and it is the AS-1 signal that already exists.
+ *   3. Otherwise probe at most once per `probeMinIntervalMs` (default 15 min).
+ *
+ * …and the WRITE has one more: an unchanged snapshot is only re-recorded once per
+ * `refreshMinIntervalMs` (default 6 h), so `probed_at` still proves liveness
+ * without an unchanged row being written 96 times a day. `snapshotFingerprint`
+ * decides "unchanged" over the whole sanitized document, so a version bump or a
+ * lost gh login is a change and a reordered scope list is not.
+ *
+ * FULLY injectable (probe / rpc / clock) so both gates are asserted with a fake
+ * clock and zero subprocesses.
+ */
+import { sanitizeSnapshot } from "./redact.js";
+/** Minimum gap between host probes on the shared AS-1 cadence. */
+export const DEFAULT_PROBE_MIN_INTERVAL_MS = 15 * 60_000;
+/** Minimum gap between re-recording an UNCHANGED snapshot (liveness refresh). */
+export const DEFAULT_REFRESH_MIN_INTERVAL_MS = 6 * 60 * 60_000;
+/**
+ * A stable content fingerprint of a snapshot. Deliberately excludes nothing:
+ * every field that reaches the server is in it, so "unchanged" means the recorded
+ * row would be byte-identical. Sorted keys, so JSON key order cannot make an
+ * unchanged machine look changed.
+ */
+export function snapshotFingerprint(snapshot) {
+    return JSON.stringify(snapshot, (_key, value) => {
+        if (value && typeof value === "object" && !Array.isArray(value)) {
+            const obj = value;
+            return Object.fromEntries(Object.keys(obj).sort().map((k) => [k, obj[k]]));
+        }
+        return value;
+    });
+}
+/**
+ * Drives the capability probe on somebody else's cadence. Holds only the last
+ * fingerprint + two timestamps, so it is cheap to keep for the process lifetime
+ * and has no timer of its own — which is what makes "there is exactly one probe
+ * loop on this host" structurally true rather than a claim in a comment.
+ */
+export class MachineCapabilityReporter {
+    deps;
+    probeMinIntervalMs;
+    refreshMinIntervalMs;
+    now;
+    lastProbeAt = null;
+    lastRecordAt = null;
+    lastFingerprint = null;
+    lastAccountKey = null;
+    seq = 0;
+    /** Serial chain so two triggers never probe concurrently or record out of order. */
+    tail = Promise.resolve();
+    constructor(deps) {
+        this.deps = deps;
+        this.probeMinIntervalMs = Math.max(0, deps.probeMinIntervalMs ?? DEFAULT_PROBE_MIN_INTERVAL_MS);
+        this.refreshMinIntervalMs = Math.max(0, deps.refreshMinIntervalMs ?? DEFAULT_REFRESH_MIN_INTERVAL_MS);
+        this.now = deps.now ?? Date.now;
+    }
+    /** The last recorded fingerprint (null before the first successful probe). */
+    fingerprint() {
+        return this.lastFingerprint;
+    }
+    /** Resolve once every queued tick has settled (test seam). */
+    async settle() {
+        await this.tail;
+    }
+    /**
+     * Note one AS-1 cadence tick. `accountKey` is the AS-1 `synthetic_account` of
+     * the identity that tick resolved: when it moves, the engine rows are stale by
+     * definition and the throttle is bypassed.
+     *
+     * Returns the outcome and never rejects — a capability report is
+     * best-effort telemetry and must never be able to fail a cadence tick.
+     */
+    onProbeTick(args) {
+        const run = this.tail.then(() => this.tick(args));
+        // Keep the chain alive even if a tick rejects (it should not — tick catches).
+        this.tail = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    shouldProbe(accountKey) {
+        if (this.lastProbeAt === null)
+            return { probe: true, reason: "first-probe" };
+        if (accountKey !== null && accountKey !== this.lastAccountKey) {
+            return { probe: true, reason: "account-changed" };
+        }
+        const age = this.now() - this.lastProbeAt;
+        if (age >= this.probeMinIntervalMs)
+            return { probe: true, reason: "interval-elapsed" };
+        return { probe: false, reason: "throttled" };
+    }
+    async tick(args) {
+        const accountKey = args.accountKey ?? null;
+        const decision = this.shouldProbe(accountKey);
+        // A skip is only ever reached when the account is UNCHANGED (rule 2 above
+        // outranks the throttle), so nothing is lost by not tracking the key here.
+        if (!decision.probe) {
+            return { action: "skipped", reason: "throttled" };
+        }
+        let snapshot;
+        try {
+            // Sanitized again here even though probe.ts already sanitizes: this class
+            // accepts an INJECTED probe, and the redaction boundary must not depend on
+            // which probe was injected.
+            snapshot = sanitizeSnapshot(await this.deps.probe());
+        }
+        catch (err) {
+            this.deps.onLog?.(`[acc-runner] machine-capability probe (${args.trigger}) failed: ${err?.message ?? String(err)}`);
+            return { action: "failed", reason: "probe-threw" };
+        }
+        const at = this.now();
+        this.lastProbeAt = at;
+        if (accountKey !== null)
+            this.lastAccountKey = accountKey;
+        const fingerprint = snapshotFingerprint(snapshot);
+        const changed = fingerprint !== this.lastFingerprint;
+        const refreshDue = this.lastRecordAt === null || at - this.lastRecordAt >= this.refreshMinIntervalMs;
+        if (!changed && !refreshDue) {
+            return {
+                action: "probed",
+                recorded: false,
+                changed: false,
+                reason: "unchanged",
+                probeReason: decision.reason,
+            };
+        }
+        if (!this.deps.transport) {
+            this.lastFingerprint = fingerprint;
+            return {
+                action: "probed",
+                recorded: false,
+                changed,
+                reason: "no-transport",
+                probeReason: decision.reason,
+            };
+        }
+        const report = {
+            snapshot,
+            trigger: args.trigger,
+            seq: ++this.seq,
+        };
+        const recorded = await recordMachineCapabilities(this.deps.transport, report, {
+            runnerId: this.deps.runnerId ?? null,
+            onLog: this.deps.onLog,
+        });
+        if (recorded) {
+            this.lastRecordAt = at;
+            this.lastFingerprint = fingerprint;
+        }
+        return {
+            action: "probed",
+            recorded,
+            changed,
+            reason: changed ? "changed" : "liveness-refresh",
+            probeReason: decision.reason,
+        };
+    }
+}
+/**
+ * Send one report to `acc.record_machine_capabilities`. Returns false (and logs)
+ * on any failure rather than throwing: a pre-0310 server 404s this RPC, and an
+ * operator on an older deploy must not have their runner wedged by a telemetry
+ * write — the same non-fatal contract `set_runner_capabilities` uses in watch.ts.
+ *
+ * The snapshot is sanitized ONE more time on the way out. That is not paranoia
+ * theatre: this function is exported and callable with an arbitrary snapshot, and
+ * the invariant it has to hold is "nothing that leaves this process carries
+ * credential material", not "nothing that leaves this class does".
+ */
+export async function recordMachineCapabilities(transport, report, opts = {}) {
+    const snapshot = sanitizeSnapshot(report.snapshot);
+    try {
+        const { error } = await transport.rpc("record_machine_capabilities", {
+            p_machine: snapshot.machine,
+            p_runner_id: opts.runnerId ?? null,
+            p_platform: snapshot.platform,
+            p_arch: snapshot.arch,
+            p_runner_version: snapshot.runner_version || null,
+            p_tools: snapshot.tools,
+            p_engines: snapshot.engines,
+            p_probe_trigger: report.trigger,
+            p_probe_seq: report.seq,
+            // No timestamp argument by design: probed_at is server time (0310 §4), so a
+            // host with a wrong clock cannot win last-writer-wins forever.
+        });
+        if (error) {
+            opts.onLog?.(`[acc-runner] record_machine_capabilities failed (continuing): ${error.message}`);
+            return false;
+        }
+        return true;
+    }
+    catch (err) {
+        opts.onLog?.(`[acc-runner] record_machine_capabilities threw (continuing): ${err?.message ?? String(err)}`);
+        return false;
+    }
+}
+//# sourceMappingURL=report.js.map

package/dist/machine-capabilities/report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../../src/machine-capabilities/report.ts"],"names":[],"mappings":"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"}

package/dist/machine-capabilities/types.d.ts

@@ -0,0 +1,115 @@
+/**
+ * AX-H1 (MACHINE-CAPABILITIES): the shapes a host reports about ITSELF.
+ *
+ * The one rule these types exist to encode (AUTH_APPROVAL_BRIEF.md §7.1 + the
+ * MLSA plan): NO CREDENTIAL EVER TRANSITS ACC. Every field below is either
+ *
+ *   - PRESENCE   — is the tool installed, does it authenticate, which version;
+ *   - IDENTITY   — which login / email / plan / scope-set it resolves to;
+ *   - PROVENANCE — which host, which runner, which AS-1 probe trigger.
+ *
+ * There is deliberately no field that could hold a token, and the field set is
+ * CLOSED on three sides: `sanitizeSnapshot` (redact.ts) rebuilds every record
+ * from these fields before it leaves the host,
+ * `acc._normalize_machine_capability_{tools,engines}` (migration 0310) rebuilds
+ * it again from the same whitelist server-side, and two CHECK constraints reject
+ * anything shaped like a credential at rest. Adding a field here without adding
+ * it to BOTH whitelists means the field is silently dropped, which is the
+ * intended failure direction.
+ *
+ * DECLARATIONS ONLY — no behaviour, no I/O, so the contract can be asserted
+ * against the SQL mirror in a unit test.
+ */
+import type { EngineAuthMode, EnginePlanHint } from "../engines/types.js";
+/**
+ * The host tools ACC probes. Mirrors `acc.machine_capability_tools()` (0310 §1)
+ * and `HOST_TOOLS` in api/_lib/machine-capabilities.ts — the unit suite asserts
+ * all three agree, so a tool added on one side cannot silently be dropped by
+ * the writer's whitelist on another.
+ *
+ * Deliberately NOT the `acc.runners.capabilities` vocabulary (0114/0115): those
+ * are routing tags an operator DECLARES; these are tools ACC PROBES.
+ */
+export declare const HOST_TOOLS: readonly ["gh", "git"];
+export type HostTool = (typeof HOST_TOOLS)[number];
+/** What one host tool offers. Presence + identity only. */
+export interface ToolCapability {
+    /** Which tool this row describes. */
+    tool: HostTool;
+    /** The binary resolved on the (launchd-augmented) PATH. */
+    present: boolean;
+    /** Reported version, e.g. "2.62.0". Null when absent or unparseable. */
+    version: string | null;
+    /**
+     * The tool holds a working credential. For `gh` this is `gh auth status`
+     * exiting 0; `git` has no host-level login of its own, so it reports false.
+     */
+    authenticated: boolean;
+    /**
+     * WHO the tool acts as: the gh account login, or git's `user.email`. An
+     * identity, never a credential — and null rather than guessed when unknown.
+     */
+    identity: string | null;
+    /** The host the credential is for (gh: github.com / a GHES hostname). */
+    host: string | null;
+    /**
+     * The AUTHORITY LABELS a gh token carries ("repo", "read:org"). These are what
+     * make "can this machine open a PR" answerable. The token itself is never
+     * read: `gh auth status --show-token` is never invoked anywhere in this
+     * package, and the unit suite asserts that.
+     */
+    scopes: string[];
+    /** Masked, credential-safe one-line summary — safe to log, store and display. */
+    detail: string;
+}
+/** What one coding engine offers on this host. */
+export interface EngineCapability {
+    /** Engine registry id (claude-code | codex | gemini). */
+    engine_id: string;
+    /** The engine's binary resolved on PATH. */
+    present: boolean;
+    /** Reported version. Null when absent or unparseable. */
+    version: string | null;
+    /** The engine resolved a real, named account (not the honest-unknown identity). */
+    logged_in: boolean;
+    /** Which auth channel the identity resolved through (AS-1 `channel`). */
+    channel: EngineAuthMode;
+    /** The account the engine is logged in as, or null when unintrospectable. */
+    account_email: string | null;
+    /** Coarse plan hint; "unknown" when the engine cannot detect one. */
+    plan_hint: EnginePlanHint;
+    /** The AS-1 stable synthetic account id. Always set. */
+    synthetic_account: string;
+    /** Masked, credential-safe one-line summary. */
+    detail: string;
+}
+/** Everything one host reports about itself in a single probe. */
+export interface MachineCapabilitySnapshot {
+    /** os.hostname() — the operator-facing name of the machine. */
+    machine: string;
+    /** process.platform. */
+    platform: string;
+    /** process.arch. */
+    arch: string;
+    /** The acc-runner version that produced this snapshot. */
+    runner_version: string;
+    /** One row per probed host tool, in HOST_TOOLS order. */
+    tools: ToolCapability[];
+    /** One row per registered chat engine. */
+    engines: EngineCapability[];
+}
+/**
+ * A snapshot plus the AS-1 provenance of the probe that produced it. This is
+ * what `recordMachineCapabilities` sends to
+ * `acc.record_machine_capabilities` — note there is no timestamp: `probed_at` is
+ * server time, because a host with a wrong clock would otherwise win every
+ * last-writer-wins comparison forever (0310 §4).
+ */
+export interface MachineCapabilityReport {
+    snapshot: MachineCapabilitySnapshot;
+    /** Which AS-1 cadence trigger fired this probe. */
+    trigger: string;
+    /** The probing process's monotonic probe sequence. */
+    seq: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/machine-capabilities/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/machine-capabilities/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1E;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU,wBAAyB,CAAC;AAEjD,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnD,2DAA2D;AAC3D,MAAM,WAAW,cAAc;IAC7B,qCAAqC;IACrC,IAAI,EAAE,QAAQ,CAAC;IACf,2DAA2D;IAC3D,OAAO,EAAE,OAAO,CAAC;IACjB,wEAAwE;IACxE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB;;;OAGG;IACH,aAAa,EAAE,OAAO,CAAC;IACvB;;;OAGG;IACH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,yEAAyE;IACzE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB;;;;;OAKG;IACH,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,iFAAiF;IACjF,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,kDAAkD;AAClD,MAAM,WAAW,gBAAgB;IAC/B,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;IAClB,4CAA4C;IAC5C,OAAO,EAAE,OAAO,CAAC;IACjB,yDAAyD;IACzD,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,mFAAmF;IACnF,SAAS,EAAE,OAAO,CAAC;IACnB,yEAAyE;IACzE,OAAO,EAAE,cAAc,CAAC;IACxB,6EAA6E;IAC7E,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,qEAAqE;IACrE,SAAS,EAAE,cAAc,CAAC;IAC1B,wDAAwD;IACxD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gDAAgD;IAChD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,kEAAkE;AAClE,MAAM,WAAW,yBAAyB;IACxC,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC;IAChB,wBAAwB;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,cAAc,EAAE,MAAM,CAAC;IACvB,yDAAyD;IACzD,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,0CAA0C;IAC1C,OAAO,EAAE,gBAAgB,EAAE,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,yBAAyB,CAAC;IACpC,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,GAAG,EAAE,MAAM,CAAC;CACb"}

package/dist/machine-capabilities/types.js

@@ -0,0 +1,11 @@
+/**
+ * The host tools ACC probes. Mirrors `acc.machine_capability_tools()` (0310 §1)
+ * and `HOST_TOOLS` in api/_lib/machine-capabilities.ts — the unit suite asserts
+ * all three agree, so a tool added on one side cannot silently be dropped by
+ * the writer's whitelist on another.
+ *
+ * Deliberately NOT the `acc.runners.capabilities` vocabulary (0114/0115): those
+ * are routing tags an operator DECLARES; these are tools ACC PROBES.
+ */
+export const HOST_TOOLS = ["gh", "git"];
+//# sourceMappingURL=types.js.map

package/dist/machine-capabilities/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/machine-capabilities/types.ts"],"names":[],"mappings":"AAwBA;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,IAAI,EAAE,KAAK,CAAU,CAAC"}