From 1f7b003fbaf41bac4e100aa896a2aef25e8d21d1 Mon Sep 17 00:00:00 2001
From: garrytan <garrytan@gmail.com>
Date: Thu, 15 Oct 2026 01:16:56 +0000
Subject: [PATCH] fix(pregate): clear validates the remote gate receipt;
 test_backend run URLs are attested

`gstack-pregate clear` accepted any --run-url for a small machine's
obligation. A pregate.json/remote_gate obligation now clears only with
--receipt <file> holding the gate's PREGATE_REMOTE: line, validated as
--remote validates it (tree equals the tested tree, tests > 0, failed = 0;
shared parseRemoteReport/remoteReportProblem); a run URL is usage (exit 2)
and a bad receipt is PREGATE_RECEIPT_INVALID (exit 1, obligation unchanged).
A test_backend/<backend> obligation has no machine-checkable receipt: its
--run-url is recorded as attested:<url> and the output says attested, not
validated. Platform lanes are unchanged. Hints name the right clear form.

New code PREGATE_RECEIPT_INVALID: result-codes row, troubleshooting anchor,
installer-form error line, regenerated doctor components.

Files (G2): lib/pregate/index.ts, lib/pregate/checks/lanes.ts,
bin/gstack-pregate, lib/result-codes.ts, bin/gstack-doctor-components.sh
(generated), docs/pregate.md, docs/troubleshooting.md,
test/pregate-remote.test.ts.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
---
 bin/gstack-doctor-components.sh |  1 +
 bin/gstack-pregate              | 28 ++++++++++++--------
 docs/pregate.md                 |  6 ++++-
 docs/troubleshooting.md         | 14 ++++++++++
 lib/pregate/checks/lanes.ts     | 37 ++++++++++++++++++--------
 lib/pregate/index.ts            | 40 ++++++++++++++++++++++++++--
 lib/result-codes.ts             |  5 ++++
 test/pregate-remote.test.ts     | 47 +++++++++++++++++++++++++++------
 8 files changed, 145 insertions(+), 33 deletions(-)

diff --git a/bin/gstack-doctor-components.sh b/bin/gstack-doctor-components.sh
index cdff473ed..ce5109884 100644
--- a/bin/gstack-doctor-components.sh
+++ b/bin/gstack-doctor-components.sh
@@ -162,6 +162,7 @@ gstack_result_anchor() {
     PREGATE_LANE_FAILED) printf '%s' 'pregate-lane-failed' ;;
     PREGATE_INCOMPLETE) printf '%s' 'pregate-incomplete' ;;
     PREGATE_STALLED) printf '%s' 'pregate-stalled' ;;
+    PREGATE_RECEIPT_INVALID) printf '%s' 'pregate-receipt-invalid' ;;
     PREGATE_STALE) printf '%s' 'pregate-stale' ;;
     PREGATE_REMOTE_UNCLEARED) printf '%s' 'pregate-remote-uncleared' ;;
     ISSUE_UNREADABLE) printf '%s' 'issue-unreadable' ;;
diff --git a/bin/gstack-pregate b/bin/gstack-pregate
index afc5e42a2..fed93616d 100755
--- a/bin/gstack-pregate
+++ b/bin/gstack-pregate
@@ -6,7 +6,7 @@
  *                  [--allow-repo-commands] [--policy-from base|head] [--out <pregate.json>]
  *                  [--timeout <s>] [--stall-timeout <s>] [--remote --spend-cap <usd>] [--run <id>] [--explain] [--json]
  *   gstack-pregate verify [--out <pregate.json>] [--json]      publication check: current tree, no fail/incomplete, obligations cleared
- *   gstack-pregate clear --remote <workflow.yml/job> --run-url <url> | --bundle-lane <label> [--out <pregate.json>]
+ *   gstack-pregate clear --remote <workflow.yml/job> --run-url <url> | --bundle-lane <label> | --receipt <file> [--out <pregate.json>]
  *   gstack-pregate lanes [--explain]                             the lane list and platform tiers read from .github/workflows
  *   gstack-pregate validate | init [--explain] [--force]         the working-tree .gstack/pregate.json
  *   gstack-pregate sealed [--range <a..b>] [--remote <name>] [--base <branch>] [--json]
@@ -29,10 +29,11 @@ import * as path from 'node:path';
 import { EXIT, exitTableHelp, formatResult, type PregateFile } from '../lib/headless-artifacts';
 import { PREGATE_CONFIG_PATH, exampleConfigJson, explainConfig, loadConfigFromHead } from '../lib/pregate/config';
 import { buildContext } from '../lib/pregate/context';
-import { CHECKS, CHECK_IDS, PREGATE_OUT_REL, PREGATE_TIER2, clearObligation, readPregateFile, renderTable, runPregate, verifyPregate, writePregateFile } from '../lib/pregate/index';
+import { CHECKS, CHECK_IDS, PREGATE_OUT_REL, PREGATE_TIER2, clearDecision, clearObligation, readPregateFile, renderTable, runPregate, verifyPregate, writePregateFile } from '../lib/pregate/index';
 import { describeLane, discoverLanes } from '../lib/pregate/workflows';
+import { REMOTE_GATE_LANE } from '../lib/pregate/checks/lanes';
 import { ensureTmpExcluded } from '../lib/restamp';
-import { resultCodeSuffix, resultLine, type ResultCodeName } from '../lib/result-codes';
+import { RESULT_CODES, resultCodeSuffix, resultLine, type ResultCodeName } from '../lib/result-codes';
 import { DEFAULT_STALL_TIMEOUT_S } from '../lib/pregate/context';
 import { cancelActive } from '../lib/pregate/supervise';
 import { defaultGh, evaluateRegate, renderRegate } from '../lib/pregate/regate';
@@ -45,7 +46,9 @@ const HELP = `gstack-pregate — cheap checks before anything paid or remote (do
 
   run (default)   stage 1 mechanical preflight (${CHECKS.filter(c => c.stage === 'preflight').map(c => c.id).join(', ')}), then stage 2 test execution (${CHECKS.filter(c => c.stage === 'tests').map(c => c.id).join(', ')})
   verify          publication check against ${PREGATE_OUT_REL}: current tree, no fail or incomplete, every requires-remote obligation cleared
-  clear           record the receipt that clears one requires-remote obligation
+  clear           record the receipt that clears one requires-remote obligation: pregate.json/remote_gate needs
+                  --receipt <file> (the gate's PREGATE_REMOTE: line, checked against the tested tree); a
+                  test_backend/<backend> run URL is recorded as attested, not validated
   lanes           print every CI lane with its platform tier (from .github/workflows/*.yml)
   validate | init the working-tree ${PREGATE_CONFIG_PATH}
   sealed [--range <a..b>] [--remote <name>] [--base <branch>]
@@ -88,7 +91,7 @@ function flag(args: string[], name: string): string | undefined { const i = args
 const VERB_FLAGS: Record<string, [string[], string[]]> = {
   run: [['--stage', '--only', '--base', '--policy-from', '--out', '--timeout', '--stall-timeout', '--spend-cap', '--run'], ['--allow-repo-commands', '--explain', '--json', '--remote']],
   verify: [['--out'], ['--json']],
-  clear: [['--remote', '--run-url', '--bundle-lane', '--out'], []],
+  clear: [['--remote', '--run-url', '--bundle-lane', '--receipt', '--out'], []],
   lanes: [[], ['--explain', '--json']],
   validate: [[], ['--json']],
   init: [[], ['--explain', '--force']],
@@ -192,16 +195,19 @@ function cmdVerify(root: string, rest: string[], json: boolean): number {
 
 function cmdClear(root: string, rest: string[]): number {
   const lane = flag(rest, '--remote');
-  const receipt = flag(rest, '--run-url') ?? (flag(rest, '--bundle-lane') ? `bundle-lane:${flag(rest, '--bundle-lane')}` : undefined);
-  if (!lane || !receipt) { process.stderr.write(`gstack-pregate clear: --remote <workflow.yml/job> and --run-url <url> (or --bundle-lane <label>) are required\n`); return EXIT.usage; }
+  if (!lane) { process.stderr.write(`gstack-pregate clear: --remote <workflow.yml/job> with --run-url <url>, --bundle-lane <label> or (for ${REMOTE_GATE_LANE}) --receipt <file> is required\n`); return EXIT.usage; }
   const out = outPath(root, rest);
   const read = fs.existsSync(out) ? readPregateFile(out) : { file: null, errors: [] };
   if (!read.file) { process.stderr.write(resultLine('gstack-pregate clear', 'PREGATE_STALE', `${out} is missing or invalid; run gstack-pregate first`) + '\n'); return EXIT.fail; }
-  let file: PregateFile;
-  try { file = clearObligation(read.file, lane, receipt, `gstack-pregate clear ${new Date().toISOString()}`); }
-  catch (e: any) { process.stderr.write(`gstack-pregate clear: ${e.message}\n`); return EXIT.usage; }
+  const decision = clearDecision(read.file, lane, { runUrl: flag(rest, '--run-url'), bundleLane: flag(rest, '--bundle-lane'), receiptPath: flag(rest, '--receipt') });
+  if ('refused' in decision) {
+    if (decision.refused === 'usage') { process.stderr.write(`gstack-pregate clear: ${decision.message}\n`); return EXIT.usage; }
+    process.stderr.write(`gstack-pregate clear: receipt refused — ${decision.message}; fix: ${RESULT_CODES.PREGATE_RECEIPT_INVALID.fix} ${resultCodeSuffix('PREGATE_RECEIPT_INVALID')}\n`);
+    return EXIT.fail;
+  }
+  const file = clearObligation(read.file, lane, decision.receipt, `gstack-pregate clear ${new Date().toISOString()}`);
   writePregateFile(root, out, file);
-  process.stdout.write(`PREGATE_CLEARED: ${lane} receipt=${receipt} verdict=${file.verdict}\n`);
+  process.stdout.write(`PREGATE_CLEARED: ${lane} receipt=${decision.receipt} verdict=${file.verdict}${decision.attested ? ` (attested, not validated: ${lane} has no machine-checkable receipt)` : ''}\n`);
   return EXIT.ok;
 }
 
diff --git a/docs/pregate.md b/docs/pregate.md
index 7ec5d374d..804a84309 100644
--- a/docs/pregate.md
+++ b/docs/pregate.md
@@ -206,7 +206,11 @@ run, `pregate.json/remote_gate` (the declared command) or
 <repo> -- '<runner> <files>'`). Without either, the tier runs locally under
 the supervision above. Close the obligation one of two ways:
 
-- `gstack-pregate clear --remote <lane> --run-url <url>` after running it; or
+- after running it, `gstack-pregate clear --remote pregate.json/remote_gate
+  --receipt <file>` with the gate's output, validated as `--remote` validates it
+  (a run URL is refused, `PREGATE_RECEIPT_INVALID` for a bad receipt), or
+  `gstack-pregate clear --remote test_backend/<backend> --run-url <url>`, which
+  has no machine-checkable receipt and is recorded as `attested:<url>`; or
 - `gstack-pregate --stage tests --remote --spend-cap <usd> --allow-repo-commands`,
   which runs the declared `remote_gate` now (never under `--policy-from head`;
   a `test_backend` without `remote_gate` cannot be run this way). The gate runs
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index ca5df4506..0ba914ee8 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -2441,6 +2441,20 @@ child, a server that never exits, a synchronous wait), fix it and rerun
 needs a larger `--stall-timeout`; `0` disables the stall kill and leaves only
 `--timeout`.
 
+<a id="pregate-receipt-invalid"></a>
+### `PREGATE_RECEIPT_INVALID`
+
+**Meaning.** `gstack-pregate clear --remote pregate.json/remote_gate --receipt
+<file>` read the remote gate's output and its `PREGATE_REMOTE:` line is missing,
+names another tree than the one `pregate.json` tested, reports 0 tests, or
+reports failures. The obligation stays uncleared. A run URL alone never clears
+this obligation; a `test_backend/<backend>` obligation takes a run URL, recorded
+as attested rather than validated.
+
+**Fix.** Run the remote gate on the tree pregate tested and pass its output
+file with `--receipt`, or let `gstack-pregate --stage tests --remote --spend-cap
+<usd> --allow-repo-commands` run and validate it.
+
 <a id="pregate-stale"></a>
 ### `PREGATE_STALE`
 
diff --git a/lib/pregate/checks/lanes.ts b/lib/pregate/checks/lanes.ts
index a4419adc2..b4c5520c5 100644
--- a/lib/pregate/checks/lanes.ts
+++ b/lib/pregate/checks/lanes.ts
@@ -117,10 +117,29 @@ function remoteObligation(ctx: PregateContext, sel: Selection): RemoteObligation
   const declared = ctx.config.remote_gate;
   const runner = detectRunner(ctx, sel.localTests);
   const command = declared ?? `${GSTACK_ROOT}/scripts/ubicloud/ubi-runner.sh run --src ${quote(ctx.repoRoot)} -- ${quote(runner ? runner.replace('{files}', sel.localTests.map(quote).join(' ')) : '<test runner> <selected files>')}`;
-  const [workflow, job] = declared ? ['pregate.json', 'remote_gate'] : ['test_backend', ctx.testBackend];
+  const [workflow, job] = declared ? REMOTE_GATE_LANE.split('/') as [string, string] : ['test_backend', ctx.testBackend];
   return { lane: `${workflow}/${job}`, platform: 'remote', workflow, job, tests: sel.localTests, receipt: null, command };
 }
 
+export const REMOTE_GATE_LANE = 'pregate.json/remote_gate';
+/** The `clear` command for an obligation: the remote gate's own output for remote_gate, a run URL otherwise. */
+export const clearHint = (lane: string) => `gstack-pregate clear --remote ${lane} ${lane === REMOTE_GATE_LANE ? '--receipt <gate output file>' : '--run-url <url>'}`;
+export interface RemoteReport { tree: string; tests: number; failed: number; spent?: string }
+
+/** The last `PREGATE_REMOTE: tree=<tree> tests=<n> failed=<n> [spent=<usd>]` line in a remote gate's output. */
+export function parseRemoteReport(output: string): RemoteReport | null {
+  const m = [...output.matchAll(/^PREGATE_REMOTE: tree=(\S+) tests=(\d+) failed=(\d+)(?: spent=(\d+(?:\.\d+)?))?\s*$/gm)].pop();
+  return m ? { tree: m[1]!, tests: Number(m[2]), failed: Number(m[3]), spent: m[4] } : null;
+}
+
+/** Why a remote gate report does not clear the obligation for `tree` (`--remote` and `clear --receipt`), or null when it does. */
+export function remoteReportProblem(report: RemoteReport, tree: string): string | null {
+  if (report.tree !== tree) return `the remote gate tested tree ${report.tree.slice(0, 12)}, not ${tree.slice(0, 12)}`;
+  if (report.tests === 0) return 'the remote gate reported 0 tests';
+  if (report.failed > 0) return `the remote gate reported ${report.failed} failed of ${report.tests}`;
+  return null;
+}
+
 /**
  * `--remote`: run the declared remote gate now, under the spend cap. The
  * gate gets PREGATE_TREE, PREGATE_FILES_FILE and PREGATE_SPEND_CAP_USD and
@@ -141,22 +160,18 @@ async function runRemote(ctx: PregateContext, sel: Selection, base: CheckResult)
   fs.writeFileSync(filesFile, sel.localTests.join('\n') + '\n');
   const r = await supervise({ command: obligation.command!, cwd: ctx.repoRoot, env: { ...ctx.env, PREGATE_TREE: ctx.wtree, PREGATE_FILES_FILE: filesFile, PREGATE_SPEND_CAP_USD: String(cap) }, log, deadline: Date.now() + ctx.timeoutMs, stallMs: ctx.stallTimeoutMs, label: `remote gate ${obligation.lane}`, progress: ctx.progress });
   const output = readRange(log, r.start, r.end);
-  const reported = [...output.matchAll(/^PREGATE_REMOTE: tree=(\S+) tests=(\d+) failed=(\d+)(?: spent=(\d+(?:\.\d+)?))?\s*$/gm)].pop();
-  const spent = reported?.[4];
+  const reported = parseRemoteReport(output);
+  const spent = reported?.spent;
   const spend = `spend: spent ${spent ? `$${spent}` : '$0'}, reserved $0, unknown ${spent ? '$0' : `$${cap} (no spent= reported; counted at the cap)`} (cap $${cap})`;
   ctx.progress(`PREGATE_REMOTE_SPEND: ${spend.slice('spend: '.length)}`);
   const runLines = [...lines, `remote gate: ${obligation.command}`, `log: ${log}`, spend, ...output.trim().split('\n').slice(-15).map(l => `  ${l}`)];
   const inputs = { ...base.inputs, command: sha256(obligation.command!) };
   const why = r.outcome !== 'exited' ? `the remote gate did not finish (${r.outcome === 'stalled' ? `no output for ${ctx.stallTimeoutMs / 1000} s` : r.outcome})`
     : !reported ? `the remote gate exited ${r.exit} without a PREGATE_REMOTE: line`
-    : reported[1] !== ctx.wtree ? `the remote gate tested tree ${reported[1]!.slice(0, 12)}, not ${ctx.wtree.slice(0, 12)}`
-    : Number(reported[2]) === 0 ? 'the remote gate reported 0 tests'
-    : Number(reported[3]) > 0 ? `the remote gate reported ${reported[3]} failed of ${reported[2]}`
-    : r.exit !== 0 ? `the remote gate exited ${r.exit}`
-    : null;
+    : remoteReportProblem(reported, ctx.wtree) ?? (r.exit !== 0 ? `the remote gate exited ${r.exit}` : null);
   if (why) return { ...base, inputs, lines: runLines, status: 'incomplete', remote: [...sel.remote, obligation], code: r.outcome === 'stalled' ? 'PREGATE_STALLED' : 'PREGATE_INCOMPLETE', detail: `${why}; requires-remote ${obligation.lane} stays uncleared`, fix: `read ${log}; the obligation clears only on PREGATE_REMOTE: tree=${ctx.wtree.slice(0, 12)}… tests>0 failed=0 with exit 0` };
-  const cleared = { ...obligation, receipt: `remote-gate tree=${ctx.wtree.slice(0, 12)} tests=${reported![2]}`, cleared_by: `gstack-pregate --remote ${new Date().toISOString()}` };
-  return { ...base, inputs, lines: runLines, status: 'requires-remote', remote: [...sel.remote, cleared], detail: `remote gate ${obligation.lane}: ${reported![2]} tests, 0 failed on tree ${ctx.wtree.slice(0, 12)}; ${spend}` };
+  const cleared = { ...obligation, receipt: `remote-gate tree=${ctx.wtree.slice(0, 12)} tests=${reported!.tests}`, cleared_by: `gstack-pregate --remote ${new Date().toISOString()}` };
+  return { ...base, inputs, lines: runLines, status: 'requires-remote', remote: [...sel.remote, cleared], detail: `remote gate ${obligation.lane}: ${reported!.tests} tests, 0 failed on tree ${ctx.wtree.slice(0, 12)}; ${spend}` };
 }
 
 async function run(ctx: PregateContext): Promise<CheckResult> {
@@ -174,7 +189,7 @@ async function run(ctx: PregateContext): Promise<CheckResult> {
   const smallMachine = ctx.cores < SMALL_MACHINE_CORES && sel.localTests.length > 0 && (ctx.config.remote_gate || ctx.testBackend !== 'local');
   if (smallMachine) {
     const obligation = remoteObligation(ctx, sel);
-    return { ...base, status: 'requires-remote', remote: [...sel.remote, obligation], lines: [...lines, `requires-remote ${obligation.lane}: ${ctx.cores} cores (under ${SMALL_MACHINE_CORES}); ${sel.localTests.length} local test file(s) recorded for the remote gate, not run here`, `run: ${obligation.command}`], detail: `${sel.localTests.length} local test file(s) recorded as requires-remote ${obligation.lane} (${ctx.cores} cores, under ${SMALL_MACHINE_CORES}); run it, then gstack-pregate clear --remote ${obligation.lane} --run-url <url>, or gstack-pregate --remote --spend-cap <usd> --allow-repo-commands` };
+    return { ...base, status: 'requires-remote', remote: [...sel.remote, obligation], lines: [...lines, `requires-remote ${obligation.lane}: ${ctx.cores} cores (under ${SMALL_MACHINE_CORES}); ${sel.localTests.length} local test file(s) recorded for the remote gate, not run here`, `run: ${obligation.command}`], detail: `${sel.localTests.length} local test file(s) recorded as requires-remote ${obligation.lane} (${ctx.cores} cores, under ${SMALL_MACHINE_CORES}); run it, then ${clearHint(obligation.lane)}, or gstack-pregate --remote --spend-cap <usd> --allow-repo-commands` };
   }
   if (!ctx.allowRepoCommands) return { ...base, status: 'incomplete', code: 'REPO_COMMANDS_NOT_ALLOWED', detail: `${sel.localTests.length} local test file(s) selected but not run (pass --allow-repo-commands)`, fix: 'rerun with --allow-repo-commands (what /ship passes)' };
   if (sel.localTests.length === 0) return { ...base, status: sel.remote.length ? 'requires-remote' : 'pass', detail: `no local lane; ${sel.remote.length} requires-remote obligation(s)` };
diff --git a/lib/pregate/index.ts b/lib/pregate/index.ts
index 67b8e1fb8..76b5f7d73 100644
--- a/lib/pregate/index.ts
+++ b/lib/pregate/index.ts
@@ -10,12 +10,13 @@
  * land: `guards` (field wave CD1); ratchets, lint, links, hermetic, patches
  * and integrator later.
  */
+import { createHash } from 'node:crypto';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { ARTIFACT_SCHEMAS, checkSchema, type PregateFile, type PregateRemote, type ValidationError } from '../headless-artifacts';
 import { wtreeFingerprint } from '../regen';
 import { guardsCheck } from './checks/guards';
-import { lanesCheck } from './checks/lanes';
+import { clearHint, lanesCheck, parseRemoteReport, REMOTE_GATE_LANE, remoteReportProblem } from './checks/lanes';
 import { literalsCheck } from './checks/literals';
 import { regenCheck } from './checks/regen';
 import { secretsCheck } from './checks/secrets';
@@ -86,7 +87,7 @@ export function renderTable(file: PregateFile, opts: { lines?: boolean } = { lin
   ].filter(Boolean);
   const remote = (file.requires_remote ?? []).map(r => {
     const run = r.command ? `run ${r.command.length > 200 ? `${r.command.slice(0, 200)}… (full command in pregate.json)` : r.command}, then ` : '';
-    return `requires-remote: ${r.lane} (${r.platform}) ${r.tests.length} test(s) — ${r.receipt ? `cleared by ${r.receipt}` : `uncleared; ${run}clear with gstack-pregate clear --remote ${r.lane} --run-url <url>`}`;
+    return `requires-remote: ${r.lane} (${r.platform}) ${r.tests.length} test(s) — ${r.receipt ? `cleared by ${r.receipt}` : `uncleared; ${run}clear with ${clearHint(r.lane)}`}`;
   });
   return [
     `stage      check     status            time  detail`,
@@ -134,6 +135,41 @@ export function verifyPregate(repoRoot: string, file: PregateFile, treeNow = wtr
   return { ok: true, message: `pregate ${file.verdict} is current for tree ${file.tree.slice(0, 12)}`, current, uncleared };
 }
 
+export interface ClearInput { runUrl?: string; bundleLane?: string; receiptPath?: string }
+export type ClearDecision = { receipt: string; attested: boolean } | { refused: 'usage' | 'PREGATE_RECEIPT_INVALID'; message: string };
+
+/**
+ * What `clear` may record for one obligation. A `pregate.json/remote_gate`
+ * obligation needs the gate's own report (`--receipt <file>` holding its
+ * PREGATE_REMOTE: line), validated as `--remote` validates it against the
+ * tested tree; a run URL is not checkable there. A `test_backend/<backend>`
+ * obligation has no machine-checkable receipt, so its run URL is recorded as
+ * attested. Platform lanes take a run URL or an evidence-bundle lane label.
+ */
+export function clearDecision(file: PregateFile, lane: string, input: ClearInput): ClearDecision {
+  const list = file.requires_remote ?? [];
+  const target = list.find(r => r.lane === lane);
+  if (!target) return { refused: 'usage', message: `no requires-remote obligation named ${lane}; obligations: ${list.map(r => r.lane).join(', ') || '(none)'}` };
+  if (target.lane === REMOTE_GATE_LANE) {
+    if (!input.receiptPath) return { refused: 'usage', message: `${lane} clears only with --receipt <file> holding the remote gate's PREGATE_REMOTE: tree=… tests=… failed=… line (a run URL is not checkable); or rerun gstack-pregate --remote` };
+    let text: string;
+    try { text = fs.readFileSync(input.receiptPath, 'utf8'); }
+    catch (e: any) { return { refused: 'PREGATE_RECEIPT_INVALID', message: `cannot read ${input.receiptPath}: ${e.message}` }; }
+    const report = parseRemoteReport(text);
+    const problem = report ? remoteReportProblem(report, file.tree) : `${input.receiptPath} has no PREGATE_REMOTE: line`;
+    if (problem) return { refused: 'PREGATE_RECEIPT_INVALID', message: `${problem}; ${lane} stays uncleared` };
+    return { receipt: `remote-gate tree=${file.tree.slice(0, 12)} tests=${report!.tests} receipt=${path.resolve(input.receiptPath)} sha256=${createHash('sha256').update(text).digest('hex').slice(0, 12)}`, attested: false };
+  }
+  if (input.receiptPath) return { refused: 'usage', message: `--receipt applies only to ${REMOTE_GATE_LANE}; clear ${lane} with --run-url <url>${target.workflow === 'test_backend' ? '' : ' or --bundle-lane <label>'}` };
+  if (target.workflow === 'test_backend') {
+    if (!input.runUrl) return { refused: 'usage', message: `${lane} clears with --run-url <url>` };
+    return { receipt: `attested:${input.runUrl}`, attested: true };
+  }
+  const receipt = input.runUrl ?? (input.bundleLane ? `bundle-lane:${input.bundleLane}` : undefined);
+  if (!receipt) return { refused: 'usage', message: `${lane} clears with --run-url <url> or --bundle-lane <label>` };
+  return { receipt, attested: false };
+}
+
 /** Record the receipt that clears one obligation (a run URL or an evidence-bundle lane label). */
 export function clearObligation(file: PregateFile, lane: string, receipt: string, by: string): PregateFile {
   const list = file.requires_remote ?? [];
diff --git a/lib/result-codes.ts b/lib/result-codes.ts
index 7dd10e420..fa25c5f99 100644
--- a/lib/result-codes.ts
+++ b/lib/result-codes.ts
@@ -394,6 +394,11 @@ export const RESULT_CODES = {
     summary: 'a test command printed nothing for the stall timeout, so its process group was killed; the check is incomplete, never pass',
     fix: 'read the lane log for the last file started, fix the hang, or raise `--stall-timeout` (`stall_timeout_s`; 0 disables) for a test that is quiet for longer, then rerun `gstack-pregate --stage tests`',
   },
+  PREGATE_RECEIPT_INVALID: {
+    anchor: 'pregate-receipt-invalid',
+    summary: 'the receipt offered to `gstack-pregate clear` for the remote gate obligation does not show the tested tree passing',
+    fix: 'rerun the remote gate on this tree and pass its output with `gstack-pregate clear --remote pregate.json/remote_gate --receipt <file>`, or run `gstack-pregate --stage tests --remote --spend-cap <usd> --allow-repo-commands`',
+  },
   PREGATE_STALE: {
     anchor: 'pregate-stale',
     summary: 'pregate.json was recorded against a different tree than the one being published',
diff --git a/test/pregate-remote.test.ts b/test/pregate-remote.test.ts
index 472f527ba..5c2dc8022 100644
--- a/test/pregate-remote.test.ts
+++ b/test/pregate-remote.test.ts
@@ -71,16 +71,47 @@ describe('small machines record the test tier for the remote gate (C4)', () => {
     expect((await lanesOn(gated(), { cores: 16, testBackend: 'local' })).lanes.status).toBe('pass');
   });
 
-  test('`clear` discharges the recorded obligation like any requires-remote lane', () => {
+  test('`clear` on the remote_gate obligation needs the gate\'s PREGATE_REMOTE receipt for the tested tree; a run URL or a bad receipt leaves it uncleared', async () => {
     const repo = gated();
     const fileAt = path.join(repo.work, '.gstack/tmp/pregate.json');
-    return lanesOn(repo, { cores: 4, testBackend: 'local' }).then(({ file }) => {
-      fs.mkdirSync(path.dirname(fileAt), { recursive: true });
-      fs.writeFileSync(fileAt, JSON.stringify(file));
-      const cleared = runBin(repo, 'gstack-pregate', ['clear', '--remote', 'pregate.json/remote_gate', '--run-url', 'https://ci.example/run/1']);
-      expect(cleared.status).toBe(EXIT.ok);
-      expect(cleared.out).toContain('PREGATE_CLEARED: pregate.json/remote_gate receipt=https://ci.example/run/1 verdict=requires-remote cleared');
-    });
+    const { file } = await lanesOn(repo, { cores: 4, testBackend: 'local' });
+    fs.mkdirSync(path.dirname(fileAt), { recursive: true });
+    fs.writeFileSync(fileAt, JSON.stringify(file));
+    const clear = (args: string[]) => runBin(repo, 'gstack-pregate', ['clear', '--remote', 'pregate.json/remote_gate', ...args]);
+    const receiptOf = (line: string) => { const f = path.join(repo.root, `receipt-${Math.random().toString(36).slice(2)}.log`); fs.writeFileSync(f, `gate log\n${line}\n`); return f; };
+    const url = clear(['--run-url', 'https://ci.example/run/1']);
+    expect(url.status).toBe(EXIT.usage);
+    expect(url.err).toContain('clears only with --receipt <file>');
+    for (const [line, why] of [
+      [`PREGATE_REMOTE: tree=${'deadbeef'.repeat(8)} tests=3 failed=0`, 'the remote gate tested tree deadbeefdead'],
+      [`PREGATE_REMOTE: tree=${file.tree} tests=0 failed=0`, 'the remote gate reported 0 tests'],
+      [`PREGATE_REMOTE: tree=${file.tree} tests=3 failed=1`, 'the remote gate reported 1 failed of 3'],
+      ['all green, trust me', 'has no PREGATE_REMOTE: line'],
+    ] as const) {
+      const r = clear(['--receipt', receiptOf(line)]);
+      expect(r.status).toBe(EXIT.fail);
+      expect(r.err).toContain(why);
+      expect(r.err).toContain('(PREGATE_RECEIPT_INVALID; https://github.com/garrytan/gstack/blob/main/docs/troubleshooting.md#pregate-receipt-invalid)');
+      expect(JSON.parse(fs.readFileSync(fileAt, 'utf8')).requires_remote[0].receipt).toBeNull();
+    }
+    const ok = clear(['--receipt', receiptOf(`PREGATE_REMOTE: tree=${file.tree} tests=3 failed=0`)]);
+    expect(ok.status).toBe(EXIT.ok);
+    expect(ok.out).toMatch(new RegExp(`^PREGATE_CLEARED: pregate\\.json/remote_gate receipt=remote-gate tree=${file.tree.slice(0, 12)} tests=3 receipt=\\S+ sha256=[0-9a-f]{12} verdict=requires-remote cleared$`, 'm'));
+    expect(ok.out).not.toContain('attested');
+  });
+
+  test('`clear` on a test_backend obligation records the run URL as attested, not validated, and says so', async () => {
+    const repo = gated(BASE_PREGATE);
+    const fileAt = path.join(repo.work, '.gstack/tmp/pregate.json');
+    const { file, lanes } = await lanesOn(repo, { cores: 4, testBackend: 'ubicloud' });
+    expect(lanes.detail).toContain('gstack-pregate clear --remote test_backend/ubicloud --run-url <url>');
+    fs.mkdirSync(path.dirname(fileAt), { recursive: true });
+    fs.writeFileSync(fileAt, JSON.stringify(file));
+    expect(runBin(repo, 'gstack-pregate', ['clear', '--remote', 'test_backend/ubicloud', '--receipt', fileAt]).status).toBe(EXIT.usage);
+    const r = runBin(repo, 'gstack-pregate', ['clear', '--remote', 'test_backend/ubicloud', '--run-url', 'https://ci.example/run/7']);
+    expect(r.status).toBe(EXIT.ok);
+    expect(r.out).toContain('PREGATE_CLEARED: test_backend/ubicloud receipt=attested:https://ci.example/run/7 verdict=requires-remote cleared (attested, not validated: test_backend/ubicloud has no machine-checkable receipt)');
+    expect(JSON.parse(fs.readFileSync(fileAt, 'utf8')).requires_remote[0].receipt).toBe('attested:https://ci.example/run/7');
   });
 
   test('config: stall_timeout_s and remote_gate are typed', async () => {