@intentic/constants 1.323.0 → 1.325.0

package/dist/index.d.ts

@@ -10,7 +10,7 @@ export declare const PUBLIC_DIR = "public";
 export declare const MEMORY_FILE = "AGENTS.md";
 export declare const FIELD_NOTES_FILE = ".intentic/config/field-notes.toon";
 export declare const HOST_STATE_ROOT = "/opt/intentic";
-export declare const LEGAL_VERSION = "2026-09-29";
+export declare const LEGAL_VERSION = "2026-10-04";
 export declare const LEGAL_CONTACT_EMAIL = "contact@intentic.dev";
 export declare const LEGAL_ENTITY_NAME = "Artur Kurowski, trading as radarsu";
 export declare const LEGAL_ENTITY_COUNTRY = "Poland";

package/dist/index.js

@@ -10,7 +10,7 @@ export const PUBLIC_DIR = "public";
 export const MEMORY_FILE = "AGENTS.md";
 export const FIELD_NOTES_FILE = ".intentic/config/field-notes.toon";
 export const HOST_STATE_ROOT = "/opt/intentic";
-export const LEGAL_VERSION = "2026-09-29";
+export const LEGAL_VERSION = "2026-10-04";
 export const LEGAL_CONTACT_EMAIL = "contact@intentic.dev";
 export const LEGAL_ENTITY_NAME = "Artur Kurowski, trading as radarsu";
 export const LEGAL_ENTITY_COUNTRY = "Poland";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentic/constants",
-  "version": "1.323.0",
+  "version": "1.325.0",
   "description": "Shared constants for the intentic packages, ports, paths, and image references the daemon, CLIs and desktop app all agree on",
   "license": "MIT",
   "type": "module",

package/src/heavy/heavy-rules.cjs

@@ -186,6 +186,38 @@ const queueArgs = (match, config) => [
     match.id,
 ];
 
+// A test run that names what it runs: a word after the test verb that reads as a path, a test file or a filter
+// (`pnpm --filter web test src/router/signIn.test.ts`, `bun test --conditions=x src/a.test.ts`, `vitest run tools/`,
+// `pnpm --filter @intentic/sandbox test filter-stats`). The
+// memory gate prices it as one worker over a few files (memory-room.mjs TARGETED_RUN_BYTES), not as a package's
+// suite: measured 2026-09-26..10-02, 2,147 of 2,463 test runs named their files, and the gate held them a median 6.4 s
+// for work that takes under one. A recursive or turbo fan-out is never targeted, whatever it names.
+const TEST_VERB = /^(test|vitest|jest)$/u;
+const FAN_OUT = /^(-r|--recursive|turbo|--workspaces?|-ws)$/u;
+const PATHLIKE = /[/.]\p{L}|^\p{L}[\w-]*\.(test|spec)\b|\b(test|spec)s?\b/u;
+const targetedRun = (invocation) => {
+    const words = invocation.slice(0, MATCH_LIMIT).split(/\s+/u).filter((word) => word !== "");
+    if (words.some((word) => FAN_OUT.test(word))) {
+        return false;
+    }
+    const verb = words.findIndex((word, index) => TEST_VERB.test(word.split("/").pop() ?? "") && (index > 0 || word !== "test"));
+    if (verb === -1) {
+        return false;
+    }
+    // A bare word (`filter-stats`) is a filter too, unless it may be the value of the flag before it (`--reporter dot`).
+    return words.slice(verb + 1).some((word, index, rest) => {
+        if (word.startsWith("-") || word.startsWith("@") || word === "run" || !/\p{L}/u.test(word)) {
+            return false;
+        }
+        const before = rest[index - 1] ?? "";
+        return PATHLIKE.test(word) || !(before.startsWith("-") && before !== "--" && !before.includes("="));
+    });
+};
+
+// queue-run's `--size` for a match: `targeted` for a test run aimed at named files, nothing for everything else.
+const sizeArgs = (match, invocation) =>
+    ["vitest", "package-script"].includes(match.id) && targetedRun(invocation) ? ["--size", "targeted"] : [];
+
 // When a slot held this long is worth a line in the log: half of what its own rule lets it hold, never for a rule that
 // lets it hold forever.
 const holdWarnSeconds = (maxHold) => (maxHold > 0 ? maxHold / 2 : undefined);
@@ -202,6 +234,8 @@ module.exports = {
     overridesOf,
     matchInvocation,
     queueArgs,
+    targetedRun,
+    sizeArgs,
     holdWarnSeconds,
     ruleById,
 };

package/src/heavy/heavy-rules.d.cts

@@ -67,5 +67,9 @@ export function mergeHeavyRules(overrides?: HeavyCommandOverrides): HeavyCommand
 export function overridesOf(full: Partial<HeavyCommandSettings> & { readonly rules?: readonly HeavyCommandRule[] | undefined }): HeavyCommandOverrides;
 export function matchInvocation(invocation: string, config: HeavyCommands, report?: (detail: string) => void): HeavyMatch | undefined;
 export function queueArgs(match: HeavyMatch, config: HeavyCommandSettings): string[];
+// Whether a test invocation names the files it runs, for the memory gate's smaller price.
+export function targetedRun(invocation: string): boolean;
+// queue-run's `--size targeted` for a targeted test run under a test rule, else nothing.
+export function sizeArgs(match: HeavyMatch, invocation: string): string[];
 export function holdWarnSeconds(maxHold: number): number | undefined;
 export function ruleById(config: HeavyCommands, id: string): HeavyCommandRule | undefined;

package/src/heavy/heavy-turn.cjs

@@ -15,7 +15,7 @@
 const { spawnSync } = require("node:child_process");
 const { accessSync, constants, readFileSync, writeFileSync } = require("node:fs");
 const { getPriority, setPriority } = require("node:os");
-const { matchInvocation, queueArgs } = require("./heavy-rules.cjs");
+const { matchInvocation, queueArgs, sizeArgs } = require("./heavy-rules.cjs");
 
 // The spec the daemon handed down, or undefined when this program is not under it or is already covered.
 const pendingSpec = (env = process.env) => {
@@ -92,13 +92,14 @@ const takeTurn = ({ program, args, command, env = process.env }) => {
     if (spec === undefined) {
         return false;
     }
-    const match = matchInvocation([program, ...args].join(" "), spec.rules);
+    const invocation = [program, ...args].join(" ");
+    const match = matchInvocation(invocation, spec.rules);
     if (match === undefined) {
         return false;
     }
     env.INTENTIC_HEAVY_HELD = match.id;
     applyClass(spec.klass);
-    const queue = spec.queue === true && typeof spec.queueRun === "string" && runnable(spec.queueRun) ? [spec.queueRun, ...queueArgs(match, spec.rules), "--"] : [];
+    const queue = spec.queue === true && typeof spec.queueRun === "string" && runnable(spec.queueRun) ? [spec.queueRun, ...queueArgs(match, spec.rules), ...sizeArgs(match, invocation), "--"] : [];
     const runner = spec.offload?.[match.id];
     if (runner !== undefined && typeof spec.offloadRun === "string") {
         const here = queue.length === 0 ? "" : `${queue.map(quote).join(" ")} `;

package/src/memory-room.d.mts

@@ -3,6 +3,9 @@ export type RoomWorkload = "agentRuntime" | "service" | "panel" | "install" | "c
 
 export const COST_BYTES: Readonly<Record<RoomWorkload, number>>;
 export const PERSON_RESERVE_BYTES: number;
+export const TARGETED_RUN_BYTES: number;
+// A toolchain command aimed at named files, priced at TARGETED_RUN_BYTES instead of its class's cost.
+export type RoomSize = "targeted";
 export const TEST_PROCESS_BYTES: Readonly<{ fanOutWorker: number; standaloneWorker: number; typecheck: number; ceiling: number }>;
 export const STALL_PERCENT: number;
 export const RESERVATION_MS: number;
@@ -12,7 +15,7 @@ export const READING_FILES: readonly string[];
 export interface MemoryReading {
     // memory.high, else memory.max, else the machine's memory; undefined where nothing bounds it.
     readonly limitBytes: number | undefined;
-    // Working set plus swap; undefined where nothing measures it.
+    // Working set plus swap; undefined where nothing measures it. Free memory is counted against its resident part.
     readonly usedBytes: number | undefined;
     // The swapped part of `usedBytes`; 0 when swap is off or unaccounted.
     readonly swapBytes: number;
@@ -50,8 +53,12 @@ export interface RoomAnswer extends RoomJudgement {
 
 export function readingFrom(read: (path: string) => string | undefined): MemoryReading;
 export function readReadingSync(): MemoryReading;
-export function needBytes(workload: RoomWorkload, attended: boolean): number;
-export function judge(reading: MemoryReading, request: { readonly workload: RoomWorkload; readonly attended: boolean; readonly reservedBytes?: number }): RoomJudgement;
+export function costBytesOf(workload: RoomWorkload, size?: RoomSize): number;
+export function needBytes(workload: RoomWorkload, attended: boolean, size?: RoomSize): number;
+export function judge(
+    reading: MemoryReading,
+    request: { readonly workload: RoomWorkload; readonly attended: boolean; readonly reservedBytes?: number; readonly size?: RoomSize | undefined },
+): RoomJudgement;
 export function freeBytesOf(reading: MemoryReading): number | undefined;
 export function askRoom(options?: {
     readonly workload?: RoomWorkload;
@@ -60,6 +67,8 @@ export function askRoom(options?: {
     readonly socketPath?: string;
     readonly intervalMs?: number;
     readonly read?: () => MemoryReading;
+    readonly size?: RoomSize;
+    readonly pid?: number;
 }): Promise<RoomAnswer>;
 export function askFree(options?: { readonly socketPath?: string; readonly read?: () => MemoryReading }): Promise<{
     readonly freeBytes: number | undefined;

package/src/memory-room.mjs

@@ -9,8 +9,12 @@
 //          memory, never more than the machine's
 //   used   the working set (memory.current less the inactive file cache the kernel reclaims first) plus what was
 //          pushed to swap; at a root cgroup, which has no memory.current, the machine's own used memory and swap
-//   free   limit − used, and never more than the machine itself has available (MemAvailable): a sandbox on a
-//          shared machine cannot take memory the machine does not have, whatever its own limit says
+//   free   limit − the resident part of used, and never more than the machine itself has available (MemAvailable): a
+//          sandbox on a shared machine cannot take memory the machine does not have, whatever its own limit says.
+//          Swap is not subtracted: the limit bounds resident pages only, and cold pages parked in swap leave that room
+//          free. Counting them held every heavy command for minutes on a sandbox with 8 GB available (measured
+//          2026-09-26..10-02: 4.2 GiB of idle swap, 17 h of gate waits a week). Swap that is being paged back in shows
+//          as stall, below, which holds work whatever the bytes say.
 //   stall  memory PSI `full avg10`: the share of the last ten seconds in which everything waited on memory
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync, realpathSync } from "node:fs";
@@ -34,6 +38,11 @@ export const COST_BYTES = Object.freeze({
     toolchain: GIB,
 });
 
+// What a toolchain command aimed at named files takes: one bun worker over one test file, not a package's suite
+// (measured 2026-10-02: a 63-test file ran in 16 ms well under 300 MiB). heavy-rules.cjs `targetedRun` decides it from
+// the invocation, and queue-run passes it as `--size targeted`.
+export const TARGETED_RUN_BYTES = 512 * MIB;
+
 // What one test or typecheck process holds at its peak, for the scripts that size a fan-out to the free memory
 // (_tools/scripts/verify/test-workers.mjs) and the ceiling that stops a runaway one (_tools/scripts/lib/memory-ceiling.mjs).
 export const TEST_PROCESS_BYTES = Object.freeze({
@@ -139,16 +148,20 @@ export const readReadingSync = () => readingFrom(readSync);
 
 const gib = (bytes) => `${(bytes / GIB).toFixed(1)} GiB`;
 
+/** What one more of `workload` costs: its class's cost, or a targeted run's where `size` says so. */
+export const costBytesOf = (workload, size) =>
+    workload === "toolchain" && size === "targeted" ? TARGETED_RUN_BYTES : (COST_BYTES[workload] ?? COST_BYTES.agentRuntime);
+
 /** What starting one more of `workload` needs free: its own cost, plus a person's turn when nobody is waiting on it. */
-export const needBytes = (workload, attended) => (COST_BYTES[workload] ?? COST_BYTES.agentRuntime) + (attended ? 0 : PERSON_RESERVE_BYTES);
+export const needBytes = (workload, attended, size) => costBytesOf(workload, size) + (attended ? 0 : PERSON_RESERVE_BYTES);
 
 /**
  * The verdict for one more of `workload`: `run`, or, when the sandbox is short, `refuse` for work a person is waiting
  * on (they are told, and decide) and `wait` for work nobody is (it is held until there is room). `reservedBytes` is what
  * other admissions still hold off the reading. An unmeasurable sandbox has no opinion, and runs.
  */
-export const judge = (reading, { workload, attended, reservedBytes = 0 }) => {
-    const need = needBytes(workload, attended);
+export const judge = (reading, { workload, attended, reservedBytes = 0, size }) => {
+    const need = needBytes(workload, attended, size);
     const { limitBytes, usedBytes, swapBytes, stallPercent, availableBytes } = reading;
     const unreserved = freeBytesOf(reading);
     if (limitBytes === undefined || usedBytes === undefined || unreserved === undefined) {
@@ -171,12 +184,12 @@ export const judge = (reading, { workload, attended, reservedBytes = 0 }) => {
         return { verdict: "run", needBytes: need, freeBytes, reservedBytes };
     }
     // The machine, not the sandbox's own limit, is what ran out: saying "9 of 16 GiB used" would read as a wrong refusal.
-    if (availableBytes !== undefined && availableBytes < limitBytes - usedBytes) {
+    if (availableBytes !== undefined && availableBytes < limitBytes - (usedBytes - swapBytes)) {
         const held = reservedBytes > 0 ? `, and ${gib(reservedBytes)} held for work that just started` : "";
         return shortOf(`Sandbox memory is low: the machine it runs on has ${gib(availableBytes)} available${held}`);
     }
     // Resident and swapped are named apart once paging starts: the limit bounds resident pages only, so their sum can
-    // exceed it, and "19.2 GiB of 16.0 GiB used" reads as a bug.
+    // exceed it, and "19.2 GiB of 16.0 GiB used" reads as a bug. Free is counted against the resident part alone.
     const used =
         swapBytes > 0
             ? `${gib(usedBytes - swapBytes)} resident + ${gib(swapBytes)} swapped, against ${gib(limitBytes)}`
@@ -186,17 +199,26 @@ export const judge = (reading, { workload, attended, reservedBytes = 0 }) => {
     return shortOf(`Sandbox memory is low: ${used}${held}`, { limitBytes, residentBytes: usedBytes - swapBytes, swapBytes });
 };
 
-/** Free memory as the formula counts it, or undefined where nothing bounds or measures it. */
+/** Free memory as the formula counts it (the limit less what is resident), or undefined where nothing bounds or measures it. */
 export const freeBytesOf = (reading) =>
     reading.limitBytes === undefined || reading.usedBytes === undefined
         ? undefined
-        : Math.max(0, Math.min(reading.limitBytes - reading.usedBytes, reading.availableBytes ?? Number.POSITIVE_INFINITY));
+        : Math.max(
+              0,
+              Math.min(reading.limitBytes - (reading.usedBytes - (reading.swapBytes ?? 0)), reading.availableBytes ?? Number.POSITIVE_INFINITY),
+          );
 
 // ---- asking the daemon, with the formula itself as the fallback ----
 
-const askSocket = (workload, waitSeconds, label, socketPath) =>
+const askSocket = (workload, waitSeconds, label, socketPath, size, pid) =>
     new Promise((resolve) => {
         const query = new URLSearchParams({ class: workload, wait: String(waitSeconds), label });
+        if (size !== undefined) {
+            query.set("size", size);
+        }
+        if (pid !== undefined) {
+            query.set("pid", String(pid));
+        }
         const asked = request({ socketPath, path: `/room?${query}`, method: "GET", timeout: (waitSeconds + 15) * 1000 }, (response) => {
             let body = "";
             response.setEncoding("utf8");
@@ -266,24 +288,36 @@ const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 /**
  * The daemon's verdict for one more of `workload`, waiting up to `waitSeconds` for room; where no daemon answers, the
  * same formula over the same files, polled every `intervalMs`. Never throws: every failure is an answer of `run`.
+ * `size: "targeted"` prices a toolchain command aimed at named files (TARGETED_RUN_BYTES); `pid` is the process the
+ * admitted work runs as, whose exit hands its reservation back at once instead of after RESERVATION_MS.
  */
-export const askRoom = async ({ workload = "toolchain", waitSeconds = 0, label = "command", socketPath = ROOM_SOCKET, intervalMs = 5_000, read = readReadingSync } = {}) => {
-    const answered = await askSocket(workload, waitSeconds, label, socketPath);
+export const askRoom = async ({
+    workload = "toolchain",
+    waitSeconds = 0,
+    label = "command",
+    socketPath = ROOM_SOCKET,
+    intervalMs = 5_000,
+    read = readReadingSync,
+    size,
+    pid,
+} = {}) => {
+    const answered = await askSocket(workload, waitSeconds, label, socketPath, size, pid);
     if (answered !== undefined) {
         return { ...answered, source: "daemon" };
     }
     const startedAt = Date.now();
-    let verdict = judge(read(), { workload, attended: false });
+    let verdict = judge(read(), { workload, attended: false, size });
     while (verdict.verdict !== "run" && Date.now() - startedAt < waitSeconds * 1000) {
         await sleep(intervalMs);
-        verdict = judge(read(), { workload, attended: false });
+        verdict = judge(read(), { workload, attended: false, size });
     }
     return { ...verdict, waitedMs: Date.now() - startedAt, source: "formula" };
 };
 
-// `memory-room --class toolchain --wait 120 --label NAME` holds a command until there is room, printing why it waited,
-// and always exits 0: a gate that cannot read the sandbox must not be the reason a command did not run. `--json` prints
-// the answer instead; `--free` prints the free memory as the daemon counts it, for a caller that sizes itself to it.
+// `memory-room --class toolchain --wait 120 --label NAME [--size targeted] [--pid PID]` holds a command until there is
+// room, printing why it waited, and always exits 0: a gate that cannot read the sandbox must not be the reason a command
+// did not run. `--json` prints the answer instead; `--free` prints the free memory as the daemon counts it, for a caller
+// that sizes itself to it.
 const main = async (args) => {
     const option = (name, fallback) => {
         const at = args.indexOf(`--${name}`);
@@ -295,7 +329,15 @@ const main = async (args) => {
     }
     const waitSeconds = Math.max(0, Number(option("wait", "0")) || 0);
     const label = option("label", "command");
-    const answer = await askRoom({ workload: option("class", "toolchain"), waitSeconds, label, intervalMs: Math.max(50, Number(option("interval-ms", "5000")) || 5000) });
+    const pid = Number(option("pid", ""));
+    const answer = await askRoom({
+        workload: option("class", "toolchain"),
+        waitSeconds,
+        label,
+        intervalMs: Math.max(50, Number(option("interval-ms", "5000")) || 5000),
+        size: option("size", undefined) === "targeted" ? "targeted" : undefined,
+        pid: Number.isInteger(pid) && pid > 1 ? pid : undefined,
+    });
     if (args.includes("--json")) {
         process.stdout.write(`${JSON.stringify(answer)}\n`);
         return;