fix(harness): close review boundary gaps

Filter Qoder home-session evidence per record while preserving explicit user-global analysis. Fail review-trigger on Git probe errors, reject empty report cwd values, and bound cloc reads before loading file content.

Completes the PR review follow-ups for #12, #15, #16, and #18 under docs/specs/2026-07-29-11-18-review-boundary-hardening.md. Validated with the 80-test focused boundary run, npm run check, the documentation link graph, syntax checks, and staged diff checks.

Author: phodal

docs/specs/2026-07-29-11-18-review-boundary-hardening.md

@@ -21,22 +21,28 @@ the product surface or changing successful-path report semantics.
   decisions.
 - AC-02 (#12): Workspace-scoped Qoder analysis excludes home-only sessions that
   have no verified relationship to the requested workspace across sessions,
-  events/show, facets, insights, file-reads, and usage-summary.
+  events/show, facets, insights, file-reads, and usage-summary. A matching
+  record cannot authorize foreign-cwd records from the same home session, and
+  cwd-less records require a workspace-linked session source instead of being
+  assigned to the requested workspace. An explicit global-capability pass can
+  retain home-only sessions only as `user-global` evidence.
 - AC-03 (#13): `report --no-sessions` executes no session probe and always uses
   the static `software-fluency` route even when local sessions exist.
 - AC-04 (#14): Blast-radius collection distinguishes an invalid/unavailable
   base ref from a real empty diff and returns an explicit fail-closed error.
-- AC-05 (#15): review-trigger argument and runtime failures exit non-zero while
-  successful findings retain their documented non-blocking result.
-- AC-06 (#16): `report --cwd` rejects missing and non-directory targets before
-  starting evidence collectors; valid-directory fallback behavior remains
-  available.
+- AC-05 (#15): review-trigger argument, Git worktree probes, and runtime
+  failures exit non-zero while successful findings retain their documented
+  non-blocking result.
+- AC-06 (#16): `report --cwd` rejects empty, missing, and non-directory targets
+  before starting evidence collectors; valid-directory fallback behavior
+  remains available.
 - AC-07 (#17): findings repair never lowers `Critical` or arbitrary unknown
   severity to `Medium`; unsupported values fail closed or use an explicit
   conservative mapping.
 - AC-08 (#18): Git-backed cloc never follows a tracked path to a target outside
-  the repository or reads a non-regular file; skipped results remain bounded
-  and do not reveal the external target.
+  the repository, reads a non-regular file, or reads a regular file beyond the
+  configured size boundary; skipped results remain bounded and do not reveal
+  the external target.
 - AC-09: Focused tests, the full Node test suite, package verification, syntax
   checks, and review-readiness checks pass on Linux-compatible local tooling;
   cross-platform path behavior remains covered by portable fixtures.
@@ -56,15 +62,16 @@ the product surface or changing successful-path report semantics.
 1. Add failing regression tests for each issue before changing implementation.
 2. Normalize Secret Guard tool events once, then scan only the content fields
    owned by matched write tools.
-3. Apply one workspace-ownership predicate to Qoder home-session discovery and
-   hydration, keeping explicit global behavior separate.
-4. Make quickstart privacy and cwd validation explicit at its CLI boundary.
+3. Apply workspace ownership at both Qoder home-session discovery and per-event
+   hydration, keeping explicit `user-global` behavior separate.
+4. Make quickstart privacy and empty/missing cwd validation explicit at its CLI
+   boundary.
 5. Replace Git diff ambiguity with a structured failure from blast-radius
    collection.
-6. Separate review-trigger execution failure from successful non-blocking
-   findings.
-7. Make severity repair conservative and make cloc file reads type- and
-   containment-aware.
+6. Separate review-trigger argument, Git-probe, and execution failures from
+   successful non-blocking findings.
+7. Make severity repair conservative and make cloc file reads type-, size-,
+   and containment-aware.
 8. Run focused tests per module, then the complete repository checks.
 9. Perform independent code-review and architecture lanes, address all
    Critical/High findings and any architectural Block, then run Review
@@ -85,26 +92,31 @@ Decision rationale:
   `node --test test/agent-guardrails-secret-scan.test.mjs`
 - AC-02:
   `node --test test/session-analysis.test.mjs test/session-usage-summary.test.mjs`
+  including mixed-cwd, cwd-less, and explicit user-global home-session cases
 - AC-03 and AC-06:
   `node --test test/harness-quickstart.test.mjs test/better-harness-cli.test.mjs`
 - AC-04:
   `node --test test/blast-radius.test.mjs`
 - AC-05:
-  `node --test test/review-trigger.test.mjs`
+  `node --test test/review-trigger.test.mjs`, including a non-Git directory
 - AC-07:
   `node --test test/harness-findings-repair.test.mjs test/harness-report-render-cli.test.mjs`
 - AC-08:
-  `node --test test/cloc.test.mjs`
+  `node --test test/cloc.test.mjs`, including an oversized regular file
 - AC-09:
   `npm test`
   `npm run pack:verify`
   `node --test test/doc-link-graph.test.mjs`
 
 Review evidence:
 
-- `npm run check` passed with 852 tests and package verification.
-- The final blocker-focused run passed 68 tests across Secret Guard,
-  review-trigger, blast-radius, and cloc; syntax and diff checks also passed.
+- Review follow-up (2026-07-29): mixed-cwd and cwd-less home-session hydration,
+  explicit user-global analysis, failed Git worktree probes, empty `--cwd=`,
+  and bounded cloc reads are covered by regressions and resolved before merge.
+- `npm run check` passed with the full Node suite and package verification.
+- The review follow-up focused run passed 80 tests across Qoder session
+  analysis, session usage summary, review-trigger, quickstart, and cloc;
+  syntax and diff checks also passed.
 - Code-reviewer recommendation: `APPROVE` after both reported High findings
   were fixed and re-reviewed.
 - Architect status: non-blocking `WATCH`; the previous fail-open `BLOCK` was

scripts/cloc/analyze.mjs

@@ -178,6 +178,7 @@ export async function analyzeCloc(options = {}) {
   const workerCount = chooseWorkerCount(options.workers, fileList.files.length);
   const countOptions = {
     markdownCode: Boolean(options.markdownCode),
+    maxFileBytes: options.maxFileBytes,
   };
   const includeFiles = options.includeFiles !== false;
   if (!includeFiles) {

scripts/cloc/count-file.mjs

@@ -4,7 +4,7 @@ import {
   fstatSync,
   lstatSync,
   openSync,
-  readFileSync,
+  readSync,
   realpathSync,
 } from "node:fs";
 import path from "node:path";
@@ -36,6 +36,33 @@ const LOCK_FILE_NAMES = new Set([
   "poetry.lock",
   "yarn.lock",
 ]);
+const DEFAULT_MAX_FILE_BYTES = 16 * 1024 * 1024;
+const READ_CHUNK_BYTES = 64 * 1024;
+
+function maxFileBytes(options = {}) {
+  const configured = Number(options.maxFileBytes);
+  return Number.isSafeInteger(configured) && configured > 0
+    ? configured
+    : DEFAULT_MAX_FILE_BYTES;
+}
+
+function readBoundedFile(descriptor, limit) {
+  const chunks = [];
+  let total = 0;
+  while (total <= limit) {
+    const chunk = Buffer.allocUnsafe(Math.min(READ_CHUNK_BYTES, limit - total + 1));
+    const bytesRead = readSync(descriptor, chunk, 0, chunk.length, null);
+    if (bytesRead === 0) {
+      return Buffer.concat(chunks, total);
+    }
+    total += bytesRead;
+    if (total > limit) {
+      return null;
+    }
+    chunks.push(chunk.subarray(0, bytesRead));
+  }
+  return null;
+}
 
 function emptyTotals() {
   return {
@@ -267,6 +294,7 @@ export function countKnownFileBuffer(buffer, filePath, options = {}) {
 
 export function countFile(repoRoot, filePath, options = {}) {
   const normalized = toPosix(filePath);
+  const fileSizeLimit = maxFileBytes(options);
   if (!isCountablePath(normalized)) {
     return { path: normalized, skipped: true, reason: "unsupported" };
   }
@@ -286,6 +314,9 @@ export function countFile(repoRoot, filePath, options = {}) {
   if (!stat.isFile()) {
     return { path: normalized, skipped: true, reason: "non-regular" };
   }
+  if (stat.size > fileSizeLimit) {
+    return { path: normalized, skipped: true, reason: "too-large" };
+  }
 
   try {
     const realRoot = realpathSync(root);
@@ -302,10 +333,17 @@ export function countFile(repoRoot, filePath, options = {}) {
   try {
     const noFollow = fsConstants.O_NOFOLLOW ?? 0;
     descriptor = openSync(absolutePath, fsConstants.O_RDONLY | noFollow);
-    if (!fstatSync(descriptor).isFile()) {
+    const openedStat = fstatSync(descriptor);
+    if (!openedStat.isFile()) {
       return { path: normalized, skipped: true, reason: "non-regular" };
     }
-    buffer = readFileSync(descriptor);
+    if (openedStat.size > fileSizeLimit) {
+      return { path: normalized, skipped: true, reason: "too-large" };
+    }
+    buffer = readBoundedFile(descriptor, fileSizeLimit);
+    if (buffer === null) {
+      return { path: normalized, skipped: true, reason: "too-large" };
+    }
   } catch {
     return { path: normalized, skipped: true, reason: "unreadable" };
   } finally {

scripts/harness-quickstart/cli.mjs

@@ -140,6 +140,20 @@ function cwdValidationError(cwd) {
   return null;
 }
 
+function explicitCwdValidationError(options) {
+  if (!Object.prototype.hasOwnProperty.call(options, "cwd")) {
+    return null;
+  }
+  if (typeof options.cwd === "string" && options.cwd.trim()) {
+    return null;
+  }
+  return {
+    code: "INVALID_CWD",
+    message: "Repository cwd requires a non-empty directory value.",
+    hint: "Pass --cwd with an existing repository directory.",
+  };
+}
+
 function errorPayload(error) {
   return {
     ok: false,
@@ -281,6 +295,11 @@ export function main(argv = process.argv.slice(2)) {
     return 0;
   }
   const options = parseArgs(argv);
+  const optionError = explicitCwdValidationError(options);
+  if (optionError) {
+    renderError(optionError, Boolean(options.json));
+    return 1;
+  }
   const cwd = options.cwd ? path.resolve(String(options.cwd)) : process.cwd();
   const validationError = cwdValidationError(cwd);
   if (validationError) {

scripts/review-trigger/cli.mjs

@@ -168,8 +168,11 @@ function hasLocalChanges(cwd) {
     stdio: ["ignore", "pipe", "ignore"],
     timeout: 10_000,
   });
-  if (result.status !== 0) {
-    return false;
+  if (result.error || result.status !== 0) {
+    throw new ReviewTriggerCliError(
+      "runtime-failure",
+      "review-trigger could not inspect the Git worktree",
+    );
   }
   return result.stdout.trim().length > 0;
 }

scripts/session-analysis/platforms/qoder.mjs

@@ -663,15 +663,6 @@ function sessionHasWorkspaceEvidence(session) {
     .some((ref) => ref.kind !== "home-session" && ref.planningScope !== "user-global");
 }
 
-function sessionHasGlobalEvidence(session) {
-  return (session?.sourceRefMap ? [...session.sourceRefMap.values()] : [])
-    .some((ref) => ref.kind !== "home-session" && ref.planningScope === "user-global");
-}
-
-function homeSessionPlanningScope(session) {
-  return sessionHasWorkspaceEvidence(session) ? "workspace" : "user-global";
-}
-
 function sourceKey(ref) {
   return `${ref.kind}:${ref.path}`;
 }
@@ -1202,16 +1193,16 @@ export class QoderSessionAnalyzer extends SessionAnalyzer {
       const sessionId = probe.sessionId ?? fallbackId;
       const existingSession = sessions.get(sessionId);
       const verifiedWorkspaceSession = sessionHasWorkspaceEvidence(existingSession);
-      const verifiedGlobalSession = scope.includeGlobalCapabilities && sessionHasGlobalEvidence(existingSession);
-      if (!probe.workspaceMatched && !verifiedWorkspaceSession && !verifiedGlobalSession) {
+      const planningScope = probe.workspaceMatched || verifiedWorkspaceSession ? "workspace" : "user-global";
+      if (planningScope === "user-global" && !scope.includeGlobalCapabilities) {
         continue;
       }
       addSessionRef(sessions, sessionId, scope.workspace, {
         kind: "home-session",
         path: filePath,
         eventType: "home-session",
         timestamp: probe.timestamp,
-        planningScope: probe.workspaceMatched ? "workspace" : homeSessionPlanningScope(existingSession),
+        planningScope,
       });
     }
   }
@@ -1457,19 +1448,31 @@ export class QoderSessionAnalyzer extends SessionAnalyzer {
     const includeCommandText = parseBooleanFlag(options["include-command-text"] ?? options.includeCommandText ?? false);
     const includeUserText = parseBooleanFlag(options["include-user-text"] ?? options.includeUserText ?? false);
     const refs = session.sourceRefs ?? [];
+    const workspaceLinked = refs.some(
+      (ref) => ref.kind !== "home-session" && ref.planningScope !== "user-global",
+    );
 
     for (const ref of refs) {
       if (ref.kind === "audit-jsonl") {
         await this.readAuditEvents(session.sessionId, scope, ref, events, { includeContent, includeCommandText, includeUserText });
       } else if (ref.kind === "project-state") {
         await this.readStateEvent(session.sessionId, ref, events, { includeContent, includeCommandText, includeUserText });
       } else if (ref.path.endsWith(JSONL_EXT)) {
-        await this.readJsonlEvents(session.sessionId, ref, events, { includeContent, includeCommandText, includeUserText });
+        await this.readJsonlEvents(
+          session.sessionId,
+          scope,
+          ref,
+          events,
+          { includeContent, includeCommandText, includeUserText },
+          { workspaceLinked },
+        );
       }
     }
 
     return events
-      .map((event) => event.cwd ? event : { ...event, cwd: scope.workspace })
+      .map((event) => event.cwd || event.planningScope === "user-global"
+        ? event
+        : { ...event, cwd: scope.workspace })
       .filter((event) => withinTimeRange(event.timestamp, scope))
       .sort((a, b) => {
         const left = timestampMillis(a.timestamp) ?? 0;
@@ -1481,13 +1484,25 @@ export class QoderSessionAnalyzer extends SessionAnalyzer {
       });
   }
 
-  async readJsonlEvents(sessionId, ref, events, options) {
+  async readJsonlEvents(sessionId, scope, ref, events, options, { workspaceLinked = false } = {}) {
     await forEachJsonLine(ref.path, (raw, line) => {
       const sourceRef = { ...ref, line, sessionId };
       const rawSessionId = inferSessionId(raw, sourceRef);
       if (rawSessionId && rawSessionId !== sessionId && ref.kind !== "logs-session") {
         return;
       }
+      if (ref.kind === "home-session") {
+        if (ref.planningScope === "user-global") {
+          if (!scope.includeGlobalCapabilities) {
+            return;
+          }
+        } else {
+          const recordCwd = inferCwd(raw);
+          if (recordCwd ? !isWorkspaceMatch(recordCwd, scope.workspace) : !workspaceLinked) {
+            return;
+          }
+        }
+      }
       events.push(this.normalizeEvent(raw, sourceRef, options));
     });
   }

test/cloc.test.mjs

@@ -174,6 +174,27 @@ test("unsupported and lock files are skipped before reading content", async () =
   }
 });
 
+test("cloc skips regular files beyond the configured read boundary", async () => {
+  const repo = await mkdtemp(path.join(os.tmpdir(), "better-harness-cloc-size-boundary-"));
+
+  try {
+    await writeFixtureFile(repo, "src/large.js", "const value = 'this file exceeds the test boundary';\n");
+
+    assert.deepEqual(countFile(repo, "src/large.js", { maxFileBytes: 16 }), {
+      path: "src/large.js",
+      skipped: true,
+      reason: "too-large",
+    });
+    assert.equal(countFile(repo, "src/large.js", { maxFileBytes: 1_024 }).skipped, false);
+
+    const report = await analyzeCloc({ cwd: repo, useGit: false, workers: 1, maxFileBytes: 16 });
+    assert.equal(report.fileList.counted, 0);
+    assert.deepEqual(report.skippedFiles, [{ path: "src/large.js", reason: "too-large" }]);
+  } finally {
+    await removeFixtureTree(repo);
+  }
+});
+
 test("git-backed cloc skips tracked symlinks without leaking external targets", async (t) => {
   const repo = await makeRepo({
     "src/app.js": "const a = 1;\n",

test/harness-quickstart.test.mjs

@@ -141,6 +141,21 @@ test("Better Harness report rejects a missing cwd before collecting evidence", a
   }
 });
 
+test("Better Harness report rejects an explicitly empty cwd", () => {
+  const machine = runBetterHarness(["report", "--cwd=", "--json"]);
+  assert.equal(machine.status, 1);
+  assert.equal(machine.stderr, "");
+  const payload = JSON.parse(machine.stdout);
+  assert.equal(payload.ok, false);
+  assert.equal(payload.error.code, "INVALID_CWD");
+  assert.match(payload.error.message, /requires a non-empty directory value/u);
+
+  const human = runBetterHarness(["report", "--cwd="]);
+  assert.equal(human.status, 1);
+  assert.equal(human.stdout, "");
+  assert.match(human.stderr, /requires a non-empty directory value/u);
+});
+
 test("Better Harness report rejects a regular-file cwd before collecting evidence", async () => {
   const root = await mkdtemp(path.join(os.tmpdir(), "better-harness-quickstart-file-cwd-"));
   const filePath = path.join(root, "not-a-directory");