@raresportan/marram 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rares Portan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @raresportan/marram
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The gate, ratchet lints and journeys that keep agent-written code from drifting.
+
+See [Marram](https://github.com/raresportan/marram) for the guide.

package/bin/marram.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+// Usage:
+//   marram gate [fast | full]                  run the project's gate (src/gate.mjs)
+//   marram hook <mode>                         the gate where work is declared done (src/hook.mjs)
+//   marram commit-lint <message file>          a review fix names each finding's class and rung (src/commit-lint.mjs)
+//   marram commit-lint --range <from>..<to>
+import { lintCommits } from "../src/core/commit-lint.mjs";
+import { load } from "../src/core/config.mjs";
+import { gate } from "../src/core/gate.mjs";
+import { hook } from "../src/core/hook.mjs";
+
+const [command, ...args] = process.argv.slice(2);
+const commands = { gate, hook, "commit-lint": lintCommits };
+if (!(command in commands)) {
+	console.error("Usage: marram gate [fast | full] | marram hook <mode> | marram commit-lint <message file> | --range <from>..<to>");
+	process.exit(1);
+}
+const { root, config } = await load();
+await commands[command](root, config, args);

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@raresportan/marram",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "The gate, ratchet lints and journeys that keep agent-written code from drifting.",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/raresportan/marram.git",
+    "directory": "packages/marram"
+  },
+  "files": ["src", "bin"],
+  "bin": {
+    "marram": "bin/marram.mjs"
+  },
+  "exports": {
+    "./core/boundaries": "./src/core/boundaries.mjs",
+    "./core/check-lint": "./src/core/check-lint.mjs",
+    "./core/no-comments": "./src/core/no-comments.mjs",
+    "./core/ratchet": "./src/core/ratchet.mjs",
+    "./core/until": "./src/core/until.ts",
+    "./node/background": "./src/node/background.ts",
+    "./node/promise-lint": "./src/node/promise-lint.mjs",
+    "./node/resource-lint": "./src/node/resource-lint.mjs",
+    "./node/scope": "./src/node/scope.ts",
+    "./react/effect-lint": "./src/react/effect-lint.mjs",
+    "./react/keyed": "./src/react/keyed.ts",
+    "./electron/feature-map": "./src/electron/feature-map.ts",
+    "./electron/frames": "./src/electron/frames.ts",
+    "./electron/geometry": "./src/electron/geometry.ts",
+    "./electron/journey-lint": "./src/electron/journey-lint.mjs",
+    "./electron/run": "./src/electron/run.ts",
+    "./electron/session": "./src/electron/session.ts"
+  },
+  "scripts": {
+    "test": "node --test \"test/**/*.test.mjs\""
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "peerDependencies": {
+    "playwright-core": "*",
+    "react": "^19.3.0",
+    "typescript": "^5.9.3"
+  },
+  "peerDependenciesMeta": {
+    "playwright-core": { "optional": true },
+    "react": { "optional": true }
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/core/boundaries.mjs

@@ -0,0 +1,76 @@
+// Where code runs decides what it may import. Main-process code imported into a renderer slows the UI, and a feature
+// reaching into another's folder ties them together for good, so the import graph is a rule, not a convention.
+//
+// A project names its layers by folder pattern (`features/*/client`, `*` being one folder). A file may import from its
+// own layer and from the layers it lists. It may reach another feature (`features/<name>`) only through an `index.ts`:
+// the feature's own, or that of one of its sides, as an app's main process needs its host and its renderer its client,
+// and one index for both would pull the host into the renderer. Only a layer with `builtins: true` may import `node:` modules or `electron`. Existing violations go on a
+// ratchet list, by `file -> import`.
+import { dirname, relative, resolve, sep } from "node:path";
+import ts from "typescript";
+import { lineOf, parse, ratchet, sourceFiles } from "./ratchet.mjs";
+
+const posix = (path) => path.split(sep).join("/");
+
+/** A pattern as a test of a path's start, `*` standing for one folder, and what it matched, for telling features apart. */
+const matcher = (pattern) => new RegExp(`^(${pattern.split("*").join("[^/]+")})(/|$)`);
+
+/** The layer pattern a path (from the folder) is in, with the folder it matched: the longest match wins. */
+function layerOf(path, layers) {
+	let found;
+	for (const pattern of Object.keys(layers)) {
+		const match = matcher(pattern).exec(path);
+		if (match !== null && (found === undefined || match[1].length > found.folder.length)) found = { pattern, folder: match[1] };
+	}
+	return found;
+}
+
+/** The feature folder (`features/<name>`) of a path, if it's in one. */
+const featureOf = (path) => /^(features\/[^/]+)(\/|$)/.exec(path)?.[1];
+
+/** A feature's way in: its folder's `index.ts`, or the `index.ts` of one of its sides (`host/index.ts`, `client/index.ts`). */
+const isEntry = (target, feature) => target === feature || /^features\/[^/]+(\/[^/]+)?\/index(\.tsx?)?$/.test(target);
+
+const isBuiltin = (specifier) => specifier === "electron" || specifier.startsWith("node:");
+
+/** What's wrong with `from` (a path from the folder) importing `specifier`, if anything. */
+function problem(from, specifier, layers) {
+	const mine = layerOf(from, layers);
+	if (isBuiltin(specifier)) return layers[mine?.pattern]?.builtins === true || mine === undefined ? undefined : `${mine.pattern} may not import ${specifier}, which needs a host`;
+	if (!specifier.startsWith(".")) return undefined;
+	const target = posix(relative(".", resolve(dirname(from), specifier)));
+	const theirFeature = featureOf(target);
+	if (theirFeature !== undefined && theirFeature !== featureOf(from)) return isEntry(target, theirFeature) ? undefined : `reaches inside ${theirFeature}: import an index.ts`;
+	const theirs = layerOf(target, layers);
+	if (mine === undefined || theirs === undefined || theirs.pattern === mine.pattern) return undefined;
+	return (layers[mine.pattern].may ?? []).includes(theirs.pattern) ? undefined : `${mine.pattern} may not import from ${theirs.pattern}`;
+}
+
+/** Import specifiers in `source`, including `export … from` and `import()`, each with its node; types count too. */
+function imports(source) {
+	const found = [];
+	const visit = (node) => {
+		const named = (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) ? node.moduleSpecifier : ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword ? node.arguments[0] : undefined;
+		if (named !== undefined && ts.isStringLiteralLike(named)) found.push(named);
+		ts.forEachChild(node, visit);
+	};
+	visit(source);
+	return found;
+}
+
+/**
+ * Problems with the imports under `root`/`folder`, given its `layers` (`{ pattern: { may: [patterns], builtins? } }`),
+ * against the ratchet list `allowed` (`{ "file -> import": reason }`, kept in `list`).
+ */
+export function importBoundaries({ root, folder, layers, allowed = {}, list }) {
+	const base = resolve(root, folder);
+	const found = sourceFiles(base).flatMap((file) => {
+		const source = parse(file);
+		const from = posix(relative(base, file));
+		return imports(source).flatMap((specifier) => {
+			const wrong = problem(from, specifier.text, layers);
+			return wrong === undefined ? [] : [{ key: `${from} -> ${specifier.text}`, at: `${folder}/${from}:${lineOf(source, specifier)}`, what: wrong }];
+		});
+	});
+	return ratchet({ list, allowed, found, fix: "move the code to a layer that may have it", stale: "is no longer imported that way" });
+}

package/src/core/check-lint.mjs

@@ -0,0 +1,107 @@
+// A check runner judges a check by its exit code alone, so a check that prints what it saw without asserting it passes
+// whatever the code does, even while a feature map cites it. So a check file must be able to fail on what it sees: a
+// `node:assert` call, a `throw` (in it or in a helper it defines), or a non-zero exit (`process.exit(1)`,
+// `process.exitCode = 1`). A crash alone doesn't count.
+//
+// And waits go through `until` (./until.ts). A loop that sleeps until something holds is a wait of the check's own:
+// each one has its own bound and a failure that says neither how long it waited nor what it saw, and some run on when
+// time is up as though what they waited for had happened. An upper bound on elapsed time (`Date.now() - started < 900`)
+// is a guess at the machine's speed that fails under load: `sooner` measures it against how long the broken behaviour
+// takes instead.
+import { readdirSync } from "node:fs";
+import { join, relative } from "node:path";
+import ts from "typescript";
+import { lineOf, parse } from "./ratchet.mjs";
+
+export const WAITS = "@raresportan/marram/core/until";
+
+/** The names an import clause binds: its default, its namespace, or each named import. */
+function bound(clause) {
+	const bindings = clause?.namedBindings;
+	if (bindings !== undefined && ts.isNamespaceImport(bindings)) return [clause.name?.text, bindings.name.text];
+	return [clause?.name?.text, ...(bindings !== undefined && ts.isNamedImports(bindings) ? bindings.elements.map((element) => element.name.text) : [])];
+}
+
+/** The names `source` binds to `node:assert`, or to `waits`, whose waits fail when time is up. */
+function assertNames(source, waits) {
+	const failing = (from) => /^(node:)?assert(\/strict)?$/.test(from) || from === waits;
+	return new Set(source.statements.filter((statement) => ts.isImportDeclaration(statement) && failing(statement.moduleSpecifier.text)).flatMap((statement) => bound(statement.importClause)).filter(Boolean));
+}
+
+const isProcess = (node, property) => ts.isPropertyAccessExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === "process" && node.name.text === property;
+const nonZero = (node) => node !== undefined && !(ts.isNumericLiteral(node) && node.text === "0");
+
+/** How `node` can fail the check, or undefined. */
+function failure(node, asserts) {
+	if (ts.isThrowStatement(node)) return "throw";
+	if (ts.isCallExpression(node)) {
+		const callee = ts.isPropertyAccessExpression(node.expression) ? node.expression.expression : node.expression;
+		if (ts.isIdentifier(callee) && asserts.has(callee.text)) return "assert";
+		if (isProcess(node.expression, "exit") && nonZero(node.arguments[0])) return "exit";
+	}
+	if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.EqualsToken && isProcess(node.left, "exitCode") && nonZero(node.right)) return "exit";
+	return undefined;
+}
+
+function canFail(source, waits) {
+	const asserts = assertNames(source, waits);
+	let found = false;
+	const visit = (node) => {
+		if (found) return;
+		if (failure(node, asserts) !== undefined) found = true;
+		else ts.forEachChild(node, visit);
+	};
+	visit(source);
+	return found;
+}
+
+const isNow = (node) => ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === "now" && ts.isIdentifier(node.expression.expression) && ["Date", "performance"].includes(node.expression.expression.text);
+const contains = (node, test) => test(node) || (ts.forEachChild(node, (child) => (contains(child, test) ? true : undefined)) ?? false);
+/** A time measured from a clock: `Date.now() - started`, or a name holding one. */
+const isElapsed = (node, elapsed) => contains(node, (part) =>
+	(ts.isBinaryExpression(part) && part.operatorToken.kind === ts.SyntaxKind.MinusToken && contains(part.left, isNow)) || (ts.isIdentifier(part) && elapsed.has(part.text)));
+/** Waiting on a timer: `setTimeout`, or a helper named for sleeping. */
+const isTimer = (node) => ts.isCallExpression(node) && ts.isIdentifier(node.expression) && /^(setTimeout|sleep|wait|delay)$/.test(node.expression.text);
+/**
+ * A loop that can go round until something holds. A loop over a list (`for…of`) runs its cases, sleeping between steps
+ * to stage a race, and isn't one; nor is a loop with a `// Not a wait:` comment saying what it is (a retry).
+ */
+const isOpenLoop = (node, source) =>
+	(ts.isForStatement(node) || ts.isWhileStatement(node) || ts.isDoStatement(node)) &&
+	!(ts.getLeadingCommentRanges(source.text, node.getFullStart()) ?? []).some((range) => source.text.slice(range.pos, range.end).includes("Not a wait:"));
+
+/** The waits and time bounds `source` has of its own, with their lines. */
+function ownWaits(source, waits) {
+	const elapsed = new Set();
+	const found = [];
+	const visit = (node) => {
+		if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer !== undefined && isElapsed(node.initializer, elapsed)) elapsed.add(node.name.text);
+		if (isOpenLoop(node, source) && contains(node, (part) => ts.isAwaitExpression(part) && contains(part, isTimer))) {
+			found.push(`line ${lineOf(source, node)}: a loop that sleeps until something holds: wait with until() from ${waits}, which says what it saw`);
+			return;
+		}
+		if (ts.isBinaryExpression(node)) {
+			const kind = node.operatorToken.kind;
+			const below = [ts.SyntaxKind.LessThanToken, ts.SyntaxKind.LessThanEqualsToken].includes(kind) ? node.left : [ts.SyntaxKind.GreaterThanToken, ts.SyntaxKind.GreaterThanEqualsToken].includes(kind) ? node.right : undefined;
+			if (below !== undefined && isElapsed(below, elapsed)) found.push(`line ${lineOf(source, node)}: an upper bound on elapsed time fails under load: use sooner() from ${waits}, measured against how long the broken behaviour takes`);
+		}
+		ts.forEachChild(node, visit);
+	};
+	visit(source);
+	return found;
+}
+
+/** What's wrong with one check's `source`: it can't fail, or it waits or bounds time on its own. `waits` is where `until` comes from. */
+export function checkProblems(source, waits = WAITS) {
+	return [
+		...(canFail(source, waits) ? [] : ["asserts nothing, so it passes whatever the code does: assert what it sees (node:assert), throw, or exit non-zero"]),
+		...ownWaits(source, waits),
+	];
+}
+
+/** Problems in each file of `root`/`folder` whose name `match`es, as `path, problem`; and how many files there were. */
+export function lintChecks({ root, folder, match, waits = WAITS }) {
+	const base = join(root, folder);
+	const files = readdirSync(base).filter((name) => match.test(name)).map((name) => join(base, name));
+	return { files: files.length, problems: files.flatMap((file) => checkProblems(parse(file), waits).map((problem) => `${relative(root, file)}: ${problem}`)) };
+}

package/src/core/commit-lint.mjs

@@ -0,0 +1,53 @@
+// A commit that fixes review findings names, for each one, its mistake class and the rung that now catches it (the
+// project's mistake-classes doc, `review.classes` in marram.config.mjs). Without that, review findings only ever produce
+// point fixes: nobody sees that a class keeps recurring, or that no rung could have caught it.
+//
+// Applies to a commit whose subject fixes review findings or gaps. Each top-level bullet (`- `) of its body is one
+// finding and needs a line `Class: <a class, joined by / if between two, or new>. Rung: <a rung | none, because …> …`.
+// A body with no bullets needs one such line. The classes are the doc's table rows (`| **A**: …`); the rungs are
+// `review.rungs`.
+// Usage: marram commit-lint <message file>   (the commit-msg hook)
+//        marram commit-lint --range <from>..<to>   (each commit in a range)
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const REVIEW_FIX = /\breview (findings?|gaps?)\b/i;
+const RUNGS = ["type", "lint", "architecture", "check", "journey", "unit"];
+
+/** The class names in a mistake-classes doc: each table row that starts with a bold name. */
+export function classesIn(doc) {
+	return [...doc.matchAll(/^\| \*\*([A-Za-z0-9-]+)\*\*/gm)].map(([, name]) => name);
+}
+
+/** What's wrong with a commit message, if anything, given the project's classes and rungs. */
+export function problems(message, { classes, rungs = RUNGS }) {
+	const lines = message.split("\n").filter((line) => !line.startsWith("#"));
+	const subject = lines[0] ?? "";
+	if (!REVIEW_FIX.test(subject) || subject.startsWith("Merge ")) return [];
+	const one = `(?:${classes.join("|")})`;
+	const named = new RegExp(`\\bClass: (?:${one}(?:\\/${one})*|new)\\b[^\\n]*?\\bRung: (?:(?:${rungs.join("|")})\\b|none, because \\S)`);
+	const body = lines.slice(1);
+	const findings = [];
+	for (const line of body) {
+		if (line.startsWith("- ")) findings.push([line]);
+		else findings.at(-1)?.push(line);
+	}
+	const example = `\`Class: <${classes[0]}-${classes.at(-1)}>. Rung: <kind> …\``;
+	if (findings.length === 0) return named.test(body.join("\n")) ? [] : [`it fixes review findings but names no class and rung: add ${example}`];
+	return findings.flatMap((finding) => (named.test(finding.join("\n")) ? [] : [`"${finding[0].slice(2, 72)}" names no class and rung: add ${example}`]));
+}
+
+export function lintCommits(root, config, [mode, target]) {
+	const doc = config.review.classes;
+	const rules = { classes: classesIn(readFileSync(join(root, doc), "utf8")), rungs: config.review.rungs };
+	if (rules.classes.length === 0) throw new Error(`${doc} lists no classes: its table rows start with | **<name>**`);
+	const messages = mode === "--range"
+		? execFileSync("git", ["log", "--format=%H%x00%B%x01", target], { cwd: root, encoding: "utf8" }).split("\x01").filter((entry) => entry.trim() !== "").map((entry) => entry.trim().split("\x00"))
+		: mode === undefined ? [] : [["this commit", readFileSync(mode, "utf8")]];
+	const found = messages.flatMap(([commit, message]) => problems(message, rules).map((problem) => `${commit.slice(0, 12)}: ${problem}`));
+	if (found.length > 0) {
+		console.error(`commit-lint: a fix for review findings names each one's class and rung (${doc})\n${found.map((problem) => `  ${problem}`).join("\n")}`);
+		process.exit(1);
+	}
+}

package/src/core/config.mjs

@@ -0,0 +1,23 @@
+// A project tells Marram what its gate runs and what its review fixes are held to in `marram.config.mjs`, at its root:
+//
+//   export default {
+//     gate: {
+//       logs: "where each run's logs go",
+//       progress: /lines from a stage worth showing as it runs/,   // besides ✓ and ✗ lines
+//       tiers: { fast: [stage, …], default: [stage, …], full: [stage, …] },  // stage: { name, run: [command, …args], env? }
+//     },
+//     review: { classes: "the mistake-classes doc", rungs: ["type", "lint", …] },
+//   };
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+const FILE = "marram.config.mjs";
+
+/** The project root, the nearest folder from `from` up that has a marram.config.mjs, and its config. */
+export async function load(from = process.cwd()) {
+	for (let dir = resolve(from); ; dir = dirname(dir)) {
+		if (existsSync(join(dir, FILE))) return { root: dir, config: (await import(pathToFileURL(join(dir, FILE)).href)).default };
+		if (dirname(dir) === dir) throw new Error(`No ${FILE} in ${resolve(from)} or above it.`);
+	}
+}

package/src/core/gate-state.mjs

@@ -0,0 +1,86 @@
+// What the gate said about each state of the working tree, so a hook doesn't run it again for code it has judged.
+// Kept in the repository's git folder (shared by its worktrees): marram-gate.json.
+import { execFileSync } from "node:child_process";
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+
+// A failure is reused this long, then the gate runs again: a flaky check gets another chance without a code change.
+const FAILURE_TTL_MS = 15 * 60 * 1000;
+const KEEP = 50;
+// What the lock guards takes milliseconds, so a lock this old was left by a hook that was killed.
+const STALE_LOCK_MS = 10_000;
+
+export const git = (cwd, args, env = {}) => execFileSync("git", args, { cwd, encoding: "utf8", env: { ...process.env, ...env } }).trim();
+
+/** The working tree as a git tree hash: tracked and untracked files, not ignored ones. Same hash, same code. */
+export function treeOf(cwd) {
+	const dir = mkdtempSync(join(tmpdir(), "marram-gate-"));
+	const index = join(dir, "index");
+	try {
+		// A copy of the real index, so unchanged files aren't hashed again.
+		const real = resolve(cwd, git(cwd, ["rev-parse", "--git-path", "index"]));
+		if (existsSync(real)) copyFileSync(real, index);
+		git(cwd, ["add", "-A"], { GIT_INDEX_FILE: index });
+		return git(cwd, ["write-tree"], { GIT_INDEX_FILE: index });
+	} finally {
+		rmSync(dir, { recursive: true, force: true });
+	}
+}
+
+const statePath = (cwd) => join(resolve(cwd, git(cwd, ["rev-parse", "--git-common-dir"])), "marram-gate.json");
+
+export function readState(cwd) {
+	try {
+		const state = JSON.parse(readFileSync(statePath(cwd), "utf8"));
+		return { trees: state.trees ?? {}, sessions: state.sessions ?? {} };
+	} catch {
+		return { trees: {}, sessions: {} };
+	}
+}
+
+/** Run `action` holding `path`'s lock: a directory, since creating one either succeeds or finds it there. */
+function withLock(path, action) {
+	const lock = `${path}.lock`;
+	for (;;) {
+		try {
+			mkdirSync(lock);
+			break;
+		} catch (error) {
+			if (error.code !== "EEXIST") throw error;
+			const age = Date.now() - (statSync(lock, { throwIfNoEntry: false })?.mtimeMs ?? Date.now());
+			if (age > STALE_LOCK_MS) rmSync(lock, { recursive: true, force: true });
+			else Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
+		}
+	}
+	try {
+		return action();
+	} finally {
+		rmSync(lock, { recursive: true, force: true });
+	}
+}
+
+/**
+ * Read, change and write the state under its lock, so hooks running at once don't lose each other's changes; returns
+ * what `change` returns. Written to a temporary file and renamed over the old one, so a reader never sees half a file.
+ * Only the newest entries are kept.
+ */
+export function updateState(cwd, change) {
+	const path = statePath(cwd);
+	return withLock(path, () => {
+		const state = readState(cwd);
+		const result = change(state);
+		const newest = (rows) => Object.fromEntries(Object.entries(rows).sort(([, a], [, b]) => b.at - a.at).slice(0, KEEP));
+		const temporary = `${path}.${process.pid}.tmp`;
+		writeFileSync(temporary, JSON.stringify({ trees: newest(state.trees), sessions: newest(state.sessions) }, null, 2));
+		renameSync(temporary, path);
+		return result;
+	});
+}
+
+/** `{ passed, stage?, log?, at }` for a tree the default or full gate passed, or failed less than 15 minutes ago. */
+export function verdictOf(cwd, tree) {
+	const verdict = readState(cwd).trees[tree];
+	if (verdict === undefined || verdict.passed) return verdict;
+	return Date.now() - verdict.at < FAILURE_TTL_MS ? verdict : undefined;
+}

package/src/core/gate.mjs

@@ -0,0 +1,90 @@
+// One gate for every change, so "green" means the same thing by hand, in a hook, in CI and in an agent's done-check.
+// Usage: marram gate [fast | full]
+//   fast      Seconds: after each edit.
+//   (default) Minutes: before a task counts as done.
+//   full      The default gate and more (a build, the slow journeys). Before merging UI work, or nightly.
+// What each tier runs is the project's: `gate.tiers` in marram.config.mjs. Stages run in order and the first failure
+// stops the gate. Each stage's output is kept in its own log under `gate.logs`/gate-<tier>-<time>/, with report.json.
+// The default and full gates record their verdict for the working tree (gate-state.mjs), which the hooks reuse.
+import { spawn } from "node:child_process";
+import { createWriteStream } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { treeOf, updateState } from "./gate-state.mjs";
+
+const TIERS = ["fast", "default", "full"];
+
+export async function gate(root, config, [tier = "default"]) {
+	if (!TIERS.includes(tier)) {
+		console.error(`Unknown gate "${tier}". Usage: marram gate [fast | full]`);
+		process.exit(1);
+	}
+	const { logs, progress, tiers } = config.gate;
+	const dir = join(root, logs, `gate-${tier}-${new Date().toISOString().replace(/[:.]/g, "-")}`);
+	await mkdir(dir, { recursive: true });
+	const report = { tier, startedAt: new Date().toISOString(), stages: [], passed: false };
+
+	// A git hook (pre-push) runs with GIT_DIR and the like pointing at this repository; checks that make their own scratch
+	// repositories would act on this one instead.
+	const outsideGit = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith("GIT_")));
+
+	// Interrupted (Ctrl-C, a hook's timeout), the gate passes the signal to the stage it runs, so a check runner can stop
+	// what it started, and records no verdict: an interrupted gate says nothing about the code.
+	let running;
+	let interrupted = false;
+	for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+		process.once(signal, () => {
+			interrupted = true;
+			running?.kill(signal);
+		});
+	}
+
+	async function runStage({ name, run: [command, ...args], env = {} }) {
+		const started = Date.now();
+		const log = createWriteStream(join(dir, `${name}.log`));
+		const child = spawn(command, args, { cwd: root, env: { ...outsideGit, ...env }, stdio: ["ignore", "pipe", "pipe"] });
+		running = child;
+		child.stdout.pipe(log, { end: false });
+		child.stderr.pipe(log, { end: false });
+		// Progress lines (a check's ✓ or ✗, and what the project's `progress` matches); everything else stays in the log.
+		child.stdout.on("data", (chunk) => {
+			for (const line of chunk.toString().split("\n")) if (/^\s*[✓✗]/.test(line) || progress?.test(line)) console.log(`  ${name}: ${line.trim()}`);
+		});
+		const code = await new Promise((done) => {
+			child.on("error", () => done(1));
+			child.on("exit", (exit) => done(exit ?? 1));
+		});
+		log.end();
+		const seconds = Math.round((Date.now() - started) / 1000);
+		report.stages.push({ name, code, seconds });
+		await writeFile(join(dir, "report.json"), JSON.stringify(report, null, 2));
+		console.log(`${code === 0 ? "✓" : "✗"} ${name} (${seconds}s)${code === 0 ? "" : `: see ${join(dir, `${name}.log`)}`}`);
+		return code === 0;
+	}
+
+	// A fast pass doesn't make a change done, so only the default and full gates record a verdict.
+	const tree = tier === "fast" ? undefined : treeOf(root);
+	const verdict = (passed, extra = {}) => {
+		if (tree !== undefined) updateState(root, (state) => { state.trees[tree] = { passed, tier, at: Date.now(), ...extra }; });
+	};
+
+	console.log(`Gate (${tier}). Logs: ${dir}`);
+	for (const stage of tiers[tier]) {
+		const passed = await runStage(stage);
+		if (interrupted) {
+			console.log(`\nGate interrupted at ${stage.name}.`);
+			process.exit(1);
+		}
+		if (!passed) {
+			verdict(false, { stage: stage.name, log: join(dir, `${stage.name}.log`) });
+			console.log(`\nGate failed at ${stage.name}.`);
+			process.exit(1);
+		}
+	}
+	report.passed = true;
+	report.completedAt = new Date().toISOString();
+	await writeFile(join(dir, "report.json"), JSON.stringify(report, null, 2));
+	// A file changed while the gate ran: what passed isn't what's there now, so the pass isn't recorded.
+	if (tree !== undefined && treeOf(root) === tree) verdict(true);
+	console.log(`\nGate passed (${report.stages.reduce((total, stage) => total + stage.seconds, 0)}s).`);
+}