@sun-asterisk/sungen 3.3.0-alpha.7 → 3.3.0-alpha.9

package/src/cli/project-sungen-invocation.ts

@@ -8,6 +8,9 @@
  *
  *   sungenInvocation(root)          'npx sungen' when <root>/node_modules/@sun-asterisk/sungen exists, else 'sungen'
  *   withProjectInvocation(cmd, root) a canonical `sungen …` command as this project runs it
+ *   withProjectInvocationInText(text, root)
+ *                                   every `sungen …` command inside printed text (a refusal, a hint, a
+ *                                   step's reason) as this project runs it (#963); prose mentions stay
  *   updateCommand(root, version?)   `<invocation> update` plus `--alpha` / `--beta` (`--tag <id>` for another prerelease)
  *
  * Only the project root itself is looked at — where `npm i` puts a QA project's install — so a
@@ -27,6 +30,23 @@ export function withProjectInvocation(command: string, projectRoot: string): str
   return inv !== 'sungen' && /^sungen\b/.test(command) ? `${inv}${command.slice('sungen'.length)}` : command;
 }
 
+/**
+ * A `sungen` that starts a command inside text: at the start of a line (after indentation), after a
+ * backtick or `(`, after ": ", "run " or "then " — and followed by a subcommand or an option. A prose
+ * mention ("written by sungen 3.3.0", "an older sungen", "sungen: …") is none of these.
+ */
+const COMMAND_IN_TEXT = /(^[ \t]*|[`(]|:[ \t]+|\b(?:[Rr]un|then)[ \t]+)sungen(?= [a-z-])/gm;
+
+/**
+ * Printed text (a refusal, a hint, a step's reason) with every `sungen …` command in it as this project
+ * runs sungen (#963): the human-only commands a QA copies from a refusal must run the project's own
+ * install, not an older global one. Text for machines (`--json`) stays canonical; this is for the screen.
+ */
+export function withProjectInvocationInText(text: string, projectRoot: string): string {
+  const inv = sungenInvocation(projectRoot);
+  return inv === 'sungen' ? text : text.replace(COMMAND_IN_TEXT, (_m, before: string) => `${before}${inv}`);
+}
+
 /** The `sungen update` flag that keeps the channel of `version` (its prerelease id); '' for stable. */
 export function updateChannelFlag(version: string = getPackageVersion()): string {
   const id = version.match(/^\d+\.\d+\.\d+-([0-9A-Za-z-]+)/)?.[1];

package/src/cli/run-command-hints.ts

@@ -0,0 +1,47 @@
+/**
+ * The run commands sungen suggests, each writing its results where the reader that asks for them
+ * looks (#964). A hint whose results nobody reads leaves a passing run invisible: the plain
+ * `npx playwright test` wrote `test-result.json` at the project root, which `sungen next` never reads.
+ *
+ *   generatedSubdir(kind, unit)      `specs/generated/<unit>` · `…/flows/<flow>` · `…/api/<area>` — where
+ *                                    `generate` writes a unit's specs and `next` / `delivery` read its results
+ *   plainRunCommand(genRel, feature) one compiled feature's spec with the JSON reporter pointed at
+ *                                    `<genRel>/<feature>-test-result.json` (graph/unit-artifact-probes RESULT_FILE)
+ *   freeRunCommand(cwd)              hand-written @free / impl:code tests: the project's free-test config, which
+ *                                    writes into its own outputDir `test-results-free/` (#941)
+ *   freeRunHasResults(cwd)           that run left its results (or a sungen run record) there
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { FREE_RUN_DIR } from '../contract/trace/trace-run-record';
+
+export type RunUnitKind = 'screen' | 'flow' | 'api';
+
+export function generatedSubdir(kind: RunUnitKind, unit: string): string {
+  return path.posix.join('specs', 'generated', ...(kind === 'flow' ? ['flows'] : kind === 'api' ? ['api'] : []), unit);
+}
+
+/** `[SUNGEN_ENV=<env> ]PLAYWRIGHT_JSON_OUTPUT_NAME=<genRel>/<feature>-test-result.json npx playwright test <genRel>/<feature>.spec.ts` */
+export function plainRunCommand(genRel: string, featureBaseName: string, env?: string): string {
+  return `${env ? `SUNGEN_ENV=${env} ` : ''}PLAYWRIGHT_JSON_OUTPUT_NAME=${genRel}/${featureBaseName}-test-result.json npx playwright test ${genRel}/${featureBaseName}.spec.ts`;
+}
+
+const FREE_CONFIG = /^playwright\.free\.config\.(?:ts|mts|cts|js|mjs|cjs)$/;
+
+/** The free run: `npx playwright test -c <playwright.free.config.*>` when the project has one, else what that config holds. */
+export function freeRunCommand(cwd: string): string {
+  let config: string | undefined;
+  try { config = fs.readdirSync(cwd).find((f) => FREE_CONFIG.test(f)); } catch { /* no project dir: the generic form */ }
+  return config
+    ? `npx playwright test -c ${config}`
+    : `run the hand-written tests with the project's free-test config (outputDir '${FREE_RUN_DIR}', trace: 'on', the sungen run-record reporter — "Free tests" in the sungen docs)`;
+}
+
+/** The free run left its JSON results or a sungen run record in `test-results-free/`. */
+export function freeRunHasResults(cwd: string): boolean {
+  try {
+    return fs.readdirSync(path.join(cwd, FREE_RUN_DIR)).some((f) => f === 'results.json' || /^sungen-run-record.*\.json$/.test(f));
+  } catch {
+    return false;   // never run
+  }
+}

package/src/cli/waiting-for-you-block.ts

@@ -1,23 +1,27 @@
 /**
  * The "Waiting for you" block (#954) — every pending human-only action of a unit, as ready-to-copy
  * commands with the reason under each. One renderer for the three places that show it: `sungen next`
- * (text) and the Stop / SessionStart hook context. Commands as the project runs sungen (`npx sungen`
- * with a local install, #939); `--json` keeps them canonical in `humanActions`. An instruction (a commit
- * through review, a `git checkout --`) is marked `✎ … (by hand, not a command)`, never shown as one to copy.
+ * (text) and the Stop / SessionStart hook context. Commands — and those inside a reason (#963) — as the
+ * project runs sungen (`npx sungen` with a local install, #939); `--json` keeps `command` canonical in
+ * `humanActions` and adds `rendered`. An instruction (a commit through review, a `git checkout --`) is
+ * marked `✎ … (by hand, not a command)`, never shown as one to copy.
  */
 import type { HumanAction } from '../graph/human-action';
-import { withProjectInvocation } from './project-sungen-invocation';
+import { withProjectInvocation, withProjectInvocationInText } from './project-sungen-invocation';
 
 export const WAITING_FOR_YOU_HEAD = '⏳ Waiting for you — a human runs these in their own terminal (in Claude Code: ! <command>); an agent never runs them:';
 
 /**
- * The block's lines (indented two spaces), or none when nothing waits for a human. `heldBy`: the title
- * of the blocking step that cut the frontier — the block is not exhaustive then, and says what holds the rest.
+ * The block's lines (indented two spaces), or none when nothing waits for a human and nothing holds the
+ * rest. `heldBy`: the title of the blocking step that cut the frontier — the block is not exhaustive then,
+ * and says what holds the rest, with that step's command (`heldByCommand`) when given (#966). A held
+ * block with no item of its own still says so, rather than vanishing (a QA read "nothing is waiting").
  */
-export function waitingForYouLines(actions: readonly HumanAction[] | undefined, projectRoot: string, heldBy?: string): string[] {
-  if (!actions?.length) return [];
+export function waitingForYouLines(actions: readonly HumanAction[] | undefined, projectRoot: string, heldBy?: string, heldByCommand?: string): string[] {
+  const holds = heldBy ? `"${heldBy}" clears${heldByCommand ? ` (the step above: ${withProjectInvocationInText(heldByCommand, projectRoot)})` : ''}` : '';
+  if (!actions?.length) return heldBy ? [`  ⏳ Waiting for you: nothing yet — more appear once ${holds}.`] : [];
   return [`  ${WAITING_FOR_YOU_HEAD}`, ...actions.flatMap((a) => [
     a.instruction ? `     ✎ ${a.command}   (by hand, not a command)` : `     ${withProjectInvocation(a.command, projectRoot)}`,
-    `       ${a.reason}`,
-  ]), ...(heldBy ? [`     More appear once "${heldBy}" clears.`] : [])];
+    `       ${withProjectInvocationInText(a.reason, projectRoot)}`,
+  ]), ...(heldBy ? [`     More appear once ${holds}.`] : [])];
 }

package/src/contract/build-trace-conformance.ts

@@ -12,17 +12,17 @@
  * Bounded (review H4, M2): a deadline (`budgetMs`; the guard's default is ~3 s) — a scenario not
  * judged in time is `unproven` when approved, a warning while proposed: fail CLOSED. An input that
  * cannot be read while judging (test-data, a trace) makes that scenario unproven with its reason,
- * never a thrown verdict. A trace older than the unit's newest `.feature` / lock is refused (stale).
+ * never a thrown verdict. A trace older than the unit's `.feature` / lock is refused (stale) — judged
+ * by their content, so a touch or a fresh clone stales nothing (#967, trace/trace-freshness.ts).
  */
 import { createHash } from 'crypto';
 import * as fs from 'fs';
 import { readCapabilities } from '../harness/capability';
 import { classifyTraceRuns, notJudged, TraceOutcome } from './classify-trace-conformance';
 import { ContractLock, ContractScenario, isHumanApproved, LockEntry } from './contract-schema';
-import { lockPathFor } from './contracts-lock-file';
 import { loadTestDataIndex, TestDataIndex } from './data-normalize';
-import { contractFeatureFiles } from './normalize-feature-steps';
 import { renderTraceSteps, RenderedStep } from './render-free-gherkin';
+import { unitContract } from './trace/trace-freshness';
 import { collectScenarioEvidence, OVER_BUDGET, ScenarioEvidence, TraceRun } from './trace/collect-trace-evidence';
 
 export { OVER_BUDGET } from './trace/collect-trace-evidence';
@@ -33,7 +33,6 @@ import { traceIntentSteps } from './trace/trace-steps';
 
 export interface UnitTraceConformance { outcomes: Map<string, TraceOutcome>; warnings: string[]; inputs: unknown }
 
-const mtimeMs = (f: string): number => { try { return fs.statSync(f).mtimeMs; } catch { return 0; } };
 const sha = (s: string | Buffer): string => createHash('sha256').update(s).digest('hex');
 const why = (e: unknown): string => (e instanceof Error ? e.message : String(e)).split('\n')[0].slice(0, 300);
 
@@ -65,8 +64,7 @@ export function traceConformanceForUnit(
   let index: TestDataIndex = { byValue: new Map() };
   let setupError = '';
   try {
-    const notBefore = Math.max(mtimeMs(lockPathFor(unit.dir)), ...contractFeatureFiles(unit.dir, unit.name).map(mtimeMs));
-    evidence = collectScenarioEvidence(projectRoot, new Set(traced.map((s) => s.id)), notBefore, deadline, new Map(traced.map((s) => [s.id, s.source.name])));
+    evidence = collectScenarioEvidence(projectRoot, new Set(traced.map((s) => s.id)), unitContract(projectRoot, unit), deadline, new Map(traced.map((s) => [s.id, s.source.name])));
     index = loadTestDataIndex(unit.dir, unit.name);
   } catch (e) { setupError = `trace conformance could not run: ${why(e)}`; }
   const { cache, problem } = readIdentityCache(projectRoot);

package/src/contract/derive-free-feature.ts

@@ -8,6 +8,8 @@
  *   identities    asked of the registered `traceIdentity` resolver (driver-ui) when one is given,
  *                 otherwise the cache, otherwise core's heuristic — `# identity low` marks those steps
  *   approved      a scenario QA already approved (no `@proposed`) is never rewritten
+ *   one id, one   two recorded tests claiming one id (#962) refuse the derive — both named with
+ *   test          file:line, NOTHING written for the unit: keeping one would drop the other's contract
  *   safety        redaction by field meaning, machine paths scrubbed, then the secret scanner and the
  *                 semantic credential check over the exact text: any hit → NOTHING is written
  */
@@ -25,6 +27,7 @@ import { scenariosOfFeatureFile } from './normalize-feature-steps';
 import { featureFilesFor } from '../harness/unit-paths';
 import { CONTROL_CHARS, freeFeatureText, renderTraceSteps, scenarioBlockText } from './render-free-gherkin';
 import { collectRuns, TraceRun } from './trace/collect-trace-evidence';
+import { idsClaimedByTwoTests } from './trace/scenario-id-claims';
 import { readIdentityCache } from './trace/identity-cache';
 import type { TraceIdentityResolver } from './trace/target-identity';
 import { identitiesFor, resolveWithDriver } from './trace/trace-identity-resolution';
@@ -39,6 +42,11 @@ export interface DeriveResult {
   /** `approved: true` — skipped because QA already approved it (derive never rewrites one), not for want of a trace. */
   skipped: Array<{ id: string; reason: string; approved?: true }>;
   refused?: SecretHit[];
+  /**
+   * Ids two or more recorded tests claim (#962), each test as `file:line "title" (run record <path>)` —
+   * nothing was written. `staleRecords`: older test-results/ records that are a claim's only source.
+   */
+  duplicateIds?: Array<{ id: string; tests: string[]; staleRecords?: string[] }>;
   note?: string;
   /** A derived id another `.feature` of the unit already uses (#939) — `contract check` and approve would trip on it later. */
   warnings?: string[];
@@ -75,7 +83,7 @@ function reusedIdWarnings(unit: { name: string; dir: string }, freeFile: string,
     } catch { /* an unparseable sibling is `contract check`'s to report */ }
   }
   return ids.filter((id) => owners.has(id)).map((id) =>
-    `${id} is already the ID of a scenario in ${owners.get(id)} — the derived scenario reuses it; give the free test (its title's leading ID) or that scenario its own ID, or \`sungen contract check\` reports it twice and approval refuses it`);
+    `${id} is already the ID of a scenario in ${owners.get(id)} — the derived scenario reuses it; give the free test (its title's leading ID, or its @tag) or that scenario its own ID, or \`sungen contract check\` reports it twice and approval refuses it`);
 }
 
 /**
@@ -84,7 +92,7 @@ function reusedIdWarnings(unit: { name: string; dir: string }, freeFile: string,
  * refused, or the project is mobile (`note`).
  */
 export function nothingDerived(r: DeriveResult): boolean {
-  return !r.note && !r.refused?.length && r.scenarios.length === 0 && !r.skipped.some((s) => s.approved);
+  return !r.note && !r.refused?.length && !r.duplicateIds?.length && r.scenarios.length === 0 && !r.skipped.some((s) => s.approved);
 }
 
 export async function deriveFreeFeature(i: DeriveInput): Promise<DeriveResult> {
@@ -93,7 +101,11 @@ export async function deriveFreeFeature(i: DeriveInput): Promise<DeriveResult> {
   const result: DeriveResult = { file, written: false, scenarios: [], skipped: [] };
   if ((readCapabilities(i.projectRoot).platform ?? '').toLowerCase() === 'mobile') return { ...result, note: MOBILE_NOT_SUPPORTED };
   const grep = i.grep ? new RegExp(i.grep, 'i') : null;
-  const found = collectRuns(i.projectRoot, (id, t) => (grep ? grep.test(`${id} ${t.title} ${t.file}`) : belongsToUnit(t.file, unitBase.toLowerCase())), 0);
+  const found = collectRuns(i.projectRoot, (id, t) => (grep ? grep.test(`${id} ${t.title} ${t.file}`) : belongsToUnit(t.file, unitBase.toLowerCase())), null);
+  const claimed = idsClaimedByTwoTests(i.projectRoot, found.runs);
+  if (claimed.size) {
+    return { ...result, duplicateIds: [...claimed].sort(([a], [b]) => a.localeCompare(b, 'en')).map(([id, c]) => ({ id, tests: c.tests, ...(c.staleRecords.length ? { staleRecords: c.staleRecords } : {}) })) };
+  }
   const byId = new Map<string, TraceRun[]>();
   for (const r of found.runs) byId.set(r.scenarioId, [...(byId.get(r.scenarioId) ?? []), r]);
   const admissible = (runs: TraceRun[]): TraceRun[] => runs.filter((r) => r.status === 'admissible' && r.trace)

package/src/contract/resolve-unit-trace-identities.ts

@@ -3,33 +3,56 @@
  * resolver (driver-ui — a real browser) about every target of the unit's admissible traces and
  * cache the answers (DOS-14.5). The verdict itself never calls a browser; it reads the cache, so
  * the CLI and the Claude Code guard keep building the same verdict from the same files.
+ *
+ * What it reports is split for QA (#966): a WARNING only when something needs attention — no
+ * resolver, a mobile project, a target the browser could not name (its steps stay opaque). "Every
+ * target was already known" and "N new targets identified" are information, in plain words.
  */
-import * as fs from 'fs';
 import { capabilityRegistry } from '../capabilities/registry';
 import { readCapabilities } from '../harness/capability';
 import { MOBILE_NOT_SUPPORTED } from './build-trace-conformance';
-import { lockPathFor } from './contracts-lock-file';
-import { contractFeatureFiles, loadContractScenarios } from './normalize-feature-steps';
+import { loadContractScenarios } from './normalize-feature-steps';
 import { collectScenarioEvidence } from './trace/collect-trace-evidence';
+import { readIdentityCache } from './trace/identity-cache';
+import { unitContract } from './trace/trace-freshness';
 import type { TraceIdentityResolver } from './trace/target-identity';
 import { resolveWithDriver } from './trace/trace-identity-resolution';
 
-const mtimeMs = (f: string): number => { try { return fs.statSync(f).mtimeMs; } catch { return 0; } };
+export interface TraceIdentityOutcome { warnings: string[]; info: string[] }
 
 /** The first registered capability that can resolve trace identities (UI: driver-ui), if any. */
 export function registeredTraceResolver(): TraceIdentityResolver | undefined {
   return capabilityRegistry.all().find((c) => typeof c.traceIdentity === 'function')?.traceIdentity;
 }
 
-export async function resolveUnitTraceIdentities(projectRoot: string, unit: { name: string; dir: string }, resolver = registeredTraceResolver()): Promise<string[]> {
+export async function traceIdentityOutcome(projectRoot: string, unit: { name: string; dir: string }, resolver = registeredTraceResolver()): Promise<TraceIdentityOutcome> {
+  const none: TraceIdentityOutcome = { warnings: [], info: [] };
   const traced = loadContractScenarios(unit.dir, unit.name).filter((s) => s.implementation !== 'compiled');
-  if (!traced.length) return [];
-  if ((readCapabilities(projectRoot).platform ?? '').toLowerCase() === 'mobile') return [MOBILE_NOT_SUPPORTED];
-  if (!resolver) return ['no trace identity resolver is registered (install @sungen/driver-ui) — every target identity stays low, so nothing can match'];
-  const notBefore = Math.max(mtimeMs(lockPathFor(unit.dir)), ...contractFeatureFiles(unit.dir, unit.name).map(mtimeMs));
-  const evidence = collectScenarioEvidence(projectRoot, new Set(traced.map((s) => s.id)), notBefore);
+  if (!traced.length) return none;
+  if ((readCapabilities(projectRoot).platform ?? '').toLowerCase() === 'mobile') return { warnings: [MOBILE_NOT_SUPPORTED], info: [] };
+  if (!resolver) return { warnings: ['no trace identity resolver is registered (install @sungen/driver-ui) — every target identity stays low, so nothing can match'], info: [] };
+  const evidence = collectScenarioEvidence(projectRoot, new Set(traced.map((s) => s.id)), unitContract(projectRoot, unit));
   const traces = [...evidence.runs.values()].flat().filter((r) => r.status === 'admissible' && r.trace).map((r) => r.trace!);
-  if (!traces.length) return [];
+  if (!traces.length) return none;
   const r = await resolveWithDriver(projectRoot, traces, resolver);
-  return [`trace identity: ${r.asked} target(s) resolved by ${r.resolver || 'the cache'}${r.blockedRequests ? `, ${r.blockedRequests} replay request(s) blocked` : ''}`];
+  const { cache } = readIdentityCache(projectRoot);
+  const total = r.keys.length;
+  const unnamed = r.keys.filter((k) => cache.entries.get(k)?.identityConfidence !== 'high').length;
+  const blocked = r.blockedRequests ? `; the replayed pages tried ${r.blockedRequests} request(s), all blocked` : '';
+  const known = total - r.asked;
+  const info = r.asked
+    ? `trace identity: ${r.asked} new target(s) identified in a real browser (${r.resolver})${known ? `, ${known} already known` : ''}${blocked}`
+    : `trace identity: all ${total} target(s) were already identified (identity cache) — nothing new to resolve`;
+  const warnings = unnamed
+    ? [`trace identity: ${unnamed} of ${total} target(s) could not be identified (no unique accessible name) — the steps on them stay opaque, for QA to review, until the test targets a unique, named element`]
+    : [];
+  return { warnings, info: [info] };
+}
+
+/**
+ * What `contract check --trace` adds to the verdict's warnings: only what needs attention (#966).
+ * The plain-words information is `traceIdentityOutcome(...).info`.
+ */
+export async function resolveUnitTraceIdentities(projectRoot: string, unit: { name: string; dir: string }, resolver = registeredTraceResolver()): Promise<string[]> {
+  return (await traceIdentityOutcome(projectRoot, unit, resolver)).warnings;
 }

package/src/contract/trace/collect-trace-evidence.ts

@@ -8,6 +8,9 @@
  *   refused        the trace exists but may not speak (swapped, stale, rejected zip…)
  *   unsupported    the trace's format version is unknown                       (exit ≠ 0)
  *
+ * Two recorded TESTS claiming one scenario id (#962) make its evidence ambiguous: neither speaks —
+ * `unproven`, both named (scenario-id-claims.ts) — instead of judging two tests' runs as one.
+ *
  * Only traces of the scenario ids asked for are opened, so a unit pays for its own tests only.
  */
 import * as fs from 'fs';
@@ -15,7 +18,9 @@ import * as path from 'path';
 import { isIdLike } from '../../harness/parse';
 import { clip, CONTROL_CHARS } from '../render-free-gherkin';
 import { FileRead, readInsideProject } from './read-file-once';
+import { idsClaimedByTwoTests, twoTestsClaim } from './scenario-id-claims';
 import { bindTrace } from './trace-binding';
+import type { UnitContract } from './trace-freshness';
 import { traceFromRead, ParsedTrace } from './trace-file-reader';
 import { traceZipLimits, TraceRejected } from './trace-zip-limits';
 import { finalAttempt, readPlaywrightReport, ReportResult, ReportTest, scenarioIdOfTest } from './select-final-attempt';
@@ -49,21 +54,33 @@ function notRead(name: string, r: Exclude<FileRead, { status: 'read' }>): string
 export const OVER_BUDGET = 'verdict budget exceeded; run `sungen contract check`';
 const NO_RECORD = "no sungen run record under test-results-free/ (or test-results/) — run the free tests with their own config: outputDir 'test-results-free', trace: 'on' and the sungen run-record reporter";
 
-/** Where a report's trace attachment is: the first candidate that exists (read later, opened once). */
-function attachmentPath(projectRoot: string, report: string, p: string): string | null {
-  for (const cand of path.isAbsolute(p) ? [p] : [path.resolve(projectRoot, p), path.resolve(path.dirname(report), p)]) {
-    if (fs.existsSync(cand)) return cand;
-  }
-  return null;
+/** `p` relative to `root` when it lies under it, else null. */
+function under(root: string, p: string): string | null {
+  const rel = path.relative(root, p);
+  return rel && !rel.startsWith('..') && !path.isAbsolute(rel) ? rel : null;
+}
+
+/**
+ * Where a report's trace attachment is: the first candidate that exists (read later, opened once, and
+ * only from inside the project). Playwright writes attachment paths ABSOLUTE, in the checkout that ran;
+ * after a clone or a move that checkout is elsewhere, so a path under the report's own config dir is
+ * first tried at the same place under this project (#967) — the run record's sha256 still binds the bytes.
+ */
+function attachmentPath(projectRoot: string, test: ReportTest, p: string): string | null {
+  const moved = path.isAbsolute(p) && test.configRoot && !under(path.resolve(projectRoot), p) ? under(test.configRoot, p) : null;
+  const candidates = path.isAbsolute(p)
+    ? [...(moved ? [path.resolve(projectRoot, moved)] : []), p]
+    : [path.resolve(projectRoot, p), path.resolve(path.dirname(test.report), p)];
+  return candidates.find((c) => fs.existsSync(c)) ?? null;
 }
 
-function judge(projectRoot: string, record: RunRecord, test: ReportTest, notBefore: number): TraceRun {
+function judge(projectRoot: string, record: RunRecord, test: ReportTest, contract: UnitContract | null): TraceRun {
   const scenarioId = scenarioIdOfTest(test.title, test.tags);
   const base = { scenarioId, test, record };
   const fin = finalAttempt(test);
   if (fin.admissibility !== 'admissible') return { ...base, result: fin.result, status: fin.admissibility, reason: fin.reason };
   const missing: TraceRun = { ...base, result: fin.result, status: 'unproven', reason: `no trace at ${fin.result!.tracePath} (the report points at a missing file)` };
-  const cand = attachmentPath(projectRoot, test.report, fin.result!.tracePath!);
+  const cand = attachmentPath(projectRoot, test, fin.result!.tracePath!);
   if (!cand) return missing;
   // Opened once, inside the project, and what was opened is what is parsed and hashed (#926).
   const limits = traceZipLimits();
@@ -77,17 +94,22 @@ function judge(projectRoot: string, record: RunRecord, test: ReportTest, notBefo
     const unsupported = e instanceof TraceRejected && e.code === 'trace.version-unsupported';
     return { ...base, result: fin.result, status: unsupported ? 'unsupported' : 'refused', reason: `trace refused: ${(e as Error).message}` };
   }
-  const bound = bindTrace({ projectRoot, test, result: fin.result!, record, trace, notBefore });
+  const bound = bindTrace({ projectRoot, test, result: fin.result!, record, trace, contract });
   if (bound.ok === false) return { ...base, result: fin.result, trace, status: 'refused', reason: `trace refused: ${bound.reason}` };
   return { ...base, result: fin.result, trace, status: 'admissible', specFile: bound.specFile };
 }
 
-/** Every judged run of the tests `want` accepts (derive: a unit's tests; check: by scenario id). */
+/**
+ * Every judged run of the tests `want` accepts (derive: a unit's tests; check: by scenario id). A trace
+ * older than `contract` — the unit's .feature files and lock, by content (#967) — is refused; derive,
+ * which writes the contract from the traces, passes null.
+ */
 export function collectRuns(
-  projectRoot: string, want: (id: string, test: ReportTest) => boolean, notBefore: number, deadline = Number.POSITIVE_INFINITY,
-): { runs: TraceRun[]; problems: string[]; inputs: string[]; records: number; seen: Array<{ id: string; title: string }> } {
+  projectRoot: string, want: (id: string, test: ReportTest) => boolean, contract: UnitContract | null, deadline = Number.POSITIVE_INFINITY,
+): { runs: TraceRun[]; problems: string[]; untrusted: string[]; inputs: string[]; records: number; seen: Array<{ id: string; title: string }> } {
   const runs: TraceRun[] = [];
   const problems: string[] = [];
+  const untrusted: string[] = [];
   const inputs: string[] = [];
   const seen: Array<{ id: string; title: string }> = [];
   const records = findRunRecords(projectRoot);
@@ -95,7 +117,11 @@ export function collectRuns(
     let record: RunRecord;
     const recordRead = readInsideProject(projectRoot, file, MAX_EVIDENCE_JSON_BYTES);
     if (recordRead.status !== 'read') { problems.push(notRead(path.basename(file), recordRead)); continue; }
-    try { record = readRunRecord(file, recordRead.bytes.toString('utf8')); } catch (e) { problems.push(`${path.basename(file)} is not trusted: ${(e as Error).message}`); continue; }
+    try { record = readRunRecord(file, recordRead.bytes.toString('utf8')); } catch (e) {
+      untrusted.push(`${path.basename(file)} is not trusted: ${(e as Error).message}`);
+      problems.push(untrusted[untrusted.length - 1]);
+      continue;
+    }
     if (!record.report) { problems.push(`${path.basename(file)} names no JSON report — add the json reporter to the free-test config`); continue; }
     const reportRead = readInsideProject(projectRoot, path.resolve(projectRoot, record.report), MAX_EVIDENCE_JSON_BYTES);
     if (reportRead.status !== 'read') { problems.push(`${path.basename(file)}: ${notRead(`the report ${path.basename(record.report)}`, reportRead)}`); continue; }
@@ -106,10 +132,10 @@ export function collectRuns(
       const id = scenarioIdOfTest(test.title, test.tags);
       seen.push({ id, title: test.title });
       if (!want(id, test)) continue;
-      runs.push(Date.now() > deadline ? { scenarioId: id, test, record, status: 'unproven', reason: OVER_BUDGET } : judge(projectRoot, record, test, notBefore));
+      runs.push(Date.now() > deadline ? { scenarioId: id, test, record, status: 'unproven', reason: OVER_BUDGET } : judge(projectRoot, record, test, contract));
     }
   }
-  return { runs, problems, inputs, records: records.length, seen };
+  return { runs, problems, untrusted, inputs, records: records.length, seen };
 }
 
 /** A title without its leading id, for comparing words only: `VP-X-001 Login works` → `login works`. */
@@ -135,12 +161,18 @@ function noTestFor(id: string, name: string | undefined, seen: Array<{ id: strin
 
 /** The runs of each scenario id; `names` (id → scenario name) lets a missing test be explained. */
 export function collectScenarioEvidence(
-  projectRoot: string, ids: ReadonlySet<string>, notBefore: number, deadline?: number, names?: ReadonlyMap<string, string>,
+  projectRoot: string, ids: ReadonlySet<string>, contract: UnitContract | null, deadline?: number, names?: ReadonlyMap<string, string>,
 ): ScenarioEvidence {
-  const found = collectRuns(projectRoot, (id) => ids.has(id), notBefore, deadline);
+  const found = collectRuns(projectRoot, (id) => ids.has(id), contract, deadline);
   const runs = new Map<string, TraceRun[]>([...ids].map((id) => [id, found.runs.filter((r) => r.scenarioId === id)]));
+  // Ambiguous evidence: no run of either test may speak for the id — never one picked arbitrarily.
+  for (const [id, claim] of idsClaimedByTwoTests(projectRoot, found.runs)) {
+    if (runs.has(id)) runs.set(id, [{ scenarioId: id, status: 'unproven', reason: twoTestsClaim(id, claim) }]);
+  }
   for (const [id, list] of runs) {
-    if (!list.length) list.push({ scenarioId: id, status: 'unproven', reason: found.records ? noTestFor(id, names?.get(id), found.seen) : NO_RECORD });
+    // A record that was not trusted may be why (a newer reporter, a hand edit): the finding says so.
+    const why = found.untrusted.length ? ` — ${found.untrusted.join('; ')}` : '';
+    if (!list.length) list.push({ scenarioId: id, status: 'unproven', reason: found.records ? `${noTestFor(id, names?.get(id), found.seen)}${why}` : NO_RECORD });
   }
   return { runs, problems: found.problems, inputs: found.inputs };
 }

package/src/contract/trace/scenario-id-claims.ts

@@ -0,0 +1,60 @@
+/**
+ * One scenario id, one test (#962): which ids more than one recorded TEST claims, said the same way
+ * by `contract derive` (it refuses) and `contract check` (the id is unproven). One test recorded
+ * again — another run or shard, a retry, a second Playwright project — is still one test: the same
+ * file and the same Playwright test id.
+ *
+ * Each claiming test names the run record(s) it came from. A test that only an older run's record
+ * under `test-results/` still mentions — while another claim comes from the free config's own
+ * `test-results-free/` — is most likely gone: that record is offered for deletion.
+ */
+import * as path from 'path';
+import { clip } from '../render-free-gherkin';
+import type { TraceRun } from './collect-trace-evidence';
+import { FREE_RUN_DIR } from './trace-run-record';
+
+export interface IdClaim {
+  /** `file:line "title" (run record <path>)` per claiming test, sorted. */
+  tests: string[];
+  /** Project-relative records under test-results/ that are a claim's only source, next to a test-results-free/ claim. */
+  staleRecords: string[];
+}
+
+const posix = (p: string): string => p.split(path.sep).join('/');
+/** A run's project-relative test file: the run record's (what the binding checks), else the report's. */
+const testFileOf = (r: TraceRun): string => r.record?.attempts.find((a) => a.testId === r.test?.testId)?.file ?? r.test?.file ?? '?';
+const label = (r: TraceRun, records: string[]): string =>
+  `${clip(testFileOf(r), 200)}:${r.test?.line ?? 0} "${clip(r.test?.title ?? '')}" (run record ${records.map((f) => clip(f, 200)).join(', ')})`;
+
+export function idsClaimedByTwoTests(projectRoot: string, runs: readonly TraceRun[]): Map<string, IdClaim> {
+  const byId = new Map<string, Map<string, { run: TraceRun; records: Set<string> }>>();
+  for (const r of runs) {
+    if (!r.test) continue;
+    const tests = byId.get(r.scenarioId) ?? new Map<string, { run: TraceRun; records: Set<string> }>();
+    const key = `${testFileOf(r)}\0${r.test.testId}`;
+    const entry = tests.get(key) ?? { run: r, records: new Set<string>() };
+    if (r.record?.file) entry.records.add(posix(path.relative(projectRoot, r.record.file)));
+    tests.set(key, entry);
+    byId.set(r.scenarioId, tests);
+  }
+  const claims = new Map<string, IdClaim>();
+  for (const [id, tests] of byId) {
+    if (tests.size < 2) continue;
+    const entries = [...tests.values()].map((t) => ({ ...t, records: [...t.records].sort() }));
+    const inFreeDir = entries.some((t) => t.records.some((f) => f.startsWith(`${FREE_RUN_DIR}/`)));
+    const legacyOnly = entries.filter((t) => t.records.length > 0 && t.records.every((f) => f.startsWith('test-results/')));
+    claims.set(id, {
+      tests: entries.map((t) => label(t.run, t.records)).sort(),
+      staleRecords: inFreeDir ? [...new Set(legacyOnly.flatMap((t) => t.records))].sort() : [],
+    });
+  }
+  return claims;
+}
+
+/** What to tell the user when several tests claim one id — check and derive say it the same way. */
+export function twoTestsClaim(id: string, claim: IdClaim): string {
+  const stale = claim.staleRecords.length
+    ? `; if that test is gone, delete ${claim.staleRecords.join(', ')} — an older run's record (free tests now record under ${FREE_RUN_DIR}/)`
+    : '';
+  return `${claim.tests.length} recorded tests claim ${id}: ${claim.tests.join(', ')} — give each test its own ID (its title's leading ID, or its @tag), then run them again with trace on${stale}`;
+}

package/src/contract/trace/select-final-attempt.ts

@@ -11,10 +11,15 @@
  * leading id, else the whole title — the same rule the contract uses for a scenario name.
  */
 import * as fs from 'fs';
+import * as path from 'path';
 import { isIdLike } from '../../harness/parse';
 
 export interface ReportResult { retry: number; status: string; startTime: string; duration: number; tracePath: string | null }
-export interface ReportTest { testId: string; title: string; file: string; line: number; tags: string[]; project: string; results: ReportResult[]; report: string }
+export interface ReportTest {
+  testId: string; title: string; file: string; line: number; tags: string[]; project: string; results: ReportResult[]; report: string;
+  /** The directory of the config that ran (`config.configFile`, absolute as Playwright writes it) — where absolute attachment paths start. */
+  configRoot?: string;
+}
 export type Admissibility = 'admissible' | 'inconclusive' | 'unproven';
 
 const isObj = (v: unknown): v is Record<string, unknown> => !!v && typeof v === 'object' && !Array.isArray(v);
@@ -38,6 +43,8 @@ export function readPlaywrightReport(file: string, text?: string): ReportTest[]
   try { doc = JSON.parse(text ?? fs.readFileSync(file, 'utf8')); } catch (e) { throw new Error(`the JSON report ${file} is not readable (${(e as Error).message.split('\n')[0]})`); }
   if (!isObj(doc) || !Array.isArray(doc.suites)) throw new Error(`${file} is not a Playwright JSON report (no suites)`);
   const out: ReportTest[] = [];
+  const configFile = isObj(doc.config) && typeof doc.config.configFile === 'string' && path.isAbsolute(doc.config.configFile) ? doc.config.configFile : null;
+  const configRoot = configFile ? { configRoot: path.dirname(configFile) } : {};
   for (const top of doc.suites) {
     for (const spec of specsOf(top)) {
       if (typeof spec.id !== 'string' || typeof spec.title !== 'string' || typeof spec.file !== 'string') continue;
@@ -46,7 +53,7 @@ export function readPlaywrightReport(file: string, text?: string): ReportTest[]
         const results = arr(t.results).map(resultOf).filter((r): r is ReportResult => !!r).sort((a, b) => a.retry - b.retry);
         out.push({
           testId: spec.id, title: spec.title, file: spec.file, line: Number(spec.line) || 0,
-          tags: arr(spec.tags).map(String), project: String(t.projectName ?? ''), results, report: file,
+          tags: arr(spec.tags).map(String), project: String(t.projectName ?? ''), results, report: file, ...configRoot,
         });
       }
     }

package/src/contract/trace/trace-binding.ts

@@ -8,12 +8,14 @@
  *   code          sha256 of the test file NOW equals the hash the record took at run start
  *   title         every library part says `<file>:<line> › … › <title>` of exactly this test
  *   clock         the trace started inside the attempt's window (±2 s)
- *   fresh         the trace is newer than the .feature and the lock it is asked to prove
+ *   fresh         the trace is not older than the .feature files and the lock it is asked to prove —
+ *                 judged by their content, not their file time (#967, trace-freshness.ts)
  */
 import { createHash } from 'crypto';
 import * as fs from 'fs';
 import * as path from 'path';
 import type { ParsedTrace } from './trace-file-reader';
+import { staleReason, UnitContract } from './trace-freshness';
 import type { RunRecord } from './trace-run-record';
 import type { ReportResult, ReportTest } from './select-final-attempt';
 
@@ -23,8 +25,8 @@ export interface BindingInput {
   result: ReportResult;
   record: RunRecord;
   trace: ParsedTrace;
-  /** Epoch ms: the newest mtime of the unit's .feature files and lock. */
-  notBefore: number;
+  /** The unit's contract as it is now; null when no contract is proven (derive reads traces to write one). */
+  contract: UnitContract | null;
 }
 export type Binding = { ok: true; specFile: string } | { ok: false; reason: string };
 
@@ -51,6 +53,7 @@ export function bindTrace(i: BindingInput): Binding {
   if (typeof wall !== 'number' || Number.isNaN(start) || wall < start - CLOCK_SLACK_MS || wall > start + i.result.duration + CLOCK_SLACK_MS) {
     return fail('the trace was not recorded during this attempt (clock window)');
   }
-  if (wall < i.notBefore) return fail('the trace is older than the .feature or the lock it should prove (stale) — re-run the test');
+  const stale = i.contract ? staleReason(i.contract, i.record) : null;
+  if (stale) return fail(stale);
   return { ok: true, specFile: attempt.file };
 }