gentle-pi 2.1.2 → 2.2.0

package/tests/native-review-parity-runtime.test.ts

@@ -89,6 +89,40 @@ interface ReviewGateResult {
 	context: ReviewGateContext;
 }
 
+// Every test in this file drives the real pinned binary through a full review
+// lifecycle, and gentle-ai v2.4.0 made receipt-driven development opt-in: an
+// install whose global mode was never set now resolves to off, and START is
+// rejected before it reaches any of the behavior these tests exist to check.
+//
+// Until that release these tests had a silent dependency on whatever the
+// operator happened to have configured. That is not a new hazard introduced by
+// the pin — it was always there — but the flip is what made it visible: the
+// suite was green on a machine with review enabled and red on a fresh CI
+// runner, from identical bytes. A test whose result depends on unversioned
+// machine state is not evidence either way.
+//
+// So each test owns a sandbox HOME and opts in the same way a user does,
+// exactly as gentle-ai did for its own lifecycle fixtures in the commit that
+// flipped the default. The process-wide HOME is what the extension-registered
+// controller path needs, because it spawns the CLI with the inherited
+// environment rather than an explicit one; it is restored afterwards.
+async function reviewEnabledHome(t: baseTest.TestContext): Promise<string> {
+	const home = await mkdtemp(join(tmpdir(), "gentle-pi-review-home-"));
+	const previousHome = process.env.HOME;
+	process.env.HOME = home;
+	t.after(async () => {
+		if (previousHome === undefined) delete process.env.HOME;
+		else process.env.HOME = previousHome;
+		await rm(home, { recursive: true, force: true });
+	});
+	const enabled = await run(binary, ["review", "mode", "enable", "--scope", "global", "--json"], packageRoot, false, { ...process.env, HOME: home });
+	// Assert the opt-in landed rather than assuming it. A silently ineffective
+	// enable would put these tests straight back to depending on ambient state,
+	// which is the exact failure this helper exists to remove.
+	assert.match(enabled.stdout, /"effective": "on"/, "the sandbox HOME must have receipt-driven development explicitly enabled");
+	return home;
+}
+
 async function run(command: string, arguments_: readonly string[], cwd: string, allowFailure = false, environment?: NodeJS.ProcessEnv): Promise<CommandResult> {
 	try {
 		const result = await execFileAsync(command, [...arguments_], { cwd, encoding: "utf8", shell: false, env: environment });
@@ -204,6 +238,7 @@ async function finalizeEmptyReview(repository: string, artifacts: string, starte
 }
 
 test("official pinned package runtime authorizes an unchanged linked-view candidate and denies a changed staging tree", async (t) => {
+	await reviewEnabledHome(t);
 	assert.equal(createHash("sha256").update(await readFile(binary)).digest("hex"), OFFICIAL_BINARY_SHA256);
 	assert.deepEqual(await run(binary, ["version"], packageRoot), { exitCode: 0, stdout: `gentle-ai ${GENTLE_AI_VERSION}\n`, stderr: "" });
 
@@ -285,6 +320,7 @@ test("official pinned package runtime authorizes an unchanged linked-view candid
 });
 
 test("official pinned package runtime keeps frozen candidate lineages and receipts isolated across replay and replacement", async (t) => {
+	await reviewEnabledHome(t);
 	const workspace = await mkdtemp(join(tmpdir(), "gentle-pi-v215-lineage-"));
 	const repository = join(workspace, "repository");
 	const artifacts = join(workspace, "artifacts");
@@ -379,6 +415,7 @@ test("official pinned package runtime keeps frozen candidate lineages and receip
 });
 
 test("registered gentle_review START materializes a safe internal skill symlink and cleans pending consent on session shutdown", async (t) => {
+	await reviewEnabledHome(t);
 	const workspace = await mkdtemp(join(tmpdir(), "gentle-pi-v215-symlink-candidate-"));
 	const repository = join(workspace, "repository");
 	t.after(async () => rm(workspace, { recursive: true, force: true }));

package/tests/native-review-parity.test.ts

@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import { execFileSync } from "node:child_process";
-import { mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { mkdtempSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import test from "node:test";
@@ -8,6 +8,7 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { __testing, createGentleAiExtension } from "../extensions/gentle-ai.ts";
 import {
 	NATIVE_REVIEW_ERROR_CODE,
+	REVIEW_CONSENT_NOTICES,
 	NativeReviewCliError,
 	NativeReviewConsentBindingError,
 	NativeReviewConsentRequiredError,
@@ -21,7 +22,7 @@ import {
 	type NativeStartRequest,
 } from "../lib/native-review-cli.ts";
 import { CandidateViewRegistry } from "../lib/review-candidate-view.ts";
-import { recordReviewConsentLatch } from "../lib/review-consent-latch.ts";
+import { readReviewConsentLatch, recordReviewConsentLatch } from "../lib/review-consent-latch.ts";
 import type { AuthorityRepairAssessmentV1, ReviewConsentV2, ReviewStatusV3 } from "../lib/review-integration-v2.ts";
 
 // Queued-adapter clients never execute a real process; default to a fixed
@@ -261,6 +262,29 @@ test("START tolerates the exact review-consent-skipped stderr line only when the
 	);
 });
 
+// gentle-ai v2.4.0 (feat(review)!: make receipt-driven development opt-in)
+// DELETED reviewConsentSkippedDefaultProvenance. It existed to admit reviews
+// were on because nobody chose; under opt-in RDD a default-source clone is
+// refused before the consent ceremony runs, so the pinned binary can never
+// emit it. The allowlist is a statement about what the PINNED binary writes
+// while still succeeding, so a line no pinned binary can produce does not
+// belong in it: keeping it would silently tolerate that exact text from
+// anywhere else in a START's stderr.
+test("the tolerated-stderr allowlist carries no line the pinned binary cannot emit", async () => {
+	assert.ok(
+		!REVIEW_CONSENT_NOTICES.some((notice) => notice.startsWith("Reviews are on by default")),
+		"the default-provenance notice was deleted upstream in v2.4.0 and must not stay tolerated",
+	);
+
+	const start = JSON.parse(START.stdout) as Record<string, unknown>;
+	const deleted = "Reviews are on by default; this was never explicitly chosen. Run 'gentle-ai review mode enable' to make reviews an explicit choice, or 'gentle-ai review mode disable' to turn them off.";
+	const queue = queuedAdapter([CAPABLE_VERSION_LINE, { stdout: JSON.stringify(start), stderr: deleted }]);
+	await assert.rejects(
+		() => new NativeReviewCliV213(queue.adapter).start({ cwd: "/repo" }),
+		(error: unknown) => error instanceof NativeReviewCliError && error.code === NATIVE_REVIEW_ERROR_CODE.UNEXPECTED_STDERR,
+	);
+});
+
 test("START rejects near-miss, prefixed, or extra-line stderr even when the mode capability is true", async () => {
 	const start = JSON.parse(START.stdout) as Record<string, unknown>;
 	const notice = "Gentle AI reviewed this change without asking, because this session has no terminal to answer on. Run 'gentle-ai review mode disable' to turn reviews off, or 'gentle-ai review mode status' to see the current setting.";
@@ -441,12 +465,16 @@ interface RegisteredEventFixture {
 	(event: unknown, ctx: ExtensionContext): Promise<unknown> | unknown;
 }
 
-function runtime(nativeReviewCli: NativeReviewCli | null): { controller: RegisteredTool; commands: Map<string, RegisteredCommandFixture>; events: Map<string, RegisteredEventFixture> } {
+function runtime(
+	nativeReviewCli: NativeReviewCli | null,
+	writeReviewConsentLatch: typeof recordReviewConsentLatch = recordReviewConsentLatch,
+	clock?: { now?: () => number; scheduleTimer?: (callback: () => void, delayMs: number) => { unref: () => void } },
+): { controller: RegisteredTool; commands: Map<string, RegisteredCommandFixture>; events: Map<string, RegisteredEventFixture> } {
 	const tools = new Map<string, RegisteredTool>();
 	const commands = new Map<string, RegisteredCommandFixture>();
 	const events = new Map<string, RegisteredEventFixture>();
-	const dependencies = { nativeReviewCli, candidateViews: new CandidateViewRegistry() } as unknown as Parameters<typeof createGentleAiExtension>[0];
-	createGentleAiExtension(dependencies)({
+	const dependencies = { nativeReviewCli, candidateViews: new CandidateViewRegistry(), ...clock } as unknown as Parameters<typeof createGentleAiExtension>[0];
+	__testing.createGentleAiExtension(dependencies, writeReviewConsentLatch)({
 		on(name: string, handler: RegisteredEventFixture) { events.set(name, handler); },
 		registerTool(definition: RegisteredTool & { name: string }) { tools.set(definition.name, definition); },
 		registerCommand(name: string, definition: RegisteredCommandFixture) { commands.set(name, definition); },
@@ -523,15 +551,28 @@ test("kill-switch: a global off names the native global-scope command, never Pi'
 	assert.ok(!/\/gentle:review-mode enable to turn/.test(String(result.next_action)), "a global off must never be sent to Pi's clone-scope command");
 });
 
-// Parity with reviewModeScopeForSource: the default source expresses no opinion
-// and can never be what keeps reviews off, so it gets no guessed continuation.
-test("kill-switch: an off with the default source names no continuation rather than guessing one", async (t) => {
+// Parity with reviewModeScopeForSource as of gentle-ai v2.4.0, which made
+// receipt-driven development opt-in. Before that release an all-sources-unset
+// install resolved to ON with source `default`, so `default` could never be
+// what kept reviews off and naming a continuation would have been a guess.
+// v2.4.0 resolves the same install to OFF with source `default`, which makes
+// this the MOST COMMON refusal there is: every install that never opted in.
+// gentle-ai answers `global` for it -- not because default is a global
+// opinion, but because global is the only scope that can turn reviews on at
+// all. Pi must say the same thing, because the alternative is handing the
+// single most common state a dead end with no way forward.
+test("kill-switch: an off with the default source names the only scope that can turn reviews on", async (t) => {
 	const cwd = repository(t);
 	const { native } = fakeOrganicNative({ reviewModeEffective: "off", reviewModeSource: "default" });
 	const { controller } = runtime(native);
 	const result = await execStart(controller, "kill-switch-default", headlessContext(cwd));
 	assert.equal(result.mode_source, "default");
-	assert.equal(result.next_action, undefined);
+	assert.equal(result.reason, "receipt-driven development is disabled: start is skipped because the default mode source keeps it off");
+	assert.equal(
+		result.next_action,
+		"Run `gentle-ai review mode enable --scope=global` to turn reviews on; receipt-driven development is opt-in and nothing here has enabled it yet. /gentle:review-mode enable only sets clone scope, which can never turn reviews on.",
+	);
+	assert.ok(!/\/gentle:review-mode enable to turn/.test(String(result.next_action)), "a default off must never be sent to Pi's clone-scope command");
 });
 
 test("kill-switch: capability-absent (no reviewMode) leaves today's path unchanged", async (t) => {
@@ -610,8 +651,13 @@ test("consent relay returns the identical complete parent-visible envelope with
 });
 
 test("explicit consent follow-up grants or declines exactly once", async (t) => {
-	const cwd = repository(t);
 	for (const answer of ["granted", "declined"] as const) {
+		const repositoryCwd = repository(t);
+		const cwd = `${repositoryCwd}-alias`;
+		symlinkSync(repositoryCwd, cwd, process.platform === "win32" ? "junction" : "dir");
+		t.after(() => rmSync(cwd, { force: true }));
+		const canonicalCwd = realpathSync(cwd);
+		assert.equal(readReviewConsentLatch(cwd), false);
 		const { native, answers, startRequests, answerRequests } = relayedConsentNative(cwd);
 		const { controller } = runtime(native);
 		const blocked = await blockedConsent(controller, `consent-${answer}`, headlessContext(cwd));
@@ -626,17 +672,42 @@ test("explicit consent follow-up grants or declines exactly once", async (t) =>
 		assert.equal(answerRequests[0]?.consent.targetIdentity, startRequests[0]?.targetIdentity);
 		if (answer === "granted") {
 			const actorBinding = result.actor_binding as { workspace_root: string; candidate_root: string };
-			assert.equal(actorBinding.workspace_root, cwd);
-			assert.notEqual(actorBinding.candidate_root, cwd);
+			assert.equal(actorBinding.workspace_root, canonicalCwd);
+			assert.notEqual(actorBinding.candidate_root, canonicalCwd);
+			assert.equal(readReviewConsentLatch(cwd), true);
 		} else {
 			assert.equal(result.outcome, "consent-declined-this-candidate");
 			assert.equal(result.lineage_created, false);
-			assert.equal(result.actor_binding, undefined);
+			assert.equal("actor_binding" in result, false);
+			assert.equal("result" in result, false);
+			assert.equal(readReviewConsentLatch(cwd), false);
 		}
 		await assert.rejects(() => answerConsent(controller, blocked.consent_binding, answer, headlessContext(cwd)), /unknown, expired, or already consumed/);
 	}
 });
 
+test("granted consent preserves the completed native start when local latch persistence fails", async (t) => {
+	const cwd = repository(t);
+	const { native, answers } = relayedConsentNative(cwd);
+	const notices: Array<{ message: string; type?: string }> = [];
+	let latchWrites = 0;
+	const { controller } = runtime(native, () => {
+		latchWrites += 1;
+		throw new Error("injected consent latch failure");
+	});
+	const blocked = await blockedConsent(controller, "consent-latch-failure", headlessContext(cwd, notices));
+	const result = await answerConsent(controller, blocked.consent_binding, "granted", headlessContext(cwd, notices));
+
+	assert.deepEqual(answers, ["granted"]);
+	assert.equal(latchWrites, 1);
+	assert.deepEqual(result.result, { lineage_id: "native-lineage", state: "reviewing", risk_tier: "high", selected_lenses: ["review-risk", "review-resilience", "review-readability", "review-reliability"], changed_files: 1, original_changed_lines: 1, correction_budget: 1, action: "created", lenses_required: true });
+	assert.equal((result.actor_binding as { workspace_root: string }).workspace_root, realpathSync(cwd));
+	assert.equal(readReviewConsentLatch(cwd), false);
+	assert.equal(notices.length, 1);
+	assert.equal(notices[0]?.type, "warning");
+	assert.match(notices[0]?.message ?? "", /native review start completed, but Pi could not record the local consent latch/i);
+});
+
 // Issue #247: a local binding mismatch was indistinguishable from a provider
 // outage, so the reporter diagnosed a missing --cwd that Pi does forward.
 test("a consent binding mismatch surfaces as an actionable local failure, not an opaque native operation failure", async (t) => {
@@ -657,6 +728,7 @@ test("a consent binding mismatch surfaces as an actionable local failure, not an
 	assert.equal(result.mutation_outcome, "none");
 	assert.equal(result.next_action, "resolve-consent-binding");
 	assert.deepEqual(answers, []);
+	assert.equal(readReviewConsentLatch(cwd), false);
 });
 
 test("consent follow-up rejects invalid token, unknown id, changed cwd, and changed target binding", async (t) => {
@@ -682,6 +754,17 @@ test("consent follow-up rejects invalid token, unknown id, changed cwd, and chan
 	(consent.choices[0] as { invocation: string }).invocation = consent.choices[0].invocation.replace("native-lineage", "changed-lineage");
 	await assert.rejects(() => answerConsent(controller, blocked.consent_binding, "granted", headlessContext(cwd)), /consent envelope binding changed/);
 	assert.deepEqual(answers, []);
+	assert.equal(readReviewConsentLatch(cwd), false);
+});
+
+test("unavailable consent follow-up leaves the clone latch unset", async (t) => {
+	const cwd = repository(t);
+	const { native } = relayedConsentNative(cwd);
+	delete native.answerConsent;
+	const { controller } = runtime(native);
+	const blocked = await blockedConsent(controller, "consent-unavailable", headlessContext(cwd));
+	await assert.rejects(() => answerConsent(controller, blocked.consent_binding, "granted", headlessContext(cwd)), /consent follow-up is unavailable/);
+	assert.equal(readReviewConsentLatch(cwd), false);
 });
 
 test("ambiguous consent mutation consumes the one-shot binding and requires status instead of blind replay", async (t) => {
@@ -696,11 +779,12 @@ test("ambiguous consent mutation consumes the one-shot binding and requires stat
 	await answerConsent(controller, blocked.consent_binding, "granted", headlessContext(cwd));
 	assert.equal(statusCalls, 2, "ambiguous consent must reconcile through target status");
 	await assert.rejects(() => answerConsent(controller, blocked.consent_binding, "granted", headlessContext(cwd)), /unknown, expired, or already consumed/);
+	assert.equal(readReviewConsentLatch(cwd), false);
 });
 
 test("session shutdown clears pending candidate consent bindings and is idempotent", async (t) => {
 	const cwd = repository(t);
-	const { native, answers } = relayedConsentNative(cwd);
+	const { native, answers, startRequests } = relayedConsentNative(cwd);
 	const { controller, events } = runtime(native);
 	const blocked = await blockedConsent(controller, "consent-before-shutdown", headlessContext(cwd));
 	const shutdown = events.get("session_shutdown");
@@ -709,6 +793,18 @@ test("session shutdown clears pending candidate consent bindings and is idempote
 	await shutdown({}, headlessContext(cwd));
 	await assert.rejects(() => answerConsent(controller, blocked.consent_binding, "granted", headlessContext(cwd)), /unknown, expired, or already consumed/);
 	assert.deepEqual(answers, []);
+	const afterShutdown = await blockedConsent(controller, "consent-after-shutdown", headlessContext(cwd));
+	assert.notEqual(afterShutdown.consent_binding, blocked.consent_binding, "the same candidate gets a fresh binding after shutdown cleanup");
+	assert.equal(startRequests.length, 2, "shutdown loss requires a fresh native START instead of local replay");
+});
+
+test("extension reload gives the same candidate a fresh consent binding instead of replaying lost local state", async (t) => {
+	const cwd = repository(t);
+	const { native, startRequests } = relayedConsentNative(cwd);
+	const beforeReload = await blockedConsent(runtime(native).controller, "consent-before-reload", headlessContext(cwd));
+	const afterReload = await blockedConsent(runtime(native).controller, "consent-after-reload", headlessContext(cwd));
+	assert.notEqual(afterReload.consent_binding, beforeReload.consent_binding);
+	assert.equal(startRequests.length, 2, "reload loss requires a fresh native START instead of local replay");
 });
 
 test("successful explicit disable clears pending candidate consent binding even after re-enable", async (t) => {
@@ -729,6 +825,90 @@ test("successful explicit disable clears pending candidate consent binding even
 	assert.deepEqual(answers, []);
 });
 
+// Issue #264: an unused consent binding and the candidate view retained
+// exclusively for that binding must expire as one lifecycle unit before any
+// later START may reuse the view. Cleanup is synchronous with respect to the
+// observable TTL; the queued cleanup macrotask is a safety net, not the
+// authority, so a fresh-candidate retry after expiry must get a new binding
+// rather than tripping candidate-target-projection-drift on a stale view.
+const REVIEW_CONSENT_TTL_MS = 10 * 60 * 1000;
+
+function fakeConsentClock(): { now: () => number; scheduleTimer: (callback: () => void, delayMs: number) => { unref: () => void }; advance: (ms: number) => void; scheduled: Array<() => void> } {
+	const start = Date.now();
+	let nowMs = start;
+	const scheduled: Array<() => void> = [];
+	return {
+		now: () => nowMs,
+		// Never fires the callback: simulates a queued cleanup macrotask that
+		// has not yet gotten a turn on the event loop.
+		scheduleTimer: (callback) => { scheduled.push(callback); return { unref: () => {} }; },
+		advance: (ms) => { nowMs = start + ms; },
+		scheduled,
+	};
+}
+
+test("an expired unused binding prunes synchronously so a fresh-candidate retry gets a new binding, not candidate-target-projection-drift", async (t) => {
+	const cwd = repository(t);
+	const { native, startRequests } = relayedConsentNative(cwd);
+	const clock = fakeConsentClock();
+	const { controller } = runtime(native, recordReviewConsentLatch, { now: clock.now, scheduleTimer: clock.scheduleTimer });
+	// First START: consent-required, binding T1 retained with a queued cleanup timer.
+	const first = await blockedConsent(controller, "expired-fresh-1", headlessContext(cwd));
+	const firstBinding = first.consent_binding;
+	assert.equal(clock.scheduled.length, 1, "the TTL cleanup macrotask is queued for T1");
+	// The candidate changes: a later START on a FRESH candidate must not reuse T1.
+	writeFileSync(join(cwd, "app.ts"), "export const value = 3;\n");
+	// Advance time to the exact TTL boundary without letting the queued cleanup macrotask fire.
+	clock.advance(REVIEW_CONSENT_TTL_MS);
+	assert.equal(clock.scheduled.length, 1, "the queued cleanup macrotask has not fired");
+	const second = await execStart(controller, "expired-fresh-2", headlessContext(cwd));
+	// The fix: a fresh consent-required binding, not candidate-target-projection-drift.
+	assert.equal(second.status, "blocked");
+	assert.equal(second.outcome, "native-review-consent-required", "the stale view must not trip candidate-target-projection-drift");
+	assert.equal(typeof second.consent_binding, "string");
+	assert.notEqual(second.consent_binding, firstBinding, "a fresh candidate gets a fresh binding, not the stale one");
+	assert.equal(startRequests.length, 2, "native start was attempted for both candidates");
+	assert.equal(clock.scheduled.length, 2, "the fresh binding queued its own cleanup macrotask");
+});
+
+test("an expired same-candidate consent request creates a fresh binding instead of replaying local state", async (t) => {
+	const cwd = repository(t);
+	const { native, startRequests } = relayedConsentNative(cwd);
+	const clock = fakeConsentClock();
+	const { controller } = runtime(native, recordReviewConsentLatch, { now: clock.now, scheduleTimer: clock.scheduleTimer });
+	const first = await blockedConsent(controller, "same-candidate-expired-1", headlessContext(cwd));
+	clock.advance(REVIEW_CONSENT_TTL_MS);
+	const second = await blockedConsent(controller, "same-candidate-expired-2", headlessContext(cwd));
+	assert.notEqual(second.consent_binding, first.consent_binding);
+	assert.equal(startRequests.length, 2, "expiry requires a fresh native START instead of local replay");
+	assert.equal(clock.scheduled.length, 2, "the fresh binding queues its own cleanup macrotask");
+});
+
+test("a non-expired same-candidate consent request reuses the same binding instead of creating a new one", async (t) => {
+	const cwd = repository(t);
+	const { native } = relayedConsentNative(cwd);
+	const clock = fakeConsentClock();
+	const { controller } = runtime(native, recordReviewConsentLatch, { now: clock.now, scheduleTimer: clock.scheduleTimer });
+	const first = await blockedConsent(controller, "dedup-1", headlessContext(cwd));
+	// Same candidate, same consent, still within TTL: the existing binding is reused.
+	const second = await blockedConsent(controller, "dedup-2", headlessContext(cwd));
+	assert.equal(second.consent_binding, first.consent_binding, "a non-expired same-candidate request deduplicates the binding");
+	assert.equal(clock.scheduled.length, 1, "no new cleanup macrotask is queued when the binding is reused");
+});
+
+test("an expired consent binding is rejected on answer-consent even before the queued cleanup macrotask fires", async (t) => {
+	const cwd = repository(t);
+	const { native } = relayedConsentNative(cwd);
+	const clock = fakeConsentClock();
+	const { controller } = runtime(native, recordReviewConsentLatch, { now: clock.now, scheduleTimer: clock.scheduleTimer });
+	const blocked = await blockedConsent(controller, "expired-answer-1", headlessContext(cwd));
+	// Advance to the exact TTL boundary without firing the queued cleanup macrotask.
+	clock.advance(REVIEW_CONSENT_TTL_MS);
+	assert.equal(clock.scheduled.length, 1, "the queued cleanup macrotask has not fired");
+	await assert.rejects(() => answerConsent(controller, blocked.consent_binding, "granted", headlessContext(cwd)), /unknown, expired, or already consumed/);
+	assert.equal(clock.scheduled.length, 1, "rejection was synchronous from the TTL observation, not from a fired macrotask");
+});
+
 test("candidate-scoped decline creates no authority and the next candidate asks again", async (t) => {
 	const cwd = repository(t);
 	const { native, answers } = relayedConsentNative(cwd);
@@ -738,11 +918,34 @@ test("candidate-scoped decline creates no authority and the next candidate asks
 		const result = await answerConsent(controller, blocked.consent_binding, "declined", headlessContext(cwd));
 		assert.equal(result.outcome, "consent-declined-this-candidate");
 		assert.equal(result.lineage_created, false);
-		assert.equal(result.actor_binding, undefined);
+		assert.equal("actor_binding" in result, false);
+		assert.equal("result" in result, false);
+		assert.equal(readReviewConsentLatch(cwd), false);
 	}
 	assert.deepEqual(answers, ["declined", "declined"]);
 });
 
+// Upstream gentle-ai.review-integration.consent/v3 consent is per-candidate:
+// the clone-local latch records only that the one-time question was already
+// put to the user, never that any later candidate is pre-approved. A fresh
+// START with the latch already recorded must still relay the complete
+// blocking envelope, and only an explicit ANSWER_CONSENT may resolve it.
+test("a pre-recorded consent latch never suppresses a later candidate's consent envelope or auto-answers it", async (t) => {
+	const cwd = repository(t);
+	recordReviewConsentLatch(cwd);
+	assert.equal(readReviewConsentLatch(cwd), true);
+	const { native, answers, startRequests } = relayedConsentNative(cwd);
+	const { controller } = runtime(native);
+	const blocked = await blockedConsent(controller, "consent-latched-fresh-start", headlessContext(cwd));
+	assert.deepEqual(blocked.consent, candidateConsent(cwd).raw, "the full consent envelope is relayed despite the pre-recorded latch");
+	assert.deepEqual(answers, [], "the latch must never auto-answer a later candidate's consent");
+	assert.equal(blocked.lineage_created, false);
+	assert.equal(startRequests.length, 1);
+	const result = await answerConsent(controller, blocked.consent_binding, "granted", headlessContext(cwd));
+	assert.deepEqual(answers, ["granted"], "explicit ANSWER_CONSENT is still required to proceed");
+	assert.ok(result.result);
+});
+
 test("low-risk zero-lens START remains silent", async (t) => {
 	const cwd = repository(t);
 	const { native } = fakeOrganicNative({ riskEvidence: undefined, lensesRequired: false });

package/tests/native-sdd-attempt-authority.test.ts

@@ -0,0 +1,235 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import test from "node:test";
+
+// ---------------------------------------------------------------------------
+// Native SDD Runtime Attempt Authority contract tests (issue #256 track 3).
+//
+// Locks the Pi-owned lazy-loaded orchestration/status contract that ports the
+// released Gentle AI v2.4.0 compact SDD attempt ledger authority. Pi must NOT
+// implement a local attempt runtime; it must route every runtime-bearing
+// sdd-apply/sdd-verify/remediation launch through the provider compact CLI.
+//
+// Both assets are Markdown contracts consumed by orchestrators; these tests
+// read the real repo files and assert the essential semantics, not merely
+// keyword presence. Negative controls guard against caller-authored
+// counters, OpenSpec/Engram attempt ledgers, automatic reset, and legacy
+// status|begin|finish|reset normal-flow routing.
+// ---------------------------------------------------------------------------
+
+const ROOT = join(import.meta.dirname, "..");
+const WORKFLOW = "assets/sdd-orchestrator-workflow.md";
+const STATUS_CONTRACT = "assets/support/sdd-status-contract.md";
+const SECTION = "Native Runtime Attempt Authority";
+
+function read(path: string): string {
+	return readFileSync(join(ROOT, path), "utf8");
+}
+
+function readMarkdownSection(source: string, heading: string): string {
+	const lines = source.split(/\r?\n/);
+	const matches = lines.flatMap((line, index) => {
+		const match = line.match(/^(#{1,6})\s+(.+?)\s*$/);
+		return match?.[2] === heading ? [{ index, level: match[1].length }] : [];
+	});
+	assert.equal(
+		matches.length,
+		1,
+		`Markdown must contain exactly one "${heading}" section (found ${matches.length})`,
+	);
+	const [{ index: start, level }] = matches;
+	const relativeEnd = lines.slice(start + 1).findIndex((line) => {
+		const match = line.match(/^(#{1,6})\s+/);
+		return match !== null && match[1].length <= level;
+	});
+	const end = relativeEnd === -1 ? lines.length : start + 1 + relativeEnd;
+	return lines.slice(start + 1, end).join("\n").trim();
+}
+
+// Extracts one command line beginning with `commandPrefix` so payload args bind
+// to the correct command shape; `--cwd`, `--change`, `--request-id` appear in
+// both acquire and settle, so a section-wide match stays green on arg removal.
+function extractCommandLine(section: string, commandPrefix: string): string {
+	const escaped = commandPrefix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	const re = new RegExp(`^[ \t]*${escaped}.*$`, "gm");
+	const matches = section.match(re) ?? [];
+	assert.equal(
+		matches.length,
+		1,
+		`Native Runtime Attempt Authority section must contain exactly one command line starting with "${commandPrefix}" (found ${matches.length})`,
+	);
+	const [line] = matches;
+	return line;
+}
+
+test("extractCommandLine rejects duplicate matching command lines (negative control)", () => {
+	for (const prefix of [
+		"gentle-ai sdd-attempt acquire ",
+		"gentle-ai sdd-attempt settle ",
+	]) {
+		const duplicate = [
+			`${prefix}--cwd repo --change change --request-id id`,
+			`${prefix}--cwd repo2 --change change2 --request-id id2`,
+		].join("\n");
+		assert.throws(
+			() => extractCommandLine(duplicate, prefix),
+			/exactly one command line/,
+			`duplicate ${prefix.trim()} lines must be rejected`,
+		);
+	}
+});
+
+test("workflow asset has exactly one Native Runtime Attempt Authority section", () => {
+	const section = readMarkdownSection(read(WORKFLOW), SECTION);
+	assert.ok(section.length > 0, "section must be non-empty");
+});
+
+test("status contract asset has exactly one Native Runtime Attempt Authority section", () => {
+	const section = readMarkdownSection(read(STATUS_CONTRACT), SECTION);
+	assert.ok(section.length > 0, "section must be non-empty");
+});
+
+test("workflow names acquire and settle as sole provider authority for OpenSpec and Engram", () => {
+	const section = readMarkdownSection(read(WORKFLOW), SECTION);
+	assert.match(section, /sdd-attempt acquire/);
+	assert.match(section, /sdd-attempt settle/);
+	assert.match(section, /sole attempt and changed-line budget authority/i);
+	assert.match(section, /Git-common-dir/);
+	assert.match(section, /OpenSpec and Engram/);
+});
+
+test("status contract names acquire and settle and forbids OpenSpec/Engram attempt ledgers", () => {
+	const section = readMarkdownSection(read(STATUS_CONTRACT), SECTION);
+	assert.match(section, /acquire/);
+	assert.match(section, /settle/);
+	assert.match(section, /OpenSpec or Engram attempt ledger/i);
+});
+
+test("workflow launches only on proceed; blocked and complete stop the launch", () => {
+	const section = readMarkdownSection(read(WORKFLOW), SECTION);
+	assert.match(section, /proceed/);
+	assert.match(section, /blocked/);
+	assert.match(section, /complete/);
+	assert.match(section, /launch only on `proceed`/i);
+	assert.match(section, /blocked.*do not launch/i);
+	assert.match(section, /complete.*do not launch/i);
+});
+
+test("workflow requires distinct request IDs with own-ID-only idempotent replay", () => {
+	const section = readMarkdownSection(read(WORKFLOW), SECTION);
+	assert.match(section, /distinct from acquire/i);
+	assert.match(section, /own ID only for idempotent replay/i);
+});
+
+test("workflow acquire command line binds every mandatory payload argument", () => {
+	const section = readMarkdownSection(read(WORKFLOW), SECTION);
+	const acquire = extractCommandLine(section, "gentle-ai sdd-attempt acquire ");
+	for (const arg of [
+		"--cwd <repo>",
+		"--change <change>",
+		"--request-id <id>",
+		"--work-unit <label>",
+		"--evidence-goal <goal>",
+		"--max-attempts <count>",
+		"--max-changed-lines <count>",
+	]) {
+		assert.ok(acquire.includes(arg), `acquire command is missing ${arg}; command: ${acquire}`);
+	}
+});
+
+test("workflow settle command line binds mandatory arguments and routing invariants", () => {
+	const section = readMarkdownSection(read(WORKFLOW), SECTION);
+	const settle = extractCommandLine(section, "gentle-ai sdd-attempt settle ");
+	for (const arg of [
+		"--cwd <repo>",
+		"--change <change>",
+		"--token <token>",
+		"--request-id <id>",
+		"--outcome <failed|interrupted|passed>",
+		"--evidence-revision <sha256:...>",
+		"--diagnosis <text>",
+		"--harness-disposition <reused|invalidated>",
+		"--cleanup-evidence <text>",
+		"--process-evidence <text>",
+	]) {
+		assert.ok(settle.includes(arg), `settle command is missing ${arg}; command: ${settle}`);
+	}
+	assert.match(section, /never `none`/);
+	assert.match(section, /proceed\|blocked\|complete/);
+	assert.match(section, /--successor-lineage/);
+	assert.match(section, /--remediates-evidence-revision/);
+});
+
+test("workflow forbids caller-authored counters and Pi-owned attempt state", () => {
+	const section = readMarkdownSection(read(WORKFLOW), SECTION);
+	assert.match(section, /never persist caller-authored/i);
+	assert.match(section, /OpenSpec artifacts, Engram memory/);
+	assert.match(section, /counter|token store|state machine|interception/i);
+});
+
+test("workflow states reset is never automatic and names compatibility surfaces", () => {
+	const section = readMarkdownSection(read(WORKFLOW), SECTION);
+	assert.match(section, /`status`, `begin`, `finish`, and `reset`/);
+	assert.match(section, /diagnostic\/compatibility surfaces/);
+	assert.match(section, /not the normal runtime route/i);
+	assert.match(section, /reset.*never automatic/i);
+	assert.match(section, /explicit maintainer scope decision/);
+});
+
+test("workflow gatekeeper rerun is subordinate to a fresh native acquire", () => {
+	const section = readMarkdownSection(read(WORKFLOW), SECTION);
+	assert.match(section, /rerun never bypasses native attempt authority/i);
+	assert.match(section, /fresh compact acquire/i);
+	// The gatekeeper quality rule is preserved (not deleted).
+	const gatekeeper = readMarkdownSection(read(WORKFLOW), "Automatic Mode Gatekeeper");
+	assert.match(gatekeeper, /rerun the same SDD phase once with corrective feedback/);
+	assert.match(gatekeeper, /Validate the rerun/);
+});
+
+test("workflow does not present status|begin|finish|reset as the primary route", () => {
+	const section = readMarkdownSection(read(WORKFLOW), SECTION);
+	assert.match(section, /not the normal runtime route/i);
+	assert.doesNotMatch(
+		section,
+		/primary route.*sdd-attempt (?:status|begin|finish|reset)/i,
+	);
+});
+
+test("status contract authority is artifact-store agnostic and excluded from SDD v1 status", () => {
+	const section = readMarkdownSection(read(STATUS_CONTRACT), SECTION);
+	assert.match(section, /artifact-store agnostic/i);
+	assert.match(section, /MUST NOT be embedded in the SDD v1 status/i);
+	assert.match(section, /separate from artifact dispatch/i);
+});
+
+test("status contract continuation rule: acquire before launch, settle after run, distinct IDs, provider states route, reset never automatic", () => {
+	const section = readMarkdownSection(read(STATUS_CONTRACT), SECTION);
+	assert.match(section, /before every runtime-bearing/i);
+	assert.match(section, /after the external run completes it MUST settle/i);
+	assert.match(section, /distinct/i);
+	assert.match(section, /proceed\|blocked\|complete/);
+	assert.match(section, /launch only on `proceed`/i);
+	assert.match(section, /reset.*never automatic/i);
+});
+
+test("status contract schema is unchanged (no attempt authority payload added)", () => {
+	const schema = readMarkdownSection(read(STATUS_CONTRACT), "Status Schema");
+	assert.doesNotMatch(
+		schema,
+		/attemptToken|attempt_token|attemptCount|attempt_counter|sddAttempt|sdd_attempt|nativeAttempt/i,
+		"Status Schema must not embed the runtime attempt authority payload",
+	);
+});
+
+test("status contract uses a runtime-safe semantic reference, not a repo-source assets/ path", () => {
+	const section = readMarkdownSection(read(STATUS_CONTRACT), SECTION);
+	assert.doesNotMatch(
+		section,
+		/See `assets\/sdd-orchestrator-workflow\.md`|see `assets\//i,
+		"status contract must not point installed consumers at a repo-source assets/ path; those are package source paths before installation",
+	);
+	assert.match(section, /lazy-loaded `SDD Orchestrator Workflow`/i);
+	assert.match(section, /Native Runtime Attempt Authority/);
+	assert.match(section, /Do not look up `assets\/\.\.\.` paths at runtime/i);
+});