@mrciphersmith/keryx 0.2.106 → 0.2.108

package/README.md

@@ -325,7 +325,12 @@ Grouped by what you are trying to do, not by internal module layout.
   trends.
 - **review** — managed review packages, standalone under `.metaproject/reviews/`
   or inside the flow package when attached to a flow, so review findings become
-  durable project artifacts.
+  durable project artifacts. A finding points at the code it **quotes**: the
+  line is derived by locating that quote at the commit the round records, not
+  taken on the reviewer's word, and a quote that cannot be found is marked
+  unlocatable rather than carrying a number nobody checked. Each round also
+  states its price — estimated before dispatch, recorded after, and divided by
+  the findings that survived it.
 
 **Operate agents**
 

package/dist/cli.js

@@ -48579,7 +48579,7 @@ import path47 from "path";
 // package.json
 var package_default = {
   name: "@mrciphersmith/keryx",
-  version: "0.2.106",
+  version: "0.2.108",
   description: "Version-controlled project context for AI coding agents: code graph, architecture wiki, project memory, relevant tests, quality signals, and task flows.",
   private: false,
   publishConfig: {
@@ -62741,7 +62741,7 @@ ${learningSourceLessons(selection).map((lesson) => `- ${lesson}
 
 // src/review/managed.ts
 init_validator();
-import { mkdir as mkdir53, readFile as readFile86, readdir as readdir28, rm as rm11 } from "fs/promises";
+import { mkdir as mkdir53, readFile as readFile86, readdir as readdir28, realpath as realpath8, rm as rm11, stat as stat16 } from "fs/promises";
 import path153 from "path";
 init_fs();
 init_store2();
@@ -64692,6 +64692,163 @@ function renderFilterStatsLine(stats) {
   return `filter_stats: total=${show(stats.total)} prefilter=${show(stats.dropped_prefilter)} low_confidence=${show(stats.dropped_low_confidence)} refuted=${show(stats.dropped_refuted)} scope_b=${show(stats.dropped_scope_b)} findings_cap=${show(stats.dropped_findings_cap)} dismissed_by_round=${show(stats.dismissed_by_round)} retained=${show(stats.retained)}`;
 }
 
+// src/review/locate.ts
+var MAX_QUOTE_LINES = 200;
+var MAX_LOCATE_FILE_LINES = 50000;
+var MAX_LOCATE_FILE_BYTES = 4000000;
+function quoteLines(quote) {
+  const lines = quote.replace(/\r\n/g, `
+`).split(`
+`);
+  while (lines.length > 0 && lines[0].trim() === "") {
+    lines.shift();
+  }
+  while (lines.length > 0 && lines[lines.length - 1].trim() === "") {
+    lines.pop();
+  }
+  if (lines.length === 0) {
+    return [];
+  }
+  const indents = lines.filter((line) => line.trim() !== "").map((line) => (line.match(/^[ \t]*/)?.[0] ?? "").length);
+  const common = indents.length === 0 ? 0 : Math.min(...indents);
+  return lines.map((line) => line.slice(common));
+}
+function normalise(line) {
+  return line.trim().replace(/\s+/g, " ");
+}
+function deindent(lines) {
+  const indents = lines.filter((line) => line.trim() !== "").map((line) => (line.match(/^[ \t]*/)?.[0] ?? "").length);
+  const common = indents.length === 0 ? 0 : Math.min(...indents);
+  return lines.map((line) => line.slice(common));
+}
+var MAX_HITS = 2;
+function findRuns(haystack, needle, shape) {
+  const hits = [];
+  if (needle.length === 0 || needle.length > haystack.length) {
+    return hits;
+  }
+  for (let start = 0;start + needle.length <= haystack.length; start += 1) {
+    const window = shape(haystack.slice(start, start + needle.length));
+    if (window.every((line, offset) => line === needle[offset])) {
+      hits.push(start + 1);
+      if (hits.length >= MAX_HITS) {
+        return hits;
+      }
+    }
+  }
+  return hits;
+}
+function ambiguity(hits, pass) {
+  return {
+    state: "unlocatable",
+    reason: `the quote matches at least ${hits.length} places${pass}(lines ${hits.join(", ")}, and the scan stopped there); an anchor chosen among them would be a guess`
+  };
+}
+function locateQuote(fileText, quote) {
+  const needle = quoteLines(quote);
+  if (needle.length === 0) {
+    return { state: "unlocatable", reason: "the quote is empty" };
+  }
+  if (needle.length > MAX_QUOTE_LINES) {
+    return {
+      state: "unlocatable",
+      reason: `the quote is ${needle.length} lines, past the ${MAX_QUOTE_LINES}-line bound; quote the few lines the finding is about`
+    };
+  }
+  const haystack = fileText.replace(/\r\n/g, `
+`).split(`
+`);
+  if (haystack.length > MAX_LOCATE_FILE_LINES) {
+    return {
+      state: "unlocatable",
+      reason: `the file is ${haystack.length} lines, past the ${MAX_LOCATE_FILE_LINES}-line bound for locating`
+    };
+  }
+  const exact = findRuns(haystack, deindent(needle).map((line) => line.trimEnd()), (window) => deindent(window).map((line) => line.trimEnd()));
+  if (exact.length === 1) {
+    return { state: "derived", method: "exact", line: exact[0] };
+  }
+  if (exact.length > 1) {
+    return ambiguity(exact, " in the file ");
+  }
+  const loose = findRuns(haystack, needle.map(normalise), (window) => window.map(normalise));
+  if (loose.length === 1) {
+    return { state: "derived", method: "whitespace-normalised", line: loose[0] };
+  }
+  if (loose.length > 1) {
+    return ambiguity(loose, " once whitespace is normalised ");
+  }
+  return { state: "unlocatable", reason: "the quote does not appear in the file" };
+}
+async function locateFinding(finding, readFile) {
+  const quote = typeof finding.quote === "string" ? finding.quote : "";
+  if (quote.trim() === "") {
+    return;
+  }
+  const reported = typeof finding.line === "number" ? finding.line : null;
+  const file = typeof finding.file === "string" ? finding.file : "";
+  if (file === "") {
+    return { state: "unlocatable", reason: "the finding quotes code but names no file", reported_line: reported };
+  }
+  const text = await readFile(file);
+  if (text === null) {
+    return { state: "unlocatable", reason: `no such file at this round's head: ${file}`, reported_line: reported };
+  }
+  const outcome = locateQuote(text, quote);
+  return outcome.state === "derived" ? { state: "derived", method: outcome.method, line: outcome.line, reported_line: reported } : { state: "unlocatable", reason: outcome.reason, reported_line: reported };
+}
+
+// src/review/repair.ts
+var REPAIRABLE = new Set(["id", "problem"]);
+function isBlank(value) {
+  return typeof value !== "string" || value.trim() === "";
+}
+function mintId(index, taken) {
+  let n = index + 1;
+  let candidate = `F-${String(n).padStart(3, "0")}`;
+  while (taken.has(candidate)) {
+    n += 1;
+    candidate = `F-${String(n).padStart(3, "0")}`;
+  }
+  return candidate;
+}
+function acceptRepair(before, after) {
+  if (before.length !== after.length) {
+    throw new Error(`Refusing a repair that changed the number of findings: ${before.length} in, ${after.length} out. A repair may fill fields in; it may never add or drop a finding.`);
+  }
+  for (const [index, finding] of after.entries()) {
+    const had = before[index];
+    const keys = new Set(Object.keys(finding));
+    const illegal = [...keys].filter((key) => !had.has(key) && !REPAIRABLE.has(key));
+    if (illegal.length > 0) {
+      throw new Error(`Refusing a repair that wrote ${illegal.join(", ")} onto finding ${index + 1}: only ${[...REPAIRABLE].join(" and ")} may be filled in. Everything else is a claim the reviewer has to make.`);
+    }
+    const removed = [...had].filter((key) => !keys.has(key));
+    if (removed.length > 0) {
+      throw new Error(`Refusing a repair that removed ${removed.join(", ")} from finding ${index + 1}: a repair may fill a field in; it may never clear one.`);
+    }
+  }
+}
+function repairMechanicalOmissions(findings) {
+  const before = findings.map((finding) => new Set(Object.keys(finding)));
+  const taken = new Set(findings.map((finding) => finding.id).filter((id) => !isBlank(id)));
+  const repairs = [];
+  for (const [index, finding] of findings.entries()) {
+    if (isBlank(finding.id)) {
+      const minted = mintId(index, taken);
+      taken.add(minted);
+      finding.id = minted;
+      repairs.push({ finding: minted, field: "id", source: `position ${index + 1} in the report` });
+    }
+    if (isBlank(finding.problem) && !isBlank(finding["title"])) {
+      finding.problem = String(finding["title"]).trim();
+      repairs.push({ finding: finding.id, field: "problem", source: "the finding's own title" });
+    }
+  }
+  acceptRepair(before, findings);
+  return repairs;
+}
+
 // src/review/managed.ts
 init_review_notes();
 init_types3();
@@ -64761,6 +64918,9 @@ async function createManagedReviewPackage(input) {
     source: input.findings,
     reviewers
   });
+  const repairs = repairMechanicalOmissions(reported);
+  const head = await resolveTargetHead(input);
+  await anchorFindings(reported, input, head);
   assignGlobalIds(reported, reviewId);
   const merged = mergeVerifications(reported, input.verifications ?? [], {
     mode: input.verificationMode ?? DEFAULT_VERIFICATION_MODE
@@ -64796,7 +64956,6 @@ async function createManagedReviewPackage(input) {
     externalRetained: scoped.external.length,
     ...input.refuted === undefined ? {} : { roundDismissed: roundDismissed.length }
   });
-  const head = await resolveTargetHead(input);
   const manifest = buildManifest2({
     input,
     target: targetWithHead(input.target, head),
@@ -64805,7 +64964,8 @@ async function createManagedReviewPackage(input) {
     flowMatch,
     coverage,
     at,
-    filterStats
+    filterStats,
+    repairs
   });
   const validation = await validateManagedReviewManifest(input.cwd, manifest);
   if (!validation.valid) {
@@ -65067,6 +65227,8 @@ function buildManifest2(args) {
     },
     coverage: args.coverage,
     filter_stats: args.filterStats,
+    ...args.repairs.length === 0 ? {} : { repairs: args.repairs },
+    ...args.input.cost === undefined ? {} : { cost: args.input.cost },
     ...crossFamily === undefined ? {} : { cross_family_review: crossFamily },
     createdAt: args.at,
     updatedAt: args.at
@@ -65132,6 +65294,80 @@ function triage(findings, args) {
     return triaged;
   });
 }
+async function anchorFindings(findings, input, head) {
+  const read = input.readTreeFile ?? (head === null ? readFromWorkingTree(input) : async (relative) => {
+    const contained = await containedRelativePath(input.cwd, relative);
+    return contained === null ? null : readFileAtCommit(input.cwd, head, contained);
+  });
+  for (const finding of findings) {
+    const locator = await locateFinding(finding, read);
+    if (locator === undefined) {
+      delete finding.locator;
+      continue;
+    }
+    if (locator.state === "derived") {
+      finding.line = locator.line;
+      finding.locator = {
+        state: "derived",
+        method: locator.method,
+        ...locator.reported_line === undefined ? {} : { reported_line: locator.reported_line }
+      };
+      continue;
+    }
+    finding.line = null;
+    finding.locator = {
+      state: "unlocatable",
+      reason: locator.reason,
+      ...locator.reported_line === undefined ? {} : { reported_line: locator.reported_line }
+    };
+  }
+}
+async function containedRelativePath(cwd, relative) {
+  const root = await realpath8(cwd).catch(() => path153.resolve(cwd));
+  const resolved = path153.resolve(root, relative);
+  const real = await realpath8(resolved).catch(() => null);
+  if (real === null || real !== root && !real.startsWith(`${root}${path153.sep}`)) {
+    return null;
+  }
+  return real;
+}
+async function readFileAtCommit(cwd, commit, absolute) {
+  const relative = path153.relative(await realpath8(cwd).catch(() => path153.resolve(cwd)), absolute);
+  try {
+    const proc = Bun.spawn(["git", "show", `${commit}:${relative}`], {
+      cwd,
+      stdout: "pipe",
+      stderr: "ignore",
+      stdin: "ignore"
+    });
+    const [stdout, exitCode] = await Promise.all([new Response(proc.stdout).text(), proc.exited]);
+    if (exitCode !== 0 || stdout.length > MAX_LOCATE_FILE_BYTES) {
+      return null;
+    }
+    return stdout;
+  } catch {
+    return null;
+  }
+}
+function readFromWorkingTree(input) {
+  return async (relative) => {
+    const root = await realpath8(input.cwd).catch(() => path153.resolve(input.cwd));
+    const resolved = path153.resolve(root, relative);
+    const real = await realpath8(resolved).catch(() => null);
+    if (real === null || real !== root && !real.startsWith(`${root}${path153.sep}`)) {
+      return null;
+    }
+    try {
+      const info = await stat16(real);
+      if (!info.isFile() || info.size > MAX_LOCATE_FILE_BYTES) {
+        return null;
+      }
+      return await readFile86(real, "utf8");
+    } catch {
+      return null;
+    }
+  };
+}
 function toContractFinding(finding) {
   const record = {
     id: finding.id,
@@ -65149,6 +65385,12 @@ function toContractFinding(finding) {
   if (finding.line !== undefined) {
     record.line = finding.line;
   }
+  if (finding.quote !== undefined) {
+    record.quote = finding.quote;
+  }
+  if (finding.locator !== undefined) {
+    record.locator = finding.locator;
+  }
   if (finding.symbol !== undefined) {
     record.symbol = finding.symbol;
   }
@@ -65801,6 +66043,73 @@ async function loadDocpackSchema(cwd) {
   return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? parsed : null;
 }
 
+// src/review/cost.ts
+function estimateTokens2(text) {
+  return Math.ceil(text.length / 4);
+}
+function grouped(value) {
+  return value.toLocaleString("en-US");
+}
+function renderScopeEstimate(scopedDiff, reviewers) {
+  const per = estimateTokens2(scopedDiff);
+  const lines = [
+    `### Estimated cost`,
+    "",
+    `- \u2248 ${grouped(per)} prompt tokens of scoped diff per reviewer (characters \xF7 4 \u2014 an estimate, not a measurement)`
+  ];
+  if (reviewers > 0) {
+    lines.push(`- \u2248 ${grouped(per * reviewers)} across ${reviewers} reviewer${reviewers === 1 ? "" : "s"}, before their own prompts, tools and any verifier wave`);
+  } else {
+    lines.push("- reviewer count not supplied, so the fan-out is not multiplied in \u2014 pass `--reviewers a,b` to see the round's total");
+  }
+  return lines.join(`
+`);
+}
+function costFrom(input) {
+  const cost = {};
+  if (typeof input.inputTokens === "number") {
+    cost.input_tokens = input.inputTokens;
+  }
+  if (typeof input.outputTokens === "number") {
+    cost.output_tokens = input.outputTokens;
+  }
+  if (typeof input.spentUsd === "number") {
+    cost.spent_usd = input.spentUsd;
+  }
+  return Object.keys(cost).length === 0 ? undefined : cost;
+}
+function renderCostPerFinding(cost, retained) {
+  if (cost === undefined) {
+    return [
+      "cost: not recorded",
+      "  Nothing reported what this round used. That is NOT zero: pass --tokens-in/--tokens-out",
+      "  or --spent at ingest so the price of a round is a number somebody can weigh."
+    ];
+  }
+  const tokens = cost.input_tokens === undefined && cost.output_tokens === undefined ? undefined : (cost.input_tokens ?? 0) + (cost.output_tokens ?? 0);
+  const lines = [];
+  if (tokens !== undefined) {
+    lines.push(`tokens: ${grouped(tokens)}`);
+  }
+  if (cost.spent_usd !== undefined) {
+    lines.push(`spent: ${cost.spent_usd} USD`);
+  }
+  lines.push(`retained findings: ${retained}`);
+  if (retained === 0) {
+    lines.push("  Nothing was retained, so there is no per-finding figure \u2014 only the bill.");
+    return lines;
+  }
+  if (tokens !== undefined) {
+    const per = tokens / retained;
+    lines.push(per > 0 && Math.round(per) === 0 ? "per retained finding: < 1 token" : `per retained finding: ${grouped(Math.round(per))} tokens`);
+  }
+  if (cost.spent_usd !== undefined) {
+    const per = cost.spent_usd / retained;
+    lines.push(per > 0 && Number(per.toFixed(4)) === 0 ? "per retained finding: < 0.0001 USD" : `per retained finding: ${per.toFixed(4)} USD`);
+  }
+  return lines;
+}
+
 // src/review/reviewers.ts
 init_project_skills();
 import { readFile as readFile87, readdir as readdir29 } from "fs/promises";
@@ -66977,6 +67286,8 @@ var CREATE_FLAGS = [
   "--max-findings",
   "--spent",
   "--spend-ceiling",
+  "--tokens-in",
+  "--tokens-out",
   "--parallel",
   "--outstanding"
 ];
@@ -67017,8 +67328,12 @@ var SCOPE_FLAGS = [
   "--base",
   "--json",
   "--scoped-diff",
-  "--append"
+  "--append",
+  "--reviewers"
 ];
+function reviewerList(args) {
+  return (optionValue(args, "--reviewers") ?? "").split(",").map((item) => item.trim()).filter(Boolean);
+}
 var FLOOR_FLAGS = ["--ref", "--base", "--diff", "--context", "--json", "--report-only"];
 var FLOOR_VALUE_FLAGS = ["--ref", "--base", "--diff", "--context"];
 function rejectValuelessOptions(args, valueFlags, usage) {
@@ -67196,7 +67511,12 @@ async function runCreate(mode, args) {
     maxFindingsPerReviewer: parseNonNegativeInteger(optionValue(args, "--max-findings"), "--max-findings"),
     spend: parseMoney(optionValue(args, "--spent"), "--spent"),
     spendCeiling: parseMoney(optionValue(args, "--spend-ceiling"), "--spend-ceiling"),
-    concurrency: parseConcurrency(args)
+    concurrency: parseConcurrency(args),
+    cost: costFrom({
+      inputTokens: parseNonNegativeInteger(optionValue(args, "--tokens-in"), "--tokens-in"),
+      outputTokens: parseNonNegativeInteger(optionValue(args, "--tokens-out"), "--tokens-out"),
+      spentUsd: parseMoney(optionValue(args, "--spent"), "--spent")
+    })
   };
   const result = await createManagedReviewPackage(input);
   console.log(`# managed review: ${result.reviewId}`);
@@ -67861,6 +68181,8 @@ async function runScope(args) {
     console.log(renderScopedDiff(scope));
   } else {
     console.log(renderReviewScopeMarkdown(scope));
+    console.log("");
+    console.log(renderScopeEstimate(renderScopedDiff(scope), reviewerList(args).length));
   }
   const append = optionValue(args, "--append");
   if (append !== undefined) {
@@ -68116,6 +68438,9 @@ async function runComplete3(args) {
   console.log(`# managed review complete: ${manifest.reviewId}`);
   console.log(`status: ${manifest.status}`);
   console.log(`dispositions recorded: ${dispositions.length}`);
+  for (const line of renderCostPerFinding(manifest.cost, manifest.filter_stats?.retained ?? 0)) {
+    console.log(line);
+  }
   for (const note of reviewNotes.written) {
     console.log(`review-note: ${note.finding} -> ${note.path} (attested by ${note.attestation})`);
   }
@@ -75053,7 +75378,7 @@ init_workspace_service();
 init_store2();
 init_fs();
 import { createHash as createHash35, randomUUID as randomUUID17 } from "crypto";
-import { appendFile as appendFile7, mkdir as mkdir58, open as open2, readFile as readFile94, rename as rename7, rm as rm12, stat as stat16, writeFile as writeFile50 } from "fs/promises";
+import { appendFile as appendFile7, mkdir as mkdir58, open as open2, readFile as readFile94, rename as rename7, rm as rm12, stat as stat17, writeFile as writeFile50 } from "fs/promises";
 import path172 from "path";
 
 // src/sac/policy-experiment.ts
@@ -75230,7 +75555,7 @@ var ledgerDigestChunkBytes = 64 * 1024;
 var isMissing = (error) => error instanceof Error && error.code === "ENOENT";
 var checkpointHash = (body) => createHash35("sha256").update(JSON.stringify(body), "utf8").digest("hex");
 async function ledgerByteLength(ledger) {
-  const value = await stat16(ledger, { bigint: true });
+  const value = await stat17(ledger, { bigint: true });
   if (value.size > BigInt(Number.MAX_SAFE_INTEGER))
     throw new Error("invalid access receipt ledger: ledger-too-large");
   return Number(value.size);
@@ -76654,7 +76979,7 @@ function buildToolRegistry() {
 init_fs();
 init_contained_read();
 import path175 from "path";
-import { lstat as lstat5, readdir as readdir34, realpath as realpath8, stat as stat17 } from "fs/promises";
+import { lstat as lstat5, readdir as readdir34, realpath as realpath9, stat as stat18 } from "fs/promises";
 var URI_PREFIX = "metaproject://";
 function mimeForPath(filePath) {
   if (filePath.endsWith(".json") || filePath.endsWith(".jsonl")) {
@@ -76682,10 +77007,10 @@ async function walkFiles(root, ownerRoot = root, ancestors = new Set) {
   const ownerInfo = await lstat5(ownerRoot).catch(() => null);
   if (!ownerInfo || !ownerInfo.isDirectory() || ownerInfo.isSymbolicLink())
     return [];
-  const ownerReal = await realpath8(ownerRoot).catch(() => null);
+  const ownerReal = await realpath9(ownerRoot).catch(() => null);
   if (!ownerReal)
     return [];
-  const canonical = await realpath8(root).catch(() => null);
+  const canonical = await realpath9(root).catch(() => null);
   if (!canonical || !isPathInside(ownerReal, canonical) || ancestors.has(canonical))
     return [];
   const nextAncestors = new Set(ancestors);
@@ -76699,8 +77024,8 @@ async function walkFiles(root, ownerRoot = root, ancestors = new Set) {
   }
   for (const entry of entries) {
     const full = path175.join(root, entry.name);
-    const info = await stat17(full).catch(() => null);
-    if (!info || !isPathInside(ownerReal, await realpath8(full).catch(() => "")))
+    const info = await stat18(full).catch(() => null);
+    if (!info || !isPathInside(ownerReal, await realpath9(full).catch(() => "")))
       continue;
     if (info.isDirectory()) {
       out.push(...await walkFiles(full, ownerRoot, nextAncestors));
@@ -76812,7 +77137,7 @@ async function readResource(cwd, roots, uri) {
   if (!resolved) {
     throw new Error(`Resource path is outside its root (rejected): ${uri}`);
   }
-  const info = await stat17(resolved.absolute).catch(() => null);
+  const info = await stat18(resolved.absolute).catch(() => null);
   if (!info || !info.isFile()) {
     throw new Error(`Resource not found: ${uri}`);
   }
@@ -80137,6 +80462,36 @@ var MAX_BACKGROUND_OUTPUT_BYTES = 2 * 1024 * 1024;
 var DEFAULT_INITIAL_BUFFER_MS = 500;
 var MAX_TRACKED_JOBS = 50;
 var TERMINATED_OUTPUT_TAIL_BYTES = 4000;
+var TASK_OUTPUT_HEAD_BYTES = 24000;
+var ENV_SHELL_IDLE_MS = "KERYX_SHELL_IDLE_MS";
+var ENV_SHELL_TIMEOUT_MS_FALLBACK = "KERYX_SHELL_TIMEOUT_MS";
+var DEFAULT_SHELL_IDLE_MS = 120000;
+var MIN_TASK_IDLE_TIMEOUT_MS = 1000;
+var MAX_TASK_IDLE_TIMEOUT_MS = 1800000;
+function parseEnvMs(raw) {
+  if (raw === undefined || raw.trim().length === 0)
+    return;
+  const n = Number.parseInt(raw.trim(), 10);
+  if (!Number.isFinite(n) || n < 0)
+    return Number.NaN;
+  return n;
+}
+function resolveShellIdleMs(env = process.env) {
+  const idle = parseEnvMs(env[ENV_SHELL_IDLE_MS]);
+  if (idle !== undefined) {
+    return Number.isNaN(idle) ? DEFAULT_SHELL_IDLE_MS : idle;
+  }
+  const legacy = parseEnvMs(env[ENV_SHELL_TIMEOUT_MS_FALLBACK]);
+  if (legacy !== undefined) {
+    return Number.isNaN(legacy) ? DEFAULT_SHELL_IDLE_MS : legacy;
+  }
+  return DEFAULT_SHELL_IDLE_MS;
+}
+function clampTaskIdleTimeoutMs(ms) {
+  if (!Number.isFinite(ms))
+    return MIN_TASK_IDLE_TIMEOUT_MS;
+  return Math.min(MAX_TASK_IDLE_TIMEOUT_MS, Math.max(MIN_TASK_IDLE_TIMEOUT_MS, Math.trunc(ms)));
+}
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -80214,11 +80569,34 @@ function createJobRegistry(options) {
   const initialBufferMs = options?.initialBufferMs ?? DEFAULT_INITIAL_BUFFER_MS;
   const onEvent = options?.onEvent;
   const maxTrackedJobs = options?.maxTrackedJobs ?? MAX_TRACKED_JOBS;
+  const idleMs = options?.idleMs ?? resolveShellIdleMs();
   let nextId = 0;
   const jobs = new Map;
   function runningJobs() {
     return [...jobs.values()].filter((j) => j.info.status === "running");
   }
+  function backgroundRunningJobs() {
+    return runningJobs().filter((j) => j.info.phase === "background");
+  }
+  function clearIdleTimer(job) {
+    if (job.idleTimer === undefined)
+      return;
+    clearTimeout(job.idleTimer);
+    job.idleTimer = undefined;
+  }
+  function armIdleTimer(job) {
+    clearIdleTimer(job);
+    if (job.info.status !== "running")
+      return;
+    const timeout = job.info.idleTimeoutMs;
+    if (timeout <= 0)
+      return;
+    const timer = setTimeout(() => {
+      requestKill(job, "idle");
+    }, timeout);
+    timer.unref?.();
+    job.idleTimer = timer;
+  }
   function evictOldestTerminatedIfOverCap() {
     if (jobs.size <= maxTrackedJobs)
       return;
@@ -80239,20 +80617,32 @@ function createJobRegistry(options) {
   }
   function appendOutput(job, chunk, stream) {
     job.outputBuffer += chunk;
+    if (job.outputHead.length < TASK_OUTPUT_HEAD_BYTES) {
+      job.outputHead = (job.outputHead + chunk).slice(0, TASK_OUTPUT_HEAD_BYTES);
+      job.info.outputHead = job.outputHead;
+    }
+    armIdleTimer(job);
     onEvent?.({ type: "output", jobId: job.info.jobId, chunk, stream });
     if (job.outputBuffer.length > MAX_BACKGROUND_OUTPUT_BYTES) {
       const dropped = job.outputBuffer.length - MAX_BACKGROUND_OUTPUT_BYTES;
       job.outputBuffer = job.outputBuffer.slice(dropped);
       job.readCursor = Math.max(0, job.readCursor - dropped);
-      if (!job.killRequested) {
-        job.killRequested = true;
-        terminateJob(job, killGraceMs);
-      }
+      requestKill(job, "output-cap");
     }
   }
+  function requestKill(job, reason) {
+    if (job.info.status !== "running")
+      return Promise.resolve();
+    if (job.killRequested)
+      return job.exitedPromise;
+    job.killRequested = true;
+    job.pendingKillReason = reason;
+    return terminateJob(job, killGraceMs);
+  }
   async function terminateJob(job, graceMs) {
     if (job.info.status !== "running")
       return;
+    clearIdleTimer(job);
     job.killRequested = true;
     job.handle.kill("SIGTERM");
     const exited = await Promise.race([job.exitedPromise.then(() => true), sleep(graceMs).then(() => false)]);
@@ -80261,14 +80651,17 @@ function createJobRegistry(options) {
     }
   }
   return {
-    async start(command) {
-      const running = runningJobs();
-      if (running.length >= maxConcurrent) {
-        const names = running.map((j) => j.info.command).join(", ");
-        return {
-          ok: false,
-          error: `background job limit reached (${maxConcurrent} running: ${names}); wait for one to finish or kill it with shell_job_kill first`
-        };
+    async start(command, opts) {
+      const phase = opts?.phase ?? "background";
+      if (phase === "background") {
+        const running = backgroundRunningJobs();
+        if (running.length >= maxConcurrent) {
+          const names = running.map((j) => j.info.command).join(", ");
+          return {
+            ok: false,
+            error: `background task limit reached (${maxConcurrent} running: ${names}); wait for one to finish or kill it with shell_job_kill first`
+          };
+        }
       }
       let handle;
       try {
@@ -80279,7 +80672,7 @@ function createJobRegistry(options) {
           error: `command failed to start: ${cause instanceof Error ? cause.message : String(cause)}`
         };
       }
-      const jobId = `job-${++nextId}-${handle.pid}`;
+      const jobId = `task-${++nextId}-${handle.pid}`;
       let resolveExited;
       const exitedPromise = new Promise((resolve) => {
         resolveExited = resolve;
@@ -80290,26 +80683,46 @@ function createJobRegistry(options) {
           pid: handle.pid,
           command,
           status: "running",
+          phase,
+          idleTimeoutMs: opts?.idleTimeoutMs ?? idleMs,
           startedAt: nowIso3()
         },
         handle,
         outputBuffer: "",
+        outputHead: "",
         readCursor: 0,
         exited: false,
         killRequested: false,
+        phaseEmitted: false,
         resolveExited,
         exitedPromise
       };
+      if (opts?.description !== undefined)
+        job.info.description = opts.description;
       jobs.set(jobId, job);
       evictOldestTerminatedIfOverCap();
-      onEvent?.({ type: "start", jobId, pid: handle.pid, command, startedAt: job.info.startedAt });
+      onEvent?.({
+        type: "start",
+        jobId,
+        pid: handle.pid,
+        command,
+        startedAt: job.info.startedAt,
+        ...opts?.description !== undefined ? { description: opts.description } : {}
+      });
+      if (phase === "background") {
+        job.phaseEmitted = true;
+        onEvent?.({ type: "phase", jobId, phase: "background" });
+      }
       handle.onOutput((chunk, stream) => appendOutput(job, chunk, stream));
       handle.onExit((info) => {
         if (job.exited)
           return;
         job.exited = true;
-        if (job.info.status === "running") {
-          job.info.status = job.killRequested ? "killed" : "exited";
+        clearIdleTimer(job);
+        const terminal = job.killRequested ? "killed" : info.exitCode === 0 ? "completed" : "failed";
+        job.info.status = terminal;
+        if (job.killRequested) {
+          job.info.killReason = job.pendingKillReason ?? "model";
         }
         job.info.exitCode = info.exitCode;
         job.info.endedAt = nowIso3();
@@ -80317,13 +80730,15 @@ function createJobRegistry(options) {
         onEvent?.({
           type: "exit",
           jobId,
-          status: job.info.status,
+          status: terminal,
+          ...job.info.killReason !== undefined ? { killReason: job.info.killReason } : {},
           exitCode: info.exitCode,
           endedAt: job.info.endedAt
         });
         shrinkTerminatedOutput(job);
       });
-      if (initialBufferMs > 0) {
+      armIdleTimer(job);
+      if (phase === "background" && initialBufferMs > 0) {
         await sleep(initialBufferMs);
       }
       const output = job.outputBuffer.slice(job.readCursor);
@@ -80345,7 +80760,41 @@ function createJobRegistry(options) {
       job.readCursor = job.outputBuffer.length;
       return { ok: true, output };
     },
-    async kill(jobId) {
+    async waitForExit(jobId, ms) {
+      const job = jobs.get(jobId);
+      if (job === undefined)
+        return "unknown";
+      if (job.exited || job.info.status !== "running")
+        return "exited";
+      let timer;
+      const timedOut = await Promise.race([
+        job.exitedPromise.then(() => false),
+        new Promise((resolve) => {
+          timer = setTimeout(() => resolve(true), ms);
+          timer.unref?.();
+        })
+      ]);
+      if (timer !== undefined)
+        clearTimeout(timer);
+      return timedOut ? "timeout" : "exited";
+    },
+    promote(jobId) {
+      const job = jobs.get(jobId);
+      if (job === undefined) {
+        return { ok: false, error: `unknown job_id: ${jobId}` };
+      }
+      job.info.phase = "background";
+      if (!job.phaseEmitted) {
+        job.phaseEmitted = true;
+        onEvent?.({ type: "phase", jobId, phase: "background" });
+      }
+      const others = backgroundRunningJobs().filter((j) => j.info.jobId !== jobId);
+      if (job.info.status === "running" && others.length >= maxConcurrent) {
+        return { ok: true, overCap: others.map((j) => j.info.command).join(", ") };
+      }
+      return { ok: true };
+    },
+    async kill(jobId, reason = "model") {
       const job = jobs.get(jobId);
       if (job === undefined) {
         return { ok: false, error: `unknown job_id: ${jobId}` };
@@ -80353,11 +80802,11 @@ function createJobRegistry(options) {
       if (job.info.status !== "running") {
         return { ok: false, error: `job ${jobId} is not running (status: ${job.info.status})` };
       }
-      await terminateJob(job, killGraceMs);
+      await requestKill(job, reason);
       return { ok: true };
     },
     async sweepAll() {
-      await Promise.all(runningJobs().map((job) => terminateJob(job, killGraceMs)));
+      await Promise.all(runningJobs().map((job) => requestKill(job, "session-exit")));
     }
   };
 }
@@ -80365,7 +80814,7 @@ function shellJobOutputTool(registry) {
   return {
     definition: {
       name: "shell_job_output",
-      description: "Return output produced by a background job (started via shell_exec with background:true) SINCE the " + "previous call for that job_id \u2014 never the full transcript again. Input: { job_id: string }. Poll this " + "instead of re-running shell_exec to check on a long-running job.",
+      description: "Return output produced by a shell task SINCE the previous call for that id \u2014 never the full transcript " + "again. Input: { job_id: string } \u2014 pass the task_id shell_exec returned for a command that outlived its " + "yield (or a background:true job). Poll this instead of re-running shell_exec to check on a long command.",
       inputSchema: {
         type: "object",
         properties: { job_id: { type: "string" } },
@@ -80391,7 +80840,7 @@ function shellJobKillTool(registry) {
   return {
     definition: {
       name: "shell_job_kill",
-      description: "Kill a background job started via shell_exec with background:true (its entire process group, including " + "any descendant it backgrounded). Input: { job_id: string }. Only jobs in this session's own registry can " + "be targeted.",
+      description: "Stop a running shell task \u2014 its entire process group, including any descendant it backgrounded. Input: " + "{ job_id: string } \u2014 the task_id shell_exec returned for a command still running after its yield (or a " + "background:true job). Only tasks in this session's own registry can be targeted.",
       inputSchema: {
         type: "object",
         properties: { job_id: { type: "string" } },
@@ -80596,6 +81045,37 @@ function resolveShellTimeoutMs(env = process.env) {
   }
   return n;
 }
+var DEFAULT_SHELL_YIELD_MS = 1e4;
+var ENV_SHELL_YIELD_MS = "KERYX_SHELL_YIELD_MS";
+function resolveShellYieldMs(env = process.env) {
+  const raw = env[ENV_SHELL_YIELD_MS];
+  if (raw === undefined || raw.trim().length === 0) {
+    return DEFAULT_SHELL_YIELD_MS;
+  }
+  const n = Number.parseInt(raw.trim(), 10);
+  if (!Number.isFinite(n) || n < 0) {
+    return DEFAULT_SHELL_YIELD_MS;
+  }
+  return n;
+}
+function boundOutput2(text) {
+  return text.length > MAX_OUTPUT_BYTES3 ? `${text.slice(0, MAX_OUTPUT_BYTES3)}
+\u2026(truncated)` : text;
+}
+function taskHandleResult(args) {
+  return {
+    output: JSON.stringify({
+      task_id: args.taskId,
+      job_id: args.taskId,
+      pid: args.pid,
+      status: "running",
+      output: boundOutput2(args.output),
+      notice: args.notice,
+      ...args.overCap !== undefined ? { over_cap: args.overCap } : {}
+    }),
+    isError: false
+  };
+}
 function makeCommandRunner(root) {
   return async (command) => {
     let netClose = async () => {};
@@ -80689,14 +81169,19 @@ ${notice}` : notice,
     }
   };
 }
-function shellExecTool(root, run = makeCommandRunner(root), jobRegistry) {
+function shellExecTool(root, run = makeCommandRunner(root), jobRegistry, options) {
   return {
     definition: {
       name: "shell_exec",
-      description: "Run a shell command in the project root (e.g. `git status`, `bun test`). Requires the user's approval " + "before it runs. Input: { command: string, background?: boolean }. Combined stdout+stderr is CAPPED at " + "20,000 bytes from the start of output \u2014 do not use sed/grep/cat/awk here to locate code (they can " + "silently truncate before reaching what you need, and repeating the command returns the same truncated " + "head); use search_code or graph_symbol instead, which are built for that and stay within the cap. Set " + "background:true for a long-running command (a dev server, a watch build) \u2014 it returns immediately with " + "{job_id, pid} instead of blocking; poll shell_job_output(job_id) for new output and shell_job_kill" + "(job_id) to stop it.",
+      description: "Run a shell command in the project root (e.g. `git status`, `bun test`). Requires the user's approval " + "before it runs. Input: { command: string, background?: boolean, description?: string, " + "idle_timeout_ms?: integer }. EVERY command returns within a bounded wait \u2014 a short one returns its " + "output directly, and one still running when the wait elapses keeps running as a task: you get " + "{task_id, pid, status, output} instead of its final output, and read the rest with " + "shell_job_output(task_id) and stop it with shell_job_kill(task_id). So a slow command never freezes " + "the session and never needs to be guessed at in advance. background:true only SKIPS the wait (use it " + "for a dev server or a watch build you know you will not read inline); it changes nothing else. " + "description is a short label for the task list. idle_timeout_ms is for a command that is deliberately " + "SILENT for a long time (a sleep, a slow poll) \u2014 a task that produces no output for its idle timeout " + "is killed, so raise it rather than lose the command. Combined stdout+stderr is CAPPED at 20,000 bytes " + "from the start of output \u2014 do not use sed/grep/cat/awk here to locate code (they can silently " + "truncate before reaching what you need, and repeating the command returns the same truncated head); " + "use search_code or graph_symbol instead, which are built for that and stay within the cap.",
       inputSchema: {
         type: "object",
-        properties: { command: { type: "string" }, background: { type: "boolean" } },
+        properties: {
+          command: { type: "string" },
+          background: { type: "boolean" },
+          description: { type: "string" },
+          idle_timeout_ms: { type: "integer" }
+        },
         required: ["command"],
         additionalProperties: false
       },
@@ -80707,20 +81192,66 @@ function shellExecTool(root, run = makeCommandRunner(root), jobRegistry) {
       if (command.length === 0) {
         return { output: "shell_exec requires a non-empty 'command'", isError: true };
       }
-      if (input.background === true) {
-        if (jobRegistry === undefined) {
+      const background = input.background === true;
+      if (jobRegistry === undefined) {
+        if (background) {
           return { output: "shell_exec: background jobs are not available in this session", isError: true };
         }
-        const started = await jobRegistry.start(command);
-        if (!started.ok) {
-          return { output: started.error, isError: true };
+        return run(command);
+      }
+      const startOpts = { phase: background ? "background" : "foreground" };
+      if (typeof input.description === "string" && input.description.length > 0) {
+        startOpts.description = input.description;
+      }
+      if (typeof input.idle_timeout_ms === "number") {
+        startOpts.idleTimeoutMs = clampTaskIdleTimeoutMs(input.idle_timeout_ms);
+      }
+      const started = await jobRegistry.start(command, startOpts);
+      if (!started.ok) {
+        return { output: started.error, isError: true };
+      }
+      const taskId = started.jobId;
+      if (background) {
+        return taskHandleResult({
+          taskId,
+          pid: started.pid,
+          output: started.output,
+          notice: `running as a background task; read new output with shell_job_output("${taskId}") and stop it with shell_job_kill("${taskId}")`
+        });
+      }
+      const yieldMs = options?.yieldMs ?? resolveShellYieldMs();
+      const outcome = await jobRegistry.waitForExit(taskId, yieldMs);
+      let collected = started.output;
+      const pending = jobRegistry.readOutput(taskId);
+      if (pending.ok)
+        collected += pending.output;
+      if (outcome === "timeout") {
+        const promoted = jobRegistry.promote(taskId);
+        if (!promoted.ok) {
+          return { output: promoted.error, isError: true };
         }
-        return {
-          output: JSON.stringify({ job_id: started.jobId, pid: started.pid, output: started.output }),
-          isError: false
-        };
+        return taskHandleResult({
+          taskId,
+          pid: started.pid,
+          output: collected,
+          notice: `still running after ${yieldMs}ms, so it is now a background task; read new output with shell_job_output("${taskId}") and stop it with shell_job_kill("${taskId}")`,
+          ...promoted.overCap !== undefined ? { overCap: promoted.overCap } : {}
+        });
       }
-      return run(command);
+      const info = jobRegistry.get(taskId);
+      if (outcome === "unknown" || info === undefined) {
+        const so_far = boundOutput2(collected.trim());
+        const lost = `shell_exec: task ${taskId} is no longer tracked, so its exit status is unknown`;
+        return { output: so_far.length > 0 ? `${so_far}
+${lost}` : lost, isError: true };
+      }
+      const exitCode = info.exitCode ?? 0;
+      const bounded = boundOutput2((info.outputHead ?? collected).trim());
+      const body = bounded.length > 0 ? bounded : `(no output; exit ${exitCode})`;
+      const idleKilled = info.status === "killed" && info.killReason === "idle";
+      const output = idleKilled ? `${body}
+shell_exec: no output for ${info.idleTimeoutMs}ms, so the command was killed (raise it for this command with idle_timeout_ms, or change the default with ${ENV_SHELL_IDLE_MS})` : body;
+      return { output, isError: info.status !== "completed" };
     }
   };
 }
@@ -86652,7 +87183,7 @@ init_store3();
 init_proposal_lifecycle();
 init_workspace_service();
 import { randomUUID as randomUUID27 } from "crypto";
-import { readdir as readdir36, stat as stat18 } from "fs/promises";
+import { readdir as readdir36, stat as stat19 } from "fs/promises";
 import path190 from "path";
 
 // src/sac/lifecycle-flag.ts
@@ -86912,7 +87443,7 @@ async function collectReceiptTargets(cwd, owner) {
 async function attributeToSession(absolutePath, sessionsNewestFirst) {
   let mtimeMs;
   try {
-    mtimeMs = (await stat18(absolutePath)).mtimeMs;
+    mtimeMs = (await stat19(absolutePath)).mtimeMs;
   } catch {
     return;
   }
@@ -94130,9 +94661,14 @@ function openExternalInspector(otui, chrome, options) {
 var MAX_BACKGROUND_JOB_OUTPUT_CHARS = 20000;
 var STATUS_GLYPH4 = {
   running: "\u25D0",
-  exited: "\u25CF",
+  completed: "\u25CF",
+  failed: "\u25B2",
   killed: "\u2717"
 };
+function appendBounded(output, chunk) {
+  const combined = output + chunk;
+  return combined.length > MAX_BACKGROUND_JOB_OUTPUT_CHARS ? combined.slice(-MAX_BACKGROUND_JOB_OUTPUT_CHARS) : combined;
+}
 function clip7(s, max) {
   if (max <= 0) {
     return "";
@@ -94161,6 +94697,9 @@ function formatJobMeta(entry, now = Date.now()) {
     ["Ended", entry.endedAt ?? "\u2014"],
     ["Exit code", entry.exitCode !== undefined ? String(entry.exitCode) : "\u2014"]
   ];
+  if (entry.killReason !== undefined) {
+    rows.push(["Kill reason", entry.killReason]);
+  }
   const width = rows.reduce((max, [label]) => Math.max(max, label.length), 0);
   return rows.map(([label, value]) => `${label.padEnd(width)}  ${value}`).join(`
 `);
@@ -94171,36 +94710,64 @@ function formatJobOutput(entry) {
 
 class BackgroundJobStore {
   jobs = new Map;
+  pending = new Map;
   listeners = new Set;
   apply(event) {
-    if (event.type === "start") {
-      this.jobs.set(event.jobId, {
-        jobId: event.jobId,
-        command: event.command,
-        pid: event.pid,
-        status: "running",
-        startedAt: event.startedAt,
-        output: ""
-      });
-      this.emit({ id: event.jobId, kind: "start" });
-      return;
-    }
-    const current = this.jobs.get(event.jobId);
-    if (current === undefined) {
-      return;
-    }
-    if (event.type === "output") {
-      const combined = current.output + event.chunk;
-      current.output = combined.length > MAX_BACKGROUND_JOB_OUTPUT_CHARS ? combined.slice(-MAX_BACKGROUND_JOB_OUTPUT_CHARS) : combined;
-      this.emit({ id: event.jobId, kind: "output" });
-      return;
-    }
-    current.status = event.status;
-    current.endedAt = event.endedAt;
-    if (event.exitCode !== undefined) {
-      current.exitCode = event.exitCode;
+    switch (event.type) {
+      case "start":
+        this.pending.set(event.jobId, {
+          jobId: event.jobId,
+          command: event.command,
+          pid: event.pid,
+          status: "running",
+          startedAt: event.startedAt,
+          output: ""
+        });
+        return;
+      case "phase": {
+        const entry = this.pending.get(event.jobId);
+        if (entry === undefined) {
+          return;
+        }
+        this.pending.delete(event.jobId);
+        this.jobs.set(event.jobId, entry);
+        this.emit({ id: event.jobId, kind: "start" });
+        return;
+      }
+      case "output": {
+        const hidden = this.pending.get(event.jobId);
+        if (hidden !== undefined) {
+          hidden.output = appendBounded(hidden.output, event.chunk);
+          return;
+        }
+        const current = this.jobs.get(event.jobId);
+        if (current === undefined) {
+          return;
+        }
+        current.output = appendBounded(current.output, event.chunk);
+        this.emit({ id: event.jobId, kind: "output" });
+        return;
+      }
+      case "exit": {
+        if (this.pending.delete(event.jobId)) {
+          return;
+        }
+        const current = this.jobs.get(event.jobId);
+        if (current === undefined) {
+          return;
+        }
+        current.status = event.status;
+        current.endedAt = event.endedAt;
+        if (event.exitCode !== undefined) {
+          current.exitCode = event.exitCode;
+        }
+        if (event.killReason !== undefined) {
+          current.killReason = event.killReason;
+        }
+        this.emit({ id: event.jobId, kind: "exit" });
+        return;
+      }
     }
-    this.emit({ id: event.jobId, kind: "exit" });
   }
   get(jobId) {
     return this.jobs.get(jobId);
@@ -94215,6 +94782,7 @@ class BackgroundJobStore {
     };
   }
   removeAll() {
+    this.pending.clear();
     if (this.jobs.size === 0) {
       return;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrciphersmith/keryx",
-  "version": "0.2.106",
+  "version": "0.2.108",
   "description": "Version-controlled project context for AI coding agents: code graph, architecture wiki, project memory, relevant tests, quality signals, and task flows.",
   "private": false,
   "publishConfig": {

package/src/gdskills/bundled/skills/review/review-layout/SKILL.md

@@ -227,7 +227,7 @@ Report done only once all of these hold:
 - The measurement was taken at the worst real case — the longest translation in
   the catalog, the narrowest supported host, the state where the sibling is
   absent — not at the convenient one.
-- Every finding names `file:line` on the component that renders the box.
+- Every finding names the `file` of the component that renders the box and `quote`s the code it is about; `line` is derived at ingest from that quote, never counted.
 - Every `blocker` and `major` carries `class_scope` with `sites` and an
   `enumeration_method` naming the search that derived the set of elements sharing
   the sizing shape.

package/src/gdskills/bundled/skills/review/review-orchestrator/SKILL.md

@@ -1350,10 +1350,10 @@ Each reviewer must return a `REVIEW_RESULT` object matching `.metaproject/skills
 
 Before consolidation, validate every reviewer result:
 - Required status: `DONE`, `DONE_WITH_CONCERNS`, `NEEDS_CONTEXT`, or `BLOCKED`.
-- Required finding fields: id, severity, file, line (nullable only for repo-wide findings), problem, impact, suggested_fix, evidence, confidence, reviewer.
+- Required finding fields: id, severity, file, `quote`, problem, impact, suggested_fix, evidence, confidence, reviewer. **`quote`, not `line`:** copy the code the finding is about verbatim out of `file` and do not count lines — `keryx review ingest` locates the quote at the round's head and derives `line` from where it matched, so a number reported here is overwritten. A model is poor at counting lines and good at repeating text it has just read; this asks only for the second. Quote enough to be unambiguous: a snippet appearing twice in the file is recorded `unlocatable` rather than anchored to the first hit. A finding about the round rather than a site carries neither.
 - Every blocker must include evidence and a concrete suggested fix.
 - Findings without evidence are downgraded to `info` or returned to the reviewer for clarification.
-- Duplicate findings are merged by `dedupe_key` or by `(file, line, problem)`.
+- Duplicate findings are merged by `dedupe_key` or by `(file, quote, problem)`.
 - `NEEDS_CONTEXT` triggers one targeted context refill. If still unresolved, keep it as an explicit open question, not as a blocker.
 - If a reviewer exceeds `max_findings`, keep blockers/majors first and summarize lower severity findings.
 

package/src/gdskills/bundled/skills/review/review-orchestrator/reviewer-finding.schema.json

@@ -74,12 +74,20 @@
             ]
           },
           "line": {
+            "description": "Do not count lines. Quote the code in `quote` instead and leave this null: `keryx review ingest` finds the quote in `file` and writes the line the match started on, overwriting anything reported here. A model is poor at counting lines and good at repeating text it has just read, and this asks it only for the second. Kept in the contract because a finding with nothing to quote — one about the round rather than a site — still has nowhere else to point.",
             "type": [
               "integer",
               "null"
             ],
             "minimum": 1
           },
+          "quote": {
+            "description": "The code this finding is about, copied verbatim out of `file`. A few lines is enough — it is matched against the file at the round's head, exactly first and then with whitespace collapsed. A quote that appears in more than one place is recorded as `unlocatable` rather than anchored to the first hit, so quote enough to be unambiguous.",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
           "problem": {
             "type": "string"
           },

package/src/gdskills/contracts/review-finding.schema.json

@@ -100,7 +100,40 @@
       "description": "Which repository `file` and `line` are in. Null, the default, means the repository under review. A cross-repo claim names the producer here and pins the ref it was read at in `evidence`; without this field a finding about another service's behaviour could not say where its evidence lived, so the rule that such a claim is `info` unless it has a `file:line` at a pinned ref could not be checked by anything but the reviewer's word. Declared in BOTH this schema and skills/review/review-orchestrator/reviewer-finding.schema.json: this one is additionalProperties:false, so a finding carrying `repo` is rejected here if only the reviewer-side schema knows about it."
     },
     "file": { "type": ["string", "null"] },
-    "line": { "type": ["integer", "null"], "minimum": 1 },
+    "line": {
+      "title": "Where the finding points — DERIVED when the finding quotes code",
+      "description": "Reported by the reviewer only when there is nothing to quote. When `quote` is present this field is OUTPUT: `review ingest` finds the quote in `file` at the round's head and writes the line the match started on, overwriting whatever the reviewer said and recording both in `locator`. The reason is the failure it replaces — nothing compared a reported line to anything, so a number that had drifted travelled into findings.json, into the report, and into the disposition recorded against it. On a fix round the file has moved under the finding by construction, which is when the reported number is least trustworthy and most acted upon.",
+      "type": ["integer", "null"],
+      "minimum": 1
+    },
+    "quote": {
+      "title": "The code this finding is about, copied verbatim out of `file`",
+      "description": "What replaces asking the model for a line number: a model is poor at counting lines and good at repeating text it has just read. The quote is matched against `file` at the round's head — exactly first, then with whitespace collapsed, then not at all. A quote that matches in more than one place is `unlocatable` rather than anchored to the first hit, because choosing among them would be a guess wearing a line number. Absent for a finding that is about the round rather than a site.",
+      "type": ["string", "null"]
+    },
+    "locator": {
+      "title": "How `line` was arrived at",
+      "description": "Present exactly when the finding carries a quote. `derived` means the quote was found and `line` is where; `unlocatable` means it was not, and then `line` is null rather than a number nobody checked. `reported_line` keeps what the reviewer said, so a round can measure how far the claims drifted from the code — which is the only way to know whether deriving them repaired anything or is insurance.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["state"],
+      "properties": {
+        "state": { "type": "string", "enum": ["derived", "unlocatable"] },
+        "method": { "type": "string", "enum": ["exact", "whitespace-normalised"] },
+        "reason": { "type": ["string", "null"] },
+        "reported_line": { "type": ["integer", "null"], "minimum": 1 }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "state": { "const": "derived" } }, "required": ["state"] },
+          "then": { "required": ["method"] }
+        },
+        {
+          "if": { "properties": { "state": { "const": "unlocatable" } }, "required": ["state"] },
+          "then": { "required": ["reason"] }
+        }
+      ]
+    },
     "symbol": { "type": ["string", "null"] },
     "problem": { "type": "string" },
     "impact": { "type": "string" },