@teamscala/service-boot 0.23.327 → 0.23.328

package/src/fn-routers/task-sync-close.ts

@@ -0,0 +1,82 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Lane-close write-through for task-sync. The session-owning fleet runtime
+ * calls this ORPC procedure before releasing an ACP lane, so work_items remains
+ * the durable lifecycle source without a second raw-SQL writer in the host.
+ */
+
+import { ORPCError } from "@orpc/server";
+import * as v from "valibot";
+import { authed, type Context } from "./auth-router.ts";
+import type { Prisma, WorkItem } from "./task-sync-router.ts";
+
+export const closeLaneInput = v.object({
+	lane_session: v.pipe(v.string(), v.minLength(1, "lane_session is required")),
+	disposition: v.picklist([
+		"completed",
+		"needs_retry",
+		"failed",
+		"orchestrator_closed",
+		"orphaned",
+	]),
+});
+
+export interface ClosedTaskState {
+	task_id: string;
+	task_status: "done" | "archived";
+	completed: boolean;
+	kind_data: Record<string, unknown>;
+}
+
+export function closedTaskState(
+	task: Pick<WorkItem, "id" | "kind_data">,
+	disposition: v.InferOutput<typeof closeLaneInput>["disposition"],
+): ClosedTaskState {
+	const completed = disposition === "completed";
+	const lane =
+		task.kind_data.lane && typeof task.kind_data.lane === "object"
+			? (task.kind_data.lane as Record<string, unknown>)
+			: {};
+	return {
+		task_id: task.id,
+		task_status: completed ? "done" : "archived",
+		completed,
+		kind_data: { ...task.kind_data, lane: { ...lane, live: false } },
+	};
+}
+
+export const closeLaneHandler = authed
+	.input(closeLaneInput)
+	.handler(async ({ input, context }) => {
+		const prisma = (context as Context).prisma as Prisma;
+		const task = await prisma.work_items.findFirst({
+			where: {
+				kind: "task",
+				kind_data: { path: ["lane", "session"], equals: input.lane_session },
+			},
+			orderBy: { created_at: "desc" },
+		});
+		if (!task) {
+			throw new ORPCError("NOT_FOUND", {
+				message: `No task is bound to ACP lane ${input.lane_session}`,
+			});
+		}
+		const state = closedTaskState(task, input.disposition);
+		await prisma.work_items.update({
+			where: { id: task.id },
+			data: {
+				kind_data: state.kind_data,
+				status: state.task_status,
+				completed: state.completed,
+			},
+			select: { id: true },
+		});
+		return {
+			task_id: state.task_id,
+			task_status: state.task_status,
+			reconciled: true,
+		};
+	});

package/src/fn-routers/task-sync-dispatch.test.ts

@@ -3,42 +3,60 @@
  * @status handwritten
  * @edit edit directly
  *
- * Unit tests for the pure event-payload builder in task-sync-dispatch. The HTTP
- * POST + registry resolution are side-effectful (covered end-to-end by the
- * DB->AGENT direction demo — a published orchestrator.message with slotName
- * cross-pane delivers to the target pane's <channel> tag); buildTaskChangedEvent
- * is pure and tested here. Satisfies what-must-have-a-test / primitive-api-has-test.
+ * Unit tests for the pure durable comment-payload builder in task-sync-dispatch.
+ * The runtime path writes this payload through the canonical comments model.
  */
 import { describe, it, expect } from "bun:test";
-import { buildTaskChangedEvent } from "./task-sync-dispatch.ts";
+import { buildTaskChangeComment, notifyLaneOfTaskChange } from "./task-sync-dispatch.ts";
 
-describe("task-sync buildTaskChangedEvent", () => {
-	it("is an orchestrator.message addressed to the owning lane pane", () => {
-		const e = buildTaskChangedEvent("tmux:%5", "task-7", 1700000000000);
-		expect(e.type).toBe("orchestrator.message");
-		expect(e.orchestratorSessionId).toBe("tmux:%5");
-	});
-
-	it("uses slotName cross-pane so watchEvents bypasses the fleet-run-existence check", () => {
-		const e = buildTaskChangedEvent("tmux:%5", "task-7", 1700000000000);
-		expect(e.slotName).toBe("cross-pane");
-	});
+	describe("task-sync buildTaskChangeComment", () => {
+		it("addresses the canonical task and runtime with no pane transport", () => {
+			const comment = buildTaskChangeComment("task-7", "session-5", "subtask-1:completed");
+			expect(comment).toMatchObject({
+				work_item_id: "task-7",
+				source_cli_session_id: "session-5",
+				sender_role: "system",
+				sender_name: "TaskSync",
+			});
+			expect(comment.system_key).toBe("task-sync:task-7:session-5:subtask-1:completed");
+			expect(comment.content).toContain("readTaskList");
+			expect(comment).not.toHaveProperty("pane");
+		});
 
-	it("carries the task id in the message so the recipient can re-read just it", () => {
-		const e = buildTaskChangedEvent("tmux:%5", "task-7", 1700000000000);
-		expect(e.message).toContain("task-7");
-		expect(e.message).toContain("readTaskList");
-	});
-
-	it("produces a single-line message (the <channel> tag renders it inline)", () => {
-		const e = buildTaskChangedEvent("tmux:%5", "task-7", 1700000000000);
-		expect(e.message.includes("\n")).toBe(false);
-	});
+		it("writes one durable comment addressed by the active cli_session", async () => {
+			const calls: unknown[] = [];
+			const result = await notifyLaneOfTaskChange(
+				{
+					cli_sessions: { findFirst: async () => ({ id: "session-5" }) },
+					comments: {
+						upsert: async (args) => {
+							calls.push(args);
+							return { id: "comment-1" };
+						},
+					},
+				},
+				"task-7",
+				"subtask-1:completed",
+			);
+			expect(result).toMatchObject({ delivered: true, sessionId: "session-5", commentId: "comment-1" });
+			expect(calls[0]).toMatchObject({ create: { work_item_id: "task-7", source_cli_session_id: "session-5" } });
+		});
 
-	it("stamps the system sender + a deterministic runId + the provided epoch-ms ts", () => {
-		const e = buildTaskChangedEvent("tmux:%5", "task-7", 1700000000000);
-		expect(e.fromOrchestratorId).toBe("task-sync");
-		expect(e.runId).toBe("task-sync-task-7-1700000000000");
-		expect(e.ts).toBe(1700000000000);
+		it("does not fabricate a pre-launch session or comment", async () => {
+			let writes = 0;
+			const result = await notifyLaneOfTaskChange(
+				{
+					cli_sessions: { findFirst: async () => null },
+					comments: {
+						upsert: async () => {
+							writes++;
+							return { id: "unexpected" };
+						},
+					},
+				},
+				"task-7",
+			);
+			expect(result).toEqual({ delivered: false, sessionId: null, commentId: null });
+			expect(writes).toBe(0);
+		});
 	});
-});

package/src/fn-routers/task-sync-lane.test.ts

@@ -0,0 +1,36 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Behavioral tests for canonical CLI-session lane resolution.
+ */
+import { describe, expect, it } from "bun:test";
+import { resolveLaneWorkName } from "./task-sync-lane.ts";
+
+describe("resolveLaneWorkName", () => {
+	it("reads the visible label from the active cli_sessions route", async () => {
+		let query: unknown;
+		const name = await resolveLaneWorkName(
+			{
+				cli_sessions: {
+					findFirst: async (args: unknown) => {
+						query = args;
+						return { id: "session-1", label: "ZeroStack" };
+					},
+				},
+			} as never,
+			"tmux:%7",
+		);
+		expect(name).toBe("ZeroStack");
+		expect(query).toMatchObject({ where: { host_route: { path: ["pane_id"], equals: "tmux:%7" } } });
+	});
+
+	it("returns no unverified title when no active session owns the pane", async () => {
+		const name = await resolveLaneWorkName(
+			{ cli_sessions: { findFirst: async () => null } } as never,
+			"tmux:%8",
+		);
+		expect(name).toBeNull();
+	});
+});

package/src/fn-routers/task-sync-projection.test.ts

@@ -12,6 +12,7 @@
 import { describe, expect, it } from "bun:test";
 import {
 	STATUS_TO_WORK_ITEM,
+	deriveEvidenceProgress,
 	normalizeStatus,
 	planReconcile,
 	resolveProjectedStatus,
@@ -29,6 +30,31 @@ describe("STATUS_TO_WORK_ITEM", () => {
 	});
 });
 
+describe("evidence-derived task progress", () => {
+	it("counts only required subtasks with independent Orchestrator acceptance", () => {
+		const out = deriveEvidenceProgress(
+			[
+				{ id: "a", status: "done" },
+				{ id: "b", status: "done" },
+				{ id: "c", status: "todo", kind_data: { pm_progress: { required: false } } },
+			],
+			[
+				{ work_item_id: "a", sender_role: "orchestrator", system_key: "acceptance:a" },
+				{ work_item_id: "b", sender_role: "worker", system_key: "acceptance:b" },
+			],
+		);
+		expect(out).toEqual({ total: 2, accepted: 1, percentage: 50 });
+	});
+
+	it("does not treat prose, context, or done alone as evidence", () => {
+		expect(
+			deriveEvidenceProgress([{ id: "a", status: "done" }], [
+				{ work_item_id: "a", sender_role: "orchestrator", system_key: "progress:100" },
+			]),
+		).toEqual({ total: 1, accepted: 0, percentage: 0 });
+	});
+});
+
 describe("status translation is a single non-drifting source", () => {
 	// The forward map (CLI → work_items) is canonical; the reverse is DERIVED from
 	// it (+ a closed synonym set). This locks the structural fix: the two

package/src/fn-routers/task-sync-projection.ts

@@ -74,6 +74,57 @@ export function normalizeStatus(s: string | null): TaskListItem["status"] {
 	return (s && WORK_ITEM_TO_STATUS[s]) || "pending";
 }
 
+export interface ProgressSubtask {
+	id: string;
+	status: string | null;
+	kind_data?: Record<string, unknown> | null;
+}
+
+export interface ProgressAcceptanceEvidence {
+	work_item_id: string | null;
+	sender_role: string | null;
+	system_key: string | null;
+}
+
+export interface EvidenceProgress {
+	total: number;
+	accepted: number;
+	percentage: number;
+}
+
+/**
+ * Derive progress from the canonical checklist and independent acceptance
+ * comments. A done status without an Orchestrator acceptance comment is not
+ * evidence of completion; prose percentages and context gauges never enter
+ * this calculation. Subtasks are required by default, with an explicit
+ * `kind_data.pm_progress.required: false` opt-out for non-gating notes.
+ */
+export function deriveEvidenceProgress(
+	subtasks: ProgressSubtask[],
+	evidence: ProgressAcceptanceEvidence[],
+): EvidenceProgress {
+	const required = subtasks.filter(
+		(s) => (s.kind_data?.pm_progress as { required?: boolean } | undefined)?.required !== false,
+	);
+	const accepted = new Set(
+		evidence
+			.filter(
+				(e) =>
+					e.sender_role === "orchestrator" &&
+					typeof e.system_key === "string" &&
+					e.system_key.startsWith("acceptance:") &&
+					e.work_item_id,
+			)
+			.map((e) => e.work_item_id as string),
+	);
+	const acceptedCount = required.filter((s) => s.status === "done" && accepted.has(s.id)).length;
+	return {
+		total: required.length,
+		accepted: acceptedCount,
+		percentage: required.length === 0 ? 0 : Math.round((acceptedCount / required.length) * 100),
+	};
+}
+
 /**
  * Decide the status to WRITE for an existing row, given what the CLI list says.
  *

package/src/fn-routers/task-sync-router.test.ts

@@ -337,8 +337,20 @@ describe("a blocked row survives a CLI list that cannot express it", () => {
 	it("planReconcile leaves a blocked subtask blocked when the list says pending", () => {
 		// The end-to-end shape: this is what re-blocked the lane three times.
 		const plan = planReconcile(
-			[{ mark: "1", content: "Deploy the fix", status: "pending" }],
-			[{ id: "row-1", title: "Deploy the fix", status: "blocked", completed: false, position: "0", kind_data: { task_sync: { mark: "1" } } }] as never,
+			[
+				{
+					id: "row-1",
+					kind: "subtask",
+					parent_id: "task-1",
+					organisation_id: "org-1",
+					title: "Deploy the fix",
+					status: "blocked",
+					position: "0",
+					completed: false,
+					kind_data: { task_sync: { mark: "1" } },
+				},
+			],
+			[{ content: "Deploy the fix", status: "pending" }],
 			"claude-code",
 		);
 		const update = plan.toUpdate.find((u) => u.id === "row-1");

package/src/handlers/singleton-tools-currency-watch.ts

@@ -30,11 +30,40 @@ import { getAppLogger } from "@teamscala/logger/app-loggers";
 import { spawn } from "@teamscala/os/spawn";
 import { pgBossHandlerRegistry } from "../pg-boss-handler-registry.ts";
 
-interface VersionSource {
-	type: "npm_package";
-	name: string;
-	dist_tag: string;
-}
+/**
+ * Where a tool's "latest" comes from.
+ *
+ * A DISCRIMINATED UNION, deliberately, rather than an optional `repo` field
+ * hanging off one shape: an unhandled variant then fails to compile instead of
+ * silently taking the npm branch. The previous single-member form
+ * (`type: "npm_package"`) made a GitHub-released binary UNREPRESENTABLE, not
+ * merely unregistered — which is why codex and zerostack are absent from
+ * `config/scala-singleton-tools` entirely. Both are standalone ELF binaries in
+ * ~/.local/bin and neither is npm-managed, so neither could be described at all.
+ *
+ * Their LOCATION is correct and must not be "fixed": `bun-bin-is-unstable`
+ * designates ${HOME}/.local/bin as the home for operator CLIs precisely so they
+ * never shadow a /usr/local/bin singleton wrapper. The gap was currency
+ * tracking, never placement.
+ */
+type VersionSource =
+	| {
+			type: "npm_package";
+			name: string;
+			dist_tag: string;
+	  }
+	| {
+			/** A GitHub release asset — the shape codex and zerostack ship as. */
+			type: "github_release";
+			/** "owner/repo". */
+			repo: string;
+			/**
+			 * Regex matched against each release asset's name to pick the download.
+			 * Required: a repo publishing several platform builds has no safe default,
+			 * and guessing one installs the wrong architecture silently.
+			 */
+			asset_pattern: string;
+	  };
 
 interface SingletonTool {
 	name: string;
@@ -98,9 +127,13 @@ function semverLt(a: string, b: string): boolean {
 /** Read the installed version from a tool's real_path (symlink-resolved binary). */
 async function readInstalledVersion(tool: SingletonTool): Promise<string | null> {
 	try {
-		if (tool.kind === "js" && tool.install_dir) {
+		const vs = tool.version_source;
+		// The package.json path only exists for an npm-sourced JS tool. A
+		// github_release tool has no node_modules entry, so it falls through to the
+		// `--version` probe below like any other binary.
+		if (tool.kind === "js" && tool.install_dir && vs?.type === "npm_package") {
 			// JS tools: read the installed package's package.json
-			const pkgJsonPath = `${tool.install_dir}/node_modules/${tool.version_source!.name}/package.json`;
+			const pkgJsonPath = `${tool.install_dir}/node_modules/${vs.name}/package.json`;
 			const pkg = await Bun.file(pkgJsonPath).json() as { version: string };
 			return pkg.version;
 		}
@@ -119,6 +152,30 @@ async function readInstalledVersion(tool: SingletonTool): Promise<string | null>
 	}
 }
 
+/**
+ * Latest published version for a GitHub-released tool.
+ *
+ * Reads the repo's latest release tag rather than enumerating assets, because
+ * the tag is what carries the VERSION; the asset pattern only decides which
+ * build to download at install time. A leading "v" is stripped so the value
+ * compares against `readInstalledVersion` output under the same semver parser.
+ */
+async function fetchLatestGithubRelease(repo: string): Promise<string | null> {
+	try {
+		const res = await fetch(
+			`https://api.github.com/repos/${repo}/releases/latest`,
+			{ headers: { accept: "application/vnd.github+json" } },
+		);
+		if (!res.ok) return null;
+		const release = (await res.json()) as { tag_name?: string };
+		const tag = (release.tag_name ?? "").trim().replace(/^v/, "");
+		if (!tag || !parseSemver(tag)) return null;
+		return tag;
+	} catch {
+		return null;
+	}
+}
+
 /** Fetch the latest version from npm for a given package + dist-tag. */
 async function fetchLatestVersion(pkg: string, distTag: string): Promise<string | null> {
 	try {
@@ -153,7 +210,35 @@ async function fetchLatestVersion(pkg: string, distTag: string): Promise<string
 /** Reinstall a stale tool to the latest version. */
 async function reinstallTool(tool: SingletonTool, latest: string): Promise<boolean> {
 	const log = getAppLogger();
-	const vs = tool.version_source!;
+	const vs = tool.version_source;
+	if (!vs) return false;
+
+	if (vs.type === "github_release") {
+		// A GitHub-released binary is NOT installed by a package manager, so there
+		// is no "reinstall" verb to call — it would have to be downloaded, verified,
+		// made executable and swapped atomically over a file that may be RUNNING.
+		// That is a real install path with real failure modes (partial download,
+		// wrong architecture, replacing a binary mid-execution), and doing it badly
+		// is worse than not doing it: a half-written CLI is a broken CLI.
+		//
+		// So this reports the drift and stops. Detection is live from today; the
+		// automated swap is a separate, deliberate change. Reporting a version the
+		// watcher cannot actually install is honest — silently claiming currency
+		// would not be.
+		log.warn(
+			`[singleton-tools-currency] ${tool.name}: STALE, latest ${latest} from ${vs.repo}. Automated github_release install is not implemented — update it manually.`,
+		);
+		recordEvent({
+			kind: "singleton-tools.currency.tick",
+			payload: {
+				tool: tool.name,
+				latest,
+				status: "stale-manual-update-required",
+				repo: vs.repo,
+			},
+		});
+		return false;
+	}
 
 	if (tool.kind === "js" && tool.install_dir) {
 		// JS tool: bun add in the install_dir
@@ -212,8 +297,21 @@ async function singletonToolsCurrencyWatch(_ctx: { config: ScheduledJobConfig })
 
 	for (const tool of config.tools) {
 		const vs = tool.version_source;
-		if (!vs || vs.type !== "npm_package") {
-			// No version_source declared — skip (the tool is not yet inside the mechanism)
+		if (!vs) {
+			// A tool with no version_source is NOT tracked, and that must be loud.
+			// This previously `continue`d silently as "not yet inside the mechanism",
+			// which is how a gap becomes permanent: nothing distinguishes a tool
+			// nobody has declared from one that is up to date, so the watcher reports
+			// a clean tick while the tool rots. That is the exact shape of
+			// `a-component-may-not-report-a-state-it-has-not-verified` — the run
+			// advertises coverage it never performed.
+			log.warn(
+				`[singleton-tools-currency] ${tool.name}: NO version_source — not tracked, cannot be kept current. Add one to config/scala-singleton-tools.`,
+			);
+			recordEvent({
+				kind: "singleton-tools.currency.tick",
+				payload: { tool: tool.name, status: "no-version-source" },
+			});
 			continue;
 		}
 
@@ -236,7 +334,12 @@ async function singletonToolsCurrencyWatch(_ctx: { config: ScheduledJobConfig })
 			continue;
 		}
 
-		const latest = await fetchLatestVersion(vs.name, vs.dist_tag);
+		// Branch on the discriminant, never on a field's presence — an unhandled
+		// variant is a compile error here rather than a silent fall-through to npm.
+		const latest =
+			vs.type === "npm_package"
+				? await fetchLatestVersion(vs.name, vs.dist_tag)
+				: await fetchLatestGithubRelease(vs.repo);
 		if (!latest) {
 			log.warn(`[singleton-tools-currency] ${tool.name}: cannot fetch latest — skip`);
 			recordEvent({

package/src/handlers/sweep-host-cache.test.ts

@@ -0,0 +1,133 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Unit tests for the `retention_dirs` helpers (`expandGlob`, `checkDirStale`) —
+ * the whole-directory prune that bounds Rust `target/` waste. The file-by-mtime
+ * `retention` path is unchanged; these cover ONLY the new build-cache model:
+ * (1) glob expansion reaches every repo's target dir; (2) an actively-built dir
+ * is kept (short-circuits on a fresh file); (3) an abandoned dir is reported
+ * stale with its full size. Lives next to the handler per co-located-test rule.
+ */
+import { describe, expect, test, beforeEach, afterEach } from "bun:test";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, utimesSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { expandGlob, checkDirStale, parseRootDiskPct } from "./sweep-host-cache.ts";
+
+const DAY = 86_400_000;
+const now = Date.now();
+const daysAgo = (n: number) => new Date(now - n * DAY);
+const touch = (p: string, t: Date) => utimesSync(p, t, t);
+
+let root: string;
+beforeEach(() => {
+	root = mkdtempSync(join(tmpdir(), "sweep-"));
+});
+afterEach(() => {
+	rmSync(root, { recursive: true, force: true });
+});
+
+describe("expandGlob", () => {
+	test("expands a single-segment wildcard to concrete dirs", () => {
+		mkdirSync(join(root, "scala-rust", "target"), { recursive: true });
+		mkdirSync(join(root, "scala-os", "target"), { recursive: true });
+		mkdirSync(join(root, "scala-os", "src"), { recursive: true });
+		const matches = expandGlob(`${root}/*/target`).sort();
+		expect(matches).toEqual(
+			[join(root, "scala-os", "target"), join(root, "scala-rust", "target")].sort(),
+		);
+	});
+	test("literal segment matches only itself", () => {
+		mkdirSync(join(root, "scala-rust", "target"), { recursive: true });
+		mkdirSync(join(root, "other", "target"), { recursive: true });
+		const matches = expandGlob(`${root}/scala-rust/target`);
+		expect(matches).toEqual([join(root, "scala-rust", "target")]);
+	});
+	test("no matches when the wildcard segment has no children", () => {
+		const matches = expandGlob(`${root}/does-not-exist/*/target`);
+		expect(matches).toEqual([]);
+	});
+});
+
+describe("checkDirStale", () => {
+	test("stale dir: all files older than cutoff → stale + full size", async () => {
+		const dir = join(root, "target");
+		mkdirSync(join(dir, "debug", "deps"), { recursive: true });
+		writeFileSync(join(dir, "debug", "deps", "a.o"), "x".repeat(40));
+		writeFileSync(join(dir, "debug", "deps", "b.o"), "y".repeat(60));
+		touch(join(dir, "debug", "deps", "a.o"), daysAgo(40));
+		touch(join(dir, "debug", "deps", "b.o"), daysAgo(35));
+		const res = await checkDirStale(dir, now - 30 * DAY);
+		expect(res.stale).toBe(true);
+		expect(res.fileCount).toBe(2);
+		expect(res.bytes).toBe(100);
+	});
+	test("active dir: a file newer than cutoff → not stale (short-circuit)", async () => {
+		const dir = join(root, "target");
+		mkdirSync(join(dir, "debug"), { recursive: true });
+		writeFileSync(join(dir, "debug", "old.o"), "x".repeat(40));
+		touch(join(dir, "debug", "old.o"), daysAgo(40));
+		writeFileSync(join(dir, "debug", "fresh.o"), "y".repeat(60));
+		touch(join(dir, "debug", "fresh.o"), daysAgo(1));
+		const res = await checkDirStale(dir, now - 30 * DAY);
+		expect(res.stale).toBe(false);
+	});
+	test("empty dir → stale with zero bytes", async () => {
+		const dir = join(root, "target");
+		mkdirSync(dir, { recursive: true });
+		const res = await checkDirStale(dir, now - 30 * DAY);
+		expect(res.stale).toBe(true);
+		expect(res.bytes).toBe(0);
+		expect(res.fileCount).toBe(0);
+	});
+});
+
+describe("parseRootDiskPct", () => {
+	test("extracts root-fs Use% from df --output=pcent,target output", () => {
+		const df =
+			"Use% Mounted on\n" +
+			"  97% /\n" +
+			"  45% /home\n";
+		expect(parseRootDiskPct(df)).toBe(97);
+	});
+	test("picks the root mount (/) over nested mounts", () => {
+		const df =
+			"Use% Mounted on\n" +
+			"  10% /proc/x\n" +
+			"  76% /\n";
+		expect(parseRootDiskPct(df)).toBe(76);
+	});
+	test("returns null when no root-mount line present", () => {
+		const df = "Use% Mounted on\n  40% /mnt/other\n";
+		expect(parseRootDiskPct(df)).toBeNull();
+	});
+	test("returns null on empty / malformed output", () => {
+		expect(parseRootDiskPct("")).toBeNull();
+		expect(parseRootDiskPct("Use% Mounted on")).toBeNull();
+	});
+});
+
+describe("disk-threshold early-warning regression lock", () => {
+	const { readFileSync } = require("node:fs");
+	// Source-shape lock (same pattern as singleton-tools-currency-watch.test.ts):
+	// the df-check that rides this periodic sweep was once removed in favour of an
+	// in-process interval watchdog — the wrong architecture (interval watchdogs
+	// are forbidden; observability is event-driven). This asserts the corrected
+	// shape survives: the sweep handler MUST carry the event-driven host.disk.high
+	// emission (logger.warn -> GlitchTip) + the pure parseRootDiskPct helper that
+	// backs it. Removing either fails this test. The asserted surface is the
+	// disk early-warning cell of host-resources-have-complete-monitoring.
+	const src = readFileSync(import.meta.dir + "/sweep-host-cache.ts", "utf-8");
+	test("handler emits the host.disk.high event (event-driven, not an interval)", () => {
+		expect(src).toContain('log.warn("host.disk.high"');
+		expect(src).toContain('kind: "host.disk.high"');
+	});
+	test("handler reads df via the sanctioned spawn (no in-process poller)", () => {
+		expect(src).toContain('command: ["df", "--output=pcent,target"]');
+	});
+	test("threshold parse is the exported pure helper", () => {
+		expect(src).toContain("export function parseRootDiskPct");
+	});
+});