gentle-pi 4.2.0 → 4.4.0

package/tests/odd-routing-contract.test.ts

@@ -10,7 +10,9 @@ const read = (path: string) => readFileSync(join(import.meta.dirname, "..", path
 const core = read("assets/orchestrator.md");
 const delegation = readDelegationDetail();
 const memory = read("assets/orchestrator-memory.md");
-const wrapper = read("extensions/gentle-ai.ts");
+// The harness as rendered by extensions/gentle-ai.ts, including the ODD steps
+// it takes from the mirrored provider bundle's routing/pi.md.
+const wrapper = __testing.buildGentlePrompt("gentleman");
 
 function containsAll(text: string, clauses: readonly string[]): void {
 	for (const clause of clauses) assert.ok(text.includes(clause), `missing contract: ${clause}`);
@@ -19,10 +21,17 @@ function containsAll(text: string, clauses: readonly string[]): void {
 test("organic entry stays read-only without authorization and loads detail before work", () => {
 	containsAll(core, [
 		"large tasks get ODD tracking and workers only by the Writer rule, else inline",
-		"ODD (Default Workflow, harness section above) is mandatory on every request",
 		"orchestrator-delegation.md",
 		"orchestrator-memory.md",
 	]);
+	// S11 T3: deduplicated. The core's "ODD (Default Workflow, harness section
+	// above) is mandatory on every request" pointer restated the harness; the
+	// mandatory workflow and its detail pointers are stated once in the harness.
+	containsAll(wrapper, [
+		"Default workflow: Organic Driven Development (MANDATORY)",
+		"Every request enters it",
+		"Detail for steps 3–7: `orchestrator-delegation.md` and `orchestrator-memory.md`.",
+	]);
 	containsAll(delegation, [
 		"Investigation, explanation, review, comparison, and proposal-only requests remain read-only",
 		"without a task or storage permission prompt",
@@ -108,15 +117,45 @@ test("assumption challenge and task checks do not activate or duplicate native r
 	]);
 });
 
-test("ODD closes each task with a work-unit commit and reviews the commit or PR slice", () => {
+// S14: commit per reviewable slice. The exact canon sentence for ODD step 6,
+// identical in gentle-ai routing.go and this harness.
+const S14_COMMIT_SENTENCE =
+	"Commit work units in reviewable slices of about 400 authored changed lines on the feature branch (branch first when on the default branch), with tests and docs alongside the behavior and a Conventional Commit message; a unit whose Risk line names a high-risk item gets its own commit so native review can take it alone, and the last slice closes the feature. Record the commit that holds each task in the feature document as evidence.";
+const PER_TASK_COMMIT_SENTENCE =
+	"Every tracked task closes with at least one work-unit commit on the feature branch, branch first when on the default branch, with tests and docs alongside the behavior, using a Conventional Commit message; record the commit identity in the feature document as evidence.";
+
+test("S14: the rendered parent prompt commits per reviewable slice, not per task", () => {
+	for (const persona of ["gentleman", "neutral"] as const) {
+		const prompt = __testing.buildGentlePrompt(persona);
+		assert.equal(prompt.split(S14_COMMIT_SENTENCE).length - 1, 1, `[${persona}] the parent prompt must carry the S14 sentence once`);
+		assert.ok(!prompt.includes(PER_TASK_COMMIT_SENTENCE), `[${persona}] the parent prompt keeps the per-task commit sentence`);
+		assert.ok(
+			prompt.includes(`${S14_COMMIT_SENTENCE} Work-unit commits on the feature branch are part of authorized large ODD implementation;`),
+			`[${persona}] step 6 must keep its authorization sentence right after the S14 sentence`,
+		);
+	}
+});
+
+// S14: commit per reviewable slice. Step 6 commits slices of about 400 authored
+// changed lines (a high-risk unit alone) instead of closing every task with a commit.
+test("ODD commits work units in reviewable slices and reviews the commit or PR slice", () => {
 	containsAll(wrapper, [
-		"Every tracked task closes with at least one work-unit commit on the feature branch, branch first when on the default branch",
-		"with tests and docs alongside the behavior, using a Conventional Commit message",
-		"record the commit identity in the feature document as evidence",
+		"Commit work units in reviewable slices of about 400 authored changed lines on the feature branch (branch first when on the default branch)",
+		"with tests and docs alongside the behavior and a Conventional Commit message",
+		"a unit whose Risk line names a high-risk item gets its own commit so native review can take it alone",
+		"Record the commit that holds each task in the feature document as evidence",
 		"Work-unit commits on the feature branch are part of authorized large ODD implementation; push, pull request creation, and merge remain the user's decisions",
 		"The native review candidate is a work-unit commit or a PR slice, never a TODO checkbox and never the accumulated feature branch",
-		"close each tracked task with a work-unit commit",
 	]);
+	// S11 T3: deduplicated. The harness principle that re-listed the ODD steps
+	// ("close each tracked task with a work-unit commit") is gone; step 6 above is
+	// the single statement. Core Safety allows exactly those commits and no others.
+	assert.ok(!wrapper.includes("close each tracked task with a work-unit commit"), "the ODD steps are re-listed outside step 6");
+	assert.ok(
+		core.includes("- Never commit unless the user explicitly asks, except the work-unit commits authorized large ODD implementation makes on its feature branch (ODD step 6)."),
+		"core Safety must allow only the ODD step 6 work-unit commits without an explicit ask",
+	);
+	assert.ok(!core.includes("- Never commit unless the user explicitly asks."), "core Safety contradicts ODD step 6 work-unit commits");
 	containsAll(delegation, [
 		'after each work-unit commit, assess it with that same call and `{"baseRef":"<last reviewed boundary>","committedOnly":true}`',
 		"Passive/low: silent structural checks, no reviewer or consent ceremony, and the boundary advances",
@@ -124,7 +163,8 @@ test("ODD closes each task with a work-unit commit and reviews the commit or PR
 		"Medium: defer to the PR slice",
 		"bounded by the delivery budget of about 400 authored changed lines",
 		"The first boundary is the branch point, and every reviewed boundary becomes the next base",
-		"Record per task the assessed tier and outcome: granted, declined, passive, deferred to slice, or unavailable",
+		// S14: commit per reviewable slice; one commit may hold several tasks, so outcomes are recorded per commit.
+		"Record per commit the assessed tier and outcome: granted, declined, passive, deferred to slice, or unavailable",
 		"Delivery follows work units",
 		"forecast authored changed lines (additions plus deletions, generated files excluded) from the task list",
 		"keep a running count from work-unit commits",
@@ -137,18 +177,28 @@ test("ODD closes each task with a work-unit commit and reviews the commit or PR
 		"never hardcode their paths",
 		"The delivery budget below reads the accumulated branch, not this per-task heuristic",
 	]);
+	assert.ok(!wrapper.includes("Every tracked task closes with at least one work-unit commit"), "step 6 keeps the per-task commit rule");
 	const docs = read("docs/readme-reference.md");
 	containsAll(docs, [
-		"Every task closes with at least one work-unit commit on the feature branch (branch first when on the default branch)",
-		"the feature document records the commit identity as evidence",
+		"Commit work units in reviewable slices of about 400 authored changed lines on the feature branch (branch first when on the default branch)",
+		"a unit whose Risk line names a high-risk item gets its own commit so native review can take it alone",
+		"the feature document records the commit that holds each task as evidence",
 		"The native review candidate is a work-unit commit or a PR slice, never a TODO checkbox and never the accumulated feature branch",
 		"**Delivery:**",
-		"Close task with a work-unit commit",
+		"Commit at a slice boundary; a high-risk unit alone",
 		"RDD enabled at work-unit commit boundary",
 		"Running authored lines over 400",
 		"Apply selected delivery strategy",
 		"Single PR; no chain artifacts",
 	]);
+	assert.ok(!docs.includes("Every task closes with at least one work-unit commit"), "docs keep the per-task commit rule");
+	const skill = read("skills/work-unit-commits/SKILL.md");
+	containsAll(skill, [
+		"Committing ODD work in reviewable slices of about 400 authored changed lines.",
+		"ODD commits work units in reviewable slices of about 400 authored changed lines, not one commit per task:",
+		"A unit whose Risk line names a high-risk item gets its own commit, so native review takes it alone.",
+	]);
+	assert.ok(!skill.includes("Every ODD task closes with at least one work-unit commit"), "the skill keeps the per-task commit rule");
 });
 
 test("delivery instructions and docs preserve localized ordered outcomes and override chaining", () => {
@@ -267,13 +317,17 @@ test("ODD defaults to applicable test-first without chat or TUI activation", ()
 	const verify = read("assets/agents/gentle-ai-verify.md");
 	const support = read("assets/support/strict-tdd.md") + read("assets/support/strict-tdd-verify.md");
 	const skill = read("skills/gentle-ai/SKILL.md");
-	for (const text of [core, delegation, worker, verify, support, skill, wrapper]) {
+	// S11 T3: deduplicated. The core sits after the harness in the same system
+	// prompt; its pointer sentence restated the harness test-first policy, so the
+	// rendered parent prompt (harness + core) now carries that policy exactly
+	// once, from the harness, instead of the core carrying its own copy.
+	const rendered = __testing.buildGentlePrompt("gentleman");
+	for (const text of [rendered, delegation, worker, verify, support, skill, wrapper]) {
 		containsAll(text, ["applicable", "RED", "GREEN"]);
 		assert.doesNotMatch(text, /(?:configured TDD mode|Strict TDD Mode is enabled|explicit user choice|test presence does not enable it|tests existing does not activate it)/i);
 	}
-	// The core sits after the harness in the same system prompt, so it points at
-	// the harness test-first policy instead of restating it (gentle-shell#1494).
-	assert.ok(core.includes("the harness's applicable test-first policy"), "core must point at the harness test-first policy");
+	assert.equal(rendered.split("use test-first by default").length - 1, 1, "the parent prompt states the test-first policy once");
+	assert.ok(!core.includes("GREEN"), "core restates the harness test-first policy");
 	for (const [actor, text] of [["delegation", delegation], ["extension", wrapper], ["skill", skill]] as const) {
 		assert.match(text, /behavior changes with applicable runnable deterministic tests and a clear expected outcome/i, `${actor} must require applicability, not test presence`);
 		assert.match(text, /passive documentation/i, `${actor} must handle passive docs`);
@@ -287,9 +341,12 @@ test("ODD defaults to applicable test-first without chat or TUI activation", ()
 	assert.doesNotMatch(core + delegation + worker + support + skill + wrapper, /If tests exist, use strict TDD/i);
 });
 
-test("mandatory delegation triggers are behavioral in the lazy canonical port and the always-on ODD step", () => {
+// S9 canon change (gentle-ai 87a3b2eb): "These triggers are mandatory, not
+// advisory." read as a default to delegate (L8). A trigger is mandatory only
+// once its condition truly holds; none holds by default, inline when in doubt.
+test("delegation triggers are behavioral in the lazy canonical port and the always-on ODD step", () => {
 	for (const clause of [
-		"These triggers are mandatory, not advisory.",
+		"Each trigger holds only when its condition truly holds, and only then is it mandatory, not advisory; no trigger holds by default, and when in doubt work inline.",
 		"stop and delegate through the runtime's subagent mechanism before continuing",
 		"executing past a fired trigger inline is a routing defect even if the work succeeds",
 		"**Mapping trigger",
@@ -302,12 +359,15 @@ test("mandatory delegation triggers are behavioral in the lazy canonical port an
 		"so skipped delegation is observable instead of silent",
 		"These triggers only choose between direct inline and delegated direct inside ODD",
 	]) {
-		assert.ok(delegation.includes(clause), `lazy canonical port is missing mandatory delegation clause: ${clause}`);
+		assert.ok(delegation.includes(clause), `lazy canonical port is missing delegation clause: ${clause}`);
 	}
+	assert.ok(!delegation.includes("These triggers are mandatory, not advisory"), "the lazy port must not read the triggers as mandatory by default");
 	assert.ok(
-		wrapper.includes("honoring its mandatory delegation triggers"),
-		"the always-on ODD step 6 must honor its mandatory delegation triggers",
+		wrapper.includes("honoring its delegation triggers when their conditions truly hold"),
+		"the always-on ODD step 6 must honor its delegation triggers only when their conditions truly hold",
 	);
+	assert.ok(wrapper.includes("No trigger holds by default and, when in doubt, work inline"), "the always-on ODD step 6 must default to inline");
+	assert.ok(!wrapper.includes("These triggers are mandatory, not advisory"), "the always-on ODD step 6 must not read the triggers as mandatory by default");
 	assert.ok(
 		wrapper.includes("executing past a fired trigger inline is a routing defect"),
 		"the always-on ODD protocol must state that skipping a fired trigger is a routing defect",
@@ -363,7 +423,6 @@ test("evidence-budget numbers agree across routing surfaces and retired triggers
 			"~10k tokens",
 			"at most ~2k tokens",
 			"`path:line`",
-			"~150k tokens",
 			"Context backstop",
 		]);
 		assert.doesNotMatch(text, /4-file rule|20 tool calls|5 exploratory (?:file )?reads/, `${path} keeps a retired trigger`);
@@ -373,6 +432,20 @@ test("evidence-budget numbers agree across routing surfaces and retired triggers
 	}
 });
 
+// Harness roadmap R1: the backstop is a measured runtime signal (min(absolute cap, fraction x window)), so the
+// prompt modules stop stating a fixed token count and only a unit needing several steps is worth delegating.
+test("context backstop prompt text defers to the runtime signal instead of a fixed token count", () => {
+	const reference = read("assets/orchestrator-delegation-reference.md");
+	for (const [path, text] of Object.entries({ "assets/orchestrator.md": core, "assets/orchestrator-delegation.md": read("assets/orchestrator-delegation.md"), "assets/orchestrator-delegation-reference.md": reference })) {
+		assert.doesNotMatch(text, /~?150k tokens/, `${path} still states a fixed backstop`);
+		assert.match(text, /\*\*Context backstop(?::\*\*|\*\*:?)[^\n]*when the runtime signals/, `${path} must defer to the runtime signal`);
+		assert.ok(text.includes("several steps"), `${path} must say only a unit needing several steps is delegated`);
+	}
+	const docs = read("docs/readme-reference.md");
+	containsAll(docs, ["GENTLE_PI_CONTEXT_BACKSTOP_TOKENS", "GENTLE_PI_CONTEXT_BACKSTOP_FRACTION", "min(", "`getContextUsage()`", "re-armed"]);
+	assert.doesNotMatch(docs, /~150k tokens|150,000-token context backstop/, "docs still describe the fixed backstop");
+});
+
 test("ODD protocol is always-on in the rendered system prompt and runs by default", () => {
 	const orderedClauses = [
 		"Default workflow: Organic Driven Development (MANDATORY)",
@@ -406,15 +479,27 @@ test("ODD protocol is always-on in the rendered system prompt and runs by defaul
 		}
 	}
 
-	assert.ok(
-		wrapper.includes("Organic Driven Development (ODD) is the predefined workflow for every request"),
-		"missing contract: extensions/gentle-ai.ts harness principle",
-	);
-	// The parent owns the injected identity; its migration is outside this suite's edit surface.
-	assert.ok(
-		core.includes("ODD (Default Workflow, harness section above) is mandatory on every request"),
-		"missing contract: assets/orchestrator.md pointer sentence",
-	);
+	// S11 T3: deduplicated. The harness principle and the core pointer sentence
+	// both restated the mandatory workflow; the steps' own header (asserted in
+	// order above as "predefined workflow of this orchestrator") is the one statement.
+	for (const persona of ["gentleman", "neutral"] as const) {
+		const prompt = __testing.buildGentlePrompt(persona);
+		assert.equal(prompt.split("is the predefined workflow").length - 1, 1, `[${persona}] the ODD workflow is declared more than once`);
+		assert.ok(!prompt.includes("ODD (Default Workflow, harness section above)"), `[${persona}] the core restates the ODD workflow`);
+	}
 	containsAll(core, ["orchestrator-delegation.md", "orchestrator-memory.md"]);
 	assert.doesNotMatch(core + delegation + memory, /SDD|sdd-|OpenSpec|openspec/i);
 });
+
+// S14: commit per reviewable slice. Mirrors gentle-ai 06ad2776: a high-risk unit that follows pending medium commits
+// closes the open slice first, so native review takes the high-risk commit alone; outcomes are recorded per commit,
+// since one commit may hold several tasks.
+test("S14: RDD tracking closes the open slice before a high-risk commit and records outcomes per commit", () => {
+	const tracking = readFileSync(join(import.meta.dirname, "..", "assets", "orchestrator-tracking.md"), "utf8");
+	assert.ok(
+		tracking.includes("When a high-risk unit follows pending medium commits still under the slice budget, close the open slice first, assessing and reviewing it as the slice, so the high-risk commit is then reviewed alone against the new boundary."),
+		"tracking must close the open slice before a high-risk commit",
+	);
+	assert.ok(tracking.includes("Record per commit the assessed tier and outcome"), "tracking must record outcomes per commit");
+	assert.ok(!tracking.includes("Record per task the assessed tier and outcome"), "tracking must not record outcomes per task");
+});

package/tests/orchestrator-budget.test.ts

@@ -31,12 +31,18 @@ const REPO_ROOT = join(import.meta.dirname, "..");
 const REAL_ASSETS_DIR = join(REPO_ROOT, "assets");
 const FIXTURE_PATH = join(import.meta.dirname, "fixtures", "orchestrator.pre-diet.md");
 // gentle-shell#1731 T10 (user decision): 8,192 -> 8,400 B for the narrowed high-risk items 1 and 3.
-const BUDGET_BYTES = 8400;
+// Verification by named risk (escalate-only rule 3) and the writer-rule fix (triggers hold only when
+// their condition holds; a unit is independent behavior over a size floor), user decision 2026-10-14: 8,400 -> 9,100 B.
+// Weak-model economy (small path reads one batch with no todo; item 1 excludes rebuildable dev/test data), measured in
+// gentle-shell-bench 1321c60 (DeepSeek -24-30% time on x2/x5, -70% on a dev-database rename; Sol unchanged), user decision
+// 2026-10-22: 9,100 -> 9,250 B.
+const BUDGET_BYTES = 9250;
 const MIN_CONTROLLED_LONG_ASSETS_ROOT_CHARS = 93;
 
 const LAZY_ASSET_NAMES = [
 	"orchestrator.md",
 	"orchestrator-delegation.md",
+	"orchestrator-delegation-reference.md",
 	"orchestrator-memory.md",
 	"orchestrator-skills.md",
 ] as const;
@@ -123,7 +129,7 @@ function measureOrchestratorPromptBytes(assetsDir: string): number {
 // measuring a shorter render again.
 const RDD_WORST_CASE_LINE = "Receipt-driven development: unknown (native status unavailable)";
 
-test("getOrchestratorPrompt return value stays within the canonical 8,400 B budget at a short assets root", () => {
+test("getOrchestratorPrompt return value stays within the canonical 9,250 B budget at a short assets root", () => {
 	const rendered = __testing.renderOrchestratorPrompt(representativeProductionAssetsDir);
 	assert.ok(
 		rendered.includes(RDD_WORST_CASE_LINE),
@@ -303,6 +309,10 @@ const SUPERSEDED_LIFECYCLE_REVIEW_LINES = new Set([
 	154,
 	160,
 	166,
+	// 280: S11 T3 made the Safety commit line consistent with ODD step 6: it now
+	// excepts the work-unit commits of authorized large ODD implementation
+	// (asserted verbatim in tests/odd-routing-contract.test.ts).
+	280,
 	// 282: gentle-shell#1731 T4 relaxed the single-writer Safety line to disjoint
 	// Allowed edit surfaces (runtime-enforced) or isolated worktrees.
 	282,
@@ -363,10 +373,12 @@ test("core-alone: load-bearing direct-delegation tokens remain without lazy unio
 
 test("lazy coordination detail retains subject guidance without inflating the core", () => {
 	const core = readRealAsset("orchestrator.md");
-	const detail = readRealAsset("orchestrator-delegation.md");
+	// S11 T2: the card binds on delegation; the session subject rules are reference material.
+	const card = readRealAsset("orchestrator-delegation.md");
+	const detail = readRealAsset("orchestrator-delegation-reference.md");
 	assert.match(core, /Bind this to the parent Pi session only/);
 	assert.match(core, /orchestrator-delegation\.md/);
-	assert.match(detail, /on delegation or routing triggers/);
+	assert.match(card, /on delegation or routing triggers/);
 	assert.match(detail, /Once a meaningful task subject is clear, before delegation or cross-session coordination, call `orchestrator_session_id`/);
 	assert.match(detail, /short, non-sensitive `subject`/);
 	assert.match(detail, /Batch with setup if possible; no extra model call/);
@@ -384,14 +396,14 @@ test("core-alone: dynamic Gentle AI ownership replaces package lifecycle instruc
 });
 
 test("lazy delegation detail has no native RDD controller markers", () => {
-	const delegation = readRealAsset("orchestrator-delegation.md");
+	const delegation = `${readRealAsset("orchestrator-delegation.md")}\n${readRealAsset("orchestrator-delegation-reference.md")}`;
 	for (const marker of ["next_transition", "review.capture-result", "reconcile-terminal-mirrors"]) {
 		assert.ok(!delegation.includes(marker), `stale RDD marker retained: ${marker}`);
 	}
 });
 
 test("live orchestrator assets remove the stale strong-gate retry contract", () => {
-	const content = `${readRealAsset("orchestrator.md")}\n${readRealAsset("orchestrator-delegation.md")}`;
+	const content = `${readRealAsset("orchestrator.md")}\n${readRealAsset("orchestrator-delegation.md")}\n${readRealAsset("orchestrator-delegation-reference.md")}`;
 	assert.doesNotMatch(content, /strong gate/i);
 	assert.doesNotMatch(content, /extension blocks.*gh pr create/i);
 	assert.doesNotMatch(content, /before the user retries the PR command/i);
@@ -464,14 +476,16 @@ test("every compressed lazy-file pointer in the core still names the material it
 	// byte budget -- each must keep naming what is over there, not collapse
 	// to an opaque "Detail: `file.md`.".
 	const namedPointers: ReadonlyArray<{ file: string; mustName: readonly string[] }> = [
+		// S11 T2: this reference material moved out of the delegation card.
 		{
-			file: "orchestrator-delegation.md",
+			file: "orchestrator-delegation-reference.md",
 			mustName: ["Per-action table", "Work Routing Ladder", "Canonical Workflows"],
 		},
 		// gentle-shell#1494 per-mechanism modules.
 		{ file: "orchestrator-prompts.md", mustName: ["blocking-prompt relays", "provider defects"] },
 		{ file: "orchestrator-tracking.md", mustName: ["Track", "feature document"] },
-		{ file: "orchestrator-verification.md", mustName: ["Verification rule", "high risk"] },
+		// Verification by named risk: rule 3 names the escalated high-risk item.
+		{ file: "orchestrator-verification.md", mustName: ["Verification rule", "high-risk item"] },
 		{ file: "orchestrator-writer.md", mustName: ["Writer rule", "large task"] },
 		{
 			file: "orchestrator-memory.md",

package/tests/orchestrator-discovery.test.ts

@@ -57,6 +57,35 @@ test("published headers retain the frozen legacy schema-1 contract after metadat
 	assert.equal(listPresence(profile).entries.length, 1);
 	assert.equal(discoverOrchestrators(profile, [peer])[0].freshness, "unknown");
 });
+test("a live peer that predates discovery publication keeps its legacy header label (#2305)", (t) => {
+	const profile = fixture(t);
+	// A long-lived peer started before discovery publication shipped heartbeats
+	// the schema-1 header only and never writes a discovery sidecar.
+	const publisher = PresencePublisher.start({ profile, sessionId: "peer", label: "gentle-shell", activity: [] });
+	t.after(() => publisher.dispose());
+	const [candidate] = discoverOrchestrators(profile, [peer]);
+	assert.equal(candidate.freshness, "unknown");
+	assert.equal(candidate.legacyLabel, "gentle-shell");
+	assert.equal(candidate.workspace, undefined);
+	assert.equal(candidate.publication, undefined);
+	// An old heartbeat is not a live legacy peer.
+	assert.equal(discoverOrchestrators(profile, [peer], Date.now() + 20_000)[0].legacyLabel, undefined);
+});
+test("a present but invalid or foreign discovery sidecar never yields a legacy label", (t) => {
+	const profile = fixture(t);
+	const publisher = PresencePublisher.start({ profile, sessionId: "peer", label: "gentle-shell", activity: [] });
+	t.after(() => publisher.dispose());
+	publisher.updateDiscovery(peer, { workspace: "/repo", tasks: [] });
+	// Metadata bound to another activation fails closed, without a label.
+	const foreign = discoverOrchestrators(profile, [{ ...peer, endpoint: "/socket/replacement" }])[0];
+	assert.equal(foreign.freshness, "unknown");
+	assert.equal(foreign.legacyLabel, undefined);
+	const sidecar = join(profile, "gentle-agents", "presence", `${publisher.target.sessionHash}.${publisher.target.incarnation}.discovery.json`);
+	writeFileSync(sidecar, "{broken");
+	const broken = discoverOrchestrators(profile, [peer])[0];
+	assert.equal(broken.freshness, "unknown");
+	assert.equal(broken.legacyLabel, undefined);
+});
 test("joins activation-bound metadata without exporting prompts or thread output", (t) => {
 	const profile = fixture(t);
 	const publisher = PresencePublisher.start({ profile, sessionId: peer.sessionId, label: "Review auth", activity: [] });

package/tests/orchestrator-presence.test.ts

@@ -2,8 +2,10 @@ import assert from "node:assert/strict";
 import { fork } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
 import * as fs from "node:fs";
+import fsSync from "node:fs";
+import { syncBuiltinESMExports } from "node:module";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import test from "node:test";
 import { historyDir, saveTask } from "../lib/agents-history.ts";
 import { TASK_STATUS, TaskStore, type TaskRecord } from "../lib/agents-protocol.ts";
@@ -20,7 +22,7 @@ function fixture(t: test.TestContext) {
 		if (fs.existsSync(root) && !fs.lstatSync(root).isSymbolicLink()) {
 			for (const name of fs.readdirSync(root)) {
 				const path = join(root, name);
-				if (["tasks", "presence"].includes(name) && fs.lstatSync(path).isDirectory()) {
+				if (["tasks", "presence", "catalog"].includes(name) && fs.lstatSync(path).isDirectory()) {
 					for (const file of fs.readdirSync(path)) fs.unlinkSync(join(path, file));
 					fs.rmdirSync(path);
 				} else fs.unlinkSync(path);
@@ -56,6 +58,102 @@ test("heartbeat refreshes a bounded canonical label and stops an invalid source"
 	assert.deepEqual(listPresence(profile).entries, []);
 });
 
+test("warm-cache flush performs no synchronous ancestor validation", (t) => {
+	t.mock.timers.enable({ apis: ["Date", "setInterval", "setTimeout"], now: 100_000 });
+	const profile = fixture(t);
+	const pub = publisher(t, profile);
+	const absolute = resolve(profile);
+	const ancestors = new Set<string>();
+	for (let path = absolute;; path = dirname(path)) {
+		ancestors.add(path);
+		if (dirname(path) === path) break;
+	}
+	ancestors.add(join(absolute, "gentle-agents"));
+	ancestors.add(join(absolute, "gentle-agents", "presence"));
+	const probes: string[] = [];
+	const originalLstat = fsSync.lstatSync;
+	const spy = t.mock.method(fsSync, "lstatSync", (path: Parameters<typeof fsSync.lstatSync>[0], ...args: unknown[]) => {
+		if (typeof path === "string" && ancestors.has(path)) probes.push(path);
+		return (originalLstat as (...args: unknown[]) => fs.Stats)(path, ...args);
+	});
+	syncBuiltinESMExports();
+	t.after(() => { spy.mock.restore(); syncBuiltinESMExports(); });
+	pub.update(rows("warm cache"));
+	t.mock.timers.tick(400);
+	assert.deepEqual(probes, [], "writes must consume the validated cache, not re-probe ancestors");
+	assert.equal(listPresence(profile).entries[0].generation, 2);
+});
+
+test("a vanished storage tree skips publication without crashing and revalidates asynchronously", async (t) => {
+	const profile = fixture(t);
+	let heartbeat: (() => void) | undefined;
+	const interval = globalThis.setInterval;
+	t.mock.method(globalThis, "setInterval", (callback: () => void, ms: number) => {
+		if (ms === 5000) heartbeat = callback;
+		return interval(callback, ms);
+	});
+	const pub = publisher(t, profile);
+	const root = join(profile, "gentle-agents", "presence");
+	for (const name of fs.readdirSync(root)) fs.unlinkSync(join(root, name));
+	fs.rmdirSync(root);
+	heartbeat!();
+	await new Promise((resolve) => setTimeout(resolve, 50));
+	assert.equal(pub.error, undefined, "a vanished tree skips writes instead of failing the publisher");
+	assert.deepEqual(listPresence(profile).entries, []);
+	fs.mkdirSync(root, { mode: 0o700 });
+	heartbeat!(); // cache is still cold: skip this tick while the heartbeat revalidates
+	await new Promise((resolve) => setTimeout(resolve, 50));
+	heartbeat!(); // warm cache again: publication resumes
+	assert.equal(listPresence(profile).entries.length, 1);
+	assert.equal(pub.error, undefined);
+});
+
+test("heartbeat path validations never overlap", async (t) => {
+	const profile = fixture(t);
+	let heartbeat: (() => void) | undefined;
+	const interval = globalThis.setInterval;
+	t.mock.method(globalThis, "setInterval", (callback: () => void, ms: number) => {
+		if (ms === 5000) heartbeat = callback;
+		return interval(callback, ms);
+	});
+	const pub = publisher(t, profile);
+	let chains = 0;
+	let release!: () => void;
+	const gate = new Promise<void>((done) => { release = done; });
+	const original = fs.promises.lstat;
+	const spy = t.mock.method(fs.promises, "lstat", async (path: Parameters<typeof fs.promises.lstat>[0], ...args: unknown[]) => {
+		if (String(path) === resolve(profile)) { chains++; await gate; }
+		return (original as (...args: unknown[]) => Promise<fs.Stats>).apply(fs.promises, [path, ...args]);
+	});
+	t.after(() => spy.mock.restore());
+	heartbeat!();
+	heartbeat!(); // while the first validation waits, this tick must not start another
+	release();
+	await new Promise((resolve) => setTimeout(resolve, 50));
+	assert.equal(chains, 1, "overlapping heartbeat validations must be skipped");
+	heartbeat!();
+	await new Promise((resolve) => setTimeout(resolve, 50));
+	assert.equal(chains, 2, "the next heartbeat validates again");
+	assert.equal(pub.error, undefined);
+});
+
+test("first publication lands immediately after start() with no heartbeat wait", (t) => {
+	const profile = fixture(t);
+	const pub = publisher(t, profile);
+	// The first updateDiscovery lands in the same tick: no heartbeat may be
+	// required for the first header, discovery, or catalog publication.
+	pub.updateDiscovery({ sessionId: "same session", endpoint: "/fixture/first.sock", createdAt: 1 },
+		{ workspace: "/repo", tasks: [{ id: "child", label: "Check auth", status: "waiting", cwd: "/repo-child" }] });
+	const header = listPresence(profile).entries[0];
+	assert.equal(header.label, "Workspace");
+	assert.equal(presence.readDiscovery(profile, header)?.workspace, "/repo");
+	assert.equal(presence.readDiscovery(profile, header)?.tasks[0].id, "child");
+	const catalog = JSON.parse(fs.readFileSync(
+		join(profile, "gentle-agents", "catalog", `${header.sessionHash}.${header.incarnation}.json`), "utf8"));
+	assert.equal(catalog.schema, 1);
+	assert.deepEqual(catalog.catalog.tasks.map((row: { id: string }) => row.id), ["child"]);
+});
+
 function rows(text = "full retained output") {
 	return [{ task: { id: "t", agent: "worker", label: "summary", status: "running", model: "model",
 		createdAt: 1000, startedAt: 1100, endedAt: null, lastActivityAt: 1200,

package/tests/orchestrator-rdd-ownership.test.ts

@@ -66,11 +66,13 @@ test("rendered parent prompt keeps the RDD boundary while omitting lifecycle mir
 	// the three renderable forms -- so this IS the worst-case render the core
 	// budget below must cover, not a smaller placeholder production later
 	// exceeds. gentle-shell#1731 T10 (user decision): budget 8,192 -> 8,400 B.
+	// Verification by named risk and the writer-rule fix: 8,400 -> 9,100 B; weak-model economy: 9,100 -> 9,250 B
+	// (the canonical budget in orchestrator-budget.test.ts).
 	assert.ok(
 		rendered.includes("Receipt-driven development: unknown (native status unavailable)"),
 		"the default render must include the worst-case RDD status line",
 	);
-	assert.ok(Buffer.byteLength(rendered, "utf8") <= 8400, "the rendered parent prompt must stay within the 8,400 B core budget");
+	assert.ok(Buffer.byteLength(rendered, "utf8") <= 9250, "the rendered parent prompt must stay within the 9,250 B core budget");
 });
 
 test("static prompts retain ODD and delegated-work guidance without SDD", () => {

package/tests/orchestrator-scope.test.ts

@@ -8,6 +8,20 @@ import { OrchestratorScopeCache, validRecordedScope } from "../lib/orchestrator-
 import { PresencePublisher, listPresence, readDiscovery } from "../lib/orchestrator-presence.ts";
 import { resolveSessionWorktree } from "../lib/session-worktree-registry.ts";
 
+test("cachedScope serves deferred publications from the snapshot without probing", () => {
+	let probes = 0;
+	const cache = new OrchestratorScopeCache(() => { probes++; return { root: "/repo", commonDir: "/clone" }; });
+	assert.equal(cache.cachedScope(), undefined, "nothing is cached before a projection");
+	const snapshot = cache.project("/repo", [], []);
+	assert.equal(probes, 1, "the event-time projection resolves eagerly");
+	assert.equal(cache.cachedScope(), snapshot);
+	assert.equal(cache.cachedScope(), snapshot, "repeated deferred reads never probe");
+	assert.equal(probes, 1);
+	cache.clear();
+	assert.equal(cache.cachedScope(), undefined, "a cleared cache publishes no stale scope");
+	assert.equal(probes, 1);
+});
+
 test("recorded host/owned child/registered scope correlates clones, isolates ambient Git and caches lifecycle", (t) => {
 	const base = realpathSync(mkdtempSync(join(tmpdir(), "orchestrator-scope-")));
 	t.after(() => rmSync(base, { recursive: true, force: true }));
@@ -59,6 +73,72 @@ test("recorded host/owned child/registered scope correlates clones, isolates amb
 	assert.equal(new OrchestratorScopeCache(() => ({ root: "/repo\nother", commonDir: "/clone" })).project(repo, [], []).host.root, null);
 });
 
+test("recency reorders preserve repository facts but retain caller order", () => {
+	const host = join(tmpdir(), "scope-host"), a = join(tmpdir(), "scope-a"), b = join(tmpdir(), "scope-b");
+	let calls = 0, now = 1;
+	const cache = new OrchestratorScopeCache(path => {
+		calls++;
+		if (path === b) throw new Error("unavailable");
+		return { root: path, commonDir: host };
+	}, () => now++);
+	const tasks = [{ id: "a", cwd: a }, { id: "b", cwd: b }];
+	const first = cache.project(host, tasks, [a, b]);
+	assert.equal(calls, 3);
+	const reordered = cache.project(host, [...tasks].reverse(), [b, a]);
+	assert.equal(calls, 3, "pure reorders must not probe Git, including cached unknowns");
+	assert.deepEqual(reordered.tasks, [...first.tasks].reverse());
+	assert.deepEqual(reordered.registered, [...first.registered].reverse());
+	assert.deepEqual(reordered.host, first.host);
+	assert.equal(reordered.tasks[0].repository.root, null);
+	assert.equal(validRecordedScope(reordered), true);
+	assert.strictEqual(cache.project(host, [...tasks].reverse(), [b, a]), reordered);
+
+	const added = cache.project(host, [...tasks, { id: "c", cwd: host }], [a, b]);
+	assert.equal(calls, 6, "membership changes refresh even existing facts");
+	assert.ok(added.host.resolvedAt > first.host.resolvedAt);
+	cache.project(host, tasks, [a, b]);
+	assert.equal(calls, 9, "removal refreshes facts");
+	cache.project(host, [{ id: "a", cwd: host }, tasks[1]], [a, b]);
+	assert.equal(calls, 12, "cwd changes refresh facts");
+	cache.project(host, [{ id: "a", cwd: host }, tasks[1]], [a]);
+	assert.equal(calls, 15, "registered membership changes refresh facts");
+	cache.clear();
+	cache.project(host, tasks, [a, b]);
+	assert.equal(calls, 18, "session replacement clears facts");
+});
+
+test("first-eight visibility evicts hidden facts and retains visible unknowns", () => {
+	const host = join(tmpdir(), "scope-visible-host");
+	const tasks = Array.from({ length: 9 }, (_, i) => ({ id: `t${i}`, cwd: join(tmpdir(), `scope-visible-task-${i}`) }));
+	const calls: string[] = [];
+	const cache = new OrchestratorScopeCache(path => {
+		calls.push(path);
+		if (path === tasks[0].cwd) throw new Error("unavailable");
+		return { root: path, commonDir: host };
+	});
+	const first = cache.project(host, tasks, []);
+	assert.deepEqual(calls, [host, ...tasks.slice(0, 8).map(t => t.cwd)]);
+	assert.equal(first.tasks[0].repository.root, null);
+	const unknown = first.tasks[0].repository;
+	const ninthVisible = [tasks[8], ...tasks.slice(0, 8)];
+	const expectedCalls = [...calls];
+	for (const [order, newlyVisible] of [[ninthVisible, tasks[8]], [tasks, tasks[7]], [ninthVisible, tasks[8]]] as const) {
+		const snapshot = cache.project(host, order, []);
+		expectedCalls.push(newlyVisible.cwd);
+		assert.deepEqual(calls, expectedCalls, "each visibility transition resolves only its evicted/newly visible path");
+		assert.deepEqual(snapshot.tasks.map(t => t.id), order.slice(0, 8).map(t => t.id));
+		assert.equal(snapshot.tasks.length, 8);
+		assert.equal(snapshot.omittedTasks, 1);
+		assert.equal(snapshot.complete, false);
+		assert.equal(validRecordedScope(snapshot), true);
+		assert.strictEqual(snapshot.tasks.find(t => t.id === "t0")!.repository, unknown, "visible unknown facts survive every reorder");
+		assert.strictEqual(cache.project(host, order, []), snapshot);
+		assert.deepEqual(calls, expectedCalls, "stable snapshots never resolve again");
+	}
+	assert.equal(calls.filter(path => path === tasks[8].cwd).length, 2, "ninth path is resolved again after eviction");
+	assert.equal(calls.filter(path => path === tasks[0].cwd).length, 1, "visible unknown is not retried");
+});
+
 test("literal recorded roots never alias Unicode separators to another real repository", (t) => {
 	const base = realpathSync(mkdtempSync(join(tmpdir(), "scope-literal-")));
 	t.after(() => rmSync(base, { recursive: true, force: true }));